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

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 分です。
• Gateway の起動時、期限を過ぎた分離エージェントターンジョブは即座に再実行されるのではなく、再スケジュールされます。これにより、モデル／ツールのブートストラップ処理がチャンネル接続期間外に保たれます。
• システム cron または別の外部スケジューラから openclaw agent を実行する場合、CLI がすでに SIGTERM/SIGINT を処理していても、ハードキルへのエスカレーションでラップしてください。Gateway を介した実行では、受理済みの実行を中止するよう Gateway に要求します。ローカル実行および埋め込みフォールバック実行にも同じ中止シグナルが送られます。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 スケジュールのみ）。

日と曜日には 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 スケジュールにヘッドレス条件スクリプトを追加します。Cron はジョブの実行時刻になるとスクリプトを評価し、スクリプトが fire: true を返した場合にのみ通常のペイロードを実行します。

{  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 として利用できます。永続化するには、新しい state 値を返します。状態の上限は 16 KB です。発火結果に message が含まれる場合、cron は実行前にそれをシステムイベントのテキストまたはエージェントターンのメッセージへ追加します。once: true は、最初に発火したペイロードが正常に完了した後、ジョブを無効にします。

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

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

openclaw cron add \  --name "PR CI ウォッチャー" \  --every 30s \  --trigger-script ./watch-pr-ci.js \  --message "CI 状態の変化に対応してください" \  --session isolated

ペイロード

各ジョブは、フラグで選択されたペイロードの種類を正確に 1 つ持ちます。

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

--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 が loopback、プライベートネットワーク、または .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 として記録されます。ゼロ以外の終了、シグナル、タイムアウト、または無出力タイムアウトの場合は error として記録され、失敗警告が発生することがあります。NO_REPLY だけを出力するコマンドには、通常の 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 は大文字と小文字を区別します。正確なルーム ID または Matrix の room:!room:server 形式を使用してください。

通知配信で channel: "last" を使用するか、channel を省略した場合、telegram:123 のようなプロバイダープレフィックス付きの対象によってチャンネルを選択できます。その後、Cron はセッション履歴または設定された単一のチャンネルへフォールバックします。読み込まれた 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 "カレンダー確認" \  --at "20m" \  --session main \  --system-event "次の Heartbeat：カレンダーを確認してください。" \  --wake now

openclaw cron create "0 7 * * *" \  "夜間の更新を要約してください。" \  --name "朝の概要" \  --tz "America/Los_Angeles" \  --session isolated \  --announce \  --channel slack \  --to "channel:C1234567890"

openclaw cron add \  --name "詳細分析" \  --cron "0 6 * * 1" \  --tz "America/Los_Angeles" \  --session isolated \  --message "プロジェクトの進捗を毎週詳細に分析してください。" \  --model "opus" \  --thinking high \  --announce

openclaw cron create "0 18 * * 1-5" \  "今日のデプロイを JSON 形式で要約してください。" \  --name "デプロイ概要" \  --webhook "https://example.invalid/openclaw/cron"

openclaw cron create "*/15 * * * *" \  --name "キュー深度の検査" \  --command "scripts/check-queue.sh" \  --command-cwd "/srv/app" \  --announce \  --channel telegram \  --to "-1001234567890"

ジョブの管理

# すべてのジョブを一覧表示openclaw cron list # 保存されたジョブを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、またはオペレーター管理者の呼び出し元による sessions.patch { archived: true }）、そのセッションに関連付けられた有効な Cron ジョブがすべて無効になります。対象には、その分離された 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|serve|off）のデフォルトとして Tailscale Funnel を使用します。

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",    maxConcurrentRuns: 8,    triggers: {      enabled: false,      minIntervalMs: 30000,    },    retry: {      maxAttempts: 3,      backoffMs: [30000, 60000, 300000],      retryOn: ["rate_limit", "overloaded", "network", "timeout", "server_error"],    },    webhookToken: "replace-with-dedicated-webhook-token",    sessionRetention: "24h",  },}

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