Codex harness troubleshooting

Symptoms, causes, and fixes for the Codex app-server harness. Part of the Codex harness guide; Where each section moved lists every section.

Troubleshooting

Codex does not appear as a normal /model provider: expected for new configs. Select an openai/gpt-* model, enable plugins.entries.codex.enabled, and check whether plugins.allow excludes codex.

OpenClaw uses the built-in harness instead of Codex: confirm the effective route is an exact official HTTPS Platform Responses or ChatGPT Responses route, has no authored provider request override, and that the Codex plugin is installed and enabled. Affirmative reasoning support and native reasoning-effort metadata do not count as request overrides. Headers, request parameters, timeouts, and payload compatibility switches still do: Codex declares an OpenClaw fallback that preserves the exact request, including for explicit runtime selections. Other unsupported routes/authentication and missing explicit harnesses fail closed. The openai/gpt-* prefix and agentRuntime.id: "codex" alone are not execution proof; inspect the actual harness in the completed result. See Runtime selection.

OpenAI Codex runtime falls back to the API-key path: collect a redacted gateway excerpt that shows the model, runtime, selected provider, and failure. Ask affected collaborators to run this read-only command on their OpenClaw host:

(  pattern='openai/gpt-5\.[45]|openai[-]codex|agentRuntime(\.id)?|harnessRuntime|Runtime: OpenAI Codex|legacy OpenAI Codex prefix|resolveSelectedOpenAIRuntimeProvider|candidateProvider[": ]+openai|status[": ]+401|Incorrect API key|No API key|api-key path|API-key path|OAuth'   if ls /tmp/openclaw/openclaw-*.log >/dev/null 2>&1; then    grep -E -i -n "$pattern" /tmp/openclaw/openclaw-*.log 2>/dev/null || true  else    journalctl --user -u openclaw-gateway --since today --no-pager 2>/dev/null \      | grep -E -i "$pattern" || true  fi) | sed -E \    -e 's/(Authorization: Bearer )[A-Za-z0-9._~+\/-]+/\1[REDACTED]/Ig' \    -e 's/(Bearer )[A-Za-z0-9._~+\/-]+/\1[REDACTED]/Ig' \    -e 's/(api[_ -]?key[=: ]+)[^ ,}"]+/\1[REDACTED]/Ig' \    -e 's/(OPENAI_API_KEY[=: ]+)[^ ,}"]+/\1[REDACTED]/Ig' \    -e 's/sk-[A-Za-z0-9_-]{12,}/sk-[REDACTED]/g' \    -e 's/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/[EMAIL-REDACTED]/g' \  | tail -200

Useful excerpts usually include openai/gpt-5.6-sol or openai/gpt-5.6-luna, Runtime: OpenAI Codex, agentRuntime.id or harnessRuntime, candidateProvider: "openai", and a 401, Incorrect API key, or No API key result. A corrected run should show the OpenAI OAuth path instead of a plain OpenAI API-key failure.

Legacy Codex model refs config remains: run openclaw doctor --fix. Doctor rewrites legacy model refs to openai/*, removes stale session and whole-agent runtime pins, and preserves existing auth-profile overrides.

The app-server is rejected: use Codex 0.149.0 or newer. Older, malformed, and unversioned servers are rejected. Newer semantic versions continue with a compatibility warning and normal runtime validation against the Codex version OpenClaw ships. Update or remove custom, remote, or desktop binary overrides that select another version.

/codex status cannot connect: check that the codex plugin is enabled, that plugins.allow includes it when an allowlist is configured, and that any custom appServer.command, url, authToken, or headers are valid.

The Codex app-server uses too much memory: distinguish the two processes first. OpenClaw runs the local Codex app-server as a separate Rust child. NODE_OPTIONS=--max-old-space-size=... changes only the Gateway's Node.js V8 heap; it does not cap or enlarge Codex. Managed Gateway installs already choose an adaptive V8 heap, and raising it can leave less host memory for Codex. Use Gateway memory troubleshooting for Gateway pressure, and inspect host or container memory for the Codex child.

The bundled Codex has no heap or RSS limit and no configurable idle-unload delay. After the last client unsubscribes, an inactive thread can remain loaded for up to 30 minutes. OpenClaw independently keeps up to 64 idle conversation threads subscribed on each Codex app-server for 30 minutes after their last activity. This preserves warm sessions and session-scoped approvals when several conversations alternate. Active turns and parents with unfinished native subagents are protected from idle eviction; session reset or deletion releases its own thread immediately. Idle-limit eviction unsubscribes the least recently used conversation, after which Codex applies its separate unloading delay and a later resumed session can require approvals again.

On constrained hosts, reduce native Codex subagent fan-out before increasing the Gateway heap:

{  plugins: {    entries: {      codex: {        config: {          appServer: {            args: ["-c", "agents.max_threads=3", "app-server", "--listen", "stdio://"],          },        },      },    },  },}

That setting limits native child threads for the bundled Codex default multi-agent backend. If you explicitly enable Codex multi-agent v2, use features.multi_agent_v2.max_concurrent_threads_per_session=3 instead; the v2 limit includes the root thread and cannot be combined with agents.max_threads. For more Codex headroom, increase the host, container, or cgroup memory allocation. An OS hard limit can terminate Codex rather than backpressure it.

Model discovery is slow: lower plugins.entries.codex.config.discovery.timeoutMs or disable discovery. See Codex harness reference.

Codex plugin state has reached its row limit: run openclaw doctor to check for bindings left behind by deleted or expired OpenClaw sessions. Stop the Gateway, then run openclaw doctor --fix to remove proven orphaned session bindings after session repair. Doctor preserves supervised bindings, active leases, ambiguous ownership, and bindings whose session store cannot be read. This cleanup does not delete native Codex thread history or managed-thread advisory records.

WebSocket transport fails immediately: check appServer.url, authToken, headers, and that the remote app-server speaks the same Codex app-server protocol version. Codex WebSocket transport remains experimental and unsupported; prefer managed stdio or the local Unix control socket.

Native shell or patch tools are blocked with Native hook relay unavailable: the Codex thread is still trying to use a native hook relay id that OpenClaw no longer has registered. This is a native Codex hook transport problem, not an ACP backend, provider, GitHub, or shell-command failure. Start a fresh session in the affected chat with /new or /reset, then retry a harmless command. If that works once but the next native tool call fails again, treat /new as a temporary workaround only: copy the prompt into a fresh session after restarting the Codex app-server or OpenClaw Gateway so old threads are dropped and native hook registrations are recreated.

Codex tool calls create too many short-lived hook processes: set plugins.entries.codex.config.appServer.loopDetectionPreToolUseRelay: false and restart the gateway. This disables only the Codex PreToolUse subprocess used for OpenClaw loop detection and its no-policy marker. Required before_tool_call and trusted-tool policy relays remain enabled.

A non-Codex model uses the built-in harness: expected unless provider or model runtime policy routes it to another harness. Plain non-OpenAI provider refs stay on their normal provider path in auto mode.

Computer Use is installed but tools do not run: check /codex computer-use status from a fresh session. If a tool reports Native hook relay unavailable, use the native hook relay recovery above. See Codex Computer Use.