openclaw 端口占用错误的标志是启动 Gateway 时日志出现 EADDRINUSE: address already in use :::18789，或提示 “another gateway instance is already listening”。根本原因分三类：openclaw 残留进程未清理、其他应用占用了同一端口、Daemon 元数据与实际进程状态不一致。本文提供从定位到解决的完整操作步骤，覆盖 macOS 和 Linux 两个系统环境。

 

快速定位：谁在占用 18789 端口

执行以下命令，30 秒内确认占用方：

macOS：

 

lsof -i :18789

Linux：

 

# 方式一（推荐，输出更详细）
ss -tlnp | grep 18789
 
# 方式二
netstat -tlnp | grep 18789

典型输出解读：

输出中的 COMMAND 字段

含义

处理方式

node / openclaw

openclaw 自身进程

→ 见"方案 A"

其他进程名（nginx、python 等）

第三方应用占用

→ 见"方案 B"

无输出

端口未被占用但启动仍失败

→ 见"方案 C"

 

方案 A：openclaw 残留进程（最常见）

场景

强制关闭终端、系统崩溃、或 gateway stop 未正常执行后，openclaw 进程残留在后台继续占用端口。

解决步骤

# Step 1：查看占用端口的 PID
lsof -i :18789
 
# 输出示例：
# COMMAND   PID     USER   TYPE  DEVICE SIZE/OFF NODE NAME
# node     4821  huyiyi   IPv6  0t0  TCP *:18789 (LISTEN)
 
# Step 2：通过 openclaw 命令优雅停止（优先）
openclaw gateway stop
 
# Step 3：若 gateway stop 无响应，按 PID 强制终止
kill -9 4821
 
# Step 4：确认端口已释放
lsof -i :18789   # 应无输出
 
# Step 5：重新启动
openclaw gateway start

一键清理所有 openclaw 进程

若存在多个残留进程，批量清理更高效：

 

# macOS / Linux 通用
pkill -f "openclaw"
 
# 确认清理结果
pgrep -a openclaw   # 应无输出
 
# 重新启动
openclaw gateway start

方案 B：第三方应用占用端口

场景

18789 端口被其他应用（开发服务器、代理工具、监控程序等）占用，openclaw 无法绑定。

解决方式一：终止第三方进程

 

# 获取 PID
lsof -i :18789
 
# 确认进程用途后终止（替换 <PID>）
kill <PID>
 
# 验证
lsof -i :18789   # 无输出后重启 openclaw
openclaw gateway start

解决方式二：修改 openclaw 端口（推荐，不影响其他应用）

 

# 通过 CLI 设置新端口（选择未被占用的端口，如 18790）
openclaw config set gateway.port 18790

或直接编辑 ~/.openclaw/openclaw.json：

{ "gateway": { "mode": "local", "port": 18790 // 修改为未占用的端口 } } 端口配置属于需要重启生效的配置项：

 

openclaw gateway restart

注意：修改端口后，Control UI 地址同步变更为 http://127.0.0.1:18790，需更新浏览器书签。

 

方案 C：Daemon 状态不一致（进程不存在但端口"看似"占用）

场景

lsof -i :18789 无输出，但 openclaw gateway start 仍报端口冲突，或 openclaw gateway status 显示 Runtime: running 但实际无进程。

原因

Gateway Daemon 的元数据（PID 文件、socket 文件）记录了已停止进程的信息，导致 openclaw 误认为自身仍在运行。

解决步骤

 

# Step 1：强制重装 Daemon 元数据（清理残留 socket/PID 文件）
openclaw gateway install --force
 
# Step 2：重新启动
openclaw gateway start
 
# Step 3：验证状态
openclaw gateway status --deep
# 预期：Runtime: running，RPC probe: ok

 

系统级端口冲突：进阶排查

查看所有高风险端口占用

若不确定是哪个端口出问题，查看 openclaw 相关的所有活跃端口：

 

# macOS
lsof -i | grep openclaw
 
# Linux
ss -tlnp | grep node

开机自启进程冲突（macOS launchd）

macOS 上若 openclaw Daemon 配置了 launchd 自启，系统重启后可能启动两个实例：

 

# 查看 openclaw 相关 launchd 服务
launchctl list | grep openclaw
 
# 若存在重复，卸载后重装
openclaw gateway uninstall
openclaw gateway install
openclaw gateway start

Linux systemd 环境

 

# 检查 systemd 服务状态
systemctl status openclaw 2>/dev/null || echo "No systemd service"
 
# 若存在 systemd 服务与手动启动的实例冲突
systemctl stop openclaw
openclaw gateway install --force
openclaw gateway start

Docker 环境端口映射冲突

Docker 容器内外的端口映射可能引发冲突：

 

# 检查 Docker 容器占用的端口
docker ps --format "table {{.Names}}\t{{.Ports}}" | grep 18789
 
# 停止冲突容器
docker stop <container_name>
 
# 或修改 openclaw 容器的端口映射（-p 宿主机端口:容器端口）
docker run -p 18790:18789 openclaw/gateway

 

端口占用预防：建立稳定运行习惯

始终用 openclaw 命令管理生命周期

避免直接 kill node 或强制关闭终端——这会绕过 Gateway 的优雅退出流程，导致 PID 文件和 socket 文件残留：

 

# 正确：优雅停止
openclaw gateway stop
 
# 错误：强制中断（留下残留文件）
kill -9 $(pgrep node)

升级前先停止服务

 

openclaw gateway stop
npm update -g openclaw
openclaw gateway install --force
openclaw gateway start

设置端口检测脚本（可选）

在启动脚本或 .zshrc / .bashrc 中加入端口预检：

# 启动前检测端口，若被占用自动清理残留进程
if lsof -i :18789 | grep -q LISTEN; then
  echo "[openclaw] Port 18789 occupied, cleaning up..."
  pkill -f "openclaw" 2>/dev/null
  sleep 1
fi
openclaw gateway start

 

常见问题

Q：改了端口配置，执行 restart 还是报旧端口冲突，怎么回事？

端口配置属于"需要重启生效"的配置项，但 restart 会先尝试停止当前实例。若当前实例已因端口冲突无法启动，restart 可能找不到进程而直接用旧配置重新拉起。正确做法：先 openclaw gateway stop（或 pkill -f openclaw），再 openclaw gateway start。

Q：lsof -i :18789 显示的 PID 每次执行都不同，是正常的吗？

不正常，说明 openclaw 在反复崩溃重启。查看日志定位崩溃原因：openclaw logs | tail -50，通常是配置错误或 API Key 无效导致的启动循环。

Q：端口改为 18790 后，接入七牛云等 AI 模型的功能还能正常使用吗？

模型 API 调用走的是外部提供商端点（如 https://api.qnaigc.com/v1），与本地 Gateway 端口无关，修改端口不影响 AI 功能。仅 Control UI 地址、RPC 调用路径需同步更新为新端口。

Q：公司网络环境下某些端口被防火墙封锁，该怎么选端口？

选择 8000–9999 或 49152–65535 范围内的非特权端口，通常不受企业防火墙限制。常用备选：8789、9099、18888。避免 3000、8080、8443 等常用开发端口，减少与其他工具冲突的概率。

Q：同一台机器能运行两个 openclaw Gateway 实例吗？

可以，但需要为每个实例分配不同端口，并使用独立的配置目录（通过环境变量 OPENCLAW_CONFIG_DIR 指定）。多实例场景建议搭配容器化部署（Docker）隔离依赖，避免状态互相干扰。

 

总结

openclaw 端口占用的核心处理逻辑：先用 lsof -i :18789 确认占用方 → 残留 openclaw 进程用 pkill -f openclaw 清理 → 第三方应用改端口绕开 → Daemon 状态不一致用 gateway install --force 重置。端口问题 90% 是残留进程导致的，pkill -f openclaw && openclaw gateway start 这一组合可解决绝大多数情况。

预防优于排查：建立"停止再升级"的操作习惯，避免强制 kill 进程，可从根源上消除端口残留问题。

本文基于 OpenClaw 官方文档（docs.openclaw.ai）及七牛云开发者平台，内容对应 2026 年 3 月当前版本，建议定期核对最新 Release Notes 确认默认端口和命令语法。

 

延伸资源

● OpenClaw Gateway 排查文档：https://docs.openclaw.ai/gateway/troubleshooting

● OpenClaw 安装配置指南（七牛云）

● 七牛云 AI 推理服务