OpenClaw 安装部署文档（Windows 桌面版）

适用系统：Windows 10 (21H2+) / Windows 11日期：2026-02-20本章节，将接着上一章继续介绍在操作系统中通过Docker安装OpenClaw。

七号隐身了

3160人浏览 · 2026-02-20 16:35:47

七号隐身了 · 2026-02-20 16:35:47 发布

OpenClaw 安装部署文档（Windows 桌面版）

适用系统：Windows 10 (21H2+) / Windows 11
日期：2026-02-20

本章节，将接着上一章继续介绍在Windows 操作系统中通过Docker安装OpenClaw

一、环境说明

1.1 与 Windows Server 的区别

对比项	Windows 桌面版	Windows Server
Docker 方案	Docker Desktop（图形界面，自带 WSL2 集成）	Docker Engine + WSL2 手动安装
WSL2	系统自带，开箱即用	需手动启用功能并重启
Linux 容器支持	Docker Desktop 原生支持切换	需通过 WSL2 内的 Docker Engine
操作方式	图形界面 + 命令行均可	纯命令行
端口转发	Docker Desktop 自动处理	需手动配置 netsh portproxy
HTTPS（外部访问）	仅局域网访问时需要	必须配置

Windows 桌面版使用 Docker Desktop 是最简单的方式，它自带 WSL2 后端，无需手动在 WSL 中安装 Docker。

二、安装 Docker Desktop

2.1 系统要求

Windows 10 版本 21H2 及以上，或 Windows 11
64 位系统
BIOS 中已启用虚拟化（VT-x / AMD-V）
至少 4GB 内存

2.2 检查虚拟化是否启用

按 Ctrl + Shift + Esc 打开任务管理器 → 性能 → CPU，查看右下方是否显示"虚拟化: 已启用"。

如果未启用，需要进入 BIOS 开启：

Intel：启用 Intel VT-x / Intel Virtualization Technology
AMD：启用 AMD-V / SVM Mode

2.3 启用 WSL2

打开 PowerShell（管理员），执行：

wsl --install

此命令会自动：

启用"适用于 Linux 的 Windows 子系统"功能
启用"虚拟机平台"功能
下载并安装 WSL2 Linux 内核
设置 WSL2 为默认版本
下载并安装 Ubuntu

安装完成后需要重启电脑。

重启后验证：

wsl --version
wsl --list --verbose

2.4 下载 Docker Desktop

访问官网下载安装包：

https://www.docker.com/products/docker-desktop/

或直接下载链接：

https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe

2.5 安装 Docker Desktop

双击运行 Docker Desktop Installer.exe
安装选项中确保勾选：
- ✅ Use WSL 2 instead of Hyper-V（使用 WSL2 后端）
- ✅ Add shortcut to desktop
点击 OK 开始安装
安装完成后点击 Close and restart（需要重启）

2.6 首次启动 Docker Desktop

重启后，Docker Desktop 会自动启动（系统托盘出现鲸鱼图标）
首次启动可能需要等待 1-2 分钟初始化
接受服务条款
可跳过登录（Skip）和问卷调查

2.7 验证 Docker 安装

打开 PowerShell 或 CMD：

docker --version
docker compose version
docker run hello-world

如果 hello-world 正常输出 “Hello from Docker!”，说明安装成功。

三、配置 Docker 镜像加速

3.1 图形界面配置（推荐）

右键系统托盘的 Docker 鲸鱼图标 → Settings（设置）
左侧选择 Docker Engine
在 JSON 配置中添加 registry-mirrors：

{
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  },
  "experimental": false,
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.xuanyuan.me",
    "https://docker.m.daocloud.io",
    "https://hub.rat.dev",
    "https://docker.1panel.live"
  ]
}

点击 Apply & restart

3.2 验证镜像加速

docker info | findstr "Mirror"

应输出配置的镜像地址列表。

四、修改 Docker 数据存储位置（可选）

Docker Desktop 默认将数据存储在 C 盘。如果 C 盘空间有限，可以迁移到其他盘。

4.1 方法一：Docker Desktop 设置

Docker Desktop → Settings → Resources → Advanced
找到 Disk image location
点击 Browse，选择新路径（如 D:\Docker\data）
点击 Apply & restart

4.2 方法二：WSL 迁移

# 停止 Docker Desktop

# 导出 WSL 中的 docker-desktop-data
wsl --export docker-desktop-data D:\Docker\docker-desktop-data.tar

# 注销原有的
wsl --unregister docker-desktop-data

# 导入到新位置
wsl --import docker-desktop-data D:\Docker\data D:\Docker\docker-desktop-data.tar

# 删除导出的临时文件
del D:\Docker\docker-desktop-data.tar

# 重启 Docker Desktop

五、获取 OpenClaw 项目

5.1 安装 Git（如果没有）

下载安装 Git for Windows：

https://git-scm.com/download/win

5.2 克隆项目

打开 PowerShell，执行：

cd D:\OpenClaw
git clone https://github.com/anthropics/openclaw.git
cd openclaw

如果 GitHub 访问慢，可使用镜像：

git clone https://ghproxy.com/https://github.com/anthropics/openclaw.git

或者直接下载 ZIP 压缩包后解压到 D:\OpenClaw\openclaw。

六、构建 OpenClaw Docker 镜像

6.1 进入项目目录

cd D:\OpenClaw\openclaw

6.2 构建镜像

docker build -t openclaw:local -f Dockerfile .

构建过程大约需要 5-10 分钟，主要步骤：

拉取 node:22-bookworm 基础镜像（约 400MB）
安装 Bun 构建工具
执行 pnpm install 安装项目依赖
执行 pnpm build 编译后端
执行 pnpm ui:build 构建前端 UI
设置文件权限

6.3 验证镜像

docker images openclaw:local

七、配置并启动 OpenClaw

7.1 创建 .env 环境变量文件

在项目目录 D:\OpenClaw\openclaw\ 下创建 .env 文件：

OPENCLAW_CONFIG_DIR=C:\Users\你的用户名\.openclaw
OPENCLAW_WORKSPACE_DIR=C:\Users\你的用户名\.openclaw\workspace
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_BRIDGE_PORT=18790
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_TOKEN=替换为你的随机Token
OPENCLAW_IMAGE=openclaw:local

生成随机 Token：

# 方法一：使用 PowerShell
-join ((1..64) | ForEach-Object { '{0:x}' -f (Get-Random -Maximum 16) })

# 方法二：使用 OpenSSL（如果已安装 Git，自带 OpenSSL）
& "C:\Program Files\Git\usr\bin\openssl.exe" rand -hex 32

请记住这个 Token 值，后续配置 Gateway 配置文件和浏览器访问时都需要用到。

7.2 创建配置目录

mkdir "$env:USERPROFILE\.openclaw\workspace" -Force

7.3 修改 docker-compose.yml

用文本编辑器打开 docker-compose.yml，在 openclaw-gateway 服务的 command 末尾添加 "--allow-unconfigured"：

    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${OPENCLAW_GATEWAY_BIND:-lan}",
        "--port",
        "18789",
        "--allow-unconfigured",
      ]

7.4 启动服务

cd D:\OpenClaw\openclaw
docker compose up -d openclaw-gateway

7.5 验证启动

查看容器状态：

docker ps

查看日志：

docker logs openclaw-openclaw-gateway-1 --tail 10

关键日志行：

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

浏览器访问验证：打开 http://localhost:18789，能正常加载即为成功。

八、Gateway 配置文件（openclaw.json）

启动后需要创建 Gateway 的核心配置文件，用于设置认证、模型提供者等。

8.1 确定配置文件路径

Docker Desktop 将 .env 中的 OPENCLAW_CONFIG_DIR 映射到容器内的 /home/node/.openclaw。

配置文件在 Windows 上的位置：

C:\Users\你的用户名\.openclaw\openclaw.json

8.2 创建配置文件

用文本编辑器（如记事本、VS Code）在 C:\Users\你的用户名\.openclaw\ 目录下创建 openclaw.json，内容如下：

{
  "gateway": {
    "mode": "local",
    "auth": {
      "token": "<粘贴你在 .env 中设置的 OPENCLAW_GATEWAY_TOKEN>"
    },
    "bind": "lan",
    "port": 18789
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "deepseek/deepseek-chat"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com/v1",
        "apiKey": "<你的 DeepSeek API Key>",
        "api": "openai-completions",
        "models": [
          {
            "id": "deepseek-chat",
            "name": "DeepSeek V3",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 64000,
            "maxTokens": 8192
          },
          {
            "id": "deepseek-reasoner",
            "name": "DeepSeek R1",
            "reasoning": true,
            "input": ["text"],
            "contextWindow": 64000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

注意：gateway.auth.token 的值必须与 .env 中 OPENCLAW_GATEWAY_TOKEN 完全一致。

8.3 配置项说明

配置项	说明
`gateway.mode`	`"local"` 表示本地模式
`gateway.auth.token`	Gateway 认证 Token，与 `.env` 一致
`gateway.bind`	`"lan"` 监听所有网卡，允许局域网访问
`agents.defaults.model.primary`	默认 AI 模型，格式 `provider/model`
`models.providers`	自定义模型提供者（如 DeepSeek）

8.4 重启 Gateway 加载配置

cd D:\OpenClaw\openclaw
docker compose restart openclaw-gateway

验证配置生效：

docker logs openclaw-openclaw-gateway-1 --tail 5

成功时会显示：

[gateway] agent model: deepseek/deepseek-chat
[gateway] listening on ws://0.0.0.0:18789 (PID 7)

如果显示 Config invalid，请检查 JSON 格式是否正确（常见错误：多余逗号、缺少引号）。

重要：配置文件中不能包含 OpenClaw 不认识的字段，否则会报配置无效。
只使用认可的顶级字段：gateway、agents、models。

九、模型配置

9.1 关于 DeepSeek 模型

OpenClaw 默认使用 Anthropic Claude 模型。如果没有 Anthropic API Key，发送消息时会报错：

Agent failed: No API key found for provider "anthropic".

第八节的配置已将默认模型改为 DeepSeek。DeepSeek API 兼容 OpenAI 接口，
通过 api: "openai-completions" 配置即可。

9.2 可用的 DeepSeek 模型

模型 ID	名称	说明
`deepseek/deepseek-chat`	DeepSeek V3	通用对话模型，速度快，推荐日常使用
`deepseek/deepseek-reasoner`	DeepSeek R1	推理增强模型，适合复杂问题

9.3 在聊天中切换模型

在 OpenClaw 聊天界面输入：

/model                              # 打开模型选择器
/model list                         # 列出可用模型
/model deepseek/deepseek-chat       # 切换到 DeepSeek V3
/model deepseek/deepseek-reasoner   # 切换到 DeepSeek R1

9.4 使用其他模型提供者（可选）

Anthropic Claude（推荐，效果最好）：

在 .env 中添加 ANTHROPIC_API_KEY=sk-ant-...
配置 "primary": "anthropic/claude-opus-4-6"

OpenAI：

在 .env 中添加 OPENAI_API_KEY=sk-...
配置 "primary": "openai/gpt-5.1-codex"

Ollama（本地模型，免费）：

安装 Ollama（https://ollama.ai）并拉取模型：ollama pull llama3.3
配置 "primary": "ollama/llama3.3"

十、设备配对（Dashboard 访问认证）

10.1 本机访问（最简单）

本机通过 http://localhost:18789 访问属于安全上下文，无需 HTTPS，也无需 Token：

直接在浏览器打开 http://localhost:18789 即可

如果提示需要 Token，使用带 Token 的 URL：

http://localhost:18789/#token=<你的OPENCLAW_GATEWAY_TOKEN>

注意：Token 使用 #token=（URL hash fragment），不是 ?token=。

10.2 局域网访问

从其他设备（如手机、平板）通过局域网访问时，由于不是 localhost，
OpenClaw 要求安全上下文（HTTPS），否则会白屏：

[ws] closed before connect ... reason=control ui requires HTTPS or localhost (secure context)

有两种解决方案：

方案 A：配置 HTTPS（推荐，见第十一节）
方案 B：使用 SSH 隧道或 Tailscale 等工具将远程连接伪装为 localhost

10.3 批准浏览器设备

首次通过浏览器连接后，可能提示 pairing required。需要通过 CLI 批准设备。

列出待批准的设备：

docker compose -f D:\OpenClaw\openclaw\docker-compose.yml run --rm openclaw-cli devices list

如果遇到安全检查错误（SECURITY ERROR: ws:// to non-loopback），
需要临时修改 openclaw.json 中 bind 为 "loopback"，运行 CLI 命令后改回 "lan"：

# 临时改 loopback（不要重启 Gateway）
# 在 openclaw.json 中把 "bind": "lan" 改为 "bind": "loopback"

# 列出设备
docker run --rm --network host -v $env:USERPROFILE\.openclaw:/home/node/.openclaw -e HOME=/home/node -e OPENCLAW_GATEWAY_TOKEN=<Token> openclaw:local node dist/index.js devices list

# 批准设备
docker run --rm --network host -v $env:USERPROFILE\.openclaw:/home/node/.openclaw -e HOME=/home/node -e OPENCLAW_GATEWAY_TOKEN=<Token> openclaw:local node dist/index.js devices approve <requestId>

# 改回 "bind": "lan"，然后重启 Gateway
docker compose restart openclaw-gateway

十一、配置 HTTPS 局域网访问（可选）

如果需要从局域网内的其他设备访问 OpenClaw（如手机、平板），需要配置 HTTPS。

如果只在本机使用（http://localhost:18789），可以跳过此节。

11.1 方案选择

方案	难度	说明
Nginx 反向代理	中等	在 WSL2 中安装 Nginx，与 Server 版方案一致
Caddy 反向代理	简单	Caddy 自动管理证书，配置简洁
mkcert 本地证书	简单	生成本地信任的证书，浏览器不会报警告

11.2 方案一：使用 mkcert + Nginx（推荐）

安装 mkcert：

# 使用 winget 安装
winget install FiloSottile.mkcert

# 安装本地 CA（只需一次）
mkcert -install

生成证书：

# 替换为你电脑的局域网 IP
mkcert -cert-file $env:USERPROFILE\.openclaw\certs\cert.pem -key-file $env:USERPROFILE\.openclaw\certs\key.pem 192.168.1.100 localhost 127.0.0.1

使用 mkcert 生成的证书，同一局域网内安装了该 CA 的设备访问时不会出现浏览器安全警告。

在 WSL2 中配置 Nginx：

# 安装 Nginx
wsl -u root -- bash -c "apt-get update && apt-get install -y nginx"

创建 Nginx 配置（在 WSL 中执行）：

wsl -u root -- bash -c "cat > /etc/nginx/sites-available/openclaw << 'EOF'
server {
    listen 443 ssl;
    server_name _;

    ssl_certificate /mnt/c/Users/你的用户名/.openclaw/certs/cert.pem;
    ssl_certificate_key /mnt/c/Users/你的用户名/.openclaw/certs/key.pem;

    location / {
        proxy_pass http://host.docker.internal:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade \$http_upgrade;
        proxy_set_header Connection \"upgrade\";
        proxy_set_header Host \$host;
        proxy_set_header X-Real-IP \$remote_addr;
        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }
}
EOF
ln -sf /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/openclaw
rm -f /etc/nginx/sites-enabled/default
nginx -t && service nginx restart"

添加防火墙规则：

netsh advfirewall firewall add rule name="OpenClaw HTTPS" dir=in action=allow protocol=tcp localport=443

之后通过 https://你的IP 即可从局域网访问。

11.3 方案二：使用自签名证书（简化版）

如果不想安装 mkcert，可以用 OpenSSL 生成自签名证书（浏览器会提示不安全，需手动信任）：

# 在 WSL 中生成证书
wsl -u root -- bash -c "mkdir -p /mnt/c/Users/你的用户名/.openclaw/certs && openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -keyout /mnt/c/Users/你的用户名/.openclaw/certs/key.pem -out /mnt/c/Users/你的用户名/.openclaw/certs/cert.pem -subj '/CN=openclaw.local' -addext 'subjectAltName=IP:192.168.1.100,DNS:localhost'"

后续 Nginx 配置步骤与方案一相同。

11.4 配置 trustedProxies（使用 Nginx 代理时必须）

如果配置了 Nginx 反向代理，需要在 openclaw.json 中添加 trustedProxies，
否则 Gateway 会忽略代理头并提示警告：

{
  "gateway": {
    "trustedProxies": ["172.18.0.0/16", "172.30.0.0/16", "127.0.0.1"]
  }
}

11.5 自动注入 Token（免带 #token= 访问）

在 Nginx 配置中添加 sub_filter，自动向页面注入 Token，这样无需在 URL 中携带 #token=：

在 Nginx 的 location / 块中添加：

sub_filter_once on;
sub_filter_types text/html;
sub_filter '</head>' '<script>(function(){var K="openclaw.control.settings.v1";var T="<你的Token>";try{var r=localStorage.getItem(K);if(r){var s=JSON.parse(r);if(!s.token){s.token=T;localStorage.setItem(K,JSON.stringify(s))}}else{var proto=location.protocol==="https:"?"wss":"ws";localStorage.setItem(K,JSON.stringify({gatewayUrl:proto+"://"+location.host,token:T,sessionKey:"main",lastActiveSessionKey:"main",theme:"system",chatFocusMode:false,chatShowThinking:true,splitRatio:0.6,navCollapsed:false,navGroupsCollapsed:{}}))}}catch(e){}})();</script></head>';
proxy_set_header Accept-Encoding "";

Accept-Encoding "" 用于禁止后端返回压缩内容，否则 sub_filter 无法替换。

十二、访问信息

访问方式	地址	说明
本机访问（推荐）	`http://localhost:18789`	安全上下文，无需 HTTPS
本机首次带 Token	`http://localhost:18789/#token=<Token>`	首次访问需带 Token
局域网 HTTPS	`https://你的IP`	需配置 HTTPS（第十一节）
局域网 HTTPS 首次	`https://你的IP/#token=<Token>`	首次需带 Token

获取 Dashboard URL（含 Token）：

cd D:\OpenClaw\openclaw
docker compose run --rm openclaw-cli dashboard --no-open

十三、日常管理命令

所有命令在 PowerShell 或 CMD 中执行：

查看日志（实时跟踪）

docker logs -f openclaw-openclaw-gateway-1

查看容器状态

docker ps

重启服务

cd D:\OpenClaw\openclaw
docker compose restart

停止服务

cd D:\OpenClaw\openclaw
docker compose down

启动服务

cd D:\OpenClaw\openclaw
docker compose up -d openclaw-gateway

重新构建镜像（代码更新后）

cd D:\OpenClaw\openclaw
docker build -t openclaw:local -f Dockerfile .
docker compose down
docker compose up -d openclaw-gateway

设置开机自启

Docker Desktop 本身支持开机自启：

Docker Desktop → Settings → General
勾选 ✅ Start Docker Desktop when you sign in to your computer

容器设置为 restart: unless-stopped（docker-compose.yml 中已配置），
Docker Desktop 启动后容器会自动恢复运行。

十四、架构说明

14.1 本机访问架构

Windows 10/11
├── Docker Desktop（自带 WSL2 后端）
│   └── Docker Engine (Linux 容器运行时)
│       └── openclaw-openclaw-gateway-1 (容器)
│           ├── Node.js 22 运行时
│           ├── OpenClaw Gateway (端口 18789)
│           ├── OpenClaw Bridge (端口 18790)
│           └── 配置文件 (/home/node/.openclaw/openclaw.json)
│               ├── Gateway 认证 (token)
│               └── 模型配置 (DeepSeek V3/R1)
├── D:\OpenClaw\openclaw (项目源码)
├── C:\Users\用户名\.openclaw (配置目录，映射到容器)
└── 端口映射: 容器 18789/18790 → localhost:18789/18790

访问路径：

浏览器 → http://localhost:18789 → Docker 容器 → OpenClaw Gateway

14.2 局域网 HTTPS 访问架构（可选）

Windows 10/11
├── Docker Desktop
│   └── Docker Engine → OpenClaw 容器 (18789)
├── WSL2 Ubuntu
│   └── Nginx (HTTPS 反向代理, 443)
│       └── SSL 证书 (mkcert 或自签名)
├── 端口映射: Docker 自动管理
└── 防火墙: 放行 443 端口

访问路径：

局域网设备 → https://电脑IP:443 → WSL2 Nginx → Docker 容器 18789 → OpenClaw

十五、常见问题

Q1: 构建镜像时下载很慢

确认已配置镜像加速（第三节），如果仍然慢，可以尝试更换其他镜像源。

Q2: 端口 18789 被占用

修改 .env 中的端口号：

OPENCLAW_GATEWAY_PORT=28789

然后重启服务。

Q3: Docker Desktop 启动后显示 “WSL 2 installation is incomplete”

重新安装 WSL2 内核：

wsl --update

Q4: 构建时报错 “no space left on device”

Docker 磁盘空间不足，清理未使用的镜像和容器：

docker system prune -a

或参考第四节将数据迁移到其他盘。

Q5: 容器启动后报 “Missing config”

确认 docker-compose.yml 中的 command 已添加 --allow-unconfigured 参数（见 7.3 节）。

Q6: 发消息报 “No API key found for provider anthropic”

默认模型是 Anthropic Claude，需要切换为 DeepSeek 或其他已配置的模型。
检查 openclaw.json 中 agents.defaults.model.primary 是否设置正确（见第八节），
并确保配置文件没有语法错误（JSON 格式严格，不允许尾逗号）。

Q7: 局域网其他设备无法访问

检查 Windows 防火墙是否放行端口：

netsh advfirewall firewall add rule name="OpenClaw Gateway" dir=in action=allow protocol=tcp localport=18789

确认 .env 中 OPENCLAW_GATEWAY_BIND=lan
如果浏览器白屏，说明需要 HTTPS（见第十一节）

Q8: openclaw.json 配置报 “Config invalid”

常见原因：

JSON 中有尾逗号（如 "port": 18789,，最后一个属性后不能有逗号）
包含 OpenClaw 不认识的字段（只允许 gateway、agents、models）
bind 值不合法（只能是 "lan" 或 "loopback"，不能是 "localhost" 或 "127.0.0.1"）

请注意，此篇文章仅供参考！

龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

OpenClaw（小龙虾）AI 智能体・极简一键部署教程

龙虾开发者社区

GPT-6 Spud倒计时×AI格局变局：2026年4月第一周全景扫描

龙虾开发者社区

OpenClaw 完整本地部署安装（接入飞书）

龙虾开发者社区

所有评论(0)

查看更多评论

七号隐身了

@u014754814

已为社区贡献3条内容