1. 为什么要在 VS Code、CLI 与 GitHub Actions 里统一 Codex 配置
Codex 这类编码代理真正难用的地方，往往不是模型本身，而是它在不同环境里各说各话。你在 VS Code 里让它改一个函数，它知道项目用 Next.js 14 的 App Router；可你切到终端用 CLI 跑同样的任务，它却开始给你推荐 Pages Router 的写法。等到了 GitHub Actions 流水线里，它连项目结构都读不全，生成的 CHANGELOG 全是套话。问题不在模型，在于每个入口拿到的上下文和通道都不一样。
我试过把同一套约定分别写进三个地方，结果维护成本高得离谱。后来发现更省事的做法是：用一份AGENTS.md作为项目级约定的唯一来源，让 VS Code 插件、CLI 和 Actions 都读它；再用统一的 Key 与 API 通道把三者的请求出口收敛到一处。这样无论你从哪个入口发起任务，Codex 看到的项目规则、模型 ID、鉴权方式都是一致的。
这篇内容适合已经在用 Codex、但被多环境配置割裂困扰的开发者。如果你还没配过 Codex，也可以跟着走一遍，因为下面每一步都是可复制的完整配置，不依赖你之前用过什么。核心检索词就三个：Codex 多环境统一配置、AGENTS.md 项目级约定、GitHub Actions 无头运行 Codex。搞懂这三件事，你就能把 Codex 从「偶尔用一下的玩具」变成日常开发流程里稳定的一环。
先说清楚三个入口各自的定位。VS Code 插件负责交互式改代码，你能看到 diff、能逐条确认；CLI 负责批量和脚本化任务，比如一次性重构某个目录、生成提交信息；GitHub Actions 负责无人值守的流水线任务，比如每次 push 后自动更新文档或跑代码审查。三者共用同一份AGENTS.md和同一个 API 通道，才不会出现「本地能跑、流水线报错」的尴尬。
2. TaoToken 前置准备：拿到统一 Key 与 API 通道
在动手改配置之前，先把通道准备好。Codex 的 CLI 和 Actions 都通过环境变量读取 Base URL 和 API Key，VS Code 插件在 BYO 模式下也会复用这套配置。所以只要把这两个值固定下来，三个入口就能指向同一个出口。
第一步是拿到 API Key。打开 TaoToken 的 API Keys 管理页，新建一个 Key，命名建议带上用途，比如codex-dev，方便以后按项目或环境区分。创建后立刻复制，页面刷新后就看不到完整值了。这个 Key 会同时用在本地 CLI、VS Code 插件和 GitHub Actions 的 secret 里。
第二步是确认 Base URL。Codex CLI 走的是 OpenAI 兼容协议，所以 Base URL 填https://taotoken.net/api即可，注意结尾不要多加/v1，CLI 会自己拼接路径。如果你在别的工具里见过带/v1的写法，那是那个工具的要求，Codex 这边按官方文档来。
第三步是确认 Model ID。不同任务适合不同模型，日常改代码用响应快的，复杂重构用推理强的。你可以在模型对话页面试一下，确认哪个模型 ID 可用，再把它写进配置。常见的做法是本地开发用一个通用模型，流水线里用更稳定的那个。
把这三个值记下来：Base URL、API Key、Model ID。后面每一处配置都会用到它们，而且要保持完全一致。很多人踩的坑就是本地填了一个模型、Actions 里填了另一个，结果同样的提示词在两个环境输出差异巨大，排查半天以为是代码问题。
注意：API Key 只放在环境变量或 GitHub Secrets 里，不要写进
AGENTS.md或任何会提交到仓库的文件。AGENTS.md是给模型看的项目约定，不是放密钥的地方。
如果你还没创建 Key，可以先到 API Keys 页面建一个；接入细节和参数说明在接入文档里有完整对照。这两个页面建议开着，配的时候随时核对。
3. 可复制配置：AGENTS.md、CLI 环境变量与 Actions 工作流
这一节是全文的核心，三份配置我都给完整片段，你直接改路径和 Key 就能用。先讲AGENTS.md，因为它是另外两个入口的上下文基础。
3.1 AGENTS.md 项目级约定片段
在项目根目录创建AGENTS.md，Codex 启动时会自动读取。它的作用是告诉模型这个项目是什么、用什么技术栈、有哪些不能碰的红线。写得越具体，模型越不容易跑偏。
# AGENTS.md ## 项目概述 这是一个基于 Next.js 14 + Prisma + PostgreSQL 的 SaaS 应用。 使用 App Router，不使用 Pages Router。 ## 技术栈 - 前端：Next.js 14, React 18, TailwindCSS, shadcn/ui - 后端：Next.js API Routes, Prisma ORM - 数据库：PostgreSQL 15 - 认证：NextAuth.js ## 重要约定 - 所有数据库操作必须通过 lib/db.ts 中的 prisma 实例 - API 路由错误统一用 lib/api-error.ts 处理 - 环境变量在 .env.local 中，参考 .env.example - 提交信息遵循 Conventional Commits ## 禁止事项 - 不要修改 prisma/schema.prisma，除非我明确要求 - 不要删除任何现有测试 - 生产环境的 .env 文件不要碰 - 不要引入新的状态管理库，现有方案已够用这份文件的关键在于「禁止事项」这一段。模型默认倾向于「帮你做得更多」，你不明确禁止，它就可能顺手重构一堆无关文件。把红线写清楚，能省掉大量 review 时间。
3.2 CLI 环境变量与配置
CLI 通过环境变量读取通道信息。你可以写进 shell 的配置文件，也可以用.env配合工具加载。最直接的方式是写进~/.zshrc或~/.bashrc：
export OPENAI_BASE_URL="https://taotoken.net/api" export OPENAI_API_KEY="sk-你的Key" export CODEX_MODEL="你的ModelID"改完执行source ~/.zshrc生效。然后验证 CLI 是否读到配置：
codex --version codex exec --help如果codex命令找不到，说明 CLI 还没装。用 npm 全局安装：
npm install -g @openai/codex装好后在项目根目录跑一个只读任务，确认它能读到AGENTS.md：
codex -a ask "这个项目用什么方式处理数据库连接？只回答，不要改文件"正常的话它会引用lib/db.ts里的 prisma 实例，说明AGENTS.md生效了。
3.3 GitHub Actions 工作流配置
流水线里跑 Codex 用的是无头模式，关键是三件事：装 CLI、注入 secret、执行任务。下面这份工作流每次 push 到 main 时自动更新 CHANGELOG：
name: Auto Update Changelog on: push: branches: [main] jobs: update-changelog: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '22' - name: Install Codex CLI run: npm install -g @openai/codex - name: Run Codex Task env: OPENAI_BASE_URL: ${{ secrets.OPENAI_BASE_URL }} OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} CODEX_MODEL: ${{ secrets.CODEX_MODEL }} CODEX_QUIET_MODE: 1 run: | codex exec --full-auto "根据最新 commits 更新 CHANGELOG.md，保持现有格式" - name: Commit changes run: | git config --local user.email 'action@github.com' git config --local user.name 'github-actions' git add CHANGELOG.md git commit -m 'chore: update changelog [skip ci]' || echo "no changes" git push三个 secret 要在仓库的 Settings → Secrets and variables → Actions 里配好，值和你本地环境变量完全一致。fetch-depth: 0是为了让 Codex 能读到完整提交历史，否则它只能看到最后一次 commit，生成的 CHANGELOG 会缺内容。
CODEX_QUIET_MODE: 1让输出更干净，适合流水线日志。--full-auto表示不需要人工确认，直接执行——这在无人值守环境里是必须的，但也意味着AGENTS.md的禁止事项要写得更严，防止它改到不该改的文件。
4. 验证请求：本地与流水线各跑一次
配置写完不验证，等于没配。这一节给你两个具体的验证动作，一个在本地，一个在流水线，跑通了才算真正打通。
4.1 本地 CLI 验证
在项目根目录执行一个会实际改文件的任务，但选一个安全的文件，比如让它给某个工具函数补注释：
codex exec --full-auto "给 utils/format.ts 里的每个导出函数补上 JSDoc 注释，不要改函数逻辑"跑完后用git diff看改动。重点检查三件事：它有没有只改utils/format.ts、有没有动函数签名、注释风格是否符合项目现有习惯。如果它顺手改了别的文件，说明AGENTS.md的禁止事项还不够明确，回去补上。
再验证一次会话恢复能力，这对长期任务很有用：
codex resume --last能恢复到上次会话上下文，说明 CLI 的会话管理正常。你可以在交互界面里用/export导出会话，第二天用/load恢复，适合跨天的大重构。
4.2 流水线验证
把工作流文件提交后，手动触发一次或等下次 push。到 Actions 页面看运行日志，重点看Run Codex Task这一步的输出。如果它成功改了CHANGELOG.md并提交，说明整条链路通了。
验证时容易忽略的一点是：流水线里的 Codex 读的是仓库里的AGENTS.md，不是你本地的。所以如果你本地改了AGENTS.md但没提交，流水线行为会和本地不一致。养成习惯，改完约定就提交。
另一个验证点是模型 ID。在 Actions 日志里搜一下实际用的模型，确认和 secret 里配的一致。有时候 secret 名字写错、或者值里多了空格，都会导致它 fallback 到默认模型，输出质量突然下降。
两次验证都通过后，你就有了一个三入口一致的 Codex 环境。本地改代码、CLI 跑批量任务、流水线做自动化，用的是同一套约定和同一个通道，不会再出现环境割裂的问题。
5. 常见报错排查：401、local proxy failed 与 reading choices
配置过程中最容易卡在几个固定报错上，这一节按真实错误信息给你排查路径。
5.1 401 Unauthorized
最常见的原因是 Key 没读到或读错了。先在本地确认环境变量生效：
echo $OPENAI_API_KEY echo $OPENAI_BASE_URL如果输出为空，说明 shell 配置没 source，或者写错了文件。如果输出正常但 CLI 仍报 401，检查 Key 是否被复制时带了空格或换行。重新从 API Keys 页面复制一次，注意不要多选字符。
流水线里的 401 通常是 secret 名字对不上。工作流里写的是secrets.OPENAI_API_KEY，那仓库 secret 就必须叫这个名字，大小写敏感。改完 secret 要重新触发工作流，旧的运行不会自动重读。
5.2 local proxy failed
这个报错一般出现在 Base URL 写错的时候。检查OPENAI_BASE_URL是不是https://taotoken.net/api，结尾不要带/v1，也不要有尾部斜杠。有些工具会自动拼/v1/chat/completions，你多写一层就变成/api/v1/v1/...，自然连不上。
如果你在本地同时开了别的网络工具，也可能干扰请求。先关掉再试，确认是配置问题还是环境问题。
5.3 reading choices 相关报错
这类报错通常是响应格式不符合预期，根源往往是模型 ID 写错或该模型不支持当前调用方式。确认CODEX_MODEL的值和你在模型对话页面验证过的一致。如果模型 ID 拼错，服务端可能返回一个结构不同的响应，CLI 解析时就报 reading choices 失败。
排查顺序建议是：先echo三个环境变量确认值，再用一个最简单的只读任务测试通道，最后才怀疑模型能力。大部分问题都出在前两步。
5.4 OAuth 与登录态冲突
如果你之前用账号登录过 VS Code 插件，又配了 API Key，可能出现登录态和 Key 冲突。VS Code 插件在 BYO 模式下会优先用 CLI 的配置，但如果你在插件里手动登录过，它可能走另一套鉴权。解决办法是在插件设置里确认走的是 API Key 模式，或者退出账号登录，让它复用 CLI 配置。
流水线里不会遇到 OAuth 问题，因为 Actions 环境是干净的，只认环境变量。所以本地和流水线行为不一致时，优先怀疑本地的登录态残留。
6. 把 Codex 稳定接入日常流程的下一步
三份配置跑通之后，你可以开始按任务类型分流。交互式改代码走 VS Code 插件，你能逐条 review diff；批量重构和脚本化任务走 CLI，配合会话导出做跨天任务；自动化文档、代码审查走 GitHub Actions，push 即触发。三者共用AGENTS.md和同一套 Key，维护成本降到最低。
如果你还在用零散的 Key 管理多个工具，建议把 Codex 相关的 Key 单独建一个，命名带codex前缀，方便在 API Keys 页面按用途筛选。模型 ID 也建议固定下来，写进团队文档，避免每个人本地配得不一样导致输出风格漂移。
长期做编码和 Agent 任务的话，可以了解一下 Coding Plan，它更适合高频、长周期的使用场景。需要核对模型能力时，直接到模型对话页面实测，比看参数表靠谱。接入过程中遇到通道问题，接入文档里有完整的参数对照和示例。
最后留一个实用习惯：每次改完AGENTS.md，先在本地 CLI 跑一个只读任务验证约定生效，再提交。这样流水线里的行为永远和本地一致，不会出现「本地好好的、CI 里乱改」的情况。
