​

백그라운드 Exec + Process Tool

​

exec tool

• command (필수)
• yieldMs (기본값 10000): 이 지연 후 자동으로 백그라운드 전환
• background (bool): 즉시 백그라운드 전환
• timeout (초, 기본값 1800): 이 타임아웃 후 프로세스 종료
• elevated (bool): elevated 모드가 활성화/허용된 경우 샌드박스 밖에서 실행(기본값은 gateway, exec 대상이 node이면 node)
• 실제 TTY가 필요하신가요? pty: true를 설정하세요.
• workdir, env

• 포그라운드 실행은 출력을 직접 반환합니다.
• 백그라운드로 전환되면(명시적 또는 타임아웃), 도구는 status: "running" + sessionId와 짧은 tail을 반환합니다.
• 출력은 세션이 폴링되거나 정리될 때까지 메모리에 유지됩니다.
• process 도구가 허용되지 않으면 exec는 동기적으로 실행되며 yieldMs/background를 무시합니다.
• 생성된 exec 명령은 컨텍스트 인식 셸/프로필 규칙을 위해 OPENCLAW_SHELL=exec를 받습니다.
• 지금 시작하는 장시간 작업의 경우, 한 번만 시작하고 자동 완료 wake가 활성화되어 있으며 명령이 출력을 내거나 실패할 때 이를 활용하세요.
• 자동 완료 wake를 사용할 수 없거나, 출력 없이 정상 종료된 명령의 조용한 성공 확인이 필요하다면 process를 사용해 완료를 확인하세요.
• sleep 루프나 반복 폴링으로 알림 또는 지연된 후속 작업을 흉내 내지 마세요. 미래 작업에는 cron을 사용하세요.

​

자식 프로세스 브리징

• 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가 종료되면 시스템 이벤트를 큐에 넣고 heartbeat를 요청합니다.
• tools.exec.notifyOnExitEmptySuccess (기본값 false): true이면, 출력 없이 성공한 백그라운드 실행에 대해서도 완료 이벤트를 큐에 넣습니다.

​

process tool

• list: 실행 중 + 완료된 세션
• poll: 세션의 새 출력을 드레인(종료 상태도 보고)
• log: 집계된 출력 읽기(offset + limit 지원)
• write: stdin 전송(data, 선택적 eof)
• send-keys: PTY 기반 세션에 명시적 키 토큰 또는 바이트 전송
• submit: PTY 기반 세션에 Enter / carriage return 전송
• paste: 리터럴 텍스트 전송, 선택적으로 bracketed paste mode로 래핑
• kill: 백그라운드 세션 종료
• clear: 완료된 세션을 메모리에서 제거
• remove: 실행 중이면 종료, 아니면 완료된 경우 정리

• 백그라운드로 전환된 세션만 메모리에 나열/유지됩니다.
• 세션은 프로세스 재시작 시 사라집니다(디스크 영속성 없음).
• 세션 로그는 process poll/log를 실행하고 도구 결과가 기록될 때만 채팅 기록에 저장됩니다.
• process는 에이전트별 범위입니다. 해당 에이전트가 시작한 세션만 볼 수 있습니다.
• 상태, 로그, 조용한 성공 확인, 또는 자동 완료 wake를 사용할 수 없을 때의 완료 확인에는 poll / log를 사용하세요.
• 입력 또는 개입이 필요할 때는 write / send-keys / submit / paste / kill을 사용하세요.
• process list에는 빠른 확인을 위한 파생 name(명령 동사 + 대상)이 포함됩니다.
• process log는 줄 기반 offset/limit를 사용합니다.
• offset과 limit가 모두 생략되면 마지막 200줄을 반환하고 페이지 힌트를 포함합니다.
• offset이 제공되고 limit가 생략되면 offset부터 끝까지 반환합니다(200줄 제한 없음).
• 폴링은 온디맨드 상태 확인용이지 대기 루프 스케줄링용이 아닙니다. 작업이 나중에 실행되어야 한다면 cron을 사용하세요.

​

예시

{ "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" }

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

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

{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }