前言

用 OpenClaw 搭建飞书机器人时，你是否遇到过这些问题？

• 配置完成后收不到消息
• 发送消息提示权限不足
• Webhook 连接一直超时
• 群聊机器人莫名其妙离线

这些问题我全部踩过坑。今天总结最常遇到的 5 种错误，每个问题都提供详细的排查步骤、完整代码示例和实战解决方案，帮你快速定位问题。

---

错误一：API 权限不足

现象

{
  "error": "Request failed with status code 400",
  "message": "permission error: contact:contact.base:readonly"
}

或者日志显示：

[ERROR] Feishu API call failed: insufficient permissions

原因分析

飞书应用权限采用 最小权限原则，需要显式声明和授权。常见原因：

1. 权限未声明：飞书开放平台未添加对应权限
2. 未发布版本：添加权限后未发布，权限不生效
3. 未完成授权：管理员未完成应用授权流程
4. 权限过期：部分权限有时效性，需要续期

飞书权限体系

权限名称	用途	适用场景
contact:contact.base:readonly	获取用户基本信息	发送@消息、查询用户
im:message	发送和接收消息	机器人核心功能
im:chat	获取群组信息	群聊机器人
im:group	管理群组	添加/移除机器人
drive:drive:readonly	读取云盘文件	处理文件消息

解决方案

步骤 1：检查缺失的权限

根据错误提示，确定需要添加的权限。常见的权限组合：

基础聊天机器人：

contact:contact.base:readonly
im:message
im:chat

群组管理机器人：

contact:contact.base:readonly
im:message
im:chat
im:group

文件处理机器人：

contact:contact.base:readonly
im:message
drive:drive:readonly

步骤 2：配置飞书应用权限

1. 登录 飞书开放平台
2. 进入你的应用 → 权限管理
3. 搜索并添加缺失的权限

示例：添加 contact:contact.base:readonly

1. 在权限管理页面搜索框输入 contact
2. 找到 获取用户基本信息（contact:contact.base:readonly）
3. 点击右侧的 申请权限
4. 勾选所有需要的权限
5. 点击 保存
6. 点击「发布版本」使权限生效

⚠️ 注意：添加权限后必须发布版本，否则权限不会生效！

步骤 3：授权应用权限

管理员需要访问授权链接完成授权：

https://open.feishu.cn/app/{app_id}/auth?q={permission_scopes}&op_from=openapi&token_type=tenant

示例：

https://open.feishu.cn/app/cli_a94e114bf3789bef/auth?q=contact%3Acontact.base%3Areadonly&op_from=openapi&token_type=tenant

操作步骤：

1. 点击授权链接
2. 使用管理员账号登录飞书
3. 查看权限范围，点击 同意授权
4. 授权成功

步骤 4：验证权限

# 测试用户信息获取
openclaw lark user:get

# 如果返回用户信息，说明权限已生效

或使用 curl 测试：

curl -X GET "https://open.feishu.cn/open-apis/contact/v3/users/me" \
  -H "Authorization: Bearer {tenant_access_token}"

返回用户信息表示权限已生效：

{
  "code": 0,
  "msg": "success",
  "data": {
    "user": {
      "user_id": "ou_xxx",
      "name": "张三",
      "en_name": "Zhang San",
      "email": "zhangsan@example.com"
    }
  }
}

---

错误二：User Access Token 过期

现象

{
  "error": "token_expired",
  "message": "User access token has expired"
}

或日志显示：

[ERROR] Token validation failed: token expired

机器人可以启动，但无法以用户身份发送消息或读取文件。

原因分析

飞书 OAuth 2.0 认证体系包含三种 Token：

Token 类型	有效期	用途	刷新机制
App Access Token	2 小时	应用级调用	自动刷新
Tenant Access Token	2 小时	租户级调用	自动刷新
User Access Token	2 小时	用户身份调用	需要重新授权

为什么 User Access Token 需要重新授权？

User Access Token 用于代表用户执行操作（如读取用户文件、发送用户身份消息），出于安全考虑，过期后需要用户重新授权。

解决方案

步骤 1：撤销过期 Token

方法一：使用 OpenClaw 命令

# 撤销当前授权
openclaw lark oauth revoke

方法二：调用飞书 API

curl -X POST "https://open.feishu.cn/open-apis/auth/v3/revoke" \
  -H "Authorization: Bearer {tenant_access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "token_type": "refresh_token"
  }'

成功返回：

{
  "code": 0,
  "msg": "success"
}

步骤 2：重新授权用户权限

撤销后，OpenClaw 会自动触发重新授权流程。

操作步骤：

1. 打开飞书客户端（PC 或手机）
2. 接收来自「飞书开放平台」的授权请求
3. 查看授权范围，点击 同意
4. 等待授权完成

授权完成后，User Access Token 会自动更新。

步骤 3：批量授权（可选）

如果需要一次性授权所有应用开通的用户权限：

# 批量授权所有权限
openclaw lark oauth batch-auth

⚠️ 注意：此操作会一次性授权所有应用开通的用户权限，仅在明确需要时使用。

步骤 4：验证 Token 状态

# 查看当前授权状态
openclaw lark oauth status

输出示例：

{
  "status": "active",
  "token_type": "user_access_token",
  "expires_at": 1711745600,
  "scopes": ["contact:contact.base:readonly", "im:message"]
}

步骤 5：实现自动刷新（进阶）

为了避免频繁手动授权，可以实现 Token 自动刷新机制：

Python 示例：

import time
from datetime import datetime, timedelta

class TokenManager:
    def __init__(self):
        self.token = None
        self.expires_at = None

    async def get_valid_token(self):
        """获取有效的 Token"""
        if self._is_token_valid():
            return self.token
        return await self._refresh_token()

    def _is_token_valid(self):
        """检查 Token 是否有效（提前 5 分钟刷新）"""
        if not self.token or not self.expires_at:
            return False
        return datetime.now() < self.expires_at - timedelta(minutes=5)

    async def _refresh_token(self):
        """刷新 Token"""
        # 调用刷新 API
        response = await self._call_refresh_api()
        self.token = response["access_token"]
        self.expires_at = datetime.now() + timedelta(seconds=response["expires_in"])
        return self.token

    async def _call_refresh_api(self):
        """调用刷新 API"""
        # 实现刷新逻辑
        pass

---

错误三：Webhook 连接超时

现象

• 飞书消息发送后，OpenClaw 没有响应
• 日志显示 Webhook timeout 或 Connection refused
• 机器人偶尔离线，需要重启

原因分析

常见原因：

1. Webhook URL 无法访问
   • 防火墙阻止外部访问
   • 端口未开放
   • SSL 证书问题
2. 网络连接不稳定
   • 服务器网络延迟高
   • DNS 解析失败
   • 跨地域网络问题
3. 服务器资源不足
   • CPU 使用率过高
   • 内存不足
   • 磁盘空间满
4. 飞书服务器连接超时
   • 飞书 API 响应慢
   • Webhook 回调超时

解决方案

步骤 1：检查 Webhook URL 可访问性

测试本地 Webhook：

# 测试 Webhook URL 连通性
curl -I https://your-webhook-url.com/lark/webhook

成功返回：

HTTP/2 200
content-type: application/json
date: Sun, 30 Mar 2026 07:00:00 GMT

失败返回：

curl: (7) Failed to connect to your-webhook-url.com port 443: Connection refused

测试内网 Webhook：

如果使用内网穿透（如 ngrok、frp），需要测试公网地址：

# 测试公网地址
curl -I https://ngrok-url.com/lark/webhook

步骤 2：配置防火墙规则

确保防火墙允许飞书服务器访问你的 Webhook 端口：

Ubuntu/Debian：

# 查看防火墙状态
sudo ufw status

# 开放 443 端口（HTTPS）
sudo ufw allow 443/tcp

# 开放 80 端口（HTTP）
sudo ufw allow 80/tcp

# 开放自定义端口
sudo ufw allow 8080/tcp

# 重载防火墙
sudo ufw reload

CentOS/RHEL：

# 查看防火墙状态
sudo firewall-cmd --state

# 开放 443 端口
sudo firewall-cmd --permanent --add-port=443/tcp

# 重载防火墙
sudo firewall-cmd --reload

云服务器（阿里云/腾讯云）：

需要在云平台控制台配置安全组规则：

1. 登录云服务器控制台
2. 找到你的服务器 → 安全组
3. 添加入站规则：
   • 端口：443
   • 协议：TCP
   • 来源：0.0.0.0/0

步骤 3：检查网络连接

测试与飞书 API 的连接：

# 测试 ping
ping open.feishu.cn

# 测试 DNS 解析
nslookup open.feishu.cn

# 测试端口连通性
telnet open.feishu.cn 443

检查延迟：

# 测试 API 响应时间
time curl -I https://open.feishu.cn

步骤 4：优化服务器资源

查看 CPU 使用率：

# 查看 CPU 使用率
top -bn1 | grep "Cpu(s)"

# 查看 OpenClaw 进程资源占用
top -p $(pgrep openclaw)

查看内存使用情况：

# 查看内存使用
free -h

# 查看进程内存占用
ps aux | grep openclaw

查看磁盘空间：

# 查看磁盘空间
df -h

# 清理日志文件
find ~/.openclaw/logs -name "*.log" -mtime +7 -delete

步骤 5：配置 Webhook 重试机制

在 OpenClaw 配置文件中启用自动重试：

openclaw.yml：

version: "1.0"

plugins:
  lark:
    webhook:
      # 重试配置
      retry_times: 3          # 重试次数
      retry_interval: 5000    # 重试间隔（毫秒）
      timeout: 10000          # 超时时间（毫秒）

      # 连接配置
      max_connections: 100    # 最大连接数
      connection_timeout: 5000  # 连接超时（毫秒）

# 日志配置
logging:
  level: info
  format: json
  file: ~/.openclaw/logs/openclaw.log

步骤 6：实现健康检查

定期检查 Webhook 服务状态：

Python 健康检查脚本：

import requests
import time

def health_check(url, interval=60):
    """健康检查"""
    while True:
        try:
            response = requests.get(url, timeout=5)
            if response.status_code == 200:
                print(f"[OK] Webhook is healthy")
            else:
                print(f"[ERROR] Webhook returned {response.status_code}")
        except Exception as e:
            print(f"[ERROR] Health check failed: {e}")

        time.sleep(interval)

if __name__ == "__main__":
    health_check("https://your-webhook-url.com/health")

---

错误四：消息发送失败

现象

{
  "error": "send_message_failed",
  "message": "invalid receive_id_type"
}

或

{
  "error": "chat_not_found",
  "message": "Chat ID does not exist"
}

原因分析

常见错误：

1. receive_id_type 参数错误
   • 混淆了 open_id 和 chat_id
   • 使用了错误的 ID 格式
2. Chat ID 不存在或已删除
   • 群聊已解散
   • 用户已退出群聊
3. 机器人未加入群聊
   • 机器人未被邀请到群组
   • 机器人被移出群组

飞书 ID 体系

ID 类型	格式前缀	用途	示例
User Open ID	ou_	标识用户	ou_d8a370502ad59b24f0b6757afb18f19b
Chat ID	oc_	标识群聊	oc_a0553eda9014c201e6969b478895c230
App ID	cli_	标识应用	cli_a94e114bf3789bef

解决方案

步骤 1：区分消息类型

单聊（私聊）发送：

# receive_id_type 必须为 open_id
{
  "receive_id": "ou_d8a370502ad59b24f0b6757afb18f19b",
  "receive_id_type": "open_id",
  "msg_type": "text",
  "content": "{\"text\":\"你好\"}"
}

群聊发送：

# receive_id_type 必须为 chat_id
{
  "receive_id": "oc_a0553eda9014c201e6969b478895c230",
  "receive_id_type": "chat_id",
  "msg_type": "text",
  "content": "{\"text\":\"大家好\"}"
}

步骤 2：获取正确的 ID

获取用户 open_id：

# 方法一：通过用户名搜索
openclaw lark user:get --user-id "张三"

# 方法二：通过手机号搜索
openclaw lark user:get --phone "13800138000"

# 方法三：通过邮箱搜索
openclaw lark user:get --email "zhangsan@example.com"

获取群聊 chat_id：

# 搜索群组
openclaw lark chat:search --query "技术交流群"

# 列出所有群组
openclaw lark chat:list

步骤 3：确认机器人已加入群聊

# 查看机器人加入的群组列表
openclaw lark chat:list

# 查看群组成员
openclaw lark chat:members --chat-id "oc_xxx"

如果机器人未加入群组：

1. 打开飞书群聊
2. 点击右上角 设置
3. 选择 群成员 → 添加成员
4. 搜索机器人名称 → 添加
5. 设置机器人为 管理员（如需要发送@消息）

步骤 4：测试消息发送

测试单聊：

openclaw lark message:send \
  --receive-id-type open_id \
  --receive-id "ou_d8a370502ad59b24f0b6757afb18f19b" \
  --message "测试消息"

测试群聊：

openclaw lark message:send \
  --receive-id-type chat_id \
  --receive-id "oc_a0553eda9014c201e6969b478895c230" \
  --message "测试群聊消息"

Python 代码示例：

import requests
import json

def send_message(receive_id, receive_id_type, content):
    """发送消息"""
    url = "https://open.feishu.cn/open-apis/im/v1/messages"

    headers = {
        "Authorization": f"Bearer {get_access_token()}",
        "Content-Type": "application/json"
    }

    payload = {
        "receive_id": receive_id,
        "receive_id_type": receive_id_type,
        "msg_type": "text",
        "content": json.dumps({"text": content})
    }

    response = requests.post(url, json=payload, headers=headers)
    return response.json()

# 发送给用户
result = send_message(
    receive_id="ou_xxx",
    receive_id_type="open_id",
    content="你好"
)

# 发送到群聊
result = send_message(
    receive_id="oc_xxx",
    receive_id_type="chat_id",
    content="大家好"
)

---

错误五：调试困难，日志不清晰

现象

• 出现错误但不知道原因
• 日志信息太少，无法定位问题
• 调试时找不到关键信息

原因分析

1. 日志级别设置过低：使用 info 级别，缺少详细错误信息
2. 未启用调试模式：关键调试信息未输出
3. 错误被忽略：异常被捕获但未记录
4. 日志格式不清晰：缺少时间戳、请求 ID 等关键信息

解决方案

步骤 1：启用调试模式

方法一：环境变量

# 设置日志级别为 DEBUG
export OPENCLAW_LOG_LEVEL=debug

# 启动 OpenClaw
openclaw start

方法二：配置文件

openclaw.yml：

# 日志配置
logging:
  level: debug              # 日志级别：debug/info/warn/error
  format: json             # 日志格式：json/text
  file: ~/.openclaw/logs/openclaw.log
  max_size: 100MB          # 单个日志文件最大大小
  max_files: 10            # 保留日志文件数量

步骤 2：查看实时日志

使用 tail 命令：

# 实时查看日志
tail -f ~/.openclaw/logs/openclaw.log

# 实时查看并过滤错误
tail -f ~/.openclaw/logs/openclaw.log | grep ERROR

# 实时查看并过滤关键词
tail -f ~/.openclaw/logs/openclaw.log | grep "webhook"

使用 journalctl：

# 查看 OpenClaw 服务日志
journalctl -u openclaw -f

# 查看最近 100 行日志
journalctl -u openclaw -n 100

# 查看错误日志
journalctl -u openclaw -p err

步骤 3：使用诊断工具

OpenClaw 提供了深度诊断命令：

# 运行飞书诊断
/feishu_doctor

诊断工具会检查：

1. 账户配置
   • App ID、App Secret 是否正确
   • 权限是否完整
2. API 连通性
   • 飞书 API 是否可访问
   • 网络延迟和稳定性
3. 应用权限
   • 权限是否完整
   • 是否已发布版本
4. 用户授权状态
   • Token 是否有效
   • 授权范围是否正确
5. 网络连接
   • Webhook 是否可访问
   • DNS 解析是否正常

步骤 4：开启详细错误信息

openclaw.yml：

plugins:
  lark:
    # 调试配置
    debug: true            # 启用调试模式
    log_errors: true       # 记录错误
    log_requests: true     # 记录请求

    # Webhook 配置
    webhook:
      log_payloads: true   # 记录消息体
      log_headers: true    # 记录请求头

步骤 5：导出诊断报告

# 生成诊断报告
openclaw lark doctor > diagnostic-report.txt

# 查看报告
cat diagnostic-report.txt

诊断报告示例：

OpenClaw Diagnostic Report
==========================

Timestamp: 2026-03-30 15:00:00

Account Configuration
---------------------
✓ App ID: cli_a94e114bf3789bef
✓ App Secret: ********
✓ Tenant Access Token: Valid

API Connectivity
----------------
✓ Feishu API: reachable (latency: 45ms)
✓ DNS resolution: OK

Application Permissions
----------------------
✓ contact:contact.base:readonly: granted
✓ im:message: granted
✓ im:chat: granted
✗ im:group: not granted (WARNING)

User Authorization
------------------
✓ User Access Token: Valid
✓ Expires at: 2026-03-30 17:00:00

Network Connection
------------------
✓ Webhook URL: accessible
✓ Firewall: port 443 open
✓ SSL certificate: valid

Issues Found
------------
1. Missing permission: im:group
   Recommendation: Add this permission in Feishu Open Platform

Overall Status: ⚠ Needs Attention

---

常见问题 FAQ

Q1: 为什么机器人有时能发送消息，有时不行？

A: 可能原因：

1. User Access Token 过期，需要重新授权
2. 网络不稳定导致请求超时
3. 飞书 API 限流（速率限制）

解决方案：

• 定期检查 Token 有效期
• 实现请求重试机制
• 监控 API 调用频率

Q2: 如何同时支持多个飞书应用？

A: 在 OpenClaw 配置中定义多个应用实例：

plugins:
  lark:
    instances:
      - name: app1
        app_id: "cli_xxx1"
        app_secret: "xxx1"
      - name: app2
        app_id: "cli_xxx2"
        app_secret: "xxx2"

Q3: Webhook 收到消息但没有响应怎么办？

A: 排查步骤：

1. 检查 OpenClaw 日志，确认是否收到消息
2. 检查消息处理逻辑是否有异常
3. 检查飞书 API 调用是否成功
4. 检查 Token 是否有效

Q4: 如何降低 Token 消耗成本？

A: 优化策略：

1. 使用缓存机制，避免重复调用
2. 批量处理相似请求
3. 选择合适的模型（GPT-3.5 vs GPT-4）
4. 优化 Prompt，减少 Token 使用

Q5: 机器人被移出群聊后如何重新加入？

A:

1. 打开群聊设置
2. 选择 群成员 → 添加成员
3. 搜索机器人名称 → 添加

---

总结

OpenClaw 连接飞书的快速排查流程：

1. 检查 API 权限是否完整
   ├─ 权限是否声明
   ├─ 版本是否发布
   └─ 是否完成授权

2. 验证 Token 是否过期
   ├─ 撤销过期 Token
   ├─ 重新授权
   └─ 验证 Token 状态

3. 测试 Webhook 连通性
   ├─ 检查 URL 可访问性
   ├─ 配置防火墙
   └─ 检查网络连接

4. 确认消息参数正确性
   ├─ 区分 open_id 和 chat_id
   ├─ 获取正确的 ID
   └─ 测试消息发送

5. 启用调试日志定位问题
   ├─ 设置日志级别
   ├─ 查看实时日志
   └─ 使用诊断工具

预防措施

1. 定期检查 Token 有效期，提前续期
2. 监控服务器资源，避免资源不足
3. 保留 Webhook URL 访问日志，便于排查问题
4. 及时更新飞书应用权限，避免权限过期

推荐工具

• 日志查看：tail -f、journalctl
• 网络测试：curl、ping、telnet
• 诊断工具：/feishu_doctor
• 监控工具：Prometheus + Grafana

---

参考资料

• 飞书开放平台文档
• OpenClaw 官方文档
• OpenClaw GitHub 仓库
• 飞书 API 错误码

---

如果这篇文章对你有帮助，欢迎点赞收藏，有问题评论区交流！觅合可及提供。