무엇이 바뀌었나?
Claude Code 2.1.318이 2026년 11월 4일 출시됐습니다. claude.ai 로그인 만료일 표시와 사전 경고, mod(Claude의 인터페이스나 동작을 바꾸는 확장)의 effort 옵션, mantle 업스트림의 assume_role이 새로 들어왔습니다. 수정은 전체 변경의 절반이 넘으며, 가장 큰 묶음은 공유 네트워크 홈 디렉터리에서 ~/.claude.json과 저장된 로그인을 지키는 작업입니다. 재시작한 세션, claude -p, 클라우드 세션, MCP 서버 관련 수정도 함께 포함됐습니다.
새 기능
-
claude auth status와claude -p의 로그인 만료일두 명령의 결과에 저장된 claude.ai 로그인이 끝나는 날짜가 나오지 않았습니다. 이제
claude auth status의loginExpiresAt과claude -pJSON 결과의credential_expires_at에서 날짜를 볼 수 있습니다. -
claude -p텍스트 출력의 만료 경고claude -p텍스트 출력에는 로그인 종료를 미리 알리는 안내가 없었습니다. 이제 저장된 claude.ai 로그인이 끝나기 10일 전부터 stderr(오류 출력)에 한 줄 경고가 표시됩니다. -
mod
$.model.fork의effort옵션mod의 간단한 부수 작업에 effort를 따로 지정하는 옵션이 없었습니다. 이제 세션의 effort와 상관없이
low로 실행할 수 있고, 결과에 실제로 보낸 effort가 표시됩니다. -
Claude Code가 작성한 mod를 켤 때의 답변 기록
세션에서 작성한 mod를 켤지 묻는 질문에 어떻게 답했는지 기록이 남지 않았습니다. 이제 답변이 기록됩니다.
-
Claude apps gateway
mantle업스트림의assume_rolemantle업스트림(gateway가 요청을 넘기는 대상)에서assume_role을 사용할 수 있습니다. 다른 AWS 계정의 역할을 쓰거나, AWS 비용을 개발자별로 구분할 때 활용합니다. -
Claude apps gateway의 Google 액세스 토큰 만료 경고
federation(
external_account) 자격 증명 파일에서 받은 Google 액세스 토큰이 곧 만료될 때 로그에 경고가 남습니다. -
셀프 호스팅 러너의
CLAUDE_RUNNER_SPAWN_REASON오케스트레이터의 spawn-runner 훅에서 러너를 띄우는 이유를 알 수 없었습니다. 이제 이 환경 변수로 Anthropic이 요청을 보낸 이유(
runner_lost,resumed등)를 확인할 수 있습니다. 이유가 전달되지 않으면 설정되지 않습니다. -
셀프 호스팅 러너의
--release-idle-session-min시작 경고마지막 인수로 값 없이 쓰면 무시되고, 공백만 넣으면
0으로 읽히는데도 아무 안내가 없었습니다. 동작은 그대로이며, 이제 시작할 때 경고가 표시됩니다. -
[Cloud sessions] No repository 옵션
클라우드 세션을 시작하려면 저장소를 골라야 했습니다. 이제 Anthropic 호스팅 환경에서는 저장소 없이 시작할 수 있습니다.
-
[Cloud sessions] Chrome 이름 추가
Playwright 외의 도구는 내장 Chromium을 찾지 못할 수 있었습니다. 이제
google-chrome과CHROME_PATH로 찾을 수 있습니다. -
[Cloud sessions] 환경 삭제 카드의 New session 버튼
세션의 환경이 삭제되면 메시지 입력창이 숨겨진 카드만 표시됐습니다. 이제 카드에 New session 버튼이 있습니다.
주요 개선
-
공유 네트워크 홈 디렉터리의 파일 저장
저장 과정에서
~/.claude.json, 설정 파일, 저장된 로그인이 삭제되거나, 잠시 비거나, 거의 빈 사본이나 이전 사본으로 바뀌는 일이 있었습니다. 이제 이런 일이 덜 발생합니다. -
네트워크 파일 시스템의 설정 파일 재확인
설정 파일이 없다고 잘못 보고되면 MCP 서버와 신뢰한 폴더 없이 세션이 시작될 수 있었습니다. 이제 한 번 더 확인하므로 이런 경우가 줄어듭니다.
-
무인 실행의
~/.claude.json쓰기claude -p와 SDK 앱은 바뀐 내용이 없어도 실행할 때마다 이 파일을 다시 썼습니다. 이제 다시 쓰지 않습니다. -
자동 업데이트 안정성
릴리스를 검증하다 잠깐 네트워크가 끊기면 다음 확인 때까지 기다려야 했습니다. 이제 바로 다시 시도합니다.
-
MCP 도구 오류
도구를 불러오기 전에 호출하면 이제 오류 응답으로 입력 스키마를 돌려줍니다.
-
macOS 내장
/bin/bash에서의 git 작업Bash 도구가 macOS 내장
/bin/bash로 실행될 때 git 커밋과 풀 리퀘스트 생성의 안정성이 개선됐습니다. -
원격 세션 재연결
일시 중지나 절전 후 원격 세션이 더 빨리 다시 연결됩니다.
-
사용량 한도 메뉴의 “Ask your admin for more usage”
이제 한 번에 요청을 보냅니다.
-
You should know 알림 문구
터미널에서만 동작하는 “press 2” 대신 “try again”이라고 안내합니다.
-
IDE 터미널에서 시작할 때의 확장 설치 중단
IDE 터미널에서 시작하면 Claude Code가 IDE 확장을 설치하거나 업데이트했습니다. 이제 하지 않으며, 외부 터미널의
/ide나 편집기의 확장 화면을 사용합니다. -
모델 전환 설정이 “Ask each time”일 때의 서브에이전트
“Switch models when a message is flagged”가 “Ask each time”이면 서브에이전트가 모델을 전환했습니다. 이제 전환하지 않고 멈춥니다.
-
백그라운드 서브에이전트의 셸 명령
이제 모든 제공업체에서 셸 명령을 3분 뒤 백그라운드로 옮깁니다. 명령이 실행되는 동안 프롬프트 캐시(이전 요청 내용을 재사용하기 위한 저장소)가 만료되지 않게 하기 위한 변경입니다.
-
서브에이전트 진행 요약
Bedrock, Vertex, Foundry를 쓰거나 텔레메트리를 끈 환경에서 프롬프트 캐시가 비어 있으면, 요약이 서브에이전트의 대기 중인 응답을 최대 5분까지 기다릴 수 있습니다.
-
mod가
prompt.submit에서 첨부하는 내용시스템 메시지로 나가던 내용이 이제 사용자 턴 안에 남습니다.
-
deniedMcpServers의 URL 항목이제 업스트림 URL이 일치하는 Anthropic 제공 서버도 차단하고, 세션이 커넥터 자체 URL을 받는 클라우드 세션과 셀프 호스팅 러너에서는 커넥터도 차단합니다. 그 외 환경에서는 커넥터를 이름으로 지정해 차단해야 합니다.
-
/permissions화면규칙 상세, 기본 제공 규칙, 삭제 확인 화면이 표준 대화상자로 바뀌었습니다. 이 화면에서 Ctrl+C를 두 번 누르면 종료되던 동작이 뒤로 가기나 취소로 바뀌었습니다.
-
/claude-api managed-agents-onboard의 기본 권한새 에이전트의 내장 도구와 빠른 시작 템플릿의 MCP 도구가 이제 Claude Console과 같은
auto권한 정책(“Judge risky actions”)을 기본으로 씁니다. “run without asking”이라고 말하면 적용하지 않습니다. -
Claude apps gateway 로그 안내
listen.trusted_proxies안내는 이제X-Forwarded-For에 연결 주소를 직접 추가하는 프록시만 등록하라고 알려 줍니다. Amazon Bedrock에서 AWS CountTokens가 실패할 때의 경고는 501 이후 토큰을 세는 쪽이 gateway가 아니라 Claude Code임을 밝히고, AWS가 접근을 거부한 경우에만 IAM을 지목합니다. -
셀프 호스팅 러너 오케스트레이터의 로그 형식
ok session=…은 디버그 수준의 stderr에만 출력됐습니다. 이제 모든 로그 수준에서 stdout에 출력되며jti=…뒤에reason=…이 붙습니다.nack session=…은retryable=…뒤의reason=…으로 필드가 끝납니다. -
Remote Control의 터미널 포크 이름
앱이 이름을 정하지 않은 경우, 터미널 포크를 다시 포크하면 “Name (fork 2)” 형식의 제목이 붙습니다.
-
[VSCode] 로그인 화면
로그인 상태 확인이 실패하면 Claude Code가 출력한 내용을 화면에서 보여 줍니다.
-
[Cloud sessions] Create PR 실패 메시지
클라우드와 Remote Control 세션에서 대부분의 실패가 Try again으로만 안내됐습니다. 이제 이유나 GitHub 링크를 보여 줍니다.
-
[Cloud sessions] 커넥터 검색 결과
검색이 커넥터 디렉터리의 일부만 다룬다는 사실을 이제 Claude에게 알려 줍니다.
-
[Code Review] 분석 페이지
서버나 네트워크 오류가 나면 빈 카드가 표시됐습니다. 이제 한 번 다시 시도한 뒤 Try again 배너를 보여 줍니다.
주요 버그 수정
설정 파일과 로그인
~/.claude.json이 유효한 JSON이 아니면 비대화형 실행이 파일을 기본값으로 덮어쓰던 문제 수정. 이제 시작이 실패하고 복원 방법을 안내하며 파일은 그대로 둡니다. (#87551)- 백업 없이 비어 있는
~/.claude.json을 손상됐다고 보고하던 문제 수정. 이제 파일이 없을 때처럼 시작합니다. - 손상되거나 없는
~/.claude.json의 복원 명령이 비어 있거나 잘린 백업을 가리키거나, 읽기 전용 파일에서 실패하던 문제 수정. claude -p만 실행하는 홈 디렉터리에서 보관 기간 정리가~/.claude.json백업을 모두 없애던 문제 수정. 이제 마지막 정상 백업을 지우기 전에 새 백업을 만듭니다.- 공유 네트워크 홈 디렉터리에서 설정 파일을 갱신하지 못해도
/logout,claude auth logout,claude mcp remove가 성공으로 보고하고, 신뢰, 동의, MCP 설정 변경이 알림 없이 사라지던 문제 수정. - 네트워크 홈 디렉터리에 데이터 공간은 없지만 새 파일은 만들 수 있을 때 저장된 로그인이 빈 파일로 바뀌던 문제 수정.
- 같은 홈 디렉터리에서 다른 터미널이나 호스트가 같은 계정과 조직으로 다시 로그인하면 작업이
Not logged in으로 종료되던 문제 수정. - 저장된 claude.ai 로그인이 시간 제한에 도달했을 때 로그인 실패 원인이 드러나지 않던 문제 수정. 이제 그 사실을 알려 주고,
claude -p에서는claude auth login과claude setup-token을 안내합니다. forceLoginOrgUUID가 설정된 컴퓨터에서 허용된 조직의setup-token토큰이 시작 시 거부되던 문제 수정.- 같은 컴퓨터의 다른 로그인이 저장한
allowedProviders목록 때문에 세션 시작이 거부되던 문제 수정. NODE_EXTRA_CA_CERTS파일이 비어 있거나, PEM이 아니거나, 손상된 인증서로 시작하면 모든 연결이 실패하던 문제 수정. 이제 읽을 수 있는 인증서를 사용하고 stderr에 경고를 표시합니다.
세션과 재시작
- 잘못된 형식의 도구 호출 재시도가 소진된 뒤
--continue가 이전 대화를 잃을 수 있던 문제 수정 (2.1.314에서 발생한 회귀). - 유휴 압축이 대화를 요약이 아닌 응답으로 대체하던 문제 수정.
- 재시작한 세션이 API 오류로 실패한 메시지를 대기 중인 새 메시지보다 먼저 다시 보내던 문제 수정.
- Claude가 큰 이미지를 읽거나 도구 호출을 재시도한 직후 재시작하면 중단된 턴을 잃던 문제 수정.
- 유휴 비대화형 세션이 종료될 때 삭제한 대화 기록이 마지막 프롬프트와 함께 다시 만들어지던 문제 수정.
- 실행 중인 Bash 명령이 많은 macOS 세션이 멈추면서 메모리 사용량이 늘어나던 문제 수정.
claude -p와 Agent SDK
- mod가
turn.step에 훅을 걸어 둔 상태에서 API 오류로 응답이 끊겨도 성공으로 보고하던 문제 수정. - 헤드리스 실행에서 mod의
turn.step훅 때문에 중단한 응답이 성공으로 끝나던 문제 수정. - 실패하거나 Claude만 호출할 수 있는 사용자 정의 슬래시 명령이 아무것도 출력하지 않던 문제 수정.
- 헤드리스 세션에서 모델 변경 직후 보낸 메시지가 Stop 뒤에도 계속 실행되던 문제 수정. 이제 대기 중인 메시지와 똑같이 취소되거나 중단됩니다.
MCP와 플러그인
claude mcp add와remove가 잠금 없이 설정을 쓰던 문제 수정. 이제 잠금을 기다리거나 종료 코드 1로 끝납니다. 다만 다른 작업의 저장이 저장된 서버를 덮어쓸 수는 있습니다.- 버전 확인 요청에 종료하는 stdio MCP 서버를 시작할 때마다 다시 확인하던 문제 수정. 다른 이유로 3초 안에 종료되는 서버도 7일 동안 이전 방식의 핸드셰이크(연결 초기 절차)로 고정됩니다.
claude plugin명령이 느린 토큰 갱신이 저장되기 전에 종료해, 다음 실행 때 로그아웃될 수 있던 문제 수정.claude plugin marketplace add가 거부하는 사용자 지정 이름의 마켓플레이스 파일을claude plugin validate가 통과시키던 문제 수정.
클라우드 세션과 셀프 호스팅 러너
- 재시작 뒤 승인한 셸 명령이 요청된 폴더가 아니라 세션 시작 폴더에서 실행되던 문제 수정. 요청된 폴더에 들어갈 수 없으면 실행하지 않습니다.
- 클라우드 세션 재시작 뒤 승인된 커넥터 도구를 쓸 수 없어도 Claude가 알지 못하던 문제 수정.
- 서비스가 몇 분 동안 업로드를 거부하면 클라우드 세션이 턴 도중에 멈추던 문제 수정.
- 일부 클라우드 세션에서
Setup훅이CLAUDE_ENV_FILE에 쓴 변수가 Bash 도구에 전달되지 않던 문제 수정. - 응답이 도구 호출에서 끊기거나 거부된 이미지나 문서가 제거된 뒤, iPhone 앱이 실행 중인 클라우드 세션의 턴을 끝난 것으로 표시하던 문제 수정.
- 클라우드 세션의
/mcp가 모델이 쓸 수 없는 도구까지 세던 문제 수정. 이제 서버 행에 사용할 수 있는 도구 수가 표시됩니다. - [Cloud sessions] GitHub Actions 로그를 읽지 못하던 문제 수정.
gh run view --log와gh api로그 요청이 접근할 수 없는 리디렉션 대신 대부분의 환경에서 로그를 받습니다.
Remote Control과 버전 정리
- 업데이트나 버전 정리가 실행 중인 프로세스의 바이너리를 지운 뒤
claude remote-control호스트, 백그라운드 데몬, 셀프 호스팅 러너가 새 세션을 시작하지 못하던 문제(spawn ENOENT) 수정. sudo claude로 남은 프로세스처럼 다른 사용자가 소유한 Claude Code 프로세스를 버전 정리가 종료된 것으로 처리해 바이너리를 지울 수 있던 문제 수정.- 연결에 실패한 세션을
/remote-control이 사용 가능으로 표시하던 문제 수정. - 세션의 작업 폴더가 없을 때 오해하기 쉬운 “spawn error: ENOENT”가 표시되던 문제 수정. 이제 오류에 폴더 이름이 나옵니다.
- 환경 메뉴의 Remote Control 행에서 한 저장소의 나란한 체크아웃이 똑같이 보이던 문제 수정. 이제 각자의 폴더 이름이 표시됩니다.
도구와 명령
- 메시지를 보낸 직후나 느린 권한 확인이 나타나기 전에 입력한 키가 권한 확인의 답으로 처리되던 문제 수정.
- 사용량 한도로 멈춘 워크플로를 재개하면 끝난 에이전트를 다시 실행하던 문제 수정.
- 백그라운드 서브에이전트가 실행되는 동안 “Now using usage credits” 알림이 약 30초마다 다시 나타나던 문제 수정.
- 요청이 404로 실패했는데도
/design revoke가 성공으로 보고하던 문제 수정. - Claude가 PushNotification 호출에서 status 필드를 빠뜨리면 알림이 중복되던 문제 수정.
- 이미지가 20개를 넘는 요청에서 이미지 크기 초과 오류가 항상 2000px 제한이라고 안내하던 문제 수정. 이제 API의 제한 값을 표시합니다.
- 대화상자가 열려 있는 동안 백그라운드 셸 상세의 실행 시간이 갱신되지 않던 문제 수정.
VS Code 확장
- 조직 설정이 로그인을 거부하는 창이 백그라운드에서 매분 새 Claude Code 프로세스를 시작하던 문제 수정.
- 채팅 패널 오류 배너의 긴 단어가 닫기 버튼을 화면 밖으로 밀어내던 문제 수정.
Claude Tag
- 관리자 설정의 키보드 포커스와 스크린 리더 안내 문제 수정. 연결 양식에서 Escape를 눌러도 Add 대화상자가 함께 닫히지 않습니다.
알아두면 좋은 점
claude -p의 stderr를 읽는 스크립트가 있다면 저장된 claude.ai 로그인이 끝나기 10일 전부터 경고 한 줄이 추가된다는 점을 반영하세요.~/.claude.json이 유효한 JSON이 아니면 비대화형 실행이 이제 파일을 초기화하는 대신 실패합니다. 복원 방법은 오류 메시지에 나옵니다.- IDE 터미널에서 시작해도 IDE 확장이 설치되거나 업데이트되지 않습니다. 외부 터미널의
/ide나 편집기의 확장 화면을 사용하세요. - 셀프 호스팅 러너의 로그를 처리하는 스크립트가 있다면
retryable=true:나retryable=false:를 찾는 부분을 수정해야 합니다. deniedMcpServers에 URL 항목을 쓰고 있다면 이제 Anthropic 제공 서버와 일부 환경의 커넥터도 차단될 수 있습니다./claude-api managed-agents-onboard로 만든 새 에이전트의 기본 권한 정책은auto입니다.- 2.1.286 또는 그 이전 버전에서 시작한 대화를 재개하면 Claude의 이전 thinking(응답 전 추론 내용)이 사라질 수 있습니다. 이를 유지하던 2.1.288의 수정이 제거됐습니다.
- 이 글은 주요 항목만 정리했습니다. 전체 변경 목록은 GitHub 릴리스 노트에서 볼 수 있습니다.