Claude Code 토큰 절약: Token Optimizer 설치·사용법
Claude Code 토큰을 줄이는 Token Optimizer 설치·사용법을 정리했습니다. MCP와 플러그인 차이, Doctor 진단, 실전 프롬프트, 절감 리포트까지 확인하세요.
이런 분을 위한 글입니다
- Claude Code의 토큰 사용량이 부담스러운 분
- 큰 파일과 긴 로그를 자주 다루는 개발자
- Token Optimizer를 처음 설치하는 분
읽고 나면 이렇게 달라집니다
- Token Optimizer가 줄이는 낭비를 이해한다
- 플러그인을 설치하고 실제 작동 여부를 진단한다
- 복사해서 쓰는 실전 프롬프트를 익힌다
- 절감 리포트를 읽고 작업 습관을 개선한다
30초 요약: Token Optimizer란?
Token Optimizer는 Claude Code가 큰 파일, 반복 읽기, 넓은 검색, 긴 로그를 다룰 때 불필요한 원문이 문맥에 들어오는 양을 줄이는 제3자 오픈소스 플러그인입니다. Claude Code에서는 MCP 서버만 연결하는 것보다 Hook과 사용 안내가 포함된 플러그인 설치가 권장됩니다.
설치는 Claude Code 안에서 플러그인 명령 세 줄을 실행하면 됩니다. 설치 후에는 /mcp로 연결을 확인하고, 터미널에서 npx token-optimizer-doctor를 실행해 Hook이 실제로 작동하는지 검사하세요.
Claude Code로 코드 몇 줄만 수정했는데 대화의 문맥이 빠르게 커질 때가 있습니다. 답변을 짧게 해달라고 요청해도 토큰 사용량은 생각만큼 줄지 않습니다.
토큰은 Claude의 답변에만 쓰이지 않기 때문입니다. Claude가 파일을 읽고, 저장소를 검색하고, 테스트 로그를 확인하고, 이전에 알아낸 내용을 다시 추론할 때도 문맥이 사용됩니다.
Token Optimizer는 이 낭비를 줄이기 위한 제3자 오픈소스 도구입니다. Anthropic이 직접 개발하거나 공식 지원하는 제품은 아닙니다. 이 글에서는 개념 설명에 그치지 않고 설치, 진단, 실전 프롬프트, 절감 리포트 확인까지 한 번에 진행합니다.
답변을 짧게 만드는 것만으로 부족한 이유
2,000줄짜리 서버 파일에서 세 줄을 수정했다고 가정해보겠습니다.
수정 전 파일 전체를 한 번 읽고, 작업 후 확인을 위해 같은 파일 전체를 다시 읽으면 대부분의 내용이 문맥에 반복해서 들어옵니다. 지금 필요한 것은 변경된 세 줄인데 나머지 내용까지 다시 전달되는 셈입니다.
검색과 로그도 마찬가지입니다. 오류가 발생한 몇 줄만 필요하지만 수백 줄의 성공 로그나 관련 없는 검색 결과까지 함께 들어올 수 있습니다.
토큰 낭비는 주로 다음 작업에서 생깁니다.
- 이미 읽은 파일을 다시 확인할 때
- 큰 파일 전체에서 일부 코드만 필요할 때
- 저장소 검색 결과가 지나치게 많을 때
- 테스트와 빌드 로그 전체를 가져올 때
- 긴 API 응답이나 문서를 반복해서 전달할 때
- 지난 세션의 결론을 처음부터 다시 추론할 때
핵심은 Claude에게 무조건 짧게 답하라고 시키는 것이 아닙니다. 지금 판단에 필요하지 않은 원문이 문맥에 다시 들어오지 않게 만드는 것이 먼저입니다.
Token Optimizer는 무엇을 바꾸나요?
Token Optimizer는 큰 파일, 반복 읽기, 넓은 검색, 긴 로그를 더 작은 결과로 바꿉니다.
| 기능 | 활용 시점 |
|---|---|
smart_read | 큰 파일을 읽거나 이미 읽은 파일을 다시 확인할 때 |
smart_grep | 저장소 검색 결과가 너무 많을 때 |
smart_glob | 파일 경로 목록이 지나치게 길 때 |
smart_logs | 빌드·테스트 로그에서 실패 원인을 먼저 볼 때 |
optimize_text | 긴 문서나 API 응답을 문맥 밖에 보관할 때 |
get_cached | 보관한 원문이 다시 필요할 때 |
get_optimization_report | 실제 절감량과 작업별 결과를 확인할 때 |
/mcp에서 현재 노출된 도구를 먼저 확인하세요.smart_read로 파일을 처음 읽으면 내용을 확인하고 상태를 저장합니다. 같은 파일을 다시 smart_read할 때는 전체 원문 대신 변경된 부분을 중심으로 반환할 수 있습니다.
긴 텍스트는 별도 키로 보관하고 현재 대화에는 작은 참조와 요약만 남길 수 있습니다. 이전 작업에서 얻은 발견, 결정, 실패한 접근을 프로젝트별 지식으로 이어가는 기능도 제공합니다.
MCP 서버만 연결하면 충분할까요?
Claude Code에서는 플러그인 설치 방식이 권장됩니다.
MCP 서버만 연결해도 smart_read 같은 도구를 사용할 수 있습니다. 하지만 모델이 그 도구를 선택하지 않으면 기존의 큰 읽기가 그대로 실행될 수 있습니다.
플러그인은 MCP 서버뿐 아니라 세션 안내와 Hook을 함께 제공합니다. Hook은 비용이 큰 기본 호출을 감지하고 최적화 도구로 유도하거나, 설정된 모드에 따라 원래 호출을 거부하고 대체 경로를 알려줍니다.
- MCP 서버는 최적화 도구를 제공합니다.
- 플러그인은 그 도구를 실제 작업 흐름에 연결합니다.
- 자동으로 낭비를 줄이고 싶다면 플러그인 방식이 더 적합합니다.
설치 전 준비물
2026년 9월 공식 README 기준 요구 사항은 다음과 같습니다.
- Claude Code
- Node.js 22 이상
- npm 9 이상
- 최초 설치에 사용할 인터넷 연결
터미널에서 버전을 확인하세요.
claude --version
node -v
npm -vNode.js 버전이 22보다 낮다면 먼저 업데이트해야 합니다.
Claude Code에 설치하기
아래 명령은 일반 터미널이 아니라 Claude Code를 실행한 화면 안에서 한 줄씩 입력합니다.
1단계: 플러그인 마켓플레이스 추가
/plugin marketplace add ooples/token-optimizer-mcp2단계: Token Optimizer 설치
/plugin install token-optimizer@token-optimizer3단계: 플러그인 다시 불러오기
/reload-plugins4단계: 새 세션 시작
새 도구와 안내가 확실하게 적용되도록 Claude Code를 다시 시작하거나 새 세션을 여세요.
설치가 실제로 작동하는지 확인하기
플러그인이 목록에 보이는 것과 Hook이 실제로 작동하는 것은 다른 문제입니다. 두 단계로 확인해야 합니다.
1. MCP 연결 확인
Claude Code의 새 세션에서 다음 명령을 실행하세요.
/mcp목록에서 token-optimizer 관련 서버와 도구를 찾습니다.
2. Hook 동작 진단
별도 터미널에서 다음 명령을 실행하세요.
npx token-optimizer-doctor이 진단은 단순히 설치 파일의 존재 여부만 확인하지 않습니다. 실제 Hook에 가상의 요청을 전달해 큰 읽기는 최적화 경로로 유도되는지, 작은 읽기는 정상 통과하는지 검사합니다.
연결은 보이지만 진단에 실패한다면 다음 순서로 복구하세요.
npx token-optimizer-install
npx token-optimizer-doctor복구가 끝나면 Claude Code를 다시 시작합니다.
/mcp에서 서버가 보이고 npx token-optimizer-doctor 진단까지 통과했다면 기본 설치와 Hook 연결을 모두 확인한 것입니다.복사해서 바로 쓰는 실전 프롬프트
플러그인이 정상 작동하면 평소처럼 Claude Code를 사용해도 됩니다. 처음에는 아래 프롬프트로 도구 사용을 명시하면 작동 방식을 이해하기 쉽습니다.
1. 큰 파일을 읽고 변경분만 다시 확인하기
이 프로젝트에서 가장 큰 서버 파일을 찾아줘.
처음에는 token-optimizer의 smart_read로 구조와 핵심 책임을 파악해줘.
수정이 끝난 뒤 같은 파일을 다시 smart_read해서 전체 파일이 아니라 변경된 부분만 확인해줘.2. 저장소 전체 검색 결과 줄이기
사용자 인증 로직이 구현된 위치를 token-optimizer의 smart_grep으로 찾아줘.
모든 검색 결과를 나열하지 말고 실제 인증 흐름과 관련된 파일과 코드 구간부터 보여줘.
추가 결과가 필요할 때만 범위를 확장해줘.3. 긴 테스트 로그에서 실패 원인 먼저 찾기
테스트를 실행하고 긴 출력은 token-optimizer의 smart_logs로 분석해줘.
성공 로그는 요약하고 실패한 테스트 이름, 핵심 오류 메시지, 관련 파일 위치를 먼저 보여줘.
그다음 가장 가능성 높은 원인부터 설명해줘.4. 긴 API 응답을 문맥 밖에 보관하기
이 API 응답 전체를 optimize_text로 customer-schema라는 키에 보관해줘.
현재 대화에는 데이터 구조, 필수 필드, 주의할 예외만 요약해서 남겨줘.
원문은 실제 구현 중 필요한 경우에만 get_cached로 다시 가져와줘.5. 이전 작업의 결론 재사용하기
이 프로젝트를 분석하면서 발견한 아키텍처 결정, 주의할 제약, 실패했던 접근을 기록해줘.
다음에 관련 파일을 다룰 때 저장된 결론을 먼저 확인하고 같은 조사를 반복하지 않도록 해줘.6. 현재 토큰 절감 결과 확인하기
token-optimizer의 get_optimization_report를 실행해줘.
원래 토큰, 최적화 후 토큰, 총 절감량과 절감률을 보여줘.
도구별로 어디에서 가장 많이 절감됐는지 설명해줘.
다음에 개선할 작업 습관 세 가지도 추천해줘.첫 절감 리포트 만들기
설치 직후에는 측정된 작업이 거의 없어 숫자가 작거나 의미가 없을 수 있습니다. 아래 실습을 한 번 진행한 뒤 확인하세요.
1단계: 실제 프로젝트 열기
파일이 어느 정도 있고 테스트나 빌드를 실행할 수 있는 프로젝트를 엽니다.
2단계: 큰 파일 읽기
smart_read로 큰 파일 하나의 구조를 파악합니다.
3단계: 작은 수정 진행
오류 메시지, 타입 정의, 주석처럼 결과를 쉽게 확인할 수 있는 작은 수정을 진행합니다.
4단계: 같은 파일 다시 확인
같은 파일을 smart_read로 다시 읽어 변경된 부분이 중심으로 돌아오는지 확인합니다.
5단계: 검색과 로그 분석
smart_grep으로 저장소를 검색하고 smart_logs로 테스트 출력을 분석합니다.
6단계: 리포트 요청
get_optimization_report를 실행해 누적 결과를 확인합니다.
절감 리포트 읽는 법
환경과 버전에 따라 표현은 달라질 수 있지만 다음 항목을 중심으로 보면 됩니다.
- Original tokens: 최적화하지 않았다면 들어왔을 원래 토큰량
- Optimized tokens: 최적화 후 남은 토큰량
- Total tokens saved: 두 값의 차이
- Overall reduction: 전체 감소 비율
- Operations tracked: 측정에 포함된 작업 수
- By action 또는 tool: 어떤 도구에서 절감됐는지
- By hook phase: 어느 Hook 단계에서 절감됐는지
- By MCP server: 어떤 MCP 서버 작업에서 절감됐는지
큰 절감률 하나만 보지 마세요. 내 작업에서 어떤 행동이 반복적으로 문맥을 키웠는지가 더 중요합니다.
smart_read 절감량이 크다면 같은 파일을 여러 번 읽는 작업이 많았다는 뜻입니다. 로그 관련 절감이 크다면 테스트 출력 전체를 가져오는 습관부터 개선할 수 있습니다.
자주 막히는 문제
잠시 약하게 사용하거나 끄기
advise는 최적화 방법만 안내하고 기존 호출을 거부하지 않습니다. off는 Hook 개입을 끕니다.
TOKEN_OPTIMIZER_MODE=advise claude
TOKEN_OPTIMIZER_MODE=off claude$env:TOKEN_OPTIMIZER_MODE="advise"
claude$env:TOKEN_OPTIMIZER_MODE="off"
claude이 설정은 해당 터미널에서 시작한 Claude Code에만 적용됩니다. 새 터미널에서 평소처럼 실행하면 기본 모드로 돌아옵니다.
데이터는 어디에 저장되나요?
공식 README는 별도 계정과 외부 텔레메트리, 호스팅 서비스 없이 로컬에서 작동한다고 설명합니다.
| 데이터 | 기본 위치 |
|---|---|
| 캐시 | ~/.token-optimizer-cache/ |
| 분석 데이터 | ~/.token-optimizer-mcp/analytics.db |
| 세션과 설정 | ~/.token-optimizer/ |
업무용 저장소에서는 설치되는 Hook, 설정 파일, 패키지 권한을 검토하고 조직의 보안 정책을 먼저 따르세요.
사용 중지와 제거
문제가 생겼다면 바로 제거하기보다 먼저 advise 또는 off 모드로 원인을 확인할 수 있습니다.
수동으로 연결한 Hook을 제거할 때는 패키지의 package.json이 있는 폴더에서 다음 명령을 사용합니다.
npm run uninstall-hooks
npm run uninstall-hooks -- --apply첫 번째 명령은 제거 계획만 보여줍니다. 두 번째 명령이 실제 제거를 적용합니다. 직접 수정한 파일은 무조건 지우지 않도록 설계되어 있으므로 출력된 목록을 확인하세요.
Claude Code 플러그인은 /plugin 메뉴에서 token-optimizer를 찾아 제거한 뒤 Claude Code를 다시 시작합니다. 마지막으로 /mcp에서 관련 서버가 남았는지 확인하세요.
자주 묻는 질문
오늘 바로 해볼 체크리스트
- Claude Code, Node.js, npm 버전을 확인했다.
- Claude Code 안에서 플러그인 설치 명령 세 줄을 실행했다.
- 새 세션에서
/mcp연결을 확인했다. -
npx token-optimizer-doctor진단을 통과했다. - 큰 파일을
smart_read로 읽었다. - 같은 파일을 수정한 뒤 변경 내용을 다시 확인했다.
- 검색 또는 테스트 로그를 최적화 도구로 분석했다.
-
get_optimization_report로 첫 리포트를 확인했다.
마무리
Token Optimizer의 핵심은 Claude에게 억지로 짧게 답하도록 만드는 것이 아닙니다.
이미 읽은 파일, 관련 없는 검색 결과, 긴 로그, 이전에 알아낸 결론처럼 지금 판단에 필요하지 않은 내용이 문맥에 반복해서 들어오지 않도록 작업 흐름을 바꾸는 것입니다.
처음부터 모든 기능을 외울 필요는 없습니다. 오늘은 플러그인을 설치하고 Doctor 진단을 통과한 뒤 큰 파일 하나를 smart_read로 읽어보세요. 작업을 몇 번 진행한 다음 절감 리포트를 확인하면 내 프로젝트에서 토큰이 어디로 새고 있었는지 구체적으로 알 수 있습니다.