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 KeyVS 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即可注意结尾不要多加/v1CLI 会自己拼接路径。如果你在别的工具里见过带/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.mdCodex 启动时会自动读取。它的作用是告诉模型这个项目是什么、用什么技术栈、有哪些不能碰的红线。写得越具体模型越不容易跑偏。# 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或~/.bashrcexport OPENAI_BASE_URLhttps://taotoken.net/api export OPENAI_API_KEYsk-你的Key export CODEX_MODEL你的ModelID改完执行source ~/.zshrc生效。然后验证 CLI 是否读到配置codex --version codex exec --help如果codex命令找不到说明 CLI 还没装。用 npm 全局安装npm install -g openai/codex装好后在项目根目录跑一个只读任务确认它能读到AGENTS.mdcodex -a ask 这个项目用什么方式处理数据库连接只回答不要改文件正常的话它会引用lib/db.ts里的 prisma 实例说明AGENTS.md生效了。3.3 GitHub Actions 工作流配置流水线里跑 Codex 用的是无头模式关键是三件事装 CLI、注入 secret、执行任务。下面这份工作流每次 push 到 main 时自动更新 CHANGELOGname: Auto Update Changelog on: push: branches: [main] jobs: update-changelog: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - name: Setup Node.js uses: actions/setup-nodev4 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 actiongithub.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 Actionspush 即触发。三者共用AGENTS.md和同一套 Key维护成本降到最低。如果你还在用零散的 Key 管理多个工具建议把 Codex 相关的 Key 单独建一个命名带codex前缀方便在 API Keys 页面按用途筛选。模型 ID 也建议固定下来写进团队文档避免每个人本地配得不一样导致输出风格漂移。长期做编码和 Agent 任务的话可以了解一下 Coding Plan它更适合高频、长周期的使用场景。需要核对模型能力时直接到模型对话页面实测比看参数表靠谱。接入过程中遇到通道问题接入文档里有完整的参数对照和示例。最后留一个实用习惯每次改完AGENTS.md先在本地 CLI 跑一个只读任务验证约定生效再提交。这样流水线里的行为永远和本地一致不会出现「本地好好的、CI 里乱改」的情况。