关于 OpenClaw,你需要读的最后一篇文章

我知道自己有点晚了，但最近我确实频繁使用了openclaw。

用着用着，我不再只是把它当成一个工具，而是开始好奇：它底层到底发生了什么？

因为很明显，它绝不是简单地把一个 prompt 发给大模型，然后拿回一个回答。它背后发生的事情要复杂得多。

于是，我花了一些时间研究它的架构。越理解它，我越能体会到在整体设计上的用心。

这篇文章，我会带你拆解 OpenClaw 的底层运行机制，帮助你建立一个清晰的心智模型：像 OpenClaw 这样的系统，到底是如何被设计出来的。

两大核心支柱

从高层来看，OpenClaw 主要围绕两个核心层构建。

Gateway：通信与控制层
它负责接收来自不同来源的输入，判断应该由哪个 Agent 处理，解析会话，并编排整个执行流程。

Agent Runtime：执行层
这一层由 Pi 驱动，Pi 是 @badlogicgames 构建的系统。真正的任务执行发生在这里：模型运行、工具调用、任务一步步推进，最终完成目标。

只要理解了这两层如何交互，整个系统的其余部分就会变得非常容易理解。

一条消息如何流经 OpenClaw

下面我们来看，当一条消息进入系统后，OpenClaw 内部究竟发生了什么。

OpenClaw 架构

1. Channel Plugin：通道插件

OpenClaw 中的每一次交互，都是从一个通道插件开始的。

通道插件负责把 OpenClaw 连接到外部平台，例如 Slack、WhatsApp、Discord、iMessage 等。每个平台都有自己的插件，而每个插件内部又有多个适配器，用来处理具体职责，例如账号配置、将传入消息标准化为统一格式，以及把输出结果格式化为对应平台需要的样子。

当消息离开这一层时，它已经被转换成一种标准化格式，后续系统中的其他部分就可以统一处理它。

2. Gateway 路由与 Agent 选择

当消息到达 Gateway 后，Gateway 会评估路由绑定规则，判断应该由哪个 Agent 来处理这条消息。

每个 Agent 都运行在自己独立的配置环境中。这包括独立的 workspace、状态目录以及 session store。这样的隔离非常重要，因为它允许不同 Agent 在彼此独立的情况下运行，同时又能被同一个系统统一编排。

从本质上说，Gateway 正在判断：这次请求应该发往哪里，以及应该以什么方式被处理。

Gateway 不只是决定请求去哪里，它还负责协调执行过程。

如果某条消息到达时，同一个 session 下已经有一个 Agent run 正在运行，那么这条新消息不会被立即处理，而是会进入队列，等当前 run 完成后再继续执行。

这样做可以避免同一个 session 中出现重叠执行，确保多轮对话中的上下文保持一致。

3. Session 解析与持久化

在选定 Agent 之后，Gateway 会加载已有 session，或者创建一个新的 session。

在理解 Gateway 如何做出这个判断之前，我们需要先理解 OpenClaw 是如何持久化 session 数据的。

OpenClaw 的 session 持久化分为两层。

OpenClaw Session 管理

Session store：轻量级元数据层
它以 key-value map 的形式实现。每个 sessionKey 都会映射到一个 SessionEntry，其中包含当前 session ID、updatedAt 以及其他 session 级别的信息。

Transcripts：真实对话历史层
这里存储真正的对话历史。它是一个 append-only log，也就是只追加、不覆盖的日志结构。每一条记录都会和之前的记录关联起来，形成一种类似树状的结构。每当新消息进入时，系统会利用这些历史记录重建上下文。

当一条新消息到达时，Gateway 会根据传入请求中的信息生成一个 sessionKey。

系统究竟是继续使用已有 session，还是启动一个新的 session，取决于 sessionKey 对应的 updatedAt 时间戳，以及为该 Agent 配置的 reset policies。

这些策略可以定义多种条件，例如每天在固定时间重置、长时间无交互后超时重置，或者通过命令手动触发重置。

如果根据这些条件判断当前 session 已经过期，系统就会创建一个新 session。否则，它会复用已有 session，并保留其中最新的上下文。

4. System Prompt 构建

当 session 解析完成后，OpenClaw 会开始构建 system prompt。

这是系统把多个组件组合成一个完整 prompt，并发送给模型的地方。

需要注意的是：OpenClaw 会为每一次 Agent run 构建一个自定义 system prompt。

OpenClaw System Prompt

最终发送给模型的 prompt，是多个组件组合后的结果。

工具列表与描述
定义所有可用的内置工具和自定义工具，并说明 Agent 可以如何使用它们。

Session history
提供过往对话上下文，让模型能够连贯地继续当前交互。

Skills
注入可复用的能力或行为，让 Agent 在相关场景中调用。需要注意的是，在这个阶段只注入 metadata。

Memory system
引入当前 session 之外的长期知识或历史经验。OpenClaw 会把这些 memory 作为普通 Markdown 文件存储在 Agent 的 workspace 中。长期记忆保存在 memory.md 文件里，运行过程中的上下文和每日笔记则会保存在 memory 目录下按时间戳命名的文件中。这样，Agent 就能够跨 session 持久化并复用知识。

Workspace files
包含结构化文件，例如 IDENTITY.md、USER.md、AGENTS.md、SOUL.md 等，用来定义 Agent 的行为、身份以及环境上下文。

Time
加入时间上下文，例如当前 UTC 时间和用户所在时区，支持模型进行时间敏感的推理。

User message
也就是用户当前输入，Agent 需要基于这条消息完成响应。

这些内容会被组合成最终 prompt，并直接影响模型如何理解请求、如何执行任务。

这一步非常关键，因为 Agent 的行为在很大程度上取决于这个 prompt 是如何构造的。

5. Agent Runtime 与执行循环

当 system prompt 构建完成后，执行流程会进入 Agent Runtime 内部的一个 Pi session。

这个 session 相当于本次任务的执行上下文。根据 session 状态，它可以是新创建的，也可以是复用已有的。

随后，组装好的 prompt 会被传入这个 session，正式开始执行。

从这里开始，Pi agent core 会运行一个 agent loop。

在每一步中，模型都会处理当前上下文，决定下一步动作：要么生成回答，要么触发一次工具调用。

这个动作的结果随后会被追加回 session context，循环继续推进。

在这个循环过程中，Agent 也可以使用 skills 和 memory。

与此同时，Agent 可以从 memory 中检索相关信息来辅助决策，也可以把新的信息写回 memory，让有价值的知识在当前 session 之外继续保留下来。

同时，runtime 会在每一步产生结构化事件。系统正是依靠这些事件来流式输出中间结果，并保持对 Agent 正在做什么的可见性。

这个过程会一直持续，直到任务完成。

6. 执行结束后发生什么

当响应生成后，控制权会回到 Gateway。

除了最终响应之外，Agent Runtime 还会产出更新后的 session state。

其中包括 session metadata，以及最新的 transcript entries，例如 Assistant 的回复、工具调用和工具输出。

随后，Gateway 会把这些信息持久化。

session store 会更新最新的元数据，transcripts 也会追加新的对话事件。

这确保了未来的交互可以在同一个 session 中无缝继续。

最后，响应会被传回 channel plugin。通道插件会根据目标平台的要求格式化响应，并把它发送回最初的来源。

OpenClaw 中触发事件的几种方式

OpenClaw 之所以给人一种响应迅速、始终在线的感觉，一个重要原因是：Agent 并不只是由用户消息触发。

系统有多种方式可以主动启动执行流程，这让它能够响应事件、在后台执行检查，并自动化处理工作流。

Messaging channels：消息通道
这是最直接的 Agent 触发方式。来自 Slack、WhatsApp、Discord 或 Web 界面的输入，会通过 channel plugins 进入系统，并被立即路由和处理。

Heartbeat：心跳触发
Heartbeat 是一种周期性触发机制。系统会按照固定间隔调用 Agent，默认通常是每 30 分钟一次，用来检查当前状态，并判断是否需要执行某些动作。这让 OpenClaw 不必等待用户输入，也能持续监控状态。

Cron jobs：定时任务
这些是基于预设时间表运行的计划触发器。例如每天早上某个固定时间触发 Agent，让它执行一项例行任务。

Webhooks：外部事件触发
Webhook 是来自外部系统的触发事件，可以调用 Agent 执行流程。例如，收到 Stripe 的支付事件后，可以触发 OpenClaw 内部的工作流，处理相关信息并更新记录。

Hooks：内部状态触发
Hooks 是系统内部基于状态变化生成的触发器。例如，当一个任务完成后，hook 可以触发另一个动作，比如发送通知。

除此之外，还有一些程序化触发方式，例如 CLI 操作、Web 界面动作，甚至一个 Agent 调用另一个 Agent。

这些机制支持系统中不同部分之间实现更深层的自动化和协同。

总体来看，这些触发机制让 OpenClaw 超越了简单的“请求—响应”交互模式。

它更像是一个持续运行的系统：能够响应、监控，并在必要时自主行动。