问题描述
启动 OpenClaw 网关时，遇到端口被占用的错误：
[openclaw:server] Error: listen EADDRINUSE: address already in use :::3000
at Server.setupListenHandle [as _listen2] (node:net:1817:16)
at listenInCluster (node:net:1865:12)
at Server.listen (node:net:1964:7)
或者启动后无法访问管理面板：
[openclaw:server] Server started on port 3000
$ curl http://localhost:3000/health
curl: (7) Failed to connect to localhost port 3000: Connection refused
OpenClaw 默认使用 3000 端口启动 HTTP 网关服务，用于接收 Webhook 回调、提供管理面板和 REST API。如果该端口已被其他程序占用，OpenClaw 将无法启动。
诊断步骤
检查端口占用情况
Linux / macOS：
lsof -i :3000
输出示例：
COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
node 12345 user 22u IPv6 123456 0t0 TCP *:3000 (LISTEN)
或者使用 ss 命令：
ss -tlnp | grep 3000
Windows：
netstat -ano | findstr :3000
输出示例：
TCP 0.0.0.0:3000 0.0.0.0:0 LISTENING 12345
通过 PID 查找占用端口的进程：
tasklist /FI "PID eq 12345"
检查是否有残留的 OpenClaw 实例
ps aux | grep openclaw
如果发现有旧的 OpenClaw 进程还在运行，可能是之前没有正确关闭。
检查 OpenClaw 配置的端口
cat ~/.openclaw/openclaw.json | grep port
确认配置文件中设置的端口号。
解决方案
方案一：停止占用端口的进程
如果端口被旧的 OpenClaw 实例占用：
openclaw stop
如果 stop 命令无效，强制终止进程：
Linux / macOS：
# 找到并终止占用3000端口的进程
kill $(lsof -t -i :3000)
# 如果普通 kill 无效
kill -9 $(lsof -t -i :3000)
Windows：
# 查找PID
netstat -ano | findstr :3000
# 终止进程（替换PID）
taskkill /PID 12345 /F
终止进程后重新启动 OpenClaw：
openclaw start
方案二：更换 OpenClaw 端口
如果 3000 端口被其他重要服务占用（如 React 开发服务器），修改 OpenClaw 的端口配置：
通过命令行参数指定端口：
openclaw start --port 3001
或者修改配置文件 ~/.openclaw/openclaw.json：
{
"server": {
"port": 3001,
"host": "0.0.0.0"
}
}
也可以通过环境变量设置：
OPENCLAW_PORT=3001 openclaw start
注意：如果你使用了 Webhook 方式接收消息（如 Telegram Webhook），更换端口后需要同时更新 Webhook URL 的端口号。
方案三：解决防火墙阻止
如果端口没有被其他程序占用，但仍然无法连接，可能是防火墙阻止了连接。
Linux（ufw）：
sudo ufw allow 3000/tcp
sudo ufw status
Linux（firewalld）：
sudo firewall-cmd --add-port=3000/tcp --permanent
sudo firewall-cmd --reload
Windows：
New-NetFirewallRule -DisplayName "OpenClaw" -Direction Inbound -Port 3000 -Protocol TCP -Action Allow
方案四：配置反向代理
在生产环境中，建议使用 Nginx 或 Caddy 作为反向代理，让 OpenClaw 监听在本地端口上，通过反向代理对外暴露标准的 80/443 端口：
Nginx 配置示例：
server {
listen 80;
server_name bot.example.com;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# WebSocket 支持
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
Caddy 配置示例（自动 HTTPS）：
bot.example.com {
reverse_proxy localhost:3000
}
使用反向代理后，OpenClaw 可以监听在 127.0.0.1:3000（仅本地访问），安全性更高：
{
"server": {
"port": 3000,
"host": "127.0.0.1"
}
}
方案五：使用 Unix Socket（Linux/macOS）
如果端口冲突是反复出现的问题，可以让 OpenClaw 使用 Unix Socket 而非 TCP 端口：
{
"server": {
"socket": "/tmp/openclaw.sock"
}
}
Nginx 配置中对应修改为：
location / {
proxy_pass http://unix:/tmp/openclaw.sock;
}
这样完全避免了端口冲突的可能性。
验证修复
启动后验证服务正常运行：
openclaw start
# 检查服务健康状态
curl http://localhost:3000/health
# 预期输出
# {"status":"ok","version":"x.x.x","uptime":5}
如果更换了端口，将命令中的 3000 替换为新的端口号。确认管理面板可以正常访问：在浏览器中打开 http://localhost:3000（或你配置的端口）。