대상 독자는 Claude Code에서 서브 에이전트나 워크플로우를 구동하며 컨텍스트 확장, 모델 비용, 과부하 오류(529)에 어려움을 겪는 분들입니다.
2026년 10월 9일에 공개된 Claude Code v2.1.296에서는 서브 에이전트 관련 설정이 3가지 추가되었습니다. 공식 changelog에는 한 줄씩만 적혀 있기 때문에, '어디에 작성해야 하는지', '어떤 설정과 충돌하는지'를 직접 설치한 v2.1.296에서 확인했습니다.
- 3가지 새 설정 각각이 무엇을 변경하는지
- 설정의 작성 위치(frontmatter와 환경 변수)
- 충돌하는 기존 설정과의 관계
- 확인된 것과, 아직 확인되지 않은 것들
changelog (v2.1.296)의 해당 행은 다음과 같습니다.
| 설정 | 종류 | 공식 설명 (요약) |
|---|
autoCompactWindow | 서브 에이전트의 frontmatter / --agents | 서브 에이전트가 메인 대화 창보다 빨리 자동 압축할 수 있음 |
CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL | 환경 변수 | 모든 워크플로우 에이전트를 하나의 모델로 구동하고, 다른 서브 에이전트는 각자의 모델을 유지함 |
CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS | 환경 변수 | 과부하(529) 재시도 시, 백오프의 최대 대기 시간을 더 길게 설정할 수 있음 |
출처는 Claude Code changelog 2.1.296 (2026-10-09)입니다.
확인에 사용한 환경은 Claude Code 2.1.296입니다.
$ claude --version
2.1.296 (Claude Code)
실행 파일 내부의 문자열을 검색하여, 3가지 이름이 실제로 존재하는지 개수를 세었습니다.
$ B=$(readlink -f $(which claude))
$ for k in CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS autoCompactWindow; do
> printf "%s: " $k; grep -a -o "$k" "$B" | wc -l
...
세 가지 모두 실행 파일에 포함되어 있었습니다. 이것만으로는 작동 여부를 알 수 없습니다. 그래서 주변 코드도 읽어 설정의 의미를 확인했습니다. 이 방법은 실행 파일 내부를 읽는 것이므로, 향후 버전에서 변경될 가능성이 있습니다. 아래 설명은 어디까지나 2.1.296 범위 내에서의 관찰입니다.
에이전트 정의 스키마에는 다음 설명이 적혀 있었습니다.
autoCompactWindow: 정수 (최소 100000・최대 1000000)
Token count at which this agent compacts its own conversation when it runs as a subagent.
It only lowers the window the subagent would otherwise inherit. No effect on the main session agent.
읽을 수 있는 것은 세 가지입니다.
- 값은 정수이며, 범위가 있습니다. 범위의 숫자(10만~100만)는 스키마가 참조하는 상수를 실행 파일에서 읽은 값입니다.
- 상속받는 창을 '낮추는' 것만 할 수 있습니다. 메인 대화보다 큰 값을 지정해도, 창이 넓어지지는 않습니다.
- 메인 세션 에이전트에는 영향을 미치지 않습니다.
작성 방법은 에이전트의 frontmatter에 한 줄 추가하는 것만으로 충분합니다.
---
name: log-reader
description: 큰 로그를 읽고 요점만 반환
...
이 예시 설명은 스키마 필드명과 타입에 맞춰 작성된 것입니다. 실제로 서브 에이전트를 구동하여 압축이 발생하는 모습까지는 확인하지 못했습니다 (후술).
실행 파일 내부의 에이전트 정의 허용 필드 목록에도 autoCompactWindow가 나열되어 있었습니다. maxTurns와 skills 사이에 있습니다.
changelog에는 알 수 없는 frontmatter 필드를 --debug로 지정하는 개선 사항도 같은 버전으로 포함되어 있습니다. 오타(예: autoCompactWindows)를 발견하기 쉬워집니다.
환경 변수 정의표에서 기존의 2개와 나란히 등록되어 있었습니다.
CLAUDE_CODE_SUBAGENT_MODEL
CLAUDE_CODE_SUBAGENT_MODEL_FORCE
CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL
또한, 워크플로우 에이전트가 개별적으로 모델을 지정했을 때 다음과 같은 형태의 메시지가 나오는 분기점이 있었습니다.
Workflow agent model "<지정된 모델>" ignored: <이유>
이유로써 CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL is set과 CLAUDE_CODE_SUBAGENT_MODEL_FORCE is on의 두 가지 종류의 문자열이 실행 파일에 있었습니다. 즉, 둘 중 어느 것이 설정되어 있으면 워크플로우 내에서 개별적으로 지정한 모델은 무시되는 구조입니다.
사용법 정리 내용은 다음과 같습니다.
| 목적 | 사용할 설정 |
|---|
| 정의나 호출 시 모델을 지정하지 않은 서브 에이전트의 기본값을 정하고 싶을 때 | CLAUDE_CODE_SUBAGENT_MODEL |
| ... | CLAUDE_CODE_SUBAGENT_MODEL와 CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 병용 |
공식 문서에서는, CLAUDE_CODE_SUBAGENT_MODEL은 정의의 model이나 호출 시 지정이 없는 에이전트의 기본값이며, v2.1.251 이후로는 이를 덮어쓰지 않습니다. 모두를 통일하려면 CLAUDE_CODE_SUBAGENT_MODEL_FORCE 병용이 필요합니다. 이 리포지토리 운영에서는 역할별로 모델을 분리하고 있기 때문에, CLAUDE_CODE_SUBAGENT_MODEL을 전역으로 두지 않는 방침입니다 (지정되지 않은 에이전트가 일률적으로 같은 모델이 되기 때문). 워크플로우 전용 변수는 영향 범위가 좁으므로, 워크플로우만 저렴한 모델로 맞추고 싶을 때의 선택지가 됩니다. 참고로, CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL과 autoCompactWindow는 기사 작성 시점에서는 공식 문서 설정 목록에 항목이 없으며, changelog가 유일한 공식 근거입니다. 개별 지정이 무시된다는 해석은 실행 파일에서 나온 것이므로, 실제로 설정하여 확인하기 전까지는 운영에 넣지 않는 편이 안전합니다.
재시도 대기 시간을 정하는 부분을 읽어보면, 환경 변수는 '과부하(529)로 판정된 경우'에만 참조되고 있었습니다.
과부하로 판정된 경우:
최대 대기 시간 = CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS
기준 대기 시간 = CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS
...
대기 시간을 계산하는 함수는 시도 횟수・기준값・상한・난수를 받아 25%의 비율의 지터(jitter, 변동성)를 추가합니다. 상한의 기본 인수는 32000 밀리초였습니다. 즉, 과부하일 때만 상한을 늘릴 수 있는 설정입니다. 다른 오류 재시도에는 영향을 미치지 않습니다.
이름이 비슷한 CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS는 2.1.295에서 들어간 또 다른 설정입니다. 무인 재시도 모드(CLAUDE_CODE_RETRY_WATCHDOG)가 429와 529를 기다리는 시간을 제한합니다. 오래 기다리게 하고 싶은 설정과, 너무 많이 기다리는 것을 막는 설정이 분리되어 있다는 점에 주의해야 합니다.
두 환경 변수는 쉘에서 export하는 것 외에도 프로젝트의 .claude/settings.json
또는 env에 작성하는 방법도 있습니다. 팀원들과 같은 설정을 공유하고 싶을 때는, 이곳이 버전 관리에 올리기 쉬운 위치입니다.
{
"env": {
"CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL": "sonnet",
...
}
값의 sonnet과 120000은 작성 예시일 뿐, 권장 값은 아닙니다. 모델명은 사용하고 있는 프로바이더에서 통하는 지정에 맞추어 주세요.
다음 3가지는 이번 확인 범위에 포함되지 않았습니다.
- 실제 압축 작동 방식:
autoCompactWindow를 지정한 서브 에이전트를 구동했을 때, 압축이 실행되는 타이밍은 확인하지 못했습니다. - 환경 변수 간 우선순위: 문자열과 분기에서 읽을 수 있는 범위 내에서 실제로 설정하고 동작시켜 보지는 않았습니다. - 529의 실 환경 대기 시간: 과부하를 재현할 수 없기 때문에, 재시도 간격의 실제 측정은 하지 못했습니다.
이 환경에서는 모델 API를 새로 호출하는 검증을 진행하지 않고, 실행 파일 내용과 공식 changelog 비교에만 그쳤습니다.
우선순위를 매긴다면 다음 순서입니다.
- autoCompactWindow: 대량의 파일을 읽는 서브 에이전트가 하나 있다면, 해당 에이전트의 frontmatter에 한 줄 추가하는 것만으로 충분합니다. 메인에는 영향을 주지 않기 때문에 시도할 때 실패 비용이 작은 설정입니다. - WORKFLOW_SUBAGENT_MODEL: 워크플로우를 사용하면서 모델 비용을 낮추고 싶을 때 고려해 봅니다. - OVERLOADED_RETRY_MAX_DELAY_MS: 무인 운영에서 529에 걸려 멈출 수 있는 경우에만, 최대 대기 시간을 늘립니다.
changelog는 한 줄씩 요약되어 있어, '줄이는 것만', '529일 때만'과 같은 제약이 적혀 있지 않았습니다. 스키마 설명문과 분기를 읽어보면 이 두 가지를 알 수 있습니다. 설정명만으로 판단하면, autoCompactWindow를 크게 해서 창을 넓힐 수 있다고 오해하기 쉬운 설정입니다.
-
v2.1.296에서 서브 에이전트의 압축 창 및 워크플로우 전용 모델, 529 최대 대기 시간을 설정할 수 있게 되었음
-
autoCompactWindow는 상속된 창을 줄이는 것만으로 메인에는 영향을 주지 않음 - 워크플로우 전용 모델 변수는 기존의 전체 지정/강제 지정과 나란히 있는 별도의 설정임
-
과부하 최대 대기 시간은 529일 때만 참조됨
-
실제 동작은 미확인이며, 도입 전에 자신의 환경에서 확인이 필요함
-
Claude Code v2.1.129-136 신규 기능 해설 — plugin-url・project purge・effort hook
-
Claude Code Agent View 입문 — 여러 세션을 한 화면에서 관리하는 CLI 대시보드
-
Claude Code Dynamic Workflows 입문 — 병렬 서브 에이전트로 대규모 작업을 자동화하는
