PigCloud Doc

Appearance

OpenClaw 首次安装教程（Windows · WSL2） ​

本教程面向从未安装过 OpenClaw 的 Windows 用户，采用 WSL2（Windows Subsystem for Linux） 方式完成安装。WSL2 提供真实的 Linux 环境，是 Windows 下运行 OpenClaw 最稳定的方式。

前置条件

  1. Windows 10 版本 2004（Build 19041）或更高 / Windows 11
  2. 前往 PigCloud 控制台 注册并获取 API Key（分组选择 Claude 8 或 Claude 5）

1. 启用 WSL2 ​

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

powershell
wsl --install

此命令会自动启用 WSL 功能并安装默认的 Ubuntu 发行版。安装完成后根据提示重启电脑。

如果已安装过 WSL 但版本为 WSL1，可执行以下命令升级：

powershell
wsl --set-default-version 2

重启后，Ubuntu 会自动打开并要求你设置一个 Linux 用户名和密码（此密码与 Windows 密码无关，请记牢）。

2. 在 WSL2 中安装 Node.js ≥ 22 ​

OpenClaw 对 Node.js 版本要求比其他工具更高，需要 v22+。推荐使用 nvm 管理 Node 版本。

打开 Ubuntu 终端，依次执行：

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

# 让 nvm 在当前会话生效
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# 安装 Node.js 22
nvm install 22
nvm use 22
nvm alias default 22

# 验证版本
node --version  # 应显示 v22.x.x

3. 安装 OpenClaw ​

bash
npm install -g openclaw@latest

4. 运行初始化向导 ​

bash
openclaw onboard --install-daemon

5. 按向导提示逐步操作 ​

在终端的交互式向导中，请按照以下选项进行配置：

  • 确认安装：回车选择 yes
  • Provider： 选择 Custom Provider
  • Base URL： 输入 https://pigcloud.xyz
  • API Key： 填入从 令牌页面 复制的 Key
  • API Format： 选择 Anthropic-compatible
  • Model Name： 填写 claude-sonnet-4-6 或 claude-opus-4-6-thinking
  • Next step： 选择 Open the Web UI

⚠️ Base URL 注意： 使用 anthropic-messages API 时，Base URL 请严格填写 https://pigcloud.xyz，绝对不要加 /v1 后缀！

6. 优化配置参数 ​

向导完成后，为了获得最佳的代码生成体验，请编辑 ~/.openclaw/openclaw.json，将默认参数提升：

bash
nano ~/.openclaw/openclaw.json

修改以下两个字段：

  • contextWindow：从 4096 修改为 200000
  • maxTokens：从 4096 修改为 8192

👉 完整的配置文件模板可直接在 OpenClaw 配置模板（一键复制） 页面获取。

7. 在 Windows 文件资源管理器中访问 WSL 文件 ​

你可以在 Windows 文件资源管理器地址栏输入以下路径，直接访问 WSL 内的项目文件：

\\wsl$\Ubuntu\home\你的用户名

也可以在 Ubuntu 终端中执行 explorer.exe . 直接打开当前目录。

8. 可用模型 ​

推荐在 OpenClaw 中使用以下模型：

  • claude-sonnet-4-6
  • claude-sonnet-4-6-thinking
  • claude-opus-4-6
  • claude-opus-4-6-thinking

9. 开始使用 ​

配置完成后，OpenClaw 会自动打开 Web UI 界面。建议先发送一条简单的问候语（如"你好"）测试连通性，确认正常返回后再开始进行复杂的代码任务。

常见问题与异常处理 (FAQ) ​

WSL2 安装相关 ​

问题解决方法
wsl --install 报错"虚拟化未启用"进入 BIOS 开启 Intel VT-x 或 AMD-V 虚拟化选项
Ubuntu 打开后卡在黑屏等待首次初始化完成，可能需要 1～3 分钟
忘记了设置的 Linux 密码以管理员身份运行 wsl -u root，执行 passwd 你的用户名 重置

OpenClaw 使用相关 ​

  1. 检查 Base URL： 必须是 https://pigcloud.xyz，不能包含 /v1
  2. 检查参数： contextWindow 是否已设为 200000，maxTokens 是否已设为 8192
  3. 账户余额： 前往 充值页面 确认账户有充足的额度
  4. nvm 命令找不到： 重新打开终端，或手动执行 source ~/.bashrc / source ~/.zshrc

💡 提示: 如果遇到问题，请先查看 常见问题 文档。如果依然无法解决，请携带完整报错截图前往首页，公告内添加客服联系方式，添加客服询问解决。

Released under the MIT License.

Copyright © 2024-present PigCloud