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

Cron は Gateway の組み込みスケジューラーです。ジョブを永続化し、適切なタイミングでエージェントを起動し、出力をチャットチャンネル、Webhook、またはどこにも配信しないようにできます。

クイックスタート

openclaw cron create "2027-02-01T16:00:00Z" \  --name "Reminder" \  --session main \  --system-event "Reminder: check the cron docs draft" \  --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 の各実行は バックグラウンドタスク レコードを作成します。
• ワンショットジョブ (--at) は、デフォルトでは成功後に自動削除されます。保持するには --keep-after-run を渡します。
• 実行ごとの実時間予算: 設定されている場合は --timeout-seconds。それ以外の場合、分離/デタッチされたエージェントターンジョブは、基盤となるエージェントターンのタイムアウト (agents.defaults.timeoutSeconds、デフォルト 48 時間) が適用される前に、cron 独自の 60 分ウォッチドッグで制限されます。コマンドジョブのデフォルトは 10 分です。
• Gateway 起動時、期限を過ぎた分離エージェントターンジョブは即時再生されず、再スケジュールされます。これにより、モデル/ツールのブートストラップ作業がチャンネル接続ウィンドウに入りません。
• システム cron や別の外部スケジューラーから openclaw agent を駆動する場合、CLI がすでに SIGTERM/SIGINT を処理していても、ハードキルへのエスカレーションでラップしてください。Gateway バックの実行では、受理済み実行の中止を Gateway に要求します。ローカル実行と組み込みフォールバック実行にも同じ中止シグナルが送られます。GNU timeout では、単純な timeout 600 ... よりも timeout -k 60 600 openclaw agent ... を推奨します。-k 値は、プロセスが時間内に終了処理できない場合のバックストップです。systemd ユニットでは、最終的な kill の前に猶予ウィンドウ (TimeoutStopSec) 付きの SIGTERM 停止シグナルを使用します。元の Gateway 実行がまだアクティブな間に --run-id を再利用すると、2 つ目の実行を開始せず、重複は実行中として報告されます。

スケジュール種別

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

毎時ちょうどに繰り返す式 (分が 0 で、時フィールドがワイルドカード) は、負荷スパイクを減らすため最大 5 分まで自動的にずらされます。正確なタイミングを強制するには --exact を使用し、明示的なウィンドウには --stagger 30s を使用します (cron スケジュールのみ)。

日付と曜日は OR ロジックを使用します

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

# Intended: "9 AM on the 15th, only if it's a Monday"# Actual:   "9 AM on every 15th, AND 9 AM on every Monday"0 9 15 * 1

これは月に 0〜1 回ではなく、おおよそ月に 5〜6 回発火します。両方の条件を必須にするには、croner の + 曜日修飾子 (0 9 15 * +1) を使用するか、一方のフィールドでスケジュールし、もう一方をジョブのプロンプトまたはコマンドでガードします。

ペイロード

すべてのジョブは、フラグで選択されるちょうど 1 つのペイロード種別を持ちます。

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

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

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

1. ジョブごとのペイロード model (明示的設定。許可されていないモデルは実行に失敗します)
2. Gmail フックのモデルオーバーライド (実行が Gmail 由来で、そのオーバーライドが許可されている場合のみ)
3. ユーザーが選択した保存済み cron セッションのモデルオーバーライド
4. エージェント/デフォルトのモデル選択

高速モードは、解決されたライブ選択に従います。選択されたモデル設定に params.fastMode がある場合、分離 cron はデフォルトでそれを使用します。保存済みセッションの fastMode オーバーライド (次にエージェントの fastModeDefault) は、どちらの方向でもモデル設定より優先されます。自動モードはモデルの params.fastAutoOnSeconds カットオフを使用し、デフォルトは 60 秒です。

実行がライブのモデル切り替えハンドオフに達した場合、cron は切り替え後のプロバイダー/モデルで再試行し、その選択 (および新しい auth プロファイル) をアクティブな実行に永続化します。再試行には上限があります。最初の試行に加えて 2 回の切り替え再試行の後、cron はループせずに中止します。

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

コマンドペイロード

コマンドペイロードは、モデルバックのターンを開始せずに、Gateway スケジューラー内で決定的なスクリプトを実行します。Gateway ホスト上で実行され、stdout/stderr をキャプチャし、実行を 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 は、プロセス環境、stdin、出力の上限を制御します。

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

実行スタイル

配信と出力

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

告知配信で channel: "last" を使用するか channel を省略した場合、telegram:123 のようなプロバイダー接頭辞付きターゲットは、cron がセッション履歴または単一の設定済みチャンネルへフォールバックする前にチャンネルを選択できます。読み込まれた plugin によって広告されている接頭辞だけがプロバイダーセレクターです。delivery.channel が明示されている場合、ターゲット接頭辞は同じプロバイダーを指す必要があります。channel: "whatsapp" と to: "telegram:123" の組み合わせは、WhatsApp が Telegram ID を電話番号として解釈することを許さず、拒否されます。ターゲット種別とサービス接頭辞（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 "Summarize the updates. Respond in Chinese; keep URLs, code, and product names unchanged."

テンプレートファイルでは、レンダリングされたプロンプトに言語指示を保持し、ジョブ実行前に {{language}} などのプレースホルダーが埋まっていることを確認してください。出力に複数の言語が混在する場合は、たとえば「Use Chinese for narrative text and keep technical terms in English.」のように、ルールを明示してください。

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"

ジョブの管理

# List all jobsopenclaw cron list # Get one stored job as JSONopenclaw cron get <jobId> # Show one job, including resolved delivery routeopenclaw cron show <jobId> # Enable/disable without deletingopenclaw cron enable <jobId>openclaw cron disable <jobId> # Edit a jobopenclaw cron edit <jobId> --message "Updated prompt" --model "opus" # Force run a job nowopenclaw cron run <jobId> # Force run a job now and wait for its terminal statusopenclaw cron run <jobId> --wait --wait-timeout 10m --poll-interval 2s # Run only if dueopenclaw cron run <jobId> --due # View run historyopenclaw cron runs --id <jobId> --limit 50 # View one exact runopenclaw cron runs --id <jobId> --run-id <runId> # Delete a jobopenclaw cron remove <jobId> # Agent selection (multi-agent setups)openclaw cron create "0 6 * * *" "Check ops queue" --name "Ops sweep" --session isolated --agent opsopenclaw cron edit <jobId> --clear-agent

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

エージェントの 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 とは異なり、--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":"New email received","mode":"now"}'

curl -X POST http://127.0.0.1:18789/hooks/agent \  -H 'Authorization: Bearer SECRET' \  -H 'Content-Type: application/json' \  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.5"}'

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 を開始し、watch を自動更新します。オプトアウトするには 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: "openrouter/meta-llama/llama-3.3-70b-instruct:free",      thinking: "off",    },  },}

設定

{  cron: {    enabled: true,    store: "~/.openclaw/cron/jobs.json",    maxConcurrentRuns: 8,    retry: {      maxAttempts: 3,      backoffMs: [30000, 60000, 300000],      retryOn: ["rate_limit", "overloaded", "network", "timeout", "server_error"],    },    webhookToken: "replace-with-dedicated-webhook-token",    sessionRetention: "24h",    runLog: { maxBytes: "2mb", keepLines: 2000 },  },}

上記の retry 値はデフォルトです。30s/60s/5m のバックオフで最大 3 回リトライし、5 つすべての一時的カテゴリをリトライします。webhookToken は、cron Webhook の POST で Authorization: Bearer <token> として送信されます。

maxConcurrentRuns は、スケジュールされた cron ディスパッチと分離されたエージェントターン実行の両方を制限し、デフォルトは 8 です。分離された cron エージェントターンは、内部的にキュー専用の cron-nested 実行レーンを使用するため、この値を引き上げると、外側の cron ラッパーだけを開始するのではなく、独立した cron LLM 実行を並列に進められます。共有の非 cron nested レーンは、この設定では拡張されません。

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 — 定期的なメインセッションターン
• タイムゾーン — タイムゾーン設定