OpenClaw Gateway 启动报错 Error: listen EADDRINUSE: address already in use :::18789 的解决方案1. 问题描述执行openclaw gateway启动网关服务时很多人会遇到进程直接崩溃退出终端里打印出这样一段 Node.js 报错栈Error: listen EADDRINUSE: address already in use :::18789 at Server.setupListenHandle [as _listen2] (node:net:...) at listenInCluster (node:net:...) at Server.listen (node:net:...) at Gateway.start (/openclaw/dist/gateway/server.js:...) Emitted error event on Server instance at: at emitErrorNT (node:net:...) at process.processTicksAndRejections (node:internal/process/task_queues:...) { code: EADDRINUSE, errno: -4091, syscall: listen, address: ::, port: 18789 }如果是用openclaw onboard初始化向导时触发终端往往会更笼统地提示 Gateway 启动失败紧接着 Dashboard管理面板打不开浏览器访问http://localhost:18789直接显示无法访问此网站✗ Gateway failed to start ✗ Dashboard is not reachable at http://localhost:18789这个问题在同一台机器上重复执行openclaw gateway start、电脑重启前 Gateway 进程没有正常退出、同时在跑另一套 OpenClaw 实例比如测试环境和正式环境、这台机器上还跑着别的服务恰好用了同一个端口这几种场景下特别常见。很多人第一反应是重装 OpenClaw 或者反复重启命令但这个报错和程序装得对不对完全无关——它是最典型的端口资源被占用问题18789 是 OpenClaw Gateway 默认监听的端口号只要这个端口在系统层面已经被别的进程独占新启动的 Gateway 进程就无法再绑定上去。2. 原因分析EADDRINUSEError Address In Use是操作系统网络栈返回的标准错误码含义是同一个 IP 端口组合同一时刻只能被一个进程独占监听。当 OpenClaw Gateway底层是一个 Node.js 进程尝试在18789端口上启动 HTTP 服务时如果这个端口已经被占用listen()这个系统调用就会失败Node.js 把这个失败原样抛成一个Error事件最终表现为你看到的这段报错栈。常见的占用来源可以归纳成几类占用来源典型表现上一次 Gateway 进程未正常退出用CtrlC强行中断、或者电脑异常关机导致旧的 Node.js 进程变成孤儿进程继续占着端口同时运行了多个 OpenClaw 实例一个用默认配置跑另一个用相同端口的自定义配置又跑了一次daemon 后台服务已经在跑openclaw onboard --install-daemon已经把 Gateway 注册成了后台自启动服务你又手动执行了一次openclaw gateway其他无关服务恰好用了同一端口概率较低但在端口分配混乱的开发机上确实会发生Docker 容器重复映射了该端口用容器方式部署旧容器没清理干净新容器映射同一端口时冲突用一张流程图梳理触发链路执行 openclaw gateway或 daemon 自动拉起 ↓ Node.js 进程尝试 listen() 绑定 0.0.0.0:18789 / :::18789 ↓ 操作系统检查该端口是否已被其他 socket 独占监听 ├─ 已占用 → 返回 EADDRINUSE → Gateway 进程抛异常退出 └─ 未占用 → 绑定成功Gateway 正常启动Dashboard 可访问需要特别说明的是openclaw onboard --install-daemon这个参数会把 Gateway 注册为随系统持续运行的后台守护进程这意味着即便你没有主动执行任何命令Gateway 也可能已经在后台悄悄跑着——这是很多人排查这个问题时最容易忽略的一点明明感觉自己什么都没启动但端口早就被自己之前配置的守护进程占着了。3. 解决方案方案一使用 openclaw 内置命令查看并停止已有 Gateway最推荐OpenClaw 自带了管理 Gateway 生命周期的命令优先用它而不是手动去杀进程# 查看当前 Gateway 运行状态 openclaw status # 如果显示 Gateway 已经在运行直接用内置命令停止 openclaw gateway stop # 确认已经停止后重新启动 openclaw gateway start这种方式是最安全的因为它走的是 OpenClaw 自己的进程管理逻辑能确保相关的子进程、锁文件、临时状态都被正确清理不会留下看起来关了但其实还有残留的隐患。方案二手动定位并结束占用端口的进程如果openclaw status显示不在运行、但端口依然报占用说明是一个脱离了 OpenClaw 管理范围的孤儿进程在占着端口需要手动排查# macOS / Linux查看 18789 端口被哪个进程占用 lsof -i :18789 # 或者用 ss现代 Linux 系统更推荐 ss -tulnp | grep 18789WindowsPowerShellnetstat -ano | findstr 18789拿到 PID 后先用psLinux/macOS或任务管理器Windows确认这确实是一个 OpenClaw/Node.js 相关的孤儿进程再决定终止# 确认进程身份 ps -p PID -o pid,ppid,cmd # 确认无误后终止 kill PID # 优先用不带-9的正常终止信号 kill -9 PID # 如果上面无效再考虑强制终止⚠️风险提示kill -9是强制终止跳过了进程正常的清理逻辑比如关闭数据库连接、清理临时文件。如果确认这个进程正在处理重要任务建议先用不带-9的普通kill信号让它优雅退出只有确认无效时才升级为强制终止。方案三检查是否已经配置了后台守护进程daemon如果之前执行过openclaw onboard --install-daemonGateway 很可能早就作为系统服务在后台自启动运行了此时你再手动执行openclaw gateway自然会撞上端口冲突。检查是否存在这样的守护进程# macOS检查 launchd 服务 launchctl list | grep openclaw # Linux检查 systemd 服务 systemctl status openclaw # Windows检查后台服务 Get-Service | Where-Object { $_.Name -like *openclaw* }如果确认存在守护进程日常使用时不需要再手动执行openclaw gateway它已经在后台持续运行了直接访问http://localhost:18789使用 Dashboard 即可。如果确实需要手动干预比如调试、修改配置后重启应该通过对应平台的服务管理命令来重启而不是绕开它直接再起一个新进程# Linux systemd 场景 sudo systemctl restart openclaw方案四修改 Gateway 监听端口从根源规避冲突如果确认占用方是一个你无法轻易停掉的其他服务比如同一台开发机上还跑着别的项目恰好也用了 18789可以修改 OpenClaw 的配置让 Gateway 换一个端口监听# 查看配置文件路径 openclaw config path # 编辑配置文件找到 gateway.port 配置项在配置文件中修改gateway: port: 18790 # 改成一个确认空闲的端口修改后重新启动openclaw gateway restart修改端口后记得同步更新你本地浏览器书签或脚本里访问 Dashboard 用的 URL避免改完端口却还在用老地址访问这种低级失误。方案五Docker 部署场景下清理残留容器再重新拉起如果 Gateway 是跑在 Docker 容器里的端口冲突通常来自旧容器没有彻底清理新容器又尝试映射同一个端口# 查看是否有旧的容器还占着这个端口 docker ps -a --filter publish18789 # 停止并移除旧容器 docker stop 容器名或ID docker rm 容器名或ID # 确认端口已释放 lsof -i :18789 # 应该没有任何输出 # 重新启动新容器 docker compose up -d如果是用docker compose管理的更彻底的清理方式是docker compose down docker compose up -ddown命令会连带清理网络和容器比单独stop更干净能避免残留配置带来的隐藏冲突。4. 各方案对比总结方案适用场景推荐指数openclaw status/stop 内置命令首选排查方式能识别自身管理的进程⭐⭐⭐⭐⭐手动定位并结束孤儿进程openclaw status 显示未运行但端口仍占用⭐⭐⭐⭐检查是否已配置daemon后台服务之前执行过 --install-daemon 参数⭐⭐⭐⭐⭐修改监听端口占用方是无法停掉的其他关键服务⭐⭐⭐Docker 场景清理残留容器容器化部署环境⭐⭐⭐⭐5. 常见问题 FAQ5.1 为什么昨天关机前明明用 CtrlC 停掉了今天开机还是报端口占用CtrlC发送的是SIGINT信号理论上会触发进程的优雅退出逻辑但如果 Gateway 当时正在处理某个耗时任务比如一次长时间的 Agent 推理调用进程可能没有来得及完全退出就被系统强行结束比如电脑直接休眠/关机导致端口的释放没有被操作系统及时回收。开机后先用lsof -i :18789或ss -tulnp确认一下是否真的还有残留进程通常这类假死的残留进程重启电脑后就会自然消失如果没消失再手动清理。5.2 用 pm2 或其他进程管理工具托管 Gateway报端口占用要怎么排查如果用了pm2这类进程管理器来管理 Gateway 进程端口冲突往往是因为pm2 里已经有一个同名进程在跑你又手动执行了一次原生命令。先查看 pm2 的进程列表pm2 list pm2 stop openclaw-gateway # 停止 pm2 托管的实例确认 pm2 里没有残留后再决定是继续用 pm2 管理pm2 restart openclaw-gateway还是切回手动命令不要两套管理方式混用。5.3 Kubernetes 部署场景下Pod 报同样的端口冲突是同一个原因吗原理类似但通常是因为同一个节点上调度了两个使用了hostPort: 18789的 Pod导致节点级别的端口冲突Kubernetes 集群内部的 Service 端口隔离通常不会有这个问题只有显式用了hostPort或hostNetwork才会暴露到节点层面产生冲突。排查方式kubectl get pods -o wide --all-namespaces | grep openclaw kubectl describe pod pod名 | grep -A5 hostPort处理方式是避免多个副本使用同一个hostPort或者改用 Service 的方式暴露端口而不是依赖节点级别的端口绑定。5.4 端口占用问题解决后Dashboard 页面依然打不开是什么原因端口冲突解决、Gateway 进程成功启动之后如果浏览器访问依然失败需要区分两种情况一是防火墙拦截尤其是云服务器场景安全组/防火墙没有放行该端口的入站规则二是监听地址范围问题比如配置文件里写的是只监听127.0.0.1导致从其他机器无法访问只能在本机访问。排查步骤# 确认进程确实在监听且状态正常 openclaw status # 确认监听的具体地址范围 ss -tulnp | grep 18789如果监听地址是127.0.0.1:18789说明只能本机访问如果需要从局域网/公网访问需要在配置里显式改成监听0.0.0.0并同时配置好防火w/安全组规则、身份认证等安全防护措施。5.5 团队协作中多人共用一台开发服务器时如何避免互相抢占默认端口建议团队约定共享开发机上不要都用默认端口跑各自的 OpenClaw 实例每个人在自己的配置文件里指定一个专属端口比如按工号/用户名分配 18790、18791……并在团队文档里维护一张端口分配表。这样既能避免互相冲突也方便后续排查这个端口是谁的服务这类问题。5.6 排查清单速查表□ 1. 先执行 openclaw status 确认 OpenClaw 自身是否已经在运行 □ 2. 检查是否配置了 --install-daemon 后台守护进程日常无需再手动启动 □ 3. 用 lsof -i :18789 / ss -tulnp / netstat -ano 定位真正占用端口的进程 □ 4. 确认占用进程身份后优先用普通 kill/openclaw gateway stop 优雅停止 □ 5. Docker 场景检查是否有未清理的旧容器仍占用该端口映射 □ 6. K8s 场景检查是否多个 Pod 使用了同一个 hostPort □ 7. 确认无冲突后重新执行 openclaw gateway start观察是否正常监听 □ 8. 长期无法解决冲突时考虑修改配置文件中的 gateway.port 换一个端口6. 总结Error: listen EADDRINUSE: address already in use :::18789本质上是一个端口资源被占用的问题与 OpenClaw 程序本身是否安装正确没有关系。核心排查思路可以浓缩成三句话先用 OpenClaw 自带的status/stop命令排查——这是最安全、最了解自身进程状态的排查入口优先于手动kill重点检查是否配置过后台守护进程——--install-daemon会让 Gateway 在你毫无察觉的情况下持续在后台运行这是很多人排查时最容易忽略的盲点手动清理孤儿进程时优先优雅终止——只有确认普通终止无效时才考虑kill -9避免破坏正在进行的任务状态。最佳实践建议如果你的工作流里经常需要频繁重启 Gateway 做调试建议固定使用openclaw gateway stop openclaw gateway start这样的组合命令而不是依赖CtrlC强行中断能大幅降低孤儿进程和端口残留占用的发生概率。