バックグラウンドタスク

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

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

TL;DR

• タスクはスケジューラーではなく記録です。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 日間保持され、その後自動的に削除されます。

クイックスタート

# すべてのタスクを一覧表示する (新しい順)openclaw tasks list # ランタイムまたはステータスで絞り込むopenclaw tasks list --runtime acpopenclaw tasks list --status running

# 特定のタスクの詳細を表示する (ID、実行 ID、またはセッションキー)openclaw tasks show <lookup>

# 実行中のタスクをキャンセルする (子セッションを終了する)openclaw tasks cancel <lookup> # タスクの通知ポリシーを変更するopenclaw tasks notify <lookup> state_changes

# ヘルス監査を実行するopenclaw tasks audit # 保守をプレビューまたは適用するopenclaw tasks maintenanceopenclaw tasks maintenance --apply

# TaskFlow の状態を調査するopenclaw 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 しきい値に加え、定期的な TRUNCATE チェックポイントとシャットダウン時の TRUNCATE チェックポイントを使用して、SQLite の先行書き込みログを制限します。

自動 maintenance

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

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

関連

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