mirror of
https://github.com/moltbot/moltbot.git
synced 2026-05-11 12:58:34 +00:00
ce0584af89
* docs: reorganize codex harness docs * docs: address codex harness review findings * docs: move codex references to reference nav * docs: add codex topic configuration section
377 lines
18 KiB
Markdown
377 lines
18 KiB
Markdown
---
|
|
summary: "Configuration, auth, discovery, and app-server reference for the Codex harness"
|
|
title: "Codex harness reference"
|
|
read_when:
|
|
- You need every Codex harness config field
|
|
- You are changing app-server transport, auth, discovery, or timeout behavior
|
|
- You are debugging Codex harness startup, model discovery, or environment isolation
|
|
---
|
|
|
|
This reference covers the detailed configuration for the bundled `codex`
|
|
plugin. For setup and routing decisions, start with
|
|
[Codex harness](/plugins/codex-harness).
|
|
|
|
## Plugin config surface
|
|
|
|
All Codex harness settings live under `plugins.entries.codex.config`.
|
|
|
|
```json5
|
|
{
|
|
plugins: {
|
|
entries: {
|
|
codex: {
|
|
enabled: true,
|
|
config: {
|
|
discovery: {
|
|
enabled: true,
|
|
timeoutMs: 2500,
|
|
},
|
|
appServer: {
|
|
mode: "guardian",
|
|
},
|
|
},
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
Supported top-level fields:
|
|
|
|
| Field | Default | Meaning |
|
|
| -------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `discovery` | enabled | Model discovery settings for Codex app-server `model/list`. |
|
|
| `appServer` | managed stdio app-server | Transport, command, auth, approval, sandbox, and timeout settings. |
|
|
| `codexDynamicToolsProfile` | `"native-first"` | Use `"openclaw-compat"` to expose the full OpenClaw dynamic tool set to Codex app-server. |
|
|
| `codexDynamicToolsLoading` | `"searchable"` | Use `"direct"` to put OpenClaw dynamic tools directly in the initial Codex tool context. |
|
|
| `codexDynamicToolsExclude` | `[]` | Additional OpenClaw dynamic tool names to omit from Codex app-server turns. |
|
|
| `codexPlugins` | disabled | Native Codex plugin/app support for migrated source-installed curated plugins. See [Native Codex plugins](/plugins/codex-native-plugins). |
|
|
| `computerUse` | disabled | Codex Computer Use setup. See [Codex Computer Use](/plugins/codex-computer-use). |
|
|
|
|
## App-server transport
|
|
|
|
By default, OpenClaw starts the managed Codex binary shipped with the bundled
|
|
plugin:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```json5
|
|
{
|
|
plugins: {
|
|
entries: {
|
|
codex: {
|
|
enabled: true,
|
|
config: {
|
|
appServer: {
|
|
transport: "websocket",
|
|
url: "ws://gateway-host:39175",
|
|
authToken: "${CODEX_APP_SERVER_TOKEN}",
|
|
requestTimeoutMs: 60000,
|
|
},
|
|
},
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
Supported `appServer` fields:
|
|
|
|
| Field | Default | Meaning |
|
|
| ----------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `transport` | `"stdio"` | `"stdio"` spawns Codex; `"websocket"` connects to `url`. |
|
|
| `command` | managed Codex binary | Executable for stdio transport. Leave unset to use the managed binary. |
|
|
| `args` | `["app-server", "--listen", "stdio://"]` | Arguments for stdio transport. |
|
|
| `url` | unset | WebSocket app-server URL. |
|
|
| `authToken` | unset | Bearer token for WebSocket transport. |
|
|
| `headers` | `{}` | Extra WebSocket headers. |
|
|
| `clearEnv` | `[]` | Extra environment variable names removed from the spawned stdio app-server process after OpenClaw builds its inherited environment. |
|
|
| `requestTimeoutMs` | `60000` | Timeout for app-server control-plane calls. |
|
|
| `turnCompletionIdleTimeoutMs` | `60000` | Quiet window after a turn-scoped app-server request while OpenClaw waits for `turn/completed`. |
|
|
| `mode` | `"yolo"` unless local Codex requirements disallow YOLO | Preset for YOLO or guardian-reviewed execution. |
|
|
| `approvalPolicy` | `"never"` or an allowed guardian approval policy | Native Codex approval policy sent to thread start, resume, and turn. |
|
|
| `sandbox` | `"danger-full-access"` or an allowed guardian sandbox | Native Codex sandbox mode sent to thread start and resume. |
|
|
| `approvalsReviewer` | `"user"` or an allowed guardian reviewer | Use `"auto_review"` to let Codex review native approval prompts when allowed. |
|
|
| `defaultWorkspaceDir` | current process directory | Workspace used by `/codex bind` when `--cwd` is omitted. |
|
|
| `serviceTier` | unset | Optional Codex app-server service tier. `"priority"` enables fast-mode routing, `"flex"` requests flex processing, and `null` clears the override. Legacy `"fast"` is accepted as `"priority"`. |
|
|
|
|
The plugin blocks older or unversioned app-server handshakes. Codex app-server
|
|
must report stable version `0.125.0` or newer.
|
|
|
|
## 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. 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:
|
|
|
|
```json5
|
|
{
|
|
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`.
|
|
|
|
## Auth and environment isolation
|
|
|
|
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, `CODEX_API_KEY`, then
|
|
`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
|
|
`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 OpenClaw's process environment by default, but
|
|
OpenClaw owns the Codex app-server account bridge and sets both `CODEX_HOME` and
|
|
`HOME` to per-agent directories under that agent's OpenClaw state. Codex's own
|
|
skill loader reads `$CODEX_HOME/skills` and `$HOME/.agents/skills`, 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
|
|
openclaw migrate codex --dry-run
|
|
openclaw migrate apply codex --yes
|
|
```
|
|
|
|
If a deployment needs additional environment isolation, add those variables to
|
|
`appServer.clearEnv`:
|
|
|
|
```json5
|
|
{
|
|
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.
|
|
`CODEX_HOME` and `HOME` remain reserved for OpenClaw's per-agent Codex
|
|
isolation on local launches.
|
|
|
|
## Dynamic tools
|
|
|
|
Codex dynamic tools default to the `native-first` profile and `searchable`
|
|
loading. In that mode, OpenClaw does not expose dynamic tools that duplicate
|
|
Codex-native workspace operations:
|
|
|
|
- `read`
|
|
- `write`
|
|
- `edit`
|
|
- `apply_patch`
|
|
- `exec`
|
|
- `process`
|
|
- `update_plan`
|
|
|
|
Remaining OpenClaw integration tools, such as messaging, sessions, media, cron,
|
|
browser, nodes, gateway, `heartbeat_respond`, and `web_search`, are available
|
|
through Codex tool search under the `openclaw` namespace. This keeps the initial
|
|
model context smaller. `sessions_yield` and message-tool-only source replies
|
|
stay direct because those are turn-control contracts.
|
|
|
|
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
|
|
|
|
OpenClaw-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 the media-understanding `image` tool, `tools.media.image.timeoutSeconds`
|
|
converted to milliseconds, or the 60 second media default.
|
|
- The 30 second dynamic-tool default.
|
|
|
|
Dynamic tool budgets are capped at 600000 ms. 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 `processing`.
|
|
|
|
After OpenClaw responds to a Codex turn-scoped app-server request, the harness
|
|
also expects Codex to finish the native turn with `turn/completed`. If the
|
|
app-server goes quiet for `appServer.turnCompletionIdleTimeoutMs` 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.
|
|
|
|
Any non-terminal notification for the same turn, including
|
|
`rawResponseItem/completed`, disarms that short watchdog because Codex has
|
|
proven the turn is still alive. The longer terminal watchdog continues to
|
|
protect genuinely stuck turns. Timeout diagnostics include the last app-server
|
|
notification method and, for raw assistant response items, the item type, role,
|
|
id, and a bounded assistant text preview.
|
|
|
|
## 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 OpenClaw
|
|
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, OpenClaw uses a bundled fallback catalog for:
|
|
|
|
- GPT-5.5
|
|
- GPT-5.4 mini
|
|
- GPT-5.2
|
|
|
|
The current bundled harness is `@openai/codex` `0.130.0`. A `model/list` probe
|
|
against that bundled app-server returned:
|
|
|
|
| Model id | Default | Hidden | Input modalities | Reasoning efforts |
|
|
| --------------------- | ------- | ------ | ---------------- | ------------------------ |
|
|
| `gpt-5.5` | Yes | No | text, image | low, medium, high, xhigh |
|
|
| `gpt-5.4` | No | No | text, image | low, medium, high, xhigh |
|
|
| `gpt-5.4-mini` | No | No | text, image | low, medium, high, xhigh |
|
|
| `gpt-5.3-codex` | No | No | text, image | low, medium, high, xhigh |
|
|
| `gpt-5.3-codex-spark` | No | No | text | low, medium, high, xhigh |
|
|
| `gpt-5.2` | No | No | text, image | low, medium, high, xhigh |
|
|
|
|
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`:
|
|
|
|
```json5
|
|
{
|
|
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:
|
|
|
|
```json5
|
|
{
|
|
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 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 OpenClaw workspace parity, the Codex harness resolves the other bootstrap
|
|
files, including `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`,
|
|
`HEARTBEAT.md`, `BOOTSTRAP.md`, and `MEMORY.md` when present, and forwards them
|
|
through Codex developer instructions on `thread/start` and `thread/resume`.
|
|
This keeps workspace persona and profile context visible on the native Codex
|
|
behavior-shaping lane without duplicating `AGENTS.md`.
|
|
|
|
## Environment overrides
|
|
|
|
Environment overrides remain available for local testing:
|
|
|
|
- `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`
|
|
|
|
`OPENCLAW_CODEX_APP_SERVER_BIN` bypasses the managed binary when
|
|
`appServer.command` is unset.
|
|
|
|
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` was removed. Use
|
|
`plugins.entries.codex.config.appServer.mode: "guardian"` instead, or
|
|
`OPENCLAW_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](/plugins/codex-harness)
|
|
- [Codex harness runtime](/plugins/codex-harness-runtime)
|
|
- [Native Codex plugins](/plugins/codex-native-plugins)
|
|
- [Codex Computer Use](/plugins/codex-computer-use)
|
|
- [OpenAI provider](/providers/openai)
|
|
- [Configuration reference](/gateway/configuration-reference)
|