1. 为什么 Command 和 SubAgent 值得单独配一遍Claude Code 用起来之后很多人会卡在同一个地方单次对话能跑通但一旦想把「错误排查」「接口重构」「安全审查」这类重复动作固化下来就发现每次都要重新手写一大段 prompt效率并没有比直接聊天高多少。Command 和 SubAgent 就是解决这个问题的两个机制——前者把可复用的 Markdown 模板变成/指令名一键触发后者把独立上下文、可并行、可指定模型的任务拆出去单独跑。这篇面向的是已经在用统一 Key / API 通道的开发者重点不是讲概念而是把settings.json、config.toml、Command 模板、SubAgent 模板这四样东西的骨架给出来再给一套验证「调用是否真的走了 TaoToken 通道」的具体动作。我试过把 Command 和 SubAgent 混着用踩过的坑主要集中在环境变量没生效、模型名写错、SubAgent 的 front matter 字段拼错这三类后面会逐个拆。适合谁看已经装好 Claude Code CLI、手里有一个统一 API Key、想让重复性任务变成/命令或者并行子代理的人。如果你还没配过 Key先看第 2 节的前置部分。2. TaoToken 前置Key、通道与两个配置文件TaoToken 在这里扮演的角色是统一的 API 通道你不需要为每个模型单独维护一套 Key 和 base_url而是把请求都指向同一个入口由它来路由到具体模型。对 Claude Code 来说这意味着settings.json里的env段和config.toml里的 provider 段都指向同一个地址即可。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个不加 UTM。Key 的申请和查看在控制台的 API Keys 页面模型对话的调试入口在模型对话页长期编码或 Agent 场景建议直接看 Coding Plan。前置动作只有三步拿到 Key、确认 base_url、把 Key 写进环境变量而不是硬编码进仓库。第三步最容易被忽略一旦 Key 进了 git后面所有配置都得重来。# 写入 shell 配置避免硬编码 echo export TAOTOKEN_API_KEYsk-你的key ~/.zshrc source ~/.zshrc # 验证变量存在 echo $TAOTOKEN_API_KEY | head -c 8输出前 8 位能对上就说明环境变量生效了。这一步做完再动 Claude Code 的配置文件否则后面报 401 你会分不清是 Key 错还是配置没读到。3. 可复制配置settings.json 与 config.toml 骨架Claude Code 的配置分两层~/.claude/settings.json管 CLI 行为和环境变量~/.claude/config.toml或项目级.claude/config.toml管 provider 和模型映射。下面这份骨架可以直接抄把sk-你的key换成真实值即可。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [Read, Write, Bash(git:*)], deny: [Bash(rm -rf:*)] } }ANTHROPIC_BASE_URL指向 TaoToken 的 API 入口ANTHROPIC_API_KEY用你的统一 KeyANTHROPIC_MODEL写你要默认走的模型名。注意模型名要和通道侧支持的名称一致写错会直接 404 而不是降级。# ~/.claude/config.toml [provider] name taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY [models] default claude-sonnet-4-20250514 fast claude-haiku-4-20250514 [agent] max_parallel 3api_key_env指向环境变量名而不是值本身这样 Key 不会出现在配置文件里。max_parallel控制 SubAgent 并行上限设太大反而会因为上下文切换拖慢整体。注意settings.json和config.toml同时存在时环境变量以settings.json的env段为准provider 段以config.toml为准。两边都写 Key 容易互相覆盖建议只在一处写。4. Command 模板从错误排查到功能重构Command 放在.claude/commands/目录下文件名就是指令名error-fix.md对应/error-fix。模板用 Markdown 写参数用$开头。下面是一个带参数的错误排查模板。!-- .claude/commands/error-fix.md -- 我的程序出现了 $ERROR_MESSAGE 错误信息。 我需要 1. 为 $TARGET_FILE 的 $FIX_FEATURE_LIST 功能编写测试示例 2. 将测试保存到 $DIR 目录并运行 3. 基于测试结果定位并修复错误代码 请先输出你解析到的参数再开始任务。Think a lot.调用时这样传参claude /error-fix - $ERROR_MESSAGE: TypeError: Cannot read property id of undefined - $TARGET_FILE: src/user.ts - $FIX_FEATURE_LIST: 用户查询 - $DIR: ./test最后那句「请先输出你解析到的参数」是验证动作如果 Claude 回显的参数和你输入的一致说明模板解析没问题如果回显为空或错位多半是$变量名和调用时的键名对不上。功能重构模板结构类似但更强调「当前情况 / 期望情况 / 工作流示例 / 要求 / 提示」五段式!-- .claude/commands/refactor.md -- 要重构的功能$FEATURE_NAME ## 当前情况 按步骤叙述现有实现。 ## 期望的情况 按步骤叙述目标实现。 ## 工作流示例 给一个工作示例不需要具体结果只要大概流程。 ## 要求 $RULES ## 提示 需要更新的文件$FILES 需要更新的测试$TESTS写测试流程时关注外部行为而不是内部细节否则重构一动内部结构测试就全红反而失去意义。5. SubAgent 模板独立上下文与并行执行SubAgent 放在~/.claude/agents/目录下同样是 Markdown但多了 front matter。front matter 里的name是 CLI 显示名description帮主代理判断何时调用tools限定它能用的内置工具model写inherit就继承父代理模型color只是显示颜色。--- name: security-auditor description: 安全专家用于检查内容中存在的账户信息、脚本等敏感数据 tools: Read model: inherit color: blue --- 你是一名安全专家。调用时 1. 识别载体内容中的账户信息和敏感个人数据 2. 识别载体中的密钥、身份认证内容 3. 识别并整理审查清单 根据严重程度报告发现 - 高敏感需要立刻移除 - 中度敏感存在泄漏但考虑移除 - 低敏感可能存在泄漏但通常无需移除调用可以主动声明也可以让主代理自行推断 请使用 SubAgent 分析并审查 vitest.config.ts 的代码安全性问题 请并行使用 code-analyzer security-auditor 分析并审查 vitest.config.ts 的代码安全性和代码规范问题第二条会同时拉起两个 SubAgent各自独立上下文、独立模型跑完把结果汇总回主代理。SubAgent 和 Command 的核心区别在于SubAgent 是独立工作区有自己的上下文和模型支持并行适合复杂任务Command 只是可复用模板和主代理共享模型与上下文适合一次性或快速完成的简单任务。6. 验证请求是否走通 TaoToken 通道配置写完不代表生效得用具体动作验证。最直接的方式是开一个最小请求看返回里有没有通道特征。curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 32, messages: [{role: user, content: reply with ok}] } | head -c 300返回里能看到content字段和ok就说明 Key 和 base_url 都对。如果返回 401检查 Key 是否带上了sk-前缀返回 404检查模型名返回 403检查 Key 是否有该模型的权限。CLI 侧再验一次claude --print 用一句话说明当前使用的模型如果输出里提到的模型和你settings.json里配的一致说明 CLI 确实走了你指定的通道。SubAgent 的验证更简单跑一个并行任务看 CLI 是否同时显示多个执行中的任务窗口是则 SubAgent 机制生效。7. 本篇常见错排查报 401 Unauthorized九成是环境变量没被读到。settings.json的env段优先级高于 shell 环境变量如果两边都写了但值不同以settings.json为准。先echo $TAOTOKEN_API_KEY确认 shell 里有值再检查settings.json里有没有写错。报 404 model not found模型名拼写问题。claude-sonnet-4-20250514这种带日期后缀的写法容易多一个或少一个字符建议从模型对话页复制准确名称。Command 参数不生效$变量名和调用时的键名必须完全一致大小写敏感。$ERROR_MESSAGE和$error_message是两个不同的变量。另外模板文件必须放在.claude/commands/下放错目录不会报错但也不会被识别。SubAgent 不触发front matter 的---必须是文件第一行前面不能有空行。description字段要写清楚用途主代理靠它判断何时调用。tools写Read就只能读写Read, Write才能写逗号后要有空格。并行任务卡住max_parallel设太大时多个 SubAgent 抢上下文反而变慢。从 2 到 3 开始试观察 CLI 的任务窗口数量是否和预期一致。8. 把配置沉淀成团队资产Command 和 SubAgent 配好之后建议把.claude/commands/和~/.claude/agents/纳入版本管理但 Key 绝对不能进仓库。团队里每个人用自己的 Key模板共享这样新人拉下来改一行环境变量就能跑。长期编码或 Agent 场景Coding Plan 比按次调用更划算模型对话页适合临时验证某个模型是否可用API Keys 页面管 Key 的轮换和权限。接入文档里有完整的参数说明遇到本文没覆盖的报错先去那里对一遍字段名。最后留一个实用习惯每次改完settings.json或config.toml先跑一次第 6 节的 curl 验证再开 CLI。这样能把「配置问题」和「模型问题」分开排查时间至少省一半。
Claude Code 使用笔记（二）- Command 和 SubAgent 的 TaoToken 配置实践
1. 为什么 Command 和 SubAgent 值得单独配一遍Claude Code 用起来之后很多人会卡在同一个地方单次对话能跑通但一旦想把「错误排查」「接口重构」「安全审查」这类重复动作固化下来就发现每次都要重新手写一大段 prompt效率并没有比直接聊天高多少。Command 和 SubAgent 就是解决这个问题的两个机制——前者把可复用的 Markdown 模板变成/指令名一键触发后者把独立上下文、可并行、可指定模型的任务拆出去单独跑。这篇面向的是已经在用统一 Key / API 通道的开发者重点不是讲概念而是把settings.json、config.toml、Command 模板、SubAgent 模板这四样东西的骨架给出来再给一套验证「调用是否真的走了 TaoToken 通道」的具体动作。我试过把 Command 和 SubAgent 混着用踩过的坑主要集中在环境变量没生效、模型名写错、SubAgent 的 front matter 字段拼错这三类后面会逐个拆。适合谁看已经装好 Claude Code CLI、手里有一个统一 API Key、想让重复性任务变成/命令或者并行子代理的人。如果你还没配过 Key先看第 2 节的前置部分。2. TaoToken 前置Key、通道与两个配置文件TaoToken 在这里扮演的角色是统一的 API 通道你不需要为每个模型单独维护一套 Key 和 base_url而是把请求都指向同一个入口由它来路由到具体模型。对 Claude Code 来说这意味着settings.json里的env段和config.toml里的 provider 段都指向同一个地址即可。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个不加 UTM。Key 的申请和查看在控制台的 API Keys 页面模型对话的调试入口在模型对话页长期编码或 Agent 场景建议直接看 Coding Plan。前置动作只有三步拿到 Key、确认 base_url、把 Key 写进环境变量而不是硬编码进仓库。第三步最容易被忽略一旦 Key 进了 git后面所有配置都得重来。# 写入 shell 配置避免硬编码 echo export TAOTOKEN_API_KEYsk-你的key ~/.zshrc source ~/.zshrc # 验证变量存在 echo $TAOTOKEN_API_KEY | head -c 8输出前 8 位能对上就说明环境变量生效了。这一步做完再动 Claude Code 的配置文件否则后面报 401 你会分不清是 Key 错还是配置没读到。3. 可复制配置settings.json 与 config.toml 骨架Claude Code 的配置分两层~/.claude/settings.json管 CLI 行为和环境变量~/.claude/config.toml或项目级.claude/config.toml管 provider 和模型映射。下面这份骨架可以直接抄把sk-你的key换成真实值即可。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [Read, Write, Bash(git:*)], deny: [Bash(rm -rf:*)] } }ANTHROPIC_BASE_URL指向 TaoToken 的 API 入口ANTHROPIC_API_KEY用你的统一 KeyANTHROPIC_MODEL写你要默认走的模型名。注意模型名要和通道侧支持的名称一致写错会直接 404 而不是降级。# ~/.claude/config.toml [provider] name taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY [models] default claude-sonnet-4-20250514 fast claude-haiku-4-20250514 [agent] max_parallel 3api_key_env指向环境变量名而不是值本身这样 Key 不会出现在配置文件里。max_parallel控制 SubAgent 并行上限设太大反而会因为上下文切换拖慢整体。注意settings.json和config.toml同时存在时环境变量以settings.json的env段为准provider 段以config.toml为准。两边都写 Key 容易互相覆盖建议只在一处写。4. Command 模板从错误排查到功能重构Command 放在.claude/commands/目录下文件名就是指令名error-fix.md对应/error-fix。模板用 Markdown 写参数用$开头。下面是一个带参数的错误排查模板。!-- .claude/commands/error-fix.md -- 我的程序出现了 $ERROR_MESSAGE 错误信息。 我需要 1. 为 $TARGET_FILE 的 $FIX_FEATURE_LIST 功能编写测试示例 2. 将测试保存到 $DIR 目录并运行 3. 基于测试结果定位并修复错误代码 请先输出你解析到的参数再开始任务。Think a lot.调用时这样传参claude /error-fix - $ERROR_MESSAGE: TypeError: Cannot read property id of undefined - $TARGET_FILE: src/user.ts - $FIX_FEATURE_LIST: 用户查询 - $DIR: ./test最后那句「请先输出你解析到的参数」是验证动作如果 Claude 回显的参数和你输入的一致说明模板解析没问题如果回显为空或错位多半是$变量名和调用时的键名对不上。功能重构模板结构类似但更强调「当前情况 / 期望情况 / 工作流示例 / 要求 / 提示」五段式!-- .claude/commands/refactor.md -- 要重构的功能$FEATURE_NAME ## 当前情况 按步骤叙述现有实现。 ## 期望的情况 按步骤叙述目标实现。 ## 工作流示例 给一个工作示例不需要具体结果只要大概流程。 ## 要求 $RULES ## 提示 需要更新的文件$FILES 需要更新的测试$TESTS写测试流程时关注外部行为而不是内部细节否则重构一动内部结构测试就全红反而失去意义。5. SubAgent 模板独立上下文与并行执行SubAgent 放在~/.claude/agents/目录下同样是 Markdown但多了 front matter。front matter 里的name是 CLI 显示名description帮主代理判断何时调用tools限定它能用的内置工具model写inherit就继承父代理模型color只是显示颜色。--- name: security-auditor description: 安全专家用于检查内容中存在的账户信息、脚本等敏感数据 tools: Read model: inherit color: blue --- 你是一名安全专家。调用时 1. 识别载体内容中的账户信息和敏感个人数据 2. 识别载体中的密钥、身份认证内容 3. 识别并整理审查清单 根据严重程度报告发现 - 高敏感需要立刻移除 - 中度敏感存在泄漏但考虑移除 - 低敏感可能存在泄漏但通常无需移除调用可以主动声明也可以让主代理自行推断 请使用 SubAgent 分析并审查 vitest.config.ts 的代码安全性问题 请并行使用 code-analyzer security-auditor 分析并审查 vitest.config.ts 的代码安全性和代码规范问题第二条会同时拉起两个 SubAgent各自独立上下文、独立模型跑完把结果汇总回主代理。SubAgent 和 Command 的核心区别在于SubAgent 是独立工作区有自己的上下文和模型支持并行适合复杂任务Command 只是可复用模板和主代理共享模型与上下文适合一次性或快速完成的简单任务。6. 验证请求是否走通 TaoToken 通道配置写完不代表生效得用具体动作验证。最直接的方式是开一个最小请求看返回里有没有通道特征。curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 32, messages: [{role: user, content: reply with ok}] } | head -c 300返回里能看到content字段和ok就说明 Key 和 base_url 都对。如果返回 401检查 Key 是否带上了sk-前缀返回 404检查模型名返回 403检查 Key 是否有该模型的权限。CLI 侧再验一次claude --print 用一句话说明当前使用的模型如果输出里提到的模型和你settings.json里配的一致说明 CLI 确实走了你指定的通道。SubAgent 的验证更简单跑一个并行任务看 CLI 是否同时显示多个执行中的任务窗口是则 SubAgent 机制生效。7. 本篇常见错排查报 401 Unauthorized九成是环境变量没被读到。settings.json的env段优先级高于 shell 环境变量如果两边都写了但值不同以settings.json为准。先echo $TAOTOKEN_API_KEY确认 shell 里有值再检查settings.json里有没有写错。报 404 model not found模型名拼写问题。claude-sonnet-4-20250514这种带日期后缀的写法容易多一个或少一个字符建议从模型对话页复制准确名称。Command 参数不生效$变量名和调用时的键名必须完全一致大小写敏感。$ERROR_MESSAGE和$error_message是两个不同的变量。另外模板文件必须放在.claude/commands/下放错目录不会报错但也不会被识别。SubAgent 不触发front matter 的---必须是文件第一行前面不能有空行。description字段要写清楚用途主代理靠它判断何时调用。tools写Read就只能读写Read, Write才能写逗号后要有空格。并行任务卡住max_parallel设太大时多个 SubAgent 抢上下文反而变慢。从 2 到 3 开始试观察 CLI 的任务窗口数量是否和预期一致。8. 把配置沉淀成团队资产Command 和 SubAgent 配好之后建议把.claude/commands/和~/.claude/agents/纳入版本管理但 Key 绝对不能进仓库。团队里每个人用自己的 Key模板共享这样新人拉下来改一行环境变量就能跑。长期编码或 Agent 场景Coding Plan 比按次调用更划算模型对话页适合临时验证某个模型是否可用API Keys 页面管 Key 的轮换和权限。接入文档里有完整的参数说明遇到本文没覆盖的报错先去那里对一遍字段名。最后留一个实用习惯每次改完settings.json或config.toml先跑一次第 6 节的 curl 验证再开 CLI。这样能把「配置问题」和「模型问题」分开排查时间至少省一半。
