@agent-our/openclaw 2026.2.6-3

package/docs/zh-CN/experiments/research/memory.md

@@ -0,0 +1,235 @@
+---
+read_when:
+  - 设计超越每日 Markdown 日志的工作区记忆（~/.openclaw/workspace）
+  - Deciding: standalone CLI vs deep OpenClaw integration
+  - 添加离线回忆 + 反思（retain/recall/reflect）
+summary: 研究笔记：Clawd 工作区的离线记忆系统（Markdown 作为数据源 + 派生索引）
+title: 工作区记忆研究
+x-i18n:
+  generated_at: "2026-02-03T10:06:14Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 1753c8ee6284999fab4a94ff5fae7421c85233699c9d3088453d0c2133ac0feb
+  source_path: experiments/research/memory.md
+  workflow: 15
+---
+
+# 工作区记忆 v2（离线）：研究笔记
+
+目标：Clawd 风格的工作区（`agents.defaults.workspace`，默认 `~/.openclaw/workspace`），其中"记忆"以每天一个 Markdown 文件（`memory/YYYY-MM-DD.md`）加上一小组稳定文件（例如 `memory.md`、`SOUL.md`）的形式存储。
+
+本文档提出一种**离线优先**的记忆架构，保持 Markdown 作为规范的、可审查的数据源，但通过派生索引添加**结构化回忆**（搜索、实体摘要、置信度更新）。
+
+## 为什么要改变？
+
+当前设置（每天一个文件）非常适合：
+
+- "仅追加"式日志记录
+- 人工编辑
+- git 支持的持久性 + 可审计性
+- 低摩擦捕获（"直接写下来"）
+
+但它在以下方面较弱：
+
+- 高召回率检索（"我们对 X 做了什么决定？"、"上次我们尝试 Y 时？"）
+- 以实体为中心的答案（"告诉我关于 Alice / The Castle / warelay 的信息"）而无需重读多个文件
+- 观点/偏好稳定性（以及变化时的证据）
+- 时间约束（"2025 年 11 月期间什么是真实的？"）和冲突解决
+
+## 设计目标
+
+- **离线**：无需网络即可工作；可在笔记本电脑/Castle 上运行；无云依赖。
+- **可解释**：检索的项目应该可归因（文件 + 位置）并与推理分离。
+- **低仪式感**：每日日志保持 Markdown，无需繁重的 schema 工作。
+- **增量式**：v1 仅使用 FTS 就很有用；语义/向量和图是可选升级。
+- **对智能体友好**：使"在 token 预算内回忆"变得简单（返回小型事实包）。
+
+## 北极星模型（Hindsight × Letta）
+
+需要融合两个部分：
+
+1. **Letta/MemGPT 风格的控制循环**
+
+- 保持一个小的"核心"始终在上下文中（角色 + 关键用户事实）
+- 其他所有内容都在上下文之外，通过工具检索
+- 记忆写入是显式的工具调用（append/replace/insert），持久化后在下一轮重新注入
+
+2. **Hindsight 风格的记忆基底**
+
+- 分离观察到的、相信的和总结的内容
+- 支持 retain/recall/reflect
+- 带有置信度的观点可以随证据演变
+- 实体感知检索 + 时间查询（即使没有完整的知识图谱）
+
+## 提议的架构（Markdown 数据源 + 派生索引）
+
+### 规范存储（git 友好）
+
+保持 `~/.openclaw/workspace` 作为规范的人类可读记忆。
+
+建议的工作区布局：
+
+```
+~/.openclaw/workspace/
+  memory.md                    # 小型：持久事实 + 偏好（类似核心）
+  memory/
+    YYYY-MM-DD.md              # 每日日志（追加；叙事）
+  bank/                        # "类型化"记忆页面（稳定、可审查）
+    world.md                   # 关于世界的客观事实
+    experience.md              # 智能体做了什么（第一人称）
+    opinions.md                # 主观偏好/判断 + 置信度 + 证据指针
+    entities/
+      Peter.md
+      The-Castle.md
+      warelay.md
+      ...
+```
+
+注意：
+
+- **每日日志保持为每日日志**。无需将其转换为 JSON。
+- `bank/` 文件是**经过整理的**，由反思任务生成，仍可手动编辑。
+- `memory.md` 保持"小型 + 类似核心"：你希望 Clawd 每次会话都能看到的内容。
+
+### 派生存储（机器回忆）
+
+在工作区下添加派生索引（不一定需要 git 跟踪）：
+
+```
+~/.openclaw/workspace/.memory/index.sqlite
+```
+
+后端支持：
+
+- 用于事实 + 实体链接 + 观点元数据的 SQLite schema
+- SQLite **FTS5** 用于词法回忆（快速、小巧、离线）
+- 可选的嵌入表用于语义回忆（仍然离线）
+
+索引始终**可从 Markdown 重建**。
+
+## Retain / Recall / Reflect（操作循环）
+
+### Retain：将每日日志规范化为"事实"
+
+Hindsight 在这里重要的关键洞察：存储**叙事性、自包含的事实**，而不是微小的片段。
+
+`memory/YYYY-MM-DD.md` 的实用规则：
+
+- 在一天结束时（或期间），添加一个 `## Retain` 部分，包含 2-5 个要点：
+  - 叙事性（保留跨轮上下文）
+  - 自包含（独立时也有意义）
+  - 标记类型 + 实体提及
+
+示例：
+
+```
+## Retain
+- W @Peter: Currently in Marrakech (Nov 27–Dec 1, 2025) for Andy's birthday.
+- B @warelay: I fixed the Baileys WS crash by wrapping connection.update handlers in try/catch (see memory/2025-11-27.md).
+- O(c=0.95) @Peter: Prefers concise replies (<1500 chars) on WhatsApp; long content goes into files.
+```
+
+最小化解析：
+
+- 类型前缀：`W`（世界）、`B`（经历/传记）、`O`（观点）、`S`（观察/摘要；通常是生成的）
+- 实体：`@Peter`、`@warelay` 等（slug 映射到 `bank/entities/*.md`）
+- 观点置信度：`O(c=0.0..1.0)` 可选
+
+如果你不想让作者考虑这些：反思任务可以从日志的其余部分推断这些要点，但有一个显式的 `## Retain` 部分是最简单的"质量杠杆"。
+
+### Recall：对派生索引的查询
+
+Recall 应支持：
+
+- **词法**："查找精确的术语/名称/命令"（FTS5）
+- **实体**："告诉我关于 X 的信息"（实体页面 + 实体链接的事实）
+- **时间**："11 月 27 日前后发生了什么"/"自上周以来"
+- **观点**："Peter 偏好什么？"（带置信度 + 证据）
+
+返回格式应对智能体友好并引用来源：
+
+- `kind`（`world|experience|opinion|observation`）
+- `timestamp`（来源日期，或如果存在则提取的时间范围）
+- `entities`（`["Peter","warelay"]`）
+- `content`（叙事性事实）
+- `source`（`memory/2025-11-27.md#L12` 等）
+
+### Reflect：生成稳定页面 + 更新信念
+
+反思是一个定时任务（每日或心跳 `ultrathink`），它：
+
+- 根据最近的事实更新 `bank/entities/*.md`（实体摘要）
+- 根据强化/矛盾更新 `bank/opinions.md` 置信度
+- 可选地提议对 `memory.md`（"类似核心"的持久事实）的编辑
+
+观点演变（简单、可解释）：
+
+- 每个观点有：
+  - 陈述
+  - 置信度 `c ∈ [0,1]`
+  - last_updated
+  - 证据链接（支持 + 矛盾的事实 ID）
+- 当新事实到达时：
+  - 通过实体重叠 + 相似性找到候选观点（先 FTS，后嵌入）
+  - 通过小幅增量更新置信度；大幅跳跃需要强矛盾 + 重复证据
+
+## CLI 集成：独立 vs 深度集成
+
+建议：**深度集成到 OpenClaw**，但保持可分离的核心库。
+
+### 为什么要集成到 OpenClaw？
+
+- OpenClaw 已经知道：
+  - 工作区路径（`agents.defaults.workspace`）
+  - 会话模型 + 心跳
+  - 日志记录 + 故障排除模式
+- 你希望智能体自己调用工具：
+  - `openclaw memory recall "…" --k 25 --since 30d`
+  - `openclaw memory reflect --since 7d`
+
+### 为什么仍要分离库？
+
+- 保持记忆逻辑可测试，无需 Gateway 网关/运行时
+- 可从其他上下文重用（本地脚本、未来的桌面应用等）
+
+形态：
+记忆工具预计是一个小型 CLI + 库层，但这仅是探索性的。
+
+## "S-Collide" / SuCo：何时使用（研究）
+
+如果"S-Collide"指的是 **SuCo（Subspace Collision）**：这是一种 ANN 检索方法，通过在子空间中使用学习/结构化碰撞来实现强召回/延迟权衡（论文：arXiv 2411.14754，2024）。
+
+对于 `~/.openclaw/workspace` 的务实观点：
+
+- **不要从** SuCo 开始。
+- 从 SQLite FTS +（可选的）简单嵌入开始；你会立即获得大部分 UX 收益。
+- 仅在以下情况下考虑 SuCo/HNSW/ScaNN 级别的解决方案：
+  - 语料库很大（数万/数十万个块）
+  - 暴力嵌入搜索变得太慢
+  - 召回质量明显受到词法搜索的瓶颈限制
+
+离线友好的替代方案（按复杂性递增）：
+
+- SQLite FTS5 + 元数据过滤（零 ML）
+- 嵌入 + 暴力搜索（如果块数量低，效果出奇地好）
+- HNSW 索引（常见、稳健；需要库绑定）
+- SuCo（研究级；如果有可嵌入的可靠实现则很有吸引力）
+
+开放问题：
+
+- 对于你的机器（笔记本 + 台式机）上的"个人助理记忆"，**最佳**的离线嵌入模型是什么？
+  - 如果你已经有 Ollama：使用本地模型嵌入；否则在工具链中附带一个小型嵌入模型。
+
+## 最小可用试点
+
+如果你想要一个最小但仍有用的版本：
+
+- 添加 `bank/` 实体页面和每日日志中的 `## Retain` 部分。
+- 使用 SQLite FTS 进行带引用的回忆（路径 + 行号）。
+- 仅在召回质量或规模需要时添加嵌入。
+
+## 参考资料
+
+- Letta / MemGPT 概念："核心记忆块" + "档案记忆" + 工具驱动的自编辑记忆。
+- Hindsight 技术报告："retain / recall / reflect"，四网络记忆，叙事性事实提取，观点置信度演变。
+- SuCo：arXiv 2411.14754（2024）："Subspace Collision"近似最近邻检索。

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

@@ -0,0 +1,142 @@
+---
+read_when:
+  - 调试模型认证或 OAuth 过期
+  - 记录认证或凭证存储
+summary: 模型认证：OAuth、API 密钥和 setup-token
+title: 认证
+x-i18n:
+  generated_at: "2026-02-03T07:47:32Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 66fa2c64ff374c9cfcdb4e7a951b0d164d512295e65513eb682f12191b75e557
+  source_path: gateway/authentication.md
+  workflow: 15
+---
+
+# 认证
+
+OpenClaw 支持模型提供商的 OAuth 和 API 密钥。对于 Anthropic 账户，我们推荐使用 **API 密钥**。对于 Claude 订阅访问，使用 `claude setup-token` 创建的长期令牌。
+
+参阅 [/concepts/oauth](/concepts/oauth) 了解完整的 OAuth 流程和存储布局。
+
+## 推荐的 Anthropic 设置（API 密钥）
+
+如果你直接使用 Anthropic，请使用 API 密钥。
+
+1. 在 Anthropic 控制台创建 API 密钥。
+2. 将其放在 **Gateway 网关主机**（运行 `openclaw gateway` 的机器）上。
+
+```bash
+export ANTHROPIC_API_KEY="..."
+openclaw models status
+```
+
+3. 如果 Gateway 网关在 systemd/launchd 下运行，最好将密钥放在 `~/.openclaw/.env` 中以便守护进程可以读取：
+
+```bash
+cat >> ~/.openclaw/.env <<'EOF'
+ANTHROPIC_API_KEY=...
+EOF
+```
+
+然后重启守护进程（或重启你的 Gateway 网关进程）并重新检查：
+
+```bash
+openclaw models status
+openclaw doctor
+```
+
+如果你不想自己管理环境变量，新手引导向导可以为守护进程使用存储 API 密钥：`openclaw onboard`。
+
+参阅[帮助](/help)了解环境变量继承的详情（`env.shellEnv`、`~/.openclaw/.env`、systemd/launchd）。
+
+## Anthropic：setup-token（订阅认证）
+
+对于 Anthropic，推荐的路径是 **API 密钥**。如果你使用 Claude 订阅，也支持 setup-token 流程。在 **Gateway 网关主机**上运行：
+
+```bash
+claude setup-token
+```
+
+然后将其粘贴到 OpenClaw：
+
+```bash
+openclaw models auth setup-token --provider anthropic
+```
+
+如果令牌是在另一台机器上创建的，手动粘贴：
+
+```bash
+openclaw models auth paste-token --provider anthropic
+```
+
+如果你看到类似这样的 Anthropic 错误：
+
+```
+This credential is only authorized for use with Claude Code and cannot be used for other API requests.
+```
+
+…请改用 Anthropic API 密钥。
+
+手动令牌输入（任何提供商；写入 `auth-profiles.json` + 更新配置）：
+
+```bash
+openclaw models auth paste-token --provider anthropic
+openclaw models auth paste-token --provider openrouter
+```
+
+自动化友好检查（过期/缺失时退出 `1`，即将过期时退出 `2`）：
+
+```bash
+openclaw models status --check
+```
+
+可选的运维脚本（systemd/Termux）在此处记录：[/automation/auth-monitoring](/automation/auth-monitoring)
+
+> `claude setup-token` 需要交互式 TTY。
+
+## 检查模型认证状态
+
+```bash
+openclaw models status
+openclaw doctor
+```
+
+## 控制使用哪个凭证
+
+### 每会话（聊天命令）
+
+使用 `/model <alias-or-id>@<profileId>` 为当前会话固定特定的提供商凭证（示例配置文件 ID：`anthropic:default`、`anthropic:work`）。
+
+使用 `/model`（或 `/model list`）获取紧凑的选择器；使用 `/model status` 获取完整视图（候选项 + 下一个认证配置文件，以及配置时的提供商端点详情）。
+
+### 每智能体（CLI 覆盖）
+
+为智能体设置显式的认证配置文件顺序覆盖（存储在该智能体的 `auth-profiles.json` 中）：
+
+```bash
+openclaw models auth order get --provider anthropic
+openclaw models auth order set --provider anthropic anthropic:default
+openclaw models auth order clear --provider anthropic
+```
+
+使用 `--agent <id>` 指定特定智能体；省略它则使用配置的默认智能体。
+
+## 故障排除
+
+### "No credentials found"
+
+如果 Anthropic 令牌配置文件缺失，在 **Gateway 网关主机**上运行 `claude setup-token`，然后重新检查：
+
+```bash
+openclaw models status
+```
+
+### 令牌即将过期/已过期
+
+运行 `openclaw models status` 确认哪个配置文件即将过期。如果配置文件缺失，重新运行 `claude setup-token` 并再次粘贴令牌。
+
+## 要求
+
+- Claude Max 或 Pro 订阅（用于 `claude setup-token`）
+- 已安装 Claude Code CLI（`claude` 命令可用）

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)