openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-02 03:00:43 +00:00
parent 4993185b1c
commit 8e60a43468
3 changed files with 605 additions and 581 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

480
docs/zh-CN/channels/discord.md
View File

File diff suppressed because it is too large Load Diff

379
docs/zh-CN/channels/slack.md
View File

@ -1,49 +1,49 @@
---
read_when:
- 设置 Slack 或调试 Slack 套接字/HTTP 模式
summary: Slack 设置和运行时行为（Socket 模式 + HTTP 请求 URL）
- 设置 Slack 或调试 Slack socket/HTTP 模式
summary: Slack 设置和运行时行为（Socket Mode + HTTP 请求 URL）
title: Slack
x-i18n:
generated_at: "2026-05-01T13:24:13Z"
generated_at: "2026-05-02T02:58:10Z"
model: gpt-5.5
provider: openai
source_hash: d2b065eab0e80dc223d33d0e0c8210e1ff05ff24426f7a335885540c9eb42ae9
source_hash: 82dbc27617415cb21e3c682d58c8a8a7f56c7471af0b43d5fcbb5df3fa872a49
source_path: channels/slack.md
workflow: 16
---
已可通过 Slack 应用集成用于生产环境中的私信和渠道。默认模式是 Socket Mode；也支持 HTTP Request URLs。
Production-ready for DMs and channels via Slack app integrations. Default mode is Socket Mode; HTTP Request URLs are also supported.
<CardGroup cols={3}>
<Card title="Pairing" icon="link" href="/zh-CN/channels/pairing">
Slack 私信默认使用配对模式。
Slack DMs default to pairing mode.
</Card>
<Card title="Slash commands" icon="terminal" href="/zh-CN/tools/slash-commands">
原生命令行为和命令目录。
Native command behavior and command catalog.
</Card>
<Card title="Channel troubleshooting" icon="wrench" href="/zh-CN/channels/troubleshooting">
跨渠道诊断和修复手册。
Cross-channel diagnostics and repair playbooks.
</Card>
</CardGroup>
## 快速设置
## Quick setup
<Tabs>
<Tab title="Socket Mode (default)">
<Steps>
<Step title="Create a new Slack app">
在 Slack 应用设置中按下 **[Create New App](https://api.slack.com/apps/new)** 按钮：
In Slack app settings press the **[Create New App](https://api.slack.com/apps/new)** button:
- 选择 **from a manifest** 并为你的应用选择一个工作区
- 粘贴下面的[示例清单](#manifest-and-scope-checklist)，然后继续创建
- 生成一个具有 `connections:write` 权限的 **App-Level Token**（`xapp-...`）
- 安装应用并复制显示的 **Bot Token**（`xoxb-...`）
- choose **from a manifest** and select a workspace for your app
- paste the [example manifest](#manifest-and-scope-checklist) from below and continue to create
- generate an **App-Level Token** (`xapp-...`) with `connections:write`
- install app and copy the **Bot Token** (`xoxb-...`) shown
</Step>
<Step title="Configure OpenClaw">
推荐的 SecretRef 设置：
Recommended SecretRef setup:
```bash
export SLACK_APP_TOKEN=xapp-...
@ -64,7 +64,7 @@ openclaw config patch --file ./slack.socket.patch.json5 --dry-run
openclaw config patch --file ./slack.socket.patch.json5
```
环境变量回退（仅默认账号）：
Env fallback (default account only):
```bash
SLACK_APP_TOKEN=xapp-...
@ -87,18 +87,18 @@ openclaw gateway
<Tab title="HTTP Request URLs">
<Steps>
<Step title="Create a new Slack app">
在 Slack 应用设置中按下 **[Create New App](https://api.slack.com/apps/new)** 按钮：
In Slack app settings press the **[Create New App](https://api.slack.com/apps/new)** button:
- 选择 **from a manifest** 并为你的应用选择一个工作区
- 粘贴[示例清单](#manifest-and-scope-checklist)，并在创建前更新 URL
- 保存用于请求验证的 **Signing Secret**
- 安装应用并复制显示的 **Bot Token**（`xoxb-...`）
- choose **from a manifest** and select a workspace for your app
- paste the [example manifest](#manifest-and-scope-checklist) and update the URLs before create
- save the **Signing Secret** for request verification
- install app and copy the **Bot Token** (`xoxb-...`) shown
</Step>
<Step title="Configure OpenClaw">
推荐的 SecretRef 设置：
Recommended SecretRef setup:
```bash
export SLACK_BOT_TOKEN=xoxb-...
@ -121,9 +121,9 @@ openclaw config patch --file ./slack.http.patch.json5
```
<Note>
为多账号 HTTP 使用唯一的 webhook 路径
Use unique webhook paths for multi-account HTTP
为每个账号提供不同的 `webhookPath`（默认 `/slack/events`），这样注册不会冲突。
Give each account a distinct `webhookPath` (default `/slack/events`) so registrations do not collide.
</Note>
</Step>
@ -140,9 +140,9 @@ openclaw gateway
</Tab>
</Tabs>
## Socket Mode 传输调优
## Socket Mode transport tuning
对于 Socket Mode，OpenClaw 默认将 Slack SDK 客户端 pong 超时设置为 15 秒。只有在需要针对工作区或主机进行特定调优时，才覆盖传输设置：
OpenClaw sets the Slack SDK client pong timeout to 15 seconds by default for Socket Mode. Override the transport settings only when you need workspace- or host-specific tuning:
```json5
{
@ -159,13 +159,13 @@ openclaw gateway
}
```
仅对记录 Slack websocket pong/server-ping 超时，或运行在已知存在事件循环饥饿问题主机上的 Socket Mode 工作区使用此配置。`clientPingTimeout` 是 SDK 发送客户端 ping 后等待 pong 的时间；`serverPingTimeout` 是等待 Slack 服务器 ping 的时间。应用消息和事件仍然是应用状态，而不是传输活跃性信号。
Use this only for Socket Mode workspaces that log Slack websocket pong/server-ping timeouts or run on hosts with known event-loop starvation. `clientPingTimeout` is the pong wait after the SDK sends a client ping; `serverPingTimeout` is the wait for Slack server pings. App messages and events remain application state, not transport liveness signals.
## 清单和 scope 检查清单
## Manifest and scope checklist
基础 Slack 应用清单对于 Socket Mode 和 HTTP Request URLs 相同。只有 `settings` 块（以及斜杠命令的 `url`）不同。
The base Slack app manifest is the same for Socket Mode and HTTP Request URLs. Only the `settings` block (and the slash command `url`) differs.
基础清单（Socket Mode 默认）：
Base manifest (Socket Mode default):
```json
{
@ -212,6 +212,7 @@ openclaw gateway
"pins:write",
"reactions:read",
"reactions:write",
"usergroups:read",
"users:read"
]
}
@ -239,7 +240,7 @@ openclaw gateway
}
```
对于 **HTTP Request URLs 模式**，将 `settings` 替换为 HTTP 变体，并为每个斜杠命令添加 `url`。需要公开 URL：
For **HTTP Request URLs mode**, replace `settings` with the HTTP variant and add `url` to each slash command. Public URL required:
```json
{
@ -269,21 +270,21 @@ openclaw gateway
}
```
### 其他清单设置
### Additional manifest settings
公开不同功能，以扩展上述默认值。
Surface different features that extend the above defaults.
默认清单启用 Slack App Home 的 **Home** 标签页，并订阅 `app_home_opened`。当工作区成员打开 Home 标签页时，OpenClaw 会通过 `views.publish` 发布一个安全的默认 Home 视图；其中不包含对话载荷或私有配置。**Messages** 标签页仍为 Slack 私信启用。
The default manifest enables the Slack App Home **Home** tab and subscribes to `app_home_opened`. When a workspace member opens the Home tab, OpenClaw publishes a safe default Home view with `views.publish`; no conversation payload or private configuration is included. The **Messages** tab remains enabled for Slack DMs.
<AccordionGroup>
<Accordion title="Optional native slash commands">
可以使用多个[原生斜杠命令](#commands-and-slash-behavior)，而不是单个已配置命令，但有一些细节：
Multiple [native slash commands](#commands-and-slash-behavior) can be used instead of a single configured command with nuance:
- 使用 `/agentstatus` 而不是 `/status`，因为 `/status` 命令已保留。
- 一次最多只能提供 25 个斜杠命令。
- Use `/agentstatus` instead of `/status` because the `/status` command is reserved.
- No more than 25 slash commands can be made available at once.
将你现有的 `features.slash_commands` 部分替换为[可用命令](/zh-CN/tools/slash-commands#command-list)的一个子集：
Replace your existing `features.slash_commands` section with a subset of [available commands](/zh-CN/tools/slash-commands#command-list):
<Tabs>
<Tab title="Socket Mode (default)">
@ -403,7 +404,7 @@ openclaw gateway
</Tab>
<Tab title="HTTP Request URLs">
使用与上方 Socket Mode 相同的 `slash_commands` 列表，并为每个条目添加 `"url": "https://gateway-host.example.com/slack/events"`。示例：
Use the same `slash_commands` list as Socket Mode above, and add `"url": "https://gateway-host.example.com/slack/events"` to every entry. Example:
```json
"slash_commands": [
@ -427,13 +428,13 @@ openclaw gateway
</Accordion>
<Accordion title="Optional authorship scopes (write operations)">
如果你希望出站消息使用当前智能体身份（自定义用户名和图标），而不是默认 Slack 应用身份，请添加 `chat:write.customize` bot scope。
Add the `chat:write.customize` bot scope if you want outgoing messages to use the active agent identity (custom username and icon) instead of the default Slack app identity.
如果你使用 emoji 图标，Slack 要求使用 `:emoji_name:` 语法。
If you use an emoji icon, Slack expects `:emoji_name:` syntax.
</Accordion>
<Accordion title="Optional user-token scopes (read operations)">
如果你配置了 `channels.slack.userToken`，典型的读取 scope 包括：
如果你配置了 `channels.slack.userToken`，典型的读取作用域为：
- `channels:history`, `groups:history`, `im:history`, `mpim:history`
- `channels:read`, `groups:read`, `im:read`, `mpim:read`
@ -454,21 +455,21 @@ openclaw gateway
字符串或 SecretRef 对象。
- 配置令牌会覆盖环境变量回退。
- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` 环境变量回退仅适用于默认账户。
- `userToken` (`xoxp-...`) 只能通过配置提供（没有环境变量回退），并默认采用只读行为（`userTokenReadOnly: true`）。
- `userToken`（`xoxp-...`）仅能通过配置设置（没有环境变量回退），默认采用只读行为（`userTokenReadOnly: true`）。
Status 快照行为：
- Slack 账户检查会按凭证跟踪 `*Source` 和 `*Status`
- Slack 账户检查会跟踪每个凭证的 `*Source` 和 `*Status`
字段（`botToken`、`appToken`、`signingSecret`、`userToken`）。
- Status 为 `available`、`configured_unavailable` 或 `missing`。
- `configured_unavailable` 表示该账户通过 SecretRef
或其他非内联密钥来源配置，但当前命令/运行时路径
无法解析实际值。
- 在 HTTP 模式中，会包含 `signingSecretStatus`；在 Socket Mode 中，
必需组合是 `botTokenStatus` + `appTokenStatus`。
- 在 HTTP 模式下，会包含 `signingSecretStatus`；在 Socket Mode 下，
必需的组合是 `botTokenStatus` + `appTokenStatus`。
<Tip>
对于操作/目录读取，配置后可以优先使用用户令牌。对于写入，仍优先使用机器人令牌；只有当 `userTokenReadOnly: false` 且机器人令牌不可用时，才允许用户令牌写入。
对于操作/目录读取，配置后可以优先使用用户令牌。对于写入，仍优先使用机器人令牌；仅当 `userTokenReadOnly: false` 且机器人令牌不可用时，才允许用户令牌写入。
</Tip>
## 操作和门控
@ -479,19 +480,19 @@ Slack 操作由 `channels.slack.actions.*` 控制。
| 组 | 默认值 |
| ---------- | ------- |
| messages | 启用 |
| reactions | 启用 |
| pins | 启用 |
| memberInfo | 启用 |
| emojiList | 启用 |
| messages | 已启用 |
| reactions | 已启用 |
| pins | 已启用 |
| memberInfo | 已启用 |
| emojiList | 已启用 |
当前 Slack 消息操作包括 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。`download-file` 接受入站文件占位符中显示的 Slack 文件 ID，并为图片返回图片预览，或为其他文件类型返回本地文件元数据。
当前 Slack 消息操作包括 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。`download-file` 接受入站文件占位符中显示的 Slack 文件 ID，并为图像返回图像预览，或为其他文件类型返回本地文件元数据。
## 访问控制和路由
<Tabs>
<Tab title="DM policy">
`channels.slack.dmPolicy` 控制私信访问。`channels.slack.allowFrom` 是规范私信允许列表。
`channels.slack.dmPolicy` 控制私信访问。`channels.slack.allowFrom` 是规范的私信允许列表。
- `pairing`（默认）
- `allowlist`
@ -509,10 +510,10 @@ Slack 操作由 `channels.slack.actions.*` 控制。
多账户优先级：
- `channels.slack.accounts.default.allowFrom` 仅适用于 `default` 账户。
- 命名账户在自己的 `allowFrom` 未设置时继承 `channels.slack.allowFrom`。
- 命名账户在自身未设置 `allowFrom` 时继承 `channels.slack.allowFrom`。
- 命名账户不会继承 `channels.slack.accounts.default.allowFrom`。
旧版 `channels.slack.dm.policy` 和 `channels.slack.dm.allowFrom` 仍会读取以保持兼容。`openclaw doctor --fix` 会在不改变访问权限的情况下，将它们迁移到 `dmPolicy` 和 `allowFrom`。
旧版 `channels.slack.dm.policy` 和 `channels.slack.dm.allowFrom` 仍会读取以保持兼容。`openclaw doctor --fix` 会在不改变访问权限的前提下，将它们迁移到 `dmPolicy` 和 `allowFrom`。
私信中的配对使用 `openclaw pairing approve slack <code>`。
@ -525,20 +526,20 @@ Slack 操作由 `channels.slack.actions.*` 控制。
- `allowlist`
- `disabled`
渠道允许列表位于 `channels.slack.channels` 下，并且配置键**必须使用稳定的 Slack 渠道 ID**（例如 `C12345678`）。
渠道允许列表位于 `channels.slack.channels` 下，并且**必须使用稳定的 Slack 渠道 ID**（例如 `C12345678`）作为配置键。
运行时注意事项：如果完全缺少 `channels.slack`（仅环境变量设置），运行时会回退到 `groupPolicy="allowlist"` 并记录警告（即使设置了 `channels.defaults.groupPolicy`）。
名称/ID 解析：
- 当令牌访问允许时，渠道允许列表条目和私信允许列表条目会在启动时解析
- 未解析的渠道名称条目会按配置保留，但默认在路由时忽略
- 入站授权和渠道路由默认优先使用 ID；直接用户名/slug 匹配需要 `channels.slack.dangerouslyAllowNameMatching: true`
- 未解析的渠道名称条目会按配置保留，但默认会在路由中被忽略
- 入站授权和渠道路由默认优先使用 ID；直接用户名/短标识匹配需要 `channels.slack.dangerouslyAllowNameMatching: true`
<Warning>
基于名称的键（`#channel-name` 或 `channel-name`）在 `groupPolicy: "allowlist"` 下**不会**匹配。渠道查找默认优先使用 ID，因此基于名称的键永远无法成功路由，该渠道中的所有消息都会被静默阻止。这不同于 `groupPolicy: "open"`，后者不需要渠道键即可路由，基于名称的键看起来会生效。
在 `groupPolicy: "allowlist"` 下，基于名称的键（`#channel-name` 或 `channel-name`）**不会**匹配。渠道查找默认优先使用 ID，因此基于名称的键永远无法成功路由，并且该渠道中的所有消息都会被静默阻止。这与 `groupPolicy: "open"` 不同，在后者中，路由不需要渠道键，基于名称的键看起来可以工作。
始终使用 Slack 渠道 ID 作为键。查找方法：在 Slack 中右键点击渠道 → **Copy link** — ID（`C...`）会出现在 URL 末尾。
始终使用 Slack 渠道 ID 作为键。查找方法：在 Slack 中右键点击渠道 → **复制链接** — ID（`C...`）会出现在 URL 末尾。
正确：
@ -574,26 +575,27 @@ Slack 操作由 `channels.slack.actions.*` 控制。
</Tab>
<Tab title="Mentions and channel users">
渠道消息默认由提及门控。
渠道消息默认受提及门控控制。
提及来源：
- 显式应用提及（`<@botId>`）
- 提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`）
- 隐式回复到 bot 线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用）
- Slack 用户组提及（`<!subteam^S...>`），当机器人用户是该用户组成员时；需要 `usergroups:read`
- 提及正则表达式模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`）
- 隐式回复机器人线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用）
单渠道控制（`channels.slack.channels.<id>`；名称仅通过启动解析或 `dangerouslyAllowNameMatching` 使用）：
按渠道控制项（`channels.slack.channels.<id>`；名称仅通过启动解析或 `dangerouslyAllowNameMatching` 使用）：
- `requireMention`
- `users`（允许列表）
- `allowBots`
- `skills`
- `systemPrompt`
- `tools`、`toolsBySender`
- `toolsBySender` 键格式：`id:`、`e164:`、`username:`、`name:`，或 `"*"` 通配符
（旧版无前缀键仍只映射到 `id:`）
- `tools`, `toolsBySender`
- `toolsBySender` 键格式：`id:`、`e164:`、`username:`、`name:` 或 `"*"` 通配符
（旧版无前缀键仍然只映射到 `id:`）
`allowBots` 对渠道和私有渠道采取保守策略：只有当发送 bot 被明确列入该房间的 `users` 允许列表，或 `channels.slack.allowFrom` 中至少一个显式 Slack 所有者 ID 当前是房间成员时，才接受 bot 发出的房间消息。通配符和显示名称形式的所有者条目不满足所有者存在条件。所有者存在检查使用 Slack `conversations.members`；请确保应用拥有与房间类型匹配的读取 scope（公开渠道用 `channels:read`，私有渠道用 `groups:read`）。如果成员查询失败，OpenClaw 会丢弃 bot 发出的房间消息。
对于渠道和私有渠道，`allowBots` 采取保守策略：只有当发送消息的机器人被明确列入该房间的 `users` 允许列表，或 `channels.slack.allowFrom` 中至少一个显式 Slack 所有者 ID 当前是房间成员时，才会接受机器人发送的房间消息。通配符和显示名称所有者条目不满足所有者存在条件。所有者存在性使用 Slack `conversations.members`；确保应用拥有与房间类型匹配的读取作用域（公共渠道为 `channels:read`，私有渠道为 `groups:read`）。如果成员查找失败，OpenClaw 会丢弃机器人发送的房间消息。
</Tab>
</Tabs>
@ -603,16 +605,16 @@ Slack 操作由 `channels.slack.actions.*` 控制。
- 私信按 `direct` 路由；渠道按 `channel` 路由；MPIM 按 `group` 路由。
- 使用默认 `session.dmScope=main` 时，Slack 私信会折叠到智能体主会话。
- 渠道会话：`agent:<agentId>:slack:channel:<channelId>`。
- 适用时，线程回复可以创建线程会话后缀（`:thread:<threadTs>`）。
- `channels.slack.thread.historyScope` 默认是 `thread`；`thread.inheritParent` 默认是 `false`。
- 线程回复在适用时可以创建线程会话后缀（`:thread:<threadTs>`）。
- `channels.slack.thread.historyScope` 默认为 `thread`；`thread.inheritParent` 默认为 `false`。
- `channels.slack.thread.initialHistoryLimit` 控制新线程会话启动时获取多少条现有线程消息（默认 `20`；设为 `0` 可禁用）。
- `channels.slack.thread.requireExplicitMention`（默认 `false`）：当为 `true` 时，抑制隐式线程提及，因此即使 bot 已参与该线程，bot 也只会响应线程内显式的 `@bot` 提及。否则，bot 已参与线程中的回复会绕过 `requireMention` 门控。
- `channels.slack.thread.requireExplicitMention`（默认 `false`）：当为 `true` 时，抑制隐式线程提及，因此机器人只会响应线程内显式的 `@bot` 提及，即使机器人已经参与了该线程。没有此设置时，机器人参与过的线程中的回复会绕过 `requireMention` 门控。
回复线程控制：
回复线程控制项：
- `channels.slack.replyToMode`：`off|first|all|batched`（默认 `off`）
- `channels.slack.replyToModeByChatType`：按 `direct|group|channel` 分别设置
- 私聊的旧版回退：`channels.slack.dm.replyToMode`
- `channels.slack.replyToModeByChatType`：按 `direct|group|channel` 设置
- 直接聊天的旧版回退：`channels.slack.dm.replyToMode`
支持手动回复标签：
@ -620,24 +622,24 @@ Slack 操作由 `channels.slack.actions.*` 控制。
- `[[reply_to:<id>]]`
<Note>
`replyToMode="off"` 会禁用 Slack 中的**所有**回复线程，包括显式 `[[reply_to_*]]` 标签。这不同于 Telegram，在 Telegram 中，显式标签在 `"off"` 模式下仍会生效。Slack 线程会把消息隐藏在渠道之外，而 Telegram 回复会保持内联可见。
`replyToMode="off"` 会禁用 Slack 中的**所有**回复线程，包括显式 `[[reply_to_*]]` 标签。这与 Telegram 不同，Telegram 在 `"off"` 模式下仍会遵循显式标签。Slack 线程会从渠道中隐藏消息，而 Telegram 回复会保持内联可见。
</Note>
## 确认表情回应
## 确认反应
`ackReaction` 会在 OpenClaw 处理入站消息时发送确认表情符号。
`ackReaction` 会在 OpenClaw 处理入站消息时发送确认表情。
解析顺序：
- `channels.slack.accounts.<accountId>.ackReaction`
- `channels.slack.ackReaction`
- `messages.ackReaction`
- 智能体身份表情符号回退（`agents.list[].identity.emoji`，否则为 "👀"）
- 智能体身份表情回退（`agents.list[].identity.emoji`，否则为 "👀"）
注意：
说明：
- Slack 需要短代码（例如 `"eyes"`）。
- 使用 `""` 可针对 Slack 账号或全局禁用该反应。
- 使用 `""` 可为 Slack 账号或全局禁用该反应。
## 文本流式传输
@ -651,11 +653,11 @@ Slack 操作由 `channels.slack.actions.*` 控制。
当 `channels.slack.streaming.mode` 为 `partial` 时，`channels.slack.streaming.nativeTransport` 控制 Slack 原生文本流式传输（默认：`true`）。
- 必须有可用的回复线程，才会显示原生文本流式传输和 Slack assistant 线程状态。线程选择仍遵循 `replyToMode`。
- 必须有可用的回复线程，才会显示原生文本流式传输和 Slack 助手线程状态。线程选择仍遵循 `replyToMode`。
- 当原生流式传输不可用时，渠道和群聊根消息仍可使用普通草稿预览。
- 顶层 Slack 私信默认不在线程内，因此不会显示线程样式预览；如果你希望那里显示可见进度，请使用线程回复或 `typingReaction`。
- 顶层 Slack 私信默认保持非线程模式，因此不会显示线程样式预览；如果你希望在那里看到可见进度，请使用线程回复或 `typingReaction`。
- 媒体和非文本载荷会回退到普通投递。
- 媒体/错误最终消息会取消待处理的预览编辑；符合条件的文本/分块最终消息仅在可以原地编辑预览时才会 flush。
- 媒体/错误最终消息会取消待处理的预览编辑；符合条件的文本/分块最终消息只有在可以原地编辑预览时才会刷新。
- 如果流式传输在回复中途失败，OpenClaw 会对剩余载荷回退到普通投递。
使用草稿预览而不是 Slack 原生文本流式传输：
@ -679,29 +681,29 @@ Slack 操作由 `channels.slack.actions.*` 控制。
- 布尔值 `channels.slack.streaming` 会自动迁移到 `channels.slack.streaming.mode` 和 `channels.slack.streaming.nativeTransport`。
- 旧版 `channels.slack.nativeStreaming` 会自动迁移到 `channels.slack.streaming.nativeTransport`。
## 输入状态反应回退
## 输入反应回退
`typingReaction` 会在 OpenClaw 处理回复时，向入站 Slack 消息添加一个临时反应，并在运行结束时将其移除。这在线程回复之外最有用，因为线程回复会使用默认的“正在输入...”状态指示器。
`typingReaction` 会在 OpenClaw 处理回复时向入站 Slack 消息添加临时反应，并在运行完成后移除它。这在线程回复之外最有用，因为线程回复会使用默认的 "is typing..." 状态指示器。
解析顺序：
- `channels.slack.accounts.<accountId>.typingReaction`
- `channels.slack.typingReaction`
注意：
说明：
- Slack 需要短代码（例如 `"hourglass_flowing_sand"`）。
- 该反应采用尽力而为方式，回复或失败路径完成后会自动尝试清理。
- 该反应是尽力而为，并会在回复或失败路径完成后自动尝试清理。
## 媒体、分块和投递
<AccordionGroup>
<Accordion title="入站附件">
Slack 文件附件会从 Slack 托管的私有 URL 下载（基于令牌认证的请求流程），并在获取成功且大小限制允许时写入媒体存储。文件占位符包含 Slack `fileId`，因此智能体可以用 `download-file` 获取原始文件。
<Accordion title="Inbound attachments">
Slack 文件附件会从 Slack 托管的私有 URL 下载（令牌认证的请求流程），并在获取成功且大小限制允许时写入媒体存储。文件占位符包含 Slack `fileId`，因此智能体可以使用 `download-file` 获取原始文件。
下载使用有界的空闲超时和总超时。如果 Slack 文件检索停滞或失败，OpenClaw 会继续处理消息，并回退到文件占位符。
下载使用有界空闲超时和总超时。如果 Slack 文件检索停滞或失败，OpenClaw 会继续处理消息，并回退到文件占位符。
运行时入站大小上限默认为 `20MB`，除非由 `channels.slack.mediaMaxMb` 覆盖。
运行时入站大小上限默认为 `20MB`，除非被 `channels.slack.mediaMaxMb` 覆盖。
</Accordion>
@ -709,24 +711,24 @@ Slack 操作由 `channels.slack.actions.*` 控制。
- 文本分块使用 `channels.slack.textChunkLimit`（默认 4000）
- `channels.slack.chunkMode="newline"` 启用段落优先拆分
- 文件发送使用 Slack 上传 API，并且可以包含线程回复（`thread_ts`）
- 配置后，出站媒体上限遵循 `channels.slack.mediaMaxMb`；否则，渠道发送使用媒体流水线中的 MIME 类型默认值
- 配置后，出站媒体上限遵循 `channels.slack.mediaMaxMb`；否则渠道发送会使用媒体流水线中的 MIME 类型默认值
</Accordion>
<Accordion title="投递目标">
首选的显式目标：
首选显式目标：
- `user:<id>` 用于私信
- `channel:<id>` 用于渠道
发送到用户目标时，会通过 Slack conversation API 打开 Slack 私信。
发送到用户目标时，会通过 Slack 会话 API 打开 Slack 私信。
</Accordion>
</AccordionGroup>
## 命令和 slash 行为
## 命令和斜杠行为
Slash 命令在 Slack 中显示为单个配置命令或多个原生命令。配置 `channels.slack.slashCommand` 可更改命令默认值：
斜杠命令在 Slack 中显示为单个已配置命令或多个原生命令。配置 `channels.slack.slashCommand` 可更改命令默认值：
- `enabled: false`
- `name: "openclaw"`
@ -737,7 +739,7 @@ Slash 命令在 Slack 中显示为单个配置命令或多个原生命令。配
/openclaw /help
```
原生命令需要在你的 Slack 应用中配置[其他清单设置](#additional-manifest-settings)，并改用 `channels.slack.commands.native: true` 启用，或在全局配置中使用 `commands.native: true`。
原生命令需要在你的 Slack 应用中配置[其他清单设置](#additional-manifest-settings)，并通过 `channels.slack.commands.native: true` 启用，或改用全局配置中的 `commands.native: true` 启用。
- Slack 的原生命令自动模式为**关闭**，因此 `commands.native: "auto"` 不会启用 Slack 原生命令。
@ -747,20 +749,20 @@ Slash 命令在 Slack 中显示为单个配置命令或多个原生命令。配
原生参数菜单使用自适应渲染策略，在分发所选选项值之前显示确认模态框：
- 最多 5 个选项：按钮区块
- 最多 5 个选项：按钮块
- 6-100 个选项：静态选择菜单
- 超过 100 个选项：当交互选项处理程序可用时，使用带异步选项过滤的外部选择
- 超出 Slack 限制：编码后的选项值回退为按钮
- 超过 100 个选项：当交互选项处理程序可用时，使用带异步选项筛选的外部选择
- 超出 Slack 限制：编码后的选项值会回退为按钮
```txt
/think
```
Slash 会话使用类似 `agent:<agentId>:slack:slash:<userId>` 的隔离键，并且仍会使用 `CommandTargetSessionKey` 将命令执行路由到目标对话会话。
斜杠会话使用类似 `agent:<agentId>:slack:slash:<userId>` 的隔离键，并且仍会使用 `CommandTargetSessionKey` 将命令执行路由到目标对话会话。
## 交互式回复
Slack 可以渲染 agent 编写的交互式回复控件，但此功能默认禁用。
Slack 可以渲染智能体编写的交互式回复控件，但此功能默认禁用。
全局启用：
@ -776,7 +778,7 @@ Slack 可以渲染 agent 编写的交互式回复控件，但此功能默认禁
}
```
或仅为一个 Slack 账号启用：
或者仅为一个 Slack 账号启用：
```json5
{
@ -794,43 +796,43 @@ Slack 可以渲染 agent 编写的交互式回复控件，但此功能默认禁
}
```
启用后，agent 可以发出仅限 Slack 的回复指令：
启用后，智能体可以发出仅适用于 Slack 的回复指令：
- `[[slack_buttons: Approve:approve, Reject:reject]]`
- `[[slack_select: Choose a target | Canary:canary, Production:production]]`
这些指令会编译为 Slack Block Kit，并通过现有 Slack 交互事件路径回传点击或选择。
这些指令会编译为 Slack Block Kit，并通过现有 Slack 交互事件路径路由点击或选择。
注意事项：
注意：
- 这是 Slack 专用 UI。其他渠道不会将 Slack Block Kit 指令转换为自己的按钮系统。
- 交互式回调值是 OpenClaw 生成的不透明令牌，不是 agent 编写的原始值。
- 如果生成的交互式区块会超过 Slack Block Kit 限制，OpenClaw 会回退为原始文本回复，而不是发送无效的 blocks 载荷。
- 交互式回调值是 OpenClaw 生成的不透明令牌，而不是智能体编写的原始值。
- 如果生成的交互式块会超出 Slack Block Kit 限制，OpenClaw 会回退到原始文本回复，而不是发送无效的块载荷。
## Slack 中的执行批准
## Slack 中的 Exec 审批
Slack 可以作为带有交互式按钮和交互的原生批准客户端，而不是回退到 Web UI 或终端。
Slack 可以作为带有交互式按钮和交互的原生审批客户端，而不是回退到 Web UI 或终端。
- 执行批准使用 `channels.slack.execApprovals.*` 进行原生私信/渠道路由。
- 当请求已经落在 Slack 中，并且批准 ID 类型为 `plugin:` 时，插件批准仍可通过同一 Slack 原生按钮界面完成。
- 仍会强制执行批准者授权：只有被识别为批准者的用户才能通过 Slack 批准或拒绝请求。
- Exec 审批使用 `channels.slack.execApprovals.*` 进行原生私信/渠道路由。
- 当请求已落在 Slack 中且审批 ID 种类为 `plugin:` 时，插件审批仍可以通过同一个 Slack 原生按钮界面解析。
- 审批人授权仍会强制执行：只有被识别为审批人的用户才能通过 Slack 批准或拒绝请求。
这会使用与其他渠道相同的共享批准按钮界面。当你的 Slack 应用设置中启用 `interactivity` 时，批准提示会在对话中直接渲染为 Block Kit 按钮。
当这些按钮存在时，它们是主要批准 UX；OpenClaw
只应在工具结果表明聊天批准不可用或手动批准是唯一路径时
包含手动 `/approve` 命令。
这使用与其他渠道相同的共享审批按钮界面。当你的 Slack 应用设置中启用 `interactivity` 后，审批提示会直接在对话中渲染为 Block Kit 按钮。
当这些按钮存在时，它们是主要审批 UX；OpenClaw
只有在工具结果表示聊天审批不可用或手动审批是唯一路径时，
才应包含手动 `/approve` 命令。
配置路径：
- `channels.slack.execApprovals.enabled`
- `channels.slack.execApprovals.approvers`（可选；可行时回退到 `commands.ownerAllowFrom`）
- `channels.slack.execApprovals.approvers`（可选；可能时回退到 `commands.ownerAllowFrom`）
- `channels.slack.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`）
- `agentFilter`、`sessionFilter`
当 `enabled` 未设置或为 `"auto"`，且至少解析出一个批准者时，Slack 会自动启用原生执行批准。设置 `enabled: false` 可显式禁用 Slack 作为原生批准客户端。
设置 `enabled: true` 可在批准者解析成功时强制启用原生批准。
当 `enabled` 未设置或为 `"auto"`，且至少能解析出一个审批人时，Slack 会自动启用原生 exec 审批。设置 `enabled: false` 可显式禁用 Slack 作为原生审批客户端。
设置 `enabled: true` 可在能解析出审批人时强制启用原生审批。
没有显式 Slack 执行批准配置时的默认行为：
没有显式 Slack exec 审批配置时的默认行为：
```json5
{
@ -840,7 +842,8 @@ Slack 可以作为带有交互式按钮和交互的原生批准客户端，而
}
```
只有在你想覆盖批准者、添加过滤器，或选择加入来源聊天投递时，才需要显式 Slack 原生配置：
仅当你想覆盖审批人、添加筛选器或
选择加入源聊天投递时，才需要显式 Slack 原生配置：
```json5
{
@ -856,22 +859,24 @@ Slack 可以作为带有交互式按钮和交互的原生批准客户端，而
}
```
共享 `approvals.exec` 转发是独立的。仅当执行批准提示还必须路由到其他聊天或显式带外目标时才使用它。共享 `approvals.plugin` 转发也是独立的；当这些请求已经落在 Slack 中时，Slack 原生按钮仍可完成插件批准。
共享的 `approvals.exec` 转发是独立的。仅当 exec 审批提示还必须
路由到其他聊天或显式带外目标时才使用它。共享的 `approvals.plugin` 转发也是
独立的；当这些请求已落在 Slack 中时，Slack 原生按钮仍可以解析插件审批。
同一聊天中的 `/approve` 也适用于已经支持命令的 Slack 渠道和私信。完整批准转发模型见[执行批准](/zh-CN/tools/exec-approvals)。
同聊天 `/approve` 也适用于已支持命令的 Slack 渠道和私信。参阅 [Exec 审批](/zh-CN/tools/exec-approvals)了解完整审批转发模型。
## 事件和运维行为
## 事件和运行行为
- 消息编辑/删除会映射为系统事件。
- 线程广播（“Also send to channel” 线程回复）会作为普通用户消息处理。
- Reaction 添加/移除事件会映射为系统事件。
- 成员加入/离开、渠道创建/重命名，以及 pin 添加/移除事件会映射为系统事件。
- 启用 `configWrites` 时，`channel_id_changed` 可以迁移渠道配置键。
- 渠道 topic/purpose 元数据会被视为不受信任的上下文，并可能被注入路由上下文。
- 适用时，线程起始消息和初始线程历史上下文注入会按配置的发送者允许列表过滤。
- 区块操作和模态框交互会发出结构化的 `Slack interaction: ...` 系统事件，并带有丰富载荷字段：
- 区块操作：所选值、标签、选择器值和 `workflow_*` 元数据
- 模态框 `view_submission` 和 `view_closed` 事件，包含路由的渠道元数据和表单输入
- 线程广播（“同时发送到渠道”的线程回复）会作为普通用户消息处理。
- 表情回应添加/移除事件会映射为系统事件。
- 成员加入/离开、渠道创建/重命名以及置顶添加/移除事件会映射为系统事件。
- 启用 `configWrites` 后，`channel_id_changed` 可以迁移渠道配置键。
- 渠道主题/用途元数据会被视为不可信上下文，并可注入到路由上下文中。
- 适用时，线程发起消息和初始线程历史上下文种子会按配置的发送者允许列表筛选。
- 块操作和模态框交互会发出结构化 `Slack interaction: ...` 系统事件，并带有丰富的载荷字段：
- 块操作：所选值、标签、选择器值以及 `workflow_*` 元数据
- 模态框 `view_submission` 和 `view_closed` 事件，带有路由后的渠道元数据和表单输入
## 配置参考
@ -879,9 +884,9 @@ Slack 可以作为带有交互式按钮和交互的原生批准客户端，而
<Accordion title="高信号 Slack 字段">
- 模式/凭证：`mode`、`botToken`、`appToken`、`signingSecret`、`webhookPath`、`accounts.*`
- 模式/认证：`mode`、`botToken`、`appToken`、`signingSecret`、`webhookPath`、`accounts.*`
- 私信访问：`dm.enabled`、`dmPolicy`、`allowFrom`（旧版：`dm.policy`、`dm.allowFrom`）、`dm.groupEnabled`、`dm.groupChannels`
- 兼容性开关：`dangerouslyAllowNameMatching`（应急开关；除非需要，否则保持关闭）
- 兼容性开关：`dangerouslyAllowNameMatching`（紧急开关；除非需要，否则保持关闭）
- 渠道访问：`groupPolicy`、`channels.*`、`channels.*.users`、`channels.*.requireMention`
- 线程/历史：`replyToMode`、`replyToModeByChatType`、`thread.*`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit`
- 投递：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`streaming`、`streaming.nativeTransport`、`streaming.preview.toolProgress`
@ -896,11 +901,11 @@ Slack 可以作为带有交互式按钮和交互的原生批准客户端，而
按顺序检查：
- `groupPolicy`
- 渠道允许列表（`channels.slack.channels`）— **键必须是渠道 ID**（`C12345678`），而不是名称（`#channel-name`）。在 `groupPolicy: "allowlist"` 下，基于名称的键会静默失败，因为默认情况下渠道路由以 ID 优先。查找 ID 的方法：在 Slack 中右键点击渠道 → **Copy link** — URL 末尾的 `C...` 值就是渠道 ID。
- 渠道允许列表（`channels.slack.channels`）— **键必须是渠道 ID**（`C12345678`），而不是名称（`#channel-name`）。在 `groupPolicy: "allowlist"` 下，基于名称的键会静默失败，因为默认情况下渠道路由以 ID 优先。要查找 ID：在 Slack 中右键点击渠道 → **Copy link** — URL 末尾的 `C...` 值就是渠道 ID。
- `requireMention`
- 每个渠道的 `users` 允许列表
- 每渠道 `users` 允许列表
有用命令：
有用的命令：
```bash
openclaw channels status --probe
@ -915,9 +920,9 @@ openclaw doctor
- `channels.slack.dm.enabled`
- `channels.slack.dmPolicy`（或旧版 `channels.slack.dm.policy`）
- 配对批准 / 允许列表条目
- 配对审批 / 允许列表条目
- Slack Assistant 私信事件：提到 `drop message_changed` 的详细日志
通常意味着 Slack 发送了一个已编辑的 Assistant 线程事件，但消息元数据中
通常意味着 Slack 发送了已编辑的 Assistant 线程事件，但消息元数据中
没有可恢复的人类发送者
```bash
@ -927,12 +932,11 @@ openclaw pairing list slack
</Accordion>
<Accordion title="Socket 模式未连接">
在 Slack 应用设置中验证 bot + app 令牌以及 Socket Mode 是否启用。
在 Slack 应用设置中验证 bot + app 令牌和 Socket Mode 启用状态。
如果 `openclaw channels status --probe --json` 显示 `botTokenStatus` 或
`appTokenStatus: "configured_unavailable"`，表示 Slack 账号
已配置，但当前运行时无法解析由 SecretRef 支持的
值。
`appTokenStatus: "configured_unavailable"`，则 Slack 账号已配置，
但当前运行时无法解析由 SecretRef 支持的值。
</Accordion>
@ -941,110 +945,109 @@ openclaw pairing list slack
- 签名密钥
- webhook 路径
- Slack Request URLs（Events + Interactivity + Slash Commands）
- Slack Request URLs（事件 + 交互 + 斜杠命令）
- 每个 HTTP 账号唯一的 `webhookPath`
如果账号快照中出现 `signingSecretStatus: "configured_unavailable"`，
表示 HTTP 账号已配置，但当前运行时无法
解析由 SecretRef 支持的签名密钥。
则 HTTP 账号已配置，但当前运行时无法解析由 SecretRef 支持的签名密钥。
</Accordion>
<Accordion title="原生/slash 命令未触发">
确认你的预期是：
<Accordion title="原生/斜杠命令未触发">
验证你的预期是：
- 原生命令模式（`channels.slack.commands.native: true`），并在 Slack 中注册匹配的 slash 命令
- 或单个 slash 命令模式（`channels.slack.slashCommand.enabled: true`）
- 原生命令模式（`channels.slack.commands.native: true`），并在 Slack 中注册匹配的斜杠命令
- 或单斜杠命令模式（`channels.slack.slashCommand.enabled: true`）
同时检查 `commands.useAccessGroups` 以及渠道/用户允许列表。
还要检查 `commands.useAccessGroups` 和渠道/用户允许列表。
</Accordion>
</AccordionGroup>
## 附件视觉参考
当 Slack 文件下载成功且大小限制允许时，Slack 可以将已下载媒体附加到 agent 轮次中。图片文件可以通过媒体理解路径传递，或直接传递给具备视觉能力的回复模型；其他文件会保留为可下载文件上下文，而不是被视为图片输入。
当 Slack 文件下载成功且大小限制允许时，Slack 可以将下载的媒体附加到智能体轮次。图像文件可以通过媒体理解路径传递，也可以直接传递给具备视觉能力的回复模型；其他文件会保留为可下载文件上下文，而不是作为图像输入处理。
### 支持的媒体类型
| 媒体类型 | 来源 | 当前行为 | 备注 |
| 媒体类型 | 来源 | 当前行为 | 备注 |
| ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| JPEG / PNG / GIF / WebP 图片 | Slack 文件 URL | 下载并附加到轮次中，以供具备视觉能力的处理 | 单文件上限：`channels.slack.mediaMaxMb`（默认 20 MB） |
| PDF 文件 | Slack 文件 URL | 下载并公开为文件上下文，供 `download-file` 或 `pdf` 等工具使用 | Slack 入站不会自动将 PDF 转换为图片视觉输入 |
| 其他文件 | Slack 文件 URL | 尽可能下载并公开为文件上下文 | 二进制文件不会被视为图片输入 |
| 线程回复 | 线程起始文件 | 当回复没有直接媒体时，可以将根消息文件水合为上下文 | 仅文件起始消息使用附件占位符 |
| 多图片消息 | 多个 Slack 文件 | 每个文件都会独立评估 | Slack 处理每条消息最多限制为八个文件 |
| JPEG / PNG / GIF / WebP 图片 | Slack 文件 URL | 下载并附加到该轮对话，以便支持视觉能力的处理 | 单文件上限：`channels.slack.mediaMaxMb`（默认 20 MB） |
| PDF 文件 | Slack 文件 URL | 下载并作为文件上下文暴露给 `download-file` 或 `pdf` 等工具 | Slack 入站不会自动将 PDF 转换为图像视觉输入 |
| 其他文件 | Slack 文件 URL | 在可能时下载并作为文件上下文暴露 | 二进制文件不会被视为图像输入 |
| 线程回复 | 线程起始消息文件 | 当回复没有直接媒体时，根消息文件可以作为上下文补充 | 仅包含文件的起始消息会使用附件占位符 |
| 多图像消息 | 多个 Slack 文件 | 每个文件都会独立评估 | Slack 处理限制为每条消息最多八个文件 |
### 入站流水线
当带有文件附件的 Slack 消息到达时：
1. OpenClaw 使用 bot 令牌（`xoxb-...`）从 Slack 的私有 URL 下载文件。
2. 成功后，文件会写入媒体存储。
1. OpenClaw 使用机器人令牌（`xoxb-...`）从 Slack 的私有 URL 下载文件。
2. 下载成功后，文件会写入媒体存储。
3. 下载的媒体路径和内容类型会添加到入站上下文。
4. 支持图像的模型/工具路径可以使用该上下文中的图像附件。
5. 非图像文件仍会作为文件元数据或媒体引用提供给能处理它们的工具。
5. 非图像文件仍会作为文件元数据或媒体引用提供给能够处理它们的工具。
### 线程根附件继承
当消息在线程中到达（有一个 `thread_ts` 父级）时：
当消息在线程中到达时（具有 `thread_ts` 父级）：
- 如果回复本身没有直接媒体，而包含的根消息有文件，Slack 可以将根文件注入为线程起始上下文。
- 如果回复本身没有直接媒体，而包含的根消息有文件，Slack 可以将根文件作为线程起始上下文补充。
- 直接回复附件优先于根消息附件。
- 只有文件而没有文本的根消息会以附件占位符表示，因此回退仍可包含其文件。
- 仅包含文件且没有文本的根消息会用附件占位符表示，以便回退仍可包含其文件。
### 多附件处理
当单条 Slack 消息包含多个文件附件时：
- 每个附件都会通过媒体管线独立处理。
- 每个附件都会通过媒体流水线独立处理。
- 下载的媒体引用会聚合到消息上下文中。
- 处理顺序遵循事件载荷中 Slack 的文件顺序。
- 一个附件下载失败不会阻塞其他附件。
- 处理顺序遵循事件载荷中的 Slack 文件顺序。
- 一个附件下载失败不会阻止其他附件。
### 大小、下载和模型限制
- **大小上限**：默认每个文件 20 MB。可通过 `channels.slack.mediaMaxMb` 配置。
- **下载失败**：Slack 无法提供的文件、过期 URL、无法访问的文件、超大文件，以及 Slack 认证/登录 HTML 响应会被跳过，而不是报告为不支持的格式。
- **视觉模型**：图像分析会使用支持视觉的当前回复模型，或使用在 `agents.defaults.imageModel` 配置的图像模型。
- **下载失败**：Slack 无法提供的文件、过期 URL、无法访问的文件、超大文件以及 Slack 身份验证/登录 HTML 响应会被跳过，而不是报告为不支持的格式。
- **视觉模型**：图像分析会在活动回复模型支持视觉时使用该模型，或使用 `agents.defaults.imageModel` 配置的图像模型。
### 已知限制
| 场景 | 当前行为 | 解决方法 |
| 场景 | 当前行为 | 解决方法 |
| -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| 过期的 Slack 文件 URL | 文件被跳过；不显示错误 | 在 Slack 中重新上传文件 |
| 未配置视觉模型 | 图像附件会存储为媒体引用，但不会作为图像分析 | 配置 `agents.defaults.imageModel`，或使用支持视觉的回复模型 |
| 非常大的图像（默认 > 20 MB） | 按大小上限跳过 | 如果 Slack 允许，增加 `channels.slack.mediaMaxMb` |
| 转发/共享的附件 | 文本和 Slack 托管的图像/文件媒体会尽力处理 | 直接在 OpenClaw 线程中重新分享 |
| PDF 附件 | 存储为文件/媒体上下文，不会自动通过图像视觉路由 | 对文件元数据使用 `download-file`，或使用 `pdf` 工具进行 PDF 分析 |
| 过期的 Slack 文件 URL | 文件被跳过；不显示错误 | 在 Slack 中重新上传文件 |
| 未配置视觉模型 | 图像附件会存储为媒体引用，但不会作为图像分析 | 配置 `agents.defaults.imageModel`，或使用支持视觉的回复模型 |
| 非常大的图像（默认 > 20 MB） | 按大小上限跳过 | 如果 Slack 允许，请提高 `channels.slack.mediaMaxMb` |
| 转发/共享的附件 | 文本和 Slack 托管的图像/文件媒体会尽力处理 | 直接在 OpenClaw 线程中重新共享 |
| PDF 附件 | 存储为文件/媒体上下文，不会自动通过图像视觉路由 | 使用 `download-file` 获取文件元数据，或使用 `pdf` 工具进行 PDF 分析 |
### 相关文档
- [媒体理解管线](/zh-CN/nodes/media-understanding)
- [媒体理解流水线](/zh-CN/nodes/media-understanding)
- [PDF 工具](/zh-CN/tools/pdf)
- 长篇任务：[#51349](https://github.com/openclaw/openclaw/issues/51349) — 启用 Slack 附件视觉
- Epic：[#51349](https://github.com/openclaw/openclaw/issues/51349) — Slack 附件视觉启用
- 回归测试：[#51353](https://github.com/openclaw/openclaw/issues/51353)
- 实时验证：[#51354](https://github.com/openclaw/openclaw/issues/51354)
## 相关内容
## 相关
<CardGroup cols={2}>
<Card title="Pairing" icon="link" href="/zh-CN/channels/pairing">
将 Slack 用户与 Gateway 网关配对。
<Card title="配对" icon="link" href="/zh-CN/channels/pairing">
将 Slack 用户配对到 Gateway 网关。
</Card>
<Card title="Groups" icon="users" href="/zh-CN/channels/groups">
<Card title="群组" icon="users" href="/zh-CN/channels/groups">
渠道和群组私信行为。
</Card>
<Card title="Channel routing" icon="route" href="/zh-CN/channels/channel-routing">
<Card title="渠道路由" icon="route" href="/zh-CN/channels/channel-routing">
将入站消息路由到智能体。
</Card>
<Card title="Security" icon="shield" href="/zh-CN/gateway/security">
<Card title="安全" icon="shield" href="/zh-CN/gateway/security">
威胁模型和加固。
</Card>
<Card title="Configuration" icon="sliders" href="/zh-CN/gateway/configuration">
<Card title="配置" icon="sliders" href="/zh-CN/gateway/configuration">
配置布局和优先级。
</Card>
<Card title="Slash commands" icon="terminal" href="/zh-CN/tools/slash-commands">
<Card title="斜杠命令" icon="terminal" href="/zh-CN/tools/slash-commands">
命令目录和行为。
</Card>
</CardGroup>

327
docs/zh-CN/gateway/config-channels.md
View File

@ -1,22 +1,22 @@
---
read_when:
- 配置渠道插件（身份验证、访问控制、多账号）
- 每个渠道的配置键名故障排除
- 配置渠道插件（身份验证、访问控制、多账户）
- 按渠道配置键名的故障排除
- 审计私信策略、群组策略或提及门控
summary: 渠道配置：Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 等渠道的访问控制、配对和按渠道配置的密钥
summary: 渠道配置：Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 等渠道的访问控制、配对和按渠道设置的密钥
title: 配置 — 渠道
x-i18n:
generated_at: "2026-05-01T18:34:53Z"
generated_at: "2026-05-02T02:58:28Z"
model: gpt-5.5
provider: openai
source_hash: bca1314b67f8d2dd4699888a728af28a75b973b001901581536df31c2d0e8ce8
source_hash: bc790f19aed583b4c52988c170c8883bf56282cfbf3eae26f655f7a4660bd4ed
source_path: gateway/config-channels.md
workflow: 16
---
按 `channels.*` 划分的各渠道配置键。涵盖私信和群组访问、多账号设置、提及门控，以及 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他内置渠道插件的各渠道键。
每个渠道配置键位于 `channels.*` 下。涵盖私信和群组访问、多账号设置、提及门控，以及 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他内置渠道插件的各渠道键。
关于智能体、工具、Gateway 网关运行时和其他顶层键，请参阅
对于智能体、工具、Gateway 网关运行时和其他顶级键，请参阅
[配置参考](/zh-CN/gateway/configuration-reference)。
## 渠道
@ -27,28 +27,28 @@ x-i18n:
所有渠道都支持私信策略和群组策略：
| 私信策略 | 行为 |
| ------------------- | --------------------------------------------------------------- |
| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 |
| `allowlist` | 仅允许 `allowFrom`（或已配对允许存储）中的发送者 |
| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） |
| `disabled` | 忽略所有传入私信 |
| 私信策略 | 行为 |
| ------------------- | ----------------------------------------------------------- |
| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 |
| `allowlist` | 仅允许 `allowFrom`（或已配对允许存储）中的发送者 |
| `open` | 允许所有入站私信（需要 `allowFrom: ["*"]`） |
| `disabled` | 忽略所有入站私信 |
| 群组策略 | 行为 |
| --------------------- | ------------------------------------------------------ |
| `allowlist`（默认） | 仅允许匹配已配置允许列表的群组 |
| `open` | 绕过群组允许列表（提及门控仍然适用） |
| `disabled` | 阻止所有群组/房间消息 |
| 群组策略 | 行为 |
| --------------------- | -------------------------------------------------- |
| `allowlist`（默认） | 仅允许匹配已配置允许名单的群组 |
| `open` | 绕过群组允许名单（提及门控仍然适用） |
| `disabled` | 阻止所有群组/房间消息 |
<Note>
`channels.defaults.groupPolicy` 会在提供商的 `groupPolicy` 未设置时设为默认值。
配对码会在 1 小时后过期。待处理的私信配对请求限制为**每个渠道 3 个**。
如果提供商块完全缺失（不存在 `channels.<provider>`），运行时群组策略会回退到 `allowlist`（故障关闭），并在启动时发出警告。
`channels.defaults.groupPolicy` 会在提供商的 `groupPolicy` 未设置时设置默认值。
配对码会在 1 小时后过期。待处理的私信配对请求上限为 **每个渠道 3 个**。
如果提供商块完全缺失（不存在 `channels.<provider>`），运行时群组策略会回退到 `allowlist`（失败关闭），并在启动时发出警告。
</Note>
### 渠道模型覆盖
使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当会话尚未有模型覆盖时（例如通过 `/model` 设置），会应用该渠道映射。
使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当会话还没有模型覆盖时（例如通过 `/model` 设置），会应用渠道映射。
```json5
{
@ -71,7 +71,7 @@ x-i18n:
### 渠道默认值和 Heartbeat
使用 `channels.defaults` 为各提供商设置共享的群组策略和 Heartbeat 行为：
使用 `channels.defaults` 设置跨提供商共享的群组策略和 Heartbeat 行为：
```json5
{
@ -89,15 +89,15 @@ x-i18n:
}
```
- `channels.defaults.groupPolicy`：当提供商级 `groupPolicy` 未设置时的回退群组策略。
- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/话题串/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与允许列表相同，但保留显式引用/回复上下文）。各渠道覆盖：`channels.<channel>.contextVisibility`。
- `channels.defaults.heartbeat.showOk`：在 Heartbeat 输出中包含健康的渠道状态。
- `channels.defaults.groupPolicy`：提供商级 `groupPolicy` 未设置时的回退群组策略。
- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许名单发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留明确引用/回复上下文）。按渠道覆盖：`channels.<channel>.contextVisibility`。
- `channels.defaults.heartbeat.showOk`：在 Heartbeat 输出中包含健康渠道状态。
- `channels.defaults.heartbeat.showAlerts`：在 Heartbeat 输出中包含降级/错误状态。
- `channels.defaults.heartbeat.useIndicator`：渲染紧凑的指示器样式 Heartbeat 输出。
### WhatsApp
WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在已链接会话时，它会自动启动。
WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。存在已链接会话时会自动启动。
```json5
{
@ -155,10 +155,10 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在
}
```
- 外发命令默认使用账号 `default`（如果存在）；否则使用第一个已配置账号 ID（排序后）。
- 可选的 `channels.whatsapp.defaultAccount` 会在其匹配已配置账号 ID 时覆盖该回退默认账号选择。
- 旧版单账号 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。
- 各账号覆盖：`channels.whatsapp.accounts.<id>.sendReadReceipts`、`channels.whatsapp.accounts.<id>.dmPolicy`、`channels.whatsapp.accounts.<id>.allowFrom`。
- 出站命令默认使用账号 `default`（如果存在）；否则使用第一个已配置账号 ID（排序后）。
- 可选的 `channels.whatsapp.defaultAccount` 会在匹配已配置账号 ID 时覆盖该回退默认账号选择。
- 旧版单账号 Baileys 凭证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。
- 按账号覆盖：`channels.whatsapp.accounts.<id>.sendReadReceipts`、`channels.whatsapp.accounts.<id>.dmPolicy`、`channels.whatsapp.accounts.<id>.allowFrom`。
</Accordion>
@ -217,14 +217,14 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在
}
```
- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅限普通文件；拒绝符号链接），默认账号会以 `TELEGRAM_BOT_TOKEN` 作为回退。
- `apiRoot` 仅是 Telegram Bot API 根地址。使用 `https://api.telegram.org` 或你的自托管/代理根地址，而不是 `https://api.telegram.org/bot<TOKEN>`；`openclaw doctor --fix` 会移除意外尾随的 `/bot<TOKEN>` 后缀。
- 可选的 `channels.telegram.defaultAccount` 会在其匹配已配置账号 ID 时覆盖默认账号选择。
- 在多账号设置（2 个以上账号 ID）中，设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；当其缺失或无效时，`openclaw doctor` 会发出警告。
- 机器人令牌：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅普通文件；符号链接会被拒绝），默认账号的回退值为 `TELEGRAM_BOT_TOKEN`。
- `apiRoot` 仅是 Telegram Bot API 根地址。使用 `https://api.telegram.org` 或你的自托管/代理根地址，不要使用 `https://api.telegram.org/bot<TOKEN>`；`openclaw doctor --fix` 会移除意外尾随的 `/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 智能体](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享。
- 带有 `type: "acp"` 的顶级 `bindings[]` 条目会为论坛主题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义在 [ACP 智能体](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享。
- Telegram 流式预览使用 `sendMessage` + `editMessageText`（适用于私聊和群聊）。
- 重试策略：参阅[重试策略](/zh-CN/concepts/retry)。
- 重试策略：请参阅[重试策略](/zh-CN/concepts/retry)。
### Discord
@ -328,39 +328,40 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在
}
```
- Token：`channels.discord.token`，默认账号的回退值为 `DISCORD_BOT_TOKEN`。
- 提供显式 Discord `token` 的直接出站调用会使用该 token 执行调用；账号重试/策略设置仍来自活动运行时快照中选定的账号。
- 可选的 `channels.discord.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。
- 使用 `user:<id>`（私信）或 `channel:<id>`（服务器渠道）作为投递目标；裸数字 ID 会被拒绝。
- 服务器 slug 为小写并将空格替换为 `-`；渠道键使用 slug 化后的名称（不带 `#`）。优先使用服务器 ID。
- 默认忽略机器人发送的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 仅接受提及机器人的机器人消息（仍会过滤自己发送的消息）。
- `channels.discord.guilds.<id>.ignoreOtherMentions`（以及渠道覆盖项）会丢弃提及其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。
- `maxLinesPerMessage`（默认 17）即使在低于 2000 个字符时也会拆分过高的消息。
- 令牌：`channels.discord.token`，默认账户回退使用 `DISCORD_BOT_TOKEN`。
- 提供显式 Discord `token` 的直接出站调用会为该调用使用该令牌；账户重试/策略设置仍来自活动运行时快照中的所选账户。
- 可选的 `channels.discord.defaultAccount` 在匹配已配置账户 ID 时会覆盖默认账户选择。
- 使用 `user:<id>`（私信）或 `channel:<id>`（公会渠道）作为投递目标；裸数字 ID 会被拒绝。
- 公会 slug 为小写，并将空格替换为 `-`；渠道键使用 slug 化名称（不含 `#`）。优先使用公会 ID。
- 默认忽略机器人发送的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 仅接受提及机器人的机器人消息（仍会过滤自身消息）。
- `channels.discord.guilds.<id>.ignoreOtherMentions`（以及渠道覆盖）会丢弃提及其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。
- `channels.discord.mentionAliases` 会在发送前将稳定的出站 `@handle` 文本映射到 Discord 用户 ID，因此即使瞬时目录缓存为空，也能确定性地提及已知队友。按账户覆盖位于 `channels.discord.accounts.<accountId>.mentionAliases` 下。
- `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 })` 自动创建/绑定线程的选择加入开关
- 带有 `type: "acp"` 的顶层 `bindings[]` 条目为渠道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用渠道/线程 ID）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享。
- `enabled`：线程绑定会话功能的 Discord 覆盖（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定投递/路由）
- `idleHours`：按小时设置非活动自动取消聚焦的 Discord 覆盖（`0` 表示禁用）
- `maxAgeHours`：按小时设置硬性最大时长的 Discord 覆盖（`0` 表示禁用）
- `spawnSubagentSessions`：用于 `sessions_spawn({ thread: true })` 自动创建/绑定线程的选择启用开关
- 顶层 `bindings[]` 条目配合 `type: "acp"` 为渠道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用渠道/线程 ID）。字段语义在 [ACP 智能体](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享。
- `channels.discord.ui.components.accentColor` 设置 Discord components v2 容器的强调色。
- `channels.discord.voice` 启用 Discord 语音渠道对话以及可选的自动加入 + LLM + TTS 覆盖项。纯文本 Discord 配置默认关闭语音；设置 `channels.discord.voice.enabled=true` 以选择加入。
- `channels.discord.voice` 启用 Discord 语音渠道对话，以及可选的自动加入 + LLM + TTS 覆盖。纯文本 Discord 配置默认关闭语音；设置 `channels.discord.voice.enabled=true` 以选择启用。
- `channels.discord.voice.model` 可选地覆盖用于 Discord 语音渠道响应的 LLM 模型。
- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会传递给 `@discordjs/voice` DAVE 选项（默认分别为 `true` 和 `24`）。
- `channels.discord.voice.connectTimeoutMs` 控制 `/vc join` 和自动加入尝试时初始 `@discordjs/voice` Ready 等待时间（默认为 `30000`）。
- `channels.discord.voice.reconnectGraceMs` 控制已断开的语音会话在 OpenClaw 销毁它之前可进入重连信令的时长（默认为 `15000`）。
- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会透传到 `@discordjs/voice` DAVE 选项（默认分别为 `true` 和 `24`）。
- `channels.discord.voice.connectTimeoutMs` 控制 `/vc join` 和自动加入尝试的初始 `@discordjs/voice` Ready 等待时间（默认 `30000`）。
- `channels.discord.voice.reconnectGraceMs` 控制已断开的语音会话可在 OpenClaw 销毁它之前进入重连信令的时长（默认 `15000`）。
- OpenClaw 还会在重复解密失败后，通过离开/重新加入语音会话来尝试语音接收恢复。
- `channels.discord.streaming` 是规范的流模式键。旧版 `streamMode` 和布尔值 `streaming` 会自动迁移。
- `channels.discord.autoPresence` 将运行时可用性映射到机器人在线状态（healthy => online、degraded => idle、exhausted => dnd），并允许可选的状态文本覆盖项。
- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/标签匹配（破窗兼容模式）。
- `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"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析审批人时，exec 审批会激活。
- `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析审批人时，会激活 exec 审批。
- `approvers`：允许批准 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。
- `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。
- `sessionFilter`：可选的会话键模式（子字符串或正则）。
- `target`：发送审批提示的位置。`"dm"`（默认）发送到审批人的私信，`"channel"` 发送到来源渠道，`"both"` 发送到两者。当目标包含 `"channel"` 时，按钮仅可由已解析的审批人使用。
- `cleanupAfterResolve`：当为 `true` 时，在批准、拒绝或超时后删除审批私信。
- `agentFilter`：可选智能体 ID 允许列表。省略则转发所有智能体的审批。
- `sessionFilter`：可选会话键模式（子字符串或正则表达式）。
- `target`：发送审批提示的位置。`"dm"`（默认）发送到审批人私信，`"channel"` 发送到来源渠道，`"both"` 同时发送到两者。当目标包含 `"channel"` 时，按钮只能由已解析的审批人使用。
- `cleanupAfterResolve`：为 `true` 时，在批准、拒绝或超时后删除审批私信。
**回应通知模式：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（来自所有消息上的 `guilds.<id>.users`）。
**反应通知模式：**`off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（来自所有消息上的 `guilds.<id>.users`）。
### Google Chat
@ -391,11 +392,11 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在
}
```
- 服务账号 JSON：内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。
- 也支持服务账号 SecretRef（`serviceAccountRef`）。
- 环境变量回退值：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。
- 服务账户 JSON：内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。
- 也支持服务账户 SecretRef（`serviceAccountRef`）。
- 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。
- 使用 `spaces/<spaceId>` 或 `users/<userId>` 作为投递目标。
- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（破窗兼容模式）。
- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（应急兼容模式）。
### Slack
@ -467,43 +468,35 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在
}
```
- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。
- **HTTP mode** 需要 `botToken` 加 `signingSecret`（位于根级或每个账号中）。
- `socketMode` 会将 Slack SDK Socket Mode 传输调优透传到公共 Bolt 接收器 API。仅在调查 ping/pong 超时或陈旧 websocket 行为时使用它。
- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文
字符串或 SecretRef 对象。
- Slack 账号快照会暴露按凭证划分的来源/状态字段，例如
`botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP mode 中的
`signingSecretStatus`。`configured_unavailable` 表示账号通过
SecretRef 配置，但当前命令/运行时路径无法解析密钥值。
- `configWrites: false` 会阻止由 Slack 发起的配置写入。
- 可选的 `channels.slack.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。
- `channels.slack.streaming.mode` 是规范的 Slack 流模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输协议。旧版 `streamMode`、布尔值 `streaming` 和 `nativeStreaming` 会自动迁移。
- **Socket 模式**需要同时提供 `botToken` 和 `appToken`（默认账户环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。
- **HTTP 模式**需要 `botToken` 加 `signingSecret`（在根级或按账户配置）。
- `socketMode` 会将 Slack SDK Socket Mode 传输调优透传到公共 Bolt 接收器 API。仅在调查 ping/pong 超时或过期 websocket 行为时使用。
- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串或 SecretRef 对象。
- Slack 账户快照会暴露按凭据的来源/状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式下的 `signingSecretStatus`。`configured_unavailable` 表示账户通过 SecretRef 配置，但当前命令/运行时路径无法解析密钥值。
- `configWrites: false` 会阻止 Slack 发起的配置写入。
- 可选的 `channels.slack.defaultAccount` 在匹配已配置账户 ID 时会覆盖默认账户选择。
- `channels.slack.streaming.mode` 是规范的 Slack 流模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输协议。旧版 `streamMode`、布尔型 `streaming` 和 `nativeStreaming` 值会自动迁移。
- 使用 `user:<id>`（私信）或 `channel:<id>` 作为投递目标。
**回应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。
**反应通知模式：**`off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。
**线程会话隔离：** `thread.historyScope` 为按线程（默认）或跨渠道共享。`thread.inheritParent` 会将父渠道转录复制到新线程。
**线程会话隔离：**`thread.historyScope` 为按线程（默认）或跨渠道共享。`thread.inheritParent` 会将父渠道转录复制到新线程。
- Slack 原生流式传输加 Slack assistant 风格的 “is typing...” 线程状态需要回复线程目标。顶层私信默认保持非线程模式，因此它们会使用 `typingReaction` 或普通投递，而不是线程风格预览。
- `typingReaction` 会在回复运行时向入站 Slack 消息添加临时回应，然后在完成时移除。使用 Slack emoji shortcode，例如 `"hourglass_flowing_sand"`。
- `channels.slack.execApprovals`：Slack 原生 exec 审批投递和审批人授权。与 Discord 相同的 schema：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。
- Slack 原生流式传输加 Slack assistant 风格的“正在输入...”线程状态需要回复线程目标。顶层私信默认保持在线程外，因此它们会使用 `typingReaction` 或常规投递，而不是线程风格预览。
- `typingReaction` 会在回复运行期间向入站 Slack 消息添加临时反应，然后在完成时移除。使用 Slack 表情短代码，例如 `"hourglass_flowing_sand"`。
- `channels.slack.execApprovals`：Slack 原生 exec 审批投递和审批人授权。架构与 Discord 相同：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。
| 操作组 | 默认值 | 备注 |
| ------------ | ------- | ---------------------- |
| reactions | enabled | 回应 + 列出回应 |
| messages | enabled | 读取/发送/编辑/删除 |
| pins | enabled | 置顶/取消置顶/列出 |
| memberInfo | enabled | 成员信息 |
| emojiList | enabled | 自定义 emoji 列表 |
| reactions | 已启用 | 反应 + 列出反应 |
| messages | 已启用 | 读取/发送/编辑/删除 |
| pins | 已启用 | 置顶/取消置顶/列表 |
| memberInfo | 已启用 | 成员信息 |
| emojiList | 已启用 | 自定义表情列表 |
### Mattermost
Mattermost 在当前 OpenClaw 版本中作为内置插件发布。较旧或
自定义构建可以使用
`openclaw plugins install @openclaw/mattermost` 安装当前 npm 包；如果 npm 报告
OpenClaw 所有的包已弃用，请使用内置插件或本地检出，
直到发布更新的 npm 包。
Mattermost 在当前 OpenClaw 版本中作为内置插件提供。较旧或自定义构建可以使用 `openclaw plugins install @openclaw/mattermost` 安装当前 npm 包；如果 npm 报告 OpenClaw 拥有的包已弃用，请使用内置插件或本地检出，直到发布更新的 npm 包。
```json5
{
@ -533,18 +526,18 @@ OpenClaw 所有的包已弃用，请使用内置插件或本地检出，
}
```
聊天模式：`oncall`（在 @-提及时响应，默认）、`onmessage`（每条消息）、`onchar`（以触发前缀开头的消息）。
聊天模式：`oncall`（响应 @ 提及，默认）、`onmessage`（每条消息）、`onchar`（以触发前缀开头的消息）。
启用 Mattermost 原生命令时：
- `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），而不是完整 URL。
- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器能够访问。
- 原生斜杠回调使用 Mattermost 在注册斜杠命令时返回的每命令令牌进行认证。如果注册失败或没有激活任何命令，OpenClaw 会拒绝回调并返回 `Unauthorized: invalid command token.`
- 对于私有/tailnet/内部回调主机，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含该回调主机/域名。使用主机/域名值，而不是完整 URL。
- `channels.mattermost.configWrites`：允许或拒绝 Mattermost 发起的配置写入。
- `channels.mattermost.requireMention`：要求在渠道中回复前先 `@mention`。
- `channels.mattermost.groups.<channelId>.requireMention`：按渠道覆盖提及门控（`"*"` 表示默认值）。
- 可选的 `channels.mattermost.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。
- `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），不能是完整 URL。
- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器必须可以访问。
- 原生斜杠回调使用每个命令的 token 进行身份验证，这些 token 由 Mattermost 在斜杠命令注册期间返回。如果注册失败或没有命令被激活，OpenClaw 会拒绝回调并返回 `Unauthorized: invalid command token.`
- 对于私有、tailnet 或内部回调主机，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机/域名。使用主机/域名值，而不是完整 URL。
- `channels.mattermost.configWrites`：允许或拒绝由 Mattermost 发起的配置写入。
- `channels.mattermost.requireMention`：在渠道中回复前要求 `@mention`。
- `channels.mattermost.groups.<channelId>.requireMention`：按渠道覆盖提及门控（`"*"` 表示默认）。
- 可选的 `channels.mattermost.defaultAccount` 会在匹配已配置的账号 ID 时覆盖默认账号选择。
### Signal
@ -565,11 +558,11 @@ OpenClaw 所有的包已弃用，请使用内置插件或本地检出，
}
```
**反应通知模式：**`off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。
**回应通知模式：** `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
@ -589,13 +582,13 @@ BlueBubbles 是推荐的 iMessage 路径（由插件支持，在 `channels.blueb
```
- 此处涵盖的核心键路径：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。
- 可选的 `channels.bluebubbles.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。
- 带有 `type: "acp"` 的顶层 `bindings[]` 条目可以将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles 句柄或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP 智能体](/zh-CN/tools/acp-agents#channel-specific-settings)。
- 完整 BlueBubbles 渠道配置记录在 [BlueBubbles](/zh-CN/channels/bluebubbles) 中。
- 可选的 `channels.bluebubbles.defaultAccount` 会在匹配已配置的账号 ID 时覆盖默认账号选择。
- 带有 `type: "acp"` 的顶层 `bindings[]` 条目可以将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP 智能体](/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
{
@ -619,15 +612,15 @@ OpenClaw 会生成 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护
}
```
- 可选的 `channels.imessage.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。
- 可选的 `channels.imessage.defaultAccount` 会在匹配已配置的账号 ID 时覆盖默认账号选择。
- 需要对 Messages DB 拥有完全磁盘访问权限。
- 需要对 Messages DB 拥有完整磁盘访问权限。
- 优先使用 `chat_id:<id>` 目标。使用 `imsg chats --limit 20` 列出聊天。
- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以便通过 SCP 获取附件。
- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。
- `attachmentRoots` 和 `remoteAttachmentRoots` 会限制入站附件路径（默认：`/Users/*/Library/Messages/Attachments`）。
- SCP 使用严格的主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。
- `channels.imessage.configWrites`：允许或拒绝 iMessage 发起的配置写入。
- 带有 `type: "acp"` 的顶层 `bindings[]` 条目可以将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化句柄或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP 智能体](/zh-CN/tools/acp-agents#channel-specific-settings)。
- `channels.imessage.configWrites`：允许或拒绝由 iMessage 发起的配置写入。
- 带有 `type: "acp"` 的顶层 `bindings[]` 条目可以将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP 智能体](/zh-CN/tools/acp-agents#channel-specific-settings)。
<Accordion title="iMessage SSH 包装器示例">
@ -670,21 +663,21 @@ Matrix 由插件支持，并在 `channels.matrix` 下配置。
}
```
- 令牌认证使用 `accessToken`；密码认证使用 `userId` + `password`。
- `channels.matrix.proxy` 会通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。具名账号可以用 `channels.matrix.accounts.<id>.proxy` 覆盖它。
- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 和此网络选择加入是彼此独立的控制项。
- `channels.matrix.defaultAccount` 在多账号设置中选择首选账号。
- `channels.matrix.autoJoin` 默认为 `off`，因此受邀房间和新的私信风格邀请会被忽略，直到你设置带有 `autoJoinAllowlist` 的 `autoJoin: "allowlist"` 或 `autoJoin: "always"`。
- `channels.matrix.execApprovals`：Matrix 原生执行批准投递和批准者授权。
- `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析批准者时，执行批准会激活。
- `approvers`：允许批准执行请求的 Matrix 用户 ID（例如 `@owner:example.org`）。
- `agentFilter`：可选智能体 ID 允许列表。省略时会转发所有智能体的批准。
- `sessionFilter`：可选会话键模式（子字符串或正则表达式）。
- `target`：发送批准提示的位置。`"dm"`（默认）、`"channel"`（来源房间）或 `"both"`。
- token 身份验证使用 `accessToken`；密码身份验证使用 `userId` + `password`。
- `channels.matrix.proxy` 通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账号可以使用 `channels.matrix.accounts.<id>.proxy` 覆盖它。
- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 和这个网络选择加入项是相互独立的控制项。
- `channels.matrix.defaultAccount` 会在多账号设置中选择首选账号。
- `channels.matrix.autoJoin` 默认为 `off`，因此受邀房间和新的私信式邀请会被忽略，直到你设置带有 `autoJoinAllowlist` 的 `autoJoin: "allowlist"` 或 `autoJoin: "always"`。
- `channels.matrix.execApprovals`：Matrix 原生 exec 审批投递和审批者授权。
- `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析审批者时，会激活 exec 审批。
- `approvers`：允许批准 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。
- `agentFilter`：可选的智能体 ID 允许列表。省略时会转发所有智能体的审批。
- `sessionFilter`：可选的会话键模式（子字符串或正则表达式）。
- `target`：发送审批提示的位置。`"dm"`（默认）、`"channel"`（来源房间）或 `"both"`。
- 按账号覆盖：`channels.matrix.accounts.<id>.execApprovals`。
- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何分组成会话：`per-user`（默认）按路由后的对等方共享，而 `per-room` 会隔离每个私信房间。
- Matrix Status 探测和实时目录查找使用与运行时流量相同的代理策略。
- 完整 Matrix 配置、目标规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix) 中。
- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何分组到会话中：`per-user`（默认）按路由后的对端共享，而 `per-room` 会隔离每个私信房间。
- Matrix 状态探测和实时目录查询使用与运行时流量相同的代理策略。
- 完整的 Matrix 配置、目标规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix) 中。
### Microsoft Teams
@ -704,7 +697,7 @@ 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
@ -730,12 +723,12 @@ IRC 由插件支持，并在 `channels.irc` 下配置。
```
- 此处涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。
- 可选的 `channels.irc.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。
- 完整 IRC 渠道配置（主机/端口/TLS/渠道/允许列表/提及门控）记录在 [IRC](/zh-CN/channels/irc) 中。
- 可选的 `channels.irc.defaultAccount` 会在匹配已配置的账号 ID 时覆盖默认账号选择。
- 完整的 IRC 渠道配置（host/port/TLS/channels/allowlists/mention gating）记录在 [IRC](/zh-CN/channels/irc) 中。
### 多账号（所有渠道）
每个渠道运行多个账号（每个都有自己的 `accountId`）：
每个渠道运行多个账号（每个账号都有自己的 `accountId`）：
```json5
{
@ -756,34 +749,34 @@ IRC 由插件支持，并在 `channels.irc` 下配置。
}
```
- 省略 `accountId` 时会使用 `default`（CLI + 路由）。
- 环境变量令牌只适用于**默认**账号。
- 基础渠道设置适用于所有账号，除非按账号覆盖。
- 使用 `bindings[].match.accountId` 将每个账号路由到不同智能体。
- 如果在仍使用单账号顶层渠道配置时，通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，OpenClaw 会先将账号范围的顶层单账号值提升到该渠道的账号映射中，从而让原始账号继续工作。大多数渠道会将它们移入 `channels.<channel>.accounts.default`；Matrix 可以改为保留现有匹配的具名/默认目标。
- 现有的仅渠道绑定（没有 `accountId`）会继续匹配默认账号；账号范围绑定仍然是可选的。
- `openclaw doctor --fix` 也会通过将账号范围的顶层单账号值移动到为该渠道选择的已提升账号，来修复混合形态。大多数渠道使用 `accounts.default`；Matrix 可以改为保留现有匹配的具名/默认目标。
- 省略 `accountId` 时使用 `default`（CLI + 路由）。
- 环境变量 token 只适用于**默认**账号。
- 基础渠道设置会应用到所有账号，除非按账号覆盖。
- 使用 `bindings[].match.accountId` 将每个账号路由到不同的智能体。
- 如果你通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，而当前仍使用单账号顶层渠道配置，OpenClaw 会先将账号作用域的顶层单账号值提升到渠道账号映射中，以便原始账号继续工作。大多数渠道会将它们移入 `channels.<channel>.accounts.default`；Matrix 则可以保留现有的匹配命名/默认目标。
- 现有的仅渠道绑定（没有 `accountId`）会继续匹配默认账号；账号作用域绑定仍然是可选的。
- `openclaw doctor --fix` 也会通过将账号作用域的顶层单账号值移动到为该渠道选择的已提升账号来修复混合形状。大多数渠道使用 `accounts.default`；Matrix 则可以保留现有的匹配命名/默认目标。
### 其他插件渠道
许多插件渠道配置为 `channels.<id>`，并记录在各自专用的渠道页面中（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。
查看完整渠道索引：[Channels](/zh-CN/channels)。
请参阅完整渠道索引：[渠道](/zh-CN/channels)。
### 群聊提及门控
群组消息默认**要求提及**（元数据提及或安全正则表达式模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。
群组消息默认**要求提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。
可见回复由单独的配置控制。群组/渠道房间默认为 `messages.groupChat.visibleReplies: "message_tool"`：OpenClaw 仍会处理该轮对话，但普通最终回复保持私密，可见房间输出需要 `message(action=send)`。只有在你想要旧版行为，即普通回复会发回房间时，才设置为 `"automatic"`。若要把相同的仅工具可见回复行为也应用于直接聊天，请设置 `messages.visibleReplies: "message_tool"`；Codex harness 也将该仅工具行为用作未设置时的直接聊天默认值。
可见回复会单独控制。群组/渠道房间默认为 `messages.groupChat.visibleReplies: "message_tool"`：OpenClaw 仍会处理该轮对话，但普通最终回复保持私密，可见的房间输出需要 `message(action=send)`。仅当你想要普通回复被发回房间的旧版行为时，才设置 `"automatic"`。要将相同的仅工具可见回复行为也应用到直接聊天，请设置 `messages.visibleReplies: "message_tool"`；Codex harness 也将这种仅工具行为用作未设置的直接聊天默认值。
如果在活动工具策略下消息工具不可用，OpenClaw 会回退到自动可见回复，而不是静默抑制响应。`openclaw doctor` 会警告这种不匹配。
如果消息工具在当前工具策略下不可用，OpenClaw 会回退到自动可见回复，而不是静默抑制响应。`openclaw doctor` 会对此不匹配发出警告。
Gateway 网关会在文件保存后热重载 `messages` 配置。仅当部署中禁用了文件监听或配置重载时才需要重启。
文件保存后，Gateway 网关会热重载 `messages` 配置。仅当部署中禁用了文件监视或配置重载时才需要重启。
**提及类型：**
- **元数据提及**：原生平台 @-mentions。在 WhatsApp 自聊模式中会被忽略。
- **文本模式**：`agents.list[].groupChat.mentionPatterns` 中的安全正则表达式模式。无效模式和不安全的嵌套重复会被忽略。
- 仅当可以检测时（原生提及或至少一个模式），才会强制执行提及门控。
- **元数据提及**：原生平台 @-提及。在 WhatsApp 自聊模式中会被忽略。
- **文本模式**：`agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。
- 只有在可以检测时（原生提及或至少一个模式），才会执行提及门控。
```json5
{
@ -802,7 +795,7 @@ Gateway 网关会在文件保存后热重载 `messages` 配置。仅当部署中
`messages.groupChat.historyLimit` 设置全局默认值。渠道可以用 `channels.<channel>.historyLimit`（或按账号）覆盖。设置为 `0` 可禁用。
`messages.visibleReplies` 是全局源回合默认值；`messages.groupChat.visibleReplies` 会针对群组/渠道源回合覆盖它。当 `messages.visibleReplies` 未设置时，harness 可以提供自己的直接/源默认值；Codex harness 默认使用 `message_tool`。渠道允许列表和提及门控仍会决定是否处理某个回合。
`messages.visibleReplies` 是全局源回合默认值；`messages.groupChat.visibleReplies` 会为群组/渠道源回合覆盖它。当 `messages.visibleReplies` 未设置时，harness 可以提供自己的 direct/source 默认值；Codex harness 默认使用 `message_tool`。渠道允许列表和提及门控仍会决定是否处理某个回合。
#### 私信历史限制
@ -875,30 +868,30 @@ Gateway 网关会在文件保存后热重载 `messages` 配置。仅当部署中
<Accordion title="命令详情">
- 此块配置命令表面。当前内置 + 内置插件命令目录请参阅 [Slash Commands](/zh-CN/tools/slash-commands)。
- 此页面是**配置键参考**，不是完整命令目录。渠道/插件拥有的命令，例如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、设备配对 `/pair`、记忆 `/dreaming`、手机控制 `/phone` 和 Talk `/voice`，记录在其渠道/插件页面以及 [Slash Commands](/zh-CN/tools/slash-commands) 中。
- 此块配置命令表面。当前内置 + 捆绑命令目录请参阅 [Slash Commands](/zh-CN/tools/slash-commands)。
- 此页面是**配置键参考**，不是完整命令目录。渠道/插件拥有的命令，例如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、设备配对 `/pair`、记忆 `/dreaming`、电话控制 `/phone` 和 Talk `/voice`，记录在各自的渠道/插件页面以及 [Slash Commands](/zh-CN/tools/slash-commands) 中。
- 文本命令必须是带前导 `/` 的**独立**消息。
- `native: "auto"` 会为 Discord/Telegram 开启原生命令，并让 Slack 保持关闭。
- `nativeSkills: "auto"` 会为 Discord/Telegram 开启原生 Skills 命令，并让 Slack 保持关闭。
- 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除之前注册的命令。
- 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除先前注册的命令。
- 使用 `channels.<provider>.commands.nativeSkills` 按渠道覆盖原生 Skills 注册。
- `channels.telegram.customCommands` 会添加额外的 Telegram bot 菜单项。
- `bash: true` 会为主机 shell 启用 `! <cmd>`。需要 `tools.elevated.enabled`，且发送者在 `tools.elevated.allowFrom.<channel>` 中。
- `config: true` 会启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化 `/config set|unset` 写入还需要 `operator.admin`；只读 `/config show` 仍可供普通写作用域的 operator 客户端使用。
- `mcp: true` 会为 `mcp.servers` 下由 OpenClaw 管理的 MCP server 配置启用 `/mcp`。
- `plugins: true` 会为插件发现、安装以及启用/禁用控制启用 `/plugins`。
- `channels.<provider>.configWrites` 按渠道限制配置变更（默认：true）。
- 对于多账号渠道，`channels.<provider>.accounts.<id>.configWrites` 还会限制面向该账号的写入（例如 `/allowlist --config --account <id>` 或 `/config set channels.<provider>.accounts.<id>...`）。
- `restart: false` 会禁用 `/restart` 和 Gateway 网关重启工具操作。默认值：`true`。
- `ownerAllowFrom` 是仅限所有者命令/工具的显式所有者允许列表。它独立于 `allowFrom`。
- `ownerDisplay: "hash"` 会在系统提示词中哈希所有者 ID。设置 `ownerDisplaySecret` 可控制哈希。
- `allowFrom` 按提供商设置。设置后，它是**唯一**授权来源（渠道允许列表/配对和 `useAccessGroups` 都会被忽略）。
- `bash: true` 启用用于主机 shell 的 `! <cmd>`。需要 `tools.elevated.enabled`，且发送者在 `tools.elevated.allowFrom.<channel>` 中。
- `config: true` 启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化的 `/config set|unset` 写入还需要 `operator.admin`；只读 `/config show` 仍可供普通写入作用域的 operator 客户端使用。
- `mcp: true` 为 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置启用 `/mcp`。
- `plugins: true` 为插件发现、安装以及启用/禁用控制启用 `/plugins`。
- `channels.<provider>.configWrites` 按渠道限制配置变更（默认值：true）。
- 对于多账号渠道，`channels.<provider>.accounts.<id>.configWrites` 也会限制以该账号为目标的写入（例如 `/allowlist --config --account <id>` 或 `/config set channels.<provider>.accounts.<id>...`）。
- `restart: false` 禁用 `/restart` 和 Gateway 网关重启工具操作。默认值：`true`。
- `ownerAllowFrom` 是仅限 owner 命令/工具的显式 owner 允许列表。它独立于 `allowFrom`。
- `ownerDisplay: "hash"` 会在系统提示中哈希 owner id。设置 `ownerDisplaySecret` 以控制哈希。
- `allowFrom` 按提供商设置。设置后，它是**唯一**授权来源（渠道允许列表/配对和 `useAccessGroups` 会被忽略）。
- 当未设置 `allowFrom` 时，`useAccessGroups: false` 允许命令绕过访问组策略。
- 命令文档映射：
- 内置 + 内置插件目录：[Slash Commands](/zh-CN/tools/slash-commands)
- 渠道专属命令表面：[渠道](/zh-CN/channels)
- 内置 + 捆绑目录：[Slash Commands](/zh-CN/tools/slash-commands)
- 渠道特定命令表面：[Channels](/zh-CN/channels)
- QQ Bot 命令：[QQ Bot](/zh-CN/channels/qqbot)
- 配对命令：[配对](/zh-CN/channels/pairing)
- 配对命令：[Pairing](/zh-CN/channels/pairing)
- LINE 卡片命令：[LINE](/zh-CN/channels/line)
- 记忆 Dreaming：[Dreaming](/zh-CN/concepts/dreaming)
@ -908,6 +901,6 @@ Gateway 网关会在文件保存后热重载 `messages` 配置。仅当部署中
## 相关内容
- [配置参考](/zh-CN/gateway/configuration-reference) — 顶层键
- [配置参考](/zh-CN/gateway/configuration-reference) — 顶级键
- [配置 — 智能体](/zh-CN/gateway/config-agents)
- [渠道概览](/zh-CN/channels)