Cassian Note

OpenClaw 是什么

Properties2
tagsai/agent, ai-engineering, openclaw, harness-engineering
aliasesOpenClaw, Open Claw, openclaw

10分钟阅读

OpenClaw 是什么

一句话：OpenClaw 是一个运行在自己设备上的个人 AI 助手网关，把同一个 agent runtime 接上你已经在使用的所有通讯渠道，让模型不只是聊天，而是能持续完成真实任务。

它不是一个 SaaS 产品，而是一个自托管的 gateway + agent runtime + 插件生态。Gateway 是控制面，Agent 是执行面，Channel 是入口面。三者共享同一个核心，但通过清晰的边界解耦。

Note

如果说 Harness Engineering 是”把模型放进工程外壳”的范式，OpenClaw 就是当前开源世界里最完整的 Harness Engineering 实践之一。

一句话定位

OpenClaw 的前身是 Warelay -> Clawdbot -> Moltbot -> OpenClaw，从”个人实验场”演化为”多通道 AI 网关”，最终收敛为”个人 AI 助手”。

它解决的问题不是”哪个模型更强”，而是**“模型接在什么系统上、通过什么渠道、以什么权限、在什么环境里做事”**。

总体架构

flowchart TD
    A["入口渠道\nWhatsApp/Telegram/Slack/Discord/Signal/..."] --> B["Gateway Daemon\nws://127.0.0.1:18789"]
    B --> C["Agent Harness\nrunAttempt / compact / reset"]
    C --> D["PI Embedded Runner\nagent loop + tools"]
    D --> E["Provider Layer\nOpenAI/Anthropic/Google/..."]
    D --> F["Tool Runtime\nbash/mcp/skills/browser/..."]
    C --> G["Plugin Registry\nchannel/provider/tool"]
    B --> H["Control Clients\nCLI/macOS App/Web UI"]
    B --> I["Nodes\nmacOS/iOS/Android/headless"]
    B --> J["Canvas Host\nHTML/CSS/JS/A2UI"]

核心组件拆解

1. Gateway Daemon

Gateway 是一个长期运行的守护进程，是整个系统的控制面。

  1. 统一入口：所有通讯渠道的消息都先到达 Gateway，由 Gateway 归一化后交给 agent。
  2. WebSocket API：客户端（CLI、macOS App、Web UI、自动化脚本）通过 WS 连接到 Gateway，发送请求、订阅事件。
  3. Node 连接：macOS/iOS/Android/headless 节点也通过 WS 连接，声明 role: node 并提供设备能力（camera、canvas、screen、location）。
  4. Typed Protocol：请求/响应/事件都有 JSON Schema 验证，connect 帧是第一个必需帧，支持幂等键重试。
  5. Canvas 服务：Gateway 同时提供 HTTP 服务，托管可编辑的 HTML/CSS/JS Canvas 和 A2UI。
  6. 一对一映射：一台主机一个 Gateway，WhatsApp session 只在这里打开。

2. Agent Harness

OpenClaw 的 agent harness 是插件化注册的，通过 AgentHarness 接口定义：

type AgentHarness = {
  id: string;
  label: string;
  pluginId?: string;
  supports(ctx: AgentHarnessSupportContext): AgentHarnessSupport;
  runAttempt(params: AgentHarnessAttemptParams): Promise<AgentHarnessAttemptResult>;
  compact?(params: AgentHarnessCompactParams): Promise<AgentHarnessCompactResult>;
  reset?(params: AgentHarnessResetParams): Promise<void>;
  dispose?(): Promise<void>;
};

关键设计：

  1. Registry 模式：harness 通过 registerAgentHarness() 注册到全局 registry，运行时通过 selectAgentHarness() 选择最合适的 harness。
  2. Plugin 可扩展：第三方插件可以注册自己的 harness，通过 supports() 声明对 provider/model 的支持度。
  3. PI 内置 fallback：内置的 “PI embedded agent” 是默认 fallback harness，执行完整的 agent loop。
  4. 运行时策略：支持 runtime: "auto" | "pi" | "<plugin-id>"，以及 fallback 策略。

3. PI Embedded Runner（内置 Agent Loop）

这是 OpenClaw 的核心 agent loop，承担：

  1. 构造上下文：系统提示、项目上下文、会话历史、工具 schema。
  2. 调用模型：通过 provider transport 调用 LLM。
  3. 执行工具调用：解析 tool call，执行工具，返回结果。
  4. 循环直到完成：直到得到最终回答或达到预算。
  5. 上下文压缩：当上下文超限时触发 compaction，保留关键信息。
  6. 会话持久化：消息历史写入磁盘，支持跨会话恢复。
  7. 中断与恢复：支持 /stop、后台任务、子 agent 生命周期管理。

4. Plugin System（插件系统）

OpenClaw 的插件系统是架构的核心，定义了三种插件类型：

  1. Channel Plugin：通讯渠道适配器（WhatsApp、Telegram、Discord、Slack、Signal、iMessage、IRC、Matrix、Feishu、LINE、WeChat、QQ 等 20+ 渠道）。
  2. Provider Plugin：模型供应商适配器（OpenAI、Anthropic、Google、xAI、Mistral、Groq、Ollama、vLLM、OpenRouter 等 30+ 供应商）。
  3. Tool Plugin：工具能力扩展（browser、coding-agent、memory、image-generation、music-generation、video-generation、speech 等）。

边界规则（从 AGENTS.md 提炼）：

  • Core 不感知 Extension：核心代码不能硬编码特定扩展的 ID 或行为。
  • Plugin SDK 是唯一公共合约：扩展只能 import openclaw/plugin-sdk/*，不能 import 核心内部。
  • Manifest-first：插件的发现、验证、配置、激活都由 manifest 元数据驱动。
  • 延迟加载：冷启动路径不加载插件运行时，只在需要时才激活。

5. Tool Runtime（工具运行时）

OpenClaw 给模型暴露的工具包括：

  1. Bash/Shell：执行命令，支持前台/后台/PTY 模式，有审批流。
  2. 文件读写：读取、写入、编辑文件。
  3. MCP 工具：接入 Model Context Protocol 服务器。
  4. Skills：可复用的工作流注入（60+ 内置 skills）。
  5. 浏览器：自动化网页交互。
  6. 子 Agent：sessions/spawn 可以创建子 agent 执行独立任务。
  7. Canvas 操作：生成和编辑 HTML/CSS/JS。
  8. 媒体理解：图像、视频、音频分析。

工具系统的关键设计：

  • 每个工具有 schema、description、policy。
  • 工具按 toolset 分组，按场景动态启用。
  • 危险命令需要审批（CLI 和 Gateway 都能处理）。
  • 工具结果结构化，模型能理解。

6. Session & Memory

  1. Session 持久化：每个会话有独立的 transcript 文件，包含完整消息历史。
  2. 上下文压缩：支持 summarization 和 token 级别的清理。
  3. Memory 插件：内置 memory-core、memory-lancedb、memory-wiki 等插件，支持长期记忆。
  4. Profile 隔离：每个 profile 有独立的 config、API keys、sessions。
  5. Auth Profile 轮换：支持多 API key 轮换和 last-good 策略。

7. Multi-Platform Adapter（平台适配）

OpenClaw 支持 20+ 通讯渠道：

  • 核心渠道：WhatsApp、Telegram、Slack、Discord、Signal、iMessage
  • 企业渠道：Microsoft Teams、Matrix、Google Chat、Feishu、LINE、Mattermost
  • 社区渠道：IRC、Nostr、Nextcloud Talk、Synology Chat、Tlon、Twitch
  • 中文渠道：WeChat、QQ、Feishu
  • 自有渠道：WebChat（Web UI）

所有渠道的消息都归一化为内部 MessageEvent，然后交给同一个 agent runtime 处理。

关键技术选择

  1. TypeScript (ESM)：整个项目用 TypeScript 编写，严格类型。
  2. Node.js 22+：运行时要求 Node 22+（推荐 Node 24）。
  3. WebSocket 协议：Gateway 和客户端之间使用自定义的 typed WS 协议。
  4. Bun for Dev：开发时用 Bun 执行 TypeScript，生产用 Node。
  5. Vitest：测试框架。
  6. Oxlint + Oxfmt：代码检查与格式化。
  7. Zod：外部边界的数据验证（config、API 响应、CLI 输出）。
  8. Monorepo：src/ 核心 + extensions/ 插件 + apps/ 客户端 + ui/ 前端。

开源治理

OpenClaw 的 AGENTS.md 是仓库的工程宪法，定义了：

  1. 架构边界：core、plugin、channel、provider 的清晰划分。
  2. 代码规范：不使用 any，使用 Result<T, E>，使用 discriminated unions。
  3. 测试策略：测试与代码 colocate，测试不能 deep-import 插件内部。
  4. Prompt Cache 稳定性：请求组装必须确定性排序，缓存前缀不能每次变化。
  5. CI Gate：pnpm check 是本地开发 gate，pnpm test 是 landing gate。
  6. PR 规则：一个 PR = 一个 issue，超过 5000 行只在大例外情况下审查。

和 Hermes Agent 的对比

维度Hermes AgentOpenClaw
定位CLI AI Agent个人 AI 助手（多通道网关）
入口CLI + Gateway + CronCLI + Gateway + 20+ 渠道 + macOS/iOS/Android
运行时PythonTypeScript/Node.js
Agent Looprun_agent.py AIAgentPI Embedded Runner
Harness内置固定插件化注册（AgentHarness 接口）
渠道Telegram/Discord/Slack/…WhatsApp/Telegram/Slack/Discord/… (20+)
插件系统General/Memory/Context/Gateway hooksChannel/Provider/Tool 三类
ProviderOpenAI-compatible/Anthropic/Codex30+ 供应商
记忆SQLite + 自定义 memoryMemory plugins (core/lancedb/wiki)
子 Agentdelegate_tasksessions/spawn
前端TUI + WebTUI + Web UI + macOS/iOS/Android App
开源协议—MIT
Sponsors—OpenAI, GitHub, NVIDIA, Vercel

关键工程洞察

1. Gateway 是控制面，Agent 是执行面

OpenClaw 把”消息路由”和”任务执行”解耦。Gateway 负责接收消息、归一化、授权、路由；Agent 负责理解、规划、执行工具、返回结果。这意味着同一个 agent 可以被任何渠道触发。

2. Plugin SDK 是核心扩展面

OpenClaw 的 openclaw/plugin-sdk/* 是唯一的公共合约。第三方插件通过 SDK 接入，而不是直接 import 核心代码。这是 Harness Engineering 中 “extensibility” 的教科书级实现。

3. Prompt Cache 被当作工程问题

OpenClaw 明确要求：请求组装必须确定性排序；缓存前缀不能每次变化；截断优先修改最新的消息。这是因为 prompt caching 直接影响成本和延迟。

4. 多 Profile 隔离

每个 profile 有独立的配置、API keys、sessions、skills、gateway 状态。这允许同一台机器上跑多个独立实例，互不干扰。

5. 安全默认值

危险命令需要审批；token 锁定防止多个 profile 使用同一个 bot token；私有入口禁用认证时必须在受信网络内。

一句话总结

OpenClaw 不是在”哪个模型更好”上竞争，而是在**“模型能接在什么系统上、通过什么渠道做事”**上构建护城河。它是一个完整的 Harness Engineering 实现，把模型、工具、渠道、权限、状态、恢复都封装在一个可自托管的系统中。

关系图谱

反向链接