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

Cron は Gateway の組み込みスケジューラです。ジョブを永続化し、適切な時刻にエージェントを起動し、出力をチャットチャンネルまたは webhook エンドポイントへ返すことができます。

クイックスタート

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 listopenclaw cron get <job-id>openclaw cron show <job-id>

openclaw cron runs --id <job-id>

cron の仕組み

• Cron は Gateway プロセスの内部で実行されます（モデルの内部ではありません）。
• ジョブ定義は ~/.openclaw/cron/jobs.json に永続化されるため、再起動してもスケジュールは失われません。
• ランタイム実行状態は、その隣の ~/.openclaw/cron/jobs-state.json に永続化されます。cron 定義を git で追跡する場合は、jobs.json を追跡し、jobs-state.json を gitignore してください。
• 分割後、古い OpenClaw バージョンは jobs.json を読み取れますが、ランタイムフィールドが現在は jobs-state.json にあるため、ジョブを新規として扱う場合があります。
• Gateway の実行中または停止中に jobs.json が編集されると、OpenClaw は変更されたスケジュールフィールドを保留中のランタイムスロットメタデータと比較し、古い nextRunAtMs 値をクリアします。純粋な整形やキー順序だけの書き換えでは、保留中のスロットは保持されます。
• すべての cron 実行は バックグラウンドタスク レコードを作成します。
• Gateway 起動時、期限を過ぎた分離エージェントターンのジョブは即座に再生されず、チャンネル接続ウィンドウの外へ再スケジュールされるため、Discord/Telegram の起動とネイティブコマンドのセットアップは再起動後も応答性を保ちます。
• 1 回限りのジョブ（--at）は、デフォルトで成功後に自動削除されます。
• 分離 cron 実行は、実行完了時に cron:<jobId> セッション用に追跡されているブラウザタブやプロセスをベストエフォートで閉じるため、切り離されたブラウザ自動化が孤立プロセスを残しません。
• 狭い cron 自己クリーンアップ権限を受け取った分離 cron 実行は、スケジューラステータス、自分の現在のジョブに自己フィルタされたリスト、そのジョブの実行履歴を引き続き読み取れるため、ステータスや Heartbeat チェックは、より広い cron 変更権限を得ずに自分自身のスケジュールを検査できます。
• 分離 cron 実行は、古い確認応答にも対処します。最初の結果が単なる暫定ステータス更新（on it、pulling everything together、および同様のヒント）であり、最終回答にまだ責任を持つ子孫サブエージェント実行がない場合、OpenClaw は配信前に実際の結果を 1 回だけ再プロンプトします。
• 分離 cron 実行は、まず埋め込み実行からの構造化された実行拒否メタデータを優先し、その後 SYSTEM_RUN_DENIED や INVALID_REQUEST などの既知の最終サマリー/出力マーカーにフォールバックするため、ブロックされたコマンドが成功した実行として報告されません。
• 分離 cron 実行は、返信ペイロードが生成されない場合でも、実行レベルのエージェント失敗をジョブエラーとして扱うため、モデル/プロバイダーの失敗は、ジョブを成功としてクリアする代わりにエラーカウンターを増やし、失敗通知をトリガーします。
• 分離エージェントターンジョブが timeoutSeconds に達すると、cron は基盤となるエージェント実行を中止し、短いクリーンアップウィンドウを与えます。実行が排出されない場合、Gateway 所有のクリーンアップが、その実行のセッション所有権を強制的にクリアしてから cron がタイムアウトを記録するため、キューに入ったチャット作業が古い処理中セッションの背後に残されません。
• 分離エージェントターンがランナー開始前または最初のモデル呼び出し前に停止した場合、cron は setup timed out before runner start や stalled before first model call (last phase: context-engine) などのフェーズ固有のタイムアウトを記録します。これらのウォッチドッグは、外部 CLI プロセスが実際に起動される前の埋め込みプロバイダーと CLI ベースのプロバイダーを対象にし、長い timeoutSeconds 値とは独立して上限が設定されるため、コールドスタート/認証/コンテキストの失敗は、ジョブ全体の予算を待たずに素早く表面化します。

スケジュールタイプ

タイムゾーンのないタイムスタンプは UTC として扱われます。ローカルの壁時計時刻でスケジュールするには --tz America/New_York を追加してください。

毎時 0 分の繰り返し式は、負荷スパイクを減らすために最大 5 分まで自動的に分散されます。正確なタイミングを強制するには --exact を使用し、明示的なウィンドウには --stagger 30s を使用します。

day-of-month と day-of-week は OR ロジックを使用する

Cron 式は croner によって解析されます。day-of-month フィールドと day-of-week フィールドの両方が非ワイルドカードの場合、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

これは 1 か月あたり 0〜1 回ではなく、約 5〜6 回発火します。OpenClaw はここで Croner のデフォルトの OR 動作を使用します。両方の条件を必須にするには、Croner の + day-of-week 修飾子（0 9 15 * +1）を使用するか、一方のフィールドでスケジュールし、もう一方をジョブのプロンプトまたはコマンド内でガードしてください。

実行スタイル

分離ジョブのペイロードオプション

--model は、選択された許可済みモデルをそのジョブのプライマリモデルとして使用します。これはチャットセッションの /model オーバーライドとは異なります。ジョブのプライマリが失敗した場合でも、構成されたフォールバックチェーンは引き続き適用されます。要求されたモデルが許可されていない、または解決できない場合、cron はジョブのエージェント/デフォルトモデル選択へ黙ってフォールバックするのではなく、明示的な検証エラーで実行を失敗させます。

Cron ジョブはペイロードレベルの fallbacks も保持できます。存在する場合、そのリストはジョブ用に構成されたフォールバックチェーンを置き換えます。選択されたモデルだけを試す厳格な cron 実行にしたい場合は、ジョブペイロード/API で fallbacks: [] を使用してください。ジョブに --model があり、ペイロードにも構成にもフォールバックがない場合、OpenClaw は明示的な空のフォールバックオーバーライドを渡すため、エージェントのプライマリが隠れた追加の再試行ターゲットとして追加されることはありません。

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

1. Gmail フックモデルオーバーライド（実行が Gmail から来ており、そのオーバーライドが許可されている場合）
2. ジョブごとのペイロード model
3. ユーザーが選択して保存した cron セッションモデルオーバーライド
4. エージェント/デフォルトモデル選択

高速モードも、解決されたライブ選択に従います。選択されたモデル構成に params.fastMode がある場合、分離 cron はデフォルトでそれを使用します。保存されたセッションの fastMode オーバーライドは、どちらの方向でも構成より優先されます。

分離実行がライブのモデル切り替えハンドオフに達した場合、cron は切り替え後のプロバイダー/モデルで再試行し、再試行前にそのライブ選択をアクティブな実行に永続化します。切り替えに新しい認証プロファイルも含まれる場合、cron はその認証プロファイルのオーバーライドもアクティブな実行に永続化します。再試行には上限があります。最初の試行に加えて 2 回の切り替え再試行後、cron は無限ループする代わりに中止します。

隔離されたCron実行がエージェントランナーに入る前に、OpenClawは、設定済みの api: "ollama" および api: "openai-completions" プロバイダーのうち、baseUrl がループバック、プライベートネットワーク、または .local である到達可能なローカルプロバイダーエンドポイントを確認します。そのエンドポイントがダウンしている場合、モデル呼び出しを開始する代わりに、明確なプロバイダー/モデルエラー付きで実行が skipped として記録されます。エンドポイント結果は5分間キャッシュされるため、同じ停止中のローカル Ollama、vLLM、SGLang、または LM Studio サーバーを使う多数の期限到来ジョブは、リクエストストームを作るのではなく、1つの小さなプローブを共有します。プロバイダー事前確認でスキップされた実行は、実行エラーのバックオフを増やしません。スキップ通知を繰り返し受け取りたい場合は、failureAlert.includeSkipped を有効にしてください。

配信と出力

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

announce 配信で 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 をスキップします。それ以外の場合、announce、webhook、none は、エージェントターン後に最終返信をランナーがどう扱うかだけを制御します。

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

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

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

• cron.failureDestination は失敗通知のグローバルデフォルトを設定します。
• job.delivery.failureDestination はジョブごとにそれを上書きします。
• どちらも設定されておらず、ジョブがすでに announce で配信している場合、失敗通知はそのプライマリ announce ターゲットへフォールバックするようになりました。
• delivery.failureDestination は、プライマリ配信モードが webhook でない限り、sessionTarget="isolated" ジョブでのみサポートされます。
• failureAlert.includeSkipped: true は、ジョブまたはグローバル cron アラートポリシーを、スキップ実行アラートの繰り返し対象にします。スキップ実行は別の連続スキップカウンターを保持するため、実行エラーのバックオフには影響しません。

CLI の例

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

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"

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

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.4"}'

Gmail PubSub 連携

Google PubSub 経由で Gmail 受信トレイトリガーを OpenClaw に接続します。

ウィザード設定（推奨）

openclaw webhooks gmail setup --account [email protected]

これは hooks.gmail 設定を書き込み、Gmail プリセットを有効化し、プッシュエンドポイントに Tailscale Funnel を使用します。

Gateway 自動起動

hooks.enabled=true かつ hooks.gmail.account が設定されている場合、Gateway は起動時に gog gmail watch serve を開始し、watch を自動更新します。無効にするには OPENCLAW_SKIP_GMAIL_WATCHER=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:[email protected] \  --role=roles/pubsub.publisher

gog gmail watch start \  --account [email protected] \  --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",    },  },}

ジョブの管理

# List all jobsopenclaw cron list # Get one stored job as JSONopenclaw cron get <jobId> # Show one job, including resolved delivery routeopenclaw cron show <jobId> # Edit a jobopenclaw cron edit <jobId> --message "Updated prompt" --model "opus" # Force run a job nowopenclaw cron run <jobId> # Run only if dueopenclaw cron run <jobId> --due # View run historyopenclaw cron runs --id <jobId> --limit 50 # Delete a jobopenclaw cron remove <jobId> # Agent selection (multi-agent setups)openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent opsopenclaw cron edit <jobId> --clear-agent

設定

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

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

ランタイム状態サイドカーは cron.store から導出されます。~/clawd/cron/jobs.json のような .json ストアは ~/clawd/cron/jobs-state.json を使用し、.json サフィックスのないストアパスでは -state.json が追加されます。

jobs.json を手動編集する場合は、jobs-state.json をソース管理から外してください。OpenClaw はそのサイドカーを、保留スロット、アクティブマーカー、最終実行メタデータ、外部で編集されたジョブに新しい nextRunAtMs が必要なタイミングをスケジューラーへ伝えるスケジュール ID に使用します。

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