github/openclaw
1
1
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-02-19 18:39:20 -05:00
Code Issues Packages Projects Releases Wiki Activity

Docs: add zh-CN translations

Browse Source
This commit is contained in:
Josh Palmer
2026-02-01 22:47:44 +01:00
parent e70984745b
commit 149dc7c4e7
298 changed files with 53861 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
docs/zh-CN/automation/auth-monitoring.md Normal file
View File

@@ -0,0 +1,47 @@
---
read_when:
- 设置认证过期监控或告警
- 自动化 Claude Code / Codex OAuth 刷新检查
summary: 监控模型提供商的 OAuth 过期状态
title: 认证监控
x-i18n:
generated_at: "2026-02-01T19:36:14Z"
model: claude-opus-4-5
provider: pi
source_hash: eef179af9545ed7ab881f3ccbef998869437fb50cdb4088de8da7223b614fa2b
source_path: automation/auth-monitoring.md
workflow: 14
---
# 认证监控
OpenClaw 通过 `openclaw models status` 暴露 OAuth 过期健康状态。可将其用于自动化和告警；脚本是针对手机工作流的可选补充。
## 推荐方式：CLI 检查（跨平台通用）
```bash
openclaw models status --check
```
退出码：
- `0`：正常
- `1`：凭证已过期或缺失
- `2`：即将过期（24 小时内）
适用于 cron/systemd，无需额外脚本。
## 可选脚本（运维/手机工作流）
这些脚本位于 `scripts/` 目录下，属于**可选项**。它们假定你可以通过 SSH 访问 Gateway 主机，并针对 systemd + Termux 进行了调优。
- `scripts/claude-auth-status.sh` 现在使用 `openclaw models status --json` 作为数据源（如果 CLI 不可用则回退到直接读取文件），因此请确保定时器中 `openclaw` 在 `PATH` 中。
- `scripts/auth-monitor.sh`：cron/systemd 定时器目标；发送告警（ntfy 或手机）。
- `scripts/systemd/openclaw-auth-monitor.{service,timer}`：systemd 用户定时器。
- `scripts/claude-auth-status.sh`：Claude Code + OpenClaw 认证检查器（完整/json/简洁模式）。
- `scripts/mobile-reauth.sh`：通过 SSH 进行引导式重新认证流程。
- `scripts/termux-quick-auth.sh`：一键小组件状态查看 + 打开认证 URL。
- `scripts/termux-auth-widget.sh`：完整的引导式小组件流程。
- `scripts/termux-sync-widget.sh`：将 Claude Code 凭证同步至 OpenClaw。
如果你不需要手机自动化或 systemd 定时器，可以跳过这些脚本。

434
docs/zh-CN/automation/cron-jobs.md Normal file
View File

@@ -0,0 +1,434 @@
---
read_when:
- 调度后台任务或唤醒
- 配置需要与心跳一起或并行运行的自动化
- 在心跳和定时任务之间做选择
summary: Gateway 调度器的定时任务与唤醒
title: 定时任务
x-i18n:
generated_at: "2026-02-01T19:37:32Z"
model: claude-opus-4-5
provider: pi
source_hash: d43268b0029f1b13d0825ddcc9c06a354987ea17ce02f3b5428a9c68bf936676
source_path: automation/cron-jobs.md
workflow: 14
---
# 定时任务（Gateway 调度器）
> **定时任务还是心跳？** 请参阅[定时任务与心跳对比](/automation/cron-vs-heartbeat)了解何时使用哪种方式。
定时任务是 Gateway 内置的调度器。它持久化任务、在合适的时间唤醒智能体，并可选择将输出发送回聊天。
如果你想要 _"每天早上运行"_ 或 _"20 分钟后提醒智能体"_，定时任务就是对应的机制。
## 简要概述
- 定时任务运行在 **Gateway 内部**（而非模型内部）。
- 任务持久化存储在 `~/.openclaw/cron/` 下，因此重启不会丢失计划。
- 两种执行方式：
- **主会话**：入队一个系统事件，然后在下一次心跳时运行。
- **隔离式**：在 `cron:<jobId>` 中运行专用智能体轮次，可选择投递输出。
- 唤醒是一等功能：任务可以请求"立即唤醒"或"下次心跳时"。
## 快速开始（可操作）
创建一个一次性提醒，验证其存在，然后立即运行：
```bash
openclaw cron add \
--name "Reminder" \
--at "2026-02-01T16:00:00Z" \
--session main \
--system-event "Reminder: check the cron docs draft" \
--wake now \
--delete-after-run
openclaw cron list
openclaw cron run <job-id> --force
openclaw cron runs --id <job-id>
```
调度一个带投递功能的周期性隔离任务：
```bash
openclaw cron add \
--name "Morning brief" \
--cron "0 7 * * *" \
--tz "America/Los_Angeles" \
--session isolated \
--message "Summarize overnight updates." \
--deliver \
--channel slack \
--to "channel:C1234567890"
```
## 工具调用等价形式（Gateway 定时任务工具）
有关规范的 JSON 结构和示例，请参阅[工具调用的 JSON 模式](/automation/cron-jobs#json-schema-for-tool-calls)。
## 定时任务的存储位置
定时任务默认持久化存储在 Gateway 主机的 `~/.openclaw/cron/jobs.json` 中。Gateway 将文件加载到内存中，并在更改时写回，因此仅在 Gateway 停止时手动编辑才是安全的。请优先使用 `openclaw cron add/edit` 或定时任务工具调用 API 进行更改。
## 新手友好概述
将定时任务理解为：**何时**运行 + **做什么**。
1. **选择调度计划**
- 一次性提醒 → `schedule.kind = "at"`（CLI：`--at`）
- 重复任务 → `schedule.kind = "every"` 或 `schedule.kind = "cron"`
- 如果你的 ISO 时间戳省略了时区，将被视为 **UTC**。
2. **选择运行位置**
- `sessionTarget: "main"` → 在下一次心跳时使用主会话上下文运行。
- `sessionTarget: "isolated"` → 在 `cron:<jobId>` 中运行专用智能体轮次。
3. **选择负载**
- 主会话 → `payload.kind = "systemEvent"`
- 隔离会话 → `payload.kind = "agentTurn"`
可选：`deleteAfterRun: true` 会在一次性任务成功运行后将其从存储中删除。
## 概念
### 任务
定时任务是一条存储记录，包含：
- 一个**调度计划**（何时运行），
- 一个**负载**（做什么），
- 可选的**投递**（输出发送到哪里）。
- 可选的**智能体绑定**（`agentId`）：在指定智能体下运行任务；如果缺失或未知，Gateway 会回退到默认智能体。
任务通过稳定的 `jobId` 标识（用于 CLI/Gateway API）。
在智能体工具调用中，`jobId` 是规范字段；旧版 `id` 仍可兼容使用。
任务可以通过 `deleteAfterRun: true` 在一次性任务成功运行后自动删除。
### 调度计划
定时任务支持三种调度类型：
- `at`：一次性时间戳（自纪元起的毫秒数）。Gateway 接受 ISO 8601 格式并转换为 UTC。
- `every`：固定间隔（毫秒）。
- `cron`：5 字段 cron 表达式，可选 IANA 时区。
Cron 表达式使用 `croner`。如果省略时区，将使用 Gateway 主机的本地时区。
### 主会话与隔离式执行
#### 主会话任务（系统事件）
主会话任务入队一个系统事件，并可选择唤醒心跳运行器。它们必须使用 `payload.kind = "systemEvent"`。
- `wakeMode: "next-heartbeat"`（默认）：事件等待下一次计划心跳。
- `wakeMode: "now"`：事件触发立即心跳运行。
当你需要正常的心跳提示 + 主会话上下文时，这是最佳选择。参见[心跳](/gateway/heartbeat)。
#### 隔离任务（专用定时会话）
隔离任务在会话 `cron:<jobId>` 中运行专用智能体轮次。
关键行为：
- 提示以 `[cron:<jobId> <任务名称>]` 为前缀，便于追踪。
- 每次运行都会启动一个**全新的会话 ID**（不继承之前的对话）。
- 摘要会发布到主会话（前缀 `Cron`，可配置）。
- `wakeMode: "now"` 在发布摘要后触发立即心跳。
- 如果 `payload.deliver: true`，输出会投递到渠道；否则保留在内部。
对于嘈杂、频繁或"后台杂务"类任务，使用隔离任务可以避免污染你的主聊天记录。
### 负载结构（运行内容）
支持两种负载类型：
- `systemEvent`：仅限主会话，通过心跳提示路由。
- `agentTurn`：仅限隔离会话，运行专用智能体轮次。
常用 `agentTurn` 字段：
- `message`：必填文本提示。
- `model` / `thinking`：可选覆盖（见下文）。
- `timeoutSeconds`：可选超时覆盖。
- `deliver`：设为 `true` 以将输出发送到渠道目标。
- `channel`：`last` 或特定渠道。
- `to`：渠道特定目标（电话/聊天/频道 ID）。
- `bestEffortDeliver`：投递失败时避免任务失败。
隔离选项（仅适用于 `session=isolated`）：
- `postToMainPrefix`（CLI：`--post-prefix`）：主会话中系统事件的前缀。
- `postToMainMode`：`summary`（默认）或 `full`。
- `postToMainMaxChars`：当 `postToMainMode=full` 时的最大字符数（默认 8000）。
### 模型和思维覆盖
隔离任务（`agentTurn`）可以覆盖模型和思维级别：
- `model`：提供商/模型字符串（例如 `anthropic/claude-sonnet-4-20250514`）或别名（例如 `opus`）
- `thinking`：思维级别（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`；仅限 GPT-5.2 + Codex 模型）
注意：你也可以在主会话任务上设置 `model`，但这会更改共享的主会话模型。我们建议仅对隔离任务使用模型覆盖，以避免意外的上下文切换。
优先级解析顺序：
1. 任务负载覆盖（最高优先级）
2. 钩子特定默认值（例如 `hooks.gmail.model`）
3. 智能体配置默认值
### 投递（渠道 + 目标）
隔离任务可以将输出投递到渠道。任务负载可以指定：
- `channel`：`whatsapp` / `telegram` / `discord` / `slack` / `mattermost`（插件）/ `signal` / `imessage` / `last`
- `to`：渠道特定的接收目标
如果省略 `channel` 或 `to`，定时任务可以回退到主会话的"最后路由"（智能体最后回复的位置）。
投递说明：
- 如果设置了 `to`，即使省略 `deliver`，定时任务也会自动投递智能体的最终输出。
- 当你需要最后路由投递但不指定明确 `to` 时，使用 `deliver: true`。
- 使用 `deliver: false` 即使存在 `to` 也保持输出为内部使用。
目标格式提醒：
- Slack/Discord/Mattermost（插件）目标应使用明确前缀（例如 `channel:<id>`、`user:<id>`）以避免歧义。
- Telegram 主题应使用 `:topic:` 格式（见下文）。
#### Telegram 投递目标（主题/论坛帖子）
Telegram 通过 `message_thread_id` 支持论坛主题。对于定时任务投递，你可以将主题/帖子编码到 `to` 字段中：
- `-1001234567890`（仅聊天 ID）
- `-1001234567890:topic:123`（推荐：明确的主题标记）
- `-1001234567890:123`（简写：数字后缀）
带前缀的目标如 `telegram:...` / `telegram:group:...` 也可接受：
- `telegram:group:-1001234567890:topic:123`
## 工具调用的 JSON 模式
直接调用 Gateway `cron.*` 工具（智能体工具调用或 RPC）时使用这些结构。CLI 标志接受人类可读的时间格式如 `20m`，但工具调用对 `atMs` 和 `everyMs` 使用纪元毫秒数（`at` 时间接受 ISO 时间戳）。
### cron.add 参数
一次性主会话任务（系统事件）：
```json
{
"name": "Reminder",
"schedule": { "kind": "at", "atMs": 1738262400000 },
"sessionTarget": "main",
"wakeMode": "now",
"payload": { "kind": "systemEvent", "text": "Reminder text" },
"deleteAfterRun": true
}
```
带投递的周期性隔离任务：
```json
{
"name": "Morning brief",
"schedule": { "kind": "cron", "expr": "0 7 * * *", "tz": "America/Los_Angeles" },
"sessionTarget": "isolated",
"wakeMode": "next-heartbeat",
"payload": {
"kind": "agentTurn",
"message": "Summarize overnight updates.",
"deliver": true,
"channel": "slack",
"to": "channel:C1234567890",
"bestEffortDeliver": true
},
"isolation": { "postToMainPrefix": "Cron", "postToMainMode": "summary" }
}
```
说明：
- `schedule.kind`：`at`（`atMs`）、`every`（`everyMs`）或 `cron`（`expr`，可选 `tz`）。
- `atMs` 和 `everyMs` 为纪元毫秒数。
- `sessionTarget` 必须为 `"main"` 或 `"isolated"`，且必须与 `payload.kind` 匹配。
- 可选字段：`agentId`、`description`、`enabled`、`deleteAfterRun`、`isolation`。
- `wakeMode` 省略时默认为 `"next-heartbeat"`。
### cron.update 参数
```json
{
"jobId": "job-123",
"patch": {
"enabled": false,
"schedule": { "kind": "every", "everyMs": 3600000 }
}
}
```
说明：
- `jobId` 是规范字段；`id` 可兼容使用。
- 在补丁中使用 `agentId: null` 可清除智能体绑定。
### cron.run 和 cron.remove 参数
```json
{ "jobId": "job-123", "mode": "force" }
```
```json
{ "jobId": "job-123" }
```
## 存储与历史
- 任务存储：`~/.openclaw/cron/jobs.json`（Gateway 管理的 JSON）。
- 运行历史：`~/.openclaw/cron/runs/<jobId>.jsonl`（JSONL，自动清理）。
- 覆盖存储路径：配置中的 `cron.store`。
## 配置
```json5
{
cron: {
enabled: true, // 默认 true
store: "~/.openclaw/cron/jobs.json",
maxConcurrentRuns: 1, // 默认 1
},
}
```
完全禁用定时任务：
- `cron.enabled: false`（配置）
- `OPENCLAW_SKIP_CRON=1`（环境变量）
## CLI 快速开始
一次性提醒（UTC ISO，成功后自动删除）：
```bash
openclaw cron add \
--name "Send reminder" \
--at "2026-01-12T18:00:00Z" \
--session main \
--system-event "Reminder: submit expense report." \
--wake now \
--delete-after-run
```
一次性提醒（主会话，立即唤醒）：
```bash
openclaw cron add \
--name "Calendar check" \
--at "20m" \
--session main \
--system-event "Next heartbeat: check calendar." \
--wake now
```
周期性隔离任务（投递到 WhatsApp）：
```bash
openclaw cron add \
--name "Morning status" \
--cron "0 7 * * *" \
--tz "America/Los_Angeles" \
--session isolated \
--message "Summarize inbox + calendar for today." \
--deliver \
--channel whatsapp \
--to "+15551234567"
```
周期性隔离任务（投递到 Telegram 主题）：
```bash
openclaw cron add \
--name "Nightly summary (topic)" \
--cron "0 22 * * *" \
--tz "America/Los_Angeles" \
--session isolated \
--message "Summarize today; send to the nightly topic." \
--deliver \
--channel telegram \
--to "-1001234567890:topic:123"
```
带模型和思维覆盖的隔离任务：
```bash
openclaw cron add \
--name "Deep analysis" \
--cron "0 6 * * 1" \
--tz "America/Los_Angeles" \
--session isolated \
--message "Weekly deep analysis of project progress." \
--model "opus" \
--thinking high \
--deliver \
--channel whatsapp \
--to "+15551234567"
```
智能体选择（多智能体配置）：
```bash
# 将任务绑定到智能体 "ops"（如果该智能体不存在则回退到默认智能体）
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
# 切换或清除现有任务的智能体
openclaw cron edit <jobId> --agent ops
openclaw cron edit <jobId> --clear-agent
```
手动运行（调试）：
```bash
openclaw cron run <jobId> --force
```
编辑现有任务（补丁字段）：
```bash
openclaw cron edit <jobId> \
--message "Updated prompt" \
--model "opus" \
--thinking low
```
运行历史：
```bash
openclaw cron runs --id <jobId> --limit 50
```
不创建任务直接发送系统事件：
```bash
openclaw system event --mode now --text "Next heartbeat: check battery."
```
## Gateway API 接口
- `cron.list`、`cron.status`、`cron.add`、`cron.update`、`cron.remove`
- `cron.run`（强制或到期）、`cron.runs`
如需不创建任务直接发送系统事件，请使用 [`openclaw system event`](/cli/system)。
## 故障排除
### "没有任何任务运行"
- 检查定时任务是否已启用：`cron.enabled` 和 `OPENCLAW_SKIP_CRON`。
- 检查 Gateway 是否持续运行（定时任务运行在 Gateway 进程内部）。
- 对于 `cron` 调度：确认时区（`--tz`）与主机时区的关系。
### Telegram 投递到了错误的位置
- 对于论坛主题，使用 `-100…:topic:<id>` 以确保明确无歧义。
- 如果你在日志或存储的"最后路由"目标中看到 `telegram:...` 前缀，这是正常的；定时任务投递接受这些前缀并仍能正确解析主题 ID。

286
docs/zh-CN/automation/cron-vs-heartbeat.md Normal file
View File

@@ -0,0 +1,286 @@
---
read_when:
- 决定如何调度周期性任务
- 设置后台监控或通知
- 优化定期检查的 token 用量
summary: 选择心跳还是定时任务进行自动化的指南
title: 定时任务与心跳对比
x-i18n:
generated_at: "2026-02-01T19:38:18Z"
model: claude-opus-4-5
provider: pi
source_hash: 5f71a63181baa41b1c307eb7bfac561df7943d4627077dfa2861eb9f76ab086b
source_path: automation/cron-vs-heartbeat.md
workflow: 14
---
# 定时任务与心跳：何时使用哪种方式
心跳和定时任务都可以按计划运行任务。本指南帮助你根据使用场景选择合适的机制。
## 快速决策指南
| 使用场景 | 推荐方式 | 原因 |
| ------------------------- | -------------------------- | ---------------------------------------- |
| 每 30 分钟检查收件箱 | 心跳 | 可与其他检查批量处理，具备上下文感知能力 |
| 每天上午 9 点准时发送报告 | 定时任务（隔离式） | 需要精确定时 |
| 监控日历中即将到来的事件 | 心跳 | 天然适合周期性感知 |
| 运行每周深度分析 | 定时任务（隔离式） | 独立任务，可使用不同模型 |
| 20 分钟后提醒我 | 定时任务（主会话，`--at`） | 精确定时的一次性任务 |
| 后台项目健康检查 | 心跳 | 搭载在现有周期上 |
## 心跳：周期性感知
心跳在**主会话**中以固定间隔运行（默认：30 分钟）。它的设计目的是让智能体检查各种事项并呈现重要信息。
### 何时使用心跳
- **多个周期性检查**：与其设置 5 个独立的定时任务分别检查收件箱、日历、天气、通知和项目状态，不如用一次心跳批量处理所有内容。
- **上下文感知决策**：智能体拥有完整的主会话上下文，因此可以智能判断哪些紧急、哪些可以等待。
- **对话连续性**：心跳运行共享同一会话，因此智能体记得最近的对话，可以自然地进行后续跟进。
- **低开销监控**：一次心跳替代多个小型轮询任务。
### 心跳优势
- **批量处理多项检查**：一次智能体轮次可以同时审查收件箱、日历和通知。
- **减少 API 调用**：一次心跳比 5 个隔离式定时任务更经济。
- **上下文感知**：智能体了解你一直在做什么，可以据此排定优先级。
- **智能抑制**：如果没有需要关注的事项，智能体回复 `HEARTBEAT_OK`，不会投递任何消息。
- **自然定时**：会根据队列负载略有漂移，但对大多数监控来说没有问题。
### 心跳示例：HEARTBEAT.md 检查清单
```md
# Heartbeat checklist
- Check email for urgent messages
- Review calendar for events in next 2 hours
- If a background task finished, summarize results
- If idle for 8+ hours, send a brief check-in
```
智能体在每次心跳时读取此清单，并在一次轮次中处理所有项目。
### 配置心跳
```json5
{
agents: {
defaults: {
heartbeat: {
every: "30m", // 间隔
target: "last", // 告警投递目标
activeHours: { start: "08:00", end: "22:00" }, // 可选
},
},
},
}
```
完整配置请参阅[心跳](/gateway/heartbeat)。
## 定时任务：精确调度
定时任务在**精确时间**运行，可以在隔离会话中运行而不影响主会话上下文。
### 何时使用定时任务
- **需要精确定时**："每周一上午 9:00 发送"（而不是"大约 9 点左右"）。
- **独立任务**：不需要对话上下文的任务。
- **不同的模型/思维级别**：需要更强大模型的深度分析。
- **一次性提醒**：使用 `--at` 实现"20 分钟后提醒我"。
- **嘈杂/频繁的任务**：会把主会话历史搞得杂乱的任务。
- **外部触发器**：无论智能体是否处于活跃状态都应独立运行的任务。
### 定时任务优势
- **精确定时**：支持带时区的 5 字段 cron 表达式。
- **会话隔离**：在 `cron:<jobId>` 中运行，不会污染主会话历史。
- **模型覆盖**：可按任务使用更便宜或更强大的模型。
- **投递控制**：可直接投递到渠道；默认仍会向主会话发布摘要（可配置）。
- **无需智能体上下文**：即使主会话空闲或已压缩，也能运行。
- **一次性支持**：`--at` 用于精确的未来时间戳。
### 定时任务示例：每日早间简报
```bash
openclaw cron add \
--name "Morning briefing" \
--cron "0 7 * * *" \
--tz "America/New_York" \
--session isolated \
--message "Generate today's briefing: weather, calendar, top emails, news summary." \
--model opus \
--deliver \
--channel whatsapp \
--to "+15551234567"
```
这会在纽约时间每天早上 7:00 准时运行，使用 Opus 保证质量，并直接投递到 WhatsApp。
### 定时任务示例：一次性提醒
```bash
openclaw cron add \
--name "Meeting reminder" \
--at "20m" \
--session main \
--system-event "Reminder: standup meeting starts in 10 minutes." \
--wake now \
--delete-after-run
```
完整 CLI 参考请参阅[定时任务](/automation/cron-jobs)。
## 决策流程图
```
任务是否需要在精确时间运行？
是 -> 使用定时任务
否 -> 继续...
任务是否需要与主会话隔离？
是 -> 使用定时任务（隔离式）
否 -> 继续...
此任务能否与其他周期性检查批量处理？
是 -> 使用心跳（添加到 HEARTBEAT.md）
否 -> 使用定时任务
这是一次性提醒吗？
是 -> 使用定时任务配合 --at
否 -> 继续...
是否需要不同的模型或思维级别？
是 -> 使用定时任务（隔离式）配合 --model/--thinking
否 -> 使用心跳
```
## 组合使用
最高效的配置是**两者结合**：
1. **心跳**处理常规监控（收件箱、日历、通知），每 30 分钟批量处理一次。
2. **定时任务**处理精确调度（每日报告、每周回顾）和一次性提醒。
### 示例：高效自动化配置
**HEARTBEAT.md**（每 30 分钟检查一次）：
```md
# Heartbeat checklist
- Scan inbox for urgent emails
- Check calendar for events in next 2h
- Review any pending tasks
- Light check-in if quiet for 8+ hours
```
**定时任务**（精确定时）：
```bash
# 每天早上 7 点的早间简报
openclaw cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --deliver
# 每周一上午 9 点的项目回顾
openclaw cron add --name "Weekly review" --cron "0 9 * * 1" --session isolated --message "..." --model opus
# 一次性提醒
openclaw cron add --name "Call back" --at "2h" --session main --system-event "Call back the client" --wake now
```
## Lobster：带审批的确定性工作流
Lobster 是用于**多步骤工具管道**的工作流运行时，适用于需要确定性执行和明确审批的场景。当任务不只是单次智能体轮次，且你需要可恢复的带人工检查点的工作流时，使用它。
### 何时适合使用 Lobster
- **多步骤自动化**：你需要一个固定的工具调用管道，而不是一次性提示。
- **审批关卡**：副作用应暂停直到你批准，然后继续执行。
- **可恢复运行**：继续暂停的工作流而无需重新运行之前的步骤。
### 如何与心跳和定时任务配合
- **心跳/定时任务**决定*何时*运行。
- **Lobster** 定义运行开始后*执行哪些步骤*。
对于计划性工作流，使用定时任务或心跳触发一次调用 Lobster 的智能体轮次。对于临时工作流，直接调用 Lobster。
### 操作说明（来自代码）
- Lobster 以**本地子进程**（`lobster` CLI）在工具模式下运行，并返回 **JSON 信封**。
- 如果工具返回 `needs_approval`，你需要使用 `resumeToken` 和 `approve` 标志来恢复。
- 该工具是**可选插件**；建议通过 `tools.alsoAllow: ["lobster"]` 附加启用。
- 如果传入 `lobsterPath`，必须是**绝对路径**。
完整用法和示例请参阅 [Lobster](/tools/lobster)。
## 主会话与隔离会话
心跳和定时任务都可以与主会话交互，但方式不同：
| | 心跳 | 定时任务（主会话） | 定时任务（隔离式） |
| ------ | ------------------------ | ---------------------- | ------------------ |
| 会话 | 主会话 | 主会话（通过系统事件） | `cron:<jobId>` |
| 历史 | 共享 | 共享 | 每次运行全新 |
| 上下文 | 完整 | 完整 | 无（从零开始） |
| 模型 | 主会话模型 | 主会话模型 | 可覆盖 |
| 输出 | 非 `HEARTBEAT_OK` 时投递 | 心跳提示 + 事件 | 摘要发布到主会话 |
### 何时使用主会话定时任务
当你需要以下场景时，使用 `--session main` 配合 `--system-event`：
- 提醒/事件出现在主会话上下文中
- 智能体在下一次心跳时带着完整上下文处理它
- 不需要单独的隔离运行
```bash
openclaw cron add \
--name "Check project" \
--every "4h" \
--session main \
--system-event "Time for a project health check" \
--wake now
```
### 何时使用隔离式定时任务
当你需要以下场景时，使用 `--session isolated`：
- 无先前上下文的全新环境
- 不同的模型或思维设置
- 输出直接投递到渠道（摘要默认仍会发布到主会话）
- 不会把主会话搞得杂乱的历史记录
```bash
openclaw cron add \
--name "Deep analysis" \
--cron "0 6 * * 0" \
--session isolated \
--message "Weekly codebase analysis..." \
--model opus \
--thinking high \
--deliver
```
## 成本考量
| 机制 | 成本特征 |
| ------------------ | ---------------------------------------------- |
| 心跳 | 每 N 分钟一次轮次；随 HEARTBEAT.md 大小扩展 |
| 定时任务（主会话） | 将事件添加到下一次心跳（无隔离轮次） |
| 定时任务（隔离式） | 每个任务一次完整智能体轮次；可使用更便宜的模型 |
**建议**：
- 保持 `HEARTBEAT.md` 精简以减少 token 开销。
- 将类似的检查批量放入心跳，而不是创建多个定时任务。
- 如果只需要内部处理，在心跳上使用 `target: "none"`。
- 对常规任务使用隔离式定时任务配合更便宜的模型。
## 相关内容
- [心跳](/gateway/heartbeat) - 完整的心跳配置
- [定时任务](/automation/cron-jobs) - 完整的定时任务 CLI 和 API 参考
- [系统](/cli/system) - 系统事件 + 心跳控制

249
docs/zh-CN/automation/gmail-pubsub.md Normal file
View File

@@ -0,0 +1,249 @@
---
read_when:
- 将 Gmail 收件箱触发器接入 OpenClaw
- 为智能体唤醒设置 Pub/Sub 推送
summary: 通过 gogcli 将 Gmail Pub/Sub 推送接入 OpenClaw webhooks
title: Gmail PubSub
x-i18n:
generated_at: "2026-02-01T19:38:47Z"
model: claude-opus-4-5
provider: pi
source_hash: dfb92133b69177e4e984b7d072f5dc28aa53a9e0cf984a018145ed811aa96195
source_path: automation/gmail-pubsub.md
workflow: 14
---
# Gmail Pub/Sub -> OpenClaw
目标：Gmail watch -> Pub/Sub 推送 -> `gog gmail watch serve` -> OpenClaw webhook。
## 前置条件
- 已安装并登录 `gcloud`（[安装指南](https://docs.cloud.google.com/sdk/docs/install-sdk)）。
- 已安装 `gog`（gogcli）并已授权 Gmail 账号（[gogcli.sh](https://gogcli.sh/)）。
- 已启用 OpenClaw hooks（参见 [Webhooks](/automation/webhook)）。
- 已登录 `tailscale`（[tailscale.com](https://tailscale.com/)）。支持的配置使用 Tailscale Funnel 作为公共 HTTPS 端点。
其他隧道服务也可以使用，但属于自行配置/不受支持，需要手动接线。
目前我们支持的是 Tailscale。
示例 hook 配置（启用 Gmail 预设映射）：
```json5
{
hooks: {
enabled: true,
token: "OPENCLAW_HOOK_TOKEN",
path: "/hooks",
presets: ["gmail"],
},
}
```
如需将 Gmail 摘要投递到聊天界面，可覆盖预设并设置带 `deliver` 以及可选的 `channel`/`to` 的映射：
```json5
{
hooks: {
enabled: true,
token: "OPENCLAW_HOOK_TOKEN",
presets: ["gmail"],
mappings: [
{
match: { path: "gmail" },
action: "agent",
wakeMode: "now",
name: "Gmail",
sessionKey: "hook:gmail:{{messages[0].id}}",
messageTemplate: "New email from {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}\n{{messages[0].body}}",
model: "openai/gpt-5.2-mini",
deliver: true,
channel: "last",
// to: "+15551234567"
},
],
},
}
```
如果你想要固定渠道，请设置 `channel` + `to`。否则 `channel: "last"` 会使用最后的投递路由（回退到 WhatsApp）。
如需为 Gmail 运行强制使用更便宜的模型，在映射中设置 `model`（`provider/model` 或别名）。如果你设置了 `agents.defaults.models`，请将其包含在允许列表中。
如需专门为 Gmail hooks 设置默认模型和思维级别，在配置中添加 `hooks.gmail.model` / `hooks.gmail.thinking`：
```json5
{
hooks: {
gmail: {
model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
thinking: "off",
},
},
}
```
说明：
- 映射中每个 hook 的 `model`/`thinking` 仍会覆盖这些默认值。
- 回退顺序：`hooks.gmail.model` → `agents.defaults.model.fallbacks` → 主模型（认证/速率限制/超时）。
- 如果设置了 `agents.defaults.models`，Gmail 模型必须在允许列表中。
- Gmail hook 内容默认使用外部内容安全边界进行包装。
如需禁用（危险），请设置 `hooks.gmail.allowUnsafeExternalContent: true`。
如需进一步自定义负载处理，可添加 `hooks.mappings` 或在 `hooks.transformsDir` 下添加 JS/TS 转换模块（参见 [Webhooks](/automation/webhook)）。
## 向导（推荐）
使用 OpenClaw 辅助工具一键完成所有配置（在 macOS 上通过 brew 安装依赖）：
```bash
openclaw webhooks gmail setup \
--account openclaw@gmail.com
```
默认配置：
- 使用 Tailscale Funnel 作为公共推送端点。
- 为 `openclaw webhooks gmail run` 写入 `hooks.gmail` 配置。
- 启用 Gmail hook 预设（`hooks.presets: ["gmail"]`）。
路径说明：当启用 `tailscale.mode` 时，OpenClaw 会自动将 `hooks.gmail.serve.path` 设置为 `/`，并将公共路径保持在 `hooks.gmail.tailscale.path`（默认 `/gmail-pubsub`），因为 Tailscale 在代理前会去除设置的路径前缀。
如果你需要后端接收带前缀的路径，请将 `hooks.gmail.tailscale.target`（或 `--tailscale-target`）设置为完整 URL，例如 `http://127.0.0.1:8788/gmail-pubsub`，并匹配 `hooks.gmail.serve.path`。
需要自定义端点？使用 `--push-endpoint <url>` 或 `--tailscale off`。
平台说明：在 macOS 上，向导通过 Homebrew 安装 `gcloud`、`gogcli` 和 `tailscale`；在 Linux 上请先手动安装它们。
Gateway 自动启动（推荐）：
- 当 `hooks.enabled=true` 且设置了 `hooks.gmail.account` 时，Gateway 会在启动时运行 `gog gmail watch serve` 并自动续期 watch。
- 设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可退出自动启动（如果你自行运行守护进程则很有用）。
- 不要同时运行手动守护进程，否则会遇到 `listen tcp 127.0.0.1:8788: bind: address already in use`。
手动守护进程（启动 `gog gmail watch serve` + 自动续期）：
```bash
openclaw webhooks gmail run
```
## 一次性设置
1. 选择**拥有 `gog` 使用的 OAuth 客户端**的 GCP 项目。
```bash
gcloud auth login
gcloud config set project <project-id>
```
注意：Gmail watch 要求 Pub/Sub 主题位于与 OAuth 客户端相同的项目中。
2. 启用 API：
```bash
gcloud services enable gmail.googleapis.com pubsub.googleapis.com
```
3. 创建主题：
```bash
gcloud pubsub topics create gog-gmail-watch
```
4. 允许 Gmail 推送发布：
```bash
gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
--member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
--role=roles/pubsub.publisher
```
## 启动 watch
```bash
gog gmail watch start \
--account openclaw@gmail.com \
--label INBOX \
--topic projects/<project-id>/topics/gog-gmail-watch
```
保存输出中的 `history_id`（用于调试）。
## 运行推送处理器
本地示例（共享令牌认证）：
```bash
gog gmail watch serve \
--account openclaw@gmail.com \
--bind 127.0.0.1 \
--port 8788 \
--path /gmail-pubsub \
--token <shared> \
--hook-url http://127.0.0.1:18789/hooks/gmail \
--hook-token OPENCLAW_HOOK_TOKEN \
--include-body \
--max-bytes 20000
```
说明：
- `--token` 保护推送端点（`x-gog-token` 或 `?token=`）。
- `--hook-url` 指向 OpenClaw `/hooks/gmail`（已映射；隔离运行 + 摘要发送到主会话）。
- `--include-body` 和 `--max-bytes` 控制发送到 OpenClaw 的正文片段。
推荐：`openclaw webhooks gmail run` 封装了相同的流程并自动续期 watch。
## 暴露处理器（高级，不受支持）
如果你需要非 Tailscale 隧道，请手动接线并在推送订阅中使用公共 URL（不受支持，无保护措施）：
```bash
cloudflared tunnel --url http://127.0.0.1:8788 --no-autoupdate
```
使用生成的 URL 作为推送端点：
```bash
gcloud pubsub subscriptions create gog-gmail-watch-push \
--topic gog-gmail-watch \
--push-endpoint "https://<public-url>/gmail-pubsub?token=<shared>"
```
生产环境：使用稳定的 HTTPS 端点并配置 Pub/Sub OIDC JWT，然后运行：
```bash
gog gmail watch serve --verify-oidc --oidc-email <svc@...>
```
## 测试
向被监控的收件箱发送一封邮件：
```bash
gog gmail send \
--account openclaw@gmail.com \
--to openclaw@gmail.com \
--subject "watch test" \
--body "ping"
```
检查 watch 状态和历史：
```bash
gog gmail watch status --account openclaw@gmail.com
gog gmail history --account openclaw@gmail.com --since <historyId>
```
## 故障排除
- `Invalid topicName`：项目不匹配（主题不在 OAuth 客户端项目中）。
- `User not authorized`：主题缺少 `roles/pubsub.publisher` 权限。
- 空消息：Gmail 推送仅提供 `historyId`；通过 `gog gmail history` 获取详情。
## 清理
```bash
gog gmail watch stop --account openclaw@gmail.com
gcloud pubsub subscriptions delete gog-gmail-watch-push
gcloud pubsub topics delete gog-gmail-watch
```

75
docs/zh-CN/automation/poll.md Normal file
View File

@@ -0,0 +1,75 @@
---
read_when:
- 添加或修改投票支持
- 调试从 CLI 或 Gateway 发送的投票
summary: 通过 Gateway + CLI 发送投票
title: 投票
x-i18n:
generated_at: "2026-02-01T19:38:57Z"
model: claude-opus-4-5
provider: pi
source_hash: 760339865d27ec40def7996cac1d294d58ab580748ad6b32cc34d285d0314eaf
source_path: automation/poll.md
workflow: 14
---
# 投票
## 支持的渠道
- WhatsApp（Web 渠道）
- Discord
- Microsoft Teams（Adaptive Cards）
## CLI
```bash
# WhatsApp
openclaw message poll --target +15555550123 \
--poll-question "Lunch today?" --poll-option "Yes" --poll-option "No" --poll-option "Maybe"
openclaw message poll --target 123456789@g.us \
--poll-question "Meeting time?" --poll-option "10am" --poll-option "2pm" --poll-option "4pm" --poll-multi
# Discord
openclaw message poll --channel discord --target channel:123456789 \
--poll-question "Snack?" --poll-option "Pizza" --poll-option "Sushi"
openclaw message poll --channel discord --target channel:123456789 \
--poll-question "Plan?" --poll-option "A" --poll-option "B" --poll-duration-hours 48
# MS Teams
openclaw message poll --channel msteams --target conversation:19:abc@thread.tacv2 \
--poll-question "Lunch?" --poll-option "Pizza" --poll-option "Sushi"
```
选项：
- `--channel`：`whatsapp`（默认）、`discord` 或 `msteams`
- `--poll-multi`：允许选择多个选项
- `--poll-duration-hours`：仅限 Discord（省略时默认为 24）
## Gateway RPC
方法：`poll`
参数：
- `to`（字符串，必填）
- `question`（字符串，必填）
- `options`（字符串数组，必填）
- `maxSelections`（数字，可选）
- `durationHours`（数字，可选）
- `channel`（字符串，可选，默认：`whatsapp`）
- `idempotencyKey`（字符串，必填）
## 渠道差异
- WhatsApp：2-12 个选项，`maxSelections` 必须在选项数量范围内，忽略 `durationHours`。
- Discord：2-10 个选项，`durationHours` 限制在 1-768 小时（默认 24）。`maxSelections > 1` 启用多选；Discord 不支持严格的选择数量限制。
- Microsoft Teams：Adaptive Card 投票（由 OpenClaw 管理）。没有原生投票 API；`durationHours` 被忽略。
## 智能体工具（Message）
使用 `message` 工具的 `poll` 操作（`to`、`pollQuestion`、`pollOption`，可选 `pollMulti`、`pollDurationHours`、`channel`）。
注意：Discord 没有"精确选择 N 个"模式；`pollMulti` 映射为多选。
Teams 投票以 Adaptive Cards 形式渲染，需要 Gateway 保持在线以在 `~/.openclaw/msteams-polls.json` 中记录投票结果。

163
docs/zh-CN/automation/webhook.md Normal file
View File

@@ -0,0 +1,163 @@
---
read_when:
- 添加或修改 webhook 端点
- 将外部系统接入 OpenClaw
summary: 用于唤醒和隔离式智能体运行的 Webhook 入口
title: Webhooks
x-i18n:
generated_at: "2026-02-01T19:39:20Z"
model: claude-opus-4-5
provider: pi
source_hash: f26b88864567be82366b1f66a4772ef2813c7846110c62fce6caf7313568265e
source_path: automation/webhook.md
workflow: 14
---
# Webhooks
Gateway 可以暴露一个小型 HTTP webhook 端点用于外部触发。
## 启用
```json5
{
hooks: {
enabled: true,
token: "shared-secret",
path: "/hooks",
},
}
```
说明：
- 当 `hooks.enabled=true` 时，`hooks.token` 为必填项。
- `hooks.path` 默认为 `/hooks`。
## 认证
每个请求必须包含 hook 令牌。推荐使用请求头：
- `Authorization: Bearer <token>`（推荐）
- `x-openclaw-token: <token>`
- `?token=<token>`（已弃用；会记录警告，将在未来的主要版本中移除）
## 端点
### `POST /hooks/wake`
请求体：
```json
{ "text": "System line", "mode": "now" }
```
- `text` **必填**（字符串）：事件描述（例如 "New email received"）。
- `mode` 可选（`now` | `next-heartbeat`）：是否触发立即心跳（默认 `now`）或等待下一次周期性检查。
效果：
- 为**主**会话入队一个系统事件
- 如果 `mode=now`，触发立即心跳
### `POST /hooks/agent`
请求体：
```json
{
"message": "Run this",
"name": "Email",
"sessionKey": "hook:email:msg-123",
"wakeMode": "now",
"deliver": true,
"channel": "last",
"to": "+15551234567",
"model": "openai/gpt-5.2-mini",
"thinking": "low",
"timeoutSeconds": 120
}
```
- `message` **必填**（字符串）：智能体处理的提示或消息。
- `name` 可选（字符串）：hook 的人类可读名称（例如 "GitHub"），用作会话摘要的前缀。
- `sessionKey` 可选（字符串）：用于标识智能体会话的键。默认为随机的 `hook:<uuid>`。使用一致的键可以在 hook 上下文中进行多轮对话。
- `wakeMode` 可选（`now` | `next-heartbeat`）：是否触发立即心跳（默认 `now`）或等待下一次周期性检查。
- `deliver` 可选（布尔值）：如果为 `true`，智能体的回复将发送到消息渠道。默认为 `true`。仅为心跳确认的回复会被自动跳过。
- `channel` 可选（字符串）：投递的消息渠道。可选值：`last`、`whatsapp`、`telegram`、`discord`、`slack`、`mattermost`（插件）、`signal`、`imessage`、`msteams`。默认为 `last`。
- `to` 可选（字符串）：渠道的接收方标识符（例如 WhatsApp/Signal 的电话号码、Telegram 的聊天 ID、Discord/Slack/Mattermost（插件）的频道 ID、Microsoft Teams 的会话 ID）。默认为主会话中的最后一个接收方。
- `model` 可选（字符串）：模型覆盖（例如 `anthropic/claude-3-5-sonnet` 或别名）。如果有模型限制，必须在允许的模型列表中。
- `thinking` 可选（字符串）：思维级别覆盖（例如 `low`、`medium`、`high`）。
- `timeoutSeconds` 可选（数字）：智能体运行的最大持续时间（秒）。
效果：
- 运行一次**隔离式**智能体轮次（使用独立的会话键）
- 始终将摘要发布到**主**会话
- 如果 `wakeMode=now`，触发立即心跳
### `POST /hooks/<name>`（映射）
自定义 hook 名称通过 `hooks.mappings` 解析（参见配置）。映射可以将任意请求体转换为 `wake` 或 `agent` 操作，并支持可选的模板或代码转换。
映射选项（概要）：
- `hooks.presets: ["gmail"]` 启用内置的 Gmail 映射。
- `hooks.mappings` 允许你在配置中定义 `match`、`action` 和模板。
- `hooks.transformsDir` + `transform.module` 加载 JS/TS 模块以实现自定义逻辑。
- 使用 `match.source` 保持通用的接收端点（基于请求体的路由）。
- TS 转换需要 TS 加载器（例如 `bun` 或 `tsx`）或运行时预编译的 `.js`。
- 在映射上设置 `deliver: true` + `channel`/`to` 可将回复路由到聊天界面（`channel` 默认为 `last`，回退到 WhatsApp）。
- `allowUnsafeExternalContent: true` 为该 hook 禁用外部内容安全包装（危险；仅限受信任的内部来源）。
- `openclaw webhooks gmail setup` 为 `openclaw webhooks gmail run` 写入 `hooks.gmail` 配置。完整的 Gmail watch 流程请参阅 [Gmail Pub/Sub](/automation/gmail-pubsub)。
## 响应
- `200` 用于 `/hooks/wake`
- `202` 用于 `/hooks/agent`（异步运行已启动）
- `401` 认证失败
- `400` 无效请求体
- `413` 请求体过大
## 示例
```bash
curl -X POST http://127.0.0.1:18789/hooks/wake \
-H 'Authorization: Bearer SECRET' \
-H 'Content-Type: application/json' \
-d '{"text":"New email received","mode":"now"}'
```
```bash
curl -X POST http://127.0.0.1:18789/hooks/agent \
-H 'x-openclaw-token: SECRET' \
-H 'Content-Type: application/json' \
-d '{"message":"Summarize inbox","name":"Email","wakeMode":"next-heartbeat"}'
```
### 使用不同的模型
在 agent 请求体（或映射）中添加 `model` 以覆盖该次运行的模型：
```bash
curl -X POST http://127.0.0.1:18789/hooks/agent \
-H 'x-openclaw-token: SECRET' \
-H 'Content-Type: application/json' \
-d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.2-mini"}'
```
如果你设置了 `agents.defaults.models`，请确保覆盖的模型包含在其中。
```bash
curl -X POST http://127.0.0.1:18789/hooks/gmail \
-H 'Authorization: Bearer SECRET' \
-H 'Content-Type: application/json' \
-d '{"source":"gmail","messages":[{"from":"Ada","subject":"Hello","snippet":"Hi"}]}'
```
## 安全
- 将 hook 端点限制在回环地址、tailnet 或受信任的反向代理之后。
- 使用专用的 hook 令牌；不要复用 Gateway 认证令牌。
- 避免在 webhook 日志中包含敏感的原始请求体。
- Hook 请求体默认被视为不受信任的，并使用安全边界进行包装。如果你必须为特定 hook 禁用此功能，请在该 hook 的映射中设置 `allowUnsafeExternalContent: true`（危险）。

170
docs/zh-CN/bedrock.md Normal file
View File

@@ -0,0 +1,170 @@
---
read_when:
- 你想在 OpenClaw 中使用 Amazon Bedrock 模型
- 你需要为模型调用设置 AWS 凭证/区域
summary: 在 OpenClaw 中使用 Amazon Bedrock（Converse API）模型
title: Amazon Bedrock
x-i18n:
generated_at: "2026-02-01T19:39:40Z"
model: claude-opus-4-5
provider: pi
source_hash: 318f1048451a1910b70522e2f7f9dfc87084de26d9e3938a29d372eed32244a8
source_path: bedrock.md
workflow: 14
---
# Amazon Bedrock
OpenClaw 可以通过 pi‑ai 的 **Bedrock Converse** 流式提供商使用 **Amazon Bedrock** 模型。Bedrock 认证使用 **AWS SDK 默认凭证链**，而非 API 密钥。
## pi‑ai 支持的内容
- 提供商：`amazon-bedrock`
- API：`bedrock-converse-stream`
- 认证：AWS 凭证（环境变量、共享配置或实例角色）
- 区域：`AWS_REGION` 或 `AWS_DEFAULT_REGION`（默认：`us-east-1`）
## 自动模型发现
如果检测到 AWS 凭证，OpenClaw 可以自动发现支持**流式传输**和**文本输出**的 Bedrock 模型。发现功能使用 `bedrock:ListFoundationModels`，并带有缓存（默认：1 小时）。
配置选项位于 `models.bedrockDiscovery` 下：
```json5
{
models: {
bedrockDiscovery: {
enabled: true,
region: "us-east-1",
providerFilter: ["anthropic", "amazon"],
refreshInterval: 3600,
defaultContextWindow: 32000,
defaultMaxTokens: 4096,
},
},
}
```
说明：
- 当 AWS 凭证存在时，`enabled` 默认为 `true`。
- `region` 默认为 `AWS_REGION` 或 `AWS_DEFAULT_REGION`，然后是 `us-east-1`。
- `providerFilter` 匹配 Bedrock 提供商名称（例如 `anthropic`）。
- `refreshInterval` 单位为秒；设置为 `0` 可禁用缓存。
- `defaultContextWindow`（默认：`32000`）和 `defaultMaxTokens`（默认：`4096`）用于发现的模型（如果你了解模型限制可以覆盖）。
## 设置（手动）
1. 确保 AWS 凭证在 **Gateway 主机**上可用：
```bash
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"
# 可选：
export AWS_SESSION_TOKEN="..."
export AWS_PROFILE="your-profile"
# 可选（Bedrock API 密钥/Bearer 令牌）：
export AWS_BEARER_TOKEN_BEDROCK="..."
```
2. 在配置中添加 Bedrock 提供商和模型（无需 `apiKey`）：
```json5
{
models: {
providers: {
"amazon-bedrock": {
baseUrl: "https://bedrock-runtime.us-east-1.amazonaws.com",
api: "bedrock-converse-stream",
auth: "aws-sdk",
models: [
{
id: "anthropic.claude-opus-4-5-20251101-v1:0",
name: "Claude Opus 4.5 (Bedrock)",
reasoning: true,
input: ["text", "image"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 200000,
maxTokens: 8192,
},
],
},
},
},
agents: {
defaults: {
model: { primary: "amazon-bedrock/anthropic.claude-opus-4-5-20251101-v1:0" },
},
},
}
```
## EC2 实例角色
在附加了 IAM 角色的 EC2 实例上运行 OpenClaw 时，AWS SDK 会自动使用实例元数据服务（IMDS）进行认证。但是，OpenClaw 的凭证检测目前仅检查环境变量，不检查 IMDS 凭证。
**解决方法：** 设置 `AWS_PROFILE=default` 以表明 AWS 凭证可用。实际认证仍通过 IMDS 使用实例角色。
```bash
# 添加到 ~/.bashrc 或你的 shell 配置文件
export AWS_PROFILE=default
export AWS_REGION=us-east-1
```
EC2 实例角色**所需的 IAM 权限**：
- `bedrock:InvokeModel`
- `bedrock:InvokeModelWithResponseStream`
- `bedrock:ListFoundationModels`（用于自动发现）
或附加托管策略 `AmazonBedrockFullAccess`。
**快速设置：**
```bash
# 1. 创建 IAM 角色和实例配置文件
aws iam create-role --role-name EC2-Bedrock-Access \
--assume-role-policy-document '{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {"Service": "ec2.amazonaws.com"},
"Action": "sts:AssumeRole"
}]
}'
aws iam attach-role-policy --role-name EC2-Bedrock-Access \
--policy-arn arn:aws:iam::aws:policy/AmazonBedrockFullAccess
aws iam create-instance-profile --instance-profile-name EC2-Bedrock-Access
aws iam add-role-to-instance-profile \
--instance-profile-name EC2-Bedrock-Access \
--role-name EC2-Bedrock-Access
# 2. 附加到你的 EC2 实例
aws ec2 associate-iam-instance-profile \
--instance-id i-xxxxx \
--iam-instance-profile Name=EC2-Bedrock-Access
# 3. 在 EC2 实例上启用发现
openclaw config set models.bedrockDiscovery.enabled true
openclaw config set models.bedrockDiscovery.region us-east-1
# 4. 设置解决方法的环境变量
echo 'export AWS_PROFILE=default' >> ~/.bashrc
echo 'export AWS_REGION=us-east-1' >> ~/.bashrc
source ~/.bashrc
# 5. 验证模型已被发现
openclaw models list
```
## 说明
- Bedrock 需要在你的 AWS 账户/区域中启用**模型访问**。
- 自动发现需要 `bedrock:ListFoundationModels` 权限。
- 如果你使用配置文件，请在 Gateway 主机上设置 `AWS_PROFILE`。
- OpenClaw 按以下顺序检测凭证来源：`AWS_BEARER_TOKEN_BEDROCK`，然后 `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`，然后 `AWS_PROFILE`，最后是默认的 AWS SDK 链。
- 推理支持取决于模型；请查看 Bedrock 模型卡了解当前功能。
- 如果你偏好托管密钥流程，也可以在 Bedrock 前面放置一个兼容 OpenAI 的代理，将其配置为 OpenAI 提供商。

48
docs/zh-CN/brave-search.md Normal file
View File

@@ -0,0 +1,48 @@
---
read_when:
- 你想使用 Brave Search 进行 web_search
- 你需要 BRAVE_API_KEY 或套餐详情
summary: 为 web_search 设置 Brave Search API
title: Brave Search
x-i18n:
generated_at: "2026-02-01T19:39:45Z"
model: claude-opus-4-5
provider: pi
source_hash: cdcb037b092b8a10609f02acf062b4164cb826ac22bdb3fb2909c842a1405341
source_path: brave-search.md
workflow: 14
---
# Brave Search API
OpenClaw 使用 Brave Search 作为 `web_search` 的默认提供商。
## 获取 API 密钥
1. 在 https://brave.com/search/api/ 创建 Brave Search API 账户。
2. 在控制面板中，选择 **Data for Search** 套餐并生成 API 密钥。
3. 将密钥存储在配置中（推荐）或在 Gateway 环境中设置 `BRAVE_API_KEY`。
## 配置示例
```json5
{
tools: {
web: {
search: {
provider: "brave",
apiKey: "BRAVE_API_KEY_HERE",
maxResults: 5,
timeoutSeconds: 30,
},
},
},
}
```
## 说明
- Data for AI 套餐与 `web_search` **不**兼容。
- Brave 提供免费套餐和付费套餐；请查看 Brave API 门户了解当前限制。
完整的 web_search 配置请参阅 [Web 工具](/tools/web)。

449
docs/zh-CN/broadcast-groups.md Normal file
View File

@@ -0,0 +1,449 @@
---
read_when:
- 配置广播群组
- 调试 WhatsApp 中的多智能体回复
status: experimental
summary: 将 WhatsApp 消息广播给多个智能体
title: 广播群组
x-i18n:
generated_at: "2026-02-01T19:40:25Z"
model: claude-opus-4-5
provider: pi
source_hash: eaeb4035912c49413e012177cf0bd28b348130d30d3317674418dca728229b70
source_path: broadcast-groups.md
workflow: 14
---
# 广播群组
**状态：** 实验性
**版本：** 在 2026.1.9 中添加
## 概述
广播群组允许多个智能体同时处理和回复同一条消息。这使你可以创建在单个 WhatsApp 群组或私聊中协同工作的专业智能体团队——全部使用同一个电话号码。
当前范围：**仅限 WhatsApp**（Web 渠道）。
广播群组在渠道允许列表和群组激活规则之后进行评估。在 WhatsApp 群组中，这意味着广播发生在 OpenClaw 正常回复的时机（例如：被提及时，取决于你的群组设置）。
## 使用场景
### 1. 专业智能体团队
部署多个具有原子化、专注职责的智能体：
```
群组："Development Team"
智能体：
- CodeReviewer（审查代码片段）
- DocumentationBot（生成文档）
- SecurityAuditor（检查漏洞）
- TestGenerator（建议测试用例）
```
每个智能体处理同一条消息并提供其专业视角。
### 2. 多语言支持
```
群组："International Support"
智能体：
- Agent_EN（用英语回复）
- Agent_DE（用德语回复）
- Agent_ES（用西班牙语回复）
```
### 3. 质量保证工作流
```
群组："Customer Support"
智能体：
- SupportAgent（提供回答）
- QAAgent（审查质量，仅在发现问题时回复）
```
### 4. 任务自动化
```
群组："Project Management"
智能体：
- TaskTracker（更新任务数据库）
- TimeLogger（记录时间消耗）
- ReportGenerator（创建摘要）
```
## 配置
### 基本设置
添加顶层 `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...` 与 `agent:baerbel:whatsapp:group:120363...`）
- **对话历史**（智能体看不到其他智能体的消息）
- **工作区**（如果配置了则为独立沙箱）
- **工具访问**（不同的允许/拒绝列表）
- **记忆/上下文**（独立的 IDENTITY.md、SOUL.md 等）
- **群组上下文缓冲区**（用于上下文的最近群组消息）按 peer 共享，因此所有广播智能体在触发时看到相同的上下文
这使得每个智能体可以拥有：
- 不同的个性
- 不同的工具访问权限（例如只读与读写）
- 不同的模型（例如 opus 与 sonnet）
- 不同的已安装技能
### 示例：隔离会话
在群组 `120363403215116621@g.us` 中，智能体为 `["alfred", "baerbel"]`：
**Alfred 的上下文：**
```
会话：agent:alfred:whatsapp:group:120363403215116621@g.us
历史：[用户消息，alfred 之前的回复]
工作区：/Users/pascal/openclaw-alfred/
工具：read、write、exec
```
**Bärbel 的上下文：**
```
会话：agent:baerbel:whatsapp:group:120363403215116621@g.us
历史：[用户消息，baerbel 之前的回复]
工作区：/Users/pascal/openclaw-baerbel/
工具：仅 read
```
## 最佳实践
### 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"] } // 只读
},
"fixer": {
"tools": { "allow": ["read", "write", "edit", "exec"] } // 读写
}
}
}
```
### 4. 监控性能
当智能体数量较多时，请考虑：
- 使用 `"strategy": "parallel"`（默认）以提高速度
- 将广播群组限制在 5-10 个智能体
- 为较简单的智能体使用更快的模型
### 5. 优雅处理失败
智能体独立失败。一个智能体的错误不会阻塞其他智能体：
```
消息 → [智能体 A ✓, 智能体 B ✗ 错误, 智能体 C ✓]
结果：智能体 A 和 C 回复，智能体 B 记录错误
```
## 兼容性
### 提供商
广播群组目前支持：
- ✅ 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` 中。
**修复：** 添加到广播配置中或从 bindings 中移除。
### 性能问题
**如果智能体较多时速度慢：**
- 减少每个群组的智能体数量
- 使用更轻量的模型（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 速率限制
## 未来增强
计划中的功能：
- [ ] 共享上下文模式（智能体可以看到彼此的回复）
- [ ] 智能体协调（智能体可以互相通信）
- [ ] 动态智能体选择（根据消息内容选择智能体）
- [ ] 智能体优先级（某些智能体先于其他智能体回复）
## 另请参阅
- [多智能体配置](/multi-agent-sandbox-tools)
- [路由配置](/concepts/channel-routing)
- [会话管理](/concepts/sessions)

271
docs/zh-CN/channels/bluebubbles.md Normal file
View File

@@ -0,0 +1,271 @@
---
read_when:
- 设置 BlueBubbles 渠道
- 排查 webhook 配对问题
- 在 macOS 上配置 iMessage
summary: 通过 BlueBubbles macOS 服务器集成 iMessage（REST 发送/接收、输入状态、回应、配对、高级操作）。
title: BlueBubbles
x-i18n:
generated_at: "2026-02-01T19:41:18Z"
model: claude-opus-4-5
provider: pi
source_hash: ac9a9d71f3bbc661da6cb2897ea32d290bbd16b35925250601cfff53bc85de8c
source_path: channels/bluebubbles.md
workflow: 14
---
# BlueBubbles（macOS REST）
状态：内置插件，通过 HTTP 与 BlueBubbles macOS 服务器通信。**推荐用于 iMessage 集成**，因为相比旧版 imsg 渠道，其 API 更丰富且更易于设置。
## 概述
- 通过 BlueBubbles 辅助应用在 macOS 上运行（[bluebubbles.app](https://bluebubbles.app)）。
- 推荐/已测试：macOS Sequoia (15)。macOS Tahoe (26) 可用；编辑功能目前在 Tahoe 上不可用，群组图标更新可能报告成功但不会同步。
- OpenClaw 通过其 REST API 与之通信（`GET /api/v1/ping`、`POST /message/text`、`POST /chat/:id/*`）。
- 收到的消息通过 webhooks 到达；发出的回复、输入指示器、已读回执和 tapback 回应均为 REST 调用。
- 附件和贴纸作为入站媒体被接收（在可能的情况下呈现给智能体）。
- 配对/允许列表与其他渠道的工作方式相同（`/start/pairing` 等），使用 `channels.bluebubbles.allowFrom` + 配对码。
- 回应作为系统事件呈现，与 Slack/Telegram 相同，因此智能体可以在回复前"提及"它们。
- 高级功能：编辑、撤回、回复线程、消息特效、群组管理。
## 快速开始
1. 在你的 Mac 上安装 BlueBubbles 服务器（按照 [bluebubbles.app/install](https://bluebubbles.app/install) 的说明操作）。
2. 在 BlueBubbles 配置中，启用 Web API 并设置密码。
3. 运行 `openclaw onboard` 并选择 BlueBubbles，或手动配置：
```json5
{
channels: {
bluebubbles: {
enabled: true,
serverUrl: "http://192.168.1.100:1234",
password: "example-password",
webhookPath: "/bluebubbles-webhook",
},
},
}
```
4. 将 BlueBubbles webhooks 指向你的 Gateway（示例：`https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`）。
5. 启动 Gateway；它将注册 webhook 处理器并开始配对。
## 上手引导
BlueBubbles 可在交互式设置向导中使用：
```
openclaw onboard
```
向导会提示输入：
- **服务器 URL**（必填）：BlueBubbles 服务器地址（例如 `http://192.168.1.100:1234`）
- **密码**（必填）：来自 BlueBubbles 服务器设置的 API 密码
- **Webhook 路径**（可选）：默认为 `/bluebubbles-webhook`
- **私聊策略**：配对、允许列表、开放或禁用
- **允许列表**：电话号码、邮箱或聊天目标
你也可以通过 CLI 添加 BlueBubbles：
```
openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>
```
## 访问控制（私聊 + 群组）
私聊：
- 默认：`channels.bluebubbles.dmPolicy = "pairing"`。
- 未知发送者会收到配对码；消息在批准前会被忽略（配对码 1 小时后过期）。
- 通过以下方式批准：
- `openclaw pairing list bluebubbles`
- `openclaw pairing approve bluebubbles <CODE>`
- 配对是默认的令牌交换方式。详情：[配对](/start/pairing)
群组：
- `channels.bluebubbles.groupPolicy = open | allowlist | disabled`（默认：`allowlist`）。
- 当设置为 `allowlist` 时，`channels.bluebubbles.groupAllowFrom` 控制谁可以在群组中触发。
### 提及门控（群组）
BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致：
- 使用 `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）检测提及。
- 当群组启用 `requireMention` 时，智能体仅在被提及时回复。
- 来自授权发送者的控制命令会绕过提及门控。
按群组配置：
```json5
{
channels: {
bluebubbles: {
groupPolicy: "allowlist",
groupAllowFrom: ["+15555550123"],
groups: {
"*": { requireMention: true }, // 所有群组的默认值
"iMessage;-;chat123": { requireMention: false }, // 针对特定群组的覆盖
},
},
},
}
```
### 命令门控
- 控制命令（例如 `/config`、`/model`）需要授权。
- 使用 `allowFrom` 和 `groupAllowFrom` 来确定命令授权。
- 授权发送者即使在群组中未提及也可以运行控制命令。
## 输入状态 + 已读回执
- **输入指示器**：在生成回复前和生成过程中自动发送。
- **已读回执**：由 `channels.bluebubbles.sendReadReceipts` 控制（默认：`true`）。
- **输入指示器**：OpenClaw 发送输入开始事件；BlueBubbles 在发送或超时时自动清除输入状态（通过 DELETE 手动停止不可靠）。
```json5
{
channels: {
bluebubbles: {
sendReadReceipts: false, // 禁用已读回执
},
},
}
```
## 高级操作
在配置中启用后，BlueBubbles 支持高级消息操作：
```json5
{
channels: {
bluebubbles: {
actions: {
reactions: true, // tapback 回应（默认：true）
edit: true, // 编辑已发送消息（macOS 13+，macOS 26 Tahoe 上不可用）
unsend: true, // 撤回消息（macOS 13+）
reply: true, // 按消息 GUID 回复线程
sendWithEffect: true, // 消息特效（slam、loud 等）
renameGroup: true, // 重命名群聊
setGroupIcon: true, // 设置群聊图标/头像（macOS 26 Tahoe 上不稳定）
addParticipant: true, // 向群组添加参与者
removeParticipant: true, // 从群组移除参与者
leaveGroup: true, // 离开群聊
sendAttachment: true, // 发送附件/媒体
},
},
},
}
```
可用操作：
- **react**：添加/移除 tapback 回应（`messageId`、`emoji`、`remove`）
- **edit**：编辑已发送的消息（`messageId`、`text`）
- **unsend**：撤回消息（`messageId`）
- **reply**：回复特定消息（`messageId`、`text`、`to`）
- **sendWithEffect**：使用 iMessage 特效发送（`text`、`to`、`effectId`）
- **renameGroup**：重命名群聊（`chatGuid`、`displayName`）
- **setGroupIcon**：设置群聊图标/头像（`chatGuid`、`media`）——在 macOS 26 Tahoe 上不稳定（API 可能返回成功但图标不会同步）。
- **addParticipant**：向群组添加成员（`chatGuid`、`address`）
- **removeParticipant**：从群组移除成员（`chatGuid`、`address`）
- **leaveGroup**：离开群聊（`chatGuid`）
- **sendAttachment**：发送媒体/文件（`to`、`buffer`、`filename`、`asVoice`）
- 语音备忘录：设置 `asVoice: true` 并使用 **MP3** 或 **CAF** 音频以 iMessage 语音消息形式发送。BlueBubbles 在发送语音备忘录时会将 MP3 转换为 CAF。
### 消息 ID（短格式与完整格式）
OpenClaw 可能会呈现*短*消息 ID（例如 `1`、`2`）以节省 token。
- `MessageSid` / `ReplyToId` 可以是短 ID。
- `MessageSidFull` / `ReplyToIdFull` 包含提供商的完整 ID。
- 短 ID 存储在内存中；它们可能在重启或缓存清除后过期。
- 操作接受短格式或完整格式的 `messageId`，但如果短 ID 不再可用则会报错。
对于持久化自动化和存储，请使用完整 ID：
- 模板：`{{MessageSidFull}}`、`{{ReplyToIdFull}}`
- 上下文：入站负载中的 `MessageSidFull` / `ReplyToIdFull`
模板变量请参阅[配置](/gateway/configuration)。
## 分块流式传输
控制回复是作为单条消息发送还是分块流式传输：
```json5
{
channels: {
bluebubbles: {
blockStreaming: true, // 启用分块流式传输（默认行为）
},
},
}
```
## 媒体 + 限制
- 入站附件会被下载并存储在媒体缓存中。
- 媒体上限通过 `channels.bluebubbles.mediaMaxMb` 设置（默认：8 MB）。
- 出站文本按 `channels.bluebubbles.textChunkLimit` 进行分块（默认：4000 字符）。
## 配置参考
完整配置：[配置](/gateway/configuration)
提供商选项：
- `channels.bluebubbles.enabled`：启用/禁用渠道。
- `channels.bluebubbles.serverUrl`：BlueBubbles REST API 基础 URL。
- `channels.bluebubbles.password`：API 密码。
- `channels.bluebubbles.webhookPath`：Webhook 端点路径（默认：`/bluebubbles-webhook`）。
- `channels.bluebubbles.dmPolicy`：`pairing | allowlist | open | disabled`（默认：`pairing`）。
- `channels.bluebubbles.allowFrom`：私聊允许列表（句柄、邮箱、E.164 号码、`chat_id:*`、`chat_guid:*`）。
- `channels.bluebubbles.groupPolicy`：`open | allowlist | disabled`（默认：`allowlist`）。
- `channels.bluebubbles.groupAllowFrom`：群组发送者允许列表。
- `channels.bluebubbles.groups`：按群组配置（`requireMention` 等）。
- `channels.bluebubbles.sendReadReceipts`：发送已读回执（默认：`true`）。
- `channels.bluebubbles.blockStreaming`：启用分块流式传输（默认：`true`）。
- `channels.bluebubbles.textChunkLimit`：出站分块大小（字符数，默认：4000）。
- `channels.bluebubbles.chunkMode`：`length`（默认）仅在超过 `textChunkLimit` 时分割；`newline` 在空行（段落边界）处分割，然后再进行长度分块。
- `channels.bluebubbles.mediaMaxMb`：入站媒体上限（MB，默认：8）。
- `channels.bluebubbles.historyLimit`：用于上下文的最大群组消息数（0 表示禁用）。
- `channels.bluebubbles.dmHistoryLimit`：私聊历史限制。
- `channels.bluebubbles.actions`：启用/禁用特定操作。
- `channels.bluebubbles.accounts`：多账户配置。
相关全局选项：
- `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）。
- `messages.responsePrefix`。
## 寻址/投递目标
推荐使用 `chat_guid` 以实现稳定路由：
- `chat_guid:iMessage;-;+15555550123`（群组推荐使用）
- `chat_id:123`
- `chat_identifier:...`
- 直接句柄：`+15555550123`、`user@example.com`
- 如果直接句柄没有现有的私聊会话，OpenClaw 将通过 `POST /api/v1/chat/new` 创建一个。这需要启用 BlueBubbles Private API。
## 安全
- Webhook 请求通过将 `guid`/`password` 查询参数或请求头与 `channels.bluebubbles.password` 比较来进行认证。来自 `localhost` 的请求也会被接受。
- 请保密 API 密码和 webhook 端点（将其视为凭证）。
- localhost 信任意味着同主机的反向代理可能会无意间绕过密码。如果你为 Gateway 设置了代理，请在代理层要求认证并配置 `gateway.trustedProxies`。参见 [Gateway 安全](/gateway/security#reverse-proxy-configuration)。
- 如果将 BlueBubbles 服务器暴露到局域网外部，请启用 HTTPS + 防火墙规则。
## 故障排除
- 如果输入/已读事件停止工作，请检查 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 变更，编辑功能目前不可用。
- 群组图标更新在 macOS 26（Tahoe）上可能不稳定：API 可能返回成功但新图标不会同步。
- OpenClaw 会根据 BlueBubbles 服务器的 macOS 版本自动隐藏已知不可用的操作。如果编辑功能在 macOS 26（Tahoe）上仍然显示，请手动通过 `channels.bluebubbles.actions.edit=false` 禁用。
- 查看状态/健康信息：`openclaw status --all` 或 `openclaw status --deep`。
通用渠道工作流参考请参阅[渠道](/channels)和[插件](/plugins)指南。

463
docs/zh-CN/channels/discord.md Normal file
View File

@@ -0,0 +1,463 @@
---
read_when:
- 开发 Discord 渠道功能
summary: Discord 机器人支持状态、功能和配置
title: Discord
x-i18n:
generated_at: "2026-02-01T19:19:25Z"
model: claude-opus-4-5
provider: pi
source_hash: 44e44e855481a81557d9c205bacaa82efef528f8dba59a2c39c26aeb4f420c62
source_path: channels/discord.md
workflow: 14
---
# Discord（Bot API）
状态：已可用于通过官方 Discord 机器人网关进行私信和服务器文字频道通信。
## 快速设置（新手）
1. 创建一个 Discord 机器人并复制机器人 token。
2. 在 Discord 应用设置中，启用 **Message Content Intent**（如果你计划使用允许列表或名称查找，还需启用 **Server Members Intent**）。
3. 为 OpenClaw 设置 token：
- 环境变量：`DISCORD_BOT_TOKEN=...`
- 或配置：`channels.discord.token: "..."`。
- 如果两者都设置了，配置优先（环境变量回退仅用于默认账户）。
4. 邀请机器人到你的服务器并赋予消息权限（如果只想用私信可以创建一个私人服务器）。
5. 启动 Gateway。
6. 私信访问默认需要配对；首次联系时批准配对码即可。
最小配置：
```json5
{
channels: {
discord: {
enabled: true,
token: "YOUR_BOT_TOKEN",
},
},
}
```
## 目标
- 通过 Discord 私信或服务器频道与 OpenClaw 对话。
- 私聊合并到智能体的主会话（默认 `agent:main:main`）；服务器频道作为 `agent:<agentId>:discord:channel:<channelId>` 保持隔离（显示名称使用 `discord:<guildSlug>#<channelSlug>`）。
- 群组私信默认被忽略；通过 `channels.discord.dm.groupEnabled` 启用，可选通过 `channels.discord.dm.groupChannels` 限制。
- 保持路由确定性：回复始终发回消息到达的渠道。
## 工作原理
1. 创建 Discord 应用 → Bot，启用所需的 intent（私信 + 服务器消息 + 消息内容），获取机器人 token。
2. 邀请机器人到你的服务器，赋予在你需要使用的地方读取/发送消息所需的权限。
3. 使用 `channels.discord.token` 配置 OpenClaw（或使用 `DISCORD_BOT_TOKEN` 作为回退）。
4. 运行 Gateway；当 token 可用（配置优先，环境变量回退）且 `channels.discord.enabled` 不为 `false` 时，它会自动启动 Discord 渠道。
- 如果你偏好使用环境变量，设置 `DISCORD_BOT_TOKEN`（配置块是可选的）。
5. 私聊：投递时使用 `user:<id>`（或 `<@id>` 提及）；所有回合都进入共享的 `main` 会话。裸数字 ID 具有歧义性，会被拒绝。
6. 服务器频道：投递时使用 `channel:<channelId>`。默认需要提及，可按服务器或按频道设置。
7. 私聊：默认通过 `channels.discord.dm.policy`（默认：`"pairing"`）进行安全保护。未知发送者会收到配对码（1 小时后过期）；通过 `openclaw pairing approve discord <code>` 批准。
- 要保持旧的"对任何人开放"行为：设置 `channels.discord.dm.policy="open"` 和 `channels.discord.dm.allowFrom=["*"]`。
- 要硬性限制允许列表：设置 `channels.discord.dm.policy="allowlist"` 并在 `channels.discord.dm.allowFrom` 中列出发送者。
- 要忽略所有私信：设置 `channels.discord.dm.enabled=false` 或 `channels.discord.dm.policy="disabled"`。
8. 群组私信默认被忽略；通过 `channels.discord.dm.groupEnabled` 启用，可选通过 `channels.discord.dm.groupChannels` 限制。
9. 可选的服务器规则：设置 `channels.discord.guilds`，以服务器 ID（推荐）或 slug 为键，包含按频道的规则。
10. 可选的原生命令：`commands.native` 默认为 `"auto"`（Discord/Telegram 开启，Slack 关闭）。通过 `channels.discord.commands.native: true|false|"auto"` 覆盖；`false` 会清除之前注册的命令。文本命令由 `commands.text` 控制，必须作为独立的 `/...` 消息发送。使用 `commands.useAccessGroups: false` 可绕过命令的访问组检查。
- 完整命令列表 + 配置：[斜杠命令](/tools/slash-commands)
11. 可选的服务器上下文历史：设置 `channels.discord.historyLimit`（默认 20，回退到 `messages.groupChat.historyLimit`）以在回复提及时包含最近 N 条服务器消息作为上下文。设置 `0` 可禁用。
12. 回应：智能体可以通过 `discord` 工具触发回应（由 `channels.discord.actions.*` 控制）。
- 回应移除语义：参见 [/tools/reactions](/tools/reactions)。
- `discord` 工具仅在当前渠道为 Discord 时暴露。
13. 原生命令使用隔离的会话键（`agent:<agentId>:discord:slash:<userId>`）而非共享的 `main` 会话。
注意：名称 → ID 解析使用服务器成员搜索，需要 Server Members Intent；如果机器人无法搜索成员，请使用 ID 或 `<@id>` 提及。
注意：Slug 为小写且空格替换为 `-`。频道名称的 slug 不包含前导 `#`。
注意：服务器上下文 `[from:]` 行包含 `author.tag` + `id`，方便进行可直接 ping 的回复。
## 配置写入
默认情况下，Discord 允许通过 `/config set|unset` 触发的配置更新写入（需要 `commands.config: true`）。
通过以下方式禁用：
```json5
{
channels: { discord: { configWrites: false } },
}
```
## 如何创建自己的机器人
这是在服务器（guild）频道（如 `#help`）中运行 OpenClaw 的"Discord 开发者门户"设置。
### 1) 创建 Discord 应用 + 机器人用户
1. Discord 开发者门户 → **Applications** → **New Application**
2. 在你的应用中：
- **Bot** → **Add Bot**
- 复制 **Bot Token**（这就是你放入 `DISCORD_BOT_TOKEN` 的值）
### 2) 启用 OpenClaw 所需的网关 intent
Discord 会阻止"特权 intent"，除非你明确启用。
在 **Bot** → **Privileged Gateway Intents** 中，启用：
- **Message Content Intent**（在大多数服务器中读取消息文本所必需；没有它你会看到"Used disallowed intents"或机器人会连接但不响应消息）
- **Server Members Intent**（推荐；某些成员/用户查找和服务器中的允许列表匹配所必需）
通常你**不**需要 **Presence Intent**。
### 3) 生成邀请 URL（OAuth2 URL 生成器）
在你的应用中：**OAuth2** → **URL Generator**
**Scopes**
- ✅ `bot`
- ✅ `applications.commands`（原生命令所必需）
**Bot Permissions**（最小基线）
- ✅ View Channels
- ✅ Send Messages
- ✅ Read Message History
- ✅ Embed Links
- ✅ Attach Files
- ✅ Add Reactions（可选但推荐）
- ✅ Use External Emojis / Stickers（可选；仅在你需要时）
除非你在调试且完全信任机器人，否则避免使用 **Administrator**。
复制生成的 URL，打开它，选择你的服务器，安装机器人。
### 4) 获取 ID（服务器/用户/频道）
Discord 到处使用数字 ID；OpenClaw 配置推荐使用 ID。
1. Discord（桌面/网页）→ **用户设置** → **高级** → 启用 **开发者模式**
2. 右键点击：
- 服务器名称 → **复制服务器 ID**（guild id）
- 频道（例如 `#help`）→ **复制频道 ID**
- 你的用户 → **复制用户 ID**
### 5) 配置 OpenClaw
#### Token
通过环境变量设置机器人 token（推荐用于服务器）：
- `DISCORD_BOT_TOKEN=...`
或通过配置：
```json5
{
channels: {
discord: {
enabled: true,
token: "YOUR_BOT_TOKEN",
},
},
}
```
多账户支持：使用 `channels.discord.accounts`，每个账户配置独立的 token 和可选的 `name`。共享模式请参阅 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts)。
#### 允许列表 + 频道路由
示例"单服务器，只允许我，只允许 #help"：
```json5
{
channels: {
discord: {
enabled: true,
dm: { enabled: false },
guilds: {
YOUR_GUILD_ID: {
users: ["YOUR_USER_ID"],
requireMention: true,
channels: {
help: { allow: true, requireMention: true },
},
},
},
retry: {
attempts: 3,
minDelayMs: 500,
maxDelayMs: 30000,
jitter: 0.1,
},
},
},
}
```
注意事项：
- `requireMention: true` 表示机器人仅在被提及时回复（推荐用于共享频道）。
- `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）对服务器消息也算作提及。
- 多智能体覆盖：在 `agents.list[].groupChat.mentionPatterns` 上设置每个智能体的模式。
- 如果存在 `channels`，任何未列出的频道默认被拒绝。
- 使用 `"*"` 频道条目来应用所有频道的默认值；明确的频道条目会覆盖通配符。
- 帖子继承父频道配置（允许列表、`requireMention`、技能、提示等），除非你明确添加帖子频道 ID。
- 机器人发送的消息默认被忽略；设置 `channels.discord.allowBots=true` 可允许它们（自己的消息仍然被过滤）。
- 警告：如果你允许回复其他机器人（`channels.discord.allowBots=true`），请使用 `requireMention`、`channels.discord.guilds.*.channels.<id>.users` 允许列表和/或在 `AGENTS.md` 和 `SOUL.md` 中设置明确的防护规则来防止机器人之间的回复循环。
### 6) 验证是否正常工作
1. 启动 Gateway。
2. 在你的服务器频道中，发送：`@Krill hello`（或你的机器人名称）。
3. 如果没有响应：查看下方**故障排除**。
### 故障排除
- 首先：运行 `openclaw doctor` 和 `openclaw channels status --probe`（可操作的警告 + 快速审计）。
- **"Used disallowed intents"**：在开发者门户中启用 **Message Content Intent**（以及可能的 **Server Members Intent**），然后重启 Gateway。
- **机器人连接但在服务器频道中从不回复**：
- 缺少 **Message Content Intent**，或
- 机器人缺少频道权限（View/Send/Read History），或
- 你的配置要求提及但你没有提及它，或
- 你的服务器/频道允许列表拒绝了该频道/用户。
- **`requireMention: false` 但仍然没有回复**：
- `channels.discord.groupPolicy` 默认为 **allowlist**；将其设置为 `"open"` 或在 `channels.discord.guilds` 下添加服务器条目（可选在 `channels.discord.guilds.<id>.channels` 下列出频道以进行限制）。
- 如果你只设置了 `DISCORD_BOT_TOKEN` 且从未创建 `channels.discord` 部分，运行时默认将 `groupPolicy` 设为 `open`。添加 `channels.discord.groupPolicy`、`channels.defaults.groupPolicy` 或服务器/频道允许列表来锁定它。
- `requireMention` 必须位于 `channels.discord.guilds`（或特定频道）下。顶层的 `channels.discord.requireMention` 会被忽略。
- **权限审计**（`channels status --probe`）仅检查数字频道 ID。如果你使用 slug/名称作为 `channels.discord.guilds.*.channels` 的键，审计无法验证权限。
- **私信不工作**：`channels.discord.dm.enabled=false`、`channels.discord.dm.policy="disabled"`，或你尚未被批准（`channels.discord.dm.policy="pairing"`）。
## 功能与限制
- 私信和服务器文字频道（帖子被视为独立频道；不支持语音）。
- 输入指示尽力发送；消息分块使用 `channels.discord.textChunkLimit`（默认 2000）并按行数分割较长回复（`channels.discord.maxLinesPerMessage`，默认 17）。
- 可选的换行分块：设置 `channels.discord.chunkMode="newline"` 在按长度分块之前按空行（段落边界）分割。
- 支持文件上传，上限为配置的 `channels.discord.mediaMaxMb`（默认 8 MB）。
- 服务器回复默认需要提及门控，以避免嘈杂的机器人。
- 当消息引用另一条消息时，会注入回复上下文（引用内容 + ID）。
- 原生回复线程**默认关闭**；通过 `channels.discord.replyToMode` 和回复标签启用。
## 重试策略
出站 Discord API 调用在速率限制（429）时使用 Discord 的 `retry_after`（如可用）进行重试，采用指数退避和抖动。通过 `channels.discord.retry` 配置。参见[重试策略](/concepts/retry)。
## 配置
```json5
{
channels: {
discord: {
enabled: true,
token: "abc.123",
groupPolicy: "allowlist",
guilds: {
"*": {
channels: {
general: { allow: true },
},
},
},
mediaMaxMb: 8,
actions: {
reactions: true,
stickers: true,
emojiUploads: true,
stickerUploads: true,
polls: true,
permissions: true,
messages: true,
threads: true,
pins: true,
search: true,
memberInfo: true,
roleInfo: true,
roles: false,
channelInfo: true,
channels: true,
voiceStatus: true,
events: true,
moderation: false,
},
replyToMode: "off",
dm: {
enabled: true,
policy: "pairing", // pairing | allowlist | open | disabled
allowFrom: ["123456789012345678", "steipete"],
groupEnabled: false,
groupChannels: ["openclaw-dm"],
},
guilds: {
"*": { requireMention: true },
"123456789012345678": {
slug: "friends-of-openclaw",
requireMention: false,
reactionNotifications: "own",
users: ["987654321098765432", "steipete"],
channels: {
general: { allow: true },
help: {
allow: true,
requireMention: true,
users: ["987654321098765432"],
skills: ["search", "docs"],
systemPrompt: "Keep answers short.",
},
},
},
},
},
},
}
```
确认回应由 `messages.ackReaction` + `messages.ackReactionScope` 全局控制。使用 `messages.removeAckAfterReply` 在机器人回复后清除确认回应。
- `dm.enabled`：设置 `false` 可忽略所有私信（默认 `true`）。
- `dm.policy`：私信访问控制（推荐 `pairing`）。`"open"` 需要 `dm.allowFrom=["*"]`。
- `dm.allowFrom`：私信允许列表（用户 ID 或名称）。用于 `dm.policy="allowlist"` 和 `dm.policy="open"` 验证。向导接受用户名并在机器人可以搜索成员时将其解析为 ID。
- `dm.groupEnabled`：启用群组私信（默认 `false`）。
- `dm.groupChannels`：群组私信频道 ID 或 slug 的可选允许列表。
- `groupPolicy`：控制服务器频道处理方式（`open|disabled|allowlist`）；`allowlist` 需要频道允许列表。
- `guilds`：按服务器 ID（推荐）或 slug 为键的按服务器规则。
- `guilds."*"`：当没有明确条目时应用的默认按服务器设置。
- `guilds.<id>.slug`：用于显示名称的可选友好 slug。
- `guilds.<id>.users`：可选的按服务器用户允许列表（ID 或名称）。
- `guilds.<id>.tools`：可选的按服务器工具策略覆盖（`allow`/`deny`/`alsoAllow`），在频道覆盖缺失时使用。
- `guilds.<id>.toolsBySender`：可选的按发送者工具策略覆盖（服务器级别，在频道覆盖缺失时应用；支持 `"*"` 通配符）。
- `guilds.<id>.channels.<channel>.allow`：当 `groupPolicy="allowlist"` 时允许/拒绝频道。
- `guilds.<id>.channels.<channel>.requireMention`：频道的提及门控。
- `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>.systemPrompt`：频道的额外系统提示（与频道主题合并）。
- `guilds.<id>.channels.<channel>.enabled`：设置 `false` 可禁用频道。
- `guilds.<id>.channels`：频道规则（键为频道 slug 或 ID）。
- `guilds.<id>.requireMention`：按服务器的提及要求（可按频道覆盖）。
- `guilds.<id>.reactionNotifications`：回应系统事件模式（`off`、`own`、`all`、`allowlist`）。
- `textChunkLimit`：出站文本分块大小（字符）。默认：2000。
- `chunkMode`：`length`（默认）仅在超过 `textChunkLimit` 时分割；`newline` 在按长度分块之前按空行（段落边界）分割。
- `maxLinesPerMessage`：每条消息的软最大行数。默认：17。
- `mediaMaxMb`：限制保存到磁盘的入站媒体大小。
- `historyLimit`：回复提及时包含的最近服务器消息数作为上下文（默认 20；回退到 `messages.groupChat.historyLimit`；`0` 禁用）。
- `dmHistoryLimit`：私信历史限制（用户回合数）。按用户覆盖：`dms["<user_id>"].historyLimit`。
- `retry`：出站 Discord API 调用的重试策略（attempts、minDelayMs、maxDelayMs、jitter）。
- `pluralkit`：解析 PluralKit 代理消息，使系统成员显示为不同的发送者。
- `actions`：按操作的工具门控；省略则允许所有（设置 `false` 可禁用）。
- `reactions`（涵盖添加回应 + 读取回应）
- `stickers`、`emojiUploads`、`stickerUploads`、`polls`、`permissions`、`messages`、`threads`、`pins`、`search`
- `memberInfo`、`roleInfo`、`channelInfo`、`voiceStatus`、`events`
- `channels`（创建/编辑/删除频道 + 分类 + 权限）
- `roles`（角色添加/移除，默认 `false`）
- `moderation`（超时/踢出/封禁，默认 `false`）
回应通知使用 `guilds.<id>.reactionNotifications`：
- `off`：无回应事件。
- `own`：机器人自己消息上的回应（默认）。
- `all`：所有消息上的所有回应。
- `allowlist`：来自 `guilds.<id>.users` 的用户在所有消息上的回应（空列表则禁用）。
### PluralKit（PK）支持
启用 PK 查找，使代理消息解析为底层的系统 + 成员。启用后，OpenClaw 使用成员身份进行允许列表匹配，并将发送者标记为 `Member (PK:System)` 以避免意外的 Discord ping。
```json5
{
channels: {
discord: {
pluralkit: {
enabled: true,
token: "pk_live_...", // 可选；私有系统需要
},
},
},
}
```
允许列表注意事项（启用 PK 时）：
- 在 `dm.allowFrom`、`guilds.<id>.users` 或按频道的 `users` 中使用 `pk:<memberId>`。
- 成员显示名称也通过名称/slug 匹配。
- 查找使用**原始** Discord 消息 ID（代理前的消息），因此 PK API 仅在其 30 分钟窗口内解析它。
- 如果 PK 查找失败（例如没有 token 的私有系统），代理消息被视为机器人消息并被丢弃，除非设置 `channels.discord.allowBots=true`。
### 工具操作默认值
| 操作组 | 默认值 | 说明 |
| -------------- | ------ | ------------------------------- |
| reactions | 启用 | 添加回应 + 列出回应 + emojiList |
| stickers | 启用 | 发送贴纸 |
| emojiUploads | 启用 | 上传表情 |
| stickerUploads | 启用 | 上传贴纸 |
| polls | 启用 | 创建投票 |
| permissions | 启用 | 频道权限快照 |
| messages | 启用 | 读取/发送/编辑/删除 |
| threads | 启用 | 创建/列出/回复 |
| pins | 启用 | 置顶/取消置顶/列出 |
| search | 启用 | 消息搜索（预览功能） |
| memberInfo | 启用 | 成员信息 |
| roleInfo | 启用 | 角色列表 |
| channelInfo | 启用 | 频道信息 + 列表 |
| channels | 启用 | 频道/分类管理 |
| voiceStatus | 启用 | 语音状态查询 |
| events | 启用 | 列出/创建计划事件 |
| roles | 禁用 | 角色添加/移除 |
| moderation | 禁用 | 超时/踢出/封禁 |
- `replyToMode`：`off`（默认）、`first` 或 `all`。仅在模型输出包含回复标签时生效。
## 回复标签
要请求线程回复，模型可以在输出中包含一个标签：
- `[[reply_to_current]]` — 回复触发的 Discord 消息。
- `[[reply_to:<id>]]` — 回复上下文/历史中的特定消息 ID。
当前消息 ID 以 `[message_id: …]` 附加到提示中；历史条目已包含 ID。
行为由 `channels.discord.replyToMode` 控制：
- `off`：忽略标签。
- `first`：仅第一个出站分块/附件作为回复。
- `all`：每个出站分块/附件都作为回复。
允许列表匹配注意事项：
- `allowFrom`/`users`/`groupChannels` 接受 ID、名称、标签或 `<@id>` 格式的提及。
- 支持 `discord:`/`user:`（用户）和 `channel:`（群组私信）等前缀。
- 使用 `*` 允许任何发送者/频道。
- 当存在 `guilds.<id>.channels` 时，未列出的频道默认被拒绝。
- 当省略 `guilds.<id>.channels` 时，允许列表中服务器的所有频道都被允许。
- 要**不允许任何频道**，设置 `channels.discord.groupPolicy: "disabled"`（或保持空的允许列表）。
- 配置向导接受 `Guild/Channel` 名称（公共 + 私有）并在可能时将其解析为 ID。
- 启动时，OpenClaw 将允许列表中的频道/用户名称解析为 ID（当机器人可以搜索成员时）并记录映射；未解析的条目保持原样。
原生命令注意事项：
- 注册的命令与 OpenClaw 的聊天命令一致。
- 原生命令遵循与私信/服务器消息相同的允许列表（`channels.discord.dm.allowFrom`、`channels.discord.guilds`、按频道规则）。
- 斜杠命令在 Discord UI 中可能对不在允许列表中的用户仍然可见；OpenClaw 在执行时强制执行允许列表并回复"未授权"。
## 工具操作
智能体可以调用 `discord` 执行以下操作：
- `react` / `reactions`（添加或列出回应）
- `sticker`、`poll`、`permissions`
- `readMessages`、`sendMessage`、`editMessage`、`deleteMessage`
- 读取/搜索/置顶工具的负载包含标准化的 `timestampMs`（UTC 纪元毫秒）和 `timestampUtc`，同时保留原始 Discord `timestamp`。
- `threadCreate`、`threadList`、`threadReply`
- `pinMessage`、`unpinMessage`、`listPins`
- `searchMessages`、`memberInfo`、`roleInfo`、`roleAdd`、`roleRemove`、`emojiList`
- `channelInfo`、`channelList`、`voiceStatus`、`eventList`、`eventCreate`
- `timeout`、`kick`、`ban`
Discord 消息 ID 在注入的上下文中呈现（`[discord message id: …]` 和历史行），方便智能体定位它们。
表情可以是 unicode（例如 `✅`）或自定义表情语法如 `<:party_blob:1234567890>`。
## 安全与运维
- 将机器人 token 视为密码；在受管主机上推荐使用 `DISCORD_BOT_TOKEN` 环境变量或锁定配置文件权限。
- 仅授予机器人所需的权限（通常是读取/发送消息）。
- 如果机器人卡住或被速率限制，在确认没有其他进程占用 Discord 会话后重启 Gateway（`openclaw gateway --force`）。

257
docs/zh-CN/channels/googlechat.md Normal file
View File

@@ -0,0 +1,257 @@
---
read_when:
- 开发 Google Chat 渠道功能
summary: Google Chat 应用支持状态、功能和配置
title: Google Chat
x-i18n:
generated_at: "2026-02-01T19:20:03Z"
model: claude-opus-4-5
provider: pi
source_hash: 3b2bb116cdd12614c3d5afddd0879e9deb05c3606e3a2385cbc07f23552b357e
source_path: channels/googlechat.md
workflow: 14
---
# Google Chat（Chat API）
状态：已可通过 Google Chat API webhook（仅 HTTP）用于私信和空间。
## 快速设置（新手）
1. 创建一个 Google Cloud 项目并启用 **Google Chat API**。
- 前往：[Google Chat API 凭据](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials)
- 如果尚未启用，请启用该 API。
2. 创建**服务账户**：
- 点击 **Create Credentials** > **Service Account**。
- 随意命名（例如 `openclaw-chat`）。
- 权限留空（点击 **Continue**）。
- 有权访问的主体留空（点击 **Done**）。
3. 创建并下载 **JSON 密钥**：
- 在服务账户列表中，点击你刚创建的那个。
- 进入 **Keys** 标签页。
- 点击 **Add Key** > **Create new key**。
- 选择 **JSON** 并点击 **Create**。
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`）
- **Avatar URL**：（例如 `https://openclaw.ai/logo.png`）
- **Description**：（例如 `Personal AI Assistant`）
- 启用 **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。_
- 在 **Visibility** 下，勾选 **Make this Chat app available to specific people and groups in &lt;Your Domain&gt;**。
- 在文本框中输入你的邮箱地址（例如 `user@example.com`）。
- 点击底部的 **Save**。
6. **启用应用状态**：
- 保存后，**刷新页面**。
- 查找 **App status** 部分（通常在保存后位于顶部或底部附近）。
- 将状态更改为 **Live - available to users**。
- 再次点击 **Save**。
7. 使用服务账户路径 + webhook audience 配置 OpenClaw：
- 环境变量：`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 请求。
## 添加到 Google Chat
Gateway 运行且你的邮箱已添加到可见性列表后：
1. 前往 [Google Chat](https://chat.google.com/)。
2. 点击 **Direct Messages** 旁边的 **+**（加号）图标。
3. 在搜索栏中（通常用于添加人员的地方），输入你在 Google Cloud Console 中配置的 **App name**。
- **注意**：机器人*不会*出现在"Marketplace"浏览列表中，因为它是私有应用。你必须按名称搜索。
4. 从结果中选择你的机器人。
5. 点击 **Add** 或 **Chat** 开始一对一对话。
6. 发送"Hello"来触发助手！
## 公共 URL（仅 Webhook）
Google Chat webhook 需要公共 HTTPS 端点。为安全起见，**仅将 `/googlechat` 路径暴露**到互联网。将 OpenClaw 仪表板和其他敏感端点保持在私有网络上。
### 方案 A：Tailscale Funnel（推荐）
使用 Tailscale Serve 用于私有仪表板，Funnel 用于公共 webhook 路径。这样 `/` 保持私有，仅暴露 `/googlechat`。
1. **检查你的 Gateway 绑定在哪个地址上：**
```bash
ss -tlnp | grep 18789
```
注意 IP 地址（例如 `127.0.0.1`、`0.0.0.0` 或你的 Tailscale IP 如 `100.x.x.x`）。
2. **仅将仪表板暴露给 tailnet（端口 8443）：**
```bash
# 如果绑定到 localhost（127.0.0.1 或 0.0.0.0）：
tailscale serve --bg --https 8443 http://127.0.0.1:18789
# 如果仅绑定到 Tailscale IP（例如 100.106.161.80）：
tailscale serve --bg --https 8443 http://100.106.161.80:18789
```
3. **仅公开暴露 webhook 路径：**
```bash
# 如果绑定到 localhost（127.0.0.1 或 0.0.0.0）：
tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat
# 如果仅绑定到 Tailscale IP（例如 100.106.161.80）：
tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat
```
4. **为节点授权 Funnel 访问：**
如果出现提示，请访问输出中显示的授权 URL，在你的 tailnet 策略中为此节点启用 Funnel。
5. **验证配置：**
```bash
tailscale serve status
tailscale funnel status
```
你的公共 webhook URL 将是：
`https://<node-name>.<tailnet>.ts.net/googlechat`
你的私有仪表板仅限 tailnet 访问：
`https://<node-name>.<tailnet>.ts.net:8443/`
在 Google Chat 应用配置中使用公共 URL（不带 `:8443`）。
> 注意：此配置在重启后持续有效。要在之后移除，运行 `tailscale funnel reset` 和 `tailscale serve reset`。
### 方案 B：反向代理（Caddy）
如果你使用像 Caddy 这样的反向代理，仅代理特定路径：
```caddy
your-domain.com {
reverse_proxy /googlechat* localhost:18789
}
```
使用此配置，对 `your-domain.com/` 的任何请求将被忽略或返回 404，而 `your-domain.com/googlechat` 安全地路由到 OpenClaw。
### 方案 C：Cloudflare Tunnel
配置你的隧道入口规则，仅路由 webhook 路径：
- **路径**：`/googlechat` -> `http://localhost:18789/googlechat`
- **默认规则**：HTTP 404（Not Found）
## 工作原理
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 项目编号。
3. 消息按空间路由：
- 私信使用会话键 `agent:<agentId>:googlechat:dm:<spaceId>`。
- 空间使用会话键 `agent:<agentId>:googlechat:group:<spaceId>`。
4. 私信访问默认需要配对。未知发送者会收到配对码；通过以下方式批准：
- `openclaw pairing approve googlechat <code>`
5. 群组空间默认需要 @提及。如果提及检测需要应用的用户名，请使用 `botUser`。
## 目标
使用以下标识符进行投递和允许列表：
- 私信：`users/<userId>` 或 `users/<email>`（接受邮箱地址）。
- 空间：`spaces/<spaceId>`。
## 配置要点
```json5
{
channels: {
googlechat: {
enabled: true,
serviceAccountFile: "/path/to/service-account.json",
audienceType: "app-url",
audience: "https://gateway.example.com/googlechat",
webhookPath: "/googlechat",
botUser: "users/1234567890", // 可选；辅助提及检测
dm: {
policy: "pairing",
allowFrom: ["users/1234567890", "name@example.com"],
},
groupPolicy: "allowlist",
groups: {
"spaces/AAAA": {
allow: true,
requireMention: true,
users: ["users/1234567890"],
systemPrompt: "Short answers only.",
},
},
actions: { reactions: true },
typingIndicator: "message",
mediaMaxMb: 20,
},
},
}
```
注意事项：
- 服务账户凭据也可以通过 `serviceAccount`（JSON 字符串）内联传递。
- 如果未设置 `webhookPath`，默认 webhook 路径为 `/googlechat`。
- 当 `actions.reactions` 启用时，可通过 `reactions` 工具和 `channels action` 使用回应功能。
- `typingIndicator` 支持 `none`、`message`（默认）和 `reaction`（reaction 需要用户 OAuth）。
- 附件通过 Chat API 下载并存储在媒体管道中（大小由 `mediaMaxMb` 限制）。
## 故障排除
### 405 Method Not Allowed
如果 Google Cloud Logs Explorer 显示如下错误：
```
status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed
```
这意味着 webhook 处理器未注册。常见原因：
1. **渠道未配置**：配置中缺少 `channels.googlechat` 部分。通过以下方式验证：
```bash
openclaw config get channels.googlechat
```
如果返回"Config path not found"，添加配置（参见[配置要点](#配置要点)）。
2. **插件未启用**：检查插件状态：
```bash
openclaw plugins list | grep googlechat
```
如果显示"disabled"，在配置中添加 `plugins.entries.googlechat.enabled: true`。
3. **Gateway 未重启**：添加配置后，重启 Gateway：
```bash
openclaw gateway restart
```
验证渠道是否正在运行：
```bash
openclaw channels status
# 应显示：Google Chat default: enabled, configured, ...
```
### 其他问题
- 检查 `openclaw channels status --probe` 查看认证错误或缺失的 audience 配置。
- 如果没有消息到达，确认 Chat 应用的 webhook URL + 事件订阅。
- 如果提及门控阻止了回复，将 `botUser` 设置为应用的用户资源名称并验证 `requireMention`。
- 发送测试消息时使用 `openclaw logs --follow` 查看请求是否到达 Gateway。
相关文档：
- [Gateway 配置](/gateway/configuration)
- [安全](/gateway/security)
- [回应](/tools/reactions)

38
docs/zh-CN/channels/grammy.md Normal file
View File

@@ -0,0 +1,38 @@
---
read_when:
- 开发 Telegram 或 grammY 相关功能
summary: 通过 grammY 集成 Telegram Bot API 及设置说明
title: grammY
x-i18n:
generated_at: "2026-02-01T19:20:16Z"
model: claude-opus-4-5
provider: pi
source_hash: ea7ef23e6d77801f4ef5fc56685ef4470f79f5aecab448d644a72cbab53521b7
source_path: channels/grammy.md
workflow: 14
---
# grammY 集成（Telegram Bot API）
# 为什么选择 grammY
- TypeScript 优先的 Bot API 客户端，内置长轮询 + webhook 辅助工具、中间件、错误处理、速率限制器。
- 比手动编写 fetch + FormData 更简洁的媒体辅助工具；支持所有 Bot API 方法。
- 可扩展：通过自定义 fetch 支持代理，会话中间件（可选），类型安全的上下文。
# 已交付的功能
- **单一客户端路径：** 基于 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 模式（否则使用长轮询）。
- **会话：** 私聊合并到智能体主会话（`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+）。这与渠道分块流式传输是分开的。
- **测试：** grammY mock 覆盖了私信 + 群组提及门控和出站发送；欢迎更多媒体/webhook 测试用例。
待讨论问题
- 如果遇到 Bot API 429 错误，考虑使用可选的 grammY 插件（throttler）。
- 添加更多结构化的媒体测试（贴纸、语音消息）。
- 使 webhook 监听端口可配置（目前固定为 8787，除非通过 Gateway 接入）。

302
docs/zh-CN/channels/imessage.md Normal file
View File

@@ -0,0 +1,302 @@
---
read_when:
- 设置 iMessage 支持
- 调试 iMessage 收发
summary: 通过 imsg（基于 stdio 的 JSON-RPC）实现 iMessage 支持、设置和 chat_id 路由
title: iMessage
x-i18n:
generated_at: "2026-02-01T19:21:07Z"
model: claude-opus-4-5
provider: pi
source_hash: bc19756a42ead80a0845f18c4830c3f1f40948f69b2b016a4026598cfb8fef0d
source_path: channels/imessage.md
workflow: 14
---
# iMessage（imsg）
状态：外部 CLI 集成。Gateway 启动 `imsg rpc`（基于 stdio 的 JSON-RPC）。
## 快速设置（新手）
1. 确保此 Mac 上的"信息"已登录。
2. 安装 `imsg`：
- `brew install steipete/tap/imsg`
3. 配置 OpenClaw 的 `channels.imessage.cliPath` 和 `channels.imessage.dbPath`。
4. 启动 Gateway 并批准所有 macOS 提示（自动化 + 完全磁盘访问权限）。
最小配置：
```json5
{
channels: {
imessage: {
enabled: true,
cliPath: "/usr/local/bin/imsg",
dbPath: "/Users/<you>/Library/Messages/chat.db",
},
},
}
```
## 它是什么
- 在 macOS 上由 `imsg` 支持的 iMessage 渠道。
- 确定性路由：回复始终发回 iMessage。
- 私信共享智能体的主会话；群组是隔离的（`agent:<agentId>:imessage:group:<chat_id>`）。
- 如果多参与者线程以 `is_group=false` 到达，你仍然可以通过 `chat_id` 使用 `channels.imessage.groups` 来隔离它（参见下方"类群组线程"）。
## 配置写入
默认情况下，iMessage 允许通过 `/config set|unset` 触发的配置更新写入（需要 `commands.config: true`）。
通过以下方式禁用：
```json5
{
channels: { imessage: { configWrites: false } },
}
```
## 要求
- macOS 且"信息"已登录。
- OpenClaw + `imsg` 需要完全磁盘访问权限（访问 Messages 数据库）。
- 发送时需要自动化权限。
- `channels.imessage.cliPath` 可以指向任何代理 stdin/stdout 的命令（例如，通过 SSH 连接到另一台 Mac 并运行 `imsg rpc` 的包装脚本）。
## 设置（快速路径）
1. 确保此 Mac 上的"信息"已登录。
2. 配置 iMessage 并启动 Gateway。
### 专用机器人 macOS 用户（用于隔离身份）
如果你希望机器人从一个**独立的 iMessage 身份**发送消息（并保持你的个人"信息"整洁），请使用专用的 Apple ID + 专用的 macOS 用户。
1. 创建一个专用的 Apple ID（例如：`my-cool-bot@icloud.com`）。
- Apple 可能需要手机号码进行验证/双重认证。
2. 创建一个 macOS 用户（例如：`openclawhome`）并登录。
3. 在该 macOS 用户中打开"信息"并使用机器人 Apple ID 登录 iMessage。
4. 启用远程登录（系统设置 → 通用 → 共享 → 远程登录）。
5. 安装 `imsg`：
- `brew install steipete/tap/imsg`
6. 设置 SSH 使 `ssh <bot-macos-user>@localhost true` 无需密码即可工作。
7. 将 `channels.imessage.accounts.bot.cliPath` 指向一个以机器人用户身份运行 `imsg` 的 SSH 包装脚本。
首次运行注意事项：发送/接收可能需要在*机器人 macOS 用户*中进行 GUI 审批（自动化 + 完全磁盘访问权限）。如果 `imsg rpc` 看起来卡住或退出，请登录该用户（屏幕共享很有帮助），运行一次 `imsg chats --limit 1` / `imsg send ...`，批准提示，然后重试。
示例包装脚本（`chmod +x`）。将 `<bot-macos-user>` 替换为你的实际 macOS 用户名：
```bash
#!/usr/bin/env bash
set -euo pipefail
# 先运行一次交互式 SSH 以接受主机密钥：
# ssh <bot-macos-user>@localhost true
exec /usr/bin/ssh -o BatchMode=yes -o ConnectTimeout=5 -T <bot-macos-user>@localhost \
"/usr/local/bin/imsg" "$@"
```
示例配置：
```json5
{
channels: {
imessage: {
enabled: true,
accounts: {
bot: {
name: "Bot",
enabled: true,
cliPath: "/path/to/imsg-bot",
dbPath: "/Users/<bot-macos-user>/Library/Messages/chat.db",
},
},
},
},
}
```
对于单账户设置，使用扁平选项（`channels.imessage.cliPath`、`channels.imessage.dbPath`）而非 `accounts` 映射。
### 远程/SSH 变体（可选）
如果你想在另一台 Mac 上使用 iMessage，将 `channels.imessage.cliPath` 设置为通过 SSH 在远程 macOS 主机上运行 `imsg` 的包装脚本。OpenClaw 只需要 stdio。
示例包装脚本：
```bash
#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"
```
**远程附件：** 当 `cliPath` 通过 SSH 指向远程主机时，Messages 数据库中的附件路径引用的是远程机器上的文件。OpenClaw 可以通过设置 `channels.imessage.remoteHost` 自动通过 SCP 获取这些文件：
```json5
{
channels: {
imessage: {
cliPath: "~/imsg-ssh", // 到远程 Mac 的 SSH 包装脚本
remoteHost: "user@gateway-host", // 用于 SCP 文件传输
includeAttachments: true,
},
},
}
```
如果未设置 `remoteHost`，OpenClaw 会尝试通过解析你包装脚本中的 SSH 命令来自动检测。建议显式配置以确保可靠性。
#### 通过 Tailscale 连接远程 Mac（示例）
如果 Gateway 运行在 Linux 主机/虚拟机上但 iMessage 必须运行在 Mac 上，Tailscale 是最简单的桥接方案：Gateway 通过 tailnet 与 Mac 通信，通过 SSH 运行 `imsg`，并通过 SCP 传回附件。
架构：
```
┌──────────────────────────────┐ SSH (imsg rpc) ┌──────────────────────────┐
│ Gateway 主机（Linux/VM） │──────────────────────────────────▶│ 装有 Messages + imsg 的 Mac │
│ - openclaw gateway │ SCP（附件） │ - Messages 已登录 │
│ - channels.imessage.cliPath │◀──────────────────────────────────│ - 远程登录已启用 │
└──────────────────────────────┘ └──────────────────────────┘
▲
│ Tailscale tailnet（主机名或 100.x.y.z）
▼
user@gateway-host
```
具体配置示例（Tailscale 主机名）：
```json5
{
channels: {
imessage: {
enabled: true,
cliPath: "~/.openclaw/scripts/imsg-ssh",
remoteHost: "bot@mac-mini.tailnet-1234.ts.net",
includeAttachments: true,
dbPath: "/Users/bot/Library/Messages/chat.db",
},
},
}
```
示例包装脚本（`~/.openclaw/scripts/imsg-ssh`）：
```bash
#!/usr/bin/env bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"
```
注意事项：
- 确保 Mac 已登录"信息"，且远程登录已启用。
- 使用 SSH 密钥使 `ssh bot@mac-mini.tailnet-1234.ts.net` 无需提示即可工作。
- `remoteHost` 应与 SSH 目标匹配，以便 SCP 可以获取附件。
多账户支持：使用 `channels.imessage.accounts`，每个账户配置独立选项和可选的 `name`。共享模式请参阅 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts)。不要提交 `~/.openclaw/openclaw.json`（它通常包含 token）。
## 访问控制（私信 + 群组）
私信：
- 默认：`channels.imessage.dmPolicy = "pairing"`。
- 未知发送者会收到配对码；在批准之前消息会被忽略（配对码 1 小时后过期）。
- 通过以下方式批准：
- `openclaw pairing list imessage`
- `openclaw pairing approve imessage <CODE>`
- 配对是 iMessage 私信的默认令牌交换方式。详情：[配对](/start/pairing)
群组：
- `channels.imessage.groupPolicy = open | allowlist | disabled`。
- 当设置为 `allowlist` 时，`channels.imessage.groupAllowFrom` 控制谁可以在群组中触发。
- 提及门控使用 `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`），因为 iMessage 没有原生提及元数据。
- 多智能体覆盖：在 `agents.list[].groupChat.mentionPatterns` 上设置每个智能体的模式。
## 工作原理（行为）
- `imsg` 流式传输消息事件；Gateway 将其标准化为共享的渠道信封。
- 回复始终路由回同一个 chat id 或用户名。
## 类群组线程（`is_group=false`）
一些 iMessage 线程可能有多个参与者，但由于"信息"存储聊天标识符的方式，仍然以 `is_group=false` 到达。
如果你在 `channels.imessage.groups` 下显式配置了一个 `chat_id`，OpenClaw 会将该线程视为"群组"，用于：
- 会话隔离（独立的 `agent:<agentId>:imessage:group:<chat_id>` 会话键）
- 群组允许列表/提及门控行为
示例：
```json5
{
channels: {
imessage: {
groupPolicy: "allowlist",
groupAllowFrom: ["+15555550123"],
groups: {
"42": { requireMention: false },
},
},
},
}
```
当你想为特定线程使用隔离的个性/模型时很有用（参见[多智能体路由](/concepts/multi-agent)）。有关文件系统隔离，请参阅[沙箱](/gateway/sandboxing)。
## 媒体 + 限制
- 通过 `channels.imessage.includeAttachments` 可选接收附件。
- 媒体上限通过 `channels.imessage.mediaMaxMb` 设置。
## 限制
- 出站文本按 `channels.imessage.textChunkLimit` 分块（默认 4000）。
- 可选的换行分块：设置 `channels.imessage.chunkMode="newline"` 在按长度分块之前按空行（段落边界）分割。
- 媒体上传上限由 `channels.imessage.mediaMaxMb` 限制（默认 16）。
## 寻址 / 投递目标
推荐使用 `chat_id` 进行稳定路由：
- `chat_id:123`（推荐）
- `chat_guid:...`
- `chat_identifier:...`
- 直接用户名：`imessage:+1555` / `sms:+1555` / `user@example.com`
列出聊天：
```
imsg chats --limit 20
```
## 配置参考（iMessage）
完整配置：[配置](/gateway/configuration)
提供商选项：
- `channels.imessage.enabled`：启用/禁用渠道启动。
- `channels.imessage.cliPath`：`imsg` 的路径。
- `channels.imessage.dbPath`：Messages 数据库路径。
- `channels.imessage.remoteHost`：当 `cliPath` 指向远程 Mac 时用于 SCP 附件传输的 SSH 主机（例如 `user@gateway-host`）。未设置时从 SSH 包装脚本自动检测。
- `channels.imessage.service`：`imessage | sms | auto`。
- `channels.imessage.region`：SMS 区域。
- `channels.imessage.dmPolicy`：`pairing | allowlist | open | disabled`（默认：pairing）。
- `channels.imessage.allowFrom`：私信允许列表（用户名、邮箱、E.164 号码或 `chat_id:*`）。`open` 需要 `"*"`。iMessage 没有用户名；使用用户名或聊天目标。
- `channels.imessage.groupPolicy`：`open | allowlist | disabled`（默认：allowlist）。
- `channels.imessage.groupAllowFrom`：群组发送者允许列表。
- `channels.imessage.historyLimit` / `channels.imessage.accounts.*.historyLimit`：包含为上下文的最大群组消息数（0 禁用）。
- `channels.imessage.dmHistoryLimit`：私信历史限制（用户回合数）。按用户覆盖：`channels.imessage.dms["<handle>"].historyLimit`。
- `channels.imessage.groups`：按群组默认值 + 允许列表（使用 `"*"` 设置全局默认值）。
- `channels.imessage.includeAttachments`：将附件接收到上下文中。
- `channels.imessage.mediaMaxMb`：入站/出站媒体上限（MB）。
- `channels.imessage.textChunkLimit`：出站分块大小（字符）。
- `channels.imessage.chunkMode`：`length`（默认）或 `newline`，在按长度分块之前按空行（段落边界）分割。
相关全局选项：
- `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）。
- `messages.responsePrefix`。

50
docs/zh-CN/channels/index.md Normal file
View File

@@ -0,0 +1,50 @@
---
read_when:
- 你想为 OpenClaw 选择一个聊天渠道
- 你需要快速了解支持的消息平台
summary: OpenClaw 可连接的消息平台
title: 聊天渠道
x-i18n:
generated_at: "2026-02-01T19:21:22Z"
model: claude-opus-4-5
provider: pi
source_hash: 2632863def6dee97e0fa8b931762f0969174fd4fb22303a00dcd46527fe4a141
source_path: channels/index.md
workflow: 14
---
# 聊天渠道
OpenClaw 可以在你已经使用的任何聊天应用上与你对话。每个渠道通过 Gateway 连接。所有渠道都支持文本；媒体和回应功能因渠道而异。
## 支持的渠道
- [WhatsApp](/channels/whatsapp) — 最受欢迎；使用 Baileys 并需要二维码配对。
- [Telegram](/channels/telegram) — 通过 grammY 使用 Bot API；支持群组。
- [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；频道、群组、私信（插件，需单独安装）。
- [Signal](/channels/signal) — signal-cli；注重隐私。
- [BlueBubbles](/channels/bluebubbles) — **推荐用于 iMessage**；使用 BlueBubbles macOS 服务器 REST API，功能完整（编辑、撤回、特效、回应、群组管理——编辑功能在 macOS 26 Tahoe 上目前不可用）。
- [iMessage](/channels/imessage) — 仅限 macOS；通过 imsg 原生集成（旧版，新设置建议使用 BlueBubbles）。
- [Microsoft Teams](/channels/msteams) — Bot Framework；企业支持（插件，需单独安装）。
- [LINE](/channels/line) — LINE Messaging API 机器人（插件，需单独安装）。
- [Nextcloud Talk](/channels/nextcloud-talk) — 通过 Nextcloud Talk 的自托管聊天（插件，需单独安装）。
- [Matrix](/channels/matrix) — Matrix 协议（插件，需单独安装）。
- [Nostr](/channels/nostr) — 通过 NIP-04 的去中心化私信（插件，需单独安装）。
- [Tlon](/channels/tlon) — 基于 Urbit 的通讯工具（插件，需单独安装）。
- [Twitch](/channels/twitch) — 通过 IRC 连接的 Twitch 聊天（插件，需单独安装）。
- [Zalo](/channels/zalo) — Zalo Bot API；越南流行的通讯工具（插件，需单独安装）。
- [Zalo Personal](/channels/zalouser) — 通过二维码登录的 Zalo 个人账户（插件，需单独安装）。
- [WebChat](/web/webchat) — 通过 WebSocket 的 Gateway WebChat UI。
## 注意事项
- 渠道可以同时运行；配置多个渠道后 OpenClaw 会按聊天路由。
- 最快的设置通常是 **Telegram**（简单的 bot token）。WhatsApp 需要二维码配对并在磁盘上存储更多状态。
- 群组行为因渠道而异；参见[群组](/concepts/groups)。
- 私信配对和允许列表出于安全考虑强制执行；参见[安全](/gateway/security)。
- Telegram 内部实现：[grammY 说明](/channels/grammy)。
- 故障排除：[渠道故障排除](/channels/troubleshooting)。
- 模型提供商单独文档化；参见[模型提供商](/providers/models)。

180
docs/zh-CN/channels/line.md Normal file
View File

@@ -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`。

63
docs/zh-CN/channels/location.md Normal file
View File

@@ -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。

221
docs/zh-CN/channels/matrix.md Normal file
View File

@@ -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）。

142
docs/zh-CN/channels/mattermost.md Normal file
View File

@@ -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` 账户。

770
docs/zh-CN/channels/msteams.md Normal file
View File

@@ -0,0 +1,770 @@
---
read_when:
- 开发 Microsoft Teams 渠道功能
summary: Microsoft Teams 机器人支持状态、功能和配置
title: Microsoft Teams
x-i18n:
generated_at: "2026-02-01T19:26:12Z"
model: claude-opus-4-5
provider: pi
source_hash: 3d5641c578086f7569f42276d4ef2462200b9927ca3f505e6ee26806103eaa60
source_path: channels/msteams.md
workflow: 14
---
# Microsoft Teams（插件）
> "进入此处者，放弃一切希望。"
更新时间：2026-01-21
状态：支持文本 + 私信附件；频道/群组文件发送需要 `sharePointSiteId` + Graph 权限（参见[在群聊中发送文件](#在群聊中发送文件)）。投票通过 Adaptive Cards 发送。
## 需要插件
Microsoft Teams 作为插件发布，不包含在核心安装中。
**破坏性变更（2026.1.15）：** Microsoft Teams 已从核心中移出。如果你使用它，必须安装插件。
原因说明：保持核心安装更轻量，并让 Microsoft Teams 依赖项可以独立更新。
通过 CLI 安装（npm 注册表）：
```bash
openclaw plugins install @openclaw/msteams
```
本地检出（从 git 仓库运行时）：
```bash
openclaw plugins install ./extensions/msteams
```
如果你在配置/上手引导期间选择了 Teams 并检测到 git 检出，OpenClaw 会自动提供本地安装路径。
详情：[插件](/plugin)
## 快速设置（新手）
1. 安装 Microsoft Teams 插件。
2. 创建一个 **Azure Bot**（App ID + 客户端密钥 + 租户 ID）。
3. 使用这些凭据配置 OpenClaw。
4. 通过公共 URL 或隧道暴露 `/api/messages`（默认端口 3978）。
5. 安装 Teams 应用包并启动 Gateway。
最小配置：
```json5
{
channels: {
msteams: {
enabled: true,
appId: "<APP_ID>",
appPassword: "<APP_PASSWORD>",
tenantId: "<TENANT_ID>",
webhook: { port: 3978, path: "/api/messages" },
},
},
}
```
注意：群聊默认被阻止（`channels.msteams.groupPolicy: "allowlist"`）。要允许群组回复，请设置 `channels.msteams.groupAllowFrom`（或使用 `groupPolicy: "open"` 允许任何成员，提及门控）。
## 目标
- 通过 Teams 私信、群聊或频道与 OpenClaw 对话。
- 保持路由确定性：回复始终发回消息到达的渠道。
- 默认使用安全的渠道行为（除非另行配置，否则需要提及）。
## 配置写入
默认情况下，Microsoft Teams 允许通过 `/config set|unset` 触发的配置更新写入（需要 `commands.config: true`）。
通过以下方式禁用：
```json5
{
channels: { msteams: { configWrites: false } },
}
```
## 访问控制（私信 + 群组）
**私信访问**
- 默认：`channels.msteams.dmPolicy = "pairing"`。未知发送者在批准前会被忽略。
- `channels.msteams.allowFrom` 接受 AAD 对象 ID、UPN 或显示名称。当凭据允许时，向导通过 Microsoft Graph 将名称解析为 ID。
**群组访问**
- 默认：`channels.msteams.groupPolicy = "allowlist"`（被阻止，除非你添加 `groupAllowFrom`）。使用 `channels.defaults.groupPolicy` 可在未设置时覆盖默认值。
- `channels.msteams.groupAllowFrom` 控制哪些发送者可以在群聊/频道中触发（回退到 `channels.msteams.allowFrom`）。
- 设置 `groupPolicy: "open"` 可允许任何成员（默认仍需提及门控）。
- 要**不允许任何频道**，设置 `channels.msteams.groupPolicy: "disabled"`。
示例：
```json5
{
channels: {
msteams: {
groupPolicy: "allowlist",
groupAllowFrom: ["user@org.com"],
},
},
}
```
**团队 + 频道允许列表**
- 通过在 `channels.msteams.teams` 下列出团队和频道来限定群组/频道回复范围。
- 键可以是团队 ID 或名称；频道键可以是会话 ID 或名称。
- 当 `groupPolicy="allowlist"` 且存在团队允许列表时，仅接受列出的团队/频道（提及门控）。
- 配置向导接受 `Team/Channel` 条目并为你存储。
- 启动时，OpenClaw 将团队/频道和用户允许列表名称解析为 ID（当 Graph 权限允许时）并记录映射；未解析的条目保持原样。
示例：
```json5
{
channels: {
msteams: {
groupPolicy: "allowlist",
teams: {
"My Team": {
channels: {
General: { requireMention: true },
},
},
},
},
},
}
```
## 工作原理
1. 安装 Microsoft Teams 插件。
2. 创建一个 **Azure Bot**（App ID + 密钥 + 租户 ID）。
3. 构建一个引用该机器人并包含下方 RSC 权限的 **Teams 应用包**。
4. 将 Teams 应用上传/安装到团队（或私人范围用于私信）。
5. 在 `~/.openclaw/openclaw.json`（或环境变量）中配置 `msteams` 并启动 Gateway。
6. Gateway 默认在 `/api/messages` 上监听 Bot Framework webhook 流量。
## Azure Bot 设置（前提条件）
在配置 OpenClaw 之前，你需要创建一个 Azure Bot 资源。
### 步骤 1：创建 Azure Bot
1. 前往[创建 Azure Bot](https://portal.azure.com/#create/Microsoft.AzureBot)
2. 填写 **Basics** 标签页：
| 字段 | 值 |
| ------------------ | --------------------------------------------------- |
| **Bot handle** | 你的机器人名称，例如 `openclaw-msteams`（必须唯一） |
| **Subscription** | 选择你的 Azure 订阅 |
| **Resource group** | 新建或使用现有的 |
| **Pricing tier** | **Free** 用于开发/测试 |
| **Type of App** | **Single Tenant**（推荐 - 见下方说明） |
| **Creation type** | **Create new Microsoft App ID** |
> **弃用通知：** 2025-07-31 之后已弃用创建新的多租户机器人。新机器人请使用 **Single Tenant**。
3. 点击 **Review + create** → **Create**（等待约 1-2 分钟）
### 步骤 2：获取凭据
1. 前往你的 Azure Bot 资源 → **Configuration**
2. 复制 **Microsoft App ID** → 这是你的 `appId`
3. 点击 **Manage Password** → 进入应用注册
4. 在 **Certificates & secrets** → **New client secret** → 复制 **Value** → 这是你的 `appPassword`
5. 进入 **Overview** → 复制 **Directory (tenant) ID** → 这是你的 `tenantId`
### 步骤 3：配置消息端点
1. 在 Azure Bot → **Configuration**
2. 将 **Messaging endpoint** 设置为你的 webhook URL：
- 生产环境：`https://your-domain.com/api/messages`
- 本地开发：使用隧道（参见下方[本地开发](#本地开发隧道)）
### 步骤 4：启用 Teams 频道
1. 在 Azure Bot → **Channels**
2. 点击 **Microsoft Teams** → Configure → Save
3. 接受服务条款
## 本地开发（隧道）
Teams 无法访问 `localhost`。本地开发请使用隧道：
**方案 A：ngrok**
```bash
ngrok http 3978
# 复制 https URL，例如 https://abc123.ngrok.io
# 将消息端点设置为：https://abc123.ngrok.io/api/messages
```
**方案 B：Tailscale Funnel**
```bash
tailscale funnel 3978
# 使用你的 Tailscale funnel URL 作为消息端点
```
## Teams 开发者门户（替代方案）
除了手动创建清单 ZIP 外，你可以使用 [Teams 开发者门户](https://dev.teams.microsoft.com/apps)：
1. 点击 **+ New app**
2. 填写基本信息（名称、描述、开发者信息）
3. 进入 **App features** → **Bot**
4. 选择 **Enter a bot ID manually** 并粘贴你的 Azure Bot App ID
5. 勾选范围：**Personal**、**Team**、**Group Chat**
6. 点击 **Distribute** → **Download app package**
7. 在 Teams 中：**Apps** → **Manage your apps** → **Upload a custom app** → 选择 ZIP
这通常比手动编辑 JSON 清单更简单。
## 测试机器人
**方案 A：Azure Web Chat（先验证 webhook）**
1. 在 Azure 门户 → 你的 Azure Bot 资源 → **Test in Web Chat**
2. 发送一条消息 - 你应该看到回复
3. 这确认了你的 webhook 端点在 Teams 设置之前可以正常工作
**方案 B：Teams（安装应用后）**
1. 安装 Teams 应用（旁加载或组织目录）
2. 在 Teams 中找到机器人并发送私信
3. 检查 Gateway 日志中的传入活动
## 设置（最小纯文本）
1. **安装 Microsoft Teams 插件**
- 从 npm：`openclaw plugins install @openclaw/msteams`
- 从本地检出：`openclaw plugins install ./extensions/msteams`
2. **机器人注册**
- 创建 Azure Bot（见上方）并记录：
- App ID
- 客户端密钥（App password）
- 租户 ID（单租户）
3. **Teams 应用清单**
- 包含一个 `bot` 条目，其中 `botId = <App ID>`。
- 范围：`personal`、`team`、`groupChat`。
- `supportsFiles: true`（个人范围文件处理所必需）。
- 添加 RSC 权限（见下方）。
- 创建图标：`outline.png`（32x32）和 `color.png`（192x192）。
- 将三个文件打包在一起：`manifest.json`、`outline.png`、`color.png`。
4. **配置 OpenClaw**
```json
{
"msteams": {
"enabled": true,
"appId": "<APP_ID>",
"appPassword": "<APP_PASSWORD>",
"tenantId": "<TENANT_ID>",
"webhook": { "port": 3978, "path": "/api/messages" }
}
}
```
你也可以使用环境变量替代配置键：
- `MSTEAMS_APP_ID`
- `MSTEAMS_APP_PASSWORD`
- `MSTEAMS_TENANT_ID`
5. **机器人端点**
- 将 Azure Bot 消息端点设置为：
- `https://<host>:3978/api/messages`（或你选择的路径/端口）。
6. **运行 Gateway**
- 当插件已安装且 `msteams` 配置存在凭据时，Teams 渠道会自动启动。
## 历史上下文
- `channels.msteams.historyLimit` 控制多少条最近的频道/群组消息被包含在提示中。
- 回退到 `messages.groupChat.historyLimit`。设置 `0` 可禁用（默认 50）。
- 私信历史可通过 `channels.msteams.dmHistoryLimit`（用户回合数）限制。按用户覆盖：`channels.msteams.dms["<user_id>"].historyLimit`。
## 当前 Teams RSC 权限（清单）
以下是我们 Teams 应用清单中**现有的 resourceSpecific 权限**。它们仅在安装了应用的团队/聊天中适用。
**频道（团队范围）：**
- `ChannelMessage.Read.Group`（Application）- 无需 @提及即可接收所有频道消息
- `ChannelMessage.Send.Group`（Application）
- `Member.Read.Group`（Application）
- `Owner.Read.Group`（Application）
- `ChannelSettings.Read.Group`（Application）
- `TeamMember.Read.Group`（Application）
- `TeamSettings.Read.Group`（Application）
**群聊：**
- `ChatMessage.Read.Chat`（Application）- 无需 @提及即可接收所有群聊消息
## 示例 Teams 清单（已脱敏）
包含必需字段的最小有效示例。请替换 ID 和 URL。
```json
{
"$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.23/MicrosoftTeams.schema.json",
"manifestVersion": "1.23",
"version": "1.0.0",
"id": "00000000-0000-0000-0000-000000000000",
"name": { "short": "OpenClaw" },
"developer": {
"name": "Your Org",
"websiteUrl": "https://example.com",
"privacyUrl": "https://example.com/privacy",
"termsOfUseUrl": "https://example.com/terms"
},
"description": { "short": "OpenClaw in Teams", "full": "OpenClaw in Teams" },
"icons": { "outline": "outline.png", "color": "color.png" },
"accentColor": "#5B6DEF",
"bots": [
{
"botId": "11111111-1111-1111-1111-111111111111",
"scopes": ["personal", "team", "groupChat"],
"isNotificationOnly": false,
"supportsCalling": false,
"supportsVideo": false,
"supportsFiles": true
}
],
"webApplicationInfo": {
"id": "11111111-1111-1111-1111-111111111111"
},
"authorization": {
"permissions": {
"resourceSpecific": [
{ "name": "ChannelMessage.Read.Group", "type": "Application" },
{ "name": "ChannelMessage.Send.Group", "type": "Application" },
{ "name": "Member.Read.Group", "type": "Application" },
{ "name": "Owner.Read.Group", "type": "Application" },
{ "name": "ChannelSettings.Read.Group", "type": "Application" },
{ "name": "TeamMember.Read.Group", "type": "Application" },
{ "name": "TeamSettings.Read.Group", "type": "Application" },
{ "name": "ChatMessage.Read.Chat", "type": "Application" }
]
}
}
}
```
### 清单注意事项（必需字段）
- `bots[].botId` **必须**与 Azure Bot App ID 匹配。
- `webApplicationInfo.id` **必须**与 Azure Bot App ID 匹配。
- `bots[].scopes` 必须包含你计划使用的范围（`personal`、`team`、`groupChat`）。
- `bots[].supportsFiles: true` 是个人范围文件处理所必需的。
- `authorization.permissions.resourceSpecific` 必须包含频道读取/发送权限（如果你需要频道流量）。
### 更新现有应用
要更新已安装的 Teams 应用（例如添加 RSC 权限）：
1. 使用新设置更新 `manifest.json`
2. **递增 `version` 字段**（例如 `1.0.0` → `1.1.0`）
3. **重新打包**清单和图标（`manifest.json`、`outline.png`、`color.png`）
4. 上传新的 zip：
- **方案 A（Teams 管理中心）：** Teams 管理中心 → Teams apps → Manage apps → 找到你的应用 → Upload new version
- **方案 B（旁加载）：** 在 Teams 中 → Apps → Manage your apps → Upload a custom app
5. **对于团队频道：** 在每个团队中重新安装应用以使新权限生效
6. **完全退出并重新启动 Teams**（不只是关闭窗口）以清除缓存的应用元数据
## 功能：仅 RSC vs Graph
### 仅使用 **Teams RSC**（已安装应用，无 Graph API 权限）
可用：
- 读取频道消息**文本**内容。
- 发送频道消息**文本**内容。
- 接收**个人（私信）**文件附件。
不可用：
- 频道/群组**图片或文件内容**（负载仅包含 HTML 占位符）。
- 下载存储在 SharePoint/OneDrive 中的附件。
- 读取消息历史（超出实时 webhook 事件范围）。
### 使用 **Teams RSC + Microsoft Graph Application 权限**
新增：
- 下载托管内容（粘贴到消息中的图片）。
- 下载存储在 SharePoint/OneDrive 中的文件附件。
- 通过 Graph 读取频道/聊天消息历史。
### RSC vs Graph API
| 功能 | RSC 权限 | Graph API |
| -------------- | ------------------ | --------------------------- |
| **实时消息** | 是（通过 webhook） | 否（仅轮询） |
| **历史消息** | 否 | 是（可查询历史） |
| **设置复杂度** | 仅需应用清单 | 需要管理员同意 + token 流程 |
| **离线可用** | 否（必须运行中） | 是（可随时查询） |
**总结：** RSC 用于实时监听；Graph API 用于历史访问。要补上离线期间错过的消息，你需要具有 `ChannelMessage.Read.All` 的 Graph API（需要管理员同意）。
## 启用 Graph 的媒体 + 历史（频道所必需）
如果你需要**频道**中的图片/文件或想获取**消息历史**，必须启用 Microsoft Graph 权限并授予管理员同意。
1. 在 Entra ID（Azure AD）**应用注册**中，添加 Microsoft Graph **Application 权限**：
- `ChannelMessage.Read.All`（频道附件 + 历史）
- `Chat.Read.All` 或 `ChatMessage.Read.All`（群聊）
2. 为租户**授予管理员同意**。
3. 递增 Teams 应用**清单版本**，重新上传，并在 **Teams 中重新安装应用**。
4. **完全退出并重新启动 Teams** 以清除缓存的应用元数据。
## 已知限制
### Webhook 超时
Teams 通过 HTTP webhook 投递消息。如果处理时间过长（例如 LLM 响应缓慢），你可能会看到：
- Gateway 超时
- Teams 重试消息（导致重复）
- 回复丢失
OpenClaw 通过快速返回并主动发送回复来处理此问题，但非常慢的响应仍可能导致问题。
### 格式
Teams markdown 比 Slack 或 Discord 更有限：
- 基本格式有效：**粗体**、_斜体_、`代码`、链接
- 复杂 markdown（表格、嵌套列表）可能无法正确渲染
- 支持 Adaptive Cards 用于投票和任意卡片发送（见下方）
## 配置
关键设置（共享渠道模式请参见 `/gateway/configuration`）：
- `channels.msteams.enabled`：启用/禁用渠道。
- `channels.msteams.appId`、`channels.msteams.appPassword`、`channels.msteams.tenantId`：机器人凭据。
- `channels.msteams.webhook.port`（默认 `3978`）
- `channels.msteams.webhook.path`（默认 `/api/messages`）
- `channels.msteams.dmPolicy`：`pairing | allowlist | open | disabled`（默认：pairing）
- `channels.msteams.allowFrom`：私信允许列表（AAD 对象 ID、UPN 或显示名称）。当 Graph 访问可用时，向导在设置期间将名称解析为 ID。
- `channels.msteams.textChunkLimit`：出站文本分块大小。
- `channels.msteams.chunkMode`：`length`（默认）或 `newline`，在按长度分块之前按空行（段落边界）分割。
- `channels.msteams.mediaAllowHosts`：入站附件主机允许列表（默认为 Microsoft/Teams 域名）。
- `channels.msteams.requireMention`：在频道/群组中需要 @提及（默认 true）。
- `channels.msteams.replyStyle`：`thread | top-level`（参见[回复样式：线程 vs 帖子](#回复样式线程-vs-帖子)）。
- `channels.msteams.teams.<teamId>.replyStyle`：按团队覆盖。
- `channels.msteams.teams.<teamId>.requireMention`：按团队覆盖。
- `channels.msteams.teams.<teamId>.tools`：按团队默认工具策略覆盖（`allow`/`deny`/`alsoAllow`），在频道覆盖缺失时使用。
- `channels.msteams.teams.<teamId>.toolsBySender`：按团队按发送者工具策略覆盖（支持 `"*"` 通配符）。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle`：按频道覆盖。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention`：按频道覆盖。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.tools`：按频道工具策略覆盖（`allow`/`deny`/`alsoAllow`）。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender`：按频道按发送者工具策略覆盖（支持 `"*"` 通配符）。
- `channels.msteams.sharePointSiteId`：用于群聊/频道文件上传的 SharePoint 站点 ID（参见[在群聊中发送文件](#在群聊中发送文件)）。
## 路由与会话
- 会话键遵循标准智能体格式（参见 [/concepts/session](/concepts/session)）：
- 私信共享主会话（`agent:<agentId>:<mainKey>`）。
- 频道/群组消息使用会话 ID：
- `agent:<agentId>:msteams:channel:<conversationId>`
- `agent:<agentId>:msteams:group:<conversationId>`
## 回复样式：线程 vs 帖子
Teams 最近在相同的底层数据模型上引入了两种频道 UI 样式：
| 样式 | 描述 | 推荐的 `replyStyle` |
| ----------------------- | ------------------------------ | ------------------- |
| **Posts**（经典） | 消息显示为卡片，下方有线程回复 | `thread`（默认） |
| **Threads**（类 Slack） | 消息线性排列，更像 Slack | `top-level` |
**问题：** Teams API 不暴露频道使用哪种 UI 样式。如果你使用了错误的 `replyStyle`：
- 在 Threads 样式的频道中使用 `thread` → 回复嵌套显示不自然
- 在 Posts 样式的频道中使用 `top-level` → 回复显示为独立的顶级帖子而非在线程中
**解决方案：** 根据频道的设置方式按频道配置 `replyStyle`：
```json
{
"msteams": {
"replyStyle": "thread",
"teams": {
"19:abc...@thread.tacv2": {
"channels": {
"19:xyz...@thread.tacv2": {
"replyStyle": "top-level"
}
}
}
}
}
}
```
## 附件与图片
**当前限制：**
- **私信：** 图片和文件附件通过 Teams bot 文件 API 可用。
- **频道/群组：** 附件存储在 M365 存储（SharePoint/OneDrive）中。Webhook 负载仅包含 HTML 占位符，而非实际文件字节。**需要 Graph API 权限**才能下载频道附件。
没有 Graph 权限时，包含图片的频道消息将仅作为纯文本接收（机器人无法访问图片内容）。默认情况下，OpenClaw 仅从 Microsoft/Teams 主机名下载媒体。通过 `channels.msteams.mediaAllowHosts` 覆盖（使用 `["*"]` 允许任何主机）。
## 在群聊中发送文件
机器人可以使用 FileConsentCard 流程在私信中发送文件（内置）。然而，**在群聊/频道中发送文件**需要额外设置：
| 场景 | 文件发送方式 | 所需设置 |
| -------------------- | --------------------------------------- | ------------------------------------ |
| **私信** | FileConsentCard → 用户接受 → 机器人上传 | 开箱即用 |
| **群聊/频道** | 上传到 SharePoint → 分享链接 | 需要 `sharePointSiteId` + Graph 权限 |
| **图片（任何场景）** | Base64 编码内联 | 开箱即用 |
### 为什么群聊需要 SharePoint
机器人没有个人 OneDrive 驱动器（`/me/drive` Graph API 端点对应用程序标识不可用）。要在群聊/频道中发送文件，机器人上传到 **SharePoint 站点**并创建共享链接。
### 设置
1. 在 Entra ID（Azure AD）→ 应用注册中**添加 Graph API 权限**：
- `Sites.ReadWrite.All`（Application）- 上传文件到 SharePoint
- `Chat.Read.All`（Application）- 可选，启用按用户共享链接
2. 为租户**授予管理员同意**。
3. **获取你的 SharePoint 站点 ID：**
```bash
# 通过 Graph Explorer 或使用有效 token 的 curl：
curl -H "Authorization: Bearer $TOKEN" \
"https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path}"
# 示例：对于 "contoso.sharepoint.com/sites/BotFiles" 的站点
curl -H "Authorization: Bearer $TOKEN" \
"https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/BotFiles"
# 响应包含："id": "contoso.sharepoint.com,guid1,guid2"
```
4. **配置 OpenClaw：**
```json5
{
channels: {
msteams: {
// ... 其他配置 ...
sharePointSiteId: "contoso.sharepoint.com,guid1,guid2",
},
},
}
```
### 共享行为
| 权限 | 共享行为 |
| --------------------------------------- | ------------------------------------------ |
| 仅 `Sites.ReadWrite.All` | 组织范围共享链接（组织中的任何人都可访问） |
| `Sites.ReadWrite.All` + `Chat.Read.All` | 按用户共享链接（仅聊天成员可访问） |
按用户共享更安全，因为只有聊天参与者可以访问文件。如果缺少 `Chat.Read.All` 权限，机器人回退到组织范围共享。
### 回退行为
| 场景 | 结果 |
| --------------------------------------- | ------------------------------------------ |
| 群聊 + 文件 + 已配置 `sharePointSiteId` | 上传到 SharePoint，发送共享链接 |
| 群聊 + 文件 + 未配置 `sharePointSiteId` | 尝试 OneDrive 上传（可能失败），仅发送文本 |
| 个人聊天 + 文件 | FileConsentCard 流程（无需 SharePoint） |
| 任何场景 + 图片 | Base64 编码内联（无需 SharePoint） |
### 文件存储位置
上传的文件存储在已配置 SharePoint 站点默认文档库中的 `/OpenClawShared/` 文件夹。
## 投票（Adaptive Cards）
OpenClaw 通过 Adaptive Cards 发送 Teams 投票（没有原生 Teams 投票 API）。
- CLI：`openclaw message poll --channel msteams --target conversation:<id> ...`
- 投票由 Gateway 记录在 `~/.openclaw/msteams-polls.json` 中。
- Gateway 必须保持在线以记录投票。
- 投票尚不会自动发布结果摘要（如需要请查看存储文件）。
## Adaptive Cards（任意）
使用 `message` 工具或 CLI 向 Teams 用户或会话发送任意 Adaptive Card JSON。
`card` 参数接受 Adaptive Card JSON 对象。提供 `card` 时，消息文本是可选的。
**智能体工具：**
```json
{
"action": "send",
"channel": "msteams",
"target": "user:<id>",
"card": {
"type": "AdaptiveCard",
"version": "1.5",
"body": [{ "type": "TextBlock", "text": "Hello!" }]
}
}
```
**CLI：**
```bash
openclaw message send --channel msteams \
--target "conversation:19:abc...@thread.tacv2" \
--card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello!"}]}'
```
卡片 schema 和示例请参见 [Adaptive Cards 文档](https://adaptivecards.io/)。目标格式详情请参见下方[目标格式](#目标格式)。
## 目标格式
Microsoft Teams 目标使用前缀区分用户和会话：
| 目标类型 | 格式 | 示例 |
| ----------------- | -------------------------------- | ------------------------------------------------- |
| 用户（按 ID） | `user:<aad-object-id>` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` |
| 用户（按名称） | `user:<display-name>` | `user:John Smith`（需要 Graph API） |
| 群组/频道 | `conversation:<conversation-id>` | `conversation:19:abc123...@thread.tacv2` |
| 群组/频道（原始） | `<conversation-id>` | `19:abc123...@thread.tacv2`（如果包含 `@thread`） |
**CLI 示例：**
```bash
# 按 ID 发送给用户
openclaw message send --channel msteams --target "user:40a1a0ed-..." --message "Hello"
# 按显示名称发送给用户（触发 Graph API 查找）
openclaw message send --channel msteams --target "user:John Smith" --message "Hello"
# 发送到群聊或频道
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" --message "Hello"
# 向会话发送 Adaptive Card
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" \
--card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello"}]}'
```
**智能体工具示例：**
```json
{
"action": "send",
"channel": "msteams",
"target": "user:John Smith",
"message": "Hello!"
}
```
```json
{
"action": "send",
"channel": "msteams",
"target": "conversation:19:abc...@thread.tacv2",
"card": {
"type": "AdaptiveCard",
"version": "1.5",
"body": [{ "type": "TextBlock", "text": "Hello" }]
}
}
```
注意：不带 `user:` 前缀时，名称默认解析为群组/团队。通过显示名称定位人员时请始终使用 `user:`。
## 主动消息
- 主动消息仅在用户**已交互后**才可能，因为我们在那个时候存储会话引用。
- `dmPolicy` 和允许列表门控请参见 `/gateway/configuration`。
## 团队和频道 ID（常见陷阱）
Teams URL 中的 `groupId` 查询参数**不是**用于配置的团队 ID。请从 URL 路径中提取 ID：
**团队 URL：**
```
https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=...
└────────────────────────────┘
团队 ID（URL 解码此部分）
```
**频道 URL：**
```
https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=...
└─────────────────────────┘
频道 ID（URL 解码此部分）
```
**用于配置：**
- 团队 ID = `/team/` 后的路径段（URL 解码后，例如 `19:Bk4j...@thread.tacv2`）
- 频道 ID = `/channel/` 后的路径段（URL 解码后）
- **忽略** `groupId` 查询参数
## 私有频道
机器人在私有频道中的支持有限：
| 功能 | 标准频道 | 私有频道 |
| ------------------- | -------- | ---------------- |
| 机器人安装 | 是 | 有限 |
| 实时消息（webhook） | 是 | 可能不可用 |
| RSC 权限 | 是 | 行为可能不同 |
| @提及 | 是 | 如果机器人可访问 |
| Graph API 历史 | 是 | 是（需要权限） |
**私有频道不可用时的变通方案：**
1. 使用标准频道进行机器人交互
2. 使用私信 - 用户始终可以直接给机器人发消息
3. 使用 Graph API 进行历史访问（需要 `ChannelMessage.Read.All`）
## 故障排除
### 常见问题
- **频道中图片不显示：** Graph 权限或管理员同意缺失。重新安装 Teams 应用并完全退出/重新打开 Teams。
- **频道中没有响应：** 默认需要提及；设置 `channels.msteams.requireMention=false` 或按团队/频道配置。
- **版本不匹配（Teams 仍显示旧清单）：** 移除并重新添加应用，完全退出 Teams 以刷新。
- **Webhook 返回 401 Unauthorized：** 在没有 Azure JWT 的情况下手动测试时这是预期的 - 表示端点可达但认证失败。使用 Azure Web Chat 进行正确测试。
### 清单上传错误
- **"Icon file cannot be empty"：** 清单引用了 0 字节的图标文件。创建有效的 PNG 图标（`outline.png` 32x32，`color.png` 192x192）。
- **"webApplicationInfo.Id already in use"：** 应用仍安装在其他团队/聊天中。先找到并卸载它，或等待 5-10 分钟传播。
- **上传时显示"Something went wrong"：** 改为通过 https://admin.teams.microsoft.com 上传，打开浏览器 DevTools（F12）→ Network 标签页，检查响应体中的实际错误。
- **旁加载失败：** 尝试"Upload an app to your org's app catalog"而非"Upload a custom app" - 这通常可以绕过旁加载限制。
### RSC 权限不生效
1. 验证 `webApplicationInfo.id` 与你的机器人 App ID 完全匹配
2. 重新上传应用并在团队/聊天中重新安装
3. 检查你的组织管理员是否阻止了 RSC 权限
4. 确认你使用了正确的范围：`ChannelMessage.Read.Group` 用于团队，`ChatMessage.Read.Chat` 用于群聊
## 参考
- [创建 Azure Bot](https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration) - Azure Bot 设置指南
- [Teams 开发者门户](https://dev.teams.microsoft.com/apps) - 创建/管理 Teams 应用
- [Teams 应用清单 schema](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema)
- [使用 RSC 接收频道消息](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-messages-with-rsc)
- [RSC 权限参考](https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/rsc/resource-specific-consent)
- [Teams bot 文件处理](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4)（频道/群组需要 Graph）
- [主动消息](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages)

141
docs/zh-CN/channels/nextcloud-talk.md Normal file
View File

@@ -0,0 +1,141 @@
---
read_when:
- 开发 Nextcloud Talk 渠道功能
summary: Nextcloud Talk 支持状态、功能和配置
title: Nextcloud Talk
x-i18n:
generated_at: "2026-02-01T19:26:32Z"
model: claude-opus-4-5
provider: pi
source_hash: 21b7b9756c4356a76dc0f14c10e44ed74a284cf3badf87e2df75eb88d8a90c31
source_path: channels/nextcloud-talk.md
workflow: 14
---
# 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）。

240
docs/zh-CN/channels/nostr.md Normal file
View File

@@ -0,0 +1,240 @@
---
read_when:
- 你想让 OpenClaw 通过 Nostr 接收私信
- 你正在设置去中心化消息
summary: 通过 NIP-04 加密消息的 Nostr 私信渠道
title: Nostr
x-i18n:
generated_at: "2026-02-01T19:26:55Z"
model: claude-opus-4-5
provider: pi
source_hash: 6b9fe4c74bf5e7c0f59bbaa129ec5270fd29a248551a8a9a7dde6cff8fb46111
source_path: channels/nostr.md
workflow: 14
---
# Nostr
**状态：** 可选插件（默认禁用）。
Nostr 是一个去中心化的社交网络协议。此渠道使 OpenClaw 能够通过 NIP-04 接收和回复加密私信（DM）。
## 安装（按需）
### 上手引导（推荐）
- 上手引导向导（`openclaw onboard`）和 `openclaw channels add` 会列出可选的渠道插件。
- 选择 Nostr 时会提示你按需安装插件。
安装默认行为：
- **开发渠道 + 可用 git 检出：** 使用本地插件路径。
- **稳定版/测试版：** 从 npm 下载。
你始终可以在提示中覆盖此选择。
### 手动安装
```bash
openclaw plugins install @openclaw/nostr
```
使用本地检出（开发工作流）：
```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` 事件发布。你可以从控制 UI（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 | 计划中 | Gift-wrapped 私信 |
| 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 gift-wrap）。

209
docs/zh-CN/channels/signal.md Normal file
View File

@@ -0,0 +1,209 @@
---
read_when:
- 设置 Signal 支持
- 调试 Signal 收发
summary: 通过 signal-cli（JSON-RPC + SSE）实现 Signal 支持、设置和号码模型
title: Signal
x-i18n:
generated_at: "2026-02-01T19:27:25Z"
model: claude-opus-4-5
provider: pi
source_hash: ca4de8b3685017f54a959e3e2699357ab40b3e4e68574bd7fb5739e4679e7d8a
source_path: channels/signal.md
workflow: 14
---
# Signal（signal-cli）
状态：外部 CLI 集成。Gateway 通过 HTTP JSON-RPC + SSE 与 `signal-cli` 通信。
## 快速设置（新手）
1. 为机器人使用一个**单独的 Signal 号码**（推荐）。
2. 安装 `signal-cli`（需要 Java）。
3. 链接机器人设备并启动守护进程：
- `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 账户**上运行机器人，它会忽略你自己的消息（循环保护）。
- 要实现"我给机器人发消息它回复我"，请使用一个**单独的机器人号码**。
## 设置（快速路径）
1. 安装 `signal-cli`（需要 Java）。
2. 链接机器人账户：
- `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`）以 `uuid:<id>` 形式存储在 `channels.signal.allowFrom` 中。
群组：
- `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/定时任务）
- 私信：`signal:+15551234567`（或纯 E.164）。
- UUID 私信：`uuid:<id>`（或裸 UUID）。
- 群组：`signal:group:<groupId>`。
- 用户名：`username:<name>`（如果你的 Signal 账户支持）。
## 配置参考（Signal）
完整配置：[配置](/gateway/configuration)
提供商选项：
- `channels.signal.enabled`：启用/禁用渠道启动。
- `channels.signal.account`：机器人账户的 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 标识。
- `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`。

530
docs/zh-CN/channels/slack.md Normal file
View File

@@ -0,0 +1,530 @@
---
read_when: 设置 Slack 或调试 Slack Socket/HTTP 模式
summary: Slack 的 Socket 或 HTTP webhook 模式设置
title: Slack
x-i18n:
generated_at: "2026-02-01T19:29:15Z"
model: claude-opus-4-5
provider: pi
source_hash: 703b4b4333bebfef26b64710ba452bdfc3e7d2115048d4e552e8659425b3609b
source_path: channels/slack.md
workflow: 14
---
# Slack
## Socket 模式（默认）
### 快速设置（新手）
1. 创建一个 Slack 应用并启用 **Socket Mode**。
2. 创建一个 **App Token**（`xapp-...`）和 **Bot Token**（`xoxb-...`）。
3. 为 OpenClaw 设置 token 并启动 Gateway。
最小配置：
```json5
{
channels: {
slack: {
enabled: true,
appToken: "xapp-...",
botToken: "xoxb-...",
},
},
}
```
### 设置
1. 在 https://api.slack.com/apps 创建 Slack 应用（从头开始）。
2. **Socket Mode** → 开启。然后进入 **Basic Information** → **App-Level Tokens** → **Generate Token and Scopes**，使用范围 `connections:write`。复制 **App Token**（`xapp-...`）。
3. **OAuth & Permissions** → 添加 bot token 范围（使用下方清单）。点击 **Install to Workspace**。复制 **Bot User OAuth Token**（`xoxb-...`）。
4. 可选：**OAuth & Permissions** → 添加 **User Token Scopes**（参见下方只读列表）。重新安装应用并复制 **User OAuth Token**（`xoxp-...`）。
5. **Event Subscriptions** → 启用事件并订阅：
- `message.*`（包括编辑/删除/线程广播）
- `app_mention`
- `reaction_added`、`reaction_removed`
- `member_joined_channel`、`member_left_channel`
- `channel_rename`
- `pin_added`、`pin_removed`
6. 邀请机器人加入你希望它读取的频道。
7. Slash Commands → 如果你使用 `channels.slack.slashCommand`，创建 `/openclaw`。如果你启用原生命令，为每个内置命令添加一个斜杠命令（名称与 `/help` 列表相同）。Slack 的原生命令默认关闭，除非你设置 `channels.slack.commands.native: true`（全局 `commands.native` 为 `"auto"`，Slack 下默认关闭）。
8. App Home → 启用 **Messages Tab** 以便用户可以给机器人发私信。
使用下方清单以保持范围和事件同步。
多账户支持：使用 `channels.slack.accounts`，每个账户配置独立 token 和可选的 `name`。共享模式请参阅 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts)。
### OpenClaw 配置（最小）
通过环境变量设置 token（推荐）：
- `SLACK_APP_TOKEN=xapp-...`
- `SLACK_BOT_TOKEN=xoxb-...`
或通过配置：
```json5
{
channels: {
slack: {
enabled: true,
appToken: "xapp-...",
botToken: "xoxb-...",
},
},
}
```
### 用户 token（可选）
OpenClaw 可以使用 Slack 用户 token（`xoxp-...`）进行读取操作（历史记录、置顶、回应、表情、成员信息）。默认保持只读：有用户 token 时读取操作优先使用它，写入仍使用 bot token，除非你明确选择。即使设置了 `userTokenReadOnly: false`，当 bot token 可用时写入操作仍优先使用它。
用户 token 在配置文件中设置（不支持环境变量）。多账户时设置 `channels.slack.accounts.<id>.userToken`。
同时使用 bot + app + user token 的示例：
```json5
{
channels: {
slack: {
enabled: true,
appToken: "xapp-...",
botToken: "xoxb-...",
userToken: "xoxp-...",
},
},
}
```
显式设置 userTokenReadOnly 的示例（允许用户 token 写入）：
```json5
{
channels: {
slack: {
enabled: true,
appToken: "xapp-...",
botToken: "xoxb-...",
userToken: "xoxp-...",
userTokenReadOnly: false,
},
},
}
```
#### Token 使用
- 读取操作（历史记录、回应列表、置顶列表、表情列表、成员信息、搜索）在配置了用户 token 时优先使用，否则使用 bot token。
- 写入操作（发送/编辑/删除消息、添加/移除回应、置顶/取消置顶、文件上传）默认使用 bot token。如果 `userTokenReadOnly: false` 且没有 bot token 可用，OpenClaw 回退到用户 token。
### 历史上下文
- `channels.slack.historyLimit`（或 `channels.slack.accounts.*.historyLimit`）控制多少条最近的频道/群组消息被包含在提示中。
- 回退到 `messages.groupChat.historyLimit`。设置 `0` 可禁用（默认 50）。
## HTTP 模式（Events API）
当你的 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`）。
5. **Interactivity & Shortcuts** → 启用并设置相同的 **Request URL**。
6. **Slash Commands** → 为你的命令设置相同的 **Request URL**。
示例请求 URL：
`https://gateway-host/slack/events`
### OpenClaw 配置（最小）
```json5
{
channels: {
slack: {
enabled: true,
mode: "http",
botToken: "xoxb-...",
signingSecret: "your-signing-secret",
webhookPath: "/slack/events",
},
},
}
```
多账户 HTTP 模式：设置 `channels.slack.accounts.<id>.mode = "http"` 并为每个账户提供唯一的 `webhookPath`，以便每个 Slack 应用可以指向自己的 URL。
### 清单（可选）
使用此 Slack 应用清单可快速创建应用（根据需要调整名称/命令）。如果你计划配置用户 token，请包含用户范围。
```json
{
"display_information": {
"name": "OpenClaw",
"description": "Slack connector for OpenClaw"
},
"features": {
"bot_user": {
"display_name": "OpenClaw",
"always_online": false
},
"app_home": {
"messages_tab_enabled": true,
"messages_tab_read_only_enabled": false
},
"slash_commands": [
{
"command": "/openclaw",
"description": "Send a message to OpenClaw",
"should_escape": false
}
]
},
"oauth_config": {
"scopes": {
"bot": [
"chat:write",
"channels:history",
"channels:read",
"groups:history",
"groups:read",
"groups:write",
"im:history",
"im:read",
"im:write",
"mpim:history",
"mpim:read",
"mpim:write",
"users:read",
"app_mentions:read",
"reactions:read",
"reactions:write",
"pins:read",
"pins:write",
"emoji:read",
"commands",
"files:read",
"files:write"
],
"user": [
"channels:history",
"channels:read",
"groups:history",
"groups:read",
"im:history",
"im:read",
"mpim:history",
"mpim:read",
"users:read",
"reactions:read",
"pins:read",
"emoji:read",
"search:read"
]
}
},
"settings": {
"socket_mode_enabled": true,
"event_subscriptions": {
"bot_events": [
"app_mention",
"message.channels",
"message.groups",
"message.im",
"message.mpim",
"reaction_added",
"reaction_removed",
"member_joined_channel",
"member_left_channel",
"channel_rename",
"pin_added",
"pin_removed"
]
}
}
}
```
如果你启用原生命令，为你想暴露的每个命令添加一个 `slash_commands` 条目（匹配 `/help` 列表）。通过 `channels.slack.commands.native` 覆盖。
## 范围（当前 vs 可选）
Slack 的 Conversations API 按类型设定范围：你只需要你实际使用的会话类型（channels、groups、im、mpim）对应的范围。概览请参见 https://docs.slack.dev/apis/web-api/using-the-conversations-api/。
### Bot token 范围（必需）
- `chat:write`（通过 `chat.postMessage` 发送/更新/删除消息）
https://docs.slack.dev/reference/methods/chat.postMessage
- `im:write`（通过 `conversations.open` 打开用户私信）
https://docs.slack.dev/reference/methods/conversations.open
- `channels:history`、`groups:history`、`im:history`、`mpim:history`
https://docs.slack.dev/reference/methods/conversations.history
- `channels:read`、`groups:read`、`im:read`、`mpim:read`
https://docs.slack.dev/reference/methods/conversations.info
- `users:read`（用户查找）
https://docs.slack.dev/reference/methods/users.info
- `reactions:read`、`reactions:write`（`reactions.get` / `reactions.add`）
https://docs.slack.dev/reference/methods/reactions.get
https://docs.slack.dev/reference/methods/reactions.add
- `pins:read`、`pins:write`（`pins.list` / `pins.add` / `pins.remove`）
https://docs.slack.dev/reference/scopes/pins.read
https://docs.slack.dev/reference/scopes/pins.write
- `emoji:read`（`emoji.list`）
https://docs.slack.dev/reference/scopes/emoji.read
- `files:write`（通过 `files.uploadV2` 上传）
https://docs.slack.dev/messaging/working-with-files/#upload
### 用户 token 范围（可选，默认只读）
如果你配置了 `channels.slack.userToken`，请在 **User Token Scopes** 下添加这些。
- `channels:history`、`groups:history`、`im:history`、`mpim:history`
- `channels:read`、`groups:read`、`im:read`、`mpim:read`
- `users:read`
- `reactions:read`
- `pins:read`
- `emoji:read`
- `search:read`
### 目前不需要（但未来可能）
- `mpim:write`（仅在我们添加群组私信打开/私信开始功能时需要，通过 `conversations.open`）
- `groups:write`（仅在我们添加私有频道管理时需要：创建/重命名/邀请/归档）
- `chat:write.public`（仅在我们想向机器人未加入的频道发帖时需要）
https://docs.slack.dev/reference/scopes/chat.write.public
- `users:read.email`（仅在我们需要从 `users.info` 获取邮箱字段时需要）
https://docs.slack.dev/changelog/2017-04-narrowing-email-access
- `files:read`（仅在我们开始列出/读取文件元数据时需要）
## 配置
Slack 仅使用 Socket Mode（无 HTTP webhook 服务器）。提供两个 token：
```json
{
"slack": {
"enabled": true,
"botToken": "xoxb-...",
"appToken": "xapp-...",
"groupPolicy": "allowlist",
"dm": {
"enabled": true,
"policy": "pairing",
"allowFrom": ["U123", "U456", "*"],
"groupEnabled": false,
"groupChannels": ["G123"],
"replyToMode": "all"
},
"channels": {
"C123": { "allow": true, "requireMention": true },
"#general": {
"allow": true,
"requireMention": true,
"users": ["U123"],
"skills": ["search", "docs"],
"systemPrompt": "Keep answers short."
}
},
"reactionNotifications": "own",
"reactionAllowlist": ["U123"],
"replyToMode": "off",
"actions": {
"reactions": true,
"messages": true,
"pins": true,
"memberInfo": true,
"emojiList": true
},
"slashCommand": {
"enabled": true,
"name": "openclaw",
"sessionPrefix": "slack:slash",
"ephemeral": true
},
"textChunkLimit": 4000,
"mediaMaxMb": 20
}
}
```
Token 也可以通过环境变量提供：
- `SLACK_BOT_TOKEN`
- `SLACK_APP_TOKEN`
确认回应由 `messages.ackReaction` + `messages.ackReactionScope` 全局控制。使用 `messages.removeAckAfterReply` 在机器人回复后清除确认回应。
## 限制
- 出站文本按 `channels.slack.textChunkLimit` 分块（默认 4000）。
- 可选的换行分块：设置 `channels.slack.chunkMode="newline"` 在按长度分块之前按空行（段落边界）分割。
- 媒体上传上限由 `channels.slack.mediaMaxMb` 限制（默认 20）。
## 回复线程
默认情况下，OpenClaw 在主频道中回复。使用 `channels.slack.replyToMode` 控制自动线程行为：
| 模式 | 行为 |
| ------- | ------------------------------------------------------------------------------------------------ |
| `off` | **默认。** 在主频道回复。仅在触发消息已在线程中时才在线程中回复。 |
| `first` | 第一条回复进入线程（在触发消息下方），后续回复进入主频道。适用于保持上下文可见同时避免线程杂乱。 |
| `all` | 所有回复都进入线程。保持对话集中但可能降低可见性。 |
该模式同时适用于自动回复和智能体工具调用（`slack sendMessage`）。
### 按聊天类型设置线程
你可以通过设置 `channels.slack.replyToModeByChatType` 为不同聊天类型配置不同的线程行为：
```json5
{
channels: {
slack: {
replyToMode: "off", // 频道默认
replyToModeByChatType: {
direct: "all", // 私信始终使用线程
group: "first", // 群组私信/MPIM 第一条回复使用线程
},
},
},
}
```
支持的聊天类型：
- `direct`：一对一私信（Slack `im`）
- `group`：群组私信 / MPIM（Slack `mpim`）
- `channel`：标准频道（公共/私有）
优先级：
1. `replyToModeByChatType.<chatType>`
2. `replyToMode`
3. 提供商默认值（`off`）
旧版 `channels.slack.dm.replyToMode` 在未设置聊天类型覆盖时仍作为 `direct` 的回退值。
示例：
仅私信使用线程：
```json5
{
channels: {
slack: {
replyToMode: "off",
replyToModeByChatType: { direct: "all" },
},
},
}
```
群组私信使用线程但频道保持在根级：
```json5
{
channels: {
slack: {
replyToMode: "off",
replyToModeByChatType: { group: "first" },
},
},
}
```
频道使用线程，私信保持在根级：
```json5
{
channels: {
slack: {
replyToMode: "first",
replyToModeByChatType: { direct: "off", group: "off" },
},
},
}
```
### 手动线程标签
对于精细控制，在智能体回复中使用以下标签：
- `[[reply_to_current]]` — 回复触发消息（开始/继续线程）。
- `[[reply_to:<id>]]` — 回复特定消息 ID。
## 会话 + 路由
- 私信共享 `main` 会话（与 WhatsApp/Telegram 类似）。
- 频道映射到 `agent:<agentId>:slack:channel:<channelId>` 会话。
- 斜杠命令使用 `agent:<agentId>:slack:slash:<userId>` 会话（前缀可通过 `channels.slack.slashCommand.sessionPrefix` 配置）。
- 如果 Slack 不提供 `channel_type`，OpenClaw 从频道 ID 前缀（`D`、`C`、`G`）推断并默认为 `channel` 以保持会话键稳定。
- 原生命令注册使用 `commands.native`（全局默认 `"auto"` → Slack 关闭），可通过 `channels.slack.commands.native` 按工作区覆盖。文本命令需要独立的 `/...` 消息，可通过 `commands.text: false` 禁用。Slack 斜杠命令在 Slack 应用中管理，不会自动移除。使用 `commands.useAccessGroups: false` 可绕过命令的访问组检查。
- 完整命令列表 + 配置：[斜杠命令](/tools/slash-commands)
## 私信安全（配对）
- 默认：`channels.slack.dm.policy="pairing"` — 未知私信发送者会收到配对码（1 小时后过期）。
- 通过 `openclaw pairing approve slack <code>` 批准。
- 要允许任何人：设置 `channels.slack.dm.policy="open"` 和 `channels.slack.dm.allowFrom=["*"]`。
- `channels.slack.dm.allowFrom` 接受用户 ID、@用户名或邮箱（启动时当 token 允许时解析）。向导在设置期间当 token 允许时接受用户名并将其解析为 ID。
## 群组策略
- `channels.slack.groupPolicy` 控制频道处理方式（`open|disabled|allowlist`）。
- `allowlist` 需要频道列在 `channels.slack.channels` 中。
- 如果你只设置了 `SLACK_BOT_TOKEN`/`SLACK_APP_TOKEN` 且从未创建 `channels.slack` 部分，运行时默认将 `groupPolicy` 设为 `open`。添加 `channels.slack.groupPolicy`、`channels.defaults.groupPolicy` 或频道允许列表来锁定它。
- 配置向导接受 `#channel` 名称并在可能时将其解析为 ID（公共 + 私有）；如果存在多个匹配，优先选择活跃频道。
- 启动时，OpenClaw 将允许列表中的频道/用户名称解析为 ID（当 token 允许时）并记录映射；未解析的条目保持原样。
- 要**不允许任何频道**，设置 `channels.slack.groupPolicy: "disabled"`（或保持空的允许列表）。
频道选项（`channels.slack.channels.<id>` 或 `channels.slack.channels.<name>`）：
- `allow`：当 `groupPolicy="allowlist"` 时允许/拒绝频道。
- `requireMention`：频道的提及门控。
- `tools`：可选的按频道工具策略覆盖（`allow`/`deny`/`alsoAllow`）。
- `toolsBySender`：可选的频道内按发送者工具策略覆盖（键为发送者 ID/@用户名/邮箱；支持 `"*"` 通配符）。
- `allowBots`：允许此频道中机器人发送的消息（默认：false）。
- `users`：可选的按频道用户允许列表。
- `skills`：技能过滤器（省略 = 所有技能，空 = 无）。
- `systemPrompt`：频道的额外系统提示（与主题/目的合并）。
- `enabled`：设置 `false` 可禁用频道。
## 投递目标
在定时任务/CLI 发送中使用：
- `user:<id>` 用于私信
- `channel:<id>` 用于频道
## 工具操作
Slack 工具操作可通过 `channels.slack.actions.*` 控制：
| 操作组 | 默认值 | 说明 |
| ---------- | ------ | ------------------- |
| reactions | 启用 | 添加回应 + 列出回应 |
| messages | 启用 | 读取/发送/编辑/删除 |
| pins | 启用 | 置顶/取消置顶/列出 |
| memberInfo | 启用 | 成员信息 |
| emojiList | 启用 | 自定义表情列表 |
## 安全注意事项
- 写入操作默认使用 bot token，以便状态变更操作保持在应用机器人权限和身份范围内。
- 设置 `userTokenReadOnly: false` 允许在 bot token 不可用时使用用户 token 进行写入操作，这意味着操作以安装用户的访问权限运行。请将用户 token 视为高权限凭据，并严格设置操作门控和允许列表。
- 如果你启用用户 token 写入，请确保用户 token 包含你预期的写入范围（`chat:write`、`reactions:write`、`pins:write`、`files:write`），否则这些操作会失败。
## 注意事项
- 提及门控通过 `channels.slack.channels` 控制（将 `requireMention` 设为 `true`）；`agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）也算作提及。
- 多智能体覆盖：在 `agents.list[].groupChat.mentionPatterns` 上设置每个智能体的模式。
- 回应通知遵循 `channels.slack.reactionNotifications`（使用 `reactionAllowlist` 配合 `allowlist` 模式）。
- 机器人发送的消息默认被忽略；通过 `channels.slack.allowBots` 或 `channels.slack.channels.<id>.allowBots` 启用。
- 警告：如果你允许回复其他机器人（`channels.slack.allowBots=true` 或 `channels.slack.channels.<id>.allowBots=true`），请使用 `requireMention`、`channels.slack.channels.<id>.users` 允许列表和/或在 `AGENTS.md` 和 `SOUL.md` 中设置明确的防护规则来防止机器人之间的回复循环。
- Slack 工具的回应移除语义请参见 [/tools/reactions](/tools/reactions)。
- 在权限允许且未超过大小限制时，附件会被下载到媒体存储。

755
docs/zh-CN/channels/telegram.md Normal file
View File

@@ -0,0 +1,755 @@
---
read_when:
- 开发 Telegram 功能或 webhook 时
summary: Telegram 机器人支持状态、功能与配置
title: Telegram
x-i18n:
generated_at: "2026-02-01T19:54:11Z"
model: claude-opus-4-5
provider: pi
source_hash: 63198fce8c29a1020590d6a3ca142314b30c35d50317b878bf1fb1bfd8d54747
source_path: channels/telegram.md
workflow: 14
---
# Telegram (Bot API)
状态：通过 grammY 实现的机器人私聊 + 群组功能已可用于生产环境。默认使用长轮询；webhook 可选。
## 快速设置（新手）
1. 通过 **@BotFather**（[直达链接](https://t.me/BotFather)）创建机器人。确认用户名确实是 `@BotFather`，然后复制令牌。
2. 设置令牌：
- 环境变量：`TELEGRAM_BOT_TOKEN=...`
- 或配置：`channels.telegram.botToken: "..."`。
- 如果两者都设置了，配置优先（环境变量回退仅适用于默认账户）。
3. 启动 Gateway。
4. 私聊访问默认为配对模式；首次联系时需批准配对码。
最小配置：
```json5
{
channels: {
telegram: {
enabled: true,
botToken: "123:abc",
dmPolicy: "pairing",
},
},
}
```
## 简介
- 由 Gateway 管理的 Telegram Bot API 渠道。
- 确定性路由：回复始终发回 Telegram；模型不会选择渠道。
- 私聊共享智能体的主会话；群组保持隔离（`agent:<agentId>:telegram:group:<chatId>`）。
## 设置（快速路径）
### 1）创建机器人令牌（BotFather）
1. 打开 Telegram，与 **@BotFather**（[直达链接](https://t.me/BotFather)）对话。确认用户名确实是 `@BotFather`。
2. 运行 `/newbot`，然后按提示操作（名称 + 以 `bot` 结尾的用户名）。
3. 复制令牌并安全保存。
可选的 BotFather 设置：
- `/setjoingroups` — 允许/禁止将机器人添加到群组。
- `/setprivacy` — 控制机器人是否能看到所有群组消息。
### 2）配置令牌（环境变量或配置）
示例：
```json5
{
channels: {
telegram: {
enabled: true,
botToken: "123:abc",
dmPolicy: "pairing",
groups: { "*": { requireMention: true } },
},
},
}
```
环境变量选项：`TELEGRAM_BOT_TOKEN=...`（适用于默认账户）。
如果环境变量和配置都设置了，配置优先。
多账户支持：使用 `channels.telegram.accounts`，为每个账户设置令牌和可选的 `name`。请参阅 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) 了解通用模式。
3. 启动 Gateway。当令牌被解析后（配置优先，环境变量回退），Telegram 即启动。
4. 私聊访问默认为配对模式。机器人首次被联系时需批准配对码。
5. 对于群组：添加机器人，决定隐私/管理员行为（见下文），然后设置 `channels.telegram.groups` 来控制提及门控 + 白名单。
## 令牌 + 隐私 + 权限（Telegram 端）
### 令牌创建（BotFather）
- `/newbot` 创建机器人并返回令牌（请保密）。
- 如果令牌泄露，通过 @BotFather 撤销/重新生成令牌并更新配置。
### 群组消息可见性（隐私模式）
Telegram 机器人默认启用**隐私模式**，这会限制它们能接收到的群组消息。
如果你的机器人必须看到*所有*群组消息，有两种选择：
- 使用 `/setprivacy` 禁用隐私模式，**或者**
- 将机器人设为群组**管理员**（管理员机器人可以接收所有消息）。
**注意：** 切换隐私模式后，Telegram 要求将机器人从每个群组中移除并重新添加，
更改才能生效。
### 群组权限（管理员权限）
管理员状态在群组内设置（Telegram 界面）。管理员机器人始终能接收所有
群组消息，因此如果需要完全可见性，请使用管理员身份。
## 工作原理（行为）
- 入站消息被规范化为共享渠道信封，包含回复上下文和媒体占位符。
- 群组回复默认需要提及（原生 @提及或 `agents.list[].groupChat.mentionPatterns` / `messages.groupChat.mentionPatterns`）。
- 多智能体覆盖：在 `agents.list[].groupChat.mentionPatterns` 上设置每个智能体的模式。
- 回复始终路由回同一个 Telegram 聊天。
- 长轮询使用 grammY runner，按聊天排序；总体并发受 `agents.defaults.maxConcurrent` 限制。
- Telegram Bot API 不支持已读回执；没有 `sendReadReceipts` 选项。
## 草稿流式传输
OpenClaw 可以使用 `sendMessageDraft` 在 Telegram 私聊中流式传输部分回复。
要求：
- 在 @BotFather 中为机器人启用话题模式（论坛话题模式）。
- 仅限私聊话题（Telegram 在入站消息中包含 `message_thread_id`）。
- `channels.telegram.streamMode` 未设为 `"off"`（默认：`"partial"`，`"block"` 启用分块草稿更新）。
草稿流式传输仅适用于私聊；Telegram 在群组或频道中不支持此功能。
## 格式化（Telegram HTML）
- 出站 Telegram 文本使用 `parse_mode: "HTML"`（Telegram 支持的标签子集）。
- 类 Markdown 输入被渲染为 **Telegram 安全的 HTML**（粗体/斜体/删除线/代码/链接）；块级元素被扁平化为带换行符/项目符号的文本。
- 来自模型的原始 HTML 会被转义，以避免 Telegram 解析错误。
- 如果 Telegram 拒绝 HTML 负载，OpenClaw 会以纯文本重试同一条消息。
## 命令（原生 + 自定义）
OpenClaw 在启动时将原生命令（如 `/status`、`/reset`、`/model`）注册到 Telegram 的机器人菜单。
你可以通过配置向菜单添加自定义命令：
```json5
{
channels: {
telegram: {
customCommands: [
{ command: "backup", description: "Git backup" },
{ command: "generate", description: "Create an image" },
],
},
},
}
```
## 故障排除
- 日志中出现 `setMyCommands failed` 通常意味着到 `api.telegram.org` 的出站 HTTPS/DNS 被阻止。
- 如果看到 `sendMessage` 或 `sendChatAction` 失败，请检查 IPv6 路由和 DNS。
更多帮助：[渠道故障排除](/channels/troubleshooting)。
注意：
- 自定义命令**仅为菜单条目**；除非你在其他地方处理它们，否则 OpenClaw 不会实现它们。
- 命令名称会被规范化（去除前导 `/`，转为小写），且必须匹配 `a-z`、`0-9`、`_`（1–32 个字符）。
- 自定义命令**不能覆盖原生命令**。冲突会被忽略并记录到日志。
- 如果 `commands.native` 被禁用，则只注册自定义命令（如果没有自定义命令则清空）。
## 限制
- 出站文本按 `channels.telegram.textChunkLimit` 分块（默认 4000）。
- 可选的换行分块：设置 `channels.telegram.chunkMode="newline"` 以在空行（段落边界）处拆分，然后再按长度分块。
- 媒体下载/上传受 `channels.telegram.mediaMaxMb` 限制（默认 5）。
- Telegram Bot API 请求在 `channels.telegram.timeoutSeconds` 后超时（通过 grammY 默认 500）。设置更低的值以避免长时间挂起。
- 群组历史上下文使用 `channels.telegram.historyLimit`（或 `channels.telegram.accounts.*.historyLimit`），回退到 `messages.groupChat.historyLimit`。设为 `0` 以禁用（默认 50）。
- 私聊历史可通过 `channels.telegram.dmHistoryLimit`（用户轮次）限制。按用户覆盖：`channels.telegram.dms["<user_id>"].historyLimit`。
## 群组激活模式
默认情况下，机器人在群组中只响应提及（`@botname` 或 `agents.list[].groupChat.mentionPatterns` 中的模式）。要更改此行为：
### 通过配置（推荐）
```json5
{
channels: {
telegram: {
groups: {
"-1001234567890": { requireMention: false }, // 在此群组中始终回复
},
},
},
}
```
**重要：** 设置 `channels.telegram.groups` 会创建一个**白名单** - 只有列出的群组（或 `"*"`）会被接受。
论坛话题继承其父群组配置（allowFrom、requireMention、skills、prompts），除非你在 `channels.telegram.groups.<groupId>.topics.<topicId>` 下添加每个话题的覆盖。
允许所有群组且始终回复：
```json5
{
channels: {
telegram: {
groups: {
"*": { requireMention: false }, // 所有群组，始终回复
},
},
},
}
```
保持所有群组仅提及时回复（默认行为）：
```json5
{
channels: {
telegram: {
groups: {
"*": { requireMention: true }, // 或完全省略 groups
},
},
},
}
```
### 通过命令（会话级别）
在群组中发送：
- `/activation always` - 回复所有消息
- `/activation mention` - 需要提及（默认）
**注意：** 命令仅更新会话状态。要在重启后保持行为，请使用配置。
### 获取群组聊天 ID
将群组中的任意消息转发给 Telegram 上的 `@userinfobot` 或 `@getidsbot`，即可看到聊天 ID（负数，如 `-1001234567890`）。
**提示：** 要获取你自己的用户 ID，私聊机器人，它会回复你的用户 ID（配对消息），或者在命令启用后使用 `/whoami`。
**隐私提示：** `@userinfobot` 是第三方机器人。如果你更注重隐私，可以将机器人添加到群组，发送一条消息，然后使用 `openclaw logs --follow` 读取 `chat.id`，或使用 Bot API 的 `getUpdates`。
## 配置写入
默认情况下，Telegram 允许写入由渠道事件或 `/config set|unset` 触发的配置更新。
以下情况会发生配置写入：
- 群组升级为超级群组时，Telegram 发出 `migrate_to_chat_id`（聊天 ID 变更）。OpenClaw 可以自动迁移 `channels.telegram.groups`。
- 你在 Telegram 聊天中运行 `/config set` 或 `/config unset`（需要 `commands.config: true`）。
禁用方式：
```json5
{
channels: { telegram: { configWrites: false } },
}
```
## 话题（论坛超级群组）
Telegram 论坛话题在每条消息中包含 `message_thread_id`。OpenClaw：
- 将 `:topic:<threadId>` 追加到 Telegram 群组会话键，使每个话题相互隔离。
- 发送输入指示器和回复时携带 `message_thread_id`，确保回复留在话题内。
- 通用话题（thread id `1`）比较特殊：消息发送时省略 `message_thread_id`（Telegram 会拒绝），但输入指示器仍包含它。
- 在模板上下文中暴露 `MessageThreadId` + `IsForum`，用于路由/模板。
- 话题级配置可在 `channels.telegram.groups.<chatId>.topics.<threadId>` 下设置（skills、白名单、自动回复、系统提示词、禁用）。
- 话题配置继承群组设置（requireMention、白名单、skills、提示词、enabled），除非按话题覆盖。
私聊在某些边缘情况下可能包含 `message_thread_id`。OpenClaw 保持私聊会话键不变，但在存在 thread id 时仍将其用于回复/草稿流式传输。
## 内联按钮
Telegram 支持带回调按钮的内联键盘。
```json5
{
channels: {
telegram: {
capabilities: {
inlineButtons: "allowlist",
},
},
},
}
```
按账户配置：
```json5
{
channels: {
telegram: {
accounts: {
main: {
capabilities: {
inlineButtons: "allowlist",
},
},
},
},
},
}
```
作用域：
- `off` — 禁用内联按钮
- `dm` — 仅私聊（群组目标被阻止）
- `group` — 仅群组（私聊目标被阻止）
- `all` — 私聊 + 群组
- `allowlist` — 私聊 + 群组，但仅限 `allowFrom`/`groupAllowFrom` 允许的发送者（与控制命令规则相同）
默认值：`allowlist`。
旧版：`capabilities: ["inlineButtons"]` = `inlineButtons: "all"`。
### 发送按钮
使用消息工具的 `buttons` 参数：
```json5
{
action: "send",
channel: "telegram",
to: "123456789",
message: "Choose an option:",
buttons: [
[
{ text: "Yes", callback_data: "yes" },
{ text: "No", callback_data: "no" },
],
[{ text: "Cancel", callback_data: "cancel" }],
],
}
```
当用户点击按钮时，回调数据会以以下格式作为消息发送回智能体：
`callback_data: value`
### 配置选项
Telegram 功能可在两个层级配置（上面展示了对象形式；旧版字符串数组仍受支持）：
- `channels.telegram.capabilities`：全局默认功能配置，应用于所有 Telegram 账户，除非被覆盖。
- `channels.telegram.accounts.<account>.capabilities`：按账户的功能配置，覆盖该账户的全局默认值。
当所有 Telegram 机器人/账户应具有相同行为时，使用全局设置。当不同机器人需要不同行为时，使用按账户配置（例如，一个账户只处理私聊，另一个允许在群组中使用）。
## 访问控制（私聊 + 群组）
### 私聊访问
- 默认：`channels.telegram.dmPolicy = "pairing"`。未知发送者会收到配对码；消息在批准前被忽略（配对码 1 小时后过期）。
- 批准方式：
- `openclaw pairing list telegram`
- `openclaw pairing approve telegram <CODE>`
- 配对是 Telegram 私聊使用的默认令牌交换方式。详情：[配对](/start/pairing)
- `channels.telegram.allowFrom` 接受数字用户 ID（推荐）或 `@username` 条目。这**不是**机器人用户名；请使用人类发送者的 ID。向导接受 `@username` 并在可能时将其解析为数字 ID。
#### 查找你的 Telegram 用户 ID
更安全的方式（无需第三方机器人）：
1. 启动 Gateway 并私聊你的机器人。
2. 运行 `openclaw logs --follow` 并查找 `from.id`。
替代方式（官方 Bot API）：
1. 私聊你的机器人。
2. 使用你的机器人令牌获取更新，并读取 `message.from.id`：
```bash
curl "https://api.telegram.org/bot<bot_token>/getUpdates"
```
第三方方式（隐私性较低）：
- 私聊 `@userinfobot` 或 `@getidsbot` 并使用返回的用户 ID。
### 群组访问
两个独立的控制：
**1. 允许哪些群组**（通过 `channels.telegram.groups` 的群组白名单）：
- 没有 `groups` 配置 = 允许所有群组
- 有 `groups` 配置 = 只允许列出的群组或 `"*"`
- 示例：`"groups": { "-1001234567890": {}, "*": {} }` 允许所有群组
**2. 允许哪些发送者**（通过 `channels.telegram.groupPolicy` 的发送者过滤）：
- `"open"` = 允许的群组中所有发送者都可以发消息
- `"allowlist"` = 只有 `channels.telegram.groupAllowFrom` 中的发送者可以发消息
- `"disabled"` = 完全不接受群组消息
默认为 `groupPolicy: "allowlist"`（除非添加 `groupAllowFrom`，否则被阻止）。
大多数用户需要：`groupPolicy: "allowlist"` + `groupAllowFrom` + 在 `channels.telegram.groups` 中列出特定群组
## 长轮询 vs webhook
- 默认：长轮询（不需要公网 URL）。
- Webhook 模式：设置 `channels.telegram.webhookUrl` 和 `channels.telegram.webhookSecret`（可选 `channels.telegram.webhookPath`）。
- 本地监听器绑定到 `0.0.0.0:8787`，默认服务 `POST /telegram-webhook`。
- 如果你的公网 URL 不同，请使用反向代理并将 `channels.telegram.webhookUrl` 指向公网端点。
## 回复线程
Telegram 通过标签支持可选的线程回复：
- `[[reply_to_current]]` -- 回复触发消息。
- `[[reply_to:<id>]]` -- 回复特定消息 ID。
通过 `channels.telegram.replyToMode` 控制：
- `first`（默认）、`all`、`off`。
## 音频消息（语音 vs 文件）
Telegram 区分**语音消息**（圆形气泡）和**音频文件**（元数据卡片）。
OpenClaw 默认使用音频文件以保持向后兼容。
要在智能体回复中强制使用语音消息气泡，在回复中的任意位置包含此标签：
- `[[audio_as_voice]]` — 以语音消息而非文件形式发送音频。
该标签会从发送的文本中移除。其他渠道会忽略此标签。
对于消息工具发送，设置 `asVoice: true` 并附带兼容语音的音频 `media` URL
（当有 media 时 `message` 为可选）：
```json5
{
action: "send",
channel: "telegram",
to: "123456789",
media: "https://example.com/voice.ogg",
asVoice: true,
}
```
## 贴纸
OpenClaw 支持接收和发送 Telegram 贴纸，并带有智能缓存。
### 接收贴纸
当用户发送贴纸时，OpenClaw 根据贴纸类型进行处理：
- **静态贴纸（WEBP）：** 下载并通过视觉能力处理。贴纸在消息内容中显示为 `<media:sticker>` 占位符。
- **动态贴纸（TGS）：** 跳过（不支持 Lottie 格式处理）。
- **视频贴纸（WEBM）：** 跳过（不支持视频格式处理）。
接收贴纸时可用的模板上下文字段：
- `Sticker` — 包含以下属性的对象：
- `emoji` — 与贴纸关联的表情
- `setName` — 贴纸集名称
- `fileId` — Telegram 文件 ID（可用于发回同一贴纸）
- `fileUniqueId` — 用于缓存查找的稳定 ID
- `cachedDescription` — 可用时的缓存视觉描述
### 贴纸缓存
贴纸通过 AI 的视觉能力处理以生成描述。由于相同的贴纸经常被重复发送，OpenClaw 会缓存这些描述以避免冗余的 API 调用。
**工作原理：**
1. **首次遇到：** 贴纸图像被发送给 AI 进行视觉分析。AI 生成描述（例如"一只卡通猫热情地挥手"）。
2. **缓存存储：** 描述与贴纸的文件 ID、表情和集合名称一起保存。
3. **后续遇到：** 再次看到同一贴纸时，直接使用缓存的描述，不再将图像发送给 AI。
**缓存位置：** `~/.openclaw/telegram/sticker-cache.json`
**缓存条目格式：**
```json
{
"fileId": "CAACAgIAAxkBAAI...",
"fileUniqueId": "AgADBAADb6cxG2Y",
"emoji": "👋",
"setName": "CoolCats",
"description": "A cartoon cat waving enthusiastically",
"cachedAt": "2026-01-15T10:30:00.000Z"
}
```
**优势：**
- 通过避免对同一贴纸重复调用视觉能力来降低 API 成本
- 缓存贴纸的响应速度更快（无视觉处理延迟）
- 支持基于缓存描述的贴纸搜索功能
缓存在接收贴纸时自动填充，无需手动管理。
### 发送贴纸
智能体可以使用 `sticker` 和 `sticker-search` 动作发送和搜索贴纸。这些功能默认禁用，必须在配置中启用：
```json5
{
channels: {
telegram: {
actions: {
sticker: true,
},
},
},
}
```
**发送贴纸：**
```json5
{
action: "sticker",
channel: "telegram",
to: "123456789",
fileId: "CAACAgIAAxkBAAI...",
}
```
参数：
- `fileId`（必填）— 贴纸的 Telegram 文件 ID。可从接收贴纸时的 `Sticker.fileId` 获取，或从 `sticker-search` 结果获取。
- `replyTo`（可选）— 要回复的消息 ID。
- `threadId`（可选）— 论坛话题的消息线程 ID。
**搜索贴纸：**
智能体可以通过描述、表情或集合名称搜索缓存的贴纸：
```json5
{
action: "sticker-search",
channel: "telegram",
query: "cat waving",
limit: 5,
}
```
从缓存返回匹配的贴纸：
```json5
{
ok: true,
count: 2,
stickers: [
{
fileId: "CAACAgIAAxkBAAI...",
emoji: "👋",
description: "A cartoon cat waving enthusiastically",
setName: "CoolCats",
},
],
}
```
搜索使用跨描述文本、表情字符和集合名称的模糊匹配。
**带线程的示例：**
```json5
{
action: "sticker",
channel: "telegram",
to: "-1001234567890",
fileId: "CAACAgIAAxkBAAI...",
replyTo: 42,
threadId: 123,
}
```
## 流式传输（草稿）
Telegram 可以在智能体生成回复时流式传输**草稿气泡**。
OpenClaw 使用 Bot API 的 `sendMessageDraft`（非真实消息），然后将
最终回复作为普通消息发送。
要求（Telegram Bot API 9.3+）：
- **启用话题的私聊**（机器人的论坛话题模式）。
- 入站消息必须包含 `message_thread_id`（私聊话题线程）。
- 群组/超级群组/频道中的流式传输会被忽略。
配置：
- `channels.telegram.streamMode: "off" | "partial" | "block"`（默认：`partial`）
- `partial`：用最新的流式文本更新草稿气泡。
- `block`：以更大的块更新草稿气泡（分块）。
- `off`：禁用草稿流式传输。
- 可选（仅适用于 `streamMode: "block"`）：
- `channels.telegram.draftChunk: { minChars?, maxChars?, breakPreference? }`
- 默认值：`minChars: 200`、`maxChars: 800`、`breakPreference: "paragraph"`（受 `channels.telegram.textChunkLimit` 限制）。
注意：草稿流式传输与**分块流式传输**（渠道消息）不同。
分块流式传输默认关闭，如果你想要提前的 Telegram 消息而非草稿更新，需要设置 `channels.telegram.blockStreaming: true`。
推理流式传输（仅 Telegram）：
- `/reasoning stream` 在回复生成时将推理过程流式传输到草稿气泡中，然后发送不包含推理过程的最终答案。
- 如果 `channels.telegram.streamMode` 为 `off`，推理流式传输将被禁用。
更多上下文：[流式传输 + 分块](/concepts/streaming)。
## 重试策略
出站 Telegram API 调用在遇到瞬态网络/429 错误时会以指数退避和抖动进行重试。通过 `channels.telegram.retry` 配置。参见[重试策略](/concepts/retry)。
## 智能体工具（消息 + 表情回应）
- 工具：`telegram`，`sendMessage` 动作（`to`、`content`，可选 `mediaUrl`、`replyToMessageId`、`messageThreadId`）。
- 工具：`telegram`，`react` 动作（`chatId`、`messageId`、`emoji`）。
- 工具：`telegram`，`deleteMessage` 动作（`chatId`、`messageId`）。
- 表情回应移除语义：参见 [/tools/reactions](/tools/reactions)。
- 工具门控：`channels.telegram.actions.reactions`、`channels.telegram.actions.sendMessage`、`channels.telegram.actions.deleteMessage`（默认：启用），以及 `channels.telegram.actions.sticker`（默认：禁用）。
## 表情回应通知
**表情回应的工作原理：**
Telegram 表情回应作为**独立的 `message_reaction` 事件**到达，而非消息负载中的属性。当用户添加表情回应时，OpenClaw：
1. 从 Telegram API 接收 `message_reaction` 更新
2. 将其转换为**系统事件**，格式为：`"Telegram reaction added: {emoji} by {user} on msg {id}"`
3. 使用与常规消息**相同的会话键**将系统事件入队
4. 当该对话中的下一条消息到达时，系统事件被排出并添加到智能体上下文的前面
智能体将表情回应视为对话历史中的**系统通知**，而非消息元数据。
**配置：**
- `channels.telegram.reactionNotifications`：控制哪些表情回应触发通知
- `"off"` — 忽略所有表情回应
- `"own"` — 当用户对机器人消息做出表情回应时通知（尽力而为；内存中）（默认）
- `"all"` — 对所有表情回应进行通知
- `channels.telegram.reactionLevel`：控制智能体的表情回应能力
- `"off"` — 智能体不能对消息做表情回应
- `"ack"` — 机器人发送确认表情回应（处理时显示 👀）（默认）
- `"minimal"` — 智能体可以少量使用表情回应（指导原则：每 5-10 次交流 1 次）
- `"extensive"` — 智能体可以在适当时大量使用表情回应
**论坛群组：** 论坛群组中的表情回应包含 `message_thread_id`，使用如 `agent:main:telegram:group:{chatId}:topic:{threadId}` 的会话键。这确保同一话题中的表情回应和消息保持在一起。
**示例配置：**
```json5
{
channels: {
telegram: {
reactionNotifications: "all", // 查看所有表情回应
reactionLevel: "minimal", // 智能体可以少量使用表情回应
},
},
}
```
**要求：**
- Telegram 机器人必须在 `allowed_updates` 中显式请求 `message_reaction`（由 OpenClaw 自动配置）
- 对于 webhook 模式，表情回应包含在 webhook 的 `allowed_updates` 中
- 对于轮询模式，表情回应包含在 `getUpdates` 的 `allowed_updates` 中
## 投递目标（CLI/定时任务）
- 使用聊天 ID（`123456789`）或用户名（`@name`）作为目标。
- 示例：`openclaw message send --channel telegram --target 123456789 --message "hi"`。
## 故障排除
**机器人在群组中不响应非提及消息：**
- 如果你设置了 `channels.telegram.groups.*.requireMention=false`，Telegram 的 Bot API **隐私模式**必须被禁用。
- BotFather：`/setprivacy` → **Disable**（然后从群组中移除并重新添加机器人）
- `openclaw channels status` 在配置期望接收非提及群组消息时会显示警告。
- `openclaw channels status --probe` 可以额外检查显式数字群组 ID 的成员资格（无法审计通配符 `"*"` 规则）。
- 快速测试：`/activation always`（仅会话级别；持久化请使用配置）
**机器人完全看不到群组消息：**
- 如果设置了 `channels.telegram.groups`，群组必须被列出或使用 `"*"`
- 在 @BotFather 中检查隐私设置 → "Group Privacy" 应为 **OFF**
- 确认机器人确实是成员（而非只是没有读取权限的管理员）
- 检查 Gateway 日志：`openclaw logs --follow`（查找 "skipping group message"）
**机器人响应提及但不响应 `/activation always`：**
- `/activation` 命令更新会话状态但不会持久化到配置
- 要持久化行为，将群组添加到 `channels.telegram.groups` 并设置 `requireMention: false`
**`/status` 等命令不工作：**
- 确保你的 Telegram 用户 ID 已授权（通过配对或 `channels.telegram.allowFrom`）
- 即使在 `groupPolicy: "open"` 的群组中，命令也需要授权
**长轮询在 Node 22+ 上立即中止（通常涉及代理/自定义 fetch）：**
- Node 22+ 对 `AbortSignal` 实例更严格；外部信号可能会立即中止 `fetch` 调用。
- 升级到规范化 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。
- 快速检查：`dig +short api.telegram.org A` 和 `dig +short api.telegram.org AAAA` 确认 DNS 返回的内容。
## 配置参考（Telegram）
完整配置：[配置](/gateway/configuration)
提供商选项：
- `channels.telegram.enabled`：启用/禁用渠道启动。
- `channels.telegram.botToken`：机器人令牌（BotFather）。
- `channels.telegram.tokenFile`：从文件路径读取令牌。
- `channels.telegram.dmPolicy`：`pairing | allowlist | open | disabled`（默认：pairing）。
- `channels.telegram.allowFrom`：私聊白名单（ID/用户名）。`open` 需要 `"*"`。
- `channels.telegram.groupPolicy`：`open | allowlist | disabled`（默认：allowlist）。
- `channels.telegram.groupAllowFrom`：群组发送者白名单（ID/用户名）。
- `channels.telegram.groups`：按群组的默认设置 + 白名单（使用 `"*"` 作为全局默认）。
- `channels.telegram.groups.<id>.requireMention`：提及门控默认值。
- `channels.telegram.groups.<id>.skills`：技能过滤（省略 = 所有技能，空 = 无技能）。
- `channels.telegram.groups.<id>.allowFrom`：按群组的发送者白名单覆盖。
- `channels.telegram.groups.<id>.systemPrompt`：群组的额外系统提示词。
- `channels.telegram.groups.<id>.enabled`：设为 `false` 时禁用该群组。
- `channels.telegram.groups.<id>.topics.<threadId>.*`：按话题覆盖（与群组字段相同）。
- `channels.telegram.groups.<id>.topics.<threadId>.requireMention`：按话题的提及门控覆盖。
- `channels.telegram.capabilities.inlineButtons`：`off | dm | group | all | allowlist`（默认：allowlist）。
- `channels.telegram.accounts.<account>.capabilities.inlineButtons`：按账户覆盖。
- `channels.telegram.replyToMode`：`off | first | all`（默认：`first`）。
- `channels.telegram.textChunkLimit`：出站分块大小（字符数）。
- `channels.telegram.chunkMode`：`length`（默认）或 `newline`，在空行（段落边界）处拆分后再按长度分块。
- `channels.telegram.linkPreview`：切换出站消息的链接预览（默认：true）。
- `channels.telegram.streamMode`：`off | partial | block`（草稿流式传输）。
- `channels.telegram.mediaMaxMb`：入站/出站媒体上限（MB）。
- `channels.telegram.retry`：出站 Telegram API 调用的重试策略（attempts、minDelayMs、maxDelayMs、jitter）。
- `channels.telegram.network.autoSelectFamily`：覆盖 Node 的 autoSelectFamily（true=启用，false=禁用）。在 Node 22 上默认禁用以避免 Happy Eyeballs 超时。
- `channels.telegram.proxy`：Bot API 调用的代理 URL（SOCKS/HTTP）。
- `channels.telegram.webhookUrl`：启用 webhook 模式（需要 `channels.telegram.webhookSecret`）。
- `channels.telegram.webhookSecret`：webhook 密钥（设置 webhookUrl 时必填）。
- `channels.telegram.webhookPath`：本地 webhook 路径（默认 `/telegram-webhook`）。
- `channels.telegram.actions.reactions`：Telegram 工具表情回应门控。
- `channels.telegram.actions.sendMessage`：Telegram 工具消息发送门控。
- `channels.telegram.actions.deleteMessage`：Telegram 工具消息删除门控。
- `channels.telegram.actions.sticker`：Telegram 贴纸动作门控 — 发送和搜索（默认：false）。
- `channels.telegram.reactionNotifications`：`off | own | all` — 控制哪些表情回应触发系统事件（未设置时默认：`own`）。
- `channels.telegram.reactionLevel`：`off | ack | minimal | extensive` — 控制智能体的表情回应能力（未设置时默认：`minimal`）。
相关全局选项：
- `agents.list[].groupChat.mentionPatterns`（提及门控模式）。
- `messages.groupChat.mentionPatterns`（全局回退）。
- `commands.native`（默认为 `"auto"` → Telegram/Discord 启用，Slack 禁用）、`commands.text`、`commands.useAccessGroups`（命令行为）。通过 `channels.telegram.commands.native` 覆盖。
- `messages.responsePrefix`、`messages.ackReaction`、`messages.ackReactionScope`、`messages.removeAckAfterReply`。

138
docs/zh-CN/channels/tlon.md Normal file
View File

@@ -0,0 +1,138 @@
---
read_when:
- 开发 Tlon/Urbit 渠道功能时
summary: Tlon/Urbit 支持状态、功能和配置
title: Tlon
x-i18n:
generated_at: "2026-02-01T19:58:15Z"
model: claude-opus-4-5
provider: pi
source_hash: 19d7ffe23e82239fd2a2e35913e0d52c809b2c2b939dd39184e6c27a539ed97d
source_path: channels/tlon.md
workflow: 14
---
# Tlon（插件）
Tlon 是一个基于 Urbit 构建的去中心化通讯工具。OpenClaw 连接到你的 Urbit ship，可以
回复私信和群聊消息。群聊回复默认需要 @ 提及，并可通过白名单进一步限制。
状态：通过插件支持。支持私信、群组提及、线程回复和纯文本媒体回退
（URL 附加到标题）。不支持反应、投票和原生媒体上传。
## 需要插件
Tlon 以插件形式提供，不包含在核心安装包中。
通过 CLI 安装（npm 注册表）：
```bash
openclaw plugins install @openclaw/tlon
```
本地签出（从 git 仓库运行时）：
```bash
openclaw plugins install ./extensions/tlon
```
详情：[插件](/plugin)
## 设置
1. 安装 Tlon 插件。
2. 获取你的 ship URL 和登录代码。
3. 配置 `channels.tlon`。
4. 重启 Gateway。
5. 向机器人发送私信或在群组渠道中提及它。
最小配置（单账户）：
```json5
{
channels: {
tlon: {
enabled: true,
ship: "~sampel-palnet",
url: "https://your-ship-host",
code: "lidlut-tabwed-pillex-ridrup",
},
},
}
```
## 群组渠道
默认启用自动发现。你也可以手动固定渠道：
```json5
{
channels: {
tlon: {
groupChannels: ["chat/~host-ship/general", "chat/~host-ship/support"],
},
},
}
```
禁用自动发现：
```json5
{
channels: {
tlon: {
autoDiscoverChannels: false,
},
},
}
```
## 访问控制
私信白名单（为空 = 允许所有）：
```json5
{
channels: {
tlon: {
dmAllowlist: ["~zod", "~nec"],
},
},
}
```
群组授权（默认为受限模式）：
```json5
{
channels: {
tlon: {
defaultAuthorizedShips: ["~zod"],
authorization: {
channelRules: {
"chat/~host-ship/general": {
mode: "restricted",
allowedShips: ["~zod", "~nec"],
},
"chat/~host-ship/announcements": {
mode: "open",
},
},
},
},
},
}
```
## 投递目标（CLI/定时任务）
与 `openclaw message send` 或定时投递配合使用：
- 私信：`~sampel-palnet` 或 `dm/~sampel-palnet`
- 群组：`chat/~host-ship/channel` 或 `group:~host-ship/channel`
## 备注
- 群聊回复需要提及（例如 `~your-bot-ship`）才会响应。
- 线程回复：如果收到的消息在线程中，OpenClaw 会在线程内回复。
- 媒体：`sendMedia` 回退为文本 + URL（不支持原生上传）。

36
docs/zh-CN/channels/troubleshooting.md Normal file
View File

@@ -0,0 +1,36 @@
---
read_when:
- 渠道已连接但消息无法流通
- 排查渠道配置错误（意图、权限、隐私模式）
summary: 渠道专属故障排除快捷指南（Discord/Telegram/WhatsApp）
title: 渠道故障排除
x-i18n:
generated_at: "2026-02-01T19:58:09Z"
model: claude-opus-4-5
provider: pi
source_hash: 6542ee86b3e50929caeaab127642d135dfbc0d8a44876ec2df0fff15bf57cd63
source_path: channels/troubleshooting.md
workflow: 14
---
# 渠道故障排除
首先运行：
```bash
openclaw doctor
openclaw channels status --probe
```
`channels status --probe` 会在检测到常见渠道配置错误时输出警告，并包含小型实时检查（凭据、部分权限/成员资格）。
## 渠道
- Discord：[/channels/discord#troubleshooting](/channels/discord#troubleshooting)
- Telegram：[/channels/telegram#troubleshooting](/channels/telegram#troubleshooting)
- WhatsApp：[/channels/whatsapp#troubleshooting-quick](/channels/whatsapp#troubleshooting-quick)
## Telegram 快速修复
- 日志显示 `HttpError: Network request for 'sendMessage' failed` 或 `sendChatAction` → 检查 IPv6 DNS。如果 `api.telegram.org` 优先解析为 IPv6 而主机缺少 IPv6 出站连接，请强制使用 IPv4 或启用 IPv6。参见 [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting)。
- 日志显示 `setMyCommands failed` → 检查到 `api.telegram.org` 的出站 HTTPS 和 DNS 可达性（常见于限制严格的 VPS 或代理环境）。

384
docs/zh-CN/channels/twitch.md Normal file
View File

@@ -0,0 +1,384 @@
---
read_when:
- 为 OpenClaw 设置 Twitch 聊天集成
summary: Twitch 聊天机器人配置与设置
title: Twitch
x-i18n:
generated_at: "2026-02-01T19:58:38Z"
model: claude-opus-4-5
provider: pi
source_hash: aa7d60444e7f7e5dd7d02ce21527089058e024b8f427aeedf9e200a2818eb007
source_path: channels/twitch.md
workflow: 14
---
# Twitch（插件）
通过 IRC 连接支持 Twitch 聊天。OpenClaw 以 Twitch 用户（机器人账号）身份连接，在频道中接收和发送消息。
## 需要插件
Twitch 以插件形式提供，未包含在核心安装中。
通过 CLI（npm 注册表）安装：
```bash
openclaw plugins install @openclaw/twitch
```
本地签出（从 git 仓库运行时）：
```bash
openclaw plugins install ./extensions/twitch
```
详情：[插件](/plugin)
## 快速设置（入门）
1. 为机器人创建一个专用 Twitch 账号（或使用现有账号）。
2. 生成凭证：[Twitch Token Generator](https://twitchtokengenerator.com/)
- 选择 **Bot Token**
- 确认已勾选 `chat:read` 和 `chat:write` 权限范围
- 复制 **Client ID** 和 **Access Token**
3. 查找你的 Twitch 用户 ID：https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
4. 配置令牌：
- 环境变量：`OPENCLAW_TWITCH_ACCESS_TOKEN=...`（仅限默认账号）
- 或配置文件：`channels.twitch.accessToken`
- 如果两者都设置了，配置文件优先（环境变量回退仅适用于默认账号）。
5. 启动 Gateway。
**⚠️ 重要：** 添加访问控制（`allowFrom` 或 `allowedRoles`）以防止未授权用户触发机器人。`requireMention` 默认为 `true`。
最小配置：
```json5
{
channels: {
twitch: {
enabled: true,
username: "openclaw", // 机器人的 Twitch 账号
accessToken: "oauth:abc123...", // OAuth Access Token（或使用 OPENCLAW_TWITCH_ACCESS_TOKEN 环境变量）
clientId: "xyz789...", // 从 Token Generator 获取的 Client ID
channel: "vevisk", // 要加入的 Twitch 频道聊天室（必填）
allowFrom: ["123456789"], // （推荐）仅限你的 Twitch 用户 ID - 从 https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ 获取
},
},
}
```
## 工作原理
- 由 Gateway 拥有的 Twitch 渠道。
- 确定性路由：回复始终返回到 Twitch。
- 每个账号映射到一个隔离的会话键 `agent:<agentId>:twitch:<accountName>`。
- `username` 是机器人的账号（用于认证），`channel` 是要加入的聊天室。
## 设置（详细）
### 生成凭证
使用 [Twitch Token Generator](https://twitchtokengenerator.com/)：
- 选择 **Bot Token**
- 确认已勾选 `chat:read` 和 `chat:write` 权限范围
- 复制 **Client ID** 和 **Access Token**
无需手动注册应用。令牌在数小时后过期。
### 配置机器人
**环境变量（仅限默认账号）：**
```bash
OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...
```
**或配置文件：**
```json5
{
channels: {
twitch: {
enabled: true,
username: "openclaw",
accessToken: "oauth:abc123...",
clientId: "xyz789...",
channel: "vevisk",
},
},
}
```
如果环境变量和配置文件都设置了，配置文件优先。
### 访问控制（推荐）
```json5
{
channels: {
twitch: {
allowFrom: ["123456789"], // （推荐）仅限你的 Twitch 用户 ID
allowedRoles: ["moderator"], // 或按角色限制
},
},
}
```
**可用角色：** `"moderator"`、`"owner"`、`"vip"`、`"subscriber"`、`"all"`。
**为什么使用用户 ID？** 用户名可以更改，存在冒充风险。用户 ID 是永久的。
查找你的 Twitch 用户 ID：https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/（将 Twitch 用户名转换为 ID）
## 令牌刷新（可选）
从 [Twitch Token Generator](https://twitchtokengenerator.com/) 获取的令牌无法自动刷新——过期后需重新生成。
如需自动刷新令牌，请在 [Twitch Developer Console](https://dev.twitch.tv/console) 创建你自己的 Twitch 应用，并添加到配置中：
```json5
{
channels: {
twitch: {
clientSecret: "your_client_secret",
refreshToken: "your_refresh_token",
},
},
}
```
机器人会在令牌过期前自动刷新，并记录刷新事件。
## 多账号支持
使用 `channels.twitch.accounts` 配置每个账号的令牌。参见 [`gateway/configuration`](/gateway/configuration) 了解通用模式。
示例（一个机器人账号加入两个频道）：
```json5
{
channels: {
twitch: {
accounts: {
channel1: {
username: "openclaw",
accessToken: "oauth:abc123...",
clientId: "xyz789...",
channel: "vevisk",
},
channel2: {
username: "openclaw",
accessToken: "oauth:def456...",
clientId: "uvw012...",
channel: "secondchannel",
},
},
},
},
}
```
**注意：** 每个账号需要自己的令牌（每个频道一个令牌）。
## 访问控制
### 基于角色的限制
```json5
{
channels: {
twitch: {
accounts: {
default: {
allowedRoles: ["moderator", "vip"],
},
},
},
},
}
```
### 按用户 ID 设置允许列表（最安全）
```json5
{
channels: {
twitch: {
accounts: {
default: {
allowFrom: ["123456789", "987654321"],
},
},
},
},
}
```
### 组合允许列表 + 角色
`allowFrom` 中的用户可绕过角色检查：
```json5
{
channels: {
twitch: {
accounts: {
default: {
allowFrom: ["123456789"],
allowedRoles: ["moderator"],
},
},
},
},
}
```
### 禁用 @提及要求
默认情况下，`requireMention` 为 `true`。要禁用并响应所有消息：
```json5
{
channels: {
twitch: {
accounts: {
default: {
requireMention: false,
},
},
},
},
}
```
## 故障排除
首先，运行诊断命令：
```bash
openclaw doctor
openclaw channels status --probe
```
### 机器人不响应消息
**检查访问控制：** 临时设置 `allowedRoles: ["all"]` 进行测试。
**检查机器人是否在频道中：** 机器人必须加入 `channel` 中指定的频道。
### 令牌问题
**"Failed to connect" 或认证错误：**
- 确认 `accessToken` 是 OAuth 访问令牌值（通常以 `oauth:` 前缀开头）
- 检查令牌是否具有 `chat:read` 和 `chat:write` 权限范围
- 如果使用令牌刷新，确认已设置 `clientSecret` 和 `refreshToken`
### 令牌刷新不工作
**检查日志中的刷新事件：**
```
Using env token source for mybot
Access token refreshed for user 123456 (expires in 14400s)
```
如果看到 "token refresh disabled (no refresh token)"：
- 确保已提供 `clientSecret`
- 确保已提供 `refreshToken`
## 配置
**账号配置：**
- `username` - 机器人用户名
- `accessToken` - 具有 `chat:read` 和 `chat:write` 权限的 OAuth 访问令牌
- `clientId` - Twitch Client ID（来自 Token Generator 或你的应用）
- `channel` - 要加入的频道（必填）
- `enabled` - 启用此账号（默认：`true`）
- `clientSecret` - 可选：用于自动刷新令牌
- `refreshToken` - 可选：用于自动刷新令牌
- `expiresIn` - 令牌过期时间（秒）
- `obtainmentTimestamp` - 令牌获取时间戳
- `allowFrom` - 用户 ID 允许列表
- `allowedRoles` - 基于角色的访问控制（`"moderator" | "owner" | "vip" | "subscriber" | "all"`）
- `requireMention` - 要求 @提及（默认：`true`）
**提供商选项：**
- `channels.twitch.enabled` - 启用/禁用渠道启动
- `channels.twitch.username` - 机器人用户名（简化单账号配置）
- `channels.twitch.accessToken` - OAuth 访问令牌（简化单账号配置）
- `channels.twitch.clientId` - Twitch Client ID（简化单账号配置）
- `channels.twitch.channel` - 要加入的频道（简化单账号配置）
- `channels.twitch.accounts.<accountName>` - 多账号配置（上述所有账号字段）
完整示例：
```json5
{
channels: {
twitch: {
enabled: true,
username: "openclaw",
accessToken: "oauth:abc123...",
clientId: "xyz789...",
channel: "vevisk",
clientSecret: "secret123...",
refreshToken: "refresh456...",
allowFrom: ["123456789"],
allowedRoles: ["moderator", "vip"],
accounts: {
default: {
username: "mybot",
accessToken: "oauth:abc123...",
clientId: "xyz789...",
channel: "your_channel",
enabled: true,
clientSecret: "secret123...",
refreshToken: "refresh456...",
expiresIn: 14400,
obtainmentTimestamp: 1706092800000,
allowFrom: ["123456789", "987654321"],
allowedRoles: ["moderator"],
},
},
},
},
}
```
## 工具操作
智能体可以调用 `twitch` 执行以下操作：
- `send` - 向频道发送消息
示例：
```json5
{
action: "twitch",
params: {
message: "Hello Twitch!",
to: "#mychannel",
},
}
```
## 安全与运维
- **将令牌视为密码** - 切勿将令牌提交到 git
- **使用自动令牌刷新** 用于长时间运行的机器人
- **使用用户 ID 允许列表** 而非用户名进行访问控制
- **监控日志** 关注令牌刷新事件和连接状态
- **最小化令牌权限范围** - 仅请求 `chat:read` 和 `chat:write`
- **如遇问题**：确认没有其他进程占用会话后，重启 Gateway
## 限制
- 每条消息最多 **500 个字符**（按词边界自动分块）
- 分块前会移除 Markdown 格式
- 无速率限制（使用 Twitch 内置的速率限制）

410
docs/zh-CN/channels/whatsapp.md Normal file
View File

@@ -0,0 +1,410 @@
---
read_when:
- 处理 WhatsApp/网页渠道行为或收件箱路由时
summary: WhatsApp（网页渠道）集成：登录、收件箱、回复、媒体和运维
title: WhatsApp
x-i18n:
generated_at: "2026-02-01T20:00:02Z"
model: claude-opus-4-5
provider: pi
source_hash: 44fd88f8e269284999e5a5a52b230edae6e6f978528dd298d6a5603d03c0c38d
source_path: channels/whatsapp.md
workflow: 14
---
# WhatsApp（网页渠道）
状态：仅支持通过 Baileys 的 WhatsApp Web。Gateway 拥有会话。
## 快速设置（入门）
1. 如果可能，使用**单独的手机号码**（推荐）。
2. 在 `~/.openclaw/openclaw.json` 中配置 WhatsApp。
3. 运行 `openclaw channels login` 扫描二维码（已关联设备）。
4. 启动 Gateway。
最小配置：
```json5
{
channels: {
whatsapp: {
dmPolicy: "allowlist",
allowFrom: ["+15551234567"],
},
},
}
```
## 目标
- 单个 Gateway 进程中支持多个 WhatsApp 账号（多账号）。
- 确定性路由：回复返回到 WhatsApp，无模型路由。
- 模型获得足够的上下文以理解引用回复。
## 配置写入
默认情况下，WhatsApp 允许通过 `/config set|unset` 触发配置更新写入（需要 `commands.config: true`）。
禁用方式：
```json5
{
channels: { whatsapp: { configWrites: false } },
}
```
## 架构（职责划分）
- **Gateway** 拥有 Baileys socket 和收件箱循环。
- **CLI / macOS 应用** 与 Gateway 通信；不直接使用 Baileys。
- **活跃监听器** 是出站发送的必要条件；否则发送会快速失败。
## 获取手机号码（两种模式）
WhatsApp 需要真实的手机号码进行验证。VoIP 和虚拟号码通常会被屏蔽。在 WhatsApp 上运行 OpenClaw 有两种支持的方式：
### 专用号码（推荐）
为 OpenClaw 使用**单独的手机号码**。最佳用户体验，干净的路由，无自聊天问题。理想设置：**备用/旧 Android 手机 + eSIM**。保持 Wi-Fi 和充电连接，通过二维码关联。
**WhatsApp Business：** 你可以在同一设备上使用不同号码的 WhatsApp Business。非常适合将个人 WhatsApp 分开 — 安装 WhatsApp Business 并在其中注册 OpenClaw 号码。
**示例配置（专用号码，单用户允许列表）：**
```json5
{
channels: {
whatsapp: {
dmPolicy: "allowlist",
allowFrom: ["+15551234567"],
},
},
}
```
**配对模式（可选）：**
如果你想使用配对而非允许列表，将 `channels.whatsapp.dmPolicy` 设置为 `pairing`。未知发送者会收到配对码；通过以下命令批准：
`openclaw pairing approve whatsapp <code>`
### 个人号码（备选方案）
快速备选方案：在**你自己的号码**上运行 OpenClaw。给自己发消息（WhatsApp "给自己发消息"）进行测试，避免打扰联系人。在设置和实验期间，需要在主手机上读取验证码。**必须启用自聊天模式。**
当向导询问你的个人 WhatsApp 号码时，输入你将用来发消息的手机号（所有者/发送者），而不是助手号码。
**示例配置（个人号码，自聊天）：**
```json
{
"whatsapp": {
"selfChatMode": true,
"dmPolicy": "allowlist",
"allowFrom": ["+15551234567"]
}
}
```
当设置了 `messages.responsePrefix` 时，自聊天回复默认使用 `[{identity.name}]`（否则为 `[openclaw]`）。
如果 `messages.responsePrefix` 未设置，则使用默认值。显式设置可自定义或禁用前缀（使用 `""` 来移除）。
### 号码获取技巧
- **本国 eSIM**，来自你所在国家的移动运营商（最可靠）
- 奥地利：[hot.at](https://www.hot.at)
- 英国：[giffgaff](https://www.giffgaff.com) — 免费 SIM 卡，无合约
- **预付费 SIM 卡** — 便宜，只需接收一条验证短信
**避免使用：** TextNow、Google Voice、大多数"免费短信"服务 — WhatsApp 会积极屏蔽这些号码。
**提示：** 该号码只需接收一条验证短信。之后，WhatsApp Web 会话通过 `creds.json` 持久保存。
## 为什么不用 Twilio？
- 早期 OpenClaw 版本支持 Twilio 的 WhatsApp Business 集成。
- WhatsApp Business 号码不适合个人助手。
- Meta 强制执行 24 小时回复窗口；如果你在过去 24 小时内没有回复，商业号码无法发起新消息。
- 高频或"频繁"使用会触发激进的封禁，因为商业账号不适合发送大量个人助手消息。
- 结果：投递不可靠且频繁被封禁，因此已移除支持。
## 登录 + 凭证
- 登录命令：`openclaw channels login`（通过已关联设备扫描二维码）。
- 多账号登录：`openclaw channels login --account <id>`（`<id>` = `accountId`）。
- 默认账号（省略 `--account` 时）：如果存在则为 `default`，否则为第一个已配置的账号 ID（排序后）。
- 凭证存储在 `~/.openclaw/credentials/whatsapp/<accountId>/creds.json`。
- 备份副本位于 `creds.json.bak`（损坏时恢复）。
- 旧版兼容：早期安装将 Baileys 文件直接存储在 `~/.openclaw/credentials/`。
- 注销：`openclaw channels logout`（或 `--account <id>`）删除 WhatsApp 认证状态（但保留共享的 `oauth.json`）。
- 已注销的 socket => 错误提示重新关联。
## 入站流程（私聊 + 群聊）
- WhatsApp 事件来自 `messages.upsert`（Baileys）。
- 收件箱监听器在关闭时解除绑定，以避免在测试/重启中累积事件处理器。
- 状态/广播聊天被忽略。
- 私聊使用 E.164 格式；群聊使用群组 JID。
- **私聊策略**：`channels.whatsapp.dmPolicy` 控制私聊访问（默认：`pairing`）。
- 配对：未知发送者会收到配对码（通过 `openclaw pairing approve whatsapp <code>` 批准；码在 1 小时后过期）。
- 开放：需要 `channels.whatsapp.allowFrom` 包含 `"*"`。
- 你关联的 WhatsApp 号码被隐式信任，因此自消息跳过 `channels.whatsapp.dmPolicy` 和 `channels.whatsapp.allowFrom` 检查。
### 个人号码模式（备选方案）
如果你在**个人 WhatsApp 号码**上运行 OpenClaw，启用 `channels.whatsapp.selfChatMode`（参见上方示例配置）。
行为：
- 出站私聊消息不会触发配对回复（防止骚扰联系人）。
- 入站未知发送者仍遵循 `channels.whatsapp.dmPolicy`。
- 自聊天模式（allowFrom 包含你的号码）避免自动已读回执并忽略提及 JID。
- 非自聊天私聊会发送已读回执。
## 已读回执
默认情况下，Gateway 会在接受入站 WhatsApp 消息后将其标记为已读（蓝色对勾）。
全局禁用：
```json5
{
channels: { whatsapp: { sendReadReceipts: false } },
}
```
按账号禁用：
```json5
{
channels: {
whatsapp: {
accounts: {
personal: { sendReadReceipts: false },
},
},
},
}
```
备注：
- 自聊天模式始终跳过已读回执。
## WhatsApp 常见问题：发送消息 + 配对
**关联 WhatsApp 后，OpenClaw 会给随机联系人发消息吗？**
不会。默认私聊策略是**配对**，因此未知发送者只会收到配对码，其消息**不会被处理**。OpenClaw 只回复收到的聊天，或你显式触发的发送（智能体/CLI）。
**WhatsApp 上的配对是如何工作的？**
配对是针对未知发送者的私聊门控：
- 新发送者的首条私聊消息会返回一个短码（消息不会被处理）。
- 通过以下命令批准：`openclaw pairing approve whatsapp <code>`（用 `openclaw pairing list whatsapp` 列出）。
- 码在 1 小时后过期；每个渠道的待处理请求上限为 3 个。
**多人可以在同一个 WhatsApp 号码上使用不同的 OpenClaw 实例吗？**
可以，通过 `bindings` 将每个发送者路由到不同的智能体（peer `kind: "dm"`，发送者 E.164 如 `+15551234567`）。回复仍然来自**同一个 WhatsApp 账号**，且私聊会折叠到每个智能体的主会话，因此请使用**每人一个智能体**。私聊访问控制（`dmPolicy`/`allowFrom`）在每个 WhatsApp 账号级别是全局的。参见[多智能体路由](/concepts/multi-agent)。
**为什么向导要询问我的手机号码？**
向导使用它来设置你的**允许列表/所有者**，以便允许你自己的私聊消息。它不用于自动发送。如果你在个人 WhatsApp 号码上运行，使用相同的号码并启用 `channels.whatsapp.selfChatMode`。
## 消息标准化（模型看到的内容）
- `Body` 是当前消息正文及其信封。
- 引用回复上下文**始终附加**：
```
[Replying to +1555 id:ABC123]
<quoted text or <media:...>>
[/Replying]
```
- 回复元数据也会设置：
- `ReplyToId` = stanzaId
- `ReplyToBody` = 引用正文或媒体占位符
- `ReplyToSender` = E.164（已知时）
- 纯媒体入站消息使用占位符：
- `<media:image|video|audio|document|sticker>`
## 群聊
- 群聊映射到 `agent:<agentId>:whatsapp:group:<jid>` 会话。
- 群聊策略：`channels.whatsapp.groupPolicy = open|disabled|allowlist`（默认 `allowlist`）。
- 激活模式：
- `mention`（默认）：需要 @提及或正则匹配。
- `always`：始终触发。
- `/activation mention|always` 仅限所有者且必须作为独立消息发送。
- 所有者 = `channels.whatsapp.allowFrom`（未设置时为自身 E.164）。
- **历史注入**（仅待处理）：
- 最近*未处理*的消息（默认 50 条）插入在：
`[Chat messages since your last reply - for context]`（已在会话中的消息不会被重复注入）
- 当前消息位于：
`[Current message - respond to this]`
- 发送者后缀附加：`[from: Name (+E164)]`
- 群聊元数据缓存 5 分钟（主题 + 参与者）。
## 回复投递（线程）
- WhatsApp Web 发送标准消息（当前 Gateway 中无引用回复线程）。
- 此渠道忽略回复标签。
## 确认反应（收到消息时自动反应）
WhatsApp 可以在收到消息时立即自动发送表情反应，在机器人生成回复之前。这为用户提供即时反馈，表明其消息已收到。
**配置：**
```json
{
"whatsapp": {
"ackReaction": {
"emoji": "👀",
"direct": true,
"group": "mentions"
}
}
}
```
**选项：**
- `emoji`（字符串）：用于确认的表情（例如 "👀"、"✅"、"📨"）。为空或省略 = 功能禁用。
- `direct`（布尔值，默认：`true`）：在私聊/DM 中发送反应。
- `group`（字符串，默认：`"mentions"`）：群聊行为：
- `"always"`：对所有群聊消息做出反应（即使没有 @提及）
- `"mentions"`：仅在机器人被 @提及时做出反应
- `"never"`：从不在群聊中做出反应
**按账号覆盖：**
```json
{
"whatsapp": {
"accounts": {
"work": {
"ackReaction": {
"emoji": "✅",
"direct": false,
"group": "always"
}
}
}
}
}
```
**行为说明：**
- 反应在收到消息时**立即**发送，在输入指示器或机器人回复之前。
- 在 `requireMention: false`（激活模式：always）的群组中，`group: "mentions"` 会对所有消息做出反应（不仅仅是 @提及）。
- 即发即忘：反应失败会被记录但不会阻止机器人回复。
- 群聊反应会自动包含参与者 JID。
- WhatsApp 忽略 `messages.ackReaction`；请改用 `channels.whatsapp.ackReaction`。
## 智能体工具（反应）
- 工具：`whatsapp`，使用 `react` 动作（`chatJid`、`messageId`、`emoji`，可选 `remove`）。
- 可选：`participant`（群聊发送者）、`fromMe`（对自己的消息做出反应）、`accountId`（多账号）。
- 反应移除语义：参见 [/tools/reactions](/tools/reactions)。
- 工具门控：`channels.whatsapp.actions.reactions`（默认：启用）。
## 限制
- 出站文本按 `channels.whatsapp.textChunkLimit` 分块（默认 4000）。
- 可选换行分块：设置 `channels.whatsapp.chunkMode="newline"` 在空行（段落边界）处分割，再进行长度分块。
- 入站媒体保存受 `channels.whatsapp.mediaMaxMb` 限制（默认 50 MB）。
- 出站媒体项受 `agents.defaults.mediaMaxMb` 限制（默认 5 MB）。
## 出站发送（文本 + 媒体）
- 使用活跃的网页监听器；如果 Gateway 未运行则报错。
- 文本分块：每条消息最大 4k（可通过 `channels.whatsapp.textChunkLimit` 配置，可选 `channels.whatsapp.chunkMode`）。
- 媒体：
- 支持图片/视频/音频/文档。
- 音频以 PTT 发送；`audio/ogg` => `audio/ogg; codecs=opus`。
- 仅第一个媒体项带字幕。
- 媒体获取支持 HTTP(S) 和本地路径。
- 动态 GIF：WhatsApp 期望带 `gifPlayback: true` 的 MP4 以实现内联循环播放。
- CLI：`openclaw message send --media <mp4> --gif-playback`
- Gateway：`send` 参数包含 `gifPlayback: true`
## 语音消息（PTT 音频）
WhatsApp 以**语音消息**（PTT 气泡）发送音频。
- 最佳效果：OGG/Opus。OpenClaw 将 `audio/ogg` 重写为 `audio/ogg; codecs=opus`。
- WhatsApp 忽略 `[[audio_as_voice]]`（音频已作为语音消息发送）。
## 媒体限制 + 优化
- 默认出站上限：5 MB（每个媒体项）。
- 覆盖：`agents.defaults.mediaMaxMb`。
- 图片会自动优化为 JPEG 以控制在上限内（缩放 + 质量扫描）。
- 超大媒体 => 错误；媒体回复回退为文本警告。
## 心跳
- **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` 跳过行为。
- 投递默认到最后使用的渠道（或已配置的目标）。
## 重连行为
- 退避策略：`web.reconnect`：
- `initialMs`、`maxMs`、`factor`、`jitter`、`maxAttempts`。
- 如果达到 maxAttempts，网页监控停止（降级）。
- 已注销 => 停止并要求重新关联。
## 配置速查表
- `channels.whatsapp.dmPolicy`（私聊策略：pairing/allowlist/open/disabled）。
- `channels.whatsapp.selfChatMode`（同号设置；机器人使用你的个人 WhatsApp 号码）。
- `channels.whatsapp.allowFrom`（私聊允许列表）。WhatsApp 使用 E.164 手机号码（无用户名）。
- `channels.whatsapp.mediaMaxMb`（入站媒体保存上限）。
- `channels.whatsapp.ackReaction`（消息收到时的自动反应：`{emoji, direct, group}`）。
- `channels.whatsapp.accounts.<accountId>.*`（按账号设置 + 可选 `authDir`）。
- `channels.whatsapp.accounts.<accountId>.mediaMaxMb`（按账号入站媒体上限）。
- `channels.whatsapp.accounts.<accountId>.ackReaction`（按账号确认反应覆盖）。
- `channels.whatsapp.groupAllowFrom`（群聊发送者允许列表）。
- `channels.whatsapp.groupPolicy`（群聊策略）。
- `channels.whatsapp.historyLimit` / `channels.whatsapp.accounts.<accountId>.historyLimit`（群聊历史上下文；`0` 禁用）。
- `channels.whatsapp.dmHistoryLimit`（私聊历史限制，按用户轮数）。按用户覆盖：`channels.whatsapp.dms["<phone>"].historyLimit`。
- `channels.whatsapp.groups`（群聊允许列表 + 提及门控默认值；使用 `"*"` 允许全部）
- `channels.whatsapp.actions.reactions`（WhatsApp 工具反应门控）。
- `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）
- `messages.groupChat.historyLimit`
- `channels.whatsapp.messagePrefix`（入站前缀；按账号：`channels.whatsapp.accounts.<accountId>.messagePrefix`；已弃用：`messages.messagePrefix`）
- `messages.responsePrefix`（出站前缀）
- `agents.defaults.mediaMaxMb`
- `agents.defaults.heartbeat.every`
- `agents.defaults.heartbeat.model`（可选覆盖）
- `agents.defaults.heartbeat.target`
- `agents.defaults.heartbeat.to`
- `agents.defaults.heartbeat.session`
- `agents.list[].heartbeat.*`（按智能体覆盖）
- `session.*`（scope、idle、store、mainKey）
- `web.enabled`（为 false 时禁用渠道启动）
- `web.heartbeatSeconds`
- `web.reconnect.*`
## 日志 + 故障排除
- 子系统：`whatsapp/inbound`、`whatsapp/outbound`、`web-heartbeat`、`web-reconnect`。
- 日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`（可配置）。
- 故障排除指南：[Gateway 故障排除](/gateway/troubleshooting)。
## 故障排除（快速）
**未关联 / 需要二维码登录**
- 症状：`channels status` 显示 `linked: false` 或警告"未关联"。
- 修复：在 Gateway 主机上运行 `openclaw channels login` 并扫描二维码（WhatsApp → 设置 → 已关联设备）。
**已关联但断开连接 / 重连循环**
- 症状：`channels status` 显示 `running, disconnected` 或警告"已关联但断开连接"。
- 修复：`openclaw doctor`（或重启 Gateway）。如果问题持续，通过 `channels login` 重新关联并检查 `openclaw logs --follow`。
**Bun 运行时**
- **不推荐**使用 Bun。WhatsApp（Baileys）和 Telegram 在 Bun 上不稳定。
请使用 **Node** 运行 Gateway。（参见入门指南运行时说明。）

196
docs/zh-CN/channels/zalo.md Normal file
View File

@@ -0,0 +1,196 @@
---
read_when:
- 处理 Zalo 功能或 webhook 时
summary: Zalo 机器人支持状态、功能和配置
title: Zalo
x-i18n:
generated_at: "2026-02-01T19:58:32Z"
model: claude-opus-4-5
provider: pi
source_hash: 0311d932349f96412b712970b5d37329b91929bf3020536edf3ca0ff464373c0
source_path: channels/zalo.md
workflow: 14
---
# Zalo (Bot API)
状态：实验性。仅支持私信；根据 Zalo 文档，群组功能即将推出。
## 需要插件
Zalo 以插件形式提供，不包含在核心安装中。
- 通过 CLI 安装：`openclaw plugins install @openclaw/zalo`
- 或在上手引导中选择 **Zalo** 并确认安装提示
- 详情：[插件](/plugin)
## 快速设置（新手）
1. 安装 Zalo 插件：
- 从源码检出安装：`openclaw plugins install ./extensions/zalo`
- 从 npm 安装（如已发布）：`openclaw plugins install @openclaw/zalo`
- 或在上手引导中选择 **Zalo** 并确认安装提示
2. 设置令牌：
- 环境变量：`ZALO_BOT_TOKEN=...`
- 或配置：`channels.zalo.botToken: "..."`。
3. 重启 Gateway（或完成上手引导）。
4. 私信访问默认使用配对模式；首次联系时需批准配对码。
最小配置：
```json5
{
channels: {
zalo: {
enabled: true,
botToken: "12345689:abc-xyz",
dmPolicy: "pairing",
},
},
}
```
## 简介
Zalo 是一款面向越南市场的即时通讯应用；其 Bot API 允许 Gateway 运行一个用于一对一对话的机器人。
它非常适合需要将消息确定性路由回 Zalo 的客服或通知场景。
- 由 Gateway 管理的 Zalo Bot API 渠道。
- 确定性路由：回复始终返回 Zalo；模型不会选择渠道。
- 私信共享智能体的主会话。
- 群组尚不支持（Zalo 文档标注"即将推出"）。
## 设置（快速路径）
### 1) 创建机器人令牌（Zalo Bot Platform）
1. 前往 **https://bot.zaloplatforms.com** 并登录。
2. 创建新机器人并配置其设置。
3. 复制机器人令牌（格式：`12345689:abc-xyz`）。
### 2) 配置令牌（环境变量或配置文件）
示例：
```json5
{
channels: {
zalo: {
enabled: true,
botToken: "12345689:abc-xyz",
dmPolicy: "pairing",
},
},
}
```
环境变量选项：`ZALO_BOT_TOKEN=...`（仅适用于默认账户）。
多账户支持：使用 `channels.zalo.accounts`，为每个账户配置令牌和可选的 `name`。
3. 重启 Gateway。当令牌被解析（通过环境变量或配置）时，Zalo 将启动。
4. 私信访问默认使用配对模式。机器人首次被联系时，请批准配对码。
## 工作原理（行为）
- 入站消息被标准化为共享渠道信封，并包含媒体占位符。
- 回复始终路由回同一个 Zalo 聊天。
- 默认使用长轮询；可通过 `channels.zalo.webhookUrl` 启用 webhook 模式。
## 限制
- 出站文本按 2000 字符分块（Zalo API 限制）。
- 媒体下载/上传受 `channels.zalo.mediaMaxMb` 限制（默认 5）。
- 由于 2000 字符限制导致流式传输意义不大，默认禁用流式传输。
## 访问控制（私信）
### 私信访问
- 默认：`channels.zalo.dmPolicy = "pairing"`。未知发送者会收到配对码；消息在批准前将被忽略（配对码 1 小时后过期）。
- 批准方式：
- `openclaw pairing list zalo`
- `openclaw pairing approve zalo <CODE>`
- 配对是默认的令牌交换方式。详情：[配对](/start/pairing)
- `channels.zalo.allowFrom` 接受数字用户 ID（不支持用户名查找）。
## 长轮询与 webhook
- 默认：长轮询（无需公网 URL）。
- Webhook 模式：设置 `channels.zalo.webhookUrl` 和 `channels.zalo.webhookSecret`。
- Webhook 密钥必须为 8-256 个字符。
- Webhook URL 必须使用 HTTPS。
- Zalo 通过 `X-Bot-Api-Secret-Token` 请求头发送事件以进行验证。
- Gateway HTTP 在 `channels.zalo.webhookPath` 处理 webhook 请求（默认为 webhook URL 路径）。
**注意：** 根据 Zalo API 文档，getUpdates（轮询）和 webhook 互斥。
## 支持的消息类型
- **文本消息**：完全支持，按 2000 字符分块。
- **图片消息**：下载并处理入站图片；通过 `sendPhoto` 发送图片。
- **贴纸**：已记录但未完全处理（无智能体响应）。
- **不支持的类型**：已记录（例如来自受保护用户的消息）。
## 功能
| 功能 | 状态 |
| ------------ | ----------------------------- |
| 私信 | ✅ 支持 |
| 群组 | ❌ 即将推出（根据 Zalo 文档） |
| 媒体（图片） | ✅ 支持 |
| 表情回应 | ❌ 不支持 |
| 话题 | ❌ 不支持 |
| 投票 | ❌ 不支持 |
| 原生命令 | ❌ 不支持 |
| 流式传输 | ⚠️ 已禁用（2000 字符限制） |
## 投递目标（CLI/定时任务）
- 使用聊天 ID 作为目标。
- 示例：`openclaw message send --channel zalo --target 123456789 --message "hi"`。
## 故障排除
**机器人无响应：**
- 检查令牌是否有效：`openclaw channels status --probe`
- 验证发送者是否已批准（配对或 allowFrom）
- 检查 Gateway 日志：`openclaw logs --follow`
**Webhook 未收到事件：**
- 确保 webhook URL 使用 HTTPS
- 验证密钥令牌为 8-256 个字符
- 确认 Gateway HTTP 端点在配置的路径上可达
- 检查 getUpdates 轮询是否未在运行（两者互斥）
## 配置参考（Zalo）
完整配置：[配置](/gateway/configuration)
提供商选项：
- `channels.zalo.enabled`：启用/禁用渠道启动。
- `channels.zalo.botToken`：来自 Zalo Bot Platform 的机器人令牌。
- `channels.zalo.tokenFile`：从文件路径读取令牌。
- `channels.zalo.dmPolicy`：`pairing | allowlist | open | disabled`（默认：pairing）。
- `channels.zalo.allowFrom`：私信允许列表（用户 ID）。`open` 需要 `"*"`。向导会要求输入数字 ID。
- `channels.zalo.mediaMaxMb`：入站/出站媒体大小上限（MB，默认 5）。
- `channels.zalo.webhookUrl`：启用 webhook 模式（需要 HTTPS）。
- `channels.zalo.webhookSecret`：webhook 密钥（8-256 个字符）。
- `channels.zalo.webhookPath`：Gateway HTTP 服务器上的 webhook 路径。
- `channels.zalo.proxy`：API 请求的代理 URL。
多账户选项：
- `channels.zalo.accounts.<id>.botToken`：每个账户的令牌。
- `channels.zalo.accounts.<id>.tokenFile`：每个账户的令牌文件。
- `channels.zalo.accounts.<id>.name`：显示名称。
- `channels.zalo.accounts.<id>.enabled`：启用/禁用账户。
- `channels.zalo.accounts.<id>.dmPolicy`：每个账户的私信策略。
- `channels.zalo.accounts.<id>.allowFrom`：每个账户的允许列表。
- `channels.zalo.accounts.<id>.webhookUrl`：每个账户的 webhook URL。
- `channels.zalo.accounts.<id>.webhookSecret`：每个账户的 webhook 密钥。
- `channels.zalo.accounts.<id>.webhookPath`：每个账户的 webhook 路径。
- `channels.zalo.accounts.<id>.proxy`：每个账户的代理 URL。

147
docs/zh-CN/channels/zalouser.md Normal file
View File

@@ -0,0 +1,147 @@
---
read_when:
- 为 OpenClaw 设置 Zalo Personal
- 调试 Zalo Personal 登录或消息流
summary: 通过 zca-cli（二维码登录）支持 Zalo 个人账号，功能与配置说明
title: Zalo Personal
x-i18n:
generated_at: "2026-02-01T19:58:27Z"
model: claude-opus-4-5
provider: pi
source_hash: 2a249728d556e5cc52274627bdaf390fa10e815afa04f4497feb57a2a0cb9261
source_path: channels/zalouser.md
workflow: 14
---
# Zalo Personal（非官方）
状态：实验性。此集成通过 `zca-cli` 自动化操作一个**个人 Zalo 账号**。
> **警告：** 这是一个非官方集成，可能导致账号被暂停或封禁。使用风险自负。
## 需要安装插件
Zalo Personal 以插件形式提供，不包含在核心安装包中。
- 通过 CLI 安装：`openclaw plugins install @openclaw/zalouser`
- 或从源码检出安装：`openclaw plugins install ./extensions/zalouser`
- 详情：[插件](/plugin)
## 前置条件：zca-cli
Gateway 所在机器必须在 `PATH` 中包含 `zca` 可执行文件。
- 验证：`zca --version`
- 如果缺失，请安装 zca-cli（参见 `extensions/zalouser/README.md` 或上游 zca-cli 文档）。
## 快速设置（入门）
1. 安装插件（见上文）。
2. 登录（二维码方式，在 Gateway 机器上操作）：
- `openclaw channels login --channel zalouser`
- 使用 Zalo 手机应用扫描终端中的二维码。
3. 启用渠道：
```json5
{
channels: {
zalouser: {
enabled: true,
dmPolicy: "pairing",
},
},
}
```
4. 重启 Gateway（或完成上手引导）。
5. 私信访问默认为配对模式；首次联系时需批准配对码。
## 功能说明
- 使用 `zca listen` 接收入站消息。
- 使用 `zca msg ...` 发送回复（文本/媒体/链接）。
- 专为 Zalo Bot API 不可用时的"个人账号"使用场景设计。
## 命名说明
渠道 ID 为 `zalouser`，以明确表示这是对**个人 Zalo 用户账号**的自动化操作（非官方）。我们将 `zalo` 保留给未来可能的官方 Zalo API 集成。
## 查找 ID（通讯录）
使用通讯录 CLI 发现联系人/群组及其 ID：
```bash
openclaw directory self --channel zalouser
openclaw directory peers list --channel zalouser --query "name"
openclaw directory groups list --channel zalouser --query "work"
```
## 限制
- 出站文本按约 2000 字符分块（Zalo 客户端限制）。
- 流式传输默认被禁用。
## 访问控制（私信）
`channels.zalouser.dmPolicy` 支持：`pairing | allowlist | open | disabled`（默认：`pairing`）。
`channels.zalouser.allowFrom` 接受用户 ID 或名称。向导在可用时通过 `zca friend find` 将名称解析为 ID。
通过以下方式批准：
- `openclaw pairing list zalouser`
- `openclaw pairing approve zalouser <code>`
## 群组访问（可选）
- 默认：`channels.zalouser.groupPolicy = "open"`（允许群组）。未设置时使用 `channels.defaults.groupPolicy` 覆盖默认值。
- 通过允许列表进行限制：
- `channels.zalouser.groupPolicy = "allowlist"`
- `channels.zalouser.groups`（键为群组 ID 或名称）
- 禁止所有群组：`channels.zalouser.groupPolicy = "disabled"`。
- 配置向导可以提示设置群组允许列表。
- 启动时，OpenClaw 会将允许列表中的群组/用户名称解析为 ID 并记录映射关系；未解析的条目保持原样。
示例：
```json5
{
channels: {
zalouser: {
groupPolicy: "allowlist",
groups: {
"123456789": { allow: true },
"Work Chat": { allow: true },
},
},
},
}
```
## 多账号
账号映射到 zca 配置文件。示例：
```json5
{
channels: {
zalouser: {
enabled: true,
defaultAccount: "default",
accounts: {
work: { enabled: true, profile: "work" },
},
},
},
}
```
## 故障排除
**找不到 `zca`：**
- 安装 zca-cli 并确保 Gateway 进程的 `PATH` 中包含该命令。
**登录状态无法保持：**
- `openclaw channels status --probe`
- 重新登录：`openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser`

173
docs/zh-CN/cli/acp.md Normal file
View File

@@ -0,0 +1,173 @@
---
read_when:
- 设置基于 ACP 的 IDE 集成
- 调试 ACP 会话到 Gateway 的路由
summary: 运行用于 IDE 集成的 ACP 桥接
title: acp
x-i18n:
generated_at: "2026-02-01T19:58:33Z"
model: claude-opus-4-5
provider: pi
source_hash: 0c09844297da250bc1a558423e7e534d6b6be9045de12d797c07ecd64a0c63ed
source_path: cli/acp.md
workflow: 14
---
# acp
运行与 OpenClaw Gateway 通信的 ACP（Agent Client Protocol）桥接。
此命令通过 stdio 使用 ACP 协议与 IDE 通信，并通过 WebSocket 将提示转发到 Gateway。它将 ACP 会话映射到 Gateway 会话密钥。
## 用法
```bash
openclaw acp
# 远程 Gateway
openclaw acp --url wss://gateway-host:18789 --token <token>
# 附加到现有会话密钥
openclaw acp --session agent:main:main
# 通过标签附加（必须已存在）
openclaw acp --session-label "support inbox"
# 在第一个提示之前重置会话密钥
openclaw acp --session agent:main:main --reset-session
```
## ACP 客户端（调试）
使用内置 ACP 客户端在无需 IDE 的情况下对桥接进行安装完整性检查。
它会启动 ACP 桥接并允许你交互式地输入提示。
```bash
openclaw acp client
# 将启动的桥接指向远程 Gateway
openclaw acp client --server-args --url wss://gateway-host:18789 --token <token>
# 覆盖服务器命令（默认：openclaw）
openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001
```
## 如何使用
当 IDE（或其他客户端）使用 Agent Client Protocol 并且你希望它驱动 OpenClaw Gateway 会话时，请使用 ACP。
1. 确保 Gateway 正在运行（本地或远程）。
2. 配置 Gateway 目标（通过配置文件或标志）。
3. 将你的 IDE 配置为通过 stdio 运行 `openclaw acp`。
示例配置（持久化）：
```bash
openclaw config set gateway.remote.url wss://gateway-host:18789
openclaw config set gateway.remote.token <token>
```
示例直接运行（不写入配置）：
```bash
openclaw acp --url wss://gateway-host:18789 --token <token>
```
## 选择智能体
ACP 不直接选择智能体。它通过 Gateway 会话密钥进行路由。
使用智能体作用域的会话密钥来指定特定智能体：
```bash
openclaw acp --session agent:main:main
openclaw acp --session agent:design:main
openclaw acp --session agent:qa:bug-123
```
每个 ACP 会话映射到单个 Gateway 会话密钥。一个智能体可以有多个会话；除非你覆盖密钥或标签，否则 ACP 默认使用隔离的 `acp:<uuid>` 会话。
## Zed 编辑器设置
在 `~/.config/zed/settings.json` 中添加自定义 ACP 智能体（或使用 Zed 的设置界面）：
```json
{
"agent_servers": {
"OpenClaw ACP": {
"type": "custom",
"command": "openclaw",
"args": ["acp"],
"env": {}
}
}
}
```
要指定特定的 Gateway 或智能体：
```json
{
"agent_servers": {
"OpenClaw ACP": {
"type": "custom",
"command": "openclaw",
"args": [
"acp",
"--url",
"wss://gateway-host:18789",
"--token",
"<token>",
"--session",
"agent:design:main"
],
"env": {}
}
}
}
```
在 Zed 中，打开 Agent 面板并选择 "OpenClaw ACP" 来开始一个对话线程。
## 会话映射
默认情况下，ACP 会话会获得一个带有 `acp:` 前缀的隔离 Gateway 会话密钥。
要复用已知会话，请传递会话密钥或标签：
- `--session <key>`：使用特定的 Gateway 会话密钥。
- `--session-label <label>`：通过标签解析现有会话。
- `--reset-session`：为该密钥生成新的会话 ID（相同密钥，新的对话记录）。
如果你的 ACP 客户端支持元数据，你可以按会话进行覆盖：
```json
{
"_meta": {
"sessionKey": "agent:main:main",
"sessionLabel": "support inbox",
"resetSession": true
}
}
```
了解更多关于会话密钥的信息，请参阅 [/concepts/session](/concepts/session)。
## 选项
- `--url <url>`：Gateway WebSocket URL（配置后默认使用 gateway.remote.url）。
- `--token <token>`：Gateway 认证令牌。
- `--password <password>`：Gateway 认证密码。
- `--session <key>`：默认会话密钥。
- `--session-label <label>`：要解析的默认会话标签。
- `--require-existing`：如果会话密钥/标签不存在则失败。
- `--reset-session`：在首次使用前重置会话密钥。
- `--no-prefix-cwd`：不在提示前添加工作目录前缀。
- `--verbose, -v`：将详细日志输出到 stderr。
### `acp client` 选项
- `--cwd <dir>`：ACP 会话的工作目录。
- `--server <command>`：ACP 服务器命令（默认：`openclaw`）。
- `--server-args <args...>`：传递给 ACP 服务器的额外参数。
- `--server-verbose`：启用 ACP 服务器的详细日志。
- `--verbose, -v`：详细客户端日志。

31
docs/zh-CN/cli/agent.md Normal file
View File

@@ -0,0 +1,31 @@
---
read_when:
- 您想从脚本中运行一次智能体轮次（可选择投递回复）
summary: "`openclaw agent` 的 CLI 参考（通过 Gateway 发送一次智能体轮次）"
title: agent
x-i18n:
generated_at: "2026-02-01T19:58:31Z"
model: claude-opus-4-5
provider: pi
source_hash: dcf12fb94e207c68645f58235792596d65afecf8216b8f9ab3acb01e03b50a33
source_path: cli/agent.md
workflow: 14
---
# `openclaw agent`
通过 Gateway 运行一次智能体轮次（使用 `--local` 进行嵌入式运行）。
使用 `--agent <id>` 直接指定一个已配置的智能体。
相关内容：
- 智能体发送工具：[智能体发送](/tools/agent-send)
## 示例
```bash
openclaw agent --to +15555550123 --message "status update" --deliver
openclaw agent --agent ops --message "Summarize logs"
openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium
openclaw agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"
```

82
docs/zh-CN/cli/agents.md Normal file
View File

@@ -0,0 +1,82 @@
---
read_when:
- 您需要多个隔离的智能体（工作区 + 路由 + 认证）
summary: "`openclaw agents` 的 CLI 参考（列出/添加/删除/设置身份）"
title: agents
x-i18n:
generated_at: "2026-02-01T19:58:38Z"
model: claude-opus-4-5
provider: pi
source_hash: 30556d81636a9ad8972573cc6b498e620fd266e1dfb16eef3f61096ea62f9896
source_path: cli/agents.md
workflow: 14
---
# `openclaw agents`
管理隔离的智能体（工作区 + 认证 + 路由）。
相关内容：
- 多智能体路由：[多智能体路由](/concepts/multi-agent)
- 智能体工作区：[智能体工作区](/concepts/agent-workspace)
## 示例
```bash
openclaw agents list
openclaw agents add work --workspace ~/.openclaw/workspace-work
openclaw agents set-identity --workspace ~/.openclaw/workspace --from-identity
openclaw agents set-identity --agent main --avatar avatars/openclaw.png
openclaw agents delete work
```
## 身份文件
每个智能体工作区可以在工作区根目录包含一个 `IDENTITY.md`：
- 示例路径：`~/.openclaw/workspace/IDENTITY.md`
- `set-identity --from-identity` 从工作区根目录读取（或从显式指定的 `--identity-file` 读取）
头像路径相对于工作区根目录解析。
## 设置身份
`set-identity` 将字段写入 `agents.list[].identity`：
- `name`
- `theme`
- `emoji`
- `avatar`（工作区相对路径、http(s) URL 或 data URI）
从 `IDENTITY.md` 加载：
```bash
openclaw agents set-identity --workspace ~/.openclaw/workspace --from-identity
```
显式覆盖字段：
```bash
openclaw agents set-identity --agent main --name "OpenClaw" --emoji "🦞" --avatar avatars/openclaw.png
```
配置示例：
```json5
{
agents: {
list: [
{
id: "main",
identity: {
name: "OpenClaw",
theme: "space lobster",
emoji: "🦞",
avatar: "avatars/openclaw.png",
},
},
],
},
}
```

57
docs/zh-CN/cli/approvals.md Normal file
View File

@@ -0,0 +1,57 @@
---
read_when:
- 您想通过 CLI 编辑执行审批
- 您需要管理 Gateway 或节点主机上的允许列表
summary: "`openclaw approvals` 的 CLI 参考（用于 Gateway 或节点主机的执行审批）"
title: approvals
x-i18n:
generated_at: "2026-02-01T19:58:39Z"
model: claude-opus-4-5
provider: pi
source_hash: 4329cdaaec2c5f5d619415b6431196512d4834dc1ccd7363576f03dd9b845130
source_path: cli/approvals.md
workflow: 14
---
# `openclaw approvals`
管理**本地主机**、**Gateway 主机**或**节点主机**的执行审批。
默认情况下，命令针对磁盘上的本地审批文件。使用 `--gateway` 针对 Gateway，或使用 `--node` 针对特定节点。
相关内容：
- 执行审批：[执行审批](/tools/exec-approvals)
- 节点：[节点](/nodes)
## 常用命令
```bash
openclaw approvals get
openclaw approvals get --node <id|name|ip>
openclaw approvals get --gateway
```
## 从文件替换审批
```bash
openclaw approvals set --file ./exec-approvals.json
openclaw approvals set --node <id|name|ip> --file ./exec-approvals.json
openclaw approvals set --gateway --file ./exec-approvals.json
```
## 允许列表辅助命令
```bash
openclaw approvals allowlist add "~/Projects/**/bin/rg"
openclaw approvals allowlist add --agent main --node <id|name|ip> "/usr/bin/uptime"
openclaw approvals allowlist add --agent "*" "/usr/bin/uname"
openclaw approvals allowlist remove "~/Projects/**/bin/rg"
```
## 注意事项
- `--node` 使用与 `openclaw nodes` 相同的解析器（id、名称、ip 或 id 前缀）。
- `--agent` 默认为 `"*"`，即适用于所有智能体。
- 节点主机必须公布 `system.execApprovals.get/set`（macOS 应用或无头节点主机）。
- 审批文件按主机存储在 `~/.openclaw/exec-approvals.json`。

114
docs/zh-CN/cli/browser.md Normal file
View File

@@ -0,0 +1,114 @@
---
read_when:
- 使用 `openclaw browser` 并需要常见任务的示例
- 想要通过节点主机控制运行在另一台机器上的浏览器
- 想要使用 Chrome 扩展中继（通过工具栏按钮附加/分离）
summary: "`openclaw browser` 的 CLI 参考（配置文件、标签页、操作、扩展中继）"
title: browser
x-i18n:
generated_at: "2026-02-01T19:58:45Z"
model: claude-opus-4-5
provider: pi
source_hash: af35adfd68726fd519c704d046451effd330458c2b8305e713137fb07b2571fd
source_path: cli/browser.md
workflow: 14
---
# `openclaw browser`
管理 OpenClaw 的浏览器控制服务器并执行浏览器操作（标签页、快照、截图、导航、点击、输入）。
相关内容：
- 浏览器工具 + API：[浏览器工具](/tools/browser)
- Chrome 扩展中继：[Chrome 扩展](/tools/chrome-extension)
## 常用标志
- `--url <gatewayWsUrl>`：Gateway WebSocket URL（默认使用配置值）。
- `--token <token>`：Gateway 令牌（如需要）。
- `--timeout <ms>`：请求超时时间（毫秒）。
- `--browser-profile <name>`：选择浏览器配置文件（默认使用配置值）。
- `--json`：机器可读输出（在支持的情况下）。
## 快速开始（本地）
```bash
openclaw browser --browser-profile chrome tabs
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot
```
## 配置文件
配置文件是命名的浏览器路由配置。实际使用中：
- `openclaw`：启动/附加到一个专用的 OpenClaw 管理的 Chrome 实例（隔离的用户数据目录）。
- `chrome`：通过 Chrome 扩展中继控制你现有的 Chrome 标签页。
```bash
openclaw browser profiles
openclaw browser create-profile --name work --color "#FF5A36"
openclaw browser delete-profile --name work
```
使用特定配置文件：
```bash
openclaw browser --browser-profile work tabs
```
## 标签页
```bash
openclaw browser tabs
openclaw browser open https://docs.openclaw.ai
openclaw browser focus <targetId>
openclaw browser close <targetId>
```
## 快照 / 截图 / 操作
快照：
```bash
openclaw browser snapshot
```
截图：
```bash
openclaw browser screenshot
```
导航/点击/输入（基于引用的 UI 自动化）：
```bash
openclaw browser navigate https://example.com
openclaw browser click <ref>
openclaw browser type <ref> "hello"
```
## Chrome 扩展中继（通过工具栏按钮附加）
此模式允许智能体控制你手动附加的现有 Chrome 标签页（不会自动附加）。
将未打包的扩展安装到稳定路径：
```bash
openclaw browser extension install
openclaw browser extension path
```
然后在 Chrome 中 → `chrome://extensions` → 启用"开发者模式" → "加载已解压的扩展程序" → 选择打印出的文件夹。
完整指南：[Chrome 扩展](/tools/chrome-extension)
## 远程浏览器控制（节点主机代理）
如果 Gateway 与浏览器运行在不同的机器上，请在安装了 Chrome/Brave/Edge/Chromium 的机器上运行**节点主机**。Gateway 会将浏览器操作代理到该节点（无需单独的浏览器控制服务器）。
使用 `gateway.nodes.browser.mode` 控制自动路由，使用 `gateway.nodes.browser.node` 在多个节点连接时固定到特定节点。
安全性 + 远程设置：[浏览器工具](/tools/browser)、[远程访问](/gateway/remote)、[Tailscale](/gateway/tailscale)、[安全](/gateway/security)

86
docs/zh-CN/cli/channels.md Normal file
View File

@@ -0,0 +1,86 @@
---
read_when:
- 你想添加/移除渠道账号（WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost（插件）/Signal/iMessage）
- 你想检查渠道状态或查看渠道日志
summary: "`openclaw channels` 的 CLI 参考（账号、状态、登录/登出、日志）"
title: channels
x-i18n:
generated_at: "2026-02-01T19:58:48Z"
model: claude-opus-4-5
provider: pi
source_hash: 16ab1642f247bfa96e8e08dfeb1eedfccb148f40d91099f5423f971df2b54e20
source_path: cli/channels.md
workflow: 14
---
# `openclaw channels`
管理 Gateway 上的聊天渠道账号及其运行时状态。
相关文档：
- 渠道指南：[渠道](/channels/index)
- Gateway 配置：[配置](/gateway/configuration)
## 常用命令
```bash
openclaw channels list
openclaw channels status
openclaw channels capabilities
openclaw channels capabilities --channel discord --target channel:123
openclaw channels resolve --channel slack "#general" "@jane"
openclaw channels logs --channel all
```
## 添加/移除账号
```bash
openclaw channels add --channel telegram --token <bot-token>
openclaw channels remove --channel telegram --delete
```
提示：`openclaw channels add --help` 可查看各渠道的专用参数（token、app token、signal-cli 路径等）。
## 登录/登出（交互式）
```bash
openclaw channels login --channel whatsapp
openclaw channels logout --channel whatsapp
```
## 故障排除
- 运行 `openclaw status --deep` 进行全面探测。
- 使用 `openclaw doctor` 获取引导式修复。
- `openclaw channels list` 输出 `Claude: HTTP 403 ... user:profile` → 用量快照需要 `user:profile` 权限范围。使用 `--no-usage`，或提供 claude.ai 会话密钥（`CLAUDE_WEB_SESSION_KEY` / `CLAUDE_WEB_COOKIE`），或通过 Claude Code CLI 重新认证。
## 能力探测
获取提供商能力提示（可用的 intents/scopes）以及静态功能支持：
```bash
openclaw channels capabilities
openclaw channels capabilities --channel discord --target channel:123
```
说明：
- `--channel` 是可选的；省略时将列出所有渠道（包括扩展）。
- `--target` 接受 `channel:<id>` 或原始数字频道 ID，仅适用于 Discord。
- 探测因提供商而异：Discord intents + 可选的频道权限；Slack bot + 用户权限范围；Telegram bot 标志 + webhook；Signal 守护进程版本；MS Teams 应用令牌 + Graph 角色/权限范围（已知的会标注）。无探测功能的渠道会报告 `Probe: unavailable`。
## 将名称解析为 ID
使用提供商目录将渠道/用户名称解析为 ID：
```bash
openclaw channels resolve --channel slack "#general" "@jane"
openclaw channels resolve --channel discord "My Server/#support" "@someone"
openclaw channels resolve --channel matrix "Project Room"
```
说明：
- 使用 `--kind user|group|auto` 强制指定目标类型。
- 当多个条目共享相同名称时，解析优先选择活跃的匹配项。

56
docs/zh-CN/cli/config.md Normal file
View File

@@ -0,0 +1,56 @@
---
read_when:
- 您想以非交互方式读取或编辑配置
summary: "`openclaw config` 的 CLI 参考（获取/设置/删除配置值）"
title: config
x-i18n:
generated_at: "2026-02-01T19:58:45Z"
model: claude-opus-4-5
provider: pi
source_hash: d60a35f5330f22bc99a0df090590586109d329ddd2ca294aeed191a22560c1c2
source_path: cli/config.md
workflow: 14
---
# `openclaw config`
配置辅助工具：通过路径获取/设置/删除值。不带子命令运行时将打开配置向导（与 `openclaw configure` 相同）。
## 示例
```bash
openclaw config get browser.executablePath
openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
openclaw config unset tools.web.search.apiKey
```
## 路径
路径使用点号或方括号表示法：
```bash
openclaw config get agents.defaults.workspace
openclaw config get agents.list[0].id
```
使用智能体列表索引来指定特定智能体：
```bash
openclaw config get agents.list
openclaw config set agents.list[1].tools.exec.node "node-id-or-name"
```
## 值
值会尽可能按 JSON5 解析；否则视为字符串。
使用 `--json` 强制要求 JSON5 解析。
```bash
openclaw config set agents.defaults.heartbeat.every "0m"
openclaw config set gateway.port 19001 --json
openclaw config set channels.whatsapp.groups '["*"]' --json
```
编辑后请重启 Gateway。

40
docs/zh-CN/cli/configure.md Normal file
View File

@@ -0,0 +1,40 @@
---
read_when:
- 您想通过交互方式调整凭据、设备或智能体默认设置
summary: "`openclaw configure` 的 CLI 参考（交互式配置提示）"
title: configure
x-i18n:
generated_at: "2026-02-01T19:58:46Z"
model: claude-opus-4-5
provider: pi
source_hash: 9cb2bb5237b02b3a2dca71b5e43b11bd6b9939b9e4aa9ce1882457464b51efd2
source_path: cli/configure.md
workflow: 14
---
# `openclaw configure`
交互式提示，用于设置凭据、设备和智能体默认配置。
注意：**模型**部分现在包含一个多选项，用于设置
`agents.defaults.models` 允许列表（决定在 `/model` 和模型选择器中显示哪些模型）。
提示：不带子命令运行 `openclaw config` 会打开相同的向导。使用
`openclaw config get|set|unset` 进行非交互式编辑。
相关内容：
- Gateway 配置参考：[配置](/gateway/configuration)
- Config CLI：[Config](/cli/config)
注意事项：
- 选择 Gateway 运行位置时会始终更新 `gateway.mode`。如果您只需要修改这一项，可以直接选择"继续"而无需配置其他部分。
- 面向渠道的服务（Slack/Discord/Matrix/Microsoft Teams）在设置过程中会提示配置渠道/房间允许列表。您可以输入名称或 ID；向导会尽可能将名称解析为 ID。
## 示例
```bash
openclaw configure
openclaw configure --section models --section channels
```

38
docs/zh-CN/cli/cron.md Normal file
View File

@@ -0,0 +1,38 @@
---
read_when:
- 您需要定时任务和唤醒功能
- 您正在调试定时任务的执行和日志
summary: "`openclaw cron` 的 CLI 参考（调度和运行后台任务）"
title: cron
x-i18n:
generated_at: "2026-02-01T19:58:49Z"
model: claude-opus-4-5
provider: pi
source_hash: bc9317c824f3b6339df657cc269961d9b5f121da65ec2b23a07d454e6d611135
source_path: cli/cron.md
workflow: 14
---
# `openclaw cron`
管理 Gateway 调度器的定时任务。
相关内容：
- 定时任务：[定时任务](/automation/cron-jobs)
提示：运行 `openclaw cron --help` 查看完整的命令列表。
## 常见编辑
更新投递设置而不更改消息内容：
```bash
openclaw cron edit <job-id> --deliver --channel telegram --to "123456789"
```
为隔离任务禁用投递：
```bash
openclaw cron edit <job-id> --no-deliver
```

23
docs/zh-CN/cli/dashboard.md Normal file
View File

@@ -0,0 +1,23 @@
---
read_when:
- 想要使用当前令牌打开控制界面
- 想要打印 URL 而不启动浏览器
summary: "`openclaw dashboard` 的 CLI 参考（打开控制界面）"
title: dashboard
x-i18n:
generated_at: "2026-02-01T19:58:50Z"
model: claude-opus-4-5
provider: pi
source_hash: 242a3b35ea43149be12ee2b8f2bc81b6dc24cea546a15f422dcfd0cf2e7724db
source_path: cli/dashboard.md
workflow: 14
---
# `openclaw dashboard`
使用当前认证信息打开控制界面。
```bash
openclaw dashboard
openclaw dashboard --no-open
```

74
docs/zh-CN/cli/devices.md Normal file
View File

@@ -0,0 +1,74 @@
---
read_when:
- 您正在审批设备配对请求
- 您需要轮换或吊销设备令牌
summary: "`openclaw devices` 的 CLI 参考（设备配对 + 令牌轮换/吊销）"
title: devices
x-i18n:
generated_at: "2026-02-01T19:58:53Z"
model: claude-opus-4-5
provider: pi
source_hash: 52f903817d2886c1dc29b85d30168d1edff7944bd120a1e139159c9d99a1f517
source_path: cli/devices.md
workflow: 14
---
# `openclaw devices`
管理设备配对请求和设备范围的令牌。
## 命令
### `openclaw devices list`
列出待处理的配对请求和已配对的设备。
```
openclaw devices list
openclaw devices list --json
```
### `openclaw devices approve <requestId>`
批准待处理的设备配对请求。
```
openclaw devices approve <requestId>
```
### `openclaw devices reject <requestId>`
拒绝待处理的设备配对请求。
```
openclaw devices reject <requestId>
```
### `openclaw devices rotate --device <id> --role <role> [--scope <scope...>]`
轮换特定角色的设备令牌（可选择更新权限范围）。
```
openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write
```
### `openclaw devices revoke --device <id> --role <role>`
吊销特定角色的设备令牌。
```
openclaw devices revoke --device <deviceId> --role node
```
## 通用选项
- `--url <url>`：Gateway WebSocket URL（配置后默认使用 `gateway.remote.url`）。
- `--token <token>`：Gateway 令牌（如需要）。
- `--password <password>`：Gateway 密码（密码认证）。
- `--timeout <ms>`：RPC 超时时间。
- `--json`：JSON 输出（推荐用于脚本）。
## 注意事项
- 令牌轮换会返回新令牌（敏感信息）。请将其视为机密处理。
- 这些命令需要 `operator.pairing`（或 `operator.admin`）权限范围。

70
docs/zh-CN/cli/directory.md Normal file
View File

@@ -0,0 +1,70 @@
---
read_when:
- 你想查找某个渠道的联系人/群组/自身 ID
- 你正在开发渠道目录适配器
summary: "`openclaw directory` 的 CLI 参考（self、peers、groups）"
title: directory
x-i18n:
generated_at: "2026-02-01T19:58:58Z"
model: claude-opus-4-5
provider: pi
source_hash: 7c878d9013aeaa22c8a21563fac30b465a86be85d8c917c5d4591b5c3d4b2025
source_path: cli/directory.md
workflow: 14
---
# `openclaw directory`
对支持目录功能的渠道进行查找（联系人/对等方、群组和"我"）。
## 通用参数
- `--channel <name>`：渠道 ID/别名（配置了多个渠道时为必填；仅配置一个渠道时自动选择）
- `--account <id>`：账号 ID（默认：渠道默认账号）
- `--json`：输出 JSON 格式
## 说明
- `directory` 用于帮助你查找可粘贴到其他命令中的 ID（特别是 `openclaw message send --target ...`）。
- 对于许多渠道，结果来源于配置（允许列表/已配置的群组），而非实时的提供商目录。
- 默认输出为以制表符分隔的 `id`（有时包含 `name`）；脚本中请使用 `--json`。
## 将结果用于 `message send`
```bash
openclaw directory peers list --channel slack --query "U0"
openclaw message send --channel slack --target user:U012ABCDEF --message "hello"
```
## ID 格式（按渠道）
- WhatsApp：`+15551234567`（私聊），`1234567890-1234567890@g.us`（群组）
- Telegram：`@username` 或数字聊天 ID；群组为数字 ID
- Slack：`user:U…` 和 `channel:C…`
- Discord：`user:<id>` 和 `channel:<id>`
- Matrix（插件）：`user:@user:server`、`room:!roomId:server` 或 `#alias:server`
- Microsoft Teams（插件）：`user:<id>` 和 `conversation:<id>`
- Zalo（插件）：用户 ID（Bot API）
- Zalo Personal / `zalouser`（插件）：来自 `zca` 的会话 ID（私聊/群组）（`me`、`friend list`、`group list`）
## Self（"我"）
```bash
openclaw directory self --channel zalouser
```
## Peers（联系人/用户）
```bash
openclaw directory peers list --channel zalouser
openclaw directory peers list --channel zalouser --query "name"
openclaw directory peers list --channel zalouser --limit 50
```
## 群组
```bash
openclaw directory groups list --channel zalouser
openclaw directory groups list --channel zalouser --query "work"
openclaw directory groups members --channel zalouser --group-id <id>
```

30
docs/zh-CN/cli/dns.md Normal file
View File

@@ -0,0 +1,30 @@
---
read_when:
- 您需要通过 Tailscale + CoreDNS 实现广域发现（DNS-SD）
- 您正在为自定义发现域名设置分离 DNS（例如：openclaw.internal）
summary: "`openclaw dns` 的 CLI 参考（广域发现辅助工具）"
title: dns
x-i18n:
generated_at: "2026-02-01T19:58:53Z"
model: claude-opus-4-5
provider: pi
source_hash: d2011e41982ffb4b71ab98211574529bc1c8b7769ab1838abddd593f42b12380
source_path: cli/dns.md
workflow: 14
---
# `openclaw dns`
用于广域发现的 DNS 辅助工具（Tailscale + CoreDNS）。目前专注于 macOS + Homebrew CoreDNS。
相关内容：
- Gateway 发现：[发现](/gateway/discovery)
- 广域发现配置：[配置](/gateway/configuration)
## 设置
```bash
openclaw dns setup
openclaw dns setup --apply
```

22
docs/zh-CN/cli/docs.md Normal file
View File

@@ -0,0 +1,22 @@
---
read_when:
- 想要从终端搜索 OpenClaw 在线文档
summary: "`openclaw docs` 的 CLI 参考（搜索在线文档索引）"
title: docs
x-i18n:
generated_at: "2026-02-01T19:58:52Z"
model: claude-opus-4-5
provider: pi
source_hash: 7a4000e91f7c6ed1140f684e2d1849577651e9389c5c90532a74db58c0b86d47
source_path: cli/docs.md
workflow: 14
---
# `openclaw docs`
搜索在线文档索引。
```bash
openclaw docs browser extension
openclaw docs sandbox allowHostControl
```

48
docs/zh-CN/cli/doctor.md Normal file
View File

@@ -0,0 +1,48 @@
---
read_when:
- 遇到连接/认证问题并需要引导修复
- 更新后想要进行安装完整性检查
summary: "`openclaw doctor` 的 CLI 参考（健康检查 + 引导修复）"
title: doctor
x-i18n:
generated_at: "2026-02-01T19:58:59Z"
model: claude-opus-4-5
provider: pi
source_hash: 92310aa3f3d111e91a74ce1150359d5d8a8d70a856666d9419e16c60d78209f2
source_path: cli/doctor.md
workflow: 14
---
# `openclaw doctor`
Gateway 和渠道的健康检查 + 快速修复。
相关内容：
- 故障排除：[故障排除](/gateway/troubleshooting)
- 安全审计：[安全](/gateway/security)
## 示例
```bash
openclaw doctor
openclaw doctor --repair
openclaw doctor --deep
```
备注：
- 交互式提示（如钥匙串/OAuth 修复）仅在 stdin 为 TTY 且**未**设置 `--non-interactive` 时运行。无头运行（cron、Telegram、无终端）将跳过提示。
- `--fix`（`--repair` 的别名）会将备份写入 `~/.openclaw/openclaw.json.bak`，并删除未知的配置键，同时列出每个删除项。
## macOS：`launchctl` 环境变量覆盖
如果你之前运行过 `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...`（或 `...PASSWORD`），该值会覆盖你的配置文件，并可能导致持续的"未授权"错误。
```bash
launchctl getenv OPENCLAW_GATEWAY_TOKEN
launchctl getenv OPENCLAW_GATEWAY_PASSWORD
launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD
```

206
docs/zh-CN/cli/gateway.md Normal file
View File

@@ -0,0 +1,206 @@
---
read_when:
- 从 CLI 运行 Gateway（开发或服务器环境）
- 调试 Gateway 认证、绑定模式和连接问题
- 通过 Bonjour 发现 Gateway（局域网 + tailnet）
summary: OpenClaw Gateway CLI（`openclaw gateway`）— 运行、查询和发现 Gateway
title: gateway
x-i18n:
generated_at: "2026-02-01T19:59:19Z"
model: claude-opus-4-5
provider: pi
source_hash: 054dd48056e4784f153c6511c8eb35b56f239db8d4e629661841a00259e9abbf
source_path: cli/gateway.md
workflow: 14
---
# Gateway CLI
Gateway 是 OpenClaw 的 WebSocket 服务器（渠道、节点、会话、钩子）。
本页中的子命令位于 `openclaw gateway …` 下。
相关文档：
- [/gateway/bonjour](/gateway/bonjour)
- [/gateway/discovery](/gateway/discovery)
- [/gateway/configuration](/gateway/configuration)
## 运行 Gateway
运行本地 Gateway 进程：
```bash
openclaw gateway
```
前台运行别名：
```bash
openclaw gateway run
```
注意事项：
- 默认情况下，除非在 `~/.openclaw/openclaw.json` 中设置了 `gateway.mode=local`，否则 Gateway 会拒绝启动。使用 `--allow-unconfigured` 进行临时/开发运行。
- 在没有认证的情况下绑定到回环地址以外的地址会被阻止（安全防护措施）。
- 授权后 `SIGUSR1` 会触发进程内重启（需启用 `commands.restart` 或使用 Gateway 工具/配置应用/更新）。
- `SIGINT`/`SIGTERM` 处理程序会停止 Gateway 进程，但不会恢复任何自定义终端状态。如果您使用 TUI 或原始模式输入包装 CLI，请在退出前恢复终端。
### 选项
- `--port <port>`：WebSocket 端口（默认来自配置/环境变量；通常为 `18789`）。
- `--bind <loopback|lan|tailnet|auto|custom>`：监听器绑定模式。
- `--auth <token|password>`：认证模式覆盖。
- `--token <token>`：令牌覆盖（同时为进程设置 `OPENCLAW_GATEWAY_TOKEN`）。
- `--password <password>`：密码覆盖（同时为进程设置 `OPENCLAW_GATEWAY_PASSWORD`）。
- `--tailscale <off|serve|funnel>`：通过 Tailscale 暴露 Gateway。
- `--tailscale-reset-on-exit`：关闭时重置 Tailscale serve/funnel 配置。
- `--allow-unconfigured`：允许在配置中没有 `gateway.mode=local` 的情况下启动 Gateway。
- `--dev`：如果缺失则创建开发配置和工作区（跳过 BOOTSTRAP.md）。
- `--reset`：重置开发配置 + 凭据 + 会话 + 工作区（需要 `--dev`）。
- `--force`：启动前终止所选端口上的现有监听器。
- `--verbose`：详细日志。
- `--claude-cli-logs`：仅在控制台显示 claude-cli 日志（并启用其 stdout/stderr）。
- `--ws-log <auto|full|compact>`：WebSocket 日志样式（默认 `auto`）。
- `--compact`：`--ws-log compact` 的别名。
- `--raw-stream`：将原始模型流事件记录到 jsonl。
- `--raw-stream-path <path>`：原始流 jsonl 路径。
## 查询运行中的 Gateway
所有查询命令使用 WebSocket RPC。
输出模式：
- 默认：人类可读（TTY 中带颜色）。
- `--json`：机器可读的 JSON（无样式/加载动画）。
- `--no-color`（或 `NO_COLOR=1`）：禁用 ANSI 但保持人类可读布局。
共享选项（在支持的命令中）：
- `--url <url>`：Gateway WebSocket URL。
- `--token <token>`：Gateway 令牌。
- `--password <password>`：Gateway 密码。
- `--timeout <ms>`：超时时间/预算（因命令而异）。
- `--expect-final`：等待"最终"响应（智能体调用）。
### `gateway health`
```bash
openclaw gateway health --url ws://127.0.0.1:18789
```
### `gateway status`
`gateway status` 显示 Gateway 服务（launchd/systemd/schtasks）以及可选的 RPC 探测。
```bash
openclaw gateway status
openclaw gateway status --json
```
选项：
- `--url <url>`：覆盖探测 URL。
- `--token <token>`：探测的令牌认证。
- `--password <password>`：探测的密码认证。
- `--timeout <ms>`：探测超时时间（默认 `10000`）。
- `--no-probe`：跳过 RPC 探测（仅查看服务状态）。
- `--deep`：同时扫描系统级服务。
### `gateway probe`
`gateway probe` 是"全面调试"命令。它始终会探测：
- 您配置的远程 Gateway（如已设置），以及
- localhost（回环地址），**即使已配置远程 Gateway**。
如果有多个 Gateway 可达，它会全部输出。当您使用隔离的配置文件/端口时（例如救援机器人），支持多个 Gateway，但大多数安装仍然运行单个 Gateway。
```bash
openclaw gateway probe
openclaw gateway probe --json
```
#### 通过 SSH 远程连接（Mac 应用对等模式）
macOS 应用的"通过 SSH 远程连接"模式使用本地端口转发，使远程 Gateway（可能仅绑定到回环地址）可通过 `ws://127.0.0.1:<port>` 访问。
CLI 等效命令：
```bash
openclaw gateway probe --ssh user@gateway-host
```
选项：
- `--ssh <target>`：`user@host` 或 `user@host:port`（端口默认为 `22`）。
- `--ssh-identity <path>`：身份文件。
- `--ssh-auto`：自动选择第一个发现的 Gateway 主机作为 SSH 目标（仅限局域网/WAB）。
配置（可选，用作默认值）：
- `gateway.remote.sshTarget`
- `gateway.remote.sshIdentity`
### `gateway call <method>`
底层 RPC 辅助工具。
```bash
openclaw gateway call status
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
```
## 管理 Gateway 服务
```bash
openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall
```
注意事项：
- `gateway install` 支持 `--port`、`--runtime`、`--token`、`--force`、`--json`。
- 生命周期命令接受 `--json` 用于脚本编写。
## 发现 Gateway（Bonjour）
`gateway discover` 扫描 Gateway 信标（`_openclaw-gw._tcp`）。
- 组播 DNS-SD：`local.`
- 单播 DNS-SD（广域 Bonjour）：选择一个域名（例如：`openclaw.internal.`）并设置分离 DNS + DNS 服务器；参见 [/gateway/bonjour](/gateway/bonjour)
只有启用了 Bonjour 发现（默认启用）的 Gateway 才会广播信标。
广域发现记录包含（TXT）：
- `role`（Gateway 角色提示）
- `transport`（传输提示，例如 `gateway`）
- `gatewayPort`（WebSocket 端口，通常为 `18789`）
- `sshPort`（SSH 端口；如未指定默认为 `22`）
- `tailnetDns`（MagicDNS 主机名，如可用）
- `gatewayTls` / `gatewayTlsSha256`（TLS 启用 + 证书指纹）
- `cliPath`（可选的远程安装路径提示）
### `gateway discover`
```bash
openclaw gateway discover
```
选项：
- `--timeout <ms>`：每条命令的超时时间（浏览/解析）；默认 `2000`。
- `--json`：机器可读输出（同时禁用样式/加载动画）。
示例：
```bash
openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'
```

28
docs/zh-CN/cli/health.md Normal file
View File

@@ -0,0 +1,28 @@
---
read_when:
- 您想快速检查正在运行的 Gateway 的健康状态
summary: "`openclaw health` 的 CLI 参考（通过 RPC 访问 Gateway 健康端点）"
title: health
x-i18n:
generated_at: "2026-02-01T19:58:57Z"
model: claude-opus-4-5
provider: pi
source_hash: 82a78a5a97123f7a5736699ae8d793592a736f336c5caced9eba06d14d973fd7
source_path: cli/health.md
workflow: 14
---
# `openclaw health`
从正在运行的 Gateway 获取健康状态。
```bash
openclaw health
openclaw health --json
openclaw health --verbose
```
说明：
- `--verbose` 会运行实时探测，并在配置了多个账号时打印每个账号的耗时。
- 配置了多个智能体时，输出中会包含每个智能体的会话存储信息。

310
docs/zh-CN/cli/hooks.md Normal file
View File

@@ -0,0 +1,310 @@
---
read_when:
- 您想管理智能体钩子
- 您想安装或更新钩子
summary: "`openclaw hooks` 的 CLI 参考（智能体钩子）"
title: hooks
x-i18n:
generated_at: "2026-02-01T19:59:18Z"
model: claude-opus-4-5
provider: pi
source_hash: e2032e61ff4b9135cb2708d92eb7889ac627b85a5fc153e3d5b84265f7bd7bc6
source_path: cli/hooks.md
workflow: 14
---
# `openclaw hooks`
管理智能体钩子（用于 `/new`、`/reset` 等命令以及 Gateway 启动的事件驱动自动化）。
相关内容：
- 钩子：[钩子](/hooks)
- 插件钩子：[插件](/plugin#plugin-hooks)
## 列出所有钩子
```bash
openclaw hooks list
```
列出从工作区、托管和内置目录中发现的所有钩子。
**选项：**
- `--eligible`：仅显示符合条件的钩子（需求已满足）
- `--json`：以 JSON 格式输出
- `-v, --verbose`：显示详细信息，包括缺失的需求
**示例输出：**
```
Hooks (4/4 ready)
Ready:
🚀 boot-md ✓ - Run BOOT.md on gateway startup
📝 command-logger ✓ - Log all command events to a centralized audit file
💾 session-memory ✓ - Save session context to memory when /new command is issued
😈 soul-evil ✓ - Swap injected SOUL content during a purge window or by random chance
```
**示例（详细模式）：**
```bash
openclaw hooks list --verbose
```
显示不符合条件的钩子缺失的需求。
**示例（JSON）：**
```bash
openclaw hooks list --json
```
返回结构化 JSON 以供程序化使用。
## 获取钩子信息
```bash
openclaw hooks info <name>
```
显示特定钩子的详细信息。
**参数：**
- `<name>`：钩子名称（例如 `session-memory`）
**选项：**
- `--json`：以 JSON 格式输出
**示例：**
```bash
openclaw hooks info session-memory
```
**输出：**
```
💾 session-memory ✓ Ready
Save session context to memory when /new command is issued
Details:
Source: openclaw-bundled
Path: /path/to/openclaw/hooks/bundled/session-memory/HOOK.md
Handler: /path/to/openclaw/hooks/bundled/session-memory/handler.ts
Homepage: https://docs.openclaw.ai/hooks#session-memory
Events: command:new
Requirements:
Config: ✓ workspace.dir
```
## 检查钩子资格
```bash
openclaw hooks check
```
显示钩子资格状态摘要（就绪与未就绪的数量）。
**选项：**
- `--json`：以 JSON 格式输出
**示例输出：**
```
Hooks Status
Total hooks: 4
Ready: 4
Not ready: 0
```
## 启用钩子
```bash
openclaw hooks enable <name>
```
通过将特定钩子添加到配置文件（`~/.openclaw/config.json`）来启用它。
**注意：** 由插件管理的钩子在 `openclaw hooks list` 中显示为 `plugin:<id>`，无法在此处启用/禁用。请改为启用/禁用对应的插件。
**参数：**
- `<name>`：钩子名称（例如 `session-memory`）
**示例：**
```bash
openclaw hooks enable session-memory
```
**输出：**
```
✓ Enabled hook: 💾 session-memory
```
**执行操作：**
- 检查钩子是否存在且符合条件
- 在配置中更新 `hooks.internal.entries.<name>.enabled = true`
- 将配置保存到磁盘
**启用后：**
- 重启 Gateway 以重新加载钩子（macOS 上重启菜单栏应用，或在开发环境中重启 Gateway 进程）。
## 禁用钩子
```bash
openclaw hooks disable <name>
```
通过更新配置来禁用特定钩子。
**参数：**
- `<name>`：钩子名称（例如 `command-logger`）
**示例：**
```bash
openclaw hooks disable command-logger
```
**输出：**
```
⏸ Disabled hook: 📝 command-logger
```
**禁用后：**
- 重启 Gateway 以重新加载钩子
## 安装钩子
```bash
openclaw hooks install <path-or-spec>
```
从本地文件夹/归档包或 npm 安装钩子包。
**执行操作：**
- 将钩子包复制到 `~/.openclaw/hooks/<id>`
- 在 `hooks.internal.entries.*` 中启用已安装的钩子
- 在 `hooks.internal.installs` 下记录安装信息
**选项：**
- `-l, --link`：链接本地目录而非复制（将其添加到 `hooks.internal.load.extraDirs`）
**支持的归档格式：** `.zip`、`.tgz`、`.tar.gz`、`.tar`
**示例：**
```bash
# 本地目录
openclaw hooks install ./my-hook-pack
# 本地归档包
openclaw hooks install ./my-hook-pack.zip
# NPM 包
openclaw hooks install @openclaw/my-hook-pack
# 链接本地目录而非复制
openclaw hooks install -l ./my-hook-pack
```
## 更新钩子
```bash
openclaw hooks update <id>
openclaw hooks update --all
```
更新已安装的钩子包（仅限 npm 安装）。
**选项：**
- `--all`：更新所有已跟踪的钩子包
- `--dry-run`：显示将要更改的内容而不实际写入
## 内置钩子
### session-memory
在您执行 `/new` 时将会话上下文保存到记忆中。
**启用：**
```bash
openclaw hooks enable session-memory
```
**输出：** `~/.openclaw/workspace/memory/YYYY-MM-DD-slug.md`
**参见：** [session-memory 文档](/hooks#session-memory)
### command-logger
将所有命令事件记录到集中审计文件中。
**启用：**
```bash
openclaw hooks enable command-logger
```
**输出：** `~/.openclaw/logs/commands.log`
**查看日志：**
```bash
# 最近的命令
tail -n 20 ~/.openclaw/logs/commands.log
# 格式化输出
cat ~/.openclaw/logs/commands.log | jq .
# 按操作过滤
grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .
```
**参见：** [command-logger 文档](/hooks#command-logger)
### soul-evil
在清除窗口期间或随机情况下，将注入的 `SOUL.md` 内容替换为 `SOUL_EVIL.md`。
**启用：**
```bash
openclaw hooks enable soul-evil
```
**参见：** [SOUL Evil 钩子](/hooks/soul-evil)
### boot-md
在 Gateway 启动时（渠道启动之后）运行 `BOOT.md`。
**事件**：`gateway:startup`
**启用**：
```bash
openclaw hooks enable boot-md
```
**参见：** [boot-md 文档](/hooks#boot-md)

1033
docs/zh-CN/cli/index.md Normal file
View File

File diff suppressed because it is too large Load Diff

31
docs/zh-CN/cli/logs.md Normal file
View File

@@ -0,0 +1,31 @@
---
read_when:
- 需要远程查看 Gateway 日志（无需 SSH）
- 需要 JSON 格式的日志行以供工具使用
summary: 通过 RPC 查看 Gateway 日志的 `openclaw logs` CLI 参考
title: logs
x-i18n:
generated_at: "2026-02-01T20:21:08Z"
model: claude-opus-4-5
provider: pi
source_hash: 911a57f0f3b78412c26312f7bf87a5a26418ab7b74e5e2eb40f16edefb6c6b8e
source_path: cli/logs.md
workflow: 14
---
# `openclaw logs`
通过 RPC 实时查看 Gateway 文件日志（支持远程模式）。
相关内容：
- 日志概述：[日志](/logging)
## 示例
```bash
openclaw logs
openclaw logs --follow
openclaw logs --json
openclaw logs --limit 500
```

52
docs/zh-CN/cli/memory.md Normal file
View File

@@ -0,0 +1,52 @@
---
read_when:
- 您想要索引或搜索语义记忆
- 您正在调试记忆可用性或索引问题
summary: "`openclaw memory`（status/index/search）的 CLI 参考"
title: memory
x-i18n:
generated_at: "2026-02-01T20:21:11Z"
model: claude-opus-4-5
provider: pi
source_hash: 95a9e94306f95be2218a909be59be5bbaa5d31322b71b23564c71a89c3a3941a
source_path: cli/memory.md
workflow: 14
---
# `openclaw memory`
管理语义记忆的索引和搜索。
由活跃的记忆插件提供（默认：`memory-core`；设置 `plugins.slots.memory = "none"` 可禁用）。
相关内容：
- 记忆概念：[记忆](/concepts/memory)
- 插件：[插件](/plugins)
## 示例
```bash
openclaw memory status
openclaw memory status --deep
openclaw memory status --deep --index
openclaw memory status --deep --index --verbose
openclaw memory index
openclaw memory index --verbose
openclaw memory search "release checklist"
openclaw memory status --agent main
openclaw memory index --agent main --verbose
```
## 选项
通用选项：
- `--agent <id>`：限定到单个智能体（默认：所有已配置的智能体）。
- `--verbose`：在探测和索引期间输出详细日志。
说明：
- `memory status --deep` 探测向量存储和嵌入模型的可用性。
- `memory status --deep --index` 在存储有未同步变更时运行重新索引。
- `memory index --verbose` 打印每个阶段的详细信息（提供商、模型、数据源、批处理活动）。
- `memory status` 包含通过 `memorySearch.extraPaths` 配置的所有额外路径。

246
docs/zh-CN/cli/message.md Normal file
View File

@@ -0,0 +1,246 @@
---
read_when:
- 添加或修改消息 CLI 操作
- 更改出站渠道行为
summary: "`openclaw message`（发送 + 渠道操作）的 CLI 参考"
title: message
x-i18n:
generated_at: "2026-02-01T20:21:30Z"
model: claude-opus-4-5
provider: pi
source_hash: 35159baf1ef7136252e3ab1e5e03881ebc4196dd43425e2319a39306ced7f48c
source_path: cli/message.md
workflow: 14
---
# `openclaw message`
用于发送消息和渠道操作的单一出站命令
（Discord/Google Chat/Slack/Mattermost（插件）/Telegram/WhatsApp/Signal/iMessage/MS Teams）。
## 用法
```
openclaw message <subcommand> [flags]
```
渠道选择：
- 如果配置了多个渠道，则必须指定 `--channel`。
- 如果只配置了一个渠道，则该渠道为默认值。
- 可选值：`whatsapp|telegram|discord|googlechat|slack|mattermost|signal|imessage|msteams`（Mattermost 需要插件）
目标格式（`--target`）：
- WhatsApp：E.164 或群组 JID
- Telegram：聊天 ID 或 `@username`
- Discord：`channel:<id>` 或 `user:<id>`（或 `<@id>` 提及；纯数字 ID 被视为频道）
- Google Chat：`spaces/<spaceId>` 或 `users/<userId>`
- Slack：`channel:<id>` 或 `user:<id>`（接受纯频道 ID）
- Mattermost（插件）：`channel:<id>`、`user:<id>` 或 `@username`（纯 ID 被视为频道）
- Signal：`+E.164`、`group:<id>`、`signal:+E.164`、`signal:group:<id>` 或 `username:<name>`/`u:<name>`
- iMessage：句柄、`chat_id:<id>`、`chat_guid:<guid>` 或 `chat_identifier:<id>`
- MS Teams：会话 ID（`19:...@thread.tacv2`）或 `conversation:<id>` 或 `user:<aad-object-id>`
名称查找：
- 对于支持的提供商（Discord/Slack 等），如 `Help` 或 `#help` 之类的频道名称会通过目录缓存进行解析。
- 缓存未命中时，如果提供商支持，OpenClaw 将尝试实时目录查找。
## 通用标志
- `--channel <name>`
- `--account <id>`
- `--target <dest>`（用于 send/poll/read 等的目标渠道或用户）
- `--targets <name>`（可重复；仅限广播）
- `--json`
- `--dry-run`
- `--verbose`
## 操作
### 核心
- `send`
- 渠道：WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost（插件）/Signal/iMessage/MS Teams
- 必需：`--target`，以及 `--message` 或 `--media`
- 可选：`--media`、`--reply-to`、`--thread-id`、`--gif-playback`
- 仅限 Telegram：`--buttons`（需要 `channels.telegram.capabilities.inlineButtons` 以启用）
- 仅限 Telegram：`--thread-id`（论坛主题 ID）
- 仅限 Slack：`--thread-id`（线程时间戳；`--reply-to` 使用相同字段）
- 仅限 WhatsApp：`--gif-playback`
- `poll`
- 渠道：WhatsApp/Discord/MS Teams
- 必需：`--target`、`--poll-question`、`--poll-option`（可重复）
- 可选：`--poll-multi`
- 仅限 Discord：`--poll-duration-hours`、`--message`
- `react`
- 渠道：Discord/Google Chat/Slack/Telegram/WhatsApp/Signal
- 必需：`--message-id`、`--target`
- 可选：`--emoji`、`--remove`、`--participant`、`--from-me`、`--target-author`、`--target-author-uuid`
- 注意：`--remove` 需要 `--emoji`（省略 `--emoji` 可清除自己的表情回应（如果支持）；参见 /tools/reactions）
- 仅限 WhatsApp：`--participant`、`--from-me`
- Signal 群组表情回应：需要 `--target-author` 或 `--target-author-uuid`
- `reactions`
- 渠道：Discord/Google Chat/Slack
- 必需：`--message-id`、`--target`
- 可选：`--limit`
- `read`
- 渠道：Discord/Slack
- 必需：`--target`
- 可选：`--limit`、`--before`、`--after`
- 仅限 Discord：`--around`
- `edit`
- 渠道：Discord/Slack
- 必需：`--message-id`、`--message`、`--target`
- `delete`
- 渠道：Discord/Slack/Telegram
- 必需：`--message-id`、`--target`
- `pin` / `unpin`
- 渠道：Discord/Slack
- 必需：`--message-id`、`--target`
- `pins`（列表）
- 渠道：Discord/Slack
- 必需：`--target`
- `permissions`
- 渠道：Discord
- 必需：`--target`
- `search`
- 渠道：Discord
- 必需：`--guild-id`、`--query`
- 可选：`--channel-id`、`--channel-ids`（可重复）、`--author-id`、`--author-ids`（可重复）、`--limit`
### 线程
- `thread create`
- 渠道：Discord
- 必需：`--thread-name`、`--target`（频道 ID）
- 可选：`--message-id`、`--auto-archive-min`
- `thread list`
- 渠道：Discord
- 必需：`--guild-id`
- 可选：`--channel-id`、`--include-archived`、`--before`、`--limit`
- `thread reply`
- 渠道：Discord
- 必需：`--target`（线程 ID）、`--message`
- 可选：`--media`、`--reply-to`
### 表情符号
- `emoji list`
- Discord：`--guild-id`
- Slack：无需额外标志
- `emoji upload`
- 渠道：Discord
- 必需：`--guild-id`、`--emoji-name`、`--media`
- 可选：`--role-ids`（可重复）
### 贴纸
- `sticker send`
- 渠道：Discord
- 必需：`--target`、`--sticker-id`（可重复）
- 可选：`--message`
- `sticker upload`
- 渠道：Discord
- 必需：`--guild-id`、`--sticker-name`、`--sticker-desc`、`--sticker-tags`、`--media`
### 角色 / 频道 / 成员 / 语音
- `role info`（Discord）：`--guild-id`
- `role add` / `role remove`（Discord）：`--guild-id`、`--user-id`、`--role-id`
- `channel info`（Discord）：`--target`
- `channel list`（Discord）：`--guild-id`
- `member info`（Discord/Slack）：`--user-id`（Discord 还需要 `--guild-id`）
- `voice status`（Discord）：`--guild-id`、`--user-id`
### 事件
- `event list`（Discord）：`--guild-id`
- `event create`（Discord）：`--guild-id`、`--event-name`、`--start-time`
- 可选：`--end-time`、`--desc`、`--channel-id`、`--location`、`--event-type`
### 管理（Discord）
- `timeout`：`--guild-id`、`--user-id`（可选 `--duration-min` 或 `--until`；两者都省略则清除超时）
- `kick`：`--guild-id`、`--user-id`（+ `--reason`）
- `ban`：`--guild-id`、`--user-id`（+ `--delete-days`、`--reason`）
- `timeout` 也支持 `--reason`
### 广播
- `broadcast`
- 渠道：任何已配置的渠道；使用 `--channel all` 可针对所有提供商
- 必需：`--targets`（可重复）
- 可选：`--message`、`--media`、`--dry-run`
## 示例
发送 Discord 回复：
```
openclaw message send --channel discord \
--target channel:123 --message "hi" --reply-to 456
```
创建 Discord 投票：
```
openclaw message poll --channel discord \
--target channel:123 \
--poll-question "Snack?" \
--poll-option Pizza --poll-option Sushi \
--poll-multi --poll-duration-hours 48
```
发送 Teams 主动消息：
```
openclaw message send --channel msteams \
--target conversation:19:abc@thread.tacv2 --message "hi"
```
创建 Teams 投票：
```
openclaw message poll --channel msteams \
--target conversation:19:abc@thread.tacv2 \
--poll-question "Lunch?" \
--poll-option Pizza --poll-option Sushi
```
在 Slack 中添加表情回应：
```
openclaw message react --channel slack \
--target C123 --message-id 456 --emoji "✅"
```
在 Signal 群组中添加表情回应：
```
openclaw message react --channel signal \
--target signal:group:abc123 --message-id 1737630212345 \
--emoji "✅" --target-author-uuid 123e4567-e89b-12d3-a456-426614174000
```
发送 Telegram 内联按钮：
```
openclaw message send --channel telegram --target @mychat --message "Choose:" \
--buttons '[ [{"text":"Yes","callback_data":"cmd:yes"}], [{"text":"No","callback_data":"cmd:no"}] ]'
```

85
docs/zh-CN/cli/models.md Normal file
View File

@@ -0,0 +1,85 @@
---
read_when:
- 您想更改默认模型或查看提供商认证状态
- 您想扫描可用的模型/提供商并调试认证配置
summary: "`openclaw models` 的 CLI 参考（status/list/set/scan、别名、回退、认证）"
title: models
x-i18n:
generated_at: "2026-02-01T20:21:16Z"
model: claude-opus-4-5
provider: pi
source_hash: 923b6ffc7de382ba25bc6e699f0515607e74877b39f2136ccdba2d99e1b1e9c3
source_path: cli/models.md
workflow: 14
---
# `openclaw models`
模型发现、扫描和配置（默认模型、回退、认证配置）。
相关内容：
- 提供商 + 模型：[模型](/providers/models)
- 提供商认证设置：[快速开始](/start/getting-started)
## 常用命令
```bash
openclaw models status
openclaw models list
openclaw models set <model-or-alias>
openclaw models scan
```
`openclaw models status` 显示已解析的默认模型/回退配置以及认证概览。
当提供商使用快照可用时，OAuth/令牌状态部分会包含提供商使用头信息。
添加 `--probe` 可对每个已配置的提供商配置运行实时认证探测。
探测会发送真实请求（可能消耗令牌并触发速率限制）。
使用 `--agent <id>` 可检查已配置智能体的模型/认证状态。省略时，
命令会使用 `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`（如已设置），否则使用
已配置的默认智能体。
注意事项：
- `models set <model-or-alias>` 接受 `provider/model` 或别名。
- 模型引用通过在**第一个** `/` 处拆分来解析。如果模型 ID 包含 `/`（OpenRouter 风格），需包含提供商前缀（示例：`openrouter/moonshotai/kimi-k2`）。
- 如果省略提供商，OpenClaw 会将输入视为别名或**默认提供商**的模型（仅在模型 ID 不包含 `/` 时有效）。
### `models status`
选项：
- `--json`
- `--plain`
- `--check`（退出码 1=已过期/缺失，2=即将过期）
- `--probe`（对已配置的认证配置进行实时探测）
- `--probe-provider <name>`（探测单个提供商）
- `--probe-profile <id>`（可重复或逗号分隔的配置 ID）
- `--probe-timeout <ms>`
- `--probe-concurrency <n>`
- `--probe-max-tokens <n>`
- `--agent <id>`（已配置的智能体 ID；覆盖 `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`）
## 别名 + 回退
```bash
openclaw models aliases list
openclaw models fallbacks list
```
## 认证配置
```bash
openclaw models auth add
openclaw models auth login --provider <id>
openclaw models auth setup-token
openclaw models auth paste-token
```
`models auth login` 运行提供商插件的认证流程（OAuth/API 密钥）。使用
`openclaw plugins list` 查看已安装的提供商。
注意事项：
- `setup-token` 会提示输入 setup-token 值（在任意机器上使用 `claude setup-token` 生成）。
- `paste-token` 接受在其他地方或通过自动化生成的令牌字符串。

115
docs/zh-CN/cli/node.md Normal file
View File

@@ -0,0 +1,115 @@
---
read_when:
- 运行无头节点主机
- 为 system.run 配对非 macOS 节点
summary: "`openclaw node`（无头节点主机）的 CLI 参考"
title: node
x-i18n:
generated_at: "2026-02-01T20:21:18Z"
model: claude-opus-4-5
provider: pi
source_hash: a8b1a57712663e2285c9ecd306fe57d067eb3e6820d7d8aec650b41b022d995a
source_path: cli/node.md
workflow: 14
---
# `openclaw node`
运行一个**无头节点主机**，连接到 Gateway WebSocket 并在本机上暴露
`system.run` / `system.which`。
## 为什么使用节点主机？
当你希望智能体**在网络中的其他机器上运行命令**，而无需在那些机器上安装完整的 macOS 伴侣应用时，可以使用节点主机。
常见用例：
- 在远程 Linux/Windows 机器上运行命令（构建服务器、实验室机器、NAS）。
- 在 Gateway 上保持执行**沙箱化**，但将已批准的运行委派给其他主机。
- 为自动化或 CI 节点提供轻量级、无头的执行目标。
执行仍受**执行审批**和节点主机上的按智能体白名单保护，因此你可以保持命令访问的范围明确可控。
## 浏览器代理（零配置）
如果节点上的 `browser.enabled` 未被禁用，节点主机会自动通告浏览器代理。这使智能体无需额外配置即可在该节点上使用浏览器自动化。
如需在节点上禁用：
```json5
{
nodeHost: {
browserProxy: {
enabled: false,
},
},
}
```
## 前台运行
```bash
openclaw node run --host <gateway-host> --port 18789
```
选项：
- `--host <host>`：Gateway WebSocket 主机（默认：`127.0.0.1`）
- `--port <port>`：Gateway WebSocket 端口（默认：`18789`）
- `--tls`：为 Gateway 连接使用 TLS
- `--tls-fingerprint <sha256>`：预期的 TLS 证书指纹（sha256）
- `--node-id <id>`：覆盖节点 ID（清除配对令牌）
- `--display-name <name>`：覆盖节点显示名称
## 服务（后台运行）
将无头节点主机安装为用户服务。
```bash
openclaw node install --host <gateway-host> --port 18789
```
选项：
- `--host <host>`：Gateway WebSocket 主机（默认：`127.0.0.1`）
- `--port <port>`：Gateway WebSocket 端口（默认：`18789`）
- `--tls`：为 Gateway 连接使用 TLS
- `--tls-fingerprint <sha256>`：预期的 TLS 证书指纹（sha256）
- `--node-id <id>`：覆盖节点 ID（清除配对令牌）
- `--display-name <name>`：覆盖节点显示名称
- `--runtime <runtime>`：服务运行时（`node` 或 `bun`）
- `--force`：如果已安装则重新安装/覆盖
管理服务：
```bash
openclaw node status
openclaw node stop
openclaw node restart
openclaw node uninstall
```
使用 `openclaw node run` 进行前台节点主机运行（无服务）。
服务命令支持 `--json` 以获取机器可读输出。
## 配对
首次连接会在 Gateway 上创建一个待处理的节点配对请求。
通过以下方式批准：
```bash
openclaw nodes pending
openclaw nodes approve <requestId>
```
节点主机将其节点 ID、令牌、显示名称和 Gateway 连接信息存储在
`~/.openclaw/node.json` 中。
## 执行审批
`system.run` 受本地执行审批控制：
- `~/.openclaw/exec-approvals.json`
- [执行审批](/tools/exec-approvals)
- `openclaw approvals --node <id|name|ip>`（从 Gateway 编辑）

79
docs/zh-CN/cli/nodes.md Normal file
View File

@@ -0,0 +1,79 @@
---
read_when:
- 正在管理配对节点（摄像头、屏幕、画布）
- 需要批准请求或调用节点命令
summary: 管理配对节点（列表/状态/批准/调用，摄像头/画布/屏幕）的 `openclaw nodes` CLI 参考
title: nodes
x-i18n:
generated_at: "2026-02-01T20:21:19Z"
model: claude-opus-4-5
provider: pi
source_hash: 23da6efdd659a82dbbc4afd18eb4ab1020a2892f69c28d610f912c8a799f734c
source_path: cli/nodes.md
workflow: 14
---
# `openclaw nodes`
管理配对节点（设备）并调用节点功能。
相关内容：
- 节点概述：[节点](/nodes)
- 摄像头：[摄像头节点](/nodes/camera)
- 图像：[图像节点](/nodes/images)
常用选项：
- `--url`、`--token`、`--timeout`、`--json`
## 常用命令
```bash
openclaw nodes list
openclaw nodes list --connected
openclaw nodes list --last-connected 24h
openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes status
openclaw nodes status --connected
openclaw nodes status --last-connected 24h
```
`nodes list` 输出待处理/已配对的表格。已配对的行包含最近一次连接的时间间隔（Last Connect）。
使用 `--connected` 仅显示当前已连接的节点。使用 `--last-connected <duration>` 筛选在指定时间段内连接过的节点（例如 `24h`、`7d`）。
## 调用 / 运行
```bash
openclaw nodes invoke --node <id|name|ip> --command <command> --params <json>
openclaw nodes run --node <id|name|ip> <command...>
openclaw nodes run --raw "git status"
openclaw nodes run --agent main --node <id|name|ip> --raw "git status"
```
调用标志：
- `--params <json>`：JSON 对象字符串（默认 `{}`）。
- `--invoke-timeout <ms>`：节点调用超时时间（默认 `15000`）。
- `--idempotency-key <key>`：可选的幂等键。
### Exec 风格的默认行为
`nodes run` 模拟模型的 exec 行为（默认值 + 审批）：
- 读取 `tools.exec.*`（以及 `agents.list[].tools.exec.*` 的覆盖配置）。
- 在调用 `system.run` 之前使用 exec 审批（`exec.approval.request`）。
- 当设置了 `tools.exec.node` 时，可以省略 `--node`。
- 需要一个声明支持 `system.run` 的节点（macOS 伴侣应用或无头节点主机）。
标志：
- `--cwd <path>`：工作目录。
- `--env <key=val>`：环境变量覆盖（可重复使用）。
- `--command-timeout <ms>`：命令超时时间。
- `--invoke-timeout <ms>`：节点调用超时时间（默认 `30000`）。
- `--needs-screen-recording`：要求屏幕录制权限。
- `--raw <command>`：运行 shell 字符串（`/bin/sh -lc` 或 `cmd.exe /c`）。
- `--agent <id>`：智能体范围的审批/白名单（默认为已配置的智能体）。
- `--ask <off|on-miss|always>`、`--security <deny|allowlist|full>`：覆盖选项。

36
docs/zh-CN/cli/onboard.md Normal file
View File

@@ -0,0 +1,36 @@
---
read_when:
- 您想要通过引导式设置配置 Gateway、工作区、认证、渠道和技能
summary: "`openclaw onboard`（交互式上手引导向导）的 CLI 参考"
title: onboard
x-i18n:
generated_at: "2026-02-01T20:21:15Z"
model: claude-opus-4-5
provider: pi
source_hash: a661049a6983233986a880a68440a3bcc6869ee2c4c6f5e9f3ab8ff973e22f60
source_path: cli/onboard.md
workflow: 14
---
# `openclaw onboard`
交互式上手引导向导（本地或远程 Gateway 设置）。
相关内容：
- 向导指南：[上手引导](/start/onboarding)
## 示例
```bash
openclaw onboard
openclaw onboard --flow quickstart
openclaw onboard --flow manual
openclaw onboard --mode remote --remote-url ws://gateway-host:18789
```
流程说明：
- `quickstart`：最少提示，自动生成 Gateway 令牌。
- `manual`：完整的端口/绑定/认证提示（`advanced` 的别名）。
- 最快开始聊天的方式：`openclaw dashboard`（控制台 UI，无需渠道设置）。

28
docs/zh-CN/cli/pairing.md Normal file
View File

@@ -0,0 +1,28 @@
---
read_when:
- 您正在使用配对模式的私信功能，需要批准发送者
summary: "`openclaw pairing`（批准/列出配对请求）的 CLI 参考"
title: pairing
x-i18n:
generated_at: "2026-02-01T20:21:19Z"
model: claude-opus-4-5
provider: pi
source_hash: e0bc9707294463c95d13e0deb67d834cfad6a105ab44baf4c25592e5de65ddf5
source_path: cli/pairing.md
workflow: 14
---
# `openclaw pairing`
批准或检查私信配对请求（适用于支持配对的渠道）。
相关内容：
- 配对流程：[配对](/start/pairing)
## 命令
```bash
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <code> --notify
```

66
docs/zh-CN/cli/plugins.md Normal file
View File

@@ -0,0 +1,66 @@
---
read_when:
- 您想安装或管理进程内 Gateway 插件
- 您想调试插件加载失败问题
summary: "`openclaw plugins` 的 CLI 参考（list、install、enable/disable、doctor）"
title: plugins
x-i18n:
generated_at: "2026-02-01T20:21:23Z"
model: claude-opus-4-5
provider: pi
source_hash: c6bf76b1e766b912ec30a0101d455151c88f1a778bffa121cdd1d0b4fbe73e1c
source_path: cli/plugins.md
workflow: 14
---
# `openclaw plugins`
管理 Gateway 插件/扩展（进程内加载）。
相关内容：
- 插件系统：[插件](/plugin)
- 插件清单 + schema：[插件清单](/plugins/manifest)
- 安全加固：[安全](/gateway/security)
## 命令
```bash
openclaw plugins list
openclaw plugins info <id>
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins doctor
openclaw plugins update <id>
openclaw plugins update --all
```
内置插件随 OpenClaw 一起分发，但默认处于禁用状态。使用 `plugins enable` 来激活它们。
所有插件必须附带一个 `openclaw.plugin.json` 文件，其中包含内联 JSON Schema（`configSchema`，即使为空也需要）。缺失或无效的清单或 schema 会导致插件无法加载，并使配置验证失败。
### 安装
```bash
openclaw plugins install <path-or-spec>
```
安全提示：安装插件等同于运行代码，请优先使用固定版本。
支持的归档格式：`.zip`、`.tgz`、`.tar.gz`、`.tar`。
使用 `--link` 可避免复制本地目录（会添加到 `plugins.load.paths`）：
```bash
openclaw plugins install -l ./my-plugin
```
### 更新
```bash
openclaw plugins update <id>
openclaw plugins update --all
openclaw plugins update <id> --dry-run
```
更新仅适用于从 npm 安装的插件（在 `plugins.installs` 中跟踪）。

24
docs/zh-CN/cli/reset.md Normal file
View File

@@ -0,0 +1,24 @@
---
read_when:
- 你想在保留 CLI 安装的同时清除本地状态
- 你想预览哪些内容会被移除
summary: "`openclaw reset`（重置本地状态/配置）的 CLI 参考"
title: reset
x-i18n:
generated_at: "2026-02-01T20:21:22Z"
model: claude-opus-4-5
provider: pi
source_hash: 08afed5830f892e07d6e2e167f09aaf2d79fd5b2ba2a26a65dca857ebdbf873c
source_path: cli/reset.md
workflow: 14
---
# `openclaw reset`
重置本地配置/状态（保留 CLI 安装）。
```bash
openclaw reset
openclaw reset --dry-run
openclaw reset --scope config+creds+sessions --yes --non-interactive
```

158
docs/zh-CN/cli/sandbox.md Normal file
View File

@@ -0,0 +1,158 @@
---
read_when: 您正在管理沙箱容器或调试沙箱/工具策略行为。
status: active
summary: 管理沙箱容器并检查生效的沙箱策略
title: Sandbox CLI
x-i18n:
generated_at: "2026-02-01T20:21:35Z"
model: claude-opus-4-5
provider: pi
source_hash: 6e1186f26c77e188206ce5e198ab624d6b38bc7bb7c06e4d2281b6935c39e347
source_path: cli/sandbox.md
workflow: 14
---
# Sandbox CLI
管理基于 Docker 的沙箱容器，用于隔离智能体执行。
## 概述
OpenClaw 可以在隔离的 Docker 容器中运行智能体以确保安全性。`sandbox` 命令帮助您管理这些容器，尤其是在更新或配置变更之后。
## 命令
### `openclaw sandbox explain`
检查**生效的**沙箱模式/作用域/工作区访问权限、沙箱工具策略以及提权门控（附带修复建议的配置键路径）。
```bash
openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json
```
### `openclaw sandbox list`
列出所有沙箱容器及其状态和配置。
```bash
openclaw sandbox list
openclaw sandbox list --browser # 仅列出浏览器容器
openclaw sandbox list --json # JSON 输出
```
**输出包括：**
- 容器名称和状态（运行中/已停止）
- Docker 镜像及其是否与配置匹配
- 存在时间（自创建以来的时长）
- 空闲时间（自上次使用以来的时长）
- 关联的会话/智能体
### `openclaw sandbox recreate`
移除沙箱容器，以便使用更新的镜像/配置强制重新创建。
```bash
openclaw sandbox recreate --all # 重新创建所有容器
openclaw sandbox recreate --session main # 指定会话
openclaw sandbox recreate --agent mybot # 指定智能体
openclaw sandbox recreate --browser # 仅浏览器容器
openclaw sandbox recreate --all --force # 跳过确认提示
```
**选项：**
- `--all`：重新创建所有沙箱容器
- `--session <key>`：重新创建指定会话的容器
- `--agent <id>`：重新创建指定智能体的容器
- `--browser`：仅重新创建浏览器容器
- `--force`：跳过确认提示
**重要提示：** 容器会在智能体下次使用时自动重新创建。
## 使用场景
### 更新 Docker 镜像后
```bash
# 拉取新镜像
docker pull openclaw-sandbox:latest
docker tag openclaw-sandbox:latest openclaw-sandbox:bookworm-slim
# 更新配置以使用新镜像
# 编辑配置：agents.defaults.sandbox.docker.image（或 agents.list[].sandbox.docker.image）
# 重新创建容器
openclaw sandbox recreate --all
```
### 更改沙箱配置后
```bash
# 编辑配置：agents.defaults.sandbox.*（或 agents.list[].sandbox.*）
# 重新创建以应用新配置
openclaw sandbox recreate --all
```
### 更改 setupCommand 后
```bash
openclaw sandbox recreate --all
# 或仅针对某个智能体：
openclaw sandbox recreate --agent family
```
### 仅针对特定智能体
```bash
# 仅更新某个智能体的容器
openclaw sandbox recreate --agent alfred
```
## 为什么需要这样做？
**问题：** 当您更新沙箱 Docker 镜像或配置时：
- 现有容器会继续使用旧设置运行
- 容器仅在空闲 24 小时后才会被清理
- 经常使用的智能体会无限期地保持旧容器运行
**解决方案：** 使用 `openclaw sandbox recreate` 强制移除旧容器。它们会在下次需要时自动使用当前设置重新创建。
提示：建议使用 `openclaw sandbox recreate` 而非手动执行 `docker rm`。它使用 Gateway 的容器命名规则，避免在作用域/会话键发生变化时出现不匹配问题。
## 配置
沙箱设置位于 `~/.openclaw/openclaw.json` 中的 `agents.defaults.sandbox` 下（按智能体覆盖的配置放在 `agents.list[].sandbox` 中）：
```jsonc
{
"agents": {
"defaults": {
"sandbox": {
"mode": "all", // off, non-main, all
"scope": "agent", // session, agent, shared
"docker": {
"image": "openclaw-sandbox:bookworm-slim",
"containerPrefix": "openclaw-sbx-",
// ... 更多 Docker 选项
},
"prune": {
"idleHours": 24, // 空闲 24 小时后自动清理
"maxAgeDays": 7, // 7 天后自动清理
},
},
},
},
}
```
## 另请参阅
- [沙箱文档](/gateway/sandboxing)
- [智能体配置](/concepts/agent-workspace)
- [Doctor 命令](/gateway/doctor) - 检查沙箱设置

33
docs/zh-CN/cli/security.md Normal file
View File

@@ -0,0 +1,33 @@
---
read_when:
- 想要对配置/状态进行快速安全审计
- 想要应用安全的"修复"建议（chmod、收紧默认值）
summary: 审计和修复常见安全隐患的 `openclaw security` CLI 参考
title: security
x-i18n:
generated_at: "2026-02-01T20:21:24Z"
model: claude-opus-4-5
provider: pi
source_hash: 19705b0fff848fa6f302b4ed09b7660c64e09048dba517c7f6a833d2db40bebf
source_path: cli/security.md
workflow: 14
---
# `openclaw security`
安全工具（审计 + 可选修复）。
相关内容：
- 安全指南：[安全](/gateway/security)
## 审计
```bash
openclaw security audit
openclaw security audit --deep
openclaw security audit --fix
```
当多个私信发送者共享主会话时，审计会发出警告，并建议共享收件箱使用 `session.dmScope="per-channel-peer"`（多账户渠道则使用 `per-account-channel-peer`）。
审计还会在小模型（`<=300B`）未启用沙箱且启用了 web/browser 工具时发出警告。

23
docs/zh-CN/cli/sessions.md Normal file
View File

@@ -0,0 +1,23 @@
---
read_when:
- 你想列出已存储的会话并查看近期活动
summary: "`openclaw sessions`（列出已存储的会话及使用情况）的 CLI 参考"
title: sessions
x-i18n:
generated_at: "2026-02-01T20:21:25Z"
model: claude-opus-4-5
provider: pi
source_hash: d8866ef166c0dea5e8d691bb62171298694935ae0771a46fada537774dadfb32
source_path: cli/sessions.md
workflow: 14
---
# `openclaw sessions`
列出已存储的对话会话。
```bash
openclaw sessions
openclaw sessions --active 120
openclaw sessions --json
```

36
docs/zh-CN/cli/setup.md Normal file
View File

@@ -0,0 +1,36 @@
---
read_when:
- 您在不使用完整上手引导向导的情况下进行首次设置
- 您想设置默认工作区路径
summary: "`openclaw setup` 的 CLI 参考（初始化配置 + 工作区）"
title: setup
x-i18n:
generated_at: "2026-02-01T20:21:26Z"
model: claude-opus-4-5
provider: pi
source_hash: 7f3fc8b246924edf48501785be2c0d356bd31bfbb133e75a139a5ee41dbf57f4
source_path: cli/setup.md
workflow: 14
---
# `openclaw setup`
初始化 `~/.openclaw/openclaw.json` 和智能体工作区。
相关内容：
- 快速开始：[快速开始](/start/getting-started)
- 向导：[上手引导](/start/onboarding)
## 示例
```bash
openclaw setup
openclaw setup --workspace ~/.openclaw/workspace
```
通过 setup 运行向导：
```bash
openclaw setup --wizard
```

33
docs/zh-CN/cli/skills.md Normal file
View File

@@ -0,0 +1,33 @@
---
read_when:
- 想要查看哪些技能可用且可以运行
- 想要调试技能缺失的二进制文件/环境变量/配置
summary: 技能列表/信息/检查及技能资格的 `openclaw skills` CLI 参考
title: skills
x-i18n:
generated_at: "2026-02-01T20:21:28Z"
model: claude-opus-4-5
provider: pi
source_hash: 7878442c88a27ec8033f3125c319e9a6a85a1c497a404a06112ad45185c261b0
source_path: cli/skills.md
workflow: 14
---
# `openclaw skills`
检查技能（内置 + 工作区 + 托管覆盖），查看哪些符合条件以及哪些缺少依赖。
相关内容：
- 技能系统：[技能](/tools/skills)
- 技能配置：[技能配置](/tools/skills-config)
- ClawHub 安装：[ClawHub](/tools/clawhub)
## 命令
```bash
openclaw skills list
openclaw skills list --eligible
openclaw skills info <name>
openclaw skills check
```

33
docs/zh-CN/cli/status.md Normal file
View File

@@ -0,0 +1,33 @@
---
read_when:
- 你想快速诊断渠道健康状况及近期会话接收者
- 你想获取可粘贴的完整状态信息用于调试
summary: "`openclaw status`（诊断、探测、使用情况快照）的 CLI 参考"
title: status
x-i18n:
generated_at: "2026-02-01T20:21:30Z"
model: claude-opus-4-5
provider: pi
source_hash: 2bbf5579c48034fc15c2cbd5506c50456230b17e4a74c06318968c590d8f1501
source_path: cli/status.md
workflow: 14
---
# `openclaw status`
渠道和会话的诊断信息。
```bash
openclaw status
openclaw status --all
openclaw status --deep
openclaw status --usage
```
说明：
- `--deep` 会运行实时探测（WhatsApp Web + Telegram + Discord + Google Chat + Slack + Signal）。
- 当配置了多个智能体时，输出包含每个智能体的会话存储。
- 概览包含 Gateway 和节点主机服务的安装/运行状态（如可用）。
- 概览包含更新渠道和 git SHA（适用于源码检出）。
- 更新信息会显示在概览中；如果有可用更新，状态会提示运行 `openclaw update`（参见[更新](/install/updating)）。

63
docs/zh-CN/cli/system.md Normal file
View File

@@ -0,0 +1,63 @@
---
read_when:
- 您想在不创建 cron 任务的情况下将系统事件加入队列
- 您需要启用或禁用心跳
- 您想检查系统存在状态条目
summary: "`openclaw system` 的 CLI 参考（系统事件、心跳、存在状态）"
title: system
x-i18n:
generated_at: "2026-02-01T20:21:34Z"
model: claude-opus-4-5
provider: pi
source_hash: 36ae5dbdec327f5a32f7ef44bdc1f161bad69868de62f5071bb4d25a71bfdfe9
source_path: cli/system.md
workflow: 14
---
# `openclaw system`
Gateway 的系统级辅助工具：将系统事件加入队列、控制心跳以及查看存在状态。
## 常用命令
```bash
openclaw system event --text "Check for urgent follow-ups" --mode now
openclaw system heartbeat enable
openclaw system heartbeat last
openclaw system presence
```
## `system event`
在**主**会话上将系统事件加入队列。下一次心跳会将其作为 `System:` 行注入到提示中。使用 `--mode now` 可立即触发心跳；`next-heartbeat` 则等待下一次计划的心跳周期。
标志：
- `--text <text>`：必需的系统事件文本。
- `--mode <mode>`：`now` 或 `next-heartbeat`（默认）。
- `--json`：机器可读输出。
## `system heartbeat last|enable|disable`
心跳控制：
- `last`：显示上一次心跳事件。
- `enable`：重新开启心跳（如果之前被禁用，请使用此命令）。
- `disable`：暂停心跳。
标志：
- `--json`：机器可读输出。
## `system presence`
列出 Gateway 已知的当前系统存在状态条目（节点、实例及类似状态行）。
标志：
- `--json`：机器可读输出。
## 注意事项
- 需要当前配置（本地或远程）可访问的运行中 Gateway。
- 系统事件是临时的，不会在重启后持久化。

30
docs/zh-CN/cli/tui.md Normal file
View File

@@ -0,0 +1,30 @@
---
read_when:
- 想要使用 Gateway 的终端 UI（支持远程）
- 想要从脚本传递 url/token/session
summary: 连接到 Gateway 的终端 UI 的 `openclaw tui` CLI 参考
title: tui
x-i18n:
generated_at: "2026-02-01T20:21:31Z"
model: claude-opus-4-5
provider: pi
source_hash: f0a97d92e08746a9d6a4f31d361ccad9aea4c3dc61cfafb310d88715f61cfb64
source_path: cli/tui.md
workflow: 14
---
# `openclaw tui`
打开连接到 Gateway 的终端 UI。
相关内容：
- TUI 指南：[TUI](/tui)
## 示例
```bash
openclaw tui
openclaw tui --url ws://127.0.0.1:18789 --token <token>
openclaw tui --session main --deliver
```

24
docs/zh-CN/cli/uninstall.md Normal file
View File

@@ -0,0 +1,24 @@
---
read_when:
- 您想移除 Gateway 服务和/或本地状态
- 您想先进行试运行
summary: "`openclaw uninstall`（移除 Gateway 服务 + 本地数据）的 CLI 参考"
title: uninstall
x-i18n:
generated_at: "2026-02-01T20:21:33Z"
model: claude-opus-4-5
provider: pi
source_hash: 8d6c3890923f18f95c12b76443d649a6b404934ebd054fb86a9fa1abae843fe4
source_path: cli/uninstall.md
workflow: 14
---
# `openclaw uninstall`
卸载 Gateway 服务 + 本地数据（CLI 保留）。
```bash
openclaw uninstall
openclaw uninstall --all --yes
openclaw uninstall --dry-run
```

101
docs/zh-CN/cli/update.md Normal file
View File

@@ -0,0 +1,101 @@
---
read_when:
- 你想安全地更新源码检出
- 你需要了解 `--update` 简写行为
summary: "`openclaw update`（安全的源码更新 + Gateway 自动重启）的 CLI 参考"
title: update
x-i18n:
generated_at: "2026-02-01T20:21:45Z"
model: claude-opus-4-5
provider: pi
source_hash: 3a08e8ac797612c498eef54ecb83e61c9a1ee5de09162a01dbb4b3bd72897206
source_path: cli/update.md
workflow: 14
---
# `openclaw update`
安全更新 OpenClaw 并在 stable/beta/dev 渠道之间切换。
如果你通过 **npm/pnpm** 安装（全局安装，无 git 元数据），更新将通过[更新](/install/updating)中的包管理器流程进行。
## 用法
```bash
openclaw update
openclaw update status
openclaw update wizard
openclaw update --channel beta
openclaw update --channel dev
openclaw update --tag beta
openclaw update --no-restart
openclaw update --json
openclaw --update
```
## 选项
- `--no-restart`：成功更新后跳过重启 Gateway 服务。
- `--channel <stable|beta|dev>`：设置更新渠道（git + npm；持久化到配置中）。
- `--tag <dist-tag|version>`：仅为本次更新覆盖 npm dist-tag 或版本。
- `--json`：输出机器可读的 `UpdateRunResult` JSON。
- `--timeout <seconds>`：每步超时时间（默认为 1200 秒）。
注意：降级需要确认，因为旧版本可能会破坏配置。
## `update status`
显示当前活跃的更新渠道 + git 标签/分支/SHA（适用于源码检出），以及更新可用性。
```bash
openclaw update status
openclaw update status --json
openclaw update status --timeout 10
```
选项：
- `--json`：输出机器可读的状态 JSON。
- `--timeout <seconds>`：检查超时时间（默认为 3 秒）。
## `update wizard`
交互式流程，用于选择更新渠道并确认更新后是否重启 Gateway（默认重启）。如果你选择 `dev` 但没有 git 检出，它会提供创建一个的选项。
## 工作原理
当你显式切换渠道（`--channel ...`）时，OpenClaw 也会保持安装方式一致：
- `dev` → 确保存在 git 检出（默认：`~/openclaw`，可通过 `OPENCLAW_GIT_DIR` 覆盖），更新它，并从该检出安装全局 CLI。
- `stable`/`beta` → 使用匹配的 dist-tag 从 npm 安装。
## Git 检出流程
渠道：
- `stable`：检出最新的非 beta 标签，然后构建 + doctor。
- `beta`：检出最新的 `-beta` 标签，然后构建 + doctor。
- `dev`：检出 `main`，然后 fetch + rebase。
概要流程：
1. 要求工作树干净（无未提交的更改）。
2. 切换到所选渠道（标签或分支）。
3. 拉取上游（仅 dev）。
4. 仅 dev：在临时工作树中进行预检 lint + TypeScript 构建；如果最新提交失败，会向前回溯最多 10 个提交以找到最新的可成功构建的提交。
5. Rebase 到所选提交（仅 dev）。
6. 安装依赖（优先使用 pnpm；回退到 npm）。
7. 构建项目 + 构建控制台 UI。
8. 运行 `openclaw doctor` 作为最终的"安全更新"检查。
9. 将插件同步到活跃渠道（dev 使用内置扩展；stable/beta 使用 npm）并更新通过 npm 安装的插件。
## `--update` 简写
`openclaw --update` 会重写为 `openclaw update`（便于在 shell 和启动脚本中使用）。
## 另请参阅
- `openclaw doctor`（在 git 检出上会提供先运行更新的选项）
- [开发渠道](/install/development-channels)
- [更新](/install/updating)
- [CLI 参考](/cli)

41
docs/zh-CN/cli/voicecall.md Normal file
View File

@@ -0,0 +1,41 @@
---
read_when:
- 使用语音通话插件并想了解 CLI 入口
- 想要 `voicecall call|continue|status|tail|expose` 的快速示例
summary: 语音通话插件命令的 `openclaw voicecall` CLI 参考
title: voicecall
x-i18n:
generated_at: "2026-02-01T20:21:37Z"
model: claude-opus-4-5
provider: pi
source_hash: d93aaee6f6f5c9ac468d8d2905cb23f0f2db75809408cb305c055505be9936f2
source_path: cli/voicecall.md
workflow: 14
---
# `openclaw voicecall`
`voicecall` 是一个由插件提供的命令。只有在安装并启用了语音通话插件时才会出现。
主要文档：
- 语音通话插件：[语音通话](/plugins/voice-call)
## 常用命令
```bash
openclaw voicecall status --call-id <id>
openclaw voicecall call --to "+15555550123" --message "Hello" --mode notify
openclaw voicecall continue --call-id <id> --message "Any questions?"
openclaw voicecall end --call-id <id>
```
## 暴露 Webhook（Tailscale）
```bash
openclaw voicecall expose --mode serve
openclaw voicecall expose --mode funnel
openclaw voicecall unexpose
```
安全提示：仅将 webhook 端点暴露给您信任的网络。尽可能优先使用 Tailscale Serve 而非 Funnel。

32
docs/zh-CN/cli/webhooks.md Normal file
View File

@@ -0,0 +1,32 @@
---
read_when:
- 您想将 Gmail Pub/Sub 事件接入 OpenClaw
- 您需要 Webhook 辅助命令
summary: "`openclaw webhooks`（Webhook 辅助工具 + Gmail Pub/Sub）的 CLI 参考"
title: webhooks
x-i18n:
generated_at: "2026-02-01T20:21:38Z"
model: claude-opus-4-5
provider: pi
source_hash: 785ec62afe6631b340ce4a4541ceb34cd6b97704cf7a9889762cb4c1f29a5ca0
source_path: cli/webhooks.md
workflow: 14
---
# `openclaw webhooks`
Webhook 辅助工具和集成（Gmail Pub/Sub、Webhook 辅助工具）。
相关内容：
- Webhook：[Webhook](/automation/webhook)
- Gmail Pub/Sub：[Gmail Pub/Sub](/automation/gmail-pubsub)
## Gmail
```bash
openclaw webhooks gmail setup --account you@example.com
openclaw webhooks gmail run
```
详情请参阅 [Gmail Pub/Sub 文档](/automation/gmail-pubsub)。

150
docs/zh-CN/concepts/agent-loop.md Normal file
View File

@@ -0,0 +1,150 @@
---
read_when:
- 您需要智能体循环或生命周期事件的详细说明
summary: 智能体循环生命周期、流和等待语义
title: 智能体循环
x-i18n:
generated_at: "2026-02-01T20:22:03Z"
model: claude-opus-4-5
provider: pi
source_hash: 0775b96eb3451e137297661a1095eaefb2bafeebb5f78123174a46290e18b014
source_path: concepts/agent-loop.md
workflow: 14
---
# 智能体循环（OpenClaw）
智能体循环是智能体的一次完整"真实"运行：接收 → 上下文组装 → 模型推理 →
工具执行 → 流式回复 → 持久化。它是将消息转化为操作和最终回复的权威路径，同时保持会话状态的一致性。
在 OpenClaw 中，循环是每个会话的单次序列化运行，在模型思考、调用工具和流式输出时发出生命周期和流事件。本文档解释了这个完整循环是如何端到端连接的。
## 入口点
- Gateway RPC：`agent` 和 `agent.wait`。
- CLI：`agent` 命令。
## 工作原理（高层概述）
1. `agent` RPC 验证参数，解析会话（sessionKey/sessionId），持久化会话元数据，立即返回 `{ runId, acceptedAt }`。
2. `agentCommand` 运行智能体：
- 解析模型 + thinking/verbose 默认值
- 加载技能快照
- 调用 `runEmbeddedPiAgent`（pi-agent-core 运行时）
- 如果嵌入式循环未发出**生命周期 end/error** 事件，则补充发出
3. `runEmbeddedPiAgent`：
- 通过每会话 + 全局队列序列化运行
- 解析模型 + 认证配置并构建 pi 会话
- 订阅 pi 事件并流式传输助手/工具增量
- 强制执行超时 -> 超时则中止运行
- 返回载荷 + 使用量元数据
4. `subscribeEmbeddedPiSession` 将 pi-agent-core 事件桥接到 OpenClaw `agent` 流：
- 工具事件 => `stream: "tool"`
- 助手增量 => `stream: "assistant"`
- 生命周期事件 => `stream: "lifecycle"`（`phase: "start" | "end" | "error"`）
5. `agent.wait` 使用 `waitForAgentJob`：
- 等待 `runId` 的**生命周期 end/error**
- 返回 `{ status: ok|error|timeout, startedAt, endedAt, error? }`
## 队列 + 并发
- 运行按会话键（会话通道）序列化，并可选择通过全局通道进行。
- 这可以防止工具/会话竞争并保持会话历史的一致性。
- 消息渠道可以选择队列模式（collect/steer/followup）来供给此通道系统。
参见[命令队列](/concepts/queue)。
## 会话 + 工作区准备
- 工作区被解析并创建；沙箱运行可能会重定向到沙箱工作区根目录。
- 技能被加载（或从快照中复用）并注入到环境和提示中。
- 引导/上下文文件被解析并注入到系统提示报告中。
- 获取会话写锁；在流式传输之前打开并准备 `SessionManager`。
## 提示组装 + 系统提示
- 系统提示由 OpenClaw 的基础提示、技能提示、引导上下文和每次运行的覆盖项构建而成。
- 强制执行模型特定的限制和压缩预留令牌数。
- 参见[系统提示](/concepts/system-prompt)了解模型所看到的内容。
## 钩子点（可拦截的位置）
OpenClaw 有两个钩子系统：
- **内部钩子**（Gateway 钩子）：用于命令和生命周期事件的事件驱动脚本。
- **插件钩子**：智能体/工具生命周期和 Gateway 管道中的扩展点。
### 内部钩子（Gateway 钩子）
- **`agent:bootstrap`**：在系统提示最终确定之前构建引导文件时运行。
用于添加/移除引导上下文文件。
- **命令钩子**：`/new`、`/reset`、`/stop` 和其他命令事件（参见钩子文档）。
参见[钩子](/hooks)了解设置和示例。
### 插件钩子（智能体 + Gateway 生命周期）
这些在智能体循环或 Gateway 管道内运行：
- **`before_agent_start`**：在运行开始前注入上下文或覆盖系统提示。
- **`agent_end`**：在完成后检查最终消息列表和运行元数据。
- **`before_compaction` / `after_compaction`**：观察或标注压缩周期。
- **`before_tool_call` / `after_tool_call`**：拦截工具参数/结果。
- **`tool_result_persist`**：在工具结果写入会话记录之前同步转换工具结果。
- **`message_received` / `message_sending` / `message_sent`**：入站 + 出站消息钩子。
- **`session_start` / `session_end`**：会话生命周期边界。
- **`gateway_start` / `gateway_stop`**：Gateway 生命周期事件。
参见[插件](/plugin#plugin-hooks)了解钩子 API 和注册详情。
## 流式传输 + 部分回复
- 助手增量从 pi-agent-core 流式传输并作为 `assistant` 事件发出。
- 块流式传输可以在 `text_end` 或 `message_end` 时发出部分回复。
- 推理流式传输可以作为单独的流或作为块回复发出。
- 参见[流式传输](/concepts/streaming)了解分块和块回复行为。
## 工具执行 + 消息工具
- 工具的 start/update/end 事件在 `tool` 流上发出。
- 工具结果在记录/发出之前会针对大小和图片载荷进行清理。
- 消息工具的发送会被跟踪，以抑制重复的助手确认。
## 回复整形 + 抑制
- 最终载荷由以下内容组装：
- 助手文本（及可选的推理内容）
- 内联工具摘要（当 verbose + 允许时）
- 模型出错时的助手错误文本
- `NO_REPLY` 被视为静默令牌，从传出载荷中过滤。
- 消息工具的重复项从最终载荷列表中移除。
- 如果没有可渲染的载荷且工具出错，则发出回退的工具错误回复
（除非消息工具已发送了用户可见的回复）。
## 压缩 + 重试
- 自动压缩发出 `compaction` 流事件，并可能触发重试。
- 重试时，内存缓冲区和工具摘要会被重置以避免重复输出。
- 参见[压缩](/concepts/compaction)了解压缩管道。
## 事件流（当前）
- `lifecycle`：由 `subscribeEmbeddedPiSession` 发出（以及作为 `agentCommand` 的回退）
- `assistant`：来自 pi-agent-core 的流式增量
- `tool`：来自 pi-agent-core 的流式工具事件
## 聊天渠道处理
- 助手增量被缓冲为聊天 `delta` 消息。
- 在**生命周期 end/error** 时发出聊天 `final`。
## 超时
- `agent.wait` 默认值：30 秒（仅等待阶段）。`timeoutMs` 参数可覆盖。
- 智能体运行时：`agents.defaults.timeoutSeconds` 默认 600 秒；在 `runEmbeddedPiAgent` 中止计时器中强制执行。
## 可能提前结束的情况
- 智能体超时（中止）
- AbortSignal（取消）
- Gateway 断开连接或 RPC 超时
- `agent.wait` 超时（仅等待阶段，不会停止智能体）

214
docs/zh-CN/concepts/agent-workspace.md Normal file
View File

@@ -0,0 +1,214 @@
---
read_when:
- 您需要解释智能体工作区或其文件布局
- 您想要备份或迁移智能体工作区
summary: 智能体工作区：位置、布局和备份策略
title: 智能体工作区
x-i18n:
generated_at: "2026-02-01T20:22:05Z"
model: claude-opus-4-5
provider: pi
source_hash: 84c550fd89b5f2474aeae586795485fd29d36effbb462f13342b31540fc18b82
source_path: concepts/agent-workspace.md
workflow: 14
---
# 智能体工作区
工作区是智能体的主目录。它是文件工具和工作区上下文使用的唯一工作目录。请将其保持私密，并视为记忆来对待。
它与 `~/.openclaw/` 是分开的，后者存储配置、凭据和会话。
**重要提示：** 工作区是**默认工作目录**，而非硬性沙箱。工具会基于工作区解析相对路径，但绝对路径仍然可以访问主机上的其他位置，除非启用了沙箱。如果您需要隔离，请使用 [`agents.defaults.sandbox`](/gateway/sandboxing)（和/或按智能体的沙箱配置）。当启用沙箱且 `workspaceAccess` 不是 `"rw"` 时，工具在 `~/.openclaw/sandboxes` 下的沙箱工作区中运行，而非您的主机工作区。
## 默认位置
- 默认：`~/.openclaw/workspace`
- 如果设置了 `OPENCLAW_PROFILE` 且不是 `"default"`，则默认变为
`~/.openclaw/workspace-<profile>`。
- 在 `~/.openclaw/openclaw.json` 中覆盖：
```json5
{
agent: {
workspace: "~/.openclaw/workspace",
},
}
```
`openclaw onboard`、`openclaw configure` 或 `openclaw setup` 将创建工作区，并在引导文件缺失时生成它们。
如果您已经自行管理工作区文件，可以禁用引导文件创建：
```json5
{ agent: { skipBootstrap: true } }
```
## 额外的工作区文件夹
较旧的安装可能创建了 `~/openclaw`。保留多个工作区目录可能会导致认证或状态不一致的困惑，因为同一时间只有一个工作区处于活跃状态。
**建议：** 保持单一活跃工作区。如果您不再使用额外的文件夹，请将其归档或移至回收站（例如 `trash ~/openclaw`）。如果您有意保留多个工作区，请确保 `agents.defaults.workspace` 指向活跃的那个。
`openclaw doctor` 在检测到额外工作区目录时会发出警告。
## 工作区文件映射（每个文件的含义）
以下是 OpenClaw 在工作区中期望的标准文件：
- `AGENTS.md`
- 智能体的操作指令以及它应如何使用记忆。
- 在每个会话开始时加载。
- 适合放置规则、优先级和"行为方式"的详细说明。
- `SOUL.md`
- 人设、语气和边界。
- 每个会话加载。
- `USER.md`
- 用户是谁以及如何称呼他们。
- 每个会话加载。
- `IDENTITY.md`
- 智能体的名称、风格和表情符号。
- 在引导仪式期间创建/更新。
- `TOOLS.md`
- 关于本地工具和约定的说明。
- 不控制工具可用性；仅作为指导。
- `HEARTBEAT.md`
- 可选的心跳运行小清单。
- 保持简短以避免消耗令牌。
- `BOOT.md`
- 可选的启动清单，在启用内部钩子时于 Gateway 重启时执行。
- 保持简短；使用消息工具进行外发。
- `BOOTSTRAP.md`
- 一次性首次运行仪式。
- 仅为全新工作区创建。
- 仪式完成后请删除它。
- `memory/YYYY-MM-DD.md`
- 每日记忆日志（每天一个文件）。
- 建议在会话开始时读取今天和昨天的内容。
- `MEMORY.md`（可选）
- 精选的长期记忆。
- 仅在主要的私人会话中加载（不在共享/群组上下文中）。
参见[记忆](/concepts/memory)了解工作流程和自动记忆刷写。
- `skills/`（可选）
- 工作区特定的技能。
- 名称冲突时覆盖托管/内置技能。
- `canvas/`（可选）
- 用于节点显示的 Canvas UI 文件（例如 `canvas/index.html`）。
如果任何引导文件缺失，OpenClaw 会在会话中注入"文件缺失"标记并继续运行。大型引导文件在注入时会被截断；可通过 `agents.defaults.bootstrapMaxChars`（默认：20000）调整限制。`openclaw setup` 可以重新创建缺失的默认文件而不会覆盖现有文件。
## 不在工作区中的内容
以下内容位于 `~/.openclaw/` 下，**不应**提交到工作区仓库：
- `~/.openclaw/openclaw.json`（配置）
- `~/.openclaw/credentials/`（OAuth 令牌、API 密钥）
- `~/.openclaw/agents/<agentId>/sessions/`（会话记录和元数据）
- `~/.openclaw/skills/`（托管技能）
如果您需要迁移会话或配置，请单独复制它们并将其排除在版本控制之外。
## Git 备份（推荐，私有）
将工作区视为私有记忆。将其放入一个**私有** git 仓库中，以便备份和恢复。
在 Gateway 运行的机器上执行以下步骤（工作区就在那里）。
### 1) 初始化仓库
如果安装了 git，全新的工作区会自动初始化。如果此工作区尚未是仓库，请运行：
```bash
cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
git commit -m "Add agent workspace"
```
### 2) 添加私有远程仓库（新手友好选项）
选项 A：GitHub 网页界面
1. 在 GitHub 上创建一个新的**私有**仓库。
2. 不要使用 README 初始化（避免合并冲突）。
3. 复制 HTTPS 远程 URL。
4. 添加远程仓库并推送：
```bash
git branch -M main
git remote add origin <https-url>
git push -u origin main
```
选项 B：GitHub CLI (`gh`)
```bash
gh auth login
gh repo create openclaw-workspace --private --source . --remote origin --push
```
选项 C：GitLab 网页界面
1. 在 GitLab 上创建一个新的**私有**仓库。
2. 不要使用 README 初始化（避免合并冲突）。
3. 复制 HTTPS 远程 URL。
4. 添加远程仓库并推送：
```bash
git branch -M main
git remote add origin <https-url>
git push -u origin main
```
### 3) 持续更新
```bash
git status
git add .
git commit -m "Update memory"
git push
```
## 不要提交密钥
即使在私有仓库中，也要避免在工作区中存储密钥：
- API 密钥、OAuth 令牌、密码或私有凭据。
- `~/.openclaw/` 下的任何内容。
- 聊天记录的原始转储或敏感附件。
如果您必须存储敏感引用，请使用占位符并将真实密钥保存在其他地方（密码管理器、环境变量或 `~/.openclaw/`）。
建议的 `.gitignore` 起始内容：
```gitignore
.DS_Store
.env
**/*.key
**/*.pem
**/secrets*
```
## 将工作区迁移到新机器
1. 将仓库克隆到目标路径（默认 `~/.openclaw/workspace`）。
2. 在 `~/.openclaw/openclaw.json` 中将 `agents.defaults.workspace` 设置为该路径。
3. 运行 `openclaw setup --workspace <path>` 以生成任何缺失的文件。
4. 如果您需要会话记录，请从旧机器单独复制 `~/.openclaw/agents/<agentId>/sessions/`。
## 高级说明
- 多智能体路由可以为每个智能体使用不同的工作区。参见[渠道路由](/concepts/channel-routing)了解路由配置。
- 如果启用了 `agents.defaults.sandbox`，非主要会话可以使用 `agents.defaults.sandbox.workspaceRoot` 下的按会话沙箱工作区。

114
docs/zh-CN/concepts/agent.md Normal file
View File

@@ -0,0 +1,114 @@
---
read_when:
- 更改智能体运行时、工作区引导或会话行为
summary: 智能体运行时（嵌入式 pi-mono）、工作区契约和会话引导
title: 智能体运行时
x-i18n:
generated_at: "2026-02-01T20:22:02Z"
model: claude-opus-4-5
provider: pi
source_hash: 04b4e0bc6345d2afd9a93186e5d7a02a393ec97da2244e531703cb6a1c182325
source_path: concepts/agent.md
workflow: 14
---
# 智能体运行时 🤖
OpenClaw 运行一个源自 **pi-mono** 的单一嵌入式智能体运行时。
## 工作区（必需）
OpenClaw 使用单一智能体工作区目录（`agents.defaults.workspace`）作为智能体工具和上下文的**唯一**工作目录（`cwd`）。
建议：使用 `openclaw setup` 创建 `~/.openclaw/openclaw.json`（如果不存在）并初始化工作区文件。
完整的工作区布局 + 备份指南：[智能体工作区](/concepts/agent-workspace)
如果启用了 `agents.defaults.sandbox`，非主会话可以使用 `agents.defaults.sandbox.workspaceRoot` 下的按会话工作区覆盖此设置（参见 [Gateway 配置](/gateway/configuration)）。
## 引导文件（注入）
在 `agents.defaults.workspace` 内，OpenClaw 期望这些用户可编辑的文件：
- `AGENTS.md` — 操作指令 + "记忆"
- `SOUL.md` — 角色设定、边界、语气
- `TOOLS.md` — 用户维护的工具说明（例如 `imsg`、`sag`、约定）
- `BOOTSTRAP.md` — 一次性首次运行仪式（完成后删除）
- `IDENTITY.md` — 智能体名称/风格/表情符号
- `USER.md` — 用户档案 + 首选称呼
在新会话的第一轮对话中，OpenClaw 会将这些文件的内容直接注入到智能体上下文中。
空白文件会被跳过。大文件会被裁剪和截断并附带标记，以保持提示词精简（阅读完整文件以获取全部内容）。
如果文件缺失，OpenClaw 会注入一行"文件缺失"标记（`openclaw setup` 会创建安全的默认模板）。
`BOOTSTRAP.md` 仅在**全新工作区**（没有其他引导文件存在）时创建。如果您在完成仪式后删除了它，后续重启时不会重新创建。
要完全禁用引导文件创建（用于预填充的工作区），请设置：
```json5
{ agent: { skipBootstrap: true } }
```
## 内置工具
核心工具（read/exec/edit/write 及相关系统工具）始终可用，受工具策略约束。`apply_patch` 是可选的，由 `tools.exec.applyPatch` 控制。`TOOLS.md` **不**控制哪些工具存在；它是关于您希望如何使用这些工具的指导。
## 技能
OpenClaw 从三个位置加载技能（名称冲突时工作区优先）：
- 内置（随安装包附带）
- 托管/本地：`~/.openclaw/skills`
- 工作区：`<workspace>/skills`
技能可以通过配置/环境变量进行控制（参见 [Gateway 配置](/gateway/configuration) 中的 `skills`）。
## pi-mono 集成
OpenClaw 复用了 pi-mono 代码库的部分内容（模型/工具），但**会话管理、发现和工具连接由 OpenClaw 负责**。
- 没有 pi-coding 智能体运行时。
- 不会读取 `~/.pi/agent` 或 `<workspace>/.pi` 设置。
## 会话
会话记录以 JSONL 格式存储在：
- `~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl`
会话 ID 是稳定的，由 OpenClaw 选择。
**不会**读取旧版 Pi/Tau 会话文件夹。
## 流式传输期间的引导
当队列模式为 `steer` 时，入站消息会被注入到当前运行中。队列在**每次工具调用后**检查；如果存在排队消息，当前助手消息的剩余工具调用会被跳过（工具结果显示"Skipped due to queued user message."错误），然后在下一个助手响应之前注入排队的用户消息。
当队列模式为 `followup` 或 `collect` 时，入站消息会被保留直到当前轮次结束，然后使用排队的负载开始新的智能体轮次。参见[队列](/concepts/queue)了解模式 + 防抖/上限行为。
块流式传输在完成的助手块完成后立即发送；**默认关闭**（`agents.defaults.blockStreamingDefault: "off"`）。
通过 `agents.defaults.blockStreamingBreak` 调整边界（`text_end` 与 `message_end`；默认为 text_end）。
使用 `agents.defaults.blockStreamingChunk` 控制软块分块（默认 800–1200 字符；优先段落分隔，其次换行；最后是句子）。
使用 `agents.defaults.blockStreamingCoalesce` 合并流式块，以减少单行刷屏（基于空闲的合并后再发送）。非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 以启用块回复。
详细的工具摘要在工具启动时发出（无防抖）；Control UI 在可用时通过智能体事件流式传输工具输出。
更多详情：[流式传输 + 分块](/concepts/streaming)。
## 模型引用
配置中的模型引用（例如 `agents.defaults.model` 和 `agents.defaults.models`）通过**第一个** `/` 进行拆分解析。
- 配置模型时使用 `provider/model` 格式。
- 如果模型 ID 本身包含 `/`（OpenRouter 风格），请包含提供商前缀（示例：`openrouter/moonshotai/kimi-k2`）。
- 如果省略提供商，OpenClaw 会将输入视为别名或**默认提供商**的模型（仅在模型 ID 中没有 `/` 时有效）。
## 配置（最小化）
至少需要设置：
- `agents.defaults.workspace`
- `channels.whatsapp.allowFrom`（强烈建议）
---
_下一篇：[群聊](/concepts/group-messages)_ 🦞

123
docs/zh-CN/concepts/architecture.md Normal file
View File

@@ -0,0 +1,123 @@
---
read_when:
- 处理 Gateway 协议、客户端或传输层相关工作时
summary: WebSocket Gateway 架构、组件和客户端流程
title: Gateway 架构
x-i18n:
generated_at: "2026-02-01T20:22:27Z"
model: claude-opus-4-5
provider: pi
source_hash: c636d5d8a5e628067432b30671466309e3d630b106d413f1708765bf2a9399a1
source_path: concepts/architecture.md
workflow: 14
---
# Gateway 架构
最后更新：2026-01-22
## 概述
- 单个长生命周期的 **Gateway** 管理所有消息接入面（通过 Baileys 接入 WhatsApp、通过 grammY 接入 Telegram、Slack、Discord、Signal、iMessage、WebChat）。
- 控制面客户端（macOS 应用、CLI、Web UI、自动化）通过 **WebSocket** 连接到 Gateway，使用配置的绑定地址（默认 `127.0.0.1:18789`）。
- **节点**（macOS/iOS/Android/无头模式）也通过 **WebSocket** 连接，但声明 `role: node` 并显式指定能力/命令。
- 每台主机一个 Gateway；它是唯一打开 WhatsApp 会话的位置。
- **画布主机**（默认 `18793`）提供智能体可编辑的 HTML 和 A2UI。
## 组件和流程
### Gateway（守护进程）
- 维护提供商连接。
- 暴露类型化的 WS API（请求、响应、服务端推送事件）。
- 根据 JSON Schema 验证入站帧。
- 发出 `agent`、`chat`、`presence`、`health`、`heartbeat`、`cron` 等事件。
### 客户端（Mac 应用 / CLI / Web 管理端）
- 每个客户端一个 WS 连接。
- 发送请求（`health`、`status`、`send`、`agent`、`system-presence`）。
- 订阅事件（`tick`、`agent`、`presence`、`shutdown`）。
### 节点（macOS / iOS / Android / 无头模式）
- 连接到**同一个 WS 服务器**，声明 `role: node`。
- 在 `connect` 中提供设备身份；配对是**基于设备**的（角色为 `node`），审批信息存储在设备配对存储中。
- 暴露 `canvas.*`、`camera.*`、`screen.record`、`location.get` 等命令。
协议详情：
- [Gateway 协议](/gateway/protocol)
### WebChat
- 静态 UI，使用 Gateway WS API 获取聊天历史和发送消息。
- 在远程设置中，通过与其他客户端相同的 SSH/Tailscale 隧道连接。
## 连接生命周期（单个客户端）
```
Client Gateway
| |
|---- req:connect -------->|
|<------ res (ok) ---------| （或 res error + 关闭）
| （payload=hello-ok 携带快照：presence + health）
| |
|<------ event:presence ---|
|<------ event:tick -------|
| |
|------- req:agent ------->|
|<------ res:agent --------| （确认：{runId,status:"accepted"}）
|<------ event:agent ------| （流式传输）
|<------ res:agent --------| （最终：{runId,status,summary}）
| |
```
## 线路协议（摘要）
- 传输层：WebSocket，文本帧携带 JSON 负载。
- 第一帧**必须**是 `connect`。
- 握手完成后：
- 请求：`{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`
- 事件：`{type:"event", event, payload, seq?, stateVersion?}`
- 如果设置了 `OPENCLAW_GATEWAY_TOKEN`（或 `--token`），`connect.params.auth.token` 必须匹配，否则套接字将关闭。
- 有副作用的方法（`send`、`agent`）需要幂等性键以安全重试；服务器维护一个短期去重缓存。
- 节点必须在 `connect` 中包含 `role: "node"` 以及能力/命令/权限。
## 配对与本地信任
- 所有 WS 客户端（操作员 + 节点）在 `connect` 时包含**设备身份**。
- 新设备 ID 需要配对审批；Gateway 颁发**设备令牌**用于后续连接。
- **本地**连接（回环地址或 Gateway 主机自身的 tailnet 地址）可以自动审批，以保持同主机用户体验的流畅性。
- **非本地**连接必须对 `connect.challenge` nonce 签名，并需要显式审批。
- Gateway 认证（`gateway.auth.*`）仍适用于**所有**连接，无论本地还是远程。
详情：[Gateway 协议](/gateway/protocol)、[配对](/start/pairing)、[安全](/gateway/security)。
## 协议类型定义与代码生成
- TypeBox schema 定义协议。
- 从这些 schema 生成 JSON Schema。
- 从 JSON Schema 生成 Swift 模型。
## 远程访问
- 推荐方式：Tailscale 或 VPN。
- 备选方式：SSH 隧道
```bash
ssh -N -L 18789:127.0.0.1:18789 user@host
```
- 相同的握手 + 认证令牌适用于隧道连接。
- 远程设置中可为 WS 启用 TLS + 可选的证书固定。
## 运维概览
- 启动：`openclaw gateway`（前台运行，日志输出到 stdout）。
- 健康检查：通过 WS 发送 `health`（也包含在 `hello-ok` 中）。
- 监管：使用 launchd/systemd 实现自动重启。
## 不变量
- 每台主机恰好一个 Gateway 控制单个 Baileys 会话。
- 握手是强制的；任何非 JSON 或非 connect 的首帧将导致硬关闭。
- 事件不会重放；客户端必须在出现间隙时刷新。

117
docs/zh-CN/concepts/channel-routing.md Normal file
View File

@@ -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: concepts/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"],
},
}
```
参见：[广播组](/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` 中。
这在所有渠道中保持一致。

67
docs/zh-CN/concepts/compaction.md Normal file
View File

@@ -0,0 +1,67 @@
---
read_when:
- 您想了解自动压缩和 /compact
- 您正在调试长会话触及上下文限制的问题
summary: 上下文窗口 + 压缩：OpenClaw 如何将会话保持在模型限制内
title: 压缩
x-i18n:
generated_at: "2026-02-01T20:22:17Z"
model: claude-opus-4-5
provider: pi
source_hash: e1d6791f2902044b5798ebf9320a7d055d37211eff4be03caa35d7e328ae803c
source_path: concepts/compaction.md
workflow: 14
---
# 上下文窗口与压缩
每个模型都有一个**上下文窗口**（可见的最大 token 数）。长时间运行的对话会累积消息和工具结果；一旦窗口空间紧张，OpenClaw 会**压缩**较早的历史记录以保持在限制范围内。
## 什么是压缩
压缩会将**较早的对话总结**为一条紧凑的摘要条目，并保持近期消息不变。摘要存储在会话历史中，因此后续请求使用的是：
- 压缩摘要
- 压缩点之后的近期消息
压缩会**持久化**到会话的 JSONL 历史记录中。
## 配置
有关 `agents.defaults.compaction` 设置，请参阅[压缩配置与模式](/concepts/compaction)。
## 自动压缩（默认开启）
当会话接近或超过模型的上下文窗口时，OpenClaw 会触发自动压缩，并可能使用压缩后的上下文重试原始请求。
您会看到：
- 详细模式下显示 `🧹 Auto-compaction complete`
- `/status` 显示 `🧹 Compactions: <count>`
在压缩之前，OpenClaw 可以运行一次**静默记忆刷写**轮次，将持久化笔记写入磁盘。详情及配置请参阅[记忆](/concepts/memory)。
## 手动压缩
使用 `/compact`（可选附带指令）强制执行一次压缩：
```
/compact Focus on decisions and open questions
```
## 上下文窗口来源
上下文窗口因模型而异。OpenClaw 使用已配置提供商目录中的模型定义来确定限制。
## 压缩与修剪
- **压缩**：总结并**持久化**到 JSONL 中。
- **会话修剪**：仅裁剪旧的**工具结果**，**在内存中**按请求进行。
有关修剪的详情，请参阅 [/concepts/session-pruning](/concepts/session-pruning)。
## 提示
- 当会话感觉过时或上下文臃肿时，使用 `/compact`。
- 大型工具输出已被截断；修剪可以进一步减少工具结果的堆积。
- 如果您需要全新开始，`/new` 或 `/reset` 会启动一个新的会话 ID。

168
docs/zh-CN/concepts/context.md Normal file
View File

@@ -0,0 +1,168 @@
---
read_when:
- 你想了解 OpenClaw 中"上下文"的含义
- 你在调试为什么模型"知道"某些内容（或遗忘了它）
- 你想减少上下文开销（/context、/status、/compact）
summary: 上下文：模型看到的内容、如何构建以及如何检查
title: 上下文
x-i18n:
generated_at: "2026-02-01T20:22:35Z"
model: claude-opus-4-5
provider: pi
source_hash: b32867b9b93254fdd1077d0d97c203cabfdba3330bb941693c83feba8e5db0cc
source_path: concepts/context.md
workflow: 14
---
# 上下文
"上下文"是 **OpenClaw 在一次运行中发送给模型的所有内容**。它受模型的**上下文窗口**（token 限制）约束。
初学者心智模型：
- **系统提示词**（由 OpenClaw 构建）：规则、工具、技能列表、时间/运行时信息，以及注入的工作区文件。
- **对话历史**：你的消息 + 助手在本次会话中的消息。
- **工具调用/结果 + 附件**：命令输出、文件读取、图片/音频等。
上下文与"记忆"_不是同一回事_：记忆可以存储在磁盘上并在之后重新加载；上下文是当前模型窗口内的内容。
## 快速开始（检查上下文）
- `/status` → 快速查看"我的窗口还剩多少空间？"以及会话设置。
- `/context list` → 查看注入了哪些内容及大致大小（按文件和总计）。
- `/context detail` → 更深入的分解：按文件、按工具 schema 大小、按技能条目大小，以及系统提示词大小。
- `/usage tokens` → 在正常回复后附加每次回复的用量信息。
- `/compact` → 将较早的历史记录总结为一个压缩条目，以释放窗口空间。
另请参阅：[斜杠命令](/tools/slash-commands)、[Token 用量与费用](/token-use)、[压缩](/concepts/compaction)。
## 示例输出
数值因模型、提供商、工具策略和工作区内容而异。
### `/context list`
```
🧠 Context breakdown
Workspace: <workspaceDir>
Bootstrap max/file: 20,000 chars
Sandbox: mode=non-main sandboxed=false
System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok))
Injected workspace files:
- AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars (~436 tok)
- SOUL.md: OK | raw 912 chars (~228 tok) | injected 912 chars (~228 tok)
- TOOLS.md: TRUNCATED | raw 54,210 chars (~13,553 tok) | injected 20,962 chars (~5,241 tok)
- IDENTITY.md: OK | raw 211 chars (~53 tok) | injected 211 chars (~53 tok)
- USER.md: OK | raw 388 chars (~97 tok) | injected 388 chars (~97 tok)
- HEARTBEAT.md: MISSING | raw 0 | injected 0
- BOOTSTRAP.md: OK | raw 0 chars (~0 tok) | injected 0 chars (~0 tok)
Skills list (system prompt text): 2,184 chars (~546 tok) (12 skills)
Tools: read, edit, write, exec, process, browser, message, sessions_send, …
Tool list (system prompt text): 1,032 chars (~258 tok)
Tool schemas (JSON): 31,988 chars (~7,997 tok) (counts toward context; not shown as text)
Tools: (same as above)
Session tokens (cached): 14,250 total / ctx=32,000
```
### `/context detail`
```
🧠 Context breakdown (detailed)
…
Top skills (prompt entry size):
- frontend-design: 412 chars (~103 tok)
- oracle: 401 chars (~101 tok)
… (+10 more skills)
Top tools (schema size):
- browser: 9,812 chars (~2,453 tok)
- exec: 6,240 chars (~1,560 tok)
… (+N more tools)
```
## 哪些内容计入上下文窗口
模型接收到的所有内容都会计入，包括：
- 系统提示词（所有部分）。
- 对话历史。
- 工具调用 + 工具结果。
- 附件/转录内容（图片/音频/文件）。
- 压缩摘要和修剪产物。
- 提供商的"包装器"或隐藏头信息（不可见，但仍会计入）。
## OpenClaw 如何构建系统提示词
系统提示词由 **OpenClaw 拥有**，每次运行时重新构建。它包括：
- 工具列表 + 简短描述。
- 技能列表（仅元数据；见下文）。
- 工作区位置。
- 时间（UTC + 如已配置则转换为用户时间）。
- 运行时元数据（主机/操作系统/模型/思考模式）。
- 在 **Project Context** 下注入的工作区引导文件。
完整分解：[系统提示词](/concepts/system-prompt)。
## 注入的工作区文件（Project Context）
默认情况下，OpenClaw 会注入一组固定的工作区文件（如果存在）：
- `AGENTS.md`
- `SOUL.md`
- `TOOLS.md`
- `IDENTITY.md`
- `USER.md`
- `HEARTBEAT.md`
- `BOOTSTRAP.md`（仅首次运行）
大文件会按 `agents.defaults.bootstrapMaxChars`（默认 `20000` 字符）逐文件截断。`/context` 会显示**原始大小与注入大小**的对比，以及是否发生了截断。
## 技能：注入的内容与按需加载的内容
系统提示词中包含一个紧凑的**技能列表**（名称 + 描述 + 位置）。此列表会产生实际开销。
技能指令默认*不会*包含在内。模型应在**需要时**才 `read` 技能的 `SKILL.md`。
## 工具：两种开销
工具以两种方式影响上下文：
1. 系统提示词中的**工具列表文本**（即你看到的"Tooling"部分）。
2. **工具 schema**（JSON）。这些会发送给模型以便其调用工具。即使你看不到它们的纯文本形式，它们也会计入上下文。
`/context detail` 会分解最大的工具 schema，让你了解哪些占用最多。
## 命令、指令和"内联快捷方式"
斜杠命令由 Gateway 处理。有几种不同的行为：
- **独立命令**：仅包含 `/...` 的消息作为命令运行。
- **指令**：`/think`、`/verbose`、`/reasoning`、`/elevated`、`/model`、`/queue` 会在模型看到消息之前被移除。
- 仅含指令的消息会持久化会话设置。
- 普通消息中的内联指令作为单次消息提示生效。
- **内联快捷方式**（仅限白名单发送者）：普通消息中的某些 `/...` 标记可以立即执行（例如："hey /status"），并在模型看到剩余文本之前被移除。
详情：[斜杠命令](/tools/slash-commands)。
## 会话、压缩和修剪（哪些内容会持久化）
跨消息持久化的内容取决于机制：
- **普通历史**会持久化在会话转录中，直到被策略压缩/修剪。
- **压缩**会将摘要持久化到转录中，并保留最近的消息不变。
- **修剪**会从运行的*内存中*提示词里移除旧的工具结果，但不会重写转录。
文档：[会话](/concepts/session)、[压缩](/concepts/compaction)、[会话修剪](/concepts/session-pruning)。
## `/context` 实际报告的内容
`/context` 优先使用最新的**运行时构建的**系统提示词报告（如果可用）：
- `System prompt (run)` = 从上一次嵌入式（具有工具能力的）运行中捕获，并持久化在会话存储中。
- `System prompt (estimate)` = 当不存在运行报告时（或通过不生成该报告的 CLI 后端运行时）即时计算。
无论哪种方式，它都会报告大小和主要贡献者；它**不会**输出完整的系统提示词或工具 schema。

91
docs/zh-CN/concepts/group-messages.md Normal file
View File

@@ -0,0 +1,91 @@
---
read_when:
- 更改群组消息规则或提及方式时
summary: WhatsApp 群组消息处理的行为与配置（mentionPatterns 在各平台间共享）
title: 群组消息
x-i18n:
generated_at: "2026-02-01T20:22:33Z"
model: claude-opus-4-5
provider: pi
source_hash: 181a72f12f5021af77c2e4c913120f711e0c0bc271d218d75cb6fe80dab675bb
source_path: concepts/group-messages.md
workflow: 14
---
# 群组消息（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`）。

380
docs/zh-CN/concepts/groups.md Normal file
View File

@@ -0,0 +1,380 @@
---
read_when:
- 更改群聊行为或提及门控
summary: 跨平台的群聊行为（WhatsApp/Telegram/Discord/Slack/Signal/iMessage/Microsoft Teams）
title: 群组
x-i18n:
generated_at: "2026-02-01T20:23:08Z"
model: claude-opus-4-5
provider: pi
source_hash: b727a053edf51f6e7b5c0c324c2fc9c9789a9796c37f622418bd555e8b5a0ec4
source_path: concepts/groups.md
workflow: 14
---
# 群组
OpenClaw 在各平台上统一处理群聊：WhatsApp、Telegram、Discord、Slack、Signal、iMessage、Microsoft Teams。
## 入门简介（2 分钟）
OpenClaw "运行"在您自己的消息账户上。没有单独的 WhatsApp 机器人用户。
如果**您**在某个群组中，OpenClaw 就能看到该群组并在其中回复。
默认行为：
- 群组受限（`groupPolicy: "allowlist"`）。
- 除非您显式禁用提及门控，否则回复需要 @提及。
含义：允许列表中的发送者可以通过提及 OpenClaw 来触发它。
> 简而言之
>
> - **私聊访问**由 `*.allowFrom` 控制。
> - **群组访问**由 `*.groupPolicy` + 允许列表（`*.groups`、`*.groupAllowFrom`）控制。
> - **回复触发**由提及门控（`requireMention`、`/activation`）控制。
快速流程（群消息的处理过程）：
```
groupPolicy? disabled -> drop
groupPolicy? allowlist -> group allowed? no -> drop
requireMention? yes -> mentioned? no -> store for context only
otherwise -> reply
```
![群消息流程](/images/groups-flow.svg)
如果您想要...
| 目标 | 需要设置的内容 |
|------|-------------|
| 允许所有群组但仅在 @提及时回复 | `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", // groups/channels are non-main -> sandboxed
scope: "session", // strongest isolation (one container per group/channel)
workspaceAccess: "none",
},
},
},
tools: {
sandbox: {
tools: {
// If allow is non-empty, everything else is blocked (deny still wins).
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"] },
},
},
},
},
},
}
```
注意事项：
- 群组/频道工具限制在全局/智能体工具策略之上额外应用（拒绝仍然优先）。
- 某些渠道对房间/频道使用不同的嵌套结构（例如 Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft 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 特定说明
有关 WhatsApp 专有行为（历史注入、提及处理详情），请参阅[群消息](/concepts/group-messages)。

117
docs/zh-CN/concepts/markdown-formatting.md Normal file
View File

@@ -0,0 +1,117 @@
---
read_when:
- 你正在更改出站渠道的 Markdown 格式化或分块逻辑
- 你正在添加新的渠道格式化器或样式映射
- 你正在调试跨渠道的格式化回归问题
summary: 出站渠道的 Markdown 格式化管道
title: Markdown 格式化
x-i18n:
generated_at: "2026-02-01T20:22:42Z"
model: claude-opus-4-5
provider: pi
source_hash: f9cbf9b744f9a218860730f29435bcad02d3db80b1847fed5f17c063c97d4820
source_path: concepts/markdown-formatting.md
workflow: 14
---
# Markdown 格式化
OpenClaw 通过将出站 Markdown 转换为共享的中间表示（IR），然后再渲染为特定渠道的输出来进行格式化。IR 保留源文本不变，同时携带样式/链接跨度信息，使分块和渲染在各渠道间保持一致。
## 目标
- **一致性：**一次解析，多个渲染器。
- **安全分块：**在渲染前拆分文本，确保行内格式不会跨块断裂。
- **渠道适配：**将同一 IR 映射到 Slack mrkdwn、Telegram HTML 和 Signal 样式范围，无需重新解析 Markdown。
## 管道
1. **解析 Markdown -> IR**
- IR 是纯文本加上样式跨度（粗体/斜体/删除线/代码/剧透）和链接跨度。
- 偏移量使用 UTF-16 代码单元，以便 Signal 样式范围与其 API 对齐。
- 仅当渠道启用了表格转换时才会解析表格。
2. **分块 IR（格式优先）**
- 分块在渲染前对 IR 文本进行操作。
- 行内格式不会跨块拆分；跨度按块进行切片。
3. **按渠道渲染**
- **Slack：** mrkdwn 标记（粗体/斜体/删除线/代码），链接格式为 `<url|label>`。
- **Telegram：** HTML 标签（`<b>`、`<i>`、`<s>`、`<code>`、`<pre><code>`、`<a href>`）。
- **Signal：** 纯文本 + `text-style` 范围；当标签与 URL 不同时，链接变为 `label (url)`。
## IR 示例
输入 Markdown：
```markdown
Hello **world** — see [docs](https://docs.openclaw.ai).
```
IR（示意）：
```json
{
"text": "Hello world — see docs.",
"styles": [{ "start": 6, "end": 11, "style": "bold" }],
"links": [{ "start": 19, "end": 23, "href": "https://docs.openclaw.ai" }]
}
```
## 使用场景
- Slack、Telegram 和 Signal 的出站适配器从 IR 进行渲染。
- 其他渠道（WhatsApp、iMessage、Microsoft Teams、Discord）仍使用纯文本或各自的格式化规则，启用时会在分块前应用 Markdown 表格转换。
## 表格处理
Markdown 表格在各聊天客户端中的支持并不一致。使用 `markdown.tables` 按渠道（和按账户）控制转换方式。
- `code`：将表格渲染为代码块（大多数渠道的默认设置）。
- `bullets`：将每行转换为项目符号列表（Signal + WhatsApp 的默认设置）。
- `off`：禁用表格解析和转换；原始表格文本直接透传。
配置键：
```yaml
channels:
discord:
markdown:
tables: code
accounts:
work:
markdown:
tables: off
```
## 分块规则
- 分块限制来自渠道适配器/配置，应用于 IR 文本。
- 代码围栏作为单个块保留，并带有尾部换行符，以确保渠道正确渲染。
- 列表前缀和引用块前缀是 IR 文本的一部分，因此分块不会在前缀中间拆分。
- 行内样式（粗体/斜体/删除线/行内代码/剧透）不会跨块拆分；渲染器会在每个块内重新打开样式。
如需了解更多跨渠道的分块行为，请参见[流式传输 + 分块](/concepts/streaming)。
## 链接策略
- **Slack：** `[label](url)` -> `<url|label>`；裸 URL 保持原样。解析时禁用自动链接以避免重复链接。
- **Telegram：** `[label](url)` -> `<a href="url">label</a>`（HTML 解析模式）。
- **Signal：** `[label](url)` -> `label (url)`，除非标签与 URL 匹配。
## 剧透
剧透标记（`||spoiler||`）仅为 Signal 解析，映射为 SPOILER 样式范围。其他渠道将其视为纯文本。
## 如何添加或更新渠道格式化器
1. **解析一次：**使用共享的 `markdownToIR(...)` 辅助函数，传入适合渠道的选项（自动链接、标题样式、引用块前缀）。
2. **渲染：**使用 `renderMarkdownWithMarkers(...)` 和样式标记映射（或 Signal 样式范围）实现渲染器。
3. **分块：**在渲染前调用 `chunkMarkdownIR(...)`；逐块渲染。
4. **接入适配器：**更新渠道出站适配器以使用新的分块器和渲染器。
5. **测试：**添加或更新格式测试，如果渠道使用分块，还需添加出站投递测试。
## 常见陷阱
- Slack 尖括号标记（`<@U123>`、`<#C123>`、`<https://...>`）必须保留；安全转义原始 HTML。
- Telegram HTML 要求对标签外的文本进行转义，以避免标记损坏。
- Signal 样式范围依赖 UTF-16 偏移量；不要使用码点偏移量。
- 保留代码围栏的尾部换行符，以确保闭合标记独占一行。

409
docs/zh-CN/concepts/memory.md Normal file
View File

@@ -0,0 +1,409 @@
---
read_when:
- 想了解记忆文件布局和工作流程
- 想调整自动预压缩记忆刷写
summary: OpenClaw 记忆的工作原理（工作区文件 + 自动记忆刷写）
title: 记忆
x-i18n:
generated_at: "2026-02-01T20:24:01Z"
model: claude-opus-4-5
provider: pi
source_hash: f3a7f5d9f61f9742eb3a8adbc3ccaddeadb7e48ceccdfb595327d6d1f55cd00e
source_path: concepts/memory.md
workflow: 14
---
# 记忆
OpenClaw 的记忆是**智能体工作区中的纯 Markdown 文件**。这些文件是唯一的事实来源；模型只"记住"写入磁盘的内容。
记忆搜索工具由活跃的记忆插件提供（默认：`memory-core`）。通过 `plugins.slots.memory = "none"` 可禁用记忆插件。
## 记忆文件（Markdown）
默认工作区布局使用两个记忆层：
- `memory/YYYY-MM-DD.md`
- 每日日志（仅追加）。
- 会话开始时读取今天和昨天的内容。
- `MEMORY.md`（可选）
- 精心整理的长期记忆。
- **仅在主要的私人会话中加载**（不在群组上下文中加载）。
这些文件位于工作区目录下（`agents.defaults.workspace`，默认 `~/.openclaw/workspace`）。完整布局参见[智能体工作区](/concepts/agent-workspace)。
## 何时写入记忆
- 决策、偏好和持久性事实写入 `MEMORY.md`。
- 日常笔记和运行上下文写入 `memory/YYYY-MM-DD.md`。
- 如果有人说"记住这个"，就写下来（不要只保留在内存中）。
- 这个领域仍在发展中。提醒模型存储记忆会有帮助；它知道该怎么做。
- 如果你想让某些信息持久保留，**让机器人把它写入**记忆。
## 自动记忆刷写（预压缩 ping）
当会话**接近自动压缩**时，OpenClaw 会触发一个**静默的智能体轮次**，提醒模型在上下文被压缩**之前**写入持久记忆。默认提示词明确表示模型*可以回复*，但通常 `NO_REPLY` 是正确的响应，这样用户不会看到这个轮次。
这由 `agents.defaults.compaction.memoryFlush` 控制：
```json5
{
agents: {
defaults: {
compaction: {
reserveTokensFloor: 20000,
memoryFlush: {
enabled: true,
softThresholdTokens: 4000,
systemPrompt: "Session nearing compaction. Store durable memories now.",
prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store.",
},
},
},
},
}
```
详情：
- **软阈值**：当会话 token 估计值超过 `contextWindow - reserveTokensFloor - softThresholdTokens` 时触发刷写。
- 默认**静默**：提示词包含 `NO_REPLY`，因此不会传递任何内容。
- **两个提示词**：一个用户提示词加一个系统提示词附加提醒。
- **每个压缩周期刷写一次**（在 `sessions.json` 中跟踪）。
- **工作区必须可写**：如果会话以 `workspaceAccess: "ro"` 或 `"none"` 在沙箱中运行，则跳过刷写。
完整的压缩生命周期参见[会话管理 + 压缩](/reference/session-management-compaction)。
## 向量记忆搜索
OpenClaw 可以对 `MEMORY.md` 和 `memory/*.md`（以及你选择加入的任何额外目录或文件）构建小型向量索引，这样即使措辞不同，语义查询也能找到相关笔记。
默认设置：
- 默认启用。
- 监视记忆文件变更（带防抖）。
- 默认使用远程嵌入。如果未设置 `memorySearch.provider`，OpenClaw 会自动选择：
1. 如果配置了 `memorySearch.local.modelPath` 且文件存在，则使用 `local`。
2. 如果可以解析到 OpenAI 密钥，则使用 `openai`。
3. 如果可以解析到 Gemini 密钥，则使用 `gemini`。
4. 否则记忆搜索保持禁用，直到完成配置。
- 本地模式使用 node-llama-cpp，可能需要运行 `pnpm approve-builds`。
- 使用 sqlite-vec（可用时）加速 SQLite 内的向量搜索。
远程嵌入**需要**嵌入提供商的 API 密钥。OpenClaw 从认证配置文件、`models.providers.*.apiKey` 或环境变量中解析密钥。Codex OAuth 仅覆盖 chat/completions，**不满足**记忆搜索的嵌入需求。对于 Gemini，使用 `GEMINI_API_KEY` 或 `models.providers.google.apiKey`。使用自定义 OpenAI 兼容端点时，设置 `memorySearch.remote.apiKey`（以及可选的 `memorySearch.remote.headers`）。
### 额外记忆路径
如果你想索引默认工作区布局之外的 Markdown 文件，添加显式路径：
```json5
agents: {
defaults: {
memorySearch: {
extraPaths: ["../team-docs", "/srv/shared-notes/overview.md"]
}
}
}
```
注意事项：
- 路径可以是绝对路径或工作区相对路径。
- 目录会递归扫描 `.md` 文件。
- 仅索引 Markdown 文件。
- 符号链接会被忽略（文件或目录）。
### Gemini 嵌入（原生）
将提供商设置为 `gemini` 以直接使用 Gemini 嵌入 API：
```json5
agents: {
defaults: {
memorySearch: {
provider: "gemini",
model: "gemini-embedding-001",
remote: {
apiKey: "YOUR_GEMINI_API_KEY"
}
}
}
}
```
注意事项：
- `remote.baseUrl` 是可选的（默认为 Gemini API 基础 URL）。
- `remote.headers` 允许你在需要时添加额外的请求头。
- 默认模型：`gemini-embedding-001`。
如果你想使用**自定义 OpenAI 兼容端点**（OpenRouter、vLLM 或代理），可以在 OpenAI 提供商下使用 `remote` 配置：
```json5
agents: {
defaults: {
memorySearch: {
provider: "openai",
model: "text-embedding-3-small",
remote: {
baseUrl: "https://api.example.com/v1/",
apiKey: "YOUR_OPENAI_COMPAT_API_KEY",
headers: { "X-Custom-Header": "value" }
}
}
}
}
```
如果你不想设置 API 密钥，使用 `memorySearch.provider = "local"` 或设置 `memorySearch.fallback = "none"`。
回退策略：
- `memorySearch.fallback` 可以是 `openai`、`gemini`、`local` 或 `none`。
- 回退提供商仅在主嵌入提供商失败时使用。
批量索引（OpenAI + Gemini）：
- OpenAI 和 Gemini 嵌入默认启用批量索引。设置 `agents.defaults.memorySearch.remote.batch.enabled = false` 可禁用。
- 默认行为等待批量完成；如需调整，请调节 `remote.batch.wait`、`remote.batch.pollIntervalMs` 和 `remote.batch.timeoutMinutes`。
- 设置 `remote.batch.concurrency` 控制并行提交的批量作业数（默认：2）。
- 批量模式在 `memorySearch.provider = "openai"` 或 `"gemini"` 时适用，并使用相应的 API 密钥。
- Gemini 批量作业使用异步嵌入批量端点，需要 Gemini Batch API 可用。
为什么 OpenAI 批量又快又便宜：
- 对于大规模回填，OpenAI 通常是我们支持的最快选项，因为我们可以在单个批量作业中提交多个嵌入请求，让 OpenAI 异步处理。
- OpenAI 为 Batch API 工作负载提供折扣定价，因此大规模索引运行通常比同步发送相同请求更便宜。
- 详情参见 OpenAI Batch API 文档和定价：
- https://platform.openai.com/docs/api-reference/batch
- https://platform.openai.com/pricing
配置示例：
```json5
agents: {
defaults: {
memorySearch: {
provider: "openai",
model: "text-embedding-3-small",
fallback: "openai",
remote: {
batch: { enabled: true, concurrency: 2 }
},
sync: { watch: true }
}
}
}
```
工具：
- `memory_search` — 返回包含文件路径和行范围的片段。
- `memory_get` — 按路径读取记忆文件内容。
本地模式：
- 设置 `agents.defaults.memorySearch.provider = "local"`。
- 提供 `agents.defaults.memorySearch.local.modelPath`（GGUF 或 `hf:` URI）。
- 可选：设置 `agents.defaults.memorySearch.fallback = "none"` 以避免远程回退。
### 记忆工具的工作原理
- `memory_search` 对来自 `MEMORY.md` + `memory/**/*.md` 的 Markdown 分块（约 400 token 目标，80 token 重叠）进行语义搜索。返回片段文本（上限约 700 字符）、文件路径、行范围、分数、提供商/模型，以及是否从本地回退到了远程嵌入。不返回完整文件内容。
- `memory_get` 读取特定的记忆 Markdown 文件（工作区相对路径），可选从起始行读取 N 行。`MEMORY.md` / `memory/` 之外的路径仅在 `memorySearch.extraPaths` 中显式列出时才允许访问。
- 两个工具仅在 `memorySearch.enabled` 对智能体解析为 true 时启用。
### 索引内容（及时机）
- 文件类型：仅 Markdown（`MEMORY.md`、`memory/**/*.md`，以及 `memorySearch.extraPaths` 下的任何 `.md` 文件）。
- 索引存储：每个智能体的 SQLite 位于 `~/.openclaw/memory/<agentId>.sqlite`（可通过 `agents.defaults.memorySearch.store.path` 配置，支持 `{agentId}` 占位符）。
- 时效性：监视 `MEMORY.md`、`memory/` 和 `memorySearch.extraPaths` 的变更并标记索引为脏（防抖 1.5 秒）。同步在会话开始时、搜索时或按间隔调度，并异步运行。会话记录使用增量阈值触发后台同步。
- 重新索引触发条件：索引存储嵌入的**提供商/模型 + 端点指纹 + 分块参数**。如果其中任何一项发生变化，OpenClaw 会自动重置并重新索引整个存储。
### 混合搜索（BM25 + 向量）
启用后，OpenClaw 结合以下两种方式：
- **向量相似度**（语义匹配，措辞可以不同）
- **BM25 关键词相关性**（精确 token，如 ID、环境变量、代码符号）
如果你的平台上全文搜索不可用，OpenClaw 会回退到纯向量搜索。
#### 为什么用混合搜索？
向量搜索擅长"这表达的是同一个意思"：
- "Mac Studio gateway 主机" vs "运行 gateway 的机器"
- "防抖文件更新" vs "避免每次写入都索引"
但对于精确的高信号 token 可能较弱：
- ID（`a828e60`、`b3b9895a…`）
- 代码符号（`memorySearch.query.hybrid`）
- 错误字符串（"sqlite-vec unavailable"）
BM25（全文搜索）恰好相反：擅长精确 token，较弱于同义改写。混合搜索是务实的折中方案：**同时使用两种检索信号**，这样"自然语言"查询和"大海捞针"查询都能获得好结果。
#### 我们如何合并结果（当前设计）
实现概要：
1. 从两端检索候选池：
- **向量**：按余弦相似度取前 `maxResults * candidateMultiplier` 个。
- **BM25**：按 FTS5 BM25 排名取前 `maxResults * candidateMultiplier` 个（值越低越好）。
2. 将 BM25 排名转换为 0..1 范围的分数：
- `textScore = 1 / (1 + max(0, bm25Rank))`
3. 按分块 ID 合并候选并计算加权分数：
- `finalScore = vectorWeight * vectorScore + textWeight * textScore`
注意事项：
- 在配置解析时 `vectorWeight` + `textWeight` 会归一化到 1.0，因此权重表现为百分比。
- 如果嵌入不可用（或提供商返回零向量），我们仍会运行 BM25 并返回关键词匹配结果。
- 如果无法创建 FTS5，我们保持纯向量搜索（不会硬失败）。
这不是"信息检索理论上的完美方案"，但它简单、快速，在实际笔记上倾向于提升召回率/精确率。如果以后想更精细，常见的下一步是互惠排名融合（RRF）或混合前的分数归一化（最小/最大值或 z-score）。
配置：
```json5
agents: {
defaults: {
memorySearch: {
query: {
hybrid: {
enabled: true,
vectorWeight: 0.7,
textWeight: 0.3,
candidateMultiplier: 4
}
}
}
}
}
```
### 嵌入缓存
OpenClaw 可以在 SQLite 中缓存**分块嵌入**，这样重新索引和频繁更新（特别是会话记录）不会重新嵌入未更改的文本。
配置：
```json5
agents: {
defaults: {
memorySearch: {
cache: {
enabled: true,
maxEntries: 50000
}
}
}
}
```
### 会话记忆搜索（实验性）
你可以选择索引**会话记录**并通过 `memory_search` 进行搜索。此功能受实验性标志控制。
```json5
agents: {
defaults: {
memorySearch: {
experimental: { sessionMemory: true },
sources: ["memory", "sessions"]
}
}
}
```
注意事项：
- 会话索引是**选择加入**的（默认关闭）。
- 会话更新带防抖，在超过增量阈值后**异步索引**（尽力而为）。
- `memory_search` 不会阻塞等待索引；在后台同步完成之前结果可能略有延迟。
- 结果仍然只包含片段；`memory_get` 仍限于记忆文件。
- 会话索引按智能体隔离（仅索引该智能体的会话日志）。
- 会话日志存储在磁盘上（`~/.openclaw/agents/<agentId>/sessions/*.jsonl`）。任何拥有文件系统访问权限的进程/用户都可以读取它们，因此应将磁盘访问视为信任边界。如需更严格的隔离，请在不同的操作系统用户或主机下运行智能体。
增量阈值（显示默认值）：
```json5
agents: {
defaults: {
memorySearch: {
sync: {
sessions: {
deltaBytes: 100000, // ~100 KB
deltaMessages: 50 // JSONL 行数
}
}
}
}
}
```
### SQLite 向量加速（sqlite-vec）
当 sqlite-vec 扩展可用时，OpenClaw 将嵌入存储在 SQLite 虚拟表（`vec0`）中，并在数据库内执行向量距离查询。这使搜索保持快速，无需将所有嵌入加载到 JS 中。
配置（可选）：
```json5
agents: {
defaults: {
memorySearch: {
store: {
vector: {
enabled: true,
extensionPath: "/path/to/sqlite-vec"
}
}
}
}
}
```
注意事项：
- `enabled` 默认为 true；禁用时，搜索回退到对存储嵌入进行进程内余弦相似度计算。
- 如果 sqlite-vec 扩展缺失或加载失败，OpenClaw 会记录错误并继续使用 JS 回退（无向量表）。
- `extensionPath` 覆盖捆绑的 sqlite-vec 路径（适用于自定义构建或非标准安装位置）。
### 本地嵌入自动下载
- 默认本地嵌入模型：`hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf`（约 0.6 GB）。
- 当 `memorySearch.provider = "local"` 时，`node-llama-cpp` 解析 `modelPath`；如果 GGUF 文件缺失，会**自动下载**到缓存目录（或 `local.modelCacheDir`，如已设置），然后加载。下载在重试时可恢复。
- 原生构建要求：运行 `pnpm approve-builds`，选择 `node-llama-cpp`，然后运行 `pnpm rebuild node-llama-cpp`。
- 回退：如果本地设置失败且 `memorySearch.fallback = "openai"`，我们会自动切换到远程嵌入（`openai/text-embedding-3-small`，除非被覆盖）并记录原因。
### 自定义 OpenAI 兼容端点示例
```json5
agents: {
defaults: {
memorySearch: {
provider: "openai",
model: "text-embedding-3-small",
remote: {
baseUrl: "https://api.example.com/v1/",
apiKey: "YOUR_REMOTE_API_KEY",
headers: {
"X-Organization": "org-id",
"X-Project": "project-id"
}
}
}
}
}
```
注意事项：
- `remote.*` 优先于 `models.providers.openai.*`。
- `remote.headers` 与 OpenAI 请求头合并；键冲突时 remote 优先。省略 `remote.headers` 则使用 OpenAI 默认值。

141
docs/zh-CN/concepts/messages.md Normal file
View File

@@ -0,0 +1,141 @@
---
read_when:
- 解释入站消息如何变为回复
- 澄清会话、队列模式或流式传输行为
- 记录推理可见性和用量影响
summary: 消息流、会话、队列和推理可见性
title: 消息
x-i18n:
generated_at: "2026-02-01T20:22:57Z"
model: claude-opus-4-5
provider: pi
source_hash: 147362b61bee21ee6e303654d970a052325f076ddb45814306053f70409737b5
source_path: concepts/messages.md
workflow: 14
---
# 消息
本页汇总了 OpenClaw 处理入站消息、会话、队列、流式传输和推理可见性的方式。
## 消息流（概览）
```
入站消息
-> 路由/绑定 -> 会话键
-> 队列（如果有运行中的任务）
-> 智能体运行（流式传输 + 工具）
-> 出站回复（渠道限制 + 分块）
```
关键配置项位于配置文件中：
- `messages.*` 用于前缀、队列和群组行为。
- `agents.defaults.*` 用于块流式传输和分块默认值。
- 渠道覆盖（`channels.whatsapp.*`、`channels.telegram.*` 等）用于上限和流式传输开关。
完整配置结构请参见[配置](/gateway/configuration)。
## 入站去重
渠道在重新连接后可能会重新投递相同的消息。OpenClaw 维护一个短期缓存，以渠道/账号/对端/会话/消息 ID 为键，避免重复投递触发额外的智能体运行。
## 入站防抖
来自**同一发送者**的快速连续消息可以通过 `messages.inbound` 合并为单个智能体轮次。防抖按渠道 + 对话维度隔离，并使用最新消息进行回复线程/ID 关联。
配置（全局默认 + 按渠道覆盖）：
```json5
{
messages: {
inbound: {
debounceMs: 2000,
byChannel: {
whatsapp: 5000,
slack: 1500,
discord: 1500,
},
},
},
}
```
说明：
- 防抖仅适用于**纯文本**消息；媒体/附件会立即发送。
- 控制命令会绕过防抖，保持为独立消息。
## 会话与设备
会话由 Gateway 管理，而非由客户端管理。
- 私聊消息归并到智能体的主会话键。
- 群组/频道拥有各自独立的会话键。
- 会话存储和对话记录保存在 Gateway 主机上。
多个设备/渠道可以映射到同一个会话，但历史记录不会完全同步回每个客户端。建议：长对话使用一个主要设备，以避免上下文分歧。控制界面和 TUI 始终显示 Gateway 端的会话记录，因此它们是权威数据源。
详情请参见：[会话管理](/concepts/session)。
## 入站消息体和历史上下文
OpenClaw 将**提示词体**与**命令体**分开处理：
- `Body`：发送给智能体的提示词文本。可能包含渠道信封和可选的历史包装。
- `CommandBody`：用于指令/命令解析的原始用户文本。
- `RawBody`：`CommandBody` 的旧版别名（保留以兼容）。
当渠道提供历史记录时，使用共享的包装格式：
- `[Chat messages since your last reply - for context]`
- `[Current message - respond to this]`
对于**非私聊**（群组/频道/房间），**当前消息体**会添加发送者标签前缀（与历史条目使用相同的格式）。这使得实时消息和排队/历史消息在智能体提示词中保持一致。
历史缓冲区为**仅待处理消息**：它们包含未触发运行的群组消息（例如，提及门控的消息），并**排除**已在会话记录中的消息。
指令剥离仅适用于**当前消息**部分，历史记录保持不变。包装历史记录的渠道应将 `CommandBody`（或 `RawBody`）设置为原始消息文本，并将 `Body` 保留为组合提示词。历史缓冲区可通过 `messages.groupChat.historyLimit`（全局默认）和按渠道覆盖进行配置，例如 `channels.slack.historyLimit` 或 `channels.telegram.accounts.<id>.historyLimit`（设置为 `0` 可禁用）。
## 队列与后续消息
如果已有运行中的任务，入站消息可以排队、引导至当前运行，或收集用于后续轮次。
- 通过 `messages.queue`（及 `messages.queue.byChannel`）进行配置。
- 模式：`interrupt`、`steer`、`followup`、`collect`，以及 backlog 变体。
详情请参见：[队列](/concepts/queue)。
## 流式传输、分块与批处理
块流式传输在模型生成文本块时发送部分回复。分块遵循渠道文本限制，避免拆分代码围栏。
关键设置：
- `agents.defaults.blockStreamingDefault`（`on|off`，默认 off）
- `agents.defaults.blockStreamingBreak`（`text_end|message_end`）
- `agents.defaults.blockStreamingChunk`（`minChars|maxChars|breakPreference`）
- `agents.defaults.blockStreamingCoalesce`（基于空闲的批处理）
- `agents.defaults.humanDelay`（块回复之间的仿人类停顿）
- 渠道覆盖：`*.blockStreaming` 和 `*.blockStreamingCoalesce`（非 Telegram 渠道需要显式设置 `*.blockStreaming: true`）
详情请参见：[流式传输 + 分块](/concepts/streaming)。
## 推理可见性与令牌
OpenClaw 可以显示或隐藏模型推理过程：
- `/reasoning on|off|stream` 控制可见性。
- 推理内容在模型生成时仍然计入令牌用量。
- Telegram 支持将推理过程流式传输到草稿气泡中。
详情请参见：[思考 + 推理指令](/tools/thinking) 和 [令牌用量](/token-use)。
## 前缀、线程与回复
出站消息格式集中在 `messages` 中管理：
- `messages.responsePrefix`（出站前缀）和 `channels.whatsapp.messagePrefix`（WhatsApp 入站前缀）
- 通过 `replyToMode` 和按渠道默认值进行回复线程关联
详情请参见：[配置](/gateway/configuration#messages) 和各渠道文档。

156
docs/zh-CN/concepts/model-failover.md Normal file
View File

@@ -0,0 +1,156 @@
---
read_when:
- 诊断认证配置文件轮换、冷却期或模型回退行为
- 更新认证配置文件或模型的故障转移规则
summary: OpenClaw 如何轮换认证配置文件并在模型之间进行故障回退
title: 模型故障转移
x-i18n:
generated_at: "2026-02-01T20:23:02Z"
model: claude-opus-4-5
provider: pi
source_hash: eab7c0633824d941cf0d6ce4294f0bc8747fbba2ce93650e9643eca327cd04a9
source_path: concepts/model-failover.md
workflow: 14
---
# 模型故障转移
OpenClaw 分两个阶段处理故障：
1. 在当前提供商内进行**认证配置文件轮换**。
2. **模型回退**到 `agents.defaults.model.fallbacks` 中的下一个模型。
本文档介绍运行时规则及其背后的数据。
## 认证存储（密钥 + OAuth）
OpenClaw 对 API 密钥和 OAuth 令牌都使用**认证配置文件**。
- 密钥存储在 `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（旧版路径：`~/.openclaw/agent/auth-profiles.json`）。
- 配置项 `auth.profiles` / `auth.order` **仅包含元数据和路由信息**（不含密钥）。
- 旧版仅导入的 OAuth 文件：`~/.openclaw/credentials/oauth.json`（首次使用时导入到 `auth-profiles.json`）。
更多详情：[/concepts/oauth](/concepts/oauth)
凭证类型：
- `type: "api_key"` → `{ provider, key }`
- `type: "oauth"` → `{ provider, access, refresh, expires, email? }`（部分提供商还包含 `projectId`/`enterpriseUrl`）
## 配置文件 ID
OAuth 登录会创建不同的配置文件，以便多个账户共存。
- 默认值：当没有可用邮箱时为 `provider:default`。
- 带邮箱的 OAuth：`provider:<email>`（例如 `google-antigravity:user@gmail.com`）。
配置文件存储在 `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` 的 `profiles` 下。
## 轮换顺序
当一个提供商有多个配置文件时，OpenClaw 按如下方式选择顺序：
1. **显式配置**：`auth.order[provider]`（如果已设置）。
2. **已配置的配置文件**：按提供商过滤的 `auth.profiles`。
3. **已存储的配置文件**：`auth-profiles.json` 中该提供商的条目。
如果未配置显式顺序，OpenClaw 使用轮询顺序：
- **主排序键：** 配置文件类型（**OAuth 优先于 API 密钥**）。
- **次排序键：** `usageStats.lastUsed`（同类型内最旧的优先）。
- **冷却中/已禁用的配置文件**被移到末尾，按最早到期时间排序。
### 会话粘性（缓存友好）
OpenClaw 会**在每个会话中固定选定的认证配置文件**，以保持提供商缓存活跃。
它**不会**在每次请求时轮换。固定的配置文件会持续使用，直到：
- 会话被重置（`/new` / `/reset`）
- 压缩完成（压缩计数递增）
- 配置文件处于冷却中/已禁用状态
通过 `/model …@<profileId>` 手动选择会为该会话设置一个**用户覆盖**，
在新会话开始前不会自动轮换。
自动固定的配置文件（由会话路由器选择）被视为一种**偏好**：
它们会优先尝试，但 OpenClaw 可能在遇到速率限制/超时时轮换到其他配置文件。
用户固定的配置文件会锁定在该配置文件上；如果它失败且配置了模型回退，
OpenClaw 会转移到下一个模型，而不是切换配置文件。
### 为什么 OAuth 可能"看起来丢失了"
如果你对同一个提供商同时拥有 OAuth 配置文件和 API 密钥配置文件，轮询可能在消息之间切换它们（除非已固定）。要强制使用单个配置文件：
- 通过 `auth.order[provider] = ["provider:profileId"]` 固定，或
- 通过 `/model …` 使用按会话覆盖并指定配置文件（当你的 UI/聊天界面支持时）。
## 冷却期
当配置文件因认证/速率限制错误（或看起来像速率限制的超时）而失败时，
OpenClaw 会将其标记为冷却状态并移至下一个配置文件。
格式/无效请求错误（例如 Cloud Code Assist 工具调用 ID
验证失败）也被视为可故障转移的，并使用相同的冷却机制。
冷却期使用指数退避：
- 1 分钟
- 5 分钟
- 25 分钟
- 1 小时（上限）
状态存储在 `auth-profiles.json` 的 `usageStats` 下：
```json
{
"usageStats": {
"provider:profile": {
"lastUsed": 1736160000000,
"cooldownUntil": 1736160600000,
"errorCount": 2
}
}
}
```
## 计费禁用
计费/额度失败（例如"额度不足"/"信用余额过低"）被视为可故障转移的，但通常不是临时性的。OpenClaw 不会使用短冷却期，而是将配置文件标记为**已禁用**（使用更长的退避时间）并轮换到下一个配置文件/提供商。
状态存储在 `auth-profiles.json` 中：
```json
{
"usageStats": {
"provider:profile": {
"disabledUntil": 1736178000000,
"disabledReason": "billing"
}
}
}
```
默认值：
- 计费退避从 **5 小时**开始，每次计费失败加倍，上限为 **24 小时**。
- 如果配置文件在 **24 小时**内未失败，退避计数器将重置（可配置）。
## 模型回退
如果某个提供商的所有配置文件都失败，OpenClaw 会移至
`agents.defaults.model.fallbacks` 中的下一个模型。这适用于认证失败、速率限制和
耗尽配置文件轮换的超时情况（其他错误不会触发回退）。
当运行以模型覆盖（钩子或 CLI）启动时，回退仍会在尝试所有已配置的回退后
止于 `agents.defaults.model.primary`。
## 相关配置
参阅 [Gateway 配置](/gateway/configuration) 了解：
- `auth.profiles` / `auth.order`
- `auth.cooldowns.billingBackoffHours` / `auth.cooldowns.billingBackoffHoursByProvider`
- `auth.cooldowns.billingMaxHours` / `auth.cooldowns.failureWindowHours`
- `agents.defaults.model.primary` / `agents.defaults.model.fallbacks`
- `agents.defaults.imageModel` 路由
参阅[模型](/concepts/models)了解更广泛的模型选择和回退概述。

317
docs/zh-CN/concepts/model-providers.md Normal file
View File

@@ -0,0 +1,317 @@
---
read_when:
- 你需要按提供商查阅模型设置参考
- 你需要模型提供商的示例配置或 CLI 上手引导命令
summary: 模型提供商概览，包含示例配置和 CLI 流程
title: 模型提供商
x-i18n:
generated_at: "2026-02-01T20:23:13Z"
model: claude-opus-4-5
provider: pi
source_hash: b3940c91ce3aee3d701af7978284966a60ec8c669649cc4be48ba9472243e444
source_path: concepts/model-providers.md
workflow: 14
---
# 模型提供商
本页介绍 **LLM/模型提供商**（非 WhatsApp/Telegram 等聊天渠道）。
有关模型选择规则，请参见 [/concepts/models](/concepts/models)。
## 快速规则
- 模型引用使用 `provider/model` 格式（例如：`opencode/claude-opus-4-5`）。
- 如果设置了 `agents.defaults.models`，它将成为白名单。
- CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`。
## 内置提供商（pi-ai 目录）
OpenClaw 自带 pi‑ai 目录。这些提供商**无需**配置 `models.providers`；只需设置认证并选择模型即可。
### OpenAI
- 提供商：`openai`
- 认证：`OPENAI_API_KEY`
- 示例模型：`openai/gpt-5.2`
- CLI：`openclaw onboard --auth-choice openai-api-key`
```json5
{
agents: { defaults: { model: { primary: "openai/gpt-5.2" } } },
}
```
### Anthropic
- 提供商：`anthropic`
- 认证：`ANTHROPIC_API_KEY` 或 `claude setup-token`
- 示例模型：`anthropic/claude-opus-4-5`
- CLI：`openclaw onboard --auth-choice token`（粘贴 setup-token）或 `openclaw models auth paste-token --provider anthropic`
```json5
{
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
}
```
### OpenAI Code (Codex)
- 提供商：`openai-codex`
- 认证：OAuth (ChatGPT)
- 示例模型：`openai-codex/gpt-5.2`
- CLI：`openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex`
```json5
{
agents: { defaults: { model: { primary: "openai-codex/gpt-5.2" } } },
}
```
### OpenCode Zen
- 提供商：`opencode`
- 认证：`OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）
- 示例模型：`opencode/claude-opus-4-5`
- CLI：`openclaw onboard --auth-choice opencode-zen`
```json5
{
agents: { defaults: { model: { primary: "opencode/claude-opus-4-5" } } },
}
```
### Google Gemini（API 密钥）
- 提供商：`google`
- 认证：`GEMINI_API_KEY`
- 示例模型：`google/gemini-3-pro-preview`
- CLI：`openclaw onboard --auth-choice gemini-api-key`
### Google Vertex、Antigravity 和 Gemini CLI
- 提供商：`google-vertex`、`google-antigravity`、`google-gemini-cli`
- 认证：Vertex 使用 gcloud ADC；Antigravity/Gemini CLI 使用各自的认证流程
- Antigravity OAuth 作为捆绑插件提供（`google-antigravity-auth`，默认禁用）。
- 启用：`openclaw plugins enable google-antigravity-auth`
- 登录：`openclaw models auth login --provider google-antigravity --set-default`
- Gemini CLI OAuth 作为捆绑插件提供（`google-gemini-cli-auth`，默认禁用）。
- 启用：`openclaw plugins enable google-gemini-cli-auth`
- 登录：`openclaw models auth login --provider google-gemini-cli --set-default`
- 注意：你**无需**将客户端 ID 或密钥粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway 主机的认证配置文件中。
### Z.AI (GLM)
- 提供商：`zai`
- 认证：`ZAI_API_KEY`
- 示例模型：`zai/glm-4.7`
- CLI：`openclaw onboard --auth-choice zai-api-key`
- 别名：`z.ai/*` 和 `z-ai/*` 会规范化为 `zai/*`
### Vercel AI Gateway
- 提供商：`vercel-ai-gateway`
- 认证：`AI_GATEWAY_API_KEY`
- 示例模型：`vercel-ai-gateway/anthropic/claude-opus-4.5`
- CLI：`openclaw onboard --auth-choice ai-gateway-api-key`
### 其他内置提供商
- OpenRouter：`openrouter`（`OPENROUTER_API_KEY`）
- 示例模型：`openrouter/anthropic/claude-sonnet-4-5`
- xAI：`xai`（`XAI_API_KEY`）
- Groq：`groq`（`GROQ_API_KEY`）
- Cerebras：`cerebras`（`CEREBRAS_API_KEY`）
- Cerebras 上的 GLM 模型使用 ID `zai-glm-4.7` 和 `zai-glm-4.6`。
- OpenAI 兼容的基础 URL：`https://api.cerebras.ai/v1`。
- Mistral：`mistral`（`MISTRAL_API_KEY`）
- GitHub Copilot：`github-copilot`（`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`）
## 通过 `models.providers` 配置的提供商（自定义/基础 URL）
使用 `models.providers`（或 `models.json`）添加**自定义**提供商或 OpenAI/Anthropic 兼容的代理。
### Moonshot AI (Kimi)
Moonshot 使用 OpenAI 兼容端点，因此将其配置为自定义提供商：
- 提供商：`moonshot`
- 认证：`MOONSHOT_API_KEY`
- 示例模型：`moonshot/kimi-k2.5`
- Kimi K2 模型 ID：
{/_ moonshot-kimi-k2-model-refs:start _/}
- `moonshot/kimi-k2.5`
- `moonshot/kimi-k2-0905-preview`
- `moonshot/kimi-k2-turbo-preview`
- `moonshot/kimi-k2-thinking`
- `moonshot/kimi-k2-thinking-turbo`
{/_ moonshot-kimi-k2-model-refs:end _/}
```json5
{
agents: {
defaults: { model: { primary: "moonshot/kimi-k2.5" } },
},
models: {
mode: "merge",
providers: {
moonshot: {
baseUrl: "https://api.moonshot.ai/v1",
apiKey: "${MOONSHOT_API_KEY}",
api: "openai-completions",
models: [{ id: "kimi-k2.5", name: "Kimi K2.5" }],
},
},
},
}
```
### Kimi Coding
Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
- 提供商：`kimi-coding`
- 认证：`KIMI_API_KEY`
- 示例模型：`kimi-coding/k2p5`
```json5
{
env: { KIMI_API_KEY: "sk-..." },
agents: {
defaults: { model: { primary: "kimi-coding/k2p5" } },
},
}
```
### Qwen OAuth（免费版）
Qwen 通过设备码流程提供对 Qwen Coder + Vision 的 OAuth 访问。
启用捆绑插件，然后登录：
```bash
openclaw plugins enable qwen-portal-auth
openclaw models auth login --provider qwen-portal --set-default
```
模型引用：
- `qwen-portal/coder-model`
- `qwen-portal/vision-model`
详见 [/providers/qwen](/providers/qwen) 了解设置详情和注意事项。
### Synthetic
Synthetic 在 `synthetic` 提供商下提供 Anthropic 兼容的模型：
- 提供商：`synthetic`
- 认证：`SYNTHETIC_API_KEY`
- 示例模型：`synthetic/hf:MiniMaxAI/MiniMax-M2.1`
- CLI：`openclaw onboard --auth-choice synthetic-api-key`
```json5
{
agents: {
defaults: { model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.1" } },
},
models: {
mode: "merge",
providers: {
synthetic: {
baseUrl: "https://api.synthetic.new/anthropic",
apiKey: "${SYNTHETIC_API_KEY}",
api: "anthropic-messages",
models: [{ id: "hf:MiniMaxAI/MiniMax-M2.1", name: "MiniMax M2.1" }],
},
},
},
}
```
### MiniMax
MiniMax 通过 `models.providers` 配置，因为它使用自定义端点：
- MiniMax（Anthropic 兼容）：`--auth-choice minimax-api`
- 认证：`MINIMAX_API_KEY`
详见 [/providers/minimax](/providers/minimax) 了解设置详情、模型选项和配置片段。
### Ollama
Ollama 是一个本地 LLM 运行时，提供 OpenAI 兼容的 API：
- 提供商：`ollama`
- 认证：无需（本地服务器）
- 示例模型：`ollama/llama3.3`
- 安装：https://ollama.ai
```bash
# 安装 Ollama，然后拉取模型：
ollama pull llama3.3
```
```json5
{
agents: {
defaults: { model: { primary: "ollama/llama3.3" } },
},
}
```
Ollama 在本地运行于 `http://127.0.0.1:11434/v1` 时会被自动检测。详见 [/providers/ollama](/providers/ollama) 了解模型推荐和自定义配置。
### 本地代理（LM Studio、vLLM、LiteLLM 等）
示例（OpenAI 兼容）：
```json5
{
agents: {
defaults: {
model: { primary: "lmstudio/minimax-m2.1-gs32" },
models: { "lmstudio/minimax-m2.1-gs32": { alias: "Minimax" } },
},
},
models: {
providers: {
lmstudio: {
baseUrl: "http://localhost:1234/v1",
apiKey: "LMSTUDIO_KEY",
api: "openai-completions",
models: [
{
id: "minimax-m2.1-gs32",
name: "MiniMax M2.1",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 200000,
maxTokens: 8192,
},
],
},
},
},
}
```
注意事项：
- 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 是可选的。
省略时，OpenClaw 默认为：
- `reasoning: false`
- `input: ["text"]`
- `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }`
- `contextWindow: 200000`
- `maxTokens: 8192`
- 建议：设置与你的代理/模型限制匹配的明确值。
## CLI 示例
```bash
openclaw onboard --auth-choice opencode-zen
openclaw models set opencode/claude-opus-4-5
openclaw models list
```
另请参见：[/gateway/configuration](/gateway/configuration) 了解完整的配置示例。

196
docs/zh-CN/concepts/models.md Normal file
View File

@@ -0,0 +1,196 @@
---
read_when:
- 添加或修改模型 CLI（models list/set/scan/aliases/fallbacks）
- 更改模型回退行为或选择体验
- 更新模型扫描探测（工具/图像）
summary: 模型 CLI：列表、设置、别名、回退、扫描、状态
title: 模型 CLI
x-i18n:
generated_at: "2026-02-01T20:23:26Z"
model: claude-opus-4-5
provider: pi
source_hash: e8b54bb370b4f63a9b917594fb0f6ff48192e168196d30c713b8bbe72b78fef6
source_path: concepts/models.md
workflow: 14
---
# 模型 CLI
认证配置轮换、冷却时间以及与回退的交互方式请参见 [/concepts/model-failover](/concepts/model-failover)。
提供商快速概览 + 示例：[/concepts/model-providers](/concepts/model-providers)。
## 模型选择的工作方式
OpenClaw 按以下顺序选择模型：
1. **主模型**（`agents.defaults.model.primary` 或 `agents.defaults.model`）。
2. `agents.defaults.model.fallbacks` 中的**回退模型**（按顺序）。
3. **提供商认证故障转移**在切换到下一个模型之前，会先在提供商内部进行。
相关说明：
- `agents.defaults.models` 是 OpenClaw 可使用的模型白名单/目录（含别名）。
- `agents.defaults.imageModel` **仅在**主模型无法处理图像时使用。
- 每个智能体的默认值可以通过 `agents.list[].model` 加绑定覆盖 `agents.defaults.model`（参见 [/concepts/multi-agent](/concepts/multi-agent)）。
## 快速模型推荐（经验之谈）
- **GLM**：在编码/工具调用方面稍好。
- **MiniMax**：在写作和风格表现方面更好。
## 设置向导（推荐）
如果不想手动编辑配置，可以运行上手引导向导：
```bash
openclaw onboard
```
它可以为常见提供商设置模型和认证，包括 **OpenAI Code (Codex) 订阅**（OAuth）和 **Anthropic**（推荐使用 API 密钥；也支持 `claude setup-token`）。
## 配置键（概览）
- `agents.defaults.model.primary` 和 `agents.defaults.model.fallbacks`
- `agents.defaults.imageModel.primary` 和 `agents.defaults.imageModel.fallbacks`
- `agents.defaults.models`（白名单 + 别名 + 提供商参数）
- `models.providers`（写入 `models.json` 的自定义提供商）
模型引用会被统一转为小写。提供商别名如 `z.ai/*` 会被规范化为 `zai/*`。
提供商配置示例（包括 OpenCode Zen）请参见 [/gateway/configuration](/gateway/configuration#opencode-zen-multi-model-proxy)。
## "Model is not allowed"（以及为什么回复停止）
如果设置了 `agents.defaults.models`，它将成为 `/model` 和会话覆盖的**白名单**。当用户选择了不在白名单中的模型时，OpenClaw 会返回：
```
Model "provider/model" is not allowed. Use /model to list available models.
```
这发生在正常回复生成**之前**，因此消息看起来可能像是"没有响应"。修复方法是：
- 将该模型添加到 `agents.defaults.models`，或
- 清除白名单（移除 `agents.defaults.models`），或
- 从 `/model list` 中选择一个模型。
白名单配置示例：
```json5
{
agent: {
model: { primary: "anthropic/claude-sonnet-4-5" },
models: {
"anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
"anthropic/claude-opus-4-5": { alias: "Opus" },
},
},
}
```
## 在聊天中切换模型（`/model`）
你可以在当前会话中切换模型而无需重启：
```
/model
/model list
/model 3
/model openai/gpt-5.2
/model status
```
说明：
- `/model`（和 `/model list`）是一个紧凑的编号选择器（模型系列 + 可用提供商）。
- `/model <#>` 从该选择器中选择。
- `/model status` 是详细视图（认证候选项，以及配置后的提供商端点 `baseUrl` + `api` 模式）。
- 模型引用通过**第一个** `/` 进行分割解析。输入 `/model <ref>` 时请使用 `provider/model` 格式。
- 如果模型 ID 本身包含 `/`（OpenRouter 风格），必须包含提供商前缀（例如：`/model openrouter/moonshotai/kimi-k2`）。
- 如果省略提供商，OpenClaw 会将输入视为别名或**默认提供商**的模型（仅在模型 ID 中不含 `/` 时有效）。
完整命令行为/配置：[斜杠命令](/tools/slash-commands)。
## CLI 命令
```bash
openclaw models list
openclaw models status
openclaw models set <provider/model>
openclaw models set-image <provider/model>
openclaw models aliases list
openclaw models aliases add <alias> <provider/model>
openclaw models aliases remove <alias>
openclaw models fallbacks list
openclaw models fallbacks add <provider/model>
openclaw models fallbacks remove <provider/model>
openclaw models fallbacks clear
openclaw models image-fallbacks list
openclaw models image-fallbacks add <provider/model>
openclaw models image-fallbacks remove <provider/model>
openclaw models image-fallbacks clear
```
`openclaw models`（无子命令）是 `models status` 的快捷方式。
### `models list`
默认显示已配置的模型。常用标志：
- `--all`：完整目录
- `--local`：仅本地提供商
- `--provider <name>`：按提供商筛选
- `--plain`：每行一个模型
- `--json`：机器可读输出
### `models status`
显示已解析的主模型、回退模型、图像模型，以及已配置提供商的认证概览。还会显示认证存储中找到的 OAuth 配置过期状态（默认在 24 小时内发出警告）。`--plain` 仅打印已解析的主模型。
OAuth 状态始终显示（并包含在 `--json` 输出中）。如果已配置的提供商没有凭证，`models status` 会打印 **Missing auth** 部分。
JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的有效认证）。
使用 `--check` 进行自动化检测（缺失/过期时退出码为 `1`，即将过期时为 `2`）。
推荐的 Anthropic 认证方式是 Claude Code CLI setup-token（可在任何地方运行；如有需要可粘贴到 Gateway 主机上）：
```bash
claude setup-token
openclaw models status
```
## 扫描（OpenRouter 免费模型）
`openclaw models scan` 检查 OpenRouter 的**免费模型目录**，并可选择性地探测模型的工具和图像支持情况。
主要标志：
- `--no-probe`：跳过实时探测（仅元数据）
- `--min-params <b>`：最小参数量（十亿）
- `--max-age-days <days>`：跳过较旧的模型
- `--provider <name>`：提供商前缀筛选
- `--max-candidates <n>`：回退列表大小
- `--set-default`：将 `agents.defaults.model.primary` 设置为第一个选择
- `--set-image`：将 `agents.defaults.imageModel.primary` 设置为第一个图像选择
探测需要 OpenRouter API 密钥（来自认证配置或 `OPENROUTER_API_KEY`）。没有密钥时，使用 `--no-probe` 仅列出候选模型。
扫描结果按以下顺序排名：
1. 图像支持
2. 工具延迟
3. 上下文大小
4. 参数数量
输入
- OpenRouter `/models` 列表（筛选 `:free`）
- 需要来自认证配置或 `OPENROUTER_API_KEY` 的 OpenRouter API 密钥（参见 [/environment](/environment)）
- 可选筛选器：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates`
- 探测控制：`--timeout`、`--concurrency`
在 TTY 中运行时，你可以交互式地选择回退模型。在非交互模式下，传入 `--yes` 以接受默认值。
## 模型注册表（`models.json`）
`models.providers` 中的自定义提供商会被写入智能体目录下的 `models.json`（默认为 `~/.openclaw/agents/<agentId>/models.json`）。除非 `models.mode` 设置为 `replace`，否则此文件默认会被合并。

369
docs/zh-CN/concepts/multi-agent.md Normal file
View File

@@ -0,0 +1,369 @@
---
read_when: 你希望在一个 Gateway 进程中运行多个隔离的智能体（工作区 + 认证）。
status: active
summary: 多智能体路由：隔离的智能体、渠道账户和绑定
title: 多智能体路由
x-i18n:
generated_at: "2026-02-01T20:23:55Z"
model: claude-opus-4-5
provider: pi
source_hash: 1848266c632cd6c96ff99ea9eb9c17bbfe6d35fa1f90450853083e7c548d5324
source_path: concepts/multi-agent.md
workflow: 14
---
# 多智能体路由
目标：在一个运行中的 Gateway 中托管多个*隔离的*智能体（独立的工作区 + `agentDir` + 会话），以及多个渠道账户（例如两个 WhatsApp）。入站消息通过绑定路由到对应的智能体。
## 什么是"一个智能体"？
一个**智能体**是一个完全独立作用域的大脑，拥有自己的：
- **工作区**（文件、AGENTS.md/SOUL.md/USER.md、本地笔记、人设规则）。
- **状态目录**（`agentDir`），用于存储认证配置文件、模型注册表和按智能体配置。
- **会话存储**（聊天历史 + 路由状态），位于 `~/.openclaw/agents/<agentId>/sessions`。
认证配置文件是**按智能体隔离的**。每个智能体从自己的目录读取：
```
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
```
主智能体的凭证**不会**自动共享。切勿在智能体之间复用 `agentDir`（会导致认证/会话冲突）。如果你想共享凭证，请将 `auth-profiles.json` 复制到另一个智能体的 `agentDir` 中。
技能通过每个工作区的 `skills/` 文件夹按智能体隔离，共享技能可从 `~/.openclaw/skills` 获取。参阅[技能：按智能体 vs 共享](/tools/skills#per-agent-vs-shared-skills)。
Gateway 可以托管**一个智能体**（默认）或**多个智能体**并行运行。
**工作区说明：** 每个智能体的工作区是**默认工作目录**，而非严格的沙箱。相对路径在工作区内解析，但绝对路径可以访问主机上的其他位置，除非启用了沙箱。参阅[沙箱](/gateway/sandboxing)。
## 路径（速查）
- 配置文件：`~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`）
- 状态目录：`~/.openclaw`（或 `OPENCLAW_STATE_DIR`）
- 工作区：`~/.openclaw/workspace`（或 `~/.openclaw/workspace-<agentId>`）
- 智能体目录：`~/.openclaw/agents/<agentId>/agent`（或 `agents.list[].agentDir`）
- 会话：`~/.openclaw/agents/<agentId>/sessions`
### 单智能体模式（默认）
如果你不做任何配置，OpenClaw 会运行单个智能体：
- `agentId` 默认为 **`main`**。
- 会话键格式为 `agent:main:<mainKey>`。
- 工作区默认为 `~/.openclaw/workspace`（设置了 `OPENCLAW_PROFILE` 时为 `~/.openclaw/workspace-<profile>`）。
- 状态默认为 `~/.openclaw/agents/main/agent`。
## 智能体助手
使用智能体向导添加新的隔离智能体：
```bash
openclaw agents add work
```
然后添加 `bindings`（或让向导完成）来路由入站消息。
验证方式：
```bash
openclaw agents list --bindings
```
## 多智能体 = 多用户、多人设
使用**多个智能体**时，每个 `agentId` 都成为一个**完全隔离的人设**：
- **不同的手机号/账户**（按渠道 `accountId`）。
- **不同的性格**（按智能体工作区文件，如 `AGENTS.md` 和 `SOUL.md`）。
- **独立的认证 + 会话**（除非显式启用，否则无串扰）。
这使得**多个用户**可以共享一台 Gateway 服务器，同时保持各自的 AI "大脑"和数据隔离。
## 一个 WhatsApp 号码，多个用户（私聊分流）
你可以将**不同的 WhatsApp 私聊**路由到不同的智能体，同时使用**同一个 WhatsApp 账户**。通过发送者的 E.164 格式号码（如 `+15551234567`）配合 `peer.kind: "dm"` 进行匹配。回复仍然从同一个 WhatsApp 号码发出（没有按智能体的发送者身份）。
重要细节：私聊会折叠到智能体的**主会话键**，因此真正的隔离需要**每人一个智能体**。
示例：
```json5
{
agents: {
list: [
{ id: "alex", workspace: "~/.openclaw/workspace-alex" },
{ id: "mia", workspace: "~/.openclaw/workspace-mia" },
],
},
bindings: [
{ agentId: "alex", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551230001" } } },
{ agentId: "mia", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551230002" } } },
],
channels: {
whatsapp: {
dmPolicy: "allowlist",
allowFrom: ["+15551230001", "+15551230002"],
},
},
}
```
说明：
- 私聊访问控制是**按 WhatsApp 账户全局的**（配对/白名单），而非按智能体。
- 对于共享群组，将群组绑定到一个智能体或使用[广播群组](/broadcast-groups)。
## 路由规则（消息如何选择智能体）
绑定是**确定性的**，遵循**最精确匹配优先**原则：
1. `peer` 匹配（精确的私聊/群组/渠道 ID）
2. `guildId`（Discord）
3. `teamId`（Slack）
4. `accountId` 匹配（按渠道）
5. 渠道级匹配（`accountId: "*"`）
6. 回退到默认智能体（`agents.list[].default`，否则取列表第一项，默认值：`main`）
## 多账户/多手机号
支持**多账户**的渠道（如 WhatsApp）使用 `accountId` 来标识每个登录。每个 `accountId` 可以路由到不同的智能体，这样一台服务器就可以托管多个手机号而不会混淆会话。
## 概念
- `agentId`：一个"大脑"（工作区、按智能体认证、按智能体会话存储）。
- `accountId`：一个渠道账户实例（例如 WhatsApp 账户 `"personal"` vs `"biz"`）。
- `binding`：通过 `(channel, accountId, peer)` 以及可选的 guild/team ID 将入站消息路由到 `agentId`。
- 私聊折叠到 `agent:<agentId>:<mainKey>`（按智能体的"主会话"；`session.mainKey`）。
## 示例：两个 WhatsApp → 两个智能体
`~/.openclaw/openclaw.json`（JSON5）：
```js
{
agents: {
list: [
{
id: "home",
default: true,
name: "Home",
workspace: "~/.openclaw/workspace-home",
agentDir: "~/.openclaw/agents/home/agent",
},
{
id: "work",
name: "Work",
workspace: "~/.openclaw/workspace-work",
agentDir: "~/.openclaw/agents/work/agent",
},
],
},
// 确定性路由：第一个匹配生效（最精确的在前）。
bindings: [
{ agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
{ agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
// 可选的按对端覆盖（示例：将特定群组发送到 work 智能体）。
{
agentId: "work",
match: {
channel: "whatsapp",
accountId: "personal",
peer: { kind: "group", id: "1203630...@g.us" },
},
},
],
// 默认关闭：智能体间消息传递必须显式启用 + 白名单。
tools: {
agentToAgent: {
enabled: false,
allow: ["home", "work"],
},
},
channels: {
whatsapp: {
accounts: {
personal: {
// 可选覆盖。默认值：~/.openclaw/credentials/whatsapp/personal
// authDir: "~/.openclaw/credentials/whatsapp/personal",
},
biz: {
// 可选覆盖。默认值：~/.openclaw/credentials/whatsapp/biz
// authDir: "~/.openclaw/credentials/whatsapp/biz",
},
},
},
},
}
```
## 示例：WhatsApp 日常聊天 + Telegram 深度工作
按渠道分流：将 WhatsApp 路由到快速日常智能体，将 Telegram 路由到 Opus 智能体。
```json5
{
agents: {
list: [
{
id: "chat",
name: "Everyday",
workspace: "~/.openclaw/workspace-chat",
model: "anthropic/claude-sonnet-4-5",
},
{
id: "opus",
name: "Deep Work",
workspace: "~/.openclaw/workspace-opus",
model: "anthropic/claude-opus-4-5",
},
],
},
bindings: [
{ agentId: "chat", match: { channel: "whatsapp" } },
{ agentId: "opus", match: { channel: "telegram" } },
],
}
```
说明：
- 如果一个渠道有多个账户，请在绑定中添加 `accountId`（例如 `{ channel: "whatsapp", accountId: "personal" }`）。
- 要将单个私聊/群组路由到 Opus 而其余保持在 chat 上，请为该对端添加 `match.peer` 绑定；对端匹配始终优先于渠道级规则。
## 示例：同一渠道，将一个对端路由到 Opus
将 WhatsApp 保持在快速智能体上，但将一个私聊路由到 Opus：
```json5
{
agents: {
list: [
{
id: "chat",
name: "Everyday",
workspace: "~/.openclaw/workspace-chat",
model: "anthropic/claude-sonnet-4-5",
},
{
id: "opus",
name: "Deep Work",
workspace: "~/.openclaw/workspace-opus",
model: "anthropic/claude-opus-4-5",
},
],
},
bindings: [
{ agentId: "opus", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551234567" } } },
{ agentId: "chat", match: { channel: "whatsapp" } },
],
}
```
对端绑定始终优先，因此请将它们放在渠道级规则之上。
## 绑定到 WhatsApp 群组的家庭智能体
将一个专用家庭智能体绑定到单个 WhatsApp 群组，使用提及控制和更严格的工具策略：
```json5
{
agents: {
list: [
{
id: "family",
name: "Family",
workspace: "~/.openclaw/workspace-family",
identity: { name: "Family Bot" },
groupChat: {
mentionPatterns: ["@family", "@familybot", "@Family Bot"],
},
sandbox: {
mode: "all",
scope: "agent",
},
tools: {
allow: [
"exec",
"read",
"sessions_list",
"sessions_history",
"sessions_send",
"sessions_spawn",
"session_status",
],
deny: ["write", "edit", "apply_patch", "browser", "canvas", "nodes", "cron"],
},
},
],
},
bindings: [
{
agentId: "family",
match: {
channel: "whatsapp",
peer: { kind: "group", id: "120363999999999999@g.us" },
},
},
],
}
```
说明：
- 工具允许/拒绝列表针对的是**工具**，而非技能。如果某个技能需要运行二进制文件，请确保允许 `exec` 并且该二进制文件存在于沙箱中。
- 要实现更严格的控制，请设置 `agents.list[].groupChat.mentionPatterns` 并为渠道启用群组白名单。
## 按智能体的沙箱和工具配置
从 v2026.1.6 开始，每个智能体可以有自己的沙箱和工具限制：
```js
{
agents: {
list: [
{
id: "personal",
workspace: "~/.openclaw/workspace-personal",
sandbox: {
mode: "off", // 个人智能体不使用沙箱
},
// 无工具限制 - 所有工具可用
},
{
id: "family",
workspace: "~/.openclaw/workspace-family",
sandbox: {
mode: "all", // 始终沙箱化
scope: "agent", // 每个智能体一个容器
docker: {
// 容器创建后的可选一次性设置
setupCommand: "apt-get update && apt-get install -y git curl",
},
},
tools: {
allow: ["read"], // 仅允许 read 工具
deny: ["exec", "write", "edit", "apply_patch"], // 拒绝其他工具
},
},
],
},
}
```
注意：`setupCommand` 位于 `sandbox.docker` 下，在容器创建时运行一次。当解析的 scope 为 `"shared"` 时，按智能体的 `sandbox.docker.*` 覆盖会被忽略。
**优势：**
- **安全隔离**：限制不受信任的智能体的工具
- **资源控制**：沙箱化特定智能体，同时让其他智能体在主机上运行
- **灵活策略**：按智能体设置不同权限
注意：`tools.elevated` 是**全局的**且基于发送者；不能按智能体配置。如果你需要按智能体的边界，请使用 `agents.list[].tools` 来拒绝 `exec`。对于群组定向，请使用 `agents.list[].groupChat.mentionPatterns`，以便 @提及能准确映射到目标智能体。
参阅[多智能体沙箱与工具](/multi-agent-sandbox-tools)获取详细示例。

151
docs/zh-CN/concepts/oauth.md Normal file
View File

@@ -0,0 +1,151 @@
---
read_when:
- 您想全面了解 OpenClaw 的 OAuth 流程
- 您遇到了令牌失效/登出问题
- 您想了解 setup-token 或 OAuth 认证流程
- 您想使用多账户或配置文件路由
summary: OpenClaw 中的 OAuth：令牌交换、存储和多账户模式
title: OAuth
x-i18n:
generated_at: "2026-02-01T20:23:29Z"
model: claude-opus-4-5
provider: pi
source_hash: af714bdadc4a89295a18da1eba5f5b857c8d533ebabe9b0758b722fe60c36124
source_path: concepts/oauth.md
workflow: 14
---
# OAuth
OpenClaw 支持通过 OAuth 进行"订阅认证"，适用于提供此功能的提供商（特别是 **OpenAI Codex（ChatGPT OAuth）**）。对于 Anthropic 订阅，请使用 **setup-token** 流程。本页说明：
- OAuth **令牌交换**的工作原理（PKCE）
- 令牌**存储**在哪里（以及原因）
- 如何处理**多账户**（配置文件 + 按会话覆盖）
OpenClaw 还支持**提供商插件**，它们自带 OAuth 或 API 密钥流程。通过以下命令运行：
```bash
openclaw models auth login --provider <id>
```
## 令牌汇聚点（为什么需要它）
OAuth 提供商通常在登录/刷新流程中发放**新的刷新令牌**。某些提供商（或 OAuth 客户端）在为同一用户/应用发放新令牌时，可能会使旧的刷新令牌失效。
实际症状：
- 您通过 OpenClaw _和_ Claude Code / Codex CLI 登录 → 其中一个稍后会随机"登出"
为减少这种情况，OpenClaw 将 `auth-profiles.json` 视为**令牌汇聚点**：
- 运行时从**同一个位置**读取凭据
- 我们可以保留多个配置文件并确定性地路由它们
## 存储（令牌存放位置）
密钥按**智能体**存储：
- 认证配置文件（OAuth + API 密钥）：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
- 运行时缓存（自动管理；请勿编辑）：`~/.openclaw/agents/<agentId>/agent/auth.json`
仅用于导入的旧版文件（仍然支持，但不是主存储）：
- `~/.openclaw/credentials/oauth.json`（首次使用时导入到 `auth-profiles.json`）
以上所有路径也遵循 `$OPENCLAW_STATE_DIR`（状态目录覆盖）。完整参考：[/gateway/configuration](/gateway/configuration#auth-storage-oauth--api-keys)
## Anthropic setup-token（订阅认证）
在任意机器上运行 `claude setup-token`，然后将其粘贴到 OpenClaw 中：
```bash
openclaw models auth setup-token --provider anthropic
```
如果您在其他地方生成了令牌，可以手动粘贴：
```bash
openclaw models auth paste-token --provider anthropic
```
验证：
```bash
openclaw models status
```
## OAuth 交换（登录工作原理）
OpenClaw 的交互式登录流程在 `@mariozechner/pi-ai` 中实现，并集成到向导/命令中。
### Anthropic（Claude Pro/Max）setup-token
流程概要：
1. 运行 `claude setup-token`
2. 将令牌粘贴到 OpenClaw
3. 作为令牌认证配置文件存储（无刷新）
向导路径为 `openclaw onboard` → 认证选择 `setup-token`（Anthropic）。
### OpenAI Codex（ChatGPT OAuth）
流程概要（PKCE）：
1. 生成 PKCE 验证器/质询 + 随机 `state`
2. 打开 `https://auth.openai.com/oauth/authorize?...`
3. 尝试在 `http://127.0.0.1:1455/auth/callback` 捕获回调
4. 如果回调无法绑定（或您在远程/无头环境中），手动粘贴重定向 URL/代码
5. 在 `https://auth.openai.com/oauth/token` 进行交换
6. 从访问令牌中提取 `accountId` 并存储 `{ access, refresh, expires, accountId }`
向导路径为 `openclaw onboard` → 认证选择 `openai-codex`。
## 刷新 + 过期
配置文件存储 `expires` 时间戳。
运行时：
- 如果 `expires` 在未来 → 使用已存储的访问令牌
- 如果已过期 → 刷新（在文件锁下）并覆盖已存储的凭据
刷新流程是自动的；您通常不需要手动管理令牌。
## 多账户（配置文件）+ 路由
两种模式：
### 1）推荐：独立智能体
如果您希望"个人"和"工作"永远不交叉，请使用隔离的智能体（独立的会话 + 凭据 + 工作区）：
```bash
openclaw agents add work
openclaw agents add personal
```
然后按智能体配置认证（向导），并将聊天路由到正确的智能体。
### 2）高级：单个智能体中的多个配置文件
`auth-profiles.json` 支持同一提供商的多个配置文件 ID。
选择使用哪个配置文件：
- 通过配置顺序全局设置（`auth.order`）
- 通过 `/model ...@<profileId>` 按会话设置
示例（会话覆盖）：
- `/model Opus@anthropic:work`
如何查看存在哪些配置文件 ID：
- `openclaw channels list --json`（显示 `auth[]`）
相关文档：
- [/concepts/model-failover](/concepts/model-failover)（轮换 + 冷却规则）
- [/tools/slash-commands](/tools/slash-commands)（命令界面）

99
docs/zh-CN/concepts/presence.md Normal file
View File

@@ -0,0 +1,99 @@
---
read_when:
- 调试实例选项卡
- 排查重复或过期的实例行
- 更改 Gateway WebSocket 连接或系统事件信标
summary: OpenClaw 在线状态条目的生成、合并与显示方式
title: 在线状态
x-i18n:
generated_at: "2026-02-01T20:23:31Z"
model: claude-opus-4-5
provider: pi
source_hash: c752c76a880878fed673d656db88beb5dbdeefff2491985127ad791521f97d00
source_path: concepts/presence.md
workflow: 14
---
# 在线状态
OpenClaw 的"在线状态"是一个轻量级、尽力而为的视图，展示：
- **Gateway** 自身，以及
- **连接到 Gateway 的客户端**（Mac 应用、WebChat、CLI 等）
在线状态主要用于渲染 macOS 应用的**实例**选项卡，并为操作人员提供快速可视化。
## 在线状态字段（显示内容）
在线状态条目是结构化对象，包含以下字段：
- `instanceId`（可选但强烈建议提供）：稳定的客户端标识（通常为 `connect.client.instanceId`）
- `host`：人类可读的主机名
- `ip`：尽力而为的 IP 地址
- `version`：客户端版本字符串
- `deviceFamily` / `modelIdentifier`：硬件提示信息
- `mode`：`ui`、`webchat`、`cli`、`backend`、`probe`、`test`、`node`，...
- `lastInputSeconds`："距上次用户输入的秒数"（如果已知）
- `reason`：`self`、`connect`、`node-connected`、`periodic`，...
- `ts`：最后更新时间戳（自纪元以来的毫秒数）
## 生产者（在线状态的来源）
在线状态条目由多个来源产生并进行**合并**。
### 1）Gateway 自身条目
Gateway 在启动时始终会创建一个"self"条目，这样即使在任何客户端连接之前，UI 也能显示 Gateway 主机。
### 2）WebSocket 连接
每个 WebSocket 客户端都以 `connect` 请求开始。握手成功后，Gateway 会为该连接更新插入一个在线状态条目。
#### 为什么一次性 CLI 命令不会显示
CLI 通常只为短暂的一次性命令建立连接。为避免实例列表被频繁刷新，`client.mode === "cli"` **不会**被转换为在线状态条目。
### 3）`system-event` 信标
客户端可以通过 `system-event` 方法发送更丰富的周期性信标。Mac 应用使用此机制报告主机名、IP 和 `lastInputSeconds`。
### 4）节点连接（role: node）
当节点通过 Gateway WebSocket 以 `role: node` 连接时，Gateway 会为该节点更新插入一个在线状态条目（与其他 WebSocket 客户端流程相同）。
## 合并与去重规则（为什么 `instanceId` 很重要）
在线状态条目存储在单个内存映射中：
- 条目以**在线状态键**作为索引。
- 最佳键是稳定的 `instanceId`（来自 `connect.client.instanceId`），可在重启后保持不变。
- 键不区分大小写。
如果客户端在没有稳定 `instanceId` 的情况下重新连接，可能会显示为**重复**行。
## TTL 和大小限制
在线状态是有意设计为临时性的：
- **TTL：**超过 5 分钟的条目将被清除
- **最大条目数：**200（优先丢弃最旧的条目）
这确保列表保持新鲜，避免无限制的内存增长。
## 远程/隧道注意事项（回环 IP）
当客户端通过 SSH 隧道/本地端口转发连接时，Gateway 可能会将远程地址识别为 `127.0.0.1`。为避免覆盖客户端报告的有效 IP，回环远程地址会被忽略。
## 消费者
### macOS 实例选项卡
macOS 应用渲染 `system-presence` 的输出，并根据最后更新的时间显示小型状态指示器（活跃/空闲/过期）。
## 调试技巧
- 要查看原始列表，请对 Gateway 调用 `system-presence`。
- 如果看到重复条目：
- 确认客户端在握手中发送了稳定的 `client.instanceId`
- 确认周期性信标使用相同的 `instanceId`
- 检查连接派生的条目是否缺少 `instanceId`（此时重复是预期行为）

94
docs/zh-CN/concepts/queue.md Normal file
View File

@@ -0,0 +1,94 @@
---
read_when:
- 更改自动回复执行或并发机制
summary: 序列化入站自动回复运行的命令队列设计
title: 命令队列
x-i18n:
generated_at: "2026-02-01T20:23:48Z"
model: claude-opus-4-5
provider: pi
source_hash: 2104c24d200fb4f9620e52a19255cd614ababe19d78f3ee42936dc6d0499b73b
source_path: concepts/queue.md
workflow: 14
---
# 命令队列（2026-01-16）
我们通过一个轻量的进程内队列来序列化入站自动回复运行（所有渠道），以防止多个智能体运行发生冲突，同时仍允许跨会话的安全并行。
## 原因
- 自动回复运行可能开销很大（LLM 调用），当多条入站消息几乎同时到达时可能发生冲突。
- 序列化可以避免争用共享资源（会话文件、日志、CLI 标准输入），并降低触发上游速率限制的概率。
## 工作原理
- 一个支持通道感知的 FIFO 队列以可配置的并发上限逐通道排空（未配置的通道默认为 1；main 默认为 4，subagent 默认为 8）。
- `runEmbeddedPiAgent` 按**会话键**（通道 `session:<key>`）入队，以保证每个会话同一时间只有一个活跃运行。
- 每个会话运行随后被排入**全局通道**（默认为 `main`），因此整体并行度受 `agents.defaults.maxConcurrent` 限制。
- 启用详细日志时，如果排队的运行在启动前等待超过约 2 秒，会发出一条简短通知。
- 输入指示器在入队时仍会立即触发（当渠道支持时），因此在等待期间用户体验不受影响。
## 队列模式（按渠道）
入站消息可以引导当前运行、等待后续轮次，或两者兼顾：
- `steer`：立即注入当前运行（在下一个工具边界后取消待执行的工具调用）。如果未在流式传输，则回退为 followup。
- `followup`：在当前运行结束后排队等待下一个智能体轮次。
- `collect`：将所有排队消息合并为**单个**后续轮次（默认）。如果消息针对不同的渠道/线程，它们会单独排空以保留路由。
- `steer-backlog`（又名 `steer+backlog`）：立即引导**并且**保留消息用于后续轮次。
- `interrupt`（旧版）：中止该会话的活跃运行，然后运行最新消息。
- `queue`（旧版别名）：等同于 `steer`。
steer-backlog 意味着在引导运行之后你还能获得后续响应，因此流式传输界面可能看起来像重复内容。如果希望每条入站消息只获得一次响应，请优先使用 `collect`/`steer`。
发送 `/queue collect` 作为独立命令（按会话生效），或设置 `messages.queue.byChannel.discord: "collect"`。
默认值（配置中未设置时）：
- 所有界面 → `collect`
通过 `messages.queue` 进行全局或按渠道配置：
```json5
{
messages: {
queue: {
mode: "collect",
debounceMs: 1000,
cap: 20,
drop: "summarize",
byChannel: { discord: "collect" },
},
},
}
```
## 队列选项
选项适用于 `followup`、`collect` 和 `steer-backlog`（以及 `steer` 回退为 followup 时）：
- `debounceMs`：在启动后续轮次前等待静默期（防止"继续，继续"的情况）。
- `cap`：每个会话的最大排队消息数。
- `drop`：溢出策略（`old`、`new`、`summarize`）。
summarize 会保留一个被丢弃消息的简短要点列表，并将其作为合成的后续提示词注入。
默认值：`debounceMs: 1000`、`cap: 20`、`drop: summarize`。
## 按会话覆盖
- 发送 `/queue <mode>` 作为独立命令，可将该模式存储到当前会话。
- 选项可以组合使用：`/queue collect debounce:2s cap:25 drop:summarize`
- `/queue default` 或 `/queue reset` 清除会话覆盖。
## 作用范围与保证
- 适用于所有使用 Gateway 回复管道的入站渠道的自动回复智能体运行（WhatsApp 网页版、Telegram、Slack、Discord、Signal、iMessage、网页聊天等）。
- 默认通道（`main`）在进程范围内适用于入站消息和主心跳；设置 `agents.defaults.maxConcurrent` 以允许多个会话并行。
- 可能存在其他通道（如 `cron`、`subagent`），以便后台任务可以并行运行而不阻塞入站回复。
- 按会话通道保证同一时间只有一个智能体运行接触给定会话。
- 无外部依赖或后台工作线程；纯 TypeScript + Promise 实现。
## 故障排除
- 如果命令似乎卡住，启用详细日志并查找 "queued for …ms" 行，以确认队列正在正常排空。
- 如果需要查看队列深度，启用详细日志并观察队列计时行。

76
docs/zh-CN/concepts/retry.md Normal file
View File

@@ -0,0 +1,76 @@
---
read_when:
- 更新提供商重试行为或默认值
- 调试提供商发送错误或速率限制
summary: 出站提供商调用的重试策略
title: 重试策略
x-i18n:
generated_at: "2026-02-01T20:23:37Z"
model: claude-opus-4-5
provider: pi
source_hash: 55bb261ff567f46ce447be9c0ee0c5b5e6d2776287d7662762656c14108dd607
source_path: concepts/retry.md
workflow: 14
---
# 重试策略
## 目标
- 按 HTTP 请求重试，而非按多步骤流程重试。
- 通过仅重试当前步骤来保持顺序。
- 避免重复执行非幂等操作。
## 默认值
- 尝试次数：3
- 最大延迟上限：30000 毫秒
- 抖动：0.1（10%）
- 提供商默认值：
- Telegram 最小延迟：400 毫秒
- Discord 最小延迟：500 毫秒
## 行为
### Discord
- 仅在速率限制错误（HTTP 429）时重试。
- 可用时使用 Discord `retry_after`，否则使用指数退避。
### Telegram
- 在瞬态错误时重试（429、超时、连接/重置/关闭、暂时不可用）。
- 可用时使用 `retry_after`，否则使用指数退避。
- Markdown 解析错误不会重试；会回退为纯文本。
## 配置
在 `~/.openclaw/openclaw.json` 中按提供商设置重试策略：
```json5
{
channels: {
telegram: {
retry: {
attempts: 3,
minDelayMs: 400,
maxDelayMs: 30000,
jitter: 0.1,
},
},
discord: {
retry: {
attempts: 3,
minDelayMs: 500,
maxDelayMs: 30000,
jitter: 0.1,
},
},
},
}
```
## 注意事项
- 重试按请求应用（消息发送、媒体上传、表情回应、投票、贴纸）。
- 组合流程不会重试已完成的步骤。

129
docs/zh-CN/concepts/session-pruning.md Normal file
View File

@@ -0,0 +1,129 @@
---
read_when:
- 你想减少工具输出导致的 LLM 上下文增长
- 你正在调优 agents.defaults.contextPruning
summary: 会话裁剪：通过修剪工具结果来减少上下文膨胀
x-i18n:
generated_at: "2026-02-01T20:23:53Z"
model: claude-opus-4-5
provider: pi
source_hash: 9b0aa2d1abea7050ba848a2db038ccc3e6e2d83c6eb4e3843a2ead0ab847574a
source_path: concepts/session-pruning.md
workflow: 14
---
# 会话裁剪
会话裁剪在每次 LLM 调用之前修剪内存上下文中的**旧工具结果**。它**不会**重写磁盘上的会话历史（`*.jsonl`）。
## 运行时机
- 当启用 `mode: "cache-ttl"` 且该会话的上次 Anthropic 调用时间超过 `ttl` 时触发。
- 仅影响该请求发送给模型的消息。
- 仅对 Anthropic API 调用（以及 OpenRouter Anthropic 模型）生效。
- 为获得最佳效果，请将 `ttl` 与模型的 `cacheControlTtl` 保持一致。
- 裁剪后，TTL 窗口会重置，后续请求将继续使用缓存直到 `ttl` 再次过期。
## 智能默认值（Anthropic）
- **OAuth 或 setup-token** 配置文件：启用 `cache-ttl` 裁剪，并将心跳设置为 `1h`。
- **API 密钥**配置文件：启用 `cache-ttl` 裁剪，将心跳设置为 `30m`，并将 Anthropic 模型的 `cacheControlTtl` 默认设为 `1h`。
- 如果你显式设置了这些值中的任何一个，OpenClaw **不会**覆盖它们。
## 改善效果（成本 + 缓存行为）
- **为什么要裁剪：** Anthropic 提示缓存仅在 TTL 内生效。如果会话空闲超过 TTL，下一次请求将重新缓存完整提示，除非你先对其进行修剪。
- **哪些费用会降低：** 裁剪减少了 TTL 过期后首次请求的 **cacheWrite** 大小。
- **为什么 TTL 重置很重要：** 裁剪运行后，缓存窗口会重置，因此后续请求可以复用新缓存的提示，而不是再次重新缓存完整历史。
- **它不会做什么：** 裁剪不会增加令牌或"翻倍"成本；它只改变 TTL 过期后首次请求的缓存内容。
## 可裁剪的内容
- 仅限 `toolResult` 消息。
- 用户和助手消息**永远不会**被修改。
- 最后 `keepLastAssistants` 条助手消息受保护；该截止点之后的工具结果不会被裁剪。
- 如果助手消息数量不足以确定截止点，则跳过裁剪。
- 包含**图片块**的工具结果会被跳过（永远不会被修剪/清除）。
## 上下文窗口估算
裁剪使用估算的上下文窗口（字符数 ≈ 令牌数 × 4）。基础窗口按以下顺序解析：
1. `models.providers.*.models[].contextWindow` 覆盖值。
2. 模型定义中的 `contextWindow`（来自模型注册表）。
3. 默认 `200000` 令牌。
如果设置了 `agents.defaults.contextTokens`，它将作为解析窗口的上限（取最小值）。
## 模式
### cache-ttl
- 仅当上次 Anthropic 调用时间超过 `ttl`（默认 `5m`）时才运行裁剪。
- 运行时：与之前相同的软修剪 + 硬清除行为。
## 软裁剪与硬裁剪
- **软修剪**：仅针对超大的工具结果。
- 保留头部和尾部，插入 `...`，并附加一条包含原始大小的说明。
- 跳过包含图片块的结果。
- **硬清除**：用 `hardClear.placeholder` 替换整个工具结果。
## 工具选择
- `tools.allow` / `tools.deny` 支持 `*` 通配符。
- 拒绝优先。
- 匹配不区分大小写。
- 允许列表为空 => 允许所有工具。
## 与其他限制的交互
- 内置工具已经会截断自身的输出；会话裁剪是一个额外的保护层，防止长时间运行的对话在模型上下文中积累过多的工具输出。
- 压缩是独立的：压缩会进行摘要并持久化，裁剪则是每次请求的临时操作。参见 [/concepts/compaction](/concepts/compaction)。
## 默认值（启用时）
- `ttl`：`"5m"`
- `keepLastAssistants`：`3`
- `softTrimRatio`：`0.3`
- `hardClearRatio`：`0.5`
- `minPrunableToolChars`：`50000`
- `softTrim`：`{ maxChars: 4000, headChars: 1500, tailChars: 1500 }`
- `hardClear`：`{ enabled: true, placeholder: "[Old tool result content cleared]" }`
## 示例
默认（关闭）：
```json5
{
agent: {
contextPruning: { mode: "off" },
},
}
```
启用 TTL 感知裁剪：
```json5
{
agent: {
contextPruning: { mode: "cache-ttl", ttl: "5m" },
},
}
```
将裁剪限制为特定工具：
```json5
{
agent: {
contextPruning: {
mode: "cache-ttl",
tools: { allow: ["exec", "read"], deny: ["*image*"] },
},
},
}
```
参见配置参考：[Gateway 配置](/gateway/configuration)

200
docs/zh-CN/concepts/session-tool.md Normal file
View File

@@ -0,0 +1,200 @@
---
read_when:
- 添加或修改会话工具
summary: 智能体会话工具：列出会话、获取历史记录和发送跨会话消息
title: 会话工具
x-i18n:
generated_at: "2026-02-01T20:24:08Z"
model: claude-opus-4-5
provider: pi
source_hash: cb6e0982ebf507bcf9de4bb17719759c2b6d3e519731c845580a55279084e4c8
source_path: concepts/session-tool.md
workflow: 14
---
# 会话工具
目标：提供小型、不易误用的工具集，使智能体能够列出会话、获取历史记录以及向其他会话发送消息。
## 工具名称
- `sessions_list`
- `sessions_history`
- `sessions_send`
- `sessions_spawn`
## 键模型
- 主私聊桶始终使用字面键 `"main"`（解析为当前智能体的主键）。
- 群聊使用 `agent:<agentId>:<channel>:group:<id>` 或 `agent:<agentId>:<channel>:channel:<id>`（传入完整键）。
- 定时任务使用 `cron:<job.id>`。
- 钩子使用 `hook:<uuid>`，除非显式设置。
- 节点会话使用 `node-<nodeId>`，除非显式设置。
`global` 和 `unknown` 是保留值，永远不会被列出。如果 `session.scope = "global"`，我们会将其别名为 `main` 供所有工具使用，这样调用方永远看不到 `global`。
## sessions_list
以行数组形式列出会话。
参数：
- `kinds?: string[]` 过滤器：`"main" | "group" | "cron" | "hook" | "node" | "other"` 的任意组合
- `limit?: number` 最大行数（默认：服务器默认值，上限如 200）
- `activeMinutes?: number` 仅返回 N 分钟内更新的会话
- `messageLimit?: number` 0 = 不返回消息（默认 0）；>0 = 包含最近 N 条消息
行为：
- `messageLimit > 0` 时会获取每个会话的 `chat.history` 并包含最近 N 条消息。
- 列表输出中会过滤工具结果；使用 `sessions_history` 获取工具消息。
- 在**沙箱化**的智能体会话中运行时，会话工具默认为**仅已生成可见**（见下文）。
行结构（JSON）：
- `key`：会话键（字符串）
- `kind`：`main | group | cron | hook | node | other`
- `channel`：`whatsapp | telegram | discord | signal | imessage | webchat | internal | unknown`
- `displayName`（群组显示标签，如可用）
- `updatedAt`（毫秒）
- `sessionId`
- `model`、`contextTokens`、`totalTokens`
- `thinkingLevel`、`verboseLevel`、`systemSent`、`abortedLastRun`
- `sendPolicy`（会话覆盖，如已设置）
- `lastChannel`、`lastTo`
- `deliveryContext`（规范化的 `{ channel, to, accountId }`，如可用）
- `transcriptPath`（根据存储目录 + sessionId 推导的尽力路径）
- `messages?`（仅当 `messageLimit > 0` 时）
## sessions_history
获取单个会话的对话记录。
参数：
- `sessionKey`（必需；接受会话键或来自 `sessions_list` 的 `sessionId`）
- `limit?: number` 最大消息数（服务器限制上限）
- `includeTools?: boolean`（默认 false）
行为：
- `includeTools=false` 过滤 `role: "toolResult"` 的消息。
- 以原始对话记录格式返回消息数组。
- 当传入 `sessionId` 时，OpenClaw 会将其解析为对应的会话键（缺失的 ID 会报错）。
## sessions_send
向另一个会话发送消息。
参数：
- `sessionKey`（必需；接受会话键或来自 `sessions_list` 的 `sessionId`）
- `message`（必需）
- `timeoutSeconds?: number`（默认 >0；0 = 即发即忘）
行为：
- `timeoutSeconds = 0`：入队并返回 `{ runId, status: "accepted" }`。
- `timeoutSeconds > 0`：等待最多 N 秒完成，然后返回 `{ runId, status: "ok", reply }`。
- 如果等待超时：`{ runId, status: "timeout", error }`。运行继续；稍后调用 `sessions_history`。
- 如果运行失败：`{ runId, status: "error", error }`。
- 通知投递在主运行完成后运行，属于尽力而为；`status: "ok"` 不保证通知已成功投递。
- 通过 Gateway `agent.wait`（服务器端）等待，因此重连不会中断等待。
- 智能体间消息上下文会注入到主运行中。
- 主运行完成后，OpenClaw 运行**回复往返循环**：
- 第 2 轮及之后在请求方和目标智能体之间交替。
- 回复 `REPLY_SKIP` 可停止来回往返。
- 最大轮数为 `session.agentToAgent.maxPingPongTurns`（0–5，默认 5）。
- 循环结束后，OpenClaw 运行**智能体间通知步骤**（仅目标智能体）：
- 回复 `ANNOUNCE_SKIP` 可保持静默。
- 其他任何回复都会发送到目标渠道。
- 通知步骤包含原始请求 + 第 1 轮回复 + 最新的往返回复。
## Channel 字段
- 对于群组，`channel` 是会话条目上记录的渠道。
- 对于私聊，`channel` 从 `lastChannel` 映射。
- 对于定时任务/钩子/节点，`channel` 为 `internal`。
- 如果缺失，`channel` 为 `unknown`。
## 安全 / 发送策略
基于策略的按渠道/聊天类型阻止（非按会话 ID）。
```json
{
"session": {
"sendPolicy": {
"rules": [
{
"match": { "channel": "discord", "chatType": "group" },
"action": "deny"
}
],
"default": "allow"
}
}
}
```
运行时覆盖（按会话条目）：
- `sendPolicy: "allow" | "deny"`（未设置 = 继承配置）
- 可通过 `sessions.patch` 或仅所有者的 `/send on|off|inherit`（独立消息）设置。
执行点：
- `chat.send` / `agent`（Gateway）
- 自动回复投递逻辑
## sessions_spawn
在隔离会话中生成子智能体运行，并将结果通知回请求方的聊天渠道。
参数：
- `task`（必需）
- `label?`（可选；用于日志/UI）
- `agentId?`（可选；如允许，在另一个智能体 ID 下生成）
- `model?`（可选；覆盖子智能体模型；无效值会报错）
- `runTimeoutSeconds?`（默认 0；设置后，N 秒后中止子智能体运行）
- `cleanup?`（`delete|keep`，默认 `keep`）
允许列表：
- `agents.list[].subagents.allowAgents`：允许通过 `agentId` 使用的智能体 ID 列表（`["*"]` 允许任意）。默认：仅请求方智能体。
发现：
- 使用 `agents_list` 发现哪些智能体 ID 可用于 `sessions_spawn`。
行为：
- 启动一个新的 `agent:<agentId>:subagent:<uuid>` 会话，设置 `deliver: false`。
- 子智能体默认使用完整工具集**减去会话工具**（可通过 `tools.subagents.tools` 配置）。
- 子智能体不允许调用 `sessions_spawn`（不允许子智能体生成子智能体）。
- 始终非阻塞：立即返回 `{ status: "accepted", runId, childSessionKey }`。
- 完成后，OpenClaw 运行子智能体**通知步骤**并将结果发布到请求方的聊天渠道。
- 在通知步骤中回复 `ANNOUNCE_SKIP` 可保持静默。
- 通知回复规范化为 `Status`/`Result`/`Notes`；`Status` 来自运行时结果（非模型文本）。
- 子智能体会话在 `agents.defaults.subagents.archiveAfterMinutes`（默认：60）后自动归档。
- 通知回复包含统计行（运行时间、token 数、sessionKey/sessionId、对话记录路径和可选费用）。
## 沙箱会话可见性
沙箱化的会话可以使用会话工具，但默认只能看到通过 `sessions_spawn` 生成的会话。
配置：
```json5
{
agents: {
defaults: {
sandbox: {
// 默认: "spawned"
sessionToolsVisibility: "spawned", // 或 "all"
},
},
},
}
```

166
docs/zh-CN/concepts/session.md Normal file
View File

@@ -0,0 +1,166 @@
---
read_when:
- 修改会话处理或存储时
summary: 聊天的会话管理规则、键和持久化
title: 会话管理
x-i18n:
generated_at: "2026-02-01T20:24:31Z"
model: claude-opus-4-5
provider: pi
source_hash: 147c8d1a4b6b4864cb16ad942feba80181b6b0e29afa765e7958f8c2483746b5
source_path: concepts/session.md
workflow: 14
---
# 会话管理
OpenClaw 将**每个智能体一个私聊会话**视为主会话。私聊归并到 `agent:<agentId>:<mainKey>`（默认 `main`），而群组/频道聊天拥有各自独立的键。`session.mainKey` 会被遵循。
使用 `session.dmScope` 控制**私信**的分组方式：
- `main`（默认）：所有私信共享主会话以保持连续性。
- `per-peer`：按发送者 ID 跨渠道隔离。
- `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。
- `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号收件箱）。
使用 `session.identityLinks` 将带提供商前缀的对端 ID 映射到规范身份，这样在使用 `per-peer`、`per-channel-peer` 或 `per-account-channel-peer` 时，同一个人可以跨渠道共享私信会话。
## Gateway 是权威数据源
所有会话状态均由 **Gateway**（"主" OpenClaw）管理。UI 客户端（macOS 应用、WebChat 等）必须向 Gateway 查询会话列表和令牌计数，而不是读取本地文件。
- 在**远程模式**下，你关心的会话存储位于远程 Gateway 主机上，而不是你的 Mac 上。
- UI 中显示的令牌计数来自 Gateway 存储字段（`inputTokens`、`outputTokens`、`totalTokens`、`contextTokens`）。客户端不会解析 JSONL 记录来"修正"总数。
## 状态存储位置
- 在 **Gateway 主机**上：
- 存储文件：`~/.openclaw/agents/<agentId>/sessions/sessions.json`（每个智能体）。
- 对话记录：`~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl`（Telegram 话题会话使用 `.../<SessionId>-topic-<threadId>.jsonl`）。
- 存储是一个 `sessionKey -> { sessionId, updatedAt, ... }` 的映射。删除条目是安全的；它们会按需重新创建。
- 群组条目可能包含 `displayName`、`channel`、`subject`、`room` 和 `space`，用于在 UI 中标记会话。
- 会话条目包含 `origin` 元数据（标签 + 路由提示），以便 UI 能够解释会话的来源。
- OpenClaw **不会**读取旧版 Pi/Tau 会话文件夹。
## 会话修剪
OpenClaw 默认在 LLM 调用之前从内存上下文中修剪**旧的工具结果**。
这**不会**重写 JSONL 历史记录。请参见 [/concepts/session-pruning](/concepts/session-pruning)。
## 压缩前记忆刷写
当会话接近自动压缩时，OpenClaw 可以运行一次**静默记忆刷写**轮次，提醒模型将持久笔记写入磁盘。这仅在工作区可写时运行。请参见[记忆](/concepts/memory)和[压缩](/concepts/compaction)。
## 传输层 → 会话键的映射
- 私聊遵循 `session.dmScope`（默认 `main`）。
- `main`：`agent:<agentId>:<mainKey>`（跨设备/渠道保持连续性）。
- 多个电话号码和渠道可以映射到同一个智能体主键；它们充当一个对话的传输通道。
- `per-peer`：`agent:<agentId>:dm:<peerId>`。
- `per-channel-peer`：`agent:<agentId>:<channel>:dm:<peerId>`。
- `per-account-channel-peer`：`agent:<agentId>:<channel>:<accountId>:dm:<peerId>`（accountId 默认为 `default`）。
- 如果 `session.identityLinks` 匹配到带提供商前缀的对端 ID（例如 `telegram:123`），规范键将替换 `<peerId>`，使同一个人跨渠道共享会话。
- 群聊隔离状态：`agent:<agentId>:<channel>:group:<id>`（房间/频道使用 `agent:<agentId>:<channel>:channel:<id>`）。
- Telegram 论坛话题在群组 ID 后附加 `:topic:<threadId>` 以实现隔离。
- 旧版 `group:<id>` 键仍被识别以支持迁移。
- 入站上下文可能仍使用 `group:<id>`；渠道从 `Provider` 推断并规范化为 `agent:<agentId>:<channel>:group:<id>` 的规范形式。
- 其他来源：
- 定时任务：`cron:<job.id>`
- Webhook：`hook:<uuid>`（除非由 hook 显式设置）
- 节点运行：`node-<nodeId>`
## 生命周期
- 重置策略：会话持续复用直到过期，过期在下一条入站消息时评估。
- 每日重置：默认为 **Gateway 主机本地时间凌晨 4:00**。当会话的最后更新早于最近一次每日重置时间时，会话即为过期。
- 空闲重置（可选）：`idleMinutes` 添加一个滑动空闲窗口。当同时配置了每日重置和空闲重置时，**先到期的那个**强制创建新会话。
- 旧版仅空闲模式：如果设置了 `session.idleMinutes` 但没有任何 `session.reset`/`resetByType` 配置，OpenClaw 会保持仅空闲模式以向后兼容。
- 按类型覆盖（可选）：`resetByType` 允许你为 `dm`、`group` 和 `thread` 会话覆盖策略（thread = Slack/Discord 线程、Telegram 话题、连接器提供的 Matrix 线程）。
- 按渠道覆盖（可选）：`resetByChannel` 覆盖特定渠道的重置策略（适用于该渠道的所有会话类型，优先级高于 `reset`/`resetByType`）。
- 重置触发器：精确的 `/new` 或 `/reset`（加上 `resetTriggers` 中的额外项）会启动一个新的会话 ID，并将消息的剩余部分继续传递。`/new <model>` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）来设置新会话的模型。如果单独发送 `/new` 或 `/reset`，OpenClaw 会运行一个简短的"问候"轮次来确认重置。
- 手动重置：从存储中删除特定键或移除 JSONL 记录；下一条消息会重新创建它们。
- 隔离的定时任务每次运行都会创建一个新的 `sessionId`（不复用空闲会话）。
## 发送策略（可选）
无需列出单个 ID 即可按特定会话类型阻止投递。
```json5
{
session: {
sendPolicy: {
rules: [
{ action: "deny", match: { channel: "discord", chatType: "group" } },
{ action: "deny", match: { keyPrefix: "cron:" } },
],
default: "allow",
},
},
}
```
运行时覆盖（仅限所有者）：
- `/send on` → 允许此会话发送
- `/send off` → 禁止此会话发送
- `/send inherit` → 清除覆盖并使用配置规则
请将这些作为独立消息发送以确保生效。
## 配置（可选的重命名示例）
```json5
// ~/.openclaw/openclaw.json
{
session: {
scope: "per-sender", // 保持群组键独立
dmScope: "main", // 私信连续性（共享收件箱请设置 per-channel-peer/per-account-channel-peer）
identityLinks: {
alice: ["telegram:123456789", "discord:987654321012345678"],
},
reset: {
// 默认值：mode=daily，atHour=4（Gateway 主机本地时间）。
// 如果同时设置了 idleMinutes，先到期的优先。
mode: "daily",
atHour: 4,
idleMinutes: 120,
},
resetByType: {
thread: { mode: "daily", atHour: 4 },
dm: { mode: "idle", idleMinutes: 240 },
group: { mode: "idle", idleMinutes: 120 },
},
resetByChannel: {
discord: { mode: "idle", idleMinutes: 10080 },
},
resetTriggers: ["/new", "/reset"],
store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
mainKey: "main",
},
}
```
## 检查
- `openclaw status` — 显示存储路径和最近的会话。
- `openclaw sessions --json` — 转储所有条目（使用 `--active <minutes>` 进行筛选）。
- `openclaw gateway call sessions.list --params '{}'` — 从运行中的 Gateway 获取会话（使用 `--url`/`--token` 访问远程 Gateway）。
- 在聊天中发送 `/status` 作为独立消息，可查看智能体是否可达、会话上下文使用了多少、当前的思考/详细模式开关，以及 WhatsApp 网页凭证的最后刷新时间（有助于发现需要重新链接的情况）。
- 发送 `/context list` 或 `/context detail` 查看系统提示词和注入的工作区文件中的内容（以及最大的上下文贡献者）。
- 发送 `/stop` 作为独立消息，可中止当前运行、清除该会话的排队后续消息，并停止由其生成的任何子智能体运行（回复中包含已停止的数量）。
- 发送 `/compact`（可选指令）作为独立消息，可总结旧的上下文并释放窗口空间。请参见 [/concepts/compaction](/concepts/compaction)。
- JSONL 记录可以直接打开以查看完整的对话轮次。
## 提示
- 将主键专用于一对一对话；让群组保持各自独立的键。
- 自动化清理时，删除单个键而不是整个存储，以保留其他地方的上下文。
## 会话来源元数据
每个会话条目在 `origin` 中记录其来源（尽力而为）：
- `label`：人类可读标签（从对话标签 + 群组主题/频道解析）
- `provider`：规范化的渠道 ID（包括扩展）
- `from`/`to`：入站信封中的原始路由 ID
- `accountId`：提供商账号 ID（多账号时）
- `threadId`：渠道支持时的线程/话题 ID
来源字段为私信、频道和群组填充。如果连接器仅更新投递路由（例如，保持私信主会话活跃），它仍应提供入站上下文，以便会话保留其说明性元数据。扩展可以通过在入站上下文中发送 `ConversationLabel`、`GroupSubject`、`GroupChannel`、`GroupSpace` 和 `SenderName`，并调用 `recordSessionMetaFromInbound`（或将相同的上下文传递给 `updateLastRoute`）来实现。

17
docs/zh-CN/concepts/sessions.md Normal file
View File

@@ -0,0 +1,17 @@
---
read_when:
- 你查找了 docs/sessions.md；规范文档位于 docs/session.md
summary: 会话管理文档的别名
title: 会话
x-i18n:
generated_at: "2026-02-01T20:23:55Z"
model: claude-opus-4-5
provider: pi
source_hash: 7f1e39c3c07b9bb5cdcda361399cf1ce1226ebae3a797d8f93e734aa6a4d00e2
source_path: concepts/sessions.md
workflow: 14
---
# 会话
规范的会话管理文档位于[会话管理](/concepts/session)。

133
docs/zh-CN/concepts/streaming.md Normal file
View File

@@ -0,0 +1,133 @@
---
read_when:
- 解释流式传输或分块在渠道上的工作方式
- 更改块流式传输或渠道分块行为
- 调试重复/提前的块回复或草稿流式传输问题
summary: 流式传输 + 分块行为（块回复、草稿流式传输、限制）
title: 流式传输与分块
x-i18n:
generated_at: "2026-02-01T20:24:24Z"
model: claude-opus-4-5
provider: pi
source_hash: f014eb1898c4351b1d6b812223226d91324701e3e809cd0f3faf6679841bc353
source_path: concepts/streaming.md
workflow: 14
---
# 流式传输 + 分块
OpenClaw 有两个独立的"流式传输"层：
- **块流式传输（渠道）：** 在助手生成内容时发送已完成的**块**。这些是普通的渠道消息（不是 token 增量）。
- **类 Token 流式传输（仅 Telegram）：** 在生成过程中用部分文本更新**草稿气泡**；最终消息在结束时发送。
目前**没有真正的 token 流式传输**到外部渠道消息。Telegram 草稿流式传输是唯一的部分流式传输界面。
## 块流式传输（渠道消息）
块流式传输在助手输出可用时以粗粒度块发送。
```
Model output
└─ text_delta/events
├─ (blockStreamingBreak=text_end)
│ └─ chunker emits blocks as buffer grows
└─ (blockStreamingBreak=message_end)
└─ chunker flushes at message_end
└─ channel send (block replies)
```
图例：
- `text_delta/events`：模型流事件（对于非流式模型可能较为稀疏）。
- `chunker`：`EmbeddedBlockChunker`，应用最小/最大边界 + 断点偏好。
- `channel send`：实际的出站消息（块回复）。
**控制项：**
- `agents.defaults.blockStreamingDefault`：`"on"`/`"off"`（默认关闭）。
- 渠道覆盖：`*.blockStreaming`（以及按账户的变体）可按渠道强制 `"on"`/`"off"`。
- `agents.defaults.blockStreamingBreak`：`"text_end"` 或 `"message_end"`。
- `agents.defaults.blockStreamingChunk`：`{ minChars, maxChars, breakPreference? }`。
- `agents.defaults.blockStreamingCoalesce`：`{ minChars?, maxChars?, idleMs? }`（发送前合并流式块）。
- 渠道硬性上限：`*.textChunkLimit`（例如 `channels.whatsapp.textChunkLimit`）。
- 渠道分块模式：`*.chunkMode`（默认 `length`，`newline` 在空行（段落边界）处分割，然后再按长度分块）。
- Discord 软性上限：`channels.discord.maxLinesPerMessage`（默认 17）拆分过长的回复以避免 UI 裁剪。
**边界语义：**
- `text_end`：分块器发出块后立即流式传输；在每个 `text_end` 时刷新。
- `message_end`：等待助手消息完成后，再刷新缓冲输出。
`message_end` 在缓冲文本超过 `maxChars` 时仍会使用分块器，因此可能在最后发出多个块。
## 分块算法（低/高边界）
块分块由 `EmbeddedBlockChunker` 实现：
- **低边界：** 在缓冲区 >= `minChars` 之前不发出（除非强制）。
- **高边界：** 优先在 `maxChars` 之前分割；如果强制，则在 `maxChars` 处分割。
- **断点偏好：** `paragraph` → `newline` → `sentence` → `whitespace` → 硬断点。
- **代码围栏：** 永远不在围栏内分割；当在 `maxChars` 处被强制分割时，关闭并重新打开围栏以保持 Markdown 有效。
`maxChars` 会被限制在渠道的 `textChunkLimit` 以内，因此不会超过按渠道的上限。
## 合并（合并流式块）
当块流式传输启用时，OpenClaw 可以在发送前**合并连续的块**。这减少了"单行刷屏"的情况，同时仍提供渐进式输出。
- 合并会等待**空闲间隔**（`idleMs`）后再刷新。
- 缓冲区受 `maxChars` 限制，超出时会刷新。
- `minChars` 防止在积累足够文本之前发送微小片段（最终刷新始终发送剩余文本）。
- 连接符由 `blockStreamingChunk.breakPreference` 派生（`paragraph` → `\n\n`，`newline` → `\n`，`sentence` → 空格）。
- 渠道覆盖可通过 `*.blockStreamingCoalesce` 设置（包括按账户的配置）。
- 除非覆盖，Signal/Slack/Discord 的默认合并 `minChars` 会提升至 1500。
## 块之间的仿真人节奏
当块流式传输启用时，你可以在块回复之间（第一个块之后）添加**随机停顿**。这让多气泡回复感觉更自然。
- 配置：`agents.defaults.humanDelay`（通过 `agents.list[].humanDelay` 按智能体覆盖）。
- 模式：`off`（默认）、`natural`（800–2500ms）、`custom`（`minMs`/`maxMs`）。
- 仅适用于**块回复**，不适用于最终回复或工具摘要。
## "流式发送块还是一次性发送全部"
对应关系：
- **流式发送块：** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"`（边生成边发送）。非 Telegram 渠道还需要设置 `*.blockStreaming: true`。
- **结束时一次性发送：** `blockStreamingBreak: "message_end"`（刷新一次，如果内容很长可能产生多个块）。
- **不使用块流式传输：** `blockStreamingDefault: "off"`（仅最终回复）。
**渠道说明：** 对于非 Telegram 渠道，块流式传输**默认关闭**，除非 `*.blockStreaming` 显式设置为 `true`。Telegram 可以通过 `channels.telegram.streamMode` 进行草稿流式传输，无需块回复。
配置位置提醒：`blockStreaming*` 默认值位于 `agents.defaults` 下，而非根配置。
## Telegram 草稿流式传输（类 Token）
Telegram 是唯一支持草稿流式传输的渠道：
- 在**带话题的私聊**中使用 Bot API `sendMessageDraft`。
- `channels.telegram.streamMode: "partial" | "block" | "off"`。
- `partial`：用最新的流式文本更新草稿。
- `block`：以分块方式更新草稿（使用相同的分块器规则）。
- `off`：不进行草稿流式传输。
- 草稿分块配置（仅用于 `streamMode: "block"`）：`channels.telegram.draftChunk`（默认值：`minChars: 200`，`maxChars: 800`）。
- 草稿流式传输与块流式传输是分离的；块回复默认关闭，仅在非 Telegram 渠道通过 `*.blockStreaming: true` 启用。
- 最终回复仍然是普通消息。
- `/reasoning stream` 将推理过程写入草稿气泡（仅 Telegram）。
当草稿流式传输处于活跃状态时，OpenClaw 会禁用该回复的块流式传输，以避免双重流式传输。
```
Telegram (private + topics)
└─ sendMessageDraft (draft bubble)
├─ streamMode=partial → update latest text
└─ streamMode=block → chunker updates draft
└─ final reply → normal message
```
图例：
- `sendMessageDraft`：Telegram 草稿气泡（不是真正的消息）。
- `final reply`：普通的 Telegram 消息发送。

101
docs/zh-CN/concepts/system-prompt.md Normal file
View File

@@ -0,0 +1,101 @@
---
read_when:
- 编辑系统提示词文本、工具列表或时间/心跳部分
- 更改工作区引导或技能注入行为
summary: OpenClaw 系统提示词的内容及其组装方式
title: 系统提示词
x-i18n:
generated_at: "2026-02-01T20:24:17Z"
model: claude-opus-4-5
provider: pi
source_hash: bef4b2674ba0414ce28fd08a4c3ead0e0ebe989e7df3c88ca8a0b2abfec2a50b
source_path: concepts/system-prompt.md
workflow: 14
---
# 系统提示词
OpenClaw 为每次智能体运行构建自定义系统提示词。该提示词由 **OpenClaw 自有**，不使用 p-coding-agent 的默认提示词。
提示词由 OpenClaw 组装并注入到每次智能体运行中。
## 结构
提示词有意保持紧凑，使用固定的部分：
- **工具**：当前工具列表及简短描述。
- **安全**：简短的护栏提醒，避免模型追求权力或绕过监督。
- **技能**（可用时）：告诉模型如何按需加载技能指令。
- **OpenClaw 自更新**：如何运行 `config.apply` 和 `update.run`。
- **工作区**：工作目录（`agents.defaults.workspace`）。
- **文档**：OpenClaw 文档的本地路径（仓库或 npm 包）及查阅时机。
- **工作区文件（注入的）**：表明引导文件包含在下方。
- **沙箱**（启用时）：表明沙箱化运行时、沙箱路径，以及是否可用提权执行。
- **当前日期和时间**：用户本地时间、时区和时间格式。
- **回复标签**：支持的提供商的可选回复标签语法。
- **心跳**：心跳提示和确认行为。
- **运行时**：主机、操作系统、Node、模型、仓库根目录（检测到时）、思考级别（一行）。
- **推理**：当前可见性级别及 /reasoning 切换提示。
系统提示词中的安全护栏是建议性的。它们引导模型行为但不强制执行策略。请使用工具策略、执行审批、沙箱化和渠道白名单进行硬性执行；操作人员可以按设计禁用这些功能。
## 提示词模式
OpenClaw 可以为子智能体渲染更小的系统提示词。运行时为每次运行设置一个 `promptMode`（非用户可配置项）：
- `full`（默认）：包含上述所有部分。
- `minimal`：用于子智能体；省略**技能**、**记忆召回**、**OpenClaw 自更新**、**模型别名**、**用户身份**、**回复标签**、**消息**、**静默回复**和**心跳**。工具、**安全**、工作区、沙箱、当前日期和时间（已知时）、运行时和注入的上下文仍然可用。
- `none`：仅返回基础身份行。
当 `promptMode=minimal` 时，额外注入的提示词标记为**子智能体上下文**而非**群聊上下文**。
## 工作区引导注入
引导文件经过裁剪后附加在**项目上下文**下，使模型无需显式读取即可看到身份和配置上下文：
- `AGENTS.md`
- `SOUL.md`
- `TOOLS.md`
- `IDENTITY.md`
- `USER.md`
- `HEARTBEAT.md`
- `BOOTSTRAP.md`（仅在全新工作区时）
大文件会被截断并附加标记。每个文件的最大大小由 `agents.defaults.bootstrapMaxChars` 控制（默认：20000）。缺失的文件会注入一个简短的缺失文件标记。
内部钩子可以通过 `agent:bootstrap` 拦截此步骤，以修改或替换注入的引导文件（例如将 `SOUL.md` 替换为备选人格）。
要查看每个注入文件的贡献量（原始 vs 注入、截断情况，以及工具模式开销），请使用 `/context list` 或 `/context detail`。参见[上下文](/concepts/context)。
## 时间处理
当用户时区已知时，系统提示词包含专门的**当前日期和时间**部分。为保持提示词缓存稳定，现在仅包含**时区**（不含动态时钟或时间格式）。
当智能体需要当前时间时，请使用 `session_status`；状态卡片包含时间戳行。
配置方式：
- `agents.defaults.userTimezone`
- `agents.defaults.timeFormat`（`auto` | `12` | `24`）
详见[日期和时间](/date-time)了解完整行为细节。
## 技能
当存在符合条件的技能时，OpenClaw 会注入一个紧凑的**可用技能列表**（`formatSkillsForPrompt`），其中包含每个技能的**文件路径**。提示词指示模型使用 `read` 加载位于所列位置（工作区、托管或捆绑）的 SKILL.md。如果没有符合条件的技能，则省略技能部分。
```
<available_skills>
<skill>
<name>...</name>
<description>...</description>
<location>...</location>
</skill>
</available_skills>
```
这样可以保持基础提示词精简，同时仍然支持有针对性的技能使用。
## 文档
当可用时，系统提示词包含一个**文档**部分，指向本地 OpenClaw 文档目录（仓库工作区中的 `docs/` 或捆绑的 npm 包文档），并注明公共镜像、源代码仓库、社区 Discord 和 ClawHub (https://clawhub.com) 用于技能发现。提示词指示模型在查询 OpenClaw 行为、命令、配置或架构时优先查阅本地文档，并在可能时自行运行 `openclaw status`（仅在无法访问时才询问用户）。

96
docs/zh-CN/concepts/timezone.md Normal file
View File

@@ -0,0 +1,96 @@
---
read_when:
- 需要了解时间戳如何为模型进行规范化
- 为系统提示词配置用户时区
summary: 智能体、信封和提示词的时区处理
title: 时区
x-i18n:
generated_at: "2026-02-01T20:24:13Z"
model: claude-opus-4-5
provider: pi
source_hash: 9ee809c96897db1126c7efcaa5bf48a63cdcb2092abd4b3205af224ebd882766
source_path: concepts/timezone.md
workflow: 14
---
# 时区
OpenClaw 对时间戳进行标准化，使模型看到**单一的参考时间**。
## 消息信封（默认为本地时间）
入站消息被包装在如下信封中：
```
[Provider ... 2026-01-05 16:26 PST] message text
```
信封中的时间戳**默认为主机本地时间**，精确到分钟。
你可以通过以下配置进行覆盖：
```json5
{
agents: {
defaults: {
envelopeTimezone: "local", // "utc" | "local" | "user" | IANA 时区
envelopeTimestamp: "on", // "on" | "off"
envelopeElapsed: "on", // "on" | "off"
},
},
}
```
- `envelopeTimezone: "utc"` 使用 UTC。
- `envelopeTimezone: "user"` 使用 `agents.defaults.userTimezone`（回退到主机时区）。
- 使用显式 IANA 时区（例如 `"Europe/Vienna"`）可设置固定偏移量。
- `envelopeTimestamp: "off"` 从信封头中移除绝对时间戳。
- `envelopeElapsed: "off"` 移除已用时间后缀（`+2m` 样式）。
### 示例
**本地时间（默认）：**
```
[Signal Alice +1555 2026-01-18 00:19 PST] hello
```
**固定时区：**
```
[Signal Alice +1555 2026-01-18 06:19 GMT+1] hello
```
**已用时间：**
```
[Signal Alice +1555 +2m 2026-01-18T05:19Z] follow-up
```
## 工具负载（原始提供商数据 + 规范化字段）
工具调用（`channels.discord.readMessages`、`channels.slack.readMessages` 等）返回**原始提供商时间戳**。我们还附加规范化字段以保持一致性：
- `timestampMs`（UTC 纪元毫秒数）
- `timestampUtc`（ISO 8601 UTC 字符串）
原始提供商字段保持不变。
## 系统提示词的用户时区
设置 `agents.defaults.userTimezone` 来告知模型用户的本地时区。如果未设置，OpenClaw 会在运行时**解析主机时区**（无需写入配置）。
```json5
{
agents: { defaults: { userTimezone: "America/Chicago" } },
}
```
系统提示词包含：
- `Current Date & Time` 部分，显示本地时间和时区
- `Time format: 12-hour` 或 `24-hour`
你可以通过 `agents.defaults.timeFormat`（`auto` | `12` | `24`）控制提示词格式。
详情参见[日期与时间](/date-time)的完整行为和示例。

284
docs/zh-CN/concepts/typebox.md Normal file
View File

@@ -0,0 +1,284 @@
---
read_when:
- 更新协议模式或代码生成
summary: TypeBox 模式作为 Gateway 协议的唯一事实来源
title: TypeBox
x-i18n:
generated_at: "2026-02-01T20:24:36Z"
model: claude-opus-4-5
provider: pi
source_hash: 233800f4f5fabe8ed0e1b3d8aded2eca27252e08c9b0b24ea9c6293e9282c918
source_path: concepts/typebox.md
workflow: 14
---
# TypeBox 作为协议的唯一事实来源
最后更新：2026-01-10
TypeBox 是一个 TypeScript 优先的模式库。我们用它来定义 **Gateway WebSocket 协议**（握手、请求/响应、服务器事件）。这些模式驱动**运行时验证**、**JSON Schema 导出**以及 macOS 应用的 **Swift 代码生成**。一个事实来源；其他一切都是生成的。
如果您想了解更高层次的协议上下文，请从 [Gateway 架构](/concepts/architecture) 开始。
## 心智模型（30 秒）
每条 Gateway WS 消息都是以下三种帧之一：
- **请求**：`{ type: "req", id, method, params }`
- **响应**：`{ type: "res", id, ok, payload | error }`
- **事件**：`{ type: "event", event, payload, seq?, stateVersion? }`
第一帧**必须**是 `connect` 请求。之后，客户端可以调用方法（如 `health`、`send`、`chat.send`）并订阅事件（如 `presence`、`tick`、`agent`）。
连接流程（最简）：
```
Client Gateway
|---- req:connect -------->|
|<---- res:hello-ok --------|
|<---- event:tick ----------|
|---- req:health ---------->|
|<---- res:health ----------|
```
常见方法 + 事件：
| 类别 | 示例 | 备注 |
| ---- | --------------------------------------------------------- | ----------------------------------- |
| 核心 | `connect`、`health`、`status` | `connect` 必须在首位 |
| 消息 | `send`、`poll`、`agent`、`agent.wait` | 有副作用的操作需要 `idempotencyKey` |
| 聊天 | `chat.history`、`chat.send`、`chat.abort`、`chat.inject` | WebChat 使用这些 |
| 会话 | `sessions.list`、`sessions.patch`、`sessions.delete` | 会话管理 |
| 节点 | `node.list`、`node.invoke`、`node.pair.*` | Gateway WS + 节点操作 |
| 事件 | `tick`、`presence`、`agent`、`chat`、`health`、`shutdown` | 服务器推送 |
权威列表位于 `src/gateway/server.ts`（`METHODS`、`EVENTS`）。
## 模式文件位置
- 源文件：`src/gateway/protocol/schema.ts`
- 运行时验证器（AJV）：`src/gateway/protocol/index.ts`
- 服务器握手 + 方法分发：`src/gateway/server.ts`
- 节点客户端：`src/gateway/client.ts`
- 生成的 JSON Schema：`dist/protocol.schema.json`
- 生成的 Swift 模型：`apps/macos/Sources/OpenClawProtocol/GatewayModels.swift`
## 当前流水线
- `pnpm protocol:gen`
- 将 JSON Schema（draft‑07）写入 `dist/protocol.schema.json`
- `pnpm protocol:gen:swift`
- 生成 Swift Gateway 模型
- `pnpm protocol:check`
- 运行两个生成器并验证输出已提交
## 模式在运行时的使用方式
- **服务器端**：每个入站帧都通过 AJV 验证。握手仅接受参数匹配 `ConnectParams` 的 `connect` 请求。
- **客户端**：JS 客户端在使用事件和响应帧之前进行验证。
- **方法接口**：Gateway 在 `hello-ok` 中公布支持的 `methods` 和 `events`。
## 示例帧
连接（第一条消息）：
```json
{
"type": "req",
"id": "c1",
"method": "connect",
"params": {
"minProtocol": 2,
"maxProtocol": 2,
"client": {
"id": "openclaw-macos",
"displayName": "macos",
"version": "1.0.0",
"platform": "macos 15.1",
"mode": "ui",
"instanceId": "A1B2"
}
}
}
```
Hello-ok 响应：
```json
{
"type": "res",
"id": "c1",
"ok": true,
"payload": {
"type": "hello-ok",
"protocol": 2,
"server": { "version": "dev", "connId": "ws-1" },
"features": { "methods": ["health"], "events": ["tick"] },
"snapshot": {
"presence": [],
"health": {},
"stateVersion": { "presence": 0, "health": 0 },
"uptimeMs": 0
},
"policy": { "maxPayload": 1048576, "maxBufferedBytes": 1048576, "tickIntervalMs": 30000 }
}
}
```
请求 + 响应：
```json
{ "type": "req", "id": "r1", "method": "health" }
```
```json
{ "type": "res", "id": "r1", "ok": true, "payload": { "ok": true } }
```
事件：
```json
{ "type": "event", "event": "tick", "payload": { "ts": 1730000000 }, "seq": 12 }
```
## 最小客户端（Node.js）
最小可用流程：连接 + 健康检查。
```ts
import { WebSocket } from "ws";
const ws = new WebSocket("ws://127.0.0.1:18789");
ws.on("open", () => {
ws.send(
JSON.stringify({
type: "req",
id: "c1",
method: "connect",
params: {
minProtocol: 3,
maxProtocol: 3,
client: {
id: "cli",
displayName: "example",
version: "dev",
platform: "node",
mode: "cli",
},
},
}),
);
});
ws.on("message", (data) => {
const msg = JSON.parse(String(data));
if (msg.type === "res" && msg.id === "c1" && msg.ok) {
ws.send(JSON.stringify({ type: "req", id: "h1", method: "health" }));
}
if (msg.type === "res" && msg.id === "h1") {
console.log("health:", msg.payload);
ws.close();
}
});
```
## 实战示例：端到端添加一个方法
示例：添加一个新的 `system.echo` 请求，返回 `{ ok: true, text }`。
1. **模式（事实来源）**
添加到 `src/gateway/protocol/schema.ts`：
```ts
export const SystemEchoParamsSchema = Type.Object(
{ text: NonEmptyString },
{ additionalProperties: false },
);
export const SystemEchoResultSchema = Type.Object(
{ ok: Type.Boolean(), text: NonEmptyString },
{ additionalProperties: false },
);
```
将两者添加到 `ProtocolSchemas` 并导出类型：
```ts
SystemEchoParams: SystemEchoParamsSchema,
SystemEchoResult: SystemEchoResultSchema,
```
```ts
export type SystemEchoParams = Static<typeof SystemEchoParamsSchema>;
export type SystemEchoResult = Static<typeof SystemEchoResultSchema>;
```
2. **验证**
在 `src/gateway/protocol/index.ts` 中导出 AJV 验证器：
```ts
export const validateSystemEchoParams = ajv.compile<SystemEchoParams>(SystemEchoParamsSchema);
```
3. **服务器行为**
在 `src/gateway/server-methods/system.ts` 中添加处理器：
```ts
export const systemHandlers: GatewayRequestHandlers = {
"system.echo": ({ params, respond }) => {
const text = String(params.text ?? "");
respond(true, { ok: true, text });
},
};
```
在 `src/gateway/server-methods.ts` 中注册（已合并 `systemHandlers`），然后将 `"system.echo"` 添加到 `src/gateway/server.ts` 的 `METHODS` 中。
4. **重新生成**
```bash
pnpm protocol:check
```
5. **测试 + 文档**
在 `src/gateway/server.*.test.ts` 中添加服务器测试，并在文档中记录该方法。
## Swift 代码生成行为
Swift 生成器输出：
- 包含 `req`、`res`、`event` 和 `unknown` case 的 `GatewayFrame` 枚举
- 强类型的 payload 结构体/枚举
- `ErrorCode` 值和 `GATEWAY_PROTOCOL_VERSION`
未知帧类型保留为原始 payload 以实现前向兼容。
## 版本控制 + 兼容性
- `PROTOCOL_VERSION` 位于 `src/gateway/protocol/schema.ts`。
- 客户端发送 `minProtocol` + `maxProtocol`；服务器拒绝不匹配的版本。
- Swift 模型保留未知帧类型以避免破坏旧客户端。
## 模式规范和约定
- 大多数对象使用 `additionalProperties: false` 以实现严格的 payload。
- `NonEmptyString` 是 ID 和方法/事件名称的默认类型。
- 顶层 `GatewayFrame` 在 `type` 上使用**鉴别器**。
- 有副作用的方法通常需要在参数中包含 `idempotencyKey`（示例：`send`、`poll`、`agent`、`chat.send`）。
## 实时 Schema JSON
生成的 JSON Schema 位于仓库的 `dist/protocol.schema.json`。已发布的原始文件通常可在以下位置获取：
- https://raw.githubusercontent.com/openclaw/openclaw/main/dist/protocol.schema.json
## 当您更改模式时
1. 更新 TypeBox 模式。
2. 运行 `pnpm protocol:check`。
3. 提交重新生成的 schema + Swift 模型。

Some files were not shown because too many files have changed in this diff Show More