From 62066ef3e6e69e8b49a2f92523924fd72115726e Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 15 Apr 2026 10:56:13 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/concepts/dreaming.md | 140 +- docs/zh-CN/concepts/experimental-features.md | 44 + docs/zh-CN/concepts/memory.md | 106 +- docs/zh-CN/gateway/configuration-reference.md | 1509 ++++++++--------- docs/zh-CN/gateway/local-models.md | 66 +- docs/zh-CN/reference/memory-config.md | 340 ++-- 6 files changed, 1114 insertions(+), 1091 deletions(-) create mode 100644 docs/zh-CN/concepts/experimental-features.md diff --git a/docs/zh-CN/concepts/dreaming.md b/docs/zh-CN/concepts/dreaming.md index 961047ca3..014b841d1 100644 --- a/docs/zh-CN/concepts/dreaming.md +++ b/docs/zh-CN/concepts/dreaming.md @@ -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//YYYY-MM-DD.md` 阶段报告文件。 +- `DREAMS.md`（或现有的 `dreams.md`）中的**人类可读输出**，以及位于 `memory/dreaming//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` 支持的可展开梦境日记阅读器 ## 相关内容 diff --git a/docs/zh-CN/concepts/experimental-features.md b/docs/zh-CN/concepts/experimental-features.md new file mode 100644 index 000000000..ddf6d515d --- /dev/null +++ b/docs/zh-CN/concepts/experimental-features.md @@ -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 就应该在文档和配置路径本身中明确说明。**不应该**做的是，把预览行为偷偷塞进一个看起来稳定的默认开关里，然后假装这很正常。配置能力面正是这样变得混乱的。 diff --git a/docs/zh-CN/concepts/memory.md b/docs/zh-CN/concepts/memory.md index 19ffd8ea6..183b270d3 100644 --- a/docs/zh-CN/concepts/memory.md +++ b/docs/zh-CN/concepts/memory.md @@ -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`）。 -如果你希望你的智能体记住某件事，直接告诉它即可：“记住我更喜欢 TypeScript。” 它会将内容写入相应的文件。 +如果你希望智能体记住某件事，只要直接告诉它：“记住我更喜欢 TypeScript。” 它会把内容写入合适的文件。 -## 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 密钥，它就能开箱即用。 -OpenClaw 会根据可用的 API key 自动检测你的 embedding 提供商。如果你已配置 OpenAI、Gemini、Voyage 或 Mistral key，memory 搜索会自动启用。 +OpenClaw 会根据可用的 API 密钥自动检测你的嵌入提供商。如果你已配置 OpenAI、Gemini、Voyage 或 Mistral 密钥，内存搜索会自动启用。 -有关搜索工作原理、调优选项和提供商设置的详细信息，请参见 +有关搜索工作方式、调优选项和提供商设置的详细信息，请参见 [Memory Search](/zh-CN/concepts/memory-search)。 -## Memory 后端 +## 内存后端 基于 SQLite。开箱即用，支持关键词搜索、向量相似度和混合搜索。无需额外依赖。 -local-first sidecar，支持重排序、查询扩展，以及为工作区外部目录建立索引的能力。 +local-first sidecar，支持重排、查询扩展，以及为工作区外的目录建立索引。 -AI 原生的跨会话 memory，支持用户建模、语义搜索和多智能体感知。需安装插件。 +AI 原生的跨会话内存，支持用户建模、语义搜索和多智能体感知。通过插件安装。 @@ -86,40 +86,40 @@ AI 原生的跨会话 memory，支持用户建模、语义搜索和多智能体 -将持久记忆编译为一个带有丰富来源信息的 wiki 资料库，包含主张、仪表板、桥接模式以及对 Obsidian 友好的工作流。 +将持久记忆编译为一个带有丰富溯源信息的 wiki 仓库，包含主张、仪表板、桥接模式，以及对 Obsidian 友好的工作流。 -## 自动 memory 刷新 +## 自动内存刷新 -在 [compaction](/zh-CN/concepts/compaction) 总结你的对话之前，OpenClaw 会运行一个静默回合，提醒智能体将重要上下文保存到 memory 文件中。此功能默认开启——你无需配置任何内容。 +在 [compaction](/zh-CN/concepts/compaction) 对你的对话进行摘要之前，OpenClaw 会运行一个静默轮次，提醒智能体将重要上下文保存到内存文件中。此功能默认启用——你无需进行任何配置。 -memory 刷新可以防止在 compaction 期间丢失上下文。如果你的智能体在对话中有重要事实尚未写入文件，它们会在摘要发生前自动保存。 +内存刷新可以防止在 compaction 期间丢失上下文。如果你的智能体在对话中包含重要事实但尚未写入文件，它们会在摘要发生前自动保存。 -## 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 如何与内存交互 diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index 4837bfa63..627eb572f 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -2,69 +2,69 @@ read_when: - 你需要精确到字段级别的配置语义或默认值 - 你正在验证渠道、模型、Gateway 网关或工具配置块 -summary: Gateway 网关 配置参考，涵盖核心 OpenClaw 键名、默认值，以及指向各专用子系统参考文档的链接 +summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键名、默认值以及指向专用子系统参考文档的链接 title: 配置参考 x-i18n: - generated_at: "2026-04-11T12:34:22Z" + generated_at: "2026-04-15T10:48:13Z" model: gpt-5.4 provider: openai - source_hash: 351a245bed59d852ea8582e4e9fec5017a5c623cd6f0034766cdea1b5330be3c + source_hash: 7a4da3b41d0304389bd6359aac1185c231e529781b607656ab352f8a8104bdba source_path: gateway/configuration-reference.md workflow: 15 --- # 配置参考 -`~/.openclaw/openclaw.json` 的核心配置参考。若需按任务组织的概览，请参阅 [Configuration](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 的核心配置参考。若需面向任务的概览，请参见 [配置](/zh-CN/gateway/configuration)。 -本页介绍 OpenClaw 的主要配置层面，并在某个子系统拥有独立的更深入参考时提供对应链接。它**不会**尝试在单个页面中内联展示每个渠道/插件自有的命令目录，或所有深层 memory/QMD 调节项。 +本页涵盖主要的 OpenClaw 配置面，并在某个子系统拥有更深入的独立参考时提供跳转链接。它**不会**尝试在同一页内嵌入每个由渠道/插件拥有的命令目录，也不会内联所有深层 memory/QMD 调节项。 -代码事实依据： +代码中的真实依据： - `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据 -- `config.schema.lookup` 返回单一路径范围的 schema 节点，供深入查看工具使用 -- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面校验配置文档基线哈希 +- `config.schema.lookup` 会返回一个按路径限定的 schema 节点，供下钻工具使用 +- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 面验证配置文档基线哈希 -专门的深入参考： +专门的深度参考： -- [Memory configuration reference](/zh-CN/reference/memory-config) 用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置 -- [Slash Commands](/zh-CN/tools/slash-commands) 用于当前内置 + 内置插件命令目录 -- 对应渠道/插件页面，用于渠道特定的命令层面 +- [Memory 配置参考](/zh-CN/reference/memory-config)，用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置 +- [斜杠命令](/zh-CN/tools/slash-commands)，用于查看当前内置 + 内置插件的命令目录 +- 对应渠道/插件页面，用于查看渠道特定的命令面 -配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的 —— OpenClaw 在省略时会使用安全默认值。 +配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段均为可选——省略时，OpenClaw 会使用安全的默认值。 --- ## 渠道 -只要某个渠道的配置段存在，它就会自动启动（除非设置了 `enabled: false`）。 +每个渠道在其配置节存在时都会自动启动（除非设置了 `enabled: false`）。 ### 私信和群组访问 所有渠道都支持私信策略和群组策略： -| 私信策略 | 行为 | -| ------------------- | ------------------------------------------------ | -| `pairing`（默认） | 未知发送者会收到一次性配对码；需要 owner 批准 | -| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对允许存储） | -| `open` | 允许所有入站私信（需要 `allowFrom: ["*"]`） | -| `disabled` | 忽略所有入站私信 | +| 私信策略 | 行为 | +| ------------------- | ---- | +| `pairing`（默认） | 未知发送者会收到一次性配对码；必须由所有者批准 | +| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对允许存储中的发送者） | +| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） | +| `disabled` | 忽略所有传入私信 | -| 群组策略 | 行为 | -| --------------------- | ---------------------------------------------- | -| `allowlist`（默认） | 仅允许匹配已配置允许列表的群组 | -| `open` | 绕过群组允许列表（仍会应用提及门控） | -| `disabled` | 阻止所有群组/房间消息 | +| 群组策略 | 行为 | +| --------------------- | ---- | +| `allowlist`（默认） | 仅允许匹配已配置允许列表的群组 | +| `open` | 绕过群组允许列表（但仍会应用提及门控） | +| `disabled` | 阻止所有群组/房间消息 | -`channels.defaults.groupPolicy` 在提供商的 `groupPolicy` 未设置时作为默认值。 +`channels.defaults.groupPolicy` 用于在某个提供商未设置 `groupPolicy` 时指定默认值。 配对码会在 1 小时后过期。待处理的私信配对请求每个渠道最多 **3 个**。 -如果某个提供商配置块完全缺失（`channels.` 不存在），运行时群组策略会回退到 `allowlist`（默认拒绝），并在启动时发出警告。 +如果某个提供商块完全缺失（`channels.` 不存在），运行时群组策略会回退为 `allowlist`（默认拒绝），并在启动时发出警告。 ### 渠道模型覆盖 -使用 `channels.modelByChannel` 可将特定渠道 ID 固定到某个模型。值可接受 `provider/model` 或已配置的模型别名。当某个会话尚未有模型覆盖时（例如通过 `/model` 设置），会应用该渠道映射。 +使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值可接受 `provider/model` 或已配置的模型别名。当会话尚未具有模型覆盖时（例如通过 `/model` 设置），会应用该渠道映射。 ```json5 { @@ -87,7 +87,7 @@ x-i18n: ### 渠道默认值和心跳 -使用 `channels.defaults` 为各提供商共享群组策略和心跳行为： +使用 `channels.defaults` 为各提供商配置共享的群组策略和心跳行为： ```json5 { @@ -105,15 +105,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`：当提供商级别的 `groupPolicy` 未设置时的后备群组策略。 -- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。每渠道覆盖：`channels..contextVisibility`。 -- `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康的渠道状态。 +- `channels.defaults.groupPolicy`：当提供商级别的 `groupPolicy` 未设置时使用的回退群组策略。 +- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。单渠道覆盖：`channels..contextVisibility`。 +- `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康渠道状态。 - `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级/错误状态。 - `channels.defaults.heartbeat.useIndicator`：以紧凑的指示器样式渲染心跳输出。 ### WhatsApp -WhatsApp 通过 Gateway 网关 的 web 渠道（Baileys Web）运行。存在已链接的会话时会自动启动。 +WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在已关联会话时会自动启动。 ```json5 { @@ -124,7 +124,7 @@ WhatsApp 通过 Gateway 网关 的 web 渠道（Baileys Web）运行。存在已 textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // 蓝色对勾（self-chat 模式下为 false） + sendReadReceipts: true, // blue ticks (false in self-chat mode) groups: { "*": { requireMention: true }, }, @@ -164,8 +164,8 @@ WhatsApp 通过 Gateway 网关 的 web 渠道（Baileys Web）运行。存在已 } ``` -- 出站命令默认使用账号 `default`（如果存在）；否则使用第一个已配置的账号 id（排序后）。 -- 可选的 `channels.whatsapp.defaultAccount` 可在其匹配某个已配置账号 id 时，覆盖该后备默认账号选择。 +- 出站命令默认使用 `default` 账号（如果存在）；否则使用第一个已配置的账号 ID（排序后）。 +- 可选的 `channels.whatsapp.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖该回退默认账号选择。 - 旧版单账号 Baileys 凭证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 - 每账号覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -202,7 +202,7 @@ WhatsApp 通过 Gateway 网关 的 web 渠道（Baileys Web）运行。存在已 historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress（默认：off；需显式启用以避免预览编辑速率限制） + streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -225,13 +225,13 @@ WhatsApp 通过 Gateway 网关 的 web 渠道（Baileys Web）运行。存在已 } ``` -- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅允许常规文件；拒绝符号链接），默认账号还可回退到 `TELEGRAM_BOT_TOKEN`。 -- 可选的 `channels.telegram.defaultAccount` 可在其匹配某个已配置账号 id 时覆盖默认账号选择。 -- 在多账号配置（2 个及以上账号 id）中，请设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；缺失或无效时，`openclaw doctor` 会发出警告。 +- 机器人令牌：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅允许常规文件；拒绝符号链接），默认账号还可回退到 `TELEGRAM_BOT_TOKEN`。 +- 可选的 `channels.telegram.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。 +- 在多账号配置（2 个及以上账号 ID）中，设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；若缺失或无效，`openclaw doctor` 会发出警告。 - `configWrites: false` 会阻止由 Telegram 发起的配置写入（supergroup ID 迁移、`/config set|unset`）。 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目用于为论坛话题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义共享于 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 -- Telegram 流式预览使用 `sendMessage` + `editMessageText`（适用于私聊和群聊）。 -- 重试策略：参见 [Retry policy](/zh-CN/concepts/retry)。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目用于为论坛主题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享说明。 +- Telegram 流式预览使用 `sendMessage` + `editMessageText`（可在私聊和群聊中工作）。 +- 重试策略：参见 [重试策略](/zh-CN/concepts/retry)。 ### Discord @@ -286,7 +286,7 @@ WhatsApp 通过 Gateway 网关 的 web 渠道（Baileys Web）运行。存在已 historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress（在 Discord 上 progress 会映射为 partial） + streaming: "off", // off | partial | block | progress (progress maps to partial on Discord) maxLinesPerMessage: 17, ui: { components: { @@ -297,7 +297,7 @@ WhatsApp 通过 Gateway 网关 的 web 渠道（Baileys Web）运行。存在已 enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // 为 sessions_spawn({ thread: true }) 显式启用 + spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true }) }, voice: { enabled: true, @@ -333,36 +333,36 @@ WhatsApp 通过 Gateway 网关 的 web 渠道（Baileys Web）运行。存在已 } ``` -- Token：`channels.discord.token`，默认账号还可回退到 `DISCORD_BOT_TOKEN`。 -- 直接出站调用若显式提供 Discord `token`，该次调用会使用该 token；但账号重试/策略设置仍来自活动运行时快照中选定的账号。 -- 可选的 `channels.discord.defaultAccount` 可在其匹配某个已配置账号 id 时覆盖默认账号选择。 -- 交付目标请使用 `user:`（私信）或 `channel:`（guild 渠道）；裸数字 ID 会被拒绝。 -- Guild slug 会转换为小写，并将空格替换为 `-`；渠道键使用 slug 化后的名称（不含 `#`）。优先使用 guild ID。 -- 默认会忽略由 bot 自己编写的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 则只接受提及该 bot 的 bot 消息（自身消息仍会被过滤）。 -- `channels.discord.guilds..ignoreOtherMentions`（以及渠道级覆盖）会丢弃提及了其他用户或角色、但未提及该 bot 的消息（不包括 @everyone/@here）。 -- `maxLinesPerMessage`（默认 17）会在消息行数过多时进行拆分，即使总长度未超过 2000 个字符。 +- 令牌：`channels.discord.token`，默认账号可回退到 `DISCORD_BOT_TOKEN`。 +- 直接出站调用如果提供了显式的 Discord `token`，则该次调用会使用该令牌；账号重试/策略设置仍来自当前运行时快照中选定的账号。 +- 可选的 `channels.discord.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。 +- 投递目标使用 `user:`（私信）或 `channel:`（guild 渠道）；裸数字 ID 会被拒绝。 +- Guild slug 为小写，并将空格替换为 `-`；渠道键使用 slug 化后的名称（不含 `#`）。优先使用 guild ID。 +- 默认会忽略由机器人自己编写的消息。`allowBots: true` 会启用这些消息；使用 `allowBots: "mentions"` 则只接受提及该机器人的机器人消息（机器人自己的消息仍会被过滤）。 +- `channels.discord.guilds..ignoreOtherMentions`（以及渠道级覆盖）会丢弃那些提及了其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。 +- `maxLinesPerMessage`（默认 17）会拆分过高的消息，即使其长度未超过 2000 个字符。 - `channels.discord.threadBindings` 控制 Discord 线程绑定路由： - - `enabled`：用于线程绑定会话功能的 Discord 覆盖设置（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定交付/路由） - - `idleHours`：以小时计的非活动自动取消聚焦 Discord 覆盖值（`0` 表示禁用） - - `maxAgeHours`：以小时计的硬性最大存活时间 Discord 覆盖值（`0` 表示禁用） - - `spawnSubagentSessions`：为 `sessions_spawn({ thread: true })` 自动创建/绑定线程的显式启用开关 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目用于为渠道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用渠道/线程 id）。字段语义共享于 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 + - `enabled`：线程绑定会话功能的 Discord 覆盖项（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定投递/路由） + - `idleHours`：以小时为单位的 Discord 非活动自动取消聚焦覆盖项（`0` 表示禁用） + - `maxAgeHours`：以小时为单位的 Discord 硬性最大时长覆盖项（`0` 表示禁用） + - `spawnSubagentSessions`：为 `sessions_spawn({ thread: true })` 自动创建/绑定线程启用的可选开关 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目用于为渠道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用 channel/thread ID）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享说明。 - `channels.discord.ui.components.accentColor` 用于设置 Discord components v2 容器的强调色。 -- `channels.discord.voice` 启用 Discord 语音频道对话，以及可选的自动加入 + TTS 覆盖。 +- `channels.discord.voice` 启用 Discord 语音频道对话以及可选的自动加入 + TTS 覆盖。 - `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会透传给 `@discordjs/voice` 的 DAVE 选项（默认分别为 `true` 和 `24`）。 - OpenClaw 还会在重复解密失败后，通过离开并重新加入语音会话来尝试恢复语音接收。 - `channels.discord.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔型 `streaming` 值会被自动迁移。 -- `channels.discord.autoPresence` 会将运行时可用性映射到 bot 在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。 -- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/tag 匹配（紧急兼容模式）。 -- `channels.discord.execApprovals`：Discord 原生 exec 审批交付和审批人授权。 +- `channels.discord.autoPresence` 会将运行时可用性映射为机器人在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。 +- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变的名称/tag 匹配（紧急兼容模式）。 +- `channels.discord.execApprovals`：Discord 原生的 exec 审批投递和审批人授权。 - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，exec 审批会激活。 - `approvers`：允许批准 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。 - - `agentFilter`：可选的智能体 ID 允许列表。省略时会为所有智能体转发审批。 + - `agentFilter`：可选的智能体 ID 允许列表。省略则为所有智能体转发审批。 - `sessionFilter`：可选的会话键模式（子串或正则）。 - - `target`：审批提示发送位置。`"dm"`（默认）发送到审批人的私信，`"channel"` 发送到来源渠道，`"both"` 同时发送到两者。当目标包含 `"channel"` 时，按钮仅对已解析的审批人可用。 - - `cleanupAfterResolve`：为 `true` 时，在审批通过、拒绝或超时后删除审批私信。 + - `target`：审批提示发送位置。`"dm"`（默认）发送到审批人的私信，`"channel"` 发送到发起渠道，`"both"` 同时发送到两者。当目标包含 `"channel"` 时，按钮仅可由已解析的审批人使用。 + - `cleanupAfterResolve`：为 `true` 时，在批准、拒绝或超时后删除审批私信。 -**Reaction notification 模式：** `off`（无）、`own`（bot 自己的消息，默认）、`all`（所有消息）、`allowlist`（`guilds..users` 中所有消息的允许列表）。 +**反应通知模式：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（`guilds..users` 中的用户在所有消息上的反应）。 ### Google Chat @@ -393,11 +393,11 @@ WhatsApp 通过 Gateway 网关 的 web 渠道（Baileys Web）运行。存在已 } ``` -- Service account JSON：支持内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 -- 也支持 Service account SecretRef（`serviceAccountRef`）。 +- 服务账号 JSON：支持内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 +- 也支持服务账号 SecretRef（`serviceAccountRef`）。 - 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 -- 交付目标请使用 `spaces/` 或 `users/`。 -- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变 email principal 匹配（紧急兼容模式）。 +- 投递目标使用 `spaces/` 或 `users/`。 +- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变的电子邮件主体匹配（紧急兼容模式）。 ### Slack @@ -449,7 +449,7 @@ WhatsApp 通过 Gateway 网关 的 web 渠道（Baileys Web）运行。存在已 chunkMode: "length", streaming: { mode: "partial", // off | partial | block | progress - nativeTransport: true, // mode=partial 时使用 Slack 原生流式 API + nativeTransport: true, // use Slack native streaming API when mode=partial }, mediaMaxMb: 20, execApprovals: { @@ -464,38 +464,34 @@ WhatsApp 通过 Gateway 网关 的 web 渠道（Baileys Web）运行。存在已 } ``` -- **Socket 模式** 需要同时提供 `botToken` 和 `appToken`（默认账号环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 -- **HTTP 模式** 需要 `botToken` 加 `signingSecret`（可位于根级或按账号配置）。 -- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文 - 字符串或 SecretRef 对象。 -- Slack 账号快照会公开按凭证区分的来源/状态字段，例如 - `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式下的 - `signingSecretStatus`。`configured_unavailable` 表示该账号通过 SecretRef - 配置，但当前命令/运行时路径无法解析出 secret 值。 +- **Socket 模式** 需要同时提供 `botToken` 和 `appToken`（默认账号的环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 +- **HTTP 模式** 需要 `botToken` 加上 `signingSecret`（可位于根级或每账号级）。 +- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串或 SecretRef 对象。 +- Slack 账号快照会暴露按凭证划分的来源/状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式下的 `signingSecretStatus`。`configured_unavailable` 表示该账号通过 SecretRef 配置，但当前命令/运行时路径无法解析该密钥值。 - `configWrites: false` 会阻止由 Slack 发起的配置写入。 -- 可选的 `channels.slack.defaultAccount` 可在其匹配某个已配置账号 id 时覆盖默认账号选择。 -- `channels.slack.streaming.mode` 是规范的 Slack 流式模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输。旧版 `streamMode`、布尔型 `streaming` 和 `nativeStreaming` 值会被自动迁移。 -- 交付目标请使用 `user:`（私信）或 `channel:`。 +- 可选的 `channels.slack.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。 +- `channels.slack.streaming.mode` 是规范的 Slack 流式模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 原生流式传输。旧版 `streamMode`、布尔型 `streaming` 和 `nativeStreaming` 值会被自动迁移。 +- 投递目标使用 `user:`（私信）或 `channel:`。 -**Reaction notification 模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 +**反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -**线程会话隔离：** `thread.historyScope` 可设为每线程（默认）或与整个渠道共享。`thread.inheritParent` 会将父渠道转录复制到新线程。 +**线程会话隔离：** `thread.historyScope` 可为每线程（默认）或全渠道共享。`thread.inheritParent` 会将父渠道转录复制到新线程。 -- Slack 原生流式传输以及 Slack assistant 风格的“正在输入...”线程状态都需要回复线程目标。顶层私信默认保持非线程模式，因此会使用 `typingReaction` 或普通交付，而不是线程样式预览。 -- `typingReaction` 会在回复运行期间向入站 Slack 消息添加一个临时 reaction，并在完成后移除。请使用 Slack emoji shortcode，例如 `"hourglass_flowing_sand"`。 -- `channels.slack.execApprovals`：Slack 原生 exec 审批交付和审批人授权。schema 与 Discord 相同：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 +- Slack 原生流式传输以及 Slack 助手风格的“正在输入...”线程状态需要以回复线程作为目标。顶层私信默认保持非线程形式，因此会使用 `typingReaction` 或常规投递，而不是线程式预览。 +- `typingReaction` 会在回复运行期间，向入站 Slack 消息添加一个临时反应，并在完成时移除。使用 Slack 表情 shortcode，例如 `"hourglass_flowing_sand"`。 +- `channels.slack.execApprovals`：Slack 原生的 exec 审批投递和审批人授权。与 Discord 使用相同 schema：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 -| 操作组 | 默认值 | 说明 | -| ----------- | ------ | -------------------- | -| reactions | 启用 | 添加 reaction + 列出 reactions | -| messages | 启用 | 读取/发送/编辑/删除 | -| pins | 启用 | 固定/取消固定/列出 | -| memberInfo | 启用 | 成员信息 | -| emojiList | 启用 | 自定义 emoji 列表 | +| 操作组 | 默认值 | 说明 | +| ------------ | ------- | ---------------------- | +| reactions | 已启用 | 添加反应 + 列出反应 | +| messages | 已启用 | 读取/发送/编辑/删除 | +| pins | 已启用 | 置顶/取消置顶/列出 | +| memberInfo | 已启用 | 成员信息 | +| emojiList | 已启用 | 自定义表情列表 | ### Mattermost -Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost`。 +Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermost`。 ```json5 { @@ -512,10 +508,10 @@ Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost` "team-channel-id": { requireMention: false }, }, commands: { - native: true, // 显式启用 + native: true, // opt-in nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // 反向代理/公网部署时可选的显式 URL + // Optional explicit URL for reverse-proxy/public deployments callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -525,22 +521,18 @@ Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost` } ``` -聊天模式：`oncall`（在 @ 提及时响应，默认）、`onmessage`（每条消息都响应）、`onchar`（以触发前缀开头的消息）。 +聊天模式：`oncall`（在 @ 提及时响应，默认）、`onmessage`（每条消息都响应）、`onchar`（响应以触发前缀开头的消息）。 启用 Mattermost 原生命令时： - `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），不能是完整 URL。 -- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关 端点，并且 Mattermost 服务器必须可访问。 -- 原生 slash 回调通过 Mattermost 在 slash 命令注册期间返回的每命令 token 进行身份验证。如果注册失败或没有 - 命令被激活，OpenClaw 会拒绝回调，并返回 - `Unauthorized: invalid command token.`。 -- 对于私有/tailnet/内部回调主机，Mattermost 可能要求 - `ServiceSettings.AllowedUntrustedInternalConnections` 包含该回调主机/域名。 - 请使用主机/域名值，而不是完整 URL。 +- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器能够访问。 +- 原生斜杠回调会使用 Mattermost 在注册斜杠命令期间返回的每命令令牌进行身份验证。如果注册失败，或没有激活任何命令，OpenClaw 会拒绝回调，并返回 `Unauthorized: invalid command token.`。 +- 对于 private/tailnet/internal 回调主机，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机/域名。请使用主机/域名值，而不是完整 URL。 - `channels.mattermost.configWrites`：允许或拒绝由 Mattermost 发起的配置写入。 -- `channels.mattermost.requireMention`：要求在渠道中先 `@mention` 才会回复。 -- `channels.mattermost.groups..requireMention`：按渠道设置的提及门控覆盖（`"*"` 表示默认值）。 -- 可选的 `channels.mattermost.defaultAccount` 可在其匹配某个已配置账号 id 时覆盖默认账号选择。 +- `channels.mattermost.requireMention`：在渠道中回复前要求 `@mention`。 +- `channels.mattermost.groups..requireMention`：每渠道提及门控覆盖（`"*"` 表示默认）。 +- 可选的 `channels.mattermost.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。 ### Signal @@ -549,7 +541,7 @@ Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost` channels: { signal: { enabled: true, - account: "+15555550123", // 可选账号绑定 + account: "+15555550123", // optional account binding dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -561,15 +553,15 @@ Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost` } ``` -**Reaction notification 模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 +**反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 - `channels.signal.account`：将渠道启动固定到特定的 Signal 账号身份。 - `channels.signal.configWrites`：允许或拒绝由 Signal 发起的配置写入。 -- 可选的 `channels.signal.defaultAccount` 可在其匹配某个已配置账号 id 时覆盖默认账号选择。 +- 可选的 `channels.signal.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。 ### BlueBubbles -BlueBubbles 是推荐的 iMessage 路径（由插件支持，配置位于 `channels.bluebubbles` 下）。 +BlueBubbles 是推荐的 iMessage 方案（由插件支持，配置位于 `channels.bluebubbles` 下）。 ```json5 { @@ -577,21 +569,21 @@ BlueBubbles 是推荐的 iMessage 路径（由插件支持，配置位于 `chann bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl、password、webhookPath、群组控制以及高级操作： - // 参见 /channels/bluebubbles + // serverUrl, password, webhookPath, group controls, and advanced actions: + // see /channels/bluebubbles }, }, } ``` - 此处涵盖的核心键路径：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 -- 可选的 `channels.bluebubbles.defaultAccount` 可在其匹配某个已配置账号 id 时覆盖默认账号选择。 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目可将 BlueBubbles 会话绑定到持久 ACP 会话。请在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- 可选的 `channels.bluebubbles.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目可将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 - 完整的 BlueBubbles 渠道配置见 [BlueBubbles](/zh-CN/channels/bluebubbles)。 ### iMessage -OpenClaw 会启动 `imsg rpc`（基于 stdio 的 JSON-RPC）。无需 daemon 或端口。 +OpenClaw 会生成 `imsg rpc`（基于 stdio 的 JSON-RPC）。无需 daemon 或端口。 ```json5 { @@ -615,17 +607,17 @@ OpenClaw 会启动 `imsg rpc`（基于 stdio 的 JSON-RPC）。无需 daemon 或 } ``` -- 可选的 `channels.imessage.defaultAccount` 可在其匹配某个已配置账号 id 时覆盖默认账号选择。 +- 可选的 `channels.imessage.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。 - 需要对 Messages 数据库授予 Full Disk Access。 -- 优先使用 `chat_id:` 目标。使用 `imsg chats --limit 20` 可列出聊天。 -- `cliPath` 可以指向 SSH 包装脚本；设置 `remoteHost`（`host` 或 `user@host`）以便通过 SCP 获取附件。 -- `attachmentRoots` 和 `remoteAttachmentRoots` 会限制入站附件路径（默认：`/Users/*/Library/Messages/Attachments`）。 -- SCP 使用严格的主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 +- 优先使用 `chat_id:` 目标。使用 `imsg chats --limit 20` 列出聊天。 +- `cliPath` 可指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。 +- `attachmentRoots` 和 `remoteAttachmentRoots` 用于限制入站附件路径（默认：`/Users/*/Library/Messages/Attachments`）。 +- SCP 使用严格主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 - `channels.imessage.configWrites`：允许或拒绝由 iMessage 发起的配置写入。 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目可将 iMessage 会话绑定到持久 ACP 会话。请在 `match.peer.id` 中使用规范化 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目可将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 - + ```bash #!/usr/bin/env bash @@ -636,7 +628,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix 由扩展支持，配置位于 `channels.matrix` 下。 +Matrix 由扩展支持，并配置在 `channels.matrix` 下。 ```json5 { @@ -666,25 +658,25 @@ Matrix 由扩展支持，配置位于 `channels.matrix` 下。 } ``` -- Token 认证使用 `accessToken`；密码认证使用 `userId` + `password`。 -- `channels.matrix.proxy` 会通过显式 HTTP(S) 代理转发 Matrix HTTP 流量。命名账号可通过 `channels.matrix.accounts..proxy` 覆盖该设置。 -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 与该网络显式启用项是彼此独立的控制项。 -- `channels.matrix.defaultAccount` 会在多账号配置中选择首选账号。 -- `channels.matrix.autoJoin` 默认为 `off`，因此受邀房间和新的私信式邀请会被忽略，直到你设置 `autoJoin: "allowlist"` 并配置 `autoJoinAllowlist`，或设置 `autoJoin: "always"`。 -- `channels.matrix.execApprovals`：Matrix 原生 exec 审批交付和审批人授权。 +- 令牌认证使用 `accessToken`；密码认证使用 `userId` + `password`。 +- `channels.matrix.proxy` 会通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账号可以通过 `channels.matrix.accounts..proxy` 进行覆盖。 +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许使用 private/internal homeserver。`proxy` 与此网络启用项是彼此独立的控制项。 +- `channels.matrix.defaultAccount` 在多账号配置中选择首选账号。 +- `channels.matrix.autoJoin` 默认为 `off`，因此受邀房间和新的私信样式邀请会被忽略，直到你设置 `autoJoin: "allowlist"` 并配合 `autoJoinAllowlist`，或设置 `autoJoin: "always"`。 +- `channels.matrix.execApprovals`：Matrix 原生的 exec 审批投递和审批人授权。 - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，exec 审批会激活。 - `approvers`：允许批准 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。 - - `agentFilter`：可选的智能体 ID 允许列表。省略时会为所有智能体转发审批。 + - `agentFilter`：可选的智能体 ID 允许列表。省略则为所有智能体转发审批。 - `sessionFilter`：可选的会话键模式（子串或正则）。 - - `target`：审批提示发送位置。`"dm"`（默认）、`"channel"`（来源房间）或 `"both"`。 + - `target`：审批提示发送位置。`"dm"`（默认）、`"channel"`（发起房间）或 `"both"`。 - 每账号覆盖：`channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归并到会话中：`per-user`（默认）按路由后的对端共享，而 `per-room` 会隔离每个私信房间。 -- Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。 +- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归并为会话：`per-user`（默认）按路由对端共享，而 `per-room` 则隔离每个私信房间。 +- Matrix 状态探测和实时目录查询使用与运行时流量相同的代理策略。 - 完整的 Matrix 配置、目标规则和设置示例见 [Matrix](/zh-CN/channels/matrix)。 ### Microsoft Teams -Microsoft Teams 由扩展支持，配置位于 `channels.msteams` 下。 +Microsoft Teams 由扩展支持，并配置在 `channels.msteams` 下。 ```json5 { @@ -692,19 +684,19 @@ Microsoft Teams 由扩展支持，配置位于 `channels.msteams` 下。 msteams: { enabled: true, configWrites: true, - // appId、appPassword、tenantId、webhook、团队/渠道策略： - // 参见 /channels/msteams + // appId, appPassword, tenantId, webhook, team/channel policies: + // see /channels/msteams }, }, } ``` - 此处涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。 -- 完整的 Teams 配置（凭证、webhook、私信/群组策略、按团队/按渠道覆盖）见 [Microsoft Teams](/zh-CN/channels/msteams)。 +- 完整的 Teams 配置（凭证、webhook、私信/群组策略、每团队/每渠道覆盖）见 [Microsoft Teams](/zh-CN/channels/msteams)。 ### IRC -IRC 由扩展支持，配置位于 `channels.irc` 下。 +IRC 由扩展支持，并配置在 `channels.irc` 下。 ```json5 { @@ -726,12 +718,12 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 ``` - 此处涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 -- 可选的 `channels.irc.defaultAccount` 可在其匹配某个已配置账号 id 时覆盖默认账号选择。 -- 完整的 IRC 渠道配置（host/port/TLS/channels/allowlists/mention gating）见 [IRC](/zh-CN/channels/irc)。 +- 可选的 `channels.irc.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。 +- 完整的 IRC 渠道配置（host/port/TLS/channels/allowlists/提及门控）见 [IRC](/zh-CN/channels/irc)。 ### 多账号（所有渠道） -每个渠道可运行多个账号（每个账号都有自己的 `accountId`）： +为每个渠道运行多个账号（每个账号都有各自的 `accountId`）： ```json5 { @@ -752,28 +744,28 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 } ``` -- 省略 `accountId` 时，会使用 `default`（CLI + 路由）。 -- 环境变量 token 仅适用于 **default** 账号。 -- 基础渠道设置适用于所有账号，除非按账号覆盖。 -- 使用 `bindings[].match.accountId` 可将每个账号路由到不同的智能体。 -- 如果你通过 `openclaw channels add`（或渠道新手引导）添加一个非默认账号，而当前仍是单账号顶层渠道配置，OpenClaw 会先将账号作用域的顶层单账号值提升到渠道账号映射中，以便原始账号继续工作。大多数渠道会将其迁移到 `channels..accounts.default`；Matrix 则可以保留现有的匹配命名/默认目标。 -- 现有的仅渠道绑定（无 `accountId`）会继续匹配默认账号；按账号作用域的绑定仍然是可选的。 -- `openclaw doctor --fix` 也会通过将账号作用域的顶层单账号值移入该渠道所选的提升账号中来修复混合形态。大多数渠道使用 `accounts.default`；Matrix 则可以保留现有的匹配命名/默认目标。 +- 省略 `accountId` 时使用 `default`（CLI + 路由）。 +- 环境变量令牌仅适用于 **default** 账号。 +- 基础渠道设置适用于所有账号，除非被每账号配置覆盖。 +- 使用 `bindings[].match.accountId` 将每个账号路由到不同智能体。 +- 如果你通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，而当前仍使用单账号顶层渠道配置，OpenClaw 会先将带账号作用域的顶层单账号值提升到该渠道的账号映射中，以便原始账号继续工作。大多数渠道会将它们移入 `channels..accounts.default`；Matrix 则可以保留现有匹配的命名/default 目标。 +- 现有仅渠道级绑定（无 `accountId`）会继续匹配默认账号；账号级绑定仍为可选。 +- `openclaw doctor --fix` 也会通过将带账号作用域的顶层单账号值移动到为该渠道选择的提升账号中来修复混合形态。大多数渠道使用 `accounts.default`；Matrix 则可以保留现有匹配的命名/default 目标。 ### 其他扩展渠道 -许多扩展渠道都配置为 `channels.`，并在其专属渠道页面中说明（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 -请参阅完整渠道索引： [Channels](/zh-CN/channels)。 +许多扩展渠道都配置为 `channels.`，并在各自专属的渠道页面中记录（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 +请参见完整渠道索引： [渠道](/zh-CN/channels)。 ### 群聊提及门控 -群组消息默认 **需要提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 +群组消息默认 **需要提及**（元数据提及或安全 regex 模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 **提及类型：** - **元数据提及**：平台原生 @ 提及。在 WhatsApp self-chat 模式下会被忽略。 -- **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 -- 仅在可以检测到提及时（原生提及或至少一个模式）才会执行提及门控。 +- **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 中的安全 regex 模式。无效模式和不安全的嵌套重复会被忽略。 +- 仅当可以检测提及时（原生提及或至少一个模式）才会强制执行提及门控。 ```json5 { @@ -786,7 +778,7 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 } ``` -`messages.groupChat.historyLimit` 设置全局默认值。渠道可通过 `channels..historyLimit`（或按账号）覆盖。设置为 `0` 可禁用。 +`messages.groupChat.historyLimit` 设置全局默认值。渠道可以通过 `channels..historyLimit`（或每账号级）覆盖。设为 `0` 可禁用。 #### 私信历史限制 @@ -803,13 +795,13 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 } ``` -解析顺序：按私信覆盖 → 提供商默认值 → 不限制（全部保留）。 +解析顺序：每私信覆盖 → 提供商默认值 → 不限制（全部保留）。 支持：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 -#### self-chat 模式 +#### Self-chat 模式 -将你自己的号码加入 `allowFrom` 以启用 self-chat 模式（忽略原生 @ 提及，只响应文本模式）： +在 `allowFrom` 中包含你自己的号码即可启用 self-chat 模式（忽略原生 @ 提及，仅响应文本模式）： ```json5 { @@ -830,21 +822,21 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 } ``` -### Commands（聊天命令处理） +### 命令（聊天命令处理） ```json5 { commands: { - native: "auto", // 支持时注册原生命令 - nativeSkills: "auto", // 支持时注册原生 Skills 命令 - text: true, // 解析聊天消息中的 /commands - bash: false, // 允许 !（别名：/bash） + native: "auto", // register native commands when supported + nativeSkills: "auto", // register native skill commands when supported + text: true, // parse /commands in chat messages + bash: false, // allow ! (alias: /bash) bashForegroundMs: 2000, - config: false, // 允许 /config - mcp: false, // 允许 /mcp - plugins: false, // 允许 /plugins - debug: false, // 允许 /debug - restart: true, // 允许 /restart + Gateway 网关重启工具 + config: false, // allow /config + mcp: false, // allow /mcp + plugins: false, // allow /plugins + debug: false, // allow /debug + restart: true, // allow /restart + gateway restart tool ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -859,32 +851,32 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 -- 此配置块用于设置命令层面。当前内置 + 内置插件命令目录请参阅 [Slash Commands](/zh-CN/tools/slash-commands)。 -- 本页是**配置键参考**，不是完整命令目录。像 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、device-pair `/pair`、memory `/dreaming`、phone-control `/phone` 和 Talk `/voice` 这类由渠道/插件自有的命令，记录在各自的渠道/插件页面以及 [Slash Commands](/zh-CN/tools/slash-commands) 中。 -- 文本命令必须是带有前导 `/` 的**独立**消息。 +- 此块用于配置命令面。当前内置 + 内置插件命令目录请参见 [斜杠命令](/zh-CN/tools/slash-commands)。 +- 本页是**配置键参考**，不是完整命令目录。由渠道/插件拥有的命令，例如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、device-pair `/pair`、memory `/dreaming`、phone-control `/phone` 和 Talk `/voice`，记录在各自的渠道/插件页面以及 [斜杠命令](/zh-CN/tools/slash-commands) 中。 +- 文本命令必须是带前导 `/` 的**独立**消息。 - `native: "auto"` 会为 Discord/Telegram 打开原生命令，Slack 保持关闭。 - `nativeSkills: "auto"` 会为 Discord/Telegram 打开原生 Skills 命令，Slack 保持关闭。 -- 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除之前注册的命令。 -- 可通过 `channels..commands.nativeSkills` 按渠道覆盖原生 Skills 注册。 -- `channels.telegram.customCommands` 会添加额外的 Telegram bot 菜单项。 +- 按渠道覆盖：`channels.discord.commands.native`（bool 或 `"auto"`）。`false` 会清除先前已注册的命令。 +- 使用 `channels..commands.nativeSkills` 按渠道覆盖原生 Skills 命令注册。 +- `channels.telegram.customCommands` 会添加额外的 Telegram 机器人菜单项。 - `bash: true` 会为主机 shell 启用 `! `。需要 `tools.elevated.enabled`，且发送者位于 `tools.elevated.allowFrom.` 中。 - `config: true` 会启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化的 `/config set|unset` 写入还需要 `operator.admin`；只读的 `/config show` 对普通写权限范围的 operator 客户端仍然可用。 -- `mcp: true` 会为 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置启用 `/mcp`。 -- `plugins: true` 会为插件发现、安装以及启用/禁用控制启用 `/plugins`。 -- `channels..configWrites` 控制每个渠道的配置变更权限（默认：true）。 +- `mcp: true` 会启用 `/mcp`，用于管理位于 `mcp.servers` 下的 OpenClaw 托管 MCP 服务器配置。 +- `plugins: true` 会启用 `/plugins`，用于插件发现、安装以及启用/禁用控制。 +- `channels..configWrites` 用于按渠道控制配置变更（默认：true）。 - 对于多账号渠道，`channels..accounts..configWrites` 也会控制针对该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 - `restart: false` 会禁用 `/restart` 和 Gateway 网关重启工具操作。默认值：`true`。 -- `ownerAllowFrom` 是仅限 owner 的命令/工具所使用的显式 owner 允许列表。它与 `allowFrom` 分开。 -- `ownerDisplay: "hash"` 会在系统提示中对 owner id 进行哈希处理。设置 `ownerDisplaySecret` 可控制哈希方式。 -- `allowFrom` 按提供商生效。设置后，它就是**唯一**的授权来源（渠道允许列表/配对以及 `useAccessGroups` 都会被忽略）。 -- `useAccessGroups: false` 会在未设置 `allowFrom` 时允许命令绕过访问组策略。 +- `ownerAllowFrom` 是 owner-only 命令/工具的显式 owner 允许列表。它独立于 `allowFrom`。 +- `ownerDisplay: "hash"` 会在系统提示中对 owner ID 做哈希处理。设置 `ownerDisplaySecret` 可控制哈希。 +- `allowFrom` 是按提供商配置的。设置后，它将成为**唯一**的授权来源（渠道允许列表/配对以及 `useAccessGroups` 都会被忽略）。 +- `useAccessGroups: false` 会在未设置 `allowFrom` 时，允许命令绕过 access-group 策略。 - 命令文档映射： - - 内置 + 内置插件目录： [Slash Commands](/zh-CN/tools/slash-commands) - - 渠道特定命令层面： [Channels](/zh-CN/channels) - - QQ Bot 命令： [QQ Bot](/zh-CN/channels/qqbot) - - 配对命令： [Pairing](/zh-CN/channels/pairing) - - LINE 卡片命令： [LINE](/zh-CN/channels/line) - - memory dreaming： [Dreaming](/zh-CN/concepts/dreaming) + - 内置 + 内置插件目录：[斜杠命令](/zh-CN/tools/slash-commands) + - 渠道特定命令面：[渠道](/zh-CN/channels) + - QQ Bot 命令：[QQ Bot](/zh-CN/channels/qqbot) + - 配对命令：[Pairing](/zh-CN/channels/pairing) + - LINE 卡片命令：[LINE](/zh-CN/channels/line) + - memory dreaming：[Dreaming](/zh-CN/concepts/dreaming) @@ -904,7 +896,7 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 ### `agents.defaults.repoRoot` -可选的仓库根目录，会显示在系统提示的 Runtime 行中。若未设置，OpenClaw 会从 workspace 开始向上遍历自动检测。 +可选的仓库根目录，会显示在系统提示的 Runtime 行中。如果未设置，OpenClaw 会从 workspace 开始向上遍历并自动检测。 ```json5 { @@ -914,27 +906,25 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 ### `agents.defaults.skills` -为未设置 -`agents.list[].skills` 的智能体提供可选的默认 Skills 允许列表。 +为未设置 `agents.list[].skills` 的智能体指定可选的默认 Skills 允许列表。 ```json5 { agents: { defaults: { skills: ["github", "weather"] }, list: [ - { id: "writer" }, // 继承 github、weather - { id: "docs", skills: ["docs-search"] }, // 替换默认值 - { id: "locked-down", skills: [] }, // 无 Skills + { id: "writer" }, // inherits github, weather + { id: "docs", skills: ["docs-search"] }, // replaces defaults + { id: "locked-down", skills: [] }, // no skills ], }, } ``` -- 省略 `agents.defaults.skills` 则默认 Skills 不受限制。 -- 省略 `agents.list[].skills` 则继承默认值。 +- 省略 `agents.defaults.skills`，则默认 Skills 不受限制。 +- 省略 `agents.list[].skills`，则继承默认值。 - 设置 `agents.list[].skills: []` 表示不启用任何 Skills。 -- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合； - 不会与默认值合并。 +- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它不会与默认值合并。 ### `agents.defaults.skipBootstrap` @@ -948,9 +938,9 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 ### `agents.defaults.contextInjection` -控制何时将 workspace bootstrap 文件注入到系统提示中。默认值：`"always"`。 +控制何时将 workspace bootstrap 文件注入系统提示。默认值：`"always"`。 -- `"continuation-skip"`：安全续接轮次（在 assistant 完成回复之后）会跳过再次注入 workspace bootstrap，从而减少提示大小。heartbeat 运行和压缩后的重试仍会重建上下文。 +- `"continuation-skip"`：安全续写轮次（在 assistant 完成响应之后）会跳过 workspace bootstrap 的重新注入，以减少提示大小。心跳运行和压缩后的重试仍会重建上下文。 ```json5 { @@ -980,12 +970,11 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 ### `agents.defaults.bootstrapPromptTruncationWarning` -控制 bootstrap 上下文被截断时对智能体可见的警告文本。 -默认值：`"once"`。 +控制在 bootstrap 上下文被截断时，向智能体可见的警告文本。默认值：`"once"`。 -- `"off"`：绝不在系统提示中注入警告文本。 -- `"once"`：每个唯一的截断签名只注入一次警告（推荐）。 -- `"always"`：只要存在截断，就在每次运行时都注入警告。 +- `"off"`：绝不将警告文本注入系统提示。 +- `"once"`：对每个唯一的截断签名仅注入一次警告（推荐）。 +- `"always"`：只要存在截断，每次运行都注入警告。 ```json5 { @@ -995,11 +984,10 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 ### `agents.defaults.imageMaxDimensionPx` -在调用提供商之前，转录/工具图像块中图像最长边的最大像素尺寸。 -默认值：`1200`。 +在调用提供商之前，transcript/tool 图像块中图像最长边的最大像素尺寸。默认值：`1200`。 -较低的值通常会减少视觉 token 使用量，以及以截图为主的运行中的请求负载大小。 -较高的值则会保留更多视觉细节。 +较低的值通常会降低 vision token 用量，并减小截图密集型运行的请求负载大小。 +较高的值会保留更多视觉细节。 ```json5 { @@ -1009,7 +997,7 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 ### `agents.defaults.userTimezone` -系统提示上下文使用的时区（不影响消息时间戳）。会回退到主机时区。 +系统提示上下文所用的时区（不影响消息时间戳）。会回退到主机时区。 ```json5 { @@ -1057,9 +1045,9 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // 全局默认提供商参数 + params: { cacheRetention: "long" }, // global default provider params embeddedHarness: { - runtime: "auto", // auto | pi | 已注册的 harness id，例如 codex + runtime: "auto", // auto | pi | registered harness id, e.g. codex fallback: "pi", // pi | none }, pdfMaxBytesMb: 10, @@ -1077,47 +1065,47 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 ``` - `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 字符串形式只设置主模型。 - - 对象形式设置主模型以及按顺序排列的故障转移模型。 + - 字符串形式仅设置主模型。 + - 对象形式设置主模型以及按顺序的故障转移模型。 - `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 由 `image` 工具路径用作其 vision 模型配置。 - - 当选定/默认模型无法接受图像输入时，也会用作回退路由。 + - 用作 `image` 工具路径的 vision 模型配置。 + - 当选定/默认模型无法接受图像输入时，也用作回退路由。 - `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 由共享图像生成能力以及任何未来生成图像的工具/插件层面使用。 - - 常见值：`google/gemini-3.1-flash-image-preview`（原生 Gemini 图像生成）、`fal/fal-ai/flux/dev`（fal）或 `openai/gpt-image-1`（OpenAI Images）。 + - 用于共享的图像生成能力，以及任何未来会生成图像的工具/插件面。 + - 典型值：`google/gemini-3.1-flash-image-preview`（原生 Gemini 图像生成）、`fal/fal-ai/flux/dev`（fal）或 `openai/gpt-image-1`（OpenAI Images）。 - 如果你直接选择某个提供商/模型，也要配置匹配的提供商凭证/API key（例如 `google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 使用 `OPENAI_API_KEY`，`fal/*` 使用 `FAL_KEY`）。 - - 如果省略，`image_generate` 仍可推断出带凭证的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的图像生成提供商。 + - 如果省略，`image_generate` 仍可推断出一个基于凭证的提供商默认值。它会先尝试当前默认提供商，再按提供商 ID 顺序尝试其余已注册的图像生成提供商。 - `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 由共享音乐生成能力和内置 `music_generate` 工具使用。 - - 常见值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。 - - 如果省略，`music_generate` 仍可推断出带凭证的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的音乐生成提供商。 + - 用于共享的音乐生成能力以及内置的 `music_generate` 工具。 + - 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。 + - 如果省略，`music_generate` 仍可推断出一个基于凭证的提供商默认值。它会先尝试当前默认提供商，再按提供商 ID 顺序尝试其余已注册的音乐生成提供商。 - 如果你直接选择某个提供商/模型，也要配置匹配的提供商凭证/API key。 - `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 由共享视频生成能力和内置 `video_generate` 工具使用。 - - 常见值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。 - - 如果省略，`video_generate` 仍可推断出带凭证的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的视频生成提供商。 + - 用于共享的视频生成能力以及内置的 `video_generate` 工具。 + - 典型值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。 + - 如果省略，`video_generate` 仍可推断出一个基于凭证的提供商默认值。它会先尝试当前默认提供商，再按提供商 ID 顺序尝试其余已注册的视频生成提供商。 - 如果你直接选择某个提供商/模型，也要配置匹配的提供商凭证/API key。 - - 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图片、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 + - 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 - `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 由 `pdf` 工具用于模型路由。 - - 如果省略，PDF 工具会依次回退到 `imageModel`，然后回退到解析后的会话/默认模型。 -- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具使用的默认 PDF 大小限制。 -- `pdfMaxPages`：`pdf` 工具在提取回退模式下默认考虑的最大页数。 -- `verboseDefault`：智能体的默认详细级别。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。 -- `elevatedDefault`：智能体的默认 elevated-output 级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 -- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该确切模型 id 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此推荐显式使用 `provider/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是继续保留陈旧的已移除提供商默认值。 -- `models`：为 `/model` 配置的模型目录和允许列表。每个条目可以包含 `alias`（快捷名）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 -- `params`：应用于所有模型的全局默认提供商参数。设置于 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 -- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（每模型）覆盖，然后 `agents.list[].params`（匹配的智能体 id）按键覆盖。详情见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 -- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。使用 `runtime: "auto"` 让已注册插件 harness 认领其支持的模型，使用 `runtime: "pi"` 强制使用内置 PI harness，或使用已注册的 harness id，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动 PI 回退。 -- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及回退添加/删除命令）会保存为规范的对象形式，并在可能时保留现有回退列表。 -- `maxConcurrent`：跨会话并行运行的最大智能体数（每个会话本身仍是串行的）。默认值：4。 + - 用于 `pdf` 工具的模型路由。 + - 如果省略，PDF 工具会先回退到 `imageModel`，再回退到解析后的会话/默认模型。 +- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb`，作为 `pdf` 工具的默认 PDF 大小限制。 +- `pdfMaxPages`：`pdf` 工具中提取回退模式默认考虑的最大页数。 +- `verboseDefault`：智能体默认详细级别。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。 +- `elevatedDefault`：智能体默认 elevated-output 级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 +- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果省略提供商，OpenClaw 会先尝试别名，然后尝试对该确切模型 ID 的唯一已配置提供商匹配，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此建议优先使用显式 `provider/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是继续暴露一个过时、已移除提供商的默认值。 +- `models`：为 `/model` 配置的模型目录和允许列表。每个条目可包含 `alias`（快捷名）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 +- `params`：应用到所有模型的全局默认提供商参数。设置在 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 +- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（每模型）覆盖，然后由 `agents.list[].params`（匹配的智能体 ID）按键覆盖。详见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 +- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。使用 `runtime: "auto"` 可让已注册插件 harness 接管受支持模型，使用 `runtime: "pi"` 可强制使用内置 PI harness，或使用已注册的 harness ID，例如 `runtime: "codex"`。将 `fallback: "none"` 设为禁用自动 PI 回退。 +- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及回退模型 add/remove 命令）会保存为规范对象形式，并尽可能保留现有回退列表。 +- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话仍然串行）。默认值：4。 ### `agents.defaults.embeddedHarness` `embeddedHarness` 控制哪个底层执行器运行嵌入式智能体轮次。 大多数部署应保留默认值 `{ runtime: "auto", fallback: "pi" }`。 -当受信任的插件提供原生 harness 时可使用此项，例如内置的 +当可信插件提供原生 harness 时使用它，例如内置的 Codex app-server harness。 ```json5 @@ -1134,15 +1122,15 @@ Codex app-server harness。 } ``` -- `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness id。内置 Codex 插件注册的 id 是 `codex`。 -- `fallback`：`"pi"` 或 `"none"`。`"pi"` 会保留内置 PI harness 作为兼容性回退。`"none"` 则会在插件 harness 选择缺失或不受支持时直接失败，而不是静默使用 PI。 +- `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness ID。内置 Codex 插件注册为 `codex`。 +- `fallback`：`"pi"` 或 `"none"`。`"pi"` 会保留内置 PI harness 作为兼容性回退。`"none"` 会在插件 harness 缺失或不支持时直接失败，而不是静默使用 PI。 - 环境变量覆盖：`OPENCLAW_AGENT_RUNTIME=` 会覆盖 `runtime`；`OPENCLAW_AGENT_HARNESS_FALLBACK=none` 会为该进程禁用 PI 回退。 -- 对于仅使用 Codex 的部署，请设置 `model: "codex/gpt-5.4"`、`embeddedHarness.runtime: "codex"` 和 `embeddedHarness.fallback: "none"`。 -- 这只控制嵌入式聊天 harness。媒体生成、vision、PDF、音乐、视频和 TTS 仍使用各自的提供商/模型设置。 +- 对于仅 Codex 的部署，设置 `model: "codex/gpt-5.4"`、`embeddedHarness.runtime: "codex"` 和 `embeddedHarness.fallback: "none"`。 +- 这仅控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的提供商/模型设置。 **内置别名简写**（仅在模型位于 `agents.defaults.models` 中时生效）： -| 别名 | 模型 | +| 别名 | 模型 | | ------------------- | -------------------------------------- | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | @@ -1156,12 +1144,12 @@ Codex app-server harness。 你配置的别名始终优先于默认值。 Z.AI GLM-4.x 模型会自动启用 thinking 模式，除非你设置 `--thinking off`，或自行定义 `agents.defaults.models["zai/"].params.thinking`。 -Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设为 `false` 可禁用。 -Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 `adaptive` thinking。 +Z.AI 模型默认启用 `tool_stream`，用于工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设为 `false` 可禁用。 +Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 `adaptive` thinking。 ### `agents.defaults.cliBackends` -用于纯文本回退运行（无工具调用）的可选 CLI 后端。在 API 提供商失败时可作为备用方案。 +用于纯文本回退运行（无工具调用）的可选 CLI 后端。当 API 提供商失败时可作为备用方案。 ```json5 { @@ -1195,7 +1183,7 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 ### `agents.defaults.systemPromptOverride` -将 OpenClaw 组装出的完整系统提示替换为固定字符串。可在默认级别设置（`agents.defaults.systemPromptOverride`），也可按智能体设置（`agents.list[].systemPromptOverride`）。按智能体的值优先；空值或仅空白字符的值会被忽略。适用于受控提示实验。 +用固定字符串替换整个由 OpenClaw 组装的系统提示。可设置在默认级别（`agents.defaults.systemPromptOverride`）或每智能体级别（`agents.list[].systemPromptOverride`）。每智能体值优先；空值或仅空白值会被忽略。适合用于受控提示实验。 ```json5 { @@ -1209,23 +1197,23 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 ### `agents.defaults.heartbeat` -周期性 heartbeat 运行。 +周期性心跳运行。 ```json5 { agents: { defaults: { heartbeat: { - every: "30m", // 0m 表示禁用 + every: "30m", // 0m disables model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // 默认：true；false 会从系统提示中省略 Heartbeat 部分 - lightContext: false, // 默认：false；true 仅保留 workspace bootstrap 文件中的 HEARTBEAT.md - isolatedSession: false, // 默认：false；true 会让每次 heartbeat 在全新会话中运行（无对话历史） + includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt + lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files + isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) session: "main", to: "+15555550123", - directPolicy: "allow", // allow（默认）| block - target: "none", // 默认：none | 可选值：last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow (default) | block + target: "none", // default: none | options: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -1236,15 +1224,15 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 } ``` -- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API-key 认证）或 `1h`（OAuth 认证）。设置为 `0m` 可禁用。 +- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。 - `includeSystemPromptSection`：为 false 时，会从系统提示中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入 bootstrap 上下文。默认值：`true`。 -- `suppressToolErrorWarnings`：为 true 时，会在 heartbeat 运行期间抑制工具错误警告负载。 -- `timeoutSeconds`：heartbeat 智能体轮次在被中止前允许的最长秒数。若未设置，则使用 `agents.defaults.timeoutSeconds`。 -- `directPolicy`：直接/私信交付策略。`allow`（默认）允许直接目标交付。`block` 会阻止直接目标交付，并发出 `reason=dm-blocked`。 -- `lightContext`：为 true 时，heartbeat 运行会使用轻量 bootstrap 上下文，并且仅保留 workspace bootstrap 文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：为 true 时，每次 heartbeat 都会在一个没有先前对话历史的全新会话中运行。与 cron `sessionTarget: "isolated"` 采用相同的隔离模式。可将每次 heartbeat 的 token 成本从约 100K 降低到约 2-5K。 -- 按智能体设置：使用 `agents.list[].heartbeat`。当任一智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 heartbeat。 -- Heartbeat 会执行完整的智能体轮次 —— 更短的间隔会消耗更多 token。 +- `suppressToolErrorWarnings`：为 true 时，会在心跳运行期间抑制工具错误警告负载。 +- `timeoutSeconds`：心跳智能体轮次在被中止前允许的最长秒数。若未设置，则使用 `agents.defaults.timeoutSeconds`。 +- `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 会抑制直接目标投递，并发出 `reason=dm-blocked`。 +- `lightContext`：为 true 时，心跳运行会使用轻量 bootstrap 上下文，并且只保留 workspace bootstrap 文件中的 `HEARTBEAT.md`。 +- `isolatedSession`：为 true 时，每次心跳都会在全新会话中运行，不带任何先前对话历史。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次心跳的 token 成本从约 100K 降至约 2-5K。 +- 每智能体：设置 `agents.list[].heartbeat`。当任意智能体定义了 `heartbeat` 时，**仅这些智能体**会运行心跳。 +- 心跳会运行完整智能体轮次——间隔越短，消耗的 token 越多。 ### `agents.defaults.compaction` @@ -1258,15 +1246,15 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // 当 identifierPolicy=custom 时使用 - postCompactionSections: ["Session Startup", "Red Lines"], // [] 表示禁用重新注入 + identifierInstructions: "精确保留部署 ID、工单 ID 和 host:port 对。", // 当 identifierPolicy=custom 时使用 + postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection model: "openrouter/anthropic/claude-sonnet-4-6", // 可选，仅用于 compaction 的模型覆盖 - notifyUser: true, // compaction 开始时向用户发送简短通知（默认：false） + notifyUser: true, // compaction 开始时发送简短通知（默认：false） memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "Session nearing compaction. Store durable memories now.", - prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.", + systemPrompt: "会话即将进行 compaction。现在存储持久 memory。", + prompt: "将任何持久笔记写入 memory/YYYY-MM-DD.md；如果没有要存储的内容，请仅回复精确的静默 token NO_REPLY。", }, }, }, @@ -1274,19 +1262,19 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 } ``` -- `mode`：`default` 或 `safeguard`（针对长历史的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `provider`：已注册 compaction 提供商插件的 id。设置后，会调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。失败时会回退到内置实现。设置提供商会强制 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `timeoutSeconds`：OpenClaw 在中止前允许单次 compaction 操作运行的最长秒数。默认值：`900`。 -- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预先附加内置的不透明标识符保留指引。 +- `mode`：`default` 或 `safeguard`（对长历史进行分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `provider`：已注册 compaction 提供商插件的 ID。设置后，将调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。失败时回退到内置实现。设置提供商会强制 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `timeoutSeconds`：OpenClaw 中止单次 compaction 操作前允许的最长秒数。默认值：`900`。 +- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预置内置的不透明标识符保留指导。 - `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。 -- `postCompactionSections`：compaction 后重新注入的可选 AGENTS.md H2/H3 章节名。默认值为 `["Session Startup", "Red Lines"]`；设置为 `[]` 可禁用重新注入。未设置时，或显式设置为该默认对时，也会接受旧版 `Every Session`/`Safety` 标题作为兼容性回退。 -- `model`：可选的 `provider/model-id` 覆盖，仅用于 compaction 摘要。当主会话应保持使用某个模型，而 compaction 摘要应改用另一个模型时可使用此项；未设置时，compaction 使用会话的主模型。 +- `postCompactionSections`：compaction 后重新注入的可选 AGENTS.md H2/H3 章节名。默认值为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。当未设置，或显式设为该默认对时，也接受旧版 `Every Session`/`Safety` 标题作为兼容性回退。 +- `model`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。适用于主会话保持某个模型，而 compaction 摘要改用另一个模型的场景；未设置时，compaction 使用会话的主模型。 - `notifyUser`：为 `true` 时，compaction 开始时向用户发送简短通知（例如“正在压缩上下文...”）。默认禁用，以保持 compaction 静默。 -- `memoryFlush`：在自动 compaction 前执行静默的智能体轮次，用于存储持久 memory。workspace 为只读时会跳过。 +- `memoryFlush`：在自动 compaction 前执行的静默智能体轮次，用于存储持久 memory。workspace 为只读时会跳过。 ### `agents.defaults.contextPruning` -在发送给 LLM 之前，从内存上下文中修剪**旧的工具结果**。**不会**修改磁盘上的会话历史。 +在发送给 LLM 之前，从内存上下文中裁剪**旧的工具结果**。**不会**修改磁盘上的会话历史。 ```json5 { @@ -1310,23 +1298,23 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 -- `mode: "cache-ttl"` 会启用修剪流程。 -- `ttl` 控制多久之后才允许再次运行修剪（自上次缓存触碰后计算）。 -- 修剪会先对过大的工具结果做软裁剪，然后在需要时对更旧的工具结果做硬清除。 +- `mode: "cache-ttl"` 会启用裁剪过程。 +- `ttl` 控制在上次缓存触达后，多久才能再次运行裁剪。 +- 裁剪会先对超大的工具结果执行软裁剪，再在需要时对更早的工具结果执行硬清除。 -**软裁剪** 会保留开头和结尾，并在中间插入 `...`。 +**软裁剪**会保留开头 + 结尾，并在中间插入 `...`。 -**硬清除** 会用占位符替换整个工具结果。 +**硬清除**会将整个工具结果替换为占位符。 注意： - 图像块永远不会被裁剪/清除。 -- 比例按字符计算（近似值），不是精确 token 数。 -- 如果 assistant 消息少于 `keepLastAssistants`，则会跳过修剪。 +- 比例基于字符数（近似），不是精确 token 数。 +- 如果 assistant 消息少于 `keepLastAssistants` 条，则跳过裁剪。 -行为细节见 [Session Pruning](/zh-CN/concepts/session-pruning)。 +行为细节参见 [会话裁剪](/zh-CN/concepts/session-pruning)。 ### 分块流式传输 @@ -1338,17 +1326,17 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 blockStreamingBreak: "text_end", // text_end | message_end blockStreamingChunk: { minChars: 800, maxChars: 1200 }, blockStreamingCoalesce: { idleMs: 1000 }, - humanDelay: { mode: "natural" }, // off | natural | custom（使用 minMs/maxMs） + humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs) }, }, } ``` -- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才会启用分块回复。 -- 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账号变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 -- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。按智能体覆盖：`agents.list[].humanDelay`。 +- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。 +- 渠道覆盖：`channels..blockStreamingCoalesce`（以及每账号变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 +- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500 ms。每智能体覆盖：`agents.list[].humanDelay`。 -行为和分块细节见 [Streaming](/zh-CN/concepts/streaming)。 +行为和分块细节参见 [流式传输](/zh-CN/concepts/streaming)。 ### 输入指示器 @@ -1364,15 +1352,15 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 ``` - 默认值：私聊/提及时为 `instant`，未提及的群聊为 `message`。 -- 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 +- 每会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 -参见 [Typing Indicators](/zh-CN/concepts/typing-indicators)。 +参见 [输入指示器](/zh-CN/concepts/typing-indicators)。 ### `agents.defaults.sandbox` -嵌入式智能体的可选沙箱隔离。完整指南见 [Sandboxing](/zh-CN/gateway/sandboxing)。 +嵌入式智能体的可选沙箱隔离。完整指南参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -1475,38 +1463,38 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 - `ssh`：通用 SSH 支持的远程运行时 - `openshell`：OpenShell 运行时 -选择 `backend: "openshell"` 时，运行时特定设置会移到 +选择 `backend: "openshell"` 时，运行时特定设置会移至 `plugins.entries.openshell.config`。 **SSH 后端配置：** - `target`：`user@host[:port]` 形式的 SSH 目标 - `command`：SSH 客户端命令（默认：`ssh`） -- `workspaceRoot`：供各作用域 workspace 使用的远程绝对根目录 +- `workspaceRoot`：用于每作用域 workspace 的远程绝对根目录 - `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件 -- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其物化为临时文件 +- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其实体化为临时文件 - `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关 -**SSH 认证优先级：** +**SSH 身份验证优先级：** - `identityData` 优先于 `identityFile` - `certificateData` 优先于 `certificateFile` - `knownHostsData` 优先于 `knownHostsFile` -- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前，从当前 active secrets 运行时快照中解析 +- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前从活动 secrets 运行时快照中解析 **SSH 后端行为：** -- 在创建或重建后，先对远程 workspace 执行一次初始填充 -- 此后保持远程 SSH workspace 为规范副本 +- 在创建或重建后对远程 workspace 执行一次初始化 +- 之后保持远程 SSH workspace 为规范副本 - 通过 SSH 路由 `exec`、文件工具和媒体路径 -- 不会自动将远程变更同步回主机 +- 不会自动将远程更改同步回主机 - 不支持沙箱浏览器容器 -**workspace 访问：** +**Workspace 访问：** -- `none`：在 `~/.openclaw/sandboxes` 下为每个作用域创建沙箱 workspace -- `ro`：沙箱 workspace 位于 `/workspace`，智能体 workspace 以只读方式挂载到 `/agent` -- `rw`：智能体 workspace 以读写方式挂载到 `/workspace` +- `none`：每作用域的沙箱 workspace 位于 `~/.openclaw/sandboxes` 下 +- `ro`：沙箱 workspace 位于 `/workspace`，智能体 workspace 只读挂载到 `/agent` +- `rw`：智能体 workspace 读写挂载到 `/workspace` **作用域：** @@ -1527,10 +1515,10 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // 可选 - gatewayEndpoint: "https://lab.example", // 可选 - policy: "strict", // 可选 OpenShell policy id - providers: ["openai"], // 可选 + gateway: "lab", // optional + gatewayEndpoint: "https://lab.example", // optional + policy: "strict", // optional OpenShell policy id + providers: ["openai"], // optional autoProviders: true, timeoutSeconds: 120, }, @@ -1542,30 +1530,30 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 **OpenShell 模式：** -- `mirror`：执行前先从本地填充远程，执行后再同步回本地；本地 workspace 保持为规范副本 -- `remote`：仅在创建沙箱时向远程填充一次，此后保持远程 workspace 为规范副本 +- `mirror`：在执行前将本地内容同步到远程，执行后再同步回本地；本地 workspace 保持为规范副本 +- `remote`：在创建沙箱时只向远程初始化一次，之后保持远程 workspace 为规范副本 -在 `remote` 模式下，种子步骤之后，在 OpenClaw 之外于主机本地所做的编辑不会自动同步到沙箱中。 -传输通过 SSH 连接到 OpenShell 沙箱，但插件负责沙箱生命周期以及可选的镜像同步。 +在 `remote` 模式下，种子步骤之后，在 OpenClaw 之外于主机本地所做的编辑不会自动同步进沙箱。 +传输通过 SSH 进入 OpenShell 沙箱，但插件拥有沙箱生命周期以及可选的 mirror 同步。 -**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统以及 root 用户。 +**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。 **容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 -默认会阻止 `"host"`。默认也会阻止 `"container:"`，除非你显式设置 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急放行）。 +`"host"` 会被阻止。默认也会阻止 `"container:"`，除非你显式设置 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急开关）。 -**入站附件** 会被暂存到当前 workspace 的 `media/inbound/*` 中。 +**入站附件** 会被暂存到活动 workspace 中的 `media/inbound/*`。 -**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的绑定会合并。 +**`docker.binds`** 会挂载额外的主机目录；全局和每智能体绑定会合并。 -**沙箱隔离浏览器**（`sandbox.browser.enabled`）：在容器中运行 Chromium + CDP。noVNC URL 会注入到系统提示中。无需在 `openclaw.json` 中启用 `browser.enabled`。 -noVNC 观察者访问默认使用 VNC 身份验证，OpenClaw 会发出一个短时有效的 token URL（而不是在共享 URL 中暴露密码）。 +**沙箱隔离浏览器**（`sandbox.browser.enabled`）：在容器中运行的 Chromium + CDP。noVNC URL 会注入到系统提示中。不需要在 `openclaw.json` 中启用 `browser.enabled`。 +noVNC 观察者访问默认使用 VNC 身份验证，OpenClaw 会发出短时有效的 token URL（而不是在共享 URL 中暴露密码）。 - `allowHostControl: false`（默认）会阻止沙箱隔离会话以主机浏览器为目标。 -- `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。仅当你明确需要全局 bridge 连通性时才设置为 `bridge`。 -- `cdpSourceRange` 可选地将容器边缘的 CDP 入站流量限制为某个 CIDR 范围（例如 `172.21.0.1/32`）。 -- `sandbox.browser.binds` 仅为沙箱隔离浏览器容器挂载额外的主机目录。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。 -- 启动默认值定义于 `scripts/sandbox-browser-entrypoint.sh`，并针对容器主机进行了调优： +- `network` 默认是 `openclaw-sandbox-browser`（专用 bridge 网络）。仅当你明确需要全局 bridge 连通性时才设为 `bridge`。 +- `cdpSourceRange` 可选择将容器边界上的 CDP 入站限制为某个 CIDR 范围（例如 `172.21.0.1/32`）。 +- `sandbox.browser.binds` 仅将额外的主机目录挂载到沙箱隔离浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。 +- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机进行了调优： - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1583,24 +1571,24 @@ noVNC 观察者访问默认使用 VNC 身份验证，OpenClaw 会发出一个短 - `--no-zygote` - `--metrics-recording-only` - `--disable-extensions`（默认启用） - - 默认会启用 `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu`，如果你的工作流需要使用 WebGL/3D，可通过设置 `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 来禁用这些选项。 - - 如果你的工作流依赖扩展，可通过 `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 重新启用扩展。 - - `--renderer-process-limit=2` 可通过 `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设为 `0` 则使用 Chromium 的默认进程上限。 - - 当启用 `noSandbox` 时，还会额外使用 `--no-sandbox` 和 `--disable-setuid-sandbox`。 - - 这些默认值是容器镜像的基线；如需更改容器默认值，请使用带有自定义 entrypoint 的自定义浏览器镜像。 + - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` 默认启用；如果 WebGL/3D 使用需要，可通过设置 `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 来禁用这些标志。 + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展，如果你的工作流依赖扩展。 + - `--renderer-process-limit=2` 可通过 `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 更改；设为 `0` 则使用 Chromium 的默认进程限制。 + - 以及当启用 `noSandbox` 时使用 `--no-sandbox` 和 `--disable-setuid-sandbox`。 + - 这些默认值是容器镜像基线；如需更改容器默认值，请使用带有自定义 entrypoint 的自定义浏览器镜像。 -浏览器沙箱隔离和 `sandbox.docker.binds` 仅适用于 Docker。 +浏览器沙箱隔离和 `sandbox.docker.binds` 仅支持 Docker。 构建镜像： ```bash -scripts/sandbox-setup.sh # 主沙箱镜像 -scripts/sandbox-browser-setup.sh # 可选浏览器镜像 +scripts/sandbox-setup.sh # main sandbox image +scripts/sandbox-browser-setup.sh # optional browser image ``` -### `agents.list`（按智能体覆盖） +### `agents.list`（每智能体覆盖） ```json5 { @@ -1613,12 +1601,12 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // 或 { primary, fallbacks } - thinkingDefault: "high", // 按智能体覆盖的默认 thinking 级别 - reasoningDefault: "on", // 按智能体覆盖的默认 reasoning 可见性 - fastModeDefault: false, // 按智能体覆盖的默认 fast mode + thinkingDefault: "high", // 每智能体 thinking 级别覆盖 + reasoningDefault: "on", // 每智能体 reasoning 可见性覆盖 + fastModeDefault: false, // 每智能体 fast mode 覆盖 embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // 按键覆盖匹配 defaults.models params - skills: ["docs-search"], // 设置后替换 agents.defaults.skills + params: { cacheRetention: "none" }, // 逐键覆盖匹配的 defaults.models params + skills: ["docs-search"], // 设置时替换 agents.defaults.skills identity: { name: "Samantha", theme: "helpful sloth", @@ -1649,27 +1637,27 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 } ``` -- `id`：稳定的智能体 id（必填）。 -- `default`：若设置了多个，则第一个生效（会记录警告）。若一个都未设置，则列表中的第一个条目为默认值。 -- `model`：字符串形式只覆盖 `primary`；对象形式 `{ primary, fallbacks }` 同时覆盖两者（`[]` 会禁用全局回退）。仅覆盖 `primary` 的 cron 作业仍会继承默认回退，除非你设置 `fallbacks: []`。 -- `params`：按智能体设置的流式参数，会合并覆盖到 `agents.defaults.models` 中所选模型条目之上。用于设置特定智能体覆盖项，例如 `cacheRetention`、`temperature` 或 `maxTokens`，而无需复制整个模型目录。 -- `skills`：可选的按智能体 Skills 允许列表。若省略，则在已设置时继承 `agents.defaults.skills`；显式列表会替换默认值而不是合并，`[]` 表示不启用任何 Skills。 -- `thinkingDefault`：可选的按智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive`）。在未设置按消息或会话覆盖时，会覆盖该智能体的 `agents.defaults.thinkingDefault`。 -- `reasoningDefault`：可选的按智能体默认 reasoning 可见性（`on | off | stream`）。在未设置按消息或会话 reasoning 覆盖时生效。 -- `fastModeDefault`：可选的按智能体 fast mode 默认值（`true | false`）。在未设置按消息或会话 fast-mode 覆盖时生效。 -- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex", fallback: "none" }` 可让某个智能体仅使用 Codex，而其他智能体保留默认的 PI 回退。 -- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，可使用 `type: "acp"` 并设置 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 -- `identity.avatar`：相对于 workspace 的路径、`http(s)` URL 或 `data:` URI。 -- `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name`/`emoji`。 -- `subagents.allowAgents`：用于 `sessions_spawn` 的智能体 id 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 -- 沙箱继承保护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝那些会以非沙箱方式运行的目标。 +- `id`：稳定的智能体 ID（必填）。 +- `default`：如果设置了多个，则第一个生效（会记录警告）。如果都未设置，则列表第一项为默认值。 +- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 同时覆盖两者（`[]` 会禁用全局回退）。仅覆盖 `primary` 的 cron 任务仍会继承默认回退，除非你设置 `fallbacks: []`。 +- `params`：按智能体的流参数，合并到 `agents.defaults.models` 中选定的模型条目之上。用于 `cacheRetention`、`temperature` 或 `maxTokens` 之类的智能体特定覆盖，而无需复制整个模型目录。 +- `skills`：可选的每智能体 Skills 允许列表。若省略，则在已设置时继承 `agents.defaults.skills`；显式列表会替换默认值而不是合并，`[]` 表示不启用任何 Skills。 +- `thinkingDefault`：可选的每智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive`）。在未设置每消息或会话覆盖时，会覆盖该智能体的 `agents.defaults.thinkingDefault`。 +- `reasoningDefault`：可选的每智能体默认 reasoning 可见性（`on | off | stream`）。在未设置每消息或会话 reasoning 覆盖时应用。 +- `fastModeDefault`：可选的每智能体默认 fast mode（`true | false`）。在未设置每消息或会话 fast-mode 覆盖时应用。 +- `embeddedHarness`：可选的每智能体底层 harness 策略覆盖。使用 `{ runtime: "codex", fallback: "none" }` 可让某个智能体仅使用 Codex，而其他智能体保留默认 PI 回退。 +- `runtime`：可选的每智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 和 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 +- `identity.avatar`：workspace 相对路径、`http(s)` URL 或 `data:` URI。 +- `identity` 会推导默认值：从 `emoji` 推导 `ackReaction`，从 `name`/`emoji` 推导 `mentionPatterns`。 +- `subagents.allowAgents`：`sessions_spawn` 使用的智能体 ID 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- 沙箱继承保护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝那些将在无沙箱状态下运行的目标。 - `subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认：false）。 --- ## 多智能体路由 -在一个 Gateway 网关 中运行多个彼此隔离的智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。 +在一个 Gateway 网关内运行多个彼此隔离的智能体。参见 [多智能体](/zh-CN/concepts/multi-agent)。 ```json5 { @@ -1688,12 +1676,12 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ### 绑定匹配字段 -- `type`（可选）：普通路由使用 `route`（缺失时默认即为 route），持久 ACP 会话绑定使用 `acp` +- `type`（可选）：`route` 用于普通路由（缺失时默认是 route），`acp` 用于持久 ACP 对话绑定。 - `match.channel`（必填） - `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号） - `match.peer`（可选；`{ kind: direct|group|channel, id }`） - `match.guildId` / `match.teamId`（可选；渠道特定） -- `acp`（可选；仅适用于 `type: "acp"`）：`{ mode, label, cwd, backend }` +- `acp`（可选；仅用于 `type: "acp"`）：`{ mode, label, cwd, backend }` **确定性匹配顺序：** @@ -1701,14 +1689,14 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 2. `match.guildId` 3. `match.teamId` 4. `match.accountId`（精确匹配，无 peer/guild/team） -5. `match.accountId: "*"`（整个渠道范围） +5. `match.accountId: "*"`（全渠道） 6. 默认智能体 在每一层级内，第一个匹配的 `bindings` 条目获胜。 -对于 `type: "acp"` 条目，OpenClaw 会按精确会话身份（`match.channel` + 账号 + `match.peer.id`）解析，不使用上述 route 绑定层级顺序。 +对于 `type: "acp"` 条目，OpenClaw 会按精确的对话身份（`match.channel` + 账号 + `match.peer.id`）进行解析，而不会使用上述 route 绑定层级顺序。 -### 按智能体访问配置 +### 每智能体访问配置 @@ -1803,7 +1791,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 -优先级细节见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 +优先级细节参见 [多智能体沙箱与工具](/zh-CN/tools/multi-agent-sandbox-tools)。 --- @@ -1829,22 +1817,22 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // 超过此 token 数时跳过父线程 fork（0 表示禁用） + parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // 时长或 false - maxDiskBytes: "500mb", // 可选硬预算 - highWaterBytes: "400mb", // 可选清理目标 + resetArchiveRetention: "30d", // duration or false + maxDiskBytes: "500mb", // optional hard budget + highWaterBytes: "400mb", // optional cleanup target }, threadBindings: { enabled: true, - idleHours: 24, // 默认按小时计的非活动自动取消聚焦（`0` 表示禁用） - maxAgeHours: 0, // 默认按小时计的硬性最大存活时长（`0` 表示禁用） + idleHours: 24, // 默认按小时计算的非活动自动取消聚焦（`0` 表示禁用） + maxAgeHours: 0, // 默认按小时计算的硬性最大时长（`0` 表示禁用） }, - mainKey: "main", // 旧版字段（运行时始终使用 "main"） + mainKey: "main", // 旧版（运行时始终使用 "main"） agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1857,34 +1845,34 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 - **`scope`**：群聊上下文的基础会话分组策略。 - - `per-sender`（默认）：在同一渠道上下文中，每个发送者都有独立会话。 - - `global`：同一渠道上下文中的所有参与者共享一个会话（仅在确实需要共享上下文时使用）。 -- **`dmScope`**：私信如何分组。 + - `per-sender`（默认）：在某个渠道上下文内，每个发送者都有彼此隔离的会话。 + - `global`：某个渠道上下文中的所有参与者共享同一个会话（仅在确实希望共享上下文时使用）。 +- **`dmScope`**：私信的分组方式。 - `main`：所有私信共享主会话。 - - `per-peer`：按发送者 id 跨渠道隔离。 + - `per-peer`：按发送者 ID 跨渠道隔离。 - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。 -- **`identityLinks`**：将规范 id 映射到带提供商前缀的对端，以实现跨渠道会话共享。 -- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。若两者都已配置，则以先到期者为准。 +- **`identityLinks`**：将规范 ID 映射到带提供商前缀的对端，用于跨渠道会话共享。 +- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。如果两者都已配置，则以先到期者为准。 - **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。 -- **`parentForkMaxTokens`**：创建 fork 线程会话时允许的父会话 `totalTokens` 上限（默认 `100000`）。 - - 如果父会话的 `totalTokens` 高于该值，OpenClaw 会启动一个全新的线程会话，而不是继承父级转录历史。 - - 设置为 `0` 可禁用此保护，并始终允许父级 fork。 -- **`mainKey`**：旧版字段。运行时始终对主私聊桶使用 `"main"`。 -- **`agentToAgent.maxPingPongTurns`**：智能体之间在智能体对智能体交互期间允许的最大来回回复轮数（整数，范围：`0`–`5`）。`0` 表示禁用 ping-pong 链。 -- **`sendPolicy`**：可按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 可作别名）、`keyPrefix` 或 `rawKeyPrefix` 进行匹配。第一个 deny 优先生效。 +- **`parentForkMaxTokens`**：创建分叉线程会话时，父会话允许的最大 `totalTokens`（默认 `100000`）。 + - 如果父会话的 `totalTokens` 高于该值，OpenClaw 会启动一个新的线程会话，而不是继承父级 transcript 历史。 + - 设为 `0` 可禁用此保护，并始终允许从父级分叉。 +- **`mainKey`**：旧版字段。运行时始终将 `"main"` 用于主私聊桶。 +- **`agentToAgent.maxPingPongTurns`**：智能体之间交换期间，允许的最大来回回复轮次（整数，范围：`0`–`5`）。`0` 会禁用 ping-pong 链接。 +- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 规则优先。 - **`maintenance`**：会话存储清理 + 保留控制。 - - `mode`：`warn` 仅发出警告；`enforce` 实施清理。 - - `pruneAfter`：过期条目的年龄截止值（默认 `30d`）。 - - `maxEntries`：`sessions.json` 中条目的最大数量（默认 `500`）。 + - `mode`：`warn` 仅发出警告；`enforce` 会实际执行清理。 + - `pruneAfter`：陈旧条目的年龄截止值（默认 `30d`）。 + - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。 - `rotateBytes`：当 `sessions.json` 超过该大小时进行轮转（默认 `10mb`）。 - - `resetArchiveRetention`：`*.reset.` 转录归档的保留期。默认等于 `pruneAfter`；设置为 `false` 可禁用。 - - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下仅记录警告；在 `enforce` 模式下会优先移除最旧的产物/会话。 + - `resetArchiveRetention`：`*.reset.` transcript 归档的保留时长。默认与 `pruneAfter` 相同；设为 `false` 可禁用。 + - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先移除最旧的产物/会话。 - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：默认的按小时计非活动自动取消聚焦时间（`0` 表示禁用；提供商可覆盖） - - `maxAgeHours`：默认的按小时计硬性最大存活时长（`0` 表示禁用；提供商可覆盖） + - `idleHours`：默认按小时计算的非活动自动取消聚焦（`0` 表示禁用；提供商可覆盖） + - `maxAgeHours`：默认按小时计算的硬性最大时长（`0` 表示禁用；提供商可覆盖） @@ -1895,7 +1883,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ```json5 { messages: { - responsePrefix: "🦞", // 或 "auto" + responsePrefix: "🦞", // or "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -1910,7 +1898,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, }, inbound: { - debounceMs: 2000, // 0 表示禁用 + debounceMs: 2000, // 0 disables byChannel: { whatsapp: 5000, slack: 1500, @@ -1922,36 +1910,36 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ### 回复前缀 -按渠道/账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 +每渠道/每账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 -解析顺序（最具体者优先）：账号 → 渠道 → 全局。`""` 会禁用并停止继续级联。`"auto"` 会派生为 `[{identity.name}]`。 +解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生为 `[{identity.name}]`。 **模板变量：** -| 变量 | 说明 | 示例 | -| ----------------- | ---------------- | --------------------------- | -| `{model}` | 简短模型名 | `claude-opus-4-6` | -| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | -| `{provider}` | 提供商名称 | `anthropic` | -| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | -| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | +| 变量 | 说明 | 示例 | +| ----------------- | ---------------------- | --------------------------- | +| `{model}` | 简短模型名称 | `claude-opus-4-6` | +| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | +| `{provider}` | 提供商名称 | `anthropic` | +| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | +| `{identity.name}` | 智能体 identity 名称 | （与 `"auto"` 相同） | 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。 -### 确认 reaction +### 确认反应 -- 默认使用活动智能体的 `identity.emoji`，否则为 `"👀"`。设置为 `""` 可禁用。 -- 按渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。 +- 默认使用活动智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。 +- 每渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。 - 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退。 -- 作用域：`group-mentions`（默认）、`group-all`、`direct`、`all`。 -- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上回复后移除 ack。 -- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态 reactions。 - 在 Slack 和 Discord 上，若未设置，当 ack reactions 处于活动状态时会保持状态 reactions 启用。 - 在 Telegram 上，需显式设为 `true` 才会启用生命周期状态 reactions。 +- 作用范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。 +- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上于回复后移除确认反应。 +- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。 + 在 Slack 和 Discord 上，未设置时会在确认反应处于活动状态时保持状态反应启用。 + 在 Telegram 上，必须显式设为 `true` 才会启用生命周期状态反应。 -### 入站去抖 +### 入站防抖 -将来自同一发送者的快速纯文本消息合并为一次智能体轮次。媒体/附件会立即刷新。控制命令会绕过去抖。 +将同一发送者的快速纯文本消息合并为一个智能体轮次。媒体/附件会立即冲刷。控制命令会绕过防抖。 ### TTS（文本转语音） @@ -1994,18 +1982,18 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 } ``` -- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆盖本地偏好，`/tts status` 会显示实际生效状态。 +- `auto` 控制默认的自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆盖本地偏好，`/tts status` 会显示生效状态。 - `summaryModel` 会覆盖用于自动摘要的 `agents.defaults.model.primary`。 -- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认值为 `false`（需显式启用）。 +- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需显式启用）。 - API key 会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。 -- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置值，然后 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。 -- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为 OpenAI 兼容 TTS 服务器，并放宽模型/语音校验。 +- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为：配置，然后 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。 +- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为 OpenAI 兼容 TTS 服务器，并放宽模型/声音验证。 --- ## Talk -Talk 模式的默认值（macOS/iOS/Android）。 +Talk 模式（macOS/iOS/Android）的默认值。 ```json5 { @@ -2030,12 +2018,12 @@ Talk 模式的默认值（macOS/iOS/Android）。 ``` - 当配置了多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的某个键。 -- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，会自动迁移到 `talk.providers.` 中。 +- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容性，会被自动迁移到 `talk.providers.`。 - Voice ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 - `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。 -- 只有在未配置 Talk API key 时，才会使用 `ELEVENLABS_API_KEY` 回退。 -- `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。 -- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多长时间才发送转录。未设置时保持平台默认停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 +- 仅当未配置 Talk API key 时，才会使用 `ELEVENLABS_API_KEY` 回退。 +- `providers.*.voiceAliases` 允许 Talk 指令使用友好的名称。 +- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多久再发送 transcript。未设置时会保留平台默认停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 --- @@ -2043,37 +2031,37 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### 工具配置 -`tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置基础允许列表： +`tools.profile` 会在应用 `tools.allow`/`tools.deny` 之前设置基础允许列表： -本地新手引导在未设置时，会将新的本地配置默认设为 `tools.profile: "coding"`（现有的显式配置会保留）。 +本地新手引导在未设置时，默认将新的本地配置设为 `tools.profile: "coding"`（现有的显式配置会被保留）。 -| 配置 | 包含内容 | -| ----------- | ---------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | 仅 `session_status` | +| 配置 | 包含 | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `minimal` | 仅 `session_status` | | `coding` | `group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`video_generate` | -| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` | -| `full` | 无限制（与未设置相同） | +| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` | +| `full` | 无限制（与未设置相同） | ### 工具组 -| 组 | 工具 | +| 组 | 工具 | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） | -| `group:fs` | `read`、`write`、`edit`、`apply_patch` | +| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） | +| `group:fs` | `read`、`write`、`edit`、`apply_patch` | | `group:sessions` | `sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status` | -| `group:memory` | `memory_search`、`memory_get` | -| `group:web` | `web_search`、`x_search`、`web_fetch` | -| `group:ui` | `browser`、`canvas` | -| `group:automation` | `cron`、`gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`、`image_generate`、`video_generate`、`tts` | -| `group:openclaw` | 所有内置工具（不包括提供商插件） | +| `group:memory` | `memory_search`、`memory_get` | +| `group:web` | `web_search`、`x_search`、`web_fetch` | +| `group:ui` | `browser`、`canvas` | +| `group:automation` | `cron`、`gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`、`image_generate`、`video_generate`、`tts` | +| `group:openclaw` | 所有内置工具（不包括提供商插件） | ### `tools.allow` / `tools.deny` -全局工具允许/拒绝策略（拒绝优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱已关闭也会应用。 +全局工具允许/拒绝策略（deny 优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱已关闭也会生效。 ```json5 { @@ -2083,7 +2071,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.byProvider` -进一步为特定提供商或模型限制工具。顺序：基础配置 → 提供商配置 → allow/deny。 +进一步限制特定提供商或模型可用的工具。顺序：基础配置 → 提供商配置 → allow/deny。 ```json5 { @@ -2115,9 +2103,9 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- 按智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧。 -- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅作用于单条消息。 -- Elevated `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`，当 exec 目标是 `node` 时则为 `node`）。 +- 每智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧。 +- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅应用于单条消息。 +- Elevated `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`，或当 exec 目标为 `node` 时使用 `node`）。 ### `tools.exec` @@ -2141,8 +2129,8 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.loopDetection` -工具循环安全检查默认**关闭**。设置 `enabled: true` 可启用检测。 -设置可在全局 `tools.loopDetection` 中定义，并在按智能体的 `agents.list[].tools.loopDetection` 中覆盖。 +工具循环安全检查**默认禁用**。设置 `enabled: true` 以启用检测。 +设置可在全局 `tools.loopDetection` 中定义，并在每智能体的 `agents.list[].tools.loopDetection` 中覆盖。 ```json5 { @@ -2163,14 +2151,14 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- `historySize`：为循环分析保留的最大工具调用历史。 -- `warningThreshold`：针对重复无进展模式发出警告的阈值。 +- `historySize`：用于循环分析而保留的最大工具调用历史。 +- `warningThreshold`：对重复无进展模式发出警告的阈值。 - `criticalThreshold`：用于阻止严重循环的更高重复阈值。 - `globalCircuitBreakerThreshold`：任何无进展运行的硬停止阈值。 - `detectors.genericRepeat`：对重复的同工具/同参数调用发出警告。 - `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展模式发出警告/阻止。 -- `detectors.pingPong`：对交替出现的无进展配对模式发出警告/阻止。 -- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，则验证失败。 +- `detectors.pingPong`：对交替出现的无进展成对模式发出警告/阻止。 +- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，验证会失败。 ### `tools.web` @@ -2212,7 +2200,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 media: { concurrency: 2, asyncCompletion: { - directSend: false, // 显式启用：将完成的异步音乐/视频直接发送到渠道 + directSend: false, // opt-in：设为 true 可将完成的异步音乐/视频直接发送到该渠道 }, audio: { enabled: true, @@ -2240,9 +2228,9 @@ Talk 模式的默认值（macOS/iOS/Android）。 **提供商条目**（`type: "provider"` 或省略）： -- `provider`：API 提供商 id（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） -- `model`：模型 id 覆盖 -- `profile` / `preferredProfile`：`auth-profiles.json` 配置选择 +- `provider`：API 提供商 ID（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） +- `model`：模型 ID 覆盖 +- `profile` / `preferredProfile`：`auth-profiles.json` 配置文件选择 **CLI 条目**（`type: "cli"`）： @@ -2252,16 +2240,16 @@ Talk 模式的默认值（macOS/iOS/Android）。 **通用字段：** - `capabilities`：可选列表（`image`、`audio`、`video`）。默认值：`openai`/`anthropic`/`minimax` → image，`google` → image+audio+video，`groq` → audio。 -- `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：按条目覆盖。 +- `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：每条目的覆盖。 - 失败时会回退到下一个条目。 -提供商认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 +提供商凭证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 **异步完成字段：** - `asyncCompletion.directSend`：为 `true` 时，已完成的异步 `music_generate` - 和 `video_generate` 任务会优先尝试直接渠道交付。默认值：`false` - （旧版的请求者会话唤醒/模型交付路径）。 + 和 `video_generate` 任务会优先尝试直接渠道投递。默认值：`false` + （旧版请求方会话唤醒/模型投递路径）。 @@ -2280,7 +2268,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.sessions` -控制哪些会话可以被会话工具（`sessions_list`、`sessions_history`、`sessions_send`）作为目标。 +控制会话工具（`sessions_list`、`sessions_history`、`sessions_send`）可将哪些会话作为目标。 默认值：`tree`（当前会话 + 由其派生的会话，例如子智能体）。 @@ -2299,8 +2287,8 @@ Talk 模式的默认值（macOS/iOS/Android）。 - `self`：仅当前会话键。 - `tree`：当前会话 + 由当前会话派生的会话（子智能体）。 -- `agent`：属于当前智能体 id 的任意会话（如果你在同一智能体 id 下运行按发送者区分的会话，可能包含其他用户）。 -- `all`：任意会话。跨智能体目标仍需要 `tools.agentToAgent`。 +- `agent`：属于当前智能体 ID 的任意会话（如果你在同一智能体 ID 下运行按发送者划分的会话，则可能包括其他用户）。 +- `all`：任意会话。跨智能体定向仍需要 `tools.agentToAgent`。 - 沙箱钳制：当当前会话处于沙箱隔离中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 ### `tools.sessions_spawn` @@ -2312,11 +2300,11 @@ Talk 模式的默认值（macOS/iOS/Android）。 tools: { sessions_spawn: { attachments: { - enabled: false, // 显式启用：设为 true 以允许内联文件附件 - maxTotalBytes: 5242880, // 所有文件总计 5 MB + enabled: false, // opt-in：设为 true 以允许内联文件附件 + maxTotalBytes: 5242880, // 所有文件合计 5 MB maxFiles: 50, maxFileBytes: 1048576, // 每个文件 1 MB - retainOnSessionKeep: false, // cleanup="keep" 时保留附件 + retainOnSessionKeep: false, // 当 cleanup="keep" 时保留附件 }, }, }, @@ -2326,15 +2314,15 @@ Talk 模式的默认值（macOS/iOS/Android）。 注意： - 仅 `runtime: "subagent"` 支持附件。ACP 运行时会拒绝它们。 -- 文件会被物化到子 workspace 的 `.openclaw/attachments//` 中，并带有一个 `.manifest.json`。 -- 附件内容会自动从转录持久化中脱敏。 -- Base64 输入会通过严格的字母表/填充检查以及解码前大小保护进行验证。 -- 目录权限为 `0700`，文件权限为 `0600`。 -- 清理由 `cleanup` 策略控制：`delete` 总会移除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留。 +- 文件会以 `.openclaw/attachments//` 的形式实体化到子 workspace 中，并带有 `.manifest.json`。 +- 附件内容会自动从 transcript 持久化中脱敏。 +- Base64 输入会通过严格的字母表/填充校验以及解码前大小保护进行验证。 +- 文件权限为目录 `0700`、文件 `0600`。 +- 清理遵循 `cleanup` 策略：`delete` 总会移除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留。 ### `tools.experimental` -实验性内置工具开关。默认关闭，除非严格 agentic GPT-5 自动启用规则生效。 +实验性内置工具标志。默认关闭，除非适用 strict-agentic GPT-5 自动启用规则。 ```json5 { @@ -2348,9 +2336,9 @@ Talk 模式的默认值（macOS/iOS/Android）。 注意： -- `planTool`：为非平凡的多步骤工作跟踪启用结构化 `update_plan` 工具。 -- 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或按智能体覆盖）对 OpenAI 或 OpenAI Codex GPT-5 系列运行设置为 `"strict-agentic"`。设置为 `true` 可在该范围外强制启用此工具，设置为 `false` 则即使在严格 agentic GPT-5 运行中也保持关闭。 -- 启用后，系统提示还会加入使用指引，以便模型仅在重要工作中使用该工具，并且始终最多只有一个步骤处于 `in_progress`。 +- `planTool`：为非平凡多步骤工作跟踪启用结构化 `update_plan` 工具。 +- 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或每智能体覆盖）被设置为 OpenAI 或 OpenAI Codex GPT-5 系列运行的 `"strict-agentic"`。设为 `true` 可在该范围外强制启用该工具，设为 `false` 则即便在 strict-agentic GPT-5 运行中也保持关闭。 +- 启用后，系统提示还会添加使用指导，以便模型仅在实质性工作中使用它，并始终最多只保留一个 `in_progress` 步骤。 ### `agents.defaults.subagents` @@ -2371,15 +2359,15 @@ Talk 模式的默认值（macOS/iOS/Android）。 ``` - `model`：派生子智能体的默认模型。若省略，子智能体会继承调用方模型。 -- `allowAgents`：当请求智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 默认允许的目标智能体 id 列表（`["*"]` = 任意；默认：仅同一智能体）。 -- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 使用的默认超时（秒）。`0` 表示无超时。 -- 按子智能体工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 +- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 可用的目标智能体 ID 默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 的默认超时时间（秒）。`0` 表示无超时。 +- 每子智能体工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 --- ## 自定义提供商和 base URL -OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义提供商。 +OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义提供商。 ```json5 { @@ -2408,27 +2396,27 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 } ``` -- 使用 `authHeader: true` + `headers` 可满足自定义认证需求。 -- 使用 `OPENCLAW_AGENT_DIR`（或旧版环境变量别名 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。 -- 对于匹配的提供商 ID，合并优先级如下： +- 对于自定义认证需求，使用 `authHeader: true` + `headers`。 +- 使用 `OPENCLAW_AGENT_DIR` 覆盖智能体配置根目录（或使用旧版环境变量别名 `PI_CODING_AGENT_DIR`）。 +- 匹配提供商 ID 的合并优先级： - 非空的智能体 `models.json` `baseUrl` 值优先。 - - 非空的智能体 `apiKey` 值仅在该提供商未在当前配置/auth-profile 上下文中由 SecretRef 管理时优先。 - - 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化已解析的 secret。 - - 由 SecretRef 管理的提供商 header 值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）。 + - 非空的智能体 `apiKey` 值仅在当前配置/auth-profile 上下文中该提供商不是 SecretRef 管理时优先。 + - SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，file/exec 引用使用 `secretref-managed`），而不是持久化已解析的密钥。 + - SecretRef 管理的提供商 header 值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，file/exec 引用使用 `secretref-managed`）。 - 空或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 - 匹配模型的 `contextWindow`/`maxTokens` 会在显式配置值和隐式目录值之间取较高者。 - - 匹配模型的 `contextTokens` 会在存在时保留显式运行时上限；可用它限制有效上下文，而不改变原生模型元数据。 + - 匹配模型的 `contextTokens` 会在存在显式运行时上限时保留该值；可用它限制有效上下文，而不改变原生模型元数据。 - 当你希望配置完全重写 `models.json` 时，使用 `models.mode: "replace"`。 - - 标记持久化以源为准：标记写入自活动源配置快照（解析前），而不是来自已解析的运行时 secret 值。 + - 标记持久化以源为准：标记从活动源配置快照（解析前）写入，而不是从已解析的运行时密钥值写入。 ### 提供商字段详情 - `models.mode`：提供商目录行为（`merge` 或 `replace`）。 -- `models.providers`：按提供商 id 作为键的自定义提供商映射。 +- `models.providers`：按提供商 ID 键控的自定义提供商映射。 - `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。 - `models.providers.*.apiKey`：提供商凭证（优先使用 SecretRef/环境变量替换）。 - `models.providers.*.auth`：认证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。 -- `models.providers.*.injectNumCtxForOpenAICompat`：用于 Ollama + `openai-completions` 时，将 `options.num_ctx` 注入请求中（默认：`true`）。 +- `models.providers.*.injectNumCtxForOpenAICompat`：对于 Ollama + `openai-completions`，将 `options.num_ctx` 注入请求（默认：`true`）。 - `models.providers.*.authHeader`：在需要时强制通过 `Authorization` header 传输凭证。 - `models.providers.*.baseUrl`：上游 API base URL。 - `models.providers.*.headers`：用于代理/租户路由的额外静态 headers。 @@ -2436,20 +2424,20 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 - `request.headers`：额外 headers（与提供商默认值合并）。值接受 SecretRef。 - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用提供商内置认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value` 和可选的 `prefix`）。 - `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（配合 `url`）。两种模式都接受可选的 `tls` 子对象。 - - `request.tls`：直接连接的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（都接受 SecretRef）、`serverName`、`insecureSkipVerify`。 - - `request.allowPrivateNetwork`：为 `true` 时，当 DNS 解析到私有、CGNAT 或类似地址范围时，允许通过提供商 HTTP fetch 防护向 `baseUrl` 发起 HTTPS 请求（这是对受信任自托管 OpenAI 兼容端点的 operator 显式启用项）。WebSocket 会对 headers/TLS 使用相同的 `request`，但不会使用该 fetch SSRF 防护。默认 `false`。 + - `request.tls`：直连的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（均接受 SecretRef）、`serverName`、`insecureSkipVerify`。 + - `request.allowPrivateNetwork`：为 `true` 时，当 DNS 解析到 private、CGNAT 或类似网段时，允许通过提供商 HTTP fetch 保护访问 `baseUrl` 的 HTTPS（供 operator 显式启用，以信任自托管 OpenAI 兼容端点）。WebSocket 对 headers/TLS 使用相同的 `request`，但不使用该 fetch SSRF 防护。默认值为 `false`。 - `models.providers.*.models`：显式提供商模型目录条目。 - `models.providers.*.models.*.contextWindow`：原生模型上下文窗口元数据。 -- `models.providers.*.models.*.contextTokens`：可选的运行时上下文上限。当你希望有效上下文预算小于模型原生 `contextWindow` 时使用此项。 -- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且 `baseUrl` 为非空非原生值（host 不是 `api.openai.com`）的情况，OpenClaw 会在运行时强制将其设为 `false`。空的/省略的 `baseUrl` 会保持默认 OpenAI 行为。 -- `models.providers.*.models.*.compat.requiresStringContent`：针对仅支持字符串的 OpenAI 兼容聊天端点的可选兼容性提示。为 `true` 时，OpenClaw 会在发送请求前，将纯文本 `messages[].content` 数组展平为普通字符串。 -- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根路径。 +- `models.providers.*.models.*.contextTokens`：可选的运行时上下文上限。当你希望有效上下文预算小于模型原生 `contextWindow` 时使用。 +- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选的兼容性提示。对于 `api: "openai-completions"` 且 `baseUrl` 为非空且非原生（主机不是 `api.openai.com`）的情况，OpenClaw 会在运行时强制将其设为 `false`。空的/省略的 `baseUrl` 会保留默认 OpenAI 行为。 +- `models.providers.*.models.*.compat.requiresStringContent`：针对仅接受字符串的 OpenAI 兼容聊天端点的可选兼容性提示。为 `true` 时，OpenClaw 会在发送请求前将纯文本 `messages[].content` 数组扁平化为普通字符串。 +- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根节点。 - `plugins.entries.amazon-bedrock.config.discovery.enabled`：打开/关闭隐式发现。 - `plugins.entries.amazon-bedrock.config.discovery.region`：用于发现的 AWS 区域。 - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：用于定向发现的可选 provider-id 过滤器。 - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`：发现刷新的轮询间隔。 -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：已发现模型的后备上下文窗口。 -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：已发现模型的后备最大输出 token 数。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：发现模型的回退上下文窗口。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：发现模型的回退最大输出 token 数。 ### 提供商示例 @@ -2465,8 +2453,8 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 fallbacks: ["cerebras/zai-glm-4.6"], }, models: { - "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" }, - "cerebras/zai-glm-4.6": { alias: "GLM 4.6 (Cerebras)" }, + "cerebras/zai-glm-4.7": { alias: "GLM 4.7（Cerebras）" }, + "cerebras/zai-glm-4.6": { alias: "GLM 4.6（Cerebras）" }, }, }, }, @@ -2478,8 +2466,8 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 apiKey: "${CEREBRAS_API_KEY}", api: "openai-completions", models: [ - { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" }, - { id: "zai-glm-4.6", name: "GLM 4.6 (Cerebras)" }, + { id: "zai-glm-4.7", name: "GLM 4.7（Cerebras）" }, + { id: "zai-glm-4.6", name: "GLM 4.6（Cerebras）" }, ], }, }, @@ -2487,7 +2475,7 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 } ``` -对 Cerebras 使用 `cerebras/zai-glm-4.7`；对 Z.AI 直连使用 `zai/glm-4.7`。 +Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。 @@ -2504,7 +2492,7 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 } ``` -设置 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。对 Zen 目录使用 `opencode/...` 引用，对 Go 目录使用 `opencode-go/...` 引用。快捷方式：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。 +设置 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。Zen 目录使用 `opencode/...` 引用，Go 目录使用 `opencode-go/...` 引用。快捷方式：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。 @@ -2521,10 +2509,10 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 } ``` -设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 都是接受的别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。 +设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 都是可接受的别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。 - 通用端点：`https://api.z.ai/api/paas/v4` -- Coding 端点（默认）：`https://api.z.ai/api/coding/paas/v4` +- 编码端点（默认）：`https://api.z.ai/api/coding/paas/v4` - 对于通用端点，请定义带有 base URL 覆盖的自定义提供商。 @@ -2564,11 +2552,11 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 } ``` -对于中国区端点：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。 +中国端点：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。 原生 Moonshot 端点会在共享的 -`openai-completions` 传输上声明流式使用兼容性，OpenClaw 会基于端点能力 -而不只是基于内置 provider id 本身来决定相关行为。 +`openai-completions` 传输上声明流式传输使用兼容性，OpenClaw 会基于端点能力 +而不只是内置提供商 ID 本身来做判断。 @@ -2669,8 +2657,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 `openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。 模型目录默认仅包含 M2.7。 -在 Anthropic 兼容的流式路径上，OpenClaw 默认会禁用 MiniMax thinking， -除非你显式自行设置 `thinking`。`/fast on` 或 +在 Anthropic 兼容的流式传输路径上，除非你显式设置 `thinking`，否则 OpenClaw 默认会禁用 MiniMax thinking。`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 @@ -2678,7 +2665,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 -参见 [Local Models](/zh-CN/gateway/local-models)。简要说明：在性能足够强的硬件上，通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。 +参见 [本地模型](/zh-CN/gateway/local-models)。简而言之：在性能较强的硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。 @@ -2709,14 +2696,12 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 } ``` -- `allowBundled`：仅针对内置 Skills 的可选允许列表（托管/workspace Skills 不受影响）。 -- `load.extraDirs`：额外的共享 Skills 根目录（最低优先级）。 -- `install.preferBrew`：为 true 时，若 `brew` 可用，则优先使用 Homebrew 安装器，再回退到其他安装器类型。 -- `install.nodeManager`：用于 `metadata.openclaw.install` - 规范的 node 安装器偏好 - （`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false`：即使 Skill 已内置/已安装，也会禁用它。 -- `entries..apiKey`：为声明主环境变量的 Skills 提供便捷设置（明文字符串或 SecretRef 对象）。 +- `allowBundled`：仅对内置 Skills 生效的可选允许列表（managed/workspace Skills 不受影响）。 +- `load.extraDirs`：额外的共享 Skills 根目录（优先级最低）。 +- `install.preferBrew`：为 true 时，在 `brew` 可用的情况下优先使用 Homebrew 安装器，然后才回退到其他安装器类型。 +- `install.nodeManager`：用于 `metadata.openclaw.install` 规范的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false`：即使 Skill 已内置/已安装，也会将其禁用。 +- `entries..apiKey`：为声明了主环境变量的 Skills 提供的便捷项（明文字符串或 SecretRef 对象）。 --- @@ -2745,42 +2730,42 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 ``` - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 -- 设备发现接受原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 +- 发现机制接受原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 - **配置变更需要重启 Gateway 网关。** -- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先生效。 -- `plugins.entries..apiKey`：插件级 API key 便捷字段（当插件支持时）。 +- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。 +- `plugins.entries..apiKey`：插件级 API key 便捷字段（在插件支持时）。 - `plugins.entries..env`：插件作用域环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hooks 以及受支持的 bundle 提供 hook 目录。 -- `plugins.entries..subagent.allowModelOverride`：显式信任此插件可以为后台子智能体运行请求按次覆盖 `provider` 和 `model`。 -- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖可用的规范 `provider/model` 目标可选允许列表。仅当你确实希望允许任意模型时才使用 `"*"`。 -- `plugins.entries..config`：插件定义的配置对象（在可用时由原生 OpenClaw 插件 schema 验证）。 -- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web-fetch 提供商设置。 +- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会变更提示的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hooks 以及受支持的 bundle 提供的 hook 目录。 +- `plugins.entries..subagent.allowModelOverride`：显式信任该插件可为后台子智能体运行请求按次运行的 `provider` 和 `model` 覆盖。 +- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖可用的规范 `provider/model` 目标可选允许列表。仅当你有意允许任意模型时才使用 `"*"`。 +- `plugins.entries..config`：插件定义的配置对象（若可用，会由原生 OpenClaw 插件 schema 验证）。 +- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web fetch 提供商设置。 - `apiKey`：Firecrawl API key（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。 - `baseUrl`：Firecrawl API base URL（默认：`https://api.firecrawl.dev`）。 - `onlyMainContent`：仅提取页面主体内容（默认：`true`）。 - - `maxAgeMs`：缓存最大年龄（毫秒，默认：`172800000` / 2 天）。 + - `maxAgeMs`：缓存最大年龄（毫秒）（默认：`172800000` / 2 天）。 - `timeoutSeconds`：抓取请求超时秒数（默认：`60`）。 - `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web 搜索）设置。 - `enabled`：启用 X Search 提供商。 - - `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。 -- `plugins.entries.memory-core.config.dreaming`：memory dreaming（实验性）设置。阶段和阈值见 [Dreaming](/zh-CN/concepts/dreaming)。 - - `enabled`：dreaming 总开关（默认 `false`）。 - - `frequency`：每次完整 dreaming 扫描的 cron 频率（默认 `"0 3 * * *"`）。 + - `model`：搜索使用的 Grok 模型（例如 `"grok-4-1-fast"`）。 +- `plugins.entries.memory-core.config.dreaming`：memory dreaming 设置。阶段和阈值参见 [Dreaming](/zh-CN/concepts/dreaming)。 + - `enabled`：dreaming 主开关（默认 `false`）。 + - `frequency`：每次完整 dreaming 扫描的 cron 周期（默认 `"0 3 * * *"`）。 - 阶段策略和阈值属于实现细节（不是面向用户的配置键）。 -- 完整 memory 配置见 [Memory configuration reference](/zh-CN/reference/memory-config)： +- 完整 memory 配置位于 [Memory 配置参考](/zh-CN/reference/memory-config)： - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- 已启用的 Claude bundle 插件也可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为已清理的智能体设置来应用，而不是作为原始 OpenClaw 配置补丁。 -- `plugins.slots.memory`：选择活动 memory 插件 id，或设为 `"none"` 以禁用 memory 插件。 -- `plugins.slots.contextEngine`：选择活动上下文引擎插件 id；默认是 `"legacy"`，除非你安装并选择了其他引擎。 -- `plugins.installs`：由 CLI 管理的安装元数据，供 `openclaw plugins update` 使用。 +- 已启用的 Claude bundle 插件也可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为已净化的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。 +- `plugins.slots.memory`：选择活动 memory 插件 ID，或使用 `"none"` 禁用 memory 插件。 +- `plugins.slots.contextEngine`：选择活动上下文引擎插件 ID；默认值为 `"legacy"`，除非你安装并选择了其他引擎。 +- `plugins.installs`：CLI 管理的安装元数据，供 `openclaw plugins update` 使用。 - 包含 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。 - - 请将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，不要手动编辑。 + - 将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。 -参见 [Plugins](/zh-CN/tools/plugin)。 +参见 [插件](/zh-CN/tools/plugin)。 --- @@ -2793,7 +2778,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // 仅在你信任私有网络访问时显式启用 + // dangerouslyAllowPrivateNetwork: true, // 仅在信任 private-network 访问时显式启用 // allowPrivateNetwork: true, // 旧版别名 // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], @@ -2821,27 +2806,27 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 ``` - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 未设置时为禁用，因此浏览器导航默认保持严格模式。 -- 只有在你明确确信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 -- 在严格模式下，远程 CDP 配置端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间也会受到同样的私有网络阻止。 -- `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受到支持。 -- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 可为特定主机添加显式例外。 -- 远程配置为仅附加模式（禁用启动/停止/重置）。 +- 未设置时，`ssrfPolicy.dangerouslyAllowPrivateNetwork` 为禁用，因此浏览器导航默认保持严格模式。 +- 仅当你明确相信 private-network 浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 +- 在严格模式下，远程 CDP 配置端点（`profiles.*.cdpUrl`）在可达性/发现检查期间也会受到相同的 private-network 阻止。 +- `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 +- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 作为显式例外。 +- 远程配置是仅附加模式（禁用 start/stop/reset）。 - `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。 - 当你希望 OpenClaw 通过 `/json/version` 进行设备发现时，请使用 HTTP(S)； - 当你的提供商直接给出 DevTools WebSocket URL 时，请使用 WS(S)。 -- `existing-session` 配置仅适用于主机，并使用 Chrome MCP 而不是 CDP。 -- `existing-session` 配置可设置 `userDataDir` 以定位特定的 - Chromium 内核浏览器用户配置，例如 Brave 或 Edge。 + 当你希望 OpenClaw 发现 `/json/version` 时，使用 HTTP(S)； + 当提供商直接给出 DevTools WebSocket URL 时，使用 WS(S)。 +- `existing-session` 配置仅适用于主机，并使用 Chrome MCP 而非 CDP。 +- `existing-session` 配置可设置 `userDataDir`，以指定具体的 + Chromium 系浏览器配置文件，例如 Brave 或 Edge。 - `existing-session` 配置保留当前 Chrome MCP 路由限制： - 基于快照/引用的操作，而非 CSS 选择器定位；单文件上传 - hooks；无对话框超时覆盖；无 `wait --load networkidle`，以及无 + 基于 snapshot/ref 的操作而非 CSS 选择器定向、单文件上传 hook、 + 不支持对话框超时覆盖、不支持 `wait --load networkidle`，以及不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 -- 本地托管的 `openclaw` 配置会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 场景下才需要显式设置 `cdpUrl`。 -- 自动检测顺序：默认浏览器若为 Chromium 内核 → Chrome → Brave → Edge → Chromium → Chrome Canary。 -- Control 服务：仅绑定 loopback（端口由 `gateway.port` 派生，默认 `18791`）。 -- `extraArgs` 会将额外启动参数附加到本地 Chromium 启动命令中（例如 - `--disable-gpu`、窗口大小设置或调试参数）。 +- 本地托管的 `openclaw` 配置会自动分配 `cdpPort` 和 `cdpUrl`；仅对远程 CDP 显式设置 `cdpUrl`。 +- 自动检测顺序：默认浏览器（若为 Chromium 系）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 +- 控制服务：仅 loopback（端口由 `gateway.port` 派生，默认 `18791`）。 +- `extraArgs` 会向本地 Chromium 启动追加额外标志（例如 + `--disable-gpu`、窗口大小设置或调试标志）。 --- @@ -2853,14 +2838,14 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji、短文本、图片 URL 或 data URI + avatar: "CB", // emoji, short text, image URL, or data URI }, }, } ``` -- `seamColor`：原生应用 UI 外观的强调色（Talk 模式气泡色调等）。 -- `assistant`：Control UI 身份覆盖。会回退到活动智能体身份。 +- `seamColor`：原生应用 UI 外观的强调色（Talk 模式气泡着色等）。 +- `assistant`：Control UI identity 覆盖。会回退到当前活动智能体 identity。 --- @@ -2876,7 +2861,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 mode: "token", // none | token | password | trusted-proxy token: "your-token", // password: "your-password", // 或 OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // 用于 mode=trusted-proxy；参见 /gateway/trusted-proxy-auth + // trustedProxy: { userHeader: "x-forwarded-user" }, // 用于 mode=trusted-proxy；见 /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -2895,7 +2880,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 // root: "dist/control-ui", // embedSandbox: "scripts", // strict | scripts | trusted // allowExternalEmbedUrls: false, // 危险：允许绝对外部 http(s) 嵌入 URL - // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必填 + // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必需 // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host-header origin 回退模式 // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, @@ -2910,9 +2895,9 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 // 可选。默认 false。 allowRealIpFallback: false, tools: { - // 对 /tools/invoke HTTP 的额外拒绝项 + // 额外的 /tools/invoke HTTP deny deny: ["browser"], - // 从默认 HTTP 拒绝列表中移除工具 + // 从默认 HTTP deny 列表中移除工具 allow: ["gateway"], }, push: { @@ -2930,63 +2915,63 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 - `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关会拒绝启动。 -- `port`：WS + HTTP 共用的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 +- `port`：WS + HTTP 的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 - `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。 -- **旧版 bind 别名**：在 `gateway.bind` 中请使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 -- **Docker 注意事项**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。在 Docker bridge 网络（`-p 18789:18789`）下，流量会到达 `eth0`，因此 Gateway 网关 不可达。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 并设置 `customBindHost: "0.0.0.0"`）以监听所有接口。 -- **认证**：默认必需。非 loopback 绑定要求使用 Gateway 网关认证。实际意味着需要共享 token/password，或使用带 `gateway.auth.mode: "trusted-proxy"` 的身份感知型反向代理。新手引导向导默认会生成 token。 -- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），必须显式设置 `gateway.auth.mode` 为 `token` 或 `password`。若两者都已配置但未设置 mode，启动以及服务安装/修复流程都会失败。 -- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的本地 local loopback 场景；新手引导提示中不会提供此选项。 -- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知型反向代理，并信任来自 `gateway.trustedProxies` 的身份 headers（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 的代理来源；同主机 loopback 反向代理不满足 trusted-proxy 认证条件。 -- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份 headers 可用于满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale header 认证；它们仍遵循 Gateway 网关 的常规 HTTP 认证模式。此无 token 流程假定 Gateway 网关 主机受信任。当 `tailscale.mode = "serve"` 时默认值为 `true`。 -- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证作用域生效（共享 secret 和设备 token 会分别跟踪）。被阻止的尝试返回 `429` + `Retry-After`。 - - 在异步的 Tailscale Serve Control UI 路径上，来自相同 `{scope, clientIp}` 的失败尝试会在写入失败记录前被串行化。因此，同一客户端的并发错误尝试可能会在第二个请求时触发限流，而不是两个都作为普通不匹配同时穿过。 - - `gateway.auth.rateLimit.exemptLoopback` 默认值为 `true`；如果你明确希望 localhost 流量也被限流（例如测试环境或严格代理部署），请设为 `false`。 -- 来自浏览器源的 WS 认证尝试始终会在关闭 loopback 豁免的情况下进行限流（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。 +- **旧版 bind 别名**：请在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），而不是主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 +- **Docker 注意事项**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量从 `eth0` 到达，因此 Gateway 网关不可达。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 并搭配 `customBindHost: "0.0.0.0"`）以在所有接口上监听。 +- **Auth**：默认必需。非 loopback bind 需要 Gateway 网关身份验证。实际使用中，这意味着共享 token/password，或配合 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成 token。 +- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式设置 `gateway.auth.mode` 为 `token` 或 `password`。当两者都已配置但未设置 mode 时，启动和服务安装/修复流程都会失败。 +- `gateway.auth.mode: "none"`：显式无身份验证模式。仅用于可信的本地 local loopback 设置；新手引导提示中不会提供此选项。 +- `gateway.auth.mode: "trusted-proxy"`：将身份验证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的 identity headers（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。该模式要求**非 loopback** 的代理来源；同主机 loopback 反向代理不满足 trusted-proxy 身份验证条件。 +- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve identity headers 可满足 Control UI/WebSocket 身份验证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale header 身份验证；它们仍遵循 Gateway 网关常规 HTTP auth 模式。此无 token 流程假定 Gateway 网关主机是可信的。当 `tailscale.mode = "serve"` 时默认值为 `true`。 +- `gateway.auth.rateLimit`：可选的身份验证失败限制器。按客户端 IP 和 auth scope 生效（共享密钥和设备 token 会分别跟踪）。被阻止的尝试返回 `429` + `Retry-After`。 + - 在异步 Tailscale Serve Control UI 路径上，对于相同 `{scope, clientIp}` 的失败尝试，会在写入失败记录前串行化。因此，同一客户端的并发错误尝试可能会在第二个请求时触发限制器，而不是两个请求都作为普通不匹配同时通过。 + - `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；如果你有意希望 localhost 流量也受速率限制（用于测试设置或严格代理部署），请设为 `false`。 +- 来自浏览器源的 WS 身份验证尝试始终会应用限流，且 loopback 豁免被禁用（作为对抗基于浏览器的 localhost 暴力破解的纵深防御）。 - 在 loopback 上，这些来自浏览器源的锁定会按规范化后的 `Origin` - 值彼此隔离，因此某个 localhost origin 的重复失败不会自动 + 值彼此隔离，因此来自某个 localhost origin 的重复失败不会自动 锁定另一个 origin。 -- `tailscale.mode`：`serve`（仅 tailnet，loopback 绑定）或 `funnel`（公网，需要认证）。 -- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器源允许列表。当预期浏览器客户端来自非 loopback 源时为必填。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为刻意依赖 Host-header origin 策略的部署启用 Host-header origin 回退。 -- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧的紧急放行覆盖，允许对受信任私有网络 IP 使用明文 `ws://`；默认情况下明文仍仅限 loopback。 -- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身并不会配置 Gateway 网关认证。 -- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建在将基于 relay 的注册发布到 Gateway 网关 后，供其使用的外部 APNs relay 的基础 HTTPS URL。该 URL 必须与编译进 iOS 构建中的 relay URL 一致。 -- `gateway.push.apns.relay.timeoutMs`：Gateway 网关 向 relay 发送时的超时，单位毫秒。默认值：`10000`。 -- 基于 relay 的注册会委派给某个特定 Gateway 网关 身份。已配对的 iOS 应用会调用 `gateway.identity.get`，在 relay 注册中包含该身份，并向 Gateway 网关 转发一个作用于该注册的发送授权。其他 Gateway 网关 无法复用已存储的该注册。 +- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公开，需要身份验证）。 +- `controlUi.allowedOrigins`：Gateway 网关 WebSocket 连接的显式浏览器源允许列表。当预期浏览器客户端来自非 loopback 源时必须设置。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host header origin 策略的部署启用 Host header origin 回退。 +- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须为 `ws://` 或 `wss://`。 +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧的紧急开关覆盖，允许对受信任的 private-network IP 使用明文 `ws://`；默认情况下，明文仍仅限于 loopback。 +- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身并不会配置 Gateway 网关 auth。 +- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建在向 Gateway 网关发布基于 relay 的注册后，所使用的外部 APNs relay 的基础 HTTPS URL。该 URL 必须与编译进 iOS 构建中的 relay URL 一致。 +- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时时间（毫秒）。默认值为 `10000`。 +- 基于 relay 的注册会委托给特定的 Gateway 网关 identity。已配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该 identity，并将作用于该注册的发送授权转发给 Gateway 网关。另一个 Gateway 网关不能复用该已存储注册。 - `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述 relay 配置的临时环境变量覆盖。 -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅供开发使用的放行开关，用于 loopback HTTP relay URL。生产环境的 relay URL 应保持为 HTTPS。 +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅开发环境使用的逃逸开关，用于 loopback HTTP relay URL。生产 relay URL 应保持为 HTTPS。 - `gateway.channelHealthCheckMinutes`：渠道健康监控间隔（分钟）。设为 `0` 可全局禁用健康监控重启。默认值：`5`。 -- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。请保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 -- `gateway.channelMaxRestartsPerHour`：滚动一小时内每个渠道/账号最多允许的健康监控重启次数。默认值：`10`。 -- `channels..healthMonitor.enabled`：在保持全局监控启用的同时，对某个渠道禁用健康监控重启。 +- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。应保持大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 +- `gateway.channelMaxRestartsPerHour`：滚动一小时内每个渠道/账号的最大健康监控重启次数。默认值：`10`。 +- `channels..healthMonitor.enabled`：在保持全局监控启用的同时，按渠道选择退出健康监控重启。 - `channels..accounts..healthMonitor.enabled`：多账号渠道的按账号覆盖。设置后，其优先级高于渠道级覆盖。 -- 本地 Gateway 网关 调用路径仅在 `gateway.auth.*` 未设置时，才可将 `gateway.remote.*` 作为回退。 -- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但无法解析，将按默认拒绝方式失败（不会被远程回退掩盖）。 -- `trustedProxies`：会终止 TLS 或注入 forwarded-client headers 的反向代理 IP。只列出你控制的代理。loopback 条目对于同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理）仍然有效，但它们**不会**让 loopback 请求有资格使用 `gateway.auth.mode: "trusted-proxy"`。 -- `allowRealIpFallback`：为 `true` 时，当缺少 `X-Forwarded-For` 时，Gateway 网关 会接受 `X-Real-IP`。默认 `false`，以保持默认拒绝。 -- `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 额外阻止的工具名（扩展默认拒绝列表）。 -- `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名。 +- 仅当 `gateway.auth.*` 未设置时，本地 Gateway 网关调用路径才能使用 `gateway.remote.*` 作为回退。 +- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password`，但未解析成功，则解析会失败并保持关闭状态（不会由远程回退掩盖）。 +- `trustedProxies`：终止 TLS 或注入转发客户端 headers 的反向代理 IP。仅列出你控制的代理。loopback 条目对同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理）仍然有效，但它们**不会**让 loopback 请求有资格使用 `gateway.auth.mode: "trusted-proxy"`。 +- `allowRealIpFallback`：为 `true` 时，在缺少 `X-Forwarded-For` 时 Gateway 网关接受 `X-Real-IP`。默认值为 `false`，以保持默认拒绝行为。 +- `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 额外阻止的工具名（在默认 deny 列表基础上扩展）。 +- `gateway.tools.allow`：从默认 HTTP deny 列表中移除工具名。 ### OpenAI 兼容端点 -- Chat Completions：默认禁用。通过 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。 +- Chat Completions：默认禁用。使用 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。 - Responses API：`gateway.http.endpoints.responses.enabled`。 - Responses URL 输入加固： - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - 空允许列表会被视为未设置；如需禁用 URL 抓取，请使用 `gateway.http.endpoints.responses.files.allowUrl=false` + 空 allowlist 会被视为未设置；如需禁用 URL 获取，请使用 `gateway.http.endpoints.responses.files.allowUrl=false` 和/或 `gateway.http.endpoints.responses.images.allowUrl=false`。 -- 可选的响应加固 header： +- 可选响应加固 header： - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS 源设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） ### 多实例隔离 -在同一主机上运行多个 Gateway 网关，并为其配置唯一端口和状态目录： +在同一主机上运行多个 Gateway 网关，并使用不同端口和状态目录： ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -2994,9 +2979,9 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \ openclaw gateway --port 19001 ``` -便捷参数：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`）、`--profile `（使用 `~/.openclaw-`）。 +便捷标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`）、`--profile `（使用 `~/.openclaw-`）。 -参见 [Multiple Gateways](/zh-CN/gateway/multiple-gateways)。 +参见 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。 ### `gateway.tls` @@ -3014,11 +2999,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`：在 Gateway 网关 监听器处启用 TLS 终止（HTTPS/WSS）（默认：`false`）。 -- `autoGenerate`：在未配置显式文件时自动生成本地自签名证书/密钥对；仅适用于本地/开发环境。 +- `enabled`：在 Gateway 网关监听器上启用 TLS 终止（HTTPS/WSS）（默认：`false`）。 +- `autoGenerate`：当未配置显式文件时，自动生成本地自签名证书/密钥对；仅用于本地/开发环境。 - `certPath`：TLS 证书文件的文件系统路径。 -- `keyPath`：TLS 私钥文件的文件系统路径；请限制其权限。 -- `caPath`：用于客户端验证或自定义信任链的可选 CA bundle 路径。 +- `keyPath`：TLS 私钥文件的文件系统路径；应限制权限。 +- `caPath`：可选的 CA bundle 路径，用于客户端验证或自定义信任链。 ### `gateway.reload` @@ -3034,13 +3019,13 @@ openclaw gateway --port 19001 } ``` -- `mode`：控制配置编辑在运行时如何应用。 - - `"off"`：忽略实时编辑；更改需要显式重启。 - - `"restart"`：配置更改时始终重启 Gateway 网关 进程。 - - `"hot"`：无需重启，在进程内直接应用更改。 - - `"hybrid"`（默认）：先尝试热重载；必要时回退到重启。 -- `debounceMs`：应用配置更改前的去抖窗口（毫秒，非负整数）。 -- `deferralTimeoutMs`：在强制重启前等待进行中操作完成的最长时间（毫秒，默认：`300000` = 5 分钟）。 +- `mode`：控制运行时如何应用配置编辑。 + - `"off"`：忽略实时编辑；变更需要显式重启。 + - `"restart"`：配置变更时始终重启 Gateway 网关进程。 + - `"hot"`：在不重启的情况下于进程内应用变更。 + - `"hybrid"`（默认）：先尝试热重载；如有需要则回退为重启。 +- `debounceMs`：应用配置变更前的防抖窗口（毫秒）（非负整数）。 +- `deferralTimeoutMs`：在强制重启前等待正在进行操作完成的最长时间（毫秒）（默认：`300000` = 5 分钟）。 --- @@ -3067,7 +3052,7 @@ openclaw gateway --port 19001 wakeMode: "now", name: "Gmail", sessionKey: "hook:gmail:{{messages[0].id}}", - messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}", + messageTemplate: "发件人：{{messages[0].from}}\n主题：{{messages[0].subject}}\n{{messages[0].snippet}}", deliver: true, channel: "last", model: "openai/gpt-5.4-mini", @@ -3077,37 +3062,37 @@ openclaw gateway --port 19001 } ``` -认证：`Authorization: Bearer ` 或 `x-openclaw-token: `。 -拒绝使用查询字符串 hook token。 +身份验证：`Authorization: Bearer ` 或 `x-openclaw-token: `。 +拒绝使用查询字符串中的 hook token。 验证和安全说明： - `hooks.enabled=true` 需要非空的 `hooks.token`。 -- `hooks.token` 必须与 `gateway.auth.token` **不同**；拒绝复用 Gateway 网关 token。 +- `hooks.token` 必须与 `gateway.auth.token` **不同**；重用 Gateway 网关 token 会被拒绝。 - `hooks.path` 不能是 `/`；请使用专用子路径，例如 `/hooks`。 -- 如果 `hooks.allowRequestSessionKey=true`，请限制 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 +- 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 **端点：** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - 只有当 `hooks.allowRequestSessionKey=true`（默认：`false`）时，才接受请求负载中的 `sessionKey`。 + - 仅当 `hooks.allowRequestSessionKey=true`（默认：`false`）时，才接受请求负载中的 `sessionKey`。 - `POST /hooks/` → 通过 `hooks.mappings` 解析 - `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 - `match.source` 匹配通用路径中的某个负载字段。 -- 像 `{{messages[0].subject}}` 这样的模板会从负载中读取值。 -- `transform` 可指向一个返回 hook action 的 JS/TS 模块。 - - `transform.module` 必须是相对路径，并且保持在 `hooks.transformsDir` 内（绝对路径和路径遍历都会被拒绝）。 -- `agentId` 会路由到特定智能体；未知 id 会回退到默认智能体。 +- 类似 `{{messages[0].subject}}` 的模板会从负载中读取。 +- `transform` 可以指向返回 hook 动作的 JS/TS 模块。 + - `transform.module` 必须是相对路径，并保持在 `hooks.transformsDir` 内（绝对路径和路径遍历会被拒绝）。 +- `agentId` 会路由到特定智能体；未知 ID 会回退到默认值。 - `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 全部拒绝）。 -- `defaultSessionKey`：用于没有显式 `sessionKey` 的 hook 智能体运行的可选固定会话键。 +- `defaultSessionKey`：hook 智能体运行在未显式提供 `sessionKey` 时使用的可选固定会话键。 - `allowRequestSessionKey`：允许 `/hooks/agent` 调用方设置 `sessionKey`（默认：`false`）。 -- `allowedSessionKeyPrefixes`：用于显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。 +- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。 - `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。 -- `model` 会覆盖此次 hook 运行使用的 LLM（如果设置了模型目录，则该模型必须被允许）。 +- `model` 会为该次 hook 运行覆盖 LLM（若已设置模型目录，则该模型必须被允许）。 @@ -3134,8 +3119,8 @@ openclaw gateway --port 19001 } ``` -- 配置后，Gateway 网关 会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。 -- 不要在 Gateway 网关 旁边单独运行另一个 `gog gmail watch serve`。 +- 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。 +- 不要在 Gateway 网关旁边单独运行另一个 `gog gmail watch serve`。 --- @@ -3151,17 +3136,17 @@ openclaw gateway --port 19001 } ``` -- 通过 Gateway 网关 端口，在 HTTP 下提供可由智能体编辑的 HTML/CSS/JS 和 A2UI： +- 通过 Gateway 网关端口下的 HTTP 提供由智能体可编辑的 HTML/CSS/JS 和 A2UI： - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - 仅限本地：保持 `gateway.bind: "loopback"`（默认）。 -- 非 loopback 绑定：canvas 路由与其他 Gateway 网关 HTTP 层面相同，需要 Gateway 网关认证（token/password/trusted-proxy）。 -- Node WebViews 通常不会发送认证 headers；在某个节点完成配对并连接后，Gateway 网关 会为 canvas/A2UI 访问广播节点作用域的 capability URL。 -- Capability URL 绑定到当前活动节点的 WS 会话，并且很快过期。不使用基于 IP 的回退。 -- 会向已提供的 HTML 注入 live-reload 客户端。 -- 为空时会自动创建初始 `index.html`。 -- 也会在 `/__openclaw__/a2ui/` 提供 A2UI。 -- 更改需要重启 Gateway 网关。 +- 非 loopback bind：canvas 路由和其他 Gateway 网关 HTTP 面一样需要 Gateway auth（token/password/trusted-proxy）。 +- Node WebView 通常不会发送 auth headers；在某个 node 配对并连接后，Gateway 网关会为 canvas/A2UI 访问发布 node 作用域 capability URL。 +- Capability URL 绑定到活动 node WS 会话，并且很快过期。不使用基于 IP 的回退。 +- 向已提供的 HTML 中注入 live-reload 客户端。 +- 当目录为空时会自动创建起始 `index.html`。 +- 同时在 `/__openclaw__/a2ui/` 提供 A2UI。 +- 变更需要重启 Gateway 网关。 - 对于大型目录或 `EMFILE` 错误，请禁用 live reload。 --- @@ -3182,9 +3167,9 @@ openclaw gateway --port 19001 - `minimal`（默认）：在 TXT 记录中省略 `cliPath` + `sshPort`。 - `full`：包含 `cliPath` + `sshPort`。 -- 主机名默认为 `openclaw`。可通过 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 +- 主机名默认为 `openclaw`。使用 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 -### 广域网（DNS-SD） +### 广域（DNS-SD） ```json5 { @@ -3194,7 +3179,7 @@ openclaw gateway --port 19001 } ``` -会在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。若需跨网络设备发现，请搭配 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS。 +在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。若需跨网络设备发现，请配合 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS。 设置：`openclaw dns setup --apply`。 @@ -3221,12 +3206,12 @@ openclaw gateway --port 19001 - 仅当进程环境中缺少该键时，才会应用内联环境变量。 - `.env` 文件：当前工作目录 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 -- `shellEnv`：从你的登录 shell 配置中导入缺失的预期键名。 -- 完整优先级见 [Environment](/zh-CN/help/environment)。 +- `shellEnv`：从你的登录 shell 配置文件中导入缺失的预期键名。 +- 完整优先级参见 [环境](/zh-CN/help/environment)。 ### 环境变量替换 -可在任意配置字符串中使用 `${VAR_NAME}` 引用环境变量： +在任意配置字符串中用 `${VAR_NAME}` 引用环境变量： ```json5 { @@ -3237,39 +3222,39 @@ openclaw gateway --port 19001 ``` - 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。 -- 缺失/空变量会在配置加载时报错。 +- 缺失/为空的变量会在配置加载时报错。 - 使用 `$${VAR}` 可转义为字面量 `${VAR}`。 -- 适用于 `$include`。 +- 可与 `$include` 一起使用。 --- -## Secrets +## 密钥 -Secret refs 是增量支持：明文值仍然可用。 +SecretRef 是增量支持：明文值仍然可用。 ### `SecretRef` -使用以下对象形态： +使用以下对象结构之一： ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } ``` -校验规则： +验证： - `provider` 模式：`^[a-z][a-z0-9_-]{0,63}$` - `source: "env"` 的 id 模式：`^[A-Z][A-Z0-9_]{0,127}$` - `source: "file"` 的 id：绝对 JSON pointer（例如 `"/providers/openai/apiKey"`） - `source: "exec"` 的 id 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `source: "exec"` 的 id 不能包含 `.` 或 `..` 的斜杠分隔路径段（例如 `a/../b` 会被拒绝） +- `source: "exec"` 的 id 不能包含 `.` 或 `..` 形式的斜杠分隔路径段（例如 `a/../b` 会被拒绝） -### 支持的凭证层面 +### 支持的凭证面 -- 规范矩阵： [SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface) -- `secrets apply` 以受支持的 `openclaw.json` 凭证路径为目标。 -- `auth-profiles.json` refs 也包含在运行时解析和审计覆盖中。 +- 规范矩阵：[SecretRef 凭证面](/zh-CN/reference/secretref-credential-surface) +- `secrets apply` 会作用于受支持的 `openclaw.json` 凭证路径。 +- `auth-profiles.json` 引用也包含在运行时解析和审计覆盖中。 -### Secret 提供商配置 +### 密钥提供商配置 ```json5 { @@ -3297,19 +3282,19 @@ Secret refs 是增量支持：明文值仍然可用。 } ``` -说明： +注意： -- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。 +- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须是 `"value"`）。 - `exec` 提供商要求使用绝对 `command` 路径，并通过 stdin/stdout 使用协议负载。 -- 默认情况下，会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时仍校验解析后的目标路径。 -- 如果配置了 `trustedDirs`，则受信任目录检查会应用到解析后的目标路径。 -- `exec` 子进程环境默认最小化；请通过 `passEnv` 显式传递所需变量。 -- Secret refs 会在激活时解析为内存快照，此后请求路径只读取该快照。 -- 激活期间会应用活动层面过滤：启用层面上的未解析 refs 会导致启动/重载失败，而非活动层面会被跳过并记录诊断信息。 +- 默认会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时仍验证解析后的目标路径。 +- 如果配置了 `trustedDirs`，则受信目录检查会作用于解析后的目标路径。 +- 默认情况下，`exec` 子进程环境最小化；请通过 `passEnv` 显式传递所需变量。 +- SecretRef 会在激活时解析为内存快照，之后请求路径只读取该快照。 +- 激活期间会应用活动面过滤：启用面上的未解析引用会导致启动/重载失败，而非活动面会被跳过并给出诊断信息。 --- -## 凭证存储 +## Auth 存储 ```json5 { @@ -3327,13 +3312,13 @@ Secret refs 是增量支持：明文值仍然可用。 } ``` -- 按智能体的配置存储在 `/auth-profiles.json`。 -- `auth-profiles.json` 对静态凭证模式支持值级 refs（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 -- OAuth 模式配置（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。 -- 静态运行时凭证来自已解析的内存快照；发现旧版静态 `auth.json` 条目时会清理。 +- 每智能体配置文件存储在 `/auth-profiles.json`。 +- `auth-profiles.json` 支持静态凭证模式下的值级引用（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 +- OAuth 模式配置文件（`auth.profiles..mode = "oauth"`）不支持 SecretRef 支持的 auth-profile 凭证。 +- 静态运行时凭证来自已解析的内存快照；发现旧版静态 `auth.json` 条目时会将其清除。 - 旧版 OAuth 从 `~/.openclaw/credentials/oauth.json` 导入。 - 参见 [OAuth](/zh-CN/concepts/oauth)。 -- Secrets 运行时行为以及 `audit/configure/apply` 工具： [Secrets Management](/zh-CN/gateway/secrets)。 +- secrets 运行时行为以及 `audit/configure/apply` 工具：参见 [密钥管理](/zh-CN/gateway/secrets)。 ### `auth.cooldowns` @@ -3355,20 +3340,20 @@ Secret refs 是增量支持：明文值仍然可用。 } ``` -- `billingBackoffHours`：当某个配置因真实的 - 计费/余额不足错误而失败时使用的基础回退时长（小时，默认：`5`）。显式的计费文本 - 即使出现在 `401`/`403` 响应中，也仍可能归入这里，但提供商特定的文本 - 匹配器仍仅作用于拥有它们的提供商（例如 OpenRouter 的 +- `billingBackoffHours`：当配置文件因真实的 + 计费/额度不足错误而失败时的基础回退时长（小时）（默认：`5`）。即使在 `401`/`403` 响应上，显式计费文本 + 仍可能落到这里，但提供商特定的文本 + 匹配器仍只作用于拥有它们的提供商（例如 OpenRouter 的 `Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或 - organization/workspace 支出上限消息则仍归入 `rate_limit` 路径。 -- `billingBackoffHoursByProvider`：可选的按提供商计费回退时长覆盖（单位：小时）。 -- `billingMaxHours`：计费回退指数增长的上限（小时，默认：`24`）。 -- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础回退时长（分钟，默认：`10`）。 -- `authPermanentMaxMinutes`：`auth_permanent` 回退增长的上限（分钟，默认：`60`）。 -- `failureWindowHours`：用于回退计数器的滚动窗口（小时，默认：`24`）。 -- `overloadedProfileRotations`：在切换到模型回退之前，同一提供商在过载错误下允许的最大 auth-profile 轮换次数（默认：`1`）。像 `ModelNotReadyException` 这样的提供商繁忙形态会归入这里。 -- `overloadedBackoffMs`：在重试过载的提供商/profile 轮换前的固定延迟（毫秒，默认：`0`）。 -- `rateLimitedProfileRotations`：在切换到模型回退之前，同一提供商在速率限制错误下允许的最大 auth-profile 轮换次数（默认：`1`）。该 rate-limit 类别包括提供商形态的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 + organization/workspace 支出上限消息则仍走 `rate_limit` 路径。 +- `billingBackoffHoursByProvider`：可选的按提供商配置的计费回退小时数覆盖。 +- `billingMaxHours`：计费回退指数增长的小时上限（默认：`24`）。 +- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础回退时长（分钟）（默认：`10`）。 +- `authPermanentMaxMinutes`：`auth_permanent` 回退增长的分钟上限（默认：`60`）。 +- `failureWindowHours`：用于回退计数器的滚动时间窗口（小时）（默认：`24`）。 +- `overloadedProfileRotations`：针对 overloaded 错误，在切换到模型回退前，同一提供商 auth-profile 允许的最大轮换次数（默认：`1`）。诸如 `ModelNotReadyException` 的提供商繁忙形态会归入这里。 +- `overloadedBackoffMs`：重试 overloaded 提供商/配置文件轮换前的固定延迟（默认：`0`）。 +- `rateLimitedProfileRotations`：针对 rate-limit 错误，在切换到模型回退前，同一提供商 auth-profile 允许的最大轮换次数（默认：`1`）。该 rate-limit 桶包括提供商特征文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 --- @@ -3388,9 +3373,9 @@ Secret refs 是增量支持：明文值仍然可用。 ``` - 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 -- 设置 `logging.file` 可使用固定路径。 +- 设置 `logging.file` 可使用稳定路径。 - 使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。 -- `maxFileBytes`：在停止写入前允许的最大日志文件大小（字节，正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 +- `maxFileBytes`：在停止写入前允许的最大日志文件大小（字节）（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 --- @@ -3427,20 +3412,20 @@ Secret refs 是增量支持：明文值仍然可用。 } ``` -- `enabled`：instrumentation 输出总开关（默认：`true`）。 -- `flags`：启用定向日志输出的标志字符串数组（支持像 `"telegram.*"` 或 `"*"` 这样的通配符）。 -- `stuckSessionWarnMs`：当会话仍处于 processing 状态时，发出卡住会话警告所使用的年龄阈值（毫秒）。 -- `otel.enabled`：启用 OpenTelemetry 导出流水线（默认：`false`）。 -- `otel.endpoint`：OTel 导出的收集器 URL。 +- `enabled`：instrumentation 输出的主开关（默认：`true`）。 +- `flags`：启用定向日志输出的标志字符串数组（支持如 `"telegram.*"` 或 `"*"` 这样的通配符）。 +- `stuckSessionWarnMs`：当会话保持在处理状态时，用于发出卡住会话警告的年龄阈值（毫秒）。 +- `otel.enabled`：启用 OpenTelemetry 导出管线（默认：`false`）。 +- `otel.endpoint`：OTel 导出的采集器 URL。 - `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。 - `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据 headers。 -- `otel.serviceName`：资源属性中的服务名。 -- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或日志导出。 -- `otel.sampleRate`：trace 采样率 `0`–`1`。 -- `otel.flushIntervalMs`：周期性 telemetry 刷新间隔（毫秒）。 -- `cacheTrace.enabled`：为嵌入式运行记录缓存跟踪快照（默认：`false`）。 -- `cacheTrace.filePath`：缓存跟踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出中包含哪些内容（默认都为 `true`）。 +- `otel.serviceName`：资源属性使用的服务名称。 +- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 logs 导出。 +- `otel.sampleRate`：`0`–`1` 的 trace 采样率。 +- `otel.flushIntervalMs`：周期性 telemetry 冲刷间隔（毫秒）。 +- `cacheTrace.enabled`：为嵌入式运行记录缓存追踪快照（默认：`false`）。 +- `cacheTrace.filePath`：缓存追踪 JSONL 输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存追踪输出中包含的内容（默认都为 `true`）。 --- @@ -3462,12 +3447,12 @@ Secret refs 是增量支持：明文值仍然可用。 } ``` -- `channel`：用于 npm/git 安装的发布渠道 —— `"stable"`、`"beta"` 或 `"dev"`。 -- `checkOnStart`：Gateway 网关 启动时检查 npm 更新（默认：`true`）。 +- `channel`：npm/git 安装使用的发布渠道——`"stable"`、`"beta"` 或 `"dev"`。 +- `checkOnStart`：在 Gateway 网关启动时检查 npm 更新（默认：`true`）。 - `auto.enabled`：为包安装启用后台自动更新（默认：`false`）。 -- `auto.stableDelayHours`：stable 渠道自动应用前的最小延迟（小时，默认：`6`；最大：`168`）。 -- `auto.stableJitterHours`：stable 渠道额外滚动发布扩散窗口（小时，默认：`12`；最大：`168`）。 -- `auto.betaCheckIntervalHours`：beta 渠道检查运行频率（小时，默认：`1`；最大：`24`）。 +- `auto.stableDelayHours`：stable 渠道自动应用前的最小延迟小时数（默认：`6`；最大：`168`）。 +- `auto.stableJitterHours`：stable 渠道发布扩散窗口的额外小时数（默认：`12`；最大：`168`）。 +- `auto.betaCheckIntervalHours`：beta 渠道检查运行的间隔小时数（默认：`1`；最大：`24`）。 --- @@ -3500,22 +3485,22 @@ Secret refs 是增量支持：明文值仍然可用。 } ``` -- `enabled`：ACP 全局功能开关（默认：`false`）。 +- `enabled`：ACP 功能的全局开关（默认：`false`）。 - `dispatch.enabled`：ACP 会话轮次分发的独立开关（默认：`true`）。设为 `false` 可在保留 ACP 命令可用的同时阻止执行。 -- `backend`：默认 ACP 运行时后端 id（必须匹配某个已注册 ACP 运行时插件）。 -- `defaultAgent`：当派生未指定显式目标时，ACP 的后备目标智能体 id。 -- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 列表；空值表示无额外限制。 -- `maxConcurrentSessions`：同时活跃的 ACP 会话最大数量。 -- `stream.coalesceIdleMs`：流式文本的空闲合并刷新窗口（毫秒）。 -- `stream.maxChunkChars`：流式块投影在拆分前允许的最大 chunk 大小。 -- `stream.repeatSuppression`：按轮次抑制重复的状态/工具行（默认：`true`）。 +- `backend`：默认 ACP 运行时后端 ID（必须匹配某个已注册的 ACP 运行时插件）。 +- `defaultAgent`：当 spawn 未指定显式目标时使用的回退 ACP 目标智能体 ID。 +- `allowedAgents`：允许用于 ACP 运行时会话的智能体 ID 允许列表；空表示不做额外限制。 +- `maxConcurrentSessions`：最大并发活动 ACP 会话数。 +- `stream.coalesceIdleMs`：流式文本的空闲冲刷窗口（毫秒）。 +- `stream.maxChunkChars`：在拆分流式分块投影前允许的最大 chunk 大小。 +- `stream.repeatSuppression`：按轮次抑制重复状态/工具行（默认：`true`）。 - `stream.deliveryMode`：`"live"` 表示增量流式传输；`"final_only"` 表示缓冲到轮次终止事件后再输出。 -- `stream.hiddenBoundarySeparator`：在隐藏工具事件后的可见文本前插入的分隔符（默认：`"paragraph"`）。 -- `stream.maxOutputChars`：每个 ACP 轮次投影的 assistant 输出最大字符数。 -- `stream.maxSessionUpdateChars`：投影的 ACP 状态/更新行的最大字符数。 +- `stream.hiddenBoundarySeparator`：隐藏工具事件之后、可见文本之前的分隔符（默认：`"paragraph"`）。 +- `stream.maxOutputChars`：每个 ACP 轮次投影的最大 assistant 输出字符数。 +- `stream.maxSessionUpdateChars`：投影 ACP 状态/更新行的最大字符数。 - `stream.tagVisibility`：记录标签名到布尔可见性覆盖的映射，用于流式事件。 -- `runtime.ttlMinutes`：ACP 会话 worker 的空闲 TTL（分钟），超过后可被清理。 -- `runtime.installCommand`：在引导 ACP 运行时环境时执行的可选安装命令。 +- `runtime.ttlMinutes`：ACP 会话工作进程在可被清理前的空闲 TTL（分钟）。 +- `runtime.installCommand`：引导 ACP 运行时环境时运行的可选安装命令。 --- @@ -3533,7 +3518,7 @@ Secret refs 是增量支持：明文值仍然可用。 - `cli.banner.taglineMode` 控制 banner 标语样式： - `"random"`（默认）：轮换的有趣/季节性标语。 - - `"default"`：固定中性标语（`All your chats, one OpenClaw.`）。 + - `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。 - `"off"`：不显示标语文本（仍显示 banner 标题/版本）。 - 如需隐藏整个 banner（而不仅是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 @@ -3559,13 +3544,13 @@ Secret refs 是增量支持：明文值仍然可用。 ## Identity -参见 [Agent defaults](#agent-defaults) 下 `agents.list` 的 identity 字段。 +参见 [智能体默认值](#agent-defaults) 下 `agents.list` 的 identity 字段。 --- -## Bridge（旧版，已移除） +## Bridge protocol（旧版节点，历史参考）（旧版，已移除） -当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（必须移除后验证才会通过；`openclaw doctor --fix` 可剥离未知键）。 +当前构建不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除之前验证会失败；`openclaw doctor --fix` 可清理未知键）。 @@ -3594,8 +3579,8 @@ Secret refs 是增量支持：明文值仍然可用。 cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // 已弃用：用于已存储 notify:true 作业的回退 - webhookToken: "replace-with-dedicated-token", // 可选：用于出站 webhook 认证的 bearer token + webhook: "https://example.invalid/legacy", // 已弃用，仅作为存储的 notify:true 作业的回退 + webhookToken: "replace-with-dedicated-token", // 可选的 bearer token，用于出站 webhook 身份验证 sessionRetention: "24h", // 时长字符串或 false runLog: { maxBytes: "2mb", // 默认 2_000_000 字节 @@ -3605,11 +3590,11 @@ Secret refs 是增量支持：明文值仍然可用。 } ``` -- `sessionRetention`：在从 `sessions.json` 中修剪前，已完成的隔离 cron 运行会话保留多久。也控制已归档的已删除 cron 转录的清理。默认值：`24h`；设为 `false` 可禁用。 -- `runLog.maxBytes`：每个运行日志文件（`cron/runs/.jsonl`）在修剪前的最大大小。默认值：`2_000_000` 字节。 -- `runLog.keepLines`：触发运行日志修剪时保留的最新行数。默认值：`2000`。 -- `webhookToken`：用于 cron webhook POST 交付（`delivery.mode = "webhook"`）的 bearer token；若省略，则不会发送认证 header。 -- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于仍设置 `notify: true` 的已存储作业。 +- `sessionRetention`：从 `sessions.json` 中裁剪前，保留已完成的隔离 cron 运行会话多久。也控制已归档、已删除的 cron transcript 的清理。默认值：`24h`；设为 `false` 可禁用。 +- `runLog.maxBytes`：触发裁剪前，每个运行日志文件（`cron/runs/.jsonl`）允许的最大大小。默认值：`2_000_000` 字节。 +- `runLog.keepLines`：触发运行日志裁剪时保留的最新行数。默认值：`2000`。 +- `webhookToken`：cron webhook POST 投递（`delivery.mode = "webhook"`）使用的 bearer token；若省略则不会发送 auth header。 +- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于那些仍带有 `notify: true` 的已存储作业。 ### `cron.retry` @@ -3625,9 +3610,9 @@ Secret refs 是增量支持：明文值仍然可用。 } ``` -- `maxAttempts`：一次性作业在瞬时错误下的最大重试次数（默认：`3`；范围：`0`–`10`）。 -- `backoffMs`：每次重试尝试的回退延迟数组（毫秒，默认：`[30000, 60000, 300000]`；1–10 个条目）。 -- `retryOn`：触发重试的错误类型 —— `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略时会重试所有瞬时错误类型。 +- `maxAttempts`：一次性作业在瞬态错误下的最大重试次数（默认：`3`；范围：`0`–`10`）。 +- `backoffMs`：每次重试对应的回退延迟数组（毫秒）（默认：`[30000, 60000, 300000]`；1–10 个条目）。 +- `retryOn`：触发重试的错误类型——`"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略则重试所有瞬态类型。 仅适用于一次性 cron 作业。周期性作业使用单独的失败处理方式。 @@ -3647,11 +3632,11 @@ Secret refs 是增量支持：明文值仍然可用。 } ``` -- `enabled`：启用 cron 作业失败告警（默认：`false`）。 -- `after`：连续失败多少次后触发告警（正整数，最小值：`1`）。 -- `cooldownMs`：同一作业重复告警之间的最短间隔（毫秒，非负整数）。 -- `mode`：交付模式 —— `"announce"` 通过渠道消息发送；`"webhook"` 则 POST 到已配置的 webhook。 -- `accountId`：用于限定告警交付范围的可选账号或渠道 id。 +- `enabled`：启用 cron 作业失败警报（默认：`false`）。 +- `after`：在触发警报前所需的连续失败次数（正整数，最小值：`1`）。 +- `cooldownMs`：同一作业重复发送警报之间的最小间隔（毫秒）（非负整数）。 +- `mode`：投递模式——`"announce"` 通过渠道消息发送；`"webhook"` 向已配置的 webhook 发送 POST。 +- `accountId`：用于限定警报投递的可选账号或渠道 ID。 ### `cron.failureDestination` @@ -3668,16 +3653,16 @@ Secret refs 是增量支持：明文值仍然可用。 } ``` -- 所有作业的默认 cron 失败通知目标。 -- `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认值为 `"announce"`。 -- `channel`：用于 announce 交付的渠道覆盖。`"last"` 会复用最后已知的交付渠道。 -- `to`：显式的 announce 目标或 webhook URL。webhook 模式下必填。 -- `accountId`：可选的交付账号覆盖。 -- 按作业的 `delivery.failureDestination` 会覆盖该全局默认值。 -- 如果既未设置全局失败目标，也未设置按作业失败目标，则已通过 `announce` 交付的作业在失败时会回退到其主 announce 目标。 -- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 的作业，除非该作业的主 `delivery.mode` 是 `"webhook"`。 +- 所有作业共享的 cron 失败通知默认目标。 +- `mode`：`"announce"` 或 `"webhook"`；当存在足够目标数据时，默认值为 `"announce"`。 +- `channel`：announce 投递的渠道覆盖。`"last"` 会复用最近一次已知投递渠道。 +- `to`：显式的 announce 目标或 webhook URL。webhook 模式下为必填。 +- `accountId`：可选的投递账号覆盖。 +- 每作业的 `delivery.failureDestination` 会覆盖该全局默认值。 +- 当全局和每作业失败目标都未设置时，原本已通过 `announce` 投递的作业在失败时会回退到其主 announce 目标。 +- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 的作业，除非该作业的主 `delivery.mode` 为 `"webhook"`。 -参见 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会被跟踪为 [background tasks](/zh-CN/automation/tasks)。 +参见 [Cron 作业](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为 [后台任务](/zh-CN/automation/tasks) 进行跟踪。 --- @@ -3685,32 +3670,32 @@ Secret refs 是增量支持：明文值仍然可用。 在 `tools.media.models[].args` 中展开的模板占位符： -| 变量 | 说明 | -| ------------------ | ----------------------------------------- | -| `{{Body}}` | 完整入站消息正文 | -| `{{RawBody}}` | 原始正文（无历史/发送者包装） | -| `{{BodyStripped}}` | 去除群组提及后的正文 | -| `{{From}}` | 发送者标识符 | -| `{{To}}` | 目标标识符 | -| `{{MessageSid}}` | 渠道消息 id | -| `{{SessionId}}` | 当前会话 UUID | -| `{{IsNewSession}}` | 新建会话时为 `"true"` | -| `{{MediaUrl}}` | 入站媒体伪 URL | -| `{{MediaPath}}` | 本地媒体路径 | -| `{{MediaType}}` | 媒体类型（image/audio/document/…） | -| `{{Transcript}}` | 音频转录 | -| `{{Prompt}}` | 为 CLI 条目解析后的媒体提示 | -| `{{MaxChars}}` | 为 CLI 条目解析后的最大输出字符数 | -| `{{ChatType}}` | `"direct"` 或 `"group"` | -| `{{GroupSubject}}` | 群组主题（尽力而为） | -| `{{GroupMembers}}` | 群组成员预览（尽力而为） | -| `{{SenderName}}` | 发送者显示名称（尽力而为） | -| `{{SenderE164}}` | 发送者电话号码（尽力而为） | +| 变量 | 说明 | +| ------------------ | ------------------------------------------------- | +| `{{Body}}` | 完整入站消息正文 | +| `{{RawBody}}` | 原始正文（无历史记录/发送者包装） | +| `{{BodyStripped}}` | 去除群组提及后的正文 | +| `{{From}}` | 发送者标识符 | +| `{{To}}` | 目标标识符 | +| `{{MessageSid}}` | 渠道消息 ID | +| `{{SessionId}}` | 当前会话 UUID | +| `{{IsNewSession}}` | 当创建了新会话时为 `"true"` | +| `{{MediaUrl}}` | 入站媒体伪 URL | +| `{{MediaPath}}` | 本地媒体路径 | +| `{{MediaType}}` | 媒体类型（image/audio/document/…） | +| `{{Transcript}}` | 音频 transcript | +| `{{Prompt}}` | 为 CLI 条目解析后的媒体提示 | +| `{{MaxChars}}` | 为 CLI 条目解析后的最大输出字符数 | +| `{{ChatType}}` | `"direct"` 或 `"group"` | +| `{{GroupSubject}}` | 群组主题（尽力而为） | +| `{{GroupMembers}}` | 群组成员预览（尽力而为） | +| `{{SenderName}}` | 发送者显示名称（尽力而为） | +| `{{SenderE164}}` | 发送者电话号码（尽力而为） | | `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） | --- -## 配置 include（`$include`） +## 配置包含（`$include`） 将配置拆分为多个文件： @@ -3727,13 +3712,13 @@ Secret refs 是增量支持：明文值仍然可用。 **合并行为：** -- 单文件：替换包含它的对象。 +- 单文件：替换所在的对象。 - 文件数组：按顺序深度合并（后者覆盖前者）。 -- 同级键：在 includes 之后合并（覆盖 include 中的值）。 -- 嵌套 includes：最多 10 层深度。 -- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内部。绝对路径/`../` 形式仅在最终仍解析到该边界内时才允许。 -- 错误：对缺失文件、解析错误和循环 include 提供清晰的错误消息。 +- 同级键：在 includes 之后合并（覆盖包含的值）。 +- 嵌套 includes：最多支持 10 层。 +- 路径：相对于发起包含的文件解析，但必须保持在顶层配置目录内（`openclaw.json` 的 `dirname`）。仅当绝对路径/`../` 形式解析后仍在该边界内时才允许。 +- 错误：对缺失文件、解析错误和循环包含提供清晰报错。 --- -_相关内容： [Configuration](/zh-CN/gateway/configuration) · [Configuration Examples](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_ +_相关内容：[配置](/zh-CN/gateway/configuration) · [配置示例](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_ diff --git a/docs/zh-CN/gateway/local-models.md b/docs/zh-CN/gateway/local-models.md index 3be02dd50..26c1c0476 100644 --- a/docs/zh-CN/gateway/local-models.md +++ b/docs/zh-CN/gateway/local-models.md @@ -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..models[].compat.requiresStringContent: true`。 -- 一些更小或更严格的本地后端，在面对 OpenClaw 完整智能体运行时的提示结构时会不稳定，尤其是在包含工具 schema 时。如果后端能处理很小的直接 `/v1/chat/completions` 调用，但在正常的 OpenClaw 智能体轮次中失败，请先尝试设置 `agents.defaults.experimental.localModelLean: true`，以移除 `browser`、`cron` 和 `message` 这类重量级默认工具；这是实验性标志，不是稳定的默认模式设置。如果这样仍然失败，再尝试 `models.providers..models[].compat.supportsTools: false`。 -- 如果后端只会在更大的 OpenClaw 运行中失败，剩余问题通常是上游模型 / 服务器容量不足，或后端本身的 bug，而不是 OpenClaw 的传输层问题。 +- 某些服务器在 Chat Completions 中只接受字符串类型的 `messages[].content`，而不接受结构化的内容片段数组。对于这些端点，请设置 `models.providers..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..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，以限制提示注入的影响范围。 diff --git a/docs/zh-CN/reference/memory-config.md b/docs/zh-CN/reference/memory-config.md index e770ff6ee..888845719 100644 --- a/docs/zh-CN/reference/memory-config.md +++ b/docs/zh-CN/reference/memory-config.md @@ -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 | -更改模型或 `outputDimensionality` 会触发自动全量重新索引。 +更改模型或 `outputDimensionality` 会触发自动全量重建索引。 --- ## 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::` 的原始键。 ### 引用 `memory.citations` 适用于所有后端： -| 值 | 行为 | -| ---------------- | ----------------------------------------------- | -| `auto`（默认） | 在片段中包含 `Source: ` 页脚 | -| `on` | 始终包含页脚 | -| `off` | 省略页脚（路径仍会在内部传递给智能体） | +| 值 | 行为 | +| ---------------- | ------------------------------------------------ | +| `auto`（默认） | 在片段中包含 `Source: ` 页脚 | +| `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 阶段策略和阈值属于内部行为，不是面向用户的配置。