OpenClaw Architecture, Explained

摘要

OpenClaw如何从周末项目成长为GitHub历史上增长最快的开源项目之一,8周内突破18万星标,重新定义个人AI助手基础设施。

正文

从周末脚本到现象级开源项目

2026年1月初,一小群开发者聚集在Michael Galpert组织的首届Claude Code Show & Tell活动上。我们只有二十人,对智能体开发充满好奇,渴望分享使用最新AI编码工具的经验。

短短几周后的2月5日,Michael Galpert和Dave Morin组织了该系列的第三场活动,现已更名为ClawCon——首届OpenClaw旧金山展示会。超过700人到场参加。现场气氛热烈,Ashton Kutcher等投资人花了近一个小时听人们展示项目。OpenClaw的创始人Peter Steinberger成为当晚真正的明星,所有人都围着他提问、祝贺并合影。

这一切是如何发生的?仅仅八周时间,OpenClaw从一个周末WhatsApp中继脚本发展成为GitHub历史上增长最快的开源项目之一,到2月初已突破18万星标。这种增长不仅是病毒式传播,而是史无前例的。

在我看来,关键不仅在于技术能力,更在于产品化。Peter构建了一个脚手架,将智能体能力从研究工作转变为人们可以实际部署和使用的工具,真正完成任务。OpenClaw将"会回应的聊天机器人"转变为"会行动的智能体"——一个运行在你自己硬件上的持久助手,可通过你已经使用的消息应用和界面访问。

什么是OpenClaw?

OpenClaw是一个个人AI助手平台,运行在你自己的基础设施上:你的笔记本电脑、VPS、壁橱里的Mac Mini或云容器。它将AI模型和工具连接到你已经使用的消息应用:WhatsApp、Telegram、Discord、Slack、Signal、iMessage、Microsoft Teams等。

OpenClaw将AI助手视为基础设施问题,而非仅仅是提示工程问题。OpenClaw不试图通过巧妙的提示让LLM"记住"上下文或安全行事,而是在模型周围构建结构化的执行环境,具备适当的会话管理、内存系统、工具沙箱和消息路由。LLM提供智能;OpenClaw提供操作系统。

你可以控制助手在哪里运行、如何路由消息、可以使用哪些工具,以及如何隔离会话。模型API调用仍然发送到Anthropic、OpenAI或你的模型所在的任何地方;但对话历史、工具执行、会话状态和所有编排逻辑都保留在你的基础设施上。

OpenClaw面向希望通过任何消息应用访问个人AI助手的开发者和高级用户,而无需将整个体验交给托管的第三方助手。如果你曾想在WhatsApp DM、Slack频道和iMessage线程中使用Claude或GPT,同时让智能在你自己的硬件上运行,OpenClaw就能实现这种体验。

核心架构原理

OpenClaw不是围绕AI模型API的聊天机器人包装器。它是AI智能体的操作系统。OpenClaw将AI视为基础设施问题:会话、内存、工具沙箱、访问控制和编排。AI模型提供智能;OpenClaw提供执行环境。

OpenClaw采用以单一网关为中心的轮辐式架构,该网关充当用户输入(WhatsApp、iMessage、Slack、macOS应用、Web UI、CLI)与AI智能体之间的控制平面:

• 网关(Gateway)

  :一个WebSocket服务器,连接到消息平台和控制界面,将每条路由消息分派给智能体运行时。

• 智能体运行时(Agent Runtime)

  :端到端运行AI循环,从会话历史和内存中组装上下文,调用模型,针对系统可用功能(浏览器自动化、文件操作、Canvas、定时任务等)执行工具调用,并持久化更新后的状态。

关键洞察在于,OpenClaw将接口层(消息来源)与助手运行时(智能和执行所在)分离。这意味着你可以通过已经使用的任何消息应用访问一个持久助手,对话状态和工具访问在你的硬件上集中管理。

通过插件实现可扩展性

OpenClaw设计为无需修改核心代码即可扩展。插件通过四种主要方式扩展系统:

1. 频道插件

   :额外的消息平台(Microsoft Teams、Matrix、Mattermost等)

2. 内存插件

   :替代存储后端(向量存储、知识图谱 vs 默认SQLite)

3. 工具插件

   :内置bash、浏览器和文件操作之外的自定义功能

4. 提供商插件

   :自定义LLM提供商或自托管模型

插件系统位于extensions/中,遵循基于发现的模型。src/plugins/loader.ts中的插件加载器扫描工作区包中package.json的openclaw.extensions字段,根据声明的模式验证,并在配置存在时热加载。

核心组件详解

1. 频道适配器(Channel Adapters)

频道适配器是OpenClaw的"耳朵和嘴巴"——它们将网关连接到外部消息平台。每个适配器处理特定平台的协议复杂性,将传入消息转换为标准化的内部格式,并将智能体响应格式化回平台的本机格式。

适配器负责:

• 身份验证

  :建立与平台的安全连接

• 入站消息解析

  :将平台特定格式转换为OpenClaw的内部表示

• 访问控制

  :验证消息来源并确定路由

• 出站消息格式化

  :将智能体响应转换为平台格式

2. 控制界面

OpenClaw提供多个控制界面来管理和与智能体交互:

• Web UI

  :基于浏览器的界面,用于配置、监控和对话

• CLI

  :命令行界面,用于脚本和管理任务

• macOS应用

  :原生菜单栏应用,提供快速访问

• 移动端

  :通过消息应用访问

3. 网关控制平面

网关是整个系统的中央枢纽。它维护与所有频道适配器和控制界面的WebSocket连接,路由消息,管理会话,并协调智能体运行时。

4. 智能体运行时

智能体运行时是智能发生的地方。它编排AI交互的整个生命周期:

会话解析:确定消息所属的会话并加载其状态

上下文组装:通过读取工作区中的AGENTS.md、SOUL.md和TOOLS.md组装系统提示,注入相关技能,并查询内存搜索系统以查找语义上类似的过去对话,这些对话可能提供有用的上下文。

执行循环:

• 模型调用

  :将丰富的上下文打包并流式传输到配置的模型提供商

• 工具执行

  :当模型响应时,运行时监视工具调用。如果模型决定需要运行bash命令,运行时会拦截该调用并执行它,如果这是非主会话,可能在Docker沙箱内执行。每个工具结果都会流式传回模型,模型将其纳入正在进行的响应中。

• 响应交付

  :响应块在到达时通过网关流回。适配器格式化每个块,转换标记并遵守消息大小限制。最后,运行时将整个对话状态持久化回磁盘上的会话JSON文件。

端到端消息流程

让我们通过一个完整的例子来理解整个流程:你通过WhatsApp向OpenClaw发送消息"今天天气怎么样?"

阶段1:摄取 - 消息通过WhatsApp的服务器到达你的手机,然后到达OpenClaw的WhatsApp适配器

阶段2:访问控制和路由 - 访问控制检查不到10毫秒

阶段3:上下文组装 - 从磁盘加载会话不到50毫秒,组装系统提示不到100毫秒

阶段4:模型调用 - 根据网络条件,从模型获得第一个令牌需要200到500毫秒

阶段5:工具执行 - bash命令通常在100毫秒内完成,而浏览器自动化可能需要1到3秒

阶段6:响应交付 - 格式化的消息通过WhatsApp服务器发送到你的手机

数据存储和状态管理

OpenClaw将其数据和配置存储在主目录的多个位置。

配置:主配置文件位于~/.openclaw/openclaw.json,使用JSON5格式,这意味着你可以包含注释和尾随逗号。配置是分层的:环境变量覆盖配置文件值,配置文件值又覆盖内置默认值。

会话状态和压缩:OpenClaw将每个对话作为会话文件持久化在~/.openclaw/sessions/下,捕获该会话的对话历史以及元数据和任何持久工具状态。会话存储为支持分支的仅追加事件日志,这使得恢复状态、检查历史记录变得容易。为了保持在模型上下文限制内,OpenClaw执行自动压缩:对话的旧部分被总结和持久化,以便会话可以继续而不丢失基本上下文。

内存搜索:OpenClaw维护对话的可搜索内存,以便在你与智能体交互时提供相关上下文。

安全架构

OpenClaw的安全模型建立在多层防御之上:

网络安全:默认情况下,网关绑定到localhost,仅通过SSH隧道或Tailscale等安全通道暴露

身份验证和设备配对:每个控制界面都需要身份验证

频道访问控制:验证消息来源并确定路由

工具沙箱:非主会话在受限环境中运行,以保护主机免受不受信任的输入

提示注入防御:系统级防护措施防止恶意输入操纵智能体行为

部署架构

OpenClaw支持多种部署模式:

本地开发(macOS/Linux):直接在开发机器上运行

生产macOS(菜单栏应用):作为原生macOS应用运行

Linux/VM(远程网关):

• 选项A:SSH隧道(推荐默认)

• 选项B:Tailscale Serve(仅限tailnet的HTTPS)

Fly.io(容器部署):网关在由Fly.io管理的Docker容器中运行,持久卷存储OpenClaw状态,Fly.io在容器前提供托管的HTTPS端点。

结论

OpenClaw代表了个人AI基础设施的现代方法:本地优先、自托管、完全可控。其架构通过单进程网关模型平衡简单性,同时通过多智能体路由、工具沙箱和可扩展插件提供强大功能。这使得它对刚入门的开发者来说易于访问,同时对要求苛刻的用例保持生产就绪状态。

围绕网关控制平面的轮辐式设计实现了跨消息平台的统一访问。无论你是从WhatsApp、Discord还是iMessage发送消息,都能获得一致的智能体体验。强大的安全边界可以防止不受信任的输入,而不会牺牲功能。具有工具执行和持久会话的智能体原生运行时提供了真正智能的助手体验,而不仅仅是LLM周围的聊天包装器。

无论你是在笔记本电脑上运行OpenClaw供个人使用,还是将其部署到VPS以实现全天候可用性,你都能获得可从任何地方访问的私人AI助手。你保留对其运行位置、暴露方式以及数据存储和访问方式的控制。

在AI能力越来越多地被锁定在专有API和封闭花园的时代,OpenClaw提供了一种替代方案:按照你的条件运行助手,通过你已经使用的频道访问,并透明了解其工作原理。