Codex Harness Configuration Reference for the Codex Plugin

This reference details the configuration options for the official codex plugin. For guidance on setup and routing, begin with Codex harness.

Plugin config surface

Every Codex harness configuration option is located under plugins.entries.codex.config.

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

Fields at the top level:

Supervision

By default, native session discovery lists non-archived Codex sessions from the Gateway machine and any opted-in paired nodes. To disable only that catalog, use:

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

supervision independently manages agent-facing tools:

Endpoint entries accept these fields:

The Codex Sessions page uses the plugin's supervision App Server and shows only non-archived sessions. Without explicit appServer connection settings, that connection runs as managed user-home stdio. Stored or idle local rows can create a model-locked Chat with bounded user and assistant history through the last terminal persisted source turn. Its private binding keeps the snapshot fork, canonical appServer-source branch, history injection, and later turns on that connection. The first canonical start uses the pair returned by the fork. Later resumes omit OpenClaw model and provider overrides so Codex restores the canonical thread's persisted pair; a separate native change can update that pair, but the outer model and fallback chain never replace it. Stored and idle rows can be archived after no-other-runner confirmation, unless another active OpenClaw binding owns the exact target or one of its non-archived spawned descendants. OpenClaw follows Codex's descendant pagination and fails closed on enumeration errors, cycles, or safety-limit exhaustion. Confirmation still covers unknown native clients and the status-to-archive race. A supervised model-locked Chat cannot be deleted while it protects the native binding. Active sources cannot create a branch or be archived, but an existing supervised Chat can still be opened. Every paired-node row stays read-only; the node transport does not yet provide the streaming lifecycle needed by the harness.

appServer.homeScope: "user" alone changes which Codex home a managed harness process uses; it does not publish the fleet catalog. Enabling supervision does not change the harness default. Instead, the separate supervision connection defaults to managed user-home stdio when no explicit appServer connection settings exist. Explicit settings are honored for that connection. Pending and committed supervised bindings retain that connection for every turn; disabled supervision or connection/lifecycle drift fails closed instead of falling back to the agent-home harness. The default connection shares stored sessions with native Codex clients, not their process-local activity state.

Legacy plugins.entries.codex-supervisor settings are retired. Run openclaw doctor --fix to migrate the old entry, endpoint definitions, policy flags, and plugin allow/deny references into this block. Explicit canonical codex.config.supervision values win conflicts.

App-server transport

For standard harness turns, OpenClaw launches the managed Codex binary that ships with the official plugin (currently @openai/codex 0.145.0):

codex app-server --listen stdio://

This approach locks the app server version to the official codex plugin, rather than whatever separate Codex CLI version is present on the local machine. Only set appServer.command when you specifically need a different executable. In standard managed turns using the default isolated agent home, this pinned package takes precedence even if a macOS desktop bundle is present. When Computer Use is active, or when homeScope is set to "user" and can load native Computer Use state, managed startup instead gives priority to the desktop app binary that holds the necessary macOS permissions. The same desktop first rule applies when an isolated agent home's active Codex config enables native Computer Use. If no desktop app bundle is found, OpenClaw falls back to the pinned package binary.

Client coordination within a single running Gateway process is handled by executable handoff and native config fencing. Restart the Gateway after any other process modifies the native Codex plugin configuration.

Supervision resolves a separate connection. When no explicit appServer connection settings are provided, it uses managed stdio with homeScope: "user"; the standard harness also uses managed stdio, but with homeScope: "agent". Both paths respect explicit connection settings. Set homeScope: "user" explicitly when you want the ordinary harness to share $CODEX_HOME (or ~/.codex) with native clients. A private supervised binding always uses the supervision connection, regardless of the ordinary harness default. Independent App Server processes each maintain their own live status and approval state.

For non-production testing against an already running app server, WebSocket transport is available:

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

Codex considers WebSocket transport experimental and unsupported. For production workloads, prefer managed stdio or the local Unix control socket.

appServer fields:

Because it alters the Codex sandbox contract, appServer.networkProxy is explicit. When this feature is turned on, OpenClaw also configures features.network_proxy.enabled and default_permissions inside the Codex thread configuration so the resulting permission profile can start Codex-managed networking. OpenClaw automatically creates a collision-resistant openclaw-network-<fingerprint> profile name from the profile body; only use profileName when a consistent local name is necessary.

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",
            },
          },
        },
      },
    },
  },
};

If the normal app-server runtime would be danger-full-access, turning on networkProxy instead applies workspace-style filesystem access for the generated permission profile. Codex-managed network enforcement is sandboxed networking, so a full-access profile would not guard outbound traffic.

The plugin blocks older, newer-unvalidated, prerelease, build-suffixed, or unversioned app-server handshakes. The Codex app-server must report a stable version from 0.143.0 through the bundled 0.145.0.

OpenClaw treats non-loopback WebSocket app-server URLs as remote and requires identity-bearing WebSocket auth through appServer.authToken or an Authorization header. appServer.authToken and each appServer.headers.* value can be a SecretInput; the secrets runtime resolves SecretRefs and env shorthand before OpenClaw builds app-server start options, and unresolved structured SecretRefs fail before any token or header is sent. When native Codex plugins are configured, OpenClaw uses the connected app-server's plugin control plane to install or refresh those plugins and then refreshes app inventory so plugin-owned apps are visible to the Codex thread. app/list is still the authoritative inventory and metadata source, but OpenClaw policy decides whether thread/start sends config.apps[appId].enabled = true for a listed accessible app even if Codex currently marks it disabled. Unknown or missing app ids remain fail-closed; this path only activates marketplace plugins via plugin/install and refreshes inventory. Only connect OpenClaw to remote app-servers that are trusted to accept OpenClaw-managed plugin installs and app inventory refreshes.

Approval and sandbox modes

Local stdio app-server sessions default to YOLO mode: approvalPolicy: "never", approvalsReviewer: "user", and sandbox: "danger-full-access". This trusted local operator posture lets unattended OpenClaw turns and heartbeats make progress without native approval prompts that nobody is around to answer.

If Codex's local system requirements file disallows implicit YOLO approval, reviewer, or sandbox values, OpenClaw treats the implicit default as guardian instead and selects allowed guardian permissions. tools.exec.mode: "auto" also forces guardian-reviewed Codex approvals and does not preserve unsafe legacy approvalPolicy: "never" or sandbox: "danger-full-access" overrides; set tools.exec.mode: "full" for an intentional no-approval posture. Hostname-matching [[remote_sandbox_config]] entries in the same requirements file are honored for the sandbox default decision.

Set appServer.mode: "guardian" for Codex guardian-reviewed approvals:

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

The guardian preset expands to approvalPolicy: "on-request", approvalsReviewer: "auto_review", and sandbox: "workspace-write" when those values are allowed. Individual policy fields override mode. The older guardian_subagent reviewer value is still accepted as a compatibility alias, but new configs should use auto_review.

When an OpenClaw sandbox is active, the local Codex app-server process still runs on the Gateway host. OpenClaw therefore disables Codex native Code Mode, user MCP servers, and app-backed plugin execution for that turn instead of treating Codex host-side sandboxing as equivalent to the OpenClaw sandbox backend. Shell access is exposed through OpenClaw sandbox-backed dynamic tools such as sandbox_exec and sandbox_process when the normal exec/process tools are available.

Note

On Docker-backed OpenClaw sandbox hosts (agents.defaults.sandbox.mode set to a Docker backend), openclaw doctor probes whether the host allows the unprivileged user (and, when Docker sandbox network egress is disabled, network) namespaces that nested Codex bwrap needs for workspace-write shell execution inside the sandbox container. A failed probe usually surfaces as bwrap: setting up uid map: Permission denied or bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted on Ubuntu/AppArmor hosts. Fix the reported host namespace policy for the OpenClaw service user and restart the gateway; prefer a scoped AppArmor profile for the service process over the host-wide kernel.apparmor_restrict_unprivileged_userns=0 fallback, and do not grant broader Docker container privileges just to satisfy nested bwrap.

Sandboxed native execution

The stable default is fail-closed: active OpenClaw sandboxing disables native Codex execution surfaces that would otherwise run from the Codex app-server host. Use appServer.experimental.sandboxExecServer: true only when you want to try Codex's remote environment support with OpenClaw's sandbox backend. This preview path works with every supported Codex app-server version.

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

When this flag is enabled and the current OpenClaw session operates in sandboxed mode, OpenClaw initiates a local loopback exec-server backed by the active sandbox, registers that server with the Codex app-server, then launches the Codex thread and turn using that OpenClaw-managed environment. If the app-server cannot register the environment, the run fails closed rather than silently reverting to host execution.

This preview path works only locally. A remote WebSocket app-server cannot connect to the loopback exec-server unless both run on the same machine, so OpenClaw refuses that combination.

Auth and environment isolation

Within the default per-agent home, authentication follows this priority:

1. An explicit OpenClaw Codex auth profile assigned to the agent.
2. The app-server's existing account inside that agent's Codex home.
3. For local stdio app-server launches exclusively, CODEX_API_KEY, then OPENAI_API_KEY, when no app-server account exists and OpenAI auth remains necessary.

When OpenClaw detects a ChatGPT subscription-style Codex auth profile (OAuth or token credential type), it strips CODEX_API_KEY and OPENAI_API_KEY from the spawned Codex child process. This keeps Gateway-level API keys accessible for embeddings or direct OpenAI models without accidentally billing native Codex app-server turns through the API.

Explicit Codex API-key profiles and local stdio env-key fallback rely on app-server login rather than inherited child-process environment. WebSocket app-server connections do not receive Gateway env API-key fallback; use an explicit auth profile or the remote app-server's own account.

Stdio app-server launches inherit OpenClaw's process environment by default. OpenClaw manages the Codex app-server account bridge and assigns CODEX_HOME to a per-agent directory under that agent's OpenClaw state. This keeps Codex config, accounts, plugin cache and data, and thread state scoped to the OpenClaw agent rather than leaking from the operator's personal ~/.codex home.

Set appServer.homeScope: "user" to share native Codex state with Codex Desktop and the CLI. This local user-home mode supports managed stdio and explicit Unix transport. It uses $CODEX_HOME when set and ~/.codex otherwise, including native auth, config, plugins, and threads. OpenClaw bypasses its auth-profile bridge for the app-server. Verified owner turns can use codex_threads to list (with an optional search filter), read, fork, rename, archive, and unarchive those threads. Fork a thread before continuing it in OpenClaw; independent Codex processes do not coordinate concurrent writers for the same thread.

That homeScope opt-in applies to ordinary harness sessions. A Chat created through Codex Sessions uses its private supervision connection instead, which preserves the native connection's auth and provider configuration for the canonical branch and future resumes.

In a model-locked supervised Chat, codex_threads cannot attach a different fork or archive the Chat's bound native thread. List and metadata-only read remain available. Raw transcript reads require allowRawTranscripts; when it is disabled, list search is also rejected because native search can match transcript previews. Rename, unarchive, detached fork, and archive of an unrelated thread not owned by another OpenClaw Chat require allowWriteControls. Neither option bypasses a locked binding.

OpenClaw does not modify HOME for normal local app-server launches. Codex-run subprocesses such as openclaw, gh, git, cloud CLIs, and shell commands see the normal process home and can find user-home config and tokens. Codex may also discover $HOME/.agents/skills and $HOME/.agents/plugins/marketplace.json; that .agents discovery is intentionally shared with the operator home and is separate from isolated ~/.codex state.

In the default agent scope, OpenClaw plugins and OpenClaw skill snapshots still route through OpenClaw's own plugin registry and skill loader; personal Codex ~/.codex assets do not. If you have useful Codex CLI skills or plugins from a Codex home that should become part of an isolated OpenClaw agent, inventory them explicitly:

openclaw migrate codex --dry-run
openclaw migrate apply codex --yes

If a deployment needs additional environment isolation, add those variables to appServer.clearEnv:

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

appServer.clearEnv only affects the spawned Codex app-server child process. OpenClaw removes CODEX_HOME and HOME from this list during local launch normalization: CODEX_HOME stays pointed at the selected agent or user scope, and HOME stays inherited so subprocesses can use normal user-home state.

Dynamic tools

Codex dynamic tools default to searchable loading, exposed under the openclaw namespace with deferLoading: true. OpenClaw normally does not expose dynamic tools that duplicate Codex-native workspace operations or Codex's own tool-search surface:

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

When a finite runtime allowlist disables native Code Mode, OpenClaw sends an empty execution-environment selection. In that direct, unsandboxed case, OpenClaw keeps its policy-filtered exec and process tools as the shell fallback. Runtime allowlists and codexDynamicToolsExclude still apply.

Most remaining OpenClaw integration tools, such as messaging, media, cron, browser, nodes, gateway, heartbeat_respond, and web_search, are available through Codex tool search under that namespace. This keeps the initial model context smaller. A small set of tools stay directly callable regardless of codexDynamicToolsLoading, because Codex tool search can be unavailable or resolve a connector-only universe: agents_list, sessions_spawn, and sessions_yield. Developer instructions still steer normal Codex subagents toward native spawn_agent for Codex-native subagent work, while sessions_spawn remains available for explicit OpenClaw or ACP delegation. Message-tool-only source replies also stay direct, since that is a turn-control contract.

Codex Code Mode translates generic OpenClaw dynamic-tool results into text. Before reading any fields, parse the JSON output first. The Codex runtime serializes nested dynamic calls, so Promise.all does not send them in parallel; when launching collector children, use a bounded sequential loop.

Tools marked catalogMode: "direct-only", which include the OpenClaw computer tool, are collected under openclaw_direct. OpenClaw appends that namespace to Codex's code_mode.direct_only_tool_namespaces list without overwriting any operator-provided entries. As a result, Codex exposes those tools as DirectModelOnly in both normal and code-mode-only threads, rather than routing them through nested Code Mode tools.* calls. This separation is necessary for results that contain images: nested Code Mode serialization reduces image output to text, which would lose the screenshot required for the next computer action.

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

Timeouts

OpenClaw-owned dynamic tool calls have their own timeout limits separate from appServer.requestTimeoutMs. Each Codex item/tool/call request picks the first available timeout from this priority list:

• A positive per-call timeoutMs argument.
• For image_generate, agents.defaults.mediaModels.image.timeoutMs.
• For image_generate without a configured timeout, the 120 second image-generation default.
• For the media-understanding image tool, the chosen image-capable tools.media.models[] entry's timeoutSeconds converted to milliseconds, or the 60 second media default. For image understanding, this applies to the request itself and is not shortened by earlier preparation steps.
• For the message tool, a fixed 600 second outer budget that covers Gateway delivery and bounded same-key reconciliation.
• The 90 second dynamic-tool default.

This watchdog acts as the outer dynamic item/tool/call budget. Provider-specific request timeouts operate inside that call and follow their own timeout rules. Dynamic tool budgets cannot exceed 600000 ms. agents_wait adds 30000 ms of outer completion grace, and the app-server client allows 660000 ms so the structured wait result can reach Codex. On timeout, OpenClaw aborts the tool signal where supported and sends a failed dynamic-tool response back to Codex, allowing the turn to continue instead of leaving the session in processing.

Once Codex accepts a turn and after OpenClaw responds to a turn-scoped app-server request, the harness expects Codex to make progress on the current turn and eventually complete the native turn with turn/completed. If the app-server stays silent for appServer.turnCompletionIdleTimeoutMs, OpenClaw makes a best-effort attempt to interrupt the Codex turn, logs a diagnostic timeout, and frees the OpenClaw session lane so subsequent chat messages do not queue behind a stale native turn.

Most non-terminal notifications for the same turn disable that short watchdog, because Codex has demonstrated the turn is still active. Tool handoffs use a longer post-tool idle budget: after OpenClaw returns an item/tool/call response, after native tool items such as commandExecution finish, after raw custom_tool_call_output completions, and after post-tool raw assistant progress, raw reasoning completions, or reasoning progress. The guard uses appServer.postToolRawAssistantCompletionIdleTimeoutMs when configured and defaults to five minutes otherwise. That same post-tool budget also extends the progress watchdog during the silent synthesis window before Codex emits the next current-turn event. Reasoning completions, commentary agentMessage completions, and pre-tool raw reasoning or assistant progress can be followed by an automatic final reply, so they use the post-progress reply guard instead of releasing the session lane immediately. Only final or non-commentary completed agentMessage items and pre-tool raw assistant completions activate the assistant-output release: if Codex then goes quiet without turn/completed, OpenClaw makes a best-effort interrupt of the native turn and releases the session lane. Replay-safe stdio app-server failures, including turn-completion idle timeouts without assistant, tool, active-item, or side-effect evidence, are retried once on a fresh app-server attempt. Unsafe timeouts still retire the stuck app-server client and release the OpenClaw session lane. They also clear the stale native thread binding instead of being replayed automatically. Completion-watch timeouts surface Codex-specific timeout text: replay-safe cases indicate the response may be incomplete, while unsafe cases instruct the user to verify current state before retrying. Public timeout diagnostics include structural fields such as the last app-server notification method, raw assistant response item id, type, and role, active request and item counts, and armed watch state. When the last notification is a raw assistant response item, they also include a bounded assistant text preview. They do not include raw prompt or tool content.

Model discovery

By default, the Codex plugin queries the app-server for available models. Model availability is managed by the Codex app-server, so the list can change when OpenClaw upgrades the bundled @openai/codex version or when a deployment points appServer.command at a different Codex binary. Availability can also be scoped to individual accounts. Use /codex models on a running gateway to view the live catalog for that harness and account.

If discovery fails or times out, OpenClaw falls back to a bundled catalog:

Note

The current bundled harness is @openai/codex 0.145.0. A model/list probe against that bundled app-server returned these public picker rows:

Model id	Input modalities	Reasoning efforts
gpt-5.6-sol	text, image	low, medium, high, xhigh, max, ultra
gpt-5.6-terra	text, image	low, medium, high, xhigh, max, ultra
gpt-5.6-luna	text, image	low, medium, high, xhigh, max
gpt-5.5	text, image	low, medium, high, xhigh
gpt-5.2	text, image	low, medium, high, xhigh

The app-server catalog can report ultra; OpenClaw reasoning controls currently expose levels through max.

Live picker rows are scoped to accounts and can change with the account, Codex catalog, or bundled version; run /codex models for the current list rather than relying on any point-in-time table. Hidden models can also appear in the app-server catalog for internal or specialized flows without being normal model-picker choices.

Tune discovery under plugins.entries.codex.config.discovery:

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

Disable discovery when you want startup to avoid probing Codex and use only the fallback catalog:

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

Workspace bootstrap files

Codex handles AGENTS.md itself through native project-doc discovery. OpenClaw does not create synthetic Codex project-doc files or rely on Codex fallback filenames for persona files, because Codex fallbacks only apply when AGENTS.md is missing.

For OpenClaw workspace parity, the Codex harness forwards the other bootstrap files as developer instructions, but not identically:

• TOOLS.md is passed along as inherited developer instructions for Codex, meaning any native Codex subagents created during that turn will also see it.
• SOUL.md, IDENTITY.md, and USER.md are passed along as turn-scoped collaboration instructions. These are not inherited by native Codex subagents, preventing the parent agent's persona and user profile from being picked up during subagent turns.
• The compact list of loaded OpenClaw skills is also forwarded as turn-scoped collaboration developer instructions, so native Codex subagents do not inherit it either.
• HEARTBEAT.md content is not injected; instead, heartbeat turns receive a collaboration-mode pointer to read the file when it exists and is not empty.
• MEMORY.md content from the configured agent workspace is not inserted into native Codex turn input when memory tools are available for that workspace. When present, the harness adds a small workspace-memory pointer to turn-scoped collaboration developer instructions, and Codex should use memory_search or memory_get when durable memory matters. If tools are disabled, memory search is unavailable, or the active workspace differs from the agent memory workspace, MEMORY.md falls back to the standard bounded turn-context path.
• BOOTSTRAP.md, when available, is forwarded as OpenClaw turn input reference context.

Environment overrides

For local testing, environment overrides remain available:

• 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

When appServer.command is not set, OPENCLAW_CODEX_APP_SERVER_BIN skips the managed binary.

OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1 has been removed. Replace it with plugins.entries.codex.config.appServer.mode: "guardian", or use OPENCLAW_CODEX_APP_SERVER_MODE=guardian for a single local test. For repeatable deployments, config is recommended since it keeps the plugin behavior in the same reviewed file as the rest of the Codex harness setup.

Related

• Codex harness
• Codex harness runtime
• Codex supervision
• Native Codex plugins
• Codex Computer Use
• OpenAI provider
• Configuration reference