Codex harness

The bundled

plugin lets OpenClaw run embedded agent turns through the Codex app-server instead of the built-in PI harness.

Use this when you want Codex to own the low-level agent session: model discovery, native thread resume, native compaction, and app-server execution. OpenClaw still owns chat channels, session files, model selection, tools, approvals, media delivery, and the visible transcript mirror.

If you are trying to orient yourself, start with Agent runtimes. The short version is:

is the model ref, is the runtime, and Telegram, Discord, Slack, or another channel remains the communication surface.

Quick config

To use the Codex harness for GPT agent turns, keep the model ref canonical as

, enable the bundled plugin, and set :

json5
Copy
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
        fallback: "none",
      },
    },
  },
}

If your config uses

, include there too:

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

Do not use

for this path. That selects Codex OAuth through the normal PI runner unless you separately force a runtime. Config changes apply to new or reset sessions; existing sessions keep their recorded runtime.

What this plugin changes

The bundled

plugin contributes several separate capabilities:

Enabling the plugin makes those capabilities available. It does not:

• start using Codex for every OpenAI model
• convert
  text

  Copy

  openai-codex/*
  model refs into the native runtime
• make ACP/acpx the default Codex path
• hot-switch existing sessions that already recorded a PI runtime
• replace OpenClaw channel delivery, session files, auth-profile storage, or message routing

The same plugin also owns the native

chat-control command surface. If the plugin is enabled and the user asks to bind, resume, steer, stop, or inspect Codex threads from chat, agents should prefer over ACP. ACP remains the explicit fallback when the user asks for ACP/acpx or is testing the ACP Codex adapter.

Native Codex turns keep OpenClaw plugin hooks as the public compatibility layer. These are in-process OpenClaw hooks, not Codex

command hooks:

• text

  Copy

  before_prompt_build
• text

  Copy

  before_compaction
  ,
  text

  Copy

  after_compaction
• text

  Copy

  llm_input
  ,
  text

  Copy

  llm_output
• text

  Copy

  before_tool_call
  ,
  text

  Copy

  after_tool_call
• text

  Copy

  before_message_write
  for mirrored transcript records
• text

  Copy

  before_agent_finalize
  through Codex
  text

  Copy

  Stop
  relay
• text

  Copy

  agent_end

Plugins can also register runtime-neutral tool-result middleware to rewrite OpenClaw dynamic tool results after OpenClaw executes the tool and before the result is returned to Codex. This is separate from the public

plugin hook, which transforms OpenClaw-owned transcript tool-result writes.

For the plugin hook semantics themselves, see Plugin hooks and Plugin guard behavior.

The harness is off by default. New configs should keep OpenAI model refs canonical as

and explicitly force or when they want native app-server execution. Legacy model refs still auto-select the harness for compatibility, but runtime-backed legacy provider prefixes are not shown as normal model/provider choices.

If the

plugin is enabled but the primary model is still , warns instead of changing the route. That is intentional: remains the PI Codex OAuth/subscription path, and native app-server execution stays an explicit runtime choice.

Route map

Use this table before changing config:

The important split is provider versus runtime:

• text

  Copy

  openai-codex/*
  answers "which provider/auth route should PI use?"
• text

  Copy

  agentRuntime.id: "codex"
  answers "which loop should execute this embedded turn?"
• text

  Copy

  /codex ...
  answers "which native Codex conversation should this chat bind or control?"
• ACP answers "which external harness process should acpx launch?"

Pick the right model prefix

OpenAI-family routes are prefix-specific. Use

when you want Codex OAuth through PI; use when you want direct OpenAI API access or when you are forcing the native Codex app-server harness:

GPT-5.5 is currently subscription/OAuth-only in OpenClaw. Use

for PI OAuth, or with the Codex app-server harness. Direct API-key access for is supported once OpenAI enables GPT-5.5 on the public API.

Legacy

refs remain accepted as compatibility aliases. Doctor compatibility migration rewrites legacy primary runtime refs to canonical model refs and records the runtime policy separately, while fallback-only legacy refs are left unchanged because runtime is configured for the whole agent container. New PI Codex OAuth configs should use ; new native app-server harness configs should use plus .

follows the same prefix split. Use when image understanding should run through the OpenAI Codex OAuth provider path. Use when image understanding should run through a bounded Codex app-server turn. The Codex app-server model must advertise image input support; text-only Codex models fail before the media turn starts.

Use

to confirm the effective harness for the current session. If the selection is surprising, enable debug logging for the subsystem and inspect the gateway's structured record. It includes the selected harness id, selection reason, runtime/fallback policy, and, in mode, each plugin candidate's support result.

What doctor warnings mean

warns when all of these are true:

• the bundled
  text

  Copy

  codex
  plugin is enabled or allowed
• an agent's primary model is
  text

  Copy

  openai-codex/*
• that agent's effective runtime is not
  text

  Copy

  codex

That warning exists because users often expect "Codex plugin enabled" to imply "native Codex app-server runtime." OpenClaw does not make that leap. The warning means:

• No change is required if you intended ChatGPT/Codex OAuth through PI.
• Change the model to
  text

  Copy

  openai/<model>
  and set
  text

  Copy

  agentRuntime.id: "codex"
  if you intended native app-server execution.
• Existing sessions still need
  text

  Copy

  /new
  or
  text

  Copy

  /reset
  after a runtime change, because session runtime pins are sticky.

Harness selection is not a live session control. When an embedded turn runs, OpenClaw records the selected harness id on that session and keeps using it for later turns in the same session id. Change

config or when you want future sessions to use another harness; use or to start a fresh session before switching an existing conversation between PI and Codex. This avoids replaying one transcript through two incompatible native session systems.

Legacy sessions created before harness pins are treated as PI-pinned once they have transcript history. Use

or to opt that conversation into Codex after changing config.

shows the effective model runtime. The default PI harness appears as , and the Codex app-server harness appears as .

Requirements

• OpenClaw with the bundled
  text

  Copy

  codex
  plugin available.
• Codex app-server
  text

  Copy

  0.125.0
  or newer. The bundled plugin manages a compatible Codex app-server binary by default, so local
  text

  Copy

  codex
  commands on
  text

  Copy

  PATH
  do not affect normal harness startup.
• Codex auth available to the app-server process or to OpenClaw's Codex auth bridge. Local app-server launches use an OpenClaw-managed Codex home for each agent and an isolated child
  text

  Copy

  HOME
  , so they do not read your personal
  text

  Copy

  ~/.codex
  account, skills, plugins, config, thread state, or native
  text

  Copy

  $HOME/.agents/skills
  by default.

The plugin blocks older or unversioned app-server handshakes. That keeps OpenClaw on the protocol surface it has been tested against.

For live and Docker smoke tests, auth usually comes from the Codex CLI account or an OpenClaw

auth profile. Local stdio app-server launches can also fall back to / when no account is present.

Add Codex alongside other models

Do not set

globally if the same agent should freely switch between Codex and non-Codex provider models. A forced runtime applies to every embedded turn for that agent or session. If you select an Anthropic model while that runtime is forced, OpenClaw still tries the Codex harness and fails closed instead of silently routing that turn through PI.

Use one of these shapes instead:

• Put Codex on a dedicated agent with
  text

  Copy

  agentRuntime.id: "codex"
  .
• Keep the default agent on
  text

  Copy

  agentRuntime.id: "auto"
  and PI fallback for normal mixed provider usage.
• Use legacy
  text

  Copy

  codex/*
  refs only for compatibility. New configs should prefer
  text

  Copy

  openai/*
  plus an explicit Codex runtime policy.

For example, this keeps the default agent on normal automatic selection and adds a separate Codex agent:

json5
Copy
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      agentRuntime: {
        id: "auto",
        fallback: "pi",
      },
    },
    list: [
      {
        id: "main",
        default: true,
        model: "anthropic/claude-opus-4-6",
      },
      {
        id: "codex",
        name: "Codex",
        model: "openai/gpt-5.5",
        agentRuntime: {
          id: "codex",
        },
      },
    ],
  },
}

With this shape:

• The default
  text

  Copy

  main
  agent uses the normal provider path and PI compatibility fallback.
• The
  text

  Copy

  codex
  agent uses the Codex app-server harness.
• If Codex is missing or unsupported for the
  text

  Copy

  codex
  agent, the turn fails instead of quietly using PI.

Agent command routing

Agents should route user requests by intent, not by the word "Codex" alone:

OpenClaw only advertises ACP spawn guidance to agents when ACP is enabled, dispatchable, and backed by a loaded runtime backend. If ACP is not available, the system prompt and plugin skills should not teach the agent about ACP routing.

Codex-only deployments

Force the Codex harness when you need to prove that every embedded agent turn uses Codex. Explicit plugin runtimes default to no PI fallback, so

is optional but often useful as documentation:

json5
Copy
{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
        fallback: "none",
      },
    },
  },
}

Environment override:

bash
Copy
OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run

With Codex forced, OpenClaw fails early if the Codex plugin is disabled, the app-server is too old, or the app-server cannot start. Set

only if you intentionally want PI to handle missing harness selection.

Per-agent Codex

You can make one agent Codex-only while the default agent keeps normal auto-selection:

json5
Copy
{
  agents: {
    defaults: {
      agentRuntime: {
        id: "auto",
        fallback: "pi",
      },
    },
    list: [
      {
        id: "main",
        default: true,
        model: "anthropic/claude-opus-4-6",
      },
      {
        id: "codex",
        name: "Codex",
        model: "openai/gpt-5.5",
        agentRuntime: {
          id: "codex",
          fallback: "none",
        },
      },
    ],
  },
}

Use normal session commands to switch agents and models.

creates a fresh OpenClaw session and the Codex harness creates or resumes its sidecar app-server thread as needed. clears the OpenClaw session binding for that thread and lets the next turn resolve the harness from current config again.

Model discovery

By default, the Codex plugin asks the app-server for available models. If discovery fails or times out, it uses a bundled fallback catalog for:

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

You can tune discovery under

:

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

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

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

App-server connection and policy

By default, the plugin starts OpenClaw's managed Codex binary locally with:

bash
Copy
codex app-server --listen stdio://

The managed binary is declared as a bundled plugin runtime dependency and staged with the rest of the

plugin dependencies. This keeps the app-server version tied to the bundled plugin instead of whichever separate Codex CLI happens to be installed locally. Set only when you intentionally want to run a different executable.

By default, OpenClaw starts local Codex harness sessions in YOLO mode:

, , and . This is the trusted local operator posture used for autonomous heartbeats: Codex can use shell and network tools without stopping on native approval prompts that nobody is around to answer.

To opt in to Codex guardian-reviewed approvals, set

:

json5
Copy
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            mode: "guardian",
            serviceTier: "fast",
          },
        },
      },
    },
  },
}

Guardian mode uses Codex's native auto-review approval path. When Codex asks to leave the sandbox, write outside the workspace, or add permissions like network access, Codex routes that approval request to the native reviewer instead of a human prompt. The reviewer applies Codex's risk framework and approves or denies the specific request. Use Guardian when you want more guardrails than YOLO mode but still need unattended agents to make progress.

The

preset expands to , , and . Individual policy fields still override , so advanced deployments can mix the preset with explicit choices. The older reviewer value is still accepted as a compatibility alias, but new configs should use .

For an already-running app-server, use WebSocket transport:

json5
Copy
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            transport: "websocket",
            url: "ws://127.0.0.1:39175",
            authToken: "${CODEX_APP_SERVER_TOKEN}",
            requestTimeoutMs: 60000,
          },
        },
      },
    },
  },
}

Stdio app-server launches inherit OpenClaw's process environment by default, but OpenClaw owns the Codex app-server account bridge and sets both

and to per-agent directories under that agent's OpenClaw state. Codex's own skill loader reads and , so both values are isolated for local app-server launches. That keeps Codex-native skills, plugins, config, accounts, and thread state scoped to the OpenClaw agent instead of leaking in from the operator's personal Codex CLI home.

OpenClaw plugins and OpenClaw skill snapshots still flow through OpenClaw's own plugin registry and skill loader. Personal Codex CLI assets do not. If you have useful Codex CLI skills or plugins that should become part of an OpenClaw agent, inventory them explicitly:

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

The Codex migration provider copies skills into the current OpenClaw agent workspace. Codex native plugins, hooks, and config files are reported or archived for manual review instead of being activated automatically, because they can execute commands, expose MCP servers, or carry credentials.

Auth is selected in this order:

1. An explicit OpenClaw Codex auth profile for the agent.
2. The app-server's existing account in that agent's Codex home.
3. For local stdio app-server launches only,
   text

   Copy

   CODEX_API_KEY
   , then
   text

   Copy

   OPENAI_API_KEY
   , when no app-server account is present and OpenAI auth is still required.

When OpenClaw sees a ChatGPT subscription-style Codex auth profile, it removes

and from the spawned Codex child process. That keeps Gateway-level API keys available for embeddings or direct OpenAI models without making native Codex app-server turns bill through the API by accident. Explicit Codex API-key profiles and local stdio env-key fallback use app-server login instead of inherited child-process env. 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.

If a deployment needs additional environment isolation, add those variables to

:

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

only affects the spawned Codex app-server child process.

Supported

fields:

OpenClaw-owned dynamic tool calls are bounded independently from

: each Codex request must receive an OpenClaw response within 30 seconds. On timeout, OpenClaw aborts the tool signal where supported and returns a failed dynamic-tool response to Codex so the turn can continue instead of leaving the session in .

After OpenClaw responds to a Codex turn-scoped app-server request, the harness also expects Codex to finish the native turn with

. If the app-server goes quiet for 60 seconds after that response, OpenClaw best-effort interrupts the Codex turn, records a diagnostic timeout, and releases the OpenClaw session lane so follow-up chat messages are not queued behind a stale native turn.

Environment overrides remain available for local testing:

• text

  Copy

  OPENCLAW_CODEX_APP_SERVER_BIN
• text

  Copy

  OPENCLAW_CODEX_APP_SERVER_ARGS
• text

  Copy

  OPENCLAW_CODEX_APP_SERVER_MODE=yolo|guardian
• text

  Copy

  OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY
• text

  Copy

  OPENCLAW_CODEX_APP_SERVER_SANDBOX

bypasses the managed binary when is unset.

was removed. Use instead, or for one-off local testing. Config is preferred for repeatable deployments because it keeps the plugin behavior in the same reviewed file as the rest of the Codex harness setup.

Computer use

Computer Use is covered in its own setup guide: Codex Computer Use.

The short version: OpenClaw does not vendor the desktop-control app or execute desktop actions itself. It prepares Codex app-server, verifies that the

MCP server is available, and then lets Codex handle the native MCP tool calls during Codex-mode turns.

For direct TryCua driver access outside the Codex marketplace flow, register

with . See Codex Computer Use for the distinction between Codex-owned Computer Use and direct MCP registration.

Minimal config:

json5
Copy
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          computerUse: {
            autoInstall: true,
          },
        },
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
        fallback: "none",
      },
    },
  },
}

The setup can be checked or installed from the command surface:

• text

  Copy

  /codex computer-use status
• text

  Copy

  /codex computer-use install
• text

  Copy

  /codex computer-use install --source <marketplace-source>
• text

  Copy

  /codex computer-use install --marketplace-path <path>

Computer Use is macOS-specific and may require local OS permissions before the Codex MCP server can control apps. If

is true and the MCP server is unavailable, Codex-mode turns fail before the thread starts instead of silently running without the native Computer Use tools. See Codex Computer Use for marketplace choices, remote catalog limits, status reasons, and troubleshooting.

When

is true, OpenClaw can register the standard bundled Codex Desktop marketplace from if Codex has not discovered a local marketplace yet. Use or after changing runtime or Computer Use config so existing sessions do not keep an old PI or Codex thread binding.

Common recipes

Local Codex with default stdio transport:

json5
Copy
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}

Codex-only harness validation:

json5
Copy
{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
      },
    },
  },
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}

Guardian-reviewed Codex approvals:

json5
Copy
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            mode: "guardian",
            approvalPolicy: "on-request",
            approvalsReviewer: "auto_review",
            sandbox: "workspace-write",
          },
        },
      },
    },
  },
}

Remote app-server with explicit headers:

json5
Copy
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            transport: "websocket",
            url: "ws://gateway-host:39175",
            headers: {
              "X-OpenClaw-Agent": "main",
            },
          },
        },
      },
    },
  },
}

Model switching stays OpenClaw-controlled. When an OpenClaw session is attached to an existing Codex thread, the next turn sends the currently selected OpenAI model, provider, approval policy, sandbox, and service tier to app-server again. Switching from

to keeps the thread binding but asks Codex to continue with the newly selected model.

Codex command

The bundled plugin registers

as an authorized slash command. It is generic and works on any channel that supports OpenClaw text commands.

Common forms:

• text

  Copy

  /codex status
  shows live app-server connectivity, models, account, rate limits, MCP servers, and skills.
• text

  Copy

  /codex models
  lists live Codex app-server models.
• text

  Copy

  /codex threads [filter]
  lists recent Codex threads.
• text

  Copy

  /codex resume <thread-id>
  attaches the current OpenClaw session to an existing Codex thread.
• text

  Copy

  /codex compact
  asks Codex app-server to compact the attached thread.
• text

  Copy

  /codex review
  starts Codex native review for the attached thread.
• text

  Copy

  /codex diagnostics [note]
  asks before sending Codex diagnostics feedback for the attached thread.
• text

  Copy

  /codex computer-use status
  checks the configured Computer Use plugin and MCP server.
• text

  Copy

  /codex computer-use install
  installs the configured Computer Use plugin and reloads MCP servers.
• text

  Copy

  /codex account
  shows account and rate-limit status.
• text

  Copy

  /codex mcp
  lists Codex app-server MCP server status.
• text

  Copy

  /codex skills
  lists Codex app-server skills.

Common debugging workflow

When a Codex-backed agent does something surprising in Telegram, Discord, Slack, or another channel, start with the conversation where the problem happened:

1. Run
   text

   Copy

   /diagnostics bad tool choice after image upload
   or another short note that describes what you saw.
2. Approve the diagnostics request once. The approval creates the local Gateway diagnostics zip and, because the session is using the Codex harness, also sends the relevant Codex feedback bundle to OpenAI servers.
3. Copy the completed diagnostics reply into the bug report or support thread. It includes the local bundle path, privacy summary, OpenClaw session ids, Codex thread ids, and an
   text

   Copy

   Inspect locally
   line for each Codex thread.
4. If you want to debug the run yourself, run the printed
   text

   Copy

   Inspect locally
   command in a terminal. It looks like
   text

   Copy

   codex resume <thread-id>
   and opens the native Codex thread so you can inspect the conversation, continue it locally, or ask Codex why it chose a particular tool or plan.

Use

only when you specifically want the Codex feedback upload for the currently attached thread without the full OpenClaw Gateway diagnostics bundle. For most support reports, is the better starting point because it ties the local Gateway state and Codex thread ids together in one reply. See Diagnostics export for the full privacy model and group-chat behavior.

Core OpenClaw also exposes owner-only

as the general Gateway diagnostics command. Its approval prompt shows the sensitive-data preamble, links to Diagnostics Export, and requests through explicit exec approval every time. Do not approve diagnostics with an allow-all rule. After approval, OpenClaw sends a pasteable report with the local bundle path and manifest summary. When the active OpenClaw session is using the Codex harness, that same approval also authorizes sending the relevant Codex feedback bundles to OpenAI servers. The approval prompt says that Codex feedback will be sent, but it does not list Codex session or thread ids before approval.

If

is invoked by an owner in a group chat, OpenClaw keeps the shared channel clean: the group receives only a short notice, while the diagnostics preamble, approval prompts, and Codex session/thread ids are sent to the owner through the private approval route. If there is no private owner route, OpenClaw refuses the group request and asks the owner to run it from a DM.

The approved Codex upload calls Codex app-server

and asks app-server to include logs for each listed thread and spawned Codex subthreads when available. The upload goes through Codex's normal feedback path to OpenAI servers; if Codex feedback is disabled in that app-server, the command returns the app-server error. The completed diagnostics reply lists the channels, OpenClaw session ids, Codex thread ids, and local commands for the threads that were sent. If you deny or ignore the approval, OpenClaw does not print those Codex ids. This upload does not replace the local Gateway diagnostics export.

writes the same sidecar binding file that the harness uses for normal turns. On the next message, OpenClaw resumes that Codex thread, passes the currently selected OpenClaw model into app-server, and keeps extended history enabled.

Inspect a Codex thread from the CLI

The fastest way to understand a bad Codex run is often to open the native Codex thread directly:

sh
Copy
codex resume <thread-id>

Use this when you notice a bug in a channel conversation and want to inspect the problematic Codex session, continue it locally, or ask Codex why it made a particular tool or reasoning choice. The easiest path is usually to run

first: after you approve it, the completed report lists each Codex thread and prints an command, for example . You can copy that command directly into a terminal.

You can also get a thread id from

for the current chat or for recent Codex app-server threads, then run the same command in your shell.

The command surface requires Codex app-server

or newer. Individual control methods are reported as if a future or custom app-server does not expose that JSON-RPC method.

Hook boundaries

The Codex harness has three hook layers:

OpenClaw does not use project or global Codex

files to route OpenClaw plugin behavior. For the supported native tool and permission bridge, OpenClaw injects per-thread Codex config for , , , and . Other Codex hooks such as and remain Codex-level controls; they are not exposed as OpenClaw plugin hooks in the v1 contract.

For OpenClaw dynamic tools, OpenClaw executes the tool after Codex asks for the call, so OpenClaw fires the plugin and middleware behavior it owns in the harness adapter. For Codex-native tools, Codex owns the canonical tool record. OpenClaw can mirror selected events, but it cannot rewrite the native Codex thread unless Codex exposes that operation through app-server or native hook callbacks.

Compaction and LLM lifecycle projections come from Codex app-server notifications and OpenClaw adapter state, not native Codex hook commands. OpenClaw's

, , , and events are adapter-level observations, not byte-for-byte captures of Codex's internal request or compaction payloads.

Codex native

and app-server notifications are projected as agent events for trajectory and debugging. They do not invoke OpenClaw plugin hooks.

V1 support contract

Codex mode is not PI with a different model call underneath. Codex owns more of the native model loop, and OpenClaw adapts its plugin and session surfaces around that boundary.

Supported in Codex runtime v1:

Not supported in Codex runtime v1:

Tools, media, and compaction

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

OpenClaw still builds the tool list and receives dynamic tool results from the harness. Text, images, video, music, TTS, approvals, and messaging-tool output continue through the normal OpenClaw delivery path.

The native hook relay is intentionally generic, but the v1 support contract is limited to the Codex-native tool and permission paths that OpenClaw tests. In the Codex runtime, that includes shell, patch, and MCP

, , and payloads. Do not assume every future Codex hook event is an OpenClaw plugin surface until the runtime contract names it.

For

, OpenClaw only returns explicit allow or deny decisions when policy decides. A no-decision result is not an allow. Codex treats it as no hook decision and falls through to its own guardian or user approval path.

Codex MCP tool approval elicitations are routed through OpenClaw's plugin approval flow when Codex marks

as . Codex prompts are sent back to the originating chat, and the next queued follow-up message answers that native server request instead of being steered as extra context. Other MCP elicitation requests still fail closed.

Active-run queue steering maps onto Codex app-server

. With the default , OpenClaw batches queued chat messages for the configured quiet window and sends them as one request in arrival order. Legacy mode sends separate requests. Codex review and manual compaction turns can reject same-turn steering, in which case OpenClaw uses the followup queue when the selected mode allows fallback. See Steering queue.

When the selected model uses the Codex harness, native thread compaction is delegated to Codex app-server. OpenClaw keeps a transcript mirror for channel history, search,

, , and future model or harness switching. The mirror includes the user prompt, final assistant text, and lightweight Codex reasoning or plan records when the app-server emits them. Today, OpenClaw only records native compaction start and completion signals. It does not yet expose a human-readable compaction summary or an auditable list of which entries Codex kept after compaction.

Because Codex owns the canonical native thread,

does not currently rewrite Codex-native tool result records. It only applies when OpenClaw is writing an OpenClaw-owned session transcript tool result.

Media generation does not require PI. Image, video, music, PDF, TTS, and media understanding continue to use the matching provider/model settings such as

, , , and .

Troubleshooting

Codex does not appear as a normal

provider: that is expected for new configs. Select an model with (or a legacy ref), enable , and check whether excludes .

OpenClaw uses PI instead of Codex:

can still use PI as the compatibility backend when no Codex harness claims the run. Set to force Codex selection while testing. A forced Codex runtime now fails instead of falling back to PI unless you explicitly set . Once Codex app-server is selected, its failures surface directly without extra fallback config.

The app-server is rejected: upgrade Codex so the app-server handshake reports version

or newer. Same-version prereleases or build-suffixed versions such as or are rejected because the stable protocol floor is what OpenClaw tests.

Model discovery is slow: lower

or disable discovery.

WebSocket transport fails immediately: check

, , and that the remote app-server speaks the same Codex app-server protocol version.

A non-Codex model uses PI: that is expected unless you forced

for that agent or selected a legacy ref. Plain and other provider refs stay on their normal provider path in mode. If you force , every embedded turn for that agent must be a Codex-supported OpenAI model.

Computer Use is installed but tools do not run: check

from a fresh session. If a tool reports , use or ; if it persists, restart the gateway to clear stale native hook registrations. If times out, restart Codex Computer Use or Codex Desktop and retry.

Related

• Agent harness plugins
• Agent runtimes
• Model providers
• OpenAI provider
• Status
• Plugin hooks
• Configuration reference
• Testing