OpenClaw Docker 部署与配置避坑指南

在使用 Docker 部署 OpenClaw 的过程中，由于 Docker 的网络隔离与安全沙盒机制，开发者常会遇到一些配置上的障碍。本文总结了近期在配置过程中遇到的核心问题及其根因，并提供了一套完整的解决方案。

常见问题总结

1. Gateway 启动失败：Allowed Origins 错误

症状：日志报错 Error: non-loopback Control UI requires gateway.controlUi.allowedOrigins... 根因：OpenClaw 默认仅允许本地回环地址（Loopback）访问控制台。在 Docker 中，即使从宿主机访问 localhost，请求通过 Docker 网桥到达容器时会被识别为来自网关 IP（如 192.168.65.1），从而触发安全拦截。 方案：在 openclaw.json 或环境变量中设置：

• 开启回退模式：gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback: true
• 或显式指定：gateway.controlUi.allowedOrigins: ["http://localhost:18789"]

2. 访问控制台提示 Pairing Required

症状：页面显示 This device needs pairing approval... 根因：OpenClaw 的设备授权机制。新设备（或新浏览器）首次连接非 127.0.0.1 的地址时需要手动批准。 方案：在容器内执行 CLI 命令：

# 查看待批准列表
docker compose exec openclaw-gateway node dist/index.js devices list
# 批准对应 ID
docker compose exec openclaw-gateway node dist/index.js devices approve <ID>

3. SSRF 保护导致 URL 抓取失败

症状：web_fetch failed: Blocked: resolves to private/internal/special-use IP address 根因：为了防止内网攻击，OpenClaw 默认禁止访问私有 IP。当你配置了宿主机代理（如 Surge/Clash）并在 HTTP_PROXY 中使用了 host.docker.internal 时，DNS 解析可能会命中私有段规则。 方案：在 docker-compose.yml 中添加环境变量： OPENCLAW_ALLOW_PRIVATE_IPS: "1"

4. Gateway Token Mismatch

症状：CLI 连接失败报错 unauthorized: gateway token mismatch 根因：.env 中的 OPENCLAW_GATEWAY_TOKEN 与 openclaw.json 中的 gateway.auth.token 不一致。 方案：统一两处的 Token，或在 CLI 命令中显式传入 --token 参数。

---

最佳实践建议

1. 优先使用 Docker Compose CLI：避免手动拼接复杂的容器名称，使用 docker compose exec <service> 是最稳妥的方式。
2. 环境变量 vs 配置文件：建议将关键凭据（Token, Session Key）放在 .env 中，将行为配置放在 openclaw.json 中。
3. 理解 Docker 宿主机网络：在 Docker Desktop (Mac/Win) 中，宿主机的 IP 身份通常是 192.168.65.1，连接宿主机代理应使用 host.docker.internal。

通过以上配置，你应该能够顺利完成 OpenClaw 的 Docker 化部署，开启你的多 Agent 自动化之旅。