AIProxyServer - 指南

시작하기

1. 앱 실행

AIProxyServer를 엽니다. 최초 실행 시 proxy가 자동으로 시작되어 로컬 머신의 포트 8421에서 대기합니다. 메인 윈도우에는 세 가지 섹션이 있습니다.

• Proxy Server — 현재 상태, 베이스 URL, 리스너를 시작/중지하는 버튼
• Bearer Token — 인증 켜기/끄기 전환과 토큰 표시
• Providers — 지원되는 모든 클라우드 AI 프로바이더. 각 행에 Set API Key 버튼

2. 첫 API 키 추가하기

1. Providers 목록에서 원하는 프로바이더를 선택합니다(예: OpenAI (ChatGPT))
2. Get API key를 클릭하여 브라우저에서 프로바이더의 콘솔을 열고 키를 생성하거나 복사합니다
3. 같은 행의 Set API Key를 클릭한 뒤 대화상자에 값을 붙여 넣습니다
4. Save를 클릭합니다. 상태 라벨이 녹색의 Configured로 바뀝니다

3. 클라이언트 앱 연결

아무 OpenAI 호환 클라이언트나 proxy를 가리키도록 설정합니다. 베이스 URL은 http://localhost:8421/<provider>/v1입니다. provider 부분이 어느 클라우드로 요청을 보낼지 결정합니다.

# 예: proxy를 가리키도록 설정한 OpenAI Python SDK
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8421/openai/v1",
    api_key="not-used-but-required-by-sdk",
)
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

클라이언트는 실제 키를 절대 볼 수 없습니다. AIProxyServer가 요청을 전달할 때 상위 자격 증명을 첨부합니다.

인터페이스 개요

Proxy Server 패널

Bearer Token 패널

• Require Bearer Token authentication — 인증 켜기/끄기를 전환하는 체크박스. 번거로움 없는 로컬 사용을 위해 기본값은 꺼짐.
• Token field — 현재 토큰을 읽기 전용으로 표시. 점으로 표시되므로 Copy로 가져옵니다.
• Regenerate — 새로운 랜덤 토큰을 발급합니다. 기존 클라이언트는 새 값으로 업데이트해야 합니다.

Providers 패널

지원되는 각 클라우드 프로바이더마다 한 행씩 표시됩니다. 각 행에는 다음이 나타납니다.

• 표시 이름(예: Claude (Anthropic))
• 설정 상태 — API 키가 저장되어 있으면 녹색의 Configured, 그렇지 않으면 회색의 Not configured
• 클라이언트가 사용하는 URL 경로(예: /anthropic/v1/chat/completions)
• Set API Key — 자격 증명 입력 대화상자를 엽니다
• Get API key — 브라우저에서 프로바이더의 콘솔을 엽니다

지원 프로바이더

11개의 클라우드 AI 서비스가 번들로 제공됩니다. 대부분은 OpenAI Chat Completions 형식을 네이티브로 사용하여 그대로 중계됩니다. 3개(Anthropic, Gemini, ERNIE)는 자체 프로토콜을 사용하지만, AIProxyServer가 요청과 응답을 즉시 변환하므로 클라이언트는 항상 OpenAI 형식만 보게 됩니다.

프로바이더별 참고 사항

• Azure OpenAI — Endpoint Base URL 필드에 전체 배포 엔드포인트를 붙여 넣습니다. 예: https://my-resource.openai.azure.com/openai/deployments/gpt-4o. proxy가 /chat/completions?api-version=2024-02-01을 자동으로 덧붙입니다.
• ERNIE — Baidu Qianfan은 OAuth를 사용하므로 API Key와 Secret Key가 모두 필요합니다. AIProxyServer가 액세스 토큰의 요청 및 캐시를 백그라운드에서 처리합니다.
• Gemini — 인증은 URL 쿼리 매개변수로 이루어지며 proxy가 자동으로 추가합니다. 무료 등급의 분당 쿼터는 그대로 적용됩니다.

API 레퍼런스

엔드포인트

스트리밍

클라이언트가 "stream": true를 보내면 proxy는 OpenAI 형식의 Server-Sent Events로 응답합니다.

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"},...}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},...}]}

data: [DONE]

Anthropic과 Gemini의 네이티브 스트림도 이 형식으로 변환되므로 모든 클라이언트가 단일 파서로 처리할 수 있습니다.

인증 헤더

Require Bearer Token authentication이 켜져 있는 경우 모든 요청에 메인 윈도우의 토큰을 첨부하여 보냅니다.

Authorization: Bearer <token-shown-in-app>

설정

하단 툴바의 기어 아이콘에서 Settings 윈도우를 엽니다.

클라이언트 예제

cURL

# OpenAI(패스스루)
curl http://localhost:8421/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# 동일한 OpenAI 형식으로 Claude 호출
curl http://localhost:8421/anthropic/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 1024
  }'

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8421/gemini/v1",
    api_key="placeholder",  # Bearer Token이 꺼져 있으면 무시됨
)
stream = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[{"role": "user", "content": "Tell me a joke"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Flutter / Dart

// 임의의 OpenAI 호환 Dart 클라이언트를 사용
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // Bearer Token이 꺼져 있으면 사용되지 않음
);

팁

• 로컬에서 개발하는 동안에는 Bearer Token을 꺼 두고, LAN 액세스를 활성화하는 순간 켜십시오.
• 클라이언트 코드에서 프로바이더마다 서로 다른 Base URL을 사용하면 상수 하나만 바꿔서 프로바이더를 전환할 수 있습니다.
• proxy는 자동 시작되지만 포트 충돌이 발생하면 메인 윈도우에서 일시적으로 중지할 수 있습니다.
• 프로바이더의 무료 등급에서 속도 제한에 걸리면 상위 오류 메시지가 그대로 전달됩니다. 클라이언트로부터 숨겨진 재시도 로직은 없습니다.
• /v1/providers 엔드포인트는 런타임에 어떤 프로바이더가 구성되어 있는지 알아내는 데 유용합니다.

문제 해결

proxy가 시작되지 않음

• 다른 프로세스가 이미 포트 8421을 사용 중일 수 있습니다. Settings에서 포트를 변경하고 proxy를 재시작하십시오.
• 시작 시 표시된 오류 메시지를 시스템 로그에서 확인하십시오.

요청이 401 Unauthorized를 반환함

• Bearer Token 요구가 켜져 있지만 클라이언트가 일치하는 Authorization: Bearer ... 헤더를 보내지 않았습니다.
• 프로바이더 자체 API 키가 유효하지 않을 수 있습니다 — 상위 오류가 그대로 전달되므로 메시지 본문을 확인하십시오.

요청이 "API key is not configured"를 반환함

• Providers 목록을 열고 해당 프로바이더의 Set API Key를 클릭하십시오.
• ERNIE는 API Key와 Secret Key를 모두 입력해야 하며, Azure OpenAI는 Endpoint Base URL도 필요합니다.

모바일 디바이스에서 proxy에 도달할 수 없음

• Settings에서 Allow LAN Access를 켜십시오.
• localhost 대신 Base URL 필드에 표시된 LAN IP를 사용하십시오.
• 두 디바이스가 동일한 Wi-Fi에 있고 방화벽이 proxy 포트로의 인바운드 연결을 허용하는지 확인하십시오.

스트리밍 응답이 한 번에 도착함

• 클라이언트가 JSON 본문에 "stream": true를 보내고 있는지 확인하십시오.
• 일부 HTTP 라이브러리는 기본적으로 SSE를 버퍼링합니다 — 클라이언트 측에서 응답 버퍼링을 비활성화하십시오.

개인정보 보호

• API 키는 ~/Library/Application Support/AIProxyServer/credentials.enc에 Fernet으로 암호화되어 저장됩니다. master.key의 암호화 키는 0600 권한입니다.
• Bearer Token도 활성화된 경우 암호화된 저장소에만 보관되며, 일반 설정 파일에는 기록되지 않습니다.
• proxy는 명시적으로 구성한 프로바이더에만 요청을 전달합니다. 다른 발신 호출은 없습니다.
• 텔레메트리, 분석, 충돌 보고가 없습니다.
• 기본 네트워크 바인딩은 127.0.0.1뿐입니다. LAN 노출은 옵트인입니다.
• 대화 내용은 저장되지 않습니다. AIProxyServer는 바이트를 전달한 즉시 잊습니다.