OpenClaw 里 AGENTS.md 和 agent.json 到底有什么区别?一文讲清工作区规则与子代理配置的协作方式

发布时间:2026/9/30 0:26:26

OpenClaw 里 AGENTS.md 和 agent.json 到底有什么区别?一文讲清工作区规则与子代理配置的协作方式 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 节的验证调用。配置文件的错误往往在运行时才暴露而一次真实的子代理调用能在几十秒内告诉你路由、工具白名单、模型通道是否全部生效。
延伸阅读

更多相关文章

2026/9/30 0:26:26

改进YOLO发核心期刊:模块搭配、实验设计与写作策略全拆解

看到“连夜看了30多篇改进YOLO的中文核心期刊”这个标题,我第一反应是“这兄弟是不是卷疯了”。但真等我把手头攒的几十篇遥感、医学影像、工业检测方向的YOLO改进论文重新翻了一遍,发现确实有个挺明显的套路:大家其实都在做同一件事&#xf…

2026/9/30 0:26:26

Agentic AI Infra:智能体工程化落地的六大生产级能力

1. 云栖2026不是一场发布会,而是一份工程化落地的路线图“云栖2026|Agentic AI Infra,加速模型与智能体创新”——这个标题里没有一个动词,却藏着最硬核的行业信号。它不是在预告某款新模型的参数有多惊艳,也不是在展示…

2026/9/30 0:21:25

TensorFlow实战指南:安装、核心概念与PyTorch对比选型

想聊一个很多人觉得"过气"、但实际撑起半个工业界的框架——TensorFlow。我在2018年第一次接触它,当时被Variable、Session、placeholder那一套折磨得不轻,一度转投PyTorch。但后来因为工作原因,连续做了几个需要上线部署的项目&am…

2026/9/30 2:41:33

Java中toString()方法的正确使用技巧

咱们来详细说说在Java这玩意儿里面括号括起来的那个方法到底是怎么回事儿, 还有为啥这么重要的道理。在 Java 开发中,() 是我们最常用的方法之一。无论是调试程序、输出日志,还是快速查看对象内容,() 方法都起到了至关重要的作用。本篇博客将…

2026/9/30 2:41:33

一键将图片转为炫酷字符画

在这篇文章里头, 我们会去用到下面这些个知识点的哦。完整的一个程序, 那个用来把图片转换成字符画的py脚本。请先在命令行工具中找到存放图片文件的那个目录位置, 接着把当前路径切换到那个地方去执行操作, 然后启动名为图片转字符画.py的这个程序脚本并在其后面跟上参数.png这…

2026/9/30 2:41:33

cocos2d-x双人坦克大战demo:输入分发与碰撞判定实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/9/30 2:41:33

Verilog三段式状态机设计:状态编码、串口实现与跨平台映射

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/9/30 2:41:33

DETR深度解析:Transformer如何颠覆目标检测的端到端范式

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/9/29 11:07:23

东莞市品牌网站建设报价常见报错与解决

东莞品牌网站建设报价单背后:一份保姆级建站教程避坑实录 网站做好了没人访问,这大概是很多老板最头疼的事。花了大几万做的品牌站,上线后流量惨淡,比路边摊还冷清。别急着骂外包公司,很多“东莞品牌网站建设报价”里藏着不少猫腻,比如用模板站冒充定制…

2026/9/29 21:48:03

如何划分训练/验证集:Spirula Studio五种eval_mode策略详解

如何划分训练/验证集:Spirula Studio五种eval_mode策略详解 【免费下载链接】spirula-studio Cross-vendor 3D Gaussian Splatting trainer - video to splat to mesh, Vulkan or CUDA. 项目地址: https://gitcode.com/GitHub_Trending/sp/spirula-studio Sp…

2026/9/29 7:00:49

SEO怎么推广速查手册新手避坑实战指南

SEO怎么推广速查手册新手避坑实战指南 模板网站太丑不够用?别急着加滤镜,那是治标不治本。很多老板盯着后台流量掉得眼红,却还在纠结首页Banner的圆角是不是3像素。这就像穿着西装去挖土,姿势不对,努力白费。我整理这份 速查手册…

2026/9/30 0:01:22

MATLAB+Yalmip+CPLEX实战:综合能源系统优化调度全流程解析

做综合能源系统优化调度这活儿,最痛苦的不是建模本身,而是模型写完之后不知道该怎么求解。看论文里轻飘飘一句“采用Yalmip调用CPLEX求解”,自己上手时却往往卡在环境配置、变量声明、约束写法和求解状态判读上,一耗就是两三天。这…

2026/9/30 0:01:22

I3C比I2C快10倍?RK3576实战:速率、DTS配置与混合总线避坑指南

I3C 比 I2C 快 10 倍?这句话在嵌入式群里传了很久,每次都能吵出一堆截图。前段时间我正好在 RK3576 上调板级 I3C 接口,从控制器寄存器一路摸到 Linux DTS 配置,踩了不少坑,也把这笔速度账彻底算明白了。本文就用 RK35…

2026/9/30 0:01:22

字符串转对象:JSON.parse、new Function与URLSearchParams

“字符串转对象”这几个字,我在技术群里见过的问法至少有十几种:有人拿着一串{a:1,b:2}说 JSON.parse 直接报错,有人要从 URL 里抠出参数,还有人只是想把abc变成能挂属性的东西。js 这门语言里,字符串和对象之间的转换…

2026/9/29 3:53:39

USB Type-C PCB布局分区设计:电源、高速信号与PD协议全攻略

做硬件这行,Type-C接口算是典型的“看着简单,做起来全坑”的东西。光引脚就24个,高低速信号、电源、控制线全部塞在一个小小的连接器里,如果PCB布局不做规划,打样回来基本就是“插上没反应”、“高速掉线”、“静电一打…

2026/9/29 9:46:12

系统编程学习原型如何补齐稳定性边界

系统编程学习原型如何补齐稳定性边界预算有限时&#xff0c;我先优化明显多余的复制&#xff0c;而不是猜测性地换容器。用借用传递只读数据通常就能减少分配&#xff1a; fn parse(line: &str) -> Result<Item, Error> { /* ... */ }用基准确认热点确实在分配&am…

2026/9/29 6:36:14

雨花区哪家财务公司代理记账比较好?

在雨花区&#xff0c;企业处理财税事务常常面临诸多挑战&#xff0c;选择一家靠谱的财务公司至关重要。湖南巨勤财务管理咨询有限公司就是本地正规实体财税服务机构&#xff0c;深耕本地工商财税行业多年&#xff0c;熟悉当地工商局、税务局最新政策与申报流程。主营公司注册、…

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑