命令行与 CI:
把 Codex 带进终端和流水线
前面 13 课都在 App 里。同一个 Codex 也能在终端里用:敲 codex,像在 App 里一样边聊边干;换成 codex exec,它就变成一条能写进脚本、放进 CI 的命令,跑完自己退出。这一课两样都教。
只想在终端里用:看第 1–6 节。要写进脚本、放进 CI:重点看第 7–9 节。
什么时候用命令行
同一个 Codex,三种用法。区别不在聪明程度,而在谁在旁边看着、中途能不能停下来问你。
codex 像坐在吧台,直接跟厨师说一样能来回对话、中途批准,只是一切都在一个终端窗口里,手不用离开键盘。远程服务器上也能用。codex exec 像下外卖订单下单时就写清楚要什么、能动哪些东西(权限)、送到哪(输出)。做的过程中没人会打电话问你,做好了送到门口。所以它适合脚本和 CI。| App | 终端里的 codex | codex exec | |
|---|---|---|---|
| 怎么开始 | ChatGPT 桌面 App 里切到 Codex | 在项目目录里敲 codex | codex exec "任务" |
| 中途能批准吗 | 能 | 能 | 不能,权限要事先给好 |
| 结果在哪 | 对话 + 审阅面板 | 终端里的对话,/diff 看改动 | 打印出来,可以写进文件、交给别的命令 |
| 适合 | 看得见每一步的日常开发 | 习惯终端的人、远程服务器 | 脚本、定时跑的任务、CI |
App、命令行、IDE 扩展共用同一套配置(~/.codex/config.toml,第 7 课),技能也三边通用。命令行没有 App 那样的项目列表:你在哪个目录启动,哪个目录就是这次对话的项目。
在终端的 Codex 里输入 /app,当前会话会在桌面 App 里打开,接着做(macOS、Windows)。反过来,终端里运行 codex app 会启动桌面 App;没装的话会开始安装。
安装与登录
装一个命令、登一次录,之后在任何项目目录里都能用。首选官方安装脚本;npm 和 Homebrew 也可以。
登录
第一次在项目目录里运行 codex,它会请你登录:选 Sign in with ChatGPT,在弹出的浏览器里登好就回来了。也可以先单独运行 codex login。两种登录方式的区别(额度、云端能不能用)第 1 课讲过。
| 方式 | 命令 | 适合 |
|---|---|---|
| ChatGPT 账号 | codex login | 日常使用,走你套餐的额度。默认就是它 |
| API key | printenv OPENAI_API_KEY | codex login --with-api-key | 按 API 标准价格另外计费;官方推荐脚本和 CI 用它 |
| 设备码 Beta | codex login --device-auth | 远程服务器、没有浏览器的机器。先要在 ChatGPT 的安全设置(工作区由管理员)里打开设备码登录 |
| 查看 / 退出 | codex login status · codex logout | 已登录时 status 的退出码是 0,脚本里可以拿来检查 |
登录信息缓存在 ~/.codex/auth.json(明文文件)或系统自带的凭据库里,命令行和 IDE 扩展共用。里面有访问令牌:别提交进仓库,别贴进工单或聊天。想强制放进系统凭据库,在 config.toml 里写 cli_auth_credentials_store = "keyring"。
终端里的按键和命令
终端里没有按钮,常用操作都在键盘上。插话、排队、@ 找文件这几样 App 里也有,其余大多是终端独有的。点一个键,看它在终端里是什么效果。
斜杠命令:哪些只有终端有
输入 / 弹出命令列表,接着打字可以筛选。Codex 正在干活时,打好一个斜杠命令按 Tab,它会排队到这一轮结束后再执行。
列表是节选。能用哪些命令会因环境和账号不同,以你输入 / 后弹出的菜单为准。
终端演练:在 order-admin 里走一遍
从确认登录,到 @ 找文件、! 跑命令、批准、双击 Esc、插话和排队,再到 codex exec 和 codex resume,9 步。中途会请你批准一次,"允许一次"和"拒绝"都可以点,后面的剧情会跟着变。
终端画面为教学示意:界面样式、Codex 说的话、测试数量都是虚构的;命令、按键和参数的作用与官方文档一致。
启动参数:只管这一次
参数像点菜时的临时备注:"这次少放辣"。它只管这一次运行,优先级最高;想每次都这样,写进 config.toml(第 7 课)。
| 参数 | 作用 |
|---|
这些参数对 codex 和大多数子命令都有效,写在子命令后面也行,比如 codex exec -m …。完整列表运行 codex --help。
App 的三档,在命令行里怎么写
命令行里权限拆成两个参数:-s 管沙箱(能碰什么),-a 管审批(什么时候问你)。它们和 App 三档的对应关系是这样的:
| App 里的档位 | 命令行写法 | 效果 |
|---|---|---|
| Ask for approval App 默认 | 什么都不加(命令行叫 Auto 预设),或 -s workspace-write -a on-request | 项目里能改文件、跑命令;联网、改项目外的文件先问你 |
| Approve for me 设置里叫 Auto-review | 上面那组,再加 -c approvals_reviewer=auto_review | 边界不变;本该问你的请求,交给自动审查判断 |
| Full access | --yolo,或 -s danger-full-access -a never | 没有沙箱,也不问。不推荐 |
| (命令行的 Read Only) | -s read-only -a on-request | 只看不改;越界的动作要你批准 |
命令行里叫 Auto 的预设,对应的是 App 的默认档 Ask for approval:越界照样停下来问你。真正"交给自动审查"的写法,要加 approvals_reviewer=auto_review。会话中途想换,输入 /permissions。
另外,Codex 启动时会看目录是不是 Git 仓库:是就推荐 Auto,不是就推荐只读。有的设置下,在你明确信任这个目录之前,它会先以只读方式启动。
练一练:按哪个键,加哪个参数
两组题。每题选一个,选完看解析。
这时该按哪个键
这次该加哪个参数
codex exec:一次说清,跑完就走
codex exec 就是那份外卖订单:不打开界面、中途不等人、做完就退出。它有几条和交互模式不一样的默认规矩,写脚本之前一定要知道。
-s 时在只读沙箱里跑:能读、能分析,不改文件。要让它改,写 --sandbox workspace-write;danger-full-access 只在隔离好的 CI runner 或容器里用。参数表写的是"默认跟配置走":你的 config.toml 设了 sandbox_mode 就以它为准,所以脚本和 CI 里最好写明 -s。--skip-git-repo-check。> 文件 和 | 下一个命令 拿到的是干净的结论。codex login 存下的登录。CI 里通常换成 API key,第 9 节讲怎么放才安全。codex exec resume --last "下一步" 接上当前目录最近的那次会话接着跑(加 --all 不限目录),适合"先审、再修"的两段式流水线。不想在磁盘上留会话记录,加 --ephemeral。codex exec -(或干脆不写提示词):管道内容整个就是提示词。两个出口:点点看
同一个任务,换几种输出方式,看 stderr 和 stdout 里各是什么。内容是示意,事件类型和字段名照官方文档。
stderr · 给人看的进度
stdout · 给下一个程序
review.md
--output-schema 用的格式说明,示例){
"type": "object",
"properties": {
"risk": { "type": "string", "enum": ["low", "medium", "high"] },
"issues": { "type": "array", "items": { "type": "string" } }
},
"required": ["risk", "issues"],
"additionalProperties": false
}官方的建议是:CI 里把 --json 和 -o 一起用。过程事件留给程序解析和排查,最后那段结论单独存成文件给人看。
命令拼装器
选你要的效果,页面实时拼出 codex exec 命令,并用大白话说明它会做什么、哪里可能踩坑。可以从一个场景开始改。
这条命令会
放进 GitHub Actions
CI 就像流水线上的质检工位:每个 PR 经过都查一遍。官方做好了这个工位 openai/codex-action@v1:它装好 Codex CLI,把 API key 锁在一个代理后面,再按你给的权限跑 codex exec。
OPENAI_API_KEY,在 workflow 里引用它,别写进文件。safety-strategy: unsafe,下面会讲的"去掉 sudo"这层保护就用不上了。prompt 里,或者放进仓库的文件、用 prompt-file 指过去。官方建议放在 .github/codex/prompts/。给 order-admin:每个 PR 自动审一遍
下面是根据官方示例改的 workflow。带色条的行可以点,说明面板会解释这一行在做什么。
审查这个 PR 相对 main 的改动。 只报告会导致 bug、安全问题或漏掉测试的地方,每条写清文件和行号。 不要修改任何文件。没有问题就回答"没有发现需要处理的问题"。
还能调的输入
| 输入 | 作用 |
|---|---|
prompt / prompt-file | 提示词,二选一。两个都写会报错 |
sandbox | read-only / workspace-write / danger-full-access,选能完成任务的最窄那个 |
codex-args | 额外的命令行参数,写成 JSON 数组(如 ["--ephemeral"])或一串参数(如 --profile ci)。要结构化输出,就在这里传 --output-schema |
model / effort | 模型和推理强度,留空用默认 |
output-file | 把最终回答写进文件,后面的步骤可以上传或比较 |
codex-version | 固定 CLI 版本;留空用最新发布的版本 |
codex-home | 指定一个共用的 Codex 配置目录,几个步骤之间复用配置和 MCP 设置 |
safety-strategy | 默认 drop-sudo:跑 Codex 前去掉 sudo(整个 job 都收不回来),保护内存里的密钥。也可以选 unprivileged-user(配 codex-user,用指定账号跑) |
allow-users / allow-bots | 谁能触发。默认只有对仓库有写权限的人 |
进阶:CI 失败时让它提修复,写权限和密钥分开
官方还给了一个模式:主 CI 失败后触发另一个 workflow,让 Codex 试着修,但它自己不能往仓库写。关键是拆成两个 job:
workflow_run)。generate_fixcodex.patch 产物。open_prgit apply 应用,开一个 PR 等人审。拿到 key 的 job 不能写仓库,能写仓库的 job 拿不到 key。就算其中一个被攻破,也拿不全两样。
练一练:这样配安全吗
@codex review 有什么不同第 13 课是在 GitHub 上直接 @ Codex,前提是给仓库设置好 Codex Cloud(云端只认 ChatGPT 账号登录)。这一课的 Action 跑在你自己仓库的 GitHub Actions 里,用 API key,什么时候跑、结果发到哪,都由你的 workflow 决定。
进阶:SDK、app-server 与避坑
想在自己的程序里调用 Codex,用 SDK;想做一个完整的客户端,才需要 app-server。最后是旧教程对照和几个容易踩的坑。
SDK:在代码里开对话、接着说
SDK 把"开一个对话、发一句话、拿到回答"变成函数调用。同一个对话对象再调用一次 run,就是在同一段对话里接着说。
| 你要…… | 用 |
|---|---|
| 在 shell 脚本、定时跑的任务里跑一次 | codex exec |
| 在 GitHub Actions 里跑 | openai/codex-action |
| 在自己的 Node / Python 程序里开对话、接着说(TypeScript 版还能恢复旧对话) | Codex SDK |
| 做一个完整的客户端(登录、对话历史、审批、流式事件),像 Codex 的 VS Code 扩展那样 | app-server 实验 |
官方说 app-server 主要用于开发和调试,可能不打招呼就改;做自动化和 CI,用 SDK。
--approval-mode suggest / auto-edit / full-auto三档:现在是-s(沙箱)和-a(审批)两个参数,App 里是三档权限(第 3 课)。codex exec --full-auto已废弃:还能跑,但会打印警告。新脚本写--sandbox workspace-write。-a untrusted、on-failure:untrusted已经不支持,留在配置里可能让 Codex 启动不了;on-failure已废弃。交互时用on-request,非交互用never。codex mcp-server(把 Codex 当 MCP 服务器)已移除:改用 app-server。- "只能
npm i -g安装,Windows 必须走 WSL":现在首选官方安装脚本,Windows 有install.ps1可以原生安装(专题 B)。 brew install codex:现在是brew install --cask codex。
进阶问答
exec 里没人点"允许",越界的动作会怎样?
-s 把权限给到刚好够用。只想审代码,不想写提示词
codex review:--uncommitted 审还没提交的改动(含暂存、未暂存、未跟踪),--base main 审当前分支相对 main 的改动,--commit <SHA> 审某一次提交。三个只能选一个,也不能和自定义提示词同时用。它和 exec 一样能用 CODEX_API_KEY。交互界面里对应的是 /review。CI 里能不能用我的 ChatGPT 账号,而不是 API key?
auth.json 放进安全存储、跑完把刷新后的文件存回去;公开仓库和开源仓库别用。官方的结论是:自动化默认用 API key,申请和轮换都简单。远程服务器上登录,浏览器回调不回来
codex login --device-auth(Beta),在浏览器里打开链接、输入一次性代码。用不了的话:在有浏览器的机器上登录,把 ~/.codex/auth.json 拷过去;或者用 ssh -L 1455:localhost:1455 把登录回调端口转发回本机。Linux / WSL2 上启动时提示沙箱有问题
bubblewrap,先用包管理器装上(Ubuntu / Debian 是 sudo apt install bubblewrap)。原生 Windows 的沙箱另有一套,见专题 B。设置好像没生效
/status 看当前的模型、审批策略、可写目录;/debug-config 看配置分了哪几层、各从哪来;启动时加 --strict-config,config.toml 里有不认识的字段会直接报错。还不行就运行 codex doctor,它会检查安装、配置、登录、Git、终端等,生成一份诊断报告。更新日志里的 --approve-for-me 是什么?
--approve-for-me,用来开启自动审查、不扩大权限;但参数参考表里没有它。用之前先 codex --help 确认你的版本有没有。参考表里写明的等价写法是 -c approvals_reviewer=auto_review。提示词太长,终端里不好写
VISUAL,没设就读 EDITOR)。脚本里把提示词放进文件:cat prompt.txt | codex exec -。想要 Tab 补全、换代码高亮主题
codex completion zsh 生成补全脚本(也支持 bash、fish、PowerShell),在 zsh 配置里加一行 eval "$(codex completion zsh)"。代码高亮主题用 /theme 挑,会存进 config.toml。在 CI 里装 CLI,不想被安装脚本的提问卡住
CODEX_NON_INTERACTIVE=1,提问会自动用默认答案:curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh。用 GitHub Actions 的话,openai/codex-action 会替你装。小测验
8 道题,每题选完会立刻看到解析。
