OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

媒体与设备

相机拍摄

OpenClaw 支持在已配对的 iOS、Android、macOS 和 Linux 节点上为智能体工作流进行相机拍摄：通过 Gateway 网关 node.invoke 拍摄照片（jpg）或短视频片段（mp4，可选音频）。

所有相机访问权限均由各平台上用户可控的设置进行限制。

iOS 节点

iOS 用户设置

  • iOS Settings 标签页 → Camera → Allow Camera（camera.enabled）。
    • 默认值：开启（缺少该键时视为已启用）。
    • 关闭时：camera.* 命令返回 CAMERA_DISABLED。

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

  • camera.list

    • 响应载荷：devices — { id, name, position, deviceType } 数组。

  • camera.snap

    • 参数：
      • facing：front|back（默认值：front）
      • maxWidth：数字（可选；默认值为 1600）
      • quality：0..1（可选；默认值为 0.9，限制在 [0.05, 1.0]）
      • format：当前为 jpg
      • delayMs：数字（可选；默认值为 0，内部上限为 10000）
      • deviceId：字符串（可选；来自 camera.list）
    • 响应载荷：format: "jpg"、base64、width、height。
    • 载荷保护：照片会被重新压缩，以将 base64 编码后的载荷保持在 5MB 以下。

  • camera.clip

    • 参数：
      • facing：front|back（默认值：front）
      • durationMs：数字（默认值为 3000，限制在 [250, 60000]）
      • includeAudio：布尔值（默认值为 true）
      • format：当前为 mp4
      • deviceId：字符串（可选；来自 camera.list）
    • 响应载荷：format: "mp4"、base64、durationMs、hasAudio。

iOS 前台要求

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

CLI 辅助工具

获取媒体文件最简单的方式是使用 CLI 辅助工具，它会将解码后的媒体写入临时文件，并输出保存路径。

bash
openclaw nodes camera snap --node <id>                 # 默认：前置 + 后置相机（2 行 MEDIA）openclaw nodes camera snap --node <id> --facing frontopenclaw nodes camera clip --node <id> --duration 3000openclaw nodes camera clip --node <id> --no-audio

nodes camera snap 默认为 --facing both，会同时使用前置和后置相机拍摄，为智能体提供两个视角；若只需一个明确的朝向，请传入 --device-id（设置 --device-id 时会拒绝 both）。除非自行构建封装，否则输出文件均为临时文件（位于操作系统临时目录中）。

Android 节点

Android 用户设置

  • Android Settings 面板 → Camera → Allow Camera（camera.enabled）。
    • 全新安装默认关闭。 在此设置推出之前完成的现有安装会迁移为开启，从而避免升级后原本正常工作的相机访问权限被静默移除。
    • 关闭时：camera.* 命令返回 CAMERA_DISABLED: enable Camera in Settings。

权限

  • CAMERA 是 camera.snap 和 camera.clip 都需要的权限；权限缺失或被拒绝时返回 CAMERA_PERMISSION_REQUIRED。
  • 当 includeAudio 为 true 时，camera.clip 需要 RECORD_AUDIO 权限；权限缺失或被拒绝时返回 MIC_PERMISSION_REQUIRED。

应用会在可能的情况下请求运行时权限。

Android 前台要求

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

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

  • camera.list

    • 响应载荷：devices — { id, name, position, deviceType } 数组。

  • camera.snap

    • 参数：facing（front|back，默认值为 front）、quality（默认值为 0.95，限制在 [0.1, 1.0]）、maxWidth（默认值为 1600）、deviceId（可选；未知 ID 会以 INVALID_REQUEST 失败）。
    • 响应载荷：format: "jpg"、base64、width、height。
    • 载荷保护：重新压缩以将 base64 保持在 5MB 以下（与 iOS 的限制相同）。

  • camera.clip

    • 参数：facing（默认值为 front）、durationMs（默认值为 3000，限制在 [200, 60000]）、includeAudio（默认值为 true）、deviceId（可选）。
    • 响应载荷：format: "mp4"、base64、durationMs、hasAudio。
    • 载荷保护：base64 编码前的原始 MP4 上限为 18MB；过大的视频片段会以 PAYLOAD_TOO_LARGE 失败（请减小 durationMs 后重试）。

macOS 应用

macOS 用户设置

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

  • Settings → General → Allow Camera（openclaw.cameraEnabled）。
    • 默认值：关闭。
    • 关闭时：相机请求返回 CAMERA_DISABLED: enable Camera in Settings。

CLI 辅助工具（节点调用）

使用主 openclaw CLI 在 macOS 节点上调用相机命令。

bash
openclaw nodes camera list --node <id>                     # 列出相机 IDopenclaw nodes camera snap --node <id>                     # 输出保存路径openclaw nodes camera snap --node <id> --max-width 1280openclaw nodes camera snap --node <id> --delay-ms 2000openclaw nodes camera snap --node <id> --device-id <id>openclaw nodes camera clip --node <id> --duration 10s       # 输出保存路径openclaw nodes camera clip --node <id> --duration-ms 3000   # 输出保存路径（旧版标志）openclaw nodes camera clip --node <id> --device-id <id>openclaw nodes camera clip --node <id> --no-audio
  • 除非被覆盖，否则 openclaw nodes camera snap 默认为 maxWidth=1600。
  • camera.snap 会在预热和曝光稳定后等待 delayMs（默认 2000ms，限制在 [0, 10000]），然后再进行拍摄。
  • 照片载荷会被重新压缩，以将 base64 保持在 5MB 以下。

Linux 节点主机

内置 Linux Node 插件为 CLI openclaw node 服务添加相机拍摄功能。它可以在无头主机上运行，无需 Linux 桌面应用。

相机访问默认关闭。请在插件条目下启用它，然后重启节点服务，以重新构建其 Gateway 网关通告：

json5
{  plugins: {    entries: {      "linux-node": {        config: {          camera: { enabled: true },        },      },    },  },}

要求：

  • 支持 V4L2 输入、libx264 和 AAC 的 FFmpeg
  • 节点服务用户可读取的 /dev/video* 设备；在常见发行版上，请将该用户添加到 video 组
  • 使用默认 includeAudio: true 录制视频片段时，需要正常工作的 PulseAudio 服务器，或带有默认音源的 PipeWire PulseAudio 兼容层

Linux 会从 camera.list 返回具备拍摄能力且可读取的 V4L2 设备路径；FFmpeg 会探测每个 /dev/video* 候选项，并忽略元数据节点或仅输出节点。设备 position 为 unknown，因此未指定 deviceId 的朝向请求会生成一张或一段 unknown 位置的照片或视频片段，而不会声称来自前置或后置相机。主机有多个相机时，请使用 deviceId。camera.snap 使用 FFmpeg 输入预热来实现 delayMs，并在限制宽度的同时保持宽高比。camera.clip 会将麦克风音频录制为 MP4 音轨；OpenClaw 特意不提供独立的麦克风命令。

该插件使用 libx264 生成 MP4 视频，且不会静默更改编解码器。缺少所需输入或编码器的 FFmpeg 构建会返回 CAMERA_UNAVAILABLE。若照片或视频片段会超过 25MB 的 base64 载荷限制，则会以 PAYLOAD_TOO_LARGE 失败。

camera.snap 和 camera.clip 仍是危险命令。仅在确实要启用拍摄时才将它们添加到 gateway.nodes.allowCommands；仅启用插件并不会绕过 Gateway 网关策略。

安全性和实际限制

  • 相机和麦克风访问会触发常规的操作系统权限提示（并且需要在 Info.plist 中提供用途说明字符串）。
  • 视频片段最长限制为 60s，以避免节点载荷过大（base64 开销加上消息限制）。

macOS 屏幕视频（操作系统级）

对于_屏幕_视频（而非相机视频），请使用 macOS 配套应用：

bash
openclaw nodes screen record --node <id> --duration 10s --fps 15   # 输出保存路径

需要 macOS Screen Recording 权限（TCC）。

相关内容

Was this useful?
On this page

On this page