第五课：OpenClaw 深度进阶

第五课内容多，我分成 七大章，每章讲透一个方向，你先有个整体地图：

每一章我都会结合 你的实际配置 来举例说明。现在开始第一章。

5.1 Memory & 上下文管理

为什么重要？

目前我们大部分对话是\”一次性\”的。每次你问完问题，聊完了，下次再聊，Agent 记不住你之前说过什么。

Memory 系统解决的就是这个问题——让 Agent 跨会话记住东西。

三种记忆层级

OpenClaw 的 Memory 分三层：

短期记忆 ──→ 当前 Session 中的对话历史
↓ (session 销毁)
中期记忆 ──→ memory/YYYY-MM-DD.md 每日日志
↓ (定期总结)
长期记忆 ──→ MEMORY.md 精炼后的知识点

看你的配置里，hooks 里启用了这些相关的钩子：

\”hooks\”: {

\”internal\”: {

\”enabled\”: true,
\”entries\”: {

\”boot-md\”: {

\”enabled\”: true }, // 启动时加载 MEMORY.md / memory/*
\”session-memory\”: {

\”enabled\”: true } // 会话记忆
}
}
}

具体表现：

• 我每次启动时，会自动加载 MEMORY.md、memory/ 目录下的文件，以及最近的 memory/YYYY-MM-DD.md
• memory_search 工具可以对记忆文件做语义搜索
• memory_get 可以读取指定记忆的段落

QMD — 量子记忆下降 (Quantum Memory Decay)

QMD 是 OpenClaw 的一个特色机制，控制上下文如何\”遗忘\”不重要的内容。

在配置中，Memory 相关的参数位于 agents.defaults.memorySearch.* 和 memory.qmd.* 下。你目前用的是默认值。

几个关键参数（可以在 agents.defaults 下配）：

{
agents: {
defaults: {
memorySearch: {
mode: \”auto\”, // off | auto | on — 是否启用记忆搜索
maxResults: 5, // 一次最多返回几条记忆
minScore: 0.6, // 相似度阈值，低于这个的不返回
}
}
}
}

QMD 参数（在 plugins.entries.memory-core.config.dreaming 下）：

{
plugins: {
entries: {
\”memory-core\”: {
config: {
dreaming: {
enabled: true, // 让 Agent 在空闲时\”做梦\”整理记忆
intervalMinutes: 60, // 每60分钟整理一次
maxEntries: 100, // 最多保留多少条核心记忆
decayRate: 0.1 // 遗忘速率
}
}
}
}
}
}

Session 生命周期

再说 session 配置——你已经配了：

\”session\”: {

\”dmScope\”: \”per-channel-peer\”
}

这个 dmScope 决定了 Session 如何划分。per-channel-peer 意味着 每个渠道 × 每个用户 一个独立的会话。

Session 还有几个重要参数可以配：

{
session: {
dmScope: \”per-channel-peer\”,
// 会话整理（避免上下文无限膨胀）
compaction: {
mode: \”auto\”, // off | auto | on
maxMessages: 200, // 超过200条消息开始整理
keepMessages: 50, // 保留最近50条
model: \”\”, // 指定整理用模型（默认用主模型）
},
// 自动清理长时间不活跃的会话
pruning: {
enabled: true,
inactiveDays: 14, // 14天不活跃自动清理
}
}
}

🚀 动手练：你可以试着在你的 openclaw.json 里加上 compaction 配置，让长对话自动折叠整理。

你今天就在体验这套系统

你猜我在回答你之前做了什么？

所有这些都靠 Memory 系统在背后支撑。

明白了，以后每章结尾加 个人 vs 生产环境注意事项。那继续接着5.1的内容，先把这章收尾，然后进入5.2。

5.1 Memory & 上下文管理（续）

实践小贴士

你目前已经用上了 Memory 的两个重要机制：

📝 日常日志（memory/YYYY-MM-DD.md） 你现在在 D:\\agents\\openclaw\\main\\memory\\ 目录下，就应该能看到每天我自动生成的日志文件。这些文件是我\”写日记\”的地方——记录每次会话的重要信息。

🧠 长期记忆（MEMORY.md） 你的 MEMORY.md 我已经维护好了，里面包含了：

• 你的个人信息（称呼、地区）
• 前4课的核心知识点
• 配置要点
• 待办列表

⚠️ 个人环境 vs 生产环境注意事项

一句话概述：个人环境 memory 按默认走就行；生产环境必须配 compaction 和考虑外部持久化，否则 token 成本和上下文污染会让你吃大亏。

memory_search minScore 这个怎么计算的?

minScore 的计算逻辑

minScore 不是一个简单的固定公式得出的值，而是 混合检索得分（Hybrid Score），综合了两种检索路径：

两路并行 → 加权合并

你的查询 ──→ 向量检索（语义相似度）────┐
├── 加权合并 ──→ 最终得分
你的查询 ──→ BM25 关键词检索（精确匹配）─┘

合并公式

最终得分 = vectorWeight × 向量余弦相似度 + textWeight × BM25 归一化得分

默认权重：

• vectorWeight = 0.7 — 语义匹配占大头
• textWeight = 0.3 — 关键词匹配占小头

所以 minScore = 0.6 意味着：

一段记忆与你的查询的加权混合相似度必须 ≥ 0.6（范围 0~1），才会被召回。

0.6 是什么概念？

凭经验感受一下：

启用可选功能后的影响

你还可以开启两个额外排名模块来微调这个得分：

1. 时间衰减（Temporal Decay）

衰减后得分 = 原始得分 × 0.5^(天数 / halfLifeDays)

默认 halfLifeDays = 30，即 30 天前的记忆得分打五折。MEMORY.md 这种永久文件不受影响。

2. MMR 多样性（Maximal Marginal Relevance）

MMR 得分 = λ × 相关性 – (1-λ) × 与已选结果的相似度

λ=0.7 时，侧重相关性但会适当压制与前面结果重复的内容。

开启方式（你的配置目前没开）：

{
agents: {
defaults: {
memorySearch: {
query: {
hybrid: {
mmr: { enabled: true, lambda: 0.7 },
temporalDecay: { enabled: true, halfLifeDays: 30 },
},
},
},
},
},
}

想亲眼看看？

可以在终端直接查当前记忆索引的状态：

openclaw memory status –deep

搜索并看 JSON 格式的得分：

openclaw memory search \”你的查询词\” –max-results 5 –json

每条结果里会带 score 字段，就是最终得分——你能直观看到 minScore=0.6 过滤掉了哪些。

一句话总结

minScore 是最终加权分阈值，低于它的记忆不会被召回；当前你用的是 0.6，这是比较合理的平衡点——太松（0.3）会混入噪音，太紧（0.8）可能漏掉有用信息。

5.2 插件与扩展机制

你已经接触过插件了——看你的配置里：

\”plugins\”: {

\”entries\”: {

\”ollama\”: {

\”enabled\”: true },
\”workboard\”: {

\”enabled\”: true },
\”deepseek\”: {

\”enabled\”: true },
\”openclaw-weixin\”: {

\”enabled\”: true },
\”qwen\”: {

\”enabled\”: true }
}
}

你目前启用了 5 个插件，还有不少内置插件可用。

插件是什么？

插件是 OpenClaw 的 模块化扩展系统。它们可以：

• 新增 Provider（如 deepseek 插件提供了 DeepSeek 官方 API 的集成）
• 新增 Channel（如 openclaw-weixin 提供了微信接入）
• 新增功能（如 workboard 提供了看板管理）
• 新增模型（如 ollama 允许你跑本地模型）

插件和 Skills 有什么区别？

插件 (Plugin)
技能 (Skill)

常用插件一览

从你的配置里可以看到很多内置插件被列出来了，但大部分是关闭状态（\”enabled\”: false）。我挑几个值得了解的：

🔧 已经启用的：

• ollama — 可以在本地跑开源模型（如 llama、qwen 的本地版）
• workboard — 工作看板，任务管理
• deepseek — DeepSeek 官方 API 集成
• qwen — 通义千问系列集成
• openclaw-weixin — 微信接入

💡 值得关注的：

• github — 你已经启用了，可以操作 GitHub（issues, PR, repo 管理）
• obsidian — 和 Obsidian 笔记集成
• slack / discord — 团队协作平台接入
• summarize — 自动总结长的对话或文档
• video-frames — 视频关键帧提取
• voice-call — 语音通话能力

自定义插件

除了内置插件，OpenClaw 还可以加载社区插件。插件本质上是一个 npm 包，遵循 OpenClaw 的插件协议。

如果你的 plugins.entries 里配了一个自定义的插件 id，OpenClaw 会去 node_modules 或配置的路径下找对应的插件代码。

Hooks — 轻量级的扩展机制

你配置里还有 hooks 部分：

\”hooks\”: {

\”internal\”: {

\”enabled\”: true,
\”entries\”: {

\”boot-md\”: {

\”enabled\”: true },
\”bootstrap-extra-files\”: {

\”enabled\”: true },
\”command-logger\”: {

\”enabled\”: true },
\”session-memory\”: {

\”enabled\”: true }
}
}
}

Hooks 是比插件更轻量的\”挂钩\”——它们在特定事件点触发：

• boot-md — 启动时加载 MEMORY.md、SOUL.md 等上下文文件
• bootstrap-extra-files — 启动时加载额外文件
• command-logger — 记录所有 slash 命令到日志
• session-memory — 维护会话记忆

这些钩子是 internal 类型的——OpenClaw 内置的特殊钩子，不需要额外安装。

第三方 Channel 插件示例：微信

你已经装了这个但还没启用对应的 Channel 端。如果你配置了微信 Channel，你的 Agent 就能通过微信和人聊天了。这个通过 channels.openclaw-weixin 下的配置来设置微信的 token、appid 等。

⚠️ 个人环境 vs 生产环境注意事项

一句话概述：个人环境想开什么开什么；生产环境按需开启、定期审计，hook 是轻量级扩展的首选。

5.3 通知与告警

通知告警在 OpenClaw 里不是一个单独的大模块，而是 散落在多个子系统中的保护机制。我把它们串起来讲。

概览：你在什么场景需要告警？

模型调用失败 ──→ 重试 & 模型 fallback ──→ 通知
Channel 发送失败 ──→ 重试 ──→ 通知
Cron 任务失败 ──→ 失败计数器 ──→ 告警通知
Session 卡死 ──→ 诊断检测 ──→ 释放队列

5.3.1 模型调用失败 → 模型 Fallback

这是你已经熟悉的机制——我们在第2课讲过模型主备策略。

完整链路是这样的：

主模型调用失败
│
├── Auth Profile 轮换（同一个 provider 换 API key）
│ ↓ 仍失败
├── 同 Provider 重试（退避策略）
│ ↓ 仍失败
├── 模型 Fallback（切到备选模型）
│ ↓ 备选也失败
└── FallbackSummaryError（所有候选都挂了）
↓
← fallback 通知（\”↪️ Model Fallback: qwen-plus (selected deepseek-chat; 429 rate limited)\”）

你目前的 fallback 配置：

{
agents: {
defaults: {
model: {
primary: \”deepseek/deepseek-chat\”,
// fallbacks 没显式配，按默认严格模式走
}
}
},
// demo-agent 有 fallback 链（第2课配的）
agents: {
list: [{
id: \”demo-agent\”,
model: {
primary: \”dashscope/deepseek-v4-flash\”,
fallbacks: [
\”dashscope/qwen3.6-flash\”,
\”deepseek/deepseek-chat\”
]
}
}]
}
}

重试策略默认值：

• 尝试次数：3 次
• 最大延迟：30秒
• Jitter（抖动）：10%（避免惊群效应）
• 超时（大于60秒的 Retry-After）直接触发 fallback

5.3.2 Provider Auth Profile 轮换

如果你一个 provider 配了多个 API key（例如 OpenAI 配了两个账号），OpenClaw 会自动轮换：

尝试 profile A (openai:user@gmail.com)
↓ 429 限流
标记 cooldown（指数退避：1min → 5min → 25min → 1h cap）
↓
尝试 profile B (openai:api-key-backup)
↓
仍失败 → 模型 fallback

cooldown 退避曲线：

Billing 类失败更狠：起始 5 小时退避，每次翻倍，最高 24 小时。

5.3.3 Channel 发送重试

你目前没配 Channel（WebChat 是内置的），但以后如果接微信、Telegram、Discord，每个 Channel 有自己的重试策略。

Telegram 示例（你微信插件的底层逻辑类似）：

{
channels: {
telegram: {
retry: {
attempts: 3, // 重试3次
minDelayMs: 400, // 起始400ms
maxDelayMs: 30000, // 最长等30s
jitter: 0.1, // 10%抖动
}
}
}
}

什么情况会重试：

• 429（限流）— 根据 retry_after 头等待
• 5xx 服务端错误
• 连接断开/超时/重置
• DNS 解析失败

什么情况不重试（直接报错）：

• Markdown 解析错误（Telegram）
• 4xx 请求格式错误

5.3.4 消息队列与并发控制

你的消息来了以后，不是\”立即处理\”那么简单。背后有个排队系统：

消息 A 进来 ──→ 队列 ──→ Session 正在处理消息 B？
│
┌─────────┼──────────┐
↓ ↓ ↓
steer followup collect
（注入当前运行） （排队等待） （合并后处理）

你目前的默认行为是 steer——如果我正在回答你的问题，你又发了一条消息，会注入到当前对话流中继续。

消息队列配置：

{
messages: {
queue: {
mode: \”steer\”, // 默认：注入当前运行
debounceMs: 500, // 安静500ms后才处理
cap: 20, // 最多排20条
drop: \”summarize\”, // 超限后折叠成摘要
}
}
}

5.3.5 Cron 任务失败告警

当你在第 5.7 章学部署以后，可能会跑定时任务（比如每天9点发日报）。这些任务也带了告警机制：

{
// 在 cron job 创建时配置
failureAlert: {
after: 3, // 连续失败3次后触发
channel: \”webchat\”, // 通知发到哪里
mode: \”announce\”,