{"id":"add-codex","name":"add-codex","summary":"Codex(OpenAIのCodexアプリサーバー)をフルエージェントプロバイダーとして活用しましょう — 計画、ツールオーケストレーション、MCPツール、サーバー側履歴、セッション再開など、Claudeと並行または代わりに。","body":"# Codex agent provider\n\n> 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.\n\nNanoClaw 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.\n\nThe 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**: OneCLI 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.\n\nThe 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.\n\n## Install\n\n### Pre-flight\n\nCheck 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**:\n\n- `src/providers/codex.ts` and `src/providers/codex-agents-md.ts`\n- `container/agent-runner/src/providers/codex.ts` and `codex-app-server.ts`\n- `setup/providers/codex.ts`\n- `import './codex.js';` in `src/providers/index.ts`, `container/agent-runner/src/providers/index.ts`, and `setup/providers/index.ts`\n- an `@openai/codex` entry in `container/cli-tools.json`\n\n### 1. Fetch and copy the payload\n\nFetch 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 + AGENTS.md compose + 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.\n\n```nc:copy from-branch:providers\nsrc/providers/codex.ts\nsrc/providers/codex-agents-md.ts\nsrc/providers/codex-registration.test.ts\nsrc/providers/codex-host-contribution.test.ts\nsrc/providers/codex-agents-md.test.ts\ncontainer/agent-runner/src/providers/codex.ts\ncontainer/agent-runner/src/providers/codex-app-server.ts\ncontainer/agent-runner/src/providers/exchange-archive.ts\ncontainer/agent-runner/src/providers/exchange-archive.test.ts\ncontainer/agent-runner/src/providers/codex-registration.test.ts\ncontainer/agent-runner/src/providers/codex.factory.test.ts\ncontainer/agent-runner/src/providers/codex.turns.test.ts\ncontainer/agent-runner/src/providers/codex-app-server.test.ts\ncontainer/agent-runner/src/providers/codex-cli-tools.test.ts\nsetup/providers/codex.ts\nsetup/providers/codex.test.ts\nsetup/providers/codex-registration.test.ts\ncontainer/AGENTS.md\n```\n\n### 2. Wire the barrels\n\nAppend the self-registration import to each of the three provider barrels (skipped if the line is already present). Each barrel-registration test imports its real barrel and asserts `codex` is registered — they go red the moment a barrel line is missing or drifts.\n\n```nc:append to:src/providers/index.ts\nimport './codex.js';\n```\n```nc:append to:container/agent-runner/src/providers/index.ts\nimport './codex.js';\n```\n```nc:append to:setup/providers/index.ts\nimport './codex.js';\n```\n\n### 3. CLI manifest\n\nThe 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.\n\n```nc:json-merge into:container/cli-tools.json key:name\n{ \"name\": \"@openai/codex\", \"version\": \"0.146.0\" }\n```\n\nThe version (`0.146.0`) is the canonical pin — this SKILL.md is the source of truth.\n\n### 4. Build\n\n```nc:run effect:build\npnpm run build\npnpm exec tsc -p container/agent-runner/tsconfig.json --noEmit\n./container/build.sh\n```\n\n### 5. Validate\n\n```nc:run effect:test\npnpm vitest run src/providers/codex-registration.test.ts src/providers/codex-host-contribution.test.ts src/providers/codex-agents-md.test.ts setup/providers/\n```\n```nc:run effect:test\ncd container/agent-runner && bun test src/providers/\n```\n\nThe 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.\n\n## Authenticate\n\n```nc:run effect:external\npnpm exec tsx setup/index.ts --step provider-auth codex\n```\n\nThe 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 OneCLI vault. Idempotent — it short-circuits when a matching secret already exists. It finishes with the install check.\n\n## Use it\n\nPer group:\n\n```bash\nncl groups config update --id <group-id> --provider codex\nncl groups restart --id <group-id>\n```\n\nSwitching is an operator action — run it from the host. Every provider uses the\nsame `memory/` tree, so memory carries across automatically. Run\n`/migrate-memory` only when upgrading a group that still has legacy `.seed.md`,\n`CLAUDE.local.md`, or unindexed imported memory. See\n[docs/provider-migration.md](../../docs/provider-migration.md).\n\n### Default new groups to codex (optional)\n\nNew 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.\n\nAfter install, ask the operator before flipping it:\n\n> \"Codex is installed. Default new agent groups to codex? Existing groups keep their current provider.\"\n\nOn yes — set it, then restart the host so it takes effect:\n\n```bash\npnpm exec tsx setup/index.ts --step set-env -- --key DEFAULT_AGENT_PROVIDER --value codex\nlaunchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS; Linux: systemctl --user restart nanoclaw\n```\n\nThis 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).\n\n## Troubleshooting\n\n- **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).\n- **In-channel `Error: spawn codex ENOENT` on every message:** the image predates the manifest entry — re-run `./container/build.sh`.\n- **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).","author":"@nanocoai","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/nanocoai/nanoclaw/tree/main/.claude/skills/add-codex","license":"MIT","category":"writing","lang":"en","tokens":1810,"stars":0,"calls30d":1,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"REMOVE.md","size":3261,"sha256":"35678eddfabee808b2e65b9dcb36b8939f1a19c35e0c8e03daf82dedcd95baaf"}],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":[]}}