openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-15 10:56:13 +00:00
parent d3541ac5dd
commit 62066ef3e6
6 changed files with 1114 additions and 1091 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

140
docs/zh-CN/concepts/dreaming.md
View File

@ -1,127 +1,118 @@
---
read_when:
- 你希望记忆提升自动运行
- 你想了解每个做梦阶段的作用
- 你想了解每个 Dreaming 阶段的作用
- 你想在不污染 `MEMORY.md` 的情况下调整巩固过程
summary: 通过浅睡、深睡和 REM 阶段进行后台记忆巩固，并配有梦境日记
title: 做梦（实验性）
summary: 通过浅层、深层和 REM 阶段进行后台记忆巩固，并配有梦境日记
title: Dreaming
x-i18n:
generated_at: "2026-04-15T00:30:39Z"
generated_at: "2026-04-15T10:48:13Z"
model: gpt-5.4
provider: openai
source_hash: 5882a5068f2eabe54ca9893184e5385330a432b921870c38626399ce11c31e25
source_hash: a5bcaec80f62e7611ed533094ef1917bd72c885f57252824db910e1f0496adc6
source_path: concepts/dreaming.md
workflow: 15
---
# 做梦（实验性）
# Dreaming
做梦是 `memory-core` 中的后台记忆巩固系统。
它帮助 OpenClaw 将强烈的短期信号转移到持久记忆中，同时
让整个过程保持可解释且可审查。
Dreaming 是 `memory-core` 中的后台记忆巩固系统。
它帮助 OpenClaw 将强烈的短期信号转入持久记忆，同时让整个过程保持可解释和可审查。
做梦为**选择启用**功能，默认禁用。
Dreaming 是**可选启用**功能，默认处于禁用状态。
## 做梦会写入什么
## Dreaming 会写入什么
做梦会保留两类输出：
Dreaming 会保留两类输出：
- `memory/.dreams/` 中的**机器状态**（召回存储、阶段信号、摄取检查点、锁）。
- `DREAMS.md`（或现有的 `dreams.md`）中的**人类可读输出**，以及可选的 `memory/dreaming/<phase>/YYYY-MM-DD.md` 阶段报告文件。
- `DREAMS.md`（或现有的 `dreams.md`）中的**人类可读输出**，以及位于 `memory/dreaming/<phase>/YYYY-MM-DD.md` 下的可选阶段报告文件。
长期提升仍然只会写入 `MEMORY.md`。
## 阶段模型
做梦使用三个协作阶段：
Dreaming 使用三个协同阶段：
| 阶段 | 目的 | 持久写入 |
| ----- | ----------------------------------------- | ----------------- |
| 浅睡 | 对近期短期材料进行整理和暂存 | 否 |
| 深睡 | 对持久候选项进行评分并提升 | 是（`MEMORY.md`） |
| REM | 反思主题和反复出现的想法 | 否 |
| Light | 对近期短期材料进行整理和暂存 | 否 |
| Deep | 对持久候选项进行评分并提升 | 是（`MEMORY.md`） |
| REM | 反思主题和反复出现的想法 | 否 |
这些阶段是内部实现细节，不是单独的用户可配置“模式”。
这些阶段是内部实现细节，并不是单独的用户可配置“模式”。
### 浅睡阶段
### Light 阶段
浅睡阶段会摄取近期的每日记忆信号和召回轨迹，对其去重，
并暂存候选条目。
Light 阶段会摄取近期的每日记忆信号和召回轨迹，对其去重，并暂存候选条目。
- 在可用时，从短期召回状态、近期每日记忆文件以及已脱敏的会话转录中读取。
- 当存储包含内联输出时，写入受管控的 `## 浅睡` 区块。
- 记录强化信号，供后续深睡排序使用。
- 在可用时，从短期召回状态、近期每日记忆文件以及已脱敏的会话转录中读取内容。
- 当存储包含内联输出时，会写入一个受管理的 `## Light Sleep` 区块。
- 记录强化信号，供后续 Deep 排名使用。
- 绝不会写入 `MEMORY.md`。
### 深睡阶段
### Deep 阶段
深睡阶段决定哪些内容会变成长期开启的记忆。
Deep 阶段决定哪些内容会成为长期记忆。
- 使用加权评分和阈值门槛对候选项进行排序。
- 要求通过 `minScore`、`minRecallCount` 和 `minUniqueQueries`。
- 在写入前从实时每日文件中重新提取片段，因此过时或已删除的片段会被跳过。
- 在写入前，会从实时的每日文件中重新提取片段，因此过时或已删除的片段会被跳过。
- 将提升后的条目追加到 `MEMORY.md`。
- 将 `## 深睡` 摘要写入 `DREAMS.md`，并可选写入 `memory/dreaming/deep/YYYY-MM-DD.md`。
- 将 `## Deep Sleep` 摘要写入 `DREAMS.md`，并可选写入 `memory/dreaming/deep/YYYY-MM-DD.md`。
### REM 阶段
REM 阶段会提取模式和反思信号。
- 从近期短期轨迹中构建主题和反思摘要。
- 当存储包含内联输出时，写入受管控的 `## REM Sleep` 区块。
- 记录供深睡排序使用的 REM 强化信号。
- 当存储包含内联输出时，会写入一个受管理的 `## REM Sleep` 区块。
- 记录供 Deep 排名使用的 REM 强化信号。
- 绝不会写入 `MEMORY.md`。
## 会话转录摄取
做梦可以将已脱敏的会话转录摄取到做梦语料中。当
转录可用时，它们会与每日记忆信号和召回轨迹一起送入浅睡阶段。个人和敏感内容会在摄取前被脱敏。
Dreaming 可以将已脱敏的会话转录摄取到 dreaming 语料中。
当转录可用时，它们会与每日记忆信号和召回轨迹一起输入到 Light 阶段。在摄取之前，个人内容和敏感内容会被脱敏。
## 梦境日记
做梦还会在 `DREAMS.md` 中保留一份叙事性的**梦境日记**。
每个阶段积累了足够材料后，`memory-core` 会尽力运行一次后台
子智能体轮次（使用默认运行时模型），并追加一条简短的日记条目。
Dreaming 还会在 `DREAMS.md` 中保留一份叙事性的**梦境日记**。
在每个阶段积累了足够材料后，`memory-core` 会以尽力而为的方式运行一次后台子智能体轮次（使用默认运行时模型），并追加一条简短的日记条目。
这份日记用于人在 Dreams UI 中阅读，而不是作为提升来源。
由做梦生成的日记/报告工件会被排除在短期
提升之外。只有有依据的记忆片段才有资格被提升到
`MEMORY.md` 中。
这份日记是供人类在 Dreams UI 中阅读的，不是提升来源。
由 Dreaming 生成的日记/报告工件会从短期提升中排除。只有有依据的记忆片段才有资格被提升到 `MEMORY.md`。
此外，还有一条基于依据的历史回填通道，用于审查和恢复工作：
此外，还有一条基于事实依据的历史回填通道，用于审查和恢复工作：
- `memory rem-harness --path ... --grounded` 会从历史 `YYYY-MM-DD.md` 笔记中预览基于依据的日记输出。
- `memory rem-backfill --path ...` 会将可逆的、基于依据的日记条目写入 `DREAMS.md`。
- `memory rem-backfill --path ... --stage-short-term` 会将基于依据的持久候选项暂存到与常规深睡阶段已使用的同一短期证据存储中。
- `memory rem-backfill --rollback` 和 `--rollback-short-term` 会移除这些已暂存的回填工件，而不会触及普通日记条目或实时短期召回。
- `memory rem-harness --path ... --grounded` 会从历史 `YYYY-MM-DD.md` 笔记中预览有依据的日记输出。
- `memory rem-backfill --path ...` 会将可逆的有依据日记条目写入 `DREAMS.md`。
- `memory rem-backfill --path ... --stage-short-term` 会将有依据的持久候选项暂存到与正常 Deep 阶段已使用的同一短期证据存储中。
- `memory rem-backfill --rollback` 和 `--rollback-short-term` 会移除这些已暂存的回填工件，而不会触碰普通日记条目或实时短期召回。
Control UI 也提供同样的日记回填/重置流程，因此你可以先在 Dreams 场景中检查
结果，再决定这些基于依据的候选项是否值得提升。
该场景还会显示一条独立的基于依据通道，这样你就能看到
哪些已暂存的短期条目来自历史回放、哪些已提升项目由依据驱动，并且只清除仅基于依据的已暂存条目，而不会影响普通的实时短期状态。
Control UI 公开了相同的日记回填/重置流程，因此你可以先在 Dreams 场景中检查结果，再决定这些有依据的候选项是否值得提升。该场景还会显示一条独立的有依据通道，这样你就能看到哪些已暂存的短期条目来自历史回放、哪些已提升条目由 grounded 流程引导生成，并且可以只清除仅限 grounded 的已暂存条目，而不影响普通的实时短期状态。
## 深睡排序信号
## Deep 排名信号
深睡排序使用六个加权基础信号，加上阶段强化：
Deep 排名使用六个带权重的基础信号，再加上阶段强化：
| 信号 | 权重 | 描述 |
| 信号 | 权重 | 说明 |
| ------------------- | ------ | ------------------------------------------------- |
| 频率 | 0.24 | 条目积累了多少短期信号 |
| 相关性 | 0.30 | 条目的平均检索质量 |
| 查询多样性 | 0.15 | 使其浮现的不同查询/日期上下文 |
| 时效性 | 0.15 | 随时间衰减的新鲜度评分 |
| 巩固度 | 0.10 | 跨日重复出现的强度 |
| 频率 | 0.24 | 该条目累积了多少短期信号 |
| 相关性 | 0.30 | 该条目的平均检索质量 |
| 查询多样性 | 0.15 | 使其出现的不同查询/日期上下文 |
| 时新性 | 0.15 | 经过时间衰减的新鲜度分数 |
| 巩固度 | 0.10 | 跨多日重复出现的强度 |
| 概念丰富度 | 0.06 | 来自片段/路径的概念标签密度 |
浅睡和 REM 阶段命中会从
`memory/.dreams/phase-signals.json` 增加一个随时间衰减的小幅提升。
Light 和 REM 阶段命中会从 `memory/.dreams/phase-signals.json` 增加一个小幅的、按时新性衰减的提升。
## 调度
启用后，`memory-core` 会自动管理一个 cron 任务，用于执行完整的做梦
扫描。每次扫描都会按顺序运行各阶段：浅睡 -> REM -> 深睡。
启用后，`memory-core` 会自动管理一个 cron 任务，用于执行完整的 dreaming 扫描。
每次扫描都会按顺序运行各阶段：light -> REM -> deep。
默认节奏行为：
默认频率行为：
| 设置 | 默认值 |
| -------------------- | ----------- |
@ -129,7 +120,7 @@ Control UI 也提供同样的日记回填/重置流程，因此你可以先在 D
## 快速开始
启用做梦：
启用 dreaming：
```json
{
@ -147,7 +138,7 @@ Control UI 也提供同样的日记回填/重置流程，因此你可以先在 D
}
```
使用自定义扫描节奏启用做梦：
使用自定义扫描频率启用 dreaming：
```json
{
@ -187,18 +178,16 @@ openclaw memory promote --limit 5
openclaw memory status --deep
```
手动 `memory promote` 默认使用深睡阶段阈值，除非通过
CLI 标志覆盖。
手动执行 `memory promote` 时，默认会使用 Deep 阶段阈值，除非你通过 CLI 标志覆盖。
解释某个特定候选项为什么会或不会被提升：
说明某个特定候选项为什么会或不会被提升：
```bash
openclaw memory promote-explain "router vlan"
openclaw memory promote-explain "router vlan" --json
```
预览 REM 反思、候选事实和深睡提升输出，
且不写入任何内容：
在不写入任何内容的情况下，预览 REM 反思、候选事实和 Deep 提升输出：
```bash
openclaw memory rem-harness
@ -214,20 +203,19 @@ openclaw memory rem-harness --json
| `enabled` | `false` |
| `frequency` | `0 3 * * *` |
阶段策略、阈值和存储行为都是内部实现
细节（不是面向用户的配置）。
阶段策略、阈值和存储行为都属于内部实现细节（不是面向用户的配置）。
完整键名列表请参阅 [记忆配置参考](/zh-CN/reference/memory-config#dreaming-experimental)。
完整键名列表请参阅 [记忆配置参考](/zh-CN/reference/memory-config#dreaming)。
## Dreams UI
启用后，Gateway 网关中的 **Dreams** 选项卡会显示：
启用后，Gateway 网关的 **Dreams** 选项卡会显示：
- 当前做梦启用状态
- 阶段级状态和受管控扫描是否存在
- 短期、基于依据、信号以及今日已提升计数
- 当前 dreaming 启用状态
- 阶段级状态和受管理扫描的存在情况
- 短期、有依据、信号以及当日已提升计数
- 下一次计划运行时间
- 一条用于已暂存历史回放条目的独立 grounded 场景通道
- 一条用于暂存历史回放条目的独立 grounded 场景通道
- 由 `doctor.memory.dreamDiary` 支持的可展开梦境日记阅读器
## 相关内容

44
docs/zh-CN/concepts/experimental-features.md Normal file
View File

@ -0,0 +1,44 @@
---
read_when:
- 你看到一个 ``.experimental`` 配置键，想知道它是否稳定。
- 你想试用预览版运行时功能，同时不把它们与正常默认设置混淆。
- 你想在一个地方找到当前已记录的实验性标志。
summary: OpenClaw 中的实验性标志是什么意思，以及当前已记录了哪些实验性标志？
title: 实验性功能
x-i18n:
generated_at: "2026-04-15T10:48:34Z"
model: gpt-5.4
provider: openai
source_hash: 2d1c7b3d4cd56ef8a0bdab1deb9918e9b2c9a33f956d63193246087f8633dcf3
source_path: concepts/experimental-features.md
workflow: 15
---
# 实验性功能
OpenClaw 中的实验性功能是**需主动启用的预览能力**。它们被放在显式标志之后，是因为这些功能在成为稳定默认设置或长期公开契约之前，仍需要经过真实世界的使用验证。
请将它们与普通配置区别对待：
- 除非相关文档明确告诉你要尝试，否则默认应**保持关闭**。
- 预期它们的**结构和行为变化速度**会快于稳定配置。
- 如果已经有稳定路径，优先使用稳定路径。
- 如果你要大范围部署 OpenClaw，请先在较小环境中测试实验性标志，再将其纳入共享基线配置。
## 当前已记录的标志
| 能力面 | 键名 | 适用场景 | 更多信息 |
| ----------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| 本地模型运行时 | `agents.defaults.experimental.localModelLean` | 较小或更严格的本地后端无法处理 OpenClaw 完整的默认工具能力面 | [本地模型](/zh-CN/gateway/local-models) |
| 记忆搜索 | `agents.defaults.memorySearch.experimental.sessionMemory` | 你希望 `memory_search` 为先前的会话转录建立索引，并接受额外的存储和索引开销 | [记忆配置参考](/zh-CN/reference/memory-config#session-memory-search-experimental) |
| 结构化规划工具 | `tools.experimental.planTool` | 你希望在兼容的运行时和 UI 中公开结构化的 `update_plan` 工具，用于多步骤工作跟踪 | [Gateway 网关配置参考](/zh-CN/gateway/configuration-reference#toolsexperimental) |
## 本地模型精简模式
`agents.defaults.experimental.localModelLean: true` 是为较弱的本地模型配置提供的减压阀。它会裁剪掉像 `browser`、`cron` 和 `message` 这类重量级默认工具，从而让提示词结构更小，并降低其在小上下文或更严格的 OpenAI 兼容后端中的脆弱性。
这**并不是**正常路径。如果你的后端能够干净地处理完整运行时，请保持此项关闭。
## 实验性不等于隐藏
如果某项功能是实验性的，OpenClaw 就应该在文档和配置路径本身中明确说明。**不应该**做的是，把预览行为偷偷塞进一个看起来稳定的默认开关里，然后假装这很正常。配置能力面正是这样变得混乱的。

106
docs/zh-CN/concepts/memory.md
View File

@ -1,84 +1,84 @@
---
read_when:
- 你想了解 memory 的工作方式
- 你想知道应该写入哪些 memory 文件
summary: OpenClaw 如何跨会话记住信息
title: Memory 概览
- 你想了解内存是如何工作的
- 你想知道应该写入哪些内存文件
summary: OpenClaw 如何在跨会话时记住内容
title: 内存概览
x-i18n:
generated_at: "2026-04-08T21:50:09Z"
generated_at: "2026-04-15T10:48:12Z"
model: gpt-5.4
provider: openai
source_hash: 2fe47910f5bf1c44be379e971c605f1cb3a29befcf2a7ee11fb3833cbe3b9059
source_hash: ad1adafe1d81f1703d24f48a9c9da2b25a0ebbd4aad4f65d8bde5df78195d55b
source_path: concepts/memory.md
workflow: 15
---
# Memory 概览
# 内存概览
OpenClaw 通过在你的智能体工作区中写入**纯 Markdown 文件**来记住信息。模型只会“记住”保存到磁盘上的内容——不存在隐藏状态。
OpenClaw 通过在你的智能体工作区中写入**纯 Markdown 文件**来记住内容。模型只会“记住”已保存到磁盘的内容——不存在隐藏状态。
## 工作原理
你的智能体有三个与 memory 相关的文件：
你的智能体有三个与内存相关的文件：
- **`MEMORY.md`** —— 长期记忆。保存持久事实、偏好和决策。会在每个私信会话开始时加载。
- **`memory/YYYY-MM-DD.md`** —— 每日笔记。保存持续积累的上下文和观察内容。今天和昨天的笔记会自动加载。
- **`DREAMS.md`**（实验性，可选）—— Dream Diary 和 dreaming sweep 摘要，供人工审查，其中包含有依据的历史回填条目。
- **`MEMORY.md`** —— 长期记忆。持久保存的事实、偏好和决定。会在每个私信会话开始时加载。
- **`memory/YYYY-MM-DD.md`** —— 每日笔记。持续记录的上下文和观察内容。系统会自动加载今天和昨天的笔记。
- **`DREAMS.md`**（可选）—— Dream Diary 和 Dreaming 扫描摘要，供人工审查，其中包括有据可依的历史回填条目。
这些文件位于智能体工作区中（默认是 `~/.openclaw/workspace`）。
<Tip>
如果你希望你的智能体记住某件事，直接告诉它即可：“记住我更喜欢 TypeScript。” 它会将内容写入相应的文件。
如果你希望智能体记住某件事，只要直接告诉它：“记住我更喜欢 TypeScript。” 它会把内容写入合适的文件。
</Tip>
## Memory 工具
## 内存工具
智能体有两个用于处理 memory 的工具：
智能体有两个用于处理内存的工具：
- **`memory_search`** —— 使用语义搜索查找相关笔记，即使措辞与原文不同也可以找到。
- **`memory_get`** —— 读取指定的 memory 文件或行范围。
- **`memory_get`** —— 读取特定的内存文件或行范围。
这两个工具都由当前激活的 memory 插件提供（默认：`memory-core`）。
这两个工具都由当前启用的内存插件提供（默认：`memory-core`）。
## Memory Wiki 配套插件
如果你希望持久记忆的行为更像是一个持续维护的知识库，而不只是原始笔记，可以使用内置的 `memory-wiki` 插件。
如果你希望持久记忆更像一个持续维护的知识库，而不只是原始笔记，请使用内置的 `memory-wiki` 插件。
`memory-wiki` 会将持久知识编译到一个 wiki 资料库中，包含：
`memory-wiki` 会将持久知识编译为一个 wiki 仓库，包含：
- 确定性的页面结构
- 结构化的主张与证据
- 矛盾与时效性跟踪
- 自动生成的仪表板
- 生成的仪表板
- 面向智能体/运行时消费者的编译摘要
- wiki 原生工具，如 `wiki_search`、`wiki_get`、`wiki_apply` 和 `wiki_lint`
它不会替代当前激活的 memory 插件。当前激活的 memory 插件仍然负责回忆、提升和 dreaming。`memory-wiki` 则在其旁边增加了一层带有丰富来源信息的知识层。
它不会替代当前启用的内存插件。当前内存插件仍然负责召回、提升和 Dreaming。`memory-wiki` 则在其旁边增加了一层带有丰富溯源信息的知识层。
参见 [Memory Wiki](/zh-CN/plugins/memory-wiki)。
## Memory 搜索
## 内存搜索
配置 embedding 提供商后，`memory_search` 会使用**混合搜索**——将向量相似度（语义含义）与关键词匹配（如 ID 和代码符号等精确术语）结合起来。一旦你为任意受支持的提供商配置了 API key，它即可开箱即用。
当已配置嵌入提供商时，`memory_search` 会使用**混合搜索**——将向量相似度（语义含义）与关键词匹配（如 ID 和代码符号等精确术语）结合起来。一旦你为任意受支持的提供商配置了 API 密钥，它就能开箱即用。
<Info>
OpenClaw 会根据可用的 API key 自动检测你的 embedding 提供商。如果你已配置 OpenAI、Gemini、Voyage 或 Mistral key，memory 搜索会自动启用。
OpenClaw 会根据可用的 API 密钥自动检测你的嵌入提供商。如果你已配置 OpenAI、Gemini、Voyage 或 Mistral 密钥，内存搜索会自动启用。
</Info>
有关搜索工作原理、调优选项和提供商设置的详细信息，请参见
有关搜索工作方式、调优选项和提供商设置的详细信息，请参见
[Memory Search](/zh-CN/concepts/memory-search)。
## Memory 后端
## 内存后端
<CardGroup cols={3}>
<Card title="内置（默认）" icon="database" href="/zh-CN/concepts/memory-builtin">
基于 SQLite。开箱即用，支持关键词搜索、向量相似度和混合搜索。无需额外依赖。
</Card>
<Card title="QMD" icon="search" href="/zh-CN/concepts/memory-qmd">
local-first sidecar，支持重排序、查询扩展，以及为工作区外部目录建立索引的能力。
local-first sidecar，支持重排、查询扩展，以及为工作区外的目录建立索引。
</Card>
<Card title="Honcho" icon="brain" href="/zh-CN/concepts/memory-honcho">
AI 原生的跨会话 memory，支持用户建模、语义搜索和多智能体感知。需安装插件。
AI 原生的跨会话内存，支持用户建模、语义搜索和多智能体感知。通过插件安装。
</Card>
</CardGroup>
@ -86,40 +86,40 @@ AI 原生的跨会话 memory，支持用户建模、语义搜索和多智能体
<CardGroup cols={1}>
<Card title="Memory Wiki" icon="book" href="/zh-CN/plugins/memory-wiki">
将持久记忆编译为一个带有丰富来源信息的 wiki 资料库，包含主张、仪表板、桥接模式以及对 Obsidian 友好的工作流。
将持久记忆编译为一个带有丰富溯源信息的 wiki 仓库，包含主张、仪表板、桥接模式，以及对 Obsidian 友好的工作流。
</Card>
</CardGroup>
## 自动 memory 刷新
## 自动内存刷新
在 [compaction](/zh-CN/concepts/compaction) 总结你的对话之前，OpenClaw 会运行一个静默回合，提醒智能体将重要上下文保存到 memory 文件中。此功能默认开启——你无需配置任何内容。
在 [compaction](/zh-CN/concepts/compaction) 对你的对话进行摘要之前，OpenClaw 会运行一个静默轮次，提醒智能体将重要上下文保存到内存文件中。此功能默认启用——你无需进行任何配置。
<Tip>
memory 刷新可以防止在 compaction 期间丢失上下文。如果你的智能体在对话中有重要事实尚未写入文件，它们会在摘要发生前自动保存。
内存刷新可以防止在 compaction 期间丢失上下文。如果你的智能体在对话中包含重要事实但尚未写入文件，它们会在摘要发生前自动保存。
</Tip>
## Dreaming（实验性）
## Dreaming
Dreaming 是一项可选的 memory 后台整合流程。它会收集短期信号、对候选项进行评分，并仅将符合条件的内容提升到长期记忆（`MEMORY.md`）中。
Dreaming 是一个可选的后台内存整合流程。它会收集短期信号、为候选项打分，并且只将符合条件的内容提升到长期记忆（`MEMORY.md`）中。
它的设计目标是让长期记忆保持高信噪比：
- **选择启用**：默认禁用。
- **定时执行**：启用后，`memory-core` 会自动管理一个周期性 cron 任务，用于执行完整的 dreaming sweep。
- **阈值筛选**：提升必须通过分数、回忆频率和查询多样性这几道门槛。
- **可审查**：阶段摘要和 diary 条目会写入 `DREAMS.md`，供人工审查。
- **选择启用**：默认关闭。
- **定时执行**：启用后，`memory-core` 会自动管理一个循环 cron 任务，用于执行完整的 Dreaming 扫描。
- **阈值控制**：提升必须通过分数、召回频率和查询多样性门槛。
- **可审查**：阶段摘要和日记条目会写入 `DREAMS.md`，供人工审查。
有关阶段行为、评分信号和 Dream Diary 详情，请参见
[Dreaming（实验性）](/zh-CN/concepts/dreaming)。
[Dreaming](/zh-CN/concepts/dreaming)。
## 有依据的回填与实时提升
## 有据可依的回填与实时提升
dreaming 系统现在有两条紧密相关的审查路径：
Dreaming 系统现在有两条紧密相关的审查路径：
- **实时 dreaming** 会基于 `memory/.dreams/` 下的短期 dreaming 存储运行，这也是常规深度阶段在判断哪些内容可以升级到 `MEMORY.md` 时使用的数据来源。
- **有依据的回填** 会将历史 `memory/YYYY-MM-DD.md` 笔记作为独立的每日文件读取，并将结构化审查输出写入 `DREAMS.md`。
- **实时 Dreaming** 基于 `memory/.dreams/` 下的短期 Dreaming 存储运行，这也是常规深度阶段在决定哪些内容可以进入 `MEMORY.md` 时使用的数据来源。
- **有据可依的回填** 会将历史的 `memory/YYYY-MM-DD.md` 笔记作为独立的每日文件读取，并将结构化审查输出写入 `DREAMS.md`。
当你希望重放较旧的笔记，并检查系统认为哪些内容具有持久价值，而又不想手动编辑 `MEMORY.md` 时，有依据的回填会很有用。
当你希望重放旧笔记，并查看系统认为什么内容具有持久价值，而又不想手动编辑 `MEMORY.md` 时，有据可依的回填会很有用。
当你使用：
@ -127,13 +127,13 @@ dreaming 系统现在有两条紧密相关的审查路径：
openclaw memory rem-backfill --path ./memory --stage-short-term
```
有依据的持久候选项不会被直接提升。它们会被暂存到常规深度阶段已经在使用的同一个短期 dreaming 存储中。这意味着：
这些有据可依的持久候选项不会被直接提升。它们会被暂存到与常规深度阶段相同的短期 Dreaming 存储中。这意味着：
- `DREAMS.md` 仍然是人工审查界面。
- `DREAMS.md` 仍然是供人工审查的界面。
- 短期存储仍然是面向机器的排序界面。
- `MEMORY.md` 仍然只会由深度提升流程写入。
- `MEMORY.md` 仍然只会通过深度提升写入。
如果你认为这次重放没有帮助，可以删除这些暂存产物，而不影响普通 diary 条目或正常的 recall 状态：
如果你决定这次重放没有帮助，你可以移除这些暂存产物，而不影响普通日记条目或常规召回状态：
```bash
openclaw memory rem-backfill --rollback
@ -150,11 +150,11 @@ openclaw memory index --force # 重建索引
## 延伸阅读
- [Builtin Memory Engine](/zh-CN/concepts/memory-builtin) —— 默认 SQLite 后端
- [Builtin Memory Engine](/zh-CN/concepts/memory-builtin) —— 默认的 SQLite 后端
- [QMD Memory Engine](/zh-CN/concepts/memory-qmd) —— 高级 local-first sidecar
- [Honcho Memory](/zh-CN/concepts/memory-honcho) —— AI 原生跨会话 memory
- [Memory Wiki](/zh-CN/plugins/memory-wiki) —— 编译后的知识资料库和 wiki 原生工具
- [Honcho Memory](/zh-CN/concepts/memory-honcho) —— AI 原生跨会话内存
- [Memory Wiki](/zh-CN/plugins/memory-wiki) —— 编译型知识仓库和 wiki 原生工具
- [Memory Search](/zh-CN/concepts/memory-search) —— 搜索流水线、提供商和调优
- [Dreaming（实验性）](/zh-CN/concepts/dreaming) —— 将短期回忆后台提升到长期记忆
- [Dreaming](/zh-CN/concepts/dreaming) —— 将短期召回内容后台提升到长期记忆
- [Memory configuration reference](/zh-CN/reference/memory-config) —— 所有配置项
- [Compaction](/zh-CN/concepts/compaction) —— compaction 如何与 memory 交互
- [Compaction](/zh-CN/concepts/compaction) —— compaction 如何与内存交互

1509
docs/zh-CN/gateway/configuration-reference.md
View File

File diff suppressed because it is too large Load Diff

66
docs/zh-CN/gateway/local-models.md
View File

@ -1,28 +1,28 @@
---
read_when:
- 你想从你自己的 GPU 主机提供模型服务
- 你正在配置 LM Studio 或兼容 OpenAI 的代理
- 你需要最安全的本地模型指导
- 你想从你自己的 GPU 机器提供模型服务
- 你正在连接 LM Studio 或兼容 OpenAI 的代理
- 你需要最安全的本地模型使用指南
summary: 在本地 LLM（LM Studio、vLLM、LiteLLM、自定义 OpenAI 端点）上运行 OpenClaw
title: 本地模型
x-i18n:
generated_at: "2026-04-15T10:43:26Z"
generated_at: "2026-04-15T10:48:14Z"
model: gpt-5.4
provider: openai
source_hash: d9b4939bb67f4fea23de45e88cdf29b887b2992389bc581058361d27bd227dd3
source_hash: 7a506ff83e4c2870d3878339f646c906584454a156ecd618c360f592cf3b0011
source_path: gateway/local-models.md
workflow: 15
---
# 本地模型
本地部署是可行的，但 OpenClaw 需要大上下文窗口，并且要对提示注入有很强的防护。小显存卡会截断上下文，并削弱安全性。尽量把配置拉高：**至少 2 台满配 Mac Studio，或同等级 GPU 设备（约 3 万美元以上）**。单张 **24 GB** GPU 只适合更轻量的提示，并且延迟会更高。使用你能运行的**最大 / 完整尺寸模型变体**；激进量化或“small”检查点会提高提示注入风险（参见[安全](/zh-CN/gateway/security)）。
本地部署是可行的，但 OpenClaw 需要大上下文窗口以及强有力的提示注入防护。小显存显卡会截断上下文，并削弱安全性。目标配置应尽量高：**至少 2 台满配 Mac Studio 或同等级别的 GPU 设备（约 3 万美元以上）**。单张 **24 GB** GPU 仅适用于较轻的提示，并且延迟会更高。尽量使用**你能运行的最大 / 全尺寸模型变体**；激进量化或“小型”检查点会提高提示注入风险（参见 [Security](/zh-CN/gateway/security)）。
如果你想要摩擦最低的本地部署方案，从 [LM Studio](/zh-CN/providers/lmstudio) 或 [Ollama](/zh-CN/providers/ollama) 加 `openclaw onboard` 开始。这一页是面向更高端本地堆栈和自定义兼容 OpenAI 的本地服务器的偏好型指南。
如果你想要摩擦最低的本地配置方式，建议从 [LM Studio](/zh-CN/providers/lmstudio) 或 [Ollama](/zh-CN/providers/ollama) 配合 `openclaw onboard` 开始。本页是面向更高端本地方案以及自定义兼容 OpenAI 的本地服务器的偏好指南。
## 推荐：LM Studio + 大型本地模型（Responses API）
这是目前最好的本地方案。先在 LM Studio 中加载一个大型模型（例如完整尺寸的 Qwen、DeepSeek 或 Llama 构建），启用本地服务器（默认是 `http://127.0.0.1:1234`），然后使用 Responses API，将推理过程与最终文本分离。
这是当前最推荐的本地方案。在 LM Studio 中加载一个大型模型（例如全尺寸的 Qwen、DeepSeek 或 Llama 构建），启用本地服务器（默认是 `http://127.0.0.1:1234`），并使用 Responses API 将推理过程与最终文本分离。
```json5
{
@ -62,15 +62,15 @@ x-i18n:
**设置检查清单**
- 安装 LM Studio：[https://lmstudio.ai](https://lmstudio.ai)
- 在 LM Studio 中，下载**可用的最大模型构建**（避免使用 “small” / 重度量化变体），启动服务器，并确认 `http://127.0.0.1:1234/v1/models` 能列出该模型。
- 用 LM Studio 中显示的实际模型 ID 替换 `my-local-model`。
- 保持模型处于已加载状态；冷加载会增加启动延迟。
- 如果你的 LM Studio 构建不同，调整 `contextWindow` / `maxTokens`。
- 对于 WhatsApp，坚持使用 Responses API，这样只会发送最终文本。
- 在 LM Studio 中，下载**可用的最大模型构建版本**（避免使用 “small”/重度量化变体），启动服务器，并确认 `http://127.0.0.1:1234/v1/models` 能列出该模型。
- 将 `my-local-model` 替换为 LM Studio 中显示的实际模型 ID。
- 保持模型处于已加载状态；冷启动加载会增加启动延迟。
- 如果你的 LM Studio 构建不同，请调整 `contextWindow`/`maxTokens`。
- 对于 WhatsApp，建议坚持使用 Responses API，这样只会发送最终文本。
即使在本地运行，也建议保留托管模型配置；使用 `models.mode: "merge"`，这样回退模型仍然可用。
即使你在运行本地模型，也建议保留托管模型配置；使用 `models.mode: "merge"`，这样回退模型仍然可用。
### 混合配置：托管主模型，本地回退
### 混合配置：托管模型为主，本地模型为回退
```json5
{
@ -111,18 +111,18 @@ x-i18n:
}
```
### 本地优先，托管兜底
### 本地优先，并保留托管安全兜底
交换主模型和回退模型的顺序；保留相同的 provider 配置块和 `models.mode: "merge"`，这样当本地主机不可用时，你仍然可以回退到 Sonnet 或 Opus。
交换 primary 和 fallback 的顺序即可；保留相同的 providers 配置块以及 `models.mode: "merge"`，这样当本地设备不可用时，你仍可回退到 Sonnet 或 Opus。
### 区域托管 / 数据路由
- 托管版的 MiniMax / Kimi / GLM 变体也可通过 OpenRouter 获取，并支持区域固定端点（例如托管在美国）。你可以在那里选择区域变体，以便将流量限制在你指定的司法辖区内，同时继续使用 `models.mode: "merge"`，为 Anthropic / OpenAI 保留回退能力。
- 纯本地仍然是隐私性最强的方案；当你需要提供商功能、但又希望控制数据流向时，区域托管路由是折中方案。
- 托管的 MiniMax/Kimi/GLM 变体也可通过 OpenRouter 使用带区域锁定的端点（例如美国托管）。你可以在那里选择区域版本，在使用 `models.mode: "merge"` 的同时保留 Anthropic/OpenAI 回退模型，并将流量限制在你选择的司法辖区内。
- 纯本地仍然是隐私性最强的路径；如果你需要提供商特性但又想控制数据流向，那么托管的区域路由是中间方案。
## 其他兼容 OpenAI 的本地代理
只要 vLLM、LiteLLM、OAI-proxy 或自定义 Gateway 网关暴露的是兼容 OpenAI 风格的 `/v1` 端点，就可以使用。把上面的 provider 配置块替换成你的端点和模型 ID 即可：
vLLM、LiteLLM、OAI-proxy 或自定义 Gateway 网关 只要暴露兼容 OpenAI 风格的 `/v1` 端点即可使用。将上面的 provider 配置块替换为你的端点和模型 ID：
```json5
{
@ -150,27 +150,27 @@ x-i18n:
}
```
保留 `models.mode: "merge"`，这样托管模型仍然可作为回退使用。
保留 `models.mode: "merge"`，这样托管模型仍可作为回退使用。
关于本地 / 代理 `/v1` 后端的行为说明：
- OpenClaw 会将这些后端视为代理风格的兼容 OpenAI 路由，而不是原生 OpenAI 端点
- 仅适用于原生 OpenAI 的请求整形不会在这里生效：没有 `service_tier`、没有 Responses 的 `store`、没有 OpenAI 推理兼容负载整形，也没有提示缓存提示
- 仅适用于原生 OpenAI 的请求整形不会在这里生效：没有 `service_tier`、没有 Responses `store`、没有 OpenAI reasoning 兼容载荷整形，也没有提示缓存提示
- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）不会注入到这些自定义代理 URL 中
对于更严格的兼容 OpenAI 后端，兼容性说明如下：
针对更严格的兼容 OpenAI 后端的兼容性说明：
- 有些服务器在 Chat Completions 中只接受字符串类型的 `messages[].content`，不接受结构化的 content-part 数组。对于这些端点，请设置 `models.providers.<provider>.models[].compat.requiresStringContent: true`。
- 一些更小或更严格的本地后端，在面对 OpenClaw 完整智能体运行时的提示结构时会不稳定，尤其是在包含工具 schema 时。如果后端能处理很小的直接 `/v1/chat/completions` 调用，但在正常的 OpenClaw 智能体轮次中失败，请先尝试设置 `agents.defaults.experimental.localModelLean: true`，以移除 `browser`、`cron` 和 `message` 这类重量级默认工具；这是实验性标志，不是稳定的默认模式设置。如果这样仍然失败，再尝试 `models.providers.<provider>.models[].compat.supportsTools: false`。
- 如果后端只会在更大的 OpenClaw 运行中失败，剩余问题通常是上游模型 / 服务器容量不足，或后端本身的 bug，而不是 OpenClaw 的传输层问题。
- 某些服务器在 Chat Completions 中只接受字符串类型的 `messages[].content`，而不接受结构化的内容片段数组。对于这些端点，请设置 `models.providers.<provider>.models[].compat.requiresStringContent: true`。
- 某些更小型或更严格的本地后端在面对 OpenClaw 完整的智能体运行时提示结构时会不稳定，尤其是在包含工具 schema 时。如果后端能处理很小的直接 `/v1/chat/completions` 调用，却无法处理正常的 OpenClaw 智能体轮次，请先尝试设置 `agents.defaults.experimental.localModelLean: true`，以移除 `browser`、`cron` 和 `message` 等重量级默认工具；这是实验性标志，不是稳定默认模式设置。参见 [Experimental Features](/zh-CN/concepts/experimental-features)。如果仍然失败，再尝试 `models.providers.<provider>.models[].compat.supportsTools: false`。
- 如果后端仍然只会在较大的 OpenClaw 运行中失败，剩余问题通常是上游模型 / 服务器容量不足，或后端本身存在 bug，而不是 OpenClaw 的传输层问题。
## 故障排除
- Gateway 网关能访问代理吗？`curl http://127.0.0.1:1234/v1/models`
- LM Studio 模型被卸载了？重新加载；冷启动是常见的“卡住”原因。
- 当检测到上下文窗口低于 **32k** 时，OpenClaw 会发出警告；低于 **16k** 时会直接阻止运行。如果你触发了这个预检查，请提高服务器 / 模型的上下文限制，或选择更大的模型。
- 上下文报错？降低 `contextWindow`，或提高服务器限制。
- Gateway 网关 能访问代理吗？`curl http://127.0.0.1:1234/v1/models`
- LM Studio 模型未加载？重新加载；冷启动是常见的“卡住”原因。
- 当检测到的上下文窗口低于 **32k** 时，OpenClaw 会发出警告；低于 **16k** 时会直接阻止运行。如果你遇到这个预检，请提高服务器 / 模型的上下文限制，或选择更大的模型。
- 上下文报错？降低 `contextWindow` 或提高你的服务器限制。
- 兼容 OpenAI 的服务器返回 `messages[].content ... expected a string`？
在该模型条目上添加 `compat.requiresStringContent: true`。
- 很小的直接 `/v1/chat/completions` 调用可以工作，但 `openclaw infer model run` 在 Gemma 或其他本地模型上失败？先用 `compat.supportsTools: false` 禁用工具 schema，然后重新测试。如果服务器仍然只会在更大的 OpenClaw 提示下崩溃，就应将其视为上游服务器 / 模型的限制。
- 安全性：本地模型会跳过提供商侧过滤；保持智能体职责范围尽量收窄，并开启压缩，以限制提示注入的影响半径。
请在该模型项中添加 `compat.requiresStringContent: true`。
- 很小的直接 `/v1/chat/completions` 调用可以工作，但 `openclaw infer model run` 在 Gemma 或其他本地模型上失败？先通过 `compat.supportsTools: false` 禁用工具 schema，然后重新测试。如果服务器仍然只会在较大的 OpenClaw 提示下崩溃，就应将其视为上游服务器 / 模型限制。
- 安全性：本地模型会跳过提供商侧过滤；请保持智能体职责收窄，并开启 compaction，以限制提示注入的影响范围。

340
docs/zh-CN/reference/memory-config.md
View File

@ -1,93 +1,98 @@
---
read_when:
- 你想要配置内存搜索提供商或嵌入模型
- 你想要配置 Memory 搜索提供商或嵌入模型
- 你想要设置 QMD 后端
- 你想要调整混合搜索、MMR 或时间衰减
- 你想要启用多模态内存索引
summary: 内存搜索、嵌入提供商、QMD、混合搜索和多模态索引的所有配置项
title: 内存配置参考
- 你想要调整混合搜索、MMR 或时间衰减参数
- 你想要启用多模态 Memory 索引
summary: Memory 搜索、嵌入提供商、QMD、混合搜索和多模态索引的所有配置项
title: Memory 配置参考
x-i18n:
generated_at: "2026-04-15T09:41:04Z"
generated_at: "2026-04-15T10:48:13Z"
model: gpt-5.4
provider: openai
source_hash: a13f6e982ee47401cc9a71bf2ee6a5305d06158b806a04703bcdcd92e340e4d5
source_hash: 334c3c4dac08e864487047d3822c75f96e9e7a97c38be4b4e0cd9e63c4489a53
source_path: reference/memory-config.md
workflow: 15
---
# 内存配置参考
# Memory 配置参考
本页列出了 OpenClaw 内存搜索的所有配置项。关于概念性概览，请参见：
本页列出了 OpenClaw Memory 搜索的所有配置项。
如需了解概念性概览，请参阅：
- [内存概览](/zh-CN/concepts/memory) —— 内存的工作方式
- [Memory 概览](/zh-CN/concepts/memory) —— Memory 的工作方式
- [内置引擎](/zh-CN/concepts/memory-builtin) —— 默认的 SQLite 后端
- [QMD 引擎](/zh-CN/concepts/memory-qmd) —— 本地优先的 sidecar
- [内存搜索](/zh-CN/concepts/memory-search) —— 搜索流水线与调优
- [主动内存](/zh-CN/concepts/active-memory) —— 为交互式会话启用内存子智能体
- [Memory 搜索](/zh-CN/concepts/memory-search) —— 搜索流水线与调优
- [Active Memory](/zh-CN/concepts/active-memory) —— 为交互式会话启用 Memory 子智能体
除非另有说明，所有内存搜索设置都位于 `openclaw.json` 中的 `agents.defaults.memorySearch` 下。
除非另有说明，所有 Memory 搜索设置都位于 `openclaw.json` 的
`agents.defaults.memorySearch` 下。
如果你在寻找 **主动内存** 功能开关和子智能体配置，它位于 `plugins.entries.active-memory` 下，而不是 `memorySearch`。
如果你要查找的是 **Active Memory** 功能开关和子智能体配置，
它位于 `plugins.entries.active-memory` 下，而不是 `memorySearch`。
主动内存使用双门控模型：
Active Memory 使用双门控模型：
1. 必须启用该插件，并将其目标设为当前智能体 ID
2. 请求必须是符合条件的交互式持久聊天会话
1. 必须启用该插件，并且目标是当前智能体 id
2. 该请求必须是符合条件的交互式持久化聊天会话
有关激活模型、插件自有配置、转录持久化和安全渐进式发布模式，请参见 [主动内存](/zh-CN/concepts/active-memory)。
有关激活模型、插件自有配置、转录持久化和安全发布模式，请参阅
[Active Memory](/zh-CN/concepts/active-memory)。
---
## 提供商选择
| 键 | 类型 | 默认值 | 说明 |
| ---------- | --------- | ---------------- | ------------------------------------------------------------------------------------------ |
| 键名 | 类型 | 默认值 | 描述 |
| ---------- | --------- | ---------------- | ---------------------------------------------------------------------------------------- |
| `provider` | `string` | 自动检测 | 嵌入适配器 ID：`bedrock`、`gemini`、`github-copilot`、`local`、`mistral`、`ollama`、`openai`、`voyage` |
| `model` | `string` | 提供商默认值 | 嵌入模型名称 |
| `fallback` | `string` | `"none"` | 主适配器失败时使用的回退适配器 ID |
| `enabled` | `boolean` | `true` | 启用或禁用内存搜索 |
| `model` | `string` | 提供商默认值 | 嵌入模型名称 |
| `fallback` | `string` | `"none"` | 主提供商失败时使用的后备适配器 ID |
| `enabled` | `boolean` | `true` | 启用或禁用 Memory 搜索 |
### 自动检测顺序
当未设置 `provider` 时，OpenClaw 会选择第一个可用项：
1. `local` —— 如果已配置 `memorySearch.local.modelPath` 且该文件存在。
2. `github-copilot` —— 如果可以解析到 GitHub Copilot 令牌（环境变量或认证配置文件）。
3. `openai` —— 如果可以解析到 OpenAI 密钥。
4. `gemini` —— 如果可以解析到 Gemini 密钥。
5. `voyage` —— 如果可以解析到 Voyage 密钥。
6. `mistral` —— 如果可以解析到 Mistral 密钥。
7. `bedrock` —— 如果 AWS SDK 凭证链可解析（实例角色、访问密钥、配置文件、SSO、Web identity 或共享配置）。
1. `local` —— 如果已配置 `memorySearch.local.modelPath` 且文件存在。
2. `github-copilot` —— 如果可以解析到 GitHub Copilot token（环境变量或认证配置文件）。
3. `openai` —— 如果可以解析到 OpenAI key。
4. `gemini` —— 如果可以解析到 Gemini key。
5. `voyage` —— 如果可以解析到 Voyage key。
6. `mistral` —— 如果可以解析到 Mistral key。
7. `bedrock` —— 如果 AWS SDK 凭证链可解析（实例角色、访问密钥、profile、SSO、web identity 或共享配置）。
支持 `ollama`，但不会自动检测（请显式设置）。
### API 密钥解析
远程嵌入需要 API 密钥。Bedrock 则改用 AWS SDK 默认凭证链（实例角色、SSO、访问密钥）。
远程嵌入需要 API 密钥。Bedrock 则改用 AWS SDK 默认凭证链
（实例角色、SSO、访问密钥）。
| 提供商 | 环境变量 | 配置键 |
| -------------- | -------------------------------------------------- | --------------------------------- |
| Bedrock | AWS 凭证链 | 不需要 API 密钥 |
| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
| GitHub Copilot | `COPILOT_GITHUB_TOKEN`、`GH_TOKEN`、`GITHUB_TOKEN` | 通过设备登录的认证配置文件 |
| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
| Ollama | `OLLAMA_API_KEY`（占位符） | -- |
| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
| 提供商 | 环境变量 | 配置键名 |
| --------------- | -------------------------------------------------- | --------------------------------- |
| Bedrock | AWS 凭证链 | 不需要 API 密钥 |
| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
| GitHub Copilot | `COPILOT_GITHUB_TOKEN`、`GH_TOKEN`、`GITHUB_TOKEN` | 通过设备登录的认证配置文件 |
| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
| Ollama | `OLLAMA_API_KEY`（占位符） | -- |
| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
Codex OAuth 仅适用于聊天/补全，不满足嵌入请求。
Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求。
---
## 远程端点配置
用于自定义 OpenAI 兼容端点或覆盖提供商默认值：
用于自定义兼容 OpenAI 的端点，或覆盖提供商默认值：
| 键 | 类型 | 说明 |
| ---------------- | -------- | ----------------------------------------- |
| `remote.baseUrl` | `string` | 自定义 API 基础 URL |
| `remote.apiKey` | `string` | 覆盖 API 密钥 |
| `remote.headers` | `object` | 额外的 HTTP 标头（与提供商默认值合并） |
| 键名 | 类型 | 描述 |
| ---------------- | -------- | ----------------------------------- |
| `remote.baseUrl` | `string` | 自定义 API 基础 URL |
| `remote.apiKey` | `string` | 覆盖 API 密钥 |
| `remote.headers` | `object` | 额外 HTTP 头（与提供商默认值合并） |
```json5
{
@ -110,21 +115,21 @@ Codex OAuth 仅适用于聊天/补全，不满足嵌入请求。
## Gemini 专用配置
| 键 | 类型 | 默认值 | 说明 |
| ---------------------- | -------- | ---------------------- | ------------------------------------------ |
| `model` | `string` | `gemini-embedding-001` | 也支持 `gemini-embedding-2-preview` |
| `outputDimensionality` | `number` | `3072` | 对于 Embedding 2：768、1536 或 3072 |
| 键名 | 类型 | 默认值 | 描述 |
| ---------------------- | -------- | ---------------------- | ----------------------------------------- |
| `model` | `string` | `gemini-embedding-001` | 也支持 `gemini-embedding-2-preview` |
| `outputDimensionality` | `number` | `3072` | 对于 Embedding 2：可选 768、1536 或 3072 |
<Warning>
更改模型或 `outputDimensionality` 会触发自动全量重新索引。
更改模型或 `outputDimensionality` 会触发自动全量重建索引。
</Warning>
---
## Bedrock 嵌入配置
Bedrock 使用 AWS SDK 默认凭证链 —— 无需 API 密钥。
如果 OpenClaw 运行在具有 Bedrock 权限实例角色的 EC2 上，只需设置
Bedrock 使用 AWS SDK 默认凭证链 —— 不需要 API 密钥。
如果 OpenClaw 运行在带有 Bedrock 权限实例角色的 EC2 上，只需设置
提供商和模型：
```json5
@ -140,14 +145,14 @@ Bedrock 使用 AWS SDK 默认凭证链 —— 无需 API 密钥。
}
```
| 键 | 类型 | 默认值 | 说明 |
| ---------------------- | -------- | ------------------------------ | ----------------------------- |
| `model` | `string` | `amazon.titan-embed-text-v2:0` | 任意 Bedrock 嵌入模型 ID |
| 键名 | 类型 | 默认值 | 描述 |
| ---------------------- | -------- | ------------------------------ | ------------------------ |
| `model` | `string` | `amazon.titan-embed-text-v2:0` | 任意 Bedrock 嵌入模型 ID |
| `outputDimensionality` | `number` | 模型默认值 | 对于 Titan V2：256、512 或 1024 |
### 支持的模型
支持以下模型（包含模型系列检测和维度默认值）：
支持以下模型（包含系列检测和默认维度）：
| 模型 ID | 提供商 | 默认维度 | 可配置维度 |
| ------------------------------------------ | ---------- | -------- | -------------------- |
@ -170,17 +175,17 @@ Bedrock 使用 AWS SDK 默认凭证链 —— 无需 API 密钥。
Bedrock 认证使用标准 AWS SDK 凭证解析顺序：
1. 环境变量（`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`）
2. SSO 令牌缓存
3. Web identity 令牌凭证
4. 共享凭证和配置文件
2. SSO token 缓存
3. Web identity token 凭证
4. 共享凭证与配置文件
5. ECS 或 EC2 元数据凭证
区域会从 `AWS_REGION`、`AWS_DEFAULT_REGION`、`amazon-bedrock`
提供商的 `baseUrl` 中解析，或默认使用 `us-east-1`。
区域会从 `AWS_REGION`、`AWS_DEFAULT_REGION`、
`amazon-bedrock` 提供商的 `baseUrl` 中解析，或默认使用 `us-east-1`。
### IAM 权限
IAM 角色或用户需要：
IAM 角色或用户需要具备：
```json
{
@ -190,7 +195,7 @@ IAM 角色或用户需要：
}
```
为了实现最小权限，请将 `InvokeModel` 限定到特定模型：
若要遵循最小权限原则，请将 `InvokeModel` 限定到特定模型：
```
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
@ -200,13 +205,13 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
## 本地嵌入配置
| 键 | 类型 | 默认值 | 说明 |
| --------------------- | -------- | ---------------------- | ----------------------------- |
| `local.modelPath` | `string` | 自动下载 | GGUF 模型文件路径 |
| `local.modelCacheDir` | `string` | `node-llama-cpp` 默认值 | 已下载模型的缓存目录 |
| 键名 | 类型 | 默认值 | 描述 |
| --------------------- | -------- | ---------------------- | ------------------------ |
| `local.modelPath` | `string` | 自动下载 | GGUF 模型文件路径 |
| `local.modelCacheDir` | `string` | `node-llama-cpp` 默认值 | 已下载模型的缓存目录 |
默认模型：`embeddinggemma-300m-qat-Q8_0.gguf`（约 0.6 GB，自动下载）。
需要原生构建：`pnpm approve-builds`，然后执行 `pnpm rebuild node-llama-cpp`。
需要原生构建：`pnpm approve-builds`，然后运行 `pnpm rebuild node-llama-cpp`。
---
@ -214,28 +219,28 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
全部位于 `memorySearch.query.hybrid` 下：
| 键 | 类型 | 默认值 | 说明 |
| --------------------- | --------- | ------- | --------------------------------- |
| `enabled` | `boolean` | `true` | 启用混合 BM25 + 向量搜索 |
| `vectorWeight` | `number` | `0.7` | 向量分数的权重（0-1） |
| `textWeight` | `number` | `0.3` | BM25 分数的权重（0-1） |
| `candidateMultiplier` | `number` | `4` | 候选池大小乘数 |
| 键名 | 类型 | 默认值 | 描述 |
| --------------------- | --------- | ------- | -------------------------------- |
| `enabled` | `boolean` | `true` | 启用 BM25 + 向量混合搜索 |
| `vectorWeight` | `number` | `0.7` | 向量分数权重（0-1） |
| `textWeight` | `number` | `0.3` | BM25 分数权重（0-1） |
| `candidateMultiplier` | `number` | `4` | 候选池大小倍数 |
### MMR（多样性）
| 键 | 类型 | 默认值 | 说明 |
| ------------- | --------- | ------- | ---------------------------------- |
| `mmr.enabled` | `boolean` | `false` | 启用 MMR 重排 |
| `mmr.lambda` | `number` | `0.7` | 0 = 最大多样性，1 = 最大相关性 |
| 键名 | 类型 | 默认值 | 描述 |
| ------------- | --------- | ------- | ----------------------------------- |
| `mmr.enabled` | `boolean` | `false` | 启用 MMR 重排序 |
| `mmr.lambda` | `number` | `0.7` | 0 = 最大多样性，1 = 最大相关性 |
### 时间衰减（新近度）
### 时间衰减（时效性）
| 键 | 类型 | 默认值 | 说明 |
| ---------------------------- | --------- | ------- | ----------------------- |
| `temporalDecay.enabled` | `boolean` | `false` | 启用新近度加权 |
| `temporalDecay.halfLifeDays` | `number` | `30` | 每 N 天分数减半 |
| 键名 | 类型 | 默认值 | 描述 |
| ---------------------------- | --------- | ------- | ------------------------- |
| `temporalDecay.enabled` | `boolean` | `false` | 启用时效性加权 |
| `temporalDecay.halfLifeDays` | `number` | `30` | 每 N 天分数减半 |
常青文件（`MEMORY.md`、`memory/` 中不带日期的文件）永远不会衰减。
常青文件（`MEMORY.md`、`memory/` 中非日期文件）永不衰减。
### 完整示例
@ -260,11 +265,11 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
---
## 其他内存路径
## 额外 Memory 路径
| 键 | 类型 | 说明 |
| ------------ | ---------- | -------------------------------- |
| `extraPaths` | `string[]` | 要索引的其他目录或文件 |
| 键名 | 类型 | 描述 |
| ------------ | ---------- | ---------------------------- |
| `extraPaths` | `string[]` | 要建立索引的额外目录或文件 |
```json5
{
@ -278,30 +283,30 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
}
```
路径可以是绝对路径，也可以是相对于工作区的路径。目录会被递归扫描，
查找 `.md` 文件。符号链接处理取决于当前使用的后端：
路径可以是绝对路径，也可以是相对于工作区的路径。目录会递归扫描
`.md` 文件。符号链接的处理取决于当前后端：
内置引擎会忽略符号链接，而 QMD 会遵循底层 QMD 扫描器的行为。
对于按智能体作用域的跨智能体转录搜索，请使用
对于按智能体范围进行的跨智能体转录搜索，请使用
`agents.list[].memorySearch.qmd.extraCollections`，而不是 `memory.qmd.paths`。
这些额外集合遵循相同的 `{ path, name, pattern? }` 结构，但会按智能体合并，
并且当路径指向当前工作区之外时，可以保留显式共享名称。
如果同一个解析后路径同时出现在 `memory.qmd.paths` 和
这些额外集合使用相同的 `{ path, name, pattern? }` 结构，但会按智能体合并，
并且当路径指向当前工作区外部时，可以保留显式共享名称。
如果同一个解析后的路径同时出现在 `memory.qmd.paths` 和
`memorySearch.qmd.extraCollections` 中，QMD 会保留第一项并跳过重复项。
---
## 多模态内存（Gemini）
## 多模态 Memory（Gemini）
使用 Gemini Embedding 2 将图像和音频与 Markdown 一起建立索引：
使用 Gemini Embedding 2，为图像和音频与 Markdown 一起建立索引：
| 键 | 类型 | 默认值 | 说明 |
| ------------------------- | ---------- | ---------- | --------------------------------- |
| `multimodal.enabled` | `boolean` | `false` | 启用多模态索引 |
| 键名 | 类型 | 默认值 | 描述 |
| ------------------------- | ---------- | ---------- | ------------------------------------- |
| `multimodal.enabled` | `boolean` | `false` | 启用多模态索引 |
| `multimodal.modalities` | `string[]` | -- | `["image"]`、`["audio"]` 或 `["all"]` |
| `multimodal.maxFileBytes` | `number` | `10000000` | 用于索引的最大文件大小 |
| `multimodal.maxFileBytes` | `number` | `10000000` | 建立索引时允许的最大文件大小 |
仅适用于 `extraPaths` 中的文件。默认内存根目录仍然只支持 Markdown。
仅适用于 `extraPaths` 中的文件。默认 Memory 根路径仍然仅支持 Markdown。
需要 `gemini-embedding-2-preview`。`fallback` 必须为 `"none"`。
支持的格式：`.jpg`、`.jpeg`、`.png`、`.webp`、`.gif`、`.heic`、`.heif`
@ -311,18 +316,18 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
## 嵌入缓存
| 键 | 类型 | 默认值 | 说明 |
| ------------------ | --------- | ------- | ------------------------------ |
| `cache.enabled` | `boolean` | `false` | 在 SQLite 中缓存分块嵌入 |
| `cache.maxEntries` | `number` | `50000` | 最大缓存嵌入条目数 |
| 键名 | 类型 | 默认值 | 描述 |
| ------------------ | --------- | ------- | --------------------------------- |
| `cache.enabled` | `boolean` | `false` | 在 SQLite 中缓存分块嵌入 |
| `cache.maxEntries` | `number` | `50000` | 最大缓存嵌入条目数 |
可防止在重新索引或更新转录时，对未更改的文本重复生成嵌入。
可防止在重建索引或转录更新期间，对未变化的文本重复生成嵌入。
---
## 批量索引
| 键 | 类型 | 默认值 | 说明 |
| 键名 | 类型 | 默认值 | 描述 |
| ----------------------------- | --------- | ------- | -------------------- |
| `remote.batch.enabled` | `boolean` | `false` | 启用批量嵌入 API |
| `remote.batch.concurrency` | `number` | `2` | 并行批处理任务数 |
@ -331,43 +336,43 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
| `remote.batch.timeoutMinutes` | `number` | -- | 批处理超时时间 |
适用于 `openai`、`gemini` 和 `voyage`。对于大规模回填，OpenAI 批处理通常
最快且最便宜。
最快且成本最低。
---
## 会话内存搜索（实验性）
## 会话 Memory 搜索（实验性）
为会话转录建立索引，并通过 `memory_search` 提供结果：
| 键 | 类型 | 默认值 | 说明 |
| 键名 | 类型 | 默认值 | 描述 |
| ----------------------------- | ---------- | ------------ | ------------------------------------- |
| `experimental.sessionMemory` | `boolean` | `false` | 启用会话索引 |
| `sources` | `string[]` | `["memory"]` | 添加 `"sessions"` 以包含转录 |
| `sync.sessions.deltaBytes` | `number` | `100000` | 触发重新索引的字节阈值 |
| `sync.sessions.deltaMessages` | `number` | `50` | 触发重新索引的消息阈值 |
| `sync.sessions.deltaBytes` | `number` | `100000` | 触发重建索引的字节阈值 |
| `sync.sessions.deltaMessages` | `number` | `50` | 触发重建索引的消息阈值 |
会话索引需要显式启用，并且会异步运行。结果可能会略有延迟。
会话索引需要主动启用，并且异步运行。结果可能会有轻微延迟。
会话日志存储在磁盘上，因此请将文件系统访问视为信任边界。
---
## SQLite 向量加速（sqlite-vec）
| 键 | 类型 | 默认值 | 说明 |
| ---------------------------- | --------- | ------- | ------------------------------ |
| `store.vector.enabled` | `boolean` | `true` | 使用 sqlite-vec 执行向量查询 |
| `store.vector.extensionPath` | `string` | 内置 | 覆盖 sqlite-vec 路径 |
| 键名 | 类型 | 默认值 | 描述 |
| ---------------------------- | --------- | ------- | ------------------------------- |
| `store.vector.enabled` | `boolean` | `true` | 对向量查询使用 sqlite-vec |
| `store.vector.extensionPath` | `string` | 内置 | 覆盖 sqlite-vec 路径 |
当 sqlite-vec 不可用时，OpenClaw 会自动回退到进程内余弦相似度。
当 sqlite-vec 不可用时，OpenClaw 会自动回退到进程内余弦相似度计算。
---
## 索引存储
| 键 | 类型 | 默认值 | 说明 |
| --------------------- | -------- | ------------------------------------- | ------------------------------------ |
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | 索引位置（支持 `{agentId}` 标记） |
| `store.fts.tokenizer` | `string` | `unicode61` | FTS5 分词器（`unicode61` 或 `trigram`） |
| 键名 | 类型 | 默认值 | 描述 |
| --------------------- | -------- | ------------------------------------- | ----------------------------------------- |
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | 索引位置（支持 `{agentId}` token） |
| `store.fts.tokenizer` | `string` | `unicode61` | FTS5 分词器（`unicode61` 或 `trigram`） |
---
@ -376,49 +381,50 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
设置 `memory.backend = "qmd"` 以启用。所有 QMD 设置都位于
`memory.qmd` 下：
| 键 | 类型 | 默认值 | 说明 |
| 键名 | 类型 | 默认值 | 描述 |
| ------------------------ | --------- | -------- | -------------------------------------------- |
| `command` | `string` | `qmd` | QMD 可执行文件路径 |
| `searchMode` | `string` | `search` | 搜索命令：`search`、`vsearch`、`query` |
| `includeDefaultMemory` | `boolean` | `true` | 自动索引 `MEMORY.md` + `memory/**/*.md` |
| `includeDefaultMemory` | `boolean` | `true` | 自动为 `MEMORY.md` + `memory/**/*.md` 建立索引 |
| `paths[]` | `array` | -- | 额外路径：`{ name, path, pattern? }` |
| `sessions.enabled` | `boolean` | `false` | 索引会话转录 |
| `sessions.retentionDays` | `number` | -- | 转录保留时长 |
| `sessions.enabled` | `boolean` | `false` | 为会话转录建立索引 |
| `sessions.retentionDays` | `number` | -- | 转录保留期 |
| `sessions.exportDir` | `string` | -- | 导出目录 |
OpenClaw 优先使用当前的 QMD 集合和 MCP 查询结构，但也会通过回退到旧版
`--mask` 集合标志以及更早版本的 MCP 工具名称，在需要时保持对旧版 QMD 的兼容。
OpenClaw 优先使用当前的 QMD collection 和 MCP 查询结构，但也会在需要时
回退到旧版 `--mask` collection 标志和旧版 MCP 工具名称，以保持对旧版 QMD
发布版本的兼容性。
QMD 模型覆盖应保留在 QMD 侧，而不是放在 OpenClaw 配置中。如果你需要
全局覆盖 QMD 的模型，请在 Gateway 网关运行时环境中设置环境变量，例如
QMD 模型覆盖应保留在 QMD 侧，而不是 OpenClaw 配置中。如果你需要全局覆盖
QMD 的模型，请在 Gateway 网关运行环境中设置环境变量，例如
`QMD_EMBED_MODEL`、`QMD_RERANK_MODEL` 和 `QMD_GENERATE_MODEL`。
### 更新计划
| 键 | 类型 | 默认值 | 说明 |
| ------------------------- | --------- | ------- | ---------------------------- |
| `update.interval` | `string` | `5m` | 刷新间隔 |
| `update.debounceMs` | `number` | `15000` | 文件变更防抖时间 |
| `update.onBoot` | `boolean` | `true` | 启动时刷新 |
| `update.waitForBootSync` | `boolean` | `false` | 启动时阻塞直到刷新完成 |
| `update.embedInterval` | `string` | -- | 单独的嵌入执行频率 |
| `update.commandTimeoutMs` | `number` | -- | QMD 命令超时时间 |
| `update.updateTimeoutMs` | `number` | -- | QMD 更新操作超时时间 |
| `update.embedTimeoutMs` | `number` | -- | QMD 嵌入操作超时时间 |
| 键名 | 类型 | 默认值 | 描述 |
| ------------------------- | --------- | ------- | ----------------------------- |
| `update.interval` | `string` | `5m` | 刷新间隔 |
| `update.debounceMs` | `number` | `15000` | 文件变更防抖时间 |
| `update.onBoot` | `boolean` | `true` | 启动时刷新 |
| `update.waitForBootSync` | `boolean` | `false` | 在刷新完成前阻塞启动 |
| `update.embedInterval` | `string` | -- | 单独的嵌入执行周期 |
| `update.commandTimeoutMs` | `number` | -- | QMD 命令超时时间 |
| `update.updateTimeoutMs` | `number` | -- | QMD 更新操作超时时间 |
| `update.embedTimeoutMs` | `number` | -- | QMD 嵌入操作超时时间 |
### 限制
| 键 | 类型 | 默认值 | 说明 |
| ------------------------- | -------- | ------- | ---------------------- |
| `limits.maxResults` | `number` | `6` | 最大搜索结果数 |
| `limits.maxSnippetChars` | `number` | -- | 限制片段长度 |
| `limits.maxInjectedChars` | `number` | -- | 限制注入的总字符数 |
| `limits.timeoutMs` | `number` | `4000` | 搜索超时时间 |
| 键名 | 类型 | 默认值 | 描述 |
| ------------------------- | -------- | ------- | ----------------------- |
| `limits.maxResults` | `number` | `6` | 最大搜索结果数 |
| `limits.maxSnippetChars` | `number` | -- | 限制片段长度 |
| `limits.maxInjectedChars` | `number` | -- | 限制注入的总字符数 |
| `limits.timeoutMs` | `number` | `4000` | 搜索超时时间 |
### 作用域
### 范围
控制哪些会话可以接收 QMD 搜索结果。使用与
[`session.sendPolicy`](/zh-CN/gateway/configuration-reference#session) 相同的结构：
[`session.sendPolicy`](/zh-CN/gateway/configuration-reference#session) 相同的模式：
```json5
{
@ -433,20 +439,20 @@ QMD 模型覆盖应保留在 QMD 侧，而不是放在 OpenClaw 配置中。如
}
```
随附的默认配置允许私信和渠道会话，同时仍然拒绝群组。
内置默认值允许私信和渠道会话，同时仍然拒绝群组会话。
默认仅限私信。`match.keyPrefix` 匹配规范化后的会话键；
默认仅限私信。`match.keyPrefix` 匹配标准化后的会话键；
`match.rawKeyPrefix` 匹配包含 `agent:<id>:` 的原始键。
### 引用
`memory.citations` 适用于所有后端：
| 值 | 行为 |
| ---------------- | ----------------------------------------------- |
| `auto`（默认） | 在片段中包含 `Source: <path#line>` 页脚 |
| `on` | 始终包含页脚 |
| `off` | 省略页脚（路径仍会在内部传递给智能体） |
| 值 | 行为 |
| ---------------- | ------------------------------------------------ |
| `auto`（默认） | 在片段中包含 `Source: <path#line>` 页脚 |
| `on` | 始终包含页脚 |
| `off` | 省略页脚（路径仍会在内部传递给智能体） |
### 完整 QMD 示例
@ -471,22 +477,22 @@ QMD 模型覆盖应保留在 QMD 侧，而不是放在 OpenClaw 配置中。如
---
## Dreaming（实验性）
## Dreaming
Dreaming 配置位于 `plugins.entries.memory-core.config.dreaming` 下，
而不是 `agents.defaults.memorySearch`。
Dreaming 作为一次计划内扫描运行，并将内部的 light/deep/REM 阶段
作为实现细节使用。
Dreaming 作为一次定时扫描运行，并将内部的浅度 / 深度 / REM 阶段
作为实现细节处理。
有关概念行为和斜杠命令，请参见 [Dreaming](/zh-CN/concepts/dreaming)。
如需了解概念行为和斜杠命令，请参阅 [Dreaming](/zh-CN/concepts/dreaming)。
### 用户设置
| 键 | 类型 | 默认值 | 说明 |
| ----------- | --------- | ----------- | ------------------------------------ |
| `enabled` | `boolean` | `false` | 完全启用或禁用 Dreaming |
| `frequency` | `string` | `0 3 * * *` | 完整 Dreaming 扫描的可选 cron 频率 |
| 键名 | 类型 | 默认值 | 描述 |
| ----------- | --------- | ----------- | ---------------------------------- |
| `enabled` | `boolean` | `false` | 完全启用或禁用 Dreaming |
| `frequency` | `string` | `0 3 * * *` | 完整 Dreaming 扫描的可选 cron 周期 |
### 示例
@ -510,5 +516,5 @@ Dreaming 作为一次计划内扫描运行，并将内部的 light/deep/REM 阶
说明：
- Dreaming 会将机器状态写入 `memory/.dreams/`。
- Dreaming 会将人类可读的叙述输出写入 `DREAMS.md`（或现有的 `dreams.md`）。
- light/deep/REM 阶段策略和阈值属于内部行为，不是面向用户的配置。
- Dreaming 会将人类可读的叙述性输出写入 `DREAMS.md`（或已有的 `dreams.md`）。
- 浅度 / 深度 / REM 阶段策略和阈值属于内部行为，不是面向用户的配置。