Skip to content

MIGRATION.md

Latest commit

 

History

History
83 lines (58 loc) · 2.52 KB

MIGRATION.md

File metadata and controls

83 lines (58 loc) · 2.52 KB
Raw

Migration Guide: Claude SDK → Codex CLI

This guide walks you through migrating Auto-Codex from the Claude SDK to the OpenAI Codex CLI.

1) Install Codex CLI

npm install -g @openai/codex
codex --version

2) Update Environment Variables

  1. Copy the example file if you have not already:
cd auto-codex
cp .env.example .env
  1. Replace the old token with a Codex auth option:
# Remove this (old)
# CLAUDE_CODE_OAUTH_TOKEN=...

# Add one of these (new)
OPENAI_API_KEY=sk-...
# or CODEX_CODE_OAUTH_TOKEN=... (from Codex CLI login, e.g. `codex login --device-auth`)
# or CODEX_CONFIG_DIR=/path/to/codex/config
  1. (Optional) Set a Codex model override:
AUTO_BUILD_MODEL=gpt-5.2-codex
# Optional reasoning effort override (recommended over model suffixes)
AUTO_BUILD_REASONING_EFFORT=xhigh

3) Verify Codex CLI Works

printf "Hello from Codex\n" | codex exec --json -m gpt-5.2-codex -c model_reasoning_effort=xhigh -

You should see JSON output with a message event.

4) Run Auto-Codex

python3 auto-codex/run.py --spec 001

Environment Variable Changes

  • CLAUDE_CODE_OAUTH_TOKEN → removed (legacy Claude token)
  • OPENAI_API_KEY → supported for Codex CLI
  • CODEX_CODE_OAUTH_TOKEN → supported (OAuth token)
  • CODEX_CONFIG_DIR → supported (Codex CLI config directory)
  • AUTO_BUILD_MODEL → optional model override (default: gpt-5.2-codex)
  • AUTO_BUILD_REASONING_EFFORT → optional reasoning effort override (default: medium)

API/Behavior Differences

  • Provider: Claude SDK calls are replaced with Codex CLI subprocess calls.
  • Auth: Use OPENAI_API_KEY, CODEX_CODE_OAUTH_TOKEN, or CODEX_CONFIG_DIR.
  • Execution: Codex CLI runs as a local process (codex exec --json) with streamed JSON events.
  • Models: Model IDs use the base model name (default gpt-5.2-codex); set reasoning via model_reasoning_effort.

FAQ

Q: Do I still need a Claude subscription? No. Codex CLI uses OpenAI credentials only.

Q: Where do I put authentication? Set OPENAI_API_KEY or CODEX_CODE_OAUTH_TOKEN in auto-codex/.env, or export them in your shell. You can also set CODEX_CONFIG_DIR to point at an existing Codex CLI profile, or rely on the default ~/.codex config directory.

Q: Can I keep my old .env file? Yes, but remove CLAUDE_CODE_OAUTH_TOKEN and add one of OPENAI_API_KEY, CODEX_CODE_OAUTH_TOKEN, or CODEX_CONFIG_DIR.

Q: How do I confirm the CLI is available? Run codex --version or the JSON test command above.