Clawdbot / OpenClaw 架构事实校准与设计参考
Clawdbot / OpenClaw 架构事实校准与设计参考
Clawdbot 这个名字需要先校准：公开资料中的 clawdbot/clawdbot 仓库目前会跳转到 openclaw/openclaw，官方文档也使用 OpenClaw 作为当前项目名。本文仍保留 Clawdbot 作为历史名称，但以下分析以 2026-05-29 能看到的 OpenClaw 官方仓库、README 与文档为事实边界。
这篇文章不是替项目写一份”完整生产架构白皮书”。更准确地说，它做三件事：
- 把官方资料明确写出的能力列出来。
- 把可以合理推断的架构拆开说明，并标记为推断。
- 把容易被夸大的地方降温，给普通开发者一套评估此类 Agent 项目的方法。
一、事实校准：先把边界立住
官方文档对 OpenClaw 的定位很清楚：它是一个自托管 Gateway，用来把用户常用的聊天应用、Web 控制台、CLI、macOS 应用、移动节点等入口连接到 AI coding agents。官方概览页写到，它运行一个 Gateway 进程，连接 Discord、Google Chat、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo 等渠道，并提供会话、路由、工具、记忆和多 Agent 路由能力。
几个可以直接作为事实使用的点：
- 当前项目名是 OpenClaw，旧的 Clawdbot 仓库地址会跳转到 OpenClaw 仓库。
- 官方 README 将其描述为运行在用户自己设备上的个人 AI assistant，Gateway 是控制面。
- 官方文档把 Gateway 定义为 sessions、routing、channel connections 的 single source of truth。
- Gateway 默认本地端口是
127.0.0.1:18789，控制面客户端通过 WebSocket 连接 Gateway。 - 配置文件路径在官方文档中写为
~/.openclaw/openclaw.json，不是旧文里写的~/.clawdbot/clawdbot.json。 - OpenClaw core 使用 TypeScript，推荐 Node 运行时；文档明确说 Bun 不推荐用于 Gateway。
- macOS companion app 和 iOS/Android mobile nodes 已被文档列为存在；Windows 和 Linux 原生 companion app 被描述为 planned，但 Gateway 当前可用，Windows 推荐 WSL2。
这意味着，讨论它时最好不要再笼统写成”本地优先 AI 助手完整架构”。更准确的表达是：一个自托管、聊天渠道驱动、以 Gateway 为控制面的个人 Agent 系统。
二、已知能力：官方资料能支撑什么
1. Gateway 是核心控制面
官方 Gateway 架构文档给出的职责包括：
- 单个长期运行的 Gateway 拥有消息渠道连接。
- macOS app、CLI、Web UI、自动化客户端通过 WebSocket 连接 Gateway。
- macOS、iOS、Android、headless nodes 也通过 WebSocket 连接，但以
role: node声明能力和命令。 - Gateway 维护 provider connections，暴露 typed WebSocket API，并用 JSON Schema 校验 inbound frames。
- Gateway 会发出
agent、chat、presence、health、heartbeat、cron等事件。 - Gateway HTTP server 承载 Canvas 相关路径，并复用默认 Gateway 端口。
这是可以确定的架构重心：OpenClaw 不是把每个聊天渠道各自做成一个孤立 bot，而是把渠道接入、客户端控制、节点能力和 Agent 执行入口收敛到一个 Gateway。
2. 多渠道接入是产品主轴
官方 Channel 文档列出的渠道很多，包括 Discord、Feishu/Lark、Google Chat、iMessage、IRC、LINE、Matrix、Mattermost、Microsoft Teams、Nextcloud Talk、Nostr、QQ Bot、Signal、Slack、Synology Chat、Telegram、Tlon、Twitch、Voice Call、WebChat、WeChat、WhatsApp、Yuanbao、Zalo 等。
但这里要注意两个边界：
- “列在文档里”不等于每个渠道都有同等成熟度。
- 不同渠道的文本、媒体、反应、群组、配对、认证方式差异很大，不能简单概括为”统一支持所有消息能力”。
比较稳妥的说法是：OpenClaw 的方向是用一个 Gateway 同时服务多个内置渠道、捆绑插件渠道和外部插件渠道；具体可用性要按渠道文档和实际版本验证。
3. Agent 能力建立在工具、技能、插件之上
Capabilities 文档把几个概念分得比较清楚：
- Tool 是 Agent 可以调用的 typed function，例如
exec、browser、web_search、message、image_generate。 - Skill 是
SKILL.md指令包，用来教 Agent 按某种工作流执行。 - Plugin 用来增加运行时能力，例如工具、模型 provider、渠道、hook、技能包、媒体生成、Web 搜索等。
这比”插件系统很强大”这种说法更具体：OpenClaw 的扩展面至少分为模型可见的工具、提示词层面的技能、运行时代码层面的插件三类。开发者评估时也应该分开看：工具影响 Agent 能做什么，技能影响 Agent 怎么做，插件影响系统能接入什么运行时能力。
4. 安全控制确实存在，但不能等同于无风险
官方 Gateway 架构文档提到：
- WebSocket 首帧必须是
connect。 - Gateway 支持 shared-secret auth。
- Tailscale Serve 或 trusted-proxy 模式可以从请求头获取身份。
gateway.auth.mode: "none"会关闭 shared-secret auth，文档明确提示不要用于公网或不可信入口。- 所有 WebSocket clients 和 nodes 都包含 device identity。
- 新 device ID 需要 pairing approval，Gateway 会签发 device token。
- 非本地连接仍需要显式批准。
Capabilities 文档还提到，工具策略会在模型调用前执行；模型只会看到 active profile、allow/deny policy、provider restrictions、sandbox state、channel permissions、plugin availability 等过滤后仍可用的工具。
所以，OpenClaw 不是完全没有安全边界。但也不能把它写成”沙箱隔离保证安全”或”生产级安全系统”。它的核心价值是让用户自托管和控制入口；它的核心风险也来自这里：一旦你把消息渠道、浏览器、文件、命令执行、插件和长期会话接到一起，攻击面会显著扩大。
三、可能架构：可以推断，但不要写成源码事实
基于官方文档，比较合理的运行链路可以写成这样：
聊天渠道 / Web UI / CLI / 移动节点
|
v
Gateway: 连接、认证、配对、路由、事件、会话入口
|
v
Agent runtime: 上下文、工具可见性、模型调用、执行循环
|
v
Tools / Skills / Plugins / Model providers / Nodes
|
v
消息回复、文件或系统操作、浏览器操作、Canvas、自动化任务这条链路里，“Gateway 是控制面”和”客户端通过 WebSocket 连接 Gateway”有官方文档支撑；“Agent runtime 如何在每一步内部调度工具、压缩上下文、恢复失败、选择模型”则需要进一步阅读源码和具体版本，不能仅靠概览文档下结论。
如果把它抽象成工程模式，OpenClaw 更像是下面这种形态：
- 入口层：聊天渠道、WebChat、CLI、桌面应用、移动节点。
- 控制面：Gateway 统一管理连接、认证、路由、会话入口、事件流。
- Agent 层：把用户意图转成模型调用和工具调用。
- 能力层：工具、插件、技能、模型 provider、浏览器、媒体、自动化。
- 本地状态层：配置、配对、会话、记忆、渠道状态。
这里的重点不是画更多图，而是理解边界：Gateway 不应该被想象成传统云原生 API 网关；Agent runtime 也不应该被想象成一个已证明支持大规模多租户生产流量的任务调度平台。它首先是个人自托管系统，然后才谈扩展。
四、适合借鉴的设计
1. 用 Gateway 收敛复杂入口
聊天应用、Web 控制台、桌面客户端、移动节点的协议都不一样。OpenClaw 选择用一个 Gateway 做中间控制面，这个方向值得借鉴。
好处是边界清楚：渠道适配负责接入，Gateway 负责连接和路由，Agent runtime 负责执行。坏处是 Gateway 变成强中心组件，一旦状态模型设计不好，后续会被会话、配对、重连、重试、权限、日志全部拖住。
普通开发者做类似项目时，不必一开始支持二十个渠道。更现实的做法是先把一个渠道、一个 Gateway、一个 Agent loop 做稳定，再抽象 channel adapter。
2. 把工具、技能、插件分层
很多 Agent 项目把”能力扩展”混成一团：有些是工具调用，有些是系统提示词，有些是 Node 包，有些是外部服务凭证。OpenClaw 文档把 Tool、Skill、Plugin 分开，这是一个成熟的设计信号。
这个分层能降低长期混乱：
- 工具需要 schema、权限、执行结果和审计。
- 技能需要加载顺序、触发条件和上下文预算。
- 插件需要生命周期、manifest、依赖、安装来源和权限请求。
如果你在设计自己的 Agent 系统，这三类能力最好从第一天就拆开。否则项目到了第三个月，所有扩展都会变成”往 prompt 里塞一段话加一个脚本”。
3. 工具策略在模型调用前生效
Capabilities 文档明确说，工具策略在模型调用前执行；被策略移除的工具不会进入当轮模型 schema。这是很重要的安全和成本设计。
原因很简单：不要只在工具执行时拦截，也要在模型思考前减少它能看到的动作空间。工具越多，模型越容易误选；危险工具越早被过滤，后面的审批压力越小。
这类设计比”执行前弹窗确认”更底层。弹窗是最后一道门，工具可见性控制才是第一道门。
4. 自托管不等于孤岛
OpenClaw 的定位不是纯离线系统。它可以连接外部模型 provider，可以接聊天平台，可以通过插件增加能力，也支持 Tailscale、SSH tunnel、VPS hosting 等远程访问方式。
这类系统更准确的描述是”用户控制的运行边界”，而不是”数据绝不出本机”。如果使用云端 LLM、第三方聊天平台、外部插件或远程浏览器，数据仍可能离开本机。文章和产品文案都应该把这点讲清楚。
五、不应夸大的地方
1. 不要说它天然生产级
官方文档提到 systemd、launchd、Scheduled Task、health、Gateway status、Tailscale、TLS、pairing 等运维能力。这些说明项目认真考虑了长期运行，但不足以推出”生产级高可用”。
除非源码和部署文档明确证明，否则不要写：
- 负载均衡。
- 自动故障转移。
- 多 Gateway 主从复制。
- 多租户隔离。
- 企业级审计闭环。
- SLA 或大规模并发验证。
这些都不是个人自托管 Agent 的默认能力。
2. 不要把插件写成安全沙箱
官方文档说明插件可以增加工具、provider、渠道、hook 和技能包，也提到权限请求和工具策略。但”有权限控制”不等于”插件被强沙箱隔离”。
对普通用户来说，插件最大的风险不是它能不能安装，而是安装后它能被 Agent 通过什么路径调用、能访问哪些文件和网络、凭证在哪里、审计是否看得懂。尤其是来自社区市场、npm、git、本地目录或压缩包的插件，安装前要按供应链软件来审查，而不是按聊天机器人配置项来对待。
3. 不要把”本地优先”写成”隐私绝对安全”
自托管让用户拥有更多控制权，但风险没有消失，只是转移到了用户自己的机器、网络、凭证、插件和配置上。
典型风险包括：
- WhatsApp、Telegram、Slack 等渠道本身仍是外部平台。
- 云端 LLM provider 会接收发送给模型的上下文。
- 浏览器和系统命令工具可能把 Agent 的错误判断放大为真实副作用。
- Gateway 如果暴露到公网且关闭认证，会变成高危入口。
- 长期记忆和会话历史一旦落盘，就需要备份、清理和加密策略。
所以更准确的结论是：OpenClaw 给用户更多控制面，但用户也承担更多运维和安全责任。
4. 不要把所有渠道能力视为一致
文档列出的渠道非常多，但每个渠道的 API 能力、登录方式、群组机制、媒体支持、消息撤回、反应、bot 限制都不同。一个架构上支持多渠道的系统，实际产品体验仍然可能高度不一致。
评估时不要只看”支持 WhatsApp / Telegram / Slack”，要看：
- 是否支持群组。
- 是否支持媒体。
- 是否需要 QR 配对。
- 是否会保存会话状态到磁盘。
- 是否有 allowlist 和 mention rules。
- 是否能防止 bot loop。
- 出错时有没有可理解的诊断日志。
六、普通开发者如何评估这类 Agent 项目
1. 先跑最小闭环，不要先看宣传图
一个 Agent 项目是否可用，最小闭环是：
一个入口 -> 一个会话 -> 一次模型调用 -> 一个工具调用 -> 一条可追踪回复如果这个闭环稳定，再看多渠道、多 Agent、插件市场、自动化任务。反过来，如果最小闭环都需要大量手工修配置，后面的能力越多，维护成本越高。
2. 看安全默认值，而不是安全选项
文档里有安全选项不够，关键是默认值是否保守。建议重点检查：
- Gateway 默认是否只绑定本地地址。
- 远程访问是否推荐 VPN、Tailscale 或 SSH tunnel，而不是裸公网。
- 新设备是否必须配对。
- 危险工具是否默认不可见。
- 命令执行是否有审批或沙箱。
- 群组消息是否需要 mention 或 allowlist。
- 插件安装是否显示权限请求。
安全能力只有在默认路径里生效，才真正保护普通用户。
3. 看状态落在哪里
Agent 项目的复杂度往往藏在状态里。要搞清楚：
- 配置在哪里。
- 渠道登录态在哪里。
- 会话历史在哪里。
- 记忆在哪里。
- 插件和技能在哪里。
- 凭证在哪里。
- 日志在哪里。
OpenClaw 官方文档明确提到配置路径 ~/.openclaw/openclaw.json。至于每类状态的精确文件布局，应以当前版本文档和源码为准，不要沿用旧名称时代的路径。
4. 看工具边界是否能解释清楚
Agent 真正危险的地方不是回答问题，而是能行动。凡是支持 exec、浏览器控制、文件写入、消息发送、Webhook、日历、邮箱、支付或云账号操作的项目，都必须回答三个问题：
- 模型什么时候能看到这个工具？
- 调用前是否需要人批准？
- 调用后是否有日志和回滚方式？
如果项目只能回答”相信模型”或”用户自己小心”，就不适合放进重要账户和生产环境。
5. 看项目是否承认限制
成熟项目通常会明确写出实验功能、推荐运行时、已知问题、远程访问风险和平台差异。OpenClaw 文档中例如明确说 Node 是推荐运行时，Bun 不推荐用于 Gateway；也把 Windows / Linux companion app 标成 planned，而不是已经完成。
这种限制说明反而是可信度信号。真正需要警惕的是那些每个能力都写”支持”，但没有版本、边界、失败模式和安全说明的项目。
七、结论
Clawdbot / OpenClaw 值得关注，不是因为它证明了”个人 AI 助手已经生产级自治”，而是因为它把几个重要方向放到同一个可运行项目里：
- 用 Gateway 统一多渠道入口。
- 让 Agent 通过用户已有聊天工具触达。
- 把工具、技能、插件作为不同层次的扩展面。
- 用自托管方式把运行边界交还给用户。
- 在 WebSocket、配对、工具策略、渠道 allowlist 等位置设置控制点。
但公开写作时必须保持边界感。能从官方文档确认的，就写成事实；只能从架构形态推出来的，就写成推断；需要生产验证的数据，就不要用营销口吻替它补齐。
对普通开发者来说，最有价值的不是照搬 OpenClaw 的全部功能，而是借鉴它的架构取舍：先把入口、控制面、执行面、能力面和状态面拆清楚，再逐步增加渠道和工具。Agent 系统的工程难点从来不是”接一个模型 API”，而是让一个会行动的模型在长期运行、复杂权限和真实副作用里仍然可控。