1. 为什么你的 Codex 换个项目就“失忆”了很多人第一次用 Codex 写代码时都会遇到一个怪现象在 A 项目里它老老实实按你的规范跑pnpm typecheck换到 B 项目它就开始乱执行命令甚至想直接git push。这不是模型变笨了而是你根本没告诉它“这个项目的规矩是什么”。Codex 的配置体系其实分三层Skill负责“某类任务具体怎么做”AGENTS.md负责“这个项目的工作规范”Rules负责“哪些命令能执行、哪些要问、哪些直接禁”。这三者又各自有项目级和全局级两个存放位置搞混了就会出现“配置写了但不生效”的经典问题。这篇就围绕 Codex Rules 与 Skills 的项目级/全局级配置差异展开重点解决三件事Skill 放哪、AGENTS.md 放哪、Rules 放哪以及怎么用 TaoToken 的统一 Key 把 API 通道一次性接进settings.json骨架让项目级和全局级切换后都能正常跑通。适合正在用 Codex、准备给团队沉淀 Skill、或者被“配置不生效”折磨过的开发者。我试过把全局 Skill 和项目 Skill 混着放结果 Codex 匹配到了旧版本排查半天才发现是路径优先级的问题。下面按“先讲清楚结构再给可复制配置最后逐项验证”的顺序来。2. TaoToken 前置统一 Key 与 API 通道准备在动 Codex 配置之前先把 API 通道准备好。TaoToken 的作用是给你一个统一的 Key 和 API 入口这样项目级和全局级的settings.json里不用各写一套不同的地址切换项目时只改模型名或通道参数即可。你需要先拿到两样东西一个 API Key在控制台的 API Keys 页面创建形如sk-xxxx。API 基础地址https://taotoken.net/api注意这个地址不带任何查询参数直接作为 base URL 使用。创建 Key 的入口在这里https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite如果你还没决定用哪个模型可以先在模型对话页面试一下https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite长期跑编码任务或者 Agent 工作流的话Coding Plan 会更划算入口https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite拿到 Key 之后先别急着写进 Codex 配置用一条 curl 确认通道是通的curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}] }返回里有choices字段就说明 Key 和通道都正常。这一步很关键因为后面 Codex 配置出问题时你得先排除“是 Key 的问题还是配置的问题”。注意API 地址统一用https://taotoken.net/api不要在后面拼/v1之外的路径Codex 的 base URL 拼接逻辑和普通 SDK 略有不同。3. 可复制配置settings.json 骨架与目录结构Codex 的配置核心是settings.json部分版本叫config.toml本文以 JSON 骨架为主字段名按你的 Codex 版本微调。下面给出项目级和全局级两套骨架以及它们对应的目录结构。3.1 项目级目录结构项目级配置放在仓库根目录随 Git 提交团队共享viewport-lab/ ├── AGENTS.md ├── .agents/ │ └── skills/ │ └── deploy-dev-machine/ │ ├── SKILL.md │ ├── references/ │ │ └── deployment.md │ └── scripts/ │ └── deploy.sh ├── .codex/ │ ├── settings.json │ └── rules/ │ └── default.rules └── src/项目级settings.json骨架{ model: gpt-4o-mini, provider: { name: taotoken, base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY }, skills: { paths: [.agents/skills] }, rules: { paths: [.codex/rules] }, instructions: { paths: [AGENTS.md] } }这里把 Key 通过环境变量TAOTOKEN_API_KEY注入而不是硬编码在 JSON 里。原因很简单项目级配置要提交到 Git硬编码 Key 等于把钥匙贴在门上。export TAOTOKEN_API_KEYsk-你的Key3.2 全局级目录结构全局级配置放在用户目录对所有项目生效~/ ├── .codex/ │ ├── AGENTS.md │ ├── settings.json │ └── rules/ │ └── default.rules └── .agents/ └── skills/ ├── commit-staged-changes/ │ └── SKILL.md └── frontend-review/ └── SKILL.md全局级settings.json骨架{ model: gpt-4o-mini, provider: { name: taotoken, base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY }, skills: { paths: [~/.agents/skills] }, rules: { paths: [~/.codex/rules] }, instructions: { paths: [~/.codex/AGENTS.md] } }两套骨架的 provider 部分完全一致这就是统一 Key 的价值项目级和全局级共用同一个 API 通道切换时只改skills.paths和rules.paths的指向。3.3 AGENTS.md 与 Rules 的职责边界很多人把 AGENTS.md 和 Rules 搞混这里用一张表说清楚配置项解决的问题项目级位置全局级位置Skill某类任务怎么做.agents/skills/~/.agents/skills/AGENTS.md项目工作规范仓库根目录~/.codex/AGENTS.mdRules命令执行权限.codex/rules/~/.codex/rules/AGENTS.md 写的是“这个项目用 pnpm 不用 npm”“提交前必须跑 typecheck”这类规范Rules 写的是“pnpm typecheck允许直接跑”“git push每次都要问”“git reset --hard直接禁”。前者是软约束后者是硬权限。一个典型的default.rules内容prefix_rule( pattern [pnpm, typecheck], decision allow, justification 项目类型检查是安全的只读验证, ) prefix_rule( pattern [pnpm, deploy:dev-machine], decision prompt, justification 部署会更新开发机需要用户确认, ) prefix_rule( pattern [git, push], decision prompt, justification 推送会修改远端仓库, ) prefix_rule( pattern [git, reset, --hard], decision forbidden, justification 可能清除未提交修改禁止执行, )三种决策的含义allow直接放行prompt每次询问forbidden直接拒绝。3.4 Skill 的渐进式加载与 SKILL.md 写法Codex 不会一次性读完所有 Skill 文件而是分四步先扫描目录收集name和description再根据任务匹配 description匹配上才读完整的SKILL.md最后按SKILL.md里的引用按需加载references/、scripts/、assets/。所以SKILL.md的头部必须写清楚触发条件--- name: deploy-dev-machine description: 将 Viewport Lab 部署到公司开发机适用于需要更新开发环境版本的场景 --- ## 部署流程 部署前完整阅读 references/deployment.md。 执行部署时优先运行 scripts/deploy.sh。 如果环境变量缺失参考 assets/env.example 补齐。关键点没有被SKILL.md引用的文件Codex 不一定会主动读。所以references/和scripts/必须在正文里显式点名。4. 验证请求项目级与全局级切换后的生效核对配置写完不代表生效必须逐项验证。下面给出项目级和全局级各自的验证动作。4.1 验证项目级 Skill 被识别进入项目目录启动 Codex输入显式触发$deploy-dev-machine如果 Skill 配置正确Codex 会读取.agents/skills/deploy-dev-machine/SKILL.md并开始执行部署流程。如果没反应先检查.agents/skills/路径是否写对再检查SKILL.md的name字段是否和触发词一致。隐式触发测试输入“帮我把 Viewport Lab 更新到开发机”Codex 应该匹配到 description 并调用同一个 Skill。4.2 验证项目级 Rules 生效在项目里让 Codex 执行一条被forbidden的命令请执行 git reset --hard预期结果是 Codex 拒绝执行并给出 justification。如果它真的执行了说明.codex/rules/default.rules没被加载检查settings.json里rules.paths是否指向.codex/rules。再测prompt级别的命令请执行 git push预期是 Codex 弹出确认而不是直接推送。4.3 验证全局级配置在任意项目生效切到一个没有.codex/目录的空项目启动 Codex输入全局 Skill 的触发词比如$commit-staged-changes。如果全局 Skill 被识别说明~/.agents/skills/路径生效。再测全局 Rules在空项目里让 Codex 执行git reset --hard应该同样被拒绝因为全局~/.codex/rules/default.rules对所有项目生效。4.4 验证 API 通道走的是 TaoToken最直接的验证方式是看请求日志。在 Codex 里发一条普通对话然后检查你的 TaoToken 控制台用量是否增加。如果用量没动说明请求没走 TaoToken 通道大概率是base_url写错或者环境变量没注入。echo $TAOTOKEN_API_KEY如果输出为空说明环境变量没设置Codex 会拿不到 Key。5. 本篇常见错排查5.1 Skill 写了但 Codex 不调用最常见的原因是description写得太模糊。Codex 靠 description 做语义匹配如果写“处理部署相关任务”它很难判断什么时候该用。改成“将 Viewport Lab 部署到公司开发机适用于需要更新开发环境版本的场景”匹配率会明显提升。第二个原因是SKILL.md的name字段和目录名不一致。显式触发$deploy-dev-machine时Codex 找的是name字段不是目录名。5.2 Rules 不生效先确认settings.json里rules.paths的路径是相对项目根目录还是绝对路径。项目级用相对路径.codex/rules全局级用~/.codex/rules。路径写错是最常见的原因。第二个原因是 Rules 文件扩展名。有些版本要求.rules后缀有些接受.txt按你的 Codex 版本文档来。5.3 项目级和全局级配置冲突当项目级和全局级都有同名 Skill 时项目级优先。但如果你发现全局 Skill 覆盖了项目 Skill检查settings.json里skills.paths的顺序靠前的路径优先级更高。AGENTS.md 同理项目根目录的 AGENTS.md 优先于~/.codex/AGENTS.md。Codex 从项目根目录开始向上查找找到第一个就停。5.4 API 返回 401 或 403先确认 Key 有没有过期再去控制台重新生成一个。然后确认base_url是https://taotoken.net/api不要多写或少写路径。最后确认环境变量在启动 Codex 的同一个 shell 里 export 了而不是在另一个终端窗口。export TAOTOKEN_API_KEYsk-你的Key codex如果是在 IDE 插件里用 Codex环境变量可能需要在插件设置里单独配置而不是系统环境变量。5.5 Skill 的 references 没被读取回到SKILL.md确认正文里显式写了“部署前完整阅读 references/deployment.md”这类指令。Codex 不会自动扫描references/目录必须由SKILL.md点名。6. 配好之后怎么继续用项目级配置适合随仓库共享团队拉下来就能用同一套 Skill 和 Rules全局级配置适合你个人的通用习惯比如提交前检查、代码审查模板。两者共用同一个 TaoToken Key 和 API 通道切换项目时不用改 provider 部分。如果你在接入过程中遇到 Key 或通道问题直接去 API Keys 页面重新生成一个最快https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite配置字段的完整说明在接入文档里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite想先验证模型输出再写进配置的话模型对话页面可以直接试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite长期跑编码任务建议上 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite最后提醒一句Rules 目前还不是特别稳定没有特殊需求不用一开始就写一堆。先把 Skill 和 AGENTS.md 跑通等真正遇到“Codex 乱执行命令”的问题时再针对性加 Rules这样排查起来也简单。
