Codex Agent Provider for NanoClaw

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.