×−+
命令行与 CI第 14 课 · Codex 教程
第 14 课 · CLI & CI

命令行与 CI:
把 Codex 带进终端和流水线

前面 13 课都在 App 里。同一个 Codex 也能在终端里用:敲 codex,像在 App 里一样边聊边干;换成 codex exec,它就变成一条能写进脚本、放进 CI 的命令,跑完自己退出。这一课两样都教。

约 45 分钟 11 节 · 8 个动手练习 章末测验 形式参考 luongnv89/claude-howto · 事实依据 OpenAI 官方文档
一条 CI 里常见的命令
入门先用起来 原理弄懂为什么 实战动手练 深入进阶与避坑

只想在终端里用:看第 1–6 节。要写进脚本、放进 CI:重点看第 7–9 节。

01入门

什么时候用命令行

同一个 Codex,三种用法。区别不在聪明程度,而在谁在旁边看着、中途能不能停下来问你。

App 像坐在餐厅里点菜厨房是透明的:每一步、每处改动都摆在眼前,随时能叫停,越界时点"允许"或"拒绝"。
终端里的 codex 像坐在吧台,直接跟厨师说一样能来回对话、中途批准,只是一切都在一个终端窗口里,手不用离开键盘。远程服务器上也能用。
codex exec 像下外卖订单下单时就写清楚要什么、能动哪些东西(权限)、送到哪(输出)。做的过程中没人会打电话问你,做好了送到门口。所以它适合脚本和 CI。
App终端里的 codexcodex exec
怎么开始ChatGPT 桌面 App 里切到 Codex在项目目录里敲 codexcodex exec "任务"
中途能批准吗能能不能,权限要事先给好
结果在哪对话 + 审阅面板终端里的对话,/diff 看改动打印出来,可以写进文件、交给别的命令
适合看得见每一步的日常开发习惯终端的人、远程服务器脚本、定时跑的任务、CI

App、命令行、IDE 扩展共用同一套配置(~/.codex/config.toml,第 7 课),技能也三边通用。命令行没有 App 那样的项目列表:你在哪个目录启动,哪个目录就是这次对话的项目。

两边可以接力

在终端的 Codex 里输入 /app,当前会话会在桌面 App 里打开,接着做(macOS、Windows)。反过来,终端里运行 codex app 会启动桌面 App;没装的话会开始安装。

02入门

安装与登录

装一个命令、登一次录,之后在任何项目目录里都能用。首选官方安装脚本;npm 和 Homebrew 也可以。

选你的系统或包管理器
安装

登录

第一次在项目目录里运行 codex,它会请你登录:选 Sign in with ChatGPT,在弹出的浏览器里登好就回来了。也可以先单独运行 codex login。两种登录方式的区别(额度、云端能不能用)第 1 课讲过。

auth.json 要当密码看

登录信息缓存在 ~/.codex/auth.json(明文文件)或系统自带的凭据库里,命令行和 IDE 扩展共用。里面有访问令牌:别提交进仓库,别贴进工单或聊天。想强制放进系统凭据库,在 config.toml 里写 cli_auth_credentials_store = "keyring"。

03原理

终端里的按键和命令

终端里没有按钮,常用操作都在键盘上。插话、排队、@ 找文件这几样 App 里也有,其余大多是终端独有的。点一个键,看它在终端里是什么效果。

codex · 示意

斜杠命令:哪些只有终端有

输入 / 弹出命令列表,接着打字可以筛选。Codex 正在干活时,打好一个斜杠命令按 Tab,它会排队到这一轮结束后再执行。

列表是节选。能用哪些命令会因环境和账号不同,以你输入 / 后弹出的菜单为准。

04实战

终端演练:在 order-admin 里走一遍

从确认登录,到 @ 找文件、! 跑命令、批准、双击 Esc、插话和排队,再到 codex exec 和 codex resume,9 步。中途会请你批准一次,"允许一次"和"拒绝"都可以点,后面的剧情会跟着变。

order-admin — zsh
$

终端画面为教学示意:界面样式、Codex 说的话、测试数量都是虚构的;命令、按键和参数的作用与官方文档一致。

05原理

启动参数:只管这一次

参数像点菜时的临时备注:"这次少放辣"。它只管这一次运行,优先级最高;想每次都这样,写进 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 的 Approve for me

命令行里叫 Auto 的预设,对应的是 App 的默认档 Ask for approval:越界照样停下来问你。真正"交给自动审查"的写法,要加 approvals_reviewer=auto_review。会话中途想换,输入 /permissions。

另外,Codex 启动时会看目录是不是 Git 仓库:是就推荐 Auto,不是就推荐只读。有的设置下,在你明确信任这个目录之前,它会先以只读方式启动。

06实战

练一练:按哪个键,加哪个参数

两组题。每题选一个,选完看解析。

这时该按哪个键

这次该加哪个参数

07原理

codex exec:一次说清,跑完就走

codex exec 就是那份外卖订单:不打开界面、中途不等人、做完就退出。它有几条和交互模式不一样的默认规矩,写脚本之前一定要知道。

1
默认只读不写 -s 时在只读沙箱里跑:能读、能分析,不改文件。要让它改,写 --sandbox workspace-write;danger-full-access 只在隔离好的 CI runner 或容器里用。参数表写的是"默认跟配置走":你的 config.toml 设了 sandbox_mode 就以它为准,所以脚本和 CI 里最好写明 -s。
2
必须在 Git 仓库里为了防止无法挽回的改动,Codex 会检查当前目录是不是 Git 仓库。确定环境安全,才加 --skip-git-repo-check。
3
进度和结果分两条路进度打到 stderr,只有最终回答打到 stdout。所以 > 文件 和 | 下一个命令 拿到的是干净的结论。
4
默认用你保存的登录本机上跑,直接用 codex login 存下的登录。CI 里通常换成 API key,第 9 节讲怎么放才安全。
5
会话默认存盘,可以接着做codex exec resume --last "下一步" 接上当前目录最近的那次会话接着跑(加 --all 不限目录),适合"先审、再修"的两段式流水线。不想在磁盘上留会话记录,加 --ephemeral。
6
能从管道读内容写了提示词又接了管道:提示词是指令,管道进来的是附加的上下文。写 codex exec -(或干脆不写提示词):管道内容整个就是提示词。

两个出口:点点看

同一个任务,换几种输出方式,看 stderr 和 stdout 里各是什么。内容是示意,事件类型和字段名照官方文档。

stderr · 给人看的进度
stdout · 给下一个程序

review.schema.json(--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 存结论

官方的建议是:CI 里把 --json 和 -o 一起用。过程事件留给程序解析和排查,最后那段结论单独存成文件给人看。

08实战

命令拼装器

选你要的效果,页面实时拼出 codex exec 命令,并用大白话说明它会做什么、哪里可能踩坑。可以从一个场景开始改。

从场景开始:
让它做什么
管道输入
提示词
权限
沙箱
输出
stdout 交给
拼出来的命令
这条命令会
    09实战

    放进 GitHub Actions

    CI 就像流水线上的质检工位:每个 PR 经过都查一遍。官方做好了这个工位 openai/codex-action@v1:它装好 Codex CLI,把 API key 锁在一个代理后面,再按你给的权限跑 codex exec。

    1
    把 OpenAI API key 存成仓库的 secret比如叫 OPENAI_API_KEY,在 workflow 里引用它,别写进文件。
    2
    用 Linux 或 macOS 的 runnerWindows runner 只能设 safety-strategy: unsafe,下面会讲的"去掉 sudo"这层保护就用不上了。
    3
    先 checkout 代码Codex 要读仓库内容,拉代码的步骤得在它前面。
    4
    写好提示词直接写在 prompt 里,或者放进仓库的文件、用 prompt-file 指过去。官方建议放在 .github/codex/prompts/。

    给 order-admin:每个 PR 自动审一遍

    下面是根据官方示例改的 workflow。带色条的行可以点,说明面板会解释这一行在做什么。

    .github/workflows/codex-review.yml
    .github/codex/prompts/review.md(示例)
    审查这个 PR 相对 main 的改动。
    只报告会导致 bug、安全问题或漏掉测试的地方,每条写清文件和行号。
    不要修改任何文件。没有问题就回答"没有发现需要处理的问题"。

    还能调的输入

    输入作用
    prompt / prompt-file提示词,二选一。两个都写会报错
    sandboxread-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:

    CI 失败主 CI 以失败结束,触发这个后续 workflow(workflow_run)。
    第 1 个 job generate_fix
    contents: read有 API key
    拉下失败的那次提交;先装依赖(这一步不给 key);再跑 Codex Action,让它做让测试通过的最小改动;最后把改动存成 codex.patch 产物。
    第 2 个 job open_pr
    contents / pull-requests: write没有 API key
    下载补丁,git apply 应用,开一个 PR 等人审。

    拿到 key 的 job 不能写仓库,能写仓库的 job 拿不到 key。就算其中一个被攻破,也拿不全两样。

    练一练:这样配安全吗

    和第 13 课的 @codex review 有什么不同

    第 13 课是在 GitHub 上直接 @ Codex,前提是给仓库设置好 Codex Cloud(云端只认 ChatGPT 账号登录)。这一课的 Action 跑在你自己仓库的 GitHub Actions 里,用 API key,什么时候跑、结果发到哪,都由你的 workflow 决定。

    10深入

    进阶:SDK、app-server 与避坑

    想在自己的程序里调用 Codex,用 SDK;想做一个完整的客户端,才需要 app-server。最后是旧教程对照和几个容易踩的坑。

    SDK:在代码里开对话、接着说

    SDK 把"开一个对话、发一句话、拿到回答"变成函数调用。同一个对话对象再调用一次 run,就是在同一段对话里接着说。

    index.ts

    你要……用
    在 shell 脚本、定时跑的任务里跑一次codex exec
    在 GitHub Actions 里跑openai/codex-action
    在自己的 Node / Python 程序里开对话、接着说(TypeScript 版还能恢复旧对话)Codex SDK
    做一个完整的客户端(登录、对话历史、审批、流式事件),像 Codex 的 VS Code 扩展那样app-server 实验

    官方说 app-server 主要用于开发和调试,可能不打招呼就改;做自动化和 CI,用 SDK。

    旧教程对照
    1. --approval-mode suggest / auto-edit / full-auto 三档:现在是 -s(沙箱)和 -a(审批)两个参数,App 里是三档权限(第 3 课)。
    2. codex exec --full-auto 已废弃:还能跑,但会打印警告。新脚本写 --sandbox workspace-write。
    3. -a untrusted、on-failure:untrusted 已经不支持,留在配置里可能让 Codex 启动不了;on-failure 已废弃。交互时用 on-request,非交互用 never。
    4. codex mcp-server(把 Codex 当 MCP 服务器)已移除:改用 app-server。
    5. "只能 npm i -g 安装,Windows 必须走 WSL":现在首选官方安装脚本,Windows 有 install.ps1 可以原生安装(专题 B)。
    6. brew install codex:现在是 brew install --cask codex。

    进阶问答

    exec 里没人点"允许",越界的动作会怎样?
    exec 是按"不需要人参与"设计的,沙箱和审批要事先定好。官方在子代理的文档里写过:非交互的流程里,需要新批准的动作会失败,错误报回给上层。所以别指望它中途来问,用 -s 把权限给到刚好够用。
    只想审代码,不想写提示词
    用 codex review:--uncommitted 审还没提交的改动(含暂存、未暂存、未跟踪),--base main 审当前分支相对 main 的改动,--commit <SHA> 审某一次提交。三个只能选一个,也不能和自定义提示词同时用。它和 exec 一样能用 CODEX_API_KEY。交互界面里对应的是 /review。
    CI 里能不能用我的 ChatGPT 账号,而不是 API key?
    能,但官方把它归为进阶做法:只在受信任的 runner 上,把 auth.json 放进安全存储、跑完把刷新后的文件存回去;公开仓库和开源仓库别用。官方的结论是:自动化默认用 API key,申请和轮换都简单。
    远程服务器上登录,浏览器回调不回来
    优先用设备码:codex login --device-auth(Beta),在浏览器里打开链接、输入一次性代码。用不了的话:在有浏览器的机器上登录,把 ~/.codex/auth.json 拷过去;或者用 ssh -L 1455:localhost:1455 把登录回调端口转发回本机。
    Linux / WSL2 上启动时提示沙箱有问题
    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。
    提示词太长,终端里不好写
    交互界面里按 Ctrl+G,用你的编辑器写(读 VISUAL,没设就读 EDITOR)。脚本里把提示词放进文件:cat prompt.txt | codex exec -。
    想要 Tab 补全、换代码高亮主题
    codex completion zsh 生成补全脚本(也支持 bash、fish、PowerShell),在 zsh 配置里加一行 eval "$(codex completion zsh)"。代码高亮主题用 /theme 挑,会存进 config.toml。
    在 CI 里装 CLI,不想被安装脚本的提问卡住
    给运行安装脚本的 shell 设 CODEX_NON_INTERACTIVE=1,提问会自动用默认答案:curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh。用 GitHub Actions 的话,openai/codex-action 会替你装。
    11检验

    小测验

    8 道题,每题选完会立刻看到解析。