用Loong搭建飞书AI助手:火山引擎+飞书/Lark完整落地Playbook详解

原创2026-11-09 21:19:211,658 阅读

用Loong搭建飞书AI助手:火山引擎+飞书/Lark完整落地Playbook详解

本文带你用开源 AI Agent 框架 Loong,以火山引擎(Volcengine ARK)作为模型服务、飞书/Lark 作为对话入口,一步步搭建一个可长期运行的飞书AI助手。全程以图文 Playbook 形式展开,新手也能照着完成从安装到网关长驻的完整落地。

火山引擎 Volcengine 标志:Loong 飞书AI助手方案中负责模型推理的提供方

为什么是 Loong + 火山引擎 + 飞书?

这套组合来自 Loong 官方推荐的一条"完整落地"路径:火山引擎负责托管模型推理,飞书/Lark 负责团队对话入口,Loong 把两者粘合成一个可治理的 AI 助手运行时。

它适合你,如果:

  • ✅ 团队日常已经在用飞书或 Lark 办公
  • ✅ 想要"能收消息、能回复"的入站 AI 助手,而不只是发通知
  • ✅ 希望模型提供方(火山引擎)显式、透明,不藏在代理层后面

Loong 是一个用 Rust 构建的轻量 AI Agent 基础设施,内置 42+ 模型供应商、25+ 消息渠道,并且支持插件、技能、审批策略等扩展。核心特性与命令体系可以在 README.md 和 README.zh-CN.md 中查看。

💡 先记住一个原则:先让模型链路跑通,再接飞书通道。顺序反了排查成本会翻倍。

准备工作:一键安装Loong与准备ARK_API_KEY

安装 Loong

Loong 只有一个命令行入口 loong。推荐克隆源码后用自带安装脚本安装(scripts/install.sh):

git clone https://gitcode.com/gh_mirrors/lo/loong
cd loong
bash scripts/install.sh --source --onboard

--onboard 参数会在安装完成后直接进入引导式配置流程,把可用配置写入 ~/.loong/config.toml,不需要手写 TOML。安装细节见 installation.mdx。

准备火山引擎 API Key

到火山引擎控制台创建 ARK API Key,并将其导出为环境变量:

export ARK_API_KEY="your-ark-api-key"

Loong 的火山引擎 Provider 默认走 https://ark.cn-beijing.volces.com 的 OpenAI 兼容接口,认证方式为 Bearer Token,密钥变量默认就是 ARK_API_KEY。完整契约见 volcengine.mdx。

第1步:火山引擎Provider配置与模型连通性验证

在 config.toml 中启用火山引擎作为活动 Provider:

active_provider = "volcengine"

[providers.volcengine]
kind = "volcengine"
api_key = { env = "ARK_API_KEY" }
model = "auto"

三个易错点:

  1. api_key = { env = "ARK_API_KEY" } 表示"从环境变量读取密钥";写成 api_key = "ARK_API_KEY" 会把它当成密钥字面值,这是新手最常见的坑。
  2. model = "auto" 走供应商侧模型发现;若你的区域/账号下发现不稳定,可显式固定 model = "<model-id>"。
  3. 切换 Provider 只需改 active_provider 字段,或重跑 loong onboard。

然后跑一遍健康检查循环(命令含义与更多诊断路径见 doctor-and-health.mdx):

loong doctor
loong runtime models list
loong ask --message "确认当前活动模型服务是否健康。"

只有三条都通过,才进入下一步。⚠️ 如果 runtime models list 失败,先修模型链路,别急着配飞书。

第2步:飞书机器人扫码Onboard,免手工创建应用

Loong 提供了官方扫码注册流程,直接在终端里生成二维码,自动创建机器人应用,并把凭据写入配置文件:

# 国内飞书租户(open.feishu.cn,CLI 默认)
loong feishu onboard --domain feishu

# 国际 Lark 租户(open.larksuite.com)
loong feishu onboard --domain lark

两个细节:

  • --domain 必须和你登录的租户一致,选错会导致二维码流程无法绑定。
  • 扫码流程只会签发 app_id / app_secret,天然适配 websocket 长连接模式;若需要 webhook 回调凭据,用 loong feishu onboard --manual --mode webhook ... 手动补。

更完整的通道字段说明(必填项、环境指针、默认值)见 feishu.mdx。

第3步:飞书通道配置详解(websocket长连接模式)

首次落地推荐 websocket 模式——由运行时主动保持长连接,无需公网回调地址,也没有 webhook 验签材料的负担。

[feishu]
enabled = true
domain = "lark"            # 国内飞书通道改为 "feishu"
mode = "websocket"
receive_id_type = "chat_id"
app_id = { env = "LARK_APP_ID" }
app_secret = { env = "LARK_APP_SECRET" }
allowed_chat_ids = ["oc_ops_room"]

关键配置语义:

字段 说明
domain "lark" 走国际 Lark,"feishu" 走国内飞书,运行时契约同族
mode websocket 模式下不需要 verification_token 与 encrypt_key
allowed_chat_ids 信任边界:只有这些群/会话能被助手响应,请认真维护
require_mention 多机器人同群时设为 true,被 @ 才响应,避免抢答

webhook 模式则需要额外提供 webhook_bind、webhook_path、verification_token、encrypt_key,适合你明确想要平台回调自有本地监听的场景。

第4步:飞书AI助手冒烟测试三步验证法

任何改动之后,都跑这条最短验证链:

loong doctor
loong channels send feishu --target "ou_example_user" --text "hello from loong"
loong channels serve feishu
步骤 验证了什么
doctor Provider 与通道前置条件是否健康
channels send 当前账号能否主动发消息(出站)
channels serve feishu 入站回复循环能否稳定挂起、在指定群边界内应答

三条都稳定后,才算"基础循环"完成。此时你已经在飞书里拥有一个可对话的 AI 助手了。🎉

第5步:多账号与Gateway长驻运行(进阶)

当单账号跑稳之后,再引入多账号和网关托管,顺序不要颠倒。

先命名账号,再谈选择器

选择器 --channel-account lark=work 必须指向已配置的 accounts.<id> 条目:

[feishu]
enabled = true
mode = "websocket"
default_account = "work"
receive_id_type = "chat_id"

[feishu.accounts.work]
domain = "lark"
app_id = { env = "LARK_WORK_APP_ID" }
app_secret = { env = "LARK_WORK_APP_SECRET" }
allowed_chat_ids = ["oc_ops_room"]

两种运行形态

形态 命令 适用时机
前台单通道 loong channels serve feishu 初始落地、验证阶段
持久化托管 loong gateway run --channel-account lark=work 基础循环已验证通过

持久化形态的控制回路是:

loong gateway run --channel-account lark=work
loong gateway status --json
loong gateway stop

完整的属主契约、选择器规则与故障恢复诊断(gateway status --json + status --json 双视图)见 gateway-and-supervision.mdx。

常见问题排查清单

症状 应该先检查什么
runtime models list 失败,通道都顾不上 先修火山引擎 Provider 链路,别在模型不通时调试通道
websocket 模式却要求 webhook 验签材料 配置形态写错了;websocket 不应依赖 verification_token / encrypt_key
gateway run --channel-account lark=work 在单账号配置上失败 先补 default_account 与 accounts.work,或去掉选择器直接运行
发送正常但回复发到了错误的群 检查 allowed_chat_ids 与 receive_id_type,再谈托管切换
不确定运行时当前归谁所有 用另一个进程执行 loong gateway status --json

完整排查表同样收录在官方 Playbook 中:volcengine-feishu-lark-playbook.mdx。

结语:一条诚实的落地顺序

回顾这条飞书AI助手的完整路径,顺序本身就是方法论:

  1. 模型先行:火山引擎 Provider 健康(doctor / models list / ask 三连)
  2. 通道跟上:loong feishu onboard 扫码建号,websocket 长连接接入
  3. 验证再托管:冒烟测试三步法通过后,才升级到多账号与 gateway run 长驻

更多端到端组合(WeCom、Telegram、本地模型出站等)可以在 common-setups.mdx 中按场景选择对应 Playbook。Loong 的设计哲学是"透明、可控、可生长"——先把一个群里的助手跑稳,再让它在你的组织里长大。🐉

登录后查看全文
loong