在 Windows 中安装并配置OpenClaw
在 Windows 中安装并配置OpenClaw
环境：Windows 11 25H2 + WSL2 (Ubuntu)，OpenClaw 版本 2026.3.2
各安装方式对比
为不同场景的用户，OpenClaw官方提供了多种安装路径。怎么选？一张对比表，让你一目了然。
Windows 下的安装方式对比
下表清晰地梳理了每种方式的适用场景、优点与主要限制：
| 安装方式 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|
① Installer Script（WSL2 bash） curl -fsSL ...|bash | 在 WSL2/Ubuntu 环境下运行 | 全自动处理 Node 检测与安装，一步到位；Linux 生态完整，systemd 守护进程支持最好，两个系统间，文件能一定程度的隔离 | 需要先配置 WSL2 |
| ② Installer Script（Windows PowerShell 原生） | 不想装 WSL2，直接在 Windows 运行 | 无需 WSL2，上手门槛低 | Windows 下 systemd 不可用，守护进程能力受限；npm 全局路径问题较多 |
③ npm 手动安装 npm install -g openclaw@latest | 已有 Node 22+，想自己管理版本 | 灵活，便于版本控制 | 需自行处理 Node 版本及 sharp/node-gyp 等原生依赖问题 |
④ pnpm 安装 pnpm add -g openclaw@latest | 习惯使用 pnpm 的开发者 | 磁盘利用率更高 | 需要额外执行 pnpm approve-builds -g 批准 build script，步骤略繁琐 |
⑤ 源码构建 git clone + pnpm build | 开发者 / 贡献者 | 可修改源码、调试 | 配置复杂，不适合普通用户 |
官方推荐方式及原因
官方的答案很明确：首选 Installer Script（即方式①或②）。
不妨看看官方文档的原文建议：
“The installer script is the recommended way to install OpenClaw. It handles Node detection, installation, and onboarding in one step.”
推荐的理由其实很充分，主要基于三点考量：
- 全自动化：脚本会自动检测系统里有没有Node.js，如果没有，它会帮你一并安装。省去了手动配置依赖的麻烦，对新手极其友好。
- 集成向导：安装完成后，它会自动进入onboarding引导流程。这一步至关重要，能有效降低因配置遗漏导致后续无法使用的风险。
- 环境优先：官方不止一次强调，如果在Windows系统上，“我们强烈建议在WSL2下运行OpenClaw”。为什么？因为在WSL2环境下，systemd守护进程的支持更完整，诸如
sharp、node-llama-cpp这类Node生态的原生依赖兼容性会好得多，整体系统稳定性和体验都明显优于Windows原生环境。
接下来，我们就以官方最推荐的路径，详细介绍在WSL2中安装OpenClaw的具体步骤。
前置条件
在开始之前，请确保你的Windows 11已经安装并配置好了WSL2，且使用的Linux发行版为Ubuntu。
如果还没安装WSL2，可以按照Microsoft官方文档的指引轻松完成安装和初始化。
安装步骤
1. 安装 OpenClaw
打开你的WSL2 Ubuntu终端，执行以下命令：
curl -fsSL https://openclaw.ai/install.sh | bash
这个脚本会自动处理Node.js等所有必需的依赖。安装完成后，它会自动跳转到引导向导。网络状况不同，这个过程需要的时间差异不小，通常可能需要等待30分钟左右，给自己泡杯咖啡的时间刚好。
2. 运行引导向导
如果安装完成后向导没有自动启动，无需担心，手动执行命令即可：
openclaw onboard --install-daemon
注意这里的--install-daemon参数，它表示将Gateway服务注册为systemd的后台服务，能实现开机自启和更好的进程管理。
跟着向导的提示一步步完成以下配置，切记不要跳过任何一步：
- 选择运行模式（例如
local）。 - 配置你的OpenAI API Key。
- 配置Agent的默认模型（比如
openai/gpt-5.2-pro）。 - 配置Gateway服务监听的端口（默认为
18789）。
3. 启动 Gateway
向导配置完成后，使用以下命令启动Gateway服务：
openclaw gateway start
如果看到终端提示 systemd service: openclaw-gateway.service 已启动，那就说明服务启动成功了。
4. 打开 Dashboard 并完成连接
Gateway启动后，就可以通过网页仪表盘进行管理了：
- 在Windows的浏览器中访问：
http://127.0.0.1:18789。 - 进入左侧菜单栏的「控制」→「概览」。
- 在页面的「网关访问」区域，确认WebSocket URL和网关令牌（token）已经自动填充。
- 直接点击那个醒目的「连接」按钮。
当右上角显示健康状况：正常时，恭喜你，连接已成功建立！✅
验证安装
安装是否成功，看几个关键指标就清楚了。在Dashboard的「概览」页面的「快照」区域，你应该能看到如下信息：
| 项目 | 状态 |
|---|---|
| 健康状况 | 正常 |
| 版本 | 2026.3.2 |
| 状态 | 正常 |
| 最后频道刷新 | just now |
下图是我本机安装成功后，控制台「概览」页面的真实截图，可以作为成功安装的参考：
FAQ
Q1：执行 openclaw onboard 后，立刻又弹出了新的向导，循环不止？
别慌，这通常是因为向导检测到之前的配置不完整，触发了自动的重新引导机制。
解决方法很简单：从头再运行一次向导，但这次必须严格对待，每一步都做出明确的选择或确认，确保配置项都完整填写，不要使用跳过或默认选项蒙混过关。
Q2：Dashboard 提示无法连接 / token 未授权？
这个问题多半是在安装引导时，跳过了某些关键步骤，导致Control UI未能与Gateway完成必要的“握手”认证。
可以按照以下步骤检查和修复：
- 确保浏览器访问的是
http://127.0.0.1:18789。 - 进入「概览」页面。
- 检查「网关令牌」输入框内是否为空。token通常保存在
~/.openclaw/openclaw.json配置文件的gateway.auth.token字段里。 - 如果token存在，直接点击「连接」按钮。
你也可以通过命令快速查看当前token：
cat ~/.openclaw/openclaw.json | grep token
Q3：重启 Gateway 后问题依然存在怎么办？
如果执行标准的 openclaw gateway restart 没有效果，可以尝试一个更彻底的“重启套餐”，确保所有相关进程都被清理干净：
openclaw gateway stop
sleep 3
pkill -f "openclaw.*gateway" 2>/dev/null
sleep 2
openclaw gateway start
Q4：如何确认 Gateway 正在正常运行？
有两个最直观的方法：
- 在WSL2终端里使用systemctl命令检查服务状态：
systemctl status openclaw-gateway.service
- 更简单的方式是直接看Dashboard右上角，只要「健康状况」显示为「正常」，就说明一切运转良好。
相关文件位置
了解关键文件的存放位置，对于后续的维护和问题排查很有帮助：
| 文件 | 路径 |
|---|---|
| 主配置文件 | ~/.openclaw/openclaw.json |
| Workspace 目录 | ~/.openclaw/workspace |
| Gateway 端口 | 18789（默认） |
遇到问题时，建议首先核对
~/.openclaw/openclaw.json配置文件是否完整准确，很多问题都源于这里的配置缺失。确认无误后，再尝试重启Gateway服务，往往能解决大部分初期故障。