@gguf/claw 2026.2.1 → 2026.2.3

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

@@ -0,0 +1,123 @@
+---
+read_when:
+  - 实现或更改 Bonjour 发现/广播功能
+  - 调整远程连接模式（直连 vs SSH）
+  - 为远程节点设计节点发现 + 配对方案
+summary: 节点发现与传输（Bonjour、Tailscale、SSH）用于查找 Gateway网关
+title: 发现与传输
+x-i18n:
+  generated_at: "2026-02-01T20:25:57Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: e12172c181515bfa6aab8625ed3fbc335b80ba92e2b516c02c6066aeeb9f884c
+  source_path: gateway/discovery.md
+  workflow: 14
+---
+
+# 发现与传输
+
+OpenClaw 有两个表面上看起来相似但实际上不同的问题：
+
+1. **操作者远程控制**：macOS 菜单栏应用控制运行在其他位置的 Gateway网关。
+2. **节点配对**：iOS/Android（以及未来的节点）找到 Gateway网关并安全配对。
+
+设计目标是将所有网络发现/广播保留在 **Node Gateway网关**（`openclaw gateway`）中，让客户端（Mac 应用、iOS）作为消费者。
+
+## 术语
+
+- **Gateway网关**：一个长期运行的 Gateway网关进程，拥有状态（会话、配对、节点注册表）并运行渠道。大多数配置每台主机使用一个；也可以进行隔离的多 Gateway网关设置。
+- **Gateway网关 WS（控制平面）**：默认位于 `127.0.0.1:18789` 的 WebSocket 端点；可通过 `gateway.bind` 绑定到局域网/Tailnet。
+- **直连 WS 传输**：面向局域网/Tailnet 的 Gateway网关 WS 端点（无 SSH）。
+- **SSH 传输（回退）**：通过 SSH 转发 `127.0.0.1:18789` 实现远程控制。
+- **旧版 TCP 桥接（已弃用/移除）**：旧的节点传输方式（参见 [桥接协议](/gateway/bridge-protocol)）；不再用于发现广播。
+
+协议详情：
+
+- [Gateway网关协议](/gateway/protocol)
+- [桥接协议（旧版）](/gateway/bridge-protocol)
+
+## 为什么同时保留"直连"和 SSH
+
+- **直连 WS** 在同一网络和 Tailnet 内提供最佳用户体验：
+  - 通过 Bonjour 在局域网上自动发现
+  - 配对令牌 + ACL 由 Gateway网关管理
+  - 不需要 shell 访问；协议接口可以保持精简且可审计
+- **SSH** 仍然是通用的回退方案：
+  - 在任何有 SSH 访问的地方都可以工作（甚至跨不相关的网络）
+  - 不受组播/mDNS 问题影响
+  - 除 SSH 外不需要新的入站端口
+
+## 发现输入（客户端如何获知 Gateway网关位置）
+
+### 1) Bonjour / mDNS（仅限局域网）
+
+Bonjour 是尽力而为的机制，无法跨网络。它仅用于"同一局域网"的便捷发现。
+
+目标方向：
+
+- **Gateway网关** 通过 Bonjour 广播其 WS 端点。
+- 客户端浏览并显示"选择 Gateway网关"列表，然后存储所选端点。
+
+故障排除和信标详情：[Bonjour](/gateway/bonjour)。
+
+#### 服务信标详情
+
+- 服务类型：
+  - `_openclaw-gw._tcp`（Gateway网关传输信标）
+- TXT 键（非机密）：
+  - `role=gateway`
+  - `lanHost=<主机名>.local`
+  - `sshPort=22`（或实际广播的端口）
+  - `gatewayPort=18789`（Gateway网关 WS + HTTP）
+  - `gatewayTls=1`（仅在启用 TLS 时）
+  - `gatewayTlsSha256=<sha256>`（仅在启用 TLS 且指纹可用时）
+  - `canvasPort=18793`（默认 canvas 主机端口；服务于 `/__openclaw__/canvas/`）
+  - `cliPath=<路径>`（可选；可运行的 `openclaw` 入口点或二进制文件的绝对路径）
+  - `tailnetDns=<magicdns>`（可选提示；当 Tailscale 可用时自动检测）
+
+禁用/覆盖：
+
+- `OPENCLAW_DISABLE_BONJOUR=1` 禁用广播。
+- `~/.openclaw/openclaw.json` 中的 `gateway.bind` 控制 Gateway网关绑定模式。
+- `OPENCLAW_SSH_PORT` 覆盖 TXT 中广播的 SSH 端口（默认为 22）。
+- `OPENCLAW_TAILNET_DNS` 发布 `tailnetDns` 提示（MagicDNS）。
+- `OPENCLAW_CLI_PATH` 覆盖广播的 CLI 路径。
+
+### 2) Tailnet（跨网络）
+
+对于伦敦/维也纳式的跨地域部署，Bonjour 无法提供帮助。推荐的"直连"目标是：
+
+- Tailscale MagicDNS 名称（首选）或稳定的 Tailnet IP。
+
+如果 Gateway网关能检测到自己运行在 Tailscale 下，它会将 `tailnetDns` 作为可选提示发布给客户端（包括广域信标）。
+
+### 3) 手动 / SSH 目标
+
+当没有直接路由（或直连被禁用）时，客户端始终可以通过 SSH 转发 local loopback Gateway网关端口进行连接。
+
+参见 [远程访问](/gateway/remote)。
+
+## 传输选择（客户端策略）
+
+推荐的客户端行为：
+
+1. 如果已配置并可达已配对的直连端点，则使用它。
+2. 否则，如果 Bonjour 在局域网上发现了 Gateway网关，提供一键"使用此 Gateway网关"选项并将其保存为直连端点。
+3. 否则，如果配置了 Tailnet DNS/IP，尝试直连。
+4. 否则，回退到 SSH。
+
+## 配对 + 认证（直连传输）
+
+Gateway网关是节点/客户端准入的权威来源。
+
+- 配对请求在 Gateway网关中创建/批准/拒绝（参见 [Gateway网关配对](/gateway/pairing)）。
+- Gateway网关强制执行：
+  - 认证（令牌 / 密钥对）
+  - 权限范围/ACL（Gateway网关不是对所有方法的原始代理）
+  - 速率限制
+
+## 各组件职责
+
+- **Gateway网关**：广播发现信标，管理配对决策，并托管 WS 端点。
+- **macOS 应用**：帮助你选择 Gateway网关，显示配对提示，仅将 SSH 作为回退方案。
+- **iOS/Android 节点**：将 Bonjour 浏览作为便捷方式，连接到已配对的 Gateway网关 WS。

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

@@ -0,0 +1,236 @@
+---
+read_when:
+  - 添加或修改 doctor 迁移
+  - 引入破坏性配置变更
+summary: Doctor 命令：健康检查、配置迁移和修复步骤
+title: Doctor
+x-i18n:
+  generated_at: "2026-02-01T20:26:33Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: df7b25f60fd08d508f4c6abfc8e7e06f29bd4bbb34c3320397f47eb72c8de83f
+  source_path: gateway/doctor.md
+  workflow: 14
+---
+
+# Doctor
+
+`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它修复过时的配置/状态、检查健康状况，并提供可操作的修复步骤。
+
+## 快速开始
+
+```bash
+openclaw doctor
+```
+
+### 无界面 / 自动化
+
+```bash
+openclaw doctor --yes
+```
+
+无需提示即接受默认值（包括适用时的重启/服务/沙箱修复步骤）。
+
+```bash
+openclaw doctor --repair
+```
+
+无需提示即应用推荐修复（安全情况下执行修复 + 重启）。
+
+```bash
+openclaw doctor --repair --force
+```
+
+同时应用激进修复（覆盖自定义 supervisor 配置）。
+
+```bash
+openclaw doctor --non-interactive
+```
+
+无提示运行，仅应用安全迁移（配置规范化 + 磁盘状态迁移）。跳过需要人工确认的重启/服务/沙箱操作。
+检测到遗留状态迁移时会自动运行。
+
+```bash
+openclaw doctor --deep
+```
+
+扫描系统服务以查找额外的 Gateway网关安装（launchd/systemd/schtasks）。
+
+如果你想在写入前查看更改，请先打开配置文件：
+
+```bash
+cat ~/.openclaw/openclaw.json
+```
+
+## 功能概述
+
+- 可选的 git 安装预检更新（仅交互模式）。
+- UI 协议新鲜度检查（当协议 schema 更新时重建控制 UI）。
+- 健康检查 + 重启提示。
+- Skills 状态摘要（可用/缺失/受阻）。
+- 遗留值的配置规范化。
+- OpenCode Zen 提供商覆盖警告（`models.providers.opencode`）。
+- 遗留磁盘状态迁移（会话/智能体目录/WhatsApp 认证）。
+- 状态完整性和权限检查（会话、转录、状态目录）。
+- 本地运行时的配置文件权限检查（chmod 600）。
+- 模型认证健康：检查 OAuth 过期、可刷新即将过期的令牌、报告认证配置的冷却/禁用状态。
+- 额外工作区目录检测（`~/openclaw`）。
+- 启用沙箱时的沙箱镜像修复。
+- 遗留服务迁移和额外 Gateway网关检测。
+- Gateway网关运行时检查（服务已安装但未运行；缓存的 launchd 标签）。
+- 渠道状态警告（从运行中的 Gateway网关探测）。
+- Supervisor 配置审计（launchd/systemd/schtasks）及可选修复。
+- Gateway网关运行时最佳实践检查（Node vs Bun、版本管理器路径）。
+- Gateway网关端口冲突诊断（默认 `18789`）。
+- 开放 私信 策略的安全警告。
+- 未设置 `gateway.auth.token` 时的 Gateway网关认证警告（本地模式；提供令牌生成）。
+- Linux 上的 systemd linger 检查。
+- 源码安装检查（pnpm workspace 不匹配、缺失 UI 资源、缺失 tsx 二进制文件）。
+- 写入更新后的配置 + 向导元数据。
+
+## 详细行为和原理
+
+### 0) 可选更新（git 安装）
+
+如果这是一个 git 检出且 doctor 在交互模式下运行，它会在运行 doctor 之前提供更新（fetch/rebase/build）。
+
+### 1) 配置规范化
+
+如果配置包含遗留值格式（例如 `messages.ackReaction` 没有渠道特定的覆盖），doctor 会将其规范化为当前 schema。
+
+### 2) 遗留配置键迁移
+
+当配置包含已弃用的键时，其他命令会拒绝运行并要求你运行 `openclaw doctor`。
+
+Doctor 将：
+
+- 说明找到了哪些遗留键。
+- 显示它应用的迁移。
+- 使用更新后的 schema 重写 `~/.openclaw/openclaw.json`。
+
+Gateway网关在启动时检测到遗留配置格式时也会自动运行 doctor 迁移，因此过时的配置无需手动干预即可修复。
+
+当前迁移：
+
+- `routing.allowFrom` → `channels.whatsapp.allowFrom`
+- `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention`
+- `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
+- `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
+- `routing.queue` → `messages.queue`
+- `routing.bindings` → 顶级 `bindings`
+- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
+- `routing.agentToAgent` → `tools.agentToAgent`
+- `routing.transcribeAudio` → `tools.media.audio.models`
+- `bindings[].match.accountID` → `bindings[].match.accountId`
+- `identity` → `agents.list[].identity`
+- `agent.*` → `agents.defaults` + `tools.*`（tools/elevated/exec/sandbox/subagents）
+- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`
+  → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
+
+### 2b) OpenCode Zen 提供商覆盖
+
+如果你手动添加了 `models.providers.opencode`（或 `opencode-zen`），它会覆盖 `@mariozechner/pi-ai` 内置的 OpenCode Zen 目录。这可能会将所有模型强制指向单个 API 或将成本归零。Doctor 会发出警告，以便你移除覆盖并恢复按模型的 API 路由 + 成本。
+
+### 3) 遗留状态迁移（磁盘布局）
+
+Doctor 可以将旧版磁盘布局迁移到当前结构：
+
+- 会话存储 + 转录：
+  - 从 `~/.openclaw/sessions/` 到 `~/.openclaw/agents/<agentId>/sessions/`
+- 智能体目录：
+  - 从 `~/.openclaw/agent/` 到 `~/.openclaw/agents/<agentId>/agent/`
+- WhatsApp 认证状态（Baileys）：
+  - 从遗留的 `~/.openclaw/credentials/*.json`（`oauth.json` 除外）
+  - 到 `~/.openclaw/credentials/whatsapp/<accountId>/...`（默认账户 ID：`default`）
+
+这些迁移尽力执行且幂等；当 doctor 保留任何遗留文件夹作为备份时会发出警告。Gateway网关/CLI 在启动时也会自动迁移遗留会话 + 智能体目录，使历史/认证/模型落入每个智能体的路径中，无需手动运行 doctor。WhatsApp 认证仅通过 `openclaw doctor` 进行迁移。
+
+### 4) 状态完整性检查（会话持久化、路由和安全性）
+
+状态目录是运行的核心枢纽。如果它消失，你将丢失会话、凭据、日志和配置（除非你在其他地方有备份）。
+
+Doctor 检查：
+
+- **状态目录缺失**：警告灾难性状态丢失，提示重新创建目录，并提醒无法恢复丢失的数据。
+- **状态目录权限**：验证可写性；提供修复权限的选项（检测到所有者/组不匹配时发出 `chown` 提示）。
+- **会话目录缺失**：`sessions/` 和会话存储目录是持久化历史记录和避免 `ENOENT` 崩溃所必需的。
+- **转录不匹配**：当近期会话条目缺少转录文件时发出警告。
+- **主会话"单行 JSONL"**：当主转录只有一行时标记（历史记录未在累积）。
+- **多个状态目录**：当多个 `~/.openclaw` 文件夹存在于不同的 home 目录中，或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告（历史记录可能在不同安装间分裂）。
+- **远程模式提醒**：如果 `gateway.mode=remote`，doctor 提醒你在远程主机上运行（状态存储在那里）。
+- **配置文件权限**：当 `~/.openclaw/openclaw.json` 对组/其他用户可读时发出警告，并提供收紧为 `600` 的选项。
+
+### 5) 模型认证健康（OAuth 过期）
+
+Doctor 检查认证存储中的 OAuth 配置，当令牌即将过期/已过期时发出警告，并在安全时刷新它们。如果 Anthropic Claude Code 配置过时，它会建议运行 `claude setup-token`（或粘贴 setup-token）。刷新提示仅在交互运行（TTY）时出现；`--non-interactive` 跳过刷新尝试。
+
+Doctor 还会报告由于以下原因暂时不可用的认证配置：
+
+- 短期冷却（速率限制/超时/认证失败）
+- 较长时间的禁用（账单/额度失败）
+
+### 6) Hooks 模型验证
+
+如果设置了 `hooks.gmail.model`，doctor 会根据目录和允许列表验证模型引用，并在无法解析或被禁止时发出警告。
+
+### 7) 沙箱镜像修复
+
+当启用沙箱时，doctor 检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到遗留名称的选项。
+
+### 8) Gateway网关服务迁移和清理提示
+
+Doctor 检测遗留 Gateway网关服务（launchd/systemd/schtasks），并提供删除它们并使用当前 Gateway网关端口安装 OpenClaw 服务的选项。它还可以扫描额外的类 Gateway网关服务并打印清理提示。以配置文件命名的 OpenClaw Gateway网关服务被视为一等公民，不会被标记为"额外"。
+
+### 9) 安全警告
+
+当提供商对 私信 开放且没有允许列表时，或当策略以危险方式配置时，doctor 会发出警告。
+
+### 10) systemd linger（Linux）
+
+如果作为 systemd 用户服务运行，doctor 确保 linger 已启用，以便 Gateway网关在注销后保持运行。
+
+### 11) Skills 状态
+
+Doctor 打印当前工作区可用/缺失/受阻 Skills 的快速摘要。
+
+### 12) Gateway网关认证检查（本地令牌）
+
+当本地 Gateway网关缺少 `gateway.auth` 时，doctor 发出警告并提供生成令牌的选项。使用 `openclaw doctor --generate-gateway-token` 在自动化中强制创建令牌。
+
+### 13) Gateway网关健康检查 + 重启
+
+Doctor 运行健康检查，并在 Gateway网关看起来不健康时提供重启选项。
+
+### 14) 渠道状态警告
+
+如果 Gateway网关健康，doctor 运行渠道状态探测并报告警告及建议的修复方案。
+
+### 15) Supervisor 配置审计 + 修复
+
+Doctor 检查已安装的 supervisor 配置（launchd/systemd/schtasks）是否有缺失或过时的默认值（例如 systemd 的 network-online 依赖和重启延迟）。当发现不匹配时，它会推荐更新并可以将服务文件/任务重写为当前默认值。
+
+说明：
+
+- `openclaw doctor` 在重写 supervisor 配置前会提示确认。
+- `openclaw doctor --yes` 接受默认修复提示。
+- `openclaw doctor --repair` 无需提示即应用推荐修复。
+- `openclaw doctor --repair --force` 覆盖自定义 supervisor 配置。
+- 你始终可以通过 `openclaw gateway install --force` 强制完全重写。
+
+### 16) Gateway网关运行时 + 端口诊断
+
+Doctor 检查服务运行时（PID、上次退出状态），并在服务已安装但实际未运行时发出警告。它还检查 Gateway网关端口（默认 `18789`）上的端口冲突并报告可能的原因（Gateway网关已在运行、SSH 隧道）。
+
+### 17) Gateway网关运行时最佳实践
+
+当 Gateway网关服务运行在 Bun 或版本管理器管理的 Node 路径（`nvm`、`fnm`、`volta`、`asdf` 等）上时，doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node，而版本管理器路径在升级后可能会失效，因为服务不会加载你的 shell 初始化文件。Doctor 会在系统 Node 安装可用时提供迁移选项（Homebrew/apt/choco）。
+
+### 18) 配置写入 + 向导元数据
+
+Doctor 持久化所有配置更改，并记录向导元数据以标记 doctor 运行。
+
+### 19) 工作区提示（备份 + 记忆系统）
+
+当缺少工作区记忆系统时，doctor 会建议添加，并在工作区尚未纳入 git 管理时打印备份提示。
+
+参见 [/concepts/agent-workspace](/concepts/agent-workspace) 获取工作区结构和 git 备份的完整指南（推荐使用私有 GitHub 或 GitLab）。

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

@@ -0,0 +1,41 @@
+---
+read_when:
+  - 运行或调试 Gateway网关进程时
+  - 调查单实例强制机制时
+summary: Gateway网关单例守卫：通过 WebSocket 监听器绑定实现
+title: Gateway网关锁
+x-i18n:
+  generated_at: "2026-02-01T20:25:58Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 15fdfa066d1925da8b4632073a876709f77ca8d40e6828c174a30d953ba4f8e9
+  source_path: gateway/gateway-lock.md
+  workflow: 14
+---
+
+# Gateway网关锁
+
+最后更新：2025-12-11
+
+## 原因
+
+- 确保同一主机上每个基础端口只运行一个 Gateway网关实例；额外的 Gateway网关必须使用隔离的配置文件和唯一端口。
+- 在崩溃/SIGKILL 后不会留下过期的锁文件。
+- 当控制端口已被占用时，快速失败并给出清晰的错误信息。
+
+## 机制
+
+- Gateway网关在启动时立即通过独占 TCP 监听器绑定 WebSocket 监听器（默认 `ws://127.0.0.1:18789`）。
+- 如果绑定失败并返回 `EADDRINUSE`，启动时将抛出 `Gateway网关LockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`。
+- 操作系统会在进程以任何方式退出时自动释放监听器，包括崩溃和 SIGKILL——无需单独的锁文件或清理步骤。
+- 关闭时，Gateway网关会关闭 WebSocket 服务器和底层 HTTP 服务器以及时释放端口。
+
+## 错误表现
+
+- 如果另一个进程持有该端口，启动时将抛出 `Gateway网关LockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`。
+- 其他绑定失败将表现为 `Gateway网关LockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")`。
+
+## 运维说明
+
+- 如果端口被*其他*进程占用，错误信息相同；请释放该端口或使用 `openclaw gateway --port <port>` 选择另一个端口。
+- macOS 应用在启动 Gateway网关之前仍会维护自己的轻量级 PID 守卫；运行时锁由 WebSocket 绑定强制执行。

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

@@ -0,0 +1,42 @@
+---
+read_when:
+  - 诊断 WhatsApp 渠道健康状况
+summary: 渠道连接的健康检查步骤
+title: 健康检查
+x-i18n:
+  generated_at: "2026-02-01T20:26:10Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 74f242e98244c135e1322682ed6b67d70f3b404aca783b1bb5de96a27c2c1b01
+  source_path: gateway/health.md
+  workflow: 14
+---
+
+# 健康检查（CLI）
+
+验证渠道连接状态的简要指南，无需猜测。
+
+## 快速检查
+
+- `openclaw status` — 本地摘要：Gateway网关可达性/模式、更新提示、已关联渠道认证时长、会话 + 近期活动。
+- `openclaw status --all` — 完整本地诊断（只读、带颜色、可安全粘贴用于调试）。
+- `openclaw status --deep` — 还会探测运行中的 Gateway网关（支持时进行逐渠道探测）。
+- `openclaw health --json` — 向运行中的 Gateway网关请求完整健康快照（仅限 WS；不直接访问 Baileys socket）。
+- 在 WhatsApp/WebChat 中发送 `/status` 作为独立消息，可获取状态回复而不触发智能体。
+- 日志：尾部查看 `/tmp/openclaw/openclaw-*.log` 并过滤 `web-heartbeat`、`web-reconnect`、`web-auto-reply`、`web-inbound`。
+
+## 深度诊断
+
+- 磁盘上的凭证：`ls -l ~/.openclaw/credentials/whatsapp/<accountId>/creds.json`（修改时间应为近期）。
+- 会话存储：`ls -l ~/.openclaw/agents/<agentId>/sessions/sessions.json`（路径可在配置中覆盖）。计数和近期接收者可通过 `status` 查看。
+- 重新关联流程：当日志中出现状态码 409–515 或 `loggedOut` 时，执行 `openclaw channels logout && openclaw channels login --verbose`。（注意：QR 登录流程在配对后遇到状态码 515 时会自动重试一次。）
+
+## 当出现故障时
+
+- `logged out` 或状态码 409–515 → 使用 `openclaw channels logout` 然后 `openclaw channels login` 重新关联。
+- Gateway网关不可达 → 启动它：`openclaw gateway --port 18789`（如果端口被占用，使用 `--force`）。
+- 没有收到入站消息 → 确认已关联的手机在线且发送者已被允许（`channels.whatsapp.allowFrom`）；对于群聊，确保允许列表 + 提及规则匹配（`channels.whatsapp.groups`、`agents.list[].groupChat.mentionPatterns`）。
+
+## 专用 "health" 命令
+
+`openclaw health --json` 向运行中的 Gateway网关请求其健康快照（CLI 不直接访问渠道 socket）。它会报告已关联凭证/认证时长（如可用）、逐渠道探测摘要、会话存储摘要和探测耗时。如果 Gateway网关不可达或探测失败/超时，则以非零状态码退出。使用 `--timeout <ms>` 可覆盖默认的 10 秒超时。