LunaRoute: Claude Code 및 Codex CLI 등과 같은 AI 코딩 어시스턴트를 위한 초고속 로컬 프록시

읽을거리&정보공유
1

LunaRoute: Claude Code 및 Codex CLI 등과 같은 AI 코딩 어시스턴트를 위한 초고속 로컬 프록시
LunaRoute: Claude Code 및 Codex CLI 등과 같은 AI 코딩 어시스턴트를 위한 초고속 로컬 프록시1752×970 46.4 KB

LunaRoute 소개

LunaRoute는 Claude Code, OpenAI Codex CLI, OpenCode 등과 같은 AI 코딩 어시스턴트를 위한 고성능 로컬 프록시(Local Proxy) 입니다. 이 도구는 개발자가 사용하는 AI 어시스턴트의 모든 요청과 응답을 가시화하여, AI가 내부적으로 어떤 동작을 수행하고 있는지를 완벽하게 추적할 수 있게 해줍니다. LunaRoute는 Rust 언어로 개발되어 초저지연(0.1~0.2ms) 성능을 제공하며, 세션 기록, 개인 정보 보호(PII) 자동 마스킹, 그리고 실시간 디버깅까지 지원합니다.

많은 개발자들이 Claude Code나 Codex CLI 같은 AI 도구를 사용할 때, 요청과 응답의 실제 내용을 확인하기 어렵다는 불편을 겪습니다. LunaRoute는 이러한 “블랙박스” 문제를 해결합니다. 즉, LunaRoute를 통해 모든 LLM 요청, 토큰 사용량, API 호출 성능, 세션 로그를 자동으로 수집하여 분석할 수 있으며, 이를 통해 비용 최적화, 성능 문제 파악, 보안 감사까지 가능합니다.

특히, LunaRoute는 별도의 API 키 설정 없이도 작동합니다. 단순히 lunaroute-server 명령어 하나만 실행하면 자동으로 클라이언트 인증을 처리하여 바로 사용할 수 있습니다.

Claude Code, OpenAI Codex CLI와의 비교

기존의 Claude Code나 OpenAI Codex CLI는 강력한 AI 기반 코딩 기능을 제공하지만, 프록시 수준에서의 투명한 가시성은 제공하지 않습니다. 예를 들어, Claude Code는 API 요청 및 응답을 내부적으로 처리하므로 토큰 사용량이나 세부 요청 내용을 파악하기 어렵습니다. 반면 LunaRoute는 이러한 모든 데이터를 “프록시 레벨”에서 실시간 기록합니다.

또한, LunaRoute는 OpenAI와 Anthropic 두 가지 API 포맷(OpenAI Chat Completions / Anthropic Messages)을 동시에 지원하여, 하나의 프록시에서 두 개의 서로 다른 AI 시스템을 병렬로 관리할 수 있습니다. 이는 팀 단위 개발 환경에서 특히 유용하며, 예를 들어 한 개발자가 Claude Code를, 다른 개발자가 Codex CLI를 사용하더라도 하나의 LunaRoute 서버로 모든 로그를 통합 관리할 수 있습니다.

LunaRoute 주요 기능

  • 완전한 LLM 세션 가시성: LunaRoute는 모든 요청, 응답, 스트리밍 이벤트, 토큰 사용량, 도구(tool) 호출 내역 등을 기록합니다. 이를 통해 다음과 같은 기능을 제공합니다:

    • AI가 보낸 요청 및 받은 응답을 완전히 복원 가능
    • 입력/출력/추론(Thinking) 토큰별 사용량 추적
    • 각 도구의 호출 빈도 및 평균 처리 시간 분석
    • 프록시 오버헤드 측정(LLM 자체 문제인지, 클라이언트 문제인지 분석 가능)
    • 과거 세션 검색: 특정 키워드(예: “TypeError”)로 대화 내역을 조회 가능
      이러한 기능은 AI 어시스턴트의 동작을 “투명하게” 들여다볼 수 있게 해주며, 버그 원인 추적 및 비용 관리에 큰 도움을 줍니다.

  • 개인정보 보호 및 규정 준수(PII Redaction): 개인정보 보호 기능은 LunaRoute의 핵심 중 하나입니다. AI 요청 로그에 이메일, 전화번호, 신용카드 번호 등이 포함되는 경우가 있는데, LunaRoute는 이를 자동으로 탐지하고 다음과 같은 방식으로 처리할 수 있습니다:

    • Masking: [EMAIL], [PHONE] 등으로 대체
    • Remove: 해당 데이터 삭제
    • Tokenize: HMAC 기반 토큰으로 가역적 치환
    • Partial: 일부만 표시 (예: “010-****-1234”)
      이 기능은 로그가 디스크에 기록되기 전에 적용되어, 데이터가 노출될 위험을 원천적으로 차단하여, 금융이나 의료, 공공기관 등과 같은 데이터 규제 환경에서도 사용할 수 있습니다.

  • 초고속, 무설정 프록시: LunaRoute는 별도의 설정 없이 다음 명령어로 바로 실행할 수 있습니다:

    lunaroute-server

    이렇게 LunaRoute를 실행한 뒤에는 다음과 같이 연결할 수 있습니다:

    # Claude Code 사용 시, 환경 변수 설정
export ANTHROPIC_BASE_URL=http://localhost:8081

# Codex CLI 사용 시, 환경 변수 설정
export OPENAI_BASE_URL=http://localhost:8081/v1

    설정 후 Claude Code 또는 Codex CLI 등을 새롭게 시작하면, 이후 모든 요청은 자동으로 로컬호스트에 실행된 LunaRoute를 거치게 되며, 인증 정보는 클라이언트 측에서 자동으로 전달됩니다. 성능 면에서도 Rust 기반의 비동기 처리 덕분에 0.1~0.2ms의 추가 지연만 발생하며, 이는 사실상 실시간 처리 수준입니다.

  • 세션 기록과 분석: LunaRoute는 SQLite와 JSONL의 두 가지 방식으로 세션을 기록할 수 있습니다:

    • SQLite에 저장하는 분석 로그: 간단한 통계 및 메타데이터를 저장합니다. 토큰 수, 모델 이름, 실행 시간 등의 데이터를 기록하여 비용과 성능 분석에 활용할 수 있습니다.
    • JSONL로 저장하는 전체 로그: 요청/응답 본문을 모두 저장하여, 디버깅 및 재생(replay)에 활용할 수 있습니다.

    위 SQLite와 JSONL의 두 방식은 함께 사용할 수 있습니다. 또한, 전체 로그를 저장하는 JSONL의 경우 저장되는 로그의 양이 커질 수 있으므로, 일정 기간 후 자동 삭제되도록 설정할 수 있습니다.

  • 실시간 웹 UI: LunaRoute는 내장된 웹 UI를 제공합니다. lunaroute-server 명령어로 LunaRoute 서버를 실행한 뒤, 웹 브라우저로 http://localhost:8082에 접속하면 곧바로 Web UI에 접근이 가능합니다. Web UI에서는 세션 목록 및 검색을 비롯하여, 요청/응답 상세 보기, 토큰 사용량 및 성능 분석 등을 제공합니다. 또한, Prometheus 기반의 메트릭 표시를 포함한 실시간 대시보드 또한 확인할 수 있습니다.

LunaRoute 아키텍처

LunaRoute는 아래와 같은 Rust 기반의 모듈형 구조로 설계되었습니다:

┌─────────────────────────────────────────────────────────────┐
│          Claude Code / OpenAI Codex CLI / OpenCode         │
└─────────────────────────┬───────────────────────────────────┘
                          │ HTTP/SSE
                          ↓
┌─────────────────────────────────────────────────────────────┐
│                      LunaRoute Proxy                        │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Ingress (Anthropic/OpenAI endpoints)                │  │
│  └─────────────────────┬────────────────────────────────┘  │
│                        │                                    │
│  ┌─────────────────────▼────────────────────────────────┐  │
│  │  Passthrough Mode (Zero-copy) OR Normalization       │  │
│  └─────────────────────┬────────────────────────────────┘  │
│                        │                                    │
│  ┌─────────────────────▼────────────────────────────────┐  │
│  │  Session Recording (JSONL + SQLite, PII redaction)   │  │
│  └─────────────────────┬────────────────────────────────┘  │
│                        │                                    │
│  ┌─────────────────────▼────────────────────────────────┐  │
│  │  Metrics & Statistics (Prometheus, session stats)    │  │
│  └─────────────────────┬────────────────────────────────┘  │
│                        │                                    │
│  ┌─────────────────────▼────────────────────────────────┐  │
│  │  Egress (Provider connectors)                         │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────┬───────────────────────────────────┘
                          │ HTTP/SSE
                          ↓
              ┌───────────────────────┐
              │  Anthropic API        │
              │  (api.anthropic.com)  │
              └───────────────────────┘

몇 가지 핵심 모듈을 살펴보면 다음과 같은 역할을 수행합니다:

  • lunaroute-core: 공통 타입 및 트레이트 정의
  • lunaroute-ingress: OpenAI / Anthropic API 엔드포인트
  • lunaroute-egress: 실제 AI API 요청 처리
  • lunaroute-session: 세션 기록 및 검색
  • lunaroute-pii: PII 탐지 및 치환 로직
  • lunaroute-observability: Prometheus 메트릭 및 상태 모니터링

각 모듈은 독립적으로 관리되며, 고성능 HTTP 연결 풀을 통해 요청을 효율적으로 처리합니다.

라이선스

LunaRoute 프로젝트는 Apache License 2.0으로 공개되어 있습니다. 상업적 사용이 가능하며, 소스 코드 수정 및 배포가 허용됩니다.

:github: LunaRoute 프로젝트 GitHub 저장소



이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. :hugs:

:pytorch:파이토치 한국 사용자 모임:south_korea:이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일:love_letter:로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

:wrapped_gift: 아래:down_right_arrow:쪽에 좋아요:+1:를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ :star_struck: