1. Win11 上跑 OpenClaw为什么我建议你用 Docker WSL2OpenClaw 是一个 AI Agent 网关简单说就是帮你统一管理各种 AI 模型调用、让 AI 安全执行工具命令的中间层程序。它原生跑在 Linux 生态里直接装到 Win11 上会遇到一堆兼容性问题——依赖缺失、路径格式不对、脚本执行权限报错折腾半天可能连启动都过不去。Docker 在这里的角色就是给 OpenClaw 搭一个独立的 Linux 小盒子所有东西都在盒子里跑跟你 Win11 本机完全隔离删了就全清零污染。而 WSL2 是 Win11 自带的 Linux 子系统Docker Desktop 在 Win11 上必须靠它才能正常跑 Linux 容器。这套方案适合谁如果你是用 Win11 做开发、想让 AI 帮你操作本地代码或执行命令又不想把本机环境搞乱那 Docker WSL2 部署 OpenClaw 就是最稳的路径。我实测下来整个流程走通大概 20 分钟但前提是前置环境得配对——顺序反了或者路径带中文后面全是坑。这篇会从 WSL2 开启、Docker Desktop 安装、镜像拉取加速、docker-compose 配置、TaoToken 统一 Key 接入一直讲到容器启动后的接口验证和常见报错排查。每一步都有可复制的命令和配置你跟着做就行。2. 前置环境WSL2 和 Docker Desktop 的安装顺序不能反2.1 先开 WSL2再装 DockerWin11 默认不开启 Linux 子系统你得手动打开。按下 Win 键搜索「启用或关闭 Windows 功能」勾选「适用于 Linux 的 Windows 子系统」和「虚拟机平台」确定后重启电脑。重启完打开 PowerShell管理员执行wsl --install wsl --set-default-version 2验证是否成功wsl --list --verbose输出里 VERSION 列显示 2 就对了。如果显示 1手动转一下wsl --set-version 发行版名 2。注意一定要先开 WSL2 再装 Docker Desktop。顺序反了 Docker 启动会失败报各种奇怪的错。2.2 安装 Docker Desktop去 Docker 官网下载 Win11 安装包双击安装时务必勾选「Use the WSL 2 based engine」。装完打开 Docker Desktop跳过登录等左下角图标从黄色变绿色就启动成功了。验证docker --version docker compose version两条命令都能输出版本号即可。2.3 路径规范纯英文、无空格所有跟 OpenClaw 相关的文件路径绝对不能有中文、空格、特殊符号。不要放「桌面」「我的文档」「新建文件夹 (2)」推荐直接放D:\openclaw这种纯英文无空格路径。这个坑我踩过路径带中文会导致卷挂载失败容器启动时报invalid mount path。3. TaoToken 前置统一 Key 和 API 通道怎么配OpenClaw 初始化时会让你选模型服务商、填 API Key。如果你手上有多个模型的 Key一个个配很麻烦而且国内直连某些 API 经常超时。我的做法是用 TaoToken 做统一通道——一个 Key 走所有模型API 地址统一成https://taotoken.net/api省去反复切换配置的麻烦。具体操作先去 TaoToken 官网注册账号然后在控制台创建一个 API Key。拿到 Key 之后在 OpenClaw 的初始化向导里选模型服务商时如果你要用 TaoToken 的统一通道选自定义 OpenAI 兼容接口Base URL 填https://taotoken.net/apiKey 填你刚创建的。如果你还没决定用哪个模型初始化时可以选Skip for now跳过先把服务跑起来后面用openclaw configure随时补上。想先体验模型对话效果的可以直接去 TaoToken 的模型对话页面试一下通道通不通。对于长期跑编码任务或 Agent 的场景建议了解一下 Coding Plan额度更划算。API Key 的管理入口在控制台的 API Keys 页面。4. 可复制配置docker-compose 与 config.toml 骨架4.1 拉取代码与目录结构在 D 盘新建D:\openclaw右键选「Open Git Bash Here」执行git clone https://github.com/openclaw/openclaw.git cd openclaw如果 git clone 报Recv failure: Connection was reset直接去 GitHub 页面点 Code → Download ZIP解压到D:\openclaw即可效果一样。4.2 docker-compose.yml 核心配置OpenClaw 官方提供了一键脚本docker-setup.sh但如果你想自己控制端口映射和卷挂载可以直接写 docker-compose.yml。以下是我实测可用的骨架services: openclaw-gateway: image: openclaw/gateway:latest container_name: openclaw-gateway restart: unless-stopped ports: - 18789:18789 volumes: - ./data:/home/node/.openclaw - D:/codex:/home/node/.codex:ro environment: - NODE_OPTIONS--max-old-space-size4096 - OPENCLAW_API_BASEhttps://taotoken.net/api - OPENCLAW_API_KEYsk-your-taotoken-key networks: - openclaw-net openclaw-cli: image: openclaw/gateway:latest container_name: openclaw-cli entrypoint: [openclaw] volumes: - ./data:/home/node/.openclaw networks: - openclaw-net networks: openclaw-net: driver: bridge几个关键点端口映射18789:18789前面是宿主机端口后面是容器端口如果 18789 被占用改成18790:18789就行。卷挂载里D:/codex:/home/node/.codex:ro是把本机 D 盘的 codex 文件夹以只读方式挂给容器Win11 路径必须用正斜杠/不能用反斜杠。环境变量里OPENCLAW_API_BASE指向 TaoToken 的 API 地址OPENCLAW_API_KEY填你的 Key。4.3 config.toml 模型配置骨架OpenClaw 的模型配置在~/.openclaw/config.toml容器里对应./data/config.toml。骨架如下[gateway] port 18789 token your-gateway-token [models.default] provider openai-compatible base_url https://taotoken.net/api api_key sk-your-taotoken-key model claude-opus-4-6 [agents.defaults.sandbox] mode non-main scope agent workspaceAccess none workspaceRoot ~/.openclaw/sandboxes [agents.defaults.sandbox.docker] image openclaw-sandbox:bookworm-slim workdir /workspace readOnlyRoot true network none memory 1g cpus 1沙箱配置是给 AI 单独开隔离盒子用的AI 执行命令都在盒子里跑就算操作失误也不会弄坏你本机文件。配完后需要构建沙箱镜像scripts/sandbox-setup.sh4.4 镜像拉取加速国内直接拉 Docker Hub 镜像经常超时。打开 Docker Desktop → Settings → Docker Engine在 JSON 里加 registry-mirrors{ builder: { gc: { defaultKeepStorage: 20GB, enabled: true } }, experimental: false, registry-mirrors: [ https://docker.1panel.live, https://docker.1ms.run ] }点 Apply restart 生效。如果构建时卡在 bun 包安装改 Dockerfile 里的 bun 安装命令加超时参数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编译时内存溢出的话在RUN pnpm build之前加ENV NODE_OPTIONS--max-old-space-size40965. 验证请求容器状态与接口连通性逐条检查5.1 启动容器在 Git Bash 里进入D:\openclaw执行docker compose up -d查看容器状态docker compose ps看到openclaw-gateway状态是Up就对了。如果显示Exit或Restarting看日志docker compose logs -f openclaw-gateway5.2 验证端口映射netstat -ano | findstr :18789有输出说明端口在监听。浏览器访问http://127.0.0.1:18789/能看到管理页面就代表网关通了。5.3 验证 TaoToken API 通道在容器里用 curl 测一下 API 连通性docker exec -it openclaw-gateway /bin/sh curl -s -o /dev/null -w %{http_code} https://taotoken.net/api/v1/models \ -H Authorization: Bearer sk-your-taotoken-key返回 200 说明通道正常。如果返回 401检查 Key 有没有填对返回超时检查容器网络能不能出外网。5.4 获取网关 Token初始化脚本跑完后会显示访问令牌没记下来的话用这个命令查docker exec -u root -it openclaw-gateway /bin/sh su node cat ~/.openclaw/openclaw.json | grep -i token拿到 Token 后在管理页面的设置里粘贴进去保存即可进入完整管理界面。6. 本篇常见错排查从 URL 报错到 pairing required6.1 访问 127.0.0.1:18789 提示「URL 拼写可能存在错误」这个报错不是 URL 写错了是 Win11 环境或配置出了问题。按顺序排查先确认容器是否在运行Docker Desktop → Containers 里看openclaw-gateway是不是绿色 Running。没运行就点启动启动失败就看日志。再查端口占用netstat -ano | findstr :18789有输出的话记住最后一列 PIDtaskkill /f /pid PID结束占用程序或者改 docker-compose.yml 里的端口映射为18790:18789重启容器后访问http://127.0.0.1:18790/。然后放行防火墙Windows Defender 防火墙 → 允许应用通过防火墙 → 找到「Docker Desktop Backend」专用和公用都勾上。最后修 WSL2 端口转发wsl --shutdown net stop LxssManager net start LxssManager重启 Docker Desktop等容器重新起来再访问。6.2 OAuth 回调 127.0.0.1:1455 报 URL 错误Docker 容器里的 OAuth 回调会尝试在你 Win11 本机的 1455 端口捕获认证信息但容器和本机网络隔离浏览器访问不到。解决方法不要关浏览器的回调页面哪怕它显示报错复制地址栏里的完整重定向 URL回到 Git Bash 终端会看到提示让你粘贴回调地址粘贴进去按回车终端会自动完成认证。6.3 code1008 reasonpairing required这是设备配对没完成。先获取带 token 的控制台链接docker compose run --rm openclaw-cli dashboard --no-open输出一个 URL保存好。然后列出待授权设备docker compose run --rm openclaw-cli devices list找到 Status 为 PENDING 的 ID批准docker compose run --rm openclaw-cli devices approve dev_123456789多个设备可以批量批准docker compose run --rm openclaw-cli devices approve --all再执行devices list确认状态变成 PAIRED打开之前保存的控制台链接就能正常登录了。如果提示No such service: openclaw-cli检查 docker-compose.yml 里 CLI 服务的实际名称替换命令里的服务名即可。7. 接入文档与后续操作入口容器跑起来、接口验证通过之后日常使用就是启动/停止容器、看日志、更新版本这几件事。启动用docker compose up -d停止用docker compose down看实时日志用docker compose logs -f openclaw-gateway。更新版本先git pull拉最新代码再重新执行./docker-setup.sh脚本会自动构建新镜像并重启容器配置不会丢。如果你在接入过程中遇到 API 通道报错、Key 鉴权失败、模型调用超时这类问题建议直接翻一下 TaoToken 的接入文档里面有各语言 SDK 的配置示例和错误码说明。需要管理或新建 Key 的话控制台 API Keys 页面可以操作。想先验证模型对话效果模型对话页面可以直接试。长期跑编码任务或 Agent 场景Coding Plan 的额度方案更合适。整套流程走下来最关键的其实就是前置环境顺序别反、路径别带中文、端口别冲突这三件事。剩下的按步骤复制粘贴就行。
【部署】Docker部署OpenClaw及常见问题解决（win11）
1. Win11 上跑 OpenClaw为什么我建议你用 Docker WSL2OpenClaw 是一个 AI Agent 网关简单说就是帮你统一管理各种 AI 模型调用、让 AI 安全执行工具命令的中间层程序。它原生跑在 Linux 生态里直接装到 Win11 上会遇到一堆兼容性问题——依赖缺失、路径格式不对、脚本执行权限报错折腾半天可能连启动都过不去。Docker 在这里的角色就是给 OpenClaw 搭一个独立的 Linux 小盒子所有东西都在盒子里跑跟你 Win11 本机完全隔离删了就全清零污染。而 WSL2 是 Win11 自带的 Linux 子系统Docker Desktop 在 Win11 上必须靠它才能正常跑 Linux 容器。这套方案适合谁如果你是用 Win11 做开发、想让 AI 帮你操作本地代码或执行命令又不想把本机环境搞乱那 Docker WSL2 部署 OpenClaw 就是最稳的路径。我实测下来整个流程走通大概 20 分钟但前提是前置环境得配对——顺序反了或者路径带中文后面全是坑。这篇会从 WSL2 开启、Docker Desktop 安装、镜像拉取加速、docker-compose 配置、TaoToken 统一 Key 接入一直讲到容器启动后的接口验证和常见报错排查。每一步都有可复制的命令和配置你跟着做就行。2. 前置环境WSL2 和 Docker Desktop 的安装顺序不能反2.1 先开 WSL2再装 DockerWin11 默认不开启 Linux 子系统你得手动打开。按下 Win 键搜索「启用或关闭 Windows 功能」勾选「适用于 Linux 的 Windows 子系统」和「虚拟机平台」确定后重启电脑。重启完打开 PowerShell管理员执行wsl --install wsl --set-default-version 2验证是否成功wsl --list --verbose输出里 VERSION 列显示 2 就对了。如果显示 1手动转一下wsl --set-version 发行版名 2。注意一定要先开 WSL2 再装 Docker Desktop。顺序反了 Docker 启动会失败报各种奇怪的错。2.2 安装 Docker Desktop去 Docker 官网下载 Win11 安装包双击安装时务必勾选「Use the WSL 2 based engine」。装完打开 Docker Desktop跳过登录等左下角图标从黄色变绿色就启动成功了。验证docker --version docker compose version两条命令都能输出版本号即可。2.3 路径规范纯英文、无空格所有跟 OpenClaw 相关的文件路径绝对不能有中文、空格、特殊符号。不要放「桌面」「我的文档」「新建文件夹 (2)」推荐直接放D:\openclaw这种纯英文无空格路径。这个坑我踩过路径带中文会导致卷挂载失败容器启动时报invalid mount path。3. TaoToken 前置统一 Key 和 API 通道怎么配OpenClaw 初始化时会让你选模型服务商、填 API Key。如果你手上有多个模型的 Key一个个配很麻烦而且国内直连某些 API 经常超时。我的做法是用 TaoToken 做统一通道——一个 Key 走所有模型API 地址统一成https://taotoken.net/api省去反复切换配置的麻烦。具体操作先去 TaoToken 官网注册账号然后在控制台创建一个 API Key。拿到 Key 之后在 OpenClaw 的初始化向导里选模型服务商时如果你要用 TaoToken 的统一通道选自定义 OpenAI 兼容接口Base URL 填https://taotoken.net/apiKey 填你刚创建的。如果你还没决定用哪个模型初始化时可以选Skip for now跳过先把服务跑起来后面用openclaw configure随时补上。想先体验模型对话效果的可以直接去 TaoToken 的模型对话页面试一下通道通不通。对于长期跑编码任务或 Agent 的场景建议了解一下 Coding Plan额度更划算。API Key 的管理入口在控制台的 API Keys 页面。4. 可复制配置docker-compose 与 config.toml 骨架4.1 拉取代码与目录结构在 D 盘新建D:\openclaw右键选「Open Git Bash Here」执行git clone https://github.com/openclaw/openclaw.git cd openclaw如果 git clone 报Recv failure: Connection was reset直接去 GitHub 页面点 Code → Download ZIP解压到D:\openclaw即可效果一样。4.2 docker-compose.yml 核心配置OpenClaw 官方提供了一键脚本docker-setup.sh但如果你想自己控制端口映射和卷挂载可以直接写 docker-compose.yml。以下是我实测可用的骨架services: openclaw-gateway: image: openclaw/gateway:latest container_name: openclaw-gateway restart: unless-stopped ports: - 18789:18789 volumes: - ./data:/home/node/.openclaw - D:/codex:/home/node/.codex:ro environment: - NODE_OPTIONS--max-old-space-size4096 - OPENCLAW_API_BASEhttps://taotoken.net/api - OPENCLAW_API_KEYsk-your-taotoken-key networks: - openclaw-net openclaw-cli: image: openclaw/gateway:latest container_name: openclaw-cli entrypoint: [openclaw] volumes: - ./data:/home/node/.openclaw networks: - openclaw-net networks: openclaw-net: driver: bridge几个关键点端口映射18789:18789前面是宿主机端口后面是容器端口如果 18789 被占用改成18790:18789就行。卷挂载里D:/codex:/home/node/.codex:ro是把本机 D 盘的 codex 文件夹以只读方式挂给容器Win11 路径必须用正斜杠/不能用反斜杠。环境变量里OPENCLAW_API_BASE指向 TaoToken 的 API 地址OPENCLAW_API_KEY填你的 Key。4.3 config.toml 模型配置骨架OpenClaw 的模型配置在~/.openclaw/config.toml容器里对应./data/config.toml。骨架如下[gateway] port 18789 token your-gateway-token [models.default] provider openai-compatible base_url https://taotoken.net/api api_key sk-your-taotoken-key model claude-opus-4-6 [agents.defaults.sandbox] mode non-main scope agent workspaceAccess none workspaceRoot ~/.openclaw/sandboxes [agents.defaults.sandbox.docker] image openclaw-sandbox:bookworm-slim workdir /workspace readOnlyRoot true network none memory 1g cpus 1沙箱配置是给 AI 单独开隔离盒子用的AI 执行命令都在盒子里跑就算操作失误也不会弄坏你本机文件。配完后需要构建沙箱镜像scripts/sandbox-setup.sh4.4 镜像拉取加速国内直接拉 Docker Hub 镜像经常超时。打开 Docker Desktop → Settings → Docker Engine在 JSON 里加 registry-mirrors{ builder: { gc: { defaultKeepStorage: 20GB, enabled: true } }, experimental: false, registry-mirrors: [ https://docker.1panel.live, https://docker.1ms.run ] }点 Apply restart 生效。如果构建时卡在 bun 包安装改 Dockerfile 里的 bun 安装命令加超时参数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编译时内存溢出的话在RUN pnpm build之前加ENV NODE_OPTIONS--max-old-space-size40965. 验证请求容器状态与接口连通性逐条检查5.1 启动容器在 Git Bash 里进入D:\openclaw执行docker compose up -d查看容器状态docker compose ps看到openclaw-gateway状态是Up就对了。如果显示Exit或Restarting看日志docker compose logs -f openclaw-gateway5.2 验证端口映射netstat -ano | findstr :18789有输出说明端口在监听。浏览器访问http://127.0.0.1:18789/能看到管理页面就代表网关通了。5.3 验证 TaoToken API 通道在容器里用 curl 测一下 API 连通性docker exec -it openclaw-gateway /bin/sh curl -s -o /dev/null -w %{http_code} https://taotoken.net/api/v1/models \ -H Authorization: Bearer sk-your-taotoken-key返回 200 说明通道正常。如果返回 401检查 Key 有没有填对返回超时检查容器网络能不能出外网。5.4 获取网关 Token初始化脚本跑完后会显示访问令牌没记下来的话用这个命令查docker exec -u root -it openclaw-gateway /bin/sh su node cat ~/.openclaw/openclaw.json | grep -i token拿到 Token 后在管理页面的设置里粘贴进去保存即可进入完整管理界面。6. 本篇常见错排查从 URL 报错到 pairing required6.1 访问 127.0.0.1:18789 提示「URL 拼写可能存在错误」这个报错不是 URL 写错了是 Win11 环境或配置出了问题。按顺序排查先确认容器是否在运行Docker Desktop → Containers 里看openclaw-gateway是不是绿色 Running。没运行就点启动启动失败就看日志。再查端口占用netstat -ano | findstr :18789有输出的话记住最后一列 PIDtaskkill /f /pid PID结束占用程序或者改 docker-compose.yml 里的端口映射为18790:18789重启容器后访问http://127.0.0.1:18790/。然后放行防火墙Windows Defender 防火墙 → 允许应用通过防火墙 → 找到「Docker Desktop Backend」专用和公用都勾上。最后修 WSL2 端口转发wsl --shutdown net stop LxssManager net start LxssManager重启 Docker Desktop等容器重新起来再访问。6.2 OAuth 回调 127.0.0.1:1455 报 URL 错误Docker 容器里的 OAuth 回调会尝试在你 Win11 本机的 1455 端口捕获认证信息但容器和本机网络隔离浏览器访问不到。解决方法不要关浏览器的回调页面哪怕它显示报错复制地址栏里的完整重定向 URL回到 Git Bash 终端会看到提示让你粘贴回调地址粘贴进去按回车终端会自动完成认证。6.3 code1008 reasonpairing required这是设备配对没完成。先获取带 token 的控制台链接docker compose run --rm openclaw-cli dashboard --no-open输出一个 URL保存好。然后列出待授权设备docker compose run --rm openclaw-cli devices list找到 Status 为 PENDING 的 ID批准docker compose run --rm openclaw-cli devices approve dev_123456789多个设备可以批量批准docker compose run --rm openclaw-cli devices approve --all再执行devices list确认状态变成 PAIRED打开之前保存的控制台链接就能正常登录了。如果提示No such service: openclaw-cli检查 docker-compose.yml 里 CLI 服务的实际名称替换命令里的服务名即可。7. 接入文档与后续操作入口容器跑起来、接口验证通过之后日常使用就是启动/停止容器、看日志、更新版本这几件事。启动用docker compose up -d停止用docker compose down看实时日志用docker compose logs -f openclaw-gateway。更新版本先git pull拉最新代码再重新执行./docker-setup.sh脚本会自动构建新镜像并重启容器配置不会丢。如果你在接入过程中遇到 API 通道报错、Key 鉴权失败、模型调用超时这类问题建议直接翻一下 TaoToken 的接入文档里面有各语言 SDK 的配置示例和错误码说明。需要管理或新建 Key 的话控制台 API Keys 页面可以操作。想先验证模型对话效果模型对话页面可以直接试。长期跑编码任务或 Agent 场景Coding Plan 的额度方案更合适。整套流程走下来最关键的其实就是前置环境顺序别反、路径别带中文、端口别冲突这三件事。剩下的按步骤复制粘贴就行。
