Windows 11 Docker 安装 OpenClaw 完整指南

本文档基于实际安装过程编写，包含完整的终端输入输出、所有踩过的坑和解决方案。 OpenClaw 版本：2026.3.13

前置条件

Windows 11 操作系统
已安装 Docker Desktop for Windows
Docker Desktop 已启动并正常运行（系统托盘有 Docker 图标）
确保 Docker Desktop 设置中 WSL 2 后端已启用

验证 Docker 是否正常：

PS C:\> docker --version
Docker version 27.x.x, build xxxxxxx

PS C:\> docker compose version
Docker Compose version v2.x.x

第一步：创建项目目录和配置文件

1.1 创建工作目录

PS C:\> mkdir C:\openclaw-docker
PS C:\> cd C:\openclaw-docker
PS C:\openclaw-docker> mkdir data

1.2 创建 docker-compose.yml

在 C:\openclaw-docker 目录下创建 docker-compose.yml 文件：

version: '3.8'

services:
  openclaw-gateway:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - ./data:/home/node/.openclaw
    environment:
      - TZ=Asia/Shanghai
      - NODE_ENV=production
    cap_drop:
      - NET_RAW
      - NET_ADMIN
    security_opt:
      - no-new-privileges:true

⚠️ 坑点1：YAML 冒号和横杠后必须有空格

这是最常见的新手错误。YAML 语法严格要求：

每个 key: value 的冒号后面必须有一个空格
每个列表项 - item 的横杠后面必须有一个空格

❌ 错误写法（会导致解析失败）：

    image:ghcr.io/openclaw/openclaw:latest    # 冒号后没空格
    container_name:openclaw                    # 冒号后没空格
    restart:unless-stopped                     # 冒号后没空格
    ports:
      -"127.0.0.1:18789:18789"                # 横杠后没空格
    environment:
      -TZ=Asia/Shanghai                        # 横杠后没空格

报错信息：

PS C:\openclaw-docker> docker compose up -d
yaml: while parsing a block mapping at <unknown position>: line 9, column 5: did not find expected key

✅ 正确写法：

    image: ghcr.io/openclaw/openclaw:latest    # ✅ 冒号后有空格
    container_name: openclaw                    # ✅ 冒号后有空格
    restart: unless-stopped                     # ✅ 冒号后有空格
    ports:
      - "18789:18789"                           # ✅ 横杠后有空格
    environment:
      - TZ=Asia/Shanghai                        # ✅ 横杠后有空格

⚠️ 坑点2：端口绑定不要写 127.0.0.1

❌ 不推荐：

    ports:
      - "127.0.0.1:18789:18789"

✅ 推荐（后面会解释原因）：

    ports:
      - "18789:18789"

写 127.0.0.1 虽然更安全，但配合后面的 gateway.bind 问题可能导致无法访问。建议先用 "18789:18789" 确保能跑通，之后再按需加固。

第二步：启动容器

PS C:\openclaw-docker> docker compose up -d
[+] Running 1/1
 ✔ Container openclaw  Started

首次运行会拉取镜像，可能需要几分钟。

2.1 验证容器状态

PS C:\openclaw-docker> docker ps
CONTAINER ID   IMAGE                              COMMAND                   CREATED          STATUS                    PORTS                    NAMES
52f425afe33e   ghcr.io/openclaw/openclaw:latest   "docker-entrypoint.s…"   10 seconds ago   Up 10 seconds (health: starting)   0.0.0.0:18789->18789/tcp   openclaw

注意 STATUS 列：

health: starting — 正在初始化，等一会儿
healthy — 正常运行
unhealthy — 有问题，需要查日志

2.2 查看启动日志

PS C:\openclaw-docker> docker logs openclaw --tail 30
2026-03-16T12:15:06.120+08:00 [gateway] auth token was missing. Generated a new token and saved it to config (gateway.auth.token).
2026-03-16T12:15:06.236+08:00 [canvas] host mounted at http://127.0.0.1:18789/__openclaw__/canvas/
2026-03-16T12:15:06.377+08:00 [heartbeat] started
2026-03-16T12:15:06.394+08:00 [health-monitor] started (interval: 300s, startup-grace: 60s)
2026-03-16T12:15:06.408+08:00 [gateway] agent model: anthropic/claude-opus-4-6
2026-03-16T12:15:06.419+08:00 [gateway] listening on ws://127.0.0.1:18789, ws://[::1]:18789 (PID 14)
2026-03-16T12:15:06.439+08:00 [gateway] log file: /tmp/openclaw/openclaw-2026-03-16.log
2026-03-16T12:15:06.483+08:00 [browser/server] Browser control listening on http://127.0.0.1:18791/

关键信息：

auth token was missing. Generated a new token — 首次启动自动生成了认证 Token
listening on ws://127.0.0.1:18789 — ⚠️ 这里监听的是 127.0.0.1，后面需要改
agent model: xxx — 当前使用的模型

第三步：运行 Onboard 配置向导

3.1 进入容器

PS C:\openclaw-docker> docker exec -it openclaw bash
node@52f425afe33e:/app$

3.2 运行 onboard

node@52f425afe33e:/app$ openclaw onboard
🦞 OpenClaw 2026.3.13 (unknown)

3.3 向导各步骤详解

向导会依次询问以下内容，按顺序操作：

① 安全警告

◇ I understand this is personal-by-default and shared/multi-user use requires lock-down. Continue?
→ 选 Yes

② 配置模式

◇ Onboarding mode
→ 选 QuickStart（快速配置，推荐新手）

③ 已有配置处理

◇ Existing config detected
  workspace: ~/.openclaw/workspace
  model: minimax/MiniMax-M2.5
  gateway.mode: local
  gateway.port: 18789
  gateway.bind: loopback

◇ Config handling
→ 选 Use existing values（保留现有配置）

④ 模型提供商（重要）

◇ Model/auth provider
→ 选 OpenRouter（推荐，有免费模型可用）

如果选了 MiniMax 等付费模型，后续可能遇到余额不足的问题，见坑点5。

⑤ API Key

◇ How do you want to provide this API key?
→ 选 Paste API key now

◇ Enter OpenRouter API key
→ 粘贴你的 OpenRouter API key（sk-or-v1-xxxx）

⑥ 默认模型

◇ Default model
→ 选一个免费模型，如 deepseek/deepseek-chat-v3-0324:free

⑦ 消息频道

◇ Select channel (QuickStart)
→ 选 Skip for now（稍后再配置 Telegram/Discord 等）

⑧ Web 搜索

◇ Search provider
→ 选 Skip for now（可以之后再配置）

⑨ 技能配置

◇ Configure skills now?
→ 选 Yes

◇ Install missing skill dependencies
→ 选 Skip for now

◇ Set GOOGLE_PLACES_API_KEY for goplaces?  → No
◇ Set GEMINI_API_KEY for nano-banana-pro?   → No
◇ Set NOTION_API_KEY for notion?            → No
◇ Set OPENAI_API_KEY for openai-image-gen?  → No
◇ Set OPENAI_API_KEY for openai-whisper-api? → No
◇ Set ELEVENLABS_API_KEY for sag?           → No

⑩ Hooks 自动化

◇ Enable hooks?
→ 全选：🚀 boot-md, 📎 bootstrap-extra-files, 📝 command-logger, 💾 session-memory

⑪ 启动方式

◇ How do you want to hatch your bot?
→ 选 Open the Web UI

3.4 Onboard 完成

向导结束后会显示带 Token 的 Web UI 链接：

◇ Dashboard ready
  Dashboard link (with token):
  http://127.0.0.1:18789/#token=0ee94d841bc99a099af80628b011766c464bb716afd276e9

⚠️ 先别急着打开这个链接，还有一个关键步骤要做。

退出容器：

node@52f425afe33e:/app$ exit

第四步：修复 Gateway 绑定地址（关键步骤）

⚠️ 坑点3：Gateway 默认只监听容器内 loopback，宿主机无法访问

这是整个安装过程中最大的坑。

问题描述：

OpenClaw 默认将 gateway.bind 设置为 loopback，即 Gateway 只监听容器内部的 127.0.0.1。Docker 的端口映射虽然把宿主机的 18789 转发到了容器的 18789，但容器内的服务只接受来自 127.0.0.1 的连接。从宿主机转发过来的流量源 IP 不是 127.0.0.1，所以会被拒绝。

症状表现：

# 浏览器打开 http://127.0.0.1:18789 → 显示 ERR_EMPTY_RESPONSE 或"无法访问此网站"

# PowerShell curl 报错
PS C:\openclaw-docker> curl http://127.0.0.1:18789/
curl : 基础连接已经关闭: 连接被意外关闭。

# 但 TCP 端口测试是通的（因为 Docker 端口映射本身没问题）
PS C:\openclaw-docker> Test-NetConnection -ComputerName 127.0.0.1 -Port 18789
TcpTestSucceeded : True

# 容器内部访问完全正常
PS C:\openclaw-docker> docker exec openclaw curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:18789/
200

日志特征（关键线索）：

[gateway] listening on ws://127.0.0.1:18789, ws://[::1]:18789

这里是 ws://127.0.0.1:18789 而不是 ws://0.0.0.0:18789，说明只监听了容器内部的 loopback。

4.1 修改绑定模式

进入容器：

PS C:\openclaw-docker> docker exec -it openclaw bash

修改绑定模式为 lan：

node@52f425afe33e:/app$ openclaw config set gateway.bind "lan"
Config overwrite: /home/node/.openclaw/openclaw.json
Updated gateway.bind. Restart the gateway to apply.

退出容器：

node@52f425afe33e:/app$ exit

⚠️ 坑点4：不能直接写 IP 地址 0.0.0.0

新版 OpenClaw 不支持直接写 IP 地址：

# ❌ 这样会报错
node@52f425afe33e:/app$ openclaw config set gateway.bind "0.0.0.0"
Error: Config validation failed: gateway.bind: gateway.bind host aliases (for example 0.0.0.0/localhost) are legacy; use bind modes (lan/loopback/custom/tailnet/auto) instead

必须使用模式名：

模式	说明
`loopback`	只监听 127.0.0.1（默认，容器外无法访问）
`lan`	监听所有接口 0.0.0.0（Docker 环境必须用这个）
`tailnet`	通过 Tailscale 暴露
`custom`	自定义绑定
`auto`	自动检测

4.2 重启容器使配置生效

PS C:\openclaw-docker> docker compose restart
[+] Restarting 1/1
 ✔ Container openclaw  Started

4.3 验证修复成功

查看日志确认监听地址已变更：

PS C:\openclaw-docker> docker logs openclaw --tail 10

应该看到类似：

[gateway] listening on ws://0.0.0.0:18789 (PID 14)

现在是 0.0.0.0 而不是 127.0.0.1，说明修复成功。

第五步：访问 Web UI

⚠️ 坑点5：不能直接访问 http://127.0.0.1:18789，需要带 Token

OpenClaw 的 Gateway 主要是 WebSocket 服务，直接用浏览器打开 http://127.0.0.1:18789 会显示空白或连接错误。必须使用带 Token 的完整链接。

5.1 获取带 Token 的访问链接

PS C:\openclaw-docker> docker exec openclaw openclaw dashboard --no-open

输出类似：

Dashboard link (with token):
http://127.0.0.1:18789/#token=0ee94d841bc99a099af80628b011766c464bb716afd276e9

5.2 在浏览器中打开

复制完整链接粘贴到浏览器地址栏打开。

⚠️ Token 不能少任何字符！ 之前我们就因为 Token 末尾的 e9 被截断导致无法访问。

完整 Token 示例：0ee94d841bc99a099af80628b011766c464bb716afd276e9 被截断的 Token：0ee94d841bc99a099af80628b011766c464bb716afd276 ← 少了 e9

5.3 如果 Token 丢失或过期

随时可以重新获取：

# 获取新的 dashboard 链接
PS C:\openclaw-docker> docker exec openclaw openclaw dashboard --no-open

# 或者直接查看 Token
PS C:\openclaw-docker> docker exec openclaw openclaw config get gateway.auth.token

# 或者生成新 Token
PS C:\openclaw-docker> docker exec openclaw openclaw doctor --generate-gateway-token

第六步：批准设备配对

⚠️ 坑点6：首次连接 Web UI 会提示 “pairing required”

打开 Web UI 后，页面会显示 WebSocket URL 和 Token 输入框，点击"连接"后可能看到红色提示：

pairing required

这是因为你的浏览器设备还没有被 OpenClaw 批准。

6.1 查看待批准设备

PS C:\openclaw-docker> docker exec openclaw openclaw devices list
Pending (1)
┌──────────────────────────────────────┬─────────────────────────────────────┬──────────┬────────────┬────────┐
│ Request                              │ Device                              │ Role     │ IP         │ Age    │
├──────────────────────────────────────┼─────────────────────────────────────┼──────────┼────────────┼────────┤
│ 37c48490-0ce5-4468-8897-1ca87340e200 │ 72ba2227dd060bbdd1af396c9d1dfa32... │ operator │ 172.20.0.1 │ 2m ago │
└──────────────────────────────────────┴─────────────────────────────────────┴──────────┴────────────┴────────┘

6.2 批准设备

复制 Request 列的 ID，执行批准命令：

PS C:\openclaw-docker> docker exec openclaw openclaw devices approve 37c48490-0ce5-4468-8897-1ca87340e200

6.3 连接成功

批准后回到浏览器，点击"连接"按钮，即可进入 OpenClaw 控制面板。

你会看到聊天界面，可以直接和 AI 对话了。

第七步：配置免费模型（OpenRouter）

⚠️ 坑点7：付费模型余额不足

如果你在 onboard 时选了 MiniMax 等付费模型，聊天时可能看到：

⚠ minimax (MiniMax M2.5) returned a billing error — your API key has run out of credits
or has an insufficient balance. Check your minimax billing dashboard and top up or switch
to a different API key.

解决方案：换用 OpenRouter 的免费模型。

7.1 获取 OpenRouter API Key

访问 https://openrouter.ai/settings/keys
注册/登录（支持 Google 账号登录）
页面会弹出一个调查问卷"Where did you first hear about OpenRouter?"，随便选一个（比如 Other / Not sure），点 Continue
创建 API Key，会得到类似 sk-or-v1-xxxx 的 key
立即复制保存，页面关闭后无法再查看

7.2 重新运行 Onboard 配置模型

PS C:\openclaw-docker> docker exec -it openclaw bash
node@52f425afe33e:/app$ openclaw onboard

在向导中：

Config handling → Use existing values
Model/auth provider → OpenRouter
API key → 粘贴你的 sk-or-v1-xxxx
Default model → 选一个带 :free 后缀的免费模型

退出容器并重启：

node@52f425afe33e:/app$ exit

PS C:\openclaw-docker> docker compose restart

7.3 推荐的免费模型

模型 ID	特点
`deepseek/deepseek-chat-v3-0324:free`	中文能力强，编程能力好
`google/gemini-2.5-flash-preview:free`	速度快，支持多模态（图片）

浏览所有免费模型：https://openrouter.ai/collections/free-models

OpenRouter 免费模型限制：

20 请求/分钟
每天 50-1000 请求（取决于账户余额）

7.4 其他免费模型提供商（备选方案）

提供商	免费额度	获取地址
Google Gemini	250次/天	https://aistudio.google.com/apikey
Qwen（通义千问）	2000次/天	https://qwen.ai/apiplatform
Kimi K2.5 (NVIDIA)	免费但延迟高	https://build.nvidia.com/settings/api-keys

OpenClaw 命令大全

以下命令均在宿主机 PowerShell 中执行（通过 docker exec 调用容器内的 openclaw CLI）。

Docker 容器管理

# 启动容器（后台运行）
docker compose up -d

# 停止并删除容器
docker compose down

# 重启容器（配置修改后需要重启）
docker compose restart

# 查看容器状态
docker ps

# 查看容器日志（最近50行）
docker logs openclaw --tail 50

# 实时查看日志（Ctrl+C 退出）
docker logs openclaw -f

# 进入容器 bash
docker exec -it openclaw bash

# 以 root 身份进入容器（安装额外软件包时需要）
docker exec -it -u root openclaw bash
# 例如安装 ripgrep：apt-get update && apt-get install -y ripgrep

Onboard 配置

# 运行完整配置向导
docker exec -it openclaw openclaw onboard

# 只配置模型部分
docker exec -it openclaw openclaw configure --section model

# 只配置 Web 搜索
docker exec -it openclaw openclaw configure --section web

# 只配置频道（Telegram/Discord 等）
docker exec -it openclaw openclaw configure --section channels

配置管理

# 查看某项配置
docker exec openclaw openclaw config get gateway.bind
docker exec openclaw openclaw config get model
docker exec openclaw openclaw config get gateway.auth.token

# 修改配置（修改后需要 docker compose restart）
docker exec openclaw openclaw config set gateway.bind "lan"
docker exec openclaw openclaw config set model.provider "openrouter"

Web UI / Dashboard

# 获取带 Token 的 Web UI 链接
docker exec openclaw openclaw dashboard --no-open

# 生成新的 Gateway Token
docker exec openclaw openclaw doctor --generate-gateway-token

设备管理

# 查看所有设备（包括待批准和已配对的）
docker exec openclaw openclaw devices list

# 批准设备配对
docker exec openclaw openclaw devices approve <REQUEST_ID>

频道配对（Telegram/Discord/WhatsApp 等）

# 查看配对状态
docker exec openclaw openclaw pairing list

# 批准频道配对
docker exec openclaw openclaw pairing approve <channel> <code>

模型管理

# 查看当前模型
docker exec openclaw openclaw models list

# 切换模型
docker exec openclaw openclaw models set <model_id>
# 例如：
docker exec openclaw openclaw models set openrouter/deepseek/deepseek-chat-v3-0324:free

Hooks 自动化

# 查看所有 hooks
docker exec openclaw openclaw hooks list

# 启用 hook
docker exec openclaw openclaw hooks enable <name>

# 禁用 hook
docker exec openclaw openclaw hooks disable <name>

插件管理

# 查看已安装插件
docker exec openclaw openclaw plugins list

# 启用插件
docker exec openclaw openclaw plugins enable <plugin_name>

# 禁用插件
docker exec openclaw openclaw plugins disable <plugin_name>

安全审计

# 运行安全审计
docker exec openclaw openclaw security audit --deep

# 自动修复安全问题
docker exec openclaw openclaw security audit --fix

会话管理

# 查看状态
docker exec openclaw openclaw status

踩坑总结

#	问题	症状	原因	解决方案
1	YAML 语法错误	`did not find expected key`	冒号/横杠后缺少空格	所有 `:` 和 `-` 后面加空格
2	端口绑定过严	配合坑点3导致无法访问	`ports` 写了 `127.0.0.1:18789:18789`	改为 `"18789:18789"`
3	Gateway 只监听 loopback	浏览器 `ERR_EMPTY_RESPONSE`，容器内正常	`gateway.bind` 默认为 `loopback`	`openclaw config set gateway.bind "lan"` 然后重启
4	bind 设置报错	`gateway.bind host aliases are legacy`	新版不支持直接写 IP 地址	使用模式名 `lan` 而非 `0.0.0.0`
5	直接访问端口无响应	浏览器打开 18789 空白	需要带 Token 认证	`openclaw dashboard --no-open` 获取完整链接
6	连接后提示配对	`pairing required`	浏览器设备未被批准	`openclaw devices list` 然后 `openclaw devices approve <ID>`
7	模型调用失败	`billing error` / 余额不足	付费模型 API key 没钱了	换用 OpenRouter 免费模型（带 `:free` 后缀）

排查问题的诊断命令

当遇到无法访问的问题时，按以下顺序排查：

# 1. 容器是否在运行？
docker ps

# 2. 端口映射是否正确？（应该看到 0.0.0.0:18789->18789/tcp）
docker ps --format "table {{.Names}}\t{{.Ports}}"

# 3. TCP 端口是否通？
Test-NetConnection -ComputerName 127.0.0.1 -Port 18789

# 4. 容器内部服务是否正常？（应该返回 200）
docker exec openclaw curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:18789/

# 5. 查看日志中 Gateway 监听地址（应该是 0.0.0.0 而非 127.0.0.1）
docker logs openclaw --tail 10

如果第4步返回 200 但浏览器打不开，说明是 gateway.bind 的问题（坑点3）。

数据持久化与备份

所有配置和数据保存在宿主机的 C:\openclaw-docker\data 目录中：

data/
├── openclaw.json          # 主配置文件（API key、模型设置等）
├── openclaw.json.bak      # 配置备份（每次修改自动生成）
├── workspace/             # Agent 工作空间
├── agents/                # Agent 会话数据
│   └── main/
│       └── sessions/      # 聊天会话记录
└── canvas/                # Canvas 数据

重建容器（docker compose down + docker compose up -d）不会丢失数据，只要 data 目录还在
建议定期备份 data 目录
openclaw.json 包含你的 API key，注意保密

代理配置（可选）

如果你在中国大陆，访问 OpenRouter 等国外 API 可能需要代理。

编辑 docker-compose.yml 的 environment 部分：

    environment:
      - TZ=Asia/Shanghai
      - NODE_ENV=production
      - http_proxy=http://host.docker.internal:7890
      - https_proxy=http://host.docker.internal:7890

host.docker.internal 是 Docker Desktop 自动提供的宿主机地址
7890 替换为你的代理软件实际端口（Clash 默认 7890，V2Ray 默认 10809）
修改后需要 docker compose down + docker compose up -d 重建容器

完整安装流程速览

1. 创建目录 + docker-compose.yml
2. docker compose up -d
3. docker exec -it openclaw openclaw onboard（配置模型和 API key）
4. docker exec openclaw openclaw config set gateway.bind "lan"（修复绑定）
5. docker compose restart（重启生效）
6. docker exec openclaw openclaw dashboard --no-open（获取链接）
7. 浏览器打开带 Token 的链接
8. docker exec openclaw openclaw devices approve <ID>（批准设备）
9. 开始使用 🦞

基于实际安装过程编写，每一个坑都是亲自踩过的。