很多人第一次听说 OpenClaw 是在某个技术群里看到有人发了一张飞书对话框里 AI 自动回复的截图第一反应是“又是什么花活”第二反应就是“这东西怎么跑起来的”。我最初也是这么入坑的花了差不多两个晚上才把 Linux 服务器上的 OpenClaw 搭好并成功接入飞书中间踩了无数个坑尤其是agent failed before reply: session file locked这个报错卡了我很久。这篇教程就是把我完整的操作过程、每一步为什么这么做、以及踩过的坑都记录下来争取让你跟着走一遍就能跑通。OpenClaw 本质上是一个开源的智能体框架你可以把它理解成一个自带“手脚”的 AI 大脑。它本身不生产回答而是负责把大模型的能力和飞书这样的外部平台连接起来飞书用户发消息OpenClaw 接收后调用大模型生成回复还能按你的配置去执行一些工具操作比如查数据库、发通知、处理表格等等。对于团队里想快速搭一个内部 AI 助手、或者个人想折腾一个私有机器人来说这个方案比直接用商业平台的机器人灵活得多数据也掌握在自己手里。这篇教程适合谁看你不需要是资深运维但至少你得拥有一台 Linux 服务器云服务器或本地虚拟机都行会一点点命令行知道cd、ls是干什么用的。我会尽量把每条命令都解释清楚你照着复制粘贴大概率能成。1. 整体思路与方案选型1.1 为什么选择 Linux OpenClaw 飞书的组合先说结论这个组合是“自托管 AI 助手”里性价比很高的一条路。市面上现成的 AI 群聊机器人不少比如飞书自带的机器人、各种 SaaS 平台的 Bot但它们的通病是逻辑黑盒、无法自定义工具、数据不归你管。OpenClaw 的好处是开源免费你可以把整个服务跑在自己的服务器上想接什么模型、想开放哪些权限、想怎么扩展全由你说了算。选 Linux 而不是 Windows是因为绝大多数云服务器都是 Linux而且 Docker、Python 这类依赖在 Linux 上的支持最完整运行也更稳定。我最初尝试在 Windows 上装折腾了半天环境变量后来切到 Ubuntu 服务器上不到半小时就装好了这就是生态的力量。飞书则是很好的“入口”。它有成熟的机器人 API、支持事件订阅还能收发消息卡片、操作多维表格。接入之后成员不需要额外装任何客户端直接在飞书里跟机器人对话就行门槛降到了最低。1.2 部署方案的两种选择Docker 还是裸机OpenClaw 的官方安装方式主要有两种一种是直接用 Docker 拉镜像跑另一种是在服务器上手动装 Python 依赖、用命令行方式启动。我推荐新手无脑选 Docker。为什么因为 OpenClaw 的依赖比较重涉及多个 Python 包、Node.js 组件裸机安装经常会碰到系统里已经有旧版本 Python 导致的冲突。Docker 把所有依赖封装在容器里你只需要装好 Docker 本身后面的事情就简单很多。如果你之前没接触过 Docker可以把它理解为一个轻量级的“打包箱”里面装有程序运行所需的全部环境无论你在哪台机器上运行行为都一样。OpenClaw 官方镜像把运行时、配置、依赖都打好了你拉下来直接跑省掉 80% 的环境问题。当然裸机安装也不是不行如果你后续要深度二次开发想直接在宿主机上改代码、调试那裸机更合适。但对于“先跑起来再说”的目标Docker 是最稳的路径。下面所有步骤我都以 Docker 方案为主顺带提一下裸机方案的关键差异。1.3 需要的硬件和软件清单可能有人担心 AI 服务对服务器配置要求很高其实不然。OpenClaw 本身只是一个转发调度的进程真正的大模型推理是在云端 API 上做的本地只负责处理消息和调用工具。所以一台 1C2G 的入门云服务器就足够跑得很顺畅了如果你只是测试甚至 1G 内存也能凑合。需要注意的倒是硬盘至少留出 10GB 给 Docker 镜像和日志免得到后面空间不够。软件方面我假设你的服务器系统是 Ubuntu 22.04其他 Debian 系发行版也适用需要 root 权限或者一个能用sudo的用户。另外你手上得有一个飞书开发者后台的账号这个用你的飞书账号登录就能创建应用不需要额外付费。2. 环境准备把服务器收拾干净2.1 安装 Docker 与 Docker ComposeOpenClaw 官方 docker-compose.yml 里通常会包含多个服务比如主进程、可能的中间件所以我们需要 Docker 和 Docker Compose 两个东西。Docker Compose 现在一般作为 Docker 的插件存在安装完 Docker 后执行docker compose version能输出版本号就说明可用了。如果你用的是全新服务器第一步是更新系统包索引sudo apt update sudo apt upgrade -y然后安装 Docker 的官方依赖sudo apt install -y ca-certificates curl gnupg lsb-release接着添加 Docker 官方 GPG 密钥和仓库我这里用阿里云镜像源加速因为国内直连 Docker Hub 经常超时curl -fsSL https://mirrors.aliyun.com/docker-ce/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://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null更新索引并安装 Dockersudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin把当前用户加入 docker 组这样不用每次敲sudo dockersudo usermod -aG docker $USER newgrp docker验证安装docker --version docker compose version看到版本号就说明成功了。这里要特别提醒如果你是在国内云服务器上操作务必把 Docker Hub 的拉取操作配置一个镜像加速器否则后面拉 OpenClaw 镜像会等得让你怀疑人生。具体配置方法是在/etc/docker/daemon.json里写入类似下面的内容{ registry-mirrors: [https://docker.m.daocloud.io] }然后重启 Dockersudo systemctl restart docker2.2 准备项目目录与环境变量文件Docker 的好处是运行环境隔离但配置和数据还是要落在宿主机上方便后续修改和备份。我习惯把这类应用统一放在/opt下面建一个专门的目录sudo mkdir -p /opt/openclaw sudo chown -R $USER:$USER /opt/openclaw cd /opt/openclawOpenClaw 启动时需要很多配置项比如大模型的 API Key、飞书应用的 App ID 和 App Secret、监听端口等等。官方推荐的做法是把这些配置写进.env文件让 docker-compose 自动加载。我们不急着填先创建一个空文件touch .env为什么用.env而不是直接写死在 docker-compose.yml 里因为里面有密钥如果哪天你想把配置分享给同事.env文件可以单独保密不会随同仓库一起泄露。这是个好习惯很多开源项目都这么设计。2.3 确认服务器防火墙与开放端口OpenClaw 默认会开一个 HTTP 服务用于飞书事件回调我用的端口是 8080。如果你服务器有防火墙或者云厂商安全组规则需要把 8080 端口对外开放至少要对飞书服务器的 IP 网段开放。飞书官方会提供一个固定的回调 IP 段你可以到飞书开放平台的文档里查到。实测下来最省事的做法是在安全组里临时允许所有 IP 访问 8080调试完再收紧。但这里有个安全风险如果端口暴露在公网任何人都能往你的服务发请求所以在配置飞书应用时一定要设置好验证令牌并且在后续步骤里把回调路径和令牌匹配上避免被人乱刷。3. 安装 OpenClaw 并完成基础配置3.1 拉取镜像与编写 docker-compose.yml环境准备好之后进入/opt/openclaw目录创建docker-compose.yml。先看看官方模板长什么样我用的版本是 0.1.x具体内容如下version: 3.8 services: openclaw: image: openclaw/openclaw:latest container_name: openclaw restart: unless-stopped ports: - 8080:8080 env_file: - .env volumes: - ./data:/data - ./logs:/logs extra_hosts: - host.docker.internal:host-gateway解释一下这个文件的关键字段。image指定镜像latest标签代表最新版本如果你是生产环境我建议锁定具体版本号比如openclaw/openclaw:0.1.3避免以后更新引发不兼容。restart: unless-stopped的含义是容器意外退出时自动重启除非你手动停止这一点对长期挂机很有用。ports把宿主机的 8080 映射到容器内的 8080后面的volumes挂载则是为了持久化数据和日志这是非常重要的一步因为容器一旦删除里面的文件就全没了挂载到宿主机后就算重装也不会丢聊天记录和配置。extra_hosts是我额外加上去的因为在容器里要访问宿主机上的某些服务比如本地数据库时用host.docker.internal这个主机名来指代宿主机会更方便。如果你的 OpenClaw 要调用宿主机上跑的数据库或 API这个配置就会用到。3.2 配置 .env模型供应商与飞书应用参数接下来是最关键的一步填写.env。OpenClaw 支持多种大模型供应商比如 OpenAI、Anthropic、以及国内的千问、豆包等。我目前用的是千问的 API因为国内访问稳定、价格也低。.env里的模型相关配置大概是这样的# 大模型 API 配置 LLM_PROVIDERqwen LLM_MODELqwen-plus LLM_API_KEY你的千问APIKey LLM_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1这里需要注意不同供应商的BASE_URL不一样千问的兼容模式地址是阿里云 DashScope 提供的 OpenAI 风格接口。如果你用 OpenAI 官方就是https://api.openai.com/v1但国内直接访问可能会有网络问题所以我个人还是优先推荐国内模型。另外LLM_MODEL建议选择qwen-plus或qwen-maxqwen-turbo虽然便宜但复杂任务的表现会弱一些支持工具调用时容易出错。接着是飞书部分。飞书相关的配置我放在后面第四步里讲因为你要先去飞书开放平台建一个应用拿到参数才能填。不过.env文件的骨架里可以先占个位# 飞书应用配置 FEISHU_APP_IDcli_xxxxx FEISHU_APP_SECRET你的AppSecret FEISHU_VERIFY_TOKEN你的验证令牌 FEISHU_ENCRYPT_KEY你的加密密钥密码和密钥不要用太简单的值飞书的加密密钥要求长度固定如果你不启用加密回调FEISHU_ENCRYPT_KEY可以留空但为了安全我建议还是配置上。3.3 启动服务并观察日志写好文件之后第一次启动cd /opt/openclaw docker compose up -d这个命令会先拉镜像再以守护模式启动容器。拉镜像可能需要几分钟取决于你的网络。完成后查看容器状态docker ps如果看到openclaw容器的状态是Up说明启动成功了。接着看日志docker logs -f openclaw日志里会出现类似“Server started on port 8080”的输出同时会有一些模型初始化、飞书适配器加载之类的提示。如果在这里就报错比如模型 API Key 无效你应该先解决掉再继续别等到后面测试的时候才回来找问题。4. 飞书应用创建与回调配置4.1 在飞书开放平台创建企业自建应用打开飞书开放平台用你的飞书账号登录然后进入“开发者后台”。点击“创建企业自建应用”名称可以叫“我的助手”描述随便写。创建完成后你会进入应用详情页这里有几个关键信息需要记下来App ID、App Secret。App ID 形如cli_xxxxxxxxApp Secret 是一串较长的字符串。这里有个很容易踩的坑如果你用的是个人飞书账号而不是企业管理员账号可能没有权限创建企业自建应用。解决办法是让企业管理员在管理后台给你开通“应用开发者”权限或者直接由管理员帮你建应用然后把凭证发给你。另外飞书开放平台有“测试企业”模式你可以创建一个测试企业来练手但这种方式下应用只能在测试企业里用不适合最终实际落地。4.2 配置机器人能力和事件订阅创建完应用后在应用的能力配置页里找到“机器人”选项启用它。启用后飞书应用会获得机器人能力可以像普通用户一样被拉进群聊或私聊。接下来是重点配置事件订阅。OpenClaw 需要接收飞书的消息事件所以我们要在“事件与回调”页面配置一个“订阅方式”推荐选择“使用长连接接收事件”。这和我们之前开放的 8080 端口有什么关系长连接模式其实不需要公网回调地址飞书服务器会主动跟你的客户端建立一个长连接通道这样更安全也不要求服务器有公网 IP。如果你选择“使用 HTTP 回调”那么就必须配置回调地址比如http://你的服务器IP:8080/webhook/feishu同时要把飞书服务器的 IP 加白。但很多人的服务器是 NAT 后的虚拟机或者没有公网 IP这时候 HTTP 回调用不了长连接就是救命稻草。OpenClaw 官方推荐使用长连接模式它会在服务启动后主动去飞书建立连接你只需要在飞书后台添加好事件订阅并把重试设置调好即可。需要订阅的事件主要是message接收消息message_read消息已读可选application_scope相关权限用于机器人权限校验订阅事件之前你要在“权限管理”里给应用添加相应的权限比如im:message读取消息im:message:send_as_bot以机器人身份发送消息contact:user.base:readonly可能需要视功能而定权限申请通过后事件订阅才能生效。这里有个细节飞书的事件订阅有个“验证”过程如果你配置了加密策略飞书会发送一个加密的验证请求你的服务必须正确解密并返回 challenge否则后台会提示“事件订阅验证失败”。OpenClaw 已经内置了飞书 SDK 的处理逻辑一般来说只要.env里的 App ID、App Secret、Encrypt Key 都填对验证会自动通过。但如果你开着docker logs会看到验证请求的日志正常时会出现“challenge accepted”之类的内容。4.3 发布应用版本并添加可用成员应用刚创建时是“开发中”状态需要发布一个版本才能在实际环境中使用。进入“版本管理与发布”创建版本填写版本号和更新说明然后提交发布。如果你的企业启用了审核流程需要等审核通过如果是测试企业或者管理员直接审核基本秒过。发布后在“成员管理”里把要使用机器人的成员加进来或者至少要添加你自己作为可用成员。拉到群聊时你在群设置里搜索应用名称添加机器人即可。如果是私聊直接在飞书搜索框里搜机器人的名字就能找到。5. 模拟运行与飞书测试5.1 在飞书里和机器人打招呼所有配置完成后理论上已经可以在飞书里测试了。先在私聊里找到你的机器人发给它一条消息“你好介绍一下你自己”。正常情况下过一两秒你会收到机器人的回复。这个过程中 OpenClaw 的日志会显示收到一条来自飞书的消息然后它会调用大模型生成回复再通过飞书 API 发回去。如果这一步顺利恭喜你核心链路已经通了。如果机器人没有任何反应先看 docker 日志有没有报错比如received unknown event说明事件订阅的事件类型不对去飞书后台检查你订阅了哪些事件。unauthorized request说明验证令牌不匹配检查.env里的FEISHU_VERIFY_TOKEN是否和后台一致。app_id or app_secret invalid说明凭证错了重新复制粘贴。私聊测试通过后你可以创建一个群把机器人拉进去在群里 它 提问。群聊场景需要机器人具备“接收群 消息”的能力这个在飞书后台的机器人设置里可以勾选。5.2 让机器人学会查天气、发表格等工具能力OpenClaw 的核心卖点是“工具调用”。默认装好后它有一组内置工具你可以在配置里开启。比如你想让它查询天气预报可以给它配置一个天气插件如果你用的是飞书多维表格还可以让机器人直接读写表格数据。这里我以“让机器人发送表格”为例。飞书机器人发送表格本质上是发送一条富文本消息或者发送一个多维表格记录。OpenClaw 的飞书适配器支持一种“卡片消息”扩展你可以让大模型输出结构化的卡片 JSONOpenClaw 会自动把它转成飞书卡片。具体做法是在.env里打开卡片支持开关FEISHU_ENABLE_CARDtrue然后你在对话里让机器人“生成一个本周工作计划的表格”它会输出卡片形式的内容。实际上这个大模型并不真的生成一张表格文件而是生成一个多维表格的在线链接或者卡片里的表格元素但观感上已经很“表格”了。如果你希望机器人能操作多维表格就需要在飞书后台给应用添加多维表格的 API 权限然后在 OpenClaw 里配置多维表格的 App Token 和工作表 ID。OpenClaw 有一个feishu_bitable工具你可以通过对话指示它往指定的表格里写入数据。这个功能很适合做自动化日报每天晚上让机器人在多维表格里新增一条今日总结记录。5.3 长连接模式下的断线重连长连接虽然方便但有个问题如果服务器重启或者网络波动连接可能会断开。OpenClaw 内置了重连机制日志里偶尔会看到reconnecting to feishu...的字样这属于正常现象。但如果你发现有长时间断线没有自动重连可以排查一下是不是容器内的 DNS 解析有问题或者服务器的出站网络不稳定。一个土办法是在 docker-compose.yml 里给容器加一个restart: always然后在宿主机上写一个定时任务每分钟检查一次容器是否存活不存活就重启crontab -e添加一行* * * * * /usr/bin/docker inspect -f {{.State.Running}} openclaw | grep -q true || /usr/bin/docker restart openclaw这行命令每分钟检查一次容器的运行状态如果发现没在运行就重启它。虽然是笨办法但实测非常管用。6. 常见问题与排查技巧实录6.1 最头疼的报错session file locked很多人在日志里看到agent failed before reply: session file locked (timeout 60000ms)然后整个人就懵了。这个报错我第一次遇到时也研究了好一阵最后定位到原因是 OpenClaw 的“会话文件”机制它会把每个对话的上下文保存在本地磁盘上如果同一个会话同时有多个请求正在处理就会产生文件锁冲突。简单说就是机器人还没处理完上一条消息新的消息又来了老的进程占着会话文件不放新的进程等了 60 秒还没等到锁释放就超时报错了。解决办法有两个。一是降低并发请求数在.env里设置MAX_CONCURRENT_TASKS1让 OpenClaw 一次只处理一个会话请求这样从根本上避免竞争。二是定期清理会话文件在/opt/openclaw/data目录下找到对应的 session 文件删除后重置。如果你想保留历史记录也可以写个定时任务每小时清理一次超过 24 小时未访问的会话文件。如果这个报错出现得非常频繁还要检查是不是有大模型 API 响应非常慢导致单条消息处理时间过长。可以试着换一个更快的模型或者把超时时间从默认的 60 秒调大一点比如在.env里加AGENT_REPLY_TIMEOUT120但调大超时不是治本的办法最根本的思路还是限制并发。6.2 飞书消息内容被截断有网友反馈机器人在飞书里回复内容太长时会被截断。这个问题的原因很可能是飞书消息接口对单条文本长度有限制通常是 20000 字节左右一旦超过就会自动截断。另外如果你用的是长连接模式底层是基于 WebSocket 传输单条消息长度也有限制。OpenClaw 本身没有做自动分片所以需要你手动优化。最简单的办法是在.env里设置MAX_MESSAGE_LENGTH15000让 OpenClaw 在发送前自动把长消息截断到安全阈值内。但更好的办法是让大模型输出精简回答在系统提示词里加一句“回答尽量控制在 500 字以内”。如果你需要发送长文档可以引导机器人生成飞书云文档链接而不是把全部文本发到聊天框里。6.3 飞书后台显示“应用未启用”但机器人能回复有时候你在飞书后台看到应用状态是“已停用”但机器人又能正常回复这是因为你测试用的是“开发版本”跑在开发环境沙箱里。这种情况下你的服务其实能工作但一旦应用被正式停用通道还是会断。处理方式很简单去后台重新启用应用并发布一个新版本。另外如果你改了机器人名称或头像需要重新发布版本才能在用户侧生效。另一个容易混淆的点飞书应用的“安全性”设置里有个 IP 白名单如果你启用了 IP 白名单但服务器 IP 不在名单里事件订阅的验证和消息接收都会被拒绝。OpenClaw 在这块常常被坑因为很多人在测试时为了方便把白名单关了后来开启后忘了加服务器 IP结果突然全部失灵。6.4 Docker 容器反复重启且看不到日志如果docker ps显示容器状态一直是Restarting大概率是配置文件出错了。最常见的是.env格式问题比如值里有特殊字符没加引号或者等号前后有空格。Docker 的env_file解析比较严格KEY VALUE会导致整行被当成非法配置。你可以先在宿主机器上手动验证.env是否可读set -a; source .env; set a; echo $LLM_API_KEY如果输出的 Key 是空的或者报错说明.env解析有问题。另外用docker compose config命令可以检查配置文件的语法。6.5 免费服务器和低配机器上的性能优化建议如果你用的是免费试用的云服务器配置通常很低跑 Docker OpenClaw 可能会卡。我实测下来1C2G 的机器能跑但内存容易吃紧。你可以通过调整 Docker 的资源限制来防止 OOMdeploy: resources: limits: memory: 1024M同时在.env里把模型设置为qwen-turbo这种轻量级模型响应速度更快内存占用也小。日志开启docker logs时不要一直挂着看会把磁盘占满。定期执行docker system prune清理无用镜像和缓存。另外一个优化技巧是如果你的服务器时区不是中国标准时间飞书的消息时间戳可能会错位 8 小时可以在容器里设置时区environment: - TZAsia/Shanghai7. 我的一些体会和后续扩展建议写到这儿OpenClaw 接入飞书的核心流程已经全部跑通了。说实在的这个项目最难的并不是敲命令而是理解“事件驱动”这一套逻辑飞书把消息推给你你的服务处理完再调飞书的接口发回去中间任何一个环节的凭证、权限、网络不通都会悄无声息地失败。所以你在配置的时候一定要养成看日志的习惯每改一个配置就重启一次容器然后盯着docker logs的输出。我在调试阶段至少重启了几十次容器每次都能从日志里发现新线索。最后分享一个小技巧把 OpenClaw 当成一个“私有工具网关”来用而不是一个简单的聊天机器人。你可以把它接上团队的知识库、接上内部系统的 Webhook、接上定时任务让它在每天早上自动推送工作汇总。等到你熟悉了配置之后可以尝试写一些简单的扩展脚本OpenClaw 支持自定义工具接入你只要按它的接口规范写一个 Python 函数就能让飞书机器人拥有“任意超能力”。这才是真正值的探索的方向。