@termix-it/cryptoclaw 1.0.0

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
+openclaw plugins install @openclaw/nextcloud-talk
+```
+
+本地检出安装（从 git 仓库运行时）：
+
+```bash
+openclaw plugins install ./extensions/nextcloud-talk
+```
+
+如果你在配置/新手引导过程中选择了 Nextcloud Talk，并且检测到 git 检出，
+OpenClaw 将自动提供本地安装路径。
+
+详情：[插件](/plugin)
+
+## 快速设置（新手）
+
+1. 安装 Nextcloud Talk 插件。
+2. 在你的 Nextcloud 服务器上创建机器人：
+   ```bash
+   ./occ talk:bot:install "OpenClaw" "<shared-secret>" "<webhook-url>" --feature reaction
+   ```
+3. 在目标房间设置中启用机器人。
+4. 配置 OpenClaw：
+   - 配置项：`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"`。未知发送者将收到配对码。
+- 批准方式：
+  - `openclaw pairing list nextcloud-talk`
+  - `openclaw 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,240 @@
+---
+read_when:
+  - 你希望 OpenClaw 通过 Nostr 接收私信
+  - 你正在设置去中心化消息
+summary: 通过 NIP-04 加密消息的 Nostr 私信渠道
+title: Nostr
+x-i18n:
+  generated_at: "2026-02-03T07:44:13Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 6b9fe4c74bf5e7c0f59bbaa129ec5270fd29a248551a8a9a7dde6cff8fb46111
+  source_path: channels/nostr.md
+  workflow: 15
+---
+
+# Nostr
+
+**状态：** 可选插件（默认禁用）。
+
+Nostr 是一个去中心化的社交网络协议。此渠道使 OpenClaw 能够通过 NIP-04 接收和回复加密私信（DMs）。
+
+## 安装（按需）
+
+### 新手引导（推荐）
+
+- 新手引导向导（`openclaw onboard`）和 `openclaw channels add` 会列出可选的渠道插件。
+- 选择 Nostr 会提示你按需安装插件。
+
+安装默认值：
+
+- **Dev 渠道 + git checkout 可用：** 使用本地插件路径。
+- **Stable/Beta：** 从 npm 下载。
+
+你可以随时在提示中覆盖选择。
+
+### 手动安装
+
+```bash
+openclaw plugins install @openclaw/nostr
+```
+
+使用本地 checkout（开发工作流）：
+
+```bash
+openclaw plugins install --link <path-to-openclaw>/extensions/nostr
+```
+
+安装或启用插件后重启 Gateway 网关。
+
+## 快速设置
+
+1. 生成 Nostr 密钥对（如需要）：
+
+```bash
+# 使用 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` 事件发布。你可以从控制界面（Channels -> Nostr -> Profile）管理它，或直接在配置中设置。
+
+示例：
+
+```json
+{
+  "channels": {
+    "nostr": {
+      "privateKey": "${NOSTR_PRIVATE_KEY}",
+      "profile": {
+        "name": "openclaw",
+        "displayName": "OpenClaw",
+        "about": "Personal assistant DM bot",
+        "picture": "https://example.com/avatar.png",
+        "banner": "https://example.com/banner.png",
+        "website": "https://example.com",
+        "nip05": "openclaw@example.com",
+        "lud16": "openclaw@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 | 计划中 | 礼物包装私信                  |
+| NIP-44 | 计划中 | 版本化加密                    |
+
+## 测试
+
+### 本地中继
+
+```bash
+# 启动 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 礼物包装）。

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 "OpenClaw"`
+4. 配置 OpenClaw 并启动 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 "OpenClaw"` 然后在 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），请单独运行守护进程并将 OpenClaw 指向它：
+
+```json5
+{
+  channels: {
+    signal: {
+      httpUrl: "http://127.0.0.1:8080",
+      autoStart: false,
+    },
+  },
+}
+```
+
+这会跳过自动启动和 OpenClaw 内部的启动等待。对于自动启动时的慢启动，请设置 `channels.signal.startupTimeoutMs`。
+
+## 访问控制（私信 + 群组）
+
+私信：
+
+- 默认：`channels.signal.dmPolicy = "pairing"`。
+- 未知发送者会收到配对码；消息在批准前会被忽略（配对码 1 小时后过期）。
+- 通过以下方式批准：
+  - `openclaw pairing list signal`
+  - `openclaw pairing approve signal <CODE>`
+- 配对是 Signal 私信的默认令牌交换方式。详情：[配对](/start/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）。
+
+## 输入指示器 + 已读回执
+
+- **输入指示器**：OpenClaw 通过 `signal-cli sendTyping` 发送输入信号，并在回复运行时刷新它们。
+- **已读回执**：当 `channels.signal.sendReadReceipts` 为 true 时，OpenClaw 为允许的私信转发已读回执。
+- 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`。