Background exec and process tool

기준일: 2026-07-26
공식 기준: Background exec and process tool

Background exec and process tool 문서는 OpenClaw 공식 문서(gateway/background-process)를 한국어로 정리한 가이드입니다. Background exec execution and process management 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Background exec execution and process management

한국어 가이드 범위: gateway/background-process 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

exec tool
Env overrides
Config (preferred over env overrides)
Child process bridging
process tool
예제
관련 문서

상세 내용

본문

OpenClaw runs shell commands through the exec tool and keeps long-running tasks in memory. The process tool manages those background sessions.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

exec tool

주요 항목:

Foreground runs return output directly.
When backgrounded (explicit or via yieldMs timeout), the tool returns status: "running" + sessionId and a short output tail.
Backgrounded and yieldMs runs inherit tools.exec.timeoutSeconds unless the call passes an explicit timeout.
Output stays in memory until the session is polled or cleared.
If the process tool is disallowed, exec runs synchronously and ignores yieldMs/background.
Spawned exec commands receive OPENCLAW_SHELL=exec for context-aware shell/profile rules.
For long-running work that starts now: start it once and rely on automatic completion wake (when enabled) once the command emits output or fails.
If automatic completion wake is unavailable, or you need quiet-success confirmation for a command that exits cleanly with no output, poll with process.
Don't emulate reminders or delayed follow-ups with sleep loops or repeated polling — use cron for future work.

Parameter	Description
`command`	Required. Shell command to run.
`workdir`	Working directory; omit to use the default cwd.
`env`	Extra environment variables for the command.
`yieldMs`	Milliseconds to wait before backgrounding (default 10000).
`background`	Run in background immediately.
`timeout`	Timeout in seconds (default `tools.exec.timeoutSeconds`); kills the process on expiry. Set `timeout: 0` to disable the exec process timeout for that call.
`pty`	Run in a pseudo-terminal when available (TTY-required CLIs, coding agents).
`elevated`	Run outside the sandbox if elevated mode is enabled/allowed (`gateway` by default, or `node` when the exec target is `node`).
`host`	Exec target: `auto`, `sandbox`, `gateway`, or `node`.
`node`	Node id/name, used with `host: "node"`.

Env overrides

Variable	Effect
`OPENCLAW_BASH_YIELD_MS`	Default yield before backgrounding (ms). Default 10000, clamped 10-120000.
`OPENCLAW_BASH_MAX_OUTPUT_CHARS`	In-memory output cap (chars).
`OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS`	Pending stdout/stderr cap per stream (chars).
`OPENCLAW_BASH_JOB_TTL_MS`	TTL for finished sessions (ms), bounded to 1m-3h.
`OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS`	Idle-output threshold before writable background sessions are marked as likely waiting for input. Default 15000.

Config (preferred over env overrides)

Key	Default	Effect
`tools.exec.backgroundMs`	10000	Same as `OPENCLAW_BASH_YIELD_MS`.
`tools.exec.timeoutSeconds`	1800	Default per-call timeout.
`tools.exec.cleanupMs`	1800000	Same as `OPENCLAW_BASH_JOB_TTL_MS`.
`tools.exec.notifyOnExit`	true	Enqueue a system event + request heartbeat when a backgrounded exec exits.
`tools.exec.notifyOnExitEmptySuccess`	false	Also enqueue completion events for successful backgrounded runs with no output.

Child process bridging

When spawning long-running child processes outside the exec/process tools (CLI respawns, gateway helpers), attach the child-process bridge helper so termination signals forward and listeners detach on exit/error. This avoids orphaned processes on systemd and keeps shutdown consistent across platforms.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

process tool

주요 항목:

Only backgrounded sessions are listed/persisted — in memory only, not on disk. Sessions are lost on process restart.
A live background session blocks cooperative host suspension and safe Gateway restart until the process owner confirms its actual exit.
process remove can hide a running session immediately after requesting termination; suspension and restart remain blocked until exit confirmation.
Session logs are only saved to chat history if you run process poll/log and the tool result is recorded.
process is scoped per agent; it only sees sessions started by that agent.
Use poll/log for status, logs, or completion confirmation when automatic completion wake is unavailable.
Use log before recovering an interactive CLI, so the current transcript, stdin state, and input-wait hint are visible together.
Use write/send-keys/submit/paste/kill when you need input or intervention.
process list includes a derived name (command verb + target) for quick scans.
process list, poll, and log report waitingForInput only when the session still has writable stdin and has been idle longer than the input-wait threshold (default 15000 ms, OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS).
process log uses line-based offset/limit. When both are omitted, it returns the last 200 lines with a paging hint. When offset is set and limit isn't, it returns from offset to the end (not capped to 200).
poll's timeout waits up to that many milliseconds before returning; values above 30000 are clamped to 30000.
Polling is for on-demand status, not wait-loop scheduling. If the work should happen later, use cron.

Action	Effect
`list`	Running + finished sessions.
`poll`	Drain new output for a session (also reports exit status).
`log`	Read aggregated output and input-recovery hints. Supports `offset` + `limit`.
`write`	Send stdin (`data`, optional `eof`).
`send-keys`	Send explicit key tokens or bytes to a PTY-backed session.
`submit`	Send Enter/carriage return to a PTY-backed session.
`paste`	Send literal text, optionally wrapped in bracketed paste mode.
`kill`	Terminate a background session.
`clear`	Remove a finished session from memory.
`remove`	Kill if running, otherwise clear if finished.

예제

Inspect an interactive session before sending input:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

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

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

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

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/background-process
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

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

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

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

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

{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }

Background exec and process tool

기준일: 2026-07-26
공식 기준: Background exec and process tool

핵심 요약

Background exec execution and process management

한국어 가이드 범위: gateway/background-process 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

exec tool
Env overrides
Config (preferred over env overrides)
Child process bridging
process tool
예제
관련 문서

상세 내용

본문

OpenClaw runs shell commands through the exec tool and keeps long-running tasks in memory. The process tool manages those background sessions.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

exec tool

주요 항목:

Foreground runs return output directly.
When backgrounded (explicit or via yieldMs timeout), the tool returns status: "running" + sessionId and a short output tail.
Backgrounded and yieldMs runs inherit tools.exec.timeoutSeconds unless the call passes an explicit timeout.
Output stays in memory until the session is polled or cleared.
If the process tool is disallowed, exec runs synchronously and ignores yieldMs/background.
Spawned exec commands receive OPENCLAW_SHELL=exec for context-aware shell/profile rules.
For long-running work that starts now: start it once and rely on automatic completion wake (when enabled) once the command emits output or fails.
If automatic completion wake is unavailable, or you need quiet-success confirmation for a command that exits cleanly with no output, poll with process.
Don't emulate reminders or delayed follow-ups with sleep loops or repeated polling — use cron for future work.

Parameter	Description
`command`	Required. Shell command to run.
`workdir`	Working directory; omit to use the default cwd.
`env`	Extra environment variables for the command.
`yieldMs`	Milliseconds to wait before backgrounding (default 10000).
`background`	Run in background immediately.
`timeout`	Timeout in seconds (default `tools.exec.timeoutSeconds`); kills the process on expiry. Set `timeout: 0` to disable the exec process timeout for that call.
`pty`	Run in a pseudo-terminal when available (TTY-required CLIs, coding agents).
`elevated`	Run outside the sandbox if elevated mode is enabled/allowed (`gateway` by default, or `node` when the exec target is `node`).
`host`	Exec target: `auto`, `sandbox`, `gateway`, or `node`.
`node`	Node id/name, used with `host: "node"`.

Env overrides

Variable	Effect
`OPENCLAW_BASH_YIELD_MS`	Default yield before backgrounding (ms). Default 10000, clamped 10-120000.
`OPENCLAW_BASH_MAX_OUTPUT_CHARS`	In-memory output cap (chars).
`OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS`	Pending stdout/stderr cap per stream (chars).
`OPENCLAW_BASH_JOB_TTL_MS`	TTL for finished sessions (ms), bounded to 1m-3h.
`OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS`	Idle-output threshold before writable background sessions are marked as likely waiting for input. Default 15000.

Config (preferred over env overrides)

Key	Default	Effect
`tools.exec.backgroundMs`	10000	Same as `OPENCLAW_BASH_YIELD_MS`.
`tools.exec.timeoutSeconds`	1800	Default per-call timeout.
`tools.exec.cleanupMs`	1800000	Same as `OPENCLAW_BASH_JOB_TTL_MS`.
`tools.exec.notifyOnExit`	true	Enqueue a system event + request heartbeat when a backgrounded exec exits.
`tools.exec.notifyOnExitEmptySuccess`	false	Also enqueue completion events for successful backgrounded runs with no output.

Child process bridging

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

process tool

주요 항목:

Only backgrounded sessions are listed/persisted — in memory only, not on disk. Sessions are lost on process restart.
A live background session blocks cooperative host suspension and safe Gateway restart until the process owner confirms its actual exit.
process remove can hide a running session immediately after requesting termination; suspension and restart remain blocked until exit confirmation.
Session logs are only saved to chat history if you run process poll/log and the tool result is recorded.
process is scoped per agent; it only sees sessions started by that agent.
Use poll/log for status, logs, or completion confirmation when automatic completion wake is unavailable.
Use log before recovering an interactive CLI, so the current transcript, stdin state, and input-wait hint are visible together.
Use write/send-keys/submit/paste/kill when you need input or intervention.
process list includes a derived name (command verb + target) for quick scans.
process list, poll, and log report waitingForInput only when the session still has writable stdin and has been idle longer than the input-wait threshold (default 15000 ms, OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS).
process log uses line-based offset/limit. When both are omitted, it returns the last 200 lines with a paging hint. When offset is set and limit isn't, it returns from offset to the end (not capped to 200).
poll's timeout waits up to that many milliseconds before returning; values above 30000 are clamped to 30000.
Polling is for on-demand status, not wait-loop scheduling. If the work should happen later, use cron.

Action	Effect
`list`	Running + finished sessions.
`poll`	Drain new output for a session (also reports exit status).
`log`	Read aggregated output and input-recovery hints. Supports `offset` + `limit`.
`write`	Send stdin (`data`, optional `eof`).
`send-keys`	Send explicit key tokens or bytes to a PTY-backed session.
`submit`	Send Enter/carriage return to a PTY-backed session.
`paste`	Send literal text, optionally wrapped in bracketed paste mode.
`kill`	Terminate a background session.
`clear`	Remove a finished session from memory.
`remove`	Kill if running, otherwise clear if finished.

예제

Inspect an interactive session before sending input:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

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

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

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

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/background-process
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

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

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

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

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

{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }

Background exec and process tool

핵심 요약

문서 구성

상세 내용

본문

exec tool

Env overrides

Config (preferred over env overrides)

Child process bridging

process tool

예제

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Background exec and process tool

핵심 요약

문서 구성

상세 내용

본문

exec tool

Env overrides

Config (preferred over env overrides)

Child process bridging

process tool

예제

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드