코딩 에이전트를 오래 쓰다 보면 성능보다 먼저 체감되는 문제가 토큰 사용량이다. 특히 Claude Code나 Codex처럼 파일 검색, 툴 호출, IDE 연동, MCP 연결을 함께 쓰는 도구는 모델 호출 자체보다 주변 설정에서 토큰이 많이 새는 경우가 있다.
이 글은 Claude Code와 Codex에서 토큰 효율에 영향을 주는 설정을 정리한 글이다. 핵심은 단순히 “더 싼 모델을 쓰자”가 아니라, 자동으로 붙는 컨텍스트와 과도한 툴 출력을 줄여 에이전트가 필요한 정보만 보게 만드는 것이다.
한눈에 보기
토큰 사용량이 늘어나는 주요 경로는 크게 세 가지다.
- 세션이나 턴마다 자동으로 붙는 추가 컨텍스트
- 대화 히스토리에 남는 긴 툴 호출 출력
- 검색, 커넥터, IDE 연동 등 외부 연결로 인한 추가 호출
Claude Code는 설정과 환경변수로 조절할 수 있는 범위가 넓다. 반면 Codex는 Claude Code보다 레버는 적지만, MCP 앱 주입, 웹 검색, 툴 출력 상한 같은 부분은 명확히 조절할 수 있다.
Claude Code에서 토큰이 늘어나는 지점
Claude Code는 기본적으로 단순한 채팅 모델이 아니라 코딩 에이전트다. 그래서 작업을 시작할 때부터 여러 종류의 정보가 시스템 프롬프트와 컨텍스트에 붙는다.
예를 들면 다음과 같은 것들이다.
- MCP 서버 정의
- 스킬 또는 서브에이전트 정의
- 툴 정의
- 훅 설정
- 메모리
CLAUDE.md- IDE에서 전달되는 파일, 선택 영역, 진단 정보
- Git 관련 지시문
- 긴 Bash 출력
- 대용량 파일 Read 결과
이 정보들은 복잡한 작업에서는 도움이 된다. 하지만 간단한 수정, 파일 이동, 정규식 기반 변경, 반복 자동화 작업에서는 오히려 불필요한 컨텍스트가 된다.
Claude Code 설정에서 볼 부분
includeGitInstructions: false
Claude Code는 기본적으로 Git 관련 지시문을 포함할 수 있다. 커밋, PR, 브랜치 흐름까지 에이전트가 다뤄야 하는 작업이라면 유용하지만, 단순 코드 수정이나 로컬 작업에서는 매번 필요한 정보가 아닐 수 있다.
Git 관련 자동 지시가 필요 없다면 이 설정을 끄는 것만으로도 기본 컨텍스트를 줄일 수 있다.
{
"includeGitInstructions": false
}단, 팀 단위로 Claude Code가 커밋 메시지나 PR 설명까지 생성하는 흐름을 표준화하고 있다면 무조건 끄기보다 작업 유형별로 나누는 편이 낫다.
autoConnectIde: false
autoConnectIde는 외부 터미널에서 Claude Code를 실행했을 때 VS Code나 JetBrains 같은 IDE와 자동 연결할지를 결정한다.
IDE 연결이 켜져 있으면 현재 열린 파일, 선택 영역, 에러 정보 같은 IDE 문맥이 자동으로 들어갈 수 있다. 이 흐름은 “선택한 부분 고쳐줘”처럼 IDE 중심으로 작업할 때는 편하다.
하지만 터미널 중심으로 작업하고, 린트나 타입 체크도 CLI에서 확인한다면 불필요한 컨텍스트가 늘어날 수 있다.
끄는 게 나은 경우는 다음과 같다.
- 터미널에서 Claude Code를 주로 실행한다
- 선택 영역 기반 지시를 거의 쓰지 않는다
- IDE 진단보다
npm run lint,npm test,tsc같은 CLI 결과를 기준으로 작업한다
반대로 IDE에서 선택한 코드나 진단 정보를 자주 활용한다면 끄지 않는 편이 낫다. 토큰 절약보다 작업 속도와 정확도가 더 중요할 수 있기 때문이다.
CLAUDE_CODE_GLOB_NO_IGNORE=false
Claude Code의 Glob 도구는 파일을 패턴으로 찾을 때 사용된다. 기본 설정에서는 .gitignore에 들어간 파일도 검색 결과에 포함될 수 있다.
모노레포나 프론트엔드 프로젝트에서는 이 차이가 꽤 크다. node_modules, 빌드 산출물, 캐시 디렉터리, generated 파일이 검색 결과에 섞이면 한 번의 Glob 결과가 길어지고, 그 결과를 따라 불필요한 Read 호출이 이어질 수 있다.
export CLAUDE_CODE_GLOB_NO_IGNORE=false이 설정은 .gitignore에 들어간 파일을 자주 만지는 프로젝트에서는 불편할 수 있다. 하지만 일반적인 앱 개발, 리팩토링, 테스트 수정 중심이라면 검색 공간을 줄이는 효과가 있다.
출력 상한은 신중하게 줄여야 한다
Claude Code에서는 Bash 출력, 파일 Read, MCP 출력의 상한을 환경변수로 조정할 수 있다.
예시로는 다음과 같은 값들이 있다.
export BASH_MAX_OUTPUT_LENGTH=12000
export CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS=12000
export MAX_MCP_OUTPUT_TOKENS=12000출력 상한을 낮추면 대형 로그나 대형 파일 하나 때문에 컨텍스트가 급격히 커지는 문제를 막을 수 있다. 다만 단점도 명확하다.
긴 출력에서 가장 중요한 정보는 대개 뒤쪽에 있다. 테스트 실패 요약, 최신 스택트레이스, 에러 원인 같은 정보가 잘릴 수 있다. 그러면 에이전트가 다시 tail, grep, 재실행을 반복하면서 오히려 토큰을 더 쓸 수 있다.
따라서 출력 상한은 “무조건 작게”가 아니라 “폭발 방지용 안전장치”로 보는 편이 맞다.
간단한 작업에는 가벼운 Claude Code 모드를 따로 두기
Claude Code를 항상 풀옵션으로 실행할 필요는 없다. 간단한 작업이나 비대화형 자동화에서는 MCP, 메모리, CLAUDE.md, 빌트인 에이전트, 슬래시 커맨드 정의를 줄인 모드를 따로 만들 수 있다.
예시는 다음과 같다.
alias ccb='ENABLE_CLAUDEAI_MCP_SERVERS=false CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 CLAUDE_CODE_DISABLE_CLAUDE_MDS=1 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 DISABLE_TELEMETRY=1 claude --tools "Bash,Edit,Glob,Grep,Read,Write" --disable-slash-commands --exclude-dynamic-system-prompt-sections'이런 별도 alias는 특히 반복 작업에 유용하다.
- 파일명 일괄 변경
- 단순 import 정리
- 정규식 기반 수정
- 테스트 로그 요약
- 특정 디렉터리 내 코드 스타일 변경
- 비대화형 워커 실행
핵심은 모든 기능을 끄는 것이 아니다. 작업에 필요한 도구만 켜두는 것이다. 예를 들어 로컬 코드 수정에는 Bash, Edit, Glob, Grep, Read, Write 정도면 충분한 경우가 많다.
Codex에서 볼 설정
Codex는 Claude Code에 비해 직접 조절할 수 있는 설정이 적다. 그래도 토큰 효율에 영향을 주는 지점은 있다.
ChatGPT에 연결된 앱과 커넥터 끄기
Codex CLI를 ChatGPT OAuth로 사용하는 경우, ChatGPT에 연결된 앱과 커넥터 정보가 시스템 프롬프트에 들어갈 수 있다.
로컬 코드베이스 수정만 하는데 외부 앱이나 커넥터가 필요 없다면 다음 설정을 고려할 수 있다.
[features]
apps = false
[apps._default]
enabled = false이 설정은 불필요한 앱 정보가 시스템 프롬프트에 주입되는 것을 줄이고, 에이전트가 필요 없는 외부 호출로 빠지는 가능성도 낮춘다.
단, 프로젝트에서 별도로 연결해둔 MCP까지 모두 꺼지는 것은 아니므로 MCP 설정은 따로 관리해야 한다.
web_search = "disabled"
Codex CLI에서는 웹 검색이 기본적으로 사용할 수 있는 기능으로 설정될 수 있다. 로컬 코드 수정, 테스트 수정, 리팩토링처럼 외부 검색이 필요 없는 작업이라면 웹 검색을 끄는 것이 낫다.
web_search = "disabled"이 설정은 에이전트가 불필요하게 검색 툴을 호출하는 것을 막는다.
다만 라이브러리 최신 API, 공식 문서 확인, 에러 원인 검색처럼 외부 정보가 필요한 작업에서는 검색을 켜는 편이 낫다. 특히 최신 프레임워크, SDK, 클라우드 설정은 로컬 코드만 보고 판단하면 오진할 수 있다.
tool_output_token_limit
Codex에서는 개별 툴 출력 저장량을 제한하는 tool_output_token_limit 설정을 볼 수 있다.
tool_output_token_limit = 10000이 값은 대량 출력이 세션을 크게 잡아먹는 문제를 줄이는 데 도움이 된다. Claude Code의 출력 상한과 비슷하게 보면 된다.
다만 마찬가지로 너무 낮게 잡으면 로그의 핵심 부분이 잘리고, 에이전트가 재조회하면서 오히려 호출 수가 늘어날 수 있다. 테스트 로그나 빌드 로그를 자주 다루는 프로젝트라면 과도하게 낮추지 않는 편이 안정적이다.
Codex 비대화형 실행에서 쓸만한 플래그
Codex는 codex exec로 비대화형 실행을 할 수 있다. 반복 자동화나 파이프라인에서 사용할 때는 다음 플래그들이 토큰과 실행 안정성에 도움이 된다.
codex exec \
--profile lightweight \
--json \
--output-last-message result.md \
--sandbox read-only \
--ephemeral \
--color never각 플래그의 의미는 대략 다음과 같다.
--profile: 특정 설정 묶음을 선택해서 실행--json: 파이프라인에서 결과 파싱을 쉽게 만듦--output-last-message FILE: 마지막 응답만 파일로 저장--sandbox read-only: 읽기 전용 작업에서 의도치 않은 수정 시도를 방지--ephemeral: 세션 파일 저장을 줄임--color never: 터미널 색상 코드가 섞이는 것을 방지
읽기만 필요한 분석 작업이라면 --sandbox read-only가 특히 유용하다. 에이전트가 수정 권한이 있는 줄 알고 파일을 바꾸려다 실패하고, 다시 계획을 세우고, 재시도하는 흐름이 줄어든다.
실무적으로 적용할 때의 기준
토큰 효율 설정은 한 번에 전부 줄이는 방식보다 작업 유형별 프로필로 나누는 편이 낫다.
예를 들어 다음처럼 나눌 수 있다.
1. 일반 개발 모드
복잡한 기능 개발, 리팩토링, 테스트 수정에 쓰는 기본 모드다.
- 파일 Read, Grep, Edit, Bash 활성화
- 프로젝트 문서 유지
- 웹 검색은 필요할 때만 활성화
- 출력 상한은 너무 낮추지 않음
- IDE 연결은 본인 작업 스타일에 맞게 결정
2. 경량 수정 모드
작고 반복적인 변경에 쓰는 모드다.
- MCP 비활성화
- 자동 메모리 비활성화
- 불필요한 슬래시 커맨드 비활성화
- 필요한 기본 툴만 활성화
- 세션 저장 최소화
3. 읽기 전용 분석 모드
코드베이스 파악, 로그 요약, 리뷰, 문서화에 쓰는 모드다.
- 쓰기 권한 제한
- 출력 파일 지정
- JSON 출력 사용
- 불필요한 커넥터 비활성화
- 웹 검색은 문서 확인이 필요할 때만 사용
이렇게 나누면 “항상 강한 설정”과 “항상 싼 설정” 사이에서 선택할 필요가 줄어든다. 작업이 단순할수록 컨텍스트를 줄이고, 작업이 복잡할수록 필요한 문맥을 충분히 제공하는 식으로 운영하면 된다.
주의할 점
토큰 절약은 성능 최적화와 비슷하다. 줄일 수 있다고 전부 줄이면 오히려 디버깅 비용이 늘어날 수 있다.
특히 다음은 조심해야 한다.
- 테스트 로그 출력 상한을 너무 낮게 잡는 것
- 프로젝트 문서를 무조건 비활성화하는 것
- IDE 문맥이 필요한 작업에서 IDE 연결을 끄는 것
- 웹 검색이 필요한 작업에서 검색을 막는 것
- MCP가 필요한 워크플로우에서 커넥터를 전부 끄는 것
에이전트가 좋은 답을 하려면 충분한 문맥이 필요하다. 문제는 “문맥이 많다”가 아니라 “필요 없는 문맥이 자동으로 계속 붙는다”에 가깝다.
정리
Claude Code와 Codex의 토큰 효율은 모델 자체보다 주변 설정에서 많이 갈린다. 자동으로 주입되는 Git 지시문, IDE 문맥, MCP 정보, 웹 검색, 긴 툴 출력이 누적되면 실제 작업보다 컨텍스트 관리 비용이 커질 수 있다.
가장 현실적인 접근은 작업별 실행 모드를 나누는 것이다. 일반 개발에는 충분한 문맥을 유지하고, 단순 반복 작업이나 비대화형 워커에는 경량 설정을 적용한다. 출력 상한은 폭발 방지용으로만 쓰고, 너무 낮춰서 핵심 로그를 잃지 않도록 조절하는 편이 안정적이다.
결국 토큰 절약의 목표는 에이전트를 멍청하게 만드는 것이 아니라, 필요한 정보만 보게 만드는 것이다.
참고 링크
