Codex harness

The bundled codex plugin lets OmeniaClaw run embedded OpenAI agent turns through Codex app-server instead of the built-in OmeniaClaw harness.

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

The normal setup uses canonical OpenAI model refs such as openai/gpt-5.5. Do not configure legacy Codex GPT refs. Put OpenAI agent auth order under auth.order.openai; older legacy Codex auth profile ids and legacy Codex auth order entries are legacy state repaired by OmeniaClaw doctor --fix.

When no OmeniaClaw sandbox is active, OmeniaClaw starts Codex app-server threads with Codex native code mode enabled while leaving code-mode-only off by default. That keeps Codex native workspace and code capabilities available while OmeniaClaw dynamic tools continue through the app-server item/tool/call bridge. Active OmeniaClaw sandboxing and restricted tool policies disable native code mode entirely unless you opt into the experimental sandbox exec-server path.

This Codex-native feature is separate from OmeniaClaw code mode, which is an opt-in QuickJS-WASI runtime for generic OmeniaClaw runs with a different exec input shape.

For the broader model/provider/runtime split, start with Agent runtimes. The short version is: openai/gpt-5.5 is the model ref, codex is the runtime, and Telegram, Discord, Slack, or another channel remains the communication surface.

Requirements

• OmeniaClaw with the bundled codex plugin available.
• If your config uses plugins.allow, include codex.
• Codex app-server 0.125.0 or newer. The bundled plugin manages a compatible Codex app-server binary by default, so local codex commands on PATH do not affect normal harness startup.
• Codex auth available through OmeniaClaw models auth login --provider openai, an app-server account 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 all config fields, see Codex harness reference.

Quickstart

Most users who want Codex in OmeniaClaw want this path: sign in with a ChatGPT/Codex subscription, enable the bundled codex plugin, and use a canonical openai/gpt-* model ref.

Sign in with Codex OAuth:

OmeniaClaw models auth login --provider openai

Enable the bundled codex plugin and select an OpenAI agent model:

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

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

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

Restart the gateway after changing plugin config. If an existing chat already has a session, use /new or /reset before testing runtime changes so the next turn resolves the harness from current config.

Configuration

The quickstart config is the minimum viable Codex harness config. Set Codex harness options in OmeniaClaw config, and use the CLI only for Codex auth:

Use openai/gpt-* model refs for Codex-backed OpenAI agent turns. Prefer auth.order.openai for subscription-first/API-key-backup ordering. Existing legacy Codex auth profile ids and legacy Codex auth order are doctor-only legacy state; do not write new legacy Codex GPT refs.

Do not set compaction.model or compaction.provider on Codex-backed agents. Codex compacts through its native app-server thread state, so OmeniaClaw ignores those local summarizer overrides at runtime and OmeniaClaw doctor --fix removes them when the agent uses Codex.

Lossless remains supported as a context engine for assembly, ingestion, and maintenance around Codex turns. Configure it through plugins.slots.contextEngine: "lossless-claw" and plugins.entries.lossless-claw.config.summaryModel, not through agents.defaults.compaction.provider. OmeniaClaw doctor --fix migrates the old compaction.provider: "lossless-claw" shape to the Lossless context-engine slot when Codex is the active runtime, but native Codex still owns compaction.

The native Codex app-server harness supports context engines that require pre-prompt assembly. Generic CLI backends, including codex-cli, do not provide that host capability.

For Codex-backed agents, /compact starts native Codex app-server compaction on the bound thread. OmeniaClaw does not wait for completion, impose an OmeniaClaw timeout, restart the shared app-server, or fall back to a context-engine or public OpenAI summarizer. If the native Codex thread binding is missing or stale, the command fails closed so the operator sees the real runtime boundary instead of silently switching compaction backends.

{  auth: {    order: {      openai: ["openai:[email protected]", "openai:api-key-backup"],    },  },}

In that shape, both profiles still run through Codex for openai/gpt-* agent turns. The API key is only an auth fallback, not a request to switch to OmeniaClaw or plain OpenAI Responses.

The rest of this page covers common variants users must choose between: deployment shape, fail-closed routing, guardian approval policy, native Codex plugins, and Computer Use. For full option lists, defaults, enums, discovery, environment isolation, timeouts, and app-server transport fields, see Codex harness reference.

Verify Codex runtime

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

Runtime: OpenAI Codex

Then check Codex app-server state:

/codex status/codex models

/codex status reports app-server connectivity, account, rate limits, MCP servers, and skills. /codex models lists the live Codex app-server catalog for the harness and account. If /status is surprising, see Troubleshooting.

Routing and model selection

Keep provider refs and runtime policy separate:

• Use openai/gpt-* for OpenAI agent turns through Codex.
• Do not use legacy Codex GPT refs in config. Run OmeniaClaw doctor --fix to repair legacy refs and stale session route pins.
• agentRuntime.id: "codex" is optional for normal OpenAI auto mode, but useful when a deployment should fail closed if Codex is unavailable.
• agentRuntime.id: "OmeniaClaw" opts a provider or model into the OmeniaClaw embedded runtime when that is intentional.
• /codex ... controls native Codex app-server conversations from chat.
• ACP/acpx is a separate external harness path. Use it only when the user asks for ACP/acpx or an external harness adapter.

Common command routing:

agents.defaults.imageModel follows the same prefix split. Use openai/gpt-* for the normal OpenAI route and codex/gpt-* only when image understanding should run through a bounded Codex app-server turn. Do not use legacy Codex GPT refs; doctor rewrites that legacy prefix to openai/gpt-*.

Deployment patterns

Basic Codex deployment

Use the quickstart config when all OpenAI agent turns should use Codex by default.

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

Mixed provider deployment

This shape keeps Claude as the default agent and adds a named Codex agent:

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

With this config, the main agent uses its normal provider path and the codex agent uses Codex app-server.

Fail-closed Codex deployment

For OpenAI agent turns, openai/gpt-* already resolves to Codex when the bundled plugin is available. Add explicit runtime policy when you want a written fail-closed rule:

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

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

App-server policy

By default, the plugin starts OmeniaClaw's managed Codex binary locally with stdio transport. Set appServer.command only when you intentionally want to run a different executable. Use WebSocket transport only when an app-server is already running elsewhere:

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

Local stdio app-server sessions default to the trusted local operator posture: approvalPolicy: "never", approvalsReviewer: "user", and sandbox: "danger-full-access". If local Codex requirements disallow that implicit YOLO posture, OmeniaClaw selects allowed guardian permissions instead. When an OmeniaClaw sandbox is active for the session, OmeniaClaw disables Codex native Code Mode, user MCP servers, and app-backed plugin execution for that turn instead of relying on Codex host-side sandboxing. Shell access is exposed through OmeniaClaw sandbox-backed dynamic tools such as sandbox_exec and sandbox_process when the normal exec/process tools are available.

Use normalized OmeniaClaw exec mode when you want Codex native auto-review before sandbox escapes or extra permissions:

{  tools: {    exec: {      mode: "auto",    },  },  plugins: {    entries: {      codex: {        enabled: true,      },    },  },}

For Codex app-server sessions, OmeniaClaw maps tools.exec.mode: "auto" to Codex Guardian-reviewed approvals, usually approvalPolicy: "on-request", approvalsReviewer: "auto_review", and sandbox: "workspace-write" when the local requirements allow those values. In tools.exec.mode: "auto", OmeniaClaw does not preserve legacy unsafe Codex approvalPolicy: "never" or sandbox: "danger-full-access" overrides; use tools.exec.mode: "full" for an intentional no-approval Codex posture. The legacy plugins.entries.codex.config.appServer.mode: "guardian" preset still works, but tools.exec.mode: "auto" is the normalized OmeniaClaw surface.

For the mode-level comparison with host exec approvals and ACPX permissions, see Permission modes.

For every app-server field, auth order, environment isolation, discovery, and timeout behavior, see Codex harness reference.

Commands and diagnostics

The bundled plugin registers /codex as a slash command on any channel that supports OmeniaClaw text commands.

Common forms:

• /codex status checks app-server connectivity, models, account, rate limits, MCP servers, and skills.
• /codex models lists live Codex app-server models.
• /codex threads [filter] lists recent Codex app-server threads.
• /codex resume <thread-id> attaches the current OmeniaClaw session to an existing Codex thread.
• /codex compact asks Codex app-server to compact the attached thread.
• /codex review starts Codex native review for the attached thread.
• /codex diagnostics [note] asks before sending Codex feedback for the attached thread.
• /codex account shows account and rate-limit status.
• /codex mcp lists Codex app-server MCP server status.
• /codex skills lists Codex app-server skills.

For most support reports, start with /diagnostics [note] in the conversation where the bug happened. It creates one Gateway diagnostics report and, for Codex harness sessions, asks for approval to send the relevant Codex feedback bundle. See Diagnostics export for the privacy model and group chat behavior.

Use /codex diagnostics [note] only when you specifically want the Codex feedback upload for the currently attached thread without the full Gateway diagnostics bundle.

Inspect Codex threads locally

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

codex resume <thread-id>

Get the thread id from the completed /diagnostics reply, /codex binding, or /codex threads [filter].

For upload mechanics and runtime-level diagnostics boundaries, see Codex harness runtime.

Auth is selected in this order:

1. Ordered OpenAI auth profiles for the agent, preferably under auth.order.openai. Run OmeniaClaw doctor --fix to migrate older legacy Codex auth profile ids and legacy Codex auth order.
2. The app-server's existing account in that agent's Codex home.
3. For local stdio app-server launches only, CODEX_API_KEY, then OPENAI_API_KEY, when no app-server account is present and OpenAI auth is still required.

When OmeniaClaw sees a ChatGPT subscription-style Codex auth profile, it removes CODEX_API_KEY and OPENAI_API_KEY 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. When native Codex plugins are configured, OmeniaClaw installs or refreshes those plugins through the connected app-server before exposing plugin-owned apps to the Codex thread.

If a subscription profile hits a Codex usage limit, OmeniaClaw records the reset time when Codex reports one and tries the next ordered auth profile for the same Codex run. When the reset time passes, the subscription profile becomes eligible again without changing the selected openai/gpt-* model or Codex runtime.

For local stdio app-server launches, OmeniaClaw sets CODEX_HOME to a per-agent directory so Codex config, auth/account files, plugin cache/data, and native thread state do not read or write the operator's personal ~/.codex by default. OmeniaClaw preserves the normal process HOME; Codex-run subprocesses can still find user-home config and tokens, and Codex may discover shared $HOME/.agents/skills and $HOME/.agents/plugins/marketplace.json entries.

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. OmeniaClaw removes CODEX_HOME and HOME from this list during local launch normalization: CODEX_HOME stays per-agent, and HOME stays inherited so subprocesses can use normal user-home state.

Codex dynamic tools default to searchable loading. OmeniaClaw does not expose dynamic tools that duplicate Codex-native workspace operations: read, write, edit, apply_patch, exec, process, and update_plan. Most remaining OmeniaClaw integration tools such as messaging, media, cron, browser, nodes, gateway, and heartbeat_respond are available through Codex tool search under the OmeniaClaw namespace, keeping the initial model context smaller. 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 OmeniaClaw's managed web_search dynamic tool are mutually exclusive so managed search cannot bypass native domain restrictions. OmeniaClaw uses the managed tool when hosted search is unavailable, explicitly disabled, or replaced by a selected managed provider. OmeniaClaw 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 and message-tool-only source replies stay direct because those are turn-control contracts. sessions_spawn stays searchable so Codex's native spawn_agent remains the primary Codex subagent surface, while explicit OmeniaClaw or ACP delegation is still available through the OmeniaClaw dynamic tool namespace. Heartbeat collaboration instructions tell Codex to search for heartbeat_respond before ending a heartbeat turn when the tool is not already loaded.

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.

Supported top-level Codex plugin fields:

Supported appServer fields:

appServer.networkProxy is explicit because it changes the Codex sandbox contract. When enabled, OmeniaClaw also sets features.network_proxy.enabled and default_permissions in the Codex thread config so the generated permission profile can start Codex managed networking. By default, OmeniaClaw generates a collision-resistant OmeniaClaw-network-<fingerprint> profile name from the profile body; use profileName only when a stable local name is required.

export default {  plugins: {    entries: {      codex: {        config: {          appServer: {            sandbox: "workspace-write",            networkProxy: {              enabled: true,              domains: {                "api.openai.com": "allow",                "blocked.example.com": "deny",              },              unixSockets: {                "/tmp/proxy.sock": "allow",                "/tmp/blocked.sock": "none",              },              allowUpstreamProxy: true,              proxyUrl: "http://127.0.0.1:3128",            },          },        },      },    },  },};

If the normal app-server runtime would be danger-full-access, enabling networkProxy uses workspace-style filesystem access for the generated permission profile. Codex managed network enforcement is sandboxed networking, so a full-access profile would not protect outbound traffic. Domain entries use allow or deny; Unix socket entries use Codex's allow or none values.

OmeniaClaw-owned dynamic tool calls are bounded independently from appServer.requestTimeoutMs: Codex item/tool/call requests use a 90 second OmeniaClaw watchdog by default. A positive per-call timeoutMs argument extends or shortens that specific tool budget. The image_generate tool uses agents.defaults.imageGenerationModel.timeoutMs when the tool call does not provide its own timeout, or a 120 second image-generation default otherwise. The media-understanding image tool uses tools.media.image.timeoutSeconds or its 60 second media default. For image understanding, that timeout applies to the request itself and is not reduced by earlier preparation work. Dynamic tool budgets are capped at 600000 ms. On timeout, OmeniaClaw 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 processing. This watchdog is the outer dynamic item/tool/call budget; provider-specific request timeouts run inside that call and keep their own timeout semantics.

After Codex accepts a turn, and after OmeniaClaw responds to a turn-scoped app-server request, the harness expects Codex to make current-turn progress and eventually finish the native turn with turn/completed. If the app-server goes quiet for appServer.turnCompletionIdleTimeoutMs, OmeniaClaw best-effort interrupts the Codex turn, records a diagnostic timeout, and releases the OmeniaClaw session lane so follow-up chat messages are not queued behind a stale native turn. Most non-terminal notifications for the same turn disarm that short watchdog because Codex has proven the turn is still alive. Tool handoffs use a longer post-tool idle budget: after OmeniaClaw returns an item/tool/call response, after native tool items such as commandExecution complete, 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 for the silent synthesis window before Codex emits the next current-turn event. Global app-server notifications, such as rate-limit updates, do not reset turn-idle progress. 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/non-commentary completed agentMessage items and pre-tool raw assistant completions arm the assistant-output release: if Codex then goes quiet without turn/completed, OmeniaClaw best-effort interrupts 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 OmeniaClaw 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 say the response may be incomplete, while unsafe cases tell 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/role, active request/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.

Environment overrides remain available for local testing:

• OmeniaClaw_CODEX_APP_SERVER_BIN
• OmeniaClaw_CODEX_APP_SERVER_ARGS
• OmeniaClaw_CODEX_APP_SERVER_MODE=yolo|guardian
• OmeniaClaw_CODEX_APP_SERVER_APPROVAL_POLICY
• OmeniaClaw_CODEX_APP_SERVER_SANDBOX

OmeniaClaw_CODEX_APP_SERVER_BIN bypasses the managed binary when appServer.command is unset.

OmeniaClaw_CODEX_APP_SERVER_GUARDIAN=1 was removed. Use plugins.entries.codex.config.appServer.mode: "guardian" instead, or OmeniaClaw_CODEX_APP_SERVER_MODE=guardian 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.

Native Codex plugins

Native Codex plugin support uses Codex app-server's own app and plugin capabilities in the same Codex thread as the OmeniaClaw harness turn. OmeniaClaw does not translate Codex plugins into synthetic codex_plugin_* OmeniaClaw dynamic tools.

codexPlugins affects only sessions that select the native Codex harness. It has no effect on built-in harness runs, normal OpenAI provider runs, ACP conversation bindings, or other harnesses.

Minimal migrated config:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          codexPlugins: {            enabled: true,            allow_destructive_actions: true,            plugins: {              "google-calendar": {                enabled: true,                marketplaceName: "openai-curated",                pluginName: "google-calendar",              },            },          },        },      },    },  },}

Thread app config is computed when OmeniaClaw establishes a Codex harness session or replaces a stale Codex thread binding. It is not recomputed on every turn. After changing codexPlugins, use /new, /reset, or restart the gateway so future Codex harness sessions start with the updated app set.

For migration eligibility, app inventory, destructive action policy, elicitations, and native plugin diagnostics, see Native Codex plugins.

OpenAI-side app and plugin access is controlled by the signed-in Codex account and, for Business and Enterprise/Edu workspaces, workspace app controls. See Using Codex with your ChatGPT plan for OpenAI's account and workspace-control overview.

Computer Use

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

The short version: OmeniaClaw does not vendor the desktop-control app or execute desktop actions itself. It prepares Codex app-server, verifies that the computer-use MCP server is available, and then lets Codex own the native MCP tool calls during Codex-mode turns.

Runtime boundaries

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

• OmeniaClaw dynamic tools are supported. Codex asks OmeniaClaw to execute those tools, so OmeniaClaw remains in the execution path.
• Codex-native shell, patch, MCP, and native app tools are owned by Codex. OmeniaClaw can observe or block selected native events through the supported relay, but it does not rewrite native tool arguments.
• Codex owns native compaction. OmeniaClaw keeps a transcript mirror for channel history, search, /new, /reset, and future model or harness switching, but it does not replace Codex compaction with an OmeniaClaw or context-engine summarizer.
• Media generation, media understanding, TTS, approvals, and messaging-tool output continue through the matching OmeniaClaw provider/model settings.
• tool_result_persist applies to OmeniaClaw-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.

Troubleshooting

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

OmeniaClaw uses the built-in harness instead of Codex: make sure the model ref is openai/gpt-* on the official OpenAI provider and that the Codex plugin is installed and enabled. If you need strict proof while testing, set provider or model agentRuntime.id: "codex". A forced Codex runtime fails instead of falling back to OmeniaClaw.

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 OmeniaClaw 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/OmeniaClaw/OmeniaClaw-*.log >/dev/null 2>&1; then    grep -E -i -n "$pattern" /tmp/OmeniaClaw/OmeniaClaw-*.log 2>/dev/null || true  else    journalctl --user -u OmeniaClaw-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.5 or openai/gpt-5.4, 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 OmeniaClaw 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 app-server 0.125.0 or newer. Same-version prereleases or build-suffixed versions such as 0.125.0-alpha.2 or 0.125.0+custom are rejected because OmeniaClaw tests the stable 0.125.0 protocol floor.

/codex status cannot connect: check that the bundled 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.

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

WebSocket transport fails immediately: check appServer.url, authToken, headers, and that the remote app-server speaks the same Codex app-server protocol version.

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 OmeniaClaw 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 OmeniaClaw Gateway so old threads are dropped and native hook registrations are recreated.

A non-Codex model uses the built-in harness: that is 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.

Related

• Codex harness reference
• Codex harness runtime
• Native Codex plugins
• Codex Computer Use
• Agent runtimes
• Model providers
• OpenAI provider
• OpenAI Codex help
• Agent harness plugins
• Plugin hooks
• Diagnostics export
• Status
• Testing