スケジュールされたタスク

Cron は Gateway に組み込まれたスケジューラです。ジョブを永続化し、適切な時刻にエージェントを起動し、出力をチャットチャンネルや Webhook に配信することも、どこにも配信しないこともできます。

クイックスタート

openclaw cron create "2027-02-01T16:00:00Z" \  --name "リマインダー" \  --session main \  --system-event "リマインダー: Cron ドキュメントの下書きを確認する" \  --wake now \  --delete-after-run

openclaw cron listopenclaw cron get <job-id>openclaw cron show <job-id>

openclaw cron runs --id <job-id>

Cron の仕組み

• Cron はモデル内ではなく、Gateway プロセス内で実行されます。スケジュールを実行するには Gateway が稼働している必要があります。
• ジョブ定義、ランタイム状態、実行履歴は OpenClaw の共有 SQLite 状態データベースに永続化されるため、再起動してもスケジュールは失われません。
• Cron を実行するたびに、バックグラウンドタスクのレコードが作成されます。
• 1 回限りのジョブ（--at）は、デフォルトでは成功後に自動削除されます。保持するには --keep-after-run を渡します。
• 実行ごとの実時間上限: 設定されている場合は --timeout-seconds。それ以外の場合、分離またはデタッチされたエージェントターンのジョブは、基盤となるエージェントターンのタイムアウト（agents.defaults.timeoutSeconds、デフォルトは 48 時間）が適用されるより前に、Cron 独自の 60 分間のウォッチドッグによって制限されます。コマンドジョブのデフォルトは 10 分、スクリプトペイロードのデフォルトは 5 分です。
• Gateway の起動時、期限を過ぎた分離エージェントターンのジョブは即座に再実行されず、再スケジュールされます。これにより、モデルやツールのブートストラップ処理がチャンネル接続期間中に行われることを防ぎます。
• システム Cron または別の外部スケジューラから openclaw agent を実行する場合、CLI がすでに SIGTERM/SIGINT を処理していても、強制終了へ移行する仕組みでラップしてください。Gateway による実行では、受理された実行を中止するよう Gateway に要求します。--local の実行にも同じ中止シグナルが送られます。GNU timeout では、単純な timeout 600 ... より timeout -k 60 600 openclaw agent ... を推奨します。プロセスを時間内に終了できない場合、-k の値が最後の安全策になります。systemd ユニットでは、最終的な強制終了の前に猶予期間（TimeoutStopSec）を設け、SIGTERM 停止シグナルを使用します。元の Gateway 実行がまだアクティブな間に --run-id を再利用すると、2 回目の実行を開始する代わりに、重複が実行中として報告されます。

スケジュールの種類

タイムゾーンのないタイムスタンプは UTC として扱われます。オフセットのない --at 日時を解釈する場合、またはその IANA タイムゾーンで Cron 式を評価する場合は、--tz America/New_York を追加します。--tz のない Cron 式には Gateway ホストのタイムゾーンが使用されます。--tz は --every または --on-exit と併用できません。

毎時 0 分に繰り返す式（分フィールドが 0 で、時フィールドがワイルドカード）は、負荷の急増を抑えるため、最大 5 分間自動的に分散されます。正確なタイミングを強制するには --exact を使用し、明示的な時間枠を指定するには --stagger 30s を使用します（Cron スケジュールのみ）。

Heartbeat タスクの移行

以前の Heartbeat スクラッチでは、構造化された tasks: ブロックがサポートされていました。アップグレード後に openclaw doctor --fix を実行すると、各エントリが通常の編集可能なメインセッションの Cron ジョブに変換されます。Doctor は間隔と以前の最終実行時刻を維持し、ブロックを削除する前にジョブを作成します。また、再実行時には同じ宣言キーを安全に収束させます。

移行されたジョブには公開 systemEvent ペイロードが含まれるため、openclaw cron list、get、edit、remove、および Cron ツールを使用して、ほかのジョブと同様に管理できます。実行には保護された Heartbeat タスクの起動処理が使用されます。アクティブ時間、最小間隔、フラッド制御、ビジー時の再試行は引き続き適用され、Cron が各タスクの独立した実行間隔を管理します。同じ統合時間枠内に期限を迎えるジョブは、1 回の Heartbeat ターンを共有できます。Heartbeat のアクティブ時間外にスケジュールされた実行はスキップされ、そのジョブの次の実行時に再試行されます。

Heartbeat スクラッチは、現在では監視用の文章のみを扱います。ランタイムの Heartbeat は tasks: のテキストをスケジュールとして解析しません。新しい繰り返し処理は Cron で作成してください。

ストリームソース

ストリームスケジュールは、オペレーターが作成した argv コマンドを Gateway の管理下で実行し続け、その標準出力および標準エラー出力の行からジョブを実行します。ストリームスケジュールはイベント駆動型であり、時刻によって期限を迎えることはありません。また、長期間実行されるコマンドはトリガースクリプトと同じ無人実行の信頼クラスに属するため、cron.triggers.enabled: true が必要です。ジョブを無効化または削除すると、プロセスが停止します。Gateway のシャットダウン時には、プロセスツリーの終了を待機します。短時間での障害発生時には、Cron に組み込まれたエラーバックオフを使用して再起動します。60 秒未満の実行が 5 回連続すると、ジョブはエラー状態になり、通常の障害アラート処理が使用されます。再起動回数の上限を解除するには、ジョブを手動で再有効化してください。

openclaw cron add \  --name "ビルドイベントストリーム" \  --stream-command '["node","scripts/build-events.mjs"]' \  --stream-mode match \  --stream-match '^(failed|recovered):' \  --stream-batch-ms 250 \  --session isolated \  --message "これらのビルドイベントを調査してください。"

mode: "line"（デフォルト）はすべての行を受け入れます。mode: "match" は、コンパイルされた match 正規表現に一致する行のみを受け入れます。バッチは、batchMs の無入力期間（デフォルトは 250 ms、50～5000 に制限）が経過するか、maxBatchBytes（デフォルトは 16384、1024～65536 に制限）に達すると閉じられます。バイト上限に達した場合、バッチの末尾には [truncated] が追加されます。マッチモードでは、maxBatchBytes を超えた場合でも、常に完全な行の全文に対して評価されます（切り詰められるのは配信されるバッチのみです）。制限された生入力の上限で切断された行は単なるプレフィックスであるため、末尾アンカー付きパターンが切断箇所で一致しないよう、不一致として扱われます。バッチはシステムイベントのテキストまたはエージェントターンのメッセージに追加されます。ソースコマンドとペイロードコマンドのプロセス所有権が曖昧になるため、ストリームスケジュールではコマンドペイロードが拒否されます。

ジョブごとに保持されるのは、実行中のペイロード 1 件と、サイズが制限された保留中のバッチ 1 件のみです。ペイロードの実行中、または組み込みの 30 秒間のトリガー間隔が経過する前に到着した行は、無制限のキューを構築する代わりに、その保留中のバッチへ統合されます。単一の直列化された所有者が、ゲートによる破棄、ペイロードエラー、未実行状態でのディスパッチを streamDroppedBatches に記録します。制限付きの統合では streamCoalescedBatches が増加します。失敗したペイロードは冪等でない可能性があるため、再試行されません。論理的なソース ID は監視対象の子プロセスが再起動しても維持されますが、ソースが無効化、削除、または置換されると変更されます。そのため、A から B、さらに A へ編集した場合でも、廃止されたソースのキュー済みバッチが実行されることはありません。停止が完了すると、古い子プロセスからの遅延コールバックは何も実行しません。V1 にはネイティブ WebSocket ソースが含まれていません。websocat wss://example.invalid/events のような argv コマンドを使用してブリッジしてください。

ストリームジョブに trigger.script も設定されている場合、閉じられたバッチごとにゲートが 1 回実行されます。現在のバッチは、trigger.state とともに、深く凍結された trigger.streamBatch 文字列として使用できます。fire: false はゲート状態を永続化した後、そのバッチを破棄します。fire: true は既存のトリガーメッセージのセマンティクスを維持し、その後、生成されたペイロードにバッチを追加します。ストリームジョブでは、条件ゲートを使用せず、代わりにスクリプトペイロードを使用することもできます。そのスクリプトは、同じ trigger.streamBatch の値を通じてバッチを受け取ります。スクリプトペイロードと条件ゲートを組み合わせると、両方が永続化された trigger.state スロットを所有することになるため、拒否されます。

動的な実行間隔（ペーシング）

繰り返しジョブでは、pacing.min と pacing.max の一方または両方を、15m や 4h のような期間文字列に設定できます。少なくとも一方の境界値が必要です。cron add|edit とともに --pacing-min および --pacing-max を使用します（--clear-pacing は両方の境界値を削除します）。

分離実行中、ペーシング対象のジョブは action: "next_check" および in: "30m" を指定して cron ツールを呼び出せます。この提案は現在実行中のそのジョブにのみ適用され、実行が正常に完了した時点から計測されます。OpenClaw は、設定された範囲内に暗黙的に収めます。

提案なしのペーシングでは、通常のスケジュールは変更されません。失敗、タイムアウト、スキップされた実行では提案が破棄されるため、既存の再試行およびエラーバックオフの動作が優先されます。定期ジョブを手動で強制実行する操作は帯域外として扱われ、保留中の通常スロットまたはペーシング済みスロットは維持されます。条件トリガー型ジョブでは、提案によってより早いチェックが要求された場合でも、組み込みの最小間隔が下限として維持されます。

日付と曜日には OR ロジックを使用する

Cron 式は croner によって解析されます。日付フィールドと曜日フィールドの両方がワイルドカードでない場合、croner は両方ではなく、いずれかのフィールドが一致すると一致と判定します。これは標準的な Vixie cron の動作です。

# 意図: 「15日が月曜日の場合にのみ、午前9時」# 実際: 「毎月15日の午前9時、かつ毎週月曜日の午前9時」0 9 15 * 1

この場合、月に 0～1 回ではなく、およそ 5～6 回実行されます。両方の条件を必須にするには、croner の曜日修飾子 +（0 9 15 * +1）を使用するか、一方のフィールドでスケジュールし、もう一方をジョブのプロンプトまたはコマンドでチェックしてください。

イベントトリガー（条件ウォッチャー）

イベントトリガーは、every、cron、または stream スケジュールにヘッドレス条件スクリプトを追加します。時刻スケジュールでは期限到来時に評価し、ストリームスケジュールではクローズされたバッチごとに評価します。スクリプトが fire: true を返した場合にのみ、Cron は通常のペイロードを実行します。

{  schedule: { kind: "every", everyMs: 30000 },  trigger: {    // 観測されたステータスが前回の評価と異なる場合にのみ発火します。    script: "const res = await tools.call('exec', { command: 'gh pr checks 123 --json state -q \\'.[].state\\' | sort -u' }); const status = String(res?.result?.details?.aggregated ?? '').trim(); json({ fire: status !== trigger.state?.status, message: `PR 123 CI: ${trigger.state?.status ?? 'unknown'} -> ${status}`, state: { status } });",    once: false,  },  payload: { kind: "agentTurn", message: "CI ステータスの変更を調査してください。" },}

スクリプトは { fire, message?, state? } を返す必要があります。以前の JSON 状態は、深く凍結された trigger.state として使用できます。ストリームゲートは、現在のバッチも trigger.streamBatch として受け取ります。永続化するには、新しい state 値を返してください。状態の上限は 16 KB です。発火結果に message が含まれる場合、Cron は実行前にそれをシステムイベントのテキストまたはエージェントターンのメッセージへ追加します。once: true は、最初に発火したペイロードが正常に完了した後、ジョブを無効にします。

fire: false は評価状態とカウンターを永続化し、実行履歴を作成せずに再スケジュールします。発火したペイロードの実行が失敗した場合、返された state は永続化されません。次の評価では以前の状態が参照され、再び発火する可能性があります。そのため、スクリプトは読み取り専用のチェックとして記述し、アクションはペイロードに保持してください。トリガースケジュールには、組み込みの最小間隔として 30 秒が設定されています。各評価には実時間で 30 秒の制限があり、ツール呼び出しは最大 5 回です。

ウォッチャーは成功だけでなく、対応可能な状態を中心に設計してください。チェックが失敗またはタイムアウトしたときに沈黙するウォッチャーは、壊れていても正常に見えます。観測結果を trigger.state と比較し、重複を排除するために新しい状態を返してください。モデルやプロセスのメモリに依存しないでください。発火時には、message が発火した実行の完全なイベントコンテキストになるため、自己完結する内容にしてください。

ローカルスクリプトファイルからウォッチャーを作成します（- は標準入力からスクリプトを読み取ります）。

openclaw cron add \  --name "PR CI watcher" \  --every 30s \  --trigger-script ./watch-pr-ci.js \  --message "Respond to the CI status change" \  --session isolated

ペイロード

各ジョブには、フラグで選択されたペイロード種別が正確に 1 つ含まれます。

追加のペイロード種別 heartbeat はシステム所有です。Gateway は、Heartbeat が有効なエージェントごとに 1 つの Heartbeat 監視ジョブへ収束させます（Heartbeat を参照）。これは cron list --all に表示されますが、CLI または API を介して作成・編集することはできません。Heartbeat の設定は、起動時、設定の再読み込み時、または openclaw doctor --fix によって、永続化された監視スケジュールへ反映されます。Cron が無効な場合、監視ジョブはティックせず、代替の Heartbeat タイマーも実行されません。

エージェントターンのオプション

ツールを実行できる新しいジョブには、常に明示的なツールポリシーが保存されます。エージェントが作成したジョブは、作成元のターンで使用可能なツールを上限とし、エージェントは保存された一覧を拡張できません。--tools を指定せずに認証済みオペレーターが作成したジョブには、制限なしの * ポリシーが保存されます。cron edit --clear-tools は、その明示的な制限なしポリシーを復元します。明示的なツールポリシーの導入前に作成された既存のジョブは、ツールポリシーが明示的に編集されるかジョブが再作成されるまで、現在の動作を維持します。

--model はジョブのプライマリモデルを設定します。セッションの /model 上書きは置き換えないため、設定済みのフォールバックチェーンは引き続きその上に適用されます。解決できない、または許可されていないモデルの場合、デフォルトへ暗黙的にフォールバックせず、明示的な検証エラーで実行が失敗します。ジョブに --model があり、明示的または設定済みのフォールバック一覧がない場合、OpenClaw はエージェントのプライマリを隠れた再試行先として暗黙的に追加せず、空のフォールバック上書きを渡します。

分離ジョブのモデル選択優先順位は、上から順に次のとおりです。

1. ジョブ単位のペイロード model（明示的な設定。許可されていないモデルでは実行が失敗）
2. Gmail フックのモデル上書き（Gmail から開始された実行で、かつその上書きが許可されている場合のみ）
3. ユーザーが選択し、保存された Cron セッションのモデル上書き
4. エージェント／デフォルトのモデル選択

高速モードは、解決された現在の選択に従います。選択されたモデル設定に params.fastMode がある場合、分離 Cron はそれをデフォルトで使用します。ただし、保存されたセッションの fastMode 上書き（次にエージェントの fastModeDefault）は、どちらの方向でもモデル設定より優先されます。自動モードはモデルの params.fastAutoOnSeconds しきい値を使用し、デフォルトは 60 秒です。

実行中にライブモデル切り替えの引き継ぎが発生した場合、Cron は切り替え後のプロバイダー／モデルで再試行し、その選択（および新しい認証プロファイルがある場合はそれも）を現在の実行に対して永続化します。再試行回数には上限があります。最初の試行に加えて切り替え再試行を 2 回行った後は、ループせずに Cron が中止します。

分離実行を開始する前に、OpenClaw は、baseUrl が local loopback、プライベートネットワーク、または .local である、設定済みの api: "ollama" および api: "openai-completions" プロバイダーについて、到達可能なローカルエンドポイントを確認します。この事前確認では、ジョブに設定されたフォールバックチェーンを順に調べ、すべての候補に到達できない場合にのみ実行を skipped としてマークします。--fallbacks "" は、この確認をプライマリモデルのみに厳密に限定します。停止中のエンドポイントでは、モデル呼び出しを開始せず、明確なエラーとともに実行を skipped として記録します。結果はエンドポイントごと（ジョブやモデルごとではなく）に 5 分間キャッシュされるため、停止中のローカル Ollama/vLLM/SGLang/LM Studio サーバーを共有する多数の期限到来ジョブでも、リクエストの集中ではなく 1 回のプローブで済みます。事前確認でスキップされた実行は、実行エラーのバックオフ回数を増加させません。スキップ通知を繰り返し受け取るには、failureAlert.includeSkipped を設定します。

コマンドペイロード

コマンドペイロードは、モデルを使用するターンを開始せずに、Gateway スケジューラー内で決定論的なスクリプトを実行します。Gateway ホスト上で実行され、標準出力／標準エラーをキャプチャし、Cron 履歴に実行を記録します。また、エージェントターンのジョブと同じ announce、webhook、none 配信モードを再利用します。

openclaw cron create "*/15 * * * *" \  --name "Queue depth probe" \  --command "scripts/check-queue.sh" \  --command-cwd "/srv/app" \  --announce \  --channel telegram \  --to "-1001234567890"

--command <shell> は argv: ["sh", "-lc", <shell>] を保存します。シェル解析を行わず、正確な argv で実行するには --command-argv '["node","scripts/report.mjs"]' を使用します。オプションの --command-env KEY=VALUE（繰り返し指定可能）、--command-input、--timeout-seconds（デフォルトは 10 分）、--no-output-timeout-seconds、--output-max-bytes で、プロセス環境、標準入力、出力上限を制御します。

配信されるテキストはプロセス出力から生成されます。空でない標準出力が優先されます。標準出力が空で標準エラーが空でない場合は、標準エラーが配信されます。両方が存在する場合、Cron は小さな stdout:／stderr: ブロックを送信します。終了コード 0 は実行を ok として記録します。0 以外の終了、シグナル、タイムアウト、または無出力タイムアウトは error として記録され、失敗アラートをトリガーすることがあります。NO_REPLY のみを出力するコマンドでは、通常の Cron サイレントトークン抑制が適用され、チャットには何も投稿されません。

スクリプトペイロード

スクリプトペイロードは、会話エージェントのターンを開始せずに、トリガースクリプトと同じコードモード実行環境でヘッドレスに実行されます。作成または実行する前に cron.triggers.enabled を有効にしてください。この危険な自動化に対するゲートは、トリガースクリプトとスクリプトペイロードの両方に適用されます。スクリプトジョブがサポートするセッションターゲットは main と isolated のみです。

openclaw cron create "0 * * * *" \  --name "Hourly queue check" \  --script ./automation/check-queue.js \  --script-timeout-seconds 300 \  --script-tool-budget 50 \  --session isolated \  --announce

ファイルまたは標準入力から JavaScript を読み取るには --script <file|-> を使用します。タイムアウトのデフォルトは 300 秒、上限は 900 秒です。ツール予算のデフォルトは 50 回、上限は 200 回です。これらのペイロード予算は、より小さいトリガーゲート評価予算とは別です。

スクリプトは、次の任意フィールドを持つオブジェクトを返せます。

• notify: ジョブの announce、webhook、または none 配信モードを通じて配信されるテキストです。省略した場合は何も配信されません。main ジョブでは、テキストがシステムイベントになります。
• wake: "now" は、notify（または簡潔な完了イベント）をキューに追加した後、即時 Heartbeat を要求します。"next-heartbeat" は、次回の Heartbeat 用にイベントをキューに追加します。
• state: JSON 状態です。上限は 16 KB で、正常に実行された後にのみ永続化されます。次回の実行では、トリガースクリプトと同様に、凍結されたコピーが trigger.state として渡されます。この名前空間の永続化所有者は 1 つだけであるため、同じジョブでスクリプトペイロードと条件トリガーを組み合わせることはできません。
• nextCheck: "15m" などの期間です。ペーシングが有効なジョブでのみ有効で、エージェントターンの提案と同じペーシング制限を使用します。

例外、タイムアウト、ツール予算の枯渇、無効な結果、およびペーシングなしの nextCheck は、通常の Cron 実行エラーです。返された状態を永続化せず、実行履歴、バックオフ、失敗アラート処理の対象になります。

実行スタイル

配信と出力

チャンネル配信には --announce --channel telegram --to "-1001234567890" を使用します。Telegram フォーラムトピックには -1001234567890:topic:123 を使用します。OpenClaw は Telegram が所有する省略形 -1001234567890:123 も受け付けます。RPC／設定の直接呼び出し元は、delivery.threadId を文字列または数値として渡せます。Slack／Discord／Mattermost のターゲットでは、明示的なプレフィックス（channel:<id>、user:<id>）を使用します。Matrix のルーム ID は大文字と小文字を区別します。Matrix から取得した正確なルーム ID または room:!room:server 形式を使用してください。

アナウンス配信で channel: "last" を使用するか、channel を省略すると、Cron がセッション履歴または設定済みの単一チャンネルにフォールバックする前に、telegram:123 のようなプロバイダープレフィックス付きターゲットでチャンネルを選択できます。読み込まれた Plugin が通知するプレフィックスのみがプロバイダーセレクターです。delivery.channel を明示した場合、ターゲットプレフィックスは同じプロバイダーを指定しなければなりません。WhatsApp が Telegram ID を電話番号として解釈できるようにするのではなく、channel: "whatsapp" と to: "telegram:123" の組み合わせは拒否されます。ターゲット種別とサービスのプレフィックス（channel:<id>、user:<id>、imessage:<handle>、sms:<number>）は、プロバイダーセレクターではなく、引き続きチャンネルが所有するターゲット構文です。

分離ジョブでは、チャット配信は共有されます。チャットルートが利用可能な場合、--no-deliver であっても、エージェントは message ツールを使用できます。エージェントが設定済みまたは現在のターゲットへ送信すると、OpenClaw はフォールバックアナウンスをスキップします。それ以外の場合、announce、webhook、none が制御するのは、エージェントターン後にランナーが最終返信をどう処理するかだけです。

エージェントがアクティブなチャットから分離リマインダーを作成すると、OpenClaw は保持されたライブ配信ターゲットをフォールバックアナウンスのルートとして保存します。内部セッションキーは小文字の場合がありますが、現在のチャットコンテキストが利用可能な場合、プロバイダーの配信ターゲットがそれらのキーから再構築されることはありません。

暗黙のアナウンス配信では、設定済みのチャンネル許可リストを使用して、古いターゲットを検証し、ルーティングし直します。DM ペアリングストアの承認先は、フォールバック自動化の受信者にはなりません。スケジュール済みジョブから DM へ能動的に送信する必要がある場合は、delivery.to を設定するか、チャンネルの allowFrom エントリを設定します。

失敗通知

失敗通知は別の宛先パスに従います。

• cron.failureDestination は、失敗通知のグローバルデフォルトを設定します。
• job.delivery.failureDestination は、ジョブごとにこれをオーバーライドします。
• どちらも設定されておらず、ジョブがすでに announce 経由で配信している場合、失敗通知はその主要アナウンスターゲットにフォールバックします。
• delivery.failureDestination は、主要な配信モードが webhook でない限り、sessionTarget="isolated" ジョブでのみサポートされます。
• failureAlert.includeSkipped: true は、ジョブまたはグローバル Cron アラートポリシーで、繰り返し発生するスキップ実行のアラートを有効にします。スキップされた実行では、連続スキップ回数が別に記録されるため、実行エラーのバックオフには影響しません。
• openclaw cron edit は、ジョブごとのアラート調整項目として、--failure-alert/--no-failure-alert、--failure-alert-after <n>、--failure-alert-channel、--failure-alert-to、--failure-alert-cooldown、--failure-alert-include-skipped/--failure-alert-exclude-skipped、--failure-alert-mode、および --failure-alert-account-id を公開します。

出力言語

Cron ジョブは、チャンネル、ロケール、以前のメッセージから返信言語を推測しません。スケジュール済みのメッセージまたはテンプレートに言語規則を含めてください。

openclaw cron edit <jobId> \  --message "更新内容を要約してください。中国語で回答し、URL、コード、製品名は変更しないでください。"

テンプレートファイルでは、レンダリングされるプロンプトに言語指示を含め、ジョブが実行される前に {{language}} などのプレースホルダーが埋められていることを確認します。出力で言語が混在する場合は、「叙述テキストには中国語を使用し、技術用語は英語のままにしてください」のように規則を明示します。

CLI の例

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

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

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

openclaw cron create "0 18 * * 1-5" \  "Summarize today's deploys as JSON." \  --name "Deploy digest" \  --webhook "https://example.invalid/openclaw/cron"

openclaw cron create "*/15 * * * *" \  --name "Queue depth probe" \  --command "scripts/check-queue.sh" \  --command-cwd "/srv/app" \  --announce \  --channel telegram \  --to "-1001234567890"

ジョブの管理

# 有効なジョブを一覧表示openclaw cron list # 無効なジョブも含めるopenclaw cron list --all # 保存済みのジョブを1件JSONとして取得openclaw cron get <jobId> # 解決済みの配信ルートを含め、ジョブを1件表示openclaw cron show <jobId> # 削除せずに有効化／無効化openclaw cron enable <jobId>openclaw cron disable <jobId> # ジョブを編集openclaw cron edit <jobId> --message "更新されたプロンプト" --model "opus" # ジョブを今すぐ強制実行openclaw cron run <jobId> # ジョブを今すぐ強制実行し、最終ステータスまで待機openclaw cron run <jobId> --wait --wait-timeout 10m --poll-interval 2s # 実行期限に達している場合のみ実行openclaw cron run <jobId> --due # 実行履歴を表示openclaw cron runs --id <jobId> --limit 50 # 特定の実行を1件表示openclaw cron runs --id <jobId> --run-id <runId> # ジョブを削除openclaw cron remove <jobId> # エージェントの選択（マルチエージェント構成）openclaw cron create "0 6 * * *" "運用キューを確認" --name "運用確認" --session isolated --agent opsopenclaw cron edit <jobId> --clear-agent

セッションをアーカイブすると（Control UI、または operator-admin 呼び出し元からの sessions.patch { archived: true }）、そのセッションに関連付けられている有効な cron ジョブがすべて無効になります。対象は、そのセッションの isolated cron:<jobId> セッション、session:<key> ターゲット、または配信／ウェイク用の sessionKey レーンです。セッションを復元しても、それらのジョブは再度有効になりません。openclaw cron enable <jobId> を使用してください。有効な関連付け済みジョブがあるセッションには、Control UI のサイドバーに時計バッジが表示されます。

openclaw cron run <jobId> は手動実行をキューに追加した後に返ります。シャットダウンフック、メンテナンススクリプト、またはキューに入った実行が完了するまでブロックする必要があるその他の自動処理では、--wait を使用してください。返された runId をポーリングし（デフォルトのタイムアウトは 10m、ポーリング間隔は 2s）、ステータスが ok の場合は 0 で終了し、error、skipped、または待機タイムアウトの場合はゼロ以外で終了します。

エージェントの cron ツールは、cron(action: "list") から簡潔なジョブ概要（id、name、enabled、nextRunAtMs、scheduleKind、lastRunStatus）を返します。完全なジョブ定義を1件取得するには cron(action: "get", jobId: "...") を使用してください。Gateway を直接呼び出す場合は、cron.list に compact: true を渡せます。省略すると、配信プレビューを含む完全なレスポンスが維持されます。

openclaw cron create は openclaw cron add のエイリアスです。新しいジョブでは、位置引数のスケジュール（"0 9 * * 1"、"every 1h"、"20m"、または ISO タイムスタンプ）の後に、位置引数のエージェントプロンプトを指定できます。完了した実行ペイロードを HTTP エンドポイントへ POST するには、cron add|create または cron edit で --webhook <url> を使用してください。Webhook 配信とチャット配信フラグ（--announce、--channel、--to、--thread-id、--account）は併用できません。cron edit、--clear-channel、--clear-to、--clear-thread-id、--clear-account は、それらのルーティングフィールドを個別に解除します（それぞれ対応する設定フラグとの併用は拒否されます）。これは、ランナーのフォールバック配信のみを無効にする --no-deliver とは異なります。

Webhook

Gateway は、外部トリガー用の HTTP Webhook エンドポイントを公開できます。設定で有効にします：

{  hooks: {    enabled: true,    token: "shared-secret",    path: "/hooks",  },}

認証

すべてのリクエストで、次のいずれかのヘッダーを介してフックトークンを含める必要があります：

• Authorization: Bearer <token>（推奨）
• x-openclaw-token: <token>

クエリ文字列のトークンは拒否されます。

curl -X POST http://127.0.0.1:18789/hooks/wake \  -H 'Authorization: Bearer SECRET' \  -H 'Content-Type: application/json' \  -d '{"text":"新しいメールを受信しました","mode":"now"}'

curl -X POST http://127.0.0.1:18789/hooks/agent \  -H 'Authorization: Bearer SECRET' \  -H 'Content-Type: application/json' \  -d '{"message":"受信トレイを要約","name":"メール","model":"openai/gpt-5.6-sol"}'

Gmail PubSub 連携

Google PubSub を介して Gmail の受信トリガーを OpenClaw に接続します。

ウィザードによるセットアップ（推奨）

openclaw webhooks gmail setup --account openclaw@gmail.com

これにより hooks.gmail 設定が書き込まれ、Gmail プリセットが有効になり、プッシュエンドポイントのデフォルトとして Tailscale Funnel（--tailscale funnel|serve|off）が使用されます。

Gateway の自動起動

hooks.enabled=true および hooks.gmail.account が設定されている場合、Gateway は起動時に gog gmail watch serve を開始し、監視を自動更新します。オプトアウトするには OPENCLAW_SKIP_GMAIL_WATCHER=1 を設定してください。

手動による1回限りのセットアップ

gcloud auth logingcloud config set project <project-id>gcloud services enable gmail.googleapis.com pubsub.googleapis.com

gcloud pubsub topics create gog-gmail-watchgcloud pubsub topics add-iam-policy-binding gog-gmail-watch \  --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \  --role=roles/pubsub.publisher

gog gmail watch start \  --account openclaw@gmail.com \  --label INBOX \  --topic projects/<project-id>/topics/gog-gmail-watch

Gmail のモデルオーバーライド

{  hooks: {    gmail: {      model: "openai/gpt-5.6-sol",      thinking: "high",    },  },}

信頼できない受信トレイには、プロバイダーで利用可能な最新世代かつ最上位のモデルを使用してください。上記の値は例です。モデルは設定済みのカタログと許可リストに存在する必要があります。

設定

{  cron: {    enabled: true,    store: "~/.openclaw/cron/jobs.json",    triggers: {      enabled: false,    },    webhookToken: "replace-with-dedicated-webhook-token",    sessionRetention: "24h",  },}

webhookToken は、cron の Webhook POST で Authorization: Bearer <token> として送信されます。

cron.store は論理ストアキーおよび doctor の移行パスであり、手作業で編集する実体のある JSON ファイルではありません。ジョブデータは SQLite に保存されます。変更には CLI または Gateway API を使用してください。

cron を無効にするには、cron.enabled: false または OPENCLAW_SKIP_CRON=1 を使用します。

トラブルシューティング

コマンドの確認手順

openclaw statusopenclaw gateway statusopenclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --followopenclaw doctor

関連項目

• 自動化 — すべての自動化メカニズムの概要
• バックグラウンドタスク — Cron 実行のタスク台帳
• Heartbeat — メインセッションの定期ターン
• タイムゾーン — タイムゾーンの設定