> ## Documentation Index
> Fetch the complete documentation index at: https://aicoding.cscitech.top/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code 迁移到 Codex 指南

> 把 Claude Code 的项目规则、权限配置、Skills、MCP、Hooks、Plugins、命令和工作流迁移到 Codex，并通过分阶段验证、兼容策略与回滚方案控制风险。

## 这页解决什么问题

如果你已经在使用 Claude Code，这次迁移不应该从“重新学习 AI 编程”开始，而应该从“逐项替换运行时约定”开始。两者都能在真实代码库中理解任务、读取文件、调用工具、修改代码并运行验证，但配置文件、权限模型、扩展目录和生命周期自动化并不完全兼容。

本页给出一条可审计的迁移路径：

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

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

## 先建立正确的心智模型

Claude Code 和 Codex 都属于终端中的代理式编程工具。你仍然可以采用“理解需求、读取项目、制定计划、执行变更、运行验证、检查差异、交付结果”的循环。真正需要迁移的是围绕这个循环的约束层。

可以把迁移拆成四层：

| 层次   | Claude Code 中的典型内容                   | Codex 中的对应内容             | 是否能直接复制          |
| ---- | ------------------------------------ | ------------------------ | ---------------- |
| 项目知识 | `CLAUDE.md`                          | `AGENTS.md`              | 内容大多可复用，发现规则必须重查 |
| 行为配置 | `settings.json`                      | `config.toml`            | 不能直接复制，需要逐项重写    |
| 安全边界 | permission mode、`allow`、`ask`、`deny` | sandbox、approval、Rules   | 目标类似，模型不同        |
| 扩展能力 | Skills、MCP、Hooks、Plugins             | Skills、MCP、Hooks、Plugins | 概念可迁移，格式和位置不同    |

迁移时不要把“名称相同”误判为“行为相同”。例如，两边都有 Skills，但一个 Skill 的目录扫描和显式调用方式可能不同；两边都支持 MCP，但 Codex 主要通过 `config.toml` 管理 server，不使用 Claude Code 的 `--scope` 语义。

## 总体对照表

| Claude Code               | Codex                              | 迁移动作                 |
| ------------------------- | ---------------------------------- | -------------------- |
| `CLAUDE.md`               | `AGENTS.md`                        | 精简内容后改名或重写           |
| `CLAUDE.local.md`         | `AGENTS.override.md`               | 不要直接替换，先理解覆盖语义       |
| `~/.claude/settings.json` | `~/.codex/config.toml`             | 按意图重写为 TOML          |
| permission mode           | `sandbox_mode` + `approval_policy` | 拆成“能力范围”和“是否询问”      |
| `allow` / `ask` / `deny`  | Rules、审批、沙箱                        | 简单命令可用 Rules，整体范围用沙箱 |
| `claude -p`               | `codex exec`                       | 迁移脚本并重新审查参数          |
| `/model`                  | `/model`                           | 先用本机帮助确认             |
| `/compact`                | `/compact`                         | 通常可沿用操作习惯            |
| `/clear`                  | `/clear`                           | 清屏和新会话行为需现场确认        |
| `/status`                 | `/status`                          | 用于核对模型、工作区和权限状态      |
| 外部 MCP server             | MCP server                         | 协议相同，配置写法不同          |
| Skill 目录                  | `.agents/skills`、用户 Skill 目录       | 重写 frontmatter 与安装路径 |
| Hook handler              | `hooks.json` 或 `[hooks]`           | 重写事件、matcher、输入输出协议  |
| 插件包                       | Codex Plugins                      | 重新安装并检查包含的资源         |
| `disableAllHooks` 等开关     | `[features] hooks = false`         | 不要假设开关名称一致           |

## 迁移前的冻结与盘点

先不要修改生产项目中的任何规则。选择一个测试仓库，建立迁移分支，并保存 Claude Code 当前配置的只读副本。

```bash theme={null}
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
```

Windows PowerShell 可以使用以下等价操作。路径按你的实际用户目录调整：

```powershell theme={null}
New-Item -ItemType Directory -Force .migration-backup
Copy-Item "$HOME\.claude" .migration-backup\claude-home -Recurse
Get-ChildItem -Force
 git status --short
```

上面的备份命令只用于保留结构，不要把真实 token、私钥或客户数据提交到仓库。配置备份应放在仓库外，或者先去除敏感值。

盘点时记录以下内容：

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`

Codex 读取的是 `AGENTS.md`。项目根目录通常放一份，子目录可以按模块添加更具体的规则。全局规则位于 Codex 主目录中的 `AGENTS.md` 或 `AGENTS.override.md`，默认主目录是 `~/.codex`，也可能由 `CODEX_HOME` 改变。

Codex 构建项目指令时通常从 Git 根目录一路走到当前目录。每个目录最多选择一个指令文件，优先级一般是：

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

找到的文件会从上到下拼接，越接近当前目录的内容越晚出现，冲突时通常由更近的规则主导。`AGENTS.override.md` 只替换同一目录中的 `AGENTS.md`，不会删除全局层或上级目录已经加载的指令。

这与 `CLAUDE.local.md` 的“附加本地内容”思路不同。迁移前先判断你原来的本地文件是补充规则，还是要在该层完全替换规则。如果只是个人偏好，优先使用用户级规则或单次提示；如果必须临时替换同级项目说明，再使用 `AGENTS.override.md`。

### 迁移内容的取舍

应保留每次任务都需要的事实：

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

应删除或移出以下内容：

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

Codex 的项目说明合并内容默认受 `project_doc_max_bytes` 限制，常见默认值是 32 KiB。这个限制按合并后的总大小计算，不是只看某一份文件的行数。超限时优先精简或按目录拆分，不要先无限增大上限。

### 推荐的 `AGENTS.md` 骨架

```md theme={null}
# 项目名称

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

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

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

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

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

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

### 兼容过渡

如果团队暂时需要同时使用两种工具，不要立即删除 `CLAUDE.md`。可以把规范正文整理成一份中立的团队文档，然后分别生成 Claude Code 和 Codex 的入口文件。也可以在 `~/.codex/config.toml` 配置：

```toml theme={null}
project_doc_fallback_filenames = ["CLAUDE.md"]
```

这只是过渡机制。它让 Codex 在找不到 `AGENTS.override.md` 和 `AGENTS.md` 时尝试备选名称，不代表 Claude Code 与 Codex 的所有语义已经兼容。长期方案仍然是维护明确的 `AGENTS.md`，避免队友不知道哪份文件是 Codex 的权威入口。

验证规则是否加载，不要让代理直接修改代码。进入项目目录后执行：

```bash theme={null}
codex --ask-for-approval never "Summarize the current instructions and list the instruction sources."
```

核对输出是否包含项目命令、包管理器、禁区和验收要求。再从一个子目录启动，验证更近的规则是否按预期生效：

```bash theme={null}
codex --cd services/payments --ask-for-approval never "Which test command applies here?"
```

## 阶段二：迁移配置与权限

### JSON 到 TOML

Claude Code 的 `settings.json` 不能直接改名为 `config.toml`。迁移时先列出你真正使用的意图，再逐项寻找 Codex 字段：默认模型、推理强度、沙箱、审批、MCP、Hooks、项目说明文件和功能开关。

一个最小 Codex 配置可以是：

```toml theme={null}
model = "gpt-5.5"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
```

TOML 使用 `=`，分组使用 `[section]`，数组使用方括号，行末不写 JSON 风格的逗号。不要把 `settings.json` 中未知的字段原样塞进 TOML；未知键可能被忽略，也可能导致解析失败。

配置通常分为用户级和项目级：

| 位置                      | 适用范围      | 迁移建议          |
| ----------------------- | --------- | ------------- |
| `~/.codex/config.toml`  | 当前用户的所有项目 | 放个人模型和通用安全偏好  |
| 项目 `.codex/config.toml` | 受信任的当前项目  | 放团队共享的项目能力配置  |
| `CODEX_HOME` 指向的目录      | 独立配置环境    | 用于 CI、演示或隔离实验 |

项目级配置尤其要谨慎。陌生仓库中的配置可能声明外部 server 或 Hooks；只有在确认仓库可信、内容经过审查后才启用。

### 权限模型的迁移方式

Claude Code 常按 permission mode 决定整体行为，并用 `allow`、`ask`、`deny` 针对工具或命令细分。Codex 将两个问题分开：

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

常见的 Codex 沙箱是：

| 沙箱                   | 含义           | 适合场景        |
| -------------------- | ------------ | ----------- |
| `read-only`          | 只读检查         | 初次探索、审查陌生仓库 |
| `workspace-write`    | 可写工作区，其他范围受限 | 日常开发的默认选择   |
| `danger-full-access` | 更广泛的系统访问     | 明确、短时、受控的排障 |

审批策略通常包括：

| 策略           | 含义              |
| ------------ | --------------- |
| `untrusted`  | 对不受信任操作更严格地询问   |
| `on-request` | 需要越界或敏感动作时询问    |
| `never`      | 不弹审批，仍不等于自动扩大沙箱 |

迁移时不要把“Claude Code 中不询问”直接翻译为“Codex 全面放权”。`approval_policy = "never"` 只是不询问，能力范围仍由沙箱决定。相反，`danger-full-access` 也不应作为日常默认值。

推荐的迁移起点是：

```toml theme={null}
sandbox_mode = "workspace-write"
approval_policy = "on-request"
```

在没有 Git 的临时目录中尤其要谨慎。Codex 可能采用更保守的只读默认值；不要为了绕过提醒就直接使用完全访问。`workspace-write` 下网络通常默认关闭，确需访问网络时再显式启用，并说明访问目标。

### Rules 的位置

如果你需要把 Claude Code 的某条 `deny` 规则迁移成命令级判断，可以研究 Codex Rules。Rules 使用 `.rules` 文件和 `prefix_rule`，常见用户级位置是 `~/.codex/rules/default.rules`。它属于实验性能力，字段和行为以本机文档为准。

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

规则决策通常分为 `allow`、`prompt` 和 `forbidden`，更严格的结果优先。写完后先检查，不要直接在真实发布流程中试：

```bash theme={null}
codex execpolicy check --pretty \
  --rules ~/.codex/rules/default.rules \
  -- git push --force origin main
```

简单的命令前缀限制适合 Rules；按复杂输入、文件内容或事件上下文判断时才考虑 Hook。沙箱仍然是整体边界，Rules 不是沙箱的替代品。

## 阶段三：迁移 Skills

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

两边的 Skill 都是在重复工作流上建立可复用能力。你原有 Skill 的目标、步骤、检查清单和参考资料大多可以保留，但要重新检查：

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

最小结构如下：

```text theme={null}
.agents/skills/release-check/
├── SKILL.md
├── scripts/
└── references/
```

`SKILL.md` 可以这样改写：

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

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

Codex 使用渐进式披露：会话初始主要看到 Skill 的名称、描述和路径，真正匹配后才读取完整正文。因此描述要把最重要的触发词放在前面。不要把所有项目背景都塞进描述；也不要使用模糊的“处理代码任务”这类描述。

### 显式与隐式调用

显式调用适合有副作用的工作流：

```text theme={null}
$release-check 检查当前分支是否具备发布条件，但不要发布。
```

也可以在会话中使用：

```text theme={null}
/skills
```

隐式调用依赖 `description` 自动匹配。对“发版”“删除数据”“修改生产配置”这类高风险 Skill，建议关闭隐式调用，在 Skill 的 `agents/openai.yaml` 中使用当前版本支持的策略字段，例如：

```yaml theme={null}
policy:
  allow_implicit_invocation: false
```

这样只有用户明确 `$release-check` 时才会调用。请先用本机版本验证字段名称。

Skill 重名时不要假设近处的定义会覆盖远处的定义。不同层级可能同时出现在选择器中，因此团队命名要带清晰的作用域或用途。通过 `/skills` 检查实际发现结果，必要时禁用不再使用的 Skill。

### Skills 的迁移验收

对每个 Skill 逐项执行：

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

## 阶段四：迁移 MCP

### 协议相同，配置方式不同

MCP server 通常可以复用同一套 server 实现，但不能复用 Claude Code 的配置命令和作用域参数。Codex 主要支持两类连接：

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

Claude Code 中类似下面的作用域参数：

```bash theme={null}
claude mcp add --scope user example ...
```

不要直接照搬。Codex 用配置文件位置表达范围：用户配置放在 `~/.codex/config.toml`，项目配置放在受信任项目的 `.codex/config.toml`。

### 添加 STDIO server

可以先用命令查看本机支持的参数：

```bash theme={null}
codex mcp --help
```

典型添加方式如下：

```bash theme={null}
codex mcp add context7 -- npx -y @upstash/context7-mcp
```

注意 `--` 后面才是 server 的启动命令。等价的 TOML 结构通常是：

```toml theme={null}
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
```

本地 server 的运行前提要重新检查，例如 Node.js、Python、可执行文件路径和环境变量。不要把 token 写进 `config.toml`：

```toml theme={null}
[mcp_servers.internal_docs]
command = "node"
args = ["server.js"]
env_vars = ["INTERNAL_DOCS_TOKEN"]
```

### 添加远程 HTTP server

远程 server 使用 URL，并让配置引用环境变量：

```toml theme={null}
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
```

认证 token 留在环境变量或凭据管理器中。需要 OAuth 的 server 使用本机支持的登录命令，例如：

```bash theme={null}
codex mcp login figma
```

### 限制 server 的能力

迁移时不要因为 Claude Code 原来默认放行，就把整个 MCP server 自动批准。可以按当前版本支持的字段控制：

```toml theme={null}
[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
```

`enabled_tools` 和 `disabled_tools` 的具体优先级以本机文档为准；常见行为是先限制白名单，再应用黑名单。陌生 server 默认只读、逐次审批，确认来源和数据边界后再放宽。

在会话中使用以下命令检查 server：

```text theme={null}
/mcp
```

验收重点不是“列表里出现了名称”，还要确认：工具数量符合预期、认证没有泄漏、首次调用触发审批、server 不能越权写入生产数据、超时和失败能够被看见。

## 阶段五：迁移 Hooks

### 先区分请求和保证

`AGENTS.md` 中写“修改后记得格式化”是给代理的请求；Hook 才能在事件发生时运行确定性脚本。迁移 Hooks 前要重新设计，而不是把 Claude Code 的 JSON 原样复制。

Codex 常见事件包括：

| 事件                           | 时机      | 适合用途          |
| ---------------------------- | ------- | ------------- |
| `SessionStart`               | 会话启动或恢复 | 注入项目状态        |
| `UserPromptSubmit`           | 用户提交提示后 | 记录或补充上下文      |
| `PreToolUse`                 | 工具执行前   | 拦截或审批高风险动作    |
| `PostToolUse`                | 工具执行后   | 格式化、记录结果、触发检查 |
| `Stop`                       | 一轮回答结束  | 发现缺项时要求继续     |
| `PermissionRequest`          | 产生审批请求时 | 统一处理部分审批      |
| `PreCompact` / `PostCompact` | 上下文压缩前后 | 记录或恢复状态       |

`PreToolUse` 能在部分工具执行前阻止操作；`PostToolUse` 不能撤销已完成的副作用，只能反馈结果；`Stop` 中的阻止信号通常表示“不要结束，继续一轮”，不要套用 Claude Code 的直觉。

### 配置位置和格式

Hook 可以写在用户级 `~/.codex/hooks.json`、用户级 `config.toml`，或项目 `.codex/hooks.json`、项目 `.codex/config.toml`。项目 Hook 可以提交给团队，但必须审查脚本来源。

项目级 `hooks.json` 的基本形态是：

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

`matcher` 是正则字符串，工具事件通常匹配工具名。修改文件时，Codex 实际工具名可能是 `apply_patch`；不要只按 Claude Code 中的 `Edit` 或 `Write` 判断。Hook 的 `timeout` 通常按秒计算，不要把 Claude Code 的毫秒配置原样带过来。

Codex 当前版本支持的处理器和异步行为可能有限。迁移前使用最小 Hook 验证，不要假设 `prompt`、`agent` 或异步处理器一定执行。

### Hook 的输入输出

Hook 脚本通常从 stdin 读取 JSON。工具事件可能包含：

```json theme={null}
{
  "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` 等事件中通常表示反馈、退回或要求继续。
* 其他退出码：按当前版本的错误处理行为验证，不要依赖未定义语义。

需要精细控制时输出事件对应的 JSON，例如拒绝工具：

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

不要用 stdout 的普通文本假设所有事件都会理解它。不同事件对纯文本、stderr 和 JSON 的处理不同，应先用模拟 stdin 单独测试脚本，再连接到真实会话。

### Codex 特有的信任步骤

非托管 Hook 默认可能不会执行。新增或修改 Hook 后，启动 Codex 并运行：

```text theme={null}
/hooks
```

逐项查看来源、命令、路径和哈希，确认无误后再信任。改动脚本哪怕只有一个字符，也可能需要重新信任。不要在日常环境中使用绕过 Hook 信任的危险启动选项；CI 若确需非交互运行，应在隔离环境审查来源后再决定。

临时关闭全部 Hooks 时，当前版本可能使用：

```toml theme={null}
[features]
hooks = false
```

这不是 Claude Code 的 `disableAllHooks` 直接替代，使用前必须查本机帮助。更好的回滚方式通常是禁用单个 Hook 或恢复备份，而不是全局关闭所有自动化。

## Plugins 的迁移策略

Plugin 往往是 Skills、MCP、Hooks、命令或配置的打包与分发单元。不要把 Claude Code Plugin 的目录复制到 Codex 后就认为它可用。先列出插件包含的资源，再按 Codex 的资源类型逐项迁移。

推荐顺序如下：

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

Skill 是工作流的编写格式，Plugin 更偏向打包和分发格式。团队插件应固定来源和版本，避免每台机器从不同地址安装出不同结果。安装器命令和目录以当前 Codex 版本为准，安装后用 `/skills`、`/mcp` 和 `/hooks` 分别验证，不要只看安装命令返回成功。

## 命令和工作流映射

### 交互命令

| 目的        | Claude Code 习惯    | Codex 迁移方式                  |
| --------- | ----------------- | --------------------------- |
| 查看帮助      | `claude --help`   | `codex --help`              |
| 无头执行      | `claude -p`       | `codex exec`，重新确认参数         |
| 切模型       | `/model`          | `/model`，以本机列表为准            |
| 查看状态      | `/status`         | `/status`                   |
| 压缩上下文     | `/compact`        | `/compact`                  |
| 清理会话      | `/clear`          | `/clear`，确认是否同时新开会话         |
| 查看改动      | `/diff`           | `/diff`                     |
| 查看 MCP    | 相关 MCP 命令         | `/mcp`                      |
| 查看 Skills | 相关 Skill 命令       | `/skills`                   |
| 查看 Hooks  | 配置或日志             | `/hooks`                    |
| 权限切换      | `Shift+Tab` 等模式切换 | `/permissions` 或启动参数        |
| 初始化项目说明   | `/init`           | `/init` 后检查生成的是 `AGENTS.md` |

命令同名不代表输出和副作用相同。迁移脚本前逐条运行 `codex <subcommand> --help`。不要在 CI 中假设交互命令可用；优先使用 `codex exec` 和明确的退出码、输出格式。

### 工作流映射

Claude Code 中常见的“先探索再修改”流程在 Codex 中仍然适用：

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

`claude -p` 迁移到 `codex exec` 时，要同步迁移三件事：工作目录、审批策略和输出处理。脚本必须明确失败时退出，而不是把代理的一段自然语言当成成功信号。

示例：

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

参数名在不同版本可能略有不同，先执行 `codex exec --help`。当命令涉及提交、推送、部署、外发消息或生产数据时，不要用 `never` 或 `--yolo` 作为默认自动化策略。

## 一个分阶段迁移案例

假设一个团队有 Node.js 单体仓库，原来使用：根目录 `CLAUDE.md`、用户级 `settings.json`、两个 Skills、一个 Context7 MCP、一个格式化 Hook，以及一个发布 Plugin。

### 第 0 阶段：只读基线

在 Claude Code 中记录一次基线：当前分支、测试结果、格式化结果、MCP 列表、Skill 列表和 Hook 行为。保存命令输出，但不要保存 token。

```bash theme={null}
git status --short
git branch --show-current
npm test
npm run lint
```

如果基线本身不通过，先记录它，不要在迁移过程中把旧问题误判成 Codex 造成的回归。

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

新建 `AGENTS.md`，只放包管理器、测试命令、禁改目录和验收标准。Codex 使用 `read-only` 或保守审批，总结规则后退出。此时不安装 Plugin、不连接生产 MCP、不启用写操作 Hook。

通过后再把模型和推理强度写入用户级 `config.toml`。确认 TOML 可解析、启动无警告、当前项目仍识别为正确的 Git 根。

### 第 2 阶段：迁移低风险 Skill

先迁移“解释错误”或“总结 diff”这类无副作用 Skill。通过 `/skills` 检查发现，分别测试隐式和显式调用。若描述太泛，缩小触发范围；若脚本依赖 Claude Code 变量，改为读取 Codex 提供的 `cwd` 或从 Git 根计算路径。

### 第 3 阶段：迁移只读 MCP

把 Context7 放在用户级配置，先用 `codex mcp add`，再用 `/mcp` 检查。第一次调用保持 `prompt`，确认返回内容确实来自 server。对远程文档内容保持提示注入意识，不要让外部文本覆盖项目规则。

### 第 4 阶段：迁移 Hooks

先部署只记录命令或只运行格式化的 Hook。用测试仓库验证 stdin、退出码、路径和超时，之后在 `/hooks` 中审查并信任。格式化 Hook 通过后，再迁移拦截危险命令的逻辑。简单前缀禁令优先写 Rules，复杂判断才使用脚本。

### 第 5 阶段：迁移发布 Plugin

最后才迁移发布相关 Plugin。把隐式触发关闭，要求 `$release-check` 显式调用；将“检查”和“发布”拆成两个能力。发布动作使用 `approval_policy = "on-request"`，并在测试环境验证拒绝、超时和回滚路径。

### 第 6 阶段：双跑和切换

同一组输入分别在 Claude Code 和 Codex 中执行，比较：

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

连续多个任务通过后，再把 Codex 设为默认工具。Claude Code 配置保留一个发布周期，不要在首次成功后立刻删除。

## 兼容差异清单

### 不能直接假设的事项

* 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` 中必须每次生效的团队规则。

### 安全边界差异

迁移完成后，用“沙箱、审批、Rules、Hooks、MCP 工具权限”五个问题重新审查，而不是沿用 Claude Code 的单一 permission mode。对以下动作始终保留人工确认：删除文件、修改数据库、读取密钥、发送外部请求、推送分支、创建或合并 PR、部署和外发消息。

## 验证清单

### 文件和配置

* [ ] 当前项目只有预期的 `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、类型检查和构建结果已记录。
* [ ] 变更范围没有包含迁移之外的文件。
* [ ] 提交和推送仍然需要明确批准。

可以在项目根执行：

```bash theme={null}
git diff --check
git diff --stat
git status --short
codex --version
codex --help
```

## 回滚和止损

迁移要分层回滚，避免为了恢复一个 Hook 而删掉整个 Codex 配置。

### 规则回滚

保留原始 `CLAUDE.md` 和新建的 `AGENTS.md`，发现规则不正确时先移除新增的 Codex 文件或恢复到迁移前版本。若只是在测试分支中修改，可以回退该分支；不要覆盖团队成员的未提交工作。

### 配置回滚

修改 `config.toml` 前复制到仓库外的备份路径。出现解析错误时，先恢复最近一个能启动 Codex 的版本，再逐项加回配置。不要把整份 Claude Code `settings.json` 粘贴到 Codex 配置中，也不要用完全访问模式掩盖配置错误。

### Skill 和 Plugin 回滚

优先禁用单个 Skill 或卸载单个 Plugin，保留目录以便审查。对自动发布、删除和写入生产的能力，先关闭隐式调用，再撤销凭据和 MCP 写工具权限。确认没有残留 Hook 后再删除文件。

### MCP 回滚

先禁用 server，再检查是否有正在运行的本地进程、缓存或凭据。撤销不再需要的 token；若 server 曾经接触真实数据，按该系统的审计和密钥轮换流程处理。删除配置前保留 server 名称、版本和失败日志，方便定位。

### Hook 回滚

在 `/hooks` 中禁用或撤销信任，随后删除项目配置中新增的那一条。若 Hook 已产生副作用，不能靠删除 Hook 撤回结果；需要使用 Git、数据库备份、部署版本或外部系统自己的回退机制。

### 工作区回滚

迁移期间任何代码变更都先查看：

```bash theme={null}
git diff --stat
git diff
git status --short
```

只撤销自己明确知道的迁移改动。已提交的错误迁移通过新的修复提交回滚，不改写共享分支历史。未提交的文件如果包含他人工作，先停止并确认归属。

## 最终切换标准

满足以下条件后，才适合把 Codex 作为团队默认工具：

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

## 小结

从 Claude Code 迁移到 Codex，最稳妥的方法不是寻找一份“一键转换器”，而是把每一项能力的意图重新落在 Codex 的边界上：项目知识进入 `AGENTS.md`，行为配置重写为 `config.toml`，权限拆成沙箱和审批，命令级限制使用经过验证的 Rules，重复工作流迁移为 Skills，外部能力通过受限 MCP 接入，生命周期自动化改写为经过信任审查的 Hooks，Plugin 则最后安装并逐项验收。

记住四条底线：配置不要直接复制，权限不要只看是否询问，外部工具不要默认信任，迁移成功不要代替回滚准备。先只读、再低风险写入、最后接入有副作用的自动化，并用 Git 差异、测试结果、命令输出和日志证明每一步。这样即使某项兼容性在未来版本中变化，也能快速定位影响范围并恢复到已知可用状态。

参考资料：`参考/codex/32-migrate-from-claude-code.md`、`参考/codex/11-agents-md.md`、`参考/codex/22-skills.md`、`参考/codex/20-mcp.md`、`参考/codex/24-hooks.md`。