很多 Agent 产品的演示都从一句话开始：用户提出任务，模型调用几个工具，然后返回答案。这个视角容易把 Agent 理解成“带函数调用的聊天机器人”。OpenClaw 的重点并不在某一次模型调用，而在于把消息渠道、模型、工具、设备、会话和长期状态组织成一个持续运行的系统。
它的核心进程叫 Gateway。Gateway 连接 WhatsApp、Telegram、Slack、Discord 等渠道，也接受 CLI、Control UI 和设备节点的请求；它负责会话路由、权限判断、Agent Loop、事件推送和状态保存。模型只是其中一个可替换部件，工具调用也只是运行链路的一部分。
本文基于 2026 年 9 月 19 日可见的 OpenClaw 官方仓库 和官方文档。由于 OpenClaw 迭代很快，文中把官方明确描述的行为标为“官方事实”，把从架构得到的设计判断标为“工程推断”；配置和命令仍应以实际安装版本为准。
一、OpenClaw 解决的不是“如何聊天”
普通聊天应用的主流程通常是：
用户输入 → 调用模型 → 返回文本
这种流程不需要稳定的会话身份，也不需要知道一条消息来自哪个渠道，更不需要协调多个设备和后台任务。一个长期运行的个人 Agent 面临的是另一组问题：
- 同一个人从 Telegram、网页和命令行发来的消息，是否应该进入同一个会话？
- 一个运行中的 Agent 正在执行工具时，新消息应该排队、插入、终止还是合并？
- 工具生成的结果如何回写到会话，而不会被旧运行覆盖？
- Agent 能否读取工作区、访问设备或向外部渠道发消息？
- 记忆、凭据、插件和日志的生命周期如何管理？
- Gateway 重启后，哪些状态可以恢复，哪些任务需要重新确认？
因此，OpenClaw 更像一个面向 Agent 的控制面。官方架构文档将 Gateway 描述为所有消息表面、会话、路由和渠道连接的长期进程；客户端与节点通过 WebSocket 连接，Gateway 再把请求交给对应的 Agent Runtime。Gateway 架构文档 给出的关键点，是把“连接管理”和“Agent 执行”放在同一个可持久化控制面中。
二、先建立组件地图
可以把 OpenClaw 拆成四个相互配合的面：
┌────────────────────── 交互面 ──────────────────────┐
│ WhatsApp / Telegram / Slack / Discord / Web / CLI │
│ macOS / iOS / Android Nodes │
└──────────────────────┬─────────────────────────────┘
│ WebSocket / Channel Plugin
▼
┌────────────────────── Gateway：可信控制面 ──────────┐
│ 认证与配对 │ 渠道路由 │ Session │ Policy │ 事件总线 │
│ Agent Loop │ 工具调度 │ Cron/Webhook │ 状态与审计 │
└──────────────┬───────────────────────┬─────────────┘
│ │
▼ ▼
Model Provider / Harness Tools / Skills / Plugins
│ │
└──────────────┬────────┘
▼
Sandbox / Node / Host
这里最容易混淆的是几个名词。
Channel 负责把不同消息平台的输入和输出接入 Gateway。它处理平台连接、消息格式、发送重试和渠道侧的身份信息。Channel 不是 Agent，也不应该决定模型如何推理。
Model Provider 提供模型和认证配置。更换 Provider 不应该改变会话、渠道或工具的生命周期。OpenClaw 还可以接入外部 Agent harness，但 Gateway 仍然需要掌握会话、权限和投递结果。
Agent Runtime 负责把一次消息变成一组动作。它组装系统提示词和工作区上下文，调用模型，执行工具，接收工具结果，再决定是否继续推理。
Tools、Skills 和 Plugins 的职责不同。Tool 是模型可以调用的动作；Skill 是按需加载的操作说明和程序化流程；Plugin 是把渠道、Provider、工具或其他能力注册进 Gateway 的扩展单元。能力可以插件化，并不代表插件天然隔离。官方文档明确提醒，原生插件在 Gateway 进程内运行，安装它就意味着信任它。
三、一条消息如何走完整链路
把一条来自聊天渠道的消息拆开，可以得到下面的流程：
渠道事件
↓
渠道认证 / Pairing / Allowlist
↓
解析 sender、channel、conversation、attachments
↓
Session 路由与权限策略
↓
进入 session queue：steer / followup / collect / interrupt
↓
准备 workspace、skills、bootstrap files、memory
↓
组装 prompt，解析 model 与 auth profile
↓
Agent Loop：模型 → 工具 → 工具结果 → 模型
↓
写入 session transcript 与审计事件
↓
流式发送 assistant / tool / lifecycle 事件
↓
渠道投递最终回复
第一步不是“直接把文本交给模型”，而是确认谁可以触发这次运行。普通主机安装默认将 Gateway 绑定到回环地址；多数支持私聊的渠道会要求陌生发送者先完成配对，群组通常还需要白名单和提及门控。安全指南 中把这些行为定义为入口控制，而不是模型提示词的一部分。
通过入口后，Gateway 会把渠道信息转换成内部请求。Session key 不只是一个聊天窗口名称，它还决定上下文、工作区、权限和并发队列。相同渠道的不同发送者不能因为都发了一句“开始”就共享同一段历史；多用户场景必须显式选择会话隔离策略。
队列决定新消息的语义
Agent 正在执行工具时，新消息可能有四种语义：
- steer：把新消息导入当前运行，在下一个模型调用或尚未启动的工具前改变方向；
- followup：等待当前运行结束，再开启下一轮；
- collect：先收集多条输入，再合并处理；
- interrupt：中止当前运行。
这不是 UI 层的按钮，而是运行时一致性问题。假设旧运行已经准备执行“删除临时文件”，用户随后发来“先不要删除”，系统必须在工具真正启动前检查 steering；已经启动的工具则不能假装被撤回。官方 Agent Loop 文档将这类边界描述为按 Session 串行化的运行语义。
四、Agent Loop：模型调用只是中间步骤
官方定义的 Agent Loop 可以压缩成五个阶段：接收请求、组装上下文、模型推理、工具执行、流式输出与持久化。Agent Loop 文档 还补充了几个对工程实现很关键的细节。
1. 先接受，再异步运行
Gateway RPC 的 agent 请求先解析 Session、保存元数据，并立即返回 runId 和接受时间。真正的 Agent Loop 在后台执行；调用方可以通过 agent.wait 等待同一个 runId 的终态。
这种设计把“请求已接收”和“任务已完成”分开了。对于聊天渠道，用户可以先看到运行状态；对于自动化任务，调度器可以保存 runId，稍后判断是成功、失败还是超时。一个 wait 超时也不等于底层任务被取消，它可能仍在运行。
2. Session 队列与全局队列
OpenClaw 会对同一 Session 的运行进行串行化，并可选地通过全局队列限制整体并发。这样可以避免两个运行同时修改同一份 transcript 或争抢同一个工作区。
这不是简单的互斥锁。开始流式输出前，运行会获得一个活动写入者标识；后续 transcript 写入需要携带预期的 writer id，提交时再次验证。如果旧运行已经被新运行取代，旧运行即使晚一步完成，也不能把过期结果写回当前会话。这里可以看成“运行世代号 + 条件提交”的组合。
3. 上下文组装
模型看到的内容来自多个来源：
基础系统提示词
+ Agent 配置
+ 工作区 bootstrap 文件
+ 已启用 Skills
+ Session 历史
+ Memory 检索结果
+ 本轮用户消息
+ 工具结果
这些内容的来源不同，可信度和生命周期也不同。工作区文件是用户可编辑的长期配置，Session 历史是会话事实，Memory 是经过提取和检索的可复用信息，工具结果则可能来自不可信网络。把它们全部拼成一段没有来源标识的文本，会让排障和安全审计变得困难。
4. 工具调用和事件流
Agent Runtime 会产生 assistant、tool 和 lifecycle 三类事件。工具事件需要区分开始、进度、结果和错误；最终回复则需要去除重复的工具确认，并根据渠道能力分块发送。
如果模型输出触发了工具，工具完成并不代表整个运行结束。模型还可能根据结果继续调用工具，或进入一次只生成最终答案的收尾调用。只有当运行完成、失败、取消或超时，并且终态已经写入，外部调度器才能把这次执行视为 settled。
5. Compaction、重试和超时
上下文接近模型上限时，系统需要压缩历史，而不是无限追加。Compaction 期间要记录事件，重试时清空临时缓冲，避免把第一次尝试的输出重复发送。
超时也有层次：agent.wait 只是等待上限，Agent Runtime 的 timeoutSeconds 才负责中止底层执行。对长时间任务而言，这个区别非常重要，否则调用方会把“暂时没有结果”误判为“任务已经停止”。
五、Workspace、Session 与 Memory
Workspace 是 Agent 的工作目录和人格入口
每个 Agent 有一个工作区。官方运行时文档列出了一组常见启动文件：
| 文件 | 作用 |
|---|---|
| AGENTS.md | 操作规约和记忆提示 |
| SOUL.md | 人格、边界和语气 |
| IDENTITY.md | 名称、风格和标识 |
| USER.md | 用户画像和称呼 |
| BOOTSTRAP.md | 新工作区的一次性初始化流程 |
| MEMORY.md | 根目录长期记忆文件 |
这些文件不是装饰性的配置。新 Session 启动时，运行时会读取并注入 Project Context；文件过大时会被截断，缺失文件也会留下明确标记。这样做让人格、操作规范和长期偏好可以版本化，但也意味着工作区文件本身是 Prompt Injection 的输入面，需要像代码一样审查。
Session 状态不等于原始聊天文件
当前运行中的 Session 状态保存在每个 Agent 的 SQLite 数据库中。Transcript JSONL 仍可能作为迁移、导入、导出或归档材料存在，但运行时不会把任意工具的 Session 目录自动当作自己的历史。
因此，备份不能只复制一个聊天目录。至少需要考虑：
- Agent 配置和工作区文件；
- SQLite Session 数据库；
- 记忆索引和来源信息；
- 渠道配对状态与凭据；
- 插件和 Skill 的版本；
- 尚未完成的自动化任务。
记忆要有来源和删除边界
向量检索只能回答“语义上相似”，不能独立回答“现在是否应该使用”。一个可治理的记忆系统需要记录来源、时间、主体、置信度和失效关系。
OpenClaw 的记忆能力可以看成三条链路：
会话事实 → 记忆提取 / 归纳 → 记忆索引
↓
当前请求 → 检索 / 重排 / 过滤 → 注入上下文
删除也不是简单删除一行数据。已进入 Session transcript、外部备份、第三方渠道或插件自有存储的内容，可能拥有不同的生命周期。官方文档对“可追踪记忆”和“原始 transcript、外部副本”作了区分，因此文章不能把 memory forget 描述成全链路擦除保证。
六、插件化带来的能力与边界
OpenClaw 的插件化解决了一个长期运行系统的扩展问题：核心 Gateway 不需要为每个渠道、模型和工具写一套固定分支。新能力可以通过注册点加入，再由配置决定是否启用。
但插件化有两个容易被忽略的代价：
- 加载边界不等于安全边界。 插件 manifest 可以帮助发现能力和校验入口，却不等于插件运行时被沙箱隔离。
- Skill 不等于可信代码。 Skill 目录中的说明、脚本和依赖都可能改变 Agent 的行为，安装前应该检查来源、版本、权限和网络访问。
- MCP 扩大了连接面。 MCP 可以把外部工具服务器接入 Agent，但每一个服务器都需要单独评估身份、凭据、数据出口和失败语义。
- 模型可替换不等于行为完全一致。 不同 Provider 对工具调用、流式事件、上下文限制和终止信号的处理可能不同，运行时需要保留自己的生命周期控制。
七、多 Agent、Cron 与主动执行
多 Agent 路由的本质是把“谁来处理”和“如何处理”拆开。可以按照 Agent、工作区、渠道、发送者或会话规则选择不同的运行时配置。这样，一个 Agent 可以负责编码，另一个 Agent 负责资料检索，但它们仍然要受到 Gateway 的会话可见性和消息权限约束。
主动执行能力通常来自 Cron、Webhook、Heartbeat 和内部 Hook：
定时器 / Webhook / Heartbeat
↓
创建或恢复 Session
↓
按既定 Agent 配置运行
↓
工具调用与结果持久化
↓
向指定渠道或会话投递
这条链路把 Agent 从“等待用户输入”变成“可能在无人值守时行动”。因此，自动化任务必须有明确的触发身份、目标会话、最大运行时间、失败重试和投递结果。调度成功、模型执行成功、消息投递成功是三个不同的状态，不能合并成一个布尔值。
八、安全模型：可信 Gateway 与不可信执行面
OpenClaw 的核心安全叙事不是“模型会遵守提示词”，而是尽量把权限决策放在代码和运行时边界中。官方信任边界文档把 Gateway 描述为拥有渠道连接、配置、凭据、策略和版本化状态的可信控制面；工具执行可以被放到 Docker、Podman、SSH、OpenShell、节点或云 Worker 中。The trust boundary 对这条边界给出了清晰示意。
默认模型是单一可信边界
默认安装面向一个信任操作者。沙箱默认关闭时，主 Session 的 exec 可能直接在 Gateway 主机执行；一个 Gateway 也不是互相敌对用户之间的强多租户隔离边界。
因此，下面两种部署不能混为一谈：
- 个人助手：操作者信任自己的渠道、插件和工作区，追求低摩擦；
- 团队或混合信任部署：需要不同用户之间的会话隔离、角色限制、沙箱、凭据分离和独立 Gateway。
“配置支持团队”不代表“默认配置已经完成租户隔离”。
策略必须在模型之外执行
工具是否存在、是否允许执行、是否需要审批，应该由工具策略和运行时权限决定，而不是只写在 System Prompt 里。Prompt 可以帮助模型理解边界，但不能阻止恶意或被注入的模型调用一个已经暴露的高权限工具。
入口侧至少要检查：
- Gateway 是否仍绑定在回环地址；
- 远程访问是否启用了认证和加密隧道；
- DM 是否处于 pairing 或 allowlist 模式；
- 群组是否有成员白名单和 mention gate；
- Session 是否按渠道和发送者隔离；
- 工具和跨 Agent 消息是否符合最小权限；
- Secret 是否通过受控引用提供，而不是直接写进 Prompt；
- 原生插件、Skill 和 MCP Server 是否固定版本并经过审查。
沙箱能缩小爆炸半径，但不能自动解决所有问题
沙箱可以限制文件系统、网络、用户身份和可执行命令，但隔离效果仍取决于挂载目录、网络策略、工具集合和凭据配置。一个挂载了整个主目录、拥有网络和宿主凭据的“沙箱”，实际保护能力会非常有限。
更稳妥的顺序是：
先限制入口 → 再限制工具 → 再隔离执行 → 最后开放必要能力
OpenClaw 提供 openclaw sandbox explain 查看有效执行姿态，提供 openclaw security audit 检查配置漂移。审计命令本身不是安全认证，它只是把若干高风险配置转换成可检查的结果。
九、几个值得提前设计的故障场景
旧运行覆盖新运行
用户快速发送两条互相矛盾的消息，旧运行晚于新运行完成。如果没有 Session 队列和 writer fence，旧结果可能覆盖新 transcript，渠道也可能收到错误顺序的回复。
工具已经执行但最终回复失败
工具可能已经创建文件、发送消息或修改远程资源，但模型的最终收尾调用失败。系统必须区分“副作用已经发生”和“用户是否收到确认”，否则重试会导致重复操作。
渠道投递成功但状态写入失败
如果消息已经发到 Telegram，而本地 Session 还没有记录投递结果，恢复逻辑可能再次发送。发送、持久化和重试需要独立的幂等键与结果状态。
记忆提取错误
模型把临时计划写成长期偏好，下一次召回后又影响了决策。记忆写入应有类型、置信度、时间和来源，必要时要求用户确认；删除和纠正要能传播到索引和缓存。
Prompt Injection 进入工具链
外部网页、邮件、文档或 Skill 说明可能包含“忽略之前规则”的文本。模型可以理解这些文本，但权限系统不能因为模型相信它们就自动放开工具。来源标记、工具白名单、敏感操作审批和网络出口限制应在模型之外生效。
十、上线前检查清单
可以把一次 OpenClaw 部署检查压缩成以下顺序：
- 确认信任边界：一个 Gateway 服务哪些用户、渠道和凭据？混合信任用户是否应该拆成多个 Gateway？
- 确认入口策略：回环绑定、反向代理、Tailscale、WebSocket 认证、DM pairing 和群组 allowlist 是否明确？
- 确认工具权限：默认 Agent 是否真的需要 shell、浏览器、文件写入、跨渠道消息和子 Agent？
- 确认执行隔离：哪些任务在主机执行，哪些任务进入 Docker、Podman、OpenShell、节点或云 Worker？
- 确认状态恢复：工作区、SQLite、配对状态、插件版本、记忆和自动化任务是否可以恢复？
- 确认可观测性：是否能区分请求已接受、模型执行完成、工具副作用完成和消息投递成功？
- 确认审计动作：运行 openclaw security audit，查看 openclaw sandbox explain，并把高风险检查项纳入变更流程。
- 确认升级策略：升级前备份版本化状态，先在隔离环境验证迁移和插件兼容性。
结语：OpenClaw 是一个 Agent 控制面
如果只看“能不能让模型调用工具”，OpenClaw 和许多 Agent SDK 没有本质差异。真正的区别在于它把 Agent 放进了一个长期运行的控制面：
- 控制面：Gateway、渠道、认证、路由、策略和事件；
- 执行面：模型、工具、Skill、节点、沙箱和远程 Worker；
- 状态面：Session、Workspace、Memory、SQLite、Transcript 和审计；
- 扩展面：Channel、Provider、Plugin、MCP、Cron、Webhook 和多 Agent。
这套设计带来持续运行、跨渠道和主动执行能力，也带来更大的权限和状态复杂度。工程上最重要的判断不是“模型够不够聪明”，而是每一次输入、每一个工具、每一条记忆、每一个副作用和每一次投递，是否都有清晰的身份、生命周期、失败语义和审计边界。
OpenClaw 的价值正在这里：它把 Agent 从一次性的模型调用，推进成一个可以被部署、观察、恢复和治理的系统。但它的安全性也不会自动从“开源”或“自托管”中产生，仍然取决于 Gateway 边界、工具策略、执行隔离、凭据管理和操作者是否理解这些默认值。