title: 定时任务故障排查 - 常见问题与解决方案 tags: [自动化, 定时任务, cron, 故障排除]

定时任务故障排查 - 常见问题与解决方案

汇总 OpenCLAW 定时任务的常见问题及排查方法，帮助你快速定位和解决故障。

故障排查流程

┌─────────────────────────────────────────────────────────────┐
│                    故障排查流程                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. 检查任务状态                                             │
│     └─> openclaw schedule list                             │
│          ↓                                                  │
│  2. 查看执行日志                                             │
│     └─> openclaw schedule logs <name>                      │
│          ↓                                                  │
│  3. 分析错误信息                                             │
│     └─> 定位具体错误类型                                     │
│          ↓                                                  │
│  4. 应用修复方案                                             │
│     └─> 根据错误类型选择解决方案                             │
│          ↓                                                  │
│  5. 验证修复                                                 │
│     └─> 手动执行任务确认修复                                 │
│                                                             │
└─────────────────────────────────────────────────────────────┘

常见错误类型

1. 任务未执行

症状：任务应该执行但没有执行

排查步骤：

# 1. 检查任务状态
openclaw schedule list

# 2. 查看任务详情
openclaw schedule info my-task

# 3. 检查任务是否启用
openclaw schedule status my-task

# 4. 查看调度器日志
openclaw scheduler logs --tail 50

常见原因及解决方案：

原因 解决方案
任务被禁用 启用任务：openclaw schedule enable my-task
Cron 表达式错误 修正 Cron 表达式
调度器未运行 启动调度器：openclaw scheduler start
时间未到 等待下一个执行时间
依赖任务失败 检查并修复依赖任务

示例：

# 检查任务状态
$ openclaw schedule status daily-sync
Name: daily-sync
Status: disabled  # ← 问题：任务被禁用

# 启用任务
$ openclaw schedule enable daily-sync
Schedule enabled successfully

2. 执行失败

症状：任务执行过程中报错

排查步骤：

# 1. 查看详细日志
openclaw schedule logs my-task --level error --limit 20

# 2. 查看最近执行记录
openclaw schedule history my-task --limit 10

# 3. 手动执行测试
openclaw schedule run my-task --debug

常见错误及解决方案：

错误1：Agent 未找到

Error: Agent 'my-agent' not found

解决方案：

# 检查 Agent 是否存在
openclaw agent list

# 如果不存在，创建 Agent
openclaw agent create my-agent

# 或者修改任务配置，使用正确的 Agent 名称

错误2：权限不足

Error: Permission denied: file operation not allowed

解决方案：

# 修改技能权限配置
skills:
  - name: file-operations
    enabled: true
    permissions:
      - read
      - write
      - list
      - delete  # 添加删除权限

错误3：API 调用失败

Error: API request failed: Connection timeout

解决方案：

# 增加超时时间
task:
  type: http
  timeout: 60  # 增加到60秒

  # 添加重试
  retry:
    enabled: true
    max_attempts: 3

错误4：脚本执行错误

Error: Script execution failed: SyntaxError

解决方案：

# 先本地测试脚本
python ./scripts/my-script.py

# 查看脚本语法错误
python -m py_compile ./scripts/my-script.py

# 检查脚本路径
ls -la ./scripts/

3. 执行超时

症状：任务长时间未完成

排查步骤：

# 查看当前正在执行的任务
openclaw schedule running

# 查看任务执行时间
openclaw schedule history my-task | grep -E "duration|超时"

# 强制终止超时任务
openclaw schedule kill <execution-id>

解决方案：

# 1. 增加超时时间
timeout:
  enabled: true
  seconds: 3600  # 增加到1小时

# 2. 优化任务逻辑
task:
  type: workflow
  steps:
    - name: step1
      timeout: 300

    - name: step2
      timeout: 300

# 3. 添加超时告警
alerts:
  on_timeout:
    - type: slack
      channel: "#alerts"

4. 结果不符合预期

症状：任务执行成功但结果不对

排查步骤：

# 1. 查看详细日志
openclaw schedule logs my-task --verbose

# 2. 检查输入参数
openclaw schedule history my-task --last --show-params

# 3. 手动执行并查看输出
openclaw schedule run my-task --show-output

常见原因：

原因 解决方案
参数错误 检查传入参数
数据问题 检查数据源
逻辑错误 修复脚本逻辑
环境差异 统一运行环境

网络问题排查

1. 连接超时

# 测试网络连接
curl -v https://api.example.com

# 测试 DNS 解析
nslookup api.example.com

# 测试端口连通性
nc -zv api.example.com 443

解决方案：

# 增加超时时间
task:
  http:
    timeout: 60

  # 添加备用方案
  fallback:
    enabled: true
    use_cache: true

2. DNS 解析失败

Error: Name or service not known

解决方案：

# 使用 IP 地址
task:
  http:
    url: http://192.168.1.100/api

# 或配置 DNS
network:
  dns_servers:
    - 8.8.8.8
    - 8.8.4.4

3. SSL 证书问题

Error: SSL certificate verify failed

解决方案：

# 禁用 SSL 验证（仅开发环境）
task:
  http:
    verify_ssl: false  # ⚠️ 仅测试环境使用

# 或更新证书
network:
  ssl_cert_path: /path/to/cert.pem

资源问题排查

1. 内存不足

Error: Out of memory

排查：

# 查看系统内存
free -h

# 查看进程内存
ps aux --sort=-%mem | head

解决方案：

# 限制内存使用
resources:
  memory:
    limit: 1GB

# 优化脚本，减少内存占用

2. 磁盘空间不足

Error: No space left on device

排查：

# 查看磁盘使用
df -h

# 查找大文件
du -sh /var/log/*

解决方案：

# 清理临时文件
cleanup:
  enabled: true
  retention_days: 7

# 增加日志轮转
logging:
  rotation:
    max_size: 100MB
    max_files: 10

3. CPU 占用过高

Error: CPU usage too high

排查：

# 查看 CPU 使用
top

# 查看具体进程
htop

解决方案：

# 限制 CPU 使用
resources:
  cpu:
    limit: "50%"

# 优化代码，减少计算量

并发问题排查

1. 重复执行

症状：同一任务执行了多次

排查：

# 查看执行历史
openclaw schedule history my-task

# 检查是否有并发执行
openclaw schedule running

解决方案：

# 防止并发执行
concurrency:
  max_instances: 1
  queue_policy: skip

# 或使用幂等设计
idempotency:
  enabled: true
  key: "${date}-task-name"

2. 任务阻塞

症状：后续任务一直等待

排查：

# 查看任务依赖
openclaw schedule deps my-task

# 查看阻塞的任务
openclaw schedule blocked

解决方案：

# 设置依赖超时
dependencies:
  - name: prev-task
    timeout: 600
    on_timeout: skip

# 修复阻塞任务

数据问题排查

1. 数据不一致

症状：数据同步后不一致

排查：

# 对比数据
openclaw task verify-data --source=api --target=db

# 查看同步日志
openclaw schedule logs sync-task | grep -i error

解决方案：

# 增加数据验证
task:
  validation:
    enabled: true

    checks:
      - type: row_count
        source: api
        target: db
        tolerance: 5%

      - type: checksum
        fields: [id, name, value]

2. 数据丢失

症状：处理的数据不完整

解决方案：

# 增加数据完整性检查
task:
  checkpoints:
    enabled: true
    save_interval: 100  # 每100条保存一次

  recovery:
    enabled: true
    from_checkpoint: true

日志分析技巧

1. 按级别过滤

# 只看错误
openclaw schedule logs my-task --level error

# 只看警告
openclaw schedule logs my-task --level warning

# 查看所有
openclaw schedule logs my-task --level debug

2. 按时间过滤

# 查看今天的日志
openclaw schedule logs my-task --since today

# 查看指定时间范围
openclaw schedule logs my-task --from "2024-01-15 09:00" --to "2024-01-15 10:00"

# 查看最近100条
openclaw schedule logs my-task --limit 100

3. 搜索关键词

# 搜索错误
openclaw schedule logs my-task | grep -i error

# 搜索特定关键词
openclaw schedule logs my-task | grep "failed to"

# 搜索并统计
openclaw schedule logs my-task | grep -c ERROR

快速诊断命令

常用诊断命令汇总

# 1. 查看所有任务状态
openclaw schedule list

# 2. 查看调度器状态
openclaw scheduler status

# 3. 查看任务详情
openclaw schedule info <task-name>

# 4. 查看最近执行
openclaw schedule history <task-name> --limit 10

# 5. 查看日志
openclaw schedule logs <task-name> --level error

# 6. 手动执行测试
openclaw schedule run <task-name> --debug

# 7. 强制停止
openclaw schedule kill <execution-id>

# 8. 重新加载配置
openclaw scheduler reload

诊断脚本

#!/bin/bash
# diagnose-schedule.sh

echo "=== 定时任务诊断 ==="

echo -e "\n1. 调度器状态"
openclaw scheduler status

echo -e "\n2. 所有任务状态"
openclaw schedule list

echo -e "\n3. 正在运行的任务"
openclaw schedule running

echo -e "\n4. 最近执行失败的任务"
openclaw schedule history | grep -E "FAILED|ERROR"

echo -e "\n5. 调度器日志"
openclaw scheduler logs --tail 20

echo -e "\n=== 诊断完成 ==="

常见问题速查表

问题 原因 解决方案
任务不执行 禁用/未启动 enable / start
执行失败 多种 查看日志定位
超时 任务太重 增加超时/优化
重复执行 无并发控制 添加 max_instances: 1
内存溢出 内存不足 限制内存/优化代码
网络失败 网络问题 检查网络/增加重试
数据错误 逻辑问题 修复脚本/添加验证

寻求帮助

如果以上方法无法解决问题：

# 1. 导出完整诊断信息
openclaw schedule diagnose my-task > diagnose.txt

# 2. 查看系统信息
openclaw system info

# 3. 收集日志
openclaw logs collect --since "1 hour ago" --output logs.zip

定时任务系列教程已完结！现在你可以：

接下来学习微信公众号运营： - OpenCLAW 对接微信公众号