@termix-it/cryptoclaw 1.0.0

package/docs/zh-CN/gateway/background-process.md

@@ -0,0 +1,100 @@
+---
+read_when:
+  - 添加或修改后台 exec 行为
+  - 调试长时间运行的 exec 任务
+summary: 后台 exec 执行和进程管理
+title: 后台 Exec 和 Process 工具
+x-i18n:
+  generated_at: "2026-02-03T10:05:51Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: e11a7d74a75000d6882f703693c2c49a2ecd3e730b6ec2b475ac402abde9e465
+  source_path: gateway/background-process.md
+  workflow: 15
+---
+
+# 后台 Exec + Process 工具
+
+OpenClaw 通过 `exec` 工具运行 shell 命令，并将长时间运行的任务保存在内存中。`process` 工具管理这些后台会话。
+
+## exec 工具
+
+关键参数：
+
+- `command`（必填）
+- `yieldMs`（默认 10000）：在此延迟后自动转为后台运行
+- `background`（布尔值）：立即转为后台运行
+- `timeout`（秒，默认 1800）：在此超时后终止进程
+- `elevated`（布尔值）：如果启用/允许提权模式，则在宿主机上运行
+- 需要真实 TTY？设置 `pty: true`。
+- `workdir`、`env`
+
+行为：
+
+- 前台运行直接返回输出。
+- 当转为后台运行（显式或超时）时，工具返回 `status: "running"` + `sessionId` 和一小段尾部输出。
+- 输出保存在内存中，直到会话被轮询或清除。
+- 如果 `process` 工具被禁用，`exec` 将同步运行并忽略 `yieldMs`/`background`。
+
+## 子进程桥接
+
+当在 exec/process 工具之外生成长时间运行的子进程时（例如 CLI 重新生成或 Gateway 网关辅助程序），请附加子进程桥接辅助程序，以便终止信号被转发，监听器在退出/错误时被分离。这可以避免在 systemd 上产生孤立进程，并保持跨平台的关闭行为一致。
+
+环境变量覆盖：
+
+- `PI_BASH_YIELD_MS`：默认 yield 时间（毫秒）
+- `PI_BASH_MAX_OUTPUT_CHARS`：内存输出上限（字符）
+- `OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS`：每个流的待处理 stdout/stderr 上限（字符）
+- `PI_BASH_JOB_TTL_MS`：已完成会话的 TTL（毫秒，限制在 1 分钟至 3 小时之间）
+
+配置（推荐）：
+
+- `tools.exec.backgroundMs`（默认 10000）
+- `tools.exec.timeoutSec`（默认 1800）
+- `tools.exec.cleanupMs`（默认 1800000）
+- `tools.exec.notifyOnExit`（默认 true）：当后台 exec 退出时，将系统事件加入队列并请求心跳。
+
+## process 工具
+
+操作：
+
+- `list`：正在运行和已完成的会话
+- `poll`：获取会话的新输出（同时报告退出状态）
+- `log`：读取聚合输出（支持 `offset` + `limit`）
+- `write`：发送 stdin（`data`，可选 `eof`）
+- `kill`：终止后台会话
+- `clear`：从内存中移除已完成的会话
+- `remove`：如果正在运行则终止，否则清除已完成的会话
+
+注意事项：
+
+- 只有后台会话会在内存中列出/保留。
+- 会话在进程重启时会丢失（无磁盘持久化）。
+- 会话日志只有在你运行 `process poll/log` 且工具结果被记录时才会保存到聊天历史。
+- `process` 按智能体隔离；它只能看到该智能体启动的会话。
+- `process list` 包含派生的 `name`（命令动词 + 目标）以便快速浏览。
+- `process log` 使用基于行的 `offset`/`limit`（省略 `offset` 以获取最后 N 行）。
+
+## 示例
+
+运行长时间任务并稍后轮询：
+
+```json
+{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }
+```
+
+```json
+{ "tool": "process", "action": "poll", "sessionId": "<id>" }
+```
+
+立即在后台启动：
+
+```json
+{ "tool": "exec", "command": "npm run build", "background": true }
+```
+
+发送 stdin：
+
+```json
+{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }
+```

package/docs/zh-CN/gateway/bonjour.md

@@ -0,0 +1,174 @@
+---
+read_when:
+  - 在 macOS/iOS 上调试 Bonjour 设备发现问题时
+  - 更改 mDNS 服务类型、TXT 记录或设备发现用户体验时
+summary: Bonjour/mDNS 设备发现 + 调试（Gateway 网关信标、客户端和常见故障模式）
+title: Bonjour 设备发现
+x-i18n:
+  generated_at: "2026-02-03T07:47:48Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 47569da55f0c0523bd5ff05275dc95ccb52f75638193cfbdb4eaaa162aadf08c
+  source_path: gateway/bonjour.md
+  workflow: 15
+---
+
+# Bonjour / mDNS 设备发现
+
+OpenClaw 使用 Bonjour（mDNS / DNS‑SD）作为**仅限局域网的便捷方式**来发现
+活跃的 Gateway 网关（WebSocket 端点）。这是尽力而为的，**不能**替代 SSH 或
+基于 Tailnet 的连接。
+
+## 通过 Tailscale 的广域 Bonjour（单播 DNS‑SD）
+
+如果节点和 Gateway 网关在不同的网络上，多播 mDNS 无法跨越
+边界。你可以通过切换到基于 Tailscale 的**单播 DNS‑SD**
+（"广域 Bonjour"）来保持相同的设备发现用户体验。
+
+概要步骤：
+
+1. 在 Gateway 网关主机上运行 DNS 服务器（可通过 Tailnet 访问）。
+2. 在专用区域下发布 `_openclaw-gw._tcp` 的 DNS‑SD 记录
+   （示例：`openclaw.internal.`）。
+3. 配置 Tailscale **分割 DNS**，使你选择的域名通过该
+   DNS 服务器为客户端（包括 iOS）解析。
+
+OpenClaw 支持任何发现域名；`openclaw.internal.` 只是一个示例。
+iOS/Android 节点同时浏览 `local.` 和你配置的广域域名。
+
+### Gateway 网关配置（推荐）
+
+```json5
+{
+  gateway: { bind: "tailnet" }, // 仅 tailnet（推荐）
+  discovery: { wideArea: { enabled: true } }, // 启用广域 DNS-SD 发布
+}
+```
+
+### 一次性 DNS 服务器设置（Gateway 网关主机）
+
+```bash
+openclaw dns setup --apply
+```
+
+这会安装 CoreDNS 并配置它：
+
+- 仅在 Gateway 网关的 Tailscale 接口上监听 53 端口
+- 从 `~/.openclaw/dns/<domain>.db` 提供你选择的域名服务（示例：`openclaw.internal.`）
+
+从 Tailnet 连接的机器上验证：
+
+```bash
+dns-sd -B _openclaw-gw._tcp openclaw.internal.
+dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short
+```
+
+### Tailscale DNS 设置
+
+在 Tailscale 管理控制台中：
+
+- 添加指向 Gateway 网关 Tailnet IP 的名称服务器（UDP/TCP 53）。
+- 添加分割 DNS，使你的发现域名使用该名称服务器。
+
+一旦客户端接受 Tailnet DNS，iOS 节点就可以在
+你的发现域名中浏览 `_openclaw-gw._tcp`，无需多播。
+
+### Gateway 网关监听器安全（推荐）
+
+Gateway 网关 WS 端口（默认 `18789`）默认绑定到 loopback。对于局域网/Tailnet
+访问，请明确绑定并保持认证启用。
+
+对于仅 Tailnet 的设置：
+
+- 在 `~/.openclaw/openclaw.json` 中设置 `gateway.bind: "tailnet"`。
+- 重启 Gateway 网关（或重启 macOS 菜单栏应用）。
+
+## 什么在广播
+
+只有 Gateway 网关广播 `_openclaw-gw._tcp`。
+
+## 服务类型
+
+- `_openclaw-gw._tcp` — Gateway 网关传输信标（被 macOS/iOS/Android 节点使用）。
+
+## TXT 键（非机密提示）
+
+Gateway 网关广播小型非机密提示以方便 UI 流程：
+
+- `role=gateway`
+- `displayName=<友好名称>`
+- `lanHost=<hostname>.local`
+- `gatewayPort=<port>`（Gateway 网关 WS + HTTP）
+- `gatewayTls=1`（仅当 TLS 启用时）
+- `gatewayTlsSha256=<sha256>`（仅当 TLS 启用且指纹可用时）
+- `canvasPort=<port>`（仅当画布主机启用时；默认 `18793`）
+- `sshPort=<port>`（未覆盖时默认为 22）
+- `transport=gateway`
+- `cliPath=<path>`（可选；可运行的 `openclaw` 入口点的绝对路径）
+- `tailnetDns=<magicdns>`（当 Tailnet 可用时的可选提示）
+
+## 在 macOS 上调试
+
+有用的内置工具：
+
+- 浏览实例：
+  ```bash
+  dns-sd -B _openclaw-gw._tcp local.
+  ```
+- 解析单个实例（替换 `<instance>`）：
+  ```bash
+  dns-sd -L "<instance>" _openclaw-gw._tcp local.
+  ```
+
+如果浏览有效但解析失败，你通常遇到的是局域网策略或
+mDNS 解析器问题。
+
+## 在 Gateway 网关日志中调试
+
+Gateway 网关会写入滚动日志文件（启动时打印为
+`gateway log file: ...`）。查找 `bonjour:` 行，特别是：
+
+- `bonjour: advertise failed ...`
+- `bonjour: ... name conflict resolved` / `hostname conflict resolved`
+- `bonjour: watchdog detected non-announced service ...`
+
+## 在 iOS 节点上调试
+
+iOS 节点使用 `NWBrowser` 来发现 `_openclaw-gw._tcp`。
+
+要捕获日志：
+
+- 设置 → Gateway 网关 → 高级 → **Discovery Debug Logs**
+- 设置 → Gateway 网关 → 高级 → **Discovery Logs** → 复现 → **Copy**
+
+日志包括浏览器状态转换和结果集变化。
+
+## 常见故障模式
+
+- **Bonjour 不能跨网络**：使用 Tailnet 或 SSH。
+- **多播被阻止**：某些 Wi‑Fi 网络禁用 mDNS。
+- **休眠 / 接口变动**：macOS 可能暂时丢弃 mDNS 结果；重试。
+- **浏览有效但解析失败**：保持机器名称简单（避免表情符号或
+  标点符号），然后重启 Gateway 网关。服务实例名称源自
+  主机名，因此过于复杂的名称可能会混淆某些解析器。
+
+## 转义的实例名称（`\032`）
+
+Bonjour/DNS‑SD 经常将服务实例名称中的字节转义为十进制 `\DDD`
+序列（例如空格变成 `\032`）。
+
+- 这在协议级别是正常的。
+- UI 应该解码以进行显示（iOS 使用 `BonjourEscapes.decode`）。
+
+## 禁用 / 配置
+
+- `OPENCLAW_DISABLE_BONJOUR=1` 禁用广播（旧版：`OPENCLAW_DISABLE_BONJOUR`）。
+- `~/.openclaw/openclaw.json` 中的 `gateway.bind` 控制 Gateway 网关绑定模式。
+- `OPENCLAW_SSH_PORT` 覆盖 TXT 中广播的 SSH 端口（旧版：`OPENCLAW_SSH_PORT`）。
+- `OPENCLAW_TAILNET_DNS` 在 TXT 中发布 MagicDNS 提示（旧版：`OPENCLAW_TAILNET_DNS`）。
+- `OPENCLAW_CLI_PATH` 覆盖广播的 CLI 路径（旧版：`OPENCLAW_CLI_PATH`）。
+
+## 相关文档
+
+- 设备发现策略和传输选择：[设备发现](/gateway/discovery)
+- 节点配对 + 批准：[Gateway 网关配对](/gateway/pairing)

package/docs/zh-CN/gateway/bridge-protocol.md

@@ -0,0 +1,86 @@
+---
+read_when:
+  - 构建或调试节点客户端（iOS/Android/macOS 节点模式）
+  - 调查配对或 bridge 认证失败
+  - 审计 Gateway 网关暴露的节点接口
+summary: Bridge 协议（旧版节点）：TCP JSONL、配对、作用域 RPC
+title: Bridge 协议
+x-i18n:
+  generated_at: "2026-02-03T07:47:42Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 789bcf3cbc6841fc293e054b919e63d661b3cc4cd205b2094289f00800127fe2
+  source_path: gateway/bridge-protocol.md
+  workflow: 15
+---
+
+# Bridge 协议（旧版节点传输）
+
+Bridge 协议是一个**旧版**节点传输（TCP JSONL）。新的节点客户端应该使用统一的 Gateway 网关 WebSocket 协议。
+
+如果你正在构建操作者或节点客户端，请使用 [Gateway 网关协议](/gateway/protocol)。
+
+**注意：** 当前的 OpenClaw 构建不再包含 TCP bridge 监听器；本文档仅作历史参考保留。
+旧版 `bridge.*` 配置键不再是配置模式的一部分。
+
+## 为什么我们有两种协议
+
+- **安全边界**：bridge 暴露一个小的允许列表，而不是完整的 Gateway 网关 API 接口。
+- **配对 + 节点身份**：节点准入由 Gateway 网关管理，并与每节点令牌绑定。
+- **设备发现用户体验**：节点可以通过局域网上的 Bonjour 发现 Gateway 网关，或通过 tailnet 直接连接。
+- **Loopback WS**：完整的 WS 控制平面保持本地，除非通过 SSH 隧道。
+
+## 传输
+
+- TCP，每行一个 JSON 对象（JSONL）。
+- 可选 TLS（当 `bridge.tls.enabled` 为 true 时）。
+- 旧版默认监听端口为 `18790`（当前构建不启动 TCP bridge）。
+
+当 TLS 启用时，设备发现 TXT 记录包含 `bridgeTls=1` 加上 `bridgeTlsSha256`，以便节点可以固定证书。
+
+## 握手 + 配对
+
+1. 客户端发送带有节点元数据 + 令牌（如果已配对）的 `hello`。
+2. 如果未配对，Gateway 网关回复 `error`（`NOT_PAIRED`/`UNAUTHORIZED`）。
+3. 客户端发送 `pair-request`。
+4. Gateway 网关等待批准，然后发送 `pair-ok` 和 `hello-ok`。
+
+`hello-ok` 返回 `serverName`，可能包含 `canvasHostUrl`。
+
+## 帧
+
+客户端 → Gateway 网关：
+
+- `req` / `res`：作用域 Gateway 网关 RPC（chat、sessions、config、health、voicewake、skills.bins）
+- `event`：节点信号（语音转录、智能体请求、聊天订阅、exec 生命周期）
+
+Gateway 网关 → 客户端：
+
+- `invoke` / `invoke-res`：节点命令（`canvas.*`、`camera.*`、`screen.record`、`location.get`、`sms.send`）
+- `event`：已订阅会话的聊天更新
+- `ping` / `pong`：保活
+
+旧版允许列表强制执行位于 `src/gateway/server-bridge.ts`（已移除）。
+
+## Exec 生命周期事件
+
+节点可以发出 `exec.finished` 或 `exec.denied` 事件来表面化 system.run 活动。
+这些被映射到 Gateway 网关中的系统事件。（旧版节点可能仍会发出 `exec.started`。）
+
+Payload 字段（除非注明，否则都是可选的）：
+
+- `sessionKey`（必需）：接收系统事件的智能体会话。
+- `runId`：用于分组的唯一 exec id。
+- `command`：原始或格式化的命令字符串。
+- `exitCode`、`timedOut`、`success`、`output`：完成详情（仅限 finished）。
+- `reason`：拒绝原因（仅限 denied）。
+
+## Tailnet 使用
+
+- 将 bridge 绑定到 tailnet IP：在 `~/.openclaw/openclaw.json` 中设置 `bridge.bind: "tailnet"`。
+- 客户端通过 MagicDNS 名称或 tailnet IP 连接。
+- Bonjour **不**跨网络；需要时使用手动主机/端口或广域 DNS‑SD。
+
+## 版本控制
+
+Bridge 目前是**隐式 v1**（无最小/最大协商）。预期向后兼容；在任何破坏性变更之前添加 bridge 协议版本字段。

package/docs/zh-CN/gateway/cli-backends.md

@@ -0,0 +1,213 @@
+---
+read_when:
+  - 你想要一个在 API 提供商失败时的可靠回退
+  - 你正在运行 Claude Code CLI 或其他本地 AI CLI 并想要复用它们
+  - 你需要一个纯文本、无工具的路径，但仍支持会话和图像
+summary: CLI 后端：通过本地 AI CLI 实现纯文本回退
+title: CLI 后端
+x-i18n:
+  generated_at: "2026-02-03T07:47:52Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 56a96e83b16a4f6443cbf4a9da7a660c41a5b178af5e13f35352c9d72e1b08dd
+  source_path: gateway/cli-backends.md
+  workflow: 15
+---
+
+# CLI 后端（回退运行时）
+
+当 API 提供商宕机、被限流或暂时异常时，OpenClaw 可以运行**本地 AI CLI** 作为**纯文本回退**。这是有意保守的设计：
+
+- **工具被禁用**（无工具调用）。
+- **文本输入 → 文本输出**（可靠）。
+- **支持会话**（因此后续轮次保持连贯）。
+- 如果 CLI 接受图像路径，**图像可以传递**。
+
+这被设计为**安全网**而非主要路径。当你想要"始终有效"的文本响应而不依赖外部 API 时使用它。
+
+## 新手友好快速开始
+
+你可以**无需任何配置**使用 Claude Code CLI（OpenClaw 自带内置默认值）：
+
+```bash
+openclaw agent --message "hi" --model claude-cli/opus-4.5
+```
+
+Codex CLI 也可以开箱即用：
+
+```bash
+openclaw agent --message "hi" --model codex-cli/gpt-5.2-codex
+```
+
+如果你的 Gateway 网关在 launchd/systemd 下运行且 PATH 很精简，只需添加命令路径：
+
+```json5
+{
+  agents: {
+    defaults: {
+      cliBackends: {
+        "claude-cli": {
+          command: "/opt/homebrew/bin/claude",
+        },
+      },
+    },
+  },
+}
+```
+
+就这样。除了 CLI 本身外，不需要密钥，不需要额外的认证配置。
+
+## 作为回退使用
+
+将 CLI 后端添加到你的回退列表中，这样它只在主要模型失败时运行：
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: {
+        primary: "anthropic/claude-opus-4-5",
+        fallbacks: ["claude-cli/opus-4.5"],
+      },
+      models: {
+        "anthropic/claude-opus-4-5": { alias: "Opus" },
+        "claude-cli/opus-4.5": {},
+      },
+    },
+  },
+}
+```
+
+注意事项：
+
+- 如果你使用 `agents.defaults.models`（允许列表），必须包含 `claude-cli/...`。
+- 如果主要提供商失败（认证、限流、超时），OpenClaw 将接着尝试 CLI 后端。
+
+## 配置概览
+
+所有 CLI 后端位于：
+
+```
+agents.defaults.cliBackends
+```
+
+每个条目以**提供商 ID**（例如 `claude-cli`、`my-cli`）为键。提供商 ID 成为你的模型引用的左侧部分：
+
+```
+<provider>/<model>
+```
+
+### 配置示例
+
+```json5
+{
+  agents: {
+    defaults: {
+      cliBackends: {
+        "claude-cli": {
+          command: "/opt/homebrew/bin/claude",
+        },
+        "my-cli": {
+          command: "my-cli",
+          args: ["--json"],
+          output: "json",
+          input: "arg",
+          modelArg: "--model",
+          modelAliases: {
+            "claude-opus-4-5": "opus",
+            "claude-sonnet-4-5": "sonnet",
+          },
+          sessionArg: "--session",
+          sessionMode: "existing",
+          sessionIdFields: ["session_id", "conversation_id"],
+          systemPromptArg: "--system",
+          systemPromptWhen: "first",
+          imageArg: "--image",
+          imageMode: "repeat",
+          serialize: true,
+        },
+      },
+    },
+  },
+}
+```
+
+## 工作原理
+
+1. **选择后端**基于提供商前缀（`claude-cli/...`）。
+2. **构建系统提示**使用相同的 OpenClaw 提示 + 工作区上下文。
+3. **执行 CLI**并带有会话 ID（如果支持），使历史记录保持一致。
+4. **解析输出**（JSON 或纯文本）并返回最终文本。
+5. **持久化会话 ID**按后端，使后续请求复用相同的 CLI 会话。
+
+## 会话
+
+- 如果 CLI 支持会话，设置 `sessionArg`（例如 `--session-id`）或 `sessionArgs`（占位符 `{sessionId}`）当 ID 需要插入到多个标志中时。
+- 如果 CLI 使用带有不同标志的**恢复子命令**，设置 `resumeArgs`（恢复时替换 `args`）以及可选的 `resumeOutput`（用于非 JSON 恢复）。
+- `sessionMode`：
+  - `always`：始终发送会话 ID（如果没有存储则使用新 UUID）。
+  - `existing`：仅在之前存储了会话 ID 时才发送。
+  - `none`：从不发送会话 ID。
+
+## 图像（传递）
+
+如果你的 CLI 接受图像路径，设置 `imageArg`：
+
+```json5
+imageArg: "--image",
+imageMode: "repeat"
+```
+
+OpenClaw 会将 base64 图像写入临时文件。如果设置了 `imageArg`，这些路径作为 CLI 参数传递。如果缺少 `imageArg`，OpenClaw 会将文件路径附加到提示中（路径注入），这对于从纯路径自动加载本地文件的 CLI 来说已经足够（Claude Code CLI 行为）。
+
+## 输入 / 输出
+
+- `output: "json"`（默认）尝试解析 JSON 并提取文本 + 会话 ID。
+- `output: "jsonl"` 解析 JSONL 流（Codex CLI `--json`）并提取最后一条智能体消息以及存在时的 `thread_id`。
+- `output: "text"` 将 stdout 视为最终响应。
+
+输入模式：
+
+- `input: "arg"`（默认）将提示作为最后一个 CLI 参数传递。
+- `input: "stdin"` 通过 stdin 发送提示。
+- 如果提示很长且设置了 `maxPromptArgChars`，则使用 stdin。
+
+## 默认值（内置）
+
+OpenClaw 自带 `claude-cli` 的默认值：
+
+- `command: "claude"`
+- `args: ["-p", "--output-format", "json", "--dangerously-skip-permissions"]`
+- `resumeArgs: ["-p", "--output-format", "json", "--dangerously-skip-permissions", "--resume", "{sessionId}"]`
+- `modelArg: "--model"`
+- `systemPromptArg: "--append-system-prompt"`
+- `sessionArg: "--session-id"`
+- `systemPromptWhen: "first"`
+- `sessionMode: "always"`
+
+OpenClaw 也自带 `codex-cli` 的默认值：
+
+- `command: "codex"`
+- `args: ["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]`
+- `resumeArgs: ["exec","resume","{sessionId}","--color","never","--sandbox","read-only","--skip-git-repo-check"]`
+- `output: "jsonl"`
+- `resumeOutput: "text"`
+- `modelArg: "--model"`
+- `imageArg: "--image"`
+- `sessionMode: "existing"`
+
+仅在需要时覆盖（常见：绝对 `command` 路径）。
+
+## 限制
+
+- **无 OpenClaw 工具**（CLI 后端永远不会收到工具调用）。某些 CLI 可能仍会运行它们自己的智能体工具。
+- **无流式传输**（CLI 输出被收集后返回）。
+- **结构化输出**取决于 CLI 的 JSON 格式。
+- **Codex CLI 会话**通过文本输出恢复（无 JSONL），这比初始的 `--json` 运行结构化程度低。OpenClaw 会话仍然正常工作。
+
+## 故障排除
+
+- **找不到 CLI**：将 `command` 设置为完整路径。
+- **模型名称错误**：使用 `modelAliases` 将 `provider/model` 映射到 CLI 模型。
+- **无会话连续性**：确保设置了 `sessionArg` 且 `sessionMode` 不是 `none`（Codex CLI 目前无法使用 JSON 输出恢复）。
+- **图像被忽略**：设置 `imageArg`（并验证 CLI 支持文件路径）。