> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmax.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw + 飞书

> 在飞书上部署 OpenClaw 机器人，接入 AihubMax

## 概述

使用 OpenClaw 和 AihubMax 部署一个飞书（Lark）AI 聊天机器人。本集成可以让你的团队在飞书对话中直接与 AI 模型交互。

<Info>
  本指南假设你已完成基本的 [OpenClaw 手动安装](/zh/integration-guide/openclaw)。如果尚未安装，请先完成 OpenClaw 的配置。
</Info>

## 前置条件

<CardGroup cols={2}>
  <Card title="AihubMax API Key" icon="key">
    一个有效的 AihubMax API Key。
  </Card>

  <Card title="OpenClaw 实例" icon="server">
    一个运行中的 OpenClaw 实例（参见[手动安装](/zh/integration-guide/openclaw)）。
  </Card>

  <Card title="飞书开发者账号" icon="building">
    能够访问[飞书开放平台](https://open.feishu.cn/)（国际版访问 [Lark 开放平台](https://open.larksuite.com/)）。
  </Card>
</CardGroup>

## 配置步骤

<Steps>
  <Step title="第一步：创建飞书应用">
    1. 登录[飞书开放平台](https://open.feishu.cn/app)（国际版访问 [Lark 开放平台](https://open.larksuite.com/app)）。
    2. 点击 **创建应用** > **企业自建应用**。
    3. 填写应用名称和描述。
    4. 记录下 **App ID**（格式：`cli_xxx`）和 **App Secret**。
  </Step>

  <Step title="第二步：配置权限">
    在飞书开放平台中，进入 **权限管理** 页面，添加以下权限：

    | 权限                       | 说明         |
    | ------------------------ | ---------- |
    | `im:message`             | 读写消息       |
    | `im:message:send_as_bot` | 以机器人身份发送消息 |
    | `im:chat`                | 访问会话信息     |
    | `im:chat:readonly`       | 读取会话信息     |

    <Tip>
      你可以在飞书开放平台通过 JSON 批量导入权限，节省时间。
    </Tip>
  </Step>

  <Step title="第三步：开启机器人能力">
    1. 在应用设置中，进入 **应用能力** > **机器人**。
    2. 启用机器人能力。
  </Step>

  <Step title="第四步：配置事件订阅">
    1. 进入 **事件订阅** 页面。
    2. 连接方式选择 **「使用长连接」**（WebSocket）。
    3. 添加事件：`im.message.receive_v1`（接收消息）。

    <Info>
      使用 WebSocket 长连接意味着你不需要公网 URL 或 SSL 证书——连接由你的服务器主动发起。
    </Info>
  </Step>

  <Step title="第五步：安装飞书插件">
    安装 OpenClaw 飞书插件：

    ```bash theme={null}
    openclaw plugins install @openclaw/feishu
    ```
  </Step>

  <Step title="第六步：配置 OpenClaw">
    将飞书配置添加到 `~/.openclaw/openclaw.json`：

    ```json theme={null}
    {
      "plugins": {
        "entries": {
          "feishu": {
            "enabled": true
          }
        }
      },
      "channels": {
        "feishu": {
          "enabled": true,
          "dmPolicy": "pairing",
          "accounts": {
            "main": {
              "appId": "cli_xxx",
              "appSecret": "your-app-secret",
              "botName": "我的 AI 助手"
            }
          }
        }
      }
    }
    ```

    <Warning>
      飞书凭证配置在 `channels.feishu.accounts` 下，**不是**在 `plugins.entries.feishu` 下。
    </Warning>

    你也可以通过环境变量设置：

    ```bash theme={null}
    export FEISHU_APP_ID="cli_xxx"
    export FEISHU_APP_SECRET="your-app-secret"
    ```

    <Note>
      Lark 国际版用户需要在账户配置中添加 `"domain": "lark"`。
    </Note>
  </Step>

  <Step title="第七步：发布并测试">
    1. 在飞书开放平台点击 **发布** 使机器人可用。
    2. 将机器人添加到飞书群聊，或与其开始私聊。
    3. 发送测试消息，如 **"你好！"**
    4. 机器人应该通过 AihubMax 配置的 AI 模型进行回复。
  </Step>
</Steps>

## 验证连接

向你的飞书机器人发送消息：

```
你是谁？你正在使用什么模型？
```

机器人应该通过 AihubMax 配置的 AI 模型返回回复。

## 常见问题

<AccordionGroup>
  <Accordion title="机器人在飞书中不回复">
    * 确认配置中的 `appId` 和 `appSecret` 正确。
    * 检查应用是否已发布并通过审核。
    * 确认已订阅 `im.message.receive_v1` 事件。
    * 检查 OpenClaw 日志中是否有错误信息。
  </Accordion>

  <Accordion title="权限不足错误">
    * 确认已在飞书开放平台授予所有必需权限。
    * 部分权限需要管理员审批——检查审批状态。
    * 添加权限后可能需要重新发布应用。
  </Accordion>

  <Accordion title="插件未加载">
    * 确认飞书插件已安装：检查 `openclaw.json` 中的 plugins 部分。
    * 确保插件和频道都设置了 `"enabled": true`。
    * 修改配置后重启 OpenClaw 守护进程。
  </Accordion>

  <Accordion title="AI 模型错误">
    * 确认 AihubMax API Key 有效且余额充足。
    * 直接测试 API Key：
      ```bash theme={null}
      curl https://api.aihubmax.com/v1/models \
        -H "Authorization: Bearer sk-your-foxapi-api-key"
      ```
  </Accordion>
</AccordionGroup>