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 URL：https://taotoken.net/api，这是所有子代理共用的请求地址。
• API Key：在 TaoToken 控制台的 API Keys 页面创建，建议按工作区分组管理，方便后续轮换。
• Model ID：根据子代理职责选择，比如研究类代理用推理能力强的模型，写作类代理用生成质量高的模型。

如果你还没创建 Key，可以先去控制台生成一个：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=console 。创建之后把 Key 写进环境变量，不要硬编码在agent.json里，这一点后面配置骨架会体现。

对于需要长期跑编码或 Agent 任务的场景，Coding Plan 会更划算，适合把多个子代理的调用量集中管理：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=coding-plan 。如果你只是想先验证模型通道是否通，可以直接在模型对话页面发一条测试请求：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=chat 。

这里有个容易踩的坑：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 环境里导出 Key：

export TAOTOKEN_API_KEY="sk-你的实际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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=api-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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=chat 。

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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=doc 。

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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=coding-plan 。需要新建 Key 时走控制台：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=console 。接入过程中遇到字段问题，先查文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=doc 。

最后留一个实操建议：每次改完 AGENTS.md 或某个 agent.json，不要只靠肉眼检查，跑一次上面第 4 节的验证调用。配置文件的错误往往在运行时才暴露，而一次真实的子代理调用能在几十秒内告诉你路由、工具白名单、模型通道是否全部生效。