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

​

exec ツール

• command (必須)
• yieldMs (デフォルト 10000): この時間が経過すると自動的にバックグラウンドへ移行します。
• background (boolean): 即座にバックグラウンドで実行します。
• timeout (秒、デフォルト 1800): 指定した時間が経過するとプロセスを強制終了します。
• elevated (boolean): 権限昇格モードが有効かつ許可されている場合に、ホスト上で実行します。
• 本物の TTY が必要ですか？ pty: true を設定してください。
• workdir, env

• フォアグラウンド（同期）実行時は、出力を直接返します。
• バックグラウンド（明示的な指定、またはタイムアウトによる移行）の場合、ツールは status: "running", sessionId および出力の短い末尾部分を返します。
• 出力内容は、セッションがポーリング（poll）されるか削除されるまでメモリ内に保持されます。
• process ツールの使用が許可されていない場合、exec は常に同期的に実行され、yieldMs や background 指定は無視されます。
• 生成された exec コマンドは OPENCLAW_SHELL=exec 環境変数を受け取ります。これは、コンテキストに応じたシェルやプロファイルの設定に使用できます。

​

子プロセスのブリッジング

• PI_BASH_YIELD_MS: デフォルトの yield 時間（ミリ秒）。
• PI_BASH_MAX_OUTPUT_CHARS: メモリ内に保持する出力の上限文字数。
• OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS: ストリームごとの未処理（pending）な標準出力/標準エラー出力の上限文字数。
• PI_BASH_JOB_TTL_MS: 終了したセッションの保持期間（1分〜3時間の範囲。ミリ秒指定）。

• tools.exec.backgroundMs (デフォルト 10000)
• tools.exec.timeoutSec (デフォルト 1800)
• tools.exec.cleanupMs (デフォルト 1800000)
• tools.exec.notifyOnExit (デフォルト true): バックグラウンド実行が終了した際、システムイベントを投入し、ハートビートを要求します。
• tools.exec.notifyOnExitEmptySuccess (デフォルト false): true の場合、出力を生成せずに成功終了したバックグラウンド実行に対しても、完了イベントを投入します。

​

process ツール

• list: 実行中および終了したセッションの一覧を表示。
• poll: セッションの新しい出力を取得（終了ステータスも併せて報告）。
• log: 蓄積された出力を読み取り（offset と limit による範囲指定が可能）。
• write: 標準入力（stdin）を送信 (data, オプションで eof)。
• kill: バックグラウンドセッションを強制終了。
• clear: 終了したセッションをメモリから削除。
• remove: 実行中の場合は強制終了し、終了済みの場合はメモリから削除。

• バックグラウンド化されたセッションのみが一覧表示され、メモリ内に保持されます。
• プロセス（ゲートウェイ）の再起動時にセッションは失われます（ディスクへの永続化は行われません）。
• セッションのログが会話履歴に保存されるのは、process poll/log を実行し、その結果が記録された場合のみです。
• process ツールはエージェントごとにスコープが分かれています。自身が開始したセッションのみを操作できます。
• process list の出力には、中身を素早く把握するための name（コマンド動詞 + ターゲット）が含まれます。
• process log は行ベースの offset/limit を使用します。
• offset と limit の両方を省略した場合、直近の 200 行を返し、ページングのヒントを付加します。
• offset を指定し limit を省略した場合は、指定位置から最後までを返します（200 行の制限は適用されません）。

​

実行例

{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }

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

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

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