Claude Code 迁移到 Codex 指南

​

这页解决什么问题

• 先区分能够直接复用的概念和必须重写的配置。
• 把 CLAUDE.md 精简后迁移为 AGENTS.md。
• 把 JSON 配置拆解为 Codex 的 config.toml、沙箱和审批策略。
• 迁移 Skills、MCP、Hooks 和 Plugins 时保留意图，不机械复制目录或字段。
• 用命令、测试、日志和最小权限逐项验证。
• 在迁移失败时只回滚迁移层，不破坏原有 Claude Code 工作流。

本页的命令、字段和默认行为以当前 Codex 版本的 codex --help、子命令帮助和官方文档为准。模型名称、实验性 Rules、Hooks 字段以及插件安装位置可能随版本变化；凡是与本机帮助输出不一致的内容，以本机输出为准。

​

先建立正确的心智模型

​

总体对照表

​

迁移前的冻结与盘点

mkdir codex-migration-backup
cp -R ~/.claude/codex-migration-backup/claude-home 2>/dev/null || true
cd path/to/repository
git switch -c migrate-to-codex
git status --short

New-Item -ItemType Directory -Force .migration-backup
Copy-Item "$HOME\.claude" .migration-backup\claude-home -Recurse
Get-ChildItem -Force
 git status --short

1. 所有层级的 CLAUDE.md 和 CLAUDE.local.md。
2. settings.json 中的模型、权限、环境变量和 Hook。
3. 项目使用的 Skills、Skill 触发条件和附带脚本。
4. MCP server 的启动命令、URL、认证方式和实际使用工具。
5. Hooks 的事件、matcher、脚本、超时和退出码。
6. Plugins 的来源、版本、包含的 Skill、MCP、命令和 Hook。
7. 常用斜杠命令、脚本调用方式和 CI 集成。
8. 现有测试、格式化、构建和发布命令。

​

阶段一：迁移项目规则

​

CLAUDE.md 到 AGENTS.md

1. AGENTS.override.md。
2. AGENTS.md。
3. project_doc_fallback_filenames 中配置的备选文件名。

​

迁移内容的取舍

• 项目用途和主要入口。
• 语言、框架、包管理器和关键运行时版本。
• 测试、Lint、格式化、构建和启动命令。
• 必须遵守的命名、目录和接口约定。
• 禁止修改的目录或文件。
• 删除数据、改依赖、迁移数据库、发布和外部写操作前的确认要求。

• 公司历史、产品愿景和长篇背景故事。
• 代码本身已经明确表达的目录说明。
• 已经由 formatter、linter 或 CI 强制执行的重复规则。
• 过期的命令、已经不存在的服务和旧版本信息。
• 需要用户每次判断的动态信息。

​

推荐的 AGENTS.md 骨架

# 项目名称

## 项目边界
- 这是一个什么项目。
- 本次任务默认只修改哪些目录。

## 技术栈
- 语言与运行时版本。
- 包管理器和关键框架。

## 常用命令
- `npm test`：运行测试。
- `npm run lint`：执行检查。
- `npm run build`：构建项目。

## 工作约定
- 先读取相关实现和测试，再修改。
- 保持现有 API 兼容性。
- 新增依赖、改数据库结构或删除文件前先确认。

## 禁区
- 不修改 `migrations/` 中已发布的文件。
- 不读取或提交 `.env`、私钥和真实客户数据。

## 验收
- 说明运行过的命令。
- 报告测试结果、未验证假设和剩余风险。

​

兼容过渡

project_doc_fallback_filenames = ["CLAUDE.md"]

codex --ask-for-approval never "Summarize the current instructions and list the instruction sources."

codex --cd services/payments --ask-for-approval never "Which test command applies here?"

​

阶段二：迁移配置与权限

​

JSON 到 TOML

model = "gpt-5.5"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

​

权限模型的迁移方式

• 沙箱决定代理可以触及的范围。
• 审批策略决定越过限制或执行敏感动作时是否询问。

sandbox_mode = "workspace-write"
approval_policy = "on-request"

​

Rules 的位置

prefix_rule(
    pattern = ["git", "push", "--force"],
    decision = "forbidden",
    justification = "禁止强制推送共享分支",
)

codex execpolicy check --pretty \
  --rules ~/.codex/rules/default.rules \
  -- git push --force origin main

​

阶段三：迁移 Skills

​

概念可以保留，入口必须重写

• SKILL.md 的 frontmatter 是否包含 name 和 description。
• description 是否明确触发场景和不应触发的边界。
• 显式调用方式是否改为 Codex 支持的 $skill-name 或 /skills。
• 仓库级 Skill 是否放在 .agents/skills，个人 Skill 是否放在 $HOME/.agents/skills。
• 脚本是否依赖 Claude Code 专有环境变量或工具名。
• Skill 是否包含会发送数据、发布或修改生产系统的副作用。

.agents/skills/release-check/
├── SKILL.md
├── scripts/
└── references/

---
name: release-check
description: 发版前检查变更、测试、版本号和回滚点。当用户要求发版前检查、准备发布或检查 release readiness 时使用；不要自行发布。
---

1. 读取 Git 状态和当前版本。
2. 检查变更范围、测试结果和变更日志。
3. 列出缺失项和风险。
4. 只有用户明确批准后，才执行提交、打 tag 或发布。

​

显式与隐式调用

$release-check 检查当前分支是否具备发布条件，但不要发布。

/skills

policy:
  allow_implicit_invocation: false

​

Skills 的迁移验收

1. 在干净测试仓库中确认 /skills 能看到它。
2. 用一条明确的人话验证隐式触发。
3. 用 $name 验证显式触发。
4. 检查脚本使用的路径、环境变量和命令在 Codex 中存在。
5. 对副作用操作确认默认不会隐式执行。
6. 保存一次运行日志和预期结果。

​

阶段四：迁移 MCP

​

协议相同，配置方式不同

• STDIO：在本机通过命令启动进程。
• Streamable HTTP：连接远程 URL，可使用 Bearer token 或 OAuth。

claude mcp add --scope user example ...

​

添加 STDIO server

codex mcp --help

codex mcp add context7 -- npx -y @upstash/context7-mcp

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.internal_docs]
command = "node"
args = ["server.js"]
env_vars = ["INTERNAL_DOCS_TOKEN"]

​

添加远程 HTTP server

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

codex mcp login figma

​

限制 server 的能力

[mcp_servers.browser]
url = "https://example.invalid/mcp"
enabled = true
enabled_tools = ["open", "read"]
disabled_tools = ["write", "delete"]
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 120

/mcp

​

阶段五：迁移 Hooks

​

先区分请求和保证

​

配置位置和格式

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "^Bash$",
        "hooks": [
          {
            "type": "command",
            "command": "python .codex/hooks/log-command.py",
            "timeout": 30,
            "statusMessage": "记录命令"
          }
        ]
      }
    ]
  }
}

​

Hook 的输入输出

{
  "session_id": "session-id",
  "cwd": "/work/repository",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "git status --short"
  }
}

• 0：正常继续。
• 2：在 PreToolUse 等前置事件中表示拒绝或阻止；在 PostToolUse、Stop 等事件中通常表示反馈、退回或要求继续。
• 其他退出码：按当前版本的错误处理行为验证，不要依赖未定义语义。

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "禁止操作生产数据库"
  }
}

​

Codex 特有的信任步骤

/hooks

[features]
hooks = false

​

Plugins 的迁移策略

1. 只迁移一个最常用、风险最低的 Skill。
2. 再迁移不含写操作的 MCP server。
3. 最后审查 Hooks、命令和发布能力。
4. 在测试仓库中安装，记录插件版本和来源。
5. 检查插件是否带有隐藏的网络、文件写入或自动触发逻辑。

​

命令和工作流映射

​

交互命令

​

工作流映射

1. 进入正确的 Git 工作区。
2. 查看 AGENTS.md 和项目 README。
3. 让 Codex 总结现状并列出计划。
4. 使用只读沙箱或保守审批开始探索。
5. 确认范围后切换到工作区写入。
6. 小步修改，每次查看 diff。
7. 运行最小代表性测试，再运行完整验证。
8. 检查密钥、生成物和无关文件。
9. 由用户明确批准后提交、推送或发布。

codex exec \
  --cd path/to/repository \
  --sandbox workspace-write \
  --ask-for-approval on-request \
  "运行测试并报告失败原因，不要提交或推送。"

​

一个分阶段迁移案例

​

第 0 阶段：只读基线

git status --short
git branch --show-current
npm test
npm run lint

​

第 1 阶段：规则和只读配置

​

第 2 阶段：迁移低风险 Skill

​

第 3 阶段：迁移只读 MCP

​

第 4 阶段：迁移 Hooks

​

第 5 阶段：迁移发布 Plugin

​

第 6 阶段：双跑和切换

• 读取的规则是否一致。
• 计划是否覆盖相同的验收条件。
• 修改文件范围是否一致。
• 测试和格式化结果是否一致。
• MCP 和 Hook 的副作用是否一致。
• 失败时是否能安全停止。

​

兼容差异清单

​

不能直接假设的事项

• Codex 不会因为仓库里有 CLAUDE.md 就自动读它，除非配置备选文件名。
• CLAUDE.local.md 与 AGENTS.override.md 不是同一个语义。
• JSON 不能直接复制到 TOML。
• 不询问审批不等于拥有更大文件或网络权限。
• workspace-write 不代表网络默认开放。
• MCP 作用域不是通过 Claude Code 的 --scope 迁移。
• Skill 的手写目录与安装器管理目录可能不同。
• Hook 的工具名、matcher、超时单位和输出协议需要重新检查。
• Codex Hook 的 block 在不同事件中可能表示阻止、反馈或继续一轮。
• Rules 可能仍属于实验性功能，不应作为唯一安全边界。
• Plugin 安装成功不代表其中的每个资源都已经被信任或启用。
• 记忆功能不能替代 AGENTS.md 中必须每次生效的团队规则。

​

安全边界差异

​

验证清单

​

文件和配置

• 当前项目只有预期的 AGENTS.md，没有重复或过时的规则冲突。
• 全局、项目和子目录规则的发现顺序已经实测。
• AGENTS.override.md 的使用范围已经确认。
• config.toml 可解析，未混入 JSON 逗号或未知字段。
• 配置和 Hook 中没有 token、密码、私钥或真实数据。
• 项目级 .codex/config.toml 和 .codex/hooks.json 的来源已审查。

​

权限和外部能力

• 日常工作使用工作区写入和按需审批。
• 只读任务没有意外写入。
• 网络只对明确需要的任务启用。
• MCP server 的工具已限到最小集合。
• 陌生 MCP 工具默认逐次审批或禁用。
• Rules 已用 codex execpolicy check 验证允许和拒绝案例。
• 新 Hook 已在 /hooks 中审阅和信任。
• 副作用 Skill 和 Plugin 已关闭隐式触发。

​

行为和交付

• /status 显示了预期模型、目录和权限。
• /skills 能发现迁移的 Skill，并且显式调用成功。
• /mcp 显示的 server 与清单一致。
• Hook 的正向、拒绝、超时和脚本失败场景均已测试。
• git diff --check 通过。
• 测试、Lint、类型检查和构建结果已记录。
• 变更范围没有包含迁移之外的文件。
• 提交和推送仍然需要明确批准。

git diff --check
git diff --stat
git status --short
codex --version
codex --help

​

回滚和止损

​

规则回滚

​

配置回滚

​

Skill 和 Plugin 回滚

​

MCP 回滚

​

Hook 回滚

​

工作区回滚

git diff --stat
git diff
git status --short

​

最终切换标准

1. 至少一个真实但低风险的任务在 Codex 中完成，并通过原有测试。
2. AGENTS.md 能稳定加载，规则冲突有明确归属。
3. 模型、沙箱、审批和网络配置经过审查。
4. Skills、MCP、Hooks、Plugins 各自完成发现、调用、失败和回滚测试。
5. codex exec 的自动化脚本能正确处理退出码和日志。
6. 团队成员知道 Codex 与 Claude Code 的差异，而不是只收到一份新配置。
7. 原有 Claude Code 配置至少保留到一个发布周期结束。
8. 迁移文档记录了版本、日期、已验证范围和未解决风险。

​

小结