AIProxyServer - 가이드

시작하기

1. 앱 실행하기

AIProxyServer를 엽니다. 처음 실행하면 프록시가 자동으로 시작되어 로컬 컴퓨터의 포트 8421 에서 요청을 대기합니다. 메인 창은 세 개의 섹션으로 구성됩니다:

• 프록시 서버 — 현재 상태, 기본 URL, 리스너를 시작하거나 중지하는 버튼
• Bearer 토큰 — 선택적 인증 토글과 토큰 표시
• 제공업체 — 지원되는 모든 클라우드 AI 제공업체 목록. 각 행에는 API 키 설정 버튼이 있습니다

2. 첫 API 키 추가하기

1. 제공업체 목록에서 원하는 제공업체를 고릅니다(예: OpenAI (ChatGPT))
2. 클릭 API 키 받기 를 클릭하면 브라우저에서 해당 제공업체의 콘솔이 열립니다. 거기서 키를 새로 만들거나 복사하세요
3. 클릭 API 키 설정 같은 행에서 대화상자에 그 값을 붙여넣은 다음
4. 클릭 저장을 누릅니다. 상태 라벨이 초록색 구성됨 으로 바뀝니다

3. 클라이언트 앱 연결하기

OpenAI 호환 클라이언트를 프록시로 지정하세요. 기본 URL은 http://localhost:8421/<provider>/v1입니다. 제공업체 세그먼트에 따라 어느 클라우드로 요청이 전달될지 결정됩니다.

# Example: OpenAI Python SDK pointed at the proxy
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가 요청을 전달할 때 상위 서비스의 인증 정보를 붙여 줍니다.

인터페이스 개요

프록시 서버 패널

Bearer 토큰 패널

• Bearer 토큰 인증 요구 — 인증을 켜고 끄는 체크박스입니다. 로컬에서 번거로움 없이 쓸 수 있도록 기본값은 꺼짐입니다.
• 토큰 필드 — 현재 토큰을 읽기 전용으로 표시합니다. 점으로 가려져 있으므로 복사 를 사용해 값을 가져오세요.
• 재생성 — 새로운 임의 토큰을 발급합니다. 기존 클라이언트는 새 값으로 업데이트해야 합니다.

제공업체 패널

지원되는 클라우드 제공업체마다 한 행씩 표시됩니다. 각 행에는 다음이 나타납니다:

• 표시 이름(예: Claude (Anthropic))
• 구성 상태 — 초록색 구성됨 은 API 키가 저장된 상태, 회색 구성되지 않음 은 그 외의 경우입니다
• 클라이언트가 사용하는 URL 경로. 예: /anthropic/v1/chat/completions
• API 키 설정 — 인증 정보를 입력하는 대화상자를 엽니다
• API 키 받기 — 브라우저에서 해당 제공업체의 콘솔을 엽니다

지원 제공업체

11개의 클라우드 AI 서비스가 기본 포함되어 있습니다. 대부분은 OpenAI Chat Completions 형식을 그대로 지원하므로 요청이 그대로 전달됩니다. 세 곳(Anthropic, Gemini, ERNIE)은 자체 프로토콜을 사용하지만 AIProxyServer가 요청과 응답을 실시간으로 변환하므로, 클라이언트는 항상 OpenAI 형식만 다루면 됩니다.

제공업체별 참고 사항

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

API 레퍼런스

엔드포인트

스트리밍

클라이언트가 "stream": true를 보내면 프록시는 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의 자체 스트림도 이 형식으로 변환되므로 모든 클라이언트가 하나의 파서만 쓰면 됩니다.

인증 헤더

다음 옵션이 Bearer 토큰 인증 요구 켜져 있으면 모든 요청에 메인 창의 토큰을 함께 보내세요:

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

설정

하단 도구 모음의 톱니바퀴 아이콘에서 설정 창을 엽니다.

클라이언트 예제

cURL

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

# Claude via the same OpenAI shape
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",  # ignored when Bearer Token is off
)
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

// Using any OpenAI-compatible Dart client
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // unused when Bearer Token is off
);

팁

• 로컬에서 개발하는 동안에는 Bearer 토큰을 꺼 두고, LAN 접근을 켜는 순간 함께 켜세요.
• 클라이언트 코드에서 제공업체별로 서로 다른 기본 URL을 쓰면 상수 하나만 바꿔서 제공업체를 전환할 수 있습니다.
• 프록시는 자동으로 시작되지만, 포트 충돌이 생기면 메인 창에서 잠시 중지할 수 있습니다.
• 제공업체의 무료 등급에서 속도 제한에 걸리면 상위 서비스의 오류 메시지가 그대로 전달됩니다. 클라이언트 모르게 재시도하는 로직은 없습니다.
• 다음 /v1/providers 엔드포인트를 사용하면 실행 중에 어떤 제공업체가 구성되어 있는지 확인할 수 있습니다.

문제 해결

프록시가 시작되지 않습니다

• 다른 프로세스가 이미 8421 포트를 쓰고 있을 수 있습니다. 설정에서 포트를 바꾸고 프록시를 다시 시작하세요.
• 시작할 때 표시된 오류 메시지를 시스템 로그에서 확인하세요.

요청이 401 Unauthorized를 반환합니다

• Bearer 토큰 요구가 켜져 있는데 클라이언트가 일치하는 Authorization: Bearer ... 헤더를 보내지 않았습니다.
• 제공업체의 API 키 자체가 잘못되었을 수도 있습니다. 상위 서비스의 오류가 그대로 전달되므로 본문 메시지를 확인하세요.

요청이 "API key is not configured"를 반환합니다

• 제공업체 목록을 열고 해당 제공업체의 API 키 설정 을 클릭하세요.
• ERNIE는 API Key와 Secret Key를 모두 입력해야 합니다. Azure OpenAI는 Endpoint Base URL도 필요합니다.

모바일 기기에서 프록시에 접근할 수 없습니다

• 설정에서 LAN 접근 허용 을 켜세요.
• 기본 URL 필드에 표시된 LAN IP를 사용하세요. 다음은 사용하지 마세요: localhost.
• 두 기기가 같은 Wi-Fi 네트워크에 있는지, 방화벽이 프록시 포트로 들어오는 연결을 허용하는지 확인하세요.

스트리밍 응답이 한꺼번에 도착합니다

• 클라이언트가 "stream": true 를 JSON 본문에 담아 보내는지 확인하세요.
• 일부 HTTP 라이브러리는 기본적으로 SSE를 버퍼링합니다. 클라이언트 쪽에서 응답 버퍼링을 꺼 주세요.

개인정보 보호

• API 키는 Fernet으로 암호화되어 다음 위치에 저장됩니다: ~/Library/Application Support/AIProxyServer/credentials.enc. 암호화 키가 들어 있는 master.key 파일의 권한은 0600입니다.
• Bearer 토큰도 켜져 있을 때 암호화된 저장소에만 보관되며, 일반 설정 파일에는 기록되지 않습니다.
• 프록시는 사용자가 직접 구성한 제공업체로만 요청을 전달합니다. 그 밖의 외부 통신은 하지 않습니다.
• 텔레메트리도, 분석도, 크래시 리포트도 없습니다.
• 기본 네트워크 바인딩은 127.0.0.1 뿐입니다. LAN 노출은 직접 선택해야 합니다.
• 대화 내용은 저장되지 않습니다. AIProxyServer는 바이트를 전달하고 곧바로 잊어버립니다.