Codex harness reference

This reference covers the detailed configuration for the bundled codex plugin. For setup and routing decisions, start with Codex harness.

Plugin config surface

All Codex harness settings live under plugins.entries.codex.config.

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

Supported top-level fields:

App-server transport

By default, OmeniaClaw starts the managed Codex binary shipped with the bundled plugin:

codex app-server --listen stdio://

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

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

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

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

The plugin blocks older or unversioned app-server handshakes. Codex app-server must report stable version 0.125.0 or newer.

OmeniaClaw 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 OmeniaClaw builds app-server start options, and unresolved structured SecretRefs fail before any token or header is sent. When native Codex plugins are configured, OmeniaClaw 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. Only connect OmeniaClaw to remote app-servers that are trusted to accept OmeniaClaw-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 OmeniaClaw 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, OmeniaClaw 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 OmeniaClaw sandbox is active, the local Codex app-server process still runs on the Gateway host. OmeniaClaw 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 OmeniaClaw sandbox backend. 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.

On Ubuntu/AppArmor hosts, Codex bwrap can fail under workspace-write before the shell command starts when you intentionally run native Codex workspace-write without active OmeniaClaw sandboxing. If you see bwrap: setting up uid map: Permission denied or bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted, run OmeniaClaw doctor and fix the reported host namespace policy for the OmeniaClaw service user rather than granting broader Docker container privileges. Prefer a scoped AppArmor profile for the service process; the kernel.apparmor_restrict_unprivileged_userns=0 fallback is host-wide and has security tradeoffs.

Sandboxed native execution

The stable default is fail-closed: active OmeniaClaw 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 OmeniaClaw's sandbox backend. This preview path requires Codex app-server 0.132.0 or newer.

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

When the flag is on and the current OmeniaClaw session is sandboxed, OmeniaClaw starts a local loopback exec-server backed by the active sandbox, registers it with Codex app-server, and starts the Codex thread and turn with that OmeniaClaw-owned environment. If the app-server cannot register the environment, the run fails closed instead of silently falling back to host execution.

This preview path is local-only. A remote WebSocket app-server cannot reach the loopback exec-server unless it is running on the same host, so OmeniaClaw rejects that combination.

Auth and environment isolation

Auth is selected in this order:

1. An explicit OmeniaClaw 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, 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.

Stdio app-server launches inherit OmeniaClaw's process environment by default. OmeniaClaw owns the Codex app-server account bridge and sets CODEX_HOME to a per-agent directory under that agent's OmeniaClaw state. That keeps Codex config, accounts, plugin cache/data, and thread state scoped to the OmeniaClaw agent instead of leaking in from the operator's personal ~/.codex home.

OmeniaClaw does not rewrite HOME for normal local app-server launches. Codex-run subprocesses such as OmeniaClaw, 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.

OmeniaClaw plugins and OmeniaClaw skill snapshots still flow through OmeniaClaw'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 OmeniaClaw agent, inventory them explicitly:

OmeniaClaw migrate codex --dry-runOmeniaClaw 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. 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.

Dynamic tools

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
• update_plan

Most remaining OmeniaClaw integration tools, such as messaging, media, cron, browser, nodes, gateway, heartbeat_respond, and web_search, are available through Codex tool search under the OmeniaClaw namespace. This keeps the initial model context smaller. 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.

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.

Timeouts

OmeniaClaw-owned dynamic tool calls are bounded independently from appServer.requestTimeoutMs. Each Codex item/tool/call request uses the first available timeout in this order:

• A positive per-call timeoutMs argument.
• For image_generate, agents.defaults.imageGenerationModel.timeoutMs.
• For image_generate without a configured timeout, the 120 second image-generation default.
• For the media-understanding image tool, tools.media.image.timeoutSeconds converted to milliseconds, or the 60 second media default. For image understanding, this applies to the request itself and is not reduced by earlier preparation work.
• The 90 second dynamic-tool default.

This watchdog is the outer dynamic item/tool/call budget. Provider-specific request timeouts run inside that call and keep their own timeout semantics. 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.

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. 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.

Model discovery

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

If discovery fails or times out, OmeniaClaw uses a bundled fallback catalog for:

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

The current bundled harness is @openai/codex 0.139.0. A model/list probe against that bundled app-server returned:

Hidden models can be returned by the app-server catalog for internal or specialized flows, but they are not 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. OmeniaClaw does not write synthetic Codex project-doc files or depend on Codex fallback filenames for persona files, because Codex fallbacks only apply when AGENTS.md is missing.

For OmeniaClaw workspace parity, the Codex harness resolves the other bootstrap files. SOUL.md, IDENTITY.md, TOOLS.md, and USER.md are forwarded as OmeniaClaw Codex developer instructions because they define the active agent, available workspace guidance, and user profile. The compact OmeniaClaw skills list is forwarded as turn-scoped collaboration developer instructions. HEARTBEAT.md content is not injected; heartbeat turns get a collaboration-mode pointer to read the file when it exists and is non-empty. MEMORY.md content from the configured agent workspace is not pasted into native Codex turn input when memory tools are available for that workspace; when it exists, 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 is relevant. If tools are disabled, memory search is unavailable, or the active workspace differs from the agent memory workspace, MEMORY.md uses the normal bounded turn-context path. BOOTSTRAP.md when present is forwarded as OmeniaClaw turn input reference context.

Environment overrides

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.

Related

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