Windows配置openclaw，我把该踩得坑都踩了 —— 附完整安装配置流程

zhangxinhe

        经过反复的折腾，我终于在Windows上成功跑通了OpenClaw。这期间遇到了无数个坑：WSL网络不通、端口转发失败、GitHub Models地址错误、模型 ID不识别、技能无法调用、网关假死……/(ㄒoㄒ)/~~

现在把完整的安装配置流程和踩过的坑都整理出来，按照这个顺序操作，你应该能一次成功。😀

第一篇：安装流程（照着做就行）
第一章：Windows原生环境准备
1.1 安装Node.js（必选）
为什么选Node.js？ OpenClaw基于Node.js运行，必须装。

访问 Node.js官网 https://nodejs.org/

下载 22.x LTS版本（不要下载最新版，LTS最稳）

安装时注意：

✅ 安装路径改为 D:\NodeJs（避免C盘爆满）

✅ 勾选“自动安装必要工具”

✅ 勾选“添加到PATH”

安装完成后，打开PowerShell验证：

node --version  
# 应该显示 v22.x.x
npm --version   
# 应该显示 10.x.x
AI写代码
bash
1.2 配置PowerShell执行策略（必选）
如果遇到 无法加载文件 npm.ps1 的报错：

# 以管理员身份运行PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
AI写代码
bash

1.3 设置npm全局路径到D盘（推荐，避免C盘爆满）
# 创建目录
mkdir D:\OpenClaw\npm-global -Force
mkdir D:\OpenClaw\npm-cache -Force
AI写代码
bash
# 配置npm路径
npm config set prefix "D:\OpenClaw\npm-global"
npm config set cache "D:\OpenClaw\npm-cache"
AI写代码
bash
# 添加到系统PATH

1. [Environment]::SetEnvironmentVariable("Path", "$env:Path;D:\OpenClaw\npm-global", "User")

复制代码

AI写代码
bash
重启PowerShell使配置生效

第二章：安装OpenClaw
2.1 全局安装OpenClaw
#powershell
# 以管理员身份运行PowerShell

1. npm install -g openclaw@latest

复制代码

AI写代码
bash
预期结果：

added 656 packages in 3m
AI写代码
bash
如果报错：

EACCES 权限错误 → 用管理员身份运行
网络超时 → 切换网络或使用代理
2.2 验证安装
#powershell

1. openclaw --version

复制代码

# 应该显示 2026.3.2 或类似版本
AI写代码
bash
第三章：首次配置（最关键的一步）
3.1 运行配置向导
#powershell

1. openclaw onboard

复制代码

#按提示选择：
#知晓风险 → Yes
#安装模式 → QuickStart（快速开始）
#配置类型 → Create new（创建新配置）
AI写代码
bash
3.2 配置模型提供商（我选的是智谱，完全免费可替换自己的ai key）
当问到 Model/auth provider 时：
选择 Custom Provider（自定义提供商）
API Base URL：输入 https://open.bigmodel.cn/api/paas/v4
API Key：输入你的智谱API Key（获取方式见第四章）
Endpoint compatibility：选择 OpenAI-compatible
Model ID：输入 glm-5
注意： 智谱的模型ID就是 glm-5，不要加任何前缀后缀。
3.3 完成向导
通讯渠道 → Skip for now（先不配）
技能配置 → No（稍后手动装）
最后选择 → Restart（重启网关）
第四章：获取智谱API Key（完全免费）
4.1 注册账号
访问 智谱开放平台 https://bigmodel.cn/
手机号注册登录
新用户自动获得 2000万tokens免费额度
4.2 创建API Key
登录后进入控制台
左侧菜单找到 “API密钥”
点击 “新建API密钥”
输入名称（比如 "openclaw"）
复制生成的Key（格式：一串数字.字母）
第五章：安装文件管理技能（让AI能操作电脑，自选）
5.1 安装ClawHub（技能商店）
#powershell

1. npm install -g clawhub

复制代码

AI写代码
bash

5.2 安装file-manager技能
#powershell

1. npx clawhub@latest install file-manager

复制代码

#预期结果：
#text
#✔ OK. Installed file-manager -> C:\Users\你的用户名\.openclaw\workspace\skills\file-manager
AI写代码
bash
5.3 验证技能安装
#powershell

1. openclaw skills list

复制代码

#应该能看到：
#text
#✓ ready   │ 📦 file-manager   │ OpenClaw自动化文件管理助手...
AI写代码
bash

第六章：配置网关和权限
6.1 编辑配置文件
#powershell

1. notepad $env:USERPROFILE\.openclaw\openclaw.json

复制代码

AI写代码
bash
6.2 替换为完整配置

1. {
   
2.   "models": {
   
3.     "mode": "merge",
   
4.     "providers": {
   
5.       "zhipu": {
   
6.         "baseUrl": "https://open.bigmodel.cn/api/paas/v4",
   
7.         "apiKey": "你的智谱API Key",
   
8.         "api": "openai-completions",
   
9.         "models": [
   
10.           {
    
11.             "id": "glm-5",
    
12.             "name": "GLM-5",
    
13.             "contextWindow": 128000,
    
14.             "maxTokens": 4096
    
15.           }
    
16.         ]
    
17.       }
    
18.     }
    
19.   },
    
20.   "agents": {
    
21.     "defaults": {
    
22.       "model": {
    
23.         "primary": "zhipu/glm-5"
    
24.       },
    
25.       "workspace": "C:\\Users\\你的用户名\\.openclaw\\workspace"
    
26.     }
    
27.   },
    
28.   "tools": {
    
29.     "profile": "full",
    
30.     "exec": {
    
31.       "host": "gateway",
    
32.       "security": "full",
    
33.       "ask": "off"
    
34.     }
    
35.   },
    
36.   "commands": {
    
37.     "native": "auto",
    
38.     "nativeSkills": "auto",
    
39.     "restart": true,
    
40.     "bash": true
    
41.   },
    
42.   "gateway": {
    
43.     "port": 18789,
    
44.     "mode": "local",
    
45.     "bind": "loopback",
    
46.     "auth": {
    
47.       "mode": "token",
    
48.       "token": "你的网关Token"
    
49.     }
    
50.   }
    
51. }

复制代码

AI写代码
bash

6.3 重启网关
#powershell

1. openclaw gateway restart

复制代码

AI写代码
bash
6.4 验证状态
#powershell

1. openclaw gateway status

复制代码

# 必须看到：
# Runtime: running
# RPC probe: ok
# Listening: 127.0.0.1:18789
AI写代码
bash
第七章：测试文件操作
7.1 打开控制面板
#powershell

1. openclaw dashboard

复制代码

#浏览器会自动打开 http://127.0.0.1:18789/
AI写代码
bash
7.2 登录
使用配置文件中的Token登录（可在配置文件中查看 gateway.auth.token）

7.3 测试指令
在聊天界面输入：
我桌面上有哪些文件？列出文件名就行
成功标志： AI返回你桌面上的文件列表。
AI写代码
bash
第二篇：我踩过的坑（血泪史）
第一章：安装阶段的坑
坑1：C盘爆满 症状： 安装到一半提示磁盘空间不足
原因： npm默认安装到C盘，OpenClaw依赖多

解决： 提前配置npm路径到D盘

#powershell

1. npm config set prefix "D:\OpenClaw\npm-global"
   
2. npm config set cache "D:\OpenClaw\npm-cache"

复制代码

AI写代码
bash

坑2：PowerShell禁止运行脚本
症状：
无法加载文件 npm.ps1，因为在此系统上禁止运行脚本
原因： Windows默认执行策略是Restricted

解决：

#powershell

1. Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

复制代码

AI写代码
bash

第二章：WSL的坑（血的教训）
坑3：在WSL里折腾
症状：WSL的IP地址每次重启都变

Windows浏览器访问不了WSL的127.0.0.1

端口转发规则各种失灵

教训： 不要用WSL！直接Windows原生安装，省去99%的网络问题。


第三章：模型接入的坑
坑4：GitHub Models地址错误
错误地址：

https://models.inference.ai.azure.com/v1  ❌
正确地址：
https://models.github.ai/inference  ✅


坑5：模型ID不识别
错误格式：
deepseek-v3-0324 ❌
glm-4.7-flash ❌
正确格式：
deepseek/deepseek-v3-0324 ✅
glm-5 ✅

坑6：Token权限不足
症状： 返回401 Unauthorized

解决： 生成GitHub Token时必须勾选 read:models 权限

坑7：以为免费就是永久免费
真相： 硅基流动的免费额度用完后会收费，我0.07元账单就是例子

教训： 用智谱GLM-5，明确标注“免费调用”


第四章：网关的坑
坑8：端口被占用
症状： 网关启动超时，端口18789被占用

排查：

#powershell

1. netstat -ano | findstr "18789"

复制代码

AI写代码
bash
解决：

#powershell
taskkill /F /PID 占用端口的PID
AI写代码
bash

坑9：网关假死
症状：

Runtime: unknownRPC probe: ok（诡异吧？🧐）端口没监听

解决：

#powershell

1. openclaw gateway stop
   
2. taskkill /F /IM node.exe
   
3. openclaw gateway start

复制代码

AI写代码
bash

第五章：技能的坑
坑10：技能显示ready但用不了
症状：

openclaw skills list显示 file-manager ✓ ready

AI回答“我只能用message工具”
AI写代码
Matlab
运行
原因1： profile 设置不对

#json
"profile": "messaging"  // ❌ 只有消息功能
"profile": "full"       // ✅ 完整权限
AI写代码
java
运行
原因2： 技能需要刷新
在聊天界面发送：

!reload skills
AI写代码
bash
原因3： 问问题的方式不对

❌ 错误： “你能用什么工具？”
✅ 正确： “帮我列出桌面上的文件”
AI写代码
bash

第六章：配置文件的坑
坑11：不认识的配置项
症状：

Unrecognized key: "filesystem"
AI写代码
bash
原因： 新版OpenClaw不支持直接配置filesystem，要通过file-manager技能实现

解决： 删除不认识的配置，用技能替代


坑12：配置文件语法错误
症状： 网关启动失败，提示JSON解析错误

常见错误：缺少逗号、多了一个逗号、引号不匹配

解决： 用JSON验证工具检查格式



第七章：网络穿透的坑
坑13：ngrok免费域名不被企业微信信任
症状： 企业微信提示“域名主体校验未通过”

原因： 已认证的企业微信必须用备案域名，IP和ngrok域名都不行

解决：

用未认证的企业微信小号测试（不需要备案）
或者购买已备案域名


第八章：其他坑
坑14：重启后配置丢失
原因： 忘记保存配置文件

教训： 每次改配置前备份

#powershell

1. copy $env:USERPROFILE\.openclaw\openclaw.json $env:USERPROFILE\.openclaw\openclaw.json.bak

复制代码

AI写代码
bash
坑15：日志不会看
症状： 遇到问题不知道从哪查起

正确姿势：

#powershell
# 实时查看日志

1. openclaw logs --follow

复制代码

# 查看网关状态
openclaw gateway status

# 查看模型状态

1. openclaw models list

复制代码

AI写代码
bash

第三篇：最终配置文件模板

1. {
   
2.   "meta": {
   
3.     "lastTouchedVersion": "2026.3.2",
   
4.     "lastTouchedAt": "2026-03-04T07:38:30.637Z"
   
5.   },
   
6.   "models": {
   
7.     "mode": "merge",
   
8.     "providers": {
   
9.       "zhipu": {
   
10.         "baseUrl": "https://open.bigmodel.cn/api/paas/v4",
    
11.         "apiKey": "你的智谱API Key",
    
12.         "api": "openai-completions",
    
13.         "models": [
    
14.           {
    
15.             "id": "glm-5",
    
16.             "name": "GLM-5",
    
17.             "contextWindow": 128000,
    
18.             "maxTokens": 4096
    
19.           }
    
20.         ]
    
21.       }
    
22.     }
    
23.   },
    
24.   "agents": {
    
25.     "defaults": {
    
26.       "model": {
    
27.         "primary": "zhipu/glm-5"
    
28.       },
    
29.       "workspace": "C:\\Users\\你的用户名\\.openclaw\\workspace"
    
30.     }
    
31.   },
    
32.   "tools": {
    
33.     "profile": "full",
    
34.     "exec": {
    
35.       "host": "gateway",
    
36.       "security": "full",
    
37.       "ask": "off"
    
38.     }
    
39.   },
    
40.   "commands": {
    
41.     "native": "auto",
    
42.     "nativeSkills": "auto",
    
43.     "restart": true,
    
44.     "bash": true
    
45.   },
    
46.   "gateway": {
    
47.     "port": 18789,
    
48.     "mode": "local",
    
49.     "bind": "loopback",
    
50.     "auth": {
    
51.       "mode": "token",
    
52.       "token": "你的网关Token"
    
53.     }
    
54.   }
    
55. }

复制代码

AI写代码
java
运行


结语
从WSL到Windows，从GitHub Models到智谱，从403到200，这一路踩了无数坑。希望这篇文档能帮你一次性成功，不用像我一样折腾几天几夜。

最后的忠告：

不要用WSL，直接Windows原生安装
不要用GitHub Models，用智谱GLM-5（完全免费）
配置文件备份，每次改配置前先备份
先看日志再问问题，openclaw logs --follow 是最好的老师
祝你一次成功！🎉