自动化故障排查

本指南汇总了 OpenClaw 各自动化模块（Cron、Hooks、Webhooks、Polls）的常见故障及排查步骤。遇到自动化任务异常时，请按照以下分类逐步排查。

通用诊断命令

在深入排查之前，先运行以下命令获取全局状态：

# 查看 Gateway 运行状态
openclaw status

# 查看自动化模块总览
openclaw automation status

# 查看最近的错误日志
openclaw logs --level error --limit 50

# 导出诊断报告
openclaw diagnose --output ~/openclaw-diag.json

Cron 任务不触发

症状

定时任务已配置但到达执行时间时没有运行。

排查步骤

1. 检查任务是否启用

openclaw cron list

确认目标任务的 STATUS 列为 enabled。如果显示 disabled，重新启用：

openclaw cron enable --id <job_id>

2. 检查时区设置

时区是最常见的问题

超过 50% 的 "Cron 不触发" 问题是时区配置错误导致的。

# 查看 Gateway 系统时区
openclaw config get timezone

# 查看任务配置的时区
openclaw cron info --id <job_id>

确保 timezone 字段与你期望的一致。推荐显式设置：

openclaw cron edit --id <job_id> --timezone "Asia/Shanghai"

3. 验证 Cron 表达式

# 预览未来 5 次执行时间
openclaw cron preview --id <job_id> --count 5

如果输出的时间不符合预期，说明 Cron Expression（Cron 表达式）有误。

4. 检查 Gateway 是否在运行

openclaw gateway status

Cron 由 Gateway 管理，Gateway 离线时所有 Cron 任务暂停。

5. 查看运行日志

openclaw cron runs --id <job_id> --limit 10

检查是否有失败记录及错误原因。

Hooks 不触发

症状

事件已发生但 Hook 处理函数没有被调用。

排查步骤

1. 确认 Hook 已被发现

openclaw hooks list

如果目标 Hook 不在列表中，检查：

• Hook 目录结构是否正确（需包含 HOOK.md 和 handler.ts）
• 放置路径是否正确（Workspace: /hooks/，Managed: ~/.openclaw/hooks/）

2. 检查事件名称是否匹配

openclaw hooks info <hook-name>

确认 HOOK.md 中声明的 events 与实际触发的事件名完全匹配。

常见拼写错误

• message:recieved ❌ → message:received ✅
• command:new_command ❌ → command:new ✅
• agent:init ❌ → agent:bootstrap ✅

3. 检查 handler.ts 语法

# 检查是否有 TypeScript 编译错误
openclaw hooks validate <hook-name>

4. 查看 Hook 执行日志

openclaw logs --source hooks --limit 20

5. 检查同名覆盖

高优先级的 Hook 会覆盖低优先级同名 Hook。确认没有 Workspace Hook 意外覆盖 Managed Hook。

Webhooks 返回错误

症状

外部系统调用 Webhook 端点返回 4xx 或 5xx 错误。

排查步骤

401 - 认证失败

# 验证 Token 是否正确
openclaw config get webhooks.token

# 测试请求
curl -v -X POST https://your-gateway.com/hooks/wake \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"text": "test"}'

确认请求中的 Token 与配置一致。注意：Token 前后不要有多余空格。

400 - 请求格式错误

检查 Content-Type 是否为 application/json，请求体是否为合法 JSON：

# 使用 jq 验证 JSON 格式
echo '{"text": "test"}' | jq .

429 - 速率限制

# 查看当前速率限制配置
openclaw config get webhooks.rateLimit

如果是合法流量，适当调高限制：

{
  "webhooks": {
    "rateLimit": {
      "maxRequests": 200,
      "windowMs": 60000
    }
  }
}

500 - 服务器内部错误

# 查看 Gateway 错误日志
openclaw logs --source gateway --level error --limit 10

Polls 不运行

症状

轮询任务已配置但没有周期性检查数据源。

排查步骤

1. 确认 Polls 模块启用

openclaw config get polls.enabled

2. 检查具体 Poll 配置

openclaw polls list

确认目标 Poll 状态为 enabled，间隔配置合理。

3. 测试数据源连通性

# 手动执行一次轮询
openclaw polls run --name <poll-name>

如果报网络错误，检查：

• 数据源地址是否可访问
• 防火墙/代理配置是否正确
• 认证凭据是否有效

4. 检查状态文件

# 查看 Poll 状态
openclaw polls status --name <poll-name>

如果状态文件损坏，可重置：

openclaw polls reset --name <poll-name>

日志分析技巧

按模块过滤日志

# Cron 日志
openclaw logs --source cron --limit 30

# Hooks 日志
openclaw logs --source hooks --limit 30

# Webhooks 日志
openclaw logs --source webhooks --limit 30

# Polls 日志
openclaw logs --source polls --limit 30

按时间范围查看

# 查看过去 1 小时的日志
openclaw logs --since "1h" --level error

# 查看特定时间段
openclaw logs --from "2026-03-05T08:00:00" --to "2026-03-05T09:00:00"

开启调试模式

# 临时开启 Debug 级别日志
openclaw config set logLevel debug

# 排查完成后恢复
openclaw config set logLevel info

调试模式性能影响

Debug 级别日志会显著增大日志文件体积并略微影响性能，排查完成后请务必恢复为 info 级别。

常见问题速查表

问题	可能原因	快速解决
所有自动化都不工作	Gateway 未运行	openclaw gateway start
Cron 时间偏移	时区未设置	添加 timezone 字段
Hook 无输出	handler 内部异常	添加 try/catch 并查看日志
Webhook 401	Token 不匹配	核对环境变量和请求头
Poll 重复处理	状态文件丢失	检查存储路径权限
OAuth Token 失效	未启用自动刷新	启用 autoRefresh

🇨🇳 中国用户须知

• 网络连通性问题在国内尤为常见，外部 API 超时建议先排查网络/代理配置
• 国内云服务器的系统时区可能不是 Asia/Shanghai，需手动确认
• 日志文件较大时，可使用 openclaw logs --export 导出后用本地工具分析