Codex (Provider)

How it works

NanoClaw runs each agent group in a long-lived poll loop inside its container. The backend is selected with AGENT_PROVIDER — claude (default), opencode, codex, or mock.

The /add-codex skill copies the Codex provider from the providers branch and wires it in. Codex runs as codex app-server, a child process that speaks JSON-RPC over stdio. That gives it native session resume, streaming events, MCP tool access, and thread/compact/start compaction — same feature bar as the Claude Agent SDK, without the Anthropic-only lock-in.

This is per-group, not global. You can run some agents on Claude, some on Codex, some on OpenCode — flip a flag in container.json.

Setup

The skill walks you through:

1. Fetch the providers branch.
2. Copy codex.ts provider files into src/providers/ and container/agent-runner/src/providers/.
3. Add the self-registration import to both barrels.
4. Pin CODEX_VERSION in container/Dockerfile and add a dedicated RUN block for the Codex CLI install.
5. Rebuild host and container.

Auth options

Option A: ChatGPT subscription (recommended for individuals). Run codex login on the host. NanoClaw copies your auth.json into a per-session ~/.codex directory mounted into the container.

Option B: API key (recommended for CI / API billing). Set OPENAI_API_KEY and CODEX_MODEL in .env. If both subscription and API key are present, Codex prefers the subscription.

Option C: BYO OpenAI-compatible endpoint (experimental). Set OPENAI_BASE_URL to point at Groq, Together, vLLM, or any OpenAI-compatible provider. Quality of tool calling depends on the model — smaller models often struggle with multi-step tool orchestration.

Per-group config

Set the provider in two places that must agree:

• groups/<folder>/container.json → "provider": "codex"
• agent_groups.agent_provider → 'codex' (or override per-session via sessions.agent_provider)

The container reads container.json directly. The DB columns drive host-side env passthrough (per-session ~/.codex mount, OPENAI_* / CODEX_MODEL).

What you get

• Native compaction kicks in automatically at 40K cumulative input tokens between turns. If compaction fails, the provider logs and continues uncompacted — no fatal error.
• Stale thread recovery — isSessionInvalid matches stale-thread errors so a cold-started app-server recovers cleanly when it sees a stored continuation it no longer has.
• Mid-turn input queueing — turns don’t accept mid-turn messages, so follow-up push() calls queue and drain between turns. The poll-loop only pushes between turns anyway, so no messages are dropped.
• Per-session ~/.codex — each group gets its own copy of the host’s auth.json. The container can rewrite config.toml freely without touching the host’s Codex config.

Tips

• Codex vs. OpenCode: Codex is OpenAI-flavored. OpenCode is multi-provider (Anthropic, OpenRouter, DeepSeek, etc.). Pick Codex if you want the native OpenAI experience; OpenCode if you want to swap models freely.
• Approvals are auto-accepted inside the container — the container is the sandbox, same posture as Claude.
• If the agent hangs after install, check ~/.codex/auth.json exists on the host (Option A) or that OPENAI_API_KEY is forwarding into the container (docker exec ... env | grep OPENAI).
• Bumping CODEX_VERSION is intentional. Pin a version, test, then update — latest can introduce breaking changes.