first commit
This commit is contained in:
120
content/nodes/audio.md
Normal file
120
content/nodes/audio.md
Normal file
@@ -0,0 +1,120 @@
|
||||
---
|
||||
read_when:
|
||||
- 更改音频转录或媒体处理方式
|
||||
summary: 入站音频/语音消息如何被下载、转录并注入回复
|
||||
title: 音频与语音消息
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:17:35Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: b926c47989ab0d1ee1fb8ae6372c51d27515b53d6fefe211a85856d372f14569
|
||||
source_path: nodes/audio.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 音频 / 语音消息 — 2026-01-17
|
||||
|
||||
## 已支持的功能
|
||||
|
||||
- **媒体理解（音频）**：如果音频理解已启用（或自动检测），OpenClaw 会：
|
||||
1. 找到第一个音频附件（本地路径或 URL），如有需要则下载。
|
||||
2. 在发送给每个模型条目之前执行 `maxBytes` 限制。
|
||||
3. 按顺序运行第一个符合条件的模型条目（提供商或 CLI）。
|
||||
4. 如果失败或跳过（大小/超时），则尝试下一个条目。
|
||||
5. 成功后，将 `Body` 替换为 `[Audio]` 块并设置 `{{Transcript}}`。
|
||||
- **命令解析**：转录成功时，`CommandBody`/`RawBody` 会设置为转录文本，因此斜杠命令仍然有效。
|
||||
- **详细日志**：在 `--verbose` 模式下，我们会在转录运行和替换正文时记录日志。
|
||||
|
||||
## 自动检测（默认）
|
||||
|
||||
如果你**未配置模型**且 `tools.media.audio.enabled` **未**设置为 `false`，OpenClaw 会按以下顺序自动检测，并在找到第一个可用选项时停止：
|
||||
|
||||
1. **本地 CLI**（如已安装）
|
||||
- `sherpa-onnx-offline`（需要 `SHERPA_ONNX_MODEL_DIR` 包含 encoder/decoder/joiner/tokens）
|
||||
- `whisper-cli`（来自 `whisper-cpp`；使用 `WHISPER_CPP_MODEL` 或内置的 tiny 模型）
|
||||
- `whisper`（Python CLI；自动下载模型）
|
||||
2. **Gemini CLI**（`gemini`）使用 `read_many_files`
|
||||
3. **提供商密钥**（OpenAI → Groq → Deepgram → Google）
|
||||
|
||||
要禁用自动检测，请设置 `tools.media.audio.enabled: false`。
|
||||
要自定义，请设置 `tools.media.audio.models`。
|
||||
注意：二进制检测在 macOS/Linux/Windows 上采用尽力而为的方式；请确保 CLI 在 `PATH` 中（我们会展开 `~`），或通过完整命令路径设置显式 CLI 模型。
|
||||
|
||||
## 配置示例
|
||||
|
||||
### 提供商 + CLI 回退（OpenAI + Whisper CLI）
|
||||
|
||||
```json5
|
||||
{
|
||||
tools: {
|
||||
media: {
|
||||
audio: {
|
||||
enabled: true,
|
||||
maxBytes: 20971520,
|
||||
models: [
|
||||
{ provider: "openai", model: "gpt-4o-mini-transcribe" },
|
||||
{
|
||||
type: "cli",
|
||||
command: "whisper",
|
||||
args: ["--model", "base", "{{MediaPath}}"],
|
||||
timeoutSeconds: 45,
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### 仅提供商 + 作用域控制
|
||||
|
||||
```json5
|
||||
{
|
||||
tools: {
|
||||
media: {
|
||||
audio: {
|
||||
enabled: true,
|
||||
scope: {
|
||||
default: "allow",
|
||||
rules: [{ action: "deny", match: { chatType: "group" } }],
|
||||
},
|
||||
models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### 仅提供商（Deepgram）
|
||||
|
||||
```json5
|
||||
{
|
||||
tools: {
|
||||
media: {
|
||||
audio: {
|
||||
enabled: true,
|
||||
models: [{ provider: "deepgram", model: "nova-3" }],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## 注意事项与限制
|
||||
|
||||
- 提供商认证遵循标准的模型认证顺序（认证配置文件、环境变量、`models.providers.*.apiKey`）。
|
||||
- 当使用 `provider: "deepgram"` 时，Deepgram 会读取 `DEEPGRAM_API_KEY`。
|
||||
- Deepgram 设置详情：[Deepgram（音频转录）](/providers/deepgram)。
|
||||
- 音频提供商可以通过 `tools.media.audio` 覆盖 `baseUrl`、`headers` 和 `providerOptions`。
|
||||
- 默认大小限制为 20MB（`tools.media.audio.maxBytes`）。超大音频会跳过该模型并尝试下一个条目。
|
||||
- 音频的默认 `maxChars` **未设置**（完整转录文本）。设置 `tools.media.audio.maxChars` 或每个条目的 `maxChars` 来裁剪输出。
|
||||
- OpenAI 自动检测默认使用 `gpt-4o-mini-transcribe`；设置 `model: "gpt-4o-transcribe"` 可获得更高准确度。
|
||||
- 使用 `tools.media.audio.attachments` 处理多条语音消息（`mode: "all"` + `maxAttachments`）。
|
||||
- 转录文本可在模板中通过 `{{Transcript}}` 使用。
|
||||
- CLI 标准输出有上限（5MB）；请保持 CLI 输出简洁。
|
||||
|
||||
## 常见陷阱
|
||||
|
||||
- 作用域规则采用首次匹配优先。`chatType` 会被规范化为 `direct`、`group` 或 `room`。
|
||||
- 确保你的 CLI 以退出码 0 退出并输出纯文本；JSON 格式需要通过 `jq -r .text` 进行转换。
|
||||
- 保持合理的超时时间（`timeoutSeconds`，默认 60 秒），以避免阻塞回复队列。
|
||||
162
content/nodes/camera.md
Normal file
162
content/nodes/camera.md
Normal file
@@ -0,0 +1,162 @@
|
||||
---
|
||||
read_when:
|
||||
- 在 iOS 节点或 macOS 上添加或修改相机捕获
|
||||
- 扩展智能体可访问的 MEDIA 临时文件工作流
|
||||
summary: 用于智能体的相机捕获（iOS 节点 + macOS 应用）：照片（jpg）和短视频片段（mp4）
|
||||
title: 相机捕获
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:50:55Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: b4d5f5ecbab6f70597cf1e1f9cc5f7f54681253bd747442db16cc681203b5813
|
||||
source_path: nodes/camera.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 相机捕获（智能体）
|
||||
|
||||
OpenClaw 支持用于智能体工作流的**相机捕获**：
|
||||
|
||||
- **iOS 节点**（通过 Gateway 网关配对）：通过 `node.invoke` 捕获**照片**（`jpg`）或**短视频片段**（`mp4`，可选音频）。
|
||||
- **Android 节点**（通过 Gateway 网关配对）：通过 `node.invoke` 捕获**照片**（`jpg`）或**短视频片段**（`mp4`，可选音频）。
|
||||
- **macOS 应用**（通过 Gateway 网关的节点）：通过 `node.invoke` 捕获**照片**（`jpg`）或**短视频片段**（`mp4`，可选音频）。
|
||||
|
||||
所有相机访问都受**用户控制的设置**限制。
|
||||
|
||||
## iOS 节点
|
||||
|
||||
### 用户设置（默认开启）
|
||||
|
||||
- iOS 设置标签页 → **相机** → **允许相机**（`camera.enabled`）
|
||||
- 默认：**开启**（缺少键时视为启用）。
|
||||
- 关闭时：`camera.*` 命令返回 `CAMERA_DISABLED`。
|
||||
|
||||
### 命令（通过 Gateway 网关 `node.invoke`）
|
||||
|
||||
- `camera.list`
|
||||
- 响应载荷：
|
||||
- `devices`：`{ id, name, position, deviceType }` 数组
|
||||
|
||||
- `camera.snap`
|
||||
- 参数：
|
||||
- `facing`：`front|back`（默认：`front`）
|
||||
- `maxWidth`：数字（可选；iOS 节点默认 `1600`）
|
||||
- `quality`：`0..1`（可选；默认 `0.9`）
|
||||
- `format`：当前为 `jpg`
|
||||
- `delayMs`：数字（可选；默认 `0`）
|
||||
- `deviceId`：字符串（可选；来自 `camera.list`）
|
||||
- 响应载荷：
|
||||
- `format: "jpg"`
|
||||
- `base64: "<...>"`
|
||||
- `width`、`height`
|
||||
- 载荷保护：照片会重新压缩以保持 base64 载荷小于 5 MB。
|
||||
|
||||
- `camera.clip`
|
||||
- 参数：
|
||||
- `facing`：`front|back`（默认：`front`）
|
||||
- `durationMs`：数字（默认 `3000`，上限 `60000`）
|
||||
- `includeAudio`：布尔值（默认 `true`）
|
||||
- `format`：当前为 `mp4`
|
||||
- `deviceId`：字符串（可选；来自 `camera.list`）
|
||||
- 响应载荷：
|
||||
- `format: "mp4"`
|
||||
- `base64: "<...>"`
|
||||
- `durationMs`
|
||||
- `hasAudio`
|
||||
|
||||
### 前台要求
|
||||
|
||||
与 `canvas.*` 类似，iOS 节点仅允许在**前台**执行 `camera.*` 命令。后台调用返回 `NODE_BACKGROUND_UNAVAILABLE`。
|
||||
|
||||
### CLI 辅助工具（临时文件 + MEDIA）
|
||||
|
||||
获取附件最简单的方法是通过 CLI 辅助工具，它将解码的媒体写入临时文件并打印 `MEDIA:<path>`。
|
||||
|
||||
示例：
|
||||
|
||||
```bash
|
||||
openclaw nodes camera snap --node <id> # default: both front + back (2 MEDIA lines)
|
||||
openclaw nodes camera snap --node <id> --facing front
|
||||
openclaw nodes camera clip --node <id> --duration 3000
|
||||
openclaw nodes camera clip --node <id> --no-audio
|
||||
```
|
||||
|
||||
注意事项：
|
||||
|
||||
- `nodes camera snap` 默认拍摄**两个**方向以给智能体提供两个视角。
|
||||
- 输出文件是临时的（在操作系统临时目录中），除非你构建自己的包装器。
|
||||
|
||||
## Android 节点
|
||||
|
||||
### 用户设置（默认开启）
|
||||
|
||||
- Android 设置页 → **相机** → **允许相机**（`camera.enabled`）
|
||||
- 默认：**开启**（缺少键时视为启用）。
|
||||
- 关闭时：`camera.*` 命令返回 `CAMERA_DISABLED`。
|
||||
|
||||
### 权限
|
||||
|
||||
- Android 需要运行时权限：
|
||||
- `CAMERA` 用于 `camera.snap` 和 `camera.clip`。
|
||||
- `RECORD_AUDIO` 用于 `includeAudio=true` 时的 `camera.clip`。
|
||||
|
||||
如果缺少权限，应用会在可能时提示；如果被拒绝，`camera.*` 请求会失败并返回 `*_PERMISSION_REQUIRED` 错误。
|
||||
|
||||
### 前台要求
|
||||
|
||||
与 `canvas.*` 类似，Android 节点仅允许在**前台**执行 `camera.*` 命令。后台调用返回 `NODE_BACKGROUND_UNAVAILABLE`。
|
||||
|
||||
### 载荷保护
|
||||
|
||||
照片会重新压缩以保持 base64 载荷小于 5 MB。
|
||||
|
||||
## macOS 应用
|
||||
|
||||
### 用户设置（默认关闭）
|
||||
|
||||
macOS 配套应用暴露一个复选框：
|
||||
|
||||
- **设置 → 通用 → 允许相机**（`openclaw.cameraEnabled`）
|
||||
- 默认：**关闭**
|
||||
- 关闭时：相机请求返回"用户已禁用相机"。
|
||||
|
||||
### CLI 辅助工具（节点调用）
|
||||
|
||||
使用主 `openclaw` CLI 在 macOS 节点上调用相机命令。
|
||||
|
||||
示例：
|
||||
|
||||
```bash
|
||||
openclaw nodes camera list --node <id> # list camera ids
|
||||
openclaw nodes camera snap --node <id> # prints MEDIA:<path>
|
||||
openclaw nodes camera snap --node <id> --max-width 1280
|
||||
openclaw nodes camera snap --node <id> --delay-ms 2000
|
||||
openclaw nodes camera snap --node <id> --device-id <id>
|
||||
openclaw nodes camera clip --node <id> --duration 10s # prints MEDIA:<path>
|
||||
openclaw nodes camera clip --node <id> --duration-ms 3000 # prints MEDIA:<path> (legacy flag)
|
||||
openclaw nodes camera clip --node <id> --device-id <id>
|
||||
openclaw nodes camera clip --node <id> --no-audio
|
||||
```
|
||||
|
||||
注意事项：
|
||||
|
||||
- `openclaw nodes camera snap` 默认 `maxWidth=1600`，除非被覆盖。
|
||||
- 在 macOS 上，`camera.snap` 在预热/曝光稳定后等待 `delayMs`（默认 2000ms）再捕获。
|
||||
- 照片载荷会重新压缩以保持 base64 小于 5 MB。
|
||||
|
||||
## 安全性 + 实际限制
|
||||
|
||||
- 相机和麦克风访问会触发通常的操作系统权限提示（并需要 Info.plist 中的使用说明字符串）。
|
||||
- 视频片段有上限（当前 `<= 60s`）以避免过大的节点载荷（base64 开销 + 消息限制）。
|
||||
|
||||
## macOS 屏幕视频（操作系统级别）
|
||||
|
||||
对于*屏幕*视频（非相机），使用 macOS 配套应用：
|
||||
|
||||
```bash
|
||||
openclaw nodes screen record --node <id> --duration 10s --fps 15 # prints MEDIA:<path>
|
||||
```
|
||||
|
||||
注意事项：
|
||||
|
||||
- 需要 macOS **屏幕录制**权限（TCC）。
|
||||
79
content/nodes/images.md
Normal file
79
content/nodes/images.md
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
read_when:
|
||||
- 修改媒体管道或附件
|
||||
summary: 发送、Gateway 网关和智能体回复的图像和媒体处理规则
|
||||
title: 图像和媒体支持
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:50:42Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 971aed398ea01078efbad7a8a4bca17f2a975222a2c4db557565e4334c9450e0
|
||||
source_path: nodes/images.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 图像与媒体支持 — 2025-12-05
|
||||
|
||||
WhatsApp 渠道通过 **Baileys Web** 运行。本文档记录了发送、Gateway 网关和智能体回复的当前媒体处理规则。
|
||||
|
||||
## 目标
|
||||
|
||||
- 通过 `openclaw message send --media` 发送带可选标题的媒体。
|
||||
- 允许来自网页收件箱的自动回复在文本旁边包含媒体。
|
||||
- 保持每种类型的限制合理且可预测。
|
||||
|
||||
## CLI 接口
|
||||
|
||||
- `openclaw message send --media <path-or-url> [--message <caption>]`
|
||||
- `--media` 可选；标题可以为空以进行纯媒体发送。
|
||||
- `--dry-run` 打印解析后的负载；`--json` 输出 `{ channel, to, messageId, mediaUrl, caption }`。
|
||||
|
||||
## WhatsApp Web 渠道行为
|
||||
|
||||
- 输入：本地文件路径**或** HTTP(S) URL。
|
||||
- 流程：加载到 Buffer，检测媒体类型，并构建正确的负载：
|
||||
- **图像：** 调整大小并重新压缩为 JPEG（最大边 2048px），目标为 `agents.defaults.mediaMaxMb`（默认 5 MB），上限 6 MB。
|
||||
- **音频/语音/视频：** 直通最大 16 MB；音频作为语音消息发送（`ptt: true`）。
|
||||
- **文档：** 其他任何内容，最大 100 MB，可用时保留文件名。
|
||||
- WhatsApp GIF 风格播放：发送带 `gifPlayback: true` 的 MP4（CLI：`--gif-playback`），使移动客户端内联循环播放。
|
||||
- MIME 检测优先使用魔数字节，然后是头信息，最后是文件扩展名。
|
||||
- 标题来自 `--message` 或 `reply.text`；允许空标题。
|
||||
- 日志：非详细模式显示 `↩️`/`✅`；详细模式包含大小和源路径/URL。
|
||||
|
||||
## 自动回复管道
|
||||
|
||||
- `getReplyFromConfig` 返回 `{ text?, mediaUrl?, mediaUrls? }`。
|
||||
- 当存在媒体时，网页发送器使用与 `openclaw message send` 相同的管道解析本地路径或 URL。
|
||||
- 如果提供多个媒体条目，则按顺序发送。
|
||||
|
||||
## 入站媒体到命令（Pi）
|
||||
|
||||
- 当入站网页消息包含媒体时，OpenClaw 下载到临时文件并暴露模板变量：
|
||||
- `{{MediaUrl}}` 入站媒体的伪 URL。
|
||||
- `{{MediaPath}}` 运行命令前写入的本地临时路径。
|
||||
- 当启用每会话 Docker 沙箱时，入站媒体被复制到沙箱工作区，`MediaPath`/`MediaUrl` 被重写为相对路径如 `media/inbound/<filename>`。
|
||||
- 媒体理解（如果通过 `tools.media.*` 或共享的 `tools.media.models` 配置）在模板化之前运行，可以将 `[Image]`、`[Audio]` 和 `[Video]` 块插入 `Body`。
|
||||
- 音频设置 `{{Transcript}}` 并使用转录进行命令解析，因此斜杠命令仍然有效。
|
||||
- 视频和图像描述保留任何标题文本用于命令解析。
|
||||
- 默认情况下只处理第一个匹配的图像/音频/视频附件；设置 `tools.media.<cap>.attachments` 以处理多个附件。
|
||||
|
||||
## 限制与错误
|
||||
|
||||
**出站发送上限（WhatsApp 网页发送）**
|
||||
|
||||
- 图像：重新压缩后约 6 MB 上限。
|
||||
- 音频/语音/视频：16 MB 上限；文档：100 MB 上限。
|
||||
- 超大或无法读取的媒体 → 日志中有明确错误，回复被跳过。
|
||||
|
||||
**媒体理解上限（转录/描述）**
|
||||
|
||||
- 图像默认：10 MB（`tools.media.image.maxBytes`）。
|
||||
- 音频默认：20 MB（`tools.media.audio.maxBytes`）。
|
||||
- 视频默认：50 MB（`tools.media.video.maxBytes`）。
|
||||
- 超大媒体跳过理解，但回复仍然使用原始正文通过。
|
||||
|
||||
## 测试说明
|
||||
|
||||
- 覆盖图像/音频/文档情况的发送 + 回复流程。
|
||||
- 验证图像的重新压缩（大小限制）和音频的语音消息标志。
|
||||
- 确保多媒体回复作为顺序发送扇出。
|
||||
348
content/nodes/index.md
Normal file
348
content/nodes/index.md
Normal file
@@ -0,0 +1,348 @@
|
||||
---
|
||||
read_when:
|
||||
- 将 iOS/Android 节点配对到 Gateway 网关时
|
||||
- 使用节点 canvas/camera 为智能体提供上下文时
|
||||
- 添加新的节点命令或 CLI 辅助工具时
|
||||
summary: 节点：配对、能力、权限以及 canvas/camera/screen/system 的 CLI 辅助工具
|
||||
title: 节点
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:51:55Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 74e9420f61c653e4ceeb00f5a27e4266bd1c7715c1000edd969c3ee185e74de9
|
||||
source_path: nodes/index.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 节点
|
||||
|
||||
**节点**是一个配套设备（macOS/iOS/Android/无头），它以 `role: "node"` 连接到 Gateway 网关 **WebSocket**（与操作员相同的端口），并通过 `node.invoke` 暴露命令接口（例如 `canvas.*`、`camera.*`、`system.*`）。协议详情：[Gateway 网关协议](/gateway/protocol)。
|
||||
|
||||
旧版传输：[Bridge 协议](/gateway/bridge-protocol)（TCP JSONL；当前节点已弃用/移除）。
|
||||
|
||||
macOS 也可以在**节点模式**下运行：菜单栏应用连接到 Gateway 网关的 WS 服务器，并将其本地 canvas/camera 命令作为节点暴露（因此 `openclaw nodes …` 可以针对这台 Mac 工作）。
|
||||
|
||||
注意事项：
|
||||
|
||||
- 节点是**外围设备**，不是 Gateway 网关。它们不运行 Gateway 网关服务。
|
||||
- Telegram/WhatsApp 等消息落在 **Gateway 网关**上，而不是节点上。
|
||||
|
||||
## 配对 + 状态
|
||||
|
||||
**WS 节点使用设备配对。** 节点在 `connect` 期间呈现设备身份；Gateway 网关
|
||||
为 `role: node` 创建设备配对请求。通过设备 CLI（或 UI）批准。
|
||||
|
||||
快速 CLI：
|
||||
|
||||
```bash
|
||||
openclaw devices list
|
||||
openclaw devices approve <requestId>
|
||||
openclaw devices reject <requestId>
|
||||
openclaw nodes status
|
||||
openclaw nodes describe --node <idOrNameOrIp>
|
||||
```
|
||||
|
||||
注意事项：
|
||||
|
||||
- 当节点的设备配对角色包含 `node` 时，`nodes status` 将节点标记为**已配对**。
|
||||
- `node.pair.*`（CLI：`openclaw nodes pending/approve/reject`）是一个单独的 Gateway 网关拥有的
|
||||
节点配对存储；它**不会**限制 WS `connect` 握手。
|
||||
|
||||
## 远程节点主机（system.run）
|
||||
|
||||
当你的 Gateway 网关在一台机器上运行而你希望命令
|
||||
在另一台机器上执行时，使用**节点主机**。模型仍然与 **Gateway 网关**通信；当选择 `host=node` 时，Gateway 网关
|
||||
将 `exec` 调用转发到**节点主机**。
|
||||
|
||||
### 什么在哪里运行
|
||||
|
||||
- **Gateway 网关主机**：接收消息，运行模型，路由工具调用。
|
||||
- **节点主机**：在节点机器上执行 `system.run`/`system.which`。
|
||||
- **批准**：通过 `~/.openclaw/exec-approvals.json` 在节点主机上执行。
|
||||
|
||||
### 启动节点主机（前台）
|
||||
|
||||
在节点机器上：
|
||||
|
||||
```bash
|
||||
openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"
|
||||
```
|
||||
|
||||
### 通过 SSH 隧道访问远程 Gateway 网关（loopback 绑定）
|
||||
|
||||
如果 Gateway 网关绑定到 loopback（`gateway.bind=loopback`，本地模式下的默认值），
|
||||
远程节点主机无法直接连接。创建 SSH 隧道并将
|
||||
节点主机指向隧道的本地端。
|
||||
|
||||
示例（节点主机 -> Gateway 网关主机）：
|
||||
|
||||
```bash
|
||||
# 终端 A（保持运行）：转发本地 18790 -> Gateway 网关 127.0.0.1:18789
|
||||
ssh -N -L 18790:127.0.0.1:18789 user@gateway-host
|
||||
|
||||
# 终端 B：导出 Gateway 网关令牌并通过隧道连接
|
||||
export OPENCLAW_GATEWAY_TOKEN="<gateway-token>"
|
||||
openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node"
|
||||
```
|
||||
|
||||
注意事项：
|
||||
|
||||
- 令牌是 Gateway 网关配置中的 `gateway.auth.token`（Gateway 网关主机上的 `~/.openclaw/openclaw.json`）。
|
||||
- `openclaw node run` 读取 `OPENCLAW_GATEWAY_TOKEN` 进行认证。
|
||||
|
||||
### 启动节点主机（服务）
|
||||
|
||||
```bash
|
||||
openclaw node install --host <gateway-host> --port 18789 --display-name "Build Node"
|
||||
openclaw node restart
|
||||
```
|
||||
|
||||
### 配对 + 命名
|
||||
|
||||
在 Gateway 网关主机上：
|
||||
|
||||
```bash
|
||||
openclaw nodes pending
|
||||
openclaw nodes approve <requestId>
|
||||
openclaw nodes list
|
||||
```
|
||||
|
||||
命名选项：
|
||||
|
||||
- 在 `openclaw node run` / `openclaw node install` 上使用 `--display-name`（持久化在节点上的 `~/.openclaw/node.json` 中）。
|
||||
- `openclaw nodes rename --node <id|name|ip> --name "Build Node"`（Gateway 网关覆盖）。
|
||||
|
||||
### 将命令加入允许列表
|
||||
|
||||
Exec 批准是**每个节点主机**的。从 Gateway 网关添加允许列表条目：
|
||||
|
||||
```bash
|
||||
openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/uname"
|
||||
openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/sw_vers"
|
||||
```
|
||||
|
||||
批准存储在节点主机的 `~/.openclaw/exec-approvals.json` 中。
|
||||
|
||||
### 将 exec 指向节点
|
||||
|
||||
配置默认值（Gateway 网关配置）：
|
||||
|
||||
```bash
|
||||
openclaw config set tools.exec.host node
|
||||
openclaw config set tools.exec.security allowlist
|
||||
openclaw config set tools.exec.node "<id-or-name>"
|
||||
```
|
||||
|
||||
或按会话：
|
||||
|
||||
```
|
||||
/exec host=node security=allowlist node=<id-or-name>
|
||||
```
|
||||
|
||||
设置后，任何带有 `host=node` 的 `exec` 调用都会在节点主机上运行（受
|
||||
节点允许列表/批准约束）。
|
||||
|
||||
相关：
|
||||
|
||||
- [节点主机 CLI](/cli/node)
|
||||
- [Exec 工具](/tools/exec)
|
||||
- [Exec 批准](/tools/exec-approvals)
|
||||
|
||||
## 调用命令
|
||||
|
||||
低级（原始 RPC）：
|
||||
|
||||
```bash
|
||||
openclaw nodes invoke --node <idOrNameOrIp> --command canvas.eval --params '{"javaScript":"location.href"}'
|
||||
```
|
||||
|
||||
对于常见的"给智能体一个 MEDIA 附件"工作流，存在更高级的辅助工具。
|
||||
|
||||
## 截图（canvas 快照）
|
||||
|
||||
如果节点正在显示 Canvas（WebView），`canvas.snapshot` 返回 `{ format, base64 }`。
|
||||
|
||||
CLI 辅助工具（写入临时文件并打印 `MEDIA:<path>`）：
|
||||
|
||||
```bash
|
||||
openclaw nodes canvas snapshot --node <idOrNameOrIp> --format png
|
||||
openclaw nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9
|
||||
```
|
||||
|
||||
### Canvas 控制
|
||||
|
||||
```bash
|
||||
openclaw nodes canvas present --node <idOrNameOrIp> --target https://example.com
|
||||
openclaw nodes canvas hide --node <idOrNameOrIp>
|
||||
openclaw nodes canvas navigate https://example.com --node <idOrNameOrIp>
|
||||
openclaw nodes canvas eval --node <idOrNameOrIp> --js "document.title"
|
||||
```
|
||||
|
||||
注意事项：
|
||||
|
||||
- `canvas present` 接受 URL 或本地文件路径（`--target`），以及可选的 `--x/--y/--width/--height` 用于定位。
|
||||
- `canvas eval` 接受内联 JS（`--js`）或位置参数。
|
||||
|
||||
### A2UI（Canvas）
|
||||
|
||||
```bash
|
||||
openclaw nodes canvas a2ui push --node <idOrNameOrIp> --text "Hello"
|
||||
openclaw nodes canvas a2ui push --node <idOrNameOrIp> --jsonl ./payload.jsonl
|
||||
openclaw nodes canvas a2ui reset --node <idOrNameOrIp>
|
||||
```
|
||||
|
||||
注意事项：
|
||||
|
||||
- 仅支持 A2UI v0.8 JSONL（v0.9/createSurface 被拒绝）。
|
||||
|
||||
## 照片 + 视频（节点相机）
|
||||
|
||||
照片（`jpg`）：
|
||||
|
||||
```bash
|
||||
openclaw nodes camera list --node <idOrNameOrIp>
|
||||
openclaw nodes camera snap --node <idOrNameOrIp> # 默认：两个朝向（2 个 MEDIA 行）
|
||||
openclaw nodes camera snap --node <idOrNameOrIp> --facing front
|
||||
```
|
||||
|
||||
视频片段（`mp4`）：
|
||||
|
||||
```bash
|
||||
openclaw nodes camera clip --node <idOrNameOrIp> --duration 10s
|
||||
openclaw nodes camera clip --node <idOrNameOrIp> --duration 3000 --no-audio
|
||||
```
|
||||
|
||||
注意事项：
|
||||
|
||||
- 节点必须处于**前台**才能使用 `canvas.*` 和 `camera.*`（后台调用返回 `NODE_BACKGROUND_UNAVAILABLE`）。
|
||||
- 片段时长被限制（当前 `<= 60s`）以避免过大的 base64 负载。
|
||||
- Android 会在可能时提示 `CAMERA`/`RECORD_AUDIO` 权限；权限被拒绝会以 `*_PERMISSION_REQUIRED` 失败。
|
||||
|
||||
## 屏幕录制（节点）
|
||||
|
||||
节点暴露 `screen.record`（mp4）。示例：
|
||||
|
||||
```bash
|
||||
openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10
|
||||
openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-audio
|
||||
```
|
||||
|
||||
注意事项：
|
||||
|
||||
- `screen.record` 需要节点应用处于前台。
|
||||
- Android 会在录制前显示系统屏幕捕获提示。
|
||||
- 屏幕录制被限制为 `<= 60s`。
|
||||
- `--no-audio` 禁用麦克风捕获（iOS/Android 支持；macOS 使用系统捕获音频）。
|
||||
- 当有多个屏幕可用时，使用 `--screen <index>` 选择显示器。
|
||||
|
||||
## 位置（节点）
|
||||
|
||||
当在设置中启用位置时，节点暴露 `location.get`。
|
||||
|
||||
CLI 辅助工具：
|
||||
|
||||
```bash
|
||||
openclaw nodes location get --node <idOrNameOrIp>
|
||||
openclaw nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000
|
||||
```
|
||||
|
||||
注意事项：
|
||||
|
||||
- 位置**默认关闭**。
|
||||
- "始终"需要系统权限；后台获取是尽力而为的。
|
||||
- 响应包括纬度/经度、精度（米）和时间戳。
|
||||
|
||||
## 短信（Android 节点）
|
||||
|
||||
当用户授予 **SMS** 权限且设备支持电话功能时，Android 节点可以暴露 `sms.send`。
|
||||
|
||||
低级调用：
|
||||
|
||||
```bash
|
||||
openclaw nodes invoke --node <idOrNameOrIp> --command sms.send --params '{"to":"+15555550123","message":"Hello from OpenClaw"}'
|
||||
```
|
||||
|
||||
注意事项：
|
||||
|
||||
- 在能力被广播之前，必须在 Android 设备上接受权限提示。
|
||||
- 没有电话功能的纯 Wi-Fi 设备不会广播 `sms.send`。
|
||||
|
||||
## 系统命令（节点主机 / mac 节点）
|
||||
|
||||
macOS 节点暴露 `system.run`、`system.notify` 和 `system.execApprovals.get/set`。
|
||||
无头节点主机暴露 `system.run`、`system.which` 和 `system.execApprovals.get/set`。
|
||||
|
||||
示例：
|
||||
|
||||
```bash
|
||||
openclaw nodes run --node <idOrNameOrIp> -- echo "Hello from mac node"
|
||||
openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"
|
||||
```
|
||||
|
||||
注意事项：
|
||||
|
||||
- `system.run` 在负载中返回 stdout/stderr/退出码。
|
||||
- `system.notify` 遵守 macOS 应用上的通知权限状态。
|
||||
- `system.run` 支持 `--cwd`、`--env KEY=VAL`、`--command-timeout` 和 `--needs-screen-recording`。
|
||||
- `system.notify` 支持 `--priority <passive|active|timeSensitive>` 和 `--delivery <system|overlay|auto>`。
|
||||
- macOS 节点会丢弃 `PATH` 覆盖；无头节点主机仅在 `PATH` 前置到节点主机 PATH 时才接受它。
|
||||
- 在 macOS 节点模式下，`system.run` 受 macOS 应用中的 exec 批准限制（设置 → Exec 批准）。
|
||||
Ask/allowlist/full 的行为与无头节点主机相同；被拒绝的提示返回 `SYSTEM_RUN_DENIED`。
|
||||
- 在无头节点主机上，`system.run` 受 exec 批准限制（`~/.openclaw/exec-approvals.json`）。
|
||||
|
||||
## Exec 节点绑定
|
||||
|
||||
当有多个节点可用时，你可以将 exec 绑定到特定节点。
|
||||
这设置了 `exec host=node` 的默认节点（可以按智能体覆盖）。
|
||||
|
||||
全局默认：
|
||||
|
||||
```bash
|
||||
openclaw config set tools.exec.node "node-id-or-name"
|
||||
```
|
||||
|
||||
按智能体覆盖：
|
||||
|
||||
```bash
|
||||
openclaw config get agents.list
|
||||
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
|
||||
```
|
||||
|
||||
取消设置以允许任何节点：
|
||||
|
||||
```bash
|
||||
openclaw config unset tools.exec.node
|
||||
openclaw config unset agents.list[0].tools.exec.node
|
||||
```
|
||||
|
||||
## 权限映射
|
||||
|
||||
节点可能在 `node.list` / `node.describe` 中包含 `permissions` 映射，按权限名称（例如 `screenRecording`、`accessibility`）键入，值为布尔值（`true` = 已授予）。
|
||||
|
||||
## 无头节点主机（跨平台）
|
||||
|
||||
OpenClaw 可以运行**无头节点主机**（无 UI），它连接到 Gateway 网关
|
||||
WebSocket 并暴露 `system.run` / `system.which`。这在 Linux/Windows
|
||||
上或在服务器旁运行最小节点时很有用。
|
||||
|
||||
启动它：
|
||||
|
||||
```bash
|
||||
openclaw node run --host <gateway-host> --port 18789
|
||||
```
|
||||
|
||||
注意事项：
|
||||
|
||||
- 仍然需要配对（Gateway 网关会显示节点批准提示）。
|
||||
- 节点主机将其节点 id、令牌、显示名称和 Gateway 网关连接信息存储在 `~/.openclaw/node.json` 中。
|
||||
- Exec 批准通过 `~/.openclaw/exec-approvals.json` 在本地执行
|
||||
（参见 [Exec 批准](/tools/exec-approvals)）。
|
||||
- 在 macOS 上，当配套应用 exec 主机可达时，无头节点主机优先使用它，
|
||||
如果应用不可用则回退到本地执行。设置 `OPENCLAW_NODE_EXEC_HOST=app` 要求
|
||||
使用应用，或设置 `OPENCLAW_NODE_EXEC_FALLBACK=0` 禁用回退。
|
||||
- 当 Gateway 网关 WS 使用 TLS 时，添加 `--tls` / `--tls-fingerprint`。
|
||||
|
||||
## Mac 节点模式
|
||||
|
||||
- macOS 菜单栏应用作为节点连接到 Gateway 网关 WS 服务器（因此 `openclaw nodes …` 可以针对这台 Mac 工作）。
|
||||
- 在远程模式下，应用为 Gateway 网关端口打开 SSH 隧道并连接到 `localhost`。
|
||||
120
content/nodes/location-command.md
Normal file
120
content/nodes/location-command.md
Normal file
@@ -0,0 +1,120 @@
|
||||
---
|
||||
read_when:
|
||||
- 添加位置节点支持或权限 UI
|
||||
- 设计后台位置 + 推送流程
|
||||
summary: 节点的位置命令（location.get）、权限模式和后台行为
|
||||
title: 位置命令
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:50:59Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 23124096256384d2b28157352b072309c61c970a20e009aac5ce4a8250dc3764
|
||||
source_path: nodes/location-command.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 位置命令（节点）
|
||||
|
||||
## 简要概述
|
||||
|
||||
- `location.get` 是一个节点命令（通过 `node.invoke`）。
|
||||
- 默认关闭。
|
||||
- 设置使用选择器：关闭 / 使用时 / 始终。
|
||||
- 单独的开关：精确位置。
|
||||
|
||||
## 为什么用选择器（而不只是开关）
|
||||
|
||||
操作系统权限是多级的。我们可以在应用内暴露选择器，但操作系统仍然决定实际授权。
|
||||
|
||||
- iOS/macOS：用户可以在系统提示/设置中选择**使用时**或**始终**。应用可以请求升级，但操作系统可能要求进入设置。
|
||||
- Android：后台位置是单独的权限；在 Android 10+ 上通常需要进入设置流程。
|
||||
- 精确位置是单独的授权（iOS 14+ "精确"，Android "精细" vs "粗略"）。
|
||||
|
||||
UI 中的选择器驱动我们请求的模式；实际授权存在于操作系统设置中。
|
||||
|
||||
## 设置模型
|
||||
|
||||
每个节点设备：
|
||||
|
||||
- `location.enabledMode`：`off | whileUsing | always`
|
||||
- `location.preciseEnabled`：bool
|
||||
|
||||
UI 行为：
|
||||
|
||||
- 选择 `whileUsing` 请求前台权限。
|
||||
- 选择 `always` 首先确保 `whileUsing`，然后请求后台（或在需要时将用户引导到设置）。
|
||||
- 如果操作系统拒绝请求的级别，回退到已授予的最高级别并显示状态。
|
||||
|
||||
## 权限映射（node.permissions）
|
||||
|
||||
可选。macOS 节点通过权限映射报告 `location`；iOS/Android 可能省略它。
|
||||
|
||||
## 命令：`location.get`
|
||||
|
||||
通过 `node.invoke` 调用。
|
||||
|
||||
参数（建议）：
|
||||
|
||||
```json
|
||||
{
|
||||
"timeoutMs": 10000,
|
||||
"maxAgeMs": 15000,
|
||||
"desiredAccuracy": "coarse|balanced|precise"
|
||||
}
|
||||
```
|
||||
|
||||
响应负载：
|
||||
|
||||
```json
|
||||
{
|
||||
"lat": 48.20849,
|
||||
"lon": 16.37208,
|
||||
"accuracyMeters": 12.5,
|
||||
"altitudeMeters": 182.0,
|
||||
"speedMps": 0.0,
|
||||
"headingDeg": 270.0,
|
||||
"timestamp": "2026-01-03T12:34:56.000Z",
|
||||
"isPrecise": true,
|
||||
"source": "gps|wifi|cell|unknown"
|
||||
}
|
||||
```
|
||||
|
||||
错误（稳定代码）：
|
||||
|
||||
- `LOCATION_DISABLED`：选择器已关闭。
|
||||
- `LOCATION_PERMISSION_REQUIRED`：缺少请求模式的权限。
|
||||
- `LOCATION_BACKGROUND_UNAVAILABLE`：应用在后台但只允许使用时。
|
||||
- `LOCATION_TIMEOUT`：在时间内没有定位。
|
||||
- `LOCATION_UNAVAILABLE`：系统故障/没有提供商。
|
||||
|
||||
## 后台行为（未来）
|
||||
|
||||
目标：模型可以在节点处于后台时请求位置，但仅当：
|
||||
|
||||
- 用户选择了**始终**。
|
||||
- 操作系统授予后台位置权限。
|
||||
- 应用被允许在后台运行以获取位置（iOS 后台模式/Android 前台服务或特殊许可）。
|
||||
|
||||
推送触发流程（未来）：
|
||||
|
||||
1. Gateway 网关向节点发送推送（静默推送或 FCM 数据）。
|
||||
2. 节点短暂唤醒并从设备请求位置。
|
||||
3. 节点将负载转发给 Gateway 网关。
|
||||
|
||||
说明：
|
||||
|
||||
- iOS：需要始终权限 + 后台位置模式。静默推送可能被限流；预期会有间歇性失败。
|
||||
- Android：后台位置可能需要前台服务；否则预期会被拒绝。
|
||||
|
||||
## 模型/工具集成
|
||||
|
||||
- 工具接口：`nodes` 工具添加 `location_get` 操作（需要节点）。
|
||||
- CLI：`openclaw nodes location get --node <id>`。
|
||||
- 智能体指南：仅在用户启用位置并理解范围时调用。
|
||||
|
||||
## UX 文案（建议）
|
||||
|
||||
- 关闭："位置共享已禁用。"
|
||||
- 使用时："仅当 OpenClaw 打开时。"
|
||||
- 始终："允许后台位置。需要系统权限。"
|
||||
- 精确："使用精确 GPS 位置。关闭以共享大致位置。"
|
||||
380
content/nodes/media-understanding.md
Normal file
380
content/nodes/media-understanding.md
Normal file
@@ -0,0 +1,380 @@
|
||||
---
|
||||
read_when:
|
||||
- 设计或重构媒体理解
|
||||
- 调优入站音频/视频/图片预处理
|
||||
summary: 入站图片/音频/视频理解（可选），带提供商 + CLI 回退
|
||||
title: 媒体理解
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:51:40Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: f6c575662b7fcbf0b62c46e3fdfa4cdb7cfd455513097e4a2cdec8a34cbdbd48
|
||||
source_path: nodes/media-understanding.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 媒体理解（入站）— 2026-01-17
|
||||
|
||||
OpenClaw 可以在回复流程运行之前**摘要入站媒体**（图片/音频/视频）。它会自动检测本地工具或提供商密钥是否可用，并且可以禁用或自定义。如果理解关闭，模型仍然会像往常一样接收原始文件/URL。
|
||||
|
||||
## 目标
|
||||
|
||||
- 可选：将入站媒体预先消化为短文本，以便更快路由 + 更好的命令解析。
|
||||
- 保留原始媒体传递给模型（始终）。
|
||||
- 支持**提供商 API** 和 **CLI 回退**。
|
||||
- 允许多个模型并按顺序回退（错误/大小/超时）。
|
||||
|
||||
## 高层行为
|
||||
|
||||
1. 收集入站附件（`MediaPaths`、`MediaUrls`、`MediaTypes`）。
|
||||
2. 对于每个启用的能力（图片/音频/视频），根据策略选择附件（默认：**第一个**）。
|
||||
3. 选择第一个符合条件的模型条目（大小 + 能力 + 认证）。
|
||||
4. 如果模型失败或媒体太大，**回退到下一个条目**。
|
||||
5. 成功时：
|
||||
- `Body` 变为 `[Image]`、`[Audio]` 或 `[Video]` 块。
|
||||
- 音频设置 `{{Transcript}}`；命令解析在有标题文本时使用标题文本，否则使用转录。
|
||||
- 标题作为 `User text:` 保留在块内。
|
||||
|
||||
如果理解失败或被禁用，**回复流程继续**使用原始正文 + 附件。
|
||||
|
||||
## 配置概述
|
||||
|
||||
`tools.media` 支持**共享模型**加上每能力覆盖：
|
||||
|
||||
- `tools.media.models`：共享模型列表（使用 `capabilities` 来限定）。
|
||||
- `tools.media.image` / `tools.media.audio` / `tools.media.video`：
|
||||
- 默认值（`prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`）
|
||||
- 提供商覆盖（`baseUrl`、`headers`、`providerOptions`）
|
||||
- 通过 `tools.media.audio.providerOptions.deepgram` 配置 Deepgram 音频选项
|
||||
- 可选的**每能力 `models` 列表**（优先于共享模型）
|
||||
- `attachments` 策略（`mode`、`maxAttachments`、`prefer`）
|
||||
- `scope`（可选的按渠道/聊天类型/会话键限定）
|
||||
- `tools.media.concurrency`：最大并发能力运行数（默认 **2**）。
|
||||
|
||||
```json5
|
||||
{
|
||||
tools: {
|
||||
media: {
|
||||
models: [
|
||||
/* 共享列表 */
|
||||
],
|
||||
image: {
|
||||
/* 可选覆盖 */
|
||||
},
|
||||
audio: {
|
||||
/* 可选覆盖 */
|
||||
},
|
||||
video: {
|
||||
/* 可选覆盖 */
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### 模型条目
|
||||
|
||||
每个 `models[]` 条目可以是**提供商**或 **CLI**：
|
||||
|
||||
```json5
|
||||
{
|
||||
type: "provider", // 省略时默认
|
||||
provider: "openai",
|
||||
model: "gpt-5.2",
|
||||
prompt: "Describe the image in <= 500 chars.",
|
||||
maxChars: 500,
|
||||
maxBytes: 10485760,
|
||||
timeoutSeconds: 60,
|
||||
capabilities: ["image"], // 可选，用于多模态条目
|
||||
profile: "vision-profile",
|
||||
preferredProfile: "vision-fallback",
|
||||
}
|
||||
```
|
||||
|
||||
```json5
|
||||
{
|
||||
type: "cli",
|
||||
command: "gemini",
|
||||
args: [
|
||||
"-m",
|
||||
"gemini-3-flash",
|
||||
"--allowed-tools",
|
||||
"read_file",
|
||||
"Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
|
||||
],
|
||||
maxChars: 500,
|
||||
maxBytes: 52428800,
|
||||
timeoutSeconds: 120,
|
||||
capabilities: ["video", "image"],
|
||||
}
|
||||
```
|
||||
|
||||
CLI 模板还可以使用：
|
||||
|
||||
- `{{MediaDir}}`（包含媒体文件的目录）
|
||||
- `{{OutputDir}}`（为本次运行创建的临时目录）
|
||||
- `{{OutputBase}}`（临时文件基础路径，无扩展名）
|
||||
|
||||
## 默认值和限制
|
||||
|
||||
推荐默认值：
|
||||
|
||||
- `maxChars`：图片/视频为 **500**（简短，适合命令）
|
||||
- `maxChars`：音频**不设置**（完整转录，除非你设置限制）
|
||||
- `maxBytes`：
|
||||
- 图片：**10MB**
|
||||
- 音频：**20MB**
|
||||
- 视频：**50MB**
|
||||
|
||||
规则：
|
||||
|
||||
- 如果媒体超过 `maxBytes`，该模型被跳过，**尝试下一个模型**。
|
||||
- 如果模型返回超过 `maxChars`，输出被截断。
|
||||
- `prompt` 默认为简单的"Describe the {media}."加上 `maxChars` 指导（仅图片/视频）。
|
||||
- 如果 `<capability>.enabled: true` 但未配置模型，当提供商支持该能力时，OpenClaw 尝试**活动的回复模型**。
|
||||
|
||||
### 自动检测媒体理解（默认）
|
||||
|
||||
如果 `tools.media.<capability>.enabled` **未**设置为 `false` 且你没有配置模型，OpenClaw 按以下顺序自动检测并**在第一个可用选项处停止**：
|
||||
|
||||
1. **本地 CLI**（仅音频；如果已安装）
|
||||
- `sherpa-onnx-offline`（需要带有 encoder/decoder/joiner/tokens 的 `SHERPA_ONNX_MODEL_DIR`）
|
||||
- `whisper-cli`（`whisper-cpp`；使用 `WHISPER_CPP_MODEL` 或捆绑的 tiny 模型）
|
||||
- `whisper`（Python CLI；自动下载模型）
|
||||
2. **Gemini CLI**（`gemini`）使用 `read_many_files`
|
||||
3. **提供商密钥**
|
||||
- 音频：OpenAI → Groq → Deepgram → Google
|
||||
- 图片：OpenAI → Anthropic → Google → MiniMax
|
||||
- 视频：Google
|
||||
|
||||
要禁用自动检测，设置：
|
||||
|
||||
```json5
|
||||
{
|
||||
tools: {
|
||||
media: {
|
||||
audio: {
|
||||
enabled: false,
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
注意：二进制文件检测在 macOS/Linux/Windows 上是尽力而为的；确保 CLI 在 `PATH` 上（我们会展开 `~`），或设置带有完整命令路径的显式 CLI 模型。
|
||||
|
||||
## 能力（可选）
|
||||
|
||||
如果你设置了 `capabilities`，该条目仅对这些媒体类型运行。对于共享列表，OpenClaw 可以推断默认值：
|
||||
|
||||
- `openai`、`anthropic`、`minimax`：**图片**
|
||||
- `google`（Gemini API）：**图片 + 音频 + 视频**
|
||||
- `groq`：**音频**
|
||||
- `deepgram`：**音频**
|
||||
|
||||
对于 CLI 条目，**显式设置 `capabilities`** 以避免意外匹配。如果你省略 `capabilities`，该条目对它出现的列表都符合条件。
|
||||
|
||||
## 提供商支持矩阵（OpenClaw 集成）
|
||||
|
||||
| 能力 | 提供商集成 | 说明 |
|
||||
| ---- | ---------------------------------------------- | --------------------------------------- |
|
||||
| 图片 | OpenAI / Anthropic / Google / 其他通过 `pi-ai` | 注册表中任何支持图片的模型都可用。 |
|
||||
| 音频 | OpenAI、Groq、Deepgram、Google | 提供商转录（Whisper/Deepgram/Gemini）。 |
|
||||
| 视频 | Google（Gemini API） | 提供商视频理解。 |
|
||||
|
||||
## 推荐提供商
|
||||
|
||||
**图片**
|
||||
|
||||
- 如果支持图片，优先使用你的活动模型。
|
||||
- 良好的默认值：`openai/gpt-5.2`、`anthropic/claude-opus-4-5`、`google/gemini-3-pro-preview`。
|
||||
|
||||
**音频**
|
||||
|
||||
- `openai/gpt-4o-mini-transcribe`、`groq/whisper-large-v3-turbo` 或 `deepgram/nova-3`。
|
||||
- CLI 回退：`whisper-cli`（whisper-cpp）或 `whisper`。
|
||||
- Deepgram 设置：[Deepgram（音频转录）](/providers/deepgram)。
|
||||
|
||||
**视频**
|
||||
|
||||
- `google/gemini-3-flash-preview`（快速）、`google/gemini-3-pro-preview`（更丰富）。
|
||||
- CLI 回退：`gemini` CLI（支持对视频/音频使用 `read_file`）。
|
||||
|
||||
## 附件策略
|
||||
|
||||
每能力的 `attachments` 控制处理哪些附件：
|
||||
|
||||
- `mode`：`first`（默认）或 `all`
|
||||
- `maxAttachments`：限制处理数量（默认 **1**）
|
||||
- `prefer`：`first`、`last`、`path`、`url`
|
||||
|
||||
当 `mode: "all"` 时，输出标记为 `[Image 1/2]`、`[Audio 2/2]` 等。
|
||||
|
||||
## 配置示例
|
||||
|
||||
### 1) 共享模型列表 + 覆盖
|
||||
|
||||
```json5
|
||||
{
|
||||
tools: {
|
||||
media: {
|
||||
models: [
|
||||
{ provider: "openai", model: "gpt-5.2", capabilities: ["image"] },
|
||||
{
|
||||
provider: "google",
|
||||
model: "gemini-3-flash-preview",
|
||||
capabilities: ["image", "audio", "video"],
|
||||
},
|
||||
{
|
||||
type: "cli",
|
||||
command: "gemini",
|
||||
args: [
|
||||
"-m",
|
||||
"gemini-3-flash",
|
||||
"--allowed-tools",
|
||||
"read_file",
|
||||
"Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
|
||||
],
|
||||
capabilities: ["image", "video"],
|
||||
},
|
||||
],
|
||||
audio: {
|
||||
attachments: { mode: "all", maxAttachments: 2 },
|
||||
},
|
||||
video: {
|
||||
maxChars: 500,
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### 2) 仅音频 + 视频（图片关闭）
|
||||
|
||||
```json5
|
||||
{
|
||||
tools: {
|
||||
media: {
|
||||
audio: {
|
||||
enabled: true,
|
||||
models: [
|
||||
{ provider: "openai", model: "gpt-4o-mini-transcribe" },
|
||||
{
|
||||
type: "cli",
|
||||
command: "whisper",
|
||||
args: ["--model", "base", "{{MediaPath}}"],
|
||||
},
|
||||
],
|
||||
},
|
||||
video: {
|
||||
enabled: true,
|
||||
maxChars: 500,
|
||||
models: [
|
||||
{ provider: "google", model: "gemini-3-flash-preview" },
|
||||
{
|
||||
type: "cli",
|
||||
command: "gemini",
|
||||
args: [
|
||||
"-m",
|
||||
"gemini-3-flash",
|
||||
"--allowed-tools",
|
||||
"read_file",
|
||||
"Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### 3) 可选图片理解
|
||||
|
||||
```json5
|
||||
{
|
||||
tools: {
|
||||
media: {
|
||||
image: {
|
||||
enabled: true,
|
||||
maxBytes: 10485760,
|
||||
maxChars: 500,
|
||||
models: [
|
||||
{ provider: "openai", model: "gpt-5.2" },
|
||||
{ provider: "anthropic", model: "claude-opus-4-5" },
|
||||
{
|
||||
type: "cli",
|
||||
command: "gemini",
|
||||
args: [
|
||||
"-m",
|
||||
"gemini-3-flash",
|
||||
"--allowed-tools",
|
||||
"read_file",
|
||||
"Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### 4) 多模态单条目（显式能力）
|
||||
|
||||
```json5
|
||||
{
|
||||
tools: {
|
||||
media: {
|
||||
image: {
|
||||
models: [
|
||||
{
|
||||
provider: "google",
|
||||
model: "gemini-3-pro-preview",
|
||||
capabilities: ["image", "video", "audio"],
|
||||
},
|
||||
],
|
||||
},
|
||||
audio: {
|
||||
models: [
|
||||
{
|
||||
provider: "google",
|
||||
model: "gemini-3-pro-preview",
|
||||
capabilities: ["image", "video", "audio"],
|
||||
},
|
||||
],
|
||||
},
|
||||
video: {
|
||||
models: [
|
||||
{
|
||||
provider: "google",
|
||||
model: "gemini-3-pro-preview",
|
||||
capabilities: ["image", "video", "audio"],
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## 状态输出
|
||||
|
||||
当媒体理解运行时，`/status` 包含一行简短摘要：
|
||||
|
||||
```
|
||||
📎 Media: image ok (openai/gpt-5.2) · audio skipped (maxBytes)
|
||||
```
|
||||
|
||||
这显示每能力的结果以及适用时选择的提供商/模型。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 理解是**尽力而为**的。错误不会阻止回复。
|
||||
- 即使理解被禁用，附件仍然传递给模型。
|
||||
- 使用 `scope` 限制理解运行的位置（例如仅私信）。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [配置](/gateway/configuration)
|
||||
- [图片和媒体支持](/nodes/images)
|
||||
97
content/nodes/talk.md
Normal file
97
content/nodes/talk.md
Normal file
@@ -0,0 +1,97 @@
|
||||
---
|
||||
read_when:
|
||||
- 在 macOS/iOS/Android 上实现 Talk 模式
|
||||
- 更改语音/TTS/中断行为
|
||||
summary: Talk 模式：使用 ElevenLabs TTS 进行连续语音对话
|
||||
title: Talk 模式
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T10:07:59Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: ecbc3701c9e9502970cf13227fedbc9714d13668d8f4f3988fef2a4d68116a42
|
||||
source_path: nodes/talk.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Talk 模式
|
||||
|
||||
Talk 模式是一个连续的语音对话循环：
|
||||
|
||||
1. 监听语音
|
||||
2. 将转录文本发送到模型（main 会话，chat.send）
|
||||
3. 等待响应
|
||||
4. 通过 ElevenLabs 朗读（流式播放）
|
||||
|
||||
## 行为（macOS）
|
||||
|
||||
- Talk 模式启用时显示**常驻悬浮窗**。
|
||||
- **监听 → 思考 → 朗读**阶段转换。
|
||||
- **短暂停顿**（静音窗口）后，当前转录文本被发送。
|
||||
- 回复被**写入 WebChat**（与打字相同）。
|
||||
- **语音中断**（默认开启）：如果用户在助手朗读时开始说话，我们会停止播放并记录中断时间戳供下一个提示使用。
|
||||
|
||||
## 回复中的语音指令
|
||||
|
||||
助手可以在回复前添加**单行 JSON** 来控制语音：
|
||||
|
||||
```json
|
||||
{ "voice": "<voice-id>", "once": true }
|
||||
```
|
||||
|
||||
规则：
|
||||
|
||||
- 仅适用于第一个非空行。
|
||||
- 未知键会被忽略。
|
||||
- `once: true` 仅适用于当前回复。
|
||||
- 没有 `once` 时，该语音成为 Talk 模式的新默认值。
|
||||
- JSON 行在 TTS 播放前会被移除。
|
||||
|
||||
支持的键：
|
||||
|
||||
- `voice` / `voice_id` / `voiceId`
|
||||
- `model` / `model_id` / `modelId`
|
||||
- `speed`、`rate`（WPM）、`stability`、`similarity`、`style`、`speakerBoost`
|
||||
- `seed`、`normalize`、`lang`、`output_format`、`latency_tier`
|
||||
- `once`
|
||||
|
||||
## 配置（`~/.openclaw/openclaw.json`）
|
||||
|
||||
```json5
|
||||
{
|
||||
talk: {
|
||||
voiceId: "elevenlabs_voice_id",
|
||||
modelId: "eleven_v3",
|
||||
outputFormat: "mp3_44100_128",
|
||||
apiKey: "elevenlabs_api_key",
|
||||
interruptOnSpeech: true,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
默认值：
|
||||
|
||||
- `interruptOnSpeech`：true
|
||||
- `voiceId`：回退到 `ELEVENLABS_VOICE_ID` / `SAG_VOICE_ID`（或当 API 密钥可用时使用第一个 ElevenLabs 语音）
|
||||
- `modelId`：未设置时默认为 `eleven_v3`
|
||||
- `apiKey`：回退到 `ELEVENLABS_API_KEY`（或 Gateway 网关 shell profile（如果可用））
|
||||
- `outputFormat`：macOS/iOS 上默认为 `pcm_44100`，Android 上默认为 `pcm_24000`（设置 `mp3_*` 以强制 MP3 流式传输）
|
||||
|
||||
## macOS UI
|
||||
|
||||
- 菜单栏切换：**Talk**
|
||||
- 配置标签页：**Talk Mode** 组（voice id + 中断开关）
|
||||
- 悬浮窗：
|
||||
- **监听**：云朵随麦克风电平脉动
|
||||
- **思考**：下沉动画
|
||||
- **朗读**：辐射圆环
|
||||
- 点击云朵：停止朗读
|
||||
- 点击 X：退出 Talk 模式
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 需要语音 + 麦克风权限。
|
||||
- 使用 `chat.send` 针对会话键 `main`。
|
||||
- TTS 使用带有 `ELEVENLABS_API_KEY` 的 ElevenLabs 流式 API，并在 macOS/iOS/Android 上进行增量播放以降低延迟。
|
||||
- `eleven_v3` 的 `stability` 验证为 `0.0`、`0.5` 或 `1.0`；其他模型接受 `0..1`。
|
||||
- 设置时 `latency_tier` 验证为 `0..4`。
|
||||
- Android 支持 `pcm_16000`、`pcm_22050`、`pcm_24000` 和 `pcm_44100` 输出格式，用于低延迟 AudioTrack 流式传输。
|
||||
8
content/nodes/troubleshooting.md
Normal file
8
content/nodes/troubleshooting.md
Normal file
@@ -0,0 +1,8 @@
|
||||
---
|
||||
summary: 节点故障排查：排查配对、前台限制、权限与工具调用失败
|
||||
title: 节点故障排查
|
||||
---
|
||||
|
||||
# 节点故障排查
|
||||
|
||||
该页面是英文文档的中文占位版本，完整内容请先参考英文版：[Node Troubleshooting](/nodes/troubleshooting)。
|
||||
375
content/nodes/tts.md
Normal file
375
content/nodes/tts.md
Normal file
@@ -0,0 +1,375 @@
|
||||
---
|
||||
read_when:
|
||||
- 为回复启用文本转语音
|
||||
- 配置 TTS 提供商或限制
|
||||
- 使用 /tts 命令
|
||||
summary: 出站回复的文本转语音（TTS）
|
||||
title: 文本转语音
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T10:13:55Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 070ff0cc8592f64c6c9e4ddaddc7e8fba82f0692ceded6fe833ec9ba5b61e6fb
|
||||
source_path: tts.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 文本转语音（TTS）
|
||||
|
||||
OpenClaw 可以使用 ElevenLabs、OpenAI 或 Edge TTS 将出站回复转换为音频。它可以在任何 OpenClaw 能发送音频的地方工作；Telegram 会显示圆形语音消息气泡。
|
||||
|
||||
## 支持的服务
|
||||
|
||||
- **ElevenLabs**（主要或备用提供商）
|
||||
- **OpenAI**（主要或备用提供商；也用于摘要）
|
||||
- **Edge TTS**（主要或备用提供商；使用 `node-edge-tts`，无 API 密钥时为默认）
|
||||
|
||||
### Edge TTS 注意事项
|
||||
|
||||
Edge TTS 通过 `node-edge-tts` 库使用 Microsoft Edge 的在线神经网络 TTS 服务。它是托管服务（非本地），使用 Microsoft 的端点，不需要 API 密钥。`node-edge-tts` 公开了语音配置选项和输出格式，但并非所有选项都被 Edge 服务支持。citeturn2search0
|
||||
|
||||
由于 Edge TTS 是一个没有公布 SLA 或配额的公共 Web 服务，请将其视为尽力而为。如果你需要有保证的限制和支持，请使用 OpenAI 或 ElevenLabs。Microsoft 的语音 REST API 记录了每个请求 10 分钟的音频限制；Edge TTS 没有公布限制，所以假设类似或更低的限制。citeturn0search3
|
||||
|
||||
## 可选密钥
|
||||
|
||||
如果你想使用 OpenAI 或 ElevenLabs：
|
||||
|
||||
- `ELEVENLABS_API_KEY`（或 `XI_API_KEY`）
|
||||
- `OPENAI_API_KEY`
|
||||
|
||||
Edge TTS **不**需要 API 密钥。如果没有找到 API 密钥，OpenClaw 默认使用 Edge TTS（除非通过 `messages.tts.edge.enabled=false` 禁用）。
|
||||
|
||||
如果配置了多个提供商，首先使用选定的提供商，其他作为备用选项。自动摘要使用配置的 `summaryModel`（或 `agents.defaults.model.primary`），所以如果你启用摘要，该提供商也必须经过认证。
|
||||
|
||||
## 服务链接
|
||||
|
||||
- [OpenAI 文本转语音指南](https://platform.openai.com/docs/guides/text-to-speech)
|
||||
- [OpenAI 音频 API 参考](https://platform.openai.com/docs/api-reference/audio)
|
||||
- [ElevenLabs 文本转语音](https://elevenlabs.io/docs/api-reference/text-to-speech)
|
||||
- [ElevenLabs 认证](https://elevenlabs.io/docs/api-reference/authentication)
|
||||
- [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts)
|
||||
- [Microsoft 语音输出格式](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs)
|
||||
|
||||
## 默认启用吗？
|
||||
|
||||
不是。自动 TTS 默认**关闭**。在配置中使用 `messages.tts.auto` 或在每个会话中使用 `/tts always`（别名：`/tts on`）启用它。
|
||||
|
||||
一旦 TTS 开启，Edge TTS **是**默认启用的，并在没有 OpenAI 或 ElevenLabs API 密钥时自动使用。
|
||||
|
||||
## 配置
|
||||
|
||||
TTS 配置位于 `openclaw.json` 中的 `messages.tts` 下。完整 schema 在 [Gateway 网关配置](/gateway/configuration)中。
|
||||
|
||||
### 最小配置（启用 + 提供商）
|
||||
|
||||
```json5
|
||||
{
|
||||
messages: {
|
||||
tts: {
|
||||
auto: "always",
|
||||
provider: "elevenlabs",
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### OpenAI 主要，ElevenLabs 备用
|
||||
|
||||
```json5
|
||||
{
|
||||
messages: {
|
||||
tts: {
|
||||
auto: "always",
|
||||
provider: "openai",
|
||||
summaryModel: "openai/gpt-4.1-mini",
|
||||
modelOverrides: {
|
||||
enabled: true,
|
||||
},
|
||||
openai: {
|
||||
apiKey: "openai_api_key",
|
||||
model: "gpt-4o-mini-tts",
|
||||
voice: "alloy",
|
||||
},
|
||||
elevenlabs: {
|
||||
apiKey: "elevenlabs_api_key",
|
||||
baseUrl: "https://api.elevenlabs.io",
|
||||
voiceId: "voice_id",
|
||||
modelId: "eleven_multilingual_v2",
|
||||
seed: 42,
|
||||
applyTextNormalization: "auto",
|
||||
languageCode: "en",
|
||||
voiceSettings: {
|
||||
stability: 0.5,
|
||||
similarityBoost: 0.75,
|
||||
style: 0.0,
|
||||
useSpeakerBoost: true,
|
||||
speed: 1.0,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Edge TTS 主要（无 API 密钥）
|
||||
|
||||
```json5
|
||||
{
|
||||
messages: {
|
||||
tts: {
|
||||
auto: "always",
|
||||
provider: "edge",
|
||||
edge: {
|
||||
enabled: true,
|
||||
voice: "en-US-MichelleNeural",
|
||||
lang: "en-US",
|
||||
outputFormat: "audio-24khz-48kbitrate-mono-mp3",
|
||||
rate: "+10%",
|
||||
pitch: "-5%",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### 禁用 Edge TTS
|
||||
|
||||
```json5
|
||||
{
|
||||
messages: {
|
||||
tts: {
|
||||
edge: {
|
||||
enabled: false,
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### 自定义限制 + 偏好路径
|
||||
|
||||
```json5
|
||||
{
|
||||
messages: {
|
||||
tts: {
|
||||
auto: "always",
|
||||
maxTextLength: 4000,
|
||||
timeoutMs: 30000,
|
||||
prefsPath: "~/.openclaw/settings/tts.json",
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### 仅在收到语音消息后用音频回复
|
||||
|
||||
```json5
|
||||
{
|
||||
messages: {
|
||||
tts: {
|
||||
auto: "inbound",
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### 禁用长回复的自动摘要
|
||||
|
||||
```json5
|
||||
{
|
||||
messages: {
|
||||
tts: {
|
||||
auto: "always",
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
然后运行：
|
||||
|
||||
```
|
||||
/tts summary off
|
||||
```
|
||||
|
||||
### 字段说明
|
||||
|
||||
- `auto`：自动 TTS 模式（`off`、`always`、`inbound`、`tagged`）。
|
||||
- `inbound` 仅在收到语音消息后发送音频。
|
||||
- `tagged` 仅在回复包含 `[[tts]]` 标签时发送音频。
|
||||
- `enabled`：旧版开关（doctor 将其迁移到 `auto`）。
|
||||
- `mode`：`"final"`（默认）或 `"all"`（包括工具/分块回复）。
|
||||
- `provider`：`"elevenlabs"`、`"openai"` 或 `"edge"`（自动备用）。
|
||||
- 如果 `provider` **未设置**，OpenClaw 优先选择 `openai`（如果有密钥），然后是 `elevenlabs`（如果有密钥），否则是 `edge`。
|
||||
- `summaryModel`：用于自动摘要的可选廉价模型；默认为 `agents.defaults.model.primary`。
|
||||
- 接受 `provider/model` 或配置的模型别名。
|
||||
- `modelOverrides`：允许模型发出 TTS 指令（默认开启）。
|
||||
- `maxTextLength`：TTS 输入的硬性上限（字符）。超出时 `/tts audio` 会失败。
|
||||
- `timeoutMs`：请求超时（毫秒）。
|
||||
- `prefsPath`：覆盖本地偏好 JSON 路径（提供商/限制/摘要）。
|
||||
- `apiKey` 值回退到环境变量（`ELEVENLABS_API_KEY`/`XI_API_KEY`、`OPENAI_API_KEY`）。
|
||||
- `elevenlabs.baseUrl`：覆盖 ElevenLabs API 基础 URL。
|
||||
- `elevenlabs.voiceSettings`：
|
||||
- `stability`、`similarityBoost`、`style`：`0..1`
|
||||
- `useSpeakerBoost`：`true|false`
|
||||
- `speed`：`0.5..2.0`（1.0 = 正常）
|
||||
- `elevenlabs.applyTextNormalization`：`auto|on|off`
|
||||
- `elevenlabs.languageCode`：2 字母 ISO 639-1（例如 `en`、`de`）
|
||||
- `elevenlabs.seed`：整数 `0..4294967295`（尽力确定性）
|
||||
- `edge.enabled`：允许 Edge TTS 使用（默认 `true`；无 API 密钥）。
|
||||
- `edge.voice`：Edge 神经网络语音名称（例如 `en-US-MichelleNeural`）。
|
||||
- `edge.lang`：语言代码（例如 `en-US`）。
|
||||
- `edge.outputFormat`：Edge 输出格式（例如 `audio-24khz-48kbitrate-mono-mp3`）。
|
||||
- 有效值参见 Microsoft 语音输出格式；并非所有格式都被 Edge 支持。
|
||||
- `edge.rate` / `edge.pitch` / `edge.volume`：百分比字符串（例如 `+10%`、`-5%`）。
|
||||
- `edge.saveSubtitles`：在音频文件旁边写入 JSON 字幕。
|
||||
- `edge.proxy`：Edge TTS 请求的代理 URL。
|
||||
- `edge.timeoutMs`：请求超时覆盖（毫秒）。
|
||||
|
||||
## 模型驱动覆盖（默认开启）
|
||||
|
||||
默认情况下，模型**可以**为单个回复发出 TTS 指令。当 `messages.tts.auto` 为 `tagged` 时，需要这些指令来触发音频。
|
||||
|
||||
启用后，模型可以发出 `[[tts:...]]` 指令来覆盖单个回复的语音，加上可选的 `[[tts:text]]...[[/tts:text]]` 块来提供表达性标签（笑声、唱歌提示等），这些仅应出现在音频中。
|
||||
|
||||
示例回复负载：
|
||||
|
||||
```
|
||||
Here you go.
|
||||
|
||||
[[tts:provider=elevenlabs voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
|
||||
[[tts:text]](laughs) Read the song once more.[[/tts:text]]
|
||||
```
|
||||
|
||||
可用指令键（启用时）：
|
||||
|
||||
- `provider`（`openai` | `elevenlabs` | `edge`）
|
||||
- `voice`（OpenAI 语音）或 `voiceId`（ElevenLabs）
|
||||
- `model`（OpenAI TTS 模型或 ElevenLabs 模型 ID）
|
||||
- `stability`、`similarityBoost`、`style`、`speed`、`useSpeakerBoost`
|
||||
- `applyTextNormalization`（`auto|on|off`）
|
||||
- `languageCode`（ISO 639-1）
|
||||
- `seed`
|
||||
|
||||
禁用所有模型覆盖：
|
||||
|
||||
```json5
|
||||
{
|
||||
messages: {
|
||||
tts: {
|
||||
modelOverrides: {
|
||||
enabled: false,
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
可选白名单（禁用特定覆盖同时保持标签启用）：
|
||||
|
||||
```json5
|
||||
{
|
||||
messages: {
|
||||
tts: {
|
||||
modelOverrides: {
|
||||
enabled: true,
|
||||
allowProvider: false,
|
||||
allowSeed: false,
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## 单用户偏好
|
||||
|
||||
斜杠命令将本地覆盖写入 `prefsPath`（默认：`~/.openclaw/settings/tts.json`，可通过 `OPENCLAW_TTS_PREFS` 或 `messages.tts.prefsPath` 覆盖）。
|
||||
|
||||
存储的字段：
|
||||
|
||||
- `enabled`
|
||||
- `provider`
|
||||
- `maxLength`（摘要阈值；默认 1500 字符）
|
||||
- `summarize`（默认 `true`）
|
||||
|
||||
这些为该主机覆盖 `messages.tts.*`。
|
||||
|
||||
## 输出格式（固定）
|
||||
|
||||
- **Telegram**：Opus 语音消息（ElevenLabs 的 `opus_48000_64`，OpenAI 的 `opus`）。
|
||||
- 48kHz / 64kbps 是语音消息的良好权衡，圆形气泡所必需。
|
||||
- **其他渠道**：MP3（ElevenLabs 的 `mp3_44100_128`，OpenAI 的 `mp3`）。
|
||||
- 44.1kHz / 128kbps 是语音清晰度的默认平衡。
|
||||
- **Edge TTS**：使用 `edge.outputFormat`（默认 `audio-24khz-48kbitrate-mono-mp3`）。
|
||||
- `node-edge-tts` 接受 `outputFormat`，但并非所有格式都可从 Edge 服务获得。citeturn2search0
|
||||
- 输出格式值遵循 Microsoft 语音输出格式（包括 Ogg/WebM Opus）。citeturn1search0
|
||||
- Telegram `sendVoice` 接受 OGG/MP3/M4A；如果你需要有保证的 Opus 语音消息，请使用 OpenAI/ElevenLabs。citeturn1search1
|
||||
- 如果配置的 Edge 输出格式失败，OpenClaw 会使用 MP3 重试。
|
||||
|
||||
OpenAI/ElevenLabs 格式是固定的；Telegram 期望 Opus 以获得语音消息用户体验。
|
||||
|
||||
## 自动 TTS 行为
|
||||
|
||||
启用后，OpenClaw：
|
||||
|
||||
- 如果回复已包含媒体或 `MEDIA:` 指令，则跳过 TTS。
|
||||
- 跳过非常短的回复（< 10 字符）。
|
||||
- 启用时使用 `agents.defaults.model.primary`（或 `summaryModel`）对长回复进行摘要。
|
||||
- 将生成的音频附加到回复中。
|
||||
|
||||
如果回复超过 `maxLength` 且摘要关闭（或没有摘要模型的 API 密钥），则跳过音频并发送正常的文本回复。
|
||||
|
||||
## 流程图
|
||||
|
||||
```
|
||||
回复 -> TTS 启用？
|
||||
否 -> 发送文本
|
||||
是 -> 有媒体 / MEDIA: / 太短？
|
||||
是 -> 发送文本
|
||||
否 -> 长度 > 限制？
|
||||
否 -> TTS -> 附加音频
|
||||
是 -> 摘要启用？
|
||||
否 -> 发送文本
|
||||
是 -> 摘要（summaryModel 或 agents.defaults.model.primary）
|
||||
-> TTS -> 附加音频
|
||||
```
|
||||
|
||||
## 斜杠命令用法
|
||||
|
||||
只有一个命令：`/tts`。参见[斜杠命令](/tools/slash-commands)了解启用详情。
|
||||
|
||||
Discord 注意：`/tts` 是 Discord 的内置命令，所以 OpenClaw 在那里注册 `/voice` 作为原生命令。文本 `/tts ...` 仍然有效。
|
||||
|
||||
```
|
||||
/tts off
|
||||
/tts always
|
||||
/tts inbound
|
||||
/tts tagged
|
||||
/tts status
|
||||
/tts provider openai
|
||||
/tts limit 2000
|
||||
/tts summary off
|
||||
/tts audio Hello from OpenClaw
|
||||
```
|
||||
|
||||
注意事项：
|
||||
|
||||
- 命令需要授权发送者（白名单/所有者规则仍然适用）。
|
||||
- 必须启用 `commands.text` 或原生命令注册。
|
||||
- `off|always|inbound|tagged` 是单会话开关（`/tts on` 是 `/tts always` 的别名）。
|
||||
- `limit` 和 `summary` 存储在本地偏好中，不在主配置中。
|
||||
- `/tts audio` 生成一次性音频回复（不会开启 TTS）。
|
||||
|
||||
## 智能体工具
|
||||
|
||||
`tts` 工具将文本转换为语音并返回 `MEDIA:` 路径。当结果与 Telegram 兼容时，工具包含 `[[audio_as_voice]]`，以便 Telegram 发送语音气泡。
|
||||
|
||||
## Gateway 网关 RPC
|
||||
|
||||
Gateway 网关方法：
|
||||
|
||||
- `tts.status`
|
||||
- `tts.enable`
|
||||
- `tts.disable`
|
||||
- `tts.convert`
|
||||
- `tts.setProvider`
|
||||
- `tts.providers`
|
||||
72
content/nodes/voicewake.md
Normal file
72
content/nodes/voicewake.md
Normal file
@@ -0,0 +1,72 @@
|
||||
---
|
||||
read_when:
|
||||
- 更改语音唤醒词行为或默认值
|
||||
- 添加需要唤醒词同步的新节点平台
|
||||
summary: 全局语音唤醒词（Gateway 网关拥有）及其如何跨节点同步
|
||||
title: 语音唤醒
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:51:10Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: eb34f52dfcdc3fc1ae088ae1f621f245546d3cf388299fbeea62face61788c37
|
||||
source_path: nodes/voicewake.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 语音唤醒（全局唤醒词）
|
||||
|
||||
OpenClaw 将**唤醒词作为单一全局列表**，由 **Gateway 网关**拥有。
|
||||
|
||||
- **没有**每节点的自定义唤醒词。
|
||||
- **任何节点/应用 UI 都可以编辑**列表；更改由 Gateway 网关持久化并广播给所有人。
|
||||
- 每个设备仍保留自己的**语音唤醒启用/禁用**开关（本地用户体验 + 权限不同）。
|
||||
|
||||
## 存储（Gateway 网关主机）
|
||||
|
||||
唤醒词存储在 Gateway 网关机器上：
|
||||
|
||||
- `~/.openclaw/settings/voicewake.json`
|
||||
|
||||
结构：
|
||||
|
||||
```json
|
||||
{ "triggers": ["openclaw", "claude", "computer"], "updatedAtMs": 1730000000000 }
|
||||
```
|
||||
|
||||
## 协议
|
||||
|
||||
### 方法
|
||||
|
||||
- `voicewake.get` → `{ triggers: string[] }`
|
||||
- `voicewake.set`，参数 `{ triggers: string[] }` → `{ triggers: string[] }`
|
||||
|
||||
注意事项：
|
||||
|
||||
- 触发词会被规范化（修剪空格、删除空值）。空列表回退到默认值。
|
||||
- 为安全起见会强制执行限制（数量/长度上限）。
|
||||
|
||||
### 事件
|
||||
|
||||
- `voicewake.changed` 载荷 `{ triggers: string[] }`
|
||||
|
||||
接收者：
|
||||
|
||||
- 所有 WebSocket 客户端（macOS 应用、WebChat 等）
|
||||
- 所有已连接的节点（iOS/Android），以及节点连接时作为初始"当前状态"推送。
|
||||
|
||||
## 客户端行为
|
||||
|
||||
### macOS 应用
|
||||
|
||||
- 使用全局列表来控制 `VoiceWakeRuntime` 触发器。
|
||||
- 在语音唤醒设置中编辑"触发词"会调用 `voicewake.set`，然后依赖广播保持其他客户端同步。
|
||||
|
||||
### iOS 节点
|
||||
|
||||
- 使用全局列表进行 `VoiceWakeManager` 触发检测。
|
||||
- 在设置中编辑唤醒词会调用 `voicewake.set`（通过 Gateway 网关 WS），同时保持本地唤醒词检测的响应性。
|
||||
|
||||
### Android 节点
|
||||
|
||||
- 在设置中暴露唤醒词编辑器。
|
||||
- 通过 Gateway 网关 WS 调用 `voicewake.set`，使编辑在所有地方同步。
|
||||
Reference in New Issue
Block a user