OpenClawのバックグラウンドexecとprocessツール

シェルツールが役に立つか、それともお荷物になるかが分かれるのが、長時間実行される作業です。OpenClawの答えは、コマンドをバックグラウンドに回してセッションIDを返し、それをポーリングし、入力を与え、終了させるための別のツールをエージェントに渡すことです。知っておくべき詳細は、出力が残るかどうか、プロセスが生き残るかどうか、そしてエージェントがスリープする代わりに何をすべきかを左右する部分です。

バックグラウンド化と保持

• フォアグラウンドの実行は保持された出力を直接返し、それ以前の出力が合計上限を超えていた場合はその旨を明示します。コマンドが明示的に、またはyield遅延を過ぎたことでバックグラウンドに回されると、ツールはrunningのステータス、セッションID、短い末尾の抜粋を返します。バックグラウンドの実行も、呼び出しで独自の値を渡さない限り、設定済みのexecタイムアウトを引き継ぎます。
• セッションIDが返されても、プロセスのタイムアウトは止まりません。gateway上やサンドボックス内で常駐サービスを動かすなら、タイムアウトを無効にしてコマンドをバックグラウンドに回し、あとでkillアクションで停止してください。その場合も、ホストとワーカーのライフサイクル制限は適用されます。
• 出力は、セッションがポーリングまたは消去されるまで、セッションごとの合計上限までメモリに保持されます。終了したセッションは完了時点から測る保持期間で期限切れになり、各execは受け付けられた時点で、そのエージェントの保持設定を取り込みます。レジストリが保持するのは最大50件の終了済みセッションと200万文字までで、古いものから順に削除されますが、最も新しく完了したセッションは上限内に収めた合計出力を保持します。
• これらの調整項目は、環境変数ではなく設定キーとして用意されています。バックグラウンドへの移行遅延のデフォルトは10秒、呼び出しごとのタイムアウトは1800秒、クリーンアップまでの保持期間は30分です。終了通知はデフォルトでオンで、システムイベントとハートビートのリクエストをキューに入れます。さらに追加の設定で、出力のない成功した実行についても通知できます。

ポーリングは必要なときに状態を確認するためのもので、待機ループによるスケジューリングのためのものではありません。あとで行うべき作業には、cronを使ってください。

ワーカー、クリーンアップ、processツール

ペアリング済みのノードや、ノードを基盤とするクラウドワーカーでは、バックグラウンドプロセスはセッションの環境に属します。ターンが終了またはキャンセルされても、すでにバックグラウンドに回されたコマンドは実行を続け、同じ環境での後続のターンからポーリング、入力、停止ができます。フォアグラウンドのコマンドは、これまでどおりターンがキャンセルされると停止します。保持されたワーカーはノードのワーカースロットを1つ占有しますが、再利用に追加のスロットは不要で、生きているバックグラウンドコマンドがない状態でターンが終わると、ワーカーは終了します。環境を移動または廃止したり、所有権を置き換えたり、ノードを停止したりしてもプロセスは停止し、ハンドルはワーカーやノードの再起動を越えて残りません。クリーンアップはほかの面でも意図的に慎重です。所有するプロセスグループについては、グループが消えたことをOSが確認するまで待ちます。コマンドが完了した、あるいは出力パイプが閉じたというだけでは子孫プロセスが停止した証拠にはならず、クリーンアップが確認されないまま強制終了した場合は、正常なシャットダウンとして報告されず、不確定のまま扱われます。

9つのアクション

• listは実行中と終了済みのセッションを派生した名前付きで表示し、pollは新しい出力を取り出して終了ステータスを報告し、logは集約された出力を行単位のページングと入力復旧のヒント付きで読み取ります。この3つがセッションを入力待ちと示すのは、stdinがまだ書き込み可能で、しきい値を超えてアイドル状態が続いている場合だけです。
• writeは任意の終端マーカー付きでstdinに送信し、send-keysは明示的なキートークンやバイトを端末ベースのセッションに送り、submitはキャリッジリターンを送り、pasteはリテラルテキストをデフォルトでブラケットペーストで囲んで送ります。killは実行中のセッションを終了し、clearは終了済みのセッションを削除し、removeはそのどちらか該当するほうを行います。
• 一覧に表示され保持されるのはバックグラウンドに回されたセッションだけで、保持先はメモリのみ、ディスクには決して書かれないため、再起動すると失われます。ツールはエージェントごとにスコープされ、そのエージェントのセッションしか見えません。生きているバックグラウンドセッションがあると、終了が確認されるまで協調的なサスペンドとgatewayの安全な再起動がブロックされます。また、30秒を超えるpollのタイムアウトは30秒に切り詰められます。

これらのセッションを開始するツールについてはOpenClawのexecツールの記事で、実行中のセッションを表示する台帳についてはOpenClawのバックグラウンドタスクの記事で解説しています。

スリープする代わりにすべきこと

ドキュメントはこのアンチパターンについてはっきり述べています。リマインダーや遅延したフォローアップを、sleepのループや繰り返しのポーリングで代用してはいけません。今すぐ始める作業なら一度だけ開始し、完了時の自動ウェイクが有効で、コマンドが出力を出すか失敗する場合はそれに任せます。そのうえで、ログ、ステータス、入力、介入にはprocessツールを使います。あとで、またはスケジュールに沿って行うべき作業には、スケジューラーが適切な手段です。対話型のコマンドを復旧する前にログを読むことも、身につけておきたい習慣です。トランスクリプト、stdinの状態、入力待ちのヒントがそろって見えるのはそこだけだからです。スケジューラーについてはOpenClawの自動化の記事で、これらのコマンドが実際にどこで動くかについてはOpenClawのサンドボックスの解説の記事で扱っています。

Dialiでは

Dialiでは、アシスタントは状態を永続ボリュームに置いた専用のランタイムで動作するため、バックグラウンドコマンドはそのお客様のランタイムだけに属します。毎日のスナップショットとワンクリック復元は、「バックアップ」アドオン（Maxに含まれます）で利用できます。ホスティングされたアシスタントについてはDialiのマネージドOpenClawホスティングのページを、アシスタントが実行できる範囲を囲む境界についてはDialiのセキュリティのページをご覧ください。

• yield遅延を過ぎたコマンドが返すのは、大量の出力ではなくセッションIDです。
• メモリのみ：セッションは再起動で失われ、上限があり、期限切れになります。
• ポーリングより完了時のウェイク、スリープよりスケジューラー。