Clawdbot 可以理解成一个运行在本地的 AI 网关。它本身不直接等同于大模型，而是负责把不同入口的消息接进来，再转发给模型和插件处理。入口可以是命令行、网页界面，也可以是飞书、企业微信、Telegram 这类聊天工具。
把 Clawdbot 接到飞书之后，日常使用方式会很自然：在飞书里给机器人发消息，机器人把消息交给本地 Clawdbot，Clawdbot 再调用 Qwen 等大模型生成回复，最后把结果发回飞书。
整体链路如下：
flowchart LR
U[飞书用户 / 群聊] --> F[飞书机器人应用]
F <-->|长连接事件| P[Clawdbot 飞书插件]
P --> G[Clawdbot Gateway]
G --> M[Qwen / 其他大模型]
G --> S[Skills / Hooks 可选能力]
M --> G
S --> G
G --> P
P --> F
F --> U
这个方案的好处是不需要单独准备公网服务器，也不需要为本地电脑配置公网回调地址。飞书的事件订阅走长连接，Clawdbot 插件主动连到飞书开放平台，收到消息后再交给本地网关处理。
不过要注意一点：如果希望机器人真正做到 7x24 小时在线，运行 Clawdbot 的电脑必须一直开机、不断网、不休眠。本地电脑关机或休眠后，飞书机器人就无法收到 Clawdbot 的回复。对稳定性要求很高时，仍然更适合放到常开机器或服务器上运行。
准备工作
需要准备这些东西：
| 项目 | 作用 |
|---|---|
| 一台能运行命令行的电脑 | 安装并运行 Clawdbot |
| 飞书账号和企业空间 | 创建企业自建应用和机器人 |
| 飞书开放平台权限 | 配置机器人能力、事件订阅和权限 |
| Qwen 登录能力 | 给 Clawdbot 提供大模型能力 |
| 基本命令行操作能力 | 执行安装、插件配置和重启命令 |
安全方面也要提前想清楚。Clawdbot 会接收飞书消息，并且可能把消息转发给模型服务；飞书应用的 App Secret 也属于敏感凭证，不要贴到公开仓库、截图或共享文档里。不建议在存有重要资料的主力电脑上随意测试自动化插件，至少要先确认插件来源和权限范围。
一、安装 Clawdbot
macOS 可以在终端里执行：
curl -fsSL https://clawd.bot/install.sh | bash
Windows 可以在 PowerShell 里执行：
iwr -useb https://clawd.bot/install.ps1 | iex
如果对一行脚本直接执行不放心，可以先把脚本下载下来检查，再手动运行：
curl -fsSL https://clawd.bot/install.sh -o install.sh
less install.sh
bash install.sh
安装过程中会出现几个交互选项，可以按下面这样选：
| 安装向导问题 | 推荐选择 | 说明 |
|---|---|---|
| 是否接受风险提示 | Yes | 确认继续安装 |
| 初始化配置模式 | Quick Start | 先用快速模式完成基础配置，细节后面还能改 |
| 模型提供方 | Qwen | 配置简单，适合快速跑通 |
| Channel 配置 | Skip for Now | 飞书不在默认列表里，后面通过插件接入 |
| Skill 配置 | No 或跳过 | 天气、画图等能力可以后续再加 |
| Hooks 配置 | Skip for Now | 自动触发器不是跑通飞书接入的必要项 |
| 运行方式 | Hatch in TUI 或默认项 | TUI（文本用户界面）适合终端运行，Web UI（网页图形界面）也可以后续打开 |
这里的几个概念可以先简单记住：
| 概念 | 含义 |
|---|---|
| Gateway | Clawdbot 的核心网关进程，负责接收消息、调模型、返回结果 |
| Model | 大模型服务，例如 Qwen、GLM、Minimax |
| Channel | 消息入口，例如飞书、企业微信、Telegram |
| Skill | 可扩展能力，例如查天气、生成图片、调用外部工具 |
| Hook | 自动触发器，在特定操作前后自动执行预设动作 |
选择 Qwen 后，浏览器会打开登录页面，按提示完成授权即可。安装完成后，Clawdbot 通常会打开一个网页管理界面，可以直接在里面测试对话。只要网页里能正常聊天，说明 Clawdbot 和模型这条链路已经跑通。
二、在飞书开放平台创建机器人应用
飞书这边要做三件事：
- 创建企业自建应用；
- 给应用添加机器人能力；
- 配置事件订阅和权限，让机器人可以收消息、发消息。
打开飞书开放平台应用管理页面：
https://open.feishu.cn/app?lang=zh-CN
创建一个「企业自建应用」，应用名称和描述按自己的用途填写即可。这个应用会承载机器人身份，后面在飞书里搜索到的机器人名字也来自这里。
创建完成后，在应用后台左侧找到「添加应用能力」，添加「机器人」能力。没有这一步，应用只是一个普通自建应用，无法作为飞书机器人参与会话。
三、先拿到 App ID 和 App Secret
飞书应用和 Clawdbot 飞书插件需要靠 App ID 和 App Secret 建立连接。它们通常在飞书应用后台的「凭证与基础信息」里。
凭证位置如下图所示，重点是复制 App ID 和 App Secret，后面会写入 Clawdbot 配置。
App ID 一般长得像 cli_xxxxx，App Secret 是一串密钥。配置时要完整复制，不要多复制空格，也不要把双引号里的示例值原样填进去。
四、安装 Clawdbot 飞书插件
Clawdbot 默认安装流程里没有直接启用飞书入口，需要额外安装飞书 Channel 插件。
在终端执行：
clawdbot plugins install @m1heng-clawd/feishu
安装完成后，把飞书后台复制出来的凭证写入 Clawdbot 配置：
clawdbot config set channels.feishu.appId "cli_xxxxx"
clawdbot config set channels.feishu.appSecret "your_app_secret"
clawdbot config set channels.feishu.enabled true
把示例里的值替换成自己的真实值：
clawdbot config set channels.feishu.appId "cli_aabbccddeeff"
clawdbot config set channels.feishu.appSecret "xxxxxxxxxxxxxxxxxxxxxxxx"
clawdbot config set channels.feishu.enabled true
配置写完后重启网关：
clawdbot gateway restart
这一步很关键。飞书的长连接订阅需要应用已经和插件建立连接，如果还没配置好插件就去飞书后台选择长连接，可能会遇到「应用未建立长连接」之类的错误。
五、配置飞书事件订阅
机器人要能回复消息，必须先收到消息事件。在飞书应用后台进入「事件与回调」，添加事件时选择：
消息与群组 -> 接收消息
事件添加入口如下，核心是选择「接收消息」这个事件。
没有订阅接收消息事件时，即使机器人已经存在于飞书里，用户给它发消息也不会触发 Clawdbot，表现出来就是「发了消息但没反应」。
事件回调方式选择「使用长连接」。
长连接方式适合本地部署场景，因为它不要求本地电脑暴露一个公网 HTTP（超文本传输协议）回调地址。Clawdbot 飞书插件会主动和飞书建立连接，飞书有消息事件时，通过这条连接把事件推给插件。
如果这里提示应用没有建立长连接，可以按这个顺序排查：
flowchart TD
A[飞书提示未建立长连接] --> B{Clawdbot 是否正在运行}
B -- 否 --> B1[启动或重启 Clawdbot Gateway]
B -- 是 --> C{飞书插件是否已安装}
C -- 否 --> C1[安装 @m1heng-clawd/feishu]
C -- 是 --> D{appId/appSecret 是否正确}
D -- 否 --> D1[重新复制并写入配置]
D -- 是 --> E[再次执行 gateway restart 后回到飞书后台重试]
六、开通机器人所需权限
事件订阅负责「收到通知」，权限负责「允许做事」。飞书后台里如果权限没开全，常见现象是机器人收不到消息、无法给用户发消息，或者在群聊里无法响应 @。
权限配置页面如下，建议在权限弹窗里直接搜索权限名称或关键词。
常用权限可以按用途分成几类：
| 用途 | 需要关注的权限 |
|---|---|
| 接收单聊消息 | 读取用户发给机器人的单聊消息 |
| 接收群聊 @ 消息 | 读取群聊中 @ 机器人的消息 |
| 发送回复 | 以应用身份发送消息 |
| 群聊场景 | 获取群组信息、读取群组相关消息 |
| 展示用户信息 | 获取用户基本信息 |
不同飞书后台版本的权限名称可能略有差异，搜索时可以用这些关键词：
消息
单聊
群聊
机器人
发送消息
接收消息
用户基本信息
群组信息
如果只需要一对一聊天，重点保证「接收单聊消息」和「发送消息」相关权限。要把机器人拉进群里使用，则需要额外关注群聊和 @ 消息相关权限。
权限添加完成后，一定要创建并发布新版本。飞书自建应用的很多修改不会立即对线上应用生效，必须通过「创建版本」把机器人能力、事件订阅和权限一起发布出去。
七、重启 Clawdbot 并测试飞书机器人
飞书配置发布完成后，再重启一次 Clawdbot：
clawdbot gateway restart
在飞书客户端里搜索刚才创建的机器人名称，打开单聊窗口，发送：
你好
如果配置正确，消息链路会这样流转：
sequenceDiagram
participant User as 飞书用户
participant Bot as 飞书机器人应用
participant Plugin as Clawdbot 飞书插件
participant Gateway as Clawdbot Gateway
participant Model as Qwen 模型
User->>Bot: 发送“你好”
Bot->>Plugin: 通过长连接推送接收消息事件
Plugin->>Gateway: 转交用户消息
Gateway->>Model: 请求生成回复
Model-->>Gateway: 返回模型结果
Gateway-->>Plugin: 返回回复内容
Plugin-->>Bot: 调用飞书接口发送消息
Bot-->>User: 展示机器人回复
群聊里使用时，通常需要把机器人加入群，然后 @机器人 发送问题。部分权限只允许机器人接收被 @ 的消息，不会读取群里所有普通消息，这一点和飞书权限设计有关。
常见问题排查
| 问题现象 | 可能原因 | 处理方式 |
|---|---|---|
| 飞书里给机器人发消息没有回复 | 没订阅「接收消息」事件 | 回到「事件与回调」添加消息接收事件 |
| 配置长连接时报「应用未建立长连接」 | Clawdbot 飞书插件未运行或凭证未配置 | 安装插件、设置 appId / appSecret，然后重启 Gateway |
| 单聊可用，群聊不可用 | 缺少群聊或 @ 消息权限 | 在权限管理里补充群聊、群组信息、@ 消息相关权限 |
| 机器人能收到消息但发不出回复 | 缺少发送消息权限 | 开通「以应用身份发送消息」相关权限并发布版本 |
| 飞书后台改了配置仍不生效 | 没有创建并发布新版本 | 在应用后台创建版本，保存并发布 |
| Clawdbot 网页里也无法聊天 | 模型侧未登录或授权失效 | 重新检查 Qwen 登录状态 |
| 过一段时间机器人离线 | 本地电脑休眠、断网或进程退出 | 关闭休眠，保持网络，必要时部署到常开机器 |
| 命令执行成功但仍没有响应 | 配置项写错或密钥复制错误 | 重新执行 clawdbot config set ... 并重启 |
运行时建议
本地运行 AI 机器人时，不要只关注能不能跑通，还要注意几个长期使用问题：
| 建议 | 原因 |
|---|---|
不要泄露 App Secret | 拿到密钥的人可能伪装成你的飞书应用 |
| 给机器人只开必要权限 | 权限越大，误操作或插件风险越高 |
| 不要让电脑自动休眠 | Clawdbot 进程停掉后，飞书机器人无法回复 |
| 先用测试群验证 | 避免机器人在正式群里刷屏或误回复 |
| 谨慎开启 Skills 和 Hooks | 自动化能力越多，越需要确认触发条件和执行范围 |
跑通之后，飞书就变成了 Clawdbot 的一个聊天入口。单聊适合处理个人问题，群聊适合让机器人参与文档草拟、方案整理、信息总结等协作场景。后续如果要扩展能力，可以继续给 Clawdbot 添加 Skill，让它调用天气、搜索、画图或其他外部工具。