AI 코딩 에이전트의 토큰 비용을 줄이는 로컬 LLM 라우터

AI 코딩 에이전트를 오래 쓰면 금방 마주치는 문제가 있습니다. 모델이 똑똑한지는 둘째 치고, 컨텍스트가 너무 비쌉니다.

대용량 로그를 붙여 넣거나, 오래된 레거시 파일을 통째로 읽히거나, 프로젝트 루트의 긴 AGENTS.md, CLAUDE.md, .cursorrules 같은 지침 파일이 매번 포함되기 시작하면 입력 토큰은 순식간에 늘어납니다. 그런데 실제 답변에 필요한 내용은 그중 아주 일부일 때가 많습니다.

token-router ↗는 이 문제를 “로컬에서는 찾고, 클라우드에서는 추론한다”는 구조로 풀려는 작은 도구입니다. 로컬 LLM이 관련 라인 범위만 찾고, 스크립트가 원문을 그대로 잘라낸 뒤, 클라우드 모델은 핵심 evidence만 보고 추론합니다.

이 글은 작성 시점 2026-06-17 · token-router GitHub README ↗, GeekNews 소개 글 ↗ 스냅숏 기준으로 정리했습니다.

왜 컨텍스트 라우터가 필요한가

큰 컨텍스트 창은 편하지만 공짜가 아닙니다. 대형 로그, 단일 거대 파일, 반복 삽입되는 에이전트 지침은 토큰 비용과 대기 시간을 동시에 키웁니다.

더 큰 문제는 노이즈입니다. 모델이 읽어야 할 정보가 많아질수록 중요한 에러 한 줄이나 변수 정의 하나가 묻힐 수 있습니다. 그래서 요즘 AI 코딩 도구에서는 프롬프트를 잘 쓰는 일만큼이나 컨텍스트를 어떻게 선별하느냐가 중요해지고 있습니다.

이 흐름은 예전에 정리한 Claude Code Memory, Claude Code Agent Teams, OpenAI Codex Sites 같은 글과도 이어집니다. 에이전트가 오래 일하려면 모델 성능뿐 아니라 기억, 역할 분리, 결과물 전달 방식, 컨텍스트 밀도가 함께 설계되어야 합니다.

token-router의 작동 방식

token-router README는 구조를 세 단계로 나눕니다. 로컬 모델은 search와 triage를 맡고, router script는 원문 추출을 맡고, 클라우드 LLM은 reasoning을 맡습니다.

flowchart TD
    A[큰 로그 / 레거시 코드 / 긴 에이전트 문서] --> B[Local Ollama model<br/>관련 라인 좌표 탐색]
    B --> C[Router script<br/>원본 파일에서 raw slice 추출]
    C --> D[Cloud reasoning model<br/>디버깅·수정·리뷰]
    D --> E[답변 또는 패치]

    B -.요약하지 않음.-> C
    C -.원문 그대로 전달.-> D

이 분리는 꽤 중요합니다. 작은 로컬 모델에게 전체 코드를 요약시키면 한 줄의 stack frame, config key, indentation, error suffix가 사라질 수 있습니다. token-router는 이 위험을 피하기 위해 로컬 모델을 분석가가 아니라 라우터로만 씁니다.

로컬 모델의 출력은 “이 범위를 보라”는 좌표입니다. 실제로 클라우드 모델에 전달되는 내용은 파이썬 스크립트가 파일에서 직접 잘라낸 raw text입니다.

세 가지 모드

README 기준 token-router는 세 가지 routing mode를 제공합니다.

특히 agent_context 모드가 흥미롭습니다. Claude Code, Codex, Cursor 같은 도구를 쓰다 보면 루트 지침 파일이 점점 길어집니다. 처음에는 몇 줄짜리 규칙이지만, 시간이 지나면 아키텍처, 테스트 정책, 배포 주의사항, 보안 규칙이 계속 붙습니다.

token-router는 이때 루트 파일을 짧게 유지하고, 긴 작업별 규칙은 별도 reference 문서로 분리한 뒤 필요한 부분만 라우팅하는 패턴을 권합니다. 이미 플랫폼이 긴 루트 파일을 자동 주입한 뒤라면 비용을 사후에 줄일 수 없기 때문에, 구조를 미리 나눠야 합니다.

설치와 실행 감각

README의 quick start는 Python 3.10+, Ollama, 로컬 routing model을 전제로 합니다. 기본 모델 예시는 gemma4:e2b-it-q4_K_M입니다.

ollama pull gemma4:e2b-it-q4_K_M

큰 로그를 조사할 때는 다음처럼 실행합니다.

OLLAMA_NUM_CTX=4096 OLLAMA_KEEP_ALIVE=0s \
python3 scripts/router.py error_log path/to/deploy.log --query "database migration timeout"

긴 소스 파일은 heavy_code 모드를 씁니다.

OLLAMA_NUM_CTX=4096 OLLAMA_KEEP_ALIVE=0s \
python3 scripts/router.py heavy_code path/to/service.py --query "token expiration"

긴 에이전트 reference 문서는 agent_context로 라우팅합니다.

OLLAMA_NUM_CTX=4096 OLLAMA_KEEP_ALIVE=0s \
python3 scripts/router.py agent_context path/to/agent-context/frontend.md --query "frontend testing workflow"

이 명령들은 모델에게 완성 답변을 맡기는 것이 아니라, 클라우드 모델이 읽을 고밀도 원문 조각을 만들기 위한 전처리입니다.

숫자는 어느 정도인가

README의 benchmark highlight는 토큰 수를 chars / 4로 추정했다고 밝힙니다. 따라서 billing-exact 숫자라기보다는 방향성을 보는 지표에 가깝습니다.

이 수치를 그대로 모든 프로젝트에 대입하면 안 됩니다. 파일이 조밀하거나, 질문이 넓은 architecture review라면 필요한 맥락이 훨씬 많을 수 있습니다.

그래도 메시지는 분명합니다. 클라우드 모델에게 모든 파일을 먼저 읽히는 대신, 로컬에서 “읽어야 할 위치”를 찾는 계층을 두면 입력 토큰을 크게 줄일 수 있습니다.

언제 우회해야 하나

token-router는 모든 문제에 맞는 도구가 아닙니다. README도 broad architecture review, 여러 모듈에 걸친 refactor planning, 보안상 complete audit이 필요한 코드, 모든 섹션이 중요한 dense source file은 우회하거나 넓은 컨텍스트를 직접 제공하라고 설명합니다.

이는 올바른 한계 설정입니다. 라우터는 필요한 줄을 잘 찾도록 돕지만, 완전성을 보장하지 않습니다. 선택된 범위가 너무 좁으면 클라우드 모델이 더 넓은 라인 범위를 다시 요청할 수 있어야 합니다.

블로그 대표 이미지 콘셉트

개발자의 노트북 화면을 중심으로, 왼쪽에는 거대한 로그 파일과 레거시 코드 파일이 토큰 더미처럼 쌓여 있고 오른쪽에는 Claude Code, Codex 같은 클라우드 AI 에이전트가 작은 핵심 코드 조각만 받아 분석하는 구조가 잘 어울립니다.

가운데에는 “Local LLM Router”라고 표시된 작은 라우터 노드를 두고, Gemma 계열 로컬 모델이 전체 문서를 요약하지 않고 관련 라인 번호만 찾아내는 흐름을 선으로 표현합니다. 하단에는 “Raw slicing, not summarization”과 “Fewer input tokens”라는 짧은 문구를 넣으면 이 글의 메시지가 선명해집니다.

마무리

AI 코딩 에이전트의 비용을 줄이는 방법은 모델을 더 싸게 쓰는 것만이 아닙니다. 애초에 모델이 읽어야 할 컨텍스트를 더 정확하게 골라주는 것도 중요합니다.

token-router는 이 방향을 잘 보여줍니다. 작은 로컬 모델은 탐색을 맡고, 클라우드 모델은 추론을 맡고, 둘 사이에는 원문을 잃지 않는 slicing layer가 있습니다.

AI 에이전트를 자주 쓰는 개발자라면 지금 워크플로를 한 번 점검해볼 만합니다. 모델에게 문제를 풀게 하고 있는지, 아니면 먼저 불필요한 문서를 뒤지게 만들고 있는지 말입니다.

참고 자료

• sleeplesshan/token-router GitHub README ↗
• GeekNews: token-router 소개 ↗
• Claude Code Memory
• Claude Code Agent Teams