Home

深色模式

Codex CLI ​

概述 ​

Codex CLI 是运行在本地终端中的 Coding Agent。它可以读取仓库、修改文件、执行现有开发工具，也可以通过非交互模式接入脚本和 CI。

截至 2026 年 8 月 19 日，CLI 的主路径已经不只是交互式 TUI。codex exec 负责自动化，codex review 提供独立代码审查，codex cloud 可以从终端操作云端任务。Skills、Plugins、Hooks、Goals 和多 Agent 也已经进入当前产品体系。

安装升级 ​

独立安装器 ​

OpenAI 官方页面目前优先展示 macOS 和 Linux 独立安装器：

sh
curl -fsSL https://chatgpt.com/codex/install.sh | sh

需要更新时可以重新执行同一条命令。已安装的发行版支持自更新时，也可以运行：

sh
codex update

npm ​

已经使用 Node.js 工具链时，可以继续通过 npm 安装：

sh
npm install --global @openai/codex

官方安装页还提供 Windows、Homebrew 和 npm 选项。安装渠道可能继续变化，以官方页面当前显示为准。

安装后检查版本并启动：

sh
codex --version
codex

认证方式 ​

首次运行 codex 时，可以在界面中选择登录方式，也可以直接执行：

sh
codex login

不带参数时会打开 ChatGPT OAuth 浏览器流程。远程服务器或无图形界面环境可以使用仍处于 beta 的设备码登录：

sh
codex login --device-auth

自动化环境也可以从标准输入提供 API key：

sh
printenv OPENAI_API_KEY | codex login --with-api-key

检查当前认证方式：

sh
codex login status

已登录时该命令退出码为 0。ChatGPT Enterprise 还可以为受信任自动化签发 Codex access token，但它不同于普通 Platform API key，不应在个人脚本里混用。

CLI、IDE extension 和 ChatGPT desktop app 会复用同一份本地 Codex 登录状态。凭据可能保存在系统 keyring，也可能保存在 ~/.codex/auth.json；后者包含访问令牌，不能提交到仓库或粘贴到工单。

交互模式 ​

直接运行：

sh
codex

也可以附带第一条任务：

sh
codex "Explain this repository and identify its main entry points"

交互模式适合连续完成调研、修改、验证和复查。当前 TUI 支持在任务执行时继续输入：

  • 按 Enter 将新指令注入当前 turn
  • 按 Tab 把 prompt、Slash command 或 shell 命令排到下一轮
  • 输入 @ 搜索文件并附加到 prompt
  • 以 ! 开头执行受当前权限约束的本地命令
  • 按 Ctrl+G 使用 VISUAL 或 EDITOR 打开长 prompt 编辑器

非交互模式 ​

codex exec 用于脚本、流水线和一次性任务：

sh
codex exec "summarize the repository structure"

它将执行进度写到 stderr，最终回答写到 stdout。与交互模式不同，codex exec 默认使用只读沙箱；需要修改工作区时应显式授权：

sh
codex exec --sandbox workspace-write "fix the build error and verify the result"

不希望保存本次 session 文件时使用：

sh
codex exec --ephemeral "review the current repository"

自动化程序可以读取 JSONL 事件，或单独保存最终回答：

sh
codex exec --json "inspect the repository"
codex exec -o result.md "write a release summary"

需要固定输出结构时，使用 JSON Schema：

sh
codex exec \
  --output-schema schema.json \
  -o result.json \
  "extract project metadata"

--full-auto 已经是兼容性参数并会显示弃用警告。新脚本应明确写 --sandbox workspace-write，不要继续依赖 --full-auto。

代码审查 ​

codex review 会以非交互方式审查指定差异，不修改工作树：

sh
codex review --uncommitted
codex review --base main
codex review --commit <COMMIT_SHA>

三种 target 互斥，也可以不选 target，直接给自定义审查要求。交互会话中对应的入口是 /review，随后可以用 /diff 查看 staged、unstaged 和 untracked 文件。

会话管理 ​

继续原会话 ​

sh
codex resume
codex resume --last
codex resume <SESSION_ID>

--last 默认只在当前工作目录中选择最近会话。需要跨目录搜索时加 --all，需要把非交互 session 也放进选择范围时加 --include-non-interactive。

非交互任务也能继续：

sh
codex exec resume --last "fix the problems found in the previous run"

分叉会话 ​

需要尝试另一条路线但保留原记录时，使用：

sh
codex fork
codex fork --last

TUI 内的 /fork 会从当前对话创建新 session。/side 则创建临时 side chat，适合在不打断主线的情况下询问一个局部问题。

归档与删除 ​

sh
codex archive <SESSION>
codex unarchive <SESSION>
codex delete <SESSION>

归档只从活跃列表中隐藏 session，仍保留 transcript；删除则不可恢复，并会删除其派生 session。

常用参数 ​

参数作用
--model / -m临时覆盖模型
--profile / -p加载 ~/.codex/<name>.config.toml
--cd / -C指定工作目录
--add-dir增加额外可写目录，可重复使用
--sandbox / -s选择旧式沙箱模式
--ask-for-approval / -a选择 untrusted、on-request 或 never
--search将 Web 搜索切换到实时模式
--image / -i附加一张或多张图片
--strict-config遇到无法识别的配置字段时直接报错

例如临时切换模型：

sh
codex --model gpt-5.6-terra

模型目录会随账号和版本变化，TUI 中 /model 显示的可用列表比文章中的固定名称更可靠。

权限与搜索 ​

本地执行由两层共同决定：

  • sandbox 决定命令在技术上能访问什么
  • approval policy 决定什么操作需要停下来询问

Auto preset 大致对应：

sh
codex --sandbox workspace-write --ask-for-approval on-request

它允许 Codex 在工作区内读写并执行命令，访问网络或工作区外路径时再申请批准。只做分析时可以使用：

sh
codex --sandbox read-only --ask-for-approval on-request

Web 搜索和 shell 命令的网络权限是两套控制。Codex 本地对话默认可以使用 OpenAI 维护的缓存搜索；--search 会切换到实时搜索，但不会自动给 shell 命令开放网络。

TUI 命令 ​

当前高频 Slash command 包括：

命令作用
/status查看模型、权限、上下文和 token 使用情况
/permissions切换 Auto、Read Only 或自定义 permission profile
/model切换模型和推理强度
/plan进入计划模式
/goal创建、编辑、暂停或继续持久目标
/review、/diff审查工作树并查看差异
/skills、/plugins选择 Skill 或浏览 Plugin
/agent切换主 Agent 与 subagent thread
/mcp查看 MCP 工具，/mcp verbose 显示诊断详情
/compact压缩长对话，释放上下文
/copy复制最近一次完成的回答，也可按 Ctrl+O
/new、/resume、/fork新建、恢复或分叉对话
/exit退出 CLI

/clear 现在会清空终端并创建新对话，不再只是清屏。只想清理显示而保留当前 conversation，应使用 Ctrl+L；只想新建对话但保留屏幕内容，则使用 /new。

扩展与诊断 ​

MCP ​

sh
codex mcp list
codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp
codex mcp login <SERVER_NAME>

MCP 配置写入 config.toml，ChatGPT desktop app、CLI 和 IDE extension 在同一 Codex host 上共享这套配置。

Skills 与 Plugins ​

Skills 用于封装可重复执行的方法，Plugins 可以进一步打包 Skills、MCP、Hooks 和其他能力。TUI 使用 /skills 和 /plugins，CLI 使用 codex plugin 管理已配置 marketplace 中的插件。

补全和诊断 ​

sh
eval "$(codex completion zsh)"
codex doctor
codex doctor --json

codex doctor 会检查安装、配置、认证、Git、终端、app-server 和 session inventory，提交问题前先运行它通常能省掉一轮排查。

高风险开关 ​

下面的命令会同时移除审批和沙箱：

sh
codex --dangerously-bypass-approvals-and-sandbox

它也可以写成 --yolo。只应在外部已经隔离的容器或 VM 中使用。普通本机开发需要额外目录时，优先使用 --add-dir；需要网络时，只开放明确的网络范围，不要用 Full Access 代替配置。

参考 ​