mirror of
https://github.com/farcasclaudiu/openclaw.git
synced 2026-06-29 01:02:03 +03:00
docs: canonicalize docs paths and align zh navigation (#11428)
* docs(navigation): canonicalize paths and align zh nav * chore(docs): remove stray .DS_Store * docs(scripts): add non-mint docs link audit * docs(nav): fix zh source paths and preserve legacy redirects (#11428) (thanks @sebslight) * chore(docs): satisfy lint for docs link audit script (#11428) (thanks @sebslight)
This commit is contained in:
Seb Slight
@@ -25,7 +25,7 @@ x-i18n:
|
||||
- OpenClaw 通过其 REST API 与之通信（`GET /api/v1/ping`、`POST /message/text`、`POST /chat/:id/*`）。
|
||||
- 传入消息通过 webhook 到达；发出的回复、输入指示器、已读回执和 tapback 均为 REST 调用。
|
||||
- 附件和贴纸作为入站媒体被接收（并在可能时呈现给智能体）。
|
||||
- 配对/白名单的工作方式与其他渠道相同（`/start/pairing` 等），使用 `channels.bluebubbles.allowFrom` + 配对码。
|
||||
- 配对/白名单的工作方式与其他渠道相同（`/channels/pairing` 等），使用 `channels.bluebubbles.allowFrom` + 配对码。
|
||||
- 回应作为系统事件呈现，与 Slack/Telegram 类似，智能体可以在回复前"提及"它们。
|
||||
- 高级功能：编辑、撤回、回复线程、消息效果、群组管理。
|
||||
|
||||
@@ -80,7 +80,7 @@ openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --passwor
|
||||
- 批准方式：
|
||||
- `openclaw pairing list bluebubbles`
|
||||
- `openclaw pairing approve bluebubbles <CODE>`
|
||||
- 配对是默认的令牌交换方式。详情：[配对](/start/pairing)
|
||||
- 配对是默认的令牌交换方式。详情：[配对](/channels/pairing)
|
||||
|
||||
群组：
|
||||
|
||||
@@ -268,4 +268,4 @@ OpenClaw 可能会显示*短*消息 ID（例如 `1`、`2`）以节省 token。
|
||||
- OpenClaw 会根据 BlueBubbles 服务器的 macOS 版本自动隐藏已知不可用的操作。如果在 macOS 26（Tahoe）上编辑仍然显示，请使用 `channels.bluebubbles.actions.edit=false` 手动禁用。
|
||||
- 查看状态/健康信息：`openclaw status --all` 或 `openclaw status --deep`。
|
||||
|
||||
有关通用渠道工作流参考，请参阅[渠道](/channels)和[插件](/plugins)指南。
|
||||
有关通用渠道工作流参考，请参阅[渠道](/channels)和[插件](/tools/plugin)指南。
|
||||
|
||||
@@ -0,0 +1,449 @@
|
||||
---
|
||||
read_when:
|
||||
- 配置广播群组
|
||||
- 调试 WhatsApp 中的多智能体回复
|
||||
status: experimental
|
||||
summary: 向多个智能体广播 WhatsApp 消息
|
||||
title: 广播群组
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:43:43Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: eaeb4035912c49413e012177cf0bd28b348130d30d3317674418dca728229b70
|
||||
source_path: channels/broadcast-groups.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 广播群组
|
||||
|
||||
**状态：** 实验性功能
|
||||
**版本：** 于 2026.1.9 版本新增
|
||||
|
||||
## 概述
|
||||
|
||||
广播群组允许多个智能体同时处理并响应同一条消息。这使你能够在单个 WhatsApp 群组或私信中创建协同工作的专业智能体团队——全部使用同一个手机号码。
|
||||
|
||||
当前范围：**仅限 WhatsApp**（web 渠道）。
|
||||
|
||||
广播群组在渠道白名单和群组激活规则之后进行评估。在 WhatsApp 群组中，这意味着广播会在 OpenClaw 正常回复时发生（例如：被提及时，具体取决于你的群组设置）。
|
||||
|
||||
## 使用场景
|
||||
|
||||
### 1. 专业智能体团队
|
||||
|
||||
部署多个具有原子化、专注职责的智能体：
|
||||
|
||||
```
|
||||
Group: "Development Team"
|
||||
Agents:
|
||||
- CodeReviewer (reviews code snippets)
|
||||
- DocumentationBot (generates docs)
|
||||
- SecurityAuditor (checks for vulnerabilities)
|
||||
- TestGenerator (suggests test cases)
|
||||
```
|
||||
|
||||
每个智能体处理相同的消息并提供其专业视角。
|
||||
|
||||
### 2. 多语言支持
|
||||
|
||||
```
|
||||
Group: "International Support"
|
||||
Agents:
|
||||
- Agent_EN (responds in English)
|
||||
- Agent_DE (responds in German)
|
||||
- Agent_ES (responds in Spanish)
|
||||
```
|
||||
|
||||
### 3. 质量保证工作流
|
||||
|
||||
```
|
||||
Group: "Customer Support"
|
||||
Agents:
|
||||
- SupportAgent (provides answer)
|
||||
- QAAgent (reviews quality, only responds if issues found)
|
||||
```
|
||||
|
||||
### 4. 任务自动化
|
||||
|
||||
```
|
||||
Group: "Project Management"
|
||||
Agents:
|
||||
- TaskTracker (updates task database)
|
||||
- TimeLogger (logs time spent)
|
||||
- ReportGenerator (creates summaries)
|
||||
```
|
||||
|
||||
## 配置
|
||||
|
||||
### 基本设置
|
||||
|
||||
添加一个顶层 `broadcast` 部分（与 `bindings` 同级）。键为 WhatsApp peer id：
|
||||
|
||||
- 群聊：群组 JID（例如 `120363403215116621@g.us`）
|
||||
- 私信：E.164 格式的电话号码（例如 `+15551234567`）
|
||||
|
||||
```json
|
||||
{
|
||||
"broadcast": {
|
||||
"120363403215116621@g.us": ["alfred", "baerbel", "assistant3"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**结果：** 当 OpenClaw 在此聊天中回复时，将运行所有三个智能体。
|
||||
|
||||
### 处理策略
|
||||
|
||||
控制智能体如何处理消息：
|
||||
|
||||
#### 并行（默认）
|
||||
|
||||
所有智能体同时处理：
|
||||
|
||||
```json
|
||||
{
|
||||
"broadcast": {
|
||||
"strategy": "parallel",
|
||||
"120363403215116621@g.us": ["alfred", "baerbel"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 顺序
|
||||
|
||||
智能体按顺序处理（后一个等待前一个完成）：
|
||||
|
||||
```json
|
||||
{
|
||||
"broadcast": {
|
||||
"strategy": "sequential",
|
||||
"120363403215116621@g.us": ["alfred", "baerbel"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 完整示例
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"list": [
|
||||
{
|
||||
"id": "code-reviewer",
|
||||
"name": "Code Reviewer",
|
||||
"workspace": "/path/to/code-reviewer",
|
||||
"sandbox": { "mode": "all" }
|
||||
},
|
||||
{
|
||||
"id": "security-auditor",
|
||||
"name": "Security Auditor",
|
||||
"workspace": "/path/to/security-auditor",
|
||||
"sandbox": { "mode": "all" }
|
||||
},
|
||||
{
|
||||
"id": "docs-generator",
|
||||
"name": "Documentation Generator",
|
||||
"workspace": "/path/to/docs-generator",
|
||||
"sandbox": { "mode": "all" }
|
||||
}
|
||||
]
|
||||
},
|
||||
"broadcast": {
|
||||
"strategy": "parallel",
|
||||
"120363403215116621@g.us": ["code-reviewer", "security-auditor", "docs-generator"],
|
||||
"120363424282127706@g.us": ["support-en", "support-de"],
|
||||
"+15555550123": ["assistant", "logger"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 工作原理
|
||||
|
||||
### 消息流程
|
||||
|
||||
1. **接收消息** 到达 WhatsApp 群组
|
||||
2. **广播检查**：系统检查 peer ID 是否在 `broadcast` 中
|
||||
3. **如果在广播列表中**：
|
||||
- 所有列出的智能体处理该消息
|
||||
- 每个智能体有自己的会话键和隔离的上下文
|
||||
- 智能体并行处理（默认）或顺序处理
|
||||
4. **如果不在广播列表中**：
|
||||
- 应用正常路由（第一个匹配的绑定）
|
||||
|
||||
注意：广播群组不会绕过渠道白名单或群组激活规则（提及/命令等）。它们只改变消息符合处理条件时*运行哪些智能体*。
|
||||
|
||||
### 会话隔离
|
||||
|
||||
广播群组中的每个智能体完全独立维护：
|
||||
|
||||
- **会话键**（`agent:alfred:whatsapp:group:120363...` vs `agent:baerbel:whatsapp:group:120363...`）
|
||||
- **对话历史**（智能体看不到其他智能体的消息）
|
||||
- **工作空间**（如果配置了则使用独立的沙箱）
|
||||
- **工具访问权限**（不同的允许/拒绝列表）
|
||||
- **记忆/上下文**（独立的 IDENTITY.md、SOUL.md 等）
|
||||
- **群组上下文缓冲区**（用于上下文的最近群组消息）按 peer 共享，因此所有广播智能体在被触发时看到相同的上下文
|
||||
|
||||
这允许每个智能体拥有：
|
||||
|
||||
- 不同的个性
|
||||
- 不同的工具访问权限（例如只读 vs 读写）
|
||||
- 不同的模型（例如 opus vs sonnet）
|
||||
- 不同的已安装 Skills
|
||||
|
||||
### 示例：隔离的会话
|
||||
|
||||
在群组 `120363403215116621@g.us` 中，智能体为 `["alfred", "baerbel"]`：
|
||||
|
||||
**Alfred 的上下文：**
|
||||
|
||||
```
|
||||
Session: agent:alfred:whatsapp:group:120363403215116621@g.us
|
||||
History: [user message, alfred's previous responses]
|
||||
Workspace: /Users/pascal/openclaw-alfred/
|
||||
Tools: read, write, exec
|
||||
```
|
||||
|
||||
**Bärbel 的上下文：**
|
||||
|
||||
```
|
||||
Session: agent:baerbel:whatsapp:group:120363403215116621@g.us
|
||||
History: [user message, baerbel's previous responses]
|
||||
Workspace: /Users/pascal/openclaw-baerbel/
|
||||
Tools: read only
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 保持智能体专注
|
||||
|
||||
将每个智能体设计为具有单一、明确的职责：
|
||||
|
||||
```json
|
||||
{
|
||||
"broadcast": {
|
||||
"DEV_GROUP": ["formatter", "linter", "tester"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
✅ **好的做法：** 每个智能体只有一个任务
|
||||
❌ **不好的做法：** 一个通用的"dev-helper"智能体
|
||||
|
||||
### 2. 使用描述性名称
|
||||
|
||||
明确每个智能体的功能：
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"security-scanner": { "name": "Security Scanner" },
|
||||
"code-formatter": { "name": "Code Formatter" },
|
||||
"test-generator": { "name": "Test Generator" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 配置不同的工具访问权限
|
||||
|
||||
只给智能体提供它们需要的工具：
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"reviewer": {
|
||||
"tools": { "allow": ["read", "exec"] } // Read-only
|
||||
},
|
||||
"fixer": {
|
||||
"tools": { "allow": ["read", "write", "edit", "exec"] } // Read-write
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 监控性能
|
||||
|
||||
当有多个智能体时，请考虑：
|
||||
|
||||
- 使用 `"strategy": "parallel"`（默认）以提高速度
|
||||
- 将广播群组限制在 5-10 个智能体
|
||||
- 为较简单的智能体使用较快的模型
|
||||
|
||||
### 5. 优雅地处理失败
|
||||
|
||||
智能体独立失败。一个智能体的错误不会阻塞其他智能体：
|
||||
|
||||
```
|
||||
Message → [Agent A ✓, Agent B ✗ error, Agent C ✓]
|
||||
Result: Agent A and C respond, Agent B logs error
|
||||
```
|
||||
|
||||
## 兼容性
|
||||
|
||||
### 提供商
|
||||
|
||||
广播群组目前支持：
|
||||
|
||||
- ✅ WhatsApp（已实现）
|
||||
- 🚧 Telegram（计划中）
|
||||
- 🚧 Discord（计划中）
|
||||
- 🚧 Slack（计划中）
|
||||
|
||||
### 路由
|
||||
|
||||
广播群组与现有路由一起工作：
|
||||
|
||||
```json
|
||||
{
|
||||
"bindings": [
|
||||
{
|
||||
"match": { "channel": "whatsapp", "peer": { "kind": "group", "id": "GROUP_A" } },
|
||||
"agentId": "alfred"
|
||||
}
|
||||
],
|
||||
"broadcast": {
|
||||
"GROUP_B": ["agent1", "agent2"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `GROUP_A`：只有 alfred 响应（正常路由）
|
||||
- `GROUP_B`：agent1 和 agent2 都响应（广播）
|
||||
|
||||
**优先级：** `broadcast` 优先于 `bindings`。
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 智能体不响应
|
||||
|
||||
**检查：**
|
||||
|
||||
1. 智能体 ID 存在于 `agents.list` 中
|
||||
2. Peer ID 格式正确（例如 `120363403215116621@g.us`）
|
||||
3. 智能体不在拒绝列表中
|
||||
|
||||
**调试：**
|
||||
|
||||
```bash
|
||||
tail -f ~/.openclaw/logs/gateway.log | grep broadcast
|
||||
```
|
||||
|
||||
### 只有一个智能体响应
|
||||
|
||||
**原因：** Peer ID 可能在 `bindings` 中但不在 `broadcast` 中。
|
||||
|
||||
**修复：** 添加到广播配置或从绑定中移除。
|
||||
|
||||
### 性能问题
|
||||
|
||||
**如果智能体较多时速度较慢：**
|
||||
|
||||
- 减少每个群组的智能体数量
|
||||
- 使用较轻的模型（sonnet 而非 opus）
|
||||
- 检查沙箱启动时间
|
||||
|
||||
## 示例
|
||||
|
||||
### 示例 1：代码审查团队
|
||||
|
||||
```json
|
||||
{
|
||||
"broadcast": {
|
||||
"strategy": "parallel",
|
||||
"120363403215116621@g.us": [
|
||||
"code-formatter",
|
||||
"security-scanner",
|
||||
"test-coverage",
|
||||
"docs-checker"
|
||||
]
|
||||
},
|
||||
"agents": {
|
||||
"list": [
|
||||
{
|
||||
"id": "code-formatter",
|
||||
"workspace": "~/agents/formatter",
|
||||
"tools": { "allow": ["read", "write"] }
|
||||
},
|
||||
{
|
||||
"id": "security-scanner",
|
||||
"workspace": "~/agents/security",
|
||||
"tools": { "allow": ["read", "exec"] }
|
||||
},
|
||||
{
|
||||
"id": "test-coverage",
|
||||
"workspace": "~/agents/testing",
|
||||
"tools": { "allow": ["read", "exec"] }
|
||||
},
|
||||
{ "id": "docs-checker", "workspace": "~/agents/docs", "tools": { "allow": ["read"] } }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**用户发送：** 代码片段
|
||||
**响应：**
|
||||
|
||||
- code-formatter："修复了缩进并添加了类型提示"
|
||||
- security-scanner："⚠️ 第 12 行存在 SQL 注入漏洞"
|
||||
- test-coverage："覆盖率为 45%，缺少错误情况的测试"
|
||||
- docs-checker："函数 `process_data` 缺少文档字符串"
|
||||
|
||||
### 示例 2：多语言支持
|
||||
|
||||
```json
|
||||
{
|
||||
"broadcast": {
|
||||
"strategy": "sequential",
|
||||
"+15555550123": ["detect-language", "translator-en", "translator-de"]
|
||||
},
|
||||
"agents": {
|
||||
"list": [
|
||||
{ "id": "detect-language", "workspace": "~/agents/lang-detect" },
|
||||
{ "id": "translator-en", "workspace": "~/agents/translate-en" },
|
||||
{ "id": "translator-de", "workspace": "~/agents/translate-de" }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## API 参考
|
||||
|
||||
### 配置模式
|
||||
|
||||
```typescript
|
||||
interface OpenClawConfig {
|
||||
broadcast?: {
|
||||
strategy?: "parallel" | "sequential";
|
||||
[peerId: string]: string[];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### 字段
|
||||
|
||||
- `strategy`（可选）：如何处理智能体
|
||||
- `"parallel"`（默认）：所有智能体同时处理
|
||||
- `"sequential"`：智能体按数组顺序处理
|
||||
- `[peerId]`：WhatsApp 群组 JID、E.164 号码或其他 peer ID
|
||||
- 值：应处理消息的智能体 ID 数组
|
||||
|
||||
## 限制
|
||||
|
||||
1. **最大智能体数：** 无硬性限制，但 10 个以上智能体可能会较慢
|
||||
2. **共享上下文：** 智能体看不到彼此的响应（设计如此）
|
||||
3. **消息顺序：** 并行响应可能以任意顺序到达
|
||||
4. **速率限制：** 所有智能体都计入 WhatsApp 速率限制
|
||||
|
||||
## 未来增强
|
||||
|
||||
计划中的功能：
|
||||
|
||||
- [ ] 共享上下文模式（智能体可以看到彼此的响应）
|
||||
- [ ] 智能体协调（智能体可以相互发信号）
|
||||
- [ ] 动态智能体选择（根据消息内容选择智能体）
|
||||
- [ ] 智能体优先级（某些智能体先于其他智能体响应）
|
||||
|
||||
## 另请参阅
|
||||
|
||||
- [多智能体配置](/tools/multi-agent-sandbox-tools)
|
||||
- [路由配置](/channels/channel-routing)
|
||||
- [会话管理](/concepts/sessions)
|
||||
@@ -0,0 +1,117 @@
|
||||
---
|
||||
read_when:
|
||||
- 更改渠道路由或收件箱行为
|
||||
summary: 每个渠道（WhatsApp、Telegram、Discord、Slack）的路由规则及共享上下文
|
||||
title: 渠道路由
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T20:22:21Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 1a322b5187e32c82fc1e8aac02437e2eeb7ba84e7b3a1db89feeab1dcf7dbbab
|
||||
source_path: channels/channel-routing.md
|
||||
workflow: 14
|
||||
---
|
||||
|
||||
# 渠道与路由
|
||||
|
||||
OpenClaw 将回复**路由回消息来源的渠道**。模型不会选择渠道；路由是确定性的，由主机配置控制。
|
||||
|
||||
## 关键术语
|
||||
|
||||
- **渠道**：`whatsapp`、`telegram`、`discord`、`slack`、`signal`、`imessage`、`webchat`。
|
||||
- **AccountId**：每个渠道的账户实例（在支持的情况下）。
|
||||
- **AgentId**：隔离的工作区 + 会话存储（"大脑"）。
|
||||
- **SessionKey**：用于存储上下文和控制并发的桶键。
|
||||
|
||||
## 会话键格式（示例）
|
||||
|
||||
私信会折叠到智能体的**主**会话：
|
||||
|
||||
- `agent:<agentId>:<mainKey>`（默认：`agent:main:main`）
|
||||
|
||||
群组和渠道按渠道隔离：
|
||||
|
||||
- 群组：`agent:<agentId>:<channel>:group:<id>`
|
||||
- 渠道/房间：`agent:<agentId>:<channel>:channel:<id>`
|
||||
|
||||
线程：
|
||||
|
||||
- Slack/Discord 线程会在基础键后追加 `:thread:<threadId>`。
|
||||
- Telegram 论坛主题在群组键中嵌入 `:topic:<topicId>`。
|
||||
|
||||
示例：
|
||||
|
||||
- `agent:main:telegram:group:-1001234567890:topic:42`
|
||||
- `agent:main:discord:channel:123456:thread:987654`
|
||||
|
||||
## 路由规则（如何选择智能体）
|
||||
|
||||
路由为每条入站消息选择**一个智能体**：
|
||||
|
||||
1. **精确对端匹配**（`bindings` 中的 `peer.kind` + `peer.id`）。
|
||||
2. **Guild 匹配**（Discord）通过 `guildId`。
|
||||
3. **Team 匹配**（Slack）通过 `teamId`。
|
||||
4. **账户匹配**（渠道上的 `accountId`）。
|
||||
5. **渠道匹配**（该渠道上的任意账户）。
|
||||
6. **默认智能体**（`agents.list[].default`，否则取列表第一项，兜底为 `main`）。
|
||||
|
||||
匹配到的智能体决定使用哪个工作区和会话存储。
|
||||
|
||||
## 广播组（运行多个智能体）
|
||||
|
||||
广播组允许你为同一对端运行**多个智能体**，**在 OpenClaw 正常回复时**触发（例如：在 WhatsApp 群组中，经过提及/激活门控之后）。
|
||||
|
||||
配置：
|
||||
|
||||
```json5
|
||||
{
|
||||
broadcast: {
|
||||
strategy: "parallel",
|
||||
"120363403215116621@g.us": ["alfred", "baerbel"],
|
||||
"+15555550123": ["support", "logger"],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
参见：[广播组](/channels/broadcast-groups)。
|
||||
|
||||
## 配置概览
|
||||
|
||||
- `agents.list`：命名的智能体定义（工作区、模型等）。
|
||||
- `bindings`：将入站渠道/账户/对端映射到智能体。
|
||||
|
||||
示例：
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
list: [{ id: "support", name: "Support", workspace: "~/.openclaw/workspace-support" }],
|
||||
},
|
||||
bindings: [
|
||||
{ match: { channel: "slack", teamId: "T123" }, agentId: "support" },
|
||||
{ match: { channel: "telegram", peer: { kind: "group", id: "-100123" } }, agentId: "support" },
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
## 会话存储
|
||||
|
||||
会话存储位于状态目录下（默认 `~/.openclaw`）：
|
||||
|
||||
- `~/.openclaw/agents/<agentId>/sessions/sessions.json`
|
||||
- JSONL 记录文件与存储位于同一目录
|
||||
|
||||
你可以通过 `session.store` 和 `{agentId}` 模板来覆盖存储路径。
|
||||
|
||||
## WebChat 行为
|
||||
|
||||
WebChat 连接到**所选智能体**，并默认使用该智能体的主会话。因此，WebChat 让你可以在一个地方查看该智能体的跨渠道上下文。
|
||||
|
||||
## 回复上下文
|
||||
|
||||
入站回复包含：
|
||||
|
||||
- `ReplyToId`、`ReplyToBody` 和 `ReplyToSender`（在可用时）。
|
||||
- 引用的上下文会以 `[Replying to ...]` 块的形式追加到 `Body` 中。
|
||||
|
||||
这在所有渠道中保持一致。
|
||||
@@ -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）
|
||||
|
||||
在 `~/.openclaw/openclaw.json` 中添加 `groupChat` 块，以便在 WhatsApp 剥离文本正文中的可视 `@` 时，显示名称提及仍能正常工作：
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
whatsapp: {
|
||||
groups: {
|
||||
"*": { requireMention: true },
|
||||
},
|
||||
},
|
||||
},
|
||||
agents: {
|
||||
list: [
|
||||
{
|
||||
id: "main",
|
||||
groupChat: {
|
||||
historyLimit: 50,
|
||||
mentionPatterns: ["@?openclaw", "\\+?15555550123"],
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
注意：
|
||||
|
||||
- 正则表达式不区分大小写；它们涵盖了像 `@openclaw` 这样的显示名称提及，以及带或不带 `+`/空格的原始号码。
|
||||
- 当有人点击联系人时，WhatsApp 仍会通过 `mentionedJids` 发送规范的提及，因此号码回退很少需要，但作为安全网很有用。
|
||||
|
||||
### 激活命令（仅所有者）
|
||||
|
||||
使用群聊命令：
|
||||
|
||||
- `/activation mention`
|
||||
- `/activation always`
|
||||
|
||||
只有所有者号码（来自 `channels.whatsapp.allowFrom`，或未设置时使用机器人自己的 E.164）可以更改此设置。在群组中发送 `/status` 作为独立消息以查看当前激活模式。
|
||||
|
||||
## 使用方法
|
||||
|
||||
1. 将你的 WhatsApp 账号（运行 OpenClaw 的账号）添加到群组。
|
||||
2. 说 `@openclaw …`（或包含号码）。只有允许列表中的发送者才能触发，除非你设置 `groupPolicy: "open"`。
|
||||
3. 智能体提示将包含最近的群组上下文以及尾部的 `[from: …]` 标记，以便它能够回应正确的人。
|
||||
4. 会话级指令（`/verbose on`、`/think high`、`/new` 或 `/reset`、`/compact`）仅适用于该群组的会话；将它们作为独立消息发送以使其生效。你的个人私信会话保持独立。
|
||||
|
||||
## 测试/验证
|
||||
|
||||
- 手动冒烟测试：
|
||||
- 在群组中发送 `@openclaw` 提及，确认收到引用发送者名称的回复。
|
||||
- 发送第二次提及，验证历史记录块被包含，然后在下一轮清除。
|
||||
- 检查 Gateway 网关日志（使用 `--verbose` 运行）以查看 `inbound web message` 条目，显示 `from: <groupJid>` 和 `[from: …]` 后缀。
|
||||
|
||||
## 已知注意事项
|
||||
|
||||
- 群组有意跳过心跳以避免嘈杂的广播。
|
||||
- 回声抑制使用组合的批次字符串；如果你发送两次相同的文本但没有提及，只有第一次会得到响应。
|
||||
- 会话存储条目将在会话存储中显示为 `agent:<agentId>:whatsapp:group:<jid>`（默认为 `~/.openclaw/agents/<agentId>/sessions/sessions.json`）；缺失条目只是意味着该群组尚未触发运行。
|
||||
- 群组中的输入指示器遵循 `agents.defaults.typingMode`（默认：未被提及时为 `message`）。
|
||||
@@ -0,0 +1,379 @@
|
||||
---
|
||||
read_when:
|
||||
- 更改群聊行为或提及限制
|
||||
summary: 跨平台的群聊行为（WhatsApp/Telegram/Discord/Slack/Signal/iMessage/Microsoft Teams）
|
||||
title: 群组
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:47:08Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: b727a053edf51f6e7b5c0c324c2fc9c9789a9796c37f622418bd555e8b5a0ec4
|
||||
source_path: channels/groups.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 群组
|
||||
|
||||
OpenClaw 在各平台上统一处理群聊：WhatsApp、Telegram、Discord、Slack、Signal、iMessage、Microsoft Teams。
|
||||
|
||||
## 新手入门（2 分钟）
|
||||
|
||||
OpenClaw"运行"在你自己的消息账户上。没有单独的 WhatsApp 机器人用户。如果**你**在一个群组中，OpenClaw 就可以看到该群组并在其中回复。
|
||||
|
||||
默认行为：
|
||||
|
||||
- 群组受限（`groupPolicy: "allowlist"`）。
|
||||
- 除非你明确禁用提及限制，否则回复需要 @ 提及。
|
||||
|
||||
解释：允许列表中的发送者可以通过提及来触发 OpenClaw。
|
||||
|
||||
> 简而言之
|
||||
>
|
||||
> - **私信访问**由 `*.allowFrom` 控制。
|
||||
> - **群组访问**由 `*.groupPolicy` + 允许列表（`*.groups`、`*.groupAllowFrom`）控制。
|
||||
> - **回复触发**由提及限制（`requireMention`、`/activation`）控制。
|
||||
|
||||
快速流程（群消息会发生什么）：
|
||||
|
||||
```
|
||||
groupPolicy? disabled -> 丢弃
|
||||
groupPolicy? allowlist -> 群组允许? 否 -> 丢弃
|
||||
requireMention? 是 -> 被提及? 否 -> 仅存储为上下文
|
||||
否则 -> 回复
|
||||
```
|
||||
|
||||
|
||||
|
||||
如果你想...
|
||||
| 目标 | 设置什么 |
|
||||
|------|-------------|
|
||||
| 允许所有群组但仅在 @ 提及时回复 | `groups: { "*": { requireMention: true } }` |
|
||||
| 禁用所有群组回复 | `groupPolicy: "disabled"` |
|
||||
| 仅特定群组 | `groups: { "<group-id>": { ... } }`（无 `"*"` 键） |
|
||||
| 仅你可以在群组中触发 | `groupPolicy: "allowlist"`、`groupAllowFrom: ["+1555..."]` |
|
||||
|
||||
## 会话键
|
||||
|
||||
- 群组会话使用 `agent:<agentId>:<channel>:group:<id>` 会话键（房间/频道使用 `agent:<agentId>:<channel>:channel:<id>`）。
|
||||
- Telegram 论坛话题在群组 ID 后添加 `:topic:<threadId>`，因此每个话题都有自己的会话。
|
||||
- 私聊使用主会话（或按发送者配置时使用各自的会话）。
|
||||
- 群组会话跳过心跳。
|
||||
|
||||
## 模式：个人私信 + 公开群组（单智能体）
|
||||
|
||||
是的——如果你的"个人"流量是**私信**而"公开"流量是**群组**，这种方式效果很好。
|
||||
|
||||
原因：在单智能体模式下，私信通常落在**主**会话键（`agent:main:main`）中，而群组始终使用**非主**会话键（`agent:main:<channel>:group:<id>`）。如果你启用 `mode: "non-main"` 的沙箱隔离，这些群组会话在 Docker 中运行，而你的主私信会话保持在主机上。
|
||||
|
||||
这给你一个智能体"大脑"（共享工作区 + 记忆），但两种执行姿态：
|
||||
|
||||
- **私信**：完整工具（主机）
|
||||
- **群组**：沙箱 + 受限工具（Docker）
|
||||
|
||||
> 如果你需要真正独立的工作区/角色（"个人"和"公开"绝不能混合），请使用第二个智能体 + 绑定。参见[多智能体路由](/concepts/multi-agent)。
|
||||
|
||||
示例（私信在主机上，群组沙箱隔离 + 仅消息工具）：
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
sandbox: {
|
||||
mode: "non-main", // 群组/频道是非主 -> 沙箱隔离
|
||||
scope: "session", // 最强隔离（每个群组/频道一个容器）
|
||||
workspaceAccess: "none",
|
||||
},
|
||||
},
|
||||
},
|
||||
tools: {
|
||||
sandbox: {
|
||||
tools: {
|
||||
// 如果 allow 非空，其他所有工具都被阻止（deny 仍然优先）。
|
||||
allow: ["group:messaging", "group:sessions"],
|
||||
deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
想要"群组只能看到文件夹 X"而不是"无主机访问"？保持 `workspaceAccess: "none"` 并仅将允许的路径挂载到沙箱中：
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
sandbox: {
|
||||
mode: "non-main",
|
||||
scope: "session",
|
||||
workspaceAccess: "none",
|
||||
docker: {
|
||||
binds: [
|
||||
// hostPath:containerPath:mode
|
||||
"~/FriendsShared:/data:ro",
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
相关：
|
||||
|
||||
- 配置键和默认值：[Gateway 网关配置](/gateway/configuration#agentsdefaultssandbox)
|
||||
- 调试为什么工具被阻止：[沙箱 vs 工具策略 vs 提权](/gateway/sandbox-vs-tool-policy-vs-elevated)
|
||||
- 绑定挂载详情：[沙箱隔离](/gateway/sandboxing#custom-bind-mounts)
|
||||
|
||||
## 显示标签
|
||||
|
||||
- UI 标签在可用时使用 `displayName`，格式为 `<channel>:<token>`。
|
||||
- `#room` 保留用于房间/频道；群聊使用 `g-<slug>`（小写，空格 -> `-`，保留 `#@+._-`）。
|
||||
|
||||
## 群组策略
|
||||
|
||||
控制每个渠道如何处理群组/房间消息：
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
whatsapp: {
|
||||
groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
|
||||
groupAllowFrom: ["+15551234567"],
|
||||
},
|
||||
telegram: {
|
||||
groupPolicy: "disabled",
|
||||
groupAllowFrom: ["123456789", "@username"],
|
||||
},
|
||||
signal: {
|
||||
groupPolicy: "disabled",
|
||||
groupAllowFrom: ["+15551234567"],
|
||||
},
|
||||
imessage: {
|
||||
groupPolicy: "disabled",
|
||||
groupAllowFrom: ["chat_id:123"],
|
||||
},
|
||||
msteams: {
|
||||
groupPolicy: "disabled",
|
||||
groupAllowFrom: ["user@org.com"],
|
||||
},
|
||||
discord: {
|
||||
groupPolicy: "allowlist",
|
||||
guilds: {
|
||||
GUILD_ID: { channels: { help: { allow: true } } },
|
||||
},
|
||||
},
|
||||
slack: {
|
||||
groupPolicy: "allowlist",
|
||||
channels: { "#general": { allow: true } },
|
||||
},
|
||||
matrix: {
|
||||
groupPolicy: "allowlist",
|
||||
groupAllowFrom: ["@owner:example.org"],
|
||||
groups: {
|
||||
"!roomId:example.org": { allow: true },
|
||||
"#alias:example.org": { allow: true },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
| 策略 | 行为 |
|
||||
| ------------- | --------------------------------------- |
|
||||
| `"open"` | 群组绕过允许列表；提及限制仍然适用。 |
|
||||
| `"disabled"` | 完全阻止所有群组消息。 |
|
||||
| `"allowlist"` | 仅允许与配置的允许列表匹配的群组/房间。 |
|
||||
|
||||
注意事项：
|
||||
|
||||
- `groupPolicy` 与提及限制（需要 @ 提及）是分开的。
|
||||
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams：使用 `groupAllowFrom`（回退：显式 `allowFrom`）。
|
||||
- Discord：允许列表使用 `channels.discord.guilds.<id>.channels`。
|
||||
- Slack：允许列表使用 `channels.slack.channels`。
|
||||
- Matrix：允许列表使用 `channels.matrix.groups`（房间 ID、别名或名称）。使用 `channels.matrix.groupAllowFrom` 限制发送者；也支持每个房间的 `users` 允许列表。
|
||||
- 群组私信单独控制（`channels.discord.dm.*`、`channels.slack.dm.*`）。
|
||||
- Telegram 允许列表可以匹配用户 ID（`"123456789"`、`"telegram:123456789"`、`"tg:123456789"`）或用户名（`"@alice"` 或 `"alice"`）；前缀不区分大小写。
|
||||
- 默认为 `groupPolicy: "allowlist"`；如果你的群组允许列表为空，群组消息将被阻止。
|
||||
|
||||
快速心智模型（群组消息的评估顺序）：
|
||||
|
||||
1. `groupPolicy`（open/disabled/allowlist）
|
||||
2. 群组允许列表（`*.groups`、`*.groupAllowFrom`、渠道特定允许列表）
|
||||
3. 提及限制（`requireMention`、`/activation`）
|
||||
|
||||
## 提及限制（默认）
|
||||
|
||||
群组消息需要提及，除非按群组覆盖。默认值位于 `*.groups."*"` 下的每个子系统中。
|
||||
|
||||
回复机器人消息被视为隐式提及（当渠道支持回复元数据时）。这适用于 Telegram、WhatsApp、Slack、Discord 和 Microsoft Teams。
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
whatsapp: {
|
||||
groups: {
|
||||
"*": { requireMention: true },
|
||||
"123@g.us": { requireMention: false },
|
||||
},
|
||||
},
|
||||
telegram: {
|
||||
groups: {
|
||||
"*": { requireMention: true },
|
||||
"123456789": { requireMention: false },
|
||||
},
|
||||
},
|
||||
imessage: {
|
||||
groups: {
|
||||
"*": { requireMention: true },
|
||||
"123": { requireMention: false },
|
||||
},
|
||||
},
|
||||
},
|
||||
agents: {
|
||||
list: [
|
||||
{
|
||||
id: "main",
|
||||
groupChat: {
|
||||
mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"],
|
||||
historyLimit: 50,
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
注意事项：
|
||||
|
||||
- `mentionPatterns` 是不区分大小写的正则表达式。
|
||||
- 提供显式提及的平台仍然通过；模式是回退。
|
||||
- 每个智能体覆盖：`agents.list[].groupChat.mentionPatterns`（当多个智能体共享一个群组时有用）。
|
||||
- 提及限制仅在提及检测可行时强制执行（原生提及或 `mentionPatterns` 已配置）。
|
||||
- Discord 默认值位于 `channels.discord.guilds."*"`（可按服务器/频道覆盖）。
|
||||
- 群组历史上下文在渠道间统一包装，并且是**仅待处理**（由于提及限制而跳过的消息）；使用 `messages.groupChat.historyLimit` 作为全局默认值，使用 `channels.<channel>.historyLimit`（或 `channels.<channel>.accounts.*.historyLimit`）进行覆盖。设置 `0` 以禁用。
|
||||
|
||||
## 群组/频道工具限制（可选）
|
||||
|
||||
某些渠道配置支持限制**特定群组/房间/频道内**可用的工具。
|
||||
|
||||
- `tools`：为整个群组允许/拒绝工具。
|
||||
- `toolsBySender`：群组内的按发送者覆盖（键是发送者 ID/用户名/邮箱/电话号码，取决于渠道）。使用 `"*"` 作为通配符。
|
||||
|
||||
解析顺序（最具体的优先）：
|
||||
|
||||
1. 群组/频道 `toolsBySender` 匹配
|
||||
2. 群组/频道 `tools`
|
||||
3. 默认（`"*"`）`toolsBySender` 匹配
|
||||
4. 默认（`"*"`）`tools`
|
||||
|
||||
示例（Telegram）：
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
telegram: {
|
||||
groups: {
|
||||
"*": { tools: { deny: ["exec"] } },
|
||||
"-1001234567890": {
|
||||
tools: { deny: ["exec", "read", "write"] },
|
||||
toolsBySender: {
|
||||
"123456789": { alsoAllow: ["exec"] },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
注意事项：
|
||||
|
||||
- 群组/频道工具限制在全局/智能体工具策略之外额外应用（deny 仍然优先）。
|
||||
- 某些渠道对房间/频道使用不同的嵌套结构（例如，Discord `guilds.*.channels.*`、Slack `channels.*`、MS Teams `teams.*.channels.*`）。
|
||||
|
||||
## 群组允许列表
|
||||
|
||||
当配置了 `channels.whatsapp.groups`、`channels.telegram.groups` 或 `channels.imessage.groups` 时，键作为群组允许列表。使用 `"*"` 允许所有群组，同时仍设置默认提及行为。
|
||||
|
||||
常见意图（复制/粘贴）：
|
||||
|
||||
1. 禁用所有群组回复
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: { whatsapp: { groupPolicy: "disabled" } },
|
||||
}
|
||||
```
|
||||
|
||||
2. 仅允许特定群组（WhatsApp）
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
whatsapp: {
|
||||
groups: {
|
||||
"123@g.us": { requireMention: true },
|
||||
"456@g.us": { requireMention: false },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
3. 允许所有群组但需要提及（显式）
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
whatsapp: {
|
||||
groups: { "*": { requireMention: true } },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
4. 仅所有者可以在群组中触发（WhatsApp）
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
whatsapp: {
|
||||
groupPolicy: "allowlist",
|
||||
groupAllowFrom: ["+15551234567"],
|
||||
groups: { "*": { requireMention: true } },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## 激活（仅所有者）
|
||||
|
||||
群组所有者可以切换每个群组的激活状态：
|
||||
|
||||
- `/activation mention`
|
||||
- `/activation always`
|
||||
|
||||
所有者由 `channels.whatsapp.allowFrom` 确定（未设置时为机器人自身的 E.164）。将命令作为独立消息发送。其他平台目前忽略 `/activation`。
|
||||
|
||||
## 上下文字段
|
||||
|
||||
群组入站负载设置：
|
||||
|
||||
- `ChatType=group`
|
||||
- `GroupSubject`（如果已知）
|
||||
- `GroupMembers`（如果已知）
|
||||
- `WasMentioned`（提及限制结果）
|
||||
- Telegram 论坛话题还包括 `MessageThreadId` 和 `IsForum`。
|
||||
|
||||
智能体系统提示在新群组会话的第一轮包含群组介绍。它提醒模型像人类一样回复，避免 Markdown 表格，避免输入字面量 `\n` 序列。
|
||||
|
||||
## iMessage 特定内容
|
||||
|
||||
- 路由或允许列表时优先使用 `chat_id:<id>`。
|
||||
- 列出聊天：`imsg chats --limit 20`。
|
||||
- 群组回复始终返回到相同的 `chat_id`。
|
||||
|
||||
## WhatsApp 特定内容
|
||||
|
||||
参见[群消息](/channels/group-messages)了解 WhatsApp 专有行为（历史注入、提及处理详情）。
|
||||
@@ -205,7 +205,7 @@ exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"
|
||||
- 批准方式：
|
||||
- `openclaw pairing list imessage`
|
||||
- `openclaw pairing approve imessage <CODE>`
|
||||
- 配对是 iMessage 私信的默认令牌交换方式。详情：[配对](/start/pairing)
|
||||
- 配对是 iMessage 私信的默认令牌交换方式。详情：[配对](/channels/pairing)
|
||||
|
||||
群组：
|
||||
|
||||
|
||||
@@ -46,7 +46,7 @@ OpenClaw 可以在你已经使用的任何聊天应用上与你交流。每个
|
||||
- 渠道可以同时运行；配置多个渠道后，OpenClaw 会按聊天进行路由。
|
||||
- 最快的设置方式通常是 **Telegram**（简单的机器人令牌）。WhatsApp 需要二维码配对，
|
||||
并在磁盘上存储更多状态。
|
||||
- 群组行为因渠道而异；参见[群组](/concepts/groups)。
|
||||
- 群组行为因渠道而异；参见[群组](/channels/groups)。
|
||||
- 为安全起见，私信配对和允许列表会被强制执行；参见[安全](/gateway/security)。
|
||||
- Telegram 内部机制：[grammY 说明](/channels/grammy)。
|
||||
- 故障排除：[渠道故障排除](/channels/troubleshooting)。
|
||||
|
||||
@@ -36,7 +36,7 @@ openclaw plugins install ./extensions/matrix
|
||||
|
||||
如果你在配置/新手引导期间选择 Matrix 并检测到 git 检出，OpenClaw 将自动提供本地安装路径。
|
||||
|
||||
详情：[插件](/plugin)
|
||||
详情：[插件](/tools/plugin)
|
||||
|
||||
## 设置
|
||||
|
||||
|
||||
@@ -37,7 +37,7 @@ openclaw plugins install ./extensions/mattermost
|
||||
|
||||
如果你在配置/新手引导期间选择 Mattermost 并检测到 git 检出，OpenClaw 会自动提供本地安装路径。
|
||||
|
||||
详情：[插件](/plugin)
|
||||
详情：[插件](/tools/plugin)
|
||||
|
||||
## 快速设置
|
||||
|
||||
|
||||
@@ -43,7 +43,7 @@ openclaw plugins install ./extensions/msteams
|
||||
如果你在配置/新手引导过程中选择 Teams 并检测到 git 检出，
|
||||
OpenClaw 将自动提供本地安装路径。
|
||||
|
||||
详情：[插件](/plugin)
|
||||
详情：[插件](/tools/plugin)
|
||||
|
||||
## 快速设置（初学者）
|
||||
|
||||
|
||||
@@ -35,7 +35,7 @@ openclaw plugins install ./extensions/nextcloud-talk
|
||||
如果你在配置/新手引导过程中选择了 Nextcloud Talk，并且检测到 git 检出，
|
||||
OpenClaw 将自动提供本地安装路径。
|
||||
|
||||
详情：[插件](/plugin)
|
||||
详情：[插件](/tools/plugin)
|
||||
|
||||
## 快速设置（新手）
|
||||
|
||||
|
||||
@@ -0,0 +1,89 @@
|
||||
---
|
||||
read_when:
|
||||
- 设置私信访问控制
|
||||
- 配对新的 iOS/Android 节点
|
||||
- 审查 OpenClaw 安全态势
|
||||
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
|
||||
---
|
||||
|
||||
# 配对
|
||||
|
||||
"配对"是 OpenClaw 的显式**所有者批准**步骤。它用于两个地方：
|
||||
|
||||
1. **私信配对**（谁被允许与机器人对话）
|
||||
2. **节点配对**（哪些设备/节点被允许加入 Gateway 网关网络）
|
||||
|
||||
安全上下文：[安全](/gateway/security)
|
||||
|
||||
## 1）私信配对（入站聊天访问）
|
||||
|
||||
当渠道配置为私信策略 `pairing` 时，未知发送者会收到一个短代码，他们的消息**不会被处理**，直到你批准。
|
||||
|
||||
默认私信策略记录在：[安全](/gateway/security)
|
||||
|
||||
配对代码：
|
||||
|
||||
- 8 个字符，大写，无歧义字符（`0O1I`）。
|
||||
- **1 小时后过期**。机器人仅在创建新请求时发送配对消息（大约每个发送者每小时一次）。
|
||||
- 待处理的私信配对请求默认上限为**每个渠道 3 个**；在一个过期或被批准之前，额外的请求将被忽略。
|
||||
|
||||
### 批准发送者
|
||||
|
||||
```bash
|
||||
openclaw pairing list telegram
|
||||
openclaw pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
支持的渠道：`telegram`、`whatsapp`、`signal`、`imessage`、`discord`、`slack`。
|
||||
|
||||
### 状态存储位置
|
||||
|
||||
存储在 `~/.openclaw/credentials/` 下：
|
||||
|
||||
- 待处理请求：`<channel>-pairing.json`
|
||||
- 已批准允许列表存储：`<channel>-allowFrom.json`
|
||||
|
||||
将这些视为敏感信息（它们控制对你助手的访问）。
|
||||
|
||||
## 2）节点设备配对（iOS/Android/macOS/无头节点）
|
||||
|
||||
节点作为 `role: node` 的**设备**连接到 Gateway 网关。Gateway 网关创建一个必须被批准的设备配对请求。
|
||||
|
||||
### 批准节点设备
|
||||
|
||||
```bash
|
||||
openclaw devices list
|
||||
openclaw devices approve <requestId>
|
||||
openclaw devices reject <requestId>
|
||||
```
|
||||
|
||||
### 状态存储位置
|
||||
|
||||
存储在 `~/.openclaw/devices/` 下：
|
||||
|
||||
- `pending.json`（短期；待处理请求会过期）
|
||||
- `paired.json`（已配对设备 + 令牌）
|
||||
|
||||
### 说明
|
||||
|
||||
- 旧版 `node.pair.*` API（CLI：`openclaw 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)
|
||||
@@ -116,7 +116,7 @@ x-i18n:
|
||||
- 通过以下方式批准：
|
||||
- `openclaw pairing list signal`
|
||||
- `openclaw pairing approve signal <CODE>`
|
||||
- 配对是 Signal 私信的默认令牌交换方式。详情：[配对](/start/pairing)
|
||||
- 配对是 Signal 私信的默认令牌交换方式。详情：[配对](/channels/pairing)
|
||||
- 仅有 UUID 的发送者（来自 `sourceUuid`）在 `channels.signal.allowFrom` 中存储为 `uuid:<id>`。
|
||||
|
||||
群组：
|
||||
|
||||
@@ -356,7 +356,7 @@ Telegram 功能可以在两个级别配置（上面显示的对象形式；旧
|
||||
- 批准方式：
|
||||
- `openclaw pairing list telegram`
|
||||
- `openclaw pairing approve telegram <CODE>`
|
||||
- 配对是 Telegram 私信使用的默认 token 交换。详情：[配对](/start/pairing)
|
||||
- 配对是 Telegram 私信使用的默认 token 交换。详情：[配对](/channels/pairing)
|
||||
- `channels.telegram.allowFrom` 接受数字用户 ID（推荐）或 `@username` 条目。这**不是**机器人用户名；使用人类发送者的 ID。向导接受 `@username` 并在可能时将其解析为数字 ID。
|
||||
|
||||
#### 查找你的 Telegram 用户 ID
|
||||
|
||||
@@ -34,7 +34,7 @@ openclaw plugins install @openclaw/tlon
|
||||
openclaw plugins install ./extensions/tlon
|
||||
```
|
||||
|
||||
详情：[插件](/plugin)
|
||||
详情：[插件](/tools/plugin)
|
||||
|
||||
## 设置
|
||||
|
||||
|
||||
@@ -32,7 +32,7 @@ openclaw plugins install @openclaw/twitch
|
||||
openclaw plugins install ./extensions/twitch
|
||||
```
|
||||
|
||||
详情：[插件](/plugin)
|
||||
详情：[插件](/tools/plugin)
|
||||
|
||||
## 快速设置（新手）
|
||||
|
||||
|
||||
@@ -22,7 +22,7 @@ Zalo 以插件形式提供，不包含在核心安装中。
|
||||
|
||||
- 通过 CLI 安装：`openclaw plugins install @openclaw/zalo`
|
||||
- 或在新手引导期间选择 **Zalo** 并确认安装提示
|
||||
- 详情：[插件](/plugin)
|
||||
- 详情：[插件](/tools/plugin)
|
||||
|
||||
## 快速设置（初学者）
|
||||
|
||||
@@ -111,7 +111,7 @@ Zalo 是一款专注于越南市场的即时通讯应用；其 Bot API 让 Gatew
|
||||
- 通过以下方式批准：
|
||||
- `openclaw pairing list zalo`
|
||||
- `openclaw pairing approve zalo <CODE>`
|
||||
- 配对是默认的令牌交换方式。详情：[配对](/start/pairing)
|
||||
- 配对是默认的令牌交换方式。详情：[配对](/channels/pairing)
|
||||
- `channels.zalo.allowFrom` 接受数字用户 ID（无用户名查找功能）。
|
||||
|
||||
## 长轮询与 webhook
|
||||
|
||||
@@ -25,7 +25,7 @@ Zalo Personal 作为插件提供，不包含在核心安装中。
|
||||
|
||||
- 通过 CLI 安装：`openclaw plugins install @openclaw/zalouser`
|
||||
- 或从源码检出安装：`openclaw plugins install ./extensions/zalouser`
|
||||
- 详情：[插件](/plugin)
|
||||
- 详情：[插件](/tools/plugin)
|
||||
|
||||
## 前置条件：zca-cli
|
||||
|
||||
|
||||
Reference in New Issue
Block a user