バックグラウンドタスク

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

タスクはセッション、Cron ジョブ、Heartbeat の代わりにはなりません。タスクは、切り離された作業で何が、いつ発生し、成功したかどうかを記録するアクティビティ台帳です。

要約

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

クイックスタート

# すべてのタスクを一覧表示（新しい順）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 : エージェント開始
    running --> succeeded : 正常完了
    running --> failed : エラー
    running --> timed_out : タイムアウト超過
    queued --> cancelled : オペレーターがキャンセル
    running --> cancelled : オペレーターがキャンセル
    queued --> lost : バッキング状態が 5 分超消失
    running --> lost : バッキング状態が 5 分超消失

遷移は自動的に行われます。エージェント実行のライフサイクルイベント（開始、終了、エラー）がタスクのステータスを更新するため、手動で管理する必要はありません。

アクティブなタスク記録では、エージェント実行の完了が信頼できる判定基準です。切り離された実行が成功すると succeeded、通常の実行エラーでは failed、タイムアウトでは timed_out、キャンセルまたは中止では cancelled として確定します。タスクが終端状態になると、後続のライフサイクルシグナルによって状態が後退することはありません。オペレーターがキャンセルしたタスクや、すでに failed/timed_out/lost になっているタスクは、その後に成功シグナルが届いてもその状態を維持します。

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

• ACP タスク: Gateway プロセス内で実行中の ACP ターンだけが、実行が継続していることを証明します。永続化されたセッションメタデータだけでは証明になりません。オフラインの CLI 監査は保守的に動作し、ACP タスクを回収することはありません。
• サブエージェントタスク: バッキングとなる子セッションが対象エージェントのストアから消失した場合（または再起動復旧用のトゥームストーンを持つ場合）。
• Cron タスク: Cron ランタイムがジョブをアクティブとして追跡しておらず、かつ永続的な Cron 実行履歴にもその実行の終端結果が記録されていない場合。オフラインの CLI 監査は、自身の空のプロセス内 Cron ランタイム状態を信頼できる判定基準として扱いません。
• CLI タスク: 実行 ID またはソース ID を持つタスクは実行中のランコンテキストを使用するため、Gateway が所有する実行が消失した後も、残存する子セッションやチャットセッションの行によってタスクがアクティブに保たれることはありません。実行識別子を持たない旧形式の CLI タスクだけは、引き続き子セッションへフォールバックします。Gateway 経由の openclaw agent 実行も実行結果から確定されるため、完了した実行がスイーパーによって lost とマークされるまでアクティブなままになることはありません。

配信と通知

タスクが終端状態に達すると、OpenClaw が通知します。配信経路は 2 つあります。

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

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

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

通知ポリシー

各タスクについて受け取る通知の量を制御します。

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

openclaw tasks notify <lookup> state_changes

CLI リファレンス

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

openclaw tasks show <lookup> [--json]

openclaw tasks cancel <lookup>

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

openclaw tasks audit [--severity <warn|error>] [--code <name>] [--limit <n>] [--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 を使用すると、そのセッションにリンクされたバックグラウンドタスクを確認できます。ボードには、アクティブなタスクと最近完了したタスクが最大5件表示され、ランタイム、ステータス、タイミング、進捗またはエラーの詳細を確認できます。

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

運用者向けの完全な台帳を確認するには、CLI の openclaw tasks list を使用します。

Control UI

Web の Control UI には、サイドバーにライブのアクティブタスクと最近のバックグラウンドタスクを表示する タスク ページがあります。進捗の確認、リンクされたセッションを開く操作、台帳の更新、キュー内および実行中のタスクのキャンセルに使用します。

チャットペインにも、そのペインのエージェントを対象とする折りたたみ可能な バックグラウンドタスク レールがあります。停止コントロール付きの実行中タスクとサブエージェント、完了済みセクション、各タスクの子セッションを開く「トランスクリプトを表示」リンクが含まれます。ペインヘッダーのアクティビティ切り替えボタン（単一ペインチャットではフローティングアクティビティボタン）から開きます。

ステータス統合（タスク負荷）

openclaw status には、タスクの概要行が含まれます:

タスク    アクティブ 2件 · キュー内 1件 · 実行中 1件 · 問題 1件 · 監査は正常 · 追跡中 6件

概要には、アクティブな作業（queued + running）、失敗（failed + timed_out + lost）、監査の検出項目、追跡対象レコードの総数が集計されます。JSON ペイロードでは、ランタイム（acp、subagent、cron、cli）別の件数も表示されます。

/status と session_status ツールはどちらも、クリーンアップを考慮したタスクのスナップショットを使用します。アクティブなタスクが優先され、期限切れの行は非表示になり、終端タスクは最近の短い期間（5分間）だけ表示されます。アクティブな作業が残っていない場合は失敗が中心に表示されます。これにより、ステータスカードには現在重要な情報だけが表示されます。

ストレージとメンテナンス

タスクの保存場所

タスクレコードと配信状態は、共有 OpenClaw SQLite 状態データベースに永続化されます:

~/.openclaw/state/openclaw.sqlite   (テーブル: task_runs, task_delivery_state, flow_runs)

状態ルート全体（デフォルトは ~/.openclaw）を別の場所へ移動するには、OPENCLAW_STATE_DIR を設定します。共有データベースのパスも一緒に移動します。

レジストリは初回使用時にメモリへ読み込まれ、書き込みのたびに SQLite へ永続化されるため、Gateway の再起動後もレコードが保持されます。WAL の増大は、SQLite のデフォルトの自動チェックポイントしきい値と定期的な PASSIVE チェックポイントによって制限されます。シャットダウン時と明示的なメンテナンス時のチェックポイントでは TRUNCATE を使用するため、バックグラウンドスイーパーをアクティブな読み取りの完了待ちにせず、通常の終了時に WAL 領域を回収できます。

古いインストールの従来のサイドカーストア（tasks/runs.sqlite、flows/registry.sqlite）は、openclaw doctor によって共有データベースへインポートされます。

自動メンテナンス

スイーパーは 60秒 ごとに実行され（初回は Gateway の起動から約5秒後）、次の4つを処理します:

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

関連項目

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