Codex (Provider)

How it works

NanoClaw runs each agent group in a long-lived poll loop inside its container. Each group’s backend is selected by the provider key in its container config (the container_configs table, default claude), set with ncl groups config update --id <group-id> --provider codex.

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 server-side conversation history — 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 — one ncl command per group.

Setup

The skill walks you through:

1. Fetch the providers branch.
2. Copy the codex.ts provider files into src/providers/, container/agent-runner/src/providers/, and setup/providers/.
3. Add the self-registration import to all three provider barrels (src, container agent-runner, and setup).
4. Add a pinned @openai/codex entry to container/cli-tools.json — the Dockerfile installs every manifest entry, so no Dockerfile edit is needed.
5. Rebuild host and container, then restart the host service.

Shortcut: pnpm exec tsx setup/index.ts --step provider-auth codex performs the whole install plus auth in one command.

Auth

Authentication is interactive and vault-only. Run it in a real terminal:

pnpm exec tsx setup/index.ts --step provider-auth codex

The walk-through offers a ChatGPT subscription login (browser or device pairing) or an OpenAI API key, landed in the OneCLI vault. OneCLI serves a sentinel auth.json stub into the container and swaps the real token on the wire — no key in .env, nothing readable in the container. It’s idempotent: it short-circuits when a matching secret already exists.

Per-group config

Switch a group from the host:

ncl groups config update --id <group-id> --provider codex
ncl groups restart --id <group-id>

groups/<folder>/container.json is materialized from the container_configs table at spawn time — no hand-editing needed. Memory does not carry over automatically between providers; run /migrate-memory to carry it across.

What you get

• Server-side conversation history — the continuation is a thread id, with no on-disk transcript. Session resume comes free.
• 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-group .codex-shared — each group gets its own Codex state dir (data/v2-sessions/<group-id>/.codex-shared, mounted at /home/node/.codex) with a OneCLI-served auth stub. 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 — including OpenAI-compatible third-party endpoints (/add-opencode).
• Approvals are auto-accepted inside the container — the container is the sandbox, same posture as Claude.
• If auth errors show up mid-conversation, the vault secret is missing or stale — re-run pnpm exec tsx setup/index.ts --step provider-auth codex.
• The @openai/codex version pin in container/cli-tools.json is intentional. Pin a version, test, then update — latest can introduce breaking changes.