Switching from Claude Code to Codex: The Complete 2026 Migration Guide (with Relay Configuration)

In June 2026, one event threw a lot of developers' routines into chaos: Anthropic's flagship models, Fable 5 and Mythos 5, went dark overnight for users worldwide due to export controls — a ban that lasted a full 20 days. Even though it was lifted in July, the episode drove home a real risk: tying your entire workflow to a single tool is expensive when things go wrong. Around the same time, OpenAI Codex shipped a wave of key updates in June — Codex Remote reached GA, mobile monitoring launched, and Amazon Bedrock integration landed — pushing weekly active developers from 3 million to 5 million. This piece pulls together every key step for migrating from Claude Code to Codex, including the relay setup that matters most to developers outside the US.

Why Are More Developers Moving to Codex?

Different developers have different motivations, but they generally boil down to four things:

Before You Switch: Claude Code vs. Codex Core Differences

The data tells one clear story: GPT-5.5 edges ahead on SWE-bench Verified, but on the harder SWE-bench Pro, Claude Opus 4.8 leads by about 6%. Each tool has its own strengths — we'll get into how to run both together later.

Step 1: Install Codex

There are two ways to install Codex — pick the one that fits how you work.

Option A: Codex CLI (terminal, closest to the Claude Code experience)

# Install (requires Node.js 18+)
npm install -g @openai/codex

# Verify the install
codex --version

After installing, running codex for the first time prompts you to log in — you can use a ChatGPT account (Plus/Pro/Business/Enterprise all work) or enter an OpenAI API key directly.

Option B: Codex desktop app (GUI, with auto-migration built in)

Download the macOS/Windows installer from openai.com/codex. The desktop app has a built-in "import config from another agent" feature (Settings → Import agent setup) that automatically scans your Claude Code config and migrates Skills, Hooks, MCP config, and 30 days of session history.

Step 2: Configure Your API Key

Accessing the official OpenAI API from outside the US typically requires a proxy. There are two paths here: direct connection (needs a VPN) or a relay (direct connect, no VPN).

Option A: Direct connection to the official OpenAI API (needs a proxy)

# macOS / Linux — add this to ~/.zshrc to persist it
export OPENAI_API_KEY=sk-your-openai-api-key

# Reload
source ~/.zshrc

# Launch Codex
codex

# Windows PowerShell
$env:OPENAI_API_KEY="sk-your-openai-api-key"

# Or set it permanently as a system environment variable:
# System Properties → Advanced → Environment Variables → New: OPENAI_API_KEY

Option B: Access via an API relay (direct connect, no VPN needed)

This is the most practical option for developers outside the US. Relays that support GPT-5.5 (codex-1) only need two environment variables set — the rest of the config is identical to Option A:

# macOS / Linux
export OPENAI_API_KEY=your-relay-api-key
export OPENAI_BASE_URL=https://your-relay-domain.com/v1

source ~/.zshrc
codex

# Windows PowerShell
$env:OPENAI_API_KEY="your-relay-api-key"
$env:OPENAI_BASE_URL="https://your-relay-domain.com/v1"

Core things to check when picking a relay:

• Explicit support for GPT-5.5 / codex-1: Codex uses the codex-1 model (an agentic-tuned variant of GPT-5.5) — the relay must have it in its model list
• OpenAI format (/v1/chat/completions): Codex speaks the OpenAI protocol, so confirm the relay's endpoint path is compatible with the standard OpenAI SDK
• Direct-connect nodes: prefer relays with nodes optimized for your region to reduce connection timeouts, e.g., on an office network
• Stable function calling: Codex's agentic mode leans heavily on tool calls — if a relay mishandles this, agent behavior will misbehave

You can filter our AI API relay comparison list for relays whose "model coverage" includes GPT-5.5 — most of the listed ones have been verified to support Codex-compatible protocols.

Step 3: Migrate CLAUDE.md → AGENTS.md

Claude Code stores project-level AI instructions in CLAUDE.md; Codex's equivalent file is AGENTS.md. The simplest starting point is a straight copy:

# From your project root
cp CLAUDE.md AGENTS.md

That said, a plain copy is only a starting point. There are some meaningful semantic differences between the two files — after migrating, check the following:

Step 4: Reconfigure MCP Servers

MCP is an open standard, and both Claude Code and Codex support it, so the servers themselves need no changes. What changes is the format of the connection config file: JSON for Claude Code, TOML for Codex.

Claude Code's MCP config (JSON, usually in ~/.claude/settings.json):

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@myorg/mcp-server"],
      "env": {
        "MY_API_KEY": "sk-xxx"
      }
    }
  }
}

Migrated to Codex's TOML format (~/.codex/config.toml):

[mcp_servers.my-server]
command = "npx"
args = ["-y", "@myorg/mcp-server"]

[mcp_servers.my-server.env]
MY_API_KEY = "sk-xxx"

Step 5: Verify Codex's Basic Workflow

Once configured, use these steps to verify Codex is working correctly:

# 1. Launch Codex inside a real project directory
cd ~/your-project
codex

# 2. Check the current config
/model        # Confirm the model is correct (should show gpt-5.5 / codex-1)

# 3. Test with a small task (use --dry-run first to preview without executing)
codex --dry-run "Find all hardcoded TODO comments under src/ and list the filenames"

# 4. Confirm tool calling works (MCP verification)
# If you have an MCP server installed, ask Codex to call an MCP tool in
# conversation and check that it responds correctly

Common Errors When Using a Relay

If you run into issues connecting through a relay, check these first:

1. 401 Unauthorized: OPENAI_API_KEY is wrong, or the relay's key format isn't compatible with the OpenAI standard. Confirm the key starts with the right prefix and check the relay's docs for its key format requirements.
2. 404 / model not found: the relay doesn't support codex-1 or gpt-5.5 as a model ID. Try manually specifying the model when launching Codex: codex --model gpt-5.5, or contact the relay to confirm the exact model ID string they expect.
3. Tool call parsing fails / agent behaves oddly: the relay has issues passing through tool calls correctly. Switch to a relay with better function-calling support, or temporarily fall back to plain conversation mode (no tool calls) to confirm whether the relay is the culprit.
4. Environment variables aren't taking effect: you edited ~/.zshrc but forgot to run source ~/.zshrc, or you changed variables in an already-open terminal session without restarting it. Open a new terminal tab and run echo $OPENAI_BASE_URL to confirm it loaded.

Codex Remote: Push Long Tasks to the Cloud

This is Codex's biggest differentiator versus Claude Code. Codex Remote (GA as of June 2026) lets you:

• Submit a task from the ChatGPT web app or mobile app, close your laptop, and have it keep running in OpenAI's isolated cloud sandbox
• Get results back automatically as a pull request on your GitHub repo — you just review and merge
• Run multiple tasks in parallel without blocking each other or eating local machine resources
• Use the mobile app (iOS public beta since June 29) to submit tasks on your commute, get PR notifications, and review code remotely

A typical use case: before you leave for the day, hand "write unit tests for feature X" to Codex Remote, and the next morning a PR is already waiting for review — with your machine never having to stay powered on.

# Connect your GitHub repo (one-time authorization)
codex connect github

# Submit a background task
codex remote "Add JSDoc comments to every function under src/auth/, with full type annotations"

# Check task status
codex remote status

# List PRs awaiting review
codex remote prs

You Don't Have to Choose: Running Claude Code + Codex Together Is the Best Setup

The clearest community consensus over the past six months is this: the most productive developers run both tools, routing tasks based on their characteristics.

In practice, a lot of teams reserve Claude Code for interactive, deep-thinking sessions, use Codex (especially Remote) for background batch work and automated PR generation, and manage keys and quota for both sides through a single API relay.

What You Lose After Switching — Know This Upfront

Summary

Migrating to Codex isn't a one-click affair, but it's less involved than it sounds. There are really only four core steps: install the CLI → configure your API key (relay users set OPENAI_BASE_URL) → rename and lightly edit CLAUDE.md into AGENTS.md → rewrite your MCP config from JSON to TOML. Give it 30 minutes and Codex is up and running — you can tune it further as you go.

The more important takeaway: you don't have to uninstall Claude Code. Each tool has its own strengths, and running both is the most productive setup in 2026. Adding Codex to your toolchain means that when one tool hits a ban, an outage, or runs out of quota, the other can pick up the slack — that's a more valuable engineering decision than optimizing around any single tool.

Sources

• How to Switch from Claude Code to OpenAI Codex: The Complete Developer Guide (2026) – Medium / Software Mind
• Switching from Claude Code to OpenAI Codex – Awesome Agents
• From Claude Code to Codex: A Practical Migration Guide for Developers in 2026 – Pasquale Pillitteri
• Claude Code to Codex Migration Guide 2026 – Blake Crosley
• Claude Code to Codex Migration: One-Click Import Guide – MindWiredAI
• Claude Code vs Codex: Which AI Coding Agent Should You Use in 2026? – Firecrawl
• Codex vs Claude Code (June 2026): Benchmarks, Subagents & Limits Compared – MorphLLM
• AI Coding Costs (2026): Claude vs Codex vs Gemini, Real Monthly Spend – MorphLLM
• Claude Code vs Codex: What I Learned After 100+ Hours With Both (2026) – Composio
• Claude Code vs OpenAI Codex: $20/mo Each but OpenAI Claims 4x Better Efficiency – SpectrumAILab
• Codex vs Claude Code in June 2026: The Fable 5 Era Rematch – Developers Digest
• Claude Code vs Codex App in 2026: Local Agent Pairing vs Cloud Agent Orchestration – Developers Digest
• Codex vs Claude Code: Which AI Coding Agent Should You Use in 2026? – MindStudio
• Codex vs. Claude Code: Context Window, Token Efficiency, and Which Lasts Longer – MindStudio
• Sync Codex and Claude Code configs: skills, agents, MCP, permissions – OpenAI Developer Community
• OpenAI Codex Step by Step Guide: Setup, Claude Code, and Cost in 2026 – GenAI Unplugged
• Codex Quickstart – OpenAI Developers (official docs)
• Codex Environment Variables – OpenAI Developers (official docs)
• Codex Unlocked: A Complete Guide to Accessing OpenAI Codex via a Self-Hosted API Relay – Kejilion
• Claude Code, Codex, OpenClaw: How I Got Them Working Together – Wang Shuyi