🦞 OpenClaw Windows 完整部署教程

项目简介

OpenClaw 是一个开源的个人 AI 助手，可以在你自己的设备上运行。它支持多种聊天渠道（WhatsApp、Telegram、Slack、Discord、Signal、iMessage、Microsoft Teams 等），并提供语音交互、浏览器控制、Canvas 画布等强大功能。

– 官网: https://openclaw.ai

– 文档: https://docs.openclaw.ai

– GitHub: https://github.com/openclaw/openclaw

—

系统要求

| 要求 | 说明 |

|——|——|

| 操作系统 | Windows 10/11 (64位) |

| WSL2 | 必需 – OpenClaw 在 Windows 上需要通过 WSL2 运行 |

| Node.js | >= 22.x |

| 内存 | 建议 8GB 以上 |

| 磁盘空间 | 至少 5GB 可用空间 |

> [!IMPORTANT]

> OpenClaw 在 Windows 上强烈推荐通过 WSL2 (Windows Subsystem for Linux 2) 部署运行，这是官方推荐的方式。

—

第一步：安装 WSL2

1.1 快速安装 WSL2

以管理员身份打开 PowerShell，执行：

“`powershell

wsl –install

“`

这会自动安装 WSL2 和默认的 Ubuntu 发行版。

1.2 选择特定 Linux 发行版（可选）

如果你想选择其他发行版：

“`powershell

# 查看可用发行版

wsl –list –online

# 安装指定发行版（推荐 Ubuntu 24.04）

wsl –install -d Ubuntu-24.04

“`

1.3 重启电脑

安装完成后，重启电脑以完成 WSL2 的安装。

1.4 设置 Linux 用户

重启后，WSL 会自动打开并要求你：

1. 设置 Linux 用户名

2. 设置密码

—

第二步：启用 systemd

OpenClaw Gateway 服务需要 systemd 支持。

2.1 配置 WSL 启用 systemd

在 WSL 终端中执行：

“`bash

sudo tee /etc/wsl.conf >/dev/null <<‘EOF’

[boot]

systemd=true

EOF

“`

2.2 重启 WSL

在 Windows PowerShell 中执行：

“`powershell

wsl –shutdown

“`

然后重新打开 WSL 终端。

2.3 验证 systemd 是否启用

“`bash

systemctl –user status

“`

如果看到正常输出，说明 systemd 已启用。

—

第三步：安装 Node.js

在 WSL 终端中安装 Node.js >= 22：

方式一：使用 NodeSource（推荐）

“`bash

# 安装 Node.js 22.x

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash –

sudo apt-get install -y nodejs

“`

方式二：使用 nvm

“`bash

# 安装 nvm

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

# 重新加载 shell 配置

source ~/.bashrc

# 安装 Node.js 22

nvm install 22

nvm use 22

“`

验证安装

“`bash

node –version  # 应显示 v22.x.x

npm –version

“`

—

第四步：安装 pnpm（推荐）

“`bash

npm install -g pnpm

“`

—

第五步：安装 OpenClaw

你有两种安装方式可选：

方式一：通过 npm 全局安装（简单）

“`bash

npm install -g openclaw@latest

# 或使用 pnpm

pnpm add -g openclaw@latest

“`

方式二：从源码安装（开发者推荐）

“`bash

# 克隆仓库

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

cd openclaw

# 安装依赖

pnpm install

# 构建 UI

pnpm ui:build

# 构建项目

pnpm build

“`

—

第六步：运行引导向导

OpenClaw 提供了一个引导向导来帮助你完成初始配置：

“`bash

openclaw onboard –install-daemon

“`

向导会引导你完成：

– 本地/远程 Gateway 配置

– AI 模型认证（支持 Anthropic Claude、OpenAI 等）

– 聊天渠道配置（WhatsApp、Telegram、Discord 等）

– 守护进程安装（使用 systemd 保持后台运行）

> [!TIP]

> 推荐使用 Anthropic Claude 模型（需要 API Key 或 Claude Pro/Max 订阅）以获得最佳效果。

—

第七步：启动 Gateway

7.1 检查 Gateway 状态

“`bash

openclaw gateway status

“`

7.2 手动启动 Gateway（调试模式）

“`bash

openclaw gateway –port 18789 –verbose

“`

Gateway 启动后，可以通过浏览器访问：

“`

http://127.0.0.1:18789/

“`

—

第八步：连接聊天渠道（可选）

WhatsApp

“`bash

openclaw channels login

“`

扫描二维码即可登录 WhatsApp。

Telegram

1. 通过 [@BotFather](https://t.me/BotFather) 创建 Bot 获取 Token

2. 配置到 `~/.openclaw/openclaw.json`：

“`json

{

  “channels”: {

    “telegram”: {

      “botToken”: “你的Bot Token”

    }

  }

}

“`

Discord

1. 在 [Discord Developer Portal](https://discord.com/developers/applications) 创建应用

2. 获取 Bot Token

3. 配置到 `~/.openclaw/openclaw.json`：

“`json

{

  “channels”: {

    “discord”: {

      “token”: “你的Bot Token”

    }

  }

}

“`

—

第九步：验证安装

运行以下命令验证一切正常：

“`bash

# openclaw docker 教程 检查状态

openclaw status

# 健康检查

openclaw health

# 安全审计

openclaw security audit –deep

# 诊断工具

openclaw doctor

“`

—

第十步：测试发送消息

“`bash

# 发送测试消息

openclaw agent –message “Hello from OpenClaw” –thinking high

# 或发送到特定联系人（需要先配置渠道）

openclaw message send –target + –message “Hello from OpenClaw”

“`

—

常用命令速查

| 命令 | 说明 |

|——|——|

| `openclaw onboard` | 运行引导向导 |

| `openclaw gateway status` | 查看 Gateway 状态 |

| `openclaw gateway –verbose` | 启动 Gateway（详细模式） |

| `openclaw status –all` | 查看完整状态 |

| `openclaw health` | 健康检查 |

| `openclaw doctor` | 诊断问题 |

| `openclaw channels login` | 登录 WhatsApp |

| `openclaw configure` | 配置向导 |

| `openclaw update` | 更新 OpenClaw |

—

配置文件位置

| 文件/目录 | 说明 |

|———–|——|

| `~/.openclaw/openclaw.json` | 主配置文件 |

| `~/.openclaw/credentials/` | 凭证存储 |

| `~/.openclaw/workspace/` | Agent 工作空间 |

| `~/.openclaw/agents/` | Agent 配置 |

—

进阶：局域网访问（端口转发）

如果需要从局域网其他设备访问 WSL 中的 Gateway：

在 Windows PowerShell（管理员） 中：

“`powershell

$Distro = “Ubuntu-24.04”

$ListenPort = 18789

$TargetPort = 18789

# 获取 WSL IP

$WslIp = (wsl -d $Distro — hostname -I).Trim().Split(” “)[0]

# 添加端口转发

netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPort connectaddress=$WslIp connectport=$TargetPort

# 添加防火墙规则

New-NetFirewallRule -DisplayName “OpenClaw Gateway” -Direction Inbound -Protocol TCP -LocalPort $ListenPort -Action Allow

“`

—

Docker 部署（可选）

如果你更喜欢使用 Docker，OpenClaw 也支持 Docker Compose 部署：

前置要求

– Docker Desktop for Windows（启用 WSL2 后端）

– Docker Compose v2

使用方法

详细的 Docker 部署指南请参考：https://docs.openclaw.ai/install/docker

—

故障排除

WSL2 无法启动

“`powershell

# 检查 WSL 状态

wsl –status

# 更新 WSL

wsl –update

“`

Node.js 版本过低

确保使用 Node.js >= 22：

“`bash

node –version

“`

Gateway 无法启动

“`bash

# 查看详细日志

openclaw gateway –verbose

# 运行诊断

openclaw doctor

“`

systemd 未启用

确保 `/etc/wsl.conf` 已正确配置，并执行 `wsl –shutdown` 后重新打开 WSL。

—

相关资源

– 📚 [官方文档](https://docs.openclaw.ai)

– 🚀 [快速入门](https://docs.openclaw.ai/start/getting-started)

– 🪟 [Windows (WSL2) 指南](https://docs.openclaw.ai/platforms/windows)

– 🐳 [Docker 部署](https://docs.openclaw.ai/install/docker)

– 💬 [Discord 社区](https://discord.gg/clawd)

– ❓ [FAQ](https://docs.openclaw.ai/start/faq)

—