从 Claude Code 迁移到 Codex 的诚实指南：12 项配置全映射与 1 个死胡同

你用 Claude Code 已经大半年了。

你的 .claude/ 目录里堆满了精心调教过的配置：十几个 MCP 服务器、五个专用的 subagent、一套精确到命令级别的权限白名单，还有一堆 hooks 脚本。每次 claude 回车，一切都运转得像瑞士手表一样精准。

但你也注意到了，Codex 这边的变化越来越快。0.140 版本加入了 /import 命令，0.142 进一步完善了沙箱和 hooks 机制。你开始琢磨：是不是该试试搬过去了？

这个问题我问过自己，也帮几个团队实际走过一遍。结论是：大部分迁移是机械的，小部分需要重新理解，有一个地方必须用额外工具绕过去。 这篇文章把 12 个配置项一一拆开，告诉你每一步会发生什么。

30 秒速览：能迁吗？#

本文基于 Codex CLI 0.142.5（2026 年 7 月 1 日）和 Claude Code 2.1.178 实测。如果你用的是更老的 Codex，先升级，/import 命令在 0.140.0 之前根本不存在。

为什么现在值得迁移？#

在动手之前，先想清楚一个根本问题：你到底为什么要迁移？

Claude Code 和 Codex 背后的设计哲学有本质差异。Claude Code 是一个对话驱动的工具，它的核心循环是「你问我答，边聊边改」。Codex 是一个任务驱动的工具，它的核心循环是「你给我一个目标，我规划、执行、验证，回来汇报结果」。

这个差异渗透到每一个配置项里。

迁移的真正收益#

• 沙箱粒度更清晰。Codex 的 read-only、workspace-write、danger-full-access 三级沙箱虽然比 Claude Code 的细粒度白名单粗，但在 CI/非交互场景下反而是优势，因为行为可预测，不会因为漏配一个 glob 规则导致构建卡住。
• 配置结构更统一。Claude Code 的配置分散在 settings.json、.mcp.json、.claude/agents/*.md 等五个地方。Codex 把几乎所有东西收拢到一个 config.toml 里，外加 profile 文件做场景切换，心智负担明显更低。
• 团队协作更友好。Claude Code 需要提交一份 settings.json，每人再维护一份 gitignore 的 settings.local.json。Codex 只需要一份 .codex/config.toml，个人差异用 --profile 切换。对于有 5 个以上开发者的团队，这个差异会被放大。

什么时候不该迁移#

如果你的日常工作方式是「打开终端，和 Claude 聊一个小时，边聊边重构一个模块」，那 Claude Code 的交互模型可能更适合你。Codex 的任务循环在长对话场景下不如 Claude Code 自然，强行切换反而会降低效率。

另外，如果你重度依赖 ConfigChange hook（在配置文件中途变化时触发自动化逻辑），或者对 outputStyle 有定制需求，Codex 目前没有对应能力。

简单原则：任务型工作用 Codex，对话型工作留 Claude Code。 两者不互斥，你完全可以两个都用。

12 项配置逐项映射#

下面这张表是整个迁移的核心。打印出来，贴在显示器旁边。

第 9 和第 11 项是「没有也行」的类型。你不会想念 outputStyle，而 ConfigChange 只在一种场景下有用：你有一个自动化脚本，监听配置文件的变化并在会话中途做出反应。这种场景本身就不常见。

第 12 项是真正的卡点，我们最后单独讲。

实战：六步走完迁移#

第一步：跑 /import#

先别急着手改。Codex 的 /import 能自动吃掉大部分脏活：

cd my-project
codex
# 进入会话后：
/import

Codex 会弹出选项让你选要导入哪些内容：项目配置、setup、最近的聊天记录。选完等几秒，你会得到一个初步填充的 ~/.codex/config.toml、一份 AGENTS.md 草稿，以及一份简短的冲突报告，列出它跳过了什么、为什么。

不要跳过这一步，然后手工从头写。/import 虽然不完美，但它节省的时间远超后续手修的时间。

第二步：CLAUDE.md → AGENTS.md#

Codex 读的是 AGENTS.md，不是 CLAUDE.md。如果 /import 没有自动创建，你有两个选择：

# ~/.codex/config.toml
# 方案 A：直接改名
# mv CLAUDE.md AGENTS.md

# 方案 B：让 Codex 同时读两个文件名
project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"]
project_doc_max_bytes = 32768

我推荐方案 A，干净直接。AGENTS.md 本身就是一个跨工具的约定，Anthropic 和 OpenAI 都在用。

第三步：MCP 服务器，JSON → TOML#

MCP 服务器本身不需要任何改动，只有声明格式变了。Claude Code 的 .mcp.json：

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

在 Codex 里变成 ~/.codex/config.toml 中的一个 table：

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

启动 Codex 时会自动列出所有已注册的 MCP 工具。如果需要环境变量，加一行 env = { "GITHUB_TOKEN" = "..." } 即可。STDIO 和 HTTP 两种传输方式都支持，远端 MCP 端点也能直接注册而不用在本地起进程。

第四步：Subagent 重写包装#

这一步最枯燥，但不复杂。Claude Code 把 subagent 存为 .claude/agents/ 下的 Markdown 文件，Codex 要求每个 subagent 一个独立的 .codex/agents/NAME.toml 文件，按项目或全局放置。

# .codex/agents/reviewer.toml
name = "reviewer"
description = "审查 diff 的正确性和代码风格"
developer_instructions = """
逐行审查 diff。对每个问题，指出文件和行号。
"""

你的旧 Markdown prompt 内容直接搬到 developer_instructions 字段，不需要改写。Subagent 默认开启，不需要额外的 feature flag。

如果你有 5 个以上的 subagent，这是整个迁移中最耗时的手工步骤，但它纯机械，不需要动脑子。

第五步：权限模型，从白名单到沙箱#

这是唯一一个「会坏」的配置面，因为两个工具的权限模型设计理念完全不同。

Claude Code 用细粒度的命令白名单：allow: ["Bash(npm run test *)"] 精确到命令名和 glob 匹配。Codex 用两级粗调旋钮：sandbox_mode 控制文件系统边界，approval_policy 控制是否需要人工确认。

一个合理的默认值：

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

这样 Codex 在仓库内自由操作，访问外部或网络时会请求确认。如果你之前花了很多时间精心调校 Claude Code 的权限白名单，迁移到这里会有一段适应期。Codex 的模型更粗，但更可预测。

第六步：Hooks 迁移#

Codex 的 hooks 现在默认开启，覆盖了 Claude Code 的大部分事件。声明方式从 JSON 变成 TOML 的 array-of-tables：

# ~/.codex/config.toml
[[hooks.PreToolUse]]
matcher = "^Bash$"

  [[hooks.PreToolUse.hooks]]
  type = "command"
  command = "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use.sh"

支持的事件包括 PreToolUse、PostToolUse、SessionStart、Stop、PreCompact 和 PostCompact。唯一缺失的是 ConfigChange，但正如前面提到的，绝大多数用户根本没用过。

唯一死胡同：Claude 模型怎么办？#

这是整个迁移里唯一一个没有原生答案的问题。Codex 的认证体系绑定 OpenAI，模型列表里只有 gpt-5.5、gpt-5.4 这些。没有开关能直接切换到 Claude Opus 或 Sonnet。

但这不是终点，只是一个岔路口。

解法是注册一个自定义 model_provider。Codex 可以和任何 OpenAI 兼容的 API 网关通信，你只需在 ~/.codex/config.toml 里加一段配置：

[model_providers.my_gateway]
name = "我的网关"
base_url = "https://api.my-gateway.com/v1"
env_key = "GATEWAY_API_KEY"
wire_api = "responses"
requires_openai_auth = false

两个容易踩到的坑：

1. wire_api 必须设为 "responses"。Codex 在 2026 年 2 月移除了对旧 chat 协议的支持，设成 "chat" 会在启动时报错。确保你的网关提供 Responses 兼容端点。
2. requires_openai_auth = false。Codex 默认期望 sk- 前缀的 OpenAI 密钥。如果你的网关用的是自己的密钥格式，必须关掉这个检查。

然后创建一个 profile 文件 ~/.codex/claude.config.toml：

model = "anthropic/claude-opus-4.8"
model_provider = "my_gateway"

用 codex --profile claude 启动，Codex 的任务循环和沙箱机制不变，但模型后端换成了 Claude。你甚至可以为不同场景创建多个 profile，在同一套配置上 A/B 对比 OpenAI 和 Anthropic 的模型效果。

团队迁移：比个人更简单#

如果你在带团队，迁移实际上比个人场景更干净。Claude Code 时代，你需要提交 .claude/settings.json 给全队共享，每人再维护一份 gitignored 的 .claude/settings.local.json 放个人偏好。两份文件，两套覆盖逻辑，新人经常搞混。

Codex 的方案更直观：

最实用的团队场景是上文的网关模式：在提交的 .codex/config.toml 里注册一个 model_provider，通过密钥管理器分发同一套 API Key，整个团队共享一个计费视角，不论用 gpt-5.5 还是 claude-opus-4.8。

常见问题速查#

如果你的项目级 .codex/config.toml 完全被忽略，检查项目是否被标记为受信（trusted）。Codex 只在受信目录加载项目级配置。

我的建议：渐进式迁移#

读完这篇文章，你不需要一次性把所有东西都搬过去。

最务实的路径是这样的：第一周，在一个副项目上跑 /import，感受一下 CLI 交互节奏的差异。第二周，把 MCP 服务器和 AGENTS.md 迁过去，用 --profile 区分实验和正式配置。第三周，处理 subagent 和 hooks。如果一切顺利，第四周你就可以正式切换。

在这个过程中，你可能会发现 Claude Code 和 Codex 其实不是非此即彼。它们有各自最适合的场景。Claude Code 擅长深度对话式编程，Codex 擅长结构化任务执行。两者并存并不矛盾。

迁移的价值不在于「换个工具」，而在于通过对比两个工具的配置体系，你被迫重新审视自己的开发流程。哪些权限规则是真正需要的？哪些 hooks 其实从来没触发过？哪些 subagent 定义得太模糊以至于 AI 根本不理解？这些问题在你日常使用一个工具的时候很少会去想，但迁移天然迫使你面对它们。

参考来源：Owen Fox, “Migrate Claude Code to Codex (2026): 12 Configs, 1 Dead End”, dev.to, 2026-07-03.