跳转至

相机拍摄

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 是 camera.snap 和 camera.clip 都必需的权限;缺失/被拒绝的权限会返回 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 辅助工具(node invoke)

使用主 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 绝对平移/俯仰或变焦控制的 USB 相机实现。它使用与捕获相同的 允许相机 设置。其他节点平台不会通告这些命令。

始终传入由 camera.list 返回的显式 deviceId。OpenClaw 从不为物理移动选择默认相机。

  • camera.ptz.status 读取当前位置而不移动相机。请求:{ "deviceId": "<camera-id>" }。
  • 响应仅在 axes 下包含可执行的 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 要求至少一个有限轴值。省略的轴保持不变,且变焦的移动增量是百分点。home 恢复设备通告的默认值;当 canHome 为 false 时,它在不移动相机的情况下返回 CAMERA_PTZ_UNSUPPORTED。Mac 应用会将请求值钳制并吸附到相机的范围和分辨率;响应返回操作后的 state,并在 adjusted 中列出已更改的请求字段。请求不支持的轴会返回 CAMERA_PTZ_AXIS_UNSUPPORTED。

两个 PTZ 命令都会短暂打开实时相机流,因为受支持的相机仅在流式传输时处理 UVC 控制。这会在该期间激活相机及其隐私指示器,包括当 camera.ptz.status 仅读取位置时。帧不会被保留,也不会生成照片、视频或文件。

平移/俯仰和变焦使用独立的硬件写入,无法原子化。OpenClaw 通过新的控制连接验证最终位置。如果后续写入或最终状态读取失败,或者某个轴未能在相机报告的分辨率内到达请求位置,CAMERA_PTZ_PARTIAL 会指明已确认的控制组,在可读时包含独立观察到的状态,并告知调用方在重试前运行 camera.ptz.status。位置失败还会报告请求值和观察值;请检查视频流是否到达相机,并禁用可能覆盖 UVC 控制的相机端 AI 取景或跟踪。

camera.ptz.control 是危险命令,在操作员显式将其添加到 gateway.nodes.commands.allow 之前保持禁用:

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

仅允许条目不会扩大现有节点批准。在更新的 Mac 重新连接并声明 PTZ 控制后,运行 openclaw nodes pending,然后使用 openclaw nodes approve <requestId> 批准扩大后的范围。

在 agent 的 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 使用 FFmpeg 输入预热作为 delayMs,并在限制宽度时保持宽高比。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