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.timeoutSec）。期限切れになるとプロセスを終了します。その呼び出しで 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.timeoutSec を継承します。
  • 出力は、セッションがポーリングまたは消去されるまでメモリ内に保持されます。
  • process ツールが許可されていない場合、exec は同期的に実行され、yieldMs/background は無視されます。
  • 起動された exec コマンドには、コンテキストを認識するシェル／プロファイルルール用として OPENCLAW_SHELL=exec が渡されます。
  • 今すぐ開始する長時間実行処理の場合: 一度だけ開始し、コマンドが出力を生成するか失敗した時点で、有効なら自動完了ウェイクに任せます。
  • 自動完了ウェイクを利用できない場合、または出力なしで正常終了するコマンドのサイレント成功を確認する必要がある場合は、process でポーリングします。
  • sleep ループや繰り返しポーリングでリマインダーや遅延フォローアップを模倣しないでください。将来の処理には Cron を使用します。

環境変数による上書き

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

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

キー デフォルト 効果
tools.exec.backgroundMs 10000 OPENCLAW_BASH_YIELD_MS と同じです。
tools.exec.timeoutSec 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 が waitingForInput を報告するのは、セッションの stdin がまだ書き込み可能で、入力待ちしきい値（デフォルトは 15000 ミリ秒、OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS）を超えてアイドル状態が続いている場合だけです。
  • 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