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 控制平面
它更接近一个 消息驱动的自动化系统入口。
对于测试、测开、平台工程团队来说，这类系统的关键不在模型能力，而在于：
- 如何控制入口
- 如何隔离会话
- 如何限制执行边界
这些问题，才是真正落到工程现场时需要面对的部分。
