𝐘𝐀𝐈

Windows 上安装 OpenClaw（WSL2 / Docker），并配置 XAI Router（gpt-5.4）

Posted February 10, 2026 by XAI 技术团队 ‐ 5 min read

OpenClaw

OpenClaw + XAI Router

本文将带你在 Windows 上运行 OpenClaw，并通过 XAI Router（xairouter） 使用 gpt-5.4。

可按以下两种方式进行：

  1. Windows 非 Docker（推荐：WSL2 + Ubuntu）：CLI + Gateway 跑在 WSL2 的 Linux 环境内
  2. Windows 使用 Docker（Docker Desktop + Docker Compose）：Gateway 跑在容器里

你将得到什么

  1. 一个可用的 OpenClaw Gateway（默认端口 18789）
  2. 一个 OpenResponses 兼容入口：http://127.0.0.1:18789/v1/responses
  3. 默认上游模型：xairouter/gpt-5.4

先决条件

  • Windows 10/11
  • 一个 XAI Router API Key（形如 sk-...）

二选一：

  • 方式一（推荐）：WSL2 + Ubuntu
  • 方式二：Docker Desktop + Docker Compose

OpenClaw 在 Windows 上官方推荐使用 WSL2（Ubuntu 推荐），这样 Node/Bun/pnpm 以及很多工具链兼容性更好。

方式一：Windows 非 Docker（WSL2 + Ubuntu，推荐）

这一方式的核心思路是：把 OpenClaw 当作 Linux 应用跑在 WSL2 里。

第一步：安装 WSL2 + Ubuntu

打开 PowerShell（建议管理员权限）执行：

wsl --install
# 或者指定发行版：
wsl --list --online
wsl --install -d Ubuntu-24.04

如系统提示重启，请按提示重启。

第二步：启用 systemd（推荐）

在 WSL2 终端里执行：

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

然后回到 PowerShell 执行：

wsl --shutdown

重新打开 Ubuntu，再验证：

systemctl --user status

第三步：安装 OpenClaw（在 WSL2 内）

推荐使用官方安装脚本（会处理 Node 检测/安装）：

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

验证安装：

openclaw --version

第四步：配置 XAI Router（gpt-5.4 推荐 Responses 路径）

  1. 设置环境变量：
export XAI_API_KEY="sk-..."
export OPENCLAW_GATEWAY_TOKEN="$(openssl rand -hex 32)"
  1. 写入 OpenClaw 配置文件 ~/.openclaw/openclaw.json：
mkdir -p ~/.openclaw

cat > ~/.openclaw/openclaw.json <<'EOF'
{
  "models": {
    "mode": "replace",
    "providers": {
      "xairouter": {
        "baseUrl": "https://api.xairouter.com/v1",
        "apiKey": "${XAI_API_KEY}",
        "api": "openai-responses",
        "models": [
          { "id": "gpt-5.4", "name": "GPT-5.4" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "xairouter/gpt-5.4" },
      "models": {
        "xairouter/gpt-5.4": {
          "alias": "Codex",
          "params": { "transport": "sse" }
        }
      }
    }
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "${OPENCLAW_GATEWAY_TOKEN}"
    },
    "http": {
      "endpoints": {
        "responses": { "enabled": true }
      }
    }
  }
}
EOF

说明：这套配置会让 OpenClaw 以上游 openai-responses 方式连接 XAI Router；不需要额外添加 headers.originator，params.transport = "sse" 会优先走 HTTP /v1/responses。如果你偏好 WebSocket-first，可改成 "auto"。

第五步：启动 Gateway

在 WSL2 里运行：

openclaw gateway --bind loopback --port 18789 --force

第六步：用 curl 验证（WSL2 内）

curl -sS http://127.0.0.1:18789/v1/responses \
  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-openclaw-agent-id: main" \
  -d '{"model":"openclaw","input":"ping"}'

你会收到一个 OpenResponses 风格 的 JSON 响应。

方式二：Windows 使用 Docker（Docker Desktop + Docker Compose）

这一方式的核心思路是：Gateway 跑在容器里，你只需要填 .env 就能启动。

第一步：下载部署模板

在 PowerShell 中执行：

git clone https://github.com/xaixagent/openclaw.git
cd openclaw

这个目录里最关键的文件：

  • docker-compose.yml：定义 openclaw-gateway 与 openclaw-cli
  • .env.example：环境变量模板
  • configs/：放你自己的 OpenClaw 配置

第二步：创建并填写 .env

Copy-Item .env.example .env
notepad .env

编辑 .env，至少需要三项：

  • XAI_API_KEY：你的 XAI Router Key
  • OPENCLAW_GATEWAY_TOKEN：Gateway 的访问令牌（用于 HTTP Authorization: Bearer ...）
  • OPENCLAW_CONFIG_NAME：设为 openclaw.xairouter-codex.json

生成一个随机的 OPENCLAW_GATEWAY_TOKEN（推荐 32 字节 / 64 个十六进制字符）：

$bytes = New-Object byte[] 32
[System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
($bytes | ForEach-Object { $_.ToString("x2") }) -join ""

一个最小可用的 .env 示例：

XAI_API_KEY="sk-xxxxxxxxxxxxxxxx"
OPENCLAW_GATEWAY_TOKEN="your-random-token"
OPENCLAW_CONFIG_NAME="openclaw.xairouter-codex.json"
OPENCLAW_GATEWAY_PORT=18789

第二步（补充）：创建 configs/openclaw.xairouter-codex.json

@'
{
  "models": {
    "mode": "replace",
    "providers": {
      "xairouter": {
        "baseUrl": "https://api.xairouter.com/v1",
        "apiKey": "${XAI_API_KEY}",
        "api": "openai-responses",
        "models": [
          { "id": "gpt-5.4", "name": "GPT-5.4" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "xairouter/gpt-5.4" },
      "models": {
        "xairouter/gpt-5.4": {
          "alias": "Codex",
          "params": { "transport": "sse" }
        }
      }
    }
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "${OPENCLAW_GATEWAY_TOKEN}"
    },
    "http": {
      "endpoints": {
        "responses": { "enabled": true }
      }
    }
  }
}
'@ | Set-Content configs/openclaw.xairouter-codex.json

第三步：启动 OpenClaw Gateway

docker compose up -d openclaw-gateway

查看运行状态：

docker compose ps

查看启动日志（第一次启动建议看一下）：

docker compose logs -f openclaw-gateway

如果你的环境只有 docker-compose，请把上面的 docker compose 替换为 docker-compose。

第四步：用 curl.exe 验证 gpt-5.4 是否可用

在同一台机器执行（PowerShell 中 curl 可能是别名，建议使用 curl.exe）：

# Load variables from .env into this PowerShell session
Get-Content .env | ForEach-Object {
  if ($_ -match '^\s*#' -or $_ -match '^\s*$') { return }
  $k, $v = $_ -split '=', 2
  Set-Item -Path ("env:" + $k.Trim()) -Value $v.Trim()
}

curl.exe -sS "http://127.0.0.1:$env:OPENCLAW_GATEWAY_PORT/v1/responses" `
  -H "Authorization: Bearer $env:OPENCLAW_GATEWAY_TOKEN" `
  -H "Content-Type: application/json" `
  -H "x-openclaw-agent-id: main" `
  -d '{"model":"openclaw","input":"ping"}'

为什么请求里写的是 model: "openclaw"？

这不是上游模型名，而是 OpenClaw Gateway 的“统一模型名”。

  • 你的应用侧：始终写 model: "openclaw"
  • 真正的上游模型：由配置决定（本教程默认为 xairouter/gpt-5.4）

在你的代码里当作 OpenAI Responses API 使用（可选）

只要把 OpenAI SDK 的：

  • baseURL 指向你的 Gateway：http://127.0.0.1:18789/v1
  • apiKey 填 OPENCLAW_GATEWAY_TOKEN

即可像调用 OpenAI Responses 一样调用 OpenClaw。

Node.js（openai SDK）示例：

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://127.0.0.1:18789/v1",
  apiKey: process.env.OPENCLAW_GATEWAY_TOKEN,
});

const resp = await client.responses.create({
  model: "openclaw",
  input: "ping",
});

console.log(resp.output_text);

Windows：局域网访问（可选）

如果你希望局域网内其它机器访问 Gateway，可能需要放行 Windows 防火墙（管理员 PowerShell，示例端口 18789）：

New-NetFirewallRule -DisplayName "OpenClaw Gateway 18789" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 18789

常用维护命令（Docker 方式）

停止并删除容器（保留数据目录 state/）：

docker compose down

升级镜像并重启：

docker compose pull
docker compose up -d openclaw-gateway

如果你需要“彻底重置”（会清掉会话/状态数据），可以：

docker compose down
Remove-Item -Recurse -Force state, workspace, codex

想了解 OpenClaw 通过 XAI Router 接入更多模型/协议，可参考：/blog/openclaw/