Win11 安装 OpenClaw 全程详细教程（WSL2 小白版）：依赖齐全 + 环境变量 + 数据放系统盘外（D 盘）

依赖清单（一次装齐）

你需要：

– Windows 11
– CPU 虚拟化已开启（Intel VT-x / AMD-V）
– WSL2 + Ubuntu（推荐 Ubuntu-24.04）
– 在 WSL(Ubuntu) 内：
– systemd（必须，用于安装 OpenClaw Gateway 后台服务）
– Node.js **>= 22**
– git / curl / 构建工具（建议装齐避免踩坑）

## 1. 安装 WSL2 + Ubuntu（Windows 侧）

管理员 PowerShell 执行（可一键复制）：

wsl --install

想指定 Ubuntu 版本（推荐 24.04）：

wsl --list --online
wsl --install -d Ubuntu-24.04

按提示重启，打开 Ubuntu 完成首次初始化（设置 Linux 用户名/密码）。

## 2. 把 WSL 发行版整体迁移到 D 盘（实现“Linux 系统盘外”）

### 2.1 查看发行版名称

PowerShell：

wsl -l -v

你可能看到 `Ubuntu` 或 `Ubuntu-24.04`。下面以 `Ubuntu-24.04` 举例，请按你机器实际名称替换。

### 2.2 关闭 WSL

wsl --shutdown

### 2.3 导出发行版到 D 盘

mkdir D:WSL
wsl --export Ubuntu-24.04 D:WSLUbuntu-24.04.tar

### 2.4 注销旧发行版（会删除旧那份，但你已导出）

wsl --unregister Ubuntu-24.04

### 2.5 导入到 D 盘（并指定 WSL2）

mkdir D:WSLUbuntu-24.04
wsl --import Ubuntu-24.04 D:WSLUbuntu-24.04 D:WSLUbuntu-24.04.tar --version 2

### 2.6 再确认是 WSL2

wsl -l -v

确保 `VERSION` 是 `2`。

## 3. 进入 Ubuntu：确认 D 盘映射可用

在 Ubuntu 终端执行：

ls -la /mnt/d

如果你没有 D 盘，那可能是 `/mnt/e`、`/mnt/f`，后面的路径请整体替换。

## 4. 在 WSL 启用 systemd（OpenClaw 安装服务必需）

Ubuntu 里执行（可一键复制）：

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

回到 Windows PowerShell：

wsl --shutdown

再打开 Ubuntu，验证：

systemctl --user status

能输出状态信息就说明 systemd 正常。

## 5. 安装必备依赖（git/curl/构建工具等）

Ubuntu 执行：

sudo apt update
sudo apt install -y 
  ca-certificates curl gnupg lsb-release 
  git unzip zip 
  build-essential python3 make g++ 
  pkg-config

## 6. 安装 Node.js 22+（OpenClaw 必需）

推荐 NodeSource（稳定、好排错）。Ubuntu 执行：

### 6.1 添加源

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

### 6.2 安装 Node

sudo apt install -y nodejs

### 6.3 验证版本（必须 >= 22）

node -v
npm -v

## 7. 规划：把 OpenClaw 所有数据放到 D 盘（目录结构建议）

建议统一放在：`/mnt/d/openclaw/` 下：

– 状态目录（配置/凭证/会话/日志/缓存）：`/mnt/d/openclaw/state`
– 工作区（你的项目/技能/文件等）：`/mnt/d/openclaw/workspace`
– 备份（可选）：`/mnt/d/openclaw/backup`

创建目录：

mkdir -p /mnt/d/openclaw/state
mkdir -p /mnt/d/openclaw/workspace
mkdir -p /mnt/d/openclaw/backup

## 8. 设置关键环境变量（永久生效）

OpenClaw 的关键路径由环境变量控制。把它写进 `~/.bashrc`（可一键复制）：

cat >> ~/.bashrc <<'EOF'

# ===== OpenClaw (WSL2) =====
# 状态目录：配置/凭证/会话/日志/缓存
export OPENCLAW_STATE_DIR=/mnt/d/openclaw/state
# 配置文件路径（推荐放在 state 目录下）
export OPENCLAW_CONFIG_PATH=/mnt/d/openclaw/state/openclaw.json
# 你的工作区（项目/文件/技能等）
export OPENCLAW_WORKSPACE_DIR=/mnt/d/openclaw/workspace
EOF

让其立即生效：

source ~/.bashrc

验证：

echo "$OPENCLAW_STATE_DIR"
echo "$OPENCLAW_CONFIG_PATH"
echo "$OPENCLAW_WORKSPACE_DIR"

## 9. 处理 PATH（避免“openclaw 不是命令”）

很多新手卡在安装完成但找不到命令，原因是 npm 全局 bin 不在 PATH。

执行：

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

## 10. 安装 OpenClaw（推荐：官方 install.sh）

Ubuntu 执行（可一键复制）：

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

验证：

openclaw --version

## 11. 第一次初始化：运行向导并安装后台服务（daemon）

Ubuntu 执行：

openclaw onboard --install-daemon

向导建议（小白优先“先跑起来”）：

– Gateway：选本机（local）
– 运行时：选 **Node**（不建议 Bun）
– 渠道：可以先跳过（后面随时加），先用 Dashboard 也能聊天
– 模型认证：按你现在能用的方式（OAuth 或 API Key）配置

完成后建议检查：

openclaw gateway status
openclaw status
openclaw health

## 12. 把敏感信息放进 `$OPENCLAW_STATE_DIR/.env`（推荐做法）

OpenClaw 会读取（且不覆盖已有值）：

– 当前目录 `.env`
– **全局 `.env`：`$OPENCLAW_STATE_DIR/.env`**（推荐放密钥）
– 配置文件 `env` 块（仅在缺失时补齐）

创建/编辑：

nano "$OPENCLAW_STATE_DIR/.env"

示例（按你实际填）：

OPENAI_API_KEY=sk-xxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxx
OPENROUTER_API_KEY=sk-or-xxxxxxxx

设置权限（建议）：

chmod 600 "$OPENCLAW_STATE_DIR/.env"

改完重启 Gateway：

openclaw gateway restart

## 13. 确保工作区也在 D 盘（配置建议）

你已经设置了 `OPENCLAW_WORKSPACE_DIR`，但为了“强约束”，建议在配置文件里也指定主智能体工作区。

编辑配置：

nano "$OPENCLAW_CONFIG_PATH"

加入/修改（示例，JSON5 允许注释/尾逗号）：

{
  routing: {
    agents: {
      main: {
        workspace: "/mnt/d/openclaw/workspace",
      },
    },
  },
}

保存后重启：

openclaw gateway restart

## 14. 打开 Dashboard（最简单的“我能用了”验证）

默认本机访问：

– `http://127.0.0.1:18789/`

如果向导生成了 token，页面会提示你输入 token（按提示粘贴即可）。

## 15. 常用运维命令（记住这些就够用）

查看状态：

openclaw gateway status
openclaw status
openclaw health

启动/停止/重启：

openclaw gateway start
openclaw gateway stop
openclaw gateway restart

前台调试（出问题时非常有用）：

openclaw gateway --port 18789 --verbose

## 16. 常见问题排错（小白速查）

### 16.1 `openclaw: command not found`

基本就是 PATH 没生效：

source ~/.bashrc
openclaw --version

必要时确保 npm 全局 bin 在 PATH：

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

### 16.2 `openclaw health` 提示未配置认证

把 API Key 写进：

nano "$OPENCLAW_STATE_DIR/.env"

然后：

openclaw gateway restart
openclaw health

### 16.3 关掉终端后服务停了

你如果是前台运行（`openclaw gateway –verbose`）当然会停。

正确做法：用 `openclaw onboard –install-daemon` 安装后台服务，并用：

openclaw gateway status

确认它在跑。

### 16.4 端口被占用

先尝试：

openclaw gateway restart

如果仍占用，建议用前台 `–verbose` 启动看具体错误。

## 17. 最终检查清单（照着打勾就能一次成功）

– [ ] Windows 11 虚拟化已启用
– [ ] WSL2 已安装：`wsl -l -v` 显示 Ubuntu Version 2
– [ ] （推荐）WSL 发行版已迁移到 D 盘（export/import 完成）
– [ ] WSL systemd 已启用：`systemctl –user status` 正常
– [ ] Node >= 22：`node -v`
– [ ] OpenClaw 已安装：`openclaw –version`
– [ ] 关键路径指向 D 盘：
– [ ] `echo $OPENCLAW_STATE_DIR` → `/mnt/d/openclaw/state`
– [ ] `echo $OPENCLAW_CONFIG_PATH` → `/mnt/d/openclaw/state/openclaw.json`
– [ ] `echo $OPENCLAW_WORKSPACE_DIR` → `/mnt/d/openclaw/workspace`
– [ ] 已完成向导并安装 daemon：`openclaw onboard –install-daemon`
– [ ] Gateway 正常：`openclaw gateway status`
– [ ] Dashboard 能打开：`http://127.0.0.1:18789/`

## 结语

按本文走 WSL2 这条路线，你在 Windows 上会获得“接近原生 Linux”的一致运行环境，OpenClaw 的兼容性和稳定性最好。