OpenClaw启动失败因3000端口被占用，需先用ss或sudo ss查占用进程PID，再kill -9终止；或改docker-compose.yml端口映射为8080:3000，或运行时指定-p 8080:3000；启动前可用check-port.sh脚本自动校验端口可用性。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
你正在尝试本地部署OpenClaw，但启动时反复报错“Bind for 0.0.0.0:3000 failed: port is already allocated”，浏览器打不开localhost:3000，连初始设置页面都进不去——这不是配置写错了，而是主机3000端口已被其他进程死死占住，必须先清障再启动。
确认哪个进程在抢3000端口
打开终端，执行：
ss -tuln | grep ':3000'
如果输出类似 tcp LISTEN 0 128 *:3000 *:* users:(("node",pid=12345,fd=20))，说明是 node 进程（比如 Vite、Next.js 或 React 开发服务器）正霸占着它。注意看括号里的 pid 数字，这是关键线索。
若无任何输出，不代表端口空闲——某些进程可能以 root 权限运行，普通用户看不到。此时改用：
sudo ss -tuln | grep ':3000'
【务必先确认占用者再杀进程，误杀系统服务可能导致网络中断】
一键终止占用3000端口的进程
拿到上一步查到的 pid（比如 12345），直接执行：
kill -9 12345
如果不知道 pid 或多个进程共用3000端口，用暴力清理法：
sudo lsof -i :3000 | awk 'NR!=1 {print $2}' | xargs -r kill -9
这条命令会精准定位所有监听3000端口的进程 ID 并强制结束。xargs -r 确保没有匹配结果时不报错，避免脚本中断。
永久避开冲突：改映射端口启动OpenClaw
方法一：修改 docker-compose.yml（推荐）
打开项目根目录下的 docker-compose.yml，找到 openclaw 服务下的 ports 字段：
将 - "3000:3000" 改为 - "8080:3000"，保存后执行：
docker-compose up -d
方法二：运行时指定新端口（无需改文件）
执行：
docker run -d --name openclaw-app -p 8080:3000 -v /var/run/docker.sock:/var/run/docker.sock openclaw/image:latest
启动成功后，浏览器访问 http://localhost:8080 即可进入界面。注意：前端代码里硬编码了 API 请求地址的端口，若页面加载后报 502 或连接拒绝，说明后端服务没跟着改——此时必须回退到方法一，改配置文件而非仅改容器端口映射。
预防下次再撞车：启动前自动检查端口可用性
第一步：创建检查脚本 check-port.sh
内容为：
#!/bin/bash
PORT=${1:-3000}
if ss -tuln | grep -q ":$PORT"; then
echo "Port $PORT is occupied"
exit 1
else
echo "Port $PORT is free"
exit 0
fi
第二步：赋予执行权限
chmod +x check-port.sh
第三步：每次启动前运行
./check-port.sh 8080 && docker-compose up -d
这一步能堵住绝大多数因忘记关开发服务器导致的重复踩坑。脚本中默认检查3000，传参可检查任意端口，比如 ./check-port.sh 8080。
