OpenClaw 进阶实战指南： 中级到高级完整教程

声明：本文为原创技术教程，内容基于 OpenClaw 官方文档及实践经验整理，仅供学习交流使用。


最后更新：2026 年 2 月
版本：2.0
适用范围：OpenClaw v2.23 及以上版本

1. 教程定位：面向哪些读者
2. 学习路径：从零基础到高阶
3. 核心配置：AGENTS.md 工作手册
4. 记忆系统：打造持久化知识库
5. 子 Agent：实现多任务并行处理
6. 定时任务：Cron 自动化实战
7. Skill 开发：扩展 AI 能力边界
8. 多平台部署：全渠道接入方案
9. 性能优化：参数调优指南
10. 实战演练：任务清单
11. 问题排查：常见疑难解答
12. 延伸学习：进阶资源推荐

本教程专为已完成 OpenClaw 基础搭建的用户设计。在开始深入学习之前，请确保你已经具备以下条件：

• ✅ OpenClaw 已成功安装并能正常运行
• ✅ 已完成基础配置文件的创建（包括 SOUL.md、USER.md、IDENTITY.md）
• ✅ 对记忆系统有基本了解（掌握 MEMORY.md 和 memorySearch 的使用）
• ✅ 熟悉 workspace 目录的整体结构
• ✅ 具备基础的命令行操作能力

如果你还未达到上述要求，建议先阅读基础教程：https://x.com/onehopeA9/status/

• OpenClaw 环境已就绪且运行正常
• 至少配置了一个可用的 AI 模型 API（Claude 或 GPT）
• 理解 JSON 和 Markdown 文件格式
• 掌握基本的文件系统操作

完成本教程的学习后，你的 OpenClaw 将获得以下能力提升：

• 编写 AGENTS.md 工作手册
• 设计 session 启动流程
• 制定记忆写入规范
• 设置安全边界和权限

• 开启 memoryFlush 防止信息丢失
• 改进日志格式提高检索准确率
• 配置自动记忆维护机制
• 调整 embedding 模型参数

• 部署子 Agent 实现任务分发
• 创建 Cron 定时任务
• 开发自定义 Skill 扩展功能
• 配置多渠道接入方案

• 微调模型参数
• 优化 token 使用效率
• 配置缓存策略
• 建立性能监控体系

1. 按部就班：不要跳过基础环节，每个配置都有其存在的价值
2. 边学边练：每完成一个配置，立即进行测试验证
3. 问题记录：遇到问题及时记录，便于后续排查和解决
4. 配置备份：重要修改前务必备份配置文件

在基础教程阶段，我们创建了描述 AI 性格特征的 SOUL.md、描述用户信息的 USER.md，以及定义身份标识的 IDENTITY.md。但这些文件主要解决了”AI 是谁”和”用户是谁”的问题，并没有明确告诉 AI”应该如何工作”。

AGENTS.md 的核心作用在于定义 AI 的工作流程和行为准则，相当于一份员工手册。它为 AI 提供了以下指导：

• 每次启动时应该读取哪些文件
• 记忆应该如何组织和管理
• 哪些操作需要用户确认
• 如何处理不同类型的任务

形象类比：

• SOUL.md → 个人性格档案
• USER.md → 服务对象信息
• IDENTITY.md → 身份标识
• AGENTS.md → 工作流程手册

OpenClaw 每次启动新会话时都会处于”初始状态”，需要通过读取文件来恢复记忆和上下文信息。合理的启动流程设计可以让 AI 快速进入工作状态。

配置文件路径：workspace/AGENTS.md

启动流程配置示例：

 Session 启动流程 每次会话开始时，按以下顺序自动执行： 1. 读取 `SOUL.md` - 加载性格特征和行为风格 2. 读取 `USER.md` - 了解用户背景和偏好设置 3. 读取 `memory/YYYY-MM-DD.md` - 加载今天和昨天的日志记录 4. 如果是主会话：额外读取 `MEMORY.md` - 加载核心记忆索引 以上操作无需询问，自动执行。

配置详解：

步骤 1-2：加载基础信息

SOUL.md 和 USER.md 文件通常很小（<1KB），每次读取不会造成明显的性能负担。这两个文件确保 AI 能够明确自己的角色定位。

步骤 3：加载近期日志

读取今天和昨天的日志文件，可以让 AI 快速了解最近发生的事情。之所以包含昨天的日志，是因为如果当前时间是凌晨时段，今天的日志可能还是空的。

步骤 4：条件加载核心记忆

MEMORY.md 可能包含敏感信息（如服务器配置、API 密钥等），因此只在主会话中加载。OpenClaw 支持多种会话类型：

• 主会话：用户直接对话（如 Discord 私聊、WebChat）
• 群聊会话：多人群组对话场景

openclaw

• 子 Agent 会话：子任务执行会话
• Cron 会话：定时任务触发的会话

AI 会自动识别当前会话类型，你只需在 AGENTS.md 中定义相应的规则即可。

OpenClaw 的记忆系统采用分层架构设计，不同类型的信息存储在不同的文件中。在 AGENTS.md 中明确定义记忆管理规范，可以确保信息被正确归档。

记忆层级架构：

分层写入规则：

• 当天发生的事件 → 写入 memory/YYYY-MM-DD.md
• 项目状态变更 → 同步更新 memory/projects.md
• 遇到问题和解决方案 → 记录到 memory/lessons.md
• 核心信息变更 → 更新 MEMORY.md 索引

核心原则：

• 记录结论而非过程细节
• 使用标签便于后续检索
• 保持 MEMORY.md 精简（<40 行）
• 重要信息必须写入文件，不要依赖”记在脑子里”

日志格式示例：

 [项目:WebApp] 服务器部署完成 - 结果：使用 Nginx 反向代理部署成功，监听 443 端口 - 相关文件：`/etc/nginx/sites-available/webapp.conf` - 经验教训：方案 A 和 B 失败原因是端口冲突，必须使用反向代理 - 检索标签：#webapp #nginx #部署

定义清晰的安全边界可以有效防止 AI 执行危险操作或泄露敏感信息。

基本原则：

• 严禁泄露私人数据和敏感信息
• 执行破坏性操作前必须获得确认
• 删除文件使用 trash 而非 rm（可恢复优于永久删除）
• 不确定时，优先询问用户

操作权限分类：

可以自由执行的操作：

• 读取文件、浏览目录结构
• 搜索网络信息
• 查询日历和邮件
• 在 workspace 目录内部工作

需要用户确认的操作：

• 发送邮件、推文、公开消息
• 任何向外部发送数据的操作
• 删除或修改重要文件
• 不确定后果的操作

群聊行为规范：

在群聊环境中：

• 你可以访问用户的文件和记忆，但不能在群聊中分享
• 你是群聊的参与者，而非用户的代言人
• 不要替用户发言或泄露用户的私人信息

# AGENTS.md - 工作空间规范 这是你的工作空间，请按照以下规范工作。 Session 启动流程 每次会话开始时，按以下顺序自动执行： 1. 读取 `SOUL.md` - 加载性格和行为风格 2. 读取 `USER.md` - 了解用户背景和偏好 3. 读取 `memory/YYYY-MM-DD.md` - 加载今天和昨天的日志 4. 如果是主会话：额外读取 `MEMORY.md` - 加载核心记忆索引 以上操作无需询问，自动执行。 记忆管理规范 你每次启动都是全新状态，这些文件是你的记忆延续。 | 层级 | 文件路径 | 存储内容 | |------|---------|---------| | 索引层 | `MEMORY.md` | 核心信息和记忆索引，保持精简 | | 项目层 | `memory/projects.md` | 各项目当前状态和待办 | | 经验层 | `memory/lessons.md` | 问题解决方案，按重要性分级 | | 日志层 | `memory/YYYY-MM-DD.md` | 每日详细记录 | 写入规则 - 日志写入 `memory/YYYY-MM-DD.md`，记录结论而非过程 - 项目变更时同步更新 `memory/projects.md` - 遇到问题时记录到 `memory/lessons.md` - MEMORY.md 仅在索引变化时更新 - 重要信息必须写入文件，不要依赖记忆 日志格式 【项目：名称】 事件标题 - 结果：一句话概括 - 相关文件：文件路径 - 经验教训：要点（如有） - 检索标签：#tag1 #tag2 安全规范 - 不得泄露私人数据 - 破坏性操作前必须确认 - 使用 `trash` 而非 `rm` - 不确定时先询问 可自由执行：读取文件、搜索、整理、在 workspace 内工作 需要确认：发送邮件/消息、任何向外发送数据的操作 群聊规范 你可以访问用户的文件和记忆，但不能在群聊中分享。 在群聊中，你是参与者，不是用户的代言人。 工具使用 Skills 提供你的工具能力。需要使用某个工具时，查看其 SKILL.md 文档。

任务目标：

1. 在 workspace 根目录创建 AGENTS.md 文件
2. 复制上面的模板并根据你的实际需求进行调整
3. 重启 OpenClaw 并验证配置是否生效

验证方法：

• 开启一个新会话
• 观察 AI 是否自动读取了指定的文件
• 让 AI 记录一件事，检查是否写入了正确的文件和格式

✅ 完成标准：

• [ ] AGENTS.md 文件创建成功
• [ ] AI 能够按照规范自动读取记忆文件
• [ ] AI 写入的日志符合指定格式

在完成基础教程后，你的 OpenClaw 已经具备了基本的记忆功能：

• 分层记忆结构（MEMORY.md + memory/*.md）
• 语义检索功能（memorySearch）

但在实际使用过程中，可能会遇到以下问题：

问题 1：长对话后 AI “失忆”

当对话内容超过上下文窗口限制时，OpenClaw 会自动压缩旧对话，这个过程可能导致重要信息丢失。

问题 2：检索命中率不理想

日志格式不统一、缺少标签、信息密度低，导致 memorySearch 难以找到相关内容。

问题 3：记忆文件缺乏维护

随着时间推移，过期信息堆积，噪音增加，影响检索质量。

本章将逐一解决这些问题。

问题场景：

你和 AI 进行了长时间的深度讨论，制定了重要决策。突然发现 AI 的回复开始变得”健忘”，好像忘记了之前讨论的内容。

原因分析：

每个 AI 模型都有上下文窗口限制（例如 Claude 是 200K tokens）。当对话接近这个限制时，OpenClaw 会触发自动压缩（compaction），将旧对话总结成摘要以腾出空间。压缩过程可能会丢失细节信息。

解决方案：

开启 memoryFlush 功能。该功能会在压缩触发前，先让 AI 将重要信息写入文件，然后再执行压缩。

工作流程：

1. OpenClaw 检测到上下文即将达到限制
2. 触发 memoryFlush，提示 AI 保存重要信息
3. AI 将关键内容写入 memory/ 目录
4. 执行压缩，清理旧对话
5. 重要信息已持久化，不会丢失

配置方法：

编辑 openclaw.json，添加以下配置：

{ "agents": { "defaults": { "compaction": { "reserveTokensFloor": 20000, "memoryFlush": { "enabled": true, "softThresholdTokens": 4000 } } } } }

参数说明：

• reserveTokensFloor: 保留的最小 token 数（20000）
• memoryFlush.enabled: 启用 memoryFlush 功能
• softThresholdTokens: 剩余多少 tokens 时触发（4000）

关于 softThresholdTokens:

这个值设置为 4000 意味着：当剩余空间不足 4000 tokens 时触发 memoryFlush。

• 太小（如 1000）：AI 没有足够空间写入详细信息
• 太大（如 10000）：会频繁触发，影响性能
• 4000 是经过测试的平衡值

效果验证：

启用后，即使进行长时间对话，AI 也能保持对之前讨论内容的记忆，因为关键信息已经持久化到文件中。

提示：memoryFlush 是静默执行的，不会打断对话。如果想查看触发情况，可以启用 verbose 模式（发送 /verbose 命令），会看到 Auto-compaction complete 的提示。

memorySearch 使用向量语义检索技术，将搜索词和日志内容都转换为向量，然后计算相似度。

提升检索准确率的关键因素：

1. 使用标签：标签（如 #deploy #nginx）可以显著提升召回率
2. 结构化格式：固定的格式使关键信息集中，便于匹配
3. 单一主题：一条日志只记录一件事，避免信息混杂

实际效果对比：

假设搜索词为：”nginx 部署配置”

低效日志（命中率低）：

今天工作内容：上午处理了数据库备份问题，中午部署了新版本应用， 下午修改了 nginx 配置，晚上写了一些文档。nginx 那边改了反向代理 的配置，具体记不太清了，反正最后跑起来了。

问题：

• 包含多个不相关主题，稀释了向量相似度
• 缺少结构化信息，关键点不突出
• 没有标签，难以精准匹配

高效日志（命中率高）：

 [项目:WebApp] Nginx 反向代理配置 - 结果：成功配置 Nginx 反向代理，应用通过 443 端口访问 - 相关文件：`/etc/nginx/sites-available/webapp.conf` - 经验教训：upstream 必须使用 127.0.0.1 而非 localhost（避免 IPv6 问题） - 检索标签：#nginx #deploy #webapp #reverse-proxy

优势：

• 标题、结果、标签都包含搜索关键词
• 结构化格式使信息密度高
• 单一主题，向量表示更准确

问题：

随着使用时间增长，日志文件会不断累积。其中一些信息已经过期（如临时调试记录、已完成的一次性任务），这些”噪音”会干扰 memorySearch 的检索结果。

解决方案：

配置定期自动维护任务，让 AI 自己整理记忆。

实现方法：

在 workspace/HEARTBEAT.md 中添加维护任务：

 记忆维护任务（每周执行） 检查 `memory/heartbeat-state.json` 中的 `lastMemoryMaintenance` 字段。 如果距今超过 7 天，执行以下维护流程： 1. 读取最近 7 天的日志文件 `memory/YYYY-MM-DD.md` 2. 提炼有长期价值的信息，归档到对应文件： - 项目决策和状态 → `memory/projects.md` - 问题解决方案 → `memory/lessons.md` 3. 压缩已完成的一次性任务为一行总结 4. 删除完全过期的临时信息 5. 更新 `heartbeat-state.json` 中的 `lastMemoryMaintenance` 为当前日期

创建状态跟踪文件 workspace/memory/heartbeat-state.json：

{ "lastMemoryMaintenance": "2026-02-26" }

维护操作说明：

提炼（Extract）：

将日志中有长期价值的信息移动到对应的层级文件。

示例：日志中记录了一个项目的技术选型决策，应该提炼到 projects.md 中。

压缩（Compress）：

将已完成的详细任务记录压缩为简短的结论。

示例：

• 压缩前：详细记录了部署过程的 10 个步骤
• 压缩后：2026-02-17: 完成 WebApp 生产环境部署，使用 Nginx + Docker 方案

清理（Clean）：

删除完全过期的临时信息。

示例：

• “明天要参加会议” → 会议已过，可以删除
• “测试中的临时配置” → 测试已完成，可以删除

memorySearch 依赖 embedding 模型将文本转换为向量。选择合适的模型可以提升检索质量并降低成本。

推荐配置：

{ "memorySearch": { "enabled": true, "provider": "openai", "remote": { "baseUrl": "https://api.siliconflow.cn/v1", "apiKey": "你的_SiliconFlow_API_Key" }, "model": "BAAI/bge-m3" } }

为什么选择 bge-m3：

• 成本：SiliconFlow 提供免费额度，个人使用足够
• 多语言：对中英文混合文本支持良好
• 性能：向量维度 1024，在精度和速度间取得平衡

获取 SiliconFlow API Key:

1. 访问 siliconflow.cn 注册账号
2. 进入控制台，创建 API Key
3. 免费额度：每天数百万 tokens，个人使用完全足够

memorySearch 工作流程：

用户提问：”上次 nginx 配置问题怎么解决的？”

1. AI 调用 memory_search("nginx 配置问题")
2. memorySearch 返回最相关的几条结果（包含文件路径和行号）
3. AI 调用 memory_get(path="memory/2026-02-18.md", from=47, lines=10)
4. AI 读取具体内容并回答用户

这种两步走的设计很高效：search 负责”定位”，get 负责”读取”，避免加载所有记忆文件。

任务目标：

1. 开启 memoryFlush 功能
2. 按照优化后的格式重写最近 3 条日志
3. 配置自动维护任务
4. 切换到 bge-m3 embedding 模型

验证方法：

• 进行一次长对话（超过 100 轮），观察是否出现失忆
• 使用 memorySearch 搜索之前记录的内容，检查命中率
• 等待一周后检查自动维护是否执行

✅ 完成标准：

• [ ] memoryFlush 配置已启用
• [ ] 日志格式符合优化标准
• [ ] 自动维护任务配置完成
• [ ] embedding 模型切换成功

在基础配置中，OpenClaw 是单线程工作的：你提出一个任务，AI 从头到尾完成。但对于复杂任务，这种模式效率很低。

子 Agent 的定义：

子 Agent 是主 Agent 派生出的独立工作进程，可以并行执行不同的子任务。

形象类比：

• 单 Agent 模式：你是项目经理，所有工作都自己做
• 多 Agent 模式：你是项目经理，可以派遣团队成员并行工作

场景 1：信息收集任务

任务：收集 5 个竞品的功能对比

• 单 Agent：顺序访问 5 个网站，耗时 10 分钟
• 多 Agent：派 5 个子 Agent 并行收集，耗时 2 分钟

场景 2：数据处理任务

任务：分析 100 个文件的内容

• 单 Agent：逐个处理，耗时很长
• 多 Agent：分配给 10 个子 Agent，每个处理 10 个文件

场景 3：监控任务

任务：同时监控多个服务的状态

• 单 Agent：轮询检查，响应慢
• 多 Agent：每个服务分配一个监控 Agent

基础配置：

编辑 openclaw.json：

{ "agents": { "defaults": { "subAgents": { "enabled": true, "maxConcurrent": 3, "timeout":  } } } }

参数说明：

关于 maxConcurrent:

这个值不是越大越好：

• 太小（如 1）：无法发挥并行优势
• 太大（如 10）：可能触发 API 速率限制，增加成本
• 推荐 3-5：在性能和成本间取得平衡

方法 1：自动派遣

AI 会自动判断任务是否适合并行处理。

示例对话：

用户：帮我收集这 5 个网站的主要功能：[网站列表] AI：我将派遣 5 个子 Agent 并行收集信息... [子 Agent 1] 正在分析网站 A... [子 Agent 2] 正在分析网站 B... ... 所有信息已收集完成，正在整理汇总...

方法 2：显式指定

你也可以明确要求使用子 Agent：

用户：使用子 Agent 并行处理这个任务...

1. 任务分解要合理

好的分解：

• 将”分析 100 个文件”分解为 10 个子任务，每个处理 10 个文件

不好的分解：

• 将”写一篇文章”分解为多个子任务（写作需要连贯性，不适合并行）

1. 设置合理的超时时间

根据任务复杂度调整 timeout：

• 简单查询：60 秒
• 数据分析：5 分钟
• 复杂处理：10 分钟

Cron 是一种定时任务调度机制，可以让 OpenClaw 在指定时间自动执行任务。

适用场景：

• 每天早上发送天气提醒
• 每周生成工作总结
• 每月检查系统状态
• 定期备份数据

配置文件位置：workspace/cron/

任务文件格式：

{ "schedule": "0 9 * * *", "command": "发送每日天气提醒", "enabled": true }

Cron 表达式说明：

* * * * * │ │ │ │ │ │ │ │ │ └─ 星期几 (0-6, 0=周日) │ │ │ └─── 月份 (1-12) │ │ └───── 日期 (1-31) │ └─────── 小时 (0-23) └───────── 分钟 (0-59)

常用表达式示例：

• 0 9 * * *：每天上午 9 点
• 0 */6 * * *：每 6 小时
• 0 9 * * 1：每周一上午 9 点
• 0 0 1 * *：每月 1 号凌晨

示例 1：每日天气提醒

{ "schedule": "0 8 * * *", "command": "查询今天天气并发送提醒", "enabled": true }

示例 2：每周工作总结

{ "schedule": "0 18 * * 5", "command": "生成本周工作总结", "enabled": true }

1. 避免任务重叠：确保任务执行时间小于调度间隔
2. 错误处理：为任务添加异常捕获和日志记录
3. 资源限制：避免同时运行过多 Cron 任务

Skill 是 OpenClaw 的扩展机制，允许你为 AI 添加自定义工具和功能。

类比：

• OpenClaw 基础功能 → 手机的原生应用
• Skill → 从应用商店下载的第三方应用

一个 Skill 通常包含以下文件：

skills/my-skill/ ├── SKILL.md # 技能文档 ├── skill.js # 技能实现 └── config.json # 技能配置

步骤 1：创建目录

mkdir -p workspace/skills/my-skill

步骤 2：编写 SKILL.md

# My Skill 这是一个示例技能。 功能 - 功能 1：描述 - 功能 2：描述 使用方法 在对话中直接使用即可。

步骤 3：实现技能逻辑

// skill.js module.exports = { name: 'my-skill', execute: async (args) => { // 技能逻辑 return '执行结果'; } };

1. 文档先行：先写 SKILL.md，明确技能用途
2. 单一职责：一个 Skill 只做一件事
3. 错误处理：添加完善的异常处理
4. 测试验证：充分测试后再部署

OpenClaw 支持多种接入方式：

• Discord
• Telegram
• Slack
• 微信（通过第三方桥接）
• WebChat

步骤 1：创建 Discord 应用

1. 访问 Discord Developer Portal
2. 创建新应用
3. 获取 Bot Token

步骤 2：配置 OpenClaw

编辑 openclaw.json：

{ "channels": { "discord": { "enabled": true, "token": "你的_Discord_Bot_Token" } } }

步骤 1：创建 Telegram Bot

1. 与 @BotFather 对话
2. 创建新 Bot
3. 获取 API Token

步骤 2：配置 OpenClaw

{ "channels": { "telegram": { "enabled": true, "token": "你的_Telegram_Bot_Token" } } }

1. 统一体验：保持各平台功能一致
2. 平台适配：利用各平台特性优化体验
3. 消息格式：注意不同平台的格式限制

temperature 参数：

• 0.0-0.3：精确、一致（适合代码生成）
• 0.4-0.7：平衡（适合日常对话）
• 0.8-1.0：创意、多样（适合创意写作）

maxTokens 参数：

• 根据任务复杂度调整
• 避免设置过大导致成本增加

策略 1：精简提示词

• 去除冗余描述
• 使用简洁指令

策略 2：上下文管理

• 及时清理不必要的历史记录
• 使用 memoryFlush 持久化重要信息

策略 3：缓存策略

• 启用响应缓存
• 对重复查询使用缓存结果

监控指标：

• API 调用次数
• Token 消耗量
• 响应时间
• 错误率

监控工具：

• OpenClaw 内置日志
• 第三方监控服务

• [ ] 创建 AGENTS.md 工作手册
• [ ] 配置 session 启动流程
• [ ] 测试记忆写入功能

• [ ] 开启 memoryFlush 功能
• [ ] 优化日志格式
• [ ] 配置自动维护任务
• [ ] 部署子 Agent
• [ ] 创建 Cron 定时任务

• [ ] 开发自定义 Skill
• [ ] 配置多平台接入
• [ ] 性能调优
• [ ] 建立监控体系

可能原因：

• 文件路径错误
• 文件格式不正确
• 权限问题

解决方法：

检查文件路径和格式，确保文件可读。

可能原因：

• 日志格式不规范
• 缺少标签
• embedding 模型未配置

解决方法：

按照优化后的格式重写日志，检查 embedding 配置。

可能原因：

• 配置未启用
• 并发数设置过小
• API 速率限制

解决方法：

检查配置，调整参数，检查 API 配额。

• OpenClaw 官方文档
• GitHub 仓库
• 社区论坛

1. 深入理解：阅读源码，理解内部机制
2. 实践项目：完成实际项目开发
3. 社区交流：参与社区讨论，分享经验
4. 持续学习：关注更新，学习新特性

• AI Agent 设计模式
• 提示工程最佳实践
• 分布式系统设计

结语

OpenClaw 是一个强大的 AI Agent 框架，通过本教程的学习，你应该已经掌握了从基础到高级的配置和使用方法。持续实践和探索，你会发现更多可能性。

如有问题，欢迎在社区交流讨论。