“如何用上 Codex”这个问题，我这两个月在几个技术群里被问到的次数，比过去一年加起来都多。问的人情况其实完全不一样：有人是看完发布消息就去注册，结果卡在订阅档位上；有人已经把 CLI 装好了，却卡在第一次登录的凭证环节；还有人真正想问的是“我能不能不依赖官方账号，把这个终端智能体的壳用起来”。这三种人踩的是三个不同的坑，但都被归到同一句“怎么用上”底下，所以网上那些答案往往对不上号。这篇我按“你属于哪一种”来拆，把账号路径、CLI 安装、配置写法、真实项目里的用法，还有几个把我卡了大半天的细节全写清楚。完全没接触过编程智能体的人能照着走，已经在用别的工具想横向对比的人，也能从配置那几节里挑到能直接抄的部分。
1. Codex 这个名字底下其实藏着三种形态
先把概念捋直，否则后面所有步骤都会错位。现在说“用上 Codex”，指向的至少是三个不同的东西，入口、计费方式、使用姿势全都不一样。
1.1 云端任务式：把活丢出去，等它交回来
第一种是网页端那种任务委托模式。你在一张对话框里描述需求，它在隔离的运行环境里自己拉代码、改文件、跑测试，最后交回一个补丁或者说一段改动说明，你审阅后决定合不合。
这种形态最省心的地方在于不用管本地环境——依赖装没装、Node 版本对不对、路径有没有中文，统统与你无关。代价是它的可控性弱，你没法中途插手，只能等结果。适合那种边界清晰、验收标准明确的小任务，比如“给这个模块补一组边界条件测试”“把这段重复逻辑抽成函数”。
很多人的第一个误解就在这里：以为自己要装什么东西才能“用上”，其实订阅到位、在网页上就能直接派活。真正需要折腾的是第二种。
1.2 终端里的 CLI：这才是绝大多数人想装的
第二种是命令行智能体，也是“如何用上”这个问题里 90% 的真正指向。它是一个能读写你本地仓库的终端程序，你给它一句自然语言，它自己决定看哪些文件、改哪几行、跑哪条命令，改完把 diff 摆给你看。
它跟网页版的本质差别是有本地文件系统的写权限。这也是它好用和危险并存的原因。所以它自带两层约束：一层是沙箱模式，限制它能写哪些目录；一层是审批策略，决定哪些操作需要你按回车放行。这两层配置后面会专门讲，很多人装完跑不起来、或者跑起来把不该改的文件改了，都是因为没搞懂这两个概念。
顺带说一句，这个 CLI 是开源发布的，协议宽松，意味着它作为“壳”可以接别人的模型服务。这一点是后面第四节的整条思路来源，也是很多没有官方订阅的人真正的出路。
1.3 编辑器扩展与底层模型：两件容易混为一谈的事
第三种是编辑器里那个侧边栏助手，交互形态上跟 CLI 接近，但入口在 IDE 内部，能拿到当前打开文件、光标位置、选中片段这些上下文。
需要特别澄清的是：Codex 不等于某个具体模型。它是一套面向编程任务的智能体产品形态，底层会调用不同版本的模型。所以你会看到有人问“Codex 和某某模型哪个强”——这是个范畴错误，一个是产品，一个是模型。搞清这一点，你在配置里看到model和model_provider这两个独立字段时就不会懵了。
| 形态 | 入口 | 是否需要本地环境 | 适合的任务 |
|---|---|---|---|
| 云端任务式 | 网页 | 不需要 | 边界清晰的小改动、补测试 |
| 终端 CLI | 命令行 | 需要 | 本地仓库重构、批量修改、脚本化 |
| 编辑器扩展 | IDE 侧边栏 | 需要 | 边写边问、单文件内的改动 |
2. 账号与权限：卡住大多数人的其实不是技术
技术门槛其实很低，一条安装命令的事。真正消耗时间的是权限这条线，而这条线上信息又最不透明。
2.1 订阅档位决定了哪些功能对你开放
官方把能力按档位切开了，这件事得先接受。不同档位之间的差别主要在三个维度：单位时间内的调用额度、能不能用云端任务模式、以及能不能用更高规格的模型。
我见过不少人反馈“装完提示没有权限”，回头一看是免费档位。也见过有人抱怨“额度怎么这么快就没了”，其实是把大仓库整个丢进去让它全量扫描，一次就吃掉了大量上下文。额度消耗跟你的任务粒度是强相关的，这一点在第五节会展开讲具体控制办法。
提示：判断自己卡在哪一层，最省事的办法是看报错文案。提示认证失败的是凭证问题，提示额度或档位的是订阅问题，提示权限拒绝的才是沙箱配置问题。这三种错误长得完全不一样，但很多人一律当成“装坏了”。
2.2 团队空间与企业空间：管理员那一层开关
如果你是在团队或组织环境里用，情况会多一层。有些能力默认不开，需要管理员在后台统一开启，个人这边无论怎么折腾都没用。
这种情况下的排查顺序跟个人版完全相反：先确认组织层面有没有放开，再去查本地配置。我见过一个组折腾了一下午重装环境，最后发现是管理员那边没勾选。所以如果你在受管环境里，“先问管理员”比“先查文档”效率高得多。
2.3 没有官方账号时，开源外壳这条替代路线
这是我觉得最值得单独讲的一条路。前面提过，CLI 本身是开源的，它的架构里把“模型提供方”抽象成了一个可配置项。也就是说，你可以把这个终端智能体的交互逻辑、工具调用、沙箱机制全部用起来，但把背后的模型换成你自己能访问的服务。
这条路的价值不在“绕过”，而在于可控。你接自己的服务，意味着：调用成本你能算清楚、数据不出你自己的链路、模型版本你能锁死不会某天突然变了行为。对于有合规要求或者要跑在离线环境里的团队，这反而是唯一可行的方案。
代价也有：能力上限取决于你接的那个模型，工具调用的稳定性也要看对方对协议的支持程度。想清楚这两点再决定要不要走这条路。
3. 装 CLI：从零到第一次成功对话
假设你走的是官方账号路线，这一节是完整步骤。走替代路线的，前三小节一样要过，只是登录那步跳过。
3.1 前置依赖：Node 版本是最常见的拦路虎
先把运行时确认好。用node -v看一眼，版本太老会在安装阶段就报奇怪的错，或者在运行阶段报语法错误——后者更难查，因为报错位置在依赖内部，跟你的操作毫无关系。
node -v npm -v我个人建议 Node 主版本至少到 20。遇到过 Node 18 能装上但运行时报模块解析错误的情况，换到 20 就正常了。如果你机器上装着多个版本，用版本管理工具切一下，别硬扛。
Windows 用户额外注意：如果你之前在系统里装过 WSL，npm 的全局安装路径可能分裂成两份，导致命令行里能找到codex但版本对不上。which codex（PowerShell 里用Get-Command codex）看一下实际解析到哪个路径，能省掉很多困惑。
3.2 三种安装方式怎么选
| 方式 | 命令 | 适合场景 | 注意点 |
|---|---|---|---|
| npm 全局 | npm install -g @openai/codex | 已有 Node 环境 | 全局目录权限问题 |
| 包管理器 | brew install codex | 类 Unix 系统 | 版本更新滞后于 npm |
| 直接下二进制 | 从发布页取对应平台包 | 无 Node 环境、离线部署 | 需手动加进 PATH |
npm 方式最通用，但有个经典坑：全局安装目录没有写权限时，npm 会报 EACCES。很多人第一反应是加sudo，这是下策——sudo 装出来的全局包归属 root，后续升级、卸载都会再撞一次权限墙。正确做法是把 npm 的全局前缀改到用户目录下：
npm config set prefix ~/.npm-global export PATH=~/.npm-global/bin:$PATH把第二行写进你的 shell 配置文件里，之后所有全局安装都不再需要提权。
装完验证：
codex --version能打印出版本号，说明二进制已经就位。如果提示 command not found，八成是 PATH 没生效，重开一个终端窗口试试。
3.3 首次登录：回调端口与无浏览器环境
官方路线的登录命令很直白：
codex login它会拉起浏览器走一遍授权流程，然后回调到本机的某个固定端口把凭证写回来。这里有两个高频问题：
第一，回调端口被占。你要是本地恰好有服务占着那个端口，登录会卡在“等待回调”这一步一直转圈。查一下端口占用，把那个服务停掉再试。
第二，没有图形界面的环境。跑在远程机器或者容器里的时候，浏览器根本拉不起来。这时候用设备码模式：
codex login --device-auth它会给你一个短码和一段提示，你在任意有浏览器的设备上完成授权，终端这边会自动拿到凭证。这个流程我用得最多，比折腾端口转发省事。
登录成功后，凭证落在用户目录下的一个 JSON 文件里，大致是~/.codex/auth.json这个位置。里面是敏感信息，千万不要提交进版本库。顺手在你的全局 gitignore 里加一条，比事后补救强。
3.4 配置文件：最小可用的一份
CLI 的行为由一份 TOML 配置文件控制，位置在~/.codex/config.toml。不写也能跑，因为你登录之后它有一套默认值。但只要你需要改模型、改审批策略、接自己的服务，就得动这个文件。
一份能跑起来的最小配置长这样：
model = "gpt-5-codex" approval_policy = "on-request" sandbox_mode = "workspace-write"三个字段的含义分别是：用哪个模型、什么时候向你要审批、沙箱给多大权限。这三行基本定义了整个使用体验，下一节专门拆。
改完不需要重启什么服务，下次启动codex自动读取。想看当前生效的配置，直接cat ~/.codex/config.toml确认文件确实在那里、字段拼写没打错——拼错的字段通常被静默忽略，不会报错，这才是最坑的地方。
4. 把 CLI 接到自己的模型服务上
这一节是给走替代路线的人写的，但只要你对调用成本敏感，也值得看。
4.1 model_providers 到底在描述什么
配置文件里有一张 provider 表，每个条目描述“去哪里找模型、用什么凭证、按什么协议说话”。三个字段最关键：
base_url：服务的接口根地址，注意是到/v1这一层，不要带具体路径env_key：从哪个环境变量读 API key，配置文件里不写 key 本身，这个设计是对的，避免明文凭证进版本库wire_api：走哪种协议，主流是chat，也就是那套通用聊天补全接口
完整写法：
model = "your-model-name" model_provider = "my-gateway" [model_providers.my-gateway] name = "My Gateway" base_url = "http://127.0.0.1:8000/v1" env_key = "MY_GATEWAY_API_KEY" wire_api = "chat"然后在使用前把 key 导出到环境变量：
export MY_GATEWAY_API_KEY="sk-xxxx"注意这里的映射关系：配置文件里的model_provider值必须和方括号里那个 provider 名完全一致，拼错一个字符就会回退到默认 provider，而默认 provider 又需要官方登录态——于是你会看到一个跟配置毫无关系的认证错误，查半天查不到点子上。
4.2 本地服务与远程服务的差异点
接本地起的服务（比如各种本地推理框架暴露的兼容接口）时，base_url用127.0.0.1就行，但要注意两点。
一是上下文长度。CLI 的工作方式是自动把相关文件内容塞进上下文，它默认按大模型的窗口大小来规划。你接一个窗口只有 8K 的模型，它一次读三个文件就爆了，然后你会看到一堆莫名其妙的截断或者模型开始胡说。解决办法是别指望它自动探索，改用显式指定文件的方式，让它只看你点名的那几个。
二是工具调用能力。CLI 的核心是让模型输出结构化的工具调用指令（读文件、写文件、跑命令）。如果你的模型对这个格式支持不好，表现就是“它能聊天但不动手”，或者动手时参数格式总是错。这不是 CLI 的问题，换模型才能解决。
接远程服务时，额外的关注点是延迟。CLI 一个任务可能连续发起十几轮调用，每轮都带着完整上下文。单轮延迟 2 秒和 0.5 秒，在一个长任务上体感差异巨大。我用下来，交互式使用的话，单轮响应超过 5 秒就开始难受了。
4.3 沙箱与审批：两个必须一起看的配置
这两个是安全边界，配错了要么寸步难行，要么放得太开。
沙箱模式控制文件系统权限：
| 模式 | 可写范围 | 适合场景 |
|---|---|---|
read-only | 全部只读 | 让它做代码审查、理解架构 |
workspace-write | 当前工作区可写，系统目录只读 | 日常开发，推荐默认 |
danger-full-access | 不限制 | 只在完全隔离的环境里用 |
审批策略控制什么时候暂停问你：
| 策略 | 行为 |
|---|---|
untrusted | 只自动执行只读操作，其余全问 |
on-request | 模型自己判断要不要问，默认值 |
on-failure | 先跑，失败了再问 |
never | 全部放行，不问 |
我自己的组合是workspace-write+on-request。这个组合下，读文件、跑测试这类操作它自己就干了，涉及写文件和装依赖会停下来问一句。想更放手一点就切on-failure，但前提是你的仓库有 git 且已经提交干净——不然它改坏了你没处回滚。
注意：
danger-full-access加上never这个组合，等于给它一把没有刹车的车。我在一个一次性容器里试过一次，它为了跑通一个测试，试图去改系统里的一个配置文件。容器里无所谓，本地机器上这么干就是事故。
5. 真实项目里怎么用才不白折腾
装好只是开始，用得好不好差别很大。下面这几条是我踩出来的。
5.1 AGENTS.md 是全套配置里性价比最高的一个文件
在仓库根目录放一个AGENTS.md，CLI 启动时会自动读它，把它作为项目级指令。这个文件写得好不好，直接决定它第一次尝试的成功率。
我的写法是四段：
## 项目结构 - src/ 源码，按领域分模块 - tests/ 测试，命名 xxx_test.py - scripts/ 一次性脚本，不要改 ## 常用命令 - 跑测试：pytest tests/ -x - 类型检查：mypy src/ - 格式化：ruff format src/ ## 约定 - 不要新增第三方依赖，需要时先问我 - 所有公开函数写 docstring - 改动涉及数据库迁移时停下来 ## 禁止 - 不要改 .github/ 下的任何文件 - 不要执行 scripts/ 里的脚本关键在最后那段“禁止”。很多人只写“要做什么”，不写“不能做什么”，结果智能体为了完成任务，顺手把 CI 配置改了、把脚本跑了。把红线写进去，比事后从 diff 里挑出来省事得多。
5.2 任务粒度：一句话能干完的活别写成一段
我一开始的习惯是把需求写得很完整，像给同事写工单一样。结果反而效果差。原因是上下文一长，模型容易在中途跑偏，或者做了一堆你没要求但“看起来合理”的改动。
后来我改成这个原则：一个任务对应一次可独立验收的 diff。比如：
- 好：“把
parse_config里对空值的处理抽成一个辅助函数，其他逻辑不动” - 差：“重构配置模块，顺便把测试补上，再看看有没有性能问题”
后者它可能给你返回来一个 800 行的 diff，你光是看就得半小时，还不如自己写。
如果确实是大任务，拆开分多次，每次跑完用 git 提交一次。这样每一步都能回滚，出问题定位也快。
5.3 让它先读再写，别急着动手
有个小技巧：第一轮不要求它改代码，只要求它读。比如：
先读 src/parser.py 和 tests/test_parser.py，用三句话告诉我 现在的空值处理逻辑是什么，然后等我下一步指令。这一轮下来，你能验证两件事：它有没有找对文件、它理解得对不对。如果理解偏了，你直接纠正，成本很低。要是它一上来就开始改，你事后才发现方向错了，处理 diff 的成本高得多。
CLI 里也有直接查看改动的方式，改完之后先看 diff 再决定要不要接受，这个习惯要养成。我吃过一次亏：一次批量重命名，它把测试文件里的字符串字面量也一起改了，测试全绿但那个字符串是断言里的预期值，等于把断言改成了永远通过。这种问题只有人看 diff 才能发现。
5.4 非交互模式：放进脚本和流水线
codex exec是不带交互的一次性执行模式，适合塞进脚本：
codex exec "检查 src/ 下所有 TODO 注释，输出一份清单到 tmp/todos.md"这个模式下它会跑到结束就退出，不进入对话循环。适合做那种定时的、重复性的检查任务。用的时候把沙箱收紧到read-only更稳妥，因为脚本里没人盯着，它要是想写文件你也不知道。
6. 五个卡了我很久的细节
这部分是纯踩坑记录，按我遇到的顺序排。
6.1 沙箱写入被拒：报错位置和真实原因隔了一层
现象是它试图写一个文件，然后报了一个权限相关的错误，但那个文件明明在工作区里。
排查链路是这样的：先确认sandbox_mode是workspace-write；再确认出问题的文件路径确实在当前工作目录之下——注意这里是解析后的真实路径，不是逻辑路径。如果你的项目目录是个软链接，或者工作区里挂了一个指向外部的符号链接，它要写的实际位置就跑到沙箱外面去了。
我用pwd -P看真实路径才定位到问题：项目目录是个软链，实际指向另一个盘。解决方式要么把软链换成实体目录，要么把那个真实目录加进允许写入的范围里。
6.2 大仓库里上下文爆炸
在一个几万文件的 monorepo 里第一次跑，它花了很久，然后开始给出一些明显没读对文件的建议。
原因很直接：仓库太大，它的自动探索策略找不准相关文件，反复试错，每一轮都把大量无关内容塞进上下文。
三个应对办法，按效果排序：
- 在
AGENTS.md里写清楚模块划分和“改 A 模块只需要看 src/a/ 和 tests/a/” - 在提问时直接点名文件，别让它自己找
- 用子目录作为工作目录启动，把可见范围缩小
第三条最粗暴也最有效。我处理大仓库时经常cd到具体模块目录再启动，相当于给它画了个小圈。
6.3 凭证文件的泄漏风险
前面提过一次，这里再强调。~/.codex/auth.json和.env这类文件，一旦被误提交，清理起来很麻烦——光删掉文件是不够的，历史记录里还在。
我的做法是在全局 gitignore 里加：
.codex/ auth.json .env .env.local全局 gitignore 的位置在~/.config/git/ignore，配一次管所有仓库。比每个项目单独写省心。
另外，如果你用env_key那套方式接自己的服务，key 是放在环境变量里的，别顺手写进.bashrc然后把这个文件也提交了。
6.4 版本升级后配置字段改名
这个坑最隐蔽。某次升级之后，之前好好的配置突然不生效了，但也不报错——它就是安静地用回了默认值。
原因是配置的字段名在版本之间调整过。TOML 解析器对不认识的键默认忽略，所以你写了个旧名字，它当作没写。
我的应对：升级之后，第一时间把config.toml里每个字段对照一遍当前版本的文档。这件事看起来笨，但比事后排查“为什么我的配置没生效”快得多。更进一步，把配置文件也纳入版本管理（当然是脱敏后的那份），升级出问题时能立刻 diff。
6.5 Windows 下的路径与换行
在 Windows 上跑，有两个小问题会反复出现。
一是路径分隔符。它生成的路径有时是正斜杠有时是反斜杠，大多数情况无所谓，但在某些命令拼接的场景会失败。用 PowerShell 而不是老式 cmd，能减少这类问题。
二是换行符。如果仓库里混着 CRLF 和 LF，它跑格式化或者 diff 的时候会报一大堆“整个文件都改了”的假改动。在仓库根目录放一个.gitattributes，把所有文本文件统一成 LF，这类假 diff 就没了。
写到这里差不多了。最后说一个我自己感受最深的点：这套工具的价值不在于它能写多少代码，而在于它把“探索仓库—定位问题—改—验证”这个循环压得很短，短到你可以在一杯咖啡的时间里试完三种不同的改法。但它不会替你做判断——diff 还是得人看，方向还是得人定。我现在的用法基本是把它当成一个执行力很强但完全没有上下文的合作者：指令给得越具体、边界画得越清楚，它交付的东西就越能直接用；反过来，含糊的需求换来的就是一堆需要你自己收拾的改动。
