---

name: add-codex description: Use Codex (OpenAI's codex app-server) as a full agent provider — planning, tool orchestration, MCP tools, server-side history, session resume — alongside or instead of Claude. ChatGPT subscription or OpenAI API key, vault-only via the selected gateway. Per-group via ncl groups config update --provider codex. Distinct from using OpenAI as an MCP tool (where Claude remains the planner). metadata: nanoclaw-provider: codex nanoclaw-provider-label: Codex nanoclaw-provider-hint: OpenAI — ChatGPT subscription or API key nanoclaw-provider-offered: 'true' nanoclaw-provider-image: local-required

Codex agent provider

Shortcut: pnpm exec tsx setup/index.ts --step provider-auth codex performs this whole install (manifest-driven from the providers branch: files, barrels, CLI manifest entry, image rebuild) plus auth in one command. The steps below are the same operations, for agent-driven or manual application.

NanoClaw selects each group's agent backend from container_configs.provider (default claude). This skill installs the Codex provider: copy the payload from the providers branch, append one import to each of the three provider barrels, add the pinned Codex CLI to the container manifest (container/cli-tools.json), rebuild, then run the vault auth walk-through.

The provider runs codex app-server as a child process speaking JSON-RPC over stdio: native streaming, MCP tools, server-side conversation history (the continuation is a thread id, no on-disk transcript). Credentials are vault-only: The selected gateway serves a sentinel auth.json stub into the container and swaps the real ChatGPT token or API key on the wire — no key in .env, nothing readable in the container.

The mechanical steps under Install carry nc: directive fences: an agent reads the prose and applies them, and a parser can apply them deterministically from the same document. Every directive is idempotent, so the whole skill is safe to re-run; anything a parser can't apply falls back to the prose beside it.

Install

Pre-flight

Requires src/project-doc-compose.ts on trunk. If it is missing, stop and tell the operator to run /update-nanoclaw first.

Check whether the payload is already wired (a prior apply, or a trunk that still carries it). All of these present means installed — skip to Authenticate:

• src/providers/codex.ts and src/providers/codex-agents-md.ts
• container/agent-runner/src/providers/codex.ts and codex-app-server.ts
• setup/providers/codex.ts and both provider-contracts/codex.ts declarations (host and container)
• import './codex.js'; in the three provider barrels and both contract barrels
• an @openai/codex entry in container/cli-tools.json

1. Fetch and copy the payload

Fetch the providers branch and copy the Codex payload into all three trees (additive — overwrite each file, never merge the branch). The host files are the provider contribution + the AGENTS.md spec (composition itself lives in trunk's src/project-doc-compose.ts) + their guards; the container files are the provider runtime (turn loop, JSON-RPC wrapper, native memory SessionStart hook, per-exchange archiver) + their guards; the setup file is the picker entry + vault auth walk-through; container/AGENTS.md is the runtime-contract base the composed AGENTS.md embeds.

src/providers/codex.ts
src/providers/codex-agents-md.ts
src/providers/codex-registration.test.ts
src/providers/codex-host-contribution.test.ts
src/providers/codex-agents-md.test.ts
container/agent-runner/src/providers/codex.ts
container/agent-runner/src/providers/codex-app-server.ts
container/agent-runner/src/providers/exchange-archive.ts
container/agent-runner/src/providers/exchange-archive.test.ts
container/agent-runner/src/providers/codex-registration.test.ts
container/agent-runner/src/providers/codex.factory.test.ts
container/agent-runner/src/providers/codex.turns.test.ts
container/agent-runner/src/providers/codex-app-server.test.ts
container/agent-runner/src/providers/codex-contract-parity.test.ts
container/agent-runner/src/providers/codex.conformance.test.ts
container/agent-runner/src/providers/codex-cli-tools.test.ts
container/agent-runner/src/provider-contracts/codex.ts
setup/providers/codex-registration.test.ts
container/AGENTS.md

Use the selected gateway for authentication

Install the bundled Codex authentication hook alongside the registry payload. This keeps the same login choices while delegating custody to the selected gateway, and preserves the hook when a provider refresh copies registry files again. These two files are omitted from the registry copy so refresh stays idempotent. The setup screens and step sequence do not change.

payload/src/provider-contracts/codex.ts -> src/provider-contracts/codex.ts
payload/setup/providers/codex.ts -> setup/providers/codex.ts
payload/setup/providers/codex.test.ts -> setup/providers/codex.test.ts

2. Wire the barrels

Append the self-registration import to each provider and contract barrel (skipped if already present).

import './codex.js';

import './codex.js';

import './codex.js';

import './codex.js';

import './codex.js';

3. CLI manifest

The agent's global Node CLIs install from container/cli-tools.json (a json-merge seam), not hand-edited Dockerfile layers. Add Codex by appending one entry — idempotent on name, so a re-run is a no-op. @openai/codex has no native postinstall, so no onlyBuilt. The Dockerfile already installs every manifest entry via pinned pnpm install -g; no Dockerfile edit is needed.

{ "name": "@openai/codex", "version": "0.155.1" }

The version (0.155.1) is the canonical pin — this SKILL.md is the source of truth.

4. Build

pnpm run build
pnpm exec tsc -p container/agent-runner/tsconfig.json --noEmit
./container/build.sh

5. Validate

pnpm exec tsx scripts/provider-contract-verifier.ts --required-declared codex

The registration tests import only the real barrels — they go red if a barrel line is missing, a barrel fails to evaluate, or the payload is broken.

Authenticate

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

The same walk-through fresh installs get from the setup picker: ChatGPT subscription (browser login or device pairing) or an OpenAI API key, landed in the selected gateway’s vault. Idempotent — it short-circuits when a matching secret already exists. It finishes with the install check.

Use it

Per group:

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

Switching is an operator action — run it from the host. Every provider uses the same memory/ tree, so memory carries across automatically. Run /migrate-memory only when upgrading a group that still has legacy .seed.md, CLAUDE.local.md, or unindexed imported memory. See docs/provider-migration.md.

Default new groups to codex (optional)

New groups are created on the instance default (DEFAULT_AGENT_PROVIDER in .env, or claude when unset). Installing this skill wires codex in but does NOT change that default — "installed" is not "authenticated", so the default stays claude until you opt in explicitly.

After install, ask the operator before flipping it:

"Codex is installed. Default new agent groups to codex? Existing groups keep their current provider."

On yes — set it, then restart the host so it takes effect:

pnpm exec tsx setup/index.ts --step set-env -- --key DEFAULT_AGENT_PROVIDER --value codex
launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS; Linux: systemctl --user restart nanoclaw

This affects only groups created afterward. Per-group ncl groups config update --provider still overrides the default in either direction. Creation itself stays provider-agnostic (no --provider flag — provider is a DB property stamped from the instance default at creation).

Troubleshooting

• Container dies at boot, channel silent: grep 'Container exited non-zero' logs/nanoclaw.error.log — the stderrTail carries the reason (e.g. Unknown provider: codex. Registered: claude means the barrels aren't wired in the running build).
• In-channel Error: spawn codex ENOENT on every message: the image predates the manifest entry — re-run ./container/build.sh.
• Auth errors mid-conversation: the vault secret is missing or stale — re-run pnpm exec tsx setup/index.ts --step provider-auth codex (subscription re-login updates the vault copy).