前言

搭建飞书 AI 机器人时，是不是遇到过这些问题：

• 机器人没反应？
• 返回错误信息看不懂？
• 发送消息后一直转圈？

别慌，90% 的问题都能自己解决。今天这篇文章，教你从零开始调试飞书机器人，10 分钟定位问题根源。

---

环境准备

在开始调试前，确保你已经：

• ✅ 安装 OpenClaw（本地或服务器）
• ✅ 创建飞书应用（获取 App ID、App Secret）
• ✅ 配置飞书机器人权限

---

一、常见错误类型

1. 权限错误

症状：

Error: permission denied
或
403 Forbidden

原因：

• 飞书应用权限未开启
• 用户授权过期
• 权限范围不足

2. 消息发送失败

症状：

Error: send_message failed
或
message_id not found

原因：

• 接收者 ID 格式错误
• 群聊/私聊配置错误
• API 地址配置错误

3. 超时错误

症状：

Error: timeout
或
Connection refused

原因：

• 网络不通
• 服务未启动
• 防火墙拦截

---

二、调试工具使用

1. 查看日志

OpenClaw 默认日志位置：

# 本地安装
~/.openclaw/logs/openclaw.log

# Docker 安装
docker logs <容器名> -f

实时监控：

tail -f ~/.openclaw/logs/openclaw.log

2. 测试 API 连通性

# 测试飞书 API 连接
curl -X GET https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal

# 检查 OpenClaw 服务状态
openclaw status

3. 使用调试模式

启动时启用详细日志：

openclaw gateway start --verbose

---

三、排查步骤（分场景）

场景 1：机器人完全无响应

排查清单：

1. OpenClaw 服务是否启动？
   → 运行 openclaw status

2. 飞书应用是否正确配置？
   → 检查 App ID、App Secret、Encrypt Key

3. 网络是否连通？
   → ping open.feishu.cn

4. 事件回调地址是否正确？
   → 飞书后台 → 事件订阅 → 请求 URL

解决方案：

# 1. 重启服务
openclaw gateway restart

# 2. 验证配置
openclaw status

# 3. 检查防火墙（云服务器）
sudo ufw status

---

场景 2：收到消息但不回复

排查清单：

1. 日志中是否收到消息事件？
   → 搜索 "message" 关键词

2. 消息格式是否正确？
   → 检查 message_id、chat_id 格式

3. 回复逻辑是否正常？
   → 查看 agent 配置

解决方案：

# 查看最近的日志
grep "message" ~/.openclaw/logs/openclaw.log | tail -20

# 手动测试消息发送
# 使用飞书 Postman 或 curl 测试 API

---

场景 3：返回错误信息

常见错误对照表：

错误信息	原因	解决方案
tenant_token expired	租户 Token 过期	重启服务自动刷新
app not exist	App ID 错误	检查配置文件
permission denied	权限不足	飞书后台开启权限
user not found	用户 ID 错误	确认 open_id 格式
chat not found	会话 ID 错误	确认 chat_id 格式

---

四、实用技巧

1. 使用测试命令

OpenClaw 内置测试工具：

# 测试飞书连接
openclaw test feishu

# 测试消息发送
openclaw test message --chat_id "oc_xxx" --text "测试"

2. 分步验证

遇到复杂问题时，分步验证：

第一步：验证 Token 获取是否成功
第二步：验证消息接收是否正常
第三步：验证消息回复逻辑
第四步：验证外部 API 调用

3. 简化复现

最小化问题场景：

• 先用简单的 "hello" 测试
• 再测试功能复杂的场景
• 最后测试完整业务流程

4. 备份配置

修改配置前先备份：

cp ~/.openclaw/config.yaml ~/.openclaw/config.yaml.bak

---

五、获取帮助

1. 查看文档

• OpenClaw 官方文档：https://docs.openclaw.ai
• 飞书开放平台：https://open.feishu.cn

2. 社区支持

• Discord 社区：https://discord.com/invite/clawd
• GitHub Issues：https://github.com/openclaw/openclaw/issues

3. 诊断工具

当自己无法解决时，运行诊断命令：

openclaw doctor

会生成详细报告，包括：

• 配置检查
• 网络测试
• 权限验证
• 服务状态

---

总结

调试飞书机器人的核心思路：

1. 先看日志 - 90% 的信息都在日志里
2. 分步排查 - 从简单到复杂，逐层验证
3. 善用工具 - openclaw status、doctor、test 命令
4. 保存备份 - 修改配置前先备份

记住：

• 不要一上来就改配置
• 先理解错误信息的含义
• 记录每次排查的结果，方便回溯

---

关注我：

• 网站：觅合可及

持续分享 OpenClaw、Coze工作流、飞书机器人 实战教程。