[OpenClaw 文档]工具--媒体与设备

2026年 5月 25日 OpenClaw SE_You

本文档汇总了 OpenClaw 官方文档站工具 > 媒体与设备 子模块下的全部 10 篇内容，源自 docs.openclaw.ai/zh-CN。

📑 本文目录（10 篇）

📄 节点

原文：https://docs.openclaw.ai/zh-CN/nodes

一个节点是连接到 Gateway 网关 WebSocket（与操作者使用同一端口）的配套设备（macOS/iOS/Android/无头设备），它使用 role: "node"，并通过 node.invoke 公开命令面（例如 canvas.*、camera.*、device.*、notifications.*、system.*）。协议详情：Gateway protocol。

旧版传输协议：Bridge protocol（TCP JSONL；
仅供当前节点作为历史参考）。

macOS 也可以在节点模式下运行：菜单栏应用会连接到 Gateway 网关的
WS 服务器，并将其本地 Canvas/摄像头命令作为节点公开（因此
openclaw nodes … 可以针对这台 Mac 工作）。在远程 Gateway 网关模式下，浏览器
自动化由 CLI 节点主机（openclaw node run 或已安装的
节点服务）处理，而不是由原生应用节点处理。

注意：

节点是外设，不是 Gateway 网关。它们不运行 Gateway 网关服务。
Telegram/WhatsApp 等消息会落到 Gateway 网关，而不是节点上。
故障排除运行手册：/nodes/troubleshooting

配对 + Status

WS 节点使用设备配对。 节点会在 connect 期间提供设备身份；Gateway 网关
会为 role: node 创建设备配对请求。通过设备 CLI（或 UI）批准。

快速 CLI：

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>

如果节点使用变更后的认证详情（角色/作用域/公钥）重试，之前的
待处理请求会被取代，并创建新的 requestId。批准前请重新运行
openclaw devices list。

注意：

当节点的设备配对角色包含 node 时，nodes status 会将该节点标记为已配对。
设备配对记录是持久的已批准角色合约。令牌
轮换保留在该合约内；它不能把已配对节点升级为
配对批准从未授予的其他角色。
node.pair.*（CLI：openclaw nodes pending/approve/reject/remove/rename）是单独由 Gateway 网关拥有的
节点配对存储；它不会门控 WS connect 握手。
openclaw nodes remove --node <id|name|ip> 会从该
单独由 Gateway 网关拥有的节点配对存储中删除陈旧条目。
批准作用域遵循待处理请求声明的命令：
无命令请求：operator.pairing
非 exec 节点命令：operator.pairing + operator.write
system.run / system.run.prepare / system.which：operator.pairing + operator.admin

远程节点主机（system.run）

当你的 Gateway 网关运行在一台机器上，而你希望命令
在另一台机器上执行时，请使用节点主机。模型仍然与 Gateway 网关通信；当选择 host=node 时，Gateway 网关
会将 exec 调用转发给节点主机。

各组件运行位置

Gateway 网关主机：接收消息、运行模型、路由工具调用。
节点主机：在节点机器上执行 system.run/system.which。
批准：通过 ~/.openclaw/exec-approvals.json 在节点主机上强制执行。

批准说明：

基于批准的节点运行会绑定精确的请求上下文。
对于直接 shell/运行时文件执行，OpenClaw 还会尽力绑定一个具体的本地
文件操作数，并在该文件执行前发生变化时拒绝运行。
如果 OpenClaw 无法为解释器/运行时命令精确识别一个具体的本地文件，
则会拒绝基于批准的执行，而不是假装已经覆盖完整运行时语义。若需要更广泛的解释器语义，请使用沙箱隔离、
独立主机，或显式的受信任 allowlist/完整工作流。

启动节点主机（前台）

在节点机器上：

openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"

通过 SSH 隧道访问远程 Gateway 网关（loopback 绑定）

如果 Gateway 网关绑定到 loopback（gateway.bind=loopback，本地模式默认值），
远程节点主机无法直接连接。创建 SSH 隧道，并让
节点主机指向隧道的本地端。

示例（节点主机 -> Gateway 网关主机）：

# Terminal A (keep running): forward local 18790 -> gateway 127.0.0.1:18789
ssh -N -L 18790:127.0.0.1:18789 user@gateway-host

# Terminal B: export the gateway token and connect through the tunnel
export OPENCLAW_GATEWAY_TOKEN="<gateway-token>"
openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node"

注意：

openclaw node run 支持令牌或密码认证。
首选环境变量：OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD。
配置回退项是 gateway.auth.token / gateway.auth.password。
在本地模式下，节点主机会有意忽略 gateway.remote.token / gateway.remote.password。
在远程模式下，gateway.remote.token / gateway.remote.password 会按远程优先级规则参与解析。
如果配置了有效的本地 gateway.auth.* SecretRefs 但未解析，节点主机认证会失败关闭。
节点主机认证解析只接受 OPENCLAW_GATEWAY_* 环境变量。

启动节点主机（服务）

openclaw node install --host <gateway-host> --port 18789 --display-name "Build Node"
openclaw node start
openclaw node restart

配对 + 命名

在 Gateway 网关主机上：

openclaw devices list
openclaw devices approve <requestId>
openclaw nodes status

如果节点使用变更后的认证详情重试，请重新运行 openclaw devices list
并批准当前 requestId。

命名选项：

在 openclaw node run / openclaw node install 上使用 --display-name（持久保存在节点上的 ~/.openclaw/node.json 中）。
openclaw nodes rename --node <id|name|ip> --name "Build Node"（Gateway 网关覆盖项）。

将命令加入 allowlist

Exec 批准是按节点主机分别配置的。从 Gateway 网关添加 allowlist 条目：

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 网关配置）：

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 调用都会在节点主机上运行（受
节点 allowlist/批准约束）。

host=auto 不会自行隐式选择节点，但允许来自 auto 的显式逐调用 host=node 请求。如果你希望节点 exec 成为该会话的默认值，请显式设置 tools.exec.host=node 或 /exec host=node ...。

调用命令

低层级（原始 RPC）：

openclaw nodes invoke --node <idOrNameOrIp> --command canvas.eval --params '{"javaScript":"location.href"}'

对于常见的“给智能体一个 MEDIA 附件”工作流，也提供更高层级的辅助命令。

命令策略

节点命令必须通过两个门控后才能被调用：

节点必须在其 WebSocket connect.commands 列表中声明该命令。
Gateway 网关的平台策略必须允许声明的命令。

Windows 和 macOS 配套节点默认允许安全的已声明命令，例如
canvas.*、camera.list、location.get 和 screen.snapshot。
宣传 talk 能力或声明 talk.* 命令的受信任节点
也会默认允许已声明的按键通话命令（talk.ptt.start、talk.ptt.stop、
talk.ptt.cancel、talk.ptt.once），且不依赖平台标签。
危险或隐私敏感的命令，例如 camera.snap、camera.clip 和
screen.record，仍需要通过
gateway.nodes.allowCommands 显式选择启用。gateway.nodes.denyCommands 始终优先于
默认值和额外 allowlist 条目。

插件拥有的节点命令可以添加 Gateway 网关 node-invoke 策略。该策略
在 allowlist 检查之后、转发到节点之前运行，因此原始
node.invoke、CLI 辅助命令和专用智能体工具共享同一个插件
权限边界。危险的插件节点命令仍需要显式
gateway.nodes.allowCommands 选择启用。

节点更改其声明的命令列表后，请拒绝旧的设备配对
并批准新请求，这样 Gateway 网关才能存储更新后的命令快照。

屏幕截图（Canvas 快照）

如果节点正在显示 Canvas（WebView），canvas.snapshot 会返回 { format, base64 }。

CLI 辅助命令（写入临时文件并打印 MEDIA:<path>）：

openclaw nodes canvas snapshot --node <idOrNameOrIp> --format png
openclaw nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9

Canvas 控件

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）

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）：

openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>            # default: both facings (2 MEDIA lines)
openclaw nodes camera snap --node <idOrNameOrIp> --facing front

视频片段（mp4）：

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）。示例：

openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10
openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-audio

注意：

screen.record 可用性取决于节点平台。
屏幕录制会被限制为 <= 60s。
--no-audio 会在受支持的平台上禁用麦克风采集。
当有多个屏幕可用时，使用 --screen <index> 选择显示器。

位置（节点）

当设置中启用位置时，节点会公开 location.get。

CLI 辅助命令：

openclaw nodes location get --node <idOrNameOrIp>
openclaw nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000

注意：

位置默认关闭。
“始终”需要系统权限；后台获取会尽力执行。
响应包含纬度/经度、精度（米）和时间戳。

SMS（Android 节点）

当用户授予 SMS 权限且设备支持电话功能时，Android 节点可以公开 sms.send。

低层级调用：

openclaw nodes invoke --node <idOrNameOrIp> --command sms.send --params '{"to":"+15555550123","message":"Hello from OpenClaw"}'

注意：

必须先在 Android 设备上接受权限提示，该能力才会被宣传。
没有电话功能的纯 Wi-Fi 设备不会宣传 sms.send。

Android 设备 + 个人数据命令

当对应能力启用时，Android 节点可以宣传额外的命令系列。

可用系列：

device.status, device.info, device.permissions, device.health
notifications.list, notifications.actions
photos.latest
contacts.search, contacts.add
calendar.events, calendar.add
callLog.search
sms.search
motion.activity, motion.pedometer

调用示例：

openclaw nodes invoke --node <idOrNameOrIp> --command device.status --params '{}'
openclaw nodes invoke --node <idOrNameOrIp> --command notifications.list --params '{}'
openclaw nodes invoke --node <idOrNameOrIp> --command photos.latest --params '{"limit":1}'

注意事项：

运动命令受可用传感器的能力限制。

系统命令（节点主机 / Mac 节点）

macOS 节点公开 system.run、system.notify 和 system.execApprovals.get/set。
无头节点主机公开 system.run、system.which 和 system.execApprovals.get/set。

示例：

openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"
openclaw nodes invoke --node <idOrNameOrIp> --command system.which --params '{"name":"git"}'

注意事项：

system.run 在负载中返回 stdout/stderr/退出码。
Shell 执行现在通过 exec 工具并使用 host=node；nodes 仍然是显式节点命令的直接 RPC 入口。
nodes invoke 不公开 system.run 或 system.run.prepare；它们只保留在 exec 路径上。
exec 路径会在批准前准备规范的 systemRunPlan。一旦批准授予，Gateway 网关会转发该已存储的计划，而不是后续由调用方编辑的命令/cwd/会话字段。
system.notify 遵循 macOS 应用中的通知权限状态。
无法识别的节点 platform / deviceFamily 元数据会使用保守的默认允许列表，排除 system.run 和 system.which。如果你有意需要为未知平台使用这些命令，请通过 gateway.nodes.allowCommands 显式添加它们。
system.run 支持 --cwd、--env KEY=VAL、--command-timeout 和 --needs-screen-recording。
对于 shell 包装器（bash|sh|zsh ... -c/-lc），请求范围的 --env 值会缩减为显式允许列表（TERM、LANG、LC_*、COLORTERM、NO_COLOR、FORCE_COLOR）。
在允许列表模式下，对于始终允许决策，已知的调度包装器（env、nice、nohup、stdbuf、timeout）会持久化内部可执行文件路径，而不是包装器路径。如果无法安全展开，则不会自动持久化允许列表条目。
在允许列表模式下的 Windows 节点主机上，通过 cmd.exe /c 运行 shell 包装器需要批准（仅允许列表条目不会自动允许包装器形式）。
system.notify 支持 --priority <passive|active|timeSensitive> 和 --delivery <system|overlay|auto>。
节点主机会忽略 PATH 覆盖，并移除危险的启动/shell 键（DYLD_*、LD_*、NODE_OPTIONS、PYTHON*、PERL*、RUBYOPT、SHELLOPTS、PS4）。如果你需要额外的 PATH 条目，请配置节点主机服务环境（或将工具安装到标准位置），而不是通过 --env 传递 PATH。
在 macOS 节点模式下，system.run 受 macOS 应用中的 exec 批准控制（设置 → Exec approvals）。
ask/allowlist/full 的行为与无头节点主机相同；被拒绝的提示会返回 SYSTEM_RUN_DENIED。
在无头节点主机上，system.run 受 exec 批准控制（~/.openclaw/exec-approvals.json）。

Exec 节点绑定

当多个节点可用时，你可以将 exec 绑定到特定节点。
这会为 exec host=node 设置默认节点（也可按智能体覆盖）。

全局默认值：

openclaw config set tools.exec.node "node-id-or-name"

按智能体覆盖：

openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"

取消设置以允许任何节点：

openclaw config unset tools.exec.node
openclaw config unset agents.list[0].tools.exec.node

权限映射

节点可以在 node.list / node.describe 中包含 permissions 映射，以权限名称为键（例如 screenRecording、accessibility），以布尔值为值（true = 已授予）。

无头节点主机（跨平台）

OpenClaw 可以运行一个连接到 Gateway 网关 WebSocket 并公开 system.run / system.which 的无头节点主机（无 UI）。这在 Linux/Windows 上很有用，也适合在服务器旁运行最小节点。

启动它：

openclaw node run --host <gateway-host> --port 18789

注意事项：

仍然需要配对（Gateway 网关会显示设备配对提示）。
节点主机会将其节点 ID、令牌、显示名称和 Gateway 网关连接信息存储在 ~/.openclaw/node.json 中。
Exec 批准会通过 ~/.openclaw/exec-approvals.json 在本地强制执行
（请参阅 Exec 批准）。
在 macOS 上，无头节点主机默认在本地执行 system.run。设置
OPENCLAW_NODE_EXEC_HOST=app 可通过配套应用 exec 主机路由 system.run；添加
OPENCLAW_NODE_EXEC_FALLBACK=0 可要求使用应用主机，并在其不可用时失败关闭。
当 Gateway 网关 WS 使用 TLS 时，添加 --tls / --tls-fingerprint。

Mac 节点模式

macOS 菜单栏应用会作为节点连接到 Gateway 网关 WS 服务器（因此 openclaw nodes … 可用于此 Mac）。
在远程模式下，该应用会为 Gateway 网关端口打开 SSH 隧道并连接到 localhost。

📄 Node 故障排除

原文：https://docs.openclaw.ai/zh-CN/nodes/troubleshooting

当节点在状态中可见但节点工具失败时，使用此页面。

命令阶梯

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

然后运行节点特定检查：

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>

健康信号：

节点已连接，并已按 node 角色配对。
nodes describe 包含你正在调用的能力。
执行批准显示预期的模式/允许列表。

前台要求

canvas.*、camera.* 和 screen.* 在 iOS/Android 节点上只能在前台使用。

快速检查和修复：

openclaw nodes describe --node <idOrNameOrIp>
openclaw nodes canvas snapshot --node <idOrNameOrIp>
openclaw logs --follow

如果你看到 NODE_BACKGROUND_UNAVAILABLE，请将节点应用切到前台后重试。

权限矩阵

能力	iOS	Android	macOS 节点应用	典型失败代码
`camera.snap`, `camera.clip`	摄像头（+ 用于片段音频的麦克风）	摄像头（+ 用于片段音频的麦克风）	摄像头（+ 用于片段音频的麦克风）	`*_PERMISSION_REQUIRED`
`screen.record`	屏幕录制（+ 可选麦克风）	屏幕捕获提示（+ 可选麦克风）	屏幕录制	`*_PERMISSION_REQUIRED`
`location.get`	使用期间或始终（取决于模式）	基于模式的前台/后台位置	位置权限	`LOCATION_PERMISSION_REQUIRED`
`system.run`	不适用（节点主机路径）	不适用（节点主机路径）	需要执行批准	`SYSTEM_RUN_DENIED`

配对与批准

这些是不同的门禁：

设备配对：此节点能否连接到 Gateway 网关？
Gateway 网关节点命令策略：RPC 命令 ID 是否被 gateway.nodes.allowCommands / denyCommands 和平台默认值允许？
执行批准：此节点能否在本地运行特定 shell 命令？

快速检查：

openclaw devices list
openclaw nodes status
openclaw approvals get --node <idOrNameOrIp>
openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"

如果缺少配对，请先批准节点设备。
如果 nodes describe 缺少某个命令，请检查 Gateway 网关节点命令策略，以及该节点连接时是否实际声明了该命令。
如果配对正常但 system.run 失败，请修复该节点上的执行批准/允许列表。

节点配对是身份/信任门禁，不是按命令批准的表面。对于 system.run，每个节点的策略位于该节点的执行批准文件中（openclaw approvals get --node ...），不在 Gateway 网关配对记录中。

对于由批准支持的 host=node 运行，Gateway 网关还会将执行绑定到
已准备好的规范 systemRunPlan。如果后续调用方在已批准运行转发之前更改命令/cwd 或
会话元数据，Gateway 网关会将该运行作为批准不匹配而拒绝，而不是信任被编辑的载荷。

常见节点错误代码

NODE_BACKGROUND_UNAVAILABLE → 应用在后台；将其切到前台。
CAMERA_DISABLED → 节点设置中的摄像头开关已禁用。
*_PERMISSION_REQUIRED → 缺少/拒绝了操作系统权限。
LOCATION_DISABLED → 位置模式已关闭。
LOCATION_PERMISSION_REQUIRED → 请求的位置模式未被授予。
LOCATION_BACKGROUND_UNAVAILABLE → 应用在后台，但只有“使用期间”权限。
SYSTEM_RUN_DENIED: approval required → 执行请求需要显式批准。
SYSTEM_RUN_DENIED: allowlist miss → 命令被允许列表模式阻止。
在 Windows 节点主机上，像 cmd.exe /c ... 这样的 shell 包装形式在
允许列表模式下会被视为允许列表未命中，除非通过询问流程批准。

快速恢复循环

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow

如果仍然卡住：

重新批准设备配对。
重新打开节点应用（前台）。
重新授予操作系统权限。
重新创建/调整执行批准策略。

📄 媒体理解

原文：https://docs.openclaw.ai/zh-CN/nodes/media-understanding

OpenClaw 可以在回复流水线运行前总结传入媒体（图片/音频/视频）。它会自动检测本地工具或提供商密钥是否可用，并且可以禁用或自定义。如果理解功能关闭，模型仍会像往常一样接收原始文件/URL。

特定厂商的媒体行为由厂商插件注册，而 OpenClaw 核心负责共享的 tools.media 配置、后备顺序和回复流水线集成。

目标

可选：将传入媒体预先摘要为短文本，以加快路由并改善命令解析。
保留向模型传递原始媒体的能力（始终保留）。
支持提供商 API 和 CLI 后备。
允许多个模型按顺序后备（错误/大小/超时）。

高层行为

收集传入附件（MediaPaths、MediaUrls、MediaTypes）。

对每个已启用的能力（图片/音频/视频），按策略选择附件（默认：第一个）。

选择第一个符合条件的模型条目（大小 + 能力 + 凭证）。

如果某个模型失败或媒体过大，后备到下一个条目。

成功时：

- `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 音频选项
- 音频转录回显控制（echoTranscript，默认 false；echoFormat）
- 可选的按能力 models 列表（优先于共享模型）
- attachments 策略（mode、maxAttachments、prefer）
- scope（可选，按渠道/chatType/会话键门控）
- tools.media.concurrency：最大并发能力运行数（默认 2）。

{
  tools: {
    media: {
      models: [
        /* shared list */
      ],
      image: {
        /* optional overrides */
      },
      audio: {
        /* optional overrides */
        echoTranscript: true,
        echoFormat: '📝 "{transcript}"',
      },
      video: {
        /* optional overrides */
      },
    },
  },
}

模型条目

每个 models[] 条目可以是提供商或 CLI：

json5 { type: "provider", // default if omitted provider: "openai", model: "gpt-5.5", prompt: "Describe the image in <= 500 chars.", maxChars: 500, maxBytes: 10485760, timeoutSeconds: 60, capabilities: ["image"], // optional, used for multi-modal entries 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，该模型会被跳过，并尝试下一个模型。
- 小于 1024 字节的音频文件会在提供商/CLI 转录前被视为空或损坏并跳过；传入回复上下文会收到确定性的占位转录文本，让智能体知道该语音备注太小。
- 如果模型返回内容超过 maxChars，输出会被截断。
- prompt 默认是简单的 “Describe the {media}.” 加上 maxChars 指引（仅图片/视频）。
- 如果当前主图片模型已经原生支持视觉，OpenClaw 会跳过 [Image] 摘要块，并改为将原始图片传入模型。
- 如果 Gateway 网关/WebChat 主模型仅支持文本，图片附件会作为卸载的 media://inbound/* 引用保留，这样图片/PDF 工具或已配置的图片模型仍可检查它们，而不会丢失附件。
- 显式的 openclaw infer image describe --model <provider/model> 请求不同：它们会直接运行该支持图片的提供商/模型，包括 ollama/qwen2.5vl:7b 这类 Ollama 引用。
- 如果 <capability>.enabled: true 但没有配置模型，OpenClaw 会在活动回复模型的提供商支持该能力时尝试使用活动回复模型。

自动检测媒体理解（默认）

如果 tools.media.<capability>.enabled 没有设置为 false，且你尚未配置模型，OpenClaw 会按以下顺序自动检测，并在第一个可用选项处停止：

当活动回复模型的提供商支持该能力时，使用活动回复模型。

agents.defaults.imageModel 主/后备引用（仅图片）。
优先使用 provider/model 引用。裸引用仅在匹配唯一时，才会从已配置的支持图片的提供商模型条目中限定。

本地 CLI（如果已安装）：

- `sherpa-onnx-offline`（需要包含 encoder/decoder/joiner/tokens 的 `SHERPA_ONNX_MODEL_DIR`）
- `whisper-cli`（`whisper-cpp`；使用 `WHISPER_CPP_MODEL` 或内置 tiny 模型）
- `whisper`（Python CLI；自动下载模型）

使用 read_many_files 的 gemini。

- 在内置后备顺序之前，会先尝试支持该能力的已配置 models.providers.* 条目。
- 仅图片的配置提供商如果带有支持图片的模型，即使不是内置厂商插件，也会自动注册用于媒体理解。
- 显式选择时可以使用 Ollama 图片理解，例如通过 agents.defaults.imageModel 或 openclaw infer image describe --model ollama/<vision-model>。

内置后备顺序：

- 音频：OpenAI → Groq → xAI → Deepgram → OpenRouter → Google → SenseAudio → ElevenLabs → Mistral
- 图片：OpenAI → Anthropic → Google → MiniMax → MiniMax Portal → Z.AI
- 视频：Google → Qwen → Moonshot

要禁用自动检测，请设置：

{
  tools: {
    media: {
      audio: {
        enabled: false,
      },
    },
  },
}

二进制检测在 macOS/Linux/Windows 上是尽力而为；请确保 CLI 位于 PATH（我们会展开 ~），或使用完整命令路径设置显式 CLI 模型。

代理环境支持（提供商模型）

启用基于提供商的音频和视频媒体理解时，OpenClaw 会在提供商 HTTP 调用中遵循标准出站代理环境变量：

HTTPS_PROXY
HTTP_PROXY
ALL_PROXY
https_proxy
http_proxy
all_proxy

如果未设置代理环境变量，媒体理解会使用直接出站连接。如果代理值格式错误，OpenClaw 会记录警告并后备到直接获取。

能力（可选）

如果你设置了 capabilities，该条目只会针对这些媒体类型运行。对于共享列表，OpenClaw 可以推断默认值：

openai、anthropic、minimax：图片
minimax-portal：图片
moonshot：图片 + 视频
openrouter：图片 + 音频
google（Gemini API）：图片 + 音频 + 视频
qwen：图片 + 视频
mistral：音频
zai：图片
groq：音频
xai：音频
deepgram：音频
任何包含支持图片模型的 models.providers.<id>.models[] 目录：图片

对于 CLI 条目，请显式设置 capabilities，以避免意外匹配。如果省略 capabilities，该条目会对它所在的列表有效。

提供商支持矩阵（OpenClaw 集成）

能力	提供商集成	备注
图片	OpenAI, OpenAI Codex OAuth, Codex app-server, OpenRouter, Anthropic, Google, MiniMax, Moonshot, Qwen, Z.AI, config providers	厂商插件会注册图片支持；`openai-codex/` 使用 OAuth 提供商管道；`codex/` 使用有界的 Codex app-server 轮次；MiniMax 和 MiniMax OAuth 都使用 `MiniMax-VL-01`；支持图片的配置提供商会自动注册。
音频	OpenAI, Groq, xAI, Deepgram, OpenRouter, Google, SenseAudio, ElevenLabs, Mistral	提供商转录（Whisper/Groq/xAI/Deepgram/OpenRouter STT/Gemini/SenseAudio/Scribe/Voxtral）。
视频	Google, Qwen, Moonshot	通过厂商插件进行提供商视频理解；Qwen 视频理解使用标准 DashScope 端点。

MiniMax 说明

minimax 和 minimax-portal 图片理解来自插件拥有的 MiniMax-VL-01 媒体提供商。
内置 MiniMax 文本目录仍从仅文本开始；显式的 models.providers.minimax 条目会具象化支持图片的 M2.7 chat 引用。

模型选择指引

当质量和安全很重要时，优先为每种媒体能力使用可用的最强最新一代模型。
对于处理不受信任输入的启用工具的智能体，避免使用更旧/更弱的媒体模型。
为每种能力至少保留一个后备以保证可用性（高质量模型 + 更快/更便宜的模型）。
当提供商 API 不可用时，CLI 后备（whisper-cli、whisper、gemini）很有用。
parakeet-mlx 说明：使用 --output-dir 时，如果输出格式为 txt（或未指定），OpenClaw 会读取 <output-dir>/<media-basename>.txt；非 txt 格式会后备到 stdout。

附件策略

按能力的 attachments 控制要处理哪些附件：

是否处理第一个选中的附件，还是处理所有选中的附件。

限制处理数量。

候选附件之间的选择偏好。

当 mode: "all" 时，输出会标记为 [Image 1/2]、[Audio 2/2] 等。

- 提取出的文件文本会先包装为不受信任的外部内容，再追加到媒体提示中。
- 注入的块使用明确的边界标记，例如 <<<EXTERNAL_UNTRUSTED_CONTENT id="...">>> / <<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>>，并包含一行 Source: External 元数据。
- 此附件提取路径会有意省略较长的 SECURITY NOTICE: 横幅，以避免媒体提示膨胀；边界标记和元数据仍会保留。
- 如果文件没有可提取文本，OpenClaw 会注入 [No extractable text]。
- 如果 PDF 在此路径中回退到渲染后的页面图像，媒体提示会保留占位符 [PDF content rendered to images; images not forwarded to model]，因为此附件提取步骤转发的是文本块，而不是渲染后的 PDF 图像。

配置示例

json5 { tools: { media: { models: [ { provider: "openai", model: "gpt-5.5", 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, }, }, }, }

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.", ], }, ], }, }, }, }

json5 { tools: { media: { image: { enabled: true, maxBytes: 10485760, maxChars: 500, models: [ { provider: "openai", model: "gpt-5.5" }, { provider: "anthropic", model: "claude-opus-4-6" }, { type: "cli", command: "gemini", args: [ "-m", "gemini-3-flash", "--allowed-tools", "read_file", "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.", ], }, ], }, }, }, }

json5 { tools: { media: { image: { models: [ { provider: "google", model: "gemini-3.1-pro-preview", capabilities: ["image", "video", "audio"], }, ], }, audio: { models: [ { provider: "google", model: "gemini-3.1-pro-preview", capabilities: ["image", "video", "audio"], }, ], }, video: { models: [ { provider: "google", model: "gemini-3.1-pro-preview", capabilities: ["image", "video", "audio"], }, ], }, }, }, }

Status 输出

媒体理解运行时，/status 会包含一行简短摘要：

📎 Media: image ok (openai/gpt-5.4) · audio skipped (maxBytes)

这会显示每种能力的结果，并在适用时显示所选的提供商/模型。

说明

理解是尽力而为。错误不会阻止回复。
即使理解已禁用，附件仍会传递给模型。
使用 scope 限制理解运行的位置（例如仅私信）。

📄 图像和媒体支持

原文：https://docs.openclaw.ai/zh-CN/nodes/images

WhatsApp 渠道通过 Baileys Web 运行。本文档记录当前针对发送、Gateway 网关和智能体回复的媒体处理规则。

目标

通过 openclaw message send --media 发送带可选说明文字的媒体。
允许来自 Web 收件箱的自动回复在文本旁包含媒体。
保持各类型限制合理且可预测。

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），目标为 channels.whatsapp.mediaMaxMb（默认：50 MB）。
音频/语音/视频：最大 16 MB 透传；音频会作为语音便笺发送（ptt: true）。
文档：其他所有内容，最大 100 MB，可用时保留文件名。
WhatsApp GIF 风格播放：发送带有 gifPlayback: true 的 MP4（CLI：--gif-playback），让移动客户端以内联方式循环播放。
MIME 检测优先使用魔数，然后是标头，最后是文件扩展名。
说明文字来自 --message 或 reply.text；允许空说明文字。
日志：非详细模式显示 ↩️/✅；详细模式包含大小和源路径/URL。

自动回复管线

getReplyFromConfig 返回 { text?, mediaUrl?, mediaUrls? }。
存在媒体时，Web 发送器会使用与 openclaw message send 相同的管线解析本地路径或 URL。
如果提供了多个媒体条目，会按顺序逐个发送。

传入媒体到命令（Pi）

当传入的 Web 消息包含媒体时，OpenClaw 会下载到临时文件，并暴露模板变量：
{{MediaUrl}} 传入媒体的伪 URL。
{{MediaPath}} 运行命令前写入的本地临时路径。
启用按会话的 Docker 沙箱时，传入媒体会复制到沙箱工作区，并将 MediaPath/MediaUrl 重写为类似 media/inbound/<filename> 的相对路径。
媒体理解（如果通过 tools.media.* 或共享的 tools.media.models 配置）会在模板渲染前运行，并可将 [Image]、[Audio] 和 [Video] 块插入到 Body 中。
音频会设置 {{Transcript}}，并使用转录文本进行命令解析，因此斜杠命令仍可工作。
视频和图片描述会保留任何说明文字以用于命令解析。
如果当前主图片模型已原生支持视觉，OpenClaw 会跳过 [Image] 摘要块，改为将原始图片传递给模型。
默认仅处理第一个匹配的图片/音频/视频附件；设置 tools.media.<cap>.attachments 可处理多个附件。

限制和错误

出站发送上限（WhatsApp Web 发送）

图片：重新压缩后最大为 channels.whatsapp.mediaMaxMb（默认：50 MB）。
音频/语音/视频：16 MB 上限；文档：100 MB 上限。
超大或不可读媒体 → 日志中显示明确错误，并跳过该回复。

媒体理解上限（转录/描述）

图片默认：10 MB（tools.media.image.maxBytes）。
音频默认：20 MB（tools.media.audio.maxBytes）。
视频默认：50 MB（tools.media.video.maxBytes）。
超大媒体会跳过理解，但回复仍会带原始正文继续发送。

测试注意事项

覆盖图片/音频/文档场景的发送和回复流程。
验证图片重新压缩（大小边界）以及音频的语音便笺标志。
确保多媒体回复会展开为按顺序发送。

📄 音频和语音消息

原文：https://docs.openclaw.ai/zh-CN/nodes/audio

可用功能

媒体理解（音频）：如果启用了音频理解（或自动检测到），OpenClaw 会：
1. 定位第一个音频附件（本地路径或 URL），并在需要时下载它。
2. 在发送到每个模型条目前强制检查 maxBytes。
3. 按顺序运行第一个符合条件的模型条目（提供商或 CLI）。
4. 如果失败或跳过（大小/超时），会尝试下一个条目。
5. 成功后，它会将 Body 替换为 [Audio] 块，并设置 {{Transcript}}。
命令解析：转录成功时，CommandBody/RawBody 会被设置为转录文本，因此斜杠命令仍然可用。
详细日志：在 --verbose 下，我们会记录转录何时运行，以及何时替换正文。

自动检测（默认）

如果你没有配置模型，并且 tools.media.audio.enabled 未设置为 false，
OpenClaw 会按以下顺序自动检测，并在第一个可用选项处停止：

当前回复模型，当其提供商支持音频理解时。
本地 CLI（如果已安装）
- sherpa-onnx-offline（需要带有 encoder/decoder/joiner/tokens 的 SHERPA_ONNX_MODEL_DIR）
- whisper-cli（来自 whisper-cpp；使用 WHISPER_CPP_MODEL 或内置 tiny 模型）
- whisper（Python CLI；自动下载模型）
Gemini CLI（gemini），使用 read_many_files
提供商凭证
- 会优先尝试配置的、支持音频的 models.providers.* 条目
- 内置备用顺序：OpenAI → Groq → xAI → Deepgram → Google → SenseAudio → ElevenLabs → Mistral

要禁用自动检测，请设置 tools.media.audio.enabled: false。
要自定义，请设置 tools.media.audio.models。
注意：二进制检测在 macOS/Linux/Windows 上是尽力而为；请确保 CLI 在 PATH 上（我们会展开 ~），或设置一个带完整命令路径的显式 CLI 模型。

配置示例

提供商 + CLI 备用（OpenAI + Whisper CLI）

{
  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,
          },
        ],
      },
    },
  },
}

仅提供商并使用范围门控

{
  tools: {
    media: {
      audio: {
        enabled: true,
        scope: {
          default: "allow",
          rules: [{ action: "deny", match: { chatType: "group" } }],
        },
        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
      },
    },
  },
}

仅提供商（Deepgram）

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "deepgram", model: "nova-3" }],
      },
    },
  },
}

仅提供商（Mistral Voxtral）

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "mistral", model: "voxtral-mini-latest" }],
      },
    },
  },
}

仅提供商（SenseAudio）

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "senseaudio", model: "senseaudio-asr-pro-1.5-260319" }],
      },
    },
  },
}

将转录文本回显到聊天（选择启用）

{
  tools: {
    media: {
      audio: {
        enabled: true,
        echoTranscript: true, // default is false
        echoFormat: '📝 "{transcript}"', // optional, supports {transcript}
        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
      },
    },
  },
}

注意事项和限制

提供商凭证遵循标准模型凭证顺序（凭证配置文件、环境变量、models.providers.*.apiKey）。
Groq 设置详情：Groq。
使用 provider: "deepgram" 时，Deepgram 会读取 DEEPGRAM_API_KEY。
Deepgram 设置详情：Deepgram（音频转录）。
Mistral 设置详情：Mistral。
使用 provider: "senseaudio" 时，SenseAudio 会读取 SENSEAUDIO_API_KEY。
SenseAudio 设置详情：SenseAudio。
音频提供商可以通过 tools.media.audio 覆盖 baseUrl、headers 和 providerOptions。
默认大小上限为 20MB（tools.media.audio.maxBytes）。超大音频会被该模型跳过，并尝试下一个条目。
低于 1024 字节的微小/空音频文件会在提供商/CLI 转录前被跳过。
音频的默认 maxChars 未设置（完整转录文本）。设置 tools.media.audio.maxChars 或每条目的 maxChars 来裁剪输出。
OpenAI 自动默认值为 gpt-4o-mini-transcribe；设置 model: "gpt-4o-transcribe" 可获得更高准确率。
使用 tools.media.audio.attachments 处理多条语音消息（mode: "all" + maxAttachments）。
转录文本可作为 {{Transcript}} 在模板中使用。
tools.media.audio.echoTranscript 默认关闭；启用它可在智能体处理前，将转录确认发送回原始聊天。
tools.media.audio.echoFormat 用于自定义回显文本（占位符：{transcript}）。
CLI stdout 有上限（5MB）；请保持 CLI 输出简洁。
CLI args 应使用 {{MediaPath}} 表示本地音频文件路径。运行 openclaw doctor --fix，可从较旧的 audio.transcription.command 配置迁移已弃用的 {input} 占位符。

代理环境支持

基于提供商的音频转录会遵循标准出站代理环境变量：

HTTPS_PROXY
HTTP_PROXY
ALL_PROXY
https_proxy
http_proxy
all_proxy

如果未设置代理环境变量，则使用直接出站连接。如果代理配置格式错误，OpenClaw 会记录警告并回退到直接获取。

群组中的提及检测

当群聊设置了 requireMention: true 时，OpenClaw 现在会在检查提及之前转录音频。这样即使语音消息中包含提及，也可以被处理。

工作方式：

如果一条语音消息没有文本正文，并且群组要求提及，OpenClaw 会执行一次“预检”转录。
转录文本会被检查是否包含提及模式（例如 @BotName、emoji 触发器）。
如果找到提及，消息会继续进入完整回复管线。
转录文本用于提及检测，因此语音消息可以通过提及门控。

备用行为：

如果预检期间转录失败（超时、API 错误等），消息会基于纯文本提及检测进行处理。
这确保混合消息（文本 + 音频）绝不会被错误丢弃。

按 Telegram 群组/话题选择退出：

设置 channels.telegram.groups.<chatId>.disableAudioPreflight: true 可跳过该群组的预检转录提及检查。
设置 channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight 可按话题覆盖（true 表示跳过，false 表示强制启用）。
默认值为 false（当提及门控条件匹配时启用预检）。

示例： 用户在设置了 requireMention: true 的 Telegram 群组中发送一条语音消息，说“Hey @Claude, what's the weather?”。语音消息会被转录，提及会被检测到，智能体随后回复。

注意点

范围规则采用首个匹配优先。chatType 会标准化为 direct、group 或 room。
确保你的 CLI 以 0 退出并打印纯文本；JSON 需要通过 jq -r .text 处理。
对于 parakeet-mlx，如果你传入 --output-dir，当 --output-format 为 txt（或省略）时，OpenClaw 会读取 <output-dir>/<media-basename>.txt；非 txt 输出格式会回退到解析 stdout。
保持合理的超时时间（timeoutSeconds，默认 60 秒），避免阻塞回复队列。
预检转录只处理用于提及检测的第一个音频附件。其他音频会在主媒体理解阶段处理。

📄 摄像头捕获

原文：https://docs.openclaw.ai/zh-CN/nodes/camera

OpenClaw 支持用于智能体工作流的摄像头捕获：

iOS 节点（通过 Gateway 网关配对）：通过 node.invoke 捕获照片（jpg）或短视频片段（mp4，可选音频）。
Android 节点（通过 Gateway 网关配对）：通过 node.invoke 捕获照片（jpg）或短视频片段（mp4，可选音频）。
macOS 应用（通过 Gateway 网关连接的节点）：通过 node.invoke 捕获照片（jpg）或短视频片段（mp4，可选音频）。

所有摄像头访问都受用户控制的设置约束。

iOS 节点

用户设置（默认开启）

iOS 设置标签页 → Camera → Allow Camera（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>。

示例：

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 默认使用两个朝向，为智能体提供两个视角。
输出文件是临时文件（位于 OS 临时目录），除非你构建自己的封装器。

Android 节点

Android 用户设置（默认开启）

Android 设置表单 → Camera → Allow Camera（camera.enabled）
默认：开启（缺失键名会被视为已启用）。
关闭时：camera.* 命令返回 CAMERA_DISABLED。

权限

Android 需要运行时权限：
CAMERA 用于 camera.snap 和 camera.clip。
当 includeAudio=true 时，RECORD_AUDIO 用于 camera.clip。

如果缺少权限，应用会在可能时提示；如果被拒绝，camera.* 请求会失败并返回
*_PERMISSION_REQUIRED 错误。

Android 前台要求

与 canvas.* 一样，Android 节点仅允许在前台执行 camera.* 命令。后台调用会返回 NODE_BACKGROUND_UNAVAILABLE。

Android 命令（通过 Gateway 网关 `node.invoke`）

camera.list
响应负载：
- devices：{ id, name, position, deviceType } 的数组

负载保护

照片会被重新压缩，以确保 base64 负载低于 5 MB。

macOS 应用

用户设置（默认关闭）

macOS 配套应用提供一个复选框：

Settings → General → Allow Camera（openclaw.cameraEnabled）
默认：关闭
关闭时：摄像头请求返回 “用户已禁用摄像头”。

CLI 辅助工具（节点调用）

使用主 openclaw CLI 在 macOS 节点上调用摄像头命令。

示例：

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。

安全性 + 实用限制

摄像头和麦克风访问会触发常规 OS 权限提示（并且需要在 Info.plist 中提供用途字符串）。
视频片段有时长上限（当前 <= 60s），以避免节点负载过大（base64 开销 + 消息限制）。

macOS 屏幕视频（OS 级别）

对于_屏幕_视频（不是摄像头），使用 macOS 配套应用：

openclaw nodes screen record --node <id> --duration 10s --fps 15   # prints MEDIA:<path>

注意：

需要 macOS Screen Recording 权限（TCC）。

📄 Talk 模式

原文：https://docs.openclaw.ai/zh-CN/nodes/talk

Talk 模式有两种运行时形态：

原生 macOS/iOS/Android Talk 使用本地语音识别、Gateway 网关聊天和 talk.speak TTS。节点会通告 talk 能力，并声明它们支持的 talk.* 命令。
浏览器 Talk 使用 talk.client.create 创建客户端拥有的 webrtc 和 provider-websocket 会话，或使用 talk.session.create 创建 Gateway 网关拥有的 gateway-relay 会话。managed-room 预留给 Gateway 网关交接和对讲房间。
仅转写客户端使用 talk.session.create({ mode: "transcription", transport: "gateway-relay", brain: "none" })，然后在需要无助手语音回复的字幕或听写时使用 talk.session.appendAudio、talk.session.cancelTurn 和 talk.session.close。

原生 Talk 是一个连续语音对话循环：

监听语音
通过活动会话将转写文本发送给模型
等待回复
通过已配置的 Talk 提供商（talk.speak）朗读

浏览器实时 Talk 通过 talk.client.toolCall 转发提供商工具调用；浏览器客户端不会为实时咨询直接调用 chat.send。

仅转写 Talk 会发出与实时以及 STT/TTS 会话相同的通用 Talk 事件信封，但使用 mode: "transcription" 和 brain: "none"。它用于字幕、听写和仅观察式语音捕获；一次性上传的语音备忘仍使用媒体/音频路径。

行为（macOS）

启用 Talk 模式时显示常驻叠层。
正在聆听 → 正在思考 → 正在说话阶段转换。
出现短暂停顿（静音窗口）时，会发送当前转写文本。
回复会写入 WebChat（与输入相同）。
说话时打断（默认开启）：如果用户在助手说话时开始讲话，我们会停止播放，并为下一次提示记录打断时间戳。

回复中的语音指令

助手可以在回复前加上单行 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`）

{
  talk: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        voiceId: "elevenlabs_voice_id",
        modelId: "eleven_v3",
        outputFormat: "mp3_44100_128",
        apiKey: "elevenlabs_api_key",
      },
      mlx: {
        modelId: "mlx-community/Soprano-80M-bf16",
      },
      system: {},
    },
    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
    realtime: {
      provider: "openai",
      providers: {
        openai: {
          apiKey: "openai_api_key",
          model: "gpt-realtime-2",
          voice: "cedar",
        },
      },
      instructions: "Speak warmly and keep answers brief.",
      mode: "realtime",
      transport: "webrtc",
      brain: "agent-consult",
    },
  },
}

默认值：

interruptOnSpeech：true
silenceTimeoutMs：未设置时，Talk 会在发送转写文本前保留平台默认的暂停窗口（macOS 和 Android 上为 700 ms，iOS 上为 900 ms）
provider：选择活动 Talk 提供商。对 macOS 本地播放路径使用 elevenlabs、mlx 或 system。
providers.<provider>.voiceId：ElevenLabs 会回退到 ELEVENLABS_VOICE_ID / SAG_VOICE_ID（或 API key 可用时的第一个 ElevenLabs 语音）。
providers.elevenlabs.modelId：未设置时默认使用 eleven_v3。
providers.mlx.modelId：未设置时默认使用 mlx-community/Soprano-80M-bf16。
providers.elevenlabs.apiKey：回退到 ELEVENLABS_API_KEY（如果可用，也会使用 Gateway 网关 shell profile）。
consultThinkingLevel：实时 openclaw_agent_consult 调用背后的完整 OpenClaw 智能体运行的可选思考级别覆盖项。
consultFastMode：实时 openclaw_agent_consult 调用的可选快速模式覆盖项。
realtime.provider：选择活动浏览器/服务器实时语音提供商。WebRTC 使用 openai，提供商 WebSocket 使用 google，或通过 Gateway 网关中继使用仅桥接提供商。
realtime.providers.<provider> 存储提供商拥有的实时配置。浏览器只接收临时或受限的会话凭据，绝不会接收标准 API key。
realtime.providers.openai.voice：内置 OpenAI Realtime 语音 ID。当前 gpt-realtime-2 语音包括 alloy、ash、ballad、coral、echo、sage、shimmer、verse、marin 和 cedar；推荐使用 marin 和 cedar 以获得最佳质量。
realtime.brain：agent-consult 通过 Gateway 网关策略路由实时工具调用；direct-tools 是仅所有者使用的兼容行为；none 用于转写或外部编排。
realtime.instructions：将面向提供商的系统指令附加到 OpenClaw 内置实时提示中。可用于语音风格和语气；OpenClaw 会保留默认的 openclaw_agent_consult 指引。
talk.catalog 会公开每个提供商的有效模式、传输协议、brain 策略、实时音频格式和能力标志，以便第一方 Talk 客户端避免不受支持的组合。
流式转写提供商通过 talk.catalog.transcription 发现。当前 Gateway 网关中继会使用 Voice Call 流式提供商配置，直到添加专用的 Talk 转写配置界面。
speechLocale：iOS/macOS 上设备端 Talk 语音识别的可选 BCP 47 区域设置 ID。留空则使用设备默认值。
outputFormat：macOS/iOS 上默认为 pcm_44100，Android 上默认为 pcm_24000（设置 mp3_* 可强制使用 MP3 流式传输）

macOS UI

菜单栏开关：Talk
配置标签页：Talk 模式组（语音 ID + 打断开关）
叠层：
正在聆听：云朵随麦克风音量脉动
正在思考：下沉动画
正在说话：向外辐射的圆环
点击云朵：停止说话
点击 X：退出 Talk 模式

Android UI

语音标签页开关：Talk
手动麦克风和 Talk 是互斥的运行时捕获模式。
当应用离开前台或用户离开语音标签页时，手动麦克风会停止。
Talk 模式会一直运行，直到被关闭或 Android 节点断开连接，并且在活动期间使用 Android 的麦克风前台服务类型。

备注

需要语音 + 麦克风权限。
原生 Talk 使用活动 Gateway 网关会话，并且只在响应事件不可用时回退到历史轮询。
浏览器实时 Talk 对 openclaw_agent_consult 使用 talk.client.toolCall，而不是把 chat.send 暴露给提供商拥有的浏览器会话。
仅转写 Talk 使用 talk.session.create、talk.session.appendAudio、talk.session.cancelTurn 和 talk.session.close；客户端订阅 talk.event 以获取部分/最终转写更新。
Gateway 网关使用活动 Talk 提供商通过 talk.speak 解析 Talk 播放。只有在该 RPC 不可用时，Android 才会回退到本地系统 TTS。
macOS 本地 MLX 播放会在存在时使用内置的 openclaw-mlx-tts helper，或使用 PATH 上的可执行文件。开发期间可设置 OPENCLAW_MLX_TTS_BIN 指向自定义 helper 二进制文件。
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 流式传输。

📄 语音唤醒

原文：https://docs.openclaw.ai/zh-CN/nodes/voicewake

OpenClaw 将唤醒词视为一个全局列表，由 Gateway 网关管理。

没有按节点自定义的唤醒词。
任何节点/应用 UI 都可以编辑该列表；更改由 Gateway 网关持久化，并广播给所有人。
macOS 和 iOS 保留本地语音唤醒启用/禁用开关（本地 UX + 权限不同）。
Android 当前保持语音唤醒关闭，并在语音标签页中使用手动麦克风流程。

存储（Gateway 网关主机）

唤醒词存储在网关机器上的：

~/.openclaw/settings/voicewake.json

结构：

{ "triggers": ["openclaw", "claude", "computer"], "updatedAtMs": 1730000000000 }

协议

方法

voicewake.get → { triggers: string[] }
voicewake.set，参数为 { triggers: string[] } → { triggers: string[] }

说明：

触发词会被规范化（去除首尾空格，丢弃空值）。空列表会回退到默认值。
出于安全考虑会强制执行限制（数量/长度上限）。

路由方法（触发词 → 目标）

voicewake.routing.get → { config: VoiceWakeRoutingConfig }
voicewake.routing.set，参数为 { config: VoiceWakeRoutingConfig } → { config: VoiceWakeRoutingConfig }

VoiceWakeRoutingConfig 结构：

{
  "version": 1,
  "defaultTarget": { "mode": "current" },
  "routes": [{ "trigger": "robot wake", "target": { "sessionKey": "agent:main:main" } }],
  "updatedAtMs": 1730000000000
}

路由目标必须且只能支持以下一种：

{ "mode": "current" }
{ "agentId": "main" }
{ "sessionKey": "agent:main:main" }

事件

voicewake.changed 载荷 { triggers: string[] }
voicewake.routing.changed 载荷 { config: VoiceWakeRoutingConfig }

接收者：

所有 WebSocket 客户端（macOS 应用、WebChat 等）
所有已连接节点（iOS/Android），并且在节点连接时也会推送一次初始“当前状态”。

客户端行为

macOS 应用

使用全局列表来限定 VoiceWakeRuntime 触发词。
在语音唤醒设置中编辑“触发词”会调用 voicewake.set，然后依赖广播让其他客户端保持同步。

iOS 节点

使用全局列表进行 VoiceWakeManager 触发词检测。
在设置中编辑唤醒词会调用 voicewake.set（通过 Gateway 网关 WS），同时也会保持本地唤醒词检测响应及时。

Android 节点

语音唤醒当前在 Android 运行时/设置中处于禁用状态。
Android 语音使用语音标签页中的手动麦克风捕获，而不是唤醒词触发。

📄 位置命令

原文：https://docs.openclaw.ai/zh-CN/nodes/location-command

简而言之

location.get 是节点命令（通过 node.invoke）。
默认关闭。
Android 应用设置使用一个选择器：关闭 / 使用期间。
单独的开关：精确定位。

为什么使用选择器（而不只是开关）

OS 权限是多级的。我们可以在应用内提供选择器，但实际授权仍由 OS 决定。

iOS/macOS 可能会在系统提示/设置中显示 使用期间 或 始终允许。
Android 应用目前仅支持前台定位。
精确定位是单独的授权（iOS 14+ “精确”，Android “fine” 与 “coarse”）。

UI 中的选择器决定我们请求的模式；实际授权存储在 OS 设置中。

设置模型

按节点设备：

location.enabledMode: off | whileUsing
location.preciseEnabled: bool

UI 行为：

选择 whileUsing 会请求前台权限。
如果 OS 拒绝请求的级别，则回退到已授权的最高级别并显示状态。

权限映射（node.permissions）

可选。macOS 节点通过权限映射报告 location；iOS/Android 可能会省略它。

命令：`location.get`

通过 node.invoke 调用。

参数（建议）：

{
  "timeoutMs": 10000,
  "maxAgeMs": 15000,
  "desiredAccuracy": "coarse|balanced|precise"
}

响应载荷：

{
  "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：系统故障 / 无提供商。

后台行为

Android 应用在后台时会拒绝 location.get。
在 Android 上请求位置时，请保持 OpenClaw 打开。
其他节点平台可能有所不同。

模型/工具集成

工具表面：nodes 工具添加 location_get 操作（需要节点）。
CLI：openclaw nodes location get --node <id>。
智能体指南：仅在用户已启用位置且理解范围时调用。

UX 文案（建议）

关闭：“位置共享已禁用。”
使用期间：“仅在 OpenClaw 打开时。”
精确：“使用精确 GPS 位置。关闭开关以共享大致位置。”

📄 文本转语音

原文：https://docs.openclaw.ai/zh-CN/tts

此页面已迁移至文本转语音。

[OpenClaw 文档]工具--媒体与设备

📄 节点

配对 + Status

远程节点主机（system.run）

各组件运行位置

启动节点主机（前台）

通过 SSH 隧道访问远程 Gateway 网关（loopback 绑定）

启动节点主机（服务）

配对 + 命名

将命令加入 allowlist

将 exec 指向节点

调用命令

命令策略

屏幕截图（Canvas 快照）

Canvas 控件

A2UI（Canvas）

照片 + 视频（节点摄像头）

屏幕录制（节点）

位置（节点）

SMS（Android 节点）

Android 设备 + 个人数据命令

系统命令（节点主机 / Mac 节点）

Exec 节点绑定

权限映射

无头节点主机（跨平台）

Mac 节点模式

📄 Node 故障排除

命令阶梯

前台要求

权限矩阵

配对与批准

常见节点错误代码

快速恢复循环

相关

📄 媒体理解

目标

高层行为

配置概览

模型条目

默认值和限制

自动检测媒体理解（默认）

代理环境支持（提供商模型）

能力（可选）

提供商支持矩阵（OpenClaw 集成）

模型选择指引

附件策略

配置示例

Status 输出

说明

相关

📄 图像和媒体支持

目标

CLI 表面

WhatsApp Web 渠道行为

自动回复管线

传入媒体到命令（Pi）

限制和错误

测试注意事项

相关内容

📄 音频和语音消息

可用功能

自动检测（默认）

配置示例

提供商 + CLI 备用（OpenAI + Whisper CLI）

仅提供商并使用范围门控

仅提供商（Deepgram）

仅提供商（Mistral Voxtral）

仅提供商（SenseAudio）

将转录文本回显到聊天（选择启用）

注意事项和限制

代理环境支持

群组中的提及检测

注意点

相关内容

📄 摄像头捕获

iOS 节点

用户设置（默认开启）

命令（通过 Gateway 网关 node.invoke）

前台要求

CLI 辅助工具（临时文件 + MEDIA）

命令（通过 Gateway 网关 `node.invoke`）

Android 命令（通过 Gateway 网关 `node.invoke`）

配置（`~/.openclaw/openclaw.json`）

命令：`location.get`