How to use the Codex Agent Provider skill for NanoClaw

What the Codex skill changes for your agent

NanoClaw picks each group's agent backend from the group's provider setting, which defaults to claude. This skill adds Codex as a full provider. The agent then keeps Codex's planning, tool orchestration, MCP tools and server-side conversation history, and it can resume sessions.

Codex runs as a child process that talks JSON-RPC over stdio, with native streaming. The continuation is a thread id, so there is no on-disk transcript for the conversation. This is different from using OpenAI only as a tool that Claude calls. In that setup Claude remains the planner, and the source notes that the add-codex skill is not that approach.

Check the requirements before you install

You need a NanoClaw trunk that includes src/project-doc-compose.ts and core's shared exchange archive at container/agent-runner/src/provider-contracts/exchange-archive.ts. If either is missing, the skill says to run /update-nanoclaw first.

You also need a ChatGPT subscription or an OpenAI API key, which is used through the selected gateway's vault. The install adds the Codex CLI (@openai/codex) to container/cli-tools.json and requires a container image rebuild.

• NanoClaw trunk with src/project-doc-compose.ts and the shared exchange archive
• A ChatGPT subscription or OpenAI API key, handled by the selected gateway's vault
• Permission to rebuild the container image and run setup commands
• Newer Codex releases need the credential gateway skill from the same NanoClaw release, so refresh both together with /update-nanoclaw

Install the skill files

Download the ZIP of the add-codex skill from this page and unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one project. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

Installing the files does not finish the job. The SKILL.md inside explains the remaining steps, which an agent can apply for you or you can apply by hand.

Apply the Codex provider to NanoClaw

The SKILL.md describes four mechanical steps. First, copy the payload files into the host, container and setup trees, overwriting each file. Second, append import './codex.js'; to each of the five provider and contract barrels. Third, add the @openai/codex entry to container/cli-tools.json. Fourth, rebuild.

The skill also documents a shortcut that performs the whole install, including auth, in one command. Every step is idempotent, so re-running the skill is safe.

• Copy the payload files listed in SKILL.md into all three trees
• Append the import to the five barrel files
• Add the pinned Codex CLI entry to container/cli-tools.json
• Run the build commands and rebuild the container image

Authenticate with your ChatGPT login or API key

Credentials are vault-only. The selected gateway serves a sentinel auth.json stub into the container and swaps in the real ChatGPT token or API key on the wire. The key is not stored in .env, and nothing readable is left in the container.

The setup screens and login steps do not change. Choose the same login options as before and the gateway handles custody.

Switch a group to Codex and trigger it

Ask your agent in plain words to add the Codex provider, or run the /add-codex command, which the REMOVE.md file refers to. Then set the provider for the specific group you want to change. Other groups stay on their current provider.

Restart the group after changing its provider so the change takes effect. The REMOVE.md file shows the same pattern for switching back to Claude.

• List groups with ncl groups list
• Switch one group with ncl groups config update --id <group-id> --provider codex
• Restart it with ncl groups restart --id <group-id>

Safety notes: scripts and network

The skill runs scripts and uses the network. Its build and setup commands run pnpm and the container build script, and the agent reads the SKILL.md directives and applies them. Read the payload and SKILL.md before you run the install, and run it only on a NanoClaw trunk you control.

Because credentials stay in the gateway's vault, you should not put an OpenAI key in .env for this provider. Check which gateway your installation uses before you start.

• Installation copies files across several trees, edits barrel files and rebuilds the image
• The provider talks to OpenAI over the network through the gateway
• To undo the change, follow REMOVE.md, which reverses each step and keeps each group's memory on disk