> ## 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** 和 **Linux** 節點上，為代理工作流程擷取相機畫面：透過閘道 `node.invoke` 拍攝相片（`jpg`）或短片（`mp4`，可選擇包含音訊）。

所有相機存取均受各平台上由使用者控制的設定限制。

## iOS 節點

### iOS 使用者設定

* iOS Settings 分頁 → **Camera** → **Allow Camera**（`camera.enabled`）。
  * 預設值：**開啟**（缺少此鍵時視為已啟用）。
  * 關閉時：`camera.*` 命令會傳回 `CAMERA_DISABLED`。

### iOS 命令（透過閘道 `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`。

### 命令列介面輔助工具

取得媒體檔案最簡單的方式是使用命令列介面輔助工具；它會將解碼後的媒體寫入暫存檔，並印出儲存路徑。

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw nodes camera snap --node <id>                 # 預設：同時使用前置與後置相機（2 行 MEDIA）
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 Settings 面板 → **Camera** → **Allow Camera**（`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 命令（透過閘道 `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`（選用；未知識別碼會以 `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`。

### 命令列介面輔助工具（節點叫用）

使用主要的 `openclaw` 命令列介面，在 macOS 節點上叫用相機命令。

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw nodes camera list --node <id>                     # 列出相機識別碼
openclaw nodes camera snap --node <id>                     # 印出儲存路徑
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       # 印出儲存路徑
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 節點外掛會為命令列介面 `openclaw node` 服務新增相機擷取功能。它可在無頭主機上運作，且不需要 Linux 桌面應用程式。

相機存取預設為關閉。請在外掛項目下啟用，然後重新啟動節點服務，讓其閘道公告重新建置：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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`；僅啟用此外掛不會略過閘道政策。

## 安全性與實務限制

* 相機和麥克風存取會觸發一般的作業系統權限提示（並且需要 `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   # 印出儲存路徑
```

需要 macOS **Screen Recording** 權限（TCC）。

## 相關內容

* [圖片與媒體支援](/zh-TW/nodes/images)
* [媒體理解](/zh-TW/nodes/media-understanding)
* [位置命令](/zh-TW/nodes/location-command)