一、什么是OpenClaw

OpenClaw 是开源本地 AI Agent 网关框架，提供 Agent 调度、工具调用、Checkpointer 状态持久化、多模型统一接入能力。

• 支持对接 Ollama 本地模型、阿里云百炼、OpenAI 兼容接口；
• 自带 Checkpointer 存档，支持会话记忆、断点续跑、人工介入 Human‑in‑the‑Loop；
• 提供统一网关18789端口，管理 Agent 生命周期、技能插件。

为什么不用 Windows 原生部署：Windows 环境会出现权限异常、文件锁、守护进程无法自启，官方优先推荐 WSL2 Ubuntu‑22.04 环境部署CSDN

二、为什么选择 WSL2 部署 OpenClaw

1. 兼容性：OpenClaw 底层基于 Node.js+Linux 生态，Windows 原生存在大量权限、文件系统 bug，WSL2 提供完整 Linux 运行环境，规避绝大多数 Windows 专属坑点。
2. 性能：WSL2 原生虚拟化，网络、IO 损耗极低，可无缝对接 Windows 宿主机 Ollama。
3. 稳定性：支持 systemd 守护进程，网关可后台常驻，重启子系统自动拉起服务。
4. 生态打通：WSL2 内部可以调用宿主机端口，Ollama 跑在 Windows，WSL2 内 OpenClaw 可以直接访问127.0.0.1:11434。

❗重要：所有 OpenClaw 操作全部在 WSL2 Ubuntu 终端执行，不要在 Windows CMD/PowerShell 执行 openclaw 命令。配置文件必须放在 WSL 家目录~/，禁止放在/mnt/cWindows 挂载目录，会出现权限报错 EACCESCSDN。

三、什么场景适合该部署方案

✅适用场景

1. Windows 电脑本地搭建 AI Agent，不想上 Linux 物理机；
2. 需要本地 Ollama 私有化大模型，同时兼容云端 API（阿里云百炼）；
3. 需要 Checkpointer 会话持久化、断点续跑、工具调用能力；
4. 开发调试 Agent 流程，做时间旅行调试、人工干预。

❌不适合场景

1. 生产公网对外提供服务（建议直接 Linux 服务器）；
2. Windows 版本低于 Win11 22H2，WSL 版本老旧。

四、WSL2 完整部署步骤

4.1 前置环境准备

管理员 PowerShell 执行，安装 WSL2 Ubuntu‑22.04

wsl --install -d Ubuntu-22.04

执行完成重启 Windows，打开 Ubuntu 终端，设置用户名密码。

确认 WSL 版本：

wsl --list --verbose

VERSION 列必须为2。

进入 WSL Ubuntu 终端，开启 WSL systemd（OpenClaw 守护进程强依赖）

sudo nano /etc/wsl.conf

写入配置：

[boot]
systemd=true

保存退出ctrl + O 回车，ctrl + X。

PowerShell 关闭 WSL，使配置生效

wsl --shutdown

重新打开 Ubuntu 终端，验证 systemd 生效

systemctl --user status

4.2 WSL 内部安装 Node.js22（硬性要求 Node>=22.x）

# 更新源
sudo apt update && sudo apt upgrade -y
sudo apt install curl git -y

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

# 校验版本，必须 >=22
node -v
npm -v

4.3 全局安装 OpenClaw CLI

npm install -g openclaw@latest

# 校验安装
openclaw --version

4.4 交互式初始化引导 onboard

openclaw onboard --flow quickstart

交互式向导关键选项：

1. 网关模式：local（本地模式），必须选 local，否则网关启动报错；
2. 模型提供商：选择自己想用的
3. api_key:记得获取之后根据提示输入正确的位置（后续可以通过配置做更换所以不用纠结）
4. 然后就是登录验证记住自己的密码或token

剩余的没特殊需求一路回车就行，最好是仔细看一下

校验配置文件是否生成

ls ~/.openclaw/

4.5 修改 openclaw.json 配置文件

nano ~/.openclaw/openclaw.json

方案 A：对接云端模型

#以云百炼qwen-plus为例
{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "host":"127.0.0.1"
  },
  "agents":{
    "defaults":{
      "model":"qwen-plus",
      "temperature":0.7
    }
  },
  "models":{
    "providers":{
      "aliyun":{
        "apiKey":"你的dashscope api-key",
        "baseUrl":"https://dashscope.aliyuncs.com/compatible-mode/v1",
        "api":"openai-completions",
        "models":[
          {
            "id":"qwen-plus",
            "name":"qwen‑plus",
            "contextWindow":128000
          }
        ]
      }
    }
  }
}

方案 B：对接 Windows 宿主机 Ollama（本地私有化）

Ollama 运行在 Windows，WSL2 访问宿主机 IP，注意 WSL 无法直接使用 127.0.0.1 访问 Windows 服务，需要获取宿主机 IP：cat /etc/resolv.conf，取 nameserver 后的 IP 作为 baseUrl 的 IP 地址。

# 以qwen为例
{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "host":"127.0.0.1"
  },
  "agents":{
    "defaults":{
      "model":"qwen2.5:7b",
      "temperature":0.7
    }
  },
  "models":{
    "providers":{
      "ollama":{
        "apiKey":"dummy",
        "baseUrl":"http://宿主机IP:11434/v1",
        "api":"openai-completions",
        "models":[
          {
            "id":"qwen2.5:7b",
            "name":"qwen2.5‑7b本地",
            "contextWindow":32768
          }
        ]
      }
    }
  }
}

保存退出 nano 编辑器。

4.6 网关启停命令

# 安装守护进程
openclaw gateway install

# 查看网关状态
openclaw gateway status

# 启动网关
openclaw gateway start

# 停止网关
openclaw gateway stop

# 重启网关
openclaw gateway restart

健康检查，返回 ok 代表网关正常运行

curl http://127.0.0.1:18789/health

成功之后浏览器访问http://127.0.0.1:18789即可访问到你的交互页面