三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

基于Kimi与OpenClaw的飞书AI助手：本地部署与智能工作流实战

发布时间：2026/8/15 21:45:59 三亩地 编程学习日记
基于Kimi与OpenClaw的飞书AI助手：本地部署与智能工作流实战

1. 项目概述：从零到一，构建你的智能工作流中枢

最近在折腾AI应用落地的朋友，估计都绕不开一个词：OpenClaw。这玩意儿本质上是一个开源的AI智能体（Agent）框架，你可以把它理解为一个“万能接线员”。它的核心能力是，把市面上那些强大的大语言模型（比如你听过的Kimi、DeepSeek、GPT等）和你日常用的工具（比如飞书、钉钉、GitHub、各类API）给连接起来。你只需要用自然语言给它下个指令，比如“帮我把今天飞书文档里的待办事项总结一下，发到群里”，它就能自动调用模型理解你的意思，再去操作相应的工具完成任务。

我这次实测的目标很明确：在本地服务器上，免费部署一个基于Kimi最新模型（以kimi-k2.5为例）的OpenClaw，并成功接入飞书，实现通过飞书机器人进行远程对话和任务处理。整个过程，我会把所有踩过的坑、关键的配置截图、以及那些官方文档里语焉不详的细节，都掰开揉碎了讲清楚。无论你是刚接触Docker的新手，还是对AI应用跃跃欲试的开发者，跟着这篇“保姆级”实录走一遍，都能把这个系统跑起来。

2. 核心组件与工具选型解析

在动手之前，我们得先搞清楚要摆弄哪些“乐高积木”。盲目安装只会导致各种依赖报错，最后无从下手。

2.1 OpenClaw：智能体的“操作系统”

OpenClaw不是一个具体的AI模型，而是一个运行和调度智能体的平台。你可以把它类比为手机上的iOS或Android系统。这个系统提供了基础的环境，让不同的“APP”（即智能体）可以安装、运行，并且让这些APP能够调用手机的硬件能力（如摄像头、网络）或其他APP的服务。

在OpenClaw的语境下，这些“基础能力”就是它对各种大模型API（如Kimi、DeepSeek）的兼容支持，以及通过“工具”（Tools）定义去连接外部服务（如飞书、数据库）的协议。我们部署OpenClaw，就是在搭建这个底层操作系统。

2.2 模型选择：为什么是Kimi-k2.5？

当前开源或提供免费API的模型中，Kimi（由月之暗面公司开发）的长文本处理能力一直是其显著优势。网络热词中提到的kimi-k2.5、kimi k3，通常指代其不同的模型版本或代号。对于我们的部署来说，关键点在于：

  1. 免费额度：Kimi为开发者提供了较为充裕的免费API调用额度，非常适合个人或小团队进行学习和原型验证。
  2. API稳定性：相对于一些完全开源、需要庞大算力本地部署的模型，使用Kimi的API服务省去了准备昂贵显卡、折腾复杂模型量化步骤的麻烦，让新手能更专注于应用逻辑本身。
  3. 长上下文：处理飞书文档、总结会议纪要这类任务，经常需要模型能“记住”很长的文本，Kimi在这方面表现不错。

因此，本次部署我们选择Kimi作为核心大模型引擎。你需要去Kimi的开放平台（通常搜索“Kimi AI开放平台”即可找到）注册账号，并创建一个应用来获取关键的API Key。这个Key相当于打开Kimi模型大门的密码。

2.3 飞书集成：远程交互的“客户端”

为什么选择飞书作为远程交互界面？因为它不仅仅是一个聊天工具。飞书机器人提供了完善的开放API，可以很方便地接收消息、发送消息，甚至与飞书文档、多维表格、日历等深度交互。这意味着，未来你可以扩展出非常多实用的自动化场景，比如：

  • 机器人自动同步GitHub Issue到飞书任务。
  • 根据群聊内容自动生成会议纪要并存入云文档。
  • 查询公司知识库来回答问题。

部署后，你的飞书群里就会出现一个机器人，你@它或者私聊它，它就会将问题转发给本地部署的OpenClaw，OpenClaw调用Kimi模型思考后，再将答案通过机器人回复给你。这样就实现了“远程”访问你本地服务的AI能力。

2.4 技术栈与环境准备

为了让这一切运转起来，我们需要一个稳定的基础环境：

  • 服务器/本地主机：一台拥有公网IP或可通过内网穿透访问的Linux服务器（Ubuntu 20.04/22.04或CentOS 7/8是常见选择），或者就是你性能不错的个人电脑。系统需保持网络通畅。
  • Docker与Docker Compose：这是本次部署的强烈推荐方式。Docker能将OpenClaw及其所有依赖（Python环境、各种库）打包在一个独立的“容器”里运行，避免与系统原有环境冲突，也使得安装和卸载变得极其干净。使用Docker部署，能避开90%因环境差异导致的问题。
  • Git：用于拉取OpenClaw的最新代码。
  • 一个域名与SSL证书（可选但推荐）：如果你希望通过HTTPS安全地访问OpenClaw的管理界面，或者为飞书机器人配置安全的回调地址，这是必需的。国内服务器可以备案后使用域名，个人测试也可用内网穿透工具（如frp、ngrok）提供的临时域名。

3. 逐步实操：OpenClaw部署与飞书接入全记录

下面进入最核心的实操环节。我会以一台纯净的Ubuntu 22.04服务器为例，假设你已经以root用户或拥有sudo权限的用户登录。

3.1 基础环境搭建与Docker安装

首先，更新系统并安装必要的工具。

# 更新软件包列表 sudo apt-get update sudo apt-get upgrade -y # 安装基础工具 sudo apt-get install -y curl git vim

接下来安装Docker和Docker Compose。Docker官方提供了便捷的安装脚本。

# 下载并运行Docker安装脚本 curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh # 将当前用户加入docker组，避免每次都要sudo sudo usermod -aG docker $USER # **注意：** 执行此命令后，你需要**退出当前SSH会话，并重新登录**，用户组变更才会生效。 # 安装Docker Compose插件（Docker新版本推荐使用Compose插件而非独立二进制文件） sudo apt-get install -y docker-compose-plugin # 验证安装 docker --version docker compose version

重新登录后，运行docker ps命令，如果不报错，说明Docker安装成功。

3.2 获取与配置OpenClaw

我们通过Git拉取OpenClaw的官方代码仓库。通常项目会在GitHub或Gitee上。

# 克隆项目代码（这里以假设的仓库地址为例，请以实际官方仓库为准） git clone https://github.com/openclaw/OpenClaw.git cd OpenClaw

使用Docker Compose部署前，最关键的一步是配置环境变量文件。项目根目录下通常会有一个.env.example或config.example.yaml之类的示例文件。

# 复制示例配置文件 cp .env.example .env # 使用vim或nano编辑这个.env文件 vim .env

你需要重点修改以下配置项（以下值为示例，请替换为你自己的）：

# 模型配置 - 指向Kimi LLM_PROVIDER=kimi KIMI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 你在Kimi开放平台获取的API Key KIMI_MODEL=kimi-k2.5 # 或根据平台最新模型名称填写，如 “moonshot-v1-8k” # 服务器访问配置（用于管理界面和API） OPENCLAW_HOST=0.0.0.0 # 监听所有网络接口 OPENCLAW_PORT=3000 # 服务运行的端口，确保防火墙开放此端口 # 数据库配置（通常使用内置SQLite即可，生产环境可换MySQL） DATABASE_URL=sqlite:///./data/openclaw.db # 飞书机器人配置（下一节详细获取） FEISHU_APP_ID=cli_xxxxxx FEISHU_APP_SECRET=xxxxxxxxxxxx FEISHU_ENCRYPT_KEY= # 如果飞书应用要求加密，则填写 FEISHU_VERIFICATION_TOKEN=xxxxxx

注意：.env文件包含所有敏感信息，切勿将其提交到Git等版本控制系统。通常项目.gitignore文件已将其忽略。

3.3 飞书应用创建与关键信息获取

这是连接飞书的核心步骤，一步错步步错。请严格按照以下流程操作：

  1. 登录飞书开放平台：访问 飞书开放平台 ，使用你的飞书账号登录。
  2. 创建企业自建应用：
    • 点击“创建应用”，选择“企业自建应用”。
    • 填写应用名称（如“我的AI助手”）、描述，并上传应用图标。
  3. 获取凭证：在应用详情页的“凭证与基础信息”部分，你会找到App ID和App Secret。这就是上面.env文件里需要的FEISHU_APP_ID和FEISHU_APP_SECRET。点击“显示”才能看到Secret，并立即复制保存。
  4. 配置权限：在“权限管理”页面，为你的应用添加以下权限：
    • im:message（发送与接收单聊、群组消息）
    • im:message.group_at_msg（接收群聊中@机器人的消息）
    • im:message.p2p_msg（接收单聊消息）
    • 根据你后续想扩展的功能，可能还需要contact:user.id:readonly（获取用户信息）等。添加后记得点击“申请线上发布”或“批量申请”（对于测试，在“版本管理与发布”中创建测试版本即可）。
  5. 配置事件订阅（最关键且最容易出错的一步）：
    • 在“事件订阅”页面，首先需要填写请求网址 URL。这就是你部署的OpenClaw服务提供给飞书回调的地址。
    • 假设你的服务器公网IP是123.123.123.123，OpenClaw服务端口是3000，那么URL格式为：http://123.123.123.123:3000/feishu/events（如果配置了HTTPS和域名，则用https://your-domain.com/feishu/events）。
    • 重要提示：飞书要求这个URL必须能在公网访问，且返回正确的验证信息。在本地开发或服务器未配置好时，可以先使用内网穿透工具（如ngrok、localtunnel）生成一个临时公网地址来填写和测试。这也是网络热词中uu远程、todesk等工具可能被尝试用于解决连接问题的场景，但更推荐专业的反向代理或内网穿透方案。
    • 填写URL后，飞书会立即发送一个带有challenge参数的GET请求来验证。你的OpenClaw服务必须能正确接收并原样返回这个challenge值。如果验证失败，检查：1) 服务是否运行；2) 端口是否开放；3) 防火墙/安全组设置；4) OpenClaw飞书路由是否正确配置。
    • 验证通过后，在下方“订阅事件”中，添加你需要的事件，例如“接收消息”、“机器人进群”等。
  6. 获取事件订阅的Token：在事件订阅页面，你可以看到Verification Token。将其填入.env文件的FEISHU_VERIFICATION_TOKEN。
  7. 发布应用：在“版本管理与发布”中，创建测试版本，并邀请至少一个其他飞书用户（不能是自己）作为测试者。只有测试者才能在飞书里看到并使用这个机器人。

3.4 启动OpenClaw服务并验证

配置完成后，使用Docker Compose一键启动所有服务。

# 在OpenClaw项目根目录下执行 docker compose up -d

-d参数表示在后台运行。使用以下命令查看日志和状态：

# 查看实时日志 docker compose logs -f # 查看容器状态 docker compose ps

如果一切顺利，你应该能看到容器状态为running，并且日志中没有持续的报错。现在，你可以通过浏览器访问http://你的服务器IP:3000来打开OpenClaw的管理界面（如果配置了的话）。

验证飞书连接：

  1. 在飞书中找到你成为测试者的应用，或者搜索你创建的应用名称。
  2. 将机器人拉入一个群聊，或直接与它发起单聊。
  3. 发送一条消息，如“你好”。
  4. 观察服务器上OpenClaw的日志 (docker compose logs -f openclaw)。你应该能看到飞书事件推送的日志，以及调用Kimi API进行处理的日志。
  5. 如果机器人能正常回复，恭喜你，核心链路已经打通！

4. 深度配置：打造实用的AI智能体

基础服务跑通只是第一步。接下来，我们要让这个AI从“能聊天”变成“能干活”。

4.1 模型参数调优与提示词工程

在OpenClaw的管理界面或配置文件中，你可以调整调用Kimi模型时的参数，以平衡速度、成本和效果。

  • 温度（Temperature）：控制模型输出的随机性。值越低（如0.2），输出越确定、保守；值越高（如0.8），输出越有创造性、不可预测。对于总结文档、提取信息等任务，建议设低（0.1-0.3）；对于头脑风暴、创意写作，可以设高（0.7-0.9）。
  • 最大令牌数（Max Tokens）：限制模型单次回复的最大长度。Kimi支持长上下文，但为避免无意义的长篇大论，可以根据需要设置，例如2048或4096。
  • 系统提示词（System Prompt）：这是塑造AI“人格”和“能力边界”的关键。你可以在OpenClaw中为连接到飞书的智能体设置系统提示词。例如：

    “你是一个高效的办公助手，专注于处理飞书中的文档总结、日程提醒和简单问答。你的回答应简洁、专业、直接。如果用户的问题超出你的能力范围或需要人工介入，请直接说明。不要编造你不知道的信息。”

一个精心设计的系统提示词能极大提升AI回复的可用性和安全性。

4.2 扩展工具能力：让AI“手”更长

OpenClaw的强大之处在于可以给AI装配“工具”。除了基础的对话，你可以通过编写或配置“工具”来让AI操作更多东西。例如：

  • 网络搜索工具：让AI能获取实时信息（需配置SerpAPI等搜索引擎API Key）。
  • 飞书文档读写工具：让AI可以读取飞书云文档内容进行分析，或将总结写入新文档。
  • 数据库查询工具：连接你的业务数据库，让AI用自然语言进行数据查询。
  • 代码执行工具（需极度谨慎）：在沙箱环境中执行Python代码进行数学计算或数据处理。

这些工具通常以插件或自定义技能的形式集成。你需要查阅OpenClaw的文档，了解如何开发和注册自定义工具。通常流程是：在指定目录编写一个Python类，定义工具的名称、描述、输入参数和执行函数，然后在配置中启用它。

4.3 实现一个简单工作流：自动会议纪要生成

我们来设想一个具体场景，并勾勒其实现思路：场景：每次团队飞书会议结束后，将会议记录文档链接发给机器人，让它自动生成一份结构化的会议纪要（包含议题、结论、待办事项）。

实现思路：

  1. 创建专用技能/工具：在OpenClaw中创建一个名为summarize_meeting的工具。该工具接收一个参数：doc_url（飞书文档链接）。
  2. 工具内部逻辑：
    • 调用飞书API，根据doc_url获取文档的纯文本内容。
    • 设计一个针对会议记录的提示词，调用Kimi模型对文本进行总结、提炼。
    • 将模型输出的结构化结果（如Markdown格式），通过飞书机器人消息或创建一个新的飞书文档返回给用户。
  3. 配置触发方式：可以在飞书机器人中设置关键词触发（如用户发送“总结会议”+文档链接），或者更智能地，通过分析消息内容自动识别会议文档链接并触发。

这个例子展示了如何将模型能力、工具API和业务场景串联起来，形成一个自动化工作流。

5. 避坑指南与常见问题排查

在实际部署和运行中，你几乎一定会遇到下面这些问题。我把我的踩坑记录和解决方案整理如下。

5.1 部署阶段常见问题

Q1: Docker启动失败，提示端口被占用。A1:检查端口3000是否已被其他程序（如另一个OpenClaw实例、其他Web服务）占用。

sudo lsof -i:3000 # 查看占用端口的进程 # 或使用 netstat sudo netstat -tulpn | grep :3000

如果被占用，要么停止那个进程，要么修改.env文件中的OPENCLAW_PORT为其他端口，如3001，并记得同步更新飞书事件订阅的URL。

Q2: 拉取Docker镜像速度慢或失败。A2:为Docker配置国内镜像加速器。编辑/etc/docker/daemon.json文件（不存在则创建）：

{ "registry-mirrors": [ "https://docker.mirrors.ustc.edu.cn", "https://hub-mirror.c.163.com" ] }

保存后，重启Docker服务：sudo systemctl restart docker。

Q3: 执行docker compose up -d报错，提示“找不到命令”或“权限被拒绝”。A3:

  • “找不到命令”：确保安装的是docker-compose-plugin，命令是docker compose（有空格）。旧版独立的docker-compose命令已逐渐被取代。
  • “权限被拒绝”：确保当前用户已在docker用户组中（执行过sudo usermod -aG docker $USER并已重新登录）。或者在所有命令前加sudo。

5.2 飞书集成阶段常见问题

Q4: 飞书事件订阅URL验证始终失败。A4:这是最高频的问题，按以下步骤排查：

  1. 检查服务可达性：在服务器本地curl http://localhost:3000/feishu/events，看是否有响应。如果没有，说明OpenClaw服务没起来或路由不对，查Docker日志。
  2. 检查公网可达性：在另一台有公网的机器上（比如你的本地电脑），用curl http://你的服务器IP:3000/feishu/events测试。如果超时或不通，问题在网络层：
    • 服务器安全组/防火墙：确保云服务商（如阿里云、腾讯云）的安全组规则和服务器本身的防火墙（ufw或iptables）已放行3000端口。
    • 家庭网络：如果你用家庭宽带，通常没有公网IP，必须使用内网穿透（如frp、ngrok）。这是个人用户最常见的解决方案。用穿透工具提供的公网地址作为飞书的请求网址。
  3. 检查OpenClaw飞书路由：确认OpenClaw项目中处理飞书事件的路由路径是否正确，是否与你在飞书平台填写的URL后缀（/feishu/events）完全一致。查看项目代码或文档。
  4. 查看日志：docker compose logs -f查看详细错误信息。飞书的验证请求是GET方法，确保你的服务能正确处理GET请求并返回challenge值。

Q5: 机器人能收到消息，但不回复，服务器日志显示模型调用失败。A5:

  1. 检查Kimi API Key：在.env文件中确认KIMI_API_KEY是否正确无误，是否还有剩余额度。可以手动用curl测试一下API：
    curl -X POST "https://api.moonshot.cn/v1/chat/completions" \ -H "Authorization: Bearer sk-your-api-key-here" \ -H "Content-Type: application/json" \ -d '{ "model": "moonshot-v1-8k", "messages": [{"role": "user", "content": "Hello"}], "temperature": 0.3 }'
  2. 检查模型名称：确认KIMI_MODEL配置的是Kimi平台当前支持的有效模型名称，如moonshot-v1-8k。过时或错误的模型名会导致调用失败。
  3. 网络问题：确保你的服务器可以正常访问Kimi的API域名 (api.moonshot.cn)。有时服务器所在的网络环境可能有特殊限制。

Q6: 飞书机器人发送消息时报错{“errmsg”:“request access: fail invalid redirect uri in h5 case”}或其他errmsg。A6:这类错误通常与飞书应用的配置有关。

  • invalid redirect uri：检查飞书应用“安全设置”中的“重定向URL”是否配置正确。这个URL用于OAuth网页授权，如果你没用到网页登录功能，可能不需要配置，但若配置了就必须是有效的、备案的域名。
  • 其他errmsg：仔细阅读飞书开放平台的错误码文档。最常见的还是权限问题——去“权限管理”页面，确认你需要的所有权限都已添加且已“申请发布”。在测试环境下，确保测试版本已创建，且用户已接受测试邀请。

5.3 运行维护与优化

Q7: 如何更新OpenClaw到新版本？A7:

# 进入项目目录 cd /path/to/OpenClaw # 拉取最新代码 git pull origin main # 重新构建并启动容器（如果docker-compose.yml有变动） docker compose down docker compose pull # 拉取更新的镜像 docker compose up -d --build # 重新构建并启动

注意：更新前最好备份你的.env配置文件和数据库文件（如果使用文件数据库如SQLite）。

Q8: 如何查看资源使用情况或调试？A8:

  • 查看容器资源：docker stats查看CPU、内存占用。
  • 进入容器内部：docker exec -it openclaw_container_name /bin/bash可以进入容器执行命令。
  • 查看详细日志：docker compose logs --tail=100 openclaw查看最近100行日志。-f参数可以实时跟踪。

Q9: 感觉响应慢怎么办？A9:响应延迟可能来自多个环节：

  1. 网络延迟：飞书服务器->你的服务器->Kimi API服务器。你的服务器地理位置会影响这两段网络。
  2. 模型响应速度：大模型生成文本本身需要时间，尤其是生成长文本时。可以尝试调低max_tokens。
  3. 服务器性能：如果服务器性能过低，处理请求本身可能成为瓶颈。对于轻量级使用，1核2G的服务器通常足够；如果并发高或处理复杂逻辑，需要更好配置。
  4. 优化提示词：清晰、简洁的提示词能引导模型更快给出准确答案，减少“思考”时间。

部署完成后，真正的乐趣才开始。你可以尝试为你的OpenClaw智能体添加更多工具，比如连接日历API让它帮你安排会议，连接GitHub API让它总结代码变更，甚至连接智能家居API实现语音控制。这个由Kimi提供“大脑”、OpenClaw提供“协调能力”、飞书提供“交互界面”的组合，为你打开了一扇低成本、高效率构建个性化AI助手的大门。

编程学习 学习日记 实战经验
← 返回列表