diff --git a/docs/zh-CN/channels/discord.md b/docs/zh-CN/channels/discord.md index 4b608b558..37d5c7aea 100644 --- a/docs/zh-CN/channels/discord.md +++ b/docs/zh-CN/channels/discord.md @@ -1,20 +1,20 @@ --- read_when: - 处理 Discord 渠道功能时 -summary: Discord 机器人支持状态、功能与配置 +summary: Discord 机器人支持状态、功能和配置 title: Discord x-i18n: - generated_at: "2026-04-05T20:19:09Z" + generated_at: "2026-04-06T02:25:41Z" model: gpt-5.4 provider: openai - source_hash: 7fc471394b4fd2384779487f7ea5249897e826d2964094c0780613f3aea13946 + source_hash: 54af2176a1b4fa1681e3f07494def0c652a2730165058848000e71a59e2a9d08 source_path: channels/discord.md workflow: 15 --- # Discord（Bot API） -状态：已就绪，可通过官方 Discord gateway 支持私信和服务器频道。 +状态：已就绪，可通过官方 Discord Gateway 网关用于私信和服务器频道。 @@ -24,44 +24,44 @@ x-i18n: 原生命令行为和命令目录。 - 跨渠道诊断与修复流程。 + 跨渠道诊断和修复流程。 ## 快速设置 -你需要创建一个带机器人的新应用，将机器人添加到你的服务器，并将其与 OpenClaw 配对。我们建议把你的机器人添加到你自己的私人服务器。如果你还没有服务器，请先[创建一个](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server)（选择 **Create My Own > For me and my friends**）。 +你需要创建一个包含机器人的新应用，将机器人添加到你的服务器，并将其与 OpenClaw 配对。我们建议你把机器人添加到你自己的私有服务器。如果你还没有，请先[创建一个](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server)（选择 **Create My Own > For me and my friends**）。 - 前往 [Discord Developer Portal](https://discord.com/developers/applications)，点击 **New Application**。给它起一个类似 “OpenClaw” 的名字。 + 前往 [Discord Developer Portal](https://discord.com/developers/applications) 并点击 **New Application**。给它起一个像 “OpenClaw” 这样的名字。 - 点击侧边栏中的 **Bot**。将 **Username** 设置为你给 OpenClaw 智能体起的名称。 + 点击侧边栏中的 **Bot**。将 **Username** 设置为你对 OpenClaw 智能体的称呼。 - 仍然在 **Bot** 页面，向下滚动到 **Privileged Gateway Intents** 并启用： + 仍在 **Bot** 页面，向下滚动到 **Privileged Gateway Intents** 并启用： - **Message Content Intent**（必需） - - **Server Members Intent**（推荐；角色 allowlist 和名称到 ID 匹配所必需） + - **Server Members Intent**（推荐；角色 allowlist 和名称到 ID 匹配需要） - **Presence Intent**（可选；仅在需要状态更新时使用） - - 向上滚动回 **Bot** 页面并点击 **Reset Token**。 + + 回到 **Bot** 页面顶部，点击 **Reset Token**。 - 尽管名称如此，这一步会生成你的第一个令牌——并不会“重置”任何内容。 + 虽然名称如此，但这会生成你的第一个令牌——并不会真的“重置”任何内容。 - 复制该令牌并将其保存到某个地方。这就是你的 **Bot Token**，你很快就会用到它。 + 复制该令牌并保存到某处。这就是你的 **Bot Token**，你很快就会用到它。 - 点击侧边栏中的 **OAuth2**。你将生成一个带有正确权限的邀请 URL，用于将机器人添加到你的服务器。 + 点击侧边栏中的 **OAuth2**。你将生成一个带有正确权限的邀请 URL，以便将机器人添加到你的服务器。 向下滚动到 **OAuth2 URL Generator** 并启用： @@ -77,30 +77,30 @@ x-i18n: - Attach Files - Add Reactions（可选） - 复制底部生成的 URL，将其粘贴到浏览器中，选择你的服务器，然后点击 **Continue** 进行连接。现在你应该能在 Discord 服务器中看到你的机器人。 + 复制底部生成的 URL，粘贴到浏览器中，选择你的服务器，然后点击 **Continue** 进行连接。现在你应该能在 Discord 服务器中看到你的机器人。 - - 回到 Discord 应用中，你需要启用 Developer Mode，这样才能复制内部 ID。 + + 回到 Discord 应用中，你需要启用开发者模式，这样才能复制内部 ID。 - 1. 点击 **User Settings**（头像旁的齿轮图标）→ **Advanced** → 打开 **Developer Mode** + 1. 点击 **User Settings**（你头像旁边的齿轮图标）→ **Advanced** → 打开 **Developer Mode** 2. 在侧边栏中右键点击你的**服务器图标** → **Copy Server ID** 3. 右键点击你自己的**头像** → **Copy User ID** - 将你的 **Server ID** 和 **User ID** 与 Bot Token 一起保存——下一步你需要把这三项都发送给 OpenClaw。 + 将你的 **Server ID** 和 **User ID** 与 Bot Token 一起保存——你将在下一步把这三项都发送给 OpenClaw。 - + 为了让配对正常工作，Discord 需要允许你的机器人向你发送私信。右键点击你的**服务器图标** → **Privacy Settings** → 打开 **Direct Messages**。 - 这会允许服务器成员（包括机器人）向你发送私信。如果你想在 OpenClaw 中使用 Discord 私信，请保持此选项开启。如果你只打算使用服务器频道，则可以在完成配对后关闭私信。 + 这会允许服务器成员（包括机器人）向你发送私信。如果你想通过 Discord 私信使用 OpenClaw，请保持开启。如果你只打算使用服务器频道，可以在配对后关闭私信。 - - 你的 Discord bot token 是一个密钥（类似密码）。在给你的智能体发送消息之前，请先在运行 OpenClaw 的机器上设置它。 + + 你的 Discord 机器人令牌是机密信息（类似密码）。在给你的智能体发消息前，请先在运行 OpenClaw 的机器上设置它。 ```bash export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" @@ -110,7 +110,7 @@ openclaw config set channels.discord.enabled true --strict-json openclaw gateway ``` - 如果 OpenClaw 已经作为后台服务运行，请通过 OpenClaw Mac 应用重启它，或者停止并重新启动 `openclaw gateway run` 进程。 + 如果 OpenClaw 已作为后台服务运行，请通过 OpenClaw Mac 应用重启它，或停止并重新启动 `openclaw gateway run` 进程。 @@ -118,11 +118,11 @@ openclaw gateway - 在任何现有渠道（例如 Telegram）中与你的 OpenClaw 智能体聊天并告诉它。如果 Discord 是你的第一个渠道，请改用 CLI / config 标签页。 + 在任意现有渠道（例如 Telegram）中与你的 OpenClaw 智能体聊天并告诉它。如果 Discord 是你的第一个渠道，请改用 CLI / config 选项卡。 - > “我已经在配置中设置好了 Discord bot token。请用 User ID `` 和 Server ID `` 完成 Discord 设置。” + > “我已经在配置中设置好了 Discord 机器人令牌。请使用 User ID `` 和 Server ID `` 完成 Discord 设置。” - + 如果你更喜欢基于文件的配置，请设置： ```json5 @@ -140,13 +140,13 @@ openclaw gateway } ``` - 默认账户的环境变量回退： + 默认账户的环境变量后备值： ```bash DISCORD_BOT_TOKEN=... ``` - 支持明文 `token` 值。`channels.discord.token` 也支持 env/file/exec 提供商的 SecretRef 值。参见 [Secrets Management](/zh-CN/gateway/secrets)。 + 支持明文 `token` 值。`channels.discord.token` 也支持通过 env/file/exec 提供商使用 SecretRef 值。参见[密钥管理](/zh-CN/gateway/secrets)。 @@ -154,11 +154,11 @@ DISCORD_BOT_TOKEN=... - 等待 Gateway 网关启动运行，然后在 Discord 中向你的机器人发送私信。它会回复一个配对码。 + 等待 Gateway 网关运行后，在 Discord 中给你的机器人发送私信。它会回复一个配对码。 - 将配对码发送给你现有渠道中的智能体： + 在你现有的渠道中把配对码发给你的智能体： > “批准这个 Discord 配对码：``” @@ -174,23 +174,23 @@ openclaw pairing approve discord 配对码会在 1 小时后过期。 - 现在你应该可以通过私信在 Discord 中与你的智能体聊天了。 + 现在你应该可以通过 Discord 私信与你的智能体聊天了。 -令牌解析具有账户感知能力。配置中的令牌值优先于环境变量回退。`DISCORD_BOT_TOKEN` 仅用于默认账户。 -对于高级出站调用（message 工具 / channel 操作），显式的单次调用 `token` 会用于该次调用。这适用于发送和读取 / 探测类操作（例如 read/search/fetch/thread/pins/permissions）。账户策略 / 重试设置仍然来自活动运行时快照中所选的账户。 +令牌解析是账户感知的。配置中的令牌值优先于环境变量后备值。`DISCORD_BOT_TOKEN` 仅用于默认账户。 +对于高级出站调用（message 工具/渠道操作），显式的按次调用 `token` 仅用于该次调用。这适用于发送和读取/探测类操作（例如 read/search/fetch/thread/pins/permissions）。账户策略/重试设置仍来自活动运行时快照中选定的账户。 ## 推荐：设置服务器工作区 -在私信正常工作后，你可以将 Discord 服务器设置为一个完整工作区，其中每个频道都有自己的智能体会话和上下文。这非常适合只有你和机器人参与的私人服务器。 +当私信可用后，你可以把 Discord 服务器配置为一个完整工作区，其中每个频道都有自己的智能体会话和上下文。这对于只有你和机器人使用的私有服务器尤其推荐。 - - 这样你的智能体就可以在服务器上的任意频道中响应，而不仅仅是私信。 + + 这样你的智能体就可以在服务器的任意频道中响应，而不只是私信。 @@ -219,12 +219,12 @@ openclaw pairing approve discord - - 默认情况下，你的智能体只会在被 @ 提及时才在服务器频道中响应。对于私人服务器，你大概率会希望它响应每一条消息。 + + 默认情况下，你的智能体只会在被 @ 提及时才会在服务器频道中响应。对于私有服务器，你可能希望它对每条消息都做出回应。 - > “允许我的智能体在这个服务器中无需被 @ 提及也能响应” + > “允许我的智能体在这个服务器上无需被 @ 提及也能回复” 在你的 guild 配置中设置 `requireMention: false`： @@ -248,54 +248,54 @@ openclaw pairing approve discord - - 默认情况下，长期记忆（MEMORY.md）只会在私信会话中加载。Guild 频道不会自动加载 MEMORY.md。 + + 默认情况下，长期记忆（MEMORY.md）只会在私信会话中加载。服务器频道不会自动加载 MEMORY.md。 - > “当我在 Discord 频道中提问时，如果你需要来自 MEMORY.md 的长期上下文，请使用 memory_search 或 memory_get。” + > “当我在 Discord 频道里提问时，如果你需要来自 MEMORY.md 的长期上下文，请使用 memory_search 或 memory_get。” - 如果你需要在每个频道中共享上下文，请把稳定的说明写入 `AGENTS.md` 或 `USER.md`（它们会注入到每个会话中）。将长期笔记保存在 `MEMORY.md` 中，并在需要时通过 memory 工具访问。 + 如果你需要在每个频道中共享上下文，请将稳定说明放在 `AGENTS.md` 或 `USER.md` 中（它们会为每个会话注入）。把长期笔记保存在 `MEMORY.md` 中，并在需要时通过记忆工具访问。 -现在，在你的 Discord 服务器中创建一些频道并开始聊天吧。你的智能体可以看到频道名称，而且每个频道都会拥有自己隔离的会话——因此你可以设置 `#coding`、`#home`、`#research`，或任何适合你工作流的频道。 +现在就在你的 Discord 服务器上创建一些频道并开始聊天吧。你的智能体可以看到频道名称，而且每个频道都有自己隔离的会话——因此你可以设置 `#coding`、`#home`、`#research`，或者任何适合你工作流的频道。 ## 运行时模型 - Gateway 网关拥有 Discord 连接。 -- 回复路由是确定性的：来自 Discord 的入站回复会回到 Discord。 +- 回复路由是确定性的：来自 Discord 的入站回复会返回到 Discord。 - 默认情况下（`session.dmScope=main`），私聊共享智能体主会话（`agent:main:main`）。 -- Guild 频道使用隔离的会话键（`agent::discord:channel:`）。 -- 默认忽略群组私信（`channels.discord.dm.groupEnabled=false`）。 -- 原生斜杠命令在隔离的命令会话中运行（`agent::discord:slash:`），同时仍会将 `CommandTargetSessionKey` 携带到被路由的对话会话中。 +- 服务器频道使用隔离的会话键（`agent::discord:channel:`）。 +- 群组私信默认被忽略（`channels.discord.dm.groupEnabled=false`）。 +- 原生斜杠命令在隔离的命令会话中运行（`agent::discord:slash:`），同时仍会把 `CommandTargetSessionKey` 传递给被路由的对话会话。 -## Forum 频道 +## 论坛频道 -Discord forum 和 media 频道只接受主题帖。OpenClaw 支持两种创建方式： +Discord 论坛和媒体频道只接受主题帖。OpenClaw 支持两种创建方式： -- 向 forum 父级频道（`channel:`）发送消息以自动创建线程。线程标题将使用消息中的第一行非空内容。 -- 使用 `openclaw message thread create` 直接创建线程。对于 forum 频道，不要传递 `--message-id`。 +- 向论坛父级（`channel:`）发送消息以自动创建主题。主题标题使用你消息中的第一条非空行。 +- 使用 `openclaw message thread create` 直接创建主题。不要为论坛频道传递 `--message-id`。 -示例：发送到 forum 父级频道以创建线程 +示例：向论坛父级发送消息以创建主题 ```bash openclaw message send --channel discord --target channel: \ --message "Topic title\nBody of the post" ``` -示例：显式创建 forum 线程 +示例：显式创建论坛主题 ```bash openclaw message thread create --channel discord --target channel: \ --thread-name "Topic title" --message "Body of the post" ``` -Forum 父级频道不接受 Discord components。如果你需要 components，请发送到线程本身（`channel:`）。 +论坛父级不接受 Discord 组件。如果你需要组件，请发送到主题本身（`channel:`）。 ## 交互式组件 @@ -304,24 +304,24 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c 支持的块： - `text`、`section`、`separator`、`actions`、`media-gallery`、`file` -- 操作行最多允许 5 个按钮或单个选择菜单 +- 操作行最多允许 5 个按钮，或一个单独的选择菜单 - 选择类型：`string`、`user`、`role`、`mentionable`、`channel` -默认情况下，组件为单次使用。设置 `components.reusable=true` 可允许按钮、选择器和表单在过期前被多次使用。 +默认情况下，组件只能使用一次。设置 `components.reusable=true` 可允许按钮、选择器和表单在过期前被多次使用。 -如需限制谁可以点击按钮，请在该按钮上设置 `allowedUsers`（Discord 用户 ID、标签，或 `*`）。配置后，不匹配的用户会收到临时的拒绝提示。 +若要限制谁可以点击按钮，请在该按钮上设置 `allowedUsers`（Discord 用户 ID、标签或 `*`）。设置后，不匹配的用户会收到一条临时拒绝消息。 -`/model` 和 `/models` 斜杠命令会打开交互式模型选择器，包含 provider 和 model 下拉菜单以及一个提交步骤。选择器回复是临时的，且只有调用用户可以使用。 +`/model` 和 `/models` 斜杠命令会打开一个交互式模型选择器，其中包含提供商和模型下拉菜单以及一个提交步骤。选择器回复是临时的，且只有发起调用的用户可以使用。 文件附件： -- `file` 块必须指向一个附件引用（`attachment://`） -- 通过 `media`/`path`/`filePath` 提供附件（单文件）；多个文件请使用 `media-gallery` -- 当上传名称需要与附件引用一致时，使用 `filename` 覆盖上传名称 +- `file` 块必须指向附件引用（`attachment://`） +- 通过 `media`/`path`/`filePath` 提供附件（单个文件）；多个文件请使用 `media-gallery` +- 当上传名称需要与附件引用匹配时，使用 `filename` 覆盖上传名称 模态表单： -- 添加 `components.modal`，最多可包含 5 个字段 +- 添加 `components.modal`，最多支持 5 个字段 - 字段类型：`text`、`checkbox`、`radio`、`select`、`role-select`、`user-select` - OpenClaw 会自动添加一个触发按钮 @@ -379,7 +379,7 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c } ``` -## 访问控制与路由 +## 访问控制和路由 @@ -390,7 +390,7 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - `open`（要求 `channels.discord.allowFrom` 包含 `"*"`；旧版：`channels.discord.dm.allowFrom`） - `disabled` - 如果私信策略不是 open，未知用户会被阻止（或在 `pairing` 模式下提示进行配对）。 + 如果私信策略不是 open，未知用户将被阻止（或者在 `pairing` 模式下提示配对）。 多账户优先级： @@ -401,14 +401,14 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c 用于投递的私信目标格式： - `user:` - - `<@id>` 提及 + - `<@id>` mention - 纯数字 ID 存在歧义，除非显式提供 user/channel 目标类型，否则会被拒绝。 + 纯数字 ID 存在歧义，除非提供显式的用户/频道目标类型，否则会被拒绝。 - - Guild 处理由 `channels.discord.groupPolicy` 控制： + + guild 处理由 `channels.discord.groupPolicy` 控制： - `open` - `allowlist` @@ -419,9 +419,9 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c `allowlist` 行为： - guild 必须匹配 `channels.discord.guilds`（优先使用 `id`，也接受 slug） - - 可选的发送者 allowlist：`users`（推荐使用稳定 ID）和 `roles`（仅角色 ID）；如果配置了其中任意一个，则发送者在匹配 `users` 或 `roles` 时被允许 - - 直接名称 / 标签匹配默认禁用；仅在紧急兼容模式下启用 `channels.discord.dangerouslyAllowNameMatching: true` - - `users` 支持名称 / 标签，但 ID 更安全；当使用名称 / 标签条目时，`openclaw security audit` 会发出警告 + - 可选的发送者 allowlist：`users`（推荐使用稳定 ID）和 `roles`（仅角色 ID）；如果配置了任一项，则发送者只要匹配 `users` 或 `roles` 即可获准 + - 直接按名称/标签匹配默认禁用；仅在紧急兼容模式下启用 `channels.discord.dangerouslyAllowNameMatching: true` + - `users` 支持名称/标签，但 ID 更安全；当使用名称/标签条目时，`openclaw security audit` 会发出警告 - 如果某个 guild 配置了 `channels`，则未列出的频道会被拒绝 - 如果某个 guild 没有 `channels` 块，则该 allowlist guild 中的所有频道都被允许 @@ -449,33 +449,33 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c } ``` - 如果你只设置了 `DISCORD_BOT_TOKEN` 而没有创建 `channels.discord` 块，则运行时回退为 `groupPolicy="allowlist"`（日志中会有警告），即使 `channels.defaults.groupPolicy` 为 `open` 也是如此。 + 如果你只设置了 `DISCORD_BOT_TOKEN` 而没有创建 `channels.discord` 块，则运行时后备值为 `groupPolicy="allowlist"`（日志中会有警告），即使 `channels.defaults.groupPolicy` 为 `open` 也是如此。 - - Guild 消息默认受提及门控。 + + 默认情况下，服务器消息需要被提及才会触发。 提及检测包括： - 显式提及机器人 - - 配置的提及模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） - - 在受支持情况下的隐式回复机器人行为 + - 已配置的提及模式（`agents.list[].groupChat.mentionPatterns`，后备为 `messages.groupChat.mentionPatterns`） + - 在受支持场景中的隐式回复给机器人行为 - `requireMention` 按 guild / channel 配置（`channels.discord.guilds...`）。 - `ignoreOtherMentions` 可选择性丢弃提及了其他用户 / 角色但未提及机器人的消息（不包括 @everyone/@here）。 + `requireMention` 按 guild/频道配置（`channels.discord.guilds...`）。 + `ignoreOtherMentions` 可选择性丢弃那些提及了其他用户/角色但未提及机器人的消息（不包括 @everyone/@here）。 群组私信： - 默认：忽略（`dm.groupEnabled=false`） - - 可选 allowlist：通过 `dm.groupChannels`（频道 ID 或 slug） + - 可选：通过 `dm.groupChannels` 设置 allowlist（频道 ID 或 slug） ### 基于角色的智能体路由 -使用 `bindings[].match.roles` 按角色 ID 将 Discord guild 成员路由到不同智能体。基于角色的绑定仅接受角色 ID，评估顺序位于 peer 或 parent-peer 绑定之后、guild-only 绑定之前。如果某个绑定还设置了其他匹配字段（例如 `peer` + `guildId` + `roles`），则所有已配置字段都必须匹配。 +使用 `bindings[].match.roles` 可按角色 ID 将 Discord guild 成员路由到不同的智能体。基于角色的绑定仅接受角色 ID，并且在 peer 或 parent-peer 绑定之后、仅 guild 绑定之前进行评估。如果某个绑定还设置了其他匹配字段（例如 `peer` + `guildId` + `roles`），则所有已配置字段都必须匹配。 ```json5 { @@ -506,7 +506,7 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c 1. Discord Developer Portal -> **Applications** -> **New Application** 2. **Bot** -> **Add Bot** - 3. 复制 bot token + 3. 复制机器人令牌 @@ -516,16 +516,16 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - Message Content Intent - Server Members Intent（推荐） - Presence intent 是可选的，只有在你希望接收状态更新时才需要。如果只是设置机器人状态（`setPresence`），则不需要为成员启用状态更新。 + Presence intent 是可选的，只有在你想接收状态更新时才需要。如果只是设置机器人状态（`setPresence`），则不需要为成员启用状态更新。 - + OAuth URL 生成器： - scopes：`bot`、`applications.commands` - 典型的基线权限： + 典型基线权限： - View Channels - Send Messages @@ -539,24 +539,24 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - 启用 Discord Developer Mode，然后复制： + 启用 Discord 开发者模式，然后复制： - - server ID - - channel ID - - user ID + - 服务器 ID + - 频道 ID + - 用户 ID - 在 OpenClaw 配置中优先使用数字 ID，以便进行可靠的审计和探测。 + 在 OpenClaw 配置中，优先使用数字 ID，以获得可靠的审计和探测结果。 -## 原生命令与命令认证 +## 原生命令和命令鉴权 -- `commands.native` 默认为 `"auto"`，并为 Discord 启用。 -- 按渠道覆盖：`channels.discord.commands.native`。 +- `commands.native` 默认值为 `"auto"`，并且对 Discord 已启用。 +- 每渠道覆盖：`channels.discord.commands.native`。 - `commands.native=false` 会显式清除先前已注册的 Discord 原生命令。 -- 原生命令认证使用与普通消息处理相同的 Discord allowlist / 策略。 -- 即使用户未被授权，命令仍可能出现在 Discord UI 中；执行时仍会强制执行 OpenClaw 认证，并返回“未授权”。 +- 原生命令鉴权使用与普通消息处理相同的 Discord allowlist/策略。 +- 命令在 Discord UI 中仍可能对未授权用户可见；执行时仍会强制执行 OpenClaw 鉴权并返回“未授权”。 命令目录和行为请参见[斜杠命令](/zh-CN/tools/slash-commands)。 @@ -567,7 +567,7 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c ## 功能细节 - + Discord 支持在智能体输出中使用回复标签： - `[[reply_to_current]]` @@ -580,22 +580,22 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - `all` - `batched` - 注意：`off` 会禁用隐式回复线程。显式的 `[[reply_to_*]]` 标签仍会生效。 - `first` 会始终将隐式原生回复引用附加到该轮中的第一条 Discord 出站消息。 - `batched` 仅在入站轮次是多个消息去抖后组成的批次时，才会附加 Discord 的隐式原生回复引用。这适合你主要希望在存在歧义的突发聊天中使用原生回复，而不是每个单消息轮次都使用。 + 注意：`off` 会禁用隐式回复线程。显式的 `[[reply_to_*]]` 标签仍会被遵循。 + `first` 总是会将隐式原生回复引用附加到该轮次中第一条出站 Discord 消息上。 + `batched` 仅在入站轮次是由多条消息去抖后合并而成时，才附加 Discord 的隐式原生回复引用。这在你主要希望为模糊、密集的突发聊天使用原生回复，而不是为每个单消息轮次都使用时很有用。 - 消息 ID 会在上下文 / 历史中呈现，因此智能体可以定位特定消息。 + 消息 ID 会显示在上下文/历史中，以便智能体定位特定消息。 - OpenClaw 可以通过发送临时消息并在文本到达时持续编辑它来流式显示回复草稿。 + OpenClaw 可以通过发送一条临时消息并在文本到达时编辑它，来流式显示回复草稿。 - `channels.discord.streaming` 控制预览流式传输（`off` | `partial` | `block` | `progress`，默认：`off`）。 - - 默认保持为 `off`，因为 Discord 预览编辑很容易触发速率限制，尤其是多个机器人或 Gateway 网关共享同一账户或 guild 流量时。 - - 为了跨渠道一致性，接受 `progress`，并在 Discord 上映射为 `partial`。 - - `channels.discord.streamMode` 是旧别名，会自动迁移。 - - `partial` 会在 token 到达时编辑单条预览消息。 + - 默认保持 `off`，因为 Discord 预览编辑可能很快触发速率限制，尤其是在多个机器人或 Gateway 网关共享同一账户或服务器流量时。 + - `progress` 为了跨渠道一致性而被接受，在 Discord 上会映射为 `partial`。 + - `channels.discord.streamMode` 是旧版别名，会被自动迁移。 + - `partial` 会在 token 到达时编辑同一条预览消息。 - `block` 会输出草稿大小的分块（使用 `draftChunk` 调整大小和断点）。 示例： @@ -610,7 +610,7 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c } ``` - `block` 模式的分块默认值（会限制在 `channels.discord.textChunkLimit` 以内）： + `block` 模式的默认分块设置（会被限制在 `channels.discord.textChunkLimit` 以内）： ```json5 { @@ -629,15 +629,15 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c 预览流式传输仅支持文本；媒体回复会回退为普通投递。 - 注意：预览流式传输与分块流式传输是分开的。当为 Discord 显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免重复流式传输。 + 注意：预览流式传输与分块流式传输是分开的。当为 Discord 显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。 - - Guild 历史上下文： + + 服务器历史上下文： - `channels.discord.historyLimit` 默认值为 `20` - - 回退：`messages.groupChat.historyLimit` + - 后备值：`messages.groupChat.historyLimit` - `0` 表示禁用 私信历史控制： @@ -645,28 +645,28 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - `channels.discord.dmHistoryLimit` - `channels.discord.dms[""].historyLimit` - 线程行为： + 主题行为： - - Discord 线程会作为频道会话进行路由 - - 父线程元数据可用于父会话链接 - - 线程配置会继承父频道配置，除非存在线程专用条目 + - Discord 主题会作为频道会话路由 + - 父主题元数据可用于父会话链接 + - 主题配置会继承父频道配置，除非存在主题专用条目 - 频道主题会作为**不受信任**的上下文注入（而不是 system prompt）。 - 回复和引用消息上下文当前会按接收到的内容保持原样。 - Discord allowlist 主要用于控制谁可以触发智能体，并不是完整的补充上下文脱敏边界。 + 频道主题会作为**不受信任**的上下文注入（不是系统提示词）。 + 回复和引用消息上下文当前会保持接收时的原样。 + Discord allowlist 主要用于控制谁可以触发智能体，而不是完整的补充上下文脱敏边界。 - - Discord 可以将一个线程绑定到某个会话目标，使该线程中的后续消息持续路由到同一个会话（包括子智能体会话）。 + + Discord 可以将线程绑定到一个会话目标，这样该线程中的后续消息会持续路由到同一个会话（包括子智能体会话）。 命令： - - `/focus ` 将当前 / 新线程绑定到某个子智能体 / 会话目标 + - `/focus ` 将当前/新线程绑定到某个子智能体/会话目标 - `/unfocus` 移除当前线程绑定 - - `/agents` 显示活动运行和绑定状态 - - `/session idle ` 检查 / 更新聚焦绑定在无活动时的自动取消聚焦 - - `/session max-age ` 检查 / 更新聚焦绑定的硬性最大时长 + - `/agents` 显示活跃运行和绑定状态 + - `/session idle ` 查看/更新聚焦绑定的空闲自动取消聚焦设置 + - `/session max-age ` 查看/更新聚焦绑定的硬性最长存活时间 配置： @@ -685,7 +685,7 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // 选择启用 + spawnSubagentSessions: false, // 需要显式启用 }, }, }, @@ -695,21 +695,21 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c 说明： - `session.threadBindings.*` 设置全局默认值。 - - `channels.discord.threadBindings.*` 覆盖 Discord 行为。 - - `spawnSubagentSessions` 必须为 true，才能为 `sessions_spawn({ thread: true })` 自动创建 / 绑定线程。 - - `spawnAcpSessions` 必须为 true，才能为 ACP（`/acp spawn ... --thread ...` 或 `sessions_spawn({ runtime: "acp", thread: true })`）自动创建 / 绑定线程。 - - 如果某个账户禁用了线程绑定，则 `/focus` 以及相关线程绑定操作不可用。 + - `channels.discord.threadBindings.*` 会覆盖 Discord 行为。 + - `spawnSubagentSessions` 必须设为 true，才能为 `sessions_spawn({ thread: true })` 自动创建/绑定线程。 + - `spawnAcpSessions` 必须设为 true，才能为 ACP 自动创建/绑定线程（`/acp spawn ... --thread ...` 或 `sessions_spawn({ runtime: "acp", thread: true })`）。 + - 如果某个账户禁用了线程绑定，则 `/focus` 和相关线程绑定操作不可用。 - 参见[子智能体](/zh-CN/tools/subagents)、[ACP Agents](/zh-CN/tools/acp-agents) 和[配置参考](/zh-CN/gateway/configuration-reference)。 + 参见[子智能体](/zh-CN/tools/subagents)、[ACP 智能体](/zh-CN/tools/acp-agents)和[配置参考](/zh-CN/gateway/configuration-reference)。 - 对于稳定的“始终在线” ACP 工作区，可配置顶层的类型化 ACP 绑定，以目标为 Discord 对话。 + 对于稳定的“始终在线” ACP 工作区，可配置以 Discord 对话为目标的顶层类型化 ACP 绑定。 配置路径： - - `bindings[]`，其中 `type: "acp"` 且 `match.channel: "discord"` + - `bindings[]`，并设置 `type: "acp"` 和 `match.channel: "discord"` 示例： @@ -761,51 +761,51 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c 说明： - - `/acp spawn codex --bind here` 会将当前 Discord 频道或线程就地绑定，并使未来消息持续路由到同一个 ACP 会话。 - - 这仍然可能意味着“启动一个新的 Codex ACP 会话”，但它本身不会创建新的 Discord 线程。现有频道会继续作为聊天界面。 - - Codex 仍可能在其自己的 `cwd` 或磁盘上的 backend 工作区中运行。该工作区属于运行时状态，不是 Discord 线程。 + - `/acp spawn codex --bind here` 会将当前 Discord 频道或线程就地绑定，并让未来消息持续路由到同一个 ACP 会话。 + - 这仍可能意味着“启动一个全新的 Codex ACP 会话”，但它本身不会创建新的 Discord 线程。现有频道仍然是聊天界面。 + - Codex 仍可能在它自己的 `cwd` 或磁盘上的后端工作区中运行。该工作区是运行时状态，不是 Discord 线程。 - 线程消息可以继承父频道 ACP 绑定。 - - 在已绑定的频道或线程中，`/new` 和 `/reset` 会原地重置同一个 ACP 会话。 - - 临时线程绑定仍然可用，并且在激活时可以覆盖目标解析。 - - 只有当 OpenClaw 需要通过 `--thread auto|here` 创建 / 绑定子线程时，才需要 `spawnAcpSessions`。对于当前频道中的 `/acp spawn ... --bind here` 则不需要。 + - 在已绑定的频道或线程中，`/new` 和 `/reset` 会就地重置同一个 ACP 会话。 + - 临时线程绑定仍然有效，并且在激活期间可覆盖目标解析。 + - 只有当 OpenClaw 需要通过 `--thread auto|here` 创建/绑定子线程时，才需要 `spawnAcpSessions`。对于当前频道中的 `/acp spawn ... --bind here` 则不需要。 - 有关绑定行为的详细信息，请参见 [ACP Agents](/zh-CN/tools/acp-agents)。 + 绑定行为详情请参见[ACP 智能体](/zh-CN/tools/acp-agents)。 - - 每个 guild 的表情反应通知模式： + + 每个 guild 的反应通知模式： - `off` - `own`（默认） - `all` - `allowlist`（使用 `guilds..users`） - 表情反应事件会转换为系统事件，并附加到路由后的 Discord 会话中。 + 反应事件会转换为系统事件，并附加到被路由的 Discord 会话中。 - - `ackReaction` 会在 OpenClaw 处理入站消息期间发送一个确认表情。 + + `ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认表情。 解析顺序： - `channels.discord.accounts..ackReaction` - `channels.discord.ackReaction` - `messages.ackReaction` - - 智能体身份 emoji 回退（`agents.list[].identity.emoji`，否则为 “👀”） + - 智能体身份表情后备值（`agents.list[].identity.emoji`，否则为 "👀"） 说明： - - Discord 接受 unicode emoji 或自定义 emoji 名称。 - - 使用 `""` 可为某个渠道或账户禁用该表情反应。 + - Discord 接受 unicode 表情或自定义表情名称。 + - 使用 `""` 可为某个渠道或账户禁用该反应。 默认启用由渠道发起的配置写入。 - 这会影响 `/config set|unset` 流程（在启用命令功能时）。 + 这会影响 `/config set|unset` 流程（启用命令功能时）。 禁用： @@ -822,7 +822,7 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - 使用 `channels.discord.proxy` 通过 HTTP(S) 代理路由 Discord gateway WebSocket 流量和启动 REST 查询（应用 ID + allowlist 解析）。 + 使用 `channels.discord.proxy` 通过 HTTP(S) 代理路由 Discord Gateway 网关 WebSocket 流量和启动 REST 查询（应用 ID + allowlist 解析）。 ```json5 { @@ -834,7 +834,7 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c } ``` - 按账户覆盖： + 每账户覆盖： ```json5 { @@ -871,14 +871,14 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c 说明： - allowlist 可以使用 `pk:` - - 只有在 `channels.discord.dangerouslyAllowNameMatching: true` 时，才会按名称 / slug 匹配成员显示名 - - 查询使用原始消息 ID，且受时间窗口限制 + - 仅当 `channels.discord.dangerouslyAllowNameMatching: true` 时，成员显示名称才会按名称/slug 匹配 + - 查询使用原始消息 ID，并受时间窗口限制 - 如果查询失败，代理消息会被视为机器人消息并丢弃，除非 `allowBots=true` - - 当你设置状态或活动字段，或启用自动状态时，将应用状态更新。 + + 当你设置状态或活动字段，或启用自动在线状态时，会应用在线状态更新。 仅状态示例： @@ -905,7 +905,7 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c } ``` - 直播示例： + Streaming 示例： ```json5 { @@ -925,10 +925,10 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - 1：Streaming（需要 `activityUrl`） - 2：Listening - 3：Watching - - 4：Custom（使用活动文本作为状态内容；emoji 可选） + - 4：Custom（使用活动文本作为状态内容；表情可选） - 5：Competing - 自动状态示例（运行时健康信号）： + 自动在线状态示例（运行时健康信号）： ```json5 { @@ -945,7 +945,7 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c } ``` - 自动状态将运行时可用性映射为 Discord 状态：healthy => online，degraded 或 unknown => idle，exhausted 或 unavailable => dnd。可选文本覆盖： + 自动在线状态会将运行时可用性映射为 Discord 状态：健康 => online，降级或未知 => idle，耗尽或不可用 => dnd。可选文本覆盖项： - `autoPresence.healthyText` - `autoPresence.degradedText` @@ -953,8 +953,8 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - - Discord 支持在私信中使用基于按钮的审批处理，并可选择在源频道中发布审批提示。 + + Discord 支持在私信中基于按钮处理审批，并且可选择在发起来源频道中发布审批提示。 配置路径： @@ -963,58 +963,58 @@ OpenClaw 为智能体消息支持 Discord components v2 容器。使用带有 `c - `channels.discord.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`） - `agentFilter`、`sessionFilter`、`cleanupAfterResolve` - 当 `enabled` 未设置或为 `"auto"`，且至少能解析出一个 approver（来自 `execApprovals.approvers` 或 `commands.ownerAllowFrom`）时，Discord 会自动启用原生 exec approvals。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或私信 `defaultTo` 推断 exec approver。将 `enabled: false` 设置为显式禁用 Discord 作为原生审批客户端。 + 当 `enabled` 未设置或为 `"auto"`，并且至少可以解析出一个审批人（来自 `execApprovals.approvers` 或 `commands.ownerAllowFrom`）时，Discord 会自动启用原生 exec 审批。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或私信 `defaultTo` 推断 exec 审批人。若要显式禁用 Discord 作为原生审批客户端，请设置 `enabled: false`。 - 当 `target` 为 `channel` 或 `both` 时，审批提示会显示在频道中。只有已解析的 approver 能使用这些按钮；其他用户会收到临时拒绝提示。审批提示中包含命令文本，因此仅应在受信任频道中启用频道投递。如果无法从会话键派生频道 ID，OpenClaw 会回退为私信投递。 + 当 `target` 为 `channel` 或 `both` 时，审批提示会显示在频道中。只有已解析的审批人可以使用这些按钮；其他用户会收到临时拒绝消息。审批提示包含命令文本，因此只应在受信任频道中启用频道投递。如果无法从会话键推导出频道 ID，OpenClaw 会回退为私信投递。 - Discord 也会渲染其他聊天渠道共用的审批按钮。原生 Discord 适配器主要增加了 approver 私信路由和频道扇出。 - 当这些按钮存在时，它们就是主要的审批 UX；只有当工具结果表明聊天审批不可用，或手动审批是唯一途径时，OpenClaw 才应包含手动 `/approve` 命令。 + Discord 还会渲染其他聊天渠道共用的审批按钮。原生 Discord 适配器主要增加了审批人私信路由和频道扇出。 + 当存在这些按钮时，它们就是主要的审批 UX；只有当工具结果表明聊天审批不可用或手动审批是唯一途径时，OpenClaw 才应包含手动 `/approve` 命令。 - 该处理器的 Gateway 网关认证使用与其他 Gateway 客户端相同的共享凭证解析契约： + 此处理器的 Gateway 网关鉴权使用与其他 Gateway 客户端相同的共享凭证解析契约： - - env 优先的本地认证（`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`，然后是 `gateway.auth.*`） - - 在本地模式下，仅当 `gateway.auth.*` 未设置时，`gateway.remote.*` 才可用作回退；已配置但无法解析的本地 SecretRef 会以关闭失败的方式处理 - - 在适用时通过 `gateway.remote.*` 支持远程模式 - - URL 覆盖是覆盖安全的：CLI 覆盖不会复用隐式凭证，而环境变量覆盖只使用环境变量凭证 + - env 优先的本地鉴权（`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`，然后是 `gateway.auth.*`） + - 在本地模式下，仅当 `gateway.auth.*` 未设置时，`gateway.remote.*` 才可作为后备；已配置但无法解析的本地 SecretRef 会以失败关闭方式处理 + - 适用时通过 `gateway.remote.*` 支持远程模式 + - URL 覆盖对覆盖操作安全：CLI 覆盖不会重用隐式凭证，环境变量覆盖仅使用环境变量凭证 审批解析行为： - - 以 `plugin:` 为前缀的 ID 通过 `plugin.approval.resolve` 解析。 + - 带有 `plugin:` 前缀的 ID 通过 `plugin.approval.resolve` 解析。 - 其他 ID 通过 `exec.approval.resolve` 解析。 - - Discord 不会在这里额外进行从 exec 到 plugin 的回退跳转；ID 前缀决定它调用哪个 gateway 方法。 + - Discord 不会在这里额外执行一次 exec 到 plugin 的回退跳转；ID 前缀决定它调用哪种 Gateway 方法。 - Exec approvals 默认在 30 分钟后过期。如果审批因未知审批 ID 失败，请检查 approver 解析、功能启用状态，以及已投递的审批 ID 类型是否与待处理请求匹配。 + Exec 审批默认会在 30 分钟后过期。如果审批因未知审批 ID 而失败，请检查审批人解析、功能启用情况，以及已投递的审批 ID 类型是否与待处理请求匹配。 - 相关文档：[Exec approvals](/zh-CN/tools/exec-approvals) + 相关文档：[Exec 审批](/zh-CN/tools/exec-approvals) -## 工具与操作门控 +## 工具和操作门控 -Discord 消息操作包括消息处理、频道管理、审核、状态和元数据操作。 +Discord 消息操作包括消息传递、频道管理、审核、在线状态和元数据操作。 核心示例： -- 消息处理：`sendMessage`、`readMessages`、`editMessage`、`deleteMessage`、`threadReply` -- 表情反应：`react`、`reactions`、`emojiList` +- 消息传递：`sendMessage`、`readMessages`、`editMessage`、`deleteMessage`、`threadReply` +- 反应：`react`、`reactions`、`emojiList` - 审核：`timeout`、`kick`、`ban` -- 状态：`setPresence` +- 在线状态：`setPresence` 操作门控位于 `channels.discord.actions.*` 下。 默认门控行为： -| 操作组 | 默认值 | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | -| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | 已启用 | -| roles | 已禁用 | -| moderation | 已禁用 | -| presence | 已禁用 | +| 操作组 | 默认值 | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | +| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | enabled | +| roles | disabled | +| moderation | disabled | +| presence | disabled | ## Components v2 UI -OpenClaw 为 exec approvals 和跨上下文标记使用 Discord components v2。Discord 消息操作也可以接受 `components` 以构建自定义 UI（高级用法；需要通过 discord 工具构造组件负载），而旧版 `embeds` 仍可用，但不推荐使用。 +OpenClaw 对 exec 审批和跨上下文标记使用 Discord components v2。Discord 消息操作也可以接受 `components` 来构建自定义 UI（高级用法；需要通过 discord 工具构造组件负载），而旧版 `embeds` 仍然可用，但不推荐。 - `channels.discord.ui.components.accentColor` 设置 Discord 组件容器使用的强调色（hex）。 - 可按账户通过 `channels.discord.accounts..ui.components.accentColor` 设置。 @@ -1038,15 +1038,15 @@ OpenClaw 为 exec approvals 和跨上下文标记使用 Discord components v2。 ## 语音频道 -OpenClaw 可以加入 Discord 语音频道，以进行实时、连续的对话。这与语音消息附件不同。 +OpenClaw 可以加入 Discord 语音频道，以进行实时、连续的对话。这与语音消息附件是分开的。 要求： - 启用原生命令（`commands.native` 或 `channels.discord.commands.native`）。 - 配置 `channels.discord.voice`。 -- 机器人需要在目标语音频道中拥有 Connect 和 Speak 权限。 +- 机器人在目标语音频道中需要 Connect 和 Speak 权限。 -使用仅限 Discord 的原生命令 `/vc join|leave|status` 来控制会话。该命令使用账户默认智能体，并遵循与其他 Discord 命令相同的 allowlist 和 group policy 规则。 +使用 Discord 专用原生命令 `/vc join|leave|status` 来控制会话。该命令使用账户默认智能体，并遵循与其他 Discord 命令相同的 allowlist 和群组策略规则。 自动加入示例： @@ -1076,23 +1076,23 @@ OpenClaw 可以加入 Discord 语音频道，以进行实时、连续的对话 说明： -- `voice.tts` 仅对语音播放覆盖 `messages.tts`。 -- 语音转录轮次会根据 Discord `allowFrom`（或 `dm.allowFrom`）推导所有者状态；非所有者说话者无法访问仅所有者可用的工具（例如 `gateway` 和 `cron`）。 -- 默认启用语音；设置 `channels.discord.voice.enabled=false` 可禁用。 +- `voice.tts` 仅覆盖语音播放，不影响 `messages.tts`。 +- 语音转录轮次会根据 Discord `allowFrom`（或 `dm.allowFrom`）派生所有者状态；非所有者说话者无法访问仅所有者可用的工具（例如 `gateway` 和 `cron`）。 +- 语音默认启用；设置 `channels.discord.voice.enabled=false` 可禁用。 - `voice.daveEncryption` 和 `voice.decryptionFailureTolerance` 会直接传递给 `@discordjs/voice` 加入选项。 -- 如果未设置，`@discordjs/voice` 默认值为 `daveEncryption=true` 和 `decryptionFailureTolerance=24`。 -- OpenClaw 还会监控接收解密失败，并在短时间内多次失败后通过离开 / 重新加入语音频道来自动恢复。 -- 如果接收日志反复显示 `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`，这可能是上游 `@discordjs/voice` 接收问题，参见 [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419)。 +- 如果未设置，`@discordjs/voice` 的默认值为 `daveEncryption=true` 和 `decryptionFailureTolerance=24`。 +- OpenClaw 还会监视接收解密失败，并在短时间内重复失败后通过离开/重新加入语音频道自动恢复。 +- 如果接收日志持续显示 `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`，这可能是上游 `@discordjs/voice` 接收 bug，见 [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419)。 ## 语音消息 -Discord 语音消息会显示波形预览，并要求使用 OGG/Opus 音频及元数据。OpenClaw 会自动生成波形，但它需要在 Gateway 网关主机上提供 `ffmpeg` 和 `ffprobe`，以便检查并转换音频文件。 +Discord 语音消息会显示波形预览，并要求使用 OGG/Opus 音频及元数据。OpenClaw 会自动生成波形，但它需要在 Gateway 网关主机上可用的 `ffmpeg` 和 `ffprobe` 来检查和转换音频文件。 -要求与限制： +要求和限制： -- 提供**本地文件路径**（URL 会被拒绝）。 -- 不要包含文本内容（Discord 不允许在同一负载中同时发送文本和语音消息）。 -- 接受任意音频格式；OpenClaw 会在需要时将其转换为 OGG/Opus。 +- 提供**本地文件路径**（不接受 URL）。 +- 省略文本内容（Discord 不允许在同一负载中同时发送文本和语音消息）。 +- 接受任意音频格式；必要时 OpenClaw 会将其转换为 OGG/Opus。 示例： @@ -1103,20 +1103,20 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a ## 故障排除 - + - 启用 Message Content Intent - - 当你依赖用户 / 成员解析时，启用 Server Members Intent - - 更改 intents 后重启 gateway + - 当你依赖用户/成员解析时，启用 Server Members Intent + - 更改 intents 后重启 Gateway 网关 - + - - 验证 `groupPolicy` - - 验证 `channels.discord.guilds` 下的 guild allowlist - - 如果存在 guild `channels` 映射，则仅允许列出的频道 - - 验证 `requireMention` 行为和提及模式 + - 检查 `groupPolicy` + - 检查 `channels.discord.guilds` 下的 guild allowlist + - 如果存在 guild `channels` 映射，则只有列出的频道会被允许 + - 检查 `requireMention` 行为和提及模式 实用检查： @@ -1128,16 +1128,16 @@ openclaw logs --follow - + 常见原因： - - `groupPolicy="allowlist"`，但没有匹配的 guild / channel allowlist + - `groupPolicy="allowlist"` 但没有匹配的 guild/频道 allowlist - `requireMention` 配置在错误位置（必须位于 `channels.discord.guilds` 或频道条目下） - - 发送者被 guild / channel `users` allowlist 阻止 + - 发送者被 guild/频道 `users` allowlist 阻止 - + 典型日志： @@ -1145,12 +1145,12 @@ openclaw logs --follow - `Slow listener detected ...` - `discord inbound worker timed out after ...` - 监听器预算调节项： + 监听器预算旋钮： - 单账户：`channels.discord.eventQueue.listenerTimeout` - 多账户：`channels.discord.accounts..eventQueue.listenerTimeout` - Worker 运行超时调节项： + Worker 运行超时旋钮： - 单账户：`channels.discord.inboundWorker.runTimeoutMs` - 多账户：`channels.discord.accounts..inboundWorker.runTimeoutMs` @@ -1177,18 +1177,18 @@ openclaw logs --follow } ``` - 对于缓慢的监听器设置，请使用 `eventQueue.listenerTimeout`；仅当你希望为排队的智能体轮次设置单独的安全阀时，才使用 `inboundWorker.runTimeoutMs`。 + 对于较慢的监听器初始化，请使用 `eventQueue.listenerTimeout`；只有当你希望为排队中的智能体轮次设置单独安全阀时，才使用 `inboundWorker.runTimeoutMs`。 - `channels status --probe` 的权限检查仅适用于数字频道 ID。 + `channels status --probe` 权限检查仅对数字频道 ID 生效。 - 如果你使用 slug 键，运行时匹配仍然可能正常工作，但探测无法完整验证权限。 + 如果你使用 slug 键，运行时匹配仍然可以工作，但探测无法完整验证权限。 - + - 私信已禁用：`channels.discord.dm.enabled=false` - 私信策略已禁用：`channels.discord.dmPolicy="disabled"`（旧版：`channels.discord.dm.policy`） @@ -1196,23 +1196,23 @@ openclaw logs --follow - - 默认情况下，会忽略由机器人发送的消息。 + + 默认情况下，由机器人编写的消息会被忽略。 - 如果你设置了 `channels.discord.allowBots=true`，请使用严格的提及和 allowlist 规则来避免循环行为。 - 更推荐使用 `channels.discord.allowBots="mentions"`，仅接受那些提及机器人的机器人消息。 + 如果你设置了 `channels.discord.allowBots=true`，请使用严格的提及和 allowlist 规则以避免循环行为。 + 更推荐 `channels.discord.allowBots="mentions"`，这样只接受提及该机器人的机器人消息。 - + - 保持 OpenClaw 为最新版本（`openclaw update`），以确保包含 Discord 语音接收恢复逻辑 - 确认 `channels.discord.voice.daveEncryption=true`（默认） - 从 `channels.discord.voice.decryptionFailureTolerance=24`（上游默认）开始，仅在需要时调整 - - 观察日志中的以下内容： + - 观察日志中是否有： - `discord voice: DAVE decrypt failures detected` - `discord voice: repeated decrypt failures; attempting rejoin` - - 如果自动重新加入后仍持续失败，请收集日志并与 [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) 进行对比 + - 如果自动重新加入后仍持续失败，请收集日志并与 [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) 对照 @@ -1223,28 +1223,28 @@ openclaw logs --follow - [配置参考 - Discord](/zh-CN/gateway/configuration-reference#discord) -高价值 Discord 字段： +高信号的 Discord 字段： -- 启动 / 认证：`enabled`、`token`、`accounts.*`、`allowBots` +- 启动/鉴权：`enabled`、`token`、`accounts.*`、`allowBots` - 策略：`groupPolicy`、`dm.*`、`guilds.*`、`guilds.*.channels.*` - 命令：`commands.native`、`commands.useAccessGroups`、`configWrites`、`slashCommand.*` - 事件队列：`eventQueue.listenerTimeout`（监听器预算）、`eventQueue.maxQueueSize`、`eventQueue.maxConcurrency` - 入站 worker：`inboundWorker.runTimeoutMs` -- 回复 / 历史：`replyToMode`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` +- 回复/历史：`replyToMode`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` - 投递：`textChunkLimit`、`chunkMode`、`maxLinesPerMessage` -- 流式传输：`streaming`（旧别名：`streamMode`）、`draftChunk`、`blockStreaming`、`blockStreamingCoalesce` -- 媒体 / 重试：`mediaMaxMb`、`retry` - - `mediaMaxMb` 限制 Discord 出站上传大小（默认：`8MB`） +- 流式传输：`streaming`（旧版别名：`streamMode`）、`draftChunk`、`blockStreaming`、`blockStreamingCoalesce` +- 媒体/重试：`mediaMaxMb`、`retry` + - `mediaMaxMb` 限制 Discord 出站上传大小（默认：`100MB`） - 操作：`actions.*` -- 状态：`activity`、`status`、`activityType`、`activityUrl` +- 在线状态：`activity`、`status`、`activityType`、`activityUrl` - UI：`ui.components.accentColor` - 功能：`threadBindings`、顶层 `bindings[]`（`type: "acp"`）、`pluralkit`、`execApprovals`、`intents`、`agentComponents`、`heartbeat`、`responsePrefix` -## 安全与运维 +## 安全和运维 -- 将 bot token 视为密钥（在受监管环境中优先使用 `DISCORD_BOT_TOKEN`）。 -- 授予最小必要的 Discord 权限。 -- 如果命令部署 / 状态陈旧，请重启 gateway，并使用 `openclaw channels status --probe` 重新检查。 +- 将机器人令牌视为机密（在受监管环境中优先使用 `DISCORD_BOT_TOKEN`）。 +- 授予最小权限的 Discord 权限。 +- 如果命令部署/状态已过期，请重启 Gateway 网关，并使用 `openclaw channels status --probe` 重新检查。 ## 相关内容 diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index a874c183b..76f9f1ab7 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -5,52 +5,52 @@ read_when: summary: 每个 OpenClaw 配置键、默认值和渠道设置的完整参考 title: 配置参考 x-i18n: - generated_at: "2026-04-06T00:57:31Z" + generated_at: "2026-04-06T02:29:17Z" model: gpt-5.4 provider: openai - source_hash: fa402242dde4bee6e7f75f8fb9512e73df615a1a3693d6beec3153c3ad8a25d1 + source_hash: 266cbb43d9a4b4a3e8839dc8bc6c6d06382ecbbe33210c702f7699b47988123d source_path: gateway/configuration-reference.md workflow: 15 --- # 配置参考 -`~/.openclaw/openclaw.json` 中提供的每个字段。若需面向任务的概览，请参见 [Configuration](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 中可用的每个字段。关于面向任务的概览，请参见 [Configuration](/zh-CN/gateway/configuration)。 -配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的——省略时，OpenClaw 会使用安全的默认值。 +配置格式为 **JSON5**（允许注释 + 尾随逗号）。所有字段都是可选的——省略时，OpenClaw 会使用安全的默认值。 --- ## 渠道 -每个渠道只要其配置节存在，就会自动启动（除非设置了 `enabled: false`）。 +每个渠道在其配置段存在时都会自动启动（除非设置了 `enabled: false`）。 ### 私信和群组访问 所有渠道都支持私信策略和群组策略： -| 私信策略 | 行为 | -| -------------------- | --------------------------------------------------------------- | -| `pairing`（默认） | 未知发送者会收到一次性配对码；必须由 owner 批准 | -| `allowlist` | 仅允许 `allowFrom`（或已配对允许存储）中的发送者 | -| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） | -| `disabled` | 忽略所有传入私信 | +| 私信策略 | 行为 | +| ------------------- | -------------------------------------------------------------- | +| `pairing`（默认） | 未知发送者会收到一次性配对码；必须由所有者批准 | +| `allowlist` | 仅允许 `allowFrom`（或已配对允许存储）中的发送者 | +| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） | +| `disabled` | 忽略所有传入私信 | -| 群组策略 | 行为 | -| ----------------------- | ------------------------------------------------------ | -| `allowlist`（默认） | 仅允许与已配置允许列表匹配的群组 | -| `open` | 绕过群组允许列表（但仍会应用提及门控） | -| `disabled` | 阻止所有群组/房间消息 | +| 群组策略 | 行为 | +| --------------------- | ------------------------------------------------------ | +| `allowlist`（默认） | 仅允许匹配已配置允许列表的群组 | +| `open` | 绕过群组允许列表（仍会应用提及门控） | +| `disabled` | 阻止所有群组/房间消息 | -`channels.defaults.groupPolicy` 会在某个提供商的 `groupPolicy` 未设置时作为默认值。 -配对码会在 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 { @@ -71,9 +71,9 @@ x-i18n: } ``` -### 渠道默认值和心跳 +### 渠道默认值与心跳 -使用 `channels.defaults` 为各提供商共享群组策略和心跳行为： +使用 `channels.defaults` 为各提供商设置共享的群组策略和心跳行为： ```json5 { @@ -91,15 +91,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`：当提供商级 `groupPolicy` 未设置时使用的回退群组策略。 +- `channels.defaults.groupPolicy`：当提供商级 `groupPolicy` 未设置时的回退群组策略。 - `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。按渠道覆盖：`channels..contextVisibility`。 - `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康渠道状态。 - `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级/错误状态。 -- `channels.defaults.heartbeat.useIndicator`：以紧凑指示器样式渲染心跳输出。 +- `channels.defaults.heartbeat.useIndicator`：渲染紧凑的指示器样式心跳输出。 ### WhatsApp -WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已关联会话时会自动启动。 +WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在已关联的会话时会自动启动。 ```json5 { @@ -110,7 +110,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // 蓝色对勾（自聊模式下为 false） + sendReadReceipts: true, // 蓝色双勾（自聊模式下为 false） groups: { "*": { requireMention: true }, }, @@ -150,9 +150,9 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- 出站命令默认使用 `default` 账号（若存在）；否则使用第一个已配置的账号 ID（排序后）。 -- 可选的 `channels.whatsapp.defaultAccount` 可在匹配某个已配置账号 ID 时覆盖该回退默认账号选择。 -- 旧版单账号 Baileys 认证目录会被 `openclaw doctor` 迁移到 `whatsapp/default`。 +- 出站命令默认使用 `default` 账号（如果存在）；否则使用第一个已配置的账号 id（排序后）。 +- 可选的 `channels.whatsapp.defaultAccount` 会在其匹配已配置账号 id 时，覆盖该回退默认账号选择。 +- 旧版单账号 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 - 按账号覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -188,7 +188,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress（默认：off；明确启用以避免预览编辑速率限制） + streaming: "partial", // off | partial | block | progress（默认：off；需显式选择，以避免预览编辑速率限制） actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -211,10 +211,10 @@ 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 发起的配置写入（supergroup ID 迁移、`/config set|unset`）。 +- 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)。 @@ -227,7 +227,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 discord: { enabled: true, token: "your-bot-token", - mediaMaxMb: 8, + mediaMaxMb: 100, allowBots: false, actions: { reactions: true, @@ -272,7 +272,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress（在 Discord 上 progress 会映射为 partial） + streaming: "off", // off | partial | block | progress（在 Discord 上，progress 会映射为 partial） maxLinesPerMessage: 17, ui: { components: { @@ -283,7 +283,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // 为 sessions_spawn({ thread: true }) 选择性启用 + spawnSubagentSessions: false, // 为 `sessions_spawn({ thread: true })` 选择启用 }, voice: { enabled: true, @@ -319,36 +319,36 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- Token：`channels.discord.token`，默认账号还可回退到 `DISCORD_BOT_TOKEN`。 -- 直接出站调用若显式提供 Discord `token`，则该调用会使用该 token；账号重试/策略设置仍来自活动运行时快照中所选账号。 -- 可选的 `channels.discord.defaultAccount` 可在匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 对投递目标使用 `user:`（私信）或 `channel:`（服务器频道）；裸数字 ID 会被拒绝。 -- Guild slug 为小写，空格替换为 `-`；频道键使用 slug 化后的名称（不含 `#`）。优先使用 guild ID。 -- 默认会忽略由 bot 编写的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 仅接受提及该 bot 的 bot 消息（自身消息仍会被过滤）。 -- `channels.discord.guilds..ignoreOtherMentions`（以及频道级覆盖）会丢弃提及其他用户或角色但未提及该 bot 的消息（不含 @everyone/@here）。 -- `maxLinesPerMessage`（默认 17）即使在消息少于 2000 字符时，也会拆分过高的消息。 +- Token：`channels.discord.token`，默认账号可回退到 `DISCORD_BOT_TOKEN`。 +- 提供显式 Discord `token` 的直接出站调用会对此次调用使用该 token；账号级重试/策略设置仍来自当前运行时快照中选定的账号。 +- 可选的 `channels.discord.defaultAccount` 会在其匹配已配置账号 id 时覆盖默认账号选择。 +- 使用 `user:`（私信）或 `channel:`（服务器频道）作为投递目标；拒绝裸数字 ID。 +- 服务器 slug 使用小写并将空格替换为 `-`；频道键使用 slug 化名称（不含 `#`）。优先使用服务器 ID。 +- 默认会忽略机器人发布的消息。`allowBots: true` 可启用；使用 `allowBots: "mentions"` 则只接受提及该机器人的机器人消息（仍会过滤自身消息）。 +- `channels.discord.guilds..ignoreOtherMentions`（及频道级覆盖）会丢弃提及了其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。 +- `maxLinesPerMessage`（默认 17）即使在少于 2000 字符时，也会拆分过高的消息。 - `channels.discord.threadBindings` 控制 Discord 线程绑定路由： - - `enabled`：线程绑定会话功能的 Discord 覆盖（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 以及绑定投递/路由） - - `idleHours`：按小时设置的 Discord 覆盖型无活动自动取消聚焦（`0` 禁用） - - `maxAgeHours`：按小时设置的 Discord 覆盖型硬最大年龄（`0` 禁用） - - `spawnSubagentSessions`：为 `sessions_spawn({ thread: true })` 自动创建/绑定线程而选择启用的开关 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目会为频道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用 channel/thread id）。字段语义与 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 共享。 + - `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 还会在重复解密失败后通过离开/重新加入语音会话来尝试恢复语音接收。 -- `channels.discord.streaming` 是规范的流模式键。旧版 `streamMode` 和布尔型 `streaming` 值会自动迁移。 -- `channels.discord.autoPresence` 将运行时可用性映射到 bot presence（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。 -- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/tag 匹配（破窗兼容模式）。 +- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会直通到 `@discordjs/voice` 的 DAVE 选项（默认分别为 `true` 和 `24`）。 +- OpenClaw 还会在重复解密失败后，通过离开/重新加入语音会话来尝试恢复语音接收。 +- `channels.discord.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔值 `streaming` 会自动迁移。 +- `channels.discord.autoPresence` 将运行时可用性映射到机器人状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选状态文本覆盖。 +- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/标签匹配（紧急兼容模式）。 - `channels.discord.execApprovals`：Discord 原生 exec 审批投递和审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在 auto 模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，会激活 exec 审批。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在 auto 模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，会激活 exec 审批。 - `approvers`：允许批准 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。 - - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。 + - `agentFilter`：可选智能体 ID 允许列表。省略则为所有智能体转发审批。 - `sessionFilter`：可选会话键模式（子串或正则）。 - - `target`：审批提示发送位置。`"dm"`（默认）发送到审批人私信，`"channel"` 发送到发起频道，`"both"` 两者都发送。当目标包含 `"channel"` 时，按钮仅能由已解析出的审批人使用。 + - `target`：审批提示的发送位置。`"dm"`（默认）发送到审批人私信，`"channel"` 发送到来源频道，`"both"` 两者都发。当目标包含 `"channel"` 时，按钮仅对已解析的审批人可用。 - `cleanupAfterResolve`：为 `true` 时，在批准、拒绝或超时后删除审批私信。 -**反应通知模式：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（`guilds..users` 中的所有消息）。 +**反应通知模式：** `off`（无）、`own`（机器人自己的消息，默认）、`all`（所有消息）、`allowlist`（来自 `guilds..users`，适用于所有消息）。 ### Google Chat @@ -379,11 +379,11 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- 服务账号 JSON：可内联（`serviceAccount`）或使用文件（`serviceAccountFile`）。 +- 服务账号 JSON：可内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 - 也支持服务账号 SecretRef（`serviceAccountRef`）。 - 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 -- 对投递目标使用 `spaces/` 或 `users/`。 -- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变 email principal 匹配（破窗兼容模式）。 +- 使用 `spaces/` 或 `users/` 作为投递目标。 +- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变邮箱主体匹配（紧急兼容模式）。 ### Slack @@ -448,38 +448,33 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号的环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 -- **HTTP mode** 需要 `botToken` 加 `signingSecret`（在根级或按账号设置）。 -- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文 - 字符串或 SecretRef 对象。 -- Slack 账号快照会暴露按凭证划分的来源/状态字段，例如 - `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP mode 下的 - `signingSecretStatus`。`configured_unavailable` 表示该账号 - 通过 SecretRef 配置，但当前命令/运行时路径无法 - 解析出 secret 值。 -- `configWrites: false` 会阻止 Slack 发起的配置写入。 -- 可选的 `channels.slack.defaultAccount` 可在匹配某个已配置账号 ID 时覆盖默认账号选择。 -- `channels.slack.streaming` 是规范的流模式键。旧版 `streamMode` 和布尔型 `streaming` 值会自动迁移。 -- 对投递目标使用 `user:`（私信）或 `channel:`。 +- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 +- **HTTP mode** 需要 `botToken` 加 `signingSecret`（可在根级或按账号设置）。 +- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串或 SecretRef 对象。 +- Slack 账号快照会暴露按凭证划分的来源/状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式下的 `signingSecretStatus`。`configured_unavailable` 表示该账号通过 SecretRef 配置，但当前命令/运行时路径无法解析该 secret 值。 +- `configWrites: false` 会阻止由 Slack 发起的配置写入。 +- 可选的 `channels.slack.defaultAccount` 会在其匹配已配置账号 id 时覆盖默认账号选择。 +- `channels.slack.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔值 `streaming` 会自动迁移。 +- 使用 `user:`（私信）或 `channel:` 作为投递目标。 **反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -**线程会话隔离：** `thread.historyScope` 可设为每线程（默认）或在频道间共享。`thread.inheritParent` 会将父频道转录复制到新线程。 +**线程会话隔离：** `thread.historyScope` 为每线程（默认）或整个频道共享。`thread.inheritParent` 会将父频道转录复制到新线程中。 -- `typingReaction` 会在回复进行期间为传入的 Slack 消息添加临时 reaction，并在完成后移除。使用 Slack emoji 简码，例如 `"hourglass_flowing_sand"`。 -- `channels.slack.execApprovals`：Slack 原生 exec 审批投递和审批人授权。其 schema 与 Discord 相同：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 +- `typingReaction` 会在回复运行期间给传入的 Slack 消息临时添加一个 reaction，完成后移除。请使用 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"`）。 -| 操作组 | 默认值 | 说明 | -| ------------ | -------- | ---------------------- | -| reactions | 已启用 | React + 列出 reactions | -| messages | 已启用 | 读取/发送/编辑/删除 | -| pins | 已启用 | 固定/取消固定/列出 | -| memberInfo | 已启用 | 成员信息 | -| emojiList | 已启用 | 自定义 emoji 列表 | +| 操作组 | 默认值 | 说明 | +| ------------ | ------ | -------------------- | +| reactions | 启用 | 添加 reaction + 列表 | +| messages | 启用 | 读取/发送/编辑/删除 | +| pins | 启用 | 固定/取消固定/列表 | +| memberInfo | 启用 | 成员信息 | +| emojiList | 启用 | 自定义 emoji 列表 | ### Mattermost -Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermost`。 +Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost`。 ```json5 { @@ -499,7 +494,7 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos native: true, // 选择启用 nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // 反向代理/公网部署的可选显式 URL + // 可选：用于反向代理/公共部署的显式 URL callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -509,21 +504,19 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos } ``` -聊天模式：`oncall`（在 @ 提及时响应，默认）、`onmessage`（每条消息都响应）、`onchar`（以触发前缀开头的消息）。 +聊天模式：`oncall`（在 @ 提及时回复，默认）、`onmessage`（每条消息都回复）、`onchar`（以触发前缀开头的消息）。 -启用 Mattermost 原生命令时： +当启用 Mattermost 原生命令时： -- `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），不能是完整 URL。 +- `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），而不是完整 URL。 - `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器能够访问。 -- 原生 slash 回调会使用 Mattermost 在 slash 命令注册期间返回的每命令 token 进行认证。如果注册失败或没有激活命令，OpenClaw 会拒绝回调，并返回 - `Unauthorized: invalid command token.`。 -- 对于私有/tailnet/internal 回调主机，Mattermost 可能要求 - `ServiceSettings.AllowedUntrustedInternalConnections` 包含该回调主机/域名。 - 使用主机/域名值，不要使用完整 URL。 -- `channels.mattermost.configWrites`：允许或拒绝 Mattermost 发起的配置写入。 +- 原生斜杠命令回调使用 Mattermost 在斜杠命令注册期间返回的每命令 token 进行认证。如果注册失败或没有激活任何命令，OpenClaw 会拒绝回调，并返回 `Unauthorized: invalid command token.`。 +- 对于私有/tailnet/内部回调主机，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机/域名。 + 请使用主机/域名值，而不是完整 URL。 +- `channels.mattermost.configWrites`：允许或拒绝由 Mattermost 发起的配置写入。 - `channels.mattermost.requireMention`：在频道中回复前要求 `@mention`。 -- `channels.mattermost.groups..requireMention`：按频道覆盖提及门控（`"*"` 表示默认）。 -- 可选的 `channels.mattermost.defaultAccount` 可在匹配某个已配置账号 ID 时覆盖默认账号选择。 +- `channels.mattermost.groups..requireMention`：按频道设置的提及门控覆盖（`"*"` 用作默认值）。 +- 可选的 `channels.mattermost.defaultAccount` 会在其匹配已配置账号 id 时覆盖默认账号选择。 ### Signal @@ -546,13 +539,13 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos **反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -- `channels.signal.account`：将渠道启动固定到特定 Signal 账号身份。 -- `channels.signal.configWrites`：允许或拒绝 Signal 发起的配置写入。 -- 可选的 `channels.signal.defaultAccount` 可在匹配某个已配置账号 ID 时覆盖默认账号选择。 +- `channels.signal.account`：将渠道启动固定到特定的 Signal 账号身份。 +- `channels.signal.configWrites`：允许或拒绝由 Signal 发起的配置写入。 +- 可选的 `channels.signal.defaultAccount` 会在其匹配已配置账号 id 时覆盖默认账号选择。 ### BlueBubbles -BlueBubbles 是推荐的 iMessage 路径（插件支持，配置在 `channels.bluebubbles` 下）。 +BlueBubbles 是推荐的 iMessage 路径（基于插件，在 `channels.bluebubbles` 下配置）。 ```json5 { @@ -568,13 +561,13 @@ BlueBubbles 是推荐的 iMessage 路径（插件支持，配置在 `channels.bl ``` - 这里涵盖的核心键路径：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 -- 可选的 `channels.bluebubbles.defaultAccount` 可在匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目可以将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 -- 完整 BlueBubbles 渠道配置记录在 [BlueBubbles](/zh-CN/channels/bluebubbles) 中。 +- 可选的 `channels.bluebubbles.defaultAccount` 会在其匹配已配置账号 id 时覆盖默认账号选择。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目可将 BlueBubbles 会话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- 完整的 BlueBubbles 渠道配置记录于 [BlueBubbles](/zh-CN/channels/bluebubbles)。 ### iMessage -OpenClaw 会生成 `imsg rpc`（通过 stdio 进行 JSON-RPC）。不需要守护进程或端口。 +OpenClaw 会生成 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护进程或端口。 ```json5 { @@ -598,17 +591,17 @@ OpenClaw 会生成 `imsg rpc`（通过 stdio 进行 JSON-RPC）。不需要守 } ``` -- 可选的 `channels.imessage.defaultAccount` 可在匹配某个已配置账号 ID 时覆盖默认账号选择。 +- 可选的 `channels.imessage.defaultAccount` 会在其匹配已配置账号 id 时覆盖默认账号选择。 -- 需要对 Messages DB 授予 Full Disk Access。 +- 需要对 Messages 数据库授予 Full Disk Access。 - 优先使用 `chat_id:` 目标。使用 `imsg chats --limit 20` 列出聊天。 -- `cliPath` 可指向 SSH wrapper；为 SCP 附件抓取设置 `remoteHost`（`host` 或 `user@host`）。 +- `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)。 +- `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)。 - + ```bash #!/usr/bin/env bash @@ -619,7 +612,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix 由扩展提供支持，配置在 `channels.matrix` 下。 +Matrix 由扩展提供，并在 `channels.matrix` 下配置。 ```json5 { @@ -650,23 +643,23 @@ Matrix 由扩展提供支持，配置在 `channels.matrix` 下。 ``` - Token 认证使用 `accessToken`；密码认证使用 `userId` + `password`。 -- `channels.matrix.proxy` 通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账号可通过 `channels.matrix.accounts..proxy` 覆盖它。 -- `channels.matrix.allowPrivateNetwork` 允许私有/internal homeserver。`proxy` 和 `allowPrivateNetwork` 是彼此独立的控制项。 -- `channels.matrix.defaultAccount` 在多账号配置中选择首选账号。 +- `channels.matrix.proxy` 会将 Matrix HTTP 流量路由到显式 HTTP(S) 代理。命名账号可以用 `channels.matrix.accounts..proxy` 覆盖。 +- `channels.matrix.allowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 和 `allowPrivateNetwork` 是彼此独立的控制项。 +- `channels.matrix.defaultAccount` 在多账号设置中选择首选账号。 - `channels.matrix.execApprovals`：Matrix 原生 exec 审批投递和审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在 auto 模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，会激活 exec 审批。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在 auto 模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，会激活 exec 审批。 - `approvers`：允许批准 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。 - - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。 + - `agentFilter`：可选智能体 ID 允许列表。省略则为所有智能体转发审批。 - `sessionFilter`：可选会话键模式（子串或正则）。 - - `target`：审批提示发送位置。`"dm"`（默认）、`"channel"`（发起房间）或 `"both"`。 + - `target`：审批提示的发送位置。`"dm"`（默认）、`"channel"`（来源房间）或 `"both"`。 - 按账号覆盖：`channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何分组到会话中：`per-user`（默认）按路由对等方共享，而 `per-room` 会隔离每个私信房间。 -- Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。 -- 完整的 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,11 +675,11 @@ Microsoft Teams 由扩展提供支持，配置在 `channels.msteams` 下。 ``` - 这里涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。 -- 完整 Teams 配置（凭证、webhook、私信/群组策略、按团队/按频道覆盖）记录在 [Microsoft Teams](/zh-CN/channels/msteams) 中。 +- 完整的 Teams 配置（凭证、webhook、私信/群组策略、按团队/频道覆盖）记录于 [Microsoft Teams](/zh-CN/channels/msteams)。 ### IRC -IRC 由扩展提供支持，配置在 `channels.irc` 下。 +IRC 由扩展提供，并在 `channels.irc` 下配置。 ```json5 { @@ -708,12 +701,12 @@ IRC 由扩展提供支持，配置在 `channels.irc` 下。 ``` - 这里涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 -- 可选的 `channels.irc.defaultAccount` 可在匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 完整 IRC 渠道配置（host/port/TLS/频道/允许列表/提及门控）记录在 [IRC](/zh-CN/channels/irc) 中。 +- 可选的 `channels.irc.defaultAccount` 会在其匹配已配置账号 id 时覆盖默认账号选择。 +- 完整的 IRC 渠道配置（主机/端口/TLS/频道/允许列表/提及门控）记录于 [IRC](/zh-CN/channels/irc)。 ### 多账号（所有渠道） -每个渠道可运行多个账号（每个都有自己的 `accountId`）： +在每个渠道运行多个账号（每个都有自己的 `accountId`）： ```json5 { @@ -734,28 +727,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 则可以保留现有匹配的命名/default 目标。 +- 现有仅按渠道绑定（无 `accountId`）仍会匹配默认账号；账号范围绑定仍是可选的。 +- `openclaw doctor --fix` 也会通过将账号范围的顶层单账号值移动到该渠道所选择的提升账号中来修复混合结构。大多数渠道使用 `accounts.default`；Matrix 则可以保留现有匹配的命名/default 目标。 ### 其他扩展渠道 -许多扩展渠道使用 `channels.` 进行配置，并在各自专属渠道页面中记录（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 +许多扩展渠道配置为 `channels.`，并记录于各自专属的渠道页面中（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 请参见完整渠道索引：[Channels](/zh-CN/channels)。 ### 群聊提及门控 -群组消息默认**需要提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 +群组消息默认 **要求提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 **提及类型：** -- **元数据提及**：原生平台 @ 提及。在 WhatsApp 自聊模式下会被忽略。 -- **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 -- 仅当检测可能时（存在原生提及或至少一个模式）才会强制执行提及门控。 +- **元数据提及**：平台原生 @ 提及。在 WhatsApp 自聊模式中会被忽略。 +- **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 +- 只有在可检测到提及时（原生提及或至少一个模式），才会强制执行提及门控。 ```json5 { @@ -768,7 +761,7 @@ IRC 由扩展提供支持，配置在 `channels.irc` 下。 } ``` -`messages.groupChat.historyLimit` 设置全局默认值。渠道可通过 `channels..historyLimit`（或按账号）覆盖。设置为 `0` 可禁用。 +`messages.groupChat.historyLimit` 设置全局默认值。渠道可以用 `channels..historyLimit`（或按账号）覆盖。设置为 `0` 可禁用。 #### 私信历史限制 @@ -785,13 +778,13 @@ IRC 由扩展提供支持，配置在 `channels.irc` 下。 } ``` -解析顺序：按私信覆盖 → 提供商默认值 → 无限制（全部保留）。 +解析顺序：按私信覆盖 → 提供商默认值 → 不限制（全部保留）。 支持：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 #### 自聊模式 -将你自己的号码包含在 `allowFrom` 中即可启用自聊模式（忽略原生 @ 提及，仅响应文本模式）： +将你自己的号码加入 `allowFrom` 以启用自聊模式（忽略原生 @ 提及，仅响应文本模式）： ```json5 { @@ -812,18 +805,18 @@ IRC 由扩展提供支持，配置在 `channels.irc` 下。 } ``` -### 命令（聊天命令处理） +### Commands（聊天命令处理） ```json5 { commands: { - native: "auto", // 在支持的平台上注册原生命令 + native: "auto", // 在支持时注册原生命令 text: true, // 解析聊天消息中的 /commands bash: false, // 允许 !（别名：/bash） bashForegroundMs: 2000, config: false, // 允许 /config debug: false, // 允许 /debug - restart: false, // 允许 /restart + Gateway 网关重启工具 + restart: false, // 允许 /restart + gateway restart 工具 allowFrom: { "*": ["user1"], discord: ["user:123"], @@ -836,15 +829,15 @@ IRC 由扩展提供支持，配置在 `channels.irc` 下。 - 文本命令必须是带前导 `/` 的**独立**消息。 -- `native: "auto"` 会为 Discord/Telegram 打开原生命令，而保留 Slack 为关闭状态。 -- 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除先前已注册的命令。 -- `channels.telegram.customCommands` 会添加额外的 Telegram bot 菜单项。 -- `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 客户端使用。 +- `native: "auto"` 会为 Discord/Telegram 开启原生命令，对 Slack 保持关闭。 +- 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除之前已注册的命令。 +- `channels.telegram.customCommands` 会添加额外的 Telegram 机器人菜单项。 +- `bash: true` 启用宿主 Shell 的 `! `。要求 `tools.elevated.enabled`，且发送者位于 `tools.elevated.allowFrom.` 中。 +- `config: true` 启用 `/config`（读取/写入 `openclaw.json`）。对于 gateway `chat.send` 客户端，持久化的 `/config set|unset` 写入还要求 `operator.admin`；只读的 `/config show` 仍对普通写权限 operator 客户端可用。 - `channels..configWrites` 控制每个渠道的配置变更（默认：true）。 -- 对多账号渠道，`channels..accounts..configWrites` 也会控制针对该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 -- `allowFrom` 是按提供商设置的。设置后，它将成为**唯一**授权来源（渠道允许列表/配对 和 `useAccessGroups` 会被忽略）。 -- 当 `allowFrom` 未设置时，`useAccessGroups: false` 允许命令绕过访问组策略。 +- 对于多账号渠道，`channels..accounts..configWrites` 也会控制针对该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 +- `allowFrom` 按提供商设置。设置后，它将成为**唯一**授权来源（渠道允许列表/配对以及 `useAccessGroups` 都会被忽略）。 +- `useAccessGroups: false` 允许在未设置 `allowFrom` 时，命令绕过 access-group 策略。 @@ -864,7 +857,7 @@ IRC 由扩展提供支持，配置在 `channels.irc` 下。 ### `agents.defaults.repoRoot` -可选的仓库根目录，会显示在系统提示的 Runtime 行中。未设置时，OpenClaw 会从 workspace 向上遍历自动检测。 +可选的仓库根目录，会显示在系统提示词的 Runtime 行中。如果未设置，OpenClaw 会从工作区向上遍历自动检测。 ```json5 { @@ -874,8 +867,7 @@ IRC 由扩展提供支持，配置在 `channels.irc` 下。 ### `agents.defaults.skills` -可选的默认 Skills 允许列表，适用于未设置 -`agents.list[].skills` 的智能体。 +为未设置 `agents.list[].skills` 的智能体提供可选的默认 Skills 允许列表。 ```json5 { @@ -890,14 +882,14 @@ IRC 由扩展提供支持，配置在 `channels.irc` 下。 } ``` -- 省略 `agents.defaults.skills`，默认对 Skills 不做限制。 -- 省略 `agents.list[].skills` 以继承默认值。 +- 省略 `agents.defaults.skills`，则默认 Skills 不受限制。 +- 省略 `agents.list[].skills`，则继承默认值。 - 设置 `agents.list[].skills: []` 表示无 Skills。 - 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；不会与默认值合并。 ### `agents.defaults.skipBootstrap` -禁用自动创建 workspace 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 { @@ -907,7 +899,7 @@ IRC 由扩展提供支持，配置在 `channels.irc` 下。 ### `agents.defaults.bootstrapMaxChars` -每个 workspace bootstrap 文件在截断前的最大字符数。默认值：`20000`。 +每个工作区 bootstrap 文件在截断前允许的最大字符数。默认值：`20000`。 ```json5 { @@ -917,7 +909,7 @@ IRC 由扩展提供支持，配置在 `channels.irc` 下。 ### `agents.defaults.bootstrapTotalMaxChars` -所有 workspace bootstrap 文件注入总字符数的上限。默认值：`150000`。 +注入所有工作区 bootstrap 文件的总最大字符数。默认值：`150000`。 ```json5 { @@ -927,12 +919,12 @@ IRC 由扩展提供支持，配置在 `channels.irc` 下。 ### `agents.defaults.bootstrapPromptTruncationWarning` -控制 bootstrap 上下文被截断时，对智能体可见的警告文本。 +控制在 bootstrap 上下文被截断时，向智能体显示的警告文本。 默认值：`"once"`。 -- `"off"`：永不在系统提示中注入警告文本。 -- `"once"`：每个唯一截断签名只注入一次警告（推荐）。 -- `"always"`：只要存在截断，每次运行都注入警告。 +- `"off"`：绝不将警告文本注入系统提示词。 +- `"once"`：针对每个唯一截断签名仅注入一次警告（推荐）。 +- `"always"`：存在截断时，每次运行都注入警告。 ```json5 { @@ -942,11 +934,11 @@ IRC 由扩展提供支持，配置在 `channels.irc` 下。 ### `agents.defaults.imageMaxDimensionPx` -在调用提供商之前，转录/工具图像块中图像最长边的最大像素尺寸。 +在调用提供商前，转录/工具图像块中图像最长边的最大像素尺寸。 默认值：`1200`。 -更低的值通常会减少视觉 token 用量和请求负载大小，尤其适用于大量截图的运行。 -更高的值可保留更多视觉细节。 +较低的值通常会减少视觉 token 使用量和请求负载大小，尤其适合大量截图的运行。 +较高的值可保留更多视觉细节。 ```json5 { @@ -956,7 +948,7 @@ IRC 由扩展提供支持，配置在 `channels.irc` 下。 ### `agents.defaults.userTimezone` -用于系统提示上下文的时区（不影响消息时间戳）。会回退到主机时区。 +系统提示词上下文使用的时区（不影响消息时间戳）。会回退到宿主机时区。 ```json5 { @@ -966,7 +958,7 @@ IRC 由扩展提供支持，配置在 `channels.irc` 下。 ### `agents.defaults.timeFormat` -系统提示中的时间格式。默认值：`auto`（操作系统偏好）。 +系统提示词中的时间格式。默认值：`auto`（操作系统偏好）。 ```json5 { @@ -1004,7 +996,7 @@ IRC 由扩展提供支持，配置在 `channels.irc` 下。 primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // 全局默认 provider 参数 + params: { cacheRetention: "long" }, // 全局默认提供商参数 pdfMaxBytesMb: 10, pdfMaxPages: 20, thinkingDefault: "low", @@ -1020,40 +1012,40 @@ IRC 由扩展提供支持，配置在 `channels.irc` 下。 ``` - `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 字符串形式仅设置主模型。 + - 字符串形式只设置主模型。 - 对象形式设置主模型以及有序故障转移模型。 - `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 被 `image` 工具路径用作其视觉模型配置。 - - 当选定/默认模型无法接受图像输入时，也会用作回退路由。 + - 被 `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 顺序尝试剩余已注册的图像生成提供商。 + - 用于共享图像生成能力，以及任何未来生成图像的工具/插件接口。 + - 典型值：用于原生 Gemini 图像生成的 `google/gemini-3.1-flash-image-preview`，用于 fal 的 `fal/fal-ai/flux/dev`，或用于 OpenAI Images 的 `openai/gpt-image-1`。 + - 如果你直接选择某个 provider/model，也请配置相应的提供商认证/API key（例如 `google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 使用 `OPENAI_API_KEY`，`fal/*` 使用 `FAL_KEY`）。 + - 如果省略，`image_generate` 仍可推断一个具备认证的提供商默认值。它会先尝试当前默认提供商，再按 provider-id 顺序尝试其余已注册的图像生成提供商。 - `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 被共享音乐生成能力和内置 `music_generate` 工具使用。 + - 用于共享音乐生成能力和内置 `music_generate` 工具。 - 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。 - - 如果省略，`music_generate` 仍可推断出有凭证支持的 provider 默认值。它会先尝试当前默认 provider，然后按 provider-id 顺序尝试剩余已注册的音乐生成提供商。 - - 如果你直接选择 provider/model，请一并配置对应的 provider 凭证/API key。 + - 如果省略，`music_generate` 仍可推断一个具备认证的提供商默认值。它会先尝试当前默认提供商，再按 provider-id 顺序尝试其余已注册的音乐生成提供商。 + - 如果你直接选择某个 provider/model，也请配置相应的提供商认证/API key。 - `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 被共享视频生成能力和内置 `video_generate` 工具使用。 + - 用于共享视频生成能力和内置 `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/model，请一并配置对应的 provider 凭证/API key。 - - 内置的 Qwen 视频生成 provider 当前最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及 provider 级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 + - 如果省略，`video_generate` 仍可推断一个具备认证的提供商默认值。它会先尝试当前默认提供商，再按 provider-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` 工具中，用于提取回退模式时考虑的默认最大页数。 + - 用于 `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 会先尝试别名，再尝试唯一配置的 provider 中与该精确模型 id 匹配的项，最后才回退到已配置的默认 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` 和故障转移 add/remove 命令）会保存规范对象形式，并在可能时保留现有的故障转移列表。 -- `maxConcurrent`：跨会话并行智能体运行的最大数量（每个会话内部仍串行）。默认值：4。 +- `elevatedDefault`：智能体的默认 elevated-output 级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 +- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果省略 provider，OpenClaw 会先尝试别名，然后尝试唯一匹配已配置提供商中该精确模型 id 的项，最后才回退到已配置默认提供商（这是已弃用的兼容行为，因此推荐显式使用 `provider/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置 provider/model，而不是暴露一个过期的、已移除提供商默认值。 +- `models`：为 `/model` 提供已配置模型目录和允许列表。每个条目可包含 `alias`（快捷名）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 +- `params`：应用到所有模型的全局默认提供商参数。设置于 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 +- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配智能体 id）按键覆盖。详情见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 +- 修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 和回退添加/删除命令）会保存规范对象形式，并尽可能保留现有回退列表。 +- `maxConcurrent`：跨会话并行智能体运行的最大数量（每个会话本身仍串行）。默认值：4。 **内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）： @@ -1070,8 +1062,8 @@ IRC 由扩展提供支持，配置在 `channels.irc` 下。 你自己配置的别名始终优先于默认值。 -Z.AI GLM-4.x 模型会自动启用 thinking 模式，除非你设置了 `--thinking off` 或自行定义 `agents.defaults.models["zai/"].params.thinking`。 -Z.AI 模型默认启用 `tool_stream` 用于工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设为 `false` 可禁用它。 +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。 - 当设置了 `sessionArg` 时支持会话。 @@ -1089,8 +1081,8 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 every: "30m", // 0m 禁用 model: "openai/gpt-5.4-mini", includeReasoning: false, - lightContext: false, // 默认：false；true 时仅保留 workspace bootstrap 文件中的 HEARTBEAT.md - isolatedSession: false, // 默认：false；true 时每次心跳都在新会话中运行（无对话历史） + lightContext: false, // 默认：false；true 时仅保留工作区 bootstrap 文件中的 HEARTBEAT.md + isolatedSession: false, // 默认：false；true 时每次心跳在全新会话中运行（无对话历史） session: "main", to: "+15555550123", directPolicy: "allow", // allow（默认）| block @@ -1104,13 +1096,13 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API-key 认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。 +- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。 - `suppressToolErrorWarnings`：为 true 时，在心跳运行期间抑制工具错误警告负载。 -- `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 会抑制直接目标投递，并输出 `reason=dm-blocked`。 -- `lightContext`：为 true 时，心跳运行使用轻量 bootstrap 上下文，并仅保留 workspace bootstrap 文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：为 true 时，每次心跳都在没有任何既有对话历史的新会话中运行。隔离模式与 cron 的 `sessionTarget: "isolated"` 相同。可将单次心跳 token 成本从约 100K 降至约 2-5K。 -- 按智能体设置：使用 `agents.list[].heartbeat`。如果任意智能体定义了 `heartbeat`，则**只有这些智能体**会运行心跳。 -- 心跳会运行完整智能体回合——更短的间隔会消耗更多 token。 +- `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。 ### `agents.defaults.compaction` @@ -1124,9 +1116,9 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // 当 identifierPolicy=custom 时使用 - postCompactionSections: ["Session Startup", "Red Lines"], // [] 禁用重新注入 + postCompactionSections: ["Session Startup", "Red Lines"], // [] 可禁用重新注入 model: "openrouter/anthropic/claude-sonnet-4-6", // 可选，仅用于 compaction 的模型覆盖 - notifyUser: true, // compaction 开始时向用户发送简短通知（默认：false） + notifyUser: true, // compaction 开始时发送简短通知（默认：false） memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -1139,14 +1131,14 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `mode`：`default` 或 `safeguard`（对长历史执行分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `timeoutSeconds`：OpenClaw 中止前，单次 compaction 操作允许的最大秒数。默认值：`900`。 -- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预置内置的不透明标识符保留指引。 -- `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。 -- `postCompactionSections`：compaction 后重新注入的可选 AGENTS.md H2/H3 章节名。默认值为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。未设置或显式设置为该默认对时，旧版 `Every Session`/`Safety` 标题也会作为兼容回退被接受。 -- `model`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。当主会话应继续使用某个模型，而 compaction 摘要应切换到另一个模型时使用；未设置时，compaction 使用会话主模型。 +- `mode`：`default` 或 `safeguard`（针对长历史的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `timeoutSeconds`：OpenClaw 中止单次 compaction 操作前允许的最长秒数。默认值：`900`。 +- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预置内置的不透明标识符保留指导。 +- `identifierInstructions`：当 `identifierPolicy=custom` 时，使用的可选自定义标识符保留文本。 +- `postCompactionSections`：可选的 AGENTS.md H2/H3 章节名，会在 compaction 后重新注入。默认值为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。未设置或显式设置为该默认对时，也接受旧版 `Every Session`/`Safety` 标题作为兼容回退。 +- `model`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。当你希望主会话保留一个模型，而 compaction 摘要使用另一个模型时可用；未设置时，compaction 使用会话主模型。 - `notifyUser`：为 `true` 时，在 compaction 开始时向用户发送简短通知（例如 “Compacting context...”）。默认禁用，以保持 compaction 静默。 -- `memoryFlush`：在自动 compaction 前执行的静默智能体回合，用于存储持久记忆。当 workspace 为只读时会跳过。 +- `memoryFlush`：在自动 compaction 之前进行的静默智能体回合，用于存储持久记忆。工作区为只读时跳过。 ### `agents.defaults.contextPruning` @@ -1174,18 +1166,18 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 -- `mode: "cache-ttl"` 启用修剪处理。 -- `ttl` 控制距离上次缓存触碰后，多久可以再次运行修剪。 -- 修剪会先对过大的工具结果做软修剪，如仍有需要，再对更旧的工具结果进行硬清除。 +- `mode: "cache-ttl"` 启用修剪过程。 +- `ttl` 控制多久之后才能再次运行修剪（从上次缓存接触开始计算）。 +- 修剪会先对过大的工具结果进行软截断，如有需要，再对更旧的工具结果进行硬清除。 -**软修剪**会保留开头和结尾，并在中间插入 `...`。 +**软截断**会保留开头 + 结尾，并在中间插入 `...`。 **硬清除**会用占位符替换整个工具结果。 -说明： +注意： -- 图像块永远不会被修剪/清除。 -- 比例基于字符数（近似），不是精确 token 数。 +- 图像块永远不会被截断/清除。 +- 比率按字符计算（近似值），并非精确 token 计数。 - 如果 assistant 消息少于 `keepLastAssistants` 条，则跳过修剪。 @@ -1208,13 +1200,13 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。 +- 非 Telegram 渠道需要显式 `*.blockStreaming: true` 才会启用块回复。 - 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账号变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 -- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。按智能体覆盖：`agents.list[].humanDelay`。 +- `humanDelay`：块回复之间的随机暂停。`natural` = 800–2500ms。按智能体覆盖：`agents.list[].humanDelay`。 -行为和分块细节请参见 [Streaming](/zh-CN/concepts/streaming)。 +关于行为和分块细节，参见 [Streaming](/zh-CN/concepts/streaming)。 -### 输入指示器 +### 正在输入指示器 ```json5 { @@ -1227,7 +1219,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- 默认值：私聊/被提及时为 `instant`，未被提及的群聊中为 `message`。 +- 默认值：在私聊/被提及时为 `instant`，在未被提及的群聊中为 `message`。 - 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 参见 [Typing Indicators](/zh-CN/concepts/typing-indicators)。 @@ -1236,7 +1228,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ### `agents.defaults.sandbox` -嵌入式智能体的可选沙箱隔离。完整指南请参见 [Sandboxing](/zh-CN/gateway/sandboxing)。 +嵌入式智能体的可选沙箱隔离。完整指南请参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -1282,7 +1274,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // 也支持 SecretRef / 内联内容： + // 也支持 SecretRefs / 内联内容： // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1339,17 +1331,17 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 - `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`：用于每作用域 workspace 的远程绝对根目录 -- `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件 -- `identityData` / `certificateData` / `knownHostsData`：OpenClaw 会在运行时将内联内容或 SecretRef 实体化为临时文件 -- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关 +- `workspaceRoot`：用于按作用域工作区的绝对远程根目录 +- `identityFile` / `certificateFile` / `knownHostsFile`：传给 OpenSSH 的现有本地文件 +- `identityData` / `certificateData` / `knownHostsData`：OpenClaw 在运行时实体化为临时文件的内联内容或 SecretRef +- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略选项 **SSH 认证优先级：** @@ -1360,23 +1352,23 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **SSH 后端行为：** -- 在创建或重建后，先对远程 workspace 进行一次初始化填充 -- 之后将远程 SSH workspace 作为规范状态保持 +- 在创建或重建后只播种远程工作区一次 +- 然后保持远程 SSH 工作区为规范状态 - 通过 SSH 路由 `exec`、文件工具和媒体路径 -- 不会自动将远程变更同步回主机 +- 不会自动将远程更改同步回宿主机 - 不支持沙箱浏览器容器 -**workspace 访问：** +**工作区访问：** -- `none`：每作用域的沙箱 workspace 位于 `~/.openclaw/sandboxes` -- `ro`：沙箱 workspace 位于 `/workspace`，智能体 workspace 只读挂载到 `/agent` -- `rw`：智能体 workspace 以读写方式挂载到 `/workspace` +- `none`：位于 `~/.openclaw/sandboxes` 下按作用域划分的沙箱工作区 +- `ro`：沙箱工作区位于 `/workspace`，智能体工作区只读挂载到 `/agent` +- `rw`：智能体工作区以读写方式挂载到 `/workspace` **作用域：** -- `session`：每会话一个容器 + workspace -- `agent`：每个智能体一个容器 + workspace（默认） -- `shared`：共享容器和 workspace（不进行跨会话隔离） +- `session`：每会话一个容器 + 工作区 +- `agent`：每智能体一个容器 + 工作区（默认） +- `shared`：共享容器和工作区（无跨会话隔离） **OpenShell 插件配置：** @@ -1406,30 +1398,30 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **OpenShell 模式：** -- `mirror`：在 exec 前从本地填充到远程，exec 后再同步回本地；本地 workspace 保持为规范状态 -- `remote`：在创建沙箱时仅向远程填充一次，之后将远程 workspace 作为规范状态保持 +- `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"`（或自定义 bridge 网络）。 +默认阻止 `"host"`。默认也阻止 `"container:"`，除非你显式设置 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急模式）。 -**传入附件** 会被暂存到活动 workspace 下的 `media/inbound/*` 中。 +**传入附件** 会被暂存到当前工作区中的 `media/inbound/*`。 -**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的 binds 会合并。 +**`docker.binds`** 会挂载额外宿主目录；全局和按智能体 binds 会合并。 -**沙箱浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。会将 noVNC URL 注入系统提示中。不需要在 `openclaw.json` 中启用 `browser.enabled`。 -默认通过 VNC 认证提供 noVNC 观察访问，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` 中，并针对容器主机进行了调优： +- `allowHostControl: false`（默认）会阻止沙箱隔离会话以宿主浏览器为目标。 +- `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。只有在你明确希望使用全局 bridge 连接时，才设置为 `bridge`。 +- `cdpSourceRange` 可选地在容器边界将 CDP 入口限制为某个 CIDR 范围（例如 `172.21.0.1/32`）。 +- `sandbox.browser.binds` 仅将额外宿主目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。 +- 启动默认值定义于 `scripts/sandbox-browser-entrypoint.sh`，并针对容器宿主环境进行了调优： - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1447,16 +1439,14 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 - `--no-zygote` - `--metrics-recording-only` - `--disable-extensions`（默认启用） - - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` - 默认启用，如需 WebGL/3D，可通过 - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用这些标志。 - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展，以适配依赖扩展的工作流。 + - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` 默认启用；如果 WebGL/3D 使用场景需要，可通过 + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用这些默认项。 + - 如果你的工作流依赖扩展，可通过 + `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 重新启用扩展。 - `--renderer-process-limit=2` 可通过 - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 更改；设为 `0` 则使用 Chromium 的 - 默认进程限制。 + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设为 `0` 可使用 Chromium 的默认进程上限。 - 当启用 `noSandbox` 时，还会附加 `--no-sandbox` 和 `--disable-setuid-sandbox`。 - - 这些默认值是容器镜像基线；若要更改容器默认行为，请使用自定义浏览器镜像和自定义 - entrypoint。 + - 这些默认值是容器镜像的基线；如需修改容器默认值，请使用带自定义 entrypoint 的自定义浏览器镜像。 @@ -1482,11 +1472,11 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // 或 { primary, fallbacks } - thinkingDefault: "high", // 按智能体覆盖 thinking 级别 - reasoningDefault: "on", // 按智能体覆盖 reasoning 可见性 - fastModeDefault: false, // 按智能体覆盖 fast mode - params: { cacheRetention: "none" }, // 按键覆盖匹配 defaults.models params - skills: ["docs-search"], // 设置后替换 agents.defaults.skills + thinkingDefault: "high", // 按智能体设置的 thinking 级别覆盖 + reasoningDefault: "on", // 按智能体设置的 reasoning 可见性覆盖 + fastModeDefault: false, // 按智能体设置的快速模式覆盖 + params: { cacheRetention: "none" }, // 按键覆盖匹配的 defaults.models params + skills: ["docs-search"], // 设置后会替换 agents.defaults.skills identity: { name: "Samantha", theme: "helpful sloth", @@ -1517,20 +1507,20 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 } ``` -- `id`：稳定的智能体 ID（必填）。 -- `default`：设置多个时，以第一个为准（会记录警告）。如果都未设置，则列表第一项为默认值。 -- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 同时覆盖两者（`[]` 会禁用全局故障转移）。只覆盖 `primary` 的 cron 作业仍会继承默认故障转移，除非你设置 `fallbacks: []`。 -- `params`：按智能体的流参数，会合并到 `agents.defaults.models` 中选定模型项之上。用于按智能体覆盖 `cacheRetention`、`temperature` 或 `maxTokens`，而无需复制整个模型目录。 -- `skills`：可选的按智能体 Skills 允许列表。省略时，若已设置 `agents.defaults.skills`，则智能体会继承它；显式列表会替换默认值而不是合并，`[]` 表示无 Skills。 -- `thinkingDefault`：可选的按智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive`）。当未设置按消息或按会话覆盖时，它会覆盖该智能体的 `agents.defaults.thinkingDefault`。 -- `reasoningDefault`：可选的按智能体默认 reasoning 可见性（`on | off | stream`）。当未设置按消息或按会话的 reasoning 覆盖时应用。 -- `fastModeDefault`：可选的按智能体默认 fast mode 值（`true | false`）。当未设置按消息或按会话的 fast-mode 覆盖时应用。 -- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"`，并设置 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 -- `identity.avatar`：workspace 相对路径、`http(s)` URL 或 `data:` URI。 -- `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name`/`emoji`。 -- `subagents.allowAgents`：`sessions_spawn` 的智能体 ID 允许列表（`["*"]` = 任意；默认：仅相同智能体）。 -- 沙箱继承保护：如果请求方会话已启用沙箱隔离，`sessions_spawn` 会拒绝那些将运行在非沙箱环境中的目标。 -- `subagents.requireAgentId`：为 true 时，阻止 `sessions_spawn` 调用省略 `agentId`（强制显式选择配置；默认：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`：可选的按智能体快速模式默认值（`true | false`）。在未设置每消息或每会话快速模式覆盖时生效。 +- `runtime`：可选的按智能体运行时描述符。当智能体默认应使用 ACP harness 会话时，使用 `type: "acp"` 和 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 +- `identity.avatar`：工作区相对路径、`http(s)` URL 或 `data:` URI。 +- `identity` 会推导默认值：从 `emoji` 推导 `ackReaction`，从 `name`/`emoji` 推导 `mentionPatterns`。 +- `subagents.allowAgents`：`sessions_spawn` 的智能体 id 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- 沙箱继承保护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝那些会以未沙箱隔离方式运行的目标。 +- `subagents.requireAgentId`：为 true 时，会阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式配置选择；默认：false）。 --- @@ -1555,11 +1545,11 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ### 绑定匹配字段 -- `type`（可选）：普通路由使用 `route`（缺失时默认为 route），持久 ACP 会话绑定使用 `acp` +- `type`（可选）：正常路由使用 `route`（省略时默认 route），持久 ACP 会话绑定使用 `acp` - `match.channel`（必填） - `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号） - `match.peer`（可选；`{ kind: direct|group|channel, id }`） -- `match.guildId` / `match.teamId`（可选；渠道特定） +- `match.guildId` / `match.teamId`（可选；按渠道特定） - `acp`（可选；仅适用于 `type: "acp"`）：`{ mode, label, cwd, backend }` **确定性匹配顺序：** @@ -1571,9 +1561,9 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 5. `match.accountId: "*"`（渠道范围） 6. 默认智能体 -在每一层级内，第一个匹配的 `bindings` 条目生效。 +在每一层内，首个匹配的 `bindings` 条目获胜。 -对 `type: "acp"` 条目，OpenClaw 会按精确会话标识（`match.channel` + account + `match.peer.id`）解析，不使用上面的 route 绑定层级顺序。 +对于 `type: "acp"` 条目，OpenClaw 会按精确会话身份（`match.channel` + account + `match.peer.id`）解析，不使用上面的 route 绑定层级顺序。 ### 按智能体访问配置 @@ -1595,7 +1585,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 - + ```json5 { @@ -1696,7 +1686,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // 父线程 fork 超过此 token 数时跳过（0 禁用） + parentForkMaxTokens: 100000, // 超过该 token 数时跳过父线程 fork（0 表示禁用） maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", @@ -1708,8 +1698,8 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, threadBindings: { enabled: true, - idleHours: 24, // 默认按小时计算的无活动自动取消聚焦（`0` 禁用） - maxAgeHours: 0, // 默认按小时计算的硬最大年龄（`0` 禁用） + idleHours: 24, // 默认按小时计算的非活动自动取消聚焦（`0` 禁用） + maxAgeHours: 0, // 默认按小时计算的硬性最大存活时间（`0` 禁用） }, mainKey: "main", // 旧版（运行时始终使用 "main"） agentToAgent: { maxPingPongTurns: 5 }, @@ -1723,35 +1713,35 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 -- **`scope`**：群聊上下文的基础会话分组策略。 - - `per-sender`（默认）：在某个渠道上下文中，每个发送者都有隔离的会话。 - - `global`：某个渠道上下文中的所有参与者共享一个会话（仅在确实需要共享上下文时使用）。 +- **`scope`**：用于群聊上下文的基础会话分组策略。 + - `per-sender`（默认）：每个发送者在一个渠道上下文中拥有独立会话。 + - `global`：一个渠道上下文中的所有参与者共享一个会话（仅在明确希望共享上下文时使用）。 - **`dmScope`**：私信分组方式。 - `main`：所有私信共享主会话。 - `per-peer`：按发送者 id 跨渠道隔离。 - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。 -- **`identityLinks`**：将规范 id 映射到带提供商前缀的对等方，用于跨渠道会话共享。 -- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。两者都配置时，先到期者生效。 -- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 别名接受。 -- **`parentForkMaxTokens`**：创建 fork 线程会话时，父会话允许的最大 `totalTokens`（默认 `100000`）。 - - 如果父会话 `totalTokens` 高于该值，OpenClaw 会启动一个新的线程会话，而不是继承父转录历史。 - - 设置为 `0` 可禁用此保护，并始终允许父级 fork。 -- **`mainKey`**：旧版字段。运行时现在始终对主私聊 bucket 使用 `"main"`。 -- **`agentToAgent.maxPingPongTurns`**：智能体间交互中，智能体之间最大来回回复轮数（整数，范围：`0`–`5`）。`0` 会禁用 ping-pong 链式传递。 -- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 别名也支持）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 优先。 -- **`maintenance`**：会话存储清理和保留控制。 - - `mode`：`warn` 仅发出警告；`enforce` 会执行清理。 - - `pruneAfter`：旧条目的年龄截止（默认 `30d`）。 - - `maxEntries`：`sessions.json` 中允许的最大条目数（默认 `500`）。 - - `rotateBytes`：当 `sessions.json` 超过该大小时执行轮转（默认 `10mb`）。 - - `resetArchiveRetention`：`*.reset.` 转录归档的保留期。默认等于 `pruneAfter`；设置为 `false` 可禁用。 - - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先删除最旧的工件/会话。 - - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。 +- **`identityLinks`**：将规范 id 映射到带提供商前缀的 peer，用于跨渠道会话共享。 +- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。两者都配置时，以先到期者为准。 +- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 作为 `direct` 的别名可接受。 +- **`parentForkMaxTokens`**：创建 fork 线程会话时，允许的父会话 `totalTokens` 最大值（默认 `100000`）。 + - 如果父会话 `totalTokens` 高于此值，OpenClaw 将启动全新的线程会话，而不是继承父转录历史。 + - 设为 `0` 可禁用此保护，并始终允许父级 fork。 +- **`mainKey`**：旧版字段。运行时现在始终对主私聊桶使用 `"main"`。 +- **`agentToAgent.maxPingPongTurns`**：智能体间交换期间允许的最大回复往返轮数（整数，范围：`0`–`5`）。`0` 表示禁用 ping-pong 链。 +- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 胜出。 +- **`maintenance`**：会话存储清理 + 保留控制。 + - `mode`：`warn` 仅发出警告；`enforce` 应用清理。 + - `pruneAfter`：过期条目的年龄截止值（默认 `30d`）。 + - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。 + - `rotateBytes`：当 `sessions.json` 超过该大小时轮转（默认 `10mb`）。 + - `resetArchiveRetention`：`*.reset.` 转录归档的保留时间。默认与 `pruneAfter` 一致；设为 `false` 可禁用。 + - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先移除最旧的产物/会话。 + - `highWaterBytes`：预算清理后的可选目标值。默认为 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - - `enabled`：主默认开关（provider 可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：默认按小时计算的无活动自动取消聚焦（`0` 禁用；provider 可覆盖） - - `maxAgeHours`：默认按小时计算的硬最大年龄（`0` 禁用；provider 可覆盖） + - `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） + - `idleHours`：按小时计算的默认非活动自动取消聚焦（`0` 禁用；提供商可覆盖） + - `maxAgeHours`：按小时计算的默认硬性最大存活时间（`0` 禁用；提供商可覆盖） @@ -1795,30 +1785,30 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 **模板变量：** -| 变量 | 描述 | 示例 | -| ----------------- | ------------------ | --------------------------- | -| `{model}` | 短模型名 | `claude-opus-4-6` | -| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | -| `{provider}` | provider 名称 | `anthropic` | -| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | -| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | +| 变量 | 描述 | 示例 | +| ------------------ | ---------------- | --------------------------- | +| `{model}` | 短模型名 | `claude-opus-4-6` | +| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | +| `{provider}` | 提供商名称 | `anthropic` | +| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | +| `{identity.name}` | 智能体 identity 名称 | （与 `"auto"` 相同） | 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。 -### Ack reaction +### 确认 reaction -- 默认使用活动智能体的 `identity.emoji`，否则为 `"👀"`。设置为 `""` 可禁用。 +- 默认使用当前智能体的 `identity.emoji`，否则为 `"👀"`。设置 `""` 可禁用。 - 按渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。 - 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退。 -- 作用域：`group-mentions`（默认）、`group-all`、`direct`、`all`。 -- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，回复后移除 ack。 -- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态 reactions。 - 在 Slack 和 Discord 上，未设置时，当 ack reactions 处于活动状态会保持启用状态 reactions。 - 在 Telegram 上，需要显式将其设为 `true` 才能启用生命周期状态 reactions。 +- 范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。 +- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上于回复后移除 ack。 +- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态 reaction。 + 在 Slack 和 Discord 上，未设置时会在 ack reaction 处于激活状态时保持状态 reaction 启用。 + 在 Telegram 上，需显式设置为 `true` 才会启用生命周期状态 reaction。 -### 入站去抖 +### 传入防抖 -将同一发送者快速发送的纯文本消息批处理为单个智能体回合。媒体/附件会立即刷新。控制命令会绕过去抖。 +将来自同一发送者的快速纯文本消息批处理为单个智能体轮次。媒体/附件会立即刷新。控制命令会绕过防抖。 ### TTS（文本转语音） @@ -1862,17 +1852,17 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ``` - `auto` 控制自动 TTS。`/tts off|always|inbound|tagged` 会按会话覆盖。 -- `summaryModel` 会覆盖自动摘要的 `agents.defaults.model.primary`。 -- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需选择启用）。 +- `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 服务器，并放宽模型/语音校验。 +- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序是配置，然后 `OPENAI_TTS_BASE_URL`，然后 `https://api.openai.com/v1`。 +- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为 OpenAI 兼容的 TTS 服务器，并放宽模型/语音校验。 --- ## Talk -Talk 模式的默认值（macOS/iOS/Android）。 +Talk 模式（macOS/iOS/Android）的默认值。 ```json5 { @@ -1896,13 +1886,13 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- 当配置了多个 Talk provider 时，`talk.provider` 必须匹配 `talk.providers` 中的某个键。 -- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，会自动迁移到 `talk.providers.`。 +- 当配置了多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的某个键。 +- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，并会自动迁移到 `talk.providers.`。 - Voice ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 - `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。 -- 仅当未配置 Talk API key 时，才会使用 `ELEVENLABS_API_KEY` 回退。 +- 仅当未配置 Talk API key 时，才会应用 `ELEVENLABS_API_KEY` 回退。 - `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。 -- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多长时间再发送转录。未设置时保持平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 +- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多久才发送转录。未设置时保持平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 --- @@ -1910,22 +1900,22 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### 工具配置文件 -`tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置一个基础允许列表： +`tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置基础允许列表： -本地新手引导会在新本地配置未设置时默认使用 `tools.profile: "coding"`（现有显式 profile 会保留）。 +当 `tools.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:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） | | `group:fs` | `read`、`write`、`edit`、`apply_patch` | | `group:sessions` | `sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status` | | `group:memory` | `memory_search`、`memory_get` | @@ -1936,11 +1926,11 @@ Talk 模式的默认值（macOS/iOS/Android）。 | `group:nodes` | `nodes` | | `group:agents` | `agents_list` | | `group:media` | `image`、`image_generate`、`video_generate`、`tts` | -| `group:openclaw` | 所有内置工具（不包括 provider 插件） | +| `group:openclaw` | 所有内置工具（不包括提供商插件） | ### `tools.allow` / `tools.deny` -全局工具 allow/deny 策略（deny 优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱已关闭也会应用。 +全局工具允许/拒绝策略（拒绝优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱关闭也会应用。 ```json5 { @@ -1950,7 +1940,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.byProvider` -进一步限制特定 provider 或模型的工具。顺序：基础 profile → provider profile → allow/deny。 +进一步限制特定提供商或模型可用的工具。顺序：基础 profile → provider profile → allow/deny。 ```json5 { @@ -1984,7 +1974,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 - 按智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧限制。 - `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅作用于单条消息。 -- Elevated `exec` 会绕过沙箱隔离，并使用配置的 escape 路径（默认 `gateway`，或当 exec 目标为 `node` 时使用 `node`）。 +- Elevated `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`，或当 exec 目标是 `node` 时使用 `node`）。 ### `tools.exec` @@ -2008,8 +1998,8 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.loopDetection` -工具循环安全检查**默认关闭**。设置 `enabled: true` 可启用检测。 -可在 `tools.loopDetection` 中全局定义，并在 `agents.list[].tools.loopDetection` 中按智能体覆盖。 +工具循环安全检查**默认禁用**。设置 `enabled: true` 可启用检测。 +可在 `tools.loopDetection` 中全局定义设置，并在 `agents.list[].tools.loopDetection` 中按智能体覆盖。 ```json5 { @@ -2030,14 +2020,14 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- `historySize`：为循环分析保留的最大工具调用历史。 +- `historySize`：用于循环分析保留的最大工具调用历史。 - `warningThreshold`：用于发出警告的重复无进展模式阈值。 -- `criticalThreshold`：用于阻止关键循环的更高重复阈值。 -- `globalCircuitBreakerThreshold`：任何无进展运行的硬停止阈值。 -- `detectors.genericRepeat`：对同工具/同参数的重复调用发出警告。 +- `criticalThreshold`：用于阻止严重循环的更高重复阈值。 +- `globalCircuitBreakerThreshold`：针对任何无进展运行的硬停止阈值。 +- `detectors.genericRepeat`：对重复的同工具/同参数调用发出警告。 - `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告/阻止。 -- `detectors.pingPong`：对交替式无进展对模式发出警告/阻止。 -- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，校验将失败。 +- `detectors.pingPong`：对交替出现的无进展成对模式发出警告/阻止。 +- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，校验会失败。 ### `tools.web` @@ -2102,11 +2092,11 @@ Talk 模式的默认值（macOS/iOS/Android）。 -**Provider 条目**（`type: "provider"` 或省略）： +**提供商条目**（`type: "provider"` 或省略）： -- `provider`：API provider id（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） +- `provider`：API 提供商 id（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） - `model`：模型 id 覆盖 -- `profile` / `preferredProfile`：`auth-profiles.json` 配置选择 +- `profile` / `preferredProfile`：`auth-profiles.json` profile 选择 **CLI 条目**（`type: "cli"`）： @@ -2119,7 +2109,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 - `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：按条目覆盖。 - 失败时会回退到下一个条目。 -Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 +提供商认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 @@ -2138,9 +2128,9 @@ Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m ### `tools.sessions` -控制 session 工具（`sessions_list`、`sessions_history`、`sessions_send`）可以针对哪些会话。 +控制哪些会话可以被会话工具（`sessions_list`、`sessions_history`、`sessions_send`）作为目标。 -默认值：`tree`（当前会话 + 由其派生的会话，例如子智能体）。 +默认值：`tree`（当前会话 + 由其生成的会话，例如子智能体）。 ```json5 { @@ -2153,13 +2143,13 @@ Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m } ``` -说明： +注意： - `self`：仅当前会话键。 -- `tree`：当前会话 + 由当前会话派生的会话（子智能体）。 -- `agent`：属于当前智能体 id 的任意会话（如果你在同一智能体 id 下运行按发送者隔离的会话，则可能包含其他用户）。 -- `all`：任意会话。跨智能体目标仍然需要 `tools.agentToAgent`。 -- 沙箱限制：当当前会话已启用沙箱隔离，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 +- `tree`：当前会话 + 由当前会话生成的会话（子智能体）。 +- `agent`：属于当前智能体 id 的任意会话（如果你在同一智能体 id 下按发送者运行会话，可能包含其他用户）。 +- `all`：任意会话。跨智能体定向仍需要 `tools.agentToAgent`。 +- 沙箱钳制：当当前会话处于沙箱隔离中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 ### `tools.sessions_spawn` @@ -2181,18 +2171,18 @@ Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m } ``` -说明： +注意： -- 仅 `runtime: "subagent"` 支持附件。ACP 运行时会拒绝它们。 -- 文件会在子 workspace 中实体化到 `.openclaw/attachments//`，并附带 `.manifest.json`。 +- 仅 `runtime: "subagent"` 支持附件。ACP runtime 会拒绝它们。 +- 文件会实体化到子工作区中的 `.openclaw/attachments//`，并带有 `.manifest.json`。 - 附件内容会自动从转录持久化中脱敏。 -- Base64 输入会进行严格字母表/填充校验，并在解码前进行大小保护检查。 +- Base64 输入会使用严格的字母表/填充检查和解码前大小保护进行校验。 - 文件权限：目录为 `0700`，文件为 `0600`。 -- 清理遵循 `cleanup` 策略：`delete` 总会删除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留。 +- 清理遵循 `cleanup` 策略：`delete` 始终会移除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留。 ### `tools.experimental` -实验性内置工具标志。默认关闭，除非有运行时特定的自动启用规则。 +实验性内置工具开关。默认关闭，除非适用某个运行时特定的自动启用规则。 ```json5 { @@ -2204,11 +2194,11 @@ Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m } ``` -说明： +注意： -- `planTool`：为非琐碎的多步骤工作跟踪启用结构化 `update_plan` 工具。 -- 默认值：对非 OpenAI provider 为 `false`。OpenAI 和 OpenAI Codex 运行会自动启用它。 -- 启用后，系统提示也会加入使用指导，以便模型仅在重要工作中使用它，并始终最多只有一个步骤处于 `in_progress`。 +- `planTool`：为非平凡多步骤工作跟踪启用结构化 `update_plan` 工具。 +- 默认值：对非 OpenAI 提供商为 `false`。OpenAI 和 OpenAI Codex 运行会自动启用它。 +- 启用后，系统提示词也会增加使用指导，使模型仅在较复杂工作时使用它，并最多保持一个 `in_progress` 步骤。 ### `agents.defaults.subagents` @@ -2228,16 +2218,16 @@ Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m } ``` -- `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`。 --- -## 自定义 provider 和 base URL +## 自定义提供商和 base URL -OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义 provider。 +OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义提供商。 ```json5 { @@ -2266,48 +2256,48 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -- 对自定义认证需求，使用 `authHeader: true` + `headers`。 +- 自定义认证需求请使用 `authHeader: true` + `headers`。 - 使用 `OPENCLAW_AGENT_DIR`（或旧版环境变量别名 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。 -- 匹配 provider ID 的合并优先级： - - 非空的智能体 `models.json` `baseUrl` 优先。 - - 非空的智能体 `apiKey` 仅在该 provider 在当前 config/auth-profile 上下文中不由 SecretRef 管理时优先。 - - 由 SecretRef 管理的 provider `apiKey` 值会从源标记（环境变量引用用 `ENV_VAR_NAME`，文件/exec 引用用 `secretref-managed`）刷新，而不是持久化已解析的 secret。 - - 由 SecretRef 管理的 provider header 值也会从源标记刷新（环境变量引用用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用用 `secretref-managed`）。 - - 空或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 - - 匹配模型的 `contextWindow`/`maxTokens` 会在显式配置值和隐式目录值之间取较高者。 - - 匹配模型的 `contextTokens` 在存在时会保留显式运行时上限；使用它可在不改变模型原生元数据的情况下限制有效上下文。 +- 匹配提供商 ID 的合并优先级： + - 非空的智能体 `models.json` `baseUrl` 值优先。 + - 非空的智能体 `apiKey` 值仅在当前配置/auth-profile 上下文中该提供商不是 SecretRef 托管时优先。 + - SecretRef 托管的提供商 `apiKey` 值会从源标记刷新（环境变量引用用 `ENV_VAR_NAME`，文件/exec 引用用 `secretref-managed`），而不是持久化已解析的 secret。 + - SecretRef 托管的提供商 header 值也会从源标记刷新（环境变量引用用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用用 `secretref-managed`）。 + - 智能体的 `apiKey`/`baseUrl` 为空或缺失时，会回退到配置中的 `models.providers`。 + - 匹配模型的 `contextWindow`/`maxTokens` 取显式配置和隐式目录值中的较高者。 + - 匹配模型的 `contextTokens` 在存在时会保留显式运行时上限；用它可以在不改变原生模型元数据的前提下限制有效上下文。 - 当你希望配置完全重写 `models.json` 时，使用 `models.mode: "replace"`。 - - 标记持久化以源为准：标记从活动源配置快照（解析前）写入，而不是从已解析的运行时 secret 值写入。 + - 标记持久化以源为权威：标记是根据活动源配置快照（解析前）写入，而不是根据已解析的运行时 secret 值写入。 -### Provider 字段详情 +### 提供商字段详情 -- `models.mode`：provider 目录行为（`merge` 或 `replace`）。 -- `models.providers`：按 provider id 键控的自定义 provider 映射。 +- `models.mode`：提供商目录行为（`merge` 或 `replace`）。 +- `models.providers`：以提供商 id 为键的自定义提供商映射。 - `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。 -- `models.providers.*.apiKey`：provider 凭证（优先使用 SecretRef/环境变量替换）。 +- `models.providers.*.apiKey`：提供商凭证（优先使用 SecretRef/环境变量替换）。 - `models.providers.*.auth`：认证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。 -- `models.providers.*.injectNumCtxForOpenAICompat`：对 Ollama + `openai-completions`，向请求中注入 `options.num_ctx`（默认：`true`）。 -- `models.providers.*.authHeader`：在需要时强制通过 `Authorization` header 传递凭证。 +- `models.providers.*.injectNumCtxForOpenAICompat`：对于 Ollama + `openai-completions`，向请求中注入 `options.num_ctx`（默认：`true`）。 +- `models.providers.*.authHeader`：在需要时强制通过 `Authorization` header 传输凭证。 - `models.providers.*.baseUrl`：上游 API base URL。 - `models.providers.*.headers`：用于代理/租户路由的额外静态 headers。 -- `models.providers.*.request`：模型 provider HTTP 请求的传输覆盖。 - - `request.headers`：额外 headers（与 provider 默认值合并）。值接受 SecretRef。 - - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用 provider 内置认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value`，可选 `prefix`）。 +- `models.providers.*.request`：模型提供商 HTTP 请求的传输覆盖。 + - `request.headers`：额外 headers（与提供商默认值合并）。值接受 SecretRef。 + - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用提供商内置认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value` 和可选 `prefix`）。 - `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（配合 `url`）。两种模式都接受可选的 `tls` 子对象。 - - `request.tls`：直连的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（都接受 SecretRef）、`serverName`、`insecureSkipVerify`。 -- `models.providers.*.models`：显式 provider 模型目录条目。 + - `request.tls`：直连时的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（都接受 SecretRef）、`serverName`、`insecureSkipVerify`。 +- `models.providers.*.models`：显式提供商模型目录条目。 - `models.providers.*.models.*.contextWindow`：原生模型上下文窗口元数据。 -- `models.providers.*.models.*.contextTokens`：可选运行时上下文上限。当你希望有效上下文预算小于模型原生 `contextWindow` 时使用。 -- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对 `api: "openai-completions"` 且非空、非原生 `baseUrl`（host 不是 `api.openai.com`）的情况，OpenClaw 会在运行时强制将其设为 `false`。空/省略的 `baseUrl` 会保留默认 OpenAI 行为。 -- `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 行为。 +- `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。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：已发现模型的回退上下文窗口。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：已发现模型的回退最大输出 token。 -### Provider 示例 +### 提供商示例 @@ -2321,8 +2311,8 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ fallbacks: ["cerebras/zai-glm-4.6"], }, models: { - "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" }, - "cerebras/zai-glm-4.6": { alias: "GLM 4.6 (Cerebras)" }, + "cerebras/zai-glm-4.7": { alias: "GLM 4.7（Cerebras）" }, + "cerebras/zai-glm-4.6": { alias: "GLM 4.6（Cerebras）" }, }, }, }, @@ -2334,8 +2324,8 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ apiKey: "${CEREBRAS_API_KEY}", api: "openai-completions", models: [ - { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" }, - { id: "zai-glm-4.6", name: "GLM 4.6 (Cerebras)" }, + { id: "zai-glm-4.7", name: "GLM 4.7（Cerebras）" }, + { id: "zai-glm-4.6", name: "GLM 4.6（Cerebras）" }, ], }, }, @@ -2343,7 +2333,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -对 Cerebras 使用 `cerebras/zai-glm-4.7`；对 Z.AI 直连使用 `zai/glm-4.7`。 +Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。 @@ -2377,11 +2367,11 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 都是可接受的别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。 +设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 都可作为别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。 - 通用端点：`https://api.z.ai/api/paas/v4` -- Coding 端点（默认）：`https://api.z.ai/api/coding/paas/v4` -- 对于通用端点，请定义一个带 base URL 覆盖的自定义 provider。 +- 编码端点（默认）：`https://api.z.ai/api/coding/paas/v4` +- 对于通用端点，请定义带 base URL 覆盖的自定义提供商。 @@ -2420,11 +2410,9 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -中国端点：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。 +中国区端点：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。 -原生 Moonshot 端点会在共享的 -`openai-completions` 传输上声明流式使用兼容性，而 OpenClaw 现在基于端点 -能力而不是仅基于内置 provider id 来决定这一点。 +原生 Moonshot 端点会在共享的 `openai-completions` 传输上声明流式使用兼容性，OpenClaw 现在依据端点能力而不是仅依据内置 provider id 来识别这一点。 @@ -2442,7 +2430,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -兼容 Anthropic 的内置 provider。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 +Anthropic 兼容的内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 @@ -2481,7 +2469,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。 +base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。 @@ -2525,16 +2513,15 @@ 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 兼容的流式路径上，除非你显式设置 `thinking`，否则 OpenClaw 默认禁用 MiniMax thinking。 +`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 -参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在性能充足的硬件上通过 LM Studio Responses API 运行大型本地模型，并保留托管模型以便故障转移。 +参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在高性能硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。 @@ -2565,14 +2552,12 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方 } ``` -- `allowBundled`：仅针对内置 Skills 的可选允许列表（受管/workspace Skills 不受影响）。 -- `load.extraDirs`：额外的共享 Skills 根目录（最低优先级）。 -- `install.preferBrew`：为 true 时，若 `brew` 可用，则优先使用 Homebrew 安装器，然后才回退到其他安装器类型。 -- `install.nodeManager`：用于 `metadata.openclaw.install` - 规格的 node 安装器偏好 - （`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false`：即使是内置/已安装 Skill，也会禁用该 Skill。 -- `entries..apiKey`：为声明了主环境变量的 Skill 提供的便捷字段（明文字符串或 SecretRef 对象）。 +- `allowBundled`：仅针对内置 Skills 的可选允许列表（managed/workspace Skills 不受影响）。 +- `load.extraDirs`：额外共享 Skills 根目录（优先级最低）。 +- `install.preferBrew`：为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器，然后才回退到其他安装器类型。 +- `install.nodeManager`：`metadata.openclaw.install` 规范所使用的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false`：即使某个 skill 已内置/已安装，也会禁用它。 +- `entries..apiKey`：为声明了主环境变量的 Skills 提供的便捷 API key 字段（明文字符串或 SecretRef 对象）。 --- @@ -2601,34 +2586,34 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方 ``` - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 -- 设备发现同时接受原生 OpenClaw 插件、兼容的 Codex bundles 和 Claude bundles，包括无 manifest 的 Claude 默认布局 bundles。 +- 发现机制接受原生 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` 中会修改 prompt 的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hooks 和受支持 bundle 提供的 hook 目录。 -- `plugins.entries..subagent.allowModelOverride`：显式信任该插件可为后台子智能体运行请求按次执行的 `provider` 和 `model` 覆盖。 -- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖的规范 `provider/model` 目标可选允许列表。仅当你有意允许任意模型时才使用 `"*"`。 -- `plugins.entries..config`：插件定义的配置对象（如果可用，会由原生 OpenClaw 插件 schema 校验）。 -- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web-fetch provider 设置。 +- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hooks 以及支持的 bundle 提供 hook 目录。 +- `plugins.entries..subagent.allowModelOverride`：显式信任该插件可为后台子智能体运行请求按次 `provider` 和 `model` 覆盖。 +- `plugins.entries..subagent.allowedModels`：针对受信任子智能体覆盖的可选规范 `provider/model` 目标允许列表。仅当你确实打算允许任意模型时才使用 `"*"`。 +- `plugins.entries..config`：插件定义的配置对象（若有原生 OpenClaw 插件 schema，则会据此校验）。 +- `plugins.entries.firecrawl.config.webFetch`：Firecrawl Web 获取提供商设置。 - `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`）。 + - `onlyMainContent`：仅提取页面主内容（默认：`true`）。 - `maxAgeMs`：最大缓存年龄（毫秒）（默认：`172800000` / 2 天）。 - - `timeoutSeconds`：抓取请求超时秒数（默认：`60`）。 -- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web 搜索）设置。 - - `enabled`：启用 X Search provider。 + - `timeoutSeconds`：抓取请求超时时间（秒）（默认：`60`）。 +- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok Web 搜索）设置。 + - `enabled`：启用 X Search 提供商。 - `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。 -- `plugins.entries.memory-core.config.dreaming`：记忆 dreaming（实验性）设置。阶段和阈值请参见 [Dreaming](/zh-CN/concepts/dreaming)。 - - `enabled`：dreaming 主开关（默认 `false`）。 - - `frequency`：每次完整 dreaming 扫描的 cron 周期（默认 `"0 3 * * *"`）。 +- `plugins.entries.memory-core.config.dreaming`：记忆 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"`，除非你安装并选择了其他引擎。 -- `plugins.installs`：由 CLI 管理的安装元数据，供 `openclaw plugins update` 使用。 - - 包含 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。 - - 将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。 +- 已启用的 Claude bundle 插件也可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将这些作为经过净化的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。 +- `plugins.slots.memory`：选择活动 memory 插件 id，或设为 `"none"` 以禁用 memory 插件。 +- `plugins.slots.contextEngine`：选择活动 context engine 插件 id；默认是 `"legacy"`，除非你安装并选择了其他引擎。 +- `plugins.installs`：CLI 管理的安装元数据，由 `openclaw plugins update` 使用。 + - 包括 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。 + - 请将 `plugins.installs.*` 视为受管状态；优先使用 CLI 命令而不是手动编辑。 参见 [Plugins](/zh-CN/tools/plugin)。 @@ -2643,7 +2628,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方 evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - dangerouslyAllowPrivateNetwork: true, // 默认受信网络模式 + dangerouslyAllowPrivateNetwork: true, // 默认可信网络模式 // allowPrivateNetwork: true, // 旧版别名 // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], @@ -2671,25 +2656,23 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方 ``` - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时默认 `true`（受信网络模型）。 -- 若要启用严格的仅公网浏览器导航，请设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: false`。 -- 在严格模式下，远程 CDP profile 端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间也会受到相同的私有网络阻止。 -- `ssrfPolicy.allowPrivateNetwork` 仍支持作为旧版别名。 -- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 配置显式例外。 +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时默认为 `true`（可信网络模型）。 +- 如需严格的仅公网浏览器导航，请设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: false`。 +- 在严格模式下，远程 CDP profile 端点（`profiles.*.cdpUrl`）在可达性/发现检查期间也会受到相同的私有网络阻止策略约束。 +- `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 +- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 作为显式例外。 - 远程 profile 为仅附加模式（禁用 start/stop/reset）。 - `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。 - 当你希望 OpenClaw 发现 `/json/version` 时使用 HTTP(S)；当 provider 直接给你 DevTools WebSocket URL 时使用 WS(S)。 -- `existing-session` profile 仅适用于主机，并使用 Chrome MCP 而不是 CDP。 -- `existing-session` profile 可设置 `userDataDir` 来指定特定 - Chromium 系浏览器 profile，例如 Brave 或 Edge。 -- `existing-session` profile 会保留当前 Chrome MCP 路由限制： - 使用 snapshot/ref 驱动的操作，而非 CSS selector 定位，仅支持单文件上传 - hooks，不支持对话框超时覆盖，不支持 `wait --load networkidle`，也不支持 - `responsebody`、PDF 导出、下载拦截或批量操作。 -- 本地托管的 `openclaw` profiles 会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 时显式设置 `cdpUrl`。 -- 自动检测顺序：默认浏览器（若为 Chromium 系）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 -- 控制服务：仅 loopback（端口由 `gateway.port` 派生，默认 `18791`）。 -- `extraArgs` 会向本地 Chromium 启动附加额外标志（例如 `--disable-gpu`、窗口大小或调试标志）。 + 当你希望 OpenClaw 发现 `/json/version` 时使用 HTTP(S)； + 当提供商直接给你 DevTools WebSocket URL 时使用 WS(S)。 +- `existing-session` profile 仅限宿主机，并使用 Chrome MCP 而不是 CDP。 +- `existing-session` profile 可设置 `userDataDir`，以指向特定基于 Chromium 的浏览器 profile，例如 Brave 或 Edge。 +- `existing-session` profile 保留当前 Chrome MCP 路由限制： + 使用 snapshot/ref 驱动操作而不是 CSS 选择器定位，单文件上传 hook，无对话框超时覆盖，无 `wait --load networkidle`，也不支持 `responsebody`、PDF 导出、下载拦截或批处理操作。 +- 本地受管 `openclaw` profile 会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 时显式设置 `cdpUrl`。 +- 自动检测顺序：默认浏览器（如果是基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 +- 控制服务：仅 loopback（端口从 `gateway.port` 派生，默认 `18791`）。 +- `extraArgs` 会将额外启动标志附加到本地 Chromium 启动参数中（例如 `--disable-gpu`、窗口大小或调试标志）。 --- @@ -2701,14 +2684,14 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方 seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji、短文本、图片 URL 或 data URI + avatar: "CB", // emoji、短文本、图像 URL 或 data URI }, }, } ``` -- `seamColor`：原生应用 UI chrome 的强调色（Talk 模式气泡着色等）。 -- `assistant`：Control UI 身份覆盖。会回退到活动智能体身份。 +- `seamColor`：原生应用 UI 外观的强调色（Talk 模式气泡色调等）。 +- `assistant`：Control UI identity 覆盖。会回退到活动智能体 identity。 --- @@ -2724,7 +2707,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方 mode: "token", // none | token | password | trusted-proxy token: "your-token", // password: "your-password", // 或 OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // 用于 mode=trusted-proxy；参见 /gateway/trusted-proxy-auth + // trustedProxy: { userHeader: "x-forwarded-user" }, // 适用于 mode=trusted-proxy；参见 /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -2756,7 +2739,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方 // 可选。默认 false。 allowRealIpFallback: false, tools: { - // 对 /tools/invoke HTTP 的额外 deny + // 额外的 /tools/invoke HTTP deny deny: ["browser"], // 从默认 HTTP deny 列表中移除工具 allow: ["gateway"], @@ -2775,51 +2758,49 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方 -- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关会拒绝启动。 +- `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`），不要使用 host 别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 -- **Docker 注意事项**：默认的 `loopback` bind 在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 Gateway 网关不可达。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 且 `customBindHost: "0.0.0.0"`）以监听所有接口。 -- **Auth**：默认必须启用。非 loopback 绑定要求 Gateway 网关认证。实际中，这意味着共享 token/password，或使用带 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成 token。 -- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式设置 `gateway.auth.mode` 为 `token` 或 `password`。若两者都已配置而 mode 未设置，启动以及服务安装/修复流程都会失败。 -- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信的本地 local loopback 设置；新手引导提示不会提供该选项。 -- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份 headers（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。该模式要求**非 loopback** 代理来源；同主机 loopback 反向代理不满足 trusted-proxy auth。 -- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份 headers 可满足 Control UI/WebSocket auth（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale header auth；它们仍遵循 Gateway 网关的普通 HTTP auth 模式。该无 token 流程假定 Gateway 网关主机受信。当 `tailscale.mode = "serve"` 时默认值为 `true`。 -- `gateway.auth.rateLimit`：可选的认证失败限速器。按客户端 IP 和 auth 作用域生效（共享 secret 和设备 token 会独立跟踪）。被阻止的请求返回 `429` + `Retry-After`。 - - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试会在写入失败前串行化。因此，来自同一客户端的并发错误尝试，可能会在第二个请求时触发限速，而不是两个都以普通不匹配方式竞争通过。 - - `gateway.auth.rateLimit.exemptLoopback` 默认值为 `true`；若你有意希望 localhost 流量也受限速（测试设置或严格代理部署），请设为 `false`。 -- 来自浏览器 origin 的 WS auth 尝试始终会关闭 loopback 豁免并进行节流（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。 -- 在 loopback 上，这些来自浏览器 origin 的锁定会按归一化后的 `Origin` - 值隔离，因此某个 localhost origin 的重复失败不会自动 - 锁死另一个 origin。 -- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公网，需要 auth）。 -- `controlUi.allowedOrigins`：Gateway 网关 WebSocket 连接的显式浏览器 origin 允许列表。当预期来自非 loopback origin 的浏览器客户端时，这是必需的。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为那些有意依赖 Host header origin 策略的部署启用 Host-header origin 回退。 -- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧破窗覆盖，允许对受信私有网络 IP 使用明文 `ws://`；默认情况下，明文仍然仅限 loopback。 -- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。 -- `gateway.push.apns.relay.baseUrl`：外部 APNs relay 的 base HTTPS URL，供官方/TestFlight iOS 构建在将基于 relay 的注册发布到 Gateway 网关之后使用。该 URL 必须与编译进 iOS 构建中的 relay URL 一致。 -- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时（毫秒）。默认值为 `10000`。 -- 基于 relay 的注册会委派给某个特定 Gateway 网关身份。已配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并将一个注册级发送授权转发给 Gateway 网关。其他 Gateway 网关无法复用该已存储注册。 -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述 relay 配置的临时环境变量覆盖。 -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅用于开发的逃生口，允许 loopback HTTP relay URL。生产 relay URL 应保持 HTTPS。 -- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔（分钟）。设置为 `0` 可全局禁用健康监控重启。默认值：`5`。 -- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 -- `gateway.channelMaxRestartsPerHour`：滚动一小时内每个渠道/账号的最大健康监控重启次数。默认值：`10`。 -- `channels..healthMonitor.enabled`：在保持全局监控启用的同时，对单个渠道选择退出健康监控重启。 -- `channels..accounts..healthMonitor.enabled`：多账号渠道的按账号覆盖。若设置，会优先于渠道级覆盖。 -- 仅当 `gateway.auth.*` 未设置时，本地 Gateway 网关调用路径才可将 `gateway.remote.*` 作为回退。 -- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置且未解析成功，则解析会失败并默认拒绝（不会被远程回退所掩盖）。 -- `trustedProxies`：终止 TLS 或注入转发客户端 headers 的反向代理 IP。仅列出你控制的代理。loopback 条目对同主机代理/本地检测场景（例如 Tailscale Serve 或本地反向代理）仍有效，但它们**不会**让 loopback 请求具备 `gateway.auth.mode: "trusted-proxy"` 的资格。 -- `allowRealIpFallback`：为 `true` 时，当缺少 `X-Forwarded-For` 时，Gateway 网关会接受 `X-Real-IP`。默认 `false`，以保持默认拒绝行为。 -- `gateway.tools.deny`：为 HTTP `POST /tools/invoke` 额外阻止的工具名（扩展默认 deny 列表）。 -- `gateway.tools.allow`：从默认 HTTP deny 列表中移除工具名。 +- **旧版 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` 的身份 header（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。该模式要求 **非 loopback** 代理来源；同机 loopback 反向代理不满足 trusted-proxy auth 的要求。 +- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve identity header 可以满足 Control UI/WebSocket 认证（通过 `tailscale whois` 校验）。HTTP API 端点**不会**使用该 Tailscale header 认证；它们仍遵循 gateway 的常规 HTTP 认证模式。该无 token 流程假设 gateway 主机受信任。当 `tailscale.mode = "serve"` 时默认值为 `true`。 +- `gateway.auth.rateLimit`：可选的认证失败限制器。按客户端 IP 及认证作用域生效（共享密钥和设备 token 会分别跟踪）。被阻止的尝试返回 `429` + `Retry-After`。 + - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试会在写入失败记录前被串行化。因此，同一客户端的并发错误尝试可能会在第二个请求上触发限制，而不是两个都仅作为普通不匹配通过。 + - `gateway.auth.rateLimit.exemptLoopback` 默认值为 `true`；当你有意希望 localhost 流量也被限速时（例如测试设置或严格代理部署），设为 `false`。 +- 来自浏览器 origin 的 WS 认证尝试始终会在关闭 loopback 豁免的情况下节流（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。 +- 在 loopback 上，这些来自浏览器 origin 的锁定会按规范化后的 `Origin` 值隔离，因此一个 localhost origin 的重复失败不会自动锁定另一个 origin。 +- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公开访问，需要认证）。 +- `controlUi.allowedOrigins`：显式浏览器 origin 允许列表，用于 Gateway WebSocket 连接。当预期有来自非 loopback origin 的浏览器客户端时为必填。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，可为有意依赖 Host header origin 策略的部署启用 Host header origin 回退。 +- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧的紧急覆盖，允许向受信任私有网络 IP 使用明文 `ws://`；默认仍仅允许 loopback 使用明文。 +- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 gateway 认证。 +- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建在向 gateway 发布基于 relay 的注册后，用于外部 APNs relay 的基础 HTTPS URL。该 URL 必须与 iOS 构建中编译进去的 relay URL 匹配。 +- `gateway.push.apns.relay.timeoutMs`：gateway 到 relay 的发送超时时间（毫秒）。默认值：`10000`。 +- 基于 relay 的注册会委托给特定 gateway identity。配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该 identity，并将注册范围的发送授权转发给 gateway。其他 gateway 无法复用该已存储注册。 +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：针对上述 relay 配置的临时环境变量覆盖。 +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅开发用逃逸开关，用于 loopback HTTP relay URL。生产 relay URL 应保持 HTTPS。 +- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔（分钟）。设为 `0` 可全局禁用健康监控重启。默认值：`5`。 +- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。应保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 +- `gateway.channelMaxRestartsPerHour`：每渠道/账号在滚动 1 小时内的最大健康监控重启次数。默认值：`10`。 +- `channels..healthMonitor.enabled`：在保持全局监控启用的同时，为单个渠道选择退出健康监控重启。 +- `channels..accounts..healthMonitor.enabled`：多账号渠道的按账号覆盖。设置后优先于渠道级覆盖。 +- 本地 gateway 调用路径只有在 `gateway.auth.*` 未设置时，才会将 `gateway.remote.*` 用作回退。 +- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但无法解析，则解析会故障关闭（不会用远程回退掩盖）。 +- `trustedProxies`：终止 TLS 或注入转发客户端 header 的反向代理 IP。只列出你控制的代理。loopback 条目对同机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理）仍然有效，但它们**不会**让 loopback 请求符合 `gateway.auth.mode: "trusted-proxy"` 的资格。 +- `allowRealIpFallback`：为 `true` 时，如果缺少 `X-Forwarded-For`，gateway 会接受 `X-Real-IP`。默认值 `false`，以实现故障关闭行为。 +- `gateway.tools.deny`：针对 HTTP `POST /tools/invoke` 额外阻止的工具名称（扩展默认 deny 列表）。 +- `gateway.tools.allow`：从默认 HTTP deny 列表中移除工具名称。 -### 兼容 OpenAI 的端点 +### OpenAI 兼容端点 -- Chat Completions：默认禁用。使用 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。 +- Chat Completions：默认禁用。通过 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。 - Responses API：`gateway.http.endpoints.responses.enabled`。 - Responses URL 输入加固： - `gateway \ No newline at end of file