Gateway

OpenClaw 使用 Bonjour（mDNS / DNS‑SD）作为仅限局域网的便捷方式来发现 活跃的 Gateway 网关（WebSocket 端点）。这是尽力而为的，不能替代 SSH 或 基于 Tailnet 的连接。 通过 Tailscale 的广域 Bonjour（单播 DNS‑SD） 如果节点和 Gateway 网关在不同的网络上，多播 mDNS 无法跨越 边界。你可以通过切换到基于 Tailscale 的单播 DNS‑SD （“广域 Bonjour”）来保持相同的设备发现用户体验。 概要步骤： 在 Gateway 网关主机上运行 DNS 服务器（可通过 Tailnet 访问）。 在专用区域下发布 _openclaw-gw._tcp 的 DNS‑SD 记录 （示例：openclaw.internal.）。 配置 Tailscale 分割 DNS，使你选择的域名通过该 DNS 服务器为客户端（包括 iOS）解析。 OpenClaw 支持任何发现域名；openclaw.internal. 只是一个示例。 iOS/Android 节点同时浏览 local. 和你配置的广域域名。 Gateway 网关配置（推荐） { gateway: { bind: "tailnet" }, // 仅 tailnet（推荐） discovery: { wideArea: { enabled: true } }, // 启用广域 DNS-SD 发布 } 一次性 DNS 服务器设置（Gateway 网关主机） openclaw dns setup --apply 这会安装 CoreDNS 并配置它： ...

Bridge 协议是一个旧版节点传输（TCP JSONL）。新的节点客户端应该使用统一的 Gateway 网关 WebSocket 协议。 如果你正在构建操作者或节点客户端，请使用 Gateway 网关协议。 注意： 当前的 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，以便节点可以固定证书。 握手 + 配对 客户端发送带有节点元数据 + 令牌（如果已配对）的 hello。 如果未配对，Gateway 网关回复 error（NOT_PAIRED/UNAUTHORIZED）。 客户端发送 pair-request。 Gateway 网关等待批准，然后发送 pair-ok 和 hello-ok。 hello-ok 返回 serverName，可能包含 canvasHostUrl。 ...

当 API 提供商宕机、被限流或暂时异常时，OpenClaw 可以运行本地 AI CLI 作为纯文本回退。这是有意保守的设计： 工具被禁用（无工具调用）。 文本输入 → 文本输出（可靠）。 支持会话（因此后续轮次保持连贯）。 如果 CLI 接受图像路径，图像可以传递。 这被设计为安全网而非主要路径。当你想要"始终有效"的文本响应而不依赖外部 API 时使用它。 新手友好快速开始 你可以无需任何配置使用 Claude Code CLI（OpenClaw 自带内置默认值）： openclaw agent --message "hi" --model claude-cli/opus-4.5 Codex CLI 也可以开箱即用： openclaw agent --message "hi" --model codex-cli/gpt-5.2-codex 如果你的 Gateway 网关在 launchd/systemd 下运行且 PATH 很精简，只需添加命令路径： { agents: { defaults: { cliBackends: { "claude-cli": { command: "/opt/homebrew/bin/claude", }, }, }, }, } 就这样。除了 CLI 本身外，不需要密钥，不需要额外的认证配置。 作为回退使用 将 CLI 后端添加到你的回退列表中，这样它只在主要模型失败时运行： { 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": {}, }, }, }, } 注意事项： ...

openclaw doctor 是 OpenClaw 的修复 + 迁移工具。它修复过时的配置/状态，检查健康状况，并提供可操作的修复步骤。 快速开始 openclaw doctor 无头/自动化 openclaw doctor --yes 无需提示接受默认值（包括适用时的重启/服务/沙箱修复步骤）。 openclaw doctor --repair 无需提示应用推荐的修复（安全时进行修复 + 重启）。 openclaw doctor --repair --force 也应用激进的修复（覆盖自定义 supervisor 配置）。 openclaw doctor --non-interactive 无需提示运行，仅应用安全迁移（配置规范化 + 磁盘状态移动）。跳过需要人工确认的重启/服务/沙箱操作。 检测到时自动运行遗留状态迁移。 openclaw doctor --deep 扫描系统服务以查找额外的 Gateway 网关安装（launchd/systemd/schtasks）。 如果你想在写入前查看更改，请先打开配置文件： cat ~/.openclaw/openclaw.json 功能概述 git 安装的可选预检更新（仅交互模式）。 UI 协议新鲜度检查（当协议 schema 较新时重建 Control UI）。 健康检查 + 重启提示。 Skills 状态摘要（符合条件/缺失/被阻止）。 遗留值的配置规范化。 OpenCode Zen 提供商覆盖警告（models.providers.opencode）。 遗留磁盘状态迁移（会话/智能体目录/WhatsApp 认证）。 状态完整性和权限检查（会话、记录、状态目录）。 本地运行时的配置文件权限检查（chmod 600）。 模型认证健康：检查 OAuth 过期，可刷新即将过期的 token，并报告认证配置文件冷却/禁用状态。 额外工作区目录检测（~/openclaw）。 启用沙箱隔离时的沙箱镜像修复。 遗留服务迁移和额外 Gateway 网关检测。 Gateway 网关运行时检查（服务已安装但未运行；缓存的 launchd 标签）。 渠道状态警告（从运行中的 Gateway 网关探测）。 Supervisor 配置审计（launchd/systemd/schtasks）及可选修复。 Gateway 网关运行时最佳实践检查（Node vs Bun，版本管理器路径）。 Gateway 网关端口冲突诊断（默认 18789）。 开放私信策略的安全警告。 未设置 gateway.auth.token 时的 Gateway 网关认证警告（本地模式；提供 token 生成）。 Linux 上的 systemd linger 检查。 源码安装检查（pnpm workspace 不匹配、缺失 UI 资产、缺失 tsx 二进制文件）。 写入更新后的配置 + 向导元数据。 详细行为和原理 0）可选更新（git 安装） 如果这是 git 检出且 doctor 以交互模式运行，它会在运行 doctor 之前提供更新（fetch/rebase/build）。 ...

Gateway 网关 WS 协议是 OpenClaw 的单一控制平面 + 节点传输。所有客户端（CLI、Web UI、macOS 应用、iOS/Android 节点、无头节点）都通过 WebSocket 连接，并在握手时声明其角色 + 作用域。 传输 WebSocket，带有 JSON 负载的文本帧。 第一帧必须是 connect 请求。 握手（connect） Gateway 网关 → 客户端（连接前质询）： { "type": "event", "event": "connect.challenge", "payload": { "nonce": "…", "ts": 1737264000000 } } 客户端 → Gateway 网关： { "type": "req", "id": "…", "method": "connect", "params": { "minProtocol": 3, "maxProtocol": 3, "client": { "id": "cli", "version": "1.2.3", "platform": "macos", "mode": "operator" }, "role": "operator", "scopes": ["operator.read", "operator.write"], "caps": [], "commands": [], "permissions": {}, "auth": { "token": "…" }, "locale": "en-US", "userAgent": "openclaw-cli/1.2.3", "device": { "id": "device_fingerprint", "publicKey": "…", "signature": "…", "signedAt": 1737264000000, "nonce": "…" } } } Gateway 网关 → 客户端： ...

在 Gateway 网关拥有的配对中，Gateway 网关是允许哪些节点加入的唯一信息源。UI（macOS 应用、未来的客户端）只是审批或拒绝待处理请求的前端。 重要：WS 节点在 connect 期间使用设备配对（角色 node）。node.pair.* 是一个独立的配对存储，不会限制 WS 握手。只有显式调用 node.pair.* 的客户端使用此流程。 概念 待处理请求：一个节点请求加入；需要审批。 已配对节点：已批准的节点，带有已颁发的认证令牌。 传输层：Gateway 网关 WS 端点转发请求但不决定成员资格。（旧版 TCP 桥接支持已弃用/移除。） 配对工作原理 节点连接到 Gateway 网关 WS 并请求配对。 Gateway 网关存储一个待处理请求并发出 node.pair.requested。 你审批或拒绝该请求（CLI 或 UI）。 审批后，Gateway 网关颁发一个新令牌（重新配对时令牌会轮换）。 节点使用该令牌重新连接，现在是"已配对"状态。 待处理请求在 5 分钟后自动过期。 CLI 工作流程（支持无头模式） openclaw nodes pending openclaw nodes approve <requestId> openclaw nodes reject <requestId> openclaw nodes status openclaw nodes rename --node <id|name|ip> --name "Living Room iPad" nodes status 显示已配对/已连接的节点及其功能。 API 接口（Gateway 网关协议） 事件： ...

最后更新：2025-12-11 原因 确保同一主机上每个基础端口只运行一个 Gateway 网关实例；额外的 Gateway 网关必须使用隔离的配置文件和唯一的端口。 在崩溃/SIGKILL 后不留下过时的锁文件。 当控制端口已被占用时快速失败并给出清晰的错误。 机制 Gateway 网关在启动时立即使用独占 TCP 监听器绑定 WebSocket 监听器（默认 ws://127.0.0.1:18789）。 如果绑定因 EADDRINUSE 失败，启动会抛出 GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")。 操作系统在任何进程退出时（包括崩溃和 SIGKILL）自动释放监听器——不需要单独的锁文件或清理步骤。 关闭时，Gateway 网关关闭 WebSocket 服务器和底层 HTTP 服务器以及时释放端口。 错误表面 如果另一个进程持有端口，启动会抛出 GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")。 其他绑定失败会显示为 GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")。 运维说明 如果端口被另一个进程占用，错误是相同的；释放端口或使用 openclaw gateway --port <port> 选择另一个端口。 macOS 应用在启动 Gateway 网关之前仍维护自己的轻量级 PID 保护；运行时锁由 WebSocket 绑定强制执行。

OpenClaw 的 Gateway 网关可以提供一个小型的 OpenAI 兼容 Chat Completions 端点。 此端点默认禁用。请先在配置中启用它。 POST /v1/chat/completions 与 Gateway 网关相同的端口（WS + HTTP 多路复用）：http://<gateway-host>:<port>/v1/chat/completions 底层实现中，请求作为普通的 Gateway 网关智能体运行执行（与 openclaw agent 相同的代码路径），因此路由/权限/配置与你的 Gateway 网关一致。 认证 使用 Gateway 网关认证配置。发送 bearer 令牌： Authorization: Bearer <token> 注意事项： 当 gateway.auth.mode="token" 时，使用 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）。 当 gateway.auth.mode="password" 时，使用 gateway.auth.password（或 OPENCLAW_GATEWAY_PASSWORD）。 选择智能体 无需自定义头：在 OpenAI model 字段中编码智能体 ID： model: "openclaw:<agentId>"（例如："openclaw:main"、"openclaw:beta"） model: "agent:<agentId>"（别名） 或通过头指定特定的 OpenClaw 智能体： x-openclaw-agent-id: <agentId>（默认：main） 高级选项： x-openclaw-session-key: <sessionKey> 完全控制会话路由。 启用端点 将 gateway.http.endpoints.chatCompletions.enabled 设置为 true： ...

OpenClaw 的 Gateway 网关可以提供兼容 OpenResponses 的 POST /v1/responses 端点。 此端点默认禁用。请先在配置中启用。 POST /v1/responses 与 Gateway 网关相同的端口（WS + HTTP 多路复用）：http://<gateway-host>:<port>/v1/responses 底层实现中，请求作为正常的 Gateway 网关智能体运行执行（与 openclaw agent 相同的代码路径），因此路由/权限/配置与你的 Gateway 网关一致。 认证 使用 Gateway 网关认证配置。发送 bearer 令牌： Authorization: Bearer <token> 说明： 当 gateway.auth.mode="token" 时，使用 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）。 当 gateway.auth.mode="password" 时，使用 gateway.auth.password（或 OPENCLAW_GATEWAY_PASSWORD）。 选择智能体 无需自定义头：在 OpenResponses model 字段中编码智能体 id： model: "openclaw:<agentId>"（示例："openclaw:main"、"openclaw:beta"） model: "agent:<agentId>"（别名） 或通过头指定特定的 OpenClaw 智能体： x-openclaw-agent-id: <agentId>（默认：main） 高级： x-openclaw-session-key: <sessionKey> 完全控制会话路由。 启用端点 将 gateway.http.endpoints.responses.enabled 设置为 true： ...

OpenClaw 可以为 Gateway 网关仪表盘和 WebSocket 端口自动配置 Tailscale Serve（tailnet）或 Funnel（公共）。这使 Gateway 网关保持绑定到 loopback，同时 Tailscale 提供 HTTPS、路由和（对于 Serve）身份头。 模式 serve：仅限 Tailnet 的 Serve，通过 tailscale serve。Gateway 网关保持在 127.0.0.1 上。 funnel：通过 tailscale funnel 的公共 HTTPS。OpenClaw 需要共享密码。 off：默认（无 Tailscale 自动化）。 认证 设置 gateway.auth.mode 来控制握手： token（设置 OPENCLAW_GATEWAY_TOKEN 时的默认值） password（通过 OPENCLAW_GATEWAY_PASSWORD 或配置的共享密钥） 当 tailscale.mode = "serve" 且 gateway.auth.allowTailscale 为 true 时， 有效的 Serve 代理请求可以通过 Tailscale 身份头（tailscale-user-login）进行认证，无需提供令牌/密码。OpenClaw 通过本地 Tailscale 守护进程（tailscale whois）解析 x-forwarded-for 地址并将其与头匹配来验证身份，然后才接受它。 OpenClaw 仅在请求从 loopback 到达并带有 Tailscale 的 x-forwarded-for、x-forwarded-proto 和 x-forwarded-host 头时才将其视为 Serve 请求。 要要求显式凭证，设置 gateway.auth.allowTailscale: false 或强制 gateway.auth.mode: "password"。 ...