codex 使用技巧：用 AGENTS.md 与 skill 搭出可复用的 TaoToken 配置骨架

1. 为什么你的 codex 每次都要重新交代一遍规矩用 codex 写代码最让人抓狂的不是它不会写而是它每次都像新来的实习生你刚说完“别动 migrations 目录”下一个 thread 它又去改了你反复强调“改完先跑 pytest”它还是直接给你一段 diff 就完事。问题不在模型笨而在于你把长期规则塞进了每次的 prompt 里而 prompt 是易失的。我试过把同一套要求复制粘贴十几遍之后才想明白codex 真正好用的姿势是把它当成一个可配置的工程搭子分四层来管。当前任务写进 prompt长期规则沉淀到 AGENTS.md重复流程封装成 skill外部信息和并行验证交给 MCP 与 subagents。这篇就聚焦前三层再叠一个统一的 Key/API 通道骨架让你换项目时不用重配一遍。具体要落地的东西有三样一份可复制的 AGENTS.md、一个能跑的 skill、一份 config.toml 骨架。骨架里把模型通道指向 TaoToken 的统一入口这样你在 codex、脚本、其他 CLI 工具之间共用一套 Key不用每个工具单独维护一份配置。下面按“先讲清楚问题 → 再给配置 → 再验证 → 再排错”的顺序走你可以直接抄。2. 先把 TaoToken 的 Key 和通道准备好codex 本身是个客户端它需要一个能对话的模型通道。TaoToken 在这里扮演的角色就是统一入口一个 Key、一个 base_urlcodex 和你的脚本都指向它省得每个工具配一遍。这一步只做两件事拿 Key、记下地址。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台里创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 列表在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。创建时给它起个能认出来的名字比如codex-dev方便以后按项目吊销。注意Key 只在创建时完整显示一次复制后立刻存进环境变量或密钥管理工具别直接写进会提交到 git 的文件里。API 的基础地址是https://taotoken.net/api这个不带任何跟踪参数配置里就填它。模型名以控制台里当前可用的为准别照抄别人的旧列表。如果你只是想先验证通道通不通可以先用模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 发一条消息确认 Key 有效再往 codex 里接。把 Key 放进环境变量这是后面所有配置能复用的前提export TAOTOKEN_API_KEYsk-你的keyWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-你的key想持久化就写进系统环境变量。这一步做完config.toml 里就不用硬编码密钥了。3. 可复制的 AGENTS.md 与 config.toml 骨架3.1 AGENTS.md 放什么、不放什么AGENTS.md 是仓库级的长期规则codex 在项目里工作时会读它。判断标准很简单如果这句话你每次都要说就放 AGENTS.md如果这是一套完整流程做成 skill。它适合放仓库结构、运行方式、build/test/lint 命令、禁区、以及“什么算完成”的定义。在项目根目录建AGENTS.md下面这份可以直接改# AGENTS.md ## 项目结构 - src/ 业务代码 - tests/ 测试改动必须同步 - migrations/ 数据库迁移禁止手改 - scripts/ 确定性脚本机械活放这里 ## 常用命令 - 安装依赖: make install - 跑测试: make test - 格式化: make fmt - 类型检查: make typecheck ## 硬性约束 - 不要修改 migrations/ 下的任何文件 - 不要引入新的第三方依赖除非先说明理由 - 所有公开函数必须有类型标注 - 提交前必须通过 make fmt 和 make test ## 完成标准 - 改动后自行运行 make fmt、make test、make typecheck - 自查 diff确认没有无关改动 - 输出一段简短说明改了什么、为什么、怎么验证的这份文件的价值在于“始终生效”。你不再需要在每个 thread 开头重复“别改 migrations”codex 进项目就会读到。规则要短、要可执行别写成一篇架构文档否则它抓不住重点。3.2 config.toml 骨架把通道指向 TaoTokencodex 的配置放在~/.codex/config.tomlWindows 是%USERPROFILE%\.codex\config.toml。下面这份骨架把模型通道指向 TaoTokenKey 从环境变量读# ~/.codex/config.toml # 默认模型通道 model_provider taotoken model 你的模型名 [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api chat # 项目级规则文件codex 会自动读取仓库根目录的 AGENTS.md # 这里显式声明避免不同版本行为差异 project_doc AGENTS.md几个参数说明一下。base_url填https://taotoken.net/api不要带路径后缀。env_key指定从哪个环境变量读 Key这样配置文件可以安全地提交或分享。wire_api按你所用客户端版本支持的协议填常见是chat如果报协议不匹配就换成对应值。model填控制台里确认可用的名字。注意不同版本的 codex 对配置字段命名可能有差异如果启动时报未知字段先看它提示的合法字段名再对照调整别硬套。3.3 一个 skill 的目录结构skill 用来封装“会反复出现的工作流”。存放位置优先放仓库里的.agents/skills/这样团队和项目都能复用。一个 skill 一个窄任务目录长这样.agents/ skills/ code-change-verification/ SKILL.md scripts/ verify.shSKILL.md里的 description 不是介绍文案而是路由条件要写清“做什么 什么时候触发”。内容如下--- name: code-change-verification description: 当代码改动完成后运行格式化、lint、类型检查和测试并汇总结果。适用于任何修改了 src/ 或 tests/ 的任务收尾阶段。 --- # 代码改动验证 ## 触发条件 - 用户要求“验证改动”或“跑一遍检查” - 一次代码修改完成准备收尾 ## 步骤 1. 运行 scripts/verify.sh 2. 如果失败定位到具体文件与行号 3. 修复后重新运行直到全部通过 4. 输出通过项、失败项、修复说明 ## 输出格式 - 检查项列表与结果 - 若有失败给出最小修复建议配套的scripts/verify.sh把机械活固定下来让脚本做确定性的事模型只负责判断和解释#!/usr/bin/env bash set -e echo fmt make fmt echo typecheck make typecheck echo test make test echo 全部检查通过给它执行权限chmod x .agents/skills/code-change-verification/scripts/verify.sh。这样一套流程就被固化下来下次不用再口述。4. 验证一次 skill 调用与请求是否真的通了配置写完不验证等于没写。分两步先验证通道再验证 skill。4.1 验证 TaoToken 通道先用一条最小请求确认 Key 和 base_url 没问题curl https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: 你的模型名, messages: [{role: user, content: 只回复 ok}] }返回里能看到choices字段和内容就说明通道通了。如果返回 401是 Key 问题返回 404多半是 base_url 多写了路径返回模型不存在就是model名字和控制台对不上。4.2 验证 skill 被正确加载在项目里启动 codex先看它有没有识别到 skill。显式调用最稳直接输入$code-change-verification点名这个 skill。如果你的版本支持/skills也可以用斜杠命令列出当前可用技能。隐式调用则依赖 description你只要说“改完了帮我验证一下”它应该能路由过去。调用后观察两件事一是它有没有真的去执行scripts/verify.sh二是输出里有没有按 SKILL.md 约定的格式给出通过项和失败项。如果它只是嘴上说“建议你跑测试”却没动手说明 skill 没被触发回到 description 检查触发条件写得够不够明确。4.3 一次完整的改-测-审流程把三层串起来跑一遍在 codex 里提一个真实小改动比如给某个函数补类型标注。它会读 AGENTS.md 知道要跑make fmt和make test收尾时你点名 skill它执行 verify.sh 并汇总。整个过程你只说了一次需求规则和流程都来自配置。这就是“可复用骨架”的意义——换项目时复制 AGENTS.md 和.agents/skills/改一下 config.toml 的模型名就能接着用。5. 本篇常见报错排查5.1 401 Unauthorized最常见。先确认环境变量在当前 shell 里真的存在echo $TAOTOKEN_API_KEY。如果为空说明 export 只在另一个终端生效或者写进了没被加载的配置文件。config.toml 里的env_key名字要和实际环境变量名完全一致大小写敏感。5.2 404 或路径错误多半是base_url写成了https://taotoken.net/api/chat/completions这种带完整路径的形式。配置里只填到https://taotoken.net/api具体路径由客户端自己拼。多写一段就会 404。5.3 模型不存在model字段和控制台可用列表对不上。去控制台确认当前可用的模型名别用记忆里的旧名字。换模型后重启 codex 让配置生效。5.4 skill 不触发先确认目录结构对不对.agents/skills/skill-name/SKILL.md层级不能错。再确认 description 里有没有写清触发条件只写“代码验证”太模糊要写“当代码改动完成后……适用于……”。最后确认你调用时用的名字和目录名一致。5.5 AGENTS.md 没被读取确认文件在仓库根目录且 config.toml 里project_doc指向的文件名一致。如果你在子目录启动 codex它可能从当前目录往上找行为因版本而异稳妥做法是在仓库根目录启动。5.6 改了配置不生效codex 通常在启动时读配置。改完 config.toml 或环境变量后退出重进。环境变量改动尤其要注意已经打开的终端不会自动刷新。6. 把骨架沉淀下来下次直接复用这套东西跑顺之后你会发现真正省时间的不是某个神 prompt而是把重复的东西从对话里搬进了文件。AGENTS.md 管长期规则skill 管重复流程config.toml 管通道三者各司其职。换项目时把 AGENTS.md 和.agents/skills/一起复制过去改一下 config.toml 里的模型名通道继续用 TaoToken 的统一 Key几分钟就能开工。如果你还没配 Key从 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 建一个想先确认模型可用性用模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 发一条消息接入细节和字段说明看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。长期在 codex 里做编码和 Agent 任务的话Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 更适合按用量规划。骨架搭好剩下的就是让它替你干活。