Codex harness

​

Requirements

• The official @openclaw/codex plugin installed. Include codex in plugins.allow if your config uses an allowlist.
• Codex app-server 0.147.0 or newer. The plugin ships and manages the exact @openai/codex 0.148.0 artifact, so a codex command on PATH does not affect normal startup. Explicit custom, remote, and macOS desktop-owned app-servers must report valid SemVer at or above the supported minimum. Versions newer than the managed artifact initialize with a warning; acceptance permits an attempt and is not readiness or capability proof.
• Node.js on the remote Codex app-server host when remoteWorkspaceRoot is set and cross-machine workspace attachments must be transferred.
• Codex auth through openclaw models auth login --provider openai, an app-server account already present in the agent’s Codex home, or an explicit Codex API-key auth profile.

​

Quickstart

openclaw plugins install @openclaw/codex
openclaw models auth login --provider openai

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

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

​

Run Codex on a paired device

{
  gateway: {
    nodes: {
      commands: {
        allow: ["codex.exec-server.stdio.v1"],
      },
    },
  },
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}

openclaw gateway call sessions.dispatch \
  --params '{"key":"agent:main:device-work","deviceId":"<paired-device-id>"}'

​

Share threads with Codex Desktop and CLI

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            homeScope: "user",
          },
        },
      },
    },
  },
}

• A subscription route requires the native home to be signed in to ChatGPT. Run codex login in that home if a turn reports missing subscription credentials.
• A Platform (API-key) route refuses a native home signed in with a ChatGPT subscription, so an API-billed route never silently spends the plan. Sign that home in with codex login --with-api-key, or switch to homeScope: "agent" and let OpenClaw inject the key it already holds.

​

Supervise Codex sessions

​

Configuration

{
  auth: {
    order: {
      openai: ["openai:user@example.com", "openai:api-key-backup"],
    },
  },
}

​

Restricted turns and ring zero

• a finite tools.allow list or an internal per-run allowlist
• disableTools or a sender/group policy that denies all tools
• a tools.deny entry with a wildcard, tool group, unknown name, or name that is not in the Codex harness’s audited safe-deny set
• an applicable agent, provider, group, sender, sandbox, subagent, inherited, scheduled, or runtime tool policy with one of those restrictions

​

Project instructions

​

Compaction

​

Direct API long context

1050000 total - 128000 maximum output = 922000 safe active input
automatic compaction threshold = 700000 active tokens

{
  "context_window": 922000,
  "max_context_window": 922000,
  "auto_compact_token_limit": 700000
}

model = "gpt-5.6-sol"
model_provider = "openai_api_direct"
model_context_window = 922000
model_auto_compact_token_limit = 700000
model_auto_compact_token_limit_scope = "total"
model_catalog_json = "/absolute/path/to/models-api-1m.json"

[model_providers.openai_api_direct]
name = "OpenAI API direct"
base_url = "https://api.openai.com/v1"
wire_api = "responses"
requires_openai_auth = false

[model_providers.openai_api_direct.auth]
command = "/absolute/path/to/read-openai-inference-key"
timeout_ms = 5000
refresh_interval_ms = 300000

{
  auth: {
    order: {
      openai: ["openai:api-key"],
    },
  },
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            args: [
              "app-server",
              "--listen",
              "stdio://",
              "-c",
              'model_catalog_json="/absolute/path/to/models-api-1m.json"',
              "-c",
              "model_context_window=922000",
              "-c",
              "model_auto_compact_token_limit=700000",
              "-c",
              "model_auto_compact_token_limit_scope=total",
            ],
          },
        },
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.6-sol" },
      models: {
        "openai/gpt-5.6-sol": {
          agentRuntime: { id: "codex" },
          params: { fastMode: true },
        },
      },
    },
  },
}

​

Verify Codex runtime

Runtime: OpenAI Codex

/codex status
/codex models
/codex binding

openclaw doctor --lint --only codex/managed-app-server --json

​

Routing and model selection

• Use openai/gpt-* for canonical OpenAI model selection. The prefix alone never selects Codex.
• With runtime unset or auto, only an exact official HTTPS Platform Responses or ChatGPT Responses route with no authored provider request override may select Codex implicitly. Valid model-scoped Fast-mode and cutoff controls do not count as authored request params.
• Do not use legacy Codex GPT refs in config; run openclaw doctor --fix to repair legacy refs and stale session route pins.
• agentRuntime.id: "codex" makes Codex a fail-closed requirement for a compatible route. It does not make an incompatible effective route compatible.
• agentRuntime.id: "openclaw" opts a provider or model into the embedded OpenClaw 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.

​

Deployment patterns

​

Basic Codex deployment

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

​

Mixed provider deployment

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    ownership: "explicit",
    defaults: {
      model: "anthropic/claude-opus-4-6",
    },
    entries: {
      main: {
        model: "anthropic/claude-opus-4-6",
      },
      codex: {
        name: "Codex",
        model: "openai/gpt-5.6-sol",
      },
    },
  },
}

​

Fail-closed Codex deployment

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

​

App-server policy

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

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

​

Native approval audit evidence

​

Commands and diagnostics

• /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 goal reads or updates the attached thread’s native Codex goal. Codex automatic goal continuation stays disabled; OpenClaw does not own autonomous follow-on turns yet.
• /codex resume <thread-id> attaches the current OpenClaw session to an existing Codex thread.
• /codex bind [thread-id] [--cwd <path>] [--model <model>] [--provider <provider>] attaches the current chat.
• /codex detach (or /codex unbind) detaches the current binding.
• /codex binding describes the current binding.
• /codex stop stops the active turn; /codex steer <text> steers it.
• /codex model <model>, /codex fast [on|off|status], and /codex permissions [default|yolo|status] change per-conversation state.
• /codex compact runs the same completion and session-accounting pipeline as /compact, then reports whether Codex compacted the session and the resulting token count. If compaction is skipped or fails, the reply includes the reason.
• /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.
• /codex plugins list shows configured native plugins; /codex plugins available discovers Codex marketplace plugins in the bound workspace.
• /codex plugins install <plugin>@<marketplace> installs and authorizes one discovered plugin. /codex plugins enable <name> and /codex plugins disable <name> update its persisted policy. Mutations require an owner or operator.admin gateway client.
• /codex computer-use [status|install] manages Codex Computer Use.
• /codex help lists the full command tree.

​

Shared Fast mode and Codex fast mode

​

Inspect Codex threads locally

codex resume <thread-id>

​

Auth order

1. Ordered OpenAI auth profiles for the agent, preferably under auth.order.openai. Run openclaw 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.

​

Environment isolation

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

​

Dynamic tools and web search

​

Config fields

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

​

Image loader ownership

​

Dynamic tool call timeouts

​

Local testing env overrides

• OPENCLAW_CODEX_APP_SERVER_BIN bypasses the managed binary when appServer.command is unset.
• OPENCLAW_CODEX_APP_SERVER_ARGS
• OPENCLAW_CODEX_APP_SERVER_MODE=yolo|guardian
• OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY
• OPENCLAW_CODEX_APP_SERVER_SANDBOX

​

Native Codex plugins

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

​

Computer Use

​

Runtime boundaries

• OpenClaw dynamic tools are supported. Codex asks OpenClaw to execute those tools, so OpenClaw remains in the execution path.
• Codex-native shell, patch, MCP, and native app tools are owned by Codex. OpenClaw can observe or block selected native events through the supported relay, but it does not rewrite native tool arguments.
• gateway_exec and gateway_process are OpenClaw-owned dynamic tools. They deliberately re-enter Gateway exec preparation for agent-readable Secret Store environment and protected egress; those values never flow into Codex native shell.
• Codex owns native compaction. OpenClaw keeps a transcript mirror for channel history, search, /new, /reset, and future model or harness switching, but does not replace Codex compaction with an OpenClaw or context-engine summarizer.
• Media generation, media understanding, TTS, approvals, and messaging-tool output continue through the matching OpenClaw provider/model settings.
• tool_result_persist applies to OpenClaw-owned transcript tool results, not Codex-native tool result records.

​

Troubleshooting

(
  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

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

​

Related

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