简体中文

English

简体中文

English

Appearance

飞书集成实战 ​

飞书是目前国内最适合接入 Hermes Agent 的平台之一。本章从头到尾演示一次完整的飞书接入，包括踩坑和优化。

场景描述 ​

你在公司使用飞书，想把 Hermes Agent 接入为团队机器人，让团队成员可以通过飞书使用 AI 能力。

前置准备 ​

  • ✅ 飞书账号（有开放平台权限）
  • ✅ Hermes Agent 已安装
  • ✅ Gateway 已配置

基础配置 ​

飞书是国内企业协作的主流平台。Hermes 通过飞书开放平台的 WebSocket 长连接接收消息，无需暴露公网 webhook URL，即可在私聊和群聊场景中使用。

创建飞书应用 ​

  1. 打开 飞书开放平台，登录后点击「创建企业自建应用」
  2. 填写应用名称（比如"我的 AI 墨鱼"）、描述，选择应用图标
  3. 进入应用详情页 →「凭证与基础信息」，复制并保管 App ID（格式 cli_xxx）和 App Secret

安全提醒

App Secret 务必保密，不要提交到代码仓库或公开渠道。如不慎泄露，请立即在开放平台重置。

Lark（国际版）用户：访问 open.larksuite.com/app，并在后续配置中将 FEISHU_DOMAIN 设为 lark。

配置应用权限 ​

进入应用的「权限管理」页面，点击「批量导入」，粘贴以下 JSON：

json
{
  "scopes": {
    "tenant": [
      "im:message",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:message.p2p_msg:readonly",
      "im:message.group_at_msg:readonly",
      "im:resource",
      "im:chat",
      "im:chat:readonly",
      "im:chat.members:bot_access",
      "im:chat.access_event.bot_p2p_chat:read",
      "contact:user.base:readonly",
      "contact:user.employee_id:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:read",
      "cardkit:card:write"
    ],
    "user": [
      "im:message",
      "im:message:readonly",
      "im:chat",
      "im:chat:readonly",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

以上权限覆盖消息收发、群聊管理、联系人读取、卡片消息等核心功能。部分权限可能因飞书版本差异导入失败，跳过即可，不影响核心消息功能。

启用机器人能力 & 配置事件订阅 ​

  1. 进入「应用能力」→「机器人」，开启机器人能力，设置机器人名称和描述
  2. 进入「事件订阅」页面：
    • 选择「使用长连接接收事件」（WebSocket 模式）
    • 添加事件：im.message.receive_v1

注意

确保你已完成 Hermes 侧的配置并启动了 Gateway，否则长连接设置可能无法保存。

发布应用 ​

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

安装依赖 ​

关键：venv 与系统 Python

Hermes 二进制文件使用项目 venv 内的 Python 解释器。所有 pip 安装都必须指向 venv，否则安装的包对 Hermes 不可见。

bash
# 源码安装的用户
/path/to/hermes-agent/venv/bin/pip install lark_oapi websockets python-socks

# 一键安装脚本的用户
hermes pip install lark_oapi websockets python-socks
已知问题：python-socks 缺失

如果系统环境设置了 SOCKS 代理变量（如 ALL_PROXY），Lark SDK 在导入时会要求 python-socks 包。如果未安装到 venv，Gateway 启动将失败：

[Lark] [ERROR] connect failed, err: python-socks is required to use a SOCKS proxy

解决方案：确认安装到正确的 Python 环境——venv/bin/pip install python-socks，而不是系统 pip。

配置 Hermes ​

方式 A：交互式配置

bash
hermes gateway
# 选择 Feishu / Lark
# 按提示填入 App ID、App Secret
# 选择 WebSocket 模式

方式 B：手动配置

编辑 ~/.hermes/.env，添加：

bash
# 飞书 / Lark 基础配置
FEISHU_APP_ID=cli_xxxxxxxxxx         # 替换为你的 App ID
FEISHU_APP_SECRET=your_app_secret    # 替换为你的 App Secret
FEISHU_DOMAIN=feishu                 # feishu（国内）或 lark（国际版）
FEISHU_CONNECTION_MODE=websocket     # 推荐 WebSocket 长连接模式

# 用户访问控制
GATEWAY_ALLOW_ALL_USERS=true         # 测试阶段：允许所有用户
# 生产环境请改为 false，并配置白名单：
# FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy  # 用户的 open_id，逗号分隔

启动 Gateway ​

bash
hermes gateway start

启动后检查日志，确认 WebSocket 连接建立：

bash
tail -f ~/.hermes/logs/gateway.log

成功的日志应包含：

[Lark] [INFO] connected to wss://msg-frontier.feishu.cn/ws/v2?...

在飞书中搜索你的机器人名称，发一条消息测试。如果墨鱼回复了，说明连接成功！

设置 Home Chat ​

/set-home

之后所有 Cron 任务结果都会发到这个聊天。

进阶：群聊配置 ​

将机器人拉入群聊后，配置群聊策略：

bash
# ~/.hermes/.env
# always: 响应群聊中所有 @机器人 的消息
# mention_only: 仅响应 @机器人
FEISHU_GROUP_POLICY=always

机器人名自动发现

为了精确检测 @mention，Hermes 需要知道机器人的名字。授予 application:application:self_manage 权限后，启动时会自动获取。也可以手动设置：

bash
FEISHU_BOT_NAME=我的AI墨鱼

常见问题与解决 ​

问题 1：WebSocket 连接后立即断开 ​

原因：App Secret 错误或权限未开通

解决：

  1. 确认 App Secret 复制完整（无多余空格）
  2. 检查「获取与发送消息」权限是否已审批通过
  3. 确认应用已发布（未发布的应用无法使用）

问题 2：消息发送成功但收不到回复 ​

原因：LLM Provider 未配置或 API Key 失效

解决：

bash
hermes doctor
hermes model    # 检查当前模型

问题 3：群聊中机器人不响应 ​

原因：FEISHU_GROUP_POLICY 配置不当，或机器人名不匹配

解决：

  1. 检查 FEISHU_GROUP_POLICY 设置
  2. 确保群聊中确实 @ 了机器人
  3. 检查机器人名自动发现是否成功

问题 4：代理环境下连接失败 ​

原因：飞书 SDK 不走系统代理

解决：

bash
# 确保 python-socks 已安装到 venv
venv/bin/pip install python-socks

# 设置代理环境变量
HTTPS_PROXY=http://127.0.0.1:7890
HTTP_PROXY=http://127.0.0.1:7890

生产环境优化 ​

用户权限管理 ​

bash
# 从 ALLOW_ALL 切换到指定用户
GATEWAY_ALLOW_ALL_USERS=false
FEISHU_ALLOWED_USERS=ou_user1,ou_user2,ou_user3

# 或启用 DM 配对系统（更安全）
# 不设 ALLOW_ALL，让新用户通过配对码加入

Webhook 加密（仅 Webhook 模式） ​

bash
FEISHU_ENCRYPT_KEY=xxxxxxxx        # 事件订阅页获取
FEISHU_VERIFICATION_TOKEN=***     # 双重验证

消息格式优化 ​

在 config.yaml 中调整消息显示：

yaml
display:
  tool_progress: true
  background_process_notifications: true

运维命令速查 ​

bash
hermes gateway start      # 启动后台服务
hermes gateway stop       # 停止服务
hermes gateway restart    # 重启服务
hermes gateway status     # 查看状态
hermes doctor             # 健康检查
hermes doctor --fix       # 自动修复问题
tail -f ~/.hermes/logs/gateway.log  # 实时日志

深入阅读 ​

基于 CC BY-NC-SA 4.0 发布 | GitHub

© 2025-present hello-hermes contributors