@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/debug/node-issue.md

@@ -0,0 +1,90 @@
+---
+read_when:
+  - 调试仅限 Node 的开发脚本或 watch 模式失败
+  - 排查 QuantumClaw 中 tsx/esbuild 加载器崩溃问题
+summary: Node + tsx "__name is not a function" 崩溃说明及解决方法
+title: Node + tsx 崩溃
+x-i18n:
+  generated_at: "2026-02-01T20:24:52Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: f9e9bd2281508337a0696126b0db2d47a2d0f56de7a11872fbc0ac4689f9ad41
+  source_path: debug/node-issue.md
+  workflow: 14
+---
+
+# Node + tsx "\_\_name is not a function" 崩溃
+
+## 概述
+
+通过 Node 使用 `tsx` 运行 QuantumClaw 时，启动阶段报错：
+
+```
+[quantumclaw] Failed to start CLI: TypeError: __name is not a function
+    at createSubsystemLogger (.../src/logging/subsystem.ts:203:25)
+    at .../src/agents/auth-profiles/constants.ts:25:20
+```
+
+此问题在开发脚本从 Bun 切换到 `tsx` 后出现（提交 `2871657e`，2026-01-06）。相同的运行路径在 Bun 下正常工作。
+
+## 环境
+
+- Node: v25.x（在 v25.3.0 上观察到）
+- tsx: 4.21.0
+- 操作系统: macOS（其他运行 Node 25 的平台也可能复现）
+
+## 复现步骤（仅 Node）
+
+```bash
+# 在仓库根目录
+node --version
+pnpm install
+node --import tsx src/entry.ts status
+```
+
+## 仓库内最小复现
+
+```bash
+node --import tsx scripts/repro/tsx-name-repro.ts
+```
+
+## Node 版本检查
+
+- Node 25.3.0：失败
+- Node 22.22.0（Homebrew `node@22`）：失败
+- Node 24：尚未安装，需要验证
+
+## 说明 / 假设
+
+- `tsx` 使用 esbuild 转换 TS/ESM。esbuild 的 `keepNames` 会生成一个 `__name` 辅助函数，并用 `__name(...)` 包裹函数定义。
+- 崩溃表明 `__name` 存在但在运行时不是函数，这意味着在 Node 25 的加载器路径中该辅助函数缺失或被覆盖。
+- 其他 esbuild 使用者也报告过类似的 `__name` 辅助函数缺失或被重写的问题。
+
+## 回归历史
+
+- `2871657e`（2026-01-06）：脚本从 Bun 改为 tsx，使 Bun 成为可选项。
+- 在此之前（Bun 路径），`quantumclaw status` 和 `gateway:watch` 均正常工作。
+
+## 解决方法
+
+- 开发脚本使用 Bun（当前临时回退方案）。
+- 使用 Node + tsc watch，然后运行编译产物：
+  ```bash
+  pnpm exec tsc --watch --preserveWatchOutput
+  node --watch quantumclaw.mjs status
+  ```
+- 已在本地确认：`pnpm exec tsc -p tsconfig.json` + `node quantumclaw.mjs status` 在 Node 25 上可正常运行。
+- 如果可能，在 TS 加载器中禁用 esbuild 的 keepNames（防止插入 `__name` 辅助函数）；tsx 目前不提供此配置项。
+- 在 Node LTS（22/24）上测试 `tsx`，确认该问题是否为 Node 25 特有。
+
+## 参考资料
+
+- https://opennext.js.org/cloudflare/howtos/keep_names
+- https://esbuild.github.io/api/#keep-names
+- https://github.com/evanw/esbuild/issues/1031
+
+## 后续步骤
+
+- 在 Node 22/24 上复现，确认是否为 Node 25 回归问题。
+- 测试 `tsx` nightly 版本，或在存在已知回归时固定到早期版本。
+- 如果在 Node LTS 上也能复现，则向上游提交包含 `__name` 堆栈跟踪的最小复现。

package/docs/zh-CN/diagnostics/flags.md

@@ -0,0 +1,98 @@
+---
+read_when:
+  - 你需要定向调试日志而不提高全局日志级别
+  - 你需要为支持人员捕获特定子系统的日志
+summary: 用于定向调试日志的诊断标志
+title: 诊断标志
+x-i18n:
+  generated_at: "2026-02-03T10:05:34Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: daf0eca0e6bd1cbc2c400b2e94e1698709a96b9cdba1a8cf00bd580a61829124
+  source_path: diagnostics/flags.md
+  workflow: 15
+---
+
+# 诊断标志
+
+诊断标志让你可以启用定向调试日志，而无需在所有地方开启详细日志。标志是可选启用的，除非子系统检查它们，否则不会生效。
+
+## 工作原理
+
+- 标志是字符串（不区分大小写）。
+- 你可以在配置中或通过环境变量覆盖来启用标志。
+- 支持通配符：
+  - `telegram.*` 匹配 `telegram.http`
+  - `*` 启用所有标志
+
+## 通过配置启用
+
+```json
+{
+  "diagnostics": {
+    "flags": ["telegram.http"]
+  }
+}
+```
+
+多个标志：
+
+```json
+{
+  "diagnostics": {
+    "flags": ["telegram.http", "gateway.*"]
+  }
+}
+```
+
+更改标志后重启 Gateway 网关。
+
+## 环境变量覆盖（一次性）
+
+```bash
+QUANTUMCLAW_DIAGNOSTICS=telegram.http,telegram.payload
+```
+
+禁用所有标志：
+
+```bash
+QUANTUMCLAW_DIAGNOSTICS=0
+```
+
+## 日志存储位置
+
+标志将日志输出到标准诊断日志文件。默认位置：
+
+```
+/tmp/quantumclaw/quantumclaw-YYYY-MM-DD.log
+```
+
+如果你设置了 `logging.file`，则使用该路径。日志为 JSONL 格式（每行一个 JSON 对象）。脱敏仍然根据 `logging.redactSensitive` 应用。
+
+## 提取日志
+
+选择最新的日志文件：
+
+```bash
+ls -t /tmp/quantumclaw/quantumclaw-*.log | head -n 1
+```
+
+过滤 Telegram HTTP 诊断：
+
+```bash
+rg "telegram http error" /tmp/quantumclaw/quantumclaw-*.log
+```
+
+或在复现时使用 tail：
+
+```bash
+tail -f /tmp/quantumclaw/quantumclaw-$(date +%F).log | rg "telegram http error"
+```
+
+对于远程 Gateway 网关，你也可以使用 `quantumclaw logs --follow`（参见 [/cli/logs](/cli/logs)）。
+
+## 注意事项
+
+- 如果 `logging.level` 设置为高于 `warn`，这些日志可能会被抑制。默认的 `info` 级别即可。
+- 标志可以安全地保持启用状态；它们只影响特定子系统的日志量。
+- 使用 [/logging](/logging) 更改日志目标、级别和脱敏设置。

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

@@ -0,0 +1,184 @@
+---
+read_when:
+  - 调试模型认证或 OAuth 过期
+  - 编写有关认证或凭证存储的文档
+summary: 模型认证：OAuth、API key 和 setup-token
+title: 认证
+x-i18n:
+  generated_at: "2026-03-16T06:22:17Z"
+  model: gpt-5.4
+  provider: openai
+  source_hash: 219ac1acd7d192a5a12779e204cca65dae77a852fdc668271c45c01e0c69b7c9
+  source_path: gateway/authentication.md
+  workflow: 15
+---
+
+# 认证
+
+QuantumClaw 支持模型提供商使用 OAuth 和 API key。对于始终在线的 Gateway 网关
+主机，API key 通常是最可预测的选项。当它们与你的提供商账号模型匹配时，
+也支持订阅/OAuth 流程。
+
+完整的 OAuth 流程和存储布局，请参阅 [/concepts/oauth](/concepts/oauth)。
+关于基于 SecretRef 的认证（`env`/`file`/`exec` 提供商），请参阅 [Secrets Management](/gateway/secrets)。
+关于 `models status --probe` 使用的凭证资格/原因码规则，请参阅
+[Auth Credential Semantics](/auth-credential-semantics)。
+
+## 推荐设置（API key，任意提供商）
+
+如果你正在运行长期存活的 Gateway 网关，请先为你选择的
+提供商配置一个 API key。
+对于 Anthropic，API key 认证是更稳妥的方式，推荐优先于
+订阅 setup-token 认证。
+
+1. 在你的提供商控制台中创建一个 API key。
+2. 将它放在 **Gateway 网关主机** 上（运行 `quantumclaw gateway` 的机器）。
+
+```bash
+export <PROVIDER>_API_KEY="..."
+quantumclaw models status
+```
+
+3. 如果 Gateway 通过 systemd/launchd 运行，建议将 key 放入
+   `~/.quantumclaw/.env`，这样守护进程就可以读取它：
+
+```bash
+cat >> ~/.quantumclaw/.env <<'EOF'
+<PROVIDER>_API_KEY=...
+EOF
+```
+
+然后重启守护进程（或重启你的 Gateway 网关进程）并重新检查：
+
+```bash
+quantumclaw models status
+quantumclaw doctor
+```
+
+如果你不想自己管理环境变量，设置向导可以为守护进程使用场景存储
+API key：`quantumclaw onboard`。
+
+有关环境继承（`env.shellEnv`、
+`~/.quantumclaw/.env`、systemd/launchd）的详细信息，请参阅 [Help](/help)。
+
+## Anthropic：setup-token（订阅认证）
+
+如果你使用的是 Claude 订阅，则支持 setup-token 流程。请在
+**Gateway 网关主机** 上运行：
+
+```bash
+claude setup-token
+```
+
+然后将它粘贴到 QuantumClaw 中：
+
+```bash
+quantumclaw models auth setup-token --provider anthropic
+```
+
+如果 token 是在另一台机器上创建的，请手动粘贴：
+
+```bash
+quantumclaw 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 key。
+
+<Warning>
+Anthropic setup-token 支持仅是技术兼容性。Anthropic 过去曾阻止
+Claude Code 之外的某些订阅用法。只有在你认为相关策略风险可接受时才使用它，
+并请你自行核实 Anthropic 当前的条款。
+</Warning>
+
+手动输入 token（任意提供商；会写入 `auth-profiles.json` + 更新配置）：
+
+```bash
+quantumclaw models auth paste-token --provider anthropic
+quantumclaw models auth paste-token --provider openrouter
+```
+
+静态凭证也支持凭证配置文件引用：
+
+- `api_key` 凭证可以使用 `keyRef: { source, provider, id }`
+- `token` 凭证可以使用 `tokenRef: { source, provider, id }`
+
+适合自动化的检查（已过期/缺失时退出码为 `1`，即将过期时为 `2`）：
+
+```bash
+quantumclaw models status --check
+```
+
+可选的运维脚本（systemd/Termux）记录在这里：
+[/automation/auth-monitoring](/automation/auth-monitoring)
+
+> `claude setup-token` 需要交互式 TTY。
+
+## 检查模型认证状态
+
+```bash
+quantumclaw models status
+quantumclaw doctor
+```
+
+## API key 轮换行为（Gateway 网关）
+
+某些提供商支持在 API 调用触发提供商限流时，使用替代 key 重试请求。
+
+- 优先级顺序：
+  - `QUANTUMCLAW_LIVE_<PROVIDER>_KEY`（单个覆盖值）
+  - `<PROVIDER>_API_KEYS`
+  - `<PROVIDER>_API_KEY`
+  - `<PROVIDER>_API_KEY_*`
+- Google 提供商还将 `GOOGLE_API_KEY` 作为额外回退项。
+- 使用前会对同一组 key 列表去重。
+- 仅当出现限流错误时，QuantumClaw 才会使用下一个 key 重试（例如
+  `429`、`rate_limit`、`quota`、`resource exhausted`）。
+- 非限流错误不会使用替代 key 重试。
+- 如果所有 key 都失败，则返回最后一次尝试的最终错误。
+
+## 控制使用哪个凭证
+
+### 每个会话（聊天命令）
+
+使用 `/model <alias-or-id>@<profileId>` 为当前会话固定使用特定的提供商凭证（示例配置文件 id：`anthropic:default`、`anthropic:work`）。
+
+使用 `/model`（或 `/model list`）查看紧凑选择器；使用 `/model status` 查看完整视图（候选项 + 下一个凭证配置文件，以及在已配置时显示提供商端点详情）。
+
+### 每个智能体（CLI 覆盖）
+
+为智能体设置显式的凭证配置文件顺序覆盖（存储在该智能体的 `auth-profiles.json` 中）：
+
+```bash
+quantumclaw models auth order get --provider anthropic
+quantumclaw models auth order set --provider anthropic anthropic:default
+quantumclaw models auth order clear --provider anthropic
+```
+
+使用 `--agent <id>` 指定特定智能体；省略它则使用已配置的默认智能体。
+
+## 故障排除
+
+### “No credentials found”
+
+如果缺少 Anthropic token 配置文件，请在
+**Gateway 网关主机** 上运行 `claude setup-token`，然后重新检查：
+
+```bash
+quantumclaw models status
+```
+
+### Token 即将过期/已过期
+
+运行 `quantumclaw models status` 以确认哪个配置文件即将过期。如果该配置文件
+缺失，请重新运行 `claude setup-token` 并再次粘贴 token。
+
+## 要求
+
+- Anthropic 订阅账号（用于 `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 工具
+
+QuantumClaw 通过 `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`：内存输出上限（字符）
+- `QUANTUMCLAW_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 设备发现
+
+QuantumClaw 使用 Bonjour（mDNS / DNS‑SD）作为**仅限局域网的便捷方式**来发现
+活跃的 Gateway 网关（WebSocket 端点）。这是尽力而为的，**不能**替代 SSH 或
+基于 Tailnet 的连接。
+
+## 通过 Tailscale 的广域 Bonjour（单播 DNS‑SD）
+
+如果节点和 Gateway 网关在不同的网络上，多播 mDNS 无法跨越
+边界。你可以通过切换到基于 Tailscale 的**单播 DNS‑SD**
+（"广域 Bonjour"）来保持相同的设备发现用户体验。
+
+概要步骤：
+
+1. 在 Gateway 网关主机上运行 DNS 服务器（可通过 Tailnet 访问）。
+2. 在专用区域下发布 `_quantumclaw-gw._tcp` 的 DNS‑SD 记录
+   （示例：`quantumclaw.internal.`）。
+3. 配置 Tailscale **分割 DNS**，使你选择的域名通过该
+   DNS 服务器为客户端（包括 iOS）解析。
+
+QuantumClaw 支持任何发现域名；`quantumclaw.internal.` 只是一个示例。
+iOS/Android 节点同时浏览 `local.` 和你配置的广域域名。
+
+### Gateway 网关配置（推荐）
+
+```json5
+{
+  gateway: { bind: "tailnet" }, // 仅 tailnet（推荐）
+  discovery: { wideArea: { enabled: true } }, // 启用广域 DNS-SD 发布
+}
+```
+
+### 一次性 DNS 服务器设置（Gateway 网关主机）
+
+```bash
+quantumclaw dns setup --apply
+```
+
+这会安装 CoreDNS 并配置它：
+
+- 仅在 Gateway 网关的 Tailscale 接口上监听 53 端口
+- 从 `~/.quantumclaw/dns/<domain>.db` 提供你选择的域名服务（示例：`quantumclaw.internal.`）
+
+从 Tailnet 连接的机器上验证：
+
+```bash
+dns-sd -B _quantumclaw-gw._tcp quantumclaw.internal.
+dig @<TAILNET_IPV4> -p 53 _quantumclaw-gw._tcp.quantumclaw.internal PTR +short
+```
+
+### Tailscale DNS 设置
+
+在 Tailscale 管理控制台中：
+
+- 添加指向 Gateway 网关 Tailnet IP 的名称服务器（UDP/TCP 53）。
+- 添加分割 DNS，使你的发现域名使用该名称服务器。
+
+一旦客户端接受 Tailnet DNS，iOS 节点就可以在
+你的发现域名中浏览 `_quantumclaw-gw._tcp`，无需多播。
+
+### Gateway 网关监听器安全（推荐）
+
+Gateway 网关 WS 端口（默认 `18789`）默认绑定到 loopback。对于局域网/Tailnet
+访问，请明确绑定并保持认证启用。
+
+对于仅 Tailnet 的设置：
+
+- 在 `~/.quantumclaw/quantumclaw.json` 中设置 `gateway.bind: "tailnet"`。
+- 重启 Gateway 网关（或重启 macOS 菜单栏应用）。
+
+## 什么在广播
+
+只有 Gateway 网关广播 `_quantumclaw-gw._tcp`。
+
+## 服务类型
+
+- `_quantumclaw-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>`（可选；可运行的 `quantumclaw` 入口点的绝对路径）
+- `tailnetDns=<magicdns>`（当 Tailnet 可用时的可选提示）
+
+## 在 macOS 上调试
+
+有用的内置工具：
+
+- 浏览实例：
+  ```bash
+  dns-sd -B _quantumclaw-gw._tcp local.
+  ```
+- 解析单个实例（替换 `<instance>`）：
+  ```bash
+  dns-sd -L "<instance>" _quantumclaw-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` 来发现 `_quantumclaw-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`）。
+
+## 禁用 / 配置
+
+- `QUANTUMCLAW_DISABLE_BONJOUR=1` 禁用广播（旧版：`QUANTUMCLAW_DISABLE_BONJOUR`）。
+- `~/.quantumclaw/quantumclaw.json` 中的 `gateway.bind` 控制 Gateway 网关绑定模式。
+- `QUANTUMCLAW_SSH_PORT` 覆盖 TXT 中广播的 SSH 端口（旧版：`QUANTUMCLAW_SSH_PORT`）。
+- `QUANTUMCLAW_TAILNET_DNS` 在 TXT 中发布 MagicDNS 提示（旧版：`QUANTUMCLAW_TAILNET_DNS`）。
+- `QUANTUMCLAW_CLI_PATH` 覆盖广播的 CLI 路径（旧版：`QUANTUMCLAW_CLI_PATH`）。
+
+## 相关文档
+
+- 设备发现策略和传输选择：[设备发现](/gateway/discovery)
+- 节点配对 + 批准：[Gateway 网关配对](/gateway/pairing)