> ## Documentation Index
> Fetch the complete documentation index at: https://openclawdoc.org/llms.txt
> Use this file to discover all available pages before exploring further.

> exec で長時間ジョブを起動し、子プロセスを橋渡ししながら process ツールで状態確認や停止を行う方法を説明します。

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

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

## `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` 環境変数を受け取ります。これは、コンテキストに応じたシェルやプロファイルの設定に使用できます。

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

`exec`/`process` ツールの外部で長時間実行される子プロセス（CLI の再起動やゲートウェイのヘルパーなど）を生成する場合は、子プロセスブリッジ（child-process bridge）ヘルパーをアタッチしてください。これにより、終了信号が適切に転送され、プロセス終了時やエラー時にリスナーが確実に解除されます。これは、systemd 環境などでの孤立プロセスの発生を防ぎ、プラットフォームを跨いで一貫したシャットダウン挙動を維持するために重要です。

環境変数による上書き設定:

* `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 行の制限は適用されません）。

## 実行例

長時間タスクを実行し、後で結果を確認する:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }
```

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "poll", "sessionId": "<id>" }
```

最初からバックグラウンドで開始する:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "exec", "command": "npm run build", "background": true }
```

標準入力を送る:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }
```