从 Cursor 迁到 Codex：别急着抄配置，先把脑回路迁过去

很多人做这个迁移时，第一反应都很自然：

“把 .cursor/rules 搬过去，把 .cursor/commands 搬过去，不就完了？”

我得先泼一盆冷水：真不是。

从 Cursor 到 Codex，最难迁的不是文件夹，而是词汇表。你以为两边都叫 Rules、Commands、Agent、AGENTS.md，应该差不多；结果一动手就发现，名字像亲戚，脾气像陌生人。你在 Cursor 里很顺手的那套玩法，照抄到 Codex 里，十有八九会得到一种很熟悉的工程体验: “配置写了不少，为什么就是不按我想的来？”

这篇文章基于两个东西来写：

• 一是我在 2026-04-23 查过的官方文档；
• 二是我这个博客仓库里真实留下来的迁移痕迹：仓库里还保留着 .cursor/commands/、.cursor/rules/，也有一份从 Cursor 迁到另一个 agent 体系的 MIGRATION_GUIDE.md，所以很多坑不是“听说”，而是“踩过”。

如果你正准备把一个已经在 Cursor 里跑顺的工程迁到 Codex，我建议先看完这篇再动手。能少走不少弯路。

先说结论：这不是“目录迁移”，而是“工作模型迁移”

先把最重要的一句放前面：

Cursor 更像“IDE 里的 agent 能力集合”，Codex 更像“以 AGENTS、sandbox、approvals、skills、hooks 为中心的 agent 运行时”。

这意味着迁移时不要盯着文件名，而要盯着“职责”。

我把最常见的映射先放一张表，方便你脑子里先立个坐标系。

如果你只记一条，那就是：

Cursor 的“Rules/Commands”思路，迁到 Codex 后，核心落点往往是 AGENTS.md + skills + hooks + approvals。

第一坑：不要把 Cursor Rules 直接迁到 Codex Rules

这可能是最容易踩、也最容易把人搞懵的一坑。

在 Cursor 文档里，Project Rules 的意思是给 Agent 持续喂上下文，放在 .cursor/rules，可以按 glob、手动引用、自动附着来生效。简单说，它解决的是“AI 应该怎么做事、遵守什么项目规范”。

但在 Codex 文档里，Rules 这页说的不是这个。它主要是控制哪些命令可以在 sandbox 外执行，本质上更接近“命令放行规则”。

同一个单词，完全不是一回事。

所以如果你把 Cursor 的写作规范、代码风格、输出模板，脑门一热塞到 ~/.codex/rules/default.rules 里，那基本就是把菜谱塞进门禁系统。它不是不能存，而是压根不管这事。

正确迁法

把原来 .cursor/rules/ 里的内容按这三个层次拆：

1. 全局习惯
   放到 ~/.codex/AGENTS.md

2. 仓库级约定
   放到项目根目录 AGENTS.md

3. 子目录特定规则
   放到对应子目录的 AGENTS.md

Codex 官方文档里讲得很明确：它会在启动时构建一条 instruction chain，从 ~/.codex/AGENTS.md 到项目根，再到当前工作目录，越靠近当前目录的文件越“后出现”，也就越容易覆盖前面的通用指导。

这套机制非常适合把原先散落在 .cursor/rules/*.mdc 里的内容重新组织一下。

一个实用写法

比如你原来在 Cursor 里有这些规则：

• core.mdc：通用风格
• security-security-baseline.mdc：安全底线
• writing-style.mdc：博客写作风格

迁到 Codex 时，可以这么拆：

# AGENTS.md

## Project Overview
- 这是一个个人博客仓库，主要内容是技术文章、journal 和工作文档。

## Working Agreements
- 修改博文时保留 frontmatter 和 license footer。
- 新 tech 文章默认放在 `content/tech/`。
- 改完文章要同步更新 `Modified` 字段。

## Writing Style
- 中文为主，避免 AI 腔。
- 先讲痛点，再讲反直觉观点，再讲读者能拿走什么。

## Validation
- 内容创作基于事实，不确定就给出处。

如果某个子目录有非常独立的玩法，比如 doc/source/5.work/ 专门写工作总结，那就在那个目录下再放一个更细的 AGENTS.md，别把所有东西都堆进仓库根文件里。

第二个小坑：AGENTS 不是越长越好

Codex 文档里还提到一个很容易被忽略的点：组合后的指令链默认有大小限制，project_doc_max_bytes 默认是 32 KiB。

也就是说，你不能把一个团队两年的制度文件、架构史、值班手册、命名规范、代码模板全贴进一个 AGENTS 里，然后指望 agent 每次都认真背诵。

我的建议很朴素：

• 根目录 AGENTS.md 只写高频、长期、跨目录的规则；
• 模块细则下沉到子目录；
• 大模板、长参考资料别硬塞 AGENTS，抽成 skill 或 reference 文档。

第二坑：不要把 .cursor/commands 直接理解成 Codex 的 slash commands

这也是一个“名字很像，功能不完全一样”的地方。

在 Cursor 里，Custom Commands 是一种很顺手的工作流复用方式。你在 .cursor/commands/ 下放 Markdown 文件，然后在聊天框里用 /design-doc、/review-code 这种命令触发。

但在 Codex 里，官方 app/CLI 的 slash commands 更偏“控制会话”和“调 agent 状态”，比如：

• /status
• /review
• /plan-mode
• /model
• /diff

它们当然很有用，但它们不是你原来那种“项目内自定义工作流模板”的一比一替代品。

正确迁法

把你原来 .cursor/commands/ 里的东西分成两类：

1. 产品级控制命令
   交给 Codex 自带的 slash commands

2. 项目内可复用流程
   迁成 skills，或者先写进 AGENTS.md / 团队文档里

我这个仓库就是个现成例子。仓库里还留着 .cursor/commands/blog-write.md、.cursor/commands/work-summarize.md 这些文件，后来在另一个 agent 体系里，它们被合并成更稳定的 skill。

这个思路迁到 Codex 一样成立：

• 把“写博客”“生成周报”“跑验收检查”这类复用流程提炼成 skill；
• 把“查看状态”“开 plan mode”“做 review”交给 Codex 自带命令。

一个判断标准

如果某个命令的本质是“告诉 agent 如何完成一类重复任务”，它更像 skill。

如果某个命令的本质是“切换当前会话状态或查看运行信息”，它更像 slash command。

这个边界想清楚，迁移时就不容易乱。

第三坑：先把 sandbox 和 approval 想明白，不然你会觉得 Codex “不听使唤”

很多第一次用 Codex 的人，前二十分钟最大的感受不是“强”，而是“怎么总要确认”“怎么这个也不让写”“怎么它不自己联网”。

这不是它笨，是它的安全模型跟 Cursor 不一样。

按 Codex 官方文档，版本控制目录默认推荐的模式是：

• workspace-write
• on-request approvals

同时，workspace-write 下网络默认还是关着的，除非你显式开启：

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

[sandbox_workspace_write]
network_access = false

这里有三个很要命的细节

1. workspace-write 不是“随便写”

官方文档明确提到，在默认 workspace-write 下，下面这些路径依然是只读保护的：

• .git
• .agents
• .codex

这意味着什么？

意味着如果你一边开着默认沙箱，一边又期待 agent 自己去改 .codex/config.toml、.codex/hooks.json，那它很可能会撞在保护墙上。

这不是 bug，这是故意的。

2. 网络默认是关的

很多人把 repo 迁过来以后，发现原来在 Cursor 里顺手就能跑的事情，在 Codex 里突然不行了。尤其是：

• 需要联网的脚本
• 需要访问外部 API 的 hook
• 运行时想 curl 一下外部资源

根因往往不是配置写错了，而是你还没有显式给网络权限。

3. Codex 的 web search 和 shell network 不是一回事

Codex 文档里还特地把这两件事拆开讲了。

简单说：

• web search 是 web search
• shell 里的联网命令是 shell 里的联网命令

你不能因为 agent “能搜网页”，就默认它的本地命令也能随便出网。

我建议的起步配置

如果你是从 Cursor 迁过来，刚开始别上来就 --yolo。先用一个比较稳妥的组合：

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

[sandbox_workspace_write]
network_access = false

先把这套跑顺，再按需要放开网络或加 prefix rules。否则刚换工具第一天就把护栏全拆了，后面出了问题，你都分不清是迁移问题还是安全边界问题。

Hooks 才是 Codex 迁移里最值得补的一课

如果说 AGENTS 解决的是“你希望 agent 平时怎么做事”，那 hooks 解决的是“在 agent 生命周期的关键节点，你想强制插入什么确定性动作”。

这玩意我很喜欢，因为它终于把很多“靠人记得住”的事，变成了“靠机制兜得住”的事。

Codex 官方文档把 hooks 定义得很直接：它是一个 extensibility framework，可以在 agent 循环里插 deterministic scripts。典型用途包括：

• 扫描 prompt 里有没有误贴的密钥
• 在会话结束时做额外校验
• 自动写摘要或日志
• 根据目录动态调整 prompt

先记住三件事

1. hooks 是实验特性
   要在 config.toml 里打开：

[features]
codex_hooks = true

1. hooks 配在 hooks.json
   最常用的位置有两个：

2. ~/.codex/hooks.json

3. <repo>/.codex/hooks.json

4. 不是所有平台都一样
   官方文档明确说了：Windows 目前暂时禁用 hooks。

最常用的几个事件

• PreToolUse：工具调用前
• PermissionRequest：申请权限时
• PostToolUse：工具调用后
• UserPromptSubmit：用户 prompt 提交时
• Stop：一轮结束时

对于团队治理来说，这几个点已经很够用了。

一个够用的 hooks 例子

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 .codex/hooks/check_command.py",
            "statusMessage": "Checking shell policy"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 .codex/hooks/check_secrets.py",
            "statusMessage": "Scanning prompt for secrets"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 .codex/hooks/write_summary.py",
            "statusMessage": "Writing summary"
          }
        ]
      }
    ]
  }
}

这套配置在真实工程里已经很有用了：

• PreToolUse 拦危险命令
• UserPromptSubmit 扫密钥和 token
• Stop 做摘要、落日志、跑一个轻量检查

Hooks 最容易踩的三个坑

坑 1：以为 hook 有严格顺序

Codex 文档明确说了：多个匹配同一事件的 command hooks 会并发启动。

翻成人话就是：

你不能指望 hook A 先跑完，再决定 hook B 要不要跑。它不是串行的流水线，更像几个并发的保安同时出门巡逻。

所以 hook 设计要满足三个词：

• 短
• 幂等
• 不依赖彼此顺序

坑 2：以为高优先级配置会覆盖低优先级 hook

也不是。

文档里说得很清楚：如果多个位置都有 hooks.json，匹配的 hooks 都会运行。高优先级层不会把低优先级层整个替换掉。

所以你在用户目录和仓库目录都配了相似 hook，很可能两个都跑。

坑 3：把 hook 当成“大而全的自动化平台”

我的经验是，hook 非常适合干“确定、短平快、可判定”的事。

适合：

• 扫敏感词
• 检查命令
• 补一段摘要
• 做轻量校验

不太适合：

• 跑一大堆慢测试
• 串复杂审批流
• 依赖很多外部网络服务的长链路任务

那些更重的流程，应该放 skill、CI 或独立 automation。

我推荐的迁移顺序：先保守，再抽象，最后清理

如果你问我“应该怎么迁最不容易翻车”，我的答案不是一次性重构，而是分三步走。

第一步：保留 .cursor/，先让 Codex 能在仓库里正常工作

别急着删旧目录。

先做三件事：

1. 在仓库根放一个靠谱的 AGENTS.md
2. 把最关键的测试、构建、目录约定写进去
3. 用默认安全模式跑几轮真实任务

这一阶段的目标不是“迁完”，而是“能用”。

第二步：把高频 commands 抽成 skills 或固定流程

我建议只先挑前三个最常用的：

• 代码 review
• 生成设计文档
• 博客/周报/工作总结

不要一上来就把 .cursor/commands/ 二十多个文件全量重写。那种迁法很容易写出一堆“看起来完整，但没人真用”的新壳子。

第三步：最后再补 hooks 和细粒度 approvals

很多人一上来就研究 hooks，最后折腾半天，连基本工作流都没跑通。

更稳的节奏是：

• 先跑通 AGENTS
• 再收敛 workflows
• 最后用 hooks 和 approvals 做治理

这样你会知道哪些摩擦是真问题，哪些只是“新工具还没用顺”。

常见翻车现场清单

下面这份清单，基本可以当迁移时的避坑卡片。

• 把 Cursor 的 .cursor/rules 直接迁去 Codex 的 rules，结果上下文完全没生效。
• 以为 Cursor 的 /blog-write、/design-doc 会自然变成 Codex slash commands，结果发现 Codex 的 slash commands 主要是会话控制。
• 把所有规范都塞进一个超长 AGENTS.md，结果超出默认大小上限，后面的内容压根没进上下文。
• 忘了 codex_hooks = true，写了半天 hooks.json，结果一个都没跑。
• 在默认 workspace-write 下让 agent 修改 .codex/ 里的配置，结果被只读保护挡住。
• 以为 hook 会按顺序执行，结果多个 hook 并发启动，互相踩脚。
• hook 脚本偷偷依赖外网，但 sandbox 默认没开网络，最后看起来像脚本 bug。
• 一开始就删掉 .cursor/，导致老工作流没法回退，团队里一半人直接炸毛。

我的建议：先迁“约束”，再迁“自动化”，最后迁“舒适性”

如果只给一个迁移原则，我会给这句：

先把 agent 做事的边界讲清楚，再把重复流程固化下来，最后才去追求顺手和炫。

边界靠什么？

• AGENTS.md
• sandbox
• approvals

流程靠什么？

• skills
• hooks
• MCP

舒适性靠什么？

• slash commands
• profiles
• statusline
• 自动化和子代理

这个顺序不要反。反过来做，通常就会变成“工具很高级，团队很疲惫”。

最后给你一份可执行清单

• [ ] 把 .cursor/rules 里的高频约定提炼到根目录 AGENTS.md
• [ ] 为复杂子目录单独补一份局部 AGENTS.md
• [ ] 只挑 2-3 个最高频 Cursor commands 先迁成 skills 或固定流程
• [ ] 先用 workspace-write + on-request approvals 跑顺真实任务
• [ ] 明确哪些脚本需要联网，再决定要不要打开 network_access
• [ ] 只加 1-2 个真正有价值的 hook，别一开始就搞 hook 大跃进
• [ ] 保留 .cursor/ 一段时间，给团队留回退和对照空间

工具总会换名字，界面也总会换风格。

但真正值得迁移的，从来不是某个按钮，而是你们团队已经打磨出来的那套做事方式：什么能自动，什么必须确认，什么要留痕，什么绝不能越线。

把这个迁过去，换工具就不会像搬家，更像换一把更顺手的扳手。

References

• Cursor Rules
• Cursor Commands
• Cursor Background Agents
• Codex AGENTS.md Guide
• Codex Hooks
• Codex Agent Approvals & Security
• Codex Skills
• Codex App Commands
• Codex CLI Slash Commands
• Codex Advanced Config
• Introducing Codex

本作品采用知识共享署名-非商业性使用-禁止演绎 4.0 国际许可协议进行许可。