Codex runtime behavior

What the Codex harness owns during a turn, and what stays with OpenClaw. Part of the Codex harness guide; Where each section moved lists every section.

Dynamic tools and web search

Codex dynamic tools default to searchable loading. OpenClaw normally does not expose dynamic tools that duplicate Codex-native workspace operations: read, write, edit, apply_patch, exec, process, get_goal, create_goal, update_goal, tool_call, tool_describe, tool_search, and tool_search_code. Goal operations stay native to Codex, so OpenClaw does not project a second goal store into Codex turns. Most remaining OpenClaw integration tools, such as messaging, media, cron, browser, nodes, gateway, progress_card, and heartbeat_respond are available through Codex tool search under the openclaw namespace, keeping the initial model context smaller. The restricted-turn shell fallback is the exception for exec and process when a finite allowlist disables native Code Mode; runtime allowlists and codexDynamicToolsExclude still apply. When native shell remains active and Gateway access is policy-eligible, OpenClaw instead publishes the distinct gateway_exec and gateway_process names so native shell and the OpenClaw-managed environment path cannot be confused.

Tools marked catalogMode: "direct-only", including the OpenClaw computer tool, use the openclaw_direct namespace instead. Codex treats that namespace as DirectModelOnly, so those tools stay directly model-visible in normal and code-mode-only threads rather than crossing nested Code Mode tools.* calls.

Web search uses Codex's hosted web_search tool by default when search is enabled and no managed provider is selected. Native hosted search and OpenClaw's managed web_search dynamic tool are mutually exclusive so managed search cannot bypass native domain restrictions. OpenClaw uses the managed tool when hosted search is unavailable, explicitly disabled, or replaced by a selected managed provider. OpenClaw keeps Codex's standalone web.run extension disabled because production app-server traffic rejects its user-defined web namespace. tools.web.search.enabled: false disables both paths, as do tool-disabled LLM-only runs. Codex treats "cached" as a preference and resolves it to live external access for unrestricted app-server turns. Automatic managed fallback fails closed when native allowedDomains are set so the allowlist cannot be bypassed. Persistent effective search-policy changes rotate the bound Codex thread before the next turn; transient per-turn restrictions use a temporary restricted thread and preserve the existing binding for later resume.

sessions_yield, sessions_spawn, and message-tool-only source replies stay direct because they are turn-control or delegation contracts. Guidance still prefers Codex's native spawn_agent as the primary Codex subagent surface, while explicit OpenClaw or ACP delegation remains directly callable through sessions_spawn. In Codex Code Mode, generic OpenClaw dynamic-tool results are JSON text rather than JavaScript objects, so parse JSON-looking results before reading fields. Codex also serializes nested dynamic calls; submit several sessions_spawn calls in a bounded loop rather than expecting Promise.all to launch them concurrently. Already-accepted children can still overlap while later calls are submitted. See Swarm for a complete pattern. Scheduled heartbeat user messages identify heartbeat_respond when structured responses are enabled; the tool remains discoverable through Codex tool search.

Set codexDynamicToolsLoading: "direct" only when connecting to a custom Codex app-server that cannot search deferred dynamic tools or when debugging the full tool payload.

Image loader ownership

For image-capable models with Codex native tools enabled, Codex owns view_image and OpenClaw suppresses its duplicate loader. The native Codex schema accepts one local filesystem path. For text-only models, or when the native tool surface is disabled, OpenClaw supplies view_image with its path/paths schema and delegated vision route. Callers must use the schema advertised for the active run.

Turn liveness and timeouts

Codex owns provider-stream liveness and native turn completion. OpenClaw waits for the exact turn/completed outcome rather than interrupting a quiet turn or treating assistant output as completion. The existing agents.defaults.timeoutSeconds limit is an elapsed execution budget per attempt: progress does not reset it, and 0 means unlimited execution. OpenClaw still bounds its own requests, dynamic tools, cancellation, and local settlement. See Timeouts for those budgets, Stop and replay behavior, and Doctor migration of retired idle settings.

Parallel chats and thread ownership

Independent chats can share a Codex app-server and run concurrently. Resuming an idle chat does not require unrelated chats, model discovery, or tool-catalog reads to finish. OpenClaw coordinates its own lifecycle operations for each native thread and preserves that thread's identity across ordinary resumes. A closed, replaced, or retired client still cannot complete a stale handoff.

After a completed provider failure, you can continue in the same chat with its existing configuration. OpenClaw retains the configured native thread, including for /codex resume of that chat's already-bound thread. Provider policy refusals end the current request without automatic retry or model fallback. A later user message is a separate turn; it does not supply a native policy override or user confirmation.

With Codex app-server 0.153.4, first-time adoption or changed configuration of a loaded failed thread still requires native unloading. OpenClaw preserves the thread and reports missing configuration confirmation instead of assuming the changes took effect. Existing active-turn and parent-controlled-thread checks still apply.

This coordination does not make native configuration replacement atomic against Codex-internal controllers. Native subagent reloads or another native controller can operate outside OpenClaw's thread queue. Avoid concurrently reconfiguring the same native thread through multiple controllers; observing native teardown alone does not reserve it against a subsequent native reload.

Runtime boundaries

The Codex harness changes the low-level embedded agent executor only.

• OpenClaw dynamic tools are supported. Codex asks OpenClaw to execute those tools, so OpenClaw remains in the execution path.
• Codex-native shell, patch, MCP, and native app tools are owned by Codex. OpenClaw can observe or block selected native events through the supported relay, but it does not rewrite native tool arguments.
• gateway_exec and gateway_process are OpenClaw-owned dynamic tools. They deliberately re-enter Gateway exec preparation for agent-readable Secret Store environment and protected egress; those values never flow into Codex native shell.
• Codex owns native compaction. OpenClaw keeps a transcript mirror for channel history, search, /new, /reset, and future model or harness switching, but does not replace Codex compaction with an OpenClaw or context-engine summarizer. Completed commentary and tool activity are saved during the turn rather than waiting for its final answer, preserving completed work across Gateway interruption.
• Media generation, media understanding, TTS, approvals, and messaging-tool output continue through the matching OpenClaw provider/model settings.
• tool_result_persist applies to OpenClaw-owned transcript tool results, not Codex-native tool result records.

For hook layers, supported V1 surfaces, native permission handling, queue steering, Codex feedback upload mechanics, and compaction details, see Codex harness runtime.