バックグラウンドタスク

バックグラウンドタスクは、メインの会話セッションの外側で実行される作業を追跡します。ACP 実行、サブエージェントの起動、分離された cron ジョブの実行、CLI から開始された操作が含まれます。

タスクはセッション、cron ジョブ、Heartbeat を置き換えるものではありません。切り離された作業で何が起きたか、いつ起きたか、成功したかどうかを記録するアクティビティ台帳です。

要約

• タスクはスケジューラではなく記録です。cron と Heartbeat が作業を_いつ_実行するかを決め、タスクは_何が起きたか_を追跡します。
• ACP、サブエージェント、すべての cron ジョブ、CLI 操作はタスクを作成します。Heartbeat ターンは作成しません。
• 各タスクは queued → running → terminal（succeeded、failed、timed_out、cancelled、lost）をたどります。
• cron ランタイムがまだジョブを所有している間、cron タスクはライブのままです。 メモリ内のランタイム状態が失われた場合、タスクメンテナンスはタスクを lost とマークする前に、 永続化された cron 実行履歴をまず確認します。
• 完了はプッシュ駆動です。切り離された作業は、完了時に直接通知するか、 要求元セッションまたは Heartbeat を起床できるため、ステータスポーリングループは 通常は適切な形ではありません。
• 分離された cron 実行とサブエージェント完了は、最終クリーンアップの記録処理の前に、子セッションで追跡されているブラウザタブやプロセスをベストエフォートでクリーンアップします。
• 分離された cron 配信は、子孫サブエージェント作業がまだ排出中の間、古くなった中間の親返信を抑制し、配信前に到着した場合は最終的な子孫出力を優先します。
• 完了通知はチャネルに直接配信されるか、次の Heartbeat 用にキューに入れられます。
• openclaw tasks list はすべてのタスクを表示します。openclaw tasks audit は問題を表面化します。
• ターミナル記録は 7 日間保持され、その後自動的に削除されます。

クイックスタート

# List all tasks (newest first)openclaw tasks list # Filter by runtime or statusopenclaw tasks list --runtime acpopenclaw tasks list --status running

# Show details for a specific task (by ID, run ID, or session key)openclaw tasks show <lookup>

# Cancel a running task (kills the child session)openclaw tasks cancel <lookup> # Change notification policy for a taskopenclaw tasks notify <lookup> state_changes

# Run a health auditopenclaw tasks audit # Preview or apply maintenanceopenclaw tasks maintenanceopenclaw tasks maintenance --apply

# Inspect TaskFlow stateopenclaw tasks flow listopenclaw tasks flow show <lookup>openclaw tasks flow cancel <lookup>

タスクを作成するもの

タスクライフサイクル

stateDiagram-v2
    [*] --> queued
    queued --> running : agent starts
    running --> succeeded : completes ok
    running --> failed : error
    running --> timed_out : timeout exceeded
    running --> cancelled : operator cancels
    queued --> lost : session gone > 5 min
    running --> lost : session gone > 5 min

遷移は自動的に発生します。関連付けられたエージェント実行が終了すると、タスクステータスはそれに合わせて更新されます。

エージェント実行の完了は、アクティブなタスク記録に対して権威があります。成功した切り離し実行は succeeded として確定し、通常の実行エラーは failed として確定し、タイムアウトまたは中止の結果は timed_out として確定します。オペレーターがすでにタスクをキャンセルしている場合、またはランタイムが failed、timed_out、lost など、より強いターミナル状態をすでに記録している場合、後から成功シグナルが来てもそのターミナルステータスは格下げされません。

lost はランタイムを考慮します。

• ACP タスク: 裏付けとなる ACP 子セッションメタデータが消失しました。
• サブエージェントタスク: 裏付けとなる子セッションがターゲットエージェントストアから消失しました。
• cron タスク: cron ランタイムがそのジョブをアクティブとして追跡しなくなり、永続化された cron 実行履歴にもその実行のターミナル結果がありません。オフライン CLI 監査は、自分自身の空のプロセス内 cron ランタイム状態を権威として扱いません。
• CLI タスク: 実行 ID またはソース ID を持つタスクはライブ実行コンテキストを使用するため、 残存する子セッションやチャットセッション行は、Gateway が所有する実行が消えた後も それらを生存扱いにはしません。実行 ID を持たないレガシー CLI タスクは引き続き 子セッションにフォールバックします。Gateway に裏付けられた openclaw agent 実行も 実行結果から確定するため、完了した実行がスイーパーに lost とマークされるまで アクティブのまま残ることはありません。

配信と通知

タスクがターミナル状態に到達すると、OpenClaw は通知します。配信経路は 2 つあります。

直接配信 - タスクにチャネルターゲット（requesterOrigin）がある場合、完了メッセージはそのチャネル（Telegram、Discord、Slack など）に直接送られます。グループおよびチャネルのタスク完了は、代わりに要求元セッション経由でルーティングされ、親エージェントが可視返信を書けるようにします。サブエージェント完了では、OpenClaw は利用可能な場合、バインドされたスレッドまたはトピックのルーティングも保持し、直接配信を断念する前に、要求元セッションの保存済みルート（lastChannel / lastTo / lastAccountId）から不足している to / アカウントを補完できます。

セッションキュー配信 - 直接配信が失敗した場合、または origin が設定されていない場合、更新は要求元のセッション内でシステムイベントとしてキューに入れられ、次の Heartbeat で表面化します。

つまり通常のワークフローはプッシュベースです。切り離された作業を一度開始し、その後はランタイムが完了時に起床または通知するのに任せます。タスク状態のポーリングは、デバッグ、介入、または明示的な監査が必要な場合にのみ行ってください。

通知ポリシー

各タスクについてどの程度通知を受けるかを制御します。

タスクの実行中にポリシーを変更します。

openclaw tasks notify <lookup> state_changes

CLI リファレンス

openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]

openclaw tasks show <lookup>

openclaw tasks cancel <lookup>

openclaw tasks notify <lookup> <done_only|state_changes|silent>

openclaw tasks audit [--json]

openclaw tasks maintenance [--json]openclaw tasks maintenance --apply [--json]

openclaw tasks flow list [--status <status>] [--json]openclaw tasks flow show <lookup> [--json]openclaw tasks flow cancel <lookup>

チャットタスクボード（/tasks）

任意のチャットセッションで /tasks を使用すると、そのセッションにリンクされたバックグラウンドタスクを確認できます。ボードには、アクティブなタスクと最近完了したタスクが、ランタイム、ステータス、タイミング、進捗またはエラー詳細とともに表示されます。

現在のセッションに表示可能なリンク済みタスクがない場合、/tasks はエージェントローカルのタスク数へフォールバックするため、他セッションの詳細を漏らさずに概要を確認できます。

完全なオペレータ台帳には CLI を使用します: openclaw tasks list。

ステータス連携（タスク負荷）

openclaw status には、タスク概要がひと目で分かる形式で含まれます。

Tasks: 3 queued · 2 running · 1 issues

概要では次を報告します。

• active - queued + running の数
• failures - failed + timed_out + lost の数
• byRuntime - acp、subagent、cron、cli ごとの内訳

/status と session_status ツールはいずれも、クリーンアップを考慮したタスクスナップショットを使用します。アクティブなタスクが優先され、古い完了行は非表示になり、最近の失敗はアクティブな作業が残っていない場合にのみ表示されます。これにより、ステータスカードは今重要な情報に集中できます。

ストレージと maintenance

タスクの保存場所

タスクレコードは SQLite の次の場所に永続化されます。

$OPENCLAW_STATE_DIR/tasks/runs.sqlite

レジストリは Gateway 起動時にメモリへ読み込まれ、再起動をまたいだ耐久性のために書き込みを SQLite へ同期します。 Gateway は、SQLite のデフォルトの autocheckpoint しきい値と定期的な PASSIVE チェックポイントを使用して、SQLite の先行書き込みログを一定範囲に保ちます。シャットダウンと明示的な maintenance チェックポイントでは引き続き TRUNCATE を使用するため、通常の終了時にバックグラウンド sweeper がアクティブな reader を待たずに WAL 領域を回収できます。

自動 maintenance

sweeper は 60秒 ごとに実行され、4つの処理を行います。

タスクと他システムの関係

関連

• 自動化 - すべての自動化メカニズムの概要
• CLI: タスク - CLI コマンドリファレンス
• Heartbeat - 定期的なメインセッション turn
• スケジュール済みタスク - バックグラウンド作業のスケジューリング
• タスクフロー - タスクの上位にあるフローオーケストレーション