1. 先把 Codex 的四个概念摆到桌面上很多人第一次接触 Codex 的扩展体系时会把 Skills、Plugins、MCP 和 AGENTS.md 混成一锅粥结果配置写了一大堆真正跑起来却不知道哪一层在起作用。我先把这四个东西用一句话拆开AGENTS.md 是项目级工作守则约束所有任务Skill 是某一类任务的专项操作手册比如“文档审查”“接口排障”Plugin 是能力安装包把多个 Skill、MCP 配置、Hooks 和资源打包分发MCP 则是连接外部工具和数据源的接口层让模型能查数据库、读知识库、调 GitHub Issue。它们解决的不是同一个问题所以配置位置和加载时机也不一样。AGENTS.md 放在仓库根目录Codex 启动时就会读取Skill 放在.agents/skills/或.codex/skills/下按需渐进加载Plugin 通过.codex-plugin/plugin.json声明入口MCP 在.mcp.json或客户端配置里声明 server。把这四层分清楚之后你才能决定“这个需求到底该写在哪一层”。这篇文章要解决的核心场景是你希望 Codex 在多个项目之间复用同一套工作流同时用 TaoToken 统一管理 API Key 和模型通道避免每个项目、每个工具都去单独配一遍密钥。下面我会给出config.toml和AGENTS.md的可复制骨架再附一次本地调用验证动作让你把工作流真正落成可安装、可复用的配置。2. TaoToken 前置统一 Key 与 API 通道在动手写 Skill 和 Plugin 之前先把模型服务这一层固定下来。Codex 本身只负责工作流编排真正调用模型时仍然需要 base_url 和 API Key。如果你同时用多个 Agent 工具、多个项目每个地方都散落一份密钥维护成本会很高也容易在截图或提交时泄露。TaoToken 在这里扮演的角色是统一入口你只需要在它那边生成一个 Key然后在各个客户端的配置里指向同一个 API 通道。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。注意 API 地址后面不加 UTM 参数保持干净。具体操作上你需要先拿到一个可用的 Key。进入控制台后创建 API Key建议按项目或按用途分多个 Key方便后续排查和吊销。创建入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。拿到 Key 之后不要直接写进仓库里的配置文件而是通过环境变量注入这一点后面配置骨架里会体现。如果你只是想先验证模型通道是否通可以用模型对话页面快速发一条请求 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。确认通道没问题之后再回到 Codex 的配置文件里做接入。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各客户端的字段说明遇到字段对不上时可以对照查。3. 可复制配置config.toml 与 AGENTS.md 骨架3.1 config.toml 的模型通道配置Codex 的模型服务配置放在用户目录下的config.toml里。Windows 下路径是%USERPROFILE%\.codex\config.tomlmacOS 和 Linux 下是$HOME/.codex/config.toml。下面是一个可复制的骨架重点是base_url指向 TaoToken 的 API 端点Key 通过环境变量读取# ~/.codex/config.toml model gpt-5.6-luna [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api/v1 env_key TAOTOKEN_API_KEY [profiles.default] model_provider taotoken model gpt-5.6-luna这里有几个细节值得说明。base_url末尾的/v1是 OpenAI 兼容协议的标准路径TaoToken 的 API 端点本身是https://taotoken.net/api拼接后就是https://taotoken.net/api/v1。env_key告诉 Codex 从哪个环境变量读取密钥而不是把 Key 硬编码在文件里。设置环境变量的方式# macOS / Linux export TAOTOKEN_API_KEYsk-你的Key # Windows PowerShell $env:TAOTOKEN_API_KEYsk-你的Key如果你用的是长期编码或 Agent 场景建议了解一下 Coding Plan它更适合高频调用 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。配置字段如果和你本地版本对不上以接入文档为准。3.2 AGENTS.md 的项目级骨架AGENTS.md 放在仓库根目录Codex 启动时会自动读取。它约束的是“所有任务”的通用规则不要把某一类任务的细节塞进来。下面是一个可复制的骨架# AGENTS.md ## 项目概览 这是一个 TypeScript Node.js 的后端服务使用 pnpm 管理依赖。 ## 通用规则 - 所有代码改动必须附带对应的测试文件。 - 提交前运行 pnpm lint 和 pnpm test。 - 不要修改 generated/ 目录下的文件它们由代码生成器产出。 ## 目录约定 - src/ 放业务代码 - tests/ 放测试 - scripts/ 放一次性脚本 ## 禁止事项 - 不要在代码中硬编码任何密钥或 Token。 - 不要直接操作生产数据库。这个文件的作用是让 Codex 在每次任务开始前就知道项目的基本约束不需要你在每条提示词里重复。它和 Skill 的分工是AGENTS.md 管“所有任务都要遵守的规则”Skill 管“某一类任务按什么步骤做”。3.3 Skill 的最小结构与目录Skill 的最小结构是一个SKILL.md开头用 YAML frontmatter 描述名称和触发场景后面用 Markdown 写执行步骤--- name: doc-review description: Review Markdown documents for structure, factual accuracy, links, and unclear wording. Use when the user asks to review or improve documentation. --- 先读取目标文档。 检查关键结论是否有依据。 先报告具体问题再给出修改稿。 最后执行格式和链接检查。name要稳定、简洁通常用小写字母、数字和连字符。description要同时写清“能做什么”和“什么时候使用”后者太宽泛时 Codex 很难在正确的任务中选中它。一个常见的 Skill 目录如下doc-review/ ├── SKILL.md ├── scripts/ ├── references/ └── assets/scripts/放可执行校验脚本references/放按需读取的长文档assets/放模板和示例文件。入口文件保持短小让模型先掌握流程再按需读取细节。3.4 Plugin 的打包结构当你需要一次安装多个 Skill或者要把 Skill 和 MCP、Hooks 一起交付时就该用 Plugin 了。典型结构my-plugin/ ├── .codex-plugin/ │ └── plugin.json ├── skills/ │ └── doc-review/ │ └── SKILL.md ├── hooks/ │ └── hooks.json ├── .mcp.json └── assets/.codex-plugin/plugin.json是插件入口最小配置{ name: my-first-plugin, version: 1.0.0, description: Reusable documentation workflows, skills: ./skills/ }如果插件还要连接外部工具在.mcp.json中声明 MCP server。安装插件前应确认来源、工具范围和是否具有写入外部系统的能力。4. 验证请求一次本地调用确认通道打通配置写完之后不要急着写复杂的 Skill先用一次最小调用确认模型通道是通的。最直接的方式是用 curl 打一条请求curl -s https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: gpt-5.6-luna, messages: [ {role: user, content: 回复 OK 两个字母即可} ] }如果返回的 JSON 里有choices字段并且内容里包含OK说明 Key 和通道都没问题。这一步能帮你排除掉大部分“配置写了但跑不通”的情况。接下来验证 Codex 是否读到了 AGENTS.md 和 Skill。在项目根目录下启动 Codex然后发一条会触发 Skill 的提示词比如“帮我审查一下 README.md 的结构”。如果 Codex 自动匹配到了doc-review这个 Skill你会看到它按 SKILL.md 里的步骤执行先读取文档再检查结论依据然后报告问题最后做格式和链接检查。如果 Skill 没有被触发先检查目录位置。项目级 Skill 放在$REPO_ROOT/.agents/skills/或$REPO_ROOT/.codex/skills/用户级放在$HOME/.agents/skills/。如果希望同一个 Skill 未来也能被其他 Agent 识别优先用.agents/skills这类通用位置。不要让多个 Skill 使用同一个名称也不要在 Skill 中写入个人路径、密钥或只存在于某台机器上的脚本。5. 本篇常见错排查5.1 base_url 拼接错误最常见的报错是 404 或连接被拒。TaoToken 的 API 端点是https://taotoken.net/apiOpenAI 兼容协议需要拼上/v1所以config.toml里应该写https://taotoken.net/api/v1。如果你只写了https://taotoken.net/api请求会打到错误的路径上。反过来如果你写成了https://taotoken.net/api/v1/v1也会 404。5.2 环境变量没生效env_key指定的变量名必须和实际设置的环境变量名完全一致大小写敏感。如果你在config.toml里写了env_key TAOTOKEN_API_KEY但终端里设置的是TAOTOKEN_KEYCodex 读不到就会报鉴权失败。另外环境变量是在当前 shell 会话里生效的如果你换了终端窗口需要重新 export或者写进.bashrc/.zshrc。5.3 Skill 没有被触发Skill 的description写得太宽泛是主要原因。比如只写“帮助审查文档”Codex 很难判断什么时候该用它。应该写清触发条件和预期输出比如“当用户要求审查或改进 Markdown 文档时使用”。另外Skill 目录层级不能错SKILL.md必须在 Skill 名称目录下不能直接放在skills/根目录。5.4 Plugin 安装后 Skill 不生效检查plugin.json里的skills字段路径是否正确。如果写的是./skills/那skills/目录下应该直接是各个 Skill 目录而不是再套一层。另外升级 Codex 后要重新检查安装入口和配置字段避免把某一版本的界面当成永久标准。5.5 MCP 连接超时MCP server 的配置在.mcp.json里常见问题是 server 启动命令路径不对或者 server 本身需要额外的环境变量。先在终端里手动跑一遍 server 的启动命令确认它能正常起来再放进配置里。涉及外部系统写入、发消息或修改数据时保留人工确认环节。6. 把工作流落成可复用配置走到这里你已经有了一个可用的模型通道、一份项目级 AGENTS.md、一个最小 Skill以及验证通过的结果。接下来的路径取决于你的复用需求如果只是个人跨项目复用把 Skill 放到$HOME/.agents/skills/就够了如果团队要共享把 Skill 放进 Plugin随仓库版本管理如果需要连接外部数据源再在.mcp.json里声明 MCP server。长期编码和 Agent 场景下调用频率会明显上升这时候可以看看 Coding Plan 是否更适合你的用量 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。如果你在配置过程中遇到字段对不上或报错接入文档里有各客户端的完整字段说明 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。需要新建或轮换 Key 时API Keys 页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。我自己的习惯是先用一个小 Skill 验证流程等它稳定跑上一周再决定要不要升级成 Plugin。不要一上来就把所有规则塞进 AGENTS.md也不要把一次性的聊天偏好写成 Skill。分层清晰之后后面换模型、换工具、换项目都只需要改对应那一层工作流本身不用重写。 Codex Skills、Plugins 与 MCP 一文搞懂：用 TaoToken 统一 Key 打通 AGENTS.md 工作流
1. 先把 Codex 的四个概念摆到桌面上很多人第一次接触 Codex 的扩展体系时会把 Skills、Plugins、MCP 和 AGENTS.md 混成一锅粥结果配置写了一大堆真正跑起来却不知道哪一层在起作用。我先把这四个东西用一句话拆开AGENTS.md 是项目级工作守则约束所有任务Skill 是某一类任务的专项操作手册比如“文档审查”“接口排障”Plugin 是能力安装包把多个 Skill、MCP 配置、Hooks 和资源打包分发MCP 则是连接外部工具和数据源的接口层让模型能查数据库、读知识库、调 GitHub Issue。它们解决的不是同一个问题所以配置位置和加载时机也不一样。AGENTS.md 放在仓库根目录Codex 启动时就会读取Skill 放在.agents/skills/或.codex/skills/下按需渐进加载Plugin 通过.codex-plugin/plugin.json声明入口MCP 在.mcp.json或客户端配置里声明 server。把这四层分清楚之后你才能决定“这个需求到底该写在哪一层”。这篇文章要解决的核心场景是你希望 Codex 在多个项目之间复用同一套工作流同时用 TaoToken 统一管理 API Key 和模型通道避免每个项目、每个工具都去单独配一遍密钥。下面我会给出config.toml和AGENTS.md的可复制骨架再附一次本地调用验证动作让你把工作流真正落成可安装、可复用的配置。2. TaoToken 前置统一 Key 与 API 通道在动手写 Skill 和 Plugin 之前先把模型服务这一层固定下来。Codex 本身只负责工作流编排真正调用模型时仍然需要 base_url 和 API Key。如果你同时用多个 Agent 工具、多个项目每个地方都散落一份密钥维护成本会很高也容易在截图或提交时泄露。TaoToken 在这里扮演的角色是统一入口你只需要在它那边生成一个 Key然后在各个客户端的配置里指向同一个 API 通道。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。注意 API 地址后面不加 UTM 参数保持干净。具体操作上你需要先拿到一个可用的 Key。进入控制台后创建 API Key建议按项目或按用途分多个 Key方便后续排查和吊销。创建入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。拿到 Key 之后不要直接写进仓库里的配置文件而是通过环境变量注入这一点后面配置骨架里会体现。如果你只是想先验证模型通道是否通可以用模型对话页面快速发一条请求 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。确认通道没问题之后再回到 Codex 的配置文件里做接入。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各客户端的字段说明遇到字段对不上时可以对照查。3. 可复制配置config.toml 与 AGENTS.md 骨架3.1 config.toml 的模型通道配置Codex 的模型服务配置放在用户目录下的config.toml里。Windows 下路径是%USERPROFILE%\.codex\config.tomlmacOS 和 Linux 下是$HOME/.codex/config.toml。下面是一个可复制的骨架重点是base_url指向 TaoToken 的 API 端点Key 通过环境变量读取# ~/.codex/config.toml model gpt-5.6-luna [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api/v1 env_key TAOTOKEN_API_KEY [profiles.default] model_provider taotoken model gpt-5.6-luna这里有几个细节值得说明。base_url末尾的/v1是 OpenAI 兼容协议的标准路径TaoToken 的 API 端点本身是https://taotoken.net/api拼接后就是https://taotoken.net/api/v1。env_key告诉 Codex 从哪个环境变量读取密钥而不是把 Key 硬编码在文件里。设置环境变量的方式# macOS / Linux export TAOTOKEN_API_KEYsk-你的Key # Windows PowerShell $env:TAOTOKEN_API_KEYsk-你的Key如果你用的是长期编码或 Agent 场景建议了解一下 Coding Plan它更适合高频调用 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。配置字段如果和你本地版本对不上以接入文档为准。3.2 AGENTS.md 的项目级骨架AGENTS.md 放在仓库根目录Codex 启动时会自动读取。它约束的是“所有任务”的通用规则不要把某一类任务的细节塞进来。下面是一个可复制的骨架# AGENTS.md ## 项目概览 这是一个 TypeScript Node.js 的后端服务使用 pnpm 管理依赖。 ## 通用规则 - 所有代码改动必须附带对应的测试文件。 - 提交前运行 pnpm lint 和 pnpm test。 - 不要修改 generated/ 目录下的文件它们由代码生成器产出。 ## 目录约定 - src/ 放业务代码 - tests/ 放测试 - scripts/ 放一次性脚本 ## 禁止事项 - 不要在代码中硬编码任何密钥或 Token。 - 不要直接操作生产数据库。这个文件的作用是让 Codex 在每次任务开始前就知道项目的基本约束不需要你在每条提示词里重复。它和 Skill 的分工是AGENTS.md 管“所有任务都要遵守的规则”Skill 管“某一类任务按什么步骤做”。3.3 Skill 的最小结构与目录Skill 的最小结构是一个SKILL.md开头用 YAML frontmatter 描述名称和触发场景后面用 Markdown 写执行步骤--- name: doc-review description: Review Markdown documents for structure, factual accuracy, links, and unclear wording. Use when the user asks to review or improve documentation. --- 先读取目标文档。 检查关键结论是否有依据。 先报告具体问题再给出修改稿。 最后执行格式和链接检查。name要稳定、简洁通常用小写字母、数字和连字符。description要同时写清“能做什么”和“什么时候使用”后者太宽泛时 Codex 很难在正确的任务中选中它。一个常见的 Skill 目录如下doc-review/ ├── SKILL.md ├── scripts/ ├── references/ └── assets/scripts/放可执行校验脚本references/放按需读取的长文档assets/放模板和示例文件。入口文件保持短小让模型先掌握流程再按需读取细节。3.4 Plugin 的打包结构当你需要一次安装多个 Skill或者要把 Skill 和 MCP、Hooks 一起交付时就该用 Plugin 了。典型结构my-plugin/ ├── .codex-plugin/ │ └── plugin.json ├── skills/ │ └── doc-review/ │ └── SKILL.md ├── hooks/ │ └── hooks.json ├── .mcp.json └── assets/.codex-plugin/plugin.json是插件入口最小配置{ name: my-first-plugin, version: 1.0.0, description: Reusable documentation workflows, skills: ./skills/ }如果插件还要连接外部工具在.mcp.json中声明 MCP server。安装插件前应确认来源、工具范围和是否具有写入外部系统的能力。4. 验证请求一次本地调用确认通道打通配置写完之后不要急着写复杂的 Skill先用一次最小调用确认模型通道是通的。最直接的方式是用 curl 打一条请求curl -s https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: gpt-5.6-luna, messages: [ {role: user, content: 回复 OK 两个字母即可} ] }如果返回的 JSON 里有choices字段并且内容里包含OK说明 Key 和通道都没问题。这一步能帮你排除掉大部分“配置写了但跑不通”的情况。接下来验证 Codex 是否读到了 AGENTS.md 和 Skill。在项目根目录下启动 Codex然后发一条会触发 Skill 的提示词比如“帮我审查一下 README.md 的结构”。如果 Codex 自动匹配到了doc-review这个 Skill你会看到它按 SKILL.md 里的步骤执行先读取文档再检查结论依据然后报告问题最后做格式和链接检查。如果 Skill 没有被触发先检查目录位置。项目级 Skill 放在$REPO_ROOT/.agents/skills/或$REPO_ROOT/.codex/skills/用户级放在$HOME/.agents/skills/。如果希望同一个 Skill 未来也能被其他 Agent 识别优先用.agents/skills这类通用位置。不要让多个 Skill 使用同一个名称也不要在 Skill 中写入个人路径、密钥或只存在于某台机器上的脚本。5. 本篇常见错排查5.1 base_url 拼接错误最常见的报错是 404 或连接被拒。TaoToken 的 API 端点是https://taotoken.net/apiOpenAI 兼容协议需要拼上/v1所以config.toml里应该写https://taotoken.net/api/v1。如果你只写了https://taotoken.net/api请求会打到错误的路径上。反过来如果你写成了https://taotoken.net/api/v1/v1也会 404。5.2 环境变量没生效env_key指定的变量名必须和实际设置的环境变量名完全一致大小写敏感。如果你在config.toml里写了env_key TAOTOKEN_API_KEY但终端里设置的是TAOTOKEN_KEYCodex 读不到就会报鉴权失败。另外环境变量是在当前 shell 会话里生效的如果你换了终端窗口需要重新 export或者写进.bashrc/.zshrc。5.3 Skill 没有被触发Skill 的description写得太宽泛是主要原因。比如只写“帮助审查文档”Codex 很难判断什么时候该用它。应该写清触发条件和预期输出比如“当用户要求审查或改进 Markdown 文档时使用”。另外Skill 目录层级不能错SKILL.md必须在 Skill 名称目录下不能直接放在skills/根目录。5.4 Plugin 安装后 Skill 不生效检查plugin.json里的skills字段路径是否正确。如果写的是./skills/那skills/目录下应该直接是各个 Skill 目录而不是再套一层。另外升级 Codex 后要重新检查安装入口和配置字段避免把某一版本的界面当成永久标准。5.5 MCP 连接超时MCP server 的配置在.mcp.json里常见问题是 server 启动命令路径不对或者 server 本身需要额外的环境变量。先在终端里手动跑一遍 server 的启动命令确认它能正常起来再放进配置里。涉及外部系统写入、发消息或修改数据时保留人工确认环节。6. 把工作流落成可复用配置走到这里你已经有了一个可用的模型通道、一份项目级 AGENTS.md、一个最小 Skill以及验证通过的结果。接下来的路径取决于你的复用需求如果只是个人跨项目复用把 Skill 放到$HOME/.agents/skills/就够了如果团队要共享把 Skill 放进 Plugin随仓库版本管理如果需要连接外部数据源再在.mcp.json里声明 MCP server。长期编码和 Agent 场景下调用频率会明显上升这时候可以看看 Coding Plan 是否更适合你的用量 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。如果你在配置过程中遇到字段对不上或报错接入文档里有各客户端的完整字段说明 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。需要新建或轮换 Key 时API Keys 页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。我自己的习惯是先用一个小 Skill 验证流程等它稳定跑上一周再决定要不要升级成 Plugin。不要一上来就把所有规则塞进 AGENTS.md也不要把一次性的聊天偏好写成 Skill。分层清晰之后后面换模型、换工具、换项目都只需要改对应那一层工作流本身不用重写。