手把手教你用Clawdbot将Qwen3-VL接入飞书，打造企业智能助手

1. 学习目标与前置准备

1.1 你能学到什么

这是一篇真正能落地的企业级AI集成实战指南。不讲虚的架构图，不堆抽象概念，只聚焦一件事：如何把已在CSDN星图平台私有化部署好的Qwen3-VL:30B大模型，通过Clawdbot网关，稳稳当当地接进你每天都在用的飞书（Lark）里，变成一个会看图、能读表、懂上下文、随时待命的多模态智能助手。

学完本篇，你将能够：

• 在飞书工作台中直接打开自己的AI助手应用，像聊天一样发送文字或图片
• 让Qwen3-VL:30B实时分析你上传的截图、Excel表格、产品设计稿并给出专业反馈
• 完全掌控数据流向——所有图片、文字、对话都留在你的私有环境，不经过任何第三方服务器
• 避开公网IP、反向代理、SSL证书等传统Bot接入的“拦路虎”，用长连接模式实现内网直连
• 看懂每一步配置背后的逻辑，而不是机械复制粘贴命令

无论你是IT运维、企业数字化负责人，还是想给团队快速上线AI能力的开发者，这篇教程都能让你在2小时内完成从零到可用的完整链路。

1.2 前置准备

请确认你已完成以下两件事（这是本篇的前提，不是本篇内容）：

• 上篇已实践：已在CSDN星图AI云平台成功完成Qwen3-VL:30B:30B的私有化部署，并可本地调用（如通过curl或Python脚本验证过模型响应）
• 飞书管理员权限：拥有企业飞书账号的管理员或应用开发者权限，能登录飞书开放平台创建和配置自建应用

不需要你额外准备GPU服务器、公网域名或Nginx配置。镜像已预装Clawdbot、Qwen3-VL运行时及飞书插件，你只需完成飞书侧的配置和Clawdbot端的几条命令。

硬件环境参考（来自镜像实测）：

• GPU：单卡A100 40GB / A800 80GB（Qwen3-VL:30B对显存要求较高，建议≥40GB）
• CPU：20核以上
• 内存：240GB
• 系统盘：50GB（足够运行Clawdbot网关服务）

提示：如果你尚未完成上篇部署，建议先返回阅读《星图平台快速搭建Clawdbot：私有化本地Qwen3-VL:30B并接入飞书平台（上篇）》，本文默认你已拥有一个正在运行的Qwen3-VL服务地址（如 http://127.0.0.1:8000/v1/chat/completions）。

2. 飞书侧：创建专属企业应用（3分钟搞定）

2.1 创建应用并获取凭证

登录 飞书开放平台，点击左上角「创建应用」→「创建企业自建应用」。

• 应用名称：建议起一个简洁、有辨识度的名字，比如 Clawd智问、Qwen办公助手 或 多模态小助手。这个名字会直接显示在飞书工作台和群聊中。
• 应用描述：一句话说明用途，例如：“基于Qwen3-VL的私有化AI助手，支持图文理解与智能问答”。

填写完毕后，点击「创建」。系统会自动跳转至应用管理页。

关键一步：在左侧菜单栏找到「凭证与基础信息」，这里你会看到两个至关重要的字符串：

• App ID：一长串以 cli_ 开头的字母数字组合
• App Secret：一长串随机字符

请立即复制并保存到安全的地方（如密码管理器）。这两个值是飞书与你的Clawdbot之间建立信任关系的“钥匙”，后续配置中必须完全一致，且不可泄露。

2.2 开启机器人能力并发布初版

在应用管理页左侧导航栏，点击「添加应用能力」→「机器人」→「添加」。

添加成功后，页面会提示你需要“发布应用”才能启用机器人功能。此时不要急于发布，先做一件小事：点击顶部「版本管理」→「创建新版本」，填写版本号 1.0.0，描述写“初始版本，启用机器人基础能力”，然后提交。

为什么需要这一步？
飞书的权限和事件订阅配置，必须绑定在一个已发布的应用版本上。先创建一个空版本，是为了让后续的配置项有地方可依附。它就像一张空白的画布，我们接下来要往上面画内容。

3. Clawdbot端：三步完成飞书插件配置（无需改代码）

3.1 安装飞书专用连接器

Clawdbot的设计哲学是“开箱即用”。镜像已预装核心框架，你只需安装对应的渠道插件。

打开你的星图云服务器终端（SSH或Web Terminal），执行以下命令：

# 安装飞书官方兼容插件
clawdbot plugins install @m1heng-clawd/feishu

命令执行后，你会看到类似 ✔ Plugin @m1heng-clawd/feishu installed successfully 的提示。这个插件的作用，是让Clawdbot能听懂飞书发来的消息格式（如JSON结构），也能按飞书要求的格式（如卡片消息、富文本）把Qwen3-VL的回复发回去。

小知识：Clawdbot本身不处理AI逻辑，它只是一个“翻译官+调度员”。它把飞书的消息“翻译”成Qwen3-VL能理解的请求，再把Qwen3-VL的原始输出“翻译”成飞书用户爱看的样式。

3.2 绑定飞书应用凭证

插件装好后，需要告诉Clawdbot：“你代表的是哪个飞书应用”。执行以下命令：

# 启动交互式配置向导
clawdbot channels add

系统会依次询问：

1. Channel Type（渠道类型）：输入 feishu（回车）
2. App ID：粘贴你刚才保存的飞书App ID（回车）
3. App Secret：粘贴你刚才保存的飞书App Secret（回车）
4. Name（渠道名称）：可以输入 feishu-prod 或留空（回车）

完成后，Clawdbot会自动生成一个配置文件（通常在 ~/.clawdbot/channels/feishu.json），里面安全地存储了你的凭证（已加密）。

注意：整个过程无需你手动编辑JSON文件或修改环境变量。Clawdbot的交互式命令就是为了降低门槛，避免手误。

4. 飞书侧深度联动：事件、权限与发布（决定能否真正对话）

4.1 配置长连接回调（告别公网IP烦恼）

这是本方案最核心的创新点。传统Bot需要你暴露一个公网IP和端口，而Clawdbot支持飞书的长连接（WebSocket）模式——Clawdbot主动连飞书，而不是飞书来连你。这意味着：

• 你的服务器可以完全处于内网环境，无需申请公网IP、配置防火墙、购买SSL证书
• 连接更稳定，延迟更低，消息几乎实时到达

回到飞书开放平台，在应用管理页左侧找到「事件订阅」→「长连接（WebSocket）」。

• 点击「开启长连接」，系统会生成一个唯一的 WebSocket URL（形如 wss://...）。
• 关键操作：将这个URL复制下来，然后回到你的星图服务器终端，执行：

  # 设置Clawdbot的WebSocket回调地址
  clawdbot config set feishu.websocket_url "wss://your-generated-url"
  

如果点击「保存」时提示“未建立长链接”，请检查两点：1）Clawdbot服务是否正在运行（clawdbot status）；2）你填入的App ID和Secret是否与飞书后台完全一致（大小写、空格都不能错）。

4.2 订阅核心事件（让机器人“听见”你）

机器人要能回复，首先得能“听见”你说话。在「事件订阅」页面，点击「添加事件」。

你需要勾选以下两个最基础、最关键的事件：

• im.message.receive_v1：这是“接收消息”的开关。没有它，飞书发来的任何文字、图片、文件，Clawdbot都收不到。
• contact.user.add_v1（可选但推荐）：当新成员关注你的应用时触发，可用于欢迎语或初始化用户档案。

添加后，事件列表里会出现这两项。它们就是Clawdbot的“耳朵”。

4.3 开通必要权限（让机器人“看得见”也“说得清”）

光听见还不够，机器人还需要权限去“看”发送者是谁、“读”你发的图片、“说”出它的回答。

在左侧菜单栏找到「权限管理」，勾选以下两项：

权限名称	作用说明
contact:user.base:readonly	让机器人知道“谁在提问”，用于个性化回复
im:message	必须全选子项：包括发送消息、读取消息、上传文件等全部能力

勾选完毕后，点击页面右上角的「提交审核」→「确定」。系统会提示“权限已提交，等待管理员审批”。

重要提醒：权限变更后，必须重新发布应用版本，配置才会生效。回到「版本管理」，点击「创建新版本」，版本号可设为 1.0.1，描述写“开通用户信息与消息权限”，然后发布。

5. 端到端验证：发一条消息，亲眼见证AI在飞书里“活”起来

5.1 在飞书中启动你的AI助手

打开手机或电脑端飞书APP：

1. 点击底部「工作台」图标
2. 在搜索框中输入你创建的应用名称（如 Clawd智问）
3. 点击进入应用主页，你会看到一个聊天窗口

现在，试着发送第一条消息：

• 纯文字测试：输入 你好，Qwen3-VL，发送。
• 多模态测试（重点！）：截一张你电脑屏幕上的图表（比如Excel销售数据图），点击输入框旁的「+」→「图片」，上传这张截图，然后输入 请分析这张图里的主要趋势和异常点。

5.2 观察后台实时反馈（确认链路畅通）

与此同时，回到你的星图云服务器终端，观察Clawdbot日志（通常在 clawdbot logs 或 journalctl -u clawdbot -f）：

• 你会看到类似 Received message from user: xxx, content: 你好，Qwen3-VL 的日志，证明飞书消息已成功抵达Clawdbot。
• 接着会看到 Forwarding to LLM: ...，表示Clawdbot正将消息转发给本地Qwen3-VL服务。
• 最后出现 LLM response received, forwarding to Feishu...，说明Qwen3-VL已生成回复，Clawdbot正将其打包成飞书格式发出。

在飞书端，几秒钟后，你就会收到一条结构清晰的回复——可能是纯文字，也可能是一张带标注的图片（如果Qwen3-VL支持视觉推理），甚至是一个包含多个选项的卡片。

验证成功标志：

• 飞书端收到回复，且内容合理（非乱码或报错）
• 星图服务器GPU显存占用率短暂上升（证明Qwen3-VL模型确实在被调用）
• Clawdbot日志中无 Connection refused 或 Authentication failed 类错误

6. 实战技巧与避坑指南（来自真实踩坑经验）

6.1 常见问题速查表

现象	可能原因	快速解决方法
飞书发消息，Clawdbot日志完全没反应	1. 事件未订阅或未发布新版本 2. 长连接URL未正确配置	检查飞书「事件订阅」和「版本管理」，确认 1.0.1 版本已发布；检查 clawdbot config get feishu.websocket_url 输出是否正确
Clawdbot日志显示“认证失败”	App ID 或 App Secret 复制错误（常见于末尾空格或特殊字符）	重新复制飞书后台的凭证，用 echo "xxx" | wc -c 检查长度是否一致；或在Clawdbot中执行 clawdbot channels remove feishu 后重试 clawdbot channels add
能收消息，但Qwen3-VL回复极慢或超时	1. Qwen3-VL服务未启动或地址错误 2. GPU显存不足，模型加载失败	执行 curl http://127.0.0.1:8000/v1/models 测试Qwen3-VL服务是否健康；检查 clawdbot config get llm.endpoint 是否指向正确的本地地址
上传图片后，机器人说“不支持该格式”	Qwen3-VL:30B对图片尺寸/格式有要求（如最大边长≤2048px）	在飞书上传前，用系统自带工具将图片缩放至1920x1080以内；或在Clawdbot配置中启用图片预处理（需额外插件）

6.2 让助手更“懂你”的三个实用建议

1. 定制System Prompt（系统指令）
   Clawdbot允许你为每个渠道设置全局的system prompt。编辑 ~/.clawdbot/channels/feishu.json，在 config 字段下添加：

   "system_prompt": "你是一名专业的办公助手，专注于解读业务文档、分析数据图表、总结会议纪要。请用简洁、专业的中文回复，避免使用Markdown格式。"
   

   重启Clawdbot后生效。这比每次提问都加一句“请用专业语气”更高效。

2. 启用多轮对话记忆
   默认Clawdbot是无状态的。若需记住上下文（如用户刚上传的报表），可在Clawdbot配置中开启Redis缓存（镜像已预装Redis），并设置 history_ttl: 3600（保留1小时对话历史）。

3. 为不同部门配置不同入口
   你可以创建多个飞书应用（如 Clawd财务助手、ClawdHR助手），分别绑定不同的system prompt和权限范围，再通过飞书工作台分组展示，实现“千人千面”的AI服务。

7. 总结

7.1 你刚刚完成了什么？

你亲手搭建了一条安全、可控、免运维的企业AI接入链路：

• 底层：Qwen3-VL:30B 这个强大的多模态大模型，安静地运行在你的私有云服务器上，所有数据不出内网；
• 中层：Clawdbot 作为智能网关，无缝翻译飞书与Qwen3-VL之间的“语言”，处理身份、权限、消息格式等所有复杂细节；
• 顶层：飞书工作台中的一个图标，就是你团队触手可及的AI助手，支持文字、图片、表格等任意形式的输入。

这不是一个Demo，而是一套可立即投入日常使用的生产力工具。销售同事可以用它秒读竞品宣传图，财务人员可以用它解析扫描版发票，产品经理可以用它从用户反馈截图中提炼需求。

7.2 下一步，让AI真正融入你的工作流

• 场景深化：尝试将助手接入飞书群聊，设置关键词（如“帮我总结”、“分析这张图”）自动触发，让AI成为群里的“隐形专家”。
• 能力扩展：Clawdbot支持插件生态，未来可轻松接入RAG（检索增强）模块，让助手能基于你公司的内部文档库作答。
• 体验升级：利用飞书卡片消息能力，将Qwen3-VL的回复包装成带按钮、进度条、多选项的交互式卡片，大幅提升用户体验。

真正的AI落地，从来不是追求参数有多高、效果有多炫，而是让技术消失在流程里，只留下“真好用”的感觉。恭喜你，已经走完了最关键的第一步。

---

> **获取更多AI镜像**
>
> 想探索更多AI镜像和应用场景？访问 [CSDN星图镜像广场](https://ai.csdn.net/?utm_source=mirror_blog_end)，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。