OpenClaw 在 Windows 上的完整安装指南 - WSL2 配置详解¶

大家好！今天我们来聊聊如何在 Windows 系统上安装 OpenClaw —— 这个可以运行在你自己机器上的开源个人 AI 助手。

如果你厌倦了把数据交给云端 AI 服务，想要一个完全可控、能访问本地文件、能执行实际任务的 AI 助手，那么 OpenClaw 正是你需要的。

什么是 OpenClaw？¶

OpenClaw 是一个自托管的 AI 网关，它可以：

📱 连接多个聊天平台（WhatsApp、Telegram、Discord、微信等）
🤖 对接各种 AI 模型（OpenAI、Claude、Gemini、本地模型等）
📁 访问你的本地文件系统和 API
⚙️ 执行实际任务而不仅仅是聊天
🔒 完全运行在你的机器上，数据不出本地

核心优势： - 自托管 - 运行在你的硬件上，你说了算 - 多通道 - 一个网关同时服务多个聊天应用 - 开源 - MIT 许可证，社区驱动 - 低门槛 - Node.js 22+，5 分钟即可完成安装

系统要求¶

在开始之前，请确认你的系统满足以下要求：

组件	要求	说明
操作系统	Windows 10/11	推荐 Windows 11
Node.js	22 或更高版本	必须！旧版本会失败
内存	最低 4GB	推荐 8GB+
磁盘空间	2GB 可用空间	用于安装和缓存
网络	稳定的互联网连接	用于下载依赖和 API 调用

⚠️ 重要提示¶

Windows 用户必须使用 WSL2！

OpenClaw 在 Windows 上的官方支持路径是通过 WSL2（Windows Subsystem for Linux 2）。虽然理论上可以在原生 Windows 上运行，但会遇到各种兼容性问题。本指南将详细介绍 WSL2 方案。

第一步：安装 WSL2¶

方法一：一键安装（推荐）¶

以管理员身份打开 PowerShell 或命令提示符，运行：

wsl --install

这个命令会： 1. 启用 WSL 功能 2. 启用虚拟机平台功能 3. 安装 Ubuntu 作为默认发行版 4. 要求重启计算机

重启后，Ubuntu 会自动打开，要求你设置用户名和密码。

方法二：手动安装¶

如果一键安装失败，可以手动执行：

# 1. 启用 WSL 功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# 2. 启用虚拟机平台
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 3. 重启计算机
shutdown /r /t 0

# 4. 重启后，设置 WSL2 为默认版本
wsl --set-default-version 2

# 5. 从 Microsoft Store 安装 Ubuntu
# 或者运行：
wsl --install -d Ubuntu

验证 WSL2 安装¶

# 检查 WSL 版本
wsl --version

# 查看已安装的发行版
wsl --list --verbose

# 确保 Ubuntu 使用 WSL2
wsl --set-version Ubuntu 2

预期输出：

  NAME      STATE           VERSION
* Ubuntu    Running         2

第二步：在 WSL2 中安装 Node.js 22¶

OpenClaw 需要 Node.js 22 或更高版本。这是最常见的安装失败原因！

方法一：使用 NodeSource（推荐）¶

在 Ubuntu 终端中运行：

# 1. 更新包列表
sudo apt update

# 2. 安装 curl（如果尚未安装）
sudo apt install -y curl

# 3. 下载并运行 NodeSource 设置脚本
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# 4. 安装 Node.js
sudo apt install -y nodejs

# 5. 验证安装
node --version
npm --version

预期输出：

v22.x.x
10.x.x

方法二：使用 nvm（Node 版本管理器）¶

如果你需要管理多个 Node.js 版本：

# 1. 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 2. 重新加载 shell 配置
source ~/.bashrc

# 3. 安装 Node.js 22
nvm install 22

# 4. 设置为默认版本
nvm use 22
nvm alias default 22

# 5. 验证
node --version

⚠️ 常见错误排查¶

错误 1：node: command not found

# 检查 npm 全局路径
npm prefix -g

# 添加到 PATH（添加到 ~/.bashrc）
export PATH="$(npm prefix -g)/bin:$PATH"
source ~/.bashrc

错误 2：权限问题

# 修复 npm 权限问题
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

第三步：安装 OpenClaw¶

方法一：官方安装脚本（推荐）¶

在 Ubuntu 终端中运行：

# 一键安装
curl -fsSL https://openclaw.sh/install | bash

安装过程会： 1. 下载 OpenClaw CLI 2. 安装到全局 npm 3. 创建配置目录 ~/.openclaw 4. 启动交互式配置向导

方法二：使用 npm 手动安装¶

# 全局安装 OpenClaw
npm install -g openclaw

# 验证安装
openclaw --version

安装后验证¶

# 检查系统健康状态
openclaw doctor

# 查看运行状态
openclaw status

# 打开 Web 控制面板
openclaw dashboard

第四步：完成初始化配置¶

安装完成后，OpenClaw 会自动启动交互式配置向导。如果没有自动启动，可以手动运行：

openclaw onboard --install-daemon

配置步骤详解¶

1. 选择 AI 模型提供商¶

OpenClaw 支持多种 AI 模型：

OpenAI (GPT-4, GPT-3.5)
Anthropic (Claude 3/3.5)
Google (Gemini Pro/Flash)
本地模型 (通过 LM Studio、Ollama 等)

推荐配置： - 追求质量 → Claude 3.5 Sonnet - 追求性价比 → Gemini 2.0 Flash - 隐私优先 → 本地 Qwen/Llama 模型

在配置向导中输入你的 API Key。

2. 配置通信渠道¶

你可以选择如何与 OpenClaw 交互：

Web UI - 浏览器访问（默认开启）
Telegram - 需要 Bot Token
WhatsApp - 需要扫描二维码
Discord - 需要 Bot Token
跳过 - 稍后配置

新手建议： 先使用 Web UI，熟悉后再配置其他渠道。

3. 启用技能（Skills）¶

OpenClaw 的技能系统允许它执行各种任务：

✅ 文件操作 - 读写文件、搜索内容
✅ Web 搜索 - 实时获取网络信息
✅ 代码执行 - 运行 Python/Shell 脚本
✅ 定时任务 - 设置提醒和自动化
✅ 多模态 - 处理图片和文档

建议： 全部启用，可以在配置文件中限制权限。

4. 安装守护进程¶

为了让 OpenClaw 持续运行，建议安装为系统服务：

# 在配置向导中选择"Install Daemon"
# 或者手动运行：
openclaw gateway install
openclaw gateway start

第五步：开始使用 OpenClaw¶

访问 Web 控制面板¶

openclaw dashboard

这会在浏览器中打开 http://127.0.0.1:18789/

主要功能： - 💬 与 AI 助手聊天 - 📊 查看会话历史 - ⚙️ 管理配置和技能 - 📅 设置定时任务 - 📝 查看日志

常用 CLI 命令¶

# 查看状态
openclaw status

# 健康检查
openclaw doctor

# 查看可用模型
openclaw models list

# 搜索记忆
openclaw memory search "关键词"

# 查看文档
openclaw docs

# 重启网关
openclaw gateway restart

# 更新 OpenClaw
openclaw update

第一个任务示例¶

在 Web UI 或聊天中尝试：

帮我创建一个测试文件，内容是"Hello OpenClaw!"

搜索一下今天的技术新闻

读取我桌面上的 readme.txt 文件并总结

常见问题排查¶

问题 1：`openclaw: command not found`¶

原因： npm 全局路径不在 PATH 中

解决方案：

# 检查路径
npm prefix -g

# 添加到 ~/.bashrc
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 或者重新打开终端

问题 2：WSL2 网络问题¶

症状： 无法下载依赖或连接 API

解决方案：

# 在 Windows  PowerShell 中运行
wsl --shutdown

# 重启 WSL
wsl

# 检查 DNS
cat /etc/resolv.conf

# 如果需要使用公共 DNS
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

问题 3：权限错误¶

症状： EACCES: permission denied

解决方案：

# 修复 npm 权限
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) ~/.openclaw

# 或者使用 nvm 避免 sudo

问题 4：网关无法启动¶

检查日志：

openclaw gateway status
openclaw gateway logs

常见原因： - 端口被占用（默认 18789） - 配置文件错误 - API Key 无效

解决方案：

# 检查端口占用
netstat -tlnp | grep 18789

# 重新配置
openclaw onboard

# 重启网关
openclaw gateway restart

问题 5：Node.js 版本过低¶

检查版本：

node --version

升级 Node.js：

# 如果使用 nvm
nvm install 22
nvm use 22
nvm alias default 22

# 如果使用 NodeSource
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

高级配置¶

修改配置文件¶

配置文件位于 ~/.openclaw/openclaw.json

示例配置：

{
  "channels": {
    "webchat": {
      "enabled": true,
      "port": 18789
    },
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN"
    }
  },
  "messages": {
    "groupChat": {
      "mentionPatterns": ["@openclaw"]
    }
  },
  "skills": {
    "allowList": ["file.read", "file.write", "web.search"],
    "denyList": ["exec"]
  }
}

环境变量¶

可以通过环境变量自定义路径：

# 自定义配置目录
export OPENCLAW_HOME=/custom/path

# 自定义状态目录
export OPENCLAW_STATE_DIR=/custom/state

# 自定义配置文件
export OPENCLAW_CONFIG_PATH=/custom/config.json

安全加固¶

生产环境建议：

限制访问来源

{
  "channels": {
    "webchat": {
      "allowFrom": ["192.168.1.0/24"]
    }
  }
}

启用身份验证

{
  "auth": {
    "required": true,
    "token": "your-secure-token"
  }
}

限制技能权限

{
  "skills": {
    "allowList": ["file.read", "web.search"],
    "denyList": ["exec", "file.delete"]
  }
}

性能优化¶

内存优化¶

如果内存有限，可以：

{
  "runtime": {
    "maxMemory": "2GB",
    "sessionLimit": 5
  }
}

启动优化¶

# 禁用不必要的技能
openclaw skills disable unused-skill

# 使用轻量级模型
openclaw model set gemini-2.0-flash

下一步¶

安装完成后，你可以：

📚 阅读官方文档 - docs.openclaw.ai
🔧 探索技能系统 - 查看可用技能和示例
🤖 配置自动化 - 设置定时任务和提醒
🔌 连接更多渠道 - 添加 Telegram、WhatsApp 等
👥 加入社区 - Discord 社区

总结¶

在 Windows 上安装 OpenClaw 的完整流程：

✅ 安装 WSL2 和 Ubuntu
✅ 安装 Node.js 22+
✅ 运行 OpenClaw 安装脚本
✅ 完成初始化配置
✅ 开始使用！

整个过程大约需要 10-15 分钟。虽然步骤看起来多，但大部分是一次性配置。

关键要点： - ⚠️ 必须使用 WSL2，不要尝试原生 Windows - ⚠️ Node.js 必须是 22 或更高版本 - ⚠️ 安装后运行 openclaw doctor 检查状态 - ✅ 建议安装守护进程实现开机自启

OpenClaw 是一个强大的工具，一旦配置完成，它会成为你的 24 小时 AI 助手，帮助你处理各种任务。无论是文件管理、信息搜索还是自动化工作流，它都能胜任。

如果你在安装过程中遇到问题，欢迎查看官方文档或在评论区留言！

下期预告： 我们将深入探讨 OpenClaw 的技能系统，教你如何让 AI 助手自动执行复杂的工作流。敬请期待！

OpenClaw 在 Windows 上的完整安装指南 - WSL2 配置详解¶

什么是 OpenClaw？¶

系统要求¶

⚠️ 重要提示¶

第一步：安装 WSL2¶

方法一：一键安装（推荐）¶

方法二：手动安装¶

验证 WSL2 安装¶

第二步：在 WSL2 中安装 Node.js 22¶

方法一：使用 NodeSource（推荐）¶

方法二：使用 nvm（Node 版本管理器）¶

⚠️ 常见错误排查¶

第三步：安装 OpenClaw¶

方法一：官方安装脚本（推荐）¶

方法二：使用 npm 手动安装¶

安装后验证¶

第四步：完成初始化配置¶

配置步骤详解¶

1. 选择 AI 模型提供商¶

2. 配置通信渠道¶

3. 启用技能（Skills）¶

4. 安装守护进程¶

第五步：开始使用 OpenClaw¶

访问 Web 控制面板¶

常用 CLI 命令¶

第一个任务示例¶

常见问题排查¶

问题 1：openclaw: command not found¶

问题 2：WSL2 网络问题¶

问题 3：权限错误¶

问题 4：网关无法启动¶

问题 5：Node.js 版本过低¶

高级配置¶

修改配置文件¶

环境变量¶

安全加固¶

性能优化¶

内存优化¶

启动优化¶

下一步¶

总结¶

问题 1：`openclaw: command not found`¶