@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/channels/nextcloud-talk.md

@@ -0,0 +1,142 @@
+---
+read_when:
+  - 开发 Nextcloud Talk 渠道功能时
+summary: Nextcloud Talk 支持状态、功能和配置
+title: Nextcloud Talk
+x-i18n:
+  generated_at: "2026-02-03T10:04:00Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 21b7b9756c4356a76dc0f14c10e44ed74a284cf3badf87e2df75eb88d8a90c31
+  source_path: channels/nextcloud-talk.md
+  workflow: 15
+---
+
+# Nextcloud Talk（插件）
+
+状态：通过插件支持（webhook 机器人）。支持私信、房间、表情回应和 Markdown 消息。
+
+## 需要插件
+
+Nextcloud Talk 以插件形式提供，不包含在核心安装包中。
+
+通过 CLI 安装（npm 仓库）：
+
+```bash
+quantumclaw plugins install @quantumclaw/nextcloud-talk
+```
+
+本地检出安装（从 git 仓库运行时）：
+
+```bash
+quantumclaw plugins install ./extensions/nextcloud-talk
+```
+
+如果你在配置/新手引导过程中选择了 Nextcloud Talk，并且检测到 git 检出，
+QuantumClaw 将自动提供本地安装路径。
+
+详情：[插件](/tools/plugin)
+
+## 快速设置（新手）
+
+1. 安装 Nextcloud Talk 插件。
+2. 在你的 Nextcloud 服务器上创建机器人：
+   ```bash
+   ./occ talk:bot:install "QuantumClaw" "<shared-secret>" "<webhook-url>" --feature reaction
+   ```
+3. 在目标房间设置中启用机器人。
+4. 配置 QuantumClaw：
+   - 配置项：`channels.nextcloud-talk.baseUrl` + `channels.nextcloud-talk.botSecret`
+   - 或环境变量：`NEXTCLOUD_TALK_BOT_SECRET`（仅默认账户）
+5. 重启 Gateway 网关（或完成新手引导）。
+
+最小配置：
+
+```json5
+{
+  channels: {
+    "nextcloud-talk": {
+      enabled: true,
+      baseUrl: "https://cloud.example.com",
+      botSecret: "shared-secret",
+      dmPolicy: "pairing",
+    },
+  },
+}
+```
+
+## 注意事项
+
+- 机器人无法主动发起私信。用户必须先向机器人发送消息。
+- Webhook URL 必须可被 Gateway 网关访问；如果在代理后面，请设置 `webhookPublicUrl`。
+- 机器人 API 不支持媒体上传；媒体以 URL 形式发送。
+- Webhook 载荷无法区分私信和房间；设置 `apiUser` + `apiPassword` 以启用房间类型查询（否则私信将被视为房间）。
+
+## 访问控制（私信）
+
+- 默认：`channels.nextcloud-talk.dmPolicy = "pairing"`。未知发送者将收到配对码。
+- 批准方式：
+  - `quantumclaw pairing list nextcloud-talk`
+  - `quantumclaw pairing approve nextcloud-talk <CODE>`
+- 公开私信：`channels.nextcloud-talk.dmPolicy="open"` 加上 `channels.nextcloud-talk.allowFrom=["*"]`。
+
+## 房间（群组）
+
+- 默认：`channels.nextcloud-talk.groupPolicy = "allowlist"`（需要提及触发）。
+- 使用 `channels.nextcloud-talk.rooms` 设置房间白名单：
+
+```json5
+{
+  channels: {
+    "nextcloud-talk": {
+      rooms: {
+        "room-token": { requireMention: true },
+      },
+    },
+  },
+}
+```
+
+- 如需禁止所有房间，保持白名单为空或设置 `channels.nextcloud-talk.groupPolicy="disabled"`。
+
+## 功能支持
+
+| 功能     | 状态   |
+| -------- | ------ |
+| 私信     | 支持   |
+| 房间     | 支持   |
+| 话题     | 不支持 |
+| 媒体     | 仅 URL |
+| 表情回应 | 支持   |
+| 原生命令 | 不支持 |
+
+## 配置参考（Nextcloud Talk）
+
+完整配置：[配置](/gateway/configuration)
+
+提供商选项：
+
+- `channels.nextcloud-talk.enabled`：启用/禁用渠道启动。
+- `channels.nextcloud-talk.baseUrl`：Nextcloud 实例 URL。
+- `channels.nextcloud-talk.botSecret`：机器人共享密钥。
+- `channels.nextcloud-talk.botSecretFile`：密钥文件路径。
+- `channels.nextcloud-talk.apiUser`：用于房间查询的 API 用户（私信检测）。
+- `channels.nextcloud-talk.apiPassword`：用于房间查询的 API/应用密码。
+- `channels.nextcloud-talk.apiPasswordFile`：API 密码文件路径。
+- `channels.nextcloud-talk.webhookPort`：webhook 监听端口（默认：8788）。
+- `channels.nextcloud-talk.webhookHost`：webhook 主机（默认：0.0.0.0）。
+- `channels.nextcloud-talk.webhookPath`：webhook 路径（默认：/nextcloud-talk-webhook）。
+- `channels.nextcloud-talk.webhookPublicUrl`：外部可达的 webhook URL。
+- `channels.nextcloud-talk.dmPolicy`：`pairing | allowlist | open | disabled`。
+- `channels.nextcloud-talk.allowFrom`：私信白名单（用户 ID）。`open` 需要 `"*"`。
+- `channels.nextcloud-talk.groupPolicy`：`allowlist | open | disabled`。
+- `channels.nextcloud-talk.groupAllowFrom`：群组白名单（用户 ID）。
+- `channels.nextcloud-talk.rooms`：每个房间的设置和白名单。
+- `channels.nextcloud-talk.historyLimit`：群组历史记录限制（0 表示禁用）。
+- `channels.nextcloud-talk.dmHistoryLimit`：私信历史记录限制（0 表示禁用）。
+- `channels.nextcloud-talk.dms`：每个私信的覆盖设置（historyLimit）。
+- `channels.nextcloud-talk.textChunkLimit`：出站文本分块大小（字符数）。
+- `channels.nextcloud-talk.chunkMode`：`length`（默认）或 `newline`，在长度分块前按空行（段落边界）分割。
+- `channels.nextcloud-talk.blockStreaming`：禁用此渠道的分块流式传输。
+- `channels.nextcloud-talk.blockStreamingCoalesce`：分块流式传输合并调优。
+- `channels.nextcloud-talk.mediaMaxMb`：入站媒体大小上限（MB）。

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

@@ -0,0 +1,249 @@
+---
+read_when:
+  - 你想让 QuantumClaw 通过 Nostr 接收私信
+  - 你正在设置去中心化消息传递
+summary: 通过 NIP-04 加密消息实现的 Nostr 私信渠道
+title: Nostr
+x-i18n:
+  generated_at: "2026-03-16T06:20:37Z"
+  model: gpt-5.4
+  provider: openai
+  source_hash: fcce57da49256971420c4bb099aebb7944f8c7e8619b17b163da685add225001
+  source_path: channels/nostr.md
+  workflow: 15
+---
+
+# Nostr
+
+**状态：** 可选插件（默认禁用）。
+
+Nostr 是一种用于社交网络的去中心化协议。此渠道使 QuantumClaw 能够通过 NIP-04 接收并回复加密私信。
+
+## 安装（按需）
+
+### 新手引导（推荐）
+
+- 设置向导（`quantumclaw onboard`）和 `quantumclaw channels add` 会列出可选渠道插件。
+- 选择 Nostr 时，系统会提示你按需安装该插件。
+
+安装默认行为：
+
+- **Dev 渠道 + 可用的 git 检出：** 使用本地插件路径。
+- **稳定版 / Beta：** 从 npm 下载。
+
+你始终可以在提示中覆盖该选择。
+
+### 手动安装
+
+```bash
+quantumclaw plugins install @quantumclaw/nostr
+```
+
+使用本地检出（dev 工作流）：
+
+```bash
+quantumclaw plugins install --link <path-to-quantumclaw>/extensions/nostr
+```
+
+安装或启用插件后，重启 Gateway 网关。
+
+### 非交互式设置
+
+```bash
+quantumclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY"
+quantumclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY" --relay-urls "wss://relay.damus.io,wss://relay.primal.net"
+```
+
+使用 `--use-env` 可将 `NOSTR_PRIVATE_KEY` 保留在环境中，而不是将密钥存储在配置里。
+
+## 快速设置
+
+1. 生成一个 Nostr 密钥对（如有需要）：
+
+```bash
+# Using nak
+nak key generate
+```
+
+2. 添加到配置中：
+
+```json
+{
+  "channels": {
+    "nostr": {
+      "privateKey": "${NOSTR_PRIVATE_KEY}"
+    }
+  }
+}
+```
+
+3. 导出密钥：
+
+```bash
+export NOSTR_PRIVATE_KEY="nsec1..."
+```
+
+4. 重启 Gateway 网关。
+
+## 配置参考
+
+| 键           | 类型     | 默认值                                      | 说明                        |
+| ------------ | -------- | ------------------------------------------- | --------------------------- |
+| `privateKey` | string   | 必填                                        | `nsec` 或十六进制格式的私钥 |
+| `relays`     | string[] | `['wss://relay.damus.io', 'wss://nos.lol']` | 中继 URL（WebSocket）       |
+| `dmPolicy`   | string   | `pairing`                                   | 私信访问策略                |
+| `allowFrom`  | string[] | `[]`                                        | 允许的发送方公钥            |
+| `enabled`    | boolean  | `true`                                      | 启用 / 禁用渠道             |
+| `name`       | string   | -                                           | 显示名称                    |
+| `profile`    | object   | -                                           | NIP-01 资料元数据           |
+
+## 资料元数据
+
+资料数据会作为 NIP-01 `kind:0` 事件发布。你可以在控制 UI 中管理它（Channels -> Nostr -> Profile），也可以直接在配置中设置。
+
+示例：
+
+```json
+{
+  "channels": {
+    "nostr": {
+      "privateKey": "${NOSTR_PRIVATE_KEY}",
+      "profile": {
+        "name": "quantumclaw",
+        "displayName": "QuantumClaw",
+        "about": "Personal assistant DM bot",
+        "picture": "https://example.com/avatar.png",
+        "banner": "https://example.com/banner.png",
+        "website": "https://example.com",
+        "nip05": "quantumclaw@example.com",
+        "lud16": "quantumclaw@example.com"
+      }
+    }
+  }
+}
+```
+
+注意：
+
+- 资料 URL 必须使用 `https://`。
+- 从中继导入时会合并字段，并保留本地覆盖项。
+
+## 访问控制
+
+### 私信策略
+
+- **pairing**（默认）：未知发送方会收到一个配对码。
+- **allowlist**：只有 `allowFrom` 中的公钥可以发送私信。
+- **open**：公开接收入站私信（要求 `allowFrom: ["*"]`）。
+- **disabled**：忽略入站私信。
+
+### 允许列表示例
+
+```json
+{
+  "channels": {
+    "nostr": {
+      "privateKey": "${NOSTR_PRIVATE_KEY}",
+      "dmPolicy": "allowlist",
+      "allowFrom": ["npub1abc...", "npub1xyz..."]
+    }
+  }
+}
+```
+
+## 密钥格式
+
+接受的格式：
+
+- **私钥：** `nsec...` 或 64 字符十六进制
+- **公钥（`allowFrom`）：** `npub...` 或十六进制
+
+## 中继
+
+默认值：`relay.damus.io` 和 `nos.lol`。
+
+```json
+{
+  "channels": {
+    "nostr": {
+      "privateKey": "${NOSTR_PRIVATE_KEY}",
+      "relays": ["wss://relay.damus.io", "wss://relay.primal.net", "wss://nostr.wine"]
+    }
+  }
+}
+```
+
+提示：
+
+- 使用 2 到 3 个中继以实现冗余。
+- 避免使用过多中继（延迟、重复）。
+- 付费中继可以提高可靠性。
+- 本地中继也适合测试（`ws://localhost:7777`）。
+
+## 协议支持
+
+| NIP    | 状态   | 说明                      |
+| ------ | ------ | ------------------------- |
+| NIP-01 | 已支持 | 基础事件格式 + 资料元数据 |
+| NIP-04 | 已支持 | 加密私信（`kind:4`）      |
+| NIP-17 | 计划中 | Gift-wrapped 私信         |
+| NIP-44 | 计划中 | 版本化加密                |
+
+## 测试
+
+### 本地中继
+
+```bash
+# Start strfry
+docker run -p 7777:7777 ghcr.io/hoytech/strfry
+```
+
+```json
+{
+  "channels": {
+    "nostr": {
+      "privateKey": "${NOSTR_PRIVATE_KEY}",
+      "relays": ["ws://localhost:7777"]
+    }
+  }
+}
+```
+
+### 手动测试
+
+1. 从日志中记下机器人公钥（npub）。
+2. 打开一个 Nostr 客户端（Damus、Amethyst 等）。
+3. 向该机器人公钥发送私信。
+4. 验证回复。
+
+## 故障排除
+
+### 未接收到消息
+
+- 验证私钥有效。
+- 确保中继 URL 可访问，并使用 `wss://`（本地则使用 `ws://`）。
+- 确认 `enabled` 不是 `false`。
+- 检查 Gateway 网关日志中的中继连接错误。
+
+### 未发送回复
+
+- 检查中继是否接受写入。
+- 验证出站连接性。
+- 注意中继速率限制。
+
+### 重复回复
+
+- 使用多个中继时这是预期行为。
+- 消息会按事件 ID 去重；只有首次投递会触发回复。
+
+## 安全性
+
+- 切勿提交私钥。
+- 对密钥使用环境变量。
+- 对生产机器人考虑使用 `allowlist`。
+
+## 限制（MVP）
+
+- 仅支持私信（不支持群聊）。
+- 不支持媒体附件。
+- 仅支持 NIP-04（计划支持 NIP-17 gift-wrap）。

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

@@ -0,0 +1,89 @@
+---
+read_when:
+  - 设置私信访问控制
+  - 配对新的 iOS/Android 节点
+  - 审查 QuantumClaw 安全态势
+summary: 配对概述：批准谁可以向你发送私信 + 哪些节点可以加入
+title: 配对
+x-i18n:
+  generated_at: "2026-02-03T07:54:19Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: c46a5c39f289c8fd0783baacd927f550c3d3ae8889a7bc7de133b795f16fa08a
+  source_path: channels/pairing.md
+  workflow: 15
+---
+
+# 配对
+
+"配对"是 QuantumClaw 的显式**所有者批准**步骤。它用于两个地方：
+
+1. **私信配对**（谁被允许与机器人对话）
+2. **节点配对**（哪些设备/节点被允许加入 Gateway 网关网络）
+
+安全上下文：[安全](/gateway/security)
+
+## 1）私信配对（入站聊天访问）
+
+当渠道配置为私信策略 `pairing` 时，未知发送者会收到一个短代码，他们的消息**不会被处理**，直到你批准。
+
+默认私信策略记录在：[安全](/gateway/security)
+
+配对代码：
+
+- 8 个字符，大写，无歧义字符（`0O1I`）。
+- **1 小时后过期**。机器人仅在创建新请求时发送配对消息（大约每个发送者每小时一次）。
+- 待处理的私信配对请求默认上限为**每个渠道 3 个**；在一个过期或被批准之前，额外的请求将被忽略。
+
+### 批准发送者
+
+```bash
+quantumclaw pairing list telegram
+quantumclaw pairing approve telegram <CODE>
+```
+
+支持的渠道：`telegram`、`whatsapp`、`signal`、`imessage`、`discord`、`slack`。
+
+### 状态存储位置
+
+存储在 `~/.quantumclaw/credentials/` 下：
+
+- 待处理请求：`<channel>-pairing.json`
+- 已批准允许列表存储：`<channel>-allowFrom.json`
+
+将这些视为敏感信息（它们控制对你助手的访问）。
+
+## 2）节点设备配对（iOS/Android/macOS/无头节点）
+
+节点作为 `role: node` 的**设备**连接到 Gateway 网关。Gateway 网关创建一个必须被批准的设备配对请求。
+
+### 批准节点设备
+
+```bash
+quantumclaw devices list
+quantumclaw devices approve <requestId>
+quantumclaw devices reject <requestId>
+```
+
+### 状态存储位置
+
+存储在 `~/.quantumclaw/devices/` 下：
+
+- `pending.json`（短期；待处理请求会过期）
+- `paired.json`（已配对设备 + 令牌）
+
+### 说明
+
+- 旧版 `node.pair.*` API（CLI：`quantumclaw nodes pending/approve`）是一个单独的 Gateway 网关拥有的配对存储。WS 节点仍然需要设备配对。
+
+## 相关文档
+
+- 安全模型 + 提示注入：[安全](/gateway/security)
+- 安全更新（运行 doctor）：[更新](/install/updating)
+- 渠道配置：
+  - Telegram：[Telegram](/channels/telegram)
+  - WhatsApp：[WhatsApp](/channels/whatsapp)
+  - Signal：[Signal](/channels/signal)
+  - iMessage：[iMessage](/channels/imessage)
+  - Discord：[Discord](/channels/discord)
+  - Slack：[Slack](/channels/slack)

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

@@ -0,0 +1,209 @@
+---
+read_when:
+  - 设置 Signal 支持
+  - 调试 Signal 发送/接收
+summary: 通过 signal-cli（JSON-RPC + SSE）支持 Signal，设置和号码模型
+title: Signal
+x-i18n:
+  generated_at: "2026-02-03T07:44:15Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: ca4de8b3685017f54a959e3e2699357ab40b3e4e68574bd7fb5739e4679e7d8a
+  source_path: channels/signal.md
+  workflow: 15
+---
+
+# Signal (signal-cli)
+
+状态：外部 CLI 集成。Gateway 网关通过 HTTP JSON-RPC + SSE 与 `signal-cli` 通信。
+
+## 快速设置（初学者）
+
+1. 为 bot 使用**单独的 Signal 号码**（推荐）。
+2. 安装 `signal-cli`（需要 Java）。
+3. 链接 bot 设备并启动守护进程：
+   - `signal-cli link -n "QuantumClaw"`
+4. 配置 QuantumClaw 并启动 Gateway 网关。
+
+最小配置：
+
+```json5
+{
+  channels: {
+    signal: {
+      enabled: true,
+      account: "+15551234567",
+      cliPath: "signal-cli",
+      dmPolicy: "pairing",
+      allowFrom: ["+15557654321"],
+    },
+  },
+}
+```
+
+## 它是什么
+
+- 通过 `signal-cli` 的 Signal 渠道（非嵌入式 libsignal）。
+- 确定性路由：回复始终返回到 Signal。
+- 私信共享智能体的主会话；群组是隔离的（`agent:<agentId>:signal:group:<groupId>`）。
+
+## 配置写入
+
+默认情况下，Signal 允许写入由 `/config set|unset` 触发的配置更新（需要 `commands.config: true`）。
+
+禁用方式：
+
+```json5
+{
+  channels: { signal: { configWrites: false } },
+}
+```
+
+## 号码模型（重要）
+
+- Gateway 网关连接到一个 **Signal 设备**（`signal-cli` 账户）。
+- 如果你在**个人 Signal 账户**上运行 bot，它会忽略你自己的消息（循环保护）。
+- 要实现"我发消息给 bot 然后它回复"，请使用**单独的 bot 号码**。
+
+## 设置（快速路径）
+
+1. 安装 `signal-cli`（需要 Java）。
+2. 链接 bot 账户：
+   - `signal-cli link -n "QuantumClaw"` 然后在 Signal 中扫描二维码。
+3. 配置 Signal 并启动 Gateway 网关。
+
+示例：
+
+```json5
+{
+  channels: {
+    signal: {
+      enabled: true,
+      account: "+15551234567",
+      cliPath: "signal-cli",
+      dmPolicy: "pairing",
+      allowFrom: ["+15557654321"],
+    },
+  },
+}
+```
+
+多账户支持：使用 `channels.signal.accounts` 配置每个账户及可选的 `name`。共享模式请参见 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts)。
+
+## 外部守护进程模式（httpUrl）
+
+如果你想自己管理 `signal-cli`（JVM 冷启动慢、容器初始化或共享 CPU），请单独运行守护进程并将 QuantumClaw 指向它：
+
+```json5
+{
+  channels: {
+    signal: {
+      httpUrl: "http://127.0.0.1:8080",
+      autoStart: false,
+    },
+  },
+}
+```
+
+这会跳过自动启动和 QuantumClaw 内部的启动等待。对于自动启动时的慢启动，请设置 `channels.signal.startupTimeoutMs`。
+
+## 访问控制（私信 + 群组）
+
+私信：
+
+- 默认：`channels.signal.dmPolicy = "pairing"`。
+- 未知发送者会收到配对码；消息在批准前会被忽略（配对码 1 小时后过期）。
+- 通过以下方式批准：
+  - `quantumclaw pairing list signal`
+  - `quantumclaw pairing approve signal <CODE>`
+- 配对是 Signal 私信的默认令牌交换方式。详情：[配对](/channels/pairing)
+- 仅有 UUID 的发送者（来自 `sourceUuid`）在 `channels.signal.allowFrom` 中存储为 `uuid:<id>`。
+
+群组：
+
+- `channels.signal.groupPolicy = open | allowlist | disabled`。
+- 当设置为 `allowlist` 时，`channels.signal.groupAllowFrom` 控制谁可以在群组中触发。
+
+## 工作原理（行为）
+
+- `signal-cli` 作为守护进程运行；Gateway 网关通过 SSE 读取事件。
+- 入站消息被规范化为共享渠道信封。
+- 回复始终路由回同一号码或群组。
+
+## 媒体 + 限制
+
+- 出站文本按 `channels.signal.textChunkLimit` 分块（默认 4000）。
+- 可选换行分块：设置 `channels.signal.chunkMode="newline"` 在长度分块前按空行（段落边界）分割。
+- 支持附件（从 `signal-cli` 获取 base64）。
+- 默认媒体上限：`channels.signal.mediaMaxMb`（默认 8）。
+- 使用 `channels.signal.ignoreAttachments` 跳过下载媒体。
+- 群组历史上下文使用 `channels.signal.historyLimit`（或 `channels.signal.accounts.*.historyLimit`），回退到 `messages.groupChat.historyLimit`。设置 `0` 禁用（默认 50）。
+
+## 输入指示器 + 已读回执
+
+- **输入指示器**：QuantumClaw 通过 `signal-cli sendTyping` 发送输入信号，并在回复运行时刷新它们。
+- **已读回执**：当 `channels.signal.sendReadReceipts` 为 true 时，QuantumClaw 为允许的私信转发已读回执。
+- Signal-cli 不暴露群组的已读回执。
+
+## 表情回应（message 工具）
+
+- 使用 `message action=react` 配合 `channel=signal`。
+- 目标：发送者 E.164 或 UUID（使用配对输出中的 `uuid:<id>`；裸 UUID 也可以）。
+- `messageId` 是你要回应的消息的 Signal 时间戳。
+- 群组表情回应需要 `targetAuthor` 或 `targetAuthorUuid`。
+
+示例：
+
+```
+message action=react channel=signal target=uuid:123e4567-e89b-12d3-a456-426614174000 messageId=1737630212345 emoji=🔥
+message action=react channel=signal target=+15551234567 messageId=1737630212345 emoji=🔥 remove=true
+message action=react channel=signal target=signal:group:<groupId> targetAuthor=uuid:<sender-uuid> messageId=1737630212345 emoji=✅
+```
+
+配置：
+
+- `channels.signal.actions.reactions`：启用/禁用表情回应操作（默认 true）。
+- `channels.signal.reactionLevel`：`off | ack | minimal | extensive`。
+  - `off`/`ack` 禁用智能体表情回应（message 工具 `react` 会报错）。
+  - `minimal`/`extensive` 启用智能体表情回应并设置指导级别。
+- 每账户覆盖：`channels.signal.accounts.<id>.actions.reactions`、`channels.signal.accounts.<id>.reactionLevel`。
+
+## 投递目标（CLI/cron）
+
+- 私信：`signal:+15551234567`（或纯 E.164）。
+- UUID 私信：`uuid:<id>`（或裸 UUID）。
+- 群组：`signal:group:<groupId>`。
+- 用户名：`username:<name>`（如果你的 Signal 账户支持）。
+
+## 配置参考（Signal）
+
+完整配置：[配置](/gateway/configuration)
+
+提供商选项：
+
+- `channels.signal.enabled`：启用/禁用渠道启动。
+- `channels.signal.account`：bot 账户的 E.164。
+- `channels.signal.cliPath`：`signal-cli` 的路径。
+- `channels.signal.httpUrl`：完整守护进程 URL（覆盖 host/port）。
+- `channels.signal.httpHost`、`channels.signal.httpPort`：守护进程绑定（默认 127.0.0.1:8080）。
+- `channels.signal.autoStart`：自动启动守护进程（如果未设置 `httpUrl` 则默认 true）。
+- `channels.signal.startupTimeoutMs`：启动等待超时（毫秒）（上限 120000）。
+- `channels.signal.receiveMode`：`on-start | manual`。
+- `channels.signal.ignoreAttachments`：跳过附件下载。
+- `channels.signal.ignoreStories`：忽略来自守护进程的动态。
+- `channels.signal.sendReadReceipts`：转发已读回执。
+- `channels.signal.dmPolicy`：`pairing | allowlist | open | disabled`（默认：pairing）。
+- `channels.signal.allowFrom`：私信允许列表（E.164 或 `uuid:<id>`）。`open` 需要 `"*"`。Signal 没有用户名；使用电话/UUID id。
+- `channels.signal.groupPolicy`：`open | allowlist | disabled`（默认：allowlist）。
+- `channels.signal.groupAllowFrom`：群组发送者允许列表。
+- `channels.signal.historyLimit`：作为上下文包含的最大群组消息数（0 禁用）。
+- `channels.signal.dmHistoryLimit`：私信历史限制（用户轮次）。每用户覆盖：`channels.signal.dms["<phone_or_uuid>"].historyLimit`。
+- `channels.signal.textChunkLimit`：出站分块大小（字符）。
+- `channels.signal.chunkMode`：`length`（默认）或 `newline` 在长度分块前按空行（段落边界）分割。
+- `channels.signal.mediaMaxMb`：入站/出站媒体上限（MB）。
+
+相关全局选项：
+
+- `agents.list[].groupChat.mentionPatterns`（Signal 不支持原生提及）。
+- `messages.groupChat.mentionPatterns`（全局回退）。
+- `messages.responsePrefix`。