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 명령어 추가
목차
  1. 릴리스 노트 모아 보기
  2. 새로 쓸 수 있게 된 기능
  3. 업데이트 효과 직접 재보기
  4. 업데이트 방법과 버전 확인

릴리스 노트 모아 보기

공식 릴리스 노트에 적힌 43개 항목을 원래 순서를 지켜 한 줄에 한 항목씩 적었습니다. 원문에서 빼거나 원문에 없는 내용을 더한 항목은 없습니다.

  1. Claude API 코드를 API 버전 `2026-10-21`로 이전하는 `/claude-api api-version`을 추가했습니다
  2. 권한 규칙, 자동 모드, 안전 검사, 훅 또는 샌드박스가 도구 호출을 중단하거나 확인을 요청하거나 되돌려보낼 때마다 발생하는 `claude_code.safety_event` OpenTelemetry 이벤트를 추가했습니다
  3. `CLAUDE_CODE_DISABLE_1M_CONTEXT`가 설정되어 있고 모델이 `opus[1m]`처럼 `[1m]` 접미사가 붙은 별칭일 때 요청이 모델을 찾을 수 없음 오류로 실패하던 문제를 고쳤습니다
  4. 아무런 효과가 없는 커스텀 `ANTHROPIC_BASE_URL` 게이트웨이 뒤 및 Foundry 환경에서 `prompt-caching-scope` 베타 헤더가 전송되던 문제를 고쳤습니다
  5. macOS에서 로그인 키체인이 잠겨 있을 때 `claude -p`에서 MCP 서버가 "인증 필요"로 표시되던 문제를 고쳤습니다. 이제 이유를 안내하며 잠금 해제 후 다음 실행 시 새로 로그인하지 않고도 연결됩니다
  6. macOS 또는 Linux 컴퓨터가 MCP 서버 연결 중에 절전 모드로 들어갔을 때 시간 초과로 보고되고 헤드리스 실행에서 실패 상태로 유지되던 문제를 고쳤습니다
  7. 호출 도중 연결이 끊어졌을 때 HTTP MCP 도구 호출이 두 번 전송되던 문제를 고쳤습니다. 이제 읽기 전용이거나 멱등성이 있는 도구만 재시도합니다
  8. 백그라운드 작업이 실행 중일 때 턴이 SDK MCP 서버의 최신 도구 없이 시작되기도 하던 문제를 고쳤습니다
  9. 많은 PDF 페이지, 이미지 또는 기타 대용량 도구 결과를 읽는 턴에서 일부 "Autocompact is thrashing" 오류가 발생하던 문제를 고쳤습니다
  10. 클라우드 세션에서 세션이 재시작된 후 `/autocompact`가 기본 윈도우 크기로 되돌아가던 문제를 고쳤습니다
  11. 클라우드 또는 셀프 호스팅 러너 세션이 재시작될 때 `/clear`로 지운 대화가 다시 나타나기도 하던 문제를 고쳤습니다
  12. Claude 앱 게이트웨이 세션에서 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`가 무시되던 문제를 고쳤습니다
  13. `OTEL_EXPORTER_OTLP_HEADERS`가 설정되어 있을 때 Claude 앱 게이트웨이 뒤의 Claude Desktop 세션에서 보낸 텔레메트리가 거부되던 문제를 고쳤습니다
  14. `/permissions` > Recently denied에서 거부된 셸 명령이 표시되지 않고, 자동 모드의 로컬 분류기가 재시도된 명령을 검사할 때 해당 화면에서의 승인을 무시하던 문제를 고쳤습니다. 이제 행을 승인하면 설명 대신 명령 이름이 지정됩니다
  15. `/help` 및 `/` 명령 메뉴에서 `/claude-api`와 같은 번들 스킬의 짧은 설명 대신 모델용 긴 설명이 표시되던 문제를 고쳤습니다
  16. 하위 에이전트 기록에서 스트리밍 응답에 대해 임시 토큰 사용량과 빈 중단 사유가 기록되던 문제를 고쳤습니다
  17. API가 모델을 확인하는 데 5초 이상 걸릴 때 Agent SDK의 `setModel()` 및 이를 기반으로 구축된 앱을 통한 모델 전환이 거부되던 문제를 고쳤습니다. 이제 Claude Code가 최대 15초까지 대기합니다
  18. 연결된 앱을 통해 중단된 백그라운드 명령(예: 유휴 세션을 보관하는 데스크톱 앱)이 Claude에게 사용자가 중단한 것으로 보고되던 문제를 고쳤습니다. 이제 알림에 해당 출력 파일 이름이 표시됩니다
  19. Cowork 클라우드 세션의 WebFetch에서 사이트가 4xx 상태나 robots.txt 거부로 응답했을 때 도구 오류로 보고하던 문제를 고쳤습니다. 이제 로컬 세션과 마찬가지로 정상 결과로 처리됩니다
  20. 직접 구성된 GitHub MCP 서버의 쓰기 도구가 데스크톱 앱의 Code 탭에서 아무것도 생성하지 않고 닫히는 양식을 표시하던 문제를 고쳤습니다
  21. 서버가 재사용된 연결을 닫았을 때 Artifact 도구 읽기가 연결 재설정으로 실패하던 문제를 고쳤습니다
  22. Self-hosted runner: `--use-anthropic-git-proxy`를 사용하는 세션이 이전 세션이 복제본에 남겨둔 `.claude/settings.local.json`을 커밋하던 문제를 고쳤습니다
  23. Self-hosted runner: 체크아웃 훅 실행 중에 세션을 보관하거나 다시 큐에 넣거나 러너를 중지할 때 훅의 프로세스가 계속 실행되고 러너의 슬롯이 점유된 채로 남아있던 문제를 고쳤습니다
  24. 파싱할 수 없는 도구 호출에서의 복구를 개선했습니다. Claude Code는 이제 오류로 턴을 종료하기 전에 호출을 최대 두 번 재시도합니다
  25. 동시에 시작된 포크 하위 에이전트들을 개선했습니다. 이제 각 에이전트가 어떤 시작이 자신의 것인지 안내받으므로 포크들이 서로의 작업을 시작하려고 할 가능성이 훨씬 줄어듭니다
  26. 브라우저 로그인을 개선했습니다. 이제 계정 프로필이 로드될 때까지 기다리지 않고 로그인이 완료되는 즉시 성공 페이지가 표시됩니다
  27. 클라우드 및 셀프 호스팅 러너 세션의 웹 검색 오류를 개선했습니다. 이유를 제공하는 403으로 검색이 거부된 경우 일반적인 "Authentication error" 대신 해당 이유를 표시합니다
  28. 데스크톱 앱의 MCP 서버 중 하나가 연결할 수 없을 때 클라우드 세션의 첫 응답 시간을 개선했습니다
  29. 기록에 대용량 붙여넣기 이미지나 PDF 읽기가 포함된 세션의 Remote Control 연결 시간을 개선했습니다
  30. WebSearch 예산이 소진되었을 때 Claude가 받는 알림을 브라우저나 컴퓨터 사용을 통해 검색 엔진에 질의하지 말라는 내용도 포함하도록 변경했습니다
  31. 설정 `env` 블록의 `axScreenReader` 설정 및 `CLAUDE_AX_SCREEN_READER`가 사용자, 관리형 또는 `--settings` 설정에서만 적용되도록 변경했습니다(2.1.305부터)
  32. Self-hosted runner: 체크아웃 훅이 기본적으로 30분 후에 중단되어 세션 설정이 실패하도록 변경했습니다. 더 긴 시간이 필요한 경우 `--checkout-hook-timeout-min`을 높이거나 `0`으로 설정하십시오
  33. Self-hosted runner: Anthropic 관리형 git용으로 빌드된 인증서 파일이 CLI처럼 신뢰할 수 있는 인증서를 필터링하도록 변경했습니다. `[runner:warn]` 줄에 제외된 수가 표시됩니다
  34. [VSCode] 음성 받아쓰기가 저절로 중단될 때(15초 동안 음성이 인식되지 않거나 2분 제한 도달) 그 이유와 지금까지의 텍스트가 유지된다는 알림을 마이크 버튼에 추가했습니다
  35. [VSCode] 자세히 보기로 확장된 긴 프롬프트가 전체 채팅 패널을 덮어버리던 문제를 고쳤습니다. 이제 고정된 프롬프트는 패널의 최대 40%까지만 차지하며 스크롤됩니다
  36. [VSCode] LaTeX 수식이 포함된 목록 항목이나 표 셀의 일부가 리치 텍스트 에디터에서 새 목록이나 표로 붙여넣어지던 문제를 고쳤습니다
  37. [VSCode] `~/.claude/settings.json`에만 `NODE_EXTRA_CA_CERTS`가 설정되어 있을 때 TLS 검사 프록시 뒤에서 받아쓰기가 실패하던 문제를 고쳤습니다. 이제 `CLAUDE_CODE_CERT_STORE`도 따릅니다
  38. [VSCode] "still open somewhere else" 알림이 확장 프로그램 재시작 후 남아 있는 Claude 프로세스(보통 10분 이내에 자동으로 종료됨)까지 포함하도록 변경했습니다
  39. [VSCode] 음성 받아쓰기가 CLI처럼 신뢰할 수 있는 인증서를 필터링하도록 변경했습니다
  40. [VSCode] 확장 프로그램 자체 요청이 CLI처럼 신뢰할 수 있는 인증서를 필터링하고 환경 변수나 사용자 설정에 지정된 `NODE_EXTRA_CA_CERTS` 파일을 신뢰하도록 변경했습니다
  41. [Cloud sessions] 검색이 아직 실행 중일 때 저장소 선택기에 "No repositories match"가 표시되던 문제를 고쳤습니다. 이제 결과가 나올 때까지 "Searching…"이 표시됩니다
  42. [Cloud sessions] 셀프 호스팅 환경에서 "Waiting for a runner" 상태가 잘리던 문제를 고쳤습니다. 온디맨드 러너의 경우 이제 마지막 메시지부터 시간을 측정하고 실패한 시도를 표시합니다
  43. [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.2921427141 / 0

함께 읽기: Claude Code v2.1.305 업데이트 주요 변경 사항 정리

▲ 맨 위로

업데이트 방법과 버전 확인

이 글의 변경을 모두 쓰려면 Claude Code 2.1.307 이상이 필요합니다. 터미널에서 claude update로 새 버전을 받고, claude --version으로 2.1.307 이상인지 확인합니다.

claude update
claude --version

▲ 맨 위로

글쓴이 MinoSui · 블로그 운영자·편집 책임

편집 방침. 오류 제보는 문의로 받습니다. 글쓴이·블로그 소개

#IT·AI#클로드AI#ClaudeCode

작성일 2026-10-22 09:21

소개 · 문의 · 개인정보처리방침 · 면책 안내 · 저작권 안내 · AI, IT 글 모음

© 2026 MinoSui. 이 글의 무단 전재·재배포를 금합니다. 원문: https://minoss0918.blogspot.com/

댓글

이 블로그의 인기 게시물

트럼프 AI 속도조절론 거부와 글로벌 빅테크 및 한국 IT의 파장

KT 모두의 AI 서비스 추진 일정과 일상 속 핵심 기능 총정리

스타크래프트 AI 플루토 김성현 대결 전략 분석 및 최신 AI 기술

아이티센클로잇 AI 에이전트, 폐쇄망 연동 필수 보안 기준과 활용법

난폭운전 보복운전 기준 차이와 스마트폰 영상 신고 정리

초보 귀농인을 위한 농작물 병해충 진단 앱 설치 및 스마트팜 활용 가이드

카카오 카나나 상담매니저 도입 및 고객 응대 효율화 방법

백화점 3사 정기 휴무일 확인법과 정기 세일 공략 팁

마인크래프트 코블몬 모드 전설 포켓몬 스폰 설정 및 소환 알아둘 점

그록 AI 반도체 설계 원리와 GPU 대비 성능 벤치마크