EADDRINUSE 一定是端口被占吗？

多数是同一机器已有 Gateway 实例或 launchd 重复安装；少数是其他进程占用 18789。用 lsof -i :18789 与 gateway status --deep 确认。

openclaw doctor --fix 会动什么？

会迁移/修复配置、对齐 supervisor 元数据中的 --port、生成缺失 token，并拒绝与 system-level 服务冲突的重复安装。

Runtime running 但连不上怎么办？

看 Probe target、Listening 与 Last gateway error；常见是 auth token 不匹配或 bind 模式与客户端 URL 不一致。

一篇搞定 OpenClaw 90% 网关异常：端口冲突 + 诊断工具实战

Q: OpenClaw Gateway 默认端口是多少？

默认 18789。优先级为 --port > OPENCLAW_GATEWAY_PORT > gateway.port > 18789。

2026 年 6 月 9 日 · OpenClaw 运维 · 约 14 分钟阅读

OpenClaw Gateway 端口 18789 冲突排查与 openclaw doctor 诊断 — Gateway 异常多半不是「OpenClaw 坏了」，而是端口、supervisor 与 auth 三件事没对齐。

把 OpenClaw Gateway 跑在云端 Mac 或本机时，真正让人抓狂的往往不是 Agent 逻辑，而是三类报错循环出现：EADDRINUSE、another gateway instance is already listening，以及「Runtime: running 但 Control UI 就是打不开」。我们在客户工单里统计过一轮：约 90% 的 Gateway 异常，都能在端口占用、supervisor 配置漂移、auth/bind 不匹配这三类里找到根因——不需要重装整套 OpenClaw，更不需要再抄一遍 install.sh 教程。

本文假设 Gateway 已经装过（部署与节点选型见远程 Mac 部署 OpenClaw 实操），只聚焦排障与修复。官方参考：Gateway runbook、Gateway Troubleshooting。

1）先判断：你的 Gateway 卡在哪个阶段？

排障的第一步不是狂敲命令，而是把现象映射到「生命周期阶段」。OpenClaw 把 Gateway 看成supervisor 托管的常驻服务（macOS 上常见为 launchd，标签如 ai.openclaw.gateway），CLI 的连通性探测则是另一套视角——两者不一致时，日志里会出现非常有用的分叉线索。

阶段	典型现象	优先命令
A. 启动失败	`gateway start blocked`、`EADDRINUSE`、进程秒退	`openclaw logs --follow` → `lsof -i :18789`
B. 进程在、端口没监听	`Runtime: running`，但 `Listening:` 为空或 probe 失败	`openclaw gateway status --deep`
C. 端口通、认证失败	浏览器 `unauthorized`、WebSocket 握手 401	`openclaw doctor` → 核对 token
D. 远程访问路径错	SSH 上去本地 curl 正常，笔记本浏览器超时	检查 bind 模式 + SSH 隧道

记下你属于 A/B/C/D 哪一类，后文 Runbook 会按阶段给最短路径。若你还在选型「OpenClaw 与 OpenHuman 怎么分工」，可先读 OpenHuman 养在云端 Mac 上，本文不展开 Agent 业务配置。

2）端口 18789：冲突排查与「谁来监听」

OpenClaw Gateway 默认监听 18789，同一端口复用 WebSocket、Control UI 与 hooks。端口解析优先级（官方）：--port → 环境变量 OPENCLAW_GATEWAY_PORT → 配置文件 gateway.port → 默认 18789。启动时若 bind 失败，会抛出 GatewayLockError / EADDRINUSE，含义很直白：已经有一个实例占着这个端口。

2.1 最常见根因：重复实例 + 重复 supervisor

在远程 Mac 上，我们见过三类高频踩坑：

手动 openclaw gateway 前台跑着一个，后台 launchd 又拉起一个；
改过 gateway.port，但 supervisor 元数据仍钉死旧 --port 18789；
同一用户多次 gateway install，残留多个 profile 争抢端口。

macOS — 查清 18789 被谁占用

# 1) 看谁占端口
lsof -nP -iTCP:18789 -sTCP:LISTEN

# 2) 对照 OpenClaw 视角
openclaw gateway status --deep

# 3) 若确认是残留进程（谨慎执行）
kill <PID>
openclaw gateway restart

官方还提供前台强制清端口再启动：openclaw gateway --force（会 force-kill 监听器后拉起）。生产环境更推荐先 status --deep 看清 supervisor 与 CLI 配置是否一致，再决定是否强杀。

2.2 改端口还是杀进程？

策略	适用场景	注意点
释放 18789，保留默认端口	占用者是旧 Gateway、僵尸 launchd 或误开的前台进程	改完后执行 `openclaw doctor --fix` 或 `gateway install --force` 对齐 supervisor
换端口（如 18790）	同机还要跑其他 dev 服务，或 CI 并行 profile	客户端、SSH 隧道、Control UI 书签必须同步改 URL
拆 profile / 拆机器	生产与实验 Gateway 必须隔离	云端 Mac 可用并联席位拆任务，见定价页

经验法则： 若 lsof 显示监听进程就是 openclaw，优先走「停服务 → doctor --fix → 再 install --force」，不要习惯性 kill -9 后立刻手动前台启动——很容易再次与 launchd 打架。

3）`openclaw doctor`：一键诊断与 `--fix` 修复

openclaw doctor 是 OpenClaw 官方的「体检 + 小手术」入口：检查配置合法性、服务安装状态、端口与 auth 是否自洽，并在安全范围内自动修复漂移。FAQ 里写得很清楚：它会迁移/修复配置与状态，并跑一轮健康检查（见 OpenClaw FAQ）。

推荐诊断序列（由浅入深）

openclaw status
openclaw gateway status
openclaw doctor
openclaw doctor --deep      # 列出 Gateway 端口上的客户端 PID（OS 允许时）
openclaw doctor --fix       # 修复配置/服务漂移；必要时对齐 --port
openclaw gateway restart

3.1 doctor 常见输出与含义

doctor 提示	含义	建议动作
`Gateway service port does not match current gateway config`	supervisor 仍用旧 `--port`	`openclaw doctor --fix` 或 `gateway install --force`
`Gateway start blocked: set gateway.mode=local`	配置处于 remote 模式或 local 标记损坏	`openclaw config set gateway.mode local`
`refusing to bind gateway without auth`	非 loopback 绑定却缺少有效 auth	`openclaw doctor --generate-gateway-token`
`System-level OpenClaw gateway service detected`	systemd/系统级与用户级服务冲突	只保留一层 supervisor；或设 `OPENCLAW_SERVICE_REPAIR_POLICY=external`

需要生成或轮换 Gateway token 时，优先用官方子命令，而不是手改 JSON 后忘记同步环境变量：openclaw doctor --generate-gateway-token 会写入 openclaw.json 并减少「文件里有 token、进程读的是旧 env」这类隐蔽故障。

4）`gateway status --deep`：分清「进程活着」与「端口通没通」

新手最容易被 Runtime: running 误导：supervisor 觉得进程在跑，不代表 18789 已在监听，更不代表 WebSocket probe 成功。官方建议信任这几行输出（FAQ · Gateway ports）：

Probe target: — CLI 实际探测的 URL；
Listening: — 端口上真正绑定的地址；
Last gateway error: — 进程存活但端口未就绪时的常见根因；
Connectivity probe: — 最终是否 ok。

结构化输出，便于贴工单

openclaw gateway status --json | jq .
openclaw logs --follow
# 另开终端触发一次 restart，观察 Last gateway error 是否刷新

--deep 还会扫描系统级服务注册（launchd/systemd/schtasks），并提示「Other gateway-like services detected」——在远程 Mac 上，这往往意味着某次手工安装没卸干净。修这类问题，比改 Agent prompt 更紧急：否则你会在「偶发能连、重启必挂」里浪费一整天。

5）认证与 bind 模式：最常见「起得来却连不上」

端口没冲突、进程也在跑，但 Control UI 仍报错时，优先查 auth 与 bind 的组合是否合法。官方 runbook 明确：非 loopback 绑定如果没有有效 gateway auth，会直接拒绝启动（refusing to bind gateway ... without auth）。

5.1 bind 模式速查

bind 设置	监听范围	典型用法
`loopback`（默认倾向）	`127.0.0.1`	SSH 到机器后本地打开 `http://127.0.0.1:18789/`
`lan` / 自定义	局域网或更广	必须配置 `gateway.auth.token` 或 password，并配合防火墙
`gateway.mode: remote`	客户端连远端 WS	本地不再起 Gateway，只连远程 URL

健康检查可辅助验证 HTTP 层是否就绪（官方 troubleshooting 指南）：

本机健康探测

curl -sS http://127.0.0.1:18789/health
# 若启用 token：
curl -sS -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/health

若 curl 本机成功、笔记本浏览器失败，九成是你没做 SSH 隧道却直接访问了私网 IP，或隧道本地端口与 gateway.port 不一致。FAQ 给出的标准隧道示例：

SSH 本地转发（远程 Gateway 在 loopback）

ssh -N -L 18789:127.0.0.1:18789 user@your-remote-mac
# 然后在笔记本打开 http://127.0.0.1:18789/

6）远程 Mac 场景：为什么云端更容易「端口看起来冲突」

在 Nuvcloud 这类独享裸金属 Mac mini 上跑 Gateway，端口冲突并不比其他云更少，但排障路径更依赖 SSH：你不会坐在机器前看 GUI，容易同时开着 VS Code Remote、tmux 里前台 gateway、以及 launchd 后台服务——三套入口叠在一起，EADDRINUSE 几乎是必然课。

建议云端固定一套约定：

只保留 launchd 托管，禁止长期前台 openclaw gateway；
变更 gateway.port 后，必须跑 doctor --fix，不要只改 JSON；
日志用 openclaw logs --follow 集中看，别分散在多个终端；
与 iOS CI 共用机器时，Runner 脚本里不要硬编码占用 18789（见 GitHub Actions iOS CI 加速）。

节点若在日本或香港，Gateway 排障节奏还受 SSH 延迟影响——长会话建议配 ServerAliveInterval，避免隧道静默断开让你误以为是 Gateway 挂了。地区选型可参考日本 vs 香港 Remote Mac，但本文不重复地区横评。

7）15 分钟排障 Runbook（按阶段执行）

把下面清单保存到团队 Wiki。每次 Gateway 异常，严格按顺序执行，不要跳步同时改三处配置。

分钟	动作	通过标准
0–2	`openclaw gateway status --deep`	记下 Runtime / Listening / Last error / Probe
2–5	`lsof -nP -iTCP:18789 -sTCP:LISTEN`	确认监听者是否 openclaw；是否多 PID
5–8	`openclaw doctor --fix`	无 blocking config/service issues
8–10	`openclaw gateway restart` + `logs --follow`	启动日志无 EADDRINUSE / auth 拒绝
10–12	`curl http://127.0.0.1:18789/health`	HTTP 200 / 预期 JSON
12–15	笔记本走 SSH 隧道访问 Control UI	WebSocket probe ok，channels 可探测

若 15 分钟内仍失败，收集三包日志再提工单：openclaw doctor > doctor.txt、openclaw gateway status --json、openclaw logs 最近 200 行。比截图报错更有用。

边界声明： 本文不覆盖 OpenClaw 完整安装、Channel 业务配置、六地区节点 TCO 横评，也不替代官方 Troubleshooting 全量条目。目标是让你把 90% 的 Gateway 异常在 CLI 层闭环。

一句话决策

见 EADDRINUSE — 先 lsof + status --deep，再决定杀进程还是改端口。
见 running 但连不上 — 查 Listening、Last gateway error、auth token 与 SSH 隧道。
任何改过 port/mode — 必须 doctor --fix 对齐 supervisor，禁止只改配置文件。

8）常见疑问

OpenClaw Gateway 默认端口是多少？

默认 18789。生效顺序：--port > OPENCLAW_GATEWAY_PORT > gateway.port > 18789。改端口后记得 doctor --fix，否则 supervisor 仍可能拉起旧端口。

`EADDRINUSE` 一定是别的软件占端口吗？

不一定是第三方软件。更常见是两个 OpenClaw Gateway 实例（前台 + launchd，或重复 install）。用 lsof 看命令行，十有八九是 openclaw 自己。

`openclaw gateway --force` 安全吗？

它会强制清掉监听再启动，适合开发机快速恢复；生产环境建议先 status --deep 确认没有关键客户端长连接，再执行，并观察 logs --follow。

doctor 和 `security audit --deep` 有什么区别？

doctor 偏配置与服务可运行性；security audit 偏暴露面与 token 强度。端口冲突修完后，若你把 bind 调到 lan，建议再跑一轮 audit。

为什么 `channels status --probe` 也要跑？

Gateway 只解决「控制面在线」。Channel _transport 仍可能单独失败。官方 troubleshooting 推荐在 Gateway ok 后再 probe channels，避免把 IM 断连误判成端口问题。

远程模式 (`gateway.mode: remote`) 还会遇到 18789 冲突吗？

客户端机器若不再本地起 Gateway，就不会有本地 18789 冲突；但你 SSH 到的那台远端 Mac 仍可能冲突。remote 模式只是角色分工变化，端口规则不变。

可以用 Nginx 反代 18789 吗？

可以，但 WebSocket 升级头、超时与 auth 头转发要配对，否则会出现「HTTP 健康检查正常、UI 一直转圈」。初学阶段更建议官方推荐的 loopback + SSH 隧道，少一层反代少一层猜。

排障时要不要重装 OpenClaw？

90% 情况不需要。按本文 Runbook 走完 doctor --fix + supervisor 对齐即可。重装只会掩盖「重复服务安装」的根因，下次升级还会复发。

最后收个口：Gateway 异常看起来吓人，多半只是端口、supervisor、auth 没对齐。把 openclaw doctor 和 gateway status --deep 养成肌肉记忆，你会比「删库重装」快一个数量级。