OpenClaw+Qwen+飞书：打造团队AI数字同事-平芜编程栈

前两天有个朋友拉着我诉苦，说他们团队试了好几个Agent工具，最后都卡在同一个地方：只有一个人能对着终端玩，其他人根本用不起来。我说你换个思路，让Agent主动住进你们天天用的那个聊天软件里不就行了。于是我用OpenClaw做Agent网关，Qwen（通义千问）当大脑，飞书当入口，搭了一套可以直接在聊天窗口里下指令的机器人，同事不用知道什么叫Channel、什么叫API，像多了一个会写代码、会查数据、会填表格的“数字同事”。这篇就把整个接入过程完整拆开：OpenClaw怎么安装、Qwen怎么接、飞书机器人怎么创建、channel怎么切换，以及你一定会遇到的session锁定、消息截断之类的坑。

1. 为什么要把这三样连起来：从“终端里的Agent”到“飞书里的同事”

先说结论：这套组合解决的核心问题，是让不会碰命令行的人也能用上Agent。单独跑OpenClaw，你只是在终端里跟一个AI自言自语；单独用Qwen，你得到的是一个网页对话窗口；单独看飞书，它只是个办公IM。三者接起来之后，Agent才真正变成一个“住在工作群里、随叫随到的同事”。

1.1 三者的角色划分

用一个不严谨但好理解的类比：OpenClaw是前台，Qwen是后台接电话的专家，飞书是前台的电话机。

OpenClaw：自托管的Agent框架/网关。它负责会话管理、工具调用、渠道接入。最有价值的是它的Channel机制——Channel就是“消息从哪里进来、回复送到哪里去”的通道。同一个Agent内核，接上CLI通道就是终端助手，接上飞书通道就是飞书机器人，接上Teams通道就是Teams机器人。身体不变，只是换了个跟人打交道的方式。
Qwen（通义千问）：负责“听懂人话”和“生成回复”的模型大脑。我选它不是因为别的模型不好，而是三个现实理由：中文场景表现稳、API价格亲民、有从云端到本地的完整型号谱系。尤其对国内网络环境来说，调用链路短、延迟可控，不用在模型接入上额外折腾网络。
飞书：人机交互入口。飞书机器人能以应用身份收发消息，而且支持长连接事件订阅模式，意味着Agent可以跑在家里NAS、办公室小主机、甚至一台普通笔记本上，不需要公网IP和域名就能让整个团队用起来。再加上飞书的消息卡片、文件上传、多维表格API，Agent能输出的不只是文字，还能是表格和结构化数据。

1.2 适合谁、不适合谁

这套方案不是万能的。我的经验是：适合有动手能力、想要一个可控数字员工的人，不适合只想要“开箱即用AI”的人。

适合：个人知识库助手；小团队的日报生成、数据查询、消息汇总；需要私有化部署、数据不出内网的场景；以及被商业Agent平台的价格或规则劝退，想自己掌握底层逻辑的玩家。
不适合：如果只是想快速体验AI，直接用飞书自带的智能伙伴、妙搭这类官方功能更快；如果完全不打算维护进程、备份数据，这套自托管方案对你来说就是负担；如果需要的是可视化多节点编排的复杂工作流，那应该去用专门的工作流平台，而不是在IM机器人里硬造。

我自己的判断很简单：Claw+Qwen+飞书，适合那些愿意花一个下午搞定基础设施，然后换来长期“团队AI入口”的人。接下来进入正文。

2. 先把OpenClaw装起来：三平台安装与本地channel验证

很多人在OpenClaw安装这一步就卡住，不是装不上，而是装完不知道下一步干什么。我的建议是：先别碰飞书，先把本地CLI通道跑通，让Agent在终端里能对话，然后再接飞书。这样后面排错时能清晰区分“是模型的问题”还是“是飞书通道的问题”。

2.1 安装前确认版本与环境

OpenClaw是跨平台的Agent框架，底层依赖Node.js和Python生态（具体版本要求会随版本更新变化，以官方仓库README为准）。我建议至少准备：

Node.js 18+
Python 3.10+
git
能正常访问GitHub拉取安装脚本和仓库

装之前先跑一遍环境检查：

node -v python3 --version git --version

如果版本太老，先去官网升完级再装OpenClaw。Windows用户尤其注意PowerShell的执行策略，很多时候“安装脚本跑不起来”不是脚本的锅，而是系统默认禁止执行脚本。

2.2 Windows、Linux、macOS三平台安装要点

平台	推荐方式	关键注意点
Windows	PowerShell管理员运行官方一键脚本	若报“禁止运行脚本”，先执行`Set-ExecutionPolicy -Scope Process Bypass`
Linux	`curl -fsSL 官方脚本 \| bash`	建议先建专用系统用户，避免OpenClaw以root身份常驻
macOS	Homebrew装好依赖后跑官方脚本	装完记得重启终端或手动source环境变量

具体安装命令以官方仓库README为准，因为这类项目迭代很快，脚本地址可能变。我的习惯是安装时把版本号和安装日期记一笔，方便以后升级对照。

安装完成后，先检查有没有自检命令，比如这类框架通常有openclaw --version或openclaw doctor之类的入口。跑一下，确认核心依赖都正常。这一步千万别跳，很多人装完直接配飞书，结果飞书没反应，最后发现是本地环境缺依赖。

2.3 本地channel先跑通再谈飞书

Channel这个词对新手是个门槛。简单说：Channel就是Agent跟人对话的界面，可以同时挂多个。先理解一个基础配置结构：

agents: default: model: provider: qwen model: qwen-plus channels: - type: cli

这一段配置的意思是：默认Agent用Qwen模型，通过CLI通道跟人对话。先用这种最简单的方式启动，在终端里发一句“你好”，确认模型能正常回复。如果这里就出错，大概率是第3章的模型配置有问题，跟飞书无关。

3. 接入Qwen：从API Key到模型选型的完整决策

Qwen接入是整条链路里最不容易出错的环节，因为阿里云百炼（DashScope）提供了一套OpenAI兼容接口，几乎所有Agent框架都能直接复用现成的OpenAI适配器。但这不代表不需要认真配置，尤其是模型选型和上下文窗口设置，直接影响Agent在实际使用中的稳定度。

3.1 创建密钥并配好兼容接口

先到阿里云百炼控制台开通模型服务，然后创建一个API-KEY。这个Key只在创建时完整显示一次，务必立刻存到安全的地方。我的做法是放在项目目录的.env文件里：

export DASHSCOPE_API_KEY="sk-你的密钥"

OpenClaw这类框架配置模型时，一般需要指定三样东西：接口地址、密钥、模型名。接口地址固定填DashScope的OpenAI兼容模式地址：

https://dashscope.aliyuncs.com/compatible-mode/v1

填好之后相当于告诉OpenClaw：“我要找一个长得像OpenAI的接口，协议不变，只是域名换成阿里云的”。这也是Qwen能无缝进各种框架的原因——协议统一，省去SDK适配的成本。

3.2 型号怎么选：Turbo、Plus、Max、Long与本地量化

Qwen不是只有一个模型，而是一个家族。我第一次踩的坑是全都用Max，结果又慢又贵；后来发现不同任务应该选不同型号。

型号	定位	我实际使用的场景
qwen-turbo	轻量、便宜、低延迟	日常问答、消息总结、触发词判断
qwen-plus	均衡型，性价比高	默认主力，多数业务Agent选它
qwen-max	强指令遵循、复杂推理	多步工具调用、代码生成、关键任务
qwen-long	百万级长文本窗口	长文档总结、切片分析
本地部署（qwen2.5系列量化版）	数据完全私有	内网隔离环境、隐私敏感数据

我自己在OpenClaw里的默认方案是：主力用qwen-plus，遇到Agent工具调用乱套、不按格式输出时临时切到qwen-max。很多“Agent突然不说话了”的假故障，其实是模型能力不够，不是框架问题。

3.3 上下文窗口：不是越大越好

上下文窗口决定一次对话能装下多少历史。但记住：窗口里塞的不只是你和Agent的聊天记录，还有系统提示、工具定义、工具返回结果。一个典型的多步工具调用，可能一次就消耗几千token。

大窗口看起来美好，代价却是延迟变高、成本增加、框架把超出窗口的旧消息粗暴截断后Agent“突然失忆”。我的三点经验：

系统提示控制在500 token内，把最重要的规则写清楚，废话删掉；
工具定义精简化，只留用得到的函数；
给Agent设置输出上限，避免单次回答过长。

一个比较稳的模型配置长这样：

model: provider: qwen model: qwen-plus base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1" max_tokens: 2048 temperature: 0.3

temperature调低到0.3左右，适合工具调用和数据任务，回复会更稳定；如果希望Agent更有“创造力”，再往上调。

4. 飞书侧配置：机器人创建、权限申请与长连接事件订阅

到了这一章，你的Agent已经有“大脑”了，接下来给它装一个“办公室座机”。飞书侧配置的核心是三步：建机器人、配权限和事件订阅、把OpenClaw的channel切过去。这里最容易翻车的是权限和事件订阅方式，很多人默认以为必须配公网回调域名，其实飞书支持长连接，这一步能省下大量折腾。

4.1 创建一个企业自建应用机器人

打开飞书开放平台（open.feishu.cn），创建一个企业自建应用。名字随便起，我一般叫“数据助手”或“项目助理”。创建后进入应用后台，在“应用能力”里启用机器人能力。

创建成功后，你会拿到两个关键凭据：

App ID：应用的身份标识，形如cli_xxxxxxxx
App Secret：应用密钥，调用API时用于换取access_token

这两个值就是OpenClaw连接飞书的核心凭据。还有一个特别容易卡住的地方：新应用默认是“开发中版本”，只有创建者自己能在飞书里搜到。想让同事也能用，必须点“创建版本/发布上线”，并设置好可用范围。否则你部署半天，同事在飞书里找不到机器人。

4.2 权限与事件订阅：优先用长连接模式

机器人建好后，别急着去配OpenClaw，先把权限开了。基础消息能力需要申请：

im:message—— 接收用户发给机器人的消息
im:message:send_as_bot—— 以机器人的身份发送消息

如果后面要做多维表格操作，还要追加bitable:app、bitable:record之类的权限。权限申请后通常需要企业管理员审核，自建应用一般很快。

然后是最关键的事件订阅。飞书默认会引导你配置“请求地址”（回调URL），用来接收消息事件。但如果你没有公网服务器、没有域名，这条路很难走。飞书早就支持长连接模式：Agent主动跟飞书服务器建立持久的WebSocket连接，事件通过这条长连接直接推过来，完全不需要公网IP。

对OpenClaw这种自托管方案，长连接模式是唯一推荐。家庭宽带、公司内网、临时开发机都能跑，不用做内网穿透，不用配HTTPS证书，省掉一大半网络层面的坑。

在事件订阅里添加事件im.message.receive_v1，这是“用户给机器人发消息”的触发器。

4.3 在OpenClaw里把channel切换到飞书

准备好App ID和App Secret后，在OpenClaw配置里把channel加进去。框架内置的飞书通道类型名可能是feishu或lark，以当前版本文档为准，但配置结构大致是这样：

channels: - type: feishu app_id: "cli_xxxxxxxx" app_secret: "xxxxxxxx" event_mode: websocket

重启OpenClaw服务，观察启动日志。如果看到飞书通道连接成功的提示，基本就成了一半。然后到飞书里找到你的机器人，发一条“你好”测试。此时大概率会遇到两类问题：一类是消息发过去没反应，另一类是回复到一半被截断，第5章展开讲。

5. 联调与经典排错：session locked、消息截断、没有回复

联调测试是所有人最头疼的阶段，但好消息是：常见故障就那几种，根因很集中。我按“先确认链路、再逐个击破”的顺序讲，你按这个顺序排查能省很多时间。

5.1 首次联调的四步走

确认应用已发布且自己可见：在飞书里能搜到机器人，否则一切白搭；
确认事件订阅已生效：长连接模式下，OpenClaw日志会显示连接建立成功，消息进来会打request id；
看OpenClaw日志：如果收到消息但Agent没回，去看模型调用是否报错；如果日志里压根没显示收到消息，问题出在飞书权限或事件订阅；
最小化提问：先问“1+1等于几”，验证链路通了再上复杂任务。

这一步建议别跳过。我见过太多人一上来就让Agent做“分析上个月销售数据并生成报告”，结果模型、工具、通路三个环节同时出问题，根本无从下手。

5.2 “agent failed before reply: session file locked”完整排查链路

这个报错在OpenClaw用户里非常常见，日志大概是：

agent failed before reply: session file locked (timeout 60000ms)

先说原理。Agent框架为了防止同一个会话的多个请求互相覆盖，会为每个session生成一个锁文件，表示“这个会话正在被处理中”。正常流程是请求处理完就释放锁，但如果前一个请求异常退出，锁没有释放，新的请求就会等锁，等到60秒超时就直接报错。

常见触发场景有四类：

可能原因	快速判断方法	处理方式
锁文件残留	进程已退出，但session目录里还有.lock文件	备份后删锁，重启
同会话并发冲突	同一用户连发多条消息，或飞书重复推送事件	按会话拆分或开启消息排队
超时设置过短	复杂任务处理超过60秒，锁没等完	调大lock timeout
数据目录问题	读写session时频繁IO异常	把session目录迁到本地SSD

完整排查链路如下：

先看进程列表，确认没有多个OpenClaw实例同时跑同一个数据目录；
找到session目录（一般在~/.openclaw/sessions或项目目录下的sessions/），查看是否存在.lock文件；
备份后删除锁文件，重启服务再测；
如果删除后仍复现，基本断定是并发问题——同一个用户连续发消息触发了同session竞争；
针对并发，在配置里把锁等待时间从默认的60000ms调大，或者为每条飞书消息绑定独立的会话ID，避免所有请求挤同一个session。

这个报错的本质是“Agent的会话管理策略太谨慎了一点点”。大部分情况下删锁重启就能解决，但它提醒了一件事：生产环境务必给OpenClaw加进程守护，避免进程被杀后锁文件残留影响后续请求。

5.3 飞书输出被截断的三种治标方法和一个治本思路

“OpenClaw在飞书输出容易被截断”这个问题，基本每个用飞书channel的人都会遇到。原因是飞书机器人单条文本消息有长度上限，而Agent生成的回答一旦太长，整段发出去就会被截断，用户看到的是戛然而止的半截话。

三种治标方法：

调小输出上限：把max_tokens从2048降到1024，从源头掐断长回复；
系统提示里加长度约束：比如要求“回复控制在800字以内，分点输出，每点不超过200字”，让模型自己克制；
开启分段发送：一些框架支持最大消息长度配置，超过就自动拆成多条发送。

这三种我都试过，最常用的是第二种，因为不改框架参数、不牺牲模型能力，只是用提示词约束输出风格。

但治本思路其实是另一个方向：别让Agent直接甩大段文本，让它输出结构化数据，再由脚本负责排版。举个例子，我需要Agent在飞书里发一份数据报告，不是让它“写一段关于销售情况的文字”，而是让它输出JSON格式的报告内容，然后发送脚本把它渲染成一张飞书消息卡片。模型只负责决策和生成内容，格式、分页、切割全部由代码保证，这样从根本上绕开“长文本被截断”的问题。

6. 进阶玩法：让Agent在飞书里“干活”，不只是聊天

通道通了、排错也兜住了，接下来才是这套组合真正值钱的地方：让Agent往飞书里写表格、发文件、操作多维表格。你会发现，它从一个“会聊天的机器人”变成了“会干活的数字员工”。

6.1 让机器人发送真正的表格文件

飞书的聊天窗口支持文件消息，这意味着Agent可以把查询结果导出成CSV或Excel直接丢到群里。这个能力对业务团队太有用了——以前他们要自己复制粘贴，现在只需要对机器人说一句“把本周订单明细导出发到群里”。

实现思路分两步：第一步，Agent生成CSV文件；第二步，调用飞书上传文件接口，拿到file_key后发送文件消息。简化后的Python调用大概是这样的（实际框架里用Agent的工具函数封装）：

import requests def send_csv_file(access_token, chat_id, file_path, file_name): upload_url = "https://open.feishu.cn/open-apis/im/v1/files" with open(file_path, "rb") as f: resp = requests.post( upload_url, headers={"Authorization": f"Bearer {access_token}"}, data={"file_type": "stream", "file_name": file_name}, files={"file": (file_name, f, "text/csv")}, ) file_key = resp.json()["data"]["file_key"] message_url = "https://open.feishu.cn/open-apis/im/v1/messages" payload = { "receive_id": chat_id, "msg_type": "file", "content": f'{{"file_key":"{file_key}"}}', } requests.post( message_url, headers={"Authorization": f"Bearer {access_token}"}, json=payload, )

注意，这里receive_id的类型（open_id、chat_id等）得按你的实际场景填对，否则飞书会报错“receiver not found”。这类问题用“多看官方文档的鉴权说明”基本能解决。

6.2 把结果写回飞书多维表格

如果说发文件是“给结果”，那写多维表格就是“参与工作流”。一个典型场景：Agent把每天收集到的线索按字段写到一张多维表格里，团队所有人只需要维护一张表，不用的杂七杂八的文档。

实现步骤不复杂：

在飞书里建一张多维表格，从URL里找到app_token和table_id；
在飞书开放平台给应用加多维表格权限；
Agent通过飞书的bitable API往指定表里写记录。

核心API长这样：

curl -X POST "https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records" \ -H "Authorization: Bearer {tenant_access_token}" \ -H "Content-Type: application/json" \ -d '{ "fields": { "任务": "生成周报", "状态": "完成", "负责人": "张三" } }'

这里最容易踩的坑是字段类型不匹配：多维表格里的数字字段不能传文本，日期字段要传毫秒级时间戳或ISO格式。报错时先检查字段类型，再检查字段名是否一致。把这条API封装成Agent的一个工具函数之后，Agent就能在对话里直接往多维表格落数据，整个团队的工作流会顺畅很多。

6.3 另一种形态：CLI会话桥接路线

最后说一个经常被放在一起讨论的备选方案：直接把飞书消息桥接进本地CLI工具。热词里出现的“windows claude code cc-connect 飞书”和“mac claude cli 用qwen key”，指的都是这个方向。

原理很简单：飞书机器人收到消息后，转交给本地正在运行的命令行Agent进程（比如Claude Code/Claude CLI），再把命令行输出发回飞书。配置上，本地CLI通过环境变量把模型指向Qwen的兼容接口，密钥用DASHSCOPE_API_KEY，相当于给CLI工具换了个Qwen大脑。

跟OpenClaw方案对比如下：

维度	OpenClaw方案	CLI桥接方案
会话管理	框架自带，适合多人多会话	依赖CLI自身的会话模型，偏单机
工具调用	框架内统一配置	取决于CLI插件生态
部署复杂度	需要完整服务化	简单，但常驻进程管理要自己操心
适合场景	团队级Agent服务	个人开发者深度使用

两个方案不冲突。我现在的环境就是两个都在跑：OpenClaw负责团队公共入口，CLI桥接留给自己做深度开发调试。选择哪个不是“哪个好”，而是“你当前需要什么”。

最后回到我个人实际使用的一些体会。这套组合搭完之后，真正改变的不是技术架构，而是团队使用AI的方式：同事不再需要申请一个账号去某个网页里跟AI对话，他们在飞书里像发消息一样把活儿派下去，Agent完成后把结果用文件或表格形式丢回群里。踩过几次坑之后，我的最大心得是——遇到“机器人不理人”先看日志，不要瞎重装；遇到“回复被截断”先想是不是消息超长，不要急着怪模型；遇到session file locked先删锁重启，不要怀疑是模型挂了。最后分享一个小技巧：把每一次排错的过程记成简短的问题模板，比如“飞书没回复-查事件订阅-查日志-查session锁”，团队里有人遇到同类问题直接按模板排查，能省下大量时间和沟通成本。