OpenClaw Windows Companion 桌面客户端 连接 LM Studio 完整配置指南

OpenClaw Windows Companion 桌面客户端 连接 LM Studio 完整配置指南

作者 ：AITechLab 由 Kimi AI 助手复盘整理

日期 ：2026-07-20

环境：Windows 11 + OpenClaw 2026.7.1-2 + LM Studio + Node.js v24.18.0

---

一、前言

OpenClaw 是一款开源的 AI 代理框架，支持通过桌面客户端（Windows Companion）连接本地或远程的 Gateway 网关，进而调用各种 AI 模型服务。本文详细记录将 OpenClaw Windows Companion 连接到 LM Studio 本地模型服务的完整配置过程，包括踩坑排查和解决方案。

技术更新纪实：OpenClaw 与 Hermes AI Agent 现已支持 Windows 桌面客户端部署

---

二、架构理解（关键！）

在开始配置前，必须先理解 OpenClaw 的架构：

┌─────────────────────────┐      ┌──────────────────┐      ┌─────────────────┐
│ OpenClaw Windows        │ ──▶  │ OpenClaw Gateway │ ──▶  │ LM Studio       │
│ Companion (桌面客户端)   │ WS   │ (ws://:18789)   │ HTTP │ (http://:1234) │
└─────────────────────────┘      └──────────────────┘      └─────────────────┘
         ↑                                                        ↑
    需要 Gateway Token                                      加载本地模型

核心要点：

• ❌ 不能直接让 Companion → LM Studio（协议不匹配，Companion 使用 WebSocket）
• ✅ 正确路径 ：Companion → OpenClaw Gateway → LM Studio
• Gateway 负责协议转换和权限管理，LM Studio 只提供模型推理服务

OpenClaw 本地部署 LM Studio 全模型接入热切换教程

---

三、环境准备

3.1 安装 LM Studio

1. 从 lmstudio.ai 下载并安装
2. 下载并加载所需的模型（如 google/gemma-4-26b-a4b）
3. 启动 Local Server ：
   • 进入 Developer → Local Server
   • 点击 Start Server
   • 默认地址：http://localhost:1234

3.2 验证 LM Studio 服务

curl http://localhost:1234/v1/models

应返回模型列表 JSON，确认服务正常。

3.3 安装 Node.js（版本要求严格！）

OpenClaw 对 Node.js 版本有严格要求：

• ✅ >=22.22.3 <23
• ✅ >=24.15.0 <25
• ✅ >=25.9.0 <26
• ❌ v25.6.0 不在支持范围内！

安装 Node.js v24 LTS：

# 使用 nvm-windows
nvm install 24.15.0
nvm use 24.15.0

# 或使用 Scoop
scoop install nodejs-lts@24.15.0

---

四、踩坑实录：Node.js 版本冲突

4.1 问题现象

openclaw --version
# 报错：Node.js >=22.22.3 <23, >=24.15.0 <25, or >=25.9.0 <25 is required (current: v25.6.0)

4.2 根因分析

系统中存在多个 Node.js 安装，PATH 优先级导致 nvm 切换不生效：

where node
# C:\Program Files
odejs
ode.exe      ← 系统安装 v25.6.0（罪魁祸首）
# C:\Windows\System32
ode
# D:\Scooppps
odejs-lts\current
ode.exe  ← Scoop 安装

4.3 解决方案

方案一：调整 PATH 优先级（推荐）

将 Scoop 或 nvm 的 Node.js 路径移到系统 PATH 的最前面：

# 查看当前 PATH
echo $env:PATH

# 临时调整（当前会话）
$env:PATH = "D:\Scooppps
odejs-lts\current;" + $env:PATH

# 永久调整：系统属性 → 环境变量 → Path → 上移

方案二：卸载系统 Node.js

# 重命名备份（保留系统安装）
ren "C:\Program Files
odejs
ode.exe" "node.exe.bak"
ren "C:\Program Files
odejs
pm.cmd" "npm.cmd.bak"

验证修复：

node -v
# v24.18.0  ✅

---

五、安装并配置 OpenClaw

5.1 安装 OpenClaw CLI

npm install -g openclaw

5.2 配置模型提供商（LM Studio）

运行交互式配置向导：

openclaw onboard

按提示选择：

• 选择 Custom Provider 或 LM Studio
• API Base URL: http://localhost:1234/v1
• API Key: 留空或填 lm-studio
• 选择模型（如 google/gemma-4-26b-a4b）

非交互式配置：

openclaw onboard --non-interactive --accept-risk \
  --auth-choice lmstudio \
  --custom-base-url http://localhost:1234/v1 \
  --custom-model-id google/gemma-4-26b-a4b

5.3 启动 Gateway

openclaw gateway

启动成功后输出示例：

🦞 OpenClaw 2026.7.1-2
[gateway] agent model: custom-127-0-0-1-1234/google/gemma-4-26b-a4b
[gateway] http server listening (4 plugins...)
[gateway] ready
[tailscale] serve enabled: https://ai.tail4f1ea9.ts.net/

关键信息：

• Gateway 地址：ws://localhost:18789
• 模型已代理到 LM Studio

OpenClaw 本地部署 LM Studio 全模型接入热切换教程
【OpenClaw 本地实战 Ep.2】零代码对接：使用交互式向导快速连接本地 LM Studio 用 CUDA GPU 推理

---

六、Windows Companion 连接 Gateway

【OpenClaw 本地实战 Ep.4】终极提效：一劳永逸解决切换浏览器 Token 鉴权失败与断连问题

6.1 获取 Gateway Token

在另一个 PowerShell 窗口运行：

openclaw config get gateway.auth.token

或从浏览器鉴权 URL 提取：http://127.0.0.1:18789/#token=abc1234

6.2 配置 Companion

打开 OpenClaw Windows Companion，进入 Gateway → Connection → Add gateway：

配置项	值
Gateway URL	http://localhost:18789（自动转为 ws://）
Shared token	上面获取的 token
Name	任意，如 Local Gateway

点击 Save & connect。

6.3 设备配对批准

首次连接会提示 "Awaiting approval"，在 Gateway 主机上运行：

openclaw devices approve <device-id>
# 示例：
openclaw devices approve 1d4dea13-90fa-43a1-9415-99cced6c54f2

然后在 Companion 中点击 Connect （或自动检测并跳转下一界面）。

---

七、Node 权限批准

连接成功后，Companion 作为 Node 注册到 Gateway，需要批准其权限声明：

openclaw nodes approve <node-id>
# 示例：
openclaw nodes approve ff6a3c99-10df-418a-a9a2-e2766248addb

批准后在 Companion 中点击 "Reconnect after approval"。

最终状态：

• ✅ Gateway: Connected
• ✅ Node: Node active · 9 capabilities
• 能力包括：Browser control、Camera、Canvas、Screen capture、Location、TTS、STT、Device info、System access

---

八、常见问题排查

Q1: "Cannot reach gateway"

原因 ：端口无服务监听

排查：

netstat -ano | findstr :1234   # LM Studio
netstat -ano | findstr :18789  # OpenClaw Gateway

Q2: "No credential available"

原因 ：OpenClaw Gateway 需要 token 认证

解决 ：运行 openclaw config get gateway.auth.token 获取

Q3: "Transport error"

原因 ：Companion 使用 WebSocket 协议连接 Gateway，不能直接连 HTTP API

解决 ：确认 URL 是 Gateway 地址（:18789），不是 LM Studio 地址（:1234）

Q4: Node.js 版本反复切换失败

原因 ：系统 PATH 中有多个 Node.js，优先级冲突

解决：

# 查看所有 node 路径
where node

# 确认实际使用的版本
Get-Command node | Select-Object Source
node -v

---

九、总结

OpenClaw 就只给它套了个壳（图形界面）？

步骤	操作	关键命令
1	启动 LM Studio 本地服务器	在 LM Studio GUI 中 Start Server
2	修复 Node.js 版本	nvm use 24.15.0 / 调整 PATH
3	安装 OpenClaw	npm install -g openclaw
4	配置 LM Studio 为模型提供商	openclaw onboard
5	启动 Gateway	openclaw gateway
6	获取 Token	openclaw config get gateway.auth.token
7	Companion 连接 Gateway	URL: http://localhost:18789
8	批准设备配对	openclaw devices approve <id>
9	批准 Node 权限	openclaw nodes approve <id>

---

十、参考链接

• OpenClaw GitHub
• LM Studio 文档
• OpenClaw 官方文档

---

结语：OpenClaw 的架构设计将 Gateway 作为核心枢纽，Companion 只负责展示和交互，模型推理由后端服务（如 LM Studio）提供。理解这一分层架构是配置成功的关键。希望本文能帮助你顺利完成配置！

---

本文基于实际配置过程复盘整理，如有问题欢迎在评论区交流。