Claude Code: 백그라운드 명령 30분 제한

Claude Code는 무인으로 실행될 때 백그라운드 명령을 30분 후 중지합니다. -p 플래그를 사용해 실행하거나, Agent SDK 애플리케이션, CI 작업 또는 클라우드 세션에서 실행하는 경우가 이에 해당합니다. Claude가 명령 자체의 실행 시간을 지정하면 최대 2시간 동안 실행됩니다. 일반 터미널, 데스크톱 앱, VS Code에는 버전 2.1.288부터 제한 시간이 없습니다.

예전에는 하루 종일 화면 앞에 앉아 있었습니다. 에이전트에게 단계를 맡기고, 결과를 확인하고, 수정한 뒤 계속하라고 요청했습니다. 단계마다 반복했습니다. 기계가 코드를 작성하고 있었을지 몰라도, 에이전트를 이끄는 건 저였습니다. 지금은 계획을 세우고 단계별로 나눈 다음, 구현을 서브에이전트에게 맡기고 밤새 자리를 비웁니다. 제가 없는 8시간 동안 Claude는 계획에 따라 조사하고, 만들고, 다듬습니다. 아침에는 결과를 다시 만드는 시간보다 작업을 승인하는 데 더 많은 시간을 씁니다.

하지만 밤샘 실행에서 -p를 사용하거나 서버에서 예약 실행하거나 CI 또는 클라우드에서 실행하면, 개발 서버와 백그라운드에서 실행 중인 빌드는 30분 동안만 실행됩니다. 그 뒤 Claude Code가 이를 중지하므로 밤샘 작업이 중간에 멈출 수 있습니다. 어떤 경우에 제한 시간이 적용되는지, 늘리는 방법은 무엇인지, 명령이 이미 중지된 경우 어떻게 해야 하는지 설명하겠습니다. 시작하겠습니다.

서비스 사용에 관한 도움말은 Ailoot 문서를 참고하세요.

제한 시간이 적용되는 대상#

백그라운드 명령은 Claude가 시작한 뒤 다른 작업을 하는 동안 계속 실행되도록 둔 명령입니다. 예를 들어 npm run dev로 시작한 개발 서버나 파일 변경 사항을 감시하는 빌드가 있습니다.

Claude Code 문서에는 다음과 같이 나와 있습니다.

다시 말해, 자리를 비운 동안 실행되는 경우에 제한 시간이 적용됩니다. -p 실행, Agent SDK 애플리케이션, CI 작업 또는 클라우드 세션이 이에 해당합니다. 직접 세션에서 작업하는 동안에는 터미널, 데스크톱 앱 또는 VS Code에 제한 시간이 없습니다. 이 제한은 2.1.285에서 도입됐으며, 2.1.288 이전에는 모든 세션에 적용됐습니다.

내게 해당하는지 확인하는 방법은 다음과 같습니다.

• 터미널이나 VS Code에서 Claude Code를 열고 작업을 맡긴 다음 잠자리에 들었습니다. 버전이 2.1.288 이상이면 제한 시간이 없습니다. 2.1.285부터 2.1.287까지는 여기에도 적용됩니다. 최신 버전으로 업데이트하는 방법은 별도 문서에서 설명했습니다.
• 예약 실행이나 직접 만든 Agent SDK 애플리케이션 또는 CI에서 claude -p "task"로 Claude Code를 실행합니다. 제한 시간이 적용됩니다.
• 클라우드 세션에서 작업이 실행됩니다. 제한 시간이 적용됩니다.

에이전트가 독립적으로 작업하도록 설정할 때는 프롬프트에 다음과 같이 적습니다. “이 조건과 중지 이유를 작업 계획에 기록하세요. 닫을 창이나 컴퓨터 자체에 프로세스가 의존하지 않는지 확인하세요.” 30분 제한도 그런 이유 중 하나입니다.

백그라운드 명령은 얼마나 오래 실행되나요?#

명령이 백그라운드로 이동하면 카운트다운이 시작됩니다. 두 가지 경우가 있습니다.

Claude가 명령을 즉시 백그라운드에서 시작합니다. 30분이 주어집니다. Claude가 시작할 때 시간을 지정하면(timeout 매개변수), 그 시간만큼 실행되지만 최대 2시간을 넘을 수 없습니다.

Claude가 기다리는 동안 명령이 끝나지 않습니다. 일반 명령은 Claude가 2분 동안 기다립니다. 끝나지 않으면 Claude Code는 명령을 중지하는 대신 백그라운드로 옮깁니다. 그 시점부터 30분이 주어집니다.

시간이 다 되면 Claude Code가 명령을 중지하고 Claude에 다음과 같이 알립니다.

Background command "<description>" was stopped after reaching its background time limit

작업이 끝나지 않았다면 Claude는 더 긴 시간을 지정해 명령을 다시 실행할 수 있습니다.

-p 실행에 관한 점도 하나 더 있습니다. 이런 유형의 실행에서는 Claude의 최종 응답 후 약 5초가 지나면 백그라운드 명령이 종료됩니다. 밤샘 -p 실행에서 시작한 서버는 실행 자체가 지속되는 동안만 유지됩니다. 실행 시간이 더 길 때 30분 제한이 중요해집니다. 예를 들어 Claude가 처음에 서버를 시작한 뒤 한 시간 동안 서버를 대상으로 검사를 수행하는 경우입니다.

Claude Code에서 밤샘 작업 구성하기#

하루 종일 에이전트를 이끄는 데 지쳐서 하나의 오케스트레이터 프롬프트로 바꿨습니다. 저녁에 실행하면 Claude는 밤새 순서대로 단계를 진행하며 글을 쓰고, 확인하고, 수정하고, 자체적으로 커밋합니다.

서브에이전트 그룹이 각자 별도의 파일을 맡아 서로 방해하지 않으면서 코드를 작성합니다. 새로 구성한 다른 그룹이 작업을 검토하고 코드 리뷰, 보안 검사 및 실시간 점검을 수행합니다. 문제가 발견되면 바로 수정하고 검사를 다시 실행합니다. 프롬프트에는 다음 문구가 들어 있습니다. “컨텍스트가 부족해지면 현재 상태를 기록하세요. 다음 실행에서 이어서 진행합니다.”

소개된 사례에서는 3일 동안 14개 단계 중 8개를 이런 방식으로 완료했습니다.

유의할 점은 두 가지뿐입니다. 오케스트레이터가 대신 생각해 주지는 않습니다. 먼저 단계별 상세 계획을 작성한 뒤 밤샘 작업을 시작하세요. 그리고 구독 사용량을 많이 소모하므로 작은 작업에는 설정할 필요가 거의 없습니다. 시도 횟수를 반드시 제한하세요. 그렇지 않으면 에이전트가 밤새 구독 사용량을 모두 소모할 수 있습니다. 지출 한도를 설정하는 방법은 별도 문서에서 설명했습니다.

제한 시간 늘리는 방법#

옵션 1: Claude에 요청하기. 특정 명령의 실행 시간은 Claude가 정하며 사용자가 직접 설정하지 않습니다. 하지만 작업에 “개발 서버를 백그라운드에서 2시간 동안 유지하세요.”라고 적을 수 있습니다. 이렇게 해도 최대 2시간까지입니다.

옵션 2: 설정 파일의 변수 사용하기. 값은 밀리초 단위입니다. 제한을 30분과 2시간보다 짧게 줄일 수는 없고, 늘리기만 할 수 있습니다.

• BASH_DEFAULT_TIMEOUT_MS를 1800000(30분)보다 크게 설정하면 기본값인 30분이 변경됩니다. 이 설정은 Claude가 실행 시간을 지정하지 않고 백그라운드에서 시작한 명령과 시간 초과 후 백그라운드로 옮겨진 명령 모두에 적용됩니다. 7200000(2시간)보다 크게 설정하면 최대 실행 시간도 늘어납니다.
• BASH_MAX_TIMEOUT_MS를 7200000보다 크게 설정하면 최대 실행 시간인 2시간이 늘어납니다. 기본값인 30분은 바뀌지 않으므로 실행 시간을 따로 지정하지 않은 명령은 계속 30분 후 중지됩니다.

BASH_DEFAULT_TIMEOUT_MS에는 부작용이 있습니다. 같은 변수가 Claude가 일반 명령을 기다리다가 백그라운드로 옮기기까지의 시간도 설정합니다. 이 값을 1시간으로 설정하면 Claude는 2분이 아니라 1시간 동안 기다립니다. 밤샘 작업에는 지장이 없습니다. 낮에는 명령 실행 시간이 길 경우 응답을 더 오래 기다려야 합니다.

세부 설정이 번거롭다면, 일반 명령과 최대 실행 시간 모두 3시간이 필요한 경우 BASH_DEFAULT_TIMEOUT_MS를 10800000으로 설정하세요. 그것으로 충분하며 두 번째 변수는 필요하지 않습니다.

설정 파일은 홈 디렉터리의 .claude 폴더에 있습니다. macOS와 Linux에서는 ~/.claude/settings.json, Windows에서는 %USERPROFILE%\.claude\settings.json입니다. 파일이 없으면 새로 만드세요. 1시간 제한은 다음과 같이 설정할 수 있습니다.

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "3600000"
  }
}

파일에 env 블록이 이미 있으면 그 안에 줄을 추가하세요. 파일을 저장하면 실행 중인 세션에서 새 값을 적용합니다. 변수를 삭제한 경우에는 다음에 claude를 시작할 때부터 반영됩니다.

파일은 에이전트가 실행되는 컴퓨터에 있어야 합니다. 에이전트가 밤새 작업하려면 컴퓨터가 절전 모드로 전환되지 않아야 합니다. 또는 원격 서버에서 Claude Code를 실행하고 그곳에 설정을 넣으세요.

명령이 이미 중지된 경우#

직접 처리할 필요는 없습니다. Claude Code는 명령이 중지된 이유를 Claude에 알리므로 우선 무슨 일이 있었는지 Claude에 물어보세요.

그런 다음 단계별로 진행하세요.

1. 최대 2시간 동안 한 번만 실행하는 경우. Claude에 더 긴 시간을 지정해 명령을 다시 실행하라고 요청하세요.
2. 명령에 30분 이상이 자주 필요합니다. 위 예시처럼 설정 파일에서 BASH_DEFAULT_TIMEOUT_MS를 1800000보다 크게 설정하세요. 2시간 이상이 필요하면 BASH_MAX_TIMEOUT_MS도 7200000보다 크게 설정하세요.
3. 명령을 다시 실행하세요. 문서에서는 변경 전에 이미 백그라운드에서 실행 중이던 명령에 대해 보장하지 않습니다.
4. 다음 실행 결과를 확인하세요. Claude의 보고서에 “stopped after reaching its background time limit”라는 문구가 다시 있으면 해당 명령에는 설정이 적용되지 않은 것입니다.

서브에이전트와 루틴을 활용하면 자리를 비운 동안에도 에이전트가 계속 작업할 수 있습니다.

에이전트를 밤새 반복 실행하는 방법은 별도 문서에서 설명했습니다. 밤새 Claude Code가 프로젝트를 손상시키지 않도록 설정하는 방법은 여기에서 확인할 수 있습니다.

밤샘 실행을 중지시키는 단계가 무엇인지 확인하고, 그 이유를 위 제한 사항과 비교하세요.

Ailoot를 만나보세요.