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

1. 几个关键概念

2. Win11上的运行逻辑

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

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

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

原理：

openclaw docker 教程

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

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

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

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

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

1. 按下Win键，搜索「PowerShell」，右键选择「以管理员身份运行」
2. 依次输入以下2条命令，每条输完按回车：
3. 执行完重启电脑，同样用验证版本为2即可

步骤2：安装Docker Desktop（Win11）

原理：

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

操作方法：

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

验证Docker是否正常：

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

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

原理：

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

操作方法：

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

原理：

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

操作步骤：

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

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

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

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

实操步骤：

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

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

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

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

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

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

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

1. 还是在刚才的Git Bash终端里，输入以下一键部署命令，输完按回车：

可能会报错，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 字段，如下所示：

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

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

2. 脚本会自动执行，全程不用操作，等待它跑完。期间会做这些事：
   • 自动检测你的系统环境，构建适配的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 快速部署，先把服务跑通最重要

     下一步✅ ◻ Skip for now（先选中这个选项，再按回车）

     Hooks 是「自动化钩子」：属于进阶功能（比如自动记录会话、保存上下文），对新手来说完全没必要现在配置；

     QuickStart 核心是「跑通服务」：这些钩子不影响 OpenClaw 的基础运行，现在跳过不会有任何功能缺失；

     后续可随时配置：等你熟悉了 OpenClaw 的基础用法，再用 openclaw hooks configure 单独开启 / 配置钩子即可。

     操作步骤：

     按键盘方向键（↑/↓） 把光标移到 ◻ Skip for now 上；

     按空格键（Space） 选中它（前面会出现 ◼ 实心方块）；

     按回车 Enter 确认，就能彻底完成所有初始化配置，进入服务启动环节。

3. 脚本执行完成后，会出现绿色的「success」提示，同时会显示你的访问令牌，一定要把这个令牌复制下来，后面登录要用

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

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

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

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

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

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

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

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

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

1. 以管理员身份打开PowerShell，输入以下命令，查看18789端口被谁占用了：
2. 如果输出了内容，说明端口被其他程序占用了，有2种解决方法：
   • 方法1：结束占用端口的程序，记住输出里最后一列的PID数字，输入
   • 方法2：修改OpenClaw的端口映射，在里把改成，然后重启容器，访问

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

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

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

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

1. 以管理员身份打开PowerShell，依次输入以下命令，重启WSL2：
2. 重启Docker Desktop，等待容器重新启动，再访问页面

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

根本原因：

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

解决方法：

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

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

如下图所示：

解决方法

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

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

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

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

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

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

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

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

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

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

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

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

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

如果批准后仍报错：

重启 OpenClaw 相关服务：

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

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

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

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

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

原理：

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

Win11安装步骤：

1. 打开Git Bash终端，输入以下命令，创建目录并下载助手脚本：
2. 把脚本添加到Git Bash的默认配置里，每次打开终端都能直接用：
3. 安装完成，常用命令：
   • 启动网关：
   • 停止网关：
   • 打开管理面板：
   • 查看所有命令：

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

原理：

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

Win11专属操作方法：

1. 打开Git Bash，进入openclaw代码根目录
2. 先设置环境变量，指定要挂载的文件夹，Win11路径必须用正斜杠/，不能用单反斜杠，示例：
3. 设置完环境变量后，重新执行一键部署脚本，自动生成挂载配置：
4. 脚本执行完成后，容器里就能访问你Win11本机的文件夹了

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

原理：

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

Win11启用步骤：

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

1. 沙箱镜像构建：配置完后，在Git Bash里执行以下命令，构建沙箱镜像，不然会报镜像缺失错误

1. 怎么启动/停止服务

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

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

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

3. 怎么更新版本

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

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

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