@termix-it/cryptoclaw 1.0.0

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

@@ -0,0 +1,120 @@
+---
+read_when:
+  - 添加位置节点支持或权限 UI
+  - 设计后台位置 + 推送流程
+summary: 节点的位置命令（location.get）、权限模式和后台行为
+title: 位置命令
+x-i18n:
+  generated_at: "2026-02-03T07:50:59Z"
+  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 "粗略"）。
+
+UI 中的选择器驱动我们请求的模式；实际授权存在于操作系统设置中。
+
+## 设置模型
+
+每个节点设备：
+
+- `location.enabledMode`：`off | whileUsing | always`
+- `location.preciseEnabled`：bool
+
+UI 行为：
+
+- 选择 `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>`。
+- 智能体指南：仅在用户启用位置并理解范围时调用。
+
+## UX 文案（建议）
+
+- 关闭："位置共享已禁用。"
+- 使用时："仅当 OpenClaw 打开时。"
+- 始终："允许后台位置。需要系统权限。"
+- 精确："使用精确 GPS 位置。关闭以共享大致位置。"

package/docs/zh-CN/nodes/media-understanding.md

@@ -0,0 +1,380 @@
+---
+read_when:
+  - 设计或重构媒体理解
+  - 调优入站音频/视频/图片预处理
+summary: 入站图片/音频/视频理解（可选），带提供商 + CLI 回退
+title: 媒体理解
+x-i18n:
+  generated_at: "2026-02-03T07:51:40Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: f6c575662b7fcbf0b62c46e3fdfa4cdb7cfd455513097e4a2cdec8a34cbdbd48
+  source_path: nodes/media-understanding.md
+  workflow: 15
+---
+
+# 媒体理解（入站）— 2026-01-17
+
+OpenClaw 可以在回复流程运行之前**摘要入站媒体**（图片/音频/视频）。它会自动检测本地工具或提供商密钥是否可用，并且可以禁用或自定义。如果理解关闭，模型仍然会像往常一样接收原始文件/URL。
+
+## 目标
+
+- 可选：将入站媒体预先消化为短文本，以便更快路由 + 更好的命令解析。
+- 保留原始媒体传递给模型（始终）。
+- 支持**提供商 API** 和 **CLI 回退**。
+- 允许多个模型并按顺序回退（错误/大小/超时）。
+
+## 高层行为
+
+1. 收集入站附件（`MediaPaths`、`MediaUrls`、`MediaTypes`）。
+2. 对于每个启用的能力（图片/音频/视频），根据策略选择附件（默认：**第一个**）。
+3. 选择第一个符合条件的模型条目（大小 + 能力 + 认证）。
+4. 如果模型失败或媒体太大，**回退到下一个条目**。
+5. 成功时：
+   - `Body` 变为 `[Image]`、`[Audio]` 或 `[Video]` 块。
+   - 音频设置 `{{Transcript}}`；命令解析在有标题文本时使用标题文本，否则使用转录。
+   - 标题作为 `User text:` 保留在块内。
+
+如果理解失败或被禁用，**回复流程继续**使用原始正文 + 附件。
+
+## 配置概述
+
+`tools.media` 支持**共享模型**加上每能力覆盖：
+
+- `tools.media.models`：共享模型列表（使用 `capabilities` 来限定）。
+- `tools.media.image` / `tools.media.audio` / `tools.media.video`：
+  - 默认值（`prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`）
+  - 提供商覆盖（`baseUrl`、`headers`、`providerOptions`）
+  - 通过 `tools.media.audio.providerOptions.deepgram` 配置 Deepgram 音频选项
+  - 可选的**每能力 `models` 列表**（优先于共享模型）
+  - `attachments` 策略（`mode`、`maxAttachments`、`prefer`）
+  - `scope`（可选的按渠道/聊天类型/会话键限定）
+- `tools.media.concurrency`：最大并发能力运行数（默认 **2**）。
+
+```json5
+{
+  tools: {
+    media: {
+      models: [
+        /* 共享列表 */
+      ],
+      image: {
+        /* 可选覆盖 */
+      },
+      audio: {
+        /* 可选覆盖 */
+      },
+      video: {
+        /* 可选覆盖 */
+      },
+    },
+  },
+}
+```
+
+### 模型条目
+
+每个 `models[]` 条目可以是**提供商**或 **CLI**：
+
+```json5
+{
+  type: "provider", // 省略时默认
+  provider: "openai",
+  model: "gpt-5.2",
+  prompt: "Describe the image in <= 500 chars.",
+  maxChars: 500,
+  maxBytes: 10485760,
+  timeoutSeconds: 60,
+  capabilities: ["image"], // 可选，用于多模态条目
+  profile: "vision-profile",
+  preferredProfile: "vision-fallback",
+}
+```
+
+```json5
+{
+  type: "cli",
+  command: "gemini",
+  args: [
+    "-m",
+    "gemini-3-flash",
+    "--allowed-tools",
+    "read_file",
+    "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
+  ],
+  maxChars: 500,
+  maxBytes: 52428800,
+  timeoutSeconds: 120,
+  capabilities: ["video", "image"],
+}
+```
+
+CLI 模板还可以使用：
+
+- `{{MediaDir}}`（包含媒体文件的目录）
+- `{{OutputDir}}`（为本次运行创建的临时目录）
+- `{{OutputBase}}`（临时文件基础路径，无扩展名）
+
+## 默认值和限制
+
+推荐默认值：
+
+- `maxChars`：图片/视频为 **500**（简短，适合命令）
+- `maxChars`：音频**不设置**（完整转录，除非你设置限制）
+- `maxBytes`：
+  - 图片：**10MB**
+  - 音频：**20MB**
+  - 视频：**50MB**
+
+规则：
+
+- 如果媒体超过 `maxBytes`，该模型被跳过，**尝试下一个模型**。
+- 如果模型返回超过 `maxChars`，输出被截断。
+- `prompt` 默认为简单的"Describe the {media}."加上 `maxChars` 指导（仅图片/视频）。
+- 如果 `<capability>.enabled: true` 但未配置模型，当提供商支持该能力时，OpenClaw 尝试**活动的回复模型**。
+
+### 自动检测媒体理解（默认）
+
+如果 `tools.media.<capability>.enabled` **未**设置为 `false` 且你没有配置模型，OpenClaw 按以下顺序自动检测并**在第一个可用选项处停止**：
+
+1. **本地 CLI**（仅音频；如果已安装）
+   - `sherpa-onnx-offline`（需要带有 encoder/decoder/joiner/tokens 的 `SHERPA_ONNX_MODEL_DIR`）
+   - `whisper-cli`（`whisper-cpp`；使用 `WHISPER_CPP_MODEL` 或捆绑的 tiny 模型）
+   - `whisper`（Python CLI；自动下载模型）
+2. **Gemini CLI**（`gemini`）使用 `read_many_files`
+3. **提供商密钥**
+   - 音频：OpenAI → Groq → Deepgram → Google
+   - 图片：OpenAI → Anthropic → Google → MiniMax
+   - 视频：Google
+
+要禁用自动检测，设置：
+
+```json5
+{
+  tools: {
+    media: {
+      audio: {
+        enabled: false,
+      },
+    },
+  },
+}
+```
+
+注意：二进制文件检测在 macOS/Linux/Windows 上是尽力而为的；确保 CLI 在 `PATH` 上（我们会展开 `~`），或设置带有完整命令路径的显式 CLI 模型。
+
+## 能力（可选）
+
+如果你设置了 `capabilities`，该条目仅对这些媒体类型运行。对于共享列表，OpenClaw 可以推断默认值：
+
+- `openai`、`anthropic`、`minimax`：**图片**
+- `google`（Gemini API）：**图片 + 音频 + 视频**
+- `groq`：**音频**
+- `deepgram`：**音频**
+
+对于 CLI 条目，**显式设置 `capabilities`** 以避免意外匹配。如果你省略 `capabilities`，该条目对它出现的列表都符合条件。
+
+## 提供商支持矩阵（OpenClaw 集成）
+
+| 能力 | 提供商集成                                     | 说明                                    |
+| ---- | ---------------------------------------------- | --------------------------------------- |
+| 图片 | OpenAI / Anthropic / Google / 其他通过 `pi-ai` | 注册表中任何支持图片的模型都可用。      |
+| 音频 | OpenAI、Groq、Deepgram、Google                 | 提供商转录（Whisper/Deepgram/Gemini）。 |
+| 视频 | Google（Gemini API）                           | 提供商视频理解。                        |
+
+## 推荐提供商
+
+**图片**
+
+- 如果支持图片，优先使用你的活动模型。
+- 良好的默认值：`openai/gpt-5.2`、`anthropic/claude-opus-4-5`、`google/gemini-3-pro-preview`。
+
+**音频**
+
+- `openai/gpt-4o-mini-transcribe`、`groq/whisper-large-v3-turbo` 或 `deepgram/nova-3`。
+- CLI 回退：`whisper-cli`（whisper-cpp）或 `whisper`。
+- Deepgram 设置：[Deepgram（音频转录）](/providers/deepgram)。
+
+**视频**
+
+- `google/gemini-3-flash-preview`（快速）、`google/gemini-3-pro-preview`（更丰富）。
+- CLI 回退：`gemini` CLI（支持对视频/音频使用 `read_file`）。
+
+## 附件策略
+
+每能力的 `attachments` 控制处理哪些附件：
+
+- `mode`：`first`（默认）或 `all`
+- `maxAttachments`：限制处理数量（默认 **1**）
+- `prefer`：`first`、`last`、`path`、`url`
+
+当 `mode: "all"` 时，输出标记为 `[Image 1/2]`、`[Audio 2/2]` 等。
+
+## 配置示例
+
+### 1) 共享模型列表 + 覆盖
+
+```json5
+{
+  tools: {
+    media: {
+      models: [
+        { provider: "openai", model: "gpt-5.2", capabilities: ["image"] },
+        {
+          provider: "google",
+          model: "gemini-3-flash-preview",
+          capabilities: ["image", "audio", "video"],
+        },
+        {
+          type: "cli",
+          command: "gemini",
+          args: [
+            "-m",
+            "gemini-3-flash",
+            "--allowed-tools",
+            "read_file",
+            "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
+          ],
+          capabilities: ["image", "video"],
+        },
+      ],
+      audio: {
+        attachments: { mode: "all", maxAttachments: 2 },
+      },
+      video: {
+        maxChars: 500,
+      },
+    },
+  },
+}
+```
+
+### 2) 仅音频 + 视频（图片关闭）
+
+```json5
+{
+  tools: {
+    media: {
+      audio: {
+        enabled: true,
+        models: [
+          { provider: "openai", model: "gpt-4o-mini-transcribe" },
+          {
+            type: "cli",
+            command: "whisper",
+            args: ["--model", "base", "{{MediaPath}}"],
+          },
+        ],
+      },
+      video: {
+        enabled: true,
+        maxChars: 500,
+        models: [
+          { provider: "google", model: "gemini-3-flash-preview" },
+          {
+            type: "cli",
+            command: "gemini",
+            args: [
+              "-m",
+              "gemini-3-flash",
+              "--allowed-tools",
+              "read_file",
+              "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
+            ],
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+### 3) 可选图片理解
+
+```json5
+{
+  tools: {
+    media: {
+      image: {
+        enabled: true,
+        maxBytes: 10485760,
+        maxChars: 500,
+        models: [
+          { provider: "openai", model: "gpt-5.2" },
+          { provider: "anthropic", model: "claude-opus-4-5" },
+          {
+            type: "cli",
+            command: "gemini",
+            args: [
+              "-m",
+              "gemini-3-flash",
+              "--allowed-tools",
+              "read_file",
+              "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
+            ],
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+### 4) 多模态单条目（显式能力）
+
+```json5
+{
+  tools: {
+    media: {
+      image: {
+        models: [
+          {
+            provider: "google",
+            model: "gemini-3-pro-preview",
+            capabilities: ["image", "video", "audio"],
+          },
+        ],
+      },
+      audio: {
+        models: [
+          {
+            provider: "google",
+            model: "gemini-3-pro-preview",
+            capabilities: ["image", "video", "audio"],
+          },
+        ],
+      },
+      video: {
+        models: [
+          {
+            provider: "google",
+            model: "gemini-3-pro-preview",
+            capabilities: ["image", "video", "audio"],
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+## 状态输出
+
+当媒体理解运行时，`/status` 包含一行简短摘要：
+
+```
+📎 Media: image ok (openai/gpt-5.2) · audio skipped (maxBytes)
+```
+
+这显示每能力的结果以及适用时选择的提供商/模型。
+
+## 注意事项
+
+- 理解是**尽力而为**的。错误不会阻止回复。
+- 即使理解被禁用，附件仍然传递给模型。
+- 使用 `scope` 限制理解运行的位置（例如仅私信）。
+
+## 相关文档
+
+- [配置](/gateway/configuration)
+- [图片和媒体支持](/nodes/images)

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

@@ -0,0 +1,97 @@
+---
+read_when:
+  - 在 macOS/iOS/Android 上实现 Talk 模式
+  - 更改语音/TTS/中断行为
+summary: Talk 模式：使用 ElevenLabs TTS 进行连续语音对话
+title: Talk 模式
+x-i18n:
+  generated_at: "2026-02-03T10:07:59Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: ecbc3701c9e9502970cf13227fedbc9714d13668d8f4f3988fef2a4d68116a42
+  source_path: nodes/talk.md
+  workflow: 15
+---
+
+# Talk 模式
+
+Talk 模式是一个连续的语音对话循环：
+
+1. 监听语音
+2. 将转录文本发送到模型（main 会话，chat.send）
+3. 等待响应
+4. 通过 ElevenLabs 朗读（流式播放）
+
+## 行为（macOS）
+
+- Talk 模式启用时显示**常驻悬浮窗**。
+- **监听 → 思考 → 朗读**阶段转换。
+- **短暂停顿**（静音窗口）后，当前转录文本被发送。
+- 回复被**写入 WebChat**（与打字相同）。
+- **语音中断**（默认开启）：如果用户在助手朗读时开始说话，我们会停止播放并记录中断时间戳供下一个提示使用。
+
+## 回复中的语音指令
+
+助手可以在回复前添加**单行 JSON** 来控制语音：
+
+```json
+{ "voice": "<voice-id>", "once": true }
+```
+
+规则：
+
+- 仅适用于第一个非空行。
+- 未知键会被忽略。
+- `once: true` 仅适用于当前回复。
+- 没有 `once` 时，该语音成为 Talk 模式的新默认值。
+- JSON 行在 TTS 播放前会被移除。
+
+支持的键：
+
+- `voice` / `voice_id` / `voiceId`
+- `model` / `model_id` / `modelId`
+- `speed`、`rate`（WPM）、`stability`、`similarity`、`style`、`speakerBoost`
+- `seed`、`normalize`、`lang`、`output_format`、`latency_tier`
+- `once`
+
+## 配置（`~/.openclaw/openclaw.json`）
+
+```json5
+{
+  talk: {
+    voiceId: "elevenlabs_voice_id",
+    modelId: "eleven_v3",
+    outputFormat: "mp3_44100_128",
+    apiKey: "elevenlabs_api_key",
+    interruptOnSpeech: true,
+  },
+}
+```
+
+默认值：
+
+- `interruptOnSpeech`：true
+- `voiceId`：回退到 `ELEVENLABS_VOICE_ID` / `SAG_VOICE_ID`（或当 API 密钥可用时使用第一个 ElevenLabs 语音）
+- `modelId`：未设置时默认为 `eleven_v3`
+- `apiKey`：回退到 `ELEVENLABS_API_KEY`（或 Gateway 网关 shell profile（如果可用））
+- `outputFormat`：macOS/iOS 上默认为 `pcm_44100`，Android 上默认为 `pcm_24000`（设置 `mp3_*` 以强制 MP3 流式传输）
+
+## macOS UI
+
+- 菜单栏切换：**Talk**
+- 配置标签页：**Talk Mode** 组（voice id + 中断开关）
+- 悬浮窗：
+  - **监听**：云朵随麦克风电平脉动
+  - **思考**：下沉动画
+  - **朗读**：辐射圆环
+  - 点击云朵：停止朗读
+  - 点击 X：退出 Talk 模式
+
+## 注意事项
+
+- 需要语音 + 麦克风权限。
+- 使用 `chat.send` 针对会话键 `main`。
+- TTS 使用带有 `ELEVENLABS_API_KEY` 的 ElevenLabs 流式 API，并在 macOS/iOS/Android 上进行增量播放以降低延迟。
+- `eleven_v3` 的 `stability` 验证为 `0.0`、`0.5` 或 `1.0`；其他模型接受 `0..1`。
+- 设置时 `latency_tier` 验证为 `0..4`。
+- Android 支持 `pcm_16000`、`pcm_22050`、`pcm_24000` 和 `pcm_44100` 输出格式，用于低延迟 AudioTrack 流式传输。

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

@@ -0,0 +1,72 @@
+---
+read_when:
+  - 更改语音唤醒词行为或默认值
+  - 添加需要唤醒词同步的新节点平台
+summary: 全局语音唤醒词（Gateway 网关拥有）及其如何跨节点同步
+title: 语音唤醒
+x-i18n:
+  generated_at: "2026-02-03T07:51:10Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: eb34f52dfcdc3fc1ae088ae1f621f245546d3cf388299fbeea62face61788c37
+  source_path: nodes/voicewake.md
+  workflow: 15
+---
+
+# 语音唤醒（全局唤醒词）
+
+OpenClaw 将**唤醒词作为单一全局列表**，由 **Gateway 网关**拥有。
+
+- **没有**每节点的自定义唤醒词。
+- **任何节点/应用 UI 都可以编辑**列表；更改由 Gateway 网关持久化并广播给所有人。
+- 每个设备仍保留自己的**语音唤醒启用/禁用**开关（本地用户体验 + 权限不同）。
+
+## 存储（Gateway 网关主机）
+
+唤醒词存储在 Gateway 网关机器上：
+
+- `~/.openclaw/settings/voicewake.json`
+
+结构：
+
+```json
+{ "triggers": ["openclaw", "claude", "computer"], "updatedAtMs": 1730000000000 }
+```
+
+## 协议
+
+### 方法
+
+- `voicewake.get` → `{ triggers: string[] }`
+- `voicewake.set`，参数 `{ triggers: string[] }` → `{ triggers: string[] }`
+
+注意事项：
+
+- 触发词会被规范化（修剪空格、删除空值）。空列表回退到默认值。
+- 为安全起见会强制执行限制（数量/长度上限）。
+
+### 事件
+
+- `voicewake.changed` 载荷 `{ triggers: string[] }`
+
+接收者：
+
+- 所有 WebSocket 客户端（macOS 应用、WebChat 等）
+- 所有已连接的节点（iOS/Android），以及节点连接时作为初始"当前状态"推送。
+
+## 客户端行为
+
+### macOS 应用
+
+- 使用全局列表来控制 `VoiceWakeRuntime` 触发器。
+- 在语音唤醒设置中编辑"触发词"会调用 `voicewake.set`，然后依赖广播保持其他客户端同步。
+
+### iOS 节点
+
+- 使用全局列表进行 `VoiceWakeManager` 触发检测。
+- 在设置中编辑唤醒词会调用 `voicewake.set`（通过 Gateway 网关 WS），同时保持本地唤醒词检测的响应性。
+
+### Android 节点
+
+- 在设置中暴露唤醒词编辑器。
+- 通过 Gateway 网关 WS 调用 `voicewake.set`，使编辑在所有地方同步。