Codex CLI 命令速查表 - OpenAI 终端编码代理全参数
Codex CLI 是 OpenAI 官方开源的终端编码代理（Rust 实现），面向想在本地仓库直接驱动 GPT 系列模型改代码、跑测试并管理批准流程的开发者，也服务想用 AI 做自动化代码生成与审查的 CI 工程师。与纯云端聊天不同，它提供可细粒度控制的沙箱（read-only/workspace-write/full-access）与批准策略，并支持 codex exec --json 无头接入流水线；本表帮你快速掌握安装登录、非交互执行与沙箱批准的取舍。
典型使用场景
面向把 AI 编码能力接进日常开发和 CI 的工程师。Codex CLI 的两种用法要分清：交互式 TUI 适合探索和结对改代码，codex exec 非交互模式才是自动化流水线里真正该用的东西。本表重点覆盖三块：一是 codex exec 配合 --json / -o / --output-schema 做结构化输出，供脚本消费；二是 -s 沙箱与 -a 批准模式的四档组合怎么按风险选；三是 MCP 服务器的增删查，便于把内部工具接给模型。会话管理（codex resume / fork / apply）也在内——把上一轮上下文接着用，比每次重述背景省时间。
安装与认证 7
npm install -g @openai/codexbrew install --cask codexcodex --versioncodex logincodex login --with-api-keycodex login --device-authcodex logout交互模式 5
codexcodex "解释这个代码库"codex --search "修复登录 bug"codex -i ./screenshot.png "实现这个 UI"codex --oss非交互执行（codex exec） 5
codex exec "修复失败的测试"echo "重构 utils" | codex exec --osscodex exec --json "列出所有 API 端点"codex exec -o result.txt "总结架构"codex exec --output-schema '{...}' "提取配置"会话管理 5
codex resumecodex forkcodex applycodex --restorecodex --history模型与配置 5
codex -m gpt-5.4 "复杂任务"codex -p openai "生成组件"codex -C /path/to/repocodex -ccodex completion bash沙箱与批准模式 8
codex -s read-onlycodex -s workspace-writecodex -s danger-full-accesscodex -a untrustedcodex -a nevercodex --full-auto "完成实现"codex --yolo "紧急修复"codex --dangerously-bypass-approvals-and-sandboxMCP 与 Codex Cloud 7
codex mcp listcodex mcp add -- <args...>codex mcp add --url https://example.com/mcpcodex mcp get <name>codex mcp remove <name>codex cloud exec --env "任务"codex cloud exec --env --attempts 3 "任务"交互斜杠命令 12
/clear/compact/new/fork/diff/status/init/review/plan/model/permissions/exit参数矩阵
| 参数 | 作用 | 示例 |
|---|---|---|
exec | 非交互模式执行一次性任务（别名 codex e） | codex exec "修复失败的测试" |
--json | 输出 JSONL，便于脚本解析 | codex exec --json "列出所有 API 端点" |
-o <file> | 把最终回答写入文件 | codex exec -o result.txt "总结架构" |
--output-schema <json> | 用 JSON Schema 约束输出结构 | codex exec --output-schema '{}' "提取配置" |
-m <model> | 指定模型 | codex -m gpt-5.4-mini "复杂任务" |
-C <dir> | 设置工作根目录（--cd） | codex -C /path/to/repo |
-p <profile> | 加载命名配置 profile | codex -p openai "生成组件" |
-c | 临时覆盖 config.toml 中的配置值 | codex -c model_reasoning_effort="high" |
-s read-only | 沙箱只读，默认最安全 | codex -s read-only "审计依赖" |
-s workspace-write | 沙箱可写工作目录 | codex --full-auto "完成实现" |
-a never | 从不弹批准，适合只读探索 | codex -a never -s read-only |
--full-auto | 自动批准：workspace-write + on-failure | codex --full-auto "完成实现" |
--search | 启用实时网络搜索 | codex --search "修复登录 bug" |
-i <img> | 附带图片（可逗号分隔多张） | codex -i ./shot.png "实现这个 UI" |
--oss | 使用本地开源模型（Ollama 等） | echo "重构 utils" | codex exec --oss |
mcp list / get / remove | 管理已配置的 MCP 服务器 | codex mcp list |
mcp add --url <url> | 添加 HTTP 类型 MCP 服务器 | codex mcp add --url https://example.com/mcp |
cloud exec --attempts <n> | 提交 Codex Cloud 任务并指定重试次数（1-4） | codex cloud exec --attempts 3 "任务" |
易错点与避坑指南
现象自动化脚本里拿不到模型的回答，只有空输出或一段人类可读文本
原因交互模式（TUI）把回答打在终端界面上，没有给非调用方留结构化出口。
处置改用 codex exec --json，按 JSONL 逐行解析；需要纯文本时用 -o 文件 落到文件里再读。
现象任务中途卡住，一直等确认，或在没有网络的环境里装依赖失败
原因默认沙箱是只读、批准模式是逐条确认，联网行为在沙箱内被禁掉。
处置需要装依赖就跑 --full-auto；只在可信环境考虑 --yolo，并优先用 -a never -s read-only 做纯只读调研。
现象任务总是「只说不做」，文件没被改动
原因当前处于 plan/只读探索模式或沙箱是 read-only，写文件请求会被直接拒绝。
处置用 /plan 之外先退出只读模式，执行阶段改用 -s workspace-write 或 --full-auto。
现象每次都要重复交代项目背景和编码规范
原因会话是无状态的，约定没有落盘。
处置把项目约定写进根目录或 ~/.codex/ 下的 AGENTS.md，Codex 会自动合并加载。
现象长会话越聊越慢、token 消耗过快，回答质量下降
原因对话历史一直累积，没有压缩。
处置会话内用 /compact 总结压缩，或 /clear 重置；/status 可先看当前用量。
现象接了 MCP 服务器但工具列表里看不到
原因服务器配置缺失、名称写错，或需要重新加载会话。
处置用 codex mcp list 确认已注册、codex mcp get <name> 看配置，再 /new 开新会话让工具重新载入。
现象改了文件但没进版本控制，review 时一片混乱
原因工作区改动没有走 git 流程，/diff 只看 diff 不负责提交。
处置会话内用 /diff 先看清改动范围，再自行提交；也可用 codex apply 把最新 diff 应用为 git apply。
排障路径
1确认安装与登录状态
codex --version先确认 CLI 在 PATH 中且能输出版本号；无头/SSH 环境用
codex login --device-auth完成登录。2把单次任务的完整回答落到文件便于审阅
codex exec -o /tmp/result.txt "总结架构"执行完读 /tmp/result.txt，能确认模型确实产出了内容，而不是静默失败。
3让输出可直接被脚本消费
codex exec --json "列出所有 API 端点"输出为 JSONL，逐行 json.loads 即可；管道场景注意不要混入非 JSON 的横幅信息。
4排查 MCP 服务器是否注册成功
codex mcp list列出的每个名字对应一条配置，配合
codex mcp get <name>查看完整参数。5管道输入 + 本地模型的最小验证
echo "重构 utils" | codex exec --oss这条同时验证了非交互输入通道与本地模型连通性，两步里任一失败都能立刻定位。
6生成补全脚本以确认子命令与标志可用
codex completion bash把输出的补全脚本 source 进当前 shell，即可用 Tab 补全确认已安装版本支持哪些子命令与标志。
命令示例
非交互执行并输出 JSON
codex exec --json "列出项目里所有 API 端点"
codex exec -o endpoints.txt "总结架构"codex exec（别名 codex e）是非交互事实标准，--json 输出 JSONL，-o 把最终回答存为文件。
输出
{"findings":{"endpoint_count":23,"categories":[...]}}
（最终回答同时写入 endpoints.txt，JSONL 便于 CI 解析）全自动完成实现
codex --full-auto "补齐 payment 模块的单测，改动前先看现有测试风格"默认 --full-auto 等价于 workspace-write 沙箱 + on-failure 批准，安全且省心，是日常首选。
输出
（模型在禁用网络的沙箱内自行读写工作目录，仅在需要联网装依赖时才退出沙箱询问）
只读探索大仓库
codex -a never -s read-only "这个项目的构建流程和依赖拓扑是怎样的"适合审计、调研、理解历史演进；如需写文件再切回 workspace-write 并加批准。
输出
（只读模式可读取全系统文件，不落任何修改、不弹确认）
添加 MCP 服务器
codex mcp add -- npx -y @modelcontextprotocol/server-github
codex mcp list__ 之后的所有参数原样传给服务器，可让模型在会话里直接调用仓库/工具接口。
输出
Added MCP server "server-github" (stdio)
常见坑与注意事项
- --dangerously-bypass-approvals-and-sandbox 会完全绕过沙箱与批准，模型能直接改系统和执行任意命令，仅在隔离容器或一次性环境使用；--yolo 也类似，务必看清语义再用。
- 用 -a never + -s read-only 才真正是"只读"；单用 -a never 但沙箱可写时，模型仍能修改工作目录内文件。
- 你把权限提示词写进 AGENTS.md（如"每次改动先跑测试"）会让 Codex 默认遵守团队约定，但也会固化行为——改动记忆文件前确认影响。
- codex exec 的非交互话单默认没有人在批准，执行有副作用的命令要靠沙箱（workspace-write 限制写范围）兜底，别依赖 -a 逐条确认来兜底自动化。
提示
- 非交互自动化一律用
codex exec+--json，配合 CI 流水线做代码生成/审查，是 Codex 的招牌用法。 - 默认
--full-auto会在网络禁用的沙箱内自动批准，安全且省心；需要联网装依赖时才会退出沙箱询问。 - 把项目约定写进 AGENTS.md（根目录或 ~/.codex/），Codex 会自动合并加载，比每次在提示词里重复更高效。
- 只读探索用
-a never -s read-only，既不弹确认又能读全系统文件，适合审计/调研类任务。
常见问题
codex exec 和直接跑 codex 有什么区别？
codex 是交互式 TUI，需要人在回路里确认；codex exec 是非交互模式，给一条指令就跑完并退出，适合脚本和 CI。加 --json 输出 JSONL 便于程序解析，加 -o result.txt 把最终回答存文件，加 --output-schema 用 JSON Schema 约束输出结构。做自动化时不要用交互模式。
沙箱和批准模式该怎么搭配才安全？
沙箱（-s）决定文件系统的可达范围：read-only 最安全，workspace-write 允许改当前目录，danger-full-access 完全放开。批准模式（-a）决定什么时候停下来问你：untrusted 逐条确认，never 从不问。生产环境建议 workspace-write 加 untrusted；只读探索用 read-only 配 never 最省事；容器里才可以考虑完全放开。
怎么把一次会话接着继续或派生分支？
codex resume 恢复上一次会话，codex fork 把上一次会话派生为一个新线程，两者的区别是后者会形成独立分支而不影响原会话。会话内还能用 /fork 克隆当前对话，/new 在同一会话里开一个全新对话而不清空历史，/compact 则压缩对话释放 token 但保留上下文。
Codex CLI 怎么用本地开源模型？
加 --oss 参数，它会通过 Ollama 等本地运行时调用开源模型，配合 codex exec --oss 可以在无网络的环境里跑。想换模型用 -m 指定，比如 -m gpt-5.4 或 -m gpt-5.4-mini。本地模型能力通常弱于旗舰模型，复杂重构任务建议仍用在线模型。
怎么让 Codex 按 JSON Schema 输出？
codex exec --output-schema '...' "任务" 会用 JSON Schema 约束输出结构，适合要把结果喂给下游程序解析的场景。加 --json 可输出 JSONL 便于逐行处理，-o result.txt 则把最终回答直接写到文件。约束格式比在提示词里描述「请输出 JSON」可靠得多。
由 巧匠 维护
公开更新于 2026年8月5日，内容持续校对官方文档。