백그라운드 실행 및 프로세스 도구

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

exec 도구

매개변수:

동작:

• 포그라운드 실행은 출력을 직접 반환합니다.
• 백그라운드로 전환되면(명시적으로 지정하거나 yieldMs 제한 시간이 지난 경우) 도구는 status: "running" + sessionId와 짧은 출력 끝부분을 반환합니다.
• 백그라운드 실행 및 yieldMs 실행은 호출에서 명시적인 timeout을 전달하지 않는 한 tools.exec.timeoutSec를 상속합니다.
• 출력은 세션을 폴링하거나 지울 때까지 메모리에 유지됩니다.
• process 도구가 허용되지 않으면 exec는 동기적으로 실행되며 yieldMs/background를 무시합니다.
• 생성된 exec 명령에는 상황 인식형 셸/프로필 규칙을 위해 OPENCLAW_SHELL=exec가 전달됩니다.
• 지금 시작하는 장시간 작업의 경우 한 번만 시작하고, 명령이 출력을 내거나 실패했을 때 자동 완료 깨우기(활성화된 경우)에 의존하세요.
• 자동 완료 깨우기를 사용할 수 없거나 출력 없이 정상 종료되는 명령의 무출력 성공을 확인해야 한다면 process로 폴링하세요.
• sleep 루프나 반복 폴링으로 알림 또는 지연된 후속 작업을 흉내 내지 마세요. 향후 작업에는 Cron을 사용하세요.

환경 변수 재정의

구성(환경 변수 재정보다 권장)

자식 프로세스 연결

exec/process 도구 외부에서 장시간 실행되는 자식 프로세스(CLI 재실행, Gateway 헬퍼)를 생성할 때는 종료 신호가 전달되고 종료/오류 시 리스너가 분리되도록 자식 프로세스 브리지 헬퍼를 연결하세요. 이렇게 하면 systemd에서 고아 프로세스가 생기는 것을 방지하고 플랫폼 전반에서 일관된 종료 동작을 유지할 수 있습니다.

process 도구

작업:

참고:

• 백그라운드 세션만 나열되고 유지됩니다. 디스크가 아닌 메모리에만 저장됩니다. 프로세스를 다시 시작하면 세션이 사라집니다.
• 활성 백그라운드 세션은 프로세스 소유자가 실제 종료를 확인할 때까지 협력적 호스트 일시 중단과 안전한 Gateway 재시작을 차단합니다.
• process remove는 종료를 요청한 직후 실행 중인 세션을 숨길 수 있지만, 종료가 확인될 때까지 일시 중단과 재시작은 계속 차단됩니다.
• 세션 로그는 process poll/log를 실행하여 도구 결과가 기록된 경우에만 채팅 기록에 저장됩니다.
• process의 범위는 에이전트별로 한정되며, 해당 에이전트가 시작한 세션만 볼 수 있습니다.
• 자동 완료 깨우기를 사용할 수 없는 경우 상태, 로그 또는 완료 확인을 위해 poll/log를 사용하세요.
• 대화형 CLI를 복구하기 전에 log를 사용하여 현재 기록, stdin 상태 및 입력 대기 힌트를 함께 확인하세요.
• 입력이나 개입이 필요할 때는 write/send-keys/submit/paste/kill을 사용하세요.
• 빠르게 훑어볼 수 있도록 process list에는 파생된 name(명령 동사 + 대상)이 포함됩니다.
• process list, poll, log는 세션에 여전히 쓰기 가능한 stdin이 있고 입력 대기 임계값(기본값 15000ms, OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS)보다 오랫동안 유휴 상태인 경우에만 waitingForInput을 보고합니다.
• process log는 줄 기반 offset/limit를 사용합니다. 둘 다 생략하면 페이징 힌트와 함께 마지막 200줄을 반환합니다. offset이 설정되고 limit가 없으면 offset부터 끝까지 반환합니다(200줄로 제한되지 않음).
• poll의 timeout은 반환하기 전에 해당 밀리초만큼 기다리며, 30000보다 큰 값은 30000으로 제한됩니다.
• 폴링은 요청 시 상태 확인을 위한 것이지 대기 루프 예약을 위한 것이 아닙니다. 작업을 나중에 수행해야 한다면 Cron을 사용하세요.

예시

장시간 작업을 실행하고 나중에 폴링하기:

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

stdin 전송하기:

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

PTY 키 전송하기:

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

관련 항목

• Exec 도구
• Exec 승인