1. 项目背景与核心价值最近在折腾AI工作流的朋友估计没少被各种“智能体”平台折腾。云端服务要么贵要么有数据隐私顾虑要么API调用不稳定。于是把AI能力“搬”到自己电脑上再让它无缝融入日常办公工具就成了一个很实际的需求。OpenClaw一个开源的AI智能体框架正好能解决这个问题。它就像一个乐高底座你可以自由地给它装上各种“大脑”大语言模型和“手脚”工具与技能让它帮你处理特定任务。而飞书作为很多团队的协作中心承载了海量的文档、对话和任务。如果能将本地部署的OpenClaw接入飞书就意味着你拥有了一个24小时在线、完全受控、能理解上下文、并能操作飞书内数据的“数字员工”。无论是自动汇总群聊信息、根据多维表格数据生成报告还是帮你快速检索知识库这个组合的想象空间非常大。网上虽然有一些零散的教程但要么步骤跳跃要么在关键环节比如飞书应用配置、OpenClaw技能配置一笔带过让新手踩坑无数。搜索热词里那一串“openclaw llamap svr operator(): got exception”、“app secret复制不上去”、“invalid redirect uri”就是血泪证明。这篇内容我就以一个从零开始的实践者角度带你走通从本地启动OpenClaw到在飞书上成功调用的完整链路把每一个可能卡住的细节都掰开揉碎讲清楚。2. 环境准备不只是安装Docker那么简单在开始敲命令之前理清环境依赖是避免后续一系列“玄学”错误的基础。OpenClaw官方推荐使用Docker部署这确实能屏蔽大量环境差异但前提是你的Docker环境本身是健康的。2.1 系统与Docker环境确认首先确保你有一个Linux环境Ubuntu 20.04/22.04或CentOS 7/8或者Windows/macOS。这里以最通用的Ubuntu 22.04为例。如果你用Windows强烈建议使用WSL 2Windows Subsystem for Linux来获得接近原生的Linux体验能避开很多路径和权限的坑。打开终端第一步不是安装Docker而是先更新系统并安装一些基础工具sudo apt update sudo apt upgrade -y sudo apt install -y curl wget git vim ca-certificates software-properties-common接下来安装Docker。很多教程让你直接用apt install docker.io但这个版本可能较旧。我建议使用Docker官方仓库安装最新稳定版# 卸载旧版本如果有 sudo apt remove docker docker-engine docker.io containerd runc # 安装依赖允许apt通过HTTPS使用仓库 sudo apt install -y apt-transport-https ca-certificates curl software-properties-common # 添加Docker官方GPG密钥 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg # 设置稳定版仓库 echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装Docker引擎 sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin安装完成后最关键的一步来了将当前用户加入docker组。否则你每次运行docker命令都需要sudo这会导致后续步骤中容器内生成的文件权限混乱是很多问题的根源。sudo usermod -aG docker $USER执行完这条命令后你必须完全退出当前终端会话并重新登录或者重启系统这个组权限变更才会生效。你可以用newgrp docker临时生效但重新登录是最稳妥的。验证安装和权限# 检查Docker服务状态 sudo systemctl status docker # 不加sudo运行hello-world测试用户组权限 docker run hello-world如果能看到“Hello from Docker!”的输出说明Docker安装和用户组配置都成功了。2.2 获取OpenClaw部署文件OpenClaw的部署主要通过一个docker-compose.yml文件来编排多个服务。我们需要先把这个文件拿到本地。# 创建一个专门的工作目录 mkdir -p ~/openclaw-deploy cd ~/openclaw-deploy # 从官方仓库获取docker-compose配置文件 # 注意这里以某个稳定版本或主分支的compose文件为例请以官方最新文档为准 wget https://raw.githubusercontent.com/openclaw-ai/openclaw/main/deploy/docker-compose.yml # 同时获取可能需要的环境变量示例文件 wget https://raw.githubusercontent.com/openclaw-ai/openclaw/main/deploy/.env.example -O .env拿到文件后先别急着启动。用cat docker-compose.yml快速浏览一下你会看到它通常包含了几个核心服务gatewayAPI网关、llm大模型服务、skill技能服务、database数据库等。这有助于你理解整个架构。3. 配置与启动OpenClaw避开配置陷阱有了部署文件下一步就是配置。这是新手最容易栽跟头的地方因为很多配置项不理解其作用要么乱改要么漏改。3.1 理解并修改环境变量上一步我们下载了.env.example文件现在需要将其复制为正式的.env文件并进行修改cp .env.example .env vim .env # 或者用你喜欢的文本编辑器如nano这个.env文件是OpenClaw服务的核心配置。你需要重点关注以下几个部分数据库配置通常包括DATABASE_URL。如果你使用Docker Compose内置的PostgreSQL这个URL一般不需要改动它会自动连接。但如果你使用外部数据库就需要修改为你的实际连接串。大模型配置这是灵魂所在。搜索热词里很多人卡在模型配置。OpenClaw本身不提供模型你需要指定一个本地或远程的LLM服务端点。本地模型推荐如果你已经在本地用Ollama、LM Studio等工具运行了模型比如qwen2.5:7b那么配置可能类似于LLM_API_BASEhttp://host.docker.internal:11434/v1 # Ollama默认地址 LLM_MODELqwen2.5:7b LLM_API_KEYsk-no-key-required # 本地模型通常不需要key注意host.docker.internal是Docker容器访问宿主机服务的特殊域名。在Linux上有时需要改用宿主机的实际IP如172.17.0.1你可以用ip addr show docker0命令查看。云端API如果你使用OpenAI、DeepSeek、智谱等云端API则需要填写对应的API_BASE和API_KEY并确保模型名称正确。服务端口检查GATEWAY_PORT如8000、WEBUI_PORT如果有如3000是否与你本地其他端口冲突。一个常见的错误是直接使用.env.example而不修改LLM_MODEL导致服务启动后因为找不到模型而报错。务必根据你的实际情况配置。3.2 启动服务与验证配置好.env后就可以启动服务了。在docker-compose.yml所在目录执行docker-compose up -d-d参数表示在后台运行。首次运行会拉取镜像需要一些时间。启动后用以下命令检查服务状态docker-compose ps你应该看到所有服务gateway, llm等的状态都是Up。如果某个服务反复重启Restarting就需要查看它的日志定位问题# 查看所有服务的日志 docker-compose logs # 查看特定服务如gateway的日志 docker-compose logs gateway热词中出现的[openclaw] could not start the cli.这类错误通常可以在日志中找到更详细的根源比如模型连接失败、数据库连接失败、配置文件语法错误等。服务正常启动后验证网关是否工作curl http://localhost:8000/health如果返回{status:ok}之类的JSON信息说明OpenClaw的核心服务已经成功在本地运行起来了。它的API网关正在8000端口监听请求。4. 飞书应用创建与配置每一步都是坑这是整个流程中最繁琐、也最容易出错的一环。飞书开放平台的配置项多且逻辑严谨一步错步步错。我们按步骤来目标是创建一个能接收消息、并能够回调我们本地OpenClaw服务的“企业自建应用”。4.1 创建应用与获取凭证进入开发者后台访问 飞书开放平台 用你的飞书账号登录。如果你代表一个组织请使用有管理员权限的账号。创建应用点击“创建企业自建应用”输入应用名称如“我的AI助手”并选择应用描述和图标。获取关键凭证应用创建后在“凭证与基础信息”页面找到App ID和App Secret这是应用的身份标识。点击“重置”或“查看”可以获取App Secret。这里就是热词中“app secret复制不上去”的坑点飞书出于安全考虑App Secret通常只显示一次你必须立即复制保存。如果错过了只能重置生成新的。建议拿到后立刻粘贴到本地文档或密码管理器中。Encrypt Key和Verification Token在“事件订阅”部分你需要先填写一个临时的请求地址比如https://example.com才能点击“重置”来生成这两个密钥。先随便填生成并保存好密钥后我们后面再回来修改正确的地址。4.2 配置权限与事件订阅权限和事件决定了你的应用能做什么、能接收什么。添加权限在“权限管理”页面根据你希望AI助手具备的能力添加对应的权限。最基础的要让机器人能接收消息和发消息需要im:message获取用户发给机器人的单聊消息im:message.group_at_msg获取群聊中机器人的消息im:message.p2p_msg获取单聊消息如果你希望机器人能主动发消息还需要im:message:send_as_bot。如果涉及读取或操作多维表格、云文档则需要添加对应的bitable:table:read、drive:file:read等权限。注意添加权限后必须点击页面底部的“申请线上发布”或“版本管理与发布”创建一个新版本并申请发布。部分高级权限需要审核但基础消息权限通常可自助开通。配置事件订阅核心难点这是连接飞书和本地服务的关键桥梁。飞书服务器需要知道把事件比如用户发消息推送给谁。请求地址这就是你本地服务的公网可访问地址。由于我们本地部署没有公网IP就需要使用内网穿透工具。常用的有ngrok、localhost.run或frp。这里以ngrok为例注意ngrok免费版域名会变化仅用于测试。# 在本地安装ngrok并启动将本地的8000端口暴露到公网 # 假设你获得了临时域名 https://abc123.ngrok.io ngrok http 8000在飞书开放平台“事件订阅”页面“请求地址”栏填写https://abc123.ngrok.io/feishu/event/callback。这个路径/feishu/event/callback是OpenClaw网关默认用于接收飞书事件的路由你可以在OpenClaw的配置中自定义但两端必须一致。加密密钥和验证令牌填入之前保存的Encrypt Key和Verification Token。订阅事件点击“添加事件”选择你需要的事件例如im.message.receive_v1接收消息。点击“保存”保存时飞书会立即向你填写的请求地址发送一个带有challenge参数的验证请求。如果你的本地OpenClaw服务没有正确配置并处理这个验证保存就会失败提示“请求不合法”或“超时”。这正是热词中“invalid redirect uri”或验证失败的根源。4.3 发布应用与添加到聊天发布应用在“版本管理与发布”中确保你已创建了一个包含所需权限的版本并点击“申请发布”。对于仅自用的应用通常选择“企业可用”即可。添加到聊天发布后在“应用发布”页面你可以看到“添加到工作台”或“添加到群聊”的选项。更常用的方式是在飞书客户端中通过搜索你的应用名称将其添加为好友或拉入群聊。只有添加后应用才能在该会话中收发消息。5. 配置OpenClaw飞书适配器打通最后一公里现在我们有了运行的OpenClaw服务也有了配置好的飞书应用。接下来就是让OpenClaw知道如何与这个特定的飞书应用通信。5.1 理解适配器配置OpenClaw通过“适配器”来连接不同的平台如飞书、钉钉、Slack。对于飞书我们需要在OpenClaw的配置中启用并配置飞书适配器。配置通常通过环境变量或配置文件完成。我们需要在之前修改的.env文件中添加飞书相关的配置项。这些配置项的名称可能因OpenClaw版本略有不同但核心逻辑一致# 飞书适配器配置 FEISHU_ENABLEDtrue FEISHU_APP_ID你的App ID FEISHU_APP_SECRET你的App Secret FEISHU_ENCRYPT_KEY你的Encrypt Key FEISHU_VERIFICATION_TOKEN你的Verification Token FEISHU_BOT_NAME我的助手 # 可选机器人的显示名称 # 事件回调路径必须与飞书后台配置的“请求地址”后缀一致 FEISHU_EVENT_CALLBACK_PATH/feishu/event/callback关键点FEISHU_APP_ID和FEISHU_APP_SECRET用于OpenClaw主动调用飞书API如发送消息时的身份认证。FEISHU_ENCRYPT_KEY和FEISHU_VERIFICATION_TOKEN用于验证飞书服务器发来的事件请求是否合法确保安全。FEISHU_EVENT_CALLBACK_PATH定义了OpenClaw网关内处理飞书事件的路由。飞书后台配置的完整请求地址是你的公网域名这个路径。5.2 重启服务并验证连接修改完.env文件后需要重启OpenClaw服务以使配置生效docker-compose down docker-compose up -d再次检查日志确保没有报错docker-compose logs gateway | grep -i feishu如果看到类似“Feishu adapter initialized”或“Event callback route registered”的日志说明飞书适配器加载成功。现在回到飞书开放平台的“事件订阅”页面再次点击“保存”。如果配置一切正确飞书发送的验证请求会被你的本地OpenClaw服务成功接收并响应页面会显示“保存成功”。如果还是失败请依次排查内网穿透是否在线确认ngrok服务还在运行且域名没有变化。路径是否一致对比飞书后台的“请求地址”和.env中的FEISHU_EVENT_CALLBACK_PATH确保拼接后的路径完全一致。OpenClaw日志查看docker-compose logs gateway的详细输出看是否收到了验证请求以及如何处理。端口与防火墙确保本地8000端口没有被其他程序占用且宿主机防火墙允许该端口的入站连接。6. 技能配置与测试让你的AI助手真正干活服务连通只是第一步让AI助手能理解指令并执行任务需要配置“技能”。6.1 理解OpenClaw技能体系OpenClaw的技能可以理解为一个个可调用的功能模块。有的技能是内置的如简单的对话有的需要你额外配置和启用。技能通过自然语言描述来触发。首先我们需要进入OpenClaw的管理界面如果有WebUI的话或通过其API来管理技能。假设OpenClaw的WebUI运行在3000端口访问http://localhost:3000。如果没有UI则需要通过其API端点来操作这通常更复杂。在技能管理页面你可能会看到一些默认技能比如general_chat通用对话。这个技能会直接将用户输入发送给你配置的LLM并将回复返回。你可以先启用这个技能进行基础测试。6.2 进行端到端测试在飞书中触发在飞书客户端打开你已添加了机器人的单聊或群聊机器人或直接发送消息例如“你好”。观察链路飞书端消息发送。飞书服务器将消息事件推送到你配置的请求地址https://你的域名/feishu/event/callback。内网穿透将请求转发到你本机的8000端口。OpenClaw网关接收请求验证签名解析出消息内容。OpenClaw技能路由根据消息内容路由到对应的技能如general_chat。LLM服务技能调用LLM服务获取生成的回复文本。OpenClaw网关通过飞书API使用App ID和Secret将回复消息发送回对应的飞书会话。飞书客户端你收到机器人的回复。排查无响应问题如果收不到回复按照上述链路逐层检查查看飞书开放平台“事件订阅”中的“事件日志”看消息事件是否推送成功是否有错误码。查看ngrok的Web界面或控制台看是否有请求进入。查看OpenClaw网关日志docker-compose logs gateway --tail100这是最关键的排错信息源。查看LLM服务日志docker-compose logs llm确认模型调用是否成功。6.3 配置自定义技能进阶基础对话测试通过后你可以配置更强大的技能。例如配置一个“文档总结”技能让它能读取飞书云文档链接并总结。这通常需要编写或配置技能逻辑这可能是一个Python脚本定义了如何调用LLM、如何处理输入如解析文档链接、获取文档内容。在OpenClaw中注册该技能通过管理界面或API告诉OpenClaw这个技能的触发关键词、描述、所需参数以及执行端点。测试技能在飞书中发送“总结一下这个文档[文档链接]”观察技能是否被正确触发和执行。这个过程涉及更多开发工作也是OpenClaw灵活性的体现。你可以根据团队需求打造专属的自动化工作流比如自动抓取多维表格数据生成日报、监控群聊关键词并提醒等。7. 常见故障排查与优化建议把流程走通后这里汇总一些高频问题和我踩过的坑帮你快速定位。7.1 飞书端验证失败与事件推送问题症状飞书后台“事件订阅”保存失败提示“请求不合法”、“超时”或“invalid redirect uri”。排查域名与路径百分之九十的问题在这里。确保飞书后台的“请求地址”完整路径与OpenClaw服务实际监听的路径完全一致。注意httpvshttps注意末尾有无斜杠。内网穿透稳定性免费ngrok域名会变一变就失效。考虑使用更稳定的穿透服务或者在内网测试时可以使用飞书开放平台的“测试环境”功能如果提供它可能对本地调试更友好。OpenClaw服务健康确保docker-compose ps里所有服务都是Up状态并且网关服务确实在监听8000端口netstat -tlnp | grep 8000。日志是王道在飞书点击“保存”时同时盯着docker-compose logs -f gateway的实时输出。看有没有收到POST请求有没有报解密失败、令牌验证失败等错误。7.2 OpenClaw服务启动异常症状docker-compose up后服务不断重启或日志中有明显错误。排查模型连接失败这是最常见的。检查.env中LLM_API_BASE和LLM_MODEL。对于本地Ollama在宿主机用curl http://localhost:11434/api/tags看看模型是否真的存在且可访问。在Docker容器内localhost指向容器自己所以要改用host.docker.internal或宿主机IP。端口冲突检查8000、3000等端口是否已被其他程序如另一个Docker容器、本地开发服务器占用。配置文件语法错误.env文件要求每行是KEYVALUE格式VALUE中如果包含特殊字符或空格可能需要引号。确保没有多余的空格或换行符错误。可以用docker-compose config命令检查配置是否有效。权限问题如果日志提示无法写入某个目录可能是Docker卷映射的目录权限不足。检查宿主机上对应目录的读写权限。7.3 消息能接收但无回复症状飞书发送消息后OpenClaw日志显示收到了事件但没有后续的回复消息发出。排查技能路由失败日志中是否显示消息被路由到了某个技能是否提示“No matching skill found”这可能是因为消息格式不符合任何技能的触发条件。检查技能的触发词和描述。LLM调用超时或失败查看LLM服务的日志。可能是模型响应太慢导致超时或者返回了非预期的格式导致技能处理出错。尝试在技能配置中增加超时时间。飞书API调用权限不足确保飞书应用已成功获取并发布了im:message:send_as_bot权限。在OpenClaw网关日志中可能会看到调用飞书发送消息API时返回了code 99991663无权限或code 99991664权限未生效等错误。需要去飞书开放平台检查权限状态。7.4 性能与稳定性优化资源占用本地运行LLM尤其是7B以上的模型对内存和GPU要求较高。如果资源紧张可以考虑使用量化版本的模型或者使用性能更好的推理后端如vLLM。使用稳定内网穿透长期使用建议放弃免费的ngrok可以购买具有固定子域名的服务或者使用frp等工具自建内网穿透服务器稳定性可控性更高。配置持久化存储在docker-compose.yml中将数据库如PostgreSQL的数据目录通过volumes映射到宿主机避免容器删除后数据丢失。日志管理Docker容器日志默认会占满磁盘。可以在docker-compose.yml中为每个服务配置日志驱动和大小限制或者使用docker-compose logs --tail50 -f来跟踪最新日志避免全量输出。