OpenClaw 本地部署完全指南：从环境验证到启动运行

文章目录

[OpenClaw 本地部署完全指南：从环境验证到启动运行](#OpenClaw 本地部署完全指南：从环境验证到启动运行)
- [📋 第一阶段：环境验证与安装](#📋 第一阶段：环境验证与安装)
- - [1. 验证依赖环境](#1. 验证依赖环境)
  - [2. 全局安装 OpenClaw](#2. 全局安装 OpenClaw)
  - [3. 验证安装成功](#3. 验证安装成功)
- [🚀 第二阶段：交互式配置向导](#🚀 第二阶段：交互式配置向导)
- - 第一步：启动配置向导
  - [第二步：配置模型 (Model) ------ **让 AI 变聪明的关键**](#第二步：配置模型 (Model) —— 让 AI 变聪明的关键)
  - [第三步：配置网关 (Gateway) ------ **核心步骤**](#第三步：配置网关 (Gateway) —— 核心步骤)
  - 第四步：完成并启动服务
- [🔗 第三阶段：连接客户端 (VS Code)](#🔗 第三阶段：连接客户端 (VS Code))
- [🛠️ 常用管理与故障排查](#🛠️ 常用管理与故障排查)
- - [1. 如何查看图形化面板？](#1. 如何查看图形化面板？)
  - [2. 配置文件在哪里？](#2. 配置文件在哪里？)
  - [3. 连接失败怎么办？](#3. 连接失败怎么办？)
  - [4. 如何让它在后台运行？](#4. 如何让它在后台运行？)
- [📝 关键信息速查表](#📝 关键信息速查表)
- 用nvm更新nodejs及安装

OpenClaw 本地部署完全指南：从环境验证到启动运行

适用场景 ：Windows/macOS/Linux 本地开发环境
目标：快速搭建 OpenClaw 网关，连接 VS Code 等编辑器与本地/远程 AI 模型。
更新时间 ：2026 年 3 月
核心版本要求：Node.js v22+, OpenClaw v2026+

📋 第一阶段：环境验证与安装

在开始配置之前，必须确保你的系统环境满足 OpenClaw 的运行要求。

1. 验证依赖环境

OpenClaw 基于 Node.js 构建，请打开终端（CMD/PowerShell/Terminal）依次执行以下命令，检查版本：

bash 复制代码

# 检查 Node.js 版本 (必须为 v22.x.x)
node --version 

# 检查 npm 版本 (必须为 v10.x.x 及以上)
npm --version

✅ 通过标准 ：
- node 输出类似 v22.14.0
- npm 输出类似 v10.9.0
❌ 未通过处理 ：如果版本过低，请前往 Node.js 官网下载最新的 LTS 版本或 Current 版本（需包含 Node 22）进行安装。

2. 全局安装 OpenClaw

环境验证通过后，使用 npm 全局安装最新版的 OpenClaw：

bash 复制代码

npm install -g openclaw@latest

3. 验证安装成功

安装完成后，验证 CLI 工具是否可用及版本号：

bash 复制代码

openclaw --version

✅ 通过标准 ：输出版本号需为 2026.x.x 及以上（例如 2026.3.10）。
注：如果提示命令不存在，请检查 npm 的全局 bin 目录是否已添加到系统环境变量 PATH 中。

🚀 第二阶段：交互式配置向导

安装成功后，我们将通过交互式界面完成核心配置。

第一步：启动配置向导

在终端中直接运行：

bash 复制代码

openclaw configure
# 或者直接运行 openclaw，它通常会自动检测并进入配置模式

系统将进入交互式配置界面 (Select sections to configure)。

第二步：配置模型 (Model) ------ 让 AI 变聪明的关键

⚠️ 重要前提 ：在配置此步骤前，请确保你的模型后端（如 Ollama, LM Studio, LocalAI 等）已经安装并正在运行。

在主菜单中，使用方向键选择 Model ，按 Enter 进入。
选择模型提供商 (Provider) ：
- 根据你运行的后端选择对应的选项：
  - 如果你用 Ollama ：选择 Ollama。
  - 如果你用 LM Studio ：选择 OpenAI Compatible (LM Studio 兼容 OpenAI 协议)。
  - 如果你用 原生 OpenAI API ：选择 OpenAI。
  - 其他后端通常选择 OpenAI Compatible 或 Custom。
配置后端地址 (Base URL) ：
- 系统会提示输入 API 地址。
- Ollama 默认 ：http://127.0.0.1:11434
- LM Studio 默认 ：http://127.0.0.1:1234/v1 (注意末尾的 /v1)
- OpenAI 官方 ：https://api.openai.com/v1
- 操作：输入地址后按 Enter。
配置 API Key (如果需要) ：
- 如果是本地模型（Ollama/LM Studio），通常留空或输入 ollama / lm-studio 即可（具体视后端要求，本地通常不需要真实 Key）。
- 如果是云端模型（OpenAI/Claude），请输入你的真实 API Key。
选择默认模型名称 (Model Name) ：
- 系统可能会尝试自动拉取模型列表。
- 手动输入你要使用的模型 ID，例如：
  - Ollama: qwen2.5:7b, llama3:8b
  - LM Studio: 你在软件中加载的模型文件名对应的 ID。
- 操作：输入模型名后按 Enter。
测试连接 (Health Check) ：
- 配置完成后，系统通常会询问是否进行测试。选择 Yes。
- 如果显示 Success 或 OK，说明 OpenClaw 已成功连接到你的模型后端。

第三步：配置网关 (Gateway) ------ 核心步骤

网关是 OpenClaw 的核心组件，负责接收编辑器请求并转发给 AI 模型。

返回主菜单，选择 Gateway ，按 Enter 进入。
Tailscale Exposure (外网暴露) :
- 选项：Off (默认) / On
- 建议：选择 Off。
- 理由：除非你需要通过 Tailscale 从其他机器远程访问，否则本地开发只需监听 127.0.0.1，更安全且延迟更低。
Gateway token source (令牌来源) :
- 选项：Generate/store plaintext token (Default) / Use SecretRef
- 建议：保持默认，直接按 Enter 选择 Generate/store plaintext token。
- 理由：系统会自动生成一个高强度随机 Token 并保存到本地配置文件。
Gateway token (网关令牌) :
- 界面会显示一串自动生成的字符（例如：783691885311de7ffd0d38c0ab9e78bee0f0399fbfe0c4b3）。
- 操作：直接按 Enter 确认使用。
- ⚠️ 重要 ：请务必复制并保存这串 Token！后续在 VS Code 插件中连接时必须用到它。

配置完成后，系统会自动备份旧配置文件 (openclaw.json.bak) 并写入新配置。

第四步：完成并启动服务

返回主菜单 (Select sections to configure)。
使用方向键向下移动，选择最底部的 Continue。
按 Enter 确认。

此时，终端将显示启动成功的信息：

text 复制代码

Control UI -------------------------------------------------------------------------------+
|                                                                                            |
|  Web UI: http://127.0.0.1:18789/                                                           |
|  Gateway WS: ws://127.0.0.1:18789                                                          |
|  Gateway: not detected (gateway closed (1006 abnormal closure...))                         |
|  Docs: https://docs.openclaw.ai/web/control-ui                                             |
|                                                                                            |
+--------------------------------------------------------------------------------------------+
|
---  Configure complete.

💡 关于 "Gateway: not detected" 的提示 ：

看到 1006 abnormal closure 不要惊慌。这通常是因为启动瞬间没有客户端（如 VS Code）连接，属于正常现象。只要窗口不报错退出，服务即视为运行正常。

🔗 第三阶段：连接客户端 (VS Code)

服务启动后，保持终端窗口最小化但不要关闭（它是服务端进程）。

打开 VS Code。
进入 OpenClaw 插件设置页面。
配置连接信息：
- WebSocket URL : ws://127.0.0.1:18789 (默认端口通常为 18789，以终端输出为准)。
- Token : 填入你在"第三步"中记录的那串 Token (例如 7836...)。
点击 Connect 或 Save。
测试：在聊天窗口发送 "Hello, are you ready?"，如果收到回复，说明部署成功！

🛠️ 常用管理与故障排查

1. 如何查看图形化面板？

在浏览器中访问终端输出的地址：

👉 http://127.0.0.1:18789/

在这里可以查看实时日志、会话历史和系统状态。

2. 配置文件在哪里？

默认位于用户目录下的隐藏文件夹：

Windows : C:\Users\<你的用户名>\.openclaw\openclaw.json
macOS/Linux : ~/.openclaw/openclaw.json

如果需要修改端口或 Token，可以直接编辑此文件（修改前建议先停止服务）。

3. 连接失败怎么办？

检查模型后端：确保 Ollama 或 LM Studio 正在运行，且模型已加载。
检查版本 ：确保 openclaw --version 是 2026.x.x 以上，Node 是 v22。
检查端口 ：确认 VS Code 中的端口与终端输出的 Gateway WS 端口一致。
检查 Token：Token 必须完全匹配，多一个空格都会导致认证失败。
检查防火墙 ：虽然是本地连接，但某些严格的安全软件可能会拦截 18789 端口。

4. 如何让它在后台运行？

如果你不想一直开着黑色终端窗口：

简单方法：右键点击窗口标题栏 -> 属性 -> 布局 -> 勾选"启动时最小化"。
高级方法 (Windows) ：使用 nssm 将其注册为 Windows 服务。
高级方法 (Linux/macOS) ：使用 systemd 或 launchd 配置守护进程。

📝 关键信息速查表

项目	默认值/示例	说明
Node.js 要求	`v22.x.x`	必须版本
OpenClaw 版本	`2026.x.x`	需通过 `npm install -g` 获取
Ollama 地址	`http://127.0.0.1:11434`	本地模型常见地址
LM Studio 地址	`http://127.0.0.1:1234/v1`	注意末尾 `/v1`
Web UI 地址	`http://127.0.0.1:18789/`	浏览器管理面板
WS 连接地址	`ws://127.0.0.1:18789`	插件连接地址
Token	`7836...` (自动生成)	连接密钥，务必保存

恭喜！ 你现在已经拥有了一个从环境搭建、模型配置到网关启动的完整本地 AI 开发环境。下次部署时，只需按照此流程操作即可。

用nvm更新nodejs及安装

cmd 复制代码

C:\Windows\System32>node -v
v20.11.1

C:\Windows\System32>node --version
v20.11.1

C:\Windows\System32>npm --version
10.8.2

C:\Windows\System32>nvm list

  * 20.11.1 (Currently using 64-bit executable)
    18.20.3
    16.18.0

C:\Windows\System32>nvm install latest
25.8.0
Downloading node.js version 25.8.0 (64-bit)...
Extracting node and npm...
Complete
npm v11.11.0 installed successfully.


Installation complete. If you want to use this version, type

nvm use 25.8.0

C:\Windows\System32>nvm use 25.8.0
Now using node v25.8.0 (64-bit)

C:\Windows\System32>npm -v
11.11.0

C:\Windows\System32>npm install -g openclaw@latest
npm warn deprecated node-domexception@1.0.0: Use your platform's native DOMException instead
npm warn deprecated glob@10.5.0: Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me

added 671 packages in 3m

C:\Windows\System32>openclaw --version
OpenClaw 2026.3.8 (3caab92)

部署

cmd 复制代码

C:\Windows\System32>G:

G:\>cd G:\OpenClaw


G:\OpenClaw>openclaw configure

🦞 OpenClaw 2026.3.8 (3caab92) --- If it works, it's automation; if it breaks, it's a "learning opportunity."

▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
██░▄▄▄░██░▄▄░██░▄▄▄██░▀██░██░▄▄▀██░████░▄▄▀██░███░██
██░███░██░▀▀░██░▄▄▄██░█░█░██░█████░████░▀▀░██░█░█░██
██░▀▀▀░██░█████░▀▀▀██░██▄░██░▀▀▄██░▀▀░█░██░██▄▀▄▀▄██
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
                  🦞 OPENCLAW 🦞

T  OpenClaw configure
|
o  Where will the Gateway run?
|  Local (this machine)
|
o  Select sections to configure
|  Workspace
|
o  Workspace directory
|  G:\OpenClaw
Workspace OK: G:\OpenClaw
Sessions OK: ~\.openclaw\agents\main\sessions
Updated ~\.openclaw\openclaw.json
|
o  Select sections to configure
|  Model
|
o  Model/auth provider
|  Qwen
|
•  Starting Qwen OAuth...|
o  Qwen OAuth -------------------------------------------------------------------------+
|                                                                                      |
|  Open https://chat.qwen.xxxxxxxxxxxxxxxxxxxxxxxxxxxx |
|  access.                                                                             |
|  If prompted, enter the code xxxxxxxxxxxxxxxx.                                               |
|                                                                                      |
+--------------------------------------------------------------------------------------+
o  Qwen OAuth complete
|
o  Model configured -----------------------------+
|                                                |
|  Default model set to qwen-portal/coder-model  |
|                                                |
+------------------------------------------------+
|
o  Provider notes ----------------------------------------------------------------------+
|                                                                                       |
|  Qwen OAuth tokens auto-refresh. Re-run login if refresh fails or access is revoked.  |
|  Base URL defaults to https://portal.qwen.ai/v1. Override                             |
|  models.providers.qwen-portal.baseUrl if needed.                                      |
|                                                                                       |
+---------------------------------------------------------------------------------------+
|
o  Models in /model picker (multi-select)
|  2 items selected
|
o  Select sections to configure
|  Gateway
|
o  Gateway port
|  18789
|
o  Gateway bind mode
|  Loopback (Local only)
|
o  Gateway auth
|  Token
|
o  Tailscale exposure
|  Off
|
o  Gateway token source
|  Generate/store plaintext token
|
|
o  Select sections to configure
|  Continue
|
o  Control UI -------------------------------------------------------------------------------+
|                                                                                            |
|  Web UI: http://127.0.0.1:18789/                                                           |
|  Gateway WS: ws://127.0.0.1:18789                                                          |
|  Gateway: not detected (gateway closed (1006 abnormal closure (no close frame)): no close  |
|  reason)                                                                                   |
|  Docs: https://docs.openclaw.ai/web/control-ui                                             |
|                                                                                            |
+--------------------------------------------------------------------------------------------+
|
---  Configure complete.