Codex features a single-command importer that automates the migration of most Claude Code settings. The core engineering challenge lies in the operational nuances: certain configuration blocks require manual reassembly, and one component cannot be migrated natively — the Anthropic Claude models themselves.

Migrating the entire configuration suite from Claude Code to Codex takes approximately 20 minutes. Below is an executive breakdown of the migration landscape.

1. What Can Be Migrated and What Cannot — Quick Verdict

1.1. Quick Assessment: Surface Compatibility Matrix

Question	Solution / Answer
Can most of the configuration be migrated?	Yes. 9 out of 12 surfaces migrate or rebuild without friction.
What is the fastest path?	Run `codex` → `/import` (Codex 0.140+), then manually refine 3 items.
What is migrated automatically?	Memory files, MCP servers, skills, slash commands, custom endpoints.
What requires manual refinement?	Permission model, hook event format, subagent wrapper definitions.
What is the only real dead end?	Anthropic Claude models. Vanilla Codex only supports OpenAI models natively.
What is the workaround for the dead end?	Configure an API gateway as a `model_provider` to continue running Claude in Codex.

📌 Environment Versions: This guide was tested on Codex CLI 0.142.5 (July 1, 2026) and Claude Code 2.1.178. If you run an older Codex build, upgrade first: the /import command requires version 0.140.0+.

1.2. Automated vs Manual Migration Components

Surfaces that migrate seamlessly:

Repository guidelines and personal preferences (content of CLAUDE.md).
MCP servers — command binaries and runtime arguments translate directly.
Skills — both tools adhere to the shared Agent Skills specification.
Slash commands and reusable prompt templates.
Custom API base URLs and authentication tokens.

Surfaces that require manual translation or workarounds:

Operation-specific permission allowlists (permissions.allow) — Codex uses coarse sandbox tiers.
The ConfigChange hook event (Codex features PreCompact/PostCompact, but no config change listener).
Output styles — the output styling concept does not exist in Codex.
Anthropic models — default Codex builds route exclusively to OpenAI models; Claude requires a proxy gateway.

2. Full Map: All 12 Claude Code Configurations and Their Codex Equivalents

2.1. Comprehensive Configuration Surface Matrix

Both tools solve identical coding automation tasks using distinct serialization paradigms: Claude Code relies on JSON (settings.json, .mcp.json) and Markdown (CLAUDE.md, .claude/agents/*.md), while Codex unifies configuration in a single TOML file (~/.codex/config.toml) alongside AGENTS.md.

#	Claude Code Surface	Codex CLI Equivalent	Migration Verdict
1	`CLAUDE.md` (memory)	`AGENTS.md` (or fallback filename)	Migrated directly
2	`.mcp.json` (JSON)	`[mcp_servers.*]` in `config.toml`	Migrated with reformatting
3	`.claude/skills/`	Codex skills (`[[skills.config]]`)	Migrated directly
4	`.claude/commands/`	Slash commands / prompts	Migrated, requires restructuring
5	`.claude/agents/` (Markdown)	`.codex/agents/*.toml` files	Rebuilt as TOML
6	`settings.json` (JSON)	`config.toml` + profiles (TOML)	Rebuilt as TOML
7	`permissions.allow/ask/deny`	`approval_policy` + `sandbox_mode`	Reconceptualized
8	Hooks (`PreToolUse`, `Stop`, …)	`[[hooks.*]]` in `config.toml`	Rebuilt as TOML
9	`ConfigChange` hook	No equivalent	No direct equivalent
10	`ANTHROPIC_BASE_URL` endpoint	`[model_providers.*]`	Migrated directly
11	`outputStyle`	No equivalent	No direct equivalent
12	Anthropic Claude models	OpenAI models only by default	Dead end (bypassed via gateway)

2.2. Core Architectural Differences: JSON vs TOML

Rows 9 and 11 are cosmetic: outputStyle has negligible operational impact, and ConfigChange is only relevant for advanced session-dynamic tooling.

The true operational hurdle is Row 12 (Anthropic models). However, defining a custom proxy in the [model_providers] table allows developers to continue leveraging Claude Opus and Sonnet within the Codex execution sandbox.

3. When to Migrate and When to Stay on Claude Code

3.1. Workflows and Criteria for Migrating to Codex

Migrating to Codex is advantageous when workflows prioritize autonomous task execution and strict filesystem isolation:

Headless CI/CD Automation: Executing agent pipelines non-interactively with predictable read-only or workspace-write sandboxes.
Team Standardization: Committing a unified config.toml with preset risk profiles instead of managing scattered .claude/settings.local.json overrides.
Latest OpenAI Models: Utilizing gpt-5.5 and gpt-5.4 as primary code synthesis engines.

3.2. When You Should Remain on Claude Code

Retain Claude Code if your development loop exhibits the following characteristics:

Reliance on Specific Hooks: Your automation depends on ConfigChange triggers or outputStyle formatting flags.
Interactive Conversational Flows: Your primary usage involves extensive conversational back-and-forth; Claude Code's conversational memory handles dialogue loops better than Codex's batch task-and-review cycle.
Granular Allowlist Rules: If you rely on complex glob patterns covering every terminal command, transitioning to Codex's coarser sandbox levels will require re-evaluating your operational security model.

💡 Stop Rule: If your primary goal is merely benchmarking Codex models on an existing codebase, do not overhaul your entire configuration. Point Codex to the repository, execute /import, and evaluate the results. Deep manual reconfiguration is only required when adopting Codex as your primary driver.

4. System Requirements Before Starting

4.1. CLI Version Checks, Project State, and Permissions

Before modifying configuration files, verify four prerequisites:

Codex CLI version 0.140.0 or higher: Check your installed binary via codex --version.
Untouched Claude Code Project: Keep the .claude/ directory and CLAUDE.md intact until migration is fully verified.
Valid API Key: Ensure an active OpenAI API key or a third-party gateway key (e.g. ofox.ai) for Anthropic model routing.
Filesystem Permissions: Ensure write access to ~/.codex/config.toml for persistent user configuration.

4.2. Migration Path: Step-by-Step Transition Pipeline

The migration follows a structured six-stage transition pipeline:

mermaid

flowchart LR A["Audit CLAUDE.md + settings.json"] --> B["Run codex /import"] B --> C["Review conflict report"] C --> D["Manually refine permissions + hooks"] D --> E["Add model_provider for Claude"] E --> F["Test with read-only profile"]

5. Step-by-Step Configuration Migration

5.1. Step 1: Run the Automated Importer (/import)

Open your project root and invoke the interactive Codex importer:

bash

cd my-project codex # Inside the Codex interactive session: /import

The /import command selectively ports settings, project instructions, and recent conversation contexts. This generates an initial ~/.codex/config.toml, drafts an AGENTS.md file, and displays an itemized report of skipped or conflicting fields.

5.2. Step 2: Instructions — Migrate from CLAUDE.md to AGENTS.md

Codex looks for AGENTS.md by default. To maintain backwards compatibility or avoid renaming existing files, specify fallback lookup filenames:

toml

# ~/.codex/config.toml project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"] project_doc_max_bytes = 32768

Your system instructions, coding conventions, build commands, and testing guidelines will load into Codex's context window without modification.

5.3. Step 3: MCP Servers — Convert from JSON to TOML

Both ecosystems implement the Model Context Protocol. The underlying server binaries remain identical; only the declarative syntax shifts from JSON to TOML.

Original entry in .mcp.json:

json

{ "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] } } }

Equivalent entry in ~/.codex/config.toml:

toml

[mcp_servers.github] command = "npx" args = ["-y", "@modelcontextprotocol/server-github"]

To provide environment variables, configure them inline: env = { GITHUB_TOKEN = "..." }. Both local STDIO processes and remote streaming HTTP/SSE transports are supported.

5.4. Step 4: Subagents — Configure in .codex/agents/

Claude Code organizes subagents as Markdown documents in .claude/agents/. Codex uses dedicated TOML files stored under ~/.codex/agents/ (user-level) or .codex/agents/ (project-level):

toml

# .codex/agents/reviewer.toml name = "reviewer" description = "Reviews diffs for correctness and style" developer_instructions = """ Review the diff for correctness and style. Cite file and line for each issue found. """

Subagents in Codex are enabled by default and are invoked upon explicit request by the user or coordinating agent.

5.5. Step 5: Permission Model — Configure Sandbox and Approval

Security architectures differ fundamentally: instead of an operation-specific glob allowlist (permissions.allow), Codex relies on filesystem isolation (sandbox_mode) and confirmation policies (approval_policy).

Claude Code Pattern	Purpose	Codex Equivalent (`~/.codex/config.toml`)
`allow: ["Bash(npm run test *)"]`	Unprompted safe execution	`sandbox_mode = "workspace-write"` `approval_policy = "on-request"`
`ask: ["Bash(python *)"]`	Require confirmation before execution	`approval_policy = "on-request"`
`deny: ["Read(./.env)"]`	Block sensitive out-of-bounds paths	`sandbox_mode = "workspace-write"`
`Plan mode`	Non-destructive analytical mode	`sandbox_mode = "read-only"`
`--dangerously-skip-permissions`	Full autonomy	`approval_policy = "never"` `sandbox_mode = "danger-full-access"`

Recommended balanced baseline configuration:

toml

# ~/.codex/config.toml approval_policy = "on-request" sandbox_mode = "workspace-write"

5.6. Step 6: Hooks — Port Lifecycle Event Handlers

Codex natively supports lifecycle hooks across key operational events: PreToolUse, PostToolUse, SessionStart, Stop, PreCompact, and PostCompact.

toml

# ~/.codex/config.toml [[hooks.PreToolUse]] matcher = "^Bash$" [[hooks.PreToolUse.hooks]] type = "command" command = "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use.sh"

⚠️ Important Note: The ConfigChange hook is unsupported in Codex. Dynamic automations that react to runtime configuration edits must be shifted to pre-session launch scripts.

6. Migration Dead End: Claude Models in Codex and How to Keep Them

6.1. Custom model_provider Gateway Architecture for Anthropic

Codex is designed around OpenAI models (gpt-5.5, gpt-5.4) and does not natively expose Anthropic endpoints. To utilize Claude Opus or Sonnet within the Codex harness, declare a custom OpenAI-compatible proxy gateway.

toml

# ~/.codex/config.toml [model_providers.ofox] name = "ofox.ai gateway" base_url = "https://api.ofox.ai/v1" env_key = "OFOX_API_KEY" wire_api = "responses" requires_openai_auth = false

6.2. Configuring wire_api=responses and Activating Claude Profile

When declaring custom providers, two directives are essential:

wire_api = "responses": Support for the legacy chat protocol was removed from Codex in February 2026.
requires_openai_auth = false: Prevents the CLI from expecting standard sk- OpenAI token formats.

Create a profile in ~/.codex/claude.config.toml:

toml

# ~/.codex/claude.config.toml model = "anthropic/claude-opus-4.8" model_provider = "ofox"

Execute Codex with the designated profile:

bash

codex --profile claude

7. Common Migration Mistakes and Solutions

7.1. Troubleshooting Matrix and Root Cause Analysis

Symptom	Root Cause	Engineering Solution
Codex ignores `CLAUDE.md`	Defaults to looking for `AGENTS.md`	Rename the file or add `project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"]`
Custom provider yields `401 Unauthorized`	Client expects OpenAI tokens with `sk-` prefix	Add `requires_openai_auth = false` in `[model_providers.*]`
Startup crash: `chat wire API deprecated`	Legacy `chat` protocol removed	Specify `wire_api = "responses"`
Subagents fail to act	Missing TOML definition or missing explicit call	Create `.codex/agents/NAME.toml`; Codex only triggers agents when explicitly called
Hooks fail to execute	Invalid event label or broken regex matcher	Verify event syntax and check `matcher` regex in `[[hooks.*]]`
Commands previously allowed are blocked	Codex sandbox is coarser than granular rules	Widen `sandbox_mode` or set `approval_policy = "on-request"`

7.2. Project Trust Settings and Configuration Precedence

If .codex/config.toml at the project level is ignored, check project trust status. For security reasons, Codex only evaluates project-level configurations within trusted directories, and intentionally forbids local project files from overriding global authentication or model providers.

8. Team Migration

8.1. Centralized config.toml vs Individual .local.json Overrides

In Claude Code, teams routinely balanced two layers: shared .claude/settings.json and git-ignored local .claude/settings.local.json. Codex simplifies this into a cleaner hierarchy:

Collaboration Aspect	Claude Code	OpenAI Codex CLI
Shared Team Configuration	`.claude/settings.json` (committed)	`.codex/config.toml` (committed to repo)
Developer Overrides	`.claude/settings.local.json`	Personal profile files in `~/.codex/`
Base Project Instructions	`CLAUDE.md`	`AGENTS.md`
Risk Tiers	`permission allowlist`	CLI flags: `--profile strict` vs `--profile fast`

8.2. Shared API Gateway and Unified Team Billing

Leveraging a centralized model_provider streamlines team finances and key distribution:

The team repository commits baseline gateway definitions in .codex/config.toml.
Developers supply their credentials via corporate secret managers (OFOX_API_KEY).
The entire engineering team accesses a unified billing endpoint, whether individuals run openai/gpt-5.5 or anthropic/claude-opus-4.8.

9. Advanced Level: Profiles for CI, Local Work, and Review

9.1. Configuring Tiered Security Profiles

Profiles are independent configuration files stored in ~/.codex/ and invoked on demand via --profile. This cleanly eliminates the need to rewrite global settings between distinct workflows.

Example configuration for automated CI review:

toml

# ~/.codex/ci.config.toml model = "gpt-5.5" approval_policy = "never" sandbox_mode = "read-only"

9.2. Practical Scenarios: Isolated CI Review and Local Development

Executing codex --profile ci guarantees read-only repository inspection without risking unintended modifications or network leaks.

Daily active development uses local.config.toml with sandbox_mode = "workspace-write", while complex architectural reasoning is delegated to codex --profile claude, running Claude Opus without changing baseline developer credentials.

10. Frequently Asked Questions (FAQ)

10.1. Model Compatibility and Configuration Files

❓ Can I use Anthropic Claude models directly in Codex CLI?
Native Codex builds connect exclusively to OpenAI models. However, you can access any Claude model (such as anthropic/claude-opus-4.8) by establishing an OpenAI-compatible proxy gateway in [model_providers] and referencing it in your profile.

❓ Does Codex CLI read the legacy CLAUDE.md instruction file?
Codex defaults to reading AGENTS.md. To retain your existing file without duplication, define project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"] in your ~/.codex/config.toml.

❓ How do I rapidly import an existing Claude Code configuration?
Launch codex in the repository root and enter /import. The automated importer migrates instructions, MCP definitions, and contextual prompts, while surfacing an itemized checklist of settings requiring manual adjustment.

❓ Are AGENTS.md and CLAUDE.md interchangeable?
Functionally, yes. AGENTS.md represents an open cross-tool specification adopted across modern coding agents, whereas CLAUDE.md is Anthropic's proprietary format. The underlying instruction syntax is parsed identically.

10.2. Technical Specifications of Hooks, MCP, and Subagents

❓ Does Codex CLI support lifecycle hooks like Claude Code?
Yes, hooks are enabled out of the box. Supported lifecycle hooks include PreToolUse, PostToolUse, SessionStart, Stop, PreCompact, and PostCompact. The only Claude Code hook without an equivalent is ConfigChange.

❓ Can Claude Code and Codex share the same MCP servers?
Yes. The underlying MCP protocol and binaries are identical. Only the declaration syntax changes from JSON format in .mcp.json to structured TOML tables in config.toml.

❓ Do I need to rewrite subagent definitions when migrating?
No, prompt instructions are preserved intact. You only need to adjust the enclosing wrapper: copy instructions from Markdown files in .claude/agents/*.md into the developer_instructions multi-line string within .codex/agents/*.toml.