バックグラウンドタスク

バックグラウンドタスクは、メインの会話セッションの外部で実行される作業を追跡します。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 status
openclaw tasks list --runtime acp
openclaw 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 task
openclaw tasks notify <lookup> state_changes

# Run a health audit
openclaw tasks audit

# Preview or apply maintenance
openclaw tasks maintenance
openclaw tasks maintenance --apply

# Inspect TaskFlow state
openclaw tasks flow list
openclaw 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 ツールはいずれも、クリーンアップを考慮したタスクスナップショットを使用します。アクティブなタスクが優先され、古い完了行は非表示になり、最近の失敗はアクティブな作業が残っていない場合にのみ表示されます。これにより、ステータスカードは今重要なことに集中できます。

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

# タスクの保存場所

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

$OPENCLAW_STATE_DIR/tasks/runs.sqlite

レジストリは Gateway 起動時にメモリへ読み込まれ、再起動をまたいだ耐久性のために書き込みを SQLite に同期します。 Gateway は、SQLite のデフォルトの 自動チェックポイントしきい値に加え、定期およびシャットダウン時の TRUNCATE チェックポイントを使用して、SQLite の先行書き込みログを一定範囲に保ちます。

# 自動メンテナンス

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

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

# 関連

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