블로그로 돌아가기

비용 최적화가이드

Claude Code 토큰 사용량: 도구 출력을 컨텍스트 밖으로 유지하기

PreToolUse 훅과 context-mode 플러그인이 테스트 로그를 Claude Code의 컨텍스트 밖으로 유지하는 방법, 그리고 필터링 유무에 따른 세션 비용 추정.

작성자: CheapTokens Team 게시됨읽는 시간 6분

테스트 명령이 grep과 head를 통해 파이프되어 실패만 Claude Code에 도달하는 터미널 화면
이 페이지의 내용
  1. 왜 하나의 로그에 여러 번 비용을 지불하는가
  2. 해결책 1: 테스트 출력을 필터링하는 PreToolUse 훅
  3. 해결책 2: 큰 도구 결과를 위한 context-mode
  4. 필터링 유무에 따른 긴 세션 비용
  5. CheapTokens 모델에서 Claude Code 실행하기
  6. 빠른 체크리스트

에이전트가 테스트 스위트를 세 번 실행했는데, 청구서가 작업보다 큽니다. 그 이유는 에이전트가 작성한 코드가 아닌 경우가 대부분입니다. 바로 테스트 로그 때문이죠. 도구 결과가 Claude Code의 컨텍스트에 한 번 들어가면, 이후의 모든 요청이 그 결과를 다시 함께 전송합니다. 해결책은 모델이 보기 전에 도구 출력을 줄이는 것입니다. 공식적인 방법은 Bash에 PreToolUse 훅을 거는 것이고, 서드파티 방법은 context-mode 플러그인입니다. 두 방법 모두 아래에 있으며, CheapTokens 모델에서 긴 세션을 실행했을 때의 비용 추정치도 포함되어 있습니다.

왜 하나의 로그에 여러 번 비용을 지불하는가#

Claude Code 비용 페이지(https://code.claude.com/docs/en/costs, 2026년 10월 23일 확인)에 따르면, Claude Code는 매 요청마다 전체 대화를 전송하며, 각 도구 사용은 도구 결과를 포함하는 또 다른 요청을 트리거합니다. 프롬프트 캐싱은 기록을 더 저렴한 캐시 요금으로 다시 읽지만, 토큰은 여전히 존재합니다.

에이전트가 npm test를 실행해서 10,000줄짜리 로그를 받았다고 가정해 봅시다. 문서에 따르면 이런 로그는 수만 개의 토큰이 될 수 있습니다. 30,000 토큰이라고 가정하죠. 다음에 무엇을 하든, 그 30,000 토큰은 11단계, 12단계, 13단계, 그리고 /clear하거나 압축할 때까지 계속해서 입력의 일부가 됩니다. 그리고 여기에 함정이 있습니다. 로그는 한 단계에만 유용한데, 서른 단계 동안 비용을 지불하게 됩니다.

해결책 1: 테스트 출력을 필터링하는 PreToolUse 훅#

같은 문서 페이지에서는 훅을 전처리로 사용할 것을 제안합니다. Bash에 PreToolUse 훅을 걸면 테스트 명령(npm test, pytest, go test)을 다시 작성해서 grep -A 5 -E '(FAIL|ERROR|error:)' | head -100을 통해 파이프되도록 합니다. 그러면 에이전트는 10,000줄의 초록 점 대신 실패와 몇 줄의 컨텍스트만 보게 됩니다. 문서에 따르면 이렇게 하면 수만 개의 토큰을 수백 개로 줄일 수 있습니다.

훅 적용 전후 에이전트가 보는 내용
원시 npm test 출력 대 실패만 표시

이것은 해당 문서 페이지(2026년 10월 23일 확인)의 스크립트입니다. jq이 필요합니다. mkdir -p ~/.claude/hooks로 폴더를 만들고, 스크립트를 ~/.claude/hooks/filter-test-output.sh로 저장한 다음 chmod +x을 실행하세요:

bash
#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')

pattern='^(npm test|pytest|go test)( [^;&|<>`$#\\[:cntrl:]]*)?$'

if [[ "$cmd" =~ $pattern ]]; then
  filtered_cmd="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100"
  echo "$input" | jq --arg filtered "$filtered_cmd" '{hookSpecificOutput: {hookEventName: "PreToolUse", updatedInput: (.tool_input + {command: $filtered})}}'
else
  echo "{}"
fi

그런 다음 ~/.claude/settings.json에 등록합니다:

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/filter-test-output.sh" }]
      }
    ]
  }
}

작동하는지 확인하려면 Claude Code 내에서 /hooks을 열고 PreToolUse 항목을 찾거나, claude --debug-file ./claude-debug.txt로 시작해서 에이전트에게 npm test을 실행하도록 요청하세요. 훅이 명령을 다시 작성했다면, 파일에 command 필드가 있는 modified tool input keys 줄이 있습니다. 테스트가 통과하면 출력이 비어 있으므로 에이전트는 조용한 성공을 받습니다. 러너가 실패를 다르게 출력한다면 패턴을 조정하세요.

해결책 2: 큰 도구 결과를 위한 context-mode#

훅은 파이프할 수 있는 명령만 처리합니다. Playwright의 페이지 스냅샷이나 20개의 GitHub 이슈 목록은 MCP 도구에서 나옵니다. context-mode가 겨냥하는 것이 바로 이것입니다. README(https://github.com/mksglu/context-mode, 2026년 10월 23일 확인; 버전이나 날짜는 표시되지 않음)에 따르면, 원시 도구 출력을 컨텍스트 윈도우 밖에 유지하고, 세션 상태를 SQLite에 저장하며, 훅을 통해 도구 호출을 라우팅하는 MCP 서버이자 플러그인입니다. Claude Code v1.0.33 이상이 필요하며, 라이선스는 Elastic License 2.0으로 OSI 오픈 소스 라이선스가 아닙니다.

Claude Code 내에서 설치:

text
/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

재시작하거나 /reload-plugins를 실행한 다음, /context-mode:ctx-doctor으로 확인하세요. MCP 전용 변형인 claude mcp add context-mode -- npx -y context-mode은 도구를 추가하지만 자동 라우팅은 없습니다.

이 프로젝트는 큰 감소를 보고합니다: 315 KB가 5.4 KB로(98%), 56 KB 페이지 스냅샷이 299 바이트로, 986 KB가 62 KB로. 이는 작성자 자신의 수치이므로 상한으로 간주하고, /context을 사용해 자신의 세션에서 전후를 측정하세요.

필터링 유무에 따른 긴 세션 비용#

가정한 한 세션에 대한 계산입니다. 20,000 토큰의 평균 기본 컨텍스트, 단계당 500 출력 토큰, 10, 20, 30단계에서 세 번의 테스트 실행이 있는 40단계 코딩 세션입니다. 각 원시 로그는 30,000 토큰이고, 필터링된 버전은 500입니다.

  • 10단계의 로그는 이후 30개 요청에서 다시 전송됩니다: 30 × 30,000 = 900,000 토큰. 20단계: 20 × 30,000 = 600,000. 30단계: 10 × 30,000 = 300,000. 추가 입력: 900,000 + 600,000 + 300,000 = 1,800,000.
  • 필터링: (30 + 20 + 10) × 500 = 30,000 추가 입력.
  • 기본 입력: 40 × 20,000 = 800,000. 출력: 40 × 500 = 20,000.
  • 따라서 세션은 필터링 없이 800,000 + 1,800,000 = 2,600,000 입력 토큰이고, 필터링하면 800,000 + 30,000 = 830,000이며, 출력 토큰은 어느 경우든 20,000입니다.

계산은 모든 입력 토큰을 전체 요금으로 계산합니다. 캐싱은 실제 숫자를 낮추지만, 동일한 논리로 두 경우 모두 낮춥니다. 이런 입력이 많은 에이전트 루프에 적합한 모델인 MiniMax-M2.7(MiniMaxAI/MiniMax-M2.7, 180K 컨텍스트, 최대 8,192 출력 토큰)의 실시간 가격은 아래 차트에 있습니다.

MiniMax-M2.7에서의 세션 비용, 40단계
  • 필터 없음$0.133
  • 훅 사용$0.0445

가정: 40단계, 20,000 토큰 기본 컨텍스트, 단계당 500 출력 토큰, 30,000 토큰의 테스트 실행 세 번(필터링: 500).

MiniMax-M2.7에서 세션 비용은 필터링 없이 $0.133, 필터링하면 $0.0445이며, 입력과 출력을 합산하면 OpenRouter의 참조 가격보다 저렴합니다. 필터링 없는 경우 입력의 약 3분의 2가 에이전트가 한 번 읽은 로그입니다.

핵심은 정확한 달러가 아닙니다. 필터가 모든 모델에서 2,600,000 입력 토큰 중 약 1,770,000개(2,600,000 − 830,000 = 1,770,000)를 제거하고, 더 저렴한 모델이 남은 모든 토큰의 가격을 낮춘다는 점입니다.

CheapTokens 모델에서 Claude Code 실행하기#

Claude Code는 Anthropic Messages 프로토콜을 사용하며, CheapTokens가 이를 지원합니다. Claude Code의 기본 URL에는 /v1이 없습니다. 전체 설정은 Claude Code를 CheapTokens에 연결하는 방법에 있습니다. 자리 표시자 키를 사용한 간단한 버전:

bash
export ANTHROPIC_BASE_URL=https://api.cheaptokens.dev
export ANTHROPIC_AUTH_TOKEN=YOUR_CHEAPTOKENS_KEY
export ANTHROPIC_MODEL=MiniMaxAI/MiniMax-M2.7
claude

문서의 전체 ID를 사용하세요. 가격표의 짧은 이름은 API에서 허용되지 않습니다. 모든 모델의 가격은 가격 페이지에 있습니다. Claude Code 청구서를 줄이는 다른 습관(/clear, /compact, /mcp, 서브에이전트)은 Claude Code를 더 저렴하게 만드는 방법을 참조하세요. 실제 요청에서 입력과 출력이 어떻게 계산되는지 보려면 API 요청은 몇 개의 토큰을 사용하는가를 읽어보세요.

빠른 체크리스트#

  1. 긴 세션에서 /context를 실행하고 무엇이 공간을 차지하는지 확인하세요.
  2. 테스트 명령에 Bash 훅을 추가하세요. /hooks 또는 디버그 로그에서 재작성을 확인하세요.
  3. MCP 도구가 큰 스냅샷을 반환하면 context-mode를 시도하고 전후 /context을 비교하세요.
  4. 관련 없는 작업 사이에 /clear을 실행해서 오래된 로그가 따라다니지 않게 하세요.
태그: