从 Claude Code 迁移到 Codex CLI：一次被动迁移后的真实使用笔记

过去一段时间，我主要用 Claude Code 做本地代码协作：读仓库、改代码、跑测试、解释报错、做 review。它的交互方式足够顺手，尤其适合在终端里直接把一个任务推进到可提交状态。

但最近我遇到了一个比较现实的问题：我的 Anthropic 账户被封了。结合当时 Anthropic 对阿里千问相关“反蒸馏”风控的讨论，我的判断是账户触发了相关风险策略。无论具体原因如何，结果都一样：原来的 Claude Code 工作流不可用了。

所以我开始把主力编码代理迁移到 Codex CLI。迁移之后的体感是：Codex CLI 不是 Claude Code 的一比一替代品，它更像一个“终端优先的本地工程代理”。如果把它当成普通聊天机器人，会觉得不够顺手；但如果围绕仓库、权限、配置和可复用指令来使用，它可以非常稳定地接管日常开发工作。

本文记录我的迁移方式和一些 Codex CLI 使用技巧。

迁移前先调整心智模型

Claude Code 的体验更像“我在终端里叫一个会写代码的同事过来”。Codex CLI 更强调几个工程化概念：

• 工作目录：Codex 会围绕当前目录读取代码、修改文件、运行命令。
• 权限与沙箱：它默认不会随便动工作区之外的文件，也不会无提示地执行高风险操作。
• 持久化配置：常用模型、审批策略、沙箱、MCP、主题、日志等都可以写进 ~/.codex/config.toml。
• 项目指令：通过 AGENTS.md 把仓库规范、测试命令、代码风格固化下来。
• 可恢复会话：本地会话会保存，可以用 codex resume 回到之前的上下文。

迁移时最重要的变化是：不要每次都从零开始给代理解释项目。应该把稳定规则写入配置和 AGENTS.md，把一次性目标写在当前 prompt 里。

安装与登录后的第一组命令

安装和登录完成后，我建议先跑这几个命令确认环境：

codex doctor
codex features list
codex "解释一下这个代码库的结构"

codex doctor 用来检查本地安装、认证、终端、Git、配置和会话状态。刚迁移时先跑它，可以快速排除很多环境问题。

日常进入交互模式：

codex

带着一个初始任务进入：

codex "阅读这个项目，找出启动命令、测试命令和主要模块"

如果只是要一次性处理一个任务，不想进入完整 TUI，可以用：

codex exec "修复当前测试失败，并说明修改原因"

推荐的基础配置

Codex 的个人配置一般放在：

~/.codex/config.toml

我建议先从保守但高效的配置开始：

model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
model_reasoning_effort = "high"
personality = "pragmatic"

[features]
shell_snapshot = true
multi_agent = true

这组配置的含义：

• model = "gpt-5.5"：把主力模型设为当前 Codex 推荐的复杂编码任务模型。
• approval_policy = "on-request"：需要越权或高风险操作时再问你。
• sandbox_mode = "workspace-write"：允许在当前工作区读写和运行命令，但限制工作区外操作。
• web_search = "cached"：默认使用缓存搜索，降低直接访问网页带来的提示注入风险。
• model_reasoning_effort = "high"：复杂任务给模型更多推理预算。
• personality = "pragmatic"：让输出更偏工程执行，而不是泛泛解释。

临时覆盖配置可以直接在命令里加 -c：

codex -c model_reasoning_effort=medium "快速解释这个报错"

临时切模型：

codex --model gpt-5.5 "重构这个模块并补测试"

用 AGENTS.md 固化项目规则

迁移到 Codex CLI 后，最值得做的一件事就是给项目加 AGENTS.md。它相当于给代理看的项目说明书。

在仓库根目录创建：

# AGENTS.md

## 项目约定

- 修改 TypeScript 文件后运行 `npm run lint` 和 `npm test`。
- 不要引入新的生产依赖，除非先说明原因。
- API 行为变更必须同步更新 `docs/`。
- 保持改动范围最小，不做无关重构。

## 常用命令

- 安装依赖：`npm install`
- 本地开发：`npm run dev`
- 测试：`npm test`
- 构建：`npm run build`

如果某个子目录有特殊规则，可以在子目录放另一个 AGENTS.md 或 AGENTS.override.md。Codex 会从项目根目录一路读到当前目录，越靠近当前目录的规则越具体。

全局个人偏好可以写到：

~/.codex/AGENTS.md

例如：

# ~/.codex/AGENTS.md

## 我的默认偏好

- 回答使用中文。
- 修改前先说明要动哪些文件。
- 完成后说明验证命令和结果。
- 不要自动提交 git commit，除非我明确要求。

这样每个项目都会继承你的个人工作习惯。

日常工作流：从“聊天”变成“任务委派”

我现在使用 Codex CLI 的方式大概是这样：

1. 让 Codex 先建立项目地图

进入新仓库后先问：

codex "阅读项目结构，告诉我入口文件、核心模块、测试命令、构建命令和潜在风险点。不要修改文件。"

这个阶段只让它读，不让它改。等它理解项目后，再给具体任务。

2. 小步提交任务

不要一次说“重构整个系统”。更好的 prompt 是：

修复登录页在 token 过期后没有跳转的问题。
要求：
1. 先定位相关代码。
2. 只修改必要文件。
3. 补一个覆盖 token 过期场景的测试。
4. 运行相关测试并汇报结果。

Codex 擅长把任务拆成“读代码 -> 制定计划 -> 修改 -> 验证”。你给它的边界越清楚，结果越稳定。

3. 用 review 模式检查改动

改完后可以在交互模式里用：

/review

它会按 review 视角检查当前 diff，重点找 bug、回归风险和缺失测试。迁移后我很依赖这个功能，因为它能把“写代码”和“审代码”拆成两个角色。

也可以直接要求：

codex "以代码审查者身份检查当前未提交改动，只列出明确的问题和对应文件行号。"

4. 用 resume 接上历史上下文

Codex 会保存本地会话。中断后继续：

codex resume

直接恢复最近一次：

codex resume --last

如果你昨天已经让它分析过项目，今天可以接着说：

codex resume --last "继续昨天的迁移计划，先处理配置模块。"

这比重新粘贴一堆背景信息更省心。

常用快捷技巧

让 Codex 只读不改

适合做解释、排查、方案设计：

codex --sandbox read-only "分析为什么这个测试会失败，不要修改文件"

给额外目录授权

如果当前项目需要同时读取另一个本地目录：

codex --add-dir ../shared-lib "检查当前项目和 shared-lib 的接口是否一致"

需要最新信息时打开实时搜索

默认搜索是缓存模式。如果要查最新版本、最新 API 或近期变更：

codex --search "查最新 Next.js 版本下这个配置项是否还有效"

给截图或设计稿

Codex CLI 可以带图片输入：

codex -i screenshot.png "根据这个报错截图定位可能原因"

多个图片：

codex --image before.png,after.png "比较两个界面差异，并指出可能的 CSS 问题"

安装 shell 补全

codex completion zsh
codex completion bash
codex completion fish
codex completion power-shell

PowerShell 用户可以先查看输出，再按自己的 profile 方式加载。

Claude Code 用户迁移时容易踩的坑

1. 不写项目指令，导致每次都重新解释

Claude Code 用户很容易习惯“临时口头交代”。迁到 Codex 后，建议尽快把重复内容沉淀到 AGENTS.md。比如测试命令、包管理器、代码风格、禁止事项，都应该写进去。

2. 权限开太大

Codex 支持 Full Access，也支持 --dangerously-bypass-approvals-and-sandbox。但日常开发不建议这么用。我的默认选择是：

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

只有在临时容器、一次性沙盒或完全可信的环境里，才考虑放宽权限。

3. 任务太大，反馈周期太长

不要直接让它“完成整个迁移”。更好的拆法是：

• 先让它读代码并输出计划。
• 再让它修改一个模块。
• 然后运行相关测试。
• 最后让它 review 自己的 diff。

这和人类工程师协作一样：任务越清晰，返工越少。

4. 忘记用 Git 兜底

Codex 会改文件、跑命令，但最终还是应该用 Git 管理风险。开始大任务前先确认工作区：

git status

完成后看 diff：

git diff

如果你让 Codex 做较大改动，最好每个阶段都 review 一次，不要等几百行 diff 堆在一起。

我的推荐 prompt 模板

代码修复

修复这个问题：<问题描述>

要求：
1. 先定位根因并简要说明。
2. 只修改必要文件。
3. 补充或更新相关测试。
4. 运行最小必要验证命令。
5. 最后汇报修改文件、验证结果和残余风险。

代码审查

请 review 当前未提交改动。

只关注：
1. 真实 bug
2. 行为回归
3. 安全风险
4. 缺失测试

不要给风格建议，除非它会导致明确问题。

项目接手

请阅读当前仓库，不要修改文件。

输出：
1. 项目用途
2. 技术栈
3. 入口文件
4. 主要模块
5. 本地启动命令
6. 测试和构建命令
7. 你建议写入 AGENTS.md 的项目规则

重构

重构 <模块/文件>。

目标：
1. 保持外部行为不变。
2. 降低重复逻辑。
3. 不引入新依赖。
4. 保留或补充测试覆盖。

请先给计划，等我确认后再改。

什么时候 Codex CLI 更适合我

迁移后，我发现 Codex CLI 特别适合这些场景：

• 本地仓库里的连续开发任务。
• 需要读多个文件、改代码、跑测试的工程任务。
• 需要严格权限控制和可审计操作记录的场景。
• 需要把团队规范固化到 AGENTS.md 的项目。
• 需要用 codex exec 做半自动化脚本的任务。
• 需要在终端里快速 review 当前 diff。

如果只是随便问一个概念，网页聊天也可以；但只要任务和本地代码、命令、测试、文件修改有关，我会优先打开 Codex CLI。

结语

这次迁移一开始是被动的：Anthropic 账户被封，原来的 Claude Code 工作流突然中断。但真正迁到 Codex CLI 后，我反而更重视“把 AI 编码代理工程化”这件事。

我的核心经验是：

• 把长期规则写进 AGENTS.md。
• 把个人偏好写进 ~/.codex/AGENTS.md。
• 把权限、模型、搜索和推理强度写进 ~/.codex/config.toml。
• 用小任务驱动 Codex，而不是一次性扔大需求。
• 每次修改后让 Codex 跑测试、做 review，再用 Git 检查 diff。

Claude Code 更像一个顺手的编码搭档；Codex CLI 更像一个可以被配置、约束和集成进工程流程的本地代理。迁移成本不高，但要用好它，关键不是换一个命令，而是把工作流从“临时聊天”升级成“可复用的工程协作系统”。