1. 项目概述为什么OpenClaw与飞书是绝配最近在折腾AI工具链的朋友估计都绕不开OpenClaw这个名字。简单来说它是一个开源的AI智能体Agent框架你可以把它理解为一个“AI大脑”的调度中心。它能连接你本地的、云上的各种大语言模型比如通过Ollama部署的Llama、Qwen或者API形式的GPT-4然后通过安装不同的“技能”Skill让这个大脑学会干各种活比如分析数据、生成报告、管理日程甚至是帮你从网上抓取信息。而我今天要聊的就是怎么把这个聪明的“大脑”塞进我们日常办公最常用的工具之一——飞书里。你可能会问为什么是飞书直接用它自带的Web界面不香吗这里面的门道可就多了。首先飞书是我们很多人每天待得最久的应用所有的工作沟通、文档协作、任务管理都在里面。如果AI助手能直接嵌入飞书那就意味着它从“一个需要特意去打开的玩具”变成了“一个随时在聊天侧边栏待命的同事”。其次飞书的机器人Bot和开放平台能力非常成熟消息推送、指令交互、卡片展示这些都能为AI智能体提供一个绝佳的交互界面。最后通过飞书你可以很方便地将AI处理的结果比如一份数据分析摘要直接同步到飞书文档、多维表格或者群聊中形成工作流的闭环。所以这篇教程就是为你准备的无论你是对Docker命令还一知半解的技术爱好者还是只想快速让AI为自己所用的业务人员。我会手把手带你完成从零部署OpenClaw到成功接入飞书机器人的全过程过程中遇到的坑和解决技巧一个不落都会告诉你。2. 核心思路与架构解析在动手之前我们得先搞清楚整个系统是怎么跑起来的。这有助于你在后面配置时明白每一个参数的意义出了问题也知道该往哪个方向排查。2.1 OpenClaw的核心组件与工作流OpenClaw的架构很清晰主要包含以下几个部分Gateway网关这是对外的统一入口。所有外部请求比如来自飞书机器人的消息都先到这里。它负责鉴权、路由把请求转发给后端的Core服务。Core核心这是真正的“大脑”所在。它管理着会话Session、技能Skill和模型Model。当你向机器人提问时Core会解析你的意图调用相应的Skill并选择合适的模型来生成回答。Skill技能这是OpenClaw可扩展性的体现。每个Skill都是一个独立的功能模块比如有专门读写文件的filesystem技能有执行Python代码的python技能还有我们后面会重点用到的、用于连接飞书的feishu技能。你可以把Skill理解为给AI安装的一个个“APP”。Model模型AI的算力来源。OpenClaw支持多种后端最常见的是通过Ollama管理的本地模型如Llama 3, Qwen2.5也可以配置成使用OpenAI、Anthropic等云端模型的API。整个工作流是这样的飞书用户机器人发送消息 - 飞书服务器将消息事件推送到我们部署的OpenClaw Gateway - Gateway转发给Core - Core根据消息内容结合已启用的Skill例如feishu技能用于理解飞书消息格式python技能用于处理数据和配置的模型生成执行计划并得到结果 - 结果经由Gateway返回给飞书服务器 - 飞书机器人将回复呈现给用户。2.2 飞书开放平台的关键概念要在飞书上创建一个能交互的机器人我们需要在飞书开放平台上完成几个关键配置企业自建应用我们创建的不是一个简单的群组机器人而是一个“企业自建应用”。这样功能更强大权限也更可控。应用创建后你会得到App ID和App Secret这是应用的身份凭证。权限配置Scopes你的机器人需要申请权限才能干活。最核心的包括im:message接收和发送单聊、群聊消息。im:message.group_at_msg接收群聊中机器人的消息。im:message.p2p_msg接收单聊消息。如果你希望机器人能读写飞书云文档或表格还需要申请对应的drive权限。事件订阅Event Subscription这是实现实时交互的核心。你需要告诉飞书“当有消息事件发生时请把事件详情推送到我这个URL即你的OpenClaw Gateway地址”。飞书会对这个URL进行“挑战验证”你必须正确响应才能订阅成功。消息卡片飞书回复不止是纯文本还可以是丰富的交互式卡片。OpenClaw的feishu技能支持将部分回复以卡片形式呈现体验更好。理清了这两端的架构我们的任务就明确了搭建好OpenClaw服务并在飞书开放平台正确配置应用将两端通过“事件订阅URL”安全地连接起来。3. 环境准备与OpenClaw部署我们选择用Docker来部署OpenClaw这是最干净、最不容易出问题的方式跨平台Windows/macOS/Linux也通用。3.1 基础环境搭建首先确保你的机器上已经安装了Docker和Docker Compose。你可以通过在终端运行docker --version和docker-compose --version来检查。如果没有安装请前往Docker官网下载适合你操作系统的Docker Desktop进行安装它通常包含了Docker Compose。接下来我们需要一个目录来存放所有配置。打开终端执行以下命令mkdir -p ~/openclaw-feishu cd ~/openclaw-feishu这个目录将作为我们项目的工作根目录。3.2 编写Docker Compose配置文件Docker Compose允许我们用一份YAML文件定义和运行多个容器。在项目根目录下创建一个名为docker-compose.yml的文件。这里有一个经过实践验证的配置模板它同时启动了OpenClaw Core、Gateway以及一个Ollama服务用于运行本地大模型。你可以直接用文本编辑器复制粘贴以下内容version: 3.8 services: ollama: image: ollama/ollama:latest container_name: openclaw-ollama restart: unless-stopped ports: - 11434:11434 volumes: - ollama_data:/root/.ollama networks: - openclaw-net openclaw-core: image: ghcr.io/openclawai/openclaw-core:latest container_name: openclaw-core restart: unless-stopped environment: - OLLAMA_BASE_URLhttp://ollama:11434 - DEFAULT_MODELllama3.2:1b # 这里指定默认模型可按需修改 depends_on: - ollama networks: - openclaw-net openclaw-gateway: image: ghcr.io/openclawai/openclaw-gateway:latest container_name: openclaw-gateway restart: unless-stopped ports: - 3000:3000 # Gateway对外服务的端口 environment: - CORE_BASE_URLhttp://openclaw-core:8000 - ENABLED_SKILLSfeishu,filesystem,python # 启用feishu等核心技能 depends_on: - openclaw-core networks: - openclaw-net volumes: ollama_data: networks: openclaw-net: driver: bridge关键参数解读OLLAMA_BASE_URLhttp://ollama:11434这是Core容器内部访问Ollama服务的地址。注意这里用的是Docker Compose的服务名ollama而不是localhost。这是一个常见坑点在容器网络内localhost指向容器自身。DEFAULT_MODELllama3.2:1b指定OpenClaw默认使用的模型。我这里用了Meta最新开源的Llama 3.2 1B版本体积小响应快适合入门和测试。你可以在Ollama运行后通过ollama pull qwen2.5:0.5b等命令拉取其他模型并在此修改。ENABLED_SKILLSfeishu,filesystem,python这是Gateway的环境变量声明需要加载的技能。feishu是必须的filesystem和python是非常实用的基础技能建议保留。ports: - 3000:3000将Gateway容器的3000端口映射到宿主机的3000端口。这意味着我们稍后配置飞书事件订阅时URL将是http://你的公网IP或域名:3000。注意如果你在本地电脑没有公网IP上测试后续需要用到内网穿透工具如ngrok、localtunnel来获得一个公网可访问的临时地址用于飞书的事件订阅回调。这是集成测试的关键一步。3.3 启动服务与初始化模型保存好docker-compose.yml文件后在终端里执行docker-compose up -d-d参数代表后台运行。执行成功后用docker-compose ps命令查看应该能看到三个服务ollama,openclaw-core,openclaw-gateway的状态都是Up。接下来我们需要为Ollama拉取之前配置的模型。执行docker exec openclaw-ollama ollama pull llama3.2:1b这个命令会进入openclaw-ollama容器内部执行ollama pull命令。下载时间取决于你的网络速度1B的小模型应该很快。下载完成后我们可以测试一下OpenClaw Gateway是否工作正常。在浏览器中访问http://localhost:3000如果能看到一个简单的欢迎页面或者API文档信息可能是一个JSON响应说明Gateway已经成功启动并运行在3000端口。4. 飞书应用创建与配置详解现在AI大脑已经在我们本地跑起来了接下来要给它创造一个在飞书里的“化身”。4.1 创建企业自建应用登录 飞书开放平台 。点击“创建企业自建应用”。应用名称可以随意比如“我的AI助手”应用描述写清楚即可。创建成功后进入应用详情页。在“凭证与基础信息”部分你会找到至关重要的App ID和App Secret。请立即将这两串字符串妥善保存下来App Secret只显示一次。4.2 配置应用权限在应用详情页找到“权限管理”标签页。我们需要为应用添加以下权限以应用身份调用APIim:message获取与发送消息以应用身份调用APIim:message.group_at_msg接收群消息以应用身份调用APIim:message.p2p_msg接收单聊消息如果你希望AI能处理飞书文档可以额外添加drive:drive等权限。添加后记得点击页面底部的“申请线上发布”或“版本管理与发布”取决于平台界面创建一个新版本并申请发布。通常自用测试只需由管理员在后台审核通过即可。4.3 配置事件订阅最关键的步骤这是连接飞书和OpenClaw的桥梁也是最容易出错的一步。在应用详情页找到“事件订阅”标签页。开启事件订阅点击“启用事件订阅”开关。设置请求地址在“请求地址URL”栏填入你的OpenClaw Gateway的公网可访问地址并加上飞书事件订阅的专用路径。格式为https://你的域名或穿透地址:3000/feishu/event。本地测试方案如果你在本地开发没有公网IP必须使用内网穿透工具。以ngrok为例在终端运行ngrok http 3000它会生成一个如https://abc123.ngrok-free.app的临时域名。那么你的请求地址就应该是https://abc123.ngrok-free.app/feishu/event。请确保穿透工具指向你本机的3000端口。添加事件点击“添加事件”在消息事件类别下勾选“接收消息v2.0”下的“群聊中机器人消息”和“单聊消息”。保存并验证填写和勾选完毕后点击“保存”。飞书会立即向你所填的URL发送一个带有challenge参数的GET请求进行“挑战验证”。你的OpenClaw Gateway必须能正确接收这个GET请求并原样返回challenge的值。这里有一个巨大的坑很多教程会忽略OpenClawfeishu技能的默认配置。OpenClaw Gateway的/feishu/event端点默认期望接收的是POST请求用于处理真正的消息事件但飞书的挑战验证是GET请求。如果你的服务没有正确处理GET请求验证就会失败一直显示“验证不通过”。解决方案确保你的OpenClaw Gateway版本支持自动处理飞书的挑战验证。目前主流的OpenClaw版本使用feishu技能已经内置了对GET /feishu/event挑战验证请求的处理逻辑。验证时飞书平台会显示“挑战成功”。如果失败请检查你的Gateway日志docker logs openclaw-gateway查看是否有关于该路径的请求记录和错误信息。4.4 获取其他必要凭证除了App ID和App Secret我们还需要一个东西Encrypt Key。 在“事件订阅”页面找到“Encrypt Key”一栏。如果为空点击“重置”即可生成一个。这个密钥用于飞书对事件消息进行加密可选但建议配置。同样复制并保存好这个密钥。至此飞书侧的配置暂时完成。我们得到了三样东西App ID、App Secret、Encrypt Key。接下来我们要把这些信息告诉OpenClaw。5. OpenClaw技能配置与连接飞书OpenClaw通过环境变量来配置feishu技能所需的参数。我们需要修改之前的docker-compose.yml文件为openclaw-gateway服务添加飞书的配置。5.1 配置环境变量打开docker-compose.yml找到openclaw-gateway服务部分在environment字段下添加飞书的配置信息。修改后的片段如下openclaw-gateway: image: ghcr.io/openclawai/openclaw-gateway:latest container_name: openclaw-gateway restart: unless-stopped ports: - 3000:3000 environment: - CORE_BASE_URLhttp://openclaw-core:8000 - ENABLED_SKILLSfeishu,filesystem,python # 飞书技能配置开始 - FEISHU_APP_IDcli_xxxxxxxxxxxxxx # 替换为你的App ID - FEISHU_APP_SECRETxxxxxxxxxxxxxxxxxxxxxxxx # 替换为你的App Secret - FEISHU_ENCRYPT_KEYxxxxxxxxxxxxxxxx # 替换为你的Encrypt Key如果未启用加密则留空或删除此行 - FEISHU_VERIFICATION_TOKEN # 飞书旧版验证令牌如未使用可留空 # 飞书技能配置结束 depends_on: - openclaw-core networks: - openclaw-net重要提示请务必将cli_xxxxxxxxxxxxxx、xxxxxxxxxxxxxxxxxxxxxxxx和xxxxxxxxxxxxxxxx替换成你从飞书开放平台实际获取的值。如果飞书应用没有启用“Encrypt Key”即事件订阅页面显示为空那么必须删除或注释掉FEISHU_ENCRYPT_KEY这一行环境变量。如果配置了一个空的或不正确的加密密钥Gateway在解密飞书事件时会失败导致机器人完全无法接收消息。FEISHU_VERIFICATION_TOKEN是飞书旧版API的验证令牌目前新创建的应用一般用不到留空即可。5.2 重启服务使配置生效配置修改保存后需要重启Gateway容器来加载新的环境变量。在项目根目录下执行docker-compose down openclaw-gateway docker-compose up -d openclaw-gateway或者更直接地重启整个栈docker-compose restart重启后强烈建议查看一下Gateway的启动日志确认没有配置错误docker logs openclaw-gateway --tail 50在日志中你应该能看到类似Skill feishu loaded successfully的信息以及它初始化时尝试加载你配置的App ID等。5.3 安装与启用飞书机器人最后一步是将我们配置好的飞书应用安装到具体的飞书群或工作台中。发布应用确保在飞书开放平台你的应用版本已经“审核通过”或“已发布”。获取安装二维码在应用详情页的“版本管理与发布”中找到已发布的版本通常会有“邀请试用”或“安装”的选项可以生成一个安装二维码。扫码安装用你的飞书APP扫描二维码选择要安装到的群组或直接添加到工作台。授权按照提示完成授权。管理员可能需要审批。安装成功后你就可以在对应的飞书群聊中你机器人的名字或者在工作台打开它开始对话了6. 实战测试与高阶玩法一切配置就绪让我们来点真正的测试。6.1 基础功能测试在你的飞书群聊里你的机器人然后发送一些简单的指令例如“你好介绍一下你自己。”“今天的日期是什么”“用Python计算一下1到100的和。”如果一切正常机器人会在几秒到十几秒内回复你。第一次调用模型可能会稍慢因为需要加载模型到内存。如果机器人没有回复请按以下顺序排查检查容器状态docker-compose ps确认三个服务都在运行。检查Gateway日志docker logs openclaw-gateway -f-f表示持续跟踪日志。然后在飞书里发一条消息观察日志是否有收到事件的记录。这是最直接的诊断方式。检查事件订阅确认飞书开放平台“事件订阅”状态是“已验证”。如果没有重新检查请求地址URL和穿透工具。检查飞书权限确认应用已成功安装到当前群聊且拥有发送消息的权限。6.2 排查经典错误operator(): got exception在测试过程中你可能会在Gateway日志或飞书机器人回复中看到类似这样的错误openclaw llamap svr operator(): got exception: { error: { code: 400, message: ..., type: ...“ } }这个错误通常不是飞书连接的问题而是OpenClaw Core在调用模型或执行技能时产生的内部错误。llamap svr暗示了问题出在模型交互层。可能的原因和解决方案模型未加载或名称错误检查docker-compose.yml中DEFAULT_MODEL设置的名字是否与Ollama中实际拉取的模型名完全一致。可以通过docker exec openclaw-ollama ollama list查看已拉取的模型列表。模型响应超时或崩溃特别是使用较大模型或硬件资源不足时。尝试在Ollama容器中运行ollama run llama3.2:1b进行直接对话测试看模型本身是否工作正常。也可以考虑在Core的环境变量中增加超时设置如果支持。技能执行错误比如请求了一个未安装或不支持的技能。确保ENABLED_SKILLS里包含了你要用的技能。遇到此类错误核心是查看OpenClaw Core的日志docker logs openclaw-core里面通常会有更详细的错误堆栈信息。6.3 技能拓展与集成OpenClaw的强大在于其技能生态。除了基础的feishu,filesystem,python你还可以探索更多连接知识库安装websearch技能让AI能联网搜索最新信息。处理飞书多维表格结合python技能和飞书OpenAPI你可以让AI读取分析多维表格中的数据甚至自动更新表格内容。这需要你额外在飞书应用申请drive:drive权限并在Skill中编写或调用相应的处理逻辑。自动化工作流你可以创建自定义Skill将OpenClaw与你的内部系统如CRM、ERPAPI相连实现诸如“机器人帮我查一下客户XXX的最新订单状态”这样的高级功能。配置额外技能通常需要修改Gateway的ENABLED_SKILLS环境变量并可能需要为技能提供额外的配置如API密钥。具体请参考OpenClaw官方文档或对应技能的README。7. 维护、优化与安全建议将AI助手投入日常使用后以下几点能让你用得更顺手、更安心。7.1 服务管理与更新停止服务在项目目录下运行docker-compose down。这会停止并移除所有容器但保留数据卷如Ollama的模型数据。更新OpenClaw拉取最新镜像并重启服务。docker-compose pull docker-compose up -d更新Ollama模型如果想换用其他模型先拉取新模型docker exec openclaw-ollama ollama pull 模型名然后修改docker-compose.yml中的DEFAULT_MODEL环境变量最后重启Core和Gateway服务。查看日志如前所述docker logs [容器名]是排查问题的第一利器。使用-f参数可以实时跟踪。7.2 性能与成本优化模型选择本地部署时模型大小直接决定响应速度和硬件消耗。对于轻量级问答、总结任务1B-7B参数量的模型如Llama 3.2 1B/3B, Qwen2.5 0.5B/1.5B是不错的选择。如果需要更强推理能力再考虑13B及以上模型。硬件资源确保你的服务器或本地电脑有足够的内存。运行一个7B模型通常需要8GB以上空闲内存。可以通过Docker Compose文件限制容器的CPU和内存使用防止资源耗尽。使用云模型API如果你追求最顶尖的效果如GPT-4或者不想消耗本地算力可以将OpenClaw的模型后端配置为OpenAI、Anthropic等云服务API。这需要在Core的环境变量中配置OPENAI_API_KEY等并将DEFAULT_MODEL改为gpt-4等。注意这会持续产生API调用费用。7.3 安全与隐私须知网络暴露你通过内网穿透工具生成的地址是公开的。务必确保你的OpenClaw服务没有敏感数据或者使用更安全的穿透方案如带认证的ngrok付费版、或自建反向代理配合HTTPS。飞书权限最小化在飞书开放平台只授予应用完成功能所必需的最小权限。例如如果不需要读写文档就不要申请drive相关权限。环境变量管理App Secret和Encrypt Key是最高机密切勿提交到公开的代码仓库。docker-compose.yml文件中的明文密码是一种简易做法。生产环境建议使用Docker Secrets、或通过env_file引用外部配置文件来管理。模型风险注意开源大模型可能产生“幻觉”编造信息或输出不受控内容。在将其接入企业办公环境前建议进行充分的测试和评估并设置必要的对话过滤或审查机制。整个过程从部署到调通最花时间的往往不是步骤本身而是排查网络连通性、飞书事件订阅验证以及模型加载这些环节的问题。只要按照上面的步骤耐心查看日志一步步排除最终看到飞书机器人回应你的那一刻所有的折腾都是值得的。这个组合为你打开了一扇门让你能在一个最熟悉的办公环境里拥有一个随时听候差遣的AI助手。