$cd ../troubleshooting/
Medium#Docker
Docker 端口 18789 冲突
当您看到 'Bind for 0.0.0.0:18789 failed: port is already allocated' 时，Docker 告诉您主机上已有另一个进程占用了端口 18789，导致 OpenClaw 无法绑定其网关端口。修复只需不到 2 分钟：要么找出并终止冲突进程，要么将 OpenClaw 重新映射到其他主机端口。两种方式都不需要重新安装任何东西。
error.log
🔍 错误信息
Error response from daemon: driver failed programming external
connectivity on endpoint openclaw:
Bind for 0.0.0.0:18789 failed: port is already allocated
端口 18789 是 OpenClaw 的默认网关端口。在三种情况下会出现此错误：(1) 上一个 OpenClaw 实例未正常关闭，端口仍被僵尸进程占用；(2) 您机器上另一个应用程序恰好使用了 18789 端口；(3) 在 macOS/Windows 上重启了 Docker Desktop，端口释放有延迟。运行下方诊断命令可精确找出占用该端口的进程。
fix.sh
✅ 逐步修复
1. 查找占用 18789 端口的进程
运行此命令获取占用该端口的进程 PID 和名称。macOS/Linux 会直接显示进程名和 PID。Windows 中，记录最后一列的 PID，然后运行 'tasklist | findstr <PID>' 获取进程名称。
$ lsof -i :18789 # macOS / Linux
$ netstat -ano | findstr 18789 # Windows
2. 方案 A — 终止冲突进程
如果阻塞的进程是废弃的 OpenClaw 实例或可以安全终止的东西，用第 1 步的 PID 终止它，然后重新启动 OpenClaw。如果冲突来自僵尸进程，这是最简洁的解决方案。
$ kill -9 <PID>
# Then restart OpenClaw
$ docker compose up -d
3. 方案 B — 更改 OpenClaw 端口
如果无法终止冲突进程（例如是您需要的其他应用），将 OpenClaw 重新映射到一个空闲端口。映射左侧是主机端口（对外暴露的），右侧 18789 是容器内部端口——保持不变。同时更新您的 API 客户端或 Nginx 配置使用新的主机端口。
# docker-compose.yml
services:
openclaw:
ports:
- "18888:18789" # host:container
❓ 常见问题
Q1. 可以用任何端口号吗？
可以。将 docker-compose.yml 中端口映射的左侧改为系统上任意空闲端口（如 '19000:18789'、'8080:18789'）。右侧的容器端口（18789）保持不变——那是 OpenClaw 的内部端口。确保选择的主机端口未被占用，在 macOS/Linux 上运行 'lsof -i :<端口>'，在 Windows 上运行 'netstat -ano | findstr <端口>' 进行检查。
Q2. 为什么系统重启后会出现这个问题？
在某些系统上（尤其是安装了 Docker Desktop 的 macOS），上一个容器停止后端口可能需要几秒钟才能完全释放。如果您重启机器后立即启动 OpenClaw，可能出现端口看起来仍在使用的竞争条件。等待 10-15 秒后再试。如果问题持续，用 'lsof -i :18789' 确认端口是否真的被某个进程占用。
Q3. lsof 没有显示任何进程但错误仍然出现，怎么办？
这可能发生在 Docker 内部网络状态混乱时，通常是不正常关闭后。运行 'docker network prune' 清理过期的 Docker 网络，如果问题持续可运行 'docker system prune --volumes'。注意 'docker system prune' 会删除已停止的容器和未使用的镜像——确认前请检查它将删除的内容。
Q4. 我终止了 PID，但重启后错误又回来了。如何永久修复？
如果某个特定应用程序持续占用 18789 端口，永久修复方案是在 docker-compose.yml 中更改 OpenClaw 的端口映射（方案 B）。添加专用端口环境变量，这样可以在 .env 文件中设置它。或者配置冲突的应用程序使用不同端口。目标是让 OpenClaw 独占 18789（或您选择的其他端口）。
Q5. 可以在同一台机器上运行多个 OpenClaw 实例吗？
可以，但每个实例需要自己的端口。第二个实例映射到不同的主机端口——例如 '18790:18789'。每个实例还需要独立的数据目录和 config.yaml。这对于同时运行个人用途和团队用途的 OpenClaw，或在不影响生产实例的情况下测试新配置非常有用。
Q6. 端口冲突在 Windows 上出现，但在 Mac 上没有。为什么？
Windows 有保留端口范围机制（Hyper-V、WSL2 和 Windows TCP/IP 栈可以保留端口块）。18789 端口可能在您系统的保留范围内。用 'netsh interface ipv4 show excludedportrange protocol=tcp' 检查。如果 18789 列在排除范围内，选择 49152 以上的端口作为主机映射，这些端口被保留的可能性更小。