网关端口、已运行和远程模式

gateway.port 控制 WebSocket + HTTP（Control UI、hooks 等）的单一多路复用端口。优先级如下：

--port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789

“Running” 是 supervisor（launchd/systemd/schtasks）视角下的状态；connectivity probe 则是 CLI 实际连接到 Gateway WebSocket 的结果。请以 openclaw gateway status 中的这些行为准：Probe target:（探针使用的 URL）、Listening:（端口上实际绑定的地址）、Last gateway error:（进程存活但端口未监听时的常见根本原因）。

你在编辑一个配置文件，而服务运行的是另一个配置（通常是 --profile / OPENCLAW_STATE_DIR 不匹配）。

解决办法：在你希望服务使用的同一个 --profile / 环境中运行：

openclaw gateway install --force

OpenClaw 通过启动时立即绑定 WebSocket 监听器（默认 ws://127.0.0.1:18789）来强制运行时锁。如果绑定失败并返回 EADDRINUSE，它会抛出 GatewayLockError（“another gateway instance is already listening”）。

解决办法：停止另一个实例，释放端口，或使用 openclaw gateway --port <port> 运行。

设置 gateway.mode: "remote" 并指向远程 WebSocket URL，可选地附带共享密钥远程凭据：

{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://gateway.tailnet:18789",
      token: "your-token",
      password: "your-password",
    },
  },
}

• openclaw gateway 仅在 gateway.mode 为 local（或你传入覆盖标志）时启动。
• macOS 应用会监视配置文件，并在这些值更改时实时切换模式。
• gateway.remote.token / .password 仅是客户端侧的远程凭据；它们本身不会启用本地 Gateway 认证。

你的 Gateway 认证路径与 UI 的认证方式不匹配。

事实（来自代码）：

• Control UI 将令牌保存在 sessionStorage 中，范围限于当前浏览器标签页和所选 Gateway URL，因此同一标签页的刷新可以继续工作，而无需持久的 localStorage 令牌持久化。
• 在 AUTH_TOKEN_MISMATCH 时，当 Gateway 返回重试提示（canRetryWithDeviceToken=true、recommendedNextStep=retry_with_device_token）时，受信任的客户端可以尝试一次有限制的重试，使用缓存的设备令牌。
• 该缓存令牌重试会复用与设备令牌一同存储的已批准作用域；显式 deviceToken / 显式 scopes 调用者保留其请求的作用域集合，而不是继承缓存的作用域。
• 在该重试路径之外，连接认证的优先级顺序为：显式共享令牌/密码优先，然后是显式 deviceToken，再是已存储的设备令牌，最后是引导令牌。
• 内置设置码引导程序返回一个 scopes: [] 的节点设备令牌，外加一个用于受信任移动设备接入的有限制操作员交接令牌。操作员交接令牌可以读取设置时的本机配置，但不授予配对修改作用域或 operator.admin。

解决办法：

• 最快：openclaw dashboard（打印并复制 dashboard URL，尝试打开；如果是无头环境则显示 SSH 提示）。
• 还没有令牌：openclaw doctor --generate-gateway-token。
• 远程：先用 ssh -N -L 18789:127.0.0.1:18789 user@host 建立隧道，然后打开 http://127.0.0.1:18789/。
• 共享密钥模式：设置 gateway.auth.token / OPENCLAW_GATEWAY_TOKEN 或 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD，然后在 Control UI 设置中粘贴匹配的密钥。
• Tailscale Serve 模式：确认已启用 gateway.auth.allowTailscale，并且你打开的是 Serve URL，而不是绕过了 Tailscale 身份头的原始 loopback/tailnet URL。
• 受信任代理模式：确认你是通过所配置的识别身份代理访问的。同主机的 loopback 代理还需要 gateway.auth.trustedProxy.allowLoopback = true。
• 在一次重试后仍然不匹配：轮换/重新批准配对的设备令牌：

  openclaw devices list
  openclaw devices rotate --device <id> --role operator
  

• 轮换被拒绝：配对设备会话只能轮换自己的设备，除非它们还拥有 operator.admin；并且显式的 --scope 值不能超出调用者当前的操作员作用域。
• 仍然卡住：运行 openclaw status --all，并查看 Troubleshooting。认证详情请参阅 Dashboard。

tailnet 绑定会从你的网络接口（100.64.0.0/10）中选择一个 Tailscale IP。如果机器不在 Tailscale 上（或该接口处于关闭状态），Gateway 会回退到 loopback，而不是暴露其他网络接口。

解决办法：在该主机上启动 Tailscale 并重启 Gateway，或显式切换到 gateway.bind: "loopback" / "lan"。

tailnet 是显式选择；auto 则优先使用 loopback。使用 gateway.bind: "tailnet" 可以将非 loopback 暴露限制在 Tailnet 内，同时保留所需的同主机 127.0.0.1 监听器。

通常不可以——一个 Gateway 可以运行多个消息通道和 agent。仅在需要冗余（例如救援机器人）或硬隔离时才使用多个 Gateway，并用各自的 OPENCLAW_CONFIG_PATH、OPENCLAW_STATE_DIR、agents.defaults.workspace 和唯一的 gateway.port 相互隔离。

Gateway 是一个 WebSocket 服务器，期望第一条消息是 connect 帧。其他任何内容都会以 代码 1008（策略违规）关闭连接。

常见原因：你在浏览器中打开了 HTTP 地址而不是使用 WS 客户端；使用了错误的端口/路径；或者代理/隧道剥离了认证头，或发送了非 Gateway 的请求。

解决方法：使用 WS 地址（ws://<host>:18789，HTTPS 下使用 wss://...）；不要在日常浏览器标签页中打开 WS 端口；并在启用认证时，在 connect 帧中包含 token/密码。CLI/TUI 示例：

openclaw tui --url ws://<host>:18789 --token <token>

协议详情：Gateway 协议。