一、认识 OpenClaw

大语言模型在被应用的过程中，需要与实际任务发生互动才能解决实际问题，因此，需要一套集成服务调度、工具管理、设备交互等功能的系统框架——OpenClaw即此类框架。

OpenClaw的核心机制

graph TD
    %% 1. 定义节点 (使用 <br> 进行换行)
    User[用户消息<br/>Telegram / WhatsApp / WebChat]
    Gateway[Gateway 网关<br/>鉴权 · 路由 · 会话接入]
    Agent[Agent 智能体<br/>推理 · 决策 · 调度]
    Tool[Tool 工具<br/>文件 · 浏览器 · Shell · HTTP]
    Session[Session 会话<br/>历史记忆 · 上下文]
    Node[Node 节点<br/>配对设备 · 远端执行 · 外设能力]

    %% 2. 定义连接关系
    User <--> Gateway
    Gateway --> Agent
    Agent <--> Tool
    Agent <--> Session
    Agent <--> Node

    %% 3. 定义样式 (简单的紫色边框和浅色背景)
    classDef mainStyle fill:#f9f9ff,stroke:#9370db,stroke-width:2px,color:#333;
    
    %% 4. 应用样式
    class User,Gateway,Agent,Tool,Session,Node mainStyle

概念	含义
gateway	负责统一各渠道消息格式、身份验证、维护连接状态。
Agent	执行任务的单元，可以有多个，不同Agent有工具、权限、记忆。
Tool	可以提高Agent效率的已有工具
Session	用户级别隔离的长短期记忆
Node	通过WebSocket接入Gateway的输出设备或执行终端都可以叫Node。

一条消息的完整流程

消息到达gateway，进行鉴权
鉴权通过后，路由到合适的agent，并挂载对应的session上下文。
Agent利用session上下文进行tools调用
tool返回结果，Agent整合结果，通过node返回给用户。

[!CAUTION]

值得注意的是，Agent可以通过配置调用其他agent，所以一次对话不止一次调用agent。

二、安装、配置、卸载 Openclaw

物料清单

LLM API Key
Channel 聊天软件凭证

2.1 常用命令

安装脚本

# Works everywhere. Installs everything. You're welcome. 🦞
# macOS/Linux
 curl -fsSL https://openclaw.ai/install.sh | bash
 # Windows
  iwr -useb https://openclaw.ai/install.ps1 | iex

配置引导

# 配置引导， --install-daemon 参数会在配置完成后启动服务并生成一个后台守护进程，保障机器即使重启后，守护进行也会在后台持续运行。
openclaw onboard --install-daemon

启动命令

#前台运行
openclaw gateway run
#后台运行
openclaw gateway start
#后台重启
openclaw gateway restart
#停止服务
openclaw gateway stop

卸载命令

# step 1: 卸载服务
openclaw uninstall --all --yes --non-interactive
# step 2: 清理残留文件
rm -rf ~/.openclaw && rm -rf ~/.clawdbot ~/.moltbot ~/.molthub
# step 3: 卸载命令行工具
npm uninstall -g openclaw

2.2 工作区

文件名/目录名	描述
`AGENTS.md`	工作区启动清单行为准则
`SOUL.md`	定义智能体人格及沟通风格
`USER.md`	用户个人画像
`IDENTITY.md`	智能体元数据，如昵称、头像等
`HEARTBEAT.md`	Heartbeat巡检清单
`BOOT.md`	启动内部Hook且Gateway重启时的启动清单
`memory/YYYY-MM-DD.md`	分日期记忆日志
`MEMORY.md`	长期记忆索引
`skills/`	技能目录
`canvas/`	节点UI或可视化文件

三、 OpenClaw 工作原理

在Openclaw 工作的过程中，模型负责提出意图，而出色完成指定任务，则是依靠工具、技能及优秀的记忆管理。

3.1 工具

工具需要具有明确输入、明确输出、明确异常处理。

结果的回注原则

为避免上下文爆炸，一般来说，模型的原始输出不会直接引入上下文，而是划分为三部分，作为具有不同生命周期的状态引入到系统中。

结论摘要：本次工具得到的关键信息总结，生命周期持续最久。
证据引用：关键信息最相关的原始来源，生命周期适中。
原始输出：全部原始输出，生命周期最短。

一个标准的回注示例：

{
  "summary":"",
  "evidence": {
    "account_id":"joy",
    "status":"active",
    "last_login":"YYYY-MM-DDTHH:mm:SSZ"
  },
  "raw_output":"{\"xxx...\"}"
}

一次工具调用的完整生命周期

graph TD
    %% 定义节点
    A[模型推理]
    C[提议: tool_name + params]
    D{策略校验}
    E[执行工具]
    F[拒绝 + 原因回注]
    G{执行结果}
    H[结构化回注]
    I[有界重试]
    J[失败回注 + 告警]
    K[模型继续推理]
    
    %% 流程连接
    A -- 输出工具调用意图 --> C
    C --> D
    
    %% 策略校验分支
    D -- allow 命中 --> E
    D -- deny 命中 --> F
    
    %% 执行工具分支
    E --> G
    
    %% 执行结果分支
    G -- 成功 --> H
    G -- 可重试错误 --> I
    G -- 致命错误 --> J
    
    %% 回流路径
    I --> E
    H --> K
    J --> K
    F --> K

工具调用的核心工程要点。

输入摘要：从上下文中提取输入的参数字段
策略校验：判断执行权限
执行结果：成功、失败、异常处理的原始输出。
回注：将工具的输出整合成状态后进行状态传递。

链式任务（多个工具串行执行）的完整周期

graph TD
    %% 定义节点
    Start[开始：链式任务]
    ExecA[工具 A 执行]
    RetryA[有界重试 A]
    FailA[中止链：回注 A 的失败原因]

    ExecB[工具 B 执行]
    RetryB[有界重试 B]
    Success[链完成：合并结果回注]
    Partial[部分完成：回注 A 结果 + B 失败原因]

    Decision[模型决策：降级/上报/跳过]

    %% 流程连接
    Start --> ExecA

    %% 工具 A 的逻辑分支
    ExecA -- 可重试错误 --> RetryA
    RetryA --> ExecA
    ExecA -- 致命错误 --> FailA
    ExecA -- 成功 --> ExecB

    %% 工具 B 的逻辑分支
    ExecB -- 可重试错误 --> RetryB
    RetryB --> ExecB
    ExecB -- 成功 --> Success
    ExecB -- 致命错误 --> Partial

    %% 最终汇聚
    FailA --> Decision
    Partial --> Decision

链式编排的工程要点。

状态收集：每一步的回注记录下来，避免失败时丢失已完成工作。
状态传递：明确不同节点的回注的生命周期，哪些状态可以传递到哪个节点。
失败隔离：模型可以基于已成功节点的上下文做出降级决策（重试、继续回答）。

3.2 技能

有了工具，相当于一个厨师获得了锅碗瓢盆，刀叉杯筷，但是这不意味着可以做出好吃的菜，因为还需要按照菜谱去一步步执行。而技能，就相当于Agent的菜谱。

技能本质上是一个说明文件（md）+ 资源包，它固化了任务的执行意图、指令步骤、验收标准，指导模型该技能的效果、使用方式。

对比Prompt，技能的核心优势是：让模型按需主动调用，不受上下文影响。

3.3 上下文管理

对于LLM而言，输入的上下文直接决定了它的输出质量。合理的管理上下文，是衡量一个Agent能否称为私人助手的关键。

上下文的构成

一次模型的上下文按注入顺序可划分为以下四部分：

层级	来源	长度（token）	生命周期
系统知识	`SOUL.md`、`USER.md`、技能指令	几k	整个会话不变
工作区知识	`MEMORY.md`、每日日志、检索记忆	几k，小于系统知识	按检索结果和对话动态更新
对话历史	用户与助手本次session的对话历史	随会话增长	受裁减和压缩
工具回注	工具调用原始返回	单次最高可达几十k	每次工具调用结束后及被裁减

[!NOTE]

根据经验，系统身份的上下文长度占 10%-15%，工作区 5%，其余的由对话历史和工具回注构成。

记忆存储

OpenClaw的长期记忆以工作区文件为中心，配套向量索引实现高效的记忆管理。

OpenCalw基于“文件即真相(files are the source of truth)”的思想,将记忆以文件的形式存储在工作区，主要包括长期记忆的memory.md 和一定周期内的每日日志memory/YYYY-MM-DD.md。系统会在遇到高价值用户偏好、重要决策或者稳定状态配置时，自动更新记忆文件。

[!IMPORTANT]

记忆的需要具有以下标准：

稳定：可跨对话服用，过期时间可控

可追溯：内容来自工具的回注或用户的输入，而非大模型的推测。

可纠错：允许随时更改错误记忆，避免错误信息持久化。

这种分两部分存储的形式，将可复用事实和过程噪声隔离，能有效提高上下文检索效率。

记忆检索

官方提供了两种检索方案。

memory_search采用向量检索为主、BM25为辅的混合检索架构，向量检索负责解决语义问题（比如搜“无人驾驶”能联想到“自动驾驶”），BM25解决精确匹配问题。

[!CAUTION]

Openclaw中，使用 const tokens = raw.match(/[\p{L}\p{N}_]+/gu);的正则完成分词，因而不支持中文。但对实际效果的影响很小，因为主要检索还是依赖向量。

使用记忆的向量检索需要配置Embedding API key，否则不具有语义检索功能。

memory_get基于已有依据直接读取内容，精确命中某块记忆。

索引的延迟在上下文记忆写到磁盘约2s生效。

记忆索引

检索的前提是索引。索引是在OpenClaw在文件落盘后自动运行的，无需手动触发。Openclaw将约400个token分块成一个doc，两个相邻doc各保持80个token的重叠区域。embedding默认基于1536维 text-embedding-3-small 模型生成，不配置Embedding API key则不生效。最终，会在本地的SQLite数据库存入以下内容：chunks(原始文本与位置)、embedings（向量）、fts（BM25倒排索引）、vector_cache（哈希表，用来避免重复生成已有内容的embedding）。

记忆失效

长期系统一定会遇到“事实过期”的情况，因此，记忆的元数据需要维护来源、更新时间、过期时间。

同一来源的新记忆覆盖旧记忆，过期条目准时清除。

记忆压缩与裁剪

压缩和裁剪并不是同样的概念，OpenClaw提供了两套方案，分别面向不同场景。

上下文裁剪：主要面向工具结果，大语言模型调用前，系统会在内存中临时舍弃一些老旧的工具执行结果，从而减轻单词请求的负荷，该过程不涉及磁盘历史文件的更改。
[!WARNING]

有三个关键内容不会被裁减：
- 包含图片内容的工具结果
- 第一条用户消息之前的系统上下文
- 被配置强行指定不裁减的工具内容
会话压缩：主要面向对话，在会话上下文接口容积上限后，系统会把更早的对话进行总结，并持久化写到磁盘中，旧记忆进索引，新记忆继续滚动。对于过长的对话，系统会分割成多段进行滚动。

记忆遵循先裁剪工具，再压缩对话的方式，流程如下：

graph TD
    %% 定义节点
    A[组装上下文] --> B[检查输入体积]

    %% 左侧分支：工具结果过大
    B -- 工具结果过大<br/>(cache-ttl 模式, Anthropic API) --> C[contextPruning 裁剪]
    C --> D[发送给模型]

    %% 右侧分支：会话接近阈值
    B -- 会话接近阈值 --> E[compaction 压缩摘要]
    E --> F[必要时 memoryFlush]

    %% 循环回路
    F --> A

    %% 样式美化 (可选，为了更像原图)
    style A fill:#f0f0ff,stroke:#9370db
    style B fill:#f0f0ff,stroke:#9370db
    style C fill:#f0f0ff,stroke:#9370db
    style D fill:#f0f0ff,stroke:#9370db
    style E fill:#f0f0ff,stroke:#9370db
    style F fill:#f0f0ff,stroke:#9370db

四、附录

成本控制

只挂在需要的工具
合理使用会话重置，避免短期记忆混合。
简单任务使用轻量模型、复杂任务使用大型模型。
尽量简化大模型的单任务复杂度和不确定性。