OpenClaw Gateway 服务启动失败，提示 "Address already in use"，这意味着配置的监听端口已被其他进程占用。要正常启动服务，必须释放当前端口或修改端口配置。本文将从确认端口、查找占用进程、释放端口到验证启动，提供完整且可操作的解决方案。
确认 OpenClaw 配置的监听端口
打开 OpenClaw 安装目录下的 application.yml 或 config.yaml 配置文件，定位 server.port 字段的值。默认情况下，该值通常为 8080 或 9000。如果配置项写的是 0，表示系统将自动分配空闲端口，此时出现报错很可能是配置被覆盖或环境变量设置错误，建议检查 SERVER_PORT 等环境变量是否强制指定了具体的端口号。
小提示： 如果不确定当前端口号，可以先执行 grep 'server.port' application.yml config.yaml 命令，快速定位配置值。
查出占用目标端口的进程
在终端中执行以下命令（将 8080 替换为你要查询的实际端口号）：
sudo ss -tuln | grep ':8080'如果没有输出结果，可以改用 lsof 命令：
sudo lsof -i :8080这两条命令能够列出所有绑定到该端口的进程名称、PID 以及所属用户。
- 注意：在 WSL2 环境下，lsof 可能没有预装，可以先执行
sudo apt install lsof进行安装。 - 如果仍然没有结果，说明端口可能被 Windows 侧的进程占用——此时需要切换到 PowerShell 中执行
netstat -ano | findstr :8080，再通过tasklist | findstr "PID号"定位具体的 Windows 进程。
常见问题： 为什么 ss 和 lsof 都查不到？
答：可能是端口被 Docker 容器、虚拟网卡或 Windows 宿主进程占用。建议优先检查 Windows 侧的进程，同时确认 WSL2 是否开启了端口转发（例如执行 wsl --shutdown 后重启）。
释放被占用的端口
方法一：终止占用进程（推荐用于开发调试场景）
获取到 PID 后，直接杀掉对应进程：sudo kill -9 PID号。这个操作虽然简单，但务必确认该进程不是系统关键服务。例如，杀掉 Chrome 浏览器的渲染进程不会影响系统，但误杀数据库或 SSH 守护进程可能导致连接中断或数据异常。
方法二：修改 OpenClaw 端口配置（推荐用于生产环境或长期共存）
编辑 application.yml 配置文件，将 server.port 修改为一个明确未被占用的端口，例如 8081 或 9001。保存后无需重启系统，直接重新启动 OpenClaw 服务即可生效。
方法三：停用 Windows SSH 服务（仅限 WSL2 用户且不需要 Windows 原生 SSH）
在 PowerShell（以管理员身份运行）中依次执行：Stop-Service sshd → Set-Service sshd -StartupType Disabled。这样可以彻底释放 22 端口，避免 WSL2 中 OpenClaw 或其他服务因端口冲突而启动失败。
小提示： 如果不确定端口是否被 SSH 占用，可以先执行 sudo lsof -i :22 查看。如需临时恢复，在 PowerShell 中执行 Start-Service sshd 即可。
验证端口是否已释放并启动服务
第一步：再次运行 sudo ss -tuln | grep ':新端口号'，确认没有任何输出结果。
第二步：进入 OpenClaw 服务目录，执行启动命令：./gateway start 或 java -jar openclaw-gateway.jar。
第三步：检查服务日志末尾是否出现 Started GatewayApplication in X.XXX seconds 字样，同时通过 curl http://localhost:新端口号/actuator/health 返回 {"status":"UP"} 即表示服务已正常监听。
常见问题： 启动后日志显示成功，但 curl 返回 Connection refused？
答：可能是防火墙规则拦截了端口，或者服务绑定到了 127.0.0.1 而非 0.0.0.0。请检查 application.yml 中的 server.address 配置，如果值为 127.0.0.1 则只能本地访问，可改为 0.0.0.0 以允许外部访问。
通过以上步骤，即可有效解决 OpenClaw Gateway 因端口冲突导致的启动失败问题。如果仍然存在异常，建议进一步检查防火墙策略或日志中更详细的错误堆栈信息。