Codex-Harness-Referenz

Diese Referenz behandelt die detaillierte Konfiguration für das offizielle codex-Plugin. Beginnen Sie bei Entscheidungen zu Einrichtung und Routing mit dem 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",          },        },      },    },  },}

Felder der obersten Ebene:

Überwachung

Die native Sitzungserkennung listet standardmäßig nicht archivierte Codex-Sitzungen vom Gateway-Computer und von aktivierten gekoppelten Nodes auf. Deaktivieren Sie nur diesen Katalog mit:

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

supervision steuert agentenseitige Tools separat:

Endpunkteinträge akzeptieren diese Felder:

Die Seite Codex-Sitzungen verwendet den Überwachungs-App-Server des Plugins und zeigt nur nicht archivierte Sitzungen an. Ohne explizite appServer-Verbindungseinstellungen wird diese Verbindung als verwaltetes Benutzer-Home-stdio betrieben. Gespeicherte oder inaktive lokale Zeilen können einen modellgebundenen Chat mit begrenztem Benutzer- und Assistentenverlauf bis zum letzten dauerhaft gespeicherten abschließenden Quelldurchlauf erstellen. Seine private Bindung hält den Snapshot-Fork, den kanonischen Branch der appServer-Quelle, die Verlaufsinjektion und spätere Durchläufe auf dieser Verbindung. Beim ersten kanonischen Start wird das vom Fork zurückgegebene Paar verwendet. Bei späteren Fortsetzungen werden OpenClaw-Modell- und Provider-Überschreibungen ausgelassen, sodass Codex das dauerhaft gespeicherte Paar des kanonischen Threads wiederherstellt. Eine separate native Änderung kann dieses Paar aktualisieren, aber das äußere Modell und die Fallback-Kette ersetzen es niemals. Gespeicherte und inaktive Zeilen können nach der Bestätigung, dass kein anderer Runner vorhanden ist, archiviert werden, sofern nicht eine andere aktive OpenClaw-Bindung das exakte Ziel oder einen seiner nicht archivierten erzeugten Nachfolger besitzt. OpenClaw folgt der Nachfolger-Paginierung von Codex und bricht bei Aufzählungsfehlern, Zyklen oder dem Ausschöpfen der Sicherheitsgrenze sicher ab. Die Bestätigung deckt weiterhin unbekannte native Clients und das Zeitfenster zwischen Statusprüfung und Archivierung ab. Ein überwachter modellgebundener Chat kann nicht gelöscht werden, solange er die native Bindung schützt. Aktive Quellen können weder einen Branch erstellen noch archiviert werden, ein bestehender überwachter Chat kann jedoch weiterhin geöffnet werden. Jede Zeile eines gekoppelten Nodes bleibt schreibgeschützt; der Node-Transport stellt den für den Harness erforderlichen Streaming-Lebenszyklus noch nicht bereit.

appServer.homeScope: "user" allein ändert, welches Codex-Home ein verwalteter Harness-Prozess verwendet; die Fleet-Katalogisierung wird dadurch nicht veröffentlicht. Das Aktivieren der Überwachung ändert den Standardwert des Harness nicht. Stattdessen verwendet die separate Überwachungsverbindung standardmäßig verwaltetes Benutzer-Home-stdio, wenn keine expliziten appServer-Verbindungseinstellungen vorhanden sind. Explizite Einstellungen werden für diese Verbindung berücksichtigt. Ausstehende und festgeschriebene überwachte Bindungen behalten diese Verbindung für jeden Durchlauf bei; eine deaktivierte Überwachung oder eine Abweichung bei Verbindung oder Lebenszyklus führt zu einem sicheren Abbruch, statt auf den Agent-Home- Harness zurückzufallen. Die Standardverbindung teilt gespeicherte Sitzungen mit nativen Codex-Clients, nicht deren prozesslokalen Aktivitätszustand.

Veraltete plugins.entries.codex-supervisor-Einstellungen werden nicht mehr unterstützt. Führen Sie openclaw doctor --fix aus, um den alten Eintrag, die Endpunktdefinitionen, Richtlinien-Flags und Plugin-Zulassungs-/Ablehnungsreferenzen in diesen Block zu migrieren. Explizite kanonische codex.config.supervision-Werte haben bei Konflikten Vorrang.

App-Server-Transport

Für gewöhnliche Harness-Durchläufe startet OpenClaw die verwaltete Codex-Binärdatei, die mit dem offiziellen Plugin ausgeliefert wird (derzeit @openai/codex 0.145.0):

codex app-server --listen stdio://

Dadurch bleibt die App-Server-Version an das offizielle codex-Plugin gebunden und nicht an eine beliebige separat lokal installierte Codex CLI. Setzen Sie appServer.command nur, wenn Sie bewusst eine andere ausführbare Datei verwenden möchten. Gewöhnliche verwaltete Durchläufe mit dem standardmäßigen isolierten Agent-Home bevorzugen dieses fixierte Paket auch dann, wenn ein macOS-Desktop-Bundle installiert ist. Wenn Computer Use aktiviert ist oder wenn homeScope den Wert "user" hat und nativen Computer-Use-Zustand laden kann, bevorzugt der verwaltete Start stattdessen die Binärdatei der Desktop-App, die über die erforderlichen macOS-Berechtigungen verfügt. Dieselbe Desktop-zuerst-Regel gilt, wenn die wirksame Codex-Konfiguration eines isolierten Agent-Home natives Computer Use aktiviert. Wenn kein Desktop-App-Bundle installiert ist, greift OpenClaw auf die Binärdatei des fixierten Pakets zurück.

Die Übergabe ausführbarer Dateien und die Abschirmung nativer Konfiguration koordinieren Clients innerhalb eines laufenden Gateway-Prozesses. Starten Sie den Gateway neu, nachdem ein anderer Prozess die native Codex-Plugin-Konfiguration geändert hat.

Die Überwachung löst eine separate Verbindung auf. Ohne explizite appServer-Verbindungseinstellungen verwendet sie verwaltetes stdio mit homeScope: "user"; der gewöhnliche Harness bleibt bei verwaltetem stdio mit homeScope: "agent". Explizite Verbindungseinstellungen werden von beiden Pfaden berücksichtigt. Setzen Sie homeScope: "user" explizit, wenn der gewöhnliche Harness $CODEX_HOME (oder ~/.codex) mit nativen Clients teilen soll. Eine private überwachte Bindung verwendet unabhängig vom Standardwert des gewöhnlichen Harness die Überwachungsverbindung. Unabhängige App-Server-Prozesse behalten getrennte Live-Status- und Genehmigungszustände bei.

Für Tests außerhalb der Produktion mit einem bereits laufenden App-Server ist der WebSocket-Transport verfügbar:

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

Codex stuft den WebSocket-Transport als experimentell und nicht unterstützt ein. Bevorzugen Sie für Produktionsworkloads verwaltetes stdio oder den lokalen Unix-Steuerungssocket.

Felder von appServer:

appServer.networkProxy ist explizit, da es den Sandbox-Vertrag von Codex ändert. Wenn diese Option aktiviert ist, setzt OpenClaw außerdem features.network_proxy.enabled und default_permissions in der Codex-Thread-Konfiguration, sodass das generierte Berechtigungsprofil die von Codex verwaltete Netzwerkfunktion starten kann. OpenClaw generiert standardmäßig einen kollisionsresistenten Profilnamen openclaw-network-<fingerprint> aus dem Profilinhalt; verwenden Sie profileName nur, wenn ein stabiler lokaler Name erforderlich ist.

export default {  plugins: {    entries: {      codex: {        config: {          appServer: {            sandbox: "workspace-write",            networkProxy: {              enabled: true,              domains: {                "api.openai.com": "allow",                "blocked.example.com": "deny",              },              allowUpstreamProxy: true,              proxyUrl: "http://127.0.0.1:3128",            },          },        },      },    },  },};

Wenn die normale App-Server-Laufzeit danger-full-access wäre, verwendet die Aktivierung von networkProxy stattdessen einen Arbeitsbereich-ähnlichen Dateisystemzugriff für das generierte Berechtigungsprofil. Die von Codex verwaltete Netzwerkdurchsetzung ist eine Sandbox-Netzwerkfunktion, daher würde ein Profil mit Vollzugriff den ausgehenden Datenverkehr nicht schützen.

Das Plugin blockiert ältere, neuere nicht validierte, Vorab-, mit Build-Suffix versehene oder unversionierte App-Server-Handshakes. Der Codex-App-Server muss eine stabile Version von 0.143.0 bis einschließlich des gebündelten 0.145.0 melden.

OpenClaw behandelt WebSocket-App-Server-URLs, die nicht auf die Loopback-Schnittstelle verweisen, als remote und verlangt identitätstragende WebSocket-Authentifizierung über appServer.authToken oder einen Authorization-Header. appServer.authToken und jeder appServer.headers.*-Wert können ein SecretInput sein; die Secrets-Laufzeit löst SecretRefs und Env-Kurzformen auf, bevor OpenClaw die App-Server-Startoptionen erstellt, und nicht aufgelöste strukturierte SecretRefs führen zu einem Fehler, bevor Token oder Header gesendet werden. Wenn native Codex-Plugins konfiguriert sind, verwendet OpenClaw die Plugin-Steuerungsebene des verbundenen App-Servers, um diese Plugins zu installieren oder zu aktualisieren, und aktualisiert anschließend das App-Inventar, damit Plugin-eigene Apps für den Codex-Thread sichtbar sind. app/list ist weiterhin die maßgebliche Inventar- und Metadatenquelle, aber die OpenClaw-Richtlinie entscheidet, ob thread/start für eine aufgelistete, zugängliche App config.apps[appId].enabled = true sendet, selbst wenn Codex sie derzeit als deaktiviert kennzeichnet. Unbekannte oder fehlende App-IDs bleiben standardmäßig gesperrt; dieser Pfad aktiviert lediglich Marketplace-Plugins über plugin/install und aktualisiert das Inventar. Verbinden Sie OpenClaw nur mit Remote-App-Servern, denen Sie zutrauen, von OpenClaw verwaltete Plugin-Installationen und Aktualisierungen des App-Inventars zu akzeptieren.

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 Haltung für lokale Operatoren ermöglicht unbeaufsichtigten OpenClaw-Durchläufen und Heartbeats Fortschritte ohne native Genehmigungsaufforderungen, die niemand beantworten kann.

Wenn die lokale Systemanforderungsdatei von Codex implizite YOLO-Genehmigungs-, Prüfer- oder Sandbox-Werte nicht zulässt, behandelt OpenClaw den impliziten Standard stattdessen als Guardian und wählt zulässige Guardian-Berechtigungen aus. tools.exec.mode: "auto" erzwingt ebenfalls von Guardian geprüfte Codex-Genehmigungen und behält unsichere veraltete Überschreibungen durch approvalPolicy: "never" oder sandbox: "danger-full-access" nicht bei; setzen Sie tools.exec.mode: "full" für eine bewusst gewählte Haltung ohne Genehmigungen. Mit dem Hostnamen übereinstimmende [[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 von Codex Guardian geprüfte 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.

Wenn eine OpenClaw-Sandbox aktiv ist, wird der lokale Codex-App-Server-Prozess weiterhin auf dem Gateway-Host ausgeführt. OpenClaw deaktiviert daher für diesen Durchlauf den nativen Code Mode von Codex, MCP-Server des Benutzers und die App-gestützte Plugin-Ausführung, anstatt die Host-seitige Sandbox von Codex als gleichwertig mit dem OpenClaw-Sandbox-Backend zu behandeln. Shell-Zugriff wird über von der OpenClaw-Sandbox gestützte dynamische Tools wie sandbox_exec und sandbox_process bereitgestellt, wenn die normalen Exec-/Prozess-Tools verfügbar sind.

Native Ausführung in der Sandbox

Der stabile Standard ist „Fail-Closed“: Eine aktive OpenClaw-Sandbox deaktiviert native Codex-Ausführungsoberflächen, die andernfalls auf dem Host des Codex-App-Servers ausgeführt würden. Verwenden Sie appServer.experimental.sandboxExecServer: true nur, wenn Sie die Remote-Umgebungsunterstützung von Codex mit dem Sandbox-Backend von OpenClaw ausprobieren möchten. Dieser Vorschaupfad funktioniert mit jeder unterstützten Codex-App-Server-Version.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            experimental: {              sandboxExecServer: true,            },          },        },      },    },  },}

Wenn das Flag aktiviert und die aktuelle OpenClaw-Sitzung in einer Sandbox ausgeführt wird, startet OpenClaw einen lokalen Loopback-Exec-Server, der von der aktiven Sandbox gestützt wird, registriert ihn beim Codex-App-Server und startet den Codex-Thread und -Durchlauf mit dieser OpenClaw-eigenen Umgebung. Wenn der App-Server die Umgebung nicht registrieren kann, schlägt der Durchlauf standardmäßig fehl, anstatt stillschweigend auf die Host-Ausführung zurückzufallen.

Dieser Vorschaupfad ist nur lokal verfügbar. Ein Remote-WebSocket-App-Server kann den Loopback-Exec-Server nur erreichen, wenn er auf demselben Host ausgeführt wird, daher lehnt OpenClaw diese Kombination ab.

Authentifizierungs- und Umgebungsisolation

Im standardmäßigen agentenspezifischen Home-Verzeichnis wird die Authentifizierung in dieser Reihenfolge ausgewählt:

1. Ein explizites OpenClaw-Codex-Authentifizierungsprofil für den Agenten.
2. Das bestehende Konto des App-Servers im Codex-Home-Verzeichnis dieses Agenten.
3. Nur für lokale stdio-App-Server-Starts: CODEX_API_KEY, anschließend OPENAI_API_KEY, wenn kein App-Server-Konto vorhanden ist und weiterhin eine OpenAI-Authentifizierung erforderlich ist.

Wenn OpenClaw ein Codex-Authentifizierungsprofil im Stil eines ChatGPT-Abonnements erkennt (OAuth oder Anmeldedatentyp „Token“), entfernt es CODEX_API_KEY und OPENAI_API_KEY aus dem erzeugten Codex-Kindprozess. Dadurch bleiben API-Schlüssel auf Gateway-Ebene für Einbettungen oder direkte OpenAI-Modelle verfügbar, ohne dass native Durchläufe des Codex-App-Servers versehentlich über die API abgerechnet werden.

Explizite Codex-API-Schlüsselprofile und der lokale stdio-Fallback auf Env-Schlüssel verwenden die App-Server-Anmeldung statt einer geerbten Kindprozessumgebung. WebSocket-App-Server- Verbindungen erhalten keinen Fallback auf API-Schlüssel aus der Gateway-Umgebung; verwenden Sie ein explizites Authentifizierungsprofil oder das eigene Konto des Remote-App-Servers.

Stdio-App-Server-Starts erben standardmäßig die Prozessumgebung von OpenClaw. OpenClaw verwaltet die Kontobrücke des Codex-App-Servers und setzt CODEX_HOME auf ein agentenspezifisches Verzeichnis unter dem OpenClaw-Status dieses Agenten. Dadurch bleiben Codex- Konfiguration, Konten, Plugin-Cache/-Daten und Thread-Status auf den OpenClaw- Agenten beschränkt, statt aus dem persönlichen ~/.codex-Home-Verzeichnis des Operators einzusickern.

Setzen Sie appServer.homeScope: "user", um den nativen Codex-Status mit Codex Desktop und der CLI zu teilen. Dieser lokale Benutzer-Home-Modus unterstützt verwaltetes stdio und expliziten Unix-Transport. Er verwendet $CODEX_HOME, wenn gesetzt, andernfalls ~/.codex, einschließlich nativer Authentifizierung, Konfiguration, Plugins und Threads. OpenClaw überspringt seine Authentifizierungsprofilbrücke für den App-Server. Verifizierte Eigentümerdurchläufe können codex_threads verwenden, um diese Threads aufzulisten (mit einem optionalen search-Filter), zu lesen, zu forken, umzubenennen, zu archivieren und die Archivierung aufzuheben. Forken Sie einen Thread, bevor Sie ihn in OpenClaw fortsetzen; unabhängige Codex-Prozesse koordinieren keine gleichzeitigen Schreibzugriffe auf denselben Thread.

Diese Zustimmung zu homeScope gilt für gewöhnliche Harness-Sitzungen. Ein über Codex Sessions erstellter Chat verwendet stattdessen seine private Überwachungsverbindung, wodurch die Authentifizierungs- und Provider-Konfiguration der nativen Verbindung für den kanonischen Branch und zukünftige Fortsetzungen erhalten bleibt.

In einem modellgebundenen überwachten Chat kann codex_threads weder einen anderen Fork anhängen noch den an den Chat gebundenen nativen Thread archivieren. Auflisten und reines Lesen von Metadaten bleiben verfügbar. Das Lesen von Rohtranskripten erfordert allowRawTranscripts; wenn diese Option deaktiviert ist, wird auch die Listensuche abgelehnt, da die native Suche Übereinstimmungen in Transkriptvorschauen finden kann. Umbenennen, Aufheben der Archivierung, abgetrenntes Forken und Archivieren eines nicht zugehörigen Threads, der keinem anderen OpenClaw-Chat gehört, erfordern allowWriteControls. Keine der Optionen umgeht eine gesperrte Bindung.

OpenClaw schreibt HOME bei normalen lokalen App-Server-Starts nicht um. Von Codex ausgeführte Unterprozesse wie openclaw, gh, git, Cloud-CLIs und Shell- Befehle sehen das normale Prozess-Home-Verzeichnis und können Benutzer-Home-Konfigurationen und Token finden. Codex kann außerdem $HOME/.agents/skills und $HOME/.agents/plugins/marketplace.json erkennen; diese .agents-Erkennung wird bewusst mit dem Operator-Home-Verzeichnis geteilt und ist vom isolierten ~/.codex-Status getrennt.

Im standardmäßigen Agentenbereich werden OpenClaw-Plugins und Momentaufnahmen von OpenClaw-Skills weiterhin über die eigene Plugin-Registry und den Skills-Loader von OpenClaw bereitgestellt; persönliche Codex-~/.codex-Assets dagegen nicht. Wenn Sie nützliche Codex-CLI-Skills oder Plugins aus einem Codex-Home-Verzeichnis haben, die Teil eines isolierten OpenClaw- Agenten werden sollen, erfassen Sie diese explizit:

openclaw migrate codex --dry-runopenclaw 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 erzeugten Kindprozess des Codex-App-Servers aus. OpenClaw entfernt CODEX_HOME und HOME während der Normalisierung des lokalen Starts aus dieser Liste: CODEX_HOME verweist weiterhin auf den ausgewählten Agenten- oder Benutzerbereich, und HOME wird weiterhin geerbt, sodass Unterprozesse den normalen Status des Benutzer-Home-Verzeichnisses verwenden können.

Dynamische Tools

Dynamische Codex-Tools verwenden standardmäßig das Laden gemäß searchable und werden unter dem Namespace openclaw mit deferLoading: true bereitgestellt. OpenClaw stellt normalerweise keine dynamischen Tools bereit, die native Arbeitsbereichsoperationen von Codex oder die eigene Toolsuche von Codex duplizieren:

• read
• write
• edit
• apply_patch
• exec
• process
• update_plan
• tool_call
• tool_describe
• tool_search
• tool_search_code

Wenn eine endliche Laufzeit-Zulassungsliste den nativen Code Mode deaktiviert, sendet OpenClaw eine leere Auswahl der Ausführungsumgebung. In diesem direkten Fall ohne Sandbox behält OpenClaw seine richtliniengefilterten Tools exec und process als Shell- Fallback bei. Laufzeit-Zulassungslisten und codexDynamicToolsExclude gelten weiterhin.

Die meisten verbleibenden OpenClaw-Integrationstools, etwa für Messaging, Medien, Cron, Browser, Nodes, Gateway, heartbeat_respond und web_search, sind über die Codex-Tool-Suche unter diesem Namespace verfügbar. Dadurch bleibt der anfängliche Modellkontext kleiner. Eine kleine Gruppe von Tools bleibt unabhängig von codexDynamicToolsLoading direkt aufrufbar, da die Codex-Tool-Suche nicht verfügbar sein oder nur ein Connector-Universum auflösen kann: agents_list, sessions_spawn und sessions_yield. Entwickleranweisungen lenken normale Codex-Subagenten für Codex-native Subagentenarbeit weiterhin zu nativem spawn_agent, während sessions_spawn für eine explizite Delegation an OpenClaw oder ACP verfügbar bleibt. Quellantworten, die ausschließlich das Nachrichtentool verwenden, bleiben ebenfalls direkt, da dies ein Vertrag zur Ablaufsteuerung eines Turns ist.

Der Codex-Code-Modus stellt Ergebnisse generischer dynamischer OpenClaw-Tools als Text dar. Parsen Sie ein JSON-Ergebnis, bevor Sie Felder auslesen. Verschachtelte dynamische Aufrufe werden von der Codex-Laufzeit serialisiert, daher übermittelt Promise.all sie nicht gleichzeitig; verwenden Sie beim Starten untergeordneter Collector-Prozesse eine begrenzte sequenzielle Startschleife.

Mit catalogMode: "direct-only" gekennzeichnete Tools, einschließlich des OpenClaw-Tools computer, werden unter openclaw_direct gruppiert. OpenClaw fügt diesen Namespace der Liste code_mode.direct_only_tool_namespaces von Codex hinzu, ohne vom Operator bereitgestellte Einträge zu ersetzen. Codex stellt diese Tools daher in normalen und ausschließlich im Code-Modus ausgeführten Threads als DirectModelOnly bereit, statt sie durch verschachtelte tools.*-Aufrufe des Code-Modus zu leiten. Diese Grenze ist für Ergebnisse mit Bildern erforderlich: Die verschachtelte Serialisierung im Code-Modus reduziert die Bildausgabe auf Text, wodurch der für die nächste Computeraktion benötigte Screenshot verloren ginge.

Setzen Sie codexDynamicToolsLoading: "direct" nur, wenn Sie eine Verbindung zu einem benutzerdefinierten Codex-App-Server herstellen, der zurückgestellte dynamische Tools nicht durchsuchen kann, oder wenn Sie die vollständige Tool-Nutzlast debuggen.

Zeitüberschreitungen

OpenClaw-eigene dynamische Tool-Aufrufe 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 aufrufbezogenes Argument timeoutMs.
• Für image_generate: agents.defaults.mediaModels.image.timeoutMs.
• Für image_generate ohne konfigurierte Zeitüberschreitung gilt der Standardwert von 120 Sekunden für die Bilderzeugung.
• Für das Medienanalyse-Tool image: der Wert timeoutSeconds des ausgewählten bildfähigen Eintrags tools.media.models[], umgerechnet in Millisekunden, oder der Medienstandardwert von 60 Sekunden. Bei der Bildanalyse gilt dies für die Anfrage selbst und wird nicht durch vorherige Vorbereitungsarbeiten reduziert.
• Für das Tool message: ein festes äußeres Zeitbudget von 600 Sekunden, das die Gateway-Zustellung und den begrenzten Abgleich für denselben Schlüssel abdeckt.
• Der Standardwert von 90 Sekunden für dynamische Tools.

Dieser Watchdog ist das äußere Budget für dynamisches item/tool/call. Provider-spezifische Anfragezeitüberschreitungen laufen innerhalb dieses Aufrufs und behalten ihre eigene Zeitüberschreitungssemantik. Budgets für dynamische Tools sind auf 600000 ms begrenzt. agents_wait fügt 30000 ms äußere Abschlusskulanz hinzu, und der App-Server-Client lässt 660000 ms zu, damit das strukturierte Warteergebnis Codex erreichen kann. Bei einer Zeitüberschreitung bricht OpenClaw das Tool-Signal ab, sofern dies unterstützt wird, und gibt eine fehlgeschlagene Antwort des dynamischen Tools an Codex zurück, sodass der Turn fortgesetzt werden kann, statt die Sitzung in processing zu belassen.

Nachdem Codex einen Turn angenommen und OpenClaw auf eine turnbezogene App-Server-Anfrage geantwortet hat, erwartet das Harness, dass Codex im aktuellen Turn Fortschritte macht und den nativen Turn schließlich mit turn/completed beendet. Wenn der App-Server für appServer.turnCompletionIdleTimeoutMs inaktiv bleibt, versucht OpenClaw nach bestem Bemühen, den Codex-Turn zu unterbrechen, zeichnet eine diagnostische Zeitüberschreitung auf und gibt die OpenClaw-Sitzungsspur frei, damit nachfolgende Chatnachrichten nicht hinter einem veralteten nativen Turn eingereiht werden.

Die meisten nicht abschließenden Benachrichtigungen für denselben Turn deaktivieren diesen kurzen Watchdog, weil Codex nachgewiesen hat, dass der Turn noch aktiv ist. Tool-Übergaben verwenden ein längeres Inaktivitätsbudget nach dem Tool: nachdem OpenClaw eine Antwort item/tool/call zurückgibt, nachdem native Tool-Elemente wie commandExecution abgeschlossen sind, nach unverarbeiteten custom_tool_call_output-Abschlüssen sowie nach unverarbeitetem Assistentenfortschritt, Argumentationsabschlüssen oder Argumentationsfortschritt nach einem Tool. Die Schutzfunktion verwendet appServer.postToolRawAssistantCompletionIdleTimeoutMs, wenn dies konfiguriert ist, und standardmäßig andernfalls fünf Minuten. Dasselbe Budget nach einem Tool verlängert auch den Fortschritts-Watchdog für das stille Synthesefenster, bevor Codex das nächste Ereignis des aktuellen Turns ausgibt. Auf Argumentationsabschlüsse, Abschlüsse von Kommentar-agentMessage und unverarbeiteten Argumentations- oder Assistentenfortschritt vor einem Tool kann eine automatische abschließende Antwort folgen; deshalb verwenden sie die Antwortschutzfunktion nach Fortschritt, statt die Sitzungsspur sofort freizugeben. Nur abgeschlossene abschließende bzw. nicht als Kommentar eingestufte agentMessage-Elemente und unverarbeitete Assistentenabschlüsse vor einem Tool aktivieren die Freigabe nach Assistentenausgabe: Wenn Codex anschließend ohne turn/completed inaktiv bleibt, versucht OpenClaw nach bestem Bemühen, den nativen Turn zu unterbrechen, und gibt die Sitzungsspur frei. Wiederholungssichere Fehler des stdio-App-Servers, einschließlich Zeitüberschreitungen bei Inaktivität bis zum Turn-Abschluss ohne Hinweise auf Assistenten-, Tool-, aktive Element- oder Nebeneffektaktivität, werden einmal mit einem neuen App-Server-Versuch wiederholt. Unsichere Zeitüberschreitungen setzen den blockierten App-Server-Client dennoch außer Betrieb und geben die OpenClaw-Sitzungsspur frei. Sie löschen außerdem die veraltete Bindung des nativen Threads, statt automatisch wiederholt zu werden. Zeitüberschreitungen der Abschlussüberwachung zeigen Codex-spezifischen Zeitüberschreitungstext an: Wiederholungssichere Fälle weisen darauf hin, dass die Antwort möglicherweise unvollständig ist, während unsichere Fälle den Benutzer anweisen, vor einem erneuten Versuch den aktuellen Zustand zu prüfen. Öffentliche Zeitüberschreitungsdiagnosen enthalten strukturelle Felder wie die Methode der letzten App-Server-Benachrichtigung, ID/Typ/Rolle des unverarbeiteten Assistentenantwortelements, Anzahl aktiver Anfragen und Elemente sowie den Zustand der aktivierten Überwachung. Wenn die letzte Benachrichtigung ein unverarbeitetes Assistentenantwortelement ist, enthalten sie außerdem eine begrenzte Vorschau des Assistententexts. Sie enthalten keine unverarbeiteten Prompt- oder Tool-Inhalte.

Modellerkennung

Standardmäßig fragt das Codex-Plugin den App-Server nach verfügbaren Modellen. Die Modellverfügbarkeit liegt in der Verantwortung des Codex-App-Servers, sodass sich die Liste ändern kann, wenn OpenClaw die gebündelte Version @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 aktuellen Katalog für dieses Harness und Konto anzuzeigen.

Wenn die Erkennung fehlschlägt oder eine Zeitüberschreitung auftritt, verwendet OpenClaw einen gebündelten Ausweichkatalog:

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 beim Start keine Abfrage von Codex erfolgen und ausschließlich der Ausweichkatalog verwendet werden soll:

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

Bootstrap-Dateien des Arbeitsbereichs

Codex verarbeitet AGENTS.md selbst über die native Erkennung der Projektdokumentation. OpenClaw schreibt keine synthetischen Codex-Projektdokumentationsdateien und ist für Persona-Dateien nicht von Codex-Ausweichdateinamen abhängig, da Codex-Ausweichwerte nur gelten, wenn AGENTS.md fehlt.

Für die Gleichwertigkeit des OpenClaw-Arbeitsbereichs leitet das Codex-Harness die anderen Bootstrap-Dateien als Entwickleranweisungen weiter, jedoch nicht auf identische Weise:

• TOOLS.md wird als geerbte Codex-Entwickleranweisung weitergeleitet, sodass native Codex-Subagenten, die während des Turns gestartet werden, sie ebenfalls sehen.
• SOUL.md, IDENTITY.md und USER.md werden als turnbezogene Zusammenarbeitsanweisungen weitergeleitet. Native Codex-Subagenten erben sie nicht, wodurch verhindert wird, dass Subagenten-Turns die Persona und das Benutzerprofil des übergeordneten Agenten übernehmen.
• Die kompakte Liste der geladenen OpenClaw-Skills wird ebenfalls als turnbezogene Entwickleranweisung zur Zusammenarbeit weitergeleitet, sodass native Codex-Subagenten auch sie nicht erben.
• Der Inhalt von HEARTBEAT.md wird nicht eingefügt; Heartbeat-Turns erhalten einen Hinweis im Zusammenarbeitsmodus, die Datei zu lesen, wenn sie vorhanden und nicht leer ist.
• Der Inhalt von MEMORY.md aus dem konfigurierten Agentenarbeitsbereich wird nicht in die Eingabe nativer Codex-Turns eingefügt, wenn für diesen Arbeitsbereich Speicher-Tools verfügbar sind; wenn er vorhanden ist, fügt das Harness den turnbezogenen Entwickleranweisungen zur Zusammenarbeit einen kurzen Hinweis auf den Arbeitsbereichsspeicher hinzu, und Codex sollte memory_search oder memory_get verwenden, wenn dauerhafter Speicher relevant ist. Wenn Tools deaktiviert sind, die Speichersuche nicht verfügbar ist oder der aktive Arbeitsbereich vom Agentenspeicher-Arbeitsbereich abweicht, verwendet MEMORY.md stattdessen den normalen begrenzten Turn-Kontextpfad.
• BOOTSTRAP.md wird, sofern vorhanden, als Referenzkontext für OpenClaw-Turn-Eingaben weitergeleitet.

Umgebungsüberschreibungen

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

• OPENCLAW_CODEX_APP_SERVER_BIN
• OPENCLAW_CODEX_APP_SERVER_ARGS
• OPENCLAW_CODEX_APP_SERVER_MODE=yolo|guardian
• OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY
• OPENCLAW_CODEX_APP_SERVER_SANDBOX

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

OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1 wurde entfernt. Verwenden Sie stattdessen plugins.entries.codex.config.appServer.mode: "guardian" oder OPENCLAW_CODEX_APP_SERVER_MODE=guardian für einmalige lokale Tests. Für reproduzierbare Bereitstellungen wird die Konfiguration bevorzugt, da dadurch das Plugin-Verhalten in derselben geprüften Datei wie die übrige Einrichtung des Codex-Harness verbleibt.

Verwandte Themen

• Codex-Harness
• Codex-Harness-Laufzeit
• Codex-Überwachung
• Native Codex-Plugins
• Codex-Computersteuerung
• OpenAI-Provider
• Konfigurationsreferenz