第一次用 Codex CLI：先把这五件事定下来

2026-08-09

装完 Codex（OpenAI Codex）的命令行工具，多数人第一反应是直接敲一句话让它干活。这样能跑起来，但接下来几天你大概率会为几件没定清楚的事返工：权限给多了心里发毛，给少了它老是卡住问你；模型选错了到 8 月底还得再改一遍；登录方式选错了，账单挂在你没打算用的那个账户上。

这五件事的共同特点是——改起来不难，但改晚了就得把前面做过的配置和习惯推倒重来。所以第一次用之前花十分钟定下来，比事后翻文档划算。下面按我建议的顺序讲，每一步都说清楚为什么这么做，以及做错了会在哪一环暴露出来。

本文里凡是标了「本机实测」的结论，都来自 codex-cli 0.147.0（Windows 11）上执行的只读命令。我们没有发起过任何模型对话请求，所以你不会在这里看到”跑了个任务花了多久”这类内容。

第一件事：确认你在用的到底是哪一个 codex

先别急着配置，先搞清楚你机器上现在跑的这个 codex 是从哪来的、版本是多少。

官方给的安装方式有四种。Windows 侧的独立安装脚本是：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

macOS / Linux 侧的独立安装脚本是：

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

另外两种是 npm（npm install -g @openai/codex）和 Homebrew（brew install --cask codex，升级用 brew upgrade --cask codex）。

为什么要先确认渠道：装过两次以上的人，很容易不确定当前跑的到底是哪一个，版本和渠道跟自己的印象对不上。翻 PATH 很慢，更快的办法是：

codex doctor --summary

本机实测在 codex-cli 0.147.0（Windows 11）上，doctor 的 Environment 分组里有一行 runtime，会直接写明当前这个 codex 是哪种渠道装的、可执行文件与资源目录在哪；紧跟着的 install 行给出一致性判断（本机显示 consistent）。这两行比你自己翻 PATH（which -a codex）更省事。

还有一个坑要提前打预防针：版本号会自己变。本机实测采集当天，开头执行 codex --version 得到 codex-cli 0.131.0，十几分钟后再执行同一条命令变成了 codex-cli 0.147.0，而 which -a codex 全程只有一个可执行文件。Codex 自身带更新能力（配置里 check_for_update_on_startup 默认为 true）。所以以后你排查任何跟版本有关的问题，都要以当次 codex --version 的实时输出为准，别用记忆里的版本号，也别拿别人截屏里的版本号跟自己比。

第二件事：定登录方式

官方给了两种认证方式，它们的差别不在”哪个方便”，而在权限归属和计费归属：

方式	官方口径
ChatGPT 登录	使用 ChatGPT workspace 凭据，浏览器完成认证，遵循 workspace 权限、RBAC 与企业留存设置
API Key	需要 OpenAI 控制台的 API key，按标准 API 费率通过 OpenAI Platform 账户计费

CLI 侧的入口分别是 codex login，以及用管道把 key 喂进去：

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

注意这条命令的形式——key 是从环境变量经管道传入的，不要把真实 key 写在命令行参数里，那会进 shell 历史。写文档、发工单时一律用 <YOUR_API_KEY> 占位。

想确认当前状态，跑：

codex login status

本机实测在 codex-cli 0.147.0（Windows 11）上，这条命令输出一行 Logged in using ChatGPT。

做错了会怎样：如果你在公司电脑上用个人 API key 登录，那 workspace 那套权限和留存规则就不适用了，账单也走的是另一条线；反过来，如果团队要求走 workspace，你却挂了 API key，管理侧就看不到你的使用情况。这事越早定越好。

凭据存放有两种去处：~/.codex/auth.json（明文文件），或者操作系统的凭据存储（keyring / Windows 凭据管理器），由 cli_auth_credentials_store 控制，可选 file、keyring、auto，默认 auto。官方对 auth.json 的原话是：把它当密码看待，别提交进仓库、别贴进工单、别在聊天里发。

几个特殊场景的官方做法：远程机器上没浏览器，首选设备码登录 codex login --device-auth（beta 阶段），按提示打开链接输一次性验证码；备选是从有浏览器的机器复制已缓存凭据，或用 SSH 隧道把 localhost 回调端口 1455 转发过去。公司网络上有 TLS 代理或私有根 CA 的，官方要求登录前设置环境变量 CODEX_CA_CERTIFICATE。登录失败的诊断信息写在配置的日志目录下的 codex-login.log。

第三件事：定沙箱模式

这是五件事里最值得慢慢想的一件。沙箱决定了这个工具能不能碰你的文件、能不能出网。三个取值官方释义如下：

模式	官方原文
`read-only`	”The agent can inspect files, but it can’t edit files or run commands without approval.”
`workspace-write`	”The agent can read files, edit within the workspace, and run routine local commands inside that boundary.”（官方标注为默认模式）
`danger-full-access`	”The agent runs without sandbox restrictions. This removes the filesystem and network boundaries…”

命令行上用 -s, --sandbox 指定，配置文件里对应 sandbox_mode。第一次用，先从 read-only 起步是最省心的——你有一整天时间观察它想干什么，再决定要不要放开到默认的 workspace-write。

参数拼错会怎样？本机实测在 codex-cli 0.147.0（Windows 11）上执行 codex -s bogus-mode，得到的报错是：

error: invalid value 'bogus-mode' for '--sandbox <SANDBOX_MODE>'
  [possible values: read-only, workspace-write, danger-full-access]

For more information, try '--help'.

拼错会直接被拦下来，不会静默降级成别的模式。

Windows 用户要额外知道的：沙箱的底层实现三个平台完全不同——macOS 用系统内置的 Seatbelt，Linux / WSL2 需要你用包管理器装 bubblewrap（bwrap），Windows 则是在 PowerShell 中使用原生 Windows 沙箱，不需要 WSL、不需要虚拟机。所以网上那些”沙箱起不来先看 bwrap 装没装”的排查步骤，在 Windows 上一条都套不上。

Windows 沙箱有两种模式，配置键是 windows.sandbox：

elevated：官方标注为首选，使用专用的低权限沙箱用户，文件系统权限边界加防火墙规则，需要管理员批准的初始化设置；
unelevated：回退方案，用从当前用户派生的受限 Windows token 运行命令，基于 ACL 做文件系统边界，用环境级离线控制代替防火墙规则。官方自己写明它保护更弱，但在拿不到管理员批准时可用。

版本支持上，Windows 11 是推荐，较新的 Windows 10（v1809+）是尽力而为（best effort），更老的 Windows 10 不推荐。另有一条硬性要求：winget 必须可用——IT 管得严的机器上先确认这一条。

初始化失败最常见的原因是拒绝了 UAC 提示、本地用户创建被阻止、防火墙规则被限制。还有一个专门的错误码：1385，官方原文是 “Windows is denying the logon type the sandbox user needs.”，意思是沙箱用户已经建出来了，但策略不允许它执行命令。官方给的排查顺序只有四步：重启 Codex → 重试 elevated 初始化 → 需要时回退到 unelevated → 发送诊断，日志在 CODEX_HOME/.sandbox/sandbox.log。网上流传的注册表改法、组策略改法都不在官方口径里，这里不给。

沙箱到底拦不拦得住写操作，可以自己验一下。本机实测在 codex-cli 0.147.0（Windows 11）上，用 codex sandbox 在沙箱内执行一条往仓库目录写文件的 cmd /c "echo ..."，命令返回后目标文件并不存在。这只是一个具体路径上的观测，不构成”沙箱能防住一切”的结论。

第四件事：定审批策略

沙箱管的是”边界在哪”，审批策略管的是”越界前要不要问你”。-a, --ask-for-approval 三档的官方释义：

untrusted：只有受信任的命令（如 ls、cat、sed）免审批，模型提出不在受信集合内的命令时升级给用户；
on-request：由模型决定何时请求审批；
never：从不询问，执行失败直接回传给模型。

这里有个特别容易理解反的地方：never 不等于”放开权限”。它改变的只是要不要问你，沙箱边界原封不动地还在。真正撤掉边界的是 danger-full-access，或者官方说明开头就写着 EXTREMELY DANGEROUS 的 --dangerously-bypass-approvals-and-sandbox（官方原文说它只适用于外部已经做了沙箱隔离的环境）。

做错了会怎样：把 never 当成”我给它全部权限”来用，结果是它一路撞墙、失败信息不断回传，你以为是模型不行，其实是边界卡着；反过来，把 danger-full-access 当成”少弹几次窗”来用，那就是真的没边界了。第一次用建议从 untrusted 或默认档起步，等你摸清它常提的命令类型再往下调。

还有一个中间选项：--approve-for-me，官方说明是审批请求走自动复核，使用 workspace-write 沙箱。配置侧与之相关的是 approvals_reviewer（user 或 auto_review）。另外，如果你只是嫌可写范围太窄，不必整体放开——sandbox_workspace_write.writable_roots 可以在保留沙箱的前提下加可写目录，命令行上也有 --add-dir。出网与否由 sandbox_workspace_write.network_access 控制。

第五件事：定模型

官方《Models》页当前推荐的是 GPT-5.6 家族三档（能力/速度星级为官方给出，核对日 2026-08-09）：

模型名	官方定位	能力/速度	需要注意的可用面
`gpt-5.6-sol`	旗舰档，面向复杂编码、计算机使用、研究与网络安全	5 星 / 2 星	全平台，含 API
`gpt-5.6-terra`	日常工作的均衡档	4 星 / 3 星	Codex cloud 不可用
`gpt-5.6-luna`	家族里最便宜的快速档	3 星 / 4 星	云端任务不可用

选型的第一个判断点不是”哪个更强”，而是你要不要用云端任务：terra 和 luna 在 Codex cloud 上不可用，如果云端任务在你的工作流里，本地这边的选择实际上被收窄到 sol。另外，Codex cloud 是自动选模型的，不是你本地选什么它就用什么——这一条属于官方文档口径，我们没有实测过云端。

配置里指定模型用 model 键（本机实测配置为 model = "gpt-5.6-sol"，codex-cli 0.147.0 / Windows 11），单次会话用 -m, --model。相关的还有 review_model（/review 专用模型，不设则继承会话模型）和 agents.default_subagent_model。

推理强度也在这一步顺手定了。官方给的选择原则是”选够用的最低档”，配置键是 model_reasoning_effort，配置文件接受的取值是 minimal / low / medium / high / xhigh。这里有个不要想当然的地方：官方文案里出现的档位名（Light/Low、Medium、High、Extra High，以及 Max、Ultra 两个特殊模式）与配置键取值不是同一套字符串，官方也没给映射表，所以别自己推断对应关系，配置文件里就按上面五个取值写。

一个有时效性的坑：官方明确写了 “GPT-5.4 and GPT-5.4 mini retire from Codex on August 31, 2026.”，迁移映射是 gpt-5.4 → gpt-5.6-terra、gpt-5.4-mini → gpt-5.6-luna；gpt-5.2 和 gpt-5.3-codex 已标记为 deprecated。要改的不止一处，官方点名了五个地方：workspace 默认模型、保存的模型设置、managed config（受管配置）、自定义 agent、计划任务。只改当前会话的模型是不够的，上面任何一处还写着旧名字，到期之后都会出问题（以官方最新说明为准）。

顺带一个反直觉的观测：本机 config.toml（codex-cli 0.147.0 / Windows 11）里有一段

[notice.model_migrations]
"gpt-5.3-codex" = "gpt-5.4"

说明确认过的模型迁移会被记进这张老名→新名的映射表。也就是说迁移提示是一次性的，确认过就不再提醒——“我没看到迁移提示”不代表你不需要迁移，得自己去上面那五个地方挨个看。

五件事定完，跑一遍自检

配置改完，先别急着开工，跑这两条只读命令验收：

codex doctor --summary
codex features list

doctor 要重点看两处。一是配置到底加载成功没有：正常态下 Configuration 分组的 config 行显示 loaded。本机实测在 codex-cli 0.147.0（Windows 11）上，故意把一段 TOML 写坏（codex -c 'features=[unclosed' doctor --summary）之后，doctor 没有崩溃退出，照常跑完，但 Notes 区会打出 ✗ config config could not be loaded。所以”我改了配置怎么没生效”的第一步永远是跑 doctor 看这一行，而不是反复重开终端。二是 Configuration 分组里的 sandbox 行，本机显示形如 restricted fs + restricted network · approval OnRequest，正好把你第三、第四件事的选择结果一起复述给你听。

features list 输出三列：特性名、所处阶段、当前生效值。阶段一共观测到五种：stable、under development、experimental、deprecated、removed。看到 experimental 和 under development 的开关，第一次用就别碰，它们会随版本变。这里还有个容易误读的点：removed 阶段的特性仍然会出现在列表里，而且本机实测在 0.147.0 上，部分 removed 项的生效值是 true——所以 removed 的含义更接近”这个开关本身不再需要你控制、行为已经固化”，不等于功能没了。

关于 --strict-config 也提一句，别把它当成万能拼写检查。它的说明是配置里出现本版本不认识的字段就报错退出，但本机实测在 codex-cli 0.147.0（Windows 11）上，codex -c model_reasoning_effortt=high --strict-config exec --help 正常打印了 help，没有报未知字段错误——说明校验发生在真正加载配置去跑会话的路径上，--help 这种不进会话的路径不触发。用它兜底可以，指望它拦住所有拼写错误不行。

什么情况下这套顺序不适用

机器不归你管：受管配置（managed config）、workspace 默认模型这些由管理员定的东西，会盖过你本地的选择。这种情况下第五件事你自己定不了，得找管理员。
拿不到管理员批准的 Windows 机器：elevated 初始化做不了，只能走 unelevated 回退，而官方自己说了它保护更弱。这时候更应该把沙箱模式压在 read-only，靠流程而不是靠沙箱兜底。
纯自动化场景：codex exec 那条非交互路径有自己的一套选项（如 --skip-git-repo-check、--json、-o），审批取舍逻辑也和交互式不同，不在本文范围内。
桌面应用、IDE 扩展、Codex cloud：这几个面我们完全没有实测，本文的实测结论一条都不要往那边套。

这五件事没有标准答案，它们是四个约束（你的权限、你的账单归属、要不要出网、要不要云端）的交点。先按最保守的档位起步，观察一两天再往上放。