@quantumclaw/quantumclaw 2026.3.22

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

@@ -0,0 +1,257 @@
+---
+read_when:
+  - 开发 Google Chat 渠道功能时
+summary: Google Chat 应用支持状态、功能和配置
+title: Google Chat
+x-i18n:
+  generated_at: "2026-02-03T07:43:39Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 3b2bb116cdd12614c3d5afddd0879e9deb05c3606e3a2385cbc07f23552b357e
+  source_path: channels/googlechat.md
+  workflow: 15
+---
+
+# Google Chat（Chat API）
+
+状态：已支持通过 Google Chat API webhooks（仅 HTTP）使用私信和空间。
+
+## 快速设置（新手）
+
+1. 创建一个 Google Cloud 项目并启用 **Google Chat API**。
+   - 前往：[Google Chat API Credentials](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials)
+   - 如果 API 尚未启用，请启用它。
+2. 创建一个**服务账号**：
+   - 点击 **Create Credentials** > **Service Account**。
+   - 随意命名（例如 `quantumclaw-chat`）。
+   - 权限留空（点击 **Continue**）。
+   - 有访问权限的主账号留空（点击 **Done**）。
+3. 创建并下载 **JSON 密钥**：
+   - 在服务账号列表中，点击刚刚创建的账号。
+   - 前往 **Keys** 标签页。
+   - 点击 **Add Key** > **Create new key**。
+   - 选择 **JSON** 并点击 **Create**。
+4. 将下载的 JSON 文件存储在 Gateway 网关主机上（例如 `~/.quantumclaw/googlechat-service-account.json`）。
+5. 在 [Google Cloud Console Chat Configuration](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat) 中创建一个 Google Chat 应用：
+   - 填写 **Application info**：
+     - **App name**：（例如 `QuantumClaw`）
+     - **Avatar URL**：（例如 `https://quantumclaw.ai/logo.png`）
+     - **Description**：（例如 `Personal AI Assistant`）
+   - 启用 **Interactive features**。
+   - 在 **Functionality** 下，勾选 **Join spaces and group conversations**。
+   - 在 **Connection settings** 下，选择 **HTTP endpoint URL**。
+   - 在 **Triggers** 下，选择 **Use a common HTTP endpoint URL for all triggers** 并将其设置为你的 Gateway 网关公网 URL 后加 `/googlechat`。
+     - _提示：运行 `quantumclaw status` 查看你的 Gateway 网关公网 URL。_
+   - 在 **Visibility** 下，勾选 **Make this Chat app available to specific people and groups in <Your Domain>**。
+   - 在文本框中输入你的邮箱地址（例如 `user@example.com`）。
+   - 点击底部的 **Save**。
+6. **启用应用状态**：
+   - 保存后，**刷新页面**。
+   - 找到 **App status** 部分（通常在保存后位于顶部或底部附近）。
+   - 将状态更改为 **Live - available to users**。
+   - 再次点击 **Save**。
+7. 使用服务账号路径和 webhook audience 配置 QuantumClaw：
+   - 环境变量：`GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json`
+   - 或配置：`channels.googlechat.serviceAccountFile: "/path/to/service-account.json"`。
+8. 设置 webhook audience 类型和值（与你的 Chat 应用配置匹配）。
+9. 启动 Gateway 网关。Google Chat 将向你的 webhook 路径发送 POST 请求。
+
+## 添加到 Google Chat
+
+Gateway 网关运行后，且你的邮箱已添加到可见性列表中：
+
+1. 前往 [Google Chat](https://chat.google.com/)。
+2. 点击 **Direct Messages** 旁边的 **+**（加号）图标。
+3. 在搜索栏（通常用于添加联系人的位置）中，输入你在 Google Cloud Console 中配置的 **App name**。
+   - **注意**：该机器人*不会*出现在"Marketplace"浏览列表中，因为它是私有应用。你必须按名称搜索。
+4. 从结果中选择你的机器人。
+5. 点击 **Add** 或 **Chat** 开始一对一对话。
+6. 发送"Hello"来触发助手！
+
+## 公网 URL（仅 Webhook）
+
+Google Chat webhooks 需要一个公网 HTTPS 端点。为了安全起见，**只将 `/googlechat` 路径暴露到互联网**。将 QuantumClaw 仪表板和其他敏感端点保留在你的私有网络上。
+
+### 方案 A：Tailscale Funnel（推荐）
+
+使用 Tailscale Serve 提供私有仪表板，使用 Funnel 提供公网 webhook 路径。这样可以保持 `/` 私有，同时只暴露 `/googlechat`。
+
+1. **检查你的 Gateway 网关绑定的地址：**
+
+   ```bash
+   ss -tlnp | grep 18789
+   ```
+
+   记下 IP 地址（例如 `127.0.0.1`、`0.0.0.0` 或你的 Tailscale IP 如 `100.x.x.x`）。
+
+2. **仅将仪表板暴露给 tailnet（端口 8443）：**
+
+   ```bash
+   # 如果绑定到 localhost（127.0.0.1 或 0.0.0.0）：
+   tailscale serve --bg --https 8443 http://127.0.0.1:18789
+
+   # 如果仅绑定到 Tailscale IP（例如 100.106.161.80）：
+   tailscale serve --bg --https 8443 http://100.106.161.80:18789
+   ```
+
+3. **仅公开暴露 webhook 路径：**
+
+   ```bash
+   # 如果绑定到 localhost（127.0.0.1 或 0.0.0.0）：
+   tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat
+
+   # 如果仅绑定到 Tailscale IP（例如 100.106.161.80）：
+   tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat
+   ```
+
+4. **授权节点访问 Funnel：**
+   如果出现提示，请访问输出中显示的授权 URL，以在你的 tailnet 策略中为此节点启用 Funnel。
+
+5. **验证配置：**
+   ```bash
+   tailscale serve status
+   tailscale funnel status
+   ```
+
+你的公网 webhook URL 将是：
+`https://<node-name>.<tailnet>.ts.net/googlechat`
+
+你的私有仪表板仅限 tailnet 访问：
+`https://<node-name>.<tailnet>.ts.net:8443/`
+
+在 Google Chat 应用配置中使用公网 URL（不带 `:8443`）。
+
+> 注意：此配置在重启后会保留。如需稍后移除，请运行 `tailscale funnel reset` 和 `tailscale serve reset`。
+
+### 方案 B：反向代理（Caddy）
+
+如果你使用像 Caddy 这样的反向代理，只代理特定路径：
+
+```caddy
+your-domain.com {
+    reverse_proxy /googlechat* localhost:18789
+}
+```
+
+使用此配置，任何发往 `your-domain.com/` 的请求将被忽略或返回 404，而 `your-domain.com/googlechat` 会安全地路由到 QuantumClaw。
+
+### 方案 C：Cloudflare Tunnel
+
+配置你的隧道入口规则，只路由 webhook 路径：
+
+- **路径**：`/googlechat` -> `http://localhost:18789/googlechat`
+- **默认规则**：HTTP 404（未找到）
+
+## 工作原理
+
+1. Google Chat 向 Gateway 网关发送 webhook POST 请求。每个请求都包含一个 `Authorization: Bearer <token>` 头。
+2. QuantumClaw 根据配置的 `audienceType` + `audience` 验证令牌：
+   - `audienceType: "app-url"` → audience 是你的 HTTPS webhook URL。
+   - `audienceType: "project-number"` → audience 是 Cloud 项目编号。
+3. 消息按空间路由：
+   - 私信使用会话键 `agent:<agentId>:googlechat:dm:<spaceId>`。
+   - 空间使用会话键 `agent:<agentId>:googlechat:group:<spaceId>`。
+4. 私信访问默认为配对模式。未知发送者会收到配对码；使用以下命令批准：
+   - `quantumclaw pairing approve googlechat <code>`
+5. 群组空间默认需要 @提及。如果提及检测需要应用的用户名，请使用 `botUser`。
+
+## 目标标识符
+
+使用这些标识符进行消息投递和允许列表：
+
+- 私信：`users/<userId>` 或 `users/<email>`（接受邮箱地址）。
+- 空间：`spaces/<spaceId>`。
+
+## 配置要点
+
+```json5
+{
+  channels: {
+    googlechat: {
+      enabled: true,
+      serviceAccountFile: "/path/to/service-account.json",
+      audienceType: "app-url",
+      audience: "https://gateway.example.com/googlechat",
+      webhookPath: "/googlechat",
+      botUser: "users/1234567890", // 可选；帮助提及检测
+      dm: {
+        policy: "pairing",
+        allowFrom: ["users/1234567890", "name@example.com"],
+      },
+      groupPolicy: "allowlist",
+      groups: {
+        "spaces/AAAA": {
+          allow: true,
+          requireMention: true,
+          users: ["users/1234567890"],
+          systemPrompt: "Short answers only.",
+        },
+      },
+      actions: { reactions: true },
+      typingIndicator: "message",
+      mediaMaxMb: 20,
+    },
+  },
+}
+```
+
+注意事项：
+
+- 服务账号凭证也可以通过 `serviceAccount`（JSON 字符串）内联传递。
+- 如果未设置 `webhookPath`，默认 webhook 路径为 `/googlechat`。
+- 当 `actions.reactions` 启用时，可通过 `reactions` 工具和 `channels action` 使用表情回应。
+- `typingIndicator` 支持 `none`、`message`（默认）和 `reaction`（reaction 需要用户 OAuth）。
+- 附件通过 Chat API 下载并存储在媒体管道中（大小受 `mediaMaxMb` 限制）。
+
+## 故障排除
+
+### 405 Method Not Allowed
+
+如果 Google Cloud Logs Explorer 显示如下错误：
+
+```
+status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed
+```
+
+这意味着 webhook 处理程序未注册。常见原因：
+
+1. **渠道未配置**：配置中缺少 `channels.googlechat` 部分。使用以下命令验证：
+
+   ```bash
+   quantumclaw config get channels.googlechat
+   ```
+
+   如果返回"Config path not found"，请添加配置（参见[配置要点](#配置要点)）。
+
+2. **插件未启用**：检查插件状态：
+
+   ```bash
+   quantumclaw plugins list | grep googlechat
+   ```
+
+   如果显示"disabled"，请在配置中添加 `plugins.entries.googlechat.enabled: true`。
+
+3. **Gateway 网关未重启**：添加配置后，重启 Gateway 网关：
+   ```bash
+   quantumclaw gateway restart
+   ```
+
+验证渠道是否正在运行：
+
+```bash
+quantumclaw channels status
+# 应显示：Google Chat default: enabled, configured, ...
+```
+
+### 其他问题
+
+- 检查 `quantumclaw channels status --probe` 以查看认证错误或缺少 audience 配置。
+- 如果没有收到消息，请确认 Chat 应用的 webhook URL 和事件订阅。
+- 如果提及门控阻止了回复，请将 `botUser` 设置为应用的用户资源名称并验证 `requireMention`。
+- 在发送测试消息时使用 `quantumclaw logs --follow` 查看请求是否到达 Gateway 网关。
+
+相关文档：
+
+- [Gateway 网关配置](/gateway/configuration)
+- [安全](/gateway/security)
+- [表情回应](/tools/reactions)

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

@@ -0,0 +1,38 @@
+---
+read_when:
+  - 开发 Telegram 或 grammY 相关功能时
+summary: 通过 grammY 集成 Telegram Bot API，附设置说明
+title: grammY
+x-i18n:
+  generated_at: "2026-02-03T10:03:55Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: ea7ef23e6d77801f4ef5fc56685ef4470f79f5aecab448d644a72cbab53521b7
+  source_path: channels/grammy.md
+  workflow: 15
+---
+
+# grammY 集成（Telegram Bot API）
+
+# 为什么选择 grammY
+
+- 以 TS 为核心的 Bot API 客户端，内置长轮询 + webhook 辅助工具、中间件、错误处理和速率限制器。
+- 媒体处理辅助工具比手动编写 fetch + FormData 更简洁；支持所有 Bot API 方法。
+- 可扩展：通过自定义 fetch 支持代理，可选的会话中间件，类型安全的上下文。
+
+# 我们发布的内容
+
+- **单一客户端路径：** 移除了基于 fetch 的实现；grammY 现在是唯一的 Telegram 客户端（发送 + Gateway 网关），默认启用 grammY throttler。
+- **Gateway 网关：** `monitorTelegramProvider` 构建 grammY `Bot`，接入 mention/allowlist 网关控制，通过 `getFile`/`download` 下载媒体，并使用 `sendMessage/sendPhoto/sendVideo/sendAudio/sendDocument` 发送回复。通过 `webhookCallback` 支持长轮询或 webhook。
+- **代理：** 可选的 `channels.telegram.proxy` 通过 grammY 的 `client.baseFetch` 使用 `undici.ProxyAgent`。
+- **Webhook 支持：** `webhook-set.ts` 封装了 `setWebhook/deleteWebhook`；`webhook.ts` 托管回调，支持健康检查和优雅关闭。当设置了 `channels.telegram.webhookUrl` + `channels.telegram.webhookSecret` 时，Gateway 网关启用 webhook 模式（否则使用长轮询）。
+- **会话：** 私聊折叠到智能体主会话（`agent:<agentId>:<mainKey>`）；群组使用 `agent:<agentId>:telegram:group:<chatId>`；回复路由回同一渠道。
+- **配置选项：** `channels.telegram.botToken`、`channels.telegram.dmPolicy`、`channels.telegram.groups`（allowlist + mention 默认值）、`channels.telegram.allowFrom`、`channels.telegram.groupAllowFrom`、`channels.telegram.groupPolicy`、`channels.telegram.mediaMaxMb`、`channels.telegram.linkPreview`、`channels.telegram.proxy`、`channels.telegram.webhookSecret`、`channels.telegram.webhookUrl`。
+- **草稿流式传输：** 可选的 `channels.telegram.streamMode` 在私有话题聊天中使用 `sendMessageDraft`（Bot API 9.3+）。这与渠道分块流式传输是分开的。
+- **测试：** grammY mock 覆盖了私信 + 群组 mention 网关控制和出站发送；欢迎添加更多媒体/webhook 测试用例。
+
+待解决问题
+
+- 如果遇到 Bot API 429 错误，考虑使用可选的 grammY 插件（throttler）。
+- 添加更多结构化媒体测试（贴纸、语音消息）。
+- 使 webhook 监听端口可配置（目前固定为 8787，除非通过 Gateway 网关配置）。

package/docs/zh-CN/channels/group-messages.md

@@ -0,0 +1,91 @@
+---
+read_when:
+  - 更改群组消息规则或提及设置时
+summary: WhatsApp 群组消息处理的行为和配置（mentionPatterns 在各平台间共享）
+title: 群组消息
+x-i18n:
+  generated_at: "2026-02-03T10:05:00Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 181a72f12f5021af77c2e4c913120f711e0c0bc271d218d75cb6fe80dab675bb
+  source_path: channels/group-messages.md
+  workflow: 15
+---
+
+# 群组消息（WhatsApp 网页渠道）
+
+目标：让 Clawd 留在 WhatsApp 群组中，仅在被提及时唤醒，并将该对话线程与个人私信会话分开。
+
+注意：`agents.list[].groupChat.mentionPatterns` 现在也被 Telegram/Discord/Slack/iMessage 使用；本文档重点介绍 WhatsApp 特定的行为。对于多智能体设置，为每个智能体设置 `agents.list[].groupChat.mentionPatterns`（或使用 `messages.groupChat.mentionPatterns` 作为全局回退）。
+
+## 已实现的功能（2025-12-03）
+
+- 激活模式：`mention`（默认）或 `always`。`mention` 需要被提及（通过 `mentionedJids` 的真实 WhatsApp @提及、正则表达式模式，或文本中任意位置的机器人 E.164 号码）。`always` 会在每条消息时唤醒智能体，但它应该只在能提供有意义价值时才回复；否则返回静默令牌 `NO_REPLY`。默认值可在配置中设置（`channels.whatsapp.groups`），并可通过 `/activation` 为每个群组单独覆盖。当设置了 `channels.whatsapp.groups` 时，它同时充当群组允许列表（包含 `"*"` 以允许所有群组）。
+- 群组策略：`channels.whatsapp.groupPolicy` 控制是否接受群组消息（`open|disabled|allowlist`）。`allowlist` 使用 `channels.whatsapp.groupAllowFrom`（回退：显式的 `channels.whatsapp.allowFrom`）。默认为 `allowlist`（在你添加发送者之前被阻止）。
+- 独立群组会话：会话键格式为 `agent:<agentId>:whatsapp:group:<jid>`，因此 `/verbose on` 或 `/think high`（作为独立消息发送）等命令仅作用于该群组；个人私信状态不受影响。群组线程会跳过心跳。
+- 上下文注入：**仅待处理**的群组消息（默认 50 条），即*未*触发运行的消息，会以 `[Chat messages since your last reply - for context]` 为前缀注入，触发行在 `[Current message - respond to this]` 下。已在会话中的消息不会重复注入。
+- 发送者显示：每个群组批次现在以 `[from: Sender Name (+E164)]` 结尾，让 Pi 知道是谁在说话。
+- 阅后即焚/一次性查看：我们在提取文本/提及之前会先解包这些消息，因此其中的提及仍会触发。
+- 群组系统提示：在群组会话的第一轮（以及每当 `/activation` 更改模式时），我们会向系统提示注入一段简短说明，如 `You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context.` 如果元数据不可用，我们仍会告知智能体这是一个群聊。
+
+## 配置示例（WhatsApp）
+
+在 `~/.quantumclaw/quantumclaw.json` 中添加 `groupChat` 块，以便在 WhatsApp 剥离文本正文中的可视 `@` 时，显示名称提及仍能正常工作：
+
+```json5
+{
+  channels: {
+    whatsapp: {
+      groups: {
+        "*": { requireMention: true },
+      },
+    },
+  },
+  agents: {
+    list: [
+      {
+        id: "main",
+        groupChat: {
+          historyLimit: 50,
+          mentionPatterns: ["@?quantumclaw", "\\+?15555550123"],
+        },
+      },
+    ],
+  },
+}
+```
+
+注意：
+
+- 正则表达式不区分大小写；它们涵盖了像 `@quantumclaw` 这样的显示名称提及，以及带或不带 `+`/空格的原始号码。
+- 当有人点击联系人时，WhatsApp 仍会通过 `mentionedJids` 发送规范的提及，因此号码回退很少需要，但作为安全网很有用。
+
+### 激活命令（仅所有者）
+
+使用群聊命令：
+
+- `/activation mention`
+- `/activation always`
+
+只有所有者号码（来自 `channels.whatsapp.allowFrom`，或未设置时使用机器人自己的 E.164）可以更改此设置。在群组中发送 `/status` 作为独立消息以查看当前激活模式。
+
+## 使用方法
+
+1. 将你的 WhatsApp 账号（运行 QuantumClaw 的账号）添加到群组。
+2. 说 `@quantumclaw …`（或包含号码）。只有允许列表中的发送者才能触发，除非你设置 `groupPolicy: "open"`。
+3. 智能体提示将包含最近的群组上下文以及尾部的 `[from: …]` 标记，以便它能够回应正确的人。
+4. 会话级指令（`/verbose on`、`/think high`、`/new` 或 `/reset`、`/compact`）仅适用于该群组的会话；将它们作为独立消息发送以使其生效。你的个人私信会话保持独立。
+
+## 测试/验证
+
+- 手动冒烟测试：
+  - 在群组中发送 `@quantumclaw` 提及，确认收到引用发送者名称的回复。
+  - 发送第二次提及，验证历史记录块被包含，然后在下一轮清除。
+- 检查 Gateway 网关日志（使用 `--verbose` 运行）以查看 `inbound web message` 条目，显示 `from: <groupJid>` 和 `[from: …]` 后缀。
+
+## 已知注意事项
+
+- 群组有意跳过心跳以避免嘈杂的广播。
+- 回声抑制使用组合的批次字符串；如果你发送两次相同的文本但没有提及，只有第一次会得到响应。
+- 会话存储条目将在会话存储中显示为 `agent:<agentId>:whatsapp:group:<jid>`（默认为 `~/.quantumclaw/agents/<agentId>/sessions/sessions.json`）；缺失条目只是意味着该群组尚未触发运行。
+- 群组中的输入指示器遵循 `agents.defaults.typingMode`（默认：未被提及时为 `message`）。