先把结论放在前面这个项目做出来之后飞书里的机器人就不再是“关键词自动回复”那种玩具了而是能理解上下文、能调用工具、能替你在服务器上跑任务的 AI Agent。我把它部署在阿里云 ECS 上24 小时在线配合飞书的消息入口基本就是随身带了个低配版贾维斯。下面直接说清楚整套链路怎么搭、哪些地方最容易踩坑以及我最终跑通的配置长什么样。1. 项目设计思路飞书当入口阿里云当底座ClawBot 当大脑1.1 ClawBot 是什么为什么选它做助理内核ClawBot 这个项目简单说就是一个智能体运行时Agent Runtime。它本身不生产 AI 能力而是把大模型、工具调用、消息渠道这三样东西粘在一起。你给它接上大模型的 API它会帮你管理对话上下文、解析用户的意图、按需调用注册好的工具最后把结果格式化输出。和直接调 OpenAI 或通义千问的 API 写个聊天机器人相比ClawBot 这类框架的核心价值在于“工具调用”的工程化。比如用户说“帮我查一下明天北京天气顺便定个早上九点的提醒”如果只靠大模型它只能给你一段文字建议但在 ClawBot 里这句话会被拆成“调用天气插件获取数据”和“创建一个定时提醒任务”两个动作由框架负责编排和回填结果。这才是 AI 助理“能干活”和“只会聊天”的分水岭。我为什么强调选它而不是从零写因为我试过用 Python FastAPI 自己写一个飞书机器人做到后面发现要在对话管理、多轮上下文、工具异常恢复、消息去重这些环节上投入大量时间而 ClawBot 这类项目已经把底层逻辑封装好了我只需要写渠道配置和自定义工具。1.2 飞书在这个架构里的角色飞书在整个项目里承担的是“前台”职责。它提供三样东西缺一不可消息入口用户在飞书单聊里给机器人发消息或者在群聊里 机器人飞书开放平台会把事件推送给服务端。身份体系企业内部成员天然有组织架构和权限边界机器人可以识别发送者是谁后续可以做“谁能用、谁不能用”的管控。富文本与交互能力回复内容可以支持 Markdown、卡片消息、按钮交互这比纯文本终端体验好太多。选择飞书而不是 Telegram、微信或钉钉主要是两个原因。一是飞书开放平台的文档和调试工具比较完善事件订阅支持长连接和 Webhook 两种方式开发者调试成本低二是如果你本来就在用飞书办公那么把 AI 助理放进日常办公工具里使用频率和接受度会高很多不需要额外装 App。1.3 阿里云在这个架构里的角色阿里云 ECS 提供的是“后台底座”也就是一个 24 小时不关机的运行环境。为什么不能跑在本地电脑上因为本地电脑存在休眠、断网、IP 变动的问题而 AI 助理的核心价值就是“随时在线”。阿里云 ECS 有固定的公网 IP带宽按量付费也很便宜对于个人使用场景一台 2 核 4G 的入门实例完全够用。这里有一个设计要点飞书服务端主动连接机器人还是机器人主动连接飞书服务端这决定了部署方式。如果走 Webhook回调模式飞书服务器会把事件 POST 到你的公网地址这就要求 ECS 有公网 IP并且配置好域名和 SSL 证书。如果走长连接WebSocket模式你的 ClawBot 进程主动和飞书服务器建立连接不需要公网入站端口部署更简单。我最终选择了长连接模式作为主力然后单独用 Nginx 暴露一个健康检查端口给 uptime 监控用。这样减少了一个容易被攻击的入口面也省去了回调地址调试的麻烦。整个调用的链路是这样的用户在飞书里发消息 → 飞书服务器把事件通过长连接推送到 ClawBot → ClawBot 判断意图并调用大模型 API 和工具插件 → 得到结果后通过飞书 API 回复到原会话。在这个链路里ClawBot 是中枢飞书是转化层阿里云是容器。2. 阿里云服务器基础环境配置2.1 实例选型与系统初始化我用的阿里云 ECS 实例配置是 2 核 4G、40G 云盘、按量带宽 5Mbps系统选择 Ubuntu 22.04 LTS。这个配置对 ClawBot 来说属于宽松档因为 Agent 本身的进程只占几百兆内存真正的资源消耗大头是大模型 API 的网络请求和工具执行时的临时进程。系统装好后我第一件事就是创建了一个普通用户避免直接用 root 跑服务。虽然抢时间的话 root 也能跑通但后面如果被扫描爆破成功整个服务器就裸奔了。安全组这边只放行了 22SSH、80HTTP、443HTTPS其他端口一律不放行。下面是初始化时的核心命令# 更新系统 sudo apt update sudo apt upgrade -y # 创建用户并加入 sudo 组 sudo adduser claw sudo usermod -aG sudo claw # 配置 SSH 密钥登录生产建议禁用密码登录 ssh-keygen -t ed25519 -f ~/.ssh/aliyun_claw ssh-copy-id claw你的服务器IP这里有个容易被忽略的点阿里云控制台里的“安全组”和服务器内部的 ufw/iptables 是两层独立规则两层都要放行才能通。我踩过这个坑在安全组放行了 80 端口但系统里 ufw 没放行结果 Nginx 死活访问不了。建议系统内部直接关掉 ufw 或者把规则策略设置成放行来自安全组的流量避免双重配置互相冲突。2.2 Docker 安装与镜像加速ClawBot 官方推荐用 Docker 部署我也沿用这个方式。Docker 的好处是环境隔离、升级方便尤其是后面要加插件工具时直接在容器里挂载卷就行不会把系统搞乱。安装 Docker 之后我配置了阿里云容器镜像加速器。这个加速器地址在阿里云控制台的“容器镜像服务”里可以找到每个人的专属地址不同sudo apt install -y docker.io docker-compose-plugin sudo systemctl enable --now docker # 配置加速器地址换成你自己的 sudo mkdir -p /etc/docker sudo tee /etc/docker/daemon.json EOF { registry-mirrors: [https://xxxx.mirror.aliyuncs.com] } EOF sudo systemctl daemon-reload sudo systemctl restart docker镜像加速器这个东西在跨国网络环境下差异很大不配置的话拉取镜像经常超时配置之后基本秒拉。如果你的服务器本身在国内这一步一定不要跳过。2.3 进程守护与日志管理Docker 容器默认会随着 Docker 服务启动而自动重启但容器内部进程如果崩溃需要靠 restart policy 兜底。我在 docker-compose.yml 里配置了restart: always这样遇到 OOM 或异常退出时容器会自动拉起。日志方面Docker 的 json-file 日志驱动默认无限增长时间长了会撑爆磁盘。我在 daemon.json 里加了日志轮转{ log-driver: json-file, log-opts: { max-size: 20m, max-file: 3 } }这套日志策略在跑 AI Agent 时特别重要——大模型工具调用的日志量相当大每个任务动辄几十 KB不轮转的话一个月就能积累几个 G 的日志文件。我后来排查问题的时候靠这些轮转后的日志文件定位了不少工具调用异常所以日志不光要防爆还要保证保留最近几天的量。3. ClawBot 安装与核心配置3.1 获取镜像与容器编排我用的部署方式是 docker-compose因为后续要同时启动 ClawBot 主服务和一个监控组件。先创建一个项目目录把编排文件放进去mkdir -p ~/clawbot cd ~/clawbotdocker-compose.yml 的结构大概是这样的version: 3.8 services: clawbot: image: ${CLAWBOT_IMAGE:-clawbot/core:latest} container_name: clawbot restart: always env_file: - .env volumes: - ./data:/app/data - ./config:/app/config ports: - 127.0.0.1:8080:8080 environment: - TZAsia/Shanghai注意我把端口绑定到了127.0.0.1:8080而不是0.0.0.0:8080。因为 ClawBot 的调试接口不需要暴露到公网如果绑到 0.0.0.0等于把管理端裸奔在公网上扫描器分分钟就能探测到。如果需要外网访问再加一层 Nginx 做反向代理和认证这样更安全。3.2 环境变量与大模型接入ClawBot 的配置通过.env文件管理核心包含大模型 API、飞书应用凭证、以及各插件的密钥。我用的模型服务是阿里云百炼上的通义千问系列兼容 OpenAI 的接口格式所以配置起来很顺。这里给出一个脱敏后的例子# 大模型配置通义千问 LLM_PROVIDERqwen LLM_API_KEYsk-xxxxxxxxxxxx LLM_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 LLM_MODELqwen-plus # 飞书应用配置 FEISHU_APP_IDcli_xxxxxxxx FEISHU_APP_SECRETyyyyyyyy FEISHU_ENCRYPT_KEYzzzzzzzz FEISHU_VERIFICATION_TOKENvvvvvvvv # 其他可选插件密钥 WEATHER_API_KEY SERP_API_KEY大模型的选型我后来做了几次调整。qwen-plus 平时对话够用但涉及复杂工具编排时我切到了 qwen-max 或者 DeepSeek效果更好。ClawBot 也支持同时配置多个模型实现按场景路由简单问答用 qwen-turbo复杂任务用 qwen-max。这个配置可以按需调整省钱和效果能兼顾。这里要特别提醒API 密钥千万不要写进代码或提交到 Git 仓库。我见过不少人在 config 文件里硬编码密钥后不小心推到 GitHub几分钟内就被爬虫抓走盗刷额度。.env文件要加入.gitignore服务器上的文件权限也改成 600。3.3 插件与工具集的注册机制ClawBot 真正的威力在于插件机制。默认安装后我启用了以下几个插件web-search网页搜索结果弥补大模型知识截止日期的问题。url-reader读取指定 URL 的正文内容做摘要或提炼重点。定时任务通过自然语言创建提醒和定时消息。自定义脚本执行这个是进阶玩法可以允许 Agent 在服务器上执行白名单命令比如查日志、备份数据库。插件的启用方式是在 config 目录下维护一个plugins.yamlplugins: web-search: enabled: true provider: bing url-reader: enabled: true scheduler: enabled: true shell: enabled: false # 默认关闭需要显式开启 allowlist: - df -h - uptime - docker psshell 插件我强烈建议默认关闭。虽然允许 Agent 执行命令很方便但这等于把一把远程命令执行的钥匙交了出去。如果要开必须配合白名单和用户权限控制绝不能给 root 权限。我实际跑了几周发现真正高频的需求其实也就是查磁盘、看进程这些只读命令白名单完全可以覆盖。4. 飞书应用接入全过程4.1 在飞书开放平台创建企业自建应用接入飞书的第一步是到飞书开放平台open.feishu.cn创建一个企业自建应用。登录后选择“开发者后台”→“创建企业自建应用”填写应用名称和描述比如我就叫它“ClawBot 助理”。创建完成后需要在应用功能里开启“机器人”能力。这一步会在飞书客户端里生成一个机器人账号用户可以通过搜索应用名称找到它并开始单聊。然后需要拿到三个关键凭证App ID应用的唯一标识。App Secret调用服务端 API 时签名使用。Verification Token / Encrypt Key事件订阅的校验凭证。这三个值在“凭证与基础信息”和“事件订阅”页面里都有复制到前面提到的.env文件里。有一点要注意App Secret 只会在创建时完整展示一次如果忘记了只能重置重置后需要同步更新服务器配置。4.2 事件订阅长连接模式 vs Webhook 模式飞书机器人要接收消息必须在“事件订阅”里配置监听消息事件。订阅的事件类型是im.message.receive_v1即收到消息事件。这里有两种接收方式我简单对比一下对比项Webhook 模式长连接模式服务器要求需要公网 HTTPS 回调地址仅需可访问外网即可SSL 证书必需且证书需有效不需要事件推送延迟低低长连接保活运维复杂度需管理回调地址、重试机制连接由 SDK 维护自动重连适用场景已有域名和网关个人项目、快速上线我一开始用的是 Webhook 模式因为想统一走 Nginx 和 SSL但后来发现飞书回调里有个加密请求体的校验逻辑调试起来比较繁琐。长连接模式在 ClawBot 里只配置 App ID 和 App Secret 就够了SDK 会自己维持连接明显省事。如果你的安全要求没那么严格优先长连接模式。如果选择 Webhook 模式需要注意回调地址必须返回特定的校验响应。飞书服务器发送 URL 验证请求时你的服务端需要解密后返回{challenge: xxx}这种格式否则验证不通过。我当时在这里卡了半天就是因为返回了普通的成功响应没有带 challenge 字段。4.3 权限与发布上线飞书应用的权限管理比较严格机器人只有在申请了对应权限并且应用发布后才能正常收发消息。我开通的权限主要是这几个im:message读取单向聊天消息。im:message.group_at_msg接收群聊中 机器人的消息。im:message.send_as_bot以机器人身份发送消息。这些权限的申请方式在开放平台“权限管理”页面里搜索对应权限码点击开通即可。开通后需要发布应用版本然后由企业管理员审核通过。如果是自建企业管理员通常是你自己点一下审核就过了。权限这个环节有一个容易被忽视的地方通过 API 查阅权限和事件订阅所需的权限是分开的。即使你订阅了事件如果对应的权限没开事件照样推送不过来。所以排查“机器人收不到消息”时除了看网络和配置还要去权限管理页面确认是否已经开通并发布了新版本。4.4 把 ClawBot 和飞书绑定起来所有配置完成后启动 ClawBotcd ~/clawbot docker compose up -d docker compose logs -f clawbot启动日志里如果看到“Feishu adapter connected”之类的信息就说明长连接已经建立。此时去飞书里给机器人发一条“你好”正常情况下会收到回复。我在日志里还发现过一个关键细节飞书的事件推送是异步的ClawBot 处理完消息后通过 API 主动发送回复。如果 AI 任务执行时间较长比如调用搜索工具加上多轮推理飞书客户端会短暂显示“消息发送中”这时候不要以为是卡住了耐心等一下就好。5. 从“能聊天”到“会干活”贾维斯功能落地5.1 基础对话与上下文记忆跑通基础对话后第一个要调的是上下文记忆。ClawBot 默认会维护每个会话的上下文窗口但窗口大小和清理策略会影响长对话的效果。我遇到的典型问题是单聊里聊了几轮之后再问跟前面相关的问题它居然忘了。后来发现是上下文窗口太小被早期对话内容挤掉了。把配置里的max_context_messages调大比如从 10 调到 20同时设置一个合理的超时时间超过 30 分钟没有新消息的会话自动清理这样既保证短期记忆够用又不会让无意义的上下文占用 token。飞书场景里还有一点值得一提群聊和单聊的上下文是隔离的。群聊中 机器人时机器人只看到被 的那条消息以及它自己参与的最近几条消息这是防串频的关键机制。如果希望群聊里所有人共用上下文那需要在 ClawBot 的渠道配置里打开“群聊共享上下文”开关但这样容易导致 A 聊的内容被 B 的提问干扰我建议保持默认隔离。5.2 让 Agent 具备联网搜索能力对于 AI 助理来说联网搜索几乎是刚需否则问个“今天有什么重大新闻”或者“某软件最新版本是多少”就直接原地升天。我配置了内置的搜索工具使用上很简单在飞书里对 ClawBot 说“帮我搜一下 ClawBot 的最新版本信息”它会自动调用搜索插件把结果整理后回复。这个过程可以通过日志清晰看到框架记录了一次搜索请求带上查询词拉回结果后交给大模型提炼。这里有一个调优点搜索结果很多的时候大模型会把大量内容塞进上下文导致 token 消耗暴增。我建议在插件配置里把搜索结果数量限制在 5 条以内只保留标题、链接和摘要把全文链接作为后续访问的资源。5.3 接入日历和待办实现真正的“助理”感“贾维斯”的核心体验是“你说一句话它帮你把事情办了”。光会搜索还不够还得能安排日程、管理待办。飞书多维表格在这里正好派上用场。我的做法比较取巧不需要单独开发一个日历服务而是让 ClawBot 在收到“创建待办”指令时调用一个自定义工具把任务写入飞书多维表格。实现思路如下在飞书多维表格建一个“待办事项”数据表字段包括任务名称、负责人、截止时间、状态。给飞书应用申请多维表格的读写权限bitable:app。在 ClawBot 里注册一个create_todo(task_name, deadline, owner)工具内部调用飞书 Bitable 的 API 写入记录。当我对机器人说“周五下午三点提醒我交周报”ClawBot 会解析出任务名“交周报”、截止时间“周五 15:00”然后调用多维表格 API 插入记录。后续我可以自己在表格里查看和打勾也可以在机器人里问“我有哪些未完成待办”它会反过来查表格。这种用“多维表格当后端数据库”的思路对个人项目和中小团队都非常实用。你不用单独维护一个数据库服务表格本身自带权限管理、移动端查看、富文本能力等于白赚了一个管理后台。5.4 定时任务能力的实现细节一个真正的 24 小时助理不能只会你问它才答还得能主动给你发消息。比如每天上午九点推送新闻摘要、每周一推送上周数据报表。ClawBot 内置的 scheduler 插件就是干这个的。配置定时任务的流程是先启用 scheduler 插件。创建任务时指定触发时间和目标会话目标会话可以是某个群聊的 chat_id也可以是某人的 open_id。任务触发后ClawBot 会把任务内容当作一个用户消息注入流程由大模型生成回复并推送到目标会话。我实际用的一个功能是每天早上 8:30机器人会主动在管理群里发一条“早安”消息内容包括当天的天气、待办事项数量以及一个简短新闻摘要。这个功能实现后飞书群瞬间有了“助理在场”的实感。这里有个容易翻车的点时区配置。服务器和 ClawBot 容器默认是 UTC 时区如果你不把TZAsia/Shanghai写进环境变量定时任务会和北京时间差 8 个小时。我最早配置的 8:30 任务连续两天在 16:30 触发查了半小时才发现是时区问题。5.5 从通用大模型到私有知识库工作场景里经常有“读一下这份需求文档提炼关键决策”的需求。基础版 ClawBot 只认公开请求文档内容如果不在上下文中它就无从下手。我把私有知识库集成进来用的是“训练”之外的另一条路线——RAG检索增强生成。简单说就是把文档切片后存入向量数据库当用户提问时先从库里检索相关内容再把匹配片段和大模型组合生成回答。在 ClawBot 里加 RAG 的能力可以通过官方支持的向量存储插件配置大概分三步准备一个文档目录把需要检索的 Markdown / PDF / DOCX 放进去。执行一次索引任务把文档切块并向量化。在飞书里直接提问Agent 会先检索再生成。我跑了一段时间的体验是RAG 对“准确引用原文”的需求帮助很大比如“我们上次例会上决定的上线时间是什么”机器人能从会议纪要里检索出来并给出原文段落。但要注意RAG 的效果严重依赖文档切块质量块太大则检索不准块太小则上下文不完整需要根据文档类型调出一个合适的切块大小。我试出来的经验是普通纪要类文档用 512 字符一档比较合适兼容性和准确率比较均衡。6. 常见问题与排查技巧实录6.1 飞书回调验证失败Webhook 模式下最常见的报错就是 URL 验证不通过。飞书服务器会向你的回调地址发送一个 GET 请求带上challenge参数你的服务端需要在响应体中原样返回这个值。但如果你用的是 ClawBot 的默认配置它应该会自动处理这个逻辑。我遇到的实际问题是Nginx 配置里没有正确透传 POST body导致飞书验证请求的包体被丢弃。排查方法很简单在 Nginx access log 里看飞书服务器的请求是否到达以及返回状态码是否是 200。如果请求都没打过来先查安全组和域名解析。6.2 机器人不回复但日志也没报错这种情况最迷惑。日志显示收到了事件但飞书里没有回复。我排查后发现是消息发送权限没开。飞书机器人发送消息需要im:message.send_as_bot权限而接收消息调用的是另一套权限。如果你只开了收消息的权限没开发消息的权限事件照常推送但 API 发送消息时会被拒绝。解决方法是去权限管理开通发送权限重新发布应用版本等几分钟生效后再试。6.3 长任务执行超时AI 工具链路一旦复杂“搜索关键词 → 读取链接 → 总结 → 生成回复”这个过程可能需要十几秒甚至几十秒。飞书对消息回复没有强制的超时限制但用户的耐心有限。我的做法是给 ClawBot 配置了“任务进行中”的提示机制。当 Agent 识别到任务耗时较长时会先回复一条“收到正在处理中”然后异步执行完整流程执行完了再发最终结果。这种体验比干等要好得多尤其在移动端飞书里用户会对“已受理”有心理预期。实现上ClawBot 的 job 队列支持把任务放到后台执行然后通过消息回调把结果送回原会话。只需要在配置里打开异步模式并设置超时时间比如 90 秒。超过 90 秒没有结果的任务可以触发一个失败提示告诉用户“任务执行超时请简化问题或稍后重试”。6.4 进程掉线和高 CPU 排查虽然配置了restart: always但有时候容器起来了飞书长连接却断了表现为“机器人彻底失联但容器还在跑”。这类问题的本质是进程存活但业务状态异常单靠 Docker 检查不出来。我的监控方案分两层健康检查在飞书群里设置一个定时任务每天早上 9 点让机器人在自己的运维群里发一条“健康检查正常”消息如果某天没收到就说明连接有问题。外部监控用 uptime kuma 监控 ClawBot 暴露的一个轻量健康接口这个接口返回 200 代表进程存活。一旦探活失败通过飞书 Webhook 把告警推给指定人。CPU 排查方面大模型本地推理必然高占用但如果只是 API 调用CPU 应该保持低位。我遇到过高 CPU 是因为某个搜索插件的并发爬虫没有设置频率限制导致同时跑了几十个抓取任务。后来在插件配置里限制了并发数CPU 立刻降了下来。6.5 常见问题速查表症状可能原因解决办法事件订阅验证失败Nginx 没透传 body / 回调地址连不通检查安全组、Nginx 配置、返回值格式机器人收到消息但无回复发送消息权限未开通在权限管理开启im:message.send_as_bot并发布长连接频繁断开网络不稳定 / 服务器本机时间不准检查系统时区与 NTP 同步开启自动重连定时任务时间不对容器时区是 UTC设置TZAsia/Shanghai并重启容器搜索工具经常报错搜索接口限额或网络问题换搜索源、限制并发、设置重试日志文件膨胀Docker 日志未轮转配置 json-file 日志轮转并重启容器群聊里 机器人没反应机器人未进入该群 / 权限不足确认机器人已被拉入群且应用已发布6.6 安全加固的一些额外措施这个项目上线后我把安全加固也做了一遍分享几个我认为必要的操作禁止 root 远程登录SSH 配置里把PermitRootLogin改为no用 ed25519 密钥登录。密钥文件权限收紧chmod 600 .env避免其他用户读取到 API 密钥。限制管理端口访问只在安全组里放行自己的 IP 访问 SSH 端口而不是 0.0.0.0/0。容器非 root 运行ClawBot 容器如果支持配置 UID/GID尽量指定普通用户运行避免容器逃逸后直接拿到 root。沙箱工具隔离给 shell 插件设置白名单白名单之外的命令一律拒绝执行。按照我个人的经验服务器被扫描是常态阿里云控制台里每天都能看到大量来自海外 IP 的 SSH 爆破尝试。只要禁了密码登录、禁了 root基本就防住了 99% 的脚本扫描。剩下的就是定期盯一下安全组和日志别把敏感端口裸奔在公网上。7. 上线一段时间后的使用心得项目运行稳定后我最大的感受是AI 助理这种工具真正的门槛不在模型能力而在“怎么把它嵌入到日常行为里让它变成一个愿意用、也用得起来的工具”。飞书入口解决了“打开率”问题——用户本来就天天用飞书不用为了问 AI 一个问题再打开额外网页Alibaba Cloud 解决了“在线率”问题——程序 24 小时运行在云端不会因为我关上电脑就消失ClawBot 解决了“执行力”问题——它不只是回答问题还能跑搜索、查表格、发定时消息、执行白名单命令。如果你也想搭一套类似的系统我建议按下面顺序推进不要一上来就追求大而全第一周先把基础链路跑通ClawBot 部署在阿里云飞书应用创建完成能单聊能群聊能正常回复消息。第二周再加搜索和定时任务让机器人变得“有点用”。第三周再把多维表格、待办、RAG 这些进阶能力规划进去每次只加一个插件跑稳了再加下一个。还有一个小建议给机器人起一个固定名字并且在项目初期就统一在群聊和单聊里使用。因为飞书机器人的上下文是按会话隔离的你在群里聊了一段它不会自动知道你在单聊里问过什么。统一使用方式能让上下文管理更可控也方便后续扩展成多机器人分工协作。最后提醒一句任何工具能力都有边界AI 助理也不例外。让机器人执行服务器命令、访问外部网络、写数据进表格之前务必先想清楚“如果这一步执行错了最坏的后果是什么”。在边界清晰的前提下放权这个助理才能长期稳定地为你干活而不是给你添乱。