OpenClaw 本地部署与 GLM-5 配置指南

本文档介绍如何在本地部署 OpenClaw 并配置智谱 AI GLM-5 模型。

环境要求

• 操作系统: Windows / Linux / macOS
• Node.js: v18.0.0 或更高版本
• npm: 8.0.0 或更高版本

安装 Node.js 和 npm

OpenClaw 基于 Node.js 开发，需要先安装 Node.js 运行环境。

Windows 系统安装

方式一：官网下载安装（推荐）

1. 访问 Node.js 官网

   打开浏览器访问：https://nodejs.org/zh-cn/

2. 下载 LTS 版本

   • 点击下载 LTS（长期支持） 版本
   • 推荐：Node.js v20.x 或 v22.x LTS
   • 文件名类似：node-v20.xx.x-x64.msi

3. 运行安装程序

   • 双击下载的 .msi 安装文件
   • 勾选 “Automatically install the necessary tools”（自动安装必要工具）
   • 点击 Next 完成安装
   • 建议保持默认安装路径：C:\Program Files\nodejs\

4. 验证安装

   打开 命令提示符 或 PowerShell：

   node --version
   npm --version
   

   输出示例：

   v20.11.0
   10.2.4
   

方式二：通过包管理器安装

使用 Chocolatey：

# 以管理员身份运行 PowerShell
choco install nodejs-lts -y

使用 Scoop：

scoop install nodejs-lts

---

Linux 系统安装

Ubuntu / Debian

# 使用 NodeSource 仓库安装 Node.js 20.x
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装
node --version
npm --version

CentOS / RHEL / Fedora

# 使用 NodeSource 仓库安装 Node.js 20.x
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs

# 验证安装
node --version
npm --version

Arch Linux

sudo pacman -S nodejs npm

---

macOS 系统安装

方式一：官网下载安装

1. 访问 https://nodejs.org/zh-cn/
2. 下载 macOS 版本的 .pkg 安装包
3. 双击运行安装包，按提示完成安装

方式二：使用 Homebrew（推荐）

# 安装 Homebrew（如果未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Node.js
brew install node

# 验证安装
node --version
npm --version

---

配置 npm 镜像源（可选，国内用户推荐）

使用淘宝镜像加速：

# 临时使用
npm install --registry=https://registry.npmmirror.com

# 永久配置
npm config set registry https://registry.npmmirror.com

# 验证配置
npm config get registry

恢复官方源：

npm config set registry https://registry.npmjs.org

---

安装步骤

1. 检查 Node.js 环境

node --version
npm --version

2. 全局安装 OpenClaw

npm install -g openclaw

安装完成后验证版本：

openclaw --version

输出示例：

OpenClaw 2026.3.8 (3caab92)

3. 初始化配置

openclaw setup

输出示例：

Wrote ~\.openclaw\openclaw.json
Workspace OK: ~\.openclaw\workspace
Sessions OK: ~\.openclaw\agents\main\sessions

配置 GLM-5 模型

4. 配置 ZAI Provider

编辑配置文件 ~\.openclaw\openclaw.json，添加 zai provider 和 GLM-5 模型：

openclaw config edit

或直接编辑文件：C:\Users\Administrator\.openclaw\openclaw.json

配置内容：

{
  "agents": {
    "defaults": {
      "workspace": "C:\\Users\\当前用户名\\.openclaw\\workspace",
      "models": {
        "zai/glm-5": {
          "alias": "glm-5"
        }
      }
    }
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true,
    "ownerDisplay": "raw"
  },
  "gateway": {
    "mode": "local",
    "port": 39999
  },
  "meta": {
    "lastTouchedVersion": "2026.3.8",
    "lastTouchedAt": "2026-03-11T05:40:18.691Z"
  },
  "models": {
    "mode": "merge",
    "providers": {
      "zai": {
        "apiKey": "YOUR_ZHIPU_API_KEY",
        "api": "openai-completions",
        "baseUrl": "https://open.bigmodel.cn/api/paas/v4/",
        "models": [
          {
            "id": "glm-5",
            "name": "GLM-5",
            "reasoning": true,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 128000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

5. 设置自定义端口（可选）

openclaw config set gateway.port 39999

6. 配置认证 Token（推荐）

openclaw config set gateway.auth.token "your-custom-token"

示例：

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

7. 配置智谱 AI API Key

方式1：通过命令设置

openclaw config set models.providers.zai.apiKey "YOUR_ZHIPU_API_KEY"

方式2：手动编辑配置文件

编辑 ~\.openclaw\openclaw.json，将：

"apiKey": ""

改为：

"apiKey": "YOUR_ZHIPU_API_KEY"

获取 API Key: 访问 智谱AI开放平台 注册并获取 API Key

8. 验证配置

openclaw config validate

输出示例：

Config valid: ~\.openclaw\openclaw.json

启动服务

9. 启动 Gateway

openclaw gateway

10. 访问 Control UI

打开浏览器访问：

http://127.0.0.1:39999/#token=your-token

示例（使用上述配置的 token）：

http://127.0.0.1:39999/#token=openclaw-xxx

常用命令

查看状态

openclaw status

查看可用模型

openclaw models

切换模型

openclaw models set zai/glm-5

运行 Agent

openclaw agent --message "你好"

查看日志

openclaw logs --follow

安全审计

openclaw security audit

查看帮助

openclaw --help
openclaw gateway --help

配置文件位置

系统	配置文件路径
Windows	C:\Users\YourUsername\.openclaw\openclaw.json
Linux/macOS	~/.openclaw/openclaw.json

完整配置示例

{
  "meta": {
    "lastTouchedVersion": "2026.3.8",
    "lastTouchedAt": "2026-03-11T06:11:31.213Z"
  },
  "models": {
    "mode": "merge",
    "providers": {
      "zai": {
        "baseUrl": "https://open.bigmodel.cn/api/paas/v4/",
        "apiKey": "YOUR_ZHIPU_API_KEY",
        "api": "openai-completions",
        "models": [
          {
            "id": "glm-5",
            "name": "GLM-5",
            "reasoning": true,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 128000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "models": {
        "zai/glm-5": {
          "alias": "glm-5"
        }
      },
      "workspace": "C:\\Users\\当前用户名\\.openclaw\\workspace"
    }
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true,
    "ownerDisplay": "raw"
  },
  "gateway": {
    "port": 39999,
    "mode": "local",
    "auth": {
      "token": "openclaw-高嘌呤"
    }
  }
}

故障排查

Gateway 连接失败

Error: ConnectionRefused

解决方案: Gateway 未启动，运行 openclaw gateway 启动服务

配置验证失败

Config invalid at ~\.openclaw\openclaw.json

解决方案: 检查 JSON 语法，运行 openclaw doctor 修复

模型不可用

model not allowed: zai/glm-5

解决方案: 确保模型已添加到 agents.defaults.models 配置中

API Key 无效

解决方案:

1. 检查 API Key 是否正确
2. 确认智谱 AI 账户余额充足
3. 验证 API Key 权限

参考资源

• OpenClaw 官方文档
• OpenClaw GitHub
• 智谱AI开放平台
• OpenClaw 常见问题

更新 OpenClaw

npm update -g openclaw

或使用 OpenClaw 内置更新命令：

openclaw update

卸载

openclaw uninstall

这会删除 Gateway 服务和本地数据，但保留 CLI。

---

文档版本: 1.0
更新日期: 2026-03-11
OpenClaw 版本: 2026.3.8