下午茶,渍

Appearance

ADR-0003：采用 OpenClaw 作为 Agent 内核 ​

  • 状态：已采纳
  • 日期：2026-09-15
  • 决策者：毕设作者
  • 相关文档：docs/03-Agent层设计-OpenClaw二次开发.md、docs/adr/0004-security-plugin-layer-in-process.md

背景 ​

课题要求"基于开源模块化 Agent 二次开发"，需要一个满足以下条件的框架：

  1. 开源、可自托管、可读源码（毕设要能讲清楚内部机制）；
  2. 具备可插拔扩展机制，否则"安全管控插件层"无处挂载；
  3. 支持工具调用与 MCP 协议（网关的工具要能被调用）；
  4. 有会话与记忆管理能力（故障分析需要多轮上下文）；
  5. 社区活跃、文档完善、能持续跟进。

决策 ​

选用 OpenClaw 作为 Agent 内核，并在其上做二次开发。

选它的关键原因不是"它是最好的 Agent 框架"，而是它的扩展机制正好与课题需求对齐：

  • 插件系统：OpenClaw 原生插件以 openclaw.plugin.json 为清单，运行时模块在进程内加载；插件可以注册工具、Skill、渠道、模型提供商，并能通过 api.on(...) 注册类型化生命周期钩子（中间件、策略、消息改写、提示词塑形、工具控制）。
  • 钩子语义匹配：api.on(...) 的定位就是"中间件 / 策略 / 工具控制"，这正是安全管控插件层需要的拦截点。相比 api.registerHook(...) 的粗粒度事件，类型化钩子支持优先级、合并语义与阻止/取消行为——策略层需要"拒绝这次工具调用"的能力。
  • MCP 支持：OpenClaw 的运行时状态中已包含原生 MCP OAuth 令牌存储，说明其 MCP 客户端路径是一等公民。
  • 多 Agent 与沙箱：支持按 Agent 配置独立的沙箱模式与工具策略（agents.entries.*.sandbox、agents.entries.*.tools.allow/deny），可以让"运维分析 Agent"与"通用 Agent"使用不同的权限剖面。
  • 自带安全审计工具：openclaw security audit 会检查插件允许列表、工具影响面、Exec 审批策略、沙箱配置偏移等，可直接作为课题的对照基线。

关键约束（必须在设计中被正视） ​

  1. OpenClaw 的信任模型是"单用户个人助理"。官方文档明确说明：一个 Gateway 对应一个可信的操作员边界，OpenClaw 不是多租户安全边界，也不适用于互相敌对的多用户共享同一 Agent。 → 对本课题的含义：不能把"多用户隔离"寄希望于 OpenClaw 自身。系统的权限模型必须由 MCP 安全网关承载，OpenClaw 只负责 Agent 运行时。
  2. 插件与 Gateway 同进程运行，属于可信代码。官方明确要求"只从信任的来源安装插件"。 → 对本课题的含义：安全管控插件层是策略执行层，不是硬边界。真正的边界是独立进程、独立凭证的网关。这一区分写在 ADR-0004。
  3. Node 版本有硬要求：Node 24.15+（推荐）、或 Node 22 LTS ≥ 22.22.3、或 Node 25.9+。 → 对本课题的含义：NVM 选版本时必须核对，本机现存的 Node 22.22.2 不满足 22 LTS 分支的下限。

备选方案与拒绝理由 ​

方案为什么没选
自研极简 ReAct 循环（不依赖框架）最可控，但"基于开源模块化 Agent 二次开发"的课题要求落空，且会话管理、工具调度、上下文压缩都要自己实现，工作量与风险不可控。
LangChain / LlamaIndex生态大，但"插件层"概念不如 OpenClaw 的进程内插件 + 类型化钩子清晰，且工具控制钩子的拦截能力更弱，安全管控层不好挂。
Dify / Coze 类平台偏低代码平台，二次开发空间受限，且难以在答辩中展示"我改了框架的哪一层"。
Claude Agent SDK依赖单一模型厂商，且插件机制与 MCP 的衔接不如 OpenClaw 明确。

后果 ​

正面

  • 二次开发的着力点明确：实现一个 OpenClaw 原生插件（安全管控插件层）+ 两个 Skill（故障分析、知识库检索）。
  • 可以直接引用 OpenClaw 官方安全基线作为对照，答辩时可展示"框架自带审计 vs 本课题新增管控"的差异。
  • 插件的安装/启用/检查有成熟的 CLI 流程（openclaw plugins install --link ./packages/security-plugin、openclaw plugins inspect <id> --runtime --json），验证手段现成。

负面 / 代价

  • 受框架版本与插件 API 兼容性约束，需要声明 openclaw.compat.pluginApi 与 openclaw.install.minHostVersion。
  • 插件的类型化钩子清单需要按实际版本文档核实，不能凭猜测编码（本项目所有钩子名以官方文档为准，不确定的标注待验证）。
  • 引入了 OpenClaw 自身的攻击面（渠道、浏览器控制、Exec 等），必须在配置中显式收紧：gateway.bind: "loopback"、tools.profile 收窄、关闭不需要的渠道与工具。