AI Claw Guide

Appearance

04D. 飞书云 Claw 故障排查速查表 ​

适用对象：已经部署好飞书云 Claw，但在使用中遇到“飞书不回、定时任务没触发、Skill 不工作”等问题的用户 | 文档版本：V1.0 更新日期：2026 年 3 月 23 日 | 文档定位：面向飞书云 Claw 场景的快速排障，不讲泛泛原理，优先给最短排查路径

先看结论 ​

飞书云 Claw 的问题，90% 都能归到下面 5 类：

  1. 网关没在运行
  2. 飞书渠道链路断了
  3. 模型失效了
  4. Skill 没装好或没配好
  5. 定时任务依赖链路不完整

排查顺序不要乱，永远先看：

  1. 飞书还能不能回复普通消息
  2. openclaw gateway status
  3. 最近日志
  4. 具体是哪类能力失效

一、先跑这 4 条命令 ​

不管你遇到什么问题，先执行：

bash
openclaw --version
openclaw doctor
openclaw gateway status
openclaw gateway logs --lines 100

如果这 4 条里已经有明显报错，先别往下猜。

二、按现象最快定位 ​

现象先看哪里
飞书里完全不回复三、问题 1
飞书能回，但回答一直报错或空白三、问题 2
只有搜索类问题不工作三、问题 3
只有浏览器/网页能力不工作三、问题 4
只有定时任务不触发三、问题 5
定时任务创建成功，但结果不对三、问题 6
以前能用，现在突然不行三、问题 7
升级或改配置后出问题三、问题 8

三、常见问题速查 ​

问题 1：飞书里完全不回复 ​

先检查：

bash
openclaw gateway status

如果网关没在运行：

bash
openclaw gateway restart

如果网关在运行但飞书完全无回应，再看：

bash
openclaw gateway logs --lines 100

重点看有没有：

  • 飞书渠道连接失败
  • Token / Secret 错误
  • 模型请求异常

如果是突然从“能用”变成“完全不回”，优先怀疑：

  • 网关挂了
  • 飞书渠道配置失效
  • 模型侧请求失败

问题 2：飞书能回，但一直转圈、空白、报错 ​

这通常不是飞书的问题，而是模型问题。

重点检查：

  • 默认模型有没有改坏
  • API Key 是否过期
  • 账户是否欠费或没余额

建议先发一个最简单的问题：

text
你好，请只回复“收到”。

如果连这种都不稳定，先回到模型链路排查。

问题 3：普通对话正常，但“最新信息”总是旧的 ​

优先检查 brave-search。

常见原因：

  1. brave-search 没装
  2. 装了但没配 API Key
  3. 配了 Key 但没重启网关

检查思路：

bash
openclaw gateway logs --lines 100

然后确认：

bash
openclaw config get 'skills.brave-search.config.apiKey'

如果你不确定配置项是否存在，也可以直接重新设置一遍再重启。

问题 4：浏览器类能力不工作 ​

比如你在飞书里说：

  • 打开某网页
  • 看某网站公告
  • 截图某页面

但它做不到。

优先检查：

  1. browser 是否已安装
  2. 任务是否真的需要浏览器能力
  3. 日志里有没有权限或环境报错

很多时候不是 Skill 坏了，而是你的描述太泛。

差写法：

text
帮我看看这个网站

好写法：

text
帮我打开这个网址，检查首页有没有最新公告，并总结最重要的 3 条信息。

问题 5：定时任务根本不触发 ​

这是飞书云 Claw 里最常见的一类问题。

先检查：

  1. scheduler 是否已安装
  2. 网关是否持续在运行
  3. 你是不是先做过一次简单测试任务

最小验证任务：

text
请帮我创建一个测试定时任务：10 分钟后提醒我“scheduler 已经生效”。

如果这个都不触发，就不要先查复杂工作流，先把最小链路跑通。

问题 6：定时任务能触发，但结果不对 ​

比如：

  • 时间到了，但输出内容空白
  • 只发了提醒，没生成简报
  • 明明要查天气/搜索/网页，但没执行

这类问题通常是“组合任务依赖不完整”。

常见原因：

  • 只装了 scheduler，但没装 weather / browser / brave-search
  • 任务依赖的 ~/.openclaw/data/*.md 文件不存在
  • 任务描述不够明确

建议拆开验证：

  1. 先测定时提醒
  2. 再单独测对应 Skill
  3. 最后再组合

问题 7：以前能用，现在突然不行 ​

先不要改一堆配置。优先问自己：

  • 最近是不是改过默认模型
  • 最近是不是新增或更新过 Skill
  • 最近是不是改过网关配置

然后看日志：

bash
openclaw gateway logs --lines 100

很多“突然不行”，本质上就是最近变更引入的问题。

问题 8：升级或改配置后出问题 ​

先回忆你最近做了什么：

  • 更新了所有 Skills
  • 改了默认模型
  • 改了 openclaw.json
  • 调整了某个 Skill 的配置项

这时最稳的做法不是继续猜，而是：

  1. 看日志
  2. 检查最近改动点
  3. 必要时回滚到之前的备份

所以前面一直强调要做备份，不是形式主义。

四、按能力拆分的排查顺序 ​

4.1 飞书消息链路问题 ​

排查顺序：

  1. 飞书里还能不能收到普通回复
  2. 网关状态是否正常
  3. 日志里有没有飞书连接错误

4.2 模型问题 ​

排查顺序：

  1. 最简单消息能不能回复
  2. API Key 是否有效
  3. 默认模型是否改动过

4.3 Skill 问题 ​

排查顺序：

  1. Skill 是否已安装
  2. 是否还缺 Key 或授权
  3. 是否重启过网关
  4. 你的话术是否足够明确

4.4 定时任务问题 ​

排查顺序：

  1. 先测一次性任务
  2. 再测周期任务
  3. 再测组合任务

五、飞书云 Claw 专属的最小排障动作 ​

如果你只想做一轮最短排查，按这个顺序：

  1. 在飞书里发一句“你好，请只回复收到”
  2. 执行 openclaw gateway status
  3. 执行 openclaw gateway logs --lines 100
  4. 如果是搜索问题，重新检查 brave-search
  5. 如果是定时问题，先做 10 分钟测试提醒

这比一上来重装、重配、重启一堆东西更有效。

六、什么时候该看更完整的排障文档 ​

如果你碰到的是这些情况，就不要只看这张速查表了：

  • 网关启动失败
  • 端口冲突
  • JSON 配置报错
  • 模型接口 401 / 403
  • 系统级权限问题

直接看完整排障文档：

七、建议你长期保留的 3 个习惯 ​

  1. 每次只改一类配置
  2. 每次改完都做最小验证
  3. 定期备份 openclaw.json、USER.md 和 data/

这 3 条会大幅减少你以后排障的成本。

下一步看哪篇 ​

你的目标建议阅读
想看飞书云 Claw 后续配置主线04A-飞书云 Claw 安装后使用与配置指南.md
想直接复制定时任务模板04B-飞书云 Claw 定时任务模板大全.md
想看常用 Skills 的话术场景04C-飞书云 Claw 常用 Skills 场景手册.md
想看更完整的 OpenClaw 排障文档10-OpenClaw-排障与维护-通用说明.md