跳转至

摄像头拍摄

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

当拍摄请求包含 deviceId 时，所选相机必须与该 ID 完全匹配。未知 ID 将直接失败，而不会从其他相机拍摄；运行 camera.list 可刷新设备 ID，相机重新连接后设备 ID 会发生变化。

macOS 应用还可以对受支持的 USB UVC 相机进行物理平移、倾斜和变焦操作。PTZ 移动的是相机硬件本身；它不会旋转、裁剪或以其他方式转换已拍摄的图像。

在每个平台上，所有相机访问权限均受用户可控设置的管控。

iOS 节点

iOS 用户设置

  • iOS 设置标签页 → 相机 → 允许相机（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 前台运行要求

iOS 节点仅允许在前台执行 camera.* 命令。后台调用将返回 NODE_BACKGROUND_UNAVAILABLE。

CLI 辅助工具

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

openclaw nodes camera snap --node <id>                 # default: one node-selected photo
openclaw nodes camera snap --node <id> --facing front
openclaw nodes camera snap --node <id> --facing both   # front then back (2 saved paths)
openclaw nodes camera clip --node <id> --duration 10s
openclaw nodes camera clip --node <id> --no-audio

--duration 接受纯毫秒数字（3000）或带单位后缀的值（10s、1m、1h30m）。默认值为 3000（3 秒）。

不带 --facing 时，nodes camera snap 使用节点默认相机拍摄一张照片，并将保存的产物标记为 unknown。在非 Linux 节点上，--facing both 会先拍摄前置再拍摄后置，并打印两个保存路径。--device-id 在不带 --facing 时有效；在非 Linux 节点上，它不能与 --facing both 组合使用。Linux 始终发送一个不带 facing 的请求，并将产物标记为 unknown，无论是否指定 --facing。除非你构建自己的包装器，否则输出文件是临时的（位于操作系统临时目录中）。

Android 节点

Android 用户设置

  • Android 设置面板 → 相机 → 允许相机（camera.enabled）。
  • 全新安装默认关闭。 早于该设置存在的现有安装会被迁移为开启，这样升级后不会静默丢失原本可用的相机访问权限。
  • 关闭时：camera.* 命令返回 CAMERA_DISABLED: enable Camera in Settings。

权限

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

应用会在可能的情况下提示授予运行时权限。

Android 前台运行要求

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。
  • 负载保护：原始 MP4 在 base64 编码前上限为 18MB；超大的片段将返回 PAYLOAD_TOO_LARGE 失败（请减小 durationMs 后重试）。

macOS 应用

macOS 用户设置

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

  • 设置 → 通用 → 允许相机（openclaw.cameraEnabled）。
  • 默认值：关闭。
  • 关闭时：相机请求返回 CAMERA_DISABLED: enable Camera in Settings。

CLI 辅助工具（节点调用）

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

openclaw nodes camera list --node <id>                     # list camera ids
openclaw nodes camera snap --node <id>                     # prints saved 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 saved path
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 以下。

如果 macOS 外接摄像头以竖屏方向启动照片会话，OpenClaw 会在存在对应格式时，选择一种已公布的横屏格式，其尺寸转置且编码相同。已是横屏的格式、内置摄像头格式以及 Continuity Camera 格式均保持不变。若没有完全对应的格式，或摄像头无法重新配置，拍摄将保持协商后的格式。--max-width 仍然只限制返回的 JPEG 宽度；它不会选择摄像头格式。

macOS 物理 PTZ

物理 PTZ 由 Mac 应用为暴露标准 UVC 绝对 pan/tilt 或 zoom 控制的 USB 摄像头实现。它使用与拍摄相同的 Allow Camera 设置。其他节点平台不公布这些命令。

始终传入 camera.list 返回的显式 deviceId。OpenClaw 绝不会为物理移动选择默认摄像头。

  • camera.ptz.status 在不移动摄像头的情况下读取当前位置。请求：{ "deviceId": "<camera-id>" }。
  • 响应在 axes 下仅包含可执行的 pan、tilt 和 zoom 轴。
  • Pan 和 tilt 值的单位是度。Zoom 值的单位是百分比。
  • 每个轴报告 current、min、max、step、unit、canSet 和 canMove。仅当摄像头成功报告设备默认值时，default 才会出现。
  • 仅当所有对外暴露且可执行的轴都有真实的设备公布默认值时，canHome 才为 true，此时才能尝试完整的归位计划。
  • camera.ptz.control 更改摄像头硬件。其支持的操作如下：
  • { "deviceId": "<camera-id>", "operation": "set", "target": { "panDegrees": 10, "tiltDegrees": -5, "zoomPercent": 40 } }
  • { "deviceId": "<camera-id>", "operation": "move", "delta": { "panDegrees": 2, "zoomPercent": -5 } }
  • { "deviceId": "<camera-id>", "operation": "home" }

set 和 move 至少需要一个有穷的轴值。省略的轴保持不变，move 中 zoom 的增量以百分点为单位。home 恢复设备公布默认值；当 canHome 为 false 时，它返回 CAMERA_PTZ_UNSUPPORTED 且不移动摄像头。Mac 应用会将请求值限制并对齐到摄像头的范围和分辨率；响应返回操作后的 state，并在 adjusted 中列出被更改的请求字段。请求不支持的轴会返回 CAMERA_PTZ_AXIS_UNSUPPORTED。

两个 PTZ 命令都会短暂打开实时摄像头流，因为受支持的摄像头仅在流式传输期间提供 UVC 控制服务。这会在该期间激活摄像头及其隐私指示灯，包括 camera.ptz.status 仅读取位置时也是如此。帧不会被保留，也不会生成任何照片、视频或文件。

Pan/tilt 和 zoom 使用独立的硬件写入操作，无法保证原子性。OpenClaw 会通过一条全新的控制连接验证最终位置。如果后续写入或最终状态读取失败，或者某个轴未能在摄像头报告的分辨率范围内到达请求位置，CAMERA_PTZ_PARTIAL 会列出已确认的控制组，在可读取时包含独立观测到的状态，并告知调用方在重试前先运行 camera.ptz.status。位置失败还会报告请求值和观测值；请检查是否有视频流到达摄像头，并禁用可能覆盖 UVC 控制的摄像头端 AI 构图或跟踪功能。

camera.ptz.control 属于危险命令，在操作员将其显式添加到 gateway.nodes.commands.allow 之前，它始终保持未启用状态：

{
  gateway: {
    nodes: {
      commands: { allow: ["camera.ptz.control"] },
    },
  },
}

仅添加 allow 条目并不会扩展现有的节点批准范围。在更新后的 Mac 重新连接并声明支持 PTZ 控制后，运行 openclaw nodes pending，然后使用 openclaw nodes approve <requestId> 批准扩展后的能力面。

在智能体的 nodes 工具中，使用 action: "camera_ptz"、选定的 Mac 节点、deviceId 以及 ptzOperation: "status" | "set" | "move" | "home"。轴输入为 panDegrees、tiltDegrees 和 zoomPercent。

Linux 节点主机

捆绑的 Linux Node 插件为 CLI 的 openclaw node 服务增加了摄像头拍摄功能。它可在无头主机上运行，且不需要 Linux 桌面应用。

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

{
  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 在 delayMs 期间使用 FFmpeg 输入预热，并在限制宽度的同时保持宽高比。camera.clip 将麦克风音频录制为 MP4 音轨；OpenClaw 有意不暴露独立的麦克风命令。

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

camera.snap 和 camera.clip 仍属于危险命令。仅在您打算启用拍摄时，才将它们添加到 gateway.nodes.commands.allow；仅启用插件并不会绕过 Gateway 策略。

安全与实际限制

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

macOS 屏幕视频（系统级）

对于_屏幕_视频（非摄像头），请使用 macOS 配套工具：

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

需要 macOS 屏幕录制 权限（TCC）。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw