OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Plugin guides

Codex harness

The official codex plugin runs embedded OpenAI agent turns through Codex app-server instead of the built-in OpenClaw harness. Codex owns the low-level agent session: native thread resume, native tool continuation, native compaction, and app-server execution. OpenClaw still owns chat channels, session files, model selection, OpenClaw dynamic tools, approvals, media delivery, and the visible transcript mirror.

Pasted text saved as a .txt attachment is extracted by OpenClaw and included in the current turn as untrusted external content, subject to the existing file extraction limits. This also applies to adopted and forked Codex sessions with locked model selection. Images continue through Codex's native image input.

Remote Codex app-servers can run on a different machine from the Gateway. Set remoteWorkspaceRoot to validate remote workspace attachment paths. OpenClaw transfers authoritative attachment bytes over the existing app-server connection using a fixed, no-shell command/exec reader. The reader rejects symlinks, enforces file and response size limits before allocation, and stages immutable Gateway-managed media before channel delivery without requiring a shared or synchronized filesystem. Codex images are materialized directly from typed app-server events. Saved-path-only images use the same bounded remote reader. Uploads always use the Gateway's configured channel identity and request timeout.

Use canonical OpenAI model refs such as openai/gpt-5.6-sol. Do not configure legacy Codex GPT refs. Put OpenAI agent auth order under auth.order.openai. Legacy Codex auth profile ids and legacy Codex auth order entries are repaired by openclaw doctor --fix.

With provider/model runtime policy unset or auto, the openai/* prefix alone never selects this harness. OpenAI may select Codex implicitly only for an exact official HTTPS Platform Responses or ChatGPT Responses route with no authored provider request override. Valid model-scoped params.fastMode / params.fast_mode values and valid cutoff keys are typed agent-runtime controls, so they do not count as authored provider request params or select a runtime by themselves. See OpenAI implicit agent runtime. If Codex owns auth before Platform versus ChatGPT routing is known, OpenClaw still requires every candidate route to declare Codex compatibility. Native auth ownership alone never bypasses that route check.

When no OpenClaw sandbox is active, OpenClaw starts Codex app-server threads with Codex native code mode enabled (code-mode-only stays off by default), so native workspace/code capabilities remain available alongside OpenClaw dynamic tools routed through the app-server item/tool/call bridge. An ordinary OpenClaw sandbox or restricted tool policy disables native code mode unless you opt into the experimental sandbox exec-server path. Node-backed remote-exec on a paired device or cloud worker instead uses its placement-owned environment without that experimental flag. A dedicated cloud worker with a completed project preparation keeps the bound workspace and HOME paths, so native commands can reuse setup caches. The node exec-server still uses a separate temporary CODEX_HOME for each connection. Ending the connection removes that Codex state and preserves the prepared project home.

Eligible native-shell turns also retain gateway_exec and gateway_process as a distinct OpenClaw execution path. Use gateway_exec only when a command needs OpenClaw-managed Gateway environment access, including Secret Store agent-readable environment values or protected egress sentinels. It is pinned to the Gateway host and follows OpenClaw exec policy. gateway_process uses the existing per-session OpenClaw process scope for background follow-up. Prefer Codex native shell for ordinary local work.

Stopping an active Codex run interrupts its turn, then stops the native background terminals listed on that Codex thread before releasing the run. Other Codex threads and deliberately backgrounded gateway_process jobs are unaffected. If native terminal cleanup fails, the run reports an error instead of silently claiming cleanup succeeded. Inspect that thread's running terminals before starting more work. This uses Codex's terminal ownership. It does not guarantee cleanup of commands that deliberately detach from that ownership.

With the default tools.exec.host: "auto" and no active OpenClaw sandbox, Codex also receives node_exec when a connected node supports system.run. Offline paired devices and devices without shell support do not expose this tool. When a node is configured, that binding must resolve to an eligible node. Native shell remains on the Codex app-server host and workspace (Gateway-local for the default stdio deployment). node_exec selects the sole connected node that supports system.run, or requires a name or id when several are eligible. It keeps OpenClaw's node approval policy in force and waits for the remote command to finish. Remote-node background follow-up is not available. If a finite runtime allowlist disables native Code Mode and leaves the turn without an execution environment, OpenClaw keeps its policy-filtered exec and process tools available instead for direct, unsandboxed execution.

When tools.exec.host: "node" or /exec host=node makes the node the session default, OpenClaw hides the Codex-native shell and exposes node_exec only while the node target is eligible. If it is unavailable, reconnect the configured node or explicitly change the exec host. OpenClaw does not silently fall back to the app-server or Gateway machine.

gateway_exec is not exposed when an active OpenClaw sandbox, a node-default execution policy, memory-flush restrictions, tool allow/deny policy, or codexDynamicToolsExclude would make Gateway host access a bypass. Secret Store environment values never enter the Codex app-server process, native shell, sandbox exec-server, ACP children, sandbox exec, or node exec.

This Codex-native feature is separate from OpenClaw Code Mode, an opt-in QuickJS-WASI runtime for generic OpenClaw runs with a different exec input shape. For the broader model/provider/runtime split, start with Agent runtimes: openai/gpt-5.6-sol is the model ref, codex is the runtime, and Telegram, Discord, Slack, or another channel is the communication surface.

Saved-account usage

The plugin's codex.accountUsage Gateway method accepts agentId and profileId. It reuses account/rateLimits/read in a temporary local app-server with the selected login, even when the normal harness uses a native home or remote server. Each request fetches current quotas for the selected saved subscription login. The request requires operator.admin and rejects changed or removed credentials. Proxy launch arguments are rejected to avoid changing a shared daemon's login.

Requirements

  • The official @openclaw/codex plugin installed. Include codex in plugins.allow if your config uses an allowlist.
  • Managed Codex app-server 0.153.4. The plugin ships and manages @openai/codex 0.153.4 by default, so a codex command on PATH does not affect normal startup. Explicit custom, remote, and macOS desktop-owned app-servers must report a parseable semantic version of 0.149.0 or newer. Newer versions continue with a compatibility warning and normal runtime validation.
  • Node.js on the remote Codex app-server host when remoteWorkspaceRoot is set and cross-machine workspace attachments must be transferred.
  • Codex auth through openclaw models auth login --provider openai, an app-server account already present in the agent's Codex home, or an explicit Codex API-key auth profile.

For auth precedence, environment isolation, custom app-server commands, model discovery, and the full config field list, see Codex harness reference.

Quickstart

Install the official plugin, then sign in with Codex OAuth:

bash
openclaw plugins install @openclaw/codexopenclaw models auth login --provider openai

Enable the codex plugin and select an OpenAI agent model:

json5
{  plugins: {    entries: {      codex: {        enabled: true,      },    },  },  agents: {    defaults: {      model: "openai/gpt-5.6-sol",    },  },}

If your config uses plugins.allow, add codex there too:

json5
{  plugins: {    allow: ["codex"],    entries: {      codex: {        enabled: true,      },    },  },}

Restart the gateway after changing plugin config. If a chat already has a session, run /new or /reset first so the next turn resolves the harness from current config.

Verify Codex runtime

Use /status in the chat where you expect Codex. A Codex-backed OpenAI agent turn shows:

text
Runtime: OpenAI Codex

Then check Codex app-server state:

text
/codex status/codex models/codex binding

After installing or updating OpenClaw, explicitly verify the managed package binary before cutover:

bash
openclaw doctor --lint --only codex/managed-app-server --json

For an effective Codex route using the managed stdio app-server, this default-disabled check resolves the platform-native executable and requires the exact Codex version pinned by OpenClaw. It does not execute custom, remote, or macOS desktop-owned app-servers.

/status reports the resolved OpenClaw Fast policy (on, off, or auto) and the selected runtime. It does not report the upstream service tier actually honored or returned for a completed request. /codex binding reports the attached native thread and current model settings. /codex status reports app-server connectivity, account, rate limits, MCP servers, and skills. Neither Codex command is provider-response telemetry. /codex models lists the live Codex app-server catalog for the harness and account. If /status is surprising, see Troubleshooting.

Where each section moved

Every section of the single-page version now lives on this page or on one of the nine child pages below. The anchors from the single-page version still resolve here.

Run Codex on another machine

Run Codex on another machine — Place Codex native execution on a paired device or a cloud worker.

Codex routing and deployment

Codex routing and deployment — Choose which OpenAI routes select Codex and shape the deployment around them.

Codex harness configuration

Codex harness configuration — Codex harness config map, restricted turns, project instructions, compaction, and long context.

Codex app-server policy

Codex app-server policy — App-server transport, approval posture, auth order, and environment isolation.

Codex plugin config fields

Codex plugin config fields — Top-level and appServer config fields for the Codex plugin.

Codex commands and diagnostics

Codex commands and diagnostics — The /codex command surface, Fast mode controls, and local thread inspection.

Codex runtime behavior

Codex runtime behavior — Dynamic tools, web search, image loading, turn liveness, and runtime boundaries.

Native Codex state and features

Native Codex state and features — Share native Codex threads, supervise sessions, and enable native plugins and Computer Use.

Codex harness troubleshooting

Codex harness troubleshooting — Symptoms and fixes for Codex harness selection, app-server, and memory problems.

Was this useful?
On this page

On this page