[好文翻译] OpenClaw 架构详解OpenClaw 将“响应式聊天机器人”转变为“行动式智能体”，一个在您自己的硬

原文：OpenClaw Architecture, Explained

OpenClaw 如何作为 AI 智能体的操作系统工作

2026 年初，一小群开发者聚集在 Michael Galpert 组织的第一届 Claude Code Show & Tell 活动上。我们二十个人，对智能体式开发充满好奇，渴望分享我们与最新 AI 编程工具的经验。

仅仅几周后，在 2 月 5 日，Michael Galpert 和 Dave Morin 组织了该系列的第三场活动，并将其重新命名为 ClawCon，即第一届 OpenClaw SF Show & Tell。超过 700 人参加。现场气氛热烈。投资者 Ashton Kutcher 花了近一个小时听取人们向他推销项目。OpenClaw 的创造者 Peter Steinberger 是当晚真正的“好莱坞式”明星，周围全是向他提问、祝贺和自拍的人。

我们是如何做到的？仅仅八周内，OpenClaw 从一个周末的 WhatsApp 联动脚本，成长为 GitHub 历史上增长最快的开源项目之一，到 2 月初星标数已超过 180,000。这种增长不仅是病毒式的，而且是前所未有的。

在我看来，关键并不仅仅是技术能力，而是产品化。Peter 构建了脚手架，将智能体能力从研究工作转变为人们可以实际部署和使用以真正完成事情的东西。

OpenClaw 将“响应式聊天机器人”转变为“行动式智能体”，一个在您自己的硬件上运行的持久助手，可通过您已经使用的消息应用程序和界面访问。

Andrej Karpathy 称其为“我所见过的最不可思议的科幻起飞相关事物。”

我通常对深入学习和理解新 AI 框架或产品的细节很感兴趣——不仅仅是使用它们。OpenClaw 似乎与我构建 Axiom 的第一个 AI 原生公司以及帮助我们的投资组合公司导航智能体架构和产品设计策略的工作特别相关。

开源的特性让我有机会深入挖掘代码，并整理出这份 OpenClaw 架构的解析，为那些正在探索类似智能体架构的创始人提供实用指导。

引言

OpenClaw 是一个运行在你自有基础设施上的个人 AI 助手平台：你的笔记本电脑、VPS、衣帽间里的 Mac Mini，或云容器。它将 AI 模型和工具连接到你已使用的消息应用：WhatsApp、Telegram、Discord、Slack、Signal、iMessage、Microsoft Teams，以及其他许多应用。

OpenClaw 将您的 AI 助手视为基础设施问题，而不仅仅是提示词工程问题。它不是试图通过巧妙的提示词让 LLM “记住”上下文或安全地行为，而是围绕模型构建一个结构化的执行环境，具有适当的会话管理、记忆系统、工具沙盒和消息路由。LLM 提供智能；OpenClaw 提供操作系统。

您控制助手运行的地点、消息的路由方式、可使用的工具，以及会话的隔离方式。模型 API 调用仍然会发送到 Anthropic、OpenAI 或您的模型所在的位置；但对话历史记录、工具执行、会话状态以及所有编排逻辑都保留在您的基础设施上。

OpenClaw 旨在面向开发者和高级用户，他们希望在任何消息应用中都能使用个人 AI 助手，而无需将整个体验交给托管的第三方助手。如果你曾经希望在 WhatsApp DMs、你的 Slack 频道以及你的 iMessage 聊天记录中都能使用 Claude 或 GPT，同时保持智能运行在你自己的硬件上，OpenClaw 就能提供这种体验。

OpenClaw 的工作原理：高层概述

OpenClaw 不是一个围绕 AI 模型 API 的聊天机器人封装。它是一个 AI 智能体的操作系统。OpenClaw 将 AI 视为一个基础设施问题：会话、记忆、工具沙盒、访问控制和编排。

AI 模型提供智能；OpenClaw 提供执行环境。

OpenClaw 采用以单个 Gateway 为中心的星型（中心 - 辐射）架构，该 Gateway 作为用户输入（WhatsApp、iMessage、Slack、macOS 应用、Web UI、CLI）与 AI 智能体之间的控制平面：

网关是一个 WebSocket 服务器，它连接到消息平台和控制接口，并将每个路由的消息分派给智能体运行时。
智能体运行时负责端到端运行 AI 环路，从会话历史和记忆中组装上下文，调用模型，执行针对系统可用能力的工具调用（如浏览器自动化、文件操作、Canvas、计划任务等），并持久化更新后的状态。

关键在于 OpenClaw 将接口层（消息来源处）与助手运行时（智能和执行所在处）分离。这意味着你可以通过任何你已使用的即时通讯应用访问一个持久的助手，而对话状态和工具访问则由你的硬件中央管理。

下图展示了系统架构的概览（点击放大）：

通过插件实现扩展性

OpenClaw 旨在无需修改核心代码即可扩展。插件通过四种主要方式扩展系统：

频道插件（Channel plugins）：额外的消息平台（Microsoft Teams、Matrix、Mattermost 等）
记忆插件（Memory plugins）：替代存储后端（向量存储、知识图谱与默认的 SQLite）
工具插件（Tool plugins）：内置 bash、浏览器和文件操作之外的定制功能
提供者插件（Provider plugins）：定制的 LLM 提供者或自托管模型

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

核心组件

1. 频道适配器

每个消息平台都有自己的专用适配器。一些适配器是预装的（你可以在像 src/telegram/ 、 src/discord/ 、 src/slack/ 、 src/imessage/ 等目录中找到它们），而其他适配器可以通过频道插件添加。适配器实现相同的接口，并规范化传入/传出消息，这样 OpenClaw 的其他部分就不需要关心特定平台的特性。虽然各个平台的 API 和协议差异很大，但每个适配器都实现了一个具有四个关键职责的通用接口：

认证
传入消息解析
访问控制
传出消息格式化

认证

认证因平台而异。WhatsApp 通过 Baileys 库使用二维码配对，将凭证存储在 ~/.openclaw/credentials 中。Telegram 和 Discord 使用通过环境变量提供的 bot token，如 TELEGRAM_BOT_TOKEN 和 DISCORD_BOT_TOKEN 。iMessage 需要原生 macOS 集成，并且需要一个正确签名的 Messages 应用程序。

入站消息解析（Inbound）

入站消息解析处理不同平台数据格式的杂乱现实。每个适配器提取文本，处理媒体附件（图片、音频、视频、文档），处理反应和表情符号，并维护线程或回复上下文。这一层标准化意味着 OpenClaw 的其余部分不需要知道消息来自 WhatsApp 还是 Discord。

访问控制

访问控制是在频道级别发生的。白名单指定哪些电话号码或用户名可以与您的机器人交互；例如， channels.whatsapp.allowFrom 接受一个电话号码数组。私信策略控制机器人如何处理来自未知发送者的私信。默认的 "pairing" 策略在处理消息之前需要批准。您可以将其设置为 "open" 接受所有私信（不推荐）或 "disabled" 完全拒绝它们。群组策略增加了一层，包括提及要求和群组特定的白名单。

出站消息格式化（Outbound）

每个平台都有自己的 Markdown 语法、消息大小限制和媒体上传 API。适配器处理所有这些，包括将长消息分块以遵守平台限制、正确渲染 Markdown、上传媒体文件，甚至管理输入指示器和在线状态信息。

以下是 WhatsApp 配置可能的样子：

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["+1234567890"],
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

2. 控制接口

OpenClaw 提供了多种与网关交互的方式，每种方式都适用于不同的使用场景和偏好：

Web UI
命令行界面（CLI）
macOS 应用程序
移动端

Web UI

Web UI 是基于 Lit 构建的 Web 组件，直接由网关本身提供服务。默认情况下，将浏览器指向 http://127.0.0.1:18789/ ，您将获得一个用于聊天、配置管理、会话检查、节点管理和健康监控的仪表板。无需单独的 Web 服务器：网关处理所有事务。

命令行界面

CLI 通过 Commander.js 实现，从 openclaw.mjs 开始并流经 src/cli/program.ts ，为您提供对一切内容的命令行控制。使用 openclaw gateway 启动网关。使用 openclaw agent 直接调用智能体。使用 openclaw channels login 配对 WhatsApp 或 Signal。使用 openclaw message send 程序发送消息。使用 openclaw doctor 运行健康诊断。或使用 openclaw onboard 进行引导式设置。

macOS 应用程序

macOS 应用采用了不同的方法。它使用 Swift 编写，位于 apps/macos/ ，驻留在您的菜单栏中，提供网关生命周期管理——启动、停止、重启，只需指尖轻触。它包含语音唤醒功能，带有一键通话覆盖层，将 WebChat 嵌入原生浏览器视图，甚至可以通过 SSH 控制远程网关。

移动端

iOS 和 Android 的移动节点通过在连接握手中声明 role: "node" ，以 WebSocket 节点的方式连接到网关。这不仅仅是为了聊天；这些应用还暴露了设备特定的功能，如相机访问、屏幕录制、位置服务和 Canvas 渲染。网关可以使用 node.invoke 协议方法调用这些功能，将您的手机变成智能体工具集的扩展。

3. 网关控制平面

网关位于 src/gateway/server.ts 并在 Node.js 22 或更高版本上运行。它使用 ws WebSocket 库构建，默认绑定到 127.0.0.1:18789 ，loopback-only for security。这不仅仅是一个路由器；它是整个 OpenClaw 系统的唯一真实来源。

每个消息平台（通过 Baileys 库连接的 WhatsApp、通过 grammY 连接的 Telegram、使用 discord.js 连接的 Discord）都通过这个中心点进行连接。CLI 工具、Web 界面和移动应用都作为 WebSocket 客户端进行连接。当有入站消息到达时，网关会通过访问控制检查进行路由，确定哪个会话应该处理该消息，并将其分派给相应的智能体。它协调系统状态，包括会话、在线状态指示器、健康监控和定时任务。并且至关重要的是，它通过为任何非回环绑定（non-loopback bindings）执行令牌或密码认证来强制执行安全性，并为直接消息（direct messages）实现配对系统。

这里的设计原则是经过深思熟虑的。首先，每个主机上只有一个网关：这可以防止 WhatsApp 会话冲突，因为 WhatsApp 的协议是严格单设备的。其次，整个协议是类型化的：所有 WebSocket 帧都会根据 JSON Schema 进行验证，而 JSON Schema 本身是由 TypeBox 定义生成的。这意味着如果客户端发送了格式错误的数据，它会被立即捕获。第三，系统是事件驱动的，而不是基于轮询的。客户端订阅 agent 、 presence 、 health 和 tick 等事件，而不是不断询问“有什么新情况？”最后，任何具有副作用的操作都需要一个幂等性密钥，这使得重试逻辑安全，并防止重复操作。本地连接（回环或同一尾网，loopback or same tailnet）可以自动批准，而远程连接需要挑战-响应（challenge-response）签名和明确批准。

4. 智能体运行时

智能体运行时（ src/agents/piembeddedrunner.ts ）的实现，是 AI 交互实际发生的地方。它使用 Pi Agent Core 库（ @mariozechner/pi-agent-core ），并遵循 RPC 风格的调用模型，支持流式响应。

从宏观角度来看，每次交互时，运行时都会执行四件事：(1)解析会话，(2)组装上下文，(3)在执行工具调用时流式传输模型响应，以及(4)将更新后的状态持久化回磁盘。

会话解析

当消息到达时，运行时首先确定哪个会话（session）应处理该消息。来自您的直接消息（direct message）映射到 main 会话。通过频道发送的私信映射到 dm:<channel>:<id> 。群聊映射到 group:<channel>:<id> 。会话不仅仅是 ID——它们是安全边界。每种会话类型可以携带不同的权限和沙箱规则（例如： main 可以在主机上运行工具，而 dm / group 会话可以默认采用更严格的允许列表和 Docker 隔离）。

上下文组装

一旦会话解决，运行时就会为模型组装上下文。它通常：

从持久化的 JSON 会话文件中加载会话历史（以便每个会话在时间上保持连续性）。
通过读取工作区配置文件并组合它们成一个指令堆栈来构建动态系统提示词。
通过语义搜索从记忆中获取信息（例如，先前的相关对话或笔记），以便模型仅看到最相关的历史上下文，而不是不断增长的对话记录。

然后，将组装的上下文流式传输到配置的模型提供者（Anthropic Claude、OpenAI GPT、Google Gemini 或本地模型），以便您能够逐个token获取响应，而不是等待单个最终结果。

执行循环

当模型响应时，运行时监控工具调用并拦截它们。如果模型请求工具（例如，运行 bash 命令、读取/写入文件、打开浏览器并抓取网页），运行时会执行该工具，具体取决于会话的沙盒策略，可能在一个 Docker 沙盒中执行。每个工具的结果都会流式传输回正在进行的模型生成，模型会将其纳入并继续。对话回合完成后，运行时会将更新的会话状态（消息、工具调用/结果以及任何其他跟踪状态）持久化到磁盘。

系统提示词架构

OpenClaw 通过组合多个来源构建提示词：

工作区配置文件：

AGENTS.md — 核心智能体指令（捆绑默认）。操作基准：智能体被允许执行的操作、全局约束以及适用于所有会话的不可协商规则。
SOUL.md — 个性与语气指导（可选）。语音和交互风格：智能体说话和结构答案的方式，但不包括工具行为或安全边界。
TOOLS.md — 用户特定的工具约定（可选）。您关于工具在您的环境中如何使用的个人笔记，不是工具注册表。OpenClaw 自动向模型提供工具定义。

动态上下文（每轮组装）：

会话历史记录 — 当前对话中的最近消息
技能（ skills/<skill>/SKILL.md ）— 技能定义和使用说明（技能存在的必要条件）。包含使用可用工具完成特定任务的指导性文件，例如操作手册或标准操作程序。
记忆搜索 — 提供有用上下文的语义相似的过去对话

工具定义（自动生成）：

内置工具（ src/agents/pi-tools.ts ， src/agents/openclaw-tools.ts ）— bash，浏览器，文件操作，canvas和核心功能
插件工具（通过 api.registerTool(toolName, toolDefinition) 注册）— 通过扩展系统添加的自定义工具

基础系统：

Pi Agent Core — 来自智能体运行时库的基础指令

所有这些元素组合成最终的系统提示词，该提示词连同对话历史记录和当前用户消息一起发送给模型。这种组合式方法意味着您可以通过编辑工作区中的文件来更改智能体行为、风格和任务能力，而无需触碰源代码，同时保持由运行时强制执行的执行、权限和沙箱化。

技能发现与技能注入是一个重要的细节：OpenClaw 可以在运行时发现技能，但不会盲目地将每个技能注入到每个提示词中。相反，运行时会选择性地仅注入与当前回合相关的技能，以避免提示词膨胀并降低模型性能。

交互与协调

1. Canvas 和 Agent-to-UI (A2UI)

Canvas 是一个由智能体驱动的可视化工作空间，作为单独的服务器进程运行，默认端口为 18793。这种与主网关的分离提供了隔离（如果画布崩溃，网关可以正常运行），并建立了不同的安全边界，因为 Canvas 提供可由智能体写入的内容。

流程如下：智能体调用 Canvas 更新方法，Canvas 服务器接收 HTML 并解析其中嵌入的 A2UI 属性，服务器通过 WebSocket 将此内容推送给已连接的浏览器客户端，客户端将 HTML 渲染为交互式界面。

A2UI 代表 Agent-to-UI，它提供了一个声明式框架，其中智能体生成带有特殊属性的 HTML。这些属性创建交互式元素，而无需智能体编写 JavaScript。例如：

<div a2ui-component="task-list">
  <button a2ui-action="complete" a2ui-param-id="123">
    Mark Complete
  </button>
</div>

当用户点击该按钮时，客户端向 Canvas 服务器发送一个动作事件，服务器将其转发为工具调用给智能体。智能体处理该动作，例如在其内部状态中将任务 123 标记为完成，并调用 canvas 更新新状态。服务器将此更新推送给客户端，显示将自动刷新。

Canvas 支持跨多个平台。macOS 应用程序使用原生 WebKit 视图进行渲染。iOS 应用程序将 Canvas 包装在 Swift UI 组件中。Android 使用 WebView 进行显示。当然，Web UI 可以简单地在一个浏览器标签中打开 Canvas。

2. 语音唤醒和交谈模式

语音唤醒功能可在 macOS、iOS 和 Android 平台上使用，提供始终开启的唤醒词检测。说出“Hey OpenClaw”，系统即可激活，准备接收您的指令。或者使用键盘快捷键进行推话模式。音频流传输至 ElevenLabs 进行转写，智能体处理您的请求，响应通过 ElevenLabs 文本转语音播放。

对话模式将此功能扩展为连续对话。您可以与智能体进行免提的来回对话，系统具备中断检测功能，让您可以在智能体说话时插入对话。配置自定义唤醒词以满足您的偏好。

3. 多智能体路由

多智能体路由功能允许您将不同的渠道或分组定向到完全隔离的智能体实例。每个实例可以拥有自己的工作空间、自己的模型和自己的行为。

想象你希望你的 Discord 服务器机器人使用 Claude Sonnet 拥有助人的管理员个性，而你的 Telegram 支持私信则使用 GPT-4 并可以访问不同的工具和更正式的语气。这种配置可以自然地表达这种需求：

{
  "agents": {
    "mapping": {
      "group:discord:123456": {
        "workspace": "~/.openclaw/workspaces/discord-bot",
        "model": "anthropic/claude-sonnet-4-5",
        "systemPromptOverrides": {
          "SOUL.md": "You are a helpful Discord moderator..."
        }
      },
      "dm:telegram:*": {
        "workspace": "~/.openclaw/workspaces/support-agent",
        "model": "openai/gpt-4o",
        "sandbox": { "mode": "always" }
      }
    }
  }
}

这种路由可以实现多种强大的用例。你可以为每个社区创建独立的角色，每个角色都针对该社区的文化和需求进行优化。不同的上下文可以有不同的工具访问权限：也许你的 Discord 机器人可以使用浏览器自动化，但你的 support 智能体则不能。隔离的沙盒为不可信用户提供了保障，即使有人尝试利用提示词注入漏洞，影响范围也会被限制在最小。你可以在一个上下文中测试新的智能体行为，而不会影响其他上下文中已建立且正常工作的智能体。

4. 会话工具（智能体间通信，A2A）

会话工具使智能体能够在不同的会话中协调，本质上提供了智能体间通信。当你想让智能体合作处理复杂任务或共享信息，而不需要你手动在不同聊天上下文中复制粘贴时，这些工具特别有用。

sessions_list 工具用于发现活动会话。这使得智能体能够查看其他可用的智能体。
sessions_send 工具向另一个会话发送消息。例如，您可以设置 announceStep: "ANNOUNCE_SKIP" 使一个智能体在无声的情况下将工作发送给另一个智能体，而不会通知两个会话中的用户。
sessions_history 工具从其他会话中获取文本记录，这在需要智能体从另一个智能体的交互中获取上下文以做出明智决策时非常有用。
sessions_spawn 工具用于以编程方式创建新的会话，以便分配工作。

5. 定时任务（Cron Jobs）和外部触发器（Webhooks）

Cron Jobs 允许您在特定时间运行智能体操作。需要每日摘要吗？配置一个每天早上 9 点触发的 Cron Job，向您的主会话发送消息。Webhooks 为智能体操作提供外部触发点。经典的例子是电子邮件集成，比如 Gmail 发布到一个 webhook 端点，从而触发智能体操作。

这两个功能都使用基于配置的设置，允许您自动化重复任务并与外部系统集成，而无需编写自定义代码。

深入解析：端到端消息流

让我们追踪当你向你的 OpenClaw 助手发送 WhatsApp 消息时会发生什么。理解这个流程可以揭示所有组件是如何协同工作的。

阶段 1：摄取

首先，Baileys 库从 WhatsApp 的服务器接收一个 WebSocket 事件。 src/whatsapp/ 中的 WhatsApp 适配器解析这个事件，提取消息文本、任何媒体附件以及发送者的元数据。

阶段 2：访问控制与路由

在消息继续传递之前，它会先经过访问控制层。这个发送者是否在你的允许列表中？如果是首次私信，配对是否已获批准？如果任何一项检查失败，消息就会在这里停止。

假设访问控制通过， src/auto-reply/reply.ts 中的自动回复系统将接管。它会确定哪个会话应该处理此消息。如果消息直接来自你，那就是具有全部功能的 main 会话。通过 WhatsApp 发送的私信成为 agent:main:whatsapp:dm:+123... 会话。群聊则成为 agent:main:whatsapp:group:120...@g.us 会话。每种会话类型都带有不同的权限和沙箱规则。

阶段 3：上下文组装

Agent 运行时的 PiEmbeddedRunner 从磁盘加载解析出的会话。它会通过读取工作空间中的 AGENTS.md 、 SOUL.md 和 TOOLS.md 来组装系统提示词，注入相关技能，并查询记忆搜索系统以查找语义上相似的过去对话，这些对话可能提供有用的上下文。

阶段 4：模型调用

这些丰富的上下文将被打包并流式传输到您配置的模型提供者。

阶段 5：工具执行

当模型响应时，运行时环境会监控工具调用。如果模型决定需要执行一个 bash 命令，运行时环境会拦截该调用并执行它，如果这是一个非主会话，可能会在 Docker 沙盒中执行。如果模型想要打开浏览器并抓取一个网站，运行时环境会启动 Chromium 并使用 Chrome DevTools 协议自动化。每个工具的结果都会被流式传输回模型，模型将其整合到其正在进行的响应中。

阶段 6：响应发送

响应块在到达时通过网关流回。WhatsApp 适配器格式化每个块，将 Markdown 转换为 WhatsApp 的标记格式并尊重消息大小限制。格式化的消息通过 Baileys 发送到 WhatsApp 的服务器，并最终发送到您的手机。最后，运行时将整个对话状态（您的消息、模型的响应、所有工具调用和结果）持久化回磁盘上的会话 JSON 文件。

整个流程的延迟预算大致如下：访问控制不到 10 毫秒。从磁盘加载会话不到 50 毫秒。组装系统提示词不到 100 毫秒。从模型获取第一个 token 根据网络条件需要 200 到 500 毫秒。工具执行各不相同：bash 命令通常在 100 毫秒内完成，而浏览器自动化可能需要 1 到 3 秒。

数据存储和状态管理

OpenClaw 将其数据和配置存储在用户主目录的多个位置。了解这种布局有助于备份、迁移和故障排除。

配置

主配置文件位于 ~/.openclaw/openclaw.json ，并使用 JSON5 格式，这意味着您可以包含注释和尾随逗号——这些功能使得手动编辑比严格的 JSON 更愉快。配置是分层管理的：环境变量会覆盖配置文件中的值，而配置文件中的值又会覆盖内置默认值。这允许您将敏感的令牌保存在环境变量中，同时在文件中保持静态配置。

会话状态和压缩

OpenClaw 将每个对话持久化为 ~/.openclaw/sessions/ 下的一个会话文件，捕获该会话的对话历史记录，以及元数据和任何持久的工具状态。

会话以仅追加的事件日志形式存储，并支持分支，这使得恢复状态、检查历史记录以及推理某个回合在对话树中的位置变得容易。

为了保持在模型上下文限制内，OpenClaw 执行自动压缩：对话的较旧部分被总结并持久化，以便会话可以继续而不丢失重要上下文。在压缩之前，系统可以运行一个轻量级的“记忆刷新”步骤，将持久化信息提升到记忆文件中；这有助于防止在压缩较旧的回合时丢失重要细节，并且在会话工作区不可写时会被跳过。

会话标识符编码了所有权和信任边界。主要操作员会话以 agent:<agentId>:main 为键，并运行具有全部功能。DM 会话使用 agent:<agentId>:<channel>:dm:<identifier> ，群组会话使用 agent:<agentId>:<channel>:group:<identifier> ；两者默认情况下都被沙盒化，以保护主机免受不可信输入和多参与者对话的影响。

记忆搜索

OpenClaw 会维护一个可搜索的对话记忆库，以便在与智能体交互时提供相关上下文。当你提问时，系统会自动搜索过去的对话，查找语义上相似的讨论，并将这些上下文注入当前对话回合中，这样智能体就可以参考几周前讨论过的事情，而无需你重复说明。

存储和索引

记忆系统使用 SQLite 数据库和向量嵌入在 ~/.openclaw/memory/<agentId>.sqlite 中存储数据。随着消息的到达，它们会被自动索引。系统使用混合搜索，结合向量相似性（语义匹配）和 BM25 关键词相关性（精确标记匹配）来查找最相关的过去上下文。

工作区中的记忆文件

除了对话记录，您还可以维护结构化的记忆文件供智能体参考：

MEMORY.md — 长期记忆，包含经过筛选的稳定事实。此文件仅在私有/main 会话中加载以保护隐私，绝不会在群聊中加载，以免他人看到您的个人上下文。
memory/YYYY-MM-DD.md — 每日笔记，提供每天活动和上下文的原始运行日志。

嵌入提供者（Embedding provider）选择

记忆系统需要一个嵌入模型来将文本转换为可搜索的向量。OpenClaw 会根据您配置的内容自动选择提供者：

如果您配置了本地嵌入模型（ local.modelPath ），则使用该模型
否则，检查 OpenAI API 密钥并使用 OpenAI 嵌入
否则，检查 Gemini API 密钥并使用 Gemini 嵌入
如果没有可用，记忆搜索将被禁用

索引管理

文件监视器会监控您的记忆文件，并在它们更改时自动重新索引（具有 1.5 秒的防抖以避免频繁刷新）。如果您更改了嵌入提供程序或模型，系统会检测到这一点并自动重新索引所有内容。您还可以通过 experimental.sessionMemory: true 启用实验性会话转录索引，这使得完整的对话历史记录可供搜索，而不仅仅是记忆文件。最后，如果 sqlite-vec 可用，它将加速 SQLite 内的向量搜索操作。

凭证

敏感的认证数据存储在 ~/.openclaw/credentials/ 中。这包括频道认证令牌，如 WhatsApp 的会话数据，Discord 等平台的 OAuth 凭证，以及任何其他用于频道访问的秘密信息。文件权限限制为 0600（仅所有者可读写），并且该目录会自动排除在版本控制之外，以防止意外泄露。

安全架构

OpenClaw 通过多层安全机制实现纵深防御。每一层提供不同类型的保护，它们协同工作，共同构建全面的安全态势。

1. 网络安全

默认情况下，网关仅绑定到 127.0.0.1 ，您的回环接口（loopback interface）。这意味着网关仅可从本地机器访问，永远不会暴露在公共互联网上。远程访问需要通过一种支持的方法进行显式配置：

# SSH tunnel (recommended for VPS)
ssh -N -L 18789:127.0.0.1:18789 user@host

Tailscale 集成提供两种模式。Tailscale Serve 提供仅针对 tailnet 的 HTTPS 访问，您的网关通过安全的加密连接对您 Tailscale 网络上的其他设备可见。Tailscale Funnel 则更进一步，通过 Tailscale 的基础设施将您的网关暴露在公共互联网上。

# Tailscale Serve (tailnet-only HTTPS)
config: gateway.tailscale.mode: "serve"

# Tailscale Funnel (public HTTPS, requires password)
config: gateway.tailscale.mode: "funnel"
       gateway.auth.mode: "password"

无论您是通过 SSH、Tailscale 还是直接连接进行连接，WebSocket 握手和认证机制都适用。

2. 认证与设备配对

基于令牌或密码的认证保护非回环绑定。在启动网关之前设置 OPENCLAW_GATEWAY_TOKEN 环境变量，所有 WebSocket 客户端都必须在其 connect.params.auth.token 字段中包含该令牌。或者，通过在配置文件中的 gateway.auth.mode: "password" 配置密码认证（Tailscale Funnel 需要）。

基于设备的配对（Device-based pairing）增加了额外的安全层。所有 WebSocket 客户端（控制界面、节点、CLI 工具）在 connect 握手过程中包含设备身份。设备身份由设备 ID 和加密密钥组成。当新设备连接时：

本地连接（回环或同一 Tailscale 网络）可以配置为自动批准，以简化同一主机的工作流程
远程连接在握手期间必须签署一个挑战随机数，以证明他们拥有有效的凭证，并需要明确批准

一旦批准，网关将为该设备颁发一个设备令牌，允许后续连接而无需重新批准。这种基于设备的模型即使有人获取了您的认证令牌，也能防止未经授权的访问。

重要：控制界面（Control UI）需要一个安全上下文（HTTPS 或 localhost）来使用 crypto.subtle 生成设备身份。如果您启用 gateway.controlUi.allowInsecureAuth ，界面会回退到仅使用明文 HTTP 的令牌认证，并跳过设备配对——这是一种安全降级。请优先使用 HTTPS（Tailscale Serve）或在 127.0.0.1 上访问界面。

3. 通道访问控制

私信配对（DM pairing）提供 human-in-the-loop 批准私信（direct messages）。当为 dmPolicy="pairing" （默认值）时，未知发送者会触发特定流程：他们发送第一条消息，网关会回复一个唯一的配对码而不是处理消息。通过运行 openclaw pairing approve <channel> <code> 来批准发送者，这会将他们添加到本地允许列表存储中。只有到那时，他们的消息才会到达智能体。

允许列表明确指定哪些电话号码或用户名可以与您的机器人交互。对于 WhatsApp： channels.whatsapp.allowFrom: ["+1234567890"] 。对于 Telegram： channels.telegram.allowFrom ，并附带用户名或数字 ID。

组策略增加了另一层控制：

requireMention : 机器人仅在群组中被@提及时才会响应
群组特定的允许列表：当设置 channels.whatsapp.groups 时，它成为一个群组允许列表（包含 "*" 以允许所有群组）
每个频道的提及模式： messages.groupChat.mentionPatterns: ["@openclaw"]

4. 工具沙盒

OpenClaw 使用基于 Docker 的沙箱技术，按会话隔离工具执行。 main 会话（操作员的直接交互）通常在主机上以原生方式运行工具，并具有完全访问权限。相比之下，私信（DM）和组（group）会话可以配置为在临时的 Docker 容器中执行工具，从而减少不受信任输入的影响。

每个沙箱容器提供隔离的文件系统、可选的网络访问（通常默认禁用，仅在需要时显式启用）以及可配置的资源限制（CPU/记忆）。容器是短命的：它们是为沙箱执行而创建的，然后被销毁，因此即使 DM 或组会话被强迫执行不安全行为，其“破坏范围”也仅限于该容器，而不是您的宿主机环境。

基于会话的安全边界

该模型与会话信任级别完美映射：

主会话（Main session）：为操作员工作流程提供完全主机访问权限（无 Docker 开销）。
私信会话（DM sessions）：默认情况下沙盒化（即使对于已批准的联系人也一样），以防止错误或提示词注入。
组会话（Group sessions）：默认情况下沙盒化，以防御高风险、多参与者输入。

什么改变了安全配置文件

几个高级旋钮决定了隔离的强度：

沙盒化的内容：沙盒化适用于工具（例如 Shell/进程/文件操作，以及可选的浏览器自动化），而不是 Gateway 本身。
容器粒度：隔离可以是每个会话（最强），每个智能体，或跨沙盒会话共享（最高效，隔离性最低）。
主机暴露：工作空间和绑定挂载决定了容器是否从主机什么都看不到，只读视图，或读写访问。绑定挂载功能强大，但如果暴露敏感路径，可能会重新引入风险。
网络访问：启用容器网络扩展了能力，但也增加了风险；除非会话真正需要，否则应保持受限。
逃逸通道：任何明确标为“主机级别”或具有提升权限的、绕过沙盒的工具都应被视为仅限高信任级别的表面。

工具策略和优先级

工具访问受分层策略管理，有效权限随着从操作员到不受信任环境的移动而逐渐缩小。

工具策略优先级（后源覆盖先源）：

工具配置文件 → 提供者配置文件 → 全局策略 → 提供者策略 → 智能体策略 → 群组策略 → 沙盒策略

群组策略和沙盒策略可以进一步限制智能体可用的工具集，但不应用于扩展超出早期策略允许的访问权限。

5. 提示词注入防御

上下文隔离有助于防御提示词注入攻击，通过将输入清晰分离。用户消息携带源元数据，系统指令与用户提供的内容保持区分，工具结果则被封装在结构化格式中，以区别于用户输入。这种分离使得攻击者更难欺骗智能体将不可信的消息视为系统指令。

模型选择也起着作用。OpenClaw 的文档建议，对于任何可以运行工具或操作文件/网络的机器人，应使用最高等级的最新一代模型（并明确建议 Claude Opus 4.5 作为强大的默认选项）。如果出于成本或延迟原因使用较小模型，文档建议通过减少影响范围来补偿：优先使用只读工具，最小化文件系统暴露，应用严格的沙箱隔离，并强制执行严格的允许列表。

这些保护措施只有在有严格的控制措施支持时才有效。通过配对/允许列表（pairing/allowlists）锁定传入的私信，在群组中优先使用提及门控（mention gating）而不是在公共房间中运行“始终开启”模式，默认将链接/附件/粘贴的指令视为敌对行为，并在沙箱中运行敏感工具，同时将秘密排除在智能体可访问的文件系统之外。对于不可信的渠道，广泛启用沙箱隔离，并禁用网络功能工具（ web_search / web_fetch / browser ，除非输入受到严格控制）。沙箱是可选的，系统提示词的约束是软性指导；执行来自频道（channel）访问控制、工具策略限制、沙箱隔离（在适用的情况下）以及明确的执行批准。

部署架构

OpenClaw 支持四种主要的部署模式，每种模式针对不同的用例和环境进行了优化。架构在所有模式中保持一致；变化的是网关的运行位置以及客户端如何连接到它。

本地开发（macOS/Linux）

在本地开发设置中，所有内容都在开发机器上运行。您使用 pnpm dev 在前台启动网关，这可以在代码更改时启用热重载。网关绑定到 127.0.0.1:18789 ，只能从本地机器访问。CLI 工具和 Web UI 直接连接到此回环地址。由于回环接口被视为可信，因此无需进行认证，调试日志以最大详细程度运行。

此模式以可视化方式表示：

生产 macOS（菜单栏应用）

macOS 生产部署使用 LaunchAgent 来将 Gateway 作为后台服务运行。该服务在登录时自动启动，并持续运行。macOS 菜单栏应用为 Gateway 提供了启动、停止和重新启动的原生界面。它包括直接嵌入应用中的 WebChat UI、用于免提操作的语音唤醒功能，以及通过回环接口的本地访问。可通过 SSH 隧道或 Tailscale 实现远程访问。

架构如下所示：

这项部署支持原生 macOS 集成，包括 iMessage 支持，因为 iMessage 需要在实际的 Mac 上运行。Voice Wake 与 ElevenLabs 集成，用于语音识别和合成。通过 A2UI 系统的 Canvas 支持，为智能体驱动的界面提供了一个可视化工作空间。

Linux/VM (远程网关)

在 VPS 或虚拟机上运行 OpenClaw 可提供 24/7 可用性，而无需保持个人计算机开启。网关作为 systemd 服务在远程主机上运行，并且可以保持绑定到回环（ 127.0.0.1 ）以增强安全性。您的本地客户端（CLI 和 Web UI）通过 SSH 隧道连接，该隧道将本地端口转发到远程回环端口。

选项 A：SSH 隧道（推荐默认选项）

SSH 端口转发将您的本地 127.0.0.1:18789 映射到远程网关的 127.0.0.1:18789 :

ssh -N -L 18789:127.0.0.1:18789 user@vps

一旦隧道建立，您的本地 CLI 和 Web UI 连接到您机器上的 127.0.0.1:18789 ，流量将通过加密的 SSH 隧道透明地转发到远程网关：

选项 B: Tailscale Serve（仅 tailnet HTTPS）

Tailscale 提供了一种替代的 VPS 部署方案。您无需维护 SSH 隧道，而是将您的 VPS 和客户端设备都加入同一个 Tailscale 网络（一个“tailnet”）。VPS 使用 Tailscale Serve 通过 HTTPS 将网关暴露给 tailnet 上的其他设备（例如， https://vps.tailnet.ts ）。这种方式提供了加密访问，无需管理 SSH 密钥或隧道进程。

Fly.io（容器部署）

Fly.io 是一种云原生部署选项，网关在由 Fly.io 管理的 Docker 容器中运行。持久化卷存储 OpenClaw 状态（配置、会话、凭证），使其在部署和重启后仍然存在。Fly.io 在容器前面提供了一个托管的 HTTPS 端点（带有 TLS 终止），使网关可以通过公共互联网远程访问。

架构图：

因为网关在这个模式下可以从公共互联网访问，所以你应该启用强认证，并将其视为一个面向互联网的服务。

结论

OpenClaw 代表了一种现代的个人 AI 基础设施方法：本地优先、自托管且完全可控。其架构通过单进程网关模型平衡了简单性，通过多智能体路由、工具沙盒和可扩展插件实现了强大的功能。这使得它对刚开始使用的开发者来说易于访问，同时也能满足高要求的用例。

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

无论您是在个人笔记本电脑上运行 OpenClaw，还是将其部署到 VPS 上以实现全天候可用性，您都可以随时随地访问一个私有的 AI 助手。您保留对其运行位置、暴露方式以及数据存储和访问的控制权。

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