如何沉淀 Skill：Codex 和 WorkBuddy 用户实战指南（TaoToken 配置篇）-育师

1. 为什么 Codex 和 WorkBuddy 用户都在聊 Skill 沉淀

如果你已经在用 Codex CLI 或 WorkBuddy 写代码，大概率经历过这样的场景：每次让 AI 帮你生成提交信息，都要重新描述一遍格式要求；每次让它跑测试并总结失败用例，都要把同样的指令再打一遍。这些重复劳动本身不复杂，但累积起来非常消耗注意力。

Skill 就是解决这个问题的机制。它把反复使用的指令、参考资料、脚本和判断逻辑打包成一个可被 AI 自动识别和调用的模块。和一次性 Prompt 最大的区别在于：Prompt 是消耗品，每次对话都要重新表述；Skill 是资产，写一次就能反复触发。

Codex CLI 的 Skill 体系标准化程度较高，核心文件是 SKILL.md，配合 scripts/、references/、assets/ 等可选目录。WorkBuddy 同样基于 SKILL.md 的理念，支持子 Skill 编排，面向国内开发者的使用习惯做了适配。两者在文件结构上高度相通，学会一种再迁移到另一种几乎没有门槛。

但很多人在实际落地时会卡在同一个地方：工具侧的 API 通道配置。Codex CLI 需要 settings.json 或 config.toml 来指定模型接入点，WorkBuddy 的插件侧也需要类似的配置。如果每个工具都单独管理 Key，不仅麻烦，还容易在切换时出错。这篇内容聚焦的就是：如何用 TaoToken 统一 Key/API 通道，把 Codex 和 WorkBuddy 的 Skill 沉淀流程一次跑通。

适合谁看：已经用过 Codex CLI 或 WorkBuddy 至少一周，手头有至少一件重复做过三次以上的任务，想把它固化成 Skill 的开发者。不需要你懂 Rust 或深入理解 Agent 架构，跟着配置走就行。

2. TaoToken 前置：统一 Key 与 API 通道

在写 SKILL.md 之前，先把工具侧的接入通道理顺。Codex CLI 和 WorkBuddy 各自有独立的配置文件，如果分别去申请和管理 Key，后续维护成本会随着工具数量增加而上升。TaoToken 的作用是提供一个统一的 API 入口，让不同工具共用同一套 Key 和接入地址。

你需要先拿到一个可用的 API Key。访问 TaoToken 控制台创建：

https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite

创建完成后，在 API Keys 页面复制你的 Key：

https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite

API 基础地址统一使用：

https://taotoken.net/api

注意这个地址后面不加 UTM 参数，直接作为 base_url 填入工具配置即可。模型名称根据你实际使用的模型填写，比如 claude-sonnet-4-20250514 或 gpt-4o 等，具体以 TaoToken 文档中的模型列表为准：

https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite

拿到 Key 和 base_url 之后，接下来的配置就围绕这两个值展开。Codex CLI 侧我们改 config.toml，WorkBuddy 侧我们改 settings.json 或插件配置。两边共用同一个 Key，后续换模型或调整通道时只需要改一处。

3. 可复制配置：Codex 与 WorkBuddy 的 settings.json / config.toml 骨架

3.1 Codex CLI 的 config.toml 配置

Codex CLI 的配置文件通常位于~/.codex/config.toml。如果你还没有这个文件，手动创建即可。以下是一个可复制的骨架，把your_api_key_here替换成你在 TaoToken 控制台创建的 Key：

# ~/.codex/config.toml [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY" [profiles.default] model_provider = "taotoken" model = "claude-sonnet-4-20250514"

然后在你的 shell 配置文件（.bashrc、.zshrc或.profile）中导出环境变量：

export TAOTOKEN_API_KEY="your_api_key_here"

这样配置的好处是 Key 不直接写在 config.toml 里，避免误提交到 Git 仓库。Codex CLI 启动时会读取TAOTOKEN_API_KEY环境变量，并通过base_url指向 TaoToken 的 API 入口。

如果你更习惯把 Key 直接写在配置文件里，也可以用下面这种简化写法，但不推荐在多人协作的机器上使用：

[model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" api_key = "your_api_key_here" [profiles.default] model_provider = "taotoken" model = "claude-sonnet-4-20250514"

3.2 WorkBuddy 的 settings.json 配置

WorkBuddy 的 VS Code 插件侧配置通常放在项目根目录的.workbuddy/settings.json或用户全局配置目录中。以下骨架可以直接复制，替换 Key 即可：

{ "apiProvider": "taotoken", "apiBaseUrl": "https://taotoken.net/api", "apiKey": "your_api_key_here", "defaultModel": "claude-sonnet-4-20250514", "skills": { "enabled": true, "scanPaths": [ ".workbuddy/skills", "~/.workbuddy/skills" ] } }

scanPaths告诉 WorkBuddy 去哪里扫描 SKILL.md 文件。项目级 Skill 放在.workbuddy/skills/下，用户全局 Skill 放在~/.workbuddy/skills/下。同名 Skill 不会合并，而是都会出现在选择器中，这一点和 Codex 的层级覆盖逻辑一致。

3.3 CC Switch 与 Cline 接入片段

如果你同时使用 CC Switch 或 Cline 作为辅助工具，它们也可以共用同一个 TaoToken Key。CC Switch 的配置片段如下：

{ "provider": "taotoken", "baseUrl": "https://taotoken.net/api", "apiKey": "your_api_key_here", "models": ["claude-sonnet-4-20250514", "gpt-4o"] }

Cline 的配置在 VS Code 设置中搜索cline.apiProvider，选择自定义 Provider，填入：

Base URL: https://taotoken.net/api API Key: your_api_key_here Model: claude-sonnet-4-20250514

这样 Codex、WorkBuddy、CC Switch、Cline 四个工具共用同一个 Key 和 base_url，后续换模型或调整通道时只需要改一处，不用逐个工具去更新。

4. 验证请求：确认 Skill 加载与调用生效

配置写完之后，不要急着写复杂的 SKILL.md，先用一个最小 Skill 验证整条链路是否跑通。

4.1 创建最小 SKILL.md

在 Codex 的项目目录下创建.agents/skills/hello-skill/SKILL.md：

--- name: hello-skill description: 当用户输入"打个招呼"或"hello skill"时触发，输出当前项目名称和一句问候。 --- # Hello Skill ## 触发条件 用户输入包含"打个招呼"或"hello skill"时触发。 ## 执行步骤 1. 读取当前工作目录的名称。 2. 输出："你好，当前项目是 {项目名}，Skill 已生效。"

WorkBuddy 侧在.workbuddy/skills/hello-skill/SKILL.md放入同样内容即可。

4.2 验证 Skill 是否被扫描到

Codex CLI 中运行：

codex /skills

如果配置正确，你应该能在列表中看到hello-skill。如果没看到，检查scanPaths或.agents/skills/目录是否存在，以及 SKILL.md 的 frontmatter 格式是否正确。

WorkBuddy 中打开命令面板，搜索WorkBuddy: List Skills，同样应该看到hello-skill。

4.3 验证 Skill 是否被正确触发

在 Codex CLI 中输入：

打个招呼

预期输出类似：

你好，当前项目是 my-project，Skill 已生效。

如果 Codex 没有触发 Skill，而是直接回答了一个通用问候，说明 description 的匹配逻辑没有命中。这时候把 description 改得更具体，比如加上"必须包含'打个招呼'四个字"。

4.4 验证 API 通道是否走通

如果 Skill 加载成功但调用时报错，大概率是 API 通道的问题。用 curl 直接测试 TaoToken 的接口：

curl -X POST https://taotoken.net/api/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: $TAOTOKEN_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "claude-sonnet-4-20250514", "max_tokens": 100, "messages": [{"role": "user", "content": "回复 OK"}] }'

如果返回中包含正常的模型回复内容，说明 Key 和 base_url 都正确。如果返回 401，检查 Key 是否复制完整；如果返回 404，检查 base_url 是否多了或少了路径段。

4.5 验证 Skill 内的脚本调用

在 SKILL.md 中引用 scripts/ 目录下的脚本时，确保脚本有可执行权限：

chmod +x .agents/skills/hello-skill/scripts/check.sh

然后在 SKILL.md 中这样引用：

## 执行步骤 1. 运行 `scripts/check.sh`，获取当前环境状态。 2. 根据脚本输出决定后续步骤。

Codex 在执行时会自动解析相对路径。如果脚本没有执行，检查 SKILL.md 中的路径是否相对于 Skill 根目录。

5. 本篇常见错排查

5.1 Skill 不触发

最常见的原因是 description 写得太模糊。比如写"处理代码相关任务"，这种描述几乎匹配所有输入，导致要么误触发要么不触发。正确做法是穷举用户可能说的具体表达，比如"当用户输入包含'生成提交信息'或'commit message'时触发"。

另一个原因是 Skill 文件位置不对。Codex 会从$CWD/.agents/skills/、$REPO_ROOT/.agents/skills/、$HOME/.agents/skills/三个位置扫描，确认你的 SKILL.md 在这三个路径之一下面。

5.2 API 返回 401 或 403

先检查环境变量是否生效：

echo $TAOTOKEN_API_KEY

如果输出为空，说明 shell 配置文件没有 source 或者写错了文件。运行source ~/.zshrc（或对应文件）后重试。

如果环境变量正常但依然 401，检查 Key 是否在 TaoToken 控制台被禁用或过期。重新创建一个 Key 并更新环境变量。

5.3 config.toml 解析报错

Codex CLI 对 TOML 格式比较严格。常见错误包括：字符串没有加引号、节名拼写错误、缩进使用了 Tab 而不是空格。用codex --config-check可以快速定位格式问题。

5.4 WorkBuddy 扫描不到 Skill

检查 settings.json 中的scanPaths是否包含了你的 Skill 目录。如果路径中有~，确认 WorkBuddy 是否正确展开了用户目录。建议先用绝对路径测试，确认能扫描到之后再换成相对路径或~。

5.5 Skill 触发了但执行结果不对

这种情况通常是 SKILL.md 中的步骤描述不够具体。比如写"运行测试并总结"，AI 可能只运行了部分测试就总结。改成"运行npm test，等待退出，读取完整输出，提取所有 FAIL 行，按文件分组总结"。

另一个可能是参考文件没有放对位置。SKILL.md 中引用的references/或scripts/路径必须相对于 Skill 根目录，不能相对于当前工作目录。

5.6 多个工具之间 Key 冲突

如果你在 Codex 和 WorkBuddy 中使用了不同的 Key，切换时容易混淆。建议统一使用同一个 TaoToken Key，通过环境变量注入。如果确实需要区分，可以在 Key 名称上做标记，比如taotoken-codex和taotoken-workbuddy，但 base_url 保持一致。

6. 把 Skill 沉淀变成日常习惯

配置跑通之后，真正的功夫在持续迭代。第一版 SKILL.md 几乎一定有问题，这很正常。每次用完 Skill 之后，花三十秒问自己三个问题：这次触发对了吗？AI 哪一步没按预期做？我手动补了什么指令？把答案写回 SKILL.md，下一次就会更顺。

Codex 内置了$skill-creator和$skill-installer两个 Skill，前者帮你交互式创建新 Skill，后者帮你从社区安装。WorkBuddy 侧虽然没有完全对应的内置工具，但 SKILL.md 的格式是通用的，你可以直接把 Codex 社区里的 Skill 迁移过来。

如果你在配置过程中遇到 API 通道的问题，优先检查 TaoToken 的接入文档和 API Keys 页面。模型对话功能可以用来快速验证 Key 是否有效：