网关端口、已在运行和远程模式
Gateway:端口、“已在运行”与远程模式¶
Gateway 使用哪个端口?
gateway.port 控制 WebSocket + HTTP(控制界面、钩子等)的单一多路复用端口。优先级:
为什么 openclaw gateway status 报告进程正在运行,但连接探测失败?
“Running”是守护进程管理器(launchd/systemd/schtasks)视角下的状态;连接性检查则是 CLI 实际连接到 Gateway WebSocket。在 openclaw gateway status 中,将连接目标 URL 与 Listening:(实际绑定在端口上的地址)进行比较;当进程存活但端口未监听时,查看 Last gateway error: 以了解失败原因。
为什么 openclaw gateway status 显示的 “Config (cli)” 和 “Config (service)” 不同?
你正在编辑一个配置文件,而服务运行的是另一个(通常是 --profile / OPENCLAW_STATE_DIR 不匹配)。
修复方法:从你希望服务使用的同一个 --profile / 环境中运行:
“another gateway instance is already listening”是什么意思?
OpenClaw 在启动时会立即绑定 WebSocket 监听器(默认 ws://127.0.0.1:18789),以此实施运行时锁。如果绑定失败并返回 EADDRINUSE,它会抛出 GatewayLockError(“另一个网关实例已在监听”)。
修复方法:停止另一个实例、释放端口,或使用 openclaw gateway --port <port> 运行。
如何以远程模式运行 OpenClaw(客户端连接到其他位置的 Gateway)?
将 gateway.mode: "remote" 并指向远程 WebSocket URL,可选地附带共享密钥远程凭据:
{
gateway: {
mode: "remote",
remote: {
url: "ws://gateway.tailnet:18789",
token: "your-token",
password: "your-password",
},
},
}
- 仅当
gateway.mode为local时(或你传递覆盖标志时),openclaw gateway才会启动。 - macOS 应用会监听配置文件,并在这些值更改时实时切换模式。
gateway.remote.token/.password仅是客户端侧的远程凭据;它们本身不会启用本地 Gateway 认证。
控制界面显示“unauthorized”(或持续重连)。接下来怎么办?
你的 Gateway 认证路径与界面的认证方式不匹配。
事实(来自代码):
- 控制界面将令牌保存在
sessionStorage中,范围限定为当前浏览器标签页和所选 Gateway URL,因此在同一标签页内刷新可继续正常工作,无需在 localStorage 中长期持久化令牌。 - 在
AUTH_TOKEN_MISMATCH时,如果 Gateway 返回重试提示(canRetryWithDeviceToken=true、recommendedNextStep=retry_with_device_token),受信任的客户端可使用缓存的设备令牌进行一次性有限重试。 - 该缓存令牌重试会复用与设备令牌一起存储的已批准作用域;显式传入
deviceToken/ 显式传入scopes的调用方则保留其请求的作用域集合,而不是继承缓存的作用域。 - 在该重试路径之外,连接认证的优先级为:显式共享令牌/密码优先,其次是显式
deviceToken,然后是存储的设备令牌,最后是引导令牌。 - 内置设置码引导会返回一个
scopes: []的节点设备令牌,外加一个用于受信任移动端接入的有限操作员交接令牌。操作员交接令牌可以读取设置期间的原生配置,但不会授予配对变更作用域或operator.admin。
修复方法:
- 最快:
openclaw 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,然后在控制界面设置中粘贴匹配的密钥。 - Tailscale Serve 模式:确认已启用
gateway.auth.allowTailscale,并且你打开的是 Serve URL,而不是绕过了 Tailscale 身份头的原始回环/tailnet URL。 - 受信任代理模式:确认你正通过已配置的身份感知代理访问。同主机回环代理还需要
gateway.auth.trustedProxy.allowLoopback = true。 - 一次重试后不匹配仍然存在:轮换/重新批准配对的设备令牌:
- 轮换被拒绝:配对设备会话只能轮换自己的设备,除非它们还拥有
operator.admin;并且显式传入的--scope值不能超出调用者当前的操作员作用域。 - 仍然无法解决:运行
openclaw status --all并参阅故障排除。认证详情请参见仪表板。
我将 gateway.bind 设置为 tailnet,但它只在回环地址上监听
tailnet 绑定会从你的网络接口中选取一个 Tailscale IP(100.64.0.0/10)。如果该机器未接入 Tailscale(或接口已关闭),Gateway 会回退到回环地址,而不是暴露其他网络接口。
修复方法:在该主机上启动 Tailscale 并重启 Gateway,或明确切换到 gateway.bind: "loopback" / "lan"。
tailnet 是明确指定的;auto 则优先使用回环地址。使用 gateway.bind: "tailnet" 可以在保留所需的同主机 127.0.0.1 监听器的同时,将非回环暴露限制在 Tailnet 内。
我可以在同一主机上运行多个 Gateway 吗?
通常不可以——一个 Gateway 可以运行多个消息渠道和代理。仅在需要冗余(例如救援机器人)或硬隔离时才使用多个 Gateway,并通过各自的 OPENCLAW_CONFIG_PATH、OPENCLAW_STATE_DIR、agents.defaults.workspace 和唯一的 gateway.port 进行隔离。
推荐:每个实例使用 openclaw --profile <name> ...(自动创建 ~/.openclaw-<name>),每个配置文件使用唯一的 gateway.port(或手动运行时使用 --port),并通过 openclaw --profile <name> gateway install 为每个配置文件安装服务。
配置文件还会为服务名称添加后缀:launchd `ai.openclaw.<profile>`、systemd `openclaw-gateway-<profile>.service`、Windows `OpenClaw Gateway (<profile>)`。不带配置文件限定的 `openclaw-gateway` systemd 单元仅存在于默认配置文件;旧的重命名前 systemd 单元名称 `clawdbot-gateway` 会自动迁移。
完整指南:[多个 Gateway](../../gateway/multiple-gateways.md)。
“无效握手” / 代码 1008 是什么意思?
Gateway 是一个 WebSocket 服务器,并期望第一条消息是 connect 帧。其他任何内容都会以 代码 1008(策略违规)关闭连接。
常见原因:你在浏览器中打开了 HTTP URL,而不是使用 WS 客户端;使用了错误的端口/路径;或代理/隧道移除了认证头,或发送了非 Gateway 请求。
修复:使用 WS URL(ws://<host>:18789,或 HTTPS 下的 wss://...),不要通过普通浏览器标签页打开 WS 端口,并在启用认证时在 connect 帧中包含 token/密码。CLI/TUI 示例:
协议详情:Gateway 协议。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw