OpenClaw Windows 安装详细教程

超低空
2 阅读6分钟

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。仅限临时测试、不想折腾虚拟化的纯新手小白。

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

  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

    wsl --install -d Ubuntu-24.04

  3. 安装完成后，如果系统提示，请重启电脑。

  4. 重启后打开 Ubuntu 终端，设置你的 Linux 用户名和密码。

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

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

  1. 在 Ubuntu 终端中运行：

    Bash

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

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

    PowerShell

    wsl --shutdown

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

    Bash

    systemctl --user status

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

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

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

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

    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

  1. 运行官方安装脚本：

    Bash

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

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

    Bash

    openclaw onboard --install-daemon

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

  4. 验证 Gateway 是否运行：

    Bash

    openclaw gateway status

  5. 打开控制面板：

    Bash

    openclaw 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

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

  2. 运行 Docker 设置脚本启动服务：

    在 Git Bash 或 WSL 中：

    Bash

    ./docker-setup.sh

    或者直接使用 Docker Compose：

    PowerShell

    docker compose up -d

第 3 步：初始化与管理

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

  1. 查看运行状态：

    PowerShell

    docker compose run --rm openclaw-cli status

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

    PowerShell

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

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

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

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

安装步骤

  1. 确保在 Windows 上安装了 Node.js 22.12.0 或以上版本。

  2. 以管理员身份打开 PowerShell，执行一键安装脚本：

    PowerShell

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

  3. 启动引导向导：

    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

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

avatar
文章
阅读
粉丝