OpenClaw Windows 安装详细教程

OpenClaw（前身为 ClawdBot）是一款本地托管的个人 AI 助手系统，可以通过网关控制平面连接到 WhatsApp、Telegram、Discord 等常见通讯软件，并在本地运行各种工作流。

由于 OpenClaw 深度依赖底层系统的进程管理和文件监听，直接在 Windows 原生环境下运行可能会遇到一些限制。因此，官方推荐使用 WSL2（Windows Subsystem for Linux） 或 Docker 来进行安装。以下是详细的安装教程和避坑指南。

安装方式优缺点对比

在开始之前，建议根据你的技术背景和需求选择合适的安装方式：

安装方式	优点	缺点	适用人群
方式一：WSL2 (官方推荐、但不可操作)	官方主推方案；兼容性与稳定性最好；支持完整的 Gateway 守护进程和 CLI 工具。	需要一点 Linux 命令行基础；需要配置 systemd。	首选方案，适合希望长期稳定运行并充分利用 OpenClaw 性能的用户。
方式二：Docker	极致的隔离性，不弄脏宿主机环境；一键卸载；避免 Node.js 版本冲突问题。	资源占用相对较高；使用 CLI 管理容器需要熟悉 Docker 命令。	喜欢环境隔离、有 Docker 使用经验的用户，以及本地已有复杂开发环境的用户。
方式三：原生 Windows	无需开启虚拟化，直接在 PowerShell 运行；安装最快。	极不稳定；后台常驻服务配置困难；非官方重点维护对象，容易出各种奇怪 Bug。	仅限临时测试、不想折腾虚拟化的纯新手小白。

🛠️ 安装前准备 (所有方式通用)

获取大模型 API Key：OpenClaw 本身不包含大语言模型，你需要准备一个模型提供商的 API Key（如 Anthropic Claude、OpenAI、DeepSeek、OpenRouter 等）。
准备通讯软件账号：例如准备一个 Telegram 账号用于绑定机器人。

🚀 方式一：使用 WSL2 安装（官方强推，最稳定）

这是目前在 Windows 上运行 OpenClaw 最正确、最稳定的姿势。

第 1 步：安装 WSL2 与 Ubuntu

以管理员身份打开 PowerShell。
运行以下命令安装 Ubuntu 24.04：

PowerShell
css 复制代码
```
wsl --install -d Ubuntu-24.04
```
安装完成后，如果系统提示，请重启电脑。
重启后打开 Ubuntu 终端，设置你的 Linux 用户名和密码。

第 2 步：开启 Systemd (极其重要)

OpenClaw 的网关守护进程依赖 systemd，而 WSL 默认不开启。如果跳过此步，后续安装守护进程必定失败。

在 Ubuntu 终端中运行：

Bash

bash 复制代码

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

关闭 Ubuntu 终端。在 Windows 的 PowerShell 中彻底关闭 WSL：

PowerShell
arduino 复制代码
```
wsl --shutdown
```
重新打开 Ubuntu 终端，验证 systemd 是否生效：

Bash
css 复制代码
```
systemctl --user status
```
如果没有报错，说明开启成功。

第 3 步：安装 Node.js (严格要求版本)

OpenClaw 明确要求 Node.js 版本必须 >= 22.12.0。

在 Ubuntu 终端中使用 nvm（Node Version Manager）安装：

Bash

bash 复制代码

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
node -v # 确保输出是 v22.12.0 或更高

第 4 步：安装与初始化 OpenClaw

运行官方安装脚本：

Bash
arduino 复制代码
```
curl -fsSL https://openclaw.ai/install.sh | bash
```
运行配置向导（Onboarding），并安装后台守护进程：

Bash
css 复制代码
```
openclaw onboard --install-daemon
```
完成配置：向导会在终端引导你选择模型供应商、输入 API Key，并配置本地控制面板。
验证 Gateway 是否运行：

Bash
lua 复制代码
```
openclaw gateway status
```
打开控制面板：

Bash
复制代码
```
openclaw dashboard
```
这会在你的 Windows 浏览器中打开 http://localhost:18789，你可以在网页端完成 Telegram 等渠道的绑定。

方式二：使用 Docker 安装（隔离性最好）

如果你不想在 Windows 系统里安装 Node 环境，Docker 是非常好的替代方案。

第 1 步：安装 Docker Desktop

前往 Docker 官网下载安装 Docker Desktop。
安装时请确保勾选 "Use WSL 2 instead of Hyper-V" 。
启动 Docker Desktop 并确保它在后台运行。

第 2 步：拉取仓库与配置

打开 Windows 的 PowerShell 或 Git Bash，克隆 OpenClaw 的官方仓库：

PowerShell
bash 复制代码
```
git clone https://github.com/openclaw/openclaw.git
cd openclaw
```
运行 Docker 设置脚本启动服务：

在 Git Bash 或 WSL 中：

Bash
arduino 复制代码
```
./docker-setup.sh
```
或者直接使用 Docker Compose：

PowerShell
复制代码
```
docker compose up -d
```

第 3 步：初始化与管理

由于使用了 Docker，你不能直接在宿主机运行 openclaw 命令。必须通过 Docker 容器来执行：

查看运行状态：

PowerShell
arduino 复制代码
```
docker compose run --rm openclaw-cli status
```
获取控制面板登录 Token 链接：

PowerShell
arduino 复制代码
```
docker compose run --rm openclaw-cli dashboard --no-open
```
复制终端输出的带有 ?token=xxx 的 URL 到浏览器中打开即可进入 Web UI。

方式三：Windows 原生安装（极度不推荐）

仅适合测试，可能会遇到文件锁和路径解析的兼容性问题。

安装步骤

确保在 Windows 上安装了 Node.js 22.12.0 或以上版本。
以管理员身份打开 PowerShell，执行一键安装脚本：

PowerShell
arduino 复制代码
```
iwr -useb https://openclaw.ai/install.ps1 | iex
```
启动引导向导：

PowerShell
复制代码
```
openclaw onboard
```
(注：在原生 Windows 下，建议不要加上 --install-daemon，因为 Windows 服务管理与 Linux 差异很大，极易报错。建议每次使用时手动启动 gateway)。

常见失败问题及解决方法 (Troubleshooting)

1. 报错提示 "Node version not supported" 或类似语法错误

原因：Node.js 版本低于 22.12.0。
解决：严格按照教程，使用 nvm 升级 Node.js 到 22 版本的最新 LTS。

2. WSL2 中执行 `--install-daemon` 失败

原因：WSL 环境下默认没有开启 systemd 系统和服务管理器。
解决：参考【方式一】的【第 2 步】写入 /etc/wsl.conf 文件并执行 wsl --shutdown 重启子系统。

3. Web UI 浏览器配对时卡住，或提示离线 (Offline / Disconnected)

原因：认证凭证（Token/Session）写入冲突，或者 Gateway 进程卡死。
解决：
1. 完全停止 Gateway 进程（CLI 运行 openclaw gateway stop 或在 Docker 中停止容器）。
2. 找到配置文件夹并删除挂起的配对文件：
  - WSL：执行 rm ~/.openclaw/gateway/pending.json
  - Docker：删除挂载卷对应的 pending.json。
3. 重新启动 Gateway：openclaw gateway start。
4. 再次从浏览器尝试配对。

4. 浏览器无法访问 `http://localhost:18789`

原因：Windows Defender 防火墙拦截了端口，或 Docker 容器端口未正确映射。
解决：
- WSL/原生 ：在 Windows 防火墙中允许 Node.js 程序的入站规则，或直接关闭测试环境的防火墙。
- Docker ：检查 docker ps，确保端口 18789 映射正确 (例如 0.0.0.0:18789->18789/tcp)。

5. 诊断工具

无论遇到什么疑难杂症，官方提供了一个自带的体检命令，它可以帮你检查环境依赖和路径权限问题。进入对应的环境（WSL 或 Docker 容器），运行：

Bash

复制代码

openclaw doctor

根据它的红色高亮提示进行修复即可。

OpenClaw Windows 安装详细教程

安装方式优缺点对比

🛠️ 安装前准备 (所有方式通用)

🚀 方式一：使用 WSL2 安装（官方强推，最稳定）

第 1 步：安装 WSL2 与 Ubuntu

第 2 步：开启 Systemd (极其重要)

第 3 步：安装 Node.js (严格要求版本)

第 4 步：安装与初始化 OpenClaw

方式二：使用 Docker 安装（隔离性最好）

第 1 步：安装 Docker Desktop

第 2 步：拉取仓库与配置

第 3 步：初始化与管理

方式三：Windows 原生安装（极度不推荐）

安装步骤

常见失败问题及解决方法 (Troubleshooting)

1. 报错提示 "Node version not supported" 或类似语法错误

2. WSL2 中执行 --install-daemon 失败

3. Web UI 浏览器配对时卡住，或提示离线 (Offline / Disconnected)

4. 浏览器无法访问 http://localhost:18789

5. 诊断工具

2. WSL2 中执行 `--install-daemon` 失败

4. 浏览器无法访问 `http://localhost:18789`