OpenClaw人人养虾：自动化故障排查

本指南汇总了 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级别。

常见问题速查表

《AI提示工程必知必会》为读者提供了丰富的AI提示工程知识与实战技能。《AI提示工程必知必会》主要内容包括各类提示词的应用，如问答式、指令式、状态类、建议式、安全类和感谢类提示词，以及如何通过实战演练掌握提示词的使用技巧；使用提示词进行文本摘要、改写重述、语法纠错、机器翻译等语言处理任务，以及在数据挖掘、程序开发等领域的应用；AI在绘画创作上的应用，百度文心一言和阿里通义大模型这两大智能平台的特性与功能，以及市场调研中提示词的实战应用。通过阅读《AI提示工程必知必会》，读者可掌握如何有效利用AI提示工程提升工作效率，创新工作流程，并在职场中脱颖而出。