把 OpenClaw 跑起来这件事，我在部署文档里来回折腾了差不多一个下午。不是装不上，而是每一步都会遇到同样的尴尬：文档只讲“做什么”，不讲“为什么这样做”；飞书后台的配置项和项目配置文件里的字段，对应关系全靠自己猜。所以这篇教程我直接按“防踩坑版”写，把链路讲透、把参数对照表给全，照着操作基本一次能通。
OpenClaw 是一个开源智能助手框架，核心能力是把大模型、工具调用和消息渠道串起来。你可以把它想成一个跑在自己服务器上的“私人助理”：它能接收消息、理解意图、调用预设工具，再把结果返回给你。而飞书是它的一个消息入口——你在飞书里和机器人对话、发指令、收结果，体验跟在群聊里 @ 一个同事差不多。
这套东西适合谁？熟悉 Linux 基本操作、会装 Docker、想私有部署个人助手的开发者。不需要懂模型训练，也不需要精通飞书开放平台，按步骤走就行。下面我从链路原理开始讲，再给部署和对接的完整步骤，最后把我在实际部署中踩过的坑全部列出来。
1. 先想清楚整条链路：OpenClaw 和飞书到底是怎么连上的
1.1 两个角色的分工
很多人在部署 OpenClaw 和飞书对接时卡住，核心原因是没有理解参与方各自的职责。这个系统里主要有三个角色：用户、飞书开放平台、OpenClaw 服务。
用户不做任何技术操作，只是在飞书聊天窗口里给机器人发消息。飞书开放平台负责把这个消息包装成一个标准事件，推送到你配置的回调地址。OpenClaw 服务则是你的私有服务器上一直运行的程序，它接收到事件后，解析内容、调用模型或工具，最后生成回复。
关键点在这里：飞书开放平台和 OpenClaw 之间不是一条常驻的双向连接，而是“回调 + API”的组合。飞书主动把消息推给 OpenClaw，走的是你配置的回调 URL；OpenClaw 把回复发回去，走的是飞书的开放 API。这两个方向用的凭证和配置完全不同，后续配置时很容易混淆。
1.2 一次完整对话的五个步骤
把一次私聊消息拆开看，整个过程是这样的：
- 用户在飞书里给机器人发一条消息，比如“帮我把这几条 TODO 整理成列表”。
- 飞书开放平台收到这条消息，将它包装成一个事件，通过 HTTP POST 请求推送到 OpenClaw 暴露的回调接口。
- OpenClaw 收到请求后，先校验签名和事件类型，再解析消息内容。
- OpenClaw 根据消息内容，调用配置好的大模型或工具，生成结果。
- OpenClaw 拿着登录凭证（App ID 和 App Secret）调用飞书 API，以机器人身份把回复发送到原会话。
理解这五步，后面配置时就不会乱。你会发现第 2 步依赖“事件订阅”，第 5 步依赖“应用凭证”。如果配好了但消息有去无回，排查方向就是第 2 步；如果消息能收到但机器人不回，排查方向就是第 5 步。
1.3 部署前需要准备的清单
开始动手之前，先把下面这些准备好，避免配置到一半才发现缺东西：
- 一台有公网 IP 的服务器，2 核 4G 内存起步，系统推荐 Ubuntu 22.04 或 Debian 12。
- 一个已经解析到该服务器的域名。飞书要求回调地址必须是公网可达的 HTTPS 地址，所以域名不是可选项。
- 服务器上装好 Docker 和 Docker Compose。不会装的话，Docker 官网有二进制安装脚本，几分钟能搞定。
- 一个飞书账号，完成开放平台开发者认证。个人账号就能创建自建应用，不需要企业资质。
- 本地能访问飞书开放平台后台，后续所有飞书侧配置都在网页上完成。
这套链路不依赖图形界面，OpenClaw 本身是一个无头服务，所有交互都通过消息完成。
2. 服务端部署：用 Docker 把 OpenClaw 跑起来
2.1 为什么要用 Docker 而不是直接裸机跑
OpenClaw 涉及运行时、第三方依赖和配置文件管理，裸机部署不是不行，但会很痛。我推荐 Docker 的理由有三个：
第一，依赖隔离。OpenClaw 可能需要特定版本的运行环境，用容器打包之后，不会污染服务器上已有的环境，也不会和其他服务打架。
第二，升级方便。新版本发布后，拉新镜像、重启容器即可完成升级，不需要手动处理依赖变更。
第三，运维省心。容器崩溃后会自动重启，日志可以用 docker logs 查看，文件挂载到宿主机后备份也方便。
如果你已经有了 docker-compose 的习惯，那更顺手。如果没用过，也别慌，后面步骤里所有命令都能直接复制运行。
2.2 拉取镜像并准备持久化目录
先创建 OpenClaw 的工作目录，我习惯放在 /opt 下面：
mkdir -p /opt/openclaw/data cd /opt/openclaw然后拉取镜像。OpenClaw 的镜像是公开的，直接拉最新版即可：
docker pull ghcr.io/openclaw/openclaw:latest这一步在部分网络环境下可能比较慢。如果拉取超时，可以在 Docker 的 daemon.json 里配置镜像加速源，各个云厂商控制台都有对应文档，配置成功后重启 Docker 服务再拉一次。
2.3 编写基础配置文件
OpenClaw 使用 YAML 格式的配置文件。先写一个最基础的版本，保证服务能起来：
# openclaw.yml app: port: 8080 log_level: info channels: feishu: app_id: "" app_secret: "" encrypt_key: "" verification_token: "" callback_path: "/feishu/callback"这里先把飞书相关字段留空，等飞书开放平台配置完再回填。callback_path 是 OpenClaw 用来接收飞书事件的 HTTP 路径，可以自定义，但后面飞书后台填写的请求地址必须和它保持一致。
注意，不同版本的 OpenClaw 配置字段名可能略有差异。拉取镜像后可以先查看项目文档确认，如果字段对不上，以后续 release 版本的实际配置为准。
2.4 启动容器
启动命令如下：
docker run -d \ --name openclaw \ --restart=always \ -p 8080:8080 \ -v /opt/openclaw/data:/data \ -v /opt/openclaw/openclaw.yml:/app/openclaw.yml \ ghcr.io/openclaw/openclaw:latest逐项解释一下：
- -d：后台运行容器。
- --name openclaw：给容器起名，后续操作方便。
- --restart=always：容器崩溃或服务器重启后自动拉起，这个参数一定要加。
- -p 8080:8080：把宿主机的 8080 端口映射到容器的 8080 端口。
- -v /opt/openclaw/data:/data：挂载数据目录，模型缓存、会话记录等持久化数据保存在宿主机。
- -v /opt/openclaw/openclaw.yml:/app/openclaw.yml：把配置文件挂载进容器。
启动后，用下面的命令看日志：
docker logs -f openclaw看到启动成功的日志后，验证一下健康检查接口：
curl http://localhost:8080/health如果返回正常状态，说明服务本身已经跑起来了。此时先别急着配飞书，我们还要解决 HTTPS 的问题。
2.5 配置域名与 HTTPS 转发
飞书开放平台要求回调地址必须是公网可达的 HTTPS 地址，这是硬性要求。如果直接用 http:// 或者 IP 地址，飞书后台保存时会直接报错。
这里有一个很省心的方案：用 Caddy 做自动 HTTPS。Caddy 能自动申请和管理证书，配置非常简短。在服务器上装好 Caddy 后，写一个 Caddyfile：
your-domain.com { reverse_proxy 127.0.0.1:8080 }然后把 your-domain.com 替换成你自己的域名，启动 Caddy。它会自动完成证书申请、续期，并把公网 443 端口的请求转发到本机的 8080 端口。这一步做完后，从公网访问 https://your-domain.com/feishu/callback 就能触达 OpenClaw 的回调接口。
如果你更习惯其他 HTTP 服务组件，也可以自行配置证书并做端口转发，原理一样。关键是确保 443 端口公网可达、证书有效。
到这里，OpenClaw 服务本身已经通了。但它还收不到飞书消息，因为飞书那边还没配置“可以把事件推到哪”。下一节去开放平台操作。
3. 飞书开放平台侧配置：创建应用、开通权限、配置事件订阅
3.1 创建企业自建应用
登录飞书开放平台后台，在“开发者后台”里选择“创建企业自建应用”。这里要说明一下：虽然名字叫“企业自建”，但个人开发者也能用，这里的“企业”指的是你自己的组织，应用不会上架到公开市场。
应用名称可以随便取，比如“我的助手”，上传一个头像，点击创建即可。创建完成后，进入应用详情页。
第一件事是打开“机器人”能力。在应用能力列表里找到机器人，点击开通。这一步决定了这个应用能不能以机器人的身份出现在会话里，不开启的话后面所有消息收发都无从谈起。
3.2 保存 App ID 和 App Secret
在应用详情页的“凭证与基础信息”里，能看到 App ID 和 App Secret 两项。App ID 是应用的公开标识，App Secret 是应用调用飞书 API 的凭证，相当于密码。
这里有一个非常容易踩的坑：App Secret 只在创建时完整展示一次，之后不会再明文显示。如果当时没保存，后面只能重置，重置后旧配置里的值会立即失效。所以拿到 App Secret 的第一时间，应该先存到一个安全的本地文件里，再继续后续操作。
3.3 配置机器人权限
接下来在“权限管理”里给应用添加机器人相关权限。飞书对机器人消息能力有细分的权限控制，至少需要开通以下几类：
- 读取用户发给机器人的单聊消息。
- 以机器人身份发送单聊消息。
- 读取群聊中 @ 机器人的消息。
- 在群聊中以机器人身份发送消息。
不同版本的飞书开放平台对这个权限的命名会有微调，搜索“消息”关键词，把涉及“读取”“接收”“发送”的权限勾上即可。记忆方法：读取类权限解决“收消息”的问题，发送类权限解决“回消息”的问题。如果权限少配了一个，典型表现是消息能收到但回复发不出去，或者反过来。
3.4 配置事件订阅
这是整个对接流程里最容易出错的地方。在应用详情页找到“事件与回调”，添加事件订阅。
订阅方式选择“事件回调”。请求地址填写之前配置好的 HTTPS 回调地址，格式是：
https://your-domain.com/feishu/callback注意路径要和 OpenClaw 配置文件里的 callback_path 保持一致。写完地址后，添加事件，选择“接收消息”，对应的事件类型通常是 im.message.receive_v1。
接下来设置加密策略。飞书支持明文和加密两种回调方式，我建议开启加密。开启后会生成一个 Encrypt Key，同时需要设置一个 Verification Token。这两个值后面要填到 OpenClaw 配置文件里，现在先记下来。
点击保存时，飞书会立刻发送一条验证请求到你的回调地址，OpenClaw 如果能正确响应，验证自动通过。如果验证失败，先去看容器日志，别急着反复点保存——频繁触发验证失败对排查没有帮助。
3.5 发布应用版本并设置可用范围
很多人在这个环节掉坑：配置全部搞定，但打开飞书搜不到机器人，或者发消息没反应。原因通常是应用没有发布。
自建应用在后台配置完成后，需要在“版本管理与发布”里创建一个版本，填版本号和更新说明，设置可用范围。可用范围可以只选你自己，也可以选整个组织，根据自己的使用场景决定。提交发布后，等待审核通过。审核通过后，机器人才能真正在飞书里被成员使用。
如果是在开发调试阶段，飞书后台通常也提供测试企业或测试成员机制，可以加速验证流程，但正式使用必须以发布后的版本为准。
3.6 先验证回调地址是否可达
在飞书后台填写回调地址之前，建议先用 curl 验证一下这个地址的通达性：
curl -I https://your-domain.com/feishu/callback如果返回 HTTP 状态码（哪怕是 404、405），都说明域名解析和 HTTPS 转发已经通了。如果提示超时、连接失败，那问题在服务器端或者域名解析上，先解决网络联通，再去飞书后台配置。
需要注意，飞书验证请求是 POST 方法，curl -I 用的是 HEAD 方法，不能完全模拟验证逻辑，但能确认网络链路是否正常。完整的验证过程要等飞书后台点保存时才能看到。
4. 参数回填：把飞书配置写进 OpenClaw
4.1 一组要回填的参数对照表
现在飞书后台的配置已经完成，需要把关键参数填回 OpenClaw 的配置文件。对照关系如下：
| OpenClaw 配置字段 | 飞书开放平台位置 | 说明 |
|---|---|---|
| app_id | 凭证与基础信息 -> App ID | 应用的公开标识 |
| app_secret | 凭证与基础信息 -> App Secret | 应用调用 API 的凭证，务必保密 |
| encrypt_key | 事件与回调 -> 加密策略 -> Encrypt Key | 开启加密后生成，用于解密回调内容 |
| verification_token | 事件与回调 -> Verification Token | 校验回调请求来源 |
这四个参数缺一不可。如果某个字段填错，不会提示“配置错误”，而是会在运行时出现签名校验失败或者消息收发异常。所以在回填之前，建议先核对一遍，尤其是 App Secret 和 Encrypt Key 这种长字符串，很容易多复制一个空格。
4.2 修改配置并重启服务
编辑之前创建的 openclaw.yml 文件，把上表中的参数填进去：
channels: feishu: app_id: "cli_xxxxx" app_secret: "YourAppSecretHere" encrypt_key: "YourEncryptKeyHere" verification_token: "YourVerificationTokenHere" callback_path: "/feishu/callback"修改完成后保存文件，重启容器让配置生效：
docker restart openclaw注意，配置文件挂载进容器后，修改宿主机上的文件，必须重启容器才会被重新读取。这一步漏掉，前面所有配置都白做。
重启后看日志确认没有报错。如果配置正确，OpenClaw 会成功初始化飞书渠道，日志里会出现类似 channel ready 或者 feishu initialized 的信息。
4.3 端到端验证：私聊和群聊
现在可以打开飞书，做一次完整的端到端验证。
第一步，在飞书搜索你的应用名称，找到机器人，进入单聊会话。发送一条简单的测试消息，比如“ping”或者“help”。
第二步，看 OpenClaw 容器日志。如果收到了消息，日志里会出现 receive event 或者 message received 之类的记录；如果回复成功，会出现 send message ok。如果日志里什么都没有，说明事件没有到达服务端，问题出在飞书事件订阅或网络链路。
第三步，测试群聊场景。把机器人拉进一个群，输入 @机器人 加消息内容。群聊和单聊的事件订阅基本一致，但需要注意确认权限管理里已经开通群消息读取权限，否则 @ 机器人时消息不会推过来。
4.4 关注日志中的几个关键信息
排错时不要凭感觉去猜，直接看日志最靠谱。OpenClaw 日志里通常会出现几个关键状态：
- receive event：飞书事件已到达，说明回调链路正常。
- message received：OpenClaw 已解析用户消息，说明消息内容正常。
- send message ok：OpenClaw 已调用飞书 API 回复成功，说明凭证和权限正常。
- error / failed：具体错误信息会出现在日志里，复制出来检索，命中率很高。
如果日志显示 send message failed，后面通常会跟错误码或错误描述，比如权限不足、凭证错误、消息内容过长等，按提示处理即可。
5. 高频踩坑实录与排查技巧
5.1 回调验证失败，到底卡在哪一环节
飞书后台保存回调地址时提示“验证不通过”，这是遇到最多的问题。按下面的顺序排查，基本能覆盖 90% 的情况：
| 可能原因 | 典型现象 | 处理方式 |
|---|---|---|
| 域名解析错误 | curl 域名超时或无法连接 | 检查 DNS 的 A 记录是否指向服务器公网 IP |
| 443 端口未开放 | curl 提示连接被拒 | 检查服务器防火墙和云厂商安全组，放行 443 |
| HTTPS 证书无效 | curl 提示证书错误 | 确保证书有效，Caddy 自动申请失败时查看 Caddy 日志 |
| 回调路径不一致 | 飞书地址和 OpenClaw 配置里的 callback_path 不一致 | 统一路径，比如都用 /feishu/callback |
| Encrypt Key 不一致 | 飞书后台填写的加密密钥和 OpenClaw 配置不一致 | 复制时注意首尾空格 |
| Verification Token 不匹配 | 签名校验失败日志 | 核对两个位置的 token 是否一致 |
我的经验是：先 curl 通道路由，再看 OpenClaw 日志，最后核对参数。顺序不要反，因为很多时候问题在更基础的地方，直接去改参数只会越搞越乱。
5.2 消息能收到但机器人不回复
这类问题比回调验证更难发现，因为链路前半段都是通的。现象是飞书里发消息没有回应，日志里能看到消息收到，但没有发送成功的记录。
优先检查三件事：App Secret 是否正确、发送消息权限是否开通、消息频率是否超限。
App Secret 错误时，OpenClaw 调用飞书 API 会直接报鉴权失败。权限不足时，错误信息里会包含权限相关的描述。频率超限则通常出现在连续大量消息的场景，飞书对机器人发送频率有平台级限制，此时可以适当放慢调用节奏。
还有一个常见情况：如果 OpenClaw 里配置了工具调用或大模型流程，处理时间可能超过飞书的回调超时限制。飞书事件回调有响应超时时间，如果 OpenClaw 长时间不返回，飞书会认为投递失败并重试。解决方案是让 OpenClaw 在收到消息后立即返回一个类似“处理中”的确认，异步再发最终结果。
5.3 容器重启后一切配置还原
出现这个问题的原因很明确：配置文件没有挂载到宿主机，或者数据目录没有持久化。
如果你是用 docker run 启动的，检查命令里有没有 -v /opt/openclaw/openclaw.yml:/app/openclaw.yml。如果少了这个挂载，配置文件就写在容器内层，容器删除后配置全部丢失。
如果你用 docker-compose，确保 volumes 段落里写了配置文件的挂载，并且修改宿主机文件后执行了 docker compose restart。
5.4 Docker 日志与配置排查的几个小工具
在排错过程中，有几个命令非常高频：
docker logs -f openclaw # 实时查看日志 docker inspect openclaw | grep Mounts # 查看挂载是否生效 docker restart openclaw # 重启容器如果怀疑配置文件格式有问题，可以在宿主机上用简单的 YAML 校验工具检查一下，避免因为缩进错误导致服务启动失败。很多配置问题其实在启动阶段就会暴露，启动后一切正常才需要往运行时的方向查。
5.5 其他容易被忽略的细节
以下这些坑不是每次都遇到，但遇到一次就能折腾半小时：
- 时区问题：服务器默认 UTC 时区，OpenClaw 日志时间和飞书消息时间差 8 小时。启动容器时加一个环境变量 -e TZ=Asia/Shanghai 即可。
- 端口占用：8080 端口如果被其他服务占用，容器会启动失败。换一个宿主机端口映射即可，但记得同步更新反向代理里的转发目标端口。
- 日志增长过快：OpenClaw 在调试模式下日志量很大，建议调整日志级别为 info，并为 Docker 配置日志轮转。
- 镜像版本更新：重新拉取镜像后，数据目录一般不受影响，但如果版本跨越较大，配置字段可能变化，查看项目 changelog 再升级。
- 自签名证书不可用：不要为了省事用自签名证书，飞书不认，必须使用受信任的证书机构签发的证书，Caddy 自动申请的正好满足。
5.6 一个实用的调试技巧：先模拟回调再点保存
在飞书后台点“保存”之前，如果想提前确认 OpenClaw 的回调接口逻辑是否正常，可以从服务器本地模拟一次飞书验证请求。比如用 Python 写一个简单的脚本，向回调地址发送带 challenge 字段的 POST 请求：
import requests url = "https://your-domain.com/feishu/callback" payload = { "challenge": "test_challenge", "token": "your_verification_token", "type": "url_verification" } resp = requests.post(url, json=payload, timeout=10) print(resp.status_code) print(resp.text)如果配置了加密，实际的验证请求体是加密的，这个脚本不能完整模拟，但至少能验证回调地址的连通性和服务是否在监听。确认通畅之后，再回飞书后台保存，成功的概率会高很多。
我个人在实际部署中的体会是，OpenClaw 和飞书对接这件事，难点不在写配置，而在于把“事件回调”这件事的机制理解清楚。一旦想明白“飞书把消息推给谁、谁来回复、回复时用什么凭证”这三个问题，整个部署流程就只剩复制粘贴了。
最后分享一个小技巧：部署时先把 OpenClaw 跑在本地开发机，用内网穿透类工具映射到公网临时测试，飞书回调可以反复触发，调试效率很高。确认整个流程没问题之后，再迁移到正式服务器，能省下大量时间。希望这篇防踩坑教程能让你少走我走过的弯路。
