保姆级教学：从零开始搭建Qwen3-VL飞书智能机器人

引言

你是否想过，让企业内部的飞书工作台拥有一个真正“看得懂、听得清、答得准”的AI助手？不是简单回复关键词的客服机器人，而是能理解你发来的截图、分析Excel表格、解读产品手册、甚至根据会议照片生成纪要的多模态智能体——这正是 Qwen3-VL:30B + Clawdbot 的组合所能实现的能力。

本文是一份完全面向新手的实操指南，不假设你有任何飞书开发经验，也不要求你懂 Python 或 WebSocket 原理。只要你会登录网页、复制粘贴 App ID、在终端敲几行命令，就能在 2 小时内完成整套部署：从飞书后台创建应用，到本地服务器接入大模型，再到在飞书里和你的专属 AI 助手第一次对话。

特别说明：本教程默认你已完成上篇内容——即已在 CSDN 星图 AI 平台成功私有化部署了 Qwen3-VL:30B 模型（镜像已预装 Clawdbot 网关与模型服务）。本篇聚焦“最后一公里”：如何把这台强大的本地算力，安全、稳定、低延迟地接入飞书生态。

我们不讲抽象架构，不堆参数术语，只告诉你每一步该点哪里、填什么、为什么这么填，以及填错后怎么快速排查。

---

1. 飞书侧准备：三步创建可通信的企业应用

别被“开放平台”“自建应用”这些词吓住——它本质上就是给你的机器人办一张“飞书通行证”。整个过程只需 5 分钟，且全部在网页端完成。

1.1 登录并新建应用

打开 飞书开放平台，使用你所在企业的管理员账号登录（必须是企业认证账号，个人飞书号不可用）。

点击左上角 “创建企业自建应用” → 选择 “企业自建” 类型（不是“第三方应用”）。

填写基础信息：

• 应用名称：建议用简洁易识别的名字，如 Clawd助教 或 Qwen-VL办公助手（后续会直接显示在飞书工作台）
• 应用描述：一句话说明用途，例如 基于Qwen3-VL的多模态文档分析助手
• 应用图标：上传一个 128×128 像素的 PNG 图标（可用任意设计工具生成，或临时用文字生成器）

小贴士：名称和图标一旦发布，员工在工作台搜索时将直接看到。避免使用“测试”“Demo”等字样，否则容易被忽略。

1.2 开启机器人能力并创建初始版本

进入新创建的应用管理页，左侧菜单找到 “添加应用能力” → 点击 “机器人” → 确认添加。

此时页面会提示“请先创建一个应用版本”，这是飞书的强制流程。点击右上角 “创建版本”，填写：

• 版本号：1.0.0（固定格式，无需修改）
• 版本描述：初始化机器人能力

点击提交。这一步不能跳过，否则后续无法配置凭证和事件。

1.3 获取关键凭证：App ID 与 App Secret

在左侧菜单中点击 “凭证与基础信息”，你会看到两串重要字符：

字段	示例值（仅示意）	用途
App ID	cli_a1b2c3d4e5f67890	Clawdbot 连接飞书的“用户名”
App Secret	sEcReT_1234567890abcdef	Clawdbot 连接飞书的“密码”，仅显示一次！

务必立即复制并保存到本地文本文件（不要存在剪贴板太久，刷新页面后 App Secret 将不可见）。这两个值将在下一步直接填入 Clawdbot 配置中。

安全提醒：App Secret 是高危凭证，切勿上传至 GitHub、共享文档或群聊。若误泄露，可在飞书后台立即重置。

---

2. Clawdbot 侧操作：两行命令完成插件绑定

现在，我们回到星图云服务器终端（可通过星图控制台 WebSSH 或本地 SSH 连接）。这里所有操作都是交互式命令，系统会一步步引导你输入，无需记忆复杂语法。

2.1 安装飞书专用连接插件

Clawdbot 采用插件化设计，飞书支持已封装为独立模块。执行以下命令安装：

clawdbot plugins install @m1heng-clawd/feishu

你会看到类似这样的输出：

✔ Plugin @m1heng-clawd/feishu installed successfully
→ Next step: run 'clawdbot channels add' to configure Feishu connection

表示插件安装成功。注意末尾提示——下一步就是配置连接。

2.2 绑定飞书应用凭证

运行命令启动交互式配置：

clawdbot channels add

系统会依次提问，请按提示输入：

1. Channel type：输入 feishu（回车）
2. App ID：粘贴你刚保存的 App ID（回车）
3. App Secret：粘贴你刚保存的 App Secret（回车）
4. Channel name：输入一个内部标识名，如 feishu-prod（回车）

完成后，你会看到：

✔ Channel 'feishu-prod' added successfully
→ Configuration saved to /root/.clawdbot/channels/feishu-prod.json

至此，Clawdbot 已记住你的飞书应用身份。但注意：此时还不能收消息，因为飞书还不知道该把消息发给谁。

---

3. 关键联动：让飞书与 Clawdbot “握手成功”

这一步是成败核心——需要在飞书后台告诉它：“以后所有发给这个机器人的消息，请通过长连接推送到我的 Clawdbot 服务”。而 Clawdbot 必须处于运行状态，才能建立这条通道。

3.1 启动 Clawdbot 网关服务

在服务器终端中，确保 Clawdbot 正在运行。如果刚安装完插件，或之前未启动，执行：

clawdbot gateway

你会看到日志持续滚动，其中包含类似：

[INFO] Gateway started on http://0.0.0.0:3000
[INFO] Feishu channel 'feishu-prod' initialized
[INFO] WebSocket server listening on wss://your-instance.csdn-ai.com/ws

注意最后一条：WebSocket server listening... 表示 Clawdbot 已准备好接收飞书的长连接请求。

如何确认服务在运行？执行 ps aux | grep clawdbot，应看到 clawdbot gateway 进程。若无，请检查是否遗漏上一步配置。

3.2 在飞书后台配置长连接回调地址

回到飞书开放平台，进入你的应用 → 左侧菜单点击 “事件订阅”。

• 连接方式：选择 “长连接（WebSocket）”（推荐！无需公网 IP 和域名备案）
• WebSocket 地址：填入 Clawdbot 日志中显示的 wss://... 地址（形如 wss://abc123.csdn-ai.com/ws）
• Token：随意填写 6 位以上字母数字组合，如 clawd2024（后续需在 Clawdbot 配置中保持一致）
• Encrypt Key：留空（本方案不启用消息加密）

点击 “保存”。如果提示“未建立长连接”，请立即检查：

• Clawdbot 是否正在运行（clawdbot gateway 命令是否在前台执行？）
• 填写的 WebSocket 地址是否与日志中完全一致（注意 wss:// 开头，不是 http://）
• Token 是否拼写正确（大小写敏感）

成功保存后，页面会显示“长连接已建立”，并出现绿色对勾。

3.3 订阅必要事件并开通权限

飞书默认不会把任何消息推给你。你需要明确告诉它：“我要接收哪些类型的消息”。

点击 “添加事件” → 勾选以下两项（其他可暂不选）：

• im.message.receive_v1：收到用户发送的文本、图片、文件等消息
• contact.user.add_v1：当新用户首次添加机器人时触发（用于欢迎语）

然后，点击左侧 “权限管理” → 找到并勾选：

权限名称	作用	是否必选
contact:user.base:readonly	读取用户姓名、部门、头像等基本信息	必选（否则不知道谁在说话）
im:message → 子项 send_message	向用户发送回复消息	必选（否则只能听不能说）

全部勾选后，点击右上角 “应用发布” → 创建新版本（如 1.0.1）→ 提交发布。

⏱ 发布后需等待约 30 秒生效。这是飞书的缓存机制，非配置错误。

---

4. 实战验证：从第一句问候到多模态响应

现在，真正的检验时刻到了。我们分三步验证：飞书端发起、模型端响应、结果端呈现。

4.1 在飞书中发起首次对话

打开手机或电脑版飞书 → 点击底部 【工作台】 → 在搜索框输入你设置的应用名称（如 Clawd助教）→ 进入应用主页。

点击右下角 “开始对话” 或直接输入一句问候，例如：

你好，能帮我看看这张截图里的表格数据吗？

然后点击 “+” 号 → 选择相册 → 上传一张含表格的截图（如 Excel 截图、网页表格等）。

如果机器人秒级回复（如“已收到图片，正在分析…”），说明通信链路已通。

4.2 观察模型调用与日志反馈

回到星图云服务器终端，观察 clawdbot gateway 日志流，你会看到清晰的处理链条：

[INFO] Received message from user@company.com (user_id: u_abc123)
[INFO] Detected image attachment: screenshot.png
[INFO] Forwarding to Qwen3-VL:30B model...
[INFO] Model response generated in 4.2s (tokens: 187)
[INFO] Sending reply to Feishu...

同时，在星图控制台的 GPU 监控面板中，能看到 GPU 显存占用率瞬间跃升至 35%~45%（Qwen3-VL:30B 的典型负载），几秒后回落——这正是模型在后台解析图像并生成文本的直观证据。

4.3 多模态能力实测：不止于文字

试试更复杂的指令，验证 Qwen3-VL 的真实能力：

• 发送一张产品说明书 PDF 的第一页截图 → 输入：请提取图中所有技术参数，列成表格
• 发送一张会议白板照片 → 输入：总结这张图里的三个核心议题和待办事项
• 发送一张带二维码的海报 → 输入：扫描二维码并告诉我跳转链接是什么

你会发现，机器人不仅能识别文字，还能理解图表结构、定位关键区域、关联上下文逻辑——这才是多模态大模型区别于纯文本模型的核心价值。

---

5. 常见问题速查与稳定性保障

部署完成只是开始。以下是高频问题与长效运行建议，帮你避开 90% 的线上故障。

5.1 为什么消息发出去没回复？

按顺序排查：

1. Clawdbot 是否存活：执行 ps aux | grep clawdbot，确认进程存在
2. 日志是否有报错：查找 ERROR 或 Connection refused 字样
3. 飞书事件是否订阅：检查“事件订阅”页面是否显示“已启用”
4. 权限是否发布生效：确认最新版本已“发布成功”，而非“草稿”

5.2 如何让机器人更“懂业务”？

Clawdbot 支持自定义系统提示词（System Prompt），在 /root/.clawdbot/config.yaml 中修改：

models:
  qwen3-vl:
    system_prompt: |
      你是一家科技公司的AI办公助手，专注处理技术文档、产品资料和会议记录。
      回复需简洁专业，优先用 bullet points 列出要点，避免冗长解释。
      对不确定的问题，直接回答“暂不支持该功能”，不猜测。

修改后重启：clawdbot gateway --reload

5.3 长期运行稳定性建议

• 守护进程：用 systemd 后台运行，避免终端关闭导致服务中断
• 日志轮转：配置 logrotate 防止日志文件无限增长
• 健康检查：在飞书后台开启“心跳检测”，自动发现连接异常
• 资源监控：星图平台提供 GPU/CPU/内存实时看板，设置告警阈值

---

总结

恭喜你，已经亲手搭建起一套真正属于企业自己的多模态智能办公助手。回顾整个过程，你完成了：

• 飞书侧：创建合规应用、获取安全凭证、配置长连接与权限
• 服务器侧：安装飞书插件、绑定凭证、启动网关服务
• 验证侧：从文本问候到图片解析，完整走通端到端链路

这不是一个玩具 Demo，而是一套可投入生产环境的解决方案：所有数据不出内网，所有模型运行在私有 GPU 上，所有交互通过飞书原生界面完成。你获得的不仅是一个机器人，更是一种将前沿 AI 能力无缝融入日常办公的新范式。

下一步，你可以：

• 将机器人添加到部门群，让团队共享多模态分析能力
• 结合飞书多维表格，实现“上传表格 → 自动生成分析报告 → 自动更新看板”的闭环
• 接入企业知识库，让机器人成为活的《内部操作手册》

真正的 AI 办公，就从这一句“你好”开始。

---

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