Codex CLI 使用教程：终端任务、代码审查与自动化入门（2026）

Codex CLI 是在终端中使用编码代理的一条路径，适合已经有本地项目、需要阅读代码、修改文件和运行测试的开发者。一次可靠的操作，应先确认工作目录和权限，再提出有边界的任务，最后用差异与测试判断结果。本文集中讲终端工作流，安装入口和编辑器操作另有专题。

需求梳理、公开代码解释可以先在 AIMirror GPT 中文站 或 AICNBox 中文 AI 入口 完成。但网页问答不等于 CLI，也不自动拥有本地文件与终端能力；真正执行前，仍要回到自己的项目环境核对。

更新日期：2026 年 10 月 24 日。命令依据本机 codex-cli 0.163.0-alpha.11 的帮助输出核对，只运行了帮助和版本查询，没有用本文示例发起付费模型任务。不同发行版参数可能变化，先以本机帮助为准。¹

一、准备好终端和项目，再启动 Codex

先在终端输入 codex --version 和 codex --help。前者确认可执行程序能启动，后者显示当前版本支持的命令；只看到版本号，不代表已经登录，也不代表项目依赖已经准备完成。尚未安装可先看 Codex 下载与安装指南，再回来继续。

本机帮助包含登录状态查询，可按下面的顺序检查。状态输出可能含账号信息，分享排错截图前先遮挡；不要把认证文件、完整日志或 API Key 发到公开评论区。

codex --version
codex --help
codex login --help
codex login status

需要登录时按客户端提示完成官方流程，不购买共享账号或临时凭证。本文不列固定套餐价格，也不保证某个账号能使用全部模型；认证、配额和地区支持应在当前官方页面与自己的账号中确认。第三方 API 接入另看 协议、配置与排错专题。

二、选对工作目录，避免读错仓库

终端当前目录会影响工具看到的文件。进入目标项目后先看 pwd、git status --short 和 README，确认目录、已有修改与项目用途；不要从个人主目录直接发出“帮我整理所有文件”之类范围过大的指令。

本机 CLI 支持 -C 指定工作根目录。下面的路径是示例，需要换成自己的绝对路径；目录名包含空格时保留引号，避免被终端拆成多个参数。

codex -C "/absolute/path/to/project" --sandbox read-only "只读 README，说明项目用途和测试入口，不修改文件。"

启动后再次核对它引用的文件。说明内容来自别的项目、找不到 README，或者把上次任务的路径带进来时，先纠正目录，不要继续授权修改。多仓库任务更应逐个确认边界，不能把可以读取理解为可以写入所有目录。

三、交互任务、非交互执行和审查怎么选

交互模式适合需求还需讨论、修改过程中可能确认细节的任务。exec 适合目标明确、输出约定清楚的批处理；review 适合先发现问题而不是立即修复。把不同用途分开，能避免一次审查顺手变成大规模重构。

执行前分别运行子命令的 --help，不要把网上旧参数直接粘贴进生产脚本。尤其是会绕过审批或沙箱的参数，不应作为“解决一切报错”的默认配置；先查清失败是权限不足、环境缺失还是任务本身不合理。

四、先做一个只读分析任务

首次使用 Codex CLI，建议让它检查 README 与项目脚本是否一致。这个任务不要求装依赖，也不要求访问外部服务，适合验证它能否找到正确文件、给出证据，并承认不确定的地方。

codex --sandbox read-only "只读检查 README 和项目脚本：列出启动、测试与构建方式，说明依据的文件。不安装依赖，不修改文件，不执行网络请求。"

“只读”限制文件写入，但不等于网络隔离或资料不会发送给模型。仍应使用公开练习项目，明确禁止无关网络请求，并核对客户端策略；涉及私密源码时，先确认组织允许使用的服务和数据处理范围。

验收时看三个方面：引用的文件真实存在，命令确实出现在项目配置中，缺少的信息被标为待确认。它说“可以运行测试”与已经运行测试是两回事，下一阶段应单独验证。需要更完整的任务拆解，可回到 Codex 使用总教程。

五、授权小范围修改，始终保留人工检查

理解项目后，再挑一个小问题实施，例如修复文档中的安装步骤，或为现有函数补边界测试。先记录 git status --short，辨认已有改动；必要时按团队流程建立任务分支，不要为了得到干净工作区删除别人的内容。

以下示例启用工作区写入并保留按需审批。提示词说明不提交、不推送、不装依赖，执行范围仍需结合实际策略与出现的审批请求判断。

codex --sandbox workspace-write --ask-for-approval on-request "只修正 README 中与项目脚本不一致的测试说明。先给方案；不修改业务代码，不安装依赖，不提交或推送。完成后说明每处改动及依据。"

完成后检查状态和差异，再打开相关文件。普通 git diff 不包含未跟踪文件的内容，因此新文件要另外审阅；改动超出约定范围时，先要求说明并收缩，不要因为模型已经写完就全部接受。

git status --short
git diff --stat
git diff --check
git diff

审批只是执行前的一道控制，不是对代码正确性的保证。测试命令也可能安装包、访问网络或修改快照，确认其影响后再运行；“让它自己决定”不应替代项目负责人的验收。

六、用 review 审查差异，不把意见当成结论

本机帮助支持审查未提交改动，也支持与指定分支比较。先确认比较对象：--uncommitted 包括暂存、未暂存和未跟踪改动，可能包含别人的工作；只有在目录范围和数据权限都清楚时才使用。

codex review --help
codex review --uncommitted

审查输出应给出文件、触发条件、可能后果和验证办法。对每条问题都尝试复现，不能把“存在风险”自动等同于真实缺陷；反过来，没有发现问题也不意味着已经安全，仍需测试和人工阅读。

需要比较分支时，使用本地确实存在的分支名，并核对基线。不要凭习惯认定远程叫 origin、主分支叫 main；错误基线会让审查遗漏相关改动或混入无关提交。

七、非交互执行从只读报告开始

将重复任务放进脚本前，先明确输入是什么、输出存在哪里，以及失败时是否允许继续。最简单的练习是生成一份公开项目说明检查报告，不涉及写业务代码或自动发布。

codex exec --sandbox read-only -o codex-summary.txt "只读检查 README，列出三项有文件依据的改进建议。不修改项目，不安装依赖，不执行网络请求。"

-o 会由 CLI 把最终回答写入指定路径，应使用新的输出文件名，避免覆盖已有内容。“只读沙箱”约束模型执行环境，不代表客户端完全不写输出文件；报告也应检查是否包含不该分享的代码、路径和账号信息。

需要处理结构化事件时再考虑 --json，本机帮助说明它输出 JSONL 事件流，并不是一个可以直接当作业务结果的单独 JSON 对象。自动化脚本要分开检查进程退出状态、工具执行结果和业务验收，不应凭最后一句“完成”触发部署。

八、终端常见问题按层排查

中断、恢复与重复执行

任务被打断后，先检查当前差异和运行中的进程，再考虑恢复会话。中断对话不代表已经启动的测试、开发服务器或构建进程都停止了；重新执行前核对状态，避免两个任务同时写同一份输出。需要结束进程时先确认归属，不要按照一个常见进程名批量终止其他项目。

使用 resume 前先看本机帮助，确认恢复的是哪次任务。继续时补充“上次已经完成什么、当前还剩什么、哪些文件不能动”，并要求先只读核对现场。恢复的聊天记录可能早于最新文件，不能把旧结论当成当前事实；验收仍以工作区和最新测试结果为准。

自动化任务还要设计重复执行的后果。报告输出可以使用新的文件名，业务改动则应先判断目标状态是否已经达到；涉及提交、上传或数据库写入时，不应把请求超时直接理解为没有执行。先查目标系统状态，再决定是否重试。失败记录保留阶段和脱敏错误，不在重试日志里输出凭证。

每次只改一个变量，再执行同一个最小任务复核。安装、认证、模型路由和项目依赖是不同层，不要同时更换它们；否则即使恢复，也无法知道原因，下一次故障很难重现。

分享排错信息时保留版本、子命令、脱敏报错和发生阶段。不要贴 API Key、认证文件或完整环境变量列表；服务端报错也可能带请求内容，需要先检查。若涉及第三方网关，另外确认模型 ID、基础地址和协议兼容性。

九、把可复用经验留在项目里

交接脚本时注明执行目录和所需环境，避免同事从错误位置直接运行。

经常重复的目录、命名和测试要求，可以写入 AGENTS.md 与提示词规则。一次性目标保留在任务消息中，临时失败记录放在交付摘要里；不要把每次聊天都堆进长期规则，反而让关键约束更难找到。

在编辑器里更方便检查代码的人，可以改看 VS Code 使用教程，不必因为选了 CLI 就坚持所有工作都在终端完成。工具入口可以变化，工作目录、差异审查、测试与授权边界应保持一致。

建议从一个公开 README 检查任务开始，随后完成一次小修改和人工审查。需求难以描述时，可先用 AIMirror GPT 中文站 整理成清楚的验收条件，再回到 Codex CLI 实施，而不是靠更长的命令替代明确的需求。