@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/automation/poll.md

@@ -0,0 +1,76 @@
+---
+read_when:
+  - 添加或修改投票支持
+  - 调试从 CLI 或 Gateway 网关发送的投票
+summary: 通过 Gateway 网关 + CLI 发送投票
+title: 投票
+x-i18n:
+  generated_at: "2026-02-03T07:43:12Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 760339865d27ec40def7996cac1d294d58ab580748ad6b32cc34d285d0314eaf
+  source_path: automation/poll.md
+  workflow: 15
+---
+
+# 投票
+
+## 支持的渠道
+
+- WhatsApp（Web 渠道）
+- Discord
+- MS Teams（Adaptive Cards）
+
+## CLI
+
+```bash
+# WhatsApp
+quantumclaw message poll --target +15555550123 \
+  --poll-question "Lunch today?" --poll-option "Yes" --poll-option "No" --poll-option "Maybe"
+quantumclaw message poll --target 123456789@g.us \
+  --poll-question "Meeting time?" --poll-option "10am" --poll-option "2pm" --poll-option "4pm" --poll-multi
+
+# Discord
+quantumclaw message poll --channel discord --target channel:123456789 \
+  --poll-question "Snack?" --poll-option "Pizza" --poll-option "Sushi"
+quantumclaw message poll --channel discord --target channel:123456789 \
+  --poll-question "Plan?" --poll-option "A" --poll-option "B" --poll-duration-hours 48
+
+# MS Teams
+quantumclaw message poll --channel msteams --target conversation:19:abc@thread.tacv2 \
+  --poll-question "Lunch?" --poll-option "Pizza" --poll-option "Sushi"
+```
+
+选项：
+
+- `--channel`：`whatsapp`（默认）、`discord` 或 `msteams`
+- `--poll-multi`：允许选择多个选项
+- `--poll-duration-hours`：仅限 Discord（省略时默认为 24）
+
+## Gateway 网关 RPC
+
+方法：`poll`
+
+参数：
+
+- `to`（字符串，必需）
+- `question`（字符串，必需）
+- `options`（字符串数组，必需）
+- `maxSelections`（数字，可选）
+- `durationHours`（数字，可选）
+- `channel`（字符串，可选，默认：`whatsapp`）
+- `idempotencyKey`（字符串，必需）
+
+## 渠道差异
+
+- WhatsApp：2-12 个选项，`maxSelections` 必须在选项数量范围内，忽略 `durationHours`。
+- Discord：2-10 个选项，`durationHours` 限制在 1-768 小时之间（默认 24）。`maxSelections > 1` 启用多选；Discord 不支持严格的选择数量限制。
+- MS Teams：Adaptive Card 投票（由 QuantumClaw 管理）。无原生投票 API；`durationHours` 被忽略。
+
+## 智能体工具（Message）
+
+使用 `message` 工具的 `poll` 操作（`to`、`pollQuestion`、`pollOption`，可选 `pollMulti`、`pollDurationHours`、`channel`）。
+
+注意：Discord 没有"恰好选择 N 个"模式；`pollMulti` 映射为多选。
+Teams 投票以 Adaptive Cards 形式渲染，需要 Gateway 网关保持在线
+以将投票记录到 `~/.quantumclaw/msteams-polls.json`。

package/docs/zh-CN/automation/troubleshooting.md

@@ -0,0 +1,8 @@
+---
+summary: 自动化故障排查：排查 cron 和 heartbeat 调度与投递问题
+title: 自动化故障排查
+---
+
+# 自动化故障排查
+
+该页面是英文文档的中文占位版本，完整内容请先参考英文版：[Automation Troubleshooting](/automation/troubleshooting)。

package/docs/zh-CN/automation/webhook.md

@@ -0,0 +1,163 @@
+---
+read_when:
+  - 添加或更改 webhook 端点
+  - 将外部系统接入 QuantumClaw
+summary: 用于唤醒和隔离智能体运行的 Webhook 入口
+title: Webhooks
+x-i18n:
+  generated_at: "2026-02-03T07:43:23Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: f26b88864567be82366b1f66a4772ef2813c7846110c62fce6caf7313568265e
+  source_path: automation/webhook.md
+  workflow: 15
+---
+
+# Webhooks
+
+Gateway 网关可以暴露一个小型 HTTP webhook 端点用于外部触发。
+
+## 启用
+
+```json5
+{
+  hooks: {
+    enabled: true,
+    token: "shared-secret",
+    path: "/hooks",
+  },
+}
+```
+
+注意事项：
+
+- 当 `hooks.enabled=true` 时，`hooks.token` 为必填项。
+- `hooks.path` 默认为 `/hooks`。
+
+## 认证
+
+每个请求必须包含 hook 令牌。推荐使用请求头：
+
+- `Authorization: Bearer <token>`（推荐）
+- `x-quantumclaw-token: <token>`
+- `?token=<token>`（已弃用；会记录警告日志，将在未来的主要版本中移除）
+
+## 端点
+
+### `POST /hooks/wake`
+
+请求体：
+
+```json
+{ "text": "System line", "mode": "now" }
+```
+
+- `text` **必填**（字符串）：事件描述（例如"收到新邮件"）。
+- `mode` 可选（`now` | `next-heartbeat`）：是否立即触发心跳（默认 `now`）或等待下一次定期检查。
+
+效果：
+
+- 为**主**会话加入一个系统事件队列
+- 如果 `mode=now`，则立即触发心跳
+
+### `POST /hooks/agent`
+
+请求体：
+
+```json
+{
+  "message": "Run this",
+  "name": "Email",
+  "sessionKey": "hook:email:msg-123",
+  "wakeMode": "now",
+  "deliver": true,
+  "channel": "last",
+  "to": "+15551234567",
+  "model": "openai/gpt-5.2-mini",
+  "thinking": "low",
+  "timeoutSeconds": 120
+}
+```
+
+- `message` **必填**（字符串）：智能体要处理的提示或消息。
+- `name` 可选（字符串）：hook 的可读名称（例如"GitHub"），用作会话摘要的前缀。
+- `sessionKey` 可选（字符串）：用于标识智能体会话的键。默认为随机的 `hook:<uuid>`。使用一致的键可以在 hook 上下文中进行多轮对话。
+- `wakeMode` 可选（`now` | `next-heartbeat`）：是否立即触发心跳（默认 `now`）或等待下一次定期检查。
+- `deliver` 可选（布尔值）：如果为 `true`，智能体的响应将发送到消息渠道。默认为 `true`。仅为心跳确认的响应会自动跳过。
+- `channel` 可选（字符串）：用于投递的消息渠道。可选值：`last`、`whatsapp`、`telegram`、`discord`、`slack`、`mattermost`（插件）、`signal`、`imessage`、`msteams`。默认为 `last`。
+- `to` 可选（字符串）：渠道的接收者标识符（例如 WhatsApp/Signal 的电话号码、Telegram 的聊天 ID、Discord/Slack/Mattermost（插件）的频道 ID、MS Teams 的会话 ID）。默认为主会话中的最后一个接收者。
+- `model` 可选（字符串）：模型覆盖（例如 `anthropic/claude-3-5-sonnet` 或别名）。如果有限制，必须在允许的模型列表中。
+- `thinking` 可选（字符串）：思考级别覆盖（例如 `low`、`medium`、`high`）。
+- `timeoutSeconds` 可选（数字）：智能体运行的最大持续时间（秒）。
+
+效果：
+
+- 运行一个**隔离的**智能体回合（独立的会话键）
+- 始终在**主**会话中发布摘要
+- 如果 `wakeMode=now`，则立即触发心跳
+
+### `POST /hooks/<name>`（映射）
+
+自定义 hook 名称通过 `hooks.mappings` 解析（见配置）。映射可以将任意请求体转换为 `wake` 或 `agent` 操作，支持可选的模板或代码转换。
+
+映射选项（摘要）：
+
+- `hooks.presets: ["gmail"]` 启用内置的 Gmail 映射。
+- `hooks.mappings` 允许你在配置中定义 `match`、`action` 和模板。
+- `hooks.transformsDir` + `transform.module` 加载 JS/TS 模块用于自定义逻辑。
+- 使用 `match.source` 保持通用的接收端点（基于请求体的路由）。
+- TS 转换需要 TS 加载器（例如 `bun` 或 `tsx`）或运行时预编译的 `.js`。
+- 在映射上设置 `deliver: true` + `channel`/`to` 可将回复路由到聊天界面（`channel` 默认为 `last`，回退到 WhatsApp）。
+- `allowUnsafeExternalContent: true` 禁用该 hook 的外部内容安全包装（危险；仅用于受信任的内部来源）。
+- `quantumclaw webhooks gmail setup` 为 `quantumclaw webhooks gmail run` 写入 `hooks.gmail` 配置。完整的 Gmail 监听流程请参阅 [Gmail Pub/Sub](/automation/gmail-pubsub)。
+
+## 响应
+
+- `200` 用于 `/hooks/wake`
+- `202` 用于 `/hooks/agent`（异步运行已启动）
+- `401` 认证失败
+- `400` 请求体无效
+- `413` 请求体过大
+
+## 示例
+
+```bash
+curl -X POST http://127.0.0.1:18789/hooks/wake \
+  -H 'Authorization: Bearer SECRET' \
+  -H 'Content-Type: application/json' \
+  -d '{"text":"New email received","mode":"now"}'
+```
+
+```bash
+curl -X POST http://127.0.0.1:18789/hooks/agent \
+  -H 'x-quantumclaw-token: SECRET' \
+  -H 'Content-Type: application/json' \
+  -d '{"message":"Summarize inbox","name":"Email","wakeMode":"next-heartbeat"}'
+```
+
+### 使用不同的模型
+
+在智能体请求体（或映射）中添加 `model` 以覆盖该次运行的模型：
+
+```bash
+curl -X POST http://127.0.0.1:18789/hooks/agent \
+  -H 'x-quantumclaw-token: SECRET' \
+  -H 'Content-Type: application/json' \
+  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.2-mini"}'
+```
+
+如果你启用了 `agents.defaults.models` 限制，请确保覆盖的模型包含在其中。
+
+```bash
+curl -X POST http://127.0.0.1:18789/hooks/gmail \
+  -H 'Authorization: Bearer SECRET' \
+  -H 'Content-Type: application/json' \
+  -d '{"source":"gmail","messages":[{"from":"Ada","subject":"Hello","snippet":"Hi"}]}'
+```
+
+## 安全
+
+- 将 hook 端点保持在 loopback、tailnet 或受信任的反向代理之后。
+- 使用专用的 hook 令牌；不要复用 Gateway 网关认证令牌。
+- 避免在 webhook 日志中包含敏感的原始请求体。
+- Hook 请求体默认被视为不受信任并使用安全边界包装。如果你必须为特定 hook 禁用此功能，请在该 hook 的映射中设置 `allowUnsafeExternalContent: true`（危险）。

package/docs/zh-CN/brave-search.md

@@ -0,0 +1,60 @@
+---
+read_when:
+  - 你想使用 Brave Search 进行 web_search
+  - 你需要 BRAVE_API_KEY 或套餐详情
+summary: 用于 web_search 的 Brave Search API 设置
+title: Brave Search
+x-i18n:
+  generated_at: "2026-02-03T07:43:09Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: cdcb037b092b8a10609f02acf062b4164cb826ac22bdb3fb2909c842a1405341
+  source_path: brave-search.md
+  workflow: 15
+---
+
+# Brave Search API
+
+QuantumClaw 使用 Brave Search 作为 `web_search` 的默认提供商。
+
+## 获取 API 密钥
+
+1. 在 https://brave.com/search/api/ 创建 Brave Search API 账户
+2. 在控制面板中，选择 **Data for Search** 套餐并生成 API 密钥。
+3. 将密钥存储在配置中（推荐），或在 Gateway 网关环境中设置 `BRAVE_API_KEY`。
+
+## 配置示例
+
+```json5
+{
+  plugins: {
+    entries: {
+      brave: {
+        config: {
+          webSearch: {
+            apiKey: "BRAVE_API_KEY_HERE",
+          },
+        },
+      },
+    },
+  },
+  tools: {
+    web: {
+      search: {
+        provider: "brave",
+        maxResults: 5,
+        timeoutSeconds: 30,
+      },
+    },
+  },
+}
+```
+
+Brave 的提供商专属搜索配置现在位于 `plugins.entries.brave.config.webSearch.*`。旧的 `tools.web.search.apiKey` 仅作为兼容层暂时保留。
+
+## 注意事项
+
+- Data for AI 套餐与 `web_search` **不**兼容。
+- Brave 提供免费层级和付费套餐；请查看 Brave API 门户了解当前限制。
+
+请参阅 [Web 工具](/tools/web) 了解完整的 web_search 配置。

package/docs/zh-CN/channels/bluebubbles.md

@@ -0,0 +1,354 @@
+---
+read_when:
+  - 设置 BlueBubbles 渠道
+  - 排查 webhook 配对问题
+  - 在 macOS 上配置 iMessage
+summary: 通过 BlueBubbles macOS 服务器使用 iMessage（REST 发送/接收、输入状态、回应、配对、高级操作）。
+title: BlueBubbles
+x-i18n:
+  generated_at: "2026-03-16T06:21:08Z"
+  model: gpt-5.4
+  provider: openai
+  source_hash: 877592bf7b9b06abdddd7567d56e756eff229d6ffa5056ef33fa3356086aa580
+  source_path: channels/bluebubbles.md
+  workflow: 15
+---
+
+# BlueBubbles（macOS REST）
+
+状态：内置插件，通过 HTTP 与 BlueBubbles macOS 服务器通信。由于其 API 更丰富且设置比旧版 imsg 渠道更简单，**推荐用于 iMessage 集成**。
+
+## 概览
+
+- 通过 BlueBubbles 辅助应用在 macOS 上运行（[bluebubbles.app](https://bluebubbles.app)）。
+- 推荐/已测试：macOS Sequoia（15）。macOS Tahoe（26）可用；目前编辑功能在 Tahoe 上已损坏，群组图标更新可能会报告成功但不会同步。
+- QuantumClaw 通过其 REST API 与其通信（`GET /api/v1/ping`、`POST /message/text`、`POST /chat/:id/*`）。
+- 传入消息通过 webhook 到达；传出回复、输入状态指示、已读回执和 tapback 都通过 REST 调用完成。
+- 附件和贴纸会作为入站媒体接收（并在可能时展示给智能体）。
+- 配对/allowlist 的工作方式与其他渠道相同（`/channels/pairing` 等），使用 `channels.bluebubbles.allowFrom` + 配对码。
+- 回应会像 Slack/Telegram 一样作为系统事件呈现，因此智能体可以在回复前“提及”它们。
+- 高级功能：编辑、撤回、回复线程、消息效果、群组管理。
+
+## 快速开始
+
+1. 在你的 Mac 上安装 BlueBubbles 服务器（按照 [bluebubbles.app/install](https://bluebubbles.app/install) 上的说明操作）。
+2. 在 BlueBubbles 配置中启用 Web API 并设置密码。
+3. 运行 `quantumclaw onboard` 并选择 BlueBubbles，或手动配置：
+
+   ```json5
+   {
+     channels: {
+       bluebubbles: {
+         enabled: true,
+         serverUrl: "http://192.168.1.100:1234",
+         password: "example-password",
+         webhookPath: "/bluebubbles-webhook",
+       },
+     },
+   }
+   ```
+
+4. 将 BlueBubbles webhook 指向你的 Gateway 网关（示例：`https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`）。
+5. 启动 Gateway 网关；它会注册 webhook 处理器并开始配对。
+
+安全说明：
+
+- 始终设置 webhook 密码。
+- 始终要求进行 webhook 身份验证。无论 loopback/代理拓扑如何，除非 BlueBubbles webhook 请求包含与 `channels.bluebubbles.password` 匹配的 password/guid（例如 `?password=<password>` 或 `x-password`），否则 QuantumClaw 会拒绝该请求。
+- 在读取/解析完整 webhook 请求体之前就会检查密码身份验证。
+
+## 保持 Messages.app 处于活动状态（VM / 无头设置）
+
+某些 macOS VM / 常开设置可能会导致 Messages.app 进入“空闲”状态（传入事件会停止，直到应用被打开/切到前台）。一个简单的解决方法是使用 AppleScript + LaunchAgent **每 5 分钟“触碰”一次 Messages**。
+
+### 1）保存 AppleScript
+
+将以下内容保存为：
+
+- `~/Scripts/poke-messages.scpt`
+
+示例脚本（非交互式；不会抢占焦点）：
+
+```applescript
+try
+  tell application "Messages"
+    if not running then
+      launch
+    end if
+
+    -- Touch the scripting interface to keep the process responsive.
+    set _chatCount to (count of chats)
+  end tell
+on error
+  -- Ignore transient failures (first-run prompts, locked session, etc).
+end try
+```
+
+### 2）安装 LaunchAgent
+
+将以下内容保存为：
+
+- `~/Library/LaunchAgents/com.user.poke-messages.plist`
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key>
+    <string>com.user.poke-messages</string>
+
+    <key>ProgramArguments</key>
+    <array>
+      <string>/bin/bash</string>
+      <string>-lc</string>
+      <string>/usr/bin/osascript &quot;$HOME/Scripts/poke-messages.scpt&quot;</string>
+    </array>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>StartInterval</key>
+    <integer>300</integer>
+
+    <key>StandardOutPath</key>
+    <string>/tmp/poke-messages.log</string>
+    <key>StandardErrorPath</key>
+    <string>/tmp/poke-messages.err</string>
+  </dict>
+</plist>
+```
+
+说明：
+
+- 这会**每 300 秒**运行一次，并且**在登录时**运行。
+- 首次运行可能会触发 macOS 的**自动化**权限提示（`osascript` → Messages）。请在运行该 LaunchAgent 的同一用户会话中批准这些提示。
+
+加载它：
+
+```bash
+launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
+launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist
+```
+
+## 新手引导
+
+BlueBubbles 可在交互式设置向导中使用：
+
+```
+quantumclaw onboard
+```
+
+向导会提示输入：
+
+- **服务器 URL**（必填）：BlueBubbles 服务器地址（例如 `http://192.168.1.100:1234`）
+- **密码**（必填）：来自 BlueBubbles Server 设置的 API 密码
+- **Webhook 路径**（可选）：默认为 `/bluebubbles-webhook`
+- **私信策略**：pairing、allowlist、open 或 disabled
+- **允许列表**：电话号码、电子邮件或聊天目标
+
+你也可以通过 CLI 添加 BlueBubbles：
+
+```
+quantumclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>
+```
+
+## 访问控制（私信 + 群组）
+
+私信：
+
+- 默认值：`channels.bluebubbles.dmPolicy = "pairing"`。
+- 未知发送者会收到一个配对码；在获得批准前，消息会被忽略（代码 1 小时后过期）。
+- 通过以下方式批准：
+  - `quantumclaw pairing list bluebubbles`
+  - `quantumclaw pairing approve bluebubbles <CODE>`
+- 配对是默认的令牌交换方式。详情见：[配对](/channels/pairing)
+
+群组：
+
+- `channels.bluebubbles.groupPolicy = open | allowlist | disabled`（默认：`allowlist`）。
+- 当设置为 `allowlist` 时，`channels.bluebubbles.groupAllowFrom` 控制谁可以在群组中触发。
+
+### 提及门控（群组）
+
+BlueBubbles 支持群聊中的提及门控，与 iMessage/WhatsApp 的行为一致：
+
+- 使用 `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）检测提及。
+- 当某个群组启用 `requireMention` 时，智能体只有在被提及时才会响应。
+- 来自授权发送者的控制命令会绕过提及门控。
+
+每群组配置：
+
+```json5
+{
+  channels: {
+    bluebubbles: {
+      groupPolicy: "allowlist",
+      groupAllowFrom: ["+15555550123"],
+      groups: {
+        "*": { requireMention: true }, // 所有群组的默认值
+        "iMessage;-;chat123": { requireMention: false }, // 对特定群组覆盖
+      },
+    },
+  },
+}
+```
+
+### 命令门控
+
+- 控制命令（例如 `/config`、`/model`）需要授权。
+- 使用 `allowFrom` 和 `groupAllowFrom` 来判断命令授权。
+- 授权发送者即使在群组中未提及，也可以运行控制命令。
+
+## 输入状态 + 已读回执
+
+- **输入状态指示**：会在生成响应之前和期间自动发送。
+- **已读回执**：由 `channels.bluebubbles.sendReadReceipts` 控制（默认：`true`）。
+- **输入状态指示**：QuantumClaw 会发送输入开始事件；BlueBubbles 会在发送后或超时后自动清除输入状态（通过 DELETE 手动停止并不可靠）。
+
+```json5
+{
+  channels: {
+    bluebubbles: {
+      sendReadReceipts: false, // 禁用已读回执
+    },
+  },
+}
+```
+
+## 高级操作
+
+在配置中启用后，BlueBubbles 支持高级消息操作：
+
+```json5
+{
+  channels: {
+    bluebubbles: {
+      actions: {
+        reactions: true, // tapback（默认：true）
+        edit: true, // 编辑已发送消息（macOS 13+，在 macOS 26 Tahoe 上已损坏）
+        unsend: true, // 撤回消息（macOS 13+）
+        reply: true, // 按消息 GUID 回复线程
+        sendWithEffect: true, // 消息效果（slam、loud 等）
+        renameGroup: true, // 重命名群聊
+        setGroupIcon: true, // 设置群聊图标/照片（在 macOS 26 Tahoe 上不稳定）
+        addParticipant: true, // 向群组添加参与者
+        removeParticipant: true, // 从群组移除参与者
+        leaveGroup: true, // 退出群聊
+        sendAttachment: true, // 发送附件/媒体
+      },
+    },
+  },
+}
+```
+
+可用操作：
+
+- **react**：添加/移除 tapback 回应（`messageId`、`emoji`、`remove`）
+- **edit**：编辑已发送消息（`messageId`、`text`）
+- **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`）
+- **leaveGroup**：退出群聊（`chatGuid`）
+- **sendAttachment**：发送媒体/文件（`to`、`buffer`、`filename`、`asVoice`）
+  - 语音备忘录：将 `asVoice: true` 与 **MP3** 或 **CAF** 音频一起设置，即可作为 iMessage 语音消息发送。BlueBubbles 在发送语音备忘录时会将 MP3 转换为 CAF。
+
+### 消息 ID（短 ID 与完整 ID）
+
+QuantumClaw 可能会显示*短*消息 ID（例如 `1`、`2`）以节省 token。
+
+- `MessageSid` / `ReplyToId` 可以是短 ID。
+- `MessageSidFull` / `ReplyToIdFull` 包含提供商的完整 ID。
+- 短 ID 存在于内存中；它们可能会在重启或缓存清除后失效。
+- 操作接受短或完整 `messageId`，但如果短 ID 不再可用，就会报错。
+
+对于持久化自动化和存储，请使用完整 ID：
+
+- 模板：`{{MessageSidFull}}`、`{{ReplyToIdFull}}`
+- 上下文：入站负载中的 `MessageSidFull` / `ReplyToIdFull`
+
+模板变量请参见[配置](/gateway/configuration)。
+
+## 分块流式传输
+
+控制响应是作为单条消息发送，还是按块流式发送：
+
+```json5
+{
+  channels: {
+    bluebubbles: {
+      blockStreaming: true, // 启用分块流式传输（默认关闭）
+    },
+  },
+}
+```
+
+## 媒体 + 限制
+
+- 入站附件会被下载并存储在媒体缓存中。
+- 通过 `channels.bluebubbles.mediaMaxMb` 控制入站和出站媒体大小上限（默认：8 MB）。
+- 出站文本会按 `channels.bluebubbles.textChunkLimit` 分块（默认：4000 个字符）。
+
+## 配置参考
+
+完整配置：[配置](/gateway/configuration)
+
+提供商选项：
+
+- `channels.bluebubbles.enabled`：启用/禁用该渠道。
+- `channels.bluebubbles.serverUrl`：BlueBubbles REST API 基础 URL。
+- `channels.bluebubbles.password`：API 密码。
+- `channels.bluebubbles.webhookPath`：Webhook 端点路径（默认：`/bluebubbles-webhook`）。
+- `channels.bluebubbles.dmPolicy`：`pairing | allowlist | open | disabled`（默认：`pairing`）。
+- `channels.bluebubbles.allowFrom`：私信 allowlist（handle、电子邮件、E.164 号码、`chat_id:*`、`chat_guid:*`）。
+- `channels.bluebubbles.groupPolicy`：`open | allowlist | disabled`（默认：`allowlist`）。
+- `channels.bluebubbles.groupAllowFrom`：群组发送者 allowlist。
+- `channels.bluebubbles.groups`：每群组配置（`requireMention` 等）。
+- `channels.bluebubbles.sendReadReceipts`：发送已读回执（默认：`true`）。
+- `channels.bluebubbles.blockStreaming`：启用分块流式传输（默认：`false`；流式回复所必需）。
+- `channels.bluebubbles.textChunkLimit`：出站分块大小（按字符计，默认：4000）。
+- `channels.bluebubbles.chunkMode`：`length`（默认）仅在超过 `textChunkLimit` 时拆分；`newline` 会先按空行（段落边界）拆分，再按长度分块。
+- `channels.bluebubbles.mediaMaxMb`：入站/出站媒体大小上限（MB，默认：8）。
+- `channels.bluebubbles.mediaLocalRoots`：允许用于出站本地媒体路径的绝对本地目录显式 allowlist。默认情况下，本地路径发送会被拒绝，除非配置了此项。每账户覆盖：`channels.bluebubbles.accounts.<accountId>.mediaLocalRoots`。
+- `channels.bluebubbles.historyLimit`：用于上下文的最大群组消息数（0 表示禁用）。
+- `channels.bluebubbles.dmHistoryLimit`：私信历史记录上限。
+- `channels.bluebubbles.actions`：启用/禁用特定操作。
+- `channels.bluebubbles.accounts`：多账户配置。
+
+相关全局选项：
+
+- `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）。
+- `messages.responsePrefix`。
+
+## 寻址 / 送达目标
+
+优先使用 `chat_guid` 以获得稳定路由：
+
+- `chat_guid:iMessage;-;+15555550123`（群组首选）
+- `chat_id:123`
+- `chat_identifier:...`
+- 直接 handle：`+15555550123`、`user@example.com`
+  - 如果某个直接 handle 没有现有私信聊天，QuantumClaw 会通过 `POST /api/v1/chat/new` 创建一个。这要求启用 BlueBubbles Private API。
+
+## 安全
+
+- 通过将查询参数或请求头中的 `guid`/`password` 与 `channels.bluebubbles.password` 进行比较来验证 webhook 请求。来自 `localhost` 的请求也会被接受。
+- 请妥善保管 API 密码和 webhook 端点（将它们视为凭证）。
+- 对 localhost 的信任意味着同主机上的反向代理可能会无意中绕过密码。如果你对 Gateway 网关进行了代理，请在代理层要求身份验证，并配置 `gateway.trustedProxies`。请参见 [Gateway 网关安全](/gateway/security#reverse-proxy-configuration)。
+- 如果要在局域网外暴露 BlueBubbles 服务器，请启用 HTTPS + 防火墙规则。
+
+## 故障排除
+
+- 如果输入状态/已读事件停止工作，请检查 BlueBubbles webhook 日志，并验证 Gateway 网关路径与 `channels.bluebubbles.webhookPath` 一致。
+- 配对码会在一小时后过期；使用 `quantumclaw pairing list bluebubbles` 和 `quantumclaw pairing approve bluebubbles <code>`。
+- 回应需要 BlueBubbles private API（`POST /api/v1/message/react`）；请确保服务器版本提供该接口。
+- 编辑/撤回需要 macOS 13+ 以及兼容的 BlueBubbles 服务器版本。在 macOS 26（Tahoe）上，由于 private API 变更，编辑功能目前已损坏。
+- 群组图标更新在 macOS 26（Tahoe）上可能不稳定：API 可能返回成功，但新图标不会同步。
+- QuantumClaw 会根据 BlueBubbles 服务器的 macOS 版本自动隐藏已知损坏的操作。如果在 macOS 26（Tahoe）上仍显示编辑操作，请手动使用 `channels.bluebubbles.actions.edit=false` 禁用它。
+- 状态/健康信息请使用：`quantumclaw status --all` 或 `quantumclaw status --deep`。
+
+有关通用渠道工作流程参考，请参见 [Channels](/channels) 和 [Plugins](/tools/plugin) 指南。