Codex-Harness-Referenz

Diese Referenz behandelt die detaillierte Konfiguration für das mitgelieferte codex-Plugin. Für Einrichtung und Routing-Entscheidungen beginnen Sie mit Codex-Harness.

Plugin-Konfigurationsoberfläche

Alle Codex-Harness-Einstellungen befinden sich unter plugins.entries.codex.config.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: true,            timeoutMs: 2500,          },          appServer: {            mode: "guardian",          },        },      },    },  },}

Unterstützte Felder auf oberster Ebene:

App-Server-Transport

Standardmäßig startet OmeniaClaw die verwaltete Codex-Binärdatei, die mit dem mitgelieferten Plugin ausgeliefert wird:

codex app-server --listen stdio://

Dadurch bleibt die App-Server-Version an das mitgelieferte codex-Plugin gebunden, statt an eine separate Codex-CLI, die zufällig lokal installiert ist. Setzen Sie appServer.command nur, wenn Sie bewusst eine andere ausführbare Datei ausführen möchten.

Für einen bereits laufenden App-Server verwenden Sie WebSocket-Transport:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            transport: "websocket",            url: "ws://gateway-host:39175",            authToken: "${CODEX_APP_SERVER_TOKEN}",            requestTimeoutMs: 60000,          },        },      },    },  },}

Unterstützte appServer-Felder:

Das Plugin blockiert ältere oder nicht versionierte App-Server-Handshakes. Der Codex-App-Server muss die stabile Version 0.125.0 oder neuer melden.

Genehmigungs- und Sandbox-Modi

Lokale stdio-App-Server-Sitzungen verwenden standardmäßig den YOLO-Modus: approvalPolicy: "never", approvalsReviewer: "user" und sandbox: "danger-full-access". Diese vertrauenswürdige lokale Operator-Haltung ermöglicht es unbeaufsichtigten OmeniaClaw-Turns und Heartbeats, ohne native Genehmigungsaufforderungen fortzufahren, die niemand beantworten kann.

Wenn die lokale Systemanforderungsdatei von Codex implizite YOLO-Genehmigungs-, Prüfer- oder Sandbox-Werte untersagt, behandelt OmeniaClaw den impliziten Standard stattdessen als Guardian und wählt zulässige Guardian-Berechtigungen aus. Hostnamenabgleichende [[remote_sandbox_config]]-Einträge in derselben Anforderungsdatei werden bei der Entscheidung über den Sandbox-Standard berücksichtigt.

Setzen Sie appServer.mode: "guardian" für Guardian-geprüfte Codex-Genehmigungen:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            mode: "guardian",            serviceTier: "priority",          },        },      },    },  },}

Die Voreinstellung guardian wird zu approvalPolicy: "on-request", approvalsReviewer: "auto_review" und sandbox: "workspace-write" erweitert, wenn diese Werte zulässig sind. Einzelne Richtlinienfelder überschreiben mode. Der ältere Prüferwert guardian_subagent wird weiterhin als Kompatibilitätsalias akzeptiert, neue Konfigurationen sollten jedoch auto_review verwenden.

Authentifizierung und Umgebungsisolation

Die Authentifizierung wird in dieser Reihenfolge ausgewählt:

1. Ein explizites OmeniaClaw-Codex-Authentifizierungsprofil für den Agenten.
2. Das bestehende App-Server-Konto im Codex-Home dieses Agenten.
3. Nur für lokale stdio-App-Server-Starts: CODEX_API_KEY, dann OPENAI_API_KEY, wenn kein App-Server-Konto vorhanden ist und OpenAI-Authentifizierung weiterhin erforderlich ist.

Wenn OmeniaClaw ein ChatGPT-Abonnement-artiges Codex-Authentifizierungsprofil erkennt, entfernt es CODEX_API_KEY und OPENAI_API_KEY aus dem gestarteten Codex-Kindprozess. Dadurch bleiben API-Schlüssel auf Gateway-Ebene für Embeddings oder direkte OpenAI-Modelle verfügbar, ohne dass native Codex-App-Server-Turns versehentlich über die API abgerechnet werden.

Explizite Codex-API-Schlüsselprofile und lokaler stdio-Env-Key-Fallback verwenden App-Server-Login statt geerbter Kindprozessumgebung. WebSocket-App-Server-Verbindungen erhalten keinen Gateway-Env-API-Schlüssel-Fallback; verwenden Sie ein explizites Authentifizierungsprofil oder das eigene Konto des entfernten App-Servers.

Starts des stdio-App-Servers erben standardmäßig die Prozessumgebung von OmeniaClaw, aber OmeniaClaw besitzt die Codex-App-Server-Kontobrücke und setzt sowohl CODEX_HOME als auch HOME auf agentenspezifische Verzeichnisse unterhalb des OmeniaClaw-Status dieses Agenten. Codex' eigener Skill-Loader liest $CODEX_HOME/skills und $HOME/.agents/skills, daher sind beide Werte für lokale App-Server-Starts isoliert. Dadurch bleiben Codex-native Skills, Plugins, Konfiguration, Konten und Thread-Status auf den OmeniaClaw-Agenten beschränkt, statt aus dem persönlichen Codex-CLI-Home des Operators einzufließen.

OmeniaClaw-Plugins und OmeniaClaw-Skill-Snapshots laufen weiterhin über OmeniaClaws eigene Plugin-Registry und den Skill-Loader. Persönliche Codex-CLI-Assets tun dies nicht. Wenn Sie nützliche Codex-CLI-Skills oder Plugins haben, die Teil eines OmeniaClaw-Agenten werden sollen, inventarisieren Sie sie explizit:

OmeniaClaw migrate codex --dry-runOmeniaClaw migrate apply codex --yes

Wenn eine Bereitstellung zusätzliche Umgebungsisolation benötigt, fügen Sie diese Variablen zu appServer.clearEnv hinzu:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"],          },        },      },    },  },}

appServer.clearEnv wirkt sich nur auf den gestarteten Codex-App-Server-Kindprozess aus. CODEX_HOME und HOME bleiben für OmeniaClaws agentenspezifische Codex-Isolation bei lokalen Starts reserviert.

Dynamische Tools

Codex Dynamic Tools verwenden standardmäßig searchable-Loading. OmeniaClaw stellt keine dynamischen Tools bereit, die native Codex-Workspace-Operationen duplizieren:

• read
• write
• edit
• apply_patch
• exec
• process
• update_plan

Verbleibende OmeniaClaw-Integrationstools wie Messaging, Sessions, Medien, Cron, Browser, Nodes, Gateway, heartbeat_respond und web_search sind über die Codex-Toolsuche im Namespace OmeniaClaw verfügbar. Dadurch bleibt der anfängliche Modellkontext kleiner. sessions_yield und nur auf Message-Tools bezogene Quellenantworten bleiben direkt, weil dies Turn-Control-Verträge sind.

Setzen Sie codexDynamicToolsLoading: "direct" nur, wenn Sie eine Verbindung zu einem benutzerdefinierten Codex-App-Server herstellen, der verzögert geladene dynamische Tools nicht durchsuchen kann, oder wenn Sie die vollständige Tool-Payload debuggen.

Zeitüberschreitungen

Dynamische Tool-Aufrufe, die OmeniaClaw gehören, werden unabhängig von appServer.requestTimeoutMs begrenzt. Jede Codex-Anfrage item/tool/call verwendet die erste verfügbare Zeitüberschreitung in dieser Reihenfolge:

• Ein positives timeoutMs-Argument pro Aufruf.
• Für image_generate, agents.defaults.imageGenerationModel.timeoutMs.
• Für das Medienverständnis-Tool image, tools.media.image.timeoutSeconds, umgerechnet in Millisekunden, oder den Medienstandardwert von 60 Sekunden.
• Den Standardwert für dynamische Tools von 30 Sekunden.

Budgets für dynamische Tools sind auf 600000 ms begrenzt. Bei einer Zeitüberschreitung bricht OmeniaClaw, sofern unterstützt, das Tool-Signal ab und gibt eine fehlgeschlagene Antwort des dynamischen Tools an Codex zurück, damit der Turn fortgesetzt werden kann, statt die Session in processing zu belassen.

Nachdem OmeniaClaw auf eine turn-bezogene App-Server-Anfrage von Codex geantwortet hat, erwartet das Harness außerdem, dass Codex den nativen Turn mit turn/completed beendet. Wenn der App-Server nach dieser Antwort für appServer.turnCompletionIdleTimeoutMs still bleibt, unterbricht OmeniaClaw nach bestem Bemühen den Codex-Turn, zeichnet eine Diagnose-Zeitüberschreitung auf und gibt die OmeniaClaw-Session-Lane frei, damit nachfolgende Chatnachrichten nicht hinter einem veralteten nativen Turn in die Warteschlange geraten.

Jede nicht terminale Benachrichtigung für denselben Turn, einschließlich rawResponseItem/completed, deaktiviert diesen kurzen Watchdog, weil Codex nachgewiesen hat, dass der Turn noch aktiv ist. Der längere terminale Watchdog schützt weiterhin vor tatsächlich hängenden Turns. Zeitüberschreitungsdiagnosen enthalten die letzte App-Server-Benachrichtigungsmethode und, bei rohen Assistentenantwortelementen, den Elementtyp, die Rolle, die ID sowie eine begrenzte Vorschau des Assistententexts.

Modellerkennung

Standardmäßig fragt das Codex-Plugin den App-Server nach verfügbaren Modellen. Die Modellverfügbarkeit gehört dem Codex-App-Server, daher kann sich die Liste ändern, wenn OmeniaClaw die gebündelte Version von @openai/codex aktualisiert oder wenn eine Bereitstellung appServer.command auf eine andere Codex-Binärdatei verweist. Die Verfügbarkeit kann außerdem kontobezogen sein. Verwenden Sie /codex models auf einem laufenden Gateway, um den Live-Katalog für dieses Harness und dieses Konto zu sehen.

Wenn die Erkennung fehlschlägt oder eine Zeitüberschreitung auftritt, verwendet OmeniaClaw einen gebündelten Fallback-Katalog für:

• GPT-5.5
• GPT-5.4 mini
• GPT-5.2

Das aktuell gebündelte Harness ist @openai/codex 0.130.0. Eine model/list-Abfrage gegen diesen gebündelten App-Server ergab:

Ausgeblendete Modelle können vom App-Server-Katalog für interne oder spezialisierte Abläufe zurückgegeben werden, sie sind jedoch keine normalen Auswahlen im Modellselektor.

Passen Sie die Erkennung unter plugins.entries.codex.config.discovery an:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: true,            timeoutMs: 2500,          },        },      },    },  },}

Deaktivieren Sie die Erkennung, wenn der Start Codex nicht abfragen und nur den Fallback-Katalog verwenden soll:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: false,          },        },      },    },  },}

Workspace-Bootstrap-Dateien

Codex verarbeitet AGENTS.md selbst über die native Projekt-Dokumenterkennung. OmeniaClaw schreibt keine synthetischen Codex-Projekt-Dokumentdateien und hängt nicht von Codex-Fallback-Dateinamen für Persona-Dateien ab, weil Codex-Fallbacks nur gelten, wenn AGENTS.md fehlt.

Für Workspace-Parität in OmeniaClaw löst das Codex-Harness die anderen Bootstrap-Dateien auf, darunter SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md und MEMORY.md, sofern vorhanden, und leitet sie über Codex-Developer-Anweisungen bei thread/start und thread/resume weiter. Dadurch bleiben Workspace-Persona- und Profilkontext auf der nativen verhaltensprägenden Codex-Lane sichtbar, ohne AGENTS.md zu duplizieren.

Umgebungsüberschreibungen

Umgebungsüberschreibungen bleiben für lokale Tests verfügbar:

• OmeniaClaw_CODEX_APP_SERVER_BIN
• OmeniaClaw_CODEX_APP_SERVER_ARGS
• OmeniaClaw_CODEX_APP_SERVER_MODE=yolo|guardian
• OmeniaClaw_CODEX_APP_SERVER_APPROVAL_POLICY
• OmeniaClaw_CODEX_APP_SERVER_SANDBOX

OmeniaClaw_CODEX_APP_SERVER_BIN umgeht die verwaltete Binärdatei, wenn appServer.command nicht gesetzt ist.

OmeniaClaw_CODEX_APP_SERVER_GUARDIAN=1 wurde entfernt. Verwenden Sie stattdessen plugins.entries.codex.config.appServer.mode: "guardian" oder OmeniaClaw_CODEX_APP_SERVER_MODE=guardian für einmalige lokale Tests. Die Konfiguration wird für wiederholbare Bereitstellungen bevorzugt, weil sie das Plugin-Verhalten in derselben geprüften Datei hält wie die restliche Einrichtung des Codex-Harness.

Verwandt

• Codex-Harness
• Codex-Harness-Laufzeit
• Native Codex-Plugins
• Codex Computer Use
• OpenAI-Provider
• Konfigurationsreferenz