1. 项目概述：OpenClaw 优化指南的核心价值

如果你正在运行一个 AI 助手，并且它开始变得迟钝、健忘、昂贵，甚至偶尔行为怪异，那么你遇到的问题，我几乎都踩过坑。从上下文窗口爆炸导致的响应冻结，到新会话开始后助手对昨天的工作一无所知，再到看着账单上高昂的 API 调用费用却感觉效率低下——这些都不是单个设置能解决的，它们是一个系统性问题。

这个指南，就是为解决这些问题而生的。它不是一份简单的配置清单，而是一套完整的、经过生产环境验证的架构哲学和实操体系。其核心论点非常直接： 一个 AI 助手 95% 的能力来自于其“缰绳”（Harness）——即围绕核心模型构建的指令、记忆、工具和协调系统，而模型本身的权重只贡献了 5%。 这意味着，同样的模型（比如 Claude Opus），在不同的“驾驭”方式下，表现会天差地别。我们的目标，就是构建那套能发挥出模型全部潜力的 95%。

经过在超过 14 个生产级智能体上长达数月的实战测试和迭代，我们总结出了一套从速度、记忆、编排到安全的完整优化方案。最终的效果是显著的：单次消息的上下文负载从平均 15-20KB 降至 4-5KB，响应延迟从数秒缩短到 1-2 秒，长期记忆从零到可以回溯数周的工作，同时整体 token 成本下降了约 70%。更重要的是，助手的行为变得稳定、可预测，并且真正具备了在复杂任务中自主协调和执行的能力。

无论你是刚刚部署 OpenClaw，正被“为什么我的助手这么慢？”所困扰，还是已经运行了一个多智能体系统，希望将其加固到生产就绪状态，这份指南都能提供直接的、可落地的路径。我们从一个最根本的问题开始：速度。

2. 速度优化：停止缓慢的响应

如果你遇到以下情况，请阅读此部分： 助手响应感觉有延迟、你正在使用 Gemini 或 GPT 的默认配置、或者你想知道哪些调整杠杆最有效。 如果你只打算读一个部分，从这里开始。 如果你已经优化了上下文、设置了备用模型并调整了推理模式，可以跳过。

每次你发送消息时，OpenClaw 都会将所有工作区文件注入到提示词中。臃肿的文件意味着更慢、更昂贵的回复。这是大多数人没有意识到的头号速度问题。

2.1 为什么精简上下文有效

一旦你拥有了向量搜索能力，就不再需要庞大的文件了。

旧方法：把所有东西都塞进 MEMORY.md ，以便助手每次消息都能“看到”它们。结果：上下文超过 15KB，响应缓慢，大量 token 浪费在无关信息上。

新方法： MEMORY.md 是一个精简的指针索引。完整细节存放在 vault/ 目录中。 memory_search() 通过本地的 Ollama 嵌入模型（零成本）即时找到它们。你的工作区文件保持小巧，同时不会丢失任何知识。

2.2 精简你的上下文文件

文件	目标大小	存放内容	为何是这个大小
SOUL.md	< 1 KB	人格、语气、核心规则	每条消息都注入 ——每个字节都消耗延迟
AGENTS.md	2-10 KB	决策树、工具路由、操作协议（如“梦境”机制、协调器规则）	操作协议值得占用这些上下文——它们替代了需要手动输入的提示词
MEMORY.md	< 3 KB	仅存放指针 ——而非完整文档	向量搜索替代了大文件
TOOLS.md	< 1 KB	工具名称 + 一行用法说明	仅是提醒，不是文档
总计	8-15 KB	每条消息注入的全部内容	在包含操作协议的情况下，8-15KB 是可接受的——它们替代了成本更高的人工提示

黄金法则： 如果一段内容比一条推特串还长，那它就不应该放在工作区文件里。把细节移到 vault/ 中。

实操心得： 我最初也舍不得精简 AGENTS.md ，总觉得规则写得越细越好。但实测发现，超过 10KB 后，助手反而会因为信息过载而忽略一些关键指令。将详细的执行流程拆解成独立的技能（Skill）文件，只在需要时通过 memory_search 调用，是更高效的做法。 AGENTS.md 应该像一份高效的“作战手册目录”，而不是整本百科全书。

2.3 添加备用模型（Fallback Model）

在你的配置中设置备用模型，当主模型被限速或响应缓慢时，OpenClaw 会自动切换。

{
  "fallbackModels": ["openrouter/google/gemini-2.0-flash-exp:free"]
}

选择备用模型的逻辑： 备用模型的核心目标是“保底”和“降本”。它不需要拥有主模型最强的推理能力，但需要在速度、成本或可用性上有显著优势。例如，使用 Claude Opus 作为主模型处理复杂规划，而用 Gemini Flash 作为备用处理简单的信息检索或格式化任务。确保备用模型支持你常用的工具调用格式。

2.4 理解并设置推理模式（Reasoning Mode）

运行 /status 命令可以查看当前的推理模式。

• 关闭（Off） ：最快，无“思考”阶段。适合简单、确定性的任务，如数据格式化。
• 低（Low） ：轻度思考，响应较快。在速度和思考深度间取得平衡，适用于大多数日常对话和任务。
• 高（High） ：深度推理，会增加 2-5 秒的延迟，但能捕捉到低/关模式可能遗漏的复杂逻辑或潜在问题。

我的选择： 在生产环境中，我坚持使用 高（High） 模式。因为从其他步骤（如上下文精简）中节省下来的延迟，足以补偿深度推理带来的开销。而深度推理带来的规划准确性和错误规避能力，对于生产系统的稳定性至关重要。一个错误的代码修改决策，其修复成本远高于几秒钟的等待时间。

2.5 禁用未使用的插件

每个启用的插件都会增加开销。检查你的 config.json ，如果确定不需要 memory-lancedb 、 memory-core 等插件，将其 "enabled" 设置为 false 。这能减少启动时间和内存占用。

2.6 为性能较弱的本机模型启用精简模式（Lean Mode）

这是 2026.4.15 版本的新特性。如果你运行的是小型本机模型（参数 ≤140亿，上下文窗口 16K-32K），并且默认的工具集占用了大量提示词空间，可以开启精简标志：

{
  "agents": {
    "defaults": {
      "experimental": { "localModelLean": true }
    }
  }
}

这将从系统提示词中移除重量级的默认工具（如浏览器、定时任务、消息处理）。你仍然会保留 memory_search 、 exec 、 sessions_spawn 等核心工具。对于一个 16K 上下文的 Qwen3-14B 模型来说，释放约 3KB 的工具定义空间，可能就是“可用”和“连一个检索结果都放不下”的天壤之别。

注意事项： 开启 localModelLean 后，助手将无法直接调用那些被移除的工具。你需要通过子智能体（Sub-agent）或特定的技能来间接完成相关功能。这正符合了“编排”的理念：主智能体负责规划和协调，具体的重型任务由专门的“工人”去执行。

2.7 Ollama 运行状态管理

本机嵌入模型是记忆搜索的基石。保持其高效运行很重要。

# 查看当前加载的模型
ollama ps

# 卸载闲置的大型模型（如已加载的文本生成模型）
ollama stop llama3.2:latest

对于记忆搜索，默认模型应该是 qwen3-embedding:0.6b （约 500 MB，1024 维）。它属于在 MTEB 基准测试中排名前列的 Qwen3 家族，能在任何设备上运行，并且质量远超之前的 nomic 模型。通过 ollama pull qwen3-embedding:0.6b 拉取。

性能升级： 如果你拥有 8GB 以上显存的 GPU，强烈建议升级到 Qwen3-Embedding-8B 。更大的模型能生成质量高得多的嵌入向量，从而显著提升搜索的相关性和准确性。具体差异和配置方法，我们会在后续的 嵌入模型专题 中详细展开。

关于 memory-lancedb 的云存储（2026.4.15 新增）： memory-lancedb 插件现在支持将索引持久化到 S3 兼容的对象存储，而不仅仅是本地磁盘。这对于多机器部署（希望每台机器看到相同的索引）或无需 rsync 的单机索引备份很有用。热路径（频繁查询）仍然在内存中——云存储只是持久化层。 不要将其与云嵌入服务混淆 （对于热路径来说，云嵌入仍然不是好主意，延迟太高）。

关于 GitHub Copilot 嵌入提供商（2026.4.15 新增）： 如果你的团队已经为 Copilot Business/Enterprise 付费，那么设置 memorySearch.provider: "copilot" 可以复用该许可进行嵌入计算。它仍然是云服务（2-5秒往返，与 OpenAI/Voyage 有相同的注意事项），因此对于个人设置，本地 Ollama 仍然是正确的默认选择。但对于已经标准化使用 Copilot 的企业部署，这可以减少一个供应商的采购流程。

3. 上下文工程：一门必须掌握的学科

2026年4月更新后重命名。 “上下文膨胀”是 问题 ；上下文工程是解决它的 学科 。Andrew Karpathy 提出了这个概念，并在一周内被行业分析机构采纳。第二部分的内容就是针对 OpenClaw 的、该学科的实践版本。 如果你遇到以下情况，请阅读此部分： 注意到每条消息越来越慢、频繁触发压缩（compaction）、或者你的 SOUL.md / MEMORY.md / AGENTS.md 合计超过了几KB。 如果你注入的总上下文已经低于 15 KB 且很少触发压缩，可以跳过。

3.1 二次方缩放问题

LLM 的注意力机制随着上下文长度呈 二次方 缩放：

• Token 数量翻倍 = 计算成本变为 4 倍
• Token 数量变为 3 倍 = 计算成本变为 9 倍

当上下文从 5 万个 token 增长到 10 万个 token 时，模型需要做 四倍 的工作。这意味着更慢的响应和更高的账单。

3.2 达到上下文窗口 50% 时会发生什么

仅仅因为一个模型 宣称 支持 100 万的上下文，并不意味着它在 100 万 token 时 表现良好 ：

• 测试的 12 个模型中有 11 个 在达到 3.2 万 token 时，准确率降至 50% 以下
• GPT-4.1 在约 13.3 万 token 时，响应时间 增加了 50 倍
• 模型表现出 “中间迷失”偏差 ——它们能跟踪开头和结尾，但会丢失中间部分的信息
• 有效上下文长度通常是最大宣称值的一小部分

3.3 膨胀的来源

来源	典型大小	注入时机
系统提示词	2-5 KB	每条消息
工作区文件	5-20 KB	每条消息
对话历史	随轮次增长	每条消息
工具调用结果	每个 1-50 KB	工具调用后
技能文件	每个 1-5 KB	技能激活时

工具调用结果是最大的膨胀源。 一个返回大文件的 exec 调用，就会永久性地在你的会话中增加 2 万+ token。五次工具调用，就意味着模型每条消息都要重新读取 10 万个 token 的上下文。

3.4 关键的数字指标

生产环境的智能体，其 上下文消耗的 token 数量是生成 token 的 100 倍 。你的上下文窗口就是你的性能预算。

压缩目标 （来自 Maxim AI 的生产数据）：

• 历史上下文： 3:1 到 5:1 的压缩比
• 工具输出： 10:1 到 20:1 的压缩比
• 如果你的智能体在 用户说话前 上下文利用率就 > 60% ，那你就有麻烦了

60% 规则： 如果系统提示词 + 工作区文件 + 记忆搜索结果在用户发送消息前就超过了上下文窗口的 60%，请按顺序应用以下策略：

1. 总结对话历史 ：将过去的对话压缩成要点摘要。
2. 过滤检索结果 ：返回更少、更相关的文本块。
3. 动态路由工具 ：只加载智能体本轮次可能需要的工具定义。
4. 压缩上一步的工具结果 ：对之前的工具输出进行摘要。

3.5 成本计算

精简 (每条消息 5K token)   → Claude Opus: $0.025/条消息
膨胀 (每条消息 50K token) → Claude Opus: $0.25/条消息   ← 贵了 10 倍
每天超过 100 条消息：$2.25/天 vs $22.50/天

3.6 内置的防御机制

会话修剪（Session Pruning） - 从上下文中移除旧的工具结果：

{
  "agents": {
    "defaults": {
      "contextPruning": { "mode": "cache-ttl", "ttl": "5m" }
    }
  }
}

自动压缩（Auto-Compaction） - 在接近上下文限制时，自动总结旧的对话。也可以使用 /compact 命令手动触发。

2026.4.15 修复： 压缩的预留 token 下限现在被限制在模型的实际上下文窗口内。在此之前，在一个 16K token 的本地模型上，压缩操作可能会请求一个比窗口本身还大的预留空间，从而产生“尝试释放 N 个 token，失败，重试”的无限循环。如果你从旧版本升级，这个修复将自动生效。

实操心得： 不要盲目追求最低的上下文占用。 AGENTS.md 中那些精炼的操作协议，虽然占用了 2-10KB，但它们替代了你可能需要手动输入的、每次数百 token 的复杂指令。这是一种“空间换时间（和准确性）”的权衡。关键在于区分什么是“每次都需要”的元指令（放在工作区文件），什么是“按需查询”的具体知识（放在 vault/ 中）。

4. 记忆系统：停止遗忘一切

如果你遇到以下情况，请阅读此部分： 新会话开始时助手对之前的工作一无所知、无法引用过去的决策或对话、感觉每次交互都像是第一次见面。 如果你已经建立了稳定的三层记忆（MEMORY.md + 每日记忆 + 保险库）并且搜索延迟低于 100ms，可以跳过。

记忆是智能体“连续性”的基石。没有记忆，每次对话都是孤岛，无法积累知识，无法从错误中学习，更谈不上长期的协作。OpenClaw 优化的记忆系统是一个分层架构，旨在用最低的成本实现最有效的回忆。

4.1 三层记忆架构

我们的目标不是记住所有事情，而是 在需要时能快速找到任何事 。架构如下：

┌─────────────────────────────────────────────────────────────┐
│                   记忆层（Memory Layer）                      │
├──────────────┬────────────────┬─────────────────────────────┤
│   MEMORY.md  │ memory/*.md    │ vault/*                     │
│  （指针索引） │ （短期记忆）    │ （长期知识库）               │
│   < 3 KB     │ （每日滚动）    │ （原始资料，只读）           │
│   每次注入    │ 按需搜索       │ 按需搜索                    │
└──────────────┴────────────────┴─────────────────────────────┘
         │              │                    │
         └──────────────┼────────────────────┘
                        ▼
                memory_search()
                （本地向量搜索，~45ms）

1. MEMORY.md（指针索引） ：这是注入到每条消息中的、小于 3KB 的文件。它不包含知识本身，而是包含指向知识的“路标”。例如：

   ## 活跃项目
   - 项目 Alpha - 下一代仪表板 → vault/projects/alpha.md
   - 项目 Beta - API 迁移 → vault/projects/beta.md
   
   ## 关键人员
   - 张三 - 后端主管，偏好异步沟通 → vault/people/zhangsan.md
   - 李四 - 产品经理，决策记录在此 → vault/people/lisi.md
   

   它的唯一作用是告诉助手：“如果你想了解项目 Alpha，去 vault/projects/alpha.md 里找。”

2. memory/YYYY-MM-DD.md（短期记忆） ：这是自动捕获的每日日志。每次会话结束后，重要的输出（如代码片段、决策理由、会议摘要）会被自动追加到当天的文件中。它提供了“最近发生了什么”的上下文。这些文件也是向量搜索的来源之一。

3. vault/（保险库） ：这是知识的最终归宿。所有详细的笔记、会议记录、项目文档、学习心得都存放在这里，按主题组织。它是 只读 的，智能体不能直接修改，只能通过 memory promote 命令将短期记忆中的内容“提升”进来，或者通过 auto-capture 钩子自动归档。这保证了核心知识的稳定性和可审计性。

4.2 记忆工作流：从产生到固化

1. 产生 ：在一次会话中，你与助手讨论了项目 Beta 的 API 设计，并最终决定采用 GraphQL。
2. 自动捕获 ：会话结束时， auto-capture 钩子会将“决定对项目 Beta 使用 GraphQL”以及相关的讨论要点，自动写入 memory/2026-04-16.md 。
3. 搜索 ：三天后，你问：“我们为什么给 Beta 选 GraphQL？” 助手运行 memory_search("Beta GraphQL 原因") 。向量搜索会在 memory/ 和 vault/ 中查找相关片段，并在几毫秒内返回结果。
4. 提升 ：一周后，你觉得这个决策足够重要，值得长期保留。你运行 memory promote ，并指定相关片段。系统会引导你将这个决策及其理由，以结构化的方式（例如，作为一个新的 Markdown 小节）写入 vault/projects/beta.md 。同时， MEMORY.md 中的指针可能会被更新，以更精确地指向这个新章节。
5. 固化 ：现在，这个知识被永久地记录在 vault/ 中，可以被未来的任何会话检索到。 MEMORY.md 中的指针确保了它能被快速定位。

4.3 配置与优化要点

嵌入模型选择：

• 默认/入门： ollama pull qwen3-embedding:0.6b 。质量好，资源占用低，几乎所有机器都能跑。
• 生产/追求质量： ollama pull Qwen3-Embedding-8B 。需要 GPU（8GB+ VRAM），但检索准确率有质的提升，尤其对于复杂、专业或语义细微的查询。
• 团队/企业： 如果公司已统一使用 GitHub Copilot，可配置 memorySearch.provider: "copilot" 作为嵌入来源。 注意： 这是云服务，有网络延迟（2-5秒）。仅推荐在已有许可且对延迟不敏感的内部知识库场景使用。

向量数据库配置：

{
  "memorySearch": {
    "provider": "ollama",
    "ollamaModel": "qwen3-embedding:0.6b",
    "database": {
      "type": "lancedb",
      "storage": {
        "type": "local", // 或 "s3" 用于云存储
        "path": "./.openclaw/data/lancedb"
      }
    }
  }
}

内存核心（memory-core）与内置梦境（Built-In Dreaming）： memory-core 插件负责管理 MEMORY.md 和 DREAMS.md （梦境日记）。从 2026.4.15 开始， 内置的梦境机制是官方推荐路径 。它会自动运行一个三阶段的巩固流程：

• 浅度阶段 ：快速总结当日记忆。
• 深度阶段 ：识别模式，将重要内容提升到 MEMORY.md 。
• 梦境阶段 ：进行创造性关联和反思，写入 DREAMS.md 。 这个机制替代了旧版中需要自定义的 autoDream 钩子，更加稳定和集成化。

常见问题排查：

• 搜索返回无关内容 ：检查嵌入模型是否匹配文本语言。对于中文， qwen3-embedding 系列比 nomic-embed-text 表现更好。同时，确保你的 vault/ 文档是结构良好的 Markdown，标题清晰。
• 记忆未被捕获 ：检查 auto-capture 钩子是否启用，并查看 memory/ 目录下是否有最新的日期文件。
• MEMORY.md 变得臃肿 ：定期审查。指针应该简洁。如果一个项目已经结束，可以考虑将其从 MEMORY.md 的“活跃项目”移到 vault/projects/archive/ ，并更新指针为“历史项目 → vault/projects/archive/xxx.md”。

避坑指南： 最大的坑是试图把 vault/ 当成一个垃圾场，随意丢入大量未处理的文本（如整篇论文、冗长的会议录音稿）。这会导致搜索质量急剧下降。务必对存入 vault/ 的内容进行预处理：提取关键结论、用清晰的标题和段落组织、添加相关标签或链接。高质量的输入是高质量记忆检索的前提。

5. 编排：停止所有事情都亲力亲为

如果你遇到以下情况，请阅读此部分： 你的主智能体（通常是 Claude Opus）正在亲自编写冗长的代码、进行深度网络研究、处理复杂的数据分析，导致每次调用成本高昂、速度缓慢。 如果你已经建立了稳定的子智能体（Sub-agent）协调模式，并且主智能体主要扮演“指挥者”角色，可以跳过。

编排的核心思想是： 让合适的模型做合适的事。 你的主力模型（如 Claude Opus）应该是一位“首席执行官（CEO）”或“指挥家”，负责高级规划、决策和协调。而具体的、耗时的执行任务，应该交给更便宜、更快、或更专业的“工人”智能体。

5.1 为什么需要编排

1. 成本效益： Claude Opus 生成 1000 个 token 的成本，足以让 Gemini Flash 生成上万个 token，或者让本地的 Qwen3-14B 模型运行好几轮。用 Opus 来写简单的数据转换代码，是巨大的浪费。
2. 速度： 专用的代码智能体可能针对代码生成进行了优化，响应更快。网络搜索智能体可以并行处理多个查询。
3. 专业化： 不同的模型在不同任务上各有专长。GPT-4 可能更擅长创意写作，而 Claude 在逻辑推理和遵循复杂指令方面更出色。
4. 稳定性： 如果一个子智能体崩溃或产生错误输出，主智能体可以捕捉到并重新调度任务，而不会导致整个会话失败。

5.2 五种协调模式

借鉴 Anthropic 的研究，以下是五种有效的多智能体协调模式：

1. CEO/Worker（首席执行官/工人）模式：

   • CEO（主智能体）： 接收用户请求，将其分解为子任务，创建并管理 Worker 智能体，汇总结果。
   • Worker（子智能体）： 执行具体的、定义明确的任务，如写代码、查资料、分析数据。
   • 示例： 用户说“帮我分析这个季度的销售数据并写一份报告”。CEO 会创建一个“数据分析师”Worker 来处理数据，再创建一个“文案”Worker 来撰写报告，最后整合。

2. 辩论会（Debate）模式：

   • 多个智能体就一个问题提出不同观点或解决方案，并进行辩论。
   • 主智能体或另一个“评审”智能体根据辩论内容做出最终决定。
   • 适用于： 复杂决策、代码审查、方案评估。

3. 工具调用链（Tool-Using Chain）模式：

   • 一个智能体的输出直接作为下一个智能体的输入或工具参数。
   • 示例： 智能体 A 搜索最新资料，智能体 B 根据这些资料起草内容，智能体 C 进行校对和格式化。

4. 验证者（Verifier）模式：

   • 一个智能体（执行者）产生输出，另一个智能体（验证者）检查输出的正确性、安全性和是否符合要求。
   • 示例： 代码生成智能体写完函数后，由另一个智能体运行单元测试或进行安全检查。

5. 分层规划（Hierarchical Planning）模式：

   • 高层智能体制定战略计划，中层智能体将其转化为战术任务，底层智能体执行。
   • 适用于： 极其复杂的项目，如软件开发全流程。

5.3 在 OpenClaw 中实现 CEO/Worker 模式

这是最常用且易于实现的模式。关键在于 AGENTS.md 中的规则和 sessions_spawn 工具。

在 AGENTS.md 中定义规则：

## 编排协议 (Orchestration Protocol)

你是指挥官（CEO）。你的职责是：
1.  **理解全局：** 分析用户请求的最终目标。
2.  **任务分解：** 将复杂请求拆解为独立的、可并行执行的子任务。
3.  **工人派遣：** 使用 `sessions_spawn` 工具创建专门的工人智能体（Worker）来执行每个子任务。为每个工人提供清晰的指令、上下文和所需工具。
4.  **监督与整合：** 监控工人进度，解决冲突，并将他们的工作成果整合成最终交付物。

## 工人创建准则

遇到以下情况时，必须创建工人：
- 需要编写超过 50 行代码。
- 需要进行深度网络研究（超过 2 个简单查询）。
- 需要执行复杂的计算或数据分析。
- 任务具有明确的专业边界（如“设计数据库 schema”和“编写前端组件”）。

创建工人时，必须指定：
- `agent`: 选择合适的模型（如 `gemini-2.0-flash-exp` 用于研究，`claude-3-5-sonnet` 用于代码）。
- `instructions`: 清晰、无歧义的任务描述，包括输入、预期输出和任何约束。
- `context`: 提供必要的背景信息，但不要复制你的全部上下文。

主智能体（CEO）的实际操作： 当用户提出一个复杂请求时，主智能体不会立即开始执行。它会先规划，然后类似这样操作：

# 假设用户在请求一个数据分析和可视化的任务
# 主智能体（CEO）在内部规划后，执行：
sessions_spawn agent="openrouter/google/gemini-2.0-flash-exp:free" instructions="请搜索过去一年关于‘AI代理成本优化’的最新文章和案例研究，总结出5个关键趋势，并以Markdown列表形式返回。搜索关键词已包含在上下文中。" context="用户需要了解AI代理成本优化的最新趋势。请使用网络搜索工具。"

sessions_spawn agent="claude-3-5-sonnet" instructions="根据以下销售数据（JSON格式，已在上下文中），使用Python的matplotlib和pandas库生成三个图表：1) 月度销售额趋势线图；2) 产品类别销售额饼图；3) 地区销售额柱状图。将代码保存为 `sales_analysis.py`，并附上简单的数据解读。" context="这是销售数据JSON：..."

然后，CEO 会等待工人返回结果，检查质量，并整合成最终答案回复给用户。

5.4 模型选择策略

你的 config.json 中的 fallbackModels 列表，实际上就是你的“工人池”。精心配置它：

{
  "fallbackModels": [
    "openrouter/google/gemini-2.0-flash-exp:free", // 快速研究、摘要
    "openrouter/anthropic/claude-3-5-sonnet",      // 代码、复杂逻辑（比Opus便宜）
    "openrouter/meta-llama/llama-3.3-70b-instruct", // 通用任务，性价比高
    "ollama/qwen3:14b"                             // 本地，零成本，简单任务
  ]
}

编排的心得： 开始时最容易犯的错误是“过度编排”——为一个非常简单的任务也创建工人。这反而增加了复杂性和延迟。我的经验法则是： 如果主智能体自己能在 30 秒内完成，并且消耗的 token 成本可接受，那就自己做。 编排是为了解决“主智能体做起来太贵、太慢或不专业”的问题。衡量标准是总体的时间成本和经济成本，而不仅仅是步骤数量。

6. 模型选择：实际该用什么

如果你遇到以下情况，请阅读此部分： 对众多模型感到困惑、不确定在速度/成本/质量间如何权衡、想设置一个高效的模型梯队。 如果你已经根据任务类型建立了清晰的模型路由策略，并且对当前成本满意，可以跳过。

模型是智能体能力的引擎，也是成本的主要来源。没有“最好”的模型，只有“最适合当前任务”的模型。我们的目标是构建一个模型梯队，在质量、速度和成本之间取得最佳平衡。

6.1 主要提供商与模型对比

提供商	代表模型	优势	劣势	典型用途
Anthropic	Claude Opus, Claude Sonnet	极强的指令遵循、逻辑推理、长上下文、安全性高	价格最贵、速度相对较慢	主智能体（CEO）、复杂规划、关键决策
Google	Gemini 2.0 Flash, Gemini 2.0 Pro	速度极快、价格便宜（Flash）、多模态能力强	指令遵循有时不如Claude严格、上下文窗口管理	备用模型、研究、摘要、快速生成
OpenAI	GPT-4o, o1	生态成熟、工具调用稳定、思维链推理强（o1）	价格中等、政策变化可能影响可用性	通用任务、创意写作、与现有OpenAI生态集成
OpenRouter	各种模型聚合	统一API、价格透明、模型选择极多	多了一层依赖、极端小众模型可能不稳定	访问特定模型（如 Llama 3.3 70B）、成本对比
本地 (Ollama)	Qwen3, Llama 3.2, Mistral	零API成本 、数据隐私、可离线	需要硬件、能力弱于顶级云端模型、上下文窗口较小	简单任务、数据预处理、作为特定技能的工人

6.2 生产环境模型配置策略

以下是一个经过实战检验的配置思路：

1. 主模型（CEO / 指挥者）：

• 首选：Claude Opus。 尽管贵，但其卓越的规划、协调和遵循复杂协议的能力，使其在整体工作流中节省的成本远超其本身费用。它犯的错少，做的决策准。
• 备选：Claude Sonnet。 如果成本敏感，Sonnet 是很好的平衡点，能力依然很强，价格低不少。
• 配置： 在 config.json 中将其设为默认模型。

2. 快速工人模型（Fast Worker）：

• 首选：Gemini 2.0 Flash。 速度飞快，价格低廉，非常适合网络搜索、信息摘要、文本格式化、简单代码生成等任务。
• 配置： 将其加入 fallbackModels 列表前列。在 AGENTS.md 的编排规则中，指定这类任务由 Flash 执行。

3. 代码专家模型（Code Specialist）：

• 首选：Claude 3.5 Sonnet 或 GPT-4o。 两者在代码生成和理解上都表现优异。Sonnet 可能更便宜一些。
• 本地备选：DeepSeek Coder 或 CodeQwen。 如果代码任务不涉及复杂业务逻辑，本地代码模型是零成本的绝佳选择。
• 配置： 在需要编写超过 50 行代码或进行复杂代码审查时，由主智能体派发任务给此模型。

4. 本地通用模型（Local Generalist）：

• 首选：Qwen3 14B 或 Llama 3.2 70B。 用于处理简单的问答、文档总结、数据提取等不要求最高智商的任务。
• 作用： 承担大量低强度工作，将云端模型的调用留给真正需要它的任务，从而大幅降低总体成本。

示例 config.json 片段：

{
  "defaultModel": "anthropic/claude-3-opus", // 主模型：Claude Opus
  "fallbackModels": [
    "openrouter/google/gemini-2.0-flash-exp:free", // 快速工人
    "openrouter/anthropic/claude-3-5-sonnet",       // 代码专家/次级指挥
    "openrouter/meta-llama/llama-3.3-70b-instruct", // 高性价比通用
    "ollama/qwen3:14b"                              // 本地零成本工人
  ],
  "agents": {
    "defaults": {
      "experimental": {
        "localModelLean": true // 如果主要用本地模型，开启此选项
      }
    }
  }
}

6.3 关键决策因子

1. 任务复杂度 vs. 模型能力： 不要用大炮打蚊子，也不要用水果刀砍树。匹配是关键。
2. 延迟要求： 实时对话需要快速模型（如 Gemini Flash），后台批处理任务可以忍受更慢但更强的模型（如 Claude Opus）。
3. 成本预算： 明确你的每月预算，并据此分配模型使用比例。使用 OpenRouter 的计费面板监控开销。
4. 隐私要求： 敏感数据必须使用本地模型或具有明确数据处理协议的提供商（如 Anthropic 的某些企业计划）。

6.4 监控与调优

• 使用 OpenRouter 或提供商控制台： 定期查看使用量和费用报表，分析哪个模型消耗最多，是否物有所值。
• 日志分析： 检查智能体的会话日志，看看是否经常因为模型能力不足而重复或纠正任务。这可能意味着需要升级该任务的模型。
• A/B 测试： 对于关键任务类型，可以短暂地让两个不同的模型执行相同任务，比较结果质量和成本。

避坑指南： 最常见的错误是“模型忠诚度”——坚持只用一个模型。这要么导致成本失控（只用 Opus），要么导致能力不足（只用本地小模型）。必须建立 模型路由 思维。另一个坑是忽略了 上下文窗口 。一个宣称 128K 窗口的模型，在用到 80K 时性能可能已经急剧下降。对于长文档处理，要么先进行摘要，要么使用专门的“长上下文模型+检索”的混合方案。

7. 网络搜索：为你的智能体装上互联网的眼睛

如果你遇到以下情况，请阅读此部分： 智能体的知识截止日期较早，无法获取最新信息；你需要它查找实时数据、新闻、价格或文档。 如果你已经稳定集成 Tavily 或 Brave Search 并配置了结果过滤，可以跳过。

没有网络搜索能力的 AI 助手，就像被关在信息孤岛里。它的知识停留在训练数据截止的那一天。对于需要最新资讯、价格对比、查找特定错误解决方案或研究新技术的任务，网络搜索是必不可少的。

7.1 主要搜索提供商对比

提供商	特点	优势	劣势	适用场景
Tavily	专为 AI 代理优化	结果已针对 LLM 总结优化、API 简单、支持自定义搜索深度	是付费服务、可能不如通用搜索引擎全面	首选 。需要简洁、可直接使用答案的 AI 工作流。
Brave Search	隐私优先的搜索引擎	提供真实的网页摘要和链接、结果质量高、有免费套餐	需要处理原始 HTML、结果需要后处理	需要原始链接和更多控制权的场景。
Serper	谷歌搜索 API	结果来自谷歌、非常全面	价格较贵、返回的是原始搜索结果	需要最大化搜索结果覆盖面的情况。
Google Gemini Grounding	与 Gemini 模型深度集成	在 Gemini 模型中使用时，搜索和回答无缝衔接	绑定 Gemini 模型、可能产生额外费用	主要使用 Gemini 模型，且需要最新信息增强回答。

7.2 配置 Tavily（推荐）

1. 获取 API 密钥： 前往 Tavily 官网 注册并获取 API 密钥。
2. 配置 OpenClaw： 在 config.json 的 tools 部分启用并配置 tavily_search 。

   {
     "tools": {
       "tavily_search": {
         "enabled": true,
         "apiKey": "你的_Tavily_API_密钥",
         "searchDepth": "advanced", // "basic" 或 "advanced"
         "includeAnswer": true, // 是否包含 AI 生成的答案摘要
         "includeRawContent": false // 为节省上下文，通常设为 false
       }
     }
   }
   

3. 在 AGENTS.md 中定义使用规则：

   ## 网络搜索协议
   
   当用户的问题涉及以下情况时，你必须使用 `tavily_search` 工具：
   - 询问当前日期之后的事件或新闻。
   - 询问价格、产品规格、版本号等可能变化的信息。
   - 询问一个你不知道具体答案，但相信互联网上存在的信息。
   - 用户明确要求“搜索一下”。
   
   搜索时，请遵循以下准则：
   1.  **构造精准查询词：** 使用关键词，避免长句。例如，用“Python asyncio timeout best practice 2026”而不是“我怎么用 asyncio 设置超时”。
   2.  **指定数量：** 使用 `numResults` 参数限制结果数量（通常 3-5 个足够）。
   3.  **评估来源：** 优先考虑官方文档（如 `python.org`, `developer.mozilla.org`）、知名的技术博客（如 Stack Overflow, GitHub 官方仓库）和主流新闻网站。
   4.  **引用来源：** 在回答中注明信息来自哪个网站，并附上链接。
   

7.3 配置 Brave Search（备用）

1. 获取 API 密钥： 前往 Brave Search API 注册。
2. 配置 OpenClaw： 启用 brave_search 工具。

   {
     "tools": {
       "brave_search": {
         "enabled": true,
         "apiKey": "你的_Brave_API_密钥"
       }
     }
   }
   

3. 结果处理： Brave 返回的是标准搜索结果（标题、链接、摘要）。智能体需要自己阅读摘要或决定是否点击链接获取更多内容。这给了你更多控制权，但也增加了智能体的工作量。

7.4 搜索策略与优化

• 避免过度搜索： 不是每个问题都需要搜索。如果知识库（ vault/ ）中已有答案，优先使用 memory_search 。搜索会增加延迟和成本（如果使用付费搜索 API）。
• 组合搜索与记忆： 对于复杂问题，可以先搜索最新信息，再结合记忆库中的背景知识进行综合回答。
• 缓存搜索结果： 对于频繁查询的静态信息（如某个库的安装命令），可以将搜索到的可靠答案通过 memory promote 提升到 vault/ 中，以后直接使用。
• 处理搜索失败： 在 AGENTS.md 中规定，如果搜索未找到答案或返回错误，智能体应如实告知用户，并尝试基于已有知识进行推理或建议其他查找途径。

实操心得： Tavily 的 includeAnswer: true 非常有用，它提供了一个由 AI 生成的答案摘要，智能体可以直接引用或在此基础上扩展，这比处理多个原始摘要更高效。但要注意，这个摘要可能不完全准确，对于关键信息，我仍然会要求智能体查阅 rawContent （如果启用）或打开原始链接进行核实。 永远不要完全信任单一来源。 另外，为搜索工具设置 速率限制 很重要，避免智能体陷入“搜索循环”或意外产生高额 API 费用。

8. 一键式处理大任务：停止迭代，开始研究

如果你遇到以下情况，请阅读此部分： 面对一个庞大、模糊的任务（如“重构这个模块”、“研究这个市场”），智能体要么不知所措，要么开始盲目行动，导致大量无效迭代。 如果你已经习惯在开始执行前，先让智能体制定详细的研究计划和步骤，可以跳过。

传统的人机交互模式是“迭代式”的：用户给出一个模糊指令，智能体尝试做一点，用户反馈，智能体调整，如此循环。对于大任务，这极其低效。“一键式”方法论的核心是： 在执行任何具体操作之前，先进行彻底的研究和规划。

8.1 一键式工作流

用户提出复杂任务
    ↓
智能体进入“研究模式”
    ↓
1. 任务分解与问题澄清
2. 内部知识库检索 (`memory_search`)
3. 外部信息搜索 (`tavily_search`)
4. 制定详细执行计划 (PRD.json)
5. 用户确认计划
6. 按计划并行/顺序执行
    ↓
交付最终成果

这个流程将“思考”和“执行”分离，确保行动建立在充分的信息基础上，减少返工。

8.2 核心：PRD.json（产品需求文档）

PRD.json 不是一个固定的文件，而是一个结构化的思维框架。智能体在研究阶段结束时，应输出这样一个 JSON 对象作为计划：

{
  "project_name": "用户身份认证模块重构",
  "goal": "将现有的基于Session的身份认证迁移为无状态的JWT方案，提升扩展性和安全性。",
  "success_criteria": [
    "所有现有API端点支持JWT验证",
    "向后兼容Session机制至少30天",
    "登录/注销性能提升20%",
    "新增令牌刷新机制"
  ],
  "assumptions": [
    "当前代码库为Node.js Express",
    "已有用户数据库模型",
    "项目使用ES6+语法"
  ],
  "open_questions": [
    "是否需支持多端同时登录？",
    "JWT密钥轮换策略如何定？",
    "现有移动端SDK是否兼容？"
  ],
  "research_summary": {
    "internal_knowledge": "找到了2024年关于‘认证瓶颈’的会议记录，指出Session存储在内存是问题根源。",
    "external_findings": "JWT最佳实践（2026）：使用HS512算法，设置合理的exp和nbf，issuer字段必填。推荐使用 `jsonwebtoken` 库 v10+。"
  },
  "phases": [
    {
      "name": "Phase 1: 分析与设计",
      "tasks": [
        "分析现有认证中间件代码",
        "设计JWT payload结构",
        "选择并评估JWT库",
        "起草迁移回滚方案"
      ],
      "agent": "claude-3-5-sonnet",
      "estimated_tokens": 5000
    },
    {
      "name": "Phase 2: 核心实现",
      "tasks": [
        "实现JWT签发与验证中间件",
        "更新登录/注销路由",
        "添加令牌刷新端点"
      ],
      "agent": "claude-3-5-sonnet",
      "estimated_tokens": 8000
    },
    {
      "name": "Phase 3: 测试与部署",
      "tasks": [
        "编写单元测试和集成测试",
        "进行性能基准测试",
        "更新API文档",
        "制定分阶段发布计划"
      ],
      "agent": "gemini-2.0-flash",
      "estimated_tokens": 4000
    }
  ],
  "risks": [
    "破坏现有移动端应用登录",
    "JWT密钥泄露风险",
    "迁移期间认证服务宕机"
  ],
  "dependencies": ["需要访问生产数据库Schema", "需要运维团队配合部署窗口"]
}

8.3 如何在 AGENTS.md 中实施

你需要制定明确的协议，告诉智能体何时以及如何触发“一键式”工作流。

## 大任务处理协议 (One-Shot Protocol)

当用户请求符合以下**任一**条件时，你必须进入“研究优先”模式，而不是立即开始执行：
1.  任务描述中包含“研究”、“分析”、“评估”、“规划”等词。
2.  任务预估需要超过 1 小时人工工时。
3.  任务涉及多个系统或模块。
4.  任务目标模糊，需要澄清（例如：“让系统更快”）。
5.  用户明确说“先做个计划”。

**研究阶段必须包括：**
1.  **澄清问题：** 向用户提问，以精确理解需求、约束条件和成功标准。
2.  **内部检索：** 使用 `memory_search` 查找相关过往项目、决策记录、技术笔记。
3.  **外部搜索：** 使用 `tavily_search` 获取最新的行业实践、工具推荐、潜在风险。
4.  **制定 PRD：** 综合以上信息，生成结构化的 `PRD.json` 文档。
5.  **获取确认：** 将 `PRD.json` 呈现给用户，并获得其对计划和预估资源的批准。

**只有在用户确认 PRD 后，才能开始执行阶段。** 执行时应遵循 PRD 中的阶段划分和模型分配。

8.4 优势与注意事项

优势：

• 减少浪费： 避免在错误的方向上投入大量生成和计算资源。
• 提高透明度： 用户提前看到全盘计划，可以中途修正方向。
• 便于协作： PRD.json 可以作为不同智能体（或与人类）之间交接工作的清晰文档。
• 优化资源： 根据任务类型（研究、编码、测试）智能分配最合适的模型，节约成本。

注意事项：

• 平衡开销： 对于一个 5 分钟就能完成的小任务，生成完整的 PRD 是过度的。协议中必须有明确的触发阈值。
• 灵活调整： PRD 不是圣经。在执行过程中发现新信息时，智能体应能暂停并建议调整计划。
• 用户耐心： 需要教育用户接受“先思考，后行动”的模式，这可能会让期待立即行动的用户感到不耐烦。

个人体会： 引入“一键式”流程是提升智能体价值最关键的一步。它把智能体从“高级打字员”变成了“初级项目经理”。最大的转变在于，我不再问“帮我写个函数”，而是问“帮我把这个模块重构一下”。智能体会反过来问我一系列 clarifying questions（澄清性问题），然后给我一个包含调研结果的计划。我批准后，它才开工。整个过程从“盲目的试错”变成了“有管理的项目”，产出质量和工作满意度都大幅提升。

9. 保险库记忆系统：停止在会话间丢失知识

如果你遇到以下情况，请阅读此部分： 感觉每次新对话都像是重启，助手记不住之前的项目细节、技术决策或个人偏好；知识无法在长期积累。 如果你已经建立了结构化的 vault/ 目录，并熟练使用 memory promote 和 MOCs，可以跳过。

vault/ 是你的长期知识库，是智能体记忆的“硬盘”。它的组织方式直接决定了知识检索的效率和准确性。一个混乱的 vault/ 比没有 vault/ 更糟。

9.1 保险库组织结构

不要把所有文件扔在一个文件夹里。采用基于主题的、可扩展的结构：

vault/
├── projects/               # 项目相关
│   ├── project-alpha.md
│   ├── project-beta.md
│   └── archive/           # 已完结项目
├── people/                # 人物档案
│   ├── alice.md
│   └── bob.md
├── areas/                 # 兴趣或责任领域
│   ├── programming/
│   │   ├── python.md
│   │   └── javascript.md
│   └── health.md
├── resources/             # 外部资源索引
│   ├── books.md
│   └── tools.md
├── meetings/              # 会议记录
│   └── 2026-04-16-standup.md
└── .learnings/           # 自动捕获的学习心得（由 auto-capture 钩子写入）
    └── 2026-04-16.md

核心原则：

• 原子性： 每个文件围绕一个核心主题。 project-alpha.md 只关于 Alpha 项目，不要混入 Python 学习笔记。
• 可链接： 大量使用 Markdown 链接 [[ ]] 来关联相关文件。这有助于未来基于图的检索（如 LightRAG）。
• 声明式命名： 文件名应清晰表明内容，如 python-asyncio-best-practices-2026.md 而非 notes.md 。

9.2 MOC（内容地图）的力量

MOC 是 vault/ 的组织核心。它是一个索引文件，列出了某个主题下的所有相关笔记。

示例： vault/projects/project-alpha/MOC.md

# Project Alpha - 内容地图

## 概述
- **状态：** 进行中
- **目标：** 构建下一代用户仪表板
- **负责人：** [[Alice]]
- **开始日期：** 2026-04-01

## 核心文档
- [[Project Alpha 产品需求文档]]
- [[技术架构设计]]
- [[API 接口规范]]

## 会议记录
- [[2026-04-10 项目启动会]]
- [[2026-04-15 架构评审]]

## 决策记录
- [[2026-04-12 决定使用 React 而非 Vue]]
- [[2026-04-14 选择 GraphQL 作为主要 API 风格]]

## 相关资源
- [[UI 设计稿链接]]
- [[性能测试报告]]

为什么 MOC 重要？

1. 为智能体提供导航： MEMORY.md 中的指针可以指向 vault/projects/project-alpha/MOC.md 。智能体通过查看 MOC，就能了解项目的全貌和所有相关文档的位置。
2. 便于人类维护： 你可以通过更新 MOC 来管理项目知识，而不需要记住每个文件的具体位置。
3. 赋能高级检索： 像 LightRAG 这样的图检索系统，可以利用 MOC 中的链接来构建知识图谱，实现更精准的关联查询。

9.3 知识获取与固化流程

1. 自动捕获（Auto-Capture）： 配置 auto-capture 钩子。每次会话结束后，它会自动分析对话，提取关键的学习点、决策、待办事项，并将其写入 vault/.learnings/YYYY-MM-DD.md 。这是知识的“种子”。
2. 定期回顾与提升（Promotion）： 每周或每两周，使用 memory promote 命令回顾 .learnings/ 中的内容。将有长期价值的部分，分类整理并写入到正式的 vault/ 文件中（如项目文档、人物档案等）。同时，更新相关的 MOC 文件，添加链接。
3. 手动补充： 不要完全依赖自动捕获。主动将重要的邮件、文档、阅读笔记整理成 Markdown 文件存入 vault/ 。

9.4 维护与保鲜

• 定期清理： 将已完结的项目移至 archive/ 子目录。更新 MEMORY.md 中的指针状态。
• 死链检查： 偶尔检查 vault/ 中是否有指向不存在的文件的 [[ ]] 链接。
• 版本控制： 将 vault/ 目录纳入 Git 版本控制。这不仅是备份，还可以追踪知识的演变历史。

避坑指南： 最大的挑战是 启动惯性 ——觉得整理知识太麻烦，干脆不开始。我的建议是： 从最小可行开始 。第一周，只要求自己每天结束前，手动在 vault/.learnings/ 里写一条最重要的收获。第二周，开始尝试将一条收获“提升”到正式的项目文件里。慢慢培养习惯。另一个坑是 过度分类 ，创建了太多层级和文件夹，导致找一个文件要点击无数次。遵循“宽浅优于窄深”的原则，优先使用标签和链接来组织，而不是复杂的文件夹树。

10. 状态前沿的嵌入模型

（注：此部分为外部链接内容概要，此处提供核心解读和配置建议） 嵌入模型是将文本转换为数值向量（嵌入）的模型，是向量搜索的基石。其质量直接决定 memory_search 的准确性。

核心要点：

1. 默认选择： qwen3-embedding:0.6b 。在 MTEB 基准测试中表现优异，仅 500MB 大小，几乎可在任何设备运行，是平衡性能与资源的最佳起点。
2. 性能升级： Qwen3-Embedding-8B 。如果你有 8GB 以上 VRAM 的 GPU，强烈推荐。更大的模型尺寸带来更精准的语义理解，尤其对于复杂、专业或细微差别的查询，效果提升显著。
3. Windows 路径问题 ：Ollama 在 Windows 上默认安装路径可能包含空格，导致 OpenClaw 调用失败。解决方案：将 Ollama 安装到无空格的路径（如 C:\Ollama ），或通过环境变量 OLLAMA_HOST 和 OLLAMA_MODELS 进行配置。
4. GitHub Copilot 作为提供商 ：对于已购买 Copilot Business/Enterprise 的团队，可设置 memorySearch.provider: "copilot" 。这利用了现有许可，但需注意这是云服务，有网络延迟（2-5秒），仅推荐在延迟不敏感的企业内部知识库场景作为备选， 不推荐作为个人或低延迟场景的主要方案 。
5. GPU 层级选择 ：如果使用 GPU 运行嵌入模型，确保 Ollama 配置正确（例如设置 OLLAMA_NUM_GPU=1 ）。对于 Qwen3-Embedding-8B ，8GB VRAM 是流畅运行的最低要求。

配置示例 (config.json):

{
  "memorySearch": {
    "provider": "ollama",
    "ollamaModel": "qwen3-embedding:0.6b", // 或 "Qwen3-Embedding-8B"
    "database": {
      "type": "lancedb"
    }
  }
}

行动建议： 如果你刚开始，直接拉取 qwen3-embedding:0.6b 。如果你对搜索质量不满意且有 GPU，升级到 8B 版本。除非身处已标准化使用 Copilot 的企业环境，否则坚持使用本地 Ollama 方案，以获得最佳的搜索速度和数据隐私。

11. 自动捕获钩子

（注：此部分为外部链接内容概要） auto-capture 钩子是在每次会话结束后自动运行的脚本，用于从对话中提取有价值的信息并写入记忆系统。

它做什么：

• 分析会话记录。
• 识别关键信息：决策、学习点、待办事项、代码片段、引用链接等。
• 将这些信息以结构化的格式（如 Markdown 列表）追加到 memory/YYYY-MM-DD.md （每日记忆）文件中。
• 有时也会直接向 vault/.learnings/ 写入更精炼的总结。

为什么重要：

• 减轻手动负担： 你不需要记住每次对话后要记录什么。
• 避免遗漏： 捕获那些当时觉得不重要，但后来可能有用的上下文。
• 为记忆提升（Promotion）提供原料： .learnings/ 和每日记忆文件是执行 memory promote 操作的主要来源。

配置与自定义： 钩子逻辑可以在 OpenClaw 的配置或插件设置中定义。你可以调整其敏感度（捕获多少内容）、输出格式以及目标文件。

个人建议： 务必启用此功能。它是构建持久化记忆的“自动化流水线”的第一步。即使捕获的内容有些噪音，后期通过 memory promote 进行筛选和整理，也比从零开始回忆和记录要高效得多。

12. 自我改进系统

（注：此部分为外部链接内容概要） 这是一个更高级的概念，旨在让智能体能够从自己的行动和结果中学习，并持续优化其行为。

核心是创建一个“微学习循环”：

1. 执行： 智能体执行任务。
2. 评估： 根据预定义的成功标准（如代码是否通过测试、用户是否满意）评估结果。
3. 反思： 智能体分析成功或失败的原因。
4. 内化： 将反思得到的经验教训，通过 memory promote 或类似的机制，转化为可重用的知识或规则，存入 vault/ 或更新 AGENTS.md 中的协议。

分层记忆（HOT/WARM/COLD）：

• HOT（热）： MEMORY.md 和当前会话上下文。立即可用，但容量小。
• WARM（温）： memory/*.md 每日文件。通过向量搜索快速访问，存储近期细节。
• COLD（冷）： vault/ 中的深度知识。需要更精确的搜索，存储长期、结构化的知识。

自我改进系统就是促进知识从 HOT → WARM → COLD 流动的引擎，同时根据 COLD 知识来优化 HOT 中的行为规则。

实现层面： 这通常需要通过自定义钩子或技能来实现，监听任务完成事件，触发评估和反思流程，并调用记忆更新函数。这属于高级用法，但对于希望智能体真正“成长”的用户来说，是终极目标。

13. 记忆桥梁

（注：此部分为外部链接内容概要） 记忆桥梁解决了一个特定问题：如何让那些本身不具备 memory_search 功能的 AI 工具或服务（如 Claude Code、GitHub Copilot、Cursor 等）也能访问你的保险库知识。

工作原理： 记忆桥梁通常是一个独立的服务或中间件，它：

1. 暴露一个 API 端点，接收查询。
2. 在本地执行向量搜索（查询你的 vault/ 和 memory/ ）。
3. 将搜索结果格式化为上下文片段。
4. 将该上下文注入到目标工具的系统提示词或编辑器中。

例如，为 Claude Code 设置记忆桥梁：

• 安装一个桥接插件或服务。
• 配置 Claude Code 在编写代码时，自动向桥梁服务发送当前文件或函数的上下文。
• 桥梁服务返回相关的代码片段、设计模式或项目规范，并插入到 Claude Code 的编辑窗口附近。

价值： 这打破了智能体之间的知识孤岛，让你在任意编码环境中都能获得统一的、个性化的知识辅助，极大提升了开发体验的一致性。

14. 快速检查清单（30分钟设置）

按照此清单操作，可以在30分钟内完成核心优化设置。

1. 精简工作区文件（5分钟）

   • 打开 SOUL.md ，删除所有非核心的人格描述和规则，压缩到 1KB 以内。
   • 打开 MEMORY.md ，删除所有完整段落，只保留项目/人员名称和指向 vault/ 的链接。目标 < 3KB。
   • 打开 AGENTS.md ，保留核心的编排、工具使用、梦境协议，删除过于细碎的例子。目标 2-10KB。
   • 打开 TOOLS.md ，只保留工具名和一行描述。

2. 设置本地嵌入模型（5分钟）

   • 确保 Ollama 已安装并运行。
   • 终端执行： ollama pull qwen3-embedding:0.6b
   • 在 config.json 中确认 memorySearch.provider 为 "ollama" ，且 ollamaModel 为 "qwen3-embedding:0.6b" 。

3. 配置模型梯队（5分钟）

   • 在 config.json 中，设置 defaultModel 为你最强的模型（如 "anthropic/claude-3-opus" ）。
   • 在 fallbackModels 列表中，按顺序添加更便宜/更快的模型，例如： ["openrouter/google/gemini-2.0-flash-exp:free", "openrouter/anthropic/claude-3-5-sonnet", "ollama/qwen3:14b"] 。

4. 启用关键插件（5分钟）

   • 在 config.json 的 plugins 部分，确保 memory-core 和 memory-lancedb 的 "enabled": true 。
   • 如果使用网络搜索，启用并配置 tavily_search 或 brave_search 。

5. 创建初始保险库结构（5分钟）

   • 在 OpenClaw 工作区根目录创建 vault/ 文件夹。
   • 在 vault/ 下创建子文件夹： projects/ , people/ , areas/ , resources/ , meetings/ , .learnings/ 。
   • 在 vault/projects/ 下为你当前的主要项目创建一个 MOC.md 文件，并添加几个基础条目。

6. 更新智能体协议（5分钟）

   • 打开 AGENTS.md ，添加或完善“编排协议”部分，规定主智能体作为协调者，将复杂任务分配给子智能体。
   • 添加“大任务处理协议”，要求对复杂任务先研究、制定 PRD，再执行。
   • 添加“网络搜索协议”，规定何时及如何搜索。

完成以上六步，你的 OpenClaw 助手将在速度、记忆力和协作效率上获得立竿见影的提升。

15. 基础设施加固

（注：此部分为外部链接内容概要，此处提炼核心安全与稳定性措施） 将智能体投入生产环境，必须考虑安全性和稳定性。

核心加固措施：

1. 修复压缩崩溃循环： 2026.4.15 版本已修复在 16K 上下文模型上，压缩操作可能因请求过多预留 token 而陷入无限循环的问题。确保你运行的是该版本或更高。
2. GPU 资源争用管理： 如果同时运行多个需要 GPU 的模型（如文本生成和嵌入），使用 CUDA_VISIBLE_DEVICES 环境变量或 Ollama 的 OLLAMA_NUM_GPU 设置来分配资源，避免内存溢出。
3. 密钥与权限隔离：
   • 绝不将 API 密钥硬编码在 config.json 中。使用环境变量或密钥管理服务。
   • 为 OpenClaw 进程创建独立的系统用户，限制其文件系统访问权限。
   • 在 config.json 中严格定义 allowedPaths ，防止智能体访问或修改敏感目录。
4. 网关崩溃循环修复： 确保网关（Gateway）有正确的重启和监控机制（如 systemd 服务配置 Restart=on-failure ）。
5. 审批与密钥脱敏： 配置 Task Brain 控制平面，对包含密钥等敏感信息的审批请求进行自动脱敏，防止泄露。
6. 并行运行与 Git 工作树： 对于需要同时处理多个代码库或项目分支的场景，可以使用 Git 工作树（worktree）为每个任务创建独立的文件系统视图，避免冲突。OpenClaw 可以配置在不同的工作树目录中运行独立的实例。

安全基线： 生产部署至少应实现：密钥管理、路径隔离、基于角色的工具访问控制（通过 AGENTS.md 中的规则）、以及完整的审计日志（通过 Task Brain）。

16. 内置梦境（memory-core）

（注：此部分为外部链接内容概要，2026.4.15 后成为官方路径） 梦境（Dreaming）是记忆系统自动进行的巩固和反思过程。

三阶段巩固流程：

1. 浅度阶段： 快速总结 memory/ 中当天的记忆文件，提取关键事件。
2. 深度阶段： 分析模式，识别重要信息，并将其“提升”到 MEMORY.md 这个持久的指针索引中。
3. 梦境阶段： 进行更抽象的联想、反思和创意生成，结果写入 DREAMS.md 文件。这有助于智能体形成更深刻的“理解”而不仅仅是“记忆”。

如何工作： memory-core 插件会定期（例如每天一次）或在触发条件下自动运行这个流程。它读取短期记忆，调用 LLM 进行分析和总结，然后更新 MEMORY.md 和 DREAMS.md 。

配置： 在 config.json 中配置 memory-core 插件，设置梦境运行的时间表（如 cron 表达式）和强度参数。

价值： 自动化了记忆从“短期”到“长期”再到“内化”的升华过程，是构建真正具有持续学习能力智能体的关键组件。从 2026.4.15 开始，这是官方推荐的方式，取代了旧版中需要自定义的 autoDream 钩子。

17. 一键设置提示词

将以下提示词复制给你的 OpenClaw 智能体（主模型，如 Claude Opus），它可以自动引导你完成大部分优化设置。 (基于 2026.4.15 稳定版)

你是一位 OpenClaw 配置专家。我将引导你进行一系列优化，以显著提升你的速度、记忆力和效率。请严格按照以下步骤操作，并在每个步骤后确认完成。

**第一步：环境检查**
1.  请运行 `/status` 命令，告诉我你的当前模型、上下文使用情况和启用的插件。
2.  请检查你的工作区根目录下是否存在 `vault/` 文件夹。如果不存在，请创建它。

**第二步：精简工作区文件**
我们将压缩关键文件。请提供以下文件的当前内容，我将指导你删减：
1.  请展示 `SOUL.md` 的完整内容。
2.  请展示 `MEMORY.md` 的完整内容。
3.  请展示 `AGENTS.md` 的完整内容。
4.  请展示 `TOOLS.md` 的完整内容。
（等待我提供具体的删减指导）

**第三步：配置模型与搜索**
1.  请检查你的 `config.json` 中 `defaultModel` 和 `fallbackModels` 的设置。告诉我它们当前的值。
2.  你是否已配置网络搜索（如 Tavily）？如果已配置，提供相关配置片段；如果未配置，请根据我的指导添加。
（等待我提供优化建议）

**第四步：初始化记忆系统**
1.  请运行命令检查 Ollama 服务是否运行，并列出已拉取的模型：`ollama list`。
2.  如果 `qwen3-embedding:0.6b` 不在列表中，请拉取它：`ollama pull qwen3-embedding:0.6b`。
3.  在 `vault/` 文件夹下创建以下子文件夹：`projects/`, `people/`, `areas/`, `resources/`, `meetings/`, `.learnings/`。

**第五步：更新智能体协议**
我将为你提供优化后的 `AGENTS.md` 核心协议片段，包括：
1.  **编排协议**：规定你作为协调者（CEO），将复杂任务分配给子智能体（Worker）。
2.  **大任务处理协议**：要求对复杂任务先研究、制定 PRD，再执行。
3.  **网络搜索协议**：规定搜索时机和方式。
4.  **记忆规则**：要求在回答关于过去的问题前，必须使用 `memory_search`。
请将这些协议整合到你的 `AGENTS.md` 文件中。

**第六步：验证与测试**
1.  完成以上所有更改后，请重启 OpenClaw 网关（或相关服务）以使配置生效。
2.  进行一次简单的测试：问我一个关于你自身配置的问题（例如，“你当前使用的嵌入模型是什么？”），并验证你的回答是否利用了更新后的记忆和搜索能力。

请从第一步开始，逐步执行。在每一步完成后，告诉我“步骤X完成”并附上结果或确认。

使用这个提示词，你可以通过与智能体对话的方式，交互式地完成整个优化流程。智能体会引导你检查状态、修改文件、运行命令，并最终验证设置是否成功。这是最快捷的入门方式。

18. 常见问题与排查技巧实录

在实战中，你会遇到各种各样的问题。这里记录了一些最常见的情况及其解决方法。

18.1 速度与响应问题

问题：智能体响应非常慢，每条消息都要等好几秒。

• 检查上下文大小： 运行 /status ，查看“Context Usage”是否接近或超过模型限制。如果很高，立即按 Part 1 和 Part 2 的方法精简 SOUL.md 、 MEMORY.md 、 AGENTS.md 。
• 检查插件： 禁用所有非必需的插件。特别是检查是否有插件在每次消息时进行缓慢的网络调用。
• 检查模型： 确认你是否不小心在使用一个速度很慢的模型作为默认模型。尝试切换到 gemini-2.0-flash 看看速度是否有改善。
• 检查网络： 如果是云端模型，可能是网络延迟。尝试 ping 一下 API 端点。

问题：智能体经常在生成中途停止，或者说“达到上下文限制”。

• 这是典型的上下文膨胀。 立即使用 /compact 命令手动压缩当前会话历史。
• 长期解决： 启用 contextPruning 配置，设置较短的 TTL（如 "5m" ），让旧工具结果自动过期。
• 审查 AGENTS.md ： 是否有一条规则导致智能体在每次响应中都附加大量文本？优化规则，避免生成冗长的中间输出。

18.2 记忆与搜索问题

**问题：