1. 为什么多 Agent 协作总在配置这一步卡住OpenClaw 是一个跑在你自己设备上的个人 AI 助手框架核心是一个 Gateway 控制平面它连接飞书、Telegram、Discord 等消息渠道托管多个互相隔离的 Agent每个 Agent 有独立的工作空间、身份文件和会话记录再通过 bindings 绑定规则把不同渠道的消息路由到不同 Agent。多 Agent 的价值在于分工——主助手负责协调代码专家负责写代码运维专家负责部署产品助手负责整理需求它们之间还能通过 sessions_* 工具族互相发消息形成一条完整的协作链路。但真正动手搭的时候绝大多数人卡在同一个地方每个 Agent 都要配模型通道每个通道都要一份 Key、一个 baseUrl、一套参数。四个 Agent 就是四份配置改一个模型要同步改四处漏一处就报 401 或者模型不存在。我试过把同一份 Key 复制到四个 Agent 的配置里结果轮换 Key 的时候漏掉了一个那个 Agent 静默失败了两天才被发现。这篇教程要解决的就是这个问题用 TaoToken 作为统一的 Key 和 API 通道让所有 Agent 共用一套接入配置只改一处就能全局生效。下面从零给出 config.toml 与 settings.json 的可复制骨架演示统一 Key 怎么接进各 Agent再附上启动验证和常见报错排查。适合已经在跑 OpenClaw、想从单 Agent 扩展到多 Agent 协作的读者也适合刚接触 OpenClaw 想直接按多 Agent 架构起步的人。2. 前置准备TaoToken 统一 Key 与 OpenClaw 环境2.1 为什么用统一 Key 而不是每个 Agent 一份多 Agent 场景下模型调用量会成倍上升主助手要理解需求、代码专家要生成代码、运维专家要写部署脚本、产品助手要整理文档四个 Agent 可能同时在工作。如果每个 Agent 各配一份 Key会带来三个麻烦一是 Key 轮换时要逐个更新容易漏二是用量分散在多个 Key 上看不到整体消耗三是不同 Agent 想切换模型时要改的配置文件太多。TaoToken 的做法是提供一个统一的 API 通道所有 Agent 都指向同一个 baseUrl、用同一个 Key模型选择在请求里指定。这样配置骨架只需要维护一份 provider 定义Agent 层面只声明用哪个模型 ID。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 注意 API 地址不带 UTM 参数。2.2 获取 Key 与确认模型清单先到控制台创建 API Key入口是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。创建后在 API Keys 页面可以查看和管理地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。建议给多 Agent 场景单独建一个 Key方便按项目统计用量。拿到 Key 之后先确认你要用的模型 ID。不同 Agent 可以指定不同模型代码专家用偏代码能力的模型运维专家用通用推理模型产品助手用响应快的轻量模型。模型清单和接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 接入前先扫一遍确认模型 ID 拼写后面配置里写错一个字符就会报模型不存在。2.3 OpenClaw 基础环境OpenClaw 要求 Node.js 22 及以上。用 nvm 装最省事curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 22 nvm use 22 nvm alias default 22 node --version然后全局安装 OpenClawnpm install -g openclawlatest openclaw --version小内存服务器建议加一个编译缓存减少 Node 模块加载时间grep -q NODE_COMPILE_CACHE ~/.bashrc || cat ~/.bashrc EOF export NODE_COMPILE_CACHE/var/tmp/openclaw-compile-cache mkdir -p /var/tmp/openclaw-compile-cache export OPENCLAW_NO_RESPAWN1 EOF source ~/.bashrc3. 可复制配置骨架config.toml 与 settings.json3.1 统一 Provider 定义config.tomlOpenClaw 支持 TOML 和 JSON 两种配置格式多 Agent 场景下 TOML 的可读性更好嵌套层级清晰。先建配置目录mkdir -p ~/.openclaw/workspace-main mkdir -p ~/.openclaw/workspace-coder mkdir -p ~/.openclaw/workspace-ops mkdir -p ~/.openclaw/workspace-product然后写~/.openclaw/config.toml核心是把 TaoToken 定义成一个 provider所有 Agent 共用# Gateway 配置 [gateway] bind loopback port 18789 mode local # 统一 ProviderTaoToken [models] mode merge [models.providers.taotoken] baseUrl https://taotoken.net/api apiKey ${TAOTOKEN_API_KEY} api openai-completions [[models.providers.taotoken.models]] id claude-sonnet-4-5 name Claude Sonnet 4.5 contextWindow 200000 maxTokens 8192 [[models.providers.taotoken.models]] id claude-haiku-4-5 name Claude Haiku 4.5 contextWindow 200000 maxTokens 8192 [[models.providers.taotoken.models]] id gpt-4.1 name GPT-4.1 contextWindow 128000 maxTokens 8192 # Agent 默认模型 [agents.defaults] model { primary taotoken/claude-sonnet-4-5 } workspace ~/.openclaw/workspace-main这里的关键点apiKey用${TAOTOKEN_API_KEY}引用环境变量不要把明文 Key 写进配置文件。环境变量在 shell 里设置echo export TAOTOKEN_API_KEYsk-your-taotoken-key ~/.bashrc source ~/.bashrcapi openai-completions表示走 OpenAI 兼容的/v1/chat/completions接口TaoToken 的 API 通道兼容这个协议所以 OpenClaw 不需要额外的适配层。3.2 多 Agent 定义settings.jsonAgent 列表和路由绑定放在~/.openclaw/settings.json和 config.toml 配合使用。四个 Agent 各自声明模型但都指向同一个 taotoken provider{ agents: { list: [ { id: main, name: 主助手, default: true, workspace: ~/.openclaw/workspace-main, agentDir: ~/.openclaw/agents/main/agent, model: taotoken/claude-sonnet-4-5, subagents: { allowAgents: [coder, ops, product] } }, { id: coder, name: 代码专家, workspace: ~/.openclaw/workspace-coder, agentDir: ~/.openclaw/agents/coder/agent, model: taotoken/claude-sonnet-4-5 }, { id: ops, name: 运维专家, workspace: ~/.openclaw/workspace-ops, agentDir: ~/.openclaw/agents/ops/agent, model: taotoken/gpt-4.1 }, { id: product, name: 产品助手, workspace: ~/.openclaw/workspace-product, agentDir: ~/.openclaw/agents/product/agent, model: taotoken/claude-haiku-4-5 } ] }, tools: { agentToAgent: { enabled: true, allow: [main, coder, ops, product] }, sessions: { visibility: all } }, bindings: [ { agentId: main, match: { channel: feishu, accountId: main } }, { agentId: coder, match: { channel: feishu, accountId: coder } }, { agentId: ops, match: { channel: feishu, accountId: ops } }, { agentId: product, match: { channel: feishu, accountId: product } } ] }注意model字段的写法是taotoken/模型ID前缀taotoken对应 config.toml 里models.providers.taotoken这个 provider 名。四个 Agent 的模型可以不同但 provider 前缀都是taotoken这就是统一 Key 的体现——换 Key 只改环境变量一处换 baseUrl 只改 config.toml 一处。3.3 各 Agent 的身份文件每个 Agent 的 workspace 里放一个AGENTS.md定义身份和协作规则。主助手的身份文件~/.openclaw/workspace-main/AGENTS.md# 主助手 你是全能协调者负责接收用户需求并分派任务。 ## 协作规则 - 代码开发任务用 sessions_send 转发给 coder - 服务器部署任务用 sessions_send 转发给 ops - 需求整理任务用 sessions_send 转发给 product - 收到子 Agent 回复后整合结果返回给用户代码专家的~/.openclaw/workspace-coder/AGENTS.md# 代码专家 你是资深软件工程师专注代码开发与审查。 ## 工作规范 - 代码必须有注释 - 提交前确认可运行 - 遇到架构问题主动咨询主助手运维专家和产品助手照此格式各写一份重点是让每个 Agent 知道自己该做什么、不该做什么避免任务在 Agent 之间来回踢皮球。4. 启动验证与成功结果4.1 启动 Gateway配置写完后先做一次语法检查再启动openclaw doctor openclaw gateway --port 18789 --verbosedoctor会检查配置文件格式、环境变量是否设置、模型 provider 是否可达。如果这一步报TAOTOKEN_API_KEY not found说明环境变量没生效重新source ~/.bashrc或者检查 shell 类型。前台启动确认没问题后转后台nohup openclaw gateway run --bind loopback --port 18789 /tmp/openclaw-gateway.log 21 tail -f /tmp/openclaw-gateway.log4.2 验证模型通道先确认 TaoToken provider 被正确加载openclaw models list预期输出里应该能看到taotoken/claude-sonnet-4-5、taotoken/gpt-4.1等条目。然后直接测一次模型响应openclaw agent --message 用一句话介绍你自己 --thinking low如果返回正常文本说明统一 Key 通道打通了。再测指定 Agentopenclaw agent --agent coder --message 写一个 Python hello world openclaw agent --agent ops --message 列出三个常见的 Docker 部署检查项4.3 验证 Agent 间通信多 Agent 协作的核心是 sessions_* 工具族。先看活跃会话openclaw agent --message 请用 sessions_list 列出当前所有活跃的 Agent 会话再测跨 Agent 消息openclaw agent --message 请用 sessions_send 向 coder 发送你好代码专家请准备接收任务预期结果是主助手调用 sessions_sendcoder 收到消息并回复主助手把回复整合后返回。如果这一步成功说明 AgentToAgent 工具配置生效了。4.4 检查整体状态openclaw gateway status openclaw agents list --bindings openclaw channels status --probeagents list --bindings会显示每个 Agent 绑定的渠道和账号确认四个 Agent 都指向了正确的飞书账号。channels status --probe会实际探测渠道连通性飞书账号显示 connected 才算真正可用。5. 本篇常见报错排查5.1 模型调用报 401 或 Key 无效最常见的原因是环境变量没传进 Gateway 进程。如果你用 systemd 启动~/.bashrc里的环境变量不会自动加载需要在 service 文件里显式声明[Service] EnvironmentTAOTOKEN_API_KEYsk-your-key或者用EnvironmentFile指向一个只含 Key 的文件。排查时先确认进程能看到变量cat /proc/$(pgrep -f openclaw-gateway)/environ | tr \0 \n | grep TAOTOKEN5.2 报模型不存在model not found检查settings.json里model字段的写法必须是taotoken/模型ID前缀和 config.toml 里的 provider 名完全一致。常见错误是写成taotoken:模型ID或者漏了前缀。另外确认模型 ID 拼写和文档里一致大小写敏感。5.3 Agent 间通信不生效先确认tools.agentToAgent.enabled是 true且allow列表包含所有需要互通的 Agent IDopenclaw config get tools.agentToAgent如果 allow 列表漏了某个 Agent那个 Agent 就无法被其他 Agent 调用。另外sessions.visibility设为all时所有 Agent 能看到彼此会话设为tree时只能看到自己派生的子 Agent按需选择。5.4 Gateway 启动失败或端口占用ss -ltnp | grep 18789 pkill -f openclaw-gateway nohup openclaw gateway run --bind loopback --port 18789 /tmp/openclaw-gateway.log 21 如果日志里报配置解析错误用openclaw doctor定位具体行号。TOML 和 JSON 混用时注意config.toml 管 provider 和 gatewaysettings.json 管 agents 和 bindings两者不要写重复的键否则后加载的会覆盖前面的。5.5 修改配置后不生效OpenClaw 不会热加载配置改完必须重启openclaw gateway restart openclaw doctor openclaw agents list --bindings重启后如果 Agent 行为还是旧的检查是不是有多个 Gateway 进程在跑pgrep -f openclaw看一下多余的杀掉。6. 把统一 Key 用顺之后的下一步统一 Key 打通之后多 Agent 的维护成本会明显下降。我的做法是把TAOTOKEN_API_KEY放在一个独立的 env 文件里systemd 和手动启动都引用同一个文件轮换 Key 时只改这一处四个 Agent 同时生效。模型切换也一样改settings.json里对应 Agent 的model字段就行provider 定义不用动。如果你想让 Agent 长期跑编码任务可以看看 Coding Plan入口是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 适合需要持续调用模型的场景。想先在网页里验证模型响应再写进配置用模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 更快。接入过程中遇到报错先翻接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 大部分配置问题那里都有对照说明。Claude Code 相关的接入配置可以参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 多 Agent 里如果有 Agent 专门跑 Claude Code这份配置能直接复用。最后提醒一个容易忽略的点多 Agent 同时工作时会话历史会快速增长定期清理~/.openclaw/agents/*/sessions/下的旧 jsonl 文件避免磁盘被占满导致 Gateway 写入失败。