1. 為什么你的 Claude Code 越用越亂Subagents 到底解決什么問題如果你最近在用 Claude Code 寫項(xiàng)目大概率遇到過這種場(chǎng)景主對(duì)話里剛聊完數(shù)據(jù)庫遷移轉(zhuǎn)頭讓它改個(gè)前端樣式它卻開始給你講 SQL 索引優(yōu)化或者你讓它跑個(gè)測(cè)試它順手把整個(gè)src目錄讀了一遍上下文瞬間被塞滿后面再問什么都開始失憶。這不是模型變笨了而是單線程上下文被污染了。Claude Code Subagents子代理就是為這個(gè)痛點(diǎn)設(shè)計(jì)的。簡(jiǎn)單說它允許你預(yù)先定義若干個(gè)專職助手每個(gè)助手有自己的系統(tǒng)提示、自己的工具權(quán)限、自己的獨(dú)立上下文。當(dāng)你的請(qǐng)求匹配到某個(gè)子代理的職責(zé)描述時(shí)主線程會(huì)把任務(wù)委派出去子代理在自己的上下文里干完活只把結(jié)果回傳。主對(duì)話線程始終保持干凈。它適合誰三類人最該用一是項(xiàng)目里同時(shí)有前端、后端、數(shù)據(jù)腳本的全棧開發(fā)者任務(wù)切換頻繁二是團(tuán)隊(duì)協(xié)作中希望把代碼審查規(guī)范測(cè)試流程固化成配置的技術(shù)負(fù)責(zé)人三是像我這樣經(jīng)常讓 AI 幫忙排查線上報(bào)錯(cuò)的運(yùn)維/后端同學(xué)需要隔離只讀診斷和可寫修復(fù)兩種權(quán)限。我試過在一個(gè)中型 Node 項(xiàng)目里不配子代理直接用結(jié)果一次會(huì)話里 Claude 反復(fù)重讀package.json和tsconfig.jsontoken 消耗肉眼可見地漲。配了code-reviewer和debugger兩個(gè)子代理之后主線程只負(fù)責(zé)調(diào)度具體審查和排錯(cuò)各自在隔離上下文里完成整個(gè)流程清爽很多。這一篇我會(huì)把 Subagents 的原理、配置文件寫法、觸發(fā)方式、報(bào)錯(cuò)排查全部拆開講并且用 TaoToken 統(tǒng)一 API 通道來演示調(diào)用驗(yàn)證——因?yàn)楹芏嗳嗽谂渲米哟頃r(shí)卡住根本不是 YAML 寫錯(cuò)而是底層的 Key 和 Base URL 沒打通。先把通道理順再談子代理順序不能反。2. TaoToken 前置先把 Key 和 API 通道理順再談 Subagents在動(dòng) Subagents 配置之前必須先確認(rèn) Claude Code 能正常發(fā)請(qǐng)求。Subagents 本質(zhì)上是同一套模型調(diào)用換了個(gè)系統(tǒng)提示和上下文如果主通道都不通子代理只會(huì)報(bào)更隱蔽的錯(cuò)。所以這一步是地基。TaoToken 在這里扮演的角色是統(tǒng)一的 API 通道你不需要為每個(gè)模型、每個(gè)工具單獨(dú)維護(hù)一套 Key而是用同一個(gè) Key 走同一個(gè) Base URLClaude Code 主線程和它派生的所有子代理都復(fù)用這條通道。這對(duì) Subagents 特別重要——因?yàn)樽哟砜赡苤付ú煌膍odel比如審查用 sonnet、數(shù)據(jù)分析用 opus如果每個(gè)模型都要單獨(dú)配 Key配置會(huì)爆炸。具體操作路徑是這樣的先到官網(wǎng) https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注冊(cè)并登錄然后在控制臺(tái)里創(chuàng)建 API Key?？刂婆_(tái)地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 管理頁在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。創(chuàng)建完記得復(fù)制Key 只顯示一次。拿到 Key 之后Claude Code 側(cè)需要設(shè)置兩個(gè)環(huán)境變量ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。Base URL 用https://taotoken.net/api注意這個(gè)地址不加 UTM 參數(shù)是純 API 端點(diǎn)。這里有個(gè)坑我踩過很多人把官網(wǎng)地址填進(jìn) Base URL結(jié)果請(qǐng)求打到網(wǎng)頁上返回 HTML報(bào)錯(cuò)信息還特別含糊。記住 API 端點(diǎn)和官網(wǎng)是兩回事。注意環(huán)境變量名在不同版本里可能有差異Claude Code 走 Anthropic 協(xié)議時(shí)用ANTHROPIC_*前綴如果你用的是兼容 OpenAI 協(xié)議的工具則用OPENAI_*前綴。本文以 Claude Code 原生協(xié)議為準(zhǔn)。配置完成后建議先用一次最簡(jiǎn)單的對(duì)話驗(yàn)證通道再進(jìn)入子代理環(huán)節(jié)。驗(yàn)證方式我放在第 4 節(jié)這里先記住原則通道不通子代理必掛通道通了子代理的問題才好定位。如果你還打算長(zhǎng)期跑編碼 Agent 任務(wù)可以順帶了解下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它更適合高頻、長(zhǎng)會(huì)話的場(chǎng)景和 Subagents 的隔離機(jī)制配合起來體驗(yàn)更穩(wěn)。3. 可復(fù)制配置Subagents 文件結(jié)構(gòu)、YAML 字段與 settings 片段這一節(jié)是全文最核心的部分我會(huì)給出能直接復(fù)制粘貼的配置。Subagents 的配置分兩層一層是 Claude Code 自身的 settings決定走哪條 API 通道一層是每個(gè)子代理的 Markdown 文件決定它干什么、能用什么工具。先看 Claude Code 的 settings。它通常放在~/.claude/settings.json用戶級(jí)或項(xiàng)目根目錄的.claude/settings.json項(xiàng)目級(jí)。項(xiàng)目級(jí)優(yōu)先級(jí)更高。一個(gè)可用的片段長(zhǎng)這樣{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密鑰 }, model: sonnet, permissions: { allow: [Read, Grep, Glob], deny: [Bash(rm -rf:*)] } }這段 JSON 里env決定了所有請(qǐng)求包括子代理派生的請(qǐng)求走 TaoToken 通道m(xù)odel是主線程默認(rèn)模型permissions是全局工具白名單和黑名單。注意deny里我特意擋了危險(xiǎn)刪除命令這是給子代理兜底——即使某個(gè)子代理被授予了 Bash 權(quán)限也刪不掉關(guān)鍵目錄。接下來是子代理文件。存放位置有兩處項(xiàng)目級(jí).claude/agents/用戶級(jí)~/.claude/agents/。重名時(shí)項(xiàng)目級(jí)優(yōu)先。每個(gè)子代理是一個(gè).md文件頭部是 YAML frontmatter正文是系統(tǒng)提示。以代碼審查員為例文件路徑.claude/agents/code-reviewer.md--- name: code-reviewer description: 專家代碼審查。在編寫或修改代碼后立即使用審查質(zhì)量、安全性和可維護(hù)性。 tools: Read, Grep, Glob, Bash model: inherit --- 你是資深代碼審查員確保高標(biāo)準(zhǔn)的質(zhì)量與安全。 被調(diào)用時(shí) 1. 運(yùn)行 git diff 查看最近改動(dòng) 2. 只聚焦被修改的文件 3. 立即開始審查 審查清單 - 代碼是否簡(jiǎn)單可讀 - 命名是否清晰 - 是否有重復(fù)代碼 - 錯(cuò)誤處理是否到位 - 是否泄露 API Key - 輸入校驗(yàn)是否實(shí)現(xiàn) - 測(cè)試覆蓋是否足夠 按優(yōu)先級(jí)反饋關(guān)鍵問題必須修、警告建議修、建議可改進(jìn)。 每條都給出具體修復(fù)示例。字段說明我用表格對(duì)照方便你查字段是否必需說明name是唯一標(biāo)識(shí)小寫加連字符調(diào)用時(shí)用它description是用途和觸發(fā)場(chǎng)景Claude 靠它判斷何時(shí)委派tools否授權(quán)工具清單逗號(hào)分隔省略則繼承主線程全部工具model否sonnet / opus / haiku或 inherit 繼承主線程這里有個(gè)關(guān)鍵設(shè)計(jì)點(diǎn)tools是權(quán)限邊界。審查員只需要讀和查所以給Read, Grep, Glob, BashBash 用于跑 git diff而調(diào)試器需要改代碼才給Edit。權(quán)限最小化不只是安全也能減少子代理亂動(dòng)手導(dǎo)致的意外修改。再給一個(gè)調(diào)試器的配置路徑.claude/agents/debugger.md--- name: debugger description: 錯(cuò)誤、測(cè)試失敗和意外行為的調(diào)試專家。遇到任何問題時(shí)主動(dòng)使用。 tools: Read, Edit, Bash, Grep, Glob model: inherit --- 你是專注根因分析的調(diào)試專家。 被調(diào)用時(shí) 1. 捕獲錯(cuò)誤信息和堆棧 2. 確定復(fù)現(xiàn)步驟 3. 定位失敗位置 4. 實(shí)施最小修復(fù) 5. 驗(yàn)證修復(fù)有效 對(duì)每個(gè)問題給出根因解釋、支撐診斷的證據(jù)、具體代碼修復(fù)、測(cè)試方案、預(yù)防建議。 聚焦修復(fù)底層問題而不是掩蓋癥狀。如果你用的是 Cline 或帶 MCP 的客戶端配置思路一致但要注意 MCP 工具名要寫全比如mcp__filesystem__read。CC Switch 這類切換工具則要確保切換后 Base URL 和 Key 同步更新否則子代理會(huì)拿著舊 Key 報(bào) 401。Codex 用戶如果走auth.json記得把OPENAI_BASE_URL指向https://taotoken.net/apiKey 填 TaoToken 的 KeyModel ID 填你實(shí)際要用的模型名——這三件套Base URL Key Model ID缺一不可。4. 驗(yàn)證請(qǐng)求從主線程到子代理的成功結(jié)果長(zhǎng)什么樣配置寫完不代表能用必須驗(yàn)證。驗(yàn)證分兩步先驗(yàn)主通道再驗(yàn)子代理委派。第一步主通道驗(yàn)證。在項(xiàng)目目錄下啟動(dòng) Claude Code直接問一句你好確認(rèn)一下連接。如果通道正常你會(huì)看到正?；貜?fù)如果報(bào)錯(cuò)先別急著查子代理問題在 settings 或環(huán)境變量。這一步能過說明 TaoToken 的 Base URL 和 Key 是對(duì)的。第二步子代理委派驗(yàn)證。這里有兩種觸發(fā)方式。自動(dòng)委派Claude 根據(jù)你的請(qǐng)求內(nèi)容和子代理的description自動(dòng)判斷。比如你改完一段代碼后說幫我看看剛才的改動(dòng)有沒有問題它應(yīng)該自動(dòng)調(diào)用code-reviewer。顯式調(diào)用直接點(diǎn)名比如輸入使用 code-reviewer 子代理檢查我最近的更改或者讓 debugger 子代理看看這個(gè)測(cè)試為什么失敗。成功的結(jié)果有幾個(gè)特征。一是你會(huì)看到 Claude 明確說我將使用 code-reviewer 子代理之類的調(diào)度語句二是審查結(jié)果會(huì)按你系統(tǒng)提示里定義的格式返回比如分關(guān)鍵問題/警告/建議三檔三是主線程上下文沒有被審查過程的中間步驟污染——它只拿到最終結(jié)論。我實(shí)測(cè)下來一個(gè)正常的 code-reviewer 輸出大概是這樣它先跑git diff然后針對(duì)改動(dòng)文件逐條列問題每條帶修復(fù)示例。如果它開始泛泛而談、不跑 git diff、或者把整個(gè)倉(cāng)庫都讀一遍說明description寫得不夠聚焦或者tools給多了導(dǎo)致它自由發(fā)揮。驗(yàn)證模型本身是否可用可以走模型對(duì)話頁面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 單獨(dú)測(cè)一下確認(rèn)你要用的 sonnet/opus 在通道里是通的。這一步能排除模型不可用和配置寫錯(cuò)兩類問題省得在子代理層面瞎猜。提示驗(yàn)證階段建議把model先設(shè)成inherit讓子代理跟隨主線程模型。等流程跑通后再按需給特定子代理指定 opus 或 haiku 做性能/成本優(yōu)化。5. 本篇常見錯(cuò)排查401、local proxy failed、reading choices、OAuth子代理配置最容易在幾個(gè)固定地方翻車我把真實(shí)報(bào)錯(cuò)和對(duì)應(yīng)解法列出來你對(duì)著查。報(bào)錯(cuò)一401 Unauthorized。這是最高頻的。原因通常是 Key 沒生效或?qū)戝e(cuò)。檢查三處ANTHROPIC_API_KEY是否填了完整 Key有沒有多余空格、Key 是否已在 TaoToken 控制臺(tái)啟用、環(huán)境變量是否被 shell 緩存了舊值。改完環(huán)境變量記得重開終端或者source一下配置文件。如果主線程能通但子代理報(bào) 401檢查子代理文件里有沒有誤寫model指向一個(gè)需要額外授權(quán)的模型。報(bào)錯(cuò)二local proxy failed / connection refused。這個(gè)多半是 Base URL 寫錯(cuò)。常見錯(cuò)誤是把官網(wǎng)地址https://taotoken.net當(dāng)成 API 端點(diǎn)填進(jìn)去正確應(yīng)該是https://taotoken.net/api。另一個(gè)可能是本地網(wǎng)絡(luò)策略攔截確認(rèn)你的終端能正常訪問該域名即可不要引入任何網(wǎng)絡(luò)代理類工具那既不合規(guī)也會(huì)讓問題更復(fù)雜。報(bào)錯(cuò)三reading choices of undefined。這個(gè)報(bào)錯(cuò)說明返回體結(jié)構(gòu)和你客戶端預(yù)期的不一致通常發(fā)生在協(xié)議不匹配時(shí)——比如客戶端按 OpenAI 格式解析但請(qǐng)求實(shí)際走了 Anthropic 格式或者反過來。檢查你的客戶端協(xié)議設(shè)置Claude Code 原生走 Anthropic 協(xié)議用ANTHROPIC_*變量如果混用了OPENAI_*變量就會(huì)解析失敗。統(tǒng)一協(xié)議即可。報(bào)錯(cuò)四OAuth 相關(guān)報(bào)錯(cuò)。如果你之前用官方賬號(hào)登錄過本地可能殘留 OAuth 憑證和 API Key 模式?jīng)_突。解決方式是清理舊的登錄態(tài)明確用 API Key 模式。Claude Code 里可以檢查是否有殘留的憑證文件刪掉后重新用環(huán)境變量方式啟動(dòng)。報(bào)錯(cuò)五子代理不觸發(fā)。配置沒錯(cuò)但 Claude 就是不調(diào)用子代理八成是description寫得太模糊。description要寫清楚什么時(shí)候用比如在編寫或修改代碼后立即使用就比代碼審查工具更容易被匹配。另外確認(rèn)文件放在.claude/agents/下且擴(kuò)展名是.mdYAML frontmatter 的---不能少。排查順序建議固定成先驗(yàn)主通道 → 再驗(yàn)子代理文件是否被識(shí)別輸入/agents看列表→ 再看description和tools→ 最后看模型是否可用。按這個(gè)順序90% 的問題能在前三步定位。6. 把 Subagents 用成團(tuán)隊(duì)資產(chǎn)從單點(diǎn)配置到可復(fù)用工作流配置跑通之后真正拉開差距的是怎么把它用成可復(fù)用的團(tuán)隊(duì)資產(chǎn)而不是每次開新項(xiàng)目都重配一遍。第一件事是把項(xiàng)目級(jí)子代理納入版本控制。.claude/agents/目錄跟著倉(cāng)庫走團(tuán)隊(duì)成員拉下來就有一致的審查規(guī)范、測(cè)試流程、調(diào)試約定。這比在群里發(fā)記得讓 AI 檢查命名有用得多。用戶級(jí)~/.claude/agents/放你個(gè)人的通用偏好項(xiàng)目級(jí)放團(tuán)隊(duì)共識(shí)兩層配合。第二件事是堅(jiān)持單一職責(zé)。一個(gè)子代理只干一件事description才精準(zhǔn)觸發(fā)才可靠。別搞一個(gè)全能助手子代理那等于沒隔離。審查、調(diào)試、數(shù)據(jù)分析、文檔生成各配各的。第三件事是權(quán)限最小化。審查員只讀調(diào)試器可改但限定范圍數(shù)據(jù)分析只碰查詢工具。這樣即使某個(gè)子代理判斷失誤破壞面也可控。配合 settings 里的deny黑名單雙保險(xiǎn)。進(jìn)階玩法是鏈?zhǔn)秸{(diào)用先讓code-analyzer找性能問題再讓optimizer修。兩個(gè)子代理各自獨(dú)立上下文主線程只做編排。這種模式在復(fù)雜重構(gòu)里特別省心因?yàn)槊恳徊降闹虚g噪音都被隔離在子代理內(nèi)部了。最后回到通道層無論你配多少子代理、指定多少種模型只要它們都走 TaoToken 這一條統(tǒng)一通道Key 和 Base URL 就只需要維護(hù)一份。子代理越多統(tǒng)一通道的價(jià)值越明顯。需要長(zhǎng)期跑編碼 Agent 的話Coding Plan 配合這套隔離機(jī)制能把長(zhǎng)會(huì)話的穩(wěn)定性再提一檔。配置這件事一次理順后面都是復(fù)利。