@gguf/claw 2026.2.1 → 2026.2.3

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-01T21:17:51Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b4d5f5ecbab6f70597cf1e1f9cc5f7f54681253bd747442db16cc681203b5813
+  source_path: nodes/camera.md
+  workflow: 15
+---
+
+# 相机捕获（智能体）
+
+OpenClaw 支持智能体工作流中的**相机捕获**：
+
+- **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
+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` 默认拍摄**两个**朝向，以便为智能体提供两个视角。
+- 输出文件是临时的（位于操作系统临时目录中），除非你自行构建包装器。
+
+## 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 伴侣应用提供一个复选框：
+
+- **设置 → 通用 → 允许相机**（`openclaw.cameraEnabled`）
+  - 默认：**关闭**
+  - 关闭时：相机请求返回"Camera disabled by user"。
+
+### CLI 辅助工具（节点调用）
+
+使用主 `openclaw` CLI 在 macOS 节点上调用相机命令。
+
+示例：
+
+```bash
+openclaw nodes camera list --node <id>            # 列出相机 ID
+openclaw nodes camera snap --node <id>            # 输出 MEDIA:<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          # 输出 MEDIA:<path>
+openclaw nodes camera clip --node <id> --duration-ms 3000      # 输出 MEDIA:<path>（旧版标志）
+openclaw nodes camera clip --node <id> --device-id <id>
+openclaw nodes camera clip --node <id> --no-audio
+```
+
+注意事项：
+
+- `openclaw nodes camera snap` 默认 `maxWidth=1600`，除非被覆盖。
+- 在 macOS 上，`camera.snap` 在预热/曝光稳定后等待 `delayMs`（默认 2000ms）再进行捕获。
+- 照片载荷会被重新压缩，以将 base64 控制在 5 MB 以内。
+
+## 安全性 + 实际限制
+
+- 相机和麦克风访问会触发常规的操作系统权限提示（且需要在 Info.plist 中添加用途说明字符串）。
+- 视频片段有长度上限（当前 `<= 60s`），以避免过大的节点载荷（base64 开销 + 消息大小限制）。
+
+## macOS 屏幕录制（操作系统级别）
+
+如需*屏幕*录制（非相机），请使用 macOS 伴侣应用：
+
+```bash
+openclaw nodes screen record --node <id> --duration 10s --fps 15   # 输出 MEDIA:<path>
+```
+
+注意事项：
+
+- 需要 macOS **屏幕录制**权限（TCC）。

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

@@ -0,0 +1,79 @@
+---
+read_when:
+  - 修改媒体处理管道或附件
+summary: 发送、Gateway网关和智能体回复的图片与媒体处理规则
+title: 图片与媒体支持
+x-i18n:
+  generated_at: "2026-02-01T21:17:54Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 971aed398ea01078efbad7a8a4bca17f2a975222a2c4db557565e4334c9450e0
+  source_path: nodes/images.md
+  workflow: 15
+---
+
+# 图片与媒体支持 — 2025-12-05
+
+WhatsApp 渠道通过 **Baileys Web** 运行。本文档记录了发送、Gateway网关和智能体回复的当前媒体处理规则。
+
+## 目标
+
+- 通过 `openclaw message send --media` 发送带可选说明文字的媒体。
+- 允许来自 Web 收件箱的自动回复在文本旁包含媒体。
+- 保持每种类型的限制合理且可预测。
+
+## CLI 接口
+
+- `openclaw message send --media <path-or-url> [--message <caption>]`
+  - `--media` 可选；说明文字可以为空，用于仅发送媒体。
+  - `--dry-run` 打印解析后的载荷；`--json` 输出 `{ channel, to, messageId, mediaUrl, caption }`。
+
+## WhatsApp Web 渠道行为
+
+- 输入：本地文件路径**或** HTTP(S) URL。
+- 流程：加载到 Buffer 中，检测媒体类型，并构建正确的载荷：
+  - **图片：** 调整大小并重新压缩为 JPEG（最大边 2048px），目标大小为 `agents.defaults.mediaMaxMb`（默认 5 MB），上限 6 MB。
+  - **音频/语音/视频：** 直通传输，上限 16 MB；音频作为语音消息发送（`ptt: true`）。
+  - **文档：** 其他所有类型，上限 100 MB，可用时保留文件名。
+- WhatsApp GIF 风格播放：发送带 `gifPlayback: true` 的 MP4（CLI：`--gif-playback`），使移动客户端内联循环播放。
+- MIME 检测优先使用魔术字节，其次是请求头，最后是文件扩展名。
+- 说明文字来自 `--message` 或 `reply.text`；允许空说明文字。
+- 日志：非详细模式显示 `↩️`/`✅`；详细模式包含大小和源路径/URL。
+
+## 自动回复管道
+
+- `getReplyFromConfig` 返回 `{ text?, mediaUrl?, mediaUrls? }`。
+- 当存在媒体时，Web 发送器使用与 `openclaw message send` 相同的管道解析本地路径或 URL。
+- 如果提供了多个媒体条目，则按顺序依次发送。
+
+## 入站媒体转命令 (Pi)
+
+- 当入站 Web 消息包含媒体时，OpenClaw 会下载到临时文件并暴露模板变量：
+  - `{{MediaUrl}}` 入站媒体的伪 URL。
+  - `{{MediaPath}}` 运行命令前写入的本地临时路径。
+- 当启用了每会话 Docker 沙箱时，入站媒体会被复制到沙箱工作区中，`MediaPath`/`MediaUrl` 会被重写为类似 `media/inbound/<filename>` 的相对路径。
+- 媒体理解（如果通过 `tools.media.*` 或共享的 `tools.media.models` 配置）在模板化之前运行，可以将 `[Image]`、`[Audio]` 和 `[Video]` 块插入 `Body`。
+  - 音频设置 `{{Transcript}}` 并使用转录文本进行命令解析，因此斜杠命令仍然有效。
+  - 视频和图片描述会保留说明文字用于命令解析。
+- 默认仅处理第一个匹配的图片/音频/视频附件；设置 `tools.media.<cap>.attachments` 可处理多个附件。
+
+## 限制与错误
+
+**出站发送上限（WhatsApp Web 发送）**
+
+- 图片：重新压缩后约 6 MB 上限。
+- 音频/语音/视频：16 MB 上限；文档：100 MB 上限。
+- 超大或不可读的媒体 → 日志中显示明确错误，回复将被跳过。
+
+**媒体理解上限（转录/描述）**
+
+- 图片默认：10 MB（`tools.media.image.maxBytes`）。
+- 音频默认：20 MB（`tools.media.audio.maxBytes`）。
+- 视频默认：50 MB（`tools.media.video.maxBytes`）。
+- 超大媒体会跳过理解处理，但回复仍会以原始正文发送。
+
+## 测试注意事项
+
+- 覆盖图片/音频/文档场景的发送 + 回复流程。
+- 验证图片的重新压缩（大小限制）和音频的语音消息标志。
+- 确保多媒体回复以顺序发送的方式展开。

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

@@ -0,0 +1,316 @@
+---
+read_when:
+  - 将 iOS/Android 节点配对到 Gateway网关
+  - 使用节点 canvas/相机为智能体提供上下文
+  - 添加新的节点命令或 CLI 辅助工具
+summary: 节点：配对、能力、权限，以及 canvas/相机/屏幕/系统的 CLI 辅助工具
+title: 节点
+x-i18n:
+  generated_at: "2026-02-01T21:18:35Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 7f7cc1934cfbb4176f0a7ce21371e51d9a9fb459dd73b8fce5a214b58877521f
+  source_path: nodes/index.md
+  workflow: 15
+---
+
+# 节点
+
+**节点**是一个伴侣设备（macOS/iOS/Android/无头），通过 **WebSocket**（与操作员相同的端口）以 `role: "node"` 连接到 Gateway网关，并通过 `node.invoke` 暴露命令接口（例如 `canvas.*`、`camera.*`、`system.*`）。协议详情：[Gateway网关协议](/gateway/protocol)。
+
+旧版传输：[Bridge 协议](/gateway/bridge-protocol)（TCP JSONL；当前节点已弃用/移除）。
+
+macOS 也可以在**节点模式**下运行：菜单栏应用连接到 Gateway网关的 WS 服务器，并将其本地 canvas/相机命令作为节点暴露（因此 `openclaw nodes …` 可以对该 Mac 使用）。
+
+注意事项：
+
+- 节点是**外围设备**，不是 Gateway网关。它们不运行 Gateway网关服务。
+- Telegram/WhatsApp 等消息到达的是 **Gateway网关**，而非节点。
+
+## 配对 + 状态
+
+**WS 节点使用设备配对。** 节点在 `connect` 时提供设备身份；Gateway网关为 `role: node` 创建设备配对请求。通过设备 CLI（或 UI）审批。
+
+快速 CLI：
+
+```bash
+openclaw devices list
+openclaw devices approve <requestId>
+openclaw devices reject <requestId>
+openclaw nodes status
+openclaw nodes describe --node <idOrNameOrIp>
+```
+
+注意事项：
+
+- `nodes status` 在设备配对角色包含 `node` 时将节点标记为**已配对**。
+- `node.pair.*`（CLI：`openclaw nodes pending/approve/reject`）是一个独立的 Gateway网关拥有的节点配对存储；它**不会**拦截 WS `connect` 握手。
+
+## 远程节点主机（system.run）
+
+当你的 Gateway网关运行在一台机器上而你希望命令在另一台机器上执行时，使用**节点主机**。模型仍然与 **Gateway网关** 通信；当选择 `host=node` 时，Gateway网关将 `exec` 调用转发给**节点主机**。
+
+### 各部分运行位置
+
+- **Gateway网关主机**：接收消息，运行模型，路由工具调用。
+- **节点主机**：在节点机器上执行 `system.run`/`system.which`。
+- **审批**：通过节点主机上的 `~/.openclaw/exec-approvals.json` 执行。
+
+### 启动节点主机（前台）
+
+在节点机器上：
+
+```bash
+openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"
+```
+
+### 启动节点主机（服务）
+
+```bash
+openclaw node install --host <gateway-host> --port 18789 --display-name "Build Node"
+openclaw node restart
+```
+
+### 配对 + 命名
+
+在 Gateway网关主机上：
+
+```bash
+openclaw nodes pending
+openclaw nodes approve <requestId>
+openclaw nodes list
+```
+
+命名选项：
+
+- 在 `openclaw node run` / `openclaw node install` 上使用 `--display-name`（持久保存在节点的 `~/.openclaw/node.json` 中）。
+- `openclaw nodes rename --node <id|name|ip> --name "Build Node"`（Gateway网关覆盖）。
+
+### 将命令加入允许列表
+
+执行审批是**按节点主机**的。从 Gateway网关添加允许列表条目：
+
+```bash
+openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/uname"
+openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/sw_vers"
+```
+
+审批存储在节点主机的 `~/.openclaw/exec-approvals.json` 中。
+
+### 将执行指向节点
+
+配置默认值（Gateway网关配置）：
+
+```bash
+openclaw config set tools.exec.host node
+openclaw config set tools.exec.security allowlist
+openclaw config set tools.exec.node "<id-or-name>"
+```
+
+或按会话设置：
+
+```
+/exec host=node security=allowlist node=<id-or-name>
+```
+
+设置后，任何 `host=node` 的 `exec` 调用都会在节点主机上运行（受节点允许列表/审批限制）。
+
+相关链接：
+
+- [节点主机 CLI](/cli/node)
+- [Exec 工具](/tools/exec)
+- [Exec 审批](/tools/exec-approvals)
+
+## 调用命令
+
+低级别（原始 RPC）：
+
+```bash
+openclaw nodes invoke --node <idOrNameOrIp> --command canvas.eval --params '{"javaScript":"location.href"}'
+```
+
+对于常见的"为智能体提供 MEDIA 附件"工作流，有更高级的辅助工具。
+
+## 截图（canvas 快照）
+
+如果节点正在显示 Canvas（WebView），`canvas.snapshot` 返回 `{ format, base64 }`。
+
+CLI 辅助工具（写入临时文件并输出 `MEDIA:<path>`）：
+
+```bash
+openclaw nodes canvas snapshot --node <idOrNameOrIp> --format png
+openclaw nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9
+```
+
+### Canvas 控制
+
+```bash
+openclaw nodes canvas present --node <idOrNameOrIp> --target https://example.com
+openclaw nodes canvas hide --node <idOrNameOrIp>
+openclaw nodes canvas navigate https://example.com --node <idOrNameOrIp>
+openclaw nodes canvas eval --node <idOrNameOrIp> --js "document.title"
+```
+
+注意事项：
+
+- `canvas present` 接受 URL 或本地文件路径（`--target`），以及可选的 `--x/--y/--width/--height` 用于定位。
+- `canvas eval` 接受内联 JS（`--js`）或位置参数。
+
+### A2UI（Canvas）
+
+```bash
+openclaw nodes canvas a2ui push --node <idOrNameOrIp> --text "Hello"
+openclaw nodes canvas a2ui push --node <idOrNameOrIp> --jsonl ./payload.jsonl
+openclaw nodes canvas a2ui reset --node <idOrNameOrIp>
+```
+
+注意事项：
+
+- 仅支持 A2UI v0.8 JSONL（v0.9/createSurface 会被拒绝）。
+
+## 照片 + 视频（节点相机）
+
+照片（`jpg`）：
+
+```bash
+openclaw nodes camera list --node <idOrNameOrIp>
+openclaw nodes camera snap --node <idOrNameOrIp>            # 默认：两个朝向（2 行 MEDIA 输出）
+openclaw nodes camera snap --node <idOrNameOrIp> --facing front
+```
+
+视频片段（`mp4`）：
+
+```bash
+openclaw nodes camera clip --node <idOrNameOrIp> --duration 10s
+openclaw nodes camera clip --node <idOrNameOrIp> --duration 3000 --no-audio
+```
+
+注意事项：
+
+- `canvas.*` 和 `camera.*` 要求节点处于**前台**（后台调用返回 `NODE_BACKGROUND_UNAVAILABLE`）。
+- 片段时长有上限（当前 `<= 60s`），以避免过大的 base64 载荷。
+- Android 会在可能时提示 `CAMERA`/`RECORD_AUDIO` 权限；拒绝权限时以 `*_PERMISSION_REQUIRED` 失败。
+
+## 屏幕录制（节点）
+
+节点暴露 `screen.record`（mp4）。示例：
+
+```bash
+openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10
+openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-audio
+```
+
+注意事项：
+
+- `screen.record` 要求节点应用处于前台。
+- Android 会在录制前显示系统屏幕捕获提示。
+- 屏幕录制上限为 `<= 60s`。
+- `--no-audio` 禁用麦克风捕获（iOS/Android 支持；macOS 使用系统捕获音频）。
+- 当有多个屏幕可用时，使用 `--screen <index>` 选择显示器。
+
+## 位置（节点）
+
+当设置中启用了位置功能时，节点暴露 `location.get`。
+
+CLI 辅助工具：
+
+```bash
+openclaw nodes location get --node <idOrNameOrIp>
+openclaw nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000
+```
+
+注意事项：
+
+- 位置功能**默认关闭**。
+- "始终"需要系统权限；后台获取为尽力而为。
+- 响应包含经纬度、精度（米）和时间戳。
+
+## 短信（Android 节点）
+
+当用户授予 **SMS** 权限且设备支持电话功能时，Android 节点可以暴露 `sms.send`。
+
+低级别调用：
+
+```bash
+openclaw nodes invoke --node <idOrNameOrIp> --command sms.send --params '{"to":"+15555550123","message":"Hello from OpenClaw"}'
+```
+
+注意事项：
+
+- 必须在 Android 设备上接受权限提示后，该功能才会被广播。
+- 没有电话功能的纯 Wi-Fi 设备不会广播 `sms.send`。
+
+## 系统命令（节点主机 / Mac 节点）
+
+macOS 节点暴露 `system.run`、`system.notify` 和 `system.execApprovals.get/set`。
+无头节点主机暴露 `system.run`、`system.which` 和 `system.execApprovals.get/set`。
+
+示例：
+
+```bash
+openclaw nodes run --node <idOrNameOrIp> -- echo "Hello from mac node"
+openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway网关 ready"
+```
+
+注意事项：
+
+- `system.run` 在载荷中返回 stdout/stderr/退出码。
+- `system.notify` 遵循 macOS 应用的通知权限状态。
+- `system.run` 支持 `--cwd`、`--env KEY=VAL`、`--command-timeout` 和 `--needs-screen-recording`。
+- `system.notify` 支持 `--priority <passive|active|timeSensitive>` 和 `--delivery <system|overlay|auto>`。
+- macOS 节点会丢弃 `PATH` 覆盖；无头节点主机仅在 `PATH` 前置于节点主机 PATH 时才接受。
+- 在 macOS 节点模式下，`system.run` 受 macOS 应用中的执行审批限制（设置 → 执行审批）。
+  询问/允许列表/完全访问的行为与无头节点主机相同；拒绝的提示返回 `SYSTEM_RUN_DENIED`。
+- 在无头节点主机上，`system.run` 受执行审批限制（`~/.openclaw/exec-approvals.json`）。
+
+## Exec 节点绑定
+
+当有多个节点可用时，你可以将 exec 绑定到特定节点。
+这会设置 `exec host=node` 的默认节点（可以按智能体覆盖）。
+
+全局默认：
+
+```bash
+openclaw config set tools.exec.node "node-id-or-name"
+```
+
+按智能体覆盖：
+
+```bash
+openclaw config get agents.list
+openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
+```
+
+取消设置以允许任意节点：
+
+```bash
+openclaw config unset tools.exec.node
+openclaw config unset agents.list[0].tools.exec.node
+```
+
+## 权限映射
+
+节点可能在 `node.list` / `node.describe` 中包含 `permissions` 映射，以权限名称为键（例如 `screenRecording`、`accessibility`），布尔值为值（`true` = 已授予）。
+
+## 无头节点主机（跨平台）
+
+OpenClaw 可以运行**无头节点主机**（无 UI），它连接到 Gateway网关 WebSocket 并暴露 `system.run` / `system.which`。这适用于 Linux/Windows 或在服务器旁运行一个最小节点。
+
+启动方式：
+
+```bash
+openclaw node run --host <gateway-host> --port 18789
+```
+
+注意事项：
+
+- 仍然需要配对（Gateway网关会显示节点审批提示）。
+- 节点主机将其节点 ID、令牌、显示名称和 Gateway网关连接信息存储在 `~/.openclaw/node.json` 中。
+- 执行审批通过 `~/.openclaw/exec-approvals.json` 在本地执行（参见[执行审批](/tools/exec-approvals)）。
+- 在 macOS 上，无头节点主机在伴侣应用执行主机可达时优先使用它，不可用时回退到本地执行。设置 `OPENCLAW_NODE_EXEC_HOST=app` 以要求使用应用，或设置 `OPENCLAW_NODE_EXEC_FALLBACK=0` 以禁用回退。
+- 当 Gateway网关 WS 使用 TLS 时，添加 `--tls` / `--tls-fingerprint`。
+
+## Mac 节点模式
+
+- macOS 菜单栏应用作为节点连接到 Gateway网关 WS 服务器（因此 `openclaw nodes …` 可以对该 Mac 使用）。
+- 在远程模式下，应用为 Gateway网关端口打开 SSH 隧道并连接到 `localhost`。

package/docs/zh-CN/nodes/location-command.md

@@ -0,0 +1,120 @@
+---
+read_when:
+  - 添加位置节点支持或权限界面
+  - 设计后台位置 + 推送流程
+summary: 节点的位置命令（location.get）、权限模式和后台行为
+title: 位置命令
+x-i18n:
+  generated_at: "2026-02-01T21:18:11Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 23124096256384d2b28157352b072309c61c970a20e009aac5ce4a8250dc3764
+  source_path: nodes/location-command.md
+  workflow: 15
+---
+
+# 位置命令（节点）
+
+## 简要说明
+
+- `location.get` 是一个节点命令（通过 `node.invoke`）。
+- 默认关闭。
+- 设置使用选择器：关闭 / 使用时 / 始终。
+- 单独的开关：精确位置。
+
+## 为什么用选择器（而不是简单开关）
+
+操作系统权限是多级的。我们可以在应用内提供选择器，但实际授权由操作系统决定。
+
+- iOS/macOS：用户可以在系统提示/设置中选择**使用时**或**始终**。应用可以请求升级，但操作系统可能要求进入设置。
+- Android：后台位置是独立的权限；在 Android 10+ 上通常需要进入设置流程。
+- 精确位置是独立的授权（iOS 14+ "精确"，Android "精确" vs "粗略"）。
+
+界面中的选择器驱动我们请求的模式；实际授权存储在操作系统设置中。
+
+## 设置模型
+
+每个节点设备：
+
+- `location.enabledMode`：`off | whileUsing | always`
+- `location.preciseEnabled`：bool
+
+界面行为：
+
+- 选择 `whileUsing` 请求前台权限。
+- 选择 `always` 首先确保 `whileUsing`，然后请求后台权限（如果需要则引导用户进入设置）。
+- 如果操作系统拒绝请求的级别，则回退到已授予的最高级别并显示状态。
+
+## 权限映射（node.permissions）
+
+可选。macOS 节点通过权限映射报告 `location`；iOS/Android 可能省略。
+
+## 命令：`location.get`
+
+通过 `node.invoke` 调用。
+
+参数（建议）：
+
+```json
+{
+  "timeoutMs": 10000,
+  "maxAgeMs": 15000,
+  "desiredAccuracy": "coarse|balanced|precise"
+}
+```
+
+响应载荷：
+
+```json
+{
+  "lat": 48.20849,
+  "lon": 16.37208,
+  "accuracyMeters": 12.5,
+  "altitudeMeters": 182.0,
+  "speedMps": 0.0,
+  "headingDeg": 270.0,
+  "timestamp": "2026-01-03T12:34:56.000Z",
+  "isPrecise": true,
+  "source": "gps|wifi|cell|unknown"
+}
+```
+
+错误（稳定错误码）：
+
+- `LOCATION_DISABLED`：选择器为关闭状态。
+- `LOCATION_PERMISSION_REQUIRED`：缺少请求模式所需的权限。
+- `LOCATION_BACKGROUND_UNAVAILABLE`：应用在后台运行但仅允许"使用时"。
+- `LOCATION_TIMEOUT`：未在规定时间内获取定位。
+- `LOCATION_UNAVAILABLE`：系统故障 / 无可用提供者。
+
+## 后台行为（未来）
+
+目标：即使节点在后台，模型也能请求位置，但仅在以下条件满足时：
+
+- 用户选择了**始终**。
+- 操作系统授予了后台位置权限。
+- 应用被允许在后台运行位置服务（iOS 后台模式 / Android 前台服务或特殊许可）。
+
+推送触发流程（未来）：
+
+1. Gateway网关向节点发送推送（静默推送或 FCM 数据）。
+2. 节点短暂唤醒并向设备请求位置。
+3. 节点将载荷转发给 Gateway网关。
+
+注意事项：
+
+- iOS：需要"始终"权限 + 后台位置模式。静默推送可能被限流；预期会有间歇性失败。
+- Android：后台位置可能需要前台服务；否则预期会被拒绝。
+
+## 模型/工具集成
+
+- 工具接口：`nodes` 工具添加 `location_get` 操作（需要节点）。
+- CLI：`openclaw nodes location get --node <id>`。
+- 智能体指南：仅在用户启用位置并了解范围时调用。
+
+## 界面文案（建议）
+
+- 关闭："位置共享已禁用。"
+- 使用时："仅在 OpenClaw 打开时共享。"
+- 始终："允许后台定位。需要系统权限。"
+- 精确："使用精确 GPS 定位。关闭后将共享大致位置。"