经过反复的折腾，我终于在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

1.2 配置PowerShell执行策略（必选）

如果遇到 无法加载文件 npm.ps1 的报错：

# 以管理员身份运行PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

1.3 设置npm全局路径到D盘（推荐，避免C盘爆满）

# 创建目录
mkdir D:\OpenClaw\npm-global -Force
mkdir D:\OpenClaw\npm-cache -Force

# 配置npm路径
npm config set prefix "D:\OpenClaw\npm-global"
npm config set cache "D:\OpenClaw\npm-cache"

# 添加到系统PATH
[Environment]::SetEnvironmentVariable("Path", "$env:Path;D:\OpenClaw\npm-global", "User")

重启PowerShell使配置生效

第二章：安装OpenClaw

2.1 全局安装OpenClaw

#powershell
# 以管理员身份运行PowerShell
npm install -g openclaw@latest

预期结果：

added 656 packages in 3m

如果报错：

• EACCES 权限错误 → 用管理员身份运行
• 网络超时 → 切换网络或使用代理

2.2 验证安装

#powershell
openclaw --version
# 应该显示 2026.3.2 或类似版本

第三章：首次配置（最关键的一步）

3.1 运行配置向导

#powershell
openclaw onboard
#按提示选择：
#知晓风险 → Yes
#安装模式 → QuickStart（快速开始）
#配置类型 → Create new（创建新配置）

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 完成向导

1. 通讯渠道 → Skip for now（先不配）
2. 技能配置 → No（稍后手动装）
3. 最后选择 → Restart（重启网关）

第四章：获取智谱API Key（完全免费）

4.1 注册账号

1. 访问 智谱开放平台 https://bigmodel.cn/
2. 手机号注册登录
3. 新用户自动获得 2000万tokens免费额度

4.2 创建API Key

1. 登录后进入控制台
2. 左侧菜单找到 “API密钥”
3. 点击 “新建API密钥”
4. 输入名称（比如 "openclaw"）
5. 复制生成的Key（格式：一串数字.字母）

第五章：安装文件管理技能（让AI能操作电脑，自选）

5.1 安装ClawHub（技能商店）

#powershell
npm install -g clawhub

5.2 安装file-manager技能

#powershell
npx clawhub@latest install file-manager
#预期结果：
#text
#✔ OK. Installed file-manager -> C:\Users\你的用户名\.openclaw\workspace\skills\file-manager

5.3 验证技能安装

#powershell
openclaw skills list
#应该能看到：
#text
#✓ ready   │ 📦 file-manager   │ OpenClaw自动化文件管理助手...

第六章：配置网关和权限

6.1 编辑配置文件

#powershell
notepad $env:USERPROFILE\.openclaw\openclaw.json

6.2 替换为完整配置

{
  "models": {
    "mode": "merge",
    "providers": {
      "zhipu": {
        "baseUrl": "https://open.bigmodel.cn/api/paas/v4",
        "apiKey": "你的智谱API Key",
        "api": "openai-completions",
        "models": [
          {
            "id": "glm-5",
            "name": "GLM-5",
            "contextWindow": 128000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "zhipu/glm-5"
      },
      "workspace": "C:\\Users\\你的用户名\\.openclaw\\workspace"
    }
  },
  "tools": {
    "profile": "full",
    "exec": {
      "host": "gateway",
      "security": "full",
      "ask": "off"
    }
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true,
    "bash": true
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "你的网关Token"
    }
  }
}

6.3 重启网关

#powershell
openclaw gateway restart

6.4 验证状态

#powershell
openclaw gateway status
# 必须看到：
# Runtime: running
# RPC probe: ok
# Listening: 127.0.0.1:18789

第七章：测试文件操作

7.1 打开控制面板

#powershell
openclaw dashboard
#浏览器会自动打开 http://127.0.0.1:18789/

7.2 登录

使用配置文件中的Token登录（可在配置文件中查看 gateway.auth.token）

7.3 测试指令
在聊天界面输入：

我桌面上有哪些文件？列出文件名就行
成功标志： AI返回你桌面上的文件列表。

第二篇：我踩过的坑（血泪史）

第一章：安装阶段的坑

坑1：C盘爆满 症状： 安装到一半提示磁盘空间不足

原因： npm默认安装到C盘，OpenClaw依赖多

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

#powershell
npm config set prefix "D:\OpenClaw\npm-global"
npm config set cache "D:\OpenClaw\npm-cache"

 

坑2：PowerShell禁止运行脚本

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

解决：

#powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

第二章：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
netstat -ano | findstr "18789"

解决：

#powershell
taskkill /F /PID 占用端口的PID

 

坑9：网关假死

症状：

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

解决：

#powershell
openclaw gateway stop
taskkill /F /IM node.exe
openclaw gateway start

第五章：技能的坑

坑10：技能显示ready但用不了

症状：

openclaw skills list显示 file-manager ✓ ready

AI回答“我只能用message工具”

原因1： profile 设置不对

#json
"profile": "messaging"  // ❌ 只有消息功能
"profile": "full"       // ✅ 完整权限

原因2： 技能需要刷新
在聊天界面发送：

!reload skills

原因3： 问问题的方式不对

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

 

第六章：配置文件的坑

坑11：不认识的配置项

症状：

Unrecognized key: "filesystem"

原因： 新版OpenClaw不支持直接配置filesystem，要通过file-manager技能实现

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

 

坑12：配置文件语法错误

症状： 网关启动失败，提示JSON解析错误

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

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

 

第七章：网络穿透的坑

坑13：ngrok免费域名不被企业微信信任

症状： 企业微信提示“域名主体校验未通过”

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

解决：

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

 

第八章：其他坑

坑14：重启后配置丢失

原因： 忘记保存配置文件

教训： 每次改配置前备份

#powershell
copy $env:USERPROFILE\.openclaw\openclaw.json $env:USERPROFILE\.openclaw\openclaw.json.bak

坑15：日志不会看

症状： 遇到问题不知道从哪查起

正确姿势：

#powershell
# 实时查看日志
openclaw logs --follow

# 查看网关状态
openclaw gateway status

# 查看模型状态
openclaw models list

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

{
  "meta": {
    "lastTouchedVersion": "2026.3.2",
    "lastTouchedAt": "2026-03-04T07:38:30.637Z"
  },
  "models": {
    "mode": "merge",
    "providers": {
      "zhipu": {
        "baseUrl": "https://open.bigmodel.cn/api/paas/v4",
        "apiKey": "你的智谱API Key",
        "api": "openai-completions",
        "models": [
          {
            "id": "glm-5",
            "name": "GLM-5",
            "contextWindow": 128000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "zhipu/glm-5"
      },
      "workspace": "C:\\Users\\你的用户名\\.openclaw\\workspace"
    }
  },
  "tools": {
    "profile": "full",
    "exec": {
      "host": "gateway",
      "security": "full",
      "ask": "off"
    }
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true,
    "bash": true
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "你的网关Token"
    }
  }
}

结语

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

最后的忠告：

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

祝你一次成功！🎉