OpenClaw 手动安装

按步骤安装 OpenClaw,完全掌控你的配置过程。

概述

OpenClaw 是一个开源的 AI agent 网关,在聊天应用与 AI agent 之间充当桥梁。通过一个集中的网关进程,它能够将 Telegram、WhatsApp、Discord、Feishu 等聊天平台对接到 AI 编程 agent。本文档介绍如何手动安装 OpenClaw,并将 Z-Mint AI API 配置为模型提供方。完成本文档后,你可以继续配置具体的聊天渠道(例如 Telegram 或 Feishu)。本指南涵盖:

安装并配置 OpenClaw 网关
将 Z-Mint AI API 配置为自定义模型提供方
验证安装结果

系统环境检查(可选)

正式安装前,建议先运行环境检查工具,确认系统满足 OpenClaw 的运行要求。

下载检查工具

从 GitHub Releases 下载与你的平台匹配的检查工具:

平台文件名Windowsopenclaw-checker-win-x64.exemacOS (Intel)openclaw-checker-macos-x64macOS (Apple Silicon)openclaw-checker-macos-arm64Linuxopenclaw-checker-linux-x64

检查项目

工具会自动检查以下项目:

✅ Node.js 版本(要求 >= 22.12.0)
✅ npm 可用
✅ Git 可用
✅ 网络连通性(github.com、npmjs.org、aigc.zhengmi.org)

检查通过示例如果检查失败,工具会给出具体的修复建议。

前置条件

开始配置前,请确认已完成以下准备工作:

1. 安装 Node.js

OpenClaw 通过 npm 安装,要求 Node.js 22 或更高版本。

Windows
macOS

访问 Node.js 官网,下载 Windows 安装包(.msi 文件)并运行安装程序。安装完成后,打开 PowerShell 进行验证:

node --version
npm --version

建议以管理员身份运行 PowerShell,以避免安装过程中出现权限问题。

方式一:使用安装包访问 Node.js 官网,下载 macOS 安装包(.pkg 文件)并运行安装程序。方式二:使用 Homebrew

brew install node

安装完成后,打开终端进行验证:

node --version
npm --version

如果安装过程中遇到权限问题,可能需要在命令前加上 sudo。

2. 获取 Z-Mint AI API Key

登录 Z-Mint AI 控制台
在控制台中找到 API Keys,点击「Create New Key」,然后复制生成的 Key
API Key 通常以 sk- 开头,请妥善保管

步骤 1:安装 OpenClaw

在终端中执行:

npm install -g openclaw@latest

安装完成后进行验证:

openclaw --version

步骤 2:初始化配置

运行 onboarding 命令,OpenClaw 会引导你完成初始化配置,并安装守护进程服务:

openclaw onboard --install-daemon

1. 确认安装

系统会提示安装风险告知,确认以继续:

2. 选择安装模式

系统会提示选择安装模式,选择 Quickstart:

3. 选择提供方

系统会提示选择模型提供方,这里选择 Skip,稍后我们会手动将 Z-Mint AI 配置为自定义提供方:

4. 选择模型

系统会提示选择要启用的模型,选择 All:

5. 选择默认模型

系统会提示选择默认模型,选择 Keep current:

6. 选择渠道

系统会提示选择聊天渠道,建议选择 Skip for now,稍后再添加渠道:

7. 配置 Skills

系统会询问是否配置 Skills,建议选择 No,稍后再添加:

8. 启用 Hooks

系统会询问是否启用 Hooks,建议选择 session-memory:

9. 重启网关服务

系统会提示网关服务已安装,选择 Restart:

10. 启动机器人

系统会提示如何启动机器人,建议选择 Do this later:

步骤 3:配置 Z-Mint AI API 与模型切换

1. 定位两个配置文件(重要)

OpenClaw 的模型配置通常涉及两个文件:

Windows
macOS

openclaw.json:%USERPROFILE%\.openclaw\openclaw.json
models.json:%USERPROFILE%\.openclaw\agents\main\agent\models.json

openclaw.json:~/.openclaw/openclaw.json
models.json:~/.openclaw/agents/main/agent/models.json

直接打开:

open ~/.openclaw/openclaw.json
open ~/.openclaw/agents/main/agent/models.json

如果 models.json 中某个 provider 的 apiKey / baseUrl 非空,会覆盖 openclaw.json 中对应的值。建议两个文件保持一致。

2. 配置模型提供方

建议在 openclaw.json 中配置以下 provider(并同步到 models.json):

"models": {
  "providers": {
    "zmint-anthropic": {
      "api": "anthropic-messages",
      "baseUrl": "https://aigc.zhengmi.org",
      "apiKey": "Your Z-Mint AI API Key",
      "models": [
        { "id": "zmint/auto", "name": "Z-Mint AI Auto" },
        { "id": "claude-opus-4-7", "name": "Claude Opus 4.7" },
        { "id": "claude-opus-4-6", "name": "Claude Opus 4.6" },
        { "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6" },
        { "id": "claude-opus-4-5-20251101", "name": "Claude Opus 4.5" },
        { "id": "claude-opus-4-1-20250805", "name": "Claude Opus 4.1" },
        { "id": "claude-sonnet-4-5-20250929", "name": "Claude Sonnet 4.5" },
        { "id": "claude-sonnet-4-20250514", "name": "Claude Sonnet 4" },
        { "id": "claude-haiku-4-5-20251001", "name": "Claude Haiku 4.5" }
      ]
    },
    "zmint-google": {
      "api": "google-generative-ai",
      "baseUrl": "https://aigc.zhengmi.org/v1beta",
      "apiKey": "Your Z-Mint AI API Key",
      "models": [
        { "id": "zmint/auto", "name": "Z-Mint AI Auto" },
        { "id": "gemini-3.1-flash-lite-preview", "name": "Gemini 3.1 Flash Lite" },
        { "id": "gemini-3.1-pro-preview", "name": "Gemini 3.1 Pro" },
        { "id": "gemini-2.5-pro", "name": "Gemini 2.5 Pro" },
        { "id": "gemini-2.5-flash", "name": "Gemini 2.5 Flash" },
        { "id": "gemini-3-pro-preview", "name": "Gemini 3.0 Pro" },
        { "id": "gemini-3-flash-preview", "name": "Gemini 3.0 Flash" }
      ]
    },
    "zmint-openai": {
      "api": "openai-completions",
      "baseUrl": "https://aigc.zhengmi.org/v1",
      "apiKey": "Your Z-Mint AI API Key",
      "models": [
        { "id": "gpt-5.4", "name": "GPT-5.4" },
        { "id": "gpt-5.2", "name": "GPT-5.2" },
        { "id": "gpt-5.1", "name": "GPT-5.1" },
        { "id": "gpt-5.1-chat", "name": "GPT-5.1 Chat" },
        { "id": "gpt-5.1-thinking", "name": "GPT-5.1 Thinking" },
        { "id": "gemini-2.5-pro", "name": "Gemini 2.5 Pro (OpenAI SDK)" },
        { "id": "gemini-2.5-flash", "name": "Gemini 2.5 Flash (OpenAI SDK)" },
        { "id": "gemini-3-pro-preview", "name": "Gemini 3.0 Pro (OpenAI SDK)" },
        { "id": "gemini-3-flash-preview", "name": "Gemini 3.0 Flash (OpenAI SDK)" },
        { "id": "doubao-seed-2.0-pro", "name": "Doubao Seed 2.0 Pro" },
        { "id": "doubao-seed-2.0-lite", "name": "Doubao Seed 2.0 Lite" },
        { "id": "doubao-seed-2.0-mini", "name": "Doubao Seed 2.0 Mini" },
        { "id": "doubao-seed-2.0-code", "name": "Doubao Seed 2.0 Code" },
        { "id": "kimi-k2-thinking", "name": "Kimi K2 Thinking" },
        { "id": "kimi-k2-thinking-turbo", "name": "Kimi K2 Thinking Turbo" }
      ]
    }
  }
}

上述模型 ID 仅作示例,请使用你的 Z-Mint AI 账号中实际可用的模型。

对于 Gemini 场景,zmint-google.baseUrl 必须包含 /v1beta,即 https://aigc.zhengmi.org/v1beta。缺少该后缀可能会遇到 Forbidden (403) 错误。

3. 配置默认模型(支持快速切换)

在 agents.defaults 中设置默认模型。我们推荐使用 Smart Model Routing zmint/auto,它会根据请求自动选择合适的模型:

"agents": {
  "defaults": {
    "model": {
      "primary": "zmint-anthropic/zmint/auto"
    }
  }
}

Smart Model Routing(Z-Mint AI Auto):将模型 ID 设置为 zmint/auto,系统会根据请求的复杂度、长度和类型,从模型池中自动挑选合适的模型,无需手动切换 —— 适合大多数通用场景。详情参见 Z-Mint AI Auto 文档。

如果想指定具体模型,也可以手动切换:

智能路由:zmint-anthropic/zmint/auto(推荐)
Claude:zmint-anthropic/claude-opus-4-6
GPT:zmint-openai/gpt-5.2
Gemini:zmint-google/gemini-3.1-pro-preview
豆包:zmint-openai/doubao-seed-2.0-mini

4. 快速切换到 Z-Mint AI 模型(推荐)

完成 provider 配置后,推荐使用 CLI 命令进行模型切换,而不是手动编辑 JSON:

# 查看已配置的 Z-Mint AI OpenAI 兼容模型
openclaw models list --provider zmint-openai --plain

# 切换默认模型(示例:gpt-5.4)
openclaw models set zmint-openai/gpt-5.4

# 查看当前生效的模型
openclaw models status --plain

如果 models list --provider zmint-openai 没有显示你期望的模型,请检查 openclaw.json 和 models.json 中是否都配置了对应的 provider。

5. 重启并验证

配置完成后重启网关:

openclaw gateway restart

查看状态:

openclaw gateway status

发送一条测试消息,验证模型是否正常工作:

openclaw agent --agent main -m "hi" --json

常用命令

命令说明openclaw gateway status查看网关运行状态openclaw gateway restart重启网关服务openclaw gateway stop停止网关服务openclaw gateway start启动网关服务openclaw logs --follow实时查看网关日志openclaw plugins list查看已安装的插件

常见问题排查

问题解决方案npm 安装失败Windows:以管理员身份运行 PowerShell;macOS:在命令前加 sudo找不到配置文件确认 onboard 流程已完成,检查 ~/.openclaw/ 目录是否存在网关无法启动检查端口是否被占用,使用 openclaw gateway status 查看详细错误API Key 无效确认 API Key 复制无误,检查是否有多余的空格或引号模型配置未生效检查 openclaw.json 与 models.json 是否一致(models.json 可能会覆盖前者)Gemini 返回 Forbidden (403)检查 models.providers.zmint-google.baseUrl 是否为 https://aigc.zhengmi.org/v1beta(必须包含 /v1beta)切换后仍使用旧模型运行 openclaw models status --plain 确认当前模型,必要时执行 openclaw gateway restart 重启

后续步骤

OpenClaw 安装和 Z-Mint AI API 配置已完成。接下来你可以:

配置 Telegram 渠道:参考 OpenClaw + Telegram 文档
配置 Feishu 渠道:参考 OpenClaw + Feishu 文档
使用自动安装工具:参考 OpenClaw 自动安装文档