​

バックグラウンド Exec + プロセスツール

​

exec ツール

• command（必須）
• yieldMs（デフォルト 10000）: この遅延後に自動でバックグラウンド化します
• background（bool）: 即座にバックグラウンド化します
• timeout（秒、デフォルト 1800）: このタイムアウト後にプロセスを終了します
• elevated（bool）: 特権モードが有効／許可されている場合にホスト上で実行します
• 実際の TTY が必要ですか？ pty: true を設定してください。 実 TTY が必要な場合は pty: true を設定します。 実 TTY が必要な場合は pty: true を設定します。
• workdir、env

• フォアグラウンド実行は出力を直接返します。
• バックグラウンド化された場合（明示的、またはタイムアウト時）、ツールは status: "running" + sessionId と短い末尾出力を返します。
• 出力は、セッションがポーリングされるかクリアされるまでメモリ内に保持されます。
• process ツールが許可されていない場合、exec は同期的に実行され、yieldMs/background は無視されます。

​

子プロセスのブリッジ

• PI_BASH_YIELD_MS: 既定の yield（ms）
• PI_BASH_MAX_OUTPUT_CHARS: メモリ内出力の上限（文字数）
• OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS: ストリームごとの保留 stdout/stderr の上限（文字数）
• PI_BASH_JOB_TTL_MS: 完了済みセッションの TTL（ms、1 分～ 3 時間に制限）

• tools.exec.backgroundMs（デフォルト 10000）
• tools.exec.timeoutSec（デフォルト 1800）
• tools.exec.cleanupMs（デフォルト 1800000）
• tools.exec.notifyOnExit（デフォルト true）: バックグラウンド化された exec が終了した際に、システムイベントをキューに入れ、リクエストのハートビートを送信します。
• tools.exec.notifyOnExitEmptySuccess（デフォルト false）: true の場合、出力を生成しなかった成功したバックグラウンド実行についても完了イベントをキューに追加します。

​

process ツール

• list: 実行中および完了済みのセッション
• poll: セッションの新しい出力をドレインします（終了ステータスも報告）
• log: 集約された出力を読み取ります（offset + limit をサポート）
• write: stdin を送信します（data、任意で eof）
• kill: バックグラウンドセッションを終了します
• clear: 完了済みセッションをメモリから削除します
• remove: 実行中であれば kill、完了済みであればクリアします

• バックグラウンド化されたセッションのみが一覧表示され、メモリ内に保持されます。
• プロセスの再起動時にセッションは失われます（ディスクへの永続化はありません）。
• セッションログは、process poll/log を実行し、ツール結果が記録された場合にのみ、チャット履歴へ保存されます。
• process はエージェント単位でスコープされており、そのエージェントが開始したセッションのみを参照します。
• process list には、簡易確認用として派生した name（コマンド動詞 + 対象）が含まれます。
• process log は行ベースの offset/limit を使用します（offset を省略すると直近 N 行を取得します）。
• offset と limit の両方が省略された場合、最後の 200 行を返し、ページングのヒントを含みます。
• offset が指定され、limit が省略された場合、offset から末尾までを返します（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" }