用Loong搭建飞书AI助手:火山引擎+飞书/Lark完整落地Playbook详解
用Loong搭建飞书AI助手:火山引擎+飞书/Lark完整落地Playbook详解
本文带你用开源 AI Agent 框架 Loong,以火山引擎(Volcengine ARK)作为模型服务、飞书/Lark 作为对话入口,一步步搭建一个可长期运行的飞书AI助手。全程以图文 Playbook 形式展开,新手也能照着完成从安装到网关长驻的完整落地。
为什么是 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"
三个易错点:
api_key = { env = "ARK_API_KEY" }表示"从环境变量读取密钥";写成api_key = "ARK_API_KEY"会把它当成密钥字面值,这是新手最常见的坑。model = "auto"走供应商侧模型发现;若你的区域/账号下发现不稳定,可显式固定model = "<model-id>"。- 切换 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助手的完整路径,顺序本身就是方法论:
- 模型先行:火山引擎 Provider 健康(
doctor/models list/ask三连) - 通道跟上:
loong feishu onboard扫码建号,websocket 长连接接入 - 验证再托管:冒烟测试三步法通过后,才升级到多账号与
gateway run长驻
更多端到端组合(WeCom、Telegram、本地模型出站等)可以在 common-setups.mdx 中按场景选择对应 Playbook。Loong 的设计哲学是"透明、可控、可生长"——先把一个群里的助手跑稳,再让它在你的组织里长大。🐉
