小龙虾技术解读
概述
OpenClaw，这是一个在你自己的设备上运行的个人 AI 助手。OpenClaw 是一个自托管网关，将你喜爱的消息应用程序 — WhatsApp、Telegram、Discord、iMessage 等等 — 连接到强大的 AI Agent。你可以在你的机器或服务器上运行单一的 Gateway 进程，它将成为你的聊天应用与一个随时可用并能执行真实任务的 AI 助手之间的桥梁。
什么是 OpenClaw？
OpenClaw 是一个多通道 AI 网关，专为那些希望拥有可以从任何地方发送消息的个人 AI 助手，同时又不想放弃数据控制权或依赖托管服务的开发者和高级用户而设计。与基于云端的 AI 助手不同，OpenClaw 在你的硬件上本地运行，在尊重你的隐私和安全边界的同时，提供强大的自动化功能。
该平台建立在网关架构 之上，其中单一的长生命进程拥有所有消息表面，并协调通道、客户端和 AI Agent 之间的通信。这种集中式设计确保了所有连接接口之间的一致的会话管理、路由和安全策略。
核心理念
OpenClaw 围绕三个塑造其架构和用户体验的基本原则设计：
自托管控制
你维护对数据和计算资源的完全所有权。Gateway 在你的设备（macOS、Linux、通过 WSL2 运行的 Windows）上运行，这意味着对话、会话历史和所有 AI 交互都保留在你的基础设施内。你选择使用哪些 AI 模型，连接哪些通道，以及执行哪些安全策略。
Agent 原生设计
与简单的聊天机器人不同，OpenClaw 从头开始就是为 AI Agent 构建的，这些 Agent 可以使用工具执行复杂任务，跨会话维护上下文，并理解多步骤工作流。嵌入式 Agent 运行时提供了一个复杂的执行环境，AI 可以在其中通过受控的工具系统读取文件、执行命令、浏览网页以及与各种服务交互。
多通道灵活性
单个 Gateway 实例可以同时服务于多个消息平台。这意味着你可以在 WhatsApp 上开始对话，在 Telegram 上继续，并通过 Web 仪表板管理它 — 所有这些都由 Agent 维护上下文和会话连续性。这种统一的方法消除了为每个平台设置独立机器人实例的需要。
架构概览
OpenClaw 架构围绕一个 Gateway 守护进程展开，它充当所有系统组件的控制平面。客户端通过 WebSocket 连接以发送命令、接收响应和订阅实时事件。
Gateway 组件
Gateway 守护进程 (src/gateway/) 充当中央协调器，维护提供者连接并暴露类型化的 WebSocket API 用于客户端通信。它根据 JSON Schema 验证所有传入请求，并为 Agent 活动、聊天消息、在线状态更新、健康状态和计划任务发出事件。Gateway 还为 Canvas 工作区和基于 Web 的接口托管 HTTP 端点。
Agent 运行时 (src/agents/) 是一个派生自 pi-mono 的嵌入式系统，负责管理 AI 模型交互、工具执行和工作区操作。它使用专用的工作区目录作为其工作目录，将引导文件（AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md）注入到 Agent 上下文中，以确立角色、边界和操作指南。会话作为带有稳定标识符的 JSONL 文件存储以实现持久化。
通道集成
OpenClaw 通过原生集成和插件扩展支持全面的消息平台集：
| Channel | Type | Location | Key Features |
|---|---|---|---|
| Native | src/whatsapp/ | 通过 Baileys 实现的基于 Web 的集成 | |
| Telegram | Native | src/telegram/ | 通过 grammY 框架支持的机器人 |
| Discord | Native | src/discord/ | 支持富消息的 Bot API |
| iMessage | Native | src/imessage/ | 通过本地 CLI 的 macOS 集成 |
| Slack | Native | src/slack/ | 支持工作区的 Bot API |
| Signal | Extension | extensions/signal/ | Bot 集成 |
| Microsoft Teams | Extension | extensions/msteams/ | 企业消息传递 |
| Matrix | Extension | extensions/matrix/ | 去中心化协议 |
| LINE | Extension | extensions/line/ | 亚洲市场平台 |
| Mattermost | Extension | extensions/mattermost/ | 企业团队消息传递 |
每个通道实现都处理平台特定的身份验证、消息格式化、在线状态更新以及特殊功能，如反应、输入指示器和位置共享。统一的通道接口 (src/channels/) 抽象了这些差异，允许 Agent 在所有平台上以一致的方式响应。
代码来源： src/channels extensions
关键能力
多 Agent 路由系统
OpenClaw 支持复杂的路由策略，用于在不同上下文中管理多个 AI Agent。你可以为每个 Agent、工作区或发送者配置隔离的会话 — 确保对话保持在适当的范围内，并且上下文不会在不同的用例之间泄漏。群聊接收隔离的会话，而直接消息则合并到共享的“主”会话中以保持连续性。
路由系统支持在群聊中基于提及的激活，允许对 Agent 响应的时间和方式进行细粒度控制。这使得 Agent 仅在明确被寻址时才参与的工作流成为可能，从而减少噪音并维持适当的社交边界。
媒体支持
OpenClaw 在所有支持的通道中提供全面的媒体处理功能。你可以发送和接收图像、录音、文档和其他文件类型。该平台包括可选的语音笔记转录挂钩，可将音频消息转换为文本，从而实现与基于文本的 AI 模型的基于语音的交互。
媒体处理流水线 (src/media/) 处理转换、压缩和格式规范化，以确保跨不同通道能力和 Agent 要求的兼容性。这包括用于视觉上下文的图像理解和允许 Agent 分析和描述内容的媒体理解功能。
代码来源： src/media
Web 控制 UI
基于浏览器的仪表板提供了一个全面的界面，用于与 OpenClaw 交互，而无需设置任何消息通道。可在网关主机上的 http://127.0.0.1:18789/ 访问，控制 UI 提供聊天功能、配置管理、会话检查、节点管理和实时监控。
此界面对于初始设置、调试以及作为更喜欢基于 Web 通信的用户的交互方法特别有用。WebChat 组件使用与其他客户端相同的 Gateway WebSocket API，确保功能对等和行为一致。
移动节点
iOS 和 Android 节点通过将移动设备与 Gateway 配对来扩展 OpenClaw 的能力。这些节点提供特定于设备的命令和功能：
Canvas：用于协作编辑的交互式可视化工作区
Camera：图像捕获和实时视觉输入
Screen recording：捕获设备屏幕以进行分析
Location：GPS 坐标和位置感知工作流
Voice：用于免提交互的语音识别和文本转语音
Device commands：访问通知、联系人、日历、SMS 和运动传感器
移动节点通过 WebSocket 连接，并带有显式的角色声明（role: node），并且需要配对批准，在实现强大的设备集成的同时确保安全性。配对是基于设备的，批准存储在设备配对存储中，支持同主机设置的本地自动批准。
技能和插件
插件架构
OpenClaw 具有广泛的插件 API，在保持核心运行时精简的同时，通过扩展启用可选功能。首选的分发模型是 npm 包，并支持本地扩展加载以进行开发。插件可以添加新通道、工具、内存系统、自动化功能或与外部服务的集成。
插件 SDK (src/plugin-sdk/) 提供用于开发扩展的 TypeScript 定义和辅助库。主要通道（Telegram、Discord、Slack、Signal、iMessage、WhatsApp、LINE、Microsoft Teams）提供了特定于平台的 SDK，抽象了协议细节并支持快速插件开发。
技能平台
技能是扩展 Agent 能力的专用自动化包。OpenClaw 从三个位置加载技能，工作区本地技能在名称冲突时优先：
| Location | Path | Use Case |
|---|---|---|
| Bundled | Built-in | 随安装附带的内置核心功能 |
| Managed | ~/.openclaw/skills | 跨工作区共享的用户安装技能 |
| Workspace | 隔离到单个工作区的项目特定技能 |
内存系统
内存是一个特殊的插件插槽，一次只能有一个内存插件处于活动状态。当前的实现包括基于向量的内存存储（LanceDB），平台正趋同于推荐的默认路径。内存插件启用持久化知识存储，允许 Agent 跨会话记住信息并随着时间的推移从交互中学习。
安全模型
OpenClaw 实现了一种深思熟虑的安全权衡：在不牺牲能力的前提下拥有强大的默认设置。目标是为实际工作维护强大的功能，同时使高风险路径显式化并由操作员控制。
安全默认设置
基于设备的配对：所有 WebSocket 客户端必须提供设备身份。新的设备 ID 需要配对批准，Gateway 会为后续连接颁发设备令牌。
本地信任自动批准：来自环回地址或网关主机 tailnet 地址的连接可以自动批准，以保持流畅的同主机用户体验。
挑战签名：所有连接必须签署 connect.challenge nonce 以进行身份验证。
可选网关令牌：当设置了 OPENCLAW_GATEWAY_TOKEN 时，客户端必须提供匹配的身份验证。
沙箱：当启用沙箱模式时，非主会话可以在具有受限工具访问权限的隔离工作区中运行。
安全文档
安全立场记录在 SECURITY.md 中，并在 docs/security/THREAT-MODEL-ATLAS.md 中维护了全面的威胁模型。这些文档定义了信任模型、设计边界、安全优先级和报告指南。
技术栈
OpenClaw 使用现代、广泛采用的技术构建，优先考虑可黑客性、迭代速度和易于贡献：
| Component | Technology | Rationale |
|---|---|---|
| Runtime | Node.js 22+ | 跨平台兼容性，广泛的生态系统 |
| Language | TypeScript | 类型安全，工具支持，广泛采用 |
| Build System | pnpm | 快速、高效的工作区管理 |
| Testing | Vitest | 支持 TypeScript 的现代测试框架 |
| Transport | WebSocket | 实时双向通信 |
| Protocol | JSON + JSON Schema | 自文档化，类型安全的 API |
| Packaging | npm | 插件的标准分发渠道 |
TypeScript 优先的方法使 OpenClaw 默认情况下易于黑客攻击 — 该语言广为人知，迭代速度快，并且易于阅读、修改和扩展。平台的编排性质（提示词、工具、协议、集成）使得 TypeScript 的类型系统在维护大规模复杂性时特别有价值。
代码来源： openclaw.mjs
项目结构
展示关键的代码结构
Gateway Control Plane 是 OpenClaw 的中央协调层，负责编排客户端、消息通道、AI agents 和系统服务之间的通信。它作为一个统一的 WebSocket 和 HTTP 服务器运行，提供实时控制、身份验证、通道管理以及基于协议的 RPC 方法，用于与整个 OpenClaw 生态系统交互。
架构概览
Gateway Control Plane 实现了分层架构，将传输层、协议层、身份验证层和业务逻辑层进行分离。这种设计在实现灵活的客户端集成同时，保持了对安全性、健康监控和资源管理的集中控制。
**Transport Layer (传输层)：**通过 WebSocket 管理网络连接以进行实时双向通信，并通过 HTTP 处理请求/响应模式。WebSocket 服务器使用 ws 库处理客户端连接，支持连接池、心跳监控和优雅关闭
来源: src/gateway/server.impl.ts src/gateway/server-runtime-state.ts
**Security Layer (安全层)：**实现多模式身份验证，支持基于令牌、基于密码、Tailscale 身份和受信任代理配置。速率限制通过可配置的每 IP 阈值防止暴力破解攻击。TLS 支持通过自动证书管理实现安全连接
来源: src/gateway/auth.ts
**Protocol Layer (协议层)：**定义请求、响应和事件的结构化帧类型，并使用 JSON schema 进行验证。RPC 方法注册中心集中了所有可用的控制操作，包括参数验证和错误处理
来源: src/gateway/protocol/index.ts src/gateway/server-methods-list.ts
**Business Logic Layer (业务逻辑层)：**包含特定领域的协调器，用于通道生命周期管理、健康监控、插件执行、Webhook 处理和 Agent 调度。这些组件与共享状态和外部服务进行交互
来源: src/gateway/server-channels.ts src/gateway/channel-health-monitor.ts
**State Management (状态管理)：**维护运行时状态，包括活动连接、会话存储、配置快照和广播机制。状态更新会触发版本化的健康状态和在线状态广播，发送给连接的客户端
来源: src/gateway/server-runtime-state.ts src/gateway/server/health-state.ts
多通道路由系统
多通道路由系统充当 OpenClaw 的智能流量控制器，协调不同通信平台与 AI agents 之间的消息流转。该系统支持基于通道身份、账户选择、对等方分类以及 Discord 角色或 Slack 团队等上下文元数据的复杂路由策略。通过提供 agents 与通信端点之间的灵活绑定机制，路由系统确保每条传入消息都能到达相应的 agent 实例，同时在对话线程间保持会话连续性。
路由架构作为一个多层决策引擎运行，通过绑定评估、账户选择和会话解析来处理传入消息。该系统围绕三个基本抽象构建：声明 agent 可访问范围的路径绑定、代表具体路由决策的已解析路由，以及维护对话状态持久化的会话密钥。
路由引擎利用基于 WeakMap 的缓存策略来优化性能，为绑定评估和已解析路由维护独立的缓存，并配置可限制（分别为 2000 和 4000 个条目）。该设计在通过对未使用的缓存条目进行垃圾回收来最小化内存压力的同时，确保了高吞吐量的消息处理。
来源：src/routing/resolve-route.ts src/routing/resolve-route.ts
路由绑定系统
路由绑定作为连接 agents 与通信端点的声明式配置机制。每个绑定指定一个匹配模式，用于确定 agent 何时应处理传入消息，支持从通道级别到基于角色的路由，范围越来越精细。
绑定匹配条件
绑定系统根据五个主要维度对消息进行评估：
| 匹配维度 | 类型 | 描述 | 示例 |
|---|---|---|---|
| channel | string | 目标通信平台 | "telegram", "discord", "slack" |
| accountId | string | 通道内的特定账户 | "primary", "bot-1" |
| peer | object | 目标对话对等方 | {kind: "direct", id: "user123"} |
| guildId | string | Discord 服务器 ID | "987654321" |
| teamId | string | Slack 工作区 ID | "T123456" |
| roles | string[] | 用于基于角色路由的 Discord 角色 ID | ["role1", "role2"]} |
peer 对象支持 ChatType 枚举中定义的三种聊天类型："direct" 用于一对一对话，"group" 用于多用户聊天群组，"channel" 用于广播式通道。这种分类使得路由策略能够区分直接消息、群组讨论和频道广播。
以上就是小龙虾大体的样子，小龙虾还在成长，总有一天会变成大龙虾，那个时候天下就要发生惊天动地的变化！