Source: https://aiprimetech.io/ko/blog/claude-code-max-output-tokens/

2026년 9월 10일 · 8분 · 개발자 가이드 

# CLAUDE_CODE_MAX_OUTPUT_TOKENS 설명: Claude Code 2.1.265의 출력 한도 및 플러그인 폴더 

 A  작성자 [AI Prime Tech](https://aiprimetech.io/ko/)  · AI 활용    

claude_code_max_output_tokens 는 다음 항목에 대한 검색어입니다. CLAUDE_CODE_MAX_OUTPUT_TOKENS, 대부분의 요청에 대한 최대 출력 토큰 수를 설정하는 Claude Code 환경 변수입니다. 이 가이드에서는 2026년 9월 10일까지 확인된 한도, 설정 예제를 해석하는 방법, Claude Code 2.1.265에서 플러그인 폴더와 저장된 도구 결과에 적용된 변경 사항을 설명합니다. 

## claude_code_max_output_tokens가 제어하는 항목 

환경 변수 참조 문서에서는 CLAUDE_CODE_MAX_OUTPUT_TOKENS 가 “대부분의 요청에 대한 최대 출력 토큰 수”를 설정한다고 설명합니다. 이 표현은 중요합니다. 이는 요청의 출력 예산을 뜻하며, 기본값과 상한은 모델마다 다릅니다. 

따라서 이 변수는 Claude Code의 출력 한도를 조사할 때 관련이 있습니다. Claude Code가 처리하는 모든 유형의 데이터에 적용되는 공통 한도로 간주해서는 안 됩니다. 버전 2.1.265에는 저장된 도구 결과에 대한 디스크 한도도 도입되었지만, 이 한도는 생성된 출력을 토큰 단위로 측정하는 것이 아니라 저장된 도구 데이터를 기가바이트 단위로 측정합니다. 

설정 문서에는 과거 시점과 관련된 유의 사항이 있습니다. [환경 변수 참조 문서](https://code.claude.com/docs/en/env-vars) 는 계속 업데이트되며, 9월 10일 당시의 정확한 개정본은 확보하지 못했습니다. 해당 설명은 변수의 용도를 설명하지만, 이 페이지로는 Claude Code 2.1.265에 적용되었던 모든 기본값을 확정할 수 없습니다. 

특정 날짜를 기준으로 작성하는 글에서는 버전 태그가 지정된 릴리스 노트가 가장 확실한 수치 근거를 제공합니다. 이 릴리스 노트는 현재 문서에서 전체 기본값 표를 추론할 필요 없이 이전의 구체적인 변경 사항을 확인해 줍니다. 

### 구분해야 할 세 가지 한도 

  | 한도  | 관련 대상  | 기준일까지 확인된 정보    

  | 요청 출력 예산  | 대부분의 요청에 대한 최대 출력 토큰 수  | v2.1.77에 문서화된 모델별 변경 사항  

  | 모델 컨텍스트 윈도우  | 문서에 명시된 모델의 컨텍스트 용량  | Sonnet 5, Opus 5, Fable 5.1의 1백만 토큰 컨텍스트 윈도우  

  | 저장된 도구 결과 상한  | 디스크에 저장된 도구 결과  | v2.1.265에 도입된 1 GB 상한    

한도 문제를 진단할 때는 먼저 이 중 어떤 한도가 적용되는지 확인하세요. 토큰 예산 설정과 디스크 저장 공간 상한은 같은 개발 세션에서 나타나더라도 서로 다르게 해석해야 합니다. 

## 확인된 기본값과 최대 출력 한도 

이 [v2.1.77 릴리스 노트](https://github.com/anthropics/claude-code/releases/tag/v2.1.77)는 2026년 3월 17일에 작성되었으며, 두 가지 관련 변경 사항을 기록합니다. Claude Opus 4.6의 기본 출력 토큰 수가 64k으로 증가했고, Opus 4.6와 Sonnet 4.6의 상한이 128k토큰으로 증가했습니다. 이 변경 사항은 v2.1.265 태그가 지정된 변경 로그에도 보존되어 있습니다. 

이 근거에 따르면 “기본값 32,000, 최댓값 64,000”을 Claude Code의 공통 규칙으로 제시할 수 없습니다. 또한 다른 모델의 누락된 기본값을 임의로 채울 근거도 되지 않습니다. 

  | 모델  | 날짜가 명시된 자료로 확인된 Claude Code 기본값  | 문서에 명시된 상한    

  | Claude Opus 4.6  | v2.1.77에서 64k으로 증가  | v2.1.77에서 128k  

  | Claude Sonnet 4.6  | 검토한 날짜 명시 자료로는 확인되지 않음  | v2.1.77에서 128k    

문서화된 변경 사항과 완전한 설정 참조 문서를 신중하게 구분해야 합니다. 3월 릴리스는 위의 변경 사항을 확인해 주지만, 확보한 날짜 명시 자료로는 v2.1.265의 전체 모델별 기본값 표를 확정할 수 없습니다. 

### 최신 모델 사양으로 CLI 기본값을 확정할 수는 없습니다 

이 [모델 릴리스 노트](https://platform.claude.com/docs/en/release-notes/overview) 는 Claude Sonnet 5, Claude Opus 5, Claude Fable 5.1에 대해 최대 출력 128k과 1백만 토큰 컨텍스트 윈도우를 명시합니다. 각 모델의 정확한 API ID는 claude-sonnet-5, claude-opus-5및 claude-fable-5-1이며, 앞서 나열한 모델 순서와 각각 대응합니다. 

이 발표는 발행 기준일 전에 공개되었습니다. Sonnet 5은 6월 30일, Opus 5는 7월 24일, Fable 5.1는 2026년 9월 1일에 발표되었습니다. 하지만 이 모델 사양은 Claude Code의 기본 요청 예산을 입증하는 근거가 아닙니다. 

모델을 선택하는 개발자는 [Claude Code 모델 가이드](/ko/claude-code/models/) 에서 관련 내용을 읽을 수 있습니다. 모델이 공개한 최댓값과 CLI에서 사용하는 기본 출력 예산을 구분하세요. 

## 변수 설정과 압축 동작 이해하기 

현재 문서에 따르면 이 변수는 다음을 실행하기 전에 설정하거나 claude, 다음 항목의 env 키 아래에 넣을 수 있습니다. 해당 항목은 settings.json입니다. 9월 10일 당시 제공되었던 문서의 정확한 개정본은 확보하지 못했으므로, 아래 예제는 이러한 과거 시점 관련 유의 사항이 있는 문서화된 설정 패턴입니다. 

### 셸 설정 

제공된 셸 예제는 출력 예산을 64,000토큰으로 설정합니다. 

```
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

```

문서에 명시된 패턴은 Claude Code를 실행하기 전에 변수를 설정하는 것입니다. 이 예제의 숫자는 선택한 설정값이며, 64,000이 모든 모델의 기본값이나 최댓값이라는 주장은 아닙니다. 

프로젝트나 문제 해결 세션의 설정을 기록할 때는 요청한 예산과 함께 선택한 모델도 명시하세요. 모델 정보가 없으면 값만으로는 문서에 명시된 기본값과 일치하는지, 또는 문서에 명시된 상한 이내인지 설명할 수 없습니다. 

### settings.json 설정 

제공된 동등한 JSON 예제는 변수를 다음 항목 아래에 배치합니다. env: 

```
{"env":{"CLAUDE_CODE_MAX_OUTPUT_TOKENS":"64000"}}

```

이 예제에서 값은 문자열입니다. 셸 설정과 마찬가지로 이 코드 조각은 요청한 예산을 나타낼 뿐, 모델별 기본값을 입증하지는 않습니다. 

관련 명령줄 사용법은 다음을 참조하세요. [Claude Code CLI 참조](/ko/claude-code/cli/). 여기서 제시한 과거 자료는 변수의 역할과 제공된 설정 예제를 뒷받침하지만, v2.1.265의 전체 기본값은 여전히 확인되지 않았습니다. 

### 압축에 관해 확인된 사항은 무엇인가요? 

v2.1.265 태그가 지정된 변경 로그에는 v2.1.69에서 다음 항목과 관련해 이루어진 이전 수정 사항이 기록되어 있습니다. CLAUDE_CODE_MAX_OUTPUT_TOKENS 가 대화 압축 중 무시되던 문제를 수정한 것입니다. 이는 이 설정과 압축 동작 사이에 확인된 연관성이 있음을 보여 줍니다. 

현재 환경 변수 참조 문서는 이 설정값을 높이면 자동 압축 전에 사용할 수 있는 유효 컨텍스트가 줄어든다고도 설명합니다. 이 설명의 게시 날짜는 불확실하므로, 9월 10일 기준으로 확인된 설명이라고 제시할 수는 없습니다. 

따라서 이 설정이 모델이 공개한 컨텍스트 윈도우를 확장한다고 설명해서는 안 됩니다. 날짜가 명시된 근거는 출력 예산 제어 기능과 압축 관련 수정 사항을 확인해 주지만, v2.1.265의 모든 모델에 대한 정확한 압축 임계값을 확정해 주지는 않습니다. 

## Claude Code 2.1.265의 플러그인 폴더 로드 방식 

[Claude Code v2.1.265](https://github.com/anthropics/claude-code/releases/tag/v2.1.265) 는 2026년 9월 8일에 출시되었으며, 릴리스 커밋은 8e02f6d입니다. 폴더 로드 방식의 변경으로 다음 항목이 --plugin-dir 여러 플러그인이 포함된 폴더를 가리킬 수 있게 되었습니다. 

제공된 실행 명령은 다음과 같습니다. 

```
claude --plugin-dir ./plugins

```

릴리스는 탐색 규칙을 “매니페스트가 있는 각 하위 폴더를 로드한다”라고 직접 설명합니다. 또한 Claude Code가 실행되는 동안 추가와 삭제를 감지한다고 명시합니다. 

따라서 여러 플러그인을 함께 관리할 때는 상위 폴더가 유용한 관리 단위가 됩니다. 문서에 명시된 동작은 매니페스트가 포함된 하위 폴더에 관한 것이며, 릴리스 노트는 재귀적 탐색을 명시하지 않습니다. 임의로 중첩된 디렉터리 트리 전체를 검색한다고 가정하지 마세요. 

### 매니페스트 구조와 과거 시점 관련 유의 사항 

현재 플러그인 참조 문서는 매니페스트를 다음 위치에 배치하고 .claude-plugin/plugin.json , 다음과 같은 구성 요소 디렉터리를 skills/, commands/및 hooks/ 플러그인 루트에 배치하도록 안내합니다. 이 참조 문서는 날짜가 명시된 v2.1.265 스냅샷으로 확보하지 못했습니다. 

9월 10일 기준의 글에서는 현재의 구조 안내와 릴리스가 명시적으로 보장하는 사항을 구분하세요. 명시적으로 보장하는 사항은 매니페스트가 있는 하위 폴더가 로드된다는 것입니다. 이 릴리스는 여러 플러그인이 포함된 폴더의 탐색을 확인해 주지만, 당시 구조 문서의 모든 세부 사항을 확정해 주지는 않습니다. 

### 릴리스에 포함된 플러그인 수정 사항 

버전 2.1.265은 다음 세 가지 플러그인 문제도 수정합니다.  
- 백슬래시가 포함된 플러그인 경로가 macOS와 Linux에서 심볼릭 링크의 경로 범위 제한을 우회할 수 있었습니다. 
- 점 두 개로 시작하는 디렉터리가 잘못 거부되었습니다. 
- 읽을 수 없는 기본 구성 요소 폴더가 별도 알림 없이 건너뛰어졌습니다. 이제는 다음 항목에 /plugin 오류 코드와 함께 표시됩니다.  

이 수정 사항은 플러그인 경로와 구성 요소 로드에 관한 것입니다. 플러그인 폴더가 로드되지 않을 때 관련 릴리스 맥락을 제공하지만, 출력 토큰 설정으로는 이러한 디렉터리 처리 문제를 설명할 수 없습니다. 

## 저장된 도구 결과의 1 GB 상한은 별도의 한도입니다 

버전 2.1.265은 디스크에 저장되는 도구 결과에 1 GB 상한을 추가합니다. 대화 미리보기는 결과가 잘렸음을 표시합니다. 

이 한도는 저장된 도구 데이터에 관한 것입니다. CLAUDE_CODE_MAX_OUTPUT_TOKENS 는 대부분의 요청에 대한 최대 출력 토큰 수에 관한 것입니다. 릴리스는 이 환경 변수가 디스크 상한을 제어한다고 설명하지 않으므로, 값을 높이는 것을 저장된 도구 결과 잘림의 해결책으로 제시해서는 안 됩니다. 

릴리스 노트는 1 GB 상한이 결과별로 적용되는지, 세션별로 적용되는지, 또는 다른 단위로 적용되는지도 명시하지 않습니다. 동작을 문서화할 때 이러한 불확실성을 유지하세요. 확인된 설명은 “디스크에 저장되는 도구 결과에 대한 1 GB 상한”입니다. 

문제 해결에 유용한 구분 기준은 개발자에게 표시되는 근거입니다. 잘림을 알리는 대화 미리보기는 새로 도입된 결과 저장 동작과 관련이 있습니다. 모델의 생성 출력 예산에 관한 질문은 선택한 모델 및 토큰 설정과 관련이 있습니다. 다음 항목에 표시되는 플러그인 오류 코드는 /plugin 플러그인 로드와 관련이 있습니다. 

이들은 동일한 릴리스 맥락에서 도입되거나 논의된 별개의 제어 항목과 진단 기능입니다. 이를 별도로 다루면 토큰 설정 변경으로 무관한 저장 공간이나 폴더 동작을 설명하는 일을 방지할 수 있습니다. 

## 9월 10일까지 제공된 게이트웨이 후속 릴리스 

버전 2.1.266도 9월 8일에 출시되었으므로 이 문서의 기준일 범위에 포함됩니다. 해당 [v2.1.266 릴리스 노트](https://github.com/anthropics/claude-code/releases/tag/v2.1.266) 다음과 관련된 v2.1.265의 게이트웨이 인증 회귀 문제를 수정합니다. CLAUDE_CODE_USE_GATEWAY. 

관련 오류는 “Cloud 게이트웨이에 로그인되어 있지 않습니다”입니다. 릴리스 안내에는 설정을 변경할 필요가 없다고 명시되어 있습니다. 

v2.1.265에서 바로 이 회귀 문제를 겪는 개발자에게는 후속 릴리스가 직접적인 관련이 있습니다. 출력 토큰 예산을 늘리거나 플러그인 폴더를 재구성하는 것은 문서에 명시된 해결 방법이 아닙니다. 

동일한 워크플로는 AI Prime Tech 같은 API 게이트웨이를 통해서도 실행할 수 있습니다. 다음 문서를 참고하세요 [API 키로 Claude Code 사용하기](/ko/learn/claude-code-api-key-setup/) 에서 관련 설정 안내를 확인하세요. AI Prime Tech는 독립적으로 운영되며 Anthropic 또는 OpenAI와 제휴 관계가 없습니다. 

## 핵심 요점  
- CLAUDE_CODE_MAX_OUTPUT_TOKENS 대부분의 요청에 대한 최대 출력 토큰 수를 설정하며, 기본값과 상한은 모델마다 다릅니다. 
- v2.1.77에서는 Opus 4.6의 기본값을 64k로, Opus 4.6/Sonnet 4.6의 상한을 128k로 늘렸습니다. v2.1.265의 전체 기본값 표는 아직 검증되지 않았습니다. 
- 모델의 최대 출력, 모델의 컨텍스트 용량, 저장된 도구 결과의 저장 공간은 각각 별개의 한도입니다. 
- v2.1.265에서는 --plugin-dir 매니페스트가 있는 하위 폴더에서 여러 플러그인을 로드하고, 실행 중에 추가 및 제거를 감지할 수 있습니다. 
- v2.1.265에서는 저장된 도구 결과에 1 GB 한도를 도입했으며, v2.1.266에서는 설정 변경 없이 게이트웨이 인증 회귀 문제를 수정합니다.  

## 자주 묻는 질문 

### CLAUDE_CODE_MAX_OUTPUT_TOKENS은 무엇을 제어하나요? 

CLAUDE_CODE_MAX_OUTPUT_TOKENS 대부분의 요청에 대한 최대 출력 토큰 수를 설정합니다. 기본값과 상한은 모델마다 다르며, 디스크에 저장된 도구 결과에 적용되는 v2.1.265의 1 GB 한도와는 별개입니다. 

### 기본 출력 한도와 최대 출력 한도는 얼마인가요? 

v2.1.77에서는 Claude Opus 4.6의 기본값을 출력 토큰 64k개로, Opus 4.6/Sonnet 4.6의 상한을 128k로 늘렸습니다. 검토한 날짜가 명시된 자료만으로는 Sonnet 4.6의 기본값이나 v2.1.265의 전체 모델별 기본값 표를 확인할 수 없습니다. 

### 설정값을 높이면 컨텍스트 창이 커지나요? 

문서에 명시된 목적은 출력 토큰 예산을 설정하는 것이며, 모델의 공개된 컨텍스트 창을 늘리는 것이 아닙니다. v2.1.69에서는 압축 중에 이 변수가 무시되는 문제를 수정했지만, 현재 온라인 문서에서 자동 압축에 미치는 영향을 설명한 부분의 게시 날짜는 불확실합니다. 

### --plugin-dir는 여러 플러그인을 어떻게 검색하나요? 

Claude Code 2.1.265에서는 --plugin-dir 상위 폴더를 지정할 수 있으며, 매니페스트가 있는 각 하위 폴더가 로드됩니다. Claude Code가 실행되는 동안 추가 및 제거를 감지하며, 릴리스 노트에는 재귀 검색 여부가 명시되어 있지 않습니다. 

[Claude](/ko/blog/tag/claude/)[코딩](/ko/blog/tag/coding/)[API](/ko/blog/tag/api/) 

A

[AI Prime Tech](https://aiprimetech.io/ko/)

이 블로그는 AI Prime Tech가 발행합니다. 기사는 AI의 도움을 받아 초안을 작성합니다. 모델 ID, 가격, 한도 등 버전별 세부 정보는 활용하기 전에 공식 문서와 대조해 확인하세요. 

 더 저렴하게 Claude API 이용하기 

API 키 하나로 Claude Opus 5.5, Sonnet 5, Haiku 4.5, Fable 5.1 및 GPT-6개 모델을 이용하세요. 구독 없이 사용한 만큼만 결제합니다. [API 키 받기 →](/register)  

AI Prime Tech는 독립적인 타사 API 게이트웨이입니다. Claude™ 및 Anthropic®는 Anthropic, PBC의 상표입니다. 제휴 또는 보증 관계를 의미하지 않습니다.