백그라운드 Exec + 프로세스 도구

OpenClaw는 exec 도구를 통해 셸 명령어를 실행하고, 장시간 실행되는 작업을 메모리에 유지합니다. process 도구로 이러한 백그라운드 세션을 관리합니다.

exec 도구

주요 매개변수:

command (필수)
yieldMs (기본값 10000): 이 시간 후 자동으로 백그라운드로 전환
background (bool): 즉시 백그라운드로 전환
timeout (초, 기본값 1800): 이 타임아웃 후 프로세스 종료
elevated (bool): 승격 모드가 활성화/허용된 경우 호스트에서 실행
실제 TTY가 필요한 경우 pty: true를 설정하세요.
workdir, env

동작:

포그라운드 실행은 출력을 직접 반환합니다.
백그라운드 전환 시(명시적 또는 타임아웃), 도구는 status: "running" + sessionId와 짧은 tail을 반환합니다.
출력은 세션이 폴링되거나 지워질 때까지 메모리에 유지됩니다.
process 도구가 비허용된 경우, exec는 동기적으로 실행되며 yieldMs/background를 무시합니다.
생성된 exec 명령어는 컨텍스트 인식 셸/프로필 규칙을 위해 OPENCLAW_SHELL=exec를 수신합니다.

자식 프로세스 브릿징

exec/process 도구 외부에서 장시간 실행되는 자식 프로세스를 생성할 때(예: CLI 재생성 또는 게이트웨이 헬퍼), 자식 프로세스 브릿지 헬퍼를 연결하여 종료 시그널이 전달되고 종료/오류 시 리스너가 분리되도록 합니다. 이렇게 하면 systemd에서 고아 프로세스를 방지하고 플랫폼 간 종료 동작의 일관성을 유지합니다.

환경 오버라이드:

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: 실행 중이면 종료, 그렇지 않으면 완료된 경우 지우기

참고:

백그라운드된 세션만 메모리에 나열/유지됩니다.
프로세스 재시작 시 세션이 손실됩니다 (디스크 영속성 없음).
세션 로그는 process poll/log를 실행하고 도구 결과가 기록된 경우에만 채팅 히스토리에 저장됩니다.
process는 에이전트별로 범위가 지정됩니다. 해당 에이전트가 시작한 세션만 볼 수 있습니다.
process list에는 빠른 스캔을 위한 파생된 name (명령어 동사 + 대상)이 포함됩니다.
process log는 줄 기반 offset/limit을 사용합니다.
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 }

stdin 전송:

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