1. 先搞清楚 Codex CLI 与 VS Code 插件到底在解决什么问题

很多人第一次接触 Codex，会把它当成"聊天框里帮我写个函数"的工具，用两天就放下了。真正让它变成生产力的是另一条路径：把它当成一个能读项目、能跑命令、能改多文件的命令行协作者。Codex CLI 是这条路径的核心，VS Code 插件则是把同一套能力搬进编辑器侧边栏。两者共享~/.codex/下的认证与配置，所以你在终端里调好的参数，插件里基本能复用。

我先把适用人群说清楚：如果你只是偶尔补全几行代码，编辑器自带的补全就够了；但如果你经常面对"这个报错在哪个文件、这个重构要动几个模块、这个脚本能不能直接跑一遍验证"这类任务，Codex CLI 的--search、沙箱执行、AGENTS.md项目约定就会明显省时间。它适合后端逻辑、脚本编排、跨文件重构，也适合把重复的排查动作写成可复用的命令。

从零上手到高阶，实际会卡在四个地方：一是认证方式选错，auth.json写错字段导致 401；二是config.toml里模型名、审批策略、沙箱模式三者互相打架；三是项目没有AGENTS.md，模型每次都要重新猜你的规范；四是本地网络层报local proxy failed这类错，看着像代码问题其实是通道问题。这篇就按"先跑通、再调优、再排障"的顺序走，每一步都给可复制的片段和验证动作。

统一 Key 与 API 通道这部分，我会用 TaoToken 作为示例接入点，因为它的 Base URL 和 Key 管理比较直观，适合把 CLI 和 VS Code 两条线一次配好。你完全可以在官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 完成注册后拿到 Key，再回到本文按步骤填。下面所有配置都以"能复制、能验证"为标准，不写空泛的"连上就能用"。

2. TaoToken 前置准备：Key、Base URL 与目录结构一次理清

在动config.toml之前，先把三样东西备齐：API Key、Base URL、你要用的 Model ID。这三件套在后面 CLI、VS Code、auth.json里会反复出现，先记在一个地方，避免来回翻。

第一步，打开 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 注册并登录，进入控制台。左侧找到 API Keys 入口，新建一个 Key，命名建议带上用途，比如codex-cli-mac，方便以后按设备吊销。Key 只在创建时完整显示一次，复制后先存到密码管理器。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console ，API Keys 页面是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys ，两个都带同一套归因参数，收藏哪个都行。

第二步，确认 Base URL。TaoToken 的 API 根地址是https://taotoken.net/api，注意这里不加任何查询参数，配置里就写这个纯地址。有些工具要求带/v1后缀，Codex 的wire_api走 responses 协议时，Base URL 填根地址即可，具体拼接由客户端完成。如果你在别的工具里看到https://taotoken.net/api/v1这种写法，那是那个工具的约定，不要混进 Codex 配置。

第三步，选 Model ID。Codex 场景常用的是编程向模型，你在控制台的模型列表里能看到当前可用的名称。把它原样抄进配置，大小写和连字符都不要改。模型名写错最典型的报错是返回里choices为空或者直接 404，后面排障章节会细说。

目录结构也要先建立认知。Codex 的用户级配置都在~/.codex/下：auth.json存认证，config.toml存全局参数，AGENTS.md可以放全局偏好。项目级则在仓库根目录放AGENTS.md，子目录还能再放一层覆盖。Windows 用户如果走 WSL2，路径就是 WSL 里的家目录，不要在 Windows 侧和 WSL 侧各配一份，容易互相覆盖。

注意：Key 不要写进项目仓库里的任何文件，auth.json和config.toml都在用户主目录，天然不进 Git。团队共享的是AGENTS.md，不是 Key。

环境要求顺带确认一下：Node.js 18 以上，macOS 12+、Ubuntu 20.04+ 或 Windows 11 的 WSL2。装 CLI 用npm install -g @openai/codex，装完codex --version能出版本号就说明二进制就位。这一步不涉及任何网络层特殊设置，如果 npm 装包慢，换国内镜像源即可，和后面的 API 通道是两回事。

3. 可复制配置：config.toml、auth.json 与 AGENTS.md 模板

这一节是全文的核心，三个文件配好，后面就是验证和排障。先给~/.codex/config.toml的完整模板，字段都有注释，你按需改值。

# ~/.codex/config.toml # 默认模型，填你在 TaoToken 控制台看到的 Model ID model = "gpt-5-codex" # 推理力度：low / medium / high，复杂重构建议 high model_reasoning_effort = "high" # 审批策略：untrusted 每次执行前询问；on-failure 沙箱失败时再问；never 全自动 approval_policy = "untrusted" # 沙箱模式：read-only 只读；workspace-write 可写工作区；danger-full-access 全盘 sandbox_mode = "workspace-write" # 关闭响应存储，减少不必要的往返 disable_response_storage = true # 走 responses 协议 wire_api = "responses" # 自定义 API 通道，Base URL 用纯根地址 [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY" # 安全档 profile：只读、低推理，适合陌生仓库先摸清结构 [profiles.safe_mode] model = "gpt-5-codex" approval_policy = "untrusted" sandbox_mode = "read-only" model_reasoning_effort = "low" # 全自动档 profile：信任的本地仓库做批量重构时用 [profiles.auto_mode] model = "gpt-5-codex" approval_policy = "never" sandbox_mode = "workspace-write" model_reasoning_effort = "high"

这里有个容易踩的点：env_key指定的是环境变量名，不是 Key 本身。你需要在 shell 里export TAOTOKEN_API_KEY="sk-..."，或者写进~/.zshrc/~/.bashrc。另一种方式是走auth.json，两者选其一即可，不要同时配导致来源冲突。

~/.codex/auth.json模板如下，字段名要和客户端预期一致：

{ "OPENAI_API_KEY": "sk-你的TaoToken密钥" }

如果你更习惯环境变量方式，auth.json可以只留空对象{}，让客户端从TAOTOKEN_API_KEY读取。实测下来，CLI 场景用环境变量更灵活，切换 Key 不用改文件；VS Code 插件场景用auth.json更省心，因为插件进程不一定继承你终端里的 export。

接着是项目根目录的AGENTS.md，这是给模型看的"项目说明书"，写得越具体，它越少犯低级错：

# AGENTS.md ## 项目简介 Next.js + TypeScript 的电商后台，包管理器用 pnpm，Node 20。 ## 开发规范 - 代码风格遵循 Prettier + ESLint，提交前必须过 lint。 - 组件与变量用驼峰命名，文件名用 kebab-case。 - 提交信息遵循 Conventional Commits，如 feat(cart): add coupon input。 ## 常用命令 - 启动开发：pnpm dev - 跑测试：pnpm test - 构建：pnpm build - 类型检查：pnpm tsc --noEmit ## 注意事项 - 禁止直接改 dist/ 下任何文件。 - 新增功能必须补对应单测，测试文件放同目录 __tests__。 - 改动涉及数据库 schema 时，先输出迁移方案再动手。

子目录可以再放一份AGENTS.md覆盖局部规则，比如src/server/AGENTS.md里写"本目录只允许改 service 层，controller 改动需在 PR 描述说明"。全局偏好放~/.codex/AGENTS.md，比如"回答用中文、代码注释用英文"。

VS Code 侧，插件安装后在设置里搜chatgpt.apiBase，填https://taotoken.net/api，再在chatgpt.config里补preferred_auth_method为apikey、model为你的 Model ID、wire_api为responses。插件和 CLI 共用~/.codex/auth.json，所以 Key 只需配一次。如果你用 Cline 这类支持 MCP 的插件，MCP server 配置里同样要写全 Base URL、Key、Model ID 三件套，缺一个就连不上。

4. 逐步验证：从 codex --version 到一次真实请求的成功回显

配置写完不算完，要一步步验证，每步都有明确的成功信号，出错时才能定位到具体环节。

第一步，验证 CLI 就位。终端执行codex --version，能打印版本号即通过。如果提示 command not found，检查 npm 全局 bin 是否在 PATH 里，npm bin -g看路径，再补进 shell 配置。

第二步，验证认证读取。执行codex login --api-key "sk-你的Key"，或者确认环境变量已 export 后直接进下一步。成功时不会有长篇输出，通常只提示已保存认证。如果这里就报 401，先别怀疑配置，去 TaoToken 控制台确认 Key 没过期、没被吊销、额度没耗尽。

第三步，最小请求验证。在任意空目录执行：

codex -m gpt-5-codex -c model_reasoning_effort="low" "用一句话说明当前目录下有哪些文件"

成功信号是模型返回一句描述，并且没有报错堆栈。这一步故意用low推理和只读意图，避免触发写操作审批。如果返回里出现choices相关错误，说明模型名或协议不对；如果出现连接类错误，看下一节。

第四步，验证项目约定生效。进入你的仓库根目录，执行：

codex "根据 AGENTS.md 的规范，告诉我跑测试的命令是什么"

如果它答出pnpm test而不是泛泛的npm test，说明AGENTS.md被正确加载。这一步很关键，很多人配了文件但模型没读到，就是因为文件不在仓库根目录，或者启动目录不对。

第五步，验证沙箱与审批。执行一个会写文件的任务：

codex -c approval_policy="untrusted" "在项目根目录新建 notes.md，写入今天的日期"

untrusted策略下，它应该先向你请求批准再写。你批准后文件出现，说明沙箱写权限和审批链路都通。如果它直接写了没问，检查config.toml里approval_policy是否被 profile 覆盖。

第六步，验证 VS Code 插件。打开命令面板，让插件发一条简单请求，比如"解释当前打开文件的用途"。成功回显说明插件侧的 Base URL、Key、Model ID 三件套都正确。插件报错时优先看输出面板里的请求日志，里面会带 HTTP 状态码，比界面提示有用得多。

六步走完，CLI 和插件两条线都通了。后面再调model_reasoning_effort、切 profile、加 MCP，都是在稳定底座上做增量，出问题也容易回滚。

5. 常见报错排查：401、local proxy failed、reading choices 与 OAuth 失败

排障的核心思路是"先分层，再看码"。Codex 的报错大致分四层：认证层、网络层、协议层、权限层。下面按真实报错逐条对。

401 Unauthorized。最常见，原因通常是 Key 无效、Key 与 Base URL 不匹配、或者auth.json字段名写错。先确认auth.json里是OPENAI_API_KEY这个键，不是api_key或token。再确认环境变量和文件不要同时存在且值不同，客户端读取优先级可能让你以为改了其实没生效。最后去控制台核对 Key 状态。修完后用第 4 节的第三步最小请求复验。

local proxy failed / connection refused。这类错看着吓人，本质是客户端连不上你配置的 Base URL。先curl -I https://taotoken.net/api看能否拿到响应头，如果 curl 通而 codex 不通，多半是客户端读到了旧的代理环境变量，比如HTTP_PROXY指向了一个已关闭的本地端口。清掉相关环境变量再试。如果 curl 也不通，检查本机 DNS 和出站规则，这一步和 Codex 配置无关。

reading choices / choices 为空。说明请求发出去了、也拿到了响应，但响应结构里没有预期的choices字段。三个高发原因：Model ID 拼错（比如把连字符写成下划线）、wire_api与通道不匹配（responses 协议却配了 chat 端点）、Base URL 多写了/v1导致路径重复。逐个核对第 3 节模板里的三个值，改完重启 CLI 再验。

OAuth 相关失败。如果你之前用过浏览器登录方式，auth.json里可能残留 OAuth 令牌，和 API Key 方式冲突。处理方式是清空auth.json只留OPENAI_API_KEY，或者删掉文件重新codex login --api-key。插件侧同理，在设置里把认证方式显式设为apikey，不要留自动。

权限被拒 / 沙箱写入失败。报错里带 sandbox 字样时，看sandbox_mode。read-only下任何写操作都会被拦，这是预期行为，不是 bug。需要写就切workspace-write，或者用--profile auto_mode启动。反过来，如果你发现它未经询问就改了文件，检查是不是 profile 把approval_policy覆盖成了never。

AGENTS.md 不生效。模型答非所问、忽略你的命令约定时，先确认启动目录就是仓库根目录，再确认文件名大小写完全一致。子目录规则只对在该子目录下发起的任务生效，跨目录任务读的是根目录那份。可以用第 4 节第四步的提问法快速自测。

把这几类错和对应层记住，下次看到报错先归类再动手，比盲目改配置快得多。每次改完只动一个变量，改完立刻用最小请求复验，这样能保证你始终知道是哪一处改动起了作用。

6. 把配置沉淀成团队资产：从单机调优到可复用工作流

单机跑通之后，真正拉开差距的是把配置变成团队可复用的东西。AGENTS.md天然适合进 Git，它是项目规范的一部分，新人 clone 下来就自带上下文。config.toml里的 profile 可以按场景固化：safe_mode给陌生仓库和代码审查用，auto_mode给信任的本地批量重构用，日常开发用默认档。这样你不用每次记一长串命令行参数，codex --profile safe_mode "..."一句话切换。

模型对话入口适合做方案讨论和提示词打磨，地址是 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat ，你在 CLI 里调好的模型名可以直接在这里对照验证。如果你长期做编码和 Agent 类任务，Coding Plan 页面 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan 有按周期计费的方案，比逐次调用更好估算成本。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc ，遇到协议细节以文档为准。Claude Code 用户如果要对照 Anthropic 兼容配置，参考 https://taotoken.net/claudecode-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode-anthropic 。

最后给一个我常用的习惯：每次升级 CLI 或插件版本后，重跑第 4 节的六步验证，尤其是第三步最小请求和第四步AGENTS.md生效检查。版本升级偶尔会改配置字段名，六步跑一遍比等出问题再回滚省事。配置文件和AGENTS.md都进版本管理，Key 永远留在用户目录，这条边界守住，团队协作就不会因为一把 Key 泄露而返工。