最近我把 OpenClaw 部署到一台闲置的 Linux 机器上并且成功接入了飞书机器人。说实话“OpenClaw 部署 飞书机器人”这几个字看起来不复杂实际跑起来还是有不少坑的尤其是agent failed before reply: session file locked (timeout 60000ms)这个报错差点把我劝退。这篇不聊虚的把我从零到跑通的过程完整写下来怎么选 channel、怎么配本地大模型、飞书发表格怎么做、长文本怎么避免被截断全部按实际操作顺序来。如果你是第一次接触 OpenClaw或者想在飞书里挂一个能调用工具、能回答问题的 AI 助手这篇基本可以直接当操作手册用。1. 先把 OpenClaw 的定位搞清楚1.1 它解决的不是“聊天”问题而是“消息路由”问题我第一次看到 OpenClaw 这个名字第一反应是“又一个聊天机器人框架”后来配完才发现它的核心价值不在聊天本身而在消息通道和 Agent 之间做了解耦。你可以把 OpenClaw 理解成一个中间层左边连接各种 IM 入口比如飞书、钉钉、Teams、Slack右边连接各种模型和工具比如本地 Ollama 跑的 Qwen、DeepSeek 的 API甚至是一些外部工具。用户发一条消息到飞书群里飞书把事件推给 OpenClawOpenClaw 再拿着上下文去调模型、执行工具最后把结果以飞书消息的形式回传给用户。整个过程里模型和通道互相不知道对方的存在替换模型或者增加渠道都不需要重写业务逻辑。这个设计对于我这种“手里模型经常换、且希望统一入口”的人特别合适。今天想用 Ollama 跑 Qwen明天想切换成 DeepSeek只需要改一个配置项不需要动飞书那边的任何东西。这才是 OpenClaw 值得部署的核心原因。1.2 为什么不用飞书开放平台直接写 Bot很多人会问飞书自带机器人能力直接在飞书开放平台创建一个自定义机器人用 Python 写个回调不就行了为什么要额外引入 OpenClaw我试过直接对接飞书机器人确实能跑但有几个问题很烦飞书机器人接收到的是一堆事件结构体你要自己解析消息类型、 逻辑、回复上下文还要自己管理会话状态。当你想让机器人调用多个工具或者做多轮工具调用时回调代码会迅速膨胀最终变成一团难以维护的“回调粘合层”。换模型或者加一个新的消息通道时整个回调处理逻辑可能要重写。OpenClaw 把这些事情都收编了消息进来之后它自己维护 session、处理工具调用、拆解模型输出然后统一转成目标 channel 的消息格式。我要做的事情就是把 channel 配好把模型地址填好剩下的是使用层面的问题。对我这种不想跟飞书事件签名轮询死磕的人来说这个抽象价值非常高。1.3 部署前我准备的硬件和软件先说说我用的环境给大家一个参考基线系统Ubuntu 22.04 LTS4 核 8G 内存单独的一块 SSDDocker24.0.2装了 docker-compose 插件本地模型先用 Ollama 跑qwen2.5:14b后续换成 DeepSeek-R1 蒸馏版网络条件服务器能正常访问飞书开放平台接口部署机可以访问局域网。OpenClaw 本身对硬件要求不高因为它只是一个消息转发和 Agent 编排层真正的算力消耗在模型那边。如果你的模型也跑在同一台机器上建议至少 8G 内存起步。如果只是接云端 API比如 DeepSeek 官方接口或者 MiniMax 的接口那用一台 2 核 4G 的小机器也完全够用。我在 Windows 上也看过 OpenClaw 的 Hub 安装版但因为我后续要常驻服务最终选 Linux Docker。这里有一个个人建议如果是正规生产使用不要用 Windows 桌面版长期挂机进程容易被系统休眠和更新打断。Linux 服务器 systemd 或者 Docker 的restart: always才是省心组合。2. 部署 OpenClaw 的两种姿势2.1 Docker Compose 方式最省心的路子OpenClaw 官方没有提供特别花哨的一键安装包最常见的推荐方式是 Docker Compose。我在/opt/openclaw目录下新建了一个docker-compose.yml结构大概是version: 3.9 services: openclaw: image: openclaw/openclaw:latest container_name: openclaw restart: always ports: - 18789:18789 volumes: - ./data:/data - ./config:/config environment: - TZAsia/Shanghai command: [serve, --config, /config/config.yaml]启动之前我先建了config和data两个目录。data目录主要放 session 数据这是后面会遇到报错的关键地方。然后执行cd /opt/openclaw docker compose pull docker compose up -d看到容器状态是Up之后再去看日志docker logs -f openclaw正常情况下会看到类似listening on :18789的输出。这个端口是 OpenClaw 自身的控制面端口飞书事件回调也会指向这个端口的某个路径。容器起来了不代表配置正确真正的考验在接入渠道之后。2.2 命令行方式适合调试和二次开发如果你不想用 Docker或者需要在里面跑自定义 Python 插件也可以直接用命令行方式。我试过一次步骤其实更直观安装 openclaw 命令行工具。初始化配置目录openclaw init。修改生成的config.yaml。执行openclaw serve --channel feishu --config config.yaml。命令行方式的好处是日志输出很直接方便在终端里观察飞书消息进来之后到底发生了什么。缺点是因为没有 Docker 隔离依赖版本冲突时处理起来比较费劲。我的建议是新手优先用 Docker想改源码或者调试 session 文件时再用命令行。不过不管是哪种方式最后都会落到同一个文件config.yaml上这个文件是 OpenClaw 的全部灵魂。2.3 初始化配置里的关键字段我第一次打开生成的config.yaml时有点懵字段不算多但不知道哪些必填。这里展示一个我后来精简出来的最小配置agent: name: claw system_prompt: 你是一个靠谱的助手回答要简洁、准确。 model: provider: ollama name: qwen2.5:14b base_url: http://localhost:11434 channels: feishu: enabled: true app_id: cli_xxxxx app_secret: xxxxx verify_token: xxxxx encrypt_key: server: port: 18789 public_url: https://your-domain.example.com其中base_url就是 Ollama 服务的地址如果 Ollama 也在 Docker 里跑需要写容器间可访问的地址比如http://host.docker.internal:11434或者同一网络里的服务名。public_url这一项很关键这是飞书回调时访问的地址必须是一个公网可达的 HTTPS 地址。很多教程没有强调verify_token的作用它其实是飞书开放平台的事件订阅校验凭证。你在飞书后台配置事件订阅 URL 时平台会先用这个 token 做一个验证请求OpenClaw 需要用这个 token 来响应。如果你漏填了飞书那边会一直提示“URL 验证失败”。这个坑我踩过一次后面还会细说。3. 把大模型接进来本地模型与云端模型3.1 用 Ollama 跑本地模型OpenClaw 本身不内置模型能力它需要外接一个推理服务。我比较推荐先上 Ollama因为安装简单命令也短curl -fsSL https://ollama.com/install.sh | sh ollama pull qwen2.5:14b ollama serve跑起来之后先自己验证一下模型服务是否正常curl http://localhost:11434/api/generate -d {model:qwen2.5:14b,prompt:你好}如果能看到返回结果说明模型服务已经就绪。接着在 OpenClaw 的配置里把 provider 指定为ollamaname 写成你拉下来的模型名。要注意的是name必须和 Ollama 里的 tag 完全一致不能只写qwen2.5我因为:14b这个 tag 漏写导致 Agent 一直返回错误后来查日志才发现是模型名没对上。本地模型的好处是不用担心 API 费用和隐私数据外泄适合内部知识库相关场景。缺点就是响应速度受限于硬件条件。在 4 核 8G 的机器上跑 14B 模型单次回复可能需要十几秒到三十秒飞书那边等久了偶尔会触发超时重试所以如果对速度敏感可以选更小的 7B 模型。3.2 配置 DeepSeek 或 Qwen 的云端接入后来我又测试了云端模型用的是 DeepSeek 的 API。OpenClaw 支持的 provider 里有openai兼容协议所以配置写法几乎一样model: provider: openai name: deepseek-chat base_url: https://api.deepseek.com/v1 api_key: sk-xxxxx这里有个小细节base_url一定要写到/v1很多教程漏了这个导致 404。另外飞书上如果出现长时间“思考中”的状态其实是因为云端模型的流式输出被某些代理层缓冲了后面我会说怎么调。如果你用 MiniMax H3 或其他模型同样走 OpenAI 兼容协议只是base_url和name不同。OpenClaw 的模型层抽象做得比较干净切换模型很多时候就是改config.yaml里的三行字。3.3 关于 model 参数的冷门注意点在我实际使用中发现 OpenClaw 对模型的temperature、max_tokens这类参数并不像 LangChain 那样单独暴露而是藏在model.options里。我一开始没有配max_tokens导致 DeepSeek 默认输出较短飞书回复经常写一半就断了。后来加了这个配置model: provider: openai name: deepseek-chat base_url: https://api.deepseek.com/v1 api_key: sk-xxxxx options: temperature: 0.7 max_tokens: 4096这里建议max_tokens不要设得太大因为飞书单条消息有长度限制OpenClaw 会把超长内容拆成多条发送但拆得太碎会破坏阅读体验。最佳实践是先把max_tokens控制在 2048 左右再结合后面提到的分段发送逻辑来处理长文本。关于 model 选择我个人经验是日常知识问答用qwen2.5:14b本地模型够了需要复杂推理或者代码生成时切到deepseek-chat或者更大的模型。没必要一个模型打天下OpenClaw 的 channel 会话上下文支持按用户区分但我还没做到按会话动态切换模型目前是全局配置后续可以研究。4. 飞书机器人的接入与消息调试4.1 在飞书开放平台创建企业自建应用接入飞书机器人先要去飞书开放平台后台创建一个“企业自建应用”。具体路径是开发者后台 → 创建企业自建应用 → 填写应用名称和描述。创建好之后需要拿三个关键凭据App ID格式一般是cli_开头App Secret创建应用后生成事件订阅的 Verfication Token进入“事件与回调”页面添加事件监听。我添加了im.message.receive_v1这是接收用户消息的必需事件。在订阅方式里我选择了“长连接”模式因为这个模式不用提供公网 HTTPS 回调地址比较适合没有固定公网 IP 的内网测试环境。如果你有公网域名和 HTTPS 证书也可以选择“HTTP 模式”。这时需要把事件回调 URL 填成 OpenClaw 暴露出来的公网路径。这里要特别提醒飞书要求回调 URL 必须是 HTTPS且不能是自签名证书否则会一直验证失败。我第一次用局域网 IP 去填飞书直接提示“URL 不可用”。拿到的三个凭据要妥善保存后面都要填到 OpenClaw 的config.yaml里。4.2 OpenClaw 中配置 feishu channel回到 OpenClaw 配置文件把刚才申请的凭证填进去channels: feishu: enabled: true app_id: cli_xxxxx app_secret: xxxxx verify_token: xxxxx encrypt_key: 我发现一个比较坑的细节verify_token虽然叫 token但在 OpenClaw 内部参与的是飞书事件订阅的签名校验。如果这里填错了日志里会频繁出现invalid signature。我当时把飞书的 App Secret 当成 verify_token 填了结果日志一直报签名错误折腾了很久才发现是两个不同的值。填好配置后重启服务再用飞书给机器人发一条消息。如果一切正常OpenClaw 日志里会看到收到事件并且开始调用模型最终飞书里出现回复。如果你遇到“这个机器人无法主动发消息给你”的情况多半是没有在飞书后台开启“机器人”能力。需要在“应用能力”里添加“机器人”能力并发布应用版本。这是新人最容易漏掉的一步。4.3 让机器人会发表格卡片消息与富文本很多场景不只是让机器人回文字还要它回一个结构化表格。比如让它查数据库、统计系统状态然后输出一张表格。热搜词里也有“飞书机器人发送表格”这个确实是一个高频需求。OpenClaw 对表格的支持不是直接拼字符串表格而是把 Agent 的输出结构化为飞书卡片消息。我一开始让它输出 Markdown 表格发现飞书里会显示成原始竖线和横线字符很难看。后来改用卡片消息的table结构效果才正常。在 OpenClaw 的 channel 配置里有一个message_style选项可以设成card。当模型输出以 JSON 形式携带表格数据时OpenClaw 会将其转换成飞书卡片channels: feishu: enabled: true message_style: card当然这要求你给 Agent 的 prompt 里有明确指令比如“当回答包含表格数据时使用表格输出”。实际操作时我是在系统提示词里加了一段如果回答中包含结构化数据请用 Markdown 表格输出列名要清晰。我发现 OpenClaw 对表格消息的支持有一定模板限制如果模型输出的表格列数太多也会被截断。所以后面我改成让模型把表格存成 CSV 字符串再让 OpenClaw 以飞书“上传文件”的形式发出去这样无论多长的表格都能完整传递。这个技巧在数据量很大的场景下特别实用。5. 那些让我头秃的报错与排查5.1 session file locked? 会话文件锁的真相这个报错是我遇到的第一个大坑日志里完整信息是agent failed before reply: session file locked (timeout 60000ms)翻译成人话就是“会话文件被锁住了等了 60 秒还没解开”。这个“session file”就是 OpenClaw 在/data/sessions目录下保存的会话状态文件用于记录每个对话的历史消息。出现这个报错的原因通常有两个第一上一个 Agent 进程还在处理同一个会话文件锁没有释放。比如你给机器人连续发了两条消息OpenClaw 内部如果没配置并发限制第二个请求就会去锁同一个 session 文件发现锁被占用于是等待直到超时报错。第二进程崩溃后留下了一个陈旧的锁文件。就像程序中途被杀掉锁没有正常释放。这种情况在 Docker 容器重启时很常见。另外如果多个任务同时写入同一个 session 文件会有竞争条件。OpenClaw 为了避免 session 数据被写坏会做文件锁。时间一长如果锁等待设置得太小高并发下就会超时。我的解决办法分几步先确认这个会话是不是真的在被另一个进程占用。ps aux | grep openclaw然后用lsof查看该 session 文件的锁状态ls /data/sessions/ lsof /data/sessions/xxx.session如果找不到占用进程那就是陈旧锁。干脆停掉服务把对应的 session 文件备份后删掉再重启服务。docker compose stop openclaw mv /data/sessions/xxx.session /tmp/xxx.session.bak docker compose start openclaw这个操作会丢失那个会话的历史上下文但能最快恢复服务。如果不想丢上下文可以用openclaw session unlock session-id这类命令释放锁不过不同版本命令名可能不同我这边是通过删除文件解决的。预防这种问题的经验是尽量不要让同一个飞书会话频繁连续触发 Agent。可以在飞书机器人端设置“输入中”状态来降低用户连发消息的概率。OpenClaw 本身也可以改超时参数比如server: session_timeout_ms: 120000可以把 60000ms 调大一点但根本解法还是避免并发操作同一个 session。5.2 agent failed before reply 不只是模型问题日志里有一个非常具有误导性的报错agent failed before reply。我一开始以为是大模型返回了空内容把 Ollama 换成了 DeepSeek问题依然存在。后来打开 debug 日志才发现绝大多数情况下是前面的session file locked异常被封装成了这句泛化提示。当你看到agent failed before reply第一件事不是去调模型而是去看更早的日志输出。通常完整错误栈里会告诉你具体是哪一步出的问题session file locked会话锁问题timeout模型调用超时或者工具调用超时invalid signature飞书签名校验失败tool execution error某个工具执行时抛了异常我的做法是给 OpenClaw 单独开启 debug 日志级别logging: level: debug然后把日志输出到文件方便查docker logs openclaw 21 | tee /tmp/openclaw.log日志会详细记录每一次消息从收到事件到调用模型、再到返回结果的流程。几乎所有问题都能在这里找到线索。5.3 飞书长文本被截断的解决办法热搜词里有一条“openclaw在飞书输出容易被截断”我也遇到了。模型一口气生成了几千字飞书消息只显示了前面几百字后面的内容直接消失。先说飞书本身的限制飞书机器人单条文本消息的字节长度上限大约是 150KB 左右但实际发送时如果你用的是文本消息类型很多客户端显示会截断过长内容。具体截断位置不一定按行而是按消息段的 boundary。OpenClaw 如果不做分段处理就会把模型的一大段输出直接丢给飞书 API飞书 API 接收超长文本时可能报错或者静默截断。我的解决方式分两个层面第一在 OpenClaw 配置里设置输出段的最大字符数比如channels: feishu: enabled: true max_message_length: 1500第二让模型自己学会压缩或分点输出。在 prompt 里加上“回答尽量分条每个要点不超过 100 字”。这个方法对大多数模型都有效。如果你必须发送长文比如日志或大段代码就别用普通文本消息了直接转成飞书云文档或文件。OpenClaw 支持文件上传类的消息我一般让 Agent 把长内容写到一个临时文件里然后调用上传工具发送给用户。这种方式不仅绕过截断问题还方便用户下载保存。对了还有一个隐性截断点OpenClaw 的max_tokens设得太小模型在输出中间就被掐断也会表现出“飞书回复不完整”。这种情况不是飞书截断而是模型没有生成完。排查时可以先看日志里模型返回的finish_reason如果是length就说明是长度限制需要调大max_tokens如果是stop那才是飞书消息层的问题。这个经验让我少走很多弯路。6. 运行截图之外的验收与扩展6.1 我实际验收的流程部署完、接完飞书之后我是按下面这条链路验收的在飞书群里机器人说“你好”确认能收到“你好”的回复。问一个需要推理的问题比如“9.9 和 9.11 哪个大”确认模型没有答错。写一段代码生成的请求确认 Agent 能正常输出 Code Block 格式。要求用表格输出一周计划确认卡片表格消息正常。连续快速发送三条消息确认没有触发 session file locked。发一段长文确认不会被截断。其中第五步最容易暴露问题如果你也用我前面提到的旧方式部署连续快速发消息大概率会看到日志里出现 waiting acquired lock 之类的警告。后来我干脆把 OpenClaw 的concurrency_per_session参数设成了 1也就是同一个会话同一时间只允许一个 Agent 任务。这样做虽然会让第二条消息排队但至少不会把 session 文件搞乱值得推荐。6.2 后续扩展方向OpenClaw 接飞书跑通之后能玩的东西不少。我目前在做的扩展有三个方向方向一接上 MCP 工具。OpenClaw 支持 MCP 协议可以用来连接 Neo4j、数据库查询、请求外部 API。比如开源社区里比较常见的mcp-neo4j-cypher把图数据库查询能力暴露给 Agent飞书里问一句“查一下某某关联关系”Agent 就能直接执行 Cypher 并返回结果。这个部署起来其实就是多跑一个 MCP server然后在 OpenClaw 工具配置里注册一个 endpoint。方向二多渠道统一接入。我已经把飞书跑通了后续想把 Microsoft Teams 也接进来。OpenClaw 的 channel 设计得比较一致Teams 的配置字段和飞书大同小异。你只需要在飞书和 Teams 两个后台分别创建机器人然后填到同一个config.yaml里。方向三和 Dify、Langfuse 这类工具链结合。OpenClaw 主要负责消息入口和 Agent 调度Dify 可以做更复杂的 RAG 流程Langfuse 可以记录推理链路。我现在正在把 OpenClaw 的模型推理日志转发到 Langfuse做一个简单的可观测性面板这样飞书上的每个问题都能看到 token 消耗和耗时。另外如果要在机器上装更多服务比如 Goldendb 三节点部署、Dify 本地部署建议造一个独立的 Docker 网络把 OpenClaw 和其他中间件放到同一个 network 里这样容器间就不用开一堆端口映射也安全一些。6.3 一点心得体会最后说几句大实话。OpenClaw 这个项目本身不难难的是你把它和飞书机器人、本地模型串起来的那一刻。你会同时面对飞书开放平台的权限配置、OpenClaw 的会话锁机制、模型服务的并发能力任何一个环节出错表面现象都是一句模糊的agent failed before reply。我个人觉得最值钱的不是部署过程而是那套排错思路遇到问题先看完整日志再判断是哪一层的问题最后针对性地去查飞书文档还是 OpenClaw 文档。千万不要看到一个报错就急着换模型、换机器那样只会让问题更复杂。如果让我重新部署一遍我会先用 Docker Compose 快速起一个最小实例跑通“飞书消息 → OpenClaw → Ollama → 回复”这条主线然后再慢慢加模型、加工具、加卡片模板。这种增量方式比一上来就追求“完整体验”要稳定得多。希望这篇文字能帮你少踩几个坑把 OpenClaw 真正用起来。