OpenClaw 在 WSL 中的完整安装与配置指南

OpenClaw 在 WSL 中的完整安装与配置指南

本文档基于真实安装过程整理，涵盖了从 WSL 环境搭建到 OpenClaw 配置、API Key 设置、常见问题解决的完整流程，适合新手参考。

---

虽然现在一键安装的脚本很多，但还是好奇，自己动手折腾了一下。耗费2个小时最终成功运行，创建了一个CVE漏洞扫描及补丁的任务，完成度还不错。

打败AI的还得是AI，有啥问题deepseek，豆包或者元宝上问问就可以解决。

---

一、前言

OpenClaw 是一款功能强大的开源 AI 代理框架，支持自然语言驱动自动化任务。本文记录在 Windows WSL2 环境中完整安装 OpenClaw 的过程，并解决配置过程中遇到的各种问题。

环境信息

• 操作系统：Windows 11
• WSL 版本：WSL2
• Linux 发行版：Ubuntu 22.04/24.04
• OpenClaw 版本：2026.3.13

---

二、WSL2 环境准备

1. 安装 WSL2

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

# 安装 WSL2 和默认 Ubuntu 发行版
wsl --install

# 安装完成后重启电脑

2. 设置 WSL2 为默认版本

wsl --set-default-version 2

3. 初始化 Ubuntu

重启后 Ubuntu 终端会自动打开，按提示完成：

• 设置用户名（如 yourname）
• 设置密码（输入时不显示星号，正常现象）

4. 更新 Ubuntu 系统

sudo apt update && sudo apt upgrade -y

5. 启用 systemd（可选，但推荐）

编辑 WSL 配置文件：

sudo nano /etc/wsl.conf

添加以下内容：

[boot]
systemd=true

保存后（Ctrl+O，回车，Ctrl+X），在 PowerShell 中执行：

wsl --shutdown

重新打开 Ubuntu 终端使配置生效。

---

三、安装 OpenClaw

1. 安装 Node.js 22.x

# 安装 Node.js 22.x
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
sudo apt install -y nodejs

# 验证安装
node --version   # 应显示 v22.x.x
npm --version    # 应显示 v10.x.x

2. 配置 npm 全局目录（解决权限问题）

# 创建 npm 全局目录
mkdir -p ~/.npm-global

# 设置 npm 使用该目录
npm config set prefix ~/.npm-global

# 配置 PATH 环境变量
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 验证
echo $PATH | grep .npm-global

3. 一键安装 OpenClaw

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

或手动通过 npm 安装：

npm install -g openclaw@latest

4. 验证安装

openclaw --version

---

四、初始化配置

1. 运行初始化向导

openclaw onboard

2. 配置选项建议

配置项	建议选择
理解风险提示	Y
Onboarding mode	QuickStart
模型提供商	Skip for now（稍后配置）
渠道选择	Skip for now
Skills 配置	按需选择，推荐先跳过
Hooks 配置	勾选 session-memory，其他跳过
启动方式	Open the Web UI

3. Gateway 网络配置

配置项	建议值
Gateway port	18789
Gateway bind mode	Loopback (Local only)
Gateway auth	Token
Tailscale exposure	Off

---

五、配置 AI 模型 API

方案一：小米 MiMo 模型（首周限免，通过 OpenRouter）

# 设置小米模型为主模型
openclaw models set openrouter/xiaomi/mimo-v2-pro

# 验证配置
openclaw models status

方案二：OpenCode Zen（公开免费 Key）

编辑配置文件：

nano ~/.openclaw/openclaw.json

添加以下内容：

{
  "models": {
    "providers": {
      "opencode": {
        "baseUrl": "https://opencode.ai/zen/v1",
        "apiKey": "sk-GyX66j2M7ohdzry8z1MVGZxwbzn5SkbWVBYFCw8qiEnb5We64Kt0n5xpek6R3z6l",
        "api": "openai-completions",
        "models": [
          {"id": "minimax-m2.5-free", "name": "minimax-m2.5-free", "input": ["text"]}
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "opencode/minimax-m2.5-free"
      }
    }
  }
}

方案三：Google Gemini（完全免费）

# 获取 API Key：https://aistudio.google.com/apikey
openclaw agents add main --provider gemini --key "你的Gemini密钥"
openclaw config set model.defaults.primary gemini/gemini-2.0-flash-exp

方案四：Groq（免费，速度快）

# 获取 API Key：https://console.groq.com/keys
openclaw agents add main --provider groq --key "你的Groq密钥"
openclaw config set model.defaults.primary groq/llama-3.3-70b-versatile

---

六、配置验证与测试

1. 查看模型状态

openclaw models status

预期输出应包含你配置的模型。

2. 重启 Gateway

openclaw gateway restart

3. 测试对话

方法一：通过 Web UI（推荐）

openclaw dashboard

浏览器会自动打开 http://127.0.0.1:18789/，在聊天框输入消息测试。

方法二：通过命令行

# 正确格式
openclaw agent --agent main --message "你好，请用一句话介绍自己"

# 或使用 chat 命令
openclaw chat --message "你好"

4. 查看日志（如有问题）

# 实时查看日志
openclaw logs --follow

# 查看最近日志
openclaw logs --tail 50

---

七、常见问题与解决方案

问题 1：Config path not found: model.defaults.primary

原因：使用了旧版本的命令格式。

解决 ：使用 openclaw models status 查看当前模型配置，而不是 openclaw config get model.defaults.primary。

问题 2：Pass --to <E.164>, --session-id, or --agent to choose a session

原因 ：openclaw agent 命令未指定会话。

解决 ：使用 openclaw agent --agent main --message "你好" 或 openclaw chat --message "你好"。

问题 3：No API key found for provider "anthropic"

原因：默认使用 Claude 模型但未配置 API Key。

解决：切换到其他免费模型（如小米 MiMo、Gemini 等）。

问题 4：auth-profiles.json: No such file or directory

原因：未配置任何 API Key。

解决 ：运行 openclaw agents add main --provider <provider> --key <key> 添加 API Key。

问题 5：openclaw: command not found

原因：npm 全局路径未加入 PATH。

解决：

export PATH="$HOME/.npm-global/bin:$PATH"
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

问题 6：模型无响应或超时

原因：API Key 无效或免费额度用尽。

解决：尝试切换到其他免费模型，或重新获取 API Key。

---

八、日常使用命令速查

命令	说明
openclaw gateway start	启动 Gateway 服务
openclaw gateway status	查看服务状态
openclaw gateway stop	停止服务
openclaw gateway restart	重启服务
openclaw dashboard	打开 Web UI
openclaw models status	查看当前模型配置
openclaw models set <model>	切换模型
openclaw chat	进入交互式聊天
openclaw logs --follow	实时查看日志
openclaw doctor	健康检查

在 Web UI 中切换模型

在聊天输入框输入：

/model openrouter/xiaomi/mimo-v2-pro

回车后立即生效。

---

九、免费模型资源汇总

模型	获取方式	配置命令
小米 MiMo V2	首周限免	openclaw models set openrouter/xiaomi/mimo-v2-pro
OpenCode Zen	公开 Key	手动配置 config.json
Google Gemini	官网申请	openclaw agents add main --provider gemini --key <key>
Groq	官网申请	openclaw agents add main --provider groq --key <key>
智谱 AutoClaw	官网下载	独立安装包

---

十、总结

通过以上步骤，你可以在 WSL2 中成功安装并配置 OpenClaw。核心要点：

1. 环境准备：WSL2 + Ubuntu + Node.js 22.x
2. 安装：一键安装脚本或 npm 全局安装
3. 初始化 ：运行 openclaw onboard，按推荐选项配置
4. 模型配置：选择一个免费模型并配置 API Key
5. 验证：通过 Web UI 或命令行测试对话

如果遇到问题，查看日志 openclaw logs --follow 定位具体错误，或参考第七部分的常见问题解决方案。

---