OpenClaw（龙虾）技术解析 · 原理、架构与实战
这篇文章讲什么：OpenClaw 是什么、它内部怎么工作、一条消息从你按下发送到 Agent 执行完任务经历了什么、你能用它干什么、它的设计有哪些值得借鉴的工程思路。读完你能向别人讲清楚 OpenClaw 的原理，并判断它适不适合你的场景。
命名说明（外部读者必读）
- OpenClaw（🦞）= 本文主角，MIT 开源的个人 AI 助理 Gateway，社区俗称「龙虾」。
- LobsterAI / 有道龙虾 = 网易有道在 OpenClaw 之上做的桌面壳（Electron UI）+ Skill Store，是产品层，不替代 OpenClaw，通过 WebSocket RPC 调 Gateway。
- 本文「龙虾」一律指 OpenClaw 本体。
阅读约定 ：
LC= Life Cycle（生命周期），LC0--LC5 为六个阶段。时效性声明 ：AI 工具迭代极快，本文反映 2026-07 写作时点 的产品状态，仅供参考 。文末「示意」标记的数字（Stars 数、73%、CVE 计数等）为举例口径，非官方常量；机制描述以文末 L1/L2 官方来源为准，使用前请务必核对官方最新文档。
TL;DR · 30 秒速览
- 是什么：跑在你自己机器上的个人 AI 助理 Gateway（Node.js / MIT），把 IM 渠道的消息接给内嵌 Agent 运行时执行工具调用，数据不出本地。
- 核心原理：Gateway 常驻进程当唯一中控 → 收 IM 消息 → 加载工作区 + Skills → 跑 ReAct 循环（LLM 推理 ↔ 工具调用）→ 结果回 IM。全程会话以 JSONL 落盘。
- 不是什么：不是模型、不是 SaaS、不是企业级平台。
- 能干啥：IM 个人助理、异步任务监控、多 Agent 协作、跨渠道统一入口、浏览器自动化、个人知识库 等（见 LC3）。
- 能上生产吗：原样不可；但 8 个设计思路可被企业借鉴（见「架构设计思路」）。
LC0 · 认知 ------ 是什么、优劣势、生态位
0.1 一句话定义
OpenClaw （🦞）是一个 自托管的个人 AI 助手 Gateway 网关，MIT 许可，社区驱动。它在你自己的机器（或 VPS）上运行一个常驻进程，把你常用的 IM 聊天应用接上 AI Agent，让你在任何地方发消息就能遥控 AI 干活。
| 维度 | OpenClaw |
|---|---|
| 本质 | 自托管 Gateway 进程（不是模型、不是 chatbot、不是 SaaS） |
| 安装 | npm install -g openclaw@latest |
| 运行时 | Node 24（推荐）/ Node 22 LTS |
| 协议 | WebSocket + JSON 帧 |
| 许可证 | MIT |
| 代码仓库 | github.com/openclaw/openclaw |
| 官方文档 | docs.openclaw.ai/zh-CN |
| GitHub Stars | 约 30 万 ⭐（社区口径·示意） |
一句话口播：「OpenClaw 是跑在你机器上的 Gateway，把 IM 消息交给 AI Agent 执行工具调用，数据不出你的硬盘。」
0.2 优劣势总结
| 维度 | 优势 ✅ | 劣势 ❌ |
|---|---|---|
| 数据主权 | 自托管，数据不出本地硬盘 | 用户自负安全（API Key 泄露风险） |
| 渠道 | 多 IM 原生支持 + 插件扩展 | 配置繁琐，每个渠道需独立设置 |
| Skills | AgentSkills 开放规范 + ClawHub 生态 | 第三方 Skills 不受信；Token 开销（每个 ~24 token） |
| 安装 | 一条 npm 命令即可 | 约 73% 新用户首次安装遇阻塞报错（社区调研·示意） |
| 卸载 | npm uninstall 删包 | 5 处残留（配置/守护进程/SHELL PATH/旧版遗留/Homebrew） |
| 环境 | --- | Node 22+ 强制；Windows 必须 WSL2；需 C++ 编译工具链 |
| 上生产 | 架构思路可借鉴 | 原样不可------缺 Registry、Eval Gate、审计、SLA、多租户 |
| 成本 | 用户自带 API Key，无服务费 | 无预算控制，可爆 token；超长循环无硬上限 |
| 安全 | 设备配对 + Challenge 签名 + 沙箱 | Skill 自建议非自进化（Workshop 需人工审批） |
| 生态 | MIT 开源 + LobsterAI 国内壳 | Windows 原生不支持；国内网络访问 npm 慢 |
0.3 生态位对照
| 产品 | 主场景 | 运行位置 |
|---|---|---|
| Cursor / Claude Code | 仓库内编码 | IDE / CLI |
| OpenClaw / Hermes | 生活+办公自动化、IM 遥控 | 本机 / VPS / 容器 |
| 企业 Buy/客服 Agent | 交易/合规域 | 集群 + 审计 |
关键区别：Cursor/Claude Code 解决「改代码」；OpenClaw 解决「在 IM 里派活、AI 在我离开时异步做」；企业 Agent 解决「可审计、可回滚、多租户的业务域」。
LC1 · 安装 ------ 上手、配置、常见坑
1.1 最小可运行安装
bash
# 1. 安装（需 Node 24 或 22 LTS 22.19+）
npm install -g openclaw@latest
# 2. 新手引导 + 安装守护进程
openclaw onboard --install-daemon
# 3. 启动 Web 控制台（http://127.0.0.1:18789）
openclaw dashboard
# 4. 添加 Telegram 渠道（最快上手）
openclaw channels add telegram
# 按提示输入 Bot Token1.2 配置最小生产安全
json5
// ~/.openclaw/openclaw.json
{
channels: {
whatsapp: { allowFrom: ["+8613800138000"] },
telegram: { allowFrom: ["@myusername"] },
},
messages: {
groupChat: { mentionPatterns: ["@openclaw", "@龙虾"] },
},
gateway: {
auth: { mode: "token" }, // 不要用 "none"
},
security: {
installPolicy: "~/.openclaw/security/audit-skill.sh",
},
skills: {
load: { watch: true },
},
}1.3 为什么难安装（6 大根因）
社区调研口径（示意）：约 73% 的 OpenClaw 新用户首次安装遇到阻塞性报错，其中 Node.js 版本不匹配一项占约 60%。
| # | 根因 | 说明 | 典型后果 |
|---|---|---|---|
| 1 | 三次改名 | Moltbot → Clawdbot → OpenClaw（2025.11 至今） | 网上教程命令/路径过期 |
| 2 | 版本迭代极快 | 几乎每周发版；配置键名频繁重命名 | 升级后旧配置静默失效 |
| 3 | 环境要求高 | Node 22+ 强制；Windows 必须 WSL2；需 C++ 编译工具链 | Node < 22 语法错误；缺 build-essential → node-gyp rebuild failed |
| 4 | npm 生态摩擦 | 全局安装权限（EACCES）、国内网络慢（ETIMEDOUT）、缓存损坏 | 三条老问题叠加 |
| 5 | Gateway 前置条件复杂 | 必须设 gateway.mode=local；绑非本机 IP 强制认证；初始化 ~40s |
"Gateway start blocked" / 提前访问以为挂了 |
| 6 | CVE 驱动强制升级 | 示意：2026.2-3 月 8 个 CVE（最严重 CVSS 8.8：跨站 WebSocket 劫持） | 不升级有风险，升级可能坏配置 |
1.4 部署模式
| 模式 | 命令 | 适用 |
|---|---|---|
| 本地开发 | npm install -g openclaw@latest + openclaw onboard --install-daemon |
个人桌面 |
| VPS/服务器 | 同上 + Tailscale / SSH 隧道远程访问 | 24/7 在线 |
| Docker | docker-compose.yml 提供 |
容器化部署 |
| WSL | 社区探索 | Windows 用户 |
OpenClaw 默认绑定
127.0.0.1:18789，远程访问需 TLS + 认证。gateway.auth.mode: "none"只在受信任入口使用，绝不在公开网络启用。
LC2 · 架构与原理 ------ 它内部怎么工作
这是全文的核心。按「一条消息的完整旅程」组织：先看端到端工作流（宏观），再拆 Gateway 内部组件（中观），再钻进 Agent 循环、Skills 加载、MCP、通信信任（微观）。
2.1 端到端工作流：一条消息如何变成一次 Agent 执行
这是理解 OpenClaw 最重要的一张图。假设你在 WhatsApp 发了一句「帮我查今天 HN 头条并总结」：
#mermaid-svg-7jUp9PYiaS9iNAOb{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-7jUp9PYiaS9iNAOb .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-7jUp9PYiaS9iNAOb .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-7jUp9PYiaS9iNAOb .error-icon{fill:#552222;}#mermaid-svg-7jUp9PYiaS9iNAOb .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-7jUp9PYiaS9iNAOb .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-7jUp9PYiaS9iNAOb .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-7jUp9PYiaS9iNAOb .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-7jUp9PYiaS9iNAOb .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-7jUp9PYiaS9iNAOb .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-7jUp9PYiaS9iNAOb .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-7jUp9PYiaS9iNAOb .marker{fill:#333333;stroke:#333333;}#mermaid-svg-7jUp9PYiaS9iNAOb .marker.cross{stroke:#333333;}#mermaid-svg-7jUp9PYiaS9iNAOb svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-7jUp9PYiaS9iNAOb p{margin:0;}#mermaid-svg-7jUp9PYiaS9iNAOb .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-7jUp9PYiaS9iNAOb .cluster-label text{fill:#333;}#mermaid-svg-7jUp9PYiaS9iNAOb .cluster-label span{color:#333;}#mermaid-svg-7jUp9PYiaS9iNAOb .cluster-label span p{background-color:transparent;}#mermaid-svg-7jUp9PYiaS9iNAOb .label text,#mermaid-svg-7jUp9PYiaS9iNAOb span{fill:#333;color:#333;}#mermaid-svg-7jUp9PYiaS9iNAOb .node rect,#mermaid-svg-7jUp9PYiaS9iNAOb .node circle,#mermaid-svg-7jUp9PYiaS9iNAOb .node ellipse,#mermaid-svg-7jUp9PYiaS9iNAOb .node polygon,#mermaid-svg-7jUp9PYiaS9iNAOb .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-7jUp9PYiaS9iNAOb .rough-node .label text,#mermaid-svg-7jUp9PYiaS9iNAOb .node .label text,#mermaid-svg-7jUp9PYiaS9iNAOb .image-shape .label,#mermaid-svg-7jUp9PYiaS9iNAOb .icon-shape .label{text-anchor:middle;}#mermaid-svg-7jUp9PYiaS9iNAOb .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-7jUp9PYiaS9iNAOb .rough-node .label,#mermaid-svg-7jUp9PYiaS9iNAOb .node .label,#mermaid-svg-7jUp9PYiaS9iNAOb .image-shape .label,#mermaid-svg-7jUp9PYiaS9iNAOb .icon-shape .label{text-align:center;}#mermaid-svg-7jUp9PYiaS9iNAOb .node.clickable{cursor:pointer;}#mermaid-svg-7jUp9PYiaS9iNAOb .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-7jUp9PYiaS9iNAOb .arrowheadPath{fill:#333333;}#mermaid-svg-7jUp9PYiaS9iNAOb .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-7jUp9PYiaS9iNAOb .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-7jUp9PYiaS9iNAOb .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-7jUp9PYiaS9iNAOb .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-7jUp9PYiaS9iNAOb .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-7jUp9PYiaS9iNAOb .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-7jUp9PYiaS9iNAOb .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-7jUp9PYiaS9iNAOb .cluster text{fill:#333;}#mermaid-svg-7jUp9PYiaS9iNAOb .cluster span{color:#333;}#mermaid-svg-7jUp9PYiaS9iNAOb div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-7jUp9PYiaS9iNAOb .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-7jUp9PYiaS9iNAOb rect.text{fill:none;stroke-width:0;}#mermaid-svg-7jUp9PYiaS9iNAOb .icon-shape,#mermaid-svg-7jUp9PYiaS9iNAOb .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-7jUp9PYiaS9iNAOb .icon-shape p,#mermaid-svg-7jUp9PYiaS9iNAOb .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-7jUp9PYiaS9iNAOb .icon-shape .label rect,#mermaid-svg-7jUp9PYiaS9iNAOb .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-7jUp9PYiaS9iNAOb .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-7jUp9PYiaS9iNAOb .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-7jUp9PYiaS9iNAOb :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 1 消息
2 标准化
3 按 Agent ID
- 发送者
4 读 JSONL
历史帧
5 加载工作区
注入引导文件
6 门控过滤
-
快照
7 组装系统提示词 -
工具 schema
8 调 LLM API
9 返回工具调用
或最终回复
10 要调工具?
是
11 结果回 LLM
12 循环直到
无工具调用
否
13 回 WhatsApp
用户在
WhatsApp 发消息
渠道适配器
(Baileys/TG Bot)
消息路由器
会话管理器
(找/建 SessionId)
Agent Runtime
(嵌入式循环)
Skills 加载器
符合条件的
Skills 列表
Provider 适配器
LLM
(35+ 模型)
工具执行器
read/exec/edit
MCP/浏览器
渠道投递器
逐步解释：
- 消息接入：你在 WhatsApp 发的消息，由对应的渠道适配器（如 Baileys 库）接收。每个 IM 平台一个适配器，把各家协议差异屏蔽掉，输出统一的标准化消息。
- 路由：消息路由器根据目标 Agent ID + 发送者身份，决定这条消息归哪个 Agent 处理。
- 会话定位 ：会话管理器找到（或新建）
SessionId。直接聊天合并到main会话；群聊各隔离。会话历史以 JSONL 存在~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl。 - 历史加载：Agent Runtime 读出该会话的历史帧，作为上下文。
- 工作区加载 ：加载该 Agent 的工作区目录，把
AGENTS.md/SOUL.md/USER.md等引导文件读出来------这些就是 Agent 的"人格配置"。 - Skills 过滤 ：Skills 加载器扫描 6 级目录，按门控字段（
os/requires.bins/requires.env/requires.config）过滤出当前可用的 Skills，生成快照。 - 提示词组装：把引导文件 + Skills 描述 + 工具 schema 拼成系统提示词。
- 模型调用 ：Provider 适配器按配置（如
anthropic/claude-sonnet-4）调用 LLM。 - LLM 返回：返回工具调用请求，或直接返回最终文本回复。
- 工具判定：如果 LLM 请求调用工具，进工具执行器；否则跳到投递。
- 工具执行 ：执行
read/exec/edit/MCP 工具/浏览器等，结果回 Agent Runtime。 - 循环：工具结果作为新的上下文，再次调 LLM，直到 LLM 不再请求工具------这就是 ReAct 循环（见 §2.3）。
- 投递：最终回复经渠道投递器发回 WhatsApp。
一句话总结：OpenClaw = IM 消息接入 → 会话定位 → Skills/工具装载 → ReAct 循环（LLM ↔ 工具）→ 结果回 IM。Gateway 是全程唯一中控。
2.2 Gateway 内部架构：单中控的组件分解
Gateway 是一个常驻 Node.js 进程（默认监听 127.0.0.1:18789），它是每台主机上唯一打开 IM 会话、管理 Agent 会话、路由消息的地方------即"唯一可信源"。
#mermaid-svg-zN8OVLPDHsPQfrjn{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-zN8OVLPDHsPQfrjn .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-zN8OVLPDHsPQfrjn .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-zN8OVLPDHsPQfrjn .error-icon{fill:#552222;}#mermaid-svg-zN8OVLPDHsPQfrjn .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-zN8OVLPDHsPQfrjn .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-zN8OVLPDHsPQfrjn .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-zN8OVLPDHsPQfrjn .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-zN8OVLPDHsPQfrjn .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-zN8OVLPDHsPQfrjn .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-zN8OVLPDHsPQfrjn .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-zN8OVLPDHsPQfrjn .marker{fill:#333333;stroke:#333333;}#mermaid-svg-zN8OVLPDHsPQfrjn .marker.cross{stroke:#333333;}#mermaid-svg-zN8OVLPDHsPQfrjn svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-zN8OVLPDHsPQfrjn p{margin:0;}#mermaid-svg-zN8OVLPDHsPQfrjn .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-zN8OVLPDHsPQfrjn .cluster-label text{fill:#333;}#mermaid-svg-zN8OVLPDHsPQfrjn .cluster-label span{color:#333;}#mermaid-svg-zN8OVLPDHsPQfrjn .cluster-label span p{background-color:transparent;}#mermaid-svg-zN8OVLPDHsPQfrjn .label text,#mermaid-svg-zN8OVLPDHsPQfrjn span{fill:#333;color:#333;}#mermaid-svg-zN8OVLPDHsPQfrjn .node rect,#mermaid-svg-zN8OVLPDHsPQfrjn .node circle,#mermaid-svg-zN8OVLPDHsPQfrjn .node ellipse,#mermaid-svg-zN8OVLPDHsPQfrjn .node polygon,#mermaid-svg-zN8OVLPDHsPQfrjn .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-zN8OVLPDHsPQfrjn .rough-node .label text,#mermaid-svg-zN8OVLPDHsPQfrjn .node .label text,#mermaid-svg-zN8OVLPDHsPQfrjn .image-shape .label,#mermaid-svg-zN8OVLPDHsPQfrjn .icon-shape .label{text-anchor:middle;}#mermaid-svg-zN8OVLPDHsPQfrjn .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-zN8OVLPDHsPQfrjn .rough-node .label,#mermaid-svg-zN8OVLPDHsPQfrjn .node .label,#mermaid-svg-zN8OVLPDHsPQfrjn .image-shape .label,#mermaid-svg-zN8OVLPDHsPQfrjn .icon-shape .label{text-align:center;}#mermaid-svg-zN8OVLPDHsPQfrjn .node.clickable{cursor:pointer;}#mermaid-svg-zN8OVLPDHsPQfrjn .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-zN8OVLPDHsPQfrjn .arrowheadPath{fill:#333333;}#mermaid-svg-zN8OVLPDHsPQfrjn .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-zN8OVLPDHsPQfrjn .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-zN8OVLPDHsPQfrjn .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-zN8OVLPDHsPQfrjn .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-zN8OVLPDHsPQfrjn .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-zN8OVLPDHsPQfrjn .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-zN8OVLPDHsPQfrjn .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-zN8OVLPDHsPQfrjn .cluster text{fill:#333;}#mermaid-svg-zN8OVLPDHsPQfrjn .cluster span{color:#333;}#mermaid-svg-zN8OVLPDHsPQfrjn div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-zN8OVLPDHsPQfrjn .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-zN8OVLPDHsPQfrjn rect.text{fill:none;stroke-width:0;}#mermaid-svg-zN8OVLPDHsPQfrjn .icon-shape,#mermaid-svg-zN8OVLPDHsPQfrjn .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-zN8OVLPDHsPQfrjn .icon-shape p,#mermaid-svg-zN8OVLPDHsPQfrjn .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-zN8OVLPDHsPQfrjn .icon-shape .label rect,#mermaid-svg-zN8OVLPDHsPQfrjn .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-zN8OVLPDHsPQfrjn .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-zN8OVLPDHsPQfrjn .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-zN8OVLPDHsPQfrjn :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 外部
OpenClaw Gateway 进程 (默认 :18789)
WS
WS
HTTPS
JSON-RPC
触发
WS Hub
(接客户端/节点/渠道)
消息路由器
会话管理器
(JSONL 存储)
Skills 加载器
(6 级优先级 + 门控)
Agent Runtime
(嵌入式循环)
Provider 适配器
(35+ 模型)
工具执行器
(沙箱隔离)
Cron/Heartbeat
调度器
MCP 事件处理器
IM 渠道
客户端/节点
(Web/CLI/App)
LLM Provider
工具/MCP Server
| 组件 | 职责 | 关键点 |
|---|---|---|
| WS Hub | 所有 WebSocket 连接的入口（客户端、节点、渠道） | 渠道适配器也走 WS 接入，统一收口 |
| 消息路由器 | 决定消息归哪个 Agent、哪个会话 | 按 Agent ID + 发送者分流 |
| 会话管理器 | 会话的创建、读取、追加（JSONL） | 每会话一个 .jsonl 文件，每行一帧，追加写、可重放 |
| Skills 加载器 | 扫描 + 门控 + 快照 Skills | 6 级优先级，会话级快照避免运行中漂移 |
| Agent Runtime | 嵌入式 Agent 循环（核心） | 不委托外部 harness，自己跑 ReAct |
| Provider 适配器 | 调用各家 LLM API | 35+ Provider，支持自托管（vLLM/Ollama） |
| 工具执行器 | 执行工具调用 | 沙箱隔离不受信代码；密钥不注入沙箱 |
| Cron/Heartbeat | 定时任务、心跳保活 | Cron 触发 Agent；Heartbeat 维持 IM 会话 |
| MCP 事件处理器 | 管理 MCP Server 通信 | MCP Server 独立进程，JSON-RPC over stdio/SSE |
为什么是单中控：IM 会话（如 WhatsApp 的 Baileys 会话）有状态------同一账号不能在两个进程同时登录，否则互相踢下线。所以 Gateway 必须是单点持有 IM 会话。所有客户端（Web/CLI/App）和远端节点都通过 WS 连到这个唯一 Gateway，而不是各自直连 IM。
2.3 Agent 循环原理：ReAct 在 OpenClaw 里怎么转
OpenClaw 不把 Agent 调用委托给外部 harness（如 Claude Code CLI），而是内嵌自己的 Agent 循环：模型发现、工具接线、提示词组装、会话管理、渠道投递全部在一个集成的运行时完成。
#mermaid-svg-YcRqJ20Dv5lNMcHs{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-YcRqJ20Dv5lNMcHs .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-YcRqJ20Dv5lNMcHs .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-YcRqJ20Dv5lNMcHs .error-icon{fill:#552222;}#mermaid-svg-YcRqJ20Dv5lNMcHs .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-YcRqJ20Dv5lNMcHs .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-YcRqJ20Dv5lNMcHs .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-YcRqJ20Dv5lNMcHs .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-YcRqJ20Dv5lNMcHs .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-YcRqJ20Dv5lNMcHs .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-YcRqJ20Dv5lNMcHs .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-YcRqJ20Dv5lNMcHs .marker{fill:#333333;stroke:#333333;}#mermaid-svg-YcRqJ20Dv5lNMcHs .marker.cross{stroke:#333333;}#mermaid-svg-YcRqJ20Dv5lNMcHs svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-YcRqJ20Dv5lNMcHs p{margin:0;}#mermaid-svg-YcRqJ20Dv5lNMcHs .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-YcRqJ20Dv5lNMcHs .cluster-label text{fill:#333;}#mermaid-svg-YcRqJ20Dv5lNMcHs .cluster-label span{color:#333;}#mermaid-svg-YcRqJ20Dv5lNMcHs .cluster-label span p{background-color:transparent;}#mermaid-svg-YcRqJ20Dv5lNMcHs .label text,#mermaid-svg-YcRqJ20Dv5lNMcHs span{fill:#333;color:#333;}#mermaid-svg-YcRqJ20Dv5lNMcHs .node rect,#mermaid-svg-YcRqJ20Dv5lNMcHs .node circle,#mermaid-svg-YcRqJ20Dv5lNMcHs .node ellipse,#mermaid-svg-YcRqJ20Dv5lNMcHs .node polygon,#mermaid-svg-YcRqJ20Dv5lNMcHs .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-YcRqJ20Dv5lNMcHs .rough-node .label text,#mermaid-svg-YcRqJ20Dv5lNMcHs .node .label text,#mermaid-svg-YcRqJ20Dv5lNMcHs .image-shape .label,#mermaid-svg-YcRqJ20Dv5lNMcHs .icon-shape .label{text-anchor:middle;}#mermaid-svg-YcRqJ20Dv5lNMcHs .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-YcRqJ20Dv5lNMcHs .rough-node .label,#mermaid-svg-YcRqJ20Dv5lNMcHs .node .label,#mermaid-svg-YcRqJ20Dv5lNMcHs .image-shape .label,#mermaid-svg-YcRqJ20Dv5lNMcHs .icon-shape .label{text-align:center;}#mermaid-svg-YcRqJ20Dv5lNMcHs .node.clickable{cursor:pointer;}#mermaid-svg-YcRqJ20Dv5lNMcHs .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-YcRqJ20Dv5lNMcHs .arrowheadPath{fill:#333333;}#mermaid-svg-YcRqJ20Dv5lNMcHs .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-YcRqJ20Dv5lNMcHs .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-YcRqJ20Dv5lNMcHs .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-YcRqJ20Dv5lNMcHs .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-YcRqJ20Dv5lNMcHs .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-YcRqJ20Dv5lNMcHs .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-YcRqJ20Dv5lNMcHs .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-YcRqJ20Dv5lNMcHs .cluster text{fill:#333;}#mermaid-svg-YcRqJ20Dv5lNMcHs .cluster span{color:#333;}#mermaid-svg-YcRqJ20Dv5lNMcHs div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-YcRqJ20Dv5lNMcHs .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-YcRqJ20Dv5lNMcHs rect.text{fill:none;stroke-width:0;}#mermaid-svg-YcRqJ20Dv5lNMcHs .icon-shape,#mermaid-svg-YcRqJ20Dv5lNMcHs .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-YcRqJ20Dv5lNMcHs .icon-shape p,#mermaid-svg-YcRqJ20Dv5lNMcHs .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-YcRqJ20Dv5lNMcHs .icon-shape .label rect,#mermaid-svg-YcRqJ20Dv5lNMcHs .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-YcRqJ20Dv5lNMcHs .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-YcRqJ20Dv5lNMcHs .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-YcRqJ20Dv5lNMcHs :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 工具调用
最终文本回复
收到用户消息
组装系统提示词
(引导文件 + Skills 快照 + 工具 schema)
调 LLM
LLM 返回
工具执行器
(read/exec/edit/MCP/浏览器)
工具结果
追加到会话 JSONL
(作为新的 tool 帧)
生成完成
投递到渠道
会话存档 JSONL
这是 ReAct（Reason + Act）循环的实现：
- Reason（推理）：LLM 基于系统提示词 + 历史 + 用户消息，决定下一步是调工具还是直接回复。
- Act（行动） ：如果要调工具，工具执行器执行，结果追加到会话 JSONL 作为新的
tool帧。 - 循环：工具结果作为新上下文，再次调 LLM，直到 LLM 不再请求工具调用------此时它返回最终文本回复。
- 终止条件：LLM 主动放弃工具调用，或达到内置迭代上限。
为什么用 JSONL 存会话 ：追加写性能好（不重写整个文件）、可重放（调试时逐帧回放 Agent 决策）、易截断（超长上下文时裁剪早期帧）。每帧是一个 JSON 对象，包含 role（user/assistant/tool）、content、tool_calls 等。
会话隔离规则 ：直接聊天合并到共享的 main 会话；群聊各自隔离（一个群一个 SessionId）。这让 Agent 在不同群里有独立记忆。
2.4 Skills 系统：能力如何被声明、加载、门控
Skill = SKILL.md 文件 （YAML frontmatter + Markdown 正文），教 Agent 何时如何用工具。遵循 AgentSkills 开放规范。OpenClaw 的 Skills 不是硬编码在代码里，而是用文档声明------这是它最值得借鉴的设计之一。
加载流程：
#mermaid-svg-2kvydk6Ei5oVxhKC{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-2kvydk6Ei5oVxhKC .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-2kvydk6Ei5oVxhKC .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-2kvydk6Ei5oVxhKC .error-icon{fill:#552222;}#mermaid-svg-2kvydk6Ei5oVxhKC .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-2kvydk6Ei5oVxhKC .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-2kvydk6Ei5oVxhKC .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-2kvydk6Ei5oVxhKC .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-2kvydk6Ei5oVxhKC .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-2kvydk6Ei5oVxhKC .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-2kvydk6Ei5oVxhKC .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-2kvydk6Ei5oVxhKC .marker{fill:#333333;stroke:#333333;}#mermaid-svg-2kvydk6Ei5oVxhKC .marker.cross{stroke:#333333;}#mermaid-svg-2kvydk6Ei5oVxhKC svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-2kvydk6Ei5oVxhKC p{margin:0;}#mermaid-svg-2kvydk6Ei5oVxhKC .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-2kvydk6Ei5oVxhKC .cluster-label text{fill:#333;}#mermaid-svg-2kvydk6Ei5oVxhKC .cluster-label span{color:#333;}#mermaid-svg-2kvydk6Ei5oVxhKC .cluster-label span p{background-color:transparent;}#mermaid-svg-2kvydk6Ei5oVxhKC .label text,#mermaid-svg-2kvydk6Ei5oVxhKC span{fill:#333;color:#333;}#mermaid-svg-2kvydk6Ei5oVxhKC .node rect,#mermaid-svg-2kvydk6Ei5oVxhKC .node circle,#mermaid-svg-2kvydk6Ei5oVxhKC .node ellipse,#mermaid-svg-2kvydk6Ei5oVxhKC .node polygon,#mermaid-svg-2kvydk6Ei5oVxhKC .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-2kvydk6Ei5oVxhKC .rough-node .label text,#mermaid-svg-2kvydk6Ei5oVxhKC .node .label text,#mermaid-svg-2kvydk6Ei5oVxhKC .image-shape .label,#mermaid-svg-2kvydk6Ei5oVxhKC .icon-shape .label{text-anchor:middle;}#mermaid-svg-2kvydk6Ei5oVxhKC .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-2kvydk6Ei5oVxhKC .rough-node .label,#mermaid-svg-2kvydk6Ei5oVxhKC .node .label,#mermaid-svg-2kvydk6Ei5oVxhKC .image-shape .label,#mermaid-svg-2kvydk6Ei5oVxhKC .icon-shape .label{text-align:center;}#mermaid-svg-2kvydk6Ei5oVxhKC .node.clickable{cursor:pointer;}#mermaid-svg-2kvydk6Ei5oVxhKC .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-2kvydk6Ei5oVxhKC .arrowheadPath{fill:#333333;}#mermaid-svg-2kvydk6Ei5oVxhKC .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-2kvydk6Ei5oVxhKC .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-2kvydk6Ei5oVxhKC .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-2kvydk6Ei5oVxhKC .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-2kvydk6Ei5oVxhKC .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-2kvydk6Ei5oVxhKC .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-2kvydk6Ei5oVxhKC .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-2kvydk6Ei5oVxhKC .cluster text{fill:#333;}#mermaid-svg-2kvydk6Ei5oVxhKC .cluster span{color:#333;}#mermaid-svg-2kvydk6Ei5oVxhKC div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-2kvydk6Ei5oVxhKC .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-2kvydk6Ei5oVxhKC rect.text{fill:none;stroke-width:0;}#mermaid-svg-2kvydk6Ei5oVxhKC .icon-shape,#mermaid-svg-2kvydk6Ei5oVxhKC .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-2kvydk6Ei5oVxhKC .icon-shape p,#mermaid-svg-2kvydk6Ei5oVxhKC .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-2kvydk6Ei5oVxhKC .icon-shape .label rect,#mermaid-svg-2kvydk6Ei5oVxhKC .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-2kvydk6Ei5oVxhKC .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-2kvydk6Ei5oVxhKC .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-2kvydk6Ei5oVxhKC :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} os 不匹配
requires.bins 缺失
requires.env 缺失
requires.config 为假
全通过
变更/新节点
扫描 6 级目录
(工作区→项目→个人→托管→内置→插件)
收集所有 SKILL.md
同名高优先级胜出
逐个门控检查
隐藏
隐藏
隐藏
隐藏
进入快照
会话开始时
注入系统提示词
监听文件变更
6 级加载优先级（高 → 低）：工作区 Skills → 项目 Agent Skills → 个人 Agent Skills → 托管 Skills → 内置 Skills → 额外目录 + 插件 Skills。同名时高优先级胜出------这让用户能用工作区 Skills 覆盖默认行为。
门控字段 （metadata.openclaw 下）------决定一个 Skill 在当前环境是否可见：
| 字段 | 行为 | 例子 |
|---|---|---|
always |
true 时跳过所有门控 |
强制加载 |
os |
平台过滤 | [darwin, linux] |
requires.bins |
每个二进制必须存在 | [uv, ffmpeg] |
requires.anyBins |
至少一个存在 | [python3, python] |
requires.env |
每个环境变量必须存在 | [GEMINI_API_KEY] |
requires.config |
每个 openclaw.json 路径为真值 | [browser.enabled] |
门控的意义 ：一个需要 ffmpeg 的视频处理 Skill，在没装 ffmpeg 的机器上自动隐藏，避免 Agent 误调用导致失败。这是"声明式能力管理"------Skill 自描述它的依赖，运行时自动过滤。
快照机制 ：会话开始时对符合条件的 Skills 做快照，会话期间用这份快照。文件变更或新远端节点连接时刷新。为什么快照：避免长会话中途 Skills 集合变化导致 Agent 行为漂移。
Skill Workshop ：Agent 不能直接写 SKILL.md------它起草提案 ，用户审查批准后才写入（openclaw skills workshop list/inspect/apply）。比 Hermes 的"任务后自动写"多一道人工审批，更接近企业的 PR 流程。
最小 Skill 示例：
markdown
---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
metadata:
{
"openclaw":
{
"requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
"primaryEnv": "GEMINI_API_KEY",
},
}
---
When the user asks to generate an image, use the `image_generate` tool...ClawHub ：clawhub.ai------公共 Skills 注册表，openclaw skills install @owner/<slug> 安装。官方明确警告："将第三方 Skills 视为不受信任的代码"------所以有 security.installPolicy 在安装前跑本地策略检查。
Token 影响：每个 Skill ~24 token 基础开销（描述进系统提示词）。Skills 太多会吃掉上下文预算，所以门控不只是功能过滤，也是 token 成本控制。
2.5 MCP 集成：外部工具如何接入
MCP（Model Context Protocol）让工具实现与 Agent 解耦------工具可以是任何语言写的独立进程，只要实现 MCP 协议。
#mermaid-svg-NFcE56CYjFmYOURs{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-NFcE56CYjFmYOURs .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-NFcE56CYjFmYOURs .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-NFcE56CYjFmYOURs .error-icon{fill:#552222;}#mermaid-svg-NFcE56CYjFmYOURs .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-NFcE56CYjFmYOURs .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-NFcE56CYjFmYOURs .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-NFcE56CYjFmYOURs .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-NFcE56CYjFmYOURs .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-NFcE56CYjFmYOURs .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-NFcE56CYjFmYOURs .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-NFcE56CYjFmYOURs .marker{fill:#333333;stroke:#333333;}#mermaid-svg-NFcE56CYjFmYOURs .marker.cross{stroke:#333333;}#mermaid-svg-NFcE56CYjFmYOURs svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-NFcE56CYjFmYOURs p{margin:0;}#mermaid-svg-NFcE56CYjFmYOURs .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-NFcE56CYjFmYOURs .cluster-label text{fill:#333;}#mermaid-svg-NFcE56CYjFmYOURs .cluster-label span{color:#333;}#mermaid-svg-NFcE56CYjFmYOURs .cluster-label span p{background-color:transparent;}#mermaid-svg-NFcE56CYjFmYOURs .label text,#mermaid-svg-NFcE56CYjFmYOURs span{fill:#333;color:#333;}#mermaid-svg-NFcE56CYjFmYOURs .node rect,#mermaid-svg-NFcE56CYjFmYOURs .node circle,#mermaid-svg-NFcE56CYjFmYOURs .node ellipse,#mermaid-svg-NFcE56CYjFmYOURs .node polygon,#mermaid-svg-NFcE56CYjFmYOURs .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-NFcE56CYjFmYOURs .rough-node .label text,#mermaid-svg-NFcE56CYjFmYOURs .node .label text,#mermaid-svg-NFcE56CYjFmYOURs .image-shape .label,#mermaid-svg-NFcE56CYjFmYOURs .icon-shape .label{text-anchor:middle;}#mermaid-svg-NFcE56CYjFmYOURs .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-NFcE56CYjFmYOURs .rough-node .label,#mermaid-svg-NFcE56CYjFmYOURs .node .label,#mermaid-svg-NFcE56CYjFmYOURs .image-shape .label,#mermaid-svg-NFcE56CYjFmYOURs .icon-shape .label{text-align:center;}#mermaid-svg-NFcE56CYjFmYOURs .node.clickable{cursor:pointer;}#mermaid-svg-NFcE56CYjFmYOURs .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-NFcE56CYjFmYOURs .arrowheadPath{fill:#333333;}#mermaid-svg-NFcE56CYjFmYOURs .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-NFcE56CYjFmYOURs .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-NFcE56CYjFmYOURs .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-NFcE56CYjFmYOURs .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-NFcE56CYjFmYOURs .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-NFcE56CYjFmYOURs .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-NFcE56CYjFmYOURs .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-NFcE56CYjFmYOURs .cluster text{fill:#333;}#mermaid-svg-NFcE56CYjFmYOURs .cluster span{color:#333;}#mermaid-svg-NFcE56CYjFmYOURs div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-NFcE56CYjFmYOURs .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-NFcE56CYjFmYOURs rect.text{fill:none;stroke-width:0;}#mermaid-svg-NFcE56CYjFmYOURs .icon-shape,#mermaid-svg-NFcE56CYjFmYOURs .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-NFcE56CYjFmYOURs .icon-shape p,#mermaid-svg-NFcE56CYjFmYOURs .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-NFcE56CYjFmYOURs .icon-shape .label rect,#mermaid-svg-NFcE56CYjFmYOURs .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-NFcE56CYjFmYOURs .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-NFcE56CYjFmYOURs .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-NFcE56CYjFmYOURs :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 工具调用
JSON-RPC
over stdio/SSE
调用
结果
JSON-RPC 响应
结果
Agent Runtime
Gateway MCP
事件处理器
MCP Server 进程
(独立)
外部工具
(数据库/API/文件系统)
关键设计：
- MCP Server 是独立进程，不是 Gateway 的插件。Gateway 通过标准 JSON-RPC（stdio 或 SSE）与之通信。
- 解耦收益：工具可用 Python/Go/任何语言写；工具崩溃不影响 Gateway；工具可独立版本化。
- 与 Skills 的分工 ：Skills 是流程知识 （Markdown 指令，告诉 Agent 何时用某个工具）；MCP 是工具实现（实际执行代码）。一个 Skill 可以引导 Agent 调用某个 MCP 工具。
- LobsterAI 增强：在 LobsterAI 中，Skill Store 的 Skills 可通过 MCP 一键对接外部工具------把"MCP 配置"产品化成图形操作。
口播：「Skills 告诉 Agent『什么时候、怎么用』；MCP 提供『工具本身』。前者是知识，后者是能力。」
2.6 通信与信任：WS 协议 + 设备配对
所有客户端、节点、渠道都通过 WebSocket 连 Gateway。连接不是匿名的------OpenClaw 有一套设备配对 + Challenge 签名的信任机制。
#mermaid-svg-FNZnEpQ6c4EYEZew{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-FNZnEpQ6c4EYEZew .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-FNZnEpQ6c4EYEZew .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-FNZnEpQ6c4EYEZew .error-icon{fill:#552222;}#mermaid-svg-FNZnEpQ6c4EYEZew .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-FNZnEpQ6c4EYEZew .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-FNZnEpQ6c4EYEZew .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-FNZnEpQ6c4EYEZew .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-FNZnEpQ6c4EYEZew .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-FNZnEpQ6c4EYEZew .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-FNZnEpQ6c4EYEZew .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-FNZnEpQ6c4EYEZew .marker{fill:#333333;stroke:#333333;}#mermaid-svg-FNZnEpQ6c4EYEZew .marker.cross{stroke:#333333;}#mermaid-svg-FNZnEpQ6c4EYEZew svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-FNZnEpQ6c4EYEZew p{margin:0;}#mermaid-svg-FNZnEpQ6c4EYEZew .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-FNZnEpQ6c4EYEZew .cluster-label text{fill:#333;}#mermaid-svg-FNZnEpQ6c4EYEZew .cluster-label span{color:#333;}#mermaid-svg-FNZnEpQ6c4EYEZew .cluster-label span p{background-color:transparent;}#mermaid-svg-FNZnEpQ6c4EYEZew .label text,#mermaid-svg-FNZnEpQ6c4EYEZew span{fill:#333;color:#333;}#mermaid-svg-FNZnEpQ6c4EYEZew .node rect,#mermaid-svg-FNZnEpQ6c4EYEZew .node circle,#mermaid-svg-FNZnEpQ6c4EYEZew .node ellipse,#mermaid-svg-FNZnEpQ6c4EYEZew .node polygon,#mermaid-svg-FNZnEpQ6c4EYEZew .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-FNZnEpQ6c4EYEZew .rough-node .label text,#mermaid-svg-FNZnEpQ6c4EYEZew .node .label text,#mermaid-svg-FNZnEpQ6c4EYEZew .image-shape .label,#mermaid-svg-FNZnEpQ6c4EYEZew .icon-shape .label{text-anchor:middle;}#mermaid-svg-FNZnEpQ6c4EYEZew .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-FNZnEpQ6c4EYEZew .rough-node .label,#mermaid-svg-FNZnEpQ6c4EYEZew .node .label,#mermaid-svg-FNZnEpQ6c4EYEZew .image-shape .label,#mermaid-svg-FNZnEpQ6c4EYEZew .icon-shape .label{text-align:center;}#mermaid-svg-FNZnEpQ6c4EYEZew .node.clickable{cursor:pointer;}#mermaid-svg-FNZnEpQ6c4EYEZew .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-FNZnEpQ6c4EYEZew .arrowheadPath{fill:#333333;}#mermaid-svg-FNZnEpQ6c4EYEZew .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-FNZnEpQ6c4EYEZew .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-FNZnEpQ6c4EYEZew .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-FNZnEpQ6c4EYEZew .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-FNZnEpQ6c4EYEZew .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-FNZnEpQ6c4EYEZew .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-FNZnEpQ6c4EYEZew .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-FNZnEpQ6c4EYEZew .cluster text{fill:#333;}#mermaid-svg-FNZnEpQ6c4EYEZew .cluster span{color:#333;}#mermaid-svg-FNZnEpQ6c4EYEZew div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-FNZnEpQ6c4EYEZew .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-FNZnEpQ6c4EYEZew rect.text{fill:none;stroke-width:0;}#mermaid-svg-FNZnEpQ6c4EYEZew .icon-shape,#mermaid-svg-FNZnEpQ6c4EYEZew .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-FNZnEpQ6c4EYEZew .icon-shape p,#mermaid-svg-FNZnEpQ6c4EYEZew .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-FNZnEpQ6c4EYEZew .icon-shape .label rect,#mermaid-svg-FNZnEpQ6c4EYEZew .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-FNZnEpQ6c4EYEZew .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-FNZnEpQ6c4EYEZew .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-FNZnEpQ6c4EYEZew :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 是
有效
无效
否
本地 loopback
远程连接
新设备发起 connect 帧
(设备身份 + challenge nonce 签名)
设备 ID 已知?
验证设备令牌
放行
拒绝
进配对队列
自动审批
人工审批
签发设备令牌
WS 协议摘要：
| 阶段 | 行为 |
|---|---|
| 连接 | 第一帧 必须 是 connect（含设备身份 + challenge 签名） |
| 请求 | {type:"req", id, method, params} → `{type:"res", id, ok, payload |
| 事件 | {type:"event", event, payload, seq?, stateVersion?} |
| 幂等 | 副作用方法（send、agent）必须带幂等键；服务器保留短周期去重缓存 |
信任分级：
- 本地 loopback（同主机）：自动审批新设备，UX 顺畅。
- 远程连接：始终需显式人工审批------防止陌生设备劫持。
- Challenge 签名 ：所有连接必须对
connect.challengenonce 签名；v3 绑定platform+deviceFamily，防止令牌跨设备复用。
远程访问首选 ：Tailscale 或 SSH 隧道 ssh -N -L 18789:127.0.0.1:18789 user@gateway-host，而非直接暴露端口。
2.7 渠道（Channels）清单
按分发方式分组：
| 分发 | 渠道 |
|---|---|
| 内置 | iMessage · Telegram · WebChat |
| 官方插件 | Discord · WhatsApp · Signal · Slack · 飞书 · QQ Bot · Zalo · Google Chat · MS Teams · LINE · Matrix · Mattermost · IRC · Nostr · Twitch · SMS · Nextcloud Talk · Synology Chat · Tlon · Voice Call |
| 外部插件 | 微信 · 腾讯元宝 |
| LobsterAI 增强 | 企微 · 钉钉 |
渠道数量不是重点------重点是 OpenClaw 通过渠道适配器模式统一了各家 IM 协议差异，让 Agent 不用关心消息来自 WhatsApp 还是 Telegram。
2.8 Agent Runtime 与工作区
每个 Agent 有独立工作区（cwd）+ 引导文件。引导文件注入系统提示词，构成 Agent 的"人格"。
| 文件 | 用途 | 类比 |
|---|---|---|
AGENTS.md |
操作指令 + "记忆" | 规则手册 |
SOUL.md |
人设、边界、语气 | 性格 |
TOOLS.md |
工具使用约定 | 工具说明书 |
IDENTITY.md |
Agent 名称/氛围/emoji | 身份证 |
USER.md |
用户资料 + 称呼 | 用户档案 |
BOOTSTRAP.md |
一次性首次运行仪式（完成后删除） | 新手引导 |
MEMORY.md |
长期记忆（可选） | 长期记忆 |
工作区布局：
<workspace>/
├── AGENTS.md # 操作规则
├── SOUL.md # 人设
├── TOOLS.md # 工具约定
├── IDENTITY.md # 身份
├── USER.md # 用户资料
├── MEMORY.md # 长期记忆（可选）
├── skills/ # 工作区 Skills（优先级最高）
└── .agents/skills/ # 项目级 Agent Skills35+ Provider ：Anthropic、OpenAI、Google 等 + 自托管（vLLM、SGLang、Ollama、llama.cpp、LM Studio、任何 OpenAI/Anthropic 兼容端点）。配置格式：provider/model（如 openrouter/moonshotai/kimi-k2）。
2.9 工具生态
内置核心 ：read / exec / edit / write / apply_patch。
搜索 Provider：Brave、DuckDuckGo、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Ollama Web Search、Perplexity、SearXNG、Tavily。
其他：浏览器自动化、沙箱隔离、Cron + Heartbeat 调度、图片/音频/视频 I/O、语音转写 + TTS、Canvas（Agent 可编辑 HTML/CSS/JS）、A2UI 管道。
2.10 多 Agent 路由
- 每个 Agent 有独立工作区、引导文件、会话存储
- 按 Agent ID / 工作区 / 发送者隔离会话
- 群聊各隔离；直接聊天合并到共享
main
json5
{
agents: {
defaults: { skills: ["github", "weather"] },
list: [
{ id: "writer" }, // 继承 defaults
{ id: "docs", skills: ["docs-search"] }, // 替换 defaults
{ id: "locked-down", skills: [] }, // 无 Skills（最小权限）
],
},
}
locked-downAgent 是个值得注意的设计------显式给空 Skills 数组，实现最小权限 Agent。企业对标：只读运维 Bot。
2.11 安全模型
| 机制 | 说明 |
|---|---|
| 设备配对审批 | 新设备需人工批准；已配对凭令牌重连 |
| Challenge 签名 | 所有连接必须对 nonce 签名；v3 绑定 platform + deviceFamily |
| Channel allowFrom | 白名单控制允许的设备/号码 |
| 群聊提及规则 | 仅在 @提及 时响应 |
| 沙箱隔离 | Docker/OS 级沙箱执行不受信代码 |
| 第三方 Skills 警告 | 官方："将第三方 Skills 视为不受信任的代码" |
| 安装策略命令 | security.installPolicy 在 Skill 安装前运行本地策略检查 |
| 密钥作用域 | API key 注入主机进程，不注入沙箱和 prompt 日志 |
核心设计哲学：「本地信任、远程审批、沙箱隔离」------本地 loopback 自动放行保 UX，远程显式审批保安全，不受信代码进沙箱保底线。
LC3 · 使用 ------ 我能用它干啥 + 开发实战
3.1 我能用它干啥：8 个典型场景
这一节回答最实际的问题：装完 OpenClaw，我到底能用它做什么？
场景 1 · IM 个人助理
- 触发：在手机 WhatsApp/Telegram 发「帮我总结今天 HN 头条」「查一下明天北京的天气」「把这封邮件草稿改得更客气点」
- 工作流 ：IM 消息 → Gateway → Agent 用
web工具抓取 + LLM 总结 → 结果回 IM - 价值：把 AI 助手嵌进你已有的聊天工具，不用切换 App。出门在外用手机就能派活。
场景 2 · 异步任务监控
- 触发：Cron 定时（如每 5 分钟）
- 工作流 ：Cron 调度器触发 Agent →
exec检查服务健康 → 异常时 LLM 生成告警摘要 → IM 推送 - 价值：比传统监控多了"AI 总结"------不是甩一堆日志，而是告诉你"数据库连接池打满了，最近 5 分钟 12 次超时，根因可能是 X"。
场景 3 · 多 Agent 协作
- 触发：复杂任务需要不同权限/能力的 Agent
- 工作流 ：
writerAgent 写稿 →docsAgent 查文档库验证事实 →locked-downAgent（空 Skills）只读执行不可信操作 - 价值：按风险分级隔离。写操作给全权 Agent，验证给只读 Agent，外部输入给沙箱 Agent。
场景 4 · 跨渠道统一入口
- 触发：同一 Agent 同时接 Telegram（出门）+ WhatsApp（国际）+ Discord（社区）
- 工作流：每个渠道一个适配器，消息归一化后路由到同一 Agent，但会话按渠道隔离
- 价值：一个 Agent 多入口，你在哪个 App 里都能找它，但各渠道记忆独立不串味。
场景 5 · 浏览器自动化
- 触发：「帮我登录 XX 站点抓取订单数据」「监控这个页面价格降到 500 就通知我」
- 工作流 ：Agent 调
browser工具（Browserbase/本地 Chromium）→ 操作页面 →read/write存结果 - 价值：用自然语言驱动浏览器，不用写 Selenium 脚本。适合一次性抓取任务。
场景 6 · 代码/文档生成
- 触发：「给这个项目生成 README」「把这份 API 文档翻译成英文」
- 工作流 ：Agent 在工作区内
read现有代码 →edit/write生成文档 - 价值：Agent 直接操作文件系统，产出落盘成文件，不是只在聊天里给你文本。
场景 7 · 个人知识库
- 触发：跨会话维护长期记忆 + 笔记
- 工作流 ：
memory工具跨会话存取 +read/edit维护 Markdown 笔记库 - 价值：Agent 记得你上周说过什么。比 ChatGPT 的"记忆"更可控------记忆文件你能直接编辑。
场景 8 · 定时内容聚合
- 触发：Cron 每天早上 7 点
- 工作流：Agent 抓多个 RSS/新闻源 → LLM 总结成晨报 → IM 推送
- 价值：个性化信息流，AI 帮你从 20 个源里提炼 5 条重点。
共性：OpenClaw 的价值不在"它是个更强的 ChatGPT"，而在"它把 AI Agent 嵌进了你已有的 IM 工作流 + 文件系统 + 定时调度"。它让 AI 从"聊天框里"走到"你的日常工具链里"。
3.2 写一个自定义 Skill
bash
mkdir -p ~/my-agent/skills/hacker-news
cat > ~/my-agent/skills/hacker-news/SKILL.md << 'EOF'
---
name: hacker-news
description: Fetch top HN stories and summarize
metadata:
{
"openclaw":
{
"emoji": "📰",
"requires": { "bins": ["curl"] },
},
}
---
When the user asks for Hacker News top stories:
1. Fetch `https://hacker-news.firebaseio.com/v0/topstories.json`
2. Get first 10 story IDs
3. Fetch each item from `https://hacker-news.firebaseio.com/v0/item/<id>.json`
4. Summarize titles + URLs in a table, sorted by score
EOF
openclaw skills install ./my-agent/skills/hacker-news --as hacker-news3.3 写一个插件（最小示例）
json
// openclaw.plugin.json
{
"id": "my-custom-plugin",
"name": "My Custom Plugin",
"version": "1.0.0",
"channels": [],
"skills": ["skills"],
"tools": []
}
bash
openclaw plugins install ./path/to/my-plugin
openclaw plugins search3.4 SKILL.md 双格式对照（面试指认点）
面试官常追问「画一个 Skill 长什么样」。三栈都收敛到 SKILL.md + frontmatter + 正文指令 同构，差异在 frontmatter 字段与加载门控。
Hermes 风格 ------条件激活靠 metadata.hermes.*：
yaml
---
name: ddg-search
description: DuckDuckGo search fallback when web toolset unavailable
metadata:
hermes:
fallback_for_toolsets: [web] # 仅当 web toolset 不可用时显示
requires_toolsets: [terminal] # 需要 terminal toolset 才能跑
---企业 Spring AI 风格------条件激活靠租户 flag + OPA：
yaml
---
name: refund-advisor
description: Refund policy advisor for CS agents
tenant_whitelist: [tmall, jd] # 走 Registry 租户门禁
release_id: 2026-07-05-r2 # 绑四维版本
audit:
hitl: required
---| 维度 | Hermes | OpenClaw | 企业 |
|---|---|---|---|
| 门控位置 | metadata.hermes.* |
metadata.openclaw.* |
Registry + OPA |
| 条件字段 | requires_toolsets |
requires.bins/env/config |
tenant_whitelist |
| 自治 | 自动写 SKILL.md | Workshop 提案 + 人审批 | 禁止，走 Git PR |
3.5 LobsterAI / 有道龙虾（中国生态）
OpenClaw（开源 Gateway，MIT）
↓ 社区 fork + 产品化
LobsterAI（有道龙虾）
↓ 通过 WebSocket RPC 调用
OpenClaw Gateway（独立进程）- LobsterAI = 网易有道的桌面壳（Electron UI）+ Skill Store + 中文优化
- LobsterAI 不替代 OpenClaw------作为 UI 层通过 WS RPC 调 Gateway
- 解耦设计：UI 升级不碰 Gateway，Gateway 升级不影响 UI
| 能力 | OpenClaw 原生 | LobsterAI 增强 |
|---|---|---|
| 桌面 UI | Web Control UI | Electron + macOS 菜单栏/Windows Hub |
| Skill 发现 | ClawHub CLI | 图形化 Skill Store + MCP 一键接入 |
| 安全确认 | --- | 工具调用弹窗确认 + HTTP 阻断 + 超时 |
| 中文 IM | QQ Bot（插件） | 企微/钉钉/飞书/QQ 等多渠道 |
LC4 · 卸载 ------ 为什么难 + 一键全清
4.1 为什么难卸载（5 个残留点）
npm uninstall -g openclaw 只删除 npm 包本身，以下全部残留：
| # | 残留位置 | 内容 | 清理命令 |
|---|---|---|---|
| 1 | ~/.openclaw/ |
所有配置、API Key、会话记录 | rm -rf ~/.openclaw |
| 2 | 守护进程 | launchd（macOS）/ systemd（Linux）仍在运行 |
openclaw daemon stop；卸载 plist |
| 3 | 旧版遗留目录 | ~/.clawdbot/ ~/.moltbot/ ~/.moldbot/（三次改名） |
rm -rf ~/.clawdbot ~/.moltbot ~/.moldbot |
| 4 | Shell 配置注入 | ~/.bashrc / ~/.zshrc 中 export PATH=... 行 |
手动删行后 source ~/.zshrc |
| 5 | Homebrew 软链接 | /opt/homebrew/bin/openclaw / /usr/local/bin/openclaw |
rm -f 删除 |
4.2 一键全清
bash
# macOS / Linux（npm 方式安装）
openclaw daemon stop
npm uninstall -g openclaw
rm -rf ~/.openclaw ~/.clawdbot ~/.moltbot ~/.moldbot
rm -f /opt/homebrew/bin/openclaw /usr/local/bin/openclaw
# 检查 ~/.bashrc / ~/.zshrc 中是否有 openclaw 相关 PATH 行，手动删除卸载难的根因：OpenClaw 不是单纯 CLI 工具，而是 Gateway 守护进程 + 多渠道插件 + npm 全局包 的三层架构，每层有独立残留点。
架构设计思路（可借鉴）
这一节是给开发者的"取经指南"------OpenClaw 的 8 个设计思路，哪些值得你在自己的系统里借鉴，怎么借鉴。
思路 1 · 单中控 Gateway 模式
OpenClaw 怎么做：每台主机一个 Gateway 进程，是 IM 会话、消息路由、会话状态的唯一可信源。所有客户端/节点通过 WS 连它，而非各自直连 IM。
为何这样设计：IM 会话有状态（如 WhatsApp Baileys 会话不能双进程共存），必须单点持有。
企业借鉴：多副本 Agent 服务别让每个副本直连 IM，用一致性哈希分片 + 共享会话存储，把"单中控"从单机扩展到集群。
思路 2 · Skills 文档化（声明式能力）
OpenClaw 怎么做 ：能力用 SKILL.md（Markdown + frontmatter）声明，而非硬编码进代码。Skill 自描述依赖与门控，运行时自动过滤。
为何这样设计：能力可热加载、可社区分发（ClawHub）、可版本化，不用改代码重新部署。
企业借鉴：团队 Agent 的能力库走 Git + PR 管理文档化 Skills，而非把 prompt 硬编码在代码里。新增能力 = 加一个 Markdown 文件。
思路 3 · MCP 端口统一（工具解耦）
OpenClaw 怎么做：工具调用走 MCP 标准协议，MCP Server 是独立进程，与 Gateway 解耦。
为何这样设计：工具可用任何语言写、可独立崩溃、可独立版本化。Agent 不关心工具实现，只关心协议契约。
企业借鉴：企业工具网关统一 MCP，而非每个 Agent 各自集成每家 API。新增工具 = 部署一个 MCP Server，所有 Agent 自动可用。
思路 4 · 设备配对信任（分级审批）
OpenClaw 怎么做：本地 loopback 自动审批新设备保 UX，远程连接强制人工审批保安全，配对后签发令牌。
为何这样设计：平衡"自己用方便"和"防陌生人劫持"。
企业借鉴：内部工具 Bot 区分内网/外网请求------内网自动放行，外网走审批队列。比一刀切"全部审批"或"全部放行"更合理。
思路 5 · 工作区引导文件（人格配置文件化）
OpenClaw 怎么做 ：Agent 的人设、规则、用户档案用 AGENTS.md/SOUL.md/USER.md 等文件管理，注入系统提示词。
为何这样设计：人格配置可版本化、可团队共享、可手工编辑。比散在代码里的 prompt 字符串易维护。
企业借鉴：团队 Agent 规范用文件约定（规则、人设、工具用法），而非把 prompt 散在各处。新人接手 = 读这几个文件。
思路 6 · JSONL 会话存储（可重放）
OpenClaw 怎么做 ：每个会话一个 .jsonl 文件，每帧一行，追加写。
为何这样设计：追加写性能好、可逐帧重放调试、易截断裁剪上下文。
企业借鉴：调试 Agent 行为时回放 JSONL，而非加满日志。出问题 = 把会话 JSONL 喂给另一个 Agent 让它分析。
思路 7 · 快照式 Skills 加载（防漂移）
OpenClaw 怎么做：会话开始时对 Skills 做快照，会话期间用快照，文件变更才刷新。
为何这样设计：长会话中途 Skills 集合变化会导致 Agent 行为漂移（前半段用 A Skill，后半段 A 消失了）。
企业借鉴：长会话 Agent 锁定 Skills/Prompt 版本，运行中不动态加载新能力。版本变更走新会话。
思路 8 · 沙箱隔离 + 密钥作用域
OpenClaw 怎么做 ：不受信代码进沙箱执行；API key 注入主机进程，不注入沙箱和 prompt 日志。
为何这样设计：第三方 Skills 视为不受信代码------即使它想偷 key，沙箱里也没有 key 可偷。
企业借鉴：Agent 执行外部代码（用户输入、第三方插件）必走沙箱 + 最小权限。密钥与执行环境隔离，是防 prompt 注入泄露 key 的底线。
总结 ：OpenClaw 的设计哲学是「单中控 + 声明式能力 + 协议解耦 + 分级信任 + 文件化配置 + 可重放存储 + 防漂移快照 + 沙箱隔离」。这套思路不只适用于个人 Agent OS------企业 Agent 平台可以照搬前 6 条，第 7-8 条尤其值得在安全敏感场景落地。
LC5 · 面试速查（附录）
以下为面试备考核心，技术博客读者可跳过本节。
5.1 与 Hermes Agent 对比
| 维度 | OpenClaw | Hermes Agent |
|---|---|---|
| 源码 | openclaw/openclaw | NousResearch/hermes-agent |
| 语言 | TypeScript / Node.js | Python |
| UI 形态 | Web Control UI + macOS/Windows 原生 | 终端 TUI (hermes) |
| Skills 门控 | metadata.openclaw.requires (bins/env/config) |
metadata.hermes.requires_toolsets / fallback_for_toolsets |
| Skills 自治 | 提案队列（Workshop，人工审批） | 自动写 SKILL.md（自进化） |
| MCP | Gateway 事件模型 | ~/.hermes/mcp_servers |
| 中国生态 | LobsterAI 有道龙虾 | 无国内定制 |
5.2 面试高频 Q&A
Q: OpenClaw Gateway 是什么？
A: 本地常驻进程（Node.js），通过 WebSocket 接受客户端/节点/渠道的消息，管理 Agent 会话、Skills 加载、模型调用和渠道投递。不是模型本身，是控制平面。
Q: OpenClaw 能上生产吗？
A: 原样不可。缺多租户 Registry、Eval Gate、合规审计、SLA。但 8 个设计思路可借鉴（见「架构设计思路」节）。
Q: Skills 和 MCP 什么关系？
A: Skills = 流程知识 （SKILL.md Markdown 指令）；MCP = 标准化工具 RPC。Skills 告诉 Agent 何时用某个工具，MCP 提供工具本身。
Q: OpenClaw vs Cursor Agent？
A: 改代码 → Cursor；跨 App 自动化/IM 派活 → OpenClaw；支付写操作 → 都不用，上 Spring AI + HITL。
Q: LobsterAI 和 OpenClaw 关系？
A: LobsterAI = 有道龙虾桌面壳 + Skill Store，通过 WebSocket RPC 调 OpenClaw Gateway。UI/Gateway 独立升级。
Q: 为什么 OpenClaw 安装和卸载这么困难？
A: 三点------(1) 不是单纯 CLI 工具，是 Gateway 守护进程 + 多渠道插件 + npm 包的三层架构；(2) 环境强依赖：Node 22+/WSL2/C++ 工具链；(3) 卸载不干净：npm uninstall 只删包，残留 5 处。
Q: OpenClaw 的 Skill Workshop 和 Hermes 的自进化有什么区别？
A: OpenClaw 的 Workshop 是**"自建议 + 人审批"------Agent 起草提案，用户审查通过后才写入。Hermes 是"自进化"**------任务后自动写。企业侧要求 PR + Eval Gate，OpenClaw 的 Workshop 更接近企业审批流程。
Q: OpenClaw 安全模型的核心是什么？
A: 三层------(1) 设备层：配对审批 + Challenge 签名 + 令牌管理；(2) 渠道层：allowFrom 白名单 + 群聊提及规则；(3) 执行层：沙箱隔离 + 密钥不注入沙箱 + 第三方 Skills 视为不受信代码。核心哲学是**"本地信任、远程审批、沙箱隔离"**。
5.3 30 秒开场金句
「OpenClaw 是 MIT 开源的个人 Agent Gateway，跑在本机，把 IM 渠道的消息经 WebSocket 交给内嵌 Agent 执行工具调用，数据不出硬盘。核心是 ReAct 循环------LLM 推理 ↔ 工具调用，会话以 JSONL 落盘可重放。企业可借鉴它的单中控、Skills 文档化、MCP 端口统一、沙箱隔离等 8 个设计思路，但原样上不了生产------缺 Registry、Eval Gate、审计。」
延伸阅读
以下为同仓库（Gitee）内的关联资料，已转为绝对链接，可直接访问。
| 关联 | 路径 |
|---|---|
| 企业对标（面试答辩） | 12 OpenClaw/Hermes 对标 |
| 速记版（2 分钟） | P3-02 速记 |
| Agent 知识全景 | AGENT-KNOWLEDGE-BASE-MAP |
官方文档与源码（一级依据）
OpenClaw · 正文机制全部来自下方 官方文档（L1） 与 官方源码仓库（L2） ；
禁止用教程站/博客充当机制依据。
L1 · 官方文档
L2 · 官方源码
L3 · 协议 / 规范
- AgentSkills 规范 --- SKILL.md 格式标准