openclaw docker部署端口冲突时，需先查清其默认主机端口（如3000、8000），再用lsof或netstat定位占用进程，最后通过终止冲突进程、修改docker-compose.yml端口映射或启用动态端口分配三步解决。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
OpenClaw Docker部署时遇到端口冲突，说明宿主机上已有进程（可能是其他容器、本地服务或残留进程）占用了OpenClaw默认映射的端口，导致容器启动失败并报错“port is already allocated”或“bind: address already in use”。
确认OpenClaw实际占用哪些端口
先查看OpenClaw项目文档或docker-compose.yml文件中定义的ports字段，常见配置类似：ports: - "3000:3000" - "8000:8000"。重点记下冒号左边的主机端口（如3000、8000），这些才是可能被抢占的关键数字。
执行grep -A 5 "ports:" docker-compose.yml快速定位——如果没找到ports字段，说明它可能使用默认端口或依赖环境变量，此时需检查environment块中的PORT或API_PORT值。
查清谁在抢你的3000端口
以最常冲突的3000端口为例，运行以下命令：
lsof -i :3000 → 若返回结果含node、python或java进程，说明是本地开发服务器（如Vite/React）占用了；若显示docker-proxy，则代表另一个Docker容器正绑定该端口。
若lsof不可用，改用sudo netstat -tulnp | grep :3000。注意：必须加sudo才能看到非当前用户启动的进程PID，否则可能漏掉root权限运行的服务。
【关键提醒】不要只查docker ps——已停止但未清理的容器仍可能残留端口绑定，docker ps -a无法反映端口状态，必须用系统级命令验证。
三步解决冲突（按优先级排序）
第一步：终止占用进程。若lsof返回PID为12345的node进程，直接执行kill 12345；若PID属于docker-proxy，运行docker stop $(docker ps --filter "expose=3000" -q)精准关停对应容器。
第二步：修改OpenClaw的主机映射端口。打开docker-compose.yml，将- "3000:3000"改为- "3001:3000"，保存后执行docker-compose down && docker-compose up -d。这一步见效最快，且不破坏原有服务逻辑。
第三步：启用动态端口分配（适合开发多实例场景）。把- "3000:3000"简化为- "3000"（只留容器端口），Docker会自动分配一个空闲主机端口。启动后用docker-compose port openclaw 3000查到实际映射值，比如0.0.0.0:32768，后续访问就用这个新地址。
