OpenClaw 飞书配置完全指南OpenClaw

发表于最近更新于最近

作者 Administrator

37~48 分钟 阅读

什么是 OpenClaw 飞书集成？

OpenClaw 是一个强大的 AI 助手框架，支持通过飞书机器人与用户交互。通过飞书集成，你可以：

在飞书私聊中与 AI 助手对话
在群组中 @机器人获取帮助
使用流式输出实时查看 AI 生成内容
管理文档、知识库等飞书资源
实现多 Agent 路由，不同用户对接不同助手

本文将详细介绍如何从零开始配置 OpenClaw 飞书机器人。

前置准备

1. 安装 OpenClaw

确保已安装 OpenClaw（推荐使用 pnpm）：

# 使用 pnpm 全局安装
pnpm add -g openclaw

# 验证安装
openclaw --version

2. 飞书账号

需要一个飞书企业账号（个人版不支持自建应用）
��要管理员权限创建应用
国际版用户使用 Lark（https://open.larksuite.com）

第一步：创建飞书应用

1. 访问飞书开放平台

国内版：https://open.feishu.cn/app
国际版（Lark）：https://open.larksuite.com/app

使用飞书账号登录。

2. 创建企业自建应用

点击 创建企业自建应用
填写应用信息：
- 应用名称：例如 "AI 助手"
- 应用描述：简要说��应用用途
- 应用图标：上传一个图标（可选）

3. 获取应用凭证

创建完成后，进入应用详情页，找到 凭证与基础信息 页面：

App ID：格式为 cli_xxx
App Secret：点击查看并复制

⚠️ 重要：App Secret 是敏感信息，请妥善保管，不要泄露给他人。

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: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"
    ]
  }
}

这些权限包括：

消息权限：接收和发送消息
文档权限：读写飞书文档
群组权限：管理群组和成员
机器人权限：机器人基础能力

5. 启用机器人能力

在 应用能力 > 机器人 页面：

点击 启用机器人
配置机器人名称（用户看到的名字）
可选：上传机器人头像

第二步：配置 OpenClaw

方式一：使用交互式向导（推荐）

运行以下命令，根据提示添加飞书渠道：

openclaw channels add

选择 Feishu，然后输入：

App ID：刚才复制的 cli_xxx
App Secret：刚才复制的密钥

向导会自动生成配置并保存到 ~/.openclaw/openclaw.json。

方式二：手动编辑配置文件

编辑 ~/.openclaw/openclaw.json，添加以下配置：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "accounts": {
        "main": {
          "appId": "cli_xxx",
          "appSecret": "你的App Secret",
          "botName": "AI 助手"
        }
      }
    }
  }
}

配置说明：

enabled: true - 启用飞书渠道
dmPolicy: "pairing" - 私聊需要配对授权（推荐）
accounts.main - 主账号配置
botName - 机器人显示名称

国际版（Lark）配置

如果使用 Lark（国际版），需要额外设置域名：

{
  "channels": {
    "feishu": {
      "domain": "lark",
      "accounts": {
        "main": {
          "appId": "cli_xxx",
          "appSecret": "你的App Secret"
        }
      }
    }
  }
}

第三步：配置事件订阅

⚠️ 重要提醒：在配置事件订阅前，必须先启动 OpenClaw 网关！

1. 启动 OpenClaw 网关

# 启动网关
openclaw gateway

# 或者在后台运行
openclaw gateway install

验证网关状态：

openclaw gateway status

应该看到类似输出：

✓ Gateway is running (PID: 12345)
✓ Feishu channel connected

2. 配置飞书事件订阅

回到飞书开放平台，进入 事件订阅 页面：

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

⚠️ 注意：

必须选择 长连接模式，不要选择 HTTP 回调
如果网关未启动，保存会失败
长连接模式无需配置公网 URL

第四步：发布应用

1. 创建版本

在 版本管理与发布 页面：

点击 创建版本
填写版本说明（例如 "v1.0.0 初始版本"）
点击保存

2. 提交审核

点击 申请发布
选择发布范围：
- 全员可见：所有企业成员可用
- 部分可见：指定部门或人员
提交审核

3. 等待审批

企业自建应用通常会自动通过
如果需要管理员审批，联系企业管理员

第五步：测试机器人

1. 在飞书中找到机器人

发布成功后，在飞书中搜索你的机器人名称，点击进入私聊。

2. 发送测试消息

发送一条消息，例如：

你好

3. 配对授权（首次使用）

如果配置了 dmPolicy: "pairing"，机器人会回复一个配对码，例如：

请管理员批准配对码：ABC123

在服务器上运行：

# 查看待审批列表
openclaw pairing list feishu

# 批准配对
openclaw pairing approve feishu ABC123

批准后，再次发送消息即可正常对话。

4. 验证功能

测试以下功能：

发送文本消息
发送图片
使用命令（如 /status）
查看流式输出效果

访问控制配置

私聊访问策略

OpenClaw 支持多种私聊访问策略：

1. 配对模式（推荐）

{
  "channels": {
    "feishu": {
      "dmPolicy": "pairing"
    }
  }
}

陌生用户首次对话会收到配对码
管理员批准后才能使用
适合企业内部使用

2. 白名单模式

{
  "channels": {
    "feishu": {
      "dmPolicy": "allowlist",
      "allowFrom": ["ou_xxx", "ou_yyy"]
    }
  }
}

仅允许指定用户对话
其他用户消息会被静默忽略
适合限制使用范围

3. 开放模式

{
  "channels": {
    "feishu": {
      "dmPolicy": "open",
      "allowFrom": ["*"]
    }
  }
}

允许所有人对话
无需配对或审批
适合公开服务

4. 禁用私聊

{
  "channels": {
    "feishu": {
      "dmPolicy": "disabled"
    }
  }
}

完全禁止私聊
仅支持群组使用

群组访问策略

1. 开放模式（默认）

{
  "channels": {
    "feishu": {
      "groupPolicy": "open"
    }
  }
}

允许所有群组使用
默认需要 @机器人才响应

2. 白名单模式

{
  "channels": {
    "feishu": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["ou_xxx", "ou_yyy"]
    }
  }
}

仅允许指定用户在群组中使用
其他用户的消息会被忽略

3. 禁用群组

{
  "channels": {
    "feishu": {
      "groupPolicy": "disabled"
    }
  }
}

完全禁止群组使用

群组 @提及配置

默认情况下，群组中需要 @机器人才会响应。可以为特定群组关闭此限制：

{
  "channels": {
    "feishu": {
      "groups": {
        "oc_xxx": {
          "requireMention": false
        }
      }
    }
  }
}

获取群组 ID：

在群组中 @机器人发消息
运行 openclaw logs --follow 查看日志
找到 chat_id 字段（格式为 oc_xxx）

高级功能配置

1. 流式输出

飞书支持通过交互式卡片实现流式输出，实时显示 AI 生成内容：

{
  "channels": {
    "feishu": {
      "streaming": true,
      "blockStreaming": true
    }
  }
}

streaming: true - 启用流式卡片输出
blockStreaming: true - 启用块级流式（更细粒度）

如需禁用流式输出（等待完整回复后一次性发送）：

{
  "channels": {
    "feishu": {
      "streaming": false
    }
  }
}

2. 消息引用

在群聊中，机器人可以引用用户的原始消息：

{
  "channels": {
    "feishu": {
      "replyToMode": "all",
      "groups": {
        "oc_xxx": {
          "replyToMode": "first"
        }
      }
    }
  }
}

replyToMode 选项：

"off" - 不引用原消息（私聊默认）
"first" - 仅第一条回复引用
"all" - 所有回复都引用（群聊默认）

⚠️ 注意：消息引用与流式输出不能同时使用。

3. 多 Agent 路由

一个飞书机器人可以对接多个不同的 Agent，根据用户或群组自动路由：

{
  "agents": {
    "list": [
      { "id": "main" },
      {
        "id": "tech-support",
        "workspace": "/home/user/tech-support",
        "agentDir": "/home/user/.openclaw/agents/tech-support/agent"
      },
      {
        "id": "sales-bot",
        "workspace": "/home/user/sales-bot",
        "agentDir": "/home/user/.openclaw/agents/sales-bot/agent"
      }
    ]
  },
  "bindings": [
    {
      "agentId": "main",
      "match": {
        "channel": "feishu",
        "peer": { "kind": "dm", "id": "ou_xxx" }
      }
    },
    {
      "agentId": "tech-support",
      "match": {
        "channel": "feishu",
        "peer": { "kind": "group", "id": "oc_tech_group" }
      }
    },
    {
      "agentId": "sales-bot",
      "match": {
        "channel": "feishu",
        "peer": { "kind": "dm", "id": "ou_yyy" }
      }
    }
  ]
}

匹配规则：

peer.kind: "dm" - 私聊
peer.kind: "group" - 群组
peer.id - 用户 Open ID（ou_xxx）或群组 ID（oc_xxx）

4. 多账号配置

管理多个飞书机器人：

{
  "channels": {
    "feishu": {
      "accounts": {
        "main": {
          "appId": "cli_xxx",
          "appSecret": "xxx",
          "botName": "主机器人"
        },
        "backup": {
          "appId": "cli_yyy",
          "appSecret": "yyy",
          "botName": "备用机器人",
          "enabled": false
        }
      }
    }
  }
}

飞书工具集成

OpenClaw 提供了丰富的飞书工具，可以直接操作飞书资源。

1. 安装飞书插件

openclaw plugins install @openclaw/feishu

2. 可用工具

安装后，AI 助手可以使用以下工具：

文档操作（feishu-doc）

读取文档内容
创建新文档
编辑文档
追加内容
管理文档块

云空间管理（feishu-drive）

列出文件和文件夹
创建文件夹
上传文件
下载文件
移动/删除文件

权限管理（feishu-perm）

查看文档权限
添加协作者
修改权限
移除协作者

知识库操作（feishu-wiki）

浏览知识库
读取 Wiki 页面
创建 Wiki 页面
编辑 Wiki 内容

3. 启用工具

在配置文件中启用需要的工具：

{
  "channels": {
    "feishu": {
      "tools": {
        "doc": true,
        "drive": true,
        "perm": true,
        "wiki": true
      }
    }
  }
}

4. 使用示例

用户可以直接在飞书中对话：

帮我创建一个文档，标题是"项目计划"

把这个文档分享给张三

列出我的云空间文件

AI 助手会自动调用相应的工具完成操作。

常用命令

网关管理

# 查看网关状态
openclaw gateway status

# 启动网关
openclaw gateway

# 后台运行网关
openclaw gateway install

# 停止网关
openclaw gateway stop

# 重启网关
openclaw gateway restart

# 查看实时日志
openclaw logs --follow

配对管理

# 查看待审批列表
openclaw pairing list feishu

# 批准配对
openclaw pairing approve feishu <配对码>

# 拒绝配对
openclaw pairing reject feishu <配对码>

渠道管理

# 添加渠道
openclaw channels add

# 列出所有渠道
openclaw channels list

# 删除渠道
openclaw channels remove feishu

故障排除

1. 机器人收不到消息

可能原因：

应用未发布或未审批通过
事件订阅配置错误
网关未启动
权限不足

解决方法：

检查应用发布状态
确认事件订阅选择了 长连接模式
运行 openclaw gateway status 检查网关状态
查看日志：openclaw logs --follow
确认权限配置完整

2. 机器人在群组中不响应

可能原因：

未 @机器人
群组策略禁用
用户不在白名单

解决方法：

确认是否 @了机器人
检查 groupPolicy 配置
如果使用白名单，确认用户在 groupAllowFrom 中
查看日志确认消息是否被接收

3. 配对码无法批准

可能原因：

配对码输入错误
配对码已过期
网关重启导致配对信息丢失

解决方法：

确认配对码拼写正确（区分大小写）
让用户重新发送消息获取新配对码
运行 openclaw pairing list feishu 查看当前待审批列表

4. App Secret 泄露

解决方法：

在飞书开放平台重置 App Secret
更新配置文件中的 appSecret
重启网关：openclaw gateway restart

5. 发送消息失败

可能原因：

缺少 im:message:send_as_bot 权限
应用未发布
网络问题

解决方法：

检查权限配置
确认应用已发布
查看详细错误日志

6. 流式输出不工作

可能原因：

streaming 配置为 false
模型不支持流式输出
网络延迟过高

解决方法：

确认配置：streaming: true
检查模型配置
查看日志确认是否有错误

最佳实践

1. 安全配置

✅ 使用 dmPolicy: "pairing" 或 "allowlist" 限制访问
✅ 定期轮换 App Secret
✅ 不要在公开仓库中提交配置文件
✅ 使用环境变量存储敏感信息

2. 性能优化

✅ 启用流式输出提升用户体验
✅ 合理配置消息分块大小（textChunkLimit）
✅ 限制媒体文件大小（mediaMaxMb）

3. 用户体验

✅ 配置友好的机器人名称和头像
✅ 设置欢迎消息（welcomeText）
✅ 在群组中使用消息引用增强上下文
✅ 为不同场景配置不同的 Agent

4. 运维管理

✅ 使用 openclaw gateway install 后台运行网关
✅ 定期查看日志排查问题
✅ 监控网关运行状态
✅ 备份配置文件

配置参考速查表

配置项	说明	默认值
`channels.feishu.enabled`	启用/禁用渠道	`true`
`channels.feishu.domain`	API 域名	`feishu`
`channels.feishu.dmPolicy`	私聊策略	`pairing`
`channels.feishu.allowFrom`	私聊白名单	-
`channels.feishu.groupPolicy`	群组策略	`open`
`channels.feishu.streaming`	启用流式输出	`true`
`channels.feishu.blockStreaming`	启用块级流式	`true`
`channels.feishu.replyToMode`	消息引用模式	`all`
`channels.feishu.textChunkLimit`	消息分块大小	`2000`
`channels.feishu.mediaMaxMb`	媒体大小限制（MB）	`30`

总结

通过本指南，你应该已经成功配置了 OpenClaw 飞书机器人。主要步骤回顾：

✅ 在飞书开放平台创建应用并获取凭证
✅ 配置应用权限和机器人能力
✅ 在 OpenClaw 中添加飞书渠道
✅ 启动网关并配置事件订阅
✅ 发布应用并测试功能
✅ 配置访问控制和高级功能

现在你可以：

在飞书中与 AI 助手对话
在群组中使用机器人
管理飞书文档和资源
实现多 Agent 路由
自定义访问控制策略

如果遇到问题，请参考 故障排除 章节，或查看 OpenClaw 官方文档：https://docs.openclaw.ai

祝你使用愉快！🎉

许可协议: CC BY 4.0