OpenClaw 原理详解：自托管 AI 网关架构深度剖析

摘要：OpenClaw 是一个自托管的多渠道 AI 代理网关，它将 WhatsApp、Telegram、Discord、iMessage 等聊天应用与 AI 编码代理（如 Pi）连接起来。本文将深入解析其架构设计、核心组件、会话管理和工具系统。

---

一、什么是 OpenClaw？

OpenClaw 🦞 是一个自托管网关，运行在你的机器（或服务器）上，作为聊天应用和 AI 助手之间的桥梁。它的核心理念是：无需放弃数据控制权，无需依赖托管服务，就能拥有一个随时待命的个人 AI 助手。

核心特点

• 自托管：运行在你的硬件上，你的规则
• 多渠道：一个网关进程同时服务 WhatsApp、Telegram、Discord 等
• 代理原生：为编码代理构建，支持工具使用、会话、记忆和多代理路由
• 开源：MIT 许可，社区驱动

适用人群

开发者和高级用户，希望从任何地方通过消息应用与个人 AI 助手交互，同时保持对数据和隐私的完全控制。

---

二、整体架构

OpenClaw 的架构设计遵循单一网关、多客户端、多节点的模式：

核心组件

组件	职责	连接方式
Gateway（网关）	维护所有消息渠道连接，暴露 WebSocket API，管理会话和路由	WebSocket (18789 端口)
Channels（渠道）	WhatsApp (Baileys)、Telegram (grammY)、Discord (discord.js) 等	各自协议
Clients（客户端）	macOS 应用、CLI、Web 管理界面	WebSocket
Nodes（节点）	iOS/Android/桌面节点，提供 Canvas、相机、屏幕录制等功能	WebSocket (role: node)
Agent（代理）	嵌入的 Pi 代理运行时，处理用户请求和工具调用	内部 RPC

---

三、网关工作原理

3.1 连接生命周期

所有客户端（包括渠道、控制客户端和节点）通过 WebSocket 连接到网关：

3.2 协议细节

• 传输层：WebSocket，JSON 文本帧
• 首帧要求：必须是 connect 握手帧
• 请求格式：{type:"req", id, method, params}
• 响应格式：{type:"res", id, ok, payload|error}
• 事件推送：{type:"event", event, payload, seq}

3.3 认证与配对

• 网关令牌：通过 OPENCLAW_GATEWAY_TOKEN 或 --token 设置
• 设备配对：新设备需要配对批准，网关颁发设备令牌
• 本地信任：环回地址或同一 Tailscale 网络的连接可自动批准
• 签名挑战：所有连接必须签名 connect.challenge nonce

---

四、会话管理系统

4.1 会话键设计

OpenClaw 使用分层会话键来隔离不同场景的对话上下文：

agent:<agentId>:<channel>:<type>:<id>

会话类型	键格式	说明
直接消息 (默认)	agent:main:main	所有 DM 共享主会话
直接消息 (隔离)	agent:main:whatsapp:dm:+15555550123	按渠道 + 发送者隔离
群聊	agent:main:whatsapp:group:<groupId>	每个群组独立会话
Telegram 话题	agent:main:telegram:group:<groupId>-topic:<threadId>	话题隔离
Cron 任务	cron:<jobId>	隔离的自动化任务

4.2 会话重置策略

{
  session: {
    reset: {
      mode: "daily",      // 每日重置
      atHour: 4,          // 凌晨 4 点
      idleMinutes: 120,   // 或 120 分钟空闲后重置
    },
    dmScope: "per-channel-peer", // 推荐：按渠道 + 发送者隔离
  }
}

4.3 会话存储

• 会话元数据：~/.openclaw/agents/<agentId>/sessions/sessions.json
• 对话记录：~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl
• 维护策略：自动修剪旧会话、归档转录文件、轮转存储

---

五、工具系统

OpenClaw 为 AI 代理提供第一类工具，无需 shell 调用，类型安全：

5.1 核心工具组

工具组	包含工具	用途
group:fs	read, write, edit, apply_patch	文件操作
group:runtime	exec, bash, process	命令执行
group:sessions	sessions_list, sessions_history, sessions_send	会话管理
group:memory	memory_search, memory_get	记忆检索
group:web	web_search, web_fetch	网络搜索
group:ui	browser, canvas	浏览器和画布自动化
group:messaging	message	消息发送
group:nodes	nodes	节点控制

5.2 工具策略

{
  tools: {
    profile: "coding",  // 基础配置：coding | messaging | minimal | full
    allow: ["group:fs", "browser"],  // 白名单
    deny: ["group:runtime"],         // 黑名单（优先）
    byProvider: {
      "google-antigravity": { profile: "minimal" },  // 按提供商限制
    },
  }
}

5.3 浏览器自动化流程

流程说明：开始 → 检查状态 → 启动浏览器（如未运行）→ 页面快照 → 执行操作（点击/输入）→ 可选截图确认 → 完成

---

六、多代理路由

OpenClaw 支持运行多个隔离的代理，每个代理有独立的工作空间和会话：

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

路由匹配流程

流程说明：收到消息 → 检查绑定规则 → 匹配渠道/账户（或使用默认代理）→ 路由到对应代理 → 加载工作空间 → 注入配置文件 → 代理响应

---

七、工作空间与记忆系统

7.1 工作空间文件

每个代理工作空间包含以下核心文件：

文件	用途
AGENTS.md	操作指令和"记忆"
SOUL.md	人格、边界、语气
TOOLS.md	用户维护的工具笔记
BOOTSTRAP.md	一次性首次运行仪式（完成后删除）
IDENTITY.md	代理名称/氛围/表情符号
USER.md	用户档案和偏好

7.2 记忆持久化

---

八、安全与权限

8.1 DM 访问控制

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",    // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true },  // 群聊需要@提及
      },
    },
  },
}

8.2 沙箱隔离

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}

8.3 工具权限

• 执行批准：exec 命令可配置为需要用户批准
• 工作空间限制：apply_patch 默认仅限工作空间内
• 提升权限：elevated 模式需要显式配置

---

九、自动化能力

9.1 心跳检查

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",  // last | whatsapp | telegram | discord | none
      },
    },
  },
}

9.2 Cron 任务

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
  },
}

9.3 Webhooks

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}

---

十、配置热重载

OpenClaw 支持配置热重载，无需手动重启：

{
  gateway: {
    reload: { mode: "hybrid" },  // hybrid | hot | restart | off
  },
}

模式	行为
hybrid (默认)	安全更改立即生效，关键更改自动重启
hot	仅热应用安全更改，需要重启时记录警告
restart	任何更改都重启网关
off	禁用文件监视，手动重启生效

---

十一、快速开始

11.1 安装

npm install -g openclaw@latest

11.2 初始化

openclaw onboard --install-daemon

11.3 配置渠道

openclaw channels login  # WhatsApp 配对

11.4 启动网关

openclaw gateway --port 18789

11.5 打开控制 UI

访问 http://127.0.0.1:18789

---

十二、总结

OpenClaw 的核心创新在于：

1. 统一网关架构：一个进程服务所有渠道，简化部署和维护
2. 会话隔离：灵活的会话键设计，支持多用户、多场景隔离
3. 工具系统：类型安全的内置工具，无需 shell 调用
4. 自托管优先：数据完全掌控，隐私有保障
5. 扩展性强：插件系统支持自定义渠道和工具

对于希望构建个人 AI 助手的开发者来说，OpenClaw 提供了一个开箱即用、高度可定制的基础架构。无论是简单的消息回复机器人，还是复杂的多代理协作系统，OpenClaw 都能胜任。

---

参考资源：

• 官方文档：https://docs.openclaw.ai
• GitHub: https://github.com/openclaw/openclaw
• 社区：https://discord.com/invite/clawd
• 技能市场：https://clawhub.com

---

本文基于 OpenClaw v2026.2.26 编写，架构和特性可能随版本更新而变化。
对了，本文的markdown文件是由openclaw直接生成的…