一份写给未来自己的文档。
防止下次再被 Docker、WSL2、Node.js 和容器网络联合教育。

---

一、环境准备

1. 必装软件

Docker Desktop

安装最新版 Docker Desktop：

Docker Desktop 官网即可下载。

安装时建议：

• 开启 WSL2 Backend

• 开启 WSL Integration

• 安装完成后重启系统

安装完成后检查：

docker -v
docker compose version

---

2. Node.js

OpenClaw 构建依赖 Node.js。

推荐版本：

Node.js 24+

安装完成后：

corepack enable
npm install -g pnpm

检查：

node -v
pnpm -v

---

二、Docker 与网络环境配置

这是整个部署过程中最容易踩坑的部分。

因为：

• Windows 网络

• WSL2 网络

• Docker Container 网络

本质上属于三个不同环境。

即使宿主机正常联网：

Docker 容器内部也可能依然无法访问外部资源。

---

三、Docker DNS 配置

Docker Desktop：

Settings
 -> Docker Engine

加入：

{
  "dns": ["8.8.8.8", "1.1.1.1"]
}

然后：

Apply & Restart

---

为什么需要配置 DNS

默认情况下：

Docker 使用宿主机 DNS。

但在部分网络环境中：

• npm 拉取

• Docker pull

• Node.js 依赖解析

可能出现：

failed to resolve reference
unexpected EOF

配置公共 DNS 后稳定性会明显提高。

---

四、本地网络加速工具配置

很多本地网络工具默认只代理：

• Windows 本机流量

并不会自动代理：

• Docker 容器

• WSL2

因此需要开启：

Allow LAN

否则可能出现：

• npm install 超时

• Docker pull 失败

• pnpm retry

• registry 拉取失败

---

五、WSL2 网络问题

如果出现：

WSL detected localhost proxy configuration but not mirrored

说明：

WSL2 没有正确继承宿主机网络配置。

---

解决方案

编辑：

C:\Users\你的用户名\.wslconfig

加入：

[wsl2]
networkingMode=mirrored
dnsTunneling=true
autoProxy=true

然后执行：

wsl --shutdown

最后重启：

• Docker Desktop

• WSL2

---

六、OpenClaw 安装

1. 克隆项目

git clone https://github.com/openclaw/openclaw.git
cd openclaw

---

2. Docker 构建

执行：

docker compose up --build

第一次构建时间会非常长。

因为需要：

• 拉取 Node 镜像

• 安装 pnpm 依赖

• TypeScript 构建

• Browser Automation 初始化

属于正常现象。

---

七、构建过程常见问题

1. npm / pnpm 下载失败

典型错误：

GET https://registry.npmjs.org/xxx error
Will retry in 10 seconds

---

原因

通常属于：

• 网络环境不稳定

• Docker DNS 异常

• 容器无法访问宿主机网络加速服务

---

解决方案

优先检查：

• Docker DNS

• 本地网络工具是否开启 Allow LAN

• Docker Proxy 配置

---

八、TypeScript 构建耗时

现象

日志长期停留：

[tsdown-build] still running pid=xx

很多时候并不是卡死。

OpenClaw 项目较大：

• TypeScript

• monorepo

• pnpm workspace

首次构建通常需要较长时间。

耐心等待即可。

---

九、Docker 内存占用过高

现象

Windows 中：

VmmemWSL

占用大量内存。

---

原因

构建过程中：

• pnpm

• TypeScript

• Docker Build

会同时消耗大量资源。

---

推荐配置

Docker Desktop：

项目	推荐
CPU	4核+
内存	8GB+
Swap	4GB+

---

十、exit code: 123

典型报错

check-package-dist-imports.mjs
exit code: 123

---

原因

通常不是 Docker 本身的问题。

更多属于：

• Node 构建缓存异常

• pnpm workspace 状态不一致

• 中间构建缓存损坏

---

解决方案

重新构建：

docker compose build --no-cache

必要时：

docker system prune -a

然后重新执行构建。

---

十一、Gateway 启动失败

1. Missing config

错误：

Missing config.
Run `openclaw setup`

---

原因

OpenClaw 尚未初始化配置文件。

---

十二、进入容器初始化

先查看容器：

docker ps

进入：

docker exec -u root -it openclaw-openclaw-cli-1 sh

---

十三、修复权限问题

典型错误：

permission denied
openclaw.json.lock

---

原因

容器内：

/home/node/.openclaw

目录权限不正确。

---

修复方式

执行：

mkdir -p /home/node/.openclaw
chown -R node:node /home/node/.openclaw

---

十四、初始化 OpenClaw

切换用户：

su node

执行：

openclaw setup

成功后会生成：

/home/node/.openclaw/openclaw.json

---

十五、Gateway 无法启动

错误

Refusing to bind gateway to lan without auth

---

原因

Docker 环境下：

Gateway 默认监听：

0.0.0.0

因此 OpenClaw 要求必须开启认证。

---

解决方案

编辑：

docker-compose.yml

加入：

environment:
  OPENCLAW_GATEWAY_PASSWORD: your_password

然后：

docker compose restart

---

十六、Gateway 成功标志

看到：

[gateway] ready

以及：

Browser control listening on

说明：

• Gateway 已正常启动

• Browser Control 已正常工作

• OpenClaw 已完成初始化

---

十七、OpenClaw UI 登录

打开：

http://localhost:3000

填写：

项目	内容
WebSocket	ws://localhost:18789
Password	你设置的密码

即可连接。

---

十八、最容易踩的几个坑

1. Docker 能联网 ≠ 容器能联网

Windows 网络正常：

不代表：

• WSL2 正常

• Docker 正常

• Container 正常

它们属于不同网络层。

---

2. openclaw setup 不等于 docker compose

CLI 配置与 Gateway 配置属于两套体系。

必须：

先 setup
再启动 gateway

---

3. docker compose restart 不会重新构建

它只会：

重启容器

修改 Dockerfile 后必须：

docker compose up --build

---

4. 容器名并不是固定的

很多人会遇到：

No such container

因为 Compose 会自动添加项目名前缀。

正确方式：

docker ps

先确认真实容器名。

---

十九、最终推荐配置

Docker Desktop

配置	建议
CPU	4核+
内存	8GB+
Swap	4GB+

---

网络配置

项目	配置
Docker DNS	8.8.8.8 / 1.1.1.1
WSL2	mirrored
LAN Access	开启

---

OpenClaw

项目	配置
Gateway Password	必配
openclaw setup	必执行
Docker Compose	推荐

---

二十、最终总结

OpenClaw 本质上是：

Node.js
+ pnpm
+ TypeScript
+ Docker
+ WebSocket
+ Browser Automation
+ Gateway

它并不是一个“单纯 docker pull 就能跑”的项目。

真正困难的地方在于：

你必须同时理解：

• Windows

• WSL2

• Docker

• Linux Container

• Node.js 构建链

• Gateway 网络模型

这些系统如何互相协作。

很多时候：

并不是代码有问题。

而是：

其中某一层网络、权限或配置出现异常后，导致整个链路开始连锁报错。

这也是容器化开发环境里最真实的一部分。