diff --git a/docs/zh-CN/channels/slack.md b/docs/zh-CN/channels/slack.md index 9d4384a64..01d5e1b9d 100644 --- a/docs/zh-CN/channels/slack.md +++ b/docs/zh-CN/channels/slack.md @@ -1,20 +1,20 @@ --- read_when: - - 设置 Slack 或调试 Slack socket/HTTP 模式时 -summary: Slack 设置与运行时行为（Socket Mode + HTTP Request URLs） + - 设置 Slack 或排查 Slack socket/HTTP 模式问题 +summary: Slack 设置和运行时行为（Socket Mode + HTTP Request URLs） title: Slack x-i18n: - generated_at: "2026-04-07T00:07:41Z" + generated_at: "2026-04-08T05:00:32Z" model: gpt-5.4 provider: openai - source_hash: 2b8fd2cc6c638ee82069f0af2c2b6f6f49c87da709b941433a0343724a9907ea + source_hash: cad132131ddce688517def7c14703ad314441c67aacc4cc2a2a721e1d1c01942 source_path: channels/slack.md workflow: 15 --- # Slack -状态：已可用于通过 Slack 应用集成实现私信和渠道。默认模式为 Socket Mode；也支持 HTTP Request URLs。 +状态：已可用于通过 Slack 应用集成在私信和渠道中投入生产使用。默认模式为 Socket Mode；也支持 HTTP Request URLs。 @@ -24,7 +24,7 @@ x-i18n: 原生命令行为和命令目录。 - 跨渠道诊断与修复操作手册。 + 跨渠道诊断和修复操作手册。 @@ -37,9 +37,9 @@ x-i18n: 在 Slack 应用设置中，点击 **[Create New App](https://api.slack.com/apps/new)** 按钮： - 选择 **from a manifest**，并为你的应用选择一个工作区 - - 粘贴下方的[示例清单](#manifest-and-scope-checklist)，然后继续创建 - - 生成带有 `connections:write` 权限的 **App-Level Token**（`xapp-...`） - - 安装应用，并复制显示的 **Bot Token**（`xoxb-...`） + - 粘贴下面的[示例清单](#manifest-and-scope-checklist)，然后继续创建 + - 生成一个带有 `connections:write` 的 **App-Level Token**（`xapp-...`） + - 安装应用并复制显示的 **Bot Token**（`xoxb-...`） @@ -85,7 +85,7 @@ openclaw gateway - 选择 **from a manifest**，并为你的应用选择一个工作区 - 粘贴[示例清单](#manifest-and-scope-checklist)，并在创建前更新 URL - 保存用于请求校验的 **Signing Secret** - - 安装应用，并复制显示的 **Bot Token**（`xoxb-...`） + - 安装应用并复制显示的 **Bot Token**（`xoxb-...`） @@ -108,7 +108,7 @@ openclaw gateway 为多账户 HTTP 使用唯一的 webhook 路径 - 为每个账户分配不同的 `webhookPath`（默认是 `/slack/events`），以避免注册冲突。 + 为每个账户指定不同的 `webhookPath`（默认是 `/slack/events`），以避免注册冲突。 @@ -125,7 +125,7 @@ openclaw gateway -## 清单与作用域检查清单 +## 清单和 scope 检查清单 @@ -290,14 +290,14 @@ openclaw gateway - - 如果你希望发出的消息使用当前智能体身份（自定义用户名和图标），而不是默认的 Slack 应用身份，请添加 `chat:write.customize` bot scope。 + + 如果你希望出站消息使用当前智能体身份（自定义用户名和图标），而不是默认的 Slack 应用身份，请添加 `chat:write.customize` bot scope。 - 如果你使用 emoji 图标，Slack 要求采用 `:emoji_name:` 语法。 + 如果你使用表情图标，Slack 期望使用 `:emoji_name:` 语法。 - - 如果你配置了 `channels.slack.userToken`，典型的读取作用域包括： + + 如果你配置了 `channels.slack.userToken`，典型读取 scope 包括： - `channels:history`, `groups:history`, `im:history`, `mpim:history` - `channels:read`, `groups:read`, `im:read`, `mpim:read` @@ -314,39 +314,39 @@ openclaw gateway - Socket Mode 需要 `botToken` + `appToken`。 - HTTP 模式需要 `botToken` + `signingSecret`。 -- `botToken`、`appToken`、`signingSecret` 和 `userToken` 支持明文字符串或 SecretRef 对象。 +- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串或 SecretRef 对象。 - 配置中的令牌会覆盖环境变量回退。 - `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` 环境变量回退仅适用于默认账户。 -- `userToken`（`xoxp-...`）仅支持通过配置提供（无环境变量回退），并默认采用只读行为（`userTokenReadOnly: true`）。 +- `userToken`（`xoxp-...`）仅可通过配置提供（无环境变量回退），且默认是只读行为（`userTokenReadOnly: true`）。 状态快照行为： -- Slack 账户检查会跟踪每个凭证的 `*Source` 和 `*Status` 字段（`botToken`、`appToken`、`signingSecret`、`userToken`）。 -- 状态值可以是 `available`、`configured_unavailable` 或 `missing`。 -- `configured_unavailable` 表示该账户通过 SecretRef 或其他非内联密钥源完成了配置，但当前命令或运行时路径无法解析实际值。 -- 在 HTTP 模式下会包含 `signingSecretStatus`；在 Socket Mode 下，必需的令牌对是 `botTokenStatus` + `appTokenStatus`。 +- Slack 账户检查会跟踪每个凭证对应的 `*Source` 和 `*Status` 字段（`botToken`、`appToken`、`signingSecret`、`userToken`）。 +- 状态值为 `available`、`configured_unavailable` 或 `missing`。 +- `configured_unavailable` 表示该账户通过 SecretRef 或其他非内联密钥来源完成了配置，但当前命令/运行时路径无法解析实际值。 +- 在 HTTP 模式下，会包含 `signingSecretStatus`；在 Socket Mode 下，所需的凭证对是 `botTokenStatus` + `appTokenStatus`。 -对于 actions/目录读取，如果配置了用户令牌，则可以优先使用用户令牌。对于写入操作，仍优先使用 bot 令牌；只有在 `userTokenReadOnly: false` 且 bot 令牌不可用时，才允许使用用户令牌写入。 +对于操作/目录读取，如果已配置用户令牌，则可以优先使用用户令牌。对于写入，仍优先使用 bot 令牌；只有在 `userTokenReadOnly: false` 且 bot 令牌不可用时，才允许使用用户令牌写入。 -## 操作与门控 +## 操作和门控 Slack 操作由 `channels.slack.actions.*` 控制。 -当前 Slack 工具中可用的操作分组： +当前 Slack 工具中的可用操作组： -| 分组 | 默认值 | +| 组 | 默认值 | | ---------- | ------- | -| messages | enabled | -| reactions | enabled | -| pins | enabled | -| memberInfo | enabled | -| emojiList | enabled | +| messages | 启用 | +| reactions | 启用 | +| pins | 启用 | +| memberInfo | 启用 | +| emojiList | 启用 | 当前 Slack 消息操作包括 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。 -## 访问控制与路由 +## 访问控制和路由 @@ -360,18 +360,18 @@ Slack 操作由 `channels.slack.actions.*` 控制。 私信标志： - `dm.enabled`（默认 true） - - `channels.slack.allowFrom`（推荐） + - `channels.slack.allowFrom`（首选） - `dm.allowFrom`（旧版） - - `dm.groupEnabled`（群组私信默认 false） + - `dm.groupEnabled`（群私信默认 false） - `dm.groupChannels`（可选 MPIM 允许列表） 多账户优先级： - `channels.slack.accounts.default.allowFrom` 仅适用于 `default` 账户。 - - 已命名账户在自身 `allowFrom` 未设置时，会继承 `channels.slack.allowFrom`。 - - 已命名账户不会继承 `channels.slack.accounts.default.allowFrom`。 + - 命名账户在其自身 `allowFrom` 未设置时，会继承 `channels.slack.allowFrom`。 + - 命名账户不会继承 `channels.slack.accounts.default.allowFrom`。 - 在私信中进行配对时，使用 `openclaw pairing approve slack `。 + 私信中的配对使用 `openclaw pairing approve slack `。 @@ -382,28 +382,28 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - `allowlist` - `disabled` - 渠道允许列表位于 `channels.slack.channels` 下，应使用稳定的渠道 ID。 + 渠道允许列表位于 `channels.slack.channels` 下，并应使用稳定的渠道 ID。 - 运行时说明：如果 `channels.slack` 完全缺失（仅使用环境变量设置），运行时会回退到 `groupPolicy="allowlist"` 并记录警告（即使设置了 `channels.defaults.groupPolicy` 也是如此）。 + 运行时说明：如果 `channels.slack` 完全缺失（仅使用环境变量设置），运行时会回退到 `groupPolicy="allowlist"` 并记录警告（即使已设置 `channels.defaults.groupPolicy` 也是如此）。 名称/ID 解析： - - 在令牌访问允许的情况下，渠道允许列表条目和私信允许列表条目会在启动时解析 - - 无法解析的渠道名条目会按配置保留，但默认在路由时被忽略 - - 入站授权和渠道路由默认优先使用 ID；直接的用户名/slug 匹配要求设置 `channels.slack.dangerouslyAllowNameMatching: true` + - 当令牌访问允许时，渠道允许列表条目和私信允许列表条目会在启动时解析 + - 无法解析的渠道名称条目会按配置保留，但默认会在路由时被忽略 + - 入站授权和渠道路由默认优先使用 ID；直接用户名/slug 匹配需要 `channels.slack.dangerouslyAllowNameMatching: true` - - 渠道消息默认受提及门控控制。 + + 渠道消息默认受提及门控限制。 提及来源： - 显式应用提及（`<@botId>`） - - 提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） - - 隐式回复 bot 线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用） + - 提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`） + - 隐式回复机器人线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用） - 每个渠道的控制项（`channels.slack.channels.`；名称仅可通过启动解析或 `dangerouslyAllowNameMatching` 使用）： + 每渠道控制（`channels.slack.channels.`；名称仅通过启动解析或 `dangerouslyAllowNameMatching` 生效）： - `requireMention` - `users`（允许列表） @@ -412,49 +412,49 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - `systemPrompt` - `tools`, `toolsBySender` - `toolsBySender` 键格式：`id:`、`e164:`、`username:`、`name:` 或 `"*"` 通配符 - （旧版未加前缀的键仍仅映射到 `id:`） + （旧版无前缀键仍仅映射到 `id:`） -## 线程、会话与回复标签 +## 线程、会话和回复标签 -- 私信路由为 `direct`；渠道为 `channel`；MPIM 为 `group`。 -- 在默认 `session.dmScope=main` 下，Slack 私信会折叠到智能体主会话。 +- 私信路由为 `direct`；渠道路由为 `channel`；MPIM 路由为 `group`。 +- 使用默认 `session.dmScope=main` 时，Slack 私信会合并到智能体主会话。 - 渠道会话：`agent::slack:channel:`。 -- 线程回复在适用时可创建线程会话后缀（`:thread:`）。 -- `channels.slack.thread.historyScope` 默认是 `thread`；`thread.inheritParent` 默认是 `false`。 -- `channels.slack.thread.initialHistoryLimit` 控制新线程会话开始时获取多少已有线程消息（默认 `20`；设为 `0` 可禁用）。 -- `channels.slack.thread.requireExplicitMention`（默认 `false`）：设为 `true` 时，会抑制隐式线程提及，因此 bot 只会响应线程中的显式 `@bot` 提及，即使 bot 已经参与了该线程。若不启用此项，在 bot 已参与的线程中回复将绕过 `requireMention` 门控。 +- 在线程回复适用时，可创建带线程会话后缀（`:thread:`）的会话。 +- `channels.slack.thread.historyScope` 默认值为 `thread`；`thread.inheritParent` 默认值为 `false`。 +- `channels.slack.thread.initialHistoryLimit` 控制新线程会话启动时抓取多少已有线程消息（默认 `20`；设为 `0` 可禁用）。 +- `channels.slack.thread.requireExplicitMention`（默认 `false`）：设为 `true` 时，会抑制隐式线程提及，因此机器人只会响应线程中的显式 `@bot` 提及，即使机器人已经参与该线程。若不启用此项，已参与机器人线程中的回复会绕过 `requireMention` 门控。 回复线程控制： - `channels.slack.replyToMode`: `off|first|all|batched`（默认 `off`） -- `channels.slack.replyToModeByChatType`: 按 `direct|group|channel` 分别设置 -- 私聊的旧版回退：`channels.slack.dm.replyToMode` +- `channels.slack.replyToModeByChatType`: 按 `direct|group|channel` +- 私聊旧版回退：`channels.slack.dm.replyToMode` 支持手动回复标签： - `[[reply_to_current]]` - `[[reply_to:]]` -注意：`replyToMode="off"` 会禁用 Slack 中**所有**回复线程能力，包括显式的 `[[reply_to_*]]` 标签。这与 Telegram 不同，在 Telegram 中，显式标签在 `"off"` 模式下仍会生效。这种差异反映了平台的线程模型：Slack 线程会把消息隐藏在渠道之外，而 Telegram 回复仍会显示在主聊天流中。 +注意：`replyToMode="off"` 会禁用 Slack 中**所有**回复线程，包括显式 `[[reply_to_*]]` 标签。这与 Telegram 不同，在 Telegram 中，显式标签在 `"off"` 模式下仍会生效。这种差异反映了平台的线程模型：Slack 线程会将消息隐藏在渠道主流之外，而 Telegram 回复仍然显示在主聊天流中。 -## 确认反应 +## Ack 反应 -`ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认 emoji。 +`ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认表情。 解析顺序： - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` - `messages.ackReaction` -- 智能体身份 emoji 回退（`agents.list[].identity.emoji`，否则为 `"👀"`） +- 智能体身份表情回退（`agents.list[].identity.emoji`，否则为 `"👀"`） 说明： -- Slack 需要使用 shortcode（例如 `"eyes"`）。 -- 使用 `""` 可为该 Slack 账户或全局禁用该反应。 +- Slack 期望使用简码（例如 `"eyes"`）。 +- 使用 `""` 可为 Slack 账户或全局禁用该反应。 ## 文本流式传输 @@ -465,11 +465,13 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - `block`：追加分块预览更新。 - `progress`：生成期间显示进度状态文本，然后发送最终文本。 -当 `streaming` 为 `partial` 时，`channels.slack.nativeStreaming` 控制 Slack 原生文本流式传输（默认：`true`）。 +当 `channels.slack.streaming.mode` 为 `partial` 时，`channels.slack.streaming.nativeTransport` 控制 Slack 原生文本流式传输（默认：`true`）。 -- 必须存在回复线程，原生文本流式传输才会显示。线程选择仍遵循 `replyToMode`。如果没有线程，则会使用普通草稿预览。 -- 媒体和非文本负载会回退到普通投递方式。 -- 如果流式传输在回复中途失败，OpenClaw 会将剩余负载回退为普通投递。 +- 必须有可用的回复线程，Slack 原生文本流式传输和 Slack assistant 线程状态才会显示。线程选择仍遵循 `replyToMode`。 +- 当原生流式传输不可用时，渠道和群聊根消息仍可使用普通草稿预览。 +- 顶层 Slack 私信默认保持非线程模式，因此不会显示线程式预览；如果你希望那里有可见进度，请使用线程回复或 `typingReaction`。 +- 媒体和非文本负载会回退到普通投递。 +- 如果流式传输在回复中途失败，OpenClaw 会对剩余负载回退到普通投递。 使用草稿预览而不是 Slack 原生文本流式传输： @@ -477,8 +479,10 @@ Slack 操作由 `channels.slack.actions.*` 控制。 { channels: { slack: { - streaming: "partial", - nativeStreaming: false, + streaming: { + mode: "partial", + nativeTransport: false, + }, }, }, } @@ -486,12 +490,13 @@ Slack 操作由 `channels.slack.actions.*` 控制。 旧版键： -- `channels.slack.streamMode`（`replace | status_final | append`）会自动迁移到 `channels.slack.streaming`。 -- 布尔值 `channels.slack.streaming` 会自动迁移到 `channels.slack.nativeStreaming`。 +- `channels.slack.streamMode`（`replace | status_final | append`）会自动迁移到 `channels.slack.streaming.mode`。 +- 布尔值 `channels.slack.streaming` 会自动迁移到 `channels.slack.streaming.mode` 和 `channels.slack.streaming.nativeTransport`。 +- 旧版 `channels.slack.nativeStreaming` 会自动迁移到 `channels.slack.streaming.nativeTransport`。 -## 输入中反应回退 +## 正在输入反应回退 -`typingReaction` 会在 OpenClaw 处理回复期间，为入站 Slack 消息添加一个临时反应，并在本次运行结束时移除。它在线程回复之外最有用，因为线程回复默认使用 “is typing...” 状态指示。 +`typingReaction` 会在 OpenClaw 处理回复期间，为入站 Slack 消息临时添加一个反应，并在运行结束时将其移除。这在非线程回复场景中特别有用，因为线程回复会使用默认的“正在输入...”状态指示器。 解析顺序： @@ -500,28 +505,28 @@ Slack 操作由 `channels.slack.actions.*` 控制。 说明： -- Slack 需要使用 shortcode（例如 `"hourglass_flowing_sand"`）。 -- 该反应采用尽力而为方式，且在回复或失败路径完成后会自动尝试清理。 +- Slack 期望使用简码（例如 `"hourglass_flowing_sand"`）。 +- 该反应属于尽力而为，系统会在回复完成或失败路径结束后自动尝试清理。 -## 媒体、分块与投递 +## 媒体、分块和投递 - Slack 文件附件会从 Slack 托管的私有 URL 下载（基于令牌认证的请求流程），并在抓取成功且大小限制允许时写入媒体存储。 + Slack 文件附件会通过 Slack 托管的私有 URL 下载（基于令牌鉴权的请求流程），并在获取成功且大小限制允许时写入媒体存储。 运行时入站大小上限默认为 `20MB`，除非通过 `channels.slack.mediaMaxMb` 覆盖。 - + - 文本分块使用 `channels.slack.textChunkLimit`（默认 4000） - `channels.slack.chunkMode="newline"` 启用按段落优先拆分 - 文件发送使用 Slack 上传 API，并可包含线程回复（`thread_ts`） - - 如果配置了 `channels.slack.mediaMaxMb`，出站媒体上限遵循该值；否则渠道发送使用媒体流水线中的 MIME 类型默认值 + - 配置 `channels.slack.mediaMaxMb` 时，出站媒体上限遵循该值；否则渠道发送使用媒体管道中的 MIME 类型默认值 - 推荐使用显式目标： + 首选的显式目标： - `user:` 用于私信 - `channel:` 用于渠道 @@ -531,19 +536,19 @@ Slack 操作由 `channels.slack.actions.*` 控制。 -## 命令与斜杠行为 +## 命令和斜杠行为 - Slack 的原生命令自动模式默认**关闭**（`commands.native: "auto"` 不会启用 Slack 原生命令）。 -- 使用 `channels.slack.commands.native: true`（或全局 `commands.native: true`）启用 Slack 原生命令处理器。 +- 使用 `channels.slack.commands.native: true`（或全局 `commands.native: true`）启用原生 Slack 命令处理器。 - 启用原生命令后，在 Slack 中注册匹配的斜杠命令（`/` 名称），但有一个例外： - 为状态命令注册 `/agentstatus`（Slack 保留 `/status`） -- 如果未启用原生命令，你可以通过 `channels.slack.slashCommand` 运行一个已配置的单一斜杠命令。 +- 如果未启用原生命令，你可以通过 `channels.slack.slashCommand` 运行单个已配置的斜杠命令。 - 原生参数菜单现在会自适应其渲染策略： - 最多 5 个选项：按钮块 - 6-100 个选项：静态选择菜单 - - 超过 100 个选项：当可用 interactivity 选项处理器时，使用带异步选项过滤的外部选择 - - 如果编码后的选项值超出 Slack 限制，该流程会回退为按钮 -- 对于较长的选项负载，斜杠命令参数菜单会在分发所选值之前显示确认对话框。 + - 超过 100 个选项：当交互选项处理器可用时，使用支持异步选项过滤的外部选择 + - 如果编码后的选项值超过 Slack 限制，流程会回退到按钮 +- 对于较长的选项负载，斜杠命令参数菜单会在派发所选值前使用确认对话框。 默认斜杠命令设置： @@ -556,11 +561,11 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - `agent::slack:slash:` -并且仍会根据目标会话键（`CommandTargetSessionKey`）对目标会话执行命令路由。 +并且仍会将命令执行路由到目标会话（`CommandTargetSessionKey`）。 ## 交互式回复 -Slack 可以渲染由智能体编写的交互式回复控件，但该功能默认禁用。 +Slack 可以渲染由智能体编写的交互式回复控件，但此功能默认禁用。 全局启用： @@ -576,7 +581,7 @@ Slack 可以渲染由智能体编写的交互式回复控件，但该功能默 } ``` -或者仅为某个 Slack 账户启用： +或者仅为一个 Slack 账户启用： ```json5 { @@ -603,32 +608,34 @@ Slack 可以渲染由智能体编写的交互式回复控件，但该功能默 说明： -- 这是 Slack 专用 UI。其他渠道不会将 Slack Block Kit 指令翻译为它们自己的按钮系统。 -- 交互回调值是 OpenClaw 生成的不透明令牌，不是智能体编写的原始值。 -- 如果生成的交互块会超出 Slack Block Kit 限制，OpenClaw 会回退为原始文本回复，而不是发送无效的 blocks 负载。 +- 这是 Slack 专用 UI。其他渠道不会将 Slack Block Kit 指令转换为它们自己的按钮系统。 +- 交互回调值是 OpenClaw 生成的不透明令牌，而不是智能体原始编写的值。 +- 如果生成的交互块会超过 Slack Block Kit 限制，OpenClaw 会回退为原始文本回复，而不是发送无效的 blocks 负载。 ## Slack 中的 Exec 审批 -Slack 可以作为原生审批客户端，使用交互式按钮和交互，而不是回退到 Web UI 或终端。 +Slack 可以充当原生审批客户端，使用交互按钮和交互流程，而不是回退到 Web UI 或终端。 - Exec 审批使用 `channels.slack.execApprovals.*` 进行原生私信/渠道路由。 -- 当请求已落在 Slack 中且审批 ID 类型为 `plugin:` 时，插件审批仍可通过同样的 Slack 原生按钮界面完成。 +- 当请求已经到达 Slack 且审批 ID 类型为 `plugin:` 时，插件审批仍可通过同一个 Slack 原生按钮界面进行处理。 - 审批人授权仍会被强制执行：只有被识别为审批人的用户才能通过 Slack 批准或拒绝请求。 -这使用与其他渠道相同的共享审批按钮界面。当你在 Slack 应用设置中启用 `interactivity` 时，审批提示会直接在会话中渲染为 Block Kit 按钮。 -当这些按钮存在时，它们就是主要的审批 UX；只有当工具结果表明聊天审批不可用或手动审批是唯一途径时，OpenClaw 才应包含手动 `/approve` 命令。 +这使用与其他渠道相同的共享审批按钮界面。当你的 Slack 应用设置中启用了 `interactivity` 时，审批提示会直接以 Block Kit 按钮形式渲染在会话中。 +当这些按钮存在时，它们就是主要的审批体验；只有当工具结果表明聊天审批不可用，或手动审批是唯一途径时，OpenClaw +才应包含手动 `/approve` 命令。 配置路径： - `channels.slack.execApprovals.enabled` -- `channels.slack.execApprovals.approvers`（可选；在可能时回退到 `commands.ownerAllowFrom`） +- `channels.slack.execApprovals.approvers`（可选；尽可能回退到 `commands.ownerAllowFrom`） - `channels.slack.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`） - `agentFilter`、`sessionFilter` -当 `enabled` 未设置或为 `"auto"`，且至少解析出一位审批人时，Slack 会自动启用原生 exec 审批。设置 `enabled: false` 可显式禁用 Slack 作为原生审批客户端。 -设置 `enabled: true` 可在审批人成功解析时强制启用原生审批。 +当 `enabled` 未设置或为 `"auto"`，且至少解析出一名 +approver 时，Slack 会自动启用原生 exec 审批。设置 `enabled: false` 可显式禁用 Slack 作为原生审批客户端。 +设置 `enabled: true` 可在 approver 解析成功时强制启用原生审批。 -没有显式 Slack exec 审批配置时的默认行为： +无显式 Slack exec 审批配置时的默认行为： ```json5 { @@ -638,7 +645,8 @@ Slack 可以作为原生审批客户端，使用交互式按钮和交互，而 } ``` -只有当你想覆盖审批人、添加筛选器或启用源聊天投递时，才需要显式的 Slack 原生配置： +只有在你希望覆盖 approver、添加过滤器，或 +选择将审批投递到来源聊天时，才需要显式 Slack 原生配置： ```json5 { @@ -654,35 +662,38 @@ Slack 可以作为原生审批客户端，使用交互式按钮和交互，而 } ``` -共享的 `approvals.exec` 转发是独立的。只有当 exec 审批提示还必须路由到其他聊天或显式的带外目标时，才使用它。共享的 `approvals.plugin` 转发同样独立；当这些请求已经落在 Slack 中时，Slack 原生按钮仍可完成插件审批。 +共享 `approvals.exec` 转发是独立的。仅在 exec 审批提示还必须 +路由到其他聊天或显式带外目标时才使用它。共享 `approvals.plugin` 转发也 +是独立的；当这些请求已经到达 +Slack 时，Slack 原生按钮仍可处理插件审批。 -同一聊天中的 `/approve` 也可在已支持命令的 Slack 渠道和私信中使用。完整审批转发模型请参见 [Exec approvals](/zh-CN/tools/exec-approvals)。 +同聊天 `/approve` 在已支持命令的 Slack 渠道和私信中同样可用。完整的审批转发模型请参见 [Exec approvals](/zh-CN/tools/exec-approvals)。 -## 事件与运行行为 +## 事件和运行行为 - 消息编辑/删除/线程广播会映射为系统事件。 - 反应添加/移除事件会映射为系统事件。 -- 成员加入/离开、渠道创建/重命名以及置顶添加/移除事件会映射为系统事件。 -- 当启用 `configWrites` 时，`channel_id_changed` 可迁移渠道配置键。 -- 渠道 topic/purpose 元数据被视为不可信上下文，并可注入路由上下文。 -- 在线程发起者和初始线程历史上下文填充时，会在适用情况下按已配置的发送者允许列表进行过滤。 -- Block actions 和 modal 交互会发出结构化的 `Slack interaction: ...` 系统事件，并包含丰富的负载字段： - - block actions：所选值、标签、选择器值以及 `workflow_*` 元数据 - - modal `view_submission` 和 `view_closed` 事件，带有已路由的渠道元数据和表单输入 +- 成员加入/离开、渠道创建/重命名，以及 pin 添加/移除事件会映射为系统事件。 +- 当启用 `configWrites` 时，`channel_id_changed` 可以迁移渠道配置键。 +- 渠道 topic/purpose 元数据被视为不可信上下文，并可注入到路由上下文中。 +- 在线程发起者和初始线程历史上下文植入时，会在适用情况下按已配置的发送方允许列表进行过滤。 +- Block 操作和模态交互会发出结构化的 `Slack interaction: ...` 系统事件，并携带丰富的负载字段： + - block 操作：所选值、标签、选择器值以及 `workflow_*` 元数据 + - 模态 `view_submission` 和 `view_closed` 事件，包含路由后的渠道元数据和表单输入 -## 配置参考指针 +## 配置参考指引 主要参考： - [配置参考 - Slack](/zh-CN/gateway/configuration-reference#slack) - 高信号的 Slack 字段： - - 模式/凭证：`mode`、`botToken`、`appToken`、`signingSecret`、`webhookPath`、`accounts.*` + 高信号 Slack 字段： + - mode/auth：`mode`、`botToken`、`appToken`、`signingSecret`、`webhookPath`、`accounts.*` - 私信访问：`dm.enabled`、`dmPolicy`、`allowFrom`（旧版：`dm.policy`、`dm.allowFrom`）、`dm.groupEnabled`、`dm.groupChannels` - - 兼容性开关：`dangerouslyAllowNameMatching`（破玻璃开关；除非确有需要，否则保持关闭） + - 兼容性开关：`dangerouslyAllowNameMatching`（紧急兜底；除非确有需要，否则保持关闭） - 渠道访问：`groupPolicy`、`channels.*`、`channels.*.users`、`channels.*.requireMention` - 线程/历史：`replyToMode`、`replyToModeByChatType`、`thread.*`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` - - 投递：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`streaming`、`nativeStreaming` + - 投递：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`streaming`、`streaming.nativeTransport` - 运维/功能：`configWrites`、`commands.native`、`slashCommand.*`、`actions.*`、`userToken`、`userTokenReadOnly` ## 故障排除 @@ -694,7 +705,7 @@ Slack 可以作为原生审批客户端，使用交互式按钮和交互，而 - `groupPolicy` - 渠道允许列表（`channels.slack.channels`） - `requireMention` - - 每个渠道的 `users` 允许列表 + - 每渠道 `users` 允许列表 有用的命令： @@ -711,7 +722,7 @@ openclaw doctor - `channels.slack.dm.enabled` - `channels.slack.dmPolicy`（或旧版 `channels.slack.dm.policy`） - - 配对审批 / 允许列表条目 + - 配对批准 / 允许列表条目 ```bash openclaw pairing list slack @@ -720,16 +731,17 @@ openclaw pairing list slack - 验证 bot 与 app 令牌，以及 Slack 应用设置中的 Socket Mode 是否已启用。 + 校验 bot 和 app 令牌，以及 Slack 应用设置中的 Socket Mode 是否已启用。 如果 `openclaw channels status --probe --json` 显示 `botTokenStatus` 或 - `appTokenStatus: "configured_unavailable"`，说明 Slack 账户已配置， - 但当前运行时无法解析由 SecretRef 支持的实际值。 + `appTokenStatus: "configured_unavailable"`，则表示 Slack 账户 + 已配置，但当前运行时无法解析由 SecretRef 支持的 + 实际值。 - - 验证： + + 校验： - signing secret - webhook 路径 @@ -737,17 +749,18 @@ openclaw pairing list slack - 每个 HTTP 账户使用唯一的 `webhookPath` 如果账户快照中出现 `signingSecretStatus: "configured_unavailable"`， - 说明该 HTTP 账户已配置，但当前运行时无法解析由 SecretRef 支持的 signing secret。 + 则表示该 HTTP 账户已配置，但当前运行时无法 + 解析由 SecretRef 支持的 signing secret。 - 请确认你想要的是： + 确认你想要的是： - - 原生命令模式（`channels.slack.commands.native: true`），并在 Slack 中注册匹配的斜杠命令 + - 原生命令模式（`channels.slack.commands.native: true`），并且已在 Slack 中注册匹配的斜杠命令 - 或单一斜杠命令模式（`channels.slack.slashCommand.enabled: true`） - 还要检查 `commands.useAccessGroups` 以及渠道/用户允许列表。 + 另外也请检查 `commands.useAccessGroups` 以及渠道/用户允许列表。 diff --git a/docs/zh-CN/concepts/streaming.md b/docs/zh-CN/concepts/streaming.md index 5c6cc18a1..f65766ee8 100644 --- a/docs/zh-CN/concepts/streaming.md +++ b/docs/zh-CN/concepts/streaming.md @@ -1,111 +1,114 @@ --- read_when: - - 解释渠道上的流式传输或分块如何工作 - - 修改分块流式传输或渠道分块行为 - - 调试重复 / 过早的分块回复或渠道预览流式传输 + - 说明流式传输或分块在各渠道中的工作方式 + - 更改分块流式传输或渠道分块行为 + - 调试重复/过早的分块回复或渠道预览流式传输 summary: 流式传输 + 分块行为（分块回复、渠道预览流式传输、模式映射） title: 流式传输和分块 x-i18n: - generated_at: "2026-04-05T08:22:40Z" + generated_at: "2026-04-08T04:59:54Z" model: gpt-5.4 provider: openai - source_hash: 44b0d08c7eafcb32030ef7c8d5719c2ea2d34e4bac5fdad8cc8b3f4e9e9fad97 + source_hash: a8e847bb7da890818cd79dec7777f6ae488e6d6c0468e948e56b6b6c598e0000 source_path: concepts/streaming.md workflow: 15 --- # 流式传输 + 分块 -OpenClaw 有两个彼此独立的流式传输层： +OpenClaw 有两层彼此独立的流式传输： -- **分块流式传输（渠道）：** 当助手写出完整**块**时立即发送。这些是普通渠道消息（不是 token 增量）。 -- **预览流式传输（Telegram / Discord / Slack）：** 在生成过程中更新一个临时的**预览消息**。 +- **分块流式传输（渠道）：** 在助手写作时发送已完成的**块**。这些是正常的渠道消息（不是 token 增量）。 +- **预览流式传输（Telegram/Discord/Slack）：** 在生成过程中更新一个临时的**预览消息**。 -目前还**没有真正的 token 增量流式传输**到渠道消息。预览流式传输是基于消息的（发送 + 编辑 / 追加）。 +目前还**没有真正的 token 增量流式传输**发送到渠道消息。预览流式传输是基于消息的（发送 + 编辑/追加）。 ## 分块流式传输（渠道消息） -分块流式传输会在内容可用时，以较粗粒度的块发送助手输出。 +分块流式传输会在助手输出可用时，以较粗粒度的块发送。 ``` -模型输出 +Model output └─ text_delta/events ├─ (blockStreamingBreak=text_end) - │ └─ 随着缓冲区增长，chunker 发出块 + │ └─ chunker emits blocks as buffer grows └─ (blockStreamingBreak=message_end) - └─ chunker 在 message_end 时刷新 - └─ 渠道发送（分块回复） + └─ chunker flushes at message_end + └─ channel send (block replies) ``` 图例： -- `text_delta/events`：模型流事件（对于非流式模型，可能较稀疏）。 -- `chunker`：应用最小 / 最大边界和断点偏好的 `EmbeddedBlockChunker`。 -- `channel send`：实际的出站消息（分块回复）。 +- `text_delta/events`：模型流事件（对于非流式模型，这些事件可能很稀疏）。 +- `chunker`：应用最小/最大边界和断点偏好的 `EmbeddedBlockChunker`。 +- `channel send`：实际发出的出站消息（分块回复）。 **控制项：** -- `agents.defaults.blockStreamingDefault`：`"on"` / `"off"`（默认关闭）。 -- 渠道覆盖：`*.blockStreaming`（以及按账户变体），用于为每个渠道强制设为 `"on"` / `"off"`。 +- `agents.defaults.blockStreamingDefault`：`"on"`/`"off"`（默认关闭）。 +- 渠道覆盖：`*.blockStreaming`（以及每账号变体）可为每个渠道强制设为 `"on"`/`"off"`。 - `agents.defaults.blockStreamingBreak`：`"text_end"` 或 `"message_end"`。 - `agents.defaults.blockStreamingChunk`：`{ minChars, maxChars, breakPreference? }`。 - `agents.defaults.blockStreamingCoalesce`：`{ minChars?, maxChars?, idleMs? }`（在发送前合并流式块）。 - 渠道硬上限：`*.textChunkLimit`（例如 `channels.whatsapp.textChunkLimit`）。 -- 渠道分块模式：`*.chunkMode`（默认 `length`，`newline` 会先按空行即段落边界分块，再按长度分块）。 -- Discord 软上限：`channels.discord.maxLinesPerMessage`（默认 17），会拆分过高的回复以避免 UI 裁切。 +- 渠道分块模式：`*.chunkMode`（默认 `length`，`newline` 会先按空行即段落边界拆分，再按长度分块）。 +- Discord 软上限：`channels.discord.maxLinesPerMessage`（默认 17）会拆分过高的回复，以避免 UI 裁剪。 **边界语义：** -- `text_end`：只要 chunker 发出块就立即流式发送；在每个 `text_end` 时刷新。 +- `text_end`：一旦 chunker 产生块就立即流式发送；在每个 `text_end` 时刷新。 - `message_end`：等待助手消息完成后，再刷新缓冲输出。 -如果缓冲文本超过 `maxChars`，`message_end` 仍会使用 chunker，因此它可能在结尾发出多个块。 +`message_end` 仍然会在缓冲文本超过 `maxChars` 时使用 chunker，因此它可以在结尾发出多个块。 -## 分块算法（低 / 高边界） +## 分块算法（低/高边界） -分块实现由 `EmbeddedBlockChunker` 完成： +分块由 `EmbeddedBlockChunker` 实现： - **低边界：** 在缓冲区达到 `minChars` 之前不发送（除非被强制发送）。 -- **高边界：** 优先在 `maxChars` 之前断开；如被强制，则在 `maxChars` 处断开。 -- **断点偏好：** `paragraph` → `newline` → `sentence` → `whitespace` → 硬断开。 -- **代码围栏：** 绝不会在围栏内断开；如果被迫在 `maxChars` 处断开，则会先关闭再重新打开围栏，以保持 Markdown 有效。 +- **高边界：** 优先在 `maxChars` 之前拆分；如果必须强制拆分，就在 `maxChars` 处拆分。 +- **断点偏好：** `paragraph` → `newline` → `sentence` → `whitespace` → 硬拆分。 +- **代码围栏：** 绝不在围栏内部拆分；如果被迫在 `maxChars` 处拆分，会先关闭再重新打开围栏，以保持 Markdown 有效。 -`maxChars` 会被限制到渠道的 `textChunkLimit`，因此不会超过每个渠道的上限。 +`maxChars` 会被限制到渠道的 `textChunkLimit`，因此你无法超过各渠道的上限。 ## 合并（合并流式块） -启用分块流式传输时，OpenClaw 可以在发送前**合并连续的分块内容**。这样可以减少“单行刷屏”，同时仍然提供渐进式输出。 +启用分块流式传输时，OpenClaw 可以在发送前**合并连续的分块**。 +这样既能提供渐进式输出，又能减少“单行刷屏”。 - 合并会等待**空闲间隔**（`idleMs`）后再刷新。 -- 缓冲区受 `maxChars` 限制，超出时会立即刷新。 -- `minChars` 会阻止过小片段在文本积累到足够长度前发送 - （最终刷新总会发送剩余文本）。 +- 缓冲区受 `maxChars` 限制，超过时会刷新。 +- `minChars` 会阻止过小的片段被提前发送，直到积累足够文本 + （最终刷新始终会发送剩余文本）。 - 连接符由 `blockStreamingChunk.breakPreference` 决定（`paragraph` → `\n\n`，`newline` → `\n`，`sentence` → 空格）。 -- 可通过 `*.blockStreamingCoalesce` 进行渠道级覆盖（包括按账户配置）。 -- 除非显式覆盖，否则 Signal / Slack / Discord 的默认合并 `minChars` 会提高到 1500。 +- 可通过 `*.blockStreamingCoalesce` 进行渠道级覆盖（包括每账号配置）。 +- 对于 Signal/Slack/Discord，默认合并 `minChars` 会提升到 1500，除非被覆盖。 -## 分块之间更像人类的节奏 +## 块之间的类人节奏 -启用分块流式传输时，你可以在分块回复之间添加**随机暂停**（首个块之后）。这样会让多气泡回复显得更自然。 +启用分块流式传输时，你可以在分块回复之间加入**随机暂停** +（第一个块之后）。这会让多气泡回复显得更自然。 - 配置：`agents.defaults.humanDelay`（可通过 `agents.list[].humanDelay` 按智能体覆盖）。 -- 模式：`off`（默认）、`natural`（800–2500 毫秒）、`custom`（`minMs` / `maxMs`）。 +- 模式：`off`（默认）、`natural`（800–2500ms）、`custom`（`minMs`/`maxMs`）。 - 仅适用于**分块回复**，不适用于最终回复或工具摘要。 -## “流式发送分块还是最后一次性发送” +## “流式发送分块，还是一次性全部发送” -其映射关系如下： +它对应为： -- **流式发送分块：** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"`（边生成边发送）。非 Telegram 渠道还需要将 `*.blockStreaming` 设置为 `true`。 -- **最后一次性发送全部内容：** `blockStreamingBreak: "message_end"`（一次刷新，如果很长，可能仍分成多个块）。 +- **流式发送分块：** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"`（边生成边发送）。非 Telegram 渠道还需要将 `*.blockStreaming` 设为 `true`。 +- **在结尾一次性发送全部内容：** `blockStreamingBreak: "message_end"`（刷新一次；如果内容很长，可能仍会拆成多个块）。 - **不使用分块流式传输：** `blockStreamingDefault: "off"`（只发送最终回复）。 -**渠道说明：** 除非 -显式将 `*.blockStreaming` 设为 `true`，否则分块流式传输**处于关闭状态**。渠道可以在没有分块回复的情况下使用实时预览流式传输（`channels..streaming`）。 +**渠道说明：** 除非显式将 +`*.blockStreaming` 设为 `true`，否则分块流式传输**默认关闭**。渠道仍然可以启用实时预览 +（`channels..streaming`），而不发送分块回复。 配置位置提醒：`blockStreaming*` 默认值位于 -`agents.defaults` 下，而不是根配置。 +`agents.defaults` 下，而不是根配置下。 ## 预览流式传输模式 @@ -114,50 +117,51 @@ OpenClaw 有两个彼此独立的流式传输层： 模式： - `off`：禁用预览流式传输。 -- `partial`：单个预览，始终替换为最新文本。 -- `block`：以分块 / 追加方式更新预览。 -- `progress`：在生成过程中显示进度 / 状态预览，完成时再发送最终答案。 +- `partial`：使用单个预览，并用最新文本替换。 +- `block`：以分块/追加的方式更新预览。 +- `progress`：在生成期间显示进度/状态预览，完成后给出最终答案。 ### 渠道映射 -| 渠道 | `off` | `partial` | `block` | `progress` | -| --------- | ----- | --------- | ------- | ----------------- | -| Telegram | ✅ | ✅ | ✅ | 映射为 `partial` | -| Discord | ✅ | ✅ | ✅ | 映射为 `partial` | -| Slack | ✅ | ✅ | ✅ | ✅ | +| 渠道 | `off` | `partial` | `block` | `progress` | +| ---- | ----- | --------- | ------- | ---------- | +| Telegram | ✅ | ✅ | ✅ | 映射为 `partial` | +| Discord | ✅ | ✅ | ✅ | 映射为 `partial` | +| Slack | ✅ | ✅ | ✅ | ✅ | -仅适用于 Slack： +仅限 Slack： -- `channels.slack.nativeStreaming` 会在 `streaming=partial` 时切换 Slack 原生流式 API 调用（默认：`true`）。 +- `channels.slack.streaming.nativeTransport` 在 `channels.slack.streaming.mode="partial"` 时切换 Slack 原生流式 API 调用（默认：`true`）。 +- Slack 原生流式传输和 Slack 助手线程状态都需要回复线程目标；顶层私信不会显示这种线程式预览。 -旧版键迁移： +旧键迁移： -- Telegram：`streamMode` + 布尔值 `streaming` 会自动迁移到枚举 `streaming`。 -- Discord：`streamMode` + 布尔值 `streaming` 会自动迁移到枚举 `streaming`。 -- Slack：`streamMode` 会自动迁移到枚举 `streaming`；布尔值 `streaming` 会自动迁移到 `nativeStreaming`。 +- Telegram：`streamMode` 和布尔值 `streaming` 会自动迁移到枚举 `streaming`。 +- Discord：`streamMode` 和布尔值 `streaming` 会自动迁移到枚举 `streaming`。 +- Slack：`streamMode` 会自动迁移到 `streaming.mode`；布尔值 `streaming` 会自动迁移到 `streaming.mode` 加 `streaming.nativeTransport`；旧版 `nativeStreaming` 会自动迁移到 `streaming.nativeTransport`。 ### 运行时行为 Telegram： -- 在私信和群组 / 主题中使用 `sendMessage` + `editMessageText` 更新预览。 -- 当 Telegram 的分块流式传输被显式启用时，会跳过预览流式传输（以避免双重流式传输）。 +- 在私信和群组/话题中使用 `sendMessage` + `editMessageText` 更新预览。 +- 当 Telegram 分块流式传输被显式启用时，会跳过预览流式传输（以避免双重流式传输）。 - `/reasoning stream` 可以将 reasoning 写入预览。 Discord： - 使用发送 + 编辑预览消息。 - `block` 模式使用草稿分块（`draftChunk`）。 -- 当 Discord 的分块流式传输被显式启用时，会跳过预览流式传输。 +- 当 Discord 分块流式传输被显式启用时，会跳过预览流式传输。 Slack： -- `partial` 在可用时可使用 Slack 原生流式传输（`chat.startStream` / `append` / `stop`）。 +- `partial` 在可用时可以使用 Slack 原生流式传输（`chat.startStream`/`append`/`stop`）。 - `block` 使用追加式草稿预览。 -- `progress` 使用状态预览文本，完成后再发送最终答案。 +- `progress` 使用状态预览文本，然后发送最终答案。 ## 相关内容 -- [消息](/concepts/messages) —— 消息生命周期和传递 -- [重试](/concepts/retry) —— 传递失败时的重试行为 -- [渠道](/channels) —— 每个渠道的流式传输支持 +- [消息](/zh-CN/concepts/messages) — 消息生命周期和投递 +- [重试](/zh-CN/concepts/retry) — 投递失败时的重试行为 +- [渠道](/zh-CN/channels) — 各渠道的流式传输支持 diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index 46179da11..0f88169f8 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -2,55 +2,69 @@ read_when: - 你需要精确到字段级别的配置语义或默认值 - 你正在验证渠道、模型、Gateway 网关或工具配置块 -summary: 每个 OpenClaw 配置键、默认值和渠道设置的完整参考 +summary: 用于核心 OpenClaw 键、默认值以及专用子系统参考链接的 Gateway 网关配置参考 title: 配置参考 x-i18n: - generated_at: "2026-04-08T03:52:03Z" + generated_at: "2026-04-08T05:05:04Z" model: gpt-5.4 provider: openai - source_hash: a22899b8f43a7819a2e27fae1bddbe67b29b314bce5a9844fc276482bda9156c + source_hash: 2f9ab34fb56897a77cb038d95bea21e8530d8f0402b66d1ee97c73822a1e8fd4 source_path: gateway/configuration-reference.md workflow: 15 --- # 配置参考 -`~/.openclaw/openclaw.json` 中可用的每个字段。若需面向任务的概览，请参阅 [Configuration](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 的核心配置参考。若需按任务组织的概览，请参见 [配置](/zh-CN/gateway/configuration)。 -配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的——省略时，OpenClaw 会使用安全的默认值。 +本页面涵盖主要的 OpenClaw 配置面，并在某个子系统拥有更深入的独立参考时提供链接。它**不会**尝试在单个页面内联每一个由渠道/插件拥有的命令目录，或每一个深层 memory/QMD 调节项。 + +代码事实依据： + +- `openclaw config schema` 会打印用于校验和 Control UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据 +- `config.schema.lookup` 返回一个按路径限定的 schema 节点，供下钻工具使用 +- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面校验配置文档基线哈希 + +专用深度参考： + +- [Memory 配置参考](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置 +- [Slash Commands](/zh-CN/tools/slash-commands)，查看当前内置 + 内置插件命令目录 +- 各自所属的渠道/插件页面，查看渠道特定命令面 + +配置格式是 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的——OpenClaw 在省略时会使用安全默认值。 --- ## 渠道 -每个渠道只要存在对应的配置段，就会自动启动（除非设置了 `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`（默认拒绝），并在启动时发出警告。 +`channels.defaults.groupPolicy` 会在某个提供商的 `groupPolicy` 未设置时作为默认值。 +配对码会在 1 小时后过期。待处理的私信配对请求每个渠道上限为 **3 个**。 +如果某个提供商配置块完全缺失（`channels.` 不存在），运行时群组策略会回退为 `allowlist`（故障时默认关闭），并在启动时发出警告。 ### 渠道模型覆盖 -使用 `channels.modelByChannel` 可将特定渠道 ID 固定到某个模型。值可接受 `provider/model` 或已配置的模型别名。当会话尚未有模型覆盖时（例如通过 `/model` 设置），就会应用渠道映射。 +使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值可接受 `provider/model` 或已配置的模型别名。当某个会话尚未拥有模型覆盖时（例如通过 `/model` 设置），才会应用该渠道映射。 ```json5 { @@ -73,7 +87,7 @@ x-i18n: ### 渠道默认值和心跳 -使用 `channels.defaults` 为各提供商设置共享的群组策略和心跳行为： +使用 `channels.defaults` 为各个提供商设置共享的群组策略和心跳行为： ```json5 { @@ -91,15 +105,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`：当提供商级 `groupPolicy` 未设置时的回退群组策略。 -- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。可选值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。按渠道覆盖：`channels..contextVisibility`。 -- `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康渠道状态。 +- `channels.defaults.groupPolicy`：当提供商级别的 `groupPolicy` 未设置时的回退群组策略。 +- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。按渠道覆盖：`channels..contextVisibility`。 +- `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康的渠道状态。 - `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级/错误状态。 -- `channels.defaults.heartbeat.useIndicator`：以紧凑的指示器样式渲染心跳输出。 +- `channels.defaults.heartbeat.useIndicator`：渲染紧凑的指示器样式心跳输出。 ### WhatsApp -WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已关联会话时会自动启动。 +WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在已关联会话时会自动启动。 ```json5 { @@ -150,8 +164,8 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- 出站命令默认使用 `default` 账号（如果存在）；否则使用第一个已配置的账号 ID（排序后）。 -- 可选的 `channels.whatsapp.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖该回退默认账号选择。 +- 出站命令默认使用 `default` 账号（如果存在）；否则使用第一个已配置的账号 ID（已排序）。 +- 可选的 `channels.whatsapp.defaultAccount` 会在它与已配置账号 ID 匹配时覆盖这一回退默认账号选择。 - 旧版单账号 Baileys 凭证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 - 按账号覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -211,13 +225,13 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅允许普通文件；拒绝符号链接），默认账号还可回退到 `TELEGRAM_BOT_TOKEN`。 -- 可选的 `channels.telegram.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 在多账号设置（2 个及以上账号 ID）中，请设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`），以避免回退路由；缺失或无效时，`openclaw doctor` 会发出警告。 -- `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`（可在私聊和群聊中工作）。 -- 重试策略：参见 [Retry policy](/zh-CN/concepts/retry)。 +- 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 发起的配置写入（supergroup ID 迁移、`/config set|unset`）。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目用于为论坛话题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义与 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 共用。 +- Telegram 流式预览使用 `sendMessage` + `editMessageText`（在私聊和群聊中都可用）。 +- 重试策略：参见 [重试策略](/zh-CN/concepts/retry)。 ### Discord @@ -319,36 +333,36 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- 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。 +- Token：`channels.discord.token`，默认账号可回退到 `DISCORD_BOT_TOKEN`。 +- 提供显式 Discord `token` 的直接出站调用会使用该 token；账号重试/策略设置仍然来自当前运行时快照中选定的账号。 +- 可选的 `channels.discord.defaultAccount` 会在它与已配置账号 ID 匹配时覆盖默认账号选择。 +- 使用 `user:`（私信）或 `channel:`（guild 渠道）作为投递目标；裸数字 ID 会被拒绝。 +- Guild slug 使用小写并将空格替换为 `-`；渠道键使用 slug 化名称（不含 `#`）。优先使用 guild ID。 +- 默认会忽略 Bot 自己撰写的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 可仅接受提及该 Bot 的机器人消息（仍会过滤自身消息）。 +- `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) 共享。 -- `channels.discord.ui.components.accentColor` 用于设置 Discord components v2 容器的强调色。 -- `channels.discord.voice` 启用 Discord 语音频道对话，以及可选的自动加入和 TTS 覆盖。 + - `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) 共用。 +- `channels.discord.ui.components.accentColor` 设置 Discord components v2 容器的强调色。 +- `channels.discord.voice` 启用 Discord 语音频道对话以及可选的自动加入 + TTS 覆盖。 - `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会透传给 `@discordjs/voice` 的 DAVE 选项（默认分别为 `true` 和 `24`）。 -- OpenClaw 还会在反复发生解密失败后，尝试通过离开/重新加入语音会话来恢复语音接收。 +- 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 审批。 - - `approvers`：允许审批 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。 +- `channels.discord.autoPresence` 将运行时可用性映射为 Bot 在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。 +- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/tag 匹配（紧急兼容模式）。 +- `channels.discord.execApprovals`：Discord 原生 exec 审批投递和审批者授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在 auto 模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批者时，exec 审批会激活。 + - `approvers`：允许批准 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。 - `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 @@ -382,8 +396,8 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 - 服务账号 JSON：内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 - 也支持服务账号 SecretRef（`serviceAccountRef`）。 - 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 -- 对投递目标请使用 `spaces/` 或 `users/`。 -- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（紧急兼容模式）。 +- 使用 `spaces/` 或 `users/` 作为投递目标。 +- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变邮箱主体匹配（紧急兼容模式）。 ### Slack @@ -433,8 +447,10 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 typingReaction: "hourglass_flowing_sand", textChunkLimit: 4000, chunkMode: "length", - streaming: "partial", // off | partial | block | progress (preview mode) - nativeStreaming: true, // use Slack native streaming API when streaming=partial + streaming: { + mode: "partial", // off | partial | block | progress + nativeTransport: true, // use Slack native streaming API when mode=partial + }, mediaMaxMb: 20, execApprovals: { enabled: "auto", // true | false | "auto" @@ -448,38 +464,39 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号的环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 -- **HTTP mode** 需要 `botToken` 加 `signingSecret`（可位于根级或按账号配置）。 +- **Socket mode** 需要同时设置 `botToken` 和 `appToken`（默认账号环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 +- **HTTP mode** 需要 `botToken` 加 `signingSecret`（位于根级或按账号设置）。 - `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文 字符串或 SecretRef 对象。 -- Slack 账号快照会暴露每个凭证的来源/状态字段，例如 - `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP mode 下的 +- Slack 账号快照会公开每项凭证的来源/状态字段，例如 + `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP mode 中的 `signingSecretStatus`。`configured_unavailable` 表示该账号 - 通过 SecretRef 配置，但当前命令/运行时路径无法 + 通过 SecretRef 进行了配置，但当前命令/运行时路径无法 解析该 secret 值。 - `configWrites: false` 会阻止由 Slack 发起的配置写入。 -- 可选的 `channels.slack.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- `channels.slack.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔型 `streaming` 值会自动迁移。 -- 对投递目标请使用 `user:`（私信）或 `channel:`。 +- 可选的 `channels.slack.defaultAccount` 会在它与已配置账号 ID 匹配时覆盖默认账号选择。 +- `channels.slack.streaming.mode` 是规范的 Slack 流式模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输。旧版 `streamMode`、布尔型 `streaming` 和 `nativeStreaming` 值会自动迁移。 +- 使用 `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"`）。 +- Slack 原生流式传输以及 Slack 助手样式的“正在输入...”线程状态都需要回复线程目标。顶层私信默认保持在线程外，因此它们会使用 `typingReaction` 或普通投递，而不是线程样式预览。 +- `typingReaction` 会在回复运行期间向传入的 Slack 消息添加一个临时反应，并在完成时移除。使用 Slack emoji shortcode，例如 `"hourglass_flowing_sand"`。 +- `channels.slack.execApprovals`：Slack 原生 exec 审批投递和审批者授权。模式与 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 -Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost`。 +Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermost`。 ```json5 { @@ -509,21 +526,21 @@ 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 服务器可以访问到。 -- 原生 slash 回调通过 Mattermost 在 slash 命令注册期间返回的每命令 token 进行认证。如果注册失败或没有命令被激活，OpenClaw 会拒绝回调，并返回 +- `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），而不是完整 URL。 +- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器可访问。 +- 原生 slash 回调使用 Mattermost 在注册 slash 命令时返回的每命令 token 进行认证。如果注册失败或没有激活任何命令，OpenClaw 会拒绝回调并返回 `Unauthorized: invalid command token.`。 -- 对于 private/tailnet/internal 回调主机，Mattermost 可能要求 - `ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机/域名。 - 请使用主机/域名值，而不是完整 URL。 +- 对于私有/tailnet/internal 回调主机，Mattermost 可能要求 + `ServiceSettings.AllowedUntrustedInternalConnections` 包含该回调主机/域名。 + 使用主机/域名值，而不是完整 URL。 - `channels.mattermost.configWrites`：允许或拒绝由 Mattermost 发起的配置写入。 -- `channels.mattermost.requireMention`：在频道中回复前要求 `@mention`。 -- `channels.mattermost.groups..requireMention`：按频道的提及门控覆盖（`"*"` 表示默认值）。 -- 可选的 `channels.mattermost.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 +- `channels.mattermost.requireMention`：在渠道中回复前要求 `@mention`。 +- `channels.mattermost.groups..requireMention`：按渠道的提及门控覆盖（`"*"` 为默认值）。 +- 可选的 `channels.mattermost.defaultAccount` 会在它与已配置账号 ID 匹配时覆盖默认账号选择。 ### Signal @@ -546,13 +563,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 { @@ -567,14 +584,14 @@ BlueBubbles 是推荐的 iMessage 路径（插件支持，在 `channels.bluebubb } ``` -- 这里涵盖的核心键路径：`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`、`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)。 ### iMessage -OpenClaw 会启动 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护进程或端口。 +OpenClaw 会生成 `imsg rpc`（通过 stdio 的 JSON-RPC）。无需守护进程或端口。 ```json5 { @@ -598,15 +615,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 DB 的完全磁盘访问权限。 +- 优先使用 `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)。 @@ -619,7 +636,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix 由扩展支持，在 `channels.matrix` 下配置。 +Matrix 由扩展支持，配置位于 `channels.matrix` 下。 ```json5 { @@ -650,24 +667,24 @@ Matrix 由扩展支持，在 `channels.matrix` 下配置。 ``` - Token 认证使用 `accessToken`；密码认证使用 `userId` + `password`。 -- `channels.matrix.proxy` 会通过显式 HTTP(S) 代理转发 Matrix HTTP 流量。命名账号可通过 `channels.matrix.accounts..proxy` 覆盖。 -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许 private/internal homeserver。`proxy` 与该网络显式启用项是独立控制项。 -- `channels.matrix.defaultAccount` 在多账号设置中选择首选账号。 -- `channels.matrix.autoJoin` 默认值为 `off`，因此邀请房间和新的私信风格邀请会被忽略，直到你设置 `autoJoin: "allowlist"` 并配合 `autoJoinAllowlist`，或设置 `autoJoin: "always"`。 -- `channels.matrix.execApprovals`：Matrix 原生 exec 审批投递和审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，会激活 exec 审批。 - - `approvers`：允许审批 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。 +- `channels.matrix.proxy` 会将 Matrix HTTP 流量路由到显式的 HTTP(S) 代理。命名账号可通过 `channels.matrix.accounts..proxy` 覆盖它。 +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有/internal homeserver。`proxy` 和这个网络启用项是相互独立的控制项。 +- `channels.matrix.defaultAccount` 会在多账号设置中选择首选账号。 +- `channels.matrix.autoJoin` 默认值为 `off`，因此受邀房间和新的私信式邀请会被忽略，直到你设置 `autoJoin: "allowlist"` 并配合 `autoJoinAllowlist`，或设置 `autoJoin: "always"`。 +- `channels.matrix.execApprovals`：Matrix 原生 exec 审批投递和审批者授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在 auto 模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批者时，exec 审批会激活。 + - `approvers`：允许批准 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。 - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。 - `sessionFilter`：可选的会话键模式（子串或正则）。 - - `target`：审批提示发送位置。`"dm"`（默认）、`"channel"`（来源房间）或 `"both"`。 + - `target`：将审批提示发送到哪里。`"dm"`（默认）、`"channel"`（源房间）或 `"both"`。 - 按账号覆盖：`channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何分组为会话：`per-user`（默认）按路由对端共享，而 `per-room` 会隔离每个私信房间。 -- Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。 -- 完整的 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 { @@ -682,12 +699,12 @@ Microsoft Teams 由扩展支持，在 `channels.msteams` 下配置。 } ``` -- 这里涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。 -- 完整的 Teams 配置（凭证、webhook、私信/群组策略、按团队/按频道覆盖）记录在 [Microsoft Teams](/zh-CN/channels/msteams) 中。 +- 此处涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。 +- 完整的 Teams 配置（凭证、webhook、私信/群组策略、按团队/按渠道覆盖）见 [Microsoft Teams](/zh-CN/channels/msteams)。 ### IRC -IRC 由扩展支持，在 `channels.irc` 下配置。 +IRC 由扩展支持，配置位于 `channels.irc`。 ```json5 { @@ -708,13 +725,13 @@ 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`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 +- 可选的 `channels.irc.defaultAccount` 会在它与已配置账号 ID 匹配时覆盖默认账号选择。 +- 完整的 IRC 渠道配置（host/port/TLS/channels/allowlists/mention gating）见 [IRC](/zh-CN/channels/irc)。 ### 多账号（所有渠道） -为同一渠道运行多个账号（每个账号都有自己的 `accountId`）： +为每个渠道运行多个账号（每个账号都有自己的 `accountId`）： ```json5 { @@ -735,28 +752,28 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 } ``` -- 省略 `accountId` 时使用 `default`（CLI + 路由）。 -- 环境变量 token 仅适用于**默认**账号。 -- 基础渠道设置适用于所有账号，除非被账号级覆盖。 -- 使用 `bindings[].match.accountId` 将每个账号路由到不同智能体。 -- 如果你通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，而当前仍使用单账号顶层渠道配置，OpenClaw 会先把账号范围的顶层单账号值提升到该渠道的账号映射中，以确保原账号继续工作。大多数渠道会将其移动到 `channels..accounts.default`；Matrix 则可能保留现有匹配的命名/default 目标。 -- 现有仅渠道级的绑定（无 `accountId`）仍会匹配默认账号；账号级绑定仍是可选的。 -- `openclaw doctor --fix` 也会修复混合形态：将账号范围的顶层单账号值移动到该渠道所选的提升账号中。大多数渠道使用 `accounts.default`；Matrix 则可能保留现有匹配的命名/default 目标。 +- 当省略 `accountId` 时，使用 `default`（CLI + 路由）。 +- 环境变量 token 只适用于 **default** 账号。 +- 基础渠道设置会应用到所有账号，除非按账号覆盖。 +- 使用 `bindings[].match.accountId` 将各账号路由到不同智能体。 +- 如果你通过 `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）。 +查看完整渠道索引：[渠道](/zh-CN/channels)。 ### 群聊提及门控 -群组消息默认**要求提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 +群组消息默认 **要求提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 **提及类型：** -- **元数据提及**：平台原生 @ 提及。在 WhatsApp 自聊模式下会被忽略。 -- **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 -- 仅在可以进行检测时（原生提及或至少一个模式）才会强制执行提及门控。 +- **元数据提及**：原生平台 @ 提及。在 WhatsApp 自聊模式中会忽略。 +- **文本模式**：`agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 +- 只有在可以检测提及时（原生提及或至少一个模式）才会强制执行提及门控。 ```json5 { @@ -769,7 +786,7 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 } ``` -`messages.groupChat.historyLimit` 设置全局默认值。渠道可通过 `channels..historyLimit`（或按账号）覆盖。设为 `0` 可禁用。 +`messages.groupChat.historyLimit` 设置全局默认值。渠道可以通过 `channels..historyLimit`（或按账号）覆盖。设置为 `0` 可禁用。 #### 私信历史限制 @@ -786,13 +803,13 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 } ``` -解析顺序：按私信覆盖 → 提供商默认值 → 无限制（全部保留）。 +解析顺序：按私信覆盖 → 提供商默认值 → 不限制（全部保留）。 支持：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 #### 自聊模式 -将你自己的号码包含在 `allowFrom` 中即可启用自聊模式（忽略原生 @ 提及，仅响应文本模式）： +将你自己的号码加入 `allowFrom` 可启用自聊模式（忽略原生 @ 提及，只响应文本模式）： ```json5 { @@ -819,12 +836,18 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 { commands: { native: "auto", // register native commands when supported + nativeSkills: "auto", // register native skill commands when supported text: true, // parse /commands in chat messages bash: false, // allow ! (alias: /bash) bashForegroundMs: 2000, config: false, // allow /config + mcp: false, // allow /mcp + plugins: false, // allow /plugins debug: false, // allow /debug - restart: false, // allow /restart + gateway restart tool + restart: true, // allow /restart + gateway restart tool + ownerAllowFrom: ["discord:123456789012345678"], + ownerDisplay: "raw", // raw | hash + ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", allowFrom: { "*": ["user1"], discord: ["user:123"], @@ -836,16 +859,32 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 -- 文本命令必须是**独立**消息，并以 `/` 开头。 -- `native: "auto"` 会为 Discord/Telegram 开启原生命令，而让 Slack 保持关闭。 +- 该块配置命令面。当前内置 + 内置插件命令目录见 [Slash Commands](/zh-CN/tools/slash-commands)。 +- 本页是**配置键参考**，不是完整命令目录。由渠道/插件拥有的命令，如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、device-pair `/pair`、memory `/dreaming`、phone-control `/phone` 和 Talk `/voice`，记录在各自渠道/插件页面以及 [Slash Commands](/zh-CN/tools/slash-commands) 中。 +- 文本命令必须是以 `/` 开头的**独立**消息。 +- `native: "auto"` 会为 Discord/Telegram 打开原生命令，而 Slack 保持关闭。 +- `nativeSkills: "auto"` 会为 Discord/Telegram 打开原生 skill 命令，而 Slack 保持关闭。 - 可按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除先前注册的命令。 -- `channels.telegram.customCommands` 可添加额外的 Telegram 机器人菜单项。 -- `bash: true` 启用主机 shell 的 `! `（别名：`/bash`）。需要 `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..commands.nativeSkills` 覆盖按渠道的原生 skill 注册。 +- `channels.telegram.customCommands` 会添加额外的 Telegram 机器人菜单项。 +- `bash: true` 为主机 shell 启用 `! `。要求 `tools.elevated.enabled`，并且发送者在 `tools.elevated.allowFrom.` 中。 +- `config: true` 启用 `/config`（读取/写入 `openclaw.json`）。对于 gateway `chat.send` 客户端，持久的 `/config set|unset` 写入还要求 `operator.admin`；只读的 `/config show` 对普通具有写权限的 operator 客户端仍可用。 +- `mcp: true` 为 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置启用 `/mcp`。 +- `plugins: true` 为插件发现、安装以及启用/禁用控制启用 `/plugins`。 +- `channels..configWrites` 控制每个渠道的配置变更（默认：true）。 - 对于多账号渠道，`channels..accounts..configWrites` 也会控制针对该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 -- `allowFrom` 按提供商生效。设置后，它将成为**唯一**的授权来源（渠道允许列表/配对和 `useAccessGroups` 都会被忽略）。 -- `useAccessGroups: false` 允许命令在未设置 `allowFrom` 时绕过访问组策略。 +- `restart: false` 会禁用 `/restart` 和 Gateway 网关重启工具动作。默认值：`true`。 +- `ownerAllowFrom` 是仅限所有者命令/工具的显式所有者允许列表。它与 `allowFrom` 分离。 +- `ownerDisplay: "hash"` 会在系统提示中哈希所有者 ID。设置 `ownerDisplaySecret` 以控制哈希。 +- `allowFrom` 是按提供商设置的。设置后，它会成为**唯一**授权来源（渠道允许列表/配对以及 `useAccessGroups` 都会被忽略）。 +- `useAccessGroups: false` 允许在未设置 `allowFrom` 时让命令绕过访问组策略。 +- 命令文档映射： + - 内置 + 内置插件目录：[Slash Commands](/zh-CN/tools/slash-commands) + - 渠道特定命令面：[渠道](/zh-CN/channels) + - QQ Bot 命令：[QQ Bot](/zh-CN/channels/qqbot) + - 配对命令：[配对](/zh-CN/channels/pairing) + - LINE card 命令：[LINE](/zh-CN/channels/line) + - memory dreaming：[Dreaming](/zh-CN/concepts/dreaming) @@ -865,7 +904,7 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 ### `agents.defaults.repoRoot` -可选的仓库根目录，会显示在系统提示词的 Runtime 行中。若未设置，OpenClaw 会从工作区向上遍历自动检测。 +可选的仓库根目录，会显示在系统提示的 Runtime 行中。若未设置，OpenClaw 会从工作区向上遍历自动检测。 ```json5 { @@ -875,7 +914,7 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 ### `agents.defaults.skills` -对未设置 `agents.list[].skills` 的智能体生效的可选默认 Skills 允许列表。 +为未设置 `agents.list[].skills` 的智能体提供可选的默认 Skills 允许列表。 ```json5 { @@ -890,15 +929,15 @@ 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` -禁用自动创建工作区 bootstrap 文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 +禁用工作区 bootstrap 文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）的自动创建。 ```json5 { @@ -908,9 +947,9 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 ### `agents.defaults.contextInjection` -控制何时将工作区 bootstrap 文件注入到系统提示词中。默认值：`"always"`。 +控制何时将工作区 bootstrap 文件注入系统提示。默认值：`"always"`。 -- `"continuation-skip"`：安全续写轮次（在 assistant 完成回复之后）会跳过工作区 bootstrap 的重新注入，从而减少提示词大小。心跳运行和压缩后的重试仍会重建上下文。 +- `"continuation-skip"`：安全续写回合（在一次已完成的助手响应之后）会跳过重新注入工作区 bootstrap，从而减小提示大小。心跳运行和压缩后的重试仍会重建上下文。 ```json5 { @@ -920,7 +959,7 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 ### `agents.defaults.bootstrapMaxChars` -工作区 bootstrap 文件在截断前的最大字符数。默认值：`20000`。 +每个工作区 bootstrap 文件在截断前允许的最大字符数。默认值：`20000`。 ```json5 { @@ -930,7 +969,7 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 ### `agents.defaults.bootstrapTotalMaxChars` -所有工作区 bootstrap 文件注入总字符数上限。默认值：`150000`。 +在所有工作区 bootstrap 文件之间注入的总最大字符数。默认值：`150000`。 ```json5 { @@ -943,9 +982,9 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 控制 bootstrap 上下文被截断时，对智能体可见的警告文本。 默认值：`"once"`。 -- `"off"`：绝不在系统提示词中注入警告文本。 -- `"once"`：对每个唯一的截断签名仅注入一次警告（推荐）。 -- `"always"`：只要存在截断，就在每次运行时注入警告。 +- `"off"`：绝不向系统提示注入警告文本。 +- `"once"`：每个唯一的截断签名仅注入一次警告（推荐）。 +- `"always"`：只要存在截断，每次运行都注入警告。 ```json5 { @@ -955,11 +994,11 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 ### `agents.defaults.imageMaxDimensionPx` -在调用提供商之前，转录/工具图像块中图像最长边的最大像素尺寸。 +在进行 provider 调用之前，转录/工具图像块中图像最长边允许的最大像素尺寸。 默认值：`1200`。 -较低的值通常会减少视觉 token 使用量以及请求负载大小，适合截图较多的运行。 -较高的值则可保留更多视觉细节。 +较低的值通常会减少视觉 token 使用量和截图密集型运行的请求负载大小。 +较高的值则会保留更多视觉细节。 ```json5 { @@ -969,7 +1008,7 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 ### `agents.defaults.userTimezone` -系统提示词上下文使用的时区（不影响消息时间戳）。会回退到主机时区。 +用于系统提示上下文的时区（不影响消息时间戳）。会回退到主机时区。 ```json5 { @@ -979,7 +1018,7 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 ### `agents.defaults.timeFormat` -系统提示词中的时间格式。默认值：`auto`（操作系统偏好）。 +系统提示中的时间格式。默认值：`auto`（OS 偏好）。 ```json5 { @@ -1032,43 +1071,43 @@ 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）。 - - 如果你直接选择某个 provider/model，也请配置相应的提供商认证/API key（例如 `google/*` 需要 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 需要 `OPENAI_API_KEY`，`fal/*` 需要 `FAL_KEY`）。 - - 若省略，`image_generate` 仍可推断出一个已认证提供商默认值。它会先尝试当前默认提供商，再按提供商 ID 顺序尝试其余已注册图像生成提供商。 -- `musicGenerationModel`：既可接受字符串（`"provider/model"`），也可接受对象（`{ primary, fallbacks }`）。 - - 用于共享的音乐生成能力和内置 `music_generate` 工具。 - - 常见值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。 - - 若省略，`music_generate` 仍可推断出一个已认证提供商默认值。它会先尝试当前默认提供商，再按提供商 ID 顺序尝试其余已注册音乐生成提供商。 - - 如果你直接选择某个 provider/model，也请配置相应的提供商认证/API key。 -- `videoGenerationModel`：既可接受字符串（`"provider/model"`），也可接受对象（`{ primary, fallbacks }`）。 - - 用于共享的视频生成能力和内置 `video_generate` 工具。 - - 常见值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。 - - 若省略，`video_generate` 仍可推断出一个已认证提供商默认值。它会先尝试当前默认提供商，再按提供商 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`）。如果省略 provider，OpenClaw 会先尝试别名，再尝试与该精确 model id 唯一匹配的已配置 provider，最后才回退到已配置默认 provider（这是已弃用的兼容行为，因此建议显式使用 `provider/model`）。如果该 provider 不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置 provider/model，而不是继续使用陈旧的已移除 provider 默认值。 -- `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` 以及 fallback add/remove 命令）会保存为规范对象形式，并在可能时保留现有回退列表。 -- `maxConcurrent`：跨会话并行智能体运行的最大数量（每个会话内部仍串行）。默认值：4。 +- `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 字符串形式只设置主模型。 + - 对象形式设置主模型以及有序故障转移模型。 +- `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 由 `image` 工具路径用作其视觉模型配置。 + - 当选定/默认模型无法接受图像输入时，也用作回退路由。 +- `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 由共享图像生成功能以及任何未来生成图像的工具/插件面使用。 + - 典型值：用于原生 Gemini 图像生成的 `google/gemini-3.1-flash-image-preview`、用于 fal 的 `fal/fal-ai/flux/dev`，或用于 OpenAI Images 的 `openai/gpt-image-1`。 + - 如果你直接选择某个 provider/model，也要配置匹配的 provider 认证/API key（例如 `google/*` 的 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 的 `OPENAI_API_KEY`，`fal/*` 的 `FAL_KEY`）。 + - 如果省略，`image_generate` 仍然可以推断一个有认证支持的 provider 默认值。它会先尝试当前默认 provider，然后按 provider ID 顺序尝试其余已注册的图像生成 provider。 +- `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 由共享音乐生成功能和内置 `music_generate` 工具使用。 + - 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。 + - 如果省略，`music_generate` 仍然可以推断一个有认证支持的 provider 默认值。它会先尝试当前默认 provider，然后按 provider ID 顺序尝试其余已注册的音乐生成 provider。 + - 如果你直接选择某个 provider/model，也要配置匹配的 provider 认证/API key。 +- `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 由共享视频生成功能和内置 `video_generate` 工具使用。 + - 典型值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。 + - 如果省略，`video_generate` 仍然可以推断一个有认证支持的 provider 默认值。它会先尝试当前默认 provider，然后按 provider ID 顺序尝试其余已注册的视频生成 provider。 + - 如果你直接选择某个 provider/model，也要配置匹配的 provider 认证/API key。 + - 内置的 Qwen 视频生成 provider 当前最多支持 1 个输出视频、1 张输入图片、4 个输入视频、10 秒时长，以及 provider 级的 `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`）。如果省略 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` 中时生效）： +**内置别名简写**（仅当模型存在于 `agents.defaults.models` 中时适用）： | 别名 | 模型 | | ------------------- | -------------------------------------- | @@ -1081,15 +1120,15 @@ IRC 由扩展支持，在 `channels.irc` 下配置。 | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -你自己配置的别名始终优先于默认值。 +你配置的别名始终优先于默认值。 -Z.AI GLM-4.x 模型会自动启用 thinking mode，除非你设置 `--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 level 时，默认使用 `adaptive` thinking。 +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。 ### `agents.defaults.cliBackends` -用于纯文本回退运行（无工具调用）的可选 CLI 后端。当 API 提供商失败时，这可作为备份。 +为纯文本回退运行（无工具调用）提供可选的 CLI 后端。当 API provider 失败时可作为备份。 ```json5 { @@ -1117,9 +1156,9 @@ Anthropic Claude 4.6 模型在未设置显式 thinking level 时，默认使用 } ``` -- CLI 后端以文本为主；工具始终禁用。 +- CLI 后端是文本优先的；工具始终被禁用。 - 设置了 `sessionArg` 时支持会话。 -- 当 `imageArg` 接受文件路径时支持图像透传。 +- 当 `imageArg` 接受文件路径时，支持图像透传。 ### `agents.defaults.heartbeat` @@ -1151,10 +1190,10 @@ Anthropic Claude 4.6 模型在未设置显式 thinking level 时，默认使用 - `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。 - `suppressToolErrorWarnings`：为 true 时，在心跳运行期间抑制工具错误警告负载。 - `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 会抑制直接目标投递，并发出 `reason=dm-blocked`。 -- `lightContext`：为 true 时，心跳运行使用轻量 bootstrap 上下文，并仅保留工作区 bootstrap 文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：为 true 时，每次心跳运行都在全新会话中执行，不带任何先前对话历史。隔离模式与 cron 的 `sessionTarget: "isolated"` 相同。可将每次心跳的 token 成本从约 100K 降至约 2-5K。 -- 按智能体设置：使用 `agents.list[].heartbeat`。当任一智能体定义了 `heartbeat` 时，**只会运行这些智能体**的心跳。 -- 心跳会运行完整智能体轮次——更短的间隔会消耗更多 token。 +- `lightContext`：为 true 时，心跳运行会使用轻量 bootstrap 上下文，并且只保留工作区 bootstrap 文件中的 `HEARTBEAT.md`。 +- `isolatedSession`：为 true 时，每次心跳都会在一个全新会话中运行，不包含任何先前对话历史。隔离模式与 cron `sessionTarget: "isolated"` 相同。可将每次心跳的 token 成本从约 100K 降低到约 2-5K token。 +- 按智能体：设置 `agents.list[].heartbeat`。当任一智能体定义了 `heartbeat` 时，**只有这些智能体**会运行心跳。 +- 心跳会运行完整智能体回合——间隔越短，消耗的 token 越多。 ### `agents.defaults.compaction` @@ -1184,15 +1223,15 @@ Anthropic Claude 4.6 模型在未设置显式 thinking level 时，默认使用 } ``` -- `mode`：`default` 或 `safeguard`（用于长历史的分块摘要）。见 [Compaction](/zh-CN/concepts/compaction)。 -- `provider`：已注册 compaction provider 插件的 id。设置后，将调用该提供商的 `summarize()`，而不是内置的 LLM 摘要。失败时会回退到内置实现。设置 provider 会强制 `mode: "safeguard"`。见 [Compaction](/zh-CN/concepts/compaction)。 -- `timeoutSeconds`：OpenClaw 中止单次 compaction 操作前允许的最大秒数。默认值：`900`。 -- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要过程中预置内建的 opaque identifier 保留指导。 -- `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义 identifier 保留说明。 -- `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 前执行静默智能体轮次，以存储持久记忆。工作区为只读时会跳过。 +- `mode`：`default` 或 `safeguard`（针对长历史的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `provider`：已注册 compaction provider 插件的 ID。设置后，将调用该 provider 的 `summarize()` 而不是内置 LLM 摘要。失败时会回退到内置实现。设置 provider 会强制使用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `timeoutSeconds`：OpenClaw 中止前允许单次 compaction 操作运行的最大秒数。默认值：`900`。 +- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预置内置的不透明标识符保留指导。 +- `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。 +- `postCompactionSections`：compaction 后可选的 AGENTS.md H2/H3 节名，用于重新注入。默认为 `["Session Startup", "Red Lines"]`；设置为 `[]` 可禁用重新注入。未设置或显式设置为该默认对时，也接受旧版 `Every Session`/`Safety` 标题作为兼容回退。 +- `model`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。当你希望主会话继续使用某个模型，而 compaction 摘要使用另一个模型时可使用；未设置时，compaction 使用会话主模型。 +- `notifyUser`：为 `true` 时，在 compaction 开始时向用户发送简短通知（例如“正在压缩上下文...”）。默认禁用，以保持 compaction 静默。 +- `memoryFlush`：在自动 compaction 之前执行的静默智能体回合，用于存储持久 memory。工作区为只读时会跳过。 ### `agents.defaults.contextPruning` @@ -1220,23 +1259,23 @@ Anthropic Claude 4.6 模型在未设置显式 thinking level 时，默认使用 -- `mode: "cache-ttl"` 启用修剪流程。 -- `ttl` 控制下次允许再次执行修剪的时间（自上次缓存触达之后）。 -- 修剪会先对过大的工具结果做软修剪，如仍有需要，再对更旧的工具结果做硬清除。 +- `mode: "cache-ttl"` 会启用修剪过程。 +- `ttl` 控制多久之后才能再次运行修剪（从上次缓存触碰之后开始计时）。 +- 修剪会先对超大的工具结果执行软修剪，如仍有必要，再对更旧的工具结果执行硬清除。 -**软修剪**会保留开头和结尾，并在中间插入 `...`。 +**软修剪** 会保留开头和结尾，并在中间插入 `...`。 -**硬清除**会用占位符替换整个工具结果。 +**硬清除** 会使用占位符替换整个工具结果。 -说明： +注意： -- 图像块绝不会被修剪/清除。 -- 比例基于字符数（近似），而非精确 token 数。 -- 若 assistant 消息少于 `keepLastAssistants` 条，则跳过修剪。 +- 图像块永远不会被修剪/清除。 +- 比例基于字符数（近似），不是精确 token 数。 +- 如果 assistant 消息少于 `keepLastAssistants`，则跳过修剪。 -行为细节见 [Session Pruning](/zh-CN/concepts/session-pruning)。 +行为细节参见 [会话修剪](/zh-CN/concepts/session-pruning)。 ### 分块流式传输 @@ -1256,9 +1295,9 @@ Anthropic Claude 4.6 模型在未设置显式 thinking level 时，默认使用 - 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。 - 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账号变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 -- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500 ms。按智能体覆盖：`agents.list[].humanDelay`。 +- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。按智能体覆盖：`agents.list[].humanDelay`。 -有关行为和分块细节，见 [Streaming](/zh-CN/concepts/streaming)。 +行为和分块细节参见 [流式传输](/zh-CN/concepts/streaming)。 ### 输入状态指示器 @@ -1273,16 +1312,16 @@ Anthropic Claude 4.6 模型在未设置显式 thinking level 时，默认使用 } ``` -- 默认值：在私聊/被提及时使用 `instant`，在未被提及的群聊中使用 `message`。 +- 默认值：私聊/提及使用 `instant`，未被提及的群聊使用 `message`。 - 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 -见 [Typing Indicators](/zh-CN/concepts/typing-indicators)。 +参见 [输入状态指示器](/zh-CN/concepts/typing-indicators)。 ### `agents.defaults.sandbox` -内嵌智能体的可选沙箱隔离。完整指南见 [Sandboxing](/zh-CN/gateway/sandboxing)。 +嵌入式智能体的可选沙箱隔离。完整指南请参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -1385,14 +1424,14 @@ Anthropic Claude 4.6 模型在未设置显式 thinking level 时，默认使用 - `ssh`：通用 SSH 远程运行时 - `openshell`：OpenShell 运行时 -选择 `backend: "openshell"` 时，运行时特定设置会移动到 +当选择 `backend: "openshell"` 时，运行时特定设置会移到 `plugins.entries.openshell.config`。 **SSH 后端配置：** -- `target`：格式为 `user@host[:port]` 的 SSH 目标 +- `target`：`user@host[:port]` 形式的 SSH 目标 - `command`：SSH 客户端命令（默认：`ssh`） -- `workspaceRoot`：用于按作用域工作区的远程绝对根目录 +- `workspaceRoot`：用于按范围工作区的远程绝对根路径 - `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件 - `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其实体化为临时文件 - `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关 @@ -1402,27 +1441,27 @@ Anthropic Claude 4.6 模型在未设置显式 thinking level 时，默认使用 - `identityData` 优先于 `identityFile` - `certificateData` 优先于 `certificateFile` - `knownHostsData` 优先于 `knownHostsFile` -- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前，从活动 secrets 运行时快照中解析 +- 基于 SecretRef 的 `*Data` 值会在沙箱会话启动前从活动 secrets 运行时快照中解析 **SSH 后端行为：** -- 在创建或重建后对远程工作区执行一次初始化 -- 此后保持远程 SSH 工作区为规范副本 +- 在创建或重建后只会为远程工作区播种一次 +- 然后保持远程 SSH 工作区为规范副本 - 通过 SSH 路由 `exec`、文件工具和媒体路径 - 不会自动将远程更改同步回主机 - 不支持沙箱浏览器容器 **工作区访问：** -- `none`：在 `~/.openclaw/sandboxes` 下使用按作用域分配的沙箱工作区 +- `none`：在 `~/.openclaw/sandboxes` 下创建按范围划分的沙箱工作区 - `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent` - `rw`：智能体工作区以读写方式挂载到 `/workspace` -**作用域：** +**范围：** - `session`：每会话一个容器 + 工作区 -- `agent`：每智能体一个容器 + 工作区（默认） -- `shared`：共享容器和工作区（不提供跨会话隔离） +- `agent`：每个智能体一个容器 + 工作区（默认） +- `shared`：共享容器和工作区（无跨会话隔离） **OpenShell 插件配置：** @@ -1452,30 +1491,30 @@ Anthropic Claude 4.6 模型在未设置显式 thinking level 时，默认使用 **OpenShell 模式：** -- `mirror`：执行前从本地播种到远程，执行后再同步回来；本地工作区保持为规范副本 -- `remote`：在创建沙箱时只向远程播种一次，此后保持远程工作区为规范副本 +- `mirror`：在 exec 之前从本地播种到远程，在 exec 之后同步回本地；本地工作区保持为规范副本 +- `remote`：在创建沙箱时只为远程播种一次，之后保持远程工作区为规范副本 -在 `remote` 模式下，种子步骤之后，在 OpenClaw 外部对主机本地做的编辑不会自动同步进沙箱。 -传输使用 SSH 进入 OpenShell 沙箱，但插件负责沙箱生命周期和可选镜像同步。 +在 `remote` 模式下，播种步骤之后，主机本地在 OpenClaw 外部所做的修改不会自动同步到沙箱中。 +传输方式是通过 SSH 进入 OpenShell 沙箱，但插件拥有沙箱生命周期以及可选的镜像同步。 -**`setupCommand`** 在容器创建后运行一次（通过 `sh -lc`）。需要网络出站、可写根文件系统和 root 用户。 +**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根目录和 root 用户。 -**容器默认使用 `network: "none"`**——如果智能体需要出站访问，请设为 `"bridge"`（或自定义 bridge 网络）。 -`"host"` 会被阻止。默认情况下 `"container:"` 也会被阻止，除非你显式设置 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急开关）。 +**容器默认使用 `network: "none"`**——如果智能体需要出站访问，请设置为 `"bridge"`（或自定义桥接网络）。 +`"host"` 会被阻止。默认也会阻止 `"container:"`，除非你显式设置 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急模式）。 -**入站附件** 会被暂存到活动工作区中的 `media/inbound/*`。 +**传入附件** 会被暂存到活动工作区中的 `media/inbound/*`。 -**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的绑定会合并。 +**`docker.binds`** 用于挂载额外的主机目录；全局和按智能体的绑定会被合并。 -**沙箱隔离浏览器**（`sandbox.browser.enabled`）：在容器中运行 Chromium + CDP。noVNC URL 会注入到系统提示词中。不需要在 `openclaw.json` 中启用 `browser.enabled`。 -默认情况下，noVNC 观察者访问使用 VNC 认证，OpenClaw 会发出短时有效 token URL（而不是在共享 URL 中暴露密码）。 +**沙箱隔离浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 会注入系统提示中。不要求在 `openclaw.json` 中启用 `browser.enabled`。 +默认情况下，noVNC 观察者访问使用 VNC 认证，OpenClaw 会发出一个短期有效的 token URL（而不是在共享 URL 中暴露密码）。 - `allowHostControl: false`（默认）会阻止沙箱隔离会话以主机浏览器为目标。 -- `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。仅当你明确想要全局 bridge 连通性时才设为 `bridge`。 -- `cdpSourceRange` 可选择性地在容器边界将 CDP 入站限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。 -- `sandbox.browser.binds` 仅将额外主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。 -- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机进行了调优： +- `network` 默认是 `openclaw-sandbox-browser`（专用桥接网络）。仅在你明确需要全局桥接连通性时才设置为 `bridge`。 +- `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` @@ -1494,16 +1533,16 @@ Anthropic Claude 4.6 模型在未设置显式 thinking level 时，默认使用 - `--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` 会重新启用扩展， - 如果你的工作流依赖它们。 + 默认启用；如果 WebGL/3D 使用场景需要它们，可通过 + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用这些标志。 + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展，如果你的工作流 + 依赖它们。 - `--renderer-process-limit=2` 可通过 - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 更改；设为 `0` 可使用 Chromium 的 + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设置为 `0` 可使用 Chromium 的 默认进程限制。 - - 当启用 `noSandbox` 时，还会附加 `--no-sandbox` 和 `--disable-setuid-sandbox`。 + - 以及在启用 `noSandbox` 时添加 `--no-sandbox` 和 `--disable-setuid-sandbox`。 - 这些默认值是容器镜像基线；如需更改容器默认值，请使用带自定义 - entrypoint 的自定义浏览器镜像。 + 入口点的自定义浏览器镜像。 @@ -1564,26 +1603,26 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `id`：稳定的智能体 id（必填）。 -- `default`：设置多个时，以第一个为准（会记录警告）。若都未设置，则列表第一项为默认。 -- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 同时覆盖二者（`[]` 会禁用全局 fallbacks）。仅覆盖 `primary` 的 cron 作业仍会继承默认 fallbacks，除非你设置 `fallbacks: []`。 -- `params`：按智能体的流参数，会合并到 `agents.defaults.models` 中选定模型条目之上。用于像 `cacheRetention`、`temperature` 或 `maxTokens` 这类智能体特定覆盖，而无需复制整个模型目录。 -- `skills`：可选的按智能体 Skills 允许列表。省略时，若设置了 `agents.defaults.skills`，该智能体将继承之；显式列表会替换默认值而非合并，`[]` 表示无 Skills。 -- `thinkingDefault`：可选的按智能体默认 thinking level（`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）。 +- `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）。 --- ## 多智能体路由 -在一个 Gateway 网关内运行多个彼此隔离的智能体。见 [Multi-Agent](/zh-CN/concepts/multi-agent)。 +在一个 Gateway 网关中运行多个隔离智能体。参见 [多智能体](/zh-CN/concepts/multi-agent)。 ```json5 { @@ -1602,12 +1641,12 @@ scripts/sandbox-browser-setup.sh # optional browser image ### 绑定匹配字段 -- `type`（可选）：普通路由使用 `route`（缺失时默认 route），持久 ACP 对话绑定使用 `acp` +- `type`（可选）：普通路由使用 `route`（省略 type 时默认为 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 }` +- `match.guildId` / `match.teamId`（可选；渠道特定） +- `acp`（可选；仅适用于 `type: "acp"`）：`{ mode, label, cwd, backend }` **确定性的匹配顺序：** @@ -1618,9 +1657,9 @@ scripts/sandbox-browser-setup.sh # optional browser image 5. `match.accountId: "*"`（渠道范围） 6. 默认智能体 -在每一层级内，第一个匹配的 `bindings` 条目获胜。 +在每个层级内，第一个匹配的 `bindings` 条目获胜。 -对于 `type: "acp"` 条目，OpenClaw 按精确对话身份解析（`match.channel` + account + `match.peer.id`），不会使用上面的 route 绑定层级顺序。 +对于 `type: "acp"` 的条目，OpenClaw 会通过精确的会话身份（`match.channel` + 账号 + `match.peer.id`）进行解析，不使用上面的 route 绑定层级顺序。 ### 按智能体访问配置 @@ -1717,7 +1756,7 @@ scripts/sandbox-browser-setup.sh # optional browser image -优先级细节见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 +优先级细节参见 [多智能体沙箱隔离与工具](/zh-CN/tools/multi-agent-sandbox-tools)。 --- @@ -1771,34 +1810,34 @@ scripts/sandbox-browser-setup.sh # optional browser image - **`scope`**：群聊上下文的基础会话分组策略。 - - `per-sender`（默认）：在渠道上下文中，每个发送者各自使用隔离会话。 - - `global`：渠道上下文中的所有参与者共享一个会话（仅在确实需要共享上下文时使用）。 + - `per-sender`（默认）：在一个渠道上下文中，每个发送者都拥有独立会话。 + - `global`：一个渠道上下文中的所有参与者共享同一个会话（仅在确实需要共享上下文时使用）。 - **`dmScope`**：私信的分组方式。 - `main`：所有私信共享主会话。 - - `per-peer`：按跨渠道发送者 id 隔离。 + - `per-peer`：跨渠道按发送者 ID 隔离。 - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。 -- **`identityLinks`**：将规范 id 映射到带 provider 前缀的对端，用于跨渠道共享会话。 -- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。若两者都配置，谁先到期就以谁为准。 +- **`identityLinks`**：将规范 ID 映射到带 provider 前缀的对端，用于跨渠道会话共享。 +- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。两者都配置时，以先到期者为准。 - **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。 -- **`parentForkMaxTokens`**：创建分叉线程会话时，允许父会话使用的最大 `totalTokens`（默认 `100000`）。 - - 如果父会话的 `totalTokens` 高于此值，OpenClaw 会启动全新的线程会话，而不是继承父级转录历史。 - - 设为 `0` 可禁用此保护，并始终允许父级分叉。 +- **`parentForkMaxTokens`**：创建分叉线程会话时，父会话允许的最大 `totalTokens`（默认 `100000`）。 + - 如果父会话的 `totalTokens` 高于该值，OpenClaw 会启动一个新的线程会话，而不是继承父级转录历史。 + - 设置为 `0` 可禁用此保护并始终允许父级分叉。 - **`mainKey`**：旧版字段。运行时现在始终对主私聊桶使用 `"main"`。 -- **`agentToAgent.maxPingPongTurns`**：智能体之间互相回复时允许的最大往返轮数（整数，范围：`0`–`5`）。`0` 表示禁用 ping-pong 链式往返。 -- **`sendPolicy`**：可按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 生效。 +- **`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`：可选的会话目录磁盘预算。在 `warn` 模式下仅记录警告；在 `enforce` 模式下会优先移除最旧的工件/会话。 - - `highWaterBytes`：可选的预算清理目标值。默认是 `maxDiskBytes` 的 `80%`。 + - `mode`：`warn` 仅发出警告；`enforce` 会实际执行清理。 + - `pruneAfter`：陈旧条目的年龄截止值（默认 `30d`）。 + - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。 + - `rotateBytes`：当 `sessions.json` 超过该大小时轮转（默认 `10mb`）。 + - `resetArchiveRetention`：`*.reset.` 转录归档的保留期限。默认与 `pruneAfter` 相同；设为 `false` 可禁用。 + - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先移除最旧的工件/会话。 + - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - - `enabled`：总开关默认值（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：按小时的默认无活动自动取消聚焦时间（`0` 表示禁用；提供商可覆盖） - - `maxAgeHours`：按小时的默认硬性最大时长（`0` 表示禁用；提供商可覆盖） + - `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） + - `idleHours`：默认按小时计算的不活动自动取消聚焦时间（`0` 禁用；提供商可覆盖） + - `maxAgeHours`：默认按小时计算的硬性最大时长（`0` 禁用；提供商可覆盖） @@ -1836,36 +1875,36 @@ scripts/sandbox-browser-setup.sh # optional browser image ### 回复前缀 -按渠道/账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 +按渠道/按账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 -解析顺序（越具体优先级越高）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会推导为 `[{identity.name}]`。 +解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会推导为 `[{identity.name}]`。 **模板变量：** -| 变量 | 描述 | 示例 | -| ------------------ | ---------------- | --------------------------- | -| `{model}` | 短模型名 | `claude-opus-4-6` | -| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | -| `{provider}` | 提供商名称 | `anthropic` | -| `{thinkingLevel}` | 当前 thinking 级别 | `high`, `low`, `off` | -| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | +| 变量 | 描述 | 示例 | +| ----------------- | ------------------ | --------------------------- | +| `{model}` | 短模型名 | `claude-opus-4-6` | +| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | +| `{provider}` | 提供商名称 | `anthropic` | +| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | +| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。 ### 确认反应 -- 默认为活动智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。 +- 默认取活动智能体的 `identity.emoji`，否则为 `"👀"`。设置为 `""` 可禁用。 - 按渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。 - 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退。 -- 作用域：`group-mentions`（默认）、`group-all`、`direct`、`all`。 -- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 中，回复后移除确认反应。 -- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 中启用生命周期状态反应。 - 在 Slack 和 Discord 上，未设置时，如果确认反应处于活动状态，则状态反应保持启用。 - 在 Telegram 上，需要显式设为 `true` 才会启用生命周期状态反应。 +- 范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。 +- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，回复后移除确认反应。 +- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。 + 在 Slack 和 Discord 上，未设置时会在确认反应激活时保持状态反应启用。 + 在 Telegram 上，需显式设置为 `true` 才会启用生命周期状态反应。 -### 入站去抖 +### 传入防抖 -将来自同一发送者的快速连续纯文本消息批处理为单个智能体轮次。媒体/附件会立即触发。控制命令会绕过去抖。 +将同一发送者快速发送的纯文本消息批量合并为一次智能体回合。媒体/附件会立即刷新。控制命令会绕过防抖。 ### TTS（文本转语音） @@ -1908,18 +1947,18 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `auto` 控制自动 TTS。`/tts off|always|inbound|tagged` 会按会话覆盖。 +- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆盖本地偏好，而 `/tts status` 会显示生效状态。 - `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 服务器，并放宽模型/语音校验。 +- `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 服务器，并放宽 model/voice 校验。 --- ## Talk -Talk mode 的默认值（macOS/iOS/Android）。 +Talk 模式（macOS/iOS/Android）的默认值。 ```json5 { @@ -1943,35 +1982,35 @@ Talk mode 的默认值（macOS/iOS/Android）。 } ``` -- 当配置了多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的某个键。 +- 当配置了多个 Talk provider 时，`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`。 +- Voice ID 可回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 - `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。 -- 仅当未配置 Talk API key 时，才会回退到 `ELEVENLABS_API_KEY`。 +- 只有在未配置任何 Talk API key 时，才会使用 `ELEVENLABS_API_KEY` 回退。 - `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。 -- `silenceTimeoutMs` 控制 Talk mode 在用户静音后等待多久才发送转录。未设置时保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 +- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多久才发送转录。未设置时会保留平台默认停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 --- ## 工具 -### 工具配置 +### 工具配置文件 -`tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置基础允许列表： +`tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置一个基础允许列表： -本地新手引导会在新本地配置未设置时，默认使用 `tools.profile: "coding"`（已显式设置的 profile 会保留）。 +本地新手引导会在新本地配置未设置时，默认设为 `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` | @@ -1987,7 +2026,7 @@ Talk mode 的默认值（macOS/iOS/Android）。 ### `tools.allow` / `tools.deny` -全局工具允许/拒绝策略（拒绝优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱关闭也会生效。 +全局工具允许/拒绝策略（deny 优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱关闭也会应用。 ```json5 { @@ -1997,7 +2036,7 @@ Talk mode 的默认值（macOS/iOS/Android）。 ### `tools.byProvider` -进一步针对特定 provider 或 model 限制工具。顺序：基础 profile → provider profile → allow/deny。 +进一步为特定 provider 或模型限制工具。顺序：基础配置文件 → provider 配置文件 → allow/deny。 ```json5 { @@ -2013,7 +2052,7 @@ Talk mode 的默认值（macOS/iOS/Android）。 ### `tools.elevated` -控制沙箱外的 elevated exec 访问： +控制沙箱外部的 elevated exec 访问： ```json5 { @@ -2029,9 +2068,9 @@ Talk mode 的默认值（macOS/iOS/Android）。 } ``` -- 按智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧。 -- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅作用于单条消息。 -- Elevated `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认 `gateway`，或当 exec 目标为 `node` 时使用 `node`）。 +- 按智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧限制。 +- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅适用于单条消息。 +- Elevated `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`，或当 exec 目标是 `node` 时使用 `node`）。 ### `tools.exec` @@ -2055,8 +2094,8 @@ Talk mode 的默认值（macOS/iOS/Android）。 ### `tools.loopDetection` -工具循环安全检查**默认禁用**。设为 `enabled: true` 可启用检测。 -设置可在 `tools.loopDetection` 中全局定义，也可在 `agents.list[].tools.loopDetection` 中按智能体覆盖。 +工具循环安全检查默认**关闭**。设置 `enabled: true` 可激活检测。 +设置可以在全局 `tools.loopDetection` 中定义，并在每个智能体的 `agents.list[].tools.loopDetection` 中覆盖。 ```json5 { @@ -2081,9 +2120,9 @@ Talk mode 的默认值（macOS/iOS/Android）。 - `warningThreshold`：用于发出警告的重复无进展模式阈值。 - `criticalThreshold`：用于阻止严重循环的更高重复阈值。 - `globalCircuitBreakerThreshold`：任何无进展运行的硬停止阈值。 -- `detectors.genericRepeat`：对重复的同工具/同参数调用发出警告。 -- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）进行警告/阻止。 -- `detectors.pingPong`：对交替出现的双向无进展模式进行警告/阻止。 +- `detectors.genericRepeat`：对重复的相同工具/相同参数调用发出警告。 +- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）发出警告/阻止。 +- `detectors.pingPong`：对交替出现的无进展成对模式发出警告/阻止。 - 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，校验会失败。 ### `tools.web` @@ -2118,7 +2157,7 @@ Talk mode 的默认值（macOS/iOS/Android）。 ### `tools.media` -配置入站媒体理解（图像/音频/视频）： +配置传入媒体理解（图像/音频/视频）： ```json5 { @@ -2152,11 +2191,11 @@ Talk mode 的默认值（macOS/iOS/Android）。 -**提供商条目**（`type: "provider"` 或省略）： +**Provider 条目**（`type: "provider"` 或省略）： -- `provider`：API 提供商 id（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） -- `model`：模型 id 覆盖 -- `profile` / `preferredProfile`：`auth-profiles.json` 配置选择 +- `provider`：API provider ID（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） +- `model`：模型 ID 覆盖 +- `profile` / `preferredProfile`：`auth-profiles.json` 配置文件选择 **CLI 条目**（`type: "cli"`）： @@ -2166,16 +2205,16 @@ Talk mode 的默认值（macOS/iOS/Android）。 **通用字段：** - `capabilities`：可选列表（`image`、`audio`、`video`）。默认值：`openai`/`anthropic`/`minimax` → image，`google` → image+audio+video，`groq` → audio。 -- `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：按条目覆盖。 +- `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：每条目的覆盖值。 - 失败时会回退到下一个条目。 -提供商认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 +Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 **异步完成字段：** - `asyncCompletion.directSend`：为 `true` 时，已完成的异步 `music_generate` 和 `video_generate` 任务会优先尝试直接投递到渠道。默认：`false` - （沿用旧版请求者会话唤醒/模型投递路径）。 + （旧版请求者会话唤醒/模型投递路径）。 @@ -2194,9 +2233,9 @@ Talk mode 的默认值（macOS/iOS/Android）。 ### `tools.sessions` -控制 session 工具（`sessions_list`、`sessions_history`、`sessions_send`）可定位哪些会话。 +控制会话工具（`sessions_list`、`sessions_history`、`sessions_send`）可以面向哪些会话。 -默认值：`tree`（当前会话 + 由其派生的会话，例如 subagents）。 +默认值：`tree`（当前会话 + 由其生成的会话，例如 subagents）。 ```json5 { @@ -2212,10 +2251,10 @@ Talk mode 的默认值（macOS/iOS/Android）。 说明： - `self`：仅当前会话键。 -- `tree`：当前会话 + 由当前会话派生的会话（subagents）。 -- `agent`：属于当前智能体 id 的任意会话（如果你在同一智能体 id 下运行 per-sender 会话，可能包括其他用户）。 +- `tree`：当前会话 + 当前会话生成的会话（subagents）。 +- `agent`：属于当前智能体 ID 的任意会话（如果你在同一个智能体 ID 下运行按发送者划分的会话，可能包括其他用户）。 - `all`：任意会话。跨智能体定向仍需要 `tools.agentToAgent`。 -- 沙箱钳制：当当前会话位于沙箱隔离中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 +- 沙箱钳制：当当前会话在沙箱中且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 ### `tools.sessions_spawn` @@ -2239,16 +2278,16 @@ Talk mode 的默认值（macOS/iOS/Android）。 说明： -- 仅对 `runtime: "subagent"` 支持附件。ACP runtime 会拒绝它们。 -- 文件会实体化到子工作区 `.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 { @@ -2262,9 +2301,9 @@ Talk mode 的默认值（macOS/iOS/Android）。 说明： -- `planTool`：为非简单多步骤工作跟踪启用结构化 `update_plan` 工具。 -- 默认值：对非 OpenAI 提供商为 `false`。OpenAI 和 OpenAI Codex 运行在未设置时会自动启用；设为 `false` 可关闭该自动启用。 -- 启用后，系统提示词也会加入使用指南，使模型仅在较复杂工作中使用它，并保持最多一个步骤处于 `in_progress`。 +- `planTool`：为非平凡多步骤工作跟踪启用结构化 `update_plan` 工具。 +- 默认：对非 OpenAI provider 为 `false`。OpenAI 和 OpenAI Codex 运行会在未设置时自动启用；设为 `false` 可禁用该自动启用。 +- 启用后，系统提示也会加入使用指导，让模型仅在重要工作时使用它，并始终最多只保留一个 `in_progress` 步骤。 ### `agents.defaults.subagents` @@ -2284,16 +2323,16 @@ Talk mode 的默认值（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`。 --- -## 自定义提供商和 base URL +## 自定义 provider 和 base URL -OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义提供商。 +OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义 provider。 ```json5 { @@ -2322,49 +2361,49 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 } ``` -- 使用 `authHeader: true` + `headers` 可满足自定义认证需求。 -- 通过 `OPENCLAW_AGENT_DIR`（或旧版环境变量别名 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。 -- 对匹配 provider ID 的合并优先级： +- 使用 `authHeader: true` + `headers` 处理自定义认证需求。 +- 使用 `OPENCLAW_AGENT_DIR`（或旧版环境变量别名 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。 +- 匹配 provider ID 的合并优先级： - 非空的智能体 `models.json` `baseUrl` 值优先。 - - 非空的智能体 `apiKey` 值仅在当前配置/auth-profile 上下文中该 provider 不是 SecretRef 管理时才优先。 - - 由 SecretRef 管理的 provider `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，file/exec 引用使用 `secretref-managed`），而不是持久化解析后的 secret。 - - 由 SecretRef 管理的 provider header 值也会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，file/exec 引用使用 `secretref-managed`）。 + - 非空的智能体 `apiKey` 值仅在该 provider 在当前配置/auth-profile 上下文中不受 SecretRef 管理时优先。 + - 受 SecretRef 管理的 provider `apiKey` 值会从源标记刷新（环境变量引用为 `ENV_VAR_NAME`，file/exec 引用为 `secretref-managed`），而不是持久化已解析的 secret。 + - 受 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 值写入。 -### 提供商字段详情 +### Provider 字段详情 - `models.mode`：provider 目录行为（`merge` 或 `replace`）。 -- `models.providers`：按 provider id 作为键的自定义 provider 映射。 +- `models.providers`：按 provider ID 建立键的自定义 provider 映射。 - `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。 - `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.*.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.*.request`：模型提供商 HTTP 请求的传输覆盖。 +- `models.providers.*.request`：模型-provider HTTP 请求的传输覆盖。 - `request.headers`：额外 headers（与 provider 默认值合并）。值接受 SecretRef。 - - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用 provider 内置认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value`，可选 `prefix`）。 + - `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`。 + - `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`（主机不是 `api.openai.com`）的情况，OpenClaw 会在运行时强制将其设为 `false`。空/省略的 `baseUrl` 保持 OpenAI 默认行为。 -- `models.providers.*.models.*.compat.requiresStringContent`：适用于仅支持字符串内容的 OpenAI 兼容聊天端点的可选兼容性提示。为 `true` 时，OpenClaw 会在发送请求前，将纯文本 `messages[].content` 数组压平成普通字符串。 -- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根节点。 +- `models.providers.*.models.*.contextTokens`：可选运行时上下文上限。当你希望有效上下文预算小于模型原生 `contextWindow` 时，请使用它。 +- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且 `baseUrl` 为非空非原生值（主机不是 `api.openai.com`）时，OpenClaw 会在运行时强制将其设为 `false`。空/省略 `baseUrl` 时会保留默认 OpenAI 行为。 +- `models.providers.*.models.*.compat.requiresStringContent`：为仅接受字符串的兼容 OpenAI 聊天端点提供可选兼容性提示。为 `true` 时，OpenClaw 会在发送请求前将纯文本 `messages[].content` 数组压平为普通字符串。 +- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根。 - `plugins.entries.amazon-bedrock.config.discovery.enabled`：开启/关闭隐式发现。 -- `plugins.entries.amazon-bedrock.config.discovery.region`：用于发现的 AWS 区域。 -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：可选的 provider-id 过滤器，用于定向发现。 +- `plugins.entries.amazon-bedrock.config.discovery.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。 -### 提供商示例 +### Provider 示例 @@ -2417,7 +2456,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`。 @@ -2434,11 +2473,11 @@ 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`。 +设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 都是可接受的别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。 - 通用端点：`https://api.z.ai/api/paas/v4` - Coding 端点（默认）：`https://api.z.ai/api/coding/paas/v4` -- 对于通用端点，请定义一个带 base URL 覆盖的自定义提供商。 +- 如果需要使用通用端点，请定义一个带 base URL 覆盖的自定义 provider。 @@ -2477,11 +2516,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 现在会依据端点 -能力，而不再仅依据内置 provider id 来判断。 +`openai-completions` 传输上声明流式使用兼容性，而 OpenClaw 现在会根据端点 +能力而不是仅凭内置 provider ID 来判断这一点。 @@ -2499,11 +2538,11 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -内置的 Anthropic 兼容 provider。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 +兼容 Anthropic 的内置 provider。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 - + ```json5 { @@ -2582,16 +2621,16 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 `openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。 模型目录现在默认仅包含 M2.7。 -在 Anthropic 兼容的流式传输路径上，除非你显式设置 `thinking`， -否则 OpenClaw 默认会禁用 MiniMax thinking。`/fast on` 或 -`params.fastMode: true` 会将 `MiniMax-M2.7` 改写为 +在兼容 Anthropic 的流式路径上，OpenClaw 默认会禁用 MiniMax thinking， +除非你显式设置了 `thinking`。`/fast on` 或 +`params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 -见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在较强硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。 +参见 [本地模型](/zh-CN/gateway/local-models)。简而言之：在强大硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留合并的托管模型作为回退。 @@ -2622,12 +2661,12 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 } ``` -- `allowBundled`：仅针对内置技能的可选允许列表（managed/workspace Skills 不受影响）。 -- `load.extraDirs`：额外的共享技能根目录（最低优先级）。 -- `install.preferBrew`：为 true 时，若 `brew` 可用，会优先使用 Homebrew 安装器，再回退到其他安装器类型。 -- `install.nodeManager`：`metadata.openclaw.install` 规范的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false`：即使技能已内置/已安装，也会禁用该技能。 -- `entries..apiKey`：对声明了主环境变量的技能提供 API key 便捷字段（明文字符串或 SecretRef 对象）。 +- `allowBundled`：仅针对内置 Skills 的可选允许列表（managed/workspace Skills 不受影响）。 +- `load.extraDirs`：额外的共享 skill 根目录（最低优先级）。 +- `install.preferBrew`：为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器，再回退到其他安装器类型。 +- `install.nodeManager`：`metadata.openclaw.install` 规格的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false`：即使某个 skill 是内置/已安装的，也会将其禁用。 +- `entries..apiKey`：为声明了主环境变量的 skill 提供便利字段（明文字符串或 SecretRef 对象）。 --- @@ -2656,36 +2695,42 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 ``` - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 -- 发现流程接受原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 -- **配置变更需要重启 Gateway 网关。** +- 设备发现接受原生 OpenClaw 插件以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 +- **配置更改需要重启 Gateway 网关。** - `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。 -- `plugins.entries..apiKey`：插件级 API key 便捷字段（插件支持时可用）。 +- `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`：显式信任此插件可为后台 subagent 运行请求按次 `provider` 和 `model` 覆盖。 -- `plugins.entries..subagent.allowedModels`：受信任 subagent 覆盖可使用的规范 `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` 环境变量。 +- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，core 会阻止 `before_prompt_build`，并忽略来自旧版 `before_agent_start` 的 prompt 变异字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hook 以及受支持的 bundle 提供 hook 目录。 +- `plugins.entries..subagent.allowModelOverride`：显式信任该插件在后台 subagent 运行时请求按次运行的 `provider` 和 `model` 覆盖。 +- `plugins.entries..subagent.allowedModels`：受信任 subagent 覆盖可使用的规范 `provider/model` 目标可选允许列表。仅在你有意允许任意模型时才使用 `"*"`。 +- `plugins.entries..config`：插件定义的配置对象（当有可用 schema 时，会由原生 OpenClaw 插件 schema 校验）。 +- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web 获取 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`）。 + - `onlyMainContent`：只提取页面主内容（默认：`true`）。 + - `maxAgeMs`：缓存最大年龄（毫秒）（默认：`172800000` / 2 天）。 + - `timeoutSeconds`：抓取请求超时（秒）（默认：`60`）。 - `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web 搜索）设置。 - `enabled`：启用 X Search provider。 - `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。 -- `plugins.entries.memory-core.config.dreaming`：记忆 dreaming（实验性）设置。阶段和阈值见 [Dreaming](/zh-CN/concepts/dreaming)。 - - `enabled`：dreaming 总开关（默认 `false`）。 +- `plugins.entries.memory-core.config.dreaming`：memory dreaming（实验性）设置。有关阶段和阈值，请参见 [Dreaming](/zh-CN/concepts/dreaming)。 + - `enabled`：dreaming 主开关（默认 `false`）。 - `frequency`：每次完整 dreaming 扫描的 cron 频率（默认 `"0 3 * * *"`）。 - 阶段策略和阈值属于实现细节（不是面向用户的配置键）。 -- 已启用的 Claude bundle 插件也可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为清洗后的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。 -- `plugins.slots.memory`：选择活动 memory 插件 id，或使用 `"none"` 禁用 memory 插件。 -- `plugins.slots.contextEngine`：选择活动上下文引擎插件 id；除非你安装并选择了其他引擎，否则默认是 `"legacy"`。 +- 完整的 memory 配置位于 [Memory 配置参考](/zh-CN/reference/memory-config)： + - `agents.defaults.memorySearch.*` + - `memory.backend` + - `memory.citations` + - `memory.qmd.*` + - `plugins.entries.memory-core.config.dreaming` +- 已启用的 Claude bundle 插件也可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为经过净化的智能体设置应用，而不是原始的 OpenClaw 配置补丁。 +- `plugins.slots.memory`：选择活动 memory 插件 ID，或设置为 `"none"` 以禁用 memory 插件。 +- `plugins.slots.contextEngine`：选择活动上下文引擎插件 ID；默认是 `"legacy"`，除非你安装并选择了其他引擎。 - `plugins.installs`：由 CLI 管理的安装元数据，供 `openclaw plugins update` 使用。 - 包含 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。 - - 请将 `plugins.installs.*` 视为受管状态；优先使用 CLI 命令，而不是手动编辑。 + - 将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。 -见 [Plugins](/zh-CN/tools/plugin)。 +参见 [插件](/zh-CN/tools/plugin)。 --- @@ -2727,27 +2772,27 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 - `ssrfPolicy.dangerouslyAllowPrivateNetwork` 未设置时默认是 `true`（trusted-network 模型）。 -- 将 `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` 设为严格的仅公共网络浏览导航模式。 -- 在严格模式下，远程 CDP 配置端点（`profiles.*.cdpUrl`）在可达性/发现检查期间也会受到相同的 private-network 阻止。 -- `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 -- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 进行显式例外配置。 -- 远程配置为仅附加模式（启动/停止/重置已禁用）。 +- 如需严格的仅公网浏览器导航，请设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: false`。 +- 在 strict 模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间也会受到相同的私有网络阻止。 +- `ssrfPolicy.allowPrivateNetwork` 仍然作为旧版别名受支持。 +- 在 strict 模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 作为显式例外。 +- 远程配置文件是仅附加的（禁用 start/stop/reset）。 - `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。 - 如果你希望 OpenClaw 发现 `/json/version`，请使用 HTTP(S)； - 如果提供方直接给你 DevTools WebSocket URL，请使用 WS(S)。 -- `existing-session` 配置仅支持主机，并使用 Chrome MCP 而非 CDP。 -- `existing-session` 配置可设置 `userDataDir` 以指向特定的 - Chromium 浏览器配置，例如 Brave 或 Edge。 -- `existing-session` 配置保持当前 Chrome MCP 路由限制： - 使用 snapshot/ref 驱动的操作，而不是 CSS 选择器定向、单文件上传 - hooks、无对话框超时覆盖、无 `wait --load networkidle`，也无 + 如果你希望 OpenClaw 发现 `/json/version`，请使用 HTTP(S)；如果你的 provider 直接提供 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`、窗口尺寸或调试参数）。 +- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；只有 + 远程 CDP 才需要显式设置 `cdpUrl`。 +- 自动检测顺序：如果默认浏览器是 Chromium 系则优先使用默认浏览器 → Chrome → Brave → Edge → Chromium → Chrome Canary。 +- 控制服务：仅 loopback（端口由 `gateway.port` 派生，默认 `18791`）。 +- `extraArgs` 会为本地 Chromium 启动追加额外启动标志（例如 + `--disable-gpu`、窗口大小设置或调试标志）。 --- @@ -2766,7 +2811,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 ``` - `seamColor`：原生应用 UI 外观的强调色（Talk Mode 气泡着色等）。 -- `assistant`：控制 UI 的身份覆盖。会回退到当前活动智能体身份。 +- `assistant`：Control UI 身份覆盖。会回退到活动智能体身份。 --- @@ -2833,29 +2878,8 @@ 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 来源的连续失败不会自动 - 锁住另一个来源。 -- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公开，需要认证）。 -- `controlUi.allowedOrigins`：用于 Gateway WebSocket 连接的显式浏览器来源允许列表。若期望来自非 loopback 来源的浏览器客户端，则必须设置。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，会启用基于 Host header 的来源回退，适用于有意依赖 Host header 来源策略的部署。 -- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧紧急开关，允许对受信任 private-network IP 使用明文 `ws://`；默认仍然只允许对 loopback 使用明文。 -- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 gateway 认证。 -- `gateway.push.apns.relay.baseUrl`：外部 APNs relay 的基础 HTTPS URL，供官方/TestFlight iOS 构建在将基于 relay 的注册发布到 gateway 之后使用。该 URL 必须与编译进 iOS 构建中的 relay URL 一致。 -- `gateway.push.apns.relay.timeoutMs`：gateway 到 relay 的发送超时（毫秒）。默认值为 `10000`。 -- 基于 relay 的注册会委托给特定的 gateway 身份。配对后的 iOS 应 \ No newline at end of file +- **旧版 bind 别名**：在 `gateway.bind` 中使用 bind 模式值（`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 网关不可达。 \ No newline at end of file