最近在帮某团队搭一个能直接拉进飞书群、被一下就能回答问题的AI助手原以为只是“装个服务、填个密钥”的简单活结果在LLM接入、飞书权限和进程守护上花了不少时间。最后在Ubuntu 24.04上把OpenClaw、Kimi 2.5和飞书完整打通从零到能稳定对话大概用了一天。这篇文章就是把整套流程拆开讲清楚包括环境依赖、模型参数、飞书应用配置、systemd自启以及我实际踩过的几个坑给正在折腾同样组合的人省点时间。这个方案适合两类人一是有Ubuntu服务器或闲置PC想给团队或者自己搭一个飞书AI机器人的开发者二是已经跑过OpenClaw但还卡在模型渠道和飞书通道上的折腾型选手。无论哪一类耐心看完都能直接照搬。1. 为什么“OpenClaw Kimi 2.5 飞书”是服务器上很顺手的AI接线方案先说结论这个组合的本质是把“对话入口”和“推理大脑”拆开再用一个轻量网关把它们粘在一起。听起来绕拆开看其实很简单。1.1 这三个组件各自扮演什么角色OpenClaw是一个消息平台适配网关它统一处理各个IM渠道收发的消息把消息转成LLM能理解的结构化请求再把LLM的回复发回原来的会话。它的价值在于不用为每个聊天平台单独写SDK封装、回调解析、会话管理一个程序就能把不同渠道都接进来。Kimi 2.5在这条链路里是“推理大脑”负责理解用户问题并生成回答。我选择它主要是因为中文语义理解好、长上下文窗口在同价位模型里很能打尤其是团队内部文档、代码片段这种内容它处理起来比较稳。飞书则是“用户界面”。对比几个常见办公IM飞书的开放平台对机器人很友好应用创建门槛低事件订阅支持长连接模式不需要公网回调地址这点对没有公网IP的服务器非常关键。用户在飞书群里直接机器人体验和用原生AI应用没差别。1.2 这个方案解决了哪些实际问题团队里真正高频的需求往往不是什么复杂的知识库问答而是几个简单场景群聊里有人问“这个需求排期怎么定的”机器人能把历史上下文拉出来给一个结构化回答让AI整理一长串聊天中的待办事项直接贴到群公告把飞书当API入口让机器人执行部署命令、查服务器负载、拉日志。这些需求如果用低代码平台或者现成SaaS机器人也能实现但往往受两个限制一是入口不够灵活没法同时接飞书、Telegram等渠道二是模型能力被锁死不给你随便换推理引擎。自己部署OpenClaw数据在自己服务器上模型也可以随时切换自由度完全不同。注意我下面提到的配置文件字段名和命令在不同版本里可能略有出入。所有路径以你实际安装的版本为准但整体结构是通用的。2. Ubuntu 24.04上把OpenClaw本体跑起来依赖安装与目录规划OpenClaw本身是编译好的二进制不需要装Python环境或者Node.js这点比很多AI网关都省心。但Ubuntu 24.04是较新的系统有些基础工具默认没带全先把环境收拾干净再继续。2.1 先装好通用的环境依赖登录服务器先更新软件源并安装基础工具sudo apt update sudo apt upgrade -y sudo apt install -y curl wget git tar jqcurl和wget用来下载安装包jq是为了后面调试API返回时格式化JSONgit有时候需要拉取配置模板。这几个包都很小装上不会污染系统。接下来确认系统的架构uname -m如果是x86_64直接用amd64的二进制如果是aarch64就得找arm64版本。这个细节很多人会忽略下载了不匹配的包之后运行时会直接报Exec format error非常影响排查进度。2.2 下载OpenClaw并初始化工作目录在GitHub Releases或其他官方分发渠道找到对应版本下载后解压到服务器。我习惯把二进制放到/usr/local/bin这样全局PATH都能访问curl -L OpenClaw官方下载地址 -o openclaw.tar.gz tar -xzf openclaw.tar.gz sudo install -m 0755 ./openclaw /usr/local/bin/openclaw安装完成后先验证一下版本openclaw --version能正常输出版本号说明二进制没问题。接下来创建工作目录我统一把运行时的数据放在一个独立目录里避免和系统文件混在一起mkdir -p ~/.openclaw/config mkdir -p ~/.openclaw/logsconfig放配置文件logs放日志。这样设计的好处是后续做备份、迁移、恢复都方便只需要打包一个目录就行。2.3 确认能否生成基础配置启动之前先跑一次初始化命令看OpenClaw是否能自动生成一个默认配置模板openclaw init --config ~/.openclaw/config/openclaw.yaml如果命令不存在说明版本没有提供init子命令那就直接手动创建配置文件touch ~/.openclaw/config/openclaw.yaml基础配置里一般包含几个大块日志级别、监听端口、LLM配置、渠道配置。初期不需要填得太多先把最小可运行版本跑通再逐步添加Kimi和飞书配置。3. 接入Kimi 2.5API密钥、模型名与参数调优OpenClaw只是个网关不会自己思考所以LLM配置是整个链路里最关键的一环。Kimi 2.5接入这一步说穿了就是“拿到密钥、填对模型名、调好参数”但实际操作中很多人栽在“模型名写错”“Base URL多了一个斜杠”“超时时间太短”这类小问题上。3.1 在模型服务方获取API密钥去Kimi 2.5对应的模型服务控制台创建一个API Key记下两个关键信息API Base URL也就是请求地址API Key本身一串以sk-开头的字符串。申请密钥的时候建议先创建一个独立密钥只开通当前项目需要的权限不要直接复制主账户的全局Key。很多团队都是因为密钥权限过大导致服务器被扫码后泄露了完整的模型额度。复制下来的密钥先放到一个临时环境变量里避免在聊天记录中暴露export KIMI_API_KEYsk-你的密钥3.2 修改OpenClaw配置文件打开刚生成的openclaw.yaml在LLM配置区域填入以下内容。以我部署时的简化配置为例llm: provider: openai base_url: https://api.kimi.example.com/v1 api_key_env: KIMI_API_KEY model: kimi-2.5 temperature: 0.7 max_tokens: 4096 timeout: 60有几个字段要特别注意providerKimi的API是OpenAI兼容格式所以provider一般填openaiOpenClaw会用OpenAI这种协议去请求。base_url必须以/v1结尾很多网络请求失败就是这里少写或多写了路径。api_key_env这个配置项很实用它让OpenClaw从环境变量读取密钥而不是直接写在配置文件里。这样即使配置文件被人看到密钥也不会直接暴露。timeout长文档问答经常超过30秒所以超时时间不要小于60秒否则只是稍微想久一点渠道就把请求判死了。3.3 温度、上下文的权衡temperature控制回答的随机性。做客服、答疑类场景建议调到0.3到0.5回答更稳定如果做头脑风暴、文案生成可以放开到0.8以上。我日常给团队用是0.5既能保证事实性回答的准确性又不会显得太机械。max_tokens要看实际用途。普通聊天2048就够但如果经常让AI总结长会议纪要建议提到4096以上否则回答会被截断在中间。如果模型支持stream流式输出OpenClaw配置里也可以打开llm: stream: true流式输出的体验更像打字机响应延迟感会低很多。不过要注意部分渠道版本对流式消息的兼容性有差异跑通之后再开也不迟。关键点修改完配置后一定要用openclaw config test这类的校验命令检查一下或者直接重启服务看日志。配置字段没报错不代表密钥能用最好用curl手动请求一次API确认密钥有效再往下走curl https://api.kimi.example.com/v1/chat/completions \ -H Authorization: Bearer $KIMI_API_KEY \ -H Content-Type: application/json \ -d {model:kimi-2.5,messages:[{role:user,content:你好}]}能正常返回JSON说明模型渠道彻底通了。4. 飞书渠道开放平台应用、权限点和事件订阅飞书渠道是整个部署里最容易让人困惑的一环因为它不是简单填一个Webhook地址就完事而是要经历“创建应用-配置权限-开启事件订阅-填入认证信息”这一整个流程。这里我按实际操作顺序一步步说。4.1 在飞书开放平台创建应用进入飞书开放平台后台点击“创建企业自建应用”应用类型选择“企业自建”。创建完成后会进入应用详情页这时能拿到两个核心凭证App ID形如cli_开头的一串字符App Secret应用密钥。这两个值就是OpenClaw连接飞书的“账号密码”要保存好。在应用详情页里还需要给应用开通“机器人”能力这样应用才能在飞书里以机器人的身份发言。4.2 配置权限点和事件订阅机器人要收发消息必须获得对应权限。在“权限管理”页面搜索并开通以下权限项权限名称用途im:message读取用户发给机器人的单聊消息im:message:send_as_bot以机器人身份发送消息im:message.receive_v1接收消息事件订阅contact:user.base:readonly读取用户基础信息用于识别发送者权限开通后进入“事件订阅”页面这是最容易卡住的地方。飞书支持“长连接”模式和“Webhook回调”模式两种事件接收方式Webhook模式需要提供一个公网可访问的HTTPS回调地址配置要求高且必须通过域名校验长连接模式由飞书开放平台与服务端建立WebSocket连接不需要公网IP也不需要在服务器上配置证书。像我这种服务器没有公网暴露端口的场景直接选择“使用长连接接收事件”然后订阅接收消息事件也就是message.receive_v1。这里有个常见的坑权限开通了但事件订阅没订阅机器人就收不到任何消息。所以每一步都要确认状态是“已开通”而不是“已申请”。4.3 在OpenClaw配置中写入飞书认证信息回到OpenClaw配置文件在channels区域增加飞书渠道配置。以实际部署时使用的简化版本为例channels: feishu: enabled: true app_id: cli_xxxxxx app_secret: 你的AppSecret encrypt_key: verification_token: use_websocket: true字段说明use_websocket对应飞书的长连接模式。保持true就不需要公网回调。encrypt_key和verification_token如果飞书应用开启了“加密策略”这里要填入对应的值。如果没开启保持空字符串即可。配置完成后建议立刻重启OpenClaw观察日志里是否出现“飞书连接成功”之类的字样。长连接模式下日志会显示WebSocket已建立、开始监听事件。如果一直提示连接失败优先检查App ID和App Secret是否复制错了——这类问题我遇到很多次大多是因为把密钥末尾的空格带进去了。4.4 用户私聊与群聊的差异飞书里机器人可以同时在单聊和群聊场景使用但两种场景的配置逻辑略有不同单聊用户直接给机器人发消息飞书会自动触发事件OpenClaw拿到消息后直接回复到单聊会话。群聊机器人需要在群里被才会响应。在事件订阅里要确保有“接收群聊中机器人的消息”的设置否则机器人会对群内消息视而不见。部署完成后我建议先私聊测试一次再拉群做群聊测试。如果私聊通了但群聊没反应不用怀疑模型配置直接去飞书后台看“机器人设置”里的群消息权限。5. 启动、自启与联调从上线到稳定运行前面的配置都完成后就到了真正启动和验证的环节。这部分我会给出完整的启动流程、systemd守护方案以及我在实际运行中总结出来的常见故障排查清单。5.1 第一次启动该怎么观察启动OpenClaw之前先确认环境变量已经生效source ~/.bashrc echo $KIMI_API_KEY然后前台方式启动便于直接看日志openclaw serve --config ~/.openclaw/config/openclaw.yaml第一次启动不要加-d或者后台运行这样日志会直接打印到终端。看到类似“server started”“listening”“feishu websocket connected”的日志后再按CtrlC停掉改成后台运行。我第一次部署时就因为直接加了nohup后台运行没看到启动报错结果飞书消息发过去石沉大海回头查日志才发现飞书密钥校验失败。所以这个阶段一定不要跳过前台观察。5.2 用systemd做进程守护OpenClaw作为常驻服务需要开机自启和进程守护。直接写一个systemd服务是最稳妥的做法[Unit] DescriptionOpenClaw AI Gateway Afternetwork-online.target Wantsnetwork-online.target [Service] Typesimple User你的用户名 Group你的用户组 EnvironmentKIMI_API_KEYsk-你的密钥 ExecStart/usr/local/bin/openclaw serve --config /home/你的用户名/.openclaw/config/openclaw.yaml Restartalways RestartSec10 StandardOutputjournal StandardErrorjournal [Install] WantedBymulti-user.target注意这里Environment里写入了KIMI_API_KEY。虽然之前我们推荐用环境变量但systemd服务本身是一个新的进程上下文不会自动读取~/.bashrc里的变量所以要在服务文件里显式声明。写入服务文件后执行sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclaw查看运行状态和日志sudo systemctl status openclaw journalctl -u openclaw -f -n 100Restartalways保证了进程意外退出后10秒自动拉起。对于AI网关来说这个配置尤其重要因为LLM请求偶尔会触发内存暴涨甚至OOM没有守护机制的进程很容易半夜挂掉。5.3 日志排查清单如果机器人没有按预期工作不要慌按照下面的优先级逐个排查现象优先检查项飞书收不到任何消息事件订阅是否完成长连接是否已建立消息收到但没回复Kimi密钥是否有效base_url是否正确回复速度很慢检查timeout是否过短有没有触发流式传输问题群聊不响应群消息机器人权限是否开启进程频繁重启查看systemd日志里的OOM记录考虑调整max_tokens之前有一次让同事帮忙看问题他折腾了半小时最后发现是飞书开放平台的“机器人名称”没设置应用根本没法以机器人身份发消息。这类问题在后台没有任何报错只有打开应用详情页才能发现。所以说联调时每走一步都要到对应后台确认状态别只盯着OpenClaw日志。5.4 安全细节和配置文件权限配置文件里存了API密钥和应用密钥它的权限一定要收严chmod 600 ~/.openclaw/config/openclaw.yaml chown -R 你的用户名:你的用户组 ~/.openclaw不要把配置文件放到Web目录也不要顺手把它推到代码仓库里。如果使用git管理配置一定要把openclaw.yaml加入.gitignore或者用模板文件代替真实配置。另外建议定期轮换API Key。我现在的做法是每个月在模型服务控制台重新生成一次并把旧密钥作废。虽然麻烦一点但比密钥泄露后被刷爆额度省心得多。飞书应用侧也建议在“安全设置”里配置IP白名单只允许服务器出口IP调用飞书API这样即使App Secret泄露攻击者也无法从其他IP调用接口。5.5 运行一段时间后的稳定性经验跑了一周多以后最明显的感受是这套组合非常省心。OpenClaw的单二进制部署让升级非常简单只需要下载新版本替换二进制再重启服务即可。Kimi 2.5在长对话上的表现很稳即便上下文里有大量代码片段也不容易跑偏或遗忘前面的约束。但有一个小细节提醒一下如果某天发现机器人开始“答非所问”不要急着怀疑模型先看看是不是飞书群里有人发了奇怪格式的消息导致OpenClaw把整段内容都塞进了上下文。可以在配置里限制单次消息的最大字符长度把超长内容自动截断这样能避免大部分上下文污染问题。还有一次是服务器重启后OpenClaw起来了但飞书长连接没恢复。排查发现是网络没完全就绪systemd里虽然配置了Afternetwork-online.target但实际还需要加一行Wantsnetwork-online.target这条依赖确保网络真正就绪后再启动服务。加上之后之后再没出现过启动后连接失败的情况。最后再分享一个经验不要急着加更多渠道。先把飞书单渠道跑稳再考虑把Telegram、Slack等其他平台接进来。因为每加一个渠道就多一组独立的消息格式和权限配置排查问题的面会成倍扩大。OpenClaw的价值本来就是“一处配置、多端通用”但“通用”的前提是每个端都验证清楚而不是指望一个配置神奇的适配所有平台。