# Add Codex

Use Codex (OpenAI's codex app-server) as a full agent provider, planning, tool...

- Repository: https://github.com/nanocoai/nanoclaw (31069 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add nanocoai/nanoclaw --skill add-codex -g -a claude-code -y`
Codex: `npx skills add nanocoai/nanoclaw --skill add-codex -g -a codex -y`
Cursor: `npx skills add nanocoai/nanoclaw --skill add-codex -g -a cursor -y`
Gemini CLI: `npx skills add nanocoai/nanoclaw --skill add-codex -g -a gemini-cli -y`

## 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).

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Codex agent provider

> Shortcut: `pnpm exec tsx setup/index.ts --step provider-auth codex` performs this whole install (manifest-driven from this skill's payload: 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 this skill's payload, 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` and core's shared exchange archive
(`container/agent-runner/src/provider-contracts/exchange-archive.ts`) on trunk.
If either 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**:

The rest: https://github.com/nanocoai/nanoclaw/blob/HEAD/.claude/skills/add-codex/SKILL.md