从 Claude Code 迁移到 Codex，基本上就是一场重命名加重排格式的活儿，而 Codex 如今还自带一条单命令导入器，帮你完成其中大部分工作。真正的麻烦藏在它遗留下来的东西里，而其中一项根本就不是配置文件。

30 秒迁移结论

你大约能在 20 分钟内把几乎整套 Claude Code 配置搬到 Codex。往下翻之前，先看这份决策表：

问题	答案
我的大部分配置能迁移吗？	能。12 项配置中有 9 项能干净地迁移或重塑。
最快路径？	codex → /import（Codex 0.140+），然后手动修 3 项。
哪些会自动迁移？	记忆文件、MCP 服务器、skills、slash 命令、自定义端点。
哪些需要手动处理？	权限模型、hooks 格式、subagent 封装。
唯一的死胡同？	Anthropic Claude 模型。原生 Codex 只支持 OpenAI。
死胡同的解法？	加一个网关作为 model_provider，就能在 Codex 里继续跑 Claude。

本指南测试所用版本：Codex CLI 0.142.5（2026 年 7 月 1 日）与 Claude Code 2.1.178。如果你用的是更旧的 Codex，请先升级，因为 /import 命令在 0.140.0 之前并不存在。

今天你能迁移什么（以及不能迁移什么）

几乎一切都能迁移，因为这两个工具用不同的文件格式解决同一个问题。Claude Code 依赖 JSON（settings.json、.mcp.json）和 Markdown（CLAUDE.md、.claude/agents/*.md）。Codex 则依赖单个 TOML 文件（~/.codex/config.toml）外加 AGENTS.md。这场迁移在很大程度上就是这两种方言之间的翻译。

你能迁移的：

• 仓库级与个人指令（CLAUDE.md 的内容）

• MCP 服务器，command 和 args 原样照搬

• Skills，它们本就遵循共享的 Agent Skills 约定

• Slash 命令和可复用提示词

• 自定义 API 端点和密钥

没有变通手段就无法迁移的：

• Claude Code 的逐命令权限白名单，Codex 没有直接对应物

• ConfigChange hook 事件（Codex 有 PreCompact/PostCompact，但没有任何在配置文件变更时触发的事件）

• 输出样式（output styles），Codex 没有建模

• Anthropic 模型本身，这才是真正的拦路虎，也是最后一节存在的原因

下面是完整的配置全景图。把这张表存下来；整场迁移一屏就能看完。

#	Claude Code	Codex 对应项	结论
1	CLAUDE.md 记忆	AGENTS.md（或回退文件名）	可迁移
2	.mcp.json（JSON）	config.toml 里的 [mcp_servers.*]	可迁移，需重排格式
3	.claude/skills/	Codex skills（[[skills.config]]）	可迁移
4	.claude/commands/	Codex slash 命令 / 提示词	可迁移，需重写
5	.claude/agents/（Markdown）	.codex/agents/*.toml 文件	需重塑
6	settings.json（JSON）	config.toml + profiles（TOML）	需重塑
7	permissions.allow/ask/deny	approval_policy + sandbox_mode	会坏
8	hooks（PreToolUse、Stop……）	config.toml 里的 [[hooks.*]]	需重塑
9	ConfigChange hook	无	无对应项
10	ANTHROPIC_BASE_URL 端点	[model_providers.*]	可迁移
11	outputStyle	无	无对应项
12	Anthropic Claude 模型	只支持 OpenAI 模型	死胡同（见解法）

第 9 和第 11 行只是表面功夫。你不会想念 outputStyle，而 ConfigChange 只有在你构建了会响应配置文件中途变更的自动化时才有意义。第 12 行才是让人卡住的那一项，而它有一个大多数迁移指南都跳过的干净解法。

决策框架：何时该迁移（何时该留守）

当你的工作是任务型、且想要更严格的沙箱时，就迁移；当你的工作是对话型、由 hook 驱动时，就留在 Claude Code。这两个工具背后有不同的心智模型，配置差异也由此而来。

何时该迁移

• 你在 CI 里非交互式地运行 agent，并希望默认姿态是 read-only 或 workspace-write 沙箱。

• 你的团队想要一份提交进仓库的 config.toml，按风险级别划分 profile，而不是一个 settings.json 加上一堆 settings.local.json 覆盖文件。

• 你想把 OpenAI 当前的 Codex 模型（gpt-5.5）作为默认驱动。较旧的 gpt-5.3-codex 已于 2026-05-26 从用户可选的 Codex 模型中弃用，因此请选 gpt-5.5 或 gpt-5.4。

何时不该迁移

• 你依赖 ConfigChange hooks 或输出样式。它们在 Codex 里无处安放，所以要么预留重做的成本，要么原地不动。

• 你的整个工作流就是一场长时间的交互式结对会话。Claude Code 的对话式模型比 Codex 的任务加审查循环更契合。

• 你有一份大量手工调校的权限白名单。Codex 粗粒度的沙箱分级会让你觉得钝，把意图迁移过去需要认真思考（见步骤 5）。

何时就此打住

如果你唯一的目标只是拿现有仓库试试 Codex 的模型，那你根本不需要迁移配置。让 Codex 指向你的仓库，运行 /import，然后就此打住。本指南剩下的内容，是写给要把 Codex 当主力工具的人的。

系统要求

在动配置之前，先确认下面四个前提。Codex 版本过旧，是 /import 和 [features] 块悄悄失效的最常见原因。

• Codex CLI 0.140.0 或更新版本。 用 codex --version 检查。/import 命令在 0.140.0 落地；本指南在 0.142.5 上测试。

• 你现有的 Claude Code 项目，其 .claude/ 目录和 CLAUDE.md 保持完整。在迁移验证通过之前不要删除它。

• 一个 API 密钥，供驱动 Codex 的服务商使用。默认是 OpenAI，或者如果你要保留 Claude 模型，则用网关密钥。

• 对 ~/.codex/ 的写权限。 Codex 每次调用都会读取 ~/.codex/config.toml，在受信任项目中还会读取仓库根目录的 .codex/config.toml。

从头到尾的迁移路径长这样：

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

分步操作：映射每一项配置

先跑自动导入器，再逐个走一遍它无法完全处理的五项配置。别跳过手动环节；导入器对自己遗留的东西很诚实，但它确实会遗留一些东西。

步骤 1：运行导入器

在你的项目里启动 Codex 并导入。

cd my-project
codex
# then, inside the session:
/import

Codex 0.140 新增了 /import，用于从 Claude Code 有选择地拉取 setup、项目配置和近期对话，详见 OpenAI Codex 更新日志。挑选你想要的配置项。预期结果：一份填充好的 ~/.codex/config.toml、一份 AGENTS.md 草稿，以及一份简短报告，列出它跳过或标记为冲突的所有内容。

步骤 2：指令，从 CLAUDE.md 到 AGENTS.md

Codex 读取的是 AGENTS.md，不是 CLAUDE.md。如果导入器还没创建一个，那就要么重命名你的文件，要么告诉 Codex 继续读旧名字。

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

预期结果：下次运行时，你的仓库级指令会加载进 Codex 上下文。内容原封不动地迁移过去，改变的只是文件名和加载路径——这也正是 AGENTS.md 约定能跨工具存在的原因。

步骤 3：MCP 服务器，从 JSON 到 TOML

MCP 进程完全一样，改变的只是声明的形式。Claude Code 里这样的一条 .mcp.json 条目：

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

在 ~/.codex/config.toml 里变成一个 TOML 表：

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

预期结果：codex 启动时会列出 github 的 MCP 工具。如果某个服务器需要环境变量，就内联加上：env = { "GITHUB_TOKEN" = "..." }。两种传输方式都能迁移：Codex 接受你在 Claude Code 里跑过的同样的基于 STDIO 命令的服务器，也在同一个表里接受流式 HTTP 服务器，因此远程托管的 MCP 端点可以直接迁移，无需再启动本地进程。

步骤 4：Subagents 到 .codex/agents/

Claude Code 把 subagents 存为 .claude/agents/ 下的 Markdown。Codex 则把每个 subagent 存为它自己的 TOML 文件，一个 agent 一个文件，放在 ~/.codex/agents/（个人）或 .codex/agents/（项目范围）下。Subagents 默认启用，所以没有功能开关需要拨动。

# .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.
"""

预期结果：reviewer 角色会通过 Codex 的 subagent 工作流变得可用，Codex 只在你明确要求时才调用它。你旧 Markdown 文件里的提示词正文迁进 developer_instructions；改变的是外层封装。如果你有很多 subagents，这会是最繁琐的手动环节，但它是机械性的。

步骤 5：权限到沙箱与审批

这是真正会坏的一项，因为两个工具对安全的建模方式不同。Claude Code 用带 glob 规则的逐命令白名单。Codex 用两个粗粒度旋钮：文件系统沙箱和审批策略。二者之间没有干净的一一对应，所以你迁移的是意图，而不是规则。

Claude Code	Codex 意图	Codex 设置
allow: ["Bash(npm run test *)"]	在仓库内运行命令而不询问	sandbox_mode = "workspace-write", approval_policy = "on-request"
ask: ["Bash(python *)"]	在有风险的命令前提示	approval_policy = "on-request"
deny: ["Read(./.env)"]	阻止访问工作区之外	sandbox_mode = "workspace-write"（阻止对 cwd 之外的写入）
Plan mode	只看不动	sandbox_mode = "read-only"
--dangerously-skip-permissions	完全自主	approval_policy = "never", sandbox_mode = "danger-full-access"

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

预期结果：Codex 在仓库内自由运行，在触及仓库之外任何东西或访问网络之前会先询问。你在 Claude Code 里那种细粒度的逐命令控制无法留存；如果你依赖一份又长又精确的白名单，那就要接受 Codex 的模型在设计上就更钝。完整的选项集见 Codex 配置参考。

步骤 6：Hooks

Codex 现在有 hooks 了，默认启用，并覆盖了 Claude Code 的大部分事件。你在 config.toml 里用表数组块声明它们；要关掉整套系统，就设 [features] hooks = false。

# ~/.codex/config.toml
[[hooks.PreToolUse]]
matcher = "^Bash$"          # same idea as Claude Code's PreToolUse matcher

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

预期结果：只要你把 JSON 处理器翻译成 TOML，PreToolUse、PostToolUse、SessionStart、Stop 乃至 PreCompact/PostCompact 就会像在 Claude Code 里那样触发。唯一的缺口是 ConfigChange，Codex 没有对应事件，所以你为响应配置文件中途变更而构建的任何自动化，就是你整套 hook 设置里唯一带不过去的部分。想温习这些 Claude Code hooks 的作用，可看我们的 Claude Code hooks、subagents 与 skills 指南。

什么没有对应项：Claude 模型（以及解法）

唯一没有原生答案的迁移步骤，是保留你的 Claude 模型，因为原生 Codex 对 OpenAI 认证，并驱动 gpt-5.5、gpt-5.4 这类 OpenAI 模型。它没有内置开关能选择 Claude Opus 或 Sonnet。如果你迁移到 Codex 是冲着它的沙箱和工作流，但仍想让 Opus 来写你的代码，那你就需要一座桥。

这座桥就是一个自定义 model_provider。Codex 能与任何 OpenAI 兼容的网关对话，所以你注册一个，并让某个 profile 指向 Claude 模型。把 provider 加进 ~/.codex/config.toml：

[model_providers.ofox]
name = "ofox.io gateway"
base_url = "https://api.ofox.io/v1"
env_key = "OFOX_API_KEY"
wire_api = "responses"
requires_openai_auth = false

有两个细节容易绊倒人。第一，设 wire_api = "responses"。Codex 在 2026 年 2 月移除了对旧 chat 协议的支持，所以停留在 wire_api = "chat" 的 provider 现在会在启动时报错；ofox 在同一个 /v1 基础 URL 下提供 Responses 兼容端点，所以真正能连上的是 responses。第二，设 requires_openai_auth = false，让 Codex 别再指望 sk- 密钥前缀。然后在 ~/.codex/claude.config.toml 创建一个 profile 文件：

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

用 codex --profile claude 运行它。现在 Codex 的任务循环和沙箱驱动着 Anthropic 的 anthropic/claude-opus-4.8，而在第二个 profile 里把 model = "openai/gpt-5.5" 换上，就能让你在不改认证的情况下对两者做 A/B 对比。provider 块的分步操作，包括重试和请求头，都在我们关于 Codex 自定义模型服务商 的详解里，而完整的 ofox 文档 涵盖密钥设置。这是唯一一项网关不是图方便、而是保住你迁移初衷的唯一途径的配置。

迁移中的常见错误（及修复）

六种失败几乎涵盖了每一次卡住的迁移。每次的套路都一样：一个 Codex 并不认同的 Claude Code 假设。

症状	原因	修复
Codex 忽略你的 CLAUDE.md	Codex 读取 AGENTS.md	重命名它，或设置 project_doc_fallback_filenames
自定义 provider 返回 401	Codex 期望一个 sk- 密钥	加上 requires_openai_auth = false
Codex 启动报错：chat wire API 已弃用	wire_api = "chat" 于 2026 年 2 月被移除	设 wire_api = "responses"
Subagents 毫无反应	没有 agent 文件，或你从没请求过	添加一个 .codex/agents/NAME.toml 文件；Codex 只在明确请求时才生成 subagent
Hooks 从不触发	事件名错误或 matcher 正则不对	修正事件名 / matcher；hooks 默认开启，无需开关
你白名单允许的命令现在停了	沙箱比旧规则更严	放宽 sandbox_mode，或用 approval_policy = "on-request"

如果某个项目的 .codex/config.toml 被完全忽略，检查该项目是否被标记为受信任。Codex 只在受信任目录中加载项目范围的配置，而且不会让项目文件覆盖 provider、认证或 profile 选择。

团队 / 多人协作迁移

对团队而言，迁移比单人情形更干净，因为 Codex 把 Claude Code 的两个文件合并成一份提交进仓库的配置。在 Claude Code 里，你为团队交付一份 .claude/settings.json，让每位开发者保留一份被 gitignore 的 .claude/settings.local.json。在 Codex 里，你在仓库根目录提交单个 .codex/config.toml，让每位开发者选择一个 profile。

关注点	Claude Code	Codex
共享的团队配置	.claude/settings.json（已提交）	.codex/config.toml（已提交，受信任仓库）
个人覆盖	.claude/settings.local.json	~/.codex/ 里的个人 profile 文件
共享指令	CLAUDE.md	AGENTS.md
每次运行的风险姿态	权限白名单	--profile strict 对比 --profile fast

团队的收益，正是上一节那招网关技巧，应用一次即可。在提交进仓库的配置里注册一个 model_provider，通过你的密钥管理器给每位开发者发放同一套 OFOX_API_KEY 方案，那么无论他们跑 openai/gpt-5.5 还是 anthropic/claude-opus-4.8，整个团队都通过一个端点路由，共用一份账单视图。这种单端点路由，正是共享网关胜过逐人 OpenAI 密钥的具体原因；配置细节见我们的 config.toml 深度解析，安装基础则在 Codex 安装指南 里。

把你的工具链迁移到 Codex，不应意味着放弃你为之迁移的那些模型，而有了一个 provider 块，它就不会。

进阶：为 CI、本地和审查准备 profile

Profile 正是 Codex 回报你迁移付出的地方，因为它取代了 Claude Code 里在 settings.json 和 settings.local.json 之间来回权衡的习惯。一个 profile 就是 ~/.codex/ 下的一个独立文件，你用 --profile 在每次运行时选择它。除非你决定改，否则全局什么都不会变。

为三种风险姿态创建三个文件：

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

在 CI 里用 codex --profile ci 运行自动化审查，它可以读一切、却改不了任何东西。保留一个处于 workspace-write 的 local.config.toml 用于日常工作，以及上一节那个在你想让 Anthropic 模型攻克难题时把驱动切换到 anthropic/claude-opus-4.8 的 claude.config.toml。基础的 config.toml 持有共享部分——providers、MCP 服务器和 hooks；每个 profile 只覆盖那两三个有差异的键。这种单文件纪律，正是迁移完成之后，让 Codex 的设置比 Claude Code 的作用域堆栈更好理解的原因。

常见问题

我能在 Codex CLI 里用 Claude 模型吗？ 原生 Codex 不行，它只支持 OpenAI。注册一个 OpenAI 兼容网关作为 model_provider，并让一个 profile 指向 anthropic/claude-opus-4.8。这是唯一没有原生对应方案的一项配置。

Codex CLI 会读取 CLAUDE.md 吗？ 默认不会。它读取 AGENTS.md。加上 project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"] 保留旧文件，或者重命名它。

怎么把我的 Claude Code 设置导入 Codex？ 运行 codex，然后 /import。Codex 0.140 新增了一个可选择的导入器，用于 setup、项目配置和近期对话。它完成大部分工作，并报告其余部分。

Codex CLI 有像 Claude Code 那样的 hooks 吗？ 有，而且默认开启。为包括 PreToolUse、PostToolUse、SessionStart、Stop、PreCompact 和 PostCompact 在内的事件声明 [[hooks.Event]] 块。唯一没有对应项的 Claude Code hook 是 ConfigChange。

Claude Code 和 Codex 能共用同一批 MCP 服务器吗？ 能。MCP 进程完全一样，改变的只是声明，从 .mcp.json 里的 JSON 变成 [mcp_servers.NAME] 下的 TOML。

我必须为 Codex 重写 Claude Code 的 subagents 吗？ 你只是重新声明，而非重写。提示词正文照搬过去；封装从 .claude/agents/ 里的 Markdown 变成 .codex/agents/ 里独立的 TOML 文件。Subagents 默认开启，无需开关启用。

AGENTS.md 文件和 CLAUDE.md 是一回事吗？ 职责相同，名字不同。AGENTS.md 是一种跨工具约定；CLAUDE.md 是 Claude Code 自己的记忆文件。内容可直接迁移。

本次更新核对的来源

• OpenAI Codex 配置参考，于 2026-07-03 核实。是 model_providers、approval_policy、sandbox_mode、[features] 及 AGENTS.md 回退机制的来源。

• OpenAI Codex 更新日志，于 2026-07-03 核实。确认从 Claude Code 导入的 /import 于 0.140.0 落地；最新版本 0.142.5。

• OpenAI Codex Hooks 参考，于 2026-07-03 核实。确认 hooks 默认启用，且 PreCompact/PostCompact 为受支持的事件。

• Claude Code 设置参考，于 2026-07-03 核实。是 settings.json、permissions、hook 事件及 .mcp.json 的来源。

• ofox.io 模型目录快照，于 2026-07-03 核实。确认 anthropic/claude-opus-4.8、anthropic/claude-sonnet-5、openai/gpt-5.5 及基础 URL https://api.ofox.io/v1。