深入OpenClaw网关：架构、网络模型与运行机制全解析

OpenClaw 是一个用于将即时通信渠道与编程智能体连接起来的 Gateway 网关系统。 它本身不提供模型能力，而是作为 消息入口、控制平面与节点协调中心 存在。

它更接近一个长期运行的 Agent 基础设施组件。

一、系统组成与工作原理

OpenClaw 的整体工作结构可以抽象为一条清晰的控制与执行链路：

WhatsApp / Telegram / Discord / iMessage（+ 插件）
        │
        ▼
  ┌───────────────────────────┐
  │       Gateway 网关        │  ws://127.0.0.1:18789（仅 loopback）
  │      （单一来源）          │
  │                           │  http://<gateway-host>:18793
  │                           │    /__openclaw__/canvas/（Canvas 主机）
  └───────────┬───────────────┘
              │
              ├─ Pi 智能体（RPC）
              ├─ CLI（openclaw …）
              ├─ 聊天 UI（SwiftUI）
              ├─ macOS 应用（OpenClaw.app）
              ├─ iOS 节点（Gateway WS + 配对）
              └─ Android 节点（Gateway WS + 配对）

所有消息首先进入 Gateway 网关，由其统一完成：

• 渠道协议适配
• 会话与上下文管理
• RPC 调度至 Pi 智能体
• 响应回传

Gateway 是系统中的单一事实源（Single Source of Truth）。

二、Gateway 网关进程模型

openclaw gateway 是一个长期运行的单进程服务，承担以下职责：

• 维护所有消息渠道连接
• 暴露 WebSocket 控制平面
• 管理节点、会话与 Canvas
• 作为 CLI、UI、移动节点的统一入口

这意味着它在工程上同时是：

• 状态中心
• 调度中心
• 安全边界集中点

任何系统级问题，最终都会回到 Gateway。

三、网络模型与连接策略

OpenClaw 官方推荐的部署模型是：

每台主机一个 Gateway 网关

原因非常明确：

• WhatsApp Web 会话只能安全地被单一进程持有
• Gateway 本身维护关键运行状态
• 多 Gateway 场景必须做到强隔离

关键网络策略包括：

• WebSocket 默认仅绑定 loopback

• ws://127.0.0.1:18789

• 向导默认生成 Gateway token（即便是 loopback）

• 非 loopback 绑定（如 tailnet）必须显式携带 token

• openclaw gateway --bind tailnet --token ...

节点（iOS / Android / UI）通过 WebSocket 连接 Gateway，可经由：

• LAN
• Tailnet
• SSH 隧道

旧版 TCP 桥接已被弃用。

四、Canvas Host 与节点模型

Gateway 同时承担 Canvas Host 职责：

• 默认端口：18793
• 提供 HTTP 文件服务
• 路径：/__openclaw__/canvas/

Canvas 用于为节点 WebView 提供界面能力：

• WebChat
• iOS 节点
• Android 节点

节点并不直接暴露业务逻辑，而是通过 Gateway 统一调度。

五、功能能力概览（系统层面）

OpenClaw 提供的能力主要集中在“接入、路由、控制”层：

• WhatsApp 集成（Baileys，WhatsApp Web 协议）
• Telegram 机器人（grammY，私聊 + 群组）
• Discord 机器人（channels.discord.js）
• Mattermost 机器人（插件，Bot API + WebSocket）
• iMessage（macOS 本地 imsg CLI）

在智能体侧：

• Pi 智能体（RPC 模式，唯一编程智能体路径）
• 支持工具调用与流式传输
• 分块流式响应（含 Telegram 草稿流）

在会话与路由层：

• 私聊折叠到共享 main 会话（默认）
• 群聊默认隔离
• 基于提及的群激活策略
• 多智能体路由（工作区 + 每智能体会话）

在多端体验层：

• WebChat
• macOS 应用
• iOS 节点（Canvas）
• Android 节点（Canvas + 聊天 + 相机）

旧版 Claude / Codex / Gemini / Opencode 路径已移除，仅保留 Pi。

六、快速开始与运行方式

运行环境要求：

• Node.js ≥ 22

推荐通过全局安装与新手引导完成部署：

npm install -g openclaw@latest
# 或
pnpm add -g openclaw@latest

openclaw onboard --install-daemon

向导会完成：

• Gateway 服务注册（launchd / systemd）
• 基础配置初始化
• token 与端口设置

WhatsApp Web 配对：

openclaw channels login

如需手动运行 Gateway：

openclaw gateway --port 18789

七、多实例与测试运行

在需要隔离或多 Gateway 场景下，可通过环境变量启动多个实例：

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001

发送测试消息（需 Gateway 运行中）：

openclaw message send \
  --target +15555550123 \
  --message "Hello from OpenClaw"

八、配置模型与访问控制

默认配置文件位于：

~/.openclaw/openclaw.json

如果不做任何配置，系统将：

• 使用内置 Pi 二进制
• 按发送者维度维护会话

更常见的工程实践是先限制入口，例如 WhatsApp 来源控制：

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15555550123"],
      "groups": { "*": { "requireMention": true } }
    }
  },
  "messages": {
    "groupChat": {
      "mentionPatterns": ["@openclaw"]
    }
  }
}

这些配置本质上是访问控制与风险收敛策略，而不是功能开关。

九、系统性质与工程含义

OpenClaw 的设计目标并不是构建一个“更聪明的聊天工具”，而是提供一套：

• 明确的 Gateway 架构
• 可控的网络模型
• 可运维的 Agent 控制平面

它更接近一个 消息驱动的自动化系统入口。

对于测试、测开、平台工程团队来说，这类系统的关键不在模型能力，而在于：

• 如何控制入口
• 如何隔离会话
• 如何限制执行边界

这些问题，才是真正落到工程现场时需要面对的部分。