OpenClaw Cronジョブ設定ガイド：タスクを自動化する

快速開始

OpenClaw の cron 機能を使えば、定期的なタスクやリマインダーを簡単に自動化できます。以下のコマンドで、タスクの追加や実行状況の確認が可能です。

# Add a one-shot reminder
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

# Check your jobs
openclaw cron list

# See run history
openclaw cron runs --id <job-id>

cron の仕組み

cron は Gateway プロセス内で動作し、タスクのスケジュール管理を行います。

cron は Gateway プロセス内で実行され、モデル内部では動作しません。
ジョブ定義は ~/.openclaw/cron/jobs.json に保存されるため、再起動してもスケジュールが失われることはありません。
実行時の状態は ~/.openclaw/cron/jobs-state.json に保存されます。Git で定義を管理する場合は jobs.json を追跡し、jobs-state.json は gitignore に追加してください。
バージョンアップ後、古い OpenClaw バージョンでも jobs.json を読み込めますが、実行時フィールドが jobs-state.json に移行しているため、ジョブが新規として扱われる場合があります。
すべての cron 実行は background task レコードを作成します。
--at を使用した単発ジョブは、デフォルトで成功後に自動削除されます。
分離された cron 実行は、完了時にその cron:<jobId> セッションに関連付けられたブラウザタブやプロセスを可能な限り終了させるため、自動化プロセスが放置されることはありません。
分離された cron 実行は、古い応答の誤検知を防ぐガード機能も備えています。最初の結果が中間ステータス（「処理中」など）で、最終的な回答を出すサブエージェントが他に存在しない場合、OpenClaw は結果を配信する前に再度確認を行います。

cron のタスク調整はランタイムが管理します。アクティブな cron タスクは、ランタイムがそのジョブを「実行中」と認識している限り維持されます。ランタイムがジョブの所有権を放棄し、5分間の猶予期間が過ぎると、メンテナンスプロセスによってタスクが lost とマークされます。

スケジュールタイプ

種類	CLI flag	説明
`at`	`--at`	単発のタイムスタンプ（ISO 8601 または `20m` のような相対指定）
`every`	`--every`	固定間隔
`cron`	`--cron`	5フィールドまたは6フィールドの cron 式（オプションで `--tz` を指定可能）

タイムスタンプにタイムゾーンが含まれていない場合は UTC として扱われます。ローカル時間を使用したい場合は --tz America/New_York のように指定してください。

毎時0分に実行されるような定期タスクは、負荷の集中を避けるため最大5分間ずらして実行されます。正確なタイミングが必要な場合は --exact を、明示的なウィンドウを指定したい場合は --stagger 30s を使用してください。

日付と曜日の OR ロジック

cron 式は 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回ではなく月に5〜6回実行されることになります。OpenClaw は Croner のデフォルトである OR 動作を採用しています。両方の条件を満たす必要がある場合は、Croner の曜日修飾子 + を使用する（0 9 15 * +1）か、片方のフィールドでスケジュールし、もう片方をジョブのプロンプトやコマンド内で制御してください。

実行スタイル

スタイル	`--session` 値	実行場所	最適な用途
Main session	`main`	次のハートビート時	リマインダー、システムイベント
Isolated	`isolated`	専用の `cron:<jobId>`	レポート、バックグラウンド処理
Current session	`current`	作成時にバインド	コンテキストを維持する定期作業
Custom session	`session:custom-id`	永続的な名前付きセッション	履歴を積み上げるワークフロー

Main session ジョブはシステムイベントをエンキューし、必要に応じてハートビートを起動します（--wake now または --wake next-heartbeat）。Isolated ジョブは、新しいセッションで専用のエージェントターンを実行します。Custom sessions (session:xxx) は実行間でコンテキストを保持するため、過去の要約に基づいた日次ミーティングのようなワークフローに適しています。

分離されたジョブの場合、ランタイムの終了処理には、その cron セッションで使用されたブラウザのクリーンアップが含まれます。クリーンアップに失敗しても、cron の結果自体は優先されます。

分離された cron がサブエージェントを制御する場合、配信時には古い親の中間テキストよりも最終的な出力が優先されます。サブエージェントがまだ実行中の場合、OpenClaw は親の中間更新を抑制します。

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

--message: プロンプトテキスト（分離ジョブでは必須）
--model / --thinking: モデルと推論レベルの上書き
--light-context: ワークスペースのブートストラップファイル注入をスキップ
--tools exec,read: ジョブが使用できるツールを制限

--model はそのジョブで許可されたモデルを使用します。指定されたモデルが許可されていない場合、cron は警告をログに記録し、エージェントのデフォルトモデル選択にフォールバックします。

分離ジョブにおけるモデル選択の優先順位は以下の通りです：

Gmail フックのモデル上書き（Gmail からの実行で、その上書きが許可されている場合）
ジョブごとのペイロード model
保存された cron セッションのモデル上書き
エージェント/デフォルトのモデル選択

Fast モードも現在のライブ選択に従います。選択されたモデル設定に params.fastMode がある場合、分離 cron はデフォルトでそれを使用します。保存されたセッションの fastMode 上書きは、設定よりも優先されます。

分離された実行中にライブモデルの切り替えが発生した場合、cron は切り替え後のプロバイダー/モデルで再試行し、その選択を保存します。切り替え時に新しい認証プロファイルが必要な場合、cron はその認証プロファイルの上書きも保存します。再試行回数は制限されており、最初の試行と2回の切り替え再試行の後、cron は無限ループを避けるために中止されます。

配信と出力

タスクの実行結果をどのように受け取るか、その配信方法を制御することは非常に重要です。OpenClaw の配信設定では、実行結果の通知先や形式を柔軟に指定できます。

モード	動作内容
`announce`	ターゲットチャンネルへ要約を配信（isolatedモードのデフォルト）
`webhook`	完了イベントのペイロードを特定のURLへPOST送信
`none`	内部処理のみ、配信は行わない

チャンネルへの配信を行うには、—announce —channel telegram —to “-1001234567890” のように指定します。Telegramのフォーラムトピックを利用する場合は -1001234567890:topic:123 と記述してください。Slack、Discord、Mattermostをターゲットにする際は、channel:<id> や user:<id> といった明示的なプレフィックスが必要です。

cronで管理されるisolatedジョブの場合、ランナーが最終的な配信パスを制御します。エージェントはプレーンテキストの要約を返すよう促され、その要約が announce、webhook を通じて送信されるか、none として内部に保持されます。—no-deliver オプションを使用すると、エージェントに配信を委ねず、実行結果を内部に留めます。

もし元のタスクで外部の受信者へのメッセージ送信が明示されている場合、エージェントは直接送信を試みるのではなく、誰に対してどこへ送るべきかをその出力内に記録するようにしてください。

失敗時の通知は、通常の配信とは別の経路をたどります。

cron.failureDestination は、失敗通知のグローバルなデフォルト値を設定します。
job.delivery.failureDestination は、ジョブごとにその設定を上書きします。
いずれも設定されておらず、ジョブがすでに announce を通じて配信を行っている場合、失敗通知はプライマリの配信ターゲットへフォールバックされます。
delivery.failureDestination は、プライマリの配信モードが webhook である場合を除き、sessionTarget=“isolated” のジョブでのみサポートされます。

CLI の使用例

OpenClaw のCLIを活用して、タスクのスケジュールや配信設定を効率的に行うための具体的なコマンド例を紹介します。

メインセッションでのワンショットリマインダーの設定例です。

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

配信設定を含めた、定期的なisolatedジョブの設定例です。

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"

モデルと思考プロセスの上書き設定を含めた、isolatedジョブの設定例です。

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

Webhooks

Gatewayは、外部からのトリガーを受け取るためにHTTP webhookエンドポイントを公開できます。設定ファイルで以下のように有効化してください。

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

認証

すべてのリクエストには、ヘッダーを通じてwebhookトークンを含める必要があります。

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

クエリ文字列によるトークン指定は拒否されます。

POST /hooks/wake

メインセッションに対してシステムイベントをエンキューします。

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

text (必須): イベントの説明
mode (任意): now （デフォルト）または next-heartbeat

POST /hooks/agent

隔離されたエージェントのターンを実行します。

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-mini"}'

フィールド: message (必須), name, agentId, wakeMode, deliver, channel, to, model, thinking, timeoutSeconds。

マップされたフック (POST /hooks/<name>)

カスタムフック名は、設定内の hooks.mappings を通じて解決されます。マッピングを使用すると、テンプレートやコード変換によって、任意のペイロードを wake または agent アクションに変換できます。

セキュリティ

webhookエンドポイントは、ループバック、Tailnet、または信頼できるリバースプロキシの背後に配置してください。
専用のフックトークンを使用し、Gatewayの認証トークンを再利用しないでください。
hooks.path は専用のサブパスに設定してください。/ は拒否されます。
hooks.allowedAgentIds を設定して、明示的な agentId ルーティングを制限してください。
呼び出し元がセッションを選択する必要がない限り、hooks.allowRequestSessionKey=false を維持してください。
hooks.allowRequestSessionKey を有効にする場合は、hooks.allowedSessionKeyPrefixes も設定して、許可されるセッションキーの形式を制限してください。
フックのペイロードは、デフォルトで安全境界によってラップされます。

Gmail PubSub integration

Google PubSubを使用して、Gmailの受信トレイのトリガーをOpenClawに連携させます。

前提条件: gcloud CLI、gog (gogcli)、OpenClawのwebhook有効化、およびパブリックHTTPSエンドポイント用のTailscale。

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

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

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

Gatewayの自動起動

hooks.enabled=true かつ hooks.gmail.account が設定されている場合、Gatewayは起動時に gog gmail watch serve を開始し、監視を自動更新します。これを無効にするには OPENCLAW_SKIP_GMAIL_WATCHER=1 を設定してください。

手動による初回セットアップ

gog が使用するOAuthクライアントを所有するGCPプロジェクトを選択します。

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

トピックを作成し、Gmailのプッシュアクセス権限を付与します。

gcloud pubsub topics create gog-gmail-watch
gcloud 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",
    },
  },
}

ジョブの管理

OpenClawのcron機能を使用すると、定期的なタスクを効率的に管理できます。以下のコマンドを使用して、ジョブの作成や編集、実行状況の確認を行ってください。

ジョブの一覧を表示する
Terminal window
```
# List all jobs
openclaw cron list
```

特定のジョブの内容を編集する

# Edit a job
openclaw cron edit <jobId> --message "Updated prompt" --model "opus"

ジョブを今すぐ強制実行する
Terminal window
```
# Force run a job now
openclaw cron run <jobId>
```
実行予定時刻が来ている場合のみ実行する
Terminal window
```
# Run only if due
openclaw cron run <jobId> --due
```

ジョブの実行履歴を確認する

# View run history
openclaw cron runs --id <jobId> --limit 50

ジョブを削除する

# Delete a job
openclaw cron remove <jobId>

マルチエージェント環境でのエージェント選択

# List all jobs
openclaw cron list

# Edit a job
openclaw cron edit <jobId> --message "Updated prompt" --model "opus"

# Force run a job now
openclaw cron run <jobId>

# Run only if due
openclaw cron run <jobId> --due

# View run history
openclaw cron runs --id <jobId> --limit 50

# Delete a job
openclaw cron remove <jobId>

# Agent selection (multi-agent setups)
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
openclaw cron edit <jobId> --clear-agent

モデルのオーバーライドに関する注意点：

openclaw cron add|edit --model ... を実行すると、そのジョブで選択されたモデルが変更されます。
指定したモデルが許可されている場合、そのプロバイダーやモデルがisolatedエージェントの実行に使用されます。
許可されていないモデルが指定された場合、cronは警告を表示し、ジョブのエージェントまたはデフォルトのモデル設定にフォールバックします。
設定済みのフォールバックチェーンは引き続き有効ですが、ジョブごとの明示的なフォールバックリストを指定せずに --model で上書きした場合、エージェントのプライマリモデルへのサイレントな再試行ターゲットとしては機能しなくなります。

設定

OpenClawのcron設定は、以下のJSON形式で定義します。システム全体の動作やリトライポリシーを細かく調整することが可能です。

{
  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 },
  },
}

ランタイム状態を保持するサイドカーファイルは cron.store から生成されます。例えば、~/clawd/cron/jobs.json のような .json ストアを使用している場合、対応する状態ファイルは ~/clawd/cron/jobs-state.json となります。.json 拡張子がないパスを指定した場合は、末尾に -state.json が付与されます。

cron機能を無効にするには、cron.enabled: false を設定するか、環境変数 OPENCLAW_SKIP_CRON=1 を使用してください。

ワンショットリトライ: 一時的なエラー（rate limit、overload、network、server error）が発生した場合、指数バックオフを用いて最大3回まで再試行します。永続的なエラーが発生した場合は、即座に無効化されます。

定期リトライ: 再試行の間隔は指数バックオフ（30秒から60分）に従います。バックオフは、次回の実行が成功した時点でリセットされます。

メンテナンス: cron.sessionRetention（デフォルトは 24h）は、isolated実行セッションのエントリを整理します。また、cron.runLog.maxBytes や cron.runLog.keepLines を設定することで、実行ログファイルを自動的に整理できます。

疑難排解

指令檢查清單

當您在使用 OpenClaw 時遇到問題，可以透過以下 CLI 指令來確認系統狀態與執行細節。這些指令能幫助您快速診斷 Gateway 或 Node.js 環境中的潛在問題。

openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow
openclaw doctor

Cron 無法觸發

若發現排程任務沒有執行，請依照下列步驟進行檢查，確保 OpenClaw 的 cron 設定正確無誤。

檢查 cron.enabled 設定以及 OPENCLAW_SKIP_CRON 環境變數是否配置正確。
確認 Gateway 是否處於持續運作的狀態。
針對 cron 排程，請務必核對 --tz 設定的時間區與主機時間區是否一致。
若執行結果顯示 reason: not-due，代表您使用 openclaw cron run <jobId> --due 進行手動執行時，該任務尚未到達預定的執行時間。

Cron 已觸發但未送達

如果任務顯示已執行但沒有收到通知，請參考以下說明來排查 webhook 或訊息傳遞失敗的原因。

若傳遞模式為 none，代表系統預期不會發送外部訊息。
若傳遞目標（channel 或 to）遺失或無效，系統會跳過發送步驟。
若出現頻道驗證錯誤（如 unauthorized 或 Forbidden），代表憑證權限不足，導致傳遞被阻擋。
如果獨立執行的任務僅回傳靜默 token（NO_REPLY / no_reply），OpenClaw 會抑制直接對外傳遞，同時也會抑制後備的佇列摘要路徑，因此聊天室不會收到任何回覆。
對於由 cron 管理的獨立任務，請勿預期代理程式會使用訊息工具作為後備方案。執行器負責最終的傳遞工作；使用 --no-deliver 參數會將結果保留在內部，而不會觸發直接發送。

時區注意事項

在設定時間相關的任務時，請留意 OpenClaw 對於時區的處理邏輯，以避免執行時間偏移。

若 cron 未設定 --tz，系統將預設使用 Gateway 主機的時區。
若 at 排程未指定時區，系統會將其視為 UTC 時間。
心跳檢測（Heartbeat）中的 activeHours 會使用已配置的時區解析規則。

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。