什么是 OpenClaw

OpenClaw 是一款开源的本地 AI 助手，运行在你自己的电脑上，可通过 Web UI、Telegram、WhatsApp、Discord 等多种方式交互，实现文件操作、终端命令执行、浏览器控制等自动化任务。

前置要求

• macOS 12 (Monterey) 或更高版本
• Node.js 环境（版本 22 或更高）
• 有效的 UniVibe API 密钥

安装步骤

1. 安装 Node.js 环境

OpenClaw 需要 Node.js 22 或更高版本才能运行。

方法一：使用 Homebrew（推荐）

如果你已经安装了 Homebrew，可以使用以下命令：

brew install node@22

如果还没有安装 Homebrew，可以先安装它：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

方法二：官网下载

1. 访问 https://nodejs.org/
2. 点击 “LTS” 版本进行下载（确保版本 ≥ 22）
3. 下载完成后运行 .pkg 安装程序
4. 按照安装向导完成安装

验证 Node.js 安装

安装完成后，打开终端，输入以下命令：

node --version
npm --version

如果显示版本号（node 版本需 ≥ 22），说明安装成功了！

2. 安装 OpenClaw

打开终端，运行以下命令：

npm install -g openclaw

这个命令会从 npm 官方仓库下载并安装最新版本的 OpenClaw。

验证 OpenClaw 安装

安装完成后，输入以下命令检查是否安装成功：

openclaw --version

如果显示版本号，恭喜你！OpenClaw 已经成功安装了。

3. 获取 API 密钥

点击获取

4. 运行安装向导

首次使用 OpenClaw，建议运行安装向导：

openclaw onboard --install-daemon

向导配置选项说明

向导会逐步引导你完成配置，以下是每个步骤的建议选择：

步骤	建议选择
Risk 确认	选择 yes 继续
Onboarding mode	推荐选择 QuickStart，快速完成基础配置
Model/auth provider	选择 Skip for now（稍后手动配置 UniVibe）
Filter models by provider	选择 All providers
Default model	选择 Keep current
Select channel	选择 Skip for now，后续再配置
Configure skills	推荐选择 Yes，启用本地实用技能
Preferred node manager for skill installs	选择 npm
Install missing skill dependencies	选择 Skip for now
各种 API Key 设置	没有的话选 No 或 Skip
Gateway service	选择 Install 或 Reinstall 安装 Gateway 服务
How to hatch your bot	推荐选择 Hatch in TUI 体验交互式界面

向导完成后

向导完成后，OpenClaw 会自动启动 Gateway 服务并打开 Web 控制页面。

默认访问地址： http://127.0.0.1:18789

如果页面没有自动打开，可以手动在浏览器中访问上述地址。

💡 提示： 向导会自动创建配置文件，你可以在后续步骤中修改它来接入 UniVibe。

5. 配置 UniVibe 服务

OpenClaw 使用 JSON 配置文件，位于 ~/.openclaw/openclaw.json。

你可以通过修改配置文件或使用 GUI 界面来接入 UniVibe。

方式一：修改配置文件

打开配置文件

# 使用 VS Code 编辑
code ~/.openclaw/openclaw.json

# 或使用 nano 编辑
nano ~/.openclaw/openclaw.json

# 或使用 vim 编辑
vim ~/.openclaw/openclaw.json

配置内容

在配置文件中添加或修改以下内容：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "univibe-gpt/gpt-5.4"
      }
    }
  },
  "models": {
    "providers": {
      "univibe-claude": {
        "baseUrl": "https://api.univibe.cc/anthropic",
        "apiKey": "你的API密钥",
        "api": "anthropic-messages",
        "models": [
          { "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6" },
          { "id": "claude-opus-4-6", "name": "Claude Opus 4.6" }
        ]
      },
      "univibe-gpt": {
        "baseUrl": "https://api.univibe.cc/openai",
        "apiKey": "你的API密钥",
        "api": "openai-responses",
        "models": [
          { "id": "gpt-5.4", "name": "GPT-5.4" },
          { "id": "gpt-5.3-codex", "name": "GPT-5.3 Codex" }
        ]
      },
      "univibe-gemini": {
        "baseUrl": "https://api.univibe.cc/openai/v1",
        "apiKey": "你的API密钥",
        "api": "openai-completions",
        "models": [
          { "id": "gemini-3.1-pro-preview", "name": "Gemini 3.1 Pro" },
          { "id": "gemini-3-pro-preview", "name": "Gemini 3 Pro" }
        ]
      }
    }
  }
}

💡 记得将 你的API密钥 替换为在上方 API Keys 标签页中创建的实际密钥。

注意： 如果配置文件中已有其他内容（如 gateway、skills、wizard 等），请保留它们，只需添加或修改 agents 和 models 部分。

完整配置示例

以下是一个完整的配置文件示例：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "univibe-gpt/gpt-5.4"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      },
      "compaction": {
        "mode": "safeguard"
      },
      "workspace": "/Users/你的用户名/.openclaw/workspace"
    }
  },
  "gateway": {
    "mode": "local",
    "port": 18789,
    "bind": "loopback"
  },
  "models": {
    "providers": {
      "univibe-claude": {
        "baseUrl": "https://api.univibe.cc/anthropic",
        "apiKey": "你的API密钥",
        "api": "anthropic-messages",
        "models": [
          { "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6" },
          { "id": "claude-opus-4-6", "name": "Claude Opus 4.6" },
          { "id": "claude-opus-4-5-20251101", "name": "Claude Opus 4.5" },
          { "id": "claude-haiku-4-5-20251001", "name": "Claude Haiku 4.5" }
        ]
      },
      "univibe-gpt": {
        "baseUrl": "https://api.univibe.cc/openai",
        "apiKey": "你的API密钥",
        "api": "openai-responses",
        "models": [
          { "id": "gpt-5.4", "name": "GPT-5.4" },
          { "id": "gpt-5.3-codex", "name": "GPT-5.3 Codex" },
          { "id": "gpt-5.1-codex-max", "name": "GPT-5.1 Codex Max" }
        ]
      },
      "univibe-gemini": {
        "baseUrl": "https://api.univibe.cc/openai/v1",
        "apiKey": "你的API密钥",
        "api": "openai-completions",
        "models": [
          { "id": "gemini-3.1-pro-preview", "name": "Gemini 3.1 Pro" },
          { "id": "gemini-3-pro-preview", "name": "Gemini 3 Pro" },
          { "id": "gemini-3-flash-preview", "name": "Gemini 3 Flash" }
        ]
      }
    }
  }
}

方式二：GUI 界面配置

如果你更喜欢图形界面，可以在 Web 控制页面中配置：

1. 打开浏览器访问 http://127.0.0.1:18789
2. 进入 Config → Models → Providers
3. 依次添加以下三个 Provider：

Claude 系列（univibe-claude）

配置项	值
Api	anthropic-messages
Api Key	你的 UniVibe API 密钥
Base Url	https://api.univibe.cc/anthropic

GPT 系列（univibe-gpt）

配置项	值
Api	openai-responses
Api Key	你的 UniVibe API 密钥
Base Url	https://api.univibe.cc/openai

Gemini 系列（univibe-gemini）

配置项	值
Api	openai-completions
Api Key	你的 UniVibe API 密钥
Base Url	https://api.univibe.cc/openai/v1

4. 保存后配置立即生效

6. 配置说明

字段	说明
agents.defaults.model.primary	默认模型，格式为 provider名/模型名（如 univibe-gpt/gpt-5.4）
models.providers	自定义模型提供商配置，建议按模型系列分开配置
baseUrl	Claude 用 https://api.univibe.cc/anthropic，GPT 用 https://api.univibe.cc/openai，Gemini 用 https://api.univibe.cc/openai/v1
apiKey	你的 UniVibe API 密钥
api	Claude 用 anthropic-messages，GPT 用 openai-responses，Gemini 用 openai-completions
models	可用模型列表，包含 id 和 name

7. 启动服务

配置完成后，启动 Gateway 服务：

openclaw gateway start

8. 开始使用

方式一：Web UI（推荐）

最简单的使用方式，无需任何外部服务：

openclaw dashboard

浏览器会打开 http://127.0.0.1:18789/，直接在网页聊天窗口发消息即可。

方式二：Telegram Bot

1. 在 Telegram 搜索 @BotFather
2. 发送 /newbot 创建机器人
3. 获取 Bot Token
4. 在 openclaw onboard 时输入 Token

9. 可用模型（UniVibe）

你可以在配置文件的 models 数组中添加以下模型：

GPT 系列

模型 ID	名称	适用场景
gpt-5.4	GPT-5.4	最新通用模型，推荐默认使用
gpt-5.2	GPT-5.2	通用高性能模型
gpt-5.3-codex	GPT-5.3 Codex	高性能编程模型，复杂重构首选
gpt-5.2-codex	GPT-5.2 Codex	稳定编程模型
gpt-5.1-codex-max	GPT-5.1 Codex Max	大上下文编程模型
gpt-5.1-codex	GPT-5.1 Codex	通用编程模型
gpt-5.1-codex-mini	GPT-5.1 Codex Mini	轻量编程模型
gpt-5.1	GPT-5.1	通用模型
gpt-5	GPT-5	基础模型
gpt-5-codex	GPT-5 Codex	基础编程模型

Claude 系列

模型 ID	名称	适用场景
claude-opus-4-6	Claude Opus 4.6	最强推理能力，复杂任务首选
claude-sonnet-4-6	Claude Sonnet 4.6	均衡性能，日常开发推荐
claude-opus-4-5-20251101	Claude Opus 4.5	高性能推理模型
claude-haiku-4-5-20251001	Claude Haiku 4.5	快速响应，简单任务首选

Gemini 系列

模型 ID	名称	适用场景
gemini-3-pro-preview	Gemini 3 Pro	顶级性能，前端开发神器
gemini-3-flash-preview	Gemini 3 Flash	性价比首选，日常开发

10. 切换模型

在聊天窗口中使用 /model 命令切换模型：

/model univibe-claude/claude-opus-4-6

或者修改配置文件中的 agents.defaults.model.primary 字段。

常用命令

终端命令

命令	功能
openclaw onboard	运行安装向导
openclaw gateway start	启动 Gateway 服务
openclaw gateway restart	重启 Gateway 服务
openclaw gateway stop	停止 Gateway 服务
openclaw status	查看运行状态
openclaw doctor	诊断配置问题
openclaw doctor --fix	自动修复配置问题
openclaw dashboard	打开 Web 控制面板
openclaw logs --follow	查看实时日志
openclaw configure	修改配置
openclaw update	更新到最新版本

聊天命令

命令	功能
/help	显示帮助
/new	开始新对话
/reset	重置对话
/stop	停止当前任务
/model <id>	切换模型
/status	查看状态
/skills	查看可用技能

macOS 常见问题解决

安装时提示权限错误

如果遇到权限问题，可以尝试：

sudo npm install -g openclaw

或者修复 npm 权限：

sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

找不到配置文件

配置文件位于 ~/.openclaw/openclaw.json，可以使用以下命令查看：

ls -la ~/.openclaw/
cat ~/.openclaw/openclaw.json

Gateway 启动失败

1. 检查端口 18789 是否被占用：

lsof -i :18789

2. 如果端口被占用，可以在配置文件中修改 gateway.port

Node.js 版本过低

OpenClaw 需要 Node.js 22+，检查版本：

node --version

如果版本低于 22，使用 Homebrew 更新：

brew upgrade node

Homebrew 安装的 Node.js 找不到

如果使用 brew install node@22 安装，可能需要添加到 PATH：

echo 'export PATH="/opt/homebrew/opt/node@22/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc