OpenClaw 安装与配置完全指南

目录

1. OpenClaw 简介
2. 环境准备
3. 安装 OpenClaw
4. 配置国内免费模型
5. 常见问题与解决方案
6. 常用命令速查

1. OpenClaw 简介

OpenClaw 是一个开源的 AI 助手框架，可以让你在本地运行大语言模型，支持多种模型提供商，包括 OpenAI、OpenRouter、智谱 AI、Kimi 等。

主要特性

• 🤖 支持多种大模型提供商
• 💻 本地运行，数据安全
• 🌐 支持 Web 界面和命令行交互
• 🔧 高度可配置
• 📱 支持多平台（Windows、macOS、Linux）

2. 环境准备

2.1 系统要求

• 操作系统：Windows 10/11（本文以 Windows 为例）
• Node.js：v18.0.0 或更高版本
• 网络：可访问 npm 仓库

2.2 安装 Node.js

如果尚未安装 Node.js，请访问 nodejs.org 下载并安装 LTS 版本。

验证安装：

node -v
npm -v

2.3 配置 npm 镜像（国内用户推荐）

由于网络原因，建议配置国内 npm 镜像：

npm config set registry https://registry.npmmirror.com

3. 安装 OpenClaw

3.1 安装国内镜像版

由于原版 OpenClaw 在国内安装可能遇到网络问题，推荐使用国内镜像版 openclaw-cn：

npm install -g openclaw-cn@latest

3.2 验证安装

安装完成后，验证是否成功：

openclaw-cn --version

预期输出：

0.1.8-fix.3

3.3 初始化配置

运行配置向导：

openclaw-cn onboard

按照提示完成初始配置。

4. 配置国内免费模型

4.1 推荐方案：智谱 AI（GLM-4-Flash）

智谱 AI 是国内领先的大模型提供商，其 GLM-4-Flash 模型完全免费，无使用额度限制。

步骤 1：获取 API Key

1. 访问智谱 AI 官网：https://bigmodel.cn/
2. 使用手机号或 Google 账号注册/登录
3. 进入控制台，创建 API Key
4. 复制保存 API Key（格式类似：xxxxxxxx.xxxxxxxx）

步骤 2：配置 OpenClaw

使用非交互式命令快速配置：

openclaw-cn onboard `
  --non-interactive `
  --accept-risk `
  --flow quickstart `
  --auth-choice zai-api-key `
  --zai-api-key "你的智谱API Key"

步骤 3：验证配置

测试模型连接：

openclaw-cn agent --local -m "你好" --agent main

如果看到 AI 回复，说明配置成功！

4.2 其他国内免费模型选项

5. 常见问题与解决方案

问题 1：npm 安装失败

现象：

npm error code 128
npm error An unknown git error occurred

解决：

# 配置 Git 使用 HTTPS 代替 SSH
git config --global url."https://github.com/".insteadOf "ssh://git@github.com/"

# 或者使用国内镜像
npm config set registry https://registry.npmmirror.com

问题 2：模型配置后提示 "Unknown model"

现象：

Error: Unknown model: xxx/xxx

解决：

检查配置文件 ~\.openclaw\openclaw.json 中的模型 ID 是否正确：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "zai/glm-4.5"
      }
    }
  }
}

问题 3：网关服务无法启动

现象：

Gateway service missing

解决：

手动启动网关：

openclaw-cn gateway run

或者在后台运行：

# 停止现有进程
taskkill /F /IM node.exe

# 重新启动
openclaw-cn gateway run

问题 4：Windows 执行策略限制

现象：

npm : 无法加载文件...因为在此系统上禁止运行脚本

解决：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

问题 5：powershell执行openclaw-cn失败

现象：

PS C:\Users\visec\.openclaw> openclaw-cn status
openclaw-cn : 无法将“openclaw-cn”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写，如果包括路径，
请确保路径正确，然后再试一次。
所在位置 行:1 字符: 1
+ openclaw-cn status
+ ~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (openclaw-cn:String) [], CommandNotFoundException
    + FullyQualifiedErrorId : CommandNotFoundException

PS C:\Users\visec\.openclaw>

解决：

# 将 openclaw-cn 添加到 PATH
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Users\visec\.stepfun\runtimes\node\install_1770035104440_y6saz4xvup\node-v22.18.0-win-x64", "User")

6. 常用命令速查

基础命令

对话相关

网关管理

配置管理

结语

通过本文档，您应该已经成功在 Windows 上安装并配置了 OpenClaw，接入了智谱 AI 的免费大模型。

OpenClaw 是一个功能强大的本地 AI 助手框架，支持多种模型和丰富的配置选项。建议进一步阅读官方文档，探索更多高级功能。

相关链接：

• OpenClaw 官方文档：https://docs.clawd.bot/
• 智谱 AI 官网：https://bigmodel.cn/

本文首发于 www.it525.com，转载请注明出处。