Codex CLI 使用
CLI 适合把工作目录、权限、输入和输出写得明确。它既能进行交互开发，也能用 `exec`、`review` 和结构化输出接入脚本。
当前实测版本：codex-cli 0.144.3 · 模型基线 gpt-5.6 · 核对日期 2026-07-15
安装、更新与诊断
使用 npm：
npm install -g @openai/codex
codex --versionmacOS 使用 Homebrew：
brew install --cask codex
codex --version更新前先确认你原来的安装方式；不要同时混用多个全局安装来源。
codex update
codex doctor --summarydoctor 检查安装、配置、认证和运行时状态；需要机器可读且脱敏的结果时使用 codex doctor --json。
登录与计费边界
交互式登录默认打开 ChatGPT 登录流程：
codex login
codex login status无浏览器或远程终端可以使用 device auth。该登录方式当前为 Beta，流程可能继续调整；失败时回到交互式登录或按组织批准的认证方式处理：
codex login --device-auth使用 OpenAI Platform API Key 时通过标准输入传递，不把 Key 写进 shell 历史：
printenv OPENAI_API_KEY | codex login --with-api-key
codex login status- ChatGPT 登录：使用 ChatGPT 订阅与工作区能力，遵循对应的管理员、保留和数据策略。
- API Key 登录：按 OpenAI Platform API 标准用量计费，遵循 API 组织的数据设置；部分 ChatGPT 能力不可用。
- Codex Cloud：只支持 ChatGPT 登录。API Key 可以用于本地 App、CLI 和 IDE 工作，但不自动获得 Cloud、连接器或 ChatGPT 工作区能力。
共享电脑使用结束后运行 codex logout。不要在文档、截图、命令参数或仓库文件中出现 Key。
选择当前模型
交互会话中使用 /model；启动时可以用 --model / -m 一次性覆盖：
codex --model gpt-5.6
codex exec -m gpt-5.6 "审查当前未提交修改并列出证据"gpt-5.6 是指向 gpt-5.6-sol 的当前别名。默认 Power 使用 Sol 和 Medium reasoning；日常任务可选 Terra，清晰且高吞吐的任务可选 Luna。先从默认推理强度开始，只有复杂任务确实需要更深规划时再提高。
使用 ChatGPT 登录时，gpt-5.2 和 gpt-5.3-codex 已弃用。API Key、自定义 model_provider 或第三方网关可能有不同模型清单；这时应使用该提供方实际公布并验证可用的 ID，不要假设别名映射完全相同。
第一次交互会话
从仓库根目录启动：
cd /path/to/project
codex或从任何位置明确目录：
codex -C /path/to/project建议第一个任务只读：
先不要修改文件。读取 AGENTS.md 和项目入口，报告：
- 当前目录、分支和未提交修改；
- 安装、测试、类型检查和构建命令的来源；
- 本任务最小需要访问的文件；
- 仍不能确认的前提。正常结果应包含具体文件证据，没有新增 diff。若 Codex 把 README 当成唯一事实，要求它继续检查实际配置和测试文件。
当前命令地图
| 命令 | 适用场景 |
|---|---|
codex | 启动交互会话 |
codex exec | 非交互执行一次任务，可输出 JSONL 或结构化结果 |
codex review | 非交互审查当前仓库的未提交、分支或提交 diff |
codex resume | 恢复已有会话；--last 继续最近一次 |
codex fork | 从历史会话复制上下文，开始独立分支 |
codex mcp | 管理 MCP 服务 |
codex plugin | 管理插件 |
codex app | 启动桌面 App；缺失时按当前 CLI 行为打开安装流程 |
codex cloud | 浏览 Codex Cloud 任务并把改动应用到本地，当前 CLI 标为实验能力 |
codex doctor | 检查安装、配置、认证和运行时健康状态 |
工作目录与附加目录
-C 决定主要工作根目录；--add-dir 会额外开放可写目录。
codex -C ./apps/web
codex -C ./apps/web --add-dir ./packages/shared只在任务确实跨目录时增加范围。不要为了省一次审批直接开放仓库上级目录、整个用户目录或包含多个客户项目的位置。
Sandbox 与 Approval
两个设置解决不同问题：
- sandbox：命令可以访问哪些文件，以及是否能使用网络。
- approval：什么时候必须由你确认。
| Sandbox | 适合 | 风险 |
|---|---|---|
read-only | 调研、架构梳理、审查 | 不能直接修改；某些工具仍会尝试写缓存 |
workspace-write | 日常开发 | 可以写工作区，仓库范围仍需检查 |
danger-full-access | 外部已经严格隔离的临时环境 | 可访问范围大，不适合普通本机默认值 |
| Approval | 行为 |
|---|---|
untrusted | 只有受信任的读取类命令可直接运行，其他动作请求确认 |
on-request | Codex 按动作和上下文决定何时申请确认 |
never | 不弹审批，失败直接返回给 Codex；不等于自动获得更高权限 |
一次性覆盖示例：
codex -s read-only -a untrusted
codex -s workspace-write -a on-requestworkspace-write 下 spawned commands 默认不能联网；确需网络时可以在配置中明确开启：
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = trueWeb search 是另一套控制面：普通本地任务默认使用 OpenAI 维护的 cached 搜索结果；codex --search 或 web_search = "live" 开启实时搜索，并且不会为每次搜索单独弹审批。例外是 --yolo 或其他 full-access sandbox 设置，此时 Web search 默认改为 live；若仍要限制为缓存结果，必须显式设置 web_search = "cached"。不要把“命令不能联网”误解为“Web search 已关闭”，也不要为了联网直接切到 danger-full-access。
DANGER
--dangerously-bypass-approvals-and-sandbox 同时绕过审批和 sandbox。只有容器、虚拟机或专用 runner 已经隔离文件、网络与凭据时才考虑使用，不能写进普通开发机的别名或团队快速开始。
会话中的高频操作
输入 / 查看当前版本实际支持的命令。常用入口包括：
| 命令 | 作用 |
|---|---|
/status | 检查模型、目录、权限和上下文状态 |
/model | 选择当前可用模型和推理设置 |
/permissions | 查看或调整当前权限策略 |
/plan | 先调查和规划，再决定是否实现 |
/diff | 查看工作区修改 |
/review | 选择范围并启动专门代码审查 |
/compact | 压缩长会话，保留关键事实和未完成项 |
/mcp | 查看 MCP 服务和工具状态 |
/init | 生成或完善项目 AGENTS.md 初稿 |
/agent / /subagents | 查看并切换主任务和子代理线程 |
命令会随版本和已安装能力变化。手册列的是高频入口，不代替你本机的 / 菜单。
图片输入
启动时附加截图：
codex -i screenshot.png \
"解释这个错误，先定位对应组件和日志，再提出最小修复"对比两个状态：
codex --image before.png,after.png \
"比较两个界面，只报告可验证的布局和交互回归"发送前裁掉邮箱、账号、文件路径、浏览器标签、通知和 Key。图片能提供可见状态，但不能证明网络请求、数据库或不可见组件内部状态。
恢复、分叉和清理会话
codex resume
codex resume --last
codex fork
codex fork --last
codex archive SESSION_ID
codex unarchive SESSION_ID- resume 继续同一任务，适合目标和仓库没有变化。
- fork 复制已有上下文后走另一条方案，避免两个方向混在一个历史里。
- archive 从活跃列表中归档会话但保留记录；unarchive 将它恢复。
- delete 永久删除会话记录及其后代会话。只有确认不再需要追溯时才运行
codex delete SESSION_ID；不要用--force做日常清理。 - 目标、仓库或信任边界已经改变时，直接开新会话通常更清晰。
恢复后先要求 Codex 重报当前目录、分支、diff 和未完成步骤，防止历史上下文与现实工作区脱节。
非交互执行
只读摘要：
codex exec -s read-only \
"概括仓库入口、测试命令和三个主要风险；引用文件，不修改"从标准输入追加日志：
npm test 2>&1 | codex exec -s read-only \
"找出最早根因，区分实现、测试和环境问题"输出事件流：
codex exec --json -s read-only \
"分析项目并输出过程事件" > codex-events.jsonl保存最终消息：
codex exec -s read-only \
-o codex-summary.md \
"输出架构摘要和风险，不修改文件"需要稳定机器接口时，用 --output-schema schema.json 限定最终结果结构；脚本仍需校验退出码、JSON 解析和必需字段，不能只相信自然语言内容。
非交互代码审查
codex review --uncommittedcodex review --base main
codex review --commit COMMIT_SHA
codex review "只报告可验证的 Bug、安全问题和缺失测试，按严重程度排序"--uncommitted、--base、--commit 和自定义 prompt 是互斥的审查范围。每个发现应包含文件位置、触发条件、影响和修复方向。高风险代码不要只把 git diff 管道给模型；应让审查在仓库内读取调用方、规则和测试。
自动化安全基线
非交互任务至少满足：
- 固定可信工作目录，并在运行前检查 Git 状态。
- 默认
read-only；确需修改时使用workspace-write和最小附加目录。 - 使用短期、最小权限凭据，日志和产物不得输出 Token。
- 限制网络目标和外部服务权限。
- 校验退出码、结构化输出和最终 diff。
- 不让任务自动提交、推送或发布，除非该外部 runner 已有独立审批和回滚机制。