企业官网建设流程全解析

1. 先搞清楚 Claude subagent 到底解决什么问题

Claude Code 里的 subagent，说白了就是给主对话配几个“专职外包”。你平时跟 Claude 聊需求、改代码，上下文越堆越长，到后面它容易忘事、串味，甚至把前面聊过的接口约定搞混。subagent 的思路是把某类固定活儿拆出去，交给一个独立上下文窗口里运行的子代理，它有自己的系统提示、自己的工具白名单、自己指定的模型，干完只把结果交回来。

这带来几个实际好处。第一是上下文隔离，子代理不会把主对话的历史全背进去，省 token 也省注意力。第二是职责单一，你可以做一个只读代码审查的 agent，工具只给 Read、Grep、Glob，它就没法乱改文件。第三是模型路由，简单活儿丢给便宜快的模型，复杂推理留给强模型，成本可控。第四是配置可复用，个人级 agent 放在用户目录下，跨项目都能用。

适合谁用？如果你已经在用 Claude Code 写代码，并且开始觉得“每次都要重复交代同一套审查规则”“主对话太长导致响应变慢变糊”，那 subagent 就是为你准备的。它不是什么新框架，本质就是一组 Markdown 配置文件，放在.claude/agents/目录里，Claude Code 启动时读取，遇到匹配的任务描述就自动委派。

我试过把代码审查和调试两个场景拆成独立 agent，主对话明显清爽了很多。下面从统一 Key 接入讲起，再一步步把 subagent 跑通。

2. 用 TaoToken 统一 Key 接入 Claude Code 的前置准备

Claude Code 默认走 Anthropic 官方端点，但很多开发者手里不止一个模型来源，希望用一个 Key 统一管理多模型调用。TaoToken 提供的就是这种统一接入层，你拿到一个 Key，配好 base URL，Claude Code 就能通过它调用模型，不用在多个平台之间来回切换配置。

需要准备的东西不多：一个 TaoToken 账号、一个 API Key、本机装好的 Claude Code。官网入口在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，注册后进控制台创建 Key。

创建 Key 的路径是控制台里的 API Keys 页面，直接访问 https://taotoken.net/console/api-keys 就能到。点新建，复制出来的那串就是你的凭证，注意它只完整显示一次，先存到安全的地方。

这里有个概念要分清：TaoToken 是统一接入层，不是让你绕过什么，它就是把多家模型的调用收敛到一个 Key 和一套端点上，方便你在 Claude Code、Coding Plan 这些工具里复用同一份凭证。接入文档在 https://taotoken.net/doc ，配置项和参数说明都在里面，遇到字段不确定时优先查它。

环境变量是最省事的接法。Claude Code 认ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN这两个变量，把 base URL 指向 TaoToken 的 API 地址，把 token 换成你的 Key，就完成了统一接入。API 地址是 https://taotoken.net/api ，注意这个地址不带任何查询参数。

3. settings.json 可复制配置骨架与 /agents 目录结构

Claude Code 的配置分两层：一层是模型接入，写在 settings.json 里；另一层是 subagent 定义，写在 agents 目录的 Markdown 文件里。先把接入层配好。

settings.json 通常放在~/.claude/settings.json（用户级）或项目里的.claude/settings.json（项目级）。下面是一份可复制的骨架，把env段填上你的实际值：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "你的_TaoToken_API_Key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" }, "permissions": { "allow": [], "deny": [] } }

ANTHROPIC_MODEL这一项决定主对话默认用哪个模型，你可以按需替换。如果不想写死在文件里，也可以直接用 shell 环境变量导出，效果一样：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_AUTH_TOKEN="你的_TaoToken_API_Key"

配完接入层，再来看 subagent 的目录结构。agents 有两个作用域：

每个 subagent 就是一个.md文件，文件名建议用英文短横线命名，比如code-reviewer.md。文件头部是 YAML frontmatter，定义 name、description、tools、model 四个关键字段，下面是系统提示正文。结构长这样：

--- name: code-reviewer description: 资深代码审查专家。主动审查代码，保障质量、安全与可维护性。在编写或修改代码后立即使用。 tools: Read, Grep, Glob, Bash model: inherit --- 你是一名资深代码审查员，负责确保代码质量与安全达到高标准。 调用时执行： 1. 执行 git diff 查看近期变更 2. 聚焦已修改的文件 3. 立即开始代码审查

model字段可以填具体模型名，也可以填inherit表示继承主对话的模型。tools是白名单，没列出的工具这个 agent 就用不了，这是做权限约束的关键。

4. 创建并调用 subagent 的完整验证步骤

配置就绪后，用/agents命令来创建和管理。在 Claude Code 终端里输入：

/agents

会弹出一个交互界面，列出当前已有的 agent，并提供创建入口。选Create new agent后，第一步是选作用域：

❯ 1. Project (.claude/agents/) 2. Personal (~/.claude/agents/)

选项目级就写进当前仓库的.claude/agents/，选个人级就写进~/.claude/agents/。接着按提示填功能描述、勾选可用工具、选模型，保存后一个 subagent 就建好了。它本质上就是生成了一个上面那种 Markdown 文件，你随时可以到对应目录手动改。

我建议先手动建一个文件来验证，比走交互界面更直观。在项目根目录执行：

mkdir -p .claude/agents

然后创建.claude/agents/code-reviewer.md，内容用上一节那份骨架。保存后重启 Claude Code，或者重新进入会话，让它重新加载配置。

验证是否被识别，输入/agents看列表里有没有code-reviewer。有就说明加载成功。接下来触发调用，最直接的方式是在对话里明确要求：

请用 code-reviewer 审查一下我刚改的代码

主对话会把任务委派给这个 subagent，它在独立上下文里执行git diff、读取变更文件、按清单输出反馈。你看到的返回是审查结论，而不是它内部的全部推理过程，这正是上下文隔离的体现。

再建一个调试 agent 做对照，文件.claude/agents/debugger.md：

--- name: debugger description: 专门处理错误、测试失败和异常行为的调试专家。遇到任何问题时主动使用。 tools: Read, Edit, Bash, Grep, Glob model: inherit --- 你是一名专注于根本原因分析的资深调试专家。 调用时执行： 1. 捕获错误信息和堆栈跟踪 2. 明确问题复现步骤 3. 定位故障位置 4. 实施最简修复方案 5. 验证解决方案有效

注意 debugger 的 tools 里带了Edit，因为它需要改代码；而 code-reviewer 故意不给Edit，保证它只审不改。这种工具白名单的差异，就是 subagent 做权限约束的实际用法。

5. 本篇常见报错与排查

报错一：/agents里看不到新建的 agent。最常见原因是文件放错目录。项目级必须在项目根目录的.claude/agents/下，个人级在~/.claude/agents/下，路径差一层就读不到。另外 frontmatter 的---必须是文件第一行，前面不能有空行或注释，否则解析失败。

报错二：调用时报 401 或认证失败。检查ANTHROPIC_AUTH_TOKEN是不是完整复制了，有没有多余空格或换行。Key 只在创建时完整显示一次，如果当时没存，回控制台重新生成一个。同时确认ANTHROPIC_BASE_URL写的是https://taotoken.net/api，不要多加斜杠或路径。

报错三：模型名不识别。ANTHROPIC_MODEL或 agent 里的model字段填了不存在的模型名。先用inherit继承主对话模型验证流程能跑通，再换成具体模型名。具体可用模型以接入文档 https://taotoken.net/doc 为准。

报错四：subagent 不自动触发。自动委派依赖description字段的语义匹配。如果描述写得太泛，主对话判断不出该不该委派。把 description 写具体，比如“在编写或修改代码后立即使用”“遇到测试失败时主动使用”，命中率会明显提高。实在不触发，就在对话里显式点名调用。

报错五：agent 想用某个工具却用不了。这是 tools 白名单在起作用，不是 bug。需要哪个工具就往tools里加，不需要的别加，保持最小权限。改完文件后重新加载会话生效。

排查时有个通用顺序：先确认文件路径和 frontmatter 格式，再确认 Key 和 base URL，最后确认模型名和 description。大部分问题出在前两步。

6. 把统一 Key 和 subagent 工作流固定下来

跑通之后，建议把配置沉淀成习惯。接入层用 TaoToken 统一 Key，主对话和各个 subagent 共用同一份凭证，换项目时只改 agents 目录，不用重复配 Key。需要管理或新建 Key 时走 https://taotoken.net/console/api-keys ，接入细节查 https://taotoken.net/doc 。

如果你主要做长期编码和 Agent 类任务，可以了解下 Coding Plan，把常用模型和额度规划好，访问 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。想先在网页里验证模型对话效果，用 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 直接试。

subagent 的价值不在功能多炫，而在于把重复的、边界清晰的活儿固化下来。我的做法是每个项目至少配一个 code-reviewer，工具只给读权限，每次改完代码顺手让它过一遍，比事后回头补审查省心得多。调试类 agent 按需加，别一上来堆一堆，先跑通一个再复制模式。