Codex 用法手册
第 02 章让你跟 Codex 通了个气;这一章我们把它正式当工具来用。审批模式、沙盒、看懂 diff、何时该重启——这些是接下来所有实战章节默认你会的能力。
3.1 三种审批模式
审批模式决定 Codex 做事前要不要问你。你可以把它理解成“助手的自主程度”。
| 模式 | 通俗理解 | 新手建议 |
|---|---|---|
| Read-only | 只看不动 | 你想让它解释项目、找问题、给计划时用。 |
| Auto / workspace-write | 能在当前项目里读写,越界会问 | 日常最推荐。第 05 章开始基本用它。 |
| Full Access | 限制最少,风险最高 | 新手先别用,除非你非常清楚它要做什么。 |
在 CLI 里,你可以用 /permissions 调整权限。刚开始不确定时,宁可保守一点。让 Codex 先解释计划,你确认后再给它更大的权限。
3.2 沙盒到底罩着什么
沙盒是 Codex 的活动边界。它控制的是“技术上能碰哪里”。审批控制的是“什么时候问你”。两者一起工作。
默认情况下,Codex 会围绕你启动它的当前目录工作。比如你在 my-product-site 里运行 codex,它就应该把这个文件夹当成工作区。
常见边界可以这样理解:
- 当前项目文件:日常可以读写。
- 项目外目录:通常需要额外授权。
- 联网:默认更保守,需要时会说明理由。
- 危险命令:比如删除、重置、改系统设置,你应该格外仔细。
想知道当前会话的边界,可以输入 /status。它会显示当前工作目录、权限、上下文等信息。
3.3 看懂它的"剧本":diff 视图怎么读
Diff 是“这次改了什么”的对照表。你不用看懂所有代码,但一定要看大方向。
+开头:新增的内容。-开头:删除的内容。- 文件名变化:这次动了哪些文件。
新手看 diff 时只问四个问题:
- 它改的是不是我刚才要求的地方?
- 有没有动到不相关文件?
- 有没有删掉大段内容?
- 有没有新增奇怪链接、账号、密钥或陌生脚本?
如果你看不懂,不要硬装懂。直接让 Codex 解释。
3.4 几个常用内置命令
在 Codex CLI 输入框里敲 /,会出现一组 slash 命令。先记这几个就够:
| 命令 | 用途 | 什么时候用 |
|---|---|---|
/plan | 先规划 | 任务超过两步、你怕它直接乱改时。 |
/permissions | 改权限 | 想从只读切到可写,或反过来收紧权限时。 |
/diff | 看改动 | 想确认当前文件改了什么时。 |
/review | 让 Codex 自查 | 提交前让它找风险、bug、遗漏测试。 |
/status | 看会话状态 | 想知道当前目录、权限、模型、上下文时。 |
/model | 选择模型和推理强度 | 想换 GPT-6 Astra,或调整速度与思考深度时。 |
/fast on | 打开 Fast mode | 确实赶时间,并愿意多消耗额度时。 |
/agent | 查看和切换子智能体 | 让多个智能体并行工作后,想检查各自进度时。 |
/goal | 设置持续目标 | 任务步骤多,需要持续推进到明确完成标准时。 |
/export | 导出完整会话 | 把对话复制到剪贴板或保存成 Markdown 文件时。 |
/import | 从其他 Agent 导入 | 想带入 Claude Code 或 Cursor 的支持设置与近期工作时。 |
/plugins | 打开插件浏览器 | 从已配置的市场查找和安装插件时。 |
/worktree | 创建或浏览隔离工作目录 | 想并行试一个方案,又不影响当前项目文件时。 |
/new | 开新对话 | 当前对话太乱,想重新开始但不退出 CLI。 |
/resume | 恢复旧会话 | 昨天做到一半,今天继续。 |
/quit | 退出 | 收工时用。 |
不要一口气背所有命令。你真的会高频用到的,前期就是 /plan、/diff、/review、/status。多智能体和 Fast mode 等真正需要时再开。
3.5 模型、Fast mode 和多智能体
截至 2026 年 9 月 30 日,复杂任务可以先试账号可用的 GPT-6.1 Sol,最难的工作再考虑 Astra。清楚的提取、分类等重复活可用 GPT-6 Luna。先用 /model 看当前账号有哪些选项,不要照抄无权限的型号。启动时也可以指定:
codex --model gpt-6.1-sol
/model:在当前会话里切换模型和推理强度。新型号的套餐和灰度限制见 最新模型说明。/fast:切换受支持模型的 Fast 模式,用更多额度换速度。额度倍率不是速度倍率;Astra Ultrafast 也不是 Ultra 多智能体,详见 官方速度说明。/agent:查看并切换正在运行的子智能体线程。你也可以直接要求 Codex 停止或调整某个子智能体。
每个子智能体都会单独使用模型和工具,所以多智能体通常更耗额度。它们会继承当前会话的权限和沙盒,不会因为分工就自动扩大访问范围。
gpt-6-sol 和 gpt-6-luna。工作区默认值、自定义智能体和定时任务里写死的旧模型要一起检查,不要只改眼前这条会话。2026 年 8-9 月新增的会话与 Agent 管理工具
下面覆盖会话导出、任务 dashboard、消息队列、Worktree 和插件刷新等能力。安装示例于 2026-10-08 更新到 10 月 7 日发布的 0.161.0。npm 用户先升级并确认版本;用其他渠道安装的,沿用原渠道更新,不要混装:
npm install -g @openai/codex@0.161.0 codex --version
| 功能 | 怎么操作 | 为什么有用 |
|---|---|---|
| 导出 | 在 TUI 输入 /export | 把完整对话复制出去或保存成 Markdown，方便交接和复盘。 |
| 分叉 | 使用 codex exec fork；先运行 codex exec fork --help 查看当前版本参数 | 保留原会话，同时尝试另一条实现路线。 |
| 归档 / 恢复 | 在 TUI 的 Resume 会话选择器里操作 | 把暂时不用的会话收起来，需要时再恢复。 |
| Agents dashboard | 运行 codex agents | 搜索、启动、打开、重命名或停止本地和远程任务。 |
| 消息队列 | 运行 codex queue | 给已经存在的会话排入下一条消息,不用先打开它。 |
| 工作目录 | 在 TUI 使用 /cd、/pwd 或 /cwd | 查看或切换当前工作文件夹,减少改错项目。 |
| 增强诊断 | 运行 codex doctor | 排查终端防护软件、网络/代理、桌面端状态和更新连接。 |
| Worktree | 启动时用 --worktree,或在 TUI 输入 /worktree | 为新任务或分叉任务创建隔离的 Git 工作目录;0.156 起默认开启支持。 |
| 运行中提问 | 在问题卡片选择建议答案,或输入自己的回答 | Codex 继续工作的同时回答澄清问题,不丢掉主输入框草稿。 |
| 插件 | 输入 /plugins 安装,或使用 codex plugin | 0.154.0 起当前会话通常会刷新插件工具、Skills 和 Hooks。 |
| 增强复制 | 使用 /copy | 复制回复、状态输出或单项会话信息,粘贴到富文本软件时保留更多格式。 |
| 导入 | 在空闲的本地会话输入 /import | 从 Claude Code 或 Cursor 导入最多 30 天内的 50 条近期聊天及支持设置。 |
/import 在任务正在运行、远程会话或连接本地 app-server daemon 时不可用。0.147 还加入 --approve-for-me 自动审查审批;它会改变批准流程,新手先保持默认审批,熟悉风险后再考虑。旧的 codex mcp-server 已在 0.154.0 移除,嵌入式集成改用 Codex App Server;日常管理 MCP 连接仍使用 codex mcp。
10 月新增:会话内登录 MCP,选对语音设备
工具提示未登录:在 Codex 输入框用 /mcp 找到已配置的服务,再输入 /mcp login <name>,把 name 换成实际服务名。跟着授权提示完成登录,回来先试读取。不是在普通终端里直接运行斜杠命令,也不是用它安装插件。见 MCP 登录步骤。
听不到、说了没反应:打开 /voice settings,分别检查麦克风、扬声器和麦克风输入通道。0.161.0 支持把这些选择保存在本机,外接声卡或换耳机后尤其值得检查。收音设备与回答的声音是两回事。
- 先确认终端有系统麦克风权限,再选择实际连接的设备。
- 按 F8 开始短测试,说“只复述我刚才说的话,不要运行命令”。
- 确认输入和播放都正常后,再用语音交代任务。别通过放开文件权限来解决收音问题。
0.160 / 0.161 还改善了断线后的消息队列和历史恢复。重新连接后先看任务有没有完成,再决定重发,尤其是提交、发信和部署。更多版本边界、Daybreak 与恢复步骤见 10 月更新专章。依据:官方发布记录。
0.158 / 0.159:复制、插话和升级后的小变化
| 变化 | 你怎么用 | 别误会 |
|---|---|---|
| 复制保留格式 | 在终端会话中选择一段含列表或表格的回复,粘贴到文档里检查。 | 复制和右键行为仍取决于终端设置,重要内容贴完再核对。 |
| 主动启用的 instant_interrupt | 支持时,新输入可以在模型回复或较长工具执行期间调整方向。 | 不是默认开启,也不保证撤销已经发生的写入。涉及删除或上线,直接暂停并确认状态。 |
| 警告查看器 | 看完关闭会移除已查看的警告;想保留某条时按 k。 | 收起警告不等于问题已经修好。 |
| 输入和登录更稳 | 新空会话切换任务时保留草稿;登录时也可以复制登录链接。 | 授权要在自己的浏览器完成,不要把验证码或凭据发给别人。 |
| Windows 闪窗修复 | 0.159.2 改善后台命令启动时弹出控制台窗口的问题。 | 仍有闪窗先确认实际运行版本,不要直接关闭系统安全功能。 |
0.158 还支持明确要求图片使用透明背景,并改进部分 MCP OAuth 连接。配置这类连接前先看服务商要求,不要把 client secret 放进公开教程、聊天截图或 Git 仓库。
两个旧入口已移除:自动追问建议及 tui.prompt_suggestions 设置,还有随 CLI 打包的 plugin-creator 技能。看不到它们不是安装损坏。要做插件,使用当前 插件开发文档,不必反复重装找旧技能。版本依据:0.158 / 0.159 更新记录。
语音已默认开启支持,不必照旧教程找实验开关
0.156 起语音会话默认开启支持,不再沿用 0.155 的实验开关步骤。在支持的终端会话按 F8 切换语音,用 /voice settings 选择声音。功能默认支持不等于麦克风已经获得系统授权。
- 先用
codex --version确认运行的是更新后的版本。 - 检查终端的系统麦克风权限;F8 被系统占用时,检查功能键设置或使用会话里的语音入口。
- 试一句“只读介绍这个项目,不要改文件”,再核对转写和结果。
- 涉及删除、发送或上线时,仍检查具体操作和审批内容。
同一轮也加入了 /tui 全屏界面选择、/usage 用量面板和 /daemon 后台服务管理。先用 /usage daily 只查看一天的用量,不必领取或消耗任何重置。纯 App 用户不用为这些终端功能额外安装 CLI。依据:0.156 发布记录、CLI 用量命令。
codex agents 的任务总览增加了隐藏、归档、删除和 Worktree 归属信息。整理列表先用隐藏或归档;删除托管 Worktree 前看清路径和归属,确认改动已保存。支持的 Mac 本地终端会话还可对 MCP 请求做 Touch ID 验证,它和服务登录、工具写入审批不是一回事。
0.155.1 修复的是推理摘要默认设置,不是“让模型不思考”。遇到服务商不支持摘要的报错,先升级;你手动设置过的摘要选项仍会保留,因此也要检查配置。官方 0.155.0 / 0.155.1 记录
进阶用户若使用后台 app-server daemon,可先看 codex app-server daemon update --help,再决定是否更新。普通 CLI 用户无需为语音单独配置后台服务。切换账号后,旧身份的远程会话和缓存会失效,应按新账号重新核对连接。
模型也要一并检查:Spark 已在 9 月 14 日停用;ChatGPT 登录的 GPT-5.5 将在 10 月 14 日退役。按 模型迁移清单 检查默认值、任务与脚本。
3.6 一次会话的健康长度
Codex 的会话越聊越长,上下文会越来越复杂。长到一定程度,它可能开始变得迟钝或跑偏。
出现这些信号,就该考虑 /new 或重新开一个任务:
- 它连续两三次犯同一个错。
- 你已经换了目标,但它还抓着旧目标不放。
- 它开始给很长的解释,但实际改动很少。
- 你自己也说不清这条对话现在到底在做什么。
重开不是失败。就像整理桌面一样,有时候清空一下反而更快。
3.7 中断、撤回、重来的三件套
你需要会三种“刹车”。
| 动作 | 通俗理解 | 场景 |
|---|---|---|
| Esc 或取消当前输入 | 我这句话不发了 | 还没提交给 Codex 时。 |
| Ctrl+C | 先停一下 | 命令跑太久、方向明显不对时。 |
| Git 回退 | 回到保存点 | 文件已经改坏,需要撤销时。 |
最稳的习惯是:每完成一个小阶段就提交一次。这样你永远有地方可退。
3.8 给项目留下"长期记忆"
如果你发现自己反复提醒 Codex 同一件事,就该把它写进 AGENTS.md。
AGENTS.md 可以理解成“项目里的工作说明”。每次 Codex 进入这个项目时,都会先读这些规则。比如:
# AGENTS.md ## 写作风格 - 面向零基础读者,用口语化中文解释。 - 先讲用途,再讲步骤,避免堆术语。 ## 修改规则 - 不要引入构建工具。 - 保持纯 HTML/CSS/JS。 - 修改后检查站内链接和 HTML 结构。
你可以用 /init 让 Codex 生成一个初稿,再让它根据你的项目补充。
3.9 新手日常工作流
把本章内容合起来,你日常可以这样用 Codex CLI:
- 进入项目文件夹,运行
codex。 - 先说目标,如果任务复杂就用
/plan。 - 确认计划后让它改一小块。
- 用
/diff或 Review 面板看改动。 - 在浏览器或终端里检查结果。
- 满意后让 Codex 帮你提交保存点。
- 任务结束前让它总结改了什么。
- 在你的项目目录里启动 Codex。
- 把权限切到只读或明确告诉它先不要改文件。
- 让它解释项目结构并给三步建议。
- 用
/status看当前会话状态。