OpenClaw + Feishu

通过飞书（Lark）机器人驱动 OpenClaw。

概述

OpenClaw 是一个开源的 AI Agent 网关，充当聊天应用与 AI Agent 之间的桥梁。通过一个集中化的 Gateway 进程，它将 Telegram、WhatsApp、Discord、飞书（Lark）等聊天平台与 AI 编码 Agent 连接起来，让你可以直接在聊天窗口中进行 AI 编程交互。通过在 OpenClaw 中将 Z-Mint AI API 配置为自定义模型提供商，并接入飞书机器人，你就能在飞书中直接使用 Z-Mint AI 提供的 Claude 模型（例如 Claude 4.6 Opus、Claude 4.5 Sonnet、Claude 4.5 Haiku）进行 AI 辅助编码对话。飞书通道采用 WebSocket 长连接模式接收消息，无需公网 URL。本指南内容包括：

安装并配置 OpenClaw Gateway
创建具备机器人能力的飞书企业自建应用
将 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）

Check success example 如果检测失败，工具会给出具体的修复建议。

前置条件

在开始配置前，请确认你已准备好以下内容：

1. 安装 Node.js

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

Windows
macOS

访问 Node.js 官网，下载 Windows 安装包（.msi 文件）并运行安装程序。安装完成后，打开 PowerShell 验证：

node --version
npm --version

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

方式 1：使用安装包访问 Node.js 官网，下载 macOS 安装包（.pkg 文件）并运行安装程序。方式 2：使用 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- 开头

3. 准备飞书账号

你需要一个飞书企业账号，用于在飞书开放平台创建应用。

第 1 步：安装 OpenClaw

在终端中执行以下命令：

npm install -g openclaw@latest

安装飞书插件：

openclaw plugins install @openclaw/feishu

第 2 步：初始化引导

执行 onboarding 命令，OpenClaw 将引导你完成初始设置，并安装后台守护服务：

openclaw onboard --install-daemon

1. 确认安装

系统会显示一段风险提示信息，确认后继续：

2. 选择安装模式

当提示选择安装模式时，选择 Quickstart：

3. 选择模型提供商

当提示选择模型提供商时，选择 Skip。我们稍后会手动将 Z-Mint AI 配置为自定义提供商：

4. 选择启用的模型

当提示选择启用哪些模型时，选择 All：

5. 选择默认模型

当提示选择默认模型时，选择 Keep current：

第 3 步：创建飞书应用

1. 登录飞书开放平台

访问飞书开放平台，使用你的飞书账号登录。

如果你使用的是 Lark（国际版），请访问 https://open.larksuite.com/app，并在配置中设置 domain: "lark"。

2. 创建应用

点击创建企业自建应用，填写应用名称、描述并选择一个图标。 Create Application

3. 获取凭证

在凭证与基础信息页面，复制以下内容：

App ID（格式为 cli_xxx）
App Secret

请妥善保管 App Secret，不要向他人透露。

Get Credentials

4. 配置权限

在权限管理页面，点击批量导入，粘贴以下 JSON 以一次性导入所有所需权限：

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

Configure Permissions

5. 启用机器人能力

在左侧导航栏点击应用能力，找到 Bot 卡片，将菜单状态切换为已启用。启用后填写机器人名称和描述——用户在飞书中搜索机器人或与之聊天时会看到这些信息。 Enable Bot Capability

6. 配置事件订阅

在配置事件订阅之前，请确认：

已完成飞书通道的配置（见第 4 步）
Gateway 已经运行（可使用 openclaw gateway status 检查）

在事件订阅页面：

选择使用长连接接收事件（WebSocket 模式）
添加事件：im.message.receive_v1（接收消息）

如果 Gateway 未运行，或通道尚未添加，长连接的配置将无法保存。

Configure Event Subscriptions

7. 发布应用

进入版本管理与发布，创建版本，提交审核并发布。企业自建应用通常会自动审核通过。

第 4 步：配置 OpenClaw

OpenClaw 的配置集中保存在 ~/.openclaw/openclaw.json 中。其中有三个关键配置域：

plugins.entries.* — 控制加载哪些插件
channels.* — 控制通道连接以及账号凭证
models.providers.* — 控制模型提供商

1. 添加飞书通道

手动配置
CLI 命令

打开 ~/.openclaw/openclaw.json：启用飞书插件（plugins.entries）：

"plugins": {
  "entries": {
    "feishu": {
      "enabled": true
    }
  }
}

配置飞书通道凭证（channels.feishu）：

"channels": {
  "feishu": {
    "enabled": true,
    "dmPolicy": "pairing",
    "accounts": {
      "main": {
        "appId": "cli_xxx",
        "appSecret": "your-app-secret",
        "botName": "My AI Assistant"
      }
    }
  }
}

飞书凭证必须放在 channels.feishu.accounts 下，不要放在 plugins.entries.feishu 中。放错位置会导致 Unrecognized key 错误。

你也可以通过环境变量进行配置：

export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"

运行以下命令，选择 Feishu，并在提示时输入 App ID 和 App Secret：

openclaw channels add

较新版本的 OpenClaw 在使用该命令时可能存在配置冲突，建议手动配置。

2. 配置 Z-Mint AI API

在同一个 openclaw.json 中，找到 models 字段，将 Z-Mint AI 作为自定义模型提供商添加进去：

"models": {
  "providers": {
    "zmint-anthropic": {
      "api": "anthropic-messages",
      "baseUrl": "https://aigc.zhengmi.org",
      "apiKey": "your-zmint-api-key",
      "models": [
        { "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-zmint-api-key",
      "models": [
        { "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-zmint-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" }
      ]
    }
  }
}

请将 "your-zmint-api-key" 替换为你在 Z-Mint AI 控制台中获取的实际 API Key。

3. 配置默认模型

在 agents 字段中设置默认模型：

"model": {
  "primary": "zmint-anthropic/claude-opus-4-6"
}

4. 重启 Gateway

重启 OpenClaw Gateway 以使配置生效：

openclaw gateway restart

请始终使用 openclaw gateway restart，而不要手动再启动一个新进程，否则会出现端口冲突错误。

确认配置已正确加载：

openclaw gateway status

第 5 步：验证连接

1. 在飞书中找到机器人

打开飞书，搜索你创建的机器人名称，发起会话。

2. 获取配对码

向机器人发送任意消息，它会返回一个配对码。

3. 完成配对

打开一个新的终端窗口并运行：

openclaw pairing approve feishu <pairing-code>

将 <pairing-code> 替换为机器人返回的实际配对码，注意去掉尖括号 <>。

4. 测试连接

配对完成后，在飞书中向机器人发送一条消息：

你好，请介绍一下你自己

如果收到了 AI 的回复，说明集成已经完成。

访问控制

私聊访问

默认 dmPolicy: "pairing" —— 陌生用户会收到一个需要管理员审批的配对码：

openclaw pairing list feishu        # 查看待审批列表
openclaw pairing approve feishu <CODE>  # 审批通过

你也可以通过 channels.feishu.allowFrom 配置一个用户 Open ID 白名单。

群聊访问

群聊策略通过 channels.feishu.groupPolicy 控制：

"open" — 允许群里的所有用户（默认）
"allowlist" — 仅允许 groupAllowFrom 中的用户
"disabled" — 禁用群消息

默认情况下，机器人只在被 @ 时才会响应（requireMention: true）。

常用命令

命令说明openclaw gateway status检查 Gateway 状态openclaw gateway restart重启 Gateway 服务openclaw logs --follow实时查看日志openclaw pairing list feishu查看待处理的配对请求openclaw plugins list查看已安装的插件

故障排查

问题解决方法机器人在群里无响应检查是否 @ 了机器人；检查 groupPolicy 是否为 "disabled"机器人收不到消息检查应用是否已发布并通过审核；确认事件订阅已配置 im.message.receive_v1；确认已选择 WebSocket 长连接模式App Secret 泄露在飞书开放平台重置 App Secret，更新配置后重启 Gateway消息发送失败检查是否已授予 im:message:send_as_bot 权限；使用 openclaw logs --follow 查看日志