Claude Code 到 Codex 迁移指南 2026
2026 年 5 月 3 日,我盘点了 744 条本地代理配置项,然后按运行权重对其中 691 条做了排序。1 数量看起来很大。但形态更重要:大约 20 个文件支撑着整个系统。
Claude Code 到 Codex 的迁移应该迁移运行契约,而不是复制文件树。把 CLAUDE.md 规则迁入分层的 AGENTS.md,把可复用流程迁入 Codex 技能,把确定性关口迁入聚焦的钩子,把风险姿态迁入配置档,把浏览器和来源工具迁入显式 MCP。不要把 Claude 的钩子网格原样复制到 Codex;要迁移证明义务。
TL;DR
私有写作和验证栈已经存在于我的 Codex 世界里。缺失的不是技能内容。缺失的是公开运行手册:可复用技能应该放在哪里,Codex 应该如何选择它们,公共写作应该使用哪个配置档,以及哪些 Claude 时代的关口应该变成 Codex 原生规则,同时不暴露私有工作流细节。
第一次真实 Codex 迁移改变了迁移规则:不要在移植的瞬间就把私有工作流变成环境默认行为。要分阶段。我的站点专用写作路径现在从仅显式调用开始,而迁移工作流作为用户技能供本地主动使用,并作为私有 Codex 包候选项用于本地测试。这个包不是开源项目,也不是通用可用版本;如果你想测试迁移工作流,请联系我。仅仅因为本地安装项存在,这个包不应该成为默认执行路径。真正的安装试点仍然需要包验证、插件安装验证、带命名空间的技能发现、重复项清理,以及新的 Codex 会话,之后才有意义。这让系统能先从真实工作中学习,再让工作流成为默认行为。181014
不要从克隆每个 Claude 钩子到 Codex 开始。先写 Codex 契约:
- 把持久的跨仓库策略放在
~/.codex/AGENTS.md。 - 把仓库策略放在
AGENTS.md,并把更窄的覆盖规则放在靠近工作的地方。 - 把可复用流程放在
.agents/skills或$HOME/.agents/skills。 - 把公共写作提升到
careful-review或专用的public-writing配置档。 - 保留确定性关口作为钩子,但把钩子视为一道护栏,而不是完整安全模型。
第一个成功的迁移产物应该是一篇能自我说明的文章。这个产物证明系统能描述自身,引用当前文档,使用经过净化的本地清单,并在 Codex 控制下产出公共作品,同时不发布背后的私有机制。
我在 Claude Code as Infrastructure 中介绍过栈里的 Claude 部分,在 AGENTS.md Patterns 中介绍过指令文件部分,在 Static Skills Are Dead Skills 中介绍过技能衰减问题。下面的迁移把这些线索连接到我实际使用的 Codex 执行环境。
相关背景还可以阅读 Codex CLI guide、Claude Code vs Codex、Codex vs Claude Code 2026、Claude Code Hooks Tutorial、Building Custom Skills 和 Jiro Quality Philosophy。这些文章解释了本次迁移在这里组装起来的各个部件。
迁移清单显示了什么?
本地系统有三个重心。
| 重心 | 核心文件 | 为什么重要 |
|---|---|---|
| Claude Code | settings、memory 文件、钩子调度器、质量准则 | 生命周期控制、质量哲学、提示阶段上下文注入、公共工作关口 |
| Codex | config.toml、全局/项目 AGENTS.md、配置档路由、插件、MCP |
模型选择、配置档路由、项目规则、Codex 执行环境姿态 |
| 写作 | 私有写作、引用、评估和 AI 可发现性技能 | 公共内容标准、引用策略、评估循环、AI 可发现性 |
使用数据指向同一个结论。我的配置档路由日志显示,重评审的工作主导了日常执行。1 真正的核心不是最长的文件,也不是最聪明的脚本。核心是决策层:它选择风险级别,加载准则,并在完成前强制要求证据。
这个发现改变了移植方式。
如果重要的是“Claude 有很多钩子”,迁移就会复制钩子。如果重要的是“系统有一套哲学”,迁移就会复制文字。清单显示了另一个答案:重要的是一个小契约,它在正确的时间触发。
发布前做了什么?
这篇文章本身成为了第一次迁移练习。
首先,我梳理了成熟 Claude Code 设置的形态:哪些部件治理行为,哪些部件只是记录偏好,哪些部件应该保持私有。然后我用官方文档和本地 CLI 检查当前 Codex 行为,因为迁移指南一旦继承旧标志或不受支持的配置形状,很快就会过期。然后我以真实迁移为背景起草本文,但把公开细节降到净化后的架构层面,而不是私有实现。
下一步发生在发布前:用这份指南搭建 Codex 设置,然后根据实际变化修订文章。公开文章应该展示迁移模式和验收标准。它不应该发布私有提示、私有写作工作流、精确钩子内部实现、敏感路径,或任何会让读者重建私有系统的内容。
这次真实迁移产出了一个可公开的证明表。我只发布契约、启用状态和验收信号,不发布私有提示、精确钩子主体或写作工作流内部细节。
| 迁移切片 | 公开经验 | 当前状态 |
|---|---|---|
| 迁移工作流 | 在任何包仍在变化时,把主动路径保留为用户技能。已安装包在证明发现能力和价值前,都应被视为试点。 | 本地已启用;私有包只作为本地安装试点安装,不作为公开发布。想测试的读者可以联系我。81014 |
| 包就绪度 | 在更广泛启用前验证私有或可共享包。市场机制是安装管道,不是发布承诺。 | 私有包验证器通过;本地安装试点证明了已安装插件状态和带命名空间的技能可见性;公开发布关口仍然阻塞。81014 |
| 本地框架健康 | 推广前不要依赖分散的手工检查。运行一个确定性健康关口,证明策略引用、配置档、技能、钩子、包状态、注册表形状和启用状态仍然一致。 | 手工健康关口通过;启用状态记录为安装试点,而不是发布。8 |
| 密钥和日志卫生 | 迁移并不会因为凭据移动到环境变量就变干净。要把可执行源码、文档、生成缓存、会话记录、shell 快照、日志和有意保留的密钥存储视为不同表面。 | 有界本地审计在适当处把辅助凭据转换为要求环境变量的配置,遮蔽了高置信度的模型可见历史,把轮换与源码清理分开追踪,并记录了预防钩子缺口,同时不发布私有路径、令牌值或检测器内部细节。8 |
| 跨代理协作 | 第二代理评审是输入,不是证明。Codex 仍要负责拒绝错误发现,只接受有依据的缺陷,修复最小真实问题,重新运行静态评审,然后运行本地验证。 | 评审/修复/再验证循环已在本地证明,覆盖缺失锚点时失败关闭、超时处理、空输出处理和 Codex 自有检查。8 |
| 指南维护 | 指南更新移植只有在命名来源证据、本地执行环境行为、公开路由渲染、发现文件、已服务爬虫路由、翻译状态和跳过的关口后,才算通过。 | 七次公开指南刷新在本地运行;引用、渲染和发现检查通过;一次修正了关于钩子事件、技能预算、钩子类型和不受支持并发上限的过期精确数量声明;另一次修复了生成版与服务版 llms-full.txt 不匹配;最近几次修正了模型/参数兼容性、基准/模型卡漂移、快速变化的插件发布漂移、渲染后 FAQ 结构化数据漂移、额度核算漂移、仅第三方 API/法律/功能最低要求声明,以及 frontmatter slug 路由漂移;最新 Codex 指南通过修正了相对 Codex CLI 0.130.0 过期的安装和市场说明,把指南翻译路径改为可选择提供方并默认使用 Codex,冒烟测试了 Codex 提供方路径,在写入缓存前拒绝截断的翻译输出,完成语言写入,验证语言路由,并用定向清理解决过期 CDN 响应。810 |
| 来源情报 | 有状态扫描器在写入记忆前需要试运行和写入量关口。配置了来源名称并不证明该来源真的被访问到。 | 有界扫描已在本地证明:拒绝了一次宽泛写入预览,一次窄扫描写入小批量私有记忆,并记录了来源可达性缺口,同时不发布私有来源列表。8 |
| 公司博客入门 | 公司写作器设置在目标公司、输出路径和采集证据明确前,不是文件生成命令。 | 现在仅显式入门会在写入前失败关闭,使生成的配置文件名与活跃博客写作核心对齐,并记录缺失采集信息,而不是创建空洞的公司配置。8 |
| 博客 i18n 审计 | 翻译覆盖率审计在作出覆盖声明前,需要发现存储、脚本、凭据和语言形状。绿色默认路由冒烟不等于完整语言覆盖。 | 审计工作流现在记录凭据关口、本地回退、过期可选脚本假设和遗漏的支持语言;针对遗漏语言的定向路由冒烟通过,而 D1 覆盖率和过期翻译状态仍是独立关口。8 |
| 博客翻译 | 翻译是具备写入能力的操作。路由健康和检测器输出不是写入许可。 | 翻译器现在会在缺少 D1 凭据、显式 slug/语言或可信队列时停止;返回完整历史目录的检测器被视为缩窄信号,而不是队列;Codex 提供方路径现在把翻译子进程与全局用户配置隔离,暴露显式模型/推理设置,在 checkpoint/D1 发布前阻塞残留过多的语言输出,在写入 D1 前拒绝畸形标题/描述元数据,并已让迁移文章在所有受支持语言上通过本地关口、D1 和线上路由验证。8 |
| Codex 自有博客发布循环 | 只有当 Codex 能以翻译、部署、CDN、线上路由和原生评审状态分离的方式发布真实文章时,迁移才算生产级。 | 四篇生产文章已经跑过 Codex 自有循环:文章评估、llms 再生成、通过 --provider auto 进行 Codex 翻译、本地 i18n 关口、D1 行、聚焦测试、精确路径提交、Railway 部署、定向 Cloudflare 清理、线上发布验证器通过、独立路由/schema 冒烟,以及明确待处理的原生评审包。8 |
| 发布路径 | 不要把本地检查、部署状态、CDN 新鲜度和线上内容证明折叠成一个绿色检查。迁移文章只有在规范 URL、渲染元数据、sitemap、llms-full.txt、本地化 JSON-LD、已部署提交和变更内容标记在生产环境通过后才算上线。过期 CDN 响应可能隐藏已部署修复。 |
在定向缓存清理、完整语言发布验证和推送提交的 Railway 部署确认后,生产文章路径已验证;后续指南发布工作增加了英文、本地化和 AI 发现路由的线上变更标记检查,然后才称发布完成。8 |
| 公共写作工作流 | 不要在私有写作器迁移的瞬间就把它变成环境默认。 | 仅显式试点。1 |
| 引用定义关口 | 从缺失和重复脚注定义开始;在理解积压前,把未使用定义视为清理债务。 | 针对变更公共 Markdown 的窄 Stop 钩子试点。28 |
| 最终验证 | 通过影子检查还不够;完成仍需要证据和已命名缺口。如果已有质量 Stop 关口能抓住确定性失败,就不要新增单独的总结钩子。 | 手工影子评审加现有质量 Stop 试点。8 |
| 会话上下文 | 当前性和公私边界提醒应该放在压缩会话上下文里,而不是放进私有提示转储。 | SessionStart 试点,带新的执行环境可见性证明。28 |
| 钩子映射 | Claude PostToolUse:Edit|Write 不会一对一映射到 Codex;本地 Codex 文件编辑通过 apply_patch 暴露。 |
Codex 形态的钩子试点和影子检查。2811 |
| 质量影子 | 非阻塞输出仍然能塑造下一次模型步骤。推广前要净化模型可见路径,并保持检测器高置信度。 | 非阻塞影子检查,带类别计数遥测、路径净化的建议输出和线上自我修正证明。8 |
你应该从钩子开始 Codex 迁移吗?
Claude 教会我按生命周期事件思考。UserPromptSubmit 钩子可以注入项目上下文。PreToolUse 钩子可以阻止敏感路径。Stop 钩子可以拒绝薄弱完成。这个模式在 Claude 中有效,因为我的本地栈围绕调度器成长起来,把许多小脚本变成一个有序事件管线。11
Codex 也有钩子,但当前 Codex 把它们视为带功能开关的生命周期系统,而不是永远启用的钩子目录。OpenAI 的钩子文档在 config.toml 中展示了 [features] codex_hooks = true,而我本地的 codex features list 报告 hooks 在 Codex CLI 0.130.0 上稳定且启用。28 OpenAI 文档说明钩子输入是 stdin 上的 JSON,包含会话 id、工作目录、事件名称和当前模型等共享字段。2 Codex 支持 SessionStart、PreToolUse、PermissionRequest、PostToolUse、UserPromptSubmit 和 Stop 等事件;PreToolUse 可以拦截 Bash、apply_patch 和 MCP 工具调用。2
同一份文档还给出了迁移中真正重要的警告:PreToolUse 仍是护栏,不是完整执行边界。文档指出,拦截不覆盖所有 shell 路径,也不会拦截网络搜索或其他非 shell、非 MCP 工具调用。2
这个限制并不让 Codex 钩子变弱。它意味着钩子不应该承载整个移植。OpenAI 还指出,同一事件的多个匹配命令钩子会并发启动,所以如果 Codex 移植需要顺序,仍然需要调度器或一个合并后的钩子命令。2
对 Codex 来说,我想让钩子处理狭窄的确定性检查:
- 阻止明显破坏性的 shell 命令。
- 对凭据形状的路径发出警告。
- 添加小型会话启动上下文。
- 记录公共写作运行的证据。
- 当缺少必需产物或验证命令时,让停止事件失败。
我不想让钩子承载写作声音、引用策略、哲学、路由或项目准则。Codex 已经有更好的归宿。
Claude 产物如何映射到 Codex?
当每个 Claude 产物都映射到最匹配其职责的 Codex 原语时,迁移会更干净。
| Claude 产物 | Codex 目标 | 移植规则 |
|---|---|---|
CLAUDE.md |
~/.codex/AGENTS.md 加仓库 AGENTS.md |
只移植运行规则,不移植人类文档。13 |
| 钩子调度器 | Codex 钩子加验证命令 | 保留必须在生命周期时间运行的检查。11 |
| 博客技能 | $HOME/.agents/skills 或仓库 .agents/skills |
用技能描述触发 Codex 隐式选择 |
| 哲学文件 | AGENTS.md 准则加聚焦技能 |
让质量准则可执行,而不是装饰性文字 |
自定义斜杠命令和旧 .claude/commands 文件 |
技能加必要时的薄启动器 | 把可重复工作流变成技能,把 $skill-name 视为可靠的显式调用,并只把 /name 作为便捷包装器或选择习惯,同时要有证明。41512 |
| MCP 配置 | config.toml 中的 [mcp_servers.*] 或 codex mcp add |
保持服务器设置显式且可检查 |
| 代理角色 | Codex 子代理或任务专用技能 | 只有当角色有边界清晰的输出时才委派。9 |
OpenAI 的 AGENTS.md 文档让第一行成为迁移主干。Codex 会在工作前读取 AGENTS.md 文件,从 Codex 主目录加载全局指导,然后从项目根目录走到当前目录,让更近的文件覆盖更早的指导。3 这种行为匹配我真正需要从 CLAUDE.md 得到的东西:持久工作约定加项目本地细节。
关键动作是:把规则重写为操作。“认真写作”不属于 AGENTS.md。“对于公共文章,先收集引用,验证 URL,运行禁用短语检查,并报告任何未验证声明”属于那里。
私有写作技能应该如何迁移到 Codex?
博客写作栈很容易移植,因为它已经有正确的形态。Codex 技能是一个包含 SKILL.md 文件的文件夹,文件中包含 frontmatter 和指令。Codex 可以在用户显式调用技能时,或任务匹配技能描述时启用技能。4 Codex 会从仓库、用户、管理员和系统位置读取技能,包括仓库 .agents/skills、$HOME/.agents/skills 和 /etc/codex/skills。4
Claude Code 迁移在这里很容易微妙出错。Codex 技能不是 Claude 斜杠命令。显式调用的官方 Codex 技能路径是技能选择器或 $skill-name 提及,而 Codex CLI 斜杠命令是另一套交互控制界面,用于 status、permissions、model changes、plugins 和会话控制等内置动作。415 像 /cave 这样的提示,如果技能描述能识别它,或有包装器把它转换为 Use $cave ...,仍然可以作为便捷写法,但斜杠文本本身不是持久契约。迁移证明应该测试 $skill-name;然后只有在你承诺兼容性时,才单独测试 /name。
这意味着我应该把新的 Codex 原生写作技能规范化到官方技能路径中,而不发布私有技能名称或内容:
$HOME/.agents/skills/source-verifier/SKILL.md
$HOME/.agents/skills/public-post-writer/SKILL.md
$HOME/.agents/skills/site-specific-writer/SKILL.md
我的本地执行环境里也有位于旧位置的可用用户技能。1 我不应该仅仅因为公开文档写的是 .agents/skills 就删除它们。安全迁移是:
- 复制或符号链接一个技能到
$HOME/.agents/skills。 - 重启 Codex。
- 确认 Codex 列出并启用该技能。
- 在试点期间让该技能只接受显式调用。
- 只有在发现和试点使用都可用后,再迁移其余技能。
- 在现有会话和脚本不再依赖旧路径前,保留旧路径。
这是我对第一个私有写作工作流采用的路径。我把一个站点专用写作器分阶段设为仅显式调用的私有技能,而不是让它成为每个内容任务的默认写作器。这给迁移提供了更好的测试:如果这个技能改善了本文和下一次公共写作运行,并且不泄露私有流程,它就可以从仅显式调用进入试点。如果它增加混乱,就继续保持范围受限。
品牌专用写作器不应该成为默认站点写作器。私有产品写作器可以共享同样的引用和评审标准,但它的受众、产品事实、行动号召和声音规则应该限定在该产品内。正确的移植会把品牌适配器分开,并为 blakecrosley.com 创建一个薄的站点专用写作器。
这个站点技能应该保持很薄:
---
name: site-specific-writer
description: 为特定站点撰写公开技术文章。用于需要已验证来源、内部链接、站点声音和发布检查的文章。
---
# 站点专用写作器
每一篇公开技术文章都要使用私有写作、来源验证和 AI 可发现性技能。
最终回复前需要的证明:
- 外部技术声明有引用。
- 当前 Codex 声明引用 OpenAI 文档。
- 内部声明链接到现有文章或标注为作者分析。
- 在有用时,文章包含 TL;DR、按角色划分的要点和读者问题。
Codex 技能文档展示 name 和 description 是手写技能 frontmatter 字段,并说明描述是隐式启用的触发器。4 正文可以告诉 Codex 使用私有配套技能;除非本地工具链增加额外元数据,否则组合关系属于指令。通用栈拥有写作规则。站点包装器拥有声音、链接模式和证明。
同样的拆分也适用于迁移工作流本身。OpenAI 的插件文档建议,当你仍在迭代一个个人工作流时,从本地技能开始;当你想跨团队共享稳定包或捆绑更多集成时,再构建插件。10 这让主动路径很清楚:先用户技能,再私有包试点。我没有开源迁移技能,也没有承诺公开发布;如果你想测试它,请联系我。一次插件缓存探测显示,已安装插件技能会出现在插件命名空间下,而不是裸技能名下,所以包文档应该区分直接技能使用和插件安装后的技能使用。8
私有包在需要发布叙事前,需要验证器。最新一轮中,我添加了一个验证器,检查市场 JSON、插件 manifest、技能 frontmatter、必需引用、引用检查器语法、安装策略、是否不存在活跃钩子或 MCP manifest、生成文件,以及明显的私有路径或密钥样本泄露。这个检查应当发生在任何更广泛启用之前,因为 OpenAI 插件文档把市场定义为安装表面,而不是不稳定私有工作流的草稿区。810
AGENTS.md 应该如何承载公共写作规则?
最有力的 Codex 迁移变化属于 AGENTS.md,而不是钩子。公共写作需要默认风险等级。
这是我想放在全局或项目文件靠前位置的规则:
## 公共写作是产品工作
公共文章、指南、会影响用户理解的落地页和文档,以及产品文案,至少使用 `default` 配置档。当声明、引用、品牌、金钱、安全、安保或用户信任受到影响时,提升到 `careful-review`。
完成公共写作前:
- 起草前收集引用。
- 当前工具行为引用官方产品文档。
- 清楚标注作者分析。
- 运行禁用短语扫描。
- 验证内部链接。
- 报告任何无法验证的声明。
这条规则修复了我在路由器清单中发现的缺陷。有些内容工作漂移到了快速执行,因为路由器把“内容”当成廉价工作。公共写作在改变人们相信、购买、安装或运行的东西时并不廉价。博客草稿、指南和产品页面比日常代码编辑更值得评审,因为失败模式是公共信任,而不是本地测试失败。
你正在阅读的这篇文章就是例子。它引用当前 Codex 文档来说明当前 Codex 行为。它把本地清单声明标注为作者分析。它使用真实栈,而不是假装迁移从空白机器开始,但它把私有实现细节留在公开文章之外。
Codex 配置档应该如何编码风险?
OpenAI 的配置参考把 profile 定义为启动时的默认配置档,并支持对受支持配置键进行配置档范围覆盖。5 同一份参考把 model_reasoning_effort、approval_policy 和 sandbox_mode 定义为显式配置控制项。5
这给了 Codex 一个编码风险的自然位置。
[profiles.public-writing]
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
web_search = "live"
具体模型可以变化。策略不应该变化。公共写作需要更高推理强度,在事实可能变化时进行实时来源检查,限制在工作区内执行,并对离开安全工作路径的动作要求人工批准。
路由器应该把这类任务映射到 public-writing 或 careful-review:
- 博客文章、指南或首页变更。
- 任何带引用的文章。
- 任何比较工具或供应商的内容。
- 任何提到当前 Codex、Claude Code、OpenAI、Anthropic、Apple、Google 或其他快速变化产品的文章。
- 任何触及 schema、
llms.txt、SEO、分析或公共元数据的工作。
配置档不是一种氛围。配置档是风险预算。
哪些 Codex 钩子仍然重要?
Codex 钩子应该强制执行那些必须在执行时发生的小事。
公共写作停止钩子可以检查变更文件,并在公共 Markdown 文章包含脚注引用但没有定义时拒绝完成。工具前钩子可以在代理尝试编辑 .env、分析凭据或生成翻译缓存时发出警告。会话启动钩子可以添加当前日期,并提醒 Codex,“最新”声明需要验证。
保持钩子载荷小。OpenAI 文档说明了钩子的 JSON 输出形状,包括 systemMessage、continue 和事件专用字段。2 用这些字段阻止或警告精确失败。不要重建整个 Claude 调度器网格,除非 Codex 失败数据证明你需要它。
设置测试不能赢得推广。钩子只有在真实使用观察通过后,才应该走出试点:它在预期场景触发,通过普通工作,并记录安全的聚合遥测,而不是私有内容。如果触发阻塞,原因必须告诉用户下一步该做什么。28
第一次真实运行后,实际钩子积压如下:
SessionStart:把紧凑的当前日期、当前性、项目和公私边界上下文保留在试点中。PreToolUse:Bash:把窄范围破坏性命令和凭据读取护栏保留在试点中。PostToolUse:apply_patch:把针对变更代码/配置补丁行的非阻塞质量影子检查保留在试点中。Stop:把变更公共 Markdown 引用关口保留在试点中。Stop:把最终验证契约折叠进现有质量 Stop 试点;在真实失败证明需要前,不创建单独总结钩子。
这组迁移了安全行为,而没有导入数月积累的 Claude 专用仪式。
MCP 和浏览器工具应该如何配合?
我当前的 Codex 设置已经使用一条由私有 MCP 支持的浏览器自动化路径。1 Codex 也通过 CLI 和 config.toml 支持 MCP 服务器:codex mcp add 可以注册 stdio 服务器,而 [mcp_servers.<server-name>] 表可以定义 command、args、environment、URLs、enabled_tools、disabled_tools 和 timeouts。6
对于公共写作,MCP 属于两个地方:
- 用浏览器自动化检查线上渲染页面、截图和本地预览。
- 当特定提供方暴露可靠 MCP 服务器时,用于来源发现或文档检索。
MCP 不应该隐藏来源链路。博客写作器需要读者可以点击的引用,而不是只存在于会话内部的私有工具结果。MCP 可以帮助找到事实。最终文章仍然需要公开来源。
如何引导 Claude Code 到 Codex 的迁移?
第一个 Codex 原生产物应该一边使用移植成果,一边描述这个移植。
这是交互式引导循环:
codex -p careful-review --search \
"盘点本地 Codex 和 Claude 迁移表面,然后为一篇关于把设置迁移到 Codex 的净化后文章创建引用库。"
codex -p careful-review \
"使用本地清单、官方 Codex 文档和现有内部文章起草 content/blog/claude-code-to-codex-migration.md。清楚标注作者分析。"
codex -p careful-review \
"评审草稿中的无依据声明、过期 Codex 标志、损坏内部链接和 AGENTS.md 运行价值。"
对于非交互式工作,使用 codex exec,并把实时搜索作为配置/配置档事项,而不是复制交互式 --search 标志。OpenAI 文档说明 codex exec 用于脚本或 CI 风格运行,并支持 --profile、--sandbox 和 --config 覆盖;我本地 Codex CLI 0.130.0 的帮助信息确认这些标志,并拒绝 codex exec --search。78
codex exec -p careful-review -c 'web_search="live"' \
"为 content/blog/claude-code-to-codex-migration.md 从官方 Codex 文档和净化后的本地清单创建引用库。"
codex exec -p careful-review \
"评审 content/blog/claude-code-to-codex-migration.md 中无依据的 Codex 声明、过期标志、损坏内部链接和 AGENTS.md 运行价值。"
命令行细节很重要。OpenAI 将 --full-auto 标记为已弃用兼容标志,并建议改用 --sandbox workspace-write。7 以 --full-auto 为中心的旧指南不应该控制新的自动化。
文章本身成为验收测试。如果 Codex 能:
- 加载写作技能。
- 使用
careful-review。 - 引用当前 OpenAI 文档。
- 使用本地清单而不暴露私有实现细节。
- 解释
AGENTS.md、技能、钩子、配置档和 MCP 中的变化。 - 在站点仓库中产出干净的 Markdown 文章。
那么写作移植就是有效的。
Claude Code 到 Codex 迁移清单
对于 Codex 配置:
- 添加或更新
~/.codex/AGENTS.md,写入全局工作约定。 - 添加仓库
AGENTS.md公共写作规则。 - 创建
public-writing,或把公共写作路由到careful-review。 - 让
careful-review对公共声明真正使用 high 或 xhigh 推理。 - 添加一条路由规则,把指南、博客文章、文档和产品文案视为公共表面工作。
对于技能:
- 一次一个地把私有写作技能移动或镜像到
$HOME/.agents/skills。 - 在把插件包视为执行路径前,把正在主动测试的迁移工作流保留为用户技能。
- 使用
$skill-name作为规范显式调用测试;把/name视为便捷包装器或选择习惯,而不是 Codex 技能已加载的证明。 - 在市场启用前添加包就绪度验证器。
- 添加本地框架健康关口,在推广前证明 AGENTS 引用、配置档、技能、钩子、包状态、注册表形状和启用状态。
- 对安装试点,验证市场添加、插件读取/安装、插件列表、技能列表、新会话技能可见性和重复市场项清理。
- 在允许隐式启用前,让试点技能保持仅显式调用。
- 把通用写作标准与站点专用声音分开。
- 把来源验证保留为硬事实关口。
- 把 AI 可发现性检查与作者声音分开。
- 创建薄的站点专用写作器技能,而不是复用品牌专用写作器。
- 每次移动后确认 Codex 发现技能。
对于跨代理协作:
- 让 Codex 继续拥有循环。
- 把评审锚定到真实文件或上下文产物。
- 当锚点缺失、输出为空或第二代理超时时失败关闭。
- 用本地证据拒绝无依据的第二代理发现。
- 只接受有依据的发现,应用最小修复,重新运行静态评审,然后运行 Codex 自有检查。
对于钩子:
- 先只移植确定性检查。
- 用
SessionStart、PreToolUse、PostToolUse和Stop处理窄关口。 - 先记录失败,再添加更多关口。
- 对影子钩子,记录类别而不是原始私有内容。
- 推广前测试一个已知失败样本和一个已知嘈杂样本。
- 在强制执行迁移检查前,区分干净失败和清理债务。
- 把钩子视为执行时检查,而不是规范准则存储。
对于写作工作流:
- 起草前收集引用。
- 对当前 Codex 行为使用官方文档。
- 对本地清单和经验使用作者分析。
- 在现有内部文章已经解释概念时链接它们。
- 最终前运行验证。
- 对指南维护,验证来源和执行环境声明,同步派生公共表面,重新生成发现文件,并命名跳过的翻译、部署和线上检查。
- 对翻译指南,记录所选翻译提供方、差异批次或章节数量、凭据状态但不记录值、是否发生写入/上传、语言验证,以及执行被阻塞时的不写入原因。
- 对密钥和日志卫生,分开处理可执行源码、文档、生成缓存、会话转录、shell 快照、日志和有意保留的密钥存储;在把迁移工作流视为安全之前,遮蔽历史并把辅助工具转换为要求环境变量的配置。
- 部署后,验证规范 URL、结构化数据、sitemap、
llms-full.txt、部署状态、CDN 新鲜度和生产环境变更内容标记。 - 如果 CDN 缓存提供过期内容,只通过现有部署路径清理受影响的公开 URL,然后重新检查变更标记。
FAQ
私有写作技能需要公开吗?
不需要。迁移文章可以描述写作系统的形状,而不发布私有技能名称、提示、评分细节或品牌专用适配器。公开经验是这些技能应放在哪里,以及 Codex 应如何启用它们。
迁移技能遵循同样规则。它目前是私有的,不是开源包。如果你想测试这个工作流,请联系我。
Claude Code 到 Codex 的迁移应该复用品牌专用写作器吗?
不应该。品牌专用写作器应该保持品牌专用。个人或公司站点需要一个薄的站点适配器,既共享验证标准,又不继承另一个产品的受众、事实或行动号召。
我应该把每个 Claude Code 钩子都复制到 Codex 吗?
不应该。只有在识别背后的契约后才复制行为。凭据阻断属于钩子。写作评分标准属于技能。风险规则属于配置档或路由器。哲学属于 AGENTS.md 加聚焦技能。
Codex 技能应该放在哪里?
对于新的 Codex 原生工作,使用官方技能位置:仓库 .agents/skills 放项目技能,$HOME/.agents/skills 放用户技能。4 如果现有本地设置也使用 ~/.codex/skills,保留它,直到 Codex 发现能力确认新位置有效。
为什么 /skill 提示在 Codex 中有时会失败?
因为 /skill 不是规范的 Codex 技能调用契约。Codex 技能会在你选择或显式提及技能时启用,包括 $skill-name,也会在任务匹配技能描述时启用。4 Codex CLI 斜杠命令是自己的内置命令界面。15 当你需要确定性技能启用时,使用 $skill-name。只把 /name 保留为便捷包装器、选择习惯或提示短语,而且它仍然需要自己的证明。
Claude Code 到 Codex 迁移的核心是什么?
核心不是钩子、技能或配置档本身。核心是在工作开始前回答四个问题的决策层:来了什么类型的工作,应该用什么风险配置档,哪些指令治理它,完成前必须存在什么证明?
关键要点
对于 Codex 用户: 移植契约,不要移植目录。AGENTS.md、配置档、技能、MCP 和钩子各有职责。把每条规则放在 Codex 最直接遵守的位置。
对于迁移过来的 Claude Code 用户: 把 Codex 钩子视为护栏,而不是成熟 Claude 调度器系统的完整替代。先从 AGENTS.md 和技能开始,然后在需要执行时强制约束的地方添加钩子。
对于公共写作者: 博客写作属于高评审配置档。当前声明需要当前来源。精致但错误的文章比坏掉的本地脚本更快损害信任。
对于我自己的栈: 私有写作系统不再只是实质上移植完成;第一个站点专用写作器已分阶段设为仅显式调用,迁移工作流作为用户技能启用,私有插件包通过了本地安装试点,但没有成为公开发布。Codex 准则现在把质量和品味变成运行规则。最终验证总结保持为手工影子评审,其窄确定性检查被折叠进现有质量 Stop 试点,而不是变成单独钩子。一个紧凑的 SessionStart 上下文钩子处于试点中,第一个活跃质量钩子以影子模式观察 apply_patch 变更,第一个 Bash 前安全护栏作为窄范围阻断试点运行,引用检查器现在作为变更公共 Markdown Stop 试点运行,指南维护运行在真实公共文档上证明了从来源到渲染的循环,一次运行修正了过期精确数量声明而不是保留旧来源框架数字,另一次捕捉到生成版与服务版 AI 发现路由不匹配,近期运行修正了模型/参数兼容性、基准/模型卡漂移、快速变化的插件发布漂移、渲染后 FAQ 结构化数据漂移、额度核算漂移、仅第三方 API/法律/功能最低要求声明和 frontmatter slug 路由漂移,最新 Codex 指南运行让指南翻译可选择提供方,对 Codex 自有工作默认使用 Codex 提供方,在写入缓存前拒绝截断的翻译输出,完成语言写入,验证语言路由,并用定向清理解决过期 CDN 响应,而不是默默依赖只适用于 Claude 的路径。一次有界密钥/日志卫生运行在记录轮换、遮蔽和预防钩子缺口前,把源码、文档、生成缓存、会话记录、shell 快照、日志和有意保留的密钥存储分开。发布循环现在把本地检查、部署状态、CDN 新鲜度和线上变更标记证明视为独立关口。一次来源情报运行在写入私有记忆前证明了试运行/写入量纪律,公司博客入门路径现在会在目标/路径/采集证据不明确时在文件生成前停止,博客翻译器现在会在缺少 D1 凭据或显式目标时在写入执行前停止,并在凭据存在时拒绝残留过多的 Codex 输出发布,一个跨代理协作循环证明了评审/修复/再验证,同时没有把权威交给第二代理,一个手工本地框架健康关口会在任何更广泛启用前检查确定性推广表面。下一步工作是继续证明剩余的仅显式生产仪式,继续把公开发布边界停在那里,并继续让真实公共写作和工程工作穿过分阶段通道,再扩大任何关口。
参考资料
-
作者于 2026 年 5 月 3 日从本地 Codex、Claude Code、代理和仓库配置生成的私有本地清单。本文中的公开声明使用经过净化的聚合发现,而不是原始清单内容或私有实现细节。 ↩↩↩↩↩↩
-
OpenAI, “Hooks,” OpenAI Developers, accessed May 5, 2026, https://developers.openai.com/codex/hooks. ↩↩↩↩↩↩↩↩↩↩
-
OpenAI, “Custom instructions with AGENTS.md,” OpenAI Developers, accessed May 5, 2026, https://developers.openai.com/codex/guides/agents-md/. ↩
-
OpenAI, “Agent Skills,” OpenAI Developers, accessed May 5, 2026, https://developers.openai.com/codex/skills. ↩↩↩↩↩↩↩
-
OpenAI, “Configuration Reference,” OpenAI Developers, accessed May 5, 2026, https://developers.openai.com/codex/config-reference. ↩↩
-
OpenAI, “Model Context Protocol,” OpenAI Developers, accessed May 5, 2026, https://developers.openai.com/codex/mcp/. ↩
-
OpenAI, “Command line options,” OpenAI Developers, accessed May 5, 2026, https://developers.openai.com/codex/cli/reference. ↩↩
-
作者于 2026 年 5 月 3-15 日使用
codex-cli 0.128.0和codex-cli 0.130.0进行的本地和生产验证。检查覆盖 Codex 功能状态、配置档和沙箱标志、交互式与非交互式搜索行为、MCP 列表和官方文档检索、用户技能发现、插件缓存命名空间行为、钩子事件/工具名称、会话启动可见性、Bash 护栏行为、引用 Stop 行为、质量影子建议行为、AGENTS 执行环境引用验证、本地框架健康验证、渲染后文章元数据、sitemap 和llms-full.txt收录、生产规范 URL 行为、通过定向缓存清理解决过期 CDN404、市场停放状态和安装试点状态,一次有界密钥/日志卫生审计在记录遮蔽、轮换、辅助配置、预防钩子和取证历史缺口前,分离了可执行源码、公共/私有文档、生成缓存、会话记录、shell 快照、日志和有意保留的密钥存储,以及真实指南维护刷新:这些刷新在记录跳过的翻译、部署和线上生产关口前,检查了当前来源/执行环境证据、公共路由渲染、引用、AI 发现文件、已服务发现路由和派生模板,其中包括一次修正过期钩子事件、技能预算、钩子类型和并发限制声明,而不是保留无依据来源框架数字的运行;一次发现并修复生成版llms-full.txt与服务路由不匹配的运行;一次根据当前官方产品文档修正模型/参数兼容性和渲染后 FAQ 结构化数据漂移的运行;一次修正基准/模型卡漂移、快速变化的插件发布漂移、sqlite 扩展发布漂移、CLI 时间线和渲染后 FAQ 基准文案的运行;一次修正额度核算、移除无依据仅第三方功能最低要求、根据官方产品和帮助文档软化未记录 API/私有测试版和法律赔偿声明、修复 frontmatter 指南 slug 泄漏到 AI 发现文件并为暴露指南 URL 添加别名重定向的运行;以及聚焦 Codex 指南运行,这些运行修正了过期 v0.130 安装和市场说明,验证了渲染指南输出,让指南翻译可选择提供方,冒烟测试 Codex 提供方路径,在写入缓存前拒绝截断的翻译输出,完成支持语言写入,验证语言路由,并通过定向清理解决过期 CDN 响应。同一时期还包括一次公司博客入门运行,它在缺少显式目标/路径/采集信息时停止在文件生成前,并让配置文件名与活跃博客写作核心对齐;一次博客 i18n 审计运行,它把路由冒烟与翻译覆盖分开,记录凭据关口、过期可选脚本假设和语言集合漂移,同时不暴露私有工作流细节;一次针对遗漏语言的路由冒烟通过,同时保持覆盖率和过期翻译状态分离;一次博客翻译关口运行,因为缺少 D1 凭据和显式 slug/语言且检测器指向完整历史目录,所以在写入执行前停止;一次迁移博客翻译发布尝试暴露了全局 Codex 推理配置牵引,添加显式提供方模型/推理隔离,只 checkpoint 通过的语言,并让残留过多的语言输出不被推广;一次后续发布运行让所有支持的迁移文章语言通过本地残留关口、D1 发布、线上本地化路由、BlogPosting/Breadcrumb/FAQ JSON-LD 验证、定向 Cloudflare 前缀清理和 Railway 对提交7624ce5d的部署确认;一次指南翻译/发现发布通过聚焦测试,以提交e5706f8a推送,确认 Railway 生产服务上下文,清理变更公共 URL,并验证英文、本地化和 AI 发现路由上的变更标记;一次有界来源情报运行在写入小批量私有记忆并记录来源可达性缺口前,试运行了候选数量;以及一次跨代理评审/修复/再验证循环,它拒绝了一个错误的第二代理发现,接受了一个有依据的缺陷,重新运行静态评审,并通过本地执行环境检查。随后,agentic-design-control-surface、agent-interface-is-the-harness、html-is-the-format-agents-want和agents-need-supervision-surfaces的 Codex 自有博客发布各自完成生产循环,包括通过--provider auto选择 Codex 翻译、九个支持语言的本地 i18n 关口通过、D1 行验证、聚焦测试和密钥扫描证据、精确路径提交、Railway 部署成功、针对 13 个变更 URL 的定向 Cloudflare 清理、线上发布验证器通过、独立路由/schema 冒烟,以及单独待处理的原生评审包。私有包就绪度审计返回PASS package validation;本地安装试点显示插件已从市场 JSON 路径安装并启用,捆绑技能出现在其插件命名空间下,重复本地包启用已移除,新的 Codex 会话看到了带命名空间的技能。本地框架健康关口在 AGENTS 引用、配置档、必需技能、钩子、包验证、注册表形状和已记录启用状态上返回PASS codex harness health。精确私有探测标签、钩子内部、来源列表、令牌形状、检测器模式、路径和私有工作流细节被有意省略。 ↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩ -
OpenAI, “Subagents,” OpenAI Developers, accessed May 5, 2026, https://developers.openai.com/codex/subagents. ↩
-
OpenAI, “Build plugins,” OpenAI Developers, accessed May 5, 2026, https://developers.openai.com/codex/plugins/build. ↩↩↩↩↩↩
-
Anthropic, “Hooks reference,” Claude Code Docs, accessed May 5, 2026, https://code.claude.com/docs/en/hooks. ↩↩↩
-
Anthropic, “Extend Claude with skills,” Claude Code Docs, accessed May 5, 2026, https://code.claude.com/docs/en/skills. ↩
-
Anthropic, “How Claude remembers your project,” Claude Code Docs, accessed May 5, 2026, https://code.claude.com/docs/en/memory. ↩
-
OpenAI, “Codex App Server,” OpenAI Developers, accessed May 6, 2026, https://developers.openai.com/codex/app-server. ↩↩↩
-
OpenAI, “Slash commands in Codex CLI,” OpenAI Developers, accessed May 6, 2026, https://developers.openai.com/codex/cli/slash-commands. ↩↩↩