mirror of
https://github.com/farcasclaudiu/openclaw.git
synced 2026-06-28 19:01:47 +03:00
Docs: normalize zh-CN terminology + tone
What: switch to 你/你的 tone; standardize Skills/Gateway网关/local loopback/私信 wording Why: align zh-CN docs with issue 6995 feedback + idiomatic tech style Tests: pnpm docs:build
This commit is contained in:
@@ -46,10 +46,10 @@ x-i18n:
|
||||
},
|
||||
}
|
||||
```
|
||||
4. 将 BlueBubbles webhooks 指向你的 Gateway(示例:`https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`)。
|
||||
5. 启动 Gateway;它将注册 webhook 处理器并开始配对。
|
||||
4. 将 BlueBubbles webhooks 指向你的 Gateway网关(示例:`https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`)。
|
||||
5. 启动 Gateway网关;它将注册 webhook 处理器并开始配对。
|
||||
|
||||
## 上手引导
|
||||
## 新手引导
|
||||
|
||||
BlueBubbles 可在交互式设置向导中使用:
|
||||
|
||||
@@ -255,12 +255,12 @@ OpenClaw 可能会呈现*短*消息 ID(例如 `1`、`2`)以节省 token。
|
||||
|
||||
- Webhook 请求通过将 `guid`/`password` 查询参数或请求头与 `channels.bluebubbles.password` 比较来进行认证。来自 `localhost` 的请求也会被接受。
|
||||
- 请保密 API 密码和 webhook 端点(将其视为凭证)。
|
||||
- localhost 信任意味着同主机的反向代理可能会无意间绕过密码。如果你为 Gateway 设置了代理,请在代理层要求认证并配置 `gateway.trustedProxies`。参见 [Gateway 安全](/gateway/security#reverse-proxy-configuration)。
|
||||
- localhost 信任意味着同主机的反向代理可能会无意间绕过密码。如果你为 Gateway网关设置了代理,请在代理层要求认证并配置 `gateway.trustedProxies`。参见 [Gateway网关安全](/gateway/security#reverse-proxy-configuration)。
|
||||
- 如果将 BlueBubbles 服务器暴露到局域网外部,请启用 HTTPS + 防火墙规则。
|
||||
|
||||
## 故障排除
|
||||
|
||||
- 如果输入/已读事件停止工作,请检查 BlueBubbles webhook 日志并验证 Gateway 路径是否与 `channels.bluebubbles.webhookPath` 匹配。
|
||||
- 如果输入/已读事件停止工作,请检查 BlueBubbles webhook 日志并验证 Gateway网关路径是否与 `channels.bluebubbles.webhookPath` 匹配。
|
||||
- 配对码在一小时后过期;使用 `openclaw pairing list bluebubbles` 和 `openclaw pairing approve bluebubbles <code>`。
|
||||
- 回应功能需要 BlueBubbles private API(`POST /api/v1/message/react`);请确保服务器版本已暴露该接口。
|
||||
- 编辑/撤回需要 macOS 13+ 和兼容的 BlueBubbles 服务器版本。在 macOS 26(Tahoe)上,由于 private API 变更,编辑功能目前不可用。
|
||||
|
||||
@@ -25,7 +25,7 @@ x-i18n:
|
||||
- 或配置:`channels.discord.token: "..."`。
|
||||
- 如果两者都设置了,配置优先(环境变量回退仅用于默认账户)。
|
||||
4. 邀请机器人到你的服务器并赋予消息权限(如果只想用私信可以创建一个私人服务器)。
|
||||
5. 启动 Gateway。
|
||||
5. 启动 Gateway网关。
|
||||
6. 私信访问默认需要配对;首次联系时批准配对码即可。
|
||||
|
||||
最小配置:
|
||||
@@ -53,7 +53,7 @@ x-i18n:
|
||||
1. 创建 Discord 应用 → Bot,启用所需的 intent(私信 + 服务器消息 + 消息内容),获取机器人 token。
|
||||
2. 邀请机器人到你的服务器,赋予在你需要使用的地方读取/发送消息所需的权限。
|
||||
3. 使用 `channels.discord.token` 配置 OpenClaw(或使用 `DISCORD_BOT_TOKEN` 作为回退)。
|
||||
4. 运行 Gateway;当 token 可用(配置优先,环境变量回退)且 `channels.discord.enabled` 不为 `false` 时,它会自动启动 Discord 渠道。
|
||||
4. 运行 Gateway网关;当 token 可用(配置优先,环境变量回退)且 `channels.discord.enabled` 不为 `false` 时,它会自动启动 Discord 渠道。
|
||||
- 如果你偏好使用环境变量,设置 `DISCORD_BOT_TOKEN`(配置块是可选的)。
|
||||
5. 私聊:投递时使用 `user:<id>`(或 `<@id>` 提及);所有回合都进入共享的 `main` 会话。裸数字 ID 具有歧义性,会被拒绝。
|
||||
6. 服务器频道:投递时使用 `channel:<channelId>`。默认需要提及,可按服务器或按频道设置。
|
||||
@@ -202,20 +202,20 @@ Discord 到处使用数字 ID;OpenClaw 配置推荐使用 ID。
|
||||
- 多智能体覆盖:在 `agents.list[].groupChat.mentionPatterns` 上设置每个智能体的模式。
|
||||
- 如果存在 `channels`,任何未列出的频道默认被拒绝。
|
||||
- 使用 `"*"` 频道条目来应用所有频道的默认值;明确的频道条目会覆盖通配符。
|
||||
- 帖子继承父频道配置(允许列表、`requireMention`、技能、提示等),除非你明确添加帖子频道 ID。
|
||||
- 帖子继承父频道配置(允许列表、`requireMention`、Skills、提示等),除非你明确添加帖子频道 ID。
|
||||
- 机器人发送的消息默认被忽略;设置 `channels.discord.allowBots=true` 可允许它们(自己的消息仍然被过滤)。
|
||||
- 警告:如果你允许回复其他机器人(`channels.discord.allowBots=true`),请使用 `requireMention`、`channels.discord.guilds.*.channels.<id>.users` 允许列表和/或在 `AGENTS.md` 和 `SOUL.md` 中设置明确的防护规则来防止机器人之间的回复循环。
|
||||
|
||||
### 6) 验证是否正常工作
|
||||
|
||||
1. 启动 Gateway。
|
||||
1. 启动 Gateway网关。
|
||||
2. 在你的服务器频道中,发送:`@Krill hello`(或你的机器人名称)。
|
||||
3. 如果没有响应:查看下方**故障排除**。
|
||||
|
||||
### 故障排除
|
||||
|
||||
- 首先:运行 `openclaw doctor` 和 `openclaw channels status --probe`(可操作的警告 + 快速审计)。
|
||||
- **"Used disallowed intents"**:在开发者门户中启用 **Message Content Intent**(以及可能的 **Server Members Intent**),然后重启 Gateway。
|
||||
- **"Used disallowed intents"**:在开发者门户中启用 **Message Content Intent**(以及可能的 **Server Members Intent**),然后重启 Gateway网关。
|
||||
- **机器人连接但在服务器频道中从不回复**:
|
||||
- 缺少 **Message Content Intent**,或
|
||||
- 机器人缺少频道权限(View/Send/Read History),或
|
||||
@@ -330,7 +330,7 @@ Discord 到处使用数字 ID;OpenClaw 配置推荐使用 ID。
|
||||
- `guilds.<id>.channels.<channel>.tools`:可选的按频道工具策略覆盖(`allow`/`deny`/`alsoAllow`)。
|
||||
- `guilds.<id>.channels.<channel>.toolsBySender`:可选的频道内按发送者工具策略覆盖(支持 `"*"` 通配符)。
|
||||
- `guilds.<id>.channels.<channel>.users`:可选的按频道用户允许列表。
|
||||
- `guilds.<id>.channels.<channel>.skills`:技能过滤器(省略 = 所有技能,空 = 无)。
|
||||
- `guilds.<id>.channels.<channel>.skills`:Skills 过滤器(省略 = 所有 Skills,空 = 无)。
|
||||
- `guilds.<id>.channels.<channel>.systemPrompt`:频道的额外系统提示(与频道主题合并)。
|
||||
- `guilds.<id>.channels.<channel>.enabled`:设置 `false` 可禁用频道。
|
||||
- `guilds.<id>.channels`:频道规则(键为频道 slug 或 ID)。
|
||||
@@ -460,4 +460,4 @@ Discord 消息 ID 在注入的上下文中呈现(`[discord message id: …]`
|
||||
|
||||
- 将机器人 token 视为密码;在受管主机上推荐使用 `DISCORD_BOT_TOKEN` 环境变量或锁定配置文件权限。
|
||||
- 仅授予机器人所需的权限(通常是读取/发送消息)。
|
||||
- 如果机器人卡住或被速率限制,在确认没有其他进程占用 Discord 会话后重启 Gateway(`openclaw gateway --force`)。
|
||||
- 如果机器人卡住或被速率限制,在确认没有其他进程占用 Discord 会话后重启 Gateway网关(`openclaw gateway --force`)。
|
||||
|
||||
@@ -31,7 +31,7 @@ x-i18n:
|
||||
- 进入 **Keys** 标签页。
|
||||
- 点击 **Add Key** > **Create new key**。
|
||||
- 选择 **JSON** 并点击 **Create**。
|
||||
4. 将下载的 JSON 文件存储在你的 Gateway 主机上(例如 `~/.openclaw/googlechat-service-account.json`)。
|
||||
4. 将下载的 JSON 文件存储在你的 Gateway网关主机上(例如 `~/.openclaw/googlechat-service-account.json`)。
|
||||
5. 在 [Google Cloud Console Chat 配置](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat) 中创建 Google Chat 应用:
|
||||
- 填写 **Application info**:
|
||||
- **App name**:(例如 `OpenClaw`)
|
||||
@@ -40,8 +40,8 @@ x-i18n:
|
||||
- 启用 **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`。
|
||||
- _提示:运行 `openclaw status` 可查找你的 Gateway 公共 URL。_
|
||||
- 在 **Triggers** 下,选择 **Use a common HTTP endpoint URL for all triggers** 并将其设置为你的 Gateway网关公共 URL 后跟 `/googlechat`。
|
||||
- _提示:运行 `openclaw status` 可查找你的 Gateway网关公共 URL。_
|
||||
- 在 **Visibility** 下,勾选 **Make this Chat app available to specific people and groups in <Your Domain>**。
|
||||
- 在文本框中输入你的邮箱地址(例如 `user@example.com`)。
|
||||
- 点击底部的 **Save**。
|
||||
@@ -54,11 +54,11 @@ x-i18n:
|
||||
- 环境变量:`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 请求。
|
||||
9. 启动 Gateway网关。Google Chat 将向你的 webhook 路径发送 POST 请求。
|
||||
|
||||
## 添加到 Google Chat
|
||||
|
||||
Gateway 运行且你的邮箱已添加到可见性列表后:
|
||||
Gateway网关运行且你的邮箱已添加到可见性列表后:
|
||||
|
||||
1. 前往 [Google Chat](https://chat.google.com/)。
|
||||
2. 点击 **Direct Messages** 旁边的 **+**(加号)图标。
|
||||
@@ -76,7 +76,7 @@ Google Chat webhook 需要公共 HTTPS 端点。为安全起见,**仅将 `/goo
|
||||
|
||||
使用 Tailscale Serve 用于私有仪表板,Funnel 用于公共 webhook 路径。这样 `/` 保持私有,仅暴露 `/googlechat`。
|
||||
|
||||
1. **检查你的 Gateway 绑定在哪个地址上:**
|
||||
1. **检查你的 Gateway网关绑定在哪个地址上:**
|
||||
|
||||
```bash
|
||||
ss -tlnp | grep 18789
|
||||
@@ -144,7 +144,7 @@ your-domain.com {
|
||||
|
||||
## 工作原理
|
||||
|
||||
1. Google Chat 向 Gateway 发送 webhook POST 请求。每个请求包含一个 `Authorization: Bearer <token>` 头。
|
||||
1. Google Chat 向 Gateway网关发送 webhook POST 请求。每个请求包含一个 `Authorization: Bearer <token>` 头。
|
||||
2. OpenClaw 根据配置的 `audienceType` + `audience` 验证 token:
|
||||
- `audienceType: "app-url"` → audience 是你的 HTTPS webhook URL。
|
||||
- `audienceType: "project-number"` → audience 是 Cloud 项目编号。
|
||||
@@ -231,7 +231,7 @@ status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Al
|
||||
|
||||
如果显示"disabled",在配置中添加 `plugins.entries.googlechat.enabled: true`。
|
||||
|
||||
3. **Gateway 未重启**:添加配置后,重启 Gateway:
|
||||
3. **Gateway网关未重启**:添加配置后,重启 Gateway网关:
|
||||
```bash
|
||||
openclaw gateway restart
|
||||
```
|
||||
@@ -248,10 +248,10 @@ openclaw channels status
|
||||
- 检查 `openclaw channels status --probe` 查看认证错误或缺失的 audience 配置。
|
||||
- 如果没有消息到达,确认 Chat 应用的 webhook URL + 事件订阅。
|
||||
- 如果提及门控阻止了回复,将 `botUser` 设置为应用的用户资源名称并验证 `requireMention`。
|
||||
- 发送测试消息时使用 `openclaw logs --follow` 查看请求是否到达 Gateway。
|
||||
- 发送测试消息时使用 `openclaw logs --follow` 查看请求是否到达 Gateway网关。
|
||||
|
||||
相关文档:
|
||||
|
||||
- [Gateway 配置](/gateway/configuration)
|
||||
- [Gateway网关配置](/gateway/configuration)
|
||||
- [安全](/gateway/security)
|
||||
- [回应](/tools/reactions)
|
||||
|
||||
@@ -22,10 +22,10 @@ x-i18n:
|
||||
|
||||
# 已交付的功能
|
||||
|
||||
- **单一客户端路径:** 基于 fetch 的实现已移除;grammY 现在是唯一的 Telegram 客户端(发送 + Gateway),默认启用 grammY throttler。
|
||||
- **Gateway:** `monitorTelegramProvider` 构建一个 grammY `Bot`,接入提及/允许列表门控、通过 `getFile`/`download` 下载媒体,并通过 `sendMessage/sendPhoto/sendVideo/sendAudio/sendDocument` 投递回复。支持通过 `webhookCallback` 进行长轮询或 webhook。
|
||||
- **单一客户端路径:** 基于 fetch 的实现已移除;grammY 现在是唯一的 Telegram 客户端(发送 + Gateway网关),默认启用 grammY throttler。
|
||||
- **Gateway网关:** `monitorTelegramProvider` 构建一个 grammY `Bot`,接入提及/允许列表门控、通过 `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 模式(否则使用长轮询)。
|
||||
- **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`(允许列表 + 提及默认值)、`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+)。这与渠道分块流式传输是分开的。
|
||||
@@ -35,4 +35,4 @@ x-i18n:
|
||||
|
||||
- 如果遇到 Bot API 429 错误,考虑使用可选的 grammY 插件(throttler)。
|
||||
- 添加更多结构化的媒体测试(贴纸、语音消息)。
|
||||
- 使 webhook 监听端口可配置(目前固定为 8787,除非通过 Gateway 接入)。
|
||||
- 使 webhook 监听端口可配置(目前固定为 8787,除非通过 Gateway网关接入)。
|
||||
|
||||
@@ -15,7 +15,7 @@ x-i18n:
|
||||
|
||||
# iMessage(imsg)
|
||||
|
||||
状态:外部 CLI 集成。Gateway 启动 `imsg rpc`(基于 stdio 的 JSON-RPC)。
|
||||
状态:外部 CLI 集成。Gateway网关启动 `imsg rpc`(基于 stdio 的 JSON-RPC)。
|
||||
|
||||
## 快速设置(新手)
|
||||
|
||||
@@ -23,7 +23,7 @@ x-i18n:
|
||||
2. 安装 `imsg`:
|
||||
- `brew install steipete/tap/imsg`
|
||||
3. 配置 OpenClaw 的 `channels.imessage.cliPath` 和 `channels.imessage.dbPath`。
|
||||
4. 启动 Gateway 并批准所有 macOS 提示(自动化 + 完全磁盘访问权限)。
|
||||
4. 启动 Gateway网关并批准所有 macOS 提示(自动化 + 完全磁盘访问权限)。
|
||||
|
||||
最小配置:
|
||||
|
||||
@@ -68,7 +68,7 @@ x-i18n:
|
||||
## 设置(快速路径)
|
||||
|
||||
1. 确保此 Mac 上的"信息"已登录。
|
||||
2. 配置 iMessage 并启动 Gateway。
|
||||
2. 配置 iMessage 并启动 Gateway网关。
|
||||
|
||||
### 专用机器人 macOS 用户(用于隔离身份)
|
||||
|
||||
@@ -149,13 +149,13 @@ exec ssh -T gateway-host imsg "$@"
|
||||
|
||||
#### 通过 Tailscale 连接远程 Mac(示例)
|
||||
|
||||
如果 Gateway 运行在 Linux 主机/虚拟机上但 iMessage 必须运行在 Mac 上,Tailscale 是最简单的桥接方案:Gateway 通过 tailnet 与 Mac 通信,通过 SSH 运行 `imsg`,并通过 SCP 传回附件。
|
||||
如果 Gateway网关运行在 Linux 主机/虚拟机上但 iMessage 必须运行在 Mac 上,Tailscale 是最简单的桥接方案:Gateway网关通过 tailnet 与 Mac 通信,通过 SSH 运行 `imsg`,并通过 SCP 传回附件。
|
||||
|
||||
架构:
|
||||
|
||||
```
|
||||
┌──────────────────────────────┐ SSH (imsg rpc) ┌──────────────────────────┐
|
||||
│ Gateway 主机(Linux/VM) │──────────────────────────────────▶│ 装有 Messages + imsg 的 Mac │
|
||||
│ Gateway网关主机(Linux/VM) │──────────────────────────────────▶│ 装有 Messages + imsg 的 Mac │
|
||||
│ - openclaw gateway │ SCP(附件) │ - Messages 已登录 │
|
||||
│ - channels.imessage.cliPath │◀──────────────────────────────────│ - 远程登录已启用 │
|
||||
└──────────────────────────────┘ └──────────────────────────┘
|
||||
@@ -216,7 +216,7 @@ exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"
|
||||
|
||||
## 工作原理(行为)
|
||||
|
||||
- `imsg` 流式传输消息事件;Gateway 将其标准化为共享的渠道信封。
|
||||
- `imsg` 流式传输消息事件;Gateway网关将其标准化为共享的渠道信封。
|
||||
- 回复始终路由回同一个 chat id 或用户名。
|
||||
|
||||
## 类群组线程(`is_group=false`)
|
||||
|
||||
@@ -15,13 +15,13 @@ x-i18n:
|
||||
|
||||
# 聊天渠道
|
||||
|
||||
OpenClaw 可以在你已经使用的任何聊天应用上与你对话。每个渠道通过 Gateway 连接。所有渠道都支持文本;媒体和回应功能因渠道而异。
|
||||
OpenClaw 可以在你已经使用的任何聊天应用上与你对话。每个渠道通过 Gateway网关连接。所有渠道都支持文本;媒体和回应功能因渠道而异。
|
||||
|
||||
## 支持的渠道
|
||||
|
||||
- [WhatsApp](/channels/whatsapp) — 最受欢迎;使用 Baileys 并需要二维码配对。
|
||||
- [Telegram](/channels/telegram) — 通过 grammY 使用 Bot API;支持群组。
|
||||
- [Discord](/channels/discord) — Discord Bot API + Gateway;支持服务器、频道和私信。
|
||||
- [Discord](/channels/discord) — Discord Bot API + Gateway网关;支持服务器、频道和私信。
|
||||
- [Slack](/channels/slack) — Bolt SDK;工作区应用。
|
||||
- [Google Chat](/channels/googlechat) — 通过 HTTP webhook 使用 Google Chat API 应用。
|
||||
- [Mattermost](/channels/mattermost) — Bot API + WebSocket;频道、群组、私信(插件,需单独安装)。
|
||||
@@ -37,7 +37,7 @@ OpenClaw 可以在你已经使用的任何聊天应用上与你对话。每个
|
||||
- [Twitch](/channels/twitch) — 通过 IRC 连接的 Twitch 聊天(插件,需单独安装)。
|
||||
- [Zalo](/channels/zalo) — Zalo Bot API;越南流行的通讯工具(插件,需单独安装)。
|
||||
- [Zalo Personal](/channels/zalouser) — 通过二维码登录的 Zalo 个人账户(插件,需单独安装)。
|
||||
- [WebChat](/web/webchat) — 通过 WebSocket 的 Gateway WebChat UI。
|
||||
- [WebChat](/web/webchat) — 通过 WebSocket 的 Gateway网关 WebChat UI。
|
||||
|
||||
## 注意事项
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@ x-i18n:
|
||||
|
||||
# LINE(插件)
|
||||
|
||||
LINE 通过 LINE Messaging API 连接到 OpenClaw。插件作为 Gateway 上的 webhook 接收器运行,使用你的频道访问 token + 频道密钥进行认证。
|
||||
LINE 通过 LINE Messaging API 连接到 OpenClaw。插件作为 Gateway网关上的 webhook 接收器运行,使用你的频道访问 token + 频道密钥进行认证。
|
||||
|
||||
状态:通过插件支持。支持私信、群聊、媒体、位置、Flex 消息、模板消息和快速回复。不支持回应和线程。
|
||||
|
||||
@@ -41,13 +41,13 @@ openclaw plugins install ./extensions/line
|
||||
2. 创建(或选择)一个 Provider 并添加一个 **Messaging API** 频道。
|
||||
3. 从频道设置中复制 **Channel access token** 和 **Channel secret**。
|
||||
4. 在 Messaging API 设置中启用 **Use webhook**。
|
||||
5. 将 webhook URL 设置为你的 Gateway 端点(需要 HTTPS):
|
||||
5. 将 webhook URL 设置为你的 Gateway网关端点(需要 HTTPS):
|
||||
|
||||
```
|
||||
https://gateway-host/line/webhook
|
||||
```
|
||||
|
||||
Gateway 响应 LINE 的 webhook 验证(GET)和入站事件(POST)。如果你需要自定义路径,请设置 `channels.line.webhookPath` 或 `channels.line.accounts.<id>.webhookPath` 并相应更新 URL。
|
||||
Gateway网关响应 LINE 的 webhook 验证(GET)和入站事件(POST)。如果你需要自定义路径,请设置 `channels.line.webhookPath` 或 `channels.line.accounts.<id>.webhookPath` 并相应更新 URL。
|
||||
|
||||
## 配置
|
||||
|
||||
@@ -176,5 +176,5 @@ LINE 插件还附带一个 `/card` 命令用于 Flex 消息预设:
|
||||
## 故障排除
|
||||
|
||||
- **Webhook 验证失败:** 确保 webhook URL 为 HTTPS 且 `channelSecret` 与 LINE 控制台匹配。
|
||||
- **没有入站事件:** 确认 webhook 路径与 `channels.line.webhookPath` 匹配且 Gateway 可从 LINE 访问。
|
||||
- **没有入站事件:** 确认 webhook 路径与 `channels.line.webhookPath` 匹配且 Gateway网关可从 LINE 访问。
|
||||
- **媒体下载错误:** 如果媒体超过默认限制,请增大 `channels.line.mediaMaxMb`。
|
||||
|
||||
@@ -34,7 +34,7 @@ openclaw plugins install @openclaw/matrix
|
||||
openclaw plugins install ./extensions/matrix
|
||||
```
|
||||
|
||||
如果你在配置/上手引导期间选择了 Matrix 并检测到 git 检出,OpenClaw 会自动提供本地安装路径。
|
||||
如果你在配置/新手引导期间选择了 Matrix 并检测到 git 检出,OpenClaw 会自动提供本地安装路径。
|
||||
|
||||
详情:[插件](/plugin)
|
||||
|
||||
@@ -72,7 +72,7 @@ openclaw plugins install ./extensions/matrix
|
||||
- 如果两者都设置了,配置优先。
|
||||
- 使用访问 token 时:用户 ID 通过 `/whoami` 自动获取。
|
||||
- 设置时,`channels.matrix.userId` 应为完整的 Matrix ID(例如:`@bot:example.org`)。
|
||||
5. 重启 Gateway(或完成上手引导)。
|
||||
5. 重启 Gateway网关(或完成新手引导)。
|
||||
6. 从任何 Matrix 客户端(Element、Beeper 等;参见 https://matrix.org/ecosystem/clients/)与机器人开始私信或邀请它加入房间。Beeper 需要端到端加密,因此请设置 `channels.matrix.encryption: true` 并验证设备。
|
||||
|
||||
最小配置(访问 token,用户 ID 自动获取):
|
||||
|
||||
@@ -33,7 +33,7 @@ openclaw plugins install @openclaw/mattermost
|
||||
openclaw plugins install ./extensions/mattermost
|
||||
```
|
||||
|
||||
如果你在配置/上手引导期间选择了 Mattermost 并检测到 git 检出,OpenClaw 会自动提供本地安装路径。
|
||||
如果你在配置/新手引导期间选择了 Mattermost 并检测到 git 检出,OpenClaw 会自动提供本地安装路径。
|
||||
|
||||
详情:[插件](/plugin)
|
||||
|
||||
@@ -42,7 +42,7 @@ openclaw plugins install ./extensions/mattermost
|
||||
1. 安装 Mattermost 插件。
|
||||
2. 创建一个 Mattermost 机器人账户并复制 **bot token**。
|
||||
3. 复制 Mattermost **基础 URL**(例如 `https://chat.example.com`)。
|
||||
4. 配置 OpenClaw 并启动 Gateway。
|
||||
4. 配置 OpenClaw 并启动 Gateway网关。
|
||||
|
||||
最小配置:
|
||||
|
||||
@@ -61,7 +61,7 @@ openclaw plugins install ./extensions/mattermost
|
||||
|
||||
## 环境变量(默认账户)
|
||||
|
||||
如果你偏好使用环境变量,请在 Gateway 主机上设置:
|
||||
如果你偏好使用环境变量,请在 Gateway网关主机上设置:
|
||||
|
||||
- `MATTERMOST_BOT_TOKEN=...`
|
||||
- `MATTERMOST_URL=https://chat.example.com`
|
||||
|
||||
@@ -40,7 +40,7 @@ openclaw plugins install @openclaw/msteams
|
||||
openclaw plugins install ./extensions/msteams
|
||||
```
|
||||
|
||||
如果你在配置/上手引导期间选择了 Teams 并检测到 git 检出,OpenClaw 会自动提供本地安装路径。
|
||||
如果你在配置/新手引导期间选择了 Teams 并检测到 git 检出,OpenClaw 会自动提供本地安装路径。
|
||||
|
||||
详情:[插件](/plugin)
|
||||
|
||||
@@ -50,7 +50,7 @@ openclaw plugins install ./extensions/msteams
|
||||
2. 创建一个 **Azure Bot**(App ID + 客户端密钥 + 租户 ID)。
|
||||
3. 使用这些凭据配置 OpenClaw。
|
||||
4. 通过公共 URL 或隧道暴露 `/api/messages`(默认端口 3978)。
|
||||
5. 安装 Teams 应用包并启动 Gateway。
|
||||
5. 安装 Teams 应用包并启动 Gateway网关。
|
||||
|
||||
最小配置:
|
||||
|
||||
@@ -148,8 +148,8 @@ openclaw plugins install ./extensions/msteams
|
||||
2. 创建一个 **Azure Bot**(App ID + 密钥 + 租户 ID)。
|
||||
3. 构建一个引用该机器人并包含下方 RSC 权限的 **Teams 应用包**。
|
||||
4. 将 Teams 应用上传/安装到团队(或私人范围用于私信)。
|
||||
5. 在 `~/.openclaw/openclaw.json`(或环境变量)中配置 `msteams` 并启动 Gateway。
|
||||
6. Gateway 默认在 `/api/messages` 上监听 Bot Framework webhook 流量。
|
||||
5. 在 `~/.openclaw/openclaw.json`(或环境变量)中配置 `msteams` 并启动 Gateway网关。
|
||||
6. Gateway网关默认在 `/api/messages` 上监听 Bot Framework webhook 流量。
|
||||
|
||||
## Azure Bot 设置(前提条件)
|
||||
|
||||
@@ -239,7 +239,7 @@ tailscale funnel 3978
|
||||
|
||||
1. 安装 Teams 应用(旁加载或组织目录)
|
||||
2. 在 Teams 中找到机器人并发送私信
|
||||
3. 检查 Gateway 日志中的传入活动
|
||||
3. 检查 Gateway网关日志中的传入活动
|
||||
|
||||
## 设置(最小纯文本)
|
||||
|
||||
@@ -284,7 +284,7 @@ tailscale funnel 3978
|
||||
- 将 Azure Bot 消息端点设置为:
|
||||
- `https://<host>:3978/api/messages`(或你选择的路径/端口)。
|
||||
|
||||
6. **运行 Gateway**
|
||||
6. **运行 Gateway网关**
|
||||
- 当插件已安装且 `msteams` 配置存在凭据时,Teams 渠道会自动启动。
|
||||
|
||||
## 历史上下文
|
||||
@@ -434,7 +434,7 @@ tailscale funnel 3978
|
||||
|
||||
Teams 通过 HTTP webhook 投递消息。如果处理时间过长(例如 LLM 响应缓慢),你可能会看到:
|
||||
|
||||
- Gateway 超时
|
||||
- Gateway网关超时
|
||||
- Teams 重试消息(导致重复)
|
||||
- 回复丢失
|
||||
|
||||
@@ -598,8 +598,8 @@ Teams 最近在相同的底层数据模型上引入了两种频道 UI 样式:
|
||||
OpenClaw 通过 Adaptive Cards 发送 Teams 投票(没有原生 Teams 投票 API)。
|
||||
|
||||
- CLI:`openclaw message poll --channel msteams --target conversation:<id> ...`
|
||||
- 投票由 Gateway 记录在 `~/.openclaw/msteams-polls.json` 中。
|
||||
- Gateway 必须保持在线以记录投票。
|
||||
- 投票由 Gateway网关记录在 `~/.openclaw/msteams-polls.json` 中。
|
||||
- Gateway网关必须保持在线以记录投票。
|
||||
- 投票尚不会自动发布结果摘要(如需要请查看存储文件)。
|
||||
|
||||
## Adaptive Cards(任意)
|
||||
|
||||
@@ -32,7 +32,7 @@ openclaw plugins install @openclaw/nextcloud-talk
|
||||
openclaw plugins install ./extensions/nextcloud-talk
|
||||
```
|
||||
|
||||
如果你在配置/上手引导期间选择了 Nextcloud Talk 并检测到 git 检出,OpenClaw 会自动提供本地安装路径。
|
||||
如果你在配置/新手引导期间选择了 Nextcloud Talk 并检测到 git 检出,OpenClaw 会自动提供本地安装路径。
|
||||
|
||||
详情:[插件](/plugin)
|
||||
|
||||
@@ -47,7 +47,7 @@ openclaw plugins install ./extensions/nextcloud-talk
|
||||
4. 配置 OpenClaw:
|
||||
- 配置:`channels.nextcloud-talk.baseUrl` + `channels.nextcloud-talk.botSecret`
|
||||
- 或环境变量:`NEXTCLOUD_TALK_BOT_SECRET`(仅默认账户)
|
||||
5. 重启 Gateway(或完成上手引导)。
|
||||
5. 重启 Gateway网关(或完成新手引导)。
|
||||
|
||||
最小配置:
|
||||
|
||||
@@ -67,7 +67,7 @@ openclaw plugins install ./extensions/nextcloud-talk
|
||||
## 注意事项
|
||||
|
||||
- 机器人无法主动发起私信。用户必须先给机器人发消息。
|
||||
- Webhook URL 必须能被 Gateway 访问;如果在代理后面,请设置 `webhookPublicUrl`。
|
||||
- Webhook URL 必须能被 Gateway网关访问;如果在代理后面,请设置 `webhookPublicUrl`。
|
||||
- 机器人 API 不支持媒体上传;媒体以 URL 形式发送。
|
||||
- Webhook 负载不区分私信和房间;设置 `apiUser` + `apiPassword` 以启用房间类型查询(否则私信会被视为房间)。
|
||||
|
||||
|
||||
@@ -17,13 +17,13 @@ x-i18n:
|
||||
|
||||
**状态:** 可选插件(默认禁用)。
|
||||
|
||||
Nostr 是一个去中心化的社交网络协议。此渠道使 OpenClaw 能够通过 NIP-04 接收和回复加密私信(DM)。
|
||||
Nostr 是一个去中心化的社交网络协议。此渠道使 OpenClaw 能够通过 NIP-04 接收和回复加密私信(私信)。
|
||||
|
||||
## 安装(按需)
|
||||
|
||||
### 上手引导(推荐)
|
||||
### 新手引导(推荐)
|
||||
|
||||
- 上手引导向导(`openclaw onboard`)和 `openclaw channels add` 会列出可选的渠道插件。
|
||||
- 新手引导向导(`openclaw onboard`)和 `openclaw channels add` 会列出可选的渠道插件。
|
||||
- 选择 Nostr 时会提示你按需安装插件。
|
||||
|
||||
安装默认行为:
|
||||
@@ -45,7 +45,7 @@ openclaw plugins install @openclaw/nostr
|
||||
openclaw plugins install --link <path-to-openclaw>/extensions/nostr
|
||||
```
|
||||
|
||||
安装或启用插件后请重启 Gateway。
|
||||
安装或启用插件后请重启 Gateway网关。
|
||||
|
||||
## 快速设置
|
||||
|
||||
@@ -74,7 +74,7 @@ nak key generate
|
||||
export NOSTR_PRIVATE_KEY="nsec1..."
|
||||
```
|
||||
|
||||
4. 重启 Gateway。
|
||||
4. 重启 Gateway网关。
|
||||
|
||||
## 配置参考
|
||||
|
||||
@@ -214,7 +214,7 @@ docker run -p 7777:7777 ghcr.io/hoytech/strfry
|
||||
- 验证私钥是否有效。
|
||||
- 确保中继 URL 可达并使用 `wss://`(本地使用 `ws://`)。
|
||||
- 确认 `enabled` 未设为 `false`。
|
||||
- 检查 Gateway 日志中的中继连接错误。
|
||||
- 检查 Gateway网关日志中的中继连接错误。
|
||||
|
||||
### 无法发送回复
|
||||
|
||||
|
||||
@@ -15,7 +15,7 @@ x-i18n:
|
||||
|
||||
# Signal(signal-cli)
|
||||
|
||||
状态:外部 CLI 集成。Gateway 通过 HTTP JSON-RPC + SSE 与 `signal-cli` 通信。
|
||||
状态:外部 CLI 集成。Gateway网关通过 HTTP JSON-RPC + SSE 与 `signal-cli` 通信。
|
||||
|
||||
## 快速设置(新手)
|
||||
|
||||
@@ -23,7 +23,7 @@ x-i18n:
|
||||
2. 安装 `signal-cli`(需要 Java)。
|
||||
3. 链接机器人设备并启动守护进程:
|
||||
- `signal-cli link -n "OpenClaw"`
|
||||
4. 配置 OpenClaw 并启动 Gateway。
|
||||
4. 配置 OpenClaw 并启动 Gateway网关。
|
||||
|
||||
最小配置:
|
||||
|
||||
@@ -61,7 +61,7 @@ x-i18n:
|
||||
|
||||
## 号码模型(重要)
|
||||
|
||||
- Gateway 连接到一个 **Signal 设备**(`signal-cli` 账户)。
|
||||
- Gateway网关连接到一个 **Signal 设备**(`signal-cli` 账户)。
|
||||
- 如果你在**个人 Signal 账户**上运行机器人,它会忽略你自己的消息(循环保护)。
|
||||
- 要实现"我给机器人发消息它回复我",请使用一个**单独的机器人号码**。
|
||||
|
||||
@@ -70,7 +70,7 @@ x-i18n:
|
||||
1. 安装 `signal-cli`(需要 Java)。
|
||||
2. 链接机器人账户:
|
||||
- `signal-cli link -n "OpenClaw"` 然后在 Signal 中扫描二维码。
|
||||
3. 配置 Signal 并启动 Gateway。
|
||||
3. 配置 Signal 并启动 Gateway网关。
|
||||
|
||||
示例:
|
||||
|
||||
@@ -126,7 +126,7 @@ x-i18n:
|
||||
|
||||
## 工作原理(行为)
|
||||
|
||||
- `signal-cli` 作为守护进程运行;Gateway 通过 SSE 读取事件。
|
||||
- `signal-cli` 作为守护进程运行;Gateway网关通过 SSE 读取事件。
|
||||
- 入站消息被标准化为共享的渠道信封。
|
||||
- 回复始终路由回同一个号码或群组。
|
||||
|
||||
|
||||
@@ -19,7 +19,7 @@ x-i18n:
|
||||
|
||||
1. 创建一个 Slack 应用并启用 **Socket Mode**。
|
||||
2. 创建一个 **App Token**(`xapp-...`)和 **Bot Token**(`xoxb-...`)。
|
||||
3. 为 OpenClaw 设置 token 并启动 Gateway。
|
||||
3. 为 OpenClaw 设置 token 并启动 Gateway网关。
|
||||
|
||||
最小配置:
|
||||
|
||||
@@ -126,14 +126,14 @@ OpenClaw 可以使用 Slack 用户 token(`xoxp-...`)进行读取操作(历
|
||||
|
||||
## HTTP 模式(Events API)
|
||||
|
||||
当你的 Gateway 可通过 HTTPS 被 Slack 访问时使用 HTTP webhook 模式(适用于服务器部署)。HTTP 模式使用 Events API + Interactivity + Slash Commands,共享请求 URL。
|
||||
当你的 Gateway网关可通过 HTTPS 被 Slack 访问时使用 HTTP webhook 模式(适用于服务器部署)。HTTP 模式使用 Events API + Interactivity + Slash Commands,共享请求 URL。
|
||||
|
||||
### 设置
|
||||
|
||||
1. 创建 Slack 应用并**禁用 Socket Mode**(如果你只使用 HTTP 则可选)。
|
||||
2. **Basic Information** → 复制 **Signing Secret**。
|
||||
3. **OAuth & Permissions** → 安装应用并复制 **Bot User OAuth Token**(`xoxb-...`)。
|
||||
4. **Event Subscriptions** → 启用事件并将 **Request URL** 设置为你的 Gateway webhook 路径(默认 `/slack/events`)。
|
||||
4. **Event Subscriptions** → 启用事件并将 **Request URL** 设置为你的 Gateway网关 webhook 路径(默认 `/slack/events`)。
|
||||
5. **Interactivity & Shortcuts** → 启用并设置相同的 **Request URL**。
|
||||
6. **Slash Commands** → 为你的命令设置相同的 **Request URL**。
|
||||
|
||||
@@ -490,7 +490,7 @@ Token 也可以通过环境变量提供:
|
||||
- `toolsBySender`:可选的频道内按发送者工具策略覆盖(键为发送者 ID/@用户名/邮箱;支持 `"*"` 通配符)。
|
||||
- `allowBots`:允许此频道中机器人发送的消息(默认:false)。
|
||||
- `users`:可选的按频道用户允许列表。
|
||||
- `skills`:技能过滤器(省略 = 所有技能,空 = 无)。
|
||||
- `skills`:Skills 过滤器(省略 = 所有 Skills,空 = 无)。
|
||||
- `systemPrompt`:频道的额外系统提示(与主题/目的合并)。
|
||||
- `enabled`:设置 `false` 可禁用频道。
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ x-i18n:
|
||||
- 环境变量:`TELEGRAM_BOT_TOKEN=...`
|
||||
- 或配置:`channels.telegram.botToken: "..."`。
|
||||
- 如果两者都设置了,配置优先(环境变量回退仅适用于默认账户)。
|
||||
3. 启动 Gateway。
|
||||
3. 启动 Gateway网关。
|
||||
4. 私聊访问默认为配对模式;首次联系时需批准配对码。
|
||||
|
||||
最小配置:
|
||||
@@ -42,7 +42,7 @@ x-i18n:
|
||||
|
||||
## 简介
|
||||
|
||||
- 由 Gateway 管理的 Telegram Bot API 渠道。
|
||||
- 由 Gateway网关管理的 Telegram Bot API 渠道。
|
||||
- 确定性路由:回复始终发回 Telegram;模型不会选择渠道。
|
||||
- 私聊共享智能体的主会话;群组保持隔离(`agent:<agentId>:telegram:group:<chatId>`)。
|
||||
|
||||
@@ -81,7 +81,7 @@ x-i18n:
|
||||
|
||||
多账户支持:使用 `channels.telegram.accounts`,为每个账户设置令牌和可选的 `name`。请参阅 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) 了解通用模式。
|
||||
|
||||
3. 启动 Gateway。当令牌被解析后(配置优先,环境变量回退),Telegram 即启动。
|
||||
3. 启动 Gateway网关。当令牌被解析后(配置优先,环境变量回退),Telegram 即启动。
|
||||
4. 私聊访问默认为配对模式。机器人首次被联系时需批准配对码。
|
||||
5. 对于群组:添加机器人,决定隐私/管理员行为(见下文),然后设置 `channels.telegram.groups` 来控制提及门控 + 白名单。
|
||||
|
||||
@@ -365,7 +365,7 @@ Telegram 功能可在两个层级配置(上面展示了对象形式;旧版
|
||||
|
||||
更安全的方式(无需第三方机器人):
|
||||
|
||||
1. 启动 Gateway 并私聊你的机器人。
|
||||
1. 启动 Gateway网关并私聊你的机器人。
|
||||
2. 运行 `openclaw logs --follow` 并查找 `from.id`。
|
||||
|
||||
替代方式(官方 Bot API):
|
||||
@@ -682,7 +682,7 @@ Telegram 表情回应作为**独立的 `message_reaction` 事件**到达,而
|
||||
- 如果设置了 `channels.telegram.groups`,群组必须被列出或使用 `"*"`
|
||||
- 在 @BotFather 中检查隐私设置 → "Group Privacy" 应为 **OFF**
|
||||
- 确认机器人确实是成员(而非只是没有读取权限的管理员)
|
||||
- 检查 Gateway 日志:`openclaw logs --follow`(查找 "skipping group message")
|
||||
- 检查 Gateway网关日志:`openclaw logs --follow`(查找 "skipping group message")
|
||||
|
||||
**机器人响应提及但不响应 `/activation always`:**
|
||||
|
||||
@@ -697,12 +697,12 @@ Telegram 表情回应作为**独立的 `message_reaction` 事件**到达,而
|
||||
**长轮询在 Node 22+ 上立即中止(通常涉及代理/自定义 fetch):**
|
||||
|
||||
- Node 22+ 对 `AbortSignal` 实例更严格;外部信号可能会立即中止 `fetch` 调用。
|
||||
- 升级到规范化 abort 信号的 OpenClaw 版本,或在 Node 20 上运行 Gateway 直到可以升级。
|
||||
- 升级到规范化 abort 信号的 OpenClaw 版本,或在 Node 20 上运行 Gateway网关直到可以升级。
|
||||
|
||||
**机器人启动后静默停止响应(或日志中出现 `HttpError: Network request ... failed`):**
|
||||
|
||||
- 某些主机优先将 `api.telegram.org` 解析为 IPv6。如果你的服务器没有可用的 IPv6 出口,grammY 可能会卡在仅 IPv6 的请求上。
|
||||
- 修复方法:启用 IPv6 出口**或者**强制 `api.telegram.org` 使用 IPv4 解析(例如,使用 IPv4 A 记录添加 `/etc/hosts` 条目,或在操作系统 DNS 栈中优先使用 IPv4),然后重启 Gateway。
|
||||
- 修复方法:启用 IPv6 出口**或者**强制 `api.telegram.org` 使用 IPv4 解析(例如,使用 IPv4 A 记录添加 `/etc/hosts` 条目,或在操作系统 DNS 栈中优先使用 IPv4),然后重启 Gateway网关。
|
||||
- 快速检查:`dig +short api.telegram.org A` 和 `dig +short api.telegram.org AAAA` 确认 DNS 返回的内容。
|
||||
|
||||
## 配置参考(Telegram)
|
||||
@@ -720,7 +720,7 @@ Telegram 表情回应作为**独立的 `message_reaction` 事件**到达,而
|
||||
- `channels.telegram.groupAllowFrom`:群组发送者白名单(ID/用户名)。
|
||||
- `channels.telegram.groups`:按群组的默认设置 + 白名单(使用 `"*"` 作为全局默认)。
|
||||
- `channels.telegram.groups.<id>.requireMention`:提及门控默认值。
|
||||
- `channels.telegram.groups.<id>.skills`:技能过滤(省略 = 所有技能,空 = 无技能)。
|
||||
- `channels.telegram.groups.<id>.skills`:Skills 过滤(省略 = 所有 Skills,空 = 无 Skills)。
|
||||
- `channels.telegram.groups.<id>.allowFrom`:按群组的发送者白名单覆盖。
|
||||
- `channels.telegram.groups.<id>.systemPrompt`:群组的额外系统提示词。
|
||||
- `channels.telegram.groups.<id>.enabled`:设为 `false` 时禁用该群组。
|
||||
|
||||
@@ -43,7 +43,7 @@ openclaw plugins install ./extensions/tlon
|
||||
1. 安装 Tlon 插件。
|
||||
2. 获取你的 ship URL 和登录代码。
|
||||
3. 配置 `channels.tlon`。
|
||||
4. 重启 Gateway。
|
||||
4. 重启 Gateway网关。
|
||||
5. 向机器人发送私信或在群组渠道中提及它。
|
||||
|
||||
最小配置(单账户):
|
||||
|
||||
@@ -46,7 +46,7 @@ openclaw plugins install ./extensions/twitch
|
||||
- 环境变量:`OPENCLAW_TWITCH_ACCESS_TOKEN=...`(仅限默认账号)
|
||||
- 或配置文件:`channels.twitch.accessToken`
|
||||
- 如果两者都设置了,配置文件优先(环境变量回退仅适用于默认账号)。
|
||||
5. 启动 Gateway。
|
||||
5. 启动 Gateway网关。
|
||||
|
||||
**⚠️ 重要:** 添加访问控制(`allowFrom` 或 `allowedRoles`)以防止未授权用户触发机器人。`requireMention` 默认为 `true`。
|
||||
|
||||
@@ -69,7 +69,7 @@ openclaw plugins install ./extensions/twitch
|
||||
|
||||
## 工作原理
|
||||
|
||||
- 由 Gateway 拥有的 Twitch 渠道。
|
||||
- 由 Gateway网关拥有的 Twitch 渠道。
|
||||
- 确定性路由:回复始终返回到 Twitch。
|
||||
- 每个账号映射到一个隔离的会话键 `agent:<agentId>:twitch:<accountName>`。
|
||||
- `username` 是机器人的账号(用于认证),`channel` 是要加入的聊天室。
|
||||
@@ -375,7 +375,7 @@ Access token refreshed for user 123456 (expires in 14400s)
|
||||
- **使用用户 ID 允许列表** 而非用户名进行访问控制
|
||||
- **监控日志** 关注令牌刷新事件和连接状态
|
||||
- **最小化令牌权限范围** - 仅请求 `chat:read` 和 `chat:write`
|
||||
- **如遇问题**:确认没有其他进程占用会话后,重启 Gateway
|
||||
- **如遇问题**:确认没有其他进程占用会话后,重启 Gateway网关
|
||||
|
||||
## 限制
|
||||
|
||||
|
||||
@@ -14,14 +14,14 @@ x-i18n:
|
||||
|
||||
# WhatsApp(网页渠道)
|
||||
|
||||
状态:仅支持通过 Baileys 的 WhatsApp Web。Gateway 拥有会话。
|
||||
状态:仅支持通过 Baileys 的 WhatsApp Web。Gateway网关拥有会话。
|
||||
|
||||
## 快速设置(入门)
|
||||
|
||||
1. 如果可能,使用**单独的手机号码**(推荐)。
|
||||
2. 在 `~/.openclaw/openclaw.json` 中配置 WhatsApp。
|
||||
3. 运行 `openclaw channels login` 扫描二维码(已关联设备)。
|
||||
4. 启动 Gateway。
|
||||
4. 启动 Gateway网关。
|
||||
|
||||
最小配置:
|
||||
|
||||
@@ -38,7 +38,7 @@ x-i18n:
|
||||
|
||||
## 目标
|
||||
|
||||
- 单个 Gateway 进程中支持多个 WhatsApp 账号(多账号)。
|
||||
- 单个 Gateway网关进程中支持多个 WhatsApp 账号(多账号)。
|
||||
- 确定性路由:回复返回到 WhatsApp,无模型路由。
|
||||
- 模型获得足够的上下文以理解引用回复。
|
||||
|
||||
@@ -56,8 +56,8 @@ x-i18n:
|
||||
|
||||
## 架构(职责划分)
|
||||
|
||||
- **Gateway** 拥有 Baileys socket 和收件箱循环。
|
||||
- **CLI / macOS 应用** 与 Gateway 通信;不直接使用 Baileys。
|
||||
- **Gateway网关** 拥有 Baileys socket 和收件箱循环。
|
||||
- **CLI / macOS 应用** 与 Gateway网关通信;不直接使用 Baileys。
|
||||
- **活跃监听器** 是出站发送的必要条件;否则发送会快速失败。
|
||||
|
||||
## 获取手机号码(两种模式)
|
||||
@@ -161,7 +161,7 @@ WhatsApp 需要真实的手机号码进行验证。VoIP 和虚拟号码通常会
|
||||
|
||||
## 已读回执
|
||||
|
||||
默认情况下,Gateway 会在接受入站 WhatsApp 消息后将其标记为已读(蓝色对勾)。
|
||||
默认情况下,Gateway网关会在接受入站 WhatsApp 消息后将其标记为已读(蓝色对勾)。
|
||||
|
||||
全局禁用:
|
||||
|
||||
@@ -242,7 +242,7 @@ WhatsApp 需要真实的手机号码进行验证。VoIP 和虚拟号码通常会
|
||||
|
||||
## 回复投递(线程)
|
||||
|
||||
- WhatsApp Web 发送标准消息(当前 Gateway 中无引用回复线程)。
|
||||
- WhatsApp Web 发送标准消息(当前 Gateway网关中无引用回复线程)。
|
||||
- 此渠道忽略回复标签。
|
||||
|
||||
## 确认反应(收到消息时自动反应)
|
||||
@@ -266,7 +266,7 @@ WhatsApp 可以在收到消息时立即自动发送表情反应,在机器人
|
||||
**选项:**
|
||||
|
||||
- `emoji`(字符串):用于确认的表情(例如 "👀"、"✅"、"📨")。为空或省略 = 功能禁用。
|
||||
- `direct`(布尔值,默认:`true`):在私聊/DM 中发送反应。
|
||||
- `direct`(布尔值,默认:`true`):在私聊/私信 中发送反应。
|
||||
- `group`(字符串,默认:`"mentions"`):群聊行为:
|
||||
- `"always"`:对所有群聊消息做出反应(即使没有 @提及)
|
||||
- `"mentions"`:仅在机器人被 @提及时做出反应
|
||||
@@ -314,7 +314,7 @@ WhatsApp 可以在收到消息时立即自动发送表情反应,在机器人
|
||||
|
||||
## 出站发送(文本 + 媒体)
|
||||
|
||||
- 使用活跃的网页监听器;如果 Gateway 未运行则报错。
|
||||
- 使用活跃的网页监听器;如果 Gateway网关未运行则报错。
|
||||
- 文本分块:每条消息最大 4k(可通过 `channels.whatsapp.textChunkLimit` 配置,可选 `channels.whatsapp.chunkMode`)。
|
||||
- 媒体:
|
||||
- 支持图片/视频/音频/文档。
|
||||
@@ -323,7 +323,7 @@ WhatsApp 可以在收到消息时立即自动发送表情反应,在机器人
|
||||
- 媒体获取支持 HTTP(S) 和本地路径。
|
||||
- 动态 GIF:WhatsApp 期望带 `gifPlayback: true` 的 MP4 以实现内联循环播放。
|
||||
- CLI:`openclaw message send --media <mp4> --gif-playback`
|
||||
- Gateway:`send` 参数包含 `gifPlayback: true`
|
||||
- Gateway网关:`send` 参数包含 `gifPlayback: true`
|
||||
|
||||
## 语音消息(PTT 音频)
|
||||
|
||||
@@ -341,7 +341,7 @@ WhatsApp 以**语音消息**(PTT 气泡)发送音频。
|
||||
|
||||
## 心跳
|
||||
|
||||
- **Gateway 心跳** 记录连接健康状态(`web.heartbeatSeconds`,默认 60 秒)。
|
||||
- **Gateway网关心跳** 记录连接健康状态(`web.heartbeatSeconds`,默认 60 秒)。
|
||||
- **智能体心跳** 可按智能体配置(`agents.list[].heartbeat`)或通过
|
||||
`agents.defaults.heartbeat` 全局配置(未设置每智能体条目时的回退)。
|
||||
- 使用配置的心跳提示(默认:`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`)+ `HEARTBEAT_OK` 跳过行为。
|
||||
@@ -390,21 +390,21 @@ WhatsApp 以**语音消息**(PTT 气泡)发送音频。
|
||||
|
||||
- 子系统:`whatsapp/inbound`、`whatsapp/outbound`、`web-heartbeat`、`web-reconnect`。
|
||||
- 日志文件:`/tmp/openclaw/openclaw-YYYY-MM-DD.log`(可配置)。
|
||||
- 故障排除指南:[Gateway 故障排除](/gateway/troubleshooting)。
|
||||
- 故障排除指南:[Gateway网关故障排除](/gateway/troubleshooting)。
|
||||
|
||||
## 故障排除(快速)
|
||||
|
||||
**未关联 / 需要二维码登录**
|
||||
|
||||
- 症状:`channels status` 显示 `linked: false` 或警告"未关联"。
|
||||
- 修复:在 Gateway 主机上运行 `openclaw channels login` 并扫描二维码(WhatsApp → 设置 → 已关联设备)。
|
||||
- 修复:在 Gateway网关主机上运行 `openclaw channels login` 并扫描二维码(WhatsApp → 设置 → 已关联设备)。
|
||||
|
||||
**已关联但断开连接 / 重连循环**
|
||||
|
||||
- 症状:`channels status` 显示 `running, disconnected` 或警告"已关联但断开连接"。
|
||||
- 修复:`openclaw doctor`(或重启 Gateway)。如果问题持续,通过 `channels login` 重新关联并检查 `openclaw logs --follow`。
|
||||
- 修复:`openclaw doctor`(或重启 Gateway网关)。如果问题持续,通过 `channels login` 重新关联并检查 `openclaw logs --follow`。
|
||||
|
||||
**Bun 运行时**
|
||||
|
||||
- **不推荐**使用 Bun。WhatsApp(Baileys)和 Telegram 在 Bun 上不稳定。
|
||||
请使用 **Node** 运行 Gateway。(参见入门指南运行时说明。)
|
||||
请使用 **Node** 运行 Gateway网关。(参见入门指南运行时说明。)
|
||||
|
||||
+10
-10
@@ -21,7 +21,7 @@ x-i18n:
|
||||
Zalo 以插件形式提供,不包含在核心安装中。
|
||||
|
||||
- 通过 CLI 安装:`openclaw plugins install @openclaw/zalo`
|
||||
- 或在上手引导中选择 **Zalo** 并确认安装提示
|
||||
- 或在新手引导中选择 **Zalo** 并确认安装提示
|
||||
- 详情:[插件](/plugin)
|
||||
|
||||
## 快速设置(新手)
|
||||
@@ -29,11 +29,11 @@ Zalo 以插件形式提供,不包含在核心安装中。
|
||||
1. 安装 Zalo 插件:
|
||||
- 从源码检出安装:`openclaw plugins install ./extensions/zalo`
|
||||
- 从 npm 安装(如已发布):`openclaw plugins install @openclaw/zalo`
|
||||
- 或在上手引导中选择 **Zalo** 并确认安装提示
|
||||
- 或在新手引导中选择 **Zalo** 并确认安装提示
|
||||
2. 设置令牌:
|
||||
- 环境变量:`ZALO_BOT_TOKEN=...`
|
||||
- 或配置:`channels.zalo.botToken: "..."`。
|
||||
3. 重启 Gateway(或完成上手引导)。
|
||||
3. 重启 Gateway网关(或完成新手引导)。
|
||||
4. 私信访问默认使用配对模式;首次联系时需批准配对码。
|
||||
|
||||
最小配置:
|
||||
@@ -52,10 +52,10 @@ Zalo 以插件形式提供,不包含在核心安装中。
|
||||
|
||||
## 简介
|
||||
|
||||
Zalo 是一款面向越南市场的即时通讯应用;其 Bot API 允许 Gateway 运行一个用于一对一对话的机器人。
|
||||
Zalo 是一款面向越南市场的即时通讯应用;其 Bot API 允许 Gateway网关运行一个用于一对一对话的机器人。
|
||||
它非常适合需要将消息确定性路由回 Zalo 的客服或通知场景。
|
||||
|
||||
- 由 Gateway 管理的 Zalo Bot API 渠道。
|
||||
- 由 Gateway网关管理的 Zalo Bot API 渠道。
|
||||
- 确定性路由:回复始终返回 Zalo;模型不会选择渠道。
|
||||
- 私信共享智能体的主会话。
|
||||
- 群组尚不支持(Zalo 文档标注"即将推出")。
|
||||
@@ -88,7 +88,7 @@ Zalo 是一款面向越南市场的即时通讯应用;其 Bot API 允许 Gatew
|
||||
|
||||
多账户支持:使用 `channels.zalo.accounts`,为每个账户配置令牌和可选的 `name`。
|
||||
|
||||
3. 重启 Gateway。当令牌被解析(通过环境变量或配置)时,Zalo 将启动。
|
||||
3. 重启 Gateway网关。当令牌被解析(通过环境变量或配置)时,Zalo 将启动。
|
||||
4. 私信访问默认使用配对模式。机器人首次被联系时,请批准配对码。
|
||||
|
||||
## 工作原理(行为)
|
||||
@@ -121,7 +121,7 @@ Zalo 是一款面向越南市场的即时通讯应用;其 Bot API 允许 Gatew
|
||||
- Webhook 密钥必须为 8-256 个字符。
|
||||
- Webhook URL 必须使用 HTTPS。
|
||||
- Zalo 通过 `X-Bot-Api-Secret-Token` 请求头发送事件以进行验证。
|
||||
- Gateway HTTP 在 `channels.zalo.webhookPath` 处理 webhook 请求(默认为 webhook URL 路径)。
|
||||
- Gateway网关 HTTP 在 `channels.zalo.webhookPath` 处理 webhook 请求(默认为 webhook URL 路径)。
|
||||
|
||||
**注意:** 根据 Zalo API 文档,getUpdates(轮询)和 webhook 互斥。
|
||||
|
||||
@@ -156,13 +156,13 @@ Zalo 是一款面向越南市场的即时通讯应用;其 Bot API 允许 Gatew
|
||||
|
||||
- 检查令牌是否有效:`openclaw channels status --probe`
|
||||
- 验证发送者是否已批准(配对或 allowFrom)
|
||||
- 检查 Gateway 日志:`openclaw logs --follow`
|
||||
- 检查 Gateway网关日志:`openclaw logs --follow`
|
||||
|
||||
**Webhook 未收到事件:**
|
||||
|
||||
- 确保 webhook URL 使用 HTTPS
|
||||
- 验证密钥令牌为 8-256 个字符
|
||||
- 确认 Gateway HTTP 端点在配置的路径上可达
|
||||
- 确认 Gateway网关 HTTP 端点在配置的路径上可达
|
||||
- 检查 getUpdates 轮询是否未在运行(两者互斥)
|
||||
|
||||
## 配置参考(Zalo)
|
||||
@@ -179,7 +179,7 @@ Zalo 是一款面向越南市场的即时通讯应用;其 Bot API 允许 Gatew
|
||||
- `channels.zalo.mediaMaxMb`:入站/出站媒体大小上限(MB,默认 5)。
|
||||
- `channels.zalo.webhookUrl`:启用 webhook 模式(需要 HTTPS)。
|
||||
- `channels.zalo.webhookSecret`:webhook 密钥(8-256 个字符)。
|
||||
- `channels.zalo.webhookPath`:Gateway HTTP 服务器上的 webhook 路径。
|
||||
- `channels.zalo.webhookPath`:Gateway网关 HTTP 服务器上的 webhook 路径。
|
||||
- `channels.zalo.proxy`:API 请求的代理 URL。
|
||||
|
||||
多账户选项:
|
||||
|
||||
@@ -29,7 +29,7 @@ Zalo Personal 以插件形式提供,不包含在核心安装包中。
|
||||
|
||||
## 前置条件:zca-cli
|
||||
|
||||
Gateway 所在机器必须在 `PATH` 中包含 `zca` 可执行文件。
|
||||
Gateway网关所在机器必须在 `PATH` 中包含 `zca` 可执行文件。
|
||||
|
||||
- 验证:`zca --version`
|
||||
- 如果缺失,请安装 zca-cli(参见 `extensions/zalouser/README.md` 或上游 zca-cli 文档)。
|
||||
@@ -37,7 +37,7 @@ Gateway 所在机器必须在 `PATH` 中包含 `zca` 可执行文件。
|
||||
## 快速设置(入门)
|
||||
|
||||
1. 安装插件(见上文)。
|
||||
2. 登录(二维码方式,在 Gateway 机器上操作):
|
||||
2. 登录(二维码方式,在 Gateway网关机器上操作):
|
||||
- `openclaw channels login --channel zalouser`
|
||||
- 使用 Zalo 手机应用扫描终端中的二维码。
|
||||
3. 启用渠道:
|
||||
@@ -53,7 +53,7 @@ Gateway 所在机器必须在 `PATH` 中包含 `zca` 可执行文件。
|
||||
}
|
||||
```
|
||||
|
||||
4. 重启 Gateway(或完成上手引导)。
|
||||
4. 重启 Gateway网关(或完成新手引导)。
|
||||
5. 私信访问默认为配对模式;首次联系时需批准配对码。
|
||||
|
||||
## 功能说明
|
||||
@@ -139,7 +139,7 @@ openclaw directory groups list --channel zalouser --query "work"
|
||||
|
||||
**找不到 `zca`:**
|
||||
|
||||
- 安装 zca-cli 并确保 Gateway 进程的 `PATH` 中包含该命令。
|
||||
- 安装 zca-cli 并确保 Gateway网关进程的 `PATH` 中包含该命令。
|
||||
|
||||
**登录状态无法保持:**
|
||||
|
||||
|
||||
Reference in New Issue
Block a user