企业官网建设流程全解析

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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api 。注意 API 地址后面不加 UTM 参数，保持干净。

具体操作上，你需要先拿到一个可用的 Key。进入控制台后创建 API Key，建议按项目或按用途分多个 Key，方便后续排查和吊销。创建入口在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，Key 管理页面在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。拿到 Key 之后不要直接写进仓库里的配置文件，而是通过环境变量注入，这一点后面配置骨架里会体现。

如果你只是想先验证模型通道是否通，可以用模型对话页面快速发一条请求： https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。确认通道没问题之后，再回到 Codex 的配置文件里做接入。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各客户端的字段说明，遇到字段对不上时可以对照查。

3. 可复制配置：config.toml 与 AGENTS.md 骨架

3.1 config.toml 的模型通道配置

Codex 的模型服务配置放在用户目录下的config.toml里。Windows 下路径是%USERPROFILE%\.codex\config.toml，macOS 和 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_KEY="sk-你的Key" # Windows PowerShell $env:TAOTOKEN_API_KEY="sk-你的Key"

如果你用的是长期编码或 Agent 场景，建议了解一下 Coding Plan，它更适合高频调用： https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。配置字段如果和你本地版本对不上，以接入文档为准。

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/api，OpenAI 兼容协议需要拼上/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_KEY，Codex 读不到就会报鉴权失败。另外，环境变量是在当前 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_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。如果你在配置过程中遇到字段对不上或报错，接入文档里有各客户端的完整字段说明： https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。需要新建或轮换 Key 时，API Keys 页面在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。

我自己的习惯是先用一个小 Skill 验证流程，等它稳定跑上一周，再决定要不要升级成 Plugin。不要一上来就把所有规则塞进 AGENTS.md，也不要把一次性的聊天偏好写成 Skill。分层清晰之后，后面换模型、换工具、换项目，都只需要改对应那一层，工作流本身不用重写。