Docker部署OpenClaw及常见问题解决（win11）

一、先搞懂核心原理

1. 几个关键概念

术语	解释
OpenClaw	AI Agent网关，简单说就是帮你管理AI机器人、让AI安全执行各种工具/命令的核心程序
Docker	一个「虚拟小电脑」工具，能给OpenClaw搭一个独立、隔离的运行环境，不会搞乱你Win11本机的任何设置，删了就全清，零污染
WSL2	Win11自带的「Linux子系统」，Docker在Win11上必须靠它才能正常跑Linux程序（OpenClaw原生是Linux生态的，直接装Win11会有90%的兼容问题）
容器化网关	把整个OpenClaw都装在Docker的「虚拟小电脑」里，所有功能都在里面跑，和你本机完全隔离
Agent沙箱	给AI单独开一个更小的「隔离盒子」，AI执行命令、下载文件都在盒子里，就算AI操作失误，也不会弄坏你Win11本机的文件

2. Win11上的运行逻辑

Plain 复制代码

你的Win11电脑 → 开启WSL2子系统 → 安装Docker Desktop（用WSL2当底层） → 拉取OpenClaw镜像 → 启动容器 → 浏览器访问管理页面

3. Win11用户必看的5条避坑

所有文件路径绝对不能有中文、空格、特殊符号 ：比如不要放「桌面」「我的文档」「新建文件夹 (2)」，推荐直接放D:\openclaw这种纯英文无空格路径
执行.sh脚本必须用Git Bash/WSL终端：不能用系统自带的CMD、PowerShell（这俩不兼容Linux脚本，会直接报错）
Docker Desktop必须全程后台运行：关掉它，所有docker命令都会失效，页面也打不开
先开WSL2，再装Docker：顺序反了，Docker会启动失败，各种奇奇怪怪的报错
第一次访问页面，防火墙弹窗一定要点「允许访问」：Win11防火墙会默认拦截容器的端口，不允许就会出现「URL拼写错误」的报错

二、Win11前置环境准备

步骤1：开启Win11的WSL2功能（Docker的底层基础）

原理：

Win11默认不开启Linux子系统，我们需要手动打开，给Docker提供一个兼容的Linux运行环境。

操作方法（2种选1种，推荐图形化）

方法1：图形化开启（小白首选）

按下Win键，搜索「启用或关闭Windows功能」，打开这个系统面板
在弹出的列表里，找到并勾选这2个选项：
- 「适用于Linux的Windows子系统」
- 「虚拟机平台」
点击「确定」，系统会自动安装组件，完成后必须重启电脑
重启后，按下Win+R，输入cmd打开命令提示符，输入以下命令，把WSL默认版本设为2：
Plain 复制代码
```
wsl --set-default-version 2
```
验证是否成功：输入wsl --list --verbose，输出里的「VERSION」列显示2，就代表成功了

方法2：命令行一键开启（熟手用）

按下Win键，搜索「PowerShell」，右键选择「以管理员身份运行」
依次输入以下2条命令，每条输完按回车：
PowerShell 复制代码
```
wsl --install
wsl --set-default-version 2
```
执行完重启电脑，同样用wsl --list --verbose验证版本为2即可

步骤2：安装Docker Desktop（Win11）

原理：

Docker Desktop是Win11上的Docker可视化管理工具，帮我们一键管理容器、镜像，不用记复杂的Linux命令。

操作方法：

打开Docker官网下载Win11专属安装包：https://www.docker.com/products/docker-desktop/
双击安装包，重点注意安装界面的勾选框：
- 必须勾选「Use the WSL 2 based engine」（用WSL2作为底层引擎，核心中的核心）
- 其他选项默认即可，点击「OK」等待安装完成
安装完成后，打开Docker Desktop，第一次打开会弹出用户协议，勾选接受，进入主界面
跳过登录（登录不是必须的，不登录完全能用），等待左下角的Docker图标从黄色变成绿色，就代表启动成功了

验证Docker是否正常：

按下Win+R，输入powershell打开终端，依次输入以下2条命令，能正常输出版本号，就代表安装成功：

PowerShell 复制代码

docker --version
docker compose version

步骤3：安装Git for Windows（兼容Linux脚本）

原理：

Git for Windows自带了Git Bash终端，能完美兼容Linux的.sh脚本，是我们执行安装脚本的必备工具，同时也能拉取OpenClaw的代码。

操作方法：

打开Git官网下载Win11安装包：https://git-scm.com/download/win
双击安装包，所有选项全部默认，一路下一步安装完成即可
安装完成后，右键空白处，能看到「Open Git Bash Here」选项，就代表安装成功了，如下图所示：

三、OpenClaw 一键部署

原理：

官方提供了一键部署脚本docker-setup.sh，会自动帮我们完成「构建镜像→初始化配置→生成令牌→启动容器→端口映射」全流程，不用手动敲复杂命令，零出错。

操作步骤：

步骤1：拉取OpenClaw代码，选对存放路径

打开D盘（或者其他非系统盘），新建一个纯英文的文件夹，比如openclaw，路径就是D:\openclaw
进入这个文件夹，在空白处右键，选择「Git Bash Here」，打开Git Bash终端
在Git Bash里输入以下命令，拉取官方代码，输完按回车：
Bash 复制代码
```
git clone https://github.com/openclaw/openclaw.git
```

如下图所示：

如果无法连上，报错：fatal: unable to access 'https://github.com/openclaw/openclaw.git/': Recv failure: Connection was reset

可以直接跳过 Git 拉取，手动从 GitHub 下载代码压缩包，解压后继续后续部署，不影响后续操作。

实操步骤：

打开 Win11 浏览器（Edge/Chrome 都可以），输入 OpenClaw 的 GitHub 地址（复制粘贴，别输错）：

Plain 复制代码

https://github.com/openclaw/openclaw

进入页面后，点击右上角的「Code」按钮，在弹出的菜单里，选择「Download ZIP」；

等待压缩包下载完成（大小20多M，几分钟就能下完）；

找到下载的压缩包（默认在「下载」文件夹），右键选择「解压到」，解压到之前准备的路径（比如 D:\openclaw）；

解压完成后，你会得到一个「openclaw」文件夹（和 Git 拉取的文件夹一模一样）；

如下图所示：

拉取完成后，输入以下命令，进入代码根目录（所有后续命令都必须在这个目录里执行）：
Bash 复制代码
```
cd openclaw
```

步骤2：执行一键部署脚本

还是在刚才的Git Bash终端里，输入以下一键部署命令，输完按回车：
Bash 复制代码
```
./docker-setup.sh
```

可能会报错，Docker Desktop 无法连接到官方镜像仓库 registry-1.docker.io。日志显示：

connectex: A connection attempt failed because the connected party did not properly respond...

解决方案

a.配置 Docker 镜像加速器（最推荐）

由于国内网络原因，直接访问 Docker Hub 经常超时。请配置国内镜像源：

打开 Docker Desktop 设置。

进入 Docker Engine 页面。

在 JSON 配置中添加 registry-mirrors 字段，如下所示：

json 复制代码

{
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  },
  "experimental": false,
  "registry-mirrors": [
    "https://docker.1panel.live",
    "https://docker.1ms.run"
  ]
}

点击 Apply & restart，重新构建。如下图所示：

如果卡在bun包安装上，可以更改dockfile文件，bun包安装增加镜像，并设置超时时间：

bash 复制代码

# Install Bun (required for build scripts)
RUN mkdir -p /root/.bun \
    && curl -fsSL --connect-timeout 30 --max-time 120 https://cdn.bytedance.com/npm/dist/bun/install | bash \
    && echo 'export PATH="$HOME/.bun/bin:$PATH"' >> /root/.bashrc

30秒没连上，120秒没下载完就退出。如下图所示：

如果编译是遇到内存溢出错误，直接在 Dockerfile 的RUN pnpm build之前添加环境变量，并且把内存设得更大（比如 4GB）：

dockfile 复制代码

ENV NODE_OPTIONS="--max-old-space-size=4096"
RUN pnpm build

脚本会自动执行，全程不用操作，等待它跑完。期间会做这些事：
- 自动检测你的系统环境，构建适配的OpenClaw镜像
- 运行初始化向导，让你配置基础信息（比如AI服务商的密钥）
- 自动生成网关访问令牌，写入配置文件
- 自动通过Docker Compose启动网关容器
- 自动配置端口映射，让你Win11的浏览器能访问容器里的服务
  
  如下图所示：
  
  QuickStart 模式默认已选中，直接按Enter 键即可确认；
  
  若未选中，用方向键切换后按 Enter；
  
  后续可通过openclaw configure修改所有配置，无需重新初始化。
  
  如下图所示：
  
  如果你在国内，追求网络稳定和中文支持
  
  选择 Qwen（通义千问）或 MiniMax
  
  Qwen：字节跳动出品，中文能力强，国内访问稳定，延迟低
  
  MiniMax：国内模型，支持长文本，性价比高
  
  优点：无需特殊网络配置，中文体验好
  
  如果你暂时没有 API Key，想先体验功能
  
  选择 Skip for now（最后一个选项）
  
  跳过模型配置，先完成 OpenClaw 的基础初始化，之后可以通过 openclaw configure 随时添加模型。
  
  下一步直接选
  
  ● All providers
  
  然后按回车 Enter
  
  下一步直接选
  
  ● Keep current (default: anthropic/claude-opus-4-6)
  
  再下一步选择Skip for now，现在是QuickStart 快速部署，先把服务跑通最重要
  
  前面那些 Telegram、WhatsApp、飞书都是聊天渠道，现在不配完全不影响核心功能，如下图所示：
  
  下一步选择no，现在是 QuickStart 快速上手，先让 OpenClaw 服务跑起来最重要，技能配置是高级功能，后面再弄；避免卡点：技能配置需要填各种依赖（比如工具路径、API 密钥），现在选 Yes 会陷入复杂配置，反而耽误你验证核心服务；灵活调整：跳过技能配置后，服务启动成功，后续想加技能随时可以用命令 openclaw skills configure 单独配置，完全不影响。如下图所示：
  
  下一步✅ ◻ Skip for now（先选中这个选项，再按回车）
  
  Hooks 是「自动化钩子」：属于进阶功能（比如自动记录会话、保存上下文），对新手来说完全没必要现在配置；
  
  QuickStart 核心是「跑通服务」：这些钩子不影响 OpenClaw 的基础运行，现在跳过不会有任何功能缺失；
  
  后续可随时配置：等你熟悉了 OpenClaw 的基础用法，再用 openclaw hooks configure 单独开启 / 配置钩子即可。
  
  操作步骤：
  
  按键盘方向键（↑/↓）把光标移到 ◻ Skip for now 上；
  
  按空格键（Space）选中它（前面会出现 ◼ 实心方块）；
  
  按回车 Enter 确认，就能彻底完成所有初始化配置，进入服务启动环节。
  
  如下图所示：
脚本执行完成后，会出现绿色的「success」提示，同时会显示你的访问令牌，一定要把这个令牌复制下来，后面登录要用

如未记录，则可以通过如下命令查看，

bash 复制代码

docker exec -u root -it openclaw-running /bin/sh
su node
cat ~/.openclaw/openclaw.json | grep -i token

如下图所示：

步骤3：访问管理页面，完成配置

打开Chrome/Edge浏览器，输入地址：http://127.0.0.1:18789/
进入页面后，找到「设置」→「token」，把刚才复制的令牌粘贴进去，保存即可
能正常进入管理界面，就代表部署成功了！

四、核心报错解决（Win11）

报错1：访问 http://127.0.0.1:18789/ 提示「URL拼写可能存在错误，请检查」

根本原因（Win11专属，按顺序排查）

这个报错不是URL写错了，是Win11的环境/配置出了问题，导致浏览器连不上容器里的服务，按以下顺序排查，一步一步来：

排查1：确认容器是否正常运行

打开Docker Desktop，点击左侧的「Containers」，能看到openclaw-gateway容器，状态是Running（绿色的）
如果容器没运行，点击启动按钮，等待它变成绿色
如果容器启动失败，点击容器名称，查看日志，看有没有报错，最常见的是端口被占用

排查2：确认18789端口没被Win11其他程序占用

以管理员身份打开PowerShell，输入以下命令，查看18789端口被谁占用了：
PowerShell 复制代码
```
netstat -ano | findstr :18789
```
如果输出了内容，说明端口被其他程序占用了，有2种解决方法：
- 方法1：结束占用端口的程序，记住输出里最后一列的PID数字，输入taskkill /f /pid 你的PID数字
- 方法2：修改OpenClaw的端口映射，在docker-compose.yml里把18789:18789改成18790:18789，然后重启容器，访问http://127.0.0.1:18790/

排查3：放行Win11防火墙/杀毒软件

按下Win键，搜索「Windows Defender 防火墙」，打开后点击左侧的「允许应用或功能通过Windows Defender防火墙」
点击「更改设置」，在列表里找到「Docker Desktop Backend」，把后面的「专用」和「公用」都勾选上，点击确定
如果你装了360、腾讯电脑管家等杀毒软件，暂时关闭防火墙功能，再重新访问页面

排查4：修复WSL2端口转发问题

Win11的WSL2有时候会出现端口转发失效，导致本机访问不了容器里的服务，修复方法：

以管理员身份打开PowerShell，依次输入以下命令，重启WSL2：
PowerShell 复制代码
```
wsl --shutdown
net stop LxssManager
net start LxssManager
```
重启Docker Desktop，等待容器重新启动，再访问页面

报错2：OpenAI Codex OAuth回调时，http://127.0.0.1:1455/auth/callback 提示「URL拼写可能存在错误，请检查」

根本原因：

Docker容器里的OAuth回调，会尝试在你Win11本机的1455端口捕获认证信息，但容器和Win11本机的网络隔离，导致浏览器访问不到这个回调地址。

解决方法：

不要关闭浏览器的回调页面，哪怕它显示报错，也保留这个页面
复制浏览器地址栏里的完整重定向URL（就是报错页面的整个地址）
回到你执行docker-setup.sh的Git Bash终端，会看到提示让你粘贴回调地址，把刚才复制的URL粘贴进去，按回车
终端会自动完成认证，不用管页面的报错，认证完成后会自动跳转到管理界面

报错3：Chrome/130.0.0.0 Safari/537.36 QuarkPC/6.4.0.728 code=1008 reason=pairing required

如下图所示：

解决方法

步骤 1：获取最新的控制台访问链接

这一步会生成带有效 token 的控制台链接，避免因旧链接失效导致的授权问题：
docker compose run --rm openclaw-cli dashboard --no-open

执行后会输出一个 URL（例如 http://xxx.xxx.xxx.xxx:xxxx/ui?token=xxx），先保存好这个链接，后续登录会用到。

步骤 2：列出所有待授权的设备 / 请求

这一步是关键，用于找到需要批准的 requestId（配对请求 ID）：
docker compose run --rm openclaw-cli devices list

执行后会输出类似如下的列表：

bash 复制代码

ID: dev_123456789 | Status: PENDING | Name: Chrome Browser
ID: dev_987654321 | Status: PAIRED | Name: Firefox Browser

你需要复制 Status 为 PENDING 对应的 ID（即，比如 dev_123456789）。

步骤 3：批准指定的配对请求

将上一步复制的替换到指令中，完成授权：

bash 复制代码

# 替换 <requestId> 为实际的待授权ID，例如：
docker compose run --rm openclaw-cli devices approve dev_123456789

如果有多个待授权设备，也可以用 --all 批量批准（懒人方式）：

bash 复制代码

docker compose run --rm openclaw-cli devices approve --all

步骤 4：验证授权结果并登录

再次执行 devices list 指令，确认目标设备的 Status 变为 PAIRED：

bash 复制代码

docker compose run --rm openclaw-cli devices list

打开步骤 1 生成的控制台链接，即可正常登录，不会再报 "pairing required" 错误。

如果执行指令时提示 Error: No such service: openclaw-cli：

检查你的 docker-compose.yml 中 CLI 服务的名称（可能是 openclaw-cn-cli/openclaw-gateway 等），替换指令中的 openclaw-cli 即可，例如：

docker compose run --rm openclaw-cn-cli devices list

如果批准后仍报错：

重启 OpenClaw 相关服务：

bash 复制代码

docker compose restart

清除浏览器缓存 / 使用无痕模式，重新访问步骤 1 生成的链接。

docker compose 环境下解决配对错误的核心是用 openclaw-cli 工具完成「列设备→批设备」两步操作；

重点是找到 Status: PENDING 对应的，批准后设备状态会变为 PAIRED；

指令中 openclaw-cli 需与 docker-compose.yml 中的服务名一致，否则会提示服务不存在。

五、进阶配置（Win11）

1. 安装ClawDock助手（一键管理容器，不用记命令）

原理：

官方提供的Shell助手，能简化日常操作，比如一键启动/停止容器、打开管理面板、查看日志，不用记复杂的docker命令。

Win11安装步骤：

打开Git Bash终端，输入以下命令，创建目录并下载助手脚本：

Bash 复制代码

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh

把脚本添加到Git Bash的默认配置里，每次打开终端都能直接用：
Bash 复制代码
```
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.bashrc && source ~/.bashrc
```
安装完成，常用命令：
- 启动网关：clawdock-start
- 停止网关：clawdock-stop
- 打开管理面板：clawdock-dashboard
- 查看所有命令：clawdock-help

2. Win11本机文件夹挂载到容器（让容器能访问你电脑里的文件）

原理：

「挂载」就是把你Win11本机的文件夹，共享给容器里的「虚拟小电脑」，两边都能读写文件，比如你想让AI操作你D盘里的代码文件，就需要挂载。

Win11专属操作方法：

打开Git Bash，进入openclaw代码根目录

先设置环境变量，指定要挂载的文件夹，**Win11路径必须用正斜杠/，不能用单反斜杠**，示例：

Bash 复制代码

# 格式：宿主机路径:容器内路径:权限，ro=只读，rw=读写
# 示例1：把D盘的codex文件夹，以只读方式挂载到容器里
export OPENCLAW_EXTRA_MOUNTS="D:/codex:/home/node/.codex:ro"
# 示例2：同时挂载多个文件夹，用逗号分隔
export OPENCLAW_EXTRA_MOUNTS="D:/codex:/home/node/.codex:ro,D:/github:/home/node/github:rw"

设置完环境变量后，重新执行一键部署脚本，自动生成挂载配置：
Bash 复制代码
```
./docker-setup.sh
```
脚本执行完成后，容器里就能访问你Win11本机的文件夹了

3. Agent沙箱启用（让AI在隔离环境里运行，更安全）

原理：

给AI单独开一个隔离的小容器，AI执行所有命令、下载文件都在这个小盒子里，就算AI被诱导执行危险命令，也不会影响你Win11本机的文件和系统，是必开的安全功能。

Win11启用步骤：

打开openclaw代码根目录，找到配置文件（一般是config.yaml或config.json）
把下面的配置复制进去，保存文件（已经给你适配了Win11的默认路径）
打开Docker Desktop，重启openclaw-gateway容器，配置就生效了

JSON 复制代码

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "agent",
        "workspaceAccess": "none",
        "workspaceRoot": "~/.openclaw/sandboxes",
        "docker": {
          "image": "openclaw-sandbox:bookworm-slim",
          "workdir": "/workspace",
          "readOnlyRoot": true,
          "tmpfs": ["/tmp", "/var/tmp", "/run"],
          "network": "none",
          "user": "1000:1000",
          "capDrop": ["ALL"],
          "env": { "LANG": "C.UTF-8" },
          "setupCommand": "apt-get update && apt-get install -y git curl jq",
          "pidsLimit": 256,
          "memory": "1g",
          "memorySwap": "2g",
          "cpus": 1
        },
        "prune": {
          "idleHours": 24,
          "maxAgeDays": 7
        }
      }
    }
  },
  "tools": {
    "sandbox": {
      "tools": {
        "allow": [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status"
        ],
        "deny": ["browser", "canvas", "nodes", "cron", "discord", "gateway"]
      }
    }
  }
}

沙箱镜像构建：配置完后，在Git Bash里执行以下命令，构建沙箱镜像，不然会报镜像缺失错误
Bash 复制代码
```
scripts/sandbox-setup.sh
```

六、Win11日常使用与维护

1. 怎么启动/停止服务

方法1（可视化，小白首选）：打开Docker Desktop，在Containers里，找到openclaw-gateway容器，点启动/停止按钮即可
方法2（命令行）：在Git Bash里进入代码根目录，输入docker compose up -d启动，输入docker compose down停止

2. 怎么查看日志，排查问题

可视化：打开Docker Desktop，点击openclaw-gateway容器，就能看到实时日志，报错会标红
命令行：在Git Bash里进入代码根目录，输入docker compose logs -f openclaw-gateway查看实时日志

3. 怎么更新版本

在Git Bash里进入代码根目录，输入git pull拉取最新代码
重新执行./docker-setup.sh，脚本会自动构建新镜像，重启容器，不会丢失你的配置

4. 怎么完全卸载，不留痕迹

在Git Bash里进入代码根目录，输入docker compose down -v，删除容器和数据卷
打开Docker Desktop，在Images里，删除所有openclaw相关的镜像
删除代码存放的文件夹，比如D:\openclaw
如需卸载Docker Desktop，在Win11的「设置→应用→已安装的应用」里，找到Docker Desktop，点击卸载即可