29. Exec failed (signal SIGTERM)로 중간 종료될 때 해결

Exec failed ... signal SIGTERM가 보이면, 많은 사람이 바로 “명령이 이상하다”부터 의심한다. 그런데 OpenClaw 운영에서는 실제로 명령 자체가 틀린 경우보다 실행 방식이 잘못 맞춰진 경우가 더 많다. 오래 걸리는 작업을 foreground로 붙잡고 있었거나, 대화형 CLI인데 pty: true가 빠졌거나, 조용히 오래 도는 작업인데 timeout이 너무 짧았던 식이다.

공식 Background Exec + Process Tool 문서 기준으로 exec는 yieldMs가 지나면 background로 넘길 수 있고, timeout 기본값은 1800초다. 즉 SIGTERM은 “완전 미스터리한 죽음”이라기보다, OpenClaw가 정리해야 한다고 판단한 종료 신호일 때 자주 보인다.

핵심은 하나다. 이 작업이 짧은 foreground 작업인지, 오래 도는 background 작업인지, 아니면 TTY가 필요한 대화형 작업인지 먼저 구분해야 한다. 그 구분만 맞으면 복구 속도가 훨씬 빨라진다.

flowchart TD
A[Exec failed + signal SIGTERM 확인] --> B{작업 성격은?}
B -->|짧은 단발성| C[foreground 유지]
B -->|오래 걸림| D[yieldMs 또는 background 사용]
B -->|대화형 CLI| E[pty true 사용]
D --> F{timeout 너무 짧은가?}
F -->|예| G[timeout 상향]
F -->|아니오| H[process poll/log로 확인]
E --> H
C --> I[명령 자체 오류 재점검]
G --> H
H --> J[성공/실패 원인 분리]

칠판 치트시트

1. SIGTERM이면 먼저 “명령 오류”보다 “실행 방식”을 의심한다
2. 오래 걸리면 yieldMs/background로 시작한다
3. 대화형 CLI면 pty: true를 먼저 붙인다
4. 오래 도는 작업은 timeout 값을 현실적으로 올린다
5. 조용한 성공 확인은 process poll/log로 한다

이런 증상이면 이 문서가 바로 맞다

아래 중 하나면, 거의 같은 계열 문제다.

• Exec failed (... signal SIGTERM)이 뜨고 작업이 중간에 끊긴다.
• 긴 빌드나 스크립트가 항상 비슷한 시간대에 종료된다.
• 인터랙티브 CLI가 바로 죽거나 입력을 못 받는다.
• 명령은 정상처럼 보이는데, 결과 없이 종료된 것처럼 보인다.

왜 SIGTERM이 나오는가

공식 문서에서 exec는 기본적으로 foreground 실행을 먼저 시도하고, yieldMs(기본 10000ms)가 지나면 background로 넘길 수 있다. 또 timeout 기본값은 1800초다. 이 말은 곧 다음 두 가지를 뜻한다.

첫째, 작업이 2초짜리인지 20분짜리인지 구분하지 않고 같은 방식으로 실행하면, 운영 중간에 체감이 어긋난다. 짧은 작업은 foreground가 편하지만, 긴 작업은 처음부터 background로 돌리는 편이 더 안정적이다.

둘째, SIGTERM은 시스템이 “이 프로세스를 정리해야 한다”고 보냈을 가능성이 크다. 그래서 원인 추적도 문법 오류보다 먼저 timeout, background 전환, PTY 필요 여부를 보는 게 실전적이다.

가장 빠른 복구 순서

1) 이 작업이 foreground인지 background인지 먼저 고른다

짧은 한두 줄 명령이라면 foreground로 바로 끝내는 편이 낫다. 반대로 빌드, 크롤링, 대형 변환, 테스트 묶음처럼 시간이 길어질 가능성이 있으면 시작부터 background 쪽으로 보는 게 안전하다.

공식 문서 표현대로, long-running work는 yieldMs 또는 background: true를 쓰고 process로 상태를 확인하는 흐름이 기본이다. 여기서 핵심은 “오래 걸릴 것 같은데 일단 일반 exec로 돌려보고 보자”가 아니라, 길어질 작업을 처음부터 길어질 작업으로 취급하는 것이다.

실무에서는 아래처럼 생각하면 된다.

• 10초 안팎이면 foreground 후보
• 수십 초~수분이면 yieldMs를 짧게 줘서 background 전환 후보
• 언제 끝날지 모르면 background: true 우선

2) 대화형 CLI면 pty: true부터 확인한다

공식 문서에 따르면 real TTY가 필요하면 pty: true를 써야 한다. 여기서 많이 헷갈리는 장면이 있다. 명령은 맞는데, CLI가 입력을 기다리거나 터미널 제어를 기대하는 순간 제대로 동작하지 않는 경우다. 이때는 명령이 틀린 게 아니라 터미널 조건이 안 맞아서 예상과 다르게 종료될 수 있다.

대표적인 예는 아래와 같다.

• Codex, Pi, OpenCode처럼 TTY를 기대하는 CLI
• curses/TUI 성격의 도구
• 실행 중 키 입력, 줄 편집, 진행 UI를 쓰는 프로그램

반대로 단순 python script.py, node build.js, bash script.sh처럼 비대화형 작업은 굳이 PTY가 필요 없는 경우가 많다.

3) 비슷한 시간대에 끊기면 timeout을 먼저 본다

공식 Background Exec + Process Tool 문서에는 timeout 기본값이 1800초라고 정리돼 있다. 그래서 작업이 늘 비슷한 시간대에 죽는다면, “랜덤 장애”보다 timeout 도달 쪽 가능성이 높다.

예를 들어 대형 테스트나 영상 변환, 대규모 문서 처리처럼 시간이 길어질 수 있는 작업을 30분 기본 설정 그대로 두면, 작업 내용은 정상이어도 운영에서는 SIGTERM으로 보일 수 있다.

이럴 때는 아래 순서가 안전하다.

1. 실제 예상 소요 시간을 보수적으로 잡는다.
2. 그보다 여유 있게 timeout을 늘린다.
3. 그래도 너무 길다면 작업 자체를 더 작은 단계로 나눈다.

즉, timeout을 무작정 크게만 올리는 게 아니라, 긴 작업을 작은 단계로 쪼갤지도 같이 판단해야 한다.

4) 조용한 성공인지 진짜 실패인지 process로 확인한다

공식 문서에는 background 세션의 상태와 로그를 process poll/log로 확인하라고 되어 있다. 이 단계가 중요한 이유는, 화면에 “조용하다”는 사실이 곧 실패를 뜻하지는 않기 때문이다. 어떤 작업은 정상 종료해도 로그를 거의 남기지 않는다.

이때는 다음처럼 구분하면 된다.

• 출력이 계속 생기는 작업: poll로 진행 상황 확인
• 이미 끝난 듯한 작업: log로 전체 로그 확인
• 성공인데 출력이 적은 작업: quiet-success 확인 용도로 process 사용

즉, 다시 같은 명령을 던지기 전에 기존 세션이 이미 끝났는지부터 확인하는 편이 중복 실행을 줄인다.

현장 미니 사례 3개

사례 A) 빌드가 10초쯤 지나면 자꾸 끊김

• 상황: 결과가 길게 나오기 전에 작업이 어색하게 종료됨
• 원인: 오래 걸릴 작업인데 foreground 감각으로만 사용
• 복구: yieldMs를 짧게 잡아 background로 넘기고 완료는 process로 확인
• 검증: 같은 명령을 두 번 재실행하지 않고, 기존 세션 상태부터 확인

사례 B) CLI가 바로 종료되고 입력도 안 먹음

• 상황: 명령은 맞는데 대화형 도구가 비정상 종료
• 원인: TTY 필요 도구인데 pty: true 누락
• 복구: PTY 모드로 다시 시작
• 검증: 인터랙티브 프롬프트/진행 UI가 실제로 보이는지 확인

사례 C) 항상 일정 시간 뒤에 SIGTERM

• 상황: 무거운 처리 작업이 거의 같은 구간에서 종료
• 원인: timeout 상한 도달 가능성 큼
• 복구: timeout 상향 + 작업 단위 분리
• 검증: 소요 시간과 종료 시점을 함께 기록해 같은 패턴이 사라졌는지 확인

운영자가 바로 판단하는 기준

아래 기준이면 대부분 빠르게 갈린다.

상황	먼저 바꿀 것	이유
오래 걸리는 빌드/테스트	yieldMs 또는 background	foreground로 붙잡을 이유가 적음
대화형 CLI	pty: true	TTY 없이 비정상 동작 가능
일정 시간 후 반복 종료	timeout	구조적 종료 가능성 높음
끝났는지 애매함	process poll/log	재실행보다 상태 확인이 우선

검색형 FAQ

Q1. SIGTERM이면 무조건 명령이 잘못된 건가요?

아니다. OpenClaw 운영에서는 명령 문법 오류보다 실행 모드 선택이 안 맞는 경우가 더 흔하다.

Q2. 오래 걸릴 것 같으면 yieldMs와 background: true 중 무엇을 쓰나요?

처음부터 오래 걸릴 게 확실하면 background: true가 단순하다. 애매하지만 조금 길 수 있으면 yieldMs로 자연스럽게 넘기는 쪽이 편하다.

Q3. output이 없으면 실패라고 봐야 하나요?

꼭 그렇지 않다. 공식 문서도 quiet-success 확인에 process를 쓰라고 안내한다. 조용한 성공과 진짜 실패를 구분해야 한다.

Q4. timeout만 크게 올리면 해결되나요?

항상 그렇지는 않다. 작업이 너무 크면 timeout을 올리는 대신 단계 분리가 더 좋은 해법일 수 있다.

다음 읽기

• 14. OpenClaw 답변 지연, 10분 먹통처럼 보일 때 해결
• 26. Subagent 돌렸는데 결과가 안 돌아올 때
• 28. OpenClaw 예전 세션이 계속 붙을 때 정리
• 16. cron 시간을 바꿨는데 예전 시각에 계속 돌 때
• 17. cron은 돌았는데 텔레그램 전달이 안 올 때
• 서브에이전트 분산운영
• 32. HEARTBEAT_OK 반복응답 해결
• systemd 충돌) 해결
• 34. 세션툴 블로그 검수 자동화
• 🚀 OpenClaw 인덱스

한 줄 결론

Exec failed (signal SIGTERM)은 대개 “명령이 완전히 틀렸다”보다 길이, TTY, timeout, background 전략이 안 맞았다에 더 가깝다.
작업 성격부터 나누고 yieldMs/background/pty/timeout을 맞추면 복구 속도가 훨씬 빨라진다.

※ 이 문서는 생성형 AI를 활용해 작성되었습니다.