여러 AI 데스크톱 클라이언트의 로그인 상태를 통합하는 OpenAI 호환 API 게이트웨이

简体中文 | English | 繁體中文 | 日本語 | 한국어 | Português (BR)

다수의 AI 데스크톱 클라이언트의 로그인 상태를 하나의 로컬 OpenAI 호환 API 게이트웨이로 통합합니다. 이를 통해 base_url을 하나로 통일하여 노출하며, 다중 계정 관리, 모델 관리, 외부 프록시(outbound proxy) 및 요청 보고서 기능을 제공하고, 즉시 사용할 수 있는 Tauri 데스크톱 애플리케이션을 함께 제공합니다. 자체 base_url 설정이 가능한 모든 OpenAI 클라이언트는 상위 API Key나 클라이언트 수정 없이도 이 게이트웨이를 통해 여러 회사의 모델 할당량을 호출할 수 있습니다.

지원 현황 요약 (✓ 지원 · ✗ 미지원 · — 개념 없음):

본 프로젝트는 학습 및 교류 목적으로만 제공됩니다. 이는 공식 클라이언트가 아닌 형태로 사용자 본인의 계정 로그인 상태를 재사용하므로, 상위 서비스의 이용 약관에 위배될 수 있으며, 위험(계정 풍제어 또는 정지 포함)은 사용자 본인이 부담합니다. 상업적 사용이나 과금 우회는 금지됩니다. 자세한 내용은 사용 선언 및 LICENSE를 참조하십시오. 본 프로젝트는 각 상위 제조사 및 그들의 공식 제품과 무관하며 (목록은 사용 선언 참고), 인터페이스 형태는 각 클라이언트와의 통신 관찰을 기반으로 하며, 상위 서비스는 언제든지 조정될 수 있습니다.

릴리스(Releases)에서 설치 패키지를 다운로드하십시오 (NSIS, 간체 중국어, 기본적으로 C:\Program Files\Agent2API에 설치되며, 설치 시 관리자 권한이 필요합니다). 설치 후 실행하면 Node나 다른 런타임 환경을 설치할 필요 없이 바로 사용할 수 있습니다.

• 최초 실행 시 애플리케이션 프로세스 내에서 로컬 게이트웨이(포트 3065)가 시작되고 메인 창이 열립니다. 이전 버전의 데이터 디렉터리나 데이터 파일이 감지되면 마이그레이션 안내 팝업이 표시되며, 지침에 따라 진행하면 됩니다.
• '계정' 페이지에서 '계정 추가'를 누르고 제공자를 선택한 후 팝업 지침에 따라 로그인하거나 자격 증명을 입력하면 됩니다 (방식은 팝업 기준: 웹 로그인 / 휴대폰 인증 코드 / 자격 증명 붙여넣기 / 로컬 로그인 상태 가져오기).
• OpenAI 클라이언트의 base_url을 http://127.0.0.1:3065/v1로, api_key는 임의 값(예: sk-local, 인증이 활성화되지 않은 경우 서버에서 검증하지 않음)으로 설정합니다.

창을 닫으면 기본적으로 트레이에 최소화되며 게이트웨이는 백그라운드에서 계속 포워딩됩니다. 완전히 종료하려면 트레이 아이콘을 마우스 오른쪽 버튼으로 클릭하고 '종료'를 선택하십시오.

게이트웨이가 실행되면, curl 명령어를 사용하여 연결성을 확인합니다 (model에 실제로 존재하는 이름을 넣으세요: GET /v1/models):

curl http://127.0.0.1:3065/health
curl http://127.0.0.1:3065/v1/models
curl http://127.0.0.1:3065/v1/chat/completions \
...

클라이언트 연동 예시 (Python SDK):

from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:3065/v1", api_key="sk-local")
resp = client.chat.completions.create(...)

웹 브라우저 페이지 (직접 구축한 Web UI 등)에서 fetch를 사용하여 직접 연결하면 크로스 오리진 검사(CORS)에 의해 거부될 수 있습니다. 게이트웨이는 기본적으로 CORS 응답을 하지 않으며, 사전 검사는 API Key 검증 단계에서 401 에러가 발생할 수 있습니다. 두 가지 해결책이 있습니다: ① 설정 페이지의 '보안 → 게이트웨이 교차 도메인 접근'을 활성화합니다 (출처 *; 이 경우 모든 웹페이지가 로컬 게이트웨이를 통해 상위 서비스에 접속할 수 있으므로, '게이트웨이 Key'를 함께 설정하는 것이 좋습니다); ② 페이지와 게이트웨이가 동일 출처(Same-Origin)인 경우 — 로컬 정적 서비스를 호스팅하고 /v1을 127.0.0.1:3065로 리버스 프록시합니다.

기본적으로 127.0.0.1만 수신 대기합니다. '설정 → 일반 → 로컬 네트워크 접근'을 활성화하면 모든 네트워크 카드를 수신 대기로 변경할 수 있으며, 로컬 네트워크 장치는 API 주소를 본인 IP로 지정하여 공유할 수 있습니다 (화면에 전체 주소가 표시됨). 보안상의 이유로 이 기능을 켜기 전에 반드시 패널 관리자를 등록해야 합니다: 관리 인터페이스는 관리자 세션 또는 게이트웨이 Key를 요구하며, 사용 가능한 Key가 없으면 포워딩 인터페이스도 서비스 거부됩니다 (활성화 과정에서 '기본' Key가 자동으로 추가됨); 또한 웹 페이지 패널을 동시에 열어둘 수도 있습니다 (기본적으로 비활성화). 변경 사항은 재시작해야 적용됩니다.

docker run -d --name agent2api --restart unless-stopped
-p 3065:3065 -v ./data:/data
aimodcc/agent2api:latest

브라우저에서 http://<호스트>:3065로 접속하면,
처음 방문 시 관리자 계정 등록을 안내받게 됩니다. 로그인 후 「게이트웨이 Key」 페이지에서 클라이언트를 위한 API Key를 생성합니다 — http://<호스트>:3065/v1
이는 OpenAI와 호환되는 엔드포인트이며 (Key가 설정되지 않은 경우 포워딩 거부), 상태(SQLite 데이터베이스 / 구성 / 로그)는 모두 ./data 볼륨에 저장됩니다.

compose 사용자용 (amd64 / arm64 모두 이미지 제공):

services:
agent2api:
image: aimodcc/agent2api:latest
...

환경 변수 (모두 선택 사항):

소스 코드에서 빌드: 이 저장소를 클론한 후 docker compose up -d --build를 실행합니다.
(이미지에는 게이트웨이와 패널만 포함되어 있으며, Rust 툴체인은 포함되어 있지 않습니다).

웹 페이지 기능 차이점 (로컬 데스크톱 클라이언트가 없는 경우 발생): 웹 로그인(WorkBuddy / Qoder / Cline), 모바일 인증 코드, 붙여넣기 자격 증명은 모두 사용 가능합니다. 로컬 기기 콜백이 필요한 웹 로그인(AutoClaw / CatPaw / Accio / CodeArts / Trae) 및 「로컬 로그인 상태 가져오기」는 사용할 수 없으므로, 붙여넣기 자격 증명을 사용해야 합니다.

모든 계정이 하나의 큐에 나열됩니다 (왼쪽에서 두 번째 열이 우선순위). 개별적으로 시작/중지할 수 있으며, 할당량 냉각 시간(限额冷却), 유효 기간 및 잔액은 행 내에 표시되고, 잔액 부족 시 기본값으로 임계치를 기준으로 건너뜁니다.

계정 추가 시 제공업체를 먼저 선택한 후 로그인합니다. 동일한 서비스의 경우 여러 버전의 계정을 저장할 수 있습니다 (예: WorkBuddy 국내 / 국제 버전).

개요: 요청 수 / 성공률 / 토큰 총량 / 상위 모델 및 계정, 제공업체 순위와 사용량 링 차트 및 365일 활동 히트맵이 표시됩니다:

추세: 24시간 캐시 적중률(꺾은선 그래프)과 토큰 소모(면적 그래프)를 이중 축으로 하나의 그래프에, 하단에는 일별 토큰 막대 그래프가 표시됩니다:

백엔드 작업은 이 페이지에서 통합 관리됩니다 (스위치 / 간격 / 마지막 결과 / 즉시 실행); 목록은 ~/.agent2api/config.json 파일의 scheduledTasks에 존재하며, 수정 사항은 즉시 적용됩니다.

백엔드는 src-tauri/ 아래의 Rust 프로세스 내 HTTP 서버이며, 프론트엔드는 ui/ 아래의 네이티브 HTML/CSS/JS로 구성되어 있습니다.

전체 디렉토리 트리 (클릭)

agent2api/
├─ desktop-tauri/
│ ├─ src-tauri/
...

• Rust >= 1.77 및 Tauri 2 툴체인 (데스크톱 본체 컴파일; Windows의 경우 WebView2 런타임 필요)
• Node.js >= 18.17 (오직 npm run tauri:*와 프론트엔드 빌드 스크립트에만 사용되며, 데스크톱 실행 시에는 Node에 의존하지 않음)

npm run tauri:install # 데스크톱 종속성 설치 (npm --prefix desktop-tauri install와 동일)
npm run tauri:dev # 개발 모드로 데스크톱 실행 (자동 리핫 로딩)
npm run tauri:build # 데스크톱 설치 패키지 빌드
...

패키징 산출물은 target/release/bundle/nsis/Agent2API_<버전>_x64-setup.exe입니다
(현재 약 3.0 MB; src-tauri/.cargo/config.toml에서 cargo의 target-dir을 프로젝트 루트의 target/로 지정합니다).

본 프로젝트는 HTTP 리버스 프록시, SSE(Server-Sent Events) 스트리밍 전송, 다중 상위 프로토콜 적응 및 데스크톱 패키징(Tauri) 등의 기술 주제를 학습하기 위한 실습 프로젝트이며, 개인적인 학습 및 연구 목적으로만 사용됩니다. 본 프로젝트는 공식 제품이 아니며, 텐센트(Tencent)와 WorkBuddy / CodeBuddy, 메이퇀(Meituan)과 CatPaw, 상산(SenseTime)과 소환웅(小浣熊), 지푸(ZhiPu)와 AutoClaw / autoglm, 알리바바(Alibaba)와 Qoder / Accio, 화웨이 클라우드(Huawei Cloud)와 CodeArts, 바이트댄스(ByteDance)와 Trae, 커디춘페이(科大讯飞)와 Loomy, 바이두 문쿠(百度文库)와 KukuAI, 창팅 테크놀로지(长亭科技)와 MonkeyCode, Command Code, Google과 Antigravity 등 어떠한 회사와도 관련이 없으며, 해당 기업으로부터의 승인, 인정 또는 후원을 받지 않았습니다.

본 프로젝트는 로컬 리버스 프록시를 구현합니다. 즉, 사용자의 자체 기기에서 본인이 가진 계정의 로그인 상태를 재사용하여 요청을 공식 상위 게이트웨이로 전달하는 방식입니다. 이는 어떠한 유료 또는 권한 검증도 해킹하거나 우회하지 않으며, 사용되는 크레딧은 항상 사용자 계정에 원래 존재하는 할당량에서 나옵니다. 하지만 명확히 해야 할 것은, 이러한 '비공식 클라이언트 형태로 로그인 상태를 재사용하는' 방식의 프록시 전송은 상위 서비스의 이용 약관이나 사용 조건에 위배될 수 있다는 점입니다. 따라서 본 프로젝트의 사용으로 인해 발생하는 모든 결과(계정 제한, 리스크 관리 대상 지정, 동결 또는 차단 포함)는 사용자 본인이 책임져야 합니다.

본 프로젝트를 어떠한 상업적 용도, 2차 배포를 통한 이익 창출, 대량 계정 운영, 상위 과금 또는 할당량 제한 우회, 기타 현지 법규 및 규정을 위반하는 활동에 사용해서는 안 됩니다. 만약 프로덕션 환경이나 상업적 시나리오에서 관련 모델 서비스를 호출해야 한다면, 반드시 공식 채널과 공식 API를 사용해 주십시오.

본 프로젝트는 계정 자격 증명(accessToken / refreshToken 등)을 평문 형태로 로컬 설정 디렉토리(기본값 ~/.agent2api/)에 저장하며, 내보내기 기능으로 생성되는 파일 역시 평문 자격 증명을 포함합니다. 사용자가 직접 안전하게 보관해야 하며, 공개 레포지토리에 제출하거나 웹하드에 업로드하거나 타인과 공유해서는 안 됩니다. 자격 증명 유출로 인해 발생하는 손실은 사용자 본인이 책임져야 합니다.

본 프로젝트는 '현황'을 기준으로 제공되며, 작성자는 그 사용 가능성, 안정성, 보안 또는 특정 용도에의 적합성에 대해 어떠한 약속도 하지 않습니다. 상위 인터페이스는 언제든지 변경될 수 있으며, 본 프로젝트는 예고 없이 효력을 잃거나 유지보수가 중단될 수 있습니다. 전체 조항은 LICENSE를 참조하십시오. 본 프로젝트의 인터페이스 형태, 프로토콜 필드 등의 정보는 각 공식 클라이언트의 공개 네트워크 통신을 관찰하고 정리한 것에서 가져왔으며, 관련 상표 및 서비스의 권리는 해당 소유자에게 있습니다. 만약 권리자가 본 프로젝트에 부적절한 부분이 있다고 판단할 경우, 작성자에게 연락하여 적시에 조정하거나 삭제해 주십시오.

본 프로젝트는 MIT License를 기반으로 하므로 자유롭게 사용, 수정 및 배포할 수 있으며, 저작권 고지 사항을 유지해야 합니다.

주의할 점은 다음과 같습니다. LICENSE 본문 뒤에 **사용 진술서(Usage Statement)**가 첨부되어 있는데, 이 중 제 3조는 MIT 라이선스 위에 추가적인 제한을 가하고 있습니다(상업적 용도 금지, 2차 배포를 통한 이익 창출 금지, 대량 계정 운영 금지). 따라서 본 프로젝트는 순수한 MIT 프로젝트가 아닙니다. MIT 조항과 사용 진술서가 함께 완전한 권한 및 사용 약관을 구성하며, 두 가지가 동일 행위에 대해 다른 결론을 내릴 경우 더 엄격한 쪽을 따릅니다. 이것이 Cargo.toml에서 SPDX `