🦞 OpenClaw 配置 VBCode.io 教程

OpenClaw 是一个开源（MIT 许可）的自托管网关，可将 WhatsApp、Telegram、Discord、iMessage 等聊天应用连接到 AI 编码代理，支持多代理路由、工具使用和会话记忆。更多信息请参考 OpenClaw 官网。本教程将指导你如何在 OpenClaw 中安装并配置 VBCode.io API。

快速导航

步骤 1：安装 OpenClaw
步骤 2：获取 API 密钥
步骤 3：配置 OpenClaw
步骤 4：启动并验证
步骤 5：对接 QQ（可选）
步骤 6：对接飞书（可选）
附录：配置字段说明

步骤 1：安装 OpenClaw

前置要求

需要 Node.js 22 或更高版本。验证方式：node --version

🍎 macOS / 🐧 Linux

方法一：官方安装脚本（推荐）

自动检测环境并安装所有依赖：

bash

curl -fsSL https://openclaw.ai/install.sh | bash

方法二：npm

bash

npm install -g openclaw@latest

方法三：pnpm

bash

pnpm add -g openclaw@latest
pnpm approve-builds -g

⊞ Windows

方法一：PowerShell 安装脚本（推荐）

powershell

iwr -useb https://openclaw.ai/install.ps1 | iex

方法二：npm（CMD / PowerShell 均可）

bash

npm install -g openclaw@latest

方法三：pnpm

bash

pnpm add -g openclaw@latest
pnpm approve-builds -g

初始化

安装完成后，运行初始化向导：

bash

openclaw onboard --install-daemon

提示

更多安装方式（Docker、从源码构建等）请参考 OpenClaw 官方文档。

步骤 2：获取 API 密钥

访问 VBCode.io 控制台，创建一个新的令牌：

点击「添加令牌」
名称：随便填写，方便自己区分即可
令牌分组：根据实际需要选择，分组有详细描述（必填项，不能留空）
额度建议：设置为无限额度

创建成功后，复制令牌备用。

步骤 3：配置 OpenClaw

配置文件位置

系统	路径
macOS / Linux	`~/.openclaw/openclaw.json`
Windows	`%USERPROFILE%\.openclaw\openclaw.json`

注意

如果文件不存在，可以手动创建。首次运行 openclaw doctor 也会自动生成默认配置。

VBCode.io 配置示例

在 openclaw.json 中添加或修改以下内容：

{
  "meta": {
    "lastTouchedVersion": "2026.2.3-1",
    "lastTouchedAt": "2026-02-06T10:08:26.053Z"
  },
  "wizard": {
    "lastRunAt": "2026-02-06T10:06:14.214Z",
    "lastRunVersion": "2026.2.3-1",
    "lastRunCommand": "doctor",
    "lastRunMode": "local"
  },
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      },
      "model": {
        "primary": "vbcode-claude/claude-opus-4-6"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "vbcode-claude": {
        "baseUrl": "https://www.vbcode.io",
        "apiKey": "你的API密钥",
        "api": "anthropic-messages",
        "headers": {
          "User-Agent": "claude-cli/2.0.76 (external, cli)",
          "Authorization": "Bearer 你的API密钥"
        },
        "models": [
          {
            "id": "claude-opus-4-6",
            "name": "claude-opus-4-6"
          }
        ]
      },
      "vbcode-codex": {
        "baseUrl": "https://www.vbcode.io/v1",
        "apiKey": "你的API密钥",
        "api": "openai-completions",
        "headers": {
          "User-Agent": "codex_cli_rs/0.77.0 (Windows 10.0.26100; x86_64) WindowsTerminal",
          "Authorization": "Bearer 你的API密钥"
        },
        "models": [
          {
            "id": "gpt-5.2-codex",
            "name": "gpt-5.2-codex"
          }
        ]
      }
    }
  },
  "messages": {
    "ackReactionScope": "group-mentions"
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto"
  },
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "保留默认值即可"
    },
    "mode": "local"
  }
}

重要提示

请将 "apiKey" 和 "headers.Authorization" 中的密钥替换为你在 VBCode.io 控制台生成的 API 密钥
Authorization 的格式为 Bearer 你的API密钥（注意 Bearer 后有一个空格）
"gateway.auth.token" 保留默认生成的值即可，无需修改
"agents.defaults.model.primary" 用于设置默认使用的 AI 模型
格式为 provider名称/模型ID，例如：
vbcode-claude/claude-opus-4-6 或 vbcode-codex/gpt-5.2-codex

关键配置说明

models.providers.vbcode-claude — Claude 模型配置：

字段	值	说明
`baseUrl`	`https://www.vbcode.io`	VBCode.io API 地址
`apiKey`	你的 API 密钥	从控制台获取
`api`	`anthropic-messages`	Anthropic 协议，用于 Claude 系列模型
`headers`	自定义请求头	详见下方说明
`models`	模型列表	需要使用的模型

models.providers.vbcode-codex — Codex 模型配置：

字段	值	说明
`baseUrl`	`https://www.vbcode.io`	VBCode.io API 地址
`apiKey`	你的 API 密钥	从控制台获取
`api`	`openai-completions`	OpenAI 协议，用于 GPT/Codex 系列模型
`headers`	自定义请求头	详见下方说明
`models`	模型列表	需要使用的模型

切换默认模型

修改 agents.defaults.model.primary 即可切换默认模型：

使用 Claude："vbcode-claude/claude-opus-4-6"
使用 Codex："vbcode-codex/gpt-5.2-codex"

格式为 provider名称/模型ID。

headers 配置说明

headers 用于自定义 HTTP 请求头：

User-Agent — 客户端标识，Claude 模型使用 claude-cli/...，Codex 模型使用 codex_cli_rs/...
Authorization — 认证头，值为 Bearer 你的API密钥（与 apiKey 填同一个密钥）

可用模型：访问 VBCode.io 模型广场查看所有可用模型。如需添加更多模型，在对应 provider 的 models 数组中追加即可。

步骤 4：启动并验证

配置完成后，先运行诊断命令检查配置是否正确：

bash

openclaw doctor

确认无误后，重启 gateway 使配置生效：

bash

openclaw gateway restart

然后启动 TUI 界面验证配置是否正常：

bash

openclaw tui

如果能正常对话，说明配置成功。

步骤 5：对接 QQ（可选）

如果你希望通过 QQ 与 OpenClaw 交互，可以按照以下步骤完成对接。OpenClaw 官方提供了 QQ 机器人接入页面，整个流程非常简单。

5.1 创建 QQ 机器人

访问 OpenClaw QQ 机器人接入页面，使用 QQ 账号登录
点击页面中的「创建机器人」按钮

创建机器人

5.2 复制机器人凭证

机器人创建成功后，页面会显示以下信息：

AppID — 机器人的唯一标识
AppSecret — 机器人的密钥

同时页面会展示 OpenClaw 原生接入流程，包含需要执行的命令。

复制相关信息

安全提示

AppSecret 是敏感信息，且不支持明文保存、二次查看。请在创建时立即复制并妥善保管。

5.3 在 OpenClaw 侧完成 QQ 配置

根据页面提示，依次执行以下命令：

bash

# 1. 安装 OpenClaw 社区 QQBot 插件
openclaw plugins install @sliverp/qqbot@latest

# 2. 配置绑定当前 QQ 机器人（token 值从页面复制）
openclaw channels add --channel qqbot --token "你的Token"

# 3. 重启网关使配置生效
openclaw gateway restart

5.4 两种安装方式

你可以选择以下任一方式执行上述命令：

方式一：通过 OpenClaw Gateway Dashboard 的聊天界面

直接在 OpenClaw 的 Web 管理界面中，将页面提供的信息和命令发送给 OpenClaw，它会自动执行安装和配置。

通过 Dashboard 聊天安装

方式二：通过已接入的 IM 渠道发送

如果你已经有其他 IM 渠道（如 Telegram、飞书等）连接到 OpenClaw，也可以直接通过该渠道将信息发送给 OpenClaw 完成安装。

通过 IM 发送安装

5.5 测试验证

配置完成后，即可在 QQ 中测试：

在 QQ 中找到你创建的机器人
发送一条消息，确认机器人能正常响应
支持 Markdown、图片、语音、文件等多媒体消息收发
手机端 QQ、桌面端 QQ 均可使用

QQ 对接常见问题

问题	可能原因	解决方案
机器人无响应	网关未启动或 token 配置错误	运行 `openclaw status` 检查状态，确认 token 正确
插件安装失败	网络问题或版本不兼容	检查网络连接，尝试 `openclaw plugins install @sliverp/qqbot@latest` 重新安装
消息发送失败	QQ 机器人权限不足	检查 QQ 开放平台上机器人的权限配置

步骤 6：对接飞书（可选）

如果你希望通过飞书与 OpenClaw 交互，可以按照以下步骤完成对接。

6.1 登录飞书开放平台

访问飞书开放平台，使用飞书账号登录
需要企业管理员或具备开发者权限的账号
进入「开发者后台」

6.2 创建企业自建应用

点击「创建企业自建应用」
填写应用信息：
- 应用名称（如 OpenClaw 助手）
- 应用描述（如 基于 OpenClaw 的 AI 智能助手）
- 应用图标（上传一张辨识度高的图标）
确认创建

6.3 获取应用凭证

进入刚创建的应用，点击左侧菜单「凭证与基础信息」
记录以下两个值（后续配置 OpenClaw 时需要）：
- App ID（格式类似 cli_a90f701cf9f99bd8）
- App Secret

安全提示

App Secret 是敏感信息，请妥善保管，不要泄露或提交到代码仓库。

6.4 添加机器人能力

在左侧菜单找到「应用能力」→「机器人」
点击开启机器人能力
可自定义机器人的名称和描述

6.5 配置应用权限

有两种方式，任选其一。

方式一：JSON 批量导入（推荐）

在左侧菜单点击「权限管理」
找到页面右上角的「批量导入」按钮
粘贴以下 JSON 并确认导入：

json

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "event:ip_list",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "cardkit:card:write",
      "im:resource"
    ],
    "user": [
      "aily:file:read",
      "aily:file:write",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

导入后，检查权限列表，如果有「申请」按钮的权限，点击逐一申请
企业自建应用的权限通常会自动通过审批

方式二：手动逐个开通

在「权限管理」中搜索并开通以下权限：

权限标识	说明	必要性
`im:message`	消息基础权限	必须
`im:message.p2p_msg:readonly`	接收用户私聊消息	必须
`im:message.group_at_msg:readonly`	接收群聊中 @机器人的消息	必须
`im:message:send_as_bot`	以机器人身份发送消息	必须
`im:message:readonly`	获取历史消息	必须
`im:resource`	消息中的资源（图片/文件）读取	必须
`im:chat.access_event.bot_p2p_chat:read`	机器人单聊事件访问	必须
`im:chat.members:bot_access`	获取机器人所在群的成员信息	必须
`cardkit:card:write`	发送交互卡片消息	必须
`application:application.app_message_stats.overview:readonly`	应用消息统计	推荐
`application:application:self_manage`	应用自管理	推荐
`application:bot.menu:write`	配置机器人菜单	推荐
`contact:user.employee_id:readonly`	读取用户工号	推荐
`aily:file:read`	AI 文件读取	推荐
`aily:file:write`	AI 文件写入	推荐
`corehr:file:download`	核心人事文件下载	可选
`event:ip_list`	事件 IP 白名单	可选

6.6 配置事件订阅

在左侧菜单找到「事件与回调」→「事件配置」
订阅方式选择「使用长连接接收事件」（推荐）
点击「添加事件」，搜索并添加 im.message.receive_v1（即「接收消息 v2.0」）

为什么推荐长连接模式？

不需要公网 IP、域名或内网穿透工具，本地即可调试
SDK 自动处理加密传输和鉴权，无需手动解密或验签
集成成本低，几分钟就能跑通

长连接限制

仅支持企业自建应用，商店应用不可用
消息必须在 3 秒内处理完成，否则触发超时重推
单应用最多 50 个连接
多客户端部署时为集群模式（非广播），只有一个客户端收到消息

6.7 创建版本并发布

必须先发布才能使用

飞书自建应用的权限和事件订阅配置，必须创建版本并发布后才会生效。未发布的应用在飞书客户端中搜索不到，也无法正常收发消息。长连接配置也需要应用发布后才能保存，否则会报错。

进入飞书开放平台「版本管理与发布」
点击「创建版本」，填写版本说明（如 OpenClaw AI 助手 v1.0）
设置应用的「可用范围」（至少添加自己或一个测试群）
点击「保存」→「申请发布」
等待企业管理员审核通过（企业自建应用通常审核较快）

注意

每次权限变更或事件订阅修改后，都需要创建新版本并重新发布，否则变更不会生效。建议在所有配置完成后统一发布，减少反复提审。

6.8 在 OpenClaw 侧完成飞书配置

飞书应用发布成功后，再配置 OpenClaw 侧并启动网关：

bash

# 1. 安装飞书插件
openclaw plugins install feishu-openclaw

# 2. 启用飞书通道并配置凭证
openclaw config set channels.feishu.enabled true --json
openclaw config set channels.feishu.appId "你的AppID"
openclaw config set channels.feishu.appSecret "你的AppSecret"

# 3. 重启网关使配置生效
openclaw gateway restart

# 4. 验证状态
openclaw status
# 预期输出：Feishu | ON | OK | configured

配置顺序很重要

正确顺序：先在飞书开放平台完成所有配置并发布应用 → 再配置 OpenClaw 并启动网关。飞书在建立 WebSocket 长连接时会验证应用凭证和发布状态，如果应用未发布或网关未启动，长连接将无法建立。

6.9 测试验证

发布审核通过且 OpenClaw 网关启动后，即可开始测试：

在飞书客户端搜索你的机器人名称，或将其添加到一个测试群
私聊机器人发送一条消息，确认能正常响应
在群聊中 @机器人发送消息，确认群聊场景也正常
测试图片、文件等富媒体消息的收发（如果需要）

飞书对接常见问题

问题	可能原因	解决方案
机器人无响应	网关未启动或凭证错误	运行 `openclaw status` 检查状态，确认 App ID / Secret 正确
群聊收不到消息	缺少 `im:message.group_at_msg:readonly` 权限	在权限管理中补充开通，重新发布版本
消息超时重复推送	处理时间超过 3 秒	优化处理逻辑，或检查 LLM API 响应速度
权限变更不生效	未重新发布应用版本	创建新版本并申请发布
长连接建立失败	应用未发布或网关未启动	确认飞书应用已发布且审核通过，然后确认 OpenClaw 网关已启动（`openclaw status`）

附录：配置字段说明

字段	说明	是否必填
`agents.defaults.model.primary`	默认使用的模型，格式：`provider/model-id`	是
`agents.defaults.maxConcurrent`	最大并发 agent 数	否（默认 4）
`agents.defaults.subagents.maxConcurrent`	最大并发子 agent 数	否（默认 8）
`agents.defaults.compaction.mode`	上下文压缩模式	否（默认 safeguard）
`models.mode`	模型合并模式	否（默认 merge）
`models.providers.<name>.baseUrl`	API 服务地址	是
`models.providers.<name>.apiKey`	API 密钥	是
`models.providers.<name>.api`	API 协议类型	是
`models.providers.<name>.headers`	自定义请求头	是
`models.providers.<name>.models`	可用模型列表	是
`gateway.mode`	gateway 运行模式	否（默认 local）
`gateway.auth.mode`	gateway 鉴权模式	否
`gateway.auth.token`	gateway 鉴权 token	否

🦞 OpenClaw 配置 VBCode.io 教程 ​

步骤 1：安装 OpenClaw ​

🍎 macOS / 🐧 Linux ​

⊞ Windows ​

初始化 ​

步骤 2：获取 API 密钥 ​

步骤 3：配置 OpenClaw ​

配置文件位置 ​

VBCode.io 配置示例 ​

关键配置说明 ​

步骤 4：启动并验证 ​

步骤 5：对接 QQ（可选） ​

5.1 创建 QQ 机器人 ​

5.2 复制机器人凭证 ​

5.3 在 OpenClaw 侧完成 QQ 配置 ​

5.4 两种安装方式 ​

5.5 测试验证 ​

QQ 对接常见问题 ​

步骤 6：对接飞书（可选） ​

6.1 登录飞书开放平台 ​

6.2 创建企业自建应用 ​

6.3 获取应用凭证 ​

6.4 添加机器人能力 ​

6.5 配置应用权限 ​

方式一：JSON 批量导入（推荐） ​

方式二：手动逐个开通 ​

6.6 配置事件订阅 ​

6.7 创建版本并发布 ​

6.8 在 OpenClaw 侧完成飞书配置 ​

6.9 测试验证 ​

飞书对接常见问题 ​

附录：配置字段说明 ​

🦞 OpenClaw 配置 VBCode.io 教程

步骤 1：安装 OpenClaw

🍎 macOS / 🐧 Linux

⊞ Windows

初始化

步骤 2：获取 API 密钥

步骤 3：配置 OpenClaw

配置文件位置

VBCode.io 配置示例

关键配置说明

步骤 4：启动并验证

步骤 5：对接 QQ（可选）

5.1 创建 QQ 机器人

5.2 复制机器人凭证

5.3 在 OpenClaw 侧完成 QQ 配置

5.4 两种安装方式

5.5 测试验证

QQ 对接常见问题

步骤 6：对接飞书（可选）

6.1 登录飞书开放平台

6.2 创建企业自建应用

6.3 获取应用凭证

6.4 添加机器人能力

6.5 配置应用权限

方式一：JSON 批量导入（推荐）

方式二：手动逐个开通

6.6 配置事件订阅

6.7 创建版本并发布

6.8 在 OpenClaw 侧完成飞书配置

6.9 测试验证

飞书对接常见问题

附录：配置字段说明