零基础实战：用星图AI云+Clawdbot，让Qwen3-VL成为你的飞书助手

零基础实战：用星图AI云+Clawdbot，让Qwen3-VL成为你的飞书助手

1. 引言：告别繁琐，让AI助手直接“住”进你的飞书

想象一下这个场景：同事在飞书群里发来一张密密麻麻的会议纪要截图，问“下周三的会议时间改到几点？”，你不需要再手动放大图片、辨认文字、翻找日历，而是直接@一下你的AI助手，它就能瞬间从图片里找到答案并回复。

这听起来像是科幻电影里的场景？不，这就是我们今天要实现的现实。

在上一篇教程中，我们已经在CSDN星图AI云上完成了Qwen3-VL:30B多模态大模型的私有化部署。现在，这个“能看会聊”的智能大脑已经准备就绪，但它还缺少一个与外界沟通的“嘴巴”和“耳朵”。

本篇教程将为你补上这最后一块拼图——通过Clawdbot这个智能代理网关，将Qwen3-VL无缝接入飞书平台。整个过程不需要你懂复杂的网络编程，也不需要处理繁琐的API对接，就像搭积木一样简单。

你将获得什么？

• 一个24小时在线的飞书智能助手
• 支持图文混合问答的办公效率工具
• 完全私有化部署，数据不出企业
• 零代码配置，全程可视化操作

准备好了吗？让我们开始吧。

2. 准备工作：确认你的“地基”是否牢固

在开始飞书接入之前，我们需要确保上一篇教程中的所有步骤都已经正确完成。这就像盖房子，地基打好了，上面的建筑才能稳固。

2.1 环境检查清单

请打开你的星图AI云控制台，逐一核对以下项目：

Qwen3-VL服务状态

• 进入实例详情页，确认状态为“运行中”
• 点击“Ollama控制台”快捷按钮，测试图文问答功能是否正常
• 上传一张包含文字的图片，观察是否能得到准确回复

Clawdbot网关状态

• 在Web终端中执行命令：clawdbot status
• 确认网关服务正在运行
• 通过公网URL访问Clawdbot控制台，使用Tokencsdn登录

网络连通性

• 确认实例已开启公网访问
• 在Clawdbot控制台的“Settings” → “Network”中，检查端口映射状态

如果以上任何一项检查失败，请先返回上一篇教程解决相应问题。磨刀不误砍柴工，确保基础环境正常，后续的配置才能一帆风顺。

2.2 你需要准备的东西

在开始飞书配置前，请准备好：

1. 一个飞书企业账号（个人版也可以，但企业版功能更完整）
2. 管理员权限（用于创建企业自建应用）
3. 10-15分钟的专注时间

不用担心技术门槛，整个过程就像在手机上安装一个新应用一样简单。

3. 第一步：在飞书开放平台创建你的智能助手应用

飞书开放平台就像是App Store，而我们要做的就是发布一个属于自己团队的“智能助手App”。

3.1 创建企业自建应用

首先，访问飞书开放平台，使用你的飞书账号登录。

登录后，你会看到开发者后台的仪表盘。点击页面右上角的“创建企业自建应用”按钮。

在弹出的创建窗口中，填写应用的基本信息：

• 应用名称：给你的助手起个名字，比如“智能办公助手”、“图文小秘书”
• 应用描述：简单说明应用的功能，例如“基于多模态AI的智能图文问答助手”
• 应用图标：上传一个醒目的图标，这将成为助手在飞书中的头像

小贴士：应用名称和图标很重要，它们会直接显示在飞书的工作台和聊天界面中。建议选择一个简洁明了的名称和辨识度高的图标，方便团队成员快速识别。

填写完成后，点击“确认创建”，你的第一个飞书应用就诞生了。

3.2 开启机器人能力

创建应用后，你会进入应用的管理页面。在左侧的导航菜单中，找到“添加应用能力”选项。

点击进入后，你会看到一个能力列表。我们需要的是“机器人”能力——这相当于给应用安装了一个可以自动收发消息的“智能大脑”。

找到“机器人”卡片，点击“添加”按钮。系统会提示你确认添加，点击“确定”即可。

添加成功后，你会在左侧菜单中看到“机器人”选项，这表示你的应用现在已经具备了聊天机器人的基础能力。

3.3 获取关键凭证：App ID和App Secret

现在我们需要获取两个重要的“钥匙”——App ID和App Secret。它们就像是应用的身份证明和密码，Clawdbot需要这些信息才能与飞书建立安全连接。

在左侧菜单中，点击“凭证与基础信息”。在这个页面，你可以看到：

• App ID：一串由数字和字母组成的唯一标识符
• App Secret：一串更长的密钥（点击“显示”才能看到完整内容）

重要提示：请立即将这两个值复制并保存到安全的地方。App Secret只会显示一次，如果忘记就需要重新生成。

为什么需要这两个凭证？简单来说：

• App ID：告诉飞书“我是谁”
• App Secret：证明“我真的是我”

没有它们，Clawdbot就无法通过飞书的安全验证，自然也就无法收发消息。

3.4 创建初始版本（重要步骤）

在飞书开放平台，很多配置功能需要先有一个应用版本才能使用。这就像你要发布一个软件，至少得有个1.0版本。

在左侧菜单中找到“版本管理与发布”，点击进入后选择“创建版本”。

填写版本信息：

• 版本号：输入“1.0.0”
• 版本说明：简单描述，如“初始版本，实现基础机器人功能”
• 可用性：选择“仅限开发人员”（这样只有你能在测试环境使用）

点击“保存”，你的应用就有了第一个正式版本。虽然这个版本功能还不完整，但它是后续所有配置的基础。

4. 第二步：配置Clawdbot连接飞书（镜像已预配置）

好消息是，我们使用的星图AI云镜像已经预装了Clawdbot和飞书插件。这意味着你不需要再手动安装任何东西，只需要进行简单的配置即可。

4.1 验证Clawdbot运行状态

首先，让我们确认Clawdbot服务是否正常运行。

打开星图AI云实例的Web终端，输入以下命令：

clawdbot status

如果看到类似下面的输出，说明服务运行正常：

Clawdbot Gateway is running (PID: 12345) Listening on: http://0.0.0.0:18789 Public URL: https://gpu-pod-xxx-18789.web.gpu.csdn.net/

如果服务没有运行，可以手动启动：

clawdbot gateway

4.2 添加飞书通信渠道

现在，我们要告诉Clawdbot：“嘿，我有个飞书应用想和你连接”。

在Web终端中执行以下命令：

clawdbot channels add

这是一个交互式配置命令，Clawdbot会一步步引导你完成配置。

当系统提示选择渠道类型时，使用方向键选择“feishu”（飞书），然后按回车确认。

接下来，系统会要求你输入飞书应用的凭证信息：

1. 请输入App ID：粘贴你刚才保存的App ID
2. 请输入App Secret：粘贴对应的App Secret
3. 请输入应用名称：输入一个易于识别的名称，如“我的飞书助手”

配置过程会有清晰的提示，就像在填一个简单的表格。完成后，Clawdbot会显示配置摘要，确认无误后按回车保存。

配置成功的关键标志：在Clawdbot控制台的“Channels”页面，你应该能看到刚刚添加的飞书渠道，状态显示为“已连接”或“等待验证”。

4.3 重启网关服务（让配置生效）

配置完成后，我们需要重启Clawdbot网关服务，让新的飞书配置生效。

在Web终端中执行：

clawdbot gateway --restart

或者，如果网关正在运行，可以先停止再启动：

clawdbot gateway stop clawdbot gateway

重启后，观察终端输出，确认没有错误信息。通常你会看到类似这样的日志：

[INFO] Loading configuration from /root/.clawdbot/clawdbot.json [INFO] Feishu channel configured: my-feishu-assistant [INFO] Gateway started on port 18789

如果看到“Feishu channel configured”的字样，恭喜你，Clawdbot端的所有配置已经完成！

5. 第三步：在飞书后台完成联动配置

现在Clawdbot已经准备好了，我们需要回到飞书开放平台，完成另一端的配置。这就像打电话，两边都要拿起听筒才能通话。

5.1 配置事件订阅（让飞书知道往哪发送消息）

在飞书开放平台的应用管理页面，找到左侧的“事件订阅”菜单。

这里有两种通信方式可选：

• Webhook（回调）：需要公网固定IP，配置相对复杂
• 长连接（WebSocket）：无需公网IP，自动建立双向通信

强烈推荐选择“长连接”模式，因为它更简单、更稳定，特别适合我们这种在云服务器上部署的场景。

点击“启用长连接”按钮，系统会自动检测Clawdbot是否已准备好接收连接。

常见问题：如果点击保存时提示“未建立长链接”，请检查：

1. Clawdbot网关是否正在运行（执行clawdbot status确认）
2. 飞书凭证是否填写正确（App ID和App Secret）
3. 网络是否通畅（可以在Clawdbot控制台测试网络连接）

5.2 添加消息接收事件

长连接建立后，我们需要告诉飞书：“当用户发送消息时，请通知我的Clawdbot”。

在事件订阅页面，点击“添加事件”按钮。

你会看到一个事件列表，我们需要订阅的是：

• 接收消息v2（im.message.receive_v1）

找到这个事件，勾选它，然后点击“确认添加”。

这个事件的作用是：当用户在飞书中向你的机器人发送消息时，飞书会立即将这个事件推送给Clawdbot，Clawdbot收到后就可以调用Qwen3-VL模型生成回复。

5.3 开通必要权限（让机器人“有权”工作）

光能接收消息还不够，机器人还需要一些“权限”才能正常工作。

在左侧菜单中找到“权限管理”，这里列出了机器人可以申请的所有权限。我们需要开通两个核心权限：

1. 获取用户基本信息

• 权限名称：获取用户 user_id
• 权限范围：contact:user.base:readonly
• 作用：识别消息发送者是谁

2. 收发消息权限

• 权限名称：获取与发送单聊、群组消息
• 权限范围：im:message
• 作用：读取用户消息并发送回复

找到这两个权限，点击右侧的“申请权限”按钮。系统会提示你确认，点击“确定”即可。

权限说明：这些权限都是最基本的，不会涉及敏感操作。获取用户ID只是为了识别对话对象，消息权限也只是在用户主动@机器人时才生效。

5.4 发布新版本（让配置生效）

所有配置完成后，我们需要发布一个新的应用版本，让这些设置正式生效。

回到“版本管理与发布”页面，点击“创建版本”。

填写版本信息：

• 版本号：比如“1.1.0”
• 版本说明：描述本次更新的内容，如“开通消息收发权限，启用长连接通信”
• 可用性：如果只是自己测试，选择“仅限开发人员”；如果需要团队使用，选择“全公司可用”

点击“保存并申请发布”，系统会进行自动审核。由于我们申请的是基础权限，通常几秒钟就能通过。

审核通过后，点击“发布”按钮，你的智能助手就正式上线了！

6. 第四步：端到端测试——让你的助手“活”起来

配置全部完成后，最激动人心的时刻到了——让我们测试一下整个系统是否正常工作。

6.1 在飞书中找到你的助手

打开飞书App（手机或电脑端都可以），进入“工作台”。

在工作台的应用列表中，你应该能看到刚刚创建的应用。如果没找到，可以在搜索框中输入应用名称。

点击进入应用，你会看到一个简单的聊天界面。这就是你的智能助手的“家”。

6.2 发送第一条消息

现在，尝试给你的助手发送一条消息。可以从简单的文字开始：

你好，我是测试用户

发送后，观察几秒钟。如果一切正常，你应该会收到助手的回复。

第一次响应可能会稍慢（5-10秒），因为Clawdbot需要：

1. 接收飞书的消息事件
2. 将消息转发给Qwen3-VL模型
3. 等待模型生成回复
4. 将回复发送回飞书

如果收到了回复，恭喜你！基础的文字对话功能已经打通了。

6.3 测试图文混合能力（核心功能）

现在让我们测试最核心的功能——图文混合问答。

在飞书聊天界面中：

1. 点击输入框旁的“+”号，选择“图片”
2. 上传一张包含文字的图片（比如商品截图、文档照片、会议纪要等）
3. 在输入框中提问，比如：“这张图片里说的是什么？”

发送后，观察助手的回复。一个正常的多模态回复应该包含：

• 对图片内容的准确描述
• 针对你问题的具体回答
• 自然的语言表达

6.4 在星图控制台观察运行状态

测试的同时，你可以打开星图AI云的控制台，观察系统的运行状态：

GPU使用情况

• 进入实例监控页面
• 观察GPU显存使用率：发送图片时应该会明显上升
• 观察GPU利用率：模型推理时应该有波动

Clawdbot日志

• 在Web终端中，Clawdbot会实时输出日志
• 你应该能看到类似这样的信息：

  [INFO] Received message from Feishu: user_xxx [INFO] Calling model: qwen3-vl:30b [INFO] Model response generated, sending back to Feishu

Ollama服务状态

• 如果打开Ollama控制台，可以看到模型调用记录
• 每次图文问答都会生成一条新的记录

这些观察能帮助你确认：消息确实从飞书传到了Clawdbot，Clawdbot确实调用了Qwen3-VL模型，模型确实生成了回复，回复确实返回给了飞书。

7. 常见问题排查与优化建议

即使按照教程一步步操作，偶尔也可能会遇到一些小问题。别担心，这里列出了最常见的几种情况及其解决方法。

7.1 问题：飞书收不到回复，或者回复很慢

可能原因1：Clawdbot网关未正常运行

• 检查：在Web终端执行clawdbot status
• 解决：如果服务停止，执行clawdbot gateway重新启动

可能原因2：飞书长连接断开

• 检查：在飞书开放平台的事件订阅页面，查看长连接状态
• 解决：点击“重新连接”按钮，或重启Clawdbot网关

可能原因3：模型响应超时

• 检查：Qwen3-VL模型是否正常加载（在Ollama控制台测试）
• 解决：复杂的图文问题可能需要更多时间，可以尝试简化问题

7.2 问题：助手回复“我无法查看图片”

可能原因1：图片格式或大小问题

• 检查：图片是否过大（建议小于5MB）
• 解决：压缩图片或截图后重新发送

可能原因2：多模态功能未正确启用

• 检查：Clawdbot配置中是否指定了Qwen3-VL模型
• 解决：确认clawdbot.json中的模型配置正确

可能原因3：模型加载异常

• 检查：在Ollama控制台直接测试图文问答
• 解决：如果Ollama也无法处理图片，可能需要重新拉取模型：

  ollama pull qwen3-vl:30b

7.3 问题：只有文字回复正常，图片相关功能异常

可能原因：Clawdbot未正确处理多模态消息

• 检查：Clawdbot日志中是否有图片处理相关的错误
• 解决：确保使用的是最新版本的Clawdbot和飞书插件

7.4 性能优化建议

提升响应速度

1. 启用流式响应：在Clawdbot配置中开启流式输出，让用户能更快看到回复
2. 优化图片尺寸：建议用户发送前适当压缩图片
3. 设置超时时间：对于复杂问题，可以设置合理的超时时间

提升使用体验

1. 添加使用指引：在飞书应用描述中简单说明如何使用
2. 设置自动欢迎语：用户第一次进入时发送使用说明
3. 添加常用功能示例：提供几个示例问题，帮助用户快速上手

安全加固

1. 限制使用范围：在飞书后台设置只有特定部门或人员可以使用
2. 添加敏感词过滤：在Clawdbot中配置关键词过滤
3. 定期检查日志：关注异常访问模式

8. 总结：从技术到价值，你的智能办公助手已就位

8.1 回顾成果：我们完成了什么？

通过上下两篇教程，我们共同完成了一个完整的AI应用落地项目：

技术层面

• 在星图AI云上私有化部署了Qwen3-VL:30B多模态大模型
• 配置了Clawdbot作为统一的AI网关和管理平台
• 将AI能力无缝接入飞书，打造了企业级智能助手

功能层面

• 实现了文字对话功能
• 实现了图文混合问答能力
• 构建了完整的消息收发链路
• 确保了数据私有化和安全性

体验层面

• 零代码配置，全程可视化操作
• 开箱即用，无需复杂的环境搭建
• 响应迅速，体验流畅

8.2 实际应用场景举例

现在，你的飞书助手已经可以处理各种实际工作场景：

会议支持

• 上传会议纪要截图，问“本次会议确定了哪些行动计划？”
• 发送项目进度表图片，问“哪个任务的延期风险最高？”

文档处理

• 上传合同扫描件，问“付款条款的具体内容是什么？”
• 发送财务报表截图，问“本季度营收同比增长了多少？”

日常办公

• 上传商品详情页截图，问“这个产品的核心卖点是什么？”
• 发送技术架构图，问“这个系统中数据库的作用是什么？”

团队协作

• 在群聊中@助手分析图片内容
• 让助手总结聊天记录中的关键信息
• 用助手快速查找历史文档中的特定内容

8.3 下一步可以做什么？

你的智能助手基础框架已经搭建完成，但这只是开始。接下来可以考虑：

功能扩展

• 接入企业知识库，让助手能回答公司内部问题
• 集成日历和待办事项，实现智能提醒
• 连接业务系统，实现数据查询和报表生成

体验优化

• 定制助手的回复风格和语气
• 添加快捷指令和模板回复
• 实现多轮对话和上下文记忆

部署推广

• 将整个环境打包为星图镜像，方便团队其他成员一键部署
• 编写使用手册和培训材料
• 收集用户反馈，持续迭代优化

8.4 最后的建议

技术工具的价值在于使用。建议你先从一个小团队开始试用，收集实际使用中的反馈。哪些功能最常用？哪些场景最需要？用户的真实需求往往与我们的设想有所不同。

记住，一个好的AI助手不是要替代人类，而是要增强人类的能力。它应该像一位得力的助手，在你需要的时候提供准确的信息和有用的建议，而不是一个冷冰冰的问答机器。

现在，你的智能办公助手已经准备就绪。去飞书里@它，开始体验AI带来的效率提升吧。从今天起，让繁琐的图文处理工作交给AI，把你的时间和精力留给更有创造性的任务。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。