@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/logging.md

@@ -0,0 +1,329 @@
+---
+read_when:
+  - 你需要一个适合初学者的日志概述
+  - 你想配置日志级别或格式
+  - 你正在故障排除并需要快速找到日志
+summary: 日志概述：文件日志、控制台输出、CLI 跟踪和控制 UI
+title: 日志
+x-i18n:
+  generated_at: "2026-02-03T07:50:52Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 884fcf4a906adff34d546908e22abd283cb89fe0845076cf925c72384ec3556b
+  source_path: logging.md
+  workflow: 15
+---
+
+# 日志
+
+QuantumClaw 在两个地方记录日志：
+
+- **文件日志**（JSON 行）由 Gateway 网关写入。
+- **控制台输出**显示在终端和控制 UI 中。
+
+本页说明日志存放位置、如何读取日志以及如何配置日志级别和格式。
+
+## 日志存放位置
+
+默认情况下，Gateway 网关在以下位置写入滚动日志文件：
+
+`/tmp/quantumclaw/quantumclaw-YYYY-MM-DD.log`
+
+日期使用 Gateway 网关主机的本地时区。
+
+你可以在 `~/.quantumclaw/quantumclaw.json` 中覆盖此设置：
+
+```json
+{
+  "logging": {
+    "file": "/path/to/quantumclaw.log"
+  }
+}
+```
+
+## 如何读取日志
+
+### CLI：实时跟踪（推荐）
+
+使用 CLI 通过 RPC 跟踪 Gateway 网关日志文件：
+
+```bash
+quantumclaw logs --follow
+```
+
+输出模式：
+
+- **TTY 会话**：美观、彩色、结构化的日志行。
+- **非 TTY 会话**：纯文本。
+- `--json`：行分隔的 JSON（每行一个日志事件）。
+- `--plain`：在 TTY 会话中强制纯文本。
+- `--no-color`：禁用 ANSI 颜色。
+
+在 JSON 模式下，CLI 输出带 `type` 标签的对象：
+
+- `meta`：流元数据（文件、游标、大小）
+- `log`：解析的日志条目
+- `notice`：截断/轮转提示
+- `raw`：未解析的日志行
+
+如果 Gateway 网关无法访问，CLI 会打印一个简短提示运行：
+
+```bash
+quantumclaw doctor
+```
+
+### 控制 UI（Web）
+
+控制 UI 的**日志**标签页使用 `logs.tail` 跟踪相同的文件。
+参见 [/web/control-ui](/web/control-ui) 了解如何打开它。
+
+### 仅渠道日志
+
+要过滤渠道活动（WhatsApp/Telegram 等），使用：
+
+```bash
+quantumclaw channels logs --channel whatsapp
+```
+
+## 日志格式
+
+### 文件日志（JSONL）
+
+日志文件中的每一行都是一个 JSON 对象。CLI 和控制 UI 解析这些条目以渲染结构化输出（时间、级别、子系统、消息）。
+
+### 控制台输出
+
+控制台日志**感知 TTY**并格式化以提高可读性：
+
+- 子系统前缀（例如 `gateway/channels/whatsapp`）
+- 级别着色（info/warn/error）
+- 可选的紧凑或 JSON 模式
+
+控制台格式由 `logging.consoleStyle` 控制。
+
+## 配置日志
+
+所有日志配置都在 `~/.quantumclaw/quantumclaw.json` 的 `logging` 下。
+
+```json
+{
+  "logging": {
+    "level": "info",
+    "file": "/tmp/quantumclaw/quantumclaw-YYYY-MM-DD.log",
+    "consoleLevel": "info",
+    "consoleStyle": "pretty",
+    "redactSensitive": "tools",
+    "redactPatterns": ["sk-.*"]
+  }
+}
+```
+
+### 日志级别
+
+- `logging.level`：**文件日志**（JSONL）级别。
+- `logging.consoleLevel`：**控制台**详细程度级别。
+
+`--verbose` 仅影响控制台输出；它不改变文件日志级别。
+
+### 控制台样式
+
+`logging.consoleStyle`：
+
+- `pretty`：人类友好、彩色、带时间戳。
+- `compact`：更紧凑的输出（最适合长会话）。
+- `json`：每行 JSON（用于日志处理器）。
+
+### 脱敏
+
+工具摘要可以在敏感令牌输出到控制台之前对其进行脱敏：
+
+- `logging.redactSensitive`：`off` | `tools`（默认：`tools`）
+- `logging.redactPatterns`：用于覆盖默认集的正则表达式字符串列表
+
+脱敏仅影响**控制台输出**，不会改变文件日志。
+
+## 诊断 + OpenTelemetry
+
+诊断是用于模型运行**和**消息流遥测（webhooks、队列、会话状态）的结构化、机器可读事件。它们**不**替代日志；它们存在是为了向指标、追踪和其他导出器提供数据。
+
+诊断事件在进程内发出，但导出器仅在启用诊断 + 导出器插件时才附加。
+
+### OpenTelemetry 与 OTLP
+
+- **OpenTelemetry（OTel）**：追踪、指标和日志的数据模型 + SDK。
+- **OTLP**：用于将 OTel 数据导出到收集器/后端的线路协议。
+- QuantumClaw 目前通过 **OTLP/HTTP（protobuf）** 导出。
+
+### 导出的信号
+
+- **指标**：计数器 + 直方图（令牌使用、消息流、队列）。
+- **追踪**：模型使用 + webhook/消息处理的 span。
+- **日志**：启用 `diagnostics.otel.logs` 时通过 OTLP 导出。日志量可能很大；请注意 `logging.level` 和导出器过滤器。
+
+### 诊断事件目录
+
+模型使用：
+
+- `model.usage`：令牌、成本、持续时间、上下文、提供商/模型/渠道、会话 ID。
+
+消息流：
+
+- `webhook.received`：每渠道的 webhook 入口。
+- `webhook.processed`：webhook 已处理 + 持续时间。
+- `webhook.error`：webhook 处理程序错误。
+- `message.queued`：消息入队等待处理。
+- `message.processed`：结果 + 持续时间 + 可选错误。
+
+队列 + 会话：
+
+- `queue.lane.enqueue`：命令队列通道入队 + 深度。
+- `queue.lane.dequeue`：命令队列通道出队 + 等待时间。
+- `session.state`：会话状态转换 + 原因。
+- `session.stuck`：会话卡住警告 + 持续时间。
+- `run.attempt`：运行重试/尝试元数据。
+- `diagnostic.heartbeat`：聚合计数器（webhooks/队列/会话）。
+
+### 启用诊断（无导出器）
+
+如果你希望诊断事件可用于插件或自定义接收器，使用此配置：
+
+```json
+{
+  "diagnostics": {
+    "enabled": true
+  }
+}
+```
+
+### 诊断标志（定向日志）
+
+使用标志在不提高 `logging.level` 的情况下开启额外的定向调试日志。
+标志不区分大小写，支持通配符（例如 `telegram.*` 或 `*`）。
+
+```json
+{
+  "diagnostics": {
+    "flags": ["telegram.http"]
+  }
+}
+```
+
+环境变量覆盖（一次性）：
+
+```
+QUANTUMCLAW_DIAGNOSTICS=telegram.http,telegram.payload
+```
+
+注意：
+
+- 标志日志进入标准日志文件（与 `logging.file` 相同）。
+- 输出仍根据 `logging.redactSensitive` 进行脱敏。
+- 完整指南：[/diagnostics/flags](/diagnostics/flags)。
+
+### 导出到 OpenTelemetry
+
+诊断可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。这适用于任何接受 OTLP/HTTP 的 OpenTelemetry 收集器/后端。
+
+```json
+{
+  "plugins": {
+    "allow": ["diagnostics-otel"],
+    "entries": {
+      "diagnostics-otel": {
+        "enabled": true
+      }
+    }
+  },
+  "diagnostics": {
+    "enabled": true,
+    "otel": {
+      "enabled": true,
+      "endpoint": "http://otel-collector:4318",
+      "protocol": "http/protobuf",
+      "serviceName": "quantumclaw-gateway",
+      "traces": true,
+      "metrics": true,
+      "logs": true,
+      "sampleRate": 0.2,
+      "flushIntervalMs": 60000
+    }
+  }
+}
+```
+
+注意：
+
+- 你也可以使用 `quantumclaw plugins enable diagnostics-otel` 启用插件。
+- `protocol` 目前仅支持 `http/protobuf`。`grpc` 被忽略。
+- 指标包括令牌使用、成本、上下文大小、运行持续时间和消息流计数器/直方图（webhooks、队列、会话状态、队列深度/等待）。
+- 追踪/指标可以通过 `traces` / `metrics` 切换（默认：开启）。启用时，追踪包括模型使用 span 加上 webhook/消息处理 span。
+- 当你的收集器需要认证时设置 `headers`。
+- 支持的环境变量：`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_SERVICE_NAME`、`OTEL_EXPORTER_OTLP_PROTOCOL`。
+
+### 导出的指标（名称 + 类型）
+
+模型使用：
+
+- `quantumclaw.tokens`（计数器，属性：`quantumclaw.token`、`quantumclaw.channel`、`quantumclaw.provider`、`quantumclaw.model`）
+- `quantumclaw.cost.usd`（计数器，属性：`quantumclaw.channel`、`quantumclaw.provider`、`quantumclaw.model`）
+- `quantumclaw.run.duration_ms`（直方图，属性：`quantumclaw.channel`、`quantumclaw.provider`、`quantumclaw.model`）
+- `quantumclaw.context.tokens`（直方图，属性：`quantumclaw.context`、`quantumclaw.channel`、`quantumclaw.provider`、`quantumclaw.model`）
+
+消息流：
+
+- `quantumclaw.webhook.received`（计数器，属性：`quantumclaw.channel`、`quantumclaw.webhook`）
+- `quantumclaw.webhook.error`（计数器，属性：`quantumclaw.channel`、`quantumclaw.webhook`）
+- `quantumclaw.webhook.duration_ms`（直方图，属性：`quantumclaw.channel`、`quantumclaw.webhook`）
+- `quantumclaw.message.queued`（计数器，属性：`quantumclaw.channel`、`quantumclaw.source`）
+- `quantumclaw.message.processed`（计数器，属性：`quantumclaw.channel`、`quantumclaw.outcome`）
+- `quantumclaw.message.duration_ms`（直方图，属性：`quantumclaw.channel`、`quantumclaw.outcome`）
+
+队列 + 会话：
+
+- `quantumclaw.queue.lane.enqueue`（计数器，属性：`quantumclaw.lane`）
+- `quantumclaw.queue.lane.dequeue`（计数器，属性：`quantumclaw.lane`）
+- `quantumclaw.queue.depth`（直方图，属性：`quantumclaw.lane` 或 `quantumclaw.channel=heartbeat`）
+- `quantumclaw.queue.wait_ms`（直方图，属性：`quantumclaw.lane`）
+- `quantumclaw.session.state`（计数器，属性：`quantumclaw.state`、`quantumclaw.reason`）
+- `quantumclaw.session.stuck`（计数器，属性：`quantumclaw.state`）
+- `quantumclaw.session.stuck_age_ms`（直方图，属性：`quantumclaw.state`）
+- `quantumclaw.run.attempt`（计数器，属性：`quantumclaw.attempt`）
+
+### 导出的 span（名称 + 关键属性）
+
+- `quantumclaw.model.usage`
+  - `quantumclaw.channel`、`quantumclaw.provider`、`quantumclaw.model`
+  - `quantumclaw.sessionKey`、`quantumclaw.sessionId`
+  - `quantumclaw.tokens.*`（input/output/cache_read/cache_write/total）
+- `quantumclaw.webhook.processed`
+  - `quantumclaw.channel`、`quantumclaw.webhook`、`quantumclaw.chatId`
+- `quantumclaw.webhook.error`
+  - `quantumclaw.channel`、`quantumclaw.webhook`、`quantumclaw.chatId`、`quantumclaw.error`
+- `quantumclaw.message.processed`
+  - `quantumclaw.channel`、`quantumclaw.outcome`、`quantumclaw.chatId`、`quantumclaw.messageId`、`quantumclaw.sessionKey`、`quantumclaw.sessionId`、`quantumclaw.reason`
+- `quantumclaw.session.stuck`
+  - `quantumclaw.state`、`quantumclaw.ageMs`、`quantumclaw.queueDepth`、`quantumclaw.sessionKey`、`quantumclaw.sessionId`
+
+### 采样 + 刷新
+
+- 追踪采样：`diagnostics.otel.sampleRate`（0.0–1.0，仅根 span）。
+- 指标导出间隔：`diagnostics.otel.flushIntervalMs`（最小 1000ms）。
+
+### 协议说明
+
+- OTLP/HTTP 端点可以通过 `diagnostics.otel.endpoint` 或 `OTEL_EXPORTER_OTLP_ENDPOINT` 设置。
+- 如果端点已包含 `/v1/traces` 或 `/v1/metrics`，则按原样使用。
+- 如果端点已包含 `/v1/logs`，则按原样用于日志。
+- `diagnostics.otel.logs` 为主日志器输出启用 OTLP 日志导出。
+
+### 日志导出行为
+
+- OTLP 日志使用与写入 `logging.file` 相同的结构化记录。
+- 遵守 `logging.level`（文件日志级别）。控制台脱敏**不**适用于 OTLP 日志。
+- 高流量安装应优先使用 OTLP 收集器采样/过滤。
+
+## 故障排除提示
+
+- **Gateway 网关无法访问？** 先运行 `quantumclaw doctor`。
+- **日志为空？** 检查 Gateway 网关是否正在运行并写入 `logging.file` 中的文件路径。
+- **需要更多细节？** 将 `logging.level` 设置为 `debug` 或 `trace` 并重试。

package/docs/zh-CN/network.md

@@ -0,0 +1,59 @@
+---
+read_when:
+  - 你需要了解网络架构和安全概述
+  - 你正在调试本地访问、tailnet 访问或配对问题
+  - 你想要获取网络文档的权威列表
+summary: 网络中心：Gateway 网关接口、配对、设备发现和安全
+title: 网络
+x-i18n:
+  generated_at: "2026-02-03T10:07:45Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 0fe4e7dbc8ddea312c8f3093af9b6bc71d9ae4007df76ae24b85889871933bc8
+  source_path: network.md
+  workflow: 15
+---
+
+# 网络中心
+
+本中心汇集了 QuantumClaw 如何在 localhost、局域网和 tailnet 之间连接、配对和保护设备的核心文档。
+
+## 核心模型
+
+- [Gateway 网关架构](/concepts/architecture)
+- [Gateway 网关协议](/gateway/protocol)
+- [Gateway 网关运维手册](/gateway)
+- [Web 接口 + 绑定模式](/web)
+
+## 配对 + 身份
+
+- [配对概述（私信 + 节点）](/channels/pairing)
+- [Gateway 网关拥有的节点配对](/gateway/pairing)
+- [Devices CLI（配对 + token 轮换）](/cli/devices)
+- [Pairing CLI（私信审批）](/cli/pairing)
+
+本地信任：
+
+- 本地连接（loopback 或 Gateway 网关主机自身的 tailnet 地址）可以自动批准配对，以保持同主机用户体验的流畅性。
+- 非本地的 tailnet/局域网客户端仍需要显式的配对批准。
+
+## 设备发现 + 传输协议
+
+- [设备发现与传输协议](/gateway/discovery)
+- [Bonjour / mDNS](/gateway/bonjour)
+- [远程访问（SSH）](/gateway/remote)
+- [Tailscale](/gateway/tailscale)
+
+## 节点 + 传输协议
+
+- [节点概述](/nodes)
+- [桥接协议（旧版节点）](/gateway/bridge-protocol)
+- [节点运维手册：iOS](/platforms/ios)
+- [节点运维手册：Android](/platforms/android)
+
+## 安全
+
+- [安全概述](/gateway/security)
+- [Gateway 网关配置参考](/gateway/configuration)
+- [故障排除](/gateway/troubleshooting)
+- [Doctor](/gateway/doctor)

package/docs/zh-CN/nodes/audio.md

@@ -0,0 +1,120 @@
+---
+read_when:
+  - 更改音频转录或媒体处理方式
+summary: 入站音频/语音消息如何被下载、转录并注入回复
+title: 音频与语音消息
+x-i18n:
+  generated_at: "2026-02-01T21:17:35Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b926c47989ab0d1ee1fb8ae6372c51d27515b53d6fefe211a85856d372f14569
+  source_path: nodes/audio.md
+  workflow: 15
+---
+
+# 音频 / 语音消息 — 2026-01-17
+
+## 已支持的功能
+
+- **媒体理解（音频）**：如果音频理解已启用（或自动检测），QuantumClaw 会：
+  1. 找到第一个音频附件（本地路径或 URL），如有需要则下载。
+  2. 在发送给每个模型条目之前执行 `maxBytes` 限制。
+  3. 按顺序运行第一个符合条件的模型条目（提供商或 CLI）。
+  4. 如果失败或跳过（大小/超时），则尝试下一个条目。
+  5. 成功后，将 `Body` 替换为 `[Audio]` 块并设置 `{{Transcript}}`。
+- **命令解析**：转录成功时，`CommandBody`/`RawBody` 会设置为转录文本，因此斜杠命令仍然有效。
+- **详细日志**：在 `--verbose` 模式下，我们会在转录运行和替换正文时记录日志。
+
+## 自动检测（默认）
+
+如果你**未配置模型**且 `tools.media.audio.enabled` **未**设置为 `false`，QuantumClaw 会按以下顺序自动检测，并在找到第一个可用选项时停止：
+
+1. **本地 CLI**（如已安装）
+   - `sherpa-onnx-offline`（需要 `SHERPA_ONNX_MODEL_DIR` 包含 encoder/decoder/joiner/tokens）
+   - `whisper-cli`（来自 `whisper-cpp`；使用 `WHISPER_CPP_MODEL` 或内置的 tiny 模型）
+   - `whisper`（Python CLI；自动下载模型）
+2. **Gemini CLI**（`gemini`）使用 `read_many_files`
+3. **提供商密钥**（OpenAI → Groq → Deepgram → Google）
+
+要禁用自动检测，请设置 `tools.media.audio.enabled: false`。
+要自定义，请设置 `tools.media.audio.models`。
+注意：二进制检测在 macOS/Linux/Windows 上采用尽力而为的方式；请确保 CLI 在 `PATH` 中（我们会展开 `~`），或通过完整命令路径设置显式 CLI 模型。
+
+## 配置示例
+
+### 提供商 + CLI 回退（OpenAI + Whisper CLI）
+
+```json5
+{
+  tools: {
+    media: {
+      audio: {
+        enabled: true,
+        maxBytes: 20971520,
+        models: [
+          { provider: "openai", model: "gpt-4o-mini-transcribe" },
+          {
+            type: "cli",
+            command: "whisper",
+            args: ["--model", "base", "{{MediaPath}}"],
+            timeoutSeconds: 45,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+### 仅提供商 + 作用域控制
+
+```json5
+{
+  tools: {
+    media: {
+      audio: {
+        enabled: true,
+        scope: {
+          default: "allow",
+          rules: [{ action: "deny", match: { chatType: "group" } }],
+        },
+        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
+      },
+    },
+  },
+}
+```
+
+### 仅提供商（Deepgram）
+
+```json5
+{
+  tools: {
+    media: {
+      audio: {
+        enabled: true,
+        models: [{ provider: "deepgram", model: "nova-3" }],
+      },
+    },
+  },
+}
+```
+
+## 注意事项与限制
+
+- 提供商认证遵循标准的模型认证顺序（认证配置文件、环境变量、`models.providers.*.apiKey`）。
+- 当使用 `provider: "deepgram"` 时，Deepgram 会读取 `DEEPGRAM_API_KEY`。
+- Deepgram 设置详情：[Deepgram（音频转录）](/providers/deepgram)。
+- 音频提供商可以通过 `tools.media.audio` 覆盖 `baseUrl`、`headers` 和 `providerOptions`。
+- 默认大小限制为 20MB（`tools.media.audio.maxBytes`）。超大音频会跳过该模型并尝试下一个条目。
+- 音频的默认 `maxChars` **未设置**（完整转录文本）。设置 `tools.media.audio.maxChars` 或每个条目的 `maxChars` 来裁剪输出。
+- OpenAI 自动检测默认使用 `gpt-4o-mini-transcribe`；设置 `model: "gpt-4o-transcribe"` 可获得更高准确度。
+- 使用 `tools.media.audio.attachments` 处理多条语音消息（`mode: "all"` + `maxAttachments`）。
+- 转录文本可在模板中通过 `{{Transcript}}` 使用。
+- CLI 标准输出有上限（5MB）；请保持 CLI 输出简洁。
+
+## 常见陷阱
+
+- 作用域规则采用首次匹配优先。`chatType` 会被规范化为 `direct`、`group` 或 `room`。
+- 确保你的 CLI 以退出码 0 退出并输出纯文本；JSON 格式需要通过 `jq -r .text` 进行转换。
+- 保持合理的超时时间（`timeoutSeconds`，默认 60 秒），以避免阻塞回复队列。

package/docs/zh-CN/nodes/camera.md

@@ -0,0 +1,162 @@
+---
+read_when:
+  - 在 iOS 节点或 macOS 上添加或修改相机捕获
+  - 扩展智能体可访问的 MEDIA 临时文件工作流
+summary: 用于智能体的相机捕获（iOS 节点 + macOS 应用）：照片（jpg）和短视频片段（mp4）
+title: 相机捕获
+x-i18n:
+  generated_at: "2026-02-03T07:50:55Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b4d5f5ecbab6f70597cf1e1f9cc5f7f54681253bd747442db16cc681203b5813
+  source_path: nodes/camera.md
+  workflow: 15
+---
+
+# 相机捕获（智能体）
+
+QuantumClaw 支持用于智能体工作流的**相机捕获**：
+
+- **iOS 节点**（通过 Gateway 网关配对）：通过 `node.invoke` 捕获**照片**（`jpg`）或**短视频片段**（`mp4`，可选音频）。
+- **Android 节点**（通过 Gateway 网关配对）：通过 `node.invoke` 捕获**照片**（`jpg`）或**短视频片段**（`mp4`，可选音频）。
+- **macOS 应用**（通过 Gateway 网关的节点）：通过 `node.invoke` 捕获**照片**（`jpg`）或**短视频片段**（`mp4`，可选音频）。
+
+所有相机访问都受**用户控制的设置**限制。
+
+## iOS 节点
+
+### 用户设置（默认开启）
+
+- iOS 设置标签页 → **相机** → **允许相机**（`camera.enabled`）
+  - 默认：**开启**（缺少键时视为启用）。
+  - 关闭时：`camera.*` 命令返回 `CAMERA_DISABLED`。
+
+### 命令（通过 Gateway 网关 `node.invoke`）
+
+- `camera.list`
+  - 响应载荷：
+    - `devices`：`{ id, name, position, deviceType }` 数组
+
+- `camera.snap`
+  - 参数：
+    - `facing`：`front|back`（默认：`front`）
+    - `maxWidth`：数字（可选；iOS 节点默认 `1600`）
+    - `quality`：`0..1`（可选；默认 `0.9`）
+    - `format`：当前为 `jpg`
+    - `delayMs`：数字（可选；默认 `0`）
+    - `deviceId`：字符串（可选；来自 `camera.list`）
+  - 响应载荷：
+    - `format: "jpg"`
+    - `base64: "<...>"`
+    - `width`、`height`
+  - 载荷保护：照片会重新压缩以保持 base64 载荷小于 5 MB。
+
+- `camera.clip`
+  - 参数：
+    - `facing`：`front|back`（默认：`front`）
+    - `durationMs`：数字（默认 `3000`，上限 `60000`）
+    - `includeAudio`：布尔值（默认 `true`）
+    - `format`：当前为 `mp4`
+    - `deviceId`：字符串（可选；来自 `camera.list`）
+  - 响应载荷：
+    - `format: "mp4"`
+    - `base64: "<...>"`
+    - `durationMs`
+    - `hasAudio`
+
+### 前台要求
+
+与 `canvas.*` 类似，iOS 节点仅允许在**前台**执行 `camera.*` 命令。后台调用返回 `NODE_BACKGROUND_UNAVAILABLE`。
+
+### CLI 辅助工具（临时文件 + MEDIA）
+
+获取附件最简单的方法是通过 CLI 辅助工具，它将解码的媒体写入临时文件并打印 `MEDIA:<path>`。
+
+示例：
+
+```bash
+quantumclaw nodes camera snap --node <id>               # default: both front + back (2 MEDIA lines)
+quantumclaw nodes camera snap --node <id> --facing front
+quantumclaw nodes camera clip --node <id> --duration 3000
+quantumclaw nodes camera clip --node <id> --no-audio
+```
+
+注意事项：
+
+- `nodes camera snap` 默认拍摄**两个**方向以给智能体提供两个视角。
+- 输出文件是临时的（在操作系统临时目录中），除非你构建自己的包装器。
+
+## Android 节点
+
+### 用户设置（默认开启）
+
+- Android 设置页 → **相机** → **允许相机**（`camera.enabled`）
+  - 默认：**开启**（缺少键时视为启用）。
+  - 关闭时：`camera.*` 命令返回 `CAMERA_DISABLED`。
+
+### 权限
+
+- Android 需要运行时权限：
+  - `CAMERA` 用于 `camera.snap` 和 `camera.clip`。
+  - `RECORD_AUDIO` 用于 `includeAudio=true` 时的 `camera.clip`。
+
+如果缺少权限，应用会在可能时提示；如果被拒绝，`camera.*` 请求会失败并返回 `*_PERMISSION_REQUIRED` 错误。
+
+### 前台要求
+
+与 `canvas.*` 类似，Android 节点仅允许在**前台**执行 `camera.*` 命令。后台调用返回 `NODE_BACKGROUND_UNAVAILABLE`。
+
+### 载荷保护
+
+照片会重新压缩以保持 base64 载荷小于 5 MB。
+
+## macOS 应用
+
+### 用户设置（默认关闭）
+
+macOS 配套应用暴露一个复选框：
+
+- **设置 → 通用 → 允许相机**（`quantumclaw.cameraEnabled`）
+  - 默认：**关闭**
+  - 关闭时：相机请求返回"用户已禁用相机"。
+
+### CLI 辅助工具（节点调用）
+
+使用主 `quantumclaw` CLI 在 macOS 节点上调用相机命令。
+
+示例：
+
+```bash
+quantumclaw nodes camera list --node <id>            # list camera ids
+quantumclaw nodes camera snap --node <id>            # prints MEDIA:<path>
+quantumclaw nodes camera snap --node <id> --max-width 1280
+quantumclaw nodes camera snap --node <id> --delay-ms 2000
+quantumclaw nodes camera snap --node <id> --device-id <id>
+quantumclaw nodes camera clip --node <id> --duration 10s          # prints MEDIA:<path>
+quantumclaw nodes camera clip --node <id> --duration-ms 3000      # prints MEDIA:<path> (legacy flag)
+quantumclaw nodes camera clip --node <id> --device-id <id>
+quantumclaw nodes camera clip --node <id> --no-audio
+```
+
+注意事项：
+
+- `quantumclaw nodes camera snap` 默认 `maxWidth=1600`，除非被覆盖。
+- 在 macOS 上，`camera.snap` 在预热/曝光稳定后等待 `delayMs`（默认 2000ms）再捕获。
+- 照片载荷会重新压缩以保持 base64 小于 5 MB。
+
+## 安全性 + 实际限制
+
+- 相机和麦克风访问会触发通常的操作系统权限提示（并需要 Info.plist 中的使用说明字符串）。
+- 视频片段有上限（当前 `<= 60s`）以避免过大的节点载荷（base64 开销 + 消息限制）。
+
+## macOS 屏幕视频（操作系统级别）
+
+对于*屏幕*视频（非相机），使用 macOS 配套应用：
+
+```bash
+quantumclaw nodes screen record --node <id> --duration 10s --fps 15   # prints MEDIA:<path>
+```
+
+注意事项：
+
+- 需要 macOS **屏幕录制**权限（TCC）。