Codex CLI 怎么用

0030 秒速览：三句话、一张处境表、一条上手路径

读完这一篇，你能自己判断三件事：这个工具能不能替你干活、它干活时会被什么卡住、以及你什么时候必须自己看一眼再放行。它不教你怎么写代码，教的是怎么指挥一个会写代码的代理。

按你的处境，直接用这个

一条可执行的上手路径

本文讲的是跑在你自己终端里的 Codex CLI（0.154.0），不是网页里的云端 Codex，也不是编辑器插件。它迭代很快，命令与默认值以你本机 codex --help 输出为准。

01它到底是什么：一个会动手的代理，不是一块更长的聊天框

它是什么

Codex CLI 是 OpenAI 官方开源的一个"终端里的 AI 编程代理"。"代理（agent）"这个词的意思是：你说目标，它自己规划并按步骤执行——不是每步都等你说，而是在你给的边界内自己往前走。它的官方描述是一句话：a coding agent from OpenAI that runs locally on your computer（一个跑在你电脑本地的编程代理）。你在终端敲 codex 打开它，用自然语言说"把 src/login.js 里空密码抛错的 bug 修掉，改完跑 npm test 确认"，它就会读文件、改文件、跑命令，最后把结果说给你听。

代码是开源的，用 Apache-2.0 协议发布，仓库在 github.com/openai/codex。新版主体是 Rust 写的原生程序，所以你看到的 npm、Homebrew、安装脚本这些入口，本质都在给你装同一个可执行文件。

它不像什么（先破四个错想）

它和网页版、IDE 插件是不是一回事

不是。OpenAI 的 Codex 有好几种形态，能力相近，但"跑在哪、钱给谁、怎么控制"完全不同。本文只讲第一行那个 CLI。

它帮你干的是哪几类活

改代码 / 修 Bug（最主要的用途：你描述需求，它规划、跨文件修改、跑验证）· 读懂陌生项目（问它"这项目是干嘛的、模块怎么分工"，适合刚接手别人代码的第一天）· 跑命令 / 自动化（跑测试、批处理、审 diff，还能用 codex exec 接进脚本和 CI）· 写文档 / 注释（几十个文件的重复文本劳动，它不改逻辑，风险最低、性价比最高）。

02没有它会怎样：一条断掉的链路

传统"用 AI 写代码"卡在哪

不用代理的时候，你大概是这样干的：在网页聊天框问 AI → 拿到一段代码 → 手动复制进编辑器 → 手动装依赖、跑测试 → 报错再贴回去问……问题不在"AI 写得不好"，而在每一步之间都要你人工搬运一遍，而且 AI 看不见搬运后的结果。

它把哪些环节收进去

它收进去的是"看代码、改代码、验证、交给版本库"这一整条链路。注意最后一个环节：它并不替你决定"要不要提交"，而是把"现在改了哪些文件"变成一份随时可查的 diff（改动差异，一行行告诉你加了什么、删了什么）。

为什么它要装"沙箱"这么重的东西

因为一个能自己跑命令的程序，风险也是自己跑出来的：它可能删掉你的文件、可能把密钥发到网络、可能在你不知情时改了别处的配置。官方的说法是——安全由两层共同构成：沙箱管"技术上能碰到哪"，审批管"什么时候必须问你"；两层配合带来的那句关键陈述是：你信任的不是代理的意图，而是它运行在被强制执行的边界之内（原文：You aren't just trusting the agent's intentions; you are trusting that the agent is operating inside enforced limits.）。这句话值得记住，它是理解后半篇文章的钥匙。

03钱、模型和"能不能离网"：六个现实问题

它收费吗

程序本身免费（开源），但"写代码的脑子"在云端，所以一定有成本，两条路选一条：

没有"完全免费无限用"这回事。官方原话是：用 API Key 登录时，按标准 API 价格计费，而不是用你套餐里包含的额度。

我的代码会被发到 OpenAI 吗

会，这是它"懂你项目"的前提：你让它读的文件内容、它跑出来的命令输出，都会送到云端模型做推理。官方在安全文档里也把这一点当成默认前提在写。所以：含密钥、含客户数据的文件，不要放它去读；确有合规要求的项目，先确认你们的数据处理条款再决定用不用。

断网能用吗

默认不能。有一个例外：你自己把模型供应方换成本地跑的模型（见 13 的 provider 配置），那才能离线干活——代价是本地模型能力普遍弱于云端旗舰模型，复杂改码更容易翻车。

它能连别的模型吗

能。默认连 OpenAI 自己的模型，也允许你配 OpenAI 兼容的后端（社区常用 Ollama、LM Studio 跑本地模型）。具体键名以你的版本与官方配置参考为准，别照抄网上某个旧版本的写法。

支持 Windows 吗

官方完整支持是 macOS 与 Linux；Windows 推荐走 WSL2（在 WSL2 里按 Linux 方式装）。原生 Windows 现在也有自己的沙箱实现，但需要额外设置，不是默认路径。Linux 侧还有一个前置条件：需要 bubblewrap（一个让程序在受限环境里运行的小工具），Ubuntu/Debian 用 sudo apt install bubblewrap，Fedora 用 sudo dnf install bubblewrap。

它和隔壁的 Claude Code / OpenCode 选哪个

三者玩法大同小异，方法论通用——学会一个，另外两个上手都很快。真要选，最靠谱的办法是拿同一个练习项目跑同一个任务，比手感，而不是比参数表。

04什么时候不该用它：四种诚实的例外

这一节不是客套。前面讲的是它擅长什么，这里讲它会让你后悔的四种情况。

一句话：它最适合"愿意下指令 + 愿意审阅"的人。它替你搬的是体力活（读库、改码、跑验证），判断力还得你自己出。

05从零到第一次改动：装、登、验

它要求什么环境

装它的四种方式，选一种就好

下面每种都核对过官方文档。新手直接用第一种。

# 方式一：官方安装脚本（macOS / Linux，推荐）
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# 方式二：Homebrew（macOS，你已经装了 brew 的话）
brew install --cask codex

# 方式三：npm（系统里已有 Node.js）
npm install -g @openai/codex

# 方式四：Windows（在 PowerShell 里）
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

安装脚本默认从 releases.openai.com/codex 下载；如果那边拿不到元数据或资源，会自动退回 GitHub Releases。想强制走 GitHub Releases，在命令前设一个环境变量：

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

也可以直接去 GitHub Releases 下压缩包，解压后把里面那个程序改名为 codex，放进 PATH（系统查找命令时依次搜索的那串目录清单）里的某个目录。Apple Silicon Mac 对应的文件名里带 aarch64-apple-darwin，Linux x86_64 对应 x86_64-unknown-linux-musl。

以后不想要了，怎么卸干净

按你当初的安装方式选一行：brew uninstall --cask codex（Homebrew 装的）或 npm uninstall -g @openai/codex（npm 装的）。如果连配置和登录态也不要了，再删掉主目录：rm -rf ~/.codex——这一步会一并删掉你的配置、AGENTS.md 与登录状态，只在确定不再用时执行。

装完先做三件事

登录：三种情况分别怎么做

公司环境要走内网证书的，在登录前设 CODEX_CA_CERTIFICATE 指向你们的根证书文件（没设时它会退回读 SSL_CERT_FILE）：

export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem
codex login

登录凭据存在哪

默认它是明文存在 ~/.codex/auth.json 这个文件里的——里面装的是你的访问令牌（access token，证明"你是你"的一串凭证）。官方给的建议原话级别就是：把它当密码对待。所以：不要提交进 git、不要贴进工单、不要在聊天里发给别人。

想不落明文，改配置用一个键就能切到系统钥匙串：cli_auth_credentials_store = "keyring"（写在 ~/.codex/config.toml 里）。四个取值的区别：file 写进 auth.json；keyring 存进系统凭据库（拿不到就直接报错）；auto 能用系统凭据库就用、否则退回文件；ephemeral 只放在内存里、进程结束就没了（适合一次性环境）。

企业 / 受管环境才需要的开关

个人用户可以跳过这一小节，遇到公司 IT 提要求时再回来查：强制只用某一种登录方式用 forced_login_method = "chatgpt" 或 "api"（不匹配就登出并退出）；限定只能登录某个工作区用 forced_chatgpt_workspace_id；凭据存储方式可以被管理员强制锁死，用户改不动。

06最小例子：从空目录到一段能跑的代码

下面这个练习大约三分钟，能一次验证四件事：装上了、登上了、它能读写你的文件、它能跑命令并把结果告诉你。全程只碰一个你自己建的练习目录。

第一步：准备一个能随便折腾的目录

# 建一个练习目录并进去
mkdir ~/codex-practice && cd ~/codex-practice

# 先变成一个 git 仓库 —— 这是你的后悔药，别跳
git init

# 放一个很小的起始文件
echo "console.log('hello')" > app.js

# 启动交互会话
codex

第一次启动它会让你登录。登录完你就看到交互界面了：下方是输入框，状态栏会显示当前模型、审批档位等信息。

第二步：下一条"能验证结果"的指令

关键是让它自己证明结果，而不是你手动去跑：

# 在 codex> 提示符后输入（这是你说的话，不是 shell 命令）
给 app.js 加一个 add(a, b) 函数并调用它打印结果，然后运行 node app.js 验证一下

你会看到一串动作：读 app.js → 给出打算怎么改 → 让你确认 → 写入文件 → 运行 node app.js → 把输出贴给你。如果这台机器没有 node，它会告诉你并且换个方式验证——观察它怎么面对失败，本身就是很好的第一次体验。

第三步：体验"不进会话、一句话出结果"

# 一次性问答，执行完自动退出（适合脚本化）
codex exec "app.js 是干什么的？逐行解释一下"

到这一步，最小闭环就走通了：听懂指令 → 读代码 → 动手改 → 跑验证 → 汇报。

如果它第一次就答非所问、越改越乱

这很正常，第一次跑偏不代表你装错了。用对指令把它扳回来，顺序别搞反：

1. 立刻喊停，别等它改完再抱怨："停。撤销刚才所有改动，回到我上一条指令之前的状态。"
2. 重讲需求，这次带上"范围 + 不做清单"："我只重新说一遍：只改 src/app.js 的 add 函数，不要动其它文件，不要装新依赖，改完先给我看 diff，等我确认再继续。"
3. 还是不行就退出重开，起一个更小的会话，只让它做其中一步。

它被你的指令引导，而不是你情绪的输出对象。模糊的需求 → 它自由发挥 → 你觉得离谱，这是这条链路的正常反应；把需求讲窄，它通常就回到正轨。

08安全边界：两个各自独立的开关

这一节是全文最该慢下来看的地方。新手最容易搞混的一点是："它会问我"和"它碰得到"是两件不同的事，由两个不同的开关控制。

先纠一个最常见的误解：沙箱不是"看不见你的代码"

不是。沙箱限制的是"它在你机器上能做什么"，不是"你允许它读的内容会不会离开本机"。你让它读的文件、它跑出来的输出，都会送到云端模型。这两件事必须分开想：沙箱防的是"它在本地乱动"，不防"数据出境"。敏感文件不要放它去读，这是唯一有效的做法。

"工作区"这个词指的是什么

工作区就是你启动 Codex 时所在的那个项目目录。默认档位下，这个目录里它可以自由读写，出了这个目录就要"敲门"。你可以用 -C 指定别的目录作为它的工作根，也可以额外放行几个目录：

# 指定工作根
codex -C ~/projects/myapp
# 除了工作区，再给某个目录写权限（推荐用这个，而不是直接开全权）
codex --add-dir ~/shared/lib

它管的命令比你想象的多

沙箱作用在它拉起的每一条子命令上——包括 git、包管理器、测试运行器，都继承同一套边界，不只是它内置的文件操作。这一点很多人没意识到：你让它跑 npm test，那条 npm 也一起被关进了同一个笼子里。

三档沙箱，一张表选完

为什么工作区里也有"只读区"

因为有些文件一旦被代理改掉，你的回退能力就没了。所以即使在 workspace-write 下，下面这些路径仍然被强制只读（递归生效，它们下面的一切都只读）：

工作区里的 .git（无论它是目录还是一个指向别处的指针文件，解析出来的真实路径也保护）、.agents 目录、.codex 目录——这三处在 workspace-write 下也是只读的，递归生效。这就是为什么你有时会看到"git commit 仍然需要审批"：它在保护你的撤销能力，不是在找麻烦。

那谁来保护"文件内容"

沙箱只保护"能写哪些文件"，不保护"文件里的内容对不对"。能回退你的东西只有 git。所以规矩很简单：让它在哪个目录干活，就先在那个目录 git init + git commit 一次干净基线；改坏了 git checkout . 一句话还原。你会在这篇里看到这句话重复出现，因为它比任何一个安全设置都实在。

审批档位有哪几种

如果你想要的是"这个项目里的命令都要我批准"的那种严格效果，官方给的迁移做法是：不写 approval_policy，而是在用户级配置里把这个项目标成不可信：

# ~/.codex/config.toml
[projects."/path/to/project"]
trust_level = "untrusted"

这样这个项目里的命令默认都要批准，并且项目级的配置文件、hooks、规则也不会被加载。如果同时显式写了 on-request，它会覆盖这个"项目推导出来的策略"。

两个开关的推荐组合

联网默认是关的，要开怎么开

默认档位下 workspace-write 不开网络。需要联网（装依赖、抓接口文档）时显式打开：

# ~/.codex/config.toml
[sandbox_workspace_write]
network_access = true

只想给一次会话开：

codex -c 'sandbox_workspace_write.network_access=true'

再往后还有一层"网络白名单"（[features.network_proxy]）：只有当命令网络已经打开时它才起作用，可以按域名放行或拦截。这不属于新手必学，知道有这个东西就行。

网页搜索有四种档位

顺带一句：全权模式（--yolo 等）下，网页搜索默认就是 live。

13配置：把默认值固定下来

配置文件放哪、谁覆盖谁

两个最常临时改的参数：换模型、发截图

模型和图片这两件事通常不用写进配置，临时在命令行上给就行。直接抄这两条：

codex --model gpt-5.6 "把这个函数的命名统一一下"      # 只这一次用这个模型
codex --image "~/Desktop/报错截图.png" "这张报错是什么意思"  # 把一张图片一起交给它看

想固定下来就别每次敲——写进下面那张表里的用户级配置，或者在会话里用 /model 换。可用模型列表以 /model 弹出的为准，官方文档里给的只是示例。

想不用每次敲参数，就写进配置文件。Codex 会从多个位置读配置，优先级从高到低是这样：

项目级配置有一个安全前提：只有你信任的项目，它的 .codex/ 才会被加载——不信任时，项目里的配置、hooks、规则一起被跳过。所以别在随便 clone 来的仓库里无脑点"信任"。

最常改的那几个键

# ~/.codex/config.toml —— 按需增删，别照抄全量
model                  = "gpt-5.6"          # 默认模型；官方示例用 gpt-5.6，以你的可用列表为准
model_provider         = "openai"           # 用哪家供应商
approval_policy        = "on-request"       # 何时停下来问你
sandbox_mode           = "workspace-write"  # 文件/网络边界
web_search             = "cached"           # 联网搜索档位
model_reasoning_effort = "high"             # 推理努力程度：minimal | low | medium | high | xhigh
# 想用系统钥匙串存凭据，而不是明文文件
cli_auth_credentials_store = "keyring"
# 想给工作区多放行一个可写目录（不需要就别加）
# [sandbox_workspace_write]
# writable_roots = ["~/tools"]

一张表查常见配置键

命名权限方案不是"额外的沙箱"

较新的文档把文件与网络边界进一步抽象成可命名、可复用的权限方案，内置三档：:read-only、:workspace、:danger-full-access，用 default_permissions 指过去。自定义方案写在 [permissions.<名>] 里，还可以 extends 内置档再叠加规则。同一个方案内部有一条让人安心的优先级：禁止 > 写 > 读，同优先级时更具体的路径压过更宽的路径——也就是说，禁止永远压过允许。

换模型供应商（含本地模型）

Codex 允许把"干活的大脑"换成别的 OpenAI 兼容后端，通过 [model_providers.<名>] 定义。想试本地模型，最省事的路径是：先在本地把 Ollama 跑起来并拉一个模型，再在配置里加一段并切过去。

# ~/.codex/config.toml
model_provider = "ollama"   # 全局切到本地供应商
[model_providers.ollama]
name     = "Ollama"
base_url = "http://localhost:11434/v1"
wire_api = "chat"

临时改一次，不动配置文件

-c 是所有配置里优先级最高的，用完即走：

# 单次用某个模型跑一趟（模型名以你的可用列表为准）
codex -c model="gpt-5.6"
# 单次收紧审批 + 只读
codex -c approval_policy=never --sandbox read-only "只分析，不要改"
# 单次换供应商
codex -c model_provider=ollama -c model=qwen2.5-coder

Profile：给不同项目配不同默认值

Profile 就是"一整套配置的命名预设"。注意这是新版写法：--profile 不再从 config.toml 里读 [profiles.名字]，而是读一个独立文件。

# 建一个 ~/.codex/deep-review.config.toml，里面写顶层键（不要嵌套在 [profiles.X] 下）
codex --profile deep-review
codex exec --profile deep-review "审查这个改动"

如果你是从老版本升上来的，官方给的迁移做法是：把原来 [profiles.名字] 里的设置搬到 ~/.codex/<名字>.config.toml，然后删掉 config.toml 里的那一段和顶层的 profile = "名字"。

09AGENTS.md：给它一本项目说明书

AGENTS.md 是一个纯文本的指令文件，Codex 在动手干活之前会自动读它。你想让它"一进项目就知道怎么装依赖、怎么跑测试、哪些目录不许碰"，靠的就是这个文件——而不是每次重新叮嘱一遍。

它会去找哪些文件、按什么顺序

1. 全局层：在你的 Codex 主目录（默认 ~/.codex，除非你设了 CODEX_HOME）里找。有 AGENTS.override.md 就只读它，否则读 AGENTS.md；这一层只取第一个非空文件。
2. 项目层：从项目根（通常是 git 根）一路走到你当前所在目录，每个目录里按 AGENTS.override.md → AGENTS.md → 备选文件名的顺序找，每个目录最多取一个。
3. 合并顺序：从根往下拼接，用空行隔开；越靠近你当前目录的内容越靠后，也越优先。

两个边界要知道：空文件会被跳过；拼起来的总大小超过 project_doc_max_bytes（默认 32 KiB）就截断——所以别把它写成百科全书。

一份够用的 AGENTS.md 长什么样

# AGENTS.md —— 放在项目根目录
## 这个项目是干嘛的
这是一个用 Node.js 写的命令行小工具，主入口是 bin/cli.js，代码在 src/ 下。
## 常用命令（改完要靠这些验证）
- 跑测试：npm test
- 跑类型检查：npm run typecheck
- 本地启动：npm start
## 代码约定
- 变量和函数名用英文，注释用中文
- 新逻辑尽量放进 src/lib/ 下的小模块，别都堆在主入口
## 边界
- 绝对不要动 .env 或任何含密钥的文件
- 提交前先给我看 git diff，不要直接 commit

这就是它最实用的形态：把"怎么验证"和"别碰什么"写死。前者让它可以自证，后者替你挡掉最危险的操作。

它什么时候生效

Codex 在每次运行开始时（TUI 里通常就是每个会话开头）重新构建这份指令链，没有需要你手动清的缓存。所以：改完 AGENTS.md 之后，在目标目录里重启一次 Codex 就生效；别指望正在进行的会话立刻用上你刚写的内容。这一点是新手上当最多的地方——改了没反应，往往只是没重启。

多目录布局：一个真实的 monorepo 例子

my-repo/
├── AGENTS.md                    # 仓库通用：跑 lint、改动要写文档、提交前过目
├── apps/
│   └── web/AGENTS.md            # 前端约定：用 pnpm、样式走 Tailwind
└── services/
    └── payments/
        ├── AGENTS.md            # 支付模块通用（同目录无 override 时生效）
        └── AGENTS.override.md   # 支付专项：跑 make test-payments；严禁碰密钥

从 services/payments/ 启动 Codex，它会拼出三层：全局文件 → 仓库根 AGENTS.md → 支付专项 override。这样团队能把规范写进代码树，每个新成员、每次 Codex 都自动遵守，而不是靠口头叮嘱。

我不想写，能自动生成吗

能。在会话里敲 /init，它会基于当前项目生成一份 AGENTS.md 草稿，你审一遍、改成符合你们约定的样子再提交。这是最快建立起点的方式。

个人也值得建一个全局文件

# ~/.codex/AGENTS.md —— 我个人的通用偏好
- 注释、commit message 用中文；变量/函数名用英文
- 每次改动前先说明计划，改动后给出 git diff 摘要
- 涉及删除文件、改配置、动密钥前必须征求我同意

不会出现"全局把项目规矩盖掉"的问题：同一目录下项目文件仍然优先，而全局文件只在没有更局部文件的层级上起替代作用。

10日常使用：怎么问才不跑偏

一次会话长什么样

先把心理预期建立起来。它不是一次性把整段"答案"甩给你，而是"提出 → 等你批 → 动手 → 汇报"的循环。示意（左边是你看到的，注释解释它在干什么）：

$ codex                              # 在项目目录里启动
# 状态栏会显示当前模型、审批档位等（用 /status 可看全部）
codex> 给 src/add.js 的 add 函数补中文注释，并写 3 个测试用例，然后跑测试验证
# 它先读文件、思考，然后给出"打算怎么做"
# 接着贴出将要写入的 diff，类似：
#   + /** 两数相加 */
#   + export function add(a, b) { ... }
# 然后停下来问你：是否应用这些改动？
codex> 你同意就确认；不同意就直接打字纠正它
# 应用后它继续：跑测试、贴结果、总结改动与验证情况
codex> /quit                         # 退出（输入 / 会弹出命令面板）

你要做的就是在每个"等你批"的节点看一眼、点个头或说"改一下"。一路按 y 等于把沙箱和审批两层都浪费了。

说"先别改"是安全咒语

会话内的斜杠命令：一个表看懂

在输入框里以 / 开头就能调出命令。下面是新手最常用的几个（不同小版本会有差异，以你本地弹出的清单为准）：

几个键盘上就能用的动作

指令的固定四件套

规律只有一句话：范围（哪里）＋ 期望（做什么/不做什么）＋ 验证（怎么算成功）＋ 节奏（先方案还是直接改）。四件越明确，它越少自由发挥。

五条能直接套用的提问模板

怎么把它的"验证"变成真的

它说"改好了"和它证明"改好了"是两件事。差距就来自你有没有在指令里给出可执行的验证手段：把验证命令写进需求（"改完跑 npm test 确认通过"远比"改一下"强）、要求它贴原始输出（不要接受"测试通过了"这句话）、给出可判定的成功标准（"这个函数对空数组返回 0"比"让它更健壮"强一百倍）。

11codex exec：无人值守的那一半

交互会话适合"一边聊一边干"。可重复、要接进脚本或 CI 的任务，用非交互模式 codex exec（简写 codex e）：一次执行、做完就退出，不需要人在旁边按按钮。它还有一个重要的默认差异——codex exec 默认在只读沙箱里跑，要它改文件必须显式加权限。

基本用法

# 一次性任务（先 cd 到项目目录再执行）
codex exec "检查仓库里未提交的改动，用中文总结风险点"

# 输出结构化 JSON，方便脚本解析
codex exec --json "把 todos.md 整理成清单"

# 要它改文件，显式给工作区写权限
codex exec --sandbox workspace-write "把仓库里的 console.log 调试语句删掉"

# 不要留下会话文件
codex exec --ephemeral "给这个仓库分级并给出下一步建议"

运行时进度走标准错误输出，只有最后那条消息走标准输出，所以你可以直接接管道：

codex exec "给最近 10 个提交写一段发布说明" | tee release-notes.md

它自己的子命令：resume 与 review

# 接着上一次非交互任务继续（两段式流水线常用）
codex exec "审查这个改动有没有竞态问题"
codex exec resume --last "把你找到的竞态问题修掉"
# 也可以按会话 ID 恢复
codex exec resume <会话ID>
# 专门做代码审查（不改你的工作区）
codex review --uncommitted
codex review --base main
codex review --commit <提交号>

让它产出机器能读的结果

两个 flag 是给下游自动化用的，值得记住：

用一个 schema 的完整例子：codex exec "提取项目元数据" --output-schema ./schema.json -o ./project-metadata.json——它按 schema.json 描述的结构回答，并把最终 JSON 写进 project-metadata.json。

密钥怎么给才安全

官方在非交互模式文档里的原话就是：不要在会检出或运行仓库代码的工作流里，把 OPENAI_API_KEY 或 CODEX_API_KEY 设成 job 级环境变量。GitHub Actions 里的推荐做法是直接用官方的 Codex GitHub Action（github.com/openai/codex-action），它会在内部起一个代理来转发 Key，避免把 Key 交给你的 shell 步骤。

把 exec 串进日常脚本

下面这段脚本演示了"新手可以照抄"的姿势：任务只读、Key 只在这一次调用里出现、结果落盘、缺 Key 就直接失败而不是默默跑一半：

#!/usr/bin/env bash
# review_diff.sh —— 让 Codex 审一遍当前未提交改动，结果存盘
set -euo pipefail
if [ -z "${CODEX_API_KEY:-}" ]; then
  echo "请在调用前临时提供 CODEX_API_KEY" >&2
  exit 1
fi
CODEX_API_KEY="$CODEX_API_KEY" codex exec \
  --sandbox read-only --json \
  "审查当前未提交改动：列问题清单（含文件行号），先不要改任何文件" \
  > review-$(date +%F).json
echo "审查结果已写入 review-$(date +%F).json"

什么时候别用 exec

Git 仓库这个前提

Codex 要求命令在 git 仓库里运行，这是为了防止破坏性改动。临时环境确实安全，才用 --skip-git-repo-check 放行。

12十个最常见的坑

每种情况下"该多说哪一句"

14排错：出问题先查这张表

15一页纸速查：装完到用顺

装 / 验证 / 更新

curl -fsSL https://chatgpt.com/codex/install.sh | sh   # macOS/Linux 官方脚本
brew install --cask codex                            # Homebrew
npm install -g @openai/codex                         # npm
codex --version                                      # 验证（本文校对时是 0.154.0）
codex --help                                         # 本版命令总览（权威以这个为准）
codex update                                         # 自更新（安装方式支持时）
codex doctor                                         # 出问题时生成一份诊断报告

登录

codex login                                        # ChatGPT 账号（浏览器）
codex login --device-auth                          # 无浏览器：设备码
printenv OPENAI_API_KEY | codex login --with-api-key   # API Key（走管道，别进历史）
codex login status / codex logout                   # 状态 / 退出

日常使用

codex                                           # 交互会话
codex --sandbox read-only                       # 只读侦察
codex --add-dir ~/shared/lib                    # 额外放行一个可写目录
codex -C ~/projects/app                         # 指定工作根
codex resume                                    # 找回本仓库的旧对话
codex exec "一句话任务"                       # 非交互（一次性）
codex exec --json "任务"                     # 非交互 + JSON 事件流
codex exec resume --last                     # 继续上次 exec
codex review --uncommitted                    # 审查未提交的改动

安全相关

--sandbox workspace-write --ask-for-approval on-request   # 日常推荐组合
--sandbox read-only --ask-for-approval on-request         # 只读侦察
--sandbox read-only --ask-for-approval never              # CI：只读且不问
--dangerously-bypass-approvals-and-sandbox / --yolo       # 仅限隔离环境
/permissions                                  # 会话里改允许范围
/model  /plan  /diff  /review  /status        # 换模型/计划/看改动/审改动/看状态

其他常用子命令（都在你本机 codex --help 里能看到）

文件都落在哪

~/.codex/config.toml                  # 用户级配置（最常改）
.codex/config.toml                    # 项目级配置（仅信任的项目生效）
~/.codex/<名字>.config.toml           # Profile 文件（--profile 名字）
~/.codex/AGENTS.md                    # 全局指令
项目根/AGENTS.md                       # 项目指令
某目录/AGENTS.override.md              # 同目录 AGENTS.md 被它整个忽略
~/.codex/auth.json                    # 登录凭据（明文，当密码保管）

每次放它动手前，过一遍这五条

1. □ 有没有 git 干净基线？改坏了能不能一句话回退？
2. □ 我是不是说清了范围（哪个文件/哪个函数）和成功标准（怎么验证）？
3. □ 当前沙箱/审批档位符合这次任务的风险吗？敏感目录有没有收敛权限？
4. □ 这次任务会不会碰到密钥、生产数据、或工作区外的写操作？
5. □ 我打算在每个"等你批"的节点看 diff，而不是一路同意？

打勾的时间成本大约十秒，返工的成本可能是一下午。

一周上手路线（给完全零基础的人）

16术语对照表（回头查用）

99一句话总结

98参考来源与证据边界

一手来源（全部逐字读取）

• github.com/openai/codex — 官方仓库 README（定位、安装方式、系统支持、Apache-2.0 协议）
• learn.chatgpt.com/docs/codex/cli — Codex CLI 总览（安装、更新、第一步、能力清单）
• learn.chatgpt.com/docs/developer-commands — 命令与 flag 参考、内置斜杠命令表、快捷键
• learn.chatgpt.com/docs/agent-approvals-security — 沙箱与审批（三档定义、推荐组合、受保护路径、网络访问、untrusted 迁移说明）
• learn.chatgpt.com/docs/sandboxing — 沙箱总览（Seatbelt / bubblewrap / WSL2 的平台差异）
• learn.chatgpt.com/docs/auth — 登录方式、凭据存储（cli_auth_credentials_store 四个取值）、设备码、内网 CA、受管环境强制项
• learn.chatgpt.com/docs/agent-configuration/agents-md — AGENTS.md 的发现顺序、override、体积上限、备选文件名
• learn.chatgpt.com/docs/config-file/config-basic — 配置分层与优先级、常见键、功能开关表
• learn.chatgpt.com/docs/config-file/config-reference — 完整配置键参考（approval_policy / sandbox_mode / default_permissions / web_search）
• learn.chatgpt.com/docs/config-file/config-advanced — Profile 文件写法变更、自定义 provider、审批与沙箱的高级组合
• learn.chatgpt.com/docs/non-interactive-mode — codex exec（默认只读、JSONL 事件、schema 输出、CI 密钥纪律、GitHub Action 建议）
• github.com/openai/codex/releases/latest — 版本锚点：本文校对时最新为 0.154.0（发布于 2026-09-09）

本文自己做的核对

除了读官方文档，本文还在本机实际跑了三条命令核实命令名与 flag：codex --version（→ codex-cli 0.154.0）、codex --help（核对子命令与全局 flag，如 --sandbox / --ask-for-approval / --add-dir / --worktree）、codex exec --help（核对 exec 专属 flag，如 --json / --output-schema / --ephemeral / --skip-git-repo-check）。