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

AI攻城狮
3 阅读6分钟

很多人第一次看 OpenClaw 的多代理目录结构时，都会有一个直觉疑问：既然已经有了 /home/water/.openclaw/workspace/AGENTS.md，为什么每个子代理下面还要再放一个 agent.json？这两个文件看起来都像“配置”，但它们解决的其实不是同一个层面的问题。

如果用一句话概括：

  • AGENTS.md 是工作区级别的 shared operating guide
  • agent.json 是单个子代理的 runtime/persona/capability config

两者不是替代关系，而是**“共享规则 + 个体配置”**的协作关系。前者定义一个 workspace 里的通用协作方式，后者定义某个 agent 自己是什么、能做什么、该怎么做。

一、先看整体：它们分别回答什么问题？

在 OpenClaw 这种多 agent 架构里，常见有两个维度：

1）/home/water/.openclaw/workspace/AGENTS.md 回答的是

在这个 workspace 里，所有会进来工作的 agent 应该遵守什么公共规则？

比如：

  • 仓库结构怎么理解
  • 默认工作方式是什么
  • 哪类任务该路由给哪个子代理
  • 修改代码后怎么验证
  • 哪些目录敏感、哪些目录不要碰
  • 当需要 web search 时优先走什么路径

它更像团队里的 “项目协作手册” 或 “工程现场作业说明书”。

2）/home/water/.openclaw/agents/*/agent.json 回答的是

这个具体的 agent 是谁？它的角色、模型、工具权限、超时、备注说明是什么？

例如：

  • /home/water/.openclaw/agents/research/agent.json
  • /home/water/.openclaw/agents/writer/agent.json
  • /home/water/.openclaw/agents/bigcommontask/agent.json

这些文件描述的是某个 agent 的个体属性，更像：

  • runtime profile
  • persona definition
  • capability boundary
  • tool allowlist
  • execution timeout

也就是“这个人是谁”，而不是“这个团队怎么协作”。

二、AGENTS.md：共享工作区规则，偏“环境与流程”

看 /home/water/.openclaw/workspace/AGENTS.md，你会发现它的内容不是在定义某个 agent 的人格，而是在定义整个 workspace 的共识。

它主要覆盖几类信息：

1. 仓库与目录认知

例如它会说明：

  • skills/ 是主要维护区
  • scripts/ 是小工具脚本
  • tmp/python-clients/ 是独立 Python 项目
  • repos/ 下不要套用根目录规则
  • node_modules/、tmp/ 里很多内容通常不该碰

这类信息对 research、writer、bigcommontask 都是通用的。

2. 路由与分工建议

这个文件里明确写了 delegation cues：

  • research：适合 reading / summarizing / analysis
  • writer：适合 drafting / rewriting / polishing
  • bigcommontask：适合 multi-step / broad / end-to-end task

注意，这不是在“创建”这些 agent，而是在给主 agent 或其他协作者一个统一的 dispatch policy。

3. 验证与工程规范

比如：

  • JS 用什么方式做 syntax check
  • Python 怎么做 py_compile
  • 没有 root-level CI，不要发明 repo-wide lint
  • 修改时尽量局部最小化

这类内容和 agent 身份无关，但和 workspace 行为强相关。

4. 通用外部能力使用规则

比如该文件明确提到 Tavily 搜索：

  • 优先通过 exec 跑 skills/tavily-search/scripts/search.mjs
  • 已知 URL 再用 web_fetch
  • 需要更深研究可以加 --deep

这就是典型的工作区级操作习惯：不是某一个 agent 独有，而是整个 workspace 的推荐路径。

三、agent.json：单个子代理配置，偏“身份与权限”

再看各个子代理的 agent.json，味道就完全不同了。这里不是在讲 repo 规则，而是在定义 agent 自身。

1）/home/water/.openclaw/agents/research/agent.json

这个文件的关键信息是：

  • agentId: research
  • description: 分析、阅读、提炼、调查
  • model: github-copilot/gpt-5.4
  • runTimeoutSeconds: 600
  • allowedTools: read, write, exec, web_fetch
  • notes: 明确建议优先用 Tavily 做搜索发现，再用 web_fetch 读具体 URL

这说明 research 不是抽象概念，而是一个有工具边界和行为提示的运行实体。 尤其 allowedTools 很关键：它决定这个 agent 在 runtime 里到底能调用什么。

2）/home/water/.openclaw/agents/writer/agent.json

Writer 的配置明显更偏内容生产：

  • agentId: writer
  • temperature: 0.8
  • capabilities: writing、editing、rewriting、article-structuring 等
  • allowedTools: read, write, exec

这里最值得注意的是两点：

  • 它有更明确的创作型 capability 标签
  • 它没有 web_fetch

也就是说，writer 的职责是“写”，不是“广泛查”。如果任务需要大规模外部信息搜集，通常应该先让 research 做材料准备，再交给 writer 生成成稿。这就是分层设计。

3）/home/water/.openclaw/agents/bigcommontask/agent.json

BigCommonTask 则更像一个“重任务总包”：

  • description: larger multi-step work / synthesis / end-to-end handling
  • runTimeoutSeconds: 900
  • allowedTools: read, write, exec, web_fetch
  • notes: 需要外部研究时，优先 Tavily discovery，再 web_fetch 精读

它和 research 的区别不是“会不会查”，而是任务粒度不同：

  • research：更偏“读、提炼、分析”
  • bigcommontask：更偏“查 + 执行 + 汇总 + 交付”

四、最核心的区别：一个管“共识”，一个管“个体”

如果把 OpenClaw 的多代理系统类比成一个小型工程团队：

  • AGENTS.md 像团队的《协作手册》
  • agent.json 像每位成员的《岗位说明书 + 权限卡 + 设备配置》

两者分工可以归纳为：

AGENTS.md 负责

  • workspace 级规则
  • 任务路由原则
  • 工程结构说明
  • 通用验证方法
  • 共享 best practice

agent.json 负责

  • agent 身份与定位
  • model 选择
  • allowedTools 白名单
  • timeout / temperature
  • 针对该 agent 的 notes

这就是典型的 policy vs profile 分层：

  • AGENTS.md 更接近 shared policy
  • agent.json 更接近 agent profile

五、一个很实用的理解方式：谁改了会影响谁？

这是判断职责边界最简单的方法。

修改 /home/water/.openclaw/workspace/AGENTS.md，通常影响：

  • 所有进入该 workspace 的 agent
  • 主 agent 的任务分派逻辑
  • 统一的执行习惯和工程约束

比如你把 Tavily 搜索流程写进这里，那么 research 和 bigcommontask 在这个 workspace 里就都应该优先遵循它。

修改某个 agent.json，通常影响：

  • 仅该 agent 本身
  • 它的可用工具、超时、角色定义
  • 它被调用时的行为倾向

比如你改 /home/water/.openclaw/agents/writer/agent.json 的 temperature，不会改变 research 的行为；你给 writer 增加 capability，也不会自动改变 workspace 路由规则。

六、结合 Tavily 工作流，看两者如何协作

最近这个例子非常典型。

共享 guidance 在哪里？

在 /home/water/.openclaw/workspace/AGENTS.md 里，已经明确写了：

  • sub-agent 需要 broader web search 时，优先 Tavily
  • 用 node skills/tavily-search/scripts/search.mjs "<query>"
  • deeper research 用 --deep
  • 对已选 URL，再配合 web_fetch

这定义的是整个 workspace 的推荐搜索范式。

个体化说明在哪里？

在 /home/water/.openclaw/agents/research/agent.json 与
/home/water/.openclaw/agents/bigcommontask/agent.json 里，又分别通过 notes 重申：

  • research：做 broader web discovery 时优先 Tavily，再 web_fetch
  • bigcommontask：需要外部研究时也优先 Tavily，再做 focused reading

这说明什么？

同一套 workspace 规则，被不同 agent 用各自方式继承和落实。

  • AGENTS.md 提供 shared convention
  • research/agent.json 把它落成 research 的默认研究动作
  • bigcommontask/agent.json 把它落成重任务执行链的一部分

而 /home/water/.openclaw/agents/writer/agent.json 没有强调 web research，恰恰说明 writer 的主责是写作，不是搜索发现。

七、给开发者的落地建议

如果你在维护自己的 OpenClaw 多代理体系，推荐这样设计：

  • 把 workspace 共识写进 AGENTS.md

    • 路由规则
    • 仓库结构
    • 校验命令
    • 通用工具使用约定

  • 把 agent 个性写进 agent.json

    • model
    • allowedTools
    • timeout
    • notes
    • capabilities / temperature

一句经验总结：

凡是“所有 agent 在这个工作区都该知道的”，放 AGENTS.md；凡是“只有这个 agent 自己需要携带的”，放 agent.json。

结语

理解 OpenClaw 里的 AGENTS.md 和 agent.json，本质上是在理解多代理系统的两层配置：

  • 环境层（workspace-level）
  • 角色层（agent-level）

/home/water/.openclaw/workspace/AGENTS.md 负责建立统一协作语境；
/home/water/.openclaw/agents/research/agent.json、/home/water/.openclaw/agents/writer/agent.json、/home/water/.openclaw/agents/bigcommontask/agent.json 负责定义各自的执行人格与能力边界。

前者让团队“不乱”，后者让成员“不混”。
只有这两层配合好，多 agent 系统才能既有统一规范，又保留专业分工。

avatar
文章
阅读
粉丝