真实参考资料

《人工智能：现代方法（第4版）》
https://docs.openclaw.ai
李宏毅课程
Generative to Agentic AI: Survey, Conceptualization, and Challenges
A survey on large language model based autonomous agent
A survey on large language model based autonomous agents
The rise and potential of large language model based agents: a survey

一.什么是智能体

任何通过传感器(sensor)感知环境(environment)并通过执行器(actuator)作用于该环境 的事物都可以被视为智能体(agent)。

一个人类智能体以眼睛、耳朵和其他器官作为传感器，以手、腿、声道等作为执行器。

二.从生成式 AI 到智能体 AI

要理解人工智能的演进，我们必须明确传统生成式 AI（Generative AI）与自主智能体 AI（Agentic AI）在底层逻辑上的核心差异。

• 核心概念与界定：
  • 生成式 AI (Generative AI)： 这类系统基于基础模型，主要根据用户的自然语言指令被动地生成数字内容（如文本、图像等） 。它们通常是被动响应的，局限于单轮或简单的对话互动，缺乏环境感知能力和自主纠错能力 。
  • 智能体 AI (Agentic AI)： 同样基于基础模型，但智能体 AI 能够根据自然语言指令，在动态环境中自主执行复杂任务 。它具备复杂的推理能力（包括规划和反思），并能与环境、外部工具以及其他智能体进行主动交互 。
• 底层的范式转移：
  • 生成式 AI 具有“被动响应（Reactive）”的局限性，缺乏目标持久性（Goal Persistence）和状态管理能力 。
  • 相比之下，Agentic AI 实现了“主动目标导向（Proactive & Goal-directed）”的跨越 。通过引入环境感知、持久记忆和规划执行引擎，它完成了从单纯的“内容生成”到“结果交付”的转变 。
• 向 Agentic AI 演进的四大驱动力（弥补 GenAI 的短板）：
  • 补足执行能力： 生成式 AI 难以处理多步复杂任务，而 Agentic AI 能通过自主规划和工具交互，端到端地完成多步工作流 。
  • 摆脱指令依赖： 生成式 AI 极度依赖用户给出详尽的提示词，而 Agentic AI 仅需要一个高层次的宏观目标，即可自主推导并拆解执行步骤 。
  • 突破上下文与学习限制： 生成式 AI 往往受限于较小的上下文窗口，缺乏即时学习能力 。Agentic AI 则可通过外部数据库检索（如向量数据库），在环境中通过试错进行持续学习和经验积累 。
  • 显著降低幻觉： 借助多路径的一步步推理、自我验证反馈机制以及外部工具调用，Agentic AI 能够大幅降低模型自信生成错误信息（幻觉）的概率

三.智能体 AI

3.1 A survey on large language model based autonomous agents

现代智能体 AI 的通用架构建立在学术界公认的“感知（Perception）- 规划（Planning）- 执行（Action）”的闭环机制之上 。为了最大化大语言模型（LLM）的能力，权威综述提出了一套包含四个高度交互模块的统一架构框架 。

1. 角色画像模块 (Profiling Module)

• 核心作用： 该模块用于识别和定义智能体的特定角色、动机或人格特征，是智能体开展工作的基础背景 。
• 生成策略： 目前主要有三种构建方式 。第一种是手工制作法，即人工手动指定智能体的属性与背景 。第二种是LLM 生成法，基于初始设定的种子规则，利用 LLM 自动批量扩展生成智能体画像 。第三种是数据集对齐法，直接从真实世界的人口数据集中提取属性，以精准反映真实人群特征 。

2. 记忆模块 (Memory Module)

• 核心作用： 记忆系统用于记录智能体对环境的感知和过往行为，从而赋予智能体状态一致性与持续学习的能力，以指导未来行动 。
• 记忆结构与格式： 记忆结构分为统一记忆（通过提示词上下文模拟短期记忆）和混合记忆（结合短期缓冲与长期外部向量存储） 。信息通常通过自然语言、嵌入向量 (Embeddings)、外部数据库或结构化列表进行存储 。
• 核心记忆操作：
  • 读取： 智能体基于最近性、相关性和重要性三个维度提取有价值的信息 。
  • 写入： 负责将新信息存入记忆，同时需要处理记忆重复和记忆溢出（如采用 FIFO 机制）的问题 。
  • 反思 (Reflection)： 赋予智能体自我总结的能力，能够将底层碎片化的记忆合成为高层次、抽象的洞察 。

3. 规划模块 (Planning Module)

• 核心作用： 规划模块使智能体能够将复杂任务解构为更简单的子任务，表现为类似于人类的“慢思考”过程 。
• 无反馈规划： 包括单路径推理（如经典的思维链 CoT）、多路径推理（如思维树 ToT，支持广度或深度优先搜索寻找最优解），以及利用传统的外部规划器将任务转为特定语言交由外部求解 。
• 有反馈规划： 智能体在行动后接收反馈以迭代修正原始计划 。反馈信号的来源涵盖外部环境（如任务完成信号或编译器报错）、人类的主观反馈以及模型内部自身的自我评估 。

4. 行动模块 (Action Module)

• 核心作用： 将智能体的决策转化为具体的输出，并负责与外部环境进行真实的交互 。
• 行动目标与触发： 行动目标主要包含任务完成、与其他智能体/人类进行通信，以及对未知环境的探索 。行动可以通过记忆检索触发，也可以严格遵循预设的计划步骤来触发 。
• 行动空间： 智能体的行动能力主要依赖两方面：一是 LLM 的内部知识（如常识理解、对话生成），二是外部工具的使用（如调用各类 API、查询外部数据库、执行代码解释器或调用外部专家模型） 。

3.2 The rise and potential of large language model based agents: a survey

四.OpenClaw 的运行机制

4.1 李宏毅课程

openclaw其实是AI Agent中不是AI的部分

语言模型真正做的事为文字接龙

• 语言模型的输入加输出的长度是有限的（context window）
  • 每一个模型的上限都不同（今日比较好的模型通常可以输入上百万token）
  • 输入越长，就算还没有到上限，往往就无法准确的接龙
    

openclaw在发送消息给语言模型前会从自身相关资讯的文件里面加一部分内容，也就是system prompt（真的很长，每次要放很多东西）。
system prompt的内容如下：

• 与身份有关的资讯
  • SOUL.md
  • IDENTITY.md
  • USER.md
  • MEMORY.md
• 有哪些工具使用（以及怎么用）
• 模型的行为：AGENTS.md
• 有哪些“SKILL”可以使用
• 之前的记忆去哪里找

SOUL.md：他是谁，他有什么目标
IDENTITY.md：名字，爱好
USER.md：使用者信息
MEMORY.md：行文准则，长期记忆

当有多轮对话的时候，会把以前的对话信息丢过去

AI Agent会把你的问题加上system prompt丢给语言模型，其中包含了工具相关的使用。语言模型会判断自己要使用什么工具，然后告诉龙虾。龙虾就会执行这个工具，再把得到的信息和以前的对话信息一起发过去。

OpenClaw强大的原因：可以使用exec这个工具来执行任何shell command(文字指令)。

• openClaw多数时候都是透过shell command 来操控电脑

openclaw会读取网页资讯，所以可能会执行不好的指令

可能的防御方法：

• 语言模型层面的防御：直接给指令让他写到MEMORY.md中
• Openclaw层面的防御：执行指令前问是否执行

龙虾可以产生小工具

特殊工具：Sub-agent

• 大龙虾召唤小龙虾，为了防止层层外包，不准小龙虾召唤小小龙虾
• 从大龙虾的角度，可以使Context window得到节省
• 使Context Engineering得到节省的技巧就叫Context Engineering
  
  
  

SKILL就是工作的SOP，只是一个md文档，因此可以和别人交换SKILL。要小心恶意的SKILL，防止下载木马病毒。一个SKILL的文档如下

当用户给出指令的时候，龙虾回去查找SKILL，然后将SKILL相关内容抽取出来塞到System Prompt。SKILL是按需读取的，用来减少token的使用

龙虾怎么进行记忆
上下文窗口永远是不够的，小龙虾可以清除所有的上下文。但有些记忆会被写到文字档里面，存在两种文档。

龙虾怎么读取记忆
使用memory_search与memory_get

避免比较弱的模型光说不做

心跳机制
心跳机制就是在龙虾会每隔一段时间给语言模型发信息，让语言模型看heartbeat.md有没有可以做的。也就是干些看看有没有新邮件之类的任务

Cron Job系统
也就是增加了一次额外的心跳。
优点是让龙虾可以等待，通过Cron Job可以去等待影片完成

Context Compression
当上下文过长的时候，龙虾就会把前面的上下文丢给语言模型进行摘要

4.2 官网

4.2.1 概述

4.2.1.1 OpenClaw是什么

OpenClaw 是一个自托管网关。

• 网关（Gateway）是计算机网络中的一种设备或服务器，用于连接不同网络或协议之间进行数据转发和处理。

你只需在自己的电脑（或服务器）上运行一个单一的 Gateway（网关）进程，它就会成为连接你的消息应用与随时待命的 AI 助手之间的桥梁 。

1. WhatsApp 收到用户消息
2. WhatsApp 适配器把消息交给 Gateway
3. Gateway 检查消息来源是否允许
4. Gateway 找到或创建对应 session
5. Gateway 把任务交给 embedded agent runtime
6. agent runtime 读取 workspace 中的启动文件
7. agent runtime 加载历史 session
8. agent runtime 组装 prompt
9. agent runtime 调用模型
10. 模型决定是否调用 tools / skills
11. 工具执行后把结果返回给 agent runtime
12. agent runtime 生成最终回复
13. Gateway 把回复发回 WhatsApp

4.2.1.2 核心功能

• Channels（渠道） 通过单一的 Gateway（网关），支持接入 Discord、iMessage、Signal、Slack、Telegram、WhatsApp、WebChat 以及更多通信平台 。
  • 每个channel都通过网关 (Gateway) 进行连接。文本消息在所有通道中均受支持；但媒体内容和表情回应 (reactions) 的支持情况因具体的通道而异。
• Plugins（插件） 在当前的常规版本中，捆绑的插件增加了对 Matrix、Nextcloud Talk、Nostr、Twitch、Zalo 等平台的支持，且无需用户进行单独安装 。
• Routing（路由） 支持多智能体（Multi-agent）路由分配，且每个会话都是相互隔离的 。
• Media（媒体） 支持处理图像、音频、视频和文档文件，并且具备图像与视频的生成能力 。
• Apps and UI（应用与用户界面） 提供 Web Control UI（网页控制面板）以及 macOS 系统的配套应用程序 。
• Mobile nodes（移动端节点） 提供 iOS 和 Android 系统的配套节点应用，支持设备配对、语音/文本聊天交互，以及丰富的设备控制指令 。

4.2.1.3 能力

对于大多数 agent，从内置工具类别开始，然后仅在 agent 需要看到更少工具或需要明确主机访问时调整策略。

如果你需要…	首选操作	然后阅读
让 agent 使用现有能力	Built-in tools	Tool categories
控制 agent 可调用内容	Tool policy	Tools and custom providers
教 agent 一套工作流程	Skills	Skills and Creating skills
添加新集成或运行时界面	Plugins	Plugins and Build plugins
后台或延迟运行任务	Automation	Automation overview
协调多个 agent 或 harnesses	Sub-agents	ACP agents and Agent send
搜索大型 PI 工具目录	Tool Search	Tool Search

4.2.2 网关架构

• 一个长期运行的单一 Gateway（网关）控制着所有的消息渠道 。
  • 无论你使用哪种聊天软件，网关都会通过底层的协议适配器（例如利用 Baileys 库解析 WhatsApp 协议，利用 grammY 库解析 Telegram 协议）将它们接入进来 。这种设计屏蔽了不同平台的接口差异，让背后的 AI 只需要处理统一的标准数据流 。
• 控制平面客户端通过 WebSocket 连接到默认的本地地址（127.0.0.1:18789）
  • 控制平面客户端是用来连接 Gateway，并对 Gateway 进行管理、控制、查看状态的软件。
  • 与传统的 HTTP 请求（客户端发一个请求，服务器回一个响应，然后连接就断开了）不同，WebSocket 建立的是一条持久的长连接。这使得 macOS App、CLI 等客户端可以实时接收到大模型流式输出的每一个字（Token）、工具执行的每一步进度，而不需要不断地去刷新/轮询服务器。
  • 控制平面客户端的常见形式有macOS APP：通过图形界面操作Gateway，CLI：命令行操作Gateway，Web UI通过浏览器管理界面。
• 节点（如 macOS/iOS/Android 或无界面设备）也通过 WebSocket 连接，但会明确声明自己是 role: node（角色：节点）并汇报自己的指令和能力 。
  • 节点就是接入 Gateway 的设备，它们可以提供一些能力给 Gateway 使用。
• 网关不仅是一个处理长连接的 WebSocket 服务器，它内部还集成了一个 HTTP 服务器，专门用来托管提供给用户查看的动态网页内容 。它直接复用了网关默认的 18789 端口 。

4.2.2.1 核心组件

1.网关

• 维护提供商（聊天平台）的连接 。
• 暴露一个带有类型定义的 WebSocket API（包括请求、响应和服务器推送事件） 。
• 根据 JSON Schema 验证入站数据帧 。
• 触发诸如 agent（智能体）、chat（聊天）、presence（在线状态）、health（健康状况）、heartbeat（心跳）、cron（定时任务）等事件 。

2.客户端（mac 应用 / 命令行 / 网页管理面板）

• 每个客户端维持一个 WebSocket 连接 。
  • 每个 mac 应用、命令行工具、网页管理面板，都会和 Gateway 建立一个长连接。
• 发送请求（如 health、status、send、agent、system-presence） 。
  • 客户端可以主动向 Gateway 发命令。
• 订阅事件（如 tick、agent、presence、shutdown） 。
  • 也可以订阅事件，等待 Gateway 主动通知。

3.节点（macOS / iOS / Android / 无头设备）

• 连接到同一个 WebSocket 服务器，并携带 role: node 标识 。
• 在连接时提供设备身份；配对是基于设备的（角色为 node），且审批记录保存在设备配对存储中 。
• 暴露诸如 canvas.*、camera.*、screen.record、location.get 等命令 。
• 协议细节请参阅：Gateway protocol（网关协议） 。

4.网页聊天

• 这是一个静态的 UI，使用 Gateway WebSocket API 来获取聊天记录并发送消息 。
• 在远程设置中，它与其他客户端一样通过相同的 SSH/Tailscale 隧道进行连接 。

5.pairing：配对
配对是设备连接 Gateway 前的信任机制。

6.Auth：认证

7.Remote access：远程访问

4.2.3 Agent runtime

4.2.3.1 概述

Agent runtime 是执行单轮智能体操作的核心组件
它会：

• 接收 prompt；
• 驱动模型输出；
• 处理原生工具调用；
• 将完成后的当前回合返回给 OpenClaw。

OpenClaw 运行一个单一的 embedded agent runtime，每个 Gateway 对应一个 agent process，并且它有自己的 workspace、bootstrap files 和 session store。

• Gateway 里面嵌入了一个 agent runtime，这个 agent runtime 负责运行 AI agent。
• 这个 runtime 有自己的工作区、启动文件、会话记录
• workspace 是 agent runtime 的工作目录。
• Bootstrap files是启动注入文件。
  • 新会话开始时，OpenClaw 会把这些文件内容塞进 agent 的上下文里。
  • 官方文档列出 OpenClaw 在 workspace 里期望存在这些用户可编辑文件：AGENTS.md、SOUL.md、TOOLS.md、BOOTSTRAP.md、IDENTITY.md、USER.md；在新会话的第一轮，OpenClaw 会把这些文件内容注入 agent 上下文。
    • AGENTS.md：操作规则、长期记忆
    • SOUL.md：人设、边界、语气
    • TOOLS.md：工具使用说明
    • BOOTSTRAP.md：第一次启动时的一次性流程（第一次运行 OpenClaw）
    • IDENTITY.md：agent 名称、风格、emoji
    • USER.md：用户信息、称呼偏好
• Session 是一段对话的记录和状态。

The embedded agent runtime is built on the Pi agent core (models, tools, and prompt pipeline). Session management, discovery, tool wiring, and channel delivery are OpenClaw-owned layers on top of that core.
嵌入式智能体运行时（embedded agent runtime）是基于 Pi 智能体核心（涵盖模型、工具和提示词管道）构建的。而会话管理（session management）、寻址（discovery）、工具接入（tool wiring）以及通道投递（channel delivery），则是搭建在该核心之上、属于 OpenClaw 自有的架构层级。

• prompt pipeline：把系统提示、用户输入、历史记录、工具结果等组织成模型输入的流程
• session management：管理不同会话的历史和状态
• discovery：发现可用能力、客户端、节点、工具或通道
• tool wiring：把工具接入到 OpenClaw，让 agent 能正确调用
• channel delivery：把 agent 的回复发送回 WhatsApp、Telegram、网页聊天等渠道

OpenClaw
├─ 自己负责的上层功能
│  ├─ session management：会话管理
│  ├─ discovery：发现机制，确定哪些工具和技能可以被智能体使用
│  ├─ tool wiring：将智能体调用的工具（系统命令、API）与实际实现绑定
│  └─ channel delivery：将智能体生成的消息发送到正确的聊天通道
│
└─ 底层依赖 Pi agent core
   ├─ models：大语言模型、技能模型等
   ├─ tools：系统命令、API 调用、消息工具等
   └─ prompt pipeline：生成 prompt、注入上下文、处理模板等

4.3.2.2 Tools：工具

Tools就是 agent 可以调用的实际能力。
工具是否存在由 OpenClaw 和配置决定，TOOLS.md 只负责写工具使用规范。

• 工具是 agent 可调用的类型化函数，例如 exec、browser、web_search、message、image_generate。
• 当 agent 需要读取数据、修改文件、发送消息、调用提供者或操作其他系统时使用工具。
• 可见工具以结构化函数定义发送给模型。
• 模型仅能看到符合当前 profile、允许/拒绝策略、提供者限制、沙箱状态、通道权限和插件可用性的工具。

4.3.2.3 Skills：技能

OpenClaw 按优先级加载技能：

1. 工作区：<workspace>/skills
2. 项目智能体技能：<workspace>/.agents/skills
3. 个人智能体技能：~/.agents/skills
4. 托管/本地：~/.openclaw/skills
5. 捆绑安装附带的技能
6. 额外技能文件夹：skills.load.extraDirs

• 系统提示包含 技能列表（名称 + 描述 + 路径）

• 技能是 SKILL.md 指令包，加载到 agent 提示中。

• 当 agent 已具备所需工具，但需要可重复工作流程、审核标准、命令序列或操作约束时使用技能。

• 技能可以存在于 workspace、共享技能目录、托管的 OpenClaw 技能根目录或插件包中。

4.3.2.3 Agent 流式执行与消息队列处理

1.agent 正在执行或流式回复时，用户发来新消息如何处理
queue mode 决定新消息的处理方式：

模式	作用
steer	新消息插入当前任务，影响当前任务后续方向
followup	新消息等当前任务结束后，作为下一轮处理
collect	多条新消息先收集，当前任务结束后一起处理

steer 模式不会立刻打断当前工具调用。它会等当前 assistant 已经开始的工具调用完成后，在下一次调用 LLM 之前，把新消息插入进去。

工具调用执行完  
↓  
插入用户新消息  
↓  
下一次调用 LLM  
↓  
agent 根据新消息调整方向

2.回复是否要分块发送
block streaming 指 agent 完成一个内容块后就立刻发送，而不是等整条回复全部完成。它默认关闭：

agents.defaults.blockStreamingDefault: "off"

相关配置：

配置	作用
blockStreamingBreak	控制什么时候算一个块结束
text_end	文本块结束就发送，默认值
message_end	整条消息结束后再发送
blockStreamingChunk	控制每块大小，默认约 800–1200 字符
blockStreamingCoalesce	合并小片段，减少刷屏

4.2.4 Agent Loop

Agentic loop 指 agent 一次完整、真实的运行过程：

输入接收 → 上下文组装 → 模型推理 → 工具执行 → 流式回复 → 持久化保存

4.2.4.1 入口点

Entry points 指 启动一次 agent loop 的入口方式。

OpenClaw 主要有两种入口：

入口	含义	适用场景
Gateway RPC: agent / agent.wait	通过 Gateway 的 WebSocket API 调用 agent	App、网页管理面板、自动化程序等客户端使用
CLI: agent	通过命令行执行 agent 命令	用户在终端里手动触发

• agent 用来启动一次 agent 运行。
• agent.wait 用来等待某次 agent 运行结束，并返回状态或结果。
• RPC 是一种计算机通信协议。它允许运行在一台计算机上的程序，像调用本地函数一样，去调用另一台计算机（或另一个进程）上的函数。

4.2.4.2 OpenClaw的Agent运行流程

OpenClaw 收到一次 agent 请求后，如何创建任务、运行 agent、转发过程事件，并返回最终状态。

整体流程可以理解为：

客户端发起 agent 请求
↓
Gateway 接收并创建任务
↓
返回 runId
↓
真正运行 agent
↓
agent 调用模型和工具
↓
持续产生事件流
↓
任务结束，返回最终状态

1. agent RPC
当客户端调用 agent 时，Gateway 不会等 agent 完成才回复，而是先做基础检查：

检查参数是否合法
↓
确定 sessionKey / sessionId
↓
保存 session 元数据
↓
立即返回 runId 和 acceptedAt

其中：

• session 元数据：描述数据的数据。
  • 帮助OpenClaw知道这个任务的相关信息
• runId：本次 agent 任务的编号， acceptedAt：务被接收的时间
  • 让客户端之后可以追踪这次任务

2.agentCommand：开始调度任务
agentCommand 负责正式运行 agent 前的准备工作：

- 解析模型 + 思考 (thinking) / 详细 (verbose) / 追踪 (trace) 的默认设置
- 加载技能快照 (skills snapshot)
- 调用 `runEmbeddedPiAgent` (pi-agent-core 核心运行时)
- 如果嵌入式循环没有发出结束或错误事件，则主动发出 lifecycle end/error (生命周期结束/错误) 事件。

其中 skills snapshot 是指：在任务开始时固定当前可用的 skills 状态，避免任务运行中途 skills 改变，导致行为不一致。

3.runEmbeddedPiAgent：真正执行 agent
runEmbeddedPiAgent 是真正让 agent 跑起来的核心部分。

• 在 OpenClaw 中，runEmbeddedPiAgent 触发的这一次 Pi session，就是一次完整的、未被中断的 ReAct (Reason + Act) 物理闭环。

它主要负责：

• 通过队列控制任务顺序
  • 判断这个任务能不能现在跑；如果同一个 session 里已经有任务在跑，就先排队
  • 避免同一个会话里多个任务同时执行，导致回复顺序和历史记录混乱
• 创建 Pi session
  • 给 Pi agent core 创建一个本次运行要用的会话对象，里面包含模型、认证信息、历史上下文等
  • Pi agent core 需要一个“运行环境”才能开始调用模型和工具
• 订阅 Pi 事件
  • OpenClaw 开始监听 Pi agent core 发出的运行过程事件
  • OpenClaw 需要知道 agent 什么时候开始、什么时候调用工具、什么时候输出内容、什么时候结束
• 转发 assistant / tool 的流式输出
  • 把 Pi agent core 产生的 assistant 输出片段、工具执行过程，转成 OpenClaw 的事件流发给客户端
  • 让用户或控制界面能实时看到 agent 正在做什么
• 检查超时
  • 给本次运行设置最长执行时间，超过就中止
  • 防止模型或工具卡死，任务无限运行
• 返回最终内容和用量信息
  • 任务结束后，把最终回复和运行统计返回给 OpenClaw
  • OpenClaw 需要把最终结果发回聊天平台，并记录本次运行消耗

所以你在 WhatsApp 上连续发三条消息：
第一条：帮我总结项目
第二条：再列出风险
第三条：翻译成英文
OpenClaw 可能是：
同一个 WhatsApp OpenClaw session
├─ 第一次 agent run → 创建一个 Pi session
├─ 第二次 agent run → 创建一个 Pi session
└─ 第三次 agent run → 创建一个 Pi session

4.subscribeEmbeddedPiSession：转换事件流

Pi agent core 的内部事件
        ↓
subscribeEmbeddedPiSession 监听并转换
        ↓
OpenClaw 能识别的事件流
        ↓
控制 UI / Telegram / WhatsApp / WebSocket 客户端

Pi agent core 会产生很多内部事件，例如：

• 工具开始执行
• 工具返回结果
• assistant 正在输出文字
• 任务开始
• 任务结束
• 任务出错
  subscribeEmbeddedPiSession 会把这些事件转换成 OpenClaw 的事件流：

Pi 事件	OpenClaw stream
工具事件	stream: "tool"
assistant 输出片段	stream: "assistant"
生命周期事件	stream: "lifecycle"

lifecycle 事件有三种阶段：

phase	含义
start	任务开始
end	任务正常结束
error	任务出错结束

5.agent.wait：等待结果
因为 agent 请求一开始只返回 runId，所以如果客户端想等待任务结束，可以调用 agent.wait。

它会等待某个 runId 对应的任务结束，然后返回：

status
startedAt
endedAt
error

其中 status 可能是：

状态	含义
ok	正常完成
error	运行出错
timeout	等待超时

注意：agent.wait 超时通常只是“等待超时”，不一定代表 agent 本身已经停止。

1. 流式回复：OpenClaw 支持增量输出，让用户无需等待整个回答完成就能看到部分内容，推理过程也可独立展示。
2. 工具执行：智能体可以调用各种工具，工具执行过程被系统跟踪、结果清理并防止重复发送。
3. 回复处理：最终发送的消息会整合智能体回答、工具摘要和错误信息，同时过滤空消息和重复项，确保输出稳定可靠。

4.2.4 System prompt

• OpenClaw 每次运行智能体（agent run）都会生成一个 自定义系统提示（system prompt）
• 这个提示 由 OpenClaw 管理，不使用 pi-coding-agent 的默认 prompt
• 系统提示被注入到每次智能体运行中，用于：
  • 提供上下文
  • 指导模型行为
  • 指明工具、权限和安全规则

4.2.4.1 结构

该 prompt 被有意设计得比较紧凑，并使用固定 section：

• Tooling：结构化工具的权威来源提醒，以及运行时工具使用指导。
• Execution Bias：简洁的执行推进指导：对可执行请求在当前回合内采取行动；持续推进直到完成或受阻；从较弱的工具结果中恢复；实时检查可变状态；在最终回复前进行验证。
• Safety：简短的安全护栏提醒，避免追求权力的行为或绕过监督。
• Skills（可用时）：告诉模型如何按需加载 skill 指令。
  • 当存在符合条件的 skills 时，OpenClaw 会注入一个紧凑的 available skills list，即 formatSkillsForPrompt，其中包含每个 skill 的 文件路径。Prompt 会指示模型使用 read 去加载列表中指定位置的 SKILL.md。
  • name + description + location
• OpenClaw Self-Update：说明如何使用 config.schema.lookup 安全地检查配置，使用 config.patch 修补配置，使用 config.apply 替换完整配置，以及只有在用户明确请求时才运行 update.run。仅限 owner 使用的 gateway 工具也会拒绝重写 tools.exec.ask / tools.exec.security，包括会规范化到这些受保护 exec 路径的旧版 tools.bash.* 别名。
• Workspace：工作目录（agents.defaults.workspace）。
• Documentation：OpenClaw 文档的本地路径（repo 或 npm package），以及什么时候应该读取这些文档。
• Workspace Files (injected)：表示 bootstrap 文件会包含在下方。
• Sandbox（启用时）：表示当前是沙箱化 runtime、沙箱路径，以及是否可以使用 elevated exec。
• Current Date & Time：用户本地时间、时区和时间格式。
• Reply Tags：受支持 provider 的可选回复标签语法。
• Heartbeats：当默认 agent 启用 heartbeats 时，heartbeat prompt 和 ack 行为。
• Runtime：host、OS、node、model、repo root（检测到时）、thinking level（单行）。
• Reasoning：当前可见性级别，以及 /reasoning 切换提示。

Tooling section 还包括针对长时间运行任务的运行时指导：

• 对于未来跟进任务（check back later、提醒、周期性工作），使用 cron，而不是 exec sleep 循环、yieldMs 延迟技巧，或反复进行 process 轮询
• 只有对于“现在启动，并继续在后台运行”的命令，才使用 exec / process
• 当 automatic completion wake 启用时，只启动一次命令，并依赖基于推送的唤醒路径；当它产生输出或失败时会唤醒
• 当需要检查正在运行的命令时，使用 process 查看日志、状态、输入或进行干预
• 如果任务更大，优先使用 sessions_spawn；sub-agent 的完成是基于推送的，并会自动向请求者回报
• 不要在循环中轮询 subagents list / sessions_list，只是为了等待完成

当实验性的 update_plan 工具启用时，Tooling 还会告诉模型：只在非平凡的多步骤工作中使用它；始终保持且只保持一个 in_progress 步骤；并避免每次更新后重复整个计划。

System prompt 中的安全护栏是建议性的。它们指导模型行为，但不强制执行策略。对于硬性执行，应使用 tool policy、exec approvals、sandboxing 和 channel allowlists；operator 按设计可以禁用这些机制。

在具有原生 approval cards/buttons 的 channel 上，runtime prompt 现在会告诉 agent 优先依赖该原生 approval UI。只有当工具结果说明 chat approvals 不可用，或者手动批准是唯一方式时，才应该包含手动 /approve 命令。

4.2.4.2 Prompt模式

OpenClaw 可以为 sub-agent 渲染更小的 system prompt。Runtime 会为每次运行设置一个 promptMode，但这不是面向用户的配置

• full（默认）：包含上面提到的所有 section。
• minimal：用于 sub-agent；会省略 Skills、Memory Recall、OpenClaw Self-Update、Model Aliases、User Identity、Reply Tags、Messaging、Silent Replies 和 Heartbeats。
  但 Tooling、Safety、Workspace、Sandbox、Current Date & Time（已知时）、Runtime，以及注入的 context 仍然可用。
• none：只返回基础身份行。

当 promptMode=minimal 时，额外注入的 prompt 会被标记为 Subagent Context，而不是 Group Chat Context。

4.2.4.3 Workspace启动文件注入

Bootstrap 文件会被裁剪后追加到 Project Context 下方，这样模型无需显式读取文件，也能看到身份和用户资料相关上下文：

• AGENTS.md
• SOUL.md
• TOOLS.md
• IDENTITY.md
• USER.md
• HEARTBEAT.md
• BOOTSTRAP.md（只在全新 workspace 中出现）
• MEMORY.md（如果存在）

除非某个文件有特定的 gate 限制，否则这些文件会在每一轮对话中被 注入到 context window 中。
当默认 agent 未启用 heartbeats，或者：agents.defaults.heartbeat.includeSystemPromptSection为 false 时，HEARTBEAT.md 会在普通运行中被省略。

Sub-agent session 只会注入：

• AGENTS.md
• TOOLS.md
  其他 bootstrap 文件会被过滤掉，以保持 sub-agent context 较小。

4.2.5 Context

“Context” 指的是：OpenClaw 为某一次运行发送给模型的全部内容。
它受到模型 context window 的限制，也就是 token 上限。

初学者可以这样理解：

• System prompt（由 OpenClaw 构建）：规则、工具、skills 列表、时间 / runtime 信息，以及被注入的 workspace 文件。
• Conversation history：当前 session 中你的消息和 assistant 的消息。
• Tool calls/results + attachments：命令输出、文件读取结果、图片 / 音频等。

4.2.5.1 Context window的内容

模型收到的所有内容都会计入 context window，包括：

• System prompt，也就是所有 section。
• Conversation history，即对话历史。
• Tool calls + tool results，即工具调用和工具结果。
• Attachments / transcripts，例如图片、音频、文件。
• Compaction summaries 和 pruning artifacts，即压缩摘要和裁剪产物。
• Provider 的 “wrappers” 或隐藏 headers，即使用户看不到，也仍然会计入。

4.2.5.2 哪些内容会持久化

哪些内容会跨消息保留下来，取决于具体机制：

• Normal history 会保存在 session transcript 中，直到被策略压缩或裁剪。
• Compaction 会把摘要写入 transcript，并保留最近的消息。
• Pruning 会从内存中的 prompt 中丢弃旧的工具结果，以释放 context-window 空间，但不会重写 session transcript。完整历史仍然可以在磁盘上检查。

4.2.6 Context engine

一个 context engine 控制 OpenClaw 如何为每一次运行构建模型上下文，包括：

• 应该包含哪些消息
• 如何总结较早的历史记录
• 如何在 sub-agent 边界之间管理上下文

OpenClaw 自带一个内置的 legacy engine，并且默认使用它。

4.2.6.1 核心流程

阶段	作用
Ingest	新消息加入 session 时，engine 可以存储或索引这条消息
Assemble	每次调用模型前，engine 决定哪些消息进入 context
Compact	context 快满或用户执行 /compact 时，engine 压缩旧历史
After turn	一轮运行结束后，engine 可以保存状态、更新索引、后台压缩

Context engine 还可以处理 sub-agent 相关生命周期。

比如主 agent 派生一个 sub-agent 去做任务时，context engine 可以决定：

子任务要不要继承父会话上下文？
继承哪些内容？
任务结束后要不要清理状态？

4.2.7 workspace

OpenClaw 期望 workspace 中包含的文件：

文件 / 目录	作用
AGENTS.md	agent 的操作规则、行为指令、记忆使用方式
SOUL.md	agent 的人格、语气、边界
USER.md	用户是谁、如何称呼用户
IDENTITY.md	agent 的名称、风格、emoji
TOOLS.md	本地工具使用约定，不决定工具是否存在
HEARTBEAT.md	heartbeat 运行时用的小清单
BOOT.md	Gateway 重启时运行的启动清单
BOOTSTRAP.md	首次运行的一次性初始化流程，完成后删除
memory/YYYY-MM-DD.md	每日记忆日志
MEMORY.md	精选长期记忆，可选
skills/	当前 workspace 专属 skills，优先级最高
canvas/	Canvas UI 文件

4.2.8 Memory

OpenClaw 通过在 agent 的 workspace 中写入 普通 Markdown 文件 来记住事情。

4.2.8.1 工作原理

你的 agent 有三个与 memory 相关的文件：

• MEMORY.md —— 长期记忆。用于保存持久事实、偏好和决策。会在每个 DM session 开始时加载。
• memory/YYYY-MM-DD.md —— 每日笔记。用于保存运行中的上下文和观察记录。今天和昨天的笔记会自动加载。
• DREAMS.md（可选）—— Dream Diary 和 dreaming sweep 摘要，用于人工审查，包括有依据的历史回填条目。

4.2.8.2 做梦机制

做梦 (Dreaming) 是一项针对记忆的可选后台整合过程。它会收集短期信号，对候选条目进行打分，并仅将合格的条目晋升 (promote) 到长期记忆 (MEMORY.md) 中。

Dreaming 过程中产生的阶段摘要、候选项分析、日记式记录，会写入 DREAMS.md。这些内容主要是给人看的，用来让你检查系统为什么认为某些信息值得保留。

只有通过筛选、评分、召回频率、查询多样性等条件的内容，才会被提升写入 MEMORY.md。MEMORY.md 才是 agent 的长期记忆文件。

它的设计旨在保持长期记忆的高信噪比：

• 选择性加入 (Opt-in)：默认关闭。
• 计划执行 (Scheduled)：启用后，memory-core 会自动管理一个重复的 cron 任务，以进行全面的梦境扫描。
• 阈值门槛 (Thresholded)：晋升操作必须通过得分、召回频率和查询多样性等关卡。
• 可审查 (Reviewable)：阶段摘要和日记条目会被写入 DREAMS.md，供人类审查。

4.2.8.1 Memeory工具

Agent 有两个用于处理 memory 的工具：

• memory_search：使用语义搜索查找相关笔记，即使用词和原文不同，也能找到。
• memory_get：读取特定 memory 文件或指定行范围。
  这两个工具由当前启用的 memory plugin 提供，默认是 memory-core。

4.2.9 Compaction

每个模型都有 context window，也就是一次能处理的最大 token 数。
当 session 里的历史消息、工具结果、system prompt 等内容越来越多时，就可能接近上限。
这时 OpenClaw 会做 compaction。

压缩前，模型可能看到：

很长的完整历史  
+ 最近消息  
+ 工具结果

压缩后，模型看到：

旧历史摘要  
+ 最近消息原文  
+ 当前用户输入

这样既减少 token，又保留关键上下文。

4.2.10 Heartbeat机制

Heartbeat runs periodic agent turns in the main session so the model can surface anything that needs attention without spamming you.

• 心跳机制会在主会话中执行周期性的智能体运行轮次，以便模型能够及时报告需要关注的事项，从而避免产生信息过载 。

1）快速入门
1.设定运行频率：
保持心跳机制开启（默认频率为 30m，若检测到 Anthropic OAuth/令牌认证模式，包括 Claude CLI 复用场景，则默认值为 1h），或自定义配置您的执行频率。
2.引入 HEARTBEAT.md (可选)：
在智能体工作区 (Workspace) 中构建一个精简的 HEARTBEAT.md 检查清单或 tasks: 任务块。
3.配置心跳消息的路由目标：
系统默认为 target: "none"；将其设置为 target: "last" 即可将消息路由至最后一次交互的联系渠道。
4.高级参数微调：

• 启用心跳机制的推理过程输出，以增强系统透明度。
• 若心跳运行仅依赖 HEARTBEAT.md，可启用轻量级引导上下文
• 启用隔离会话)，以避免在每次心跳轮询时传输完整的对话历史记录。
• 约束心跳机制仅在设定的活跃时间窗口（本地时区）内运行
  • 利用该机制，可将心跳探测严格限制在特定时区下的业务操作时段内

2）提示词主体
即系统在触发心跳时，实际发送给大语言模型的那段具体的指令文本，通过 agents.defaults.heartbeat.prompt 配置。
Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK. (如存在 HEARTBEAT.md 请阅读并严格执行。请勿推断或重复先前对话中的旧任务。若无事需要关注，请回复 HEARTBEAT_OK。)

3）完整流水线
1.时序触发与准入校验
心跳并非由用户输入触发，而是由系统内部的定时器驱动。

• 节拍生成： 系统依据配置的周期参数（如默认的 30m，即30分钟）持续产生时钟节拍。
• 负载与时钟校验： 当节拍产生时，网关层不会立刻调用大模型。它首先会校验当前时间是否落入允许的活跃时间窗口内。同时，它会检查系统的当前负载（例如是否存在优先级更高的Cron定时任务，或子智能体是否处于繁忙状态）。若条件不满足，该次心跳请求将被平滑丢弃或推迟，以此保障本地计算资源不被挤兑。
  2.上下文动态组装
  当心跳请求获批进入执行层后，系统开始为大模型准备运行环境。
• 注入标准指令： 系统会在后台默默向大模型发送一条隐式的提示词，要求其去阅读工作区内的 HEARTBEAT.md 文件 。
• 加载巡检规程： HEARTBEAT.md 充当了心跳周期的检查清单。如果该文件中配置了嵌套的 tasks: 区块（如分别设定30分钟查一次邮件，2小时查一次日历），解析器会计算各子任务的冷却时间，仅将到期的任务连同历史对话上下文一起打包，发送给底层的推理模型 。
• 当HEARTBEAT.md文件缺失时，大语言模型将无法获取具体的子任务要求（如“去查邮件”或“去查日历”），它将转而依赖其全局系统提示词、过往的历史记忆以及当前的上下文环境。
  3.模型推演与状态判定
  底层的大语言模型接收到包含巡检清单的上下文后，开始进行逻辑推演。此时，系统要求模型遵循严格的“响应契约”：
• 稳态（无事发生）： 如果模型检查后判定一切正常，没有需要用户立刻介入的待办事项，它被强制要求仅输出一条标准化的字符串：HEARTBEAT_OK。
• 异常态（需要预警）： 如果模型发现有紧急邮件或被阻塞的任务，它则会输出具体的警示性分析文本。
  4.网关拦截与信道路由
  这是心跳机制区别于普通对话的最关键步骤。网关层负责对大模型的输出流实施“过滤与分发”：
• 静默丢弃： 当网关扫描到大模型仅仅回复了 HEARTBEAT_OK（且开启了隐藏OK的配置），网关会在内部更新任务的时间戳和会话状态，但会在网络层彻底拦截这条消息。用户端不会收到任何打扰信息，这保证了系统可以高频自检而不会产生信息过载。
• 精准投递： 只有当模型输出了实际的预警文本时，网关才会依据配置文件中的 target 参数（例如 last 指向最后交互的终端，或指定路由至特定的WhatsApp账户），将这条报警载荷精准投递给用户。

4.2.11 Cron Job机制

Cron 是网关（Gateway）架构中内置的精确定时调度器。该组件负责对作业进行持久化存储，在预设的时间节点准确唤醒智能体，并将输出结果路由投递至通讯信道或 Webhook 端点。其底层机制支持一次性任务提醒、基于表达式的周期性循环调度，以及入站 Webhook 触发模式。

4.2.12 sub agent机制

子智能体（Sub-agents）是由当前活动的智能体运行（agent run）所衍生出的后台运行实例。它们在各自独立的专属会话 (agent:<agentId>:subagent:<uuid>) 中执行。当任务完成时，它们会将结果以通告 (announce) 的形式反馈至最初发起请求的聊天通道。每一次子智能体的运行都会被系统记录并追踪为一个后台任务 (background task) 。

子智能体是一种非常有效的工作流隔离单元，但请注意，在同一个共享的网关 (Gateway) 内部，它们并不构成抵御恶意多租户 (multi-tenant) 的安全授权边界 。

核心设计目标：

• 并行化处理： 将“资料调研 / 长耗时任务 / 慢速工具调用”等工作转移至后台并行处理，避免阻塞主运行通道 。
• 默认隔离原则： 保持子智能体处于默认隔离状态（基于会话隔离机制，并辅以可选的沙箱环境） 。
• 工具权限收敛： 降低工具的滥用风险：系统不会默认将高级的“会话管理工具”下放给子智能体 。
• 编排器模式支持： 允许配置嵌套深度，以支持复杂的任务编排器 (orchestrator) 模式 。

上下文注入模式

模式 (Mode)	适用架构场景 (When to use it)	机制行为 (Behavior)
isolated	新兴资料收集、独立代码实现、慢速工具调用等，凡是能用一段任务描述（Task Text）交代清楚的业务逻辑	系统将缔造一份干干净净的子转录副本 。此为出厂默认态，可大幅压减 Token 算力开销 。
fork	强依赖于当前对话时序状态、高度依赖前置工具调用结果，或是请求方转录数据中早已潜藏着极其微妙且难以复述的隐形指令的复杂场景	抢在子节点点火启动之前，系统会将请求方的庞大转录数据如树枝分叉般强行压入子会话的上下文沙箱中 。

无限套娃：嵌套子智能体
系统在出厂设定中，用物理锁锁死了子智能体继续自我繁衍（spawn）的能力，即将其卡死在 (maxSpawnDepth: 1) 的层级 。

4.2.13 Pi Agent Core

OpenClaw 摒弃了将 pi 作为子进程 (subprocess) 派生或采用 RPC（远程过程调用）通信的松耦合模式，而是通过调用 createAgentSession()，直接在同一进程内存空间内导入并实例化 pi 的 AgentSession。这种深度的嵌入式架构赋予了系统以下核心优势：

• 对会话生命周期与事件流处理（event handling）的绝对控制权
• 支持深度定制化的工具注入（涵盖消息推送、沙箱逃逸防护、特定通道操作等）
• 能够基于不同的通道/上下文动态重构系统提示词（System prompt）
• 原生支持具备分支 (branching) 与压缩 (compaction) 功能的会话持久化机制
• 实现了支持故障转移 (failover) 策略的多账户授权凭证轮换 (Auth profile rotation)
• 构建了与具体模型提供商解耦 (Provider-agnostic) 的模型热切换机制

4.2.14 Channels

通道可以同时运行；配置多个时，OpenClaw 会按聊天路由消息

1.配对
在 OpenClaw 中，“配对”是明确的访问授权步骤，用于两个场景：

1. DM 配对（谁可以与 Bot 对话）
2. 节点配对（哪些设备/节点允许加入 Gateway 网络）

4.2.15 Node.js

• OpenClaw 的 主进程（Gateway、CLI 等）是用 Node.js 编写和运行的。
• 当你安装和运行 OpenClaw 时，实际上是在启动一个 Node.js 程序。

在 OpenClaw 中，Gateway 是整个系统的核心引擎：

• 监听来自各个消息通道（WhatsApp、Telegram、Slack 等）的消息
• 路由消息到对应的智能体（Agent）和会话
• 维护会话状态、插件、技能、工具调用
• 将响应发回到用户渠道
  这个 Gateway 进程就是一个 Node.js 服务器进程，通过 WebSocket 与节点（nodes）、UI 客户端、通道插件等进行通信。

4.2.16 会话

4.2.16.1 消息路由

来源	行为
Direct messages（私聊）	默认共享一个 session
Group chats（群组）	每个群组独立 session
Rooms/channels（通道/房间）	每个房间独立 session
Cron jobs（定时任务）	每次运行新建 session
Webhooks	每个 webhook 独立 session

• 默认情况下，所有私聊共用一个 session，适合单用户
• 如果多用户可访问智能体，需要启用 DM 隔离，否则不同用户的私聊会互相可见

4.2.16.2 会话生命周期

• 会话会被复用，直到过期：
  1. 每日重置（默认）：每天 4:00 AM 本地时间开启新 session
  2. 空闲重置（可选）：一段时间无用户操作后创建新 session
     • 配置：session.reset.idleMinutes
     • 仅用户/通道交互触发，cron/heartbeat 不算
  3. 手动重置：聊天中输入 /new 或 /reset
     • /new <model> 可以切换模型
• 如果同时配置每日和空闲重置，以先到者为准
• 系统事件写入 metadata 不会延长重置时间
• 活跃的 provider CLI session 不会被默认每日重置中断，需要手动 /reset 或显式配置

4.2.16.3 会话状态存储位置

• 会话状态由 Gateway 管理，UI 客户端查询 Gateway 获取 session 数据
• 文件路径：
  • 会话列表：~/.openclaw/agents/<agentId>/sessions/sessions.json
  • 会话记录（transcripts）：~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
• sessions.json 字段：
  • sessionStartedAt：当前 sessionId 开始时间，用于每日重置
  • lastInteractionAt：最后一次用户/通道交互，用于空闲重置
  • updatedAt：最近一次数据更新，用于列表和裁剪，不影响重置时间
• 旧的 session 行没有 timestamp 时，会从 transcript JSONL 里推算

4.2.16.4

• Session pruning 是在每次 LLM 调用前，把会话中旧的工具输出结果从上下文里裁剪掉

• 目的是：减少上下文膨胀（工具输出、执行结果、文件读取、搜索结果累积）

• 注意：

  • 仅在内存中裁剪
  • 不会修改磁盘上的会话记录（session transcript）
  • 你的完整历史总是保留的

• Context window 里确实包含了 tool results（工具输出），这部分是模型在生成回答时能“看到”的内容。

• Session pruning 做的就是 在 context 里临时裁剪掉一些旧的工具输出，让模型看到的 context 更小、更轻量。

• 裁剪后：

  • tool results 内容不全了，旧的部分被替换为占位符或软裁剪标记
  • 对话历史（Conversation history）依然完整
  • 磁盘上的 session transcript 也没有被改动，历史记录完整保留

4.2.17 多智能体

在一个运行的 Gateway 中，可以运行多个隔离的智能体（isolated agents）——每个智能体拥有自己的工作区（workspace）、状态目录 (agentDir) 和会话历史，同时支持多个渠道账号（例如两个 WhatsApp 账号）。收到的消息通过 bindings 路由到对应智能体。

这里的 agent（智能体） 是完整的人格范围（per-persona scope）：包括工作区文件、认证信息、模型注册表和会话存储。agentDir 是存放每个智能体配置的本地磁盘目录，路径为 ~/.openclaw/agents/<agentId>/。binding 将一个渠道账号（如 Slack 工作区或 WhatsApp 号码）映射到某个智能体。

一个 智能体 (agent) 是一个作用域完整的“大脑”，拥有它自己的：

• 工作区 (Workspace) (文件、AGENTS.md/SOUL.md/USER.md、本地笔记、角色规则)。
• 状态目录 (State directory) (agentDir)，用于存放认证配置文件、模型注册表和针对该智能体的配置。
• 会话存储 (Session store) (聊天记录 + 路由状态)，位于 ~/.openclaw/agents/<agentId>/sessions 下。

技能 (Skills) 从每个智能体的工作区以及共享的根目录（如 ~/.openclaw/skills）加载，然后通过生效的智能体技能许可列表（如果已配置）进行过滤。

WhatsApp personal → home agent
WhatsApp biz → work agent
Telegram → coding agent
某个 WhatsApp 群 → family agent
官方说 binding 会把 channel account，比如 Slack workspace 或 WhatsApp number，映射到某个 agent。

4.3 示例

1. 你在 WhatsApp 给 OpenClaw 接入的账号发消息：
   “制作并在 YouTube 上上传一个 Agent 介绍视频，上传完成后通知我。”

2. WhatsApp channel 收到消息，通过 adapter 交给 Gateway。

3. Gateway 检查：
   - 发送者是否在 allowlist / pairing 允许范围内
   - 这个 WhatsApp account 对应哪个 agent
   - 这条消息属于哪个 session

4. Gateway 启动 agent run。

5. Agent runtime 组装 context：
   - system prompt
   - session 历史
   - workspace 文件
   - skills
   - 可用工具
   - 当前时间
   - 用户这次消息

6. 大模型理解任务，制定计划：
   - 生成脚本
   - 生成分镜
   - 生成素材
   - 合成视频
   - 上传 YouTube
   - 通知用户

7. Agent 检查本地能力：
   - 是否有 ffmpeg
   - 是否有配音工具/API
   - 是否有 YouTube 上传脚本/API
   - 是否有 YouTube OAuth token
   - 是否需要用户确认公开视频

8. Agent 生成视频内容：
   - 文案
   - 标题
   - 描述
   - 字幕
   - 音频
   - 视频文件

9. Agent 验证视频文件：
   - 文件是否存在
   - 时长是否正确
   - 格式是否为 mp4
   - 大小是否合理

10. Agent 调用 YouTube 上传能力：
    - 使用 YouTube Data API，或
    - 使用浏览器自动化，或
    - 使用第三方发布工具

11. 上传成功后，Agent 获取视频链接。

12. Agent 通过 Gateway 的 WhatsApp channel 发消息给你：
    “视频已上传完成，这是链接：...”

五.Openclaw软件架构

OpenClaw的总体架构可以划分为五个层次：接入层、网关层、智能体运行时层、持久层和工具执行层。这五个层次共同构成了OpenClaw从外部输入接入、请求编排、智能体运行、状态保存到工具执行的完整运行链路。

其中，接入层主要负责连接用户、外部设备以及不同类型的交互入口，包括消息通道、控制客户端和节点等组件；网关层位于接入层之后，主要承担协议接入、消息编排和运行时协调等功能，是外部请求进入智能体运行系统之前的调度中枢；智能体运行时层是系统执行智能体任务的核心区域，主要由OpenClaw Runtime Layer和Pi Agent Core构成，并与底层大语言模型进行交互；持久层负责保存智能体运行过程中所需的状态与资源，包括智能体存储和共享资源存储；工具执行层则通过工具和执行环境承接智能体的外部操作请求，使模型生成的行动意图能够转化为对真实或虚拟环境的具体操作。