OpenClaw 核心架构1万2千字解析:从 WebSocket 网关到多代理路由的完整实现

在 AI Agent 基础设施领域，OpenClaw 不是另一个"AI 助手框架"，而是一个生产级的多通道消息网关，将飞书、WhatsApp、Telegram、Discord、iMessage 等消息平台与 AI 编码代理（如 Codex、Claude Code）无缝连接。
这篇文章将深入 OpenClaw 的核心架构，从 WebSocket 网关协议到多代理路由系统，从会话管理到沙箱执行，从安全模型到插件扩展机制，逐层剖析其设计哲学与工程实现。
本文的独特价值：
基于官方文档与源码的深度分析，非表面介绍
包含完整的架构图、消息流转图、时序图
揭示每个组件的底层实现细节
分析每个大版本的关键优化与演进路径
提供生产环境部署的安全最佳实践
适合人群：
想改造 OpenClaw 的、对 AI Agent 架构感兴趣的、纯好奇想搞明白"龙虾这玩意儿怎么跑起来"的。🦞

1. 整体架构概览

1.1 核心设计哲学

OpenClaw 的设计遵循几个核心原则：

┌─────────────────────────────────────────────────────────────────┐│                    OpenClaw 设计原则                              │├─────────────────────────────────────────────────────────────────┤│  1. 单一网关进程 (Single Gateway Process)                        ││     - 一个主机运行一个 Gateway，统一管理所有消息通道              ││     - 避免多进程状态同步复杂性                                    ││                                                                  ││  2. 控制平面与数据平面分离                                        ││     - WebSocket 控制平面：CLI、Web UI、macOS App                 ││     - 消息数据平面：WhatsApp、Telegram、Discord 等通道            ││                                                                  ││  3. 个人助手信任模型 (Personal Assistant Trust Model)            ││     - 假设单一可信操作员边界                                     ││     - 不支持敌对多租户隔离                                       ││     - 多用户场景需拆分信任边界（独立网关/主机）                   ││                                                                  ││  4. 插件化扩展 (Plugin-First Extension)                          ││     - 核心功能最小化                                             ││     - 通道、工具、认证通过插件扩展                                ││                                                                  ││  5. 安全默认关闭 (Secure by Default)                             ││     - 本地回环绑定 + 强制认证                                     ││     - DM 配对默认开启                                            ││     - 工具策略需显式启用                                         │└─────────────────────────────────────────────────────────────────┘

1.2 系统架构图

graph TB    subgraph "消息通道层 Message Channels"        WA[WhatsApp<br/>Baileys]        TG[Telegram<br/>grammY]        DC[Discord<br/>discord.js]        SL[Slack<br/>Bolt]        IM[iMessage<br/>BlueBubbles]        WX[WebChat]    end    subgraph "Gateway 核心层"        direction TB        WS[WebSocket 服务器<br/>端口 18789]        RT[路由引擎<br/>Routing Engine]        SM[会话管理器<br/>Session Manager]        TM[工具管理器<br/>Tool Manager]        PM[插件注册表<br/>Plugin Registry]        AM[代理运行时<br/>Agent Runtime]    end    subgraph "控制平面 Control Plane"        CLI[CLI 工具]        WEB[Web Control UI]        MAC[macOS App]        IOS[iOS Node]        AND[Android Node]    end    subgraph "AI 代理层 AI Agents"        PI[Pi Agent<br/>Embedded]        CX[Codex CLI]        CC[Claude Code]        SA[Subagents]    end    subgraph "存储层 Storage"        CFG[Config<br/>~/.openclaw/openclaw.json]        SES[Sessions<br/>~/.openclaw/agents/<id>/sessions/]        CRD[Credentials<br/>~/.openclaw/credentials/]        LOG[Logs<br/>/tmp/openclaw/]    end    WA --> WS    TG --> WS    DC --> WS    SL --> WS    IM --> WS    WX --> WS    WS --> RT    RT --> SM    RT --> TM    RT --> AM    CLI --> WS    WEB --> WS    MAC --> WS    IOS --> WS    AND --> WS    AM --> PI    AM --> CX    AM --> CC    AM --> SA    SM --> SES    TM --> CRD    RT --> CFG    WS --> LOG    style WS fill:#e1f5fe    style RT fill:#fff3e0    style SM fill:#f3e5f5    style AM fill:#e8f5e9

1.3 核心组件职责

组件	职责	关键文件
Gateway	WebSocket 服务器，消息路由，会话管理	`src/gateway/`
Channels	消息通道适配器，入站/出站消息处理	`src/channels/`
Agents	AI 代理运行时，工具调用，流式响应	`src/agents/`
Tools	工具注册与执行，技能加载	`src/tools/`
Plugins	插件发现、加载、注册	`src/plugins/`
Sessions	会话状态管理，JSONL 转录存储	`src/sessions/`
Sandbox	Docker 沙箱容器管理	`src/sandbox/`

2. Gateway 核心组件

2.1 Gateway 启动流程

sequenceDiagram    participant OS as 操作系统    participant CLI as CLI 入口    participant GW as Gateway 主进程    participant PL as 插件系统    participant CH as 通道监控器    participant WS as WebSocket 服务器    OS->>CLI: openclaw gateway    CLI->>GW: 启动主进程    GW->>GW: 加载配置文件<br/>~/.openclaw/openclaw.json    GW->>GW: 解析 SecretRef 凭证    GW->>GW: 初始化日志系统    GW->>PL: 发现并加载插件    PL-->>GW: 注册通道/工具/RPC 方法    GW->>CH: 启动通道监控器    CH->>CH: WhatsApp (Baileys)    CH->>CH: Telegram (grammY)    CH->>CH: Discord (discord.js)    CH-->>GW: 通道就绪状态    GW->>WS: 启动 WebSocket 服务器    WS->>WS: 绑定端口 (默认 18789)    WS->>WS: 加载 TLS 证书 (可选)    WS-->>GW: 监听中    GW->>GW: 发送健康检查事件    GW-->>CLI: Gateway 就绪

2.2 配置加载与验证

配置文件位于 ~/.openclaw/openclaw.json，使用 JSON5 格式支持注释和尾随逗号。

关键配置项：

{  // Gateway 网络绑定  gateway: {    mode: "local",           // local | remote    bind: "loopback",        // loopback | lan | tailnet | custom    port: 18789,    auth: {      mode: "token",         // token | password | trusted-proxy      token: "${GATEWAY_TOKEN}"    }  },  // 会话管理  session: {    dmScope: "per-channel-peer",  // main | per-peer | per-channel-peer    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json"  },  // 代理默认配置  agents: {    defaults: {      model: "anthropic/claude-sonnet-4-5",      sandbox: {        mode: "non-main",    // off | non-main | all        scope: "session",    // session | agent | shared        workspaceAccess: "none"  // none | ro | rw      }    }  },  // 工具策略  tools: {    profile: "messaging",    // messaging | coding | minimal    deny: ["gateway", "cron"],    fs: { workspaceOnly: true },    exec: {       security: "deny",      // deny | allowlist | full      ask: "always"          // off | on-miss | always    }  }}

2.3 插件注册表

插件系统是 OpenClaw 扩展性的核心。所有功能（通道、工具、RPC 方法、CLI 命令）都通过插件注册表统一管理。

graph LR    subgraph "插件发现 Plugin Discovery"        D1[Config Paths<br/>plugins.load.paths]        D2[Workspace<br/>.openclaw/extensions/]        D3[Global<br/>~/.openclaw/extensions/]        D4[Bundled<br/>npm package]    end    subgraph "插件加载 Plugin Loading"        L1[读取 openclaw.plugin.json]        L2[验证入口文件]        L3[jiti 加载 TS/JS]        L4[调用 register]    end    subgraph "注册表 Registry"        R1[Tools]        R2[Channels]        R3[Gateway RPC]        R4[CLI Commands]        R5[Hooks]        R6[Services]    end    D1 --> L1    D2 --> L1    D3 --> L1    D4 --> L1    L1 --> L2 --> L3 --> L4    L4 --> R1    L4 --> R2    L4 --> R3    L4 --> R4    L4 --> R5    L4 --> R6    style R1 fill:#e3f2fd    style R2 fill:#e8f5e9    style R3 fill:#fff3e0

3. WebSocket 协议详解

3.1 协议概述

OpenClaw 使用自定义的 WebSocket 协议作为控制平面通信标准。所有客户端（CLI、Web UI、macOS App、Node 设备）都通过此协议与 Gateway 交互。

传输层：

WebSocket 文本帧，JSON 载荷
首帧必须是 connect 握手请求
支持 TLS (wss://) 和明文 (ws://，仅限回环)

3.2 握手流程

sequenceDiagram    participant Client as 客户端    participant GW as Gateway    Note over GW: 客户端连接 WebSocket    GW-->>Client: event:connect.challenge<br/>{ nonce, ts }    Client->>GW: req:connect<br/>{<br/>  minProtocol, maxProtocol,<br/>  client: { id, version, platform },<br/>  role: "operator" | "node",<br/>  scopes: ["operator.read", "operator.write"],<br/>  device: {<br/>    id, publicKey,<br/>    signature, signedAt, nonce<br/>  }<br/>}    GW->>GW: 验证设备签名    GW->>GW: 检查配对状态    GW->>GW: 验证 Auth Token    alt 验证成功      GW-->>Client: res:connect<br/>{<br/>    type: "hello-ok",<br/>    protocol: 3,<br/>    auth: { deviceToken? }<br/>  }      Note over Client,GW: 进入正常请求/事件循环    else 验证失败      GW-->>Client: res:connect { error: {...} }      GW->>Client: 关闭连接    end

握手请求示例：

{"type": "req","id": "conn-123","method": "connect","params": {"minProtocol": 3,"maxProtocol": 3,"client": {"id": "cli","version": "2026.3.13","platform": "macos","mode": "operator"    },"role": "operator","scopes": ["operator.read", "operator.write"],"caps": [],"commands": [],"permissions": {},"auth": { "token": "xxx" },"locale": "en-US","device": {"id": "device_fingerprint","publicKey": "ed25519:xxx","signature": "xxx","signedAt": 1737264000000,"nonce": "server-provided-nonce"    }  }}

3.3 帧结构

**请求帧 (Request)**：

{"type": "req","id": "unique-request-id","method": "sessions.list","params": { "activeMinutes": 30 }}

**响应帧 (Response)**：

{"type": "res","id": "unique-request-id","ok": true,"payload": { "sessions": [...] }}

**事件帧 (Event)**：

{"type": "event","event": "agent","payload": {"runId": "run-123","stream": "assistant","delta": "Hello"  },"seq": 42}

3.4 核心 RPC 方法

方法	作用域	描述
`connect`	所有	WebSocket 握手
`health`	operator	健康检查
`status`	operator	获取 Gateway 状态
`send`	operator.write	发送消息到通道
`agent`	operator.write	启动代理运行
`agent.wait`	operator.write	等待代理运行完成
`sessions.list`	operator.read	列出会话
`sessions.reset`	operator.admin	重置会话
`config.get`	operator.read	获取配置
`config.patch`	operator.admin	部分更新配置
`config.apply`	operator.admin	应用完整配置
`exec.approval.resolve`	operator.approvals	审批执行请求
`device.token.rotate`	operator.pairing	轮换设备令牌

3.5 事件类型

事件	触发条件	载荷内容
`connect.challenge`	新连接	`{ nonce, ts }`
`presence`	客户端连接/断开	设备在线状态
`tick`	定期心跳	间隔可配置
`agent`	代理运行	流式输出/工具事件
`chat`	聊天消息	增量/最终消息
`exec.approval.requested`	需要审批的执行	命令详情
`health`	健康状态变化	通道/服务状态
`heartbeat`	心跳触发	系统事件注入

4. 会话管理系统

4.1 会话键设计

会话是 OpenClaw 状态管理的核心单元。每个会话有唯一的键 (sessionKey)，用于路由和状态隔离。

会话键格式：

agent:<agentId>:<scope>:<channel>:<chatType>:<peerId>[:topic:<threadId>]

实际示例：

agent:main:main                          # 默认主会话 (所有 DM)agent:main:telegram:direct:123456789     # Telegram 特定发送者agent:main:discord:channel:987654321     # Discord 频道agent:main:whatsapp:group:120363@g.us    # WhatsApp 群组agent:main:telegram:group:120363@g.us:topic:456  # Telegram 话题

4.2 DM 范围配置

session.dmScope 控制直接消息的会话分组策略：

graph TD    subgraph "dmScope: main (默认)"        M1[所有 DM 共享主会话]        M2[优点：上下文连续]        M3[风险：多用户信息泄露]    end    subgraph "dmScope: per-peer"        P1[按发送者 ID 隔离]        P2[优点：用户隔离]        P3[跨通道同一用户共享]    end    subgraph "dmScope: per-channel-peer"        C1[按通道 + 发送者隔离]        C2[优点：完全隔离]        C3[推荐：多用户收件箱]    end    subgraph "dmScope: per-account-channel-peer"        A1[按账号 + 通道 + 发送者隔离]        A2[优点：多账号完全隔离]        A3[推荐：企业多账号场景]    end    style M1 fill:#ffebee    style C1 fill:#e8f5e9    style A1 fill:#e3f2fd

安全建议：

单用户场景：main（保持上下文连续性）
多用户共享收件箱：per-channel-peer（防止跨用户信息泄露）
多账号企业部署：per-account-channel-peer

4.3 会话存储结构

~/.openclaw/agents/<agentId>/sessions/├── sessions.json              # 会话元数据索引├── <sessionId>.jsonl         # 会话转录 (JSONL 格式)├── <sessionId>.jsonl.lock    # 会话锁文件├── *.deleted.<timestamp>     # 归档的已删除转录└── *.reset.<timestamp>       # 归档的重置转录

sessions.json 结构：

{"agent:main:main": {"sessionId": "sess-abc123","updatedAt": 1737264000000,"label": "Main Session","origin": {"provider": "webchat","from": "user-123","to": "bot-456"    },"inputTokens": 15000,"outputTokens": 8000,"totalTokens": 23000,"contextTokens": 12000,"modelProvider": "anthropic","modelId": "claude-sonnet-4-5"  }}

JSONL 转录格式：

{"role": "user", "content": "Hello", "timestamp": 1737264000000}{"role": "assistant", "content": "Hi there!", "timestamp": 1737264001000}{"role": "tool", "name": "exec", "params": {...}, "result": {...}}

4.4 会话重置策略

OpenClaw 支持多种会话重置触发器：

配置示例：

{  session: {    reset: {      mode: "daily",        // daily | idle | disabled      atHour: 4,            // 每日重置时间 (本地时区)      idleMinutes: 120,     // 空闲重置阈值    },    resetByType: {      thread: { mode: "daily", atHour: 4 },      direct: { mode: "idle", idleMinutes: 240 },      group: { mode: "idle", idleMinutes: 120 }    },    resetByChannel: {      discord: { mode: "idle", idleMinutes: 10080 }  // 每周    },    resetTriggers: ["/new", "/reset"]  }}

重置流程：

sequenceDiagram    participant User as 用户    participant GW as Gateway    participant SM as Session Manager    participant FS as 文件系统    User->>GW: /new 或触发每日重置    GW->>SM: 检查重置策略    SM->>SM: 生成新 sessionId    SM->>FS: 归档旧转录文件    SM->>FS: 创建新会话条目    SM-->>GW: 新会话就绪    GW->>User: 确认重置    Note over GW: 后续消息使用新 sessionId

4.5 会话维护

OpenClaw 自动执行会话维护以防止无限增长：

维护配置：

{  session: {    maintenance: {      mode: "enforce",       // warn | enforce      pruneAfter: "45d",     // 删除超过 45 天的条目      maxEntries: 800,       // 最大会话数      rotateBytes: "20mb",   // sessions.json 轮转阈值      resetArchiveRetention: "14d",  // 归档保留期      maxDiskBytes: "1gb",   // 磁盘预算上限      highWaterBytes: "800mb"  // 高水位线 (触发清理)    }  }}

维护执行顺序：

修剪过期条目 (pruneAfter)
限制条目数量 (maxEntries)
归档已删除条目的转录
清理旧归档文件
轮转 sessions.json
执行磁盘预算 enforcement

5. 多代理路由机制

5.1 多代理架构

OpenClaw 支持在单个 Gateway 进程中运行多个隔离的 AI 代理。每个代理有独立的：

工作区 (workspace)
状态目录 (agentDir)
会话存储
工具策略
沙箱配置

多代理使用场景：

个人代理 vs 工作代理（不同模型/工具集）
家庭共享代理（受限工具 + 沙箱）
公共客服代理（最小权限）
多用户隔离（每个用户独立代理）

5.2 路由绑定系统

消息路由通过 bindings 配置实现，支持精确匹配和通配符。

绑定匹配优先级（从高到低）：

graph TB    P1[1. peer 精确匹配<br/>DM/群组/频道 ID]    P2[2. parentPeer 匹配<br/>线程继承]    P3[3. guildId + roles<br/>Discord 角色路由]    P4[4. guildId 匹配<br/>Discord 服务器]    P5[5. teamId 匹配<br/>Slack 团队]    P6[6. accountId 匹配<br/>通道账号]    P7[7. channel 匹配<br/>accountId: "*"]    P8[8. fallback<br/>默认代理]    P1 --> P2 --> P3 --> P4 --> P5 --> P6 --> P7 --> P8    style P1 fill:#ffcdd2    style P8 fill:#c8e6c9

绑定配置示例：

{  agents: {    list: [      { id: "personal", workspace: "~/.openclaw/workspace-personal" },      { id: "work", workspace: "~/.openclaw/workspace-work" },      { id: "family", workspace: "~/.openclaw/workspace-family" }    ]  },  bindings: [    // 精确 DM 路由（优先级最高）    {      agentId: "work",      match: {         channel: "whatsapp",         peer: { kind: "direct", id: "+15551234567" }       }    },    // 账号级路由    { agentId: "personal", match: { channel: "whatsapp", accountId: "personal" } },    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },    // 通道级 fallback    { agentId: "family", match: { channel: "telegram" } },    // Discord 角色路由    {      agentId: "work",      match: {         channel: "discord",         guildId: "123456789",         roles: ["developer"]       }    }  ]}

5.3 路由解析流程

sequenceDiagram    participant Msg as 入站消息    participant RE as 路由引擎    participant BC as 绑定缓存    participant AG as 代理选择    Msg->>RE: 提取路由键<br/>(channel, accountId, peer, guildId, roles)    RE->>BC: 查询绑定缓存    BC-->>RE: 缓存未命中    RE->>RE: 按优先级遍历 bindings    RE->>RE: 1. 检查 peer 精确匹配    RE->>RE: 2. 检查 parentPeer    RE->>RE: 3. 检查 guildId+roles    RE->>RE: 4. 检查 guildId/teamId    RE->>RE: 5. 检查 accountId    RE->>RE: 6. 检查 channel    RE->>AG: 返回匹配的 agentId    AG-->>RE: 代理配置    RE-->>Msg: 路由到目标代理会话

5.4 代理间隔离

隔离边界：

资源	隔离级别	说明
工作区	完全隔离	每个代理独立 `workspace` 目录
会话	完全隔离	`agent:<id>:*` 键前缀隔离
凭证	完全隔离	`auth-profiles.json` 每代理独立
技能	部分隔离	工作区技能独立，共享技能可见
工具	可配置隔离	每代理 `tools.allow/deny`
沙箱	可配置隔离	每代理 `sandbox.*` 配置

代理间通信：默认禁用，需显式启用：

{  tools: {    agentToAgent: {      enabled: true,      allow: ["personal", "work"]  // 允许互相调用的代理    }  }}

5.5 每代理沙箱与工具配置

{  agents: {    list: [      {        id: "personal",        sandbox: { mode: "off" },  // 无沙箱，完全访问        tools: {          // 无限制，所有工具可用        }      },      {        id: "family",        sandbox: {          mode: "all",          scope: "agent",          docker: {            setupCommand: "apt-get update && apt-get install -y git curl"          }        },        tools: {          allow: ["read", "exec"],          deny: ["write", "edit", "apply_patch", "browser", "nodes", "cron"]        }      },      {        id: "public",        sandbox: {          mode: "all",          workspaceAccess: "none"        },        tools: {          allow: ["telegram", "whatsapp", "sessions_list"],          deny: ["exec", "read", "write", "browser", "gateway", "cron"]        }      }    ]  }}

6. 工具与技能系统

6.1 工具 vs 技能

工具 (Tools)：

内置函数，由 Gateway 直接提供
例如：read, write, exec, browser, sessions_list
通过 tools.allow/deny 控制访问

技能 (Skills)：

AgentSkills 兼容的 Markdown 指令文件
教导代理如何使用工具
位于 skills/<name>/SKILL.md
可包含二进制依赖和安装说明

6.2 技能加载机制

graph TB    subgraph "技能来源"        B1[Bundled<br/>npm 包内]        M1[Managed<br/>~/.openclaw/skills]        W1[Workspace<br/><workspace>/skills]        E1[Extra Dirs<br/>skills.load.extraDirs]    end    subgraph "加载流程"        L1[扫描 SKILL.md]        L2[解析 frontmatter]        L3[检查 gating 条件<br/>bins/env/config]        L4[生成系统提示]    end    subgraph "优先级"        P1[Workspace 最高]        P2[Managed 中等]        P3[Bundled 最低]    end    B1 --> L1    M1 --> L1    W1 --> L1    E1 --> L1    L1 --> L2 --> L3 --> L4    L4 --> P1 --> P2 --> P3    style P1 fill:#ffcdd2    style W1 fill:#e8f5e9

SKILL.md 格式：

---name: nano-banana-prodescription: Generate or edit images via Gemini 3 Pro Imagemetadata:  {"openclaw": {"requires": {"bins": ["uv"], "env": ["GEMINI_API_KEY"]}}}---# nano-banana-pro使用 Gemini 3 Pro Image 生成或编辑图片。## 用法```bashuv run generate.py --prompt "..." --output image.png

**技能 gating 条件**：```json{"metadata": {"openclaw": {"always": false,           // 总是包含"os": ["darwin", "linux"], // 仅限特定 OS"requires": {"bins": ["uv", "git"],           // 必需二进制"anyBins": ["node", "bun"],      // 任一即可"env": ["GEMINI_API_KEY"],       // 环境变量"config": ["browser.enabled"]    // 配置项      },"primaryEnv": "GEMINI_API_KEY",    // 主环境变量"install": [...]                   // 安装说明    }  }}

6.3 工具执行流程

sequenceDiagram    participant Agent as AI 代理    participant TM as 工具管理器    participant SP as 沙箱进程    participant HP as 主机进程    participant EP as 执行审批    Agent->>TM: 调用工具 (exec, read, etc.)    TM->>TM: 检查工具策略 (allow/deny)    alt 工具被拒绝      TM-->>Agent: 错误：工具不允许    else 工具允许      TM->>TM: 检查沙箱配置    end    alt 沙箱模式 = all 或非主会话      TM->>SP: 在 Docker 容器中执行      SP->>SP: 挂载 workspace (ro/rw/none)      SP->>SP: 应用 bind mounts      SP-->>TM: 执行结果    else 沙箱模式 = off 或主会话      TM->>TM: 检查 exec.security    end    alt security = allowlist 且未匹配      TM->>EP: 请求审批      EP-->>TM: 用户批准/拒绝    else security = full 或已批准      TM->>HP: 在主机执行      HP-->>TM: 执行结果    end    TM-->>Agent: 工具结果

6.4 工具策略配置

{  tools: {    // 预设配置文件    profile: "coding",  // messaging | coding | minimal    // 显式允许/拒绝    allow: ["exec", "read", "write", "browser"],    deny: ["gateway", "cron", "sessions_spawn"],    // 文件系统限制    fs: {      workspaceOnly: true  // 限制到工作区    },    // 执行审批    exec: {      security: "allowlist",  // deny | allowlist | full      ask: "on-miss",         // off | on-miss | always      host: "sandbox",        // sandbox | gateway      applyPatch: {        workspaceOnly: true      }    },    // 提升模式（绕过沙箱）    elevated: {      enabled: false,      allowFrom: ["+15551234567"]  // 允许的用户    }  }}

7. 沙箱执行引擎

7.1 沙箱架构

OpenClaw 使用 Docker 容器作为工具执行的沙箱环境，提供文件系统隔离和进程隔离。

沙箱模式：

off：无沙箱，所有工具在主机执行
non-main：仅非主会话使用沙箱（默认推荐）
all：所有会话使用沙箱

沙箱范围：

session：每会话一个容器（最隔离）
agent：每代理一个容器（平衡）
shared：所有沙箱会话共享容器（最经济）

工作区访问：

none：沙箱内看不到主机工作区（默认）
ro：只读挂载到 /agent
rw：读写挂载到 /workspace

7.2 沙箱容器配置

graph TB    subgraph "主机 Host"        H1[Gateway 进程]        H2[工作区<br/>~/.openclaw/workspace]        H3[技能目录<br/>skills/]    end    subgraph "Docker 容器 Container"        C1[工具执行环境]        C2[沙箱工作区<br/>/workspace 或 /agent]        C3[技能镜像<br/>/skills]        C4[入站媒体<br/>media/inbound/]    end    H1 -->|exec 调用 | C1    H2 -->|ro/rw 挂载 | C2    H3 -->|镜像挂载 | C3    H2 -->|复制 | C4    style C1 fill:#e3f2fd    style C2 fill:#e8f5e9

Docker 配置示例：

{  agents: {    defaults: {      sandbox: {        mode: "non-main",        scope: "agent",        workspaceAccess: "ro",        docker: {          image: "openclaw-sandbox:bookworm-slim",          network: "none",  // 默认无网络          user: "0:0",      // root 用户          binds: [            "/home/user/source:/source:ro",            "/var/data:/data:ro"          ],          env: {            "GEMINI_API_KEY": "${GEMINI_API_KEY}"          },          setupCommand: "apt-get update && apt-get install -y nodejs npm"        }      }    }  }}

7.3 沙箱安全边界

沙箱提供的隔离：

✅ 文件系统隔离（通过挂载控制）
✅ 进程命名空间隔离
✅ 网络隔离（默认 network: "none"）
✅ 资源限制（CPU/内存）

沙箱不提供的隔离：

❌ 内核漏洞利用防护
❌ 侧信道攻击防护
❌ 恶意代码检测
❌ 多租户强隔离

重要安全说明：

沙箱是减轻损害范围的工具，不是安全银弹。对于敌对多租户场景，应使用独立主机/VM。

7.4 自定义沙箱镜像

基础镜像构建：

# 基础沙箱镜像（无 Node）scripts/sandbox-setup.sh# 常用工具镜像（含 nodejs, python3, git, curl）scripts/sandbox-common-setup.sh# 沙箱浏览器镜像scripts/sandbox-browser-setup.sh

自定义 Dockerfile 示例：

FROM node:22-bookworm-slim# 安装常用工具RUN apt-get update && apt-get install -y \    git curl wget jq python3 pipx \    && rm -rf /var/lib/apt/lists/*# 设置工作目录WORKDIR /workspace# 非 root 用户RUN useradd -m sandbox && chown sandbox:sandbox /workspaceUSER sandbox# 健康检查HEALTHCHECK CMD node --version || exit 1

8. 插件扩展架构

8.1 插件类型

OpenClaw 插件系统支持多种扩展类型：

类型	注册 API	用途
工具	`registerTool`	添加新工具
通道	`registerChannel`	添加消息通道
Provider	`registerProvider`	添加模型认证
Gateway RPC	`registerGatewayMethod`	添加 RPC 方法
CLI 命令	`registerCli`	添加 CLI 命令
Hook	`registerHook` / `api.on`	生命周期钩子
服务	`registerService`	后台服务
上下文引擎	`registerContextEngine`	替代默认上下文管理

8.2 插件发现与加载

sequenceDiagram    participant GW as Gateway    participant DS as 发现系统    participant MF as 清单读取    participant VL as 验证器    participant LD as 加载器    participant RG as 注册表    GW->>DS: 扫描插件路径    DS-->>GW: 候选插件列表    loop 每个候选插件      GW->>MF: 读取 openclaw.plugin.json      MF-->>GW: 清单元数据      GW->>VL: 验证入口文件      VL-->>GW: 安全检查通过      GW->>LD: jiti 加载 TS/JS      LD-->>GW: 插件模块      GW->>RG: 调用 register(api)      RG-->>GW: 注册成功    end

插件目录结构：

my-plugin/├── package.json├── openclaw.plugin.json    # 插件清单├── src/│   └── index.ts           # 入口文件├── skills/                # 可选技能│   └── my-skill/│       └── SKILL.md└── README.md

openclaw.plugin.json：

{"id": "my-plugin","name": "My Plugin","version": "1.0.0","openclaw": {"extensions": ["./src/index.ts"],"channel": {"id": "mychannel","label": "My Channel","docsPath": "/channels/mychannel"    },"configSchema": {"type": "object","properties": {"apiKey": { "type": "string" }      }    },"uiHints": {"apiKey": { "label": "API Key", "sensitive": true }    }  }}

8.3 插件配置管理

{  plugins: {    enabled: true,           // 主开关    allow: ["voice-call"],   // 允许列表（id 基础）    deny: ["untrusted"],     // 拒绝列表    load: {      paths: ["~/plugins/custom"]  // 额外路径    },    slots: {      memory: "memory-core",      // 独占槽位      contextEngine: "legacy"    },    entries: {      "voice-call": {        enabled: true,        config: {          provider: "twilio",          accountSid: "${TWILIO_SID}"        }      }    }  }}

8.4 插件钩子系统

生命周期钩子：

api.on("before_prompt_build", (event, ctx) => {return {    prependSystemContext: "Follow company style guide.",    prependContext: `Current user: ${ctx.senderId}`  };});api.on("after_tool_call", (event, ctx) => {// 记录工具调用审计日志  logToolCall(ctx.toolName, ctx.result);});api.on("session_start", (event, ctx) => {// 初始化会话状态  initializeSessionState(ctx.sessionKey);});

钩子执行顺序：

before_model_resolve（最高优先级）
before_prompt_build
before_agent_start（遗留兼容）
before_tool_call
after_tool_call
agent_end
session_end

9. 安全模型与信任边界

9.1 个人助手信任模型

核心假设：

┌────────────────────────────────────────────────────────────┐│           OpenClaw 信任模型声明                              │├────────────────────────────────────────────────────────────┤│                                                            ││  ✅ 支持：单一可信操作员边界                                 ││     - 一个用户/信任边界 per Gateway                         ││     - 推荐：一个 OS 用户/主机/VPS per 信任边界               ││                                                            ││  ❌ 不支持：敌对多租户隔离                                   ││     - 多个互不信任的用户共享一个 Gateway                     ││     - 共享 Gateway + 凭证的对抗性用户场景                    ││                                                            ││  ⚠️  如需多用户隔离：                                        ││     - 拆分信任边界（独立 Gateway + 凭证）                    ││     - 理想情况：独立 OS 用户/主机                           ││                                                            │└────────────────────────────────────────────────────────────┘

实际含义：

经过认证的 Gateway 操作员是可信控制平面角色
sessionKey 是路由选择器，不是用户认证令牌
操作员可以访问所有会话元数据/历史（设计如此）
如需对抗性用户隔离，必须运行独立 Gateway

9.2 认证与授权

Gateway 认证模式：

模式	配置	用途
Token	`gateway.auth.mode: "token"`	推荐，共享令牌
Password	`gateway.auth.mode: "password"`	密码认证
Trusted Proxy	`gateway.auth.mode: "trusted-proxy"`	反向代理认证
None	`gateway.auth.mode: "none"`	❌ 不推荐

设备配对：

新设备需要配对审批
本地回环连接自动批准
配对码 1 小时过期
每通道最多 3 个待处理请求

配对审批流程：

sequenceDiagram    participant NewDevice as 新设备    participant GW as Gateway    participant Owner as 操作员    NewDevice->>GW: connect (未配对设备)    GW->>GW: 检查配对状态    GW-->>NewDevice: 返回配对码 (1 小时有效)    Note over Owner: 收到配对通知    Owner->>GW: openclaw pairing approve <code>    GW->>GW: 验证配对码    GW->>GW: 生成设备令牌    GW-->>NewDevice: 配对成功 (后续连接使用设备令牌)

9.3 入站访问控制

DM 策略：

{  channels: {    whatsapp: {      dmPolicy: "pairing"  // pairing | allowlist | open | disabled    },    telegram: {      dmPolicy: "allowlist",      allowFrom: ["tg:123456789", "tg:987654321"]    }  }}

群组策略：

{  channels: {    whatsapp: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15551234567"],      groups: {        "120363@g.us": {          requireMention: true,          allowFrom: ["+15551234567"]        }      }    },    discord: {      guilds: {        "123456789": {          channels: {            "987654321": { allow: true, requireMention: true }          }        }      }    }  }}

9.4 安全审计清单

运行 openclaw security audit 检查常见配置问题：

关键检查项：

Check ID	严重性	说明
`fs.state_dir.perms_world_writable`	critical	状态目录可写
`gateway.bind_no_auth`	critical	远程绑定无认证
`gateway.tailscale_funnel`	critical	Tailscale Funnel 暴露
`security.exposure.open_groups_with_elevated`	critical	开放群组 + 提升工具
`sandbox.dangerous_network_mode`	critical	沙箱危险网络模式
`tools.exec.host_sandbox_no_sandbox_defaults`	warn	沙箱关闭但配置为沙箱

修复命令：

# 运行审计openclaw security audit# 深度审计（包含实时 Gateway 探测）openclaw security audit --deep# 自动修复openclaw security audit --fix# JSON 输出（用于自动化）openclaw security audit --json

10. 消息流转完整生命周期

10.1 入站消息处理

sequenceDiagram    participant Channel as 消息通道    participant Monitor as 通道监控器    participant Router as 路由引擎    participant Auth as 认证检查    participant Queue as 消息队列    participant Agent as AI 代理    participant Reply as 回复交付    Channel->>Monitor: 入站消息事件    Monitor->>Monitor: 解析消息元数据    Monitor->>Auth: 检查 DM/群组策略    alt 未授权      Auth-->>Monitor: 拒绝      Monitor-->>Channel: 忽略或返回配对码    else 已授权      Auth-->>Monitor: 允许    end    Monitor->>Router: 解析路由键    Router->>Router: 匹配 bindings    Router-->>Monitor: 目标 agentId + sessionKey    Monitor->>Queue: 入队消息    Queue->>Agent: 触发代理运行    Agent->>Agent: 加载会话上下文    Agent->>Agent: 构建提示词    Agent->>Agent: 调用 LLM    Agent->>Agent: 执行工具调用    Agent->>Reply: 返回响应    Reply->>Channel: 发送消息    Reply-->>Monitor: 更新会话状态

10.2 出站消息交付

graph TB    subgraph "消息来源"        S1[AI 代理响应]        S2[工具调用结果]        S3[Cron 作业]        S4[Hook 触发]    end    subgraph "交付管道"        D1[消息格式化]        D2[通道选择]        D3[目标解析]        D4[分块处理]        D5[发送执行]    end    subgraph "交付确认"        A1[成功确认]        A2[失败重试]        A3[队列隔离]    end    S1 --> D1    S2 --> D1    S3 --> D1    S4 --> D1    D1 --> D2 --> D3 --> D4 --> D5    D5 --> A1    D5 --> A2    D5 --> A3    style D1 fill:#e3f2fd    style D5 fill:#e8f5e9    style A1 fill:#c8e6c9    style A2 fill:#ffcdd2

10.3 流式响应处理

流式模式：

off：无流式，等待完整响应
partial：单预览消息，实时更新
block：分块预览，追加式更新
progress：进度预览 + 最终答案

通道流式支持：

通道	off	partial	block	progress
Telegram	✅	✅	✅	→ partial
Discord	✅	✅	✅	→ partial
Slack	✅	✅	✅	✅
WhatsApp	✅	❌	❌	❌

分块配置：

{  agents: {    defaults: {      blockStreamingDefault: "on",      blockStreamingBreak: "text_end",  // text_end | message_end      blockStreamingChunk: {        minChars: 500,        maxChars: 2000,        breakPreference: "paragraph"      },      blockStreamingCoalesce: {        minChars: 1500,        maxChars: 4000,        idleMs: 500      }    }  },  channels: {    telegram: {      streaming: "partial",      textChunkLimit: 4096    },    discord: {      streaming: "block",      maxLinesPerMessage: 17    }  }}

11. 版本演进与优化路径

11.1 版本历史概览

基于 CHANGELOG.md 分析关键版本演进：

版本	日期	关键特性
2026.3.13	最新	Control UI v2, Fast Mode, 安全加固
2026.3.12	-	Dashboard v2, Ollama 集成，安全修复
2026.3.11	-	多模态记忆，Gemini Embedding 2
2026.3.8	-	备份系统，Talk Mode，混合搜索
2026.3.7	-	上下文引擎插件，ACP 线程绑定
2026.3.2	-	SecretRef 全覆盖，PDF 工具，多账号路由
2026.3.1	-	OpenAI WebSocket, ACP 持久化
2026.2.26	-	外部密钥管理，ACP 线程代理
2026.2.25	-	Android 节点增强，安全审计
2026.2.24	-	中止快捷键，Talk 配置
2026.2.23	-	KiloCode 提供商，视频理解
2026.2.22	-	插件工具目录，Gemini Web 搜索

11.2 关键架构演进

2026.3.x 系列优化：

Control UI 重构

模块化仪表板（概览/聊天/配置/代理/会话）
命令面板支持
移动端底部标签导航
聊天工具增强（斜杠命令/搜索/导出/置顶）

Fast Mode 支持

OpenAI GPT-5.4 Fast Mode
Anthropic Claude Fast Mode
每会话快速切换 (/fast)

安全加固

设备配对单重设置码
插件工作空间自动加载禁用
Exec 审批边界强化
SSRF 防护增强

记忆系统增强

多模态记忆（图片/音频）
Gemini Embedding 2 支持
混合搜索（BM25 + 向量）
MMR 重排序（多样性）
时间衰减（近期优先）

2026.2.x 系列优化：

多账号路由

通道级默认账号配置
账号级绑定升级
跨账号隔离强化

ACP 集成

线程绑定代理
持久化通道绑定
ACPX 流式优化

沙箱增强

每代理沙箱配置
自定义绑定挂载
浏览器沙箱隔离

11.3 性能优化路径

启动时间优化：

插件发现缓存
懒加载运行时边界
编译缓存启用
快速路径启动（--version, --help）

内存优化：

低内存主机并行工作线程分级
插件 SDK 子路径导入
会话引导缓存失效优化

网络优化：

代理感知调度器
IPv4 回退机制
连接池复用

12. 生产环境部署指南

12.1 安全基线配置

{  // 网络绑定：仅本地回环  gateway: {    mode: "local",    bind: "loopback",    port: 18789,    auth: {      mode: "token",      token: "${GATEWAY_TOKEN}"  // 长随机令牌    }  },  // 会话隔离  session: {    dmScope: "per-channel-peer"  // 多用户场景  },  // 工具策略：最小权限  tools: {    profile: "messaging",    deny: ["gateway", "cron", "sessions_spawn", "sessions_send"],    fs: { workspaceOnly: true },    exec: {      security: "deny",      ask: "always"    },    elevated: { enabled: false }  },  // 通道策略：严格准入  channels: {    whatsapp: {      dmPolicy: "pairing",      groups: { "*": { requireMention: true } }    },    telegram: {      dmPolicy: "pairing",      groups: { "*": { requireMention: true } }    }  },  // 沙箱：非主会话启用  agents: {    defaults: {      sandbox: {        mode: "non-main",        scope: "agent",        workspaceAccess: "none"      }    }  }}

12.2 Docker 部署

docker-compose.yml：

version:'3.8'services:openclaw-gateway:image:ghcr.io/openclaw/openclaw:latestcontainer_name:openclawrestart:unless-stoppedports:-"127.0.0.1:18789:18789"# 仅本地回环volumes:-./config:/app/config:ro-./state:/home/node/.openclaw-./workspace:/app/workspaceenvironment:-OPENCLAW_GATEWAY_TOKEN=${GATEWAY_TOKEN}-OPENCLAW_SANDBOX=1# 启用沙箱networks:-openclaw-netsecurity_opt:-no-new-privileges:truecap_drop:-NET_RAW-NET_ADMINnetworks:openclaw-net:driver:bridge

部署步骤：

# 1. 创建目录结构mkdir -p openclaw/{config,state,workspace}# 2. 生成令牌openssl rand -hex 32 > .env# 3. 启动服务docker compose up -d# 4. 验证状态docker compose logs -f openclaw# 5. 配置通道docker compose exec openclaw openclaw channels login

12.3 Tailscale 远程访问

推荐方案：Tailscale Serve

# 1. 安装 Tailscalecurl -fsSL https://tailscale.com/install.sh | sh# 2. 认证tailscale up# 3. 配置 Servetailscale serve https / http://127.0.0.1:18789# 4. 获取访问 URLtailscale status

Gateway 配置：

{  gateway: {    bind: "loopback",    auth: {      mode: "token",      allowTailscale: true  // 允许 Tailscale 身份头    },    tailscale: {      mode: "serve"  // serve | funnel    }  }}

12.4 监控与日志

日志配置：

{  logging: {    level: "info",  // debug | info | warn | error    format: "pretty",  // pretty | json    file: "/tmp/openclaw/openclaw.log",    maxFileBytes: "500mb",  // 单文件上限    redactSensitive: "tools"  // 脱敏级别  }}

健康检查：

# WebSocket 健康检查openclaw gateway status# 深度检查（包含通道探测）openclaw gateway status --deep# JSON 输出（用于监控）openclaw gateway status --json

Prometheus 指标（通过插件）：

openclaw_gateway_up：Gateway 状态
openclaw_sessions_active：活跃会话数
openclaw_messages_total：消息计数
openclaw_tools_calls_total：工具调用计数

13. 总结与展望

13.1 架构优势

OpenClaw 的核心优势：

统一网关架构

单一进程管理所有通道
避免多进程状态同步复杂性
简化部署和运维

灵活的代理路由

多代理隔离运行
精确的绑定匹配系统
每代理独立配置

强大的扩展性

插件化架构
技能系统
自定义工具/通道

安全优先设计

默认安全配置
沙箱执行
细粒度访问控制

生产级可靠性

会话持久化
自动维护
故障恢复

13.2 适用场景

推荐使用：

✅ 个人 AI 助手（单用户）
✅ 小团队协作（共享信任边界）
✅ 开发/测试环境
✅ 研究/实验项目

不推荐使用：

❌ 敌对多租户 SaaS
❌ 公共 AI 服务（无信任边界）
❌ 高安全性要求场景（需额外加固）

13.3 学习资源

官方文档：

https://docs.openclaw.ai
https://github.com/openclaw/openclaw

社区：

Discord: https://discord.com/invite/clawd
ClawHub（技能市场）: https://clawhub.com

附录 A：术语表

术语	定义
Gateway	OpenClaw 核心网关进程，管理所有通道和代理
Channel	消息通道适配器（飞书、WhatsApp、Telegram 等）
Agent	AI 代理实例，有独立工作区和会话
Session	会话状态单元，包含上下文和历史
Binding	消息路由规则，匹配入站消息到代理
Tool	内置函数，代理可调用的能力
Skill	AgentSkills 兼容的 Markdown 指令文件
Plugin	扩展模块，注册工具/通道/RPC 等
Sandbox	Docker 容器隔离的执行环境
SecretRef	凭证引用机制，支持 env/file/exec 源

附录 B：常见问题 (FAQ)

Q: OpenClaw 与 LangChain/LlamaIndex 有何不同？

A: OpenClaw 是消息网关，专注于连接消息平台与 AI 代理。LangChain/LlamaIndex 是应用框架，用于构建 AI 工作流。两者可以互补使用。

Q: 如何备份 OpenClaw 数据？

A: 备份 ~/.openclaw/ 目录（或 $OPENCLAW_STATE_DIR）。关键数据：

openclaw.json：配置
agents/*/sessions/：会话转录
credentials/：通道凭证
agents/*/agent/auth-profiles.json：模型凭证

Q: 如何迁移到新版本？

# npm 全局安装npm update -g openclaw# 重启 Gatewayopenclaw gateway restart# 验证版本openclaw --version

Q: 生产环境需要哪些监控？

A: 至少监控：

Gateway 进程状态
WebSocket 连接数
通道健康状态
磁盘使用率（会话存储）
错误日志频率

建议收藏 + 慢慢啃，信息量略大。 🦞

#Openclaw #go后端开发 #龙虾

🌟 技术之路，贵在坚持

欢迎 点赞 · 在看 · 分享