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-05 23:00:14 +00:00
parent 4a10097e3e
commit 960623aec8
3 changed files with 361 additions and 349 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -2,51 +2,53 @@
read_when:
- 你希望记忆提升能够自动运行
- 你希望了解 Dreaming 的三个阶段
- 你希望调整整合过程，而不污染 MEMORY.md
summary: 具有三个协作阶段的后台记忆整合：轻度、深度和 REM
- 你希望在不污染 MEMORY.md 的情况下调整整合行为
summary: 通过 light、deep 和 REM 三个协同阶段进行后台记忆整合
title: Dreaming（实验性）
x-i18n:
generated_at: "2026-04-05T17:47:08Z"
generated_at: "2026-04-05T22:59:53Z"
model: gpt-5.4
provider: openai
source_hash: a038e6e010af895abde5524727b11be224aa27d630ae1e9bc056e616777d9714
source_hash: e6a82edf0b8630b48f458dacc270b0afc4032d5756baf39e28bf142e53cd8080
source_path: concepts/dreaming.md
workflow: 15
---
# Dreaming（实验性）
Dreaming 是 `memory-core` 中的后台记忆整合系统。它会重新审视对话中出现的内容，并决定哪些内容值得作为持久上下文保留下来。
Dreaming 是 `memory-core` 中的后台记忆整合系统。它会重新查看对话中出现的内容，并决定哪些内容值得保留为持久上下文。
Dreaming 使用三个协作的**阶段**，而不是相互竞争的模式。每个阶段都有明确不同的职责、写入到不同的目标，并按照各自的计划运行。
Dreaming 使用三个协同工作的**阶段**，而不是彼此竞争的模式。每个阶段都有不同的职责、写入不同的目标，并按照自己的计划运行。
## 三个阶段
### Light
Light Dreaming 会整理最近的杂乱内容。它会扫描最近的记忆痕迹，按 Jaccard 相似度去重，对相关条目进行聚类，并将候选记忆暂存到每日记忆笔记中（`memory/YYYY-MM-DD.md`）。
Light Dreaming 会整理最近的杂乱内容。它会扫描最近的记忆轨迹，按 Jaccard 相似度去重，对相关条目进行聚类，并在启用 inline 存储时，将候选记忆暂存到共享的 Dreaming 轨迹文件（`DREAMS.md`）中。
Light **不会**向 `MEMORY.md` 写入任何内容。它只负责组织和暂存。可以理解为：“今天有哪些内容以后可能会重要？”
Light **不会**向 `MEMORY.md` 写入任何内容。它只负责组织和暂存。可以理解为：“今天哪些内容以后可能会重要？”
### Deep
Deep Dreaming 会决定哪些内容会成为持久记忆。它运行真正的提升逻辑：基于六个信号的加权评分、阈值门槛、召回次数、唯一查询多样性、近期衰减，以及最大年龄过滤。
Deep Dreaming 会决定哪些内容会成为持久记忆。它运行真正的提升逻辑：基于六种信号的加权评分、阈值门槛、召回次数、唯一查询多样性、近期性衰减以及最大年龄过滤。
Deep 是**唯一**允许将持久事实写入 `MEMORY.md` 的阶段。它还负责在记忆稀薄时进行恢复（当健康度低于配置阈值时）。可以理解为：“哪些内容足够真实，值得保留？”
Deep 是**唯一**允许将持久事实写入 `MEMORY.md` 的阶段。
它还负责在记忆不足时进行恢复（当健康度低于配置阈值时）。可以理解为：“哪些内容足够真实，值得保留？”
### REM
REM Dreaming 会寻找模式并进行反思。它会检查近期材料，通过概念标签聚类识别重复出现的主题，并将更高层次的笔记和反思写入每日笔记。
REM Dreaming 会寻找模式并进行反思。它检查最近的材料，通过概念标签聚类识别反复出现的主题，并在启用 inline 存储时，将更高层次的笔记和反思写入 `DREAMS.md`。
REM 会写入每日笔记（`memory/YYYY-MM-DD.md`），**不会**写入 `MEMORY.md`。它的输出是解释性的，而不是规范性的。可以理解为：“我注意到了什么模式？”
REM 在 inline 模式下会写入 `DREAMS.md`，**不会**写入 `MEMORY.md`。
它的输出是解释性的，而不是规范性的。可以理解为：“我注意到了什么模式？”
## 硬性边界
## 明确边界
| 阶段 | 职责 | 写入到 | 不会写入到 |
| ----- | --------- | -------------------------- | ----------------- |
| Light | 整理 | 每日笔记（YYYY-MM-DD.md） | MEMORY.md |
| Deep | 保留 | MEMORY.md | -- |
| REM | 解释 | 每日笔记（YYYY-MM-DD.md） | MEMORY.md |
| 阶段 | 职责 | 写入位置 | 不会写入 |
| ----- | -------- | ------------------------- | -------- |
| Light | 整理 | `DREAMS.md`（inline 模式） | MEMORY.md |
| Deep | 保留 | MEMORY.md | -- |
| REM | 解释 | `DREAMS.md`（inline 模式） | MEMORY.md |
## 快速开始
@ -68,7 +70,7 @@ REM 会写入每日笔记（`memory/YYYY-MM-DD.md`），**不会**写入 `MEMORY
}
```
仅启用深度提升：
仅启用 deep 提升：
```json
{
@ -93,113 +95,114 @@ REM 会写入每日笔记（`memory/YYYY-MM-DD.md`），**不会**写入 `MEMORY
## 配置
所有 Dreaming 设置都位于 `openclaw.json` 的 `plugins.entries.memory-core.config.dreaming` 下。完整键名列表请参阅 [记忆配置参考](/zh-CN/reference/memory-config#dreaming-experimental)。
所有 Dreaming 设置都位于 `openclaw.json` 中的 `plugins.entries.memory-core.config.dreaming` 下。
完整键名列表请参见 [记忆配置参考](/zh-CN/reference/memory-config#dreaming-experimental)。
### 全局设置
| 键名 | 类型 | 默认值 | 说明 |
| ---------------- | --------- | ---------- | ------------------------------------------------ |
| `enabled` | `boolean` | `true` | 所有阶段的总开关 |
| `timezone` | `string` | 未设置 | 用于计划评估和每日笔记的时区 |
| `verboseLogging` | `boolean` | `false` | 输出详细的每次 Dreaming 运行日志 |
| `storage.mode` | `string` | `"inline"` | `inline`、`separate` 或 `both` |
| 键名 | 类型 | 默认值 | 说明 |
| ---------------- | --------- | ---------- | ------------------------------------------------------------ |
| `enabled` | `boolean` | `true` | 所有阶段的总开关 |
| `timezone` | `string` | 未设置 | 用于计划评估和 Dreaming 日期分桶的时区 |
| `verboseLogging` | `boolean` | `false` | 输出每次运行的详细 Dreaming 日志 |
| `storage.mode` | `string` | `"inline"` | 使用 inline `DREAMS.md`、独立报告，或两者同时使用 |
### Light 阶段配置
| 键名 | 类型 | 默认值 | 说明 |
| ------------------ | ---------- | ------------------------------- | --------------------------------- |
| `enabled` | `boolean` | `true` | 启用 Light 阶段 |
| `cron` | `string` | `0 */6 * * *` | 计划（默认：每 6 小时一次） |
| `lookbackDays` | `number` | `2` | 要扫描多少天的痕迹 |
| `limit` | `number` | `100` | 每次运行最多暂存的候选项数 |
| `dedupeSimilarity` | `number` | `0.9` | 去重的 Jaccard 阈值 |
| `sources` | `string[]` | `["daily","sessions","recall"]` | 要扫描的数据源 |
| 键名 | 类型 | 默认值 | 说明 |
| ------------------ | ---------- | ------------------------------- | -------------------------- |
| `enabled` | `boolean` | `true` | 启用 Light 阶段 |
| `cron` | `string` | `0 */6 * * *` | 计划（默认：每 6 小时） |
| `lookbackDays` | `number` | `2` | 扫描多少天内的轨迹 |
| `limit` | `number` | `100` | 每次运行最多暂存的候选数 |
| `dedupeSimilarity` | `number` | `0.9` | 去重的 Jaccard 阈值 |
| `sources` | `string[]` | `["daily","sessions","recall"]` | 要扫描的数据源 |
### Deep 阶段配置
| 键名 | 类型 | 默认值 | 说明 |
| 键名 | 类型 | 默认值 | 说明 |
| --------------------- | ---------- | ----------------------------------------------- | ------------------------------------ |
| `enabled` | `boolean` | `true` | 启用 Deep 阶段 |
| `cron` | `string` | `0 3 * * *` | 计划（默认：每天凌晨 3 点） |
| `limit` | `number` | `10` | 每个周期最多提升的候选项数 |
| `minScore` | `number` | `0.8` | 提升所需的最低加权分数 |
| `minRecallCount` | `number` | `3` | 最低召回次数阈值 |
| `minUniqueQueries` | `number` | `3` | 最低不同查询数 |
| `recencyHalfLifeDays` | `number` | `14` | 近期分数减半所需天数 |
| `maxAgeDays` | `number` | `30` | 可提升的每日笔记最大年龄 |
| `sources` | `string[]` | `["daily","memory","sessions","logs","recall"]` | 数据源 |
| `enabled` | `boolean` | `true` | 启用 Deep 阶段 |
| `cron` | `string` | `0 3 * * *` | 计划（默认：每天凌晨 3 点） |
| `limit` | `number` | `10` | 每个周期最多提升的候选数 |
| `minScore` | `number` | `0.8` | 提升所需的最低加权分数 |
| `minRecallCount` | `number` | `3` | 最低召回次数阈值 |
| `minUniqueQueries` | `number` | `3` | 最低不同查询数量 |
| `recencyHalfLifeDays` | `number` | `14` | 近期性分数减半所需的天数 |
| `maxAgeDays` | `number` | `30` | 可提升的每日笔记最大年龄 |
| `sources` | `string[]` | `["daily","memory","sessions","logs","recall"]` | 数据源 |
### Deep 恢复配置
当长期记忆健康度低于某个阈值时，会触发恢复。
| 键名 | 类型 | 默认值 | 说明 |
| --------------------------------- | --------- | ------- | ------------------------------------------ |
| `recovery.enabled` | `boolean` | `true` | 启用自动恢复 |
| `recovery.triggerBelowHealth` | `number` | `0.35` | 触发恢复的健康度阈值 |
| `recovery.lookbackDays` | `number` | `30` | 回溯查找恢复材料的时间范围 |
| `recovery.maxRecoveredCandidates` | `number` | `20` | 每次运行最多恢复的候选项数 |
| `recovery.minRecoveryConfidence` | `number` | `0.9` | 恢复候选项所需的最低置信度 |
| `recovery.autoWriteMinConfidence` | `number` | `0.97` | 自动写入阈值（跳过人工审核） |
| 键名 | 类型 | 默认值 | 说明 |
| --------------------------------- | --------- | ------- | -------------------------------- |
| `recovery.enabled` | `boolean` | `true` | 启用自动恢复 |
| `recovery.triggerBelowHealth` | `number` | `0.35` | 触发恢复的健康度分数阈值 |
| `recovery.lookbackDays` | `number` | `30` | 向前查找恢复材料的范围 |
| `recovery.maxRecoveredCandidates` | `number` | `20` | 每次运行最多恢复的候选数 |
| `recovery.minRecoveryConfidence` | `number` | `0.9` | 恢复候选所需的最低置信度 |
| `recovery.autoWriteMinConfidence` | `number` | `0.97` | 自动写入阈值（跳过人工审查） |
### REM 阶段配置
| 键名 | 类型 | 默认值 | 说明 |
| -------------------- | ---------- | --------------------------- | --------------------------------------- |
| `enabled` | `boolean` | `true` | 启用 REM 阶段 |
| `cron` | `string` | `0 5 * * 0` | 计划（默认：每周日凌晨 5 点） |
| `lookbackDays` | `number` | `7` | 要反思多少天的材料 |
| `limit` | `number` | `10` | 最多写入的模式或主题数 |
| `minPatternStrength` | `number` | `0.75` | 最低标签共现强度 |
| `sources` | `string[]` | `["memory","daily","deep"]` | 用于反思的数据源 |
| 键名 | 类型 | 默认值 | 说明 |
| -------------------- | ---------- | --------------------------- | ------------------------------------ |
| `enabled` | `boolean` | `true` | 启用 REM 阶段 |
| `cron` | `string` | `0 5 * * 0` | 计划（默认：每周日凌晨 5 点） |
| `lookbackDays` | `number` | `7` | 反思多少天内的材料 |
| `limit` | `number` | `10` | 最多写入的模式或主题数量 |
| `minPatternStrength` | `number` | `0.75` | 最低标签共现强度 |
| `sources` | `string[]` | `["memory","daily","deep"]` | 用于反思的数据源 |
### 执行覆盖设置
### 执行覆盖
每个阶段都接受一个 `execution` 块，用于覆盖全局默认值：
每个阶段都支持一个 `execution` 块，用于覆盖全局默认值：
| 键名 | 类型 | 默认值 | 说明 |
| 键名 | 类型 | 默认值 | 说明 |
| ----------------- | -------- | ------------ | ------------------------------ |
| `speed` | `string` | `"balanced"` | `fast`、`balanced` 或 `slow` |
| `thinking` | `string` | `"medium"` | `low`、`medium` 或 `high` |
| `budget` | `string` | `"medium"` | `cheap`、`medium` 或 `expensive` |
| `model` | `string` | 未设置 | 为此阶段覆盖模型 |
| `maxOutputTokens` | `number` | 未设置 | 限制输出 token 数 |
| `temperature` | `number` | 未设置 | 采样温度（0-2） |
| `timeoutMs` | `number` | 未设置 | 阶段超时时间（毫秒） |
| `speed` | `string` | `"balanced"` | `fast`、`balanced` 或 `slow` |
| `thinking` | `string` | `"medium"` | `low`、`medium` 或 `high` |
| `budget` | `string` | `"medium"` | `cheap`、`medium` 或 `expensive` |
| `model` | `string` | 未设置 | 覆盖此阶段使用的模型 |
| `maxOutputTokens` | `number` | 未设置 | 限制输出 token 数 |
| `temperature` | `number` | 未设置 | 采样温度（0-2） |
| `timeoutMs` | `number` | 未设置 | 阶段超时时间（毫秒） |
## 提升信号（Deep 阶段）
Deep Dreaming 会组合六个加权信号。要完成提升，所有已配置的阈值门槛都必须同时通过。
Deep Dreaming 会组合六种加权信号。要完成提升，所有已配置的阈值门槛都必须同时通过。
| 信号 | 权重 | 说明 |
| ------------------- | ------ | -------------------------------------------------- |
| 频率 | 0.24 | 同一条目被召回的频率 |
| 相关性 | 0.30 | 被检索时的平均召回分数 |
| 查询多样性 | 0.15 | 使其浮现出来的不同查询意图数量 |
| 近期性 | 0.15 | 时间衰减（`recencyHalfLifeDays`，默认 14） |
| 整合度 | 0.10 | 奖励跨多天重复出现的召回 |
| 概念丰富度 | 0.06 | 奖励具有更丰富派生概念标签的条目 |
| 信号 | 权重 | 说明 |
| ------------------ | ---- | -------------------------------------------------- |
| 频率 | 0.24 | 同一条目被召回的频率 |
| 相关性 | 0.30 | 被检索到时的平均召回分数 |
| 查询多样性 | 0.15 | 使其浮现出来的不同查询意图数量 |
| 近期性 | 0.15 | 时间衰减（`recencyHalfLifeDays`，默认 14） |
| 整合度 | 0.10 | 奖励跨多天重复出现的召回 |
| 概念丰富度 | 0.06 | 奖励派生概念标签更丰富的条目 |
## 聊天命令
```
/dreaming status # 显示阶段配置和运行频率
/dreaming status # 显示阶段配置和执行频率
/dreaming on # 启用所有阶段
/dreaming off # 禁用所有阶段
/dreaming enable light|deep|rem # 启用特定阶段
/dreaming disable light|deep|rem # 禁用特定阶段
/dreaming help # 显示用法指南
/dreaming help # 显示使用指南
```
## CLI 命令
从命令行预览并应用深度提升：
从命令行预览并应用 deep 提升：
```bash
# 预览提升候选项
# 预览提升候选
openclaw memory promote
# 将提升内容应用到 MEMORY.md
# 将提升结果应用到 MEMORY.md
openclaw memory promote --apply
# 限制预览数量
@ -212,57 +215,58 @@ openclaw memory promote --include-promoted
openclaw memory status --deep
```
完整 flag 参考请参阅 [memory CLI](/cli/memory)。
完整 flag 参考请参见 [memory CLI](/cli/memory)。
## 工作原理
### Light 阶段流水线
### Light 阶段流程
1. 从 `memory/.dreams/short-term-recall.json` 读取短期召回条目。
2. 过滤出位于当前时间 `lookbackDays` 范围内的条目。
2. 过滤出在当前时间 `lookbackDays` 范围内的条目。
3. 按 Jaccard 相似度去重（阈值可配置）。
4. 按平均召回分数排序，最多取 `limit` 个条目。
5. 将暂存候选项写入每日笔记中的 `## Light Sleep` 区块。
4. 按平均召回分数排序，最多取 `limit` 条目。
5. 在启用 inline 存储时，将暂存候选写入 `DREAMS.md` 的 `## Light Sleep` 区块下。
### Deep 阶段流水线
### Deep 阶段流程
1. 使用加权信号读取并排序短期召回候选项。
1. 使用加权信号读取并排序短期召回候选。
2. 应用阈值门槛：`minScore`、`minRecallCount`、`minUniqueQueries`。
3. 按 `maxAgeDays` 过滤，并应用近期衰减。
4. 在已配置的记忆工作区之间展开处理。
3. 按 `maxAgeDays` 过滤，并应用近期性衰减。
4. 扩展到所有已配置的记忆工作区。
5. 写入前重新读取实时每日笔记（跳过过期或已删除的片段）。
6. 将符合条件的条目追加到 `MEMORY.md`，并附带提升时间戳。
7. 标记已提升条目，以便将来周期中排除它们。
6. 将符合条件的条目连同提升时间戳追加到 `MEMORY.md`。
7. 标记已提升条目，以便在后续周期中将其排除。
8. 如果健康度低于 `recovery.triggerBelowHealth`，则运行恢复流程。
### REM 阶段流水线
### REM 阶段流程
1. 读取 `lookbackDays` 范围内最近的记忆痕迹。
1. 读取 `lookbackDays` 范围内的近期记忆轨迹。
2. 按共现关系对概念标签进行聚类。
3. 按 `minPatternStrength` 过滤模式。
4. 将主题和反思写入每日笔记中的 `## REM Sleep` 区块。
4. 在启用 inline 存储时，将主题和反思写入 `DREAMS.md` 的 `## REM Sleep` 区块下。
## 调度
每个阶段都会自动管理自己的 cron 作业。启用 Dreaming 后，`memory-core` 会在 Gateway 网关启动时协调受管 cron 作业。你不需要手动创建 cron 条目。
每个阶段都会自动管理自己的 cron 任务。启用 Dreaming 后，
`memory-core` 会在 Gateway 网关启动时协调受管的 cron 任务。你无需手动创建 cron 条目。
| 阶段 | 默认计划 | 说明 |
| ----- | ---------------- | ------------------- |
| Light | `0 */6 * * *` | 每 6 小时一次 |
| Deep | `0 3 * * *` | 每天凌晨 3 点 |
| REM | `0 5 * * 0` | 每周日凌晨 5 点 |
| 阶段 | 默认计划 | 说明 |
| ----- | ---------------- | ----------------- |
| Light | `0 */6 * * *` | 每 6 小时一次 |
| Deep | `0 3 * * *` | 每天凌晨 3 点 |
| REM | `0 5 * * 0` | 每周日凌晨 5 点 |
你可以使用阶段的 `cron` 键覆盖任何计划。所有计划都会遵循全局 `timezone` 设置。
你可以使用阶段的 `cron` 键覆盖任意计划。所有计划都会遵循全局 `timezone` 设置。
## Dreams UI
启用 Dreaming 后，Gateway 网关侧边栏会显示一个 **Dreams** 标签页，其中包含记忆统计信息（短期数量、长期数量、已提升数量）以及下一次计划周期时间。每日计数在设置了 `dreaming.timezone` 时会遵循该配置，否则回退到已配置的用户时区。
启用 Dreaming 后，Gateway 网关侧边栏会显示一个 **Dreams** 标签页，其中包含记忆统计信息（短期数量、长期数量、已提升数量）以及下一次计划周期时间。每日计数在设置了 `dreaming.timezone` 时会遵循该时区，否则回退到已配置的用户时区。
手动运行 `openclaw memory promote` 默认使用相同的 Deep 阶段阈值，因此除非你传递 CLI 覆盖参数，否则计划运行与按需提升会保持一致。
手动运行 `openclaw memory promote` 时，默认会使用与 Deep 阶段相同的阈值，因此除非你传入 CLI 覆盖项，否则计划提升与按需提升会保持一致。
## 相关内容
- [Memory](/zh-CN/concepts/memory)
- [Memory Search](/zh-CN/concepts/memory-search)
- [记忆](/zh-CN/concepts/memory)
- [记忆搜索](/zh-CN/concepts/memory-search)
- [记忆配置参考](/zh-CN/reference/memory-config)
- [memory CLI](/cli/memory)

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

@ -1,80 +1,80 @@
---
read_when:
- 你想配置记忆搜索提供商或 embedding 模型
- 你想配置内存搜索提供商或嵌入模型
- 你想设置 QMD 后端
- 你想调优混合搜索、MMR 或时间衰减
- 你想启用多模态记忆索引
summary: 记忆搜索、embedding 提供商、QMD、混合搜索和多模态索引的所有配置项
title: 记忆配置参考
- 你想启用多模态内存索引
summary: 内存搜索、嵌入提供商、QMD、混合搜索和多模态索引的所有配置项
title: 内存配置参考
x-i18n:
generated_at: "2026-04-05T17:49:47Z"
generated_at: "2026-04-05T23:00:14Z"
model: gpt-5.4
provider: openai
source_hash: 40ad19f65d8c688c9a4ce3275befe9455ed40073e0df0cee2f7f3fc4c0c363c4
source_hash: 24dcdca7e2c29f27e61b0ed076574d6b473832f839cba2cc0c0d57e2ac17c196
source_path: reference/memory-config.md
workflow: 15
---
# 记忆配置参考
# 内存配置参考
本页列出了 OpenClaw 记忆搜索的每一个配置项。有关概念性概览，请参见：
本页列出了 OpenClaw 内存搜索的每一个配置项。有关概念概览，请参见：
- [记忆概览](/zh-CN/concepts/memory) -- 记忆的工作方式
- [内存概览](/zh-CN/concepts/memory) -- 内存的工作方式
- [内置引擎](/zh-CN/concepts/memory-builtin) -- 默认的 SQLite 后端
- [QMD 引擎](/zh-CN/concepts/memory-qmd) -- 本地优先的 sidecar
- [记忆搜索](/zh-CN/concepts/memory-search) -- 搜索流水线和调优
- [内存搜索](/zh-CN/concepts/memory-search) -- 搜索流水线和调优
除非另有说明，所有记忆搜索设置都位于 `openclaw.json` 的
除非另有说明，所有内存搜索设置都位于 `openclaw.json` 中的
`agents.defaults.memorySearch` 下。
---
## 提供商选择
| 键名 | 类型 | 默认值 | 说明 |
| ---------- | --------- | -------------- | ------------------------------------------------------------------------ |
| `provider` | `string` | 自动检测 | Embedding 适配器 ID：`openai`、`gemini`、`voyage`、`mistral`、`ollama`、`local` |
| `model` | `string` | 提供商默认值 | Embedding 模型名称 |
| `fallback` | `string` | `"none"` | 主适配器失败时使用的回退适配器 ID |
| `enabled` | `boolean` | `true` | 启用或禁用记忆搜索 |
| Key | Type | Default | Description |
| ---------- | --------- | ---------------- | -------------------------------------------------------------------------------- |
| `provider` | `string` | 自动检测 | 嵌入适配器 ID：`openai`、`gemini`、`voyage`、`mistral`、`ollama`、`local` |
| `model` | `string` | 提供商默认值 | 嵌入模型名称 |
| `fallback` | `string` | `"none"` | 当主适配器失败时使用的回退适配器 ID |
| `enabled` | `boolean` | `true` | 启用或禁用内存搜索 |
### 自动检测顺序
当未设置 `provider` 时，OpenClaw 会选择第一个可用项：
1. `local` -- 如果配置了 `memorySearch.local.modelPath` 且文件存在。
2. `openai` -- 如果可以解析出 OpenAI 密钥。
3. `gemini` -- 如果可以解析出 Gemini 密钥。
4. `voyage` -- 如果可以解析出 Voyage 密钥。
5. `mistral` -- 如果可以解析出 Mistral 密钥。
1. `local` -- 如果已配置 `memorySearch.local.modelPath` 且文件存在。
2. `openai` -- 如果可以解析到 OpenAI 密钥。
3. `gemini` -- 如果可以解析到 Gemini 密钥。
4. `voyage` -- 如果可以解析到 Voyage 密钥。
5. `mistral` -- 如果可以解析到 Mistral 密钥。
支持 `ollama`，但不会自动检测（请显式设置）。
### API 密钥解析
远程 embedding 需要 API 密钥。OpenClaw 会从以下来源解析：
auth profiles、`models.providers.*.apiKey` 或环境变量。
远程嵌入需要 API 密钥。OpenClaw 会从以下位置解析：
auth 配置文件、`models.providers.*.apiKey` 或环境变量。
| 提供商 | 环境变量 | 配置键名 |
| ------ | ---------------------------- | --------------------------------- |
| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
| Ollama | `OLLAMA_API_KEY`（占位符） | -- |
| Provider | Env var | Config key |
| -------- | ------------------------------ | --------------------------------- |
| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
| Ollama | `OLLAMA_API_KEY` （占位符） | -- |
Codex OAuth 仅覆盖聊天/completions，不满足 embedding 请求。
Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求。
---
## 远程端点配置
用于自定义 OpenAI 兼容端点或覆盖提供商默认值：
用于自定义兼容 OpenAI 的端点或覆盖提供商默认值：
| 键名 | 类型 | 说明 |
| ---------------- | -------- | --------------------------------- |
| `remote.baseUrl` | `string` | 自定义 API 基础 URL |
| `remote.apiKey` | `string` | 覆盖 API 密钥 |
| Key | Type | Description |
| ---------------- | -------- | -------------------------------------------------- |
| `remote.baseUrl` | `string` | 自定义 API 基础 URL |
| `remote.apiKey` | `string` | 覆盖 API 密钥 |
| `remote.headers` | `object` | 额外的 HTTP 标头（与提供商默认值合并） |
```json5
@ -96,28 +96,28 @@ Codex OAuth 仅覆盖聊天/completions，不满足 embedding 请求。
---
## Gemini 专属配置
## Gemini 专用配置
| 键名 | 类型 | 默认值 | 说明 |
| Key | Type | Default | Description |
| ---------------------- | -------- | ---------------------- | ------------------------------------------ |
| `model` | `string` | `gemini-embedding-001` | 也支持 `gemini-embedding-2-preview` |
| `model` | `string` | `gemini-embedding-001` | 也支持 `gemini-embedding-2-preview` |
| `outputDimensionality` | `number` | `3072` | 对于 Embedding 2：768、1536 或 3072 |
<Warning>
更改模型或 `outputDimensionality` 会触发自动全量重建索引。
更改模型或 `outputDimensionality` 会触发自动完整重建索引。
</Warning>
---
## 本地 embedding 配置
## 本地嵌入配置
| 键名 | 类型 | 默认值 | 说明 |
| --------------------- | -------- | ---------------------- | ---------------------------- |
| `local.modelPath` | `string` | 自动下载 | GGUF 模型文件路径 |
| `local.modelCacheDir` | `string` | node-llama-cpp 默认值 | 已下载模型的缓存目录 |
| Key | Type | Default | Description |
| --------------------- | -------- | ---------------------- | ------------------------------- |
| `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`。
---
@ -125,28 +125,28 @@ Codex OAuth 仅覆盖聊天/completions，不满足 embedding 请求。
全部位于 `memorySearch.query.hybrid` 下：
| 键名 | 类型 | 默认值 | 说明 |
| --------------------- | --------- | ------- | ------------------------------ |
| `enabled` | `boolean` | `true` | 启用混合 BM25 + 向量搜索 |
| `vectorWeight` | `number` | `0.7` | 向量分数权重（0-1） |
| `textWeight` | `number` | `0.3` | BM25 分数权重（0-1） |
| `candidateMultiplier` | `number` | `4` | 候选池大小倍数 |
| Key | Type | Default | Description |
| --------------------- | --------- | ------- | ---------------------------------- |
| `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 = 最大相关性 |
| Key | Type | Default | Description |
| ------------- | --------- | ------- | ------------------------------------ |
| `mmr.enabled` | `boolean` | `false` | 启用 MMR 重排序 |
| `mmr.lambda` | `number` | `0.7` | 0 = 最大多样性，1 = 最大相关性 |
### 时间衰减（新近性）
| 键名 | 类型 | 默认值 | 说明 |
| ---------------------------- | --------- | ------- | ------------------------ |
| `temporalDecay.enabled` | `boolean` | `false` | 启用新近性加权 |
| `temporalDecay.halfLifeDays` | `number` | `30` | 分数每 N 天减半 |
| Key | Type | Default | Description |
| ---------------------------- | --------- | ------- | ------------------------- |
| `temporalDecay.enabled` | `boolean` | `false` | 启用新近性提升 |
| `temporalDecay.halfLifeDays` | `number` | `30` | 每隔 N 天分数减半 |
常青文件（`MEMORY.md`、`memory/` 中未带日期的文件）永不衰减。
常青文件（`MEMORY.md`、`memory/` 中无日期的文件）永远不会衰减。
### 完整示例
@ -171,11 +171,11 @@ Codex OAuth 仅覆盖聊天/completions，不满足 embedding 请求。
---
## 额外记忆路径
## 额外内存路径
| 键名 | 类型 | 说明 |
| ------------ | ---------- | ------------------------------ |
| `extraPaths` | `string[]` | 要索引的额外目录或文件 |
| Key | Type | Description |
| ------------ | ---------- | ---------------------------------------- |
| `extraPaths` | `string[]` | 要索引的额外目录或文件 |
```json5
{
@ -190,94 +190,100 @@ Codex OAuth 仅覆盖聊天/completions，不满足 embedding 请求。
```
路径可以是绝对路径，也可以是相对于工作区的路径。目录会递归扫描
`.md` 文件。符号链接处理取决于当前后端：
内置引擎会忽略符号链接，而 QMD 会遵循底层 QMD 扫描器的行为。
`.md` 文件。符号链接的处理取决于当前后端：
内置引擎会忽略符号链接，而 QMD 会遵循底层 QMD
扫描器的行为。
对于按智能体范围的跨智能体 transcript 搜索，请使用
对于按智能体范围进行的跨智能体转录搜索，请使用
`agents.list[].memorySearch.qmd.extraCollections`，而不是 `memory.qmd.paths`。
这些额外集合遵循相同的 `{ path, name, pattern? }` 结构，但会按智能体合并，并且当路径指向当前工作区之外时，可以保留显式共享名称。
这些额外集合遵循相同的 `{ path, name, pattern? }` 结构，但
它们会按智能体合并，并且当路径指向当前工作区之外时，
可以保留显式共享名称。
如果同一个解析后的路径同时出现在 `memory.qmd.paths` 和
`memorySearch.qmd.extraCollections` 中，QMD 会保留第一个条目并跳过重复项。
`memorySearch.qmd.extraCollections` 中，QMD 会保留第一个条目并跳过
重复项。
---
## 多模态记忆（Gemini）
## 多模态内存（Gemini）
使用 Gemini Embedding 2，在 Markdown 之外同时索引图像和音频：
使用 Gemini Embedding 2 将图片和音频与 Markdown 一起编入索引：
| 键名 | 类型 | 默认值 | 说明 |
| ------------------------- | ---------- | ---------- | ------------------------------------ |
| `multimodal.enabled` | `boolean` | `false` | 启用多模态索引 |
| Key | Type | Default | Description |
| ------------------------- | ---------- | ---------- | -------------------------------------- |
| `multimodal.enabled` | `boolean` | `false` | 启用多模态索引 |
| `multimodal.modalities` | `string[]` | -- | `["image"]`、`["audio"]` 或 `["all"]` |
| `multimodal.maxFileBytes` | `number` | `10000000` | 可索引的最大文件大小 |
| `multimodal.maxFileBytes` | `number` | `10000000` | 用于索引的最大文件大小 |
仅适用于 `extraPaths` 中的文件。默认记忆根目录仍然只支持 Markdown。
仅适用于 `extraPaths` 中的文件。默认内存根目录仍仅支持 Markdown。
需要 `gemini-embedding-2-preview`。`fallback` 必须为 `"none"`。
支持的格式：`.jpg`、`.jpeg`、`.png`、`.webp`、`.gif`、`.heic`、`.heif`
（图像）；`.mp3`、`.wav`、`.ogg`、`.opus`、`.m4a`、`.aac`、`.flac`（音频）。
（图片）；`.mp3`、`.wav`、`.ogg`、`.opus`、`.m4a`、`.aac`、`.flac`（音频）。
---
## Embedding 缓存
## 嵌入缓存
| 键名 | 类型 | 默认值 | 说明 |
| Key | Type | Default | Description |
| ------------------ | --------- | ------- | -------------------------------- |
| `cache.enabled` | `boolean` | `false` | 在 SQLite 中缓存分块 embedding |
| `cache.maxEntries` | `number` | `50000` | 最大缓存 embedding 数量 |
| `cache.enabled` | `boolean` | `false` | 在 SQLite 中缓存分块嵌入 |
| `cache.maxEntries` | `number` | `50000` | 最大缓存嵌入数量 |
防止在重建索引或 transcript 更新期间，对未变化的文本重复做 embedding。
可防止在重建索引或转录更新期间对未更改文本重复生成嵌入。
---
## 批量索引
| 键名 | 类型 | 默认值 | 说明 |
| ----------------------------- | --------- | ------- | ---------------------- |
| `remote.batch.enabled` | `boolean` | `false` | 启用批量 embedding API |
| `remote.batch.concurrency` | `number` | `2` | 并行批任务数 |
| `remote.batch.wait` | `boolean` | `true` | 等待批处理完成 |
| `remote.batch.pollIntervalMs` | `number` | -- | 轮询间隔 |
| `remote.batch.timeoutMinutes` | `number` | -- | 批处理超时时间 |
| Key | Type | Default | Description |
| ----------------------------- | --------- | ------- | -------------------------- |
| `remote.batch.enabled` | `boolean` | `false` | 启用批量嵌入 API |
| `remote.batch.concurrency` | `number` | `2` | 并行批处理作业 |
| `remote.batch.wait` | `boolean` | `true` | 等待批处理完成 |
| `remote.batch.pollIntervalMs` | `number` | -- | 轮询间隔 |
| `remote.batch.timeoutMinutes` | `number` | -- | 批处理超时时间 |
适用于 `openai`、`gemini` 和 `voyage`。对于大型回填任务，OpenAI 批处理通常
最快且最便宜。
适用于 `openai`、`gemini` 和 `voyage`。OpenAI 批处理通常
在大规模回填时最快且最便宜。
---
## 会话记忆搜索（实验性）
## 会话内存搜索（实验性）
对会话 transcript 建立索引，并通过 `memory_search` 暴露：
为会话转录建立索引，并通过 `memory_search` 暴露：
| 键名 | 类型 | 默认值 | 说明 |
| ----------------------------- | ---------- | ------------ | ------------------------------------- |
| `experimental.sessionMemory` | `boolean` | `false` | 启用会话索引 |
| `sources` | `string[]` | `["memory"]` | 添加 `"sessions"` 以包含 transcript |
| `sync.sessions.deltaBytes` | `number` | `100000` | 触发重建索引的字节阈值 |
| `sync.sessions.deltaMessages` | `number` | `50` | 触发重建索引的消息阈值 |
| Key | Type | Default | Description |
| ----------------------------- | ---------- | ------------ | --------------------------------------- |
| `experimental.sessionMemory` | `boolean` | `false` | 启用会话索引 |
| `sources` | `string[]` | `["memory"]` | 添加 `"sessions"` 以包含转录 |
| `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 路径 |
| Key | Type | Default | Description |
| ---------------------------- | --------- | ------- | --------------------------------- |
| `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}` token） |
| `store.fts.tokenizer` | `string` | `unicode61` | FTS5 tokenizer（`unicode61` 或 `trigram`） |
| Key | Type | Default | Description |
| --------------------- | -------- | ------------------------------------- | ------------------------------------------- |
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | 索引位置（支持 `{agentId}` 令牌） |
| `store.fts.tokenizer` | `string` | `unicode61` | FTS5 分词器（`unicode61` 或 `trigram`） |
---
@ -286,41 +292,41 @@ Codex OAuth 仅覆盖聊天/completions，不满足 embedding 请求。
设置 `memory.backend = "qmd"` 以启用。所有 QMD 设置都位于
`memory.qmd` 下：
| 键名 | 类型 | 默认值 | 说明 |
| Key | Type | Default | Description |
| ------------------------ | --------- | -------- | -------------------------------------------- |
| `command` | `string` | `qmd` | QMD 可执行文件路径 |
| `searchMode` | `string` | `search` | 搜索命令：`search`、`vsearch`、`query` |
| `includeDefaultMemory` | `boolean` | `true` | 自动索引 `MEMORY.md` + `memory/**/*.md` |
| `paths[]` | `array` | -- | 额外路径：`{ name, path, pattern? }` |
| `sessions.enabled` | `boolean` | `false` | 索引会话 transcript |
| `sessions.retentionDays` | `number` | -- | Transcript 保留天数 |
| `sessions.exportDir` | `string` | -- | 导出目录 |
| `command` | `string` | `qmd` | QMD 可执行文件路径 |
| `searchMode` | `string` | `search` | 搜索命令：`search`、`vsearch`、`query` |
| `includeDefaultMemory` | `boolean` | `true` | 自动索引 `MEMORY.md` + `memory/**/*.md` |
| `paths[]` | `array` | -- | 额外路径：`{ name, path, pattern? }` |
| `sessions.enabled` | `boolean` | `false` | 索引会话转录 |
| `sessions.retentionDays` | `number` | -- | 转录保留期 |
| `sessions.exportDir` | `string` | -- | 导出目录 |
### 更新计划
| 键名 | 类型 | 默认值 | 说明 |
| ------------------------- | --------- | -------- | ------------------------------ |
| `update.interval` | `string` | `5m` | 刷新间隔 |
| `update.debounceMs` | `number` | `15000` | 文件变更防抖 |
| `update.onBoot` | `boolean` | `true` | 启动时刷新 |
| `update.waitForBootSync` | `boolean` | `false` | 阻塞启动直到刷新完成 |
| `update.embedInterval` | `string` | -- | 单独的 embedding 节奏 |
| `update.commandTimeoutMs` | `number` | -- | QMD 命令超时时间 |
| `update.updateTimeoutMs` | `number` | -- | QMD 更新操作超时时间 |
| `update.embedTimeoutMs` | `number` | -- | QMD embedding 操作超时时间 |
| Key | Type | Default | Description |
| ------------------------- | --------- | ------- | ------------------------------------- |
| `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` | -- | 限制总注入字符数 |
| Key | Type | Default | Description |
| ------------------------- | -------- | ------- | -------------------------- |
| `limits.maxResults` | `number` | `6` | 最大搜索结果数 |
| `limits.maxSnippetChars` | `number` | -- | 限制摘要长度 |
| `limits.maxInjectedChars` | `number` | -- | 限制注入的总字符数 |
| `limits.timeoutMs` | `number` | `4000` | 搜索超时时间 |
### 范围
控制哪些会话可以接收 QMD 搜索结果。Schema 与
控制哪些会话可以接收 QMD 搜索结果。结构与
[`session.sendPolicy`](/zh-CN/gateway/configuration-reference#session) 相同：
```json5
@ -343,11 +349,11 @@ Codex OAuth 仅覆盖聊天/completions，不满足 embedding 请求。
`memory.citations` 适用于所有后端：
| 值 | 行为 |
| ---------------- | ---------------------------------------------- |
| `auto`（默认） | 在片段中包含 `Source: <path#line>` 页脚 |
| `on` | 始终包含页脚 |
| `off` | 省略页脚（路径仍会在内部传递给智能体） |
| Value | Behavior |
| ---------------- | --------------------------------------------------- |
| `auto` （默认） | 在摘要中包含 `Source: <path#line>` 页脚 |
| `on` | 始终包含页脚 |
| `off` | 省略页脚（路径仍会在内部传递给智能体） |
### 完整 QMD 示例
@ -375,88 +381,90 @@ Codex OAuth 仅覆盖聊天/completions，不满足 embedding 请求。
## Dreaming（实验性）
Dreaming 配置位于 `plugins.entries.memory-core.config.dreaming` 下，
而不是 `agents.defaults.memorySearch` 下。Dreaming 使用三个协作阶段
（light、deep、REM），每个阶段都有自己的计划和配置。有关概念细节和聊天命令，请参阅 [Dreaming](/concepts/dreaming)。
而不是 `agents.defaults.memorySearch`。Dreaming 使用三个协同
阶段（light、deep、REM），每个阶段都有自己的计划和配置。有关
概念细节和聊天命令，请参见 [Dreaming](/zh-CN/concepts/dreaming)。
### 全局设置
| 键名 | 类型 | 默认值 | 说明 |
| ------------------------- | --------- | ------------ | -------------------------------------------- |
| `enabled` | `boolean` | `true` | 所有阶段的总开关 |
| `timezone` | `string` | 未设置 | 用于计划评估和每日笔记的时区 |
| `verboseLogging` | `boolean` | `false` | 输出详细的每次运行 Dreaming 日志 |
| `storage.mode` | `string` | `"inline"` | `inline`、`separate` 或 `both` |
| `storage.separateReports` | `boolean` | `false` | 为每个阶段写入单独的报告文件 |
| Key | Type | Default | Description |
| ------------------------- | --------- | ---------- | ------------------------------------------------------------ |
| `enabled` | `boolean` | `true` | 所有阶段的总开关 |
| `timezone` | `string` | 未设置 | 用于计划评估和 Dreaming 日期分桶的时区 |
| `verboseLogging` | `boolean` | `false` | 输出详细的逐次运行 Dreaming 日志 |
| `storage.mode` | `string` | `"inline"` | 内联 `DREAMS.md`、单独报告或两者都写入 |
| `storage.separateReports` | `boolean` | `false` | 为每个阶段写入单独的报告文件 |
### Light 阶段（`phases.light`）
扫描最近的 traces、去重，并将候选内容暂存到每日笔记中。
扫描最近的轨迹、去重，并在启用内联存储时将候选项暂存到 `DREAMS.md` 中。
**不会**写入 `MEMORY.md`。
| 键名 | 类型 | 默认值 | 说明 |
| ------------------ | ---------- | ------------------------------- | ------------------------- |
| `enabled` | `boolean` | `true` | 启用 light 阶段 |
| `cron` | `string` | `0 */6 * * *` | 计划（每 6 小时一次） |
| `lookbackDays` | `number` | `2` | 要扫描的 trace 天数 |
| `limit` | `number` | `100` | 最大暂存候选数 |
| `dedupeSimilarity` | `number` | `0.9` | 去重的 Jaccard 阈值 |
| `sources` | `string[]` | `["daily","sessions","recall"]` | 数据源 |
| Key | Type | Default | Description |
| ------------------ | ---------- | ------------------------------- | --------------------------- |
| `enabled` | `boolean` | `true` | 启用 light 阶段 |
| `cron` | `string` | `0 */6 * * *` | 计划（每 6 小时一次） |
| `lookbackDays` | `number` | `2` | 要扫描的轨迹天数 |
| `limit` | `number` | `100` | 要暂存的最大候选数 |
| `dedupeSimilarity` | `number` | `0.9` | 去重的 Jaccard 阈值 |
| `sources` | `string[]` | `["daily","sessions","recall"]` | 数据源 |
### Deep 阶段（`phases.deep`）
将符合条件的候选内容提升到 `MEMORY.md` 中。它是**唯一**会写入持久事实的阶段。也负责在记忆稀薄时进行恢复。
将合格候选项提升到 `MEMORY.md` 中。**唯一**会写入持久事实的阶段。
也负责在内存内容稀少时进行恢复。
| 键名 | 类型 | 默认值 | 说明 |
| --------------------- | ---------- | ----------------------------------------------- | ------------------------------ |
| `enabled` | `boolean` | `true` | 启用 deep 阶段 |
| `cron` | `string` | `0 3 * * *` | 计划（每天凌晨 3 点） |
| `limit` | `number` | `10` | 每轮最大提升候选数 |
| `minScore` | `number` | `0.8` | 提升所需的最小加权分数 |
| `minRecallCount` | `number` | `3` | 最小 recall 次数阈值 |
| `minUniqueQueries` | `number` | `3` | 最小不同查询数 |
| `recencyHalfLifeDays` | `number` | `14` | 新近性分数减半所需天数 |
| `maxAgeDays` | `number` | `30` | 可提升的每日笔记最大年龄 |
| Key | Type | Default | Description |
| --------------------- | ---------- | ----------------------------------------------- | ------------------------------------ |
| `enabled` | `boolean` | `true` | 启用 deep 阶段 |
| `cron` | `string` | `0 3 * * *` | 计划（每天凌晨 3 点） |
| `limit` | `number` | `10` | 每个周期最大提升候选数 |
| `minScore` | `number` | `0.8` | 提升所需的最低加权分数 |
| `minRecallCount` | `number` | `3` | 最低 recall 次数阈值 |
| `minUniqueQueries` | `number` | `3` | 最低不同查询数 |
| `recencyHalfLifeDays` | `number` | `14` | 新近性分数减半所需天数 |
| `maxAgeDays` | `number` | `30` | 可提升的每日笔记最大时长 |
| `sources` | `string[]` | `["daily","memory","sessions","logs","recall"]` | 数据源 |
#### Deep 恢复（`phases.deep.recovery`）
| 键名 | 类型 | 默认值 | 说明 |
| ------------------------ | --------- | ------- | ------------------------------------- |
| `enabled` | `boolean` | `true` | 启用自动恢复 |
| `triggerBelowHealth` | `number` | `0.35` | 触发恢复的健康分数阈值 |
| `lookbackDays` | `number` | `30` | 查找恢复材料的回溯天数 |
| `maxRecoveredCandidates` | `number` | `20` | 每次运行最大恢复候选数 |
| `minRecoveryConfidence` | `number` | `0.9` | 恢复候选的最小置信度 |
| `autoWriteMinConfidence` | `number` | `0.97` | 自动写入阈值（跳过人工审核） |
| Key | Type | Default | Description |
| ------------------------ | --------- | ------- | ------------------------------------------ |
| `enabled` | `boolean` | `true` | 启用自动恢复 |
| `triggerBelowHealth` | `number` | `0.35` | 触发恢复的健康分数阈值 |
| `lookbackDays` | `number` | `30` | 向前查找恢复材料的时间范围 |
| `maxRecoveredCandidates` | `number` | `20` | 每次运行最大恢复候选数 |
| `minRecoveryConfidence` | `number` | `0.9` | 恢复候选项的最低置信度 |
| `autoWriteMinConfidence` | `number` | `0.97` | 自动写入阈值（跳过人工审核） |
### REM 阶段（`phases.rem`）
将主题、反思和模式笔记写入每日笔记。
在启用内联存储时，将主题、反思和模式注释写入 `DREAMS.md`。
**不会**写入 `MEMORY.md`。
| 键名 | 类型 | 默认值 | 说明 |
| -------------------- | ---------- | --------------------------- | -------------------------- |
| `enabled` | `boolean` | `true` | 启用 REM 阶段 |
| `cron` | `string` | `0 5 * * 0` | 计划（每周日凌晨 5 点） |
| `lookbackDays` | `number` | `7` | 用于反思的材料天数 |
| `limit` | `number` | `10` | 最多写入的模式或主题数 |
| `minPatternStrength` | `number` | `0.75` | 最小标签共现强度 |
| `sources` | `string[]` | `["memory","daily","deep"]` | 用于反思的数据源 |
| Key | Type | Default | Description |
| -------------------- | ---------- | --------------------------- | ---------------------------------- |
| `enabled` | `boolean` | `true` | 启用 REM 阶段 |
| `cron` | `string` | `0 5 * * 0` | 计划（每周日凌晨 5 点） |
| `lookbackDays` | `number` | `7` | 要反思的材料天数 |
| `limit` | `number` | `10` | 要写入的最大模式或主题数 |
| `minPatternStrength` | `number` | `0.75` | 最低标签共现强度 |
| `sources` | `string[]` | `["memory","daily","deep"]` | 用于反思的数据源 |
### 执行覆盖
每个阶段都接受一个 `execution` 块。还存在一个全局的
每个阶段都接受一个 `execution` 块。还有一个全局
`execution.defaults` 块，供各阶段继承。
| 键名 | 类型 | 默认值 | 说明 |
| ----------------- | -------- | ------------- | ---------------------------- |
| `speed` | `string` | `"balanced"` | `fast`、`balanced` 或 `slow` |
| `thinking` | `string` | `"medium"` | `low`、`medium` 或 `high` |
| `budget` | `string` | `"medium"` | `cheap`、`medium` 或 `expensive` |
| `model` | `string` | 未设置 | 覆盖此阶段的模型 |
| `maxOutputTokens` | `number` | 未设置 | 限制输出 token 数 |
| `temperature` | `number` | 未设置 | 采样温度（0-2） |
| `timeoutMs` | `number` | 未设置 | 阶段超时时间（毫秒） |
| Key | Type | Default | Description |
| ----------------- | -------- | ------------ | ------------------------------ |
| `speed` | `string` | `"balanced"` | `fast`、`balanced` 或 `slow` |
| `thinking` | `string` | `"medium"` | `low`、`medium` 或 `high` |
| `budget` | `string` | `"medium"` | `cheap`、`medium` 或 `expensive` |
| `model` | `string` | 未设置 | 覆盖此阶段使用的模型 |
| `maxOutputTokens` | `number` | 未设置 | 限制输出 token |
| `temperature` | `number` | 未设置 | 采样温度（0-2） |
| `timeoutMs` | `number` | 未设置 | 阶段超时时间（毫秒） |
### 示例

86
docs/zh-CN/tools/video-generation.md
View File

@ -3,13 +3,13 @@ read_when:
- 通过智能体生成视频
- 配置视频生成提供商和模型
- 了解 `video_generate` 工具参数
summary: 使用已配置的提供商（如 Alibaba、OpenAI、Google、Qwen 和 MiniMax）生成视频
summary: 使用已配置的提供商（例如 Alibaba、OpenAI、Google、Qwen 和 MiniMax）生成视频
title: 视频生成
x-i18n:
generated_at: "2026-04-05T22:30:15Z"
generated_at: "2026-04-05T22:59:35Z"
model: gpt-5.4
provider: openai
source_hash: 138de16fae7c0f00d1e2be55e62ccd6d8ea9e6364dc7f0159a68f9b00a2902eb
source_hash: 8b57870c6a53e51694cc1606b5620fc7b260a64ff9aec83a6123566f64b6f2ab
source_path: tools/video-generation.md
workflow: 15
---
@ -19,13 +19,13 @@ x-i18n:
`video_generate` 工具让智能体能够使用你已配置的提供商创建视频。生成的视频会作为媒体附件自动随智能体的回复一并发送。
<Note>
仅当至少有一个视频生成提供商可用时，此工具才会显示。如果你在智能体工具中看不到 `video_generate`，请配置 `agents.defaults.videoGenerationModel` 或设置提供商 API 密钥。
只有在至少有一个视频生成提供商可用时，此工具才会显示。如果你在智能体的工具中看不到 `video_generate`，请配置 `agents.defaults.videoGenerationModel` 或设置提供商 API 密钥。
</Note>
## 快速开始
1. 为至少一个提供商设置 API 密钥（例如 `OPENAI_API_KEY`、`GEMINI_API_KEY`、`MODELSTUDIO_API_KEY` 或 `QWEN_API_KEY`）。
2. 可选：设置你偏好的模型：
2. 你也可以设置首选模型：
```json5
{
@ -39,9 +39,9 @@ x-i18n:
}
```
3. 向智能体提问：_“生成一段 5 秒钟、黄昏时分一只友善龙虾冲浪的电影感视频。”_
3. 向智能体提出请求：_“生成一段 5 秒钟、具有电影感的友好龙虾在日落时分冲浪的视频。”_
智能体会自动调用 `video_generate`。无需工具允许列表——当有可用提供商时，它默认启用。
智能体会自动调用 `video_generate`。不需要工具允许列表 —— 当有可用提供商时，它默认启用。
## 支持的提供商
@ -65,24 +65,24 @@ x-i18n:
## 工具参数
| 参数 | 类型 | 说明 |
| ----------------- | -------- | ------------------------------------------------------------------------------------- |
| `prompt` | string | 视频生成提示词（`action: "generate"` 时必填） |
| `action` | string | `"generate"`（默认）或 `"list"`，用于查看提供商 |
| `model` | string | 提供商/模型覆盖，例如 `qwen/wan2.6-t2v` |
| `image` | string | 单个参考图片路径或 URL |
| `images` | string[] | 多个参考图片（最多 5 张） |
| `video` | string | 单个参考视频路径或 URL |
| `videos` | string[] | 多个参考视频（最多 4 个） |
| `size` | string | 当提供商支持时的尺寸提示 |
| `aspectRatio` | string | 宽高比：`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9` |
| `resolution` | string | 分辨率提示：`480P`、`720P` 或 `1080P` |
| `durationSeconds` | number | 目标时长（秒） |
| `audio` | boolean | 当提供商支持时，启用生成音频 |
| `watermark` | boolean | 当支持时，切换提供商水印 |
| `filename` | string | 输出文件名提示 |
| 参数 | 类型 | 说明 |
| ----------------- | -------- | -------------------------------------------------------------------------------------- |
| `prompt` | string | 视频生成提示词（`action: "generate"` 时必填） |
| `action` | string | `"generate"`（默认）或 `"list"`，用于查看提供商 |
| `model` | string | 提供商/模型覆盖，例如 `qwen/wan2.6-t2v` |
| `image` | string | 单个参考图片路径或 URL |
| `images` | string[] | 多个参考图片（最多 5 张） |
| `video` | string | 单个参考视频路径或 URL |
| `videos` | string[] | 多个参考视频（最多 4 个） |
| `size` | string | 当提供商支持时使用的尺寸提示 |
| `aspectRatio` | string | 宽高比：`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9` |
| `resolution` | string | 分辨率提示：`480P`、`720P` 或 `1080P` |
| `durationSeconds` | number | 目标时长（秒）。OpenClaw 可能会将其四舍五入到最接近的提供商支持值 |
| `audio` | boolean | 当提供商支持时启用生成音频 |
| `watermark` | boolean | 当支持时切换提供商水印 |
| `filename` | string | 输出文件名提示 |
并非所有提供商都支持所有参数。该工具会在提交请求前校验提供商能力限制。
并非所有提供商都支持所有参数。该工具会在提交请求前验证提供商的能力限制。当某个提供商或模型只支持离散的视频时长集合时，OpenClaw 会将 `durationSeconds` 四舍五入到最接近的受支持值，并在工具结果中报告规范化后的时长。
## 配置
@ -105,37 +105,37 @@ x-i18n:
生成视频时，OpenClaw 会按以下顺序尝试提供商：
1. 工具调用中的 **`model` 参数**（如果智能体指定了）
1. 工具调用中的 **`model` 参数**（如果智能体指定了一个）
2. 配置中的 **`videoGenerationModel.primary`**
3. 按顺序使用 **`videoGenerationModel.fallbacks`**
4. **自动检测**——仅使用基于凭证的提供商默认值：
4. **自动检测** —— 仅使用基于认证的提供商默认值：
- 先使用当前默认提供商
- 再按提供商 ID 顺序使用其余已注册的视频生成提供商
- 再按 provider-id 顺序使用其余已注册的视频生成提供商
如果某个提供商失败，会自动尝试下一个候选项。如果全部失败，错误中会包含每次尝试的详细信息。
如果某个提供商失败，会自动尝试下一个候选项。如果全部失败，错误信息中会包含每次尝试的详细信息。
## 提供商说明
- Alibaba 使用 DashScope / Model Studio 的异步视频端点，目前要求参考素材必须是远程 `http(s)` URL。
- Google 使用 Gemini/Veo，支持单个图片或视频参考输入。
- MiniMax、Together、BytePlus（国际版）和 fal 当前支持单个图片参考输入。
- Alibaba 使用 DashScope / Model Studio 异步视频端点，目前要求参考资源使用远程 `http(s)` URL。
- Google 使用 Gemini/Veo，并支持单个图片或视频参考输入。
- MiniMax、Together、BytePlus（国际版）和 fal 目前支持单个图片参考输入。
- OpenAI 使用原生视频端点，目前默认使用 `sora-2`。
- Qwen 支持图片/视频参考，但上游 DashScope 视频端点目前要求这些参考必须是远程 `http(s)` URL。
- xAI 使用原生 xAI 视频 API，支持文生视频、图生视频以及远程视频编辑/扩展流程。
- xAI 使用原生 xAI 视频 API，并支持文生视频、图生视频，以及远程视频编辑/扩展流程。
## Qwen 参考输入
内置的 Qwen 提供商支持文生视频以及图片/视频参考模式，但上游 DashScope 视频端点目前要求参考输入必须是**远程 http(s) URL**。本地文件路径和上传的缓冲区会在前端直接被拒绝，而不会被静默忽略。
内置的 Qwen 提供商支持文生视频以及图片/视频参考模式，但上游 DashScope 视频端点目前要求参考输入必须为 **远程 http(s) URL**。本地文件路径和上传的缓冲区会被提前拒绝，而不是被静默忽略。
## 相关内容
- [工具概览](/zh-CN/tools) — 所有可用的智能体工具
- [Alibaba Model Studio](/zh-CN/providers/alibaba) — 直接配置 Wan 提供商
- [Google (Gemini)](/zh-CN/providers/google) — Veo 提供商设置
- [MiniMax](/zh-CN/providers/minimax) — Hailuo 提供商设置
- [OpenAI](/zh-CN/providers/openai) — Sora 提供商设置
- [Qwen](/zh-CN/providers/qwen) — Qwen 专属设置与限制
- [Together AI](/zh-CN/providers/together) — Together Wan 提供商设置
- [xAI](/zh-CN/providers/xai) — Grok 视频提供商设置
- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) — `videoGenerationModel` 配置
- [模型](/zh-CN/concepts/models) — 模型配置与故障转移
- [工具概览](/zh-CN/tools) —— 所有可用的智能体工具
- [Alibaba Model Studio](/zh-CN/providers/alibaba) —— 直接设置 Wan 提供商
- [Google（Gemini）](/zh-CN/providers/google) —— Veo 提供商设置
- [MiniMax](/zh-CN/providers/minimax) —— Hailuo 提供商设置
- [OpenAI](/zh-CN/providers/openai) —— Sora 提供商设置
- [Qwen](/zh-CN/providers/qwen) —— Qwen 专用设置和限制
- [Together AI](/zh-CN/providers/together) —— Together Wan 提供商设置
- [xAI](/zh-CN/providers/xai) —— Grok 视频提供商设置
- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) —— `videoGenerationModel` 配置
- [模型](/zh-CN/concepts/models) —— 模型配置和故障转移