@gguf/claw 2026.2.1 → 2026.2.2

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

@@ -0,0 +1,180 @@
+---
+read_when:
+  - 你想将 OpenClaw 连接到 LINE
+  - 你需要 LINE webhook + 凭据设置
+  - 你需要 LINE 特定的消息选项
+summary: LINE Messaging API 插件设置、配置和使用
+title: LINE
+x-i18n:
+  generated_at: "2026-02-01T19:21:38Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 8fbac126786f95b9454f3cc61906c2798393a8d7914e787d3755c020c7ab2da6
+  source_path: channels/line.md
+  workflow: 14
+---
+
+# LINE（插件）
+
+LINE 通过 LINE Messaging API 连接到 OpenClaw。插件作为 Gateway网关上的 webhook 接收器运行，使用你的频道访问 token + 频道密钥进行认证。
+
+状态：通过插件支持。支持私信、群聊、媒体、位置、Flex 消息、模板消息和快速回复。不支持回应和线程。
+
+## 需要插件
+
+安装 LINE 插件：
+
+```bash
+openclaw plugins install @openclaw/line
+```
+
+本地检出（从 git 仓库运行时）：
+
+```bash
+openclaw plugins install ./extensions/line
+```
+
+## 设置
+
+1. 创建 LINE Developers 账户并打开控制台：
+   https://developers.line.biz/console/
+2. 创建（或选择）一个 Provider 并添加一个 **Messaging API** 频道。
+3. 从频道设置中复制 **Channel access token** 和 **Channel secret**。
+4. 在 Messaging API 设置中启用 **Use webhook**。
+5. 将 webhook URL 设置为你的 Gateway网关端点（需要 HTTPS）：
+
+```
+https://gateway-host/line/webhook
+```
+
+Gateway网关响应 LINE 的 webhook 验证（GET）和入站事件（POST）。如果你需要自定义路径，请设置 `channels.line.webhookPath` 或 `channels.line.accounts.<id>.webhookPath` 并相应更新 URL。
+
+## 配置
+
+最小配置：
+
+```json5
+{
+  channels: {
+    line: {
+      enabled: true,
+      channelAccessToken: "LINE_CHANNEL_ACCESS_TOKEN",
+      channelSecret: "LINE_CHANNEL_SECRET",
+      dmPolicy: "pairing",
+    },
+  },
+}
+```
+
+环境变量（仅默认账户）：
+
+- `LINE_CHANNEL_ACCESS_TOKEN`
+- `LINE_CHANNEL_SECRET`
+
+Token/密钥文件：
+
+```json5
+{
+  channels: {
+    line: {
+      tokenFile: "/path/to/line-token.txt",
+      secretFile: "/path/to/line-secret.txt",
+    },
+  },
+}
+```
+
+多账户：
+
+```json5
+{
+  channels: {
+    line: {
+      accounts: {
+        marketing: {
+          channelAccessToken: "...",
+          channelSecret: "...",
+          webhookPath: "/line/marketing",
+        },
+      },
+    },
+  },
+}
+```
+
+## 访问控制
+
+私信默认需要配对。未知发送者会收到配对码，在批准之前其消息会被忽略。
+
+```bash
+openclaw pairing list line
+openclaw pairing approve line <CODE>
+```
+
+允许列表和策略：
+
+- `channels.line.dmPolicy`：`pairing | allowlist | open | disabled`
+- `channels.line.allowFrom`：私信的允许 LINE 用户 ID 列表
+- `channels.line.groupPolicy`：`allowlist | open | disabled`
+- `channels.line.groupAllowFrom`：群组的允许 LINE 用户 ID 列表
+- 按群组覆盖：`channels.line.groups.<groupId>.allowFrom`
+
+LINE ID 区分大小写。有效的 ID 格式如下：
+
+- 用户：`U` + 32 位十六进制字符
+- 群组：`C` + 32 位十六进制字符
+- 房间：`R` + 32 位十六进制字符
+
+## 消息行为
+
+- 文本在 5000 字符处分块。
+- Markdown 格式会被去除；代码块和表格在可能时会转换为 Flex 卡片。
+- 流式响应会被缓冲；智能体工作时 LINE 接收完整分块并显示加载动画。
+- 媒体下载上限由 `channels.line.mediaMaxMb` 限制（默认 10）。
+
+## 渠道数据（富消息）
+
+使用 `channelData.line` 发送快速回复、位置、Flex 卡片或模板消息。
+
+```json5
+{
+  text: "Here you go",
+  channelData: {
+    line: {
+      quickReplies: ["Status", "Help"],
+      location: {
+        title: "Office",
+        address: "123 Main St",
+        latitude: 35.681236,
+        longitude: 139.767125,
+      },
+      flexMessage: {
+        altText: "Status card",
+        contents: {
+          /* Flex 负载 */
+        },
+      },
+      templateMessage: {
+        type: "confirm",
+        text: "Proceed?",
+        confirmLabel: "Yes",
+        confirmData: "yes",
+        cancelLabel: "No",
+        cancelData: "no",
+      },
+    },
+  },
+}
+```
+
+LINE 插件还附带一个 `/card` 命令用于 Flex 消息预设：
+
+```
+/card info "Welcome" "Thanks for joining!"
+```
+
+## 故障排除
+
+- **Webhook 验证失败：** 确保 webhook URL 为 HTTPS 且 `channelSecret` 与 LINE 控制台匹配。
+- **没有入站事件：** 确认 webhook 路径与 `channels.line.webhookPath` 匹配且 Gateway网关可从 LINE 访问。
+- **媒体下载错误：** 如果媒体超过默认限制，请增大 `channels.line.mediaMaxMb`。

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

@@ -0,0 +1,63 @@
+---
+read_when:
+  - 添加或修改渠道位置解析
+  - 在智能体提示或工具中使用位置上下文字段
+summary: 入站渠道位置解析（Telegram + WhatsApp）及上下文字段
+title: 渠道位置解析
+x-i18n:
+  generated_at: "2026-02-01T19:21:46Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 5602ef105c3da7e47497bfed8fc343dd8d7f3c019ff7e423a08b25092c5a1837
+  source_path: channels/location.md
+  workflow: 14
+---
+
+# 渠道位置解析
+
+OpenClaw 将聊天渠道中分享的位置标准化为：
+
+- 附加到入站消息体的可读文本，以及
+- 自动回复上下文负载中的结构化字段。
+
+目前支持：
+
+- **Telegram**（位置图钉 + 地点 + 实时位置）
+- **WhatsApp**（locationMessage + liveLocationMessage）
+- **Matrix**（`m.location` 配合 `geo_uri`）
+
+## 文本格式
+
+位置以友好的行格式呈现，不带括号：
+
+- 图钉：
+  - `📍 48.858844, 2.294351 ±12m`
+- 命名地点：
+  - `📍 Eiffel Tower — Champ de Mars, Paris (48.858844, 2.294351 ±12m)`
+- 实时分享：
+  - `🛰 Live location: 48.858844, 2.294351 ±12m`
+
+如果渠道包含标题/评论，会附加在下一行：
+
+```
+📍 48.858844, 2.294351 ±12m
+Meet here
+```
+
+## 上下文字段
+
+当存在位置信息时，以下字段会被添加到 `ctx` 中：
+
+- `LocationLat`（数字）
+- `LocationLon`（数字）
+- `LocationAccuracy`（数字，米；可选）
+- `LocationName`（字符串；可选）
+- `LocationAddress`（字符串；可选）
+- `LocationSource`（`pin | place | live`）
+- `LocationIsLive`（布尔值）
+
+## 渠道说明
+
+- **Telegram**：地点映射到 `LocationName/LocationAddress`；实时位置使用 `live_period`。
+- **WhatsApp**：`locationMessage.comment` 和 `liveLocationMessage.caption` 作为标题行附加。
+- **Matrix**：`geo_uri` 解析为图钉位置；忽略海拔高度，`LocationIsLive` 始终为 false。

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

@@ -0,0 +1,221 @@
+---
+read_when:
+  - 开发 Matrix 渠道功能
+summary: Matrix 支持状态、功能和配置
+title: Matrix
+x-i18n:
+  generated_at: "2026-02-01T19:22:24Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b276b5263593c766e7be6549abbb27927177e7b51cfd297b4825965372513ee4
+  source_path: channels/matrix.md
+  workflow: 14
+---
+
+# Matrix（插件）
+
+Matrix 是一个开放、去中心化的消息协议。OpenClaw 作为 Matrix **用户**连接到任何主服务器，因此你需要为机器人创建一个 Matrix 账户。登录后，你可以直接私信机器人或邀请它加入房间（Matrix 的"群组"）。Beeper 也是一个可用的客户端选项，但它需要启用端到端加密。
+
+状态：通过插件支持（@vector-im/matrix-bot-sdk）。支持私信、房间、线程、媒体、回应、投票（发送 + poll-start 转为文本）、位置和端到端加密（需要加密支持）。
+
+## 需要插件
+
+Matrix 作为插件发布，不包含在核心安装中。
+
+通过 CLI 安装（npm 注册表）：
+
+```bash
+openclaw plugins install @openclaw/matrix
+```
+
+本地检出（从 git 仓库运行时）：
+
+```bash
+openclaw plugins install ./extensions/matrix
+```
+
+如果你在配置/新手引导期间选择了 Matrix 并检测到 git 检出，OpenClaw 会自动提供本地安装路径。
+
+详情：[插件](/plugin)
+
+## 设置
+
+1. 安装 Matrix 插件：
+   - 从 npm：`openclaw plugins install @openclaw/matrix`
+   - 从本地检出：`openclaw plugins install ./extensions/matrix`
+2. 在主服务器上创建 Matrix 账户：
+   - 在 [https://matrix.org/ecosystem/hosting/](https://matrix.org/ecosystem/hosting/) 浏览托管选项
+   - 或自行托管。
+3. 获取机器人账户的访问 token：
+   - 在你的主服务器上使用 Matrix 登录 API 配合 `curl`：
+
+   ```bash
+   curl --request POST \
+     --url https://matrix.example.org/_matrix/client/v3/login \
+     --header 'Content-Type: application/json' \
+     --data '{
+     "type": "m.login.password",
+     "identifier": {
+       "type": "m.id.user",
+       "user": "your-user-name"
+     },
+     "password": "your-password"
+   }'
+   ```
+
+   - 将 `matrix.example.org` 替换为你的主服务器 URL。
+   - 或设置 `channels.matrix.userId` + `channels.matrix.password`：OpenClaw 调用相同的登录端点，将访问 token 存储在 `~/.openclaw/credentials/matrix/credentials.json` 中，并在下次启动时重用。
+
+4. 配置凭据：
+   - 环境变量：`MATRIX_HOMESERVER`、`MATRIX_ACCESS_TOKEN`（或 `MATRIX_USER_ID` + `MATRIX_PASSWORD`）
+   - 或配置：`channels.matrix.*`
+   - 如果两者都设置了，配置优先。
+   - 使用访问 token 时：用户 ID 通过 `/whoami` 自动获取。
+   - 设置时，`channels.matrix.userId` 应为完整的 Matrix ID（例如：`@bot:example.org`）。
+5. 重启 Gateway网关（或完成新手引导）。
+6. 从任何 Matrix 客户端（Element、Beeper 等；参见 https://matrix.org/ecosystem/clients/）与机器人开始私信或邀请它加入房间。Beeper 需要端到端加密，因此请设置 `channels.matrix.encryption: true` 并验证设备。
+
+最小配置（访问 token，用户 ID 自动获取）：
+
+```json5
+{
+  channels: {
+    matrix: {
+      enabled: true,
+      homeserver: "https://matrix.example.org",
+      accessToken: "syt_***",
+      dm: { policy: "pairing" },
+    },
+  },
+}
+```
+
+端到端加密配置（启用端到端加密）：
+
+```json5
+{
+  channels: {
+    matrix: {
+      enabled: true,
+      homeserver: "https://matrix.example.org",
+      accessToken: "syt_***",
+      encryption: true,
+      dm: { policy: "pairing" },
+    },
+  },
+}
+```
+
+## 加密（端到端加密）
+
+端到端加密通过 Rust 加密 SDK **支持**。
+
+通过 `channels.matrix.encryption: true` 启用：
+
+- 如果加密模块加载成功，加密房间会自动解密。
+- 向加密房间发送时，出站媒体会被加密。
+- 首次连接时，OpenClaw 会从你的其他会话请求设备验证。
+- 在另一个 Matrix 客户端（Element 等）中验证设备以启用密钥共享。
+- 如果加密模块无法加载，端到端加密将被禁用且加密房间无法解密；OpenClaw 会记录警告。
+- 如果你看到缺少加密模块的错误（例如 `@matrix-org/matrix-sdk-crypto-nodejs-*`），请允许 `@matrix-org/matrix-sdk-crypto-nodejs` 的构建脚本并运行 `pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs` 或通过 `node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js` 获取二进制文件。
+
+加密状态按账户 + 访问 token 存储在 `~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/`（SQLite 数据库）。同步状态存储在同一目录下的 `bot-storage.json` 中。如果访问 token（设备）发生变化，会创建新的存储，机器人必须重新验证才能在加密房间中使用。
+
+**设备验证：**
+启用端到端加密后，机器人会在启动时从你的其他会话请求验证。打开 Element（或其他客户端）并批准验证请求以建立信任。验证完成后，机器人可以解密加密房间中的消息。
+
+## 路由模型
+
+- 回复始终发回 Matrix。
+- 私信共享智能体的主会话；房间映射到群组会话。
+
+## 访问控制（私信）
+
+- 默认：`channels.matrix.dm.policy = "pairing"`。未知发送者会收到配对码。
+- 通过以下方式批准：
+  - `openclaw pairing list matrix`
+  - `openclaw pairing approve matrix <CODE>`
+- 公开私信：`channels.matrix.dm.policy="open"` 加上 `channels.matrix.dm.allowFrom=["*"]`。
+- `channels.matrix.dm.allowFrom` 接受用户 ID 或显示名称。向导在目录搜索可用时会将显示名称解析为用户 ID。
+
+## 房间（群组）
+
+- 默认：`channels.matrix.groupPolicy = "allowlist"`（提及门控）。使用 `channels.defaults.groupPolicy` 可在未设置时覆盖默认值。
+- 使用 `channels.matrix.groups` 允许列表中的房间（房间 ID、别名或名称）：
+
+```json5
+{
+  channels: {
+    matrix: {
+      groupPolicy: "allowlist",
+      groups: {
+        "!roomId:example.org": { allow: true },
+        "#alias:example.org": { allow: true },
+      },
+      groupAllowFrom: ["@owner:example.org"],
+    },
+  },
+}
+```
+
+- `requireMention: false` 启用该房间的自动回复。
+- `groups."*"` 可以设置跨房间的提及门控默认值。
+- `groupAllowFrom` 限制哪些发送者可以在房间中触发机器人（可选）。
+- 按房间的 `users` 允许列表可以进一步限制特定房间内的发送者。
+- 配置向导会提示输入房间允许列表（房间 ID、别名或名称）并在可能时解析名称。
+- 启动时，OpenClaw 将允许列表中的房间/用户名称解析为 ID 并记录映射；未解析的条目保持原样。
+- 邀请默认自动加入；通过 `channels.matrix.autoJoin` 和 `channels.matrix.autoJoinAllowlist` 控制。
+- 要**不允许任何房间**，设置 `channels.matrix.groupPolicy: "disabled"`（或保持空的允许列表）。
+- 旧版键：`channels.matrix.rooms`（与 `groups` 结构相同）。
+
+## 线程
+
+- 支持回复线程。
+- `channels.matrix.threadReplies` 控制回复是否保持在线程中：
+  - `off`、`inbound`（默认）、`always`
+- `channels.matrix.replyToMode` 控制不在线程中回复时的 reply-to 元数据：
+  - `off`（默认）、`first`、`all`
+
+## 功能
+
+| 功能       | 状态                                                       |
+| ---------- | ---------------------------------------------------------- |
+| 私信       | ✅ 支持                                                    |
+| 房间       | ✅ 支持                                                    |
+| 线程       | ✅ 支持                                                    |
+| 媒体       | ✅ 支持                                                    |
+| 端到端加密 | ✅ 支持（需要加密模块）                                    |
+| 回应       | ✅ 支持（通过工具发送/读取）                               |
+| 投票       | ✅ 支持发送；入站 poll start 转换为文本（响应/结束被忽略） |
+| 位置       | ✅ 支持（geo URI；忽略海拔）                               |
+| 原生命令   | ✅ 支持                                                    |
+
+## 配置参考（Matrix）
+
+完整配置：[配置](/gateway/configuration)
+
+提供商选项：
+
+- `channels.matrix.enabled`：启用/禁用渠道启动。
+- `channels.matrix.homeserver`：主服务器 URL。
+- `channels.matrix.userId`：Matrix 用户 ID（使用访问 token 时可选）。
+- `channels.matrix.accessToken`：访问 token。
+- `channels.matrix.password`：登录密码（token 会被存储）。
+- `channels.matrix.deviceName`：设备显示名称。
+- `channels.matrix.encryption`：启用端到端加密（默认：false）。
+- `channels.matrix.initialSyncLimit`：初始同步限制。
+- `channels.matrix.threadReplies`：`off | inbound | always`（默认：inbound）。
+- `channels.matrix.textChunkLimit`：出站文本分块大小（字符）。
+- `channels.matrix.chunkMode`：`length`（默认）或 `newline`，在按长度分块之前按空行（段落边界）分割。
+- `channels.matrix.dm.policy`：`pairing | allowlist | open | disabled`（默认：pairing）。
+- `channels.matrix.dm.allowFrom`：私信允许列表（用户 ID 或显示名称）。`open` 需要 `"*"`。向导在可能时将名称解析为 ID。
+- `channels.matrix.groupPolicy`：`allowlist | open | disabled`（默认：allowlist）。
+- `channels.matrix.groupAllowFrom`：群组消息的允许发送者列表。
+- `channels.matrix.allowlistOnly`：强制对私信 + 房间执行允许列表规则。
+- `channels.matrix.groups`：群组允许列表 + 按房间设置映射。
+- `channels.matrix.rooms`：旧版群组允许列表/配置。
+- `channels.matrix.replyToMode`：线程/标签的 reply-to 模式。
+- `channels.matrix.mediaMaxMb`：入站/出站媒体上限（MB）。
+- `channels.matrix.autoJoin`：邀请处理（`always | allowlist | off`，默认：always）。
+- `channels.matrix.autoJoinAllowlist`：自动加入的允许房间 ID/别名。
+- `channels.matrix.actions`：按操作的工具门控（reactions/messages/pins/memberInfo/channelInfo）。

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

@@ -0,0 +1,142 @@
+---
+read_when:
+  - 设置 Mattermost
+  - 调试 Mattermost 路由
+summary: Mattermost 机器人设置和 OpenClaw 配置
+title: Mattermost
+x-i18n:
+  generated_at: "2026-02-01T19:22:40Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 57fabe5eb0efbcb885f4178b317b2fa99a41daf609e3a471de2b44db9def4ad7
+  source_path: channels/mattermost.md
+  workflow: 14
+---
+
+# Mattermost（插件）
+
+状态：通过插件支持（bot token + WebSocket 事件）。支持频道、群组和私信。Mattermost 是一个可自托管的团队消息平台；有关产品详情和下载请访问官方网站 [mattermost.com](https://mattermost.com)。
+
+## 需要插件
+
+Mattermost 作为插件发布，不包含在核心安装中。
+
+通过 CLI 安装（npm 注册表）：
+
+```bash
+openclaw plugins install @openclaw/mattermost
+```
+
+本地检出（从 git 仓库运行时）：
+
+```bash
+openclaw plugins install ./extensions/mattermost
+```
+
+如果你在配置/新手引导期间选择了 Mattermost 并检测到 git 检出，OpenClaw 会自动提供本地安装路径。
+
+详情：[插件](/plugin)
+
+## 快速设置
+
+1. 安装 Mattermost 插件。
+2. 创建一个 Mattermost 机器人账户并复制 **bot token**。
+3. 复制 Mattermost **基础 URL**（例如 `https://chat.example.com`）。
+4. 配置 OpenClaw 并启动 Gateway网关。
+
+最小配置：
+
+```json5
+{
+  channels: {
+    mattermost: {
+      enabled: true,
+      botToken: "mm-token",
+      baseUrl: "https://chat.example.com",
+      dmPolicy: "pairing",
+    },
+  },
+}
+```
+
+## 环境变量（默认账户）
+
+如果你偏好使用环境变量，请在 Gateway网关主机上设置：
+
+- `MATTERMOST_BOT_TOKEN=...`
+- `MATTERMOST_URL=https://chat.example.com`
+
+环境变量仅适用于**默认**账户（`default`）。其他账户必须使用配置值。
+
+## 聊天模式
+
+Mattermost 自动响应私信。频道行为由 `chatmode` 控制：
+
+- `oncall`（默认）：仅在频道中被 @提及时响应。
+- `onmessage`：响应频道中的每条消息。
+- `onchar`：当消息以触发前缀开头时响应。
+
+配置示例：
+
+```json5
+{
+  channels: {
+    mattermost: {
+      chatmode: "onchar",
+      oncharPrefixes: [">", "!"],
+    },
+  },
+}
+```
+
+注意事项：
+
+- `onchar` 模式仍然响应明确的 @提及。
+- `channels.mattermost.requireMention` 对旧版配置仍然有效，但推荐使用 `chatmode`。
+
+## 访问控制（私信）
+
+- 默认：`channels.mattermost.dmPolicy = "pairing"`（未知发送者会收到配对码）。
+- 通过以下方式批准：
+  - `openclaw pairing list mattermost`
+  - `openclaw pairing approve mattermost <CODE>`
+- 公开私信：`channels.mattermost.dmPolicy="open"` 加上 `channels.mattermost.allowFrom=["*"]`。
+
+## 频道（群组）
+
+- 默认：`channels.mattermost.groupPolicy = "allowlist"`（提及门控）。
+- 使用 `channels.mattermost.groupAllowFrom` 允许列表发送者（用户 ID 或 `@username`）。
+- 开放频道：`channels.mattermost.groupPolicy="open"`（提及门控）。
+
+## 出站投递目标
+
+在 `openclaw message send` 或定时任务/webhook 中使用以下目标格式：
+
+- `channel:<id>` 用于频道
+- `user:<id>` 用于私信
+- `@username` 用于私信（通过 Mattermost API 解析）
+
+裸 ID 被视为频道。
+
+## 多账户
+
+Mattermost 支持在 `channels.mattermost.accounts` 下配置多个账户：
+
+```json5
+{
+  channels: {
+    mattermost: {
+      accounts: {
+        default: { name: "Primary", botToken: "mm-token", baseUrl: "https://chat.example.com" },
+        alerts: { name: "Alerts", botToken: "mm-token-2", baseUrl: "https://alerts.example.com" },
+      },
+    },
+  },
+}
+```
+
+## 故障排除
+
+- 频道中没有回复：确保机器人已加入频道并提及它（oncall 模式），使用触发前缀（onchar 模式），或设置 `chatmode: "onmessage"`。
+- 认证错误：检查 bot token、基础 URL 以及账户是否已启用。
+- 多账户问题：环境变量仅适用于 `default` 账户。