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，执行：

powershell 复制代码

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

# 安装完成后重启电脑

2. 设置 WSL2 为默认版本

powershell 复制代码

wsl --set-default-version 2

3. 初始化 Ubuntu

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

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

4. 更新 Ubuntu 系统

bash 复制代码

sudo apt update && sudo apt upgrade -y

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

编辑 WSL 配置文件：

bash 复制代码

sudo nano /etc/wsl.conf

添加以下内容：

复制代码

[boot]
systemd=true

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

powershell 复制代码

wsl --shutdown

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

三、安装 OpenClaw

1. 安装 Node.js 22.x

bash 复制代码

# 安装 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 全局目录（解决权限问题）

bash 复制代码

# 创建 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

bash 复制代码

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

或手动通过 npm 安装：

bash 复制代码

npm install -g openclaw@latest

4. 验证安装

bash 复制代码

openclaw --version

四、初始化配置

1. 运行初始化向导

bash 复制代码

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）

bash 复制代码

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

# 验证配置
openclaw models status

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

编辑配置文件：

bash 复制代码

nano ~/.openclaw/openclaw.json

添加以下内容：

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（完全免费）

bash 复制代码

# 获取 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（免费，速度快）

bash 复制代码

# 获取 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. 查看模型状态

bash 复制代码

openclaw models status

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

2. 重启 Gateway

bash 复制代码

openclaw gateway restart

3. 测试对话

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

bash 复制代码

openclaw dashboard

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

方法二：通过命令行

bash 复制代码

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

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

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

bash 复制代码

# 实时查看日志
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。

解决：

bash 复制代码

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。核心要点：

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

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

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