1. 先搞清楚 OpenClaw 多代理目录里两个文件的分工如果你刚接触 OpenClaw 的多代理体系打开工作区目录大概率会愣一下/home/water/.openclaw/workspace/AGENTS.md已经写了一大堆规则为什么每个子代理目录下还要再放一个agent.json两个文件看起来都在做“配置”改哪个、什么时候改、改了影响谁很容易搞混。先把结论摆出来AGENTS.md 是工作区级别的共享操作手册agent.json 是单个子代理的运行档案。前者回答“在这个工作区里所有代理应该遵守什么公共规则”后者回答“这个具体的代理是谁、用什么模型、能调用哪些工具、超时多久”。它们不是替代关系而是“共享规则 个体配置”的协作关系。这个区分在实际维护中非常关键。我见过有人把模型参数写进 AGENTS.md结果所有子代理都被迫用同一个模型也见过有人把仓库结构说明塞进每个 agent.json改一次目录要同步改五六个文件。理解职责边界之后这类重复劳动和误改基本可以避免。本文会给出两份配置的可复制骨架演示一次子代理调用如何验证两者协作生效并说明如何通过 TaoToken 统一 Key 和 API 通道接入让多代理的模型调用走同一条稳定链路。适合正在搭建或维护 OpenClaw 多代理工作区的开发者也适合想搞清楚“工作区规则”和“子代理配置”到底怎么配合的人。2. TaoToken 前置统一 Key 与 API 通道接入 OpenClaw 子代理在讲配置骨架之前先把模型接入这条链路理清楚。OpenClaw 的每个子代理在agent.json里都要指定model字段如果每个代理各自配一套 Key 和 Base URL维护成本会随代理数量线性增长。更合理的做法是让所有子代理共用一条统一的 API 通道TaoToken 就是干这个的。TaoToken 提供兼容 OpenAI 风格的 API 接口你可以把它理解成一个统一的模型调用入口Base URL 固定Key 统一管理模型 ID 按需切换。对 OpenClaw 这种多代理架构来说好处很直接——research、writer、bigcommontask这些子代理的agent.json里model字段可以指向同一套通道下的不同模型 ID而 Key 只需要在环境变量或全局配置里维护一份。接入前你需要准备三样东西Base URLhttps://taotoken.net/api这是所有子代理共用的请求地址。API Key在 TaoToken 控制台的 API Keys 页面创建建议按工作区分组管理方便后续轮换。Model ID根据子代理职责选择比如研究类代理用推理能力强的模型写作类代理用生成质量高的模型。如果你还没创建 Key可以先去控制台生成一个https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole 。创建之后把 Key 写进环境变量不要硬编码在agent.json里这一点后面配置骨架会体现。对于需要长期跑编码或 Agent 任务的场景Coding Plan 会更划算适合把多个子代理的调用量集中管理https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan 。如果你只是想先验证模型通道是否通可以直接在模型对话页面发一条测试请求https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat 。这里有个容易踩的坑OpenClaw 的子代理在读取agent.json时model字段的格式通常是provider/model-name这种带前缀的写法。如果你用的是统一通道需要确认 OpenClaw 的 provider 配置里已经把 TaoToken 的 Base URL 注册进去否则子代理启动时会报模型找不到。具体做法在下一节的配置骨架里会给出。3. 可复制配置AGENTS.md 与 agent.json 骨架这一节给出两份可以直接抄的配置骨架。先说明目录结构假设你的工作区根目录是/home/water/.openclaw/workspace/子代理目录在/home/water/.openclaw/agents/下每个子代理一个文件夹。3.1 AGENTS.md 工作区规则骨架AGENTS.md 放在工作区根目录承载的是所有子代理共享的规则。下面这份骨架覆盖了仓库认知、路由建议、验证规范和外部能力使用约定四块内容# Workspace Operating Guide ## 1. Repository Layout - skills/ — 主要维护区所有可复用技能脚本放这里 - scripts/ — 小工具脚本一次性任务用 - tmp/python-clients/ — 独立 Python 项目不套用根目录规则 - repos/ — 外部仓库克隆区不要在这里套用根目录 lint - node_modules/、tmp/ — 通常不要碰 ## 2. Delegation Cues - research — 适合 reading / summarizing / analysis - writer — 适合 drafting / rewriting / polishing - bigcommontask — 适合 multi-step / broad / end-to-end task ## 3. Verification - JS 语法检查node --check file - Python 语法检查python -m py_compile file - 没有 root-level CI不要发明 repo-wide lint - 修改尽量局部最小化 ## 4. External Capabilities - 需要 web search 时优先走统一搜索脚本 - 已知 URL 再用 web_fetch 精读 - 更深研究可以加 --deep 参数这份文件的关键在于它不定义任何具体代理的身份只定义“在这个工作区里大家应该怎么做”。比如路由建议里写了research适合分析类任务但并没有说research用什么模型、超时多久——那些是agent.json的事。3.2 agent.json 子代理配置骨架每个子代理目录下放一个agent.json。下面以research为例给出完整骨架{ agentId: research, description: 分析、阅读、提炼、调查, model: taotoken/gpt-4o, runTimeoutSeconds: 600, temperature: 0.3, allowedTools: [read, write, exec, web_fetch], capabilities: [reading, summarizing, analysis], notes: 做 broader web discovery 时优先走统一搜索脚本再 web_fetch 精读 }writer的骨架则明显偏内容生产{ agentId: writer, description: 草稿、改写、润色、文章结构化, model: taotoken/gpt-4o, runTimeoutSeconds: 600, temperature: 0.8, allowedTools: [read, write, exec], capabilities: [writing, editing, rewriting, article-structuring], notes: 主责是写作不承担大规模外部信息搜集 }注意writer的allowedTools里没有web_fetch这是有意的写作代理不应该自己去广泛查资料需要外部信息时应该先让research准备材料。这就是分层设计在配置层面的体现。bigcommontask作为重任务总包超时给到 900 秒工具集更全{ agentId: bigcommontask, description: larger multi-step work / synthesis / end-to-end handling, model: taotoken/gpt-4o, runTimeoutSeconds: 900, temperature: 0.5, allowedTools: [read, write, exec, web_fetch], capabilities: [multi-step, synthesis, end-to-end], notes: 需要外部研究时先 discovery 再 focused reading }三份配置里model字段都指向taotoken/前缀这意味着所有子代理的模型调用都走同一条 TaoToken 通道。你只需要在 OpenClaw 的 provider 配置里注册一次 Base URL 和 Key所有子代理自动继承。3.3 provider 配置与 Key 管理OpenClaw 的 provider 配置通常在全局配置文件里把 TaoToken 注册为一个 provider[providers.taotoken] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY然后在 shell 环境里导出 Keyexport TAOTOKEN_API_KEYsk-你的实际Key这样agent.json里的taotoken/gpt-4o就能被正确解析。Key 不落在任何配置文件里轮换时只改环境变量所有子代理同时生效。4. 验证请求一次子代理调用看两者如何协作配置写完不算完得实际跑一次才能确认 AGENTS.md 和 agent.json 真的在协作。下面用一个具体任务来验证让主代理把一个“调研 写作”的复合任务分派给research和writer。4.1 触发一次子代理调用在 OpenClaw 的交互入口发起任务比如帮我调研一下 OpenClaw 多代理配置的最佳实践然后写一篇 800 字的总结。主代理读取 AGENTS.md 里的路由建议判断这个任务需要先调研再写作于是分派给research做信息收集再把结果交给writer成稿。4.2 观察 research 子代理的行为research启动时读取自己的agent.json拿到model: taotoken/gpt-4o、allowedTools: [read, write, exec, web_fetch]、runTimeoutSeconds: 600。它执行搜索时会遵循 AGENTS.md 里的外部能力约定——优先走统一搜索脚本已知 URL 再用web_fetch。你可以通过日志确认模型调用走的是 TaoToken 通道。如果 provider 配置正确请求会发往https://taotoken.net/api返回正常的 completion 结果。4.3 观察 writer 子代理的行为research完成后主代理把材料转给writer。writer读取自己的agent.json拿到temperature: 0.8和allowedTools: [read, write, exec]。注意它没有web_fetch所以它不会自己去查资料只会基于research提供的材料写作。这正是 AGENTS.md 里“writer 适合 drafting / rewriting / polishing”这条路由建议在运行时的落地。4.4 验证两者协作生效的判断标准一次成功的协作调用应该满足这几个条件research的模型调用走 TaoToken 通道返回正常research遵循了 AGENTS.md 里的搜索约定没有乱调工具writer没有尝试web_fetch说明allowedTools白名单生效writer的temperature生效输出风格偏创作而非分析整个链路没有出现模型找不到或 Key 无效的报错如果这五点都满足说明 AGENTS.md 的共享规则和 agent.json 的个体配置在协作层面已经打通。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置多代理时报错往往集中在几个固定位置。下面按真实报错逐条排查。5.1 401 Unauthorized最常见的原因是TAOTOKEN_API_KEY没有正确导出或者 Key 已失效。先确认环境变量echo $TAOTOKEN_API_KEY如果为空说明 shell 会话里没导出。如果非空但仍然 401去控制台检查 Key 状态https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys 。另外注意agent.json里不要硬编码 Key否则轮换时会漏改。5.2 local proxy failed这个报错通常出现在 OpenClaw 尝试连接 provider 时。检查providers.taotoken的base_url是否写成了https://taotoken.net/api不要多加路径或斜杠。如果本地有网络层配置确认没有拦截对taotoken.net的请求。这个报错和 Key 无关纯粹是连接层问题。5.3 reading choices 相关报错如果日志里出现reading choices或choices字段解析失败通常是模型返回格式和 OpenClaw 预期不一致。先确认model字段的格式是taotoken/gpt-4o这种带 provider 前缀的写法而不是裸模型名。如果格式正确仍然报错用模型对话页面单独测一下该模型 ID 是否可用https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat 。5.4 OAuth 相关报错OpenClaw 某些 provider 走 OAuth 流程如果你混用了 OAuth 和 API Key 两种认证方式可能报 OAuth 错误。统一走 TaoToken 的 API Key 通道时确认 provider 配置里没有残留 OAuth 相关字段。如果之前配过其他 provider 的 OAuth清理掉对应配置再重启。5.5 子代理找不到模型如果报错说模型不存在检查两点一是agent.json里的model前缀是否和 provider 配置里的名称一致比如都是taotoken二是 provider 配置是否在全局配置里正确注册。两者不一致时子代理启动就会失败。排查完这些如果还有问题接入文档里有更详细的字段说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc 。6. 把统一通道接进你的 OpenClaw 工作流回到最开始的问题AGENTS.md 和 agent.json 到底怎么配合一句话总结——凡是“所有代理在这个工作区都该知道的”放 AGENTS.md凡是“只有这个代理自己需要携带的”放 agent.json。前者让团队不乱后者让成员不混。而 TaoToken 在这套体系里的角色是把所有子代理的模型调用收敛到一条通道上。你不需要为每个子代理单独申请 Key、单独配 Base URL只需要在 provider 层注册一次所有agent.json里的model字段自动走同一条链路。Key 轮换、模型切换、用量统计都在一个地方完成。如果你正在维护多个 OpenClaw 工作区建议把 TaoToken 的 Key 按工作区分组配合 Coding Plan 管理长期任务的调用量https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan 。需要新建 Key 时走控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole 。接入过程中遇到字段问题先查文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc 。最后留一个实操建议每次改完 AGENTS.md 或某个 agent.json不要只靠肉眼检查跑一次上面第 4 节的验证调用。配置文件的错误往往在运行时才暴露而一次真实的子代理调用能在几十秒内告诉你路由、工具白名单、模型通道是否全部生效。
