OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

バックグラウンド実行とプロセスツール

OpenClaw は exec ツールを介してシェルコマンドを実行し、長時間実行されるタスクをメモリ内に保持します。process ツールは、それらのバックグラウンドセッションを管理します。

exec ツール

パラメーター:

パラメーター 説明
command 必須。実行するシェルコマンド。
workdir 作業ディレクトリ。省略するとデフォルトの cwd を使用します。
env コマンドに追加する環境変数。
yieldMs バックグラウンド化するまで待機するミリ秒数（デフォルトは 10000）。
background 直ちにバックグラウンドで実行します。
timeout タイムアウト（秒、デフォルトは tools.exec.timeoutSeconds）。期限切れになるとプロセスを終了します。その呼び出しで exec プロセスのタイムアウトを無効にするには、timeout: 0 を設定します。
pty 利用可能な場合は擬似端末で実行します（TTY が必要な CLI、コーディングエージェント）。
elevated 昇格モードが有効かつ許可されている場合に、サンドボックス外で実行します（デフォルトは gateway。exec のターゲットが node の場合は node）。
host exec のターゲット: auto、sandbox、gateway、または node。
node Node の ID/名前。host: "node" とともに使用します。

動作:

  • フォアグラウンド実行では、出力が直接返されます。
  • バックグラウンド化された場合（明示的な指定、または yieldMs のタイムアウトによるもの）、ツールは status: "running" + sessionId と短い出力末尾を返します。
  • バックグラウンド化された実行と yieldMs 実行は、呼び出しで明示的な timeout が渡されない限り、tools.exec.timeoutSeconds を継承します。
  • 出力は、セッションがポーリングまたはクリアされるまでメモリ内に保持されます。
  • process ツールが許可されていない場合、exec は同期的に実行され、yieldMs/background は無視されます。
  • 起動された exec コマンドは、コンテキストに応じたシェル/プロファイル規則のために OPENCLAW_SHELL=exec を受け取ります。
  • 今すぐ開始する長時間実行の作業では、一度だけ開始し、コマンドが出力を生成するか失敗した時点で、自動完了ウェイク（有効な場合）に任せます。
  • 自動完了ウェイクが利用できない場合、または出力なしで正常終了するコマンドについて無出力の成功確認が必要な場合は、process でポーリングします。
  • リマインダーや遅延フォローアップを sleep ループや反復ポーリングで模倣しないでください。将来の作業には Cron を使用してください。

環境変数による上書き

変数 効果
OPENCLAW_BASH_YIELD_MS バックグラウンド化するまでのデフォルト待機時間（ms）。デフォルトは 10000、10〜120000 の範囲に制限されます。
OPENCLAW_BASH_MAX_OUTPUT_CHARS メモリ内の出力上限（文字数）。
OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS ストリームごとの保留中 stdout/stderr の上限（文字数）。
OPENCLAW_BASH_JOB_TTL_MS 完了したセッションの TTL（ms）。1m〜3h の範囲に制限されます。
OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS 書き込み可能なバックグラウンドセッションが入力待ちの可能性ありと判断されるまでの無出力アイドル時間のしきい値。デフォルトは 15000。

設定（環境変数による上書きより推奨）

キー デフォルト 効果
tools.exec.backgroundMs 10000 OPENCLAW_BASH_YIELD_MS と同じです。
tools.exec.timeoutSeconds 1800 呼び出しごとのデフォルトタイムアウト。
tools.exec.cleanupMs 1800000 OPENCLAW_BASH_JOB_TTL_MS と同じです。
tools.exec.notifyOnExit true バックグラウンド化された exec が終了したときに、システムイベントをキューに追加し、Heartbeat を要求します。
tools.exec.notifyOnExitEmptySuccess false 出力なしで成功したバックグラウンド実行についても、完了イベントをキューに追加します。

子プロセスのブリッジ

exec/process ツールの外部で長時間実行される子プロセス（CLI の再起動、Gateway ヘルパー）を起動する場合は、子プロセスブリッジヘルパーを接続し、終了シグナルが転送され、終了時またはエラー時にリスナーが解除されるようにします。これにより、systemd 上で孤立プロセスが発生するのを防ぎ、プラットフォーム間で一貫したシャットダウンを維持できます。

process ツール

アクション:

アクション 効果
list 実行中および完了済みのセッション。
poll セッションの新しい出力を取り出します（終了ステータスも報告します）。
log 集約された出力と入力復旧のヒントを読み取ります。offset + limit をサポートします。
write stdin を送信します（data、任意の eof）。
send-keys PTY ベースのセッションに明示的なキートークンまたはバイトを送信します。
submit PTY ベースのセッションに Enter/キャリッジリターンを送信します。
paste リテラルテキストを送信します。必要に応じてブラケットペーストモードで囲みます。
kill バックグラウンドセッションを終了します。
clear 完了したセッションをメモリから削除します。
remove 実行中の場合は終了し、完了済みの場合はクリアします。

注:

  • 一覧表示および保持されるのはバックグラウンド化されたセッションのみです。保持先はメモリ内だけで、ディスクには保存されません。セッションはプロセスの再起動時に失われます。
  • 稼働中のバックグラウンドセッションがあると、プロセス所有者が実際の終了を確認するまで、協調的なホストのサスペンドと安全な Gateway の再起動がブロックされます。
  • process remove は終了を要求した直後に実行中のセッションを非表示にできますが、終了が確認されるまでサスペンドと再起動は引き続きブロックされます。
  • セッションログがチャット履歴に保存されるのは、process poll/log を実行し、ツール結果が記録された場合のみです。
  • process のスコープはエージェントごとで、そのエージェントが開始したセッションのみが表示されます。
  • 自動完了ウェイクが利用できない場合は、ステータス、ログ、または完了の確認に poll/log を使用します。
  • 対話型 CLI を復旧する前に log を使用し、現在のトランスクリプト、stdin の状態、入力待ちのヒントをまとめて確認できるようにします。
  • 入力または介入が必要な場合は、write/send-keys/submit/paste/kill を使用します。
  • process list には、すばやく確認できるよう、派生した name（コマンドの動詞 + ターゲット）が含まれます。
  • process list、poll、および log は、セッションの stdin が引き続き書き込み可能で、入力待ちのしきい値（デフォルトは 15000 ms、OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS）を超えてアイドル状態にある場合にのみ、waitingForInput を報告します。
  • process log は、行ベースの offset/limit を使用します。両方を省略すると、ページングのヒントとともに末尾の 200 行を返します。offset が設定され、limit が設定されていない場合、offset から末尾までを返します（200 行には制限されません）。
  • poll の timeout は、値で指定されたミリ秒数まで待ってから結果を返します。30000 を超える値は 30000 に制限されます。
  • ポーリングはオンデマンドのステータス確認用であり、待機ループのスケジューリング用ではありません。作業を後で実行する場合は、Cron を使用してください。

例

長時間実行するタスクを開始し、後でポーリングする:

json
{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }
json
{ "tool": "process", "action": "poll", "sessionId": "<id>" }

入力を送信する前に対話型セッションを調べる:

json
{ "tool": "process", "action": "log", "sessionId": "<id>" }

直ちにバックグラウンドで開始する:

json
{ "tool": "exec", "command": "npm run build", "background": true }

stdin を送信する:

json
{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }

PTY キーを送信する:

json
{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }

現在の行を送信する:

json
{ "tool": "process", "action": "submit", "sessionId": "<id>" }

リテラルテキストを貼り付ける:

json
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

関連項目

Was this useful?
On this page

On this page