第一次打开 Codex，很多人做的第一件事是输入"帮我做个网站"，然后盯着它刷屏。
几分钟后，页面确实能打开。然后你会发现按钮点不动，手机上排版全散了，刷新一下刚填的东西没了。最难受的是，你不知道它到底改了哪些文件，也不知道它为什么这么改。
这篇东西就是为了让你别走那一遭。
读完之后，你应该能在正确的目录里给 Codex 一个边界清楚的任务，看懂它改了什么，用证据判断它是不是真做完了，最后把这套做法固定下来，变成以后能反复用的规则和工具。不需要你是程序员。会建文件夹、会装软件、会复制命令，愿意每一步都看一眼结果，就够了。
全文分九章，前面八章是一条从零到能用的路，最后一章是随手翻的手册。
一到二章：Codex 是个什么东西，从哪个入口进，怎么装上三到四章：界面怎么看，第一个真任务怎么从需求走到验收五到六章：上下文怎么管，模型和命令怎么选七到八章：什么时候值得做 Skill、接 MCP、开定时任务，外加三个能照着做的案例第九章：踩坑清单、提示词模板、速查表开工前的几句交代版本。 所有产品事实按 2026 年 9 月初的官方文档和 CLI 0.147 到 0.152 写的。Codex 更新得很快，命令名和界面文字以你手上那版为准。方法论不会过时，按钮名字会。
练习项目。 全文共用一个练习项目，叫读书笔记本。它小到一个下午能做完，又刚好覆盖界面、交互、数据存储和手机适配。需求一句话：
做一个只在本地跑的读书笔记页面。能新增一条笔记（书名加一句摘录或感想），能给笔记打标签，能按关键字搜，能删。刷新页面数据还在。手机宽度下不出现横向滚动条。不接后端，不用登录。
目录名统一叫 reading-notes。第四章把它从空目录做到能验收，第五章给它写项目规则，第六章在它上面调模型，第七章把它的审查流程做成 Skill，第八章的知识库案例是它的自然延伸。
叫法。 同一个东西在不同文档里有不同名字，全文统一用下面这套。
本文用词
指什么
你在别处可能看到
任务
一次独立的对话和它的执行过程
Thread、Chat、会话、线程
项目
桌面 App 左栏里的一个条目，对应一个目录
Project、仓库
工作区
Codex 当前被允许读写的目录边界
Workspace、工作目录
只读 / 工作区可写 / 完全访问
沙箱的三个档位
read-only / workspace-write / danger-full-access
审批策略
什么时候停下来问你
approval policy
项目规则
写在 AGENTS.md 里的长期约束
instructions、rules
审查面板
App 右侧看改动的那块
Diff 面板、review pane
定时任务
App 里按时间触发任务的功能
Automations、Scheduled tasks
桌面 App
ChatGPT 桌面应用里的 Codex
Codex App
Skill
封装好的一套做事方法
技能
MCP
连接外部工具和数据的协议
Model Context Protocol
一、它到底是个什么东西1.1 先把预期掰正大多数人把 Codex 当成"更会写代码的 ChatGPT"。这个理解会让你在前三天里反复撞墙。
问题出在预期上，不在模型上。生成一段代码，和交付一个能用的东西，中间隔着一整段活儿：读懂现有文件，理解约束，改对地方，跑一下看结果，不对再改。聊天框只能帮你干第一步。Codex 值钱的地方恰恰在后面几步。
所以更准的说法是：Codex 是一个能进你项目、能操作你电脑、拿结果说话的执行者。它不光给建议，它动手，而且会把动手的过程摊开给你看。
左边靠人来回搬运，右边它自己在项目里走完一轮
1.2 一次任务里它在干嘛拆开看，一次任务通常走这七步。它不一定每步都告诉你，但每步都在发生。
摸清目标。 确认你到底要什么，拿不准会反问。看环境。 读目录结构、关键文件、项目说明、依赖。拆步骤。 把大活儿切成几个能单独验证的小步。动手改。 建文件、改文件，需要时跑命令。跑验证。 执行测试、构建、类型检查，或者真打开页面看一眼。看差异。 检查有没有误伤别的文件，有没有引入明显的回归。交代结果。 告诉你改了什么、验了什么、还剩什么没覆盖。
一次任务是一个循环，蓝色那几步是证据的来源
第五步和第六步最值得盯。只会生成代码的工具很容易给你一种"已经做完了"的错觉，而且它说"已完成"的时候，语气跟真做完了一模一样。这是最麻烦的地方。合格的 Agent 得拿证据说话：跑过什么命令，输出是什么，diff 里有哪些文件。
有个习惯值得第一天就养成：每次下任务，结尾都加一句收尾要求。
收尾时请列出四样东西：动了哪些文件、跑了哪些检查、检查结果如何、哪些部分没能验证。只回一句"完成了"不算交付。
这句话看着挺朴素，但它能明显减少"代码写完了但根本跑不起来"的次数。后面还会反复用到。
1.3 五个入口，各站在什么位置Codex 不是一个软件，是五个入口。每个入口站在你工作流的不同位置上，谁也替代不了谁。
入口
在哪儿用
更适合什么
桌面 App
ChatGPT 桌面应用里的 Codex
第一次接触；多任务并行；查看改动；操作本机文件和应用；定时任务
CLI
终端
单个任务；脚本化和批处理；想看清每一步在干什么
IDE 扩展
VS Code、Cursor、Windsurf 等编辑器
已经在编辑器里，围绕当前文件做小改
Cloud
浏览器里的远程环境
任务说清楚就能扔出去后台跑，不占本机
浏览器扩展
已登录的 Chrome、Edge 等
操作需要登录态的网页，比如邮箱、后台系统
挨个说。
桌面 App 是个工作台，现在是 ChatGPT 桌面应用的一部分，顶部切到 Codex 就是。左边项目和任务，中间对话和执行，右边文件改动。它不光处理代码，文档、表格、网页、本地文件都能当任务对象。第一次接触从这儿进最省事，因为它不要求你先会用终端。
CLI 是把 Codex 装进终端。在项目目录里敲一个命令就开始，改动直接落在当前目录。它把读文件、申请权限、跑命令、验证结果的每一步都摊在你眼前，适合想看清它到底在干嘛的人，也适合脚本化和 CI。
IDE 扩展 装在编辑器里，能直接用上你打开的文件、选中的代码和编辑器里的报错。解释一段代码、修当前文件的一个问题、做一次局部重构，这个入口最顺手。
Cloud 把任务扔到远程。它克隆你的仓库，在隔离容器里跑，跑完给你一份改动，你决定合不合。价值在于任务能脱离你的电脑持续跑，还能同时跑好几个。界面并不会因此变简单。代价是远程环境和本地不完全一样，依赖、密钥、网络访问得单独配。
浏览器扩展 让 Codex 操作你已经登录的浏览器，Chrome、Edge 都支持，由桌面 App 驱动。它和内置浏览器是两回事：内置浏览器负责打开本地页面检查界面，浏览器扩展负责在真实登录态下操作网页。
同一套能力，五个入口。蓝线那个是第一次建议进的
还有个经常被误解的地方：ChatGPT 手机 App 里也能看到 Codex。它不是独立的手机版 Codex，也不是把手机变成远程鼠标键盘。它更像个遥控器。你的桌面 App 或远程环境里正跑着任务，手机负责看进度、回问题、批操作。下一章讲怎么接上。
1.4 第一个入口怎么选一条原则：选离你现在干活的位置最近的那个。
第一次学，或者你不写代码：从 App 进。你平时就活在终端里：从 CLI 进。你正在编辑器里改代码，只想顺手用一下：IDE 扩展。你手上一堆边界清楚、能异步等结果的活儿：再考虑 Cloud。手机端和浏览器扩展都不是起点，它们是前四个的延伸。
别一上来把五个入口全配一遍。入口多不等于效率高，反而容易把一下午耗在配置上。本文的做法是：界面和操作以 App 为主讲，方法论对所有入口通用，CLI 的命令集中放在第六章。
1.5 门槛其实不在提示词上很多人以为用好 Codex 的门槛是"会不会写提示词"。提示词只是入口，决定结果的是另外四件事。
给它正确的目录。 目录决定它看得到什么，也决定它默认能改什么。给它刚好够用的权限。 给小了它干不了活，给大了你看不见过程，出错影响范围也收不住。给它够用但不过量的上下文。 太少它猜，太多它晕。给它能执行的验收标准。 没有验收标准，"完成"就只是它的一句话。这四件事任何一件没弄好，模型再强也可能朝着错误方向一路狂奔。后面每一章，讲的都是这四件事里的某一件。
二、先装上这一章只解决"用上"的问题：装哪个、怎么装、怎么登录、怎么确认它真能跑。顺带说清 Windows 上最容易踩的那个坑，以及手机怎么跟进任务。
2.1 装哪个上一章说过，第一次接触从 App 进最省事，习惯终端的人从 CLI 进。两个是分开装的，都装也不冲突。用 App 的人后面照样会用到 CLI 的命令，所以两个都讲，你可以只装一个。
账号方面，Codex 要一个 ChatGPT 账号。免费账号也能用，额度看方案。也可以用 API 密钥登录，但那样用不了云端功能，按 API 计费。具体额度看官方定价页，这里不展开。
2.2 装 AppCodex 现在是 ChatGPT 桌面应用的一部分。去官方页面下载 ChatGPT 桌面应用，macOS 和 Windows 都有安装包，Windows 也能从 Microsoft Store 装，Linux 有预览版。装完打开，顶部切到 Codex，用 ChatGPT 账号登录，然后添加一个项目目录，就能开始了。
先选择项目目录，再输入任务（根据官方界面截图制作的操作示意）
如果你已经装了 CLI，也可以在终端里直接拉起 App，没装的话它会帮你走安装流程：
codex app
2.3 装 CLI官方给了几种方式，挑一种就行。
macOS 和 Linux 上最省事的是安装脚本：
curl -fsSL https://chatgpt.com/codex/install.sh | sh
已经有 Node.js 的，可以走 npm：
npm install -g @openai/codex
习惯 Homebrew 的 macOS 用户注意，它是 cask，不是普通 formula：
brew install --cask codex
Windows 用 PowerShell：
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
千万别几种方式一起上。 系统里躺着三个 codex，你更新了其中一个，终端调用的还是另一个，然后你会花半小时怀疑人生。这种问题最难查，因为哪儿都不报错，它就是行为不对。装完先确认当前调用的是哪个：
which codex
codex --version
以后更新用这条，它会按你当初的安装方式处理：
codex update
2.4 登录终端里执行：
codex login
它会拉起浏览器让你授权。第一次直接跑 codex 也会触发同样的流程。
两种特殊情况：
这台机器没浏览器，比如远程服务器。用设备码：codex login --device-auth，它给你一个地址和一段代码，你在任何有浏览器的设备上完成授权。这个方式得先在 ChatGPT 的安全设置里开启。想用 API 密钥而不是 ChatGPT 账号：printenv OPENAI_API_KEY | codex login --with-api-key。密钥从标准输入读，不会留在命令历史里。随时可以看登录状态：
codex login status
退出用 codex logout。
2.5 跑通第一条命令装完登完，别在随便什么目录直接开搞。先进一个专门的目录。练习项目要用 reading-notes，现在就可以建：
mkdir reading-notes
cd reading-notes
codex
启动后界面上会显示当前模型、工作目录和沙箱模式。先看一眼目录是不是你刚建的那个。然后发第一条指令，只读，什么都别改：
列出当前目录里的文件，并告诉我你现在的工作目录和沙箱模式是什么。不要修改任何文件。
它应该回答目录是空的，并报出工作目录的完整路径。这就算跑通了。
第一条只读指令：确认工作目录（教学对话示例，个人路径已遮挡）
会话里输入 /status 随时能看到这些信息。要是启动就报错，或者登录状态不对，先跑自检：
codex doctor
它会把安装、配置、登录、运行环境挨个查一遍，哪儿不对就告诉你。
2.6 Windows：把所有东西放在同一个世界里Windows 是完整支持的。有 PowerShell 安装脚本，有原生沙箱，建议 Windows 11。桌面 App 也有 Windows 版，还能选让 Agent 跑在原生 Windows 还是 WSL 里。WSL2 是备选，不是官方推荐路线。你的项目本来就跑在 Linux 环境，再考虑在 WSL 里装 CLI。
这里只有一条原则：Codex、Git、Node 或 Python、项目文件，必须在同一个能互相访问的环境里。
最经典的 Windows 坑长这样：项目放在 Windows 的某个盘，依赖装在 WSL 里，终端又是从第三个地方启的。表现出来就是命令找不到、权限异常、路径对不上。Codex 一点毛病没有，是这几样东西分散在两个世界里，互相看不见。
二选一，别混：
主要在 Linux 环境开发：CLI 装 WSL 里，项目也放 WSL 的文件系统里，终端从 WSL 启。主要在 Windows 原生开发：CLI、Git、运行时、项目全在 Windows 侧。2.7 手机上跟进任务ChatGPT 手机 App 里能看到 Codex。先说清楚它是什么、不是什么。
它不是独立的手机版 Codex，也不是把手机变成远程桌面的鼠标键盘。准确说：你的桌面 App、远程开发机或者云端环境里正跑着 Codex，手机负责连上去，让你离开电脑之后还能看进度、回问题、批操作、改方向。
连本地电脑的功能叫 Codex Remote，设置从桌面 App 开始：在桌面 App 里开启远程连接，用手机上的 ChatGPT App 扫码配对。配对之后手机上能干的事不少，发起新任务、选分支或 Worktree、中途插话、批准命令、看改动和文件、在具体某一行上留评论、管长期目标，还能用语音。云端任务不用配对，手机上直接能看。
典型玩法是把一台常开的机器当工作台，比如家里那台吃灰的 Mac mini。任务在它上面跑，你在外面用手机看结果、批操作、给下一步指令。
手机是遥控器，任务还是在电脑或云端跑
2.8 装不上、登不了，看这几条codex 命令找不到。 看安装方式对应的目录在不在 PATH 里。npm 全局装的，看 npm prefix -g 输出那个路径。更新了但版本还是旧的。 十有八九装了不止一份。which codex 看当前调的是哪个，多余的卸掉。登录时浏览器回调打不开。 公司网络和代理环境的常客。改用 codex login --device-auth。启动后目录不对。 退出，cd 到对的目录再启。别在错的目录里将就。说不清哪儿出了问题。 先跑 codex doctor，把输出贴给 Codex 或者拿去搜。三、认一下驾驶舱装好之后第一次打开 App，卡住你的往往不是"该怎么输入"，而是眼前这一堆区域各管什么：项目和任务有啥区别，Local、Worktree、Cloud 该选哪个，权限给到哪一档，审批弹窗跳出来该看什么。这一章把驾驶舱认一遍。
3.1 三块区域，各管一件事桌面 App 的主体分三块：左边管项目和任务，中间是对话和执行，右边是文件改动。别的面板都围着这三块转，主逻辑不会变。
左：项目和任务；中：对话和执行；右：文件与改动（官方界面截图整理）
3.1.1 左栏：项目和任务项目对应一个目录。你把一个网站仓库、一个文章目录、一个工具工程加进来，等于告诉 Codex：这批文件属于同一摊活儿。项目决定它默认从哪儿读材料，也决定沙箱默认允许它往哪儿写。
任务是项目下的一次独立对话。一个任务最好只负责一个明确结果，比如"检查这个页面的结构""修复标签丢失的问题""整理昨天的提交记录"。项目可以一直留着，任务应该有个结束点。
左栏常用的动作：
添加或切换项目在当前项目下新建任务打开以前的任务接着干看哪些任务在跑、哪些在等你批、哪些结束了把某个任务弹成独立窗口，跟浏览器或编辑器并排看什么时候该新建任务、什么时候留在原任务，第五章有专门的讨论。这里先记一条：旧任务已经混进一堆无关内容、新需求又完全不搭，就新建；只是接着改同一个东西，留在原地。
3.1.2 中间：对话区和输入框中间显示 Codex 的回复、计划、执行的命令、工具调用、审批请求和最终总结。底部那个输入框不只是聊天框，它是任务的控制台。
输入框周围通常有这些控制：
发送 / 停止：提交要求，或者叫停正在跑的任务模型：选模型和推理强度权限：决定这个任务能干到哪一步附件：塞文件或图片进去当上下文语音输入：听写模式，说的话转成文字工作模式：Local、Worktree、Cloud 三选一，决定任务在哪儿跑输入 @ 能搜索并引用工作区里的文件，输入 / 能看当前环境支持哪些命令。
它跑起来之后你不用干等。发现方向不对，直接补一句"只检查，不要修改""不要装依赖""先停在计划阶段"。越早喊停，浪费越少。
3.1.3 右侧：改动面板右侧这块官方叫审查面板，用来看 Codex 到底改了什么。新增一般是绿的，删除是红的。可以按文件看，也可以只看某一轮，或者整个分支的变化。
它不只是给你"看一眼"用的，实际能当审查台使：
看所有未提交的修改在具体某一行旁边留评论按文件或按改动块暂存、撤销直接在 App 里提交、推送，或者开 PR有个很好用的招：某一行有问题，就在那一行留评论，比在输入框里描述"上面那个函数里的第二个判断"准确一百倍。评论留完再发一句：
处理我刚才留的行内评论，其他部分不要扩大修改。
面板快捷键记这几个就够：⌘B 收展左栏，⌘⌥B 开审查面板，⌘J 开底部面板，⌃` 开终端，⌘⇧B 开浏览器面板，⌘K 呼出命令菜单。Windows 上把 ⌘ 换成 Ctrl。
在具体代码行上留下反馈（根据官方审查界面制作的操作示意）
3.2 工作区：你打开什么，它就看得见什么工作区就是 Codex 当前干活的目录。"找不到文件""改到别处去了""读了一堆不相干的材料"，这三类问题大部分都是目录选错了。
判断标准只有一条：干完这件事需要的文件，能不能集中放进一个最小的目录里。能，就只打开这个目录。别为了省一次切换，把整个桌面、整个用户目录或者一堆无关项目一起端给它。
几种常见情况：
只改一个独立项目：打开项目根目录一个仓库里有几个互不相干的应用：分别加成几个项目前后端分在相邻两个目录：以主要那个启动，需要时给另一个补可写权限只想分析不想改：照样打开正确目录，但权限设成只读任务要在远端跑：选 Cloud，别放大本地权限CLI 里启动时就能指定工作目录和额外的可写目录：
codex -C ~/projects/frontend --add-dir ../backend
这比直接给整台电脑写权限清楚多了。边界越小，出事时的影响范围越小。
3.3 Local、Worktree、Cloud 怎么选新建任务时最重要的选择之一，是它在哪儿干活。
Local / Worktree / Cloud
Local，直接改当前目录。 改动立刻落到本地文件上。日常大部分活儿都适合：改文档、修一个问题、跑测试、整理目录、看项目结构。好处是直接，坏处也直接：你和它同时改同一批文件，会打架。单个任务从 Local 开始最省事。
Worktree，给任务一份隔离副本。 基于 Git 的 worktree，给这个任务单开一份工作目录。它在副本里折腾，你手上这份不受影响。两种情况用得上：几个任务同时改一个仓库；或者想让它试一个改动，又不想马上碰当前分支。做完可以在副本里建分支、提交、开 PR，也可以把结果交接回 Local。不是每个任务都要开 Worktree，就改一个小文件、就一个任务在跑，Local 更省事。
Cloud，扔到云端。 它在远端隔离环境里克隆仓库然后开干。适合边界清楚、能异步等的活儿：代码审查、修一个描述明确的 Issue、批量重构、跑一轮测试。好处是你不用守着电脑，跑完看改动，再决定合不合。需要频繁讨论、依赖本机文件或本地应用的活儿，还是 Local 或 Worktree 顺手。
一张表帮你选：
你现在要干的
选
一个任务，直接改当前目录
Local
同一个仓库并行两个以上任务
Worktree
试一个改动，不想碰当前分支
Worktree
任务说清楚了，扔出去后台跑
Cloud
需要本机的应用、文件，或者要频繁讨论
Local 或 Worktree
3.4 权限：刚好够用就行，给大了反而添乱第一次看到权限提示，本能反应是全部允许，省得反复确认。这个本能得压一压。
Codex 能执行命令、改文件、上网。权限给大了不只是安全问题，你还会失去观察它干活的机会，出了事也不知道波及到哪儿。把整个用户目录端给它，跟新人第一天入职就发生产库密码差不多。
先把两个概念分开：
沙箱边界：决定命令能碰到哪儿。硬约束。审批策略：决定什么时候停下来问你。软约束。一个任务哪怕在工作区沙箱里，也可能因为要联网、要写工作区外的目录、要执行高风险操作而来问你。两者叠起来，才是它的实际权限。
沙箱三档：
档位
能干什么
适合什么
只读
读和分析，一个字都不写
摸陌生项目、审代码、找问题、出方案
工作区可写
在当前工作区内写，越界受限
日常开发的绝大多数活儿，新手默认选这个
完全访问
拆掉本地沙箱
只在明确需要、完全清楚后果、环境能恢复时才考虑
CLI 里对应 --sandbox 的三个值：read-only、workspace-write、danger-full-access。审批策略用 --ask-for-approval，可选 untrusted（只有已知安全的命令免审批）、on-request（模型自己决定什么时候问你）、never（从不问，失败直接返回给模型）。
默认组合叫 Auto，等于工作区可写加按需审批。不是 Git 仓库的目录，默认直接给只读。工作区可写模式下网络默认关着；.git、.codex、.agents 这几个目录哪怕在可写范围内也保持只读。CLI 里输入 /permissions 能在 Auto、Read Only 这些预设之间切。
App 的权限菜单是另一套说法，三个预设：
请求批准：默认档。越出沙箱的操作都停下来问你。替我审批：越界操作先交给一个审查 Agent 判断，它拿不准的才问你。CLI 里对应 --approve-for-me。完全访问：不问，也不拦。想要只读这类更细的档，在设置的权限项里开启额外模式。
权限先看说明，再选档位；名称以当前版本为准（官方界面截图整理）
审批请求跳出来的时候，先看四件事：
它准备执行什么命令在哪个目录执行要不要联网这一步对当前目标为什么是必要的装依赖、传文件、删数据、改账号设置、对外发布、碰凭据，这几类都值得停一下。
给新手的规则是：读代码用只读；正常改项目用工作区可写；装依赖和联网按次确认；删文件、重置历史、强制推送、动生产环境，必须单独看。完全访问不该为了少点两次确认就打开，更不适合挂着无人值守的定时任务。
还有一条和权限一样要紧：别把装着私钥、钱包助记词、生产凭证或者一堆个人文件的目录直接当工作区。权限的意义是把错误的影响半径控制住。
3.5 几个容易被忽略的内置工具集成终端。 每个任务都有自己的终端，目录跟着任务走：Local 任务开在本地项目，Worktree 任务开在对应的副本目录。你可以在里面跑测试、起开发服务、看 git status。更省事的是，Codex 能读终端当前的输出，看到报错直接说"检查终端里的报错"，不用整段复制粘贴。
内置浏览器。 用来打开本地页面检查界面。它有个标注模式，你可以在页面元素上直接留带位置的评论，比如"这里字号小一点""这个按钮跟上面的输入框对齐"。这种反馈比纯文字描述准多了。它不会复用你已经登录的浏览器会话，要操作邮箱、后台系统这类登录态网页，用浏览器扩展。
Computer Use。 让 Codex 操作桌面应用：点击、输入、拖拽、读屏幕、按快捷键。适合那些没有 API 的老工具、批量录入、文件整理和跨应用流程。但它能操作不代表什么都该自动化，涉及付款、发布、删除、账号权限和对外发送的动作，最后那一下留给人。
图片。 图片可以直接拖进输入框当上下文，界面错位这类问题，一张截图顶三段描述。Codex 也能生成图片，做界面素材、概念图、文档配图都行，属于可选能力，不是每个任务都用得上。
四、跑通第一个真任务这一章是全文的主线。用读书笔记本这个练习项目，把准备、只读扫描、验收清单、任务写法、执行、修问题、审查、收尾整条路走一遍。跟完你手上会有一个能用的页面，更值钱的是会有一套以后干什么活儿都能套用的流程。
4.1 开工前只要三样东西很多教程一上来就讲模型、MCP、Skill 和一堆配置。等你照着配完，第一个任务还没跑起来，人已经累了。第一次真正需要的只有三样。
一，一个独立的项目目录。 别让 Codex 第一次就面对你的桌面、下载文件夹或者整个用户目录。目录决定它看得见什么，也决定它默认能改什么。给练习专门开一个：
mkdir reading-notes
cd reading-notes
二，一个 Git 检查点。 Git 不是程序员专属，把它当成项目的撤销历史就行。让 Codex 动手之前先提交一次，做完看差异，哪怕结果不满意，你也能清楚知道发生了什么，随时退回去。
git init
echo "# 读书笔记本" > README.md
git add .
git commit -m "before codex"
不习惯命令行就用图形化 Git 工具，一样。重要的是给每次自动修改留一条能退回的边界，命令记不住无所谓。
三，一个一小时内能验收的小目标。 第一次别上来就做"完整的知识管理系统"。目标越大，出了问题你越分不清是需求的锅、模型的锅、环境的锅还是代码的锅。这次的目标是：
做一个只在本地跑的读书笔记页面。能新增一条笔记（书名加一句摘录或感想），能打标签，能按关键字搜，能删。刷新页面数据还在。手机宽度下不出现横向滚动条。不接后端，不用登录。
够小，又刚好覆盖界面、交互、数据存储和手机适配，练完整交付链路正合适。
4.2 启动，先看目录App 里：添加项目，选中 reading-notes 目录，在这个项目下新建一个任务。启动后先瞄一眼项目名和目录路径，别选错。
CLI 里：
cd reading-notes
codex
启动界面会显示当前模型、工作目录和沙箱状态。目录不对就立刻退出，到对的目录重开。让 Agent 在错误的目录里干活，比提示词写得烂危险多了。
开工前核对工作目录与沙箱（CLI 状态示意，字段以本机 /status 为准）
4.3 第一步别写代码，先让它说说看见了什么信任不是从"它生成了页面"开始建立的，而是从一次只读检查开始的。CLI 里用 codex --sandbox read-only 启动；App 里选最保守的权限预设，要是没有只读档，就把"不要创建或修改任何文件"写进提示词当硬约束。然后输入：
先不要创建或修改任何文件。请检查当前目录，回答四个问题：
1. 现在有哪些文件；
2. 这个项目处在什么状态；
3. 要做"本地读书笔记页面"，你建议的最小技术方案是什么；
4. 有哪些选择需要我先拍板。
这一步干三件事：确认它真的站在正确的目录里；确认它听懂了目标；让你在写任何代码之前先看见技术选型。
理想的回答会把方案压得足够小。对这个练习，原生 HTML、CSS、JavaScript 加上浏览器自带的 localStorage 就够了，依赖少，启动简单，每个文件你都看得懂。要是它上来就给你建议数据库、账号系统、Docker 外加一个前端框架，那就是典型的过度设计，直接让它收回去。
4.4 把"我想要"翻译成"什么叫做完了"需求描述和验收标准是两回事。前者是你脑子里的画面，后者是能逐条打勾的清单。让它帮你翻译：
把上面的需求改写成一份验收清单。每一项都必须能通过页面操作或者命令来检查，不要写"体验流畅""代码整洁"这种没法判断的话。只输出清单，先不要开始做。
你应该拿到类似这样的东西：
页面首次打开无报错输入书名和内容后能新增一条笔记书名或内容为空、或只有空格时不能提交可以给笔记添加至少一个标签，标签显示在笔记上搜索框输入关键字后，只显示书名、内容或标签命中的笔记可以删除一条笔记刷新页面后笔记、标签、完成状态都还在浏览器宽度缩到 375px 时没有横向滚动控制台没有未处理的错误到这儿，需求才从"我想做个东西"变成了"什么叫做完了"。这份清单后面还要反复用：做的时候对着它，验收对着它，审查还是对着它。
想法 → 验收清单 → 四字段任务
4.5 任务怎么写：把四个字段补齐新手写任务的问题通常不是不够长，而是缺字段。一份能被稳定执行的任务描述，有四个部分。
目标：要改变什么。写"新增笔记时支持回车提交，并拦截纯空格输入"，别写"优化一下"。上下文：先看哪儿。可以是文件、目录、截图、报错、参考页面。不是越多越好，关键是让它先读真正相关的那几份。约束：不能碰什么。不引入框架、不改公共接口、不读 .env、保持现有视觉风格、只改当前模块。完成标准：怎么证明做完了。测试通过、构建成功、指定操作能复现、没有新增控制台报错。四个字段拼起来，这次的任务可以这么写：
目标：在当前空目录里做一个本地读书笔记页面。支持新增笔记（书名 + 内容）、给笔记打标签、按关键字搜索、删除笔记，数据用 localStorage 持久化。
上下文：先读 README.md。项目目前没有代码。用原生 HTML、CSS、JavaScript，保证我能直接看懂每个文件。
约束：不接后端，不做登录，不引入任何框架和远程 CDN。界面白底，强调色用蓝色。375px 宽度下不能出现横向滚动。
完成标准：创建必要文件后在本地打开验证；逐项检查新增、空值拦截、标签、搜索、删除、刷新保留和移动端布局；最后列出改了哪些文件、做了哪些验证、还有哪些没覆盖。开始前先给一个不超过六步的计划，确认没超出需求再动手。
这份任务一点也不花哨，但它比"你是一名世界级全栈工程师，请深度思考后给我最完美的方案"有用得多。角色设定替代不了项目事实，感叹号也替代不了验收标准。
4.6 要不要先看计划上面那份任务最后一句要求它先给计划。计划不是每次都要，值不值得看，取决于任务。
值得：任务跨好几个文件；改动不好回退；得先查清原因再动手；你自己还在几种做法之间摇摆。
不值得：改一个标题、查一个报错在哪、执行一条确定的命令。这种活儿硬要它列五步计划，纯属走过场。
CLI 里输入 /plan 进规划模式，或者把要求写在后面：
/plan 先检查当前目录和相关文件，只给出修改计划，不要写文件
App 里也有 /plan，或者直接用大白话说：
先不要动手。告诉我你理解的目标、准备看的文件、准备改的地方，以及最后怎么证明做完了。我确认后你再开始。
一份有用的计划至少要回答四个问题：真正要解决什么，准备看哪些材料，准备改哪些地方，最后怎么证明完成。要是回来的是"分析需求、开始实现、测试、总结"这种模板，信息量约等于零，让它重写。
还有一条比计划本身更基础的原则：接到任务先找最短可靠路径。能直接干完就不搭流程，能复用现成的就不从头做，能局部改就不推倒重来，能一条命令解决就不写脚本，能一个脚本解决就不建项目。计划是用来选方法的，不是用来给简单问题加仪式感的。
4.7 第一轮：先跑通，别管好看计划确认了就让它开干。第一轮别同时追功能和视觉，先要一个最小可用的版本：
按已确认的验收清单实现第一版。先保证能用，不做动画和复杂组件。每完成一个阶段就运行能执行的检查；如果环境缺工具，先说最小的解决办法，不要擅自加依赖。做完停下来，等我验收。
它应该建出 index.html、styles.css、app.js 这类文件，然后用适合当前环境的方式打开或检查页面。这个过程要看的是它实际跑了哪些命令，最终那段回复反而次要。执行记录能告诉你它有没有真验证过，一句"已完成"不能。
第一版出来，自己动手验一轮，按清单来：
新增三条笔记，内容各不相同。输入几个空格试着提交，看拦不拦。给其中一条打两个标签。搜一个只在标签里出现的词。删掉一条。刷新页面，看剩下两条和标签还在不在。把浏览器宽度拖到手机尺寸，看有没有横向滚动。打开控制台，看有没有红的。
布局验收参考：桌面与 375px 预览（本机配图专用练习页面截图整理）
4.8 发现问题怎么说验收时多半会揪出毛病。这时候最忌讳把所有现象揉成一句"还是不好用"。给它一个最小复现：
我发现一个可以稳定复现的问题：给笔记"《小王子》"加上标签"童话"，刷新页面后笔记还在，标签没了。
请先定位根因，说明数据在哪一步没有被保存，再做最小修改，不要重构无关代码。修好后按同样的步骤重新验证，并补一个能防止这类问题再次出现的检查。
这段话把现象、复现步骤、预期行为、修改边界和验证方式全说清了。它比"标签有 bug，修一下"靠谱得多，因为它把"猜"的空间压到了最小。
4.9 第二轮：再管好看功能全过了，再单独收拾视觉。把它和功能分开是有原因的：一次只改一类东西，出了问题好定位。
在不改变现有功能和数据结构的前提下调整界面：白底、深灰正文、蓝色强调色；内容区最大宽度 720px；输入区和笔记卡片在 375px 宽度下不溢出；标签要一眼能认出来但不抢正文。只改样式和必要的语义标签。做完对比修改前后，并把全部功能再验一遍。
4.10 让另一双眼睛再看一遍两轮做完，让 Codex 换个身份，从审查者的角度看一遍未提交的修改。CLI 里输入 /review，也可以在终端里非交互地跑：
codex review --uncommitted
审查的价值在于换视角，不是让它把刚才的实现再夸一遍。把审查重点写清楚：
从审查者角度检查未提交的修改，重点看：localStorage 读写是否可靠、用户输入有没有做处理、有没有点了没反应的交互、移动端是否溢出、有没有和本次任务无关的改动。
审查回来的意见别机械照单全修。先判断两件事：这问题是不是真的存在，属不属于本次任务的范围。不属于的记下来，留给下一个任务。
4.11 收尾：先看 diff，再决定留不留最后回到 Git，看一眼这回到底改了什么：
git status
git diff --stat
App 用户直接看右侧的改动面板，按文件过一遍。确认没有误伤、没有多余改动，再提交：
git add .
git commit -m "reading-notes v1"
这条链路的关键，是把每一次失败变成能定位、能修、能回归验证的问题。指望一次写对反而最不靠谱。你在练的是交付能力，不是多抽几次卡的运气。
五、上下文：给少了它猜，给多了它晕上一章跑通了一个任务。任务一多，新麻烦就来了：同样的话你得反复说；会话越拖越长，它开始忘掉前面定下的事，或者被早就毙掉的方案带跑偏。这一章讲上下文怎么分层放，项目规则怎么写进 AGENTS.md，会话什么时候该压缩、什么时候该另起炉灶。
5.1 它每一轮看到的是什么Codex 每轮做判断，眼前的材料大概这几样：你这轮说的话、这个会话之前的对话历史、它读过的文件和命令输出、项目里的规则文件，还有接进来的工具返回的东西。
这些加起来叫上下文。上下文有上限，而且不是越满越好。会话越长，那些旧讨论、被推翻的方案、重复的报错全都还堆在里面，它做判断时会被这些东西干扰。CLI 里输入 /status 就能看到当前用了多少，任务拖长了值得偶尔瞄一眼。
新手常犯两个极端：只丢一句需求，指望它自己把什么都找齐；或者一口气塞进几十份文档、全部聊天记录和整个需求库。前者它靠猜，后者它晕。
5.2 分四层放解决办法是分层。不同性质的信息放不同地方，各有各的生命周期。
四层上下文：当前任务、项目规则、可复用流程、外部动态信息
第一层，当前任务。 这次要干什么，问题怎么复现，做到什么程度算完。短而明确就行，上一章的四字段写法就是给这层准备的。
第二层，项目规则。 目录结构、运行命令、工程约束、验证要求。这些每次任务都一样，不该每次重说，写进 AGENTS.md。这一章的重点。
第三层，可复用流程。 同一套步骤会反复执行，比如固定的审查清单、发布说明怎么生成、日志怎么排查，就封装成 Skill。第七章讲。
第四层，外部动态信息。 数据在 GitHub、Sentry、Figma、Notion、数据库这些系统里，而且一直在变，这时候才通过 MCP 或插件接进来。也在第七章。
判断一条信息归哪层，问一句话就够：它是这次才有的，还是每次都一样，还是一套会反复跑的步骤，还是在项目外面且一直在变的数据。
5.3 AGENTS.md：把重复说的话变成规则信号很明显。当你第三次提醒它"用 pnpm 别用 npm""改完记得跑测试""别碰 dist 目录"的时候，就该写规则了。
AGENTS.md 是写给 Agent 看的项目说明书。Codex 进项目时会自动读，你不用每次贴。可以在项目根目录用 /init 生成一份草稿，然后把草稿删到只剩真正有用的部分。
给读书笔记本写一份，大概长这样：
# AGENTS.md
## 这个项目是什么
- 本地读书笔记页面，零依赖，原生 HTML、CSS、JavaScript 加 localStorage。
- 目标是简单、可读，不做抽象，不做工程化。
## 改动规则
- 不新增框架、构建工具和远程依赖。
- 只改与当前任务相关的文件。
- 不读取、不输出任何密钥、环境变量和个人文件。
## 验证规则
- 改过 JavaScript 之后，确认浏览器控制台没有新增错误。
- 每次交付都要过一遍：新增、标签、搜索、删除、刷新保留。
- 收尾说明必须包含三部分：修改了哪些文件、验证结果、剩余风险。
## 怎么运行
- 直接用浏览器打开 index.html，没有构建步骤。
/init 只给草稿，删到只剩会反复用到的规则
写 AGENTS.md 最容易犯两个错。
一是写成几千字的愿望清单，通篇"高质量""最佳实践""深度思考"这类没法执行的词。规则太长会吃上下文，条目之间还可能打架。规则要短、要具体、要能被检查。
二是把一次性需求写进去，比如"今天把按钮改成绿色"。这是当前任务，属于第一层，不是规则。长期规则的标准是：稳定、可执行、能反复用。
规则应该从真实问题里长出来，别一上来就写成公司宪法。同一个错误犯第二次，再补一条对应的规则。短而准，比长而全更容易被真正执行。顺便说一句，所有规则文件加起来有大小上限，默认 32 KB，这是规则要短的另一个理由。
5.4 规则也可以分层项目一大，规则就不止一份。Codex 按层级读规则文件，越靠近当前文件的优先级越高。
全局规则：放在 ~/.codex/AGENTS.md，存你的个人习惯。比如你偏好的语言、提交信息格式、永远别碰的目录。桌面 App 设置里的"自定义指令"写的就是这一份。仓库根目录：团队共同规范。构建命令、目录约定、代码风格、验收方式。子目录：某个服务或模块的局部规则。前端目录说明用什么组件库，后端目录说明测试怎么跑。你不用第一天就把这套体系搭全。一个项目一份根目录规则能用很久。等哪个子目录反复出只属于它的问题，再在那儿补一份。
顺带说下记忆功能。Codex 有个 Memories，默认关着，在设置的个性化里能打开。开了之后它会从空闲会话里提炼你反复表达过的偏好和纠正，存在本机，会话里用 /memories 能临时开关。它和 AGENTS.md 的分工是：记忆是慢慢攒出来的隐式偏好，你没法一条条审；AGENTS.md 是明确可见、能进版本库、团队都看得到的规则。重要的规则一律写进 AGENTS.md，别指望记忆替你记。
5.5 一个会话，一个目标会话是上下文的容器。管会话第一条原则：一个会话只围着一个连贯目标转。别上午在里面做前端，下午分析数据，晚上又回来修同一个 bug。三摊事的上下文互相污染，最后哪摊都做不好。
会话变长了怎么办。 别直接压缩，先让它整理状态：
请先整理当前任务的上下文，只保留这几样：目标、核心约束、已经确认的决策、已经修改的文件、验证结果、还没解决的问题、下一步计划。被推翻的方案和重复的讨论都删掉。
它输出整理结果之后，再用 /compact 压缩。压缩会把早期对话折叠成摘要，保留目标、约束、决策和进度，把旧信息的干扰降下来。先整理再压缩，摘要质量会好不少。
任务分叉了怎么办。 一个会话里冒出两个互不相干的问题，比如一边在修标签持久化，一边想重做搜索逻辑，拆开比堆在一起干净。可以直接新建任务，也可以用 /fork 从当前位置分叉，新会话带着到此为止的上下文，之后各走各的。
什么时候留在原地。 只是接着改同一个东西，比如第一版做完再调样式，那就留着，不用为了形式上的整洁反复开新对话。判断标准就一条：新需求跟旧上下文有没有关系。有关系就留，八竿子打不着就另起。
跑着的时候随时能喊停。 不用等它彻底跑完才说话。发现方向不对，直接补一句"只检查，不要修改""不要装依赖""先停在计划阶段"。越早喊，浪费越少。
5.6 给它看什么：文件、截图、报错上下文第一层是你这轮给的材料。给材料有几个顺手的办法。
点名文件。 输入框里用 @ 能搜索并引用工作区里的文件。与其说"看看那个处理保存的函数"，不如直接 @app.js 然后说清看哪一段。给截图。 界面错位、样式不对，一张截图比三段文字准。App 里直接拖进输入框；CLI 启动时用 -i 附上图片。给报错。 完整报错，包括堆栈和触发操作，比"报错了"有用一百倍。App 里 Codex 能直接读集成终端的输出，你说一句"检查终端里的报错"就行，不用手动复制。材料的原则跟整体一样：让它先读最相关的那几份，多不等于好。任务里写清楚"先读 A，再看 B，其他先不用管"，比一口气全塞进去管用。
六、模型、推理强度和那些命令模型选择是最容易被营销话术带跑偏的地方。这一章讲三件事：模型和推理强度怎么按任务分档，配置该放在哪一级，以及那些真正天天用的命令和快捷键。
6.1 模型：先认几个名字模型名字变得飞快，任何教程里写的名字都会过时。最靠谱的做法是在会话里输入 /model，看你的账号现在能用哪些。
写这篇的时候，Codex 推荐的是 GPT-5.6 这一代的三个型号：Sol 是旗舰，默认组合就是 Sol 加中等推理；Terra 和 Luna 是同代的另外两个，定位偏轻快，具体差别看 /model 里的说明。另外还有一个 Pro 方案专属的研究预览型号。云端任务的模型是固定的，不用你选。
选模型看三条：
任务复不复杂。错一次的代价高不高。你能不能很快验证结果。改一个按钮文字，没必要动用最重的配置。生产数据迁移哪怕只有几行代码，也值得更谨慎的推理和审查。
6.2 推理强度：五档，按任务挑推理强度决定它回答前"想"多久。CLI 里的值是 minimal、low、medium、high、xhigh，App 和 IDE 里显示成 Light、Medium、High、Extra High 这类标签，部分模型还有更高的 Max 和 Ultra，Ultra 会调子代理，得在设置里打开。
先选模型，再选推理强度；菜单以当前版本为准（官方界面截图整理）
新手最常见的想法是"永远最强模型加最高推理，结果肯定最好"。实际用下来，小任务明显变慢，回复变长，质量也没见着涨。按任务分档更实在：
任务类型
推理强度
解释一个文件、微调文案、边界清楚的单文件修改
low 或 medium
跨文件的功能、常规重构、补测试
medium 或 high
疑难 bug、架构迁移、长链路任务、安全审查
high 或 xhigh
一句话：边界越清楚，推理越低；越需要跨文件推断和权衡，推理越高。最高档留给那些真的难、也真的值得等的活儿。
还有个跟推理强度不冲突的开关：快速模式。会话里输入 /fast 切换，它不换模型，只是让输出更快。适合边界清楚、你盯着看的短任务。
6.3 在哪儿改：会话、档案、项目、全局同一个设置能在四个地方改，生命周期不一样。学习阶段优先用最临时的那种，等你摸清自己大部分任务属于哪一类，再往稳定的地方写。
会话内。 /model 选模型和推理强度，只管当前会话。App 和 IDE 里也能直接在输入框旁边的选择器里改，或者用 /reasoning 单独调推理。
全局配置。 文件在 ~/.codex/config.toml，存你的个人默认值。给读书笔记本这种练习项目，一份够用的配置大概是：
model = "gpt-5.6-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
[sandbox_workspace_write]
network_access = false
[projects."/Users/you/reading-notes"]
trust_level = "trusted"
最后那段 projects 是信任列表。第一次在某个目录启动 Codex，它会问你信不信任这个目录。信任了才会加载项目级配置，才会用默认的工作区可写模式。不信任的目录一律只读。
项目级配置。 放在仓库里的 .codex/config.toml，存这个仓库特有的设置。比如这个项目就是难，默认推理调到 high；或者这个项目要接某个 MCP。它只对受信任的项目生效，而且不能设置账号、提供商这类敏感项，免得别人的仓库靠一个配置文件偷偷改你的环境。
配置档案。 一份档案就是一个单独的文件 ~/.codex/<名字>.config.toml，启动时用 -p <名字> 叠到全局配置上。适合几套固定组合，比如一份专门用来审查的：
model_reasoning_effort = "high"
sandbox_mode = "read-only"
存成 ~/.codex/review.config.toml，以后审代码就 codex -p review。
临时覆盖。 只想改这一次，用 -c：
codex -c model_reasoning_effort="high"
优先级从高到低：命令行参数和 -c 覆盖 → 项目级配置 → 档案 → 全局配置 → 默认值。近的赢远的。
6.4 终端里的命令CLI 的子命令不少，日常用得上的是这些：
命令
作用
codex
在当前目录启动交互界面
codex "任务"
启动并直接下第一条任务
codex exec "任务"
非交互跑一次，跑完退出，适合脚本和 CI
codex resume --last
接着上次的会话干，不加 --last 会给你一个列表挑
codex fork --last
从最近一次会话分叉
codex review --uncommitted
非交互审查未提交的修改，也能 --base main 或 --commit
codex mcp add / list / remove / login
管 MCP 连接
codex plugin list / add / remove
管插件
codex login / login status / logout
登录相关
codex update
更新
codex doctor
自检安装、配置、登录、运行环境
codex app
打开桌面 App
codex exec 值得单说一句。它默认是只读沙箱，想让它改文件得加 --sandbox workspace-write。它能从标准输入读任务，所以可以把别的命令的输出直接喂进去：
npm test 2>&1 | codex exec "总结失败的测试，提出最小的修复方案，不要改文件"
启动参数前面第三章讲过，最后一章还有完整的表，这儿只重复最常用的：-C 指定目录，--add-dir 加可写目录，-s 沙箱，-a 审批策略，-m 模型，-i 附图，--search 允许联网搜。
6.5 会话里的命令输入 / 就能列出当前版本真正支持的命令，不用背。先把这八个用熟：
命令
什么时候用
/status
看会话、上下文用量和限制。任务越长越该偶尔瞄一眼
/model
给当前任务换模型或推理强度
/permissions
看和切沙箱与审批预设
/plan
进规划模式，只出计划不动手
/review
让它换成审查视角看未提交的改动
/diff
看 Git diff
/init
给当前项目生成 AGENTS.md 草稿
/compact
会话太长时压缩早期上下文
用熟了再加这些：/fork 从当前位置分叉，/new 开新会话，/clear 清屏并开新会话，/mcp 看 MCP 连接状态，/skills 看有哪些 Skill，/plugins 逛插件，/goal 设长期目标，/usage 看额度，/memories 临时开关记忆，/fast 切快速模式。
注意 /reasoning 只在 App 和 IDE 里有，CLI 里推理强度是在 /model 里选的。
6.6 输入框里的小动作CLI 输入框有几组很实用的操作：
输入 @ 搜索并引用工作区文件输入 ! 加一条命令，直接跑 Shell，照样受当前沙箱和审批约束它正跑着的时候按 Enter，给当前这轮补一句它正跑着的时候按 Tab，排队一条后续指令，等这轮完了再执行空输入框连按两下 Esc，回到上一条消息接着编辑，会从那儿分叉出新会话Ctrl+R 搜历史输入，Ctrl+O 复制上一次完整输出Ctrl+L 只清屏，不清上下文；/clear 才是真清空App 里 @ 一样能引用文件，还能引用浏览器、终端这些内置工具，比如"看一下 @Browser 里现在的页面"。
6.7 一个小练习在读书笔记本上做次对比。同一个会话，两个任务，分别用低档和高档推理。
任务 A，用 low：
把搜索改成不区分大小写。只改 app.js 里的搜索逻辑，改完用 Python 和 python 各搜一次验证，结果应该一样。
任务 B，用 high：
给 localStorage 的读写加上异常处理：存储的数据损坏，或者存储空间满了的时候，页面不能白屏，要给出提示，并且尽量保留还能读到的数据。先说明你打算处理哪几种情况，再改。
对比四件事：花了多长时间，回复多长，改动范围多大，有没有多做你没要求的事。做完这一次，你对"什么任务配什么档"就有直觉了，这个直觉比任何表格都管用。
七、Skill、Plugin、MCP 到底谁是谁这五个词经常被混在一起讲，新手最容易在这儿迷路：不知道该装哪个，装完又不知道它什么时候会被用到。这一章把它们各自回答的问题分清楚，给一条"值不值得接"的判断标准，最后给一个靠谱的升级顺序。
7.1 先说一条纪律先别急着装东西。
很多人第一次接触扩展生态，一口气装上七八个 MCP 和一堆插件。结果是工具列表拉得老长，授权请求一个接一个，真干活的时候你不知道该让它调哪个，模型也不知道。
一条简单的纪律：没有手动重复过三次的流程，先别自动化。 第一次做，你还不知道正确做法是什么；第二次做，你开始有感觉；第三次做，你才分得清哪些步骤是固定的、哪些是随机应变的。这时候固化下来的东西才靠谱。
判断一个外部连接值不值得接，问三句话：
这些数据在不在项目外面？这些数据是不是经常变？接上之后，能不能省掉持续的复制粘贴？三个答案都是"否"，普通文件加提示词就够了，什么都不用接。
7.2 五个东西，各回答一个问题能力
它回答的问题
一句话
Skill
这一类事该怎么做
固定下来的做法
Plugin
怎么一次装好一整套相关能力
打包好的套装
MCP
外面的数据和工具怎么接进来
对外的接口
定时任务
什么时候启动、多久跑一次
定时器
/goal
这个长期目标做到哪了、什么时候算完
跨会话的目标记录
Skill 是插进去的卡片，Plugin 是打包的套装，MCP 是对外的接口线，定时任务是闹钟，goal 是那面旗
实际干活不用五个一起上。缺哪层补哪层。
7.3 Skill：把一套做法固定下来一个 Skill 就是一个目录，核心文件叫 SKILL.md。里面写三样：这个 Skill 叫什么，什么情况下该用，具体步骤是什么。目录里还能放脚本、模板和参考资料。
它解决的是"这件事怎么稳定地做"。以前你要反复粘一段很长的提示词，现在写一次，以后点名就行。
Skill 有两种被调用的方式：
显式调用：任务里写 $skill-name，直接点名。隐式调用：Codex 看 Skill 的说明，自己判断当前任务用不用得上。涉及删除、发布、对外发送这类破坏性操作的 Skill，建议把隐式触发关掉，只允许手动点名。做法是在 Skill 目录的 agents/openai.yaml 里把 allow_implicit_invocation 设成 false。你肯定不希望它某天"觉得挺合适"，然后自己跑了一遍发布流程。
给读书笔记本做一个审查 Skill，把第四章的审查重点固定下来：
---
name: notes-review
description: 审查读书笔记本项目的未提交修改。当用户要求审查、review 或验收这个项目的改动时使用。
---
# 审查步骤
1. 运行 `git diff --stat`，列出本次改动涉及的文件。
2. 对照 README.md 里的验收清单，逐条检查是否仍然满足。
3. 重点看四类问题：localStorage 读写是否可靠、用户输入有没有处理、有没有点了没反应的交互、375px 宽度下有没有溢出。
4. 检查有没有和本次任务无关的改动。
# 输出格式
- 问题列表：每条写文件、位置、现象、建议。
- 最后单独一段"本次范围之外的发现"，不混进问题列表。
- 没有证据的项不要标记为通过。
以后在这个项目里说一句 $notes-review，它就按这套步骤走，不用你再把审查重点重打一遍。
建 Skill 可以直接让 Codex 帮你：它自带一个专门用来生成 Skill 的 Skill，任务里点名 $skill-creator，描述你想固化的流程，它会把目录和 SKILL.md 草稿都建好。装别人写好的用 $skill-installer 加名字。
位置有两处。个人通用的放 ~/.agents/skills/，跟着你走；团队共享的放仓库里的 .agents/skills/，跟着项目走，从仓库根目录到当前目录之间每一层都会被扫。会话里输入 /skills 能看到现在加载了哪些。
常见的 Skill 大概这几类：
文档和内容：长文写作规范、去模板腔、PDF 或表格处理开发流程：代码审查、发布、处理 Issue、开 PR视觉和媒体：生成图片、处理视频、做演示文稿团队规则：某个仓库固定的测试、部署、验收方法研究分析：检索资料、整理数据、按固定格式出报告Skill 越多不代表越好。只有一类活儿确实会反复出现，才值得把它固化下来。
7.4 Plugin：一次装一整套Plugin 把一组 Skill、MCP 连接和应用连接器打包在一块儿，装一次所有工作区都能用。App 里有专门的 Plugins 页面，CLI 里输入 /plugins 能浏览和安装，也能在终端里管：
codex plugin list
codex plugin add
codex plugin remove
插件页：一个插件可包含 Skill、MCP 与连接器（官方界面截图整理）
典型插件包括代码托管平台、CI 服务、协作工具、办公套件的连接器，也有一些是把某类工作流打包好的能力集。插件目录和 ChatGPT 共用，装一次两边都能用。IDE 扩展里暂时还没有插件。
装之前先问自己一句：当前的活儿是不是反复需要这个系统的数据或动作。只用一次的网站不值得装插件；原生功能已经能干的，也别为了"生态"再套一层。
7.5 MCP：给它接外部工具MCP 可以理解成一个统一的接口标准。外部服务按这个标准实现一个服务端，Codex 就能把它提供的查询和操作当成自己的工具用。
它解决的是"上下文在哪儿"的问题。读设计稿、看线上错误、查工单、访问内部知识库，这些信息既不在你的仓库里，也不在聊天框里，MCP 负责把它们接进来。
常见的 MCP 大概这几类：
文档查询：查某个库的最新文档设计工具：读设计稿的结构和样式浏览器：控制和检查网页错误监控：读线上报错代码托管：处理 PR 和 IssueCLI 里加一个 MCP：
codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp list
第一条命令的写法是固定的：名字，两个横线，后面跟启动这个服务的命令。要是对方是一个网络地址而不是本地进程，用 --url。加完进会话，输入 /mcp 看每个连接的状态，确认它是真连上了。需要登录的服务用 codex mcp login
App 里在设置中有对应的 MCP 管理界面，效果一样。
要留神的是，MCP 可能带来真实的外部操作。配置时盯三件事：认证信息放哪、允许它调哪些工具、权限范围多大。每接一个工具，就多一组权限、一种失败方式、一批上下文噪声。这也是为什么开头说先别急着装。
7.6 定时任务：到点自动跑定时任务是 App 里的调度系统，早期叫 Automations，现在叫 Scheduled tasks。它适合三类事：固定频率的检查、未来某个时间点要执行的任务、需要跨天持续推进的长活儿。
设置过程五步：
选任务对应的项目。写清楚到点后要执行什么。选时间点或重复频率。选在 Local 还是 Worktree 里执行。检查权限，保存，等它跑。
定时之前先手动跑通同一份 Prompt（配置示意，未创建定时任务）
给读书笔记本安排一个不太危险的：每周五下午整理本周的提交记录，生成一份变更摘要写进 CHANGELOG.md。任务描述这么写：
读取最近 7 天的 git log，按"新增功能 / 修复 / 调整"三类整理成变更摘要，追加到 CHANGELOG.md 顶部，日期用今天。只改这一个文件，不要提交。
运行结果都收在定时任务视图里，有未读标记，你看完再决定要不要处理。
三条经验：
对 Git 仓库，选 Worktree 执行更稳，不会打扰你正在编辑的目录。定时之前，先在普通任务里手动跑一遍同样的描述。范围、工具、输出、改动都符合预期，再交给它无人值守。跑得勤的任务会攒下一堆 Worktree，定期归档不再需要的。7.7 /goal：跨会话追一个长期结果/goal 用来设一个跨多次会话的目标。它和 Plan、定时任务经常被搞混，用一张表分开：
功能
回答的问题
Plan
这一次准备分几步做
定时任务
什么时候启动，多久重复一次
/goal
这个长期目标还在不在推进，什么时候算完成
/goal 适合有明确完成标准、需要长时间持续推进的任务。目标挂在当前会话上，设完 Codex 会自动接着推，直到你暂停、清除，或者它达成结束条件。相关命令：/goal 看当前目标，还有 /goal edit、/goal pause、/goal resume、/goal clear。注意 /clear 会开一个新会话，目标不会跟过去。几分钟的小任务用不上它；需要你频繁判断方向的探索性任务，也别硬让它"不做完不停"。
一个像样的目标得有可验证的结束条件。"把所有测试迁移到新框架，并让现有测试全部通过"适合当目标；"持续优化这个项目"不适合，因为它永远都能找到新活儿干。
7.8 合理的升级顺序对新手，最稳的顺序是这样：
先做完一个纯本地的项目，什么都不接。把 AGENTS.md 写好。把反复出现的审查或发布流程做成一个 Skill。只接一个你确实需要的外部工具。需要定时或跨天运行了，再开定时任务和 /goal。能力是一层一层长出来的，不是一次堆出来的。用得熟不熟，从来跟你装了多少扩展没关系。
八、三个真实案例前面七章讲的是方法。这一章把方法塞进三个真实场景：让 Codex 通过 MCP 画架构图，让它在 CI 挂掉之后自动修好并开 PR，把 Obsidian 变成一个由它维护的知识库。每个案例都按同一套结构走：场景、准备、步骤、验收、坑。重点不是炫技，是需求、执行和验收怎么接上。
8.1 案例一：让它画架构图8.1.1 场景你要跟别人讲一个项目的结构、一段业务流程、几个系统之间的关系。纯文字看着费劲，一张图能省掉一半解释。以前你得自己拖框连线，现在可以让 Codex 从代码里读出结构，直接画。
8.1.2 三条路线，从简单到复杂路线一，什么都不装。 让 Codex 直接写 Mermaid。GitHub 的 Issue、PR、README 都能原生渲染，Obsidian 也能。想要能拖拽编辑的图，让它写 draw.io 的 XML 文件（后缀 .drawio），用 VS Code 的 Draw.io 扩展打开就能改。大多数"给 README 配张图"的需求，这条路就够了。
路线二，接官方 MCP。 draw.io 的维护者提供了官方 MCP 服务，npm 包名 @drawio/mcp。接上之后 Codex 多出几个工具：用 XML、CSV 或 Mermaid 打开一张图，在一万多个内置图形里搜（AWS、Azure、GCP、Kubernetes 这些都有），读取或替换本地 .drawio 文件里的某一页。效果是在浏览器里打开 draw.io 编辑器显示这张图，图的内容放在网址片段里，不上传到服务器。这条路没有导出功能，想要 PNG 得在编辑器里手动导。
路线三，装官方插件。 同一个仓库也提供了 Codex 插件，本地直接生成 .drawio 文件，装了 draw.io 桌面版之后还能导出 PNG、SVG、PDF。适合想把图当文件管、纳入版本库的情况。
这个案例走路线二，它最能体现上一章讲的 MCP 接入。
8.1.3 准备按上一章的写法添加，然后确认连上了：
codex mcp add drawio -- npx -y @drawio/mcp
codex mcp list
进会话，输入 /mcp，看到 drawio 状态是已连接、工具列表里有 open_drawio_xml 和 search_shapes 这些名字，就算接好了。App 用户在设置的 MCP 服务器里添加，效果一样。
8.1.4 步骤回到读书笔记本，让它画这个项目自己的结构图：
用 draw.io 的 MCP 画一张 reading-notes 项目的结构图。
内容：index.html、styles.css、app.js 三个文件之间的引用关系；app.js 里新增、搜索、删除三个操作各自和 localStorage 的读写关系；用户从输入到看到结果的数据流。
要求：横向布局；文件用圆角矩形，操作用普通矩形，存储用圆柱；数据流用带箭头的实线，引用关系用虚线；每个节点标注对应的文件或函数名。
画之前先把节点和边列成清单给我看，我确认后再画。画完在浏览器里打开。
两个细节值得注意。第一，提示词里明写了"用 draw.io 的 MCP"。不写的话它大概率直接回你一段 Mermaid，工具压根没被调用。第二，先要节点和边的清单再画。复杂的图一次画对的概率不高，清单是个很便宜的中间检查点。
reading-notes 结构示意（本机 draw.io 截图整理，另附可编辑源文件）
8.1.5 验收节点和代码对得上：每个节点都能在代码里找到对应的文件或函数边的方向对：读 localStorage 和写 localStorage 的箭头方向不一样层级清楚：文件、操作、存储三类节点在视觉上分得开真能编辑：在浏览器里能拖能改字，说明它生成的是真图，不是一张贴图8.1.6 坑图太复杂一次画不对。 让它分层来：先画文件层，确认了再加操作层。中文标签偶尔错位重叠。 让它改成自动排版，或者先用英文标签再手动改回来。想要文件不想要浏览器里的图。 换路线三，或者让它把 XML 直接写进一个 .drawio 文件。8.2 案例二：CI 挂了自动修，还顺手开个 PR8.2.1 场景CI 挂掉是家常便饭。传统流程是：收到通知，打开日志一行行看报错，切到本地找问题代码，修，提交，再推，等 CI 重跑，过了开 PR 等人合。整条链路全靠人串。碰上下班时间或者跨时区，一个 CI 失败拖到第二天太正常了。
接上 Codex 之后可以变成：CI 一挂，自动触发一个工作流，Codex 自己读代码、复现失败、做最小修改、跑测试，然后把修复开成一个 PR。你要做的只剩审一眼、点合并。
8.2.2 准备三样东西：
一个有测试的仓库。 读书笔记本原本没测试，给它加一个：把搜索逻辑抽成纯函数 filterNotes(notes, keyword) 放进 notes.js，用 Jest 写几条用例放进 notes.test.js，再加一个名为 CI 的工作流跑 npm test。一个 OpenAI API 密钥，存进仓库的 Secrets，名字叫 OPENAI_API_KEY。CI 里用的是 API 密钥不是 ChatGPT 账号，按 API 计费。仓库设置里允许 Actions 创建 PR。 位置在 Settings、Actions、General 下面的 Workflow permissions，勾上允许创建和批准 PR。不勾这一项，最后开 PR 那步会直接报错，而且报错信息不会告诉你是这儿的问题。8.2.3 工作流官方有个现成的 GitHub Action，叫 openai/codex-action。它负责装 CLI，并且通过一个安全代理访问模型接口，密钥不会直接暴露给 Codex 执行的命令。
关键设计是把工作流拆成两段：第一段只有读权限，负责跑 Codex 并把改动打成补丁文件；第二段有写权限但拿不到 API 密钥，负责应用补丁、开 PR。密钥和写权限永远不在同一个 job 里。下面这份改编自官方文档，存成 .github/workflows/codex-autofix.yml：
name: Codex auto-fix on CI failure
on:
workflow_run:
workflows: ["CI"]
types: [completed]
jobs:
generate_fix:
if: ${{ github.event.workflow_run.conclusion == 'failure' }}
runs-on: ubuntu-latest
permissions:
contents: read
outputs:
has_patch: ${{ steps.diff.outputs.has_patch }}
steps:
- uses: actions/checkout@v5
with:
ref: ${{ github.event.workflow_run.head_sha }}
fetch-depth: 0
persist-credentials: false
- uses: actions/setup-node@v4
with:
node-version: "20"
- name: Install dependencies
run: npm ci
- name: Run Codex
uses: openai/codex-action@v1
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
prompt: |
CI 工作流 "${{ github.event.workflow_run.name }}" 在提交
${{ github.event.workflow_run.head_sha }} 上失败了。
先运行 npm test --silent 复现失败。找出让测试通过所需的最小改动，
只做这一处修改，然后再运行 npm test --silent 确认通过。
不要重构无关文件，不要修改测试用例本身。
- name: Create patch artifact
id: diff
run: |
git add -N .
git diff --binary HEAD > codex.patch
if [ -s codex.patch ]; then
echo "has_patch=true" >> "$GITHUB_OUTPUT"
else
echo "has_patch=false" >> "$GITHUB_OUTPUT"
fi
- name: Upload patch artifact
if: steps.diff.outputs.has_patch == 'true'
uses: actions/upload-artifact@v4
with:
name: codex-fix-patch
path: codex.patch
if-no-files-found: error
open_pr:
runs-on: ubuntu-latest
needs: generate_fix
if: needs.generate_fix.outputs.has_patch == 'true'
permissions:
contents: write
pull-requests: write
steps:
- uses: actions/checkout@v5
with:
ref: ${{ github.event.workflow_run.head_sha }}
fetch-depth: 0
- uses: actions/download-artifact@v4
with:
name: codex-fix-patch
- name: Apply Codex patch
run: git apply --index codex.patch
- name: Open pull request
env:
GH_TOKEN: ${{ github.token }}
FAILED_HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
FAILED_HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
RUN_ID: ${{ github.event.workflow_run.run_id }}
run: |
branch="codex/auto-fix-$RUN_ID"
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git switch -c "$branch"
git commit -m "Auto-fix failing CI via Codex"
git push origin "$branch"
{
echo "Codex 在 CI 于 \`$FAILED_HEAD_SHA\` 失败后生成了这个补丁。"
echo
echo "合并前请先审查改动。"
} > pr-body.md
gh pr create \
--base "$FAILED_HEAD_BRANCH" \
--head "$branch" \
--title "Auto-fix failing CI via Codex" \
--body-file pr-body.md
几点说明：
workflow_run 只对默认分支上的工作流文件生效。得先把这个文件合进主分支，它才会开始监听。触发条件是名为 CI 的工作流以失败结束。workflows 里的名字改成你自己的。提示词就是第四章那套修 bug 的写法：先复现，再最小修改，再验证，不碰无关文件。这里多加了一句"不要修改测试用例本身"，防止它走捷径把测试改成永远通过。第一段没给 Codex 任何写远端的权限，它连推送都做不到，只能留下一个补丁文件。8.2.4 走一遍在读书笔记本里故意埋个雷：把 filterNotes 里的关键字匹配改成区分大小写，而测试用例要求不区分。推送。CI 挂。几分钟后仓库里多出一个叫 codex/auto-fix-<编号 class="imgbox"> 的分支和一个 PR，改动只有一行，把匹配改回不区分大小写。看一眼 diff，合并。
PR 审查示意：核对 diff、检查状态和审查意见后再决定（非真实 PR / CI 结果）
8.2.5 验收PR 的改动范围和失败原因对得上，没有顺手改别的修复分支上的 CI 是绿的Actions 日志里能看到它真跑了 npm test，不是只改了代码测试文件没被动过8.2.6 坑和安全密钥别设成 job 级的环境变量。 只通过 Action 的输入传。Job 级环境变量会被 Codex 执行的每一条命令看到。Codex 步骤放在 job 的最后一步。 它可能留下后台进程，或者改动仓库里的钩子，后面再跑别的步骤不安全。别对外部贡献者的 PR 触发。 别人可以在 PR 描述、提交信息甚至 AGENTS.md 里塞指令，这些对 Codex 来说全是不可信输入。这个 Action 默认只允许有写权限的人触发，保持默认就好。别关默认的安全策略。 它默认会去掉 sudo，为的是防止密钥通过进程信息泄露。别为了省事改成不安全模式。盯着成本。 一次成功的修复通常几美分，但调试工作流的阶段可能反复触发。给密钥设个月度上限，睡得踏实。再提一句，这条路和 Codex 云端的 GitHub 集成是两码事。云端集成是在 PR 评论里 @codex review 让它审查，或者 @codex fix the CI failures 让它在云端开个任务去修。那条路不用写工作流，但得把仓库连到 Codex 云端。这个案例走的是 Actions，权限和成本完全在你手里。
8.3 案例三：让它替你维护一个知识库8.3.1 场景你收藏了几百篇文章，一篇都没回头看过。每次想起"之前好像读过一篇讲这个的"，还得重新搜一遍。
常见解法是 RAG：把文章切块、向量化，提问时临时检索几段拼给模型。它的毛病是每次都从零开始，读一百遍也不会比第一遍更懂。
LLM Wiki 是另一条思路，来自 Andrej Karpathy 2026 年 4 月发的一份想法文件。核心是：不在提问时临时检索，而是让 Agent 增量地写并持续维护一个 wiki。知识只编译一次，之后不断更新，越用越厚。你几乎不亲手写 wiki 里的任何一页，Agent 写，Agent 维护。他有个很准的比喻：Obsidian 是编辑器，模型是程序员，wiki 是代码库。
这个案例是读书笔记本的自然升级。笔记本存的是一句话摘录，知识库存的是跨文章的实体、概念，以及它们之间的关系。
8.3.2 结构三层：
原始资料 raw/：你放进去的文章、PDF、网页剪藏。只读，Agent 从这儿读，永远不改。wiki wiki/：Agent 写的 markdown 页面。每篇资料一页摘要，每个人物、项目、工具一页实体，每个概念一页概念，还有综述和对比。规则 AGENTS.md：告诉 Agent 这个 wiki 的目录结构、页面格式、命名约定和工作流程。第五章讲的项目规则，在这儿成了整个系统的骨架。再加两个特殊文件：
index.md：全部页面的目录，每页一行说明。每次摄入都更新。回答问题时先读它，再决定翻哪几页。几百页的规模下，这比向量检索省事得多。log.md：只追加的日志，记录每次摄入、查询、巡检干了什么。三个操作：
摄入：读一篇新资料，跟你对一下要点，写摘要页，更新索引，更新所有相关的实体页和概念页，追加一条日志。一篇文章可能牵动十几页。查询：先读索引，找到相关页，读完综合回答，带引用。答得好的可以回填成一个新页面。巡检：找页面之间的矛盾、被新资料推翻的旧说法、没有入链的孤儿页、被反复提到却没有自己页面的概念、缺失的交叉引用。8.3.3 为什么是 Obsidian一个 Obsidian 仓库就是一个装满 markdown 的文件夹，页面之间用 [[双链]] 连着。这意味着 Codex 不用装任何插件就能在这个文件夹里干活，它读写的就是普通文件。Obsidian 负责三件它擅长的事：Web Clipper 把网页剪进 raw/，图谱视图让你看见 wiki 长成了什么样，日常翻阅和手动补几笔。
想要更多能力有两条延伸：Obsidian 从 1.12 版起有官方命令行工具，Codex 可以直接调它搜索、创建、追加内容；社区也有基于本地 REST API 插件的 MCP 服务，让 Codex 通过接口操作仓库。第一版这些都用不上，一个文件夹就够。
8.3.4 步骤第一步，建仓库。 在 Obsidian 里新建仓库 reading-wiki，初始化成 Git 仓库，建好 raw/、wiki/ 两个目录和空的 index.md、log.md。
第二步，写规则。 这是整个案例最关键的一步。按第五章的原则来：短、具体、可执行。
# AGENTS.md
## 这是什么
这是一个由你维护的个人知识库。你负责写和维护 wiki/ 下的所有页面，我只负责往 raw/ 里放资料和提问。
## 目录
- raw/：原始资料，只读。永远不要修改、移动或删除这里的任何文件。
- wiki/summaries/：每篇原始资料一页摘要，文件名和资料同名。
- wiki/entities/：人物、项目、工具、组织，一个实体一页。
- wiki/concepts/：概念和方法，一个概念一页。
- index.md：全部 wiki 页面的目录，每页一行，写清楚这页讲什么。
- log.md：只追加的操作日志。
## 页面格式
- 每页开头一段 frontmatter：type（summary / entity / concept）、sources（引用的 raw 文件列表）、updated（日期）。
- 正文里提到其他页面时一律用 [[双链]]，链接目标必须真实存在。
- 每个结论后面标注来源，格式是 [[summaries/文件名]]。
- 不确定的说法明确写"来源未证实"，不要编。
## 摄入流程
1. 读 raw/ 里我指定的新资料，先用五句话告诉我要点，等我确认。
2. 写摘要页。
3. 找出资料里出现的实体和概念，已有页面就更新，没有就新建。
4. 更新 index.md。
5. 在 log.md 追加一行：## [日期] ingest | 资料名，后面列出新建和更新的页面。
## 查询流程
先读 index.md，挑出相关页面再读正文，回答时带页面引用。回答里如果包含了 wiki 里没有的新综合，问我要不要存成新页面。
## 巡检流程
检查五类问题：页面之间的矛盾、被新资料推翻的旧说法、没有入链的孤儿页、被多次提到但没有页面的概念、缺失的交叉引用。只输出问题清单和建议，等我确认后再改。
## 禁止
- 不改 raw/。
- 不删页面，要删先问我。
- 一次摄入不超过 5 篇。
第三步，第一次摄入。 用 Obsidian 的 Web Clipper 剪三篇文章进 raw/，然后在仓库目录启动 Codex：
按 AGENTS.md 的摄入流程处理 raw/ 里的三篇新资料。先逐篇给我五句话要点，我确认一篇你处理一篇。
摄入完打开 Obsidian 的图谱视图，你会看到三篇摘要页周围长出一圈实体页和概念页，彼此连着线。
第四步，第一次查询。 挑一个跨三篇文章的问题：
根据 wiki 回答：这三篇文章对"最小可行产品"的看法有什么不同？每个观点标注来自哪一页。
第五步，巡检。 摄入到二三十篇之后，做第一次巡检：
按 AGENTS.md 的巡检流程检查整个 wiki，输出问题清单，先不要改。
巡检特别适合做成定时任务。按上一章的方法，每周一早上跑一次，环境选 Worktree，结果进定时任务视图，你周一看清单决定处理哪些。
知识图谱示意：资料、实体与概念通过双链连接（根据官方图谱制作的示例知识库）
8.3.5 验收raw/ 里每篇资料在 wiki/summaries/ 里都有对应的摘要页index.md 列出了全部页面，随机抽三个链接都能打开随机挑一个实体页，入链不止一个log.md 每次操作都有记录，最新一条在最下面随机挑一个结论，顺着引用能一路回溯到 raw/ 里的原文8.3.6 坑一次塞太多资料。 每篇会牵动十几页，一次二十篇它就顾此失彼了。规则里限死五篇，守住它。它动了原始资料。 规则里写了禁止，但你还是要在 diff 里确认 raw/ 没被碰。这也是把仓库纳入 Git 的理由之一。只摄入不巡检。 矛盾和过时说法会悄悄堆起来，等你发现的时候已经不知道该信哪一页了。巡检频率至少要跟上摄入频率。规则写得太空。 要是 AGENTS.md 只写一句"维护一个高质量的知识库"，它会自己发明一套结构，而且每次发明的还不一样。目录、格式、流程，都得写死。8.4 三个案例的共同点回头看，三个案例用的其实是同一套东西。
都走第四章那条链路：先定目标和边界，再执行，最后用证据验收。案例一是上一章的 MCP 接入，接之前先问了三句话，接上之后用 /mcp 确认。案例二把第三章的权限思路推到了极致：非交互执行，密钥和写权限分开，Codex 连推送都做不到。案例三把第五章的项目规则当成系统骨架，再加上定时任务做巡检。方法没变，变的只是场景。
九、随身手册这一章不讲道理，只放能直接抄的东西。前面八章散落的规则、模板和命令，都收在这儿了。用的时候翻。
9.1 十二个常见的坑坑
典型表现
更直接的修正
在错误的目录启动
找不到文件、改到别处、读了一堆无关材料
启动后第一件事看工作目录和文件清单，不对就退出重开
一句话要求做一个大项目
做出来的东西哪儿都差一点，还说不清问题在哪
先定义最小可用版本，大目标拆成每轮可验收的小任务
没有 Git 检查点
改坏了不知道怎么退回，也说不清改了什么
任务前提交一次，完成后看 diff，再决定留不留
只说要什么，不说不能改什么
顺手换了依赖、改了接口、动了无关目录
明确依赖、接口、目录和数据安全边界
把"运行成功"当"需求完成"
页面能打开，但按用户的操作走一遍就露馅
用用户动作写验收清单，运行通过只是证据之一
发现问题就让它大规模重构
一个 bug 修出三个新 bug
先要根因分析，再做最小修改，最后补回归检查
一上来就给完全访问
看不到它的过程，出错影响范围也收不住
只读探索，工作区可写执行，高风险动作单独确认
把所有规则塞进每次提示词
提示词越来越长，还是漏
长期规则进 AGENTS.md，重复流程做成 Skill
一个长会话处理不相关的任务
它把上一个任务的约束带到这个任务里
一个会话对应一个连贯目标，长了就整理压缩，分叉就另起
只看总结，不看实际差异
"已完成"三个字把你骗过去了
看修改的文件、命令输出、测试结果和 diff，它的自述不是证据
一口气装满扩展
工具列表老长，真干活时不知道该调哪个
没有手动重复三次的流程不自动化，接入前先问三句话
定时任务没手动跑过就上线
半夜跑出一堆没人要的改动
先在普通任务里手动跑一遍同样的描述，再交给无人值守
9.2 六个可以直接复制的提示词方括号里的内容替换成你自己的。
1. 快速理解一个陌生项目（只读）
先不要修改任何文件。请从当前项目中找出：项目用途、主要目录、启动入口、依赖管理方式、构建和测试命令，以及最可能出问题的三个区域。每个结论都注明依据的文件。最后给我一条从零启动这个项目的最短路径。信息不够就明确说缺什么，不要猜。
2. 把模糊的想法变成可执行的需求
我想做【一句话描述想法】。先不要写代码。请同时站在产品和工程的角度审这个需求：目标用户是谁，核心场景是什么，最小的功能闭环是什么，明确不做的范围有哪些，关键风险在哪，验收标准怎么写才能逐条检查。最多问我 5 个会影响方案的问题，等我回答后再输出分阶段的实施计划。
3. 安全地实现一个功能（四字段）
目标：【要改变什么，具体到操作层面】。
上下文：【先读哪些文件、相关的报错、参考实现或截图】。
约束：【不能改的接口、不能加的依赖、不能碰的目录、要保持的风格】。
完成标准：【测试、构建、指定操作的结果，怎么算做完】。
先读相关文件，给出不超过 6 步的计划；只做与目标有关的最小修改；完成后运行相关验证，列出修改的文件、命令结果和剩余风险。
4. 修复一个可复现的问题
问题现象：【实际发生了什么】。
复现步骤：1.【 】 2.【 】 3.【 】。
预期结果：【应该发生什么】。
请先定位根因并给出证据，不要立即重构；然后提出最小修复方案。实施后按同样的步骤重新验证，并补一个能防止回归的测试或检查。不要修改无关文件。
5. 收尾前的交付自检
结束前做一次交付审查：逐条对照原始目标和验收标准；看 Git diff 里有没有无关修改；运行与本次变更相关的测试、构建、lint 或类型检查；检查错误处理和边界情况。最后只输出四部分：已完成、验证证据、未完成、风险与下一步。没有证据的项不要标记为完成。
6. 整理上下文，准备压缩
请先整理当前任务的上下文，只保留：目标、核心约束、已经确认的决策、已经修改的文件、验证结果、还没解决的问题、下一步计划。被推翻的方案和重复的讨论都删掉。
整理完再输入 /compact。
9.3 速查表9.3.1 你要做的事，用什么你现在要做的事
优先使用
了解一个项目，不允许它改
只读沙箱 + 普通任务
直接改当前目录
Local + 工作区可写
同一个仓库并行两个任务
Worktree
试一个改动，不碰当前分支
Worktree
任务说清楚了，交出去后台跑
Cloud
先讨论方案再动手
/plan，或者在任务里写明只要计划
检查它改了什么
改动面板 + /review
看报错、跑测试
集成终端
检查本地网页
内置浏览器
操作已登录的网页
浏览器扩展
操作本地桌面应用
Computer Use
固化一套重复的做法
Skill
一次装一整套相关能力
Plugin
连接项目外的数据和工具
MCP
定时重复执行
定时任务
跨会话追一个长期结果
/goal
9.3.2 CLI 常用命令codex # 在当前目录启动交互界面
codex "任务描述" # 启动并直接下第一条任务
codex exec "任务描述" # 非交互执行一次，适合脚本和 CI
codex resume --last # 继续最近一次会话
codex resume # 从列表里挑一个会话继续
codex fork --last # 从最近一次会话分叉
codex review --uncommitted # 非交互审查未提交的修改
codex review --base main # 审查相对 main 分支的改动
codex mcp add <名字> -- <启动命令>
codex mcp list
codex plugin list
codex login / codex login status / codex logout
codex update # 更新到最新版
codex doctor # 自检安装、配置、登录和运行环境
codex app # 打开桌面 App
9.3.3 常用启动参数参数
作用
-C <目录>
指定工作目录
--add-dir <目录>
额外允许写入的目录
-s read-only / -s workspace-write / -s danger-full-access
沙箱档位
-a untrusted / -a on-request / -a never
审批策略
-m <模型>
指定模型
-p <名字>
叠加一份命名配置，对应 ~/.codex/<名字>.config.toml
-i <图片>
附上图片作为上下文
--search
允许联网搜索
-c key=value
临时覆盖某个配置项
9.3.4 会话内常用命令输入 / 会列出当前版本真正支持的命令。下面是最常用的一批。
命令
用途
/status
查看会话、上下文用量和限制
/model
切换模型和推理强度（App 和 IDE 里另有 /reasoning）
/permissions
查看和调整沙箱与审批
/plan
进入规划模式，只出计划不动手
/review
审查当前改动
/diff
查看 Git diff
/init
生成 AGENTS.md 草稿
/compact
压缩对话历史
/fork
从当前位置分叉一个新任务
/clear
清屏并开始新对话
/new
开始新对话，不清屏
/usage
查看额度用量
/memories
临时开关记忆功能
/fast
切换快速模式
/mcp
查看 MCP 连接状态
/skills
查看可用的 Skill
/plugins
浏览和安装插件
/goal
设置跨会话的长期目标
9.3.5 输入框里的操作操作
效果
输入 @
搜索并引用工作区文件
输入 ! 加命令
直接运行一条 Shell 命令
运行中按 Enter
给当前这一轮补充指令
运行中按 Tab
排队一条后续指令
空输入框连按两次 Esc
回到上一条消息继续编辑，会从那里分叉
Ctrl+R
搜索历史输入
Ctrl+O
复制上一次完整输出
Ctrl+L
只清屏，不清上下文
/clear
真正清空上下文
9.4 开工前过一遍☐ 目录对不对，是不是最小的那个☐ 有没有 Git 检查点☐ 权限档位是不是刚好够用☐ 目标能不能一句话说清楚☐ 有没有能逐条打勾的验收清单☐ 该给它看的文件、截图、报错，给了没有☐ 结尾有没有要求它列出改了什么、验了什么、还剩什么9.5 交付前再过一遍☐ 逐条对照验收清单☐ diff 里没有无关改动☐ 相关的测试、构建、检查都跑过了☐ 错误处理和边界情况看过了☐ 最终说明分四部分：已完成、证据、未完成、风险☐ 没有证据的项没被标记成完成写在最后全文到这儿就结束了。
如果只让你记一件事，那就记这个：Codex 的交付质量取决于四个开关，目标够不够清晰，上下文够不够有效，权限合不合理，验收能不能执行。任何一个开关没打开，结果都会打折。
模型能力越强，这四个开关越要紧。因为强大的 Agent 能更快地放大正确方向，也能同样快地放大错误假设。
所以新手真不必一上来就追求"让它一次生成一个完整产品"。先让它在正确的目录里干完一件小事，拿出能验证的证据，再一点点扩大范围。你能看懂它为什么这么改，知道怎么退回去，能判断它到底做完没有，才算真的把它用起来了。