调试与错误处理指南

本文档提供飞书插件的调试方法和常见错误解决方案。

调试模式

开启详细日志

在配置中启用调试模式：

{
  "channels": {
    "feishu": {
      "debug": true,
      "logLevel": "verbose"
    }
  }
}

使用诊断命令

openclaw feishu-diagnose

该命令会检查：

• OAuth 授权状态
• API 连接性
• 应用权限配置

常见错误与解决方案

1. 授权相关错误

错误：token_expired

错误信息：

{
  "code": 99991668,
  "msg": "access token is expired"
}

解决方案：

• 用户身份授权的 token 会在约 2 小时后过期
• 插件会自动使用 refresh_token 刷新
• 如持续失败，发送 撤销授权 重新授权

错误：unauthorized

错误信息：

{
  "code": 99991663,
  "msg": "no permission to access this resource"
}

解决方案：

• 检查用户是否有该资源的访问权限
• 用户身份授权权限受限于用户本身的飞书权限
• 确认应用已开通相应 API 权限

2. 多维表格错误

错误：1254064 - 日期格式错误

错误原因：日期字段值格式不正确

正确格式：毫秒时间戳

{
  "fields": {
    "签约日期": 1674206443000
  }
}

错误示例：

{
  "fields": {
    "签约日期": "2024-01-01"
  }
}

错误：1254068 - 超链接格式错误

正确格式：

{
  "fields": {
    "官网": {"link": "https://example.com", "text": "访问网站"}
  }
}

错误：1254015 - 字段类型不匹配

原因：插入的值类型与字段定义不匹配

解决：

1. 先查询字段类型
2. 按字段类型构造值

{
  "action": "list",
  "app_token": "S404bxxxxx",
  "table_id": "tblxxxxx"
}

错误：1254104 - 批量超限

原因：单次批量操作超过 500 条限制

解决：分批处理

const BATCH_SIZE = 500;
for (let i = 0; i < records.length; i += BATCH_SIZE) {
  const batch = records.slice(i, i + BATCH_SIZE);
  await createRecords(batch);
}

错误：1254291 - 并发冲突

原因：同一数据表并发写入

解决：添加延迟，串行调用

await createRecord(data1);
await new Promise(r => setTimeout(r, 500)); // 延迟 0.5 秒
await createRecord(data2);

3. 文档错误

错误：21311 - 文档不存在

原因：文档已被删除或没有访问权限

错误：1254048 - 文件已存在

原因：目标位置已有同名文件

4. 日历错误

错误：1254043 - 日程时间冲突

原因：该时间段已有其他日程

5. 任务错误

错误：1254020 - 任务不存在

原因：任务 GUID 无效或任务已被删除

错误码速查表

错误码	说明	解决方案
99991663	无权限	检查用户权限
99991668	Token 过期	重新授权
1254015	字段类型不匹配	检查字段类型
1254043	时间冲突	调整时间
1254048	文件已存在	更换名称
1254064	日期格式错误	使用毫秒时间戳
1254066	人员格式错误	使用 {id} 对象
1254068	超链接格式错误	使用
1254104	批量超限	分批处理
1254291	并发冲突	串行调用

调试技巧

1. 使用 feishu-diagnose

# 诊断所有问题
openclaw feishu-diagnose

# 检查特定问题
openclaw feishu-diagnose --auth

2. 检查应用权限

在飞书开放平台后台检查：

1. 进入应用详情
2. 点击"权限管理"
3. 确认已开通所需权限

3. 使用 API 测试工具

在飞书开放平台使用 API 测试：

1. 访问 https://open.feishu.cn
2. 进入"API 测试"
3. 选择对应 API 测试

4. 查看飞书错误文档

访问官方错误码文档：

• https://open.feishu.cn/document/server-docs/getting-started-overview