1. 为什么你的 Claude Code 需要一套专家角色库Claude Code 本身已经是个很强的编码助手但默认状态下它更像一个什么都懂一点的通用工程师。你问它帮我审查这段认证代码它大概率会回你一串正确但没法直接落地的建议注意 SQL 注入、做好输入校验、记得上 HTTPS。问题是你的项目用的是 ORM压根没有原生 SQL这些建议听着都对却一条都用不上。根因不在模型能力而在上下文。同一段代码安全工程师盯的是攻击面DBA 盯的是执行计划和索引架构师盯的是模块耦合。通用模式下 AI 什么都能说两句但每句都停在表面。agency-agents 这个开源项目做的事情很直接把 193 个专业角色覆盖 18 个部门以 Markdown 文件的形式塞进 Claude Code 的 agents 目录每个角色自带工作流程、交付标准和专业约束。装完之后你用一句自然语言就能切换身份让 Claude Code 按安全工程师或DBA的视角干活。这篇教程面向已经在用 Claude Code、但想让输出更专业分工的开发者。我会从安装命令讲到 settings.json 配置骨架再给出验证角色是否真正生效的可复制检查动作最后说明怎么通过 TaoToken 统一 Key 和 API 通道完成接入避免多工具多 Key 来回切换的麻烦。全程可跟做命令直接复制即可。2. 前置准备TaoToken 统一 Key 与 API 通道在装角色库之前先把模型调用通道理顺。Claude Code 默认走 Anthropic 官方接口如果你同时还在用 Cursor、Codex CLI 等工具每个工具配一套 Key 会很乱。TaoToken 的作用是提供一个统一的 API 入口你只需要维护一份 Key就能让 Claude Code 和其他工具共用同一条通道。官网地址https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基础地址不带 UTMhttps://taotoken.net/api你需要先拿到一个 API Key。登录后进入控制台在 API Keys 页面创建一个新 Key复制保存。这个 Key 后面会写进 Claude Code 的环境变量或 settings.json 里。注意Key 只显示一次创建后立刻复制到安全的地方。不要把它硬编码进提交到 Git 的配置文件里。拿到 Key 之后Claude Code 有两种接入方式一种是通过环境变量ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY指向 TaoToken 的 API 地址另一种是写进~/.claude/settings.json的env字段。后者更适合长期使用因为配置持久化不用每次开终端都 export。如果你还没创建 Key可以直接打开 API Keys 管理页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content3. 安装 agency-agents 角色库三条命令搞定角色库的安装本身不复杂核心就是把角色 Markdown 文件复制到 Claude Code 读取的 agents 目录。整个过程三条命令。3.1 克隆项目并进入目录git clone https://github.com/jnMetaCode/agency-agents-zh.git cd agency-agents-zh克隆位置任意放哪都行安装脚本会自动检测你机器上已安装的 AI 工具。3.2 执行安装脚本./scripts/install.sh如果你只用 Claude Code可以显式指定工具避免脚本去检测其他工具./scripts/install.sh --tool claude-code安装脚本会把角色文件复制到~/.claude/agents/目录。这个操作不影响你现有的任何 Claude Code 配置属于纯增量。哪天不想用了删掉这个目录就干净了没有残留。3.3 验证安装结果ls ~/.claude/agents/ | head -10看到类似engineering-security-engineer.md、marketing-xiaohongshu-operator.md这样的文件名说明安装成功。你可以数一下总数ls ~/.claude/agents/ | wc -l正常应该接近 193 个部分角色可能按部门分目录存放具体以项目实际结构为准。3.4 其他工具的格式转换如果你除了 Claude Code 还用 Cursor 或 OpenClaw这些工具需要先做一步格式转换因为它们的规则文件格式不同./scripts/convert.sh --tool cursor # 转成 .mdc 格式 ./scripts/install.sh --tool cursor # 再安装支持的工具一共 14 种包括 Claude Code、Cursor、GitHub Copilot、OpenClaw、Kiro、Trae、Gemini CLI、Aider、Windsurf、Qwen Code、Codex CLI、DeerFlow、OpenCode、Antigravity。你按需选择即可。4. settings.json 配置骨架把 TaoToken 通道和角色库串起来角色文件装好了但如果 Claude Code 还在走默认的官方接口你可能会遇到额度或网络层面的限制。这一步把 TaoToken 的 API 通道写进settings.json让角色库和统一 Key 一起生效。4.1 settings.json 的完整骨架打开或创建~/.claude/settings.json写入以下结构{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 }, permissions: { allow: [ Read, Write, Bash(git:*), Bash(ls:*) ] }, agents: { directory: ~/.claude/agents } }逐字段说明env.ANTHROPIC_BASE_URL指向 TaoToken 的 API 基础地址注意这里不加任何 UTM 参数保持干净。env.ANTHROPIC_API_KEY填你在控制台创建的 Key。permissions.allow是 Claude Code 的工具权限白名单按你实际需要增减不要无脑全开。agents.directory告诉 Claude Code 去哪里读角色文件默认就是~/.claude/agents显式写出来更清晰。4.2 环境变量方式的等价写法如果你不想改 settings.json也可以在 shell 配置文件里 exportexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥两种方式选一种即可不要同时配否则容易出现优先级混乱。settings.json 的方式更推荐因为它跟着 Claude Code 走换终端也不丢。4.3 角色激活的两种路径配置完成后角色激活有两种方式。第一种是自然语言直接说用安全工程师审查 src/api/auth.py 切换到DBA模式帮我优化这个慢查询 用小红书运营专家帮我写一篇种草笔记不需要记住精确的角色文件名你说安全专家搞安全的安全工程师Claude Code 都能匹配到对应角色。第二种是在项目的CLAUDE.md里预设映射适合高频固定场景当我说安全审查时按安全工程师角色工作 当我说优化查询时按DBA角色工作 代码审查时默认使用高级开发者角色这样连用 XX 角色都不用说直接说安全审查就触发。5. 验证角色是否真正生效可复制的检查动作装完不等于生效。下面给几个可复制的验证动作逐条确认角色库和 API 通道都在工作。5.1 检查 API 通道是否通先用一个最小请求确认 TaoToken 通道可达。如果你装了 curl可以这样测curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复OK两个字}] }返回里带content字段且文本正常说明 Key 和通道没问题。如果返回 401检查 Key 是否复制完整返回 404检查 base URL 是否写成了带路径的完整地址。5.2 检查角色文件是否被读取在 Claude Code 里直接问它列出你当前可用的 agents 角色按部门分组如果角色库生效它会列出 engineering、marketing、testing 等部门下的角色。如果它说我没有角色列表说明agents.directory没配对或者文件没复制到位。5.3 对比验证同一问题通用模式 vs 角色模式最直接的验证是拿同一个问题问两次。先不指定角色帮我看看这段认证代码有没有安全问题记下它的回答。然后指定角色再问一次用安全工程师审查 src/api/auth.py角色模式下输出应该变成结构化的威胁分析比如按 STRIDE 模型逐项列出身份伪造、信息泄露、权限提升并给出修复优先级。如果两次回答没区别说明角色没被激活回去检查第 4 步的配置。5.4 检查 settings.json 是否被正确解析cat ~/.claude/settings.json | python3 -m json.tool如果 JSON 格式有误这条命令会报错。常见错误是多了尾逗号或者 Key 里带了换行。修好之后再重启 Claude Code。6. 本篇常见错排查6.1 安装脚本报权限错误./scripts/install.sh提示 Permission denied先加执行权限chmod x ./scripts/install.sh chmod x ./scripts/convert.sh再重新执行。6.2 角色装了但 Claude Code 不认先确认目录存在且非空ls -la ~/.claude/agents/ | head如果目录是空的说明安装脚本没跑成功或者--tool参数写错了。重新跑一次./scripts/install.sh --tool claude-code观察输出里有没有 copied N files 之类的提示。6.3 API 返回 401 或 403九成是 Key 的问题。检查三点Key 是否复制完整有没有漏掉前缀、Key 是否已过期或被删除、settings.json 里的 Key 有没有被引号包住。如果 Key 里本身含特殊字符确保 JSON 转义正确。6.4 改了 settings.json 但没生效Claude Code 在启动时读取配置改完要重启。另外确认你改的是~/.claude/settings.json而不是项目目录下的某个同名文件两者优先级不同容易搞混。6.5 角色匹配不到你说用安全专家但角色库里叫安全工程师一般能模糊匹配。如果匹配不到直接用文件名里的关键词比如security engineer。实在不行先ls ~/.claude/agents/ | grep security看看实际有哪些角色。6.6 想只装部分角色193 个全装占空间也没必要。手动复制你需要的cp engineering/*.md ~/.claude/agents/ cp marketing/marketing-xiaohongshu-operator.md ~/.claude/agents/按部门或按单个文件都行。7. 下一步把角色库用成工作流角色装好只是起点。真正提效的用法是多角色串行第一轮用产品经理分析需求输出 PRD第二轮用架构师基于 PRD 设计技术方案第三轮用安全工程师审查方案风险第四轮用前端开发者开始实现。每个角色基于上一个角色的输出继续工作比一个通用 AI 从头做到尾质量高得多。如果你嫌手动切换麻烦可以搭配 agency-orchestrator 用 YAML 定义工作流自动编排。另外长期高频使用编码和 Agent 场景的话可以了解一下 Coding Plan把额度规划好避免用到一半断流https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content想先直观感受模型对话效果可以直接在模型对话页试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入文档在这里遇到配置细节可以对照查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content卸载角色库也很简单删目录即可rm -rf ~/.claude/agents/没有任何残留。装之前建议先备份一下现有的~/.claude/agents/如果有的话避免覆盖掉你自己写的角色文件。