@gguf/claw 2026.2.1 → 2026.2.3

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-01T20:25:21Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: e11a7d74a75000d6882f703693c2c49a2ecd3e730b6ec2b475ac402abde9e465
+  source_path: gateway/background-process.md
+  workflow: 14
+---
+
+# 后台 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,160 @@
+---
+read_when:
+  - 在 macOS/iOS 上调试 Bonjour 发现问题
+  - 更改 mDNS 服务类型、TXT 记录或发现相关的用户体验
+summary: Bonjour/mDNS 发现 + 调试（Gateway网关信标、客户端及常见故障模式）
+title: Bonjour 发现
+x-i18n:
+  generated_at: "2026-02-01T20:25:34Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 47569da55f0c0523bd5ff05275dc95ccb52f75638193cfbdb4eaaa162aadf08c
+  source_path: gateway/bonjour.md
+  workflow: 14
+---
+
+# 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`）默认绑定到 local 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=<主机名>.local`
+- `gatewayPort=<端口>`（Gateway网关 WS + HTTP）
+- `gatewayTls=1`（仅在启用 TLS 时）
+- `gatewayTlsSha256=<sha256>`（仅在启用 TLS 且指纹可用时）
+- `canvasPort=<端口>`（仅在启用 canvas 主机时；默认 `18793`）
+- `sshPort=<端口>`（未覆盖时默认为 22）
+- `transport=gateway`
+- `cliPath=<路径>`（可选；可运行的 `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网关 → 高级 → **发现调试日志**
+- 设置 → Gateway网关 → 高级 → **发现日志** → 复现问题 → **复制**
+
+日志包含浏览器状态转换和结果集变化。
+
+## 常见故障模式
+
+- **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,84 @@
+---
+read_when:
+  - 构建或调试节点客户端（iOS/Android/macOS 节点模式）
+  - 排查配对或桥接认证故障
+  - 审计 Gateway网关暴露的节点接口
+summary: 桥接协议（旧版节点）：TCP JSONL、配对、作用域 RPC
+title: 桥接协议
+x-i18n:
+  generated_at: "2026-02-01T20:25:34Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 789bcf3cbc6841fc293e054b919e63d661b3cc4cd205b2094289f00800127fe2
+  source_path: gateway/bridge-protocol.md
+  workflow: 14
+---
+
+# 桥接协议（旧版节点传输）
+
+桥接协议是一种**旧版**节点传输方式（TCP JSONL）。新的节点客户端应改用统一的 Gateway网关 WebSocket 协议。
+
+如果你正在构建操作端或节点客户端，请使用 [Gateway网关协议](/gateway/protocol)。
+
+**注意：** 当前版本的 OpenClaw 不再附带 TCP 桥接监听器；本文档仅作历史参考保留。旧版 `bridge.*` 配置键已不再属于配置模式的一部分。
+
+## 为什么有两种协议
+
+- **安全边界**：桥接仅暴露一个小型允许列表，而非完整的 Gateway网关 API 接口。
+- **配对与节点身份**：节点准入由 Gateway网关管理，并与每个节点的令牌绑定。
+- **发现体验**：节点可以通过局域网上的 Bonjour 发现 Gateway网关，或通过 tailnet 直接连接。
+- **local loopback WS**：完整的 WS 控制平面保持在本地，除非通过 SSH 隧道转发。
+
+## 传输方式
+
+- TCP，每行一个 JSON 对象（JSONL）。
+- 可选 TLS（当 `bridge.tls.enabled` 为 true 时）。
+- 旧版默认监听端口为 `18790`（当前版本不再启动 TCP 桥接）。
+
+启用 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（聊天、会话、配置、健康检查、语音唤醒、skills.bins）
+- `event`：节点信号（语音转录、智能体请求、聊天订阅、执行生命周期）
+
+Gateway网关 → 客户端：
+
+- `invoke` / `invoke-res`：节点命令（`canvas.*`、`camera.*`、`screen.record`、`location.get`、`sms.send`）
+- `event`：已订阅会话的聊天更新
+- `ping` / `pong`：保活
+
+旧版允许列表强制执行逻辑位于 `src/gateway/server-bridge.ts`（已移除）。
+
+## 执行生命周期事件
+
+节点可以发出 `exec.finished` 或 `exec.denied` 事件以展示 system.run 活动。这些会映射为 Gateway网关中的系统事件。（旧版节点可能仍会发出 `exec.started`。）
+
+有效载荷字段（除特别说明外均为可选）：
+
+- `sessionKey`（必填）：接收系统事件的智能体会话。
+- `runId`：用于分组的唯一执行 ID。
+- `command`：原始或格式化的命令字符串。
+- `exitCode`、`timedOut`、`success`、`output`：完成详情（仅限 finished）。
+- `reason`：拒绝原因（仅限 denied）。
+
+## Tailnet 使用
+
+- 将桥接绑定到 tailnet IP：在 `~/.openclaw/openclaw.json` 中设置 `bridge.bind: "tailnet"`。
+- 客户端通过 MagicDNS 名称或 tailnet IP 连接。
+- Bonjour **不能**跨网络；需要时请使用手动指定主机/端口或广域 DNS-SD。
+
+## 版本控制
+
+桥接目前为**隐式 v1**（无最小/最大版本协商）。预期保持向后兼容；在引入任何破坏性变更之前应添加桥接协议版本字段。

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

@@ -0,0 +1,214 @@
+---
+read_when:
+  - 你需要在 API 提供商故障时使用可靠的回退方案
+  - 你正在运行 Claude Code CLI 或其他本地 AI CLI，并希望复用它们
+  - 你需要一个纯文本、无工具的路径，同时仍支持会话和图片
+summary: CLI 后端：通过本地 AI CLI 实现纯文本回退
+title: CLI 后端
+x-i18n:
+  generated_at: "2026-02-01T20:25:48Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 56a96e83b16a4f6443cbf4a9da7a660c41a5b178af5e13f35352c9d72e1b08dd
+  source_path: gateway/cli-backends.md
+  workflow: 14
+---
+
+# CLI 后端（回退运行时）
+
+OpenClaw 可以将**本地 AI CLI** 作为**纯文本回退**运行，适用于 API 提供商宕机、被限流或暂时异常的情况。该方案设计上有意保持保守：
+
+- **工具已禁用**（不进行工具调用）。
+- **文本输入 → 文本输出**（可靠）。
+- **支持会话**（后续对话轮次保持连贯）。
+- **可传递图片**（如果 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"` 将标准输出作为最终响应。
+
+输入模式：
+
+- `input: "arg"`（默认）将提示词作为最后一个 CLI 参数传递。
+- `input: "stdin"` 通过标准输入发送提示词。
+- 如果提示词很长且设置了 `maxPromptArgChars`，将使用标准输入。
+
+## 默认值（内置）
+
+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 支持文件路径）。