OpenClaw 技术深度解析

一个连接 20+ 聊天平台的自托管 AI 代理网关——让个人大模型真正动手做事

OpenClaw 是一款开源的个人 AI 助手框架，它通过统一的 Gateway 网关将 WhatsApp、Telegram、Discord、iMessage、Slack 等主流聊天工具接入大语言模型，并赋予代理执行实际任务的能力。与一般的聊天机器人不同，OpenClaw 让 AI 成为全天候在线的私人助理：它可以读取邮件、管理日历、操作文件、运行脚本，甚至替你值机。它以“任何操作系统、任何渠道、一个网关”的理念，为开发者提供了高度可定制、安全可控的 AI 代理基础设施。

本文将深入解析 OpenClaw 的核心架构、多智能体路由、安全模型和典型实践，帮助你理解这个被用户称为“早期 AGI 体验”的项目。

目录

项目背景与定位

随着大语言模型（LLM）能力的爆发，开发者开始探索如何让 AI 不仅仅停留在对话界面，而是真正融入日常工作流。传统做法是为每个聊天平台单独编写机器人接入代码，维护成本极高，且难以保证统一的上下文、权限和工具调用策略。OpenClaw 的诞生正是为了解决这一痛点。

项目的核心理念是 “随身携带的 AI 代理”——用户只需在自己的设备（或服务器）上运行一个 Gateway 进程，便可通过任意聊天 App 向 AI 发送指令，AI 可以访问本地文件、执行代码、调用外部 API，并将结果实时返回。它强调 自托管、持久化记忆 和 主动任务执行，让个人 AI 助手从被动问答走向主动代办。

用户社区的评价极具代表性：“这就像 ChatGPT 发布那一刻的震撼”“感觉像是早期的 AGI”——这些反馈不仅源于其强大的工具调用能力，更因为它将 AI 无缝嵌入到了人们最熟悉的通信工具中。

核心架构：Gateway 网关模式

OpenClaw 采用中心化的 Gateway 网关架构。Gateway 是整个系统的控制平面和策略中心，所有消息流量、身份认证、会话管理、工具权限均通过它进行调度。客户端（节点）可以运行在 macOS、Windows、Linux 甚至移动设备上，它们与 Gateway 保持长连接，接收远程指令并执行本地操作。

graph TD
    User[用户消息] -->|WhatsApp / Telegram / Discord / Slack...| Channels[渠道层]
    Channels -->|WebSocket / Webhook| Gateway[OpenClaw Gateway]
    Gateway -->|路由绑定| Router[多智能体路由器]
    Router --> Agent1[Agent A]
    Router --> Agent2[Agent B]
    Agent1 --> Tools[工具层]
    Agent2 --> Tools
    Tools -->|文件系统 / 网络 / 执行 / 浏览器| OS[操作系统]
    Gateway -->|远程命令| Node[移动 / 桌面节点]
    Node --> OS
    Gateway -->|API| ControlUI[Web 控制台 / macOS App]

Gateway 的核心职责包括：

  • 渠道适配：将不同聊天平台的 HTTP 请求或 WebSocket 消息统一转化为内部消息格式。
  • 身份与认证：通过 Token、配对流程等方式验证客户端和节点身份，确保只有受信设备可以接入。
  • 路由与绑定：根据配置的绑定规则将消息分发到正确的 Agent（多智能体场景下）。
  • 工具执行控制：定义哪些工具可用，并实施审批策略。
  • 会话存储：持久化所有对话历史，支持跨设备、跨会话的长程记忆。

Gateway 的配置采用 JSON5 格式，既保留了 JSON 的结构化，又支持注释等便利特性。下面是一个最小可运行配置示例：

{
  gateway: {
    mode: "local",
    bind: "loopback",
    auth: { mode: "token", token: "${OPENCLAW_GATEWAY_TOKEN}" }
  },
  tools: {
    profile: "messaging",
    fs: { workspaceOnly: true },
    exec: { security: "deny" }
  },
  channels: {
    telegram: { token: "${TELEGRAM_BOT_TOKEN}" },
    whatsapp: { dmPolicy: "pairing" }
  }
}

该配置将 Gateway 绑定在本地回环地址，仅允许持有 Token 的客户端连接；工具方面禁止代码执行，文件系统限制在工作区目录；频道只启用了 Telegram 和 WhatsApp，并对 WhatsApp 私聊实施了配对策略。

多渠道接入能力

OpenClaw 的渠道生态非常丰富，覆盖了几乎市面上所有主流的即时通讯和协作平台。官方将渠道分为三类：

  1. 内置渠道：直接编译进 Gateway，无需额外安装。包括 Discord、Google Chat、iMessage、IRC、Signal、Slack、Telegram、WebChat、WhatsApp 等。
  2. 捆绑插件渠道：随发行版打包的插件，一般单次启用即可使用。例如 Matrix、Microsoft Teams、Nextcloud Talk、Nostr、QQ Bot、Zalo、Feishu、LINE 等。
  3. 第三方渠道插件：社区或用户自行开发的插件，如 WeChat，以及通过 Voice Call 插件实现的语音通话能力。

下表列出了部分代表性渠道及其接入方式：

渠道类型接入方式特点
Telegram内置Bot Token双向通信，支持群聊和 inline mode
WhatsApp内置baileys 库（WebSocket）无需官方商业 API，支持多号码
Slack内置Webhook / Socket Mode支持工作空间绑定和 mention 触发
Discord内置Bot TokenGateway 连接，支持频道和私信
iMessage内置Apple Messages 桥接仅限 macOS 节点
Signal内置signal-cli 或 libsignal端到端加密，需注册号码
Matrix插件Homeserver URL联邦协议，适合企业内部
Microsoft Teams插件Bot Framework要求 Azure 注册，支持团队频道
QQ Bot插件OneBot 协议覆盖国内用户，与 QQ 机器人生态兼容
WeChat第三方多种实现社区驱动，非官方 API，需注意合规

所有渠道在 Gateway 内部被抽象为统一的 sendMessage 和 receiveMessage 语义，使得 Agent 不需要关心消息来自哪里。开发者只需在配置文件中声明要启用的渠道，并提供相应的认证凭证即可。例如，同时接入 Telegram、Discord 和 QQ Bot 的配置片段：

channels: {
  telegram: { token: "123456:ABC-DEF1234gh..." },
  discord: { token: "NDI...DSF.sdfl..." },
  "qq-bot": { connection: "ws://localhost:6700", accessToken: "abc" }
}

这种插件化、声明式的渠道管理方式，大大降低了为 AI 代理增加一个全新聊天平台的成本。

多智能体路由机制

OpenClaw 支持在同一个 Gateway 进程内运行多个 隔离的 Agent。每个 Agent 拥有独立的：

  • 工作区（workspace）：存放项目文件、个人笔记、固定指令（AGENTS.md, SOUL.md, USER.md 等）。
  • 状态目录（agentDir）：持久化认证信息、模型配置和 Agent 专属设置。
  • 会话存储：所有聊天历史，保存为 JSONL 文件。
  • 工具权限：每个 Agent 可以有不同的工具白名单和执行审批策略。

Agent 与渠道之间通过 绑定（binding） 建立关联。一个绑定映射了“某个渠道上的某个账户”到“某个 Agent”。例如，你的 WhatsApp 私人账号绑定到个人助理 Agent，而 Slack 工作空间的机器人则绑定到团队任务 Agent：

agents: [
  {
    id: "personal",
    workspace: "~/.openclaw/agents/personal/workspace",
    tools: { profile: "full", exec: { security: "ask" } }
  },
  {
    id: "work",
    workspace: "~/.openclaw/agents/work/workspace",
    tools: { profile: "messaging", exec: { security: "deny" } }
  }
],
bindings: [
  { agentId: "personal", channel: "whatsapp", account: "+1234567890" },
  { agentId: "work", channel: "slack", workspace: "T012345/B012345" }
]

当名为 “personal” 的 WhatsApp 号码收到消息时，Gateway 会自动将消息路由到 “personal” Agent；Slack 消息则路由到 “work” Agent。两个 Agent 的记忆、工具和文件系统完全隔离，互不干扰。

此外，路由还支持 基于会话上下文的动态路由：Gateway 会将消息的 sessionKey 与 Agent 的会话历史匹配，从而在群聊中区分不同对话上下文，保持上下文连贯性。会话键可以是 “频道+用户” 组合，也可以自定义。

安装与快速上手

OpenClaw 提供了多种安装方式，以适应不同操作系统和开发者习惯。

一键安装脚本

在 macOS、Linux 和 Windows (WSL/Git Bash) 上，可以直接使用官方安装脚本：

curl -fsSL https://openclaw.ai/install.sh | bash

脚本会自动检测环境，下载对应平台的预编译 Gateway 二进制文件，并完成基础配置。

npm 全局安装

如果你习惯使用 Node.js 生态，也可以从 npm 安装：

npm i -g openclaw

安装完成后，执行引导向导进行初始化：

openclaw onboard

onboard 命令会以交互方式询问所需的 AI 模型提供商、API 密钥、要启用的渠道、配对设备等，并自动生成配置文件。

源码构建

对于希望定制功能的开发者，可以从 GitHub 克隆仓库并基于 pnpm workspace 进行构建：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build

构建产物位于 packages/openclaw/dist，可直接运行。

验证安装

启动 Gateway 后，通过在终端执行 CLI 命令或打开 Web 控制台（默认 http://localhost:18700）来验证系统是否正常工作：

openclaw status
openclaw agent say "Hello, OpenClaw!" --agent personal

如果一切正常，你会在绑定的 Telegram/WhatsApp 上收到回复，并在控制台看到交互日志。

安全模型解读

由于 OpenClaw 被设计为能够执行文件操作、代码运行和网络访问的个人助理，安全是其架构中不可妥协的维度。官方明确定义其信任边界：一个 Gateway 实例假定只有一位可信操作员，不支持多租户或敌对用户共用同一网关的场景。

信任边界

  • Gateway 是控制平面，所有策略在此定义。
  • 节点（桌面/移动设备）是远程执行端，通过配对信任后，所有来自节点的动作都被视为操作员的自主行为。
  • 外部聊天平台用户需经过身份匹配（如 WhatsApp 号码验证）和 DM（私聊）策略确认，才能与 Agent 交互。

快速安全基线

官方推荐在启动前应用以下最小权限配置（此处精简展示）：

{
  gateway: { mode: "local", bind: "loopback", auth: { mode: "token", token: "..." } },
  session: { dmScope: "per-channel-peer" },
  tools: {
    profile: "messaging",
    deny: ["group:runtime", "group:fs", "sessions_spawn"],
    fs: { workspaceOnly: true },
    exec: { security: "deny" },
    elevated: { enabled: false }
  },
  channels: {
    whatsapp: { dmPolicy: "pairing", groups: { "*": { requireMention: true } } }
  }
}

关键点解释：

  • gateway.mode: "local" 和 bind: "loopback"：Gateway 只监听本地回环地址，杜绝局域网或公网暴露。
  • tools.fs.workspaceOnly: true：文件操作严格限制在工作区目录内，无法读/写系统敏感路径。
  • exec.security: "deny"：完全禁止代码执行，防止通过提示注入执行恶意命令。
  • channels.whatsapp.dmPolicy: "pairing"：WhatsApp 私聊需要先配对（即用户主动发起授权流程），防止陌生人直接向 Agent 发送指令。
  • groups.*.requireMention：群聊中仅在 @mention 机器人的情况下才响应，避免意外触发。

安全审计命令

OpenClaw 内置了 openclaw security audit 命令，可以自动巡检配置缺陷：

# 基础审计
openclaw security audit

# 深度探测（实时检测 Gateway 状态）
openclaw security audit --deep

# 自动修复可修复的误配置
openclaw security audit --fix

# 输出 JSON 格式结果，适合接入 CI/CD 管道
openclaw security audit --json

审计项目包括：入站访问策略是否合理、工具爆炸半径是否过大、代码执行是否有审批、浏览器控制是否暴露、文件系统权限等。建议开发者将审计脚本加入日常运维流程。

常见误区

  • 将 sessionKey 当作认证令牌：sessionKey 仅用于路由和上下文选择，不能作为用户身份凭证。
  • 假设单主机共享网关有多租户隔离：多用户共用一个 Gateway 时，需要按操作系统用户或容器进行分割。
  • 依赖模型自身的防护：始终应先控制 “谁能对话”，再限制 “Agent 能做什么”，最后才依赖模型的安全对齐。

典型使用场景

个人生活助理

通过 WhatsApp 或 Telegram 与 OpenClaw 代理对话，代理可以：

  • 阅读 Gmail 收件箱摘要，草拟邮件回复
  • 管理 Google Calendar 日程，自动创建会议
  • 通过网页自动化完成航班值机（利用内置无头浏览器工具）
  • 智能家居控制（通过 MQTT 插件）等

实际命令示例：

User: 明天上午有什么会议？
Agent: 9:00 设计评审，11:00 周会。需要我帮你准备评审材料吗？

软件团队协作

在 Slack 或 Microsoft Teams 中部署 OpenClaw 代理，绑定至团队工作 Agent。开发者可以：

  • 要求代理查看 GitHub PR 列表并进行初步代码审查
  • 触发自动化测试流水线
  • 查询 Sentry 错误日志并汇总报告
  • 定时提醒团队成员更新任务状态

利用多智能体功能，还可以为每个子项目设置独立的 Agent，权限隔离。

自动化运维

运维人员通过 IRC 或 Matrix 频道向 Agent 发出指令：

  • 服务器状态巡检
  • 日志异常告警
  • 灰度发布控制
  • 自愈脚本执行（需配合审批流程）

由于 Gateway 可以直接执行 shell 命令并返回结果，它相当于一个自然语言驱动的运维终端。

跨平台消息中继

即使不接入 AI 模型，Gateway 也可以作为消息路由中枢，将来自 QQ 的消息自动转发到 Telegram，或将 Slack 消息同步到 WhatsApp。通过插件机制，还能实现富媒体转换、翻译等功能。

总结与展望

OpenClaw 展示了个人 AI 助手从“对话玩具”走向“任务代理”的完整路径。其 Gateway 架构巧妙地解决了多平台接入、多智能体隔离和安全权限控制三大核心问题，并以开源、自托管的方式让开发者拥有完全的控制权。20+ 渠道的生态覆盖、JS/TS 友好的插件体系、以及逐步完善的配套 App，都使得它的易用性和扩展性在同类项目中脱颖而出。

随着 LLM 推理成本的下降和本地模型能力的提升，OpenClaw 有望成为个人数字生活的操作系统级入口。未来，我们可以期待更精细的权限代理（如临时授权、上下文感知审批）、更强的离线/本地执行能力，以及更丰富的设备端传感器集成。对于每一位想要构建真正“动手”的 AI 代理的开发者而言，OpenClaw 无疑是一个值得深度研究和实践的基石项目。

立即开始：curl -fsSL https://openclaw.ai/install.sh | bash，五分钟开启你的私人 AI 门户。

Post Views: 9