1. 先把三个容易混淆的东西拆开看Claude Code 用久了会发现claude agents、/agents、/tasks这三个词长得像亲戚但管的事情完全不一样。我一开始也把它们当成同一套东西结果在排查后台任务时绕了不少弯路。这篇笔记就按我实际踩坑的顺序把多 Agent 协作、后台通知、优雅退出这条链路讲清楚并且用 TaoToken 统一 Key 把多 Agent 的配置骨架搭起来让你在本地能直接复现一套可观测的工作流。先说结论式的区分方便你建立心智模型claude agents是 CLI 命令管的是 background session也就是后台独立运行的完整 Claude Code 会话。它跨项目是一个全局的后台会话管理器。/agents是交互会话里的 slash command管的是 subagent也就是当前会话派出去的专用助手比如 code-reviewer、Explore 这类有独立上下文窗口的角色。/tasks也是 slash command管的是当前会话内部的任务列表类似一个 todo 面板看的是工作项而不是执行者。一句话记忆claude agents看后台会话/agents看或管理 subagents/tasks看当前会话任务项。这三者关注的对象不同混用会导致你在错误的地方找信息。比如你想看后台跑完没有去/tasks是找不到的你想看当前会话拆了几步去claude agents也是看不到的。理解了这个分层后面配置 TaoToken 统一 Key、挂 hooks 通知、做优雅退出才有清晰的落点。因为多 Agent 协作的本质就是让不同的执行单元后台会话、subagent、任务项各自跑在正确的轨道上而你需要一个统一的入口去观测它们。2. 用 TaoToken 统一 Key 打通多 Agent 配置多 Agent 场景下最烦的事情之一是 Key 管理。后台会话、subagent、不同项目目录如果每个地方都塞一份不同的 Key改起来就是灾难。我的做法是用 TaoToken 作为统一的 API 通道所有 Claude Code 会话都指向同一个入口这样无论开多少个后台 agent鉴权和计费口径都是一致的。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数。你需要先在控制台创建 API Key控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到字段不确定的时候对着文档核对最稳。这里要强调一点TaoToken 是合规的 API 通道服务不是所谓的中转也不涉及任何网络访问工具。你只是把 Claude Code 的模型请求指向一个统一的 API 入口方便多 Agent 共享同一套鉴权配置。这一点在团队协作里尤其重要因为 Key 集中管理后轮换和审计都简单很多。配置的核心落在~/.claude/settings.json。这个文件同时承载了模型通道配置和 hooks 配置所以后面讲通知的时候还会回到它。建议你先备份一份原始文件再动手改cp ~/.claude/settings.json ~/.claude/settings.json.bak如果你还没有这个文件直接新建即可。下面给出一个可复制的配置骨架把 TaoToken 的 API 通道和基础环境变量放进去。注意ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址ANTHROPIC_AUTH_TOKEN填你在控制台创建的 Key{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥 }, preferredNotifChannel: auto }这个骨架的好处是所有从这个环境启动的 Claude Code 会话包括claude --bg创建的后台会话都会自动继承这套通道配置。你不需要在每个项目里重复写 Key也不用担心某个后台 agent 用了旧的鉴权信息。如果你有多个项目需要隔离计费或权限可以在项目级配置里覆盖但大多数个人开发场景下全局统一一套就够了。改完之后用下面的命令确认 JSON 没写坏jq . ~/.claude/settings.json /dev/null echo settings.json OK输出settings.json OK就说明格式没问题。这一步看着简单但后面 hooks 配置一旦写错整份文件可能被忽略所以每次改完都验一下是值得养成的习惯。3. 可复制的多 Agent 与 hooks 通知配置现在把多 Agent 协作真正需要的东西补全。后台会话跑长任务时你最怕的是它跑完了你不知道或者它卡在权限确认上等你半天。Claude Code 的 hooks 机制就是解决这个的在特定事件发生时触发本地命令比如弹一个系统通知。下面这份配置在上一节的基础上加入了后台 agent 完成、任务完成、需要权限、需要输入这几类事件的通知。macOS 用osascript触发系统通知Linux 可以换成notify-sendWindows 可以用 PowerShell 的 BurntToast 之类方案这里以 macOS 为例{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥 }, preferredNotifChannel: auto, hooks: { SubagentStop: [ { matcher: , hooks: [ { type: command, command: osascript -e display notification \后台 agent 已完成\ with title \Claude Code\ } ] } ], TaskCompleted: [ { hooks: [ { type: command, command: osascript -e display notification \Claude 任务已完成\ with title \Claude Code\ } ] } ], Notification: [ { matcher: permission_prompt|idle_prompt, hooks: [ { type: command, command: osascript -e display notification \Claude 需要你的处理\ with title \Claude Code\ } ] } ], PermissionRequest: [ { matcher: Bash|Edit|Write|Read|MultiEdit|NotebookEdit|AskUserQuestion, hooks: [ { type: command, command: osascript -e display notification \Claude 正在等待权限确认\ with title \Claude Code\ } ] } ], Elicitation: [ { hooks: [ { type: command, command: osascript -e display notification \Claude 正在等待你的输入\ with title \Claude Code\ } ] } ] } }如果你原来已经有 hooks千万不要整段覆盖要把新的事件节点合并进去。JSON 里同一个 key 重复出现会以后者为准直接覆盖会丢掉你之前的配置。各事件的分工可以对照下面这张表理解事件触发场景是否关键SubagentStop子 agent 或后台 agent 结束后台任务提醒的核心TaskCompletedtask 被标记完成任务进度提醒Notification权限提示、空闲提示等内部通知需要你回来处理PermissionRequestClaude 准备请求工具权限避免卡在授权ElicitationClaude 需要用户输入或确认避免长时间空等Stop当前这一轮响应结束可选粒度较细如果只关心后台任务做完提醒重点配SubagentStop和TaskCompleted。如果还关心需要你回来处理把Notification、PermissionRequest、Elicitation一起加上。多 Agent 并行时这几个通知能显著降低你来回切窗口的频率。4. 验证请求与成功结果配置写完不代表生效得实际触发一次才算数。验证分三层JSON 格式、通知命令本身、hook 节点是否被识别。第一层确认 JSON 没坏jq . ~/.claude/settings.json /dev/null echo settings.json OK第二层确认系统通知命令能弹出来osascript -e display notification Claude Code 通知测试 with title Claude Code如果这条命令能弹通知说明系统通知本身没问题。弹不出来就去系统设置的通知里检查 Terminal、iTerm2、Warp 这些终端应用是否被允许通知。第三层确认 hook 节点确实写进去了jq -e .hooks.SubagentStop and .hooks.TaskCompleted and .hooks.Notification and .hooks.PermissionRequest ~/.claude/settings.json输出true就说明节点都在。这三层只能证明配置存在、命令能跑要验证 hook 真的被 Claude Code 触发还得制造真实事件。验证后台 agent 完成通知启动一个简单的后台会话claude --bg --name notify-test 简单总结当前目录下有哪些文件只输出摘要不修改文件然后用claude agents查看会话列表等它跑完后应该能看到系统通知弹出「后台 agent 已完成」。如果没弹先确认这个会话确实结束了再看claude logs id有没有正常输出。验证权限提醒可以让 Claude 执行一个需要确认的命令比如让它运行pwd。如果当前权限模式会弹确认那么应该同时看到系统通知。如果没触发可能是这个命令已经被 allow 了换一个尚未授权的工具再试。验证模型通道是否走通可以直接用模型对话页面发一条测试消息地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 确认返回正常就说明 Key 和通道没问题。这一步和 Claude Code 的配置是同一套鉴权能帮你快速定位是 Key 问题还是本地配置问题。如果配置改了但没生效可以在 Claude Code 里打开/hooks让它重新加载或者直接重启。还要检查一下 hooks 有没有被全局禁用jq .disableAllHooks ~/.claude/settings.json如果输出true说明 hooks 被关掉了改成false或删掉这个字段。5. 本篇常见错排查多 Agent 配置最容易出问题的地方我整理成几条按出现频率排序。第一条claude agents看到的结果跨项目导致误操作。这个我实测下来确实如此它更像一个全局后台会话管理器不是当前项目专属列表。如果你同时在多个项目里开了后台会话列表会混在一起。降低风险的做法是创建时带名字比如claude --bg --name my-app-test-check 检查当前项目测试失败原因查看时用claude agents --cwd ~/projects/my-app过滤停止或删除前先claude logs id看日志不确定就先claude attach id确认归属。第二条把claude agents和/agents当成一回事。前者是 CLI 命令管后台会话后者是 slash command管 subagent。你在终端里敲claude agents和在会话里敲/agents看到的是完全不同的东西。这个混淆会导致你以为后台任务没了其实只是看错了地方。第三条hooks 配置覆盖了原有内容。合并时一定要保留已有节点JSON 里同名 key 后者覆盖前者直接粘贴会丢配置。改完用jq验证别凭肉眼。第四条通知不弹。先确认系统通知权限给了终端应用再确认osascript命令单独能跑通最后确认 hook 节点存在。三层都过了还不弹就检查disableAllHooks是不是true。第五条删除后台会话时连带清掉 worktree。如果 Claude 为后台会话创建了独立 worktree删除会话可能清理对应 worktree里面有未提交改动就会一起没。删除前确认这个会话有没有 worktree、里面有没有未保存的改动。相对保守的做法是用claude rm id命令行删除对有未提交改动的 worktree 通常会更谨慎可能保留路径并提示你手动处理。第六条优雅退出的按键语义搞错。在claude agents视图里CtrlX第一次是 stop session短时间内第二次才是 delete session。只是想离开界面让 agent 继续跑用Esc已经 attach 进去的用←或CtrlZ只是 detach不会停止后台会话。想真正停止用claude stop id想删除用claude rm id。第七条Key 配了但请求失败。先确认ANTHROPIC_BASE_URL是https://taotoken.net/api注意 API 地址不带 UTM 参数再确认ANTHROPIC_AUTH_TOKEN是控制台里创建的有效 Key。如果还是不行去接入文档核对字段或者用模型对话页面单独测一下 Key 是否可用。6. 长期编码与 Agent 工作流的入口如果你打算把 Claude Code 当成长期运行的开发助手而不是一次性问答工具那后台会话、任务追踪、hooks 通知这几块能力会越来越重要。它们解决的不是「Claude 会不会写代码」而是「长任务跑完我能不能知道」「需要我授权时我能不能及时回来」「多个后台会话并行时我怎么管理」「结束后我怎么安全清理」这些实际协作问题。多 Agent 协作的推荐分工是主会话负责决策、整合、确认方向后台会话负责搜索、分析、验证这类长任务/tasks负责追踪当前主线任务进度。这样claude agents里看后台会话/tasks里看当前事情做到哪了职责清晰不容易乱。如果你主要在本地做长期编码、跑 Agent 工作流可以了解一下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合这种持续性的编码场景。需要管理多个 Key 或做团队协作时API Keys 页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入细节随时对照 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。Claude Code 相关的接入说明也可以看 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite 里面有更贴近 Claude Code 的配置示例。最后留一个我自己的使用习惯创建后台会话时一定带--name名字里带项目或任务信息删除前先logs再attach确认归属再stop或rm。这套流程跑顺之后Claude Code 的后台能力就更像一个可管理、可追踪、可提醒的 AI 开发工作台而不是一堆散落的会话。