> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 摄像头捕获

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

所有摄像头访问都受每个平台上由用户控制的设置约束。

## 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 前台要求

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

### CLI 辅助工具

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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` 默认使用 `--facing both`，同时捕获前置和后置视角，以便为智能体提供两个视图；如果设置了 `--device-id`，请传入单一明确的朝向（设置 `--device-id` 时会拒绝 `both`）。输出文件是临时文件（位于操作系统临时目录中），除非你构建自己的封装器。

## 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 前台要求

与 `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`。
  * 有效载荷保护：原始 MP4 在 base64 编码前上限为 18MB；超大片段会以 `PAYLOAD_TOO_LARGE` 失败（减小 `durationMs` 后重试）。

## macOS 应用

### macOS 用户设置

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

* **设置 → 通用 → 允许摄像头**（`openclaw.cameraEnabled`）。
  * 默认值：**关闭**。
  * 关闭时：摄像头请求返回 `CAMERA_DISABLED: enable Camera in Settings`。

### CLI 辅助工具（节点调用）

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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> --duration-ms 3000   # prints saved 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`。
* `camera.snap` 在预热/曝光稳定后等待 `delayMs`（默认 2000ms，限制在 `[0, 10000]`）再捕获。
* 照片有效载荷会被重新压缩，使 base64 保持在 5MB 以下。

## 安全性 + 实际限制

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

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw nodes screen record --node <id> --duration 10s --fps 15   # prints saved path
```

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

## 相关

* [图像和媒体支持](/zh-CN/nodes/images)
* [媒体理解](/zh-CN/nodes/media-understanding)
* [位置命令](/zh-CN/nodes/location-command)