适用人群：想在 Windows 电脑上通过 WSL2（Windows Subsystem for Linux）部署并使用 OpenClaw 的用户。
前置知识：基本的电脑操作，能跟着教程复制粘贴命令即可。
涉及内容：WSL2 环境配置、OpenClaw 安装、DeepSeek API 接入、Gateway 启动与使用、常见网络问题排查。

一、什么是 OpenClaw？为什么选择 WSL2 方案？

OpenClaw（俗称“小龙虾”或“大龙虾”）是一款开源、本地优先的个人 AI 助手系统。与普通聊天机器人不同，它的核心优势在于强执行能力——能通过自然语言指令自动拆解任务，帮你处理邮件、管理文件，甚至调用系统工具

官方推荐在 Windows 上通过 WSL2（Windows Subsystem for Linux） 运行 OpenClaw，原因如下

• 环境隔离：WSL2 提供完整的 Linux 内核，避免 Node.js 等依赖与 Windows 产生冲突。

• 生态兼容：既能享受 Linux 生态，又能方便地访问 Windows 文件系统（位于 /mnt/c/）。

• 官方推荐：OpenClaw 的 CLI 和 Gateway 在 Linux 环境下兼容性最好

二、环境准备：安装 WSL2 与 Ubuntu

2.1 系统要求

• 操作系统：Windows 10 版本 2004 及以上，或 Windows 11

• 内存：建议 8GB 以上

• 虚拟化：确保 BIOS 中已开启 Intel VT-x 或 AMD-V

2.2 启用 WSL 相关功能

1. 按 Win + S 搜索“Windows 功能”，打开“启用或关闭 Windows 功能”。

2. 勾选以下三项：

   • ✅ 虚拟机平台

   • ✅ Windows 虚拟机监控程序平台

   • ✅ 适用于 Linux 的 Windows 子系统

3. 点击“确定”，重启电脑。

2.3 安装 WSL2 与 Ubuntu

重启后，以管理员身份打开 PowerShell 或 Windows 终端，执行

wsl --install

此命令会自动启用 WSL2 并默认安装 Ubuntu 最新 LTS 版。

如果遇到网络问题，可以指定安装 Ubuntu 22.04 或 24.04：

wsl --install -d Ubuntu-24.04

安装完成后，再次重启电脑。

2.4 首次启动 Ubuntu 配置

1. 在开始菜单中找到并启动 Ubuntu。

2. 等待初始化完成，根据提示创建 UNIX 用户名和密码（不要使用中文，建议记住你的账号密码）。

3. 验证安装是否成功：

wsl -l -v

如果 VERSION 列为 2，说明安装成功

2.5 启用 systemd（关键步骤）

OpenClaw 的 Gateway 服务需要 systemd 支持。

在 Ubuntu 终端中执行

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

然后回到 Windows PowerShell，执行以下命令重启 WSL：

wsl --shutdown

重新打开 Ubuntu 终端，验证 systemd 是否正常

systemctl --user status

如果看到服务列表输出，说明配置成功。

2.6 配置国内镜像源（加快下载速度）

在 Ubuntu 终端中执行

# 备份原始源
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak

# 替换为清华镜像源（Ubuntu 22.04 适用）
sudo tee /etc/apt/sources.list << 'EOF'
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-updates main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-backports main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-security main restricted universe multiverse
EOF

# 更新软件包
sudo apt update && sudo apt upgrade -y

注意：如果你安装的是 Ubuntu 24.04，请将上面的 jammy 替换为 noble。

三、安装 OpenClaw

OpenClaw 基于 Node.js 构建，官方推荐使用 Node.js 22 LTS 或更高版本。

在 Ubuntu 终端中执行：

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

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

3.2 安装 OpenClaw

OpenClaw 官方提供了便捷的一键安装脚本。

在 Ubuntu 终端中执行：

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

安装脚本会自动检测并安装所需依赖。

3.3 验证安装

安装完成后，验证 OpenClaw 是否安装成功：

openclaw --version

如果显示版本号，说明安装成功。

---

四、配置 DeepSeek API（或其他大模型）

OpenClaw 本身不提供大模型能力，需要配置 API 才能工作。

4.1 获取 DeepSeek API Key

1. 访问 DeepSeek 开放平台。

2. 注册账号并登录。

3. 进入“API Keys”页面，创建新的密钥。

4. 复制并保存生成的 API Key（以 sk- 开头）。

4.2 配置 OpenClaw 使用 DeepSeek

有两种方式可以配置：

方式一：通过 openclaw onboard 向导（推荐）

openclaw onboard --auth-choice deepseek-api-key

按照提示输入你的 DeepSeek API Key 即可。

方式二：手动修改配置文件
编辑 ~/.openclaw/openclaw.json 文件：

{
  "models": {
    "mode": "merge",
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com",
        "apiKey": "你的DeepSeek API Key",
        "api": "openai-completions",
        "models": [
          { "id": "deepseek-chat", "name": "DeepSeek Chat" },
          { "id": "deepseek-reasoner", "name": "DeepSeek Reasoner" },
          { "id": "deepseek-v4-pro", "name": "DeepSeek V4 Pro" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "models": {
        "deepseek/deepseek-chat": {},
        "deepseek/deepseek-reasoner": {},
        "deepseek/deepseek-v4-pro": {}
      }
    }
  }
}

4.3 验证模型配置

openclaw models list | grep deepseek

如果能看到 DeepSeek 相关模型，说明配置成功。

五、启动 Gateway 服务

Gateway 是 OpenClaw 的核心后台服务。

5.1 运行配置向导并安装服务

openclaw onboard --install-daemon

按照交互式提示完成配置。

关键选项建议：

• Gateway mode：选择 local（本地模式）

• Memory search：如果未配置 OpenAI API Key，选择 No

• Skills：选择 Yes 禁用不可用的技能

• Hooks：建议至少选择 session-memory

5.2 启动 Gateway

openclaw gateway start

5.3 检查 Gateway 状态

openclaw gateway status

如果显示 Runtime: running 和 Connectivity probe: ok，说明 Gateway 正常运行

六、使用 OpenClaw

6.1 启动 TUI（在Ubuntu终端交互界面）

openclaw tui

进入 TUI 后，你可以像聊天一样输入指令，OpenClaw 会执行相应的任务。

6.2 启动 Web 控制台（Dashboard）

openclaw dashboard

浏览器会自动打开 http://127.0.0.1:18789/，提供图形化操作界面。

6.3 常用命令

命令	作用
openclaw gateway status	查看 Gateway 运行状态
openclaw gateway restart	重启 Gateway
openclaw gateway stop	停止 Gateway
openclaw tui	打开终端交互界面
openclaw dashboard	打开 Web 控制台
openclaw models list	查看已配置的模型列表
openclaw config set <key> <value>	修改配置

七、常见问题与解决方案

7.1 网络问题：WSL2 无法访问外网

现象：curl 命令超时，无法访问百度或 DeepSeek API。

原因：WSL2 网络栈卡死，或 VPN/代理与 WSL2 冲突。

解决方案：

1. 关闭所有 VPN 和代理软件。

2. 以管理员身份打开 PowerShell，依次执行

3. wsl --shutdown
   netsh winsock reset
   netsh int ip reset all
   ipconfig /flushdns

4. 重启电脑。

5. 如果问题依旧，创建 C:\Users\你的用户名\.wslconfig 文件，内容如下：

6. [wsl2]
   networkingMode=mirrored
   dnsTunneling=true
   firewall=true
   autoProxy=true

保存后，在 PowerShell 中执行 wsl --shutdown，重启 WSL2。

7.2 Gateway 无法启动（端口被占用）

现象：Gateway 启动失败，提示端口 18789 被占用。

解决方案

# 查找占用端口的进程
sudo lsof -i :18789
# 或
netstat -ano | findstr 18789

终止占用进程后，重新启动 Gateway。

7.3 TUI 显示 connected | error

现象：TUI 能连接 Gateway，但发送消息后报错。

可能原因：

• DeepSeek API Key 无效或余额不足

• 网络无法访问 DeepSeek API

• 模型配置错误

排查步骤：

1. 检查 DeepSeek 账户余额。

2. 测试网络连通性：curl -I https://api.deepseek.com

3. 检查模型配置：openclaw models list

4. 查看日志：openclaw logs 50

7.4 命令找不到（openclaw: command not found）

原因：环境变量 PATH 未正确配置。

解决方案：

# 查找 openclaw 安装位置
which openclaw
# 或重新安装
npm install -g openclaw

7.5 配置文件缺失

现象：Gateway 启动失败，提示 Config (cli): ~/.openclaw/openclaw.json (missing)。

解决方案：重新运行配置向导：

openclaw onboard

八、补充说明

8.1 关于 VPN 的影响

使用 VPN 时，WSL2 的网络可能无法自动继承 Windows 的代理设置。如果需要通过代理访问外网，可以在 WSL2 中手动设置：

export http_proxy="http://宿主机IP:代理端口"
export https_proxy="http://宿主机IP:代理端口"

宿主机 IP 可通过 cat /etc/resolv.conf 中的 nameserver 获取。

8.2 关于“小龙虾”名称的由来

OpenClaw 的社区昵称“小龙虾”或“大龙虾”源于其图标和项目名称的谐音。

8.3 进一步学习资源

• OpenClaw 官方文档

• OpenClaw 中文安装与使用手册

• OpenClaw 入门指南

---

以上是 OpenClaw 在 Windows WSL2 环境下的完整安装与配置教程。如果你在使用过程中遇到教程中未覆盖的问题，欢迎随时交流。第二篇关于 Claude Code (CC) 的教程将单独整理，涵盖安装、DeepSeek API 接入、代理配置以及禁令相关的注意事项。