From f15b6e1440ca98d3ffeffd4209ed5d416e7fe2dd Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 5 Apr 2026 19:23:49 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/channels/matrix.md | 510 ++++---- docs/zh-CN/gateway/configuration-reference.md | 1065 ++++++++--------- 2 files changed, 780 insertions(+), 795 deletions(-) diff --git a/docs/zh-CN/channels/matrix.md b/docs/zh-CN/channels/matrix.md index 0fecf00d7..ed2405d15 100644 --- a/docs/zh-CN/channels/matrix.md +++ b/docs/zh-CN/channels/matrix.md @@ -5,10 +5,10 @@ read_when: summary: Matrix 支持状态、设置和配置示例 title: Matrix x-i18n: - generated_at: "2026-04-05T17:48:32Z" + generated_at: "2026-04-05T19:18:53Z" model: gpt-5.4 provider: openai - source_hash: 5e43bc2b11f86650b165cd46cd053b0874cc564993999670c0fe422cb9283cb5 + source_hash: 3a1413c8c6fb6991a6bbb54ef7893ce01350ccf9d18405127981ac7369c52ab5 source_path: channels/matrix.md workflow: 15 --- @@ -16,13 +16,13 @@ x-i18n: # Matrix Matrix 是 OpenClaw 的 Matrix 内置渠道插件。 -它使用官方的 `matrix-js-sdk`，并支持私信、房间、线程、媒体、回应、投票、位置和 E2EE。 +它使用官方 `matrix-js-sdk`，并支持私信、房间、线程、媒体、回应、投票、位置和 E2EE。 ## 内置插件 -Matrix 作为内置插件随当前的 OpenClaw 版本一起提供，因此常规的打包构建无需单独安装。 +Matrix 作为内置插件随当前的 OpenClaw 版本一起发布，因此常规打包构建不需要单独安装。 -如果你使用的是较旧版本，或使用排除了 Matrix 的自定义安装，请手动安装： +如果你使用的是较旧版本，或是不包含 Matrix 的自定义安装，请手动安装： 从 npm 安装： @@ -36,19 +36,19 @@ openclaw plugins install @openclaw/matrix openclaw plugins install ./path/to/local/matrix-plugin ``` -有关插件行为和安装规则，请参阅 [Plugins](/zh-CN/tools/plugin)。 +有关插件行为和安装规则，请参阅 [插件](/zh-CN/tools/plugin)。 ## 设置 1. 确保 Matrix 插件可用。 - 当前打包的 OpenClaw 版本已内置该插件。 - - 较旧版本或自定义安装可使用上述命令手动添加。 -2. 在你的 homeserver 上创建一个 Matrix 账户。 + - 较旧版本/自定义安装可使用上述命令手动添加。 +2. 在你的 homeserver 上创建一个 Matrix 账号。 3. 使用以下任一方式配置 `channels.matrix`： - `homeserver` + `accessToken`，或 - `homeserver` + `userId` + `password`。 4. 重启 Gateway 网关。 -5. 与机器人发起私信，或邀请它加入房间。 +5. 与机器人发起私信，或将它邀请到房间中。 交互式设置路径： @@ -57,25 +57,25 @@ openclaw channels add openclaw configure --section channels ``` -Matrix 向导实际会询问以下内容： +Matrix 向导实际会询问的内容： - homeserver URL -- 认证方式：访问令牌或密码 +- 认证方式：access token 或 password - 仅当你选择密码认证时才需要用户 ID -- 可选设备名称 +- 可选的设备名称 - 是否启用 E2EE -- 是否立即配置 Matrix 房间访问 +- 是否现在配置 Matrix 房间访问 需要注意的向导行为： -- 如果所选账户已存在 Matrix 认证环境变量，且该账户的配置中尚未保存认证信息，向导会提供环境变量快捷方式，并且只会为该账户写入 `enabled: true`。 -- 当你以交互方式添加另一个 Matrix 账户时，输入的账户名称会被规范化为配置和环境变量中使用的账户 ID。例如，`Ops Bot` 会变成 `ops-bot`。 -- 私信 allowlist 提示可立即接受完整的 `@user:server` 值。仅当实时目录查找能找到一个精确匹配时，显示名称才可用；否则向导会要求你使用完整的 Matrix ID 重试。 -- 房间 allowlist 提示可直接接受房间 ID 和别名。它们也可以实时解析已加入房间的名称，但无法解析的名称只会在设置期间按原样保留，之后会在运行时 allowlist 解析中被忽略。建议优先使用 `!room:server` 或 `#alias:server`。 -- 运行时房间 / 会话标识使用稳定的 Matrix 房间 ID。房间声明的别名只用作查找输入，而不是长期会话键或稳定的群组标识。 -- 如需在保存前解析房间名称，请使用 `openclaw channels resolve --channel matrix "Project Room"`。 +- 如果所选账号已经存在 Matrix 认证环境变量，且该账号的认证信息尚未保存在配置中，向导会提供环境变量快捷方式，并且只会为该账号写入 `enabled: true`。 +- 当你以交互方式添加另一个 Matrix 账号时，输入的账号名称会被规范化为配置和环境变量中使用的账号 ID。例如，`Ops Bot` 会变成 `ops-bot`。 +- 私信 allowlist 提示可立即接受完整的 `@user:server` 值。仅当实时目录查找恰好找到一个精确匹配时，显示名称才可用；否则向导会要求你使用完整的 Matrix ID 重试。 +- 房间 allowlist 提示可直接接受房间 ID 和别名。它们也可以实时解析已加入的房间名称，但无法解析的名称只会在设置期间按原样保留，稍后运行时 allowlist 解析会忽略它们。建议优先使用 `!room:server` 或 `#alias:server`。 +- 运行时房间/会话身份使用稳定的 Matrix 房间 ID。房间声明的别名仅作为查找输入使用，不会作为长期会话键或稳定群组身份。 +- 若要在保存前解析房间名称，请使用 `openclaw channels resolve --channel matrix "Project Room"`。 -基于令牌的最小配置： +基于 token 的最小设置： ```json5 { @@ -90,7 +90,7 @@ Matrix 向导实际会询问以下内容： } ``` -基于密码的设置（登录后会缓存令牌）： +基于密码的设置（登录后会缓存 token）： ```json5 { @@ -106,10 +106,10 @@ Matrix 向导实际会询问以下内容： } ``` -Matrix 将缓存的凭证存储在 `~/.openclaw/credentials/matrix/` 中。 -默认账户使用 `credentials.json`；命名账户使用 `credentials-.json`。 +Matrix 会将缓存的凭证存储在 `~/.openclaw/credentials/matrix/` 中。 +默认账号使用 `credentials.json`；命名账号使用 `credentials-.json`。 -等效的环境变量（当未设置配置键时使用）： +等效的环境变量（当未设置对应配置键时使用）： - `MATRIX_HOMESERVER` - `MATRIX_ACCESS_TOKEN` @@ -118,7 +118,7 @@ Matrix 将缓存的凭证存储在 `~/.openclaw/credentials/matrix/` 中。 - `MATRIX_DEVICE_ID` - `MATRIX_DEVICE_NAME` -对于非默认账户，请使用带账户作用域的环境变量： +对于非默认账号，请使用带账号作用域的环境变量： - `MATRIX__HOMESERVER` - `MATRIX__ACCESS_TOKEN` @@ -127,24 +127,24 @@ Matrix 将缓存的凭证存储在 `~/.openclaw/credentials/matrix/` 中。 - `MATRIX__DEVICE_ID` - `MATRIX__DEVICE_NAME` -账户 `ops` 的示例： +以账号 `ops` 为例： - `MATRIX_OPS_HOMESERVER` - `MATRIX_OPS_ACCESS_TOKEN` -对于规范化账户 ID `ops-bot`，请使用： +对于规范化后的账号 ID `ops-bot`，请使用： - `MATRIX_OPS_X2D_BOT_HOMESERVER` - `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` -Matrix 会对账户 ID 中的标点符号进行转义，以避免带作用域的环境变量发生冲突。 +Matrix 会对账号 ID 中的标点符号进行转义，以避免带作用域的环境变量发生冲突。 例如，`-` 会变成 `_X2D_`，因此 `ops-prod` 会映射为 `MATRIX_OPS_X2D_PROD_*`。 -只有当这些认证环境变量已经存在，且所选账户的配置中尚未保存 Matrix 认证信息时，交互式向导才会提供环境变量快捷方式。 +只有当这些认证环境变量已存在，且所选账号尚未在配置中保存 Matrix 认证信息时，交互式向导才会提供环境变量快捷方式。 ## 配置示例 -这是一个实用的基线配置，启用了私信配对、房间 allowlist 和 E2EE： +这是一个实用的基础配置，启用了私信配对、房间 allowlist 和 E2EE： ```json5 { @@ -157,6 +157,7 @@ Matrix 会对账户 ID 中的标点符号进行转义，以避免带作用域的 dm: { policy: "pairing", + sessionScope: "per-room", threadReplies: "off", }, @@ -180,9 +181,9 @@ Matrix 会对账户 ID 中的标点符号进行转义，以避免带作用域的 ## 流式预览 -Matrix 回复流式传输为选择启用。 +Matrix 回复流式传输为可选启用。 -当你希望 OpenClaw 发送一条草稿回复、在模型生成文本时原地编辑该草稿，并在回复完成后将其定稿时，请将 `channels.matrix.streaming` 设置为 `"partial"`： +当你希望 OpenClaw 发送一条草稿回复、在模型生成文本时原地编辑这条草稿，并在回复完成后最终定稿时，请将 `channels.matrix.streaming` 设置为 `"partial"`： ```json5 { @@ -195,25 +196,25 @@ Matrix 回复流式传输为选择启用。 ``` - `streaming: "off"` 是默认值。OpenClaw 会等待最终回复并一次性发送。 -- `streaming: "partial"` 会为当前助手块创建一条可编辑的预览消息，而不是发送多条部分消息。 -- `blockStreaming: true` 会启用单独的 Matrix 进度消息。配合 `streaming: "partial"` 时，Matrix 会保留当前块的实时草稿，并将已完成的块保留为单独消息。 -- 当 `streaming: "partial"` 且 `blockStreaming` 关闭时，Matrix 只会编辑实时草稿，并在该块或该轮结束时发送完整回复。 -- 如果预览已无法容纳在单个 Matrix 事件中，OpenClaw 会停止预览流式传输，并回退到常规的最终投递。 -- 媒体回复仍会正常发送附件。如果过期的预览已无法安全复用，OpenClaw 会在发送最终媒体回复前将其撤回。 -- 预览编辑会产生额外的 Matrix API 调用。如果你希望采用最保守的速率限制行为，请保持关闭流式传输。 +- `streaming: "partial"` 会为当前 assistant 块创建一条可编辑的预览消息，而不是发送多条部分消息。 +- `blockStreaming: true` 会启用单独的 Matrix 进度消息。与 `streaming: "partial"` 一起使用时，Matrix 会保留当前块的实时草稿，并将已完成的块保留为单独消息。 +- 当 `streaming: "partial"` 且 `blockStreaming` 关闭时，Matrix 只会编辑实时草稿，并在该块或该轮完成后发送完整回复。 +- 如果预览已无法容纳在单个 Matrix 事件中，OpenClaw 会停止预览流式传输并回退为正常的最终发送。 +- 媒体回复仍会正常发送附件。如果过期预览无法再被安全复用，OpenClaw 会在发送最终媒体回复前将其 redact。 +- 预览编辑会产生额外的 Matrix API 调用。如果你希望采用最保守的速率限制行为，请关闭流式传输。 `blockStreaming` 本身不会启用草稿预览。 -使用 `streaming: "partial"` 来启用预览编辑；如果你还希望已完成的助手块作为单独的进度消息保留可见，再添加 `blockStreaming: true`。 +如需预览编辑，请使用 `streaming: "partial"`；如果你还希望已完成的 assistant 块以单独进度消息保留可见，再添加 `blockStreaming: true`。 ## 加密和验证 -在加密（E2EE）房间中，出站图片事件会使用 `thumbnail_file`，因此图片预览会与完整附件一起加密。未加密房间仍使用普通的 `thumbnail_url`。无需任何配置——插件会自动检测 E2EE 状态。 +在加密（E2EE）房间中，出站图片事件使用 `thumbnail_file`，因此图片预览会与完整附件一起被加密。未加密房间仍使用普通的 `thumbnail_url`。无需任何配置——插件会自动检测 E2EE 状态。 ### Bot 对 bot 房间 -默认情况下，来自其他已配置 OpenClaw Matrix 账户的 Matrix 消息会被忽略。 +默认情况下，来自其他已配置 OpenClaw Matrix 账号的 Matrix 消息会被忽略。 -当你明确希望启用智能体之间的 Matrix 通信时，请使用 `allowBots`： +当你有意启用智能体之间的 Matrix 流量时，请使用 `allowBots`： ```json5 { @@ -230,13 +231,13 @@ Matrix 回复流式传输为选择启用。 } ``` -- `allowBots: true` 接受来自其他已配置 Matrix 机器人账户、并位于允许房间和私信中的消息。 -- `allowBots: "mentions"` 仅在这些消息在房间中明确提及此机器人时才接受。私信仍然允许。 -- `groups..allowBots` 会覆盖单个房间的账户级设置。 -- OpenClaw 仍会忽略来自相同 Matrix 用户 ID 的消息，以避免自回复循环。 -- Matrix 在这里不提供原生的机器人标记；OpenClaw 将“由机器人发送”视为“由此 OpenClaw Gateway 网关上另一个已配置的 Matrix 账户发送”。 +- `allowBots: true` 会接受来自其他已配置 Matrix bot 账号、且位于允许房间和私信中的消息。 +- `allowBots: "mentions"` 仅当这些消息在房间中显式提及此 bot 时才接受。私信仍然允许。 +- `groups..allowBots` 会覆盖该房间的账号级设置。 +- OpenClaw 仍会忽略来自同一 Matrix 用户 ID 的消息，以避免自回复循环。 +- Matrix 在这里不提供原生 bot 标记；OpenClaw 将“由 bot 撰写”视为“由此 OpenClaw Gateway 网关上另一个已配置的 Matrix 账号发送”。 -在共享房间中启用 bot 对 bot 通信时，请使用严格的房间 allowlist 和提及要求。 +在共享房间中启用 bot 对 bot 流量时，请使用严格的房间 allowlist 和提及要求。 启用加密： @@ -272,13 +273,13 @@ openclaw matrix verify status --verbose openclaw matrix verify status --include-recovery-key --json ``` -引导跨签名和验证状态： +引导 cross-signing 和验证状态： ```bash openclaw matrix verify bootstrap ``` -多账户支持：使用 `channels.matrix.accounts` 配置每个账户的凭证和可选 `name`。共享模式请参阅 [配置参考](/zh-CN/gateway/configuration-reference#multi-account-all-channels)。 +多账号支持：使用 `channels.matrix.accounts` 配置每个账号的凭证和可选的 `name`。共享模式请参阅 [配置参考](/zh-CN/gateway/configuration-reference#multi-account-all-channels)。 详细引导诊断： @@ -286,7 +287,7 @@ openclaw matrix verify bootstrap openclaw matrix verify bootstrap --verbose ``` -在引导前强制重置为全新的跨签名身份： +在引导前强制重置一个全新的 cross-signing 身份： ```bash openclaw matrix verify bootstrap --force-reset-cross-signing @@ -328,20 +329,18 @@ openclaw matrix verify backup restore openclaw matrix verify backup restore --verbose ``` -删除当前服务器备份并创建新的备份基线。如果存储的 -备份密钥无法被干净地加载，此重置也可以重新创建秘密存储， -以便未来冷启动时能够加载新的备份密钥： +删除当前服务器备份并创建全新的备份基线。如果无法干净地加载已存储的备份密钥，此重置还可以重新创建 secret storage，以便未来冷启动时能够加载新的备份密钥： ```bash openclaw matrix verify backup reset --yes ``` -所有 `verify` 命令默认都保持简洁（包括安静的内部 SDK 日志），只有使用 `--verbose` 时才显示详细诊断。 -进行脚本编写时，请使用 `--json` 获取完整的机器可读输出。 +所有 `verify` 命令默认都很简洁（包括安静的内部 SDK 日志），只有在使用 `--verbose` 时才显示详细诊断。 +编写脚本时，请使用 `--json` 获取完整的机器可读输出。 -在多账户设置中，Matrix CLI 命令会使用隐式的 Matrix 默认账户，除非你传递 `--account `。 -如果你配置了多个命名账户，请先设置 `channels.matrix.defaultAccount`，否则这些隐式 CLI 操作会停止并要求你显式选择账户。 -当你希望验证或设备操作明确针对某个命名账户时，请使用 `--account`： +在多账号设置中，Matrix CLI 命令会使用隐式的 Matrix 默认账号，除非你传入 `--account `。 +如果你配置了多个命名账号，请先设置 `channels.matrix.defaultAccount`，否则这些隐式 CLI 操作会停止并要求你显式选择一个账号。 +当你希望验证或设备操作显式针对某个命名账号时，请使用 `--account`： ```bash openclaw matrix verify status --account assistant @@ -349,42 +348,40 @@ openclaw matrix verify backup restore --account assistant openclaw matrix devices list --account assistant ``` -当某个命名账户禁用了加密或加密不可用时，Matrix 警告和验证错误会指向该账户的配置键，例如 `channels.matrix.accounts.assistant.encryption`。 +当命名账号禁用了加密，或该账号不可用时，Matrix 警告和验证错误会指向该账号的配置键，例如 `channels.matrix.accounts.assistant.encryption`。 ### “已验证” 的含义 -只有当这个 Matrix 设备被你自己的跨签名身份验证后，OpenClaw 才会将其视为已验证。 -在实践中，`openclaw matrix verify status --verbose` 会暴露三个信任信号： +只有当这个 Matrix 设备由你自己的 cross-signing 身份验证后，OpenClaw 才会将其视为已验证。 +实际上，`openclaw matrix verify status --verbose` 会暴露三个信任信号： - `Locally trusted`：此设备仅被当前客户端信任 -- `Cross-signing verified`：SDK 报告该设备已通过跨签名验证 -- `Signed by owner`：该设备已由你自己的自签名密钥签名 +- `Cross-signing verified`：SDK 报告该设备已通过 cross-signing 验证 +- `Signed by owner`：该设备由你自己的 self-signing 密钥签名 -只有在存在跨签名验证或所有者签名时，`Verified by owner` 才会变为 `yes`。 -仅有本地信任不足以让 OpenClaw 将该设备视为完全已验证。 +只有当存在 cross-signing 验证或所有者签名时，`Verified by owner` 才会变为 `yes`。 +仅有本地信任，不足以让 OpenClaw 将该设备视为完全已验证。 -### 引导会做什么 +### bootstrap 的作用 -`openclaw matrix verify bootstrap` 是加密 Matrix 账户的修复和设置命令。 -它会依次完成以下所有操作： +`openclaw matrix verify bootstrap` 是用于加密 Matrix 账号的修复和设置命令。 +它会按顺序完成以下所有操作： -- 引导秘密存储，并尽可能复用现有恢复密钥 -- 引导跨签名并上传缺失的公开跨签名密钥 -- 尝试标记并跨签名当前设备 -- 如果服务器端房间密钥备份尚不存在，则创建一个新的备份 +- 引导 secret storage，并在可能时复用现有恢复密钥 +- 引导 cross-signing 并上传缺失的公开 cross-signing 密钥 +- 尝试标记并 cross-sign 当前设备 +- 如果服务器端尚不存在房间密钥备份，则创建新的服务器端房间密钥备份 -如果 homeserver 在上传跨签名密钥时要求交互式认证，OpenClaw 会先尝试不带认证上传，然后尝试 `m.login.dummy`，最后在配置了 `channels.matrix.password` 时尝试 `m.login.password`。 +如果 homeserver 要求交互式认证才能上传 cross-signing 密钥，OpenClaw 会先尝试无认证上传，然后尝试 `m.login.dummy`，当已配置 `channels.matrix.password` 时再尝试 `m.login.password`。 -仅当你明确希望丢弃当前跨签名身份并创建新身份时，才使用 `--force-reset-cross-signing`。 +只有在你明确想要丢弃当前 cross-signing 身份并创建新身份时，才使用 `--force-reset-cross-signing`。 -如果你明确希望丢弃当前房间密钥备份，并为未来消息启动新的 -备份基线，请使用 `openclaw matrix verify backup reset --yes`。 -仅当你接受不可恢复的旧加密历史仍将无法访问，并且 OpenClaw 可能会在当前备份 -密钥无法安全加载时重新创建秘密存储时，才这样做。 +如果你明确想要丢弃当前房间密钥备份，并为未来消息建立新的备份基线，请使用 `openclaw matrix verify backup reset --yes`。 +只有在你可以接受无法恢复的旧加密历史仍然不可用，并且 OpenClaw 可能会在当前备份 secret 无法安全加载时重新创建 secret storage 的情况下，才这样做。 ### 全新备份基线 -如果你希望保证未来的加密消息继续可用，并接受丢失不可恢复的旧历史，请按顺序运行以下命令： +如果你想保持未来的加密消息继续正常工作，并接受丢失无法恢复的旧历史，请按顺序运行以下命令： ```bash openclaw matrix verify backup reset --yes @@ -392,105 +389,102 @@ openclaw matrix verify backup status --verbose openclaw matrix verify status ``` -当你希望明确指定某个命名 Matrix 账户时，请为每个命令添加 `--account `。 +当你想显式针对某个命名 Matrix 账号时，请为每条命令添加 `--account `。 ### 启动行为 -当 `encryption: true` 时，Matrix 会将 `startupVerification` 默认为 `"if-unverified"`。 -启动时，如果此设备仍未验证，Matrix 会在另一个 Matrix 客户端中请求自验证， -在已有请求待处理时跳过重复请求，并在重启后重试前应用本地冷却时间。 -默认情况下，失败的请求尝试比成功创建请求后的重试更快。 -如果你想禁用自动启动请求，请设置 `startupVerification: "off"`；如果你希望更短或更长的重试窗口，请调整 `startupVerificationCooldownHours`。 +当 `encryption: true` 时，Matrix 默认会将 `startupVerification` 设为 `"if-unverified"`。 +在启动时，如果此设备仍未验证，Matrix 会在另一个 Matrix 客户端中请求自我验证，在已有请求待处理时跳过重复请求，并在重启后重试前应用本地冷却时间。 +默认情况下，失败的请求尝试会比成功创建请求后的重试更早再次尝试。 +如果你想禁用自动启动请求，请设置 `startupVerification: "off"`；如果你想缩短或延长重试窗口，请调整 `startupVerificationCooldownHours`。 -启动时还会自动执行一次保守的加密引导流程。 -该流程会优先尝试复用当前的秘密存储和跨签名身份，并避免重置跨签名，除非你运行显式的引导修复流程。 +启动时还会自动执行一轮保守的加密 bootstrap。 +该过程会优先尝试复用当前的 secret storage 和 cross-signing 身份，除非你运行显式的 bootstrap 修复流程，否则不会重置 cross-signing。 -如果启动时发现引导状态已损坏，且配置了 `channels.matrix.password`，OpenClaw 可以尝试更严格的修复路径。 -如果当前设备已经带有所有者签名，OpenClaw 会保留该身份，而不是自动重置它。 +如果启动时发现 bootstrap 状态损坏，且已配置 `channels.matrix.password`，OpenClaw 可以尝试更严格的修复路径。 +如果当前设备已经由 owner 签名，OpenClaw 会保留该身份，而不会自动重置。 -从上一版公开 Matrix 插件升级时： +从上一个公开 Matrix 插件升级时： -- OpenClaw 会在可能的情况下自动复用相同的 Matrix 账户、访问令牌和设备身份。 -- 在执行任何可操作的 Matrix 迁移更改之前，OpenClaw 会在 `~/Backups/openclaw-migrations/` 下创建或复用恢复快照。 -- 如果你使用多个 Matrix 账户，请在从旧的平面存储布局升级前先设置 `channels.matrix.defaultAccount`，这样 OpenClaw 才知道应将共享旧状态分配给哪个账户。 -- 如果之前的插件在本地存储了 Matrix 房间密钥备份解密密钥，启动流程或 `openclaw doctor --fix` 会自动将其导入新的恢复密钥流程。 -- 如果 Matrix 访问令牌在迁移准备完成后发生变化，启动时现在会在放弃自动备份恢复之前，扫描同级的令牌哈希存储根目录以查找待恢复的旧状态。 -- 如果同一账户、homeserver 和用户之后又更换了 Matrix 访问令牌，OpenClaw 现在会优先复用最完整的现有令牌哈希存储根目录，而不是从空的 Matrix 状态目录开始。 +- OpenClaw 会在可能时自动复用相同的 Matrix 账号、access token 和设备身份。 +- 在运行任何可执行的 Matrix 迁移更改之前，OpenClaw 会在 `~/Backups/openclaw-migrations/` 下创建或复用恢复快照。 +- 如果你使用多个 Matrix 账号，请在从旧的平面存储布局升级前设置 `channels.matrix.defaultAccount`，这样 OpenClaw 才知道应将共享的旧状态交给哪个账号。 +- 如果之前的插件在本地存储了 Matrix 房间密钥备份解密密钥，启动过程或 `openclaw doctor --fix` 会自动将其导入到新的恢复密钥流程中。 +- 如果 Matrix access token 在准备迁移之后发生了变化，启动时现在会扫描同级 token-hash 存储根目录中待恢复的旧状态，而不是立即放弃自动备份恢复。 +- 如果同一账号、homeserver 和用户稍后更换了 Matrix access token，OpenClaw 现在会优先复用最完整的现有 token-hash 存储根，而不是从空的 Matrix 状态目录开始。 - 在下一次 Gateway 网关启动时，已备份的房间密钥会自动恢复到新的加密存储中。 -- 如果旧插件存在从未备份的仅本地房间密钥，OpenClaw 会明确发出警告。这些密钥无法从之前的 rust 加密存储中自动导出，因此某些旧的加密历史可能仍然不可用，直到手动恢复为止。 -- 完整的升级流程、限制、恢复命令和常见迁移消息，请参阅 [Matrix migration](/zh-CN/install/migrating-matrix)。 +- 如果旧插件中存在从未备份的仅本地房间密钥，OpenClaw 会明确发出警告。由于这些密钥无法从之前的 rust crypto store 中自动导出，因此在手动恢复之前，某些旧的加密历史可能仍然不可用。 +- 完整升级流程、限制、恢复命令和常见迁移消息请参阅 [Matrix 迁移](/zh-CN/install/migrating-matrix)。 -加密运行时状态按每账户、每用户、每令牌哈希根目录组织，路径位于 +加密运行时状态按每个账号、每个用户的 token-hash 根目录组织，路径位于 `~/.openclaw/matrix/accounts//__//`。 -当这些功能被使用时，该目录包含同步存储（`bot-storage.json`）、加密存储（`crypto/`）、 +该目录在使用相关功能时包含同步存储（`bot-storage.json`）、加密存储（`crypto/`）、 恢复密钥文件（`recovery-key.json`）、IndexedDB 快照（`crypto-idb-snapshot.json`）、 -线程绑定（`thread-bindings.json`）和启动验证状态（`startup-verification.json`）。 -当令牌变更但账户身份保持不变时，OpenClaw 会为该账户 / homeserver / 用户元组复用最佳现有 -根目录，以便先前的同步状态、加密状态、线程绑定 -和启动验证状态保持可见。 +线程绑定（`thread-bindings.json`）以及启动验证状态（`startup-verification.json`）。 +当 token 改变但账号身份保持不变时，OpenClaw 会为该账号/homeserver/用户元组复用最佳现有根目录，以便先前的同步状态、加密状态、线程绑定和启动验证状态保持可见。 ### Node 加密存储模型 -此插件中的 Matrix E2EE 在 Node 中使用官方 `matrix-js-sdk` 的 Rust 加密路径。 -当你希望加密状态在重启后仍然保留时，该路径需要基于 IndexedDB 的持久化。 +此插件中的 Matrix E2EE 在 Node 中使用官方 `matrix-js-sdk` Rust 加密路径。 +如果你希望加密状态在重启后继续保留，这一路径要求使用基于 IndexedDB 的持久化。 -OpenClaw 当前在 Node 中通过以下方式提供这一能力： +OpenClaw 当前在 Node 中通过以下方式提供支持： -- 使用 `fake-indexeddb` 作为 SDK 所期望的 IndexedDB API 垫片 +- 使用 `fake-indexeddb` 作为 SDK 所要求的 IndexedDB API shim - 在 `initRustCrypto` 之前，从 `crypto-idb-snapshot.json` 恢复 Rust 加密 IndexedDB 内容 - 在初始化后和运行期间，将更新后的 IndexedDB 内容持久化回 `crypto-idb-snapshot.json` -- 使用建议性文件锁，围绕 `crypto-idb-snapshot.json` 串行化快照恢复与持久化，以避免 Gateway 网关运行时持久化与 CLI 维护在同一个快照文件上发生竞争 +- 通过建议性文件锁，对 `crypto-idb-snapshot.json` 的快照恢复和持久化进行串行化，以避免 Gateway 网关运行时持久化与 CLI 维护操作在同一快照文件上发生竞争 -这是兼容性 / 存储层管线，而不是自定义加密实现。 -快照文件属于敏感运行时状态，并采用严格的文件权限进行存储。 -在 OpenClaw 的安全模型下，Gateway 网关主机和本地 OpenClaw 状态目录已经位于受信任的操作员边界之内，因此这主要是一个操作持久性问题，而不是单独的远程信任边界。 +这属于兼容性/存储管线，而不是自定义加密实现。 +该快照文件属于敏感运行时状态，并以严格的文件权限存储。 +按照 OpenClaw 的安全模型，Gateway 网关主机和本地 OpenClaw 状态目录本来就位于受信任的操作员边界之内，因此这主要是一个运行耐久性问题，而不是单独的远程信任边界问题。 计划中的改进： -- 为持久 Matrix 密钥材料添加 SecretRef 支持，以便恢复密钥和相关存储加密密钥可来自 OpenClaw 密钥提供商，而不只是本地文件 +- 为持久化的 Matrix 密钥材料添加 SecretRef 支持，以便恢复密钥及相关的存储加密 secret 可通过 OpenClaw secrets 提供商提供，而不仅限于本地文件 -## 资料管理 +## 配置文件管理 -使用以下命令更新所选账户的 Matrix 自身资料： +使用以下命令更新所选账号的 Matrix 自身配置文件： ```bash openclaw matrix profile set --name "OpenClaw Assistant" openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png ``` -当你希望明确针对某个命名 Matrix 账户时，请添加 `--account `。 +当你想显式针对某个命名账号时，请添加 `--account `。 -Matrix 可直接接受 `mxc://` 头像 URL。当你传入 `http://` 或 `https://` 头像 URL 时，OpenClaw 会先将其上传到 Matrix，然后将解析后的 `mxc://` URL 回写到 `channels.matrix.avatarUrl`（或所选账户的覆盖项）中。 +Matrix 可直接接受 `mxc://` 头像 URL。当你传入 `http://` 或 `https://` 头像 URL 时，OpenClaw 会先将其上传到 Matrix，然后将解析后的 `mxc://` URL 回写到 `channels.matrix.avatarUrl`（或所选账号的覆盖项）中。 ## 自动验证通知 -Matrix 现在会将验证生命周期通知直接作为 `m.notice` 消息发布到严格的私信验证房间中。 -其中包括： +Matrix 现在会将验证生命周期通知直接作为 `m.notice` 消息发布到严格私信验证房间中。 +这包括： - 验证请求通知 -- 验证就绪通知（附带明确的“通过表情符号验证”指引） +- 验证就绪通知（带有明确的“通过表情符号验证”指引） - 验证开始和完成通知 -- 可用时的 SAS 详细信息（表情符号和十进制） +- SAS 详情（表情符号和十进制），如果可用 来自另一个 Matrix 客户端的传入验证请求会被 OpenClaw 跟踪并自动接受。 -对于自验证流程，OpenClaw 还会在表情符号验证可用时自动启动 SAS 流程，并确认自己的这一侧。 -对于来自另一个 Matrix 用户 / 设备的验证请求，OpenClaw 会自动接受请求，然后等待 SAS 流程正常继续。 -你仍然需要在你的 Matrix 客户端中比较表情符号或十进制 SAS，并在那里确认“它们匹配”，才能完成验证。 +对于自我验证流程，当表情符号验证可用时，OpenClaw 也会自动启动 SAS 流程并确认自己这一侧。 +对于来自另一位 Matrix 用户/设备的验证请求，OpenClaw 会自动接受请求，然后等待 SAS 流程正常继续。 +你仍然需要在你的 Matrix 客户端中比较表情符号或十进制 SAS，并在其中确认“它们匹配”，才能完成验证。 -OpenClaw 不会盲目自动接受由自己发起的重复流程。若已有自验证请求处于待处理状态，启动时会跳过创建新的请求。 +OpenClaw 不会盲目自动接受由自己发起的重复流程。当自我验证请求已在待处理中时，启动过程会跳过创建新请求。 -验证协议 / 系统通知不会转发到智能体聊天管线，因此不会产生 `NO_REPLY`。 +验证协议/系统通知不会转发到智能体聊天管线，因此不会产生 `NO_REPLY`。 ### 设备清理 -由 OpenClaw 管理的旧 Matrix 设备可能会在账户中逐渐累积，使加密房间的信任状态更难判断。 -可使用以下命令列出它们： +旧的由 OpenClaw 管理的 Matrix 设备可能会在账号上不断累积，使加密房间中的信任关系更难理解。 +使用以下命令列出它们： ```bash openclaw matrix devices list ``` -使用以下命令移除过期的 OpenClaw 管理设备： +使用以下命令移除过时的 OpenClaw 管理设备： ```bash openclaw matrix devices prune-stale @@ -498,48 +492,53 @@ openclaw matrix devices prune-stale ### 直接房间修复 -如果私信状态不同步，OpenClaw 可能会留下陈旧的 `m.direct` 映射，指向旧的单人房间而不是当前的私信。可使用以下命令检查某个对端的当前映射： +如果私信状态不同步，OpenClaw 最终可能会留下过时的 `m.direct` 映射，这些映射指向旧的单人房间，而不是当前的活跃私信。使用以下命令检查某个对等方的当前映射： ```bash openclaw matrix direct inspect --user-id @alice:example.org ``` -使用以下命令修复它： +使用以下命令修复： ```bash openclaw matrix direct repair --user-id @alice:example.org ``` -修复会将 Matrix 专属逻辑保留在插件内部： +修复逻辑会将 Matrix 专用逻辑保留在插件内部： -- 它会优先选择已映射在 `m.direct` 中的严格 1:1 私信 -- 否则会回退到与该用户当前已加入的任意严格 1:1 私信 -- 如果不存在健康的私信，它会创建一个新的直接房间，并重写 `m.direct` 使其指向该房间 +- 优先选择已在 `m.direct` 中映射的严格 1:1 私信 +- 否则回退到与该用户当前已加入的任意严格 1:1 私信 +- 如果不存在健康的私信，则创建一个新的直连房间，并重写 `m.direct` 使其指向该房间 -修复流程不会自动删除旧房间。它只会选定健康的私信并更新映射，这样新的 Matrix 发送、验证通知和其他私信流程就会再次指向正确的房间。 +修复流程不会自动删除旧房间。它只会选择健康的私信并更新映射，以便新的 Matrix 发送、验证通知和其他直连消息流再次正确地指向目标房间。 ## 线程 -Matrix 同时支持用于自动回复和消息工具发送的原生 Matrix 线程。 +Matrix 同时支持自动回复和 message-tool 发送中的原生 Matrix 线程。 -- `threadReplies: "off"` 会让回复保持在顶层，并将传入的线程消息保留在父会话上。 -- `threadReplies: "inbound"` 仅当传入消息本来就在该线程中时，才在线程内回复。 -- `threadReplies: "always"` 会将房间回复保留在以触发消息为根的线程中，并从第一条触发消息开始，通过匹配的线程作用域会话路由该对话。 -- `dm.threadReplies` 仅覆盖私信的顶层设置。例如，你可以让房间线程保持隔离，同时让私信保持扁平。 -- 传入的线程消息会将线程根消息作为额外的智能体上下文包含进来。 -- 当目标是同一房间或同一私信用户目标时，消息工具发送现在会自动继承当前 Matrix 线程，除非明确提供了 `threadId`。 +- `dm.sessionScope: "per-user"`（默认）会让 Matrix 私信路由保持按发送者作用域，因此多个私信房间在解析到同一个对等方时可以共享一个会话。 +- `dm.sessionScope: "per-room"` 会将每个 Matrix 私信房间隔离到各自的会话键中，同时仍使用正常的私信认证和 allowlist 检查。 +- 显式的 Matrix 会话绑定仍然优先于 `dm.sessionScope`，因此已绑定的房间和线程会保持它们选择的目标会话。 +- `threadReplies: "off"` 会让回复保持在顶层，并让传入的线程消息进入父会话。 +- `threadReplies: "inbound"` 仅当传入消息本来就在某个线程中时，才在线程内回复。 +- `threadReplies: "always"` 会让房间回复保持在线程中，并以触发消息为根路由该会话，通过第一次触发消息所匹配的线程作用域会话继续。 +- `dm.threadReplies` 仅为私信覆盖顶层设置。例如，你可以让房间线程保持隔离，同时让私信保持平铺。 +- 传入的线程消息会将线程根消息作为额外的智能体上下文。 +- 现在，当目标为同一房间或同一私信用户目标，且未提供显式 `threadId` 时，message-tool 发送会自动继承当前 Matrix 线程。 +- 仅当当前会话元数据能证明是同一 Matrix 账号上的同一私信对等方时，同会话私信用户目标复用才会生效；否则 OpenClaw 会回退到常规的用户作用域路由。 +- 当 OpenClaw 发现某个 Matrix 私信房间与同一共享 Matrix 私信会话上的另一个私信房间发生冲突时，如果启用了线程绑定并存在 `dm.sessionScope` 提示，它会在该房间中发布一次性 `m.notice`，并附带 `/focus` 逃生口。 - Matrix 支持运行时线程绑定。`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 和线程绑定的 `/acp spawn` 现在都可在 Matrix 房间和私信中使用。 -- 当 `threadBindings.spawnSubagentSessions=true` 时，顶层 Matrix 房间 / 私信中的 `/focus` 会创建一个新的 Matrix 线程，并将其绑定到目标会话。 -- 在现有 Matrix 线程中运行 `/focus` 或 `/acp spawn --thread here`，则会改为绑定当前线程。 +- 当 `threadBindings.spawnSubagentSessions=true` 时，在顶层 Matrix 房间/私信中执行 `/focus` 会创建一个新的 Matrix 线程并将其绑定到目标会话。 +- 在现有 Matrix 线程中运行 `/focus` 或 `/acp spawn --thread here` 时，则会改为绑定当前线程。 -## ACP 对话绑定 +## ACP 会话绑定 -Matrix 房间、私信和现有 Matrix 线程都可以在不改变聊天界面的情况下，变成持久化的 ACP 工作区。 +Matrix 房间、私信和现有 Matrix 线程都可以变成持久的 ACP 工作区，而无需改变聊天界面。 -快速操作流程： +快速操作员流程： -- 在你希望继续使用的 Matrix 私信、房间或现有线程中运行 `/acp spawn codex --bind here`。 -- 在顶层 Matrix 私信或房间中，当前私信 / 房间会继续作为聊天界面，后续消息会路由到新建的 ACP 会话。 +- 在你想继续使用的 Matrix 私信、房间或现有线程中运行 `/acp spawn codex --bind here`。 +- 在顶层 Matrix 私信或房间中，当前私信/房间会保持为聊天界面，后续消息将路由到新生成的 ACP 会话。 - 在现有 Matrix 线程中，`--bind here` 会将当前线程原地绑定。 - `/new` 和 `/reset` 会原地重置同一个已绑定的 ACP 会话。 - `/acp close` 会关闭 ACP 会话并移除绑定。 @@ -547,11 +546,11 @@ Matrix 房间、私信和现有 Matrix 线程都可以在不改变聊天界面 说明： - `--bind here` 不会创建子 Matrix 线程。 -- 只有在 `/acp spawn --thread auto|here` 这种 OpenClaw 需要创建或绑定子 Matrix 线程的情况下，才需要 `threadBindings.spawnAcpSessions`。 +- 只有在使用 `/acp spawn --thread auto|here` 且 OpenClaw 需要创建或绑定子 Matrix 线程时，才需要 `threadBindings.spawnAcpSessions`。 ### 线程绑定配置 -Matrix 继承 `session.threadBindings` 的全局默认值，同时也支持按渠道覆盖： +Matrix 会继承 `session.threadBindings` 中的全局默认值，同时也支持按渠道覆盖： - `threadBindings.enabled` - `threadBindings.idleHours` @@ -559,29 +558,29 @@ Matrix 继承 `session.threadBindings` 的全局默认值，同时也支持按 - `threadBindings.spawnSubagentSessions` - `threadBindings.spawnAcpSessions` -Matrix 线程绑定的生成标志为选择启用： +Matrix 线程绑定的生成标志为可选启用： - 设置 `threadBindings.spawnSubagentSessions: true` 以允许顶层 `/focus` 创建并绑定新的 Matrix 线程。 - 设置 `threadBindings.spawnAcpSessions: true` 以允许 `/acp spawn --thread auto|here` 将 ACP 会话绑定到 Matrix 线程。 ## 回应 -Matrix 支持出站回应操作、入站回应通知和入站 ack 回应。 +Matrix 支持出站回应操作、入站回应通知和入站确认回应。 - 出站回应工具受 `channels["matrix"].actions.reactions` 控制。 - `react` 会向特定 Matrix 事件添加一个回应。 - `reactions` 会列出特定 Matrix 事件当前的回应摘要。 -- `emoji=""` 会移除机器人账户在该事件上的所有回应。 -- `remove: true` 仅移除机器人账户的指定表情回应。 +- `emoji=""` 会移除 bot 账号自己在该事件上的回应。 +- `remove: true` 只会移除 bot 账号上的指定表情回应。 -ack 回应使用标准的 OpenClaw 解析顺序： +确认回应的解析顺序遵循标准 OpenClaw 解析顺序： - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` - 智能体身份 emoji 回退 -ack 回应作用域按以下顺序解析： +确认回应作用域按以下顺序解析： - `channels["matrix"].accounts..ackReactionScope` - `channels["matrix"].ackReactionScope` @@ -595,29 +594,29 @@ ack 回应作用域按以下顺序解析： 当前行为： -- `reactionNotifications: "own"` 会在新增的 `m.reaction` 事件目标为机器人所发送的 Matrix 消息时转发这些事件。 +- `reactionNotifications: "own"` 会在目标是 bot 撰写的 Matrix 消息时，转发新增的 `m.reaction` 事件。 - `reactionNotifications: "off"` 会禁用回应系统事件。 -- 由于 Matrix 将回应移除作为 redaction 而不是独立的 `m.reaction` 移除事件提供，因此回应移除目前仍不会被合成为系统事件。 +- 回应移除仍不会被合成为系统事件，因为 Matrix 将它们作为 redact 而不是独立的 `m.reaction` 移除来呈现。 ## 历史上下文 -- `channels.matrix.historyLimit` 控制当 Matrix 房间消息触发智能体时，作为 `InboundHistory` 包含多少条最近房间消息。 +- `channels.matrix.historyLimit` 控制当 Matrix 房间消息触发智能体时，作为 `InboundHistory` 包含多少最近房间消息。 - 它会回退到 `messages.groupChat.historyLimit`。设置为 `0` 可禁用。 -- Matrix 房间历史仅限房间。私信仍使用普通会话历史。 -- Matrix 房间历史为待处理模式：OpenClaw 会缓冲那些尚未触发回复的房间消息，然后在收到提及或其他触发时对该窗口进行快照。 -- 当前触发消息不会包含在 `InboundHistory` 中；它会在该轮的主入站正文中保留。 -- 同一 Matrix 事件的重试会复用原始历史快照，而不会漂移到更新的房间消息。 +- Matrix 房间历史仅限房间。私信仍使用常规会话历史。 +- Matrix 房间历史仅适用于待处理消息：OpenClaw 会缓冲尚未触发回复的房间消息，然后在提及或其他触发到来时快照该窗口。 +- 当前触发消息不会包含在 `InboundHistory` 中；它会保留在该轮的主入站正文中。 +- 对同一 Matrix 事件的重试会复用原始历史快照，而不会漂移到更新的房间消息。 ## 上下文可见性 -Matrix 支持共享的 `contextVisibility` 控制，用于补充房间上下文，例如获取的回复文本、线程根和待处理历史。 +Matrix 支持共享的 `contextVisibility` 控制，用于补充房间上下文，例如获取到的回复文本、线程根和待处理历史。 -- `contextVisibility: "all"` 是默认值。补充上下文会按接收到的内容保留。 -- `contextVisibility: "allowlist"` 会根据当前房间 / 用户 allowlist 检查，将补充上下文过滤为仅允许的发送者。 -- `contextVisibility: "allowlist_quote"` 的行为类似于 `allowlist`，但仍会保留一条明确引用的回复。 +- `contextVisibility: "all"` 是默认值。补充上下文会按接收时原样保留。 +- `contextVisibility: "allowlist"` 会将补充上下文过滤为仅保留通过当前房间/用户 allowlist 检查的发送者内容。 +- `contextVisibility: "allowlist_quote"` 的行为与 `allowlist` 类似，但仍会保留一条显式引用回复。 -此设置影响的是补充上下文的可见性，而不是入站消息本身是否能够触发回复。 -触发授权仍然来自 `groupPolicy`、`groups`、`groupAllowFrom` 和私信策略设置。 +此设置影响的是补充上下文的可见性，而不是入站消息本身是否可以触发回复。 +触发授权仍来自 `groupPolicy`、`groups`、`groupAllowFrom` 和私信策略设置。 ## 私信和房间策略示例 @@ -642,7 +641,7 @@ Matrix 支持共享的 `contextVisibility` 控制，用于补充房间上下文 } ``` -有关提及门控和 allowlist 行为，请参阅 [Groups](/zh-CN/channels/groups)。 +有关提及门控和 allowlist 行为，请参阅 [群组](/zh-CN/channels/groups)。 Matrix 私信的配对示例： @@ -651,53 +650,53 @@ openclaw pairing list matrix openclaw pairing approve matrix ``` -如果一个尚未获批的 Matrix 用户在批准前持续向你发送消息，OpenClaw 会复用同一个待处理配对码，并且在短暂冷却后可能再次发送提醒回复，而不是生成新的配对码。 +如果某个尚未批准的 Matrix 用户在批准前持续向你发送消息，OpenClaw 会复用同一个待处理的配对码，并且在短暂冷却后可能再次发送提醒回复，而不是生成新的配对码。 -有关共享的私信配对流程和存储布局，请参阅 [Pairing](/zh-CN/channels/pairing)。 +有关共享的私信配对流程和存储布局，请参阅 [配对](/zh-CN/channels/pairing)。 ## Exec 审批 -Matrix 可以作为某个 Matrix 账户的 exec 审批客户端。 +Matrix 可以作为某个 Matrix 账号的 exec 审批客户端。 - `channels.matrix.execApprovals.enabled` -- `channels.matrix.execApprovals.approvers`（可选；回退到 `channels.matrix.dm.allowFrom`） -- `channels.matrix.execApprovals.target`（`dm` | `channel` | `both`，默认值：`dm`） +- `channels.matrix.execApprovals.approvers`（可选；会回退到 `channels.matrix.dm.allowFrom`） +- `channels.matrix.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`） - `channels.matrix.execApprovals.agentFilter` - `channels.matrix.execApprovals.sessionFilter` -审批者必须是 Matrix 用户 ID，例如 `@owner:example.org`。当 `enabled` 未设置或为 `"auto"`，且至少能从 `execApprovals.approvers` 或 `channels.matrix.dm.allowFrom` 解析出一个审批者时，Matrix 会自动启用原生 exec 审批。将 `enabled: false` 设为显式禁用 Matrix 作为原生审批客户端。否则，审批请求会回退到其他已配置的审批路由或 exec 审批回退策略。 +审批人必须是 Matrix 用户 ID，例如 `@owner:example.org`。当 `enabled` 未设置或为 `"auto"`，且至少能解析出一位审批人时，Matrix 会自动启用原生 exec 审批；审批人可来自 `execApprovals.approvers` 或 `channels.matrix.dm.allowFrom`。设置 `enabled: false` 可显式禁用 Matrix 作为原生审批客户端。否则，审批请求会回退到其他已配置的审批路由或 exec 审批回退策略。 -Matrix 原生路由目前仅用于 exec： +原生 Matrix 路由目前仅支持 exec： -- `channels.matrix.execApprovals.*` 仅控制 exec 审批的原生私信 / 渠道路由。 +- `channels.matrix.execApprovals.*` 仅控制 exec 审批的原生私信/渠道路由。 - 插件审批仍使用共享的同聊天 `/approve`，以及任何已配置的 `approvals.plugin` 转发。 -- 当 Matrix 能安全推断审批者时，它仍可复用 `channels.matrix.dm.allowFrom` 用于插件审批授权，但它不会暴露单独的原生插件审批私信 / 渠道分发路径。 +- 当 Matrix 能够安全推断审批人时，它仍可复用 `channels.matrix.dm.allowFrom` 进行插件审批授权，但它不会暴露单独的原生插件审批私信/渠道扇出路径。 投递规则： -- `target: "dm"` 会将审批提示发送到审批者私信 -- `target: "channel"` 会将提示发送回原始 Matrix 房间或私信 -- `target: "both"` 会同时发送到审批者私信和原始 Matrix 房间或私信 +- `target: "dm"` 会将审批提示发送到审批人私信 +- `target: "channel"` 会将提示发回原始 Matrix 房间或私信 +- `target: "both"` 会同时发送到审批人私信和原始 Matrix 房间或私信 Matrix 审批提示会在主审批消息上预置回应快捷方式： - `✅` = 允许一次 - `❌` = 拒绝 -- `♾️` = 当该决定被有效 exec 策略允许时，始终允许 +- `♾️` = 当该决策受当前 exec 策略允许时，始终允许 -审批者可以对该消息添加回应，或使用后备斜杠命令：`/approve allow-once`、`/approve allow-always` 或 `/approve deny`。 +审批人可以对该消息添加回应，或使用回退斜杠命令：`/approve allow-once`、`/approve allow-always` 或 `/approve deny`。 -只有已解析的审批者才能批准或拒绝。渠道投递会包含命令文本，因此只有在受信任房间中才启用 `channel` 或 `both`。 +只有已解析的审批人可以批准或拒绝。渠道投递会包含命令文本，因此只有在受信任房间中才应启用 `channel` 或 `both`。 -Matrix 审批提示复用了共享核心审批规划器。Matrix 专属的原生界面只是 exec 审批的传输层：房间 / 私信路由以及消息发送 / 更新 / 删除行为。 +Matrix 审批提示复用共享核心审批规划器。Matrix 专用的原生界面仅作为 exec 审批的传输层：房间/私信路由以及消息发送/更新/删除行为。 -按账户覆盖： +按账号覆盖： - `channels.matrix.accounts..execApprovals` -相关文档：[Exec approvals](/zh-CN/tools/exec-approvals) +相关文档：[Exec 审批](/zh-CN/tools/exec-approvals) -## 多账户示例 +## 多账号示例 ```json5 { @@ -727,22 +726,20 @@ Matrix 审批提示复用了共享核心审批规划器。Matrix 专属的原生 } ``` -除非账户自行覆盖，否则顶层 `channels.matrix` 值会作为命名账户的默认值。 -你可以通过 `groups..account`（或旧版 `rooms..account`）将继承的房间条目限制到某个 Matrix 账户。 -未设置 `account` 的条目会在所有 Matrix 账户之间共享，而带有 `account: "default"` 的条目在默认账户直接配置于顶层 `channels.matrix.*` 时仍然有效。 -仅有部分共享认证默认值本身不会创建单独的隐式默认账户。只有当该默认账户具有新的认证信息（`homeserver` 加 `accessToken`，或 `homeserver` 加 `userId` 和 `password`）时，OpenClaw 才会合成顶层 `default` 账户；命名账户在缓存凭证稍后满足认证条件时，仍可仅凭 `homeserver` 加 `userId` 保持可发现。 -如果 Matrix 已经恰好存在一个命名账户，或者 `defaultAccount` 指向现有命名账户键，那么单账户到多账户的修复 / 设置升级会保留该账户，而不会新建 `accounts.default` 条目。只有 Matrix 认证 / 引导键会移动到该升级后的账户中；共享投递策略键仍保留在顶层。 -当你希望 OpenClaw 在隐式路由、探测和 CLI 操作中优先使用某个命名 Matrix 账户时，请设置 `defaultAccount`。 -如果你配置了多个命名账户，请设置 `defaultAccount`，或为依赖隐式账户选择的 CLI 命令传递 `--account `。 -当你希望为单个命令覆盖该隐式选择时，请向 `openclaw matrix verify ...` 和 `openclaw matrix devices ...` 传递 `--account `。 +除非账号自行覆盖，否则顶层 `channels.matrix` 值会作为命名账号的默认值。 +你可以使用 `groups..account`（或旧版 `rooms..account`）将继承的房间条目限定到某一个 Matrix 账号。 +不带 `account` 的条目会在所有 Matrix 账号之间共享，而带有 `account: "default"` 的条目在默认账号直接配置在顶层 `channels.matrix.*` 时仍然有效。 +部分共享认证默认值本身不会创建单独的隐式默认账号。只有当该默认账号拥有新的认证信息（`homeserver` 加 `accessToken`，或 `homeserver` 加 `userId` 和 `password`）时，OpenClaw 才会合成顶层 `default` 账号；命名账号仍可依靠 `homeserver` 加 `userId` 保持可发现性，只要后续缓存凭证能够满足认证。 +如果 Matrix 已经正好有一个命名账号，或 `defaultAccount` 指向现有命名账号键，那么单账号到多账号的修复/设置升级会保留该账号，而不是新建一个 `accounts.default` 条目。只有 Matrix 认证/bootstrap 键会移动到升级后的账号中；共享投递策略键会保留在顶层。 +当你希望 OpenClaw 在隐式路由、探测和 CLI 操作中优先使用某个命名 Matrix 账号时，请设置 `defaultAccount`。 +如果你配置了多个命名账号，请设置 `defaultAccount`，或在依赖隐式账号选择的 CLI 命令中传入 `--account `。 +当你希望为某条命令覆盖该隐式选择时，请将 `--account ` 传给 `openclaw matrix verify ...` 和 `openclaw matrix devices ...`。 -## 私有 / LAN homeserver +## 私有/LAN homeserver -默认情况下，OpenClaw 会阻止连接私有 / 内部 Matrix homeserver，以防 SSRF，除非你 -为每个账户显式选择启用。 +默认情况下，出于 SSRF 防护考虑，OpenClaw 会阻止连接私有/内部 Matrix homeserver，除非你为每个账号显式选择加入。 -如果你的 homeserver 运行在 localhost、LAN/Tailscale IP 或内部主机名上，请为 -该 Matrix 账户启用 `allowPrivateNetwork`： +如果你的 homeserver 运行在 localhost、LAN/Tailscale IP 或内部主机名上，请为该 Matrix 账号启用 `allowPrivateNetwork`： ```json5 { @@ -766,12 +763,12 @@ openclaw matrix account add \ --access-token syt_ops_xxx ``` -此选择启用仅允许受信任的私有 / 内部目标。公共明文 homeserver，例如 -`http://matrix.example.org:8008`，仍然会被阻止。请尽可能优先使用 `https://`。 +此选择加入仅允许受信任的私有/内部目标。公共明文 homeserver，例如 +`http://matrix.example.org:8008`，仍会被阻止。请尽可能优先使用 `https://`。 ## 代理 Matrix 流量 -如果你的 Matrix 部署需要显式出站 HTTP(S) 代理，请设置 `channels.matrix.proxy`： +如果你的 Matrix 部署需要显式的出站 HTTP(S) 代理，请设置 `channels.matrix.proxy`： ```json5 { @@ -785,85 +782,86 @@ openclaw matrix account add \ } ``` -命名账户可以通过 `channels.matrix.accounts..proxy` 覆盖顶层默认值。 -OpenClaw 会将同一代理设置用于运行时 Matrix 流量和账户状态探测。 +命名账号可以使用 `channels.matrix.accounts..proxy` 覆盖顶层默认值。 +OpenClaw 会将同一代理设置用于运行时 Matrix 流量和账号状态探测。 ## 目标解析 -在 OpenClaw 要求你提供房间或用户目标的任何地方，Matrix 都接受以下目标形式： +在 OpenClaw 任何要求你输入房间或用户目标的地方，Matrix 都接受以下目标形式： - 用户：`@user:server`、`user:@user:server` 或 `matrix:user:@user:server` - 房间：`!room:server`、`room:!room:server` 或 `matrix:room:!room:server` - 别名：`#alias:server`、`channel:#alias:server` 或 `matrix:channel:#alias:server` -实时目录查找使用已登录的 Matrix 账户： +实时目录查找使用已登录的 Matrix 账号： - 用户查找会查询该 homeserver 上的 Matrix 用户目录。 -- 房间查找会直接接受显式房间 ID 和别名，然后回退到搜索该账户已加入房间的名称。 -- 已加入房间名称查找是尽力而为的。如果房间名称无法解析为 ID 或别名，它会在运行时 allowlist 解析中被忽略。 +- 房间查找会直接接受显式房间 ID 和别名，然后回退到搜索该账号已加入的房间名称。 +- 已加入房间名称查找属于尽力而为。如果房间名称无法解析为 ID 或别名，运行时 allowlist 解析会忽略它。 ## 配置参考 - `enabled`：启用或禁用该渠道。 -- `name`：账户的可选标签。 -- `defaultAccount`：配置了多个 Matrix 账户时的首选账户 ID。 +- `name`：账号的可选标签。 +- `defaultAccount`：配置多个 Matrix 账号时的首选账号 ID。 - `homeserver`：homeserver URL，例如 `https://matrix.example.org`。 -- `allowPrivateNetwork`：允许该 Matrix 账户连接到私有 / 内部 homeserver。当 homeserver 解析为 `localhost`、LAN/Tailscale IP 或 `matrix-synapse` 这样的内部主机时，请启用此项。 -- `proxy`：Matrix 流量的可选 HTTP(S) 代理 URL。命名账户可以使用自己的 `proxy` 覆盖顶层默认值。 -- `userId`：完整 Matrix 用户 ID，例如 `@bot:example.org`。 -- `accessToken`：基于令牌认证的访问令牌。`channels.matrix.accessToken` 和 `channels.matrix.accounts..accessToken` 支持明文值和 SecretRef 值，适用于 env/file/exec 提供商。请参阅 [Secrets Management](/zh-CN/gateway/secrets)。 +- `allowPrivateNetwork`：允许此 Matrix 账号连接到私有/内部 homeserver。当 homeserver 解析为 `localhost`、LAN/Tailscale IP 或诸如 `matrix-synapse` 之类的内部主机时，请启用此项。 +- `proxy`：Matrix 流量的可选 HTTP(S) 代理 URL。命名账号可以用自己的 `proxy` 覆盖顶层默认值。 +- `userId`：完整的 Matrix 用户 ID，例如 `@bot:example.org`。 +- `accessToken`：基于 token 的认证 access token。`channels.matrix.accessToken` 和 `channels.matrix.accounts..accessToken` 支持跨 env/file/exec 提供商的明文值和 SecretRef 值。请参阅 [Secrets Management](/zh-CN/gateway/secrets)。 - `password`：基于密码登录的密码。支持明文值和 SecretRef 值。 - `deviceId`：显式 Matrix 设备 ID。 -- `deviceName`：密码登录的设备显示名称。 -- `avatarUrl`：用于资料同步和 `set-profile` 更新的已存储自身头像 URL。 -- `initialSyncLimit`：启动同步事件限制。 +- `deviceName`：用于密码登录的设备显示名称。 +- `avatarUrl`：用于配置文件同步和 `set-profile` 更新的已存储自身头像 URL。 +- `initialSyncLimit`：启动时同步事件限制。 - `encryption`：启用 E2EE。 -- `allowlistOnly`：对私信和房间强制执行仅 allowlist 行为。 -- `allowBots`：允许来自其他已配置 OpenClaw Matrix 账户的消息（`true` 或 `"mentions"`）。 +- `allowlistOnly`：强制对私信和房间仅使用 allowlist 行为。 +- `allowBots`：允许来自其他已配置 OpenClaw Matrix 账号的消息（`true` 或 `"mentions"`）。 - `groupPolicy`：`open`、`allowlist` 或 `disabled`。 -- `contextVisibility`：补充房间上下文的可见性模式（`all`、`allowlist`、`allowlist_quote`）。 +- `contextVisibility`：补充房间上下文可见性模式（`all`、`allowlist`、`allowlist_quote`）。 - `groupAllowFrom`：房间流量的用户 ID allowlist。 -- `groupAllowFrom` 条目应为完整的 Matrix 用户 ID。未解析的名称会在运行时被忽略。 -- `historyLimit`：作为群组历史上下文包含的最大房间消息数。会回退到 `messages.groupChat.historyLimit`。设置为 `0` 可禁用。 +- `groupAllowFrom` 条目应为完整的 Matrix 用户 ID。无法解析的名称会在运行时被忽略。 +- `historyLimit`：作为群组历史上下文包含的最大房间消息数。会回退到 `messages.groupChat.historyLimit`。设置 `0` 可禁用。 - `replyToMode`：`off`、`first` 或 `all`。 - `markdown`：出站 Matrix 文本的可选 Markdown 渲染配置。 - `streaming`：`off`（默认）、`partial`、`true` 或 `false`。`partial` 和 `true` 会启用带原地编辑更新的单消息草稿预览。 -- `blockStreaming`：`true` 会在草稿预览流式传输激活时，为已完成的助手块启用单独的进度消息。 +- `blockStreaming`：`true` 会在草稿预览流式传输处于激活状态时，为已完成的 assistant 块启用单独进度消息。 - `threadReplies`：`off`、`inbound` 或 `always`。 - `threadBindings`：线程绑定会话路由和生命周期的按渠道覆盖。 -- `startupVerification`：启动时自动自验证请求模式（`if-unverified`、`off`）。 -- `startupVerificationCooldownHours`：自动启动验证请求重试前的冷却时间。 +- `startupVerification`：启动时自动自我验证请求模式（`if-unverified`、`off`）。 +- `startupVerificationCooldownHours`：自动启动验证请求再次尝试前的冷却时间。 - `textChunkLimit`：出站消息分块大小。 - `chunkMode`：`length` 或 `newline`。 - `responsePrefix`：出站回复的可选消息前缀。 -- `ackReaction`：该渠道 / 账户的可选 ack 回应覆盖值。 -- `ackReactionScope`：可选 ack 回应作用域覆盖（`group-mentions`、`group-all`、`direct`、`all`、`none`、`off`）。 +- `ackReaction`：此渠道/账号的可选确认回应覆盖。 +- `ackReactionScope`：可选的确认回应作用域覆盖（`group-mentions`、`group-all`、`direct`、`all`、`none`、`off`）。 - `reactionNotifications`：入站回应通知模式（`own`、`off`）。 -- `mediaMaxMb`：Matrix 媒体处理的媒体大小上限（MB）。它适用于出站发送和入站媒体处理。 +- `mediaMaxMb`：Matrix 媒体处理的媒体大小上限（MB）。适用于出站发送和入站媒体处理。 - `autoJoin`：邀请自动加入策略（`always`、`allowlist`、`off`）。默认值：`off`。 -- `autoJoinAllowlist`：当 `autoJoin` 为 `allowlist` 时允许的房间 / 别名。别名条目会在邀请处理期间解析为房间 ID；OpenClaw 不会信任受邀房间声明的别名状态。 -- `dm`：私信策略块（`enabled`、`policy`、`allowFrom`、`threadReplies`）。 -- `dm.allowFrom` 条目应为完整的 Matrix 用户 ID，除非你已经通过实时目录查找解析了它们。 -- `dm.threadReplies`：仅私信线程策略覆盖（`off`、`inbound`、`always`）。它会覆盖顶层 `threadReplies` 设置，影响私信中的回复位置和会话隔离。 +- `autoJoinAllowlist`：当 `autoJoin` 为 `allowlist` 时允许的房间/别名。别名条目会在处理邀请时解析为房间 ID；OpenClaw 不信任被邀请房间声称的别名状态。 +- `dm`：私信策略块（`enabled`、`policy`、`allowFrom`、`sessionScope`、`threadReplies`）。 +- `dm.allowFrom` 条目应为完整的 Matrix 用户 ID，除非你已经通过实时目录查找完成了解析。 +- `dm.sessionScope`：`per-user`（默认）或 `per-room`。如果你希望每个 Matrix 私信房间即使面对同一对等方也保留独立上下文，请使用 `per-room`。 +- `dm.threadReplies`：仅私信的线程策略覆盖（`off`、`inbound`、`always`）。它会覆盖顶层 `threadReplies` 设置，并同时影响私信中的回复位置和会话隔离。 - `execApprovals`：Matrix 原生 exec 审批投递（`enabled`、`approvers`、`target`、`agentFilter`、`sessionFilter`）。 -- `execApprovals.approvers`：允许批准 exec 请求的 Matrix 用户 ID。当 `dm.allowFrom` 已能识别审批者时，此项为可选。 -- `execApprovals.target`：`dm | channel | both`（默认值：`dm`）。 -- `accounts`：命名的按账户覆盖。顶层 `channels.matrix` 值会作为这些条目的默认值。 -- `groups`：按房间策略映射。优先使用房间 ID 或别名；未解析的房间名会在运行时被忽略。会话 / 群组标识在解析后使用稳定的房间 ID，而面向人的标签仍来自房间名称。 -- `groups..account`：在多账户设置中，将某个继承的房间条目限制到特定 Matrix 账户。 -- `groups..allowBots`：针对已配置机器人发送者的房间级覆盖（`true` 或 `"mentions"`）。 +- `execApprovals.approvers`：允许审批 exec 请求的 Matrix 用户 ID。当 `dm.allowFrom` 已经标识审批人时可选。 +- `execApprovals.target`：`dm | channel | both`（默认：`dm`）。 +- `accounts`：每个账号的命名覆盖项。顶层 `channels.matrix` 值会作为这些条目的默认值。 +- `groups`：按房间的策略映射。优先使用房间 ID 或别名；无法解析的房间名称会在运行时被忽略。解析后，会话/群组身份使用稳定的房间 ID，而人类可读标签仍来自房间名称。 +- `groups..account`：在多账号设置中，将一个继承的房间条目限制到特定 Matrix 账号。 +- `groups..allowBots`：已配置 bot 发送者的房间级覆盖（`true` 或 `"mentions"`）。 - `groups..users`：按房间的发送者 allowlist。 -- `groups..tools`：按房间的工具允许 / 拒绝覆盖。 -- `groups..autoReply`：房间级提及门控覆盖。`true` 会禁用该房间的提及要求；`false` 会再次强制启用。 -- `groups..skills`：可选的房间级 skill 过滤器。 -- `groups..systemPrompt`：可选的房间级 system prompt 片段。 -- `rooms`：`groups` 的旧别名。 -- `actions`：按动作的工具门控（`messages`、`reactions`、`pins`、`profile`、`memberInfo`、`channelInfo`、`verification`）。 +- `groups..tools`：按房间的工具允许/拒绝覆盖。 +- `groups..autoReply`：房间级提及门控覆盖。`true` 会禁用该房间的提及要求；`false` 会重新强制启用。 +- `groups..skills`：可选的房间级技能过滤器。 +- `groups..systemPrompt`：可选的房间级系统提示片段。 +- `rooms`：`groups` 的旧版别名。 +- `actions`：按操作的工具门控（`messages`、`reactions`、`pins`、`profile`、`memberInfo`、`channelInfo`、`verification`）。 -## 相关内容 +## 相关 -- [Channels Overview](/zh-CN/channels) — 所有受支持的渠道 -- [Pairing](/zh-CN/channels/pairing) — 私信认证和配对流程 -- [Groups](/zh-CN/channels/groups) — 群聊行为和提及门控 -- [Channel Routing](/zh-CN/channels/channel-routing) — 消息的会话路由 -- [Security](/zh-CN/gateway/security) — 访问模型和安全加固 +- [渠道概览](/zh-CN/channels) — 所有受支持的渠道 +- [配对](/zh-CN/channels/pairing) — 私信认证和配对流程 +- [群组](/zh-CN/channels/groups) — 群聊行为和提及门控 +- [渠道路由](/zh-CN/channels/channel-routing) — 消息的会话路由 +- [安全](/zh-CN/gateway/security) — 访问模型和加固 diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index 8b9d43893..3a189adca 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -1,21 +1,21 @@ --- read_when: - - 你需要精确的字段级配置语义或默认值 + - 你需要精确到字段级别的配置语义或默认值 - 你正在验证渠道、模型、Gateway 网关或工具配置块 summary: 每个 OpenClaw 配置键、默认值和渠道设置的完整参考 title: 配置参考 x-i18n: - generated_at: "2026-04-05T18:18:46Z" + generated_at: "2026-04-05T19:23:49Z" model: gpt-5.4 provider: openai - source_hash: c3b087ff868e25165e7b80dd7505f8b29c218cd6894304179b7a9426da231276 + source_hash: b2ac0b26762d642cd3667b3f18b11938947968e79d9cd363e86e31312ce7e981 source_path: gateway/configuration-reference.md workflow: 15 --- # 配置参考 -`~/.openclaw/openclaw.json` 中可用的每个字段。若需按任务组织的概览，请参见 [Configuration](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 中提供的每个字段。若要查看面向任务的概览，请参见 [Configuration](/zh-CN/gateway/configuration)。 配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的——省略时，OpenClaw 会使用安全的默认值。 @@ -23,34 +23,34 @@ x-i18n: ## 渠道 -每个渠道在其配置节存在时都会自动启动（除非设置了 `enabled: false`）。 +每个渠道只要存在其配置段，就会自动启动（除非设置了 `enabled: false`）。 ### 私信和群组访问 所有渠道都支持私信策略和群组策略： -| 私信策略 | 行为 | -| --------------------- | -------------------------------------------------------- | -| `pairing`（默认） | 未知发送者会收到一次性配对码；必须由所有者批准 | -| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对的允许存储） | -| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） | -| `disabled` | 忽略所有传入私信 | +| 私信策略 | 行为 | +| --------------------- | ------------------------------------- | +| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 | +| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对允许存储中的发送者） | +| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） | +| `disabled` | 忽略所有传入私信 | -| 群组策略 | 行为 | -| ----------------------- | ------------------------------------------------------ | -| `allowlist`（默认） | 仅允许与已配置允许列表匹配的群组 | -| `open` | 绕过群组允许列表（仍会应用提及门控） | -| `disabled` | 阻止所有群组/房间消息 | +| 群组策略 | 行为 | +| ----------------------- | ----------------------------------------- | +| `allowlist`（默认） | 仅允许与已配置允许列表匹配的群组 | +| `open` | 绕过群组允许列表（仍会应用提及门控） | +| `disabled` | 阻止所有群组/房间消息 | `channels.defaults.groupPolicy` 会在提供商的 `groupPolicy` 未设置时作为默认值。 -配对码会在 1 小时后过期。待处理的私信配对请求上限为**每个渠道 3 个**。 -如果提供商配置块完全缺失（即不存在 `channels.`），运行时群组策略会回退为 `allowlist`（默认拒绝），并在启动时发出警告。 +配对码会在 1 小时后过期。待处理的私信配对请求每个渠道上限为 **3 个**。 +如果某个提供商块完全缺失（不存在 `channels.`），运行时群组策略会回退为 `allowlist`（默认拒绝）并在启动时发出警告。 ### 渠道模型覆盖 -使用 `channels.modelByChannel` 可将特定渠道 ID 固定到某个模型。值可接受 `provider/model` 或已配置的模型别名。当会话尚未有模型覆盖时（例如通过 `/model` 设置），渠道映射才会生效。 +使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当某个会话尚未有模型覆盖时（例如通过 `/model` 设置），才会应用该渠道映射。 ```json5 { @@ -91,7 +91,7 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`：当提供商级 `groupPolicy` 未设置时的回退群组策略。 +- `channels.defaults.groupPolicy`：当提供商级 `groupPolicy` 未设置时使用的回退群组策略。 - `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。每渠道覆盖：`channels..contextVisibility`。 - `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康渠道状态。 - `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级/错误状态。 @@ -99,7 +99,7 @@ x-i18n: ### WhatsApp -WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在已关联的会话时会自动启动。 +WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。存在已关联的会话时会自动启动。 ```json5 { @@ -150,8 +150,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`。 @@ -182,13 +182,13 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在 }, }, customCommands: [ - { command: "backup", description: "Git backup" }, - { command: "generate", description: "Create an image" }, + { command: "backup", description: "Git 备份" }, + { command: "generate", description: "创建图像" }, ], historyLimit: 50, replyToMode: "first", // off | first | all linkPreview: true, - streaming: "partial", // off | partial | block | progress（默认：off；需显式启用以避免预览编辑速率限制） + streaming: "partial", // off | partial | block | progress（默认：off；为避免预览编辑频率限制，需要显式启用） actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -211,12 +211,12 @@ 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` 会发出警告。 +- 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` 会发出警告。 - `configWrites: false` 会阻止由 Telegram 发起的配置写入（超级群组 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`（在私聊和群聊中都可用）。 +- 顶层 `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)。 ### Discord @@ -264,7 +264,7 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在 requireMention: true, users: ["987654321098765432"], skills: ["docs"], - systemPrompt: "Short answers only.", + systemPrompt: "只给出简短回答。", }, }, }, @@ -272,7 +272,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（在 Discord 上，progress 会映射为 partial） maxLinesPerMessage: 17, ui: { components: { @@ -283,7 +283,7 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在 enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // 为 `sessions_spawn({ thread: true })` 显式启用 + spawnSubagentSessions: false, // 为 `sessions_spawn({ thread: true })` 选择性启用 }, voice: { enabled: true, @@ -319,36 +319,36 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在 } ``` -- Token：`channels.discord.token`，默认账号还可回退到 `DISCORD_BOT_TOKEN`。 -- 直接出站调用若显式提供 Discord `token`，将使用该 token 发起调用；账号级重试/策略设置仍来自当前运行时快照中选定的账号。 -- 可选的 `channels.discord.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 +- Token：`channels.discord.token`，默认账号可回退到 `DISCORD_BOT_TOKEN`。 +- 直接出站调用如果显式提供 Discord `token`，该次调用会使用该 token；账号重试/策略设置仍来自活动运行时快照中的已选账号。 +- 可选的 `channels.discord.defaultAccount` 会在其匹配已配置账号 ID 时覆盖默认账号选择。 - 使用 `user:`（私信）或 `channel:`（服务器频道）作为投递目标；裸数字 ID 会被拒绝。 -- 服务器 slug 使用小写并将空格替换为 `-`；频道键使用 slug 化名称（不含 `#`）。优先使用服务器 ID。 -- 默认忽略机器人发送的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 仅接受提及机器人的机器人消息（仍会过滤机器人自己的消息）。 -- `channels.discord.guilds..ignoreOtherMentions`（以及频道级覆盖）会丢弃提及其他用户或角色但未提及机器人的消息（不含 @everyone/@here）。 -- `maxLinesPerMessage`（默认 17）会拆分行数过多的消息，即使总字符数未超过 2000。 -- `channels.discord.threadBindings` 控制 Discord 线程绑定路由： +- 服务器 slug 会转为小写并将空格替换为 `-`；频道键使用 slug 化名称（不带 `#`）。优先使用服务器 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) 共享。 + - `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) 共享。 - `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` 将运行时可用性映射为机器人在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。 -- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变的名称/标签匹配（紧急兼容模式）。 +- OpenClaw 还会在重复解密失败后通过离开/重新加入语音会话来尝试恢复语音接收。 +- `channels.discord.streaming` 是规范的流模式键。旧版 `streamMode` 和布尔型 `streaming` 值会自动迁移。 +- `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 审批会激活。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当能从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，会激活 exec 审批。 - `approvers`：允许批准 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。 - - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批请求。 + - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。 - `sessionFilter`：可选的会话键模式（子串或正则）。 - - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批人私信，`"channel"` 发送到原始频道，`"both"` 两处都发。若目标包含 `"channel"`，按钮仅解析出的审批人可用。 + - `target`：审批提示发送位置。`"dm"`（默认）发送到审批人的私信，`"channel"` 发送到原始频道，`"both"` 两处都发送。当目标包含 `"channel"` 时，按钮仅对已解析出的审批人可用。 - `cleanupAfterResolve`：为 `true` 时，在批准、拒绝或超时后删除审批私信。 -**反应通知模式：** `off`（无）、`own`（机器人自己的消息，默认）、`all`（所有消息）、`allowlist`（`guilds..users` 中用户发出的所有消息）。 +**反应通知模式：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（来自 `guilds..users`，作用于所有消息）。 ### Google Chat @@ -379,11 +379,11 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在 } ``` -- 服务账号 JSON：可内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 +- 服务账号 JSON：支持内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 - 也支持服务账号 SecretRef（`serviceAccountRef`）。 - 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 - 使用 `spaces/` 或 `users/` 作为投递目标。 -- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变邮箱主体匹配（紧急兼容模式）。 +- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变邮箱主体匹配（破窗兼容模式）。 ### Slack @@ -405,7 +405,7 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在 allowBots: false, users: ["U123"], skills: ["docs"], - systemPrompt: "Short answers only.", + systemPrompt: "只给出简短回答。", }, }, historyLimit: 50, @@ -448,33 +448,29 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在 } ``` -- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 -- **HTTP mode** 需要 `botToken` 和 `signingSecret`（可在根级或每账号级配置）。 -- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串 - 或 SecretRef 对象。 -- Slack 账号快照会暴露每项凭证的来源/状态字段，例如 - `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式下的 - `signingSecretStatus`。`configured_unavailable` 表示该账号通过 SecretRef - 配置，但当前命令/运行时路径无法解析该密钥值。 +- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号的环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 +- **HTTP mode** 需要 `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` 是规范的流式模式键。旧版 `streamMode` 和布尔型 `streaming` 值会被自动迁移。 +- 可选的 `channels.slack.defaultAccount` 会在其匹配已配置账号 ID 时覆盖默认账号选择。 +- `channels.slack.streaming` 是规范的流模式键。旧版 `streamMode` 和布尔型 `streaming` 值会自动迁移。 - 使用 `user:`（私信）或 `channel:` 作为投递目标。 **反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -**线程会话隔离：** `thread.historyScope` 为每线程（默认）或跨频道共享。`thread.inheritParent` 会将父频道转录复制到新线程。 +**线程会话隔离：** `thread.historyScope` 可设为按线程（默认）或跨频道共享。`thread.inheritParent` 会将父频道转录复制到新线程中。 -- `typingReaction` 会在回复进行期间给传入的 Slack 消息添加一个临时反应，并在完成后移除。使用 Slack emoji 简码，例如 `"hourglass_flowing_sand"`。 -- `channels.slack.execApprovals`：Slack 原生 exec 审批投递与审批人授权。与 Discord 使用相同 schema：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 +- `typingReaction` 会在回复运行期间为入站 Slack 消息添加一个临时反应，并在完成后移除。使用 Slack emoji 简码，例如 `"hourglass_flowing_sand"`。 +- `channels.slack.execApprovals`：Slack 原生 exec 审批投递与审批人授权。其 schema 与 Discord 相同：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 -| 动作组 | 默认值 | 说明 | -| ------------ | -------- | -------------------- | -| reactions | 已启用 | 添加反应 + 列出反应 | -| messages | 已启用 | 读取/发送/编辑/删除 | -| pins | 已启用 | 置顶/取消置顶/列出 | -| memberInfo | 已启用 | 成员信息 | -| emojiList | 已启用 | 自定义 emoji 列表 | +| 操作组 | 默认值 | 说明 | +| ------------ | ------- | --------------------- | +| reactions | 启用 | 添加反应并列出反应 | +| messages | 启用 | 读取/发送/编辑/删除 | +| pins | 启用 | 固定/取消固定/列出 | +| memberInfo | 启用 | 成员信息 | +| emojiList | 启用 | 自定义 emoji 列表 | ### Mattermost @@ -495,10 +491,10 @@ Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost` "team-channel-id": { requireMention: false }, }, commands: { - native: true, // 显式启用 + native: true, // 选择性启用 nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // 反向代理/公网部署时可选的显式 URL + // 反向代理/公共部署时可选的显式 URL callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -508,21 +504,19 @@ Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost` } ``` -聊天模式：`oncall`（在 @ 提及时响应，默认）、`onmessage`（每条消息都响应）、`onchar`（以触发前缀开头的消息）。 +聊天模式：`oncall`（在 @ 提及时响应，默认）、`onmessage`（每条消息都响应）、`onchar`（响应以触发前缀开头的消息）。 -启用 Mattermost 原生命令时： +当启用 Mattermost 原生命令时： -- `commands.callbackPath` 必须是一个路径（例如 `/api/channels/mattermost/command`），不能是完整 URL。 -- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器必须能访问到。 -- 原生斜杠命令回调使用 Mattermost 在斜杠命令注册期间返回的每命令 token 进行认证。如果注册失败或没有激活任何命令，OpenClaw 会拒绝回调，并返回 - `Unauthorized: invalid command token.`。 -- 对于私有/tailnet/内部回调主机，Mattermost 可能要求 - `ServiceSettings.AllowedUntrustedInternalConnections` 包含该回调主机/域名。 - 请使用主机/域名值，而不是完整 URL。 +- `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。 - `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 @@ -545,13 +539,13 @@ Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost` **反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -- `channels.signal.account`：将渠道启动固定到特定的 Signal 账号身份。 +- `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 { @@ -559,7 +553,7 @@ BlueBubbles 是推荐的 iMessage 路径（由插件支持，配置位于 `chann bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl、password、webhookPath、群组控制和高级动作： + // serverUrl、password、webhookPath、群组控制和高级操作： // 参见 /channels/bluebubbles }, }, @@ -567,13 +561,13 @@ BlueBubbles 是推荐的 iMessage 路径（由插件支持，配置位于 `chann ``` - 此处涵盖的核心键路径：`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)。 -- 完整的 BlueBubbles 渠道配置见 [BlueBubbles](/zh-CN/channels/bluebubbles)。 +- 可选的 `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）。不需要守护进程或端口。 +OpenClaw 会启动 `imsg rpc`（通过 stdio 的 JSON-RPC）。无需守护进程或端口。 ```json5 { @@ -597,15 +591,15 @@ OpenClaw 会生成 `imsg rpc`（基于 stdio 的 JSON-RPC）。不需要守护 } ``` -- 可选的 `channels.imessage.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 +- 可选的 `channels.imessage.defaultAccount` 会在其匹配已配置账号 ID 时覆盖默认账号选择。 -- 需要对 Messages 数据库具有“完全磁盘访问权限”。 -- 优先使用 `chat_id:` 目标。使用 `imsg chats --limit 20` 列出聊天。 -- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。 -- `attachmentRoots` 和 `remoteAttachmentRoots` 会限制传入附件路径（默认：`/Users/*/Library/Messages/Attachments`）。 -- SCP 使用严格主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 +- 需要对 Messages 数据库授予“完全磁盘访问”权限。 +- 优先使用 `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)。 @@ -618,7 +612,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix 由扩展支持，配置位于 `channels.matrix`。 +Matrix 由扩展提供支持，配置在 `channels.matrix` 下。 ```json5 { @@ -649,22 +643,23 @@ Matrix 由扩展支持，配置位于 `channels.matrix`。 ``` - Token 认证使用 `accessToken`；密码认证使用 `userId` + `password`。 -- `channels.matrix.proxy` 会将 Matrix HTTP 流量路由到显式 HTTP(S) 代理。命名账号可通过 `channels.matrix.accounts..proxy` 覆盖。 +- `channels.matrix.proxy` 通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账号可通过 `channels.matrix.accounts..proxy` 覆盖它。 - `channels.matrix.allowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 和 `allowPrivateNetwork` 是相互独立的控制项。 - `channels.matrix.defaultAccount` 在多账号设置中选择首选账号。 - `channels.matrix.execApprovals`：Matrix 原生 exec 审批投递与审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，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`。 -- Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。 -- 完整的 Matrix 配置、目标规则和设置示例见 [Matrix](/zh-CN/channels/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 { @@ -680,11 +675,11 @@ Microsoft Teams 由扩展支持，配置位于 `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 { @@ -706,8 +701,8 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ``` - 此处涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 -- 可选的 `channels.irc.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 完整的 IRC 渠道配置（主机/端口/TLS/频道/允许列表/提及门控）见 [IRC](/zh-CN/channels/irc)。 +- 可选的 `channels.irc.defaultAccount` 会在其匹配已配置账号 ID 时覆盖默认账号选择。 +- 完整的 IRC 渠道配置（主机/端口/TLS/频道/允许列表/提及门控）请参见 [IRC](/zh-CN/channels/irc)。 ### 多账号（所有渠道） @@ -719,11 +714,11 @@ IRC 由扩展支持，配置位于 `channels.irc`。 telegram: { accounts: { default: { - name: "Primary bot", + name: "主 Bot", botToken: "123456:ABC...", }, alerts: { - name: "Alerts bot", + name: "告警 Bot", botToken: "987654:XYZ...", }, }, @@ -732,28 +727,28 @@ IRC 由扩展支持，配置位于 `channels.irc`。 } ``` -- 当省略 `accountId` 时，使用 `default`（CLI + 路由）。 -- 环境变量 token 仅适用于**默认**账号。 -- 基础渠道设置适用于所有账号，除非在账号级被覆盖。 +- 当省略 `accountId` 时会使用 `default`（CLI + 路由）。 +- 环境变量 token 只适用于 **default** 账号。 +- 基础渠道设置会应用到所有账号，除非被按账号覆盖。 - 使用 `bindings[].match.accountId` 将每个账号路由到不同智能体。 -- 如果你通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，而当前仍使用单账号顶层渠道配置，OpenClaw 会先将账号范围的顶层单账号值提升到该渠道的账号映射中，这样原账号仍可继续工作。大多数渠道会将它们移入 `channels..accounts.default`；Matrix 则可保留现有匹配的命名/默认目标。 -- 现有仅渠道级绑定（无 `accountId`）将继续匹配默认账号；账号范围绑定仍是可选的。 -- `openclaw doctor --fix` 也会通过将账号范围的顶层单账号值移入该渠道所选择的提升账号，来修复混合结构。大多数渠道使用 `accounts.default`；Matrix 可保留现有匹配的命名/默认目标。 +- 如果你通过 `openclaw channels add`（或渠道新手引导）添加了非默认账号，而此时仍是单账号顶层渠道配置，OpenClaw 会先将按账号范围的顶层单账号值提升到渠道账号映射中，以确保原账号继续工作。大多数渠道会移动到 `channels..accounts.default`；Matrix 则可以保留现有的匹配命名/默认目标。 +- 现有的纯渠道绑定（无 `accountId`）将继续匹配默认账号；按账号范围的绑定仍然是可选的。 +- `openclaw doctor --fix` 也会修复混合形态：它会将按账号范围的顶层单账号值移动到该渠道选定的提升后账号中。大多数渠道使用 `accounts.default`；Matrix 可以保留现有的匹配命名/默认目标。 ### 其他扩展渠道 -许多扩展渠道以 `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）。 +参见完整渠道索引：[Channels](/zh-CN/channels)。 ### 群聊提及门控 -群组消息默认**需要提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 +群组消息默认 **要求提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 **提及类型：** - **元数据提及**：平台原生 @ 提及。在 WhatsApp 自聊模式下会被忽略。 - **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 -- 仅当可检测到提及（原生提及或至少一个模式）时，才会强制执行提及门控。 +- 仅在可检测时（原生提及或至少存在一个模式）才会强制执行提及门控。 ```json5 { @@ -766,7 +761,7 @@ IRC 由扩展支持，配置位于 `channels.irc`。 } ``` -`messages.groupChat.historyLimit` 设置全局默认值。渠道可通过 `channels..historyLimit`（或每账号级）覆盖。设置为 `0` 可禁用。 +`messages.groupChat.historyLimit` 设置全局默认值。渠道可通过 `channels..historyLimit`（或按账号）覆盖。设为 `0` 可禁用。 #### 私信历史限制 @@ -783,13 +778,13 @@ IRC 由扩展支持，配置位于 `channels.irc`。 } ``` -解析顺序：每私信覆盖 → 提供商默认值 → 不限制（全部保留）。 +解析顺序：按私信覆盖 → 提供商默认值 → 无限制（全部保留）。 支持：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 #### 自聊模式 -将你自己的号码加入 `allowFrom` 以启用自聊模式（忽略原生 @ 提及，仅响应文本模式）： +将你自己的号码包含在 `allowFrom` 中即可启用自聊模式（忽略原生 @ 提及，只响应文本模式）： ```json5 { @@ -810,18 +805,18 @@ IRC 由扩展支持，配置位于 `channels.irc`。 } ``` -### 命令（聊天命令处理） +### Commands（聊天命令处理） ```json5 { commands: { native: "auto", // 在支持的平台上注册原生命令 - text: true, // 在聊天消息中解析 /commands + text: true, // 解析聊天消息中的 /commands bash: false, // 允许 !（别名：/bash） bashForegroundMs: 2000, config: false, // 允许 /config debug: false, // 允许 /debug - restart: false, // 允许 /restart + gateway restart 工具 + restart: false, // 允许 /restart + Gateway 网关重启工具 allowFrom: { "*": ["user1"], discord: ["user:123"], @@ -833,16 +828,16 @@ IRC 由扩展支持，配置位于 `channels.irc`。 -- 文本命令必须是带有前导 `/` 的**独立**消息。 -- `native: "auto"` 会开启 Discord/Telegram 的原生命令，而保持 Slack 关闭。 -- 每渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除先前已注册命令。 +- 文本命令必须是带前导 `/` 的**独立**消息。 +- `native: "auto"` 会为 Discord/Telegram 打开原生命令，Slack 则保持关闭。 +- 可按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除之前已注册的命令。 - `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 客户端仍然可用。 -- `channels..configWrites` 按渠道控制配置变更（默认：true）。 -- 对于多账号渠道，`channels..accounts..configWrites` 也控制面向该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 -- `allowFrom` 是按提供商划分的。设置后，它会成为**唯一**授权来源（渠道允许列表/配对和 `useAccessGroups` 都会被忽略）。 -- `useAccessGroups: false` 会在未设置 `allowFrom` 时允许命令绕过访问组策略。 +- `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 客户端可用。 +- `channels..configWrites` 控制每个渠道的配置变更（默认：true）。 +- 对于多账号渠道，`channels..accounts..configWrites` 也会控制针对该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 +- `allowFrom` 是按提供商划分的。设置后，它将成为**唯一**授权来源（渠道允许列表/配对及 `useAccessGroups` 都会被忽略）。 +- `useAccessGroups: false` 允许命令在 `allowFrom` 未设置时绕过访问组策略。 @@ -862,7 +857,7 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.repoRoot` -可选的仓库根目录，会显示在系统提示的 Runtime 行中。若未设置，OpenClaw 会从 workspace 向上遍历自动检测。 +可选的仓库根目录，会显示在系统提示的 Runtime 行中。未设置时，OpenClaw 会从工作区向上遍历自动检测。 ```json5 { @@ -887,15 +882,14 @@ IRC 由扩展支持，配置位于 `channels.irc`。 } ``` -- 省略 `agents.defaults.skills` 表示默认不限制 Skills。 -- 省略 `agents.list[].skills` 会继承默认值。 -- 设置 `agents.list[].skills: []` 表示没有 Skills。 -- 非空的 `agents.list[].skills` 列表是该智能体的最终集合； - 不会与默认值合并。 +- 省略 `agents.defaults.skills`，默认表示 Skills 不受限制。 +- 省略 `agents.list[].skills` 表示继承默认值。 +- 设置 `agents.list[].skills: []` 表示不启用任何 Skills。 +- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它不会与默认值合并。 ### `agents.defaults.skipBootstrap` -禁用自动创建 workspace 引导文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 +禁用自动创建工作区引导文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 ```json5 { @@ -905,7 +899,7 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.bootstrapMaxChars` -每个 workspace 引导文件在截断前的最大字符数。默认值：`20000`。 +单个工作区引导文件在截断前允许的最大字符数。默认值：`20000`。 ```json5 { @@ -915,7 +909,7 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.bootstrapTotalMaxChars` -所有 workspace 引导文件注入内容的总最大字符数。默认值：`150000`。 +所有工作区引导文件注入总字符数上限。默认值：`150000`。 ```json5 { @@ -925,11 +919,11 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.bootstrapPromptTruncationWarning` -控制当引导上下文被截断时，对智能体可见的警告文本。 +控制在引导上下文被截断时，向智能体显示的警告文本。 默认值：`"once"`。 -- `"off"`：绝不将警告文本注入系统提示。 -- `"once"`：每个唯一的截断签名仅注入一次警告（推荐）。 +- `"off"`：绝不在系统提示中注入警告文本。 +- `"once"`：每种唯一截断签名仅注入一次警告（推荐）。 - `"always"`：只要存在截断，每次运行都注入警告。 ```json5 @@ -940,11 +934,11 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.imageMaxDimensionPx` -在调用提供商之前，转录/工具图像块中最长边允许的最大像素尺寸。 +在调用提供商前，转录/工具图像块中图像最长边的最大像素尺寸。 默认值：`1200`。 -较低值通常会减少视觉 token 用量和截图密集型运行的请求负载大小。 -较高值可保留更多视觉细节。 +更低的值通常能减少视觉 token 用量和请求载荷大小，适合截图较多的运行。 +更高的值能保留更多视觉细节。 ```json5 { @@ -964,7 +958,7 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.timeFormat` -系统提示中的时间格式。默认值：`auto`（操作系统偏好）。 +系统提示中的时间格式。默认值：`auto`（跟随操作系统偏好）。 ```json5 { @@ -1002,7 +996,7 @@ IRC 由扩展支持，配置位于 `channels.irc`。 primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // 全局默认提供商参数 + params: { cacheRetention: "long" }, // 全局默认 provider 参数 pdfMaxBytesMb: 10, pdfMaxPages: 20, thinkingDefault: "low", @@ -1017,36 +1011,36 @@ IRC 由扩展支持，配置位于 `channels.irc`。 } ``` -- `model`：既可接受字符串（`"provider/model"`），也可接受对象（`{ primary, fallbacks }`）。 - - 字符串形式仅设置主模型。 - - 对象形式可设置主模型以及有序故障切换模型。 -- `imageModel`：既可接受字符串（`"provider/model"`），也可接受对象（`{ primary, fallbacks }`）。 - - 被 `image` 工具路径用作其视觉模型配置。 - - 当选定/默认模型无法接受图像输入时，也用作回退路由。 -- `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）。 - - 如果你直接选择某个提供商/模型，也要配置匹配的提供商认证/API key（例如 `google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 使用 `OPENAI_API_KEY`，`fal/*` 使用 `FAL_KEY`）。 - - 若省略，`image_generate` 仍可推断基于认证的提供商默认值。它会先尝试当前默认提供商，再按提供商 ID 顺序尝试剩余已注册的图像生成提供商。 -- `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` 仍可推断基于认证的提供商默认值。它会先尝试当前默认提供商，再按提供商 ID 顺序尝试剩余已注册的视频生成提供商。 - - 如果你直接选择某个提供商/模型，也要配置匹配的提供商认证/API key。 - - 内置的 Qwen 视频生成提供商目前最多支持 1 个输出视频、1 张输入图片、4 个输入视频、10 秒时长，以及提供商级 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 -- `pdfModel`：既可接受字符串（`"provider/model"`），也可接受对象（`{ primary, fallbacks }`）。 - - 被 `pdf` 工具用于模型路由。 - - 若省略，PDF 工具会回退到 `imageModel`，再回退到已解析的会话/默认模型。 -- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具的默认 PDF 大小限制。 +- `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 字符串形式只设置主模型。 + - 对象形式设置主模型以及有序故障转移模型。 +- `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 由 `image` 工具路径作为其视觉模型配置使用。 + - 当所选/默认模型不能接受图像输入时，也会用作回退路由。 +- `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）。 + - 如果你直接选择某个 provider/model，也要配置相应的提供商认证/API key（例如 `google/*` 需要 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 需要 `OPENAI_API_KEY`，`fal/*` 需要 `FAL_KEY`）。 + - 如果省略，`image_generate` 仍可推断基于认证的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。 +- `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` 仍可推断基于认证的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。 + - 如果你直接选择某个 provider/model，也要配置相应的提供商认证/API key。 + - 内置的 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 输出级别。取值：`"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)。 -- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及回退模型添加/移除命令）会保存为规范对象形式，并在可能时保留现有回退列表。 -- `maxConcurrent`：跨会话并行运行的最大智能体数量（每个会话内部仍然串行）。默认值：4。 +- `verboseDefault`：智能体的默认 verbose 级别。取值：`"off"`、`"on"`、`"full"`。默认：`"off"`。 +- `elevatedDefault`：智能体的默认 elevated-output 级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认：`"on"`。 +- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果省略 provider，OpenClaw 会先尝试别名，然后尝试与该确切模型 ID 唯一匹配的已配置 provider，最后才回退到已配置的默认 provider（已弃用的兼容行为，因此建议使用显式 `provider/model`）。如果该 provider 不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置 provider/model，而不是暴露一个过时的已删除 provider 默认值。 +- `models`：已配置的模型目录以及 `/model` 的允许列表。每个条目都可以包含 `alias`（快捷方式）和 `params`（provider 特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 +- `params`：应用于所有模型的全局默认 provider 参数。设置在 `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)。 +- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 和回退添加/删除命令）会保存为规范对象形式，并尽可能保留现有回退列表。 +- `maxConcurrent`：跨会话的智能体最大并行运行数（每个会话仍会串行化）。默认值：4。 **内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）： @@ -1064,10 +1058,10 @@ IRC 由扩展支持，配置位于 `channels.irc`。 你自己配置的别名始终优先于默认值。 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。 -- 当设置了 `sessionArg` 时支持会话。 +- 设置了 `sessionArg` 时支持会话。 - 当 `imageArg` 接受文件路径时支持图像透传。 ### `agents.defaults.heartbeat` @@ -1082,8 +1076,8 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 every: "30m", // 0m 表示禁用 model: "openai/gpt-5.4-mini", includeReasoning: false, - lightContext: false, // 默认：false；true 时仅保留 workspace 引导文件中的 HEARTBEAT.md - isolatedSession: false, // 默认：false；true 时每次心跳都在全新会话中运行（无对话历史） + lightContext: false, // 默认：false；true 时仅保留工作区引导文件中的 HEARTBEAT.md + isolatedSession: false, // 默认：false；true 时每次心跳都在全新会话中运行（无历史对话） session: "main", to: "+15555550123", directPolicy: "allow", // allow（默认）| block @@ -1097,13 +1091,13 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。 -- `suppressToolErrorWarnings`：为 true 时，在心跳运行期间抑制工具错误警告负载。 -- `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 会阻止直接目标投递，并发出 `reason=dm-blocked`。 -- `lightContext`：为 true 时，心跳运行使用轻量引导上下文，并且仅保留 workspace 引导文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：为 true 时，每次心跳都在没有先前对话历史的全新会话中运行。与 cron 的 `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次心跳的 token 成本从约 100K 降低到约 2-5K token。 -- 每智能体：设置 `agents.list[].heartbeat`。当任一智能体定义了 `heartbeat` 时，**只有这些智能体**会运行心跳。 -- 心跳会运行完整的智能体回合——更短的间隔会消耗更多 token。 +- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API-key 认证）或 `1h`（OAuth 认证）。设置为 `0m` 可禁用。 +- `suppressToolErrorWarnings`：为 true 时，在心跳运行中抑制工具错误警告载荷。 +- `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 会抑制直接目标投递并发出 `reason=dm-blocked`。 +- `lightContext`：为 true 时，心跳运行使用轻量级引导上下文，并只保留工作区引导文件中的 `HEARTBEAT.md`。 +- `isolatedSession`：为 true 时，每次心跳都在没有历史对话的全新会话中运行。与 cron 的 `sessionTarget: "isolated"` 使用相同隔离模式。可将每次心跳的 token 成本从约 100K 降低到约 2-5K。 +- 每智能体：设置 `agents.list[].heartbeat`。当任意智能体定义了 `heartbeat` 时，**只有这些智能体**会运行心跳。 +- 心跳会运行完整的智能体轮次——间隔越短，消耗的 token 越多。 ### `agents.defaults.compaction` @@ -1116,7 +1110,7 @@ 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 时使用 + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // 在 identifierPolicy=custom 时使用 postCompactionSections: ["Session Startup", "Red Lines"], // [] 表示禁用重新注入 model: "openrouter/anthropic/claude-sonnet-4-6", // 可选，仅用于 compaction 的模型覆盖 notifyUser: true, // compaction 开始时发送简短通知给用户（默认：false） @@ -1132,18 +1126,18 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `mode`：`default` 或 `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`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。当主会话应保持一个模型、而 compaction 摘要应使用另一个模型时使用；未设置时，compaction 使用会话的主模型。 -- `notifyUser`：为 `true` 时，在 compaction 开始时向用户发送简短通知（例如“正在压缩上下文...”）。默认禁用以保持 compaction 静默。 -- `memoryFlush`：自动 compaction 前执行静默智能体回合以存储持久记忆。workspace 为只读时会跳过。 +- `mode`：`default` 或 `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`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。当主会话应保持一个模型，而 compaction 摘要应使用另一个模型时使用；未设置时，compaction 使用会话主模型。 +- `notifyUser`：为 `true` 时，在 compaction 开始时向用户发送简短通知（例如 “Compacting context...”）。默认禁用，以保持 compaction 静默。 +- `memoryFlush`：在自动 compaction 前进行的静默智能体轮次，用于存储持久记忆。工作区为只读时会跳过。 ### `agents.defaults.contextPruning` -在发送到 LLM 之前，从内存上下文中裁剪**旧的工具结果**。**不会**修改磁盘上的会话历史。 +在发送给 LLM 前，从内存上下文中裁剪**旧的工具结果**。**不会**修改磁盘上的会话历史。 ```json5 { @@ -1167,23 +1161,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)。 +行为细节参见 [Session Pruning](/zh-CN/concepts/session-pruning)。 ### 分块流式传输 @@ -1201,11 +1195,11 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- 非 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–2500ms。每智能体覆盖：`agents.list[].humanDelay`。 -行为和分块详情见 [Streaming](/zh-CN/concepts/streaming)。 +行为和分块细节参见 [Streaming](/zh-CN/concepts/streaming)。 ### 输入状态指示器 @@ -1220,7 +1214,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- 默认值：私聊/被提及时为 `instant`，未提及的群聊为 `message`。 +- 默认值：私聊/被提及时使用 `instant`，未被提及的群聊使用 `message`。 - 每会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 参见 [Typing Indicators](/zh-CN/concepts/typing-indicators)。 @@ -1229,7 +1223,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ### `agents.defaults.sandbox` -嵌入式智能体的可选沙箱隔离。完整指南见 [Sandboxing](/zh-CN/gateway/sandboxing)。 +嵌入式智能体的可选沙箱隔离。完整指南参见 [Sandboxing](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -1332,15 +1326,15 @@ 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 的绝对远程根目录 -- `identityFile` / `certificateFile` / `knownHostsFile`：传给 OpenSSH 的现有本地文件 +- `workspaceRoot`：用于按 scope 划分工作区的远程绝对根目录 +- `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件 - `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其实体化为临时文件 - `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关 @@ -1349,27 +1343,27 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 - `identityData` 优先于 `identityFile` - `certificateData` 优先于 `certificateFile` - `knownHostsData` 优先于 `knownHostsFile` -- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前，从当前活跃的 secrets 运行时快照中解析 +- 由 SecretRef 支持的 `*Data` 值会在沙箱会话开始前从活动 secrets 运行时快照中解析 **SSH 后端行为：** -- 在创建或重建后仅为远程 workspace 执行一次初始化 -- 然后持续将远程 SSH workspace 作为规范 workspace +- 创建或重建后，会为远程工作区执行一次初始播种 +- 然后保持远程 SSH 工作区为规范副本 - 通过 SSH 路由 `exec`、文件工具和媒体路径 -- 不会自动将远程更改同步回主机 +- 不会自动将远程变更同步回主机 - 不支持沙箱浏览器容器 -**workspace 访问：** +**工作区访问：** -- `none`：在 `~/.openclaw/sandboxes` 下按作用域创建沙箱 workspace -- `ro`：沙箱 workspace 位于 `/workspace`，智能体 workspace 只读挂载到 `/agent` -- `rw`：智能体 workspace 以读写方式挂载到 `/workspace` +- `none`：位于 `~/.openclaw/sandboxes` 下、按 scope 划分的沙箱工作区 +- `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent` +- `rw`：智能体工作区以读写方式挂载到 `/workspace` **作用域：** -- `session`：每会话一个容器 + workspace -- `agent`：每智能体一个容器 + workspace（默认） -- `shared`：共享容器和 workspace（无跨会话隔离） +- `session`：每会话一个容器 + 工作区 +- `agent`：每智能体一个容器 + 工作区（默认） +- `shared`：共享容器和工作区（无跨会话隔离） **OpenShell 插件配置：** @@ -1399,30 +1393,30 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **OpenShell 模式：** -- `mirror`：执行前从本地同步到远程，执行后再同步回本地；本地 workspace 保持为规范副本 -- `remote`：在创建沙箱时仅进行一次远程初始化，之后远程 workspace 保持为规范副本 +- `mirror`：执行前从本地播种到远端，执行后同步回本地；本地工作区保持为规范副本 +- `remote`：创建沙箱时只向远端播种一次，然后保持远程工作区为规范副本 -在 `remote` 模式下，于 OpenClaw 外部在主机本地做出的修改，在初始化之后不会自动同步到沙箱中。 -传输通过 SSH 进入 OpenShell 沙箱，但插件负责沙箱生命周期以及可选的镜像同步。 +在 `remote` 模式下，在播种步骤之后，于 OpenClaw 外部对主机本地所做的编辑不会自动同步进沙箱。 +传输使用 SSH 连接到 OpenShell 沙箱，但插件负责沙箱生命周期以及可选的 mirror 同步。 -**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统以及 root 用户。 +**`setupCommand`** 在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。 -**容器默认使用 `network: "none"`**——如果智能体需要出站访问，请设为 `"bridge"`（或自定义桥接网络）。 +**容器默认使用 `network: "none"`**——如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 默认会阻止 `"host"`。默认也会阻止 `"container:"`，除非你显式设置 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急放行）。 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（破窗模式）。 -**传入附件** 会被暂存到当前活跃 workspace 中的 `media/inbound/*`。 +**入站附件** 会暂存到活动工作区中的 `media/inbound/*`。 -**`docker.binds`** 会挂载额外的主机目录；全局和每智能体 binds 会合并。 +**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的 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`。 -- `cdpSourceRange` 可选地在容器边界按 CIDR 范围限制 CDP 入站（例如 `172.21.0.1/32`）。 -- `sandbox.browser.binds` 仅将额外挂载应用到沙箱浏览器容器。当设置该项时（包括 `[]`），它会替换浏览器容器的 `docker.binds`。 -- 启动默认值在 `scripts/sandbox-browser-entrypoint.sh` 中定义，并针对容器主机做了调优： +- `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` 中，并针对容器主机进行了调优： - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1440,15 +1434,15 @@ noVNC 旁观访问默认使用 VNC 认证，OpenClaw 会发出一个短期 token - `--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` 重新启用扩展。 + - `--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。 + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设置为 `0` 以使用 Chromium 的 + 默认进程限制。 + - 在启用 `noSandbox` 时，还会加上 `--no-sandbox` 和 `--disable-setuid-sandbox`。 + - 默认值即容器镜像基线；如需修改容器默认值，请使用带自定义入口点的自定义浏览器镜像。 @@ -1461,7 +1455,7 @@ scripts/sandbox-setup.sh # 主沙箱镜像 scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ``` -### `agents.list`（每智能体覆盖） +### `agents.list`（按智能体覆盖） ```json5 { @@ -1470,13 +1464,13 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 { id: "main", default: true, - name: "Main Agent", + name: "主智能体", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // 或 { primary, fallbacks } - thinkingDefault: "high", // 每智能体 thinking 级别覆盖 - reasoningDefault: "on", // 每智能体推理可见性覆盖 - fastModeDefault: false, // 每智能体快速模式覆盖 + thinkingDefault: "high", // 按智能体覆盖 thinking 级别 + reasoningDefault: "on", // 按智能体覆盖 reasoning 可见性 + fastModeDefault: false, // 按智能体覆盖 fast mode params: { cacheRetention: "none" }, // 按键覆盖匹配 defaults.models 的参数 skills: ["docs-search"], // 设置时会替换 agents.defaults.skills identity: { @@ -1509,26 +1503,26 @@ 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`：可选的每智能体默认推理可见性（`on | off | stream`）。当未设置每消息或会话级推理覆盖时生效。 -- `fastModeDefault`：可选的每智能体快速模式默认值（`true | false`）。当未设置每消息或会话级快速模式覆盖时生效。 -- `runtime`：可选的每智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 以及 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 -- `identity.avatar`：相对于 workspace 的路径、`http(s)` URL 或 `data:` URI。 +- `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 覆盖时生效。 +- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 配合 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 +- `identity.avatar`：相对于工作区的路径、`http(s)` URL 或 `data:` URI。 - `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name`/`emoji`。 -- `subagents.allowAgents`：`sessions_spawn` 的智能体 ID 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 -- 沙箱继承保护：如果请求者会话处于沙箱隔离中，`sessions_spawn` 会拒绝会导致目标未沙箱隔离的请求。 -- `subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认：false）。 +- `subagents.allowAgents`：用于 `sessions_spawn` 的智能体 ID 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- 沙箱继承保护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝那些将以非沙箱方式运行的目标。 +- `subagents.requireAgentId`：为 true 时，阻止未提供 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置文件；默认：false）。 --- ## 多智能体路由 -在一个 Gateway 网关中运行多个隔离智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。 +在一个 Gateway 网关中运行多个相互隔离的智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。 ```json5 { @@ -1547,27 +1541,27 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ### 绑定匹配字段 -- `type`（可选）：普通路由使用 `route`（缺失时默认 route），持久 ACP 对话绑定使用 `acp` -- `match.channel`（必填） +- `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 }` **确定性匹配顺序：** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId`（精确，无 peer/guild/team） +4. `match.accountId`（精确匹配，无 peer/guild/team） 5. `match.accountId: "*"`（全渠道） 6. 默认智能体 -在每一层内，第一个匹配的 `bindings` 条目获胜。 +在每一层内，第一条匹配的 `bindings` 会生效。 -对于 `type: "acp"` 条目，OpenClaw 会按精确对话身份（`match.channel` + 账号 + `match.peer.id`）解析，不使用上述 route 绑定分层顺序。 +对于 `type: "acp"` 条目，OpenClaw 会按精确会话身份（`match.channel` + account + `match.peer.id`）解析，不使用上述 route 绑定分层顺序。 -### 每智能体访问配置 +### 按智能体的访问配置 @@ -1587,7 +1581,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 - + ```json5 { @@ -1662,7 +1656,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 -优先级详情见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 +优先级细节参见 [Multi-Agent 沙箱隔离与工具](/zh-CN/tools/multi-agent-sandbox-tools)。 --- @@ -1688,7 +1682,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // 超过该 token 数则跳过父线程 fork（0 表示禁用） + parentForkMaxTokens: 100000, // 高于此 token 数时跳过父线程 fork（0 表示禁用） maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", @@ -1700,8 +1694,8 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, threadBindings: { enabled: true, - idleHours: 24, // 默认按小时计算的无活动自动取消聚焦（`0` 表示禁用） - maxAgeHours: 0, // 默认按小时计算的硬性最大存活时间（`0` 表示禁用） + idleHours: 24, // 默认按小时计算的非活动自动取消聚焦（`0` 表示禁用） + maxAgeHours: 0, // 默认按小时计算的硬性最大存活期（`0` 表示禁用） }, mainKey: "main", // 旧字段（运行时始终使用 "main"） agentToAgent: { maxPingPongTurns: 5 }, @@ -1716,34 +1710,34 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 - **`scope`**：群聊上下文的基础会话分组策略。 - - `per-sender`（默认）：在某个渠道上下文中，每个发送者都有隔离的会话。 - - `global`：一个渠道上下文中的所有参与者共享同一个会话（仅在确实需要共享上下文时使用）。 + - `per-sender`（默认）：在某个渠道上下文中，每个发送者都有独立会话。 + - `global`：渠道上下文中的所有参与者共享一个会话（仅当确实需要共享上下文时使用）。 - **`dmScope`**：私信的分组方式。 - `main`：所有私信共享主会话。 - - `per-peer`：按跨渠道发送者 ID 隔离。 + - `per-peer`：按跨渠道的发送者 ID 隔离。 - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。 -- **`identityLinks`**：将规范 ID 映射到带提供商前缀的 peer，用于跨渠道共享会话。 -- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在空闲 `idleMinutes` 后重置。当两者都配置时，以先到期者为准。 -- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。 -- **`parentForkMaxTokens`**：创建 fork 线程会话时，允许父会话 `totalTokens` 的最大值（默认 `100000`）。 - - 如果父会话 `totalTokens` 高于该值，OpenClaw 会启动一个全新的线程会话，而不是继承父级转录历史。 - - 设为 `0` 可禁用该保护，并始终允许父级 fork。 +- **`identityLinks`**：将规范 ID 映射到带 provider 前缀的 peer，用于跨渠道共享会话。 +- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。当两者都配置时，以先到期者为准。 +- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 仍接受为 `direct` 的别名。 +- **`parentForkMaxTokens`**：创建分叉线程会话时，允许的父会话 `totalTokens` 最大值（默认 `100000`）。 + - 如果父会话 `totalTokens` 高于该值，OpenClaw 会启动一个全新的线程会话，而不是继承父转录历史。 + - 设置为 `0` 可禁用该保护，并始终允许父级 fork。 - **`mainKey`**：旧字段。运行时现在始终对主私聊桶使用 `"main"`。 -- **`agentToAgent.maxPingPongTurns`**：智能体之间在 agent-to-agent 交换中允许的最大来回回复轮数（整数，范围：`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`）。 +- **`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`）。 - `rotateBytes`：当 `sessions.json` 超过该大小时轮转（默认 `10mb`）。 - - `resetArchiveRetention`：`*.reset.` 转录归档的保留时间。默认等于 `pruneAfter`；设为 `false` 可禁用。 - - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先移除最旧的产物/会话。 - - `highWaterBytes`：预算清理后的可选目标值。默认为 `maxDiskBytes` 的 `80%`。 + - `resetArchiveRetention`：`*.reset.` 转录归档的保留时长。默认与 `pruneAfter` 相同；设为 `false` 可禁用。 + - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先移除最旧的制品/会话。 + - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - - `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：默认按小时计算的无活动自动取消聚焦（`0` 表示禁用；提供商可覆盖） - - `maxAgeHours`：默认按小时计算的硬性最大存活时间（`0` 表示禁用；提供商可覆盖） + - `enabled`：主默认开关（provider 可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） + - `idleHours`：默认按小时计算的非活动自动取消聚焦（`0` 表示禁用；provider 可覆盖） + - `maxAgeHours`：默认按小时计算的硬性最大存活期（`0` 表示禁用；provider 可覆盖） @@ -1779,17 +1773,17 @@ 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` | +| `{model}` | 简短模型名 | `claude-opus-4-6` | | `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | | `{provider}` | 提供商名称 | `anthropic` | | `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | @@ -1799,18 +1793,18 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ### 确认反应 -- 默认使用当前智能体的 `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 上，在回复后移除确认反应。 +- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上回复后移除确认反应。 - `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。 - 在 Slack 和 Discord 上，未设置时如果确认反应处于激活状态，则状态反应保持启用。 - 在 Telegram 上，需要显式设为 `true` 才会启用生命周期状态反应。 + 在 Slack 和 Discord 上，未设置时如果确认反应处于启用状态，则保持状态反应启用。 + 在 Telegram 上，需要显式设置为 `true` 才会启用生命周期状态反应。 -### 入站去抖 +### 入站防抖 -将来自同一发送者的快速文本消息批处理为一次智能体回合。媒体/附件会立即冲刷。控制命令会绕过去抖。 +将来自同一发送者的快速文本消息批量合并为一次智能体轮次。媒体/附件会立即刷新。控制命令会绕过防抖。 ### TTS（文本转语音） @@ -1854,11 +1848,11 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ``` - `auto` 控制自动 TTS。`/tts off|always|inbound|tagged` 会按会话覆盖。 -- `summaryModel` 会覆盖自动摘要所使用的 `agents.defaults.model.primary`。 -- `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 服务器，并放宽模型/语音校验。 +- `summaryModel` 会覆盖 `agents.defaults.model.primary` 用于自动摘要。 +- `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 服务器，并放宽模型/语音校验。 --- @@ -1888,51 +1882,51 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -- 当配置了多个 Talk 提供商时，`talk.provider` 必须与 `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`。 +- 当配置了多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的一个键。 +- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，会自动迁移到 `talk.providers.`。 +- 语音 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`）。 +- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多久才发送转录。未设置时保持平台默认暂停窗口（macOS 和 Android 为 `700 ms`，iOS 为 `900 ms`）。 --- ## 工具 -### 工具配置 +### 工具配置文件 `tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置基础允许列表： -本地新手引导在未设置时，会将新的本地配置默认设为 `tools.profile: "coding"`（现有显式配置会被保留）。 +本地新手引导会在未设置时将新的本地配置默认设为 `tools.profile: "coding"`（现有的显式配置文件会被保留）。 -| 配置 | 包含内容 | -| ------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| `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` | 不做限制（与未设置相同） | +| 配置文件 | 包含内容 | +| ----------- | ---------------------------------------------------------------------------------------------------------------------------- | +| `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` | 不限制（与未设置相同） | ### 工具组 -| 工具组 | 工具 | -| ------------------- | ----------------------------------------------------------------------------------------------------------------------- | -| `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: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` | 所有内置工具（不包括提供商插件） | ### `tools.allow` / `tools.deny` -全局工具允许/拒绝策略（拒绝优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱关闭也会生效。 +全局工具允许/拒绝策略（deny 优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱关闭也会应用。 ```json5 { @@ -1942,7 +1936,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.byProvider` -为特定提供商或模型进一步限制工具。顺序：基础配置 → 提供商配置 → allow/deny。 +进一步限制特定提供商或模型的工具。顺序：基础配置文件 → 提供商配置文件 → allow/deny。 ```json5 { @@ -1958,7 +1952,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.elevated` -控制沙箱外的 elevated exec 访问： +控制沙箱外的高权限 exec 访问： ```json5 { @@ -1974,9 +1968,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` 会按会话存储状态；内联指令仅应用于单条消息。 +- 高权限 `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认 `gateway`，当 exec 目标是 `node` 时则使用 `node`）。 ### `tools.exec` @@ -2001,7 +1995,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.loopDetection` 工具循环安全检查**默认禁用**。设置 `enabled: true` 可启用检测。 -设置可全局定义在 `tools.loopDetection` 中，也可在每智能体级通过 `agents.list[].tools.loopDetection` 覆盖。 +设置可以定义在全局 `tools.loopDetection` 中，也可以在每智能体 `agents.list[].tools.loopDetection` 中覆盖。 ```json5 { @@ -2022,14 +2016,14 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -- `historySize`：用于循环分析所保留的最大工具调用历史数。 -- `warningThreshold`：触发警告的重复无进展模式阈值。 -- `criticalThreshold`：阻止严重循环的更高重复阈值。 -- `globalCircuitBreakerThreshold`：任何无进展运行的硬停止阈值。 -- `detectors.genericRepeat`：对重复调用“同工具/同参数”发出警告。 -- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展模式发出警告/阻止。 +- `historySize`：为循环分析保留的最大工具调用历史。 +- `warningThreshold`：重复无进展模式的警告阈值。 +- `criticalThreshold`：阻止关键循环的更高重复阈值。 +- `globalCircuitBreakerThreshold`：任意无进展运行的硬停止阈值。 +- `detectors.genericRepeat`：对重复的同工具/同参数调用发出警告。 +- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告/阻止。 - `detectors.pingPong`：对交替出现的无进展成对模式发出警告/阻止。 -- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，验证会失败。 +- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，验证将失败。 ### `tools.web` @@ -2046,7 +2040,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 }, fetch: { enabled: true, - provider: "firecrawl", // 可选；省略表示自动检测 + provider: "firecrawl", // 可选；省略则自动检测 maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2096,9 +2090,9 @@ Talk 模式（macOS/iOS/Android）的默认值。 **提供商条目**（`type: "provider"` 或省略）： -- `provider`：API 提供商 ID（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） +- `provider`：API provider ID（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） - `model`：模型 ID 覆盖 -- `profile` / `preferredProfile`：`auth-profiles.json` 配置选择 +- `profile` / `preferredProfile`：`auth-profiles.json` 配置文件选择 **CLI 条目**（`type: "cli"`）： @@ -2107,9 +2101,9 @@ Talk 模式（macOS/iOS/Android）的默认值。 **公共字段：** -- `capabilities`：可选列表（`image`、`audio`、`video`）。默认值：`openai`/`anthropic`/`minimax` → image，`google` → image+audio+video，`groq` → audio。 -- `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：每条目覆盖。 -- 失败时会回退到下一个条目。 +- `capabilities`：可选列表（`image`、`audio`、`video`）。默认：`openai`/`anthropic`/`minimax` → image，`google` → image+audio+video，`groq` → audio。 +- `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：按条目的覆盖。 +- 失败时会回退到下一条目。 提供商认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 @@ -2130,9 +2124,9 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.sessions` -控制哪些会话可被会话工具（`sessions_list`、`sessions_history`、`sessions_send`）定位。 +控制会话工具（`sessions_list`、`sessions_history`、`sessions_send`）可定位哪些会话。 -默认值：`tree`（当前会话 + 由它生成的会话，例如子智能体）。 +默认值：`tree`（当前会话 + 由其派生的会话，例如 subagents）。 ```json5 { @@ -2145,13 +2139,13 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -说明： +注意： - `self`：仅当前会话键。 -- `tree`：当前会话 + 由当前会话生成的会话（子智能体）。 -- `agent`：属于当前智能体 ID 的任意会话（如果你在同一智能体 ID 下运行按发送者划分的会话，则可能包含其他用户）。 -- `all`：任意会话。跨智能体定位仍然需要 `tools.agentToAgent`。 -- 沙箱钳制：当当前会话处于沙箱隔离中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 +- `tree`：当前会话 + 由当前会话派生的会话（subagents）。 +- `agent`：属于当前智能体 ID 的任意会话（如果你在同一智能体 ID 下运行按发送者划分的会话，可能包含其他用户）。 +- `all`：任意会话。跨智能体定位仍需要 `tools.agentToAgent`。 +- 沙箱限制：当当前会话处于沙箱隔离中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即便 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 ### `tools.sessions_spawn` @@ -2162,10 +2156,10 @@ Talk 模式（macOS/iOS/Android）的默认值。 tools: { sessions_spawn: { attachments: { - enabled: false, // 显式启用：设为 true 以允许内联文件附件 - maxTotalBytes: 5242880, // 所有文件总计 5 MB + enabled: false, // 选择性启用：设为 true 以允许内联文件附件 + maxTotalBytes: 5242880, // 所有文件合计 5 MB maxFiles: 50, - maxFileBytes: 1048576, // 每文件 1 MB + maxFileBytes: 1048576, // 每个文件 1 MB retainOnSessionKeep: false, // 当 cleanup="keep" 时保留附件 }, }, @@ -2173,18 +2167,18 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -说明： +注意： -- 附件仅对 `runtime: "subagent"` 提供支持。ACP 运行时会拒绝它们。 -- 文件会实体化到子 workspace 的 `.openclaw/attachments//` 中，并带有 `.manifest.json`。 +- 仅 `runtime: "subagent"` 支持附件。ACP 运行时会拒绝它们。 +- 文件会被实体化到子工作区的 `.openclaw/attachments//` 中，并包含 `.manifest.json`。 - 附件内容会自动从转录持久化中脱敏。 -- Base64 输入会使用严格的字母表/填充校验以及解码前大小保护。 -- 文件权限为：目录 `0700`，文件 `0600`。 -- 清理遵循 `cleanup` 策略：`delete` 总是删除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留。 +- Base64 输入会进行严格的字母表/填充校验，并在解码前进行大小保护。 +- 文件权限为目录 `0700`、文件 `0600`。 +- 清理由 `cleanup` 策略决定：`delete` 总会删除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留。 ### `tools.experimental` -实验性内置工具标志。除非有运行时特定自动启用规则，否则默认关闭。 +实验性内置工具开关。默认关闭，除非某条运行时特定的自动启用规则适用。 ```json5 { @@ -2196,11 +2190,11 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -说明： +注意： -- `planTool`：为非简单的多步骤工作跟踪启用结构化 `update_plan` 工具。 -- 默认值：对非 OpenAI 提供商为 `false`。OpenAI 和 OpenAI Codex 运行会自动启用它。 -- 启用后，系统提示也会添加使用说明，以便模型仅在实质性工作中使用它，并始终最多仅有一个步骤处于 `in_progress`。 +- `planTool`：为非平凡的多步骤工作跟踪启用结构化 `update_plan` 工具。 +- 默认值：对于非 OpenAI 提供商为 `false`。OpenAI 和 OpenAI Codex 运行会自动启用它。 +- 启用后，系统提示也会添加使用指导，使模型仅在实质性工作中使用它，并始终保持最多一个步骤为 `in_progress`。 ### `agents.defaults.subagents` @@ -2220,9 +2214,9 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -- `model`：生成子智能体时使用的默认模型。若省略，子智能体会继承调用者的模型。 -- `allowAgents`：当请求智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 目标智能体 ID 的默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。 -- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 的默认超时（秒）。`0` 表示无超时。 +- `model`：派生子智能体的默认模型。省略时，子智能体会继承调用者模型。 +- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，供 `sessions_spawn` 使用的默认目标智能体 ID 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 使用的默认超时（秒）。`0` 表示无超时。 - 每子智能体工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 --- @@ -2258,46 +2252,46 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -- 如需自定义认证，请使用 `authHeader: true` + `headers`。 +- 对于自定义认证需求，使用 `authHeader: true` + `headers`。 - 使用 `OPENCLAW_AGENT_DIR`（或旧版环境变量别名 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。 -- 对匹配提供商 ID 的合并优先级： +- 对于匹配 provider 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 管理的 provider `apiKey` 值会从源标记刷新（环境变量引用为 `ENV_VAR_NAME`，file/exec 引用为 `secretref-managed`），而不是持久化已解析的密钥。 + - 由 SecretRef 管理的 provider header 值会从源标记刷新（环境变量引用为 `secretref-env:ENV_VAR_NAME`，file/exec 引用为 `secretref-managed`）。 - 为空或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 - - 匹配模型的 `contextWindow`/`maxTokens` 会使用显式配置值和隐式目录值中的较高者。 - - 匹配模型的 `contextTokens` 会在存在时保留显式运行时上限；可用它限制有效上下文，而不改变模型原生元数据。 - - 如果你希望配置完全重写 `models.json`，请使用 `models.mode: "replace"`。 - - 标记持久化是“源权威”的：标记写入基于当前活跃的源配置快照（解析前），而不是基于已解析的运行时 secret 值。 + - 匹配模型的 `contextWindow`/`maxTokens` 会取显式配置值与隐式目录值中更高者。 + - 匹配模型的 `contextTokens` 在显式存在运行时上限时会保留；用它可以在不改变原生模型元数据的情况下限制有效上下文。 + - 当你希望配置完全重写 `models.json` 时，使用 `models.mode: "replace"`。 + - 标记持久化以源为权威：标记来自活动源配置快照（解析前）而非已解析的运行时 secret 值。 ### 提供商字段详情 -- `models.mode`：提供商目录行为（`merge` 或 `replace`）。 -- `models.providers`：以提供商 ID 为键的自定义提供商映射。 +- `models.mode`：provider 目录行为（`merge` 或 `replace`）。 +- `models.providers`：按 provider ID 为键的自定义 provider 映射。 - `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。 -- `models.providers.*.apiKey`：提供商凭证（优先使用 SecretRef/环境变量替换）。 +- `models.providers.*.apiKey`：provider 凭证（优先使用 SecretRef/环境变量替换）。 - `models.providers.*.auth`：认证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。 -- `models.providers.*.injectNumCtxForOpenAICompat`：对 Ollama + `openai-completions`，将 `options.num_ctx` 注入请求（默认：`true`）。 -- `models.providers.*.authHeader`：在需要时强制通过 `Authorization` header 传输凭证。 +- `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。 +- `models.providers.*.headers`：用于代理/租户路由的额外静态 header。 - `models.providers.*.request`：模型提供商 HTTP 请求的传输覆盖。 - - `request.headers`：额外 headers（与提供商默认值合并）。值接受 SecretRef。 - - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用提供商内置认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value`，可选 `prefix`）。 + - `request.headers`：额外 header（与 provider 默认值合并）。值支持 SecretRef。 + - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用 provider 内建认证）、`"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`。 -- `models.providers.*.models`：显式提供商模型目录条目。 -- `models.providers.*.models.*.contextWindow`：模型原生上下文窗口元数据。 + - `request.tls`：直连时的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（都支持 SecretRef）、`serverName`、`insecureSkipVerify`。 +- `models.providers.*.models`：显式 provider 模型目录条目。 +- `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 默认行为。 -- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根。 +- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且非空、非原生 `baseUrl`（host 不是 `api.openai.com`），OpenClaw 会在运行时强制将其设为 `false`。为空或省略 `baseUrl` 时保持默认 OpenAI 行为。 +- `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.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。 ### 提供商示例 @@ -2313,8 +2307,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）" }, }, }, }, @@ -2326,8 +2320,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）" }, ], }, }, @@ -2335,7 +2329,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`。 @@ -2352,7 +2346,7 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -设置 `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`。 @@ -2372,8 +2366,8 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` 设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 都是可接受的别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。 - 通用端点：`https://api.z.ai/api/paas/v4` -- 编码端点（默认）：`https://api.z.ai/api/coding/paas/v4` -- 若使用通用端点，请定义带有 base URL 覆盖的自定义提供商。 +- Coding 端点（默认）：`https://api.z.ai/api/coding/paas/v4` +- 对于通用端点，定义带 base URL 覆盖的自定义 provider。 @@ -2412,10 +2406,11 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -中国端点请使用：`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 现在会基于端点能力而非仅内置提供商 ID 来判断这一点。 +`openai-completions` 传输上声明流式使用兼容性，OpenClaw 现在根据端点 +能力而不是仅根据内置 provider ID 来决定这一点。 @@ -2433,7 +2428,7 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -兼容 Anthropic 的内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 +兼容 Anthropic 的内置 provider。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 @@ -2472,7 +2467,7 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。 +Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。 @@ -2515,17 +2510,16 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 设置 `MINIMAX_API_KEY`。快捷方式： `openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。 -模型目录现在默认仅包含 M2.7。 +模型目录现在默认仅使用 M2.7。 在兼容 Anthropic 的流式路径上，除非你显式设置 `thinking`，否则 OpenClaw 默认会禁用 MiniMax thinking。 -`/fast on` 或 -`params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 +`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 -参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在高性能硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留合并的托管模型作为回退。 +参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在性能充足的硬件上通过 LM Studio Responses API 运行大型本地模型；保留已合并的托管模型用于回退。 @@ -2556,13 +2550,13 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 } ``` -- `allowBundled`：仅对内置 Skills 生效的可选允许列表（托管/workspace Skills 不受影响）。 +- `allowBundled`：仅针对内置 Skills 的可选允许列表（托管/工作区 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`：为声明主环境变量的 Skill 提供便捷 API key 字段（明文字符串或 SecretRef 对象）。 +- `install.preferBrew`：为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器，再回退到其他安装器类型。 +- `install.nodeManager`：针对 `metadata.openclaw.install` + 规格的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false`：即使某个 Skill 已内置/已安装，也会将其禁用。 +- `entries..apiKey`：为声明了主环境变量的 Skills 提供的便捷 API key 字段（明文字符串或 SecretRef 对象）。 --- @@ -2591,40 +2585,40 @@ 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 便捷字段（当插件支持时）。 - `plugins.entries..env`：插件作用域环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，core 会阻止 `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 抓取提供商设置。 - - `apiKey`：Firecrawl API key（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。 +- `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 provider 设置。 + - `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 天）。 - - `timeoutSeconds`：抓取请求超时（秒）（默认：`60`）。 + - `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`：记忆 dreaming（实验性）设置。有关模式和阈值，请参见 [Dreaming](/zh-CN/concepts/dreaming)。 + - `enabled`：启用 X Search provider。 + - `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。 +- `plugins.entries.memory-core.config.dreaming`：记忆 dreaming（实验性）设置。模式和阈值参见 [Dreaming](/zh-CN/concepts/dreaming)。 - `mode`：dreaming 频率预设（`"off"`、`"core"`、`"rem"`、`"deep"`）。默认：`"off"`。 - - `cron`：dreaming 调度的可选 cron 表达式覆盖。 + - `cron`：可选的 dreaming 调度 cron 表达式覆盖。 - `timezone`：调度评估使用的时区（回退到 `agents.defaults.userTimezone`）。 - - `limit`：每个周期提升的候选项最大数。 - - `minScore`：提升所需的最小加权分阈值。 - - `minRecallCount`：最小回忆次数阈值。 + - `limit`：每个周期最多提升的候选数。 + - `minScore`：提升所需的最小加权分数阈值。 + - `minRecallCount`：最小回忆计数阈值。 - `minUniqueQueries`：最小不同查询数阈值。 - - `recencyHalfLifeDays`：新近度分数衰减为一半所需的天数。默认：`14`。 - - `maxAgeDays`：可选的每日笔记最大年龄（天），超过则不允许提升。 - - `verboseLogging`：将详细的每次运行 dreaming 日志输出到常规 Gateway 网关日志流。 -- 已启用的 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`。 + - `recencyHalfLifeDays`：近期性分数衰减到一半所需的天数。默认：`14`。 + - `maxAgeDays`：可选的最大日记年龄（按天），超出则不允许提升。 + - `verboseLogging`：将详细的每次 dreaming 日志输出到常规 Gateway 网关日志流。 +- 已启用的 Claude bundle 插件也可提供来自 `settings.json` 的嵌入式 Pi 默认值；OpenClaw 会将其作为净化后的智能体设置应用，而不是原始 OpenClaw 配置补丁。 +- `plugins.slots.memory`：选择活动记忆插件 ID，或设置为 `"none"` 以禁用记忆插件。 +- `plugins.slots.contextEngine`：选择活动上下文引擎插件 ID；默认是 `"legacy"`，除非你安装并选用了其他引擎。 +- `plugins.installs`：供 `openclaw plugins update` 使用的 CLI 管理安装元数据。 + - 包括 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。 - 将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。 参见 [Plugins](/zh-CN/tools/plugin)。 @@ -2640,7 +2634,7 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - dangerouslyAllowPrivateNetwork: true, // 默认的受信任网络模式 + dangerouslyAllowPrivateNetwork: true, // 默认可信网络模式 // allowPrivateNetwork: true, // 旧别名 // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], @@ -2668,27 +2662,21 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 ``` - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时默认是 `true`（受信任网络模型）。 -- 如需严格的仅公网浏览器导航，请设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: false`。 -- 在严格模式下，远程 CDP 配置端点（`profiles.*.cdpUrl`）在可达性/发现检查时也会受到同样的私有网络阻止策略约束。 -- `ssrfPolicy.allowPrivateNetwork` 仍然支持作为旧版别名。 -- 在严格模式下，请使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 作为显式例外。 -- 远程配置是仅附加模式（不支持 start/stop/reset）。 +- 当未设置时，`ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认是 `true`（可信网络模型）。 +- 如需严格的仅公共网络浏览导航，请设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: false`。 +- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间也会受到同样的私有网络阻止策略约束。 +- `ssrfPolicy.allowPrivateNetwork` 仍支持作为旧版别名。 +- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 添加显式例外。 +- 远程配置文件仅支持附加（禁用启动/停止/重置）。 - `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。 -- `existing-session` 配置保留当前 Chrome MCP 路由限制： - 使用 snapshot/ref 驱动的动作而不是 CSS 选择器定位， - 单文件上传钩子，不支持对话框超时覆盖，不支持 `wait --load networkidle`， - 也不支持 `responsebody`、PDF 导出、下载拦截或批量动作。 -- 本地托管的 `openclaw` 配置会自动分配 `cdpPort` 和 `cdpUrl`；只有远程 CDP 才需要显式设置 `cdpUrl`。 -- 自动检测顺序：默认浏览器（若为 Chromium 系）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 -- 控制服务：仅 loopback（端口由 `gateway.port` 推导，默认 `18791`）。 -- `extraArgs` 会为本地 Chromium 启动追加额外标志（例如 - `--disable-gpu`、窗口大小或调试标志）。 + 当你希望 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 路由限制：使用 snapshot/ref 驱动的操作而非 CSS 选择器定位、单文件上传 hook、不支持对话框超时覆盖、不支持 `wait --load networkidle`，以及不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 +- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 场景下才显式设置 `cdpUrl`。 +- 自动检测顺序：如果默认浏览器是基于 Chromium 则优先它 → Chrome → Brave → Edge → Chromium → Chrome Canary。 +- 控制服务：仅 loopback（端口由 `gateway.port` 派生，默认 `18791`）。 +- `extraArgs` 会将额外启动标志附加到本地 Chromium 启动中（例如 `--disable-gpu`、窗口大小或调试标志）。 --- @@ -2706,8 +2694,8 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 } ``` -- `seamColor`：原生应用 UI 外观的强调色（Talk Mode 气泡色调等）。 -- `assistant`：Control UI 身份覆盖。默认回退到当前活跃智能体身份。 +- `seamColor`：原生应用 UI 边框的强调色（Talk Mode 气泡着色等）。 +- `assistant`：Control UI 身份覆盖。默认回退到活动智能体身份。 --- @@ -2723,7 +2711,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, @@ -2740,8 +2728,8 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 enabled: true, basePath: "/openclaw", // root: "dist/control-ui", - // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必填 - // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host 头来源回退模式 + // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必需 + // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的基于 Host header 的 origin 回退模式 // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -2774,40 +2762,39 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 -- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关会拒绝启动。 -- `port`：WS + HTTP 的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 +- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关拒绝启动。 +- `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 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` 的身份头（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 代理源；同主机上的 loopback 反向代理不满足 trusted-proxy 认证条件。 -- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份头可满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 头认证；它们仍遵循 Gateway 网关正常的 HTTP 认证模式。此无 token 流程假定 Gateway 网关主机受信任。当 `tailscale.mode = "serve"` 时，默认值为 `true`。 -- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证作用域应用（共享密钥和设备 token 分别独立追踪）。被阻止的尝试会返回 `429` + `Retry-After`。 - - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试在写入失败记录前会被串行化。因此，同一客户端的并发错误尝试可能会在第二个请求时触发限流，而不是两个请求都当作普通不匹配穿过。 - - `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；若你有意让 localhost 流量也接受限流（用于测试环境或严格代理部署），可设为 `false`。 -- 来自浏览器来源的 WS 认证尝试始终会在关闭 loopback 豁免的情况下被限速（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。 -- 在 loopback 上，这些浏览器来源锁定会按标准化后的 `Origin` - 值相互隔离，因此来自一个 localhost origin 的重复失败不会自动 - 锁定另一个 origin。 -- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公网，需要认证）。 -- `controlUi.allowedOrigins`：Gateway 网关 WebSocket 连接的显式浏览器来源允许列表。当预期浏览器客户端来自非 loopback 来源时必须设置。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host 头来源策略的部署启用 Host 头来源回退。 +- **旧版 bind 别名**：在 `gateway.bind` 中使用 bind mode 值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用 host 别名（`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"`（或设为 `"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` 的身份 header（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求 **非 loopback** 代理源；同主机的 loopback 反向代理不满足 trusted-proxy 认证条件。 +- `gateway.auth.allowTailscale`：当为 `true` 时，Tailscale Serve 身份 header 可用于满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale header 认证；它们仍遵循 Gateway 网关的常规 HTTP 认证模式。此无 token 流程假定 Gateway 网关主机是受信任的。当 `tailscale.mode = "serve"` 时默认值为 `true`。 +- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证范围应用（共享密钥和设备 token 会独立跟踪）。被拦截的尝试会返回 `429` + `Retry-After`。 + - 在异步的 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试会在失败写入之前串行化。因此来自同一客户端的并发错误尝试，可能会在第二个请求时触发限流，而不是两个都作为普通不匹配并发通过。 + - `gateway.auth.rateLimit.exemptLoopback` 默认是 `true`；若你有意让 localhost 流量也受限流约束（测试环境或严格代理部署），请设为 `false`。 +- 源自浏览器的 WS 认证尝试始终会在禁用 loopback 豁免的条件下被限流（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。 +- 在 loopback 上，这些浏览器来源的锁定会按规范化后的 `Origin` + 值独立隔离，因此来自某个 localhost origin 的重复失败不会自动锁死不同的 origin。 +- `tailscale.mode`：`serve`（仅 tailnet，loopback 绑定）或 `funnel`（公开，需要认证）。 +- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器 origin 允许列表。当期望浏览器客户端来自非 loopback origin 时必需。 +- `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 使用明文。 +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧的破窗覆盖，允许对受信任私有网络 IP 使用明文 `ws://`；默认仍只允许 loopback 使用明文。 - `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。 -- `gateway.push.apns.relay.baseUrl`：外部 APNs relay 的 base HTTPS URL，供官方/TestFlight iOS 构建在将 relay 支持的注册发布到 Gateway 网关后使用。此 URL 必须与 iOS 构建中编译进去的 relay URL 一致。 +- `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 网关无法复用该已存储注册。 -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：对上述 relay 配置的临时环境变量覆盖。 -- `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`：每渠道选择退出健康监控重启，但保留全局监控启用。 -- `channels..accounts..healthMonitor.enabled`：多账号渠道的每账号覆盖。设置后优先于渠道级覆盖。 -- 本地 Gateway 网关调用路径仅在 `gateway.auth.*` 未设置时，才可将 `gateway.remote.*` 用作回退。 -- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但未解析成功，则解析会默认关闭（不会使用远程回退进行掩盖）。 -- `trustedProxies`：终止 TLS 或注入转发客户端头的反向代理 IP。仅列出你控制的代理。loopback 条目对同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理）仍然有效，但它们**不会**让 loopback 请求有资格使用 `gateway.auth.mode: "trusted-proxy"`。 -- `allowRealIpFallback`：为 `true` 时，当缺少 `X-Forwarded-For` 时，Gateway 网关接受 `X \ No newline at end of file +- 基于 relay 的注册会委托给特定的 Gateway 网关身份。配对后的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并向 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。 +- `gateway.channelHealthCheckMinutes`：渠道健康监视器间隔（分钟）。设为 `0` 可全局禁用健康监视重启。默认值：`5`。 +- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。应保持大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 +- `gateway.channelMaxRestartsPerHour`：滚动一小时内，每个渠道/账号的健康监视器最大重启次数。默认值：`10`。 +- `channels..healthMonitor.enabled`：在保留全局监视器启用的前提下，按渠道选择退出健康监视器重启。 +- `channels..accounts..healthMonitor.enabled`：多账号渠道的按账号覆盖。设置时，它优先于渠道级覆盖。 +- 仅当 `gateway.auth.*` 未设置时，本地 Gateway 网关调用路径才可将 `gateway.remote.*` 用作回退。 +- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但无法解析，则会以默认拒绝方式失败（不会使用远程回退来掩盖）。 +- `trustedProxies`：终止 TLS 或注入转发客户端 header 的反向代理 IP。只列出你控制的代理。loopback 条目对于同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理）仍然有效，但它们**不会**让 loopback 请求具备 `gateway.auth.mode: "trusted-proxy"` 资格。 +- `allowRealIpFallback`：为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认 `false` \ No newline at end of file