Claude Code 2.1.310: 게이트웨이 오류와 Windows 훅 수정
실제로 실행되는 Claude Code를 업데이트하고, effort beta와 대화 중간의 시스템 메시지 거부 오류를 구분하세요. Windows에서 인터프리터 실행 실패 시 훅이 도구 호출을 차단하는지 검증하고, cleanupPeriodDays의 지나치게 큰 값을 적절한 보존 기간으로 바꾸세요. 남아 있는 첨부 파일을 보존하면서 자동 재시도와 파일 복구의 한계도 확인합니다.
목차
Claude Code가 게이트웨이를 통해 요청을 보낼 때 effort-2025-11-24를 언급하는 Unexpected value(s) 또는 Unexpected role "system" 오류가 발생하면, 2.1.310 이상으로 업데이트한 뒤 문제가 발생한 대화에서 다시 요청하세요. Windows를 사용하는 팀은 훅의 인터프리터가 실패했을 때 도구 호출이 실제로 차단되는지도 확인해야 합니다. cleanupPeriodDays에 지나치게 큰 값을 사용하던 중 붙여넣은 이미지가 사라졌다면, 보존 기간을 바꾸기 전에 남아 있는 데이터를 먼저 보관하세요.
2026-10-25 기준 2.1.310 공식 릴리스 노트는 이러한 게이트웨이, Windows 훅, 정리 작업 문제의 수정을 명시합니다. 아래 절차에서는 각 실패 상황을 따로 확인합니다.
실제로 실행되는 버전이 2.1.310 이상인지 확인하기
터미널이 어떤 실행 파일을 시작하는지 확인한 다음, 기존에 사용한 설치 방식에 맞춰 업데이트하세요. Bash에서 다음 명령을 실행합니다. Windows PowerShell에서도 그대로 사용할 수 있습니다.
claude --version
claude doctorclaude doctor는 설치 상태와 설정을 변경하지 않는 읽기 전용 진단을 제공합니다. 업데이트 전의 버전 출력을 보관하면 업데이트 후 결과와 비교할 수 있습니다.
Anthropic의 설치 및 업데이트 안내에서 현재 설치 방식에 해당하는 명령을 사용하세요.
| 기존 설치 방식 | 셸 | 업데이트 명령 |
|---|---|---|
| 네이티브 설치 프로그램 | Bash 또는 PowerShell | claude update |
| Homebrew stable cask | Bash | brew upgrade claude-code |
| Homebrew latest cask | Bash | brew upgrade claude-code@latest |
| WinGet | PowerShell | winget upgrade Anthropic.ClaudeCode |
| npm | Bash 또는 PowerShell | npm install -g @anthropic-ai/claude-code@latest |
네이티브 업데이트는 설정된 릴리스 채널을 따릅니다. Homebrew의 claude-code cask는 stable을, claude-code@latest는 latest를 따르므로, 업데이트가 성공해도 필요한 버전보다 낮은 버전이 남아 있을 수 있습니다.
이미 네이티브 방식으로 설치했다면 claude install 2.1.310으로 CLI에서 특정 버전을 설치할 수도 있습니다. 패키지로 관리하는 배포 환경에서는 평소 배포 절차에 따라 필요한 버전을 제공하는 패키지나 채널을 선택하세요.
claude --version을 다시 실행한 다음 새 Claude Code 세션을 시작하세요. 여전히 이전 버전이 표시되면 Bash의 which -a claude 또는 PowerShell의 where.exe claude로 서로 충돌하는 설치를 확인하세요. 편집기 내장 터미널에서는 변경된 PATH를 반영하기 위해 편집기 자체를 다시 시작해야 할 수도 있습니다.
게이트웨이 오류에 맞는 재시도 동작 구분하기
반환된 오류 문구를 기준으로 해결 방법을 선택하세요. 일반적인 400 상태 코드만으로는 게이트웨이가 어떤 기능을 거부했는지 알 수 없습니다.
Anthropic의 게이트웨이 호환성 안내는 다음과 같은 복구 동작을 설명합니다.
| 응답에서 확인할 문구 | 자동 대체 처리 | 확인할 사항 |
|---|---|---|
Unexpected value(s)로 시작하고 anthropic-beta의 effort-2025-11-24를 언급하는 400 | Claude Code를 종료할 때까지 해당 모델의 요청에서 effort 필드와 beta를 생략합니다. | 이 값을 ANTHROPIC_BETAS에 직접 추가했다면 제거하세요. |
output_config.effort와 Extra inputs are not permitted를 언급하거나 effort를 지원하지 않는다고 알리는 400 | effort를 제외하는 대체 처리를 적용합니다. | 실제로 거부된 필드가 effort인지 확인하세요. |
Unexpected role "system" 등의 400 | 대화 중간의 시스템 텍스트를 사용자 메시지로 옮깁니다. /clear를 실행하거나 컨텍스트가 압축될 때까지 이 형식을 유지합니다. | 문제가 발생한 대화에서 다시 요청하세요. |
이러한 폴백, 즉 호환성을 위한 대체 처리는 요청 내용을 바꿉니다. effort 매개변수는 모델의 토큰 사용 방식을 제어하므로, 이를 제외한 재시도가 성공했다고 해서 원래 요청한 effort 설정이 적용되었다고 볼 수는 없습니다. 시스템 텍스트를 사용자 메시지로 옮기는 경우에도 텍스트 자체는 보존되지만 전달 형식은 달라집니다.
문제가 발생한 대화에서 재현하기
업데이트 효과를 확인하는 동안 게이트웨이, 인증 정보의 출처, 선택한 모델을 그대로 유지하세요. 제공업체와 버전을 동시에 바꾸면 무엇 때문에 결과가 달라졌는지 구분하기 어렵습니다.
먼저 Claude Code를 시작하고 /status를 실행하세요. 게이트웨이 연결 안내에는 이 화면에서 사용 중인 기본 URL과 인증 정보의 출처를 확인하는 방법이 나와 있습니다. 의도한 게이트웨이가 표시되지 않으면 beta 지원 여부를 조사하기 전에 연결 설정부터 바로잡으세요.
그다음 세션을 종료하고, 로컬 진단 로그를 남기도록 문제가 발생한 대화를 다시 여세요. Bash에서는 다음 명령을 사용합니다.
claude --resume --debug-file ./claude-gateway-debug.log선택 목록에서 실패했던 세션을 고르고, 문제를 재현하는 가장 작은 요청을 반복하세요. 이 플래그들은 CLI 참조 문서에 설명되어 있습니다.
일차적인 성공 기준은 이전에 실패했던 요청에서 사용할 수 있는 어시스턴트 응답을 받는 것입니다. 호환성 대체 처리 덕분에 복구되었는지까지 확인하려면 클라이언트 진단과, 접근할 수 있다면 게이트웨이의 요청 진단에서 거부 응답 뒤에 수정된 요청이 다시 전송되었는지 살펴보세요. 새 대화의 첫 프롬프트가 성공하는 것만으로는 이후에 만들어지는 모든 대화 구조가 검증되지는 않습니다.
BetterToken의 Claude Code 설정 안내는 /v1 없이 ANTHROPIC_BASE_URL=https://bettertoken.ai를 사용하도록 명시합니다. 클라이언트 업데이트를 확인하는 동안 이 문서화된 주소를 유지하세요.
업데이트한 클라이언트에서도 계속 실패한다면
상위 서비스에서 받은 오류 응답 본문을 그대로 보존하세요. 식별 가능한 거부 메시지를 불분명한 게이트웨이 오류로 바꾸면 클라이언트가 폴백이 필요한 상황을 감지하지 못할 수 있습니다. 또한 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1은 effort와 대화 중간의 시스템 항목을 유지하므로, 이 오류들을 모두 해결하는 설정은 아닙니다.
남아 있는 증거에 맞춰 다음 조치를 선택하세요.
- 동일한 식별 가능한 거부가 반복됨: 실제 실행 파일, 수동으로 추가한 beta 값, 게이트웨이가 상위 서비스의 오류를 다시 작성하는지 확인하세요.
- 인증 실패: 게이트웨이의 인증 정보 설정 안내를 따르세요. 연결 안내는 Bearer 인증용
ANTHROPIC_AUTH_TOKEN과x-api-key용ANTHROPIC_API_KEY를 구분합니다. 제공업체가 문서화한 방식을 사용하세요. - 오류가 다른 필드를 지목함: 해당 필드의 호환성 요구 사항을 조사하세요. 모든 스키마 거부를 effort 문제로 분류하지 마세요.
- API 응답이 오기 전에 연결 실패: 엔드포인트, 프록시, DNS 또는 TLS 연결 경로를 조사하세요.
지원 요청을 보낼 때는 클라이언트 버전, 운영체제, 선택한 모델 ID, 요청 시각 또는 요청 ID, HTTP 상태, 정확한 오류 문구를 모으세요. 인증 정보나 대화 로그 전체 대신 민감한 정보를 제거한 진단 발췌본을 공유하세요.
Windows 훅이 실제로 호출을 차단하는지 확인하기
최소 2.1.310으로 업데이트하고, 정책 적용에 사용하는 훅이 실패할 때의 동작을 시험하세요. 연속된 두 릴리스는 서로 다른 상황을 수정합니다.
- 2.1.309는 PowerShell 훅의 종료 코드 처리와, 훅이 PowerShell을 명시적으로 선택했을 때 Git이 없어 발생하는 실패를 수정합니다.
- 2.1.310는 Git Bash가 없고 훅 명령이 따옴표로 감싼 문자열로만 구성된 추가 사례를 수정합니다.
훅에 오류가 발생했다고 해서 호출이 자동으로 거부되는 것은 아닙니다. 훅 참조 문서는 실패 시 해당 훅을 실행하게 만든 작업을 중단해야 하는 명령 및 HTTP 훅을 위해 onFailure: "block"을 제공합니다.
따옴표로 감싼 명령의 회귀 문제 확인하기
Git Bash가 없는 일회용 네이티브 Windows 테스트 환경을 사용하세요. Claude Code 연결은 정상적으로 작동해야 하며, 관련 없는 훅이나 플러그인이 결과에 영향을 주지 않아야 합니다. 이렇게 하면 실제 작업 컴퓨터에서 Git을 제거하지 않고도 Git Bash가 없는 상황을 시험할 수 있습니다.
PowerShell에서 새 테스트 디렉터리와 무해한 파일을 만드세요.
$hookProbe = Join-Path $env:TEMP ("claude-hook-probe-" + [guid]::NewGuid().ToString("N"))
New-Item -ItemType Directory -Path (Join-Path $hookProbe '.claude') -Force | Out-Null
Set-Location $hookProbe
Set-Content -LiteralPath .\probe.txt -Value ([guid]::NewGuid().ToString())
Test-Path 'C:\__claude_hook_probe_missing__\python.exe'
claude --versionTest-Path는 False를 반환해야 하며, 버전은 2.1.310 이상이어야 합니다.
이 테스트 디렉터리에 다음 내용으로 .claude/settings.local.json을 만드세요.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Read",
"hooks": [
{
"type": "command",
"command": "\"C:\\__claude_hook_probe_missing__\\python.exe\""
}
]
}
]
}
}shell, args, onFailure 필드를 생략한 것은 의도적입니다. 이 단계에서는 따옴표로 감싼 명령 자체에 대한 대체 실행 동작을 확인합니다.
PowerShell에서 세션을 시작하세요.
claude --tools Read --debug-file .\phase1.log이 일회용 디렉터리를 신뢰할 수 있는 작업 공간으로 승인한 다음, /hooks를 실행해 PreToolUse 훅이 Read에 일치하는지 확인하세요. 다음과 같이 요청합니다.
Read 도구를 정확히 한 번 사용해 probe.txt를 읽어 줘. 호출이 차단되면 그 사실을 알리고 중단해. 다른 방법은 사용하지 마.
예상 결과: Read 호출이 차단되고 오류나 진단에 PowerShell started no program이 나타납니다. PowerShell은 일반적으로 따옴표로 감싼 경로를 문자열로 평가합니다. Microsoft의 호출 연산자 문서는 이 경로를 실제 명령으로 실행하려면 왜 다른 구문이 필요한지 설명합니다.
Read가 실제로 파일 읽기에 성공했다면 이 검사는 실패한 것입니다. Claude가 Read 호출을 시도하지 않았다면 결과를 판단할 수 없습니다. 모델의 설명만 증거로 받아들이지 말고 도구 실행 결과와 로그를 확인하세요.
/hooks에 해당 설정이 표시되지 않으면 훅 로딩 점검 절차를 따르세요. 설정은 보통 자동으로 다시 로드되지만, 파일 감시기가 변경을 놓쳤다면 재시작해 다시 읽도록 할 수 있습니다. 조직의 관리 정책이 관리형 훅만 허용하는 경우에도 이 프로젝트 수준의 검사는 실행되지 않은 것입니다.
실제로 없는 인터프리터의 실행 실패 확인하기
인터프리터를 시작할 수 없을 때의 동작을 시험하려면 실패 처리 정책을 명시하세요. 테스트 세션을 종료하고, 내부 훅 객체만 다음 내용으로 바꾸세요.
{
"type": "command",
"command": "C:\\__claude_hook_probe_missing__\\python.exe",
"args": [],
"onFailure": "block"
}여기서 args는 실행 파일을 직접 호출하는 방식을 선택합니다. 이제는 따옴표 안의 문자열 표현식을 평가하는 것이 아니라, 존재하지 않는 실행 파일을 시작하려다가 실제 실행 실패가 발생합니다.
PowerShell에서 다시 시작하고 앞서 사용한 Read 요청을 반복하세요.
claude --tools Read --debug-file .\phase2.log예상 결과: 인터프리터 시작에 실패했기 때문에 Read가 차단됩니다. 이 검사는 Git Bash의 설치 여부와 무관하게 명시적인 실패 처리 정책을 확인합니다. 앞서 확인한 따옴표 명령의 회귀 문제와는 별개의 검사입니다.
결과를 검토한 뒤 테스트 설정을 제거하세요. 실제 정책 훅에서는 정상적으로 작동하는 인터프리터를 복구하고, 검사 실패 시 작업을 중단해야 하는 경우 명시적인 차단 정책을 유지하세요.
이 두 검사는 PreToolUse를 실행합니다. PermissionRequest 훅은 권한 요청 단계에 도달하는 작업으로 별도 검증해야 합니다. 정상적인 거부 응답은 hookSpecificOutput.decision.behavior를 "deny"로 설정하며, 종료 코드 2만으로는 이 이벤트를 거부하지 않습니다. onFailure: "block"이 설정된 상태에서 실제 실패가 발생하면 요청이 거부됩니다.
지나치게 큰 보존 기간을 필요한 값으로 바꾸기
팀에 별도의 보존 요구 사항이 없다면 문서에 명시된 기본값인 30일을 사용하세요. 기존 기간을 줄이기 전에는 계속 필요한 기록을 별도로 보관하세요.
정리 작업 수정은 cleanupPeriodDays에 매우 큰 값을 설정했을 때 최근 파일이 삭제되던 문제를 다룹니다. 이 설정이 영구 보관 시스템으로 바뀌는 것도, 이미 삭제된 파일이 복구되는 것도 아닙니다.
기준을 바꾸기 전에 남아 있는 데이터 보관하기
실행 중인 세션을 종료하고, 아직 필요한 데이터를 Claude Code가 관리하는 디렉터리 밖으로 복사하세요. ~/.claude 또는 Windows의 %USERPROFILE%\.claude에 있는 관련 데이터와 함께 남아 있는 이미지 첨부 파일도 포함해야 합니다.
현재 애플리케이션 데이터 문서에 따르면 새로 붙여넣은 이미지는 Claude Code의 임시 루트 아래에 있는 세션별 images/ 디렉터리에 저장됩니다. 이 임시 루트는 CLAUDE_CODE_TMPDIR로 제어됩니다. 따라서 ~/.claude만 백업했다는 사실로는 현재 이미지 사본도 보존되었다고 확인할 수 없습니다.
데이터를 보관한 다음 해당 설정 파일에 아래 설정을 병합하세요.
{
"cleanupPeriodDays": 30
}개인 기본값을 지정하는 파일은 ~/.claude/settings.json이며, Windows에서는 %USERPROFILE%\.claude\settings.json입니다. 다른 키는 그대로 유지하세요.
2026-10-25에 확인한 문서상 최솟값은 1이며, 0은 유효성 검사에 실패합니다. 기간을 줄이면 더 오래된 데이터가 정리 대상에 포함되므로, 필요한 데이터를 보관하는 일이 먼저입니다.
claude doctor를 실행해 설정의 유효성을 확인하세요. 의도한 값이 적용되지 않으면 설정 우선순위를 살펴보세요. 관리형 설정과 우선순위가 높은 세션 또는 프로젝트 설정이 개인 파일의 값을 덮어쓸 수 있습니다. /status는 로드된 설정 출처를 보여 주며, 모든 개별 키의 최종 적용 값을 보여 주는 것은 아닙니다.
사라진 첨부 파일은 별도로 복구하기
없어진 이미지는 원본 파일이나 기존 파일 시스템 백업에서 복원한 뒤, 복구한 사본을 대화에 다시 첨부하세요. 파일이 로컬에서 열리는지, Claude가 첨부 파일을 다시 사용할 수 있는지 확인하세요.
보존 설정을 바꾸어도 삭제된 바이트를 재구성할 수는 없습니다. /rewind가 첨부 파일을 복구해 줄 것이라고 가정해서도 안 됩니다. 체크포인트 스냅샷도 만료되며, 필요한 스냅샷이 사라졌다면 복원에 실패할 수 있습니다.
이미 텔레메트리를 내보내는 팀이라면 완료된 claude_code.retention_sweep 이벤트를 확인하세요. 모니터링 참조 문서는 result: "complete"와 문자열 타입의 period_days를 설명합니다. "30"은 해당 정리 실행에서 30일을 사용했다는 뜻입니다.
재시작한 뒤 잠깐 실행하는 것만으로 정리 작업이 수행되었다고 입증할 수는 없습니다. 정리는 백그라운드에서 세션당 최대 한 번 실행되며, 이전 24시간 안에 정리가 수행되었다면 다음 세션의 정리는 최소 10분 지연됩니다. 첨부 파일을 읽을 수 있다는 사실과 정리 작업이 완료되었다는 증거는 각각 따로 확인하세요.
Monitor 지원 확대는 별개의 변경 사항
2.1.310은 Monitor 도구와 플러그인 모니터를 Bedrock, Vertex, Foundry에서도 사용할 수 있도록 확장합니다. 텔레메트리나 비필수 트래픽이 비활성화된 설정도 포함됩니다. 릴리스 노트는 해당 환경에서 포그라운드의 긴 대기도 차단된다고 설명합니다.
이러한 배포 환경에서 Monitor를 사용할 수 없었다면 텔레메트리 정책을 바꾸기 전에 실행 중인 버전을 확인하세요. 이 지원 범위 변경과 특정 게이트웨이가 effort 설정이나 대화 중간의 시스템 항목을 허용하는지는 별개의 문제입니다。
