OpenClaw Windows 安装详细教程

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

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

安装方式优缺点对比

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

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

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

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

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

第 1 步：安装 WSL2 与 Ubuntu

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

1wsl --install -d Ubuntu-24.04  

3. 安装完成后，如果系统提示，请重启电脑。
4. 重启后打开 Ubuntu 终端，设置你的 Linux 用户名和密码。

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

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

1. 在 Ubuntu 终端中运行：
   Bash

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

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

1wsl --shutdown  

3. 重新打开 Ubuntu 终端，验证 systemd 是否生效：
   Bash

1systemctl --user status  

如果没有报错，说明开启成功。

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

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

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

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

第 4 步：安装与初始化 OpenClaw

1. 运行官方安装脚本：
   Bash

1curl -fsSL https://openclaw.ai/install.sh | bash  

2. 运行配置向导（Onboarding），并安装后台守护进程：
   Bash

1openclaw onboard --install-daemon  

3. 完成配置：向导会在终端引导你选择模型供应商、输入 API Key，并配置本地控制面板。
4. 验证 Gateway 是否运行：
   Bash

1openclaw gateway status  

5. 打开控制面板：
   Bash

1openclaw dashboard  

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

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

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

第 1 步：安装 Docker Desktop

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

第 2 步：拉取仓库与配置

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

1git clone https://github.com/openclaw/openclaw.git  
2cd openclaw  

2. 运行 Docker 设置脚本启动服务：
   在 Git Bash 或 WSL 中：
   Bash

1./docker-setup.sh  

或者直接使用 Docker Compose：
PowerShell

1docker compose up -d  

第 3 步：初始化与管理

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

1. 查看运行状态：
   PowerShell

1docker compose run --rm openclaw-cli status  

2. 获取控制面板登录 Token 链接：
   PowerShell

1docker compose run --rm openclaw-cli dashboard --no-open  

复制终端输出的带有 ?token=xxx 的 URL 到浏览器中打开即可进入 Web UI。

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

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

安装步骤

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

1iwr -useb https://openclaw.ai/install.ps1 | iex  

3. 启动引导向导：
   PowerShell

1openclaw 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

1openclaw doctor
2

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

《OpenClaw Windows 安装详细教程》 是转载文章，点击查看原文。