Cron jobs（Gateway スケジューラー）

Cron vs Heartbeat? どちらを使用するかについては、Cron vs Heartbeat を参照してください。

Cron は Gateway の組み込みスケジューラーです。ジョブを永続化し、適切なタイミングで Agent（エージェント）を起こし、オプションでチャットに出力を返すことができます。

「毎朝これを実行する」または「20分後にエージェントをつつく」が必要な場合、Cron がそのメカニズムです。

TL;DR

  • Cron は Gateway 内部で実行されます（モデル内部ではありません）。
  • ジョブは ~/.openclaw/cron/ 以下に永続化されるため、再起動してもスケジュールは失われません。
  • 2つの実行スタイル:
    • Main session（メインセッション）: システムイベントをエンキューし、次の Heartbeat で実行します。
    • Isolated（分離）: 専用の Agent ターンを cron:<jobId> で実行し、オプションで出力を配信します。
  • Wakeup（ウェイクアップ）はファーストクラスです: ジョブは「今すぐ起動」対「次の Heartbeat」をリクエストできます。

初心者向けの概要

Cron ジョブは次のように考えてください: いつ実行するか + 何をするか。

  1. スケジュールを選択

    • ワンショットリマインダー → schedule.kind = "at" (CLI: --at)
    • 繰り返しジョブ → schedule.kind = "every" または schedule.kind = "cron"
    • ISO タイムスタンプがタイムゾーンを省略した場合、UTC として扱われます。

  2. 実行場所を選択

    • sessionTarget: "main" → 次の Heartbeat 中にメインコンテキストで実行します。
    • sessionTarget: "isolated" → 専用の Agent ターンを cron:<jobId> で実行します。

  3. ペイロードを選択

    • Main session → payload.kind = "systemEvent"
    • Isolated session → payload.kind = "agentTurn"

オプション: deleteAfterRun: true は成功したワンショットジョブをストアから削除します。

概念

Jobs（ジョブ）

Cron ジョブは次の要素を持つ保存レコードです:

  • schedule（いつ実行するか）
  • payload（何をするか）
  • オプションの delivery（出力をどこに送るか）
  • オプションの Agent バインディング（agentId）: 特定の Agent でジョブを実行します。欠落しているか不明な場合、Gateway はデフォルトの Agent にフォールバックします。

ジョブは安定した jobId で識別されます（CLI/Gateway API で使用）。 Agent ツール呼び出しでは、jobId が正規です。レガシーの id も互換性のために受け入れられます。 ジョブは deleteAfterRun: true を介して、成功したワンショット実行後に自動削除できます。

Schedules（スケジュール）

Cron は3つのスケジュール種別をサポートします:

  • at: ワンショットタイムスタンプ（エポックからのミリ秒）。Gateway は ISO 8601 を受け入れ、UTC に変換します。
  • every: 固定間隔（ミリ秒）。
  • cron: オプションの IANA タイムゾーンを持つ5フィールドの Cron 式。

Cron 式は croner を使用します。タイムゾーンが省略された場合、Gateway ホストのローカルタイムゾーンが使用されます。

Main vs isolated 実行

Main session ジョブ（システムイベント）

Main ジョブはシステムイベントをエンキューし、オプションで Heartbeat ランナーを起こします。 payload.kind = "systemEvent" を使用する必要があります。

  • wakeMode: "next-heartbeat" (デフォルト): イベントは次のスケジュールされた Heartbeat を待ちます。
  • wakeMode: "now": イベントは即座に Heartbeat 実行をトリガーします。

これは通常の Heartbeat プロンプト + メインセッションコンテキストが必要な場合に最適です。 Heartbeat を参照してください。

Isolated ジョブ（専用 Cron セッション）

Isolated ジョブは専用の Agent ターンを session cron:<jobId> で実行します。

主な動作:

  • プロンプトにトレーサビリティのため [cron:<jobId> <job name>] が接頭辞されます。
  • 各実行は 新しい session id を開始します（以前の会話の持ち越しなし）。
  • 要約が Main session に投稿されます（接頭辞 Cron、設定可能）。
  • wakeMode: "now" は要約を投稿した後、即座に Heartbeat をトリガーします。
  • payload.deliver: true の場合、出力は Channel（チャンネル）に配信されます。それ以外は内部に留まります。

頻繁でノイズが多いもの、またはメインチャット履歴をスパムしない「バックグラウンド雑用」には Isolated ジョブを使用してください。

Payload 形式（何を実行するか）

2つのペイロード種別がサポートされています:

  • systemEvent: メインセッションのみ、Heartbeat プロンプト経由でルーティングされます。
  • agentTurn: Isolated セッションのみ、専用の Agent ターンを実行します。

一般的な agentTurn フィールド:

  • message: 必須のテキストプロンプト。
  • model / thinking: オプションのオーバーライド（以下を参照）。
  • timeoutSeconds: オプションのタイムアウトオーバーライド。
  • deliver: true で Channel ターゲットに出力を送信します。
  • channel: last または特定の Channel。
  • to: Channel 固有のターゲット（電話/チャット/Channel ID）。
  • bestEffortDeliver: 配信失敗時にジョブを失敗させないようにします。

Isolation オプション（session=isolated のみ）:

  • postToMainPrefix (CLI: --post-prefix): Main のシステムイベントの接頭辞。
  • postToMainMode: summary（デフォルト）または full。
  • postToMainMaxChars: postToMainMode=full の場合の最大文字数（デフォルト 8000）。

Model と Thinking のオーバーライド

Isolated ジョブ（agentTurn）は Model（モデル）と Thinking レベルをオーバーライドできます:

  • model: プロバイダー/モデル文字列（例: anthropic/claude-sonnet-4-20250514）またはエイリアス（例: opus）
  • thinking: Thinking レベル（off, minimal, low, medium, high, xhigh。GPT-5.2 + Codex モデルのみ）

注意: Main session ジョブにも model を設定できますが、共有 Main session モデルが変更されます。予期しないコンテキストシフトを避けるため、Isolated ジョブのみに Model オーバーライドを推奨します。

解決の優先順位:

  1. ジョブペイロードオーバーライド（最高）
  2. Hook 固有のデフォルト（例: hooks.gmail.model）
  3. Agent 設定のデフォルト

Delivery（Channel + ターゲット）

Isolated ジョブは出力を Channel に配信できます。ジョブペイロードは次を指定できます:

  • channel: whatsapp / telegram / discord / slack / mattermost（プラグイン）/ signal / imessage / last
  • to: Channel 固有の受信者ターゲット

channel または to が省略された場合、Cron は Main session の「最後のルート」（Agent が最後に返信した場所）にフォールバックできます。

配信に関する注意:

  • to が設定されている場合、deliver が省略されていても Cron は自動的に Agent の最終出力を配信します。
  • 明示的な to なしで最後のルート配信が必要な場合は deliver: true を使用してください。
  • to が存在する場合でも出力を内部に保つには deliver: false を使用してください。

ターゲット形式の注意事項:

  • Slack/Discord/Mattermost（プラグイン）ターゲットは曖昧さを避けるために明示的な接頭辞（例: channel:<id>, user:<id>）を使用する必要があります。
  • Telegram トピックは :topic: 形式を使用する必要があります（以下を参照）。

Telegram 配信ターゲット（トピック / フォーラムスレッド）

Telegram は message_thread_id を介してフォーラムトピックをサポートします。Cron 配信用に、トピック/スレッドを to フィールドにエンコードできます:

  • -1001234567890（チャット ID のみ）
  • -1001234567890:topic:123（推奨: 明示的なトピックマーカー）
  • -1001234567890:123（短縮形: 数値サフィックス）

telegram:... / telegram:group:... のような接頭辞付きターゲットも受け入れられます:

  • telegram:group:-1001234567890:topic:123

ストレージと履歴

  • ジョブストア: ~/.openclaw/cron/jobs.json（Gateway 管理 JSON）。
  • 実行履歴: ~/.openclaw/cron/runs/<jobId>.jsonl（JSONL、自動プルーニング）。
  • ストアパスのオーバーライド: 設定の cron.store。

設定

{
  cron: {
    enabled: true, // デフォルト true
    store: "~/.openclaw/cron/jobs.json",
    maxConcurrentRuns: 1 // デフォルト 1
  }
}

Cron を完全に無効化:

  • cron.enabled: false（設定）
  • OPENCLAW_SKIP_CRON=1（環境変数）

CLI クイックスタート

ワンショットリマインダー（UTC ISO、成功後自動削除）:

openclaw cron add \
  --name "Send reminder" \
  --at "2026-01-12T18:00:00Z" \
  --session main \
  --system-event "Reminder: submit expense report." \
  --wake now \
  --delete-after-run

ワンショットリマインダー（Main session、即座にウェイク）:

openclaw cron add \
  --name "Calendar check" \
  --at "20m" \
  --session main \
  --system-event "Next heartbeat: check calendar." \
  --wake now

繰り返し Isolated ジョブ（WhatsApp に配信）:

openclaw cron add \
  --name "Morning status" \
  --cron "0 7 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Summarize inbox + calendar for today." \
  --deliver \
  --channel whatsapp \
  --to "+15551234567"

繰り返し Isolated ジョブ（Telegram トピックに配信）:

openclaw cron add \
  --name "Nightly summary (topic)" \
  --cron "0 22 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Summarize today; send to the nightly topic." \
  --deliver \
  --channel telegram \
  --to "-1001234567890:topic:123"

Model と Thinking オーバーライド付き Isolated ジョブ:

openclaw cron add \
  --name "Deep analysis" \
  --cron "0 6 * * 1" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Weekly deep analysis of project progress." \
  --model "opus" \
  --thinking high \
  --deliver \
  --channel whatsapp \
  --to "+15551234567"

Agent 選択（マルチエージェント設定）:

# ジョブを Agent "ops" に固定（そのエージェントが見つからない場合はデフォルトにフォールバック）
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops

# 既存のジョブの Agent を切り替えまたはクリア
openclaw cron edit <jobId> --agent ops
openclaw cron edit <jobId> --clear-agent

手動実行（デバッグ）:

openclaw cron run <jobId> --force

既存のジョブを編集（フィールドをパッチ）:

openclaw cron edit <jobId> \
  --message "Updated prompt" \
  --model "opus" \
  --thinking low

実行履歴:

openclaw cron runs --id <jobId> --limit 50

ジョブを作成せずに即座のシステムイベント:

openclaw system event --mode now --text "Next heartbeat: check battery."

Gateway API サーフェス

  • cron.list, cron.status, cron.add, cron.update, cron.remove
  • cron.run（強制または期限）, cron.runs ジョブなしで即座のシステムイベントには openclaw system event を使用してください。

トラブルシューティング

"何も実行されない"

  • Cron が有効であることを確認: cron.enabled と OPENCLAW_SKIP_CRON。
  • Gateway が継続的に実行されていることを確認（Cron は Gateway プロセス内で実行されます）。
  • cron スケジュールの場合: タイムゾーン（--tz）対ホストタイムゾーンを確認してください。

Telegram が間違った場所に配信される

  • フォーラムトピックには -100…:topic:<id> を使用して明示的で明確にしてください。
  • ログまたは保存された「最後のルート」ターゲットに telegram:... 接頭辞が表示される場合、それは正常です。 Cron 配信はそれらを受け入れ、トピック ID を正しく解析します。
← ドキュメントに戻る