Windows 原生搭建 OpenClaw 实战指南｜从安装到网关连通（避坑版）

前言

作为一名前端开发者，最近尝试在 Windows 原生环境部署 OpenClaw ，过程中遇到了令牌配置迁移、--force 参数不兼容、端口占用等典型问题。本文基于实际操作，从基础搭建到问题闭环，整理成可直接复用的步骤，避免重复踩坑，帮助同环境的开发者快速完成部署。

一、环境准备

核心依赖要求

依赖项	版本要求	说明
操作系统	Windows 10/11 64 位	无需 WSL2，原生环境可运行
Node.js	≥ 22.0.0	官方强制要求，低于此版本会导致安装失败
终端	管理员权限 PowerShell	避免权限不足导致的配置 / 启动问题

快速安装 Node.js

1. 前往 Node.js 官网，下载 Windows 64 位 .msi 安装包；
2. 安装时勾选「Automatically install the necessary tools」，自动配置环境变量；
3. 验证安装：在管理员 PowerShell 执行以下命令，输出版本即成功。

node -v # 应显示 22.x.x
npm -v # 应显示 10.9.4

二、基础搭建：从安装到初始化

步骤 1：全局安装 OpenClaw

使用 npm 全局安装最新版 OpenClaw，这是官方推荐的最简方式。

npm install -g openclaw@latest

若出现 sharp 安装失败，可添加环境变量强制使用预构建二进制文件：$env:SHARP_IGNORE_GLOBAL_LIBVIPS=1; npm install -g openclaw@latest。

步骤 2：初始化配置（可选）

执行初始化向导，快速完成基础配置（如工作空间、模型提供商），新手建议执行。

openclaw onboard

按照交互提示选择即可，若暂时无需配置模型（键盘空格选择），可选择「Skip」跳过。

步骤 3：验证安装

执行以下命令，查看 OpenClaw 版本，确认安装成功。

openclaw --version # 应显示

三、核心配置：网关认证与令牌迁移

问题背景

首次启动网关后，控制面板出现 unauthorized: gateway token missing 报错，尝试配置 gateway.token 时，收到「配置已迁移至 gateway.auth.token」的提示。

关键操作

1. 设置认证令牌 OpenClaw 已将令牌配置迁移至 gateway.auth.token，原 gateway.token 被废弃。执行以下命令设置自定义令牌：

   openclaw config set gateway.auth.token "my-openclaw-token"
   
   

2. 验证配置（脱敏显示是正常的） 执行查询命令，输出 __OPENCLAW_REDACTED__ 为安全脱敏机制，代表令牌已成功保存，并非配置失败。

   openclaw config get gateway.auth.token
   
   

四、网关启动：Windows 环境避坑核心

问题 1：--force 参数不兼容

执行 openclaw gateway run --force --auth none --allow-unconfigured 时，出现 fuser not found 报错。原因：--force 依赖 Linux/macOS 下的 fuser 工具清理端口占用，Windows 无此工具，直接移除即可。

问题 2：端口占用兜底方案

若启动时提示 port 18789 is already in use，使用 Windows 原生命令清理。

# 1. 查找 18789 端口占用的进程 PID
netstat -ano | findstr :18789

# 2. 强制终止进程（替换 [PID] 为上一步查到的数字）
taskkill /F /PID [PID]

最终启动命令（Windows 专用）

采用无认证模式启动网关（本地开发最省事，无安全风险），无需令牌即可连通。

openclaw gateway run --auth none --allow-unconfigured

启动成功标志

命令行日志显示 Gateway WebSocket listening on ws://127.0.0.1:18789，无任何认证 / 端口相关报错。

五、控制面板连通：完成最后一步

1. 打开浏览器，访问 http://127.0.0.1:18789，进入 OpenClaw 控制面板；
2. 因已启用 --auth none，无需填写任何令牌，直接刷新页面；
3. 页面底部显示「Connected to gateway」，代表网关与控制面板成功连通，此前的 unauthorized 报错彻底解决。

六、总结与注意事项

1. 配置迁移：gateway.token 已废弃，统一使用 gateway.auth.token 配置认证令牌；
2. Windows 特性：--force 参数无效，端口占用需用 netstat + taskkill 处理；
3. 安全建议：本地开发可使用 --auth none，若需远程访问，建议恢复令牌认证并严格保管；
4. 进程管理：网关为前台运行，关闭终端会停止服务，本地开发可保持终端打开，生产环境建议配置为系统服务。

通过以上步骤，可在 Windows 原生环境快速完成 OpenClaw 基础搭建与网关连通，避开核心兼容性问题。后续若需配置模型、部署服务，可参考官方文档进一步扩展。