
Claude Code v2.1.202~v2.1.203 | 백그라운드 에이전트 관련 수정 사항 총정리 | 매일 Changelog 해설
요약
Claude Code v2.1.202~v2.1.203 업데이트를 통해 백그라운드 에이전트의 안정성을 대폭 강화했습니다. 환경 변수 인식 오류, macOS 프리즈 현상, 서브 에이전트의 작업 승계 문제 등 주요 버그를 해결했습니다.
핵심 포인트
- ANTHROPIC_BASE_URL 환경 변수 미인식으로 인한 401 오류 수정
- macOS에서 발생하던 15~20초간의 실행 및 전환 프리즈 현상 해결
- 서브 에이전트가 중단되지 않고 작업을 이어갈 수 있도록 개선
- 동적 워크플로우 규모(small/medium/large) 설정 기능 추가
- 의존성 지연 로딩을 통한 메모리 사용량 절감
v2.1.203은 백그라운드 에이전트(Background Agent) 관련 수정이 대부분을 차지하는 안정화 릴리스입니다. 그중에서도 셸(Shell)에서 export한 ANTHROPIC_BASE_URL이 무시되어, API 키가 기본 엔드포인트(Default Endpoint)로 전송되어 401 오류가 발생하는 버그는 프록시(Proxy)나 자체 게이트웨이(Gateway)를 경유하는 사용자일수록 영향이 큽니다. macOS에서 실행 및 전환 시 15~20초간 멈추는 문제(2.1.196의 리그레션(Regression))도 해결되었습니다.
백그라운드/에이전트 뷰에서 셸 export 환경 변수가 무시되어 401로 실패하던 문제 수정 (v2.1.203): ANTHROPIC_BASE_URL이 누락되어 API 키가 기본 엔드포인트로 전송됨
macOS의 15~20초 프리즈(Freeze) 해소: 잘못된 메모리 부족 감지로 인해 백그라운드 세션의 실행 및 전환이 중단되던 문제 해결. 2.1.196의 리그레션 (v2.1.203)
서브 에이전트(Sub-agent)의 작업 승계: claude agents로 돌아오면 실행 중이던 서브 에이전트가 조용히 멈추고 프롬프트를 처음부터 다시 시작하던 문제 수정 (v2.1.203)
Dynamic workflow size 설정 추가: /config에서 동적 워크플로우(Dynamic Workflow)의 규모(small/medium/large)를 지정 가능. 강제 상한선이 아닌 가이드라인 역할 (v2.1.202)
스킬(Skill) 재로드 시 지시사항 중복 문제 수정: 이미 로드된 스킬을 다시 호출하면 지시사항의 복사본이 컨텍스트(Context)에 추가되던 문제 수정 (v2.1.202)
바이너리 및 실행 메모리 각각 7 MB 절감: 대규모 동봉 의존성을 지연 로드(Lazy Load)로 전환 (v2.1.203)
ANTHROPIC_BASE_URL을 셸의 export를 통해 사내 프록시나 자체 게이트웨이로 향하게 설정하는 구성은 흔합니다. 하지만 v2.1.203 이전에는 백그라운드 세션과 에이전트 뷰의 세션에서 이 변수가 누락되었습니다.
목적지는 기본 API 엔드포인트가 됩니다. 그곳으로 API 키가 그대로 전송되어 401로 거부됩니다. 단순히 작동하지 않는 것이 아니라, 키가 의도하지 않은 목적지로 전달된다는 점이 실질적인 피해입니다.
ANTHROPIC_BASE_URL을 셸의 export로 전달하고 있는 분들은 v2.1.203으로 업데이트한 후 백그라운드 실행을 시도해 보세요. 프록시를 경유해야 할 요청이 기본 엔드포인트에 도달하고 있지는 않은지 게이트웨이 측 로그에서 확인해 두는 것이 안전합니다.
대상 독자: claude agents나 백그라운드 실행, 워크트리(Worktree) 분리를 업무에 활용하고 있는 분.
2.1.203은 이 영역에서만 20건 이상의 수정을 진행했습니다. 실운영에서 체감될 주요 사항은 다음과 같습니다.
macOS 실행·전환 프리즈: 잘못된 메모리 부족 감지로 인해 15~20초간 정지하던 문제 해결 (2.1.196의 리그레션)
세션 자동 복구: 데몬(Daemon)의 세션 토큰이 오래되면 attach, 응답, stop 모두 무반응이었던 현상이 자동으로 복구됨
서브 에이전트 작업 승계: claude agents로 돌아오면 실행 중인 서브 에이전트가 중단되어 프롬프트를 처음부터 다시 시작하던 문제 수정
워크트리 분리 철저: 분리된 서브 에이전트가 부모 체크아웃(Parent Checkout)에서 명령을 실행하거나, 다중 리포지토리(Multi-repo) 구성에서 중첩된 repo의 분리에 실패하던 버그 수정
크래시 루프(Crash Loop) 제거: 작업 디렉토리가 삭제 또는 교체된 백그라운드 에이전트가 무한 크래시되지 않고, 명확한 에러와 함께 한 번만 종료됨
TaskStop / TaskOutput이 다른 에이전트에서 발생한 백그라운드 에이전트를 찾지 못하던 버그도 수정되었으며, 실패 시 실행 중인 에이전트를 ID와 설명으로 나열해 줍니다.
/config에 「Dynamic workflow size」 설정이 추가되어, 동적 워크플로우의 규모를 small / medium / large로 지정할 수 있습니다. 이는 에이전트 수의 상한을 강제하는 것이 아니라, Claude가 생성하는 규모의 가이드라인입니다.
또 하나 유용한 점은 스킬의 이중 로드 수정입니다. 이미 로드된 스킬을 다시 호출하면 해당 지시문의 복사본이 컨텍스트에 통째로 추가되었습니다. 이는 긴 세션에서 컨텍스트를 압박하던 원인 중 하나였습니다.
| 버전 | 카테고리 | 변경 사항 | 개요 |
|---|---|---|---|
| 2.1.203 | UI | 수동 허가 모드에 회색 ⏸ 배지 추가 | 푸터(Footer)에서 현재 모드를 항상 확인할 수 있음 |
| ... | 변경 시 notifications/roots/list_changed를 전송 | ||
| 2.1.203 | 성능 | 컨텍스트 사용량 표시의 재분석 폐지 | 매 턴(Turn)마다 전체 트랜스크립트(Transcript)를 분석하여 발생하던 메모리/CPU 악화 현상 수정 |
| 2.1.203 | 동작 | 왼쪽 화살표로 뷰(View)를 닫지 않음 | 백그라운드 태스크(Background Task)·diff·워크플로(Workflow) 상세 정보는 Esc 키로 닫음 |
| 2.1.202 | 네트워크 | 다운로드 자동 재시도 | 프록시(Proxy) 연결 끊김 시 「aborted」 상태로 즉시 실패하지 않음 |
| ... | /review <pr>을 단발성 리뷰로 복구 | 다단계 리뷰는 /code-review <level> <pr#> 사용 | |
2.1.203은 백그라운드 에이전트(Background Agent)의 신뢰성을 끌어올리는 수정 사항이 중심입니다. ANTHROPIC_BASE_URL 누락이나 macOS에서의 15~20초 프리징(Freezing) 등, 실제 운영 환경에서 뼈아팠던 버그들이 포함되어 있습니다. 평소 사용 중이라면, 업데이트를 통해 무반응·프리징·작업 소실과 같은 병목 지점들을 대부분 해결할 수 있습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Qiita AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기