本文来源:http://www.hqwc.cn/a/904007.html
若有版权问题,请来信告知:13951431913#139.com 或在右方提交评论。
OpenClaw智能体框架实战:零成本集成飞书打造AI办公助手
1. 项目概述:从“养虾”到智能体开发
最近在开发者圈子里,一个叫“OpenClaw”的项目火得不行,连带“飞书”和“每日免费百万tokens”这几个词也成了高频讨论点。乍一看标题“养虾实战教程”,你可能以为这是个农业养殖或者美食博主的分享,但实际上,这是一个极具吸引力的技术组合: OpenClaw 是一个开源的AI智能体(Agent)框架,而“养虾”是开发者们对它的一种戏称,意指“培养和调教自己的AI智能体”。这个项目的核心魅力在于,它让你能够轻松地将强大的AI能力,通过字节跳动的 飞书 办公套件,无缝集成到日常工作和协作流程中。更关键的是,它巧妙地利用了飞书开放平台提供的免费额度,让你每天都能“薅到”价值不菲的AI计算资源(即tokens),实现近乎零成本的自动化与智能化。
简单来说,这就是一个“用官方资源,搭私人AI助手”的实战方案。对于中小团队、个人开发者,或者任何希望提升工作效率、尝试AI应用落地的朋友来说,这无疑打开了一扇新的大门。你不再需要为调用OpenAI、Claude等商业API的昂贵费用而头疼,也不再需要从零开始搭建复杂的后端服务。OpenClaw提供了智能体的大脑和骨架,飞书提供了现成的交互界面和免费的“算力饲料”,你要做的,就是按照“教程”把它们组装起来,开始“养”一只听话又能干的“电子宠物虾”。
接下来,我将以一个实际操盘手的角度,为你彻底拆解这个组合。从OpenClaw的核心概念、飞书Skill的创建,到如何稳定部署、高效利用免费tokens,以及避坑指南,我会把每一步的原理、操作和背后的考量讲清楚。无论你是想快速尝鲜,还是计划深度集成,这篇内容都能给你提供一条清晰的路径。
2. 核心组件深度解析:OpenClaw与飞书Skill
在动手之前,我们必须先理解手中的“积木”到底是什么,以及它们为何能组合在一起发挥巨大威力。这部分的深入理解,能帮助你在后续部署和调试时事半功倍。
OpenClaw本质上是一个 开源的多智能体(Multi-Agent)协作框架 。它的设计目标很明确:降低构建复杂AI工作流的门槛。与需要你从零编写大量胶水代码的原始API调用不同,OpenClaw提供了一套声明式的配置方法和丰富的内置“技能”(Skill),让你可以通过YAML配置文件,就像搭积木一样,定义智能体的角色、能力、记忆以及它们之间的协作关系。
模块化与可扩展性 :每个“技能”都是一个独立的模块,比如网络搜索、文件读取、代码执行等。你可以像安装插件一样轻松添加或移除技能,也可以基于模板开发自己的专属技能。
多模型支持 :它不绑定任何单一的大模型供应商。你可以轻松配置后端连接 OpenAI GPT、Anthropic Claude、本地部署的 Llama 系列模型(通过 Ollama)等。这带来了极大的灵活性,也是实现“免费tokens”策略的基础。
状态管理与记忆 :智能体不是一次性的问答机器。OpenClaw为智能体提供了对话历史、短期/长期记忆的管理能力,使其能在多轮交互中保持上下文连贯,完成更复杂的任务。
易于集成的网关(Gateway) :OpenClaw Gateway 作为一个统一的HTTP服务接口暴露出来,这使得它可以被任何能够发送HTTP请求的应用调用,比如飞书机器人、微信机器人、自定义的Web界面等。
注意 :网络上搜索“openclaw”时,可能会遇到一些混淆的信息,因为它有时也指代其他项目或工具。在本教程语境下,我们特指在GitHub上活跃的那个开源AI智能体框架。确保你从官方或可靠的社区仓库获取代码和文档。
这是整个方案中最具吸引力的部分。飞书Skill,指的是在飞书开放平台上创建的一个 自定义机器人(Bot)应用 。这个机器人可以被添加到飞书群聊或作为单独的应用使用,用户通过@机器人或点击应用卡片与之交互。
那么,“每日免费百万tokens”从何而来?这并非飞书直接赠送AI算力,而是一个巧妙的资源利用:
飞书开放平台的API调用配额 :飞书为开发者提供的机器人、消息、审批等API接口,在一定的调用频率和数量内是免费的。当我们通过OpenClaw处理用户请求时,智能体本身的计算(大模型推理)发生在别处(如本地或第三方平台),而飞书机器人只负责接收和发送消息。这部分消息收发的API调用,在常规使用量下,完全在飞书的免费额度内。
大模型侧的免费资源 :这才是“tokens”的真正来源。关键在于OpenClaw支持连接 免费或低成本的大模型服务 。例如: Ollama + 本地模型 :在你自己电脑或服务器上部署Ollama,然后运行开源的Llama 3、Qwen等模型。这完全是零token成本,但消耗本地算力。 云厂商的免费额度 :许多AI云平台(如DeepSeek、智谱AI、月之暗面等)为新用户或特定模型提供一定量的免费API调用额度。OpenClaw可以配置使用这些API。 项目本身的福利 :有时开源项目会与模型提供商合作,提供一些测试用的API Key。
所谓的“百万tokens”,通常是指通过组合利用这些免费资源所能获得的等效计算量。例如,一个中等规模的本地模型,处理日常问答和文档总结,一天消耗的token量折算成商业API的价格,可能确实价值数百元。因此,这个说法是一种形象化的表达,核心是 极低的边际成本 。
飞书机器人的核心价值 在于,它提供了一个现成的、用户友好的、且与工作场景深度绑定的交互界面。你不需要自己开发前端,你的团队成员也无需学习新工具,直接在熟悉的飞书里就能使用AI助手。
理解了组件,我们来看它们如何协同工作。整个系统的数据流是这样的:
事件驱动 :你在飞书开放平台配置一个“事件订阅”URL,指向你部署的OpenClaw Gateway。当用户在飞书里@机器人时,飞书服务器会向这个URL发送一个携带事件信息的HTTP POST请求。
请求处理 :OpenClaw Gateway收到请求后,解析出用户的文本消息。
智能体执行 :Gateway将用户消息交给配置好的OpenClaw智能体。智能体根据其角色设定、记忆和技能库,决定如何响应该消息。这可能包括调用网络搜索、查询数据库、执行代码等。
模型推理 :智能体组织好思考过程和需要生成的回复内容,向配置的后端大模型(如本地Ollama)发起请求,得到模型生成的文本。
响应返回 :OpenClaw将最终回复文本通过Gateway返回给飞书事件回调的处理逻辑。
消息发送 :你的服务器端逻辑(通常是一段简单的Webhook处理代码)调用飞书的“发送消息”API,将AI的回复内容发送回原来的群聊或会话。
这个架构清晰地将交互界面(飞书)、智能逻辑(OpenClaw)和计算核心(大模型)解耦,每一层都可以独立替换和升级,提供了极大的灵活性。
理论清晰后,我们进入实战环节。部署是整个流程中步骤最多的一环,我会详细拆解,并标注出每个环节的注意事项。我们将采用 Docker Compose 作为部署方式,这是目前最推荐的方法,能极大简化依赖管理和服务编排。
你需要一台拥有公网IP地址的服务器(云服务器如阿里云ECS、腾讯云CVM均可),或者如果你只想在本地局域网测试,一台性能尚可的PC/Mac也可以。操作系统以Ubuntu 22.04 LTS为例。
第二步:安装Docker与Docker Compose Docker能保证环境一致性,避免“在我机器上好好的”这类问题。
第三步:获取OpenClaw部署文件 OpenClaw社区通常提供了标准的 docker-compose.yml 配置文件。
这里有一个关键点:你需要确认仓库里的 docker-compose.yml 文件是否包含了所有必需的服务,特别是 Ollama 服务(用于运行本地大模型)和 OpenClaw Gateway 服务。
实操心得 :在克隆仓库前,先浏览仓库的README文件。优秀的开源项目会在README中明确说明部署方式、环境变量配置和快速启动命令。如果仓库没有提供现成的compose文件,你可能需要参考文档,自己编写一个,将OpenClaw、PostgreSQL(用于记忆存储)、Redis(用于缓存)和Ollama服务编排在一起。
假设我们有一个标准的 docker-compose.yml ,内容概览如下:
OLLAMA_BASE_URL :这是最重要的环境变量之一。它告诉OpenClaw去哪里寻找大模型服务。在Docker Compose网络内,服务间可以使用服务名( ollama )进行通信,对应容器内部的11434端口。
DEFAULT_MODEL :指定智能体默认使用哪个模型。你需要确保这个模型已经在Ollama中拉取(Pull)了。
卷(Volumes)映射 :将容器内的配置目录( /app/config )和数据目录( /app/data )映射到宿主机,这样即使容器重建,你的配置和记忆数据也不会丢失。
模型拉取需要时间,取决于你的网络和模型大小。8B参数模型大约需要4-5GB磁盘空间。
注意事项 :首次启动时,务必通过日志检查OpenClaw是否成功连接到了Ollama。常见的错误是 OLLAMA_BASE_URL 配置错误或Ollama服务未就绪。你可以在宿主机上运行 curl http://localhost:11434/api/tags 来测试Ollama API是否可用。
服务运行后,OpenClaw本身还需要配置。这通常通过修改宿主机 ./config 目录下的YAML文件来完成。你需要创建一个智能体定义文件,例如 my_assistant.yaml 。
这个配置文件定义了智能体的身份、能力和行为准则。 skills 部分列出了它可用的工具。你需要根据OpenClaw官方文档,了解有哪些内置技能可用以及如何配置它们。
配置完成后,通常需要重启OpenClaw服务或通过其管理API加载新配置。
这是连接飞书与你的OpenClaw服务器的桥梁。步骤稍多,但飞书开放平台的界面比较友好。
填写应用名称(如“AI工作助手”)、描述,并上传应用图标。
创建完成后,进入应用详情页,你需要关注几个关键信息: App ID 和 App Secret :这是应用的身份凭证,用于调用飞书API。务必妥善保管 App Secret 。 Encryption Key 和 Verification Token :在“事件订阅”部分,飞书会提供这两个值,用于验证来自飞书服务器的请求真实性。
为了让机器人能接收消息和发送消息,你需要为它添加相应的权限。
添加以下权限(根据你的需求选择): 获取用户发给机器人的单聊消息 ( im:message.p2p_msg ) 获取群聊中用户@机器人的消息 ( im:message.group_at_msg ) 获取用户在群聊中@机器人的消息 ( im:message.group_at_msg?only_bot=false ) 以应用身份发消息 ( im:message ) 获取用户发给机器人的单聊消息 ( im:message.p2p_msg ) (可选) 获取与上传图片或文件 ( im:image , im:file ),如果想让AI处理图片或文档。
添加权限后,记得在页面底部点击“申请线上发布”或“版本管理与发布”,创建一个新版本并申请发布。通常测试阶段可以在“安全设置”中添加测试人员,无需正式发布。
事件订阅是让飞书主动通知你的服务器的机制。
填写请求地址URL :这里要填入你部署了OpenClaw Gateway的服务器公网地址,并指向一个特定的webhook端点。例如: https://your-server.com:3000/feishu/webhook 。这个端点需要你后续在代码中实现。 重要 :此URL必须支持HTTPS。对于测试,你可以使用内网穿透工具(如ngrok、localtunnel)将本地服务暴露为一个HTTPS地址。
验证请求 :填写URL后点击“保存”,飞书会向该地址发送一个带有 challenge 参数的GET请求。你的webhook服务必须能正确解析这个请求并返回 challenge 值,否则无法通过验证。这通常在webhook处理代码的第一步实现。
订阅事件 :在事件列表里,找到并订阅“接收消息”相关的事件,例如: im.message.receive_v1 (用户发送消息给机器人)
你的OpenClaw Gateway(端口3000)需要有一个额外的路由来处理飞书的回调。你可以用任何你熟悉的语言(Python, Node.js, Go)写一个简单的服务,或者利用OpenClaw社区可能提供的飞书适配器模块。
以下是一个极简的Python Flask示例,展示核心逻辑:
这个示例省略了详细的签名验证和飞书消息发送API的调用实现,你需要参考飞书官方文档补全。核心思路是:接收飞书事件 -> 提取用户消息 -> 转发给OpenClaw -> 获取AI回复 -> 调用飞书API发回消息。
将这个服务也通过Docker Compose管理,与OpenClaw服务一同部署。
基础功能跑通后,我们需要关注如何让它更稳定、更安全、更好用。
OpenClaw的强大之处在于技能库。除了基本的对话,你可以为你的“虾”添加更多能力:
网络搜索技能 :配置Serper API或SearxNG(自建搜索引擎),让AI能回答实时性问题。注意:使用商业搜索API会产生费用。
文件处理技能 :让AI能读取用户上传到飞书的TXT、PDF、Word、Excel文件,并进行总结、问答。这需要配置相应的文件解析库(如 pypdf , python-docx )。
代码解释/执行技能 (谨慎使用):在沙箱环境中执行Python代码片段,用于数学计算或数据分析演示。 务必严格限制权限和资源,避免安全风险。
长期记忆 :配置OpenClaw使用PostgreSQL或向量数据库(如Chroma, Weaviate)来存储和检索长期对话记忆,使AI能记住跨会话的上下文。
配置这些技能通常需要在智能体的YAML配置文件中声明,并确保相应的后端服务可用。
模型选择 :本地部署时,模型大小需与服务器硬件匹配。8B参数模型在16GB内存的服务器上运行较为流畅。如果资源紧张,可以考虑更小的模型(如Phi-3 mini, 3.8B),或使用量化版本(如 llama3.1:8b-instruct-q4_K_M )。
Ollama优化 : 使用 ollama pull 拉取模型时,可以指定标签,如 llama3.1:8b-instruct-q4_K_M ,其中 q4_K_M 是4位量化,能显著减少内存占用和提升推理速度,精度损失在可接受范围内。 在Ollama运行时,可以通过环境变量 OLLAMA_NUM_PARALLEL 等控制并发数。
OpenClaw配置 : 调整 max_tokens , temperature 等生成参数,控制回复长度和创造性。 设置合理的请求超时时间,避免长时间无响应。
网关与Webhook服务 : 为Flask/Django等Web服务配备生产级WSGI服务器,如Gunicorn(配合Nginx反向代理),而不是直接运行开发服务器。 在Nginx配置中启用HTTPS、设置超时、限制请求体大小等。 为webhook服务添加重试和队列机制(如使用Redis Queue),防止因OpenClaw处理慢导致飞书回调超时(飞书回调有5秒超时限制)。常见的做法是webhook接口收到事件后立即返回200,然后将任务放入队列异步处理,再主动调用飞书API发送消息。
飞书侧 : 权限最小化 :只申请应用真正需要的权限。 IP白名单 :在飞书开放平台配置服务器IP白名单,防止回调地址被恶意调用。 妥善保管密钥 : App Secret 、 Encryption Key 等绝对不要提交到代码仓库。使用环境变量或密钥管理服务。
服务器侧 : HTTPS :公网服务必须使用HTTPS。可以使用Let‘s Encrypt免费证书。 验证签名 : 务必 在webhook服务中实现飞书事件签名验证。这是确认请求真正来自飞书的唯一方式,防止伪造请求攻击。 防火墙 :只开放必要的端口(如443, 80)。Ollama的11434端口、OpenClaw的管理端口不应直接暴露到公网。 Docker安全 :以非root用户运行容器,定期更新镜像。 模型与技能隔离 :对于文件读取、代码执行等高风险技能,应在严格的沙箱环境中运行,并限制其访问的文件系统范围和网络权限。
内容安全 : 在OpenClaw的 system_prompt 中明确加入内容安全约束,要求AI不生成有害、违法、侵权的内容。 考虑在webhook层或OpenClaw之前添加一个内容过滤中间件,对用户输入和AI输出进行二次检查。
在实际部署和运行中,你几乎一定会遇到下面这些问题。这里记录了我的排查思路和解决方法。
问题1:Docker Compose启动后,OpenClaw日志报错“连接Ollama失败”或“模型未找到”。
排查 : 检查 docker-compose.yml 中 OLLAMA_BASE_URL 的值。在Compose网络内,应使用服务名 http://ollama:11434 ;如果从宿主机测试,用 http://localhost:11434 。 运行 docker compose logs ollama 查看Ollama容器是否启动成功,有无错误日志。 进入Ollama容器检查模型是否已拉取: docker exec -it ollama ollama list 。 在OpenClaw容器内测试网络连通性: docker exec -it openclaw curl http://ollama:11434/api/tags 。
解决 : 确保Ollama容器健康运行。 如果模型未拉取,执行 docker exec -it ollama ollama pull
问题2:飞书事件订阅URL验证失败。
排查 : 确认你的webhook服务已经运行且端口可访问。 确认URL是HTTPS(飞书要求)。本地测试必须用ngrok等工具。 检查你的webhook服务是否正确响应了GET请求并返回了正确的 challenge 值。查看你的服务日志。 检查服务器防火墙/安全组是否放行了webhook服务端口。
解决 : 在webhook服务中,确保 /feishu/webhook 的GET请求处理逻辑正确。 使用 curl 或 Postman 手动模拟飞书的验证请求进行测试。
问题3:用户在飞书@机器人,机器人没反应。
排查 : 检查事件订阅 :飞书开发者后台-事件订阅,查看是否有事件送达记录。如果有“失败”记录,点击查看详情。 检查webhook服务日志 :看是否收到了POST请求。如果没收到,问题在飞书侧或网络。 检查签名验证 :如果收到了请求但返回了403,可能是签名验证失败。仔细核对 Verification Token 和签名计算逻辑。 检查OpenClaw Gateway :webhook服务转发请求给OpenClaw后,查看OpenClaw的日志是否有错误。 检查飞书API调用 :webhook服务调用飞书发消息API是否成功。飞书API返回的错误码很有帮助。
解决 :这是一个典型的端到端排查流程。按照“飞书->你的服务器->OpenClaw->你的服务器->飞书”这个链条,逐一检查日志和状态。
问题4:AI回复速度很慢,或者飞书提示“消息发送失败,超时”。
原因 :大模型推理本身较慢,尤其是首次加载或处理长文本时。飞书服务器等待回调响应有超时限制(约5秒)。
解决 : 异步处理 :这是 必须 的优化。Webhook接口收到事件后,立即返回成功响应。然后使用消息队列(如Redis + RQ,或Celery)将处理任务异步化。异步任务完成后,再调用飞书的“发送消息”API(该API没有短超时限制)。 模型量化 :使用量化模型(如q4, q5)提升推理速度。 硬件升级 :确保服务器有足够的CPU/GPU资源和内存。
问题5:OpenClaw技能(如搜索、读文件)不工作。
排查 : 检查智能体YAML配置中,该技能是否 enabled: true 。 检查技能所需的配置项(如API Key、文件路径)是否正确设置,特别是通过环境变量引用的值是否已正确注入容器。 查看OpenClaw日志,通常会有技能加载失败或执行错误的具体信息。 如果技能涉及外部API,在容器内测试网络连通性。
解决 :根据日志错误信息,修正配置或解决网络问题。
问题6:本地模型消耗内存太大,服务器卡顿。
解决 : 换用更小或量化模型 :这是最直接有效的方法。 调整Ollama参数 :通过 OLLAMA_NUM_PARALLEL 限制并发请求数。 硬件层面 :增加虚拟内存(swap空间),但会影响速度。最根本的还是升级服务器配置。
本文来源:http://www.hqwc.cn/a/904007.html
若有版权问题,请来信告知:13951431913#139.com 或在右方提交评论。
1. Project overview: from 'raising shrimp' to agent development
Recently a project called OpenClaw has taken the developer world by storm, dragging terms like 'Feishu' and 'a million free tokens a day' into frequent discussion. At first glance a title like 'shrimp-raising tutorial' might look like farming or food-blog content, but in reality it is a very appealing technical combination. OpenClaw is an open-source AI agent framework, and 'raising shrimp' is developers' playful nickname for it, meaning cultivating and training your own AI agent. The core appeal is that it lets you easily integrate powerful AI capabilities into daily work and collaboration through ByteDance's Feishu office suite. More importantly, it cleverly exploits Feishu's free API quota so you can harvest valuable AI compute resources (tokens) every day, achieving near-zero-cost automation and intelligence.
In simple terms, this is a hands-on plan for 'using official resources to build a private AI assistant.' For small and medium teams, individual developers, or anyone who wants to improve efficiency and try AI in real applications, it opens a new door. You no longer need to worry about the expensive cost of calling commercial APIs like OpenAI or Claude, nor build complex backend services from scratch. OpenClaw provides the brain and skeleton of the agent; Feishu provides a ready-made interface and free 'compute feed.' Your job is to assemble them following the tutorial and start raising an obedient, capable 'electronic pet shrimp.'
2. Core components explained: OpenClaw and Feishu Skills
Before getting hands-on, we must understand what these 'building blocks' are and why they combine into something so powerful. OpenClaw is essentially an open-source multi-agent collaboration framework with a clear goal: lowering the barrier to building complex AI workflows. Unlike raw API calls that require writing large amounts of glue code, OpenClaw offers declarative configuration and a rich set of built-in 'Skills,' letting you define agents' roles, abilities, memory, and collaboration relationships through YAML files, like stacking blocks.
Its modularity and extensibility mean every 'Skill' is an independent module, such as web search, file reading, or code execution. You can add or remove skills like plugins, or develop your own from templates. Its multi-model support is not tied to any single model provider; you can configure backends connecting to OpenAI GPT, Anthropic Claude, or locally deployed Llama models via Ollama. This flexibility is the basis of the 'free tokens' strategy. Its state management and memory give agents conversation history and short/long-term memory so they stay coherent across multiple turns and complete more complex tasks. And an easy-to-integrate Gateway exposes a unified HTTP service interface that any application able to send HTTP requests can call, including Feishu bots, WeChat bots, and custom web UIs.
A note of caution: searching the web for 'openclaw' can surface confusing information, because the name sometimes refers to other projects or tools. In this tutorial we specifically mean the open-source AI agent framework active on GitHub, so make sure you get the code and documentation from official or reliable community repositories.
The most attractive part of the whole scheme is the Feishu Skill: a custom bot application created on the Feishu open platform. This bot can be added to group chats or used as a standalone app, and users interact with it by @-mentioning it or clicking app cards.
Where do the 'million free tokens a day' come from? It is not that Feishu directly gifts AI compute; it is a clever use of resources. First, Feishu's open platform gives developers free API call quotas for bots, messages, approvals, and other endpoints within certain frequency and volume limits. When OpenClaw processes a request, the agent's actual computation (model inference) happens elsewhere, locally or on a third-party platform, while the Feishu bot only receives and sends messages; under normal usage these message calls stay within Feishu's free quota.
Second, and this is the true source of the 'tokens,' OpenClaw supports connecting to free or low-cost model services. You can deploy Ollama with open models such as Llama 3 or Qwen on your own machine or server for zero token cost, at the expense of local compute. Many AI platforms such as DeepSeek, Zhipu AI, and Moonshot offer a certain amount of free API quota for new users or specific models, which OpenClaw can be configured to use. And sometimes open-source projects partner with model providers to offer test API keys.
The so-called 'million tokens' usually refers to the equivalent compute obtainable by combining these free resources. A mid-sized local model handling daily Q&A and document summarization might consume a token amount worth hundreds of yuan if priced as a commercial API. So the phrase is a vivid expression whose core meaning is extremely low marginal cost. Feishu's real value is providing a ready-made, user-friendly interface deeply tied to the work scenario, so you need not build a front end and your team need not learn a new tool.
The whole system's data flow is event-driven. You configure an 'event subscription' URL on the Feishu open platform pointing to your deployed OpenClaw Gateway; when a user @-mentions the bot, Feishu sends an HTTP POST carrying event info to that URL. The Gateway parses the user's text message and hands it to the configured agent, which decides how to respond based on its role, memory, and skill library, possibly calling web search, querying a database, or executing code. The agent then requests the configured backend model (such as local Ollama), receives generated text, and OpenClaw returns the final reply through the Gateway to the callback handler, where your server-side webhook code calls Feishu's 'send message' API to deliver the reply back to the original chat. This architecture cleanly decouples the interface (Feishu), the intelligence (OpenClaw), and the compute core (the model), so each layer can be replaced and upgraded independently.
3. Deployment: Docker Compose and the practical path
Deployment has the most steps, so I will break it down in detail and flag the cautions at each stage. We use Docker Compose, currently the most recommended method because it greatly simplifies dependency management and service orchestration. You need a server with a public IP (a cloud instance such as Alibaba Cloud ECS or Tencent Cloud CVM works), or for local LAN testing a reasonably capable PC or Mac. We will use Ubuntu 22.04 LTS as the example OS.
Install Docker and Docker Compose to keep environments consistent and avoid 'it works on my machine' problems. Then obtain the OpenClaw deployment files; the community usually provides a standard docker-compose.yml. A key point: confirm that the compose file includes all required services, especially Ollama (for running local models) and the OpenClaw Gateway. Before cloning, browse the repository README; a good open-source project clearly documents deployment, environment variables, and quick-start commands. If no ready compose file is provided, you may need to write one yourself, orchestrating OpenClaw, PostgreSQL (for memory storage), Redis (for caching), and Ollama together.
OLLAMA_BASE_URL is one of the most important environment variables; it tells OpenClaw where to find the model service. Inside the Compose network, services communicate using the service name 'ollama' on internal port 11434. DEFAULT_MODEL specifies which model the agent uses by default, and you must ensure it has been pulled into Ollama. Volume mapping binds the container's config directory (/app/config) and data directory (/app/data) to the host so configuration and memory survive container rebuilds. Pulling a model takes time depending on your network and model size; an 8B model needs roughly 4-5GB of disk. On first launch, always check the logs to confirm OpenClaw connected to Ollama; common errors are a wrong OLLAMA_BASE_URL or an unready Ollama service. You can run 'curl http://localhost:11434/api/tags' on the host to test the Ollama API.
Once the services are running, OpenClaw itself still needs configuration, usually by editing YAML files in the host's ./config directory. Create an agent definition file such as my_assistant.yaml defining the agent's identity, capabilities, and behavior guidelines; the skills section lists available tools. Consult the official OpenClaw docs for which built-in skills exist and how to configure them. Afterward, restart the OpenClaw service or load the new configuration through its management API.
4. Connecting Feishu: creating the app and event subscription
This is the bridge between Feishu and your OpenClaw server. The steps are a bit more numerous, but the Feishu open platform interface is fairly friendly. Create an app, fill in a name (such as 'AI Work Assistant') and description, and upload an icon. On the app detail page, note several key pieces of information: App ID and App Secret are the app's identity credentials used to call Feishu APIs; store the App Secret carefully. Encryption Key and Verification Token are provided in the event subscription section to verify that requests genuinely come from Feishu.
To let the bot receive and send messages, add the appropriate permissions: receive private messages sent to the bot (im:message.p2p_msg), receive @-mentions in groups (im:message.group_at_msg), receive @-mentions in groups with only_bot=false, send messages as the app (im:message), and optionally read and upload images or files (im:image, im:file) if you want AI to handle images or documents. After adding permissions, click 'apply for online release' or 'version management and release' at the bottom to create a version and apply for publication. During testing you can usually just add testers under security settings without a formal release.
Event subscription is the mechanism by which Feishu actively notifies your server. Fill in the request URL with the public address of your OpenClaw Gateway server, pointing to a specific webhook endpoint such as https://your-server.com:3000/feishu/webhook, which you will implement in code later. Important: this URL must support HTTPS; for testing you can use a tunneling tool such as ngrok or localtunnel to expose a local service as an HTTPS address. After saving, Feishu sends a GET request with a challenge parameter; your webhook must parse it and return the challenge value correctly or verification fails. Then subscribe to 'receive message' events such as im.message.receive_v1.
Your OpenClaw Gateway (port 3000) needs an extra route to handle Feishu callbacks. You can write a small service in any language you know (Python, Node.js, Go), or use a Feishu adapter module the OpenClaw community may provide. A minimal Python Flask example shows the core logic: receive the Feishu event, extract the user message, forward it to OpenClaw, get the AI reply, and call the Feishu API to send the message back. The example omits detailed signature verification and the message-sending API implementation; consult the official Feishu docs to complete them. Manage this service with Docker Compose as well, deploying it alongside OpenClaw.
5. Making it stable, secure, and useful
OpenClaw's strength lies in its skill library. Beyond basic chat you can add more abilities to your 'shrimp': a web search skill configured with the Serper API or self-hosted SearxNG so the AI can answer real-time questions (note that commercial search APIs cost money); a file processing skill letting AI read and summarize TXT, PDF, Word, and Excel files uploaded to Feishu (requiring libraries such as pypdf and python-docx); a code interpretation/execution skill that runs Python snippets in a sandbox for math or data analysis demonstrations (strictly limit permissions and resources to avoid security risks); and long-term memory using PostgreSQL or a vector database such as Chroma or Weaviate so the AI remembers context across sessions. Configuring these skills usually means declaring them in the agent's YAML file and ensuring the corresponding backends are available.
For model choice, match model size to hardware: an 8B model runs smoothly on a server with 16GB of memory; if resources are tight, consider a smaller model such as Phi-3 mini (3.8B) or a quantized build such as llama3.1:8b-instruct-q4_K_M. When pulling with Ollama you can specify tags such as q4_K_M, a 4-bit quantization that significantly reduces memory usage and speeds inference with acceptable accuracy loss. OLLAMA_NUM_PARALLEL and similar environment variables control concurrency. In OpenClaw, tune generation parameters such as max_tokens and temperature to control reply length and creativity, and set reasonable request timeouts to avoid long hangs.
For the gateway and webhook service, back your Flask/Django service with a production-grade WSGI server such as Gunicorn behind Nginx rather than running the development server directly; enable HTTPS, set timeouts, and limit request body size in Nginx. Add retries and a queue mechanism (such as Redis Queue) to the webhook so a slow OpenClaw does not cause Feishu callback timeouts (Feishu callbacks have a 5-second limit). A common practice is to return 200 immediately on receiving an event, push the task into a queue for asynchronous processing, and then proactively call Feishu's API to send the message.
On the Feishu side, apply least privilege, configure a server IP whitelist to prevent malicious calls to the callback address, and never commit App Secret or Encryption Key to a code repository; use environment variables or a secret manager. On the server side, always use HTTPS for public services (Let's Encrypt offers free certificates), implement Feishu event signature verification in the webhook (the only way to confirm a request truly comes from Feishu), open only necessary ports such as 443 and 80 (do not expose Ollama's 11434 or OpenClaw's management port directly), run containers as non-root and update images regularly, and isolate high-risk skills such as file reading and code execution in strict sandboxes with limited filesystem and network access. For content safety, add explicit constraints in OpenClaw's system_prompt forbidding harmful, illegal, or infringing content, and consider a content filter before the webhook or OpenClaw to double-check both input and output.
6. Troubleshooting common problems
In real deployment you will almost certainly hit these issues. If Docker Compose starts but OpenClaw logs 'failed to connect to Ollama' or 'model not found,' check the value of OLLAMA_BASE_URL in docker-compose.yml: inside the Compose network use the service name http://ollama:11434, while from the host use http://localhost:11434. Run 'docker compose logs ollama' to see whether the container started cleanly, 'docker exec -it ollama ollama list' to check whether the model was pulled, and 'docker exec -it openclaw curl http://ollama:11434/api/tags' to test connectivity. Ensure the Ollama container is healthy; if the model is missing, pull it with 'docker exec -it ollama ollama pull
If Feishu event subscription URL verification fails, confirm the webhook service is running and its port is reachable, that the URL is HTTPS (required by Feishu, use ngrok for local testing), that your service correctly responds to the GET request with the right challenge value (check logs), and that the server firewall or security group allows the webhook port. Test manually with curl or Postman by simulating Feishu's verification request.
If you @-mention the bot and it does not respond, follow the end-to-end chain: Feishu → your server → OpenClaw → your server → Feishu. Check the Feishu developer console's event subscription for delivery records, your webhook logs for the POST request, signature verification (a 403 response usually means failure, so recheck the Verification Token and signature logic), the OpenClaw Gateway logs after forwarding, and whether the webhook's call to Feishu's send-message API succeeded by reading the returned error code.
If AI replies are slow or Feishu reports 'message send failed, timeout,' remember that model inference is inherently slow, especially on first load or long text, while Feishu waits only about 5 seconds for a callback. Asynchronous processing is mandatory: return success immediately on receiving an event, use a message queue such as Redis + RQ or Celery to process in the background, then call Feishu's send-message API (which has no short timeout) when done. Also use quantized models (q4, q5) for speed and ensure adequate CPU/GPU and memory.
If OpenClaw skills such as search or file reading do not work, check that the skill is enabled: true in the agent's YAML, that its configuration items (API keys, file paths) are correct and that environment-variable values are properly injected into the container, read the OpenClaw logs for specific load or execution errors, and test network connectivity inside the container if an external API is involved. If local models consume too much memory and the server lags, switch to a smaller or quantized model, limit concurrency with OLLAMA_NUM_PARALLEL, add swap space (at the cost of speed), and ultimately upgrade the server configuration.
