32. 最佳实践与速查表

心态：把 Codex 当队友

用 Codex 这件事，效果好坏一大半取决于你把它当什么。把它当「问一句答一句」的搜索框，它永远只能发挥三成功力。

Codex 像你新招进来的一个能力很强、但完全不了解你们项目的新同事。你得给他一份入职手册（AGENTS.md）、告诉他代码怎么跑怎么测、踩错了纠正他一次让他记住。调教得越久，他越顺手。

提示词四件套

同一个需求，话说得到不到位，Codex 干出来的活儿天差地别。你把一句信息量约等于零的「修一下这个 bug」甩过去，它只能脑补，猜错了你盯着 diff 嘀咕「这 AI 不行」。

把要喂的东西记成四件套，缺哪件它就在哪件上替你做主：

要件	回答的问题	缺了会怎样
目标（Goal）	要做成什么	它猜你想要啥，方向全凭运气
上下文（Context）	哪些文件、报错相关	它在错的地方瞎找，绕远路
约束（Constraints）	有什么不能碰	它按自己习惯来，风格全乱
验收（Done when）	怎么算成功	它觉得「能跑」就交差，bug 留给你

四件齐活的一条例子：

在 src/validators.py 里加一个 validate_email 函数（目标）。
只动这个文件，别碰别的（范围）。
用标准库 re 实现，别引第三方库（约束）。
写完补三个测试：user@example.com 为真、invalid 为假、user@.com 为假，
跑 pytest 确认全过（验证）。

能贴别说

凡是能「贴」的，绝不用「说」。Codex 读原始材料，永远比读你对材料的二手转述准。

你想给的料	用嘴描述	直接喂
某个文件的内容	「项目里有个认证文件」	需求里点名 src/auth/session.ts
当前在看的代码	「就那块逻辑」	IDE 里选中它，扩展自动带进上下文
一段报错	「它报了个 undefined」	把完整 traceback 原样贴进去
一个 UI 问题	「按钮位置不对」	直接粘截图

工作流模式

先计划再动手

任务一复杂一模糊，直接让它写代码，它就得一边猜你的意图一边敲键盘，方向歪了你很晚才发现。让它先出个计划，等于在动手前给你一次便宜的纠偏机会。

/plan 把这个模块从回调写法迁到 async/await，
列清楚改哪些文件、每个文件改什么，列完先别动

什么活儿该拆、该上 /plan，什么活儿别折腾：

任务	怎么处理
改错别字、加一行日志	直接干，别拆别规划
给单个函数加校验、补一个测试	单个需求 + 四件套，一步到位
跨多文件、你不熟的代码	先 /plan 出方案，审完再分步放行
「实现整个 XX 系统」	拆成 5~8 个自带验证的小步，逐步跑

权限分档：默认从严

一上来就给满权限，等于把方向盘和油门同时交给一个你还没摸清脾气的新司机。

场景	建议档位	理由
刚上手 / 不熟的项目	默认（动手前问、沙箱收紧）	看清它要干嘛再放行
自己的可信仓库、重复跑的活	适度放宽审批	减少一直点「同意」的烦躁
跑不熟的脚本 / 第三方代码	收到最紧	防止执行没预期的命令

让它自验证

别让 Codex 写完代码就停。让它顺手把测试写了、把检查跑了、把改动 review 一遍，再交给你。

但有个前提：它得知道「好」长什么样。这份标准从哪来？要么写在提示里，要么写在 AGENTS.md 里。

改完跑 pnpm test，全绿了再告诉我

一句话的事，挡掉一大半返工。CLI 里还有个 /review 命令特别值钱：它能按 PR 风格跟基线分支对比着审、审未提交的改动。

管好线程

一条线程只干一件连贯的事。只要还是同一个问题，就待在同一条线程里。只有当工作真的分叉了，才用 /fork 另起一条。最该避免的反模式是「一个项目从头到尾就用一条线程」，那会让上下文越堆越肥。

# 接着存档的对话往下聊
/resume

# 另起新线程，原记录不动
/fork

# 压缩长对话，腾出上下文
/compact

# 看当前状态和剩余上下文
/status

线上任务先取证

线上问题别让 Codex 先猜原因，先让它拿证据链。提示可以这么写：

先不要改代码。请按证据链排查这个线上问题：
1. 复现用户路径，记录请求方式、状态码、关键响应摘要和时间
2. 查对应时间段的应用日志，只摘出相关错误行
3. 找到涉及的配置、路由、任务或数据表，但不要修改生产状态
4. 给出「已验证事实 / 待确认假设 / 下一步验证」三段结论
5. 输出时脱敏，隐藏 token、私有链接、邮箱、手机号、订单号

踩坑与正确做法对照表

踩坑	正确做法
把持久规则塞进提示里	搬进 AGENTS.md，提示只放一次性需求
没告诉它构建、测试命令怎么跑	在 AGENTS.md 里写清运行和测试方式
多步复杂任务跳过规划直接写	复杂活先 /plan 出计划、确认方向再动手
还没摸清工作流就给满权限	默认从严，按可信场景逐步放宽
一个项目从头到尾就一条线程	一个任务一条线程，分叉了才 /fork
多条线程同时改同一批文件	用 git worktree 各开一份独立工作区
盯着它一步步看，自己干不了别的	让它并行跑，你腾出手做自己的事
线上问题没复现就开修	先记录原始症状、请求状态、日志时间
把日志原样贴进公开 PR	脱敏敏感值，保留时间、状态码、错误类型

常见问题排查

排查心法：先查三样

遇到任何 Codex 问题，先按顺序确认三件事，八成问题卡在这三关：

# 1. 版本对不对、装没装上
codex --version

# 2. 登没登录、用的哪种认证
codex login status

# 3. 当前会话权限怎么配的（在交互界面里敲）
/status

装不上、命令找不到

npm install 之后敲 codex 回你 command not found，八成是 PATH 没含 npm 全局 bin。敲 npm config get prefix 看全局目录在哪，确认它的 bin 子目录在 PATH 里。

装的时候一堆 EACCES 权限报错，别用 sudo npm install -g 硬怼。正路是改 npm 全局目录到你自己有权限的位置，或者用版本管理器装的 Node。

登录失败、认证过期

在服务器、Docker、SSH 这种没浏览器的环境登不了，用设备码登录：

codex login --device-auth

它会给你一个链接和一次性验证码，在任意一台有浏览器的机器上打开链接、输码、确认即可。

你的环境	推荐登录方式
本机有浏览器	直接 codex login
远程 / 服务器	codex login --device-auth
设备码也不行	本机登好，拷贝 ~/.codex/auth.json 过去
公司有 TLS 代理	先设 CODEX_CA_CERTIFICATE 再登

不肯改文件

这不是 bug，是默认安全设计。Codex 默认不会无脑改你机器上的文件，沙箱写权限默认收着。临时放开用命令行参数：

codex --sandbox workspace-write --ask-for-approval on-request

越聊越笨

一个会话聊久了，Codex 开始「失忆」，忘了前面说过的约定。这是上下文窗口满了，早期信息被挤出去。

你的处境	该用哪个
当前任务没完，但聊太长开始飘	/compact 压缩摘要
换个全新任务，不想被旧上下文带偏	/new 另起一段干净对话
想连界面带对话彻底重置	/clear 全清
想先看看还剩多少容量	/status 查上下文余量

费用 / 额度用超

简单活儿用 gpt-5.6-luna、低推理强度，把旗舰 + 高推理留给真正的硬骨头。API key 账单超预期，先看是不是推理强度拉太满。

# 临时覆盖推理强度
codex -c model_reasoning_effort=medium

# 长期写入配置
# model_reasoning_effort = "medium"  写进 ~/.codex/config.toml

改错了怎么撤

首选靠 Git。这就是为什么动手前先 git commit 一次干净状态。改坏了，git diff 看它动了啥，git restore 退回上一个提交。

命令速查表

安装与登录

目的	命令
标准安装（macOS/Linux）	curl -fsSL https://chatgpt.com/codex/install.sh | sh
标准安装（Windows）	powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
npm 安装	npm install -g @openai/codex
Homebrew 安装	brew install --cask codex
更新到最新版	codex update
登录（浏览器 OAuth）	codex login
登录（设备码）	codex login --device-auth
查登录状态	codex login status
退出登录	codex logout
体检诊断	codex doctor

CLI 常用子命令

子命令	干什么
codex	启动交互式终端界面
codex exec	非交互跑一次，跑完即退
codex resume	接着上一次会话继续聊
codex fork	把某次会话分叉成新线程
codex apply	把云端任务生成的 diff 应用到本地
codex mcp	管理 MCP 服务器
codex features	列出功能开关并持久启用/禁用

高频全局标志

标志	作用
--model / -m	临时换模型
--image / -i	附带图片
--cd / -C	指定工作目录
--sandbox / -s	选沙箱档位
--ask-for-approval / -a	选审批时机
--search	开实时联网搜索
--add-dir	额外给某目录写权限
--config / -c	命令行临时改配置
--yolo	跳过一切审批和沙箱（危险）

codex exec 专属标志

标志	作用
-（作为 PROMPT）	从 stdin 读提示词
--json	输出按行的 JSON 事件流
--output-last-message / -o	把最终回复写到文件
--output-schema	给 JSON Schema 约束最终输出
--skip-git-repo-check	允许在非 Git 目录里跑
--ephemeral	不在磁盘留会话记录

斜杠命令（TUI 里输入）

斜杠命令	干什么
/model	切当前模型
/status	看模型、审批、可写目录、剩余上下文
/compact	把长对话压成摘要
/diff	看 Git diff
/permissions	中途调整审批策略
/review	让 Codex 审一遍当前改动
/init	在当前目录生成 AGENTS.md 脚手架
/mcp	列出当前会话能调的 MCP 工具
/skills	浏览并选用本地 skill
/new	同一 CLI 会话里开全新对话
/clear	清屏并开新对话
/plan	进入计划模式
/quit	退出 CLI

config.toml 常用配置项

# ~/.codex/config.toml 最小可用配置
model = "gpt-5.6"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = false

配置键	作用	取值示例
model	默认模型	"gpt-5.6"
model_reasoning_effort	推理强度	minimal/low/medium/high/xhigh
sandbox_mode	沙箱档位	read-only/workspace-write/danger-full-access
approval_policy	审批策略	untrusted/on-request/never
web_search	联网搜索模式	disabled/cached/live
sandbox_workspace_write.network_access	工作区联网	true/false
sandbox_workspace_write.writable_roots	额外可写目录	["/path/a"]

权限与沙箱档位

沙箱档位	能干什么	适合场景
read-only	只读，不能改文件	让它先看、先分析
workspace-write	能改工作区内文件	日常本地开发
danger-full-access	全盘读写、放开网络	只在隔离容器/CI 里用

审批时机	含义
untrusted	只对可信命令放行，其余都问
on-request	需要时才暂停问你（推荐）
never	从不问，非交互/CI 用

本地低摩擦干活的推荐组合：

codex --sandbox workspace-write --ask-for-approval on-request

模型与推理强度

模型	定位	什么时候用
gpt-5.6-sol	旗舰、默认	复杂编程、重构、难缠 bug
gpt-5.6-terra	中量、平衡	日常写功能、补逻辑、代码审查
gpt-5.6-luna	轻量、快、省	杂活、批量任务、子代理
gpt-5.3-codex-spark	即时型研究预览	高频实时迭代（仅 ChatGPT Pro）

推理强度档位：

取值	思考力度	典型场景
minimal	几乎不想，最快	改 typo、重命名
low	略想一下	小修小补
medium	默认甜区	绝大多数日常编程
high	深思熟虑	多文件改动、设计权衡
xhigh	顶格	真·硬骨头

快捷键

快捷键	功能
Enter	发送消息
Shift+Enter	换行
Ctrl+C	中断操作
Ctrl+C 两次	退出 Codex
Ctrl+D	退出（输入空时）
Ctrl+R	搜索历史
Esc Esc	编辑上一条消息
Ctrl+O	复制最后回复

进阶能力入口

能力	关键入口
MCP	codex mcp list / codex mcp add <name>
子代理	config.toml 里 [agents]，会话里 /agent 切线程
Skills	会话里 /skills，配置里 [[skills.config]]
Hooks	config.toml 里 [hooks] 段

术语表

基础概念

术语	一句话记住
智能体（Agent）	会自己动手的 AI，不只是回你话
智能体循环（Agentic Loop）	想 -> 做 -> 看，不行再来一轮
上下文窗口（Context Window）	一次能看到的信息总量，有上限
token	计量文本的最小单位，关乎额度和钱

Codex 专有概念

术语	一句话记住
AGENTS.md	给 Codex 看的项目说明书，写一次永久生效
codex exec	非交互运行方式，给脚本和自动化用
沙箱（Sandbox）	给 Codex 画的边界，圈内自己干，出圈要问你
审批模式（Approval Mode）	要出圈时停不停下来问你，和沙箱并排的旋钮
推理强度	让模型「动手前想多久」的旋钮
service_tier	给请求排优先级，优先省钱还是优先快
config.toml	Codex 的总配置文件，TOML 格式
Chronicle	实验性记忆功能，从屏幕上下文构建记忆

扩展能力五件套

术语	一句话区分	什么时候碰
MCP	接外部工具的统一接口	想连数据库/设计稿/浏览器
子代理（Subagent）	并行干专项活、回汇总	一件事要从多个角度同时审
技能（Skill）	把固定步骤打包成一招	同一套流程你反复要它做
钩子（Hook）	特定时机自动触发的脚本	想强制每次都自动跑某件事
插件（Plugin）	一堆能力打成套装一键装	要团队共享、统一管理

模型相关

模型	定位	最适合
gpt-5.6-sol	旗舰、默认	复杂编程、重构、研究
gpt-5.6-terra	中量、平衡	日常写功能、代码审查
gpt-5.6-luna	轻量、快省	简单批量活、给子代理用
gpt-5.3-codex-spark	即时型（研究预览）	高频实时迭代
gpt-5.2 / gpt-5.3-codex	已弃用	别再用，换成最新的

配置文件路径

文件	路径	作用
用户配置	~/.codex/config.toml	全局默认配置
项目配置	.codex/config.toml	项目特定配置
项目指令	AGENTS.md	项目行为规范
日志目录	~/.codex/log/	运行日志
会话目录	~/.codex/sessions/	会话记录

小结

这一章把全书的核心浓缩成速查表和最佳实践：

• 心态：把 Codex 当持续调教的队友，不是一次性工具
• 提示词：目标 + 上下文 + 约束 + 验收，四件套填空，别漏验收
• 工作流：复杂活先 /plan、权限默认从严、让它自验证、一条线程一件事
• 排查：先查版本、登录、权限三体征；不肯改文件是默认安全；越聊越笨用 /compact
• 速查表：-m 换模型、-s 调沙箱、-a 调审批、-o/--json 收结果
• 术语：沙箱管能不能、审批管问不问、MCP 接工具、子代理分活、Skill 打包流程

拿到任意一个 Codex 任务时，下意识过一遍：要不要先出计划、提示四件套填全没、AGENTS.md 里的规矩够不够、要不要让它自测、该用哪档权限。把这套变成肌肉记忆，你跟 Codex 的协作就从碰运气变成了有章法。