Claude Code v2.1.307 업데이트: API 버전 관리 및 모니터링 강화
Claude Code v2.1.307 릴리스가 공개되었습니다. 이번 업데이트는 최신 API 버전 전환 지원과 관측 가능성(OpenTelemetry) 및 도구 호출의 안정성 향상에 초점을 맞추었습니다. 사용 환경에서 새롭게 활용할 수 있는 주요 기능들을 정리해 드립니다.
- /claude-api 명령어에 api-version 설정 추가 (API 버전 2026-10-21 지원)
- OpenTelemetry에 claude_code.safety_event 이벤트 추가하여 보안 추적 강화
- 구문 분석 실패 도구 호출 시 최대 2회 자동 재시도 메커니즘 도입
- 코드 리뷰 기능에 @claude review stop 명령어 추가
릴리스 노트 모아 보기
공식 릴리스 노트에 적힌 43개 항목을 원래 순서를 지켜 한 줄에 한 항목씩 적었습니다. 원문에서 빼거나 원문에 없는 내용을 더한 항목은 없습니다.
- Claude API 코드를 API 버전 `2026-10-21`로 이전하는 `/claude-api api-version`을 추가했습니다
- 권한 규칙, 자동 모드, 안전 검사, 훅 또는 샌드박스가 도구 호출을 중단하거나 확인을 요청하거나 되돌려보낼 때마다 발생하는 `claude_code.safety_event` OpenTelemetry 이벤트를 추가했습니다
- `CLAUDE_CODE_DISABLE_1M_CONTEXT`가 설정되어 있고 모델이 `opus[1m]`처럼 `[1m]` 접미사가 붙은 별칭일 때 요청이 모델을 찾을 수 없음 오류로 실패하던 문제를 고쳤습니다
- 아무런 효과가 없는 커스텀 `ANTHROPIC_BASE_URL` 게이트웨이 뒤 및 Foundry 환경에서 `prompt-caching-scope` 베타 헤더가 전송되던 문제를 고쳤습니다
- macOS에서 로그인 키체인이 잠겨 있을 때 `claude -p`에서 MCP 서버가 "인증 필요"로 표시되던 문제를 고쳤습니다. 이제 이유를 안내하며 잠금 해제 후 다음 실행 시 새로 로그인하지 않고도 연결됩니다
- macOS 또는 Linux 컴퓨터가 MCP 서버 연결 중에 절전 모드로 들어갔을 때 시간 초과로 보고되고 헤드리스 실행에서 실패 상태로 유지되던 문제를 고쳤습니다
- 호출 도중 연결이 끊어졌을 때 HTTP MCP 도구 호출이 두 번 전송되던 문제를 고쳤습니다. 이제 읽기 전용이거나 멱등성이 있는 도구만 재시도합니다
- 백그라운드 작업이 실행 중일 때 턴이 SDK MCP 서버의 최신 도구 없이 시작되기도 하던 문제를 고쳤습니다
- 많은 PDF 페이지, 이미지 또는 기타 대용량 도구 결과를 읽는 턴에서 일부 "Autocompact is thrashing" 오류가 발생하던 문제를 고쳤습니다
- 클라우드 세션에서 세션이 재시작된 후 `/autocompact`가 기본 윈도우 크기로 되돌아가던 문제를 고쳤습니다
- 클라우드 또는 셀프 호스팅 러너 세션이 재시작될 때 `/clear`로 지운 대화가 다시 나타나기도 하던 문제를 고쳤습니다
- Claude 앱 게이트웨이 세션에서 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`가 무시되던 문제를 고쳤습니다
- `OTEL_EXPORTER_OTLP_HEADERS`가 설정되어 있을 때 Claude 앱 게이트웨이 뒤의 Claude Desktop 세션에서 보낸 텔레메트리가 거부되던 문제를 고쳤습니다
- `/permissions` > Recently denied에서 거부된 셸 명령이 표시되지 않고, 자동 모드의 로컬 분류기가 재시도된 명령을 검사할 때 해당 화면에서의 승인을 무시하던 문제를 고쳤습니다. 이제 행을 승인하면 설명 대신 명령 이름이 지정됩니다
- `/help` 및 `/` 명령 메뉴에서 `/claude-api`와 같은 번들 스킬의 짧은 설명 대신 모델용 긴 설명이 표시되던 문제를 고쳤습니다
- 하위 에이전트 기록에서 스트리밍 응답에 대해 임시 토큰 사용량과 빈 중단 사유가 기록되던 문제를 고쳤습니다
- API가 모델을 확인하는 데 5초 이상 걸릴 때 Agent SDK의 `setModel()` 및 이를 기반으로 구축된 앱을 통한 모델 전환이 거부되던 문제를 고쳤습니다. 이제 Claude Code가 최대 15초까지 대기합니다
- 연결된 앱을 통해 중단된 백그라운드 명령(예: 유휴 세션을 보관하는 데스크톱 앱)이 Claude에게 사용자가 중단한 것으로 보고되던 문제를 고쳤습니다. 이제 알림에 해당 출력 파일 이름이 표시됩니다
- Cowork 클라우드 세션의 WebFetch에서 사이트가 4xx 상태나 robots.txt 거부로 응답했을 때 도구 오류로 보고하던 문제를 고쳤습니다. 이제 로컬 세션과 마찬가지로 정상 결과로 처리됩니다
- 직접 구성된 GitHub MCP 서버의 쓰기 도구가 데스크톱 앱의 Code 탭에서 아무것도 생성하지 않고 닫히는 양식을 표시하던 문제를 고쳤습니다
- 서버가 재사용된 연결을 닫았을 때 Artifact 도구 읽기가 연결 재설정으로 실패하던 문제를 고쳤습니다
- Self-hosted runner: `--use-anthropic-git-proxy`를 사용하는 세션이 이전 세션이 복제본에 남겨둔 `.claude/settings.local.json`을 커밋하던 문제를 고쳤습니다
- Self-hosted runner: 체크아웃 훅 실행 중에 세션을 보관하거나 다시 큐에 넣거나 러너를 중지할 때 훅의 프로세스가 계속 실행되고 러너의 슬롯이 점유된 채로 남아있던 문제를 고쳤습니다
- 파싱할 수 없는 도구 호출에서의 복구를 개선했습니다. Claude Code는 이제 오류로 턴을 종료하기 전에 호출을 최대 두 번 재시도합니다
- 동시에 시작된 포크 하위 에이전트들을 개선했습니다. 이제 각 에이전트가 어떤 시작이 자신의 것인지 안내받으므로 포크들이 서로의 작업을 시작하려고 할 가능성이 훨씬 줄어듭니다
- 브라우저 로그인을 개선했습니다. 이제 계정 프로필이 로드될 때까지 기다리지 않고 로그인이 완료되는 즉시 성공 페이지가 표시됩니다
- 클라우드 및 셀프 호스팅 러너 세션의 웹 검색 오류를 개선했습니다. 이유를 제공하는 403으로 검색이 거부된 경우 일반적인 "Authentication error" 대신 해당 이유를 표시합니다
- 데스크톱 앱의 MCP 서버 중 하나가 연결할 수 없을 때 클라우드 세션의 첫 응답 시간을 개선했습니다
- 기록에 대용량 붙여넣기 이미지나 PDF 읽기가 포함된 세션의 Remote Control 연결 시간을 개선했습니다
- WebSearch 예산이 소진되었을 때 Claude가 받는 알림을 브라우저나 컴퓨터 사용을 통해 검색 엔진에 질의하지 말라는 내용도 포함하도록 변경했습니다
- 설정 `env` 블록의 `axScreenReader` 설정 및 `CLAUDE_AX_SCREEN_READER`가 사용자, 관리형 또는 `--settings` 설정에서만 적용되도록 변경했습니다(2.1.305부터)
- Self-hosted runner: 체크아웃 훅이 기본적으로 30분 후에 중단되어 세션 설정이 실패하도록 변경했습니다. 더 긴 시간이 필요한 경우 `--checkout-hook-timeout-min`을 높이거나 `0`으로 설정하십시오
- Self-hosted runner: Anthropic 관리형 git용으로 빌드된 인증서 파일이 CLI처럼 신뢰할 수 있는 인증서를 필터링하도록 변경했습니다. `[runner:warn]` 줄에 제외된 수가 표시됩니다
- [VSCode] 음성 받아쓰기가 저절로 중단될 때(15초 동안 음성이 인식되지 않거나 2분 제한 도달) 그 이유와 지금까지의 텍스트가 유지된다는 알림을 마이크 버튼에 추가했습니다
- [VSCode] 자세히 보기로 확장된 긴 프롬프트가 전체 채팅 패널을 덮어버리던 문제를 고쳤습니다. 이제 고정된 프롬프트는 패널의 최대 40%까지만 차지하며 스크롤됩니다
- [VSCode] LaTeX 수식이 포함된 목록 항목이나 표 셀의 일부가 리치 텍스트 에디터에서 새 목록이나 표로 붙여넣어지던 문제를 고쳤습니다
- [VSCode] `~/.claude/settings.json`에만 `NODE_EXTRA_CA_CERTS`가 설정되어 있을 때 TLS 검사 프록시 뒤에서 받아쓰기가 실패하던 문제를 고쳤습니다. 이제 `CLAUDE_CODE_CERT_STORE`도 따릅니다
- [VSCode] "still open somewhere else" 알림이 확장 프로그램 재시작 후 남아 있는 Claude 프로세스(보통 10분 이내에 자동으로 종료됨)까지 포함하도록 변경했습니다
- [VSCode] 음성 받아쓰기가 CLI처럼 신뢰할 수 있는 인증서를 필터링하도록 변경했습니다
- [VSCode] 확장 프로그램 자체 요청이 CLI처럼 신뢰할 수 있는 인증서를 필터링하고 환경 변수나 사용자 설정에 지정된 `NODE_EXTRA_CA_CERTS` 파일을 신뢰하도록 변경했습니다
- [Cloud sessions] 검색이 아직 실행 중일 때 저장소 선택기에 "No repositories match"가 표시되던 문제를 고쳤습니다. 이제 결과가 나올 때까지 "Searching…"이 표시됩니다
- [Cloud sessions] 셀프 호스팅 환경에서 "Waiting for a runner" 상태가 잘리던 문제를 고쳤습니다. 온디맨드 러너의 경우 이제 마지막 메시지부터 시간을 측정하고 실패한 시도를 표시합니다
- [Code Review] 새 리뷰를 시작하지 않고 풀 리퀘스트의 `@claude review always` 구독을 종료하는 `@claude review stop`(및 `off`, `pause`)을 Code Review에 추가했습니다
함께 읽기: Claude Code v2.1.306 릴리스 노트 분석 · Claude Code v2.1.304 업데이트: 새 명령어와 모드 제어 기능 추가
새로 쓸 수 있게 된 기능
이번 업데이트로 새로 쓸 수 있게 된 기능은 5가지입니다. 근거 항목은 위 릴리스 노트의 번호입니다.
| 기능 | 달라진 점 | 근거 항목 |
|---|---|---|
| Claude API 버전 설정 명령어 추가 | `/claude-api api-version` 명령어로 Claude API 코드를 `2026-10-21` 버전으로 간편하게 전환할 수 있습니다. | 1번 |
| OpenTelemetry 안전 이벤트 로깅 지원 | 권한 규칙, 자동 모드, 안전 점검, 훅, 샌드박스가 작업을 중단하거나 확인 및 반환할 때마다 `claude_code.safety_event` 이벤트를 수집합니다. | 2번 |
| 구문 분석 실패 도구 호출 자동 재시도 | 도구 호출의 구문을 분석할 수 없는 경우, 오류로 종료하기 전에 최대 2회까지 자동으로 호출을 재시도합니다. | 24번 |
| 코드 리뷰 구독 중단 명령어 지원 | 풀 리퀘스트에서 `@claude review stop`(또는 `off`, `pause`) 명령어로 자동 리뷰 구독을 새 리뷰 시작 없이 즉시 종료할 수 있습니다. | 43번 |
| VSCode 음성 받아쓰기 중단 알림 표시 | 음성 인식 무반응(15초) 또는 제한 시간(2분)으로 음성 받아쓰기가 자동 종료될 때 원인을 알리고 입력된 텍스트를 유지합니다. | 34번 |
업데이트 효과 직접 재보기
에이전트, effort, 속도, 재시도에 관한 변경이 내 작업에서 얼마나 차이 나는지는 직접 재 보면 숫자로 확인됩니다. claude -p를 JSON 출력으로 실행하면 걸린 시간과 턴 수, 서브에이전트 결과가 함께 나옵니다.
claude -p "<작업 지시>" \
--output-format json < /dev/null
작업 지시는 옵션보다 앞에 둡니다. --allowedTools Agent "<작업 지시>"처럼 쓰면 --allowedTools가 값을 여러 개 받는 옵션이라 작업 지시까지 도구 이름으로 읽습니다. 옵션을 뒤에 쓰려면 --allowedTools=Agent처럼 =로 붙입니다. 아무것도 보내지 않는 파이프에 표준 입력이 연결돼 있으면 3초를 기다린 뒤 경고를 띄우고 진행하는데, < /dev/null로 표준 입력을 막아 두면 이 대기가 없습니다.
- duration_ms: 실행 전체에 걸린 시간(밀리초)
- num_turns: 결과가 나오기까지 걸린 턴 수
- subagent_stats.completed / subagent_stats.failed: 서브에이전트가 끝까지 마친 수와 실패한 수
단순 조회 작업 하나(예: 어떤 함수가 어디서 호출되는지 찾기)와 코드 수정 작업 하나(예: 함수 하나에 테스트 추가)를 정해 둡니다. 같은 저장소에서 설정마다(업데이트 전후, effort 수준별) 두 작업을 각각 여러 번 실행하고, 조회와 수정의 기록을 따로 모아 비교합니다.
아래는 Claude Code 2.1.292에서 서브에이전트 한 개를 띄운 실행의 실제 출력에서 위 네 값만 남긴 것입니다. 나머지 키는 ...로 줄였습니다.
{
"duration_ms": 14271,
"num_turns": 4,
"subagent_stats": {
"completed": 1,
"failed": 0,
...
},
...
}
기록표의 첫 줄은 이 실행을 옮긴 것입니다. 조회 작업과 코드 수정 작업을 나눠, 실행할 때마다 한 줄씩 더합니다.
| 작업 | 설정 | 시간(ms) | 턴 | 완료/실패 |
|---|---|---|---|---|
| 예시 | 2.1.292 | 14271 | 4 | 1 / 0 |
함께 읽기: Claude Code v2.1.305 업데이트 주요 변경 사항 정리
업데이트 방법과 버전 확인
이 글의 변경을 모두 쓰려면 Claude Code 2.1.307 이상이 필요합니다. 터미널에서 claude update로 새 버전을 받고, claude --version으로 2.1.307 이상인지 확인합니다.
claude update
claude --version
- Claude Code v2.1.307 릴리스 노트 · github.com
작성일 2026-10-22 09:21
소개 · 문의 · 개인정보처리방침 · 면책 안내 · 저작권 안내 · AI, IT 글 모음
© 2026 MinoSui. 이 글의 무단 전재·재배포를 금합니다. 원문: https://minoss0918.blogspot.com/
댓글
댓글 쓰기