1. 为什么你的 OpenClaw 需要一个 Agent HubOpenClaw 的 agent 体系有个很实在的特点每个 agent 都是独立运行的main agent 没有内置机制把任务派发给其他 agent。这意味着你装了一堆模型实际用起来还是只能跟主模型对话图片分析、代码生成、翻译润色全压在一个模型身上。主模型什么都能干但可能什么都干不精——分析图片不如专门的视觉模型写代码不如专门负责 coding 的模型。Agent Hub 就是来解决这个问题的。它是一个主从式多 agent 调度系统用户和 main agent 交互main agent 通过 Skill 机制调用 hub.py把任务分发给对应的专业 agent。整个链路是「用户 → main agent → hub.py → openclaw agent CLI → OpenClaw Gateway → 专业 agent → 返回结果」。这套设计有个关键取舍hub.py 不直接调 API只封装 openclaw agent CLI。认证、工具权限、会话管理全由 OpenClaw Gateway 兜底hub.py 只负责本地预处理——URL 下载、媒体格式包装、QQ 标签生成。这样做的好处是权限体系不会被绕过你不需要在 hub.py 里再维护一套 key 管理逻辑。而多模型接入这块我用 TaoToken 的统一 Key 来打通。TaoToken 提供 OpenAI 兼容的 API 通道一个 Key 就能路由到不同模型省去在 OpenClaw 里为每个 provider 单独配 key 的麻烦。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。适合谁看已经在用 OpenClaw、想让多个专业模型各司其职的人手上有多个模型 key、想统一管理的人想搭一套可扩展 agent 调度系统的人。下面从目录结构开始一步步把 Agent Hub 搭起来。2. TaoToken 前置准备与 OpenClaw 环境检查在动手改配置之前先把两件事确认清楚TaoToken 的 Key 拿到手OpenClaw 版本够新。2.1 获取 TaoToken API Key打开 https://taotoken.net/api-keys 登录后创建一个 API Key。这个 Key 就是后面所有模型调用的统一凭证。创建时建议给它起个能认出来的名字比如openclaw-agent-hub方便以后在控制台里区分。拿到 Key 之后先别急着往 OpenClaw 里塞。用一条 curl 验证通道是否通curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoTokenKey \ -H Content-Type: application/json \ -d { model: qwen/qwen3-coder, messages: [{role: user, content: 回复 ok}] }返回里能看到choices数组和内容说明 Key 和通道都没问题。如果返回 401检查 Key 有没有复制完整、有没有多余空格。2.2 检查 OpenClaw 版本与依赖Agent Hub 依赖 OpenClaw 2026.3.8因为这个版本才支持--json输出和agents.list配置。查版本openclaw --version低于这个版本的话先升级。另外确认 Python 3 和 Node.js 都在python3 --version node --version如果你需要语音分析功能还得装 qqbot 插件因为silk2wav.js硬编码了依赖路径~/.openclaw/extensions/qqbot/node_modules/silk-wasm。检查一下这个路径存不存在ls ~/.openclaw/extensions/qqbot/node_modules/silk-wasm不存在就先装 qqbot 插件或者手动npm install silk-wasm到该路径。这一步不做的话语音相关功能会直接报Cannot find module silk-wasm。2.3 把 TaoToken 配成 OpenClaw 的 providerOpenClaw 的 provider 配置在~/.openclaw/openclaw.json。找到 providers 段加入 TaoToken{ providers: { taotoken: { type: openai-compatible, baseUrl: https://taotoken.net/api/v1, apiKey: sk-你的TaoTokenKey } } }这里baseUrl用https://taotoken.net/api/v1不要带 UTM 参数。配好之后模型 ID 就可以写成taotoken/模型名的形式比如taotoken/qwen/qwen3-coder。改完配置跑一下openclaw doctor确认 provider 被正确识别。如果 doctor 报 provider 连接失败先回到 2.1 的 curl 步骤排查别急着往下走。3. Agent Hub 目录结构与可复制配置片段Agent Hub 的目录结构不复杂核心就几个文件。先建目录再逐个填配置。3.1 目录结构agent-hub/ ├── hub.py # 核心CLI 封装 媒体预处理 ├── agent-lists.json # 配置你的 agent 清单 ├── add_agent.sh # 一键注册新 agent ├── remove_agent.sh # 一键移除 agent ├── silk2wav.js # 语音格式转换QQ 语音适配 ├── voice_analyze.sh # 语音分析流水线 └── requirements.md # 依赖清单把整个目录拷到 OpenClaw workspacecp -r agent-hub/ ~/.openclaw/workspace/agent-hub/ cd ~/.openclaw/workspace/agent-hub/3.2 agent-lists.json 配置这个文件定义你的 agent 军团。每个 agent 有 model、description、emoji、capabilities 四个字段{ agents: { omni-agent: { model: taotoken/healer-alpha, description: 全模态图片/视频/音频分析, emoji: , capabilities: [image, video, audio, vision, multimodal] }, coder-agent: { model: taotoken/qwen/qwen3-coder, description: 代码生成/调试/优化, emoji: , capabilities: [code, debug, refactor] }, translator-agent: { model: taotoken/stepfun/step-3.5-flash, description: 多语言翻译/文本润色, emoji: , capabilities: [translate, polish] } } }注意 model 字段用的是taotoken/前缀这样所有请求都走 TaoToken 统一通道。capabilities 目前用于文档化和列表展示手动指定 agent 是必须的——hub.py 不会自动路由你不能只说「写代码」让系统自己选。3.3 注册 agent 到 OpenClaw用add_agent.sh一条命令完成注册。它自动执行 8 步备份 openclaw.json、添加 agent 到 agents.list、创建 agent 目录 config.json、创建 workspace SOUL.md、更新 agent-lists.json、重新生成 SKILL.md、跑 openclaw doctor 验证、重启 Gateway 并自动测试。bash add_agent.sh omni-agent taotoken/healer-alpha \ 全模态分析 你是视觉分析专家擅长描述图像、视频和音频内容。 bash add_agent.sh coder-agent taotoken/qwen/qwen3-coder \ 代码专家 你是编程专家写出简洁高效的代码附带必要的注释。 bash add_agent.sh translator-agent taotoken/stepfun/step-3.5-flash \ 翻译专家 你是多语言翻译专家保留原文风格和语气。三个 agent 注册完你的多模型军团就成型了。每个 agent 的 system prompt 是add_agent.sh的最后一个参数直接写就行。3.4 换模型与加能力标记想换模型重新跑一次add_agent.sh覆盖即可bash add_agent.sh coder-agent taotoken/deepseek/deepseek-coder \ 代码专家 你是编程专家。capabilities 字段可以加自定义标记后续在 hub.py 里实现自动路由时用得上capabilities: [math, statistics, latex, long-context]4. 验证请求与成功结果配置写完得验证整条链路真的通了。分三步列 agent、测文本、测多模态。4.1 查看已注册的 agentpython3 hub.py list正常输出会列出三个 agent 的 id、model、description。如果这里报错多半是 agent-lists.json 格式有问题用python3 -m json.tool agent-lists.json检查 JSON 合法性。4.2 测试代码生成JSON 输出python3 hub.py coder-agent 用 Python 写个 Hello World --json--json参数让 hub.py 输出结构化结果方便后续程序处理。成功的话你会看到类似{ agent: coder-agent, model: taotoken/qwen/qwen3-coder, result: print(Hello World), status: ok }如果返回里status不是 ok或者报reading choices错误说明模型返回格式不对往下看第 5 节的排查。4.3 测试图片分析自动下载 URLpython3 hub.py omni-agent 描述内容 -i https://example.com/photo.jpghub.py 会自动下载 URL 资源到本地包装成[media attached: ...]格式再传给 openclaw agent CLI。成功的话 omni-agent 会返回对图片的描述。4.4 多模态组合测试支持任意组合图片 视频对比python3 hub.py omni-agent 对比这两张图和这段视频 -i a.jpg -i b.jpg -v clip.mp4纯音频分析python3 hub.py omni-agent 这段录音的背景噪音是什么类型 -a recording.wav注意 healer-alpha 分析声音特征频率分布、振幅变化、噪音类型但不做语音转文字。要 transcript 得额外装 whisper。4.5 QQ 富媒体输出加--qq参数输出带qqimg/qqvoice/qqvideo标签直接发给 QQ 机器人python3 hub.py omni-agent 描述这张图 -i photo.jpg --qq5. 本篇常见错误排查搭 Agent Hub 踩坑是常态下面几个是我实际遇到过的对照报错找解法。5.1 401 Unauthorized最常见。原因通常是 TaoToken Key 没配对或者 openclaw.json 里 provider 的 apiKey 字段写错。检查两处~/.openclaw/openclaw.json的 providers.taotoken.apiKey以及 agent 的 model 前缀是不是taotoken/。如果 Key 里有多余空格或换行也会 401。5.2 local proxy failed这个报错说明 OpenClaw Gateway 到 provider 的连接没建立起来。先确认 Gateway 在跑openclaw gateway status。如果 Gateway 正常检查 baseUrl 是不是https://taotoken.net/api/v1末尾不要多斜杠。网络层面确认能访问 taotoken.net。5.3 reading choices 报错模型返回的 JSON 里没有choices字段或者格式不符合 OpenAI 兼容规范。先回到 2.1 的 curl 步骤确认 TaoToken 通道本身返回正常。如果 curl 正常但 hub.py 报这个错检查 agent 的 model ID 有没有拼错——拼错的模型名有时会返回非标准错误体。5.4 OAuth 相关报错如果你之前配过 OAuth 类型的 providerOpenClaw 可能优先走 OAuth 而不是 API Key。检查 openclaw.json 里有没有冲突的 provider 配置把不需要的 OAuth provider 注释掉或删掉。5.5 免费模型限流 429TaoToken 上的:free模型限流约 8 次/分钟。同时触发多个 agent 会撞 429。应对关键任务用付费模型或者在批量调用时加sleep 8间隔。5.6 healer-alpha 的 audio 不是语音转写它能分析声音特征但不能输出文字 transcript。要语音转文字额外装 whisperpip3 install faster-whisper然后自己封装一个 whisper-agent。5.7 视频分析超时大视频文件可能超过默认 120 秒超时。先用 ffmpeg 裁剪ffmpeg -i big_video.mp4 -t 10 -c copy short_clip.mp4 python3 hub.py omni-agent 描述这段视频 -v short_clip.mp4 -t 300-t 300把超时提到 300 秒。5.8 silk-wasm 路径硬编码报错silk2wav.js报Cannot find module silk-wasm检查ls ~/.openclaw/extensions/qqbot/node_modules/silk-wasm不存在就先装 qqbot 插件或手动npm install silk-wasm到该路径。6. 扩展思路与接入文档Agent Hub 跑通之后几个扩展方向比较自然。自动路由在 hub.py 开头加意图分类用关键词匹配或轻量模型判断该调哪个 agent。这样你就不用每次手动指定 agent id。结果缓存在call_agent()前对(agent_id, task, media_paths)做 hash缓存到~/.openclaw/hub/cache/。重复任务直接命中缓存。媒体缓存prepare_media()内按 URL MD5 存下载文件避免重复下载。批量处理新加batch.py遍历文件夹逐个调 hub.py结果写 CSV/JSONL。Web API用 FastAPI 包装暴露/agent/{agent_id}endpoint接收 multipart/form-data。这些扩展都基于现有代码结构不需要大改。Agent Hub 解决的核心问题很简单不要让一个模型干所有事。专业的事交给专业的模型hub.py 做预处理和封装OpenClaw 做底层调度TaoToken 做统一 Key 通道。三件套组合起来5 分钟部署一条命令加 agent。接入文档在 https://taotoken.net/doc 模型对话入口 https://taotoken.net/models 长期编码和 Agent 场景可以看 Coding Plan https://taotoken.net/coding-plan 。先把三个 agent 跑通再按上面的扩展思路往上加你的多模型军团就成型了。