OpenClaw 中文文档 — 简介概览

近期在评估自托管 AI Agent 接入方案时，OpenClaw 是一个值得关注的项目。它的定位比较明确：不做 AI 模型本身，而是做聊天平台与 AI Agent 之间的网关层。

从架构层面来看，这个思路有一定道理——把"渠道接入"和"Agent 逻辑"解耦，中间用一个统一的 Gateway 来调度，各渠道只需对接一次。实测下来，这个项目的完成度比我预期的要高。

本文基于官方文档和实际部署，对 OpenClaw 的定位、架构和核心功能做一个系统性的梳理。

项目定位

OpenClaw 是一个开源（MIT 许可）的自托管跨渠道 AI Agent 网关。

核心做的事情是：在用户自有的机器上运行一个 Gateway 进程，统一连接 WhatsApp、Telegram、Discord、iMessage 等聊天应用，将消息转发给后端的 AI Agent（如 Pi）处理，再把回复推回聊天应用。

相比于直接在某个平台上做一个聊天机器人，OpenClaw 的设计决策有几个值得注意的点：

自托管：Gateway 运行在用户自己的硬件上，消息数据不经过第三方服务
多渠道统一：单一 Gateway 进程同时服务多个聊天平台，Agent 逻辑与渠道解耦
Agent 原生：不是简单的消息转发，原生支持工具调用、会话管理、记忆持久化和多 Agent 路由
社区驱动：MIT 开源，插件机制支持社区扩展

这个设计决策背后的考量应该是：聊天平台是用户最高频使用的工具，把 AI 能力注入到这些已有平台中，比让用户去适应一个新的 AI 入口要更自然。

系统架构

OpenClaw 采用以 Gateway 为中心的星型架构：

聊天渠道层
├── WhatsApp（Baileys / WhatsApp Web 协议）
├── Telegram（grammY 框架）
├── Discord（discord.js）
├── iMessage（本地 imsg CLI，仅 macOS）
└── Mattermost 等（插件机制）
        │
        ▼
  Gateway（核心进程）
  ├── 消息路由与会话管理
  ├── Agent 调度（RPC 模式）
  ├── WebSocket API（类型化，JSON Schema 校验）
  └── 媒体处理（图片/音频/文档）
        │
        ▼
  客户端与节点层
  ├── CLI
  ├── Web 控制面板（浏览器 UI）
  ├── macOS 菜单栏应用
  └── iOS / Android 节点（Canvas、相机、语音）

值得注意的是，Gateway 是整个系统的 Single Source of Truth。所有会话状态、路由规则、渠道连接都由 Gateway 维护。客户端和移动端节点均通过 WebSocket 连接到 Gateway，协议层做了 JSON Schema 校验，这在开源项目中算是比较规范的做法。

每台主机只运行一个 Gateway 实例，它也是唯一打开 WhatsApp Web 会话的进程——这个约束简化了会话一致性的问题。

核心功能

渠道支持

渠道	集成方式	备注
WhatsApp	Baileys（Web 协议）	链接设备模式，需扫码配对
Telegram	grammY 框架	Bot API
Discord	discord.js	Bot 方式接入
iMessage	本地 imsg CLI	仅 macOS
Mattermost 等	插件机制	社区贡献

消息与会话

多 Agent 路由：按工作区或发送者隔离会话，不同场景分配不同 Agent
流式输出：长回复分块推送，用户端体验流畅
会话管理：私聊合并到共享会话，群组独立隔离
媒体处理：图片、音频、文档的收发，支持语音转录

管理与控制

Web 控制面板：浏览器端管理聊天、配置、会话和节点状态
CLI 工具链：完整的命令行管理工具
移动端节点：iOS/Android 设备配对，支持 Canvas、相机、屏幕录制、定位等设备能力

环境要求与快速部署

系统要求

Node 24（推荐）或 Node 22 LTS（22.16+）
macOS、Linux 或 Windows（Windows 推荐 WSL2 环境）

部署流程

# 1. 安装（macOS/Linux/WSL2）
curl -fsSL https://openclaw.ai/install.sh | bash

# 2. 运行引导向导
openclaw onboard --install-daemon

# 3. 配对 WhatsApp
openclaw channels login

# 4. 启动 Gateway
openclaw gateway --port 18789

# 5. 验证
openclaw dashboard

Windows 环境可通过 PowerShell 安装：

iwr -useb https://openclaw.ai/install.ps1 | iex

Gateway 启动后，访问 http://127.0.0.1:18789/ 进入 Web 控制面板。

基础配置

配置文件路径：~/.openclaw/openclaw.json

默认配置即可运行。生产环境建议至少配置访问白名单：

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

相比于不做任何限制，这个配置至少解决了两个问题：一是限制了谁能触发 Agent（控制 API 调用成本），二是群聊中要求 @提及才会响应（避免噪音）。

小结

从架构设计来看，OpenClaw 做了一个比较清晰的抽象——渠道层、网关层、Agent 层各司其职。对于需要在多个聊天平台接入 AI 能力的场景，这个方案值得评估。

本文是 OpenClaw 中文文档系列的第一篇，后续会按模块逐篇展开，覆盖安装部署、渠道配置、Gateway 管理、安全设置等内容。

完整中文文档：OpenClaw 中文文档

GitHub 仓库：openclaw/openclaw

posted @ 2026-03-23 15:10 wakeupxm 阅读(2) 评论(0) 收藏举报

刷新页面返回顶部

openclaws