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-04-23 06:50:19 +00:00
parent 9515db89e4
commit abb5be6c9d
45 changed files with 4704 additions and 4141 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
docs/zh-CN/AGENTS.md
View File

@ -1,38 +1,38 @@
---
x-i18n:
generated_at: "2026-04-12T08:32:18Z"
generated_at: "2026-04-23T06:39:57Z"
model: gpt-5.4
provider: openai
source_hash: 6805814012caac6ff64f17f44f393975510c5af3421fae9651ed9033e5861784
source_hash: 8b046833f9a15dc61894ab9e808a09a9fb055ef7ada5c3d4893fbe5f70dec126
source_path: AGENTS.md
workflow: 15
---
# 文档指南
本目录负责文档编写、Mintlify 链接规则以及文档 i18n 策略。
此目录负责文档编写、Mintlify 链接规则以及文档 i18n 策略。
## Mintlify 规则
- 文档托管在 Mintlify（`https://docs.openclaw.ai`）。
- `docs/**/*.md` 中的内部文档链接必须保持为根相对路径，且不带 `.md` 或 `.mdx` 后缀（例如：`[Config](/configuration)`）。
- 章节交叉引用应在根相对路径上使用锚点（例如：`[Hooks](/configuration#hooks)`）。
- 文档托管在 Mintlify（`https://docs.openclaw.ai`）上。
- `docs/**/*.md` 中的内部文档链接必须保持为根相对路径，且不带 `.md` 或 `.mdx` 后缀（示例：`[配置](/gateway/configuration)`）。
- 章节交叉引用应在根相对路径上使用锚点（示例：`[Hooks](/gateway/configuration-reference#hooks)`）。
- 文档标题应避免使用长破折号和撇号，因为 Mintlify 的锚点生成在这些情况下不稳定。
- README 和其他在 GitHub 上渲染的文档应保留绝对文档 URL，这样链接在 Mintlify 之外也能正常工作。
- README 和其他在 GitHub 上渲染的文档应保留绝对文档 URL，以确保链接在 Mintlify 之外也能正常工作。
- 文档内容必须保持通用：不要使用个人设备名称、主机名或本地路径；请使用类似 `user@gateway-host` 的占位符。
## 文档内容规则
- 对于文档、UI 文案和选择器列表，服务 / 提供商应按字母顺序排列，除非该部分明确是在描述运行时顺序或自动检测顺序。
- 保持内置插件命名与根目录 `AGENTS.md` 中的全仓库插件术语规则一致。
- 对于文档、UI 文案和选择器列表，服务/提供商应按字母顺序排列，除非该部分明确是在描述运行时顺序或自动检测顺序。
- 保持内置 plugin 的命名与根 `AGENTS.md` 中的全仓库 plugin 术语规则一致。
## 文档 i18n
- 本仓库不维护外语文档。生成后的发布输出位于单独的 `openclaw/docs` 仓库中（本地通常克隆为 `../openclaw-docs`）。
- 不要在此处新增或编辑 `docs/<locale>/**` 下的本地化文档。
- 将本仓库中的英文文档和术语表文件视为事实来源。
- 流程：先在这里更新英文文档，再按需更新 `docs/.i18n/glossary.<locale>.json`，然后让发布仓库同步，并在 `openclaw/docs` 中运行 `scripts/docs-i18n`。
- 在重新运行 `scripts/docs-i18n` 之前，为任何新的技术术语、页面标题或必须保持英文或使用固定译法的简短导航标签添加术语表条目。
- `pnpm docs:check-i18n-glossary` 是用于检查英文文档标题和简短内部文档标签变更的守卫命令。
- 翻译记忆存储在发布仓库中生成的 `docs/.i18n/*.tm.jsonl` 文件里。
- 此仓库不维护外语文档。生成后的发布输出位于单独的 `openclaw/docs` 仓库中（本地通常克隆为 `../openclaw-docs`）。
- 不要在此仓库中的 `docs/<locale>/**` 下添加或编辑本地化文档。
- 将此仓库中的英文文档以及术语表文件视为唯一事实来源。
- 流程：先在此处更新英文文档，再按需要更新 `docs/.i18n/glossary.<locale>.json`，然后让发布仓库同步，并在 `openclaw/docs` 中运行 `scripts/docs-i18n`。
- 在重新运行 `scripts/docs-i18n` 之前，为任何必须保留英文或需要固定译法的新技术术语、页面标题或简短导航标签添加术语表条目。
- `pnpm docs:check-i18n-glossary` 是用于检查已变更英文文档标题和简短内部文档标签的守卫命令。
- 翻译记忆库存储在发布仓库中生成的 `docs/.i18n/*.tm.jsonl` 文件里。
- 参见 `docs/.i18n/README.md`。

8
docs/zh-CN/automation/poll.md
View File

@ -1,15 +1,15 @@
---
summary: 重定向到 /tools/message
summary: 重定向到 /cli/message
title: 投票
x-i18n:
generated_at: "2026-04-05T08:12:47Z"
generated_at: "2026-04-23T06:40:04Z"
model: gpt-5.4
provider: openai
source_hash: 8d69432ad8ba5fd80b59f8df779a1105ce0a2ff767d7dd5dc9d8e3ac1cb1ff1f
source_hash: 0639c4d35678e5cb0d3a262e2db9cd8db1e25e3eb26adc28bf76b5df14e5446f
source_path: automation/poll.md
workflow: 15
---
# 投票
本页已迁移至 [消息工具](/cli/message)。有关投票文档，请参见 [消息工具](/cli/message)。
本页已移至 [消息工具](/zh-CN/cli/message)。有关投票文档，请参阅 [消息工具](/zh-CN/cli/message)。

277
docs/zh-CN/channels/bluebubbles.md
View File

@ -1,37 +1,38 @@
---
read_when:
- 设置 BlueBubbles 渠道
- Webhook 配对故障排除
- 故障排除 webhook 配对
- 在 macOS 上配置 iMessage
summary: 通过 BlueBubbles macOS 服务器接入 iMessage（REST 发送/接收、正在输入、表情回应、配对、高级操作）。
summary: 通过 BlueBubbles macOS 服务器使用 iMessage（REST 发送/接收、正在输入、回应、配对、高级操作）。
title: BlueBubbles
x-i18n:
generated_at: "2026-04-21T20:11:29Z"
generated_at: "2026-04-23T06:40:08Z"
model: gpt-5.4
provider: openai
source_hash: db2e193db3fbcea22748187c21d0493037f59d4f1af163725530d5572b06e8b4
source_hash: a1c1670bb453a1f78bb8e35e4b7065ceeba46ce93180e1288745621f8c4179c9
source_path: channels/bluebubbles.md
workflow: 15
---
# BlueBubbles（macOS REST）
状态：一个通过 HTTP 与 BlueBubbles macOS 服务器通信的内置插件。由于其 API 更丰富、设置也比旧版 `imsg` 渠道更简单，**推荐用于 iMessage 集成**。
状态：通过 HTTP 与 BlueBubbles macOS 服务器通信的内置插件。由于相比旧版 imsg 渠道拥有更丰富的 API 和更简单的设置流程，**推荐用于 iMessage 集成**。
## 内置插件
当前的 OpenClaw 版本内置了 BlueBubbles，因此常规打包构建**不需要**单独执行 `openclaw plugins install` 步骤。
当前的 OpenClaw 发行版已内置 BlueBubbles，因此普通打包构建
不需要单独执行 `openclaw plugins install` 步骤。
## 概览
- 通过 BlueBubbles 辅助应用在 macOS 上运行（[bluebubbles.app](https://bluebubbles.app)）。
- 推荐/已测试：macOS Sequoia（15）。macOS Tahoe（26）可用；但当前在 Tahoe 上编辑功能不可用，群组图标更新也可能显示成功但不会同步。
- OpenClaw 通过它的 REST API 与其通信（`GET /api/v1/ping`、`POST /message/text`、`POST /chat/:id/*`）。
- 推荐/已测试：macOS Sequoia（15）。macOS Tahoe（26）可用；目前在 Tahoe 上编辑功能失效，群组图标更新可能会显示成功但不会同步。
- OpenClaw 通过其 REST API 与之通信（`GET /api/v1/ping`、`POST /message/text`、`POST /chat/:id/*`）。
- 传入消息通过 webhook 到达；传出回复、正在输入指示、已读回执和 tapback 都通过 REST 调用完成。
- 附件和贴纸会作为入站媒体摄取（并在可能时暴露给智能体）。
- 配对/允许列表的工作方式与其他渠道相同（`/channels/pairing` 等），使用 `channels.bluebubbles.allowFrom` + 配对码。
- 表情回应会像 Slack/Telegram 一样作为系统事件暴露，因此智能体可以在回复前“提及”它们。
- 高级功能：编辑、撤回、回复线程、消息效果、群组管理。
- 附件和贴纸会作为入站媒体接收（并在可能时提供给智能体）。
- 配对/allowlist 的工作方式与其他渠道相同（`/channels/pairing` 等），使用 `channels.bluebubbles.allowFrom` + 配对码。
- Reactions 会像 Slack/Telegram 一样作为系统事件呈现，因此智能体可以在回复前“提及”它们。
- 高级功能：编辑、撤回发送、回复线程、消息效果、群组管理。
## 快速开始
@ -58,16 +59,16 @@ x-i18n:
安全说明：
- 始终设置 webhook 密码。
- 始终要求进行 webhook 身份验证。无论 loopback/代理拓扑如何，除非 BlueBubbles webhook 请求包含与 `channels.bluebubbles.password` 匹配的 password/guid（例如 `?password=<password>` 或 `x-password`），否则 OpenClaw 会拒绝该请求。
- 在读取/解析完整 webhook 请求体之前，会先检查密码认证。
- 始终要求 webhook 身份验证。无论 local loopback/proxy 拓扑如何，除非 BlueBubbles webhook 请求包含与 `channels.bluebubbles.password` 匹配的 password/guid（例如 `?password=<password>` 或 `x-password`），否则 OpenClaw 会拒绝该请求。
- 密码身份验证会在读取/解析完整 webhook 请求体之前检查。
## 保持 Messages.app 处于活动状态（VM / 无头设置）
某些 macOS VM / 常开环境可能会出现 Messages.app 进入“空闲”状态的情况（传入事件会停止，直到应用被打开/切到前台）。一个简单的变通办法是使用 AppleScript + LaunchAgent **每 5 分钟轻触一次 Messages**。
某些 macOS VM / 常开设置可能会导致 Messages.app 进入“空闲”状态（在应用被打开/置于前台之前，传入事件会停止）。一个简单的解决办法是使用 AppleScript + LaunchAgent **每 5 分钟轻触一次 Messages**。
### 1）保存 AppleScript
将其保存为：
将以下内容保存为：
- `~/Scripts/poke-messages.scpt`
@ -90,7 +91,7 @@ end try
### 2）安装 LaunchAgent
将其保存为：
将以下内容保存为：
- `~/Library/LaunchAgents/com.user.poke-messages.plist`
@ -126,7 +127,7 @@ end try
说明：
- 该任务会**每 300 秒**运行一次，并且会**在登录时**运行。
- 首次运行时可能会触发 macOS 的**自动化**提示（`osascript` → Messages）。请在运行该 LaunchAgent 的同一用户会话中批准这些提示。
- 首次运行可能会触发 macOS 的**自动化**权限提示（`osascript` → Messages）。请在运行该 LaunchAgent 的同一用户会话中批准这些提示。
加载它：
@ -139,21 +140,21 @@ launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist
BlueBubbles 可在交互式新手引导中使用：
```
```text
openclaw onboard
```
向导会提示你输入：
- **Server URL**（必填）：BlueBubbles 服务器地址（例如 `http://192.168.1.100:1234`）
- **Password**（必填）：来自 BlueBubbles Server 设置的 API 密码
- **Password**（必填）：BlueBubbles Server 设置中的 API 密码
- **Webhook path**（可选）：默认为 `/bluebubbles-webhook`
- **DM policy**：pairing、allowlist、open 或 disabled
- **Allow list**：电话号码、电子邮件或聊天目标
- **私信策略**：pairing、allowlist、open 或 disabled
- **允许列表**：电话号码、电子邮件地址或聊天目标
你也可以通过 CLI 添加 BlueBubbles：
```
```text
openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>
```
@ -162,25 +163,25 @@ openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --passwor
私信：
- 默认值：`channels.bluebubbles.dmPolicy = "pairing"`。
- 未知发送者会收到一个配对码；在获得批准之前，消息会被忽略（配对码 1 小时后过期）。
- 通过以下方式批准：
- 未知发送者会收到一个配对码；在批准之前，其消息会被忽略（代码在 1 小时后过期）。
- 通过以下命令批准：
- `openclaw pairing list bluebubbles`
- `openclaw pairing approve bluebubbles <CODE>`
- 配对是默认的令牌交换方式。详情参见：[Pairing](/zh-CN/channels/pairing)
- 配对是默认的令牌交换方式。详情请参见：[Pairing](/zh-CN/channels/pairing)
群组：
- `channels.bluebubbles.groupPolicy = open | allowlist | disabled`（默认：`allowlist`）。
- 当设置为 `allowlist` 时，`channels.bluebubbles.groupAllowFrom` 控制谁可以在群组中触发。
- 当设置为 `allowlist` 时，`channels.bluebubbles.groupAllowFrom` 用于控制群组中谁可以触发。
### 联系人姓名增强（macOS，可选）
### 联系人名称增强（macOS，可选）
BlueBubbles 的群组 webhook 通常只包含原始参与者地址。如果你希望 `GroupMembers` 上下文改为显示本地联系人姓名，可以选择在 macOS 上启用本地通讯录增强：
BlueBubbles 群组 webhook 通常只包含原始参与者地址。如果你希望 `GroupMembers` 上下文显示本地联系人名称而不是原始值，可以选择在 macOS 上启用本地通讯录增强：
- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` 启用该查找。默认值：`false`。
- 只有在群组访问、命令授权和提及门控都允许该消息通过之后，才会执行查找。
- 只有未命名的电话参与者会被增强。
- 如果未找到本地匹配项，则原始电话号码仍会作为回退值保留。
- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` 启用查找。默认值：`false`。
- 只有在群组访问、命令授权和提及门控允许消息通过后，才会执行查找。
- 仅对未命名的电话参与者进行增强。
- 如果找不到本地匹配项，则仍会使用原始电话号码作为回退值。
```json5
{
@ -197,10 +198,10 @@ BlueBubbles 的群组 webhook 通常只包含原始参与者地址。如果你
BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 的行为一致：
- 使用 `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）检测提及。
- 当为某个群组启用 `requireMention` 时，智能体只有在被提及时才会响应。
- 当某个群组启用 `requireMention` 时，智能体仅在被提及后才会响应。
- 来自已授权发送者的控制命令会绕过提及门控。
按群组配置：
每个群组的配置：
```json5
{
@ -210,7 +211,7 @@ BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 的行为一致
groupAllowFrom: ["+15555550123"],
groups: {
"*": { requireMention: true }, // 所有群组的默认值
"iMessage;-;chat123": { requireMention: false }, // 特定群组的覆盖值
"iMessage;-;chat123": { requireMention: false }, // 覆盖特定群组
},
},
},
@ -220,12 +221,12 @@ BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 的行为一致
### 命令门控
- 控制命令（例如 `/config`、`/model`）需要授权。
- 使用 `allowFrom` 和 `groupAllowFrom` 来确定命令授权。
- 已授权发送者即使在群组中未提及，也可以运行控制命令。
- 使用 `allowFrom` 和 `groupAllowFrom` 判定命令授权。
- 已授权的发送者即使在群组中未提及，也可以运行控制命令。
### 按群组设置 system prompt
### 每个群组的系统提示词
`channels.bluebubbles.groups.*` 下的每个条目都接受一个可选的 `systemPrompt` 字符串。每当处理该群组中的消息时，该值都会注入到智能体的 system prompt 中，因此你可以为每个群组设置特定人格或行为规则，而无需编辑智能体提示词：
`channels.bluebubbles.groups.*` 下的每个条目都接受一个可选的 `systemPrompt` 字符串。每次处理该群组中的消息时，这个值都会注入到智能体的系统提示词中，因此你可以为每个群组设置独立的人设或行为规则，而无需编辑智能体提示词：
```json5
{
@ -233,7 +234,7 @@ BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 的行为一致
bluebubbles: {
groups: {
"iMessage;-;chat123": {
systemPrompt: "将回复控制在 3 句话以内。模仿群组的随意语气。",
systemPrompt: "将回复控制在 3 句话以内。模仿该群组的轻松语气。",
},
},
},
@ -241,11 +242,11 @@ BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 的行为一致
}
```
该键与 BlueBubbles 为该群组报告的 `chatGuid` / `chatIdentifier` / 数字 `chatId` 相匹配，而 `"*"` 通配符条目则为每个没有精确匹配的群组提供默认值（与 `requireMention` 和按群组工具策略使用的模式相同）。精确匹配始终优先于通配符。私信会忽略此字段；请改用智能体级或账户级提示词自定义。
该键会匹配 BlueBubbles 报告的群组 `chatGuid` / `chatIdentifier` / 数值型 `chatId` 中的任意一种；而 `"*"` 通配符条目会为所有没有精确匹配的群组提供默认值（与 `requireMention` 和每个群组工具策略使用相同模式）。精确匹配始终优先于通配符。私信会忽略此字段；请改用智能体级或账户级提示词定制。
#### 示例：线程回复和 tapback 表情回应（Private API）
#### 示例：线程回复与 tapback 反应（Private API）
启用 BlueBubbles Private API 后，传入消息会带有简短消息 ID（例如 `[[reply_to:5]]`），智能体可以调用 `action=reply` 将回复串接到特定消息，或调用 `action=react` 添加 tapback。按群组设置 `systemPrompt` 是让智能体稳定选择正确工具的可靠方法：
启用 BlueBubbles Private API 后，入站消息会携带短消息 ID（例如 `[[reply_to:5]]`），并且智能体可以调用 `action=reply` 以线程方式回复特定消息，或调用 `action=react` 添加 tapback。每个群组的 `systemPrompt` 是让智能体持续选择正确工具的一种可靠方式：
```json5
{
@ -254,9 +255,9 @@ BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 的行为一致
groups: {
"iMessage;+;chat-family": {
systemPrompt: [
"在此群组中回复时，始终使用上下文中的",
"[[reply_to:N]] messageId 调用 action=reply，这样你的回复会串接到",
"触发消息下方。绝不要发送新的未关联消息。",
"在这个群组中回复时，始终调用 action=reply，并使用",
"上下文中的 [[reply_to:N]] messageId，这样你的回复会在线程中",
"显示在触发消息下方。绝不要发送新的未关联消息。",
"",
"对于简短确认（'ok'、'got it'、'on it'），请使用",
"action=react 并选择合适的 tapback 表情（❤️、👍、😂、‼️、❓），",
@ -269,24 +270,24 @@ BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 的行为一致
}
```
tapback 表情回应和线程回复都需要 BlueBubbles Private API；相关底层机制参见 [Advanced actions](#advanced-actions) 和 [Message IDs](#message-ids-short-vs-full)。
Tapback 反应和线程回复都需要 BlueBubbles Private API；其底层机制请参见 [Advanced actions](#advanced-actions) 和 [Message IDs](#message-ids-short-vs-full)。
## ACP 会话绑定
BlueBubbles 聊天可以在不改变传输层的情况下转变为持久 ACP 工作区。
BlueBubbles 聊天可以转换为持久化 ACP 工作区，而无需更改传输层。
快速操作流程：
- 在私信或允许的群聊中运行 `/acp spawn codex --bind here`。
- 在同一个 BlueBubbles 会话中，后续消息会路由到生成的 ACP 会话。
- `/new` 和 `/reset` 会在原地重置同一个已绑定 ACP 会话。
- 之后在同一个 BlueBubbles 会话中的消息会路由到已启动的 ACP 会话。
- `/new` 和 `/reset` 会在原位置重置同一个已绑定的 ACP 会话。
- `/acp close` 会关闭 ACP 会话并移除绑定。
也支持通过顶层 `bindings[]` 条目配置持久绑定，使用 `type: "acp"` 和 `match.channel: "bluebubbles"`。
还支持通过顶层 `bindings[]` 条目配置持久化绑定，其中 `type: "acp"` 且 `match.channel: "bluebubbles"`。
`match.peer.id` 可以使用任意受支持的 BlueBubbles 目标形式：
- 标准化私信句柄，例如 `+15555550123` 或 `user@example.com`
- 规范化的私信句柄，例如 `+15555550123` 或 `user@example.com`
- `chat_id:<id>`
- `chat_guid:<guid>`
- `chat_identifier:<identifier>`
@ -323,13 +324,13 @@ BlueBubbles 聊天可以在不改变传输层的情况下转变为持久 ACP 工
}
```
共享的 ACP 绑定行为参见 [ACP Agents](/zh-CN/tools/acp-agents)。
共享的 ACP 绑定行为请参见 [ACP Agents](/zh-CN/tools/acp-agents)。
## 正在输入 + 已读回执
- **正在输入指示**：会在生成回复之前和期间自动发送。
- **已读回执**：由 `channels.bluebubbles.sendReadReceipts` 控制（默认：`true`）。
- **正在输入指示**：OpenClaw 会发送开始输入事件；BlueBubbles 会在发送后或超时后自动清除输入状态（通过 DELETE 手动停止并不可靠）。
- **正在输入指示**：OpenClaw 会发送开始输入事件；BlueBubbles 会在发送消息后或超时后自动清除输入状态（通过 DELETE 手动停止并不可靠）。
```json5
{
@ -350,8 +351,8 @@ BlueBubbles 聊天可以在不改变传输层的情况下转变为持久 ACP 工
channels: {
bluebubbles: {
actions: {
reactions: true, // tapback 表情回应（默认：true）
edit: true, // 编辑已发送消息（macOS 13+，在 macOS 26 Tahoe 上不可用）
reactions: true, // tapback（默认：true）
edit: true, // 编辑已发送消息（macOS 13+，在 macOS 26 Tahoe 上失效）
unsend: true, // 撤回消息（macOS 13+）
reply: true, // 按消息 GUID 进行线程回复
sendWithEffect: true, // 消息效果（slam、loud 等）
@ -369,19 +370,19 @@ BlueBubbles 聊天可以在不改变传输层的情况下转变为持久 ACP 工
可用操作：
- **react**：添加/移除 tapback 表情回应（`messageId`、`emoji`、`remove`）。iMessage 原生的 tapback 集合是 `love`、`like`、`dislike`、`laugh`、`emphasize` 和 `question`。当智能体选择了该集合之外的 emoji（例如 `👀`）时，reaction 工具会回退为 `love`，这样 tapback 仍然会渲染，而不会导致整个请求失败。已配置的确认表情回应仍会严格校验，遇到未知值时会报错。
- **react**：添加/移除 tapback 反应（`messageId`、`emoji`、`remove`）。iMessage 原生的 tapback 集合为 `love`、`like`、`dislike`、`laugh`、`emphasize` 和 `question`。当智能体选择了不在该集合中的 emoji（例如 `👀`）时，反应工具会回退到 `love`，这样 tapback 仍能正常渲染，而不会导致整个请求失败。已配置的确认反应仍会严格校验，并在值未知时报错。
- **edit**：编辑已发送消息（`messageId`、`text`）
- **unsend**：撤回消息（`messageId`）
- **reply**：回复特定消息（`messageId`、`text`、`to`）
- **unsend**：撤回一条消息（`messageId`）
- **reply**：回复某条特定消息（`messageId`、`text`、`to`）
- **sendWithEffect**：使用 iMessage 效果发送（`text`、`to`、`effectId`）
- **renameGroup**：重命名群聊（`chatGuid`、`displayName`）
- **setGroupIcon**：设置群聊图标/照片（`chatGuid`、`media`）—— 在 macOS 26 Tahoe 上不稳定（API 可能返回成功，但图标不会同步）。
- **addParticipant**：向群组添加成员（`chatGuid`、`address`）
- **removeParticipant**：从群组移除成员（`chatGuid`、`address`）
- **addParticipant**：向群组添加某人（`chatGuid`、`address`）
- **removeParticipant**：将某人从群组中移除（`chatGuid`、`address`）
- **leaveGroup**：退出群聊（`chatGuid`）
- **upload-file**：发送媒体/文件（`to`、`buffer`、`filename`、`asVoice`）
- 语音备忘录：将 **MP3** 或 **CAF** 音频与 `asVoice: true` 一起设置，即可作为 iMessage 语音消息发送。BlueBubbles 在发送语音备忘录时会将 MP3 转换为 CAF。
- 旧别名：`sendAttachment` 仍然可用，但 `upload-file` 才是规范操作名称。
- 语音备忘录：将 **MP3** 或 **CAF** 音频与 `asVoice: true` 一起设置，以作为 iMessage 语音消息发送。BlueBubbles 在发送语音备忘录时会将 MP3 转换为 CAF。
- 旧别名：`sendAttachment` 仍可用，但 `upload-file` 是规范操作名称。
### 消息 ID（短 ID 与完整 ID）
@ -389,41 +390,43 @@ OpenClaw 可能会暴露_短_消息 ID（例如 `1`、`2`）以节省 token。
- `MessageSid` / `ReplyToId` 可以是短 ID。
- `MessageSidFull` / `ReplyToIdFull` 包含提供商的完整 ID。
- 短 ID 保存在内存中；重启或缓存清除后可能失效。
- 短 ID 存储在内存中；它们可能会在重启或缓存逐出后失效。
- 操作接受短 ID 或完整 `messageId`，但如果短 ID 已不可用，就会报错。
对于持久自动化和存储，请使用完整 ID：
对于持久化自动化和存储，请使用完整 ID：
- 模板：`{{MessageSidFull}}`、`{{ReplyToIdFull}}`
- 上下文：入站载荷中的 `MessageSidFull` / `ReplyToIdFull`
- 上下文：入站负载中的 `MessageSidFull` / `ReplyToIdFull`
模板变量参见 [Configuration](/zh-CN/gateway/configuration)。
模板变量请参见 [配置](/zh-CN/gateway/configuration)。
## 合并拆分发送的私信（一次编辑中同时包含命令 + URL）
<a id="coalescing-split-send-dms-command--url-in-one-composition"></a>
当用户在 iMessage 中同时输入命令和 URL 时——例如 `Dump https://example.com/article`——Apple 会把这次发送拆成**两个独立的 webhook 投递**：
## 合并拆分发送的私信（同一次输入中的命令 + URL）
当用户在 iMessage 中同时输入命令和 URL 时——例如 `Dump https://example.com/article`——Apple 会将这次发送拆分为**两个独立的 webhook 投递**：
1. 一条文本消息（`"Dump"`）。
2. 一个 URL 预览气泡（`"https://..."`），并带有 OG 预览图片作为附件。
2. 一个 URL 预览气泡（`"https://..."`），并附带 OG 预览图片作为附件。
在大多数环境中，这两个 webhook 会相隔约 0.8 - 2.0 秒到达 OpenClaw。如果不进行合并，智能体会在第 1 轮只收到命令本身，然后回复（通常是“把 URL 发给我”），等到第 2 轮才看到 URL——此时命令上下文已经丢失。
在大多数设置中，这两个 webhook 会以约 0.8 - 2.0 秒的间隔到达 OpenClaw。如果不进行合并，智能体在第 1 轮只会收到命令本身并作出回复（通常是“把 URL 发给我”），而直到第 2 轮才看到 URL——此时命令上下文已经丢失。
`channels.bluebubbles.coalesceSameSenderDms` 可让私信选择启用：将同一发送者连续发来的 webhook 合并为一次智能体轮次。群聊则继续按单条消息作为键，以保留多用户轮次结构。
`channels.bluebubbles.coalesceSameSenderDms` 可选择为私信启用连续同一发送者 webhook 的合并，使其进入同一个智能体轮次。群聊仍按每条消息单独分键，以保留多用户轮次结构。
### 何时启用
在以下情况下启用：
在以下情况启用：
- 你提供的 Skills 期望在一条消息中接收 `命令 + 负载`（dump、paste、save、queue 等）。
- 你的用户会把 URL、图片或长内容与命令一起粘贴发送。
- 你可以接受额外增加的私信轮次延迟（见下文）。
- 你提供的 Skills 预期 `command + payload` 在同一条消息中出现（dump、paste、save、queue 等）。
- 你的用户会将 URL、图片或长内容与命令一起粘贴发送。
- 你可以接受私信轮次增加的延迟（见下文）。
在以下情况下保持关闭：
在以下情况保持禁用：
- 你需要单词私信触发命令的最低延迟。
- 你需要单词级私信触发命令的最低延迟。
- 你的所有流程都是不带后续负载的一次性命令。
### 启用方式
### 启用方法
```json5
{
@ -435,17 +438,17 @@ OpenClaw 可能会暴露_短_消息 ID（例如 `1`、`2`）以节省 token。
}
```
当此标志开启，且未显式设置 `messages.inbound.byChannel.bluebubbles` 时，去抖窗口会扩大到 **2500 ms**（未启用合并时默认是 500 ms）。必须使用更宽的窗口——Apple 0.8 - 2.0 秒的拆分发送节奏无法落入更紧的默认窗口中。
启用该标志后，如果没有显式设置 `messages.inbound.byChannel.bluebubbles`，防抖窗口会扩展到 **2500 ms**（非合并模式默认值为 500 ms）。之所以需要更宽的窗口，是因为 Apple 的拆分发送节奏为 0.8 - 2.0 秒，无法适配更紧的默认窗口。
如果你要自行调整窗口：
如果你想自行调整该窗口：
```json5
{
messages: {
inbound: {
byChannel: {
// 2500 ms 适用于大多数环境；如果你的 Mac 较慢
// 或存在内存压力（观察到的间隔可能超过 2 秒），可提高到 4000 ms。
// 对大多数设置来说，2500 ms 可用；如果你的 Mac 较慢
// 或处于内存压力下（此时观察到的间隔可能会超过 2 秒），可提高到 4000 ms。
bluebubbles: 2500,
},
},
@ -455,60 +458,60 @@ OpenClaw 可能会暴露_短_消息 ID（例如 `1`、`2`）以节省 token。
### 权衡
- **私信控制命令会增加延迟。** 启用该标志后，私信控制命令消息（如 `Dump`、`Save` 等）现在会在分发前最多等待整个去抖窗口，以防后续还有负载 webhook 到来。群聊命令仍然会立即分发。
- **合并输出有上限**——合并文本最多 4000 个字符，超出时会带有显式的 `…[truncated]` 标记；附件上限为 20；来源条目上限为 10（超过后保留“第一条 + 最新条目”）。每个来源 `messageId` 仍然会进入入站去重，因此如果之后 MessagePoller 重放其中任意单个事件，系统仍会识别它是重复事件。
- **按渠道选择启用。** 其他渠道（Telegram、WhatsApp、Slack、……）不受影响。
- **私信控制命令会增加延迟。** 启用该标志后，私信控制命令消息（如 `Dump`、`Save` 等）现在会最多等待一个防抖窗口后再分发，以防后续还有负载 webhook 到来。群聊命令仍保持即时分发。
- **合并后的输出有边界限制**——合并文本上限为 4000 个字符，并带有明确的 `…[truncated]` 标记；附件上限为 20 个；源条目上限为 10 个（超出后保留首条和最新条目）。每个源 `messageId` 仍会进入入站去重，因此后续任何单独事件的 MessagePoller 重放都会被识别为重复。
- **按渠道选择启用。** 其他渠道（Telegram、WhatsApp、Slack……）不受影响。
### 场景与智能体实际看到的内容
| 用户输入内容 | Apple 投递内容 | 标志关闭（默认） | 标志开启 + 2500 ms 窗口 |
| ------------------------------------------------------------------ | ------------------------- | --------------------------------------- | ----------------------------------------------------------------------- |
| `Dump https://example.com`（一次发送） | 2 个 webhook，相隔约 1 秒 | 两个智能体轮次：“Dump” 单独一轮，然后是 URL | 一轮：合并文本 `Dump https://example.com` |
| `Save this 📎image.jpg caption`（附件 + 文本） | 2 个 webhook | 两轮 | 一轮：文本 + 图片 |
| `/status`（独立命令） | 1 个 webhook | 立即分发 | **最多等待整个窗口后再分发** |
| 单独粘贴 URL | 1 个 webhook | 立即分发 | 立即分发（bucket 中只有一个条目） |
| 文本 + URL 分几分钟作为两条独立消息刻意发送 | 窗口之外的 2 个 webhook | 两轮 | 两轮（窗口在两者之间到期） |
| 快速洪泛（窗口内 >10 条小型私信） | N 个 webhook | N 轮 | 一轮，带有上限输出（应用“第一条 + 最新条目”、文本/附件上限） |
| `Dump https://example.com`（一次发送） | 2 个 webhook，间隔约 1 秒 | 两个智能体轮次：先只有 “Dump”，再是 URL | 一个轮次：合并后的文本为 `Dump https://example.com` |
| `Save this 📎image.jpg caption`（附件 + 文本） | 2 个 webhook | 两个轮次 | 一个轮次：文本 + 图片 |
| `/status`（独立命令） | 1 个 webhook | 即时分发 | **最多等待窗口时长后再分发** |
| 单独粘贴一个 URL | 1 个 webhook | 即时分发 | 即时分发（桶中只有一个条目） |
| 文本 + URL 作为两条刻意分开发送的消息，间隔数分钟 | 窗口外的 2 个 webhook | 两个轮次 | 两个轮次（窗口已在它们之间过期） |
| 快速洪泛（窗口内超过 10 条小私信） | N 个 webhook | N 个轮次 | 一个轮次，带边界限制的输出（保留首条 + 最新条目，并应用文本/附件上限） |
### 拆分发送合并的故障排除
如果标志已开启，但拆分发送仍然作为两轮到达，请逐层检查：
如果标志已开启，但拆分发送仍然以两个轮次到达，请逐层检查：
1. **配置是否实际已加载。**
1. **确认配置已实际加载。**
```
```text
grep coalesceSameSenderDms ~/.openclaw/openclaw.json
```
然后执行 `openclaw gateway restart`——该标志会在 debouncer 注册表创建时读取。
然后执行 `openclaw gateway restart`——该标志会在 debouncer-registry 创建时读取。
2. **你的环境的去抖窗口是否足够宽。** 查看 BlueBubbles 服务器日志 `~/Library/Logs/bluebubbles-server/main.log`：
2. **你的设置的防抖窗口是否足够宽。** 查看位于 `~/Library/Logs/bluebubbles-server/main.log` 的 BlueBubbles 服务器日志：
```
```text
grep -E "Dispatching event to webhook" main.log | tail -20
```
测量 `"Dump"` 这类文本分发与后续 `"https://..."`; Attachments:` 分发之间的间隔。将 `messages.inbound.byChannel.bluebubbles` 提高到足以覆盖该间隔。
测量 `"Dump"` 这类文本分发与其后 `"https://..."`; Attachments:` 分发之间的间隔。将 `messages.inbound.byChannel.bluebubbles` 调高到能从容覆盖该间隔的值。
3. **会话 JSONL 时间戳 ≠ webhook 到达时间。** 会话事件时间戳（`~/.openclaw/agents/<id>/sessions/*.jsonl`）反映的是 Gateway 网关何时将消息交给智能体，**不是** webhook 何时到达。如果排队中的第二条消息被标记为 `[Queued messages while agent was busy]`，说明第二个 webhook 到达时，第一轮仍在运行——合并 bucket 已经刷新。请根据 BB 服务器日志而不是会话日志来调整窗口。
3. **会话 JSONL 时间戳 ≠ webhook 到达时间。** 会话事件时间戳（`~/.openclaw/agents/<id>/sessions/*.jsonl`）反映的是 Gateway 网关将消息交给智能体的时间，**而不是** webhook 到达时间。带有 `[Queued messages while agent was busy]` 标记的排队第二条消息，意味着第二个 webhook 到达时第一轮仍在运行——合并桶此时已经冲刷。请根据 BB 服务器日志而不是会话日志来调整窗口。
4. **内存压力拖慢了回复分发。** 在较小的机器（8 GB）上，智能体轮次可能耗时较长，以至于在回复完成前合并 bucket 就已刷新，结果 URL 作为排队的第二轮到达。检查 `memory_pressure` 和 `ps -o rss -p $(pgrep openclaw-gateway)`；如果 Gateway 网关的 RSS 超过约 500 MB 且压缩器处于活跃状态，请关闭其他重型进程或升级到更大的主机。
4. **内存压力导致回复分发变慢。** 在较小的机器（8 GB）上，智能体轮次可能耗时足够长，以至于在回复完成前合并桶就已冲刷，URL 因而作为排队的第二轮到达。检查 `memory_pressure` 以及 `ps -o rss -p $(pgrep openclaw-gateway)`；如果 Gateway 网关的 RSS 超过约 500 MB，且压缩器处于活动状态，请关闭其他高负载进程，或迁移到更大的主机。
5. **回复引用发送走的是另一条路径。** 如果用户把 `Dump` 作为对现有 URL 预览气泡的**回复**发出（iMessage 会在 Dump 气泡上显示 “1 Reply” 标记），那么 URL 位于 `replyToBody` 中，而不是第二个 webhook 中。这时不适用合并——这是 Skills/提示词层面的问题，而不是 debouncer 层面的问题。
5. **回复引用发送走的是另一条路径。** 如果用户是将 `Dump` 作为对已有 URL 气泡的**回复**发送（iMessage 会在 Dump 气泡上显示 “1 Reply” 标记），那么 URL 位于 `replyToBody` 中，而不是第二个 webhook 中。此时不适用合并——这属于 Skills/提示词问题，而不是去抖器问题。
## 分块流式传输
控制是将回复作为单条消息发送，还是按块流式发送：
控制响应是作为单条消息发送，还是按块流式发送：
__OC_I18N_900017__
## 媒体 + 限制
- 入站附件会被下载并存储在媒体缓存中。
- 入站和出站媒体的大小上限由 `channels.bluebubbles.mediaMaxMb` 控制（默认：8 MB）。
- 入站附件会被下载并存储到媒体缓存中。
- 通过 `channels.bluebubbles.mediaMaxMb` 控制入站和出站媒体大小上限（默认：8 MB）。
- 出站文本会按 `channels.bluebubbles.textChunkLimit` 分块（默认：4000 个字符）。
## 配置参考
完整配置： [Configuration](/gateway/configuration)
完整配置： [配置](/gateway/configuration)
提供商选项：
@ -517,20 +520,20 @@ __OC_I18N_900017__
- `channels.bluebubbles.password`：API 密码。
- `channels.bluebubbles.webhookPath`：webhook 端点路径（默认：`/bluebubbles-webhook`）。
- `channels.bluebubbles.dmPolicy`：`pairing | allowlist | open | disabled`（默认：`pairing`）。
- `channels.bluebubbles.allowFrom`：私信允许列表（handles、电子邮件、E.164 号码、`chat_id:*`、`chat_guid:*`）。
- `channels.bluebubbles.allowFrom`：私信 allowlist（handles、邮箱、E.164 号码、`chat_id:*`、`chat_guid:*`）。
- `channels.bluebubbles.groupPolicy`：`open | allowlist | disabled`（默认：`allowlist`）。
- `channels.bluebubbles.groupAllowFrom`：群组发送者允许列表。
- `channels.bluebubbles.enrichGroupParticipantsFromContacts`：在 macOS 上，在门控通过后，可选择从本地通讯录增强未命名的群组参与者。默认：`false`。
- `channels.bluebubbles.groups`：按群组配置（`requireMention` 等）。
- `channels.bluebubbles.groupAllowFrom`：群组发送者 allowlist。
- `channels.bluebubbles.enrichGroupParticipantsFromContacts`：在 macOS 上，可在门控通过后选择从本地通讯录中补全未命名群组参与者。默认：`false`。
- `channels.bluebubbles.groups`：每个群组的配置（`requireMention` 等）。
- `channels.bluebubbles.sendReadReceipts`：发送已读回执（默认：`true`）。
- `channels.bluebubbles.blockStreaming`：启用分块流式传输（默认：`false`；流式回复所必需）。
- `channels.bluebubbles.blockStreaming`：启用分块流式传输（默认：`false`；流式回复必需）。
- `channels.bluebubbles.textChunkLimit`：出站分块字符数上限（默认：4000）。
- `channels.bluebubbles.sendTimeoutMs`：通过 `/api/v1/message/text` 发送出站文本时每个请求的超时时间（毫秒）（默认：30000）。在 macOS 26 环境中，如果 Private API 的 iMessage 发送可能在 iMessage 框架内部停滞 60 秒以上，请调高此值；例如设为 `45000` 或 `60000`。探测、聊天查找、表情回应、编辑和健康检查当前仍保留较短的 10 秒默认值；后续计划将更宽的超时覆盖到表情回应和编辑。按账户覆盖：`channels.bluebubbles.accounts.<accountId>.sendTimeoutMs`。
- `channels.bluebubbles.chunkMode`：`length`（默认）仅在超过 `textChunkLimit` 时拆分；`newline` 会先按空行（段落边界）拆分，再按长度分块。
- `channels.bluebubbles.mediaMaxMb`：入站/出站媒体大小上限（MB）（默认：8）。
- `channels.bluebubbles.mediaLocalRoots`：允许用于出站本地媒体路径的绝对本地目录显式允许列表。默认会拒绝发送本地路径，除非配置了此项。按账户覆盖：`channels.bluebubbles.accounts.<accountId>.mediaLocalRoots`。
- `channels.bluebubbles.coalesceSameSenderDms`：将同一发送者连续发来的私信 webhook 合并为一次智能体轮次，使 Apple 拆分的“文本 + URL”发送能够作为一条消息到达（默认：`false`）。场景、窗口调优和权衡取舍参见 [合并拆分发送的私信](#coalescing-split-send-dms-command--url-in-one-composition)。当启用且未显式设置 `messages.inbound.byChannel.bluebubbles` 时，会将默认入站去抖窗口从 500 ms 扩大到 2500 ms。
- `channels.bluebubbles.historyLimit`：用于上下文的群组消息最大数量（0 表示禁用）。
- `channels.bluebubbles.sendTimeoutMs`：通过 `/api/v1/message/text` 发送出站文本时每个请求的超时时间（毫秒，默认：30000）。在 macOS 26 设置中，如果 Private API 的 iMessage 发送可能在 iMessage 框架内部卡住 60 秒以上，可将其调高，例如 `45000` 或 `60000`。探测、聊天查找、反应、编辑和健康检查目前仍保持较短的 10 秒默认值；后续计划将更长超时覆盖到反应和编辑。每账户覆盖：`channels.bluebubbles.accounts.<accountId>.sendTimeoutMs`。
- `channels.bluebubbles.chunkMode`：`length`（默认）仅在超过 `textChunkLimit` 时拆分；`newline` 则先按空行（段落边界）拆分，再按长度分块。
- `channels.bluebubbles.mediaMaxMb`：入站/出站媒体大小上限（MB，默认：8）。
- `channels.bluebubbles.mediaLocalRoots`：允许出站本地媒体路径使用的绝对本地目录显式 allowlist。默认情况下，除非配置了此项，否则会拒绝本地路径发送。每账户覆盖：`channels.bluebubbles.accounts.<accountId>.mediaLocalRoots`。
- `channels.bluebubbles.coalesceSameSenderDms`：将连续来自同一发送者的私信 webhook 合并为一个智能体轮次，从而让 Apple 的文本 + URL 拆分发送以单条消息到达（默认：`false`）。有关场景、窗口调优和权衡，请参见[合并拆分发送的私信](#coalescing-split-send-dms-command--url-in-one-composition)。当启用且未显式设置 `messages.inbound.byChannel.bluebubbles` 时，会将默认入站防抖窗口从 500 ms 扩大到 2500 ms。
- `channels.bluebubbles.historyLimit`：用于上下文的最大群组消息数（0 表示禁用）。
- `channels.bluebubbles.dmHistoryLimit`：私信历史记录上限。
- `channels.bluebubbles.actions`：启用/禁用特定操作。
- `channels.bluebubbles.accounts`：多账户配置。
@ -542,42 +545,42 @@ __OC_I18N_900017__
## 寻址 / 投递目标
为了获得稳定路由，优先使用 `chat_guid`：
为获得稳定路由，优先使用 `chat_guid`：
- `chat_guid:iMessage;-;+15555550123`（群组首选）
- `chat_id:123`
- `chat_identifier:...`
- 直接 handle：`+15555550123`、`user@example.com`
- 如果某个直接 handle 没有现有的私信聊天，OpenClaw 会通过 `POST /api/v1/chat/new` 创建一个。这要求启用 BlueBubbles Private API。
- 直接 handles：`+15555550123`、`user@example.com`
- 如果直接 handle 没有现有私信聊天，OpenClaw 会通过 `POST /api/v1/chat/new` 创建一个。此功能要求启用 BlueBubbles Private API。
### iMessage 与 SMS 路由
当同一个 handle 在 Mac 上同时存在 iMessage 聊天和 SMS 聊天时（例如某个已注册 iMessage 的电话号码，同时也收过绿色气泡的回退消息），OpenClaw 会优先选择 iMessage 聊天，绝不会静默降级到 SMS。要强制使用 SMS 聊天，请使用显式的 `sms:` 目标前缀（例如 `sms:+15555550123`）。如果某个 handle 没有匹配的 iMessage 聊天，则仍会通过 BlueBubbles 报告的相应聊天发送。
当同一个 handle 在 Mac 上同时存在 iMessage 聊天和 SMS 聊天时（例如某个已注册 iMessage 的手机号也曾接收过绿气泡回退消息），OpenClaw 会优先使用 iMessage 聊天，绝不会静默降级为 SMS。若要强制使用 SMS 聊天，请使用显式 `sms:` 目标前缀（例如 `sms:+15555550123`）。对于没有匹配 iMessage 聊天的 handle，仍会通过 BlueBubbles 报告的对应聊天发送。
## 安全
- webhook 请求通过将查询参数或请求头中的 `guid`/`password` 与 `channels.bluebubbles.password` 进行比较来完成身份验证。
- 请妥善保管 API 密码和 webhook 端点（将它们视为凭据）。
- BlueBubbles webhook 身份验证没有 localhost 绕过。如果你代理 webhook 流量，请在整个请求链路中保留 BlueBubbles 密码。这里的 `gateway.trustedProxies` 不能替代 `channels.bluebubbles.password`。参见 [Gateway 网关安全](/gateway/security#reverse-proxy-configuration)。
- 如果要在局域网之外暴露 BlueBubbles 服务器，请启用 HTTPS 和防火墙规则。
- 请妥善保管 API 密码和 webhook 端点（将它们视为凭证）。
- BlueBubbles webhook 身份验证没有 localhost 绕过。如果你代理 webhook 流量，请在整个请求链路中保留 BlueBubbles 密码。这里的 `gateway.trustedProxies` 不能替代 `channels.bluebubbles.password`。请参见 [Gateway 网关安全](/gateway/security#reverse-proxy-configuration)。
- 如果要在 LAN 之外暴露 BlueBubbles 服务器，请启用 HTTPS 和防火墙规则。
## 故障排除
- 如果“正在输入”/已读事件停止工作，请检查 BlueBubbles webhook 日志，并验证 Gateway 网关路径与 `channels.bluebubbles.webhookPath` 一致。
- 如果正在输入/已读事件停止工作，请检查 BlueBubbles webhook 日志，并确认 Gateway 网关路径与 `channels.bluebubbles.webhookPath` 匹配。
- 配对码会在一小时后过期；请使用 `openclaw pairing list bluebubbles` 和 `openclaw pairing approve bluebubbles <code>`。
- 表情回应需要 BlueBubbles private API（`POST /api/v1/message/react`）；请确认服务器版本提供了该接口。
- 编辑/撤回需要 macOS 13+ 和兼容的 BlueBubbles 服务器版本。在 macOS 26（Tahoe）上，由于 private API 变更，编辑当前不可用。
- 群组图标更新在 macOS 26（Tahoe）上可能不稳定：API 可能返回成功，但新图标不会同步。
- OpenClaw 会根据 BlueBubbles 服务器的 macOS 版本自动隐藏已知有问题的操作。如果在 macOS 26（Tahoe）上仍然显示 edit，请手动使用 `channels.bluebubbles.actions.edit=false` 禁用它。
- 已启用 `coalesceSameSenderDms`，但拆分发送（例如 `Dump` + URL）仍然作为两轮到达：请参阅[拆分发送合并的故障排除](#split-send-coalescing-troubleshooting)检查清单——常见原因包括去抖窗口过窄、将会话日志时间戳误读为 webhook 到达时间，或发送的是回复引用（它使用的是 `replyToBody`，而不是第二个 webhook）。
- Reactions 需要 BlueBubbles private API（`POST /api/v1/message/react`）；请确保服务器版本已提供该接口。
- 编辑/撤回需要 macOS 13+ 和兼容的 BlueBubbles 服务器版本。在 macOS 26（Tahoe）上，由于 private API 变更，编辑目前已失效。
- 在 macOS 26（Tahoe）上，群组图标更新可能不稳定：API 可能返回成功，但新图标不会同步。
- OpenClaw 会根据 BlueBubbles 服务器的 macOS 版本自动隐藏已知损坏的操作。如果在 macOS 26（Tahoe）上仍然显示编辑，请使用 `channels.bluebubbles.actions.edit=false` 手动禁用。
- 已启用 `coalesceSameSenderDms`，但拆分发送（例如 `Dump` + URL）仍然以两个轮次到达：请参阅[拆分发送合并的故障排除](#split-send-coalescing-troubleshooting)检查清单——常见原因包括防抖窗口过短、误将会话日志时间戳当作 webhook 到达时间，或使用了回复引用发送（其使用的是 `replyToBody`，而不是第二个 webhook）。
- 查看状态/健康信息：`openclaw status --all` 或 `openclaw status --deep`。
有关通用渠道工作流的参考，请参见 [Channels](/zh-CN/channels) 和 [Plugins](/zh-CN/tools/plugin) 指南。
有关通用渠道工作流参考，请参见 [Channels](/zh-CN/channels) 和 [Plugins](/zh-CN/tools/plugin) 指南。
## 相关内容
- [Channels Overview](/zh-CN/channels) —— 所有受支持的渠道
- [Pairing](/zh-CN/channels/pairing) —— 私信认证和配对流程
- [Groups](/zh-CN/channels/groups) —— 群聊行为和提及门控
- [Channel Routing](/zh-CN/channels/channel-routing) —— 消息的会话路由
- [Security](/zh-CN/gateway/security) —— 访问模型与加固
- [Channels Overview](/zh-CN/channels) — 所有受支持的渠道
- [Pairing](/zh-CN/channels/pairing) — 私信身份验证与配对流程
- [Groups](/zh-CN/channels/groups) — 群聊行为与提及门控
- [Channel Routing](/zh-CN/channels/channel-routing) — 消息的会话路由
- [Security](/zh-CN/gateway/security) — 访问模型与加固

62
docs/zh-CN/channels/channel-routing.md
View File

@ -4,43 +4,43 @@ read_when:
summary: 各渠道（WhatsApp、Telegram、Discord、Slack）的路由规则和共享上下文
title: 渠道路由
x-i18n:
generated_at: "2026-04-23T00:41:51Z"
generated_at: "2026-04-23T06:40:05Z"
model: gpt-5.4
provider: openai
source_hash: e7d437d85d5edd3a0157fd683c6ec63d5d7e905e3e6bdce9a3ba11ddab97d3c2
source_hash: ad1101d9d3411d9e9f48efd14c0dab09d76e83a6bd93c713d38efc01a14c8391
source_path: channels/channel-routing.md
workflow: 15
---
# 渠道与路由
OpenClaw 会将回复**路由回消息来源的那个渠道**。模型不会选择渠道；路由是确定性的，并由主机配置控制。
OpenClaw 会将回复**发回消息来源的那个渠道**。模型不会选择渠道；路由是确定性的，并由宿主配置控制。
## 关键术语
- **渠道**：`telegram`、`whatsapp`、`discord`、`irc`、`googlechat`、`slack`、`signal`、`imessage`、`line`，以及扩展渠道。`webchat` 是内部的 WebChat UI 渠道，不是可配置的出站渠道。
- **渠道**：`telegram`、`whatsapp`、`discord`、`irc`、`googlechat`、`slack`、`signal`、`imessage`、`line`，以及插件渠道。`webchat` 是内部 WebChat UI 渠道，不是可配置的出站渠道。
- **AccountId**：每个渠道的账户实例（在支持时）。
- 可选的渠道默认账户：`channels.<channel>.defaultAccount` 用于选择在出站路径未指定 `accountId` 时使用哪个账户。
- 在多账户配置中，当配置了两个或更多账户时，请设置显式默认值（`defaultAccount` 或 `accounts.default`）。否则，回退路由可能会选择第一个标准化后的账户 ID。
- 可选的渠道默认账户：`channels.<channel>.defaultAccount` 用于选择当出站路径未指定 `accountId` 时应使用哪个账户。
- 在多账户配置中，当配置了两个或更多账户时，请设置一个显式默认值（`defaultAccount` 或 `accounts.default`）。否则，回退路由可能会选择第一个规范化后的账户 ID。
- **AgentId**：隔离的工作区 + 会话存储（“大脑”）。
- **SessionKey**：用于存储上下文并控制并发的桶键。
## 会话键形状（示例）
默认情况下，私信会折叠到智能体的 **main** 会话：
默认情况下，私信会收敛到智能体的**主**会话：
- `agent:<agentId>:<mainKey>`（默认：`agent:main:main`）
即使私信会话历史与 main 共享，针对外部私信，沙箱和工具策略仍会使用派生出的按账户区分的私聊运行时键，这样来自渠道的消息就不会被当作本地 main 会话运行处理。
即使私信会话历史与主会话共享，沙箱和工具策略仍会为外部私信使用派生的、按账户区分的私聊运行时键，这样来自渠道的消息就不会被当作本地主会话运行来处理。
群组和频道在每个渠道内仍然保持隔离：
群组和频道在每个渠道内仍保持隔离：
- 群组：`agent:<agentId>:<channel>:group:<id>`
- 频道/房间：`agent:<agentId>:<channel>:channel:<id>`
线程：
- Slack/Discord 线程会将 `:thread:<threadId>` 追加到基础键后面。
- Slack/Discord 线程会在基础键后追加 `:thread:<threadId>`。
- Telegram 论坛话题会将 `:topic:<topicId>` 嵌入群组键中。
示例：
@ -48,36 +48,37 @@ OpenClaw 会将回复**路由回消息来源的那个渠道**。模型不会选
- `agent:main:telegram:group:-1001234567890:topic:42`
- `agent:main:discord:channel:123456:thread:987654`
## main 私信路由固定
## 主私信路由固定
当 `session.dmScope` 为 `main` 时，私信可能共享一个 main 会话。为了防止会话的 `lastRoute` 被非所有者私信覆盖，OpenClaw 会在以下条件全部满足时，从 `allowFrom` 推断出一个固定所有者：
当 `session.dmScope` 为 `main` 时，私信可以共享同一个主会话。
为防止会话的 `lastRoute` 被非所有者私信覆盖，若以下条件全部满足，OpenClaw 会根据 `allowFrom` 推断一个固定所有者：
- `allowFrom` 恰好有一个非通配符条目。
- 该条目可被标准化为该渠道中的具体发送者 ID。
- `allowFrom` 恰好包含一个非通配符条目。
- 该条目可以规范化为该渠道中的具体发送者 ID。
- 入站私信发送者与该固定所有者不匹配。
在这种不匹配情况下，OpenClaw 仍会记录入站会话元数据，但会跳过更新 main 会话的 `lastRoute`。
在这种不匹配的情况下，OpenClaw 仍会记录入站会话元数据，但会跳过更新主会话的 `lastRoute`。
## 路由规则（如何选择一个智能体）
## 路由规则（如何选择智能体）
路由会为每条入站消息选择**一个智能体**：
1. **精确对等方匹配**（带 `peer.kind` + `peer.id` 的 `bindings`）。
1. **精确对等方匹配**（带有 `peer.kind` + `peer.id` 的 `bindings`）。
2. **父对等方匹配**（线程继承）。
3. **服务器 + 角色匹配**（Discord），通过 `guildId` + `roles`。
4. **服务器匹配**（Discord），通过 `guildId`。
3. **公会 + 角色匹配**（Discord），通过 `guildId` + `roles`。
4. **公会匹配**（Discord），通过 `guildId`。
5. **团队匹配**（Slack），通过 `teamId`。
6. **账户匹配**（渠道上的 `accountId`）。
7. **渠道匹配**（该渠道上的任意账户，`accountId: "*"`）。
8. **默认智能体**（`agents.list[].default`，否则为列表中的第一项，回退到 `main`）。
8. **默认智能体**（`agents.list[].default`，否则为列表中的第一项，回退为 `main`）。
当一个绑定包含多个匹配字段（`peer`、`guildId`、`teamId`、`roles`）时，**所有已提供的字段都必须匹配**，该绑定才会生效。
当一个绑定包含多个匹配字段（`peer`、`guildId`、`teamId`、`roles`）时，**所有已提供字段都必须匹配**，该绑定才会生效。
匹配到的智能体决定使用哪个工作区和会话存储。
## 广播组（运行多个智能体）
广播组允许你针对同一个对等方运行**多个智能体**，前提是 **OpenClaw 本来就会回复**（例如：在 WhatsApp 群组中，通过提及/激活门控之后）。
广播组让你可以在同一个对等方上运行**多个智能体**，前提是 **OpenClaw 原本会进行回复**（例如：在 WhatsApp 群组中，通过提及/激活门控之后）。
配置：
@ -91,7 +92,7 @@ OpenClaw 会将回复**路由回消息来源的那个渠道**。模型不会选
}
```
参见：[Broadcast Groups](/zh-CN/channels/broadcast-groups)。
参见：[广播组](/zh-CN/channels/broadcast-groups)。
## 配置概览
@ -117,21 +118,22 @@ OpenClaw 会将回复**路由回消息来源的那个渠道**。模型不会选
会话存储位于状态目录下（默认 `~/.openclaw`）：
- `~/.openclaw/agents/<agentId>/sessions/sessions.json`
- JSONL 转录文件与该存储文件位于同一目录
- JSONL 转录文件与该存储并列保存
你可以通过 `session.store` 和 `{agentId}` 模板覆盖存储路径。
Gateway 网关 和 ACP 会话发现也会扫描默认 `agents/` 根目录下以及模板化 `session.store` 根目录下的磁盘后备智能体存储。发现到的存储必须保持在解析后的智能体根目录内，并使用常规的 `sessions.json` 文件。符号链接和根目录外路径会被忽略。
Gateway 网关 和 ACP 会话发现也会扫描默认 `agents/` 根目录下以及模板化 `session.store` 根目录下、由磁盘支持的智能体存储。发现到的存储必须保持在解析后的智能体根目录内，并使用常规的 `sessions.json` 文件。符号链接和根目录外路径会被忽略。
## WebChat 行为
WebChat 会附加到**所选智能体**，并默认使用该智能体的 main 会话。因此，WebChat 让你可以在一个地方查看该智能体的跨渠道上下文。
WebChat 会附加到**所选智能体**，并默认使用该智能体的主会话。
因此，WebChat 让你能够在一个地方查看该智能体的跨渠道上下文。
## 回复上下文
入站回复包含：
入站回复在可用时会包含：
- 在可用时包含 `ReplyToId`、`ReplyToBody` 和 `ReplyToSender`。
- 引用上下文会作为一个 `[Replying to ...]` 块追加到 `Body` 中。
- `ReplyToId`、`ReplyToBody` 和 `ReplyToSender`。
- 引用上下文会作为 `[Replying to ...]` 块追加到 `Body` 中。
这在各个渠道之间保持一致。
这一行为在各渠道之间保持一致。

144
docs/zh-CN/channels/feishu.md
View File

@ -5,10 +5,10 @@ read_when:
summary: Feishu 机器人概览、功能和配置
title: Feishu
x-i18n:
generated_at: "2026-04-13T10:05:19Z"
generated_at: "2026-04-23T06:40:05Z"
model: gpt-5.4
provider: openai
source_hash: 77fcf95a3fab534ed898bc157d76bf8bdfa8bf8a918d6af84c0db19890916c1a
source_hash: 11bf136cecb26dc939c5e78e020c0e6aa3312d9f143af0cab7568743c728cf13
source_path: channels/feishu.md
workflow: 15
---
@ -30,7 +30,7 @@ Feishu/Lark 是一个一体化协作平台，团队可以在其中聊天、共
```bash
openclaw channels login --channel feishu
```
使用你的 Feishu/Lark 移动应用扫描二维码，以自动创建一个 Feishu/Lark 机器人。
使用你的 Feishu/Lark 移动应用扫描二维码，自动创建一个 Feishu/Lark 机器人。
</Step>
<Step title="设置完成后，重启 Gateway 网关以应用更改">
@ -48,7 +48,7 @@ Feishu/Lark 是一个一体化协作平台，团队可以在其中聊天、共
配置 `dmPolicy` 以控制谁可以向机器人发送私信：
- `"pairing"` — 未知用户会收到配对码；通过 CLI 批准
- `"pairing"` — 未知用户会收到一个配对码；通过 CLI 批准
- `"allowlist"` — 只有列在 `allowFrom` 中的用户可以聊天（默认：仅机器人所有者）
- `"open"` — 允许所有用户
- `"disabled"` — 禁用所有私信
@ -64,25 +64,25 @@ openclaw pairing approve feishu <CODE>
**群组策略**（`channels.feishu.groupPolicy`）：
| Value | 行为 |
| ------------- | ---------------------------------- |
| `"open"` | 响应群组中的所有消息 |
| `"allowlist"` | 仅响应 `groupAllowFrom` 中的群组 |
| `"disabled"` | 禁用所有群组消息 |
| Value | 行为 |
| ------------- | ------------------------------------------ |
| `"open"` | 响应群组中的所有消息 |
| `"allowlist"` | 仅响应 `groupAllowFrom` 中的群组 |
| `"disabled"` | 禁用所有群组消息 |
默认值：`allowlist`
**提及要求**（`channels.feishu.requireMention`）：
- `true` — 必须 @提及（默认）
- `false` — 无需 @提及也会响应
- `true` — 需要 @mention（默认）
- `false` — 无需 @mention 也会响应
- 按群组覆盖：`channels.feishu.groups.<chat_id>.requireMention`
---
## 群组配置示例
### 允许所有群组，不需要 @提及
### 允许所有群组，无需 @mention
```json5
{
@ -94,7 +94,7 @@ openclaw pairing approve feishu <CODE>
}
```
### 允许所有群组，但仍然要求 @提及
### 允许所有群组，但仍要求 @mention
```json5
{
@ -114,7 +114,7 @@ openclaw pairing approve feishu <CODE>
channels: {
feishu: {
groupPolicy: "allowlist",
// 群组 ID 类似于：oc_xxx
// 群组 ID 形如：oc_xxx
groupAllowFrom: ["oc_xxx", "oc_yyy"],
},
},
@ -131,7 +131,7 @@ openclaw pairing approve feishu <CODE>
groupAllowFrom: ["oc_xxx"],
groups: {
oc_xxx: {
// 用户 open_id 类似于：ou_xxx
// 用户 open_id 形如：ou_xxx
allowFrom: ["ou_user1", "ou_user2"],
},
},
@ -142,11 +142,13 @@ openclaw pairing approve feishu <CODE>
---
<a id="get-groupuser-ids"></a>
## 获取群组/用户 ID
### 群组 ID（`chat_id`，格式：`oc_xxx`）
在 Feishu/Lark 中打开群组，点击右上角的菜单图标，然后进入**设置**。群组 ID（`chat_id`）会显示在设置页面中。
在 Feishu/Lark 中打开群组，点击右上角的菜单图标，然后进入 **设置**。群组 ID（`chat_id`）会显示在设置页面中。
![Get Group ID](/images/feishu-get-group-id.png)
@ -168,11 +170,11 @@ openclaw pairing list feishu
## 常用命令
| Command | 说明 |
| --------- | ----------------------- |
| `/status` | 显示机器人状态 |
| `/reset` | 重置当前会话 |
| `/model` | 显示或切换 AI 模型 |
| Command | 说明 |
| --------- | --------------------------- |
| `/status` | 显示机器人状态 |
| `/reset` | 重置当前会话 |
| `/model` | 显示或切换 AI 模型 |
> Feishu/Lark 不支持原生斜杠命令菜单，因此请将这些命令作为普通文本消息发送。
@ -182,16 +184,16 @@ openclaw pairing list feishu
### 机器人在群聊中没有响应
1. 确保机器人已加入群组
2. 确保你已 @提及机器人（默认必需）
1. 确保机器人已被添加到群组中
2. 确保你已 @mention 机器人（默认要求）
3. 验证 `groupPolicy` 不是 `"disabled"`
4. 检查日志：`openclaw logs --follow`
### 机器人未收到消息
### 机器人没有收到消息
1. 确保机器人应用已在 Feishu Open Platform / Lark Developer 中发布并通过审核
1. 确保机器人已在 Feishu Open Platform / Lark Developer 中发布并通过审核
2. 确保事件订阅包含 `im.message.receive_v1`
3. 确保已选择**持久连接**（WebSocket）
3. 确保已选择 **persistent connection**（WebSocket）
4. 确保已授予所有必需的权限范围
5. 确保 Gateway 网关正在运行：`openclaw gateway status`
6. 检查日志：`openclaw logs --follow`
@ -199,14 +201,14 @@ openclaw pairing list feishu
### App Secret 泄露
1. 在 Feishu Open Platform / Lark Developer 中重置 App Secret
2. 更新配置中的值
2. 更新你配置中的值
3. 重启 Gateway 网关：`openclaw gateway restart`
---
## 高级配置
### 多账号
### 多账户
```json5
{
@ -231,7 +233,7 @@ openclaw pairing list feishu
}
```
`defaultAccount` 用于控制当出站 API 未指定 `accountId` 时使用哪个账号。
`defaultAccount` 用于控制当出站 API 未指定 `accountId` 时使用哪个账户。
### 消息限制
@ -247,20 +249,20 @@ Feishu/Lark 支持通过交互式卡片进行流式回复。启用后，机器
channels: {
feishu: {
streaming: true, // 启用流式卡片输出（默认：true）
blockStreaming: true, // 启用块级分块流式传输（默认：true）
blockStreaming: true, // 启用块级流式传输（默认：true）
},
},
}
```
将 `streaming: false` 设为关闭后，会一次性发送完整回复。
将 `streaming: false` 设为关闭后，会以一条完整消息发送完整回复。
### 配额优化
使用两个可选标志减少 Feishu/Lark API 调用次数：
使用两个可选标志来减少 Feishu/Lark API 调用次数：
- `typingIndicator`（默认 `true`）：设为 `false` 以跳过“正在输入”反应调用
- `resolveSenderNames`（默认 `true`）：设为 `false` 以跳过发送者资料查找
- `typingIndicator`（默认 `true`）：设为 `false` 以跳过正在输入反应调用
- `resolveSenderNames`（默认 `true`）：设为 `false` 以跳过发送者资料查询
```json5
{
@ -329,7 +331,7 @@ Feishu/Lark 支持用于私信和群组话题消息的 ACP。Feishu/Lark ACP 由
/acp spawn codex --thread here
```
`--thread here` 可用于私信和 Feishu/Lark 话题消息。后续消息会在已绑定的会话中直接路由到该 ACP 会话。
`--thread here` 适用于私信和 Feishu/Lark 话题消息。绑定会话中的后续消息会直接路由到该 ACP 会话。
### 多智能体路由
@ -365,45 +367,45 @@ Feishu/Lark 支持用于私信和群组话题消息的 ACP。Feishu/Lark ACP 由
路由字段：
- `match.channel`: `"feishu"`
- `match.peer.kind`: `"direct"`（私信）或 `"group"`（群聊）
- `match.peer.id`: 用户 Open ID（`ou_xxx`）或群组 ID（`oc_xxx`）
- `match.channel`：`"feishu"`
- `match.peer.kind`：`"direct"`（私信）或 `"group"`（群聊）
- `match.peer.id`：用户 Open ID（`ou_xxx`）或群组 ID（`oc_xxx`）
查找提示请参见 [获取群组/用户 ID](#get-groupuser-ids)。
有关查找提示，请参见[获取群组/用户 ID](#get-groupuser-ids)。
---
## 配置参考
完整配置：[Gateway configuration](/zh-CN/gateway/configuration)
完整配置：[Gateway 网关配置](/zh-CN/gateway/configuration)
| Setting | 说明 | 默认值 |
| ------------------------------------------------- | ------------------------------------ | ---------------- |
| `channels.feishu.enabled` | 启用/禁用该渠道 | `true` |
| `channels.feishu.domain` | API 域名（`feishu` 或 `lark`） | `feishu` |
| Setting | 说明 | 默认值 |
| ------------------------------------------------- | ------------------------------------------ | ---------------- |
| `channels.feishu.enabled` | 启用/禁用该渠道 | `true` |
| `channels.feishu.domain` | API 域（`feishu` 或 `lark`） | `feishu` |
| `channels.feishu.connectionMode` | 事件传输方式（`websocket` 或 `webhook`） | `websocket` |
| `channels.feishu.defaultAccount` | 出站路由的默认账号 | `default` |
| `channels.feishu.verificationToken` | webhook 模式必需 | — |
| `channels.feishu.encryptKey` | webhook 模式必需 | — |
| `channels.feishu.webhookPath` | webhook 路由路径 | `/feishu/events` |
| `channels.feishu.webhookHost` | webhook 绑定主机 | `127.0.0.1` |
| `channels.feishu.webhookPort` | webhook 绑定端口 | `3000` |
| `channels.feishu.accounts.<id>.appId` | App ID | — |
| `channels.feishu.accounts.<id>.appSecret` | App Secret | — |
| `channels.feishu.accounts.<id>.domain` | 按账号覆盖域名 | `feishu` |
| `channels.feishu.dmPolicy` | 私信策略 | `allowlist` |
| `channels.feishu.allowFrom` | 私信允许列表（`open_id` 列表） | [BotOwnerId] |
| `channels.feishu.groupPolicy` | 群组策略 | `allowlist` |
| `channels.feishu.groupAllowFrom` | 群组允许列表 | — |
| `channels.feishu.requireMention` | 群组中需要 @提及 | `true` |
| `channels.feishu.groups.<chat_id>.requireMention` | 按群组覆盖 @提及要求 | 继承 |
| `channels.feishu.groups.<chat_id>.enabled` | 启用/禁用特定群组 | `true` |
| `channels.feishu.textChunkLimit` | 消息分块大小 | `2000` |
| `channels.feishu.mediaMaxMb` | 媒体大小限制 | `30` |
| `channels.feishu.streaming` | 流式卡片输出 | `true` |
| `channels.feishu.blockStreaming` | 分块流式传输 | `true` |
| `channels.feishu.typingIndicator` | 发送“正在输入”反应 | `true` |
| `channels.feishu.resolveSenderNames` | 解析发送者显示名称 | `true` |
| `channels.feishu.defaultAccount` | 用于出站路由的默认账户 | `default` |
| `channels.feishu.verificationToken` | webhook 模式必需 | — |
| `channels.feishu.encryptKey` | webhook 模式必需 | — |
| `channels.feishu.webhookPath` | Webhook 路由路径 | `/feishu/events` |
| `channels.feishu.webhookHost` | Webhook 绑定主机 | `127.0.0.1` |
| `channels.feishu.webhookPort` | Webhook 绑定端口 | `3000` |
| `channels.feishu.accounts.<id>.appId` | App ID | — |
| `channels.feishu.accounts.<id>.appSecret` | App Secret | — |
| `channels.feishu.accounts.<id>.domain` | 按账户覆盖域设置 | `feishu` |
| `channels.feishu.dmPolicy` | 私信策略 | `allowlist` |
| `channels.feishu.allowFrom` | 私信允许列表（`open_id` 列表） | [BotOwnerId] |
| `channels.feishu.groupPolicy` | 群组策略 | `allowlist` |
| `channels.feishu.groupAllowFrom` | 群组允许列表 | — |
| `channels.feishu.requireMention` | 在群组中要求 @mention | `true` |
| `channels.feishu.groups.<chat_id>.requireMention` | 按群组覆盖 @mention 要求 | inherited |
| `channels.feishu.groups.<chat_id>.enabled` | 启用/禁用特定群组 | `true` |
| `channels.feishu.textChunkLimit` | 消息分块大小 | `2000` |
| `channels.feishu.mediaMaxMb` | 媒体大小限制 | `30` |
| `channels.feishu.streaming` | 流式卡片输出 | `true` |
| `channels.feishu.blockStreaming` | 分块流式传输 | `true` |
| `channels.feishu.typingIndicator` | 发送正在输入反应 | `true` |
| `channels.feishu.resolveSenderNames` | 解析发送者显示名称 | `true` |
---
@ -427,11 +429,11 @@ Feishu/Lark 支持用于私信和群组话题消息的 ACP。Feishu/Lark ACP 由
- ✅ 音频
- ✅ 视频/媒体
- ✅ 交互式卡片（包括流式更新）
- ⚠️ 富文本（post 风格格式；不支持完整的 Feishu/Lark 创作能力）
- ⚠️ 富文本（post 样式格式；不支持完整的 Feishu/Lark 编辑能力）
### 话题和回复
- ✅ 行内回复
- ✅ 内联回复
- ✅ 话题回复
- ✅ 回复话题消息时，媒体回复会保持话题感知
@ -440,7 +442,7 @@ Feishu/Lark 支持用于私信和群组话题消息的 ACP。Feishu/Lark ACP 由
## 相关内容
- [渠道概览](/zh-CN/channels) — 所有受支持的渠道
- [配对](/zh-CN/channels/pairing) — 私信身份验证和配对流程
- [群组](/zh-CN/channels/groups) — 群聊行为和提及门控
- [配对](/zh-CN/channels/pairing) — 私信身份验证与配对流程
- [群组](/zh-CN/channels/groups) — 群聊行为与提及门控
- [渠道路由](/zh-CN/channels/channel-routing) — 消息的会话路由
- [安全](/zh-CN/gateway/security) — 访问模型和加固措施
- [安全](/zh-CN/gateway/security) — 访问模型与加固措施

84
docs/zh-CN/channels/irc.md
View File

@ -1,27 +1,27 @@
---
read_when:
- 你想将 OpenClaw 连接到 IRC 频道或私信
- 你正在配置 IRC 允许列表、群组策略或提及门控
- 你正在配置 IRC allowlist、群组策略或提及门控
summary: IRC 插件设置、访问控制和故障排除
title: IRC
x-i18n:
generated_at: "2026-04-05T12:34:26Z"
generated_at: "2026-04-23T06:40:06Z"
model: gpt-5.4
provider: openai
source_hash: fceab2979db72116689c6c774d6736a8a2eee3559e3f3cf8969e673d317edd94
source_hash: 89c788a2be95b43420a5324ed30cada32626b72b2feb77df62aeb928fc0a386c
source_path: channels/irc.md
workflow: 15
---
# IRC
当你想让 OpenClaw 进入经典频道（`#room`）和私信时，请使用 IRC。
IRC 作为扩展插件提供，但它在主配置中的 `channels.irc` 下进行配置。
当你希望 OpenClaw 出现在传统频道（`#room`）和私信中时，请使用 IRC。
IRC 作为内置插件提供，但需在主配置中的 `channels.irc` 下进行配置。
## 快速开始
1. 在 `~/.openclaw/openclaw.json` 中启用 IRC 配置。
2. 至少设置以下内容：
2. 至少设置：
```json5
{
@ -38,9 +38,9 @@ IRC 作为扩展插件提供，但它在主配置中的 `channels.irc` 下进行
}
```
建议使用私有 IRC 服务器进行机器人协调。如果你有意使用公共 IRC 网络，常见选择包括 Libera.Chat、OFTC 和 Snoonet。避免将可预测的公共频道用于机器人或 swarm 的回传通道流量。
优先使用私有 IRC 服务器进行机器人协作。如果你有意使用公共 IRC 网络，常见选择包括 Libera.Chat、OFTC 和 Snoonet。避免将可预测的公共频道用于机器人或 swarm 的回传流量。
3. 启动或重启 Gateway 网关：
3. 启动/重启 Gateway 网关：
```bash
openclaw gateway run
@ -50,25 +50,25 @@ openclaw gateway run
- `channels.irc.dmPolicy` 默认为 `"pairing"`。
- `channels.irc.groupPolicy` 默认为 `"allowlist"`。
- 当 `groupPolicy="allowlist"` 时，设置 `channels.irc.groups` 来定义允许的频道。
- 除非你明确接受明文传输，否则请使用 TLS（`channels.irc.tls=true`）。
- 当 `groupPolicy="allowlist"` 时，设置 `channels.irc.groups` 以定义允许的频道。
- 使用 TLS（`channels.irc.tls=true`），除非你明确接受明文传输。
## 访问控制
IRC 频道有两个独立的“门控”：
IRC 频道有两个彼此独立的“门”：
1. **频道访问**（`groupPolicy` + `groups`）：机器人是否完全接受来自某个频道的消息。
2. **发送者访问**（`groupAllowFrom` / 每频道 `groups["#channel"].allowFrom`）：谁被允许在该频道内触发机器人。
2. **发送者访问**（`groupAllowFrom` / 每频道 `groups["#channel"].allowFrom`）：在该频道内，谁被允许触发机器人。
配置键：
- 私信允许列表（私信发送者访问）：`channels.irc.allowFrom`
- 群组发送者允许列表（频道发送者访问）：`channels.irc.groupAllowFrom`
- 每频道控制项（频道 + 发送者 + 提及规则）：`channels.irc.groups["#channel"]`
- 私信 allowlist（私信发送者访问）：`channels.irc.allowFrom`
- 群组发送者 allowlist（频道发送者访问）：`channels.irc.groupAllowFrom`
- 每频道控制（频道 + 发送者 + 提及规则）：`channels.irc.groups["#channel"]`
- `channels.irc.groupPolicy="open"` 允许未配置的频道（**默认仍然受提及门控限制**）
允许列表条目应使用稳定的发送者身份（`nick!user@host`）。
裸 nick 匹配是可变的，并且只有在 `channels.irc.dangerouslyAllowNameMatching: true` 时才会启用。
allowlist 条目应使用稳定的发送者身份（`nick!user@host`）。
仅昵称匹配是可变的，并且只有在 `channels.irc.dangerouslyAllowNameMatching: true` 时才会启用。
### 常见陷阱：`allowFrom` 用于私信，不用于频道
@ -76,10 +76,10 @@ IRC 频道有两个独立的“门控”：
- `irc: drop group sender alice!ident@host (policy=allowlist)`
……这表示该发送者未被允许发送 **群组/频道** 消息。可通过以下任一方式修复：
……这意味着发送者没有被允许发送**群组/频道**消息。可通过以下方式修复：
- 设置 `channels.irc.groupAllowFrom`（对所有频道全局生效），或
- 设置每频道发送者允许列表：`channels.irc.groups["#channel"].allowFrom`
- 设置每频道发送者 allowlist：`channels.irc.groups["#channel"].allowFrom`
示例（允许 `#tuirc-dev` 中的任何人与机器人对话）：
@ -96,13 +96,13 @@ IRC 频道有两个独立的“门控”：
}
```
## 回复触发方式（提及）
## 回复触发（提及）
即使某个频道已被允许（通过 `groupPolicy` + `groups`）且发送者已被允许，OpenClaw 在群组上下文中默认仍会启用 **提及门控**。
即使频道已被允许（通过 `groupPolicy` + `groups`），且发送者也已被允许，OpenClaw 在群组上下文中默认仍会启用**提及门控**。
这意味着，除非消息中包含与机器人匹配的提及模式，否则你可能会看到类似 `drop channel … (missing-mention)` 的日志。
这意味着，除非消息中包含与机器人匹配的提及模式，否则你可能会看到如 `drop channel … (missing-mention)` 这样的日志。
如果你希望机器人在 IRC 频道中 **无需提及即可回复**，请为该频道禁用提及门控：
如果你希望机器人在 IRC 频道中**无需提及也能回复**，请为该频道禁用提及门控：
```json5
{
@ -120,7 +120,7 @@ IRC 频道有两个独立的“门控”：
}
```
或者，要允许 **所有** IRC 频道（不使用每频道允许列表），并且仍然无需提及即可回复：
或者，如果要允许**所有** IRC 频道（不使用每频道 allowlist），同时仍然无需提及即可回复：
```json5
{
@ -138,9 +138,9 @@ IRC 频道有两个独立的“门控”：
## 安全说明（建议用于公共频道）
如果你在公共频道中允许 `allowFrom: ["*"]`，任何人都可以向机器人发出提示。
为降低风险，请为该频道限制工具。
为降低风险，请限制该频道可用的工具。
### 频道中所有人使用相同工具
### 频道中所有人使用相同的工具
```json5
{
@ -159,9 +159,9 @@ IRC 频道有两个独立的“门控”：
}
```
### 按发送者区分工具（所有者拥有更多权限）
### 按发送者使用不同的工具（所有者拥有更高权限）
使用 `toolsBySender` 对 `"*"` 应用更严格的策略，而对你的 nick 应用更宽松的策略：
使用 `toolsBySender`，对 `"*"` 应用更严格的策略，而对你的昵称应用更宽松的策略：
```json5
{
@ -189,14 +189,14 @@ IRC 频道有两个独立的“门控”：
- `toolsBySender` 键应对 IRC 发送者身份值使用 `id:`：
`id:eigen` 或 `id:eigen!~eigen@174.127.248.171`，后者匹配更强。
- 旧版未加前缀的键仍然被接受，但只会按 `id:` 进行匹配。
- 首个匹配到的发送者策略优先；`"*"` 是通配回退项。
- 旧版不带前缀的键仍然可接受，但只会按 `id:` 进行匹配。
- 首个匹配到的发送者策略会生效；`"*"` 是通配回退项。
有关群组访问与提及门控（以及它们如何交互）的更多信息，请参阅：[/channels/groups](/zh-CN/channels/groups)。
有关群组访问与提及门控（以及它们如何交互）的更多内容，请参阅：[/channels/groups](/zh-CN/channels/groups)。
## NickServ
要在连接后使用 NickServ 进行身份识别：
要在连接后通过 NickServ 进行身份识别：
```json5
{
@ -212,7 +212,7 @@ IRC 频道有两个独立的“门控”：
}
```
连接时可选的一次性注册：
可选：连接时执行一次性注册：
```json5
{
@ -227,7 +227,7 @@ IRC 频道有两个独立的“门控”：
}
```
在 nick 注册完成后禁用 `register`，以避免重复尝试 REGISTER。
昵称注册完成后，请禁用 `register`，以避免重复尝试 REGISTER。
## 环境变量
@ -240,20 +240,20 @@ IRC 频道有两个独立的“门控”：
- `IRC_USERNAME`
- `IRC_REALNAME`
- `IRC_PASSWORD`
- `IRC_CHANNELS`（以逗号分隔）
- `IRC_CHANNELS`（逗号分隔）
- `IRC_NICKSERV_PASSWORD`
- `IRC_NICKSERV_REGISTER_EMAIL`
## 故障排除
- 如果机器人已连接但在频道中始终不回复，请检查 `channels.irc.groups`，**以及** 提及门控是否因 `missing-mention` 而丢弃消息。如果你希望它在不被 ping 的情况下回复，请为该频道设置 `requireMention:false`。
- 如果登录失败，请检查 nick 是否可用以及服务器密码是否正确。
- 如果在自定义网络上 TLS 失败，请检查 host/port 和证书配置。
- 如果机器人已连接，但在频道中始终不回复，请检查 `channels.irc.groups`，**以及** 是否因提及门控而丢弃消息（`missing-mention`）。如果你希望它无需 ping 就能回复，请为该频道设置 `requireMention:false`。
- 如果登录失败，请检查昵称是否可用以及服务器密码是否正确。
- 如果在自定义网络上 TLS 失败，请检查主机/端口和证书设置。
## 相关内容
- [渠道概览](/zh-CN/channels) — 所有支持的渠道
- [配对](/zh-CN/channels/pairing) — 私信身份验证和配对流程
- [群组](/zh-CN/channels/groups) — 群聊行为和提及门控
- [渠道概览](/zh-CN/channels) — 所有受支持的渠道
- [Pairing](/zh-CN/channels/pairing) — 私信认证和配对流程
- [Groups](/zh-CN/channels/groups) — 群聊行为与提及门控
- [渠道路由](/zh-CN/channels/channel-routing) — 消息的会话路由
- [安全](/zh-CN/gateway/security) — 访问模型和加固措施
- [安全](/zh-CN/gateway/security) — 访问模型与加固措施

268
docs/zh-CN/channels/mattermost.md
View File

@ -5,10 +5,10 @@ read_when:
summary: Mattermost 机器人设置和 OpenClaw 配置
title: Mattermost
x-i18n:
generated_at: "2026-04-22T01:34:42Z"
generated_at: "2026-04-23T06:40:05Z"
model: gpt-5.4
provider: openai
source_hash: dd3059c5e64f417edc02c3e850ddd066e38decda0cbdcea31e1c57136e6bcb1d
source_hash: 7288378af9a3b58d51be19cdeee827350f6a4cbd80031d10ef467d482f3259e5
source_path: channels/mattermost.md
workflow: 15
---
@ -16,14 +16,15 @@ x-i18n:
# Mattermost
状态：内置插件（bot token + WebSocket 事件）。支持渠道、群组和私信。
Mattermost 是一个可自托管的团队消息平台；产品详情和下载请参见官方站点
Mattermost 是一个可自行托管的团队消息平台；产品详情和下载请参见官方网站
[mattermost.com](https://mattermost.com)。
## 内置插件
Mattermost 在当前的 OpenClaw 版本中作为内置插件提供，因此常规打包构建无需单独安装。
Mattermost 在当前的 OpenClaw 版本中作为内置插件提供，因此普通的
打包构建不需要单独安装。
如果你使用的是较旧版本，或是不包含 Mattermost 的自定义安装，
如果你使用的是较旧的构建，或排除了 Mattermost 的自定义安装，
请手动安装：
通过 CLI 安装（npm 注册表）：
@ -32,21 +33,21 @@ Mattermost 在当前的 OpenClaw 版本中作为内置插件提供，因此常
openclaw plugins install @openclaw/mattermost
```
本地 checkout（从 git 仓库运行时）：
本地检出（从 git 仓库运行时）：
```bash
openclaw plugins install ./path/to/local/mattermost-plugin
```
详情： [Plugins](/zh-CN/tools/plugin)
详情：[Plugins](/zh-CN/tools/plugin)
## 快速设置
1. 确保 Mattermost 插件可用。
- 当前打包发布的 OpenClaw 版本已内置该插件。
- 较旧版本 / 自定义安装可使用上面的命令手动添加。
2. 创建一个 Mattermost bot 账户，并复制 **bot token**。
3. 复制 Mattermost **base URL**（例如 `https://chat.example.com`）。
- 当前打包的 OpenClaw 版本已内置它。
- 较旧/自定义安装可以使用上面的命令手动添加。
2. 创建一个 Mattermost 机器人账户并复制 **bot token**。
3. 复制 Mattermost 的 **base URL**（例如 `https://chat.example.com`）。
4. 配置 OpenClaw 并启动 Gateway 网关。
最小配置：
@ -77,7 +78,7 @@ Mattermost API 注册 `oc_*` 斜杠命令，并在 Gateway 网关 HTTP 服务器
native: true,
nativeSkills: true,
callbackPath: "/api/channels/mattermost/command",
// 当 Mattermost 无法直接访问 Gateway 网关时使用（反向代理 / 公网 URL）。
// 当 Mattermost 无法直接访问 Gateway 网关时使用（反向代理/公共 URL）。
callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
},
},
@ -88,38 +89,39 @@ Mattermost API 注册 `oc_*` 斜杠命令，并在 Gateway 网关 HTTP 服务器
说明：
- `native: "auto"` 对 Mattermost 默认为禁用。设置 `native: true` 以启用。
- 如果省略 `callbackUrl`，OpenClaw 会根据 Gateway 网关 host / port 和 `callbackPath` 自动推导。
- 对于多账户配置，`commands` 可以设置在顶层，也可以设置在
`channels.mattermost.accounts.<id>.commands` 下（账户级值会覆盖顶层字段）。
- 命令回调会使用 Mattermost 在 OpenClaw 注册 `oc_*` 命令时返回的每命令 token 进行校验。
- 当注册失败、启动不完整，或回调 token 与任一已注册命令都不匹配时，
斜杠命令回调会以失败关闭方式拒绝处理。
- 如果省略 `callbackUrl`，OpenClaw 会根据 Gateway 网关 host/port 和 `callbackPath` 自动推导。
- 对于多账户设置，`commands` 可以设置在顶层，或设置在
`channels.mattermost.accounts.<id>.commands` 下（账户值会覆盖顶层字段）。
- 命令回调会使用 Mattermost 在 OpenClaw 注册 `oc_*` 命令时
返回的每个命令 token 进行校验。
- 当注册失败、启动不完整，或回调 token 与任何已注册命令都不匹配时，
斜杠命令回调会以默认拒绝的方式失败。
- 可达性要求：回调端点必须可从 Mattermost 服务器访问。
- 除非 Mattermost 与 OpenClaw 运行在同一主机 / 网络命名空间中，否则不要将 `callbackUrl` 设置为 `localhost`。
- 除非 Mattermost 与 OpenClaw 运行在同一主机/网络命名空间中，否则不要将 `callbackUrl` 设置为 `localhost`。
- 除非该 URL 会将 `/api/channels/mattermost/command` 反向代理到 OpenClaw，否则不要将 `callbackUrl` 设置为你的 Mattermost base URL。
- 一个快速检查方法是运行 `curl https://<gateway-host>/api/channels/mattermost/command`；GET 请求应返回来自 OpenClaw 的 `405 Method Not Allowed`，而不是 `404`。
- Mattermost 出站允许列表要求：
- 如果你的回调目标是私有地址 / tailnet / 内网地址，请设置 Mattermost
`ServiceSettings.AllowedUntrustedInternalConnections` 以包含回调 host / domain。
- 使用 host / domain 条目，而不是完整 URL。
- 如果你的回调目标是私有/tailnet/内部地址，请设置 Mattermost
`ServiceSettings.AllowedUntrustedInternalConnections` 以包含回调 host/domain。
- 使用 host/domain 条目，不要使用完整 URL。
- 正确：`gateway.tailnet-name.ts.net`
- 错误：`https://gateway.tailnet-name.ts.net`
## 环境变量（默认账户）
如果你更倾向于使用环境变量，请在 Gateway 网关主机上设置以下内容：
如果你更喜欢使用环境变量，请在 Gateway 网关主机上设置这些变量：
- `MATTERMOST_BOT_TOKEN=...`
- `MATTERMOST_URL=https://chat.example.com`
环境变量仅适用于 **默认** 账户（`default`）。其他账户必须使用配置值。
环境变量仅适用于**默认**账户（`default`）。其他账户必须使用配置值。
## 聊天模式
Mattermost 会自动响应私信。渠道行为由 `chatmode` 控制：
- `oncall`（默认）：仅在渠道中被 @提及时响应。
- `onmessage`：响应每条渠道消息。
- `onmessage`：响应每一条渠道消息。
- `onchar`：当消息以触发前缀开头时响应。
配置示例：
@ -138,17 +140,17 @@ Mattermost 会自动响应私信。渠道行为由 `chatmode` 控制：
说明：
- `onchar` 仍会响应显式的 @提及。
- `channels.mattermost.requireMention` 仍会兼容旧版配置，但更推荐使用 `chatmode`。
- `channels.mattermost.requireMention` 会兼容旧版配置，但更推荐使用 `chatmode`。
## 线程与会话
## 线程和会话
使用 `channels.mattermost.replyToMode` 来控制渠道和群组回复是保留在主渠道中，
还是在触发消息下启动一个线程。
使用 `channels.mattermost.replyToMode` 控制渠道和群组回复是保留在
主渠道中，还是在触发消息下开启线程。
- `off`（默认）：仅当传入消息本身已经在线程中时，才在线程中回复。
- `first`：对于渠道 / 群组中的顶层消息，在该消息下启动线程，并将对话路由到一个线程作用域的会话。
- `all`：在当前 Mattermost 中，其行为与 `first` 相同。
- 私信会忽略该设置，并保持非线程模式。
- `off`（默认）：仅当传入帖子本身已经在线程中时，才在线程中回复。
- `first`：对于顶层渠道/群组帖子，在该帖子下开启线程，并将对话路由到线程范围的会话。
- `all`：对 Mattermost 当前的行为与 `first` 相同。
- 私信会忽略此设置，并保持非线程模式。
配置示例：
@ -164,27 +166,27 @@ Mattermost 会自动响应私信。渠道行为由 `chatmode` 控制：
说明：
- 线程作用域会话使用触发消息的 post id 作为线程根节点。
- `first` 和 `all` 当前等价，因为一旦 Mattermost 已经有线程根节点，
后续分块和媒体内容都会继续发送到同一线程中。
- 线程范围的会话使用触发帖子的 id 作为线程根。
- `first` 和 `all` 当前等价，因为一旦 Mattermost 有了线程根，
后续分块和媒体内容都会继续发布到同一线程中。
## 访问控制（私信）
- 默认：`channels.mattermost.dmPolicy = "pairing"`（未知发送者会收到一个配对码）。
- 通过以下命令批准：
- 通过以下方式批准：
- `openclaw pairing list mattermost`
- `openclaw pairing approve mattermost <CODE>`
- 公开私信：`channels.mattermost.dmPolicy="open"` 加 `channels.mattermost.allowFrom=["*"]`。
- 公开私信：`channels.mattermost.dmPolicy="open"` 加上 `channels.mattermost.allowFrom=["*"]`。
## 渠道（群组）
## Channels（群组）
- 默认：`channels.mattermost.groupPolicy = "allowlist"`（受提及门控）。
- 默认：`channels.mattermost.groupPolicy = "allowlist"`（提及门控）。
- 使用 `channels.mattermost.groupAllowFrom` 将发送者加入允许列表（推荐使用用户 ID）。
- 每渠道提及覆盖项位于 `channels.mattermost.groups.<channelId>.requireMention`
- 每个渠道的提及覆盖配置位于 `channels.mattermost.groups.<channelId>.requireMention`
或 `channels.mattermost.groups["*"].requireMention`（作为默认值）。
- `@username` 匹配是可变的，且仅在 `channels.mattermost.dangerouslyAllowNameMatching: true` 时启用。
- 开放渠道：`channels.mattermost.groupPolicy="open"`（受提及门控）。
- 运行时说明：如果完全缺少 `channels.mattermost`，运行时在进行群组检查时会回退为 `groupPolicy="allowlist"`（即使已设置 `channels.defaults.groupPolicy` 也是如此）。
- 开放渠道：`channels.mattermost.groupPolicy="open"`（提及门控）。
- 运行时说明：如果 `channels.mattermost` 完全缺失，运行时在群组检查中会回退到 `groupPolicy="allowlist"`（即使设置了 `channels.defaults.groupPolicy` 也是如此）。
示例：
@ -202,31 +204,30 @@ Mattermost 会自动响应私信。渠道行为由 `chatmode` 控制：
}
```
## 出站投递的 target 格式
## 出站投递目标
在 `openclaw message send` 或 cron / webhook 中使用以下 target 格式：
将以下目标格式与 `openclaw message send` 或 cron/webhooks 搭配使用：
- `channel:<id>` 表示渠道
- `user:<id>` 表示私信
- `@username` 表示私信（通过 Mattermost API 解析）
裸的不透明 ID（如 `64ifufp...`）在 Mattermost 中是 **有歧义的**
（可能是用户 ID，也可能是渠道 ID）。
裸的不透明 ID（如 `64ifufp...`）在 Mattermost 中是**有歧义的**（用户 ID 或渠道 ID）。
OpenClaw 会按 **用户优先** 进行解析：
OpenClaw 会按**用户优先**进行解析：
- 如果该 ID 作为用户存在（`GET /api/v4/users/<id>` 成功），OpenClaw 会通过 `/api/v4/channels/direct` 解析直连渠道并发送 **私信**。
- 否则，该 ID 会被视为 **渠道 ID**。
- 如果该 ID 作为用户存在（`GET /api/v4/users/<id>` 成功），OpenClaw 会通过 `/api/v4/channels/direct` 解析直连渠道后发送**私信**。
- 否则该 ID 会被视为**渠道 ID**。
如果你需要确定性的行为，请始终使用显式前缀（`user:<id>` / `channel:<id>`）。
如果你需要确定性行为，请始终使用显式前缀（`user:<id>` / `channel:<id>`）。
## 私信渠道重试
当 OpenClaw 向 Mattermost 私信 target 发送消息且需要先解析直连渠道时，
默认会对瞬时性的直连渠道创建失败进行重试。
当 OpenClaw 向 Mattermost 私信目标发送消息，且需要先解析直连渠道时，
默认会重试瞬时性的直连渠道创建失败。
使用 `channels.mattermost.dmChannelRetry` 可全局调整 Mattermost 插件的此行为，
或使用 `channels.mattermost.accounts.<id>.dmChannelRetry` 为某个账户单独设置。
使用 `channels.mattermost.dmChannelRetry` 为 Mattermost 插件全局调整该行为，
或使用 `channels.mattermost.accounts.<id>.dmChannelRetry` 为单个账户调整。
```json5
{
@ -245,13 +246,13 @@ OpenClaw 会按 **用户优先** 进行解析：
说明：
- 这仅适用于私信渠道创建（`/api/v4/channels/direct`），而不是每一次 Mattermost API 调用。
- 重试适用于限流、5xx 响应，以及网络或超时错误等瞬时性失败。
- 除 `429` 之外的 4xx 客户端错误会被视为永久性错误，不会重试。
- 这仅适用于私信渠道创建（`/api/v4/channels/direct`），而不是每一个 Mattermost API 调用。
- 重试适用于限流、5xx 响应以及网络或超时错误等瞬时故障。
- 除 `429` 外的 4xx 客户端错误会被视为永久性错误，不会重试。
## 预览流式传输
Mattermost 会将思考内容、工具活动和部分回复文本流式写入同一个**草稿预览消息**，当最终答案可以安全发送时，会原地完成定稿。预览会在同一个 post id 上更新，而不会用逐块消息刷屏。媒体 / 错误类最终结果会取消待处理的预览编辑，并改用常规投递，而不是刷新一个临时的预览消息。
Mattermost 会将思考过程、工具活动和部分回复文本流式写入同一个**草稿预览帖子**，并在最终答案可安全发送时就地完成。预览会在同一个帖子 id 上更新，而不会用逐块消息刷屏。媒体/错误类最终结果会取消待处理的预览编辑，并改用常规投递，而不是刷新一个一次性的预览帖子。
通过 `channels.mattermost.streaming` 启用：
@ -267,20 +268,20 @@ Mattermost 会将思考内容、工具活动和部分回复文本流式写入同
说明：
- `partial` 是通常的选择：使用一条预览消息，随着回复增长不断编辑，最后以完整答案定稿。
- `block` 会在预览消息内使用追加式草稿分块。
- `progress` 会在生成期间显示状态预览，并仅在完成时发布最终答案。
- `partial` 是常见选择：使用一个预览帖子，随着回复增长不断编辑，最后以完整答案完成。
- `block` 会在预览帖子中使用追加式草稿分块。
- `progress` 会在生成时显示状态预览，并仅在完成时发布最终答案。
- `off` 会禁用预览流式传输。
- 如果流无法原地定稿（例如消息在流过程中被删除），OpenClaw 会回退为发送一条新的最终消息，以确保回复不会丢失。
- 参见 [Streaming](/zh-CN/concepts/streaming#preview-streaming-modes) 了解渠道映射矩阵。
- 如果流无法就地完成（例如帖子在流式过程中被删除），OpenClaw 会回退为发送一个新的最终帖子，以确保回复绝不会丢失。
- 参见 [Streaming](/zh-CN/concepts/streaming#preview-streaming-modes) 查看渠道映射矩阵。
## Reactions（消息工具）
- 使用 `message action=react`，并设置 `channel=mattermost`。
- `messageId` 是 Mattermost 的 post id。
- `emoji` 接受如 `thumbsup` 或 `:+1:` 这样的名称（冒号可选）。
- 设置 `remove=true`（布尔值）可移除一个 reaction。
- Reaction 添加 / 移除事件会作为系统事件转发到已路由的智能体会话。
- `messageId` 是 Mattermost 帖子 id。
- `emoji` 接受 `thumbsup` 或 `:+1:` 这类名称（冒号可选）。
- 设置 `remove=true`（布尔值）以移除 reaction。
- reaction 添加/移除事件会作为系统事件转发到已路由的智能体会话。
示例：
@ -291,7 +292,7 @@ message action=react channel=mattermost target=channel:<channelId> messageId=<po
配置：
- `channels.mattermost.actions.reactions`：启用 / 禁用 reaction 操作（默认 true）。
- `channels.mattermost.actions.reactions`：启用/禁用 reaction 操作（默认 true）。
- 每账户覆盖：`channels.mattermost.accounts.<id>.actions.reactions`。
## 交互式按钮（消息工具）
@ -311,7 +312,7 @@ message action=react channel=mattermost target=channel:<channelId> messageId=<po
}
```
使用 `message action=send` 并提供 `buttons` 参数。按钮为二维数组（按钮行）：
使用 `message action=send` 并传入 `buttons` 参数。按钮是一个二维数组（按钮行）：
```
message action=send channel=mattermost target=channel:<channelId> buttons=[[{"text":"Yes","callback_data":"yes"},{"text":"No","callback_data":"no"}]]
@ -320,40 +321,42 @@ message action=send channel=mattermost target=channel:<channelId> buttons=[[{"te
按钮字段：
- `text`（必填）：显示标签。
- `callback_data`（必填）：点击后回传的值（作为 action ID 使用）。
- `callback_data`（必填）：点击后回传的值（用作 action ID）。
- `style`（可选）：`"default"`、`"primary"` 或 `"danger"`。
当用户点击按钮时：
1. 所有按钮都会被替换为一行确认文本（例如，“✓ **Yes** selected by @user”）。
2. 智能体会将该选择作为一条传入消息接收，并作出响应。
1. 所有按钮都会被替换为一行确认文本（例如：“✓ **Yes** selected by @user”）。
2. 智能体会将该选择作为一条入站消息接收，并作出响应。
说明：
- 按钮回调使用 HMAC-SHA256 校验（自动完成，无需配置）。
- Mattermost 会从其 API 响应中剥离回调数据（安全特性），因此点击后所有按钮
都会被移除——无法实现部分移除。
- Mattermost 会从其 API 响应中去除 callback data（安全特性），因此点击后所有按钮
都会被移除——无法只移除部分按钮。
- 包含连字符或下划线的 action ID 会被自动清理
（Mattermost 路由限制）。
配置：
- `channels.mattermost.capabilities`：能力字符串数组。添加 `"inlineButtons"` 以在智能体系统提示中启用按钮工具说明。
- `channels.mattermost.interactions.callbackBaseUrl`：按钮回调的可选外部基础 URL
（例如 `https://gateway.example.com`）。当 Mattermost 无法直接通过 Gateway 网关绑定的 host 访问时，请使用此项。
- 在多账户配置中，你也可以在
- `channels.mattermost.capabilities`：能力字符串数组。添加 `"inlineButtons"` 以
在智能体系统提示中启用按钮工具说明。
- `channels.mattermost.interactions.callbackBaseUrl`：可选的外部基础 URL，用于按钮
回调（例如 `https://gateway.example.com`）。当 Mattermost 无法
直接通过 Gateway 网关的绑定主机访问它时，请使用此项。
- 在多账户设置中，你也可以在
`channels.mattermost.accounts.<id>.interactions.callbackBaseUrl` 下设置相同字段。
- 如果省略 `interactions.callbackBaseUrl`，OpenClaw 会根据
`gateway.customBindHost` + `gateway.port` 推导回调 URL，然后回退到 `http://localhost:<port>`。
- 可达性规则：按钮回调 URL 必须可从 Mattermost 服务器访问。
`localhost` 仅在 Mattermost 和 OpenClaw 运行在同一主机 / 网络命名空间时有效。
- 如果你的回调目标是私有地址 / tailnet / 内网地址，请将其 host / domain 添加到 Mattermost 的
`ServiceSettings.AllowedUntrustedInternalConnections`。
`localhost` 仅在 Mattermost 和 OpenClaw 运行于同一主机/网络命名空间时可用。
- 如果你的回调目标是私有/tailnet/内部地址，请将其 host/domain 添加到 Mattermost
`ServiceSettings.AllowedUntrustedInternalConnections` 中。
### 直接 API 集成（外部脚本）
外部脚本和 webhook 可以直接通过 Mattermost REST API 发送按钮，
而不必经过智能体的 `message` 工具。尽可能使用扩展中的 `buildButtonAttachments()`；如果发送原始 JSON，请遵循以下规则：
外部脚本和 webhook 可以直接通过 Mattermost REST API 发布按钮，
而不必通过智能体的 `message` 工具。尽可能使用插件中的 `buildButtonAttachments()`；如果发布原始 JSON，请遵循以下规则：
**负载结构：**
@ -366,17 +369,17 @@ message action=send channel=mattermost target=channel:<channelId> buttons=[[{"te
{
actions: [
{
id: "mybutton01", // alphanumeric only — see below
type: "button", // required, or clicks are silently ignored
name: "Approve", // display label
style: "primary", // optional: "default", "primary", "danger"
id: "mybutton01", // 仅限字母数字字符 —— 见下文
type: "button", // 必填，否则点击会被静默忽略
name: "Approve", // 显示标签
style: "primary", // 可选："default"、"primary"、"danger"
integration: {
url: "https://gateway.example.com/mattermost/interactions/default",
context: {
action_id: "mybutton01", // must match button id (for name lookup)
action_id: "mybutton01", // 必须与按钮 id 匹配（用于名称查找）
action: "approve",
// ... any custom fields ...
_token: "<hmac>", // see HMAC section below
// ... 任何自定义字段 ...
_token: "<hmac>", // 参见下方 HMAC 章节
},
},
},
@ -389,27 +392,27 @@ message action=send channel=mattermost target=channel:<channelId> buttons=[[{"te
**关键规则：**
1. Attachments 应放在 `props.attachments` 中，而不是顶层 `attachments`（否则会被静默忽略）。
2. 每个 action 都需要 `type: "button"` —— 缺少它时，点击会被静默吞掉。
3. 每个 action 都需要一个 `id` 字段 —— 没有 ID 的 action 会被 Mattermost 忽略。
4. Action `id` 必须是**仅字母数字**（`[a-zA-Z0-9]`）。连字符和下划线会破坏
Mattermost 服务端的 action 路由（返回 404）。使用前请将它们移除。
5. `context.action_id` 必须与按钮的 `id` 一致，这样确认消息才会显示按钮名称
（例如 “Approve”），而不是原始 ID。
1. Attachments 必须放在 `props.attachments` 中，而不是顶层 `attachments`（否则会被静默忽略）。
2. 每个 action 都需要 `type: "button"` —— 没有它，点击会被静默吞掉。
3. 每个 action 都需要 `id` 字段 —— Mattermost 会忽略没有 ID 的 action。
4. Action `id` 必须**只包含字母数字字符**（`[a-zA-Z0-9]`）。连字符和下划线会破坏
Mattermost 服务端的 action 路由（返回 404）。使用前请去掉它们。
5. `context.action_id` 必须与按钮的 `id` 匹配，这样确认消息才会显示
按钮名称（例如 “Approve”），而不是原始 ID。
6. `context.action_id` 是必填项 —— 没有它，交互处理器会返回 400。
**HMAC token 生成：**
Gateway 网关使用 HMAC-SHA256 校验按钮点击。外部脚本必须生成
与 Gateway 网关校验逻辑一致的 token：
Gateway 网关使用 HMAC-SHA256 校验按钮点击。外部脚本必须生成与
Gateway 网关校验逻辑匹配的 token：
1. 从 bot token 派生 secret：
`HMAC-SHA256(key="openclaw-mattermost-interactions", data=botToken)`
2. 构建 context 对象，包含除 `_token` 之外的所有字段。
3. 使用**排序后的键**和**无空格**进行序列化（Gateway 网关使用
带排序键的 `JSON.stringify`，会产生紧凑输出）。
2. 构建包含所有字段但**不含** `_token` 的 context 对象。
3. 使用**排序后的键**和**无空格**进行序列化（Gateway 网关使用带排序键的 `JSON.stringify`
，会生成紧凑输出）。
4. 签名：`HMAC-SHA256(key=secret, data=serializedContext)`
5. 将得到的十六进制摘要作为 `_token` 加入 context。
5. 将生成的十六进制摘要作为 `_token` 添加到 context 中。
Python 示例：
@ -432,20 +435,20 @@ context = {**ctx, "_token": token}
- Python 的 `json.dumps` 默认会添加空格（`{"key": "val"}`）。请使用
`separators=(",", ":")` 以匹配 JavaScript 的紧凑输出（`{"key":"val"}`）。
- 始终对**所有** context 字段（不含 `_token`）进行签名。Gateway 网关会先移除 `_token`，
然后对剩余所有内容签名。只签名子集会导致静默校验失败。
- 使用 `sort_keys=True` —— Gateway 网关在签名前会对键排序，而 Mattermost 在存储负载时
- 始终对**所有** context 字段（除 `_token` 外）进行签名。Gateway 网关会去掉 `_token`，然后
对剩余的全部内容签名。只签名子集会导致静默校验失败。
- 使用 `sort_keys=True` —— Gateway 网关会在签名前对键进行排序，而 Mattermost 在存储负载时
可能会重排 context 字段。
- 从 bot token 派生 secret（确定性），而不是使用随机字节。创建按钮的进程与负责校验的 Gateway 网关
必须使用相同的 secret。
- 使用 bot token 派生 secret（确定性），而不是随机字节。这个 secret
必须在创建按钮的进程与执行校验的 Gateway 网关之间保持一致。
## 目录适配器
Mattermost 插件包含一个目录适配器，可通过 Mattermost API 解析渠道名和用户名。
这样就能在 `openclaw message send` 和 cron / webhook 投递中使用
`#channel-name` 和 `@username` 作为 target。
Mattermost 插件包含一个目录适配器，可通过 Mattermost API 解析渠道和用户名。
这使得在
`openclaw message send` 和 cron/webhook 投递中可以使用 `#channel-name` 和 `@username` 目标。
无需配置 —— 该适配器会使用账户配置中的 bot token。
无需配置——该适配器会使用账户配置中的 bot token。
## 多账户
@ -466,33 +469,34 @@ Mattermost 支持在 `channels.mattermost.accounts` 下配置多个账户：
## 故障排除
- 渠道中没有回复：确认 bot 已加入该渠道，并提及它（oncall），使用触发前缀（onchar），或设置 `chatmode: "onmessage"`。
- 认证错误：检查 bot token、base URL，以及账户是否已启用。
- 渠道中没有回复：确认机器人已加入该渠道，并 @提及它（oncall）、使用触发前缀（onchar），或设置 `chatmode: "onmessage"`。
- 认证错误：检查 bot token、base URL，以及该账户是否已启用。
- 多账户问题：环境变量仅适用于 `default` 账户。
- 原生斜杠命令返回 `Unauthorized: invalid command token.`：OpenClaw
未接受该回调 token。常见原因包括：
- 斜杠命令注册在启动时失败，或仅部分完成
- 回调打到了错误的 Gateway 网关 / 账户
没有接受该回调 token。常见原因：
- 启动时斜杠命令注册失败，或只完成了部分注册
- 回调命中了错误的 Gateway 网关/账户
- Mattermost 仍保留指向旧回调目标的旧命令
- Gateway 网关重启后未重新激活斜杠命令
- Gateway 网关重启后没有重新激活斜杠命令
- 如果原生斜杠命令停止工作，请检查日志中是否有
`mattermost: failed to register slash commands` 或
`mattermost: native slash commands enabled but no commands could be registered`。
- 如果省略了 `callbackUrl`，且日志警告回调被解析为
`http://127.0.0.1:18789/...`，那么该 URL 很可能仅在
Mattermost 与 OpenClaw 运行于同一主机 / 网络命名空间时可达。请改为显式设置一个外部可达的 `commands.callbackUrl`。
- 按钮显示为空白框：智能体可能发送了格式错误的按钮数据。检查每个按钮是否同时包含 `text` 和 `callback_data` 字段。
- 如果省略了 `callbackUrl`，且日志警告回调解析为
`http://127.0.0.1:18789/...`，该 URL 很可能只有在
Mattermost 与 OpenClaw 运行于同一主机/网络命名空间时才可访问。请改为设置一个
明确的、外部可访问的 `commands.callbackUrl`。
- 按钮显示为白色方框：智能体可能发送了格式错误的按钮数据。检查每个按钮是否同时具有 `text` 和 `callback_data` 字段。
- 按钮能渲染但点击无效：确认 Mattermost 服务器配置中的 `AllowedUntrustedInternalConnections` 包含 `127.0.0.1 localhost`，并且 `ServiceSettings` 中的 `EnablePostActionIntegration` 为 `true`。
- 按钮点击返回 404：按钮的 `id` 很可能包含连字符或下划线。Mattermost 的 action 路由器无法处理非字母数字 ID。仅使用 `[a-zA-Z0-9]`。
- Gateway 网关日志显示 `invalid _token`：HMAC 不匹配。请检查你是否对所有 context 字段签名（而不是子集）、使用了排序键，并使用紧凑 JSON（无空格）。参见上方 HMAC 部分。
- Gateway 网关日志显示 `missing _token in context`：按钮的 context 中缺少 `_token` 字段。构建集成负载时请确保包含它。
- 确认信息显示的是原始 ID 而不是按钮名称：`context.action_id` 与按钮的 `id` 不一致。请将二者设置为相同的清洗后值。
- 按钮点击返回 404：按钮的 `id` 很可能包含连字符或下划线。Mattermost 的 action 路由器在非字母数字 ID 上会失效。仅使用 `[a-zA-Z0-9]`。
- Gateway 网关日志出现 `invalid _token`：HMAC 不匹配。请检查你是否对所有 context 字段进行了签名（而不是子集）、是否使用了排序后的键，以及是否使用了紧凑 JSON（无空格）。参见上面的 HMAC 章节。
- Gateway 网关日志出现 `missing _token in context`：按钮的 context 中没有 `_token` 字段。请确保在构建集成负载时包含它。
- 确认消息显示原始 ID 而不是按钮名称：`context.action_id` 与按钮的 `id` 不匹配。请将两者设置为同一个已清理的值。
- 智能体不知道按钮功能：在 Mattermost 渠道配置中添加 `capabilities: ["inlineButtons"]`。
## 相关内容
- [Channels Overview](/zh-CN/channels) — 所有支持的渠道
- [Pairing](/zh-CN/channels/pairing) — 私信认证与配对流程
- [Groups](/zh-CN/channels/groups) — 群组聊天行为与提及门控
- [Channel Routing](/zh-CN/channels/channel-routing) — 消息的会话路由
- [Security](/zh-CN/gateway/security) — 访问模型与加固
- [Channels Overview](/zh-CN/channels) —— 所有支持的渠道
- [Pairing](/zh-CN/channels/pairing) —— 私信认证和配对流程
- [Groups](/zh-CN/channels/groups) —— 群聊行为和提及门控
- [Channel Routing](/zh-CN/channels/channel-routing) —— 消息的会话路由
- [Security](/zh-CN/gateway/security) —— 访问模型与加固

410
docs/zh-CN/channels/msteams.md
View File

@ -4,23 +4,23 @@ read_when:
summary: Microsoft Teams 机器人支持状态、功能和配置
title: Microsoft Teams
x-i18n:
generated_at: "2026-04-21T21:27:19Z"
generated_at: "2026-04-23T06:40:10Z"
model: gpt-5.4
provider: openai
source_hash: ee9d52fb2cc7801e84249a705e0fa2052d4afbb7ef58cee2d3362b3e7012348c
source_hash: c1f093cbb9aed7d7f7348ec796b00f05ef66c601b5345214a08986940020d28e
source_path: channels/msteams.md
workflow: 15
---
# Microsoft Teams
> “进入此地者，放弃一切希望。”
> “进入此处者，放弃一切希望。”
状态：支持文本和私信附件；渠道/群组文件发送需要 `sharePointSiteId` + Graph 权限（参见[在群聊中发送文件](#sending-files-in-group-chats)）。投票通过 Adaptive Cards 发送。消息操作会暴露显式的 `upload-file`，用于以文件为先的发送。
状态：支持文本和私信附件；渠道/群组文件发送需要 `sharePointSiteId` + Graph 权限（见[在群组聊天中发送文件](#sending-files-in-group-chats)）。投票通过 Adaptive Cards 发送。消息操作会暴露显式的 `upload-file`，用于以文件为主的发送。
## 内置插件
Microsoft Teams 在当前的 OpenClaw 版本中作为内置插件提供，因此在常规打包构建中不需要单独安装。
Microsoft Teams 在当前的 OpenClaw 版本中作为内置插件提供，因此在常规打包构建中无需单独安装。
如果你使用的是较旧的构建版本，或是不包含内置 Teams 的自定义安装，请手动安装：
@ -28,22 +28,22 @@ Microsoft Teams 在当前的 OpenClaw 版本中作为内置插件提供，因此
openclaw plugins install @openclaw/msteams
```
本地检出版本（从 git 仓库运行时）：
本地检出（从 git 仓库运行时）：
```bash
openclaw plugins install ./path/to/local/msteams-plugin
```
详情：[Plugins](/zh-CN/tools/plugin)
详情参见：[Plugins](/zh-CN/tools/plugin)
## 快速设置（初学者）
## 快速设置（新手）
1. 确保 Microsoft Teams 插件可用。
- 当前打包发布的 OpenClaw 版本已默认内置该插件。
- 较旧/自定义安装可通过上面的命令手动添加。
2. 创建一个 **Azure Bot**（App ID + 客户端密钥 + tenant ID）。
- 当前打包发布的 OpenClaw 版本已内置该插件。
- 较旧/自定义安装可使用上面的命令手动添加。
2. 创建一个 **Azure Bot**（App ID + 客户端密钥 + 租户 ID）。
3. 使用这些凭证配置 OpenClaw。
4. 通过公共 URL 或隧道暴露 `/api/messages`（默认端口为 3978）。
4. 通过公开 URL 或隧道暴露 `/api/messages`（默认端口为 3978）。
5. 安装 Teams 应用包并启动 Gateway 网关。
最小配置（客户端密钥）：
@ -62,15 +62,15 @@ openclaw plugins install ./path/to/local/msteams-plugin
}
```
对于生产部署，建议考虑使用[联合身份验证](#federated-authentication-certificate--managed-identity)（证书或托管身份），而不是客户端密钥。
对于生产部署，建议考虑使用[联邦身份验证](#federated-authentication-certificate--managed-identity)（证书或托管身份）来替代客户端密钥。
注意：默认会阻止群聊（`channels.msteams.groupPolicy: "allowlist"`）。如需允许群组回复，请设置 `channels.msteams.groupAllowFrom`（或使用 `groupPolicy: "open"` 以允许任何成员，默认仍需提及门控）。
注意：默认会阻止群组聊天（`channels.msteams.groupPolicy: "allowlist"`）。若要允许群组回复，请设置 `channels.msteams.groupAllowFrom`（或使用 `groupPolicy: "open"` 以允许任意成员，但默认仍需提及）。
## 目标
- 通过 Teams 私信、群聊或渠道与 OpenClaw 交流。
- 保持路由确定性：回复始终返回消息到达时所在的渠道。
- 默认采用安全的渠道行为（除非另有配置，否则必须提及）。
- 通过 Teams 私信、群组聊天或渠道与 OpenClaw 交互。
- 保持路由确定性：回复始终返回到消息来源的渠道。
- 默认采用安全的渠道行为（除非已配置，否则必须提及）。
## 配置写入
@ -88,16 +88,16 @@ openclaw plugins install ./path/to/local/msteams-plugin
**私信访问**
- 默认：`channels.msteams.dmPolicy = "pairing"`。未知发送者在获得批准前会被忽略。
- 默认：`channels.msteams.dmPolicy = "pairing"`。未知发送者在获准前会被忽略。
- `channels.msteams.allowFrom` 应使用稳定的 AAD 对象 ID。
- UPN/显示名称是可变的；默认禁用直接匹配，只有在启用 `channels.msteams.dangerouslyAllowNameMatching: true` 时才会启用。
- UPN/显示名称是可变的；默认禁用直接匹配，只有启用 `channels.msteams.dangerouslyAllowNameMatching: true` 时才会启用。
- 当凭证允许时，向导可以通过 Microsoft Graph 将名称解析为 ID。
**群组访问**
- 默认：`channels.msteams.groupPolicy = "allowlist"`（除非你添加 `groupAllowFrom`，否则会被阻止）。未设置时，可使用 `channels.defaults.groupPolicy` 覆盖默认值。
- `channels.msteams.groupAllowFrom` 控制哪些发送者可以在群聊/渠道中触发（回退到 `channels.msteams.allowFrom`）。
- 设置 `groupPolicy: "open"` 可允许任何成员（默认仍需提及门控）。
- `channels.msteams.groupAllowFrom` 控制哪些发送者可以在群组聊天/渠道中触发（回退到 `channels.msteams.allowFrom`）。
- 设置 `groupPolicy: "open"` 以允许任意成员（默认仍需提及）。
- 若要**不允许任何渠道**，请设置 `channels.msteams.groupPolicy: "disabled"`。
示例：
@ -115,11 +115,11 @@ openclaw plugins install ./path/to/local/msteams-plugin
**Teams + 渠道允许列表**
- 通过在 `channels.msteams.teams` 下列出团队和渠道，限定群组/渠道回复范围。
- 通过在 `channels.msteams.teams` 下列出团队和渠道来限定群组/渠道回复范围。
- 键应使用稳定的团队 ID 和渠道会话 ID。
- 当 `groupPolicy="allowlist"` 且存在 teams 允许列表时，只接受列出的团队/渠道（需提及门控）。
- 配置向导接受 `Team/Channel` 条目，并会为你存储它们。
- 在启动时，OpenClaw 会将团队/渠道和用户允许列表中的名称解析为 ID（当 Graph 权限允许时），并记录映射；未解析的团队/渠道名称会按原样保留，但默认会在路由中被忽略，除非启用 `channels.msteams.dangerouslyAllowNameMatching: true`。
- 当 `groupPolicy="allowlist"` 且存在 teams 允许列表时，仅接受已列出的团队/渠道（默认需提及）。
- 配置向导接受 `Team/Channel` 条目，并会为你保存。
- 启动时，OpenClaw 会将团队/渠道和用户允许列表中的名称解析为 ID（当 Graph 权限允许时），并记录映射；无法解析的团队/渠道名称会按输入保留，但默认会在路由时忽略，除非启用 `channels.msteams.dangerouslyAllowNameMatching: true`。
示例：
@ -143,17 +143,17 @@ openclaw plugins install ./path/to/local/msteams-plugin
## 工作原理
1. 确保 Microsoft Teams 插件可用。
- 当前打包发布的 OpenClaw 版本已默认内置该插件。
- 较旧/自定义安装可通过上面的命令手动添加。
2. 创建一个 **Azure Bot**（App ID + 密钥 + tenant ID）。
3. 构建一个 **Teams 应用包**，引用该 bot 并包含下面的 RSC 权限。
4. 将 Teams 应用上传/安装到团队中（或用于私信的个人作用域）。
5. 在 `~/.openclaw/openclaw.json`（或环境变量）中配置 `msteams`，并启动 Gateway 网关。
6. Gateway 网关默认在 `/api/messages` 上监听 Bot Framework webhook 流量。
- 当前打包发布的 OpenClaw 版本已内置该插件。
- 较旧/自定义安装可使用上面的命令手动添加。
2. 创建一个 **Azure Bot**（App ID + 密钥 + 租户 ID）。
3. 构建一个 **Teams 应用包**，引用该机器人并包含下方的 RSC 权限。
4. 将 Teams 应用上传/安装到团队中（或安装到个人范围用于私信）。
5. 在 `~/.openclaw/openclaw.json`（或环境变量）中配置 `msteams`，然后启动 Gateway 网关。
6. Gateway 网关默认会在 `/api/messages` 上监听 Bot Framework webhook 流量。
## Azure Bot 设置（前置条件）
在配置 OpenClaw 之前，你需要创建一个 Azure Bot 资源。
在配置 OpenClaw 之前，你需要先创建一个 Azure Bot 资源。
### 第 1 步：创建 Azure Bot
@ -162,14 +162,14 @@ openclaw plugins install ./path/to/local/msteams-plugin
| 字段 | 值 |
| ------------------ | -------------------------------------------------------- |
| **Bot handle** | 你的 bot 名称，例如 `openclaw-msteams`（必须唯一） |
| **Bot handle** | 你的机器人名称，例如 `openclaw-msteams`（必须唯一） |
| **Subscription** | 选择你的 Azure 订阅 |
| **Resource group** | 新建或使用现有资源组 |
| **Pricing tier** | 开发/测试使用 **Free** |
| **Type of App** | **Single Tenant**（推荐——见下方说明） |
| **Type of App** | **Single Tenant**（推荐，见下方说明） |
| **Creation type** | **Create new Microsoft App ID** |
> **弃用通知：** 创建新的多租户 bot 已在 2025-07-31 后弃用。新 bot 请使用 **Single Tenant**。
> **弃用通知：** 新建多租户机器人的功能已在 2025-07-31 后弃用。新机器人请使用 **Single Tenant**。
3. 点击 **Review + create** → **Create**（等待约 1–2 分钟）
@ -177,28 +177,30 @@ openclaw plugins install ./path/to/local/msteams-plugin
1. 前往你的 Azure Bot 资源 → **Configuration**
2. 复制 **Microsoft App ID** → 这就是你的 `appId`
3. 点击 **Manage Password** → 进入 App Registration
4. 在 **Certificates & secrets** 下点击 **New client secret** → 复制 **Value** → 这就是你的 `appPassword`
3. 点击 **Manage Password** → 前往 App Registration
4. 在 **Certificates & secrets** 下 → **New client secret** → 复制 **Value** → 这就是你的 `appPassword`
5. 前往 **Overview** → 复制 **Directory (tenant) ID** → 这就是你的 `tenantId`
### 第 3 步：配置消息端点
1. 在 Azure Bot 中进入 **Configuration**
1. 在 Azure Bot 中前往 **Configuration**
2. 将 **Messaging endpoint** 设置为你的 webhook URL：
- 生产环境：`https://your-domain.com/api/messages`
- 本地开发：使用隧道（参见下方[本地开发](#local-development-tunneling)）
- 本地开发：使用隧道（见下方[本地开发](#local-development-tunneling)）
### 第 4 步：启用 Teams 渠道
1. 在 Azure Bot 中进入 **Channels**
1. 在 Azure Bot 中前往 **Channels**
2. 点击 **Microsoft Teams** → Configure → Save
3. 接受服务条款
## 联合身份验证（证书 + 托管身份）
<a id="federated-authentication-certificate--managed-identity"></a>
## 联邦身份验证（证书 + 托管身份）
> 添加于 2026.3.24
对于生产部署，OpenClaw 支持**联合身份验证**，作为比客户端密钥更安全的替代方案。提供两种方式：
对于生产部署，OpenClaw 支持将**联邦身份验证**作为比客户端密钥更安全的替代方案。提供两种方式：
### 选项 A：基于证书的身份验证
@ -206,7 +208,7 @@ openclaw plugins install ./path/to/local/msteams-plugin
**设置：**
1. 生成或获取一个证书（包含私钥的 PEM 格式）。
1. 生成或获取一个证书（带私钥的 PEM 格式）。
2. 在 Entra ID → App Registration → **Certificates & secrets** → **Certificates** 中上传公钥证书。
**配置：**
@ -231,24 +233,24 @@ openclaw plugins install ./path/to/local/msteams-plugin
- `MSTEAMS_AUTH_TYPE=federated`
- `MSTEAMS_CERTIFICATE_PATH=/path/to/cert.pem`
### 选项 B：Azure 托管身份
### 选项 B：Azure Managed Identity
使用 Azure 托管身份实现无密码身份验证。这非常适合部署在 Azure 基础设施上的场景（AKS、App Service、Azure VM），即存在可用托管身份时。
使用 Azure Managed Identity 实现免密身份验证。这非常适合部署在 Azure 基础设施上的场景（AKS、App Service、Azure VM），前提是存在可用的托管身份。
**工作原理：**
1. bot 所在的 pod/VM 拥有一个托管身份（系统分配或用户分配）。
2. 一个**联合身份凭证**将该托管身份连接到 Entra ID 应用注册。
3. 在运行时，OpenClaw 使用 `@azure/identity` 从 Azure IMDS 端点（`169.254.169.254`）获取令牌。
4. 该令牌会传递给 Teams SDK，用于 bot 身份验证。
1. 机器人 pod/VM 具有托管身份（系统分配或用户分配）。
2. 一个**联邦身份凭证**将托管身份链接到 Entra ID 应用注册。
3. 运行时，OpenClaw 使用 `@azure/identity` 从 Azure IMDS 端点（`169.254.169.254`）获取令牌。
4. 该令牌会传递给 Teams SDK 用于机器人身份验证。
**前置条件：**
- 已启用托管身份的 Azure 基础设施（AKS workload identity、App Service、VM）
- 已在 Entra ID 应用注册上创建联合身份凭证
- pod/VM 可通过网络访问 IMDS（`169.254.169.254:80`）
- 已在 Entra ID 应用注册上创建联邦身份凭证
- pod/VM 能够通过网络访问 IMDS（`169.254.169.254:80`）
**配置（系统分配托管身份）：**
**配置（系统分配的托管身份）：**
```json5
{
@ -265,7 +267,7 @@ openclaw plugins install ./path/to/local/msteams-plugin
}
```
**配置（用户分配托管身份）：**
**配置（用户分配的托管身份）：**
```json5
{
@ -287,14 +289,14 @@ openclaw plugins install ./path/to/local/msteams-plugin
- `MSTEAMS_AUTH_TYPE=federated`
- `MSTEAMS_USE_MANAGED_IDENTITY=true`
- `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID=<client-id>`（仅适用于用户分配）
- `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID=<client-id>`（仅用于用户分配）
### AKS Workload Identity 设置
对于使用 workload identity 的 AKS 部署：
1. 在你的 AKS 集群上**启用 workload identity**。
2. 在 Entra ID 应用注册上**创建联合身份凭证**：
2. 在 Entra ID 应用注册上**创建联邦身份凭证**：
```bash
az ad app federated-credential create --id <APP_OBJECT_ID> --parameters '{
@ -324,17 +326,17 @@ openclaw plugins install ./path/to/local/msteams-plugin
azure.workload.identity/use: "true"
```
5. **确保网络可访问** IMDS（`169.254.169.254`）——如果你使用 NetworkPolicy，请添加一条出口规则，允许到 `169.254.169.254/32` 的 80 端口流量。
5. **确保可通过网络访问** IMDS（`169.254.169.254`）——如果你使用 NetworkPolicy，请添加一条出口规则，允许访问 `169.254.169.254/32` 的 80 端口流量。
### 身份验证类型对比
| 方式 | 配置 | 优点 | 缺点 |
| -------------------- | ---------------------------------------------- | ---------------------------------- | ------------------------------------- |
| **客户端密钥** | `appPassword` | 设置简单 | 需要轮换密钥，安全性较低 |
| **证书** | `authType: "federated"` + `certificatePath` | 无需通过网络共享密钥 | 证书管理有额外成本 |
| **托管身份** | `authType: "federated"` + `useManagedIdentity` | 无密码，无需管理密钥 | 需要 Azure 基础设施 |
| **证书** | `authType: "federated"` + `certificatePath` | 网络中无需共享密钥 | 证书管理有额外开销 |
| **Managed Identity** | `authType: "federated"` + `useManagedIdentity` | 免密，无需管理密钥 | 需要 Azure 基础设施 |
**默认行为：** 当未设置 `authType` 时，OpenClaw 默认使用客户端密钥身份验证。现有配置无需修改即可继续使用。
**默认行为：** 当未设置 `authType` 时，OpenClaw 默认使用客户端密钥身份验证。现有配置无需修改即可继续工作。
## 本地开发（隧道）
@ -357,7 +359,7 @@ tailscale funnel 3978
## Teams Developer Portal（替代方式）
你可以不手动创建 manifest ZIP，而是使用 [Teams Developer Portal](https://dev.teams.microsoft.com/apps)：
除了手动创建 manifest ZIP 外，你也可以使用 [Teams Developer Portal](https://dev.teams.microsoft.com/apps)：
1. 点击 **+ New app**
2. 填写基本信息（名称、描述、开发者信息）
@ -367,31 +369,31 @@ tailscale funnel 3978
6. 点击 **Distribute** → **Download app package**
7. 在 Teams 中：**Apps** → **Manage your apps** → **Upload a custom app** → 选择该 ZIP
这通常比手动编辑 JSON manifest 更容易。
这通常比手动编辑 JSON manifest 更简单。
## 测试 Bot
## 测试机器人
**选项 A：Azure Web Chat（先验证 webhook）**
1. 在 Azure Portal 中进入你的 Azure Bot 资源 → **Test in Web Chat**
2. 发送一条消息——你应该能看到响应
3. 这可以在设置 Teams 之前确认你的 webhook 端点正常工作
1. 在 Azure Portal 中 → 你的 Azure Bot 资源 → **Test in Web Chat**
2. 发送一条消息 —— 你应该能看到回复
3. 这可以确认你的 webhook 端点在配置 Teams 之前已正常工作
**选项 B：Teams（安装应用后）**
1. 安装 Teams 应用（侧载或组织目录）
2. 在 Teams 中找到该 bot 并发送一条私信
3. 检查 Gateway 网关日志中的传入活动
1. 安装 Teams 应用（侧载或通过组织目录）
2. 在 Teams 中找到该机器人并发送私信
3. 检查 Gateway 网关日志中的传入 activity
## 设置（最小文本模式）
## 设置（仅最小文本支持）
1. **确保 Microsoft Teams 插件可用**
- 当前打包发布的 OpenClaw 版本已默认内置该插件。
- 当前打包发布的 OpenClaw 版本已内置该插件。
- 较旧/自定义安装可手动添加：
- 从 npm：`openclaw plugins install @openclaw/msteams`
- 从本地检出：`openclaw plugins install ./path/to/local/msteams-plugin`
2. **Bot 注册**
2. **机器人注册**
- 创建一个 Azure Bot（见上文），并记录：
- App ID
- 客户端密钥（App password）
@ -400,10 +402,10 @@ tailscale funnel 3978
3. **Teams 应用 manifest**
- 包含一个 `bot` 条目，其中 `botId = <App ID>`。
- 作用域：`personal`、`team`、`groupChat`。
- `supportsFiles: true`（个人作用域文件处理必需）。
- `supportsFiles: true`（个人作用域文件处理所必需）。
- 添加 RSC 权限（见下文）。
- 创建图标：`outline.png`（32x32）和 `color.png`（192x192）。
- 将这三个文件一起打包为 ZIP：`manifest.json`、`outline.png`、`color.png`。
- 将这三个文件一起打包成 zip：`manifest.json`、`outline.png`、`color.png`。
4. **配置 OpenClaw**
@ -421,46 +423,46 @@ tailscale funnel 3978
}
```
你也可以使用环境变量来代替配置键：
你也可以使用环境变量代替配置键：
- `MSTEAMS_APP_ID`
- `MSTEAMS_APP_PASSWORD`
- `MSTEAMS_TENANT_ID`
- `MSTEAMS_AUTH_TYPE`（可选：`"secret"` 或 `"federated"`）
- `MSTEAMS_CERTIFICATE_PATH`（联合身份验证 + 证书）
- `MSTEAMS_CERTIFICATE_PATH`（联邦身份验证 + 证书）
- `MSTEAMS_CERTIFICATE_THUMBPRINT`（可选，身份验证不要求）
- `MSTEAMS_USE_MANAGED_IDENTITY`（联合身份验证 + 托管身份）
- `MSTEAMS_USE_MANAGED_IDENTITY`（联邦身份验证 + 托管身份）
- `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID`（仅用户分配的 MI）
5. **Bot 端点**
- 将 Azure Bot Messaging Endpoint 设置为：
- `https://<host>:3978/api/messages`（或你自定义的路径/端口）。
5. **机器人端点**
- 将 Azure Bot 消息端点设置为：
- `https://<host>:3978/api/messages`（或你选择的路径/端口）。
6. **运行 Gateway 网关**
- 当内置或手动安装的插件可用，且存在带凭证的 `msteams` 配置时，Teams 渠道会自动启动。
## 成员信息操作
OpenClaw 为 Microsoft Teams 提供了由 Graph 支持的 `member-info` 操作，因此智能体和自动化流程可以直接从 Microsoft Graph 解析渠道成员详情（显示名称、电子邮件、角色）。
OpenClaw 为 Microsoft Teams 提供基于 Graph 的 `member-info` 操作，因此智能体和自动化可以直接从 Microsoft Graph 解析渠道成员详情（显示名称、邮箱、角色）。
要求：
- `Member.Read.Group` RSC 权限（已包含在推荐的 manifest 中）
- 对于跨团队查询：具有管理员同意的 `User.Read.All` Graph 应用程序权限
- `Member.Read.Group` RSC 权限（已包含在推荐 manifest 中）
- 对于跨团队查找：`User.Read.All` Graph Application 权限，并已授予管理员同意
该操作受 `channels.msteams.actions.memberInfo` 控制（默认：当 Graph 凭证可用时启用）。
## 历史上下文
- `channels.msteams.historyLimit` 控制会包装进提示中的最近渠道/群组消息数量。
- 回退到 `messages.groupChat.historyLimit`。设置为 `0` 可禁用（默认 50）。
- 获取到的线程历史会按发送者允许列表（`allowFrom` / `groupAllowFrom`）进行过滤，因此线程上下文预填充目前只包含来自允许发送者的消息。
- 引用的附件上下文（从 Teams 回复 HTML 派生的 `ReplyTo*`）目前会按接收时的原样传递。
- `channels.msteams.historyLimit` 控制会封装到提示词中的最近渠道/群组消息数量。
- 回退到 `messages.groupChat.historyLimit`。设为 `0` 可禁用（默认 50）。
- 获取到的线程历史会按发送者允许列表（`allowFrom` / `groupAllowFrom`）过滤，因此线程上下文预填充目前只包含允许的发送者消息。
- 引用的附件上下文（由 Teams 回复 HTML 派生的 `ReplyTo*`）当前会按接收原样传递。
- 换句话说，允许列表控制谁可以触发智能体；目前只有特定的补充上下文路径会被过滤。
- 私信历史可通过 `channels.msteams.dmHistoryLimit`（用户轮次）限制。每用户覆盖：`channels.msteams.dms["<user_id>"].historyLimit`。
- 私信历史可通过 `channels.msteams.dmHistoryLimit`（用户轮次）限制。按用户覆盖：`channels.msteams.dms["<user_id>"].historyLimit`。
## 当前 Teams RSC 权限（Manifest）
这些是我们的 Teams 应用 manifest 中**现有的 resourceSpecific 权限**。它们仅在安装了该应用的团队/聊天内生效。
这些是我们 Teams 应用 manifest 中**现有的 resourceSpecific 权限**。它们仅适用于安装了该应用的团队/聊天内部。
**用于渠道（团队作用域）：**
@ -472,13 +474,13 @@ OpenClaw 为 Microsoft Teams 提供了由 Graph 支持的 `member-info` 操作
- `TeamMember.Read.Group`（Application）
- `TeamSettings.Read.Group`（Application）
**用于群聊：**
**用于群组聊天：**
- `ChatMessage.Read.Chat`（Application）- 无需 @mention 即可接收所有群聊消息
- `ChatMessage.Read.Chat`（Application）- 无需 @mention 即可接收所有群组聊天消息
## Teams Manifest 示例（已脱敏）
这是一个包含必需字段的最小有效示例。请替换其中的 ID 和 URL。
包含所需字段的最小有效示例。请替换其中的 ID 和 URL。
```json5
{
@ -526,7 +528,7 @@ OpenClaw 为 Microsoft Teams 提供了由 Graph 支持的 `member-info` 操作
}
```
### Manifest 注意事项（必需字段）
### Manifest 注意事项（必填字段）
- `bots[].botId` **必须**与 Azure Bot App ID 一致。
- `webApplicationInfo.id` **必须**与 Azure Bot App ID 一致。
@ -539,13 +541,13 @@ OpenClaw 为 Microsoft Teams 提供了由 Graph 支持的 `member-info` 操作
要更新一个已安装的 Teams 应用（例如添加 RSC 权限）：
1. 使用新设置更新你的 `manifest.json`
2. **增加 `version` 字段**（例如 `1.0.0` → `1.1.0`）
3. **重新打包为 ZIP**，包含 manifest 和图标（`manifest.json`、`outline.png`、`color.png`）
2. **递增 `version` 字段**（例如 `1.0.0` → `1.1.0`）
3. **重新打包 zip**，包含 manifest 和图标（`manifest.json`、`outline.png`、`color.png`）
4. 上传新的 zip：
- **选项 A（Teams Admin Center）：** Teams Admin Center → Teams apps → Manage apps → 找到你的应用 → Upload new version
- **选项 B（侧载）：** 在 Teams 中 → Apps → Manage your apps → Upload a custom app
5. **对于团队渠道：** 在每个团队中重新安装应用，以使新权限生效
6. **完全退出并重新启动 Teams**（不只是关闭窗口），以清除缓存的应用元数据
5. **对于团队渠道：** 在每个团队中重新安装应用，新的权限才会生效
6. **完全退出并重新启动 Teams**（而不是只关闭窗口），以清除缓存的应用元数据
## 功能：仅 RSC 与 Graph
@ -559,41 +561,41 @@ OpenClaw 为 Microsoft Teams 提供了由 Graph 支持的 `member-info` 操作
不可用：
- 渠道/群组**图片或文件内容**（负载仅包含 HTML 占位内容）。
- 渠道/群组中的**图片或文件内容**（payload 仅包含 HTML 占位内容）。
- 下载存储在 SharePoint/OneDrive 中的附件。
- 读取消息历史（超出实时 webhook 事件之外）。
- 读取消息历史记录（实时 webhook 事件之外的内容）。
### 使用**Teams RSC + Microsoft Graph 应用程序权限**
### 使用**Teams RSC + Microsoft Graph Application 权限**
额外支持：
额外提供：
- 下载托管内容（粘贴到消息中的图片）。
- 下载存储在 SharePoint/OneDrive 中的文件附件。
- 通过 Graph 读取渠道/聊天消息历史。
### RSC 与 Graph API
### RSC 与 Graph API 对比
| 能力 | RSC 权限 | Graph API |
| 功能 | RSC 权限 | Graph API |
| ----------------------- | -------------------- | ----------------------------------- |
| **实时消息** | 是（通过 webhook） | 否（仅轮询） |
| **历史消息** | 否 | 是（可查询历史） |
| **设置复杂度** | 仅应用 manifest | 需要管理员同意 + 令牌流 |
| **离线可用** | 否（必须在运行） | 是（可随时查询） |
| **设置复杂度** | 仅应用 manifest | 需要管理员同意 + 令牌流程 |
| **离线可用** | 否（必须正在运行） | 是（可随时查询） |
**结论：** RSC 用于实时监听；Graph API 用于历史访问。如果你希望在离线期间补收错过的消息，你需要启用带 `ChannelMessage.Read.All` 的 Graph API（需要管理员同意）。
**结论：** RSC 用于实时监听；Graph API 用于历史访问。如果你想在离线期间补抓错过的消息，就需要使用带 `ChannelMessage.Read.All` 的 Graph API（需要管理员同意）。
## 启用 Graph 的媒体 + 历史（渠道必需）
## 启用 Graph 的媒体 + 历史记录（渠道必需）
如果你需要**渠道**中的图片/文件，或想要获取**消息历史**，则必须启用 Microsoft Graph 权限并授予管理员同意。
如果你需要在**渠道**中处理图片/文件，或想获取**消息历史**，则必须启用 Microsoft Graph 权限并授予管理员同意。
1. 在 Entra ID（Azure AD）的 **App Registration** 中，添加 Microsoft Graph **Application permissions**：
1. 在 Entra ID（Azure AD）**App Registration** 中，添加 Microsoft Graph **Application permissions**：
- `ChannelMessage.Read.All`（渠道附件 + 历史）
- `Chat.Read.All` 或 `ChatMessage.Read.All`（群聊）
2. **为租户授予管理员同意**。
3. 提升 Teams 应用 **manifest 版本**，重新上传，并在 **Teams 中重新安装该应用**。
- `Chat.Read.All` 或 `ChatMessage.Read.All`（群组聊天）
2. 为租户**授予管理员同意**。
3. 提升 Teams 应用 **manifest version**，重新上传，并在 **Teams 中重新安装应用**。
4. **完全退出并重新启动 Teams**，以清除缓存的应用元数据。
**用户提及的额外权限：** 对于当前会话中的用户，用户 @mention 可直接使用。但是，如果你希望动态搜索并提及**不在当前会话中**的用户，请添加 `User.Read.All`（Application）权限并授予管理员同意。
**用户提及所需的额外权限：** 对于对话中的用户，用户 @mentions 开箱即用。但是，如果你想动态搜索并提及**不在当前对话中**的用户，请添加 `User.Read.All`（Application）权限并授予管理员同意。
## 已知限制
@ -602,57 +604,57 @@ OpenClaw 为 Microsoft Teams 提供了由 Graph 支持的 `member-info` 操作
Teams 通过 HTTP webhook 传递消息。如果处理耗时过长（例如 LLM 响应较慢），你可能会看到：
- Gateway 网关超时
- Teams 重试消息（导致重复）
- Teams 重试该消息（导致重复）
- 回复丢失
OpenClaw 通过快速返回并主动发送回复来处理这种情况，但响应非常慢时仍可能出现问题。
OpenClaw 通过快速返回并主动发送回复来处理这个问题，但响应非常慢时仍可能出现问题。
### 格式化
Teams 的 Markdown 支持比 Slack 或 Discord 更有限：
Teams 的 markdown 能力比 Slack 或 Discord 更有限：
- 基本格式可用：**粗体**、_斜体_、`code`、链接
- 复杂 Markdown（表格、嵌套列表）可能无法正确渲染
- 支持用于投票和语义化展示发送的 Adaptive Cards（见下文）
- 基本格式可用：**加粗**、_斜体_、`code`、链接
- 复杂 markdown（表格、嵌套列表）可能无法正确渲染
- 投票和语义化展示发送支持 Adaptive Cards（见下文）
## 配置
关键设置（共享渠道模式请参见 `/gateway/configuration`）：
关键设置（共享渠道模式参见 `/gateway/configuration`）：
- `channels.msteams.enabled`：启用/禁用该渠道。
- `channels.msteams.appId`、`channels.msteams.appPassword`、`channels.msteams.tenantId`：bot 凭证。
- `channels.msteams.appId`、`channels.msteams.appPassword`、`channels.msteams.tenantId`：机器人凭证。
- `channels.msteams.webhook.port`（默认 `3978`）
- `channels.msteams.webhook.path`（默认 `/api/messages`）
- `channels.msteams.dmPolicy`：`pairing | allowlist | open | disabled`（默认：pairing）
- `channels.msteams.allowFrom`：私信允许列表（推荐使用 AAD 对象 ID）。当 Graph 访问可用时，向导会在设置期间将名称解析为 ID。
- `channels.msteams.dangerouslyAllowNameMatching`：紧急开关，用于重新启用可变的 UPN/显示名匹配，以及直接按团队/渠道名称进行路由。
- `channels.msteams.allowFrom`：私信允许列表（建议使用 AAD 对象 ID）。当 Graph 访问可用时，向导会在设置过程中将名称解析为 ID。
- `channels.msteams.dangerouslyAllowNameMatching`：紧急开关，用于重新启用可变 UPN/显示名称匹配，以及直接的团队/渠道名称路由。
- `channels.msteams.textChunkLimit`：出站文本分块大小。
- `channels.msteams.chunkMode`：`length`（默认）或 `newline`，会在按长度分块前先按空行（段落边界）拆分。
- `channels.msteams.mediaAllowHosts`：入站附件主机允许列表（默认包含 Microsoft/Teams 域名）。
- `channels.msteams.mediaAuthAllowHosts`：媒体重试时附加 Authorization 标头的主机允许列表（默认包含 Graph + Bot Framework 主机）。
- `channels.msteams.chunkMode`：`length`（默认）或 `newline`，在按长度分块前先按空行（段落边界）拆分。
- `channels.msteams.mediaAllowHosts`：传入附件主机的允许列表（默认是 Microsoft/Teams 域名）。
- `channels.msteams.mediaAuthAllowHosts`：媒体重试时允许附加 Authorization 头的主机允许列表（默认是 Graph + Bot Framework 主机）。
- `channels.msteams.requireMention`：在渠道/群组中要求 @mention（默认 true）。
- `channels.msteams.replyStyle`：`thread | top-level`（参见[回复样式](#reply-style-threads-vs-posts)）。
- `channels.msteams.replyStyle`：`thread | top-level`（见[回复样式](#reply-style-threads-vs-posts)）。
- `channels.msteams.teams.<teamId>.replyStyle`：按团队覆盖。
- `channels.msteams.teams.<teamId>.requireMention`：按团队覆盖。
- `channels.msteams.teams.<teamId>.tools`：默认的按团队工具策略覆盖（`allow`/`deny`/`alsoAllow`），当缺少渠道覆盖时使用。
- `channels.msteams.teams.<teamId>.toolsBySender`：默认的按团队、按发送者工具策略覆盖（支持 `"*"` 通配符）。
- `channels.msteams.teams.<teamId>.tools`：按团队的默认工具策略覆盖（`allow`/`deny`/`alsoAllow`），当缺少渠道级覆盖时使用。
- `channels.msteams.teams.<teamId>.toolsBySender`：按团队、按发送者的默认工具策略覆盖（支持 `"*"` 通配符）。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle`：按渠道覆盖。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention`：按渠道覆盖。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.tools`：按渠道工具策略覆盖（`allow`/`deny`/`alsoAllow`）。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender`：按渠道、按发送者工具策略覆盖（支持 `"*"` 通配符）。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.tools`：按渠道的工具策略覆盖（`allow`/`deny`/`alsoAllow`）。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender`：按渠道、按发送者的工具策略覆盖（支持 `"*"` 通配符）。
- `toolsBySender` 键应使用显式前缀：
`id:`、`e164:`、`username:`、`name:`（旧版无前缀键仍只会映射到 `id:`）。
- `channels.msteams.actions.memberInfo`：启用或禁用由 Graph 支持的成员信息操作（默认：当 Graph 凭证可用时启用）。
- `channels.msteams.authType`：身份验证类型——`"secret"`（默认）或 `"federated"`。
- `channels.msteams.certificatePath`：PEM 证书文件路径（联合身份验证 + 证书身份验证）。
- `channels.msteams.actions.memberInfo`：启用或禁用基于 Graph 的成员信息操作（默认：当 Graph 凭证可用时启用）。
- `channels.msteams.authType`：身份验证类型 —— `"secret"`（默认）或 `"federated"`。
- `channels.msteams.certificatePath`：PEM 证书文件路径（联邦身份验证 + 证书认证）。
- `channels.msteams.certificateThumbprint`：证书指纹（可选，身份验证不要求）。
- `channels.msteams.useManagedIdentity`：启用托管身份身份验证（联合模式）。
- `channels.msteams.useManagedIdentity`：启用托管身份认证（联邦模式）。
- `channels.msteams.managedIdentityClientId`：用户分配托管身份的客户端 ID。
- `channels.msteams.sharePointSiteId`：用于群聊/渠道中文件上传的 SharePoint 站点 ID（参见[在群聊中发送文件](#sending-files-in-group-chats)）。
- `channels.msteams.sharePointSiteId`：用于群组聊天/渠道文件上传的 SharePoint 站点 ID（见[在群组聊天中发送文件](#sending-files-in-group-chats)）。
## 路由与会话
- 会话键遵循标准智能体格式（参见 [/concepts/session](/zh-CN/concepts/session)）：
- 会话键遵循标准智能体格式（见 [/concepts/session](/zh-CN/concepts/session)）：
- 私信共享主会话（`agent:<agentId>:<mainKey>`）。
- 渠道/群组消息使用会话 ID：
- `agent:<agentId>:msteams:channel:<conversationId>`
@ -660,19 +662,19 @@ Teams 的 Markdown 支持比 Slack 或 Discord 更有限：
## 回复样式：线程 vs 帖子
Teams 最近在相同底层数据模型之上引入了两种渠道 UI 样式：
Teams 最近在相同的底层数据模型之上引入了两种渠道 UI 样式：
| 样式 | 描述 | 推荐的 `replyStyle` |
| ------------------------ | --------------------------------------------------------- | ------------------------ |
| **Posts**（经典） | 消息显示为卡片，下方带线程回复 | `thread`（默认） |
| **Posts**（经典） | 消息显示为卡片，下面附带线程式回复 | `thread`（默认） |
| **Threads**（类似 Slack） | 消息线性流动，更像 Slack | `top-level` |
**问题：** Teams API 不会暴露某个渠道使用的是哪种 UI 样式。如果你使用了错误的 `replyStyle`：
**问题在于：** Teams API 不会暴露某个渠道使用的是哪种 UI 样式。如果你使用了错误的 `replyStyle`：
- 在线程式渠道中使用 `thread` → 回复会以不自然的嵌套方式显示
- 在 Posts 样式渠道中使用 `top-level` → 回复会显示为独立的顶层帖子，而不是在线程内
- 在线程式渠道中使用 `thread` → 回复会以别扭的嵌套方式显示
- 在帖子式渠道中使用 `top-level` → 回复会显示为单独的顶层帖子，而不是线程内回复
**解决方案：** 根据渠道的设置，按渠道配置 `replyStyle`：
**解决方案：** 根据渠道的实际设置，为每个渠道配置 `replyStyle`：
```json5
{
@ -697,40 +699,40 @@ Teams 最近在相同底层数据模型之上引入了两种渠道 UI 样式：
**当前限制：**
- **私信：** 图片和文件附件可通过 Teams bot 文件 API 工作。
- **渠道/群组：** 附件保存在 M365 存储中（SharePoint/OneDrive）。webhook 负载仅包含 HTML 占位内容，不包含实际文件字节。**下载渠道附件需要 Graph API 权限。**
- 对于显式的文件优先发送，请使用 `action=upload-file`，并配合 `media` / `filePath` / `path`；可选的 `message` 会成为附带文本/评论，而 `filename` 会覆盖上传名称。
- **私信：** 图片和文件附件通过 Teams 机器人文件 API 工作。
- **渠道/群组：** 附件存放在 M365 存储中（SharePoint/OneDrive）。webhook payload 只包含 HTML 占位内容，不包含实际文件字节。**下载渠道附件需要 Graph API 权限**。
- 对于显式的文件优先发送，请使用 `action=upload-file`，搭配 `media` / `filePath` / `path`；可选的 `message` 会作为附带文本/评论，`filename` 会覆盖上传名称。
如果没有 Graph 权限，包含图片的渠道消息将仅以文本形式接收（bot 无法访问图片内容）。
默认情况下，OpenClaw 只会从 Microsoft/Teams 主机名下载媒体。可通过 `channels.msteams.mediaAllowHosts` 覆盖（使用 `["*"]` 可允许任意主机）。
Authorization 标头仅会附加到 `channels.msteams.mediaAuthAllowHosts` 中的主机（默认包含 Graph + Bot Framework 主机）。请保持该列表严格受限（避免多租户后缀）。
如果没有 Graph 权限，包含图片的渠道消息将仅作为文本接收（机器人无法访问图片内容）。
默认情况下，OpenClaw 只会从 Microsoft/Teams 主机名下载媒体。你可以使用 `channels.msteams.mediaAllowHosts` 覆盖（使用 `["*"]` 允许任意主机）。
Authorization 头仅会附加到 `channels.msteams.mediaAuthAllowHosts` 中的主机（默认为 Graph + Bot Framework 主机）。请保持该列表严格受限（避免使用多租户后缀）。
## 在群聊中发送文件
## 在群组聊天中发送文件
bot 可以在私信中通过 FileConsentCard 流程发送文件（内置支持）。但是，**在群聊/渠道中发送文件**需要额外设置：
机器人可以在私信中使用 FileConsentCard 流程发送文件（内置支持）。但是，**在群组聊天/渠道中发送文件**需要额外设置：
| 上下文 | 文件发送方式 | 所需设置 |
| 场景 | 文件发送方式 | 所需设置 |
| ------------------------ | -------------------------------------------- | ----------------------------------------------- |
| **私信** | FileConsentCard → 用户接受 → bot 上传 | 开箱即用 |
| **群聊/渠道** | 上传到 SharePoint → 分享链接 | 需要 `sharePointSiteId` + Graph 权限 |
| **图片（任意上下文）** | Base64 编码内联 | 开箱即用 |
| **私信** | FileConsentCard → 用户接受 → 机器人上传 | 开箱即用 |
| **群组聊天/渠道** | 上传到 SharePoint → 分享链接 | 需要 `sharePointSiteId` + Graph 权限 |
| **图片（任意场景）** | Base64 编码内联 | 开箱即用 |
### 为什么群聊需要 SharePoint
### 为什么群组聊天需要 SharePoint
bot 没有个人 OneDrive 驱动器（`/me/drive` Graph API 端点不适用于应用身份）。要在群聊/渠道中发送文件，bot 需要上传到一个 **SharePoint 站点** 并创建共享链接。
机器人没有个人 OneDrive 驱动器（`/me/drive` Graph API 端点对应用身份无效）。要在群组聊天/渠道中发送文件，机器人需要上传到 **SharePoint 站点** 并创建共享链接。
### 设置
1. 在 Entra ID（Azure AD）→ App Registration 中添加 **Graph API 权限**：
- `Sites.ReadWrite.All`（Application）- 将文件上传到 SharePoint
1. 在 Entra ID（Azure AD）→ App Registration 中添加 Graph API 权限：
- `Sites.ReadWrite.All`（Application）- 上传文件到 SharePoint
- `Chat.Read.All`（Application）- 可选，启用按用户共享链接
2. **为租户授予管理员同意**。
2. 为租户**授予管理员同意**。
3. **获取你的 SharePoint 站点 ID：**
```bash
# 通过 Graph Explorer，或使用带有效令牌的 curl：
# 通过 Graph Explorer 或使用有效令牌的 curl：
curl -H "Authorization: Bearer $TOKEN" \
"https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path}"
@ -738,7 +740,7 @@ bot 没有个人 OneDrive 驱动器（`/me/drive` Graph API 端点不适用于
curl -H "Authorization: Bearer $TOKEN" \
"https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/BotFiles"
# 响应包含："id": "contoso.sharepoint.com,guid1,guid2"
# 响应中包含："id": "contoso.sharepoint.com,guid1,guid2"
```
4. **配置 OpenClaw：**
@ -761,35 +763,35 @@ bot 没有个人 OneDrive 驱动器（`/me/drive` Graph API 端点不适用于
| `Sites.ReadWrite.All` only | 组织范围共享链接（组织内任何人都可访问） |
| `Sites.ReadWrite.All` + `Chat.Read.All` | 按用户共享链接（仅聊天成员可访问） |
按用户共享更安全，因为只有聊天参与者可以访问该文件。如果缺少 `Chat.Read.All` 权限，bot 会回退到组织范围共享。
按用户共享更安全，因为只有聊天参与者能够访问该文件。如果缺少 `Chat.Read.All` 权限，机器人会回退到组织范围共享。
### 回退行为
| 场景 | 结果 |
| ------------------------------------------------- | -------------------------------------------------- |
| 群聊 + 文件 + 已配置 `sharePointSiteId` | 上传到 SharePoint，发送共享链接 |
| 群聊 + 文件 + 未配置 `sharePointSiteId` | 尝试上传到 OneDrive（可能失败），仅发送文本 |
| 群组聊天 + 文件 + 已配置 `sharePointSiteId` | 上传到 SharePoint，发送共享链接 |
| 群组聊天 + 文件 + 未配置 `sharePointSiteId` | 尝试上传到 OneDrive（可能失败），仅发送文本 |
| 个人聊天 + 文件 | FileConsentCard 流程（无需 SharePoint 也可工作） |
| 任意上下文 + 图片 | Base64 编码内联（无需 SharePoint 也可工作） |
| 任意场景 + 图片 | Base64 编码内联（无需 SharePoint 也可工作） |
### 文件存储位置
上传的文件会存储在已配置 SharePoint 站点默认文档库中的 `/OpenClawShared/` 文件夹里。
上传的文件会存储在已配置 SharePoint 站点默认文档库中的 `/OpenClawShared/` 文件夹内。
## 投票（Adaptive Cards）
OpenClaw 通过 Adaptive Cards 发送 Teams 投票（Teams 没有原生投票 API）。
OpenClaw 将 Teams 投票作为 Adaptive Cards 发送（Teams 没有原生投票 API）。
- CLI：`openclaw message poll --channel msteams --target conversation:<id> ...`
- 投票由 Gateway 网关记录到 `~/.openclaw/msteams-polls.json`。
- 投票由 Gateway 网关记录在 `~/.openclaw/msteams-polls.json` 中。
- Gateway 网关必须保持在线才能记录投票。
- 投票尚不会自动发布结果摘要（如有需要，请检查存储文件）。
- 投票目前不会自动发布结果摘要（如有需要，请检查存储文件）。
## 展示卡片
使用 `message` 工具或 CLI，将语义化展示负载发送给 Teams 用户或会话。OpenClaw 会基于通用展示契约将其渲染为 Teams Adaptive Cards。
使用 `message` 工具或 CLI，将语义化展示 payload 发送给 Teams 用户或会话。OpenClaw 会根据通用展示契约，将其渲染为 Teams Adaptive Cards。
`presentation` 参数接受语义块。提供 `presentation` 时，消息文本为可选项。
`presentation` 参数接受语义化区块。提供 `presentation` 时，消息文本是可选的。
**智能体工具：**
@ -813,11 +815,11 @@ openclaw message send --channel msteams \
--presentation '{"title":"Hello","blocks":[{"type":"text","text":"Hello!"}]}'
```
关于目标格式的详情，请参见下方[目标格式](#target-formats)。
有关 target 格式的详细信息，见下方[目标格式](#target-formats)。
## 目标格式
MSTeams 目标使用前缀来区分用户和会话：
MSTeams target 使用前缀来区分用户和会话：
| 目标类型 | 格式 | 示例 |
| ------------------- | -------------------------------- | --------------------------------------------------- |
@ -835,10 +837,10 @@ openclaw message send --channel msteams --target "user:40a1a0ed-..." --message "
# 按显示名称向用户发送（会触发 Graph API 查找）
openclaw message send --channel msteams --target "user:John Smith" --message "Hello"
# 向群聊或渠道发送
# 发送到群组聊天或渠道
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" --message "Hello"
# 向会话发送展示卡片
# 向某个会话发送展示卡片
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" \
--presentation '{"title":"Hello","blocks":[{"type":"text","text":"Hello"}]}'
```
@ -866,23 +868,23 @@ openclaw message send --channel msteams --target "conversation:19:abc...@thread.
}
```
注意：如果没有 `user:` 前缀，名称默认会按群组/团队解析。按显示名称定位个人时，请始终使用 `user:`。
注意：如果没有 `user:` 前缀，名称默认会按群组/团队解析。按显示名称定位人员时，务必使用 `user:`。
## 主动消息
- 只有在用户已经互动**之后**，才可以发送主动消息，因为我们会在那时存储会话引用。
- 有关 `dmPolicy` 和允许列表门控，请参见 `/gateway/configuration`。
- 只有在用户已经发生过交互之后，才可以发送**主动消息**，因为我们会在那时存储会话引用。
- 有关 `dmPolicy` 和允许列表门控，参见 `/gateway/configuration`。
## 团队和渠道 ID（常见陷阱）
Teams URL 中的 `groupId` 查询参数**不是**用于配置的团队 ID。请从 URL 路径中提取 ID：
Teams URL 中的 `groupId` 查询参数**不是**用于配置的团队 ID。请改为从 URL 路径中提取 ID：
**团队 URL：**
```
https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=...
└────────────────────────────┘
团队 ID（对其进行 URL 解码）
团队 ID（对此进行 URL 解码）
```
**渠道 URL：**
@ -890,7 +892,7 @@ https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?gro
```
https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=...
└─────────────────────────┘
渠道 ID（对其进行 URL 解码）
渠道 ID（对此进行 URL 解码）
```
**用于配置时：**
@ -901,44 +903,44 @@ https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?gr
## 私有渠道
bot 在私有渠道中的支持有限：
机器人在私有渠道中的支持有限：
| 功能 | 标准渠道 | 私有渠道 |
| ---------------------------- | ----------------- | ---------------------- |
| bot 安装 | 是 | 有限 |
| 机器人安装 | 是 | 有限 |
| 实时消息（webhook） | 是 | 可能不可用 |
| RSC 权限 | 是 | 行为可能不同 |
| @mentions | 是 | 如果 bot 可访问 |
| Graph API 历史记录 | 是 | 是（需要权限） |
| @mentions | 是 | 如果机器人可访问 |
| Graph API 历史记录 | 是 | 是（有权限时） |
**如果私有渠道无法工作，可使用以下变通方法：**
**如果私有渠道不可用，可尝试以下变通方法：**
1. 使用标准渠道进行 bot 交互
2. 使用私信——用户始终可以直接向 bot 发消息
3. 使用 Graph API 进行历史访问（需要 `ChannelMessage.Read.All`）
1. 使用标准渠道进行机器人交互
2. 使用私信 —— 用户始终可以直接向机器人发送消息
3. 使用 Graph API 访问历史记录（需要 `ChannelMessage.Read.All`）
## 故障排除
### 常见问题
- **渠道中不显示图片：** 缺少 Graph 权限或管理员同意。请重新安装 Teams 应用，并完全退出/重新打开 Teams。
- **渠道中没有响应：** 默认要求提及；请设置 `channels.msteams.requireMention=false` 或按团队/渠道配置。
- **版本不匹配（Teams 仍显示旧 manifest）：** 删除并重新添加该应用，然后完全退出 Teams 以刷新。
- **webhook 返回 401 Unauthorized：** 在未使用 Azure JWT 时手动测试会出现该情况——这表示端点可达，但身份验证失败。请使用 Azure Web Chat 进行正确测试。
- **渠道中不显示图片：** 缺少 Graph 权限或管理员同意。重新安装 Teams 应用，并彻底退出/重新打开 Teams。
- **渠道中没有响应：** 默认要求提及；请设置 `channels.msteams.requireMention=false`，或按团队/渠道进行配置。
- **版本不匹配（Teams 仍显示旧 manifest）：** 移除后重新添加应用，并彻底退出 Teams 以刷新。
- **webhook 返回 401 Unauthorized：** 在没有 Azure JWT 的情况下手动测试时这是预期行为 —— 说明端点可达，但身份验证失败。请使用 Azure Web Chat 正确测试。
### Manifest 上传错误
- **“Icon file cannot be empty”：“** manifest 引用了大小为 0 字节的图标文件。请创建有效的 PNG 图标（`outline.png` 为 32x32，`color.png` 为 192x192）。
- **“webApplicationInfo.Id already in use”：“** 该应用仍安装在其他团队/聊天中。请先找到并卸载，或等待 5–10 分钟让变更传播。
- **上传时出现 “Something went wrong”：** 请改为通过 [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com) 上传，打开浏览器 DevTools（F12）→ Network 选项卡，并检查响应体中的实际错误。
- **侧载失败：** 尝试使用 “Upload an app to your org's app catalog” 而不是 “Upload a custom app”——这通常可以绕过侧载限制。
- **“Icon file cannot be empty”：** manifest 引用了大小为 0 字节的图标文件。请创建有效的 PNG 图标（`outline.png` 为 32x32，`color.png` 为 192x192）。
- **“webApplicationInfo.Id already in use”：** 该应用仍安装在其他团队/聊天中。请先找到并卸载，或等待 5–10 分钟完成传播。
- **上传时出现 “Something went wrong”：** 请改用 [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com) 上传，打开浏览器 DevTools（F12）→ Network 选项卡，并检查响应体中的实际错误。
- **侧载失败：** 试试使用 “Upload an app to your org's app catalog” 而不是 “Upload a custom app” —— 这通常可以绕过侧载限制。
### RSC 权限不起作用
### RSC 权限不生效
1. 确认 `webApplicationInfo.id` 与你的 bot App ID 完全一致
1. 验证 `webApplicationInfo.id` 与你的机器人 App ID 完全一致
2. 重新上传应用，并在团队/聊天中重新安装
3. 检查你的组织管理员是否阻止了 RSC 权限
4. 确认你使用了正确的作用域：团队使用 `ChannelMessage.Read.Group`，群聊使用 `ChatMessage.Read.Chat`
4. 确认你使用了正确的作用域：团队使用 `ChannelMessage.Read.Group`，群组聊天使用 `ChatMessage.Read.Chat`
## 参考资料
@ -953,7 +955,7 @@ bot 在私有渠道中的支持有限：
## 相关内容
- [Channels Overview](/zh-CN/channels) — 所有支持的渠道
- [Pairing](/zh-CN/channels/pairing) — 私信身份验证和配对流程
- [Groups](/zh-CN/channels/groups) — 群聊行为和提及门控
- [Pairing](/zh-CN/channels/pairing) — 私信身份验证与配对流程
- [Groups](/zh-CN/channels/groups) — 群组聊天行为与提及门控
- [Channel Routing](/zh-CN/channels/channel-routing) — 消息的会话路由
- [Security](/zh-CN/gateway/security) — 访问模型和安全加固
- [Security](/zh-CN/gateway/security) — 访问模型与加固

119
docs/zh-CN/cli/plugins.md
View File

@ -1,14 +1,14 @@
---
read_when:
- 你想安装或管理 Gateway 网关插件或兼容的捆绑包
- 你想调试插件加载失败
summary: '`openclaw plugins` 的 CLI 参考（列出、安装、市场、卸载、启用 / 禁用、Doctor）'
- 你想调试插件加载失败问题
summary: '`openclaw plugins` 的 CLI 设置参考（list、install、marketplace、uninstall、enable/disable、doctor）'
title: 插件
x-i18n:
generated_at: "2026-04-23T06:18:15Z"
generated_at: "2026-04-23T06:40:17Z"
model: gpt-5.4
provider: openai
source_hash: ad76a8068054d145db578ed01f1fb0726fff884c48d256ad8c0b708a516cd727
source_hash: 80e324995fa2dbb5babb9631714eb2449a1c8c00411bf6bf44c4c74bc9a3e2b8
source_path: cli/plugins.md
workflow: 15
---
@ -19,7 +19,7 @@ x-i18n:
相关内容：
- 插件系统：[插件](/zh-CN/tools/plugin)
- 插件系统：[Plugins](/zh-CN/tools/plugin)
- 捆绑包兼容性：[插件捆绑包](/zh-CN/plugins/bundles)
- 插件清单 + schema：[插件清单](/zh-CN/plugins/manifest)
- 安全加固：[安全](/zh-CN/gateway/security)
@ -46,49 +46,49 @@ openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
```
内置插件随 OpenClaw 一起提供。其中一些默认启用（例如内置模型提供商、内置语音提供商和内置浏览器插件）；另一些则需要执行 `plugins enable`。
内置插件随 OpenClaw 一起发布。其中一些默认启用（例如内置模型提供商、内置语音提供商以及内置浏览器插件）；另一些则需要运行 `plugins enable`。
原生 OpenClaw 插件必须提供带有内联 JSON Schema 的 `openclaw.plugin.json`（即使为空也要有 `configSchema`）。兼容捆绑包则使用它们自己的捆绑包清单。
原生 OpenClaw 插件必须随附 `openclaw.plugin.json`，并包含内联 JSON Schema（`configSchema`，即使为空也需要提供）。兼容捆绑包则改用它们自己的 bundle manifest。
`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细列表 / info 输出还会显示捆绑包子类型（`codex`、`claude` 或 `cursor`）以及检测到的捆绑包能力。
`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细列表 / 信息输出还会显示 bundle 子类型（`codex`、`claude` 或 `cursor`），以及检测到的 bundle 能力。
### 安装
```bash
openclaw plugins install <package> # 先查 ClawHub，再查 npm
openclaw plugins install <package> # 先 ClawHub，后 npm
openclaw plugins install clawhub:<package> # 仅 ClawHub
openclaw plugins install <package> --force # 覆盖现有安装
openclaw plugins install <package> --pin # 固定版本
openclaw plugins install <package> --dangerously-force-unsafe-install
openclaw plugins install <path> # 本地路径
openclaw plugins install <plugin>@<marketplace> # 市场
openclaw plugins install <plugin> --marketplace <name> # 市场（显式）
openclaw plugins install <plugin>@<marketplace> # marketplace
openclaw plugins install <plugin> --marketplace <name> # marketplace（显式）
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
```
不带前缀的包名会先在 ClawHub 中查找，再回退到 npm。安全提示：请像对待可执行代码一样对待插件安装。优先固定版本。
裸包名会先在 ClawHub 中查找，然后再查找 npm。安全提示：请将插件安装视为执行代码。优先使用固定版本。
如果配置无效，`plugins install` 通常会以失败关闭，并提示你先运行 `openclaw doctor --fix`。唯一记录在案的例外，是针对显式选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件所提供的一条受限的内置插件恢复路径。
如果配置无效，`plugins install` 通常会以安全关闭方式失败，并提示你先运行 `openclaw doctor --fix`。唯一有文档说明的例外，是一个针对内置插件的窄范围恢复路径，用于那些显式选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件。
`--force` 会复用现有安装目标，并原地覆盖已安装的插件或 hook 包。当你有意从新的本地路径、归档文件、ClawHub 包或 npm 工件重新安装相同 id 时，请使用它。对于已跟踪 npm 插件的常规升级，优先使用 `openclaw plugins update <id-or-npm-spec>`。
`--force` 会复用现有安装目标，并原地覆盖已安装的插件或 hook 包。当你明确要从新的本地路径、归档、ClawHub 包或 npm 制品重新安装同一 id 时，请使用它。对于已跟踪 npm 插件的常规升级，优先使用 `openclaw plugins update <id-or-npm-spec>`。
`--pin` 仅适用于 npm 安装。它不支持与 `--marketplace` 一起使用，因为市场安装会保存市场来源元数据，而不是 npm spec。
`--pin` 仅适用于 npm 安装。不支持与 `--marketplace` 一起使用，因为 marketplace 安装会保存 marketplace 源元数据，而不是 npm spec。
`--dangerously-force-unsafe-install` 是一个紧急破玻璃选项，用于处理内置危险代码扫描器的误报。即使内置扫描器报告 `critical` 级别发现，它也允许安装继续，但它**不会**绕过插件 `before_install` hook 策略拦截，也**不会**绕过扫描失败。
`--dangerously-force-unsafe-install` 是一个紧急兜底选项，用于处理内置危险代码扫描器的误报。即使内置扫描器报告 `critical` 级发现，它也允许继续安装，但它**不会**绕过插件 `before_install` hook 的策略阻止，也**不会**绕过扫描失败。
这个 CLI 标志适用于插件安装 / 更新流程。由 Gateway 网关支持的 skill 依赖安装使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍然是独立的 ClawHub skill 下载 / 安装流程。
这个 CLI 标志适用于插件 install / update 流程。由 Gateway 网关支持的技能依赖安装使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖项，而 `openclaw skills install` 仍然是独立的 ClawHub Skills 下载 / 安装流程。
`plugins install` 也是安装在 `package.json` 中暴露 `openclaw.hooks` 的 hook 包的安装界面。对于过滤后的 hook 可见性和按 hook 启用，请使用 `openclaw hooks`，而不是包安装。
`plugins install` 也是暴露了 `openclaw.hooks` 的 hook 包在 `package.json` 中的安装入口。请使用 `openclaw hooks` 来查看经过筛选的 hook 可见性以及按 hook 启用，而不是用于包安装。
npm spec **仅限 registry**（包名 + 可选的**精确版本**或 **dist-tag**）。Git / URL / 文件 spec 和 semver 范围都会被拒绝。出于安全考虑，依赖安装会使用 `--ignore-scripts` 运行。
npm spec **仅支持 registry**（包名 + 可选的**精确版本**或 **dist-tag**）。Git / URL / file spec 和 semver 范围都会被拒绝。为确保安全，依赖安装会使用 `--ignore-scripts` 运行。
不带版本的 spec 和 `@latest` 会停留在稳定通道上。如果 npm 将其中任意一种解析为预发布版本，OpenClaw 会停止并要求你通过预发布标签（例如 `@beta` / `@rc`）或精确的预发布版本（例如 `@1.2.3-beta.4`）显式选择加入。
裸 spec 和 `@latest` 会停留在稳定轨道上。如果 npm 将其中任一项解析为预发布版本，OpenClaw 会停止，并要求你通过预发布 tag（例如 `@beta` / `@rc`）或精确的预发布版本（例如 `@1.2.3-beta.4`）显式选择加入。
如果一个不带前缀的安装 spec 与某个内置插件 id 匹配（例如 `diffs`），OpenClaw 会直接安装该内置插件。要安装同名的 npm 包，请使用显式带作用域的 spec（例如 `@scope/diffs`）。
如果一个裸安装 spec 与某个内置插件 id 匹配（例如 `diffs`），OpenClaw 会直接安装该内置插件。若要安装同名的 npm 包，请使用显式的带作用域 spec（例如 `@scope/diffs`）。
支持的归档格式：`.zip`、`.tgz`、`.tar.gz`、`.tar`。
也支持 Claude 市场安装。
也支持 Claude marketplace 安装。
ClawHub 安装使用显式的 `clawhub:<package>` 定位符：
@ -97,22 +97,22 @@ openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
```
OpenClaw 现在也会优先为安全的裸 npm 插件 spec 使用 ClawHub。只有当 ClawHub 没有该包或该版本时，才会回退到 npm：
OpenClaw 现在也会优先为裸 npm-safe 插件 spec 使用 ClawHub。只有当 ClawHub 中没有该包或该版本时，才会回退到 npm：
```bash
openclaw plugins install openclaw-codex-app-server
```
OpenClaw 会从 ClawHub 下载包归档，检查声明的插件 API / 最低 Gateway 网关兼容性，然后通过常规归档路径进行安装。记录的安装会保留其 ClawHub 来源元数据，以供后续更新使用。
OpenClaw 会从 ClawHub 下载包归档，检查声明的插件 API / 最低 Gateway 网关兼容性，然后通过常规归档路径安装。已记录的安装会保留其 ClawHub 源元数据，以便后续更新。
当市场名称存在于 Claude 的本地注册表缓存 `~/.claude/plugins/known_marketplaces.json` 中时，使用 `plugin@marketplace` 简写：
当 marketplace 名称存在于 Claude 的本地注册表缓存 `~/.claude/plugins/known_marketplaces.json` 中时，可使用 `plugin@marketplace` 简写：
```bash
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
```
当你想显式传递市场来源时，请使用 `--marketplace`：
如果你想显式传递 marketplace 源，请使用 `--marketplace`：
```bash
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
@ -121,24 +121,24 @@ openclaw plugins install <plugin-name> --marketplace https://github.com/<owner>/
openclaw plugins install <plugin-name> --marketplace ./my-marketplace
```
市场来源可以是：
Marketplace 源可以是：
- 来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知市场名称
- 本地市场根目录或 `marketplace.json` 路径
- 形如 `owner/repo` 的 GitHub 仓库简写
- 形如 `https://github.com/owner/repo` 的 GitHub 仓库 URL
- `~/.claude/plugins/known_marketplaces.json` 中 Claude 已知 marketplace 名称
- 本地 marketplace 根目录或 `marketplace.json` 路径
- GitHub 仓库简写，例如 `owner/repo`
- GitHub 仓库 URL，例如 `https://github.com/owner/repo`
- git URL
对于从 GitHub 或 git 加载的远程市场，插件条目必须保留在克隆下来的市场仓库内部。OpenClaw 接受该仓库中的相对路径来源，并拒绝远程清单中的 HTTP(S)、绝对路径、git、GitHub 和其他非路径插件来源。
对于从 GitHub 或 git 加载的远程 marketplace，插件条目必须保持在克隆后的 marketplace 仓库内。OpenClaw 接受来自该仓库的相对路径源，并拒绝远程 manifest 中的 HTTP(S)、绝对路径、git、GitHub 以及其他非路径插件源。
对于本地路径和归档，OpenClaw 会自动检测：
- 原生 OpenClaw 插件（`openclaw.plugin.json`）
- 兼容 Codex 的捆绑包（`.codex-plugin/plugin.json`）
- 兼容 Claude 的捆绑包（`.claude-plugin/plugin.json` 或默认的 Claude 组件布局）
- 兼容 Cursor 的捆绑包（`.cursor-plugin/plugin.json`）
- Codex 兼容捆绑包（`.codex-plugin/plugin.json`）
- Claude 兼容捆绑包（`.claude-plugin/plugin.json` 或默认的 Claude 组件布局）
- Cursor 兼容捆绑包（`.cursor-plugin/plugin.json`）
兼容捆绑包会安装到常规扩展根目录中，并参与相同的 list / info / enable / disable 流程。目前，支持捆绑包 Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录；其他检测到的捆绑包能力会显示在诊断 / info 中，但尚未接入运行时执行。
兼容捆绑包会安装到常规插件根目录中，并参与相同的 list / info / enable / disable 流程。目前，已支持 bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` / manifest 声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录；其他已检测到的 bundle 能力会在诊断 / 信息中显示，但尚未接入运行时执行。
### 列表
@ -149,17 +149,17 @@ openclaw plugins list --verbose
openclaw plugins list --json
```
使用 `--enabled` 仅显示已加载的插件。使用 `--verbose` 可从表格视图切换到按插件显示详细行，包括来源 / 起源 / 版本 / 激活元数据。使用 `--json` 获取机器可读的清单和注册表诊断。
使用 `--enabled` 仅显示已加载的插件。使用 `--verbose` 可从表格视图切换到按插件显示的详细行，其中包含 source / origin / version / activation 元数据。使用 `--json` 可获取机器可读的清单以及注册表诊断信息。
使用 `--link` 避免复制本地目录（会添加到 `plugins.load.paths`）：
使用 `--link` 可避免复制本地目录（会添加到 `plugins.load.paths`）：
```bash
openclaw plugins install -l ./my-plugin
```
`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是复制到受管理的安装目标上。
`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是复制到受管安装目标上。
在 npm 安装中使用 `--pin`，可将解析得到的精确 spec（`name@version`）保存到 `plugins.installs` 中，而默认行为则保持不固定版本。
在 npm 安装中使用 `--pin`，可将解析出的精确 spec（`name@version`）保存到 `plugins.installs` 中，同时保持默认行为为不固定版本。
### 卸载
@ -169,11 +169,11 @@ openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
```
`uninstall` 会从 `plugins.entries`、`plugins.installs`、插件允许列表以及链接的 `plugins.load.paths` 条目中移除插件记录（如适用）。对于活跃的内存插件，memory 槽位会重置为 `memory-core`。
`uninstall` 会从 `plugins.entries`、`plugins.installs`、插件 allowlist，以及在适用时的已链接 `plugins.load.paths` 条目中移除插件记录。对于活动中的 memory 插件，memory 槽位会重置为 `memory-core`。
默认情况下，卸载还会删除活动 state-dir 插件根目录下的插件安装目录。使用 `--keep-files` 可保留磁盘上的文件。
`--keep-config` 作为 `--keep-files` 的废弃别名仍然受支持。
`--keep-config` 作为 `--keep-files` 的已弃用别名仍受支持。
### 更新
@ -185,19 +185,19 @@ openclaw plugins update @openclaw/voice-call@beta
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
```
更新会应用到 `plugins.installs` 中已跟踪的安装，以及 `hooks.internal.installs` 中已跟踪的 hook 包安装。
更新会应用于 `plugins.installs` 中跟踪的安装，以及 `hooks.internal.installs` 中跟踪的 hook 包安装。
当你传入插件 id 时，OpenClaw 会复用为该插件记录的安装 spec。这意味着先前保存的 dist-tag（例如 `@beta`）和精确固定版本在后续执行 `update <id>` 时会继续被使用。
当你传入插件 id 时，OpenClaw 会复用为该插件记录的安装 spec。这意味着此前保存的 dist-tag（例如 `@beta`）和固定的精确版本，之后在运行 `update <id>` 时仍会继续使用。
对于 npm 安装，你也可以传入带有 dist-tag 或精确版本的显式 npm 包 spec。OpenClaw 会将该包名解析回已跟踪的插件记录，更新该已安装插件，并为未来基于 id 的更新记录新的 npm spec。
对于 npm 安装，你也可以传入带有 dist-tag 或精确版本的显式 npm 包 spec。OpenClaw 会将该包名回溯解析到已跟踪的插件记录，更新那个已安装插件，并为将来基于 id 的更新记录新的 npm spec。
传入不带版本或标签的 npm 包名，同样会解析回已跟踪的插件记录。当某个插件被固定到精确版本，而你想让它回到 registry 的默认发布线时，请使用这种方式。
仅传入不带版本或 tag 的 npm 包名，也会回溯解析到已跟踪的插件记录。当某个插件被固定到精确版本，而你想把它移回 registry 的默认发布线时，可使用这种方式。
在执行实际的 npm 更新之前，OpenClaw 会根据 npm registry 元数据检查已安装包版本。如果已安装版本和记录的工件标识已经与解析后的目标一致，则会跳过更新，不会下载、重新安装，也不会重写 `openclaw.json`。
在实际执行 npm 更新之前，OpenClaw 会将已安装包版本与 npm registry 元数据进行检查。如果已安装版本与记录的制品标识已经匹配解析出的目标版本，则会跳过更新，不会下载、重新安装，也不会重写 `openclaw.json`。
当存在已保存的完整性哈希，而获取到的工件哈希发生变化时，OpenClaw 会将其视为 npm 工件漂移。交互式 `openclaw plugins update` 命令会打印预期和实际哈希，并在继续之前请求确认。非交互式更新辅助工具会以失败关闭，除非调用方提供显式的继续策略。
当存在已存储的完整性哈希，而获取到的制品哈希发生变化时，OpenClaw 会将其视为 npm 制品漂移。交互式 `openclaw plugins update` 命令会打印预期哈希和实际哈希，并在继续前请求确认。非交互式更新辅助流程会以安全关闭方式失败，除非调用方提供显式的继续策略。
`--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为在插件更新期间处理内置危险代码扫描误报的紧急覆盖选项。它仍然不会绕过插件 `before_install` 策略拦截或扫描失败拦截，并且它只适用于插件更新，不适用于 hook 包更新。
`--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为处理插件更新期间内置危险代码扫描误报的紧急覆盖项。它仍然不会绕过插件 `before_install` 策略阻止或扫描失败阻止，并且只适用于插件更新，不适用于 hook 包更新。
### 检查
@ -206,20 +206,20 @@ openclaw plugins inspect <id>
openclaw plugins inspect <id> --json
```
用于单个插件的深度内省。显示身份信息、加载状态、来源、已注册能力、hooks、工具、命令、服务、Gateway 网关方法、HTTP 路由、策略标志、诊断、安装元数据、捆绑包能力，以及任何检测到的 MCP 或 LSP 服务器支持。
对单个插件进行深度检查。显示标识、加载状态、来源、已注册能力、hooks、工具、命令、服务、Gateway 网关方法、HTTP 路由、策略标志、诊断信息、安装元数据、bundle 能力，以及任何检测到的 MCP 或 LSP 服务器支持。
每个插件都会根据其在运行时实际注册的内容进行分类：
- **plain-capability** — 一种能力类型（例如仅提供商插件）
- **plain-capability** — 一种能力类型（例如仅 provider 插件）
- **hybrid-capability** — 多种能力类型（例如文本 + 语音 + 图像）
- **hook-only** — 只有 hooks，没有能力或界面
- **hook-only** — 只有 hooks，没有能力或表面
- **non-capability** — 有工具 / 命令 / 服务，但没有能力
关于能力模型的更多信息，请参见 [插件形态](/zh-CN/plugins/architecture#plugin-shapes)。
有关能力模型的更多信息，请参阅 [Plugin shapes](/zh-CN/plugins/architecture#plugin-shapes)。
`--json` 标志会输出适合脚本和审计使用的机器可读报告。
`--json` 标志会输出适用于脚本处理和审计的机器可读报告。
`inspect --all` 会渲染一个面向整个集群的表格，其中包含形态、能力种类、兼容性提示、捆绑包能力和 hook 摘要列。
`inspect --all` 会渲染一个全局表格，其中包含 shape、capability kinds、compatibility notices、bundle capabilities 和 hook summary 列。
`info` 是 `inspect` 的别名。
@ -229,16 +229,15 @@ openclaw plugins inspect <id> --json
openclaw plugins doctor
```
`doctor` 会报告插件加载错误、清单 / 发现诊断以及兼容性提示。当一切正常时，它会打印 `No plugin issues
detected.`
`doctor` 会报告插件加载错误、manifest / 发现诊断信息以及兼容性提示。当一切正常时，它会输出 `No plugin issues detected.`
对于诸如缺少 `register` / `activate` 导出之类的模块形态失败，请使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以在诊断输出中包含精简的导出形态摘要。
对于缺少 `register` / `activate` 导出之类的模块形状失败问题，请使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以便在诊断输出中包含紧凑的导出形状摘要。
### 市场
### Marketplace
```bash
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
```
市场列表接受本地市场路径、`marketplace.json` 路径、形如 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL 或 git URL。`--json` 会打印解析后的来源标签，以及已解析的市场清单和插件条目。
Marketplace list 接受本地 marketplace 路径、`marketplace.json` 路径、如 `owner/repo` 这样的 GitHub 简写、GitHub 仓库 URL 或 git URL。`--json` 会输出解析后的源标签，以及已解析的 marketplace manifest 和插件条目。

59
docs/zh-CN/cli/security.md
View File

@ -1,14 +1,14 @@
---
read_when:
- 你想对配置/状态运行快速安全审计
- 你想对配置/状态运行一次快速安全审计
- 你想应用安全的“修复”建议（权限、收紧默认值）
summary: '`openclaw security` 的 CLI 参考（审计并修复常见安全陷阱）'
title: security
title: 安全
x-i18n:
generated_at: "2026-04-05T08:20:23Z"
generated_at: "2026-04-23T06:40:18Z"
model: gpt-5.4
provider: openai
source_hash: e5a3e4ab8e0dfb6c10763097cb4483be2431985f16de877523eb53e2122239ae
source_hash: 92b80468403b7d329391c40add9ae9c0e2423f5c6ff162291fa13ab91ace985d
source_path: cli/security.md
workflow: 15
---
@ -19,7 +19,7 @@ x-i18n:
相关内容：
- 安全指南：[安全性](/gateway/security)
- 安全指南：[安全](/zh-CN/gateway/security)
## 审计
@ -32,27 +32,28 @@ openclaw security audit --fix
openclaw security audit --json
```
当多个私信发送者共享主会话时，审计会发出警告，并推荐使用**安全私信模式**：`session.dmScope="per-channel-peer"`（对于多账户渠道则使用 `per-account-channel-peer`）。这适用于协作式/共享收件箱的加固。由相互不信任/对抗性的操作员共享同一个 Gateway 网关并不是推荐的设置；请使用单独的 Gateway 网关（或单独的 OS 用户/主机）来拆分信任边界。
当配置暗示可能存在共享用户入口时（例如开放的私信/群组策略、已配置的群组目标，或通配符发送者规则），它还会发出 `security.trust_model.multi_user_heuristic`，并提醒你 OpenClaw 默认采用个人助理信任模型。
对于有意的共享用户设置，审计建议对所有会话启用沙箱隔离、将文件系统访问限制在工作区范围内，并且不要在该运行时上放置个人/私有身份或凭证。
当小模型（`<=300B`）在未启用沙箱隔离的情况下使用，且启用了 web/browser 工具时，它也会发出警告。
对于 webhook 入口，当 `hooks.token` 重用了 Gateway 网关令牌、`hooks.token` 过短、`hooks.path="/"`、`hooks.defaultSessionKey` 未设置、`hooks.allowedAgentIds` 未受限制、启用了请求 `sessionKey` 覆盖，以及在未设置 `hooks.allowedSessionKeyPrefixes` 的情况下启用了覆盖时，它也会发出警告。
当 sandbox Docker 设置已配置但沙箱模式关闭时、当 `gateway.nodes.denyCommands` 使用了无效的类模式/未知条目时（仅支持精确的节点命令名匹配，不支持 shell 文本过滤）、当 `gateway.nodes.allowCommands` 显式启用了危险的节点命令时、当全局 `tools.profile="minimal"` 被智能体工具配置文件覆盖时、当开放群组在没有沙箱/工作区保护的情况下暴露运行时/文件系统工具时，以及当已安装的扩展插件工具在宽松工具策略下可能可达时，它也会发出警告。
它还会标记 `gateway.allowRealIpFallback=true`（如果代理配置错误，存在请求头伪造风险）和 `discovery.mdns.mode="full"`（通过 mDNS TXT 记录泄露元数据）。
当沙箱浏览器使用 Docker `bridge` 网络而未设置 `sandbox.browser.cdpSourceRange` 时，它也会发出警告。
当多个私信发送者共享主会话时，审计会发出警告，并建议使用 **安全私信模式**：`session.dmScope="per-channel-peer"`（对于多账号渠道，则使用 `per-account-channel-peer`），适用于共享收件箱。
这是为了加固协作式/共享式收件箱。由彼此不信任或存在对抗关系的操作人员共享同一个 Gateway 网关，并不是推荐的设置；应通过单独的 Gateway 网关（或单独的操作系统用户/主机）来划分信任边界。
当配置表明很可能存在共享用户入口时，它还会输出 `security.trust_model.multi_user_heuristic`（例如开放的私信/群组策略、已配置的群组目标，或通配符发送者规则），并提醒你 OpenClaw 默认采用个人助理信任模型。
对于有意的共享用户设置，审计建议对所有会话启用沙箱隔离，将文件系统访问限制在工作区范围内，并且不要在该运行时中放入个人/私有身份或凭证。
当使用小模型（`<=300B`）且未启用沙箱隔离，同时启用了 web/browser 工具时，它也会发出警告。
对于 webhook 入口，它会在以下情况下发出警告：`hooks.token` 复用 Gateway 网关 token、`hooks.token` 过短、`hooks.path="/"`、未设置 `hooks.defaultSessionKey`、`hooks.allowedAgentIds` 未受限制、启用了请求 `sessionKey` 覆盖，以及启用了覆盖但未设置 `hooks.allowedSessionKeyPrefixes`。
当配置了沙箱 Docker 设置但沙箱模式处于关闭状态时，它也会发出警告；当 `gateway.nodes.denyCommands` 使用无效的类模式/未知条目时也会发出警告（这里只支持精确的节点命令名匹配，不支持 shell 文本过滤）；当 `gateway.nodes.allowCommands` 显式启用危险节点命令时会发出警告；当全局 `tools.profile="minimal"` 被智能体工具配置文件覆盖时会发出警告；当开放群组在没有沙箱/工作区防护的情况下暴露运行时/文件系统工具时会发出警告；当已安装的 plugin 工具可能在宽松工具策略下可被访问时也会发出警告。
它还会将 `gateway.allowRealIpFallback=true` 标记为风险项（如果代理配置错误，会有 header 伪造风险），并将 `discovery.mdns.mode="full"` 标记为风险项（通过 mDNS TXT 记录泄露元数据）。
当沙箱浏览器使用 Docker `bridge` 网络但未设置 `sandbox.browser.cdpSourceRange` 时，它也会发出警告。
它还会标记危险的沙箱 Docker 网络模式（包括 `host` 和 `container:*` 命名空间加入）。
当现有沙箱浏览器 Docker 容器缺少或使用了过时的哈希标签时（例如迁移前的容器缺少 `openclaw.browserConfigEpoch`），它也会发出警告，并建议运行 `openclaw sandbox recreate --browser --all`。
当基于 npm 的插件/hook 安装记录未固定版本、缺少完整性元数据，或与当前已安装的软件包版本不一致时，它也会发出警告。
当渠道允许列表依赖可变的名称/邮箱/标签而非稳定 ID 时（适用于 Discord、Slack、Google Chat、Microsoft Teams、Mattermost，以及适用的 IRC 范围），它也会发出警告。
当 `gateway.auth.mode="none"` 导致 Gateway 网关 HTTP API 在没有共享密钥的情况下可被访问时（`/tools/invoke` 加上任何已启用的 `/v1/*` 端点），它也会发出警告。
以 `dangerous`/`dangerously` 为前缀的设置是明确的 break-glass 操作员覆盖项；启用其中某一项本身并不自动构成安全漏洞报告。
完整的危险参数清单，请参阅[安全性](/gateway/security)中的“非安全或危险标志摘要”部分。
当现有的沙箱浏览器 Docker 容器缺少或使用了过期的哈希标签时（例如迁移前容器缺少 `openclaw.browserConfigEpoch`），它也会发出警告，并建议运行 `openclaw sandbox recreate --browser --all`。
当基于 npm 的 plugin/hook 安装记录未固定版本、缺少完整性元数据，或与当前已安装的软件包版本不一致时，它也会发出警告。
当渠道 allowlist 依赖可变名称/邮箱/标签而不是稳定 ID 时，它会发出警告（适用于 Discord、Slack、Google Chat、Microsoft Teams、Mattermost，以及适用范围内的 IRC）。
当 `gateway.auth.mode="none"` 使 Gateway 网关 HTTP API 在没有共享密钥的情况下可访问时，它也会发出警告（`/tools/invoke` 以及任何已启用的 `/v1/*` 端点）。
以 `dangerous`/`dangerously` 为前缀的设置，是明确的紧急破玻璃式操作员覆盖项；启用其中某一项本身并不自动构成安全漏洞报告。
如需查看完整的危险参数清单，请参见[安全](/zh-CN/gateway/security)中的“`Insecure or dangerous flags summary`”章节。
SecretRef 行为：
- `security audit` 会以只读模式解析其目标路径中受支持的 SecretRef。
- 如果当前命令路径中某个 SecretRef 不可用，审计会继续进行，并报告 `secretDiagnostics`（而不是崩溃）。
- `--token` 和 `--password` 仅覆盖该次命令调用的深度探测认证；它们不会重写配置或 SecretRef 映射。
- `--token` 和 `--password` 只会覆盖本次命令调用的深度探测认证；它们不会重写配置或 SecretRef 映射。
## JSON 输出
@ -63,7 +64,7 @@ openclaw security audit --json | jq '.summary'
openclaw security audit --deep --json | jq '.findings[] | select(.severity=="critical") | .checkId'
```
如果组合使用 `--fix` 和 `--json`，输出将同时包含修复操作和最终报告：
如果同时使用 `--fix` 和 `--json`，输出会同时包含修复操作和最终报告：
```bash
openclaw security audit --fix --json | jq '{fix: .fix.ok, summary: .report.summary}'
@ -71,20 +72,20 @@ openclaw security audit --fix --json | jq '{fix: .fix.ok, summary: .report.summa
## `--fix` 会修改什么
`--fix` 会应用安全、确定性的修复措施：
`--fix` 会应用安全且确定性的修复措施：
- 将常见的 `groupPolicy="open"` 切换为 `groupPolicy="allowlist"`（包括受支持渠道中的账户变体）
- 当 WhatsApp 群组策略切换为 `allowlist` 时，如果已存在存储的 `allowFrom` 文件且配置中尚未定义 `allowFrom`，则会从该文件为 `groupAllowFrom` 设定初始值
- 将常见的 `groupPolicy="open"` 切换为 `groupPolicy="allowlist"`（包括受支持渠道中的账号变体）
- 当 WhatsApp 群组策略切换为 `allowlist` 时，如果已存在存储的 `allowFrom` 文件且配置中尚未定义 `allowFrom`，则从该文件为 `groupAllowFrom` 设定初始值
- 将 `logging.redactSensitive` 从 `"off"` 设置为 `"tools"`
- 收紧状态/配置以及常见敏感文件的权限
（`credentials/*.json`、`auth-profiles.json`、`sessions.json`、会话
`*.jsonl`）
- 也会收紧 `openclaw.json` 中引用的配置 include 文件
- 在 POSIX 主机上使用 `chmod`，在 Windows 上使用 `icacls` 重置
- 也会收紧从 `openclaw.json` 引用的配置 include 文件的权限
- 在 POSIX 主机上使用 `chmod`，在 Windows 上使用 `icacls` 重置权限
`--fix` **不会**：
- 轮换令牌/密码/API 密钥
- 轮换 token/password/API key
- 禁用工具（`gateway`、`cron`、`exec` 等）
- 更改 Gateway 网关绑定/认证/网络暴露选择
- 删除或重写插件/Skills
- 更改 Gateway 网关的绑定/认证/网络暴露选择
- 删除或重写 plugins/Skills

96
docs/zh-CN/cli/update.md
View File

@ -1,24 +1,24 @@
---
read_when:
- 你想安全地更新源码检出副本
- 你需要了解 `--update` 简写行为
summary: '`openclaw update` 的 CLI 参考（相对安全的源码更新 + Gateway 网关自动重启）'
title: update
- 你想相对安全地更新源码检出副本
- 你需要理解 `--update` 简写行为
summary: '`openclaw update` 的 CLI 参考（相对安全的源更新 + Gateway 网关 自动重启）'
title: 更新
x-i18n:
generated_at: "2026-04-23T06:18:33Z"
generated_at: "2026-04-23T06:40:28Z"
model: gpt-5.4
provider: openai
source_hash: dc049ecf3d35fe276a1e5962bb8e5316dbbc3219ef0b91ee64d41cbbea20f9ae
source_hash: abcfbd2fb66f560f2c6e9d78d37355510d78946eaeafa17d67fe36bc158ad5cd
source_path: cli/update.md
workflow: 15
---
# `openclaw update`
安全更新 OpenClaw，并在 stable/beta/dev 渠道之间切换。
安全地更新 OpenClaw，并在 stable/beta/dev 渠道之间切换。
如果你通过 **npm/pnpm/bun** 安装（全局安装，无 git 元数据），
更新会通过 [Updating](/zh-CN/install/updating) 中的包管理器流程进行。
更新会通过 [Updating](/zh-CN/install/updating) 中的软件包管理器流程进行。
## 用法
@ -39,21 +39,19 @@ openclaw --update
## 选项
- `--no-restart`：成功更新后跳过重启 Gateway 网关服务。
- `--no-restart`：成功更新后跳过重启 Gateway 网关 服务。
- `--channel <stable|beta|dev>`：设置更新渠道（git + npm；会持久化到配置中）。
- `--tag <dist-tag|version|spec>`：仅为本次更新覆盖包目标。对于包安装，`main` 会映射为 `github:openclaw/openclaw#main`。
- `--dry-run`：预览计划中的更新操作（渠道/tag/目标/重启流程），但不写入配置、不安装、不同步插件，也不重启。
- `--json`：打印机器可读的 `UpdateRunResult` JSON，包括
当在更新后插件同步期间检测到 npm 插件产物漂移时的
`postUpdate.plugins.integrityDrifts`。
- `--timeout <seconds>`：每一步的超时时间（默认 1200 秒）。
- `--tag <dist-tag|version|spec>`：仅为本次更新覆盖软件包目标。对于软件包安装，`main` 映射到 `github:openclaw/openclaw#main`。
- `--dry-run`：预览计划中的更新操作（渠道/标签/目标/重启流程），但不会写入配置、安装、同步插件或重启。
- `--json`：输出机器可读的 `UpdateRunResult` JSON，包括在更新后插件同步期间检测到 npm 插件产物漂移时的 `postUpdate.plugins.integrityDrifts`。
- `--timeout <seconds>`：每个步骤的超时时间（默认 1200 秒）。
- `--yes`：跳过确认提示（例如降级确认）
注意：降级需要确认，因为旧版本可能会破坏配置。
## `update status`
显示当前激活的更新渠道 + git tag/branch/SHA（对于源码检出副本），以及更新可用性。
显示当前活动的更新渠道 + git 标签/分支/SHA（适用于源码检出），以及更新可用性。
```bash
openclaw update status
@ -63,14 +61,14 @@ openclaw update status --timeout 10
选项：
- `--json`：打印机器可读的状态 JSON。
- `--json`：输出机器可读的状态 JSON。
- `--timeout <seconds>`：检查超时时间（默认 3 秒）。
## `update wizard`
用于选择更新渠道并确认更新后是否重启 Gateway 网关的交互式流程
（默认会重启）。如果你在没有 git 检出副本的情况下选择 `dev`，
它会提供创建检出副本的选项。
交互式流程，用于选择更新渠道并确认更新后是否重启 Gateway 网关
（默认会重启）。如果你在没有 git 检出的情况下选择 `dev`，它会
提供创建检出的选项。
选项：
@ -78,58 +76,54 @@ openclaw update status --timeout 10
## 它会做什么
当你显式切换渠道时（`--channel ...`），OpenClaw 也会保持
安装方式与之对齐：
当你显式切换渠道（`--channel ...`）时，OpenClaw 也会保持安装方式一致：
- `dev` → 确保存在一个 git 检出副本（默认：`~/openclaw`，可通过 `OPENCLAW_GIT_DIR` 覆盖），
对其进行更新，并从该检出副本安装全局 CLI。
- `dev` → 确保存在一个 git 检出（默认：`~/openclaw`，可通过 `OPENCLAW_GIT_DIR`` 覆盖），
更新它，并从该检出安装全局 CLI。
- `stable` → 使用 `latest` 从 npm 安装。
- `beta` → 优先使用 npm dist-tag `beta`，但当 beta 不存在
或比当前 stable 发布更旧时，会回退到 `latest`。
- `beta` → 优先使用 npm dist-tag `beta`，但当 beta 不存在或比当前 stable 版本更旧时，会回退到 `latest`。
Gateway 网关核心自动更新器（在配置中启用时）会复用相同的更新路径。
Gateway 网关 核心自动更新器（在配置中启用时）会复用同一条更新路径。
对于包管理器安装，`openclaw update` 会先解析目标包
版本，然后再调用包管理器。如果已安装版本与目标版本完全
匹配，并且不需要持久化任何更新渠道变更，则该
命令会在执行包安装、插件同步、补全刷新
或 Gateway 网关重启之前，以跳过状态退出。
对于软件包管理器安装，`openclaw update` 会在调用软件包管理器之前解析目标软件包
版本。如果已安装版本与目标完全一致，且不需要持久化更新渠道变更，
命令会在软件包安装、插件同步、补全刷新或 Gateway 网关 重启之前以跳过状态退出。
## Git 检出副本流程
## Git 检出流程
渠道：
- `stable`：检出最新的非 beta tag，然后 build + doctor。
- `beta`：优先使用最新的 `-beta` tag，但当 beta 不存在或更旧时，
会回退到最新的 stable tag。
- `dev`：检出 `main`，然后 fetch + rebase。
- `stable`：检出最新的非 beta 标签，然后执行构建 + doctor。
- `beta`：优先使用最新的 `-beta` 标签，但当 beta 不存在或更旧时，
回退到最新 stable 标签。
- `dev`：检出 `main`，然后执行 fetch + rebase。
高级流程：
1. 需要一个干净的工作树（没有未提交的更改）。
2. 切换到所选渠道（tag 或 branch）。
3. 获取上游更新（仅 `dev`）。
4. 仅 `dev`：在临时工作树中执行预检 lint + TypeScript build；如果最新提交失败，则向后回退最多 10 个提交，以找到最新的可干净构建版本。
5. 变基到所选提交（仅 `dev`）。
6. 使用仓库包管理器安装依赖。对于 pnpm 检出副本，更新器会按需引导安装 `pnpm`（优先通过 `corepack`，然后回退到临时 `npm install pnpm@10`），而不是在 pnpm workspace 中运行 `npm run build`。
7. 执行 build，并构建 Control UI。
1. 要求工作树干净（没有未提交的更改）。
2. 切换到所选渠道（标签或分支）。
3. 拉取上游（仅 dev）。
4. 仅 dev：在临时工作树中执行预检 lint + TypeScript 构建；如果最新提交失败，则最多回退 10 个提交，以找到最新的可干净构建版本。
5. 变基到所选提交（仅 dev）。
6. 使用仓库的软件包管理器安装依赖。对于 pnpm 检出，更新器会按需引导 `pnpm`（优先通过 `corepack`，然后回退到临时 `npm install pnpm@10`），而不是在 pnpm 工作区内运行 `npm run build`。
7. 构建 + 构建 Control UI。
8. 运行 `openclaw doctor` 作为最终的“安全更新”检查。
9. 将插件同步到当前渠道（`dev` 使用内置 extensions；`stable`/`beta` 使用 npm），并更新通过 npm 安装的插件。
9. 将插件同步到当前渠道（dev 使用内置插件；stable/beta 使用 npm），并更新通过 npm 安装的插件。
如果某个精确固定版本的 npm 插件更新解析到的产物，其完整性
与已存储安装记录不同，`openclaw update` 会中止该插件
产物更新，而不是安装它。只有在验证你信任该新产物之后，
如果一个精确固定版本的 npm 插件更新解析到的产物，其完整性与已存储的安装记录不同，
`openclaw update` 会中止该插件产物更新，而不是安装它。只有在确认你信任该新产物之后，
才应显式重新安装或更新该插件。
如果 pnpm 引导安装仍然失败，更新器现在会提前停止，并给出包管理器特定错误，而不是尝试在检出副本中运行 `npm run build`。
如果 pnpm 引导仍然失败，更新器现在会尽早停止，并报告针对该软件包管理器的特定错误，
而不是尝试在检出中运行 `npm run build`。
## `--update` 简写
`openclaw --update` 会重写为 `openclaw update`（对 shell 和启动脚本很有用）。
## 另请参阅
## 另请参见
- `openclaw doctor`（对于 git 检出副本，会先提供运行更新的选项）
- `openclaw doctor`（在 git 检出上会先提供运行更新）
- [Development channels](/zh-CN/install/development-channels)
- [Updating](/zh-CN/install/updating)
- [CLI reference](/zh-CN/cli)

143
docs/zh-CN/concepts/dreaming.md
View File

@ -2,14 +2,14 @@
read_when:
- 你希望记忆提升能够自动运行
- 你想了解每个 Dreaming 阶段的作用
- 你想在不污染 `MEMORY.md` 的情况下调整整合过程
summary: 通过轻度、深度和 REM 阶段进行后台记忆整合，并附带 Dream Diary
- 你想在不污染 `MEMORY.md` 的情况下调整整合机制
summary: 通过浅层、深层和 REM 阶段进行后台记忆整合，并配有 Dream Diary
title: Dreaming
x-i18n:
generated_at: "2026-04-22T01:53:20Z"
generated_at: "2026-04-23T06:40:32Z"
model: gpt-5.4
provider: openai
source_hash: 050e99bd2b3a18d7d2f02747e3010a7679515098369af5061d0a97b5703fc581
source_hash: 1a44c7568992e60d249d7e424a585318401f678767b9feb7d75c830b01de1cf6
source_path: concepts/dreaming.md
workflow: 15
---
@ -18,112 +18,110 @@ x-i18n:
Dreaming 是 `memory-core` 中的后台记忆整合系统。
它帮助 OpenClaw 将强烈的短期信号转移到持久记忆中，同时
保持整个过程可解释且可审查。
让整个过程可解释、可审查。
Dreaming 是**可选启用**的，默认禁用。
Dreaming 是**可选启用**功能，默认禁用。
## Dreaming 会写入什么
Dreaming 会保留两类输出：
- `memory/.dreams/` 中的**机器状态**（召回存储、阶段信号、摄取检查点、锁）。
- `DREAMS.md`（或现有的 `dreams.md`）中的**人类可读输出**，以及位于 `memory/dreaming/<phase>/YYYY-MM-DD.md` 下的可选阶段报告文件。
- `DREAMS.md`（或已有的 `dreams.md`）中的**人类可读输出**，以及可选的阶段报告文件，位于 `memory/dreaming/<phase>/YYYY-MM-DD.md`。
长期提升仍然只会写入 `MEMORY.md`。
## 阶段模型
Dreaming 使用三个协同工作的阶段：
Dreaming 使用三个协作阶段：
| 阶段 | 目的 | 持久写入 |
| ----- | ----------------------------------------- | ----------------- |
| Light | 整理并暂存近期短期材料 | 否 |
| Deep | 评分并提升持久候选项 | 是（`MEMORY.md`） |
| REM | 反思主题和反复出现的想法 | 否 |
| ----- | ----- | ----- |
| Light | 对近期短期材料进行整理和暂存 | 否 |
| Deep | 对持久候选项进行评分和提升 | 是（`MEMORY.md`） |
| REM | 反思主题和重复出现的想法 | 否 |
这些阶段是内部实现细节，不是单独的用户可配置“模式”。
这些阶段是内部实现细节，并不是单独供用户配置的“模式”。
### Light 阶段
Light 阶段会摄取近期的每日记忆信号和召回轨迹，对其去重，
并暂存候选条目。
并暂存候选行。
- 从短期召回状态、近期每日记忆文件，以及可用时已脱敏的会话转录中读取。
- 当存储包含内联输出时，写入一个受管的 `## Light Sleep` 区块。
- 记录强化信号，供后续 Deep 排名使用。
- 在可用时，从短期召回状态、近期每日记忆文件以及已脱敏的会话转录中读取。
- 当存储包含内联输出时，写入受管理的 `## Light Sleep` 区块。
- 记录强化信号，供后续 Deep 排序使用。
- 绝不会写入 `MEMORY.md`。
### Deep 阶段
Deep 阶段决定哪些内容会成为长期记忆。
Deep 阶段决定什么会成为长期记忆。
- 使用加权评分和阈值门槛对候选项进行排序。
- 需要通过 `minScore`、`minRecallCount` 和 `minUniqueQueries`。
- 在写入前会从实时每日文件中重新提取片段，因此过时或已删除的片段会被跳过。
- 将已提升的条目追加到 `MEMORY.md`。
- 将 `## Deep Sleep` 摘要写入 `DREAMS.md`，并可选择写入 `memory/dreaming/deep/YYYY-MM-DD.md`。
- 要求通过 `minScore`、`minRecallCount` 和 `minUniqueQueries`。
- 在写入前，会从实时每日文件中重新提取片段，因此陈旧或已删除的片段会被跳过。
- 将提升后的条目追加到 `MEMORY.md`。
- 将 `## Deep Sleep` 摘要写入 `DREAMS.md`，并可选写入 `memory/dreaming/deep/YYYY-MM-DD.md`。
### REM 阶段
REM 阶段提取模式和反思信号。
- 根据近期短期轨迹构建主题和反思摘要。
- 当存储包含内联输出时，写入一个受管的 `## REM Sleep` 区块。
- 记录供 Deep 排名使用的 REM 强化信号。
- 当存储包含内联输出时，写入受管理的 `## REM Sleep` 区块。
- 记录供 Deep 排序使用的 REM 强化信号。
- 绝不会写入 `MEMORY.md`。
## 会话转录摄取
Dreaming 可以将已脱敏的会话转录摄取到 Dreaming 语料中。当
转录可用时，它们会与每日记忆信号和召回轨迹一起被送入 Light 阶段。个人和敏感内容会在摄取前被脱敏。
转录可用时，它们会与每日记忆信号和召回轨迹一起输入到 Light 阶段。个人和敏感内容会在摄取前被脱敏。
## Dream Diary
Dreaming 还会在 `DREAMS.md` 中保留一份叙事性的 **Dream Diary**。
当每个阶段积累了足够的材料后，`memory-core` 会尽力运行一次后台
每当某个阶段积累了足够的材料后，`memory-core` 就会运行一次尽力而为的后台
子智能体轮次（使用默认运行时模型），并追加一条简短的日记条目。
这份日记用于在 Dreams UI 中供人阅读，而不是作为提升来源。
由 Dreaming 生成的日记/报告产物会从短期
提升中排除。只有有依据的记忆片段才有资格被提升到
`MEMORY.md` 中。
这份日记用于人在 Dreams UI 中阅读，而不是作为提升来源。
由 Dreaming 生成的日记/报告产物会被排除在短期
提升之外。只有有据可依的记忆片段才有资格提升到
`MEMORY.md`。
此外，还有一条有依据的历史回填通道，用于审查和恢复工作：
此外，还有一条基于事实依据的历史回填通道，用于审查和恢复工作：
- `memory rem-harness --path ... --grounded` 可从历史 `YYYY-MM-DD.md` 记录中预览有依据的日记输出。
- `memory rem-backfill --path ...` 会将可逆的、有依据的日记条目写入 `DREAMS.md`。
- `memory rem-backfill --path ... --stage-short-term` 会将有依据的持久候选项暂存到与常规 Deep 阶段已使用的同一短期证据存储中。
- `memory rem-backfill --rollback` 和 `--rollback-short-term` 会移除这些已暂存的回填产物，而不会触及普通日记条目或实时短期召回。
- `memory rem-harness --path ... --grounded` 可从历史 `YYYY-MM-DD.md` 笔记中预览基于事实依据的日记输出。
- `memory rem-backfill --path ...` 会将可回滚的、基于事实依据的日记条目写入 `DREAMS.md`。
- `memory rem-backfill --path ... --stage-short-term` 会将基于事实依据的持久候选项暂存到与常规 Deep 阶段相同的短期证据存储中。
- `memory rem-backfill --rollback` 和 `--rollback-short-term` 会移除这些暂存的回填产物，而不会影响普通日记条目或实时短期召回。
Control UI 也暴露了相同的日记回填/重置流程，这样你就可以先在 Dreams 场景中检查
结果，再决定这些有依据的候选项
是否值得提升。该场景还会显示一条独立的有依据通道，以便你查看
哪些已暂存的短期条目来自历史回放、哪些已提升
项目由 grounded 流程引导，以及只清除仅基于 grounded 的已暂存条目，而不
触及普通的实时短期状态。
Control UI 也暴露了相同的日记回填/重置流程，因此你可以先在
Dreams 场景中检查结果，再决定这些基于事实依据的候选项
是否值得提升。该场景还会显示一条单独的基于事实依据通道，这样你就可以看到
哪些暂存的短期条目来自历史回放、哪些提升项由 grounded 通道驱动，并且仅清除基于事实依据的暂存条目，而不影响普通实时短期状态。
## Deep 排名信号
## Deep 排序信号
Deep 排名使用六个加权基础信号，再加上阶段强化：
Deep 排序使用六个带权重的基础信号，再加上阶段强化：
| 信号 | 权重 | 说明 |
| ------------------- | ------ | ------------------------------------------------- |
| 频率 | 0.24 | 该条目累积了多少短期信号 |
| 相关性 | 0.30 | 该条目的平均检索质量 |
| 查询多样性 | 0.15 | 让它浮现出来的不同查询/日期上下文 |
| 近期性 | 0.15 | 基于时间衰减的新鲜度分数 |
| 整合度 | 0.10 | 跨日重复出现的强度 |
| 概念丰富度 | 0.06 | 来自片段/路径的概念标签密度 |
| Frequency | 0.24 | 条目累计了多少短期信号 |
| Relevance | 0.30 | 条目的平均检索质量 |
| Query diversity | 0.15 | 使其浮现的不同查询/日期上下文 |
| Recency | 0.15 | 带时间衰减的新鲜度分数 |
| Consolidation | 0.10 | 跨日重复出现的强度 |
| Conceptual richness | 0.06 | 来自片段/路径的概念标签密度 |
来自 Light 和 REM 阶段的命中会基于
`memory/.dreams/phase-signals.json` 增加一个小幅的、按近期性衰减的提升。
Light 和 REM 阶段命中会从
`memory/.dreams/phase-signals.json` 中增加一个带轻微时间衰减的提升值。
## 调度
启用后，`memory-core` 会自动管理一个用于完整 Dreaming
扫描的 cron 任务。每次扫描会按顺序运行各阶段：light -> REM -> deep。
启用后，`memory-core` 会自动管理一个 cron 任务，用于执行完整的 Dreaming
扫描。每次扫描都会按顺序运行各阶段：light -> REM -> deep。
默认频率行为：
默认调度频率行为：
| 设置 | 默认值 |
| -------------------- | ----------- |
@ -149,7 +147,7 @@ Deep 排名使用六个加权基础信号，再加上阶段强化：
}
```
使用自定义扫描频率启用 Dreaming：
启用 Dreaming 并设置自定义扫描频率：
```json
{
@ -189,18 +187,17 @@ openclaw memory promote --limit 5
openclaw memory status --deep
```
手动 `memory promote` 默认使用 Deep 阶段阈值，除非通过
CLI 标志覆盖。
手动执行 `memory promote` 时，默认使用 Deep 阶段阈值，除非通过
CLI 标志进行覆盖。
解释某个特定候选项为什么会或不会被提升：
解释某个特定候选项为何会或不会被提升：
```bash
openclaw memory promote-explain "router vlan"
openclaw memory promote-explain "router vlan" --json
```
预览 REM 反思、候选事实以及 Deep 提升输出，而不
写入任何内容：
在不写入任何内容的情况下，预览 REM 反思、候选事实以及 Deep 提升输出：
```bash
openclaw memory rem-harness
@ -211,42 +208,42 @@ openclaw memory rem-harness --json
所有设置都位于 `plugins.entries.memory-core.config.dreaming` 下。
| 键名 | 默认值 |
| 键 | 默认值 |
| ----------- | ----------- |
| `enabled` | `false` |
| `frequency` | `0 3 * * *` |
阶段策略、阈值和存储行为都是内部实现
阶段策略、阈值和存储行为属于内部实现
细节（不是面向用户的配置）。
完整键名列表请参见 [记忆配置参考](/zh-CN/reference/memory-config#dreaming)。
完整键列表请参见 [记忆配置参考](/zh-CN/reference/memory-config#dreaming)。
## Dreams UI
启用后，Gateway 网关中的 **Dreams** 选项卡会显示：
启用后，Gateway 网关的 **Dreams** 标签页会显示：
- 当前 Dreaming 启用状态
- 阶段级状态和受管扫描是否存在
- 短期、有依据、信号以及今日已提升数量
- 下一次计划运行时间
- 用于已暂存历史回放条目的独立 grounded 场景通道
- 由 `doctor.memory.dreamDiary` 提供支持的可展开 Dream Diary 阅读器
- 阶段级状态和受管理扫描是否存在
- 短期、grounded、信号以及今日已提升计数
- 下次计划运行时间
- 一条单独的 grounded 场景通道，用于显示暂存的历史回放条目
- 一个可展开的 Dream Diary 阅读器，由 `doctor.memory.dreamDiary` 提供支持
## 故障排除
### Dreaming 从不运行（状态显示为 blocked）
受管 Dreaming cron 依赖默认智能体的 heartbeat。如果该智能体的 heartbeat 没有触发，cron 就会排入一个无人消费的系统事件，而 Dreaming 就会静默地不运行。在这种情况下，`openclaw memory status` 和 `/dreaming status` 都会报告 `blocked`，并指出哪个智能体的 heartbeat 是阻塞源。
受管理的 Dreaming cron 依赖默认智能体的心跳。如果该智能体的心跳没有触发，cron 就会排入一个无人消费的系统事件，而 Dreaming 就会静默不运行。在这种情况下，`openclaw memory status` 和 `/dreaming status` 都会报告 `blocked`，并指出是哪一个智能体的心跳导致了阻塞。
两个常见原因：
- 另一个智能体声明了显式的 `heartbeat:` 区块。当 `agents.list` 中任一条目拥有自己的 `heartbeat` 区块时，只有那些智能体会发送 heartbeat —— 默认设置将不再应用于所有智能体，因此默认智能体可能会静默。请将 heartbeat 设置移动到 `agents.defaults.heartbeat`，或在默认智能体上添加显式的 `heartbeat` 区块。参见 [作用域与优先级](/zh-CN/gateway/heartbeat#scope-and-precedence)。
- `heartbeat.every` 为 `0`、为空，或无法解析。cron 没有可用于调度的间隔，因此 heartbeat 实际上已被禁用。请将 `every` 设置为一个正时长，例如 `30m`。参见 [默认值](/zh-CN/gateway/heartbeat#defaults)。
- 另一个智能体声明了显式的 `heartbeat:` 区块。当 `agents.list` 中任意条目拥有自己的 `heartbeat` 区块时，只有这些智能体会发送心跳——默认值不再应用于其他所有智能体，因此默认智能体可能会静默。请将心跳设置移动到 `agents.defaults.heartbeat`，或在默认智能体上添加显式的 `heartbeat` 区块。参见 [作用域与优先级](/zh-CN/gateway/heartbeat#scope-and-precedence)。
- `heartbeat.every` 为 `0`、空值或无法解析。cron 没有可用于调度的间隔，因此心跳实际上被禁用了。请将 `every` 设置为正时长，例如 `30m`。参见 [默认值](/zh-CN/gateway/heartbeat#defaults)。
## 相关内容
- [Heartbeat](/zh-CN/gateway/heartbeat)
- [记忆](/zh-CN/concepts/memory)
- [Memory Search](/zh-CN/concepts/memory-search)
- [memory CLI](/cli/memory)
- [memory CLI](/zh-CN/cli/memory)
- [记忆配置参考](/zh-CN/reference/memory-config)

1531
docs/zh-CN/gateway/configuration-reference.md
View File

File diff suppressed because it is too large Load Diff

939
docs/zh-CN/help/testing.md
View File

File diff suppressed because it is too large Load Diff

201
docs/zh-CN/install/docker.md
View File

@ -1,48 +1,48 @@
---
read_when:
- 你想要一个容器化的 Gateway 网关，而不是本地安装。
- 你正在验证 Docker 流程。
summary: 可选的基于 Docker 的 OpenClaw 设置和新手引导
- 你想要使用容器化的 Gateway 网关，而不是本地安装
- 你正在验证 Docker 流程
summary: OpenClaw 的可选 Docker 安装与新手引导
title: Docker
x-i18n:
generated_at: "2026-04-20T18:29:34Z"
generated_at: "2026-04-23T06:40:50Z"
model: gpt-5.4
provider: openai
source_hash: f8d3e346ca60daa9908aef0846c9052321087af7dd2c919ce79de4d5925136a2
source_hash: 60a874ff7a3c5405ba4437a1d6746f0d9268ba7bd4faf3e20cee6079d5fb68d3
source_path: install/docker.md
workflow: 15
---
# Docker（可选）
Docker **是可选的**。仅当你想要一个容器化的 Gateway 网关，或需要验证 Docker 流程时才使用它。
Docker **是可选的**。只有在你想要容器化的 Gateway 网关，或验证 Docker 流程时才使用它。
## Docker 适合我吗？
- **是**：你想要一个隔离的、可随时丢弃的 Gateway 网关环境，或者希望在没有本地安装的主机上运行 OpenClaw。
- **是**：你想要一个隔离的、可随时丢弃的 Gateway 网关 环境，或想在没有本地安装的主机上运行 OpenClaw。
- **否**：你是在自己的机器上运行，只想要最快的开发循环。请改用常规安装流程。
- **沙箱注意事项**：默认的沙箱后端在启用沙箱隔离时会使用 Docker，但沙箱隔离默认是关闭的，并且**不**要求整个 Gateway 网关都运行在 Docker 中。也提供 SSH 和 OpenShell 沙箱后端。请参阅 [沙箱隔离](/zh-CN/gateway/sandboxing)。
- **沙箱注意事项**：启用沙箱隔离时，默认沙箱后端会使用 Docker，但沙箱隔离默认是关闭的，并且**不**要求整个 Gateway 网关 都运行在 Docker 中。也提供 SSH 和 OpenShell 沙箱后端。参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。
## 前提条件
## 先决条件
- Docker Desktop（或 Docker Engine）+ Docker Compose v2
- 镜像构建至少需要 2 GB 内存（在 1 GB 主机上，`pnpm install` 可能因 OOM 被终止，并返回退出码 137）
- 镜像构建至少需要 2 GB 内存（在 1 GB 主机上，`pnpm install` 可能因 OOM 而以退出码 137 被终止）
- 足够的磁盘空间用于镜像和日志
- 如果在 VPS/公网主机上运行，请查看
[网络暴露的安全加固](/zh-CN/gateway/security)，
特别是 Docker 的 `DOCKER-USER` 防火墙策略。
特别是 Docker `DOCKER-USER` 防火墙策略。
## 容器化 Gateway 网关
<Steps>
<Step title="构建镜像">
在仓库根目录运行设置脚本：
在仓库根目录运行安装脚本：
```bash
./scripts/docker/setup.sh
```
这会在本地构建 Gateway 网关镜像。如果要改用预构建镜像：
这会在本地构建 Gateway 网关 镜像。若要改用预构建镜像：
```bash
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
@ -56,23 +56,23 @@ Docker **是可选的**。仅当你想要一个容器化的 Gateway 网关，或
</Step>
<Step title="完成新手引导">
设置脚本会自动运行新手引导。它将会：
安装脚本会自动运行新手引导。它会：
- 提示你输入提供商 API 密钥
- 生成一个 Gateway 网关令牌并写入 `.env`
- 提示输入提供商 API 密钥
- 生成一个 Gateway 网关 令牌并将其写入 `.env`
- 通过 Docker Compose 启动 Gateway 网关
在设置期间，启动前的新手引导和配置写入会直接通过
`openclaw-gateway` 运行。`openclaw-cli` 用于 Gateway 网关容器已经存在后
你再执行的命令。
在安装期间，启动前的新手引导和配置写入会直接通过
`openclaw-gateway` 执行。`openclaw-cli` 用于在
Gateway 网关 容器已存在之后运行的命令。
</Step>
<Step title="打开控制 UI">
<Step title="打开 Control UI">
在浏览器中打开 `http://127.0.0.1:18789/`，并将已配置的
共享密钥粘贴到“设置”中。设置脚本默认会将一个令牌写入 `.env`；如果你把容器配置切换为密码认证，请改用该密码。
共享密钥粘贴到 Settings 中。安装脚本默认会将令牌写入 `.env`；如果你把容器配置切换为密码认证，请改用该密码。
需要再次获取 URL 吗？
想再次获取 URL？
```bash
docker compose run --rm openclaw-cli dashboard --no-open
@ -84,7 +84,7 @@ Docker **是可选的**。仅当你想要一个容器化的 Gateway 网关，或
使用 CLI 容器添加消息渠道：
```bash
# WhatsApp（QR）
# WhatsApp（二维码）
docker compose run --rm openclaw-cli channels login
# Telegram
@ -101,7 +101,7 @@ Docker **是可选的**。仅当你想要一个容器化的 Gateway 网关，或
### 手动流程
如果你更喜欢自己逐步执行，而不是使用设置脚本：
如果你更喜欢自行运行每个步骤，而不是使用安装脚本：
```bash
docker build -t openclaw:local -f Dockerfile .
@ -114,30 +114,30 @@ docker compose up -d openclaw-gateway
<Note>
请从仓库根目录运行 `docker compose`。如果你启用了 `OPENCLAW_EXTRA_MOUNTS`
或 `OPENCLAW_HOME_VOLUME`，设置脚本会写入 `docker-compose.extra.yml`；
请使用 `-f docker-compose.yml -f docker-compose.extra.yml` 将其一并包含。
或 `OPENCLAW_HOME_VOLUME`，安装脚本会写入 `docker-compose.extra.yml`；
请通过 `-f docker-compose.yml -f docker-compose.extra.yml` 将其包含进来。
</Note>
<Note>
由于 `openclaw-cli` 共享 `openclaw-gateway` 的网络命名空间，它是一个
启动后的工具。在执行 `docker compose up -d openclaw-gateway` 之前，请通过
带有 `--no-deps --entrypoint node` 的 `openclaw-gateway` 来运行新手引导
和设置阶段的配置写入。
启动后工具。在 `docker compose up -d openclaw-gateway` 之前，请通过带有
`--no-deps --entrypoint node` 的 `openclaw-gateway`
运行新手引导和安装时配置写入。
</Note>
### 环境变量
设置脚本接受以下可选环境变量：
安装脚本支持以下可选环境变量：
| Variable | Purpose |
| ------------------------------ | ---------------------------------------------------------------- |
| `OPENCLAW_IMAGE` | 使用远程镜像，而不是在本地构建 |
| `OPENCLAW_DOCKER_APT_PACKAGES` | 在构建期间安装额外的 apt 软件包（以空格分隔） |
| `OPENCLAW_EXTENSIONS` | 在构建时预安装扩展依赖（以空格分隔的名称） |
| `OPENCLAW_EXTRA_MOUNTS` | 额外的主机 bind mount（以逗号分隔的 `source:target[:opts]`） |
| `OPENCLAW_HOME_VOLUME` | 将 `/home/node` 持久化到一个具名 Docker volume 中 |
| `OPENCLAW_SANDBOX` | 选择启用沙箱引导（`1`、`true`、`yes`、`on`） |
| `OPENCLAW_DOCKER_SOCKET` | 覆盖 Docker socket 路径 |
| 变量 | 用途 |
| ------------------------------ | --------------------------------------------------------------- |
| `OPENCLAW_IMAGE` | 使用远程镜像，而不是在本地构建 |
| `OPENCLAW_DOCKER_APT_PACKAGES` | 在构建期间安装额外的 apt 软件包（以空格分隔） |
| `OPENCLAW_EXTENSIONS` | 在构建时预安装插件依赖（以空格分隔的名称） |
| `OPENCLAW_EXTRA_MOUNTS` | 额外的宿主机绑定挂载（以逗号分隔的 `source:target[:opts]`） |
| `OPENCLAW_HOME_VOLUME` | 将 `/home/node` 持久化到命名 Docker 卷中 |
| `OPENCLAW_SANDBOX` | 选择启用沙箱引导（`1`、`true`、`yes`、`on`） |
| `OPENCLAW_DOCKER_SOCKET` | 覆盖 Docker socket 路径 |
### 健康检查
@ -148,9 +148,9 @@ curl -fsS http://127.0.0.1:18789/healthz # 存活性
curl -fsS http://127.0.0.1:18789/readyz # 就绪性
```
Docker 镜像内置了一个 `HEALTHCHECK`，会 ping `/healthz`。
Docker 镜像包含一个内置的 `HEALTHCHECK`，会探测 `/healthz`。
如果检查持续失败，Docker 会将容器标记为 `unhealthy`，
编排系统可以重启或替换它。
编排系统就可以重启或替换它。
需要认证的深度健康快照：
@ -160,53 +160,52 @@ docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLA
### LAN 与 loopback
`scripts/docker/setup.sh` 默认设置 `OPENCLAW_GATEWAY_BIND=lan`，这样通过 Docker 端口发布时，主机就可以访问
`http://127.0.0.1:18789`。
`scripts/docker/setup.sh` 默认将 `OPENCLAW_GATEWAY_BIND=lan`，以便宿主机能够通过
Docker 端口发布访问 `http://127.0.0.1:18789`。
- `lan`（默认）：主机浏览器和主机 CLI 都可以访问已发布的 Gateway 网关端口。
- `lan`（默认）：宿主机浏览器和宿主机 CLI 都可以访问已发布的 Gateway 网关 端口。
- `loopback`：只有容器网络命名空间内的进程才能直接访问
Gateway 网关。
<Note>
请在 `gateway.bind` 中使用 bind mode 的值（`lan` / `loopback` / `custom` /
`tailnet` / `auto`），不要使用像 `0.0.0.0` 或 `127.0.0.1` 这样的主机别名。
请在 `gateway.bind` 中使用绑定模式值（`lan` / `loopback` / `custom` /
`tailnet` / `auto`），而不是宿主机别名，如 `0.0.0.0` 或 `127.0.0.1`。
</Note>
### 存储与持久化
Docker Compose 会将 `OPENCLAW_CONFIG_DIR` bind-mount 到 `/home/node/.openclaw`，
并将 `OPENCLAW_WORKSPACE_DIR` bind-mount 到 `/home/node/.openclaw/workspace`，因此这些路径在容器被替换后
仍然会保留。
Docker Compose 会将 `OPENCLAW_CONFIG_DIR` 绑定挂载到 `/home/node/.openclaw`，
并将 `OPENCLAW_WORKSPACE_DIR` 绑定挂载到 `/home/node/.openclaw/workspace`，因此这些路径在容器替换后仍会保留。
这个已挂载的配置目录也是 OpenClaw 存放以下内容的位置：
这个已挂载的配置目录是 OpenClaw 存放以下内容的位置：
- 用于行为配置的 `openclaw.json`
- 用于存储提供商 OAuth/API 密钥认证信息的 `agents/<agentId>/agent/auth-profiles.json`
- 用于保存基于环境变量的运行时密钥（例如 `OPENCLAW_GATEWAY_TOKEN`）的 `.env`
- 用于存储提供商 OAuth/API 密钥认证的 `agents/<agentId>/agent/auth-profiles.json`
- 用于基于环境变量的运行时密钥（如 `OPENCLAW_GATEWAY_TOKEN`）的 `.env`
有关 VM 部署中完整的持久化细节，请参阅
[Docker VM Runtime - 数据会持久保存到哪里](/zh-CN/install/docker-vm-runtime#what-persists-where)。
有关 VM 部署中持久化细节的完整说明，请参见
[Docker VM Runtime - What persists where](/zh-CN/install/docker-vm-runtime#what-persists-where)。
**磁盘增长热点：**请关注 `media/`、会话 JSONL 文件、`cron/runs/*.jsonl`，
以及 `/tmp/openclaw/` 下的滚动文件日志。
### Shell 辅助工具（可选）
### Shell 帮助脚本（可选）
为了更方便地进行日常 Docker 管理，请安装 `ClawDock`：
为了更轻松地进行日常 Docker 管理，请安装 `ClawDock`：
```bash
mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
```
如果你之前是通过旧的 `scripts/shell-helpers/clawdock-helpers.sh` 原始路径安装 ClawDock，请重新运行上面的安装命令，以便让你的本地辅助文件跟踪新位置。
如果你之前是从旧路径 `scripts/shell-helpers/clawdock-helpers.sh` 安装 ClawDock 的原始文件，请重新运行上面的安装命令，以便你的本地帮助文件跟踪新位置。
然后你可以使用 `clawdock-start`、`clawdock-stop`、`clawdock-dashboard` 等命令。运行
`clawdock-help` 可查看所有命令。
完整辅助指南请参阅 [ClawDock](/zh-CN/install/clawdock)。
然后使用 `clawdock-start`、`clawdock-stop`、`clawdock-dashboard` 等命令。
运行 `clawdock-help` 可查看所有命令。
完整帮助指南请参见 [ClawDock](/zh-CN/install/clawdock)。
<AccordionGroup>
<Accordion title="为 Docker Gateway 网关启用智能体沙箱">
<Accordion title="为 Docker Gateway 网关 启用智能体沙箱">
```bash
export OPENCLAW_SANDBOX=1
./scripts/docker/setup.sh
@ -220,7 +219,7 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
./scripts/docker/setup.sh
```
只有在沙箱前提条件检查通过后，脚本才会挂载 `docker.sock`。如果
脚本只有在沙箱先决条件通过后才会挂载 `docker.sock`。如果
沙箱设置无法完成，脚本会将 `agents.defaults.sandbox.mode`
重置为 `off`。
@ -238,14 +237,14 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
<Accordion title="共享网络安全说明">
`openclaw-cli` 使用 `network_mode: "service:openclaw-gateway"`，因此 CLI
命令可以通过 `127.0.0.1` 访问 Gateway 网关。请将此视为一个共享的
信任边界。compose 配置为 `openclaw-cli` 去掉了 `NET_RAW`/`NET_ADMIN`，并启用了
命令可以通过 `127.0.0.1` 访问 Gateway 网关。请将此视为共享的
信任边界。compose 配置对 `openclaw-cli` 去除了 `NET_RAW`/`NET_ADMIN`，并启用了
`no-new-privileges`。
</Accordion>
<Accordion title="权限与 EACCES">
镜像以 `node`（uid 1000）身份运行。如果你在
`/home/node/.openclaw` 上看到权限错误，请确保主机 bind mount 归 uid 1000 所有：
`/home/node/.openclaw` 上看到权限错误，请确保宿主机绑定挂载归 uid 1000 所有：
```bash
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
@ -253,9 +252,9 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
</Accordion>
<Accordion title="更快的重建">
请安排你的 Dockerfile，使依赖层可以被缓存。这样可以避免在 lockfile 未变化时
反复运行 `pnpm install`：
<Accordion title="更快的重新构建">
请安排好 Dockerfile 的顺序，以便缓存依赖层。这样可避免在锁文件未变化时
重复运行 `pnpm install`：
```dockerfile
FROM node:24-bookworm
@ -277,57 +276,59 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
</Accordion>
<Accordion title="高级容器选项">
默认镜像以安全优先为设计原则，并以非 root 用户 `node` 运行。如果你想要一个功能更完整的容器：
<Accordion title="高级用户容器选项">
默认镜像以安全优先为设计目标，并以非 root 的 `node` 身份运行。若需要更
完整功能的容器：
1. **持久化 `/home/node`**：`export OPENCLAW_HOME_VOLUME="openclaw_home"`
2. **预装系统依赖**：`export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"`
2. **烘焙系统依赖**：`export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"`
3. **安装 Playwright 浏览器**：
```bash
docker compose run --rm openclaw-cli \
node /app/node_modules/playwright-core/cli.js install chromium
```
4. **持久化浏览器下载内容**：设置
`PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright`，并使用
`PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright` 并使用
`OPENCLAW_HOME_VOLUME` 或 `OPENCLAW_EXTRA_MOUNTS`。
</Accordion>
<Accordion title="OpenAI Codex OAuth（无头 Docker）">
如果你在向导中选择 OpenAI Codex OAuth，它会打开一个浏览器 URL。在
Docker 或无头环境中，请复制你最终跳转到的完整重定向 URL，并将其粘贴回
向导中以完成认证。
Docker 或无头环境中，请复制你最终到达的完整重定向 URL，并将其粘贴回
向导以完成认证。
</Accordion>
<Accordion title="基础镜像元数据">
主 Docker 镜像使用 `node:24-bookworm`，并发布 OCI 基础镜像
注解，包括 `org.opencontainers.image.base.name`、
`org.opencontainers.image.source` 等。请参阅
`org.opencontainers.image.source` 等。参见
[OCI image annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md)。
</Accordion>
</AccordionGroup>
### 在 VPS 上运行？
请参阅 [Hetzner（Docker VPS）](/zh-CN/install/hetzner) 和
[Docker VM Runtime](/zh-CN/install/docker-vm-runtime)，了解共享 VM 部署步骤，
包括二进制预构建、持久化和更新。
有关共享 VM 部署步骤，包括二进制预烘焙、持久化和更新，
请参见 [Hetzner (Docker VPS)](/zh-CN/install/hetzner) 和
[Docker VM Runtime](/zh-CN/install/docker-vm-runtime)。
## 智能体沙箱
当启用 `agents.defaults.sandbox` 并使用 Docker 后端时，Gateway 网关会在隔离的 Docker
容器中运行智能体工具执行（shell、文件读写等），而 Gateway 网关本身仍然保留在主机上。这样你就能在不将整个
Gateway 网关容器化的前提下，为不受信任或多租户的智能体会话建立一道硬隔离墙。
当使用 Docker 后端启用 `agents.defaults.sandbox` 时，Gateway 网关
会在隔离的 Docker 容器中运行智能体工具执行（shell、文件读/写等），
而 Gateway 网关 本身仍运行在宿主机上。这为不受信任或多租户的智能体会话
提供了一道硬隔离边界，而无需将整个 Gateway 网关 容器化。
沙箱范围可以是每个智能体（默认）、每个会话，或共享。每种范围
都会获得各自挂载到 `/workspace` 的工作区。你还可以配置
工具允许/拒绝策略、网络隔离、资源限制以及浏览器容器。
沙箱范围可以是按智能体（默认）、按会话，或共享。每种范围
都会获得各自挂载在 `/workspace` 的工作区。你还可以配置
工具允许/拒绝策略、网络隔离、资源限制和浏览器容器。
有关完整配置、镜像、安全说明和多智能体配置文件，请参阅：
有关完整配置、镜像、安全说明和多智能体配置文件，请参见：
- [沙箱隔离](/zh-CN/gateway/sandboxing) -- 完整的沙箱参考
- [OpenShell](/zh-CN/gateway/openshell) -- 对沙箱容器的交互式 shell 访问
- [多智能体沙箱与工具](/zh-CN/tools/multi-agent-sandbox-tools) -- 按智能体覆盖
- [Multi-Agent Sandbox and Tools](/zh-CN/tools/multi-agent-sandbox-tools) -- 按智能体覆盖
### 快速启用
@ -354,29 +355,29 @@ scripts/sandbox-setup.sh
<AccordionGroup>
<Accordion title="镜像缺失或沙箱容器未启动">
使用
请使用
[`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh)
构建沙箱镜像，或将 `agents.defaults.sandbox.docker.image` 设置为你的自定义镜像。
容器会按需为每个会话自动创建。
</Accordion>
<Accordion title="沙箱中的权限错误">
将 `docker.user` 设置为与你挂载的工作区所有权匹配的 UID:GID，
将 `docker.user` 设置为与你挂载工作区所有权匹配的 UID:GID，
或对工作区文件夹执行 chown。
</Accordion>
<Accordion title="在沙箱中找不到自定义工具">
OpenClaw 使用 `sh -lc`（登录 shell）运行命令，这会加载
`/etc/profile`，并且可能重置 PATH。请设置 `docker.env.PATH` 以便在前面添加你的
自定义工具路径，或者在你的 Dockerfile 中向 `/etc/profile.d/` 添加脚本。
`/etc/profile`，并且可能会重置 PATH。请设置 `docker.env.PATH` 以预先添加你的
自定义工具路径，或在你的 Dockerfile 中将脚本添加到 `/etc/profile.d/` 下。
</Accordion>
<Accordion title="镜像构建期间因 OOM 被终止（退出码 137）">
VM 至少需要 2 GB 内存。请使用更大的机器规格后重试。
虚拟机至少需要 2 GB 内存。请使用更大的机器规格后重试。
</Accordion>
<Accordion title="Control UI 中出现 Unauthorized 或需要配对">
获取一个新的仪表板链接，并批准该浏览器设备：
<Accordion title="Control UI 中显示 Unauthorized 或需要配对">
获取一个新的 dashboard 链接并批准浏览器设备：
```bash
docker compose run --rm openclaw-cli dashboard --no-open
@ -384,12 +385,12 @@ scripts/sandbox-setup.sh
docker compose run --rm openclaw-cli devices approve <requestId>
```
更多细节： [Dashboard](/web/dashboard)、[Devices](/cli/devices)。
更多细节： [Dashboard](/zh-CN/web/dashboard)、[Devices](/zh-CN/cli/devices)。
</Accordion>
<Accordion title="Gateway 网关目标显示为 ws://172.x.x.x，或从 Docker CLI 出现配对错误">
重置 Gateway 网关模式和绑定：
<Accordion title="Gateway 网关 目标显示为 ws://172.x.x.x，或从 Docker CLI 出现配对错误">
重置 Gateway 网关 模式和绑定：
```bash
docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]'
@ -401,8 +402,8 @@ scripts/sandbox-setup.sh
## 相关内容
- [安装概览](/zh-CN/install) — 所有安装方式
- [Install Overview](/zh-CN/install) — 所有安装方式
- [Podman](/zh-CN/install/podman) — Docker 的 Podman 替代方案
- [ClawDock](/zh-CN/install/clawdock) — Docker Compose 社区配置
- [更新](/zh-CN/install/updating) — 让 OpenClaw 保持最新
- [配置](/zh-CN/gateway/configuration) — 安装后的 Gateway 网关配置
- [ClawDock](/zh-CN/install/clawdock) — Docker Compose 社区安装方案
- [Updating](/zh-CN/install/updating) — 让 OpenClaw 保持最新
- [Configuration](/zh-CN/gateway/configuration) — 安装后的 Gateway 网关 配置

48
docs/zh-CN/install/hostinger.md
View File

@ -1,15 +1,15 @@
---
read_when:
- 在 Hostinger 上设置 OpenClaw
- 正在寻找适用于 OpenClaw 的托管 VPS
- 正在寻找适合 OpenClaw 的托管 VPS
- 使用 Hostinger 一键安装 OpenClaw
summary: 在 Hostinger 上托管 OpenClaw
title: Hostinger
x-i18n:
generated_at: "2026-04-13T13:14:20Z"
generated_at: "2026-04-23T06:41:03Z"
model: gpt-5.4
provider: openai
source_hash: cf173cdcf6344f8ee22e839a27f4e063a3a102186f9acc07c4a33d4794e2c034
source_hash: 1ee70d24fd1c3a6de503fc967d7e726d701f84cc6717fe7a3bc65a6a28e386ea
source_path: install/hostinger.md
workflow: 15
---
@ -18,26 +18,26 @@ x-i18n:
通过 **一键安装** 托管部署或 **VPS** 安装，在 [Hostinger](https://www.hostinger.com/openclaw) 上运行持久化的 OpenClaw Gateway 网关。
## 前提条件
## 先决条件
- Hostinger 账户（[注册](https://www.hostinger.com/openclaw)）
- 大约 5-10 分钟
- 大约 5 - 10 分钟
## 选项 A：一键安装 OpenClaw
## 方案 A：一键安装 OpenClaw
最快的入门方式。Hostinger 会处理基础设施、Docker 和自动更新。
最快的入门方式。Hostinger 会负责基础设施、Docker 和自动更新。
<Steps>
<Step title="购买并启动">
1. 在 [Hostinger OpenClaw 页面](https://www.hostinger.com/openclaw) 上，选择一个托管 OpenClaw 套餐并完成结账。
1. 前往 [Hostinger OpenClaw 页面](https://www.hostinger.com/openclaw)，选择一个托管 OpenClaw 套餐并完成结账。
<Note>
在结账过程中，你可以选择 **Ready-to-Use AI** 积分，这些积分已预先购买，并会立即在 OpenClaw 内集成——无需其他提供商的外部账户或 API 密钥。你可以立刻开始聊天。或者，你也可以在设置过程中提供你自己的 Anthropic、OpenAI、Google Gemini 或 xAI 密钥。
在结账过程中，你可以选择 **Ready-to-Use AI** 点数，这些点数会预先购买并立即集成到 OpenClaw 中——无需其他提供商的外部账户或 API 密钥。你可以立即开始聊天。或者，你也可以在设置期间提供自己来自 Anthropic、OpenAI、Google Gemini 或 xAI 的密钥。
</Note>
</Step>
<Step title="选择一个消息渠道">
<Step title="选择消息渠道">
选择一个或多个要连接的渠道：
- **WhatsApp** —— 扫描设置向导中显示的二维码。
@ -46,21 +46,21 @@ x-i18n:
</Step>
<Step title="完成安装">
点击 **Finish** 以部署实例。准备就绪后，可从 hPanel 中的 **OpenClaw Overview** 访问 OpenClaw 仪表板。
点击 **Finish** 来部署实例。实例准备就绪后，可从 hPanel 中的 **OpenClaw Overview** 访问 OpenClaw 控制面板。
</Step>
</Steps>
## 选项 B：在 VPS 上运行 OpenClaw
## 方案 B：在 VPS 上运行 OpenClaw
对你的服务器拥有更多控制权。Hostinger 会通过 Docker 在你的 VPS 上部署 OpenClaw，而你可通过 hPanel 中的 **Docker Manager** 进行管理。
你可以对服务器拥有更多控制权。Hostinger 会通过 Docker 在你的 VPS 上部署 OpenClaw，而你可以通过 hPanel 中的 **Docker Manager** 进行管理。
<Steps>
<Step title="购买 VPS">
1. 在 [Hostinger OpenClaw 页面](https://www.hostinger.com/openclaw) 上，选择一个 OpenClaw on VPS 套餐并完成结账。
1. 前往 [Hostinger OpenClaw 页面](https://www.hostinger.com/openclaw)，选择一个 VPS 上的 OpenClaw 套餐并完成结账。
<Note>
你可以在结账过程中选择 **Ready-to-Use AI** 积分——这些积分已预先购买，并会立即在 OpenClaw 内集成，因此你无需任何外部账户或其他提供商的 API 密钥即可开始聊天。
你可以在结账时选择 **Ready-to-Use AI** 点数——这些点数会预先购买并立即集成到 OpenClaw 中，因此你无需任何外部账户或其他提供商的 API 密钥即可开始聊天。
</Note>
</Step>
@ -68,32 +68,32 @@ x-i18n:
<Step title="配置 OpenClaw">
VPS 配置完成后，填写以下配置字段：
- **Gateway token** —— 自动生成；请保存以便后续使用。
- **WhatsApp number** —— 带国家区号的你的号码（可选）。
- **Gateway token** —— 自动生成；请保存以备后用。
- **WhatsApp number** —— 你的带国家区号的号码（可选）。
- **Telegram bot token** —— 来自 [BotFather](https://t.me/BotFather)（可选）。
- **API keys** —— 仅当你在结账时未选择 Ready-to-Use AI 积分时才需要。
- **API keys** —— 仅当你在结账时未选择 Ready-to-Use AI 点数时才需要。
</Step>
<Step title="启动 OpenClaw">
点击 **Deploy**。运行后，在 hPanel 中点击 **Open** 打开 OpenClaw 仪表板。
点击 **Deploy**。运行后，可在 hPanel 中点击 **Open** 打开 OpenClaw 控制面板。
</Step>
</Steps>
日志、重启和更新均可直接在 hPanel 的 Docker Manager 界面中管理。要更新，请在 Docker Manager 中点击 **Update**，这将拉取最新镜像。
日志、重启和更新都可直接在 hPanel 的 Docker Manager 界面中管理。要更新，请在 Docker Manager 中点击 **Update**，这会拉取最新镜像。
## 验证你的设置
在你已连接的渠道中向你的助手发送“Hi”。OpenClaw 会回复你，并引导你完成初始偏好设置。
在你已连接的渠道中，向你的助手发送“Hi”。OpenClaw 会回复，并引导你完成初始偏好设置。
## 故障排除
**仪表板无法加载** —— 等待几分钟，让容器完成配置。检查 hPanel 中 Docker Manager 的日志。
**控制面板无法加载** —— 等待几分钟，让容器完成配置。检查 hPanel 中 Docker Manager 的日志。
**Docker 容器持续重启** —— 打开 Docker Manager 日志，查看是否存在配置错误（缺少令牌、API 密钥无效）。
**Docker 容器不断重启** —— 打开 Docker Manager 日志，查看是否存在配置错误（缺少令牌、API 密钥无效）。
**Telegram 机器人没有响应** —— 直接通过 Telegram 将你的配对代码消息发送到 OpenClaw 聊天中，以完成连接。
**Telegram 机器人没有响应** —— 直接从 Telegram 将你的配对代码消息作为消息发送到 OpenClaw 聊天中，以完成连接。
## 后续步骤

44
docs/zh-CN/install/northflank.mdx
View File

@ -1,49 +1,51 @@
---
read_when:
- 将 OpenClaw 部署到 Northflank
- 你想要一种支持基于浏览器控制 UI 的一键云部署方式
summary: 使用一键模板在 Northflank 上部署 OpenClaw
- 你希望通过一键云部署获得基于浏览器的 Control UI
summary: 通过一键模板在 Northflank 上部署 OpenClaw
title: Northflank
x-i18n:
generated_at: "2026-04-05T08:28:00Z"
generated_at: "2026-04-23T06:41:06Z"
model: gpt-5.4
provider: openai
source_hash: 6b659607621ad2b38e61644f41cf3e5ae1a32761469223c460952a832d3b93fe
source_hash: 5610e076b09d50c23186f1f8db16c039c99d287c34ef6fd71d4272bc527b0388
source_path: install/northflank.mdx
workflow: 15
---
使用一键模板在 Northflank 上部署 OpenClaw，并通过网页控制 UI 访问它。
# Northflank
通过一键模板在 Northflank 上部署 OpenClaw，并通过网页 Control UI 访问它。
这是最简单的“服务器上无需终端”路径：Northflank 会为你运行 Gateway 网关。
## 如何开始
1. 点击 [Deploy OpenClaw](https://northflank.com/stacks/deploy-openclaw) 打开模板。
2. 如果你还没有账户，请先在 [Northflank](https://app.northflank.com/signup) 上创建一个。
3. 点击 **Deploy OpenClaw now**。
4. 设置必需的环境变量：`OPENCLAW_GATEWAY_TOKEN`（请使用高强度随机值）。
5. 点击 **Deploy stack** 以构建并运行 OpenClaw 模板。
6. 等待部署完成，然后点击 **View resources**。
1. 点击 [部署 OpenClaw](https://northflank.com/stacks/deploy-openclaw) 打开模板。
2. 如果你还没有账号，请先在 [Northflank 注册账号](https://app.northflank.com/signup)。
3. 点击 **立即部署 OpenClaw**。
4. 设置必需的环境变量：`OPENCLAW_GATEWAY_TOKEN`（请使用强随机值）。
5. 点击 **部署堆栈** 以构建并运行 OpenClaw 模板。
6. 等待部署完成，然后点击 **查看资源**。
7. 打开 OpenClaw 服务。
8. 打开位于 `/openclaw` 的公开 OpenClaw URL，并使用已配置的共享密钥连接。此模板默认使用 `OPENCLAW_GATEWAY_TOKEN`；如果你将其替换为 password 认证，请改用该密码。
8. 打开公开的 OpenClaw URL，并访问 `/openclaw`，然后使用已配置的共享密钥连接。此模板默认使用 `OPENCLAW_GATEWAY_TOKEN`；如果你改用密码认证，请改用该密码。
## 你将获得
- 托管的 OpenClaw Gateway 网关 + 控制 UI
- 托管的 OpenClaw Gateway 网关 + Control UI
- 通过 Northflank Volume（`/data`）提供的持久化存储，因此 `openclaw.json`、
每个智能体的 `auth-profiles.json`、渠道/provider 状态、会话以及
每个智能体的 `auth-profiles.json`、渠道/提供商状态、会话以及
工作区都能在重新部署后保留
## 连接一个渠道
使用位于 `/openclaw` 的控制 UI，或通过 SSH 运行 `openclaw onboard` 获取渠道设置说明：
使用 `/openclaw` 下的 Control UI，或通过 SSH 运行 `openclaw onboard` 获取渠道设置说明：
- [Telegram](/channels/telegram)（最快——只需要一个 bot token）
- [Discord](/channels/discord)
- [所有渠道](/channels)
- [Telegram](/zh-CN/channels/telegram)（最快 —— 只需要一个机器人令牌）
- [Discord](/zh-CN/channels/discord)
- [所有渠道](/zh-CN/channels)
## 后续步骤
- 设置消息渠道：[Channels](/channels)
- 配置 Gateway 网关：[Gateway 配置](/gateway/configuration)
- 保持 OpenClaw 为最新版本：[更新](/install/updating)
- 设置消息渠道：[Channels](/zh-CN/channels)
- 配置 Gateway 网关：[Gateway 配置](/zh-CN/gateway/configuration)
- 保持 OpenClaw 为最新版本：[更新](/zh-CN/install/updating)

126
docs/zh-CN/install/podman.md
View File

@ -1,34 +1,34 @@
---
read_when:
- 你想使用 Podman 而不是 Docker 来运行容器化 Gateway 网关
summary: 在 rootless Podman 容器中运行 OpenClaw
- 你希望使用 Podman 而不是 Docker 来运行容器化的 Gateway 网关
summary: 在无 root 的 Podman 容器中运行 OpenClaw
title: Podman
x-i18n:
generated_at: "2026-04-05T08:28:26Z"
generated_at: "2026-04-23T06:41:16Z"
model: gpt-5.4
provider: openai
source_hash: 6cb06e2d85b4b0c8a8c6e69c81f629c83b447cbcbb32e34b7876a1819c488020
source_hash: df478ad4ac63b363c86a53bc943494b32602abfaad8576c5e899e77f7699a533
source_path: install/podman.md
workflow: 15
---
# Podman
在由你当前非 root 用户管理的 rootless Podman 容器中运行 OpenClaw Gateway 网关。
在无 root 的 Podman 容器中运行 OpenClaw Gateway 网关，并由你当前的非 root 用户进行管理。
推荐的模型是：
- Podman 运行 gateway 容器。
- Podman 运行 Gateway 网关容器。
- 你主机上的 `openclaw` CLI 是控制平面。
- 持久化状态默认保存在主机的 `~/.openclaw` 下。
- 持久状态默认存储在主机上的 `~/.openclaw` 下。
- 日常管理使用 `openclaw --container <name> ...`，而不是 `sudo -u openclaw`、`podman exec` 或单独的服务用户。
## 前置条件
- 以 rootless 模式运行的 **Podman**
- 已安装在主机上的 **OpenClaw CLI**
- **可选：**如果你想要由 Quadlet 管理自动启动，则需要 `systemd --user`
- **可选：**只有当你想在无头主机上使用 `loginctl enable-linger "$(whoami)"` 以实现开机持久化时，才需要 `sudo`
- 以无 root 模式运行的 **Podman**
- 已在主机上安装 **OpenClaw CLI**
- **可选：** 如果你希望使用 Quadlet 管理自动启动，需要 `systemd --user`
- **可选：** 仅当你希望在无头主机上使用 `loginctl enable-linger "$(whoami)"` 实现开机持久运行时，才需要 `sudo`
## 快速开始
@ -46,16 +46,16 @@ x-i18n:
</Step>
<Step title="从主机 CLI 管理正在运行的容器">
设置 `OPENCLAW_CONTAINER=openclaw`，然后在主机上使用普通的 `openclaw` 命令。
设置 `OPENCLAW_CONTAINER=openclaw`，然后从主机使用普通的 `openclaw` 命令。
</Step>
</Steps>
设置细节：
设置详情：
- `./scripts/podman/setup.sh` 默认会在你的 rootless Podman 存储中构建 `openclaw:local`，或者如果你已设置 `OPENCLAW_IMAGE` / `OPENCLAW_PODMAN_IMAGE`，则会使用它们。
- 如果缺失，它会创建 `~/.openclaw/openclaw.json`，并设定 `gateway.mode: "local"`。
- 如果缺失，它会创建带有 `OPENCLAW_GATEWAY_TOKEN` 的 `~/.openclaw/.env`。
- 对于手动启动，辅助脚本只会从 `~/.openclaw/.env` 中读取一小部分与 Podman 相关的允许列表键，并向容器传递显式运行时环境变量；它不会把完整 env 文件交给 Podman。
- `./scripts/podman/setup.sh` 默认会在你的无 root Podman 存储中构建 `openclaw:local`，或者如果你设置了 `OPENCLAW_IMAGE` / `OPENCLAW_PODMAN_IMAGE`，则使用它指定的镜像。
- 如果 `~/.openclaw/openclaw.json` 不存在，它会创建该文件，并写入 `gateway.mode: "local"`。
- 如果 `~/.openclaw/.env` 不存在，它会创建该文件，并写入 `OPENCLAW_GATEWAY_TOKEN`。
- 对于手动启动，辅助脚本只会从 `~/.openclaw/.env` 读取一个较小的 Podman 相关键 allowlist，并将显式运行时环境变量传递给容器；它不会把整个 env 文件交给 Podman。
由 Quadlet 管理的设置：
@ -63,15 +63,15 @@ x-i18n:
./scripts/podman/setup.sh --quadlet
```
Quadlet 是仅限 Linux 的选项，因为它依赖 systemd 用户服务。
Quadlet 仅适用于 Linux，因为它依赖 systemd 用户服务。
你也可以设置 `OPENCLAW_PODMAN_QUADLET=1`。
可选的构建/设置环境变量：
- `OPENCLAW_IMAGE` 或 `OPENCLAW_PODMAN_IMAGE` —— 使用现有/已拉取的镜像，而不是构建 `openclaw:local`
- `OPENCLAW_DOCKER_APT_PACKAGES` —— 在构建镜像时安装额外 apt 软件包
- `OPENCLAW_EXTENSIONS` —— 在构建时预安装扩展依赖
- `OPENCLAW_IMAGE` 或 `OPENCLAW_PODMAN_IMAGE` —— 使用已有/已拉取的镜像，而不是构建 `openclaw:local`
- `OPENCLAW_DOCKER_APT_PACKAGES` —— 在镜像构建期间安装额外的 apt 软件包
- `OPENCLAW_EXTENSIONS` —— 在构建时预安装插件依赖
容器启动：
@ -79,7 +79,7 @@ Quadlet 是仅限 Linux 的选项，因为它依赖 systemd 用户服务。
./scripts/run-openclaw-podman.sh launch
```
该脚本会以你当前的 uid/gid 配合 `--userns=keep-id` 启动容器，并将你的 OpenClaw 状态以 bind mount 的方式挂载进容器。
该脚本会以你当前的 uid/gid，使用 `--userns=keep-id` 启动容器，并将你的 OpenClaw 状态目录 bind-mount 到容器中。
新手引导：
@ -87,7 +87,7 @@ Quadlet 是仅限 Linux 的选项，因为它依赖 systemd 用户服务。
./scripts/run-openclaw-podman.sh launch setup
```
然后打开 `http://127.0.0.1:18789/`，并使用 `~/.openclaw/.env` 中的 token。
然后打开 `http://127.0.0.1:18789/`，并使用 `~/.openclaw/.env` 中的令牌。
主机 CLI 默认值：
@ -95,39 +95,39 @@ Quadlet 是仅限 Linux 的选项，因为它依赖 systemd 用户服务。
export OPENCLAW_CONTAINER=openclaw
```
然后像下面这样的命令就会自动在该容器内运行：
这样，下面这些命令就会自动在该容器内运行：
```bash
openclaw dashboard --no-open
openclaw gateway status --deep # 包含额外服务扫描
openclaw gateway status --deep # includes extra service scan
openclaw doctor
openclaw channels login
```
在 macOS 上，Podman machine 可能会让浏览器在 gateway 看来不再是本地访问。
如果启动后 Control UI 报告设备认证错误，请参考
在 macOS 上，Podman machine 可能会让浏览器在 Gateway 网关看来不像本地访问。
如果启动后 Control UI 报告设备认证错误，请参阅
[Podman + Tailscale](#podman--tailscale) 中的 Tailscale 指南。
<a id="podman--tailscale"></a>
## Podman + Tailscale
若要通过 HTTPS 或远程浏览器访问，请遵循主 Tailscale 文档。
若要使用 HTTPS 或远程浏览器访问，请遵循主要的 Tailscale 文档。
Podman 专用说明：
Podman 特别说明：
- 保持 Podman 发布主机为 `127.0.0.1`。
- 优先使用由主机管理的 `tailscale serve`，而不是 `openclaw gateway --tailscale serve`。
- 在 macOS 上，如果本地浏览器设备认证上下文不可靠，请使用 Tailscale 访问，而不是临时的本地隧道变通方案。
- 优先使用主机管理的 `tailscale serve`，而不是 `openclaw gateway --tailscale serve`。
- 在 macOS 上，如果本地浏览器设备认证上下文不稳定，请使用 Tailscale 访问，而不是临时性的本地隧道变通方案。
请参阅：
请参见：
- [Tailscale](/gateway/tailscale)
- [Control UI](/web/control-ui)
- [Tailscale](/zh-CN/gateway/tailscale)
- [Control UI](/zh-CN/web/control-ui)
## Systemd（Quadlet，可选）
如果你运行了 `./scripts/podman/setup.sh --quadlet`，setup 会在以下位置安装一个 Quadlet 文件：
如果你运行了 `./scripts/podman/setup.sh --quadlet`，设置程序会在以下位置安装一个 Quadlet 文件：
```bash
~/.config/containers/systemd/openclaw.container
@ -147,71 +147,71 @@ systemctl --user daemon-reload
systemctl --user restart openclaw.service
```
若要在 SSH/无头主机上实现开机持久化，请为当前用户启用 lingering：
若要在 SSH/无头主机上实现开机持久运行，请为你的当前用户启用 lingering：
```bash
sudo loginctl enable-linger "$(whoami)"
```
## 配置、环境变量和存储
## 配置、env 和存储
- **配置目录：** `~/.openclaw`
- **工作区目录：** `~/.openclaw/workspace`
- **Token 文件：** `~/.openclaw/.env`
- **令牌文件：** `~/.openclaw/.env`
- **启动辅助脚本：** `./scripts/run-openclaw-podman.sh`
启动脚本和 Quadlet 会将主机状态以 bind mount 的方式挂载进容器：
启动脚本和 Quadlet 会将主机状态 bind-mount 到容器中：
- `OPENCLAW_CONFIG_DIR` -> `/home/node/.openclaw`
- `OPENCLAW_WORKSPACE_DIR` -> `/home/node/.openclaw/workspace`
默认情况下，这些都是主机目录，而不是匿名容器状态，因此
默认情况下，这些是主机目录，而不是匿名容器状态，因此
`openclaw.json`、每个智能体的 `auth-profiles.json`、渠道/提供商状态、
会话和工作区在容器被替换后仍然保留。
Podman 设置还会在已发布的 gateway 端口上为 `127.0.0.1` 和 `localhost` 预设 `gateway.controlUi.allowedOrigins`，以便本地仪表板能在容器的非 loopback bind 配置下正常工作。
会话以及工作区在容器替换后仍会保留。
Podman 设置还会为发布的 Gateway 网关端口上的 `127.0.0.1` 和 `localhost` 预填充 `gateway.controlUi.allowedOrigins`，从而让本地仪表板在容器使用非 loopback 绑定时仍能正常工作。
手动启动器的有用环境变量：
对手动启动器有用的环境变量：
- `OPENCLAW_PODMAN_CONTAINER` —— 容器名（默认是 `openclaw`）
- `OPENCLAW_PODMAN_CONTAINER` —— 容器名称（默认为 `openclaw`）
- `OPENCLAW_PODMAN_IMAGE` / `OPENCLAW_IMAGE` —— 要运行的镜像
- `OPENCLAW_PODMAN_GATEWAY_HOST_PORT` —— 映射到容器 `18789` 的主机端口
- `OPENCLAW_PODMAN_BRIDGE_HOST_PORT` —— 映射到容器 `18790` 的主机端口
- `OPENCLAW_PODMAN_PUBLISH_HOST` —— 发布端口使用的主机接口；默认是 `127.0.0.1`
- `OPENCLAW_GATEWAY_BIND` —— 容器内的 gateway bind 模式；默认是 `lan`
- `OPENCLAW_PODMAN_PUBLISH_HOST` —— 已发布端口的主机接口；默认为 `127.0.0.1`
- `OPENCLAW_GATEWAY_BIND` —— 容器内的 Gateway 网关绑定模式；默认为 `lan`
- `OPENCLAW_PODMAN_USERNS` —— `keep-id`（默认）、`auto` 或 `host`
手动启动器会在最终确定容器/镜像默认值之前读取 `~/.openclaw/.env`，因此你可以将这些值持久化在其中。
手动启动器在最终确定容器/镜像默认值之前会读取 `~/.openclaw/.env`，因此你可以将这些值持久保存在那里。
如果你使用非默认的 `OPENCLAW_CONFIG_DIR` 或 `OPENCLAW_WORKSPACE_DIR`，请在 `./scripts/podman/setup.sh` 和后续 `./scripts/run-openclaw-podman.sh launch` 命令中设置相同的变量。仓库内的启动器不会在不同 shell 之间持久化自定义路径覆盖。
如果你使用非默认的 `OPENCLAW_CONFIG_DIR` 或 `OPENCLAW_WORKSPACE_DIR`，请对 `./scripts/podman/setup.sh` 和后续的 `./scripts/run-openclaw-podman.sh launch` 命令设置相同的变量。仓库本地启动器不会在不同 shell 之间持久保存自定义路径覆盖值。
Quadlet 说明：
- 生成的 Quadlet 服务有意保持固定、加固后的默认形态：`127.0.0.1` 已发布端口、容器内使用 `--bind lan`，以及 `keep-id` 用户命名空间。
- 生成的 Quadlet 服务有意保持固定且加固的默认形态：发布端口为 `127.0.0.1`、容器内使用 `--bind lan`，以及 `keep-id` 用户命名空间。
- 它固定设置 `OPENCLAW_NO_RESPAWN=1`、`Restart=on-failure` 和 `TimeoutStartSec=300`。
- 它会发布 `127.0.0.1:18789:18789`（gateway）和 `127.0.0.1:18790:18790`（bridge）。
- 它会将 `~/.openclaw/.env` 作为运行时 `EnvironmentFile` 读取，用于 `OPENCLAW_GATEWAY_TOKEN` 之类的值，但不会使用手动启动器中 Podman 专用的覆盖允许列表。
- 它会同时发布 `127.0.0.1:18789:18789`（gateway）和 `127.0.0.1:18790:18790`（bridge）。
- 它将 `~/.openclaw/.env` 作为运行时 `EnvironmentFile` 读取，用于获取 `OPENCLAW_GATEWAY_TOKEN` 等值，但不会使用手动启动器中 Podman 特定覆盖项的 allowlist。
- 如果你需要自定义发布端口、发布主机或其他容器运行标志，请使用手动启动器，或直接编辑 `~/.config/containers/systemd/openclaw.container`，然后重新加载并重启服务。
## 常用命令
- **容器日志：** `podman logs -f openclaw`
- **停止容器：** `podman stop openclaw`
- **移除容器：** `podman rm -f openclaw`
- **删除容器：** `podman rm -f openclaw`
- **从主机 CLI 打开仪表板 URL：** `openclaw dashboard --no-open`
- **通过主机 CLI 查看健康/状态：** `openclaw gateway status --deep`（RPC 探测 + 额外
- **通过主机 CLI 查看健康状态/状态：** `openclaw gateway status --deep`（RPC 探测 + 额外
服务扫描）
## 故障排除
- **配置或工作区出现 Permission denied（EACCES）：** 容器默认使用 `--userns=keep-id` 和 `--user <your uid>:<your gid>` 运行。请确保主机上的配置/工作区路径归当前用户所有。
- **Gateway 网关启动被阻止（缺少 `gateway.mode=local`）：** 请确保 `~/.openclaw/openclaw.json` 存在，并设置 `gateway.mode="local"`。如果缺失，`scripts/podman/setup.sh` 会创建它。
- **容器 CLI 命令命中了错误目标：** 请显式使用 `openclaw --container <name> ...`，或在你的 shell 中导出 `OPENCLAW_CONTAINER=<name>`。
- **使用 `--container` 时 `openclaw update` 失败：** 这是预期行为。请重建/拉取镜像，然后重启容器或 Quadlet 服务。
- **Quadlet 服务无法启动：** 运行 `systemctl --user daemon-reload`，然后执行 `systemctl --user start openclaw.service`。在无头系统上，你可能还需要 `sudo loginctl enable-linger "$(whoami)"`。
- **SELinux 阻止 bind mount：** 保持默认挂载行为不变；当 SELinux 处于 enforcing 或 permissive 模式时，启动器会在 Linux 上自动添加 `:Z`。
- **配置或工作区出现权限被拒绝（EACCES）：** 容器默认使用 `--userns=keep-id` 和 `--user <your uid>:<your gid>` 运行。请确保主机上的配置/工作区路径归你当前用户所有。
- **Gateway 网关启动被阻止（缺少 `gateway.mode=local`）：** 请确保 `~/.openclaw/openclaw.json` 存在，并设置了 `gateway.mode="local"`。如果文件不存在，`scripts/podman/setup.sh` 会创建它。
- **容器 CLI 命令命中了错误目标：** 显式使用 `openclaw --container <name> ...`，或在你的 shell 中导出 `OPENCLAW_CONTAINER=<name>`。
- **`openclaw update` 配合 `--container` 失败：** 这是预期行为。请重建/拉取镜像，然后重启容器或 Quadlet 服务。
- **Quadlet 服务无法启动：** 运行 `systemctl --user daemon-reload`，然后运行 `systemctl --user start openclaw.service`。在无头系统上，你可能还需要执行 `sudo loginctl enable-linger "$(whoami)"`。
- **SELinux 阻止 bind mount：** 保持默认挂载行为不变；当 Linux 上 SELinux 处于 enforcing 或 permissive 模式时，启动器会自动添加 `:Z`。
## 相关
## 相关内容
- [Docker](/install/docker)
- [Gateway 后台进程](/gateway/background-process)
- [Gateway 网关故障排除](/gateway/troubleshooting)
- [Docker](/zh-CN/install/docker)
- [Gateway 后台进程](/zh-CN/gateway/background-process)
- [Gateway 故障排除](/zh-CN/gateway/troubleshooting)

60
docs/zh-CN/install/railway.mdx
View File

@ -1,52 +1,54 @@
---
read_when:
- 将 OpenClaw 部署到 Railway
- 你想要一种支持基于浏览器控制 UI 的一键云部署方式
summary: 使用一键模板在 Railway 上部署 OpenClaw
- 你希望通过基于浏览器的 Control UI 进行一键云部署
summary: 通过一键模板在 Railway 上部署 OpenClaw
title: Railway
x-i18n:
generated_at: "2026-04-05T08:28:12Z"
generated_at: "2026-04-23T06:41:16Z"
model: gpt-5.4
provider: openai
source_hash: f59699aa4e9d27d50018acc2e89ed1bbb1b1a5c85e3fd52f2afe5b2c97b21720
source_hash: 989c8467ead04b8aa7c94101abd99c936ecd3e451fe728afe8c2f2bd5a78df48
source_path: install/railway.mdx
workflow: 15
---
使用一键模板在 Railway 上部署 OpenClaw，并通过网页控制 UI 访问它。
# Railway
通过一键模板在 Railway 上部署 OpenClaw，并通过网页 Control UI 访问它。
这是最简单的“服务器上无需终端”路径：Railway 会为你运行 Gateway 网关。
## 快速检查清单（新用户）
1. 点击下方的 **Deploy on Railway**。
1. 点击**在 Railway 上部署**（见下方）。
2. 添加一个挂载到 `/data` 的 **Volume**。
3. 设置必需的 **Variables**（至少包括 `OPENCLAW_GATEWAY_PORT` 和 `OPENCLAW_GATEWAY_TOKEN`）。
3. 设置所需的**变量**（至少包括 `OPENCLAW_GATEWAY_PORT` 和 `OPENCLAW_GATEWAY_TOKEN`）。
4. 在端口 `8080` 上启用 **HTTP Proxy**。
5. 打开 `https://<your-railway-domain>/openclaw`，并使用已配置的共享密钥进行连接。此模板默认使用 `OPENCLAW_GATEWAY_TOKEN`；如果你将其替换为 password 认证，请改用该密码。
5. 打开 `https://<your-railway-domain>/openclaw`，并使用已配置的共享密钥连接。此模板默认使用 `OPENCLAW_GATEWAY_TOKEN`；如果你将其替换为密码认证，请改用该密码。
## 一键部署
<a href="https://railway.com/deploy/clawdbot-railway-template" target="_blank" rel="noreferrer">
Deploy on Railway
在 Railway 上部署
</a>
部署完成后，在 **Railway → 你的服务 → Settings → Domains** 中找到你的公开 URL。
部署后，在 **Railway → 你的服务 → Settings → Domains** 中找到你的公开 URL。
Railway 会：
- 为你分配一个生成的域名（通常类似 `https://<something>.up.railway.app`），或
- 使用你附加的自定义域名。
- 提供一个自动生成的域名（通常为 `https://<something>.up.railway.app`），或
- 如果你已绑定自定义域名，则使用你的自定义域名。
然后打开：
- `https://<your-railway-domain>/openclaw` — 控制 UI
- `https://<your-railway-domain>/openclaw` — Control UI
## 你将获得
- 托管的 OpenClaw Gateway 网关 + 控制 UI
- 托管的 OpenClaw Gateway 网关 + Control UI
- 通过 Railway Volume（`/data`）提供的持久化存储，因此 `openclaw.json`、
每个智能体的 `auth-profiles.json`、渠道/provider 状态、会话以及
工作区都能在重新部署后保留
每个智能体的 `auth-profiles.json`、渠道/提供商状态、会话以及
工作区都能在重新部署后继续保留
## 必需的 Railway 设置
@ -58,40 +60,40 @@ Railway 会：
### Volume（必需）
挂载一个 volume 到：
挂载一个卷到：
- `/data`
### Variables
### 变量
在该服务上设置以下变量：
- `OPENCLAW_GATEWAY_PORT=8080`（必需——必须与 Public Networking 中的端口一致）
- `OPENCLAW_GATEWAY_TOKEN`（必需；请将其视为管理员级秘密）
- `OPENCLAW_GATEWAY_PORT=8080`（必需——必须与公共网络中的端口一致）
- `OPENCLAW_GATEWAY_TOKEN`（必需；请将其视为管理员密钥）
- `OPENCLAW_STATE_DIR=/data/.openclaw`（推荐）
- `OPENCLAW_WORKSPACE_DIR=/data/workspace`（推荐）
## 连接一个渠道
使用位于 `/openclaw` 的控制 UI，或通过 Railway 的 shell 运行 `openclaw onboard` 获取渠道设置说明：
使用位于 `/openclaw` 的 Control UI，或通过 Railway 的 shell 运行 `openclaw onboard` 获取渠道设置说明：
- [Telegram](/channels/telegram)（最快——只需要一个 bot token）
- [Discord](/channels/discord)
- [所有渠道](/channels)
- [Telegram](/zh-CN/channels/telegram)（最快——只需一个 bot token）
- [Discord](/zh-CN/channels/discord)
- [所有渠道](/zh-CN/channels)
## 备份与迁移
导出你的状态、配置、auth 配置文件和工作区：
导出你的状态、配置、认证配置文件和工作区：
```bash
openclaw backup create
```
这会创建一个可移植的备份归档，其中包含 OpenClaw 状态以及任何已配置的
工作区。详情请参见 [Backup](/cli/backup)。
工作区。详情请参见 [Backup](/zh-CN/cli/backup)。
## 后续步骤
- 设置消息渠道：[Channels](/channels)
- 配置 Gateway 网关：[Gateway 配置](/gateway/configuration)
- 保持 OpenClaw 为最新版本：[更新](/install/updating)
- 设置消息渠道：[Channels](/zh-CN/channels)
- 配置 Gateway 网关：[Gateway configuration](/zh-CN/gateway/configuration)
- 让 OpenClaw 保持最新：[Updating](/zh-CN/install/updating)

102
docs/zh-CN/install/render.mdx
View File

@ -2,39 +2,40 @@
read_when:
- 将 OpenClaw 部署到 Render
- 你想使用 Render Blueprints 进行声明式云部署
summary: 使用 Infrastructure as Code 在 Render 上部署 OpenClaw
summary: 使用基础设施即代码在 Render 上部署 OpenClaw
title: Render
x-i18n:
generated_at: "2026-04-05T08:28:33Z"
generated_at: "2026-04-23T06:41:21Z"
model: gpt-5.4
provider: openai
source_hash: 379297f0298ddac0c1c657695f52619bb482f7b76d358e765880726f6f558c88
source_hash: 95ffe98a60e9919826a7c7fdb9cbafd63d20ce3de111ac305f43907b1ae442dc
source_path: install/render.mdx
workflow: 15
---
使用 Infrastructure as Code 在 Render 上部署 OpenClaw。内置的 `render.yaml` Blueprint 以声明式方式定义了你的整个栈、服务、磁盘和环境变量，因此你可以一键部署，并让基础设施与代码一起进行版本管理。
# Render
## 前置条件
使用基础设施即代码在 Render 上部署 OpenClaw。随附的 `render.yaml` Blueprint 会以声明式方式定义你的整个技术栈——服务、磁盘、环境变量——因此你可以一键部署，并让基础设施与代码一起进行版本管理。
## 先决条件
- 一个 [Render 账户](https://render.com)（提供免费层）
- 你首选[模型提供商](/providers)的 API key
- 你首选[模型提供商](/zh-CN/providers)的 API 密钥
## 使用 Render Blueprint 部署
[Deploy to Render](https://render.com/deploy?repo=https://github.com/openclaw/openclaw)
[部署到 Render](https://render.com/deploy?repo=https://github.com/openclaw/openclaw)
点击此链接将会：
1. 基于本仓库根目录中的 `render.yaml` Blueprint 创建一个新的 Render 服务。
1. 从此仓库根目录中的 `render.yaml` Blueprint 创建一个新的 Render 服务。
2. 构建 Docker 镜像并部署
部署完成后，你的服务 URL 将遵循 `https://<service-name>.onrender.com` 这一格式。
部署完成后，你的服务 URL 将遵循 `https://<service-name>.onrender.com` 这样的格式。
## 理解 Blueprint
Render Blueprint 是用于定义基础设施的 YAML 文件。本仓库中的 `render.yaml`
配置了运行 OpenClaw 所需的一切：
Render Blueprints 是用于定义基础设施的 YAML 文件。此仓库中的 `render.yaml` 配置了运行 OpenClaw 所需的一切：
```yaml
services:
@ -58,41 +59,38 @@ services:
sizeGB: 1
```
所使用的 Blueprint 关键特性：
使用到的 Blueprint 关键特性：
| 特性 | 用途 |
| 特性 | 用途 |
| --------------------- | ---------------------------------------------------------- |
| `runtime: docker` | 从仓库中的 Dockerfile 构建 |
| `healthCheckPath` | Render 监控 `/health` 并重启不健康实例 |
| `generateValue: true` | 自动生成加密安全的值 |
| `disk` | 可在重新部署后保留的持久化存储 |
| `runtime: docker` | 从仓库的 Dockerfile 构建 |
| `healthCheckPath` | Render 监控 `/health`，并在实例不健康时重启 |
| `generateValue: true` | 自动生成加密安全的值 |
| `disk` | 可在重新部署后保留的持久化存储 |
## 选择套餐
| 套餐 | 休眠 | 磁盘 | 最适合 |
| 套餐 | 休眠 | 磁盘 | 最适合 |
| --------- | ----------------- | ------------- | ----------------------------- |
| Free | 空闲 15 分钟后 | 不可用 | 测试、演示 |
| Starter | 永不 | 1GB+ | 个人使用、小团队 |
| Standard+ | 永不 | 1GB+ | 生产环境、多个渠道 |
| Free | 空闲 15 分钟后 | 不可用 | 测试、演示 |
| Starter | 永不 | 1GB+ | 个人使用、小型团队 |
| Standard+ | 永不 | 1GB+ | 生产环境、多个渠道 |
Blueprint 默认使用 `starter`。如果你想使用免费层，请在
你 fork 的 `render.yaml` 中将 `plan: starter` 改为 `plan: free`（但请注意：没有持久磁盘意味着 OpenClaw 状态会在每次部署时被重置）。
Blueprint 默认使用 `starter`。若要使用免费层，请在你 fork 的 `render.yaml` 中将 `plan: starter` 改为 `plan: free`（但请注意：没有持久化磁盘意味着 OpenClaw 状态会在每次部署时重置）。
## 部署后
## 部署之后
### 访问控制 UI
网页仪表板位于 `https://<your-service>.onrender.com/`。
Web 控制面板位于 `https://<your-service>.onrender.com/`。
请使用已配置的共享密钥进行连接。此部署模板会自动生成
`OPENCLAW_GATEWAY_TOKEN`（可在 **Dashboard → 你的服务 →
Environment** 中查看）；如果你将其替换为 password 认证，请改用该密码。
使用已配置的共享密钥进行连接。此部署模板会自动生成 `OPENCLAW_GATEWAY_TOKEN`（可在 **Dashboard → your service → Environment** 中找到）；如果你将其替换为密码认证，请改用该密码。
## Render Dashboard 功能
## Render 控制面板功能
### 日志
可在 **Dashboard → 你的服务 → Logs** 中查看实时日志。可按以下内容筛选：
可在 **Dashboard → your service → Logs** 中查看实时日志。可按以下类型筛选：
- 构建日志（Docker 镜像创建）
- 部署日志（服务启动）
@ -100,70 +98,68 @@ Environment** 中查看）；如果你将其替换为 password 认证，请改
### Shell 访问
如需调试，请通过 **Dashboard → 你的服务 → Shell** 打开一个 shell 会话。持久化磁盘挂载在 `/data`。
如需调试，可通过 **Dashboard → your service → Shell** 打开一个 shell 会话。持久化磁盘挂载在 `/data`。
### 环境变量
可在 **Dashboard → 你的服务 → Environment** 中修改变量。更改会触发自动重新部署。
可在 **Dashboard → your service → Environment** 中修改变量。修改后会触发自动重新部署。
### 自动部署
如果你使用的是原始 OpenClaw 仓库，Render 不会自动部署你的 OpenClaw。要更新它，请在仪表板中手动运行一次 Blueprint 同步。
如果你使用的是原始 OpenClaw 仓库，Render 不会自动部署你的 OpenClaw。要更新它，请从控制面板手动执行 Blueprint 同步。
## 自定义域名
1. 前往 **Dashboard → 你的服务 → Settings → Custom Domains**
1. 前往 **Dashboard → your service → Settings → Custom Domains**
2. 添加你的域名
3. 按说明配置 DNS（将 CNAME 指向 `*.onrender.com`）
3. 按照说明配置 DNS（CNAME 指向 `*.onrender.com`）
4. Render 会自动配置 TLS 证书
## 扩展
## 扩缩容
Render 支持水平和垂直扩展：
Render 支持水平扩展和垂直扩展：
- **垂直扩展**：更换套餐以获取更多 CPU/RAM
- **水平扩展**：增加实例数量（需 Standard 及以上套餐）
- **垂直扩展**：更换套餐以获得更多 CPU / RAM
- **水平扩展**：增加实例数量（Standard 套餐及以上）
对于 OpenClaw，通常垂直扩展就足够了。水平扩展则需要粘性会话或外部状态管理。
## 备份与迁移
可随时通过 Render Dashboard 中的 shell 访问导出你的状态、配置、auth 配置文件和工作区：
你可以随时使用 Render 控制面板中的 shell 访问导出状态、配置、认证配置文件和工作区：
```bash
openclaw backup create
```
这会创建一个可移植的备份归档，其中包含 OpenClaw 状态以及任何已配置的
工作区。详情请参见 [Backup](/cli/backup)。
这会创建一个可移植的备份归档，其中包含 OpenClaw 状态以及所有已配置的工作区。详见[备份](/zh-CN/cli/backup)。
## 故障排除
### 服务无法启动
请检查 Render Dashboard 中的部署日志。常见问题包括：
请检查 Render 控制面板中的部署日志。常见问题包括：
- 缺少 `OPENCLAW_GATEWAY_TOKEN` —— 请确认它已在 **Dashboard → Environment** 中设置
- 端口不匹配 —— 请确认已设置 `OPENCLAW_GATEWAY_PORT=8080`，以便 gateway 绑定到 Render 期望的端口
- 缺少 `OPENCLAW_GATEWAY_TOKEN` —— 确认已在 **Dashboard → Environment** 中设置
- 端口不匹配 —— 确保已设置 `OPENCLAW_GATEWAY_PORT=8080`，使 Gateway 网关绑定到 Render 所期望的端口
### 冷启动缓慢（免费层）
### 冷启动较慢（免费层）
免费层服务在空闲 15 分钟后会休眠。休眠后的第一次请求需要几秒钟，因为容器需要启动。升级到 Starter 套餐可实现始终在线。
免费层服务会在空闲 15 分钟后休眠。休眠后的首次请求需要几秒钟，因为容器需要启动。升级到 Starter 套餐即可保持始终在线。
### 重新部署后数据丢失
这会发生在免费层（无持久磁盘）上。请升级到付费套餐，或者
定期在 Render shell 中通过 `openclaw backup create` 导出完整备份。
这会发生在免费层（无持久化磁盘）上。请升级到付费套餐，或定期在 Render shell 中通过 `openclaw backup create` 导出完整备份。
### 健康检查失败
Render 要求 `/health` 在 30 秒内返回 200 响应。如果构建成功但部署失败，可能是服务启动耗时过长。请检查：
- 构建日志中是否有错误
- 容器是否能在本地通过 `docker build && docker run` 正常运行
- 容器在本地使用 `docker build && docker run` 是否可以运行
## 后续步骤
- 设置消息渠道：[Channels](/channels)
- 配置 Gateway 网关：[Gateway 配置](/gateway/configuration)
- 保持 OpenClaw 为最新版本：[更新](/install/updating)
- 设置消息渠道：[Channels](/zh-CN/channels)
- 配置 Gateway 网关：[Gateway 网关配置](/zh-CN/gateway/configuration)
- 保持 OpenClaw 为最新版本：[更新](/zh-CN/install/updating)

1196
docs/zh-CN/plugins/architecture.md
View File

File diff suppressed because it is too large Load Diff

138
docs/zh-CN/providers/anthropic.md
View File

@ -4,46 +4,44 @@ read_when:
summary: 在 OpenClaw 中通过 API 密钥或 Claude CLI 使用 Anthropic Claude
title: Anthropic
x-i18n:
generated_at: "2026-04-12T11:08:22Z"
generated_at: "2026-04-23T06:41:43Z"
model: gpt-5.4
provider: openai
source_hash: 5e3dda5f98ade9d4c3841888103bfb43d59e075d358a701ed0ae3ffb8d5694a7
source_hash: 02e99e31bf58d08a18f526281b3bf5c3a5a96b2ff342adf3a6a193a076147a03
source_path: providers/anthropic.md
workflow: 15
---
# Anthropic（Claude）
Anthropic 构建了 **Claude** 模型系列。OpenClaw 支持两种认证方式：
Anthropic 构建了 **Claude** 模型家族。OpenClaw 支持两种认证方式：
- **API 密钥** — 直接访问 Anthropic API，并按使用量计费（`anthropic/*` 模型）
- **Claude CLI** — 在同一主机上复用现有的 Claude CLI 登录
- **API key** —— 通过 Anthropic API 直接访问，并按使用量计费（`anthropic/*` 模型）
- **Claude CLI** —— 复用同一主机上现有的 Claude CLI 登录
<Warning>
Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此
除非 Anthropic 发布新的政策，否则 OpenClaw 会将 Claude CLI 复用和 `claude -p`
用法视为已获认可。
Anthropic 团队告诉我们，OpenClaw 风格的 Claude CLI 用法已再次被允许，因此除非 Anthropic 发布新的政策，否则 OpenClaw 会将 Claude CLI 复用和 `claude -p` 用法视为获准行为。
对于长期运行的 Gateway 网关主机，Anthropic API 密钥仍然是最明确且
最可预测的生产路径。
对于长期运行的 Gateway 网关主机，Anthropic API key 仍然是最清晰、最可预测的生产环境方案。
Anthropic 当前的公开文档：
- [Claude Code CLI 参考](https://code.claude.com/docs/en/cli-reference)
- [Claude Agent SDK 概览](https://platform.claude.com/docs/en/agent-sdk/overview)
- [在你的 Pro 或 Max 套餐中使用 Claude Code](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
- [在你的 Team 或 Enterprise 套餐中使用 Claude Code](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/)
</Warning>
- [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference)
- [Claude Agent SDK overview](https://platform.claude.com/docs/en/agent-sdk/overview)
- [Using Claude Code with your Pro or Max plan](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
- [Using Claude Code with your Team or Enterprise plan](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/)
</Warning>
## 入门指南
<Tabs>
<Tab title="API 密钥">
<Tab title="API key">
**最适合：** 标准 API 访问和按使用量计费。
<Steps>
<Step title="获取你的 API 密钥">
在 [Anthropic Console](https://console.anthropic.com/) 中创建一个 API 密钥。
<Step title="获取你的 API key">
在 [Anthropic Console](https://console.anthropic.com/) 中创建一个 API key。
</Step>
<Step title="运行新手引导">
```bash
@ -51,7 +49,7 @@ Anthropic 当前的公开文档：
# choose: Anthropic API key
```
或者直接传入密钥：
或直接传入密钥：
```bash
openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
@ -76,11 +74,11 @@ Anthropic 当前的公开文档：
</Tab>
<Tab title="Claude CLI">
**最适合：** 复用现有的 Claude CLI 登录，而无需单独的 API 密钥。
**最适合：** 复用现有 Claude CLI 登录，而无需单独的 API key。
<Steps>
<Step title="确保已安装 Claude CLI 并完成登录">
验证方式如下：
通过以下命令验证：
```bash
claude --version
@ -102,21 +100,21 @@ Anthropic 当前的公开文档：
</Steps>
<Note>
Claude CLI 后端的设置与运行时细节见 [CLI 后端](/zh-CN/gateway/cli-backends)。
Claude CLI 后端的设置和运行时细节见 [CLI Backends](/zh-CN/gateway/cli-backends)。
</Note>
<Tip>
如果你想要最清晰的计费路径，请改用 Anthropic API 密钥。OpenClaw 也支持来自 [OpenAI Codex](/zh-CN/providers/openai)、[Qwen Cloud](/zh-CN/providers/qwen)、[MiniMax](/zh-CN/providers/minimax) 和 [Z.AI / GLM](/zh-CN/providers/glm) 的订阅式选项。
如果你想要最清晰的计费路径，请改用 Anthropic API key。OpenClaw 还支持来自 [OpenAI Codex](/zh-CN/providers/openai)、[Qwen Cloud](/zh-CN/providers/qwen)、[MiniMax](/zh-CN/providers/minimax) 和 [Z.AI / GLM](/zh-CN/providers/glm) 的订阅式选项。
</Tip>
</Tab>
</Tabs>
## 思考默认值（Claude 4.6）
## Thinking 默认值（Claude 4.6）
当未设置显式思考级别时，Claude 4.6 模型在 OpenClaw 中默认使用 `adaptive` 思考。
当未设置显式 thinking 级别时，Claude 4.6 模型在 OpenClaw 中默认使用 `adaptive` thinking。
可通过 `/think:<level>` 为每条消息覆盖，或在模型参数中设置：
可通过 `/think:<level>` 按消息覆盖，或在模型参数中设置：
```json5
{
@ -134,19 +132,19 @@ Anthropic 当前的公开文档：
<Note>
相关 Anthropic 文档：
- [自适应思考](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking)
- [扩展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)
- [Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking)
- [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)
</Note>
## 提示词缓存
OpenClaw 支持 Anthropic 在 API 密钥认证下的提示词缓存功能。
OpenClaw 支持 Anthropic 的提示词缓存功能，适用于 API key 认证。
| 值 | 缓存时长 | 说明 |
| ------------------- | -------- | ------------------------------ |
| `"short"`（默认） | 5 分钟 | 对 API 密钥认证自动启用 |
| `"long"` | 1 小时 | 扩展缓存 |
| `"none"` | 不缓存 | 禁用提示词缓存 |
| 值 | 缓存时长 | 说明 |
| ------------------- | -------------- | -------------------------------------- |
| `"short"`（默认） | 5 分钟 | 会自动应用于 API key 认证 |
| `"long"` | 1 小时 | 扩展缓存 |
| `"none"` | 不缓存 | 禁用提示词缓存 |
```json5
{
@ -164,7 +162,7 @@ OpenClaw 支持 Anthropic 在 API 密钥认证下的提示词缓存功能。
<AccordionGroup>
<Accordion title="按智能体覆盖缓存">
使用模型级参数作为基线，然后通过 `agents.list[].params` 覆盖特定智能体：
先将模型级参数作为基线，然后通过 `agents.list[].params` 覆盖特定智能体：
```json5
{
@ -190,24 +188,24 @@ OpenClaw 支持 Anthropic 在 API 密钥认证下的提示词缓存功能。
1. `agents.defaults.models["provider/model"].params`
2. `agents.list[].params`（匹配 `id`，按键覆盖）
这样可以让一个智能体保留长期缓存，而同一模型上的另一个智能体则为突发型 / 低复用流量禁用缓存。
这样可以让一个智能体保留长期缓存，而同一模型上的另一个智能体则为突发 / 低复用流量禁用缓存。
</Accordion>
<Accordion title="Bedrock Claude 说明">
- Bedrock 上的 Anthropic Claude 模型（`amazon-bedrock/*anthropic.claude*`）在已配置时接受 `cacheRetention` 透传。
- 非 Anthropic 的 Bedrock 模型会在运行时被强制设为 `cacheRetention: "none"`。
- 当未设置显式值时，API 密钥的智能默认值也会为 Bedrock 上的 Claude 引用预填 `cacheRetention: "short"`。
- Bedrock 上的 Anthropic Claude 模型（`amazon-bedrock/*anthropic.claude*`）在配置后接受 `cacheRetention` 透传。
- 非 Anthropic 的 Bedrock 模型会在运行时被强制设置为 `cacheRetention: "none"`。
- 当未设置显式值时，API key 智能默认值也会为 Claude-on-Bedrock 引用预置 `cacheRetention: "short"`。
</Accordion>
</AccordionGroup>
## 高级配置
<AccordionGroup>
<Accordion title="快速模式">
OpenClaw 的共享 `/fast` 开关支持直连 Anthropic 流量（API 密钥以及面向 `api.anthropic.com` 的 OAuth）。
<Accordion title="Fast mode">
OpenClaw 的共享 `/fast` 开关支持直接 Anthropic 流量（发送到 `api.anthropic.com` 的 API key 和 OAuth）。
| Command | Maps to |
| 命令 | 映射为 |
|---------|---------|
| `/fast on` | `service_tier: "auto"` |
| `/fast off` | `service_tier: "standard_only"` |
@ -227,30 +225,29 @@ OpenClaw 支持 Anthropic 在 API 密钥认证下的提示词缓存功能。
```
<Note>
- 仅对直连 `api.anthropic.com` 的请求注入。代理路由会保持 `service_tier` 不变。
- 如果同时设置了显式 `serviceTier` 或 `service_tier` 参数，它们会覆盖 `/fast`。
- 在没有 Priority Tier 容量的账户上，`service_tier: "auto"` 可能会解析为 `standard`。
- 仅注入到直接发送到 `api.anthropic.com` 的请求中。代理路由不会改动 `service_tier`。
- 当 `/fast` 与显式 `serviceTier` 或 `service_tier` 参数同时设置时，后者优先。
- 对于没有 Priority Tier 容量的账户，`service_tier: "auto"` 可能会解析为 `standard`。
</Note>
</Accordion>
<Accordion title="媒体理解（图片和 PDF）">
内置的 Anthropic 插件注册了图片和 PDF 理解能力。OpenClaw
会根据已配置的 Anthropic 认证自动解析媒体能力——无需
额外配置。
<Accordion title="媒体理解（图像和 PDF）">
内置 Anthropic 插件注册了图像和 PDF 理解功能。OpenClaw
会根据配置的 Anthropic 认证自动解析媒体能力——无需额外配置。
| Property | Value |
| --------------- | -------------------- |
| Default model | `claude-opus-4-6` |
| Supported input | Images, PDF documents |
| 属性 | 值 |
| -------------- | -------------------- |
| 默认模型 | `claude-opus-4-6` |
| 支持的输入 | 图像、PDF 文档 |
当图片或 PDF 附加到会话中时，OpenClaw 会自动
通过 Anthropic 媒体理解提供商进行路由。
当会话中附加图像或 PDF 时，OpenClaw 会自动
将其路由到 Anthropic 媒体理解提供商。
</Accordion>
<Accordion title="1M 上下文窗口（测试版）">
Anthropic 的 1M 上下文窗口受测试版权限控制。请按模型启用：
<Accordion title="1M 上下文窗口（beta）">
Anthropic 的 1M 上下文窗口受 beta 门控。请按模型启用：
```json5
{
@ -269,29 +266,36 @@ OpenClaw 支持 Anthropic 在 API 密钥认证下的提示词缓存功能。
OpenClaw 会将其映射为请求中的 `anthropic-beta: context-1m-2025-08-07`。
<Warning>
需要你的 Anthropic 凭证具备长上下文访问权限。旧版令牌认证（`sk-ant-oat-*`）不支持 1M 上下文请求——OpenClaw 会记录一条警告并回退到标准上下文窗口。
需要你的 Anthropic 凭证具备长上下文访问权限。旧版 token 认证（`sk-ant-oat-*`）不支持 1M 上下文请求——OpenClaw 会记录警告，并回退到标准上下文窗口。
</Warning>
</Accordion>
<Accordion title="Claude Opus 4.7 1M 上下文标准化">
Claude Opus 4.7（`anthropic/claude-opus-4.7`）及其 `claude-cli` 变体，会在解析后的运行时元数据以及活动智能体状态 / 上下文报告中标准化为 1M 上下文窗口。对于 Opus 4.7，你不需要设置 `params.context1m: true`；它不再继承过时的 200k 回退值。
压缩和溢出处理会自动使用 1M 窗口。其他 Anthropic 模型仍保持其公开限制。
</Accordion>
</AccordionGroup>
## 故障排除
<AccordionGroup>
<Accordion title="401 错误 / 令牌突然失效">
Anthropic 令牌认证可能过期或被撤销。对于新配置，建议迁移到 Anthropic API 密钥。
<Accordion title="401 错误 / token 突然失效">
Anthropic token 认证可能会过期或被撤销。对于新配置，建议迁移到 Anthropic API key。
</Accordion>
<Accordion title='未找到提供商 "anthropic" 的 API 密钥'>
认证是**按智能体**区分的。新智能体不会继承主智能体的密钥。请为该智能体重新运行新手引导，或在 Gateway 网关主机上配置 API 密钥，然后使用 `openclaw models status` 验证。
<Accordion title='未找到 provider "anthropic" 的 API key'>
认证是**按智能体**区分的。新智能体不会继承主智能体的密钥。请为该智能体重新运行新手引导，或在 Gateway 网关主机上配置 API key，然后使用 `openclaw models status` 验证。
</Accordion>
<Accordion title='未找到配置文件 "anthropic:default" 的凭证'>
运行 `openclaw models status` 以查看当前启用的是哪个认证配置文件。重新运行新手引导，或为该配置文件路径配置 API 密钥。
<Accordion title='未找到 profile "anthropic:default" 的凭证'>
运行 `openclaw models status` 查看当前启用的是哪个认证配置文件。重新运行新手引导，或为该配置文件路径配置 API key。
</Accordion>
<Accordion title="没有可用的认证配置文件（全部处于冷却中）">
检查 `openclaw models status --json` 中的 `auth.unusableProfiles`。Anthropic 的速率限制冷却可能是按模型作用域生效的，因此同级的其他 Anthropic 模型可能仍可使用。添加另一个 Anthropic 配置文件，或等待冷却结束。
使用 `openclaw models status --json` 检查 `auth.unusableProfiles`。Anthropic 限流冷却可能是按模型范围生效的，因此同级的另一个 Anthropic 模型可能仍然可用。请添加另一个 Anthropic 配置文件，或等待冷却结束。
</Accordion>
</AccordionGroup>
@ -306,10 +310,10 @@ OpenClaw 支持 Anthropic 在 API 密钥认证下的提示词缓存功能。
选择提供商、模型引用和故障切换行为。
</Card>
<Card title="CLI 后端" href="/zh-CN/gateway/cli-backends" icon="terminal">
Claude CLI 后端设置与运行时细节。
Claude CLI 后端设置和运行时细节。
</Card>
<Card title="提示词缓存" href="/zh-CN/reference/prompt-caching" icon="database">
提示词缓存在各提供商中的工作方式。
提示词缓存如何在不同提供商之间工作。
</Card>
<Card title="OAuth 和认证" href="/zh-CN/gateway/authentication" icon="key">
认证细节和凭证复用规则。

94
docs/zh-CN/providers/bedrock-mantle.md
View File

@ -2,54 +2,57 @@
read_when:
- 你想在 OpenClaw 中使用由 Bedrock Mantle 托管的 OSS 模型
- 你需要用于 GPT-OSS、Qwen、Kimi 或 GLM 的 Mantle OpenAI 兼容端点
summary: 使用 Amazon Bedrock Mantle（兼容 OpenAI）模型与 OpenClaw 配合使用
summary: 在 OpenClaw 中使用 Amazon Bedrock Mantle（兼容 OpenAI）模型
title: Amazon Bedrock Mantle
x-i18n:
generated_at: "2026-04-12T10:22:34Z"
generated_at: "2026-04-23T06:42:01Z"
model: gpt-5.4
provider: openai
source_hash: 27e602b6f6a3ae92427de135cb9df6356e0daaea6b6fe54723a7542dd0d5d21e
source_hash: b7b3ba0e0a6a175ca1159c0c8ac9cf13a43dfb59b7bb106089c635876c349c61
source_path: providers/bedrock-mantle.md
workflow: 15
---
# Amazon Bedrock Mantle
OpenClaw 内置了一个 **Amazon Bedrock Mantle** 提供商，可连接到 Mantle 的 OpenAI 兼容端点。Mantle 通过基于 Bedrock 基础设施的标准 `/v1/chat/completions` 接口托管开源和第三方模型（GPT-OSS、Qwen、Kimi、GLM 及类似模型）。
OpenClaw 内置了一个 **Amazon Bedrock Mantle** 提供商，用于连接到
Mantle 的 OpenAI 兼容端点。Mantle 通过由 Bedrock 基础设施支持的标准
`/v1/chat/completions` 接口托管开源和第三方模型
（GPT-OSS、Qwen、Kimi、GLM 等类似模型）。
| 属性 | 值 |
| -------------- | ----------------------------------------------------------------------------------- |
| -------------- | ------------------------------------------------------------------------------------------- |
| 提供商 ID | `amazon-bedrock-mantle` |
| API | `openai-completions`（兼容 OpenAI） |
| 认证 | 显式 `AWS_BEARER_TOKEN_BEDROCK` 或通过 IAM 凭证链生成 bearer token |
| API | `openai-completions`（OpenAI 兼容）或 `anthropic-messages`（Anthropic Messages 路由） |
| 认证 | 显式 `AWS_BEARER_TOKEN_BEDROCK` 或基于 IAM 凭证链生成 bearer token |
| 默认区域 | `us-east-1`（可通过 `AWS_REGION` 或 `AWS_DEFAULT_REGION` 覆盖） |
## 入门指南
选择你偏好的认证方式，并按照设置步骤进行操作。
选择你偏好的认证方式，并按步骤进行设置。
<Tabs>
<Tab title="显式 bearer token">
**最适合：** 已经拥有 Mantle bearer token 的环境。
**最适合：** 你已经拥有 Mantle bearer token 的环境。
<Steps>
<Step title="在 Gateway 网关主机上设置 bearer token">
<Step title="在 Gateway 网关 宿主机上设置 bearer token">
```bash
export AWS_BEARER_TOKEN_BEDROCK="..."
```
你也可以选择设置区域（默认为 `us-east-1`）：
你也可以选择设置区域（默认是 `us-east-1`）：
```bash
export AWS_REGION="us-west-2"
```
</Step>
<Step title="验证是否已发现模型">
<Step title="验证模型已被发现">
```bash
openclaw models list
```
已发现的模型会显示在 `amazon-bedrock-mantle` 提供商下。除非你想覆盖默认设置，否则无需额外配置。
已发现的模型会显示在 `amazon-bedrock-mantle` 提供商下。除非你想覆盖默认值，否则不需要额外配置。
</Step>
</Steps>
@ -59,25 +62,25 @@ OpenClaw 内置了一个 **Amazon Bedrock Mantle** 提供商，可连接到 Mant
**最适合：** 使用兼容 AWS SDK 的凭证（共享配置、SSO、web identity、实例角色或任务角色）。
<Steps>
<Step title="在 Gateway 网关主机上配置 AWS 凭证">
任何兼容 AWS SDK 的认证来源都可以使用：
<Step title="在 Gateway 网关 宿主机上配置 AWS 凭证">
任何兼容 AWS SDK 的认证源都可以使用：
```bash
export AWS_PROFILE="default"
export AWS_REGION="us-west-2"
```
</Step>
<Step title="验证是否已发现模型">
<Step title="验证模型已被发现">
```bash
openclaw models list
```
OpenClaw 会自动通过凭证链生成 Mantle bearer token。
OpenClaw 会自动从凭证链生成 Mantle bearer token。
</Step>
</Steps>
<Tip>
当未设置 `AWS_BEARER_TOKEN_BEDROCK` 时，OpenClaw 会通过 AWS 默认凭证链为你签发 bearer token，其中包括共享凭证/配置 profile、SSO、web identity、实例角色或任务角色。
当未设置 `AWS_BEARER_TOKEN_BEDROCK` 时，OpenClaw 会从 AWS 默认凭证链为你签发 bearer token，包括共享凭证/配置 profile、SSO、web identity，以及实例角色或任务角色。
</Tip>
</Tab>
@ -85,15 +88,17 @@ OpenClaw 内置了一个 **Amazon Bedrock Mantle** 提供商，可连接到 Mant
## 自动模型发现
当设置了 `AWS_BEARER_TOKEN_BEDROCK` 时，OpenClaw 会直接使用它。否则，OpenClaw 会尝试通过 AWS 默认凭证链生成 Mantle bearer token。然后，它会通过查询该区域的 `/v1/models` 端点来发现可用的 Mantle 模型。
设置了 `AWS_BEARER_TOKEN_BEDROCK` 时，OpenClaw 会直接使用它。否则，
OpenClaw 会尝试从 AWS 默认凭证链生成 Mantle bearer token。
然后，它会通过查询该区域的 `/v1/models` 端点来发现可用的 Mantle 模型。
| 行为 | 详情 |
| ----------------- | ------------------------- |
| 发现缓存 | 结果缓存 1 小时 |
| IAM token 刷新 | 每小时一次 |
| IAM token 刷新 | 每小时 |
<Note>
该 bearer token 与标准 [Amazon Bedrock](/zh-CN/providers/bedrock) 提供商使用的 `AWS_BEARER_TOKEN_BEDROCK` 相同。
该 bearer token 与标准 [Amazon Bedrock](/zh-CN/providers/bedrock) 提供商使用的 `AWS_BEARER_TOKEN_BEDROCK` 是同一个。
</Note>
### 支持的区域
@ -104,7 +109,7 @@ OpenClaw 内置了一个 **Amazon Bedrock Mantle** 提供商，可连接到 Mant
## 手动配置
如果你更喜欢显式配置而不是自动发现：
如果你更喜欢显式配置，而不是自动发现：
```json5
{
@ -136,17 +141,54 @@ OpenClaw 内置了一个 **Amazon Bedrock Mantle** 提供商，可连接到 Mant
<AccordionGroup>
<Accordion title="推理支持">
是否支持推理会根据模型 ID 中是否包含 `thinking`、`reasoner` 或 `gpt-oss-120b` 等模式来推断。对于匹配的模型，OpenClaw 会在发现时自动设置 `reasoning: true`。
推理支持会根据模型 ID 中是否包含诸如
`thinking`、`reasoner` 或 `gpt-oss-120b` 之类的模式来推断。
对于匹配的模型，OpenClaw 会在发现期间自动设置 `reasoning: true`。
</Accordion>
<Accordion title="端点不可用">
如果 Mantle 端点不可用或未返回任何模型，该提供商会被静默跳过。OpenClaw 不会报错；其他已配置的提供商仍会继续正常工作。
如果 Mantle 端点不可用或未返回任何模型，该提供商会被静默跳过。
OpenClaw 不会报错；其他已配置的提供商会继续正常工作。
</Accordion>
<Accordion title="通过 Anthropic Messages 路由使用 Claude Opus 4.7">
Mantle 还暴露了一个 Anthropic Messages 路由，该路由通过同一条基于 bearer 认证的流式传输路径承载 Claude 模型。Claude Opus 4.7（`amazon-bedrock-mantle/claude-opus-4.7`）可通过此路由调用，并使用由提供商拥有的流式传输，因此 AWS bearer token 不会被当作 Anthropic API 密钥处理。
当你在 Mantle 提供商上固定使用一个 Anthropic Messages 模型时，OpenClaw 会对该模型使用 `anthropic-messages` API 接口，而不是 `openai-completions`。认证仍然来自 `AWS_BEARER_TOKEN_BEDROCK`（或已签发的 IAM bearer token）。
```json5
{
models: {
providers: {
"amazon-bedrock-mantle": {
models: [
{
id: "claude-opus-4.7",
name: "Claude Opus 4.7",
api: "anthropic-messages",
reasoning: true,
input: ["text", "image"],
contextWindow: 1000000,
maxTokens: 32000,
},
],
},
},
},
}
```
对于已发现的 Mantle 模型，其上下文窗口元数据会在可用时使用已知的公开限制；对于未列出的模型，则采用保守回退值，因此压缩和溢出处理能够对较新的条目正确工作，同时不会夸大未知模型的能力。
</Accordion>
<Accordion title="与 Amazon Bedrock 提供商的关系">
Bedrock Mantle 与标准的 [Amazon Bedrock](/zh-CN/providers/bedrock) 提供商是两个独立的提供商。Mantle 使用兼容 OpenAI 的 `/v1` 接口，而标准 Bedrock 提供商使用原生 Bedrock API。
Bedrock Mantle 与标准
[Amazon Bedrock](/zh-CN/providers/bedrock) 提供商是两个独立的提供商。Mantle 使用
OpenAI 兼容的 `/v1` 接口，而标准 Bedrock 提供商使用
原生 Bedrock API。
如果存在，这两个提供商会共用同一个 `AWS_BEARER_TOKEN_BEDROCK` 凭证。
在存在时，这两个提供商共享同一个 `AWS_BEARER_TOKEN_BEDROCK` 凭证。
</Accordion>
</AccordionGroup>

48
docs/zh-CN/providers/deepgram.md
View File

@ -1,30 +1,30 @@
---
read_when:
- 你想要为音频附件使用 Deepgram 语音转文本功能
- 你想要为 Voice Call 使用 Deepgram 流式转录功能
- 你希望为音频附件使用 Deepgram 语音转文本
- 你希望为 Voice Call 使用 Deepgram 流式转录
- 你需要一个快速的 Deepgram 配置示例
summary: 用于接收入站语音便笺的 Deepgram 转录
summary: 用于入站语音便笺的 Deepgram 转录
title: Deepgram
x-i18n:
generated_at: "2026-04-23T02:13:13Z"
generated_at: "2026-04-23T06:41:55Z"
model: gpt-5.4
provider: openai
source_hash: ddc55436ebae295db9bd979765fbccab3ba7f25a6f5354a4e7964d151faffa22
source_hash: 0b05f0f436a723c6e7697612afa0f8cb7e2b84a722d4ec12fae9c0bece945407
source_path: providers/deepgram.md
workflow: 15
---
# Deepgram（音频转录）
Deepgram 是一个语音转文本 API。在 OpenClaw 中，它用于通过 `tools.media.audio` 进行入站音频/语音便笺转录，以及通过 `plugins.entries.voice-call.config.streaming` 为 Voice Call 提供流式 STT。
Deepgram 是一个语音转文本 API。在 OpenClaw 中，它用于通过 `tools.media.audio` 处理入站音频/语音便笺转录，以及通过 `plugins.entries.voice-call.config.streaming` 处理 Voice Call 流式 STT。
对于批量转录，OpenClaw 会将完整的音频文件上传到 Deepgram，并将转录文本注入回复流水线（`{{Transcript}}` + `[Audio]` 块）。对于 Voice Call 流式转录，OpenClaw 会通过 Deepgram 的 WebSocket `listen` 端点转发实时 G.711 u-law 帧，并在 Deepgram 返回结果时输出部分或最终转录文本。
对于批量转录，OpenClaw 会将完整音频文件上传到 Deepgram，并将转录文本注入回复流水线（`{{Transcript}}` + `[Audio]` 块）。对于 Voice Call 流式处理，OpenClaw 会通过 Deepgram 的 WebSocket `listen` 端点转发实时 G.711 u-law 帧，并在 Deepgram 返回时发出部分或最终转录结果。
| 详情 | 值 |
| ------------- | ---------------------------------------------------------- |
| 网站 | [deepgram.com](https://deepgram.com) |
| 文档 | [developers.deepgram.com](https://developers.deepgram.com) |
| 认证 | `DEEPGRAM_API_KEY` |
| 身份验证 | `DEEPGRAM_API_KEY` |
| 默认模型 | `nova-3` |
## 入门指南
@ -53,7 +53,8 @@ Deepgram 是一个语音转文本 API。在 OpenClaw 中，它用于通过 `tool
```
</Step>
<Step title="发送语音便笺">
通过任何已连接的渠道发送一条音频消息。OpenClaw 会通过 Deepgram 对其进行转录，并将转录文本注入回复流水线。
通过任意已连接渠道发送一条音频消息。OpenClaw 会通过 Deepgram 对其进行转录，
并将转录文本注入回复流水线。
</Step>
</Steps>
@ -68,7 +69,7 @@ Deepgram 是一个语音转文本 API。在 OpenClaw 中，它用于通过 `tool
| `smart_format` | `tools.media.audio.providerOptions.deepgram.smart_format` | 启用智能格式化（可选） |
<Tabs>
<Tab title="带语言提示">
<Tab title="使用语言提示">
```json5
{
tools: {
@ -82,7 +83,7 @@ Deepgram 是一个语音转文本 API。在 OpenClaw 中，它用于通过 `tool
}
```
</Tab>
<Tab title="带 Deepgram 选项">
<Tab title="使用 Deepgram 选项">
```json5
{
tools: {
@ -116,8 +117,8 @@ Deepgram 是一个语音转文本 API。在 OpenClaw 中，它用于通过 `tool
| 语言 | `...deepgram.language` | （未设置） |
| 编码 | `...deepgram.encoding` | `mulaw` |
| 采样率 | `...deepgram.sampleRate` | `8000` |
| 端点检测 | `...deepgram.endpointingMs` | `800` |
| 中间结果 | `...deepgram.interimResults` | `true` |
| Endpointing | `...deepgram.endpointingMs` | `800` |
| 临时结果 | `...deepgram.interimResults` | `true` |
```json5
{
@ -145,34 +146,39 @@ Deepgram 是一个语音转文本 API。在 OpenClaw 中，它用于通过 `tool
```
<Note>
Voice Call 接收的是 8 kHz G.711 u-law 电话音频。Deepgram 流式提供商默认使用 `encoding: "mulaw"` 和 `sampleRate: 8000`，因此可以直接转发 Twilio 媒体帧。
Voice Call 接收的是 8 kHz G.711 u-law 电话音频。Deepgram
流式提供商默认使用 `encoding: "mulaw"` 和 `sampleRate: 8000`，因此
Twilio 媒体帧可以直接转发。
</Note>
## 说明
<AccordionGroup>
<Accordion title="认证">
认证遵循标准的提供商认证顺序。`DEEPGRAM_API_KEY` 是最简单的方式。
<Accordion title="身份验证">
身份验证遵循标准的提供商身份验证顺序。`DEEPGRAM_API_KEY` 是
最简单的方式。
</Accordion>
<Accordion title="代理和自定义端点">
使用代理时，可通过 `tools.media.audio.baseUrl` 和 `tools.media.audio.headers` 覆盖端点或请求头。
使用代理时，可通过 `tools.media.audio.baseUrl` 和
`tools.media.audio.headers` 覆盖端点或请求头。
</Accordion>
<Accordion title="输出行为">
输出遵循与其他提供商相同的音频规则（大小限制、超时、转录文本注入）。
输出遵循与其他提供商相同的音频规则（大小上限、超时、
转录文本注入）。
</Accordion>
</AccordionGroup>
## 相关内容
<CardGroup cols={2}>
<Card title="媒体工具" href="/tools/media" icon="photo-film">
<Card title="媒体工具" href="/zh-CN/tools/media-overview" icon="photo-film">
音频、图像和视频处理流水线概览。
</Card>
<Card title="配置" href="/zh-CN/gateway/configuration" icon="gear">
包含媒体工具设置在内的完整配置参考。
包括媒体工具设置在内的完整配置参考。
</Card>
<Card title="故障排除" href="/zh-CN/help/troubleshooting" icon="wrench">
常见问题和调试步骤。
常见问题与调试步骤。
</Card>
<Card title="常见问题" href="/zh-CN/help/faq" icon="circle-question">
关于 OpenClaw 设置的常见问题。

27
docs/zh-CN/providers/index.md
View File

@ -5,23 +5,24 @@ read_when:
summary: OpenClaw 支持的模型提供商（LLM）
title: 提供商目录
x-i18n:
generated_at: "2026-04-23T05:40:53Z"
generated_at: "2026-04-23T06:41:52Z"
model: gpt-5.4
provider: openai
source_hash: 5a62f8af86fa23f248163d1a23929c628f5bcc757366d0fdb12157f995f8024d
source_hash: 2b038f095480fc2cd4f7eb75500d9d8eb7b03fa90614e122744939e0ddc6996d
source_path: providers/index.md
workflow: 15
---
# 模型提供商
OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份验证，然后将默认模型设置为 `provider/model`。
OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成认证，然后将
默认模型设置为 `provider/model`。
在找聊天渠道文档（WhatsApp/Telegram/Discord/Slack/Mattermost（plugin）/等）吗？请参阅 [Channels](/zh-CN/channels)。
在找聊天渠道文档（WhatsApp/Telegram/Discord/Slack/Mattermost（插件）/ 等）？请参见 [Channels](/zh-CN/channels)。
## 快速开始
1. 使用提供商完成身份验证（通常通过 `openclaw onboard`）。
1. 使用提供商完成认证（通常通过 `openclaw onboard`）。
2. 设置默认模型：
```json5
@ -46,10 +47,10 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份
- [fal](/zh-CN/providers/fal)
- [Fireworks](/zh-CN/providers/fireworks)
- [GitHub Copilot](/zh-CN/providers/github-copilot)
- [GLM 模型](/zh-CN/providers/glm)
- [GLM models](/zh-CN/providers/glm)
- [Google（Gemini）](/zh-CN/providers/google)
- [Groq（LPU 推理）](/zh-CN/providers/groq)
- [Hugging Face（Inference）](/zh-CN/providers/huggingface)
- [Hugging Face（推理）](/zh-CN/providers/huggingface)
- [inferrs（本地模型）](/zh-CN/providers/inferrs)
- [Kilocode](/zh-CN/providers/kilocode)
- [LiteLLM（统一 Gateway 网关）](/zh-CN/providers/litellm)
@ -70,6 +71,7 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份
- [SGLang（本地模型）](/zh-CN/providers/sglang)
- [StepFun](/zh-CN/providers/stepfun)
- [Synthetic](/zh-CN/providers/synthetic)
- [腾讯云（TokenHub）](/zh-CN/providers/tencent)
- [Together AI](/zh-CN/providers/together)
- [Venice（Venice AI，注重隐私）](/zh-CN/providers/venice)
- [Vercel AI Gateway](/zh-CN/providers/vercel-ai-gateway)
@ -83,9 +85,9 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份
## 共享概览页面
- [其他内置变体](/zh-CN/providers/models#additional-bundled-provider-variants) - Anthropic Vertex、Copilot Proxy 和 Gemini CLI OAuth
- [图像生成](/zh-CN/tools/image-generation) - 共享的 `image_generate` 工具、提供商选择和故障切换
- [音乐生成](/zh-CN/tools/music-generation) - 共享的 `music_generate` 工具、提供商选择和故障切换
- [视频生成](/zh-CN/tools/video-generation) - 共享的 `video_generate` 工具、提供商选择和故障切换
- [图像生成](/zh-CN/tools/image-generation) - 共享的 `image_generate` 工具、提供商选择和故障转移
- [音乐生成](/zh-CN/tools/music-generation) - 共享的 `music_generate` 工具、提供商选择和故障转移
- [视频生成](/zh-CN/tools/video-generation) - 共享的 `video_generate` 工具、提供商选择和故障转移
## 转录提供商
@ -97,6 +99,7 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份
## 社区工具
- [Claude Max API Proxy](/zh-CN/providers/claude-max-api-proxy) - 用于 Claude 订阅凭证的社区代理（使用前请确认 Anthropic 的政策/条款）
- [Claude Max API Proxy](/zh-CN/providers/claude-max-api-proxy) - 用于 Claude 订阅凭证的社区代理（使用前请核实 Anthropic 的政策/条款）
如需查看完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，请参阅 [模型提供商](/zh-CN/concepts/model-providers)。
有关完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，
请参见 [模型提供商](/zh-CN/concepts/model-providers)。

53
docs/zh-CN/providers/litellm.md
View File

@ -1,37 +1,38 @@
---
read_when:
- 你想通过 LiteLLM 代理来路由 OpenClaw
- 你希望通过 LiteLLM 代理来路由 OpenClaw
- 你需要通过 LiteLLM 实现成本跟踪、日志记录或模型路由
summary: 通过 LiteLLM Proxy 运行 OpenClaw，以实现统一的模型访问和成本跟踪
title: LiteLLM
x-i18n:
generated_at: "2026-04-12T10:19:22Z"
generated_at: "2026-04-23T06:42:11Z"
model: gpt-5.4
provider: openai
source_hash: 766692eb83a1be83811d8e09a970697530ffdd4f3392247cfb2927fd590364a0
source_hash: 6f9665b204126861a7dbbd426b26a624e60fd219a44756cec6a023df73848cef
source_path: providers/litellm.md
workflow: 15
---
# LiteLLM
[LiteLLM](https://litellm.ai) 是一个开源的 LLM 网关，为 100 多家模型提供商提供统一 API。通过 LiteLLM 路由 OpenClaw，你可以获得集中的成本跟踪、日志记录，以及在不更改 OpenClaw 配置的情况下切换后端的灵活性。
[LiteLLM](https://litellm.ai) 是一个开源 LLM Gateway 网关，为 100 多个模型提供商提供统一 API。将 OpenClaw 通过 LiteLLM 路由后，你可以获得集中式成本跟踪、日志记录，以及在不更改 OpenClaw 配置的情况下切换后端的灵活性。
<Tip>
**为什么将 LiteLLM 与 OpenClaw 搭配使用？**
**为什么要将 LiteLLM 与 OpenClaw 一起使用？**
- **成本跟踪** — 准确查看 OpenClaw 在所有模型上的支出
- **模型路由** — 无需更改配置，即可在 Claude、GPT-4、Gemini、Bedrock 之间切换
- **虚拟密钥** — 为 OpenClaw 创建带有支出限制的密钥
- **日志记录** — 用于调试的完整请求/响应日志
- **故障切换** — 如果你的主要提供商不可用，可自动切换
</Tip>
- **成本跟踪** — 精确查看 OpenClaw 在所有模型上的花费
- **模型路由** — 无需改动配置即可在 Claude、GPT-4、Gemini、Bedrock 之间切换
- **虚拟密钥** — 为 OpenClaw 创建带有消费限制的密钥
- **日志记录** — 提供完整的请求/响应日志，便于调试
- **故障转移** — 当主提供商不可用时自动切换
</Tip>
## 快速开始
<Tabs>
<Tab title="新手引导（推荐）">
**最适合：** 以最快方式完成可用的 LiteLLM 设置。
**最适合：** 以最快路径获得可用的 LiteLLM 设置。
<Steps>
<Step title="运行新手引导">
@ -53,14 +54,14 @@ x-i18n:
litellm --model claude-opus-4-6
```
</Step>
<Step title="将 OpenClaw 指向 LiteLLM">
<Step title="让 OpenClaw 指向 LiteLLM">
```bash
export LITELLM_API_KEY="your-litellm-key"
openclaw
```
就这些。OpenClaw 现在会通过 LiteLLM 进行路由。
就这样。OpenClaw 现在会通过 LiteLLM 进行路由。
</Step>
</Steps>
@ -118,7 +119,7 @@ export LITELLM_API_KEY="sk-litellm-key"
<AccordionGroup>
<Accordion title="虚拟密钥">
为 OpenClaw 创建一个带有支出限制的专用密钥：
为 OpenClaw 创建一个带消费限制的专用密钥：
```bash
curl -X POST "http://localhost:4000/key/generate" \
@ -131,12 +132,12 @@ export LITELLM_API_KEY="sk-litellm-key"
}'
```
使用生成的密钥作为 `LITELLM_API_KEY`。
将生成的密钥用作 `LITELLM_API_KEY`。
</Accordion>
<Accordion title="模型路由">
LiteLLM 可以将模型请求路由到不同后端。在你的 LiteLLM `config.yaml` 中进行配置：
LiteLLM 可以将模型请求路由到不同后端。在你的 LiteLLM `config.yaml` 中配置：
```yaml
model_list:
@ -151,12 +152,12 @@ export LITELLM_API_KEY="sk-litellm-key"
api_key: os.environ/OPENAI_API_KEY
```
OpenClaw 会继续请求 `claude-opus-4-6`——LiteLLM 会负责路由。
OpenClaw 会继续请求 `claude-opus-4-6` —— 路由由 LiteLLM 负责处理。
</Accordion>
<Accordion title="查看用量">
查看 LiteLLM 的仪表板或 API：
检查 LiteLLM 的仪表板或 API：
```bash
# Key info
@ -172,17 +173,17 @@ export LITELLM_API_KEY="sk-litellm-key"
<Accordion title="代理行为说明">
- LiteLLM 默认运行在 `http://localhost:4000`
- OpenClaw 通过 LiteLLM 的代理式、与 OpenAI 兼容的 `/v1`
- OpenClaw 通过 LiteLLM 的代理式、兼容 OpenAI 的 `/v1`
端点进行连接
- 通过 LiteLLM 时，不会应用原生仅限 OpenAI 的请求整形：
没有 `service_tier`、没有 Responses `store`、没有提示词缓存提示，也没有
OpenAI 推理兼容负载整形
- 在自定义 LiteLLM base URLs 上，不会注入隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`）
- 原生仅限 OpenAI 的请求整形不会通过 LiteLLM 生效：
不支持 `service_tier`、不支持 Responses `store`、不支持 prompt-cache 提示，也不支持
OpenAI reasoning 兼容负载整形
- 在自定义 LiteLLM base URL 上，不会注入隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）
</Accordion>
</AccordionGroup>
<Note>
有关通用提供商配置和故障切换行为，请参阅 [模型提供商](/zh-CN/concepts/model-providers)。
有关通用提供商配置和故障转移行为，请参见 [模型提供商](/zh-CN/concepts/model-providers)。
</Note>
## 相关内容
@ -192,7 +193,7 @@ export LITELLM_API_KEY="sk-litellm-key"
LiteLLM 官方文档和 API 参考。
</Card>
<Card title="模型提供商" href="/zh-CN/concepts/model-providers" icon="layers">
所有提供商、模型引用和故障切换行为概览。
所有提供商、模型引用和故障转移行为的概览。
</Card>
<Card title="配置" href="/zh-CN/gateway/configuration" icon="gear">
完整配置参考。

66
docs/zh-CN/providers/lmstudio.md
View File

@ -1,21 +1,21 @@
---
read_when:
- 你想通过 LM Studio 使用开源模型运行 OpenClaw。
- 你想设置并配置 LM Studio。
- 你希望通过 LM Studio 使用开源模型运行 OpenClaw
- 你希望设置并配置 LM Studio
summary: 使用 LM Studio 运行 OpenClaw
title: LM Studio
x-i18n:
generated_at: "2026-04-13T07:24:19Z"
generated_at: "2026-04-23T06:42:19Z"
model: gpt-5.4
provider: openai
source_hash: 11264584e8277260d4215feb7c751329ce04f59e9228da1c58e147c21cd9ac2c
source_hash: 733527e95041da04562c0ee5d9486750d8355a255624a6d5735954de34429a5c
source_path: providers/lmstudio.md
workflow: 15
---
# LM Studio
LM Studio 是一款友好且功能强大的应用，可让你在自己的硬件上运行开放权重模型。它支持运行 llama.cpp（GGUF）或 MLX 模型（Apple Silicon）。提供 GUI 安装包，也提供无头守护进程（`llmster`）。有关产品和设置文档，请参阅 [lmstudio.ai](https://lmstudio.ai/)。
LM Studio 是一个对用户友好但功能强大的应用，可让你在自己的硬件上运行开放权重模型。它支持运行 llama.cpp（GGUF）或 MLX 模型（Apple Silicon）。既提供 GUI 安装包，也提供无头守护进程（`llmster`）。有关产品和设置文档，请参见 [lmstudio.ai](https://lmstudio.ai/)。
## 快速开始
@ -27,7 +27,7 @@ curl -fsSL https://lmstudio.ai/install.sh | bash
2. 启动服务器
请确保你要么启动桌面应用，要么使用以下命令运行守护进程：
请确保你已启动桌面应用，或使用以下命令运行守护进程：
```bash
lms daemon up
@ -37,9 +37,9 @@ lms daemon up
lms server start --port 1234
```
如果你使用的是应用，请确保已启用 JIT，以获得流畅体验。了解更多信息，请参阅 [LM Studio JIT and TTL guide](https://lmstudio.ai/docs/developer/core/ttl-and-auto-evict)。
如果你使用的是应用，请确保已启用 JIT，以获得更流畅的体验。了解更多信息，请参见 [LM Studio JIT and TTL guide](https://lmstudio.ai/docs/developer/core/ttl-and-auto-evict)。
3. OpenClaw 需要一个 LM Studio token 值。设置 `LM_API_TOKEN`：
3. OpenClaw 需要一个 LM Studio token 值。请设置 `LM_API_TOKEN`：
```bash
export LM_API_TOKEN="your-lm-studio-api-token"
@ -51,7 +51,7 @@ export LM_API_TOKEN="your-lm-studio-api-token"
export LM_API_TOKEN="placeholder-key"
```
有关 LM Studio 身份验证设置的详细信息，请参阅 [LM Studio Authentication](https://lmstudio.ai/docs/developer/core/authentication)。
有关 LM Studio 身份验证设置详情，请参见 [LM Studio Authentication](https://lmstudio.ai/docs/developer/core/authentication)。
4. 运行新手引导并选择 `LM Studio`：
@ -59,7 +59,7 @@ export LM_API_TOKEN="placeholder-key"
openclaw onboard
```
5. 在新手引导中，使用 `Default model` 提示来选择你的 LM Studio 模型。
5. 在新手引导中，使用 `Default model` 提示选择你的 LM Studio 模型。
你也可以稍后设置或更改它：
@ -67,11 +67,12 @@ openclaw onboard
openclaw models set lmstudio/qwen/qwen3.5-9b
```
LM Studio 模型键采用 `author/model-name` 格式（例如 `qwen/qwen3.5-9b`）。OpenClaw 模型引用会在前面加上提供商名称：`lmstudio/qwen/qwen3.5-9b`。你可以通过运行 `curl http://localhost:1234/api/v1/models` 并查看 `key` 字段来找到某个模型的准确键名。
LM Studio 模型键采用 `author/model-name` 格式（例如 `qwen/qwen3.5-9b`）。OpenClaw
模型引用会在前面加上提供商名称：`lmstudio/qwen/qwen3.5-9b`。你可以通过运行 `curl http://localhost:1234/api/v1/models` 并查看 `key` 字段来找到模型的准确键名。
## 非交互式新手引导
当你想以脚本方式完成设置时（CI、配置、远程引导），请使用非交互式新手引导：
当你想要以脚本方式完成设置时（CI、预配、远程引导），请使用非交互式新手引导：
```bash
openclaw onboard \
@ -80,7 +81,7 @@ openclaw onboard \
--auth-choice lmstudio
```
或者使用 API key 指定 base URL 或模型：
或者使用 API 密钥指定基础 URL 或模型：
```bash
openclaw onboard \
@ -92,20 +93,35 @@ openclaw onboard \
--custom-model-id qwen/qwen3.5-9b
```
`--custom-model-id` 接收 LM Studio 返回的模型键（例如 `qwen/qwen3.5-9b`），不包含 `lmstudio/` 提供商前缀。
`--custom-model-id` 接收 LM Studio 返回的模型键（例如 `qwen/qwen3.5-9b`），不包含
`lmstudio/` 提供商前缀。
非交互式新手引导需要 `--lmstudio-api-key`（或环境中的 `LM_API_TOKEN`）。
对于未启用身份验证的 LM Studio 服务器，任意非空 token 值都可以使用。
非交互式新手引导需要 `--lmstudio-api-key`（或环境变量中的 `LM_API_TOKEN`）。
对于不启用身份验证的 LM Studio 服务器，任意非空 token 值都可用。
`--custom-api-key` 仍然保留以兼容旧用法，但对于 LM Studio，优先使用 `--lmstudio-api-key`。
出于兼容性考虑，`--custom-api-key` 仍受支持，但对于 LM Studio，优先使用 `--lmstudio-api-key`。
这会写入 `models.providers.lmstudio`，将默认模型设置为
`lmstudio/<custom-model-id>`，并写入 `lmstudio:default` 身份验证配置文件。
交互式设置可以提示输入一个可选的首选加载上下文长度，并将其应用到保存到配置中的已发现 LM Studio 模型。
交互式设置还可以提示输入可选的首选加载上下文长度，并将其应用到保存到配置中的已发现 LM Studio 模型。
## 配置
### 流式使用量兼容性
OpenClaw 将 LM Studio 标记为与流式使用量兼容，因此在流式补全时，token 统计不再退化为未知或过期总数。当 LM Studio 不输出 OpenAI 形状的 `usage` 对象时，OpenClaw 还会从 llama.cpp 风格的 `timings.prompt_n` / `timings.predicted_n` 元数据中恢复 token 计数。
适用相同行为的其他 OpenAI 兼容本地后端：
- vLLM
- SGLang
- llama.cpp
- LocalAI
- Jan
- TabbyAPI
- text-generation-webui
### 显式配置
```json5
@ -137,14 +153,14 @@ openclaw onboard \
### 未检测到 LM Studio
请确保 LM Studio 正在运行，并且你已设置 `LM_API_TOKEN`（对于未启用身份验证的服务器，任意非空 token 值都可以使用）：
请确保 LM Studio 正在运行，并且你已设置 `LM_API_TOKEN`（对于不启用身份验证的服务器，任意非空 token 值都可用）：
```bash
# 通过桌面应用启动，或以无头方式启动：
lms server start --port 1234
```
验证 API 可访问：
验证 API 是否可访问：
```bash
curl http://localhost:1234/api/v1/models
@ -152,12 +168,12 @@ curl http://localhost:1234/api/v1/models
### 身份验证错误（HTTP 401）
如果设置过程中报告 HTTP 401，请检查你的 API key：
如果设置过程中报告 HTTP 401，请验证你的 API 密钥：
- 检查 `LM_API_TOKEN` 是否与 LM Studio 中配置的 key 匹配。
- 有关 LM Studio 身份验证设置的详细信息，请参阅 [LM Studio Authentication](https://lmstudio.ai/docs/developer/core/authentication)。
- 如果你的服务器不需要身份验证，请为 `LM_API_TOKEN` 使用任意非空 token 值。
- 检查 `LM_API_TOKEN` 是否与 LM Studio 中配置的密钥一致。
- 有关 LM Studio 身份验证设置详情，请参见 [LM Studio Authentication](https://lmstudio.ai/docs/developer/core/authentication)。
- 如果你的服务器不要求身份验证，请为 `LM_API_TOKEN` 使用任意非空 token 值。
### 即时模型加载
LM Studio 支持即时（JIT）模型加载，即模型会在第一次请求时加载。请确保已启用此功能，以避免出现“Model not loaded”错误。
LM Studio 支持即时（JIT）模型加载，即模型会在第一次请求时加载。请确保你已启用此功能，以避免出现“Model not loaded”错误。

68
docs/zh-CN/providers/mistral.md
View File

@ -1,26 +1,26 @@
---
read_when:
- 你想在 OpenClaw 中使用 Mistral 模型
- 你想为 Voice Call 使用 Voxtral 实时转录功能
- 你需要 Mistral API 密钥新手引导和模型参考信息
summary: 使用 Mistral 模型和 Voxtral 转录功能与 OpenClaw 配合使用
- 你想为 Voice Call 使用 Voxtral 实时转录
- 你需要 Mistral API 密钥新手引导和模型参考
summary: 在 OpenClaw 中使用 Mistral 模型和 Voxtral 转录
title: Mistral
x-i18n:
generated_at: "2026-04-23T02:13:15Z"
generated_at: "2026-04-23T06:42:22Z"
model: gpt-5.4
provider: openai
source_hash: 8aec3c47fee12588b28ea2b652b89f0ff136399d25ca47174d7cb6e7b5d5d97f
source_hash: cbf2f8926a1e8c877a12ea395e96622ff3b337ffa1368277c03abbfb881b18cf
source_path: providers/mistral.md
workflow: 15
---
# Mistral
OpenClaw 支持 Mistral，用于文本/图像模型路由（`mistral/...`）以及在媒体理解中通过 Voxtral 进行音频转录。
OpenClaw 同时支持将 Mistral 用于文本/图像模型路由（`mistral/...`）以及通过 Voxtral 在媒体理解中进行音频转录。
Mistral 也可用于记忆嵌入（`memorySearch.provider = "mistral"`）。
- 提供商：`mistral`
- 凭证：`MISTRAL_API_KEY`
- 认证：`MISTRAL_API_KEY`
- API：Mistral Chat Completions（`https://api.mistral.ai/v1`）
## 入门指南
@ -60,19 +60,19 @@ Mistral 也可用于记忆嵌入（`memorySearch.provider = "mistral"`）。
OpenClaw 当前内置了以下 Mistral 目录：
| 模型引用 | 输入 | 上下文 | 最大输出 | 说明 |
| 模型引用 | 输入 | 上下文 | 最大输出 | 说明 |
| -------------------------------- | ----------- | ------- | ---------- | ---------------------------------------------------------------- |
| `mistral/mistral-large-latest` | text, image | 262,144 | 16,384 | 默认模型 |
| `mistral/mistral-medium-2508` | text, image | 262,144 | 8,192 | Mistral Medium 3.1 |
| `mistral/mistral-small-latest` | text, image | 128,000 | 16,384 | Mistral Small 4；可通过 API `reasoning_effort` 调整推理强度 |
| `mistral/pixtral-large-latest` | text, image | 128,000 | 32,768 | Pixtral |
| `mistral/codestral-latest` | text | 256,000 | 4,096 | 编码 |
| `mistral/devstral-medium-latest` | text | 262,144 | 32,768 | Devstral 2 |
| `mistral/magistral-small` | text | 128,000 | 40,000 | 启用推理 |
| `mistral/mistral-large-latest` | text, image | 262,144 | 16,384 | 默认模型 |
| `mistral/mistral-medium-2508` | text, image | 262,144 | 8,192 | Mistral Medium 3.1 |
| `mistral/mistral-small-latest` | text, image | 128,000 | 16,384 | Mistral Small 4；可通过 API `reasoning_effort` 调整推理强度 |
| `mistral/pixtral-large-latest` | text, image | 128,000 | 32,768 | Pixtral |
| `mistral/codestral-latest` | text | 256,000 | 4,096 | 编码 |
| `mistral/devstral-medium-latest` | text | 262,144 | 32,768 | Devstral 2 |
| `mistral/magistral-small` | text | 128,000 | 40,000 | 启用推理 |
## 音频转录（Voxtral）
通过媒体理解流水线使用 Voxtral 进行批量音频转录。
通过媒体理解管线使用 Voxtral 进行批量音频转录。
```json5
{
@ -95,13 +95,13 @@ OpenClaw 当前内置了以下 Mistral 目录：
内置的 `mistral` 插件会将 Voxtral Realtime 注册为 Voice Call 流式 STT 提供商。
| 设置 | 配置路径 | 默认值 |
| 设置 | 配置路径 | 默认值 |
| ------------ | ---------------------------------------------------------------------- | --------------------------------------- |
| API 密钥 | `plugins.entries.voice-call.config.streaming.providers.mistral.apiKey` | 回退到 `MISTRAL_API_KEY` |
| 模型 | `...mistral.model` | `voxtral-mini-transcribe-realtime-2602` |
| 编码 | `...mistral.encoding` | `pcm_mulaw` |
| 采样率 | `...mistral.sampleRate` | `8000` |
| 目标延迟 | `...mistral.targetStreamingDelayMs` | `800` |
| API 密钥 | `plugins.entries.voice-call.config.streaming.providers.mistral.apiKey` | 回退到 `MISTRAL_API_KEY` |
| 模型 | `...mistral.model` | `voxtral-mini-transcribe-realtime-2602` |
| 编码 | `...mistral.encoding` | `pcm_mulaw` |
| 采样率 | `...mistral.sampleRate` | `8000` |
| 目标延迟 | `...mistral.targetStreamingDelayMs` | `800` |
```json5
{
@ -127,24 +127,24 @@ OpenClaw 当前内置了以下 Mistral 目录：
```
<Note>
OpenClaw 默认将 Mistral 实时 STT 设置为 `pcm_mulaw` 和 8 kHz，这样 Voice Call 就能直接转发 Twilio 媒体帧。仅当你的上游流已经是原始 PCM 时，才使用 `encoding: "pcm_s16le"` 和匹配的 `sampleRate`。
OpenClaw 默认将 Mistral 实时 STT 设置为 8 kHz 的 `pcm_mulaw`，这样 Voice Call 就可以直接转发 Twilio 媒体帧。只有在你的上游流已经是原始 PCM 时，才使用 `encoding: "pcm_s16le"` 和匹配的 `sampleRate`。
</Note>
## 高级配置
<AccordionGroup>
<Accordion title="可调推理（mistral-small-latest）">
`mistral/mistral-small-latest` 映射到 Mistral Small 4，并通过 `reasoning_effort` 支持在 Chat Completions API 上进行[可调推理](https://docs.mistral.ai/capabilities/reasoning/adjustable)（`none` 会尽量减少输出中的额外思考；`high` 会在最终答案前展示完整的思考轨迹）。
`mistral/mistral-small-latest` 对应 Mistral Small 4，并支持通过 Chat Completions API 的 `reasoning_effort` 使用[可调推理](https://docs.mistral.ai/capabilities/reasoning/adjustable)（`none` 会尽量减少输出中的额外思考；`high` 会在最终答案前展示完整的思考轨迹）。
OpenClaw 会将会话 **thinking** 级别映射到 Mistral 的 API：
OpenClaw 会将会话的 **thinking** 级别映射到 Mistral 的 API：
| OpenClaw thinking 级别 | Mistral `reasoning_effort` |
| ---------------------------------------------- | -------------------------- |
| **off** / **minimal** | `none` |
| **low** / **medium** / **high** / **xhigh** / **adaptive** / **max** | `high` |
| OpenClaw thinking 级别 | Mistral `reasoning_effort` |
| ------------------------------------------------ | -------------------------- |
| **off** / **minimal** | `none` |
| **low** / **medium** / **high** / **xhigh** / **adaptive** / **max** | `high` |
<Note>
其他内置 Mistral 目录模型不会使用这个参数。当你想要使用 Mistral 原生的推理优先行为时，请继续使用 `magistral-*` 模型。
其他内置 Mistral 目录模型不使用此参数。如果你希望使用 Mistral 原生的以推理优先为主的行为，请继续使用 `magistral-*` 模型。
</Note>
</Accordion>
@ -160,8 +160,8 @@ OpenClaw 默认将 Mistral 实时 STT 设置为 `pcm_mulaw` 和 8 kHz，这样 V
</Accordion>
<Accordion title="凭证和基础 URL">
- Mistral 凭证使用 `MISTRAL_API_KEY`。
<Accordion title="认证和基础 URL">
- Mistral 认证使用 `MISTRAL_API_KEY`。
- 提供商基础 URL 默认为 `https://api.mistral.ai/v1`。
- 新手引导默认模型为 `mistral/mistral-large-latest`。
- Z.AI 使用你的 API 密钥进行 Bearer 认证。
@ -172,9 +172,9 @@ OpenClaw 默认将 Mistral 实时 STT 设置为 `pcm_mulaw` 和 8 kHz，这样 V
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用和故障切换行为。
选择提供商、模型引用和故障转移行为。
</Card>
<Card title="媒体理解" href="/tools/media-understanding" icon="microphone">
<Card title="媒体理解" href="/zh-CN/nodes/media-understanding" icon="microphone">
音频转录设置和提供商选择。
</Card>
</CardGroup>

128
docs/zh-CN/providers/moonshot.md
View File

@ -1,25 +1,25 @@
---
read_when:
- 你想要设置 Moonshot K2（Moonshot Open Platform）与 Kimi Coding 的对比配置
- 你需要了解单独的端点、密钥和模型引用
- 你想要适用于任一提供商的可复制粘贴配置
summary: 配置 Moonshot K2 与 Kimi Coding（使用单独的提供商 + 密钥）
- 你想设置 Moonshot K2（Moonshot Open Platform）与 Kimi Coding
- 你需要了解独立的端点、密钥和模型引用
- 你想要适用于任一提供商的可复制 / 粘贴配置
summary: 配置 Moonshot K2 与 Kimi Coding（独立的提供商 + 密钥）
title: Moonshot AI
x-i18n:
generated_at: "2026-04-21T02:12:32Z"
generated_at: "2026-04-23T06:42:20Z"
model: gpt-5.4
provider: openai
source_hash: 5a04b0c45d55dbf8d56a04a1811f0850b800842ea501b212d44b53ff0680b5a2
source_hash: d9a726df279bfc0351b8ab224e682b5c1e6e360440659e33e8568a94c351df51
source_path: providers/moonshot.md
workflow: 15
---
# Moonshot AI（Kimi）
Moonshot 通过与 OpenAI 兼容的端点提供 Kimi API。请配置该提供商，并将默认模型设置为 `moonshot/kimi-k2.6`，或者使用 `kimi/kimi-code` 作为 Kimi Coding。
Moonshot 提供带有 OpenAI 兼容端点的 Kimi API。配置该提供商并将默认模型设置为 `moonshot/kimi-k2.6`，或使用 `kimi/kimi-code` 来启用 Kimi Coding。
<Warning>
Moonshot 和 Kimi Coding 是**单独的提供商**。密钥不能互换，端点不同，模型引用也不同（`moonshot/...` 与 `kimi/...`）。
Moonshot 和 Kimi Coding 是**独立的提供商**。密钥不能互换，端点不同，模型引用也不同（`moonshot/...` vs `kimi/...`）。
</Warning>
## 内置模型目录
@ -28,19 +28,19 @@ Moonshot 和 Kimi Coding 是**单独的提供商**。密钥不能互换，端点
| Model ref | 名称 | 推理 | 输入 | 上下文 | 最大输出 |
| --------------------------------- | ---------------------- | ---- | ----------- | ------ | -------- |
| `moonshot/kimi-k2.6` | Kimi K2.6 | 否 | text, image | 262,144 | 262,144 |
| `moonshot/kimi-k2.5` | Kimi K2.5 | 否 | text, image | 262,144 | 262,144 |
| `moonshot/kimi-k2-thinking` | Kimi K2 Thinking | 是 | text | 262,144 | 262,144 |
| `moonshot/kimi-k2-thinking-turbo` | Kimi K2 Thinking Turbo | 是 | text | 262,144 | 262,144 |
| `moonshot/kimi-k2-turbo` | Kimi K2 Turbo | 否 | text | 256,000 | 16,384 |
| `moonshot/kimi-k2.6` | Kimi K2.6 | 否 | text, image | 262,144 | 262,144 |
| `moonshot/kimi-k2.5` | Kimi K2.5 | 否 | text, image | 262,144 | 262,144 |
| `moonshot/kimi-k2-thinking` | Kimi K2 Thinking | 是 | text | 262,144 | 262,144 |
| `moonshot/kimi-k2-thinking-turbo` | Kimi K2 Thinking Turbo | 是 | text | 262,144 | 262,144 |
| `moonshot/kimi-k2-turbo` | Kimi K2 Turbo | 否 | text | 256,000 | 16,384 |
[//]: # "moonshot-kimi-k2-ids:end"
当前由 Moonshot 托管的 K2 模型，其内置成本估算使用 Moonshot 公布的按量付费价格：Kimi K2.6 为 $0.16/MTok 缓存命中、$0.95/MTok 输入、$4.00/MTok 输出；Kimi K2.5 为 $0.10/MTok 缓存命中、$0.60/MTok 输入、$3.00/MTok 输出。其他旧版目录条目会保留零成本占位值，除非你在配置中覆盖它们。
当前由 Moonshot 托管的 K2 模型，其内置成本估算使用 Moonshot 公布的按量计费价格：Kimi K2.6 为 $0.16/MTok 缓存命中、$0.95/MTok 输入、$4.00/MTok 输出；Kimi K2.5 为 $0.10/MTok 缓存命中、$0.60/MTok 输入、$3.00/MTok 输出。其他旧目录条目会保留零成本占位值，除非你在配置中覆盖它们。
## 入门指南
选择你的提供商并按步骤完成设置。
选择你的提供商，并按步骤完成设置。
<Tabs>
<Tab title="Moonshot API">
@ -48,17 +48,17 @@ Moonshot 和 Kimi Coding 是**单独的提供商**。密钥不能互换，端点
<Steps>
<Step title="选择你的端点区域">
| 鉴权选项 | 端点 | 区域 |
| ---------------------- | ---------------------------- | ---- |
| `moonshot-api-key` | `https://api.moonshot.ai/v1` | 国际 |
| `moonshot-api-key-cn` | `https://api.moonshot.cn/v1` | 中国 |
| 认证选项 | 端点 | 区域 |
| -------------------- | ------------------------------ | ---- |
| `moonshot-api-key` | `https://api.moonshot.ai/v1` | 国际 |
| `moonshot-api-key-cn` | `https://api.moonshot.cn/v1` | 中国 |
</Step>
<Step title="运行新手引导">
```bash
openclaw onboard --auth-choice moonshot-api-key
```
或者，如果使用中国端点：
或者使用中国端点：
```bash
openclaw onboard --auth-choice moonshot-api-key-cn
@ -75,13 +75,13 @@ Moonshot 和 Kimi Coding 是**单独的提供商**。密钥不能互换，端点
}
```
</Step>
<Step title="验证模型是否可用">
<Step title="验证模型可用">
```bash
openclaw models list --provider moonshot
```
</Step>
<Step title="运行实时冒烟测试">
当你想在不影响正常会话的情况下验证模型访问和成本跟踪时，请使用独立的状态目录：
当你想验证模型访问和成本跟踪，而不影响正常会话时，请使用隔离的状态目录：
```bash
OPENCLAW_CONFIG_PATH=/tmp/openclaw-kimi/openclaw.json \
@ -93,8 +93,8 @@ Moonshot 和 Kimi Coding 是**单独的提供商**。密钥不能互换，端点
--json
```
JSON 响应应显示 `provider: "moonshot"` 和
`model: "kimi-k2.6"`。当 Moonshot 返回用量元数据时，助手转录条目会在 `usage.cost` 下存储标准化后的 token 用量以及预估成本。
JSON 响应应报告 `provider: "moonshot"` 和
`model: "kimi-k2.6"`。当 Moonshot 返回使用量元数据时，助手转录条目会在 `usage.cost` 下存储标准化后的 token 使用量和估算成本。
</Step>
</Steps>
@ -182,10 +182,10 @@ Moonshot 和 Kimi Coding 是**单独的提供商**。密钥不能互换，端点
</Tab>
<Tab title="Kimi Coding">
**最适合：** 通过 Kimi Coding 端点执行以代码为重点的任务。
**最适合：** 通过 Kimi Coding 端点处理以代码为重点的任务。
<Note>
Kimi Coding 使用与 Moonshot 不同的 API 密钥和提供商前缀（`kimi/...`），而 Moonshot 使用 `moonshot/...`。旧版模型引用 `kimi/k2p5` 仍然作为兼容性 id 被接受。
Kimi Coding 使用与 Moonshot 不同的 API key 和提供商前缀（`kimi/...` 而非 `moonshot/...`）。旧模型引用 `kimi/k2p5` 仍作为兼容 id 被接受。
</Note>
<Steps>
@ -205,7 +205,7 @@ Moonshot 和 Kimi Coding 是**单独的提供商**。密钥不能互换，端点
}
```
</Step>
<Step title="验证模型是否可用">
<Step title="验证模型可用">
```bash
openclaw models list --provider kimi
```
@ -233,7 +233,7 @@ Moonshot 和 Kimi Coding 是**单独的提供商**。密钥不能互换，端点
## Kimi web 搜索
OpenClaw 还内置了 **Kimi** 作为 `web_search` 提供商，其底层由 Moonshot web 搜索支持。
OpenClaw 还内置了 **Kimi** 作为 `web_search` 提供商，由 Moonshot web 搜索提供支持。
<Steps>
<Step title="运行交互式 web 搜索设置">
@ -241,17 +241,17 @@ OpenClaw 还内置了 **Kimi** 作为 `web_search` 提供商，其底层由 Moon
openclaw configure --section web
```
在 web 搜索部分选择 **Kimi**，以存储
在 web 搜索部分选择 **Kimi**，以保存
`plugins.entries.moonshot.config.webSearch.*`。
</Step>
<Step title="配置 web 搜索区域和模型">
交互式设置会提示以下内容：
| 设置 | 选项 |
| 设置 | 选项 |
| ------------------- | -------------------------------------------------------------------- |
| API 区域 | `https://api.moonshot.ai/v1`（国际）或 `https://api.moonshot.cn/v1`（中国） |
| Web 搜索模型 | 默认为 `kimi-k2.6` |
| API 区域 | `https://api.moonshot.ai/v1`（国际）或 `https://api.moonshot.cn/v1`（中国） |
| Web 搜索模型 | 默认为 `kimi-k2.6` |
</Step>
</Steps>
@ -283,7 +283,7 @@ OpenClaw 还内置了 **Kimi** 作为 `web_search` 提供商，其底层由 Moon
}
```
## 高级
## 高级设置
<AccordionGroup>
<Accordion title="原生 thinking 模式">
@ -292,7 +292,7 @@ OpenClaw 还内置了 **Kimi** 作为 `web_search` 提供商，其底层由 Moon
- `thinking: { type: "enabled" }`
- `thinking: { type: "disabled" }`
通过 `agents.defaults.models.<provider/model>.params` 为每个模型配置：
通过 `agents.defaults.models.<provider/model>.params` 按模型配置：
```json5
{
@ -312,16 +312,16 @@ OpenClaw 还内置了 **Kimi** 作为 `web_search` 提供商，其底层由 Moon
OpenClaw 还会为 Moonshot 映射运行时 `/think` 级别：
| `/think` 级别 | Moonshot 行为 |
| `/think` 级别 | Moonshot 行为 |
| -------------------- | -------------------------- |
| `/think off` | `thinking.type=disabled` |
| 任何非 off 级别 | `thinking.type=enabled` |
<Warning>
当启用 Moonshot thinking 时，`tool_choice` 必须为 `auto` 或 `none`。为保证兼容性，OpenClaw 会将不兼容的 `tool_choice` 值标准化为 `auto`。
启用 Moonshot thinking 时，`tool_choice` 必须是 `auto` 或 `none`。OpenClaw 会将不兼容的 `tool_choice` 值标准化为 `auto` 以确保兼容性。
</Warning>
Kimi K2.6 还接受一个可选的 `thinking.keep` 字段，用于控制 `reasoning_content` 在多轮对话中的保留方式。将其设置为 `"all"` 可在多轮中保留完整推理；省略它（或保持为 `null`）则使用服务器默认策略。OpenClaw 只会为 `moonshot/kimi-k2.6` 转发 `thinking.keep`，并会从其他模型中移除该字段。
Kimi K2.6 还接受一个可选的 `thinking.keep` 字段，用于控制 `reasoning_content` 在多轮对话中的保留方式。将其设置为 `"all"` 可在多轮中保留完整推理；省略它（或保留为 `null`）则使用服务器默认策略。OpenClaw 仅会为 `moonshot/kimi-k2.6` 转发 `thinking.keep`，并会从其他模型中移除它。
```json5
{
@ -341,25 +341,45 @@ OpenClaw 还内置了 **Kimi** 作为 `web_search` 提供商，其底层由 Moon
</Accordion>
<Accordion title="流式用量兼容性">
原生 Moonshot 端点（`https://api.moonshot.ai/v1` 和
`https://api.moonshot.cn/v1`）在共享的 `openai-completions` 传输协议上声明支持流式用量兼容性。OpenClaw 会基于端点能力进行判断，因此，指向相同原生 Moonshot 主机的兼容自定义提供商 id 也会继承相同的流式用量行为。
<Accordion title="工具调用 id 清洗">
Moonshot Kimi 在 OpenAI 兼容传输上提供原生 `tool_call` id，其格式类似 `functions.<name>:<index>`。OpenClaw 不再为 Moonshot 严格清洗这些 id，因此当服务层根据原始工具定义匹配被改写的 id 时，经由 Kimi K2.6 的多轮智能体流程可以在 2 - 3 轮工具调用之后继续正常工作。
使用内置的 K2.6 定价时，包含输入、输出和缓存读取 token 的流式用量，也会被转换为本地预估美元成本，用于 `/status`、`/usage full`、`/usage cost` 以及基于转录的会话计费统计。
如果某个自定义 OpenAI 兼容提供商需要之前的行为，请在提供商条目上设置 `sanitizeToolCallIds: true`。该标志位于共享的 `openai-compatible` replay 系列上；Moonshot 默认接入的是选择退出行为。
```json5
{
models: {
providers: {
"my-kimi-proxy": {
api: "openai-completions",
sanitizeToolCallIds: true,
},
},
},
}
```
</Accordion>
<Accordion title="端点与模型引用对照">
| 提供商 | 模型引用前缀 | 端点 | 鉴权环境变量 |
| ------------- | ---------------- | ----------------------------- | -------------------- |
| Moonshot | `moonshot/` | `https://api.moonshot.ai/v1` | `MOONSHOT_API_KEY` |
| Moonshot CN | `moonshot/` | `https://api.moonshot.cn/v1` | `MOONSHOT_API_KEY` |
| Kimi Coding | `kimi/` | Kimi Coding 端点 | `KIMI_API_KEY` |
| Web 搜索 | N/A | 与 Moonshot API 区域相同 | `KIMI_API_KEY` or `MOONSHOT_API_KEY` |
<Accordion title="流式使用量兼容性">
原生 Moonshot 端点（`https://api.moonshot.ai/v1` 和
`https://api.moonshot.cn/v1`）会在共享的 `openai-completions` 传输上声明流式使用量兼容性。OpenClaw 基于端点能力来判断，因此指向相同原生 Moonshot 主机的兼容自定义提供商 id 也会继承相同的流式使用量行为。
- Kimi web 搜索使用 `KIMI_API_KEY` 或 `MOONSHOT_API_KEY`，默认端点为 `https://api.moonshot.ai/v1`，默认模型为 `kimi-k2.6`。
- 如有需要，可在 `models.providers` 中覆盖定价和上下文元数据。
- 如果 Moonshot 为某个模型发布了不同的上下文限制，请相应调整 `contextWindow`。
配合内置的 K2.6 定价，包含输入、输出和缓存读取 token 的流式使用量，也会被转换为本地估算的 USD 成本，用于 `/status`、`/usage full`、`/usage cost` 和基于转录的会话计费。
</Accordion>
<Accordion title="端点和模型引用参考">
| Provider | 模型引用前缀 | 端点 | 认证环境变量 |
| ---------- | ---------------- | ----------------------------- | ------------------- |
| Moonshot | `moonshot/` | `https://api.moonshot.ai/v1` | `MOONSHOT_API_KEY` |
| Moonshot CN | `moonshot/` | `https://api.moonshot.cn/v1` | `MOONSHOT_API_KEY` |
| Kimi Coding | `kimi/` | Kimi Coding 端点 | `KIMI_API_KEY` |
| Web 搜索 | N/A | 与 Moonshot API 区域相同 | `KIMI_API_KEY` 或 `MOONSHOT_API_KEY` |
- Kimi web 搜索使用 `KIMI_API_KEY` 或 `MOONSHOT_API_KEY`，并默认使用 `https://api.moonshot.ai/v1` 和模型 `kimi-k2.6`。
- 如有需要，请在 `models.providers` 中覆盖定价和上下文元数据。
- 如果 Moonshot 为某个模型公布了不同的上下文限制，请相应调整 `contextWindow`。
</Accordion>
</AccordionGroup>
@ -370,13 +390,13 @@ OpenClaw 还内置了 **Kimi** 作为 `web_search` 提供商，其底层由 Moon
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用和故障切换行为。
</Card>
<Card title="Web 搜索" href="/tools/web-search" icon="magnifying-glass">
配置 web 搜索提供商，包括 Kimi。
<Card title="Web 搜索" href="/zh-CN/tools/web" icon="magnifying-glass">
配置包括 Kimi 在内的 web 搜索提供商。
</Card>
<Card title="配置参考" href="/zh-CN/gateway/configuration-reference" icon="gear">
提供商、模型和插件的完整配置 schema。
</Card>
<Card title="Moonshot Open Platform" href="https://platform.moonshot.ai" icon="globe">
Moonshot API 密钥管理与文档。
Moonshot API key 管理和文档。
</Card>
</CardGroup>

166
docs/zh-CN/providers/openai.md
View File

@ -3,52 +3,52 @@ read_when:
- 你想在 OpenClaw 中使用 OpenAI 模型
- 你想使用 Codex 订阅认证，而不是 API 密钥
- 你需要更严格的 GPT-5 智能体执行行为
summary: 在 OpenClaw 中使用 OpenAI 的 API 密钥或 Codex 订阅
summary: 在 OpenClaw 中通过 API 密钥或 Codex 订阅使用 OpenAI
title: OpenAI
x-i18n:
generated_at: "2026-04-23T01:23:55Z"
generated_at: "2026-04-23T06:42:29Z"
model: gpt-5.4
provider: openai
source_hash: 775a937680731ff09181dd58d2be1ca1a751c9193ac299ba6657266490a6a9b7
source_hash: c3d847e53c2faee5363071dfdcb1f4150b64577674161e000844f579482198d1
source_path: providers/openai.md
workflow: 15
---
# OpenAI
OpenAI 提供用于 GPT 模型的开发者 API。OpenClaw 支持两种认证方式：
OpenAI 提供 GPT 模型的开发者 API。OpenClaw 支持两种认证路径：
- **API 密钥** — 通过按量计费直接访问 OpenAI Platform（`openai/*` 模型）
- **Codex 订阅** — 通过 ChatGPT/Codex 登录并使用订阅访问（`openai-codex/*` 模型）
- **API 密钥** —— 通过基于用量计费的 OpenAI Platform 直接访问（`openai/*` 模型）
- **Codex 订阅** —— 通过 ChatGPT/Codex 登录并使用订阅访问（`openai-codex/*` 模型）
OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OAuth。
## OpenClaw 功能覆盖范围
| OpenAI 能力 | OpenClaw 表面 | 状态 |
| OpenAI 能力 | OpenClaw 接口 | 状态 |
| ------------------------- | ----------------------------------------- | ------------------------------------------------------ |
| 聊天 / Responses | `openai/<model>` 模型提供商 | 是 |
| Chat / Responses | `openai/<model>` 模型提供商 | 是 |
| Codex 订阅模型 | `openai-codex/<model>` 模型提供商 | 是 |
| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，启用 Web 搜索且未固定提供商时 |
| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，在启用 Web 搜索且未固定提供商时 |
| 图像 | `image_generate` | 是 |
| 视频 | `video_generate` | 是 |
| 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 |
| 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 |
| 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 |
| 实时语音 | Voice Call `realtime.provider: "openai"` | 是 |
| Embeddings | memory embedding 提供商 | 是 |
| Embeddings | 记忆嵌入提供商 | 是 |
## 入门指南
选择你偏好的认证方式，并按照设置步骤操作。
选择你偏好的认证方式，并按步骤进行设置。
<Tabs>
<Tab title="API 密钥（OpenAI Platform）">
**最适合：** 直接访问 API 和按量计费。
**最适合：** 直接 API 访问和基于用量的计费。
<Steps>
<Step title="获取你的 API 密钥">
在 [OpenAI Platform 控制台](https://platform.openai.com/api-keys) 中创建或复制一个 API 密钥。
在 [OpenAI Platform dashboard](https://platform.openai.com/api-keys) 创建或复制一个 API 密钥。
</Step>
<Step title="运行新手引导">
```bash
@ -70,7 +70,7 @@ x-i18n:
### 路由摘要
| Model ref | Route | Auth |
| 模型引用 | 路由 | 认证 |
|-----------|-------|------|
| `openai/gpt-5.4` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
| `openai/gpt-5.4-pro` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
@ -89,7 +89,7 @@ x-i18n:
```
<Warning>
OpenClaw **不会** 在直接 API 路径上公开 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型。Spark 仅限 Codex。
OpenClaw **不会**在直接 API 路径上暴露 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型。Spark 仅限 Codex。
</Warning>
</Tab>
@ -108,6 +108,12 @@ x-i18n:
```bash
openclaw models auth login --provider openai-codex
```
对于无头环境或不适合回调的环境，可添加 `--device-code`，通过 ChatGPT 设备码流程登录，而不是使用 localhost 浏览器回调：
```bash
openclaw models auth login --provider openai-codex --device-code
```
</Step>
<Step title="设置默认模型">
```bash
@ -123,13 +129,13 @@ x-i18n:
### 路由摘要
| Model ref | Route | Auth |
| 模型引用 | 路由 | 认证 |
|-----------|-------|------|
| `openai-codex/gpt-5.4` | ChatGPT/Codex OAuth | Codex 登录 |
| `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Codex 登录（取决于授权资格） |
| `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Codex 登录（取决于 entitlement） |
<Note>
此路由与 `openai/gpt-5.4` 有意分离。直接 Platform 访问请使用带 API 密钥的 `openai/*`，Codex 订阅访问请使用 `openai-codex/*`。
此路由有意与 `openai/gpt-5.4` 分开。若要直接访问 Platform，请将 API 密钥用于 `openai/*`；若要使用 Codex 订阅访问，请使用 `openai-codex/*`。
</Note>
### 配置示例
@ -140,9 +146,9 @@ x-i18n:
}
```
<Tip>
如果新手引导复用了现有的 Codex CLI 登录，这些凭证仍由 Codex CLI 管理。过期后，OpenClaw 会先重新读取外部 Codex 来源，再把刷新的凭证写回 Codex 存储。
</Tip>
<Note>
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备码流程登录 —— OpenClaw 会在它自己的智能体认证存储中管理生成的凭证。
</Note>
### 上下文窗口上限
@ -153,7 +159,7 @@ x-i18n:
- 原生 `contextWindow`：`1050000`
- 默认运行时 `contextTokens` 上限：`272000`
较小的默认上限在实践中通常具有更好的延迟和质量表现。你可以用 `contextTokens` 覆盖它：
实践中，较小的默认上限通常具有更好的延迟和质量特性。你可以通过 `contextTokens` 覆盖它：
```json5
{
@ -168,7 +174,7 @@ x-i18n:
```
<Note>
使用 `contextWindow` 来声明原生模型元数据。使用 `contextTokens` 来限制运行时上下文预算。
使用 `contextWindow` 声明模型的原生元数据。使用 `contextTokens` 限制运行时上下文预算。
</Note>
</Tab>
@ -197,15 +203,16 @@ x-i18n:
```
<Note>
有关共享工具参数、提供商选择和故障转移行为，请参见 [图像生成](/zh-CN/tools/image-generation)。
有关共享工具参数、提供商选择和故障转移行为，请参见 [Image Generation](/zh-CN/tools/image-generation)。
</Note>
`gpt-image-2` 是 OpenAI 文生图生成和图像编辑的默认模型。`gpt-image-1` 仍可作为显式模型覆盖使用，但新的 OpenAI 图像工作流应使用 `openai/gpt-image-2`。
`gpt-image-2` 是 OpenAI 文生图和图像编辑的默认模型。`gpt-image-1`
仍可作为显式模型覆盖使用，但新的 OpenAI 图像工作流应使用 `openai/gpt-image-2`。
生成：
```
/tool image_generate model=openai/gpt-image-2 prompt="为 macOS 上的 OpenClaw 制作一张精致的发布海报" size=3840x2160 count=1
/tool image_generate model=openai/gpt-image-2 prompt="为 OpenClaw 在 macOS 上发布制作一张精致的启动海报" size=3840x2160 count=1
```
编辑：
@ -221,10 +228,10 @@ x-i18n:
| 能力 | 值 |
| ---------------- | --------------------------------------------------------------------------------- |
| 默认模型 | `openai/sora-2` |
| 模式 | 文生视频、图生视频、单视频编辑 |
| 模式 | 文本生成视频、图像生成视频、单视频编辑 |
| 参考输入 | 1 张图像或 1 个视频 |
| 尺寸覆盖 | 支持 |
| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并产生工具警告 |
| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并给出工具警告 |
```json5
{
@ -237,20 +244,20 @@ x-i18n:
```
<Note>
有关共享工具参数、提供商选择和故障转移行为，请参见 [视频生成](/zh-CN/tools/video-generation)。
有关共享工具参数、提供商选择和故障转移行为，请参见 [Video Generation](/zh-CN/tools/video-generation)。
</Note>
## GPT-5 提示词扩展
## GPT-5 提示词贡献
OpenClaw 会为跨提供商的 GPT-5 系列运行添加共享的 GPT-5 提示词扩展。它按模型 id 应用，因此 `openai/gpt-5.4`、`openai-codex/gpt-5.4`、`openrouter/openai/gpt-5.4`、`opencode/gpt-5.4` 以及其他兼容的 GPT-5 引用都会接收相同的叠加层。较旧的 GPT-4.x 模型不会应用该扩展。
OpenClaw 会为跨提供商的 GPT-5 系列运行添加一个共享的 GPT-5 提示词贡献。它按模型 ID 应用，因此 `openai/gpt-5.4`、`openai-codex/gpt-5.4`、`openrouter/openai/gpt-5.4`、`opencode/gpt-5.4` 以及其他兼容的 GPT-5 引用都会获得同一层覆盖。较早的 GPT-4.x 模型则不会。
内置的原生 Codex harness 提供商（`codex/*`）通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和心跳叠加层，因此 `codex/gpt-5.x` 会话会保持相同的后续跟进行为和主动心跳指引，即使 Codex 拥有 harness 提示词的其余部分也是如此。
内置的原生 Codex harness 提供商（`codex/*`）通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和心跳覆盖，因此 `codex/gpt-5.x` 会话即使其余 harness 提示词由 Codex 自行管理，也会保持相同的执行跟进和主动心跳指导。
GPT-5 扩展添加了一个带标签的行为契约，用于规定角色持续性、执行安全、工具纪律、输出形态、完成检查和验证。特定渠道的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。对于匹配的模型，GPT-5 指引始终启用。友好的交互风格层是独立的，并且可配置。
GPT-5 贡献为人设持久性、执行安全、工具纪律、输出形状、完成检查和验证添加了一个带标签的行为契约。渠道特定的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站投递策略中。对于匹配的模型，GPT-5 指导始终启用。友好交互风格层是单独的，并且可配置。
| 值 | 效果 |
| ---------------------- | ------------------------------------------- |
| `"friendly"`（默认） | 启用友好的交互风格层 |
| `"friendly"`（默认） | 启用友好交互风格层 |
| `"on"` | `"friendly"` 的别名 |
| `"off"` | 仅禁用友好风格层 |
@ -276,18 +283,18 @@ GPT-5 扩展添加了一个带标签的行为契约，用于规定角色持续
</Tabs>
<Tip>
运行时值不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
这些值在运行时不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
</Tip>
<Note>
当共享设置 `agents.defaults.promptOverlays.gpt5.personality` 未设置时，仍会读取旧版 `plugins.entries.openai.config.personality` 作为兼容性回退。
当未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 时，仍会读取旧版 `plugins.entries.openai.config.personality` 作为兼容性回退。
</Note>
## 语音和语音识别
## 语音与音频
<AccordionGroup>
<Accordion title="语音合成（TTS）">
内置的 `openai` 插件为 `messages.tts` 表面注册语音合成功能。
内置的 `openai` 插件为 `messages.tts` 接口注册了语音合成功能。
| 设置 | 配置路径 | 默认值 |
|---------|------------|---------|
@ -295,7 +302,7 @@ GPT-5 扩展添加了一个带标签的行为契约，用于规定角色持续
| 语音 | `messages.tts.providers.openai.voice` | `coral` |
| 速度 | `messages.tts.providers.openai.speed` | （未设置） |
| 指令 | `messages.tts.providers.openai.instructions` | （未设置，仅 `gpt-4o-mini-tts`） |
| 格式 | `messages.tts.providers.openai.responseFormat` | 语音便笺为 `opus`，文件为 `mp3` |
| 格式 | `messages.tts.providers.openai.responseFormat` | 语音便笺用 `opus`，文件用 `mp3` |
| API 密钥 | `messages.tts.providers.openai.apiKey` | 回退到 `OPENAI_API_KEY` |
| Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
@ -314,22 +321,23 @@ GPT-5 扩展添加了一个带标签的行为契约，用于规定角色持续
```
<Note>
设置 `OPENAI_TTS_BASE_URL` 可以覆盖 TTS Base URL，而不会影响聊天 API 端点。
设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 的 Base URL，而不会影响聊天 API 端点。
</Note>
</Accordion>
<Accordion title="语音转文本">
内置的 `openai` 插件通过 OpenClaw 的媒体理解转录表面注册批量语音转文本功能。
内置的 `openai` 插件通过
OpenClaw 的媒体理解转录接口注册批量语音转文本。
- 默认模型：`gpt-4o-transcribe`
- 端点：OpenAI REST `/v1/audio/transcriptions`
- 输入路径：multipart 音频文件上传
- 在 OpenClaw 中，只要入站音频转录使用
`tools.media.audio`，就受支持，包括 Discord 语音频道片段和渠道
- 在 OpenClaw 中，凡是入站音频转录使用
`tools.media.audio` 的地方都支持，包括 Discord 语音频道片段和渠道
音频附件
要为入站音频转录强制使用 OpenAI：
要强制对入站音频转录使用 OpenAI：
```json5
{
@ -349,13 +357,13 @@ GPT-5 扩展添加了一个带标签的行为契约，用于规定角色持续
}
```
当共享音频媒体配置或每次调用的转录请求提供了语言和提示词提示时，
这些内容会转发给 OpenAI。
当共享音频媒体配置或按次转录请求提供了语言和提示词提示时，
它们会被转发给 OpenAI。
</Accordion>
<Accordion title="实时转录">
内置的 `openai` 插件为 Voice Call 插件注册实时转录功能。
内置的 `openai` 插件为 Voice Call 插件注册了实时转录。
| 设置 | 配置路径 | 默认值 |
|---------|------------|---------|
@ -367,13 +375,13 @@ GPT-5 扩展添加了一个带标签的行为契约，用于规定角色持续
| API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
<Note>
使用到 `wss://api.openai.com/v1/realtime` 的 WebSocket 连接，并采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。此流式提供商用于 Voice Call 的实时转录路径；Discord 语音当前仍会录制短片段，并改用批量 `tools.media.audio` 转录路径。
使用到 `wss://api.openai.com/v1/realtime` 的 WebSocket 连接，并采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。这个流式提供商用于 Voice Call 的实时转录路径；Discord 语音目前仍会录制短片段，并改用批量 `tools.media.audio` 转录路径。
</Note>
</Accordion>
<Accordion title="实时语音">
内置的 `openai` 插件为 Voice Call 插件注册实时语音功能。
内置的 `openai` 插件为 Voice Call 插件注册了实时语音。
| 设置 | 配置路径 | 默认值 |
|---------|------------|---------|
@ -395,19 +403,19 @@ GPT-5 扩展添加了一个带标签的行为契约，用于规定角色持续
<AccordionGroup>
<Accordion title="传输方式（WebSocket 与 SSE）">
OpenClaw 对 `openai/*` 和 `openai-codex/*` 都优先使用 WebSocket，并在失败时回退到 SSE（`"auto"`）。
对于 `openai/*` 和 `openai-codex/*`，OpenClaw 默认都采用 WebSocket 优先、SSE 回退（`"auto"`）。
在 `"auto"` 模式下，OpenClaw 会：
- 在回退到 SSE 之前，重试一次早期 WebSocket 失败
- 失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE
- 在回退到 SSE 之前重试一次早期 WebSocket 失败
- 在失败后，将 WebSocket 标记为约 60 秒的降级状态，并在冷却期间使用 SSE
- 为重试和重连附加稳定的会话与轮次标识头
- 在不同传输变体之间规范化用量计数器（`input_tokens` / `prompt_tokens`）
- 在不同传输变体间规范化用量计数器（`input_tokens` / `prompt_tokens`）
| 值 | 行为 |
|-------|----------|
| `"auto"`（默认） | 优先 WebSocket，失败时回退到 SSE |
| `"sse"` | 仅强制使用 SSE |
| `"websocket"` | 仅强制使用 WebSocket |
| `"auto"`（默认） | WebSocket 优先，SSE 回退 |
| `"sse"` | 强制仅使用 SSE |
| `"websocket"` | 强制仅使用 WebSocket |
```json5
{
@ -424,13 +432,13 @@ GPT-5 扩展添加了一个带标签的行为契约，用于规定角色持续
```
相关 OpenAI 文档：
- [使用 WebSocket 的 Realtime API](https://platform.openai.com/docs/guides/realtime-websocket)
- [流式 API 响应（SSE）](https://platform.openai.com/docs/guides/streaming-responses)
- [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
- [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
</Accordion>
<Accordion title="WebSocket 预热">
OpenClaw 默认对 `openai/*` 启用 WebSocket 预热，以降低首次轮次延迟。
为了降低首轮延迟，OpenClaw 默认对 `openai/*` 启用 WebSocket 预热。
```json5
// 禁用预热
@ -449,13 +457,15 @@ GPT-5 扩展添加了一个带标签的行为契约，用于规定角色持续
</Accordion>
<a id="openai-fast-mode"></a>
<Accordion title="快速模式">
OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供共享的快速模式开关：
OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供统一的快速模式开关：
- **聊天/UI：** `/fast status|on|off`
- **配置：** `agents.defaults.models["<provider>/<model>"].params.fastMode`
启用后，OpenClaw 会将快速模式映射到 OpenAI 优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，并且快速模式不会重写 `reasoning` 或 `text.verbosity`。
启用后，OpenClaw 会将快速模式映射到 OpenAI 的优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，快速模式不会改写 `reasoning` 或 `text.verbosity`。
```json5
{
@ -471,13 +481,13 @@ GPT-5 扩展添加了一个带标签的行为契约，用于规定角色持续
```
<Note>
会话覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，该会话会恢复为配置的默认值。
会话级覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，该会话会恢复为配置中的默认值。
</Note>
</Accordion>
<Accordion title="优先处理（service_tier）">
OpenAI 的 API 通过 `service_tier` 提供优先处理。你可以在 OpenClaw 中按模型设置它：
OpenAI 的 API 通过 `service_tier` 暴露优先处理能力。你可以在 OpenClaw 中按模型设置：
```json5
{
@ -495,7 +505,7 @@ GPT-5 扩展添加了一个带标签的行为契约，用于规定角色持续
支持的值：`auto`、`default`、`flex`、`priority`。
<Warning>
`serviceTier` 仅会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 会保持 `service_tier` 不变。
`serviceTier` 只会被转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 会保持 `service_tier` 不变。
</Warning>
</Accordion>
@ -503,13 +513,13 @@ GPT-5 扩展添加了一个带标签的行为契约，用于规定角色持续
<Accordion title="服务端压缩（Responses API）">
对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenClaw 会自动启用服务端压缩：
- 强制设置 `store: true`（除非模型兼容性将 `supportsStore: false`）
- 强制 `store: true`（除非模型兼容性设置了 `supportsStore: false`）
- 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]`
- 默认 `compact_threshold`：`contextWindow` 的 70%（不可用时为 `80000`）
- 默认 `compact_threshold`：`contextWindow` 的 70%（如果不可用则为 `80000`）
<Tabs>
<Tab title="显式启用">
对 Azure OpenAI Responses 这类兼容端点很有用：
这对兼容端点（如 Azure OpenAI Responses）很有用：
```json5
{
@ -561,7 +571,7 @@ GPT-5 扩展添加了一个带标签的行为契约，用于规定角色持续
</Tabs>
<Note>
`responsesServerCompaction` 仅控制 `context_management` 注入。除非兼容性将 `supportsStore: false`，直接 OpenAI Responses 模型仍会强制使用 `store: true`。
`responsesServerCompaction` 只控制 `context_management` 的注入。直接 OpenAI Responses 模型仍会强制 `store: true`，除非兼容性设置了 `supportsStore: false`。
</Note>
</Accordion>
@ -580,26 +590,26 @@ GPT-5 扩展添加了一个带标签的行为契约，用于规定角色持续
```
使用 `strict-agentic` 时，OpenClaw 会：
- 当工具操作可用时，不再将仅有计划的轮次视为成功推进
- 使用“立即行动”的引导重试该轮次
- 对于较大工作自动启用 `update_plan`
- 如果模型持续只做计划而不行动，则显示明确的阻塞状态
- 当工具操作可用时，不再将仅做计划的轮次视为成功推进
- 通过“立即执行”的引导重试该轮次
- 对实质性工作自动启用 `update_plan`
- 如果模型持续只规划不执行，则显式显示阻塞状态
<Note>
仅限 OpenAI 和 Codex GPT-5 系列运行。其他提供商和较旧的模型系列保持默认行为。
仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧的模型系列会保持默认行为。
</Note>
</Accordion>
<Accordion title="原生路由与 OpenAI-compatible 路由">
OpenClaw 会区别对待直接 OpenAI、Codex 和 Azure OpenAI 端点，以及通用的 OpenAI-compatible `/v1` 代理：
<Accordion title="原生路由与 OpenAI 兼容路由">
OpenClaw 会区别对待直接 OpenAI、Codex 和 Azure OpenAI 端点，以及通用的 OpenAI 兼容 `/v1` 代理：
**原生路由**（`openai/*`、`openai-codex/*`、Azure OpenAI）：
- 仅对支持 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }`
- 对于拒绝 `reasoning.effort: "none"` 的模型或代理，省略禁用的 reasoning
- 对拒绝 `reasoning.effort: "none"` 的模型或代理，省略禁用的 reasoning
- 默认将工具 schema 设为严格模式
- 仅在已验证的原生主机上附加隐藏归因头
- 保留 OpenAI 专有的请求整形（`service_tier`、`store`、reasoning 兼容性、提示词缓存提示）
- 仅在已验证的原生宿主上附加隐藏归因头
- 保留 OpenAI 专属的请求整形（`service_tier`、`store`、reasoning 兼容性、提示词缓存提示）
**代理/兼容路由：**
- 使用更宽松的兼容行为

151
docs/zh-CN/providers/qwen.md
View File

@ -5,10 +5,10 @@ read_when:
summary: 通过 OpenClaw 内置的 qwen 提供商使用 Qwen Cloud
title: Qwen
x-i18n:
generated_at: "2026-04-12T11:08:22Z"
generated_at: "2026-04-23T06:42:37Z"
model: gpt-5.4
provider: openai
source_hash: 5247f851ef891645df6572d748ea15deeea47cd1d75858bc0d044a2930065106
source_hash: 70726b64202d8167f7879320281bde86d69ffa4c40117a53352922eb65d66400
source_path: providers/qwen.md
workflow: 15
---
@ -17,37 +17,38 @@ x-i18n:
<Warning>
**Qwen OAuth 已被移除。** 之前使用 `portal.qwen.ai` 端点的免费层 OAuth 集成
**Qwen OAuth 已移除。** 之前使用 `portal.qwen.ai` 端点的免费层 OAuth 集成
（`qwen-portal`）现已不可用。
背景信息请参见 [Issue #49557](https://github.com/openclaw/openclaw/issues/49557)。
</Warning>
OpenClaw 现在将 Qwen 视为一等内置提供商，其规范 id
为 `qwen`。该内置提供商面向 Qwen Cloud / Alibaba DashScope 和
Coding Plan 端点，并保留旧版 `modelstudio` id 作为兼容性别名。
OpenClaw 现在将 Qwen 视为一级内置提供商，其规范 id
为 `qwen`。该内置提供商面向 Qwen Cloud / Alibaba DashScope 以及
Coding Plan 端点，并保留旧版 `modelstudio` id 作为
兼容性别名。
- 提供商：`qwen`
- 首选环境变量：`QWEN_API_KEY`
- 出于兼容性也接受：`MODELSTUDIO_API_KEY`、`DASHSCOPE_API_KEY`
- API 风格：与 OpenAI 兼容
- API 风格：兼容 OpenAI
<Tip>
如果你想使用 `qwen3.6-plus`，建议优先选择**标准版（按量计费）**端点。
Coding Plan 支持可能会落后于公开目录。
如果你想使用 `qwen3.6-plus`，优先选择**标准版（按量付费）**端点。
Coding Plan 支持可能会落后于公开模型目录。
</Tip>
## 入门指南
选择你的套餐类型并按照设置步骤操作。
选择你的套餐类型，然后按照设置步骤进行。
<Tabs>
<Tab title="Coding Plan（订阅制）">
**最适合：** 通过 Qwen Coding Plan 获得基于订阅的访问。
**最适合：** 通过 Qwen Coding Plan 使用订阅制访问。
<Steps>
<Step title="获取你的 API 密钥">
在 [home.qwencloud.com/api-keys](https://home.qwencloud.com/api-keys) 创建或复制一个 API 密钥。
在 [home.qwencloud.com/api-keys](https://home.qwencloud.com/api-keys) 创建或复制 API 密钥。
</Step>
<Step title="运行新手引导">
对于**全球**端点：
@ -82,18 +83,18 @@ Coding Plan 支持可能会落后于公开目录。
<Note>
旧版 `modelstudio-*` auth-choice id 和 `modelstudio/...` 模型引用仍然
可以作为兼容性别名继续使用，但新的设置流程应优先使用规范的
作为兼容性别名可用，但新的设置流程应优先使用规范的
`qwen-*` auth-choice id 和 `qwen/...` 模型引用。
</Note>
</Tab>
<Tab title="标准版（按量计费）">
**最适合：** 通过标准版 Model Studio 端点进行按量计费访问，包括像 `qwen3.6-plus` 这样在 Coding Plan 中可能不可用的模型。
<Tab title="标准版（按量付费）">
**最适合：** 通过标准版 Model Studio 端点按量付费访问，包括 `qwen3.6-plus` 等可能在 Coding Plan 中不可用的模型。
<Steps>
<Step title="获取你的 API 密钥">
在 [home.qwencloud.com/api-keys](https://home.qwencloud.com/api-keys) 创建或复制一个 API 密钥。
在 [home.qwencloud.com/api-keys](https://home.qwencloud.com/api-keys) 创建或复制 API 密钥。
</Step>
<Step title="运行新手引导">
对于**全球**端点：
@ -128,7 +129,7 @@ Coding Plan 支持可能会落后于公开目录。
<Note>
旧版 `modelstudio-*` auth-choice id 和 `modelstudio/...` 模型引用仍然
可以作为兼容性别名继续使用，但新的设置流程应优先使用规范的
作为兼容性别名可用，但新的设置流程应优先使用规范的
`qwen-*` auth-choice id 和 `qwen/...` 模型引用。
</Note>
@ -139,14 +140,14 @@ Coding Plan 支持可能会落后于公开目录。
| 套餐 | 区域 | Auth choice | 端点 |
| -------------------------- | ------ | -------------------------- | ------------------------------------------------ |
| 标准版（按量计费） | 中国 | `qwen-standard-api-key-cn` | `dashscope.aliyuncs.com/compatible-mode/v1` |
| 标准版（按量计费） | 全球 | `qwen-standard-api-key` | `dashscope-intl.aliyuncs.com/compatible-mode/v1` |
| 标准版（按量付费） | 中国 | `qwen-standard-api-key-cn` | `dashscope.aliyuncs.com/compatible-mode/v1` |
| 标准版（按量付费） | 全球 | `qwen-standard-api-key` | `dashscope-intl.aliyuncs.com/compatible-mode/v1` |
| Coding Plan（订阅制） | 中国 | `qwen-api-key-cn` | `coding.dashscope.aliyuncs.com/v1` |
| Coding Plan（订阅制） | 全球 | `qwen-api-key` | `coding-intl.dashscope.aliyuncs.com/v1` |
该提供商会根据你的 auth choice 自动选择端点。规范选择使用 `qwen-*`
系列；`modelstudio-*` 仅保留用于兼容性。
你也可以在配置中通过自定义 `baseUrl` 进行覆盖。
该提供商会根据你的 auth choice 自动选择端点。规范
选项使用 `qwen-*` 系列；`modelstudio-*` 仅保留用于兼容。
你也可以在配置中使用自定义 `baseUrl` 进行覆盖。
<Tip>
**管理密钥：** [home.qwencloud.com/api-keys](https://home.qwencloud.com/api-keys) |
@ -155,18 +156,18 @@ Coding Plan 支持可能会落后于公开目录。
## 内置目录
OpenClaw 当前内置了以下 Qwen 目录。已配置的目录会感知端点：
Coding Plan 配置会省略那些目前仅确认可在
标准版端点上运行的模型。
OpenClaw 当前内置以下 Qwen 目录。配置后的目录会感知端点类型：
Coding Plan 配置会省略那些已知仅在
标准版端点上可用的模型。
| 模型引用 | 输入 | 上下文 | 说明 |
| --------------------------- | ----------- | --------- | -------------------------------------------------- |
| `qwen/qwen3.5-plus` | text, image | 1,000,000 | 默认模型 |
| `qwen/qwen3.6-plus` | text, image | 1,000,000 | 当你需要此模型时，建议优先使用标准版端点 |
| `qwen/qwen3.6-plus` | text, image | 1,000,000 | 需要此模型时优先使用标准版端点 |
| `qwen/qwen3-max-2026-01-23` | text | 262,144 | Qwen Max 系列 |
| `qwen/qwen3-coder-next` | text | 262,144 | 编码 |
| `qwen/qwen3-coder-plus` | text | 1,000,000 | 编码 |
| `qwen/MiniMax-M2.5` | text | 1,000,000 | 已启用推理 |
| `qwen/qwen3-coder-next` | text | 262,144 | Coding |
| `qwen/qwen3-coder-plus` | text | 1,000,000 | Coding |
| `qwen/MiniMax-M2.5` | text | 1,000,000 | 已启用 reasoning |
| `qwen/glm-5` | text | 202,752 | GLM |
| `qwen/glm-4.7` | text | 202,752 | GLM |
| `qwen/kimi-k2.5` | text, image | 262,144 | 通过 Alibaba 提供的 Moonshot AI |
@ -175,15 +176,15 @@ Coding Plan 配置会省略那些目前仅确认可在
即使某个模型出现在内置目录中，其可用性仍可能因端点和计费套餐而异。
</Note>
## 多模态附加能力
## 多模态附加功能
`qwen` 扩展还会在**标准版**
DashScope 端点（而非 Coding Plan 端点）上提供多模态能力：
`qwen` 插件还会在**标准版**
DashScope 端点上（而不是 Coding Plan 端点）公开多模态能力：
- 通过 `qwen-vl-max-latest` 提供**视频理解**
- 通过 `wan2.6-t2v`（默认）、`wan2.6-i2v`、`wan2.6-r2v`、`wan2.6-r2v-flash`、`wan2.7-r2v` 提供 **Wan 视频生成**
要将 Qwen 用作默认视频提供商：
要将 Qwen 设为默认视频提供商：
```json5
{
@ -196,85 +197,87 @@ DashScope 端点（而非 Coding Plan 端点）上提供多模态能力：
```
<Note>
有关共享工具参数、提供商选择和故障切换行为，请参见 [Video Generation](/zh-CN/tools/video-generation)。
有关共享工具参数、提供商选择和故障转移行为，请参见 [视频生成](/zh-CN/tools/video-generation)。
</Note>
## 高级
<AccordionGroup>
<Accordion title="图像和视频理解">
内置的 Qwen 插件会在**标准版** DashScope 端点（而非 Coding Plan 端点）上为图像和视频注册媒体理解能力。
内置的 Qwen 插件会在**标准版** DashScope 端点上（而不是 Coding Plan 端点）
为图像和视频注册媒体理解能力。
| 属性 | 值 |
| ------------- | --------------------- |
| 模型 | `qwen-vl-max-latest` |
| 支持的输入 | 图像、视频 |
| 支持的输入 | Images, video |
媒体理解会根据已配置的 Qwen 凭证自动解析——
无需额外配置。请确保你使用的是支持媒体理解的标准版（按量计费）
端点。
媒体理解会根据已配置的 Qwen 认证自动解析——
无需额外配置。请确保你使用的是标准版（按量付费）
端点，以支持媒体理解。
</Accordion>
<Accordion title="Qwen 3.6 Plus 可用性">
`qwen3.6-plus` 可在标准版（按量计费）Model Studio
`qwen3.6-plus` 可在标准版（按量付费）Model Studio
端点上使用：
- 中国：`dashscope.aliyuncs.com/compatible-mode/v1`
- 全球：`dashscope-intl.aliyuncs.com/compatible-mode/v1`
如果 Coding Plan 端点对 `qwen3.6-plus` 返回“unsupported model”错误，
请切换到标准版（按量计费），而不是继续使用 Coding Plan
端点 / 密钥组合。
如果 Coding Plan 端点对
`qwen3.6-plus` 返回“unsupported model”错误，请切换到标准版（按量付费），而不是继续使用 Coding Plan
端点/密钥组合。
</Accordion>
<Accordion title="能力规划">
`qwen` 扩展正在被定位为完整 Qwen
Cloud 能力面的厂商归属入口，而不仅仅是编码 / 文本模型。
`qwen` 插件正在被定位为完整 Qwen
Cloud 能力面的厂商归属位置，而不仅仅是 coding/text 模型。
- **文本 / 聊天模型：** 现已内置
- **工具调用、结构化输出、思维链：** 继承自与 OpenAI 兼容的传输层
- **图像生成：** 计划在提供商插件层支持
- **图像 / 视频理解：** 现已在标准版端点内置
- **语音 / 音频：** 计划在提供商插件层支持
- **Memory 嵌入 / 重排序：** 计划通过嵌入适配器能力面支持
- **视频生成：** 现已通过共享视频生成能力内置
- **文本/聊天模型：** 当前已内置
- **工具调用、结构化输出、thinking：** 继承自兼容 OpenAI 的传输层
- **图像生成：** 计划在提供商插件层提供
- **图像/视频理解：** 当前已在标准版端点内置
- **语音/音频：** 计划在提供商插件层提供
- **记忆 embeddings/reranking：** 计划通过 embedding 适配器层提供
- **视频生成：** 当前已通过共享视频生成能力内置
</Accordion>
<Accordion title="视频生成详情">
对于视频生成，OpenClaw 会先将已配置的 Qwen 区域映射到匹配的
DashScope AIGC 主机，然后再提交任务：
对于视频生成，OpenClaw 会在提交任务前，将配置的 Qwen 区域映射到对应的
DashScope AIGC 主机：
- 全球 / 国际版：`https://dashscope-intl.aliyuncs.com`
- 全球/国际版：`https://dashscope-intl.aliyuncs.com`
- 中国：`https://dashscope.aliyuncs.com`
这意味着，普通的 `models.providers.qwen.baseUrl` 即使指向
Coding Plan 或标准版 Qwen 主机之一，
视频生成仍会使用正确的区域性 DashScope 视频端点。
Coding Plan 或标准版 Qwen 主机，也仍然能让视频生成使用正确的
区域性 DashScope 视频端点。
当前内置 Qwen 视频生成限制：
当前内置的 Qwen 视频生成限制：
- 每个请求最多 **1** 个输出视频
- 最多 **1** 张输入图片
- 最多 **1** 张输入图像
- 最多 **4** 个输入视频
- 最长 **10 秒** 时长
- 支持 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark`
- 参考图片 / 视频模式目前要求使用**远程 http(s) URL**。本地
文件路径会被预先拒绝，因为 DashScope 视频端点不接受
为这些参考上传本地缓冲区。
- 参考图像/视频模式当前要求使用**远程 http(s) URL**。本地
文件路径会被提前拒绝，因为 DashScope 视频端点不
接受为这些参考上传本地缓冲区。
</Accordion>
<Accordion title="流式使用兼容性">
原生 Model Studio 端点会在共享 `openai-completions` 传输层上声明
流式使用兼容性。OpenClaw 现在基于端点能力来判断这一点，因此面向相同原生主机的
DashScope 兼容自定义提供商 id 也会继承相同的流式使用行为，
而不再要求必须使用内置 `qwen` 提供商 id。
<Accordion title="流式使用量兼容性">
原生 Model Studio 端点在共享的
`openai-completions` 传输上声明支持流式使用量兼容性。OpenClaw 现在会根据端点
能力进行判断，因此，指向同一原生主机的、兼容 DashScope 的自定义提供商 id
也会继承相同的流式使用量行为，而不是
必须特定使用内置 `qwen` 提供商 id。
原生流式使用兼容性同时适用于 Coding Plan 主机和
标准版 DashScope 兼容主机：
原生流式使用量兼容性同时适用于 Coding Plan 主机和
标准版兼容 DashScope 的主机：
- `https://coding.dashscope.aliyuncs.com/v1`
- `https://coding-intl.dashscope.aliyuncs.com/v1`
@ -287,14 +290,14 @@ DashScope 端点（而非 Coding Plan 端点）上提供多模态能力：
多模态能力面（视频理解和 Wan 视频生成）使用的是
**标准版** DashScope 端点，而不是 Coding Plan 端点：
- 全球 / 国际版标准 base URL：`https://dashscope-intl.aliyuncs.com/compatible-mode/v1`
- 全球/国际版标准 base URL：`https://dashscope-intl.aliyuncs.com/compatible-mode/v1`
- 中国标准 base URL：`https://dashscope.aliyuncs.com/compatible-mode/v1`
</Accordion>
<Accordion title="环境和守护进程设置">
如果 Gateway 网关以守护进程（launchd/systemd）方式运行，请确保 `QWEN_API_KEY`
对该进程可用（例如放在 `~/.openclaw/.env` 中，或通过
如果 Gateway 网关作为守护进程运行（launchd/systemd），请确保 `QWEN_API_KEY` 对该进程
可用（例如放在 `~/.openclaw/.env` 中，或通过
`env.shellEnv` 提供）。
</Accordion>
</AccordionGroup>
@ -303,7 +306,7 @@ DashScope 端点（而非 Coding Plan 端点）上提供多模态能力：
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用和故障切换行为。
选择提供商、模型引用和故障转移行为。
</Card>
<Card title="视频生成" href="/zh-CN/tools/video-generation" icon="video">
共享视频工具参数和提供商选择。
@ -312,6 +315,6 @@ DashScope 端点（而非 Coding Plan 端点）上提供多模态能力：
旧版 ModelStudio 提供商和迁移说明。
</Card>
<Card title="故障排除" href="/zh-CN/help/troubleshooting" icon="wrench">
常规故障排除和常见问题。
通用故障排除和常见问题。
</Card>
</CardGroup>

23
docs/zh-CN/providers/tencent.md
View File

@ -1,21 +1,21 @@
---
read_when:
- 你想在 OpenClaw 中使用腾讯混元模型
- 你希望在 OpenClaw 中使用腾讯混元模型
- 你需要设置 TokenHub API 密钥
summary: 腾讯云 TokenHub 设置
summary: 腾讯云（TokenHub）设置
title: 腾讯云（TokenHub）
x-i18n:
generated_at: "2026-04-22T05:47:53Z"
generated_at: "2026-04-23T06:42:42Z"
model: gpt-5.4
provider: openai
source_hash: 04da073973792c55dc0c2d287bfc51187bb2128bbbd5c4a483f850adeea50ab5
source_hash: 90fce0d5957b261439cacd2b4df2362ed69511cb047af6a76ccaf54004806041
source_path: providers/tencent.md
workflow: 15
---
# 腾讯云（TokenHub）
腾讯云提供商通过 TokenHub 端点（`tencent-tokenhub`）提供对腾讯混元模型的访问。
腾讯云作为 **内置提供商插件** 随 OpenClaw 一起提供。它通过 TokenHub 端点（`tencent-tokenhub`）提供对腾讯混元模型的访问。
该提供商使用与 OpenAI 兼容的 API。
@ -36,9 +36,9 @@ openclaw onboard --non-interactive \
--accept-risk
```
## 提供商和端点
## 提供商与端点
| 提供商 | 端点 | 用例 |
| 提供商 | 端点 | 用途 |
| ------------------ | ----------------------------- | ----------------------- |
| `tencent-tokenhub` | `tokenhub.tencentmaas.com/v1` | 通过腾讯 TokenHub 使用混元 |
@ -46,19 +46,22 @@ openclaw onboard --non-interactive \
### tencent-tokenhub
- **hy3-preview** — Hy3 预览版（256K 上下文、推理、默认）
- **hy3-preview** — 混元 3 预览版（256K 上下文、支持推理、默认）
## 说明
- TokenHub 模型引用使用 `tencent-tokenhub/<modelId>`。
- 该插件内置了分层的混元 3 定价元数据，因此无需手动覆盖定价即可填充成本估算。
- 如有需要，可在 `models.providers` 中覆盖定价和上下文元数据。
## 环境说明
如果 Gateway 网关 以守护进程方式运行（`launchd`/`systemd`），请确保 `TOKENHUB_API_KEY` 对该进程可用（例如，在 `~/.openclaw/.env` 中，或通过 `env.shellEnv`）。
如果 Gateway 网关以守护进程方式运行（launchd/systemd），请确保 `TOKENHUB_API_KEY`
对该进程可用（例如放在 `~/.openclaw/.env` 中，或通过
`env.shellEnv` 提供）。
## 相关文档
- [OpenClaw 配置](/zh-CN/gateway/configuration)
- [模型提供商](/zh-CN/concepts/model-providers)
- [腾讯 TokenHub](https://cloud.tencent.com/document/product/1823/130050)
- [Tencent TokenHub](https://cloud.tencent.com/document/product/1823/130050)

87
docs/zh-CN/providers/volcengine.md
View File

@ -2,26 +2,26 @@
read_when:
- 你想在 OpenClaw 中使用火山引擎或 Doubao 模型
- 你需要设置 Volcengine API 密钥
summary: 火山引擎设置（Doubao 模型，通用 + 编程端点）
title: 火山引擎（Doubao）
summary: 火山引擎设置（Doubao 模型、通用端点 + 编码端点）
title: Volcengine（Doubao）
x-i18n:
generated_at: "2026-04-12T10:26:13Z"
generated_at: "2026-04-23T06:42:44Z"
model: gpt-5.4
provider: openai
source_hash: a21f390da719f79c88c6d55a7d952d35c2ce5ff26d910c9f10020132cd7d2f4c
source_hash: 4d803e965699bedf06cc7ea4e902ffc92e4a168be012224e845820069fd67acc
source_path: providers/volcengine.md
workflow: 15
---
# 火山引擎（Doubao）
# Volcengine（Doubao）
Volcengine 提供商可让你访问部署在火山引擎上的 Doubao 模型和第三方模型，并为通用工作负载和编程工作负载提供分别独立的端点。
Volcengine 提供商可访问托管在火山引擎上的 Doubao 模型和第三方模型，并为通用工作负载和编码工作负载提供独立端点。
| 详情 | 值 |
| 详情 | 值 |
| --------- | --------------------------------------------------- |
| 提供商 | `volcengine`（通用）+ `volcengine-plan`（编程） |
| 认证 | `VOLCANO_ENGINE_API_KEY` |
| API | 与 OpenAI 兼容 |
| 提供商 | `volcengine`（通用）+ `volcengine-plan`（编码） |
| 认证 | `VOLCANO_ENGINE_API_KEY` |
| API | 兼容 OpenAI |
## 入门指南
@ -33,7 +33,7 @@ Volcengine 提供商可让你访问部署在火山引擎上的 Doubao 模型和
openclaw onboard --auth-choice volcengine-api-key
```
这会通过一个 API 密钥同时注册通用提供商（`volcengine`）和编程提供商（`volcengine-plan`）。
这会通过一个 API 密钥同时注册通用提供商（`volcengine`）和编码提供商（`volcengine-plan`）。
</Step>
<Step title="设置默认模型">
@ -47,7 +47,7 @@ Volcengine 提供商可让你访问部署在火山引擎上的 Doubao 模型和
}
```
</Step>
<Step title="验证模型可用">
<Step title="验证模型是否可用">
```bash
openclaw models list --provider volcengine
openclaw models list --provider volcengine-plan
@ -69,36 +69,36 @@ openclaw onboard --non-interactive \
## 提供商和端点
| 提供商 | 端点 | 使用场景 |
| ----------------- | ----------------------------------------- | ------------ |
| `volcengine` | `ark.cn-beijing.volces.com/api/v3` | 通用模型 |
| `volcengine-plan` | `ark.cn-beijing.volces.com/api/coding/v3` | 编程模型 |
| 提供商 | 端点 | 用途 |
| ----------------- | ----------------------------------------- | -------------- |
| `volcengine` | `ark.cn-beijing.volces.com/api/v3` | 通用模型 |
| `volcengine-plan` | `ark.cn-beijing.volces.com/api/coding/v3` | 编码模型 |
<Note>
这两个提供商都通过同一个 API 密钥进行配置。设置时会自动同时注册两者。
这两个提供商都通过同一个 API 密钥配置。设置时会自动同时注册。
</Note>
## 可用模型
<Tabs>
<Tab title="通用（volcengine)">
| Model ref | 名称 | 输入 | 上下文 |
| -------------------------------------------- | ------------------------------- | ----------- | ------ |
| `volcengine/doubao-seed-1-8-251228` | Doubao Seed 1.8 | 文本、图像 | 256,000 |
| `volcengine/doubao-seed-code-preview-251028` | doubao-seed-code-preview-251028 | 文本、图像 | 256,000 |
| `volcengine/kimi-k2-5-260127` | Kimi K2.5 | 文本、图像 | 256,000 |
| `volcengine/glm-4-7-251222` | GLM 4.7 | 文本、图像 | 200,000 |
| `volcengine/deepseek-v3-2-251201` | DeepSeek V3.2 | 文本、图像 | 128,000 |
<Tab title="通用（volcengine）">
| 模型引用 | 名称 | 输入 | 上下文 |
| -------------------------------------------- | ------------------------------- | ----------- | ------- |
| `volcengine/doubao-seed-1-8-251228` | Doubao Seed 1.8 | text, image | 256,000 |
| `volcengine/doubao-seed-code-preview-251028` | doubao-seed-code-preview-251028 | text, image | 256,000 |
| `volcengine/kimi-k2-5-260127` | Kimi K2.5 | text, image | 256,000 |
| `volcengine/glm-4-7-251222` | GLM 4.7 | text, image | 200,000 |
| `volcengine/deepseek-v3-2-251201` | DeepSeek V3.2 | text, image | 128,000 |
</Tab>
<Tab title="编程（volcengine-plan)">
| Model ref | 名称 | 输入 | 上下文 |
| ------------------------------------------------- | ------------------------ | ---- | ------ |
| `volcengine-plan/ark-code-latest` | Ark Coding Plan | 文本 | 256,000 |
| `volcengine-plan/doubao-seed-code` | Doubao Seed Code | 文本 | 256,000 |
| `volcengine-plan/glm-4.7` | GLM 4.7 Coding | 文本 | 200,000 |
| `volcengine-plan/kimi-k2-thinking` | Kimi K2 Thinking | 文本 | 256,000 |
| `volcengine-plan/kimi-k2.5` | Kimi K2.5 Coding | 文本 | 256,000 |
| `volcengine-plan/doubao-seed-code-preview-251028` | Doubao Seed Code Preview | 文本 | 256,000 |
<Tab title="编码（volcengine-plan）">
| 模型引用 | 名称 | 输入 | 上下文 |
| ------------------------------------------------- | ------------------------ | ----- | ------- |
| `volcengine-plan/ark-code-latest` | Ark Coding Plan | text | 256,000 |
| `volcengine-plan/doubao-seed-code` | Doubao Seed Code | text | 256,000 |
| `volcengine-plan/glm-4.7` | GLM 4.7 Coding | text | 200,000 |
| `volcengine-plan/kimi-k2-thinking` | Kimi K2 Thinking | text | 256,000 |
| `volcengine-plan/kimi-k2.5` | Kimi K2.5 Coding | text | 256,000 |
| `volcengine-plan/doubao-seed-code-preview-251028` | Doubao Seed Code Preview | text | 256,000 |
</Tab>
</Tabs>
@ -107,13 +107,15 @@ openclaw onboard --non-interactive \
<AccordionGroup>
<Accordion title="新手引导后的默认模型">
`openclaw onboard --auth-choice volcengine-api-key` 当前会将
`volcengine-plan/ark-code-latest` 设为默认模型，同时也会注册通用的 `volcengine` 模型目录。
`volcengine-plan/ark-code-latest` 设为默认模型，同时也会注册
通用 `volcengine` 目录。
</Accordion>
<Accordion title="模型选择器的回退行为">
<Accordion title="模型选择器回退行为">
在新手引导/配置模型选择期间，Volcengine 认证选项会优先显示
`volcengine/*` 和 `volcengine-plan/*` 条目。如果这些模型尚未加载，
OpenClaw 会回退到未筛选的模型目录，而不是显示一个空的按提供商范围筛选的选择器。
`volcengine/*` 和 `volcengine-plan/*` 条目。如果这些模型尚未
加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的、
按提供商限定的选择器。
</Accordion>
<Accordion title="守护进程的环境变量">
@ -124,22 +126,23 @@ openclaw onboard --non-interactive \
</AccordionGroup>
<Warning>
当 OpenClaw 作为后台服务运行时，你在交互式 shell 中设置的环境变量不会被自动继承。请参阅上面的守护进程说明。
当 OpenClaw 作为后台服务运行时，你在交互式 shell 中设置的环境变量
不会被自动继承。请参见上面的守护进程说明。
</Warning>
## 相关内容
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用以及故障切换行为。
选择提供商、模型引用和故障转移行为。
</Card>
<Card title="配置" href="/zh-CN/gateway/configuration" icon="gear">
关于智能体、模型和提供商的完整配置参考。
智能体、模型和提供商的完整配置参考。
</Card>
<Card title="故障排除" href="/zh-CN/help/troubleshooting" icon="wrench">
常见问题和调试步骤。
</Card>
<Card title="常见问题" href="/zh-CN/help/faq" icon="circle-question">
关于 OpenClaw 设置的常见问题解答。
关于 OpenClaw 设置的常见问题。
</Card>
</CardGroup>

103
docs/zh-CN/refactor/async-exec-duplicate-completion-investigation.md
View File

@ -1,132 +1,137 @@
---
read_when:
- 调试重复的节点 exec 完成事件
- 处理 heartbeat/system-event 去重
summary: 重复 async exec 完成注入的调查说明
title: Async Exec Duplicate Completion Investigation
x-i18n:
generated_at: "2026-04-15T20:07:43Z"
generated_at: "2026-04-23T06:42:52Z"
model: gpt-5.4
provider: openai
source_hash: 95e56c5411204363676f002059c942201503e2359515d1a4b409882cc2e04920
source_hash: 8b0a3287b78bbc4c41e4354e9062daba7ae790fa207eee9a5f77515b958b510b
source_path: refactor/async-exec-duplicate-completion-investigation.md
workflow: 15
---
# Async Exec 重复完成调查
# Async Exec Duplicate Completion Investigation
## 范围
- 会话：`agent:main:telegram:group:-1003774691294:topic:1`
- 现象：同一个针对会话/运行 `keen-nexus` 的异步 exec 完成事件在 LCM 中被记录了两次，且都作为用户轮次。
- 症状：同一个会话/运行 `keen-nexus` 的 async exec 完成事件在 LCM 中被记录为两次用户轮次。
- 目标：识别这更可能是重复的会话注入，还是单纯的出站投递重试。
## 结论
这最可能是**重复的会话注入**，而不是纯粹的出站投递重试。
这更可能是**重复的会话注入**，而不是单纯的出站投递重试。
Gateway 网关侧最明显的缺口在于**节点 exec 完成路径**：
Gateway 网关侧最明显的缺口出现在**节点 exec 完成路径**：
1. 节点侧 exec 结束会发出带完整 `runId` 的 `exec.finished`。
2. Gateway 网关中的 `server-node-events` 会将其转换为一个 system event，并请求一次 heartbeat。
3. heartbeat 运行会把已排空的 system event 块注入到智能体提示中。
4. 嵌入式 runner 会将该提示作为新的用户轮次持久化到会话 transcript 中。
1. 节点侧 exec 完成时会发出带完整 `runId` 的 `exec.finished`。
2. Gateway 网关的 `server-node-events` 会将其转换为系统事件并请求一次 heartbeat。
3. heartbeat 运行会将已排空的系统事件块注入到智能体提示词中。
4. 嵌入式 runner 会将该提示词持久化为会话转录中的一个新用户轮次。
如果同一个 `runId` 的 `exec.finished` 因任何原因再次到达 Gateway 网关（重放、重连重复、上游重发、生产者重复），OpenClaw 当前在这条路径上**没有基于 `runId` / `contextKey` 的幂等性检查**。第二份副本会变成第二条内容相同的用户消息。
如果由于任何原因（重放、重连重复、上游重发、生产者重复）相同的 `exec.finished` 针对同一个 `runId` 两次到达 Gateway 网关，OpenClaw 当前在这条路径上**没有基于 `runId`/`contextKey` 的幂等检查**。第二份副本会变成第二条内容相同的用户消息。
## 精确代码路径
### 1. 生产者：节点 exec 完成事件
- `src/node-host/invoke.ts:340-360`
- `sendExecFinishedEvent(...)` 会发出事件为 `exec.finished` 的 `node.event`。
- 载荷包含 `sessionKey` 和完整 `runId`。
- `sendExecFinishedEvent(...)` 发出事件为 `exec.finished` 的 `node.event`。
- 负载包含 `sessionKey` 和完整 `runId`。
### 2. Gateway 网关事件摄取
- `src/gateway/server-node-events.ts:574-640`
- 处理 `exec.finished`。
- 构造文本：
- 构建文本：
- `Exec finished (node=..., id=<runId>, code ...)`
- 通过以下方式入队：
- 通过以下方式将其入队：
- `enqueueSystemEvent(text, { sessionKey, contextKey: runId ? \`exec:${runId}\` : "exec", trusted: false })`
- 然后立即请求唤醒：
- 并立即请求唤醒：
- `requestHeartbeatNow(scopedHeartbeatWakeOptions(sessionKey, { reason: "exec-event" }))`
### 3. system event 去重薄弱点
### 3. 系统事件去重薄弱点
- `src/infra/system-events.ts:90-115`
- `enqueueSystemEvent(...)` 只会抑制**连续的重复文本**：
- `if (entry.lastText === cleaned) return false`
- 它会存储 `contextKey`，但**不会**使用 `contextKey` 做幂等性判断。
- drain 之后，重复抑制会重置。
- 它会存储 `contextKey`，但**不会**使用 `contextKey` 做幂等检查。
- 在 drain 之后，重复抑制会重置。
这意味着，即使代码里已经有稳定的幂等性候选键（`exec:<runId>`），稍后被重放的相同 `runId` 的 `exec.finished` 仍然会再次被接受。
这意味着，即使代码已经有一个稳定的幂等候选键（`exec:<runId>`），被重放的相同 `runId` 的 `exec.finished` 之后仍可能再次被接受。
### 4. 唤醒处理不是主要的重复来源
- `src/infra/heartbeat-wake.ts:79-117`
- 唤醒会按 `(agentId, sessionKey)` 合并。
- 同一目标的重复唤醒请求会折叠为一个待处理唤醒条目。
- 针对同一目标的重复唤醒请求会折叠为一个待处理唤醒条目。
这使得**单独的重复唤醒处理**相比重复事件摄取而言，是一个更弱的解释。
因此，相比重复事件摄取，**单靠重复唤醒处理**来解释问题的可能性更低。
### 5. Heartbeat 消费事件并将其转为提示输入
### 5. Heartbeat 消费该事件并将其转为提示词输入
- `src/infra/heartbeat-runner.ts:535-574`
- 预检会窥视待处理的 system event，并对 exec-event 运行进行分类。
- 预检会窥视待处理系统事件，并对 exec-event 运行进行分类。
- `src/auto-reply/reply/session-system-events.ts:86-90`
- `drainFormattedSystemEvents(...)` 会排空该会话的队列。
- `src/auto-reply/reply/get-reply-run.ts:400-427`
- 已排空的 system event 块会被前置到智能体提示正文中。
- 排空后的系统事件块会被前置注入到智能体提示词主体中。
### 6. Transcript 注入点
### 6. 转录注入点
- `src/agents/pi-embedded-runner/run/attempt.ts:2000-2017`
- `activeSession.prompt(effectivePrompt)` 会将完整提示提交给嵌入式 PI 会话。
- 这就是完成事件衍生出的提示被持久化为用户轮次的位置。
- `activeSession.prompt(effectivePrompt)` 会将完整提示词提交给嵌入式 PI 会话。
- 这就是基于完成事件生成的提示词变成持久化用户轮次的那个点。
因此，一旦同一个 system event 被两次重建进提示中，LCM 中出现重复的用户消息就是符合预期的。
因此，一旦同一个系统事件被两次重建进提示词中，出现重复的 LCM 用户消息就是预期结果。
## 为什么单纯的出站投递重试可能性更低
heartbeat runner 中确实存在真实的出站失败路径：
- `src/infra/heartbeat-runner.ts:1194-1242`
- 回复会先生成。
- 出站投递随后通过 `deliverOutboundPayloads(...)` 进行。
- 该步骤失败会返回 `{ status: "failed" }`。
- 先生成回复。
- 然后通过 `deliverOutboundPayloads(...)` 进行出站投递。
- 此处失败会返回 `{ status: "failed" }`。
但是，对于同一个 system event 队列条目，仅这一点**不足以**解释重复的用户轮次：
但是，对于同一个系统事件队列条目，仅凭这一点**不足以**解释重复的用户轮次：
- `src/auto-reply/reply/session-system-events.ts:86-90`
- system event 队列在出站投递之前就已经被排空了。
- 系统事件队列在出站投递之前就已经被排空。
所以，单独的渠道发送重试不会重新创建同一个已入队事件。它可以解释外部投递缺失/失败，但本身不能解释第二条完全相同的会话用户消息。
因此，仅仅是渠道发送重试本身不会重新创建完全相同的排队事件。它可以解释外部投递缺失/失败，但单靠这一点无法解释第二条完全相同的会话用户消息。
## 次要的、置信度较低的可能性
智能体 runner 中存在完整运行的重试循环：
智能体 runner 中存在一个完整运行重试循环：
- `src/auto-reply/reply/agent-runner-execution.ts:741-1473`
- 某些瞬时失败可能会重试整个运行，并重新提交同一个 `commandBody`。
- 某些瞬时失败会重试整个运行，并重新提交相同的 `commandBody`。
如果在触发重试条件之前，提示已经被追加，那么这可能会在**同一次回复执行**中复制一个已持久化的用户提示。
如果在触发重试条件之前提示词已经被追加，那么这可能会在**同一次回复执行内部**复制一个已持久化的用户提示词。
我认为这比重复的 `exec.finished` 摄取可能性更低，因为：
我将这种可能性排在低于重复 `exec.finished` 摄取之后，因为：
- 观察到的间隔大约为 51 秒，这更像是第二次唤醒/轮次，而不是进程内重试；
- 报告中已经提到消息发送失败反复出现，这更指向一个单独的后续轮次，而不是一次即时的模型/运行时重试。
- 观察到的时间间隔约为 51 秒，更像是第二次唤醒/轮次，而不是进程内重试；
- 报告中已经提到重复的消息发送失败，这更指向一次后续独立轮次，而不是即时的模型/运行时重试。
## 根因假设
最高置信度的假设是：
最高置信度假设：
- `keen-nexus` 的完成事件走的是**节点 exec 事件路径**。
- 同一个 `exec.finished` 被投递到了 `server-node-events` 两次。
- `keen-nexus` 完成事件走的是**节点 exec 事件路径**。
- 同一个 `exec.finished` 被两次投递到 `server-node-events`。
- Gateway 网关接受了这两次事件，因为 `enqueueSystemEvent(...)` 不会按 `contextKey` / `runId` 去重。
- 每个被接受的事件都会触发一次 heartbeat，并被注入为 PI transcript 中的一个用户轮次。
- 每个被接受的事件都会触发一次 heartbeat，并作为一个用户轮次注入到 PI 转录中。
## 建议的微创修复
## 建议的微小外科式修复
如果要修复，最小但高价值的改动是：
- 让 exec/system-event 的幂等性在短时间窗口内基于 `contextKey` 生效，至少要拦截完全相同的 `(sessionKey, contextKey, text)` 重复；
- 或者在 `server-node-events` 中为 `exec.finished` 增加一个专门的去重，键为 `(sessionKey, runId, event kind)`。
- 让 exec/系统事件幂等性在短时间窗口内尊重 `contextKey`，至少对完全相同的 `(sessionKey, contextKey, text)` 重复项生效；
- 或者在 `server-node-events` 中为 `exec.finished` 添加专用去重，键为 `(sessionKey, runId, event kind)`。
这样可以在重放的 `exec.finished` 变成会话轮次之前，直接将其拦住。
这将直接阻止被重放的 `exec.finished` 重复项在变成会话轮次之前通过。

286
docs/zh-CN/refactor/qa.md
View File

@ -1,9 +1,14 @@
---
read_when:
- 重构 QA 场景定义或 qa-lab 测试框架代码
- 在 Markdown 场景与 TypeScript 测试框架逻辑之间迁移 QA 行为
summary: QA 重构：场景目录与测试框架整合计划
title: QA 重构
x-i18n:
generated_at: "2026-04-17T15:05:20Z"
generated_at: "2026-04-23T06:43:04Z"
model: gpt-5.4
provider: openai
source_hash: dbb2c70c82da7f6f12d90e25666635ff4147c52e8a94135e902d1de4f5cbccca
source_hash: 16867d5be372ab414aa516144193144414c326ea53a52627f3ff91f85b8fdf9d
source_path: refactor/qa.md
workflow: 15
---
@ -14,20 +19,21 @@ x-i18n:
## 目标
将 OpenClaw QA 从拆分定义模型迁移为单一事实来源：
将 OpenClaw QA 从分裂定义模型迁移为单一事实来源：
- 场景元数据
- 发送给模型的提示词
- 设置与清理
- harness 逻辑
- 测试框架逻辑
- 断言与成功标准
- 产物与报告提示
期望的最终状态是：一个通用 QA harness 加载功能强大的场景定义文件，而不是将大部分行为硬编码在 TypeScript 中。
期望的最终状态是：一个通用 QA 测试框架加载功能强大的场景定义文件，而不是在 TypeScript 中硬编码大部分行为。
## 当前状态
当前的主要事实来源现在位于 `qa/scenarios/index.md`，以及每个场景对应的单独文件 `qa/scenarios/<theme>/*.md`。
当前的主要事实来源已位于 `qa/scenarios/index.md`，以及
`qa/scenarios/<theme>/*.md` 下每个场景对应的单独文件中。
已实现：
@ -39,28 +45,28 @@ x-i18n:
- 每个场景一个 Markdown 文件
- 场景元数据
- handler 绑定
- 场景专用执行配置
- 场景特定执行配置
- `extensions/qa-lab/src/scenario-catalog.ts`
- Markdown 包解析器 + zod 校验
- `extensions/qa-lab/src/qa-agent-bootstrap.ts`
- 从 Markdown 包渲染执行计划
- 从 Markdown 包渲染计划
- `extensions/qa-lab/src/qa-agent-workspace.ts`
- 生成兼容性文件种子，以及 `QA_SCENARIOS.md`
- 生成兼容性种子文件以及 `QA_SCENARIOS.md`
- `extensions/qa-lab/src/suite.ts`
- 通过 Markdown 定义的 handler 绑定选择可执行场景
- QA 总线协议 + UI
- 用于图片 / 视频 / 音频 / 文件渲染的通用内联附件
- QA bus 协议 + UI
- 用于图像/视频/音频/文件渲染的通用内联附件
仍然拆分的部分：
仍然分裂的表面：
- `extensions/qa-lab/src/suite.ts`
- 仍然承载大多数可执行自定义 handler 逻辑
- 仍然承载大部分可执行的自定义 handler 逻辑
- `extensions/qa-lab/src/report.ts`
- 仍然根据运行时输出推导报告结构
- 仍然从运行时输出中推导报告结构
因此，事实来源拆分问题已经修复，但执行层仍然主要依赖 handler，而不是完全声明式。
因此，事实来源分裂的问题已修复，但执行层面目前仍主要依赖 handler，而非完全声明式。
## 实际场景面是什么样的
## 实际的场景表面是什么样的
阅读当前 suite 可以看到几类不同的场景。
@ -68,49 +74,49 @@ x-i18n:
- 渠道基线
- 私信基线
- 线程后续跟进
- 线程跟进
- 模型切换
- 审批后续执行
- reaction / edit / delete
- 审批继续执行
- 反应/编辑/删除
### 配置与运行时变更
- config patch skill disable
- config apply restart wake-up
- config restart capability flip
- runtime inventory drift check
- 配置补丁禁用 Skills
- 配置应用后重启唤醒
- 配置重启能力切换
- 运行时清单漂移检查
### 文件系统与仓库断言
- source / docs discovery report
- build Lobster Invaders
- generated image artifact lookup
- source/docs 发现报告
- 构建 Lobster Invaders
- 生成图像产物查找
### Memory 编排
- memory recall
- 渠道上下文中的 memory 工具
- memory failure fallback
- session memory ranking
- 线程 memory 隔离
- memory dreaming sweep
- 记忆召回
- 渠道上下文中的记忆工具
- 记忆失败回退
- 会话记忆排序
- 线程记忆隔离
- 记忆 Dreaming 扫描
### 工具与插件集成
- MCP plugin-tools call
- Skills 可见性
- Skills 热安装
- MCP plugin-tools 调用
- skill 可见性
- skill 热安装
- 原生图像生成
- 图像往返
- 从附件理解图像
### 多轮与多参与者
- subagent handoff
- subagent fanout synthesis
- restart recovery 风格流程
- 子智能体移交
- 子智能体扇出综合
- 重启恢复类流程
这些分类很重要，因为它们决定 DSL 的需求。仅靠“提示词 + 预期文本”的平面列表是不够的。
这些分类之所以重要，是因为它们决定了 DSL 的需求。仅有“提示词 + 期望文本”的扁平列表是不够的。
## 方向
@ -120,18 +126,18 @@ x-i18n:
这个包应保持：
- 便于人工在评审中阅读
- 可被机器解析
- 足够丰富，可驱动：
- 在评审中人类可读
- 机器可解析
- 足够丰富，能够驱动：
- suite 执行
- QA 工作区 bootstrap
- QA 工作区引导
- QA Lab UI 元数据
- docs / discovery 提示词
- 文档/发现提示词
- 报告生成
### 首选编写格式
使用 Markdown 作为顶层格式，并在其中使用结构化 YAML。
使用 Markdown 作为顶层格式，并在其中嵌入结构化 YAML。
推荐结构：
@ -142,7 +148,7 @@ x-i18n:
- tags
- docs refs
- code refs
- model / provider overrides
- model/provider overrides
- prerequisites
- prose sections
- objective
@ -156,13 +162,13 @@ x-i18n:
这样可以获得：
- 比庞大的 JSON 更好的 PR 可读性
- 比大型 JSON 更好的 PR 可读性
- 比纯 YAML 更丰富的上下文
- 严格解析与 zod 校验
- 严格解析和 zod 校验
原始 JSON 仅应作为中间生成形式接受。
原始 JSON 只应作为中间生成形式被接受。
## 提议的场景文件结构
## 建议的场景文件结构
示例：
@ -187,7 +193,7 @@ codeRefs:
# Objective
Verify generated media is reattached on the follow-up turn.
验证生成的媒体会在后续轮次中重新附加。
# Setup
@ -208,7 +214,7 @@ Verify generated media is reattached on the follow-up turn.
- action: agent.send
session: agent:qa:image-roundtrip
message: |
Image generation check: generate a QA lighthouse image and summarize it in one short sentence.
图像生成检查：生成一张 QA 灯塔图像，并用一句简短的话总结它。
- action: artifact.capture
kind: generated-image
promptSnippet: Image generation check
@ -216,7 +222,7 @@ Verify generated media is reattached on the follow-up turn.
- action: agent.send
session: agent:qa:image-roundtrip
message: |
Roundtrip image inspection check: describe the generated lighthouse attachment in one short sentence.
图像往返检查：用一句简短的话描述生成的灯塔附件。
attachments:
- fromArtifact: lighthouseImage
```
@ -235,11 +241,11 @@ Verify generated media is reattached on the follow-up turn.
```
````
## DSL 必须覆盖的运行器能力
## DSL 必须覆盖的 Runner 能力
根据当前 suite，通用运行器需要的不只是提示词执行。
根据当前 suite，通用 runner 需要的不仅仅是执行提示词。
### 环境与设置动作
### 环境与设置操作
- `bus.reset`
- `gateway.waitHealthy`
@ -248,14 +254,14 @@ Verify generated media is reattached on the follow-up turn.
- `thread.create`
- `workspace.writeSkill`
### 智能体轮次动作
### 智能体轮次操作
- `agent.send`
- `agent.wait`
- `bus.injectInbound`
- `bus.injectOutbound`
### 配置与运行时动作
### 配置与运行时操作
- `config.get`
- `config.patch`
@ -264,7 +270,7 @@ Verify generated media is reattached on the follow-up turn.
- `tools.effective`
- `skills.status`
### 文件与产物动作
### 文件与产物操作
- `file.write`
- `file.read`
@ -273,7 +279,7 @@ Verify generated media is reattached on the follow-up turn.
- `artifact.captureGeneratedImage`
- `artifact.capturePath`
### Memory 与 cron 动作
### Memory 与 cron 操作
- `memory.indexForce`
- `memory.searchCli`
@ -283,7 +289,7 @@ Verify generated media is reattached on the follow-up turn.
- `cron.waitCompletion`
- `sessionTranscript.write`
### MCP 动作
### MCP 操作
- `mcp.callTool`
@ -307,62 +313,62 @@ Verify generated media is reattached on the follow-up turn.
DSL 必须支持保存输出并在后续引用。
当前 suite 中的示例：
来自当前 suite 的示例：
- 创建一个线程，然后复用 `threadId`
- 创建一个 session，然后复用 `sessionKey`
- 生成一张图片，然后在下一轮中附加该文件
- 生成一个 wake marker 字符串，然后断言它稍后出现
- 创建线程，然后复用 `threadId`
- 创建会话，然后复用 `sessionKey`
- 生成图像，然后在下一轮附加该文件
- 生成一个唤醒标记字符串，然后断言它稍后出现
所需能力：
- `saveAs`
- `${vars.name}`
- `${artifacts.name}`
- 针对路径、session key、线程 id、marker、工具输出的类型化引用
- 路径、会话键、线程 ID、标记、工具输出的类型化引用
如果没有变量支持，harness 逻辑就会继续泄漏回 TypeScript 中。
如果没有变量支持，测试框架逻辑仍会不断从 DSL 泄漏回 TypeScript。
## 哪些内容应保留为逃生口
在第 1 阶段，完全纯声明式的运行器并不现实。
在第一阶段，实现一个完全纯声明式的 runner 并不现实。
有些场景天然就是重编排型的：
有些场景天生就更偏编排：
- memory dreaming sweep
- config apply restart wake-up
- config restart capability flip
- 按时间戳 / 路径解析生成图像产物
- discovery-report evaluation
- 记忆 Dreaming 扫描
- 配置应用后重启唤醒
- 配置重启能力切换
- 基于时间戳/路径解析生成图像产物
- discovery-report 评估
这些目前应继续使用显式自定义 handler。
目前这些应继续使用显式自定义 handler。
推荐规则：
- 85-90% 声明式
- 对剩余困难部分使用显式 `customHandler` steps
- 仅允许具名且有文档说明的自定义 handler
- 不允许在场景文件中写匿名内联代码
- 85–90% 声明式
- 对于剩余复杂部分，使用显式 `customHandler` 步骤
- 仅允许已命名并有文档的自定义 handler
- 场景文件中不允许匿名内联代码
这样可以让通用引擎保持整洁，同时仍然推进迁移。
这样既能保持通用引擎整洁，又能继续推进。
## 架构变更
### 当前
场景 Markdown 现在已经是以下内容的事实来源：
场景 Markdown 现在已是以下内容的事实来源：
- suite 执行
- 工作区 bootstrap 文件
- 工作区引导文件
- QA Lab UI 场景目录
- 报告元数据
- discovery 提示词
- 发现提示词
生成的兼容性内容：
已生成的兼容性内容：
- seed 工作区仍然包含 `QA_KICKOFF_TASK.md`
- seed 工作区仍然包含 `QA_SCENARIO_PLAN.md`
- seed 工作区现在还包含 `QA_SCENARIOS.md`
- 种子工作区仍包含 `QA_KICKOFF_TASK.md`
- 种子工作区仍包含 `QA_SCENARIO_PLAN.md`
- 种子工作区现在还包含 `QA_SCENARIOS.md`
## 重构计划
@ -372,10 +378,10 @@ DSL 必须支持保存输出并在后续引用。
- 添加了 `qa/scenarios/index.md`
- 将场景拆分到 `qa/scenarios/<theme>/*.md`
- 为具名 Markdown YAML 包内容添加了解析器
- 添加了命名 Markdown YAML 包内容解析器
- 使用 zod 进行校验
- 将消费者切换到已解析的包
- 删除了仓库级 `qa/seed-scenarios.json` 和 `qa/QA_KICKOFF_TASK.md`
- 将消费者切换到解析后的包
- 移除了仓库级的 `qa/seed-scenarios.json` 和 `qa/QA_KICKOFF_TASK.md`
### 第 2 阶段：通用引擎
@ -385,55 +391,55 @@ DSL 必须支持保存输出并在后续引用。
- action registry
- assertion registry
- custom handlers
- 保留现有 helper functions 作为引擎操作
- 保留现有辅助函数作为引擎操作
交付物：
- 引擎执行简单的声明式场景
- 引擎可执行简单的声明式场景
先从主要是 prompt + wait + assert 的场景开始：
从主要是“提示词 + 等待 + 断言”的场景开始：
- threaded follow-up
- 线程跟进
- 从附件理解图像
- Skills 可见性与调用
- channel baseline
- skill 可见性与调用
- 渠道基线
交付物：
- 第一批真正由 Markdown 定义并通过通用引擎交付的场景
- 第一批真正由 Markdown 定义并通过通用引擎运行的场景上线
### 第 4 阶段：迁移中等复杂度场景
- image generation roundtrip
- 渠道上下文中的 memory 工具
- session memory ranking
- subagent handoff
- subagent fanout synthesis
- 图像生成往返
- 渠道上下文中的记忆工具
- 会话记忆排序
- 子智能体移交
- 子智能体扇出综合
交付物：
- 变量、产物、工具断言、request-log 断言都得到验证
- 变量、产物、工具断言、request-log 断言得到验证
### 第 5 阶段：将困难场景保留在自定义 handler 中
### 第 5 阶段：将复杂场景保留在自定义 handler 中
- memory dreaming sweep
- config apply restart wake-up
- config restart capability flip
- runtime inventory drift
- 记忆 Dreaming 扫描
- 配置应用后重启唤醒
- 配置重启能力切换
- 运行时清单漂移
交付物：
- 保持相同的编写格式，但在需要时使用显式 custom-step blocks
- 保持相同的编写格式，但在需要时使用显式自定义步骤块
### 第 6 阶段：删除硬编码场景映射
当包覆盖率足够高后：
- 删除 `extensions/qa-lab/src/suite.ts` 中大多数按场景分支的 TypeScript 逻辑
- 删除 `extensions/qa-lab/src/suite.ts` 中大部分特定场景的 TypeScript 分支逻辑
## Fake Slack / 富媒体支持
当前 QA 总线仍然是 text-first。
当前的 QA bus 以文本为主。
相关文件：
@ -443,17 +449,17 @@ DSL 必须支持保存输出并在后续引用。
- `extensions/qa-lab/src/bus-server.ts`
- `extensions/qa-lab/web/src/ui-render.ts`
目前 QA 总线支持：
当前 QA bus 支持：
- 文本
- reactions
- threads
- 反应
- 线程
它还不能建模内联媒体附件。
它尚未对内联媒体附件建模。
### 所需的传输契约
### 所需传输契约
添加通用 QA 总线附件模型：
添加一个通用 QA bus 附件模型：
```ts
type QaBusAttachment = {
@ -478,34 +484,34 @@ type QaBusAttachment = {
- `QaBusInboundMessageInput`
- `QaBusOutboundMessageInput`
### 为什么要先做通用层
### 为什么先做通用模型
不要构建仅限 Slack 的媒体模型。
而应该：
而应采用：
- 先有一个通用 QA 传输模型
- 再在其上构建多个渲染器
- 当前 QA Lab chat
- 一个通用 QA 传输模型
- 其上支持多个渲染器
- 当前的 QA Lab 聊天
- 未来的 fake Slack web
- 其他任何 fake transport views
- 其他任何 fake transport 视图
这样可以避免重复逻辑，并让媒体场景保持与传输层无关。
这样可以避免重复逻辑，并让媒体场景保持与传输方式无关。
### 所需的 UI 工作
### 所需 UI 工作
更新 QA UI 以渲染：
更新 QA UI，以渲染：
- 内联图片预览
- 内联音频播放器
- 内联视频播放器
- 文件附件 chip
当前 UI 已经可以渲染线程和 reactions，因此附件渲染应可以叠加到同一消息卡片模型上。
当前 UI 已能渲染线程和反应，因此附件渲染应能叠加到相同的消息卡片模型上。
### 媒体传输启用后的场景工作
### 媒体传输将启用的场景工作
一旦附件可以通过 QA 总线流转，我们就可以添加更丰富的 fake-chat 场景：
一旦附件可以通过 QA bus 流动，我们就能添加更丰富的 fake-chat 场景：
- fake Slack 中的内联图片回复
- 音频附件理解
@ -515,24 +521,24 @@ type QaBusAttachment = {
## 建议
下一块实现工作应是：
下一块实现应当是：
1. 添加 Markdown 场景加载器 + zod schema
2. 从 Markdown 生成当前目录
3. 先迁移几个简单场景
4. 添加通用 QA 总线附件支持
4. 添加通用 QA bus 附件支持
5. 在 QA UI 中渲染内联图片
6. 然后再扩展到音频和视频
6. 然后扩展到音频和视频
这是能同时验证两个目标的最小路径：
- 通用的 Markdown 定义 QA
- 更丰富的 fake messaging surfaces
- 通用、由 Markdown 定义的 QA
- 更丰富的 fake messaging 表面
## 开放问题
## 未决问题
- 场景文件是否应允许嵌入带变量插值的 Markdown 提示词模板
- setup / cleanup 应该是具名 section，还是仅作为有序动作列表
- 产物引用在 schema 中应采用强类型，还是基于字符串
- 自定义 handler 应放在一个统一 registry 中，还是按 surface 分 registry
- 在迁移期间，生成的 JSON 兼容性文件是否应继续保留为已检入状态
- 设置/清理应作为命名区段存在，还是仅作为有序操作列表
- 产物引用在 schema 中应为强类型，还是基于字符串
- 自定义 handler 应放在一个统一注册表中，还是按 surface 分注册表
- 在迁移期间，生成的 JSON 兼容文件是否应继续保留为已检入状态

33
docs/zh-CN/reference/rich-output-protocol.md
View File

@ -1,23 +1,28 @@
---
read_when:
- 更改 Control UI 中的助手输出渲染方式
- 调试 `[embed ...]`、`MEDIA:`、reply 或音频展示指令
summary: 用于嵌入、媒体、音频提示和回复的富输出短代码协议
title: 富输出协议
x-i18n:
generated_at: "2026-04-11T12:34:16Z"
generated_at: "2026-04-23T06:43:16Z"
model: gpt-5.4
provider: openai
source_hash: 2a8884fc2c304bf96d4675f0c1d1ff781d6dc1ae8c49d92ce08040c9c7709035
source_hash: 566338ac0571c6ab9062c6bad0bc4f71fe65249a3fcd9d8e575affcd93db11e7
source_path: reference/rich-output-protocol.md
workflow: 15
---
# 富输出协议
助手输出可以携带一小组传递/渲染指令：
助手输出可以携带一小组投递/渲染指令：
- `MEDIA:` 用于附件传递
- `[[audio_as_voice]]` 用于音频呈现提示
- `MEDIA:` 用于附件投递
- `[[audio_as_voice]]` 用于音频展示提示
- `[[reply_to_current]]` / `[[reply_to:<id>]]` 用于回复元数据
- `[embed ...]` 用于 Control UI 富渲染
这些指令彼此独立。`MEDIA:` 以及回复/语音标签仍然是传递元数据；`[embed ...]` 是仅限 Web 的富渲染路径。
这些指令彼此独立。`MEDIA:` 和 reply/voice 标签仍然属于投递元数据；`[embed ...]` 则是仅限 web 的富渲染路径。
## `[embed ...]`
@ -26,19 +31,19 @@ x-i18n:
自闭合示例：
```text
[embed ref="cv_123" title="状态" /]
[embed ref="cv_123" title="Status" /]
```
规则：
- `[view ...]` 不再对新输出有效。
- Embed 短代码只会在助手消息界面中渲染。
- 只有基于 URL 的 embed 会被渲染。使用 `ref="..."` 或 `url="..."`。
- 块级内联 HTML embed 短代码不会被渲染。
- Web UI 会从可见文本中移除该短代码，并以内联方式渲染 embed。
- `MEDIA:` 不是 embed 的别名，不应被用于富 embed 渲染。
- Embed 短代码仅在助手消息界面中渲染。
- 仅渲染基于 URL 的 embed。请使用 `ref="..."` 或 `url="..."`。
- 不渲染块形式的内联 HTML embed 短代码。
- Web UI 会从可见文本中移除该短代码，并在行内渲染 embed。
- `MEDIA:` 不是 embed 别名，不应用于富 embed 渲染。
## 存储渲染形状
## 存储的渲染形状
规范化/存储后的助手内容块是一个结构化的 `canvas` 项：
@ -57,4 +62,4 @@ x-i18n:
}
```
存储/渲染后的富内容块直接使用这个 `canvas` 形状。`present_view` 不会被识别。
存储/渲染后的富内容块直接使用这种 `canvas` 形状。`present_view` 不被识别。

109
docs/zh-CN/reference/transcript-hygiene.md
View File

@ -1,34 +1,38 @@
---
read_when:
- 你正在调试与转录形状相关的提供商请求拒绝问题
- 你正在修改转录清理或工具调用修复逻辑
- 你正在更改转录清理或工具调用修复逻辑
- 你正在调查跨提供商的工具调用 id 不匹配问题
summary: 参考：提供商专用的转录清理与修复规则
title: 转录清理
summary: 参考：提供商特定的转录清理与修复规则
title: 转录卫生规范
x-i18n:
generated_at: "2026-04-05T10:08:54Z"
generated_at: "2026-04-23T06:43:29Z"
model: gpt-5.4
provider: openai
source_hash: 217afafb693cf89651e8fa361252f7b5c197feb98d20be4697a83e6dedc0ec3f
source_hash: 0b528099b547155e5cf25be19e64a017d338b6f7b9c7ef51dc3ce2c2963193b8
source_path: reference/transcript-hygiene.md
workflow: 15
---
# 转录清理（提供商修复）
# 转录卫生规范（提供商修正规则）
本文档描述了在一次运行之前应用到转录上的**提供商专用修复**（构建模型上下文时）。这些是用于满足严格提供商要求的**内存中**调整。这些清理步骤**不会**重写磁盘上存储的 JSONL 转录；不过，在会话加载之前，单独的会话文件修复过程可能会通过丢弃无效行来重写格式错误的 JSONL 文件。发生修复时，原始文件会在会话文件旁边进行备份。
本文档描述了在一次运行之前对转录应用的**提供商特定修复**
（构建模型上下文时）。这些是用于满足严格
提供商要求的**内存中**调整。这些卫生步骤**不会**重写磁盘上存储的 JSONL 转录；
不过，在会话加载前，一个单独的会话文件修复流程可能会通过丢弃无效行来重写格式错误的 JSONL 文件。
发生修复时，原始文件会与会话文件一起进行备份。
范围包括：
- 工具调用 id 清理
- 工具调用输入校验
- 工具调用输入验证
- 工具结果配对修复
- 轮次校验 / 排序
- thought signature 清理
- 轮次验证 / 排序
- 思维签名清理
- 图像负载清理
- 用户输入来源标记（用于跨会话路由的提示词）
- 用户输入来源标记（用于跨会话路由的提示）
如果你需要转录存储的详细信息，请参见：
如果你需要了解转录存储细节，请参见：
- [/reference/session-management-compaction](/zh-CN/reference/session-management-compaction)
@ -36,62 +40,63 @@ x-i18n:
## 运行位置
所有转录清理都集中在嵌入式运行器中：
所有转录卫生逻辑都集中在嵌入式运行器中：
- 策略选择：`src/agents/transcript-policy.ts`
- 清理/修复应用：`src/agents/pi-embedded-runner/google.ts` 中的 `sanitizeSessionHistory`
- 清理/修复应用：`src/agents/pi-embedded-runner/replay-history.ts` 中的 `sanitizeSessionHistory`
该策略使用 `provider`、`modelApi` 和 `modelId` 来决定应用哪些规则。
与转录清理分开的是，会话文件会在加载前按需修复：
与转录卫生分开的是，会话文件会在加载前按需修复：
- `src/agents/session-file-repair.ts` 中的 `repairSessionFileIfNeeded`
- 从 `run/attempt.ts` 和 `compact.ts`（嵌入式运行器）中调用
- 由 `run/attempt.ts` 和 `compact.ts`（嵌入式运行器）调用
---
## 全局规则：图像清理
图像负载始终会被清理，以防因大小限制导致提供商侧拒绝
（对过大的 base64 图像进行缩放/重新压缩）。
图像负载始终会被清理，以防止因尺寸
限制而被提供商拒绝（对超大的 base64 图像进行缩放/重新压缩）。
这也有助于控制支持视觉的模型中由图像驱动的 token 压力。
这也有助于控制支持视觉模型时由图像驱动的 token 压力。
较低的最大尺寸通常会减少 token 使用量；较高的尺寸则能保留更多细节。
实现：
实现位置：
- `src/agents/pi-embedded-helpers/images.ts` 中的 `sanitizeSessionMessagesImages`
- `src/agents/tool-images.ts` 中的 `sanitizeContentBlocksImages`
- 最大图像边长可通过 `agents.defaults.imageMaxDimensionPx` 配置（默认：`1200`）。
- 最大图像边长可通过 `agents.defaults.imageMaxDimensionPx` 配置（默认值：`1200`）。
---
## 全局规则：格式错误的工具调用
缺少 `input` 和 `arguments` 的 assistant 工具调用区块会在构建模型上下文前被丢弃。
这可防止提供商因部分持久化的工具调用而拒绝请求（例如在速率限制失败之后）。
缺少 `input` 和 `arguments` 的 assistant 工具调用块会在构建
模型上下文前被丢弃。这可防止提供商因部分持久化的工具调用
而拒绝请求（例如在速率限制失败之后）。
实现：
实现位置：
- `src/agents/session-transcript-repair.ts` 中的 `sanitizeToolCallInputs`
- 应用于 `src/agents/pi-embedded-runner/google.ts` 中的 `sanitizeSessionHistory`
- 应用于 `src/agents/pi-embedded-runner/replay-history.ts` 中的 `sanitizeSessionHistory`
---
## 全局规则：跨会话输入来源
当智能体通过 `sessions_send` 将提示词发送到另一个会话时（包括
智能体对智能体的回复/公告步骤），OpenClaw 会将创建的用户轮次持久化为：
当一个智能体通过 `sessions_send` 向另一个会话发送提示时（包括
智能体到智能体的回复/公告步骤），OpenClaw 会将创建出的用户轮次持久化为：
- `message.provenance.kind = "inter_session"`
该元数据会在追加转录时写入，不会改变角色
（为兼容提供商，`role: "user"` 保持不变）。转录读取器可以利用
这一点，避免将路由的内部提示词视为最终用户撰写的指令。
此元数据在追加到转录时写入，不会改变角色
（为了兼容提供商，仍保持 `role: "user"`）。转录读取器可以利用
这一点，避免将路由的内部提示视为终端用户编写的指令。
在上下文重建期间，OpenClaw 还会在内存中为这些用户轮次前置一个简短的 `[Inter-session message]`
标记，以便模型将它们与
外部最终用户指令区分开来。
在重建上下文期间，OpenClaw 还会在内存中为这些用户轮次前置一个简短的 `[Inter-session message]`
标记，以便模型将其与
外部终端用户指令区分开来。
---
@ -100,35 +105,35 @@ x-i18n:
**OpenAI / OpenAI Codex**
- 仅图像清理。
- 对于 OpenAI Responses/Codex 转录，丢弃孤立的 reasoning signature（后面没有内容区块的独立 reasoning 项）。
- 对于 OpenAI Responses/Codex 转录，丢弃孤立的 reasoning 签名（即后面没有跟随内容块的独立 reasoning 项）。
- 不进行工具调用 id 清理。
- 不进行工具结果配对修复。
- 不进行轮次校验或重排序。
- 不生成合成工具结果。
- 不移除 thought signature。
- 不进行轮次验证或重新排序。
- 不注入合成工具结果。
- 不移除 thought 签名。
**Google（Generative AI / Gemini CLI / Antigravity）**
- 工具调用 id 清理：严格字母数字。
- 工具结果配对修复和合成工具结果。
- 轮次校验（Gemini 风格轮次交替）。
- Google 轮次排序修复（如果历史记录以 assistant 开始，则前置一个很小的用户 bootstrap）。
- Antigravity Claude：规范化 thinking signature；丢弃未签名的 thinking 区块。
- 轮次验证（Gemini 风格的轮次交替）。
- Google 轮次顺序修复（如果历史记录以 assistant 开始，则前置一个很小的用户引导消息）。
- Antigravity Claude：规范化 thinking 签名；丢弃未签名的 thinking 块。
**Anthropic / Minimax（兼容 Anthropic）**
**Anthropic / Minimax（Anthropic 兼容）**
- 工具结果配对修复和合成工具结果。
- 轮次校验（合并连续的用户轮次，以满足严格交替要求）。
- 轮次验证（合并连续的用户轮次，以满足严格交替要求）。
**Mistral（包括基于 model-id 的检测）**
**Mistral（包括基于 model id 的检测）**
- 工具调用 id 清理：strict9（长度为 9 的字母数字）。
**OpenRouter Gemini**
- Thought signature 清理：移除非 base64 的 `thought_signature` 值（保留 base64）。
- thought 签名清理：移除非 base64 的 `thought_signature` 值（保留 base64）。
**其他所有情况**
**其他所有提供商**
- 仅图像清理。
@ -136,17 +141,17 @@ x-i18n:
## 历史行为（2026.1.22 之前）
在 2026.1.22 版本之前，OpenClaw 会应用多层转录清理：
在 2026.1.22 发布之前，OpenClaw 应用了多层转录卫生处理：
- 一个 **transcript-sanitize 扩展** 会在每次构建上下文时运行，并且可能：
- 每次构建上下文时都会运行一个 **transcript-sanitize 扩展**，它可以：
- 修复工具使用/结果配对。
- 清理工具调用 id（包括保留 `_`/`-` 的非严格模式）。
- 运行器还会执行提供商专用清理，从而造成重复工作。
- 还有额外的变更发生在提供商策略之外，包括：
- 在持久化之前从 assistant 文本中移除 `<final>` 标签。
- 运行器也会执行提供商特定清理，这造成了重复工作。
- 在提供商策略之外还存在额外变更，包括：
- 在持久化前从 assistant 文本中移除 `<final>` 标签。
- 丢弃空的 assistant 错误轮次。
- 在工具调用之后裁剪 assistant 内容。
- 在工具调用后裁剪 assistant 内容。
这种复杂性导致了跨提供商回归（尤其是 `openai-responses`
`call_id|fc_id` 配对）。2026.1.22 的清理工作移除了该扩展，将
逻辑集中到运行器中，并使 OpenAI 除图像清理之外保持**不触碰**。
逻辑集中到运行器中，并让 OpenAI 除图像清理之外保持**不做额外处理**。

94
docs/zh-CN/start/hubs.md
View File

@ -1,40 +1,40 @@
---
read_when:
- 你想查看完整的文档地图
summary: 链接到每一篇 OpenClaw 文档的中心页
title: 文档中心
- 你想要一份完整的文档地图
summary: 链接到所有 OpenClaw 文档的导航中心
title: 文档导航中心
x-i18n:
generated_at: "2026-04-05T10:09:27Z"
generated_at: "2026-04-23T06:43:24Z"
model: gpt-5.4
provider: openai
source_hash: 4998710e3dc8018a50abc41285caac83df4b3bf8aec2e4a7525a0563649eb06c
source_hash: 4bf24887af25cb345834e7f61e33d1ca3595833a42934ae91a87cc0951b3ae10
source_path: start/hubs.md
workflow: 15
---
# 文档中心
# 文档导航中心
<Note>
如果你是 OpenClaw 新用户，请先阅读 [入门指南](/zh-CN/start/getting-started)。
如果你刚开始接触 OpenClaw，请先阅读 [入门指南](/zh-CN/start/getting-started)。
</Note>
使用这些中心页来发现所有页面，包括那些不会出现在左侧导航中的深入解析和参考文档。
使用这些导航中心来发现每一页文档，包括左侧导航中未显示的深度解析和参考文档。
## 从这里开始
- [索引](/zh-CN)
- [Index](/zh-CN)
- [入门指南](/zh-CN/start/getting-started)
- [新手引导](/zh-CN/start/onboarding)
- [设置向导（CLI）](/zh-CN/start/wizard)
- [设置](/zh-CN/start/setup)
- [仪表板（本地 Gateway 网关）](http://127.0.0.1:18789/)
- [帮助](/zh-CN/help)
- [Dashboard（本地 Gateway 网关）](http://127.0.0.1:18789/)
- [Help](/zh-CN/help)
- [文档目录](/zh-CN/start/docs-directory)
- [配置](/zh-CN/gateway/configuration)
- [配置示例](/zh-CN/gateway/configuration-examples)
- [OpenClaw 助手](/zh-CN/start/openclaw)
- [展示](/zh-CN/start/showcase)
- [背景故事](/zh-CN/start/lore)
- [OpenClaw assistant](/zh-CN/start/openclaw)
- [Showcase](/zh-CN/start/showcase)
- [Lore](/zh-CN/start/lore)
## 安装 + 更新
@ -45,7 +45,7 @@ x-i18n:
## 核心概念
- [架构](/zh-CN/concepts/architecture)
- [Architecture](/zh-CN/concepts/architecture)
- [功能](/zh-CN/concepts/features)
- [网络中心](/zh-CN/network)
- [智能体运行时](/zh-CN/concepts/agent)
@ -56,7 +56,7 @@ x-i18n:
- [多智能体路由](/zh-CN/concepts/multi-agent)
- [压缩](/zh-CN/concepts/compaction)
- [会话](/zh-CN/concepts/session)
- [会话修剪](/zh-CN/concepts/session-pruning)
- [会话裁剪](/zh-CN/concepts/session-pruning)
- [会话工具](/zh-CN/concepts/session-tool)
- [队列](/zh-CN/concepts/queue)
- [斜杠命令](/zh-CN/tools/slash-commands)
@ -69,10 +69,10 @@ x-i18n:
- [渠道路由](/zh-CN/channels/channel-routing)
- [群组](/zh-CN/channels/groups)
- [群组消息](/zh-CN/channels/group-messages)
- [模型故障转移](/zh-CN/concepts/model-failover)
- [模型故障切换](/zh-CN/concepts/model-failover)
- [OAuth](/zh-CN/concepts/oauth)
## 提供商 + 入站入口
## 提供商 + 接入
- [聊天渠道中心](/zh-CN/channels)
- [模型提供商中心](/zh-CN/providers/models)
@ -86,7 +86,7 @@ x-i18n:
- [QQ Bot](/zh-CN/channels/qqbot)
- [iMessage（旧版）](/zh-CN/channels/imessage)
- [位置解析](/zh-CN/channels/location)
- [WebChat](/web/webchat)
- [WebChat](/zh-CN/web/webchat)
- [Webhooks](/zh-CN/automation/cron-jobs#webhooks)
- [Gmail Pub/Sub](/zh-CN/automation/cron-jobs#gmail-pubsub-integration)
@ -97,13 +97,13 @@ x-i18n:
- [Gateway 网关配对](/zh-CN/gateway/pairing)
- [Gateway 网关锁](/zh-CN/gateway/gateway-lock)
- [后台进程](/zh-CN/gateway/background-process)
- [健康检查](/zh-CN/gateway/health)
- [心跳](/zh-CN/gateway/heartbeat)
- [健康状态](/zh-CN/gateway/health)
- [Heartbeat](/zh-CN/gateway/heartbeat)
- [Doctor](/zh-CN/gateway/doctor)
- [日志记录](/zh-CN/gateway/logging)
- [日志](/zh-CN/gateway/logging)
- [沙箱隔离](/zh-CN/gateway/sandboxing)
- [仪表板](/web/dashboard)
- [Control UI](/web/control-ui)
- [Dashboard](/zh-CN/web/dashboard)
- [Control UI](/zh-CN/web/control-ui)
- [远程访问](/zh-CN/gateway/remote)
- [远程 Gateway 网关 README](/zh-CN/gateway/remote-gateway-readme)
- [Tailscale](/zh-CN/gateway/tailscale)
@ -112,28 +112,28 @@ x-i18n:
## 工具 + 自动化
- [工具界面](/zh-CN/tools)
- [工具总览](/zh-CN/tools)
- [OpenProse](/zh-CN/prose)
- [CLI 参考](/cli)
- [CLI 参考](/zh-CN/cli)
- [Exec 工具](/zh-CN/tools/exec)
- [PDF 工具](/tools/pdf)
- [Elevated 模式](/zh-CN/tools/elevated)
- [PDF 工具](/zh-CN/tools/pdf)
- [提升模式](/zh-CN/tools/elevated)
- [Cron 作业](/zh-CN/automation/cron-jobs)
- [自动化与任务](/zh-CN/automation)
- [思考 + 详细模式](/zh-CN/tools/thinking)
- [Thinking + verbose](/zh-CN/tools/thinking)
- [模型](/zh-CN/concepts/models)
- [子智能体](/zh-CN/tools/subagents)
- [智能体发送 CLI](/zh-CN/tools/agent-send)
- [终端 UI](/web/tui)
- [Agent send CLI](/zh-CN/tools/agent-send)
- [Terminal UI](/zh-CN/web/tui)
- [浏览器控制](/zh-CN/tools/browser)
- [浏览器（Linux 故障排除）](/zh-CN/tools/browser-linux-troubleshooting)
- [投票](/cli/message)
- [Browser（Linux 故障排除）](/zh-CN/tools/browser-linux-troubleshooting)
- [投票](/zh-CN/cli/message)
## 节点、媒体、语音
- [节点概览](/zh-CN/nodes)
- [相机](/zh-CN/nodes/camera)
- [图片](/zh-CN/nodes/images)
- [图像](/zh-CN/nodes/images)
- [音频](/zh-CN/nodes/audio)
- [位置命令](/zh-CN/nodes/location-command)
- [语音唤醒](/zh-CN/nodes/voicewake)
@ -147,39 +147,39 @@ x-i18n:
- [Android](/zh-CN/platforms/android)
- [Windows（WSL2）](/zh-CN/platforms/windows)
- [Linux](/zh-CN/platforms/linux)
- [Web 界面](/web)
- [Web 界面](/zh-CN/web)
## macOS 配套应用（高级）
- [macOS 开发设置](/zh-CN/platforms/mac/dev-setup)
- [macOS 菜单栏](/zh-CN/platforms/mac/menu-bar)
- [macOS 语音唤醒](/zh-CN/platforms/mac/voicewake)
- [macOS 语音覆盖层](/zh-CN/platforms/mac/voice-overlay)
- [macOS 语音浮层](/zh-CN/platforms/mac/voice-overlay)
- [macOS WebChat](/zh-CN/platforms/mac/webchat)
- [macOS Canvas](/zh-CN/platforms/mac/canvas)
- [macOS 子进程](/zh-CN/platforms/mac/child-process)
- [macOS 健康检查](/zh-CN/platforms/mac/health)
- [macOS 健康状态](/zh-CN/platforms/mac/health)
- [macOS 图标](/zh-CN/platforms/mac/icon)
- [macOS 日志记录](/zh-CN/platforms/mac/logging)
- [macOS 日志](/zh-CN/platforms/mac/logging)
- [macOS 权限](/zh-CN/platforms/mac/permissions)
- [macOS 远程](/zh-CN/platforms/mac/remote)
- [macOS 远程访问](/zh-CN/platforms/mac/remote)
- [macOS 签名](/zh-CN/platforms/mac/signing)
- [macOS Gateway 网关（launchd）](/zh-CN/platforms/mac/bundled-gateway)
- [macOS XPC](/zh-CN/platforms/mac/xpc)
- [macOS Skills](/zh-CN/platforms/mac/skills)
- [macOS Peekaboo](/zh-CN/platforms/mac/peekaboo)
## 扩展 + 插件
## 插件
- [插件概览](/zh-CN/tools/plugin)
- [Building Plugins](/zh-CN/plugins/building-plugins)
- [Plugin Manifest](/zh-CN/plugins/manifest)
- [Plugins 概览](/zh-CN/tools/plugin)
- [构建插件](/zh-CN/plugins/building-plugins)
- [插件清单](/zh-CN/plugins/manifest)
- [智能体工具](/zh-CN/plugins/building-plugins#registering-agent-tools)
- [插件包](/zh-CN/plugins/bundles)
- [社区插件](/zh-CN/plugins/community)
- [能力扩展手册](/tools/capability-cookbook)
- [语音通话插件](/zh-CN/plugins/voice-call)
- [Zalo 用户插件](/zh-CN/plugins/zalouser)
- [能力扩展手册](/zh-CN/plugins/architecture)
- [Voice call 插件](/zh-CN/plugins/voice-call)
- [Zalo user 插件](/zh-CN/plugins/zalouser)
## 工作区 + 模板
@ -203,4 +203,4 @@ x-i18n:
- [测试](/zh-CN/reference/test)
- [发布策略](/zh-CN/reference/RELEASING)
- [设备型号](/zh-CN/reference/device-models)
- [设备模型](/zh-CN/reference/device-models)

176
docs/zh-CN/start/showcase.md
View File

@ -1,27 +1,25 @@
---
description: Real-world OpenClaw projects from the community
read_when:
- 在寻找真实的 OpenClaw 使用示例吗
- 更新社区项目亮点
- 寻找真实的 OpenClaw 使用示例
- 更新社区项目精选
summary: 由 OpenClaw 驱动的社区构建项目和集成
title: 展示区
x-i18n:
generated_at: "2026-04-14T13:43:49Z"
generated_at: "2026-04-23T06:43:41Z"
model: gpt-5.4
provider: openai
source_hash: 797d0b85c9eca920240c79d870eb9636216714f3eba871c5ebd0f7f40cf7bbf1
source_hash: 5bf4bd2548709a01ad18331537f804b32c3213139c2234915aa17f7a2638f19f
source_path: start/showcase.md
workflow: 15
---
<!-- markdownlint-disable MD033 -->
# 展示区
<div className="showcase-hero">
<p className="showcase-kicker">构建于聊天、终端、浏览器和客厅之中</p>
<p className="showcase-lead">
OpenClaw 项目不是玩具演示。人们正在从他们已经在使用的渠道中，交付 PR 审查闭环、移动应用、家庭自动化、语音系统、开发工具，以及内存密集型工作流。
OpenClaw 项目不是玩具演示。人们正在通过他们早已使用的渠道，交付 PR 审查循环、移动应用、家庭自动化、语音系统、开发工具和重度记忆工作流。
</p>
<div className="showcase-actions">
<a href="#videos">观看演示</a>
@ -30,27 +28,27 @@ x-i18n:
</div>
<div className="showcase-highlights">
<div className="showcase-highlight">
<strong>原生聊天式构建</strong>
<span>Telegram、WhatsApp、Discord、Beeper、网页聊天，以及以终端为先的工作流。</span>
<strong>聊天原生构建</strong>
<span>Telegram、WhatsApp、Discord、Beeper、网页聊天，以及终端优先工作流。</span>
</div>
<div className="showcase-highlight">
<strong>真实自动化</strong>
<span>预订、购物、支持、报告和浏览器控制，无需等待 API。</span>
</div>
<div className="showcase-highlight">
<strong>本地 + 现实世界</strong>
<span>打印机、扫地机器人、摄像头、健康数据、家庭系统，以及个人知识库。</span>
<strong>本地 + 物理世界</strong>
<span>打印机、扫地机器人、摄像头、健康数据、家庭系统和个人知识库。</span>
</div>
</div>
</div>
<Info>
**想被推荐展示吗？** 在 [Discord 的 #self-promotion](https://discord.gg/clawd) 中分享你的项目，或在 [X 上 @openclaw](https://x.com/openclaw) 标记我们。
**想被推荐展示？** 请在 [Discord 的 #self-promotion](https://discord.gg/clawd) 中分享你的项目，或在 [X 上标记 @openclaw](https://x.com/openclaw)。
</Info>
<div className="showcase-jump-links">
<a href="#videos">视频</a>
<a href="#fresh-from-discord">Discord 最新项目</a>
<a href="#fresh-from-discord">Discord 最新精选</a>
<a href="#automation-workflows">自动化</a>
<a href="#knowledge-memory">记忆</a>
<a href="#voice-phone">语音与电话</a>
@ -60,10 +58,10 @@ x-i18n:
<a href="#submit-your-project">提交项目</a>
</div>
<h2 id="videos">视频</h2>
## 视频
<p className="showcase-section-intro">
如果你想用最短路径从“这是什么？”到“好，我懂了。”，请从这里开始。
如果你想用最短路径从“这是什么？”走到“好，我懂了”，就从这里开始。
</p>
<div className="showcase-video-grid">
@ -71,14 +69,14 @@ x-i18n:
<div className="showcase-video-shell">
<iframe
src="https://www.youtube-nocookie.com/embed/SaWSPZoPX34"
title="OpenClaw：本应成为 Siri 的自托管 AI（完整设置）"
title="OpenClaw：本应由 Siri 提供的自托管 AI（完整安装）"
loading="lazy"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
allowFullScreen
/>
</div>
<h3>完整设置演练</h3>
<p>VelvetShark，28 分钟。安装、新手引导，并从头到尾完成第一个可用助手的配置。</p>
<h3>完整安装演练</h3>
<p>VelvetShark，28 分钟。从安装、新手引导到端到端获得第一个可用助手。</p>
<a href="https://www.youtube.com/watch?v=SaWSPZoPX34">在 YouTube 上观看</a>
</div>
@ -93,7 +91,7 @@ x-i18n:
/>
</div>
<h3>社区展示集锦</h3>
<p>更快速地浏览围绕 OpenClaw 构建的真实项目、使用界面和工作流。</p>
<p>快速浏览围绕 OpenClaw 构建的真实项目、界面和工作流。</p>
<a href="https://www.youtube.com/watch?v=mMSKQvlmFuQ">在 YouTube 上观看</a>
</div>
@ -108,15 +106,15 @@ x-i18n:
/>
</div>
<h3>真实世界中的项目</h3>
<p>来自社区的示例，涵盖原生聊天式编码闭环、硬件和个人自动化。</p>
<p>来自社区的示例，从聊天原生编码循环到硬件和个人自动化。</p>
<a href="https://www.youtube.com/watch?v=5kkIJNUGFho">在 YouTube 上观看</a>
</div>
</div>
<h2 id="fresh-from-discord">Discord 最新项目</h2>
## Discord 最新精选
<p className="showcase-section-intro">
近期在编码、开发工具、移动端以及原生聊天式产品构建方面的亮眼项目。
近期在编码、开发工具、移动端和聊天原生产品构建方面的亮点项目。
</p>
<CardGroup cols={2}>
@ -124,23 +122,23 @@ x-i18n:
<Card title="PR 审查 → Telegram 反馈" icon="code-pull-request" href="https://x.com/i/status/2010878524543131691">
**@bangnokia** • `review` `github` `telegram`
OpenCode 完成更改 → 打开 PR → OpenClaw 审查 diff，并在 Telegram 中回复“次要建议”和明确的合并结论（包括需优先修复的关键问题）。
OpenCode 完成更改 → 打开 PR → OpenClaw 审查 diff，并在 Telegram 中回复“细微建议”以及明确的合并结论（包括需要优先修复的关键问题）。
<img src="/assets/showcase/pr-review-telegram.jpg" alt="通过 Telegram 发送的 OpenClaw PR 审查反馈" />
<img src="/assets/showcase/pr-review-telegram.jpg" alt="OpenClaw 在 Telegram 中交付 PR 审查反馈" />
</Card>
<Card title="几分钟构建葡萄酒酒窖 Skill" icon="wine-glass" href="https://x.com/i/status/2010916352454791216">
<Card title="几分钟内构建酒窖 Skill" icon="wine-glass" href="https://x.com/i/status/2010916352454791216">
**@prades_maxime** • `skills` `local` `csv`
请求“Robby”（@openclaw）创建一个本地葡萄酒酒窖 Skill。它会索要一个示例 CSV 导出文件以及存储位置，然后快速构建并测试该 Skill（示例中有 962 瓶）。
向 “Robby”（@openclaw）请求一个本地酒窖 Skill。它会索取示例 CSV 导出和存储位置，然后快速构建/测试该 Skill（示例中为 962 瓶）。
<img src="/assets/showcase/wine-cellar-skill.jpg" alt="OpenClaw 从 CSV 构建本地葡萄酒酒窖 Skill" />
<img src="/assets/showcase/wine-cellar-skill.jpg" alt="OpenClaw 根据 CSV 构建本地酒窖 Skill" />
</Card>
<Card title="Tesco 购物自动驾驶" icon="cart-shopping" href="https://x.com/i/status/2009724862470689131">
**@marchattonhere** • `automation` `browser` `shopping`
每周膳食计划 → 常购商品 → 预订配送时段 → 确认订单。无需 API，只靠浏览器控制。
每周餐单 → 常购商品 → 预订配送时段 → 确认订单。无需 API，只用浏览器控制。
<img src="/assets/showcase/tesco-shop.jpg" alt="通过聊天实现 Tesco 购物自动化" />
</Card>
@ -148,7 +146,7 @@ OpenCode 完成更改 → 打开 PR → OpenClaw 审查 diff，并在 Telegram
<Card title="SNAG 截图转 Markdown" icon="scissors" href="https://github.com/am-will/snag">
**@am-will** • `devtools` `screenshots` `markdown`
热键选取屏幕区域 → Gemini 视觉 → 剪贴板中即时获得 Markdown。
热键选择屏幕区域 → Gemini 视觉 → Markdown 即刻进入你的剪贴板。
<img src="/assets/showcase/snag.png" alt="SNAG 截图转 Markdown 工具" />
</Card>
@ -164,7 +162,7 @@ OpenCode 完成更改 → 打开 PR → OpenClaw 审查 diff，并在 Telegram
<Card title="Telegram 语音便笺（papla.media）" icon="microphone" href="https://papla.media/docs">
**社区** • `voice` `tts` `telegram`
封装 papla.media TTS，并将结果作为 Telegram 语音便笺发送（没有烦人的自动播放）。
封装 papla.media TTS，并将结果作为 Telegram 语音便笺发送（不会有烦人的自动播放）。
<img src="/assets/showcase/papla-tts.jpg" alt="来自 TTS 的 Telegram 语音便笺输出" />
</Card>
@ -188,7 +186,7 @@ OpenCode 完成更改 → 打开 PR → OpenClaw 审查 diff，并在 Telegram
<Card title="维也纳交通（Wiener Linien）" icon="train" href="https://clawhub.ai/hjanuschka/wienerlinien">
**@hjanuschka** • `travel` `transport` `skill`
提供维也纳公共交通的实时发车信息、中断情况、电梯状态和路线规划。
提供维也纳公共交通的实时发车、故障、电梯状态和路线规划。
<img src="/assets/showcase/wienerlinien.png" alt="Wiener Linien Skill" />
</Card>
@ -196,19 +194,19 @@ OpenCode 完成更改 → 打开 PR → OpenClaw 审查 diff，并在 Telegram
<Card title="ParentPay 学校餐食" icon="utensils">
**@George5562** • `automation` `browser` `parenting`
通过 ParentPay 自动预订英国学校餐食。使用鼠标坐标来可靠点击表格单元格。
通过 ParentPay 自动预订英国学校餐食。使用鼠标坐标可靠点击表格单元格。
</Card>
<Card title="R2 上传（把文件发给我）" icon="cloud-arrow-up" href="https://clawhub.ai/skills/r2-upload">
<Card title="R2 上传（把我的文件发给我）" icon="cloud-arrow-up" href="https://clawhub.ai/skills/r2-upload">
**@julianengel** • `files` `r2` `presigned-urls`
上传到 Cloudflare R2/S3 并生成安全的预签名下载链接。非常适合远程 OpenClaw 实例。
上传到 Cloudflare R2/S3，并生成安全的预签名下载链接。非常适合远程 OpenClaw 实例。
</Card>
<Card title="通过 Telegram 构建 iOS 应用" icon="mobile">
**@coard** • `ios` `xcode` `testflight`
完全通过 Telegram 聊天构建了一个包含地图和语音录制功能的完整 iOS 应用，并部署到 TestFlight。
完全通过 Telegram 聊天构建了一个带地图和语音录制功能的完整 iOS 应用，并部署到 TestFlight。
<img src="/assets/showcase/ios-testflight.jpg" alt="TestFlight 上的 iOS 应用" />
</Card>
@ -216,34 +214,36 @@ OpenCode 完成更改 → 打开 PR → OpenClaw 审查 diff，并在 Telegram
<Card title="Oura Ring 健康助手" icon="heart-pulse">
**@AS** • `health` `oura` `calendar`
将 Oura ring 数据与日历、预约和健身安排集成的个人 AI 健康助手。
个人 AI 健康助手，将 Oura ring 数据与日历、预约和健身安排集成。
<img src="/assets/showcase/oura-health.png" alt="Oura ring 健康助手" />
</Card>
<Card title="Kev 的梦之队（14+ 个智能体）" icon="robot" href="https://github.com/adam91holt/orchestrated-ai-articles">
<Card title="Kev 的梦之队（14+ 智能体）" icon="robot" href="https://github.com/adam91holt/orchestrated-ai-articles">
**@adam91holt** • `multi-agent` `orchestration` `architecture` `manifesto`
一个 Gateway 网关下运行 14+ 个智能体，由 Opus 4.5 编排器委派任务给 Codex worker。完整的[技术说明](https://github.com/adam91holt/orchestrated-ai-articles)涵盖了梦之队成员、模型选择、沙箱隔离、webhook、心跳和委派流程。用于智能体沙箱隔离的 [Clawdspace](https://github.com/adam91holt/clawdspace)。[博客文章](https://adams-ai-journey.ghost.io/2026-the-year-of-the-orchestrator/)。
一个 Gateway 网关 下运行 14+ 个智能体，由 Opus 4.5 编排器委派给 Codex 工作智能体。完整的[技术说明](https://github.com/adam91holt/orchestrated-ai-articles)涵盖 Dream Team 阵容、模型选择、沙箱隔离、webhooks、心跳和委派流程。[Clawdspace](https://github.com/adam91holt/clawdspace) 用于智能体沙箱隔离。[博客文章](https://adams-ai-journey.ghost.io/2026-the-year-of-the-orchestrator/)。
</Card>
<Card title="Linear CLI" icon="terminal" href="https://github.com/Finesssee/linear-cli">
**@NessZerra** • `devtools` `linear` `cli` `issues`
一个可与智能体工作流（Claude Code、OpenClaw）集成的 Linear CLI。从终端管理 issue、项目和工作流。首个外部 PR 已合并！
适用于 Linear 的 CLI，可与智能体式工作流（Claude Code、OpenClaw）集成。在终端中管理 issue、项目和工作流。首个外部 PR 已合并！
</Card>
<Card title="Beeper CLI" icon="message" href="https://github.com/blqke/beepcli">
**@jules** • `messaging` `beeper` `cli` `automation`
通过 Beeper Desktop 读取、发送和归档消息。使用 Beeper 本地 MCP API，因此智能体可以在一个地方管理你所有聊天（iMessage、WhatsApp 等）。
通过 Beeper Desktop 读取、发送和归档消息。使用 Beeper 本地 MCP API，因此智能体可以在一个地方管理你的所有聊天（iMessage、WhatsApp 等）。
</Card>
</CardGroup>
<h2 id="automation-workflows">自动化与工作流</h2>
<a id="automation-workflows"></a>
## 自动化与工作流
<p className="showcase-section-intro">
日程安排、浏览器控制、支持闭环，以及产品中“直接替我把任务做完”的那一面。
涵盖排程、浏览器控制、支持循环，以及“直接替我把这件事做了”的产品能力。
</p>
<CardGroup cols={2}>
@ -251,23 +251,23 @@ OpenCode 完成更改 → 打开 PR → OpenClaw 审查 diff，并在 Telegram
<Card title="Winix 空气净化器控制" icon="wind" href="https://x.com/antonplex/status/2010518442471006253">
**@antonplex** • `automation` `hardware` `air-quality`
Claude Code 发现并确认了净化器控制方式，然后 OpenClaw 接手管理室内空气质量。
Claude Code 发现并确认了净化器控制方式，然后由 OpenClaw 接手管理房间空气质量。
<img src="/assets/showcase/winix-air-purifier.jpg" alt="通过 OpenClaw 控制 Winix 空气净化器" />
</Card>
<Card title="漂亮天空相机拍摄" icon="camera" href="https://x.com/signalgaining/status/2010523120604746151">
<Card title="漂亮天空相机抓拍" icon="camera" href="https://x.com/signalgaining/status/2010523120604746151">
**@signalgaining** • `automation` `camera` `skill` `images`
由屋顶摄像头触发：每当天空看起来很美时，就让 OpenClaw 拍一张天空照片——它设计了一个 Skill 并完成了拍摄。
由屋顶摄像头触发：每当天空看起来很美时，就让 OpenClaw 拍一张天空照片 —— 它设计了一个 Skill 并完成了拍摄。
<img src="/assets/showcase/roof-camera-sky.jpg" alt="由 OpenClaw 捕捉的屋顶摄像头天空快照" />
<img src="/assets/showcase/roof-camera-sky.jpg" alt="由 OpenClaw 捕获的屋顶摄像头天空快照" />
</Card>
<Card title="可视化晨间简报场景" icon="robot" href="https://x.com/buddyhadry/status/2010005331925954739">
**@buddyhadry** • `automation` `briefing` `images` `telegram`
一个定时提示词每天早晨生成一张“场景”图片（天气、任务、日期、喜欢的帖子/语录），通过 OpenClaw 人设完成。
一个定时提示词每天早晨生成一张“场景”图像（天气、任务、日期、喜欢的帖子/语录），由一个 OpenClaw 人设驱动。
</Card>
<Card title="Padel 球场预订" icon="calendar-check" href="https://github.com/joshp123/padel-cli">
@ -281,13 +281,13 @@ Claude Code 发现并确认了净化器控制方式，然后 OpenClaw 接手管
<Card title="会计资料收集" icon="file-invoice-dollar">
**社区** • `automation` `email` `pdf`
从电子邮件收集 PDF，并为税务顾问准备文档。每月会计工作进入自动驾驶。
从电子邮件中收集 PDF，并为税务顾问整理文档。每月会计工作进入自动驾驶。
</Card>
<Card title="沙发土豆开发模式" icon="couch" href="https://davekiss.com">
**@davekiss** • `telegram` `website` `migration` `astro`
通过 Telegram 重建了整个个人网站，同时还在看 Netflix——Notion → Astro，迁移了 18 篇文章，DNS 切到 Cloudflare。全程没有打开过笔记本电脑。
通过 Telegram 重建了整个个人网站，同时还在看 Netflix —— Notion → Astro，迁移了 18 篇文章，DNS 切换到 Cloudflare。全程没打开过笔记本电脑。
</Card>
<Card title="求职智能体" icon="briefcase">
@ -299,33 +299,35 @@ Claude Code 发现并确认了净化器控制方式，然后 OpenClaw 接手管
<Card title="Jira Skill 构建器" icon="diagram-project" href="https://x.com/jdrhyne/status/2008336434827002232">
**@jdrhyne** • `automation` `jira` `skill` `devtools`
OpenClaw 连接到 Jira，然后实时生成了一个新的 Skill（当时它甚至还不存在于 ClawHub 上）。
OpenClaw 连接到 Jira，然后即时生成了一个新 Skill（当时它甚至还不存在于 ClawHub 上）。
</Card>
<Card title="通过 Telegram 使用 Todoist Skill" icon="list-check" href="https://x.com/iamsubhrajyoti/status/2009949389884920153">
**@iamsubhrajyoti** • `automation` `todoist` `skill` `telegram`
实现了 Todoist 任务自动化，并让 OpenClaw 直接在 Telegram 聊天中生成该 Skill。
自动化 Todoist 任务，并让 OpenClaw 直接在 Telegram 聊天中生成该 Skill。
</Card>
<Card title="TradingView 分析" icon="chart-line">
**@bheem1798** • `finance` `browser` `automation`
通过浏览器自动化登录 TradingView，对图表截图，并按需执行技术分析。无需 API——只需浏览器控制。
通过浏览器自动化登录 TradingView，截取图表，并按需执行技术分析。无需 API——只需浏览器控制。
</Card>
<Card title="Slack 自动支持" icon="slack">
**@henrymascot** • `slack` `automation` `support`
监控公司 Slack 渠道，提供有帮助的回复，并将通知转发到 Telegram。在无人要求的情况下，自主修复了一个已部署应用中的生产环境 bug。
监控公司 Slack 渠道，提供有帮助的回复，并将通知转发到 Telegram。甚至在没有被要求的情况下，自主修复了一个已部署应用中的生产 bug。
</Card>
</CardGroup>
<h2 id="knowledge-memory">知识与记忆</h2>
<a id="knowledge-memory"></a>
## 知识与记忆
<p className="showcase-section-intro">
用于索引、搜索、记忆并基于个人或团队知识进行推理的系统。
用于索引、搜索、记忆以及基于个人或团队知识进行推理的系统。
</p>
<CardGroup cols={2}>
@ -338,49 +340,53 @@ OpenClaw 连接到 Jira，然后实时生成了一个新的 Skill（当时它甚
<img src="/assets/showcase/xuezh-pronunciation.jpeg" alt="xuezh 发音反馈" />
</Card>
<Card title="WhatsApp 记忆库" icon="vault">
<Card title="WhatsApp 记忆金库" icon="vault">
**社区** • `memory` `transcription` `indexing`
导入完整的 WhatsApp 导出内容，转录 1000 多条语音便笺，与 git 日志交叉核对，并输出带链接的 markdown 报告。
导入完整的 WhatsApp 导出内容，转录 1000+ 条语音便笺，与 git 日志交叉核对，并输出带链接的 markdown 报告。
</Card>
<Card title="Karakeep 语义搜索" icon="magnifying-glass" href="https://github.com/jamesbrooksco/karakeep-semantic-search">
**@jamesbrooksco** • `search` `vector` `bookmarks`
使用 Qdrant + OpenAI/Ollama embeddings 为 Karakeep 书签添加向量搜索。
使用 Qdrant + OpenAI/Ollama embeddings，为 Karakeep 书签添加向量搜索。
</Card>
<Card title="头脑特工队 2 式记忆" icon="brain">
<Card title="头脑特工队 2 记忆系统" icon="brain">
**社区** • `memory` `beliefs` `self-model`
独立的记忆管理器，可将会话文件转化为记忆 → 信念 → 持续演化的自我模型。
一个独立的记忆管理器，将会话文件转化为记忆 → 信念 → 持续演化的自我模型。
</Card>
</CardGroup>
<h2 id="voice-phone">语音与电话</h2>
<a id="voice-phone"></a>
## 语音与电话
<p className="showcase-section-intro">
以语音为先的入口、电话桥接，以及以转录为核心的工作流。
以语音为优先的入口、电话桥接和重度依赖转录的工作流。
</p>
<CardGroup cols={2}>
<Card title="Clawdia 电话桥接" icon="phone" href="https://github.com/alejandroOPI/clawdia-bridge">
<Card title="Clawdia 电话桥" icon="phone" href="https://github.com/alejandroOPI/clawdia-bridge">
**@alejandroOPI** • `voice` `vapi` `bridge`
Vapi 语音助手 ↔ OpenClaw HTTP 桥接。与你的智能体进行近实时电话通话。
Vapi 语音助手 ↔ OpenClaw HTTP 桥。与你的智能体进行接近实时的电话通话。
</Card>
<Card title="OpenRouter 转录" icon="microphone" href="https://clawhub.ai/obviyus/openrouter-transcribe">
**@obviyus** • `transcription` `multilingual` `skill`
通过 OpenRouter（Gemini 等）进行多语言音频转录。可在 ClawHub 上使用。
通过 OpenRouter（Gemini 等）进行多语言音频转录。可在 ClawHub 上获取。
</Card>
</CardGroup>
<h2 id="infrastructure-deployment">基础设施与部署</h2>
<a id="infrastructure-deployment"></a>
## 基础设施与部署
<p className="showcase-section-intro">
让 OpenClaw 更易于运行和扩展的打包、部署和集成。
@ -391,19 +397,19 @@ OpenClaw 连接到 Jira，然后实时生成了一个新的 Skill（当时它甚
<Card title="Home Assistant 附加组件" icon="home" href="https://github.com/ngutman/openclaw-ha-addon">
**@ngutman** • `homeassistant` `docker` `raspberry-pi`
运行在 Home Assistant OS 上的 OpenClaw gateway，支持 SSH 隧道和持久化状态。
运行在 Home Assistant OS 上的 OpenClaw Gateway 网关，支持 SSH 隧道和持久化状态。
</Card>
<Card title="Home Assistant Skill" icon="toggle-on" href="https://clawhub.ai/skills/homeassistant">
**ClawHub** • `homeassistant` `skill` `automation`
通过自然语言控制和自动化 Home Assistant 设备。
通过自然语言控制并自动化 Home Assistant 设备。
</Card>
<Card title="Nix 打包" icon="snowflake" href="https://github.com/openclaw/nix-openclaw">
**@openclaw** • `nix` `packaging` `deployment`
开箱即用的 nix 化 OpenClaw 配置，用于可复现部署。
开箱即用的 Nix 化 OpenClaw 配置，用于可复现部署。
</Card>
<Card title="CalDAV 日历" icon="calendar" href="https://clawhub.ai/skills/caldav-calendar">
@ -414,10 +420,12 @@ OpenClaw 连接到 Jira，然后实时生成了一个新的 Skill（当时它甚
</CardGroup>
<h2 id="home-hardware">家庭与硬件</h2>
<a id="home-hardware"></a>
## 家庭与硬件
<p className="showcase-section-intro">
OpenClaw 的现实世界一面：家庭、传感器、摄像头、扫地机器人以及其他设备。
OpenClaw 的物理世界一面：家庭、传感器、摄像头、扫地机器人和其他设备。
</p>
<CardGroup cols={2}>
@ -425,7 +433,7 @@ OpenClaw 连接到 Jira，然后实时生成了一个新的 Skill（当时它甚
<Card title="GoHome 自动化" icon="house-signal" href="https://github.com/joshp123/gohome">
**@joshp123** • `home` `nix` `grafana`
以 Nix 为原生基础的家庭自动化，由 OpenClaw 作为交互界面，外加美观的 Grafana 仪表板。
以 Nix 为原生的家庭自动化，使用 OpenClaw 作为交互界面，并配有精美的 Grafana 仪表板。
<img src="/assets/showcase/gohome-grafana.png" alt="GoHome Grafana 仪表板" />
</Card>
@ -433,17 +441,17 @@ OpenClaw 连接到 Jira，然后实时生成了一个新的 Skill（当时它甚
<Card title="Roborock 扫地机器人" icon="robot" href="https://github.com/joshp123/gohome/tree/main/plugins/roborock">
**@joshp123** • `vacuum` `iot` `plugin`
通过自然对话控制你的 Roborock 扫地机器人。
通过自然对话控制你的 Roborock 机器人吸尘器。
<img src="/assets/showcase/roborock-screenshot.jpg" alt="Roborock 状态" />
</Card>
</CardGroup>
<h2 id="community-projects">社区项目</h2>
## 社区项目
<p className="showcase-section-intro">
从单一工作流成长为更广泛产品或生态系统的项目。
那些已经超越单一工作流，发展为更广泛产品或生态系统的项目。
</p>
<CardGroup cols={2}>
@ -451,29 +459,29 @@ OpenClaw 连接到 Jira，然后实时生成了一个新的 Skill（当时它甚
<Card title="StarSwap Marketplace" icon="star" href="https://star-swap.com/">
**社区** • `marketplace` `astronomy` `webapp`
完整的天文设备交易市场。基于 OpenClaw 生态系统构建，或围绕其构建。
完整的天文设备交易市场。基于/围绕 OpenClaw 生态系统构建。
</Card>
</CardGroup>
---
<h2 id="submit-your-project">提交你的项目</h2>
## 提交你的项目
<p className="showcase-section-intro">
如果你正在用 OpenClaw 构建一些有趣的东西，请发给我们。高质量截图和具体成果会很有帮助。
如果你正在用 OpenClaw 构建有趣的东西，欢迎发给我们。清晰的截图和具体成果会更有帮助。
</p>
有内容想分享吗？我们很乐意推荐展示！
有内容想分享？我们很乐意展示它！
<Steps>
<Step title="分享出来">
在 [Discord 的 #self-promotion](https://discord.gg/clawd) 发帖，或在 [X 上发帖并 @openclaw](https://x.com/openclaw)
<Step title="分享它">
在 [Discord 的 #self-promotion](https://discord.gg/clawd) 中发帖，或 [在 X 上 @openclaw](https://x.com/openclaw)
</Step>
<Step title="附上细节">
告诉我们它能做什么，附上仓库/演示链接，如果有截图也请一起分享
告诉我们它的功能，附上仓库/演示链接，如果有截图也请一并分享
</Step>
<Step title="获得展示推荐">
我们会将亮眼项目添加到此页面
<Step title="获得展示">
我们会将优秀项目添加到此页面
</Step>
</Steps>

183
docs/zh-CN/tools/index.md
View File

@ -2,54 +2,55 @@
read_when:
- 你想了解 OpenClaw 提供了哪些工具
- 你需要配置、允许或拒绝工具
- 你正在内置工具、Skills 和插件之间做决定
- 你正在决定使用内置工具、Skills 还是插件
summary: OpenClaw 工具和插件概览：智能体能做什么，以及如何扩展它
title: 工具和插件
x-i18n:
generated_at: "2026-04-22T23:49:30Z"
generated_at: "2026-04-23T06:43:48Z"
model: gpt-5.4
provider: openai
source_hash: 1c32414dfa99969372e9b0c846305a1af1ffb18a282e6dfc8a6adabe3fab145a
source_hash: ef0975c567b0bca0e991a0445d3db4a00fe2e2cf91b9e6bea5686825deac91a0
source_path: tools/index.md
workflow: 15
---
# 工具和插件
智能体除了生成文本之外所做的一切，都是通过**工具**完成的。
智能体除生成文本之外所做的一切，都通过**工具**完成。
工具是智能体读取文件、运行命令、浏览网页、发送消息以及与设备交互的方式。
## 工具、Skills 和插件
OpenClaw 有三层协同工作：
OpenClaw 有三个协同工作的层级：
<Steps>
<Step title="工具是智能体调用的内容">
工具是智能体可以调用的类型化函数（例如 `exec`、`browser`、
`web_search`、`message`）。OpenClaw 内置了一组**内置工具**，并且
插件可以注册额外的工具。
<Step title="工具是智能体实际调用的内容">
工具是智能体可调用的类型化函数（例如 `exec`、`browser`、
`web_search`、`message`）。OpenClaw 内置了一组**内置工具**，插件也可以注册额外工具。
对智能体来说，工具就是发送到模型 API 的结构化函数定义。
对智能体来说，工具表现为发送到模型 API 的结构化函数定义。
</Step>
<Step title="Skills 教会智能体何时以及如何使用">
Skill 是注入到系统提示词中的 Markdown 文件（`SKILL.md`）。
Skills 为智能体提供上下文、约束，以及如何高效使用工具的分步指导。
Skills 可以位于你的工作区、共享文件夹中，或者随插件一起提供。
<Step title="Skills 告诉智能体何时以及如何使用">
Skill 是注入到系统提示词中的 markdown 文件（`SKILL.md`）。
Skills 为智能体提供上下文、约束以及逐步指导，以便更有效地
使用工具。Skills 可以存在于你的工作区、共享文件夹中，
也可以随插件一起提供。
[Skills 参考](/zh-CN/tools/skills) | [创建 Skills](/zh-CN/tools/creating-skills)
</Step>
<Step title="插件将一切打包在一起">
插件是可以注册任意能力组合的软件包，包括：
渠道、模型提供商、工具、Skills、语音、实时转写、
插件是可以注册任意能力组合的包：
渠道、模型提供商、工具、Skills、语音、实时转录、
实时语音、媒体理解、图像生成、视频生成、
网页抓取、网页搜索等。部分插件属于**核心**插件（随
OpenClaw 一起提供），其余则是**外部**插件（由社区发布到 npm）。
web 获取、web 搜索等。有些插件是**核心**
（随 OpenClaw 一起提供），另一些则是**外部**
（由社区发布到 npm）。
[安装并配置插件](/zh-CN/tools/plugin) | [构建你自己的插件](/zh-CN/plugins/building-plugins)
[安装和配置插件](/zh-CN/tools/plugin) | [构建你自己的插件](/zh-CN/plugins/building-plugins)
</Step>
</Steps>
@ -58,68 +59,68 @@ OpenClaw 有三层协同工作：
这些工具随 OpenClaw 一起提供，无需安装任何插件即可使用：
| 工具 | 作用 | 页面 |
| ------------------------------------------ | ------------------------------------------------------------- | ------------------------------------------- |
| `exec` / `process` | 运行 shell 命令，管理后台进程 | [Exec](/zh-CN/tools/exec) |
| `code_execution` | 运行沙箱隔离的远程 Python 分析 | [Code Execution](/zh-CN/tools/code-execution) |
| `browser` | 控制 Chromium 浏览器（导航、点击、截图） | [Browser](/zh-CN/tools/browser) |
| `web_search` / `x_search` / `web_fetch` | 搜索网页、搜索 X 帖子、抓取页面内容 | [Web](/zh-CN/tools/web) |
| `read` / `write` / `edit` | 在工作区中进行文件 I/O | |
| `apply_patch` | 多片段文件补丁 | [Apply Patch](/zh-CN/tools/apply-patch) |
| `message` | 跨所有渠道发送消息 | [Agent Send](/zh-CN/tools/agent-send) |
| `canvas` | 驱动节点 Canvas（展示、求值、快照） | |
| `nodes` | 发现并定位已配对设备 | |
| `cron` / `gateway` | 管理计划任务；检查、修补、重启或更新 Gateway 网关 | |
| `image` / `image_generate` | 分析或生成图像 | [Image Generation](/zh-CN/tools/image-generation) |
| `music_generate` | 生成音乐轨道 | [Music Generation](/zh-CN/tools/music-generation) |
| `video_generate` | 生成视频 | [Video Generation](/zh-CN/tools/video-generation) |
| `tts` | 一次性文本转语音转换 | [TTS](/zh-CN/tools/tts) |
| `sessions_*` / `subagents` / `agents_list` | 会话管理、状态查看和子智能体编排 | [Sub-agents](/zh-CN/tools/subagents) |
| `session_status` | 轻量级 `/status` 风格回读和会话模型覆盖 | [Session Tools](/zh-CN/concepts/session-tool) |
| Tool | 功能 | 页面 |
| ------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------ |
| `exec` / `process` | 运行 shell 命令、管理后台进程 | [Exec](/zh-CN/tools/exec), [Exec Approvals](/zh-CN/tools/exec-approvals) |
| `code_execution` | 运行沙箱隔离的远程 Python 分析 | [Code Execution](/zh-CN/tools/code-execution) |
| `browser` | 控制 Chromium 浏览器（导航、点击、截图） | [Browser](/zh-CN/tools/browser) |
| `web_search` / `x_search` / `web_fetch` | 搜索网页、搜索 X 帖子、获取页面内容 | [Web](/zh-CN/tools/web), [Web Fetch](/zh-CN/tools/web-fetch) |
| `read` / `write` / `edit` | 在工作区中进行文件 I/O | |
| `apply_patch` | 多段文件补丁 | [Apply Patch](/zh-CN/tools/apply-patch) |
| `message` | 跨所有渠道发送消息 | [Agent Send](/zh-CN/tools/agent-send) |
| `canvas` | 驱动节点 Canvas（present、eval、snapshot） | |
| `nodes` | 发现并定向到已配对设备 | |
| `cron` / `gateway` | 管理定时任务；检查、修补、重启或更新 Gateway 网关 | |
| `image` / `image_generate` | 分析或生成图像 | [Image Generation](/zh-CN/tools/image-generation) |
| `music_generate` | 生成音乐轨道 | [Music Generation](/zh-CN/tools/music-generation) |
| `video_generate` | 生成视频 | [Video Generation](/zh-CN/tools/video-generation) |
| `tts` | 一次性文本转语音转换 | [TTS](/zh-CN/tools/tts) |
| `sessions_*` / `subagents` / `agents_list` | 会话管理、状态和子智能体编排 | [Sub-agents](/zh-CN/tools/subagents) |
| `session_status` | 轻量级 `/status` 风格回读和会话模型覆盖 | [Session Tools](/zh-CN/concepts/session-tool) |
对于图像工作，使用 `image` 进行分析，使用 `image_generate` 进行生成或编辑。如果你要使用 `openai/*`、`google/*`、`fal/*` 或其他非默认图像提供商，请先配置该提供商的凭证 / API 密钥。
对于图像任务，使用 `image` 进行分析，使用 `image_generate` 进行生成或编辑。如果你要使用 `openai/*`、`google/*`、`fal/*` 或其他非默认图像提供商，请先配置该提供商的认证 / API key。
对于音乐工作，使用 `music_generate`。如果你要使用 `google/*`、`minimax/*` 或其他非默认音乐提供商，请先配置该提供商的凭证 / API 密钥。
对于音乐任务，使用 `music_generate`。如果你要使用 `google/*`、`minimax/*` 或其他非默认音乐提供商，请先配置该提供商的认证 / API key。
对于视频工作，使用 `video_generate`。如果你要使用 `qwen/*` 或其他非默认视频提供商，请先配置该提供商的凭证 / API 密钥。
对于视频任务，使用 `video_generate`。如果你要使用 `qwen/*` 或其他非默认视频提供商，请先配置该提供商的认证 / API key。
对于由工作流驱动的音频生成，在诸如
ComfyUI 这类插件注册该工具时，请使用 `music_generate`。这与 `tts` 不同，后者用于文本转语音。
对于基于工作流的音频生成，当某个插件（例如
ComfyUI）注册了 `music_generate` 时，请使用它。这与 `tts`
不同，后者是文本转语音。
`session_status` 是 sessions 组中的轻量级状态 / 回读工具。
它用于回答当前会话中类似 `/status` 的问题，并且可以
选择性设置按会话生效的模型覆盖；`model=default` 会清除此
覆盖。与 `/status` 一样，它可以从最新的转录使用记录中回填稀疏的令牌 / 缓存计数器以及当前运行时模型标签。
`session_status` 是 sessions 分组中的轻量级状态 / 回读工具。
它用于回答有关当前会话的 `/status` 风格问题，并且可以
选择设置按会话生效的模型覆盖；`model=default` 会清除此
覆盖。与 `/status` 一样，它可以从最新转录使用记录中回填稀疏的 token / 缓存计数，以及当前运行时模型标签。
`gateway` 是仅所有者可用、用于 Gateway 网关操作的运行时工具：
`gateway` 是仅限所有者使用的 Gateway 网关运行时工具，用于执行 Gateway 网关操作：
- `config.schema.lookup`：在编辑前查询某一路径范围内的配置子树
- `config.schema.lookup`：在编辑前查看某个按路径限定的配置子树
- `config.get`：获取当前配置快照 + 哈希
- `config.patch`：执行带重启的局部配置更新
- `config.apply`：仅用于完整配置替换
- `config.apply`：仅用于完整替换整个配置
- `update.run`：显式执行自更新 + 重启
对于局部更改，优先使用 `config.schema.lookup`，然后使用 `config.patch`。只有在你有意替换整个配置时，才使用
`config.apply`。
该工具还会拒绝更改 `tools.exec.ask` 或 `tools.exec.security`；
旧版 `tools.bash.*` 别名会规范化到相同的受保护 exec 路径。
对于部分变更，优先使用 `config.schema.lookup`，然后使用 `config.patch`。仅当你明确要替换整个配置时，才使用 `config.apply`。
该工具还拒绝修改 `tools.exec.ask` 或 `tools.exec.security`；
旧版 `tools.bash.*` 别名会被标准化为同样受保护的 exec 路径。
### 插件提供的工具
插件可以注册额外工具。一些示例：
插件可以注册额外工具。示例包括：
- [Diffs](/zh-CN/tools/diffs) — 差异查看器和渲染器
- [LLM Task](/zh-CN/tools/llm-task) — 仅 JSON 的 LLM 步骤，用于结构化输出
- [Diffs](/zh-CN/tools/diffs) — diff 查看器和渲染器
- [LLM Task](/zh-CN/tools/llm-task) — 仅输出 JSON 的 LLM 步骤，用于结构化输出
- [Lobster](/zh-CN/tools/lobster) — 带可恢复审批的类型化工作流运行时
- [Music Generation](/zh-CN/tools/music-generation) — 带工作流支持提供商的共享 `music_generate` 工具
- [OpenProse](/zh-CN/prose) — 以 Markdown 为先的工作流编排
- [Tokenjuice](/zh-CN/tools/tokenjuice) — 紧凑的高噪声 `exec` 和 `bash` 工具结果
- [Music Generation](/zh-CN/tools/music-generation) — 由工作流支持的提供商共享的 `music_generate` 工具
- [OpenProse](/zh-CN/prose) — markdown 优先的工作流编排
- [Tokenjuice](/zh-CN/tools/tokenjuice) — 紧凑显示嘈杂 `exec` 和 `bash` 工具结果
## 工具配置
### 允许列表和拒绝列表
### 允许和拒绝列表
通过配置中的 `tools.allow` / `tools.deny` 控制智能体可以调用哪些工具。拒绝规则始终优先于允许规则。
通过配置中的 `tools.allow` / `tools.deny` 控制智能体可调用哪些工具。拒绝始终优先于允许。
```json5
{
@ -130,54 +131,54 @@ ComfyUI 这类插件注册该工具时，请使用 `music_generate`。这与 `tt
}
```
### 工具配置档
### 工具配置档案
`tools.profile` 会在应用 `allow` / `deny` 之前设置基础允许列表。
`tools.profile` 会在应用 `allow` / `deny` 之前设置基础 allowlist。
按智能体覆盖：`agents.list[].tools.profile`。
| 配置档 | 包含内容 |
| Profile | 包含内容 |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `full` | 无限制（等同于未设置） |
| `coding` | `group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`music_generate`、`video_generate` |
| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` |
| `minimal` | 仅 `session_status` |
| `full` | 不限制（与未设置相同） |
| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `music_generate`, `video_generate` |
| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
| `minimal` | 仅 `session_status` |
`coding` 和 `messaging` 配置档还允许插件键 `bundle-mcp` 下已配置的 bundle MCP 工具。
当你希望某个配置档保留其常规内置工具，但隐藏所有已配置的 MCP 工具时，添加 `tools.deny: ["bundle-mcp"]`。
`minimal` 配置档不包含 bundle MCP 工具。
`coding` 和 `messaging` 配置档案还会允许在插件键 `bundle-mcp` 下已配置的 bundle MCP 工具。
当你希望某个配置档案保留其常规内置工具，但隐藏所有已配置 MCP 工具时，请添加 `tools.deny: ["bundle-mcp"]`。
`minimal` 配置档案不包含 bundle MCP 工具。
### 工具组
### 工具分组
在允许 / 拒绝列表中使用 `group:*` 简写：
在 allow / deny 列表中使用 `group:*` 简写：
| 组 | 工具 |
| Group | 工具 |
| ------------------ | --------------------------------------------------------------------------------------------------------- |
| `group:runtime` | exec、process、code_execution（`bash` 可作为 `exec` 的别名使用） |
| `group:fs` | read、write、edit、apply_patch |
| `group:runtime` | exec、process、code_execution（`bash` 可作为 `exec` 的别名） |
| `group:fs` | read、write、edit、apply_patch |
| `group:sessions` | sessions_list、sessions_history、sessions_send、sessions_spawn、sessions_yield、subagents、session_status |
| `group:memory` | memory_search、memory_get |
| `group:web` | web_search、x_search、web_fetch |
| `group:ui` | browser、canvas |
| `group:automation` | cron、gateway |
| `group:messaging` | message |
| `group:nodes` | nodes |
| `group:agents` | agents_list |
| `group:media` | image、image_generate、music_generate、video_generate、tts |
| `group:openclaw` | 所有 OpenClaw 内置工具（不包括插件工具） |
| `group:memory` | memory_search、memory_get |
| `group:web` | web_search、x_search、web_fetch |
| `group:ui` | browser、canvas |
| `group:automation` | cron、gateway |
| `group:messaging` | message |
| `group:nodes` | nodes |
| `group:agents` | agents_list |
| `group:media` | image、image_generate、music_generate、video_generate、tts |
| `group:openclaw` | 所有内置 OpenClaw 工具（不包括插件工具） |
`sessions_history` 返回受限且经过安全过滤的回忆视图。它会移除
`sessions_history` 返回一个有边界、经过安全过滤的回溯视图。它会去除
thinking 标签、`<relevant-memories>` 脚手架、纯文本工具调用 XML
负载（包括 `<tool_call>...</tool_call>`、
载荷（包括 `<tool_call>...</tool_call>`、
`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、
`<function_calls>...</function_calls>` 以及被截断的工具调用块）、
降级后的工具调用脚手架、泄露的 ASCII / 全角模型控制
令牌，以及助手文本中格式错误的 MiniMax 工具调用 XML，然后再应用
脱敏 / 截断，并在必要时使用超大行占位符，而不是把它
当作原始转录转储返回。
token，以及助手文本中格式错误的 MiniMax 工具调用 XML，然后再应用
脱敏 / 截断，并在必要时使用超大行占位符，而不是充当
原始转录转储。
### 提供商特定限制
使用 `tools.byProvider` 为特定提供商限制工具，而无需
使用 `tools.byProvider` 可为特定提供商限制工具，而无需
更改全局默认值：
```json5

219
docs/zh-CN/tools/plugin.md
View File

@ -1,23 +1,27 @@
---
read_when:
- 安装或配置插件
- 了解插件发现和加载规则
- 了解插件发现与加载规则
- 使用与 Codex/Claude 兼容的插件包
sidebarTitle: Install and Configure
summary: 安装、配置和管理 OpenClaw 插件
title: 插件
title: Plugins
x-i18n:
generated_at: "2026-04-23T05:40:51Z"
generated_at: "2026-04-23T06:43:53Z"
model: gpt-5.4
provider: openai
source_hash: fb81789de548aed0cd0404e8c42a2d9ce00d0e9163f944e07237b164d829ac40
source_hash: dc944b53654552ca5cf6132c6ef16c71745a7bffc249daccaee40c513e04209c
source_path: tools/plugin.md
workflow: 15
---
# 插件
# Plugins
插件通过提供新能力来扩展 OpenClaw：渠道、模型提供商、工具、Skills、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。有些插件是 **核心** 插件（随 OpenClaw 一起提供），另一些是 **外部** 插件（由社区发布到 npm）。
Plugins 为 OpenClaw 扩展新能力：渠道、模型提供商、
工具、Skills、语音、实时转录、实时语音、
媒体理解、图像生成、视频生成、网页抓取、网页
搜索等。有些插件是**核心**插件（随 OpenClaw 一起发布），另一些
是**外部**插件（由社区发布到 npm）。
## 快速开始
@ -30,10 +34,10 @@ x-i18n:
<Step title="安装插件">
```bash
# 来自 npm
# 从 npm
openclaw plugins install @openclaw/voice-call
# 来自本地目录或归档文件
# 从本地目录或归档文件
openclaw plugins install ./my-plugin
openclaw plugins install ./my-plugin.tgz
```
@ -45,12 +49,12 @@ x-i18n:
openclaw gateway restart
```
然后在你的配置文件中，通过 `plugins.entries.\<id\>.config` 进行配置。
然后在你的配置文件中通过 `plugins.entries.\<id\>.config` 进行配置。
</Step>
</Steps>
如果你更喜欢在聊天中直接控制，请启用 `commands.plugins: true` 并使用：
如果你更喜欢原生聊天控制，请启用 `commands.plugins: true` 并使用：
```text
/plugin install clawhub:@openclaw/voice-call
@ -58,11 +62,20 @@ x-i18n:
/plugin enable voice-call
```
安装路径使用与 CLI 相同的解析器：本地路径 / 归档文件、显式 `clawhub:<pkg>`，或裸包规范（优先 ClawHub，然后回退到 npm）。
安装路径使用与 CLI 相同的解析器：本地路径/归档、显式
`clawhub:<pkg>`，或裸包规范（优先 ClawHub，然后回退到 npm）。
如果配置无效，安装通常会以安全失败方式结束，并提示你运行 `openclaw doctor --fix`。唯一的恢复例外，是针对选择启用 `openclaw.install.allowInvalidConfigRecovery` 的插件，提供了一条受限的内置插件重新安装路径。
如果配置无效，安装通常会默认失败关闭，并提示你运行
`openclaw doctor --fix`。唯一的恢复例外是一个较窄的内置插件
重装路径，适用于选择加入
`openclaw.install.allowInvalidConfigRecovery` 的插件。
打包分发的 OpenClaw 安装不会预先安装每个内置插件的全部运行时依赖树。当某个 OpenClaw 自带的内置插件因插件配置、旧版渠道配置或默认启用的清单而处于活动状态时，启动修复只会在导入该插件前修复它声明的运行时依赖。外部插件和自定义加载路径仍然必须通过 `openclaw plugins install` 安装。
打包版 OpenClaw 安装不会急切安装每个内置插件的
运行时依赖树。当某个 OpenClaw 自有的内置插件因
插件配置、旧版渠道配置或默认启用的 manifest 而处于激活状态时，
启动修复只会在导入该插件前修复它声明的运行时依赖。
外部插件和自定义加载路径仍然必须通过
`openclaw plugins install` 安装。
## 插件类型
@ -71,11 +84,12 @@ OpenClaw 可识别两种插件格式：
| 格式 | 工作方式 | 示例 |
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
| **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 |
| **Bundle** | 兼容 Codex/Claude/Cursor 的布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
| **Bundle** | 与 Codex/Claude/Cursor 兼容的布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
两种格式都会显示在 `openclaw plugins list` 中。有关 Bundle 的详细信息，请参阅 [插件 Bundle](/zh-CN/plugins/bundles)。
两者都会显示在 `openclaw plugins list` 中。有关 Bundle 的详细信息，请参阅 [Plugin Bundles](/zh-CN/plugins/bundles)。
如果你要编写原生插件，请从 [构建插件](/zh-CN/plugins/building-plugins) 和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。
如果你在编写原生插件，请从 [Building Plugins](/zh-CN/plugins/building-plugins)
和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。
## 官方插件
@ -83,40 +97,40 @@ OpenClaw 可识别两种插件格式：
| 插件 | 包 | 文档 |
| --------------- | ---------------------- | ------------------------------------ |
| Matrix | `@openclaw/matrix` | [Matrix](/zh-CN/channels/matrix) |
| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/zh-CN/channels/msteams) |
| Nostr | `@openclaw/nostr` | [Nostr](/zh-CN/channels/nostr) |
| Voice Call | `@openclaw/voice-call` | [Voice Call](/zh-CN/plugins/voice-call) |
| Zalo | `@openclaw/zalo` | [Zalo](/zh-CN/channels/zalo) |
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/zh-CN/plugins/zalouser) |
| Matrix | `@openclaw/matrix` | [Matrix](/zh-CN/channels/matrix) |
| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/zh-CN/channels/msteams) |
| Nostr | `@openclaw/nostr` | [Nostr](/zh-CN/channels/nostr) |
| Voice Call | `@openclaw/voice-call` | [Voice Call](/zh-CN/plugins/voice-call) |
| Zalo | `@openclaw/zalo` | [Zalo](/zh-CN/channels/zalo) |
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/zh-CN/plugins/zalouser) |
### 核心（随 OpenClaw 一起提供）
### 核心（随 OpenClaw 一起发布）
<AccordionGroup>
<Accordion title="模型提供商（默认启用）">
`anthropic`、`byteplus`、`cloudflare-ai-gateway`、`github-copilot`、`google`、
`huggingface`、`kilocode`、`kimi-coding`、`minimax`、`mistral`、`qwen`、
`moonshot`、`nvidia`、`openai`、`opencode`、`opencode-go`、`openrouter`、
`qianfan`、`synthetic`、`together`、`venice`、
`vercel-ai-gateway`、`volcengine`、`xiaomi`、`zai`
`anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`,
`huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`,
`moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`,
`qianfan`, `synthetic`, `together`, `venice`,
`vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai`
</Accordion>
<Accordion title="Memory 插件">
- `memory-core` — 内置内存搜索（默认通过 `plugins.slots.memory` 使用）
- `memory-lancedb` — 按需安装的长期记忆，带自动回忆 / 捕获功能（设置 `plugins.slots.memory = "memory-lancedb"`）
- `memory-core` — 内置的 Memory 搜索（默认通过 `plugins.slots.memory`）
- `memory-lancedb` — 按需安装的长期 Memory，带自动召回/捕获（设置 `plugins.slots.memory = "memory-lancedb"`）
</Accordion>
<Accordion title="语音提供商（默认启用）">
`elevenlabs`、`microsoft`
`elevenlabs`, `microsoft`
</Accordion>
<Accordion title="其他">
- `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、浏览器运行时以及默认浏览器控制服务的内置浏览器插件（默认启用；替换前请先禁用）
- `copilot-proxy` — VS Code Copilot Proxy 桥接（默认禁用）
- `browser` — 用于 browser 工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、browser 运行时以及默认 browser 控制服务的内置 browser 插件（默认启用；替换前请先禁用）
- `copilot-proxy` — VS Code Copilot Proxy bridge（默认禁用）
</Accordion>
</AccordionGroup>
在找第三方插件？请参阅 [社区插件](/zh-CN/plugins/community)。
想找第三方插件？请参阅 [Community Plugins](/zh-CN/plugins/community)。
## 配置
@ -126,7 +140,7 @@ OpenClaw 可识别两种插件格式：
enabled: true,
allow: ["voice-call"],
deny: ["untrusted-plugin"],
load: { paths: ["~/Projects/oss/voice-call-extension"] },
load: { paths: ["~/Projects/oss/voice-call-plugin"] },
entries: {
"voice-call": { enabled: true, config: { provider: "twilio" } },
},
@ -134,20 +148,22 @@ OpenClaw 可识别两种插件格式：
}
```
| 字段 | 描述 |
| 字段 | 说明 |
| ---------------- | --------------------------------------------------------- |
| `enabled` | 主开关（默认：`true`） |
| `allow` | 插件允许列表（可选） |
| `deny` | 插件拒绝列表（可选；拒绝优先） |
| `load.paths` | 额外的插件文件 / 目录 |
| `slots` | 独占槽位选择器（例如 `memory`、`contextEngine`） |
| `entries.\<id\>` | 每个插件的开关 + 配置 |
| `load.paths` | 额外的插件文件/目录 |
| `slots` | 排他性 slot 选择器（例如 `memory`、`contextEngine`） |
| `entries.\<id\>` | 按插件的开关 + 配置 |
配置更改 **需要重启 Gateway 网关**。如果 Gateway 网关正在以启用配置监视和进程内重启的方式运行（默认的 `openclaw gateway` 路径），那么在配置写入完成后，通常会自动在稍后片刻执行重启。
配置变更**需要重启 Gateway 网关**。如果 Gateway 网关以配置
监听 + 进程内重启方式运行（默认的 `openclaw gateway` 路径），那么
配置写入落地后通常会在短时间内自动执行该重启。
<Accordion title="插件状态：已禁用、缺失、无效">
- **已禁用**：插件存在，但被启用规则关闭。配置会被保留。
- **缺失**：配置引用了某个插件 ID，但在发现过程中未找到。
<Accordion title="插件状态：已禁用 vs 缺失 vs 无效">
- **已禁用**：插件存在，但启用规则将其关闭。配置会被保留。
- **缺失**：配置引用了某个插件 id，但在发现阶段未找到。
- **无效**：插件存在，但其配置与声明的 schema 不匹配。
</Accordion>
@ -169,7 +185,7 @@ OpenClaw 按以下顺序扫描插件（先匹配者胜出）：
</Step>
<Step title="内置插件">
随 OpenClaw 一起提供。许多默认启用（模型提供商、语音等）。
随 OpenClaw 一起发布。许多插件默认启用（模型提供商、语音）。
其他插件则需要显式启用。
</Step>
</Steps>
@ -177,42 +193,42 @@ OpenClaw 按以下顺序扫描插件（先匹配者胜出）：
### 启用规则
- `plugins.enabled: false` 会禁用所有插件
- `plugins.deny` 总是优先于 allow
- `plugins.deny` 始终优先于 allow
- `plugins.entries.\<id\>.enabled: false` 会禁用该插件
- 来源于工作区的插件 **默认禁用**（必须显式启用）
- 内置插件遵循内建的默认启用集合，除非被覆盖
- 独占槽位可以为该槽位强制启用所选插件
- 来自工作区的插件**默认禁用**（必须显式启用）
- 内置插件遵循内建的默认开启集合，除非被覆盖
- 排他性 slot 可以强制启用该 slot 所选中的插件
## 插件槽位（独占类别）
## 插件 slots（排他类别）
某些类别是独占的（同一时间只能有一个处于活动状态）：
某些类别是排他的（同一时间只能有一个激活）：
```json5
{
plugins: {
slots: {
memory: "memory-core", // 或 "none" 表示禁用
memory: "memory-core", // 或 "none" 以禁用
contextEngine: "legacy", // 或某个插件 id
},
},
}
```
| 槽位 | 控制内容 | 默认值 |
| Slot | 控制内容 | 默认值 |
| --------------- | --------------------- | ------------------- |
| `memory` | 活动的内存插件 | `memory-core` |
| `contextEngine` | 活动的上下文引擎 | `legacy`（内建） |
| `memory` | 当前激活的 Memory 插件 | `memory-core` |
| `contextEngine` | 当前激活的上下文引擎 | `legacy`（内建） |
## CLI 参考
```bash
openclaw plugins list # 简明清单
openclaw plugins list # 紧凑清单
openclaw plugins list --enabled # 仅显示已加载插件
openclaw plugins list --verbose # 每个插件的详细信息行
openclaw plugins list --verbose # 每个插件的详细行
openclaw plugins list --json # 机器可读清单
openclaw plugins inspect <id> # 深度详情
openclaw plugins inspect <id> --json # 机器可读
openclaw plugins inspect --all # 整体范围表格
openclaw plugins inspect --all # 全量表格
openclaw plugins info <id> # inspect 别名
openclaw plugins doctor # 诊断
@ -228,7 +244,7 @@ openclaw plugins install <spec> --dangerously-force-unsafe-install
openclaw plugins update <id-or-npm-spec> # 更新单个插件
openclaw plugins update <id-or-npm-spec> --dangerously-force-unsafe-install
openclaw plugins update --all # 更新全部
openclaw plugins uninstall <id> # 删除配置 / 安装记录
openclaw plugins uninstall <id> # 移除配置/安装记录
openclaw plugins uninstall <id> --keep-files
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
@ -237,29 +253,58 @@ openclaw plugins enable <id>
openclaw plugins disable <id>
```
内置插件随 OpenClaw 一起提供。许多插件默认启用（例如内置模型提供商、内置语音提供商以及内置浏览器插件）。其他内置插件仍然需要执行 `openclaw plugins enable <id>`。
内置插件随 OpenClaw 一起发布。许多插件默认启用（例如
内置模型提供商、内置语音提供商，以及内置 browser
插件）。其他内置插件仍需要 `openclaw plugins enable <id>`。
`--force` 会原地覆盖现有已安装的插件或 hook 包。对于已跟踪的 npm 插件的常规升级，请使用 `openclaw plugins update <id-or-npm-spec>`。它不支持与 `--link` 一起使用，因为 `--link` 会复用源路径，而不是复制到受管理的安装目标。
`--force` 会原地覆盖已安装的插件或 hook pack。对于已跟踪 npm
插件的常规升级，请使用 `openclaw plugins update <id-or-npm-spec>`。
它不支持与 `--link` 一起使用，因为 `--link` 会复用源路径，
而不是复制到受管理的安装目标中。
`openclaw plugins update <id-or-npm-spec>` 适用于已跟踪的安装。传入带 dist-tag 或精确版本的 npm 包规范时，会把包名解析回已跟踪的插件记录，并记录新的规范以供后续更新。传入不带版本的包名时，会将精确固定版本的安装切回注册表默认发布线。如果已安装的 npm 插件已经匹配解析后的版本和记录的制品标识，OpenClaw 会跳过更新，而不会下载、重新安装或重写配置。
`openclaw plugins update <id-or-npm-spec>` 适用于已跟踪的安装。传入
带 dist-tag 或精确版本的 npm 包规范时，会将包名解析回
已跟踪的插件记录，并记录新的规范用于后续更新。
传入不带版本的包名时，会将精确 pin 的安装移回到
注册表的默认发布线。如果已安装的 npm 插件已经匹配
解析后的版本和记录的产物标识，OpenClaw 会跳过此次更新，
不会下载、重装或重写配置。
`--pin` 仅适用于 npm。不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm 规范。
`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为
marketplace 安装会持久化 marketplace 来源元数据，
而不是 npm 规范。
`--dangerously-force-unsafe-install` 是一种紧急覆盖选项，用于处理内置危险代码扫描器的误报。它允许插件安装和插件更新在遇到内置 `critical` 发现后继续进行，但仍然不会绕过插件 `before_install` 策略阻止或扫描失败阻止。
`--dangerously-force-unsafe-install` 是用于处理内置危险代码扫描器
误报的紧急覆盖开关。它允许插件安装
和插件更新在遇到内置 `critical` 发现后继续执行，但仍然
不会绕过插件 `before_install` 策略阻止或扫描失败阻止。
此 CLI 标志仅适用于插件安装 / 更新流程。由 Gateway 网关支持的 Skills 依赖安装则使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖；而 `openclaw skills install` 仍然是独立的 ClawHub Skills 下载 / 安装流程。
这个 CLI 标志只适用于插件 install/update 流程。由 Gateway 网关支持的 Skills
依赖安装则使用匹配的 `dangerouslyForceUnsafeInstall` 请求覆盖；
而 `openclaw skills install` 仍然是独立的 ClawHub Skills 下载/安装流程。
兼容的 Bundle 会参与相同的插件 list / inspect / enable / disable 流程。当前运行时支持包括 Bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。
兼容的 Bundle 也参与同一套插件 list/inspect/enable/disable
流程。当前运行时支持包括 Bundle Skills、Claude command-skills、
Claude `settings.json` 默认值、Claude `.lsp.json` 和 manifest 声明的
`lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook
目录。
`openclaw plugins inspect <id>` 还会报告检测到的 Bundle 能力，以及对于基于 Bundle 的插件所支持或不支持的 MCP 和 LSP 服务器条目。
`openclaw plugins inspect <id>` 还会报告检测到的 Bundle 能力，
以及由 Bundle 支持的插件中受支持或不受支持的 MCP 和 LSP server 条目。
Marketplace 来源可以是来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplace，插件条目必须保持在克隆出的 marketplace 仓库内，并且只能使用相对路径来源。
Marketplace 来源可以是来自
`~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、本地 marketplace 根目录或
`marketplace.json` 路径、如 `owner/repo` 这样的 GitHub 简写、GitHub 仓库
URL，或 git URL。对于远程 marketplace，插件条目必须保留在
克隆的 marketplace 仓库内，并且只能使用相对路径来源。
有关完整细节，请参阅 [`openclaw plugins` CLI 参考](/cli/plugins)。
完整详情参见 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins)。
## 插件 API 概览
原生插件会导出一个入口对象，并暴露 `register(api)`。较旧的插件仍可能使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。
原生插件会导出一个入口对象，并暴露 `register(api)`。旧版
插件仍可能使用 `activate(api)` 作为旧版别名，但新插件应
使用 `register`。
```typescript
export default definePluginEntry({
@ -279,7 +324,9 @@ export default definePluginEntry({
});
```
OpenClaw 会加载该入口对象，并在插件激活期间调用 `register(api)`。加载器仍会为旧插件回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公开契约。
OpenClaw 会加载该入口对象，并在插件激活期间调用 `register(api)`。
对于旧版插件，加载器仍会回退到 `activate(api)`，
但内置插件和新的外部插件应将 `register` 视为公共契约。
常见注册方法：
@ -291,34 +338,34 @@ OpenClaw 会加载该入口对象，并在插件激活期间调用 `register(api
| `registerHook` / `on(...)` | 生命周期 hook |
| `registerSpeechProvider` | 文本转语音 / STT |
| `registerRealtimeTranscriptionProvider` | 流式 STT |
| `registerRealtimeVoiceProvider` | 双向实时语音 |
| `registerMediaUnderstandingProvider` | 图像 / 音频分析 |
| `registerRealtimeVoiceProvider` | 双工实时语音 |
| `registerMediaUnderstandingProvider` | 图像/音频分析 |
| `registerImageGenerationProvider` | 图像生成 |
| `registerMusicGenerationProvider` | 音乐生成 |
| `registerVideoGenerationProvider` | 视频生成 |
| `registerWebFetchProvider` | 网页抓取 / 抓取提供商 |
| `registerWebFetchProvider` | 网页抓取 / 爬取提供商 |
| `registerWebSearchProvider` | 网页搜索 |
| `registerHttpRoute` | HTTP 端点 |
| `registerCommand` / `registerCli` | CLI 命令 |
| `registerContextEngine` | 上下文引擎 |
| `registerService` | 后台服务 |
类型化生命周期 hook 的守卫行为：
类型化生命周期 hook 的 guard 行为：
- `before_tool_call`：`{ block: true }` 为终止结果；较低优先级的处理器会被跳过。
- `before_tool_call`：`{ block: false }` 是空操作，不会清除先前的阻止。
- `before_install`：`{ block: true }` 为终止结果；较低优先级的处理器会被跳过。
- `before_install`：`{ block: false }` 是空操作，不会清除先前的阻止。
- `message_sending`：`{ cancel: true }` 为终止结果；较低优先级的处理器会被跳过。
- `message_sending`：`{ cancel: false }` 是空操作，不会清除先前的取消。
- `before_tool_call`：`{ block: true }` 为终止结果；低优先级 handler 会被跳过。
- `before_tool_call`：`{ block: false }` 为 no-op，不会清除更早的 block。
- `before_install`：`{ block: true }` 为终止结果；低优先级 handler 会被跳过。
- `before_install`：`{ block: false }` 为 no-op，不会清除更早的 block。
- `message_sending`：`{ cancel: true }` 为终止结果；低优先级 handler 会被跳过。
- `message_sending`：`{ cancel: false }` 为 no-op，不会清除更早的 cancel。
有关完整的类型化 hook 行为，请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
## 相关内容
- [构建插件](/zh-CN/plugins/building-plugins) — 创建你自己的插件
- [插件 Bundle](/zh-CN/plugins/bundles) — Codex/Claude/Cursor Bundle 兼容性
- [插件清单](/zh-CN/plugins/manifest) — 清单 schema
- [注册工具](/zh-CN/plugins/building-plugins#registering-agent-tools) — 在插件中添加智能体工具
- [插件内部机制](/zh-CN/plugins/architecture) — 能力模型和加载流水线
- [社区插件](/zh-CN/plugins/community) — 第三方列表
- [Building Plugins](/zh-CN/plugins/building-plugins) — 创建你自己的插件
- [Plugin Bundles](/zh-CN/plugins/bundles) — 与 Codex/Claude/Cursor Bundle 的兼容性
- [Plugin Manifest](/zh-CN/plugins/manifest) — manifest schema
- [Registering Tools](/zh-CN/plugins/building-plugins#registering-agent-tools) — 在插件中添加智能体工具
- [Plugin Internals](/zh-CN/plugins/architecture) — 能力模型与加载管线
- [Community Plugins](/zh-CN/plugins/community) — 第三方列表

80
docs/zh-CN/tools/skills-config.md
View File

@ -2,20 +2,20 @@
read_when:
- 添加或修改 Skills 配置
- 调整内置 allowlist 或安装行为
summary: Skills 配置 schema 和示例
summary: Skills 配置模式和示例
title: Skills 配置
x-i18n:
generated_at: "2026-04-20T18:30:05Z"
generated_at: "2026-04-23T06:43:47Z"
model: gpt-5.4
provider: openai
source_hash: 8af3a51af5d6d6af355c529bb8ec0a045046c635d8fff0dec20cd875ec12e88b
source_hash: 7f3b0a5946242bb5c07fd88678c88e3ee62cda514a5afcc9328f67853e05ad3f
source_path: tools/skills-config.md
workflow: 15
---
# Skills 配置
大多数 Skills 加载器/安装配置位于 `~/.openclaw/openclaw.json` 中的 `skills` 下。特定智能体的 Skills 可见性位于 `agents.defaults.skills` 和 `agents.list[].skills` 下。
大多数 Skills 加载器/安装配置位于 `~/.openclaw/openclaw.json` 中的 `skills` 下。智能体特定的 Skills 可见性位于 `agents.defaults.skills` 和 `agents.list[].skills` 下。
```json5
{
@ -28,7 +28,7 @@ x-i18n:
},
install: {
preferBrew: true,
nodeManager: "npm", // npm | pnpm | yarn | bun (Gateway 运行时仍为 Node；不建议使用 bun)
nodeManager: "npm", // npm | pnpm | yarn | bun（Gateway 网关运行时仍为 Node；不推荐 bun）
},
entries: {
"image-lab": {
@ -45,18 +45,18 @@ x-i18n:
}
```
对于内置的图像生成/编辑，优先使用 `agents.defaults.imageGenerationModel` 加上核心 `image_generate` 工具。`skills.entries.*` 仅用于自定义或第三方 skill 工作流。
对于内置图像生成/编辑，优先使用 `agents.defaults.imageGenerationModel` 加上核心 `image_generate` 工具。`skills.entries.*` 仅用于自定义或第三方 Skill 工作流。
如果你选择了特定的图像提供商/模型，还需要配置该提供商的凭证/API 密钥。常见示例：`google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 使用 `OPENAI_API_KEY`，`fal/*` 使用 `FAL_KEY`。
如果你选择了特定的图像提供商/模型，也请配置该提供商的身份验证/API 密钥。常见示例：`google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 使用 `OPENAI_API_KEY`，`fal/*` 使用 `FAL_KEY`。
示例：
- 原生 Nano Banana 风格设置：`agents.defaults.imageGenerationModel.primary: "google/gemini-3.1-flash-image-preview"`
- 原生 Nano Banana Pro 风格设置：`agents.defaults.imageGenerationModel.primary: "google/gemini-3-pro-image-preview"`
- 原生 fal 设置：`agents.defaults.imageGenerationModel.primary: "fal/fal-ai/flux/dev"`
## 智能体 Skills allowlist
## 智能体 Skill allowlist
当你希望同一台机器/工作区使用相同的 skill 根目录，但每个智能体可见的 skill 集合不同，请使用智能体配置。
当你希望同一台机器/工作区使用相同的 Skill 根目录，但每个智能体显示的 Skill 集合不同，请使用智能体配置。
```json5
{
@ -75,52 +75,54 @@ x-i18n:
规则：
- `agents.defaults.skills`：供省略 `agents.list[].skills` 的智能体继承的共享基线 allowlist。
- 省略 `agents.defaults.skills`，则默认不限制 Skills。
- `agents.list[].skills`：该智能体显式的最终 skill 集合；不会与默认值合并。
- `agents.defaults.skills`：对省略 `agents.list[].skills` 的智能体生效的共享基础 allowlist。
- 省略 `agents.defaults.skills` 可让 Skills 默认不受限制。
- `agents.list[].skills`：该智能体的显式最终 Skill 集合；不会与默认值合并。
- `agents.list[].skills: []`：该智能体不暴露任何 Skills。
## 字段
- 内置的 skill 根目录始终包括 `~/.openclaw/skills`、`~/.agents/skills`、`<workspace>/.agents/skills` 和 `<workspace>/skills`。
- `allowBundled`：仅针对**内置** Skills 的可选 allowlist。设置后，只有列表中的内置 Skills 可用（不影响受管 Skills、智能体 Skills 和工作区 Skills）。
- `load.extraDirs`：要扫描的额外 skill 目录（最低优先级）。
- `load.watch`：监听 skill 文件夹并刷新 Skills 快照（默认：true）。
- `load.watchDebounceMs`：skill 监听事件的防抖时间（毫秒，默认：250）。
- 内置 Skill 根目录始终包括 `~/.openclaw/skills`、`~/.agents/skills`、`<workspace>/.agents/skills` 和 `<workspace>/skills`。
- `allowBundled`：仅针对**内置** Skills 的可选 allowlist。设置后，只有列表中的内置 Skills 才有资格被启用（不影响 managed、智能体和工作区 Skills）。
- `load.extraDirs`：要扫描的其他 Skill 目录（最低优先级）。
- `load.watch`：监视 Skill 文件夹并刷新 Skills 快照（默认：true）。
- `load.watchDebounceMs`：Skill watcher 事件的防抖时间（毫秒，默认：250）。
- `install.preferBrew`：可用时优先使用 brew 安装器（默认：true）。
- `install.nodeManager`：Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`，默认：npm）。
这只影响 **skill 安装**；Gateway 运行时仍应为 Node
（WhatsApp/Telegram 不建议使用 Bun）。
- `openclaw setup --node-manager` 的范围更窄，目前仅接受 `npm`、
`pnpm` 或 `bun`。如果你想使用基于 Yarn 的 skill 安装，请手动设置 `skills.install.nodeManager: "yarn"`。
- `entries.<skillKey>`：按 skill 的覆盖项。
- `agents.defaults.skills`：供省略 `agents.list[].skills` 的智能体继承的可选默认 skill allowlist。
- `agents.list[].skills`：可选的按智能体最终 skill allowlist；显式列表会替换继承的默认值，而不是合并。
这只影响 **Skill 安装**；Gateway 网关运行时仍应为 Node
（WhatsApp/Telegram 不推荐使用 Bun）。
- `openclaw setup --node-manager` 的范围更窄，目前只接受 `npm`、
`pnpm` 或 `bun`。如果你想使用 Yarn 支持的 Skill 安装，请手动设置 `skills.install.nodeManager: "yarn"`。
- `entries.<skillKey>`：每个 Skill 的覆盖项。
- `agents.defaults.skills`：可选的默认 Skill allowlist，由省略
`agents.list[].skills` 的智能体继承。
- `agents.list[].skills`：可选的每智能体最终 Skill allowlist；显式
列表会替换继承的默认值，而不是合并。
按 skill 的字段：
每个 Skill 的字段：
- `enabled`：设置为 `false` 可禁用某个 skill，即使它已内置/已安装。
- `env`：为智能体运行注入的环境变量（仅在尚未设置时生效）。
- `apiKey`：为声明了主环境变量的 skill 提供的可选便捷配置。
- `enabled`：即使 Skill 已内置/安装，也可通过设为 `false` 禁用。
- `env`：为智能体运行注入的环境变量（仅在尚未设置时）。
- `apiKey`：为声明了主环境变量的 Skill 提供的可选便捷项。
支持明文字符串或 SecretRef 对象（`{ source, provider, id }`）。
## 说明
- `entries` 下的键默认映射到 skill 名称。如果某个 skill 定义了
`metadata.openclaw.skillKey`，则使用该键。
- `entries` 下的键默认映射到 Skill 名称。如果某个 Skill 定义了
`metadata.openclaw.skillKey`，则改用该键。
- 加载优先级为 `<workspace>/skills` → `<workspace>/.agents/skills` →
`~/.agents/skills` → `~/.openclaw/skills` → 内置 Skills →
`skills.load.extraDirs`。
- 启用监听器后，对 Skills 的更改会在智能体的下一轮处理时生效。
- 启用 watcher 时，对 Skills 的更改会在下一次智能体轮次时生效。
### 沙箱隔离的 Skills + 环境变量
### 沙箱隔离 Skills + 环境变量
当一个会话处于**沙箱隔离**状态时，skill 进程会在已配置的
沙箱后端内运行。沙箱**不会**继承主机的 `process.env`。
当某个会话处于**沙箱隔离**状态时，Skill 进程会在配置好的
沙箱后端中运行。该沙箱**不会**继承宿主机的 `process.env`。
请使用以下之一：
请使用以下方式之一：
- Docker 后端使用 `agents.defaults.sandbox.docker.env`（或按智能体使用 `agents.list[].sandbox.docker.env`）
- 将环境变量烘焙进你的自定义沙箱镜像或远程沙箱环境
- Docker 后端使用 `agents.defaults.sandbox.docker.env`（或每智能体的 `agents.list[].sandbox.docker.env`）
- 将环境变量烘焙进你的自定义沙箱镜像或远程沙箱环境中
全局 `env` 和 `skills.entries.<skill>.env/apiKey` 仅适用于**主机**运行。
全局 `env` 和 `skills.entries.<skill>.env/apiKey` 仅适用于**宿主机**运行。

257
docs/zh-CN/tools/slash-commands.md
View File

@ -2,13 +2,13 @@
read_when:
- 使用或配置聊天命令
- 调试命令路由或权限
summary: 斜杠命令：文本与原生、配置以及支持的命令
summary: 斜杠命令：文本版与原生版、配置以及受支持的命令
title: 斜杠命令
x-i18n:
generated_at: "2026-04-21T20:23:17Z"
generated_at: "2026-04-23T06:43:54Z"
model: gpt-5.4
provider: openai
source_hash: 43cc050149de60ca39083009fd6ce566af3bfa79d455e2e0f44e2d878bf4d2d9
source_hash: d591ba4e692d77ca5b4549987ad9db557fc5c6d00a3f152381b74eae73c4ea81
source_path: tools/slash-commands.md
workflow: 15
---
@ -16,20 +16,21 @@ x-i18n:
# 斜杠命令
命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。
仅主机可用的 bash 聊天命令使用 `! <cmd>`（`/bash <cmd>` 是它的别名）。
仅限主机的 bash 聊天命令使用 `! <cmd>`（`/bash <cmd>` 是其别名）。
这里有两个相关系统：
- **命令**：独立的 `/...` 消息。
- **指令**：`/think`、`/fast`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/exec`、`/model`、`/queue`。
- 指令会在模型看到消息之前从消息中剥离。
- 在普通聊天消息中（不是仅含指令的消息），它们会被视为“内联提示”，并且**不会**持久化会话设置。
- 在仅含指令的消息中（消息只包含指令），它们会持久化到会话中，并回复一条确认消息。
- 指令只会对**已授权发送者**生效。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则授权来自渠道允许列表/配对以及 `commands.useAccessGroups`。
未授权发送者会看到指令被当作纯文本处理。
- 在普通聊天消息中（非纯指令消息），它们会被视为“内联提示”，且**不会**持久化会话设置。
- 在纯指令消息中（消息只包含指令），它们会持久化到会话，并回复一条确认信息。
- 指令只会应用于**已授权发送者**。如果设置了 `commands.allowFrom`，它就是唯一使用的
allowlist；否则授权来自渠道 allowlist/配对以及 `commands.useAccessGroups`。
未授权发送者会看到指令被当作普通文本处理。
另外还有一些**内联快捷方式**（仅限允许列表/已授权发送者）：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
它们会立即运行，在模型看到消息之前被剥离，剩余文本继续按正常流程处理。
还有少量**内联快捷命令**（仅限 allowlist/已授权发送者）：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
它们会立即运行，在模型看到消息前被剥离，剩余文本会继续走正常流程。
## 配置
@ -61,89 +62,90 @@ x-i18n:
- `commands.text`（默认 `true`）启用在聊天消息中解析 `/...`。
- 在没有原生命令的界面上（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams），即使你将其设为 `false`，文本命令仍然可用。
- `commands.native`（默认 `"auto"`）注册原生命令。
- Auto：对 Discord/Telegram 开启；对 Slack 关闭（直到你添加斜杠命令）；对不支持原生命令的提供商忽略。
- 设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。
- `false` 会在启动时清除之前在 Discord/Telegram 上注册的命令。Slack 命令在 Slack 应用中管理，不会自动移除。
- `commands.nativeSkills`（默认 `"auto"`）在支持时以原生方式注册 **skill** 命令。
- Auto：对 Discord/Telegram 开启；对 Slack 关闭（Slack 需要为每个 skill 单独创建一个斜杠命令）。
- 设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。
- `commands.bash`（默认 `false`）启用 `! <cmd>` 以运行主机 shell 命令（`/bash <cmd>` 是别名；需要 `tools.elevated` 允许列表）。
- `commands.bashForegroundMs`（默认 `2000`）控制 bash 在切换到后台模式前等待多长时间（`0` 表示立即转入后台）。
- Auto：Discord/Telegram 上开启；Slack 上关闭（直到你添加 slash commands）；对于不支持原生能力的提供商会被忽略。
- 可设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native`，以按提供商覆盖（布尔值或 `"auto"`）。
- `false` 会在启动时清除 Discord/Telegram 上先前注册的命令。Slack 命令在 Slack 应用中管理，不会自动移除。
- `commands.nativeSkills`（默认 `"auto"`）会在支持时以原生方式注册 **skill** 命令。
- Auto：Discord/Telegram 上开启；Slack 上关闭（Slack 需要为每个 skill 单独创建一个 slash command）。
- 可设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills`，以按提供商覆盖（布尔值或 `"auto"`）。
- `commands.bash`（默认 `false`）启用 `! <cmd>` 来运行主机 shell 命令（`/bash <cmd>` 是别名；需要 `tools.elevated` allowlist）。
- `commands.bashForegroundMs`（默认 `2000`）控制 bash 在切换到后台模式前等待多久（`0` 表示立即转入后台）。
- `commands.config`（默认 `false`）启用 `/config`（读取/写入 `openclaw.json`）。
- `commands.mcp`（默认 `false`）启用 `/mcp`（读取/写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 配置）。
- `commands.mcp`（默认 `false`）启用 `/mcp`（读取/写入由 OpenClaw 管理的 `mcp.servers` 下的 MCP 配置）。
- `commands.plugins`（默认 `false`）启用 `/plugins`（插件发现/状态，以及安装 + 启用/禁用控制）。
- `commands.debug`（默认 `false`）启用 `/debug`（仅运行时覆盖）。
- `commands.restart`（默认 `true`）启用 `/restart` 以及 Gateway 网关重启工具操作。
- `commands.ownerAllowFrom`（可选）为仅限所有者的命令/工具界面设置显式所有者允许列表。这与 `commands.allowFrom` 分开。
- 每个渠道的 `channels.<channel>.commands.enforceOwnerForCommands`（可选，默认 `false`）会让该界面上的仅限所有者命令必须由**所有者身份**执行。设为 `true` 时，发送者必须匹配一个已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生所有者元数据），或者在内部消息渠道上持有内部 `operator.admin` 范围。渠道 `allowFrom` 中的通配符条目，或空的/无法解析的所有者候选列表，**都不足以**满足要求——该渠道上的仅限所有者命令会以关闭方式失败。如果你希望仅限所有者命令只受 `ownerAllowFrom` 和标准命令允许列表限制，请保持关闭。
- `commands.ownerDisplay` 控制所有者 id 在系统提示中如何显示：`raw` 或 `hash`。
- `commands.ownerDisplaySecret` 可选设置当 `commands.ownerDisplay="hash"` 时使用的 HMAC secret。
- `commands.allowFrom`（可选）为命令授权设置按提供商划分的允许列表。配置后，它将成为命令和指令的唯一授权来源（渠道允许列表/配对以及 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商特定键会覆盖它。
- `commands.useAccessGroups`（默认 `true`）在未设置 `commands.allowFrom` 时，对命令强制执行允许列表/策略。
- `commands.ownerAllowFrom`（可选）为仅限所有者的命令/工具界面设置显式所有者 allowlist。这与 `commands.allowFrom` 是分开的。
- 每渠道的 `channels.<channel>.commands.enforceOwnerForCommands`（可选，默认 `false`）会让该界面上的仅限所有者命令必须由**所有者身份**才能运行。为 `true` 时，发送者必须匹配已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生所有者元数据），或者在内部消息渠道上持有内部 `operator.admin` 作用域。渠道 `allowFrom` 中的通配符条目，或空/未解析的所有者候选列表，**都不**足够——该渠道上的仅限所有者命令会以关闭默认放行的方式失败。如果你希望仅限所有者命令只受 `ownerAllowFrom` 和标准命令 allowlist 约束，请保持此项关闭。
- `commands.ownerDisplay` 控制系统提示中所有者 id 的显示方式：`raw` 或 `hash`。
- `commands.ownerDisplaySecret` 可选设置当 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。
- `commands.allowFrom`（可选）为命令授权设置按提供商划分的 allowlist。配置后，它将成为命令和指令的唯一授权来源（渠道 allowlist/配对和 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商特定键会覆盖它。
- `commands.useAccessGroups`（默认 `true`）在未设置 `commands.allowFrom` 时，对命令强制执行 allowlist/策略。
## 命令列表
当前事实来源：
当前权威来源：
- 核心内置命令来自 `src/auto-reply/commands-registry.shared.ts`
- 生成的 dock 命令来自 `src/auto-reply/commands-registry.data.ts`
- 插件命令来自插件 `registerCommand()` 调用
- 你网关上的实际可用性仍取决于配置标志、渠道界面以及已安装/已启用的插件
- 插件命令来自插件的 `registerCommand()` 调用
- 你网关中的实际可用性仍取决于配置标志、渠道界面以及已安装/已启用的插件
### 核心内置命令
当前可用的内置命令：
- `/new [model]` 开始一个新会话；`/reset` 是重置别名。
- `/reset soft [message]` 保留当前转录内容，丢弃复用的 CLI 后端会话 id，并原地重新运行启动/系统提示加载。
- `/new [model]` 启动新会话；`/reset` 是重置别名。
- `/reset soft [message]` 保留当前转录，丢弃复用的 CLI 后端会话 id，并原地重新运行启动/系统提示加载。
- `/compact [instructions]` 压缩会话上下文。参见 [/concepts/compaction](/zh-CN/concepts/compaction)。
- `/stop` 中止当前运行。
- `/session idle <duration|off>` 和 `/session max-age <duration|off>` 管理线程绑定过期。
- `/think <level>` 设置思考级别。可选项来自活动模型的提供商配置；常见级别有 `off`、`minimal`、`low`、`medium` 和 `high`，也可能有 `xhigh`、`adaptive`、`max` 等自定义级别，或仅在支持时提供二元 `on`。别名：`/thinking`、`/t`。
- `/think <level>` 设置 thinking 级别。可选值来自活动模型的提供商配置文件；常见级别有 `off`、`minimal`、`low`、`medium` 和 `high`，也有仅在支持时可用的自定义级别，如 `xhigh`、`adaptive`、`max` 或二元值 `on`。别名：`/thinking`、`/t`。
- `/verbose on|off|full` 切换详细输出。别名：`/v`。
- `/trace on|off` 为当前会话切换插件跟踪输出。
- `/fast [status|on|off]` 显示或设置快速模式。
- `/reasoning [on|off|stream]` 切换推理可见性。别名：`/reason`。
- `/elevated [on|off|ask|full]` 切换提权模式。别名：`/elev`。
- `/reasoning [on|off|stream]` 切换 reasoning 可见性。别名：`/reason`。
- `/elevated [on|off|ask|full]` 切换 elevated 模式。别名：`/elev`。
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` 显示或设置 exec 默认值。
- `/model [name|#|status]` 显示或设置模型。
- `/models [provider] [page] [limit=<n>|size=<n>|all]` 列出提供商或某个提供商的模型。
- `/queue <mode>` 管理队列行为（`steer`、`interrupt`、`followup`、`collect`、`steer-backlog`），以及诸如 `debounce:2s cap:25 drop:summarize` 的选项。
- `/help` 显示简短帮助摘要。
- `/models [provider] [page] [limit=<n>|size=<n>|all]` 列出提供商或某个提供商下的模型。
- `/queue <mode>` 管理队列行为（`steer`、`interrupt`、`followup`、`collect`、`steer-backlog`），以及如 `debounce:2s cap:25 drop:summarize` 之类的选项。
- `/help` 显示简要帮助摘要。
- `/commands` 显示生成的命令目录。
- `/tools [compact|verbose]` 显示当前智能体现在可以使用什么。
- `/tools [compact|verbose]` 显示当前智能体此刻可用的工具。
- `/status` 显示运行时状态，包括可用时的提供商使用量/配额。
- `/tasks` 列出当前会话的活动/最近后台任务。
- `/context [list|detail|json]` 说明上下文是如何组装的。
- `/tasks` 列出当前会话活跃/最近的后台任务。
- `/context [list|detail|json]` 解释上下文是如何组装的。
- `/export-session [path]` 将当前会话导出为 HTML。别名：`/export`。
- `/export-trajectory [path]` 为当前会话导出 JSONL 轨迹包。别名：`/trajectory`。
- `/whoami` 显示你的发送者 id。别名：`/id`。
- `/skill <name> [input]` 按名称运行一个 skill。
- `/allowlist [list|add|remove] ...` 管理允许列表条目。仅文本。
- `/allowlist [list|add|remove] ...` 管理 allowlist 条目。仅文本版。
- `/approve <id> <decision>` 处理 exec 审批提示。
- `/btw <question>` 提出一个旁支问题，而不改变后续会话上下文。参见 [/tools/btw](/zh-CN/tools/btw)。
- `/btw <question>` 提出一个旁支问题，但不改变未来会话上下文。参见 [/tools/btw](/zh-CN/tools/btw)。
- `/subagents list|kill|log|info|send|steer|spawn` 管理当前会话的子智能体运行。
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` 管理 ACP 会话和运行时选项。
- `/focus <target>` 将当前 Discord 线程或 Telegram 话题/对话绑定到一个会话目标。
- `/focus <target>` 将当前 Discord 线程或 Telegram 话题/会话绑定到一个会话目标。
- `/unfocus` 移除当前绑定。
- `/agents` 列出当前会话中线程绑定的智能体。
- `/kill <id|#|all>` 中止一个或所有正在运行的子智能体。
- `/steer <id|#> <message>` 向正在运行的子智能体发送引导。别名：`/tell`。
- `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅限所有者。需要 `commands.config: true`。
- `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅限所有者。需要 `commands.mcp: true`。
- `/mcp show|get|set|unset` 读取或写入 OpenClaw 管理的 `mcp.servers` 下的 MCP 服务器配置。仅限所有者。需要 `commands.mcp: true`。
- `/plugins list|inspect|show|get|install|enable|disable` 检查或修改插件状态。`/plugin` 是别名。写操作仅限所有者。需要 `commands.plugins: true`。
- `/debug show|set|unset|reset` 管理仅运行时的配置覆盖。仅限所有者。需要 `commands.debug: true`。
- `/debug show|set|unset|reset` 管理仅运行时配置覆盖。仅限所有者。需要 `commands.debug: true`。
- `/usage off|tokens|full|cost` 控制每次响应的使用量页脚，或打印本地成本摘要。
- `/tts on|off|status|provider|limit|summary|audio|help` 控制 TTS。参见 [/tools/tts](/zh-CN/tools/tts)。
- `/restart` 在启用时重启 OpenClaw。默认：启用；设置 `commands.restart: false` 可禁用它。
- `/restart` 在启用时重启 OpenClaw。默认：启用；设置 `commands.restart: false` 可禁用。
- `/activation mention|always` 设置群组激活模式。
- `/send on|off|inherit` 设置发送策略。仅限所有者。
- `/bash <command>` 运行主机 shell 命令。仅文本。别名：`! <command>`。需要 `commands.bash: true` 加上 `tools.elevated` 允许列表。
- `/bash <command>` 运行主机 shell 命令。仅文本版。别名：`! <command>`。需要 `commands.bash: true` 加 `tools.elevated` allowlist。
- `!poll [sessionId]` 检查后台 bash 作业。
- `!stop [sessionId]` 停止后台 bash 作业。
### 生成的 dock 命令
Dock 命令由具有原生命令支持的渠道插件生成。当前内置集合：
Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
- `/dock-discord`（别名：`/dock_discord`）
- `/dock-mattermost`（别名：`/dock_mattermost`）
@ -154,12 +156,12 @@ Dock 命令由具有原生命令支持的渠道插件生成。当前内置集合
内置插件可以添加更多斜杠命令。此仓库中当前的内置命令：
- `/dreaming [on|off|status|help]` 切换 memory dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。
- `/dreaming [on|off|status|help]` 切换记忆 Dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。
- `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。参见 [Pairing](/zh-CN/channels/pairing)。
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` 临时启用高风险手机节点命令。
- `/voice status|list [limit]|set <voiceId|name>` 管理 Talk 语音配置。在 Discord 上，原生命令名是 `/talkvoice`。
- `/voice status|list [limit]|set <voiceId|name>` 管理 Talk 语音配置。在 Discord 上，原生命令名为 `/talkvoice`。
- `/card ...` 发送 LINE 富卡片预设。参见 [LINE](/zh-CN/channels/line)。
- `/codex status|models|threads|resume|compact|review|account|mcp|skills` 检查并控制内置 Codex 应用服务器 harness。参见 [Codex Harness](/zh-CN/plugins/codex-harness)。
- `/codex status|models|threads|resume|compact|review|account|mcp|skills` 检查并控制内置 Codex app-server harness。参见 [Codex Harness](/zh-CN/plugins/codex-harness)。
- 仅 QQ Bot 命令：
- `/bot-ping`
- `/bot-version`
@ -169,71 +171,71 @@ Dock 命令由具有原生命令支持的渠道插件生成。当前内置集合
### 动态 skill 命令
用户可调用的 skills 也会作为斜杠命令暴露：
用户可调用的 Skills 也会作为斜杠命令暴露：
- `/skill <name> [input]` 始终可作为通用入口点使用。
- 当 skill/插件注册它们时，skills 也可能显示为直接命令，例如 `/prose`。
- 当 skill/插件注册了直接命令时，它们也可能显示为像 `/prose` 这样的直接命令。
- 原生 skill 命令注册由 `commands.nativeSkills` 和 `channels.<provider>.commands.nativeSkills` 控制。
注意：
说明：
- 命令接受命令与参数之间可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。
- `/new <model>` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配项，则该文本会被视为消息正文。
- 要查看完整的提供商用量明细，请使用 `openclaw status --usage`。
- `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道的 `configWrites`。
- 命令接受一个可选的 `:` 作为命令与参数之间的分隔（例如 `/think: high`、`/send: on`、`/help:`）。
- `/new <model>` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果未匹配到，则该文本会被视为消息正文。
- 如需完整的提供商使用量明细，请使用 `openclaw status --usage`。
- `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道 `configWrites`。
- 在多账户渠道中，面向配置目标的 `/allowlist --account <id>` 和 `/config set channels.<provider>.accounts.<id>...` 也会遵循目标账户的 `configWrites`。
- `/usage` 控制每次响应的使用量页脚；`/usage cost` 会从 OpenClaw 会话日志中打印本地成本摘要。
- `/restart` 默认启用；设置 `commands.restart: false` 可禁用它。
- `/plugins install <spec>` 接受与 `openclaw plugins install` 相同的插件规范：本地路径/归档、npm 包，或 `clawhub:<pkg>`。
- `/plugins enable|disable` 会更新插件配置，并且可能提示你重启。
- 仅限 Discord 的原生命令：`/vc join|leave|status` 用于控制语音频道（需要 `channels.discord.voice` 和原生命令；不提供文本形式）。
- Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）要求有效线程绑定已启用（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。
- `/usage` 控制每条响应的使用量页脚；`/usage cost` 会根据 OpenClaw 会话日志打印本地成本摘要。
- `/restart` 默认启用；设置 `commands.restart: false` 可禁用。
- `/plugins install <spec>` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/归档、npm 包或 `clawhub:<pkg>`。
- `/plugins enable|disable` 会更新插件配置，并可能提示重启。
- 仅限 Discord 的原生命令：`/vc join|leave|status` 用于控制语音频道（需要 `channels.discord.voice` 和原生命令；文本版不可用）。
- Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）要求已有效启用线程绑定（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。
- ACP 命令参考和运行时行为： [ACP Agents](/zh-CN/tools/acp-agents)。
- `/verbose` 用于调试和额外可见性；在正常使用中请保持**关闭**。
- `/trace` 比 `/verbose` 更窄：它只显示插件所属的跟踪/调试行，并保持正常的详细工具输出关闭。
- `/fast on|off` 会持久化一个会话覆盖。使用会话 UI 中的 `inherit` 选项可清除它，并回退到配置默认值。
- `/fast` 是提供商特定的：OpenAI/OpenAI Codex 会在原生 Responses 端点上将其映射为 `service_tier=priority`，而直接发送到 `api.anthropic.com` 的公开 Anthropic 请求（包括通过 OAuth 认证的流量）会将其映射为 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。
- 相关时仍会显示工具失败摘要，但详细失败文本只会在 `/verbose` 为 `on` 或 `full` 时包含。
- `/reasoning`、`/verbose` 和 `/trace` 在群组场景中有风险：它们可能暴露你原本无意公开的内部推理、工具输出或插件诊断信息。建议保持关闭，尤其是在群聊中。
- `/verbose` 用于调试和提供更多可见性；在正常使用中请保持**关闭**。
- `/trace` 比 `/verbose` 更窄：它只显示插件拥有的 trace/debug 行，并保持普通的详细工具输出关闭。
- `/fast on|off` 会持久化一个会话覆盖值。使用 Sessions UI 的 `inherit` 选项可清除该值并回退到配置默认值。
- `/fast` 具有提供商特异性：OpenAI/OpenAI Codex 会在原生 Responses 端点上将其映射为 `service_tier=priority`，而直接发往 `api.anthropic.com` 的公开 Anthropic 请求（包括通过 OAuth 认证发送的流量）则会将其映射为 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。
- 工具失败摘要仍会在相关时显示，但详细失败文本只有在 `/verbose` 为 `on` 或 `full` 时才会包含。
- `/reasoning`、`/verbose` 和 `/trace` 在群组环境中具有风险：它们可能暴露你原本无意公开的内部推理、工具输出或插件诊断信息。建议保持关闭，尤其是在群聊中。
- `/model` 会立即持久化新的会话模型。
- 如果智能体处于空闲状态，下一次运行会立即使用它。
- 如果智能体处于空闲状态，下次运行会立即使用它。
- 如果某次运行已经处于活动状态，OpenClaw 会将实时切换标记为待处理，并仅在一个干净的重试点重启到新模型。
- 如果工具活动或回复输出已经开始，这个待处理切换可能会一直排队，直到稍后的重试机会或下一次用户轮次。
- **快速路径：** 来自允许列表发送者的仅命令消息会立即处理（绕过队列 + 模型）。
- **群组提及门控：** 来自允许列表发送者的仅命令消息会绕过提及要求。
- **内联快捷方式（仅限允许列表发送者）：** 某些命令在嵌入普通消息时也可工作，并会在模型看到剩余文本前被剥离。
- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到后续的重试机会或下一个用户轮次。
- **快速路径：** 来自 allowlist 发送者的纯命令消息会被立即处理（绕过队列 + 模型）。
- **群组提及门控：** 来自 allowlist 发送者的纯命令消息会绕过提及要求。
- **内联快捷命令（仅限 allowlist 发送者）：** 某些命令在嵌入普通消息时也可工作，并会在模型看到剩余文本前被剥离。
- 示例：`hey /status` 会触发一条状态回复，剩余文本继续按正常流程处理。
- 当前包括：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
- 未授权的仅命令消息会被静默忽略，而内联 `/...` 令牌会被当作纯文本处理。
- **Skill 命令：** `user-invocable` 的 skills 会作为斜杠命令公开。名称会被规范化为 `a-z0-9_`（最多 32 个字符）；冲突时会添加数字后缀（例如 `_2`）。
- `/skill <name> [input]` 按名称运行一个 skill（当原生命令限制阻止为每个 skill 创建命令时，这很有用）。
- 未授权的纯命令消息会被静默忽略，而内联 `/...` 令牌会被视为普通文本。
- **Skill 命令：** `user-invocable` 的 Skills 会暴露为斜杠命令。名称会被清理为 `a-z0-9_`（最多 32 个字符）；冲突时会追加数字后缀（例如 `_2`）。
- `/skill <name> [input]` 按名称运行一个 skill（当原生命令限制阻止为每个 skill 创建单独命令时，这很有用）。
- 默认情况下，skill 命令会作为普通请求转发给模型。
- Skills 可以选择声明 `command-dispatch: tool`，将命令直接路由到工具（确定性，不经过模型）。
- 示例：`/prose`（OpenProse 插件）——参见 [OpenProse](/zh-CN/prose)。
- **原生命令参数：** Discord 对动态选项使用自动补全（当你省略必需参数时，也会显示按钮菜单）。Telegram 和 Slack 在命令支持可选项且你省略该参数时，会显示按钮菜单。
- Skills 可以选择声明 `command-dispatch: tool`，将命令直接路由到某个工具（确定性，不经过模型）。
- 示例：`/prose`（OpenProse 插件）—— 参见 [OpenProse](/zh-CN/prose)。
- **原生命令参数：** Discord 对动态选项使用自动补全（当你省略必需参数时，也会使用按钮菜单）。Telegram 和 Slack 则会在某个命令支持可选项且你省略该参数时显示一个按钮菜单。
## `/tools`
`/tools` 回答的是一个运行时问题，而不是配置问题：**这个智能体现在在
这个对话中可以使用什么**。
`/tools` 回答的是一个运行时问题，而不是配置问题：**这个智能体当前在
这段对话中实际能使用什么**。
- 默认的 `/tools` 是紧凑模式，并针对快速浏览进行了优化。
- 默认的 `/tools` 是精简版，针对快速浏览进行了优化。
- `/tools verbose` 会添加简短说明。
- 支持参数的原生命令界面会公开相同的模式切换，即 `compact|verbose`。
- 结果以会话为作用域，因此更改智能体、渠道、线程、发送者授权或模型都可能
- 支持参数的原生命令界面会以 `compact|verbose` 暴露相同的模式切换。
- 结果是会话范围的，因此更换智能体、渠道、线程、发送者授权或模型都可能
改变输出。
- `/tools` 包括那些在运行时实际上可达的工具，包括核心工具、已连接的
插件工具以及渠道所属工具。
- `/tools` 包括运行时实际可达的工具，包括核心工具、已连接的
插件工具以及渠道自有工具。
对于配置文件和覆盖项编辑，请使用控制 UI 的工具面板或配置/目录界面，
而不要将 `/tools` 当作静态目录。
对于配置文件和覆盖项编辑，请使用 Control UI 的 Tools 面板或配置/目录界面，
而不要把 `/tools` 当作静态目录。
## 使用量界面（什么显示在哪里）
## 使用量界面（各处显示内容）
- **提供商用量/配额**（例如：“Claude 剩余 80%”）会在启用使用量跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口统一标准化为“剩余百分比”；对于 MiniMax，仅剩余量百分比字段会在显示前取反，而 `model_remains` 响应会优先使用聊天模型条目加上带模型标签的套餐标签。
- `/status` 中的**令牌/缓存行**在实时会话快照信息不足时，可能回退到最近的转录使用量条目。现有的非零实时值仍然优先，且转录回退也可以在存储总量缺失或更小时，恢复活动运行时模型标签以及一个更偏向提示的大总量。
- **每次响应的令牌/成本** 由 `/usage off|tokens|full` 控制（附加在正常回复后）。
- `/model status` 关注的是**模型/认证/端点**，而不是使用量。
- **提供商使用量/配额**（例如：“Claude 剩余 80%”）会在启用使用量跟踪时显示于当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口统一规范化为“剩余百分比”；对于 MiniMax，仅剩余量百分比字段会在显示前取反，而 `model_remains` 响应会优先选择聊天模型条目以及带模型标签的套餐标签。
- `/status` 中的 **token/cache 行** 在实时会话快照信息稀疏时，可以回退到最新的转录使用量条目。现有的非零实时值仍然优先，而转录回退还可以在存储总量缺失或更小时恢复活动运行时模型标签以及更大的、面向提示的总量。
- **每条响应的 token/成本** 由 `/usage off|tokens|full` 控制（附加到普通回复后）。
- `/model status` 关注的是**模型/认证/端点**，不是使用量。
## 模型选择（`/model`）
@ -252,14 +254,14 @@ Dock 命令由具有原生命令支持的渠道插件生成。当前内置集合
说明：
- `/model` 和 `/model list` 会显示一个紧凑的编号选择器（模型家族 + 可用提供商）。
- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单，以及一个提交步骤。
- `/model <#>` 会从该选择器中进行选择（并在可能时优先当前提供商）。
- `/model status` 会显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`），如果可用。
- `/model` 和 `/model list` 会显示一个紧凑的编号选择器（模型系列 + 可用提供商）。
- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单以及 Submit 步骤。
- `/model <#>` 会从该选择器中进行选择（并尽可能优先使用当前提供商）。
- `/model status` 会显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`），如果可用的话。
## 调试覆盖
## Debug 覆盖项
`/debug` 允许你设置**仅运行时**配置覆盖（内存中，不写磁盘）。仅限所有者。默认禁用；使用 `commands.debug: true` 启用。
`/debug` 允许你设置**仅运行时**的配置覆盖项（位于内存中，不写入磁盘）。仅限所有者。默认禁用；使用 `commands.debug: true` 启用。
示例：
@ -273,12 +275,12 @@ Dock 命令由具有原生命令支持的渠道插件生成。当前内置集合
说明：
- 覆盖会立即应用于新的配置读取，但**不会**写入 `openclaw.json`。
- 使用 `/debug reset` 清除所有覆盖并返回磁盘上的配置。
- 覆盖项会立即应用于新的配置读取，但**不会**写入 `openclaw.json`。
- 使用 `/debug reset` 清除所有覆盖项，并返回到磁盘上的配置。
## 插件跟踪输出
## 插件 trace 输出
`/trace` 让你可以切换**会话作用域的插件跟踪/调试行**，而无需开启完整详细模式。
`/trace` 允许你切换**会话范围的插件 trace/debug 行**，而无需启用完整详细模式。
示例：
@ -290,16 +292,16 @@ Dock 命令由具有原生命令支持的渠道插件生成。当前内置集合
说明：
- 不带参数的 `/trace` 会显示当前会话的跟踪状态。
- `/trace on` 会为当前会话启用插件跟踪行。
- 不带参数的 `/trace` 会显示当前会话的 trace 状态。
- `/trace on` 为当前会话启用插件 trace 行。
- `/trace off` 会再次将其关闭。
- 插件跟踪行可能出现在 `/status` 中，也可能在正常助手回复之后作为后续诊断消息出现。
- `/trace` 不能替代 `/debug`；`/debug` 仍用于管理仅运行时的配置覆盖。
- `/trace` 不能替代 `/verbose`；常规详细工具/状态输出仍归属于 `/verbose`。
- 插件 trace 行可以出现在 `/status` 中，也可以在普通助手回复之后作为一条后续诊断消息出现。
- `/trace` 不能替代 `/debug`；`/debug` 仍用于管理仅运行时的配置覆盖项。
- `/trace` 不能替代 `/verbose`；普通的详细工具/状态输出仍属于 `/verbose`。
## 配置更新
`/config` 会写入你的磁盘配置（`openclaw.json`）。仅限所有者。默认禁用；使用 `commands.config: true` 启用。
`/config` 会写入你磁盘上的配置（`openclaw.json`）。仅限所有者。默认禁用；使用 `commands.config: true` 启用。
示例：
@ -313,12 +315,12 @@ Dock 命令由具有原生命令支持的渠道插件生成。当前内置集合
说明：
- 写入前会验证配置；无效更改会被拒绝。
- 写入前会对配置进行验证；无效更改会被拒绝。
- `/config` 更新会在重启后保留。
## MCP 更新
`/mcp` 会将由 OpenClaw 管理的 MCP 服务器定义写入 `mcp.servers` 下。仅限所有者。默认禁用；使用 `commands.mcp: true` 启用。
`/mcp` 会将 OpenClaw 管理的 MCP 服务器定义写入 `mcp.servers` 下。仅限所有者。默认禁用；使用 `commands.mcp: true` 启用。
示例：
@ -331,12 +333,12 @@ Dock 命令由具有原生命令支持的渠道插件生成。当前内置集合
说明：
- `/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 所拥有的项目设置中。
- 运行时适配器决定哪些传输方式实际上可执行。
- `/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 自有项目设置中。
- 运行时适配器决定哪些传输实际上可执行。
## 插件更新
`/plugins` 允许操作员检查已发现的插件，并在配置中切换启用状态。只读流程可使用 `/plugin` 作为别名。默认禁用；使用 `commands.plugins: true` 启用。
`/plugins` 允许操作员检查已发现的插件，并在配置中切换启用状态。只读流程可以使用 `/plugin` 作为别名。默认禁用；使用 `commands.plugins: true` 启用。
示例：
@ -350,20 +352,20 @@ Dock 命令由具有原生命令支持的渠道插件生成。当前内置集合
说明：
- `/plugins list` 和 `/plugins show` 会针对当前工作区加磁盘配置执行真实的插件发现。
- `/plugins enable|disable` 只更新插件配置；它不会安装或卸载插件。
- 在启用/禁用更改后，重启网关以应用这些更改。
- `/plugins list` 和 `/plugins show` 会基于当前工作区和磁盘上的配置执行真实的插件发现。
- `/plugins enable|disable` 只会更新插件配置；不会安装或卸载插件。
- 启用/禁用变更后，请重启 gateway 以使其生效。
## 界面说明
- **文本命令** 在正常聊天会话中运行（私信共享 `main`，群组有各自独立的会话）。
- **文本命令** 在普通聊天会话中运行（私信共享 `main`，群组有各自的会话）。
- **原生命令** 使用隔离会话：
- Discord：`agent:<agentId>:discord:slash:<userId>`
- Slack：`agent:<agentId>:slack:slash:<userId>`（前缀可通过 `channels.slack.slashCommand.sessionPrefix` 配置）
- Telegram：`telegram:slash:<userId>`（通过 `CommandTargetSessionKey` 指向聊天会话）
- **`/stop`** 以活动聊天会话为目标，因此它可以中止当前运行。
- **Slack：** 仍然支持 `channels.slack.slashCommand`，用于单个 `/openclaw` 风格命令。如果你启用 `commands.native`，则必须为每个内置命令创建一个 Slack 斜杠命令（名称与 `/help` 等相同）。Slack 的命令参数菜单会以临时 Block Kit 按钮的形式发送。
- Slack 原生命令例外：请注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本形式的 `/status` 在 Slack 消息中仍然可用。
- **Slack：** `channels.slack.slashCommand` 仍支持用于单个 `/openclaw` 风格命令。如果你启用了 `commands.native`，则必须为每个内置命令创建一个 Slack slash command（名称与 `/help` 等相同）。Slack 的命令参数菜单会以临时的 Block Kit 按钮形式传递。
- Slack 原生命令例外：请注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本版 `/status` 在 Slack 消息中仍然可用。
## BTW 旁支问题
@ -371,13 +373,14 @@ Dock 命令由具有原生命令支持的渠道插件生成。当前内置集合
与普通聊天不同：
- 它使用当前会话作为背景上下文，
- 它以一个单独的**无工具**一次性调用运行，
- 它不会改变后续会话上下文，
- 它会使用当前会话作为背景上下文，
- 它会以单独的**无工具**一次性调用运行，
- 它不会改变未来会话上下文，
- 它不会写入转录历史，
- 它会作为实时旁支结果传递，而不是普通助手消息。
- 它会以实时旁支结果的形式交付，而不是普通助手消息。
这使得 `/btw` 在你希望获得临时澄清而主任务继续进行时非常有用。
这使得 `/btw` 在你希望主任务继续进行的同时，
临时获得一个澄清时非常有用。
示例：
@ -385,4 +388,4 @@ Dock 命令由具有原生命令支持的渠道插件生成。当前内置集合
/btw what are we doing right now?
```
完整行为和客户端 UX 细节请参见 [BTW Side Questions](/zh-CN/tools/btw)。
完整行为和客户端 UX 细节请参见 [BTW 旁支问题](/zh-CN/tools/btw)。

7
docs/zh-CN/tts.md
View File

@ -1,13 +1,14 @@
---
redirect: /tools/tts
summary: 重定向到 /tools/tts
title: 文本转语音
x-i18n:
generated_at: "2026-04-06T15:31:37Z"
generated_at: "2026-04-23T06:44:08Z"
model: gpt-5.4
provider: openai
source_hash: 0c9ace272aa9adff93c946ee6275f6eb314dc1fa5043e0a26ecb164c990c0c59
source_hash: 87d5df4216805bde41fb099e4fc7ec97a82658cdbd80cc1224dd9fee81c49abf
source_path: tts.md
workflow: 15
---
此页面已迁移至 [文本转语音](/zh-CN/tools/tts)。
此页面已移至 [文本转语音](/zh-CN/tools/tts)。

300
docs/zh-CN/web/control-ui.md
View File

@ -1,26 +1,26 @@
---
read_when:
- 你想要通过浏览器操作 Gateway 网关
- 你想要无需 SSH 隧道即可通过 Tailnet 访问
summary: Gateway 网关的基于浏览器的控制 UI（聊天、节点、配置）
title: 控制 UI
- 你希望通过浏览器操作 Gateway 网关
- 你希望在不使用 SSH 隧道的情况下通过 Tailnet 访问
summary: 基于浏览器的 Gateway 网关控制 UI（聊天、节点、配置）
title: Control UI
x-i18n:
generated_at: "2026-04-23T06:18:41Z"
generated_at: "2026-04-23T06:44:13Z"
model: gpt-5.4
provider: openai
source_hash: 63e3dbba6b05a5e00499fbe75e6a66a89e0b6b3d9d66e69143068e087f517b8a
source_hash: 05c5a1b9c0527d230b1657e15b1adf681817d279128af8197a14eb9bdde3d211
source_path: web/control-ui.md
workflow: 15
---
# 控制 UI（浏览器）
# Control UI（浏览器）
控制 UI 是一个由 Gateway 网关提供的小型 **Vite + Lit** 单页应用：
Control UI 是一个由 Gateway 网关提供的小型 **Vite + Lit** 单页应用：
- 默认：`http://<host>:18789/`
- 可选前缀：设置 `gateway.controlUi.basePath`（例如 `/openclaw`）
它会在同一端口上**直接与 Gateway 网关 WebSocket 通信**。
它会**直接连接到同一端口上的 Gateway 网关 WebSocket**。
## 快速打开（本地）
@ -28,30 +28,24 @@ x-i18n:
- [http://127.0.0.1:18789/](http://127.0.0.1:18789/)（或 [http://localhost:18789/](http://localhost:18789/)）
如果页面无法加载，请先启动 Gateway 网关：`openclaw gateway`。
如果页面加载失败，请先启动 Gateway 网关：`openclaw gateway`。
认证会在 WebSocket 握手期间通过以下方式提供：
身份验证会在 WebSocket 握手期间通过以下方式提供：
- `connect.params.auth.token`
- `connect.params.auth.password`
- 当 `gateway.auth.allowTailscale: true` 时使用 Tailscale Serve 身份标头
- 当 `gateway.auth.mode: "trusted-proxy"` 时使用 trusted-proxy 身份标头
- 当 `gateway.auth.allowTailscale: true` 时使用 Tailscale Serve 身份请求头
- 当 `gateway.auth.mode: "trusted-proxy"` 时使用受信任代理身份请求头
仪表板设置面板会为当前浏览器标签页会话
和所选 gateway URL 保存一个 token；密码不会持久化。新手引导通常会在首次连接时
生成一个用于共享密钥认证的 gateway token，但当 `gateway.auth.mode` 为 `"password"` 时，
密码认证也同样可用。
仪表板设置面板会为当前浏览器标签页会话和所选 Gateway 网关 URL 保留一个 token；密码不会被持久化。新手引导通常会在首次连接时为共享密钥身份验证生成一个 Gateway 网关 token，但当 `gateway.auth.mode` 为 `"password"` 时，也可以使用密码身份验证。
## 设备配对（首次连接）
当你从新的浏览器或设备连接到控制 UI 时，Gateway 网关
会要求进行**一次性配对批准**——即使你位于同一个 Tailnet 上，
且 `gateway.auth.allowTailscale: true` 也是如此。这是一项安全措施，
用于防止未经授权的访问。
当你从新的浏览器或设备连接到 Control UI 时，Gateway 网关会要求一次**一次性配对批准**——即使你位于同一个 Tailnet 中，并且设置了 `gateway.auth.allowTailscale: true` 也是如此。这是一项安全措施，用于防止未授权访问。
**你会看到：** “disconnected (1008): pairing required”
**批准设备：**
**批准该设备：**
```bash
# 列出待处理请求
@ -61,106 +55,91 @@ openclaw devices list
openclaw devices approve <requestId>
```
如果浏览器在配对重试时更改了认证详情（role / scopes / public
key），之前的待处理请求会被替换，并创建新的 `requestId`。
请在批准前重新运行 `openclaw devices list`。
如果浏览器在更改了身份验证详情（角色/作用域/公钥）后重试配对，之前的待处理请求会被替换，并生成新的 `requestId`。批准前请重新运行 `openclaw devices list`。
如果浏览器已经完成配对，而你将其从只读访问更改为
写入 / 管理访问，这会被视为批准升级，而不是静默重连。
OpenClaw 会保持原有批准继续生效，阻止更宽泛权限的重连，
并要求你显式批准新的作用域集合。
如果浏览器已经配对，而你将其从只读访问更改为写入/管理员访问，这会被视为一次权限升级批准，而不是静默重连。OpenClaw 会保持旧批准有效，阻止权限更高的重连，并要求你显式批准新的作用域集合。
一旦批准，设备就会被记住，除非你使用 `openclaw devices revoke --device <id> --role <role>` 撤销它，
否则无需再次批准。关于 token 轮换和撤销，请参见
[Devices CLI](/zh-CN/cli/devices)。
一旦获批，该设备会被记住，除非你使用 `openclaw devices revoke --device <id> --role <role>` 撤销它，否则无需再次批准。有关 token 轮换和撤销，请参见 [Devices CLI](/zh-CN/cli/devices)。
**说明：**
- 直接的本地 local loopback 浏览器连接（`127.0.0.1` / `localhost`）会
自动批准。
- Tailnet 和 LAN 浏览器连接仍然需要显式批准，即使
它们来自同一台机器。
- 每个浏览器配置文件都会生成唯一的设备 ID，因此切换浏览器或
清除浏览器数据都需要重新配对。
- 直接本地 local loopback 浏览器连接（`127.0.0.1` / `localhost`）会自动获批。
- Tailnet 和 LAN 浏览器连接即使来自同一台机器，仍然需要显式批准。
- 每个浏览器配置文件都会生成唯一的设备 ID，因此切换浏览器或清除浏览器数据后都需要重新配对。
## 语言支持
控制 UI 可以在首次加载时根据你的浏览器语言环境进行本地化。
如果之后想覆盖它，请打开 **Overview -> Gateway Access -> Language**。该
语言选择器位于 Gateway Access 卡片中，而不在 Appearance 下。
Control UI 可在首次加载时根据你的浏览器区域设置进行本地化。若要之后覆盖它，请打开 **Overview -> Gateway Access -> Language**。语言选择器位于 Gateway Access 卡片中，而不在 Appearance 下。
- 支持的语言环境：`en`、`zh-CN`、`zh-TW`、`pt-BR`、`de`、`es`、`ja-JP`、`ko`、`fr`、`tr`、`uk`、`id`、`pl`
- 非英语翻译会在浏览器中按需延迟加载。
- 所选语言环境会保存在浏览器存储中，并在后续访问时复用。
- 缺失的翻译键会回退为英语。
- 支持的区域设置：`en`、`zh-CN`、`zh-TW`、`pt-BR`、`de`、`es`、`ja-JP`、`ko`、`fr`、`tr`、`uk`、`id`、`pl`、`th`
- 非英语翻译会在浏览器中按需懒加载。
- 所选区域设置会保存到浏览器存储中，并在后续访问时复用。
- 缺失的翻译键会回退到英语。
## 当前可执行的操作
- 通过 Gateway 网关 WS 与模型聊天（`chat.history`、`chat.send`、`chat.abort`、`chat.inject`）
- 在聊天中流式显示工具调用 + 实时工具输出卡片（智能体事件）
- 渠道：内置渠道以及内置 / 外部渠道插件的状态、QR 登录和每渠道配置（`channels.status`、`web.login.*`、`config.patch`）
- 实例：在线列表 + 刷新（`system-presence`）
- 会话：列表 + 每会话模型 / thinking / fast / verbose / trace / reasoning 覆盖（`sessions.list`、`sessions.patch`）
- Dreams：dreaming 状态、启用 / 禁用切换和 Dream Diary 阅读器（`doctor.memory.status`、`doctor.memory.dreamDiary`、`config.patch`）
- Cron 作业：列出 / 添加 / 编辑 / 运行 / 启用 / 禁用 + 运行历史（`cron.*`）
- Skills：状态、启用 / 禁用、安装、API key 更新（`skills.*`）
- 在 Chat 中流式显示工具调用 + 实时工具输出卡片（智能体事件）
- Channels：内置以及内置/外部渠道插件状态、QR 登录和按渠道配置（`channels.status`、`web.login.*`、`config.patch`）
- 实例：在线状态列表 + 刷新（`system-presence`）
- Sessions：列表 + 按会话覆盖 model/thinking/fast/verbose/trace/reasoning（`sessions.list`、`sessions.patch`）
- Dreams：Dreaming 状态、启用/禁用开关，以及 Dream Diary 阅读器（`doctor.memory.status`、`doctor.memory.dreamDiary`、`config.patch`）
- Cron 作业：列出/添加/编辑/运行/启用/禁用 + 运行历史（`cron.*`）
- Skills：状态、启用/禁用、安装、API 密钥更新（`skills.*`）
- 节点：列表 + 能力（`node.list`）
- 执行批准权限：编辑 gateway 或节点允许列表 + `exec host=gateway/node` 的询问策略（`exec.approvals.*`）
- 配置：查看 / 编辑 `~/.openclaw/openclaw.json`（`config.get`、`config.set`）
- 配置：带验证的应用 + 重启（`config.apply`），并唤醒上次活动的会话
- Exec 批准：编辑 gateway 或节点 allowlist + `exec host=gateway/node` 的询问策略（`exec.approvals.*`）
- 配置：查看/编辑 `~/.openclaw/openclaw.json`（`config.get`、`config.set`）
- 配置：带验证的应用 + 重启（`config.apply`），并唤醒最后一个活跃会话
- 配置写入包含 base-hash 保护，以防覆盖并发编辑
- 配置写入（`config.set` / `config.apply` / `config.patch`）还会对所提交配置负载中的活跃 SecretRef 解析进行预检；无法解析的活跃已提交引用会在写入前被拒绝
- 配置 schema + 表单渲染（`config.schema` / `config.schema.lookup`，
包括字段 `title` / `description`、匹配的 UI 提示、直接子项
摘要、嵌套对象 / 通配符 / 数组 / 组合节点上的文档元数据，
以及可用时的 plugin + 渠道 schema）；仅当快照具备安全的原始往返能力时，
才提供 Raw JSON 编辑器
- 如果某个快照无法安全地往返原始文本，控制 UI 会强制使用 Form 模式，并为该快照禁用 Raw 模式
- 结构化 SecretRef 对象值会在表单文本输入中以只读方式呈现，以防意外将对象损坏为字符串
- 调试：status / health / models 快照 + 事件日志 + 手动 RPC 调用（`status`、`health`、`models.list`）
- 日志：带筛选 / 导出的 gateway 文件日志实时 tail（`logs.tail`）
- 更新：运行 package / git 更新 + 重启（`update.run`），并附带重启报告
- 配置写入（`config.set`/`config.apply`/`config.patch`）还会在写入前，对已提交配置负载中的活动 SecretRef 执行预检解析；无法解析的活动已提交引用会在写入前被拒绝
- 配置模式 + 表单渲染（`config.schema` / `config.schema.lookup`，
包括字段 `title` / `description`、匹配的 UI 提示、直接子项摘要、嵌套对象/通配符/数组/组合节点上的文档元数据，
以及可用时的插件 + 渠道模式）；仅当快照具备安全的原始往返能力时，才提供 Raw JSON 编辑器
- 如果某个快照无法安全地进行原始文本往返，Control UI 会强制使用 Form 模式，并对该快照禁用 Raw 模式
- 结构化 SecretRef 对象值会在表单文本输入中以只读方式渲染，以防意外将对象破坏成字符串
- 调试：状态/健康/模型快照 + 事件日志 + 手动 RPC 调用（`status`、`health`、`models.list`）
- 日志：Gateway 网关文件日志实时 tail，支持筛选/导出（`logs.tail`）
- 更新：执行包/git 更新 + 重启（`update.run`），并附带重启报告
Cron 作业面板说明：
- 对于隔离作业，投递默认是播报摘要。如果你希望仅供内部运行，可以切换为 none。
- 选择 announce 时，会显示 channel / target 字段。
- Webhook 模式使用 `delivery.mode = "webhook"`，并将 `delivery.to` 设置为有效的 HTTP(S) webhook URL。
- 对于隔离作业，投递默认是公告摘要。如果你只想内部运行，可以切换为 none。
- 当选择 announce 时，会显示渠道/目标字段。
- webhook 模式使用 `delivery.mode = "webhook"`，并将 `delivery.to` 设置为有效的 HTTP(S) webhook URL。
- 对于主会话作业，可使用 webhook 和 none 投递模式。
- 高级编辑控件包括运行后删除、清除智能体覆盖、cron 精确 / 错峰选项、
智能体 model / thinking 覆盖，以及尽力投递切换。
- 表单验证为内联字段级错误；在修复前，无效值会禁用保存按钮。
- 设置 `cron.webhookToken` 可发送专用 bearer token；如果省略，webhook 将在无 auth 标头的情况下发送。
- 已弃用的回退：已存储的旧版作业若带有 `notify: true`，在迁移前仍可使用 `cron.webhook`。
- 高级编辑控件包括运行后删除、清除智能体覆盖、cron 精确/错峰选项、
智能体 model/thinking 覆盖，以及尽力投递开关。
- 表单验证为内联方式，并显示字段级错误；无效值会禁用保存按钮，直到修复。
- 设置 `cron.webhookToken` 可发送专用 bearer token；若省略，则发送 webhook 时不带身份验证请求头。
- 已弃用的回退：已存储的旧作业若带有 `notify: true`，在迁移前仍可使用 `cron.webhook`。
## 聊天行为
- `chat.send` 是**非阻塞**的：它会立即以 `{ runId, status: "started" }` 确认，响应则通过 `chat` 事件流式返回。
- `chat.send` 是**非阻塞**的：它会立即确认并返回 `{ runId, status: "started" }`，响应则通过 `chat` 事件流式返回。
- 使用相同的 `idempotencyKey` 重新发送时，运行中会返回 `{ status: "in_flight" }`，完成后返回 `{ status: "ok" }`。
- `chat.history` 响应有大小上限，以确保 UI 安全。当转录条目过大时，Gateway 网关可能会截断长文本字段、省略重量级元数据块，并用占位符替换超大消息（`[chat.history omitted: message too large]`）。
- `chat.history` 还会从可见的助手文本中移除仅用于显示的内联指令标签（例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`）、纯文本工具调用 XML 负载（包括 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>` 以及被截断的工具调用块）、以及泄露的 ASCII / 全角模型控制 token，并省略那些其全部可见文本仅为精确静默 token `NO_REPLY` / `no_reply` 的助手条目。
- `chat.inject` 会向会话转录追加一条助手备注，并广播 `chat` 事件用于仅 UI 更新（不会触发智能体运行，也不会向渠道投递）。
- 聊天头部的 model 和 thinking 选择器会立即通过 `sessions.patch` 修改当前活动会话；它们是持久化的会话覆盖，而不是只针对单轮发送的选项。
- `chat.history` 响应有大小限制，以保障 UI 安全。当转录条目过大时，Gateway 网关可能会截断长文本字段、省略体积较大的元数据块，并用占位符替换超大消息（`[chat.history omitted: message too large]`）。
- `chat.history` 还会从可见助手文本中剥离仅用于显示的内联指令标签（例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`）、纯文本工具调用 XML 负载（包括 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>` 以及被截断的工具调用块），并移除泄露出的 ASCII/全角模型控制 token；同时会省略那些完整可见文本仅为精确静默 token `NO_REPLY` / `no_reply` 的助手条目。
- `chat.inject` 会向会话转录追加一条助手说明，并广播一个 `chat` 事件用于仅 UI 更新（不会触发智能体运行，也不会进行渠道投递）。
- 聊天头部的 model 和 thinking 选择器会通过 `sessions.patch` 立即修补当前活跃会话；它们是持久化的会话覆盖，而不是单轮发送选项。
- 停止：
- 点击 **Stop**（调用 `chat.abort`）
- 输入 `/stop`（或独立的中止短语，例如 `stop`、`stop action`、`stop run`、`stop openclaw`、`please stop`）以进行带外中止
- `chat.abort` 支持 `{ sessionKey }`（无需 `runId`）来中止该会话的所有活动运行
- 输入 `/stop`（或独立的中止短语，如 `stop`、`stop action`、`stop run`、`stop openclaw`、`please stop`）以带外中止
- `chat.abort` 支持 `{ sessionKey }`（无需 `runId`），可中止该会话的所有活跃运行
- 中止后的部分保留：
- 当某次运行被中止时，部分助手文本仍然可以在 UI 中显示
- 当存在缓冲输出时，Gateway 网关会将中止时的部分助手文本持久化到转录历史中
- 持久化条目包含中止元数据，以便转录消费者能够区分中止的部分输出和正常完成输出
- 当某次运行被中止时，部分助手文本仍可能显示在 UI 中
- 如果存在缓冲输出，Gateway 网关会将被中止的部分助手文本持久化到转录历史中
- 持久化条目包含中止元数据，以便转录消费者区分中止产生的部分文本和正常完成输出
## 托管嵌入
## 托管 embed
助手消息可以通过 `[embed ...]`
短代码以内联方式渲染托管的网页内容。iframe 沙箱策略由
短代码以内联方式渲染托管网页内容。iframe 沙箱策略由
`gateway.controlUi.embedSandbox` 控制：
- `strict`：禁用托管嵌入中的脚本执行
- `scripts`：允许交互式嵌入，同时保持源隔离；这是
默认值，通常足以支持自包含的浏览器游戏 / 小部件
- `trusted`：在 `allow-scripts` 之上额外添加 `allow-same-origin`，用于同站点
且确实需要更高权限的文档
- `strict`：禁止在托管 embed 中执行脚本
- `scripts`：允许交互式 embed，同时保持源隔离；这是
默认值，通常足以满足自包含的浏览器游戏/小部件
- `trusted`：在 `allow-scripts` 基础上再添加 `allow-same-origin`，适用于有意需要更高权限的同站文档
示例：
@ -174,19 +153,19 @@ Cron 作业面板说明：
}
```
仅当被嵌入文档确实需要 same-origin
行为时才使用 `trusted`。对于大多数智能体生成的游戏和交互式画布，`scripts` 是
仅当嵌入文档确实需要同源行为时才使用 `trusted`。
对于大多数由智能体生成的游戏和交互式 canvas，`scripts` 是
更安全的选择。
绝对外部 `http(s)` 嵌入 URL 默认仍会被阻止。如果你
确实希望加载第三方页面形式的 `[embed url="https://..."]`，请设置
默认情况下，绝对外部 `http(s)` embed URL 仍会被阻止。如果你
确实希望 `[embed url="https://..."]` 加载第三方页面，请设置
`gateway.controlUi.allowExternalEmbedUrls: true`。
## Tailnet 访问（推荐）
### 集成的 Tailscale Serve（首选）
### 集成 Tailscale Serve（首选）
让 Gateway 网关保持在 loopback 上，并让 Tailscale Serve 使用 HTTPS 代理它：
让 Gateway 网关保持绑定在 loopback 上，并由 Tailscale Serve 通过 HTTPS 代理它：
```bash
openclaw gateway --tailscale serve
@ -196,21 +175,13 @@ openclaw gateway --tailscale serve
- `https://<magicdns>/`（或你配置的 `gateway.controlUi.basePath`）
默认情况下，当 `gateway.auth.allowTailscale` 为 `true` 时，控制 UI / WebSocket Serve 请求
可以通过 Tailscale 身份标头
（`tailscale-user-login`）进行认证。OpenClaw
会通过使用 `tailscale whois` 解析 `x-forwarded-for` 地址
并将其与该标头进行匹配来验证身份，而且只有当
请求携带 Tailscale 的 `x-forwarded-*` 标头并命中 loopback 时才会接受这些身份。设置
`gateway.auth.allowTailscale: false` 可在 Serve 流量场景下也强制要求显式共享密钥
凭证。然后使用 `gateway.auth.mode: "token"` 或
默认情况下，当 `gateway.auth.allowTailscale` 为 `true` 时，Control UI/WebSocket Serve 请求可以通过 Tailscale 身份请求头
（`tailscale-user-login`）完成身份验证。OpenClaw
会通过 `tailscale whois` 解析 `x-forwarded-for` 地址并与该请求头匹配来验证身份，并且仅在请求通过 Tailscale 的 `x-forwarded-*` 请求头命中 loopback 时接受这些请求。若你希望即使对于 Serve 流量也要求显式共享密钥凭证，请设置
`gateway.auth.allowTailscale: false`。然后使用 `gateway.auth.mode: "token"` 或
`"password"`。
对于该异步 Serve 身份路径，来自同一客户端 IP
和同一 auth 作用域的失败认证尝试会在写入速率限制前被串行化处理。
因此，同一浏览器的并发错误重试在第二次请求时可能会显示 `retry later`，
而不是两个普通不匹配并行竞争。
无 token 的 Serve 认证假定 gateway 主机是可信的。如果该主机上
可能运行不受信任的本地代码，请要求使用 token / password 认证。
对于该异步 Serve 身份路径，来自同一客户端 IP 和相同身份验证作用域的失败身份验证尝试，会在写入限流数据之前串行化处理。因此，同一浏览器的并发错误重试在第二次请求时可能会显示 `retry later`，而不是出现两个并行竞争的普通不匹配。
无 token 的 Serve 身份验证假设 Gateway 网关主机是可信的。如果该主机上可能运行不可信本地代码，请要求使用 token/password 身份验证。
### 绑定到 tailnet + token
@ -227,22 +198,22 @@ openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
## 不安全的 HTTP
如果你通过普通 HTTP 打开仪表板（`http://<lan-ip>` 或 `http://<tailscale-ip>`），
如果你通过纯 HTTP 打开仪表板（`http://<lan-ip>` 或 `http://<tailscale-ip>`），
浏览器会运行在**非安全上下文**中，并阻止 WebCrypto。默认情况下，
OpenClaw 会**阻止**没有设备身份的控制 UI 连接。
OpenClaw 会**阻止**没有设备身份的 Control UI 连接。
有文档说明的例外情况：
文档化的例外情况：
- 仅 localhost 的不安全 HTTP 兼容模式，使用 `gateway.controlUi.allowInsecureAuth=true`
- 通过 `gateway.auth.mode: "trusted-proxy"` 成功完成 operator 控制 UI 认证
- 应急开关 `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
- 仅限 localhost 的不安全 HTTP 兼容模式：`gateway.controlUi.allowInsecureAuth=true`
- 通过 `gateway.auth.mode: "trusted-proxy"` 成功进行的操作员 Control UI 身份验证
- 紧急兜底：`gateway.controlUi.dangerouslyDisableDeviceAuth=true`
**推荐修复方式：** 使用 HTTPS（Tailscale Serve）或在本地打开 UI：
- `https://<magicdns>/`（Serve）
- `http://127.0.0.1:18789/`（在 gateway 主机上）
**不安全认证开关行为：**
**不安全身份验证开关行为：**
```json5
{
@ -254,14 +225,14 @@ OpenClaw 会**阻止**没有设备身份的控制 UI 连接。
}
```
`allowInsecureAuth` 只是本地兼容性开关：
`allowInsecureAuth` 仅是一个本地兼容性开关：
- 它允许 localhost 控制 UI 会话在非安全 HTTP 上下文中
无需设备身份即可继续。
- 它允许 localhost 的 Control UI 会话在非安全 HTTP 上下文中，
无需设备身份即可继续进行。
- 它不会绕过配对检查。
- 它不会放宽远程（非 localhost）设备身份要求。
**仅限应急使用：**
**仅限紧急兜底：**
```json5
{
@ -273,56 +244,56 @@ OpenClaw 会**阻止**没有设备身份的控制 UI 连接。
}
```
`dangerouslyDisableDeviceAuth` 会禁用控制 UI 的设备身份检查，这是一次
严重的安全降级。请在紧急使用后尽快恢复。
`dangerouslyDisableDeviceAuth` 会禁用 Control UI 设备身份检查，是一种
严重的安全降级。紧急使用后请尽快恢复。
trusted-proxy 说明：
受信任代理说明：
- 成功的 trusted-proxy 认证可以允许**operator** 控制 UI 会话在无
- 成功的 trusted-proxy 身份验证可以让**操作员** Control UI 会话在没有
设备身份的情况下接入
- 这**不**适用于 node 角色的控制 UI 会话
- 同一主机上的 loopback 反向代理仍然不能满足 trusted-proxy 认证；参见
- 这**不**适用于 node-role 的 Control UI 会话
- 同一主机上的 loopback 反向代理仍然不能满足 trusted-proxy 身份验证；请参见
[Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)
有关 HTTPS 设置指南，请参见 [Tailscale](/zh-CN/gateway/tailscale)。
有关 HTTPS 设置指导，请参见 [Tailscale](/zh-CN/gateway/tailscale)。
## 内容安全策略
控制 UI 内置了严格的 `img-src` 策略：仅允许**同源**资源和 `data:` URL。远程 `http(s)` 和协议相对图片 URL 会被浏览器拒绝，并且不会发起网络请求。
Control UI 采用严格的 `img-src` 策略：只允许**同源**资源和 `data:` URL。远程 `http(s)` 和协议相对图片 URL 会被浏览器拒绝，也不会发起网络请求。
这在实践中的含义是：
这在实际中的含义：
- 通过相对路径提供的头像和图片（例如 `/avatars/<id>`）仍可正常渲染。
- 内联 `data:image/...` URL 仍可正常渲染（这对协议内负载很有用）。
- 渠道元数据输出的远程头像 URL 会在控制 UI 的头像辅助函数中被剥离，并替换为内置 logo / badge，因此即使某个渠道被攻破或存在恶意行为，也无法强制 operator 浏览器任意抓取远程图片。
- 内联 `data:image/...` URL 仍可正常渲染（对协议内负载很有用）。
- 渠道元数据输出的远程头像 URL 会在 Control UI 的头像辅助函数中被剥离，并替换为内置 logo/badge，因此即使某个渠道被攻破或存在恶意行为，也无法强制操作员浏览器任意拉取远程图片。
你无需做任何改动即可获得该行为——它始终启用，且不可配置。
你无需进行任何更改即可获得此行为——它始终开启，且不可配置。
## 头像路由认证
## 头像路由身份验证
当 gateway 认证已配置时，控制 UI 头像端点需要与其余 API 相同的 gateway token：
当配置了 Gateway 网关身份验证时，Control UI 的头像端点要求使用与其余 API 相同的 Gateway 网关 token：
- `GET /avatar/<agentId>` 仅向已认证调用方返回头像图片。`GET /avatar/<agentId>?meta=1` 在同样规则下返回头像元数据。
- 对任一路由的未认证请求都会被拒绝（与同级 assistant-media 路由保持一致）。这可防止头像路由在本应受到保护的主机上泄露智能体身份。
- 控制 UI 本身在拉取头像时会将 gateway token 作为 bearer 标头转发，并使用已认证的 blob URL，因此图片仍可在仪表板中渲染。
- `GET /avatar/<agentId>` 仅向已通过身份验证的调用者返回头像图片。`GET /avatar/<agentId>?meta=1` 也会在相同规则下返回头像元数据。
- 对这两个路由的未认证请求都会被拒绝（与相邻的 assistant-media 路由保持一致）。这可以防止头像路由在其他部分已受保护的主机上泄露智能体身份。
- Control UI 本身在获取头像时会将 Gateway 网关 token 作为 bearer 请求头转发，并使用已认证的 blob URL，因此图片仍能在仪表板中正常渲染。
如果你禁用了 gateway 认证（不建议在共享主机上这样做），则头像路由也会与 gateway 其余部分保持一致，变为无需认证。
如果你禁用了 Gateway 网关身份验证（不建议在共享主机上这样做），则头像路由也会像网关其余部分一样变为无身份验证。
## 构建 UI
Gateway 网关会从 `dist/control-ui` 提供静态文件。使用以下命令构建：
Gateway 网关会从 `dist/control-ui` 提供静态文件。请使用以下命令构建：
```bash
pnpm ui:build
```
可选的绝对 base（当你希望使用固定资源 URL 时）：
可选的绝对 base（当你想要固定资源 URL 时）：
```bash
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
```
用于本地开发（独立开发服务器）：
用于本地开发（独立 dev server）：
```bash
pnpm ui:dev
@ -330,20 +301,20 @@ pnpm ui:dev
然后将 UI 指向你的 Gateway 网关 WS URL（例如 `ws://127.0.0.1:18789`）。
## 调试 / 测试：开发服务器 + 远程 Gateway 网关
## 调试/测试：dev server + 远程 Gateway 网关
控制 UI 是静态文件；WebSocket 目标可配置，并且可以
不同于 HTTP 源。当你希望在本地运行 Vite 开发服务器、
而 Gateway 网关运行在其他位置时，这会非常方便。
Control UI 是静态文件；WebSocket 目标可配置，并且可以
与 HTTP 源不同。当你想在本地运行 Vite dev server，
但 Gateway 网关运行在别处时，这非常有用。
1. 启动 UI 开发服务器：`pnpm ui:dev`
1. 启动 UI dev server：`pnpm ui:dev`
2. 打开如下 URL：
```text
http://localhost:5173/?gatewayUrl=ws://<gateway-host>:18789
```
可选的一次性认证（如果需要）：
可选的一次性身份验证（如需要）：
```text
http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-token>
@ -351,20 +322,19 @@ http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-toke
说明：
- `gatewayUrl` 会在加载后存储到 localStorage 中，并从 URL 中移除。
- `token` 应尽可能通过 URL 片段（`#token=...`）传递。片段不会发送到服务器，因此可避免请求日志和 Referer 泄露。旧版 `?token=` 查询参数仍会出于兼容性被一次性导入，但仅作为回退，并会在引导后立即移除。
- `gatewayUrl` 会在加载后存入 localStorage，并从 URL 中移除。
- `token` 应尽可能通过 URL 片段（`#token=...`）传递。片段不会发送到服务器，因此可避免请求日志和 Referer 泄露。旧版 `?token=` 查询参数为了兼容仍会导入一次，但仅作为回退使用，并会在 bootstrap 后立即剥离。
- `password` 仅保存在内存中。
- 设置 `gatewayUrl` 后，UI 不会回退到配置或环境变量凭证。
请显式提供 `token`（或 `password`）。缺少显式凭证会报错。
- 当 Gateway 网关位于 TLS 后方时（Tailscale Serve、HTTPS 代理等），请使用 `wss://`。
- 当设置了 `gatewayUrl` 时，UI 不会回退到配置或环境凭证。
请显式提供 `token`（或 `password`）。如果缺少显式凭证，会报错。
- 当 Gateway 网关位于 TLS 后面时（Tailscale Serve、HTTPS 代理等），请使用 `wss://`。
- `gatewayUrl` 仅在顶层窗口中接受（不能嵌入），以防止点击劫持。
- 非 loopback 的控制 UI 部署必须显式设置 `gateway.controlUi.allowedOrigins`
（完整 origin）。这也包括远程开发环境设置。
- 除非是受到严格控制的
本地测试，否则不要使用 `gateway.controlUi.allowedOrigins: ["*"]`。它表示允许任意浏览器源，而不是“匹配我
当前使用的任意主机”。
- 非 loopback 的 Control UI 部署必须显式设置 `gateway.controlUi.allowedOrigins`
（完整 origin）。这也包括远程开发设置。
- 除非是在严格受控的本地测试中，否则不要使用 `gateway.controlUi.allowedOrigins: ["*"]`。
这表示允许任意浏览器 origin，而不是“匹配我正在使用的任意主机”。
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用
Host 标头 origin 回退模式，但这是一种危险的安全模式。
Host 请求头 origin 回退模式，但这是危险的安全模式。
示例：
@ -378,11 +348,11 @@ http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-toke
}
```
远程访问设置详情：[Remote access](/zh-CN/gateway/remote)。
远程访问设置详情： [远程访问](/zh-CN/gateway/remote)。
## 相关内容
- [Dashboard](/zh-CN/web/dashboard) —— gateway 仪表板
- [WebChat](/zh-CN/web/webchat) —— 基于浏览器的聊天界面
- [TUI](/zh-CN/web/tui) —— 终端用户界面
- [Health Checks](/zh-CN/gateway/health) —— gateway 健康监控
- [Dashboard](/zh-CN/web/dashboard) — Gateway 网关仪表板
- [WebChat](/zh-CN/web/webchat) — 基于浏览器的聊天界面
- [TUI](/zh-CN/web/tui) — 终端用户界面
- [Health Checks](/zh-CN/gateway/health) — Gateway 网关健康监控