简体中文 | English
“授人以鱼不如授人以渔”
老子
这是一个开源的 Codex 使用讲解。本项目的重点不是针对某个非常具体的场景给一套 skills 或配置模板，而是告诉大家：哪些方法能显著提高 Codex 使用体验、一定程度降低模型幻觉，以及如何和 Codex 逐步磨合。这个 repo 里真正更有帮助的不是文件本身，而是下面这些经验总结，希望你耐心看完。本人主要用 Codex 做一些研究性质的工作，这就是本文的使用背景。
我一开始并不想先介绍一堆文件和配置参数。我更想先讲一个前提：Codex 是一个助手，他不是你项目的大脑，更不是领导者。相反，你才是。
先和 Codex 把架构和技术点聊透，再让他写代码，往往才是更稳的第一步。如果一上来就让他“自己想然后自己写”，那大概率会出错，不管是立刻运行时报错，还是未来埋下更深层的问题。
我的第一个想法，也是我觉得最重要的一点，就是：一定一定要先和 Codex 一起打磨想法和架构。你要先理解一些关键架构和技术点，再把自己的判断和顾虑说出来，让他带着这些前提去思考。也许这听起来没有某些 skills 那么“高级”，但相信我，和这条建议相比，后面很多技巧都只能算锦上添花。
关于如何用好 Codex，其实我们更需要的是采纳一些共性的使用技巧，然后多用、多反馈给 Codex。
下面这个循环，比“一上来就让 Codex 直接写完”更接近真实且高质量的使用方式：
flowchart TB
A["使用一些基础的<br/>AGENTS.md 和 prompt 技巧"]
B["开始和 Codex 聊<br/>技术点、边界和架构想法"]
C["聊得差不多后，给出反馈<br/>并让 Codex 开始写代码"]
D["任务过程中碰到问题<br/>发现新约束或新共识"]
E["把稳定结论和通用规则<br/>反馈进 AGENTS.md"]
F["继续接着聊技术点<br/>实现方式和下一轮方向"]
A --> B --> C --> D --> E --> F
F --> C
这个流程里有三个点尤其重要：
prompt负责把这一次任务讲清楚。AGENTS.md负责把多次任务里反复出现的共识沉淀下来。- 反馈不是“修修补补”，而是在逐步建立你和 Codex 的协作方式。
因此不难看出，Vibe Coding 不是什么特别复杂、也不是什么能玩出无限花样的技术，但在当下阶段，你确实不能指望它在没有你介入的情况下，从“有想法”到“写代码”再到“完全落地跑通”一气呵成。把现在的 Vibe Coding 当成打怪升级更合适：先拿一套新手村装备，慢慢打怪，慢慢磨练你驾驭它的能力，最后它就会像你身上的装备和武器一样，带你去完成更难的任务。
先记住一个核心原则：~/.codex/config.toml 放个人长期偏好（人话：让 Codex 写代码时的默认权限等设置），.codex/config.toml 放仓库级行为（人话：特定文件夹里你想让 Codex 获取的权限）。官方最佳实践也明确建议把个人默认配置和 repo 配置分层维护，而不是把所有东西都塞进一次性的 prompt 里。
Codex 使用大概有以下几种方式：
- Desktop Codex：适合本地开发，最大的优点是功能全面。一些 Plugins 可以直接浏览安装，非常方便。不过如果你只是刚开始用 Codex，其实下面这些使用方法差别没有那么大。个人觉得最有用的是做一个 Automation，每天整理技术前沿信息。
- IDE Extension：适合边看文件边提问。科研任务很多时候需要 SSH 连接，我个人觉得 Extension 里的 Codex 也完全够用。如果不够用，那就去服务器那边用 Codex CLI 起一些对话，完成 Extension 不太方便做的配置；过一会你通常也能在 Extension 里看到 CLI 开起来的对话。
- CLI：适合 shell-heavy 工作流、脚本化使用、远程环境。我自己不算常用，但功能和 Desktop Codex 差别不大。
推荐先用一个保守但实用的起步配置：
model = "gpt-5.4"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = false
writable_roots = ["YOUR_PROJECT_PATH"]这套配置的意思很简单：
model = "gpt-5.4"：官方示例配置里给多数用户的推荐模型。这里我也建议大家基本就用这个模型，效果足够，token 也不会烧得太快。approval_policy = "on-request"：需要时再请求你批准。如果你胆子比较大、又需要一堆窗口一起跑任务，也可以换成"never"。sandbox_mode = "workspace-write"：允许在当前工作区改代码，但不越界。network_access = false：默认不放网络，只有确实需要时再开。不是我们常规理解里的“完全离线”，很多时候正常的 search 能力依然够用。writable_roots = ["YOUR_PROJECT_PATH"]：这里可以理解为给 Codex 指定额外可写的项目路径。
这个文件本质上就是 Codex 必须遵守的一些规范。但不要觉得你必须先找到一份别人写好的、特别成熟的 AGENTS.md才能开始用。 你完全可以先按我下面建议包含的内容写一个初版。什么时候模型开始“不听话”了，或者 prompt 已经压不住问题了，再根据自己的实际情况慢慢修自己的版本。
因此，AGENTS.md 最适合放这些内容：
- 项目背景和目标
- 必跑命令，例如
test、lint、build - 代码风格、目录约定、命名规范
- 风险边界，例如“不要改 schema”“不要碰线上配置”
- 完成定义，例如“必须补测试”“必须更新 docs”
Codex 甚至大部分模型在完成任务时，遇到少见问题，或者一个任务拖得太久，幻觉都会变得比较严重。同时，因为 context 会不断压缩，一些规矩也会慢慢被忘掉。
这里结合我的经验，给大家两个我觉得非常值得加进去的方向，能够有效缓解模型幻觉和复杂任务里的上下文消耗过快：
# AGENTS.md
## Communication style
- Be objective, rigorous, and critical.
- Do not flatter, overpraise, or agree too quickly.
- Maintain a sober, evidence-seeking tone when discussing ideas; do not present speculative claims as established facts.
## Workflow
- Do not rely only on internal model knowledge for research discussions when external evidence is important.
## Coding workflow
- Before writing substantial code, first propose a minimal implementation plan.
- Prefer the smallest runnable slice first.
- Keep changes localized unless a broader refactor is explicitly requested.
## Tool usage
- Use external tools such as GitHub or paper/document access when external evidence is needed.
- When discussing ideas, related work, or external implementations, proactively search for relevant evidence when it is likely to improve accuracy or sharpen criticism.
- Use subagents only for clearly separable tasks.
- Avoid spawning subagents for casual brainstorming or small edits.
- For complex tasks, it is acceptable to spawn a small number of subagents when doing so materially improves parallel exploration, implementation, or verification.上面这些点，很多时候都能让 Codex 少一点阿谀奉承，多一点辩证思考；在面对稍微复杂一点、或者没太多人做过的任务时，也能一定程度减轻幻觉，并降低 context 消耗速度。
至于原理，其实不难理解。你可以把它想成一个人干活：如果不借助外部资料和别人做过的成果，就很容易钻牛角尖，这就是模型幻觉；如果又没人配合，很多东西都得自己硬记，那 context 自然就会越拖越长。
先说一个很个人的观点：你的大部分任务都不需要 skills，并且很多别人开源出来的 skills，对你来说很可能弊大于利。 图一乐可以，真干起活来会出现各种问题。如果你没有特别垂直、特别稳定的任务流，完全可以先跳过这个现在很火的技术。
当然，官方对 skills 的定义仍然很清楚：它是 reusable workflows。它不是“再写一份提示词”，而是把一类重复任务沉淀成可触发、可复用、可分发的能力包。
一个 skill 目录通常长这样：
.agents/skills/release-notes/
├── SKILL.md
├── references/
│ └── checklist.md
└── scripts/
└── collect_changes.sh
如果你现在还在饶有兴致地看 skills，我的建议是：先到这里就行。等你真的有这类需求了，再专门去学也不迟。
MCP 适合把外部文档、内部工具、知识库、系统接口接进 Codex。官方文档给出的配置方式很直接：
- 用
codex mcp管理 - 或者直接改
config.toml - 既可以配全局，也可以只配在可信项目里
举个非常直白的例子：GitHub 的 MCP，和你用了我的基础 AGENTS.md 再让 Codex 去 GitHub 上搜索，有什么区别？一个最容易理解的区别就是：GitHub MCP 能让 agent 访问到你的一些私有 repo，而普通的 web search 只能搜到公开 repo。至于要不要专门去折腾 MCP，你可以自己衡量。
你自己把一个任务打磨到很好用，再打包给别人，让别人也能舒服地复用这套流程，这就是 Plugins 很实用的地方。本质上它就是一种可安装、可分发的打包能力。
适合上插件的场景：
- 团队里很多人都需要同一组 skills
- 你想把 GitHub、Slack、Drive 之类的外部连接打包交付
- 你已经有一套稳定工作流，想让别人一装就能用
上面说到，subagents 能在一定程度缓解 context 飞速消耗；除此之外，也能让一些复杂任务跑得更快。本质上就是你之前对接的 Codex main agent 现在当组长了，有了一个小团队一起干活。 速度通常会更快，但你付的“工资”也就是 token，通常也会更多，这很容易理解。
至于怎么开始让 Codex 用 subagents，除了像我上面说的那样在 AGENTS.md 里稍微约束一下，你也可以直接在 prompt 里说“任务有点复杂，开 2-3 个 subagents”。如果你想写得更细一点，可以这样说：
先理解这个仓库，再用 2-3 个 subagents 并行做以下事情：
1. 梳理核心模块和调用链
2. 找出和本次改动相关的测试与风险点
3. 给出最小可行实现方案
最后由主 agent 汇总结论并实施。
但你指定 subagents 的工作，和让 Codex 自己分配任务，效果差别大吗？我只能说要看情况。我个人习惯让 Codex 自己去分配 subagents，就好比我是老板，我不想直接管下面每个人具体干什么，我更希望一个组长来对我汇报。
官方支持在 Codex App 里跑 recurring tasks，并且可以和 skills 组合使用。适合做这些事：
- 每天巡检错误日志或失败 CI
- 定期汇总最近代码变更
- 定时检查依赖、文档、告警、review 队列
如果某件事已经稳定到“不需要你每次重新解释”，那它就不该一直靠手动 prompt 重复触发，而应该被做成 automation。
如果你没有上面这些需求，还有个挺有意思的玩法：每天早上让它当你的新闻速递。如果你对某些信息不感兴趣，也可以直接写进给它的指令里。
看到这里，你应该也能感觉到：Codex 这种 Vibe Coding 没有神秘到需要掌握一大堆玄学技术。Codex 更像是一座桥，连接的是人的语言、想法和代码实现。你的想法和经验永远是第一位的。因此，与其一下子追着别人好用的“武器”跑，不如先把自己的“装备”磨好，多用、多反馈、慢慢迭代，这才更像真正的 Vibe Coding。
感谢 @GuoLuPM。他还开源了一个很有意思的 skills 项目，在开发过程中当满足触发条件时，就会启用对应的 skills，感兴趣的可以玩一下。