nsxdavid/anthropic-max-router

Anthropic MAX 플랜을 ANY AI 도구 - Anthropic SDK, OpenAI SDK, LangChain 등에서 사용하세요!

이중 엔드포인트 (Dual endpoints): 네이티브 Anthropic API + OpenAI 호환 API (Anthropic으로 자동 변환)

• 🌟 무엇이 특별한가요?
• ⚡ 빠른 시작 (Quick Start)
• 🚀 API 라우터 (API Router)
• 🔧 대화형 CLI (Interactive CLI)
• 📚 구현 가이드 (Implementation Guide)
• 🧪 테스트 (Testing)

이 라우터는 **이중 API 엔드포인트 (dual API endpoints)**를 제공합니다. Anthropic 또는 OpenAI 중 어느 쪽을 위해 구축된 도구에서도 MAX 플랜을 사용할 수 있습니다!

엔드포인트 (Endpoint)	형식 (Format)	사용 가능 도구 (Use With)
/v1/messages	Anthropic 네이티브 (Anthropic native)	Anthropic SDK, Claude 전용 도구
/v1/chat/completions	OpenAI 호환 (OpenAI compatible)	OpenAI SDK, LangChain, LiteLLM, ChatGPT 도구, 모든 GPT-4 호환 도구

하나의 라우터. 두 개의 API. 무제한의 호환성. 🚀

OAuth 흐름을 테스트하고, 인증을 이해하며, API 요청을 실험할 수 있는 메뉴 기반 도구입니다.

npm start

http://localhost:3000을 통해 ANY AI 도구가 귀하의 MAX 플랜 구독을 사용할 수 있도록 하는 Anthropic 및 OpenAI 엔드포인트를 모두 갖춘 독립형 HTTP 프록시입니다.

.

작동 환경: Anthropic SDK, OpenAI SDK, LangChain, LiteLLM, 그리고 커스텀 베이스 URL (custom base URLs)을 지원하는 모든 도구!

npx anthropic-max-router

전체 기술 문서: OAuth PKCE 흐름, 시스템 프롬프트 검증, 토큰 관리 및 API 패턴.

이 저장소는 귀하의 코드와 함께 Anthropic의 Claude MAX 구독 플랜을 사용할 수 있도록 실용적인 도구와 완전한 문서를 모두 제공합니다.

왜 MAX 플랜인가요? 토큰당 과금 방식 대신 정액제 요금이 적용됩니다. 대량의 AI 개발에 완벽합니다.

왜 이 라우터인가요? Anthropic API용으로 구축되었든 OpenAI API용으로 구축되었든, ANY AI 도구에서 귀하의 MAX 플랜을 사용할 수 있습니다. 두 엔드포인트가 모두 포함되어 있습니다!

OpenCode에 특별한 감사를 전합니다 - OpenCode의 OAuth 구현을 연구한 덕분에 이 프로젝트가 가능했습니다.

Claude MAX 구독 claude.ai 제공 - 월 $100 또는 월 $200 플랜
Node.js 18+

가장 빠르게 시작하는 방법 - git clone이나 npm install이 필요 없습니다:

npx anthropic-max-router

그게 전부입니다! 라우터는 다음과 같이 작동합니다:

• OAuth를 통해 자동으로 인증 (최초 실행 시에만 수행)
• Anthropic 및 OpenAI 엔드포인트(endpoint)를 모두 포함하여 http://localhost:3000에서 프록시 서버(proxy server) 시작
• Anthropic 또는 OpenAI 형식을 사용하는 것과 관계없이, **어떤 도구(tool)**에서도 MAX Plan 과금 체계를 사용할 수 있게 해줍니다!

npx anthropic-max-router --help # 모든 옵션 표시
npx anthropic-max-router --port 8080 # 사용자 정의 포트
npx anthropic-max-router --verbose # 전체 요청 로깅 (request logging)
...

옵션 2: GitHub에서 실행 (최신 개발 버전)

# GitHub 저장소에서 직접 실행
npx github:nsxdavid/anthropic-max-router
# 옵션과 함께 실행
...

옵션 3: 클론(Clone) 후 실행 (개발용)

# 저장소 클론
git clone https://github.com/nsxdavid/anthropic-max-router
cd anthropic-max-router
...

OAuth 흐름(flow)을 테스트, 학습 및 디버깅(debugging)하기 위한 메뉴 기반 애플리케이션입니다.

• 🔐 단계별 안내가 포함된 OAuth 인증
• 🔄 수동 토큰 갱신(token refresh) 테스트
• 💬 Claude와의 대화형 채팅 모드
• 🗑️ 토큰 로그아웃/관리
• ✅ MAX Plan 유효성 검증 증명 테스트

npm start

다음과 같은 대화형 메뉴가 나타납니다:

╔════════════════════════════════════════════════════════════╗
║ Anthropic MAX Plan OAuth CLI ║
╚════════════════════════════════════════════════════════════╝
...

• 🧪 OAuth 흐름 테스트
• 📖 인증 작동 방식 학습
• 🐛 API 요청 디버깅
• 🔍 MAX Plan 유효성 검증 이해
• 📝 시스템 프롬프트(system prompt) 실험

src/
├── cli.ts # 대화형 메뉴
├── oauth.ts # OAuth PKCE 흐름
...

모든 AI 도구 또는 애플리케이션이 사용자의 MAX Plan 구독을 사용할 수 있도록 해주는 이중 API 엔드포인트(dual API endpoints) (Anthropic + OpenAI)를 갖춘 독립형 HTTP 프록시 서버입니다.

두 가지 API 형식을 모두 지원합니다:

/v1/messages

• 네이티브 Anthropic Messages API

/v1/chat/completions

• OpenAI Chat Completions API (Anthropic으로 자동 변환)

Anthropic 또는 OpenAI용으로 구축된 도구 모두와 호환됩니다. 도구의 주소를 http://localhost:3000으로 지정하기만 하면 됩니다.

!

┌─────────────────────┐
│ 귀하의 AI 도구 │
│ (모든 애플리케이션) │
...

• ✅
  이중 API 엔드포인트 (Dual API endpoints)
• Anthropic 네이티브 + OpenAI 호환 - ✅
  범용 호환성 (Universal compatibility)
• Anthropic SDK, OpenAI SDK, LangChain, LiteLLM 등을 지원 - ✅
  자동 변환 (Automatic translation)
• OpenAI 요청을 Anthropic 형식으로 원활하게 변환 - ✅
  스마트 모델 매핑 (Smart model mapping)
• gpt-4, gpt-5, o1 등을 Claude 모델로 자동 매핑 - ✅
• 첫 실행 시 자동 OAuth 인증
• ✅ 투명한 시스템 프롬프트 주입 (Anthropic에서 요구됨)
• ✅ 토큰 자동 갱신 (8시간 만료 자동 처리)
• ✅ 설정 가능한 로깅 레벨 (Logging levels)
• ✅
  Bearer 토큰 전달 (Bearer token passthrough)
• 클라이언트가 자신의 API 키를 사용할 수 있음 (기본적으로 활성화됨)

# 라우터 시작 (기본값: 포트 3000, 중간 수준의 상세도)
npm run router
# 옵션 사용 시
...

첫 실행: 라우터가 OAuth를 통해 인증하도록 안내합니다. 안내 지침을 따르세요.

이후 실행: 라우터가 즉시 시작되며 토큰을 자동으로 갱신합니다.

옵션	약어	설명
--help	-h	도움말 메시지 표시
--version	-v	버전 번호 표시
--port PORT	-p	포트 설정 (기본값: 3000)
엔드포인트 제어 (Endpoint Control)
--enable-anthropic	Anthropic /v1/messages 엔드포인트 활성화 (기본값: 활성화)
--disable-anthropic	Anthropic 엔드포인트 비활성화
--enable-openai	OpenAI /v1/chat/completions 엔드포인트 활성화 (기본값: 활성화)
--disable-openai	OpenAI 엔드포인트 비활성화
--enable-all-endpoints	Anthropic 및 OpenAI 엔드포인트 모두 활성화 (기본값과 동일)
인증 (Authentication)
--disable-bearer-passthrough	모든 요청이 라우터의 OAuth를 사용하도록 강제 (기본값: 전달 활성화)
상세도 (Verbosity)
--quiet	-q	요청 로깅 없음
--minimal	-m	요청당 한 줄 출력
(기본값)	요청당 요약 - 중간 수준의 상세도
--verbose	-V	전체 요청/응답 본문 (Full request/response bodies)

환경 변수 (Environment variables):

기본적으로 클라이언트는 라우터의 OAuth 자격 증명 대신 자신의 Anthropic API 키를 사용할 수 있습니다.

요청에 Authorization: Bearer <token>이 포함된 경우

header:

• ✅ 라우터(Router)가 제공된 Bearer 토큰을 사용합니다.
• ✅ 요청 횟수는 클라이언트의 할당량(Quota)에 반영됩니다 (MAX Plan이 아님).
• ✅ 여러 사용자가 각자의 API 키를 사용하여 하나의 라우터를 공유할 수 있습니다.

사용 사례 (Use cases):

• 이미 Anthropic API 키를 보유하고 있는 도구들
• 개별 API 키를 가진 개발 팀
• MAX Plan 사용과 일반 API 사용의 혼합
• 다양한 자격 증명(Credentials)을 통한 테스트

패스스루(Passthrough)를 비활성화하려면 (모든 요청을 OAuth를 통해 강제하려면):

npm run router -- --disable-bearer-passthrough

자세한 문서는 BEARER-TOKEN-PASSTHROUGH.md를 참조하세요.

환경 변수 (Environment variables):

ROUTER_PORT=8080

• 포트 설정
  ANTHROPIC_DEFAULT_MODEL=claude-haiku-4-5

• OpenAI 요청에 대한 모델 매핑(Model mapping) 재정의

최소 (Minimal) (-m) - 요청당 한 줄 출력:

[10:30:45] ✓ 200 claude-sonnet-4-5 (in:28 out:19)
[10:31:12] ✓ 200 claude-sonnet-4-5 (in:300 out:500)

중간 (Medium) (기본값) - 요청 요약:

[2025-11-02T10:30:45.123Z] [abc123] Incoming request
Model: claude-sonnet-4-5
Max tokens: 1000
...

상세 (Verbose) (-V) - 디버깅을 위한 전체 JSON 요청/응답 본문(Body).

정숙 (Quiet) (-q) - 요청 로그를 남기지 않음 (시작 메시지와 에러만 표시).

라우터는 기본적으로 Anthropic과 OpenAI 엔드포인트(Endpoints)를 모두 제공합니다:

네이티브 Anthropic 형식. Anthropic SDK 또는 Anthropic 호환 도구와 함께 사용하세요.

curl -X POST http://localhost:3000/v1/messages \
-H "Content-Type: application/json" \
-d '{"model":"claude-sonnet-4-5","max_tokens":100,"messages":[{"role":"user","content":"Hello"}]}'

Anthropic으로 자동 변환되는 OpenAI 호환 형식. OpenAI SDK, LangChain, LiteLLM 등을 함께 사용하세요.

curl -X POST http://localhost:3000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"gpt-4","messages":[{"role":"user","content":"Hello"}]}'

Anthropic에서 사용 가능한 Claude 모델 목록을 반환합니다.

** ⚠️ 중요:** 이 엔드포인트는 Anthropic API 키(OAuth 아님)를 필요로 합니다. API 키는

이 엔드포인트에서만 사용됩니다 - 다른 모든 엔드포인트는 OAuth 인증을 사용합니다.

curl http://localhost:3000/v1/models \
-H "x-api-key: sk-ant-api03-..."

왜 API 키가 필요한가요? Anthropic의 /v1/models 엔드포인트는 OAuth 인증을 지원하지 않으며 API 키를 필요로 합니다. API 키를 제공하면, 라우터(router)가 Anthropic API로 요청을 프록시(proxy)하여 현재 모델 목록을 가져옵니다.

API 키가 없는 경우:

{
"type": "error",
"error": {
...

curl http://localhost:3000/health
# 반환값: {"status":"ok","service":"anthropic-max-plan-router"}

라우터는 OpenAI Chat Completions API 형식을 지원하여, OpenAI용으로 구축된 도구들과 **코드 수정 없는 통합 (zero-code integration)**을 가능하게 합니다.

빠른 비교:

보유 중인 것	얻게 되는 것	방법
Anthropic용으로 구축된 도구	네이티브 Anthropic 엔드포인트 사용	http://localhost:3000을 가리킴
...

많은 AI 도구와 라이브러리(Python OpenAI SDK, LangChain 등)는 오직 OpenAI의 API 형식에 맞춰 구축되어 있습니다. OpenAI 호환 엔드포인트를 사용하면, 이러한 도구들을 코드 변경 없이 MAX Plan 구독과 함께 사용할 수 있습니다. 단지 http://localhost:3000을 가리키기만 하면 됩니다.

두 엔드포인트 모두 기본적으로 활성화되어 있습니다! 라우터를 시작하기만 하면 됩니다:

npm run router
# 또는
npx anthropic-max-router

필요한 경우 엔드포인트를 비활성화할 수 있습니다:

# OpenAI 엔드포인트 비활성화 (Anthropic 전용)
npm run router -- --disable-openai
# Anthropic 엔드포인트 비활성화 (OpenAI 전용)
...

활성화된 경우, 라우터는 각 요청이 어떤 엔드포인트를 사용하는지 로그를 남깁니다:

[10:30:45] [OpenAI] ✓ 200 claude-sonnet-4-5 (in:28 out:19)
[10:31:12] [Anthropic] ✓ 200 claude-sonnet-4-5 (in:300 out:500)

┌─────────────────────────┐
│ OpenAI 호환 도구        │
│ (Python SDK 등)         │
...

라우터는 패턴 기반 탐지(pattern-based detection)를 사용하여 OpenAI 모델 이름을 Claude 모델로 자동으로 매핑합니다:

OpenAI 모델 패턴	매핑 대상	이유
gpt-3.5-* , gpt-3-* , *-nano	claude-haiku-4-5	저사양/빠른 모델 (Low-tier/fast models)
gpt-4 , gpt-5 , gpt-6 , o1 , o3 , o4 , etc.	claude-sonnet-4-5	기타 모든 모델 (MAX 플랜에 최적)

예시 (Examples):

gpt-4 → claude-sonnet-4-5
gpt-4o → claude-sonnet-4-5
gpt-5.1 → claude-sonnet-4-5
...

사용자 정의 매핑 (Custom Mappings):

.router-mappings.json을 사용하여 특정 모델을 오버라이드(Override)할 수 있습니다:

{
"gpt-5-experimental": "claude-sonnet-4",
"my-custom-model": "claude-haiku-4-5"
...
}

또는 환경 변수를 사용하여 모든 매핑을 오버라이드할 수 있습니다:

ANTHROPIC_DEFAULT_MODEL=claude-haiku-4-5 npm run router -- --enable-openai

Python (OpenAI SDK):

from openai import OpenAI
client = OpenAI(
api_key="not-used", # 무엇이든 상관없음 - 라우터가 인증을 처리함
...

JavaScript/TypeScript (OpenAI SDK):

import OpenAI from 'openai';
const client = new OpenAI({
apiKey: 'not-used', // 무엇이든 상관없음 - 라우터가 인증을 처리함
...

cURL:

curl -X POST http://localhost:3000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
...

스트리밍(Streaming)은 OpenAI 호환 요청과 함께 작동합니다:

from openai import OpenAI
client = OpenAI(
api_key="not-used",
...

라우터는 Anthropic의 서버 전송 이벤트(Server-Sent Events, SSE)를 OpenAI의 스트리밍 형식으로 자동 변환합니다.

지원 항목 (Supported):

• ✅ 메시지 형식 변환 (system/user/assistant 역할)
• ✅ 모델 이름 매핑 (gpt-4 → claude-sonnet-4-5)
• ✅ 스트리밍 응답 (SSE 형식 변환)
• ✅ 도구/함수 호출 (Tool/function calling, 형식 변환)
• ✅ 토큰 사용량 보고 (input_tokens → prompt_tokens)
• ✅ Temperature, max_tokens, stop sequences

미지원 항목 (Anthropic 제한 사항) (Not Supported):

• ❌ 다중 완성 (Multiple completions, n > 1) - 에러 반환
• ❌ 로그 확률 (Log probabilities, logprobs) - 에러 반환
• ❌ presence_penalty / frequency_penalty - 경고와 함께 무시됨

"Error: Multiple completions (n > 1) are not supported"
→ Anthropic은 단 하나의 완성(completion)만 반환합니다. n=1로 설정하세요.

또는 해당 파라미터를 생략하세요.

"Model 'gpt-xyz' mapped to 'claude-sonnet-4-5'"
→ 이는 예상된 동작입니다. 모델 매핑(mapping)을 확인하려면 medium/verbose 로그를 확인하세요.

도구 호출 (Tool calling) 동작 방식의 차이
→ Anthropic의 도구 호출 (tool calling)은 OpenAI보다 더 엄격합니다. 일부 병렬 도구 호출 (parallel tool calls)은 예상대로 작동하지 않을 수 있습니다.

번역을 확인하고 싶으신가요?
→ npm run router -- --enable-openai --verbose를 사용하여 전체 요청/응답 (request/response) 번역을 확인하세요.

테스트 요청을 보내세요:

PowerShell:

curl -X POST http://localhost:3000/v1/messages `
-H "Content-Type: application/json" `
-d '{"model":"claude-sonnet-4-5","max_tokens":50,"messages":[{"role":"user","content":"Say hello in one short sentence."}]}'

Bash/Linux/Mac:

curl -X POST http://localhost:3000/v1/messages \
-H "Content-Type: application/json" \
-d '{
...