​

Cron ジョブ（Gateway スケジューラ）

Cron と Heartbeat の違いは？ それぞれの使い分けについては、Cron vs Heartbeat を参照してください。

​

TL;DR

• Cron は Gateway の内部で実行 されます（モデル内部ではありません）。
• ジョブは ~/.openclaw/cron/ の配下に永続化されるため、再起動してもスケジュールは失われません。
• 実行スタイルは 2 種類あります:
  • メインセッション: システムイベントをキューに入れ、次のハートビートで実行します。
  • 分離実行: cron:<jobId> で専用のエージェントターンを実行し、配信（デフォルトは通知、またはなし）を行います。
• ウェイクアップは第一級の機能です。ジョブは「今すぐ起こす」か「次のハートビート」を指定できます。

​

クイックスタート（実践）

openclaw cron add \
  --name "Reminder" \
  --at "2026-02-01T16:00:00Z" \
  --session main \
  --system-event "Reminder: check the cron docs draft" \
  --wake now \
  --delete-after-run

openclaw cron list
openclaw cron run <job-id>
openclaw cron runs --id <job-id>

openclaw cron add \
  --name "Morning brief" \
  --cron "0 7 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Summarize overnight updates." \
  --announce \
  --channel slack \
  --to "channel:C1234567890"

​

ツールコール相当（Gateway cron ツール）

​

cron ジョブの保存場所

​

初心者向け概要

1. スケジュールを選ぶ
   • 単発リマインダー → schedule.kind = "at"（CLI: --at）
   • 繰り返しジョブ → schedule.kind = "every" または schedule.kind = "cron"
   • ISO タイムスタンプにタイムゾーンが含まれない場合、UTC として扱われます。
2. 実行場所を選ぶ
   • sessionTarget: "main" → 次のハートビートでメインコンテキストとして実行します。
   • sessionTarget: "isolated" → cron:<jobId> で専用のエージェントターンを実行します。
3. ペイロードを選ぶ
   • メインセッション → payload.kind = "systemEvent"
   • 分離セッション → payload.kind = "agentTurn"

​

概念

​

ジョブ

• スケジュール（いつ実行するか）
• ペイロード（何を実行するか）
• 任意の 配信モード（通知またはなし）
• 任意の エージェントバインディング（agentId）: 特定のエージェントでジョブを実行します。指定がない、または不明な場合は、Gateway がデフォルトのエージェントにフォールバックします。

​

スケジュール

• at: schedule.at（ISO 8601）による単発タイムスタンプ
• every: 固定間隔（ミリ秒）
• cron: オプションの IANA タイムゾーン付き 5 フィールドの cron 式

​

メイン実行と分離実行

​

メインセッションジョブ（システムイベント）

• wakeMode: "now"（デフォルト）: イベントは即座にハートビート実行をトリガーします。
• wakeMode: "next-heartbeat": イベントは次に予定されたハートビートまで待機します。

​

分離ジョブ（専用 cron セッション）

• プロンプトはトレーサビリティのために [cron:<jobId> <job name>] が前置されます。
• 各実行は 新しいセッション ID で開始されます（過去の会話は引き継がれません）。
• デフォルトの挙動: delivery が省略された場合、分離ジョブはサマリーを通知します（delivery.mode = "announce"）。
• delivery.mode（分離専用）で挙動を選択します:
  • announce: 対象チャンネルにサマリーを配信し、メインセッションにも簡潔なサマリーを投稿します。
  • none: 内部のみ（配信なし、メインセッションのサマリーなし）。
• wakeMode は、メインセッションへのサマリー投稿タイミングを制御します:
  • now: 即時ハートビート。
  • next-heartbeat: 次に予定されたハートビートまで待機。

​

ペイロード形状（実行内容）

• systemEvent: メインセッション専用。ハートビートプロンプト経由でルーティングされます。
• agentTurn: 分離セッション専用。専用のエージェントターンを実行します。

• message: 必須のテキストプロンプト
• model / thinking: 任意の上書き設定（後述）
• timeoutSeconds: 任意のタイムアウト上書き

• delivery.mode: none | announce
• delivery.channel: last または特定のチャンネル
• delivery.to: チャンネル固有のターゲット（電話 / チャット / チャンネル ID）
• delivery.bestEffort: 通知配信が失敗してもジョブを失敗扱いにしない

​

通知配信フロー

• 内容: 配信は、分離実行のアウトバウンドペイロード（テキスト / メディア）を通常の分割とチャンネル整形で使用します。
• ハートビート専用の応答（実体のある内容を伴わない HEARTBEAT_OK）は配信されません。
• 分離実行がすでに同一ターゲットへメッセージツールで送信している場合、重複回避のため配信はスキップされます。
• 配信ターゲットが欠落または無効な場合、delivery.bestEffort = true がない限りジョブは失敗します。
• 短いサマリーは、delivery.mode = "announce" の場合にのみメインセッションへ投稿されます。
• メインセッションのサマリーは wakeMode に従います。now は即時ハートビート、next-heartbeat は次に予定されたハートビートを待機します。

​

モデルおよび思考レベルの上書き

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

1. ジョブペイロードの上書き（最優先）
2. フック固有のデフォルト（例: hooks.gmail.model）
3. エージェント設定のデフォルト

​

配信（チャンネル + ターゲット）

• delivery.mode: announce（サマリーを配信）または none
• delivery.channel: whatsapp / telegram / discord / slack / mattermost（プラグイン） / signal / imessage / last
• delivery.to: チャンネル固有の受信者ターゲット

• Slack / Discord / Mattermost（プラグイン）のターゲットは、曖昧さを避けるため明示的なプレフィックス（例: channel:<id>, user:<id>）を使用してください。
• Telegram のトピックは :topic: 形式を使用してください（下記参照）。

​

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

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

• telegram:group:-1001234567890:topic:123

​

ツールコール用 JSON スキーマ

​

cron.add params

{
  "name": "Reminder",
  "schedule": { "kind": "at", "at": "2026-02-01T16:00:00Z" },
  "sessionTarget": "main",
  "wakeMode": "now",
  "payload": { "kind": "systemEvent", "text": "Reminder text" },
  "deleteAfterRun": true
}

{
  "name": "Morning brief",
  "schedule": { "kind": "cron", "expr": "0 7 * * *", "tz": "America/Los_Angeles" },
  "sessionTarget": "isolated",
  "wakeMode": "next-heartbeat",
  "payload": {
    "kind": "agentTurn",
    "message": "Summarize overnight updates."
  },
  "delivery": {
    "mode": "announce",
    "channel": "slack",
    "to": "channel:C1234567890",
    "bestEffort": true
  }
}

• schedule.kind: at（at）、every（everyMs）、または cron（expr、任意で tz）。
• schedule.at は ISO 8601 を受け付けます（タイムゾーン省略可。省略時は UTC として扱われます）。
• everyMs はミリ秒です。
• sessionTarget は "main" または "isolated" でなければならず、payload.kind と一致する必要があります。
• 任意フィールド: agentId, description, enabled, deleteAfterRun（at の場合はデフォルト true）, delivery。
• wakeMode は省略時に "now" がデフォルトになります。

​

cron.update params

{
  "jobId": "job-123",
  "patch": {
    "enabled": false,
    "schedule": { "kind": "every", "everyMs": 3600000 }
  }
}

• jobId が正規であり、互換性のため id も受け付けます。
• エージェントバインディングを解除するには、パッチ内で agentId: null を使用してください。

​

cron.run および cron.remove params

{ "jobId": "job-123", "mode": "force" }

{ "jobId": "job-123" }

​

ストレージと履歴

• ジョブストア: ~/.openclaw/cron/jobs.json（Gateway 管理の JSON）
• 実行履歴: ~/.openclaw/cron/runs/<jobId>.jsonl（JSONL、自動的に剪定）
• ストアパスの上書き: 設定で cron.store

​

設定

{
  cron: {
    enabled: true, // default true
    store: "~/.openclaw/cron/jobs.json",
    maxConcurrentRuns: 1, // default 1
  },
}

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

​

CLI クイックスタート

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

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

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

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

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 \
  --announce \
  --channel whatsapp \
  --to "+15551234567"

# Pin a job to agent "ops" (falls back to default if that agent is missing)
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops

# Switch or clear the agent on an existing job
openclaw cron edit <jobId> --agent ops
openclaw cron edit <jobId> --clear-agent

openclaw cron run <jobId>
openclaw cron run <jobId> --due

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（force または due）, cron.runs ジョブを作成せずに即時システムイベントを実行するには、openclaw system event を使用してください。

​

トラブルシューティング

​

「何も実行されない」

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

​

定期ジョブが失敗後に遅延し続ける

• OpenClaw は、連続エラー後の定期ジョブに対して指数バックオフの再試行を適用します: 30 秒、1 分、5 分、15 分、その後は 60 分間隔です。
• 次に成功した実行後、バックオフは自動的にリセットされます。
• 単発（at）ジョブは、終了状態（ok, error, または skipped）後に無効化され、再試行されません。

​

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

• フォーラムトピックの場合は、明示的で曖昧さのない -100…:topic:<id> を使用してください。
• ログや保存された「最後のルート」ターゲットに telegram:... プレフィックスが表示される場合がありますが、これは正常です。 cron 配信はそれらを受け付け、トピック ID も正しく解析します。