OpenClaw 2026.x Windows + WSL2 完整部署指南
一、目标

在 Windows 11 环境下（可能还得在翻墙环境下）：

安装 WSL2 Ubuntu

安装 Node.js

下载 OpenClaw

启动 Gateway

正确配置 OpenAI API Key

成功使用 Chat

二、Windows 环境准备
1️⃣ 检查 Windows 版本

必须：

Windows 10 21H2 以上
或

Windows 11

检查方式：

winver
2️⃣ 安装 WSL2

在 PowerShell（管理员模式）运行：

wsl --install

安装完成后重启电脑。

3️⃣ 设置默认 WSL 版本为 2
wsl --set-default-version 2
4️⃣ 安装 Ubuntu

如果未自动安装：

打开 Microsoft Store：

搜索：

Ubuntu 22.04 LTS

或命令安装：

wsl --install -d Ubuntu-22.04
5️⃣ 首次启动 Ubuntu

设置用户名与密码。

例如：

Username: l××××××
Password: ********
三、WSL 环境基础配置

进入 Ubuntu 后：

sudo apt update
sudo apt upgrade -y
四、安装 Node.js（必须 18+，推荐 20+）
推荐使用 NodeSource
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

验证：

node -v
npm -v

应显示类似：

v22.x.x
五、安装 Git
sudo apt install -y git

验证：

git --version
六、下载 OpenClaw

进入 home：

cd ~

克隆源码：

git clone https://github.com/openclaw/openclaw.git openclaw-src
cd openclaw-src

安装依赖（使用 pnpm）：

sudo npm install -g pnpm
pnpm install
七、首次启动 OpenClaw
node openclaw.mjs gateway --allow-unconfigured

成功标志：

[gateway] listening on ws://127.0.0.1:18789
[browser/server] Browser control listening on http://127.0.0.1:18791
八、查询 Gateway Token
python3 - <<‘PY’
import json, pathlib
cfg=json.loads(pathlib.Path.home().joinpath(“.openclaw/openclaw.json”).read_text())
print(cfg[“gateway”][“auth”][“token”])
PY

在浏览器访问：

http://localhost:18791/?token=刚刚打印的token
九、配置 OpenAI API Key（关键步骤）

⚠️ 不要在 Dashboard 填
⚠️ 不要在 openclaw.json 填
⚠️ 只在 auth-profiles.json 填

创建目录
mkdir -p ~/.openclaw/agents/main/agent
写入正确结构（2026.x 必须）
nano ~/.openclaw/agents/main/agent/auth-profiles.json

写入：

{
“profiles”: {
“default”: {
“providers”: {
“openai”: {
“key”: “sk-***”
}
}
}
},
“activeProfile”: “default”
}

保存退出。

验证 JSON
python3 -m json.tool ~/.openclaw/agents/main/agent/auth-profiles.json
十、设置默认模型

推荐测试模型：

python3 - <<‘PY’
import json, pathlib
p=pathlib.Path.home().joinpath(“.openclaw/openclaw.json”)
cfg=json.loads(p.read_text())
cfg.setdefault(“agents”, {}).setdefault(“defaults”, {})[“model”]=“openai/gpt-4o-mini”
p.write_text(json.dumps(cfg, indent=2))
print(“Model updated”)
PY
十一、降低并发（防止限流）
python3 - <<‘PY’
import json, pathlib
p=pathlib.Path.home().joinpath(“.openclaw/openclaw.json”)
cfg=json.loads(p.read_text())
d=cfg.setdefault(“agents”, {}).setdefault(“defaults”, {})
d[“maxConcurrent”]=1
d.setdefault(“subagents”, {})[“maxConcurrent”]=1
p.write_text(json.dumps(cfg, indent=2))
print(“Concurrency reduced”)
PY
十二、重启 Gateway
Ctrl + C
node openclaw.mjs gateway --allow-unconfigured
十三、成功验证

访问：

http://localhost:18789

在 Chat 输入：

hello

如果返回 AI 回复，说明成功。

十四、常见错误与解决方案
1️⃣ JSON5 parse failed

原因：

手动修改 openclaw.json 破坏格式

解决：

rm -rf ~/.openclaw
node openclaw.mjs gateway --allow-unconfigured
2️⃣ gateway token missing

原因：

浏览器未携带 token

解决：

访问：

http://localhost:18791/?token=xxx
3️⃣ No API key found

原因：

auth-profiles.json 结构错误

必须使用：

profiles.default.providers.openai.key
4️⃣ ignored invalid auth profile entries

说明：

JSON 结构不符合当前版本

使用本文推荐结构。

5️⃣ API rate limit reached

解决：

降低并发

使用 gpt-4o-mini

检查 OpenAI 项目额度

十五、最终架构图
Browser
↓ (Gateway Token)
Gateway (18789)
↓
Agent
↓ (auth-profiles.json)
OpenAI API
十六、最终稳定启动命令
cd ~/openclaw-src
export OPENAI_API_KEY=“sk-***”
node openclaw.mjs gateway --allow-unconfigured
总结

成功运行 OpenClaw 需要理解三层认证：

Gateway Token（浏览器连接）

Agent Auth（OpenAI key）

Model 指定（gpt-4o-mini）

绝大多数错误来自：

把 API key 填错位置

JSON 结构不符合 2026.x schema

并发导致限流