Codex CLI 使用教程：安装、常用命令与第一次修改项目
更新日期：2026 年 10 月 24 日。本文命令按 2026 年 10 月本机 Codex CLI 帮助与官方 GitHub 文档核对。CLI 更新较快，请以
codex --help和当前官方说明为准。
Codex CLI 是在本地终端运行的编程智能体。安装后，它可以在你指定的工作区中读取代码、执行命令、修改文件、运行测试并生成审查结果。它的价值来自“能操作项目并验证”，所以第一课是限定范围、检查差异，再逐步扩大任务，而不是一上来就要求它重写整个仓库。
这篇教程先带你完成安装、登录和第一次修改，再解释交互模式、非交互模式、审查、恢复、诊断与安全参数。第一次接触 Codex 的完整路线可先看 Codex 使用教程总览。
安装与版本检查
macOS 或 Linux 使用官方安装脚本：
curl -fsSL https://chatgpt.com/codex/install.sh | shWindows 11 使用 PowerShell：
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"也可以用包管理器安装：
npm install -g @openai/codex
brew install --cask codex检查命令是否可用：
codex --version
codex doctor --summarydoctor 会检查安装、配置、认证和运行环境。需要提交诊断信息时，可用 codex doctor --json 生成更适合工具处理的结果；发送给他人前仍要检查其中是否包含你不想公开的路径或环境信息。
登录与账号
运行 codex 后选择 Sign in with ChatGPT。官方推荐使用具备 Codex 权益的 ChatGPT 套餐，API Key 使用方式则需要额外配置。检查登录状态：
codex login status无法完成浏览器回调时，可尝试：
codex login --device-auth退出登录使用 codex logout。不要将 Cookie、访问令牌或 API Key 写进项目、脚本示例或 shell 历史。如果当前账号无法登录，先排查账号、网络、代理和组织策略，详见 登录失败与国内使用排查。
交互模式的基本流程
进入项目并启动：
cd /path/to/project
codex第一次会话可以要求只读分析：
只读检查项目，找出测试入口、构建命令、核心模块和潜在风险。
不要修改文件。确认理解后，再发一个边界清楚的任务：
把设置页的手机号校验改为可复用函数，并为有效、空值和错误格式补充测试。
不要修改后端 API，也不要升级依赖。
完成后运行该模块的测试并列出结果。Codex 可能询问是否执行命令。检查命令和目录后再批准。若它开始修改超出范围的文件，应停止并收紧任务，而不是继续批准更多权限。
常用启动参数
指定工作目录
codex -C /path/to/project只读模式
codex --sandbox read-only适合理解仓库、审查风险或让智能体只提供方案。只读不意味着绝对无风险：读取敏感文件、访问外部服务等仍需按任务边界管理。
工作区可写模式
codex --sandbox workspace-write这是多数日常改动的合理起点。写入被限制在工作区范围内，必要时再明确添加额外目录：
codex --add-dir ../shared-library额外目录会扩大可访问范围，只添加确实需要且来源可信的目录。
明确审批策略
codex --ask-for-approval on-requeston-request 允许智能体在需要时发起审批；never 表示不再请求人工批准。不要把 never 和“安全”混为一谈，普通开发任务尤其不要默认使用 danger-full-access。
启用联网搜索
codex --search只有任务需要最新网页信息时才开启。搜索结果也可能包含错误、过期内容或提示注入，引用前要核对来源。项目内的安全配置详见 Codex 配置与安全指南。
codex exec：一次任务跑完
codex exec 是非交互模式，适合脚本、定时任务或批处理：
codex exec "检查当前仓库的构建配置，找出 3 个可能影响 CI 的问题；不要修改文件"从标准输入读取任务：
cat task.md | codex exec -把最后一条回复写入文件：
codex exec "总结当前改动和验证结果" -o result.md需要机器读取事件时使用 --json：
codex exec --json "检查测试失败原因"非交互不等于可以省略安全控制。脚本运行时仍应指定工作目录、沙箱、审批与输出边界；无人值守任务不要把高风险开关当成省事配置。
用 JSON Schema 固定输出
需要让下游脚本稳定读取结果时，可以提供 JSON Schema：
codex exec --output-schema review-schema.json "检查改动并输出结构化结论"Schema 只约束最终结果的结构，不能保证结论一定正确。下游仍需校验必填字段、枚举值、退出码和业务规则。对涉及发布、转账、删除等动作的结果，应保留人工或独立规则复核。
审查未提交改动或提交
审查当前未提交内容：
codex review --uncommitted与某个基线分支比较：
codex review --base main审查指定提交：
codex review --commit <commit-sha>可以附加审查重点：
codex review --uncommitted "重点检查权限绕过、数据丢失和遗漏测试"审查命令适合发现回归，但它不是形式化证明。合并前仍要运行项目测试、检查关键 diff，并遵循团队评审流程。
恢复和分叉会话
继续最近一次会话：
codex resume --last打开会话选择器：
codex resume根据当前帮助，还可用 codex fork --last 从历史会话分叉，避免覆盖原任务。恢复会话时先确认工作目录和仓库状态，因为原会话之后项目可能已经被其他人修改。
更新与维护
更新 CLI：
codex update更新后检查：
codex --version
codex doctor --summary如果更新后配置不兼容，不要盲目删除整个配置目录。先保留原文件、查看错误信息，再按当前官方配置说明逐项调整。配置字段与安全策略见 配置与安全专题。
第一次项目修改的验收清单
git status --short
git diff
git diff --check
npm test把 npm test 换成实际命令。验收时检查：
- 只修改了任务允许的文件；
- 测试确实运行，失败没有被忽略；
- 没有提交
.env、密钥、缓存、日志或构建产物； - 新依赖有必要且锁文件变化可解释；
- 自动生成文件是否应按项目规则重新生成；
- 最终说明列出了未完成项和残余风险。
常见命令问题
codex: command not found
重新打开终端，检查 PATH 与安装日志。也可以运行 codex doctor。如果使用 npm 安装，确认 npm 全局可执行目录在 PATH 中，不要通过随意修改系统权限来绕过安装问题。
在错误目录启动了 Codex
先退出，再进入项目根目录启动，或用 codex -C /path/to/project。不要在工作区外直接授予全盘写权限来“修复”路径问题。
长任务中断
用 codex resume --last 继续。若只想复用思路又不想覆盖原任务，可以按当前版本支持的分叉命令创建新会话。
自动脚本卡住
先检查是否在等待审批、认证或交互输入。无人值守时明确审批和沙箱策略，设置外部超时，并避免让脚本执行不可逆操作。不要把 --dangerously-bypass-approvals-and-sandbox 直接塞进 CI。