--- read_when: - バックグラウンド実行動作の追加または変更 - 長時間実行される exec タスクのデバッグ summary: バックグラウンド exec 実行とプロセス管理 title: バックグラウンド実行とプロセスツール x-i18n: generated_at: "2026-07-11T22:12:41Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: b540455797df71dcdb18b0caa5f5088e81ef8823e0ec79364bebad8e6f060f12 source_path: gateway/background-process.md workflow: 16 --- 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": "" } ``` 入力を送信する前に対話型セッションを確認する: ```json { "tool": "process", "action": "log", "sessionId": "" } ``` 直ちにバックグラウンドで開始する: ```json { "tool": "exec", "command": "npm run build", "background": true } ``` stdin を送信する: ```json { "tool": "process", "action": "write", "sessionId": "", "data": "y\n" } ``` PTY キーを送信する: ```json { "tool": "process", "action": "send-keys", "sessionId": "", "keys": ["C-c"] } ``` 現在の行を送信する: ```json { "tool": "process", "action": "submit", "sessionId": "" } ``` リテラルテキストを貼り付ける: ```json { "tool": "process", "action": "paste", "sessionId": "", "text": "line1\nline2\n" } ``` ## 関連項目 - [Exec ツール](/ja-JP/tools/exec) - [Exec の承認](/ja-JP/tools/exec-approvals)