Agent2API 입문 튜토리얼: 데스크톱 AI 로그인 상태를 OpenAI 호환 게이트웨이에 연결하기

Agent2API란 무엇인가

Agent2API는 여러 AI 데스크톱 클라이언트에 로그인된 계정을 통합하고, 통합된 OpenAI 호환 인터페이스를 통해 모델 호출 기능을 제공하는 로컬 AI API 게이트웨이입니다. 사용자 지정 base_url을 지원하는 클라이언트라면 http://127.0.0.1:3065/v1에 연결할 수 있으며, 일반적으로 상위 API Key가 필요하지 않고 클라이언트를 수정할 필요도 없습니다.

이 프로젝트는 Chat, Responses, Messages 세 가지 프로토콜을 지원하며 /v1/models 모델 목록 API를 제공합니다. 게이트웨이는 로컬 컴퓨터 또는 배포한 서버에서 실행되며, 계정의 사용량 한도는 해당 계정 자체에서 제공됩니다.

핵심 기능 개요

• OpenAI 호환 인터페이스: /v1/chat/completions, /v1/responses, /v1/messages를 지원하며, Messages는 count_tokens도 지원합니다.
• 다중 제공업체: WorkBuddy, 小浣熊, CatPaw, Qoder, Trae 등을 포함한 여러 제공업체가 기본 제공되며, 사용자 지정 제공업체도 구성할 수 있습니다.
• 계정 순환: 계정은 우선순위에 따라 대기열에 배치됩니다. 429가 발생하면 계정을 전환할 수 있으며, 한도 냉각 기간에 있는 계정은 계속 사용되지 않습니다.
• 자격 증명 관리: 일부 제공업체는 Token 자동 갱신, 만료 임박 자격 증명의 일괄 새로 고침, 모델 목록 새로 고침을 지원합니다.
• 네트워크 및 보안: 계정별 독립 외부 연결 프록시를 설정하고, 여러 게이트웨이 Key를 통해 권한을 분배할 수 있습니다.
• 운영 관리: 요청 수, 성공률, Token 사용량, 캐시 적중률, 장기 히트맵 등의 보고서를 제공합니다.
• 예약 작업: 자동 출석 체크, 자격 증명 관리, 모델 목록 새로 고침 작업을 관리할 수 있습니다.

배포 방식 선택

Agent2API는 세 가지 형태를 제공합니다. 데스크톱 버전은 개인 컴퓨터에 적합하며 Windows, macOS, Linux를 지원하고 트레이에서 상주 실행할 수 있습니다. 서버 버전은 그래픽 인터페이스가 없는 Windows Server 또는 Linux 환경에 적합합니다. Docker는 이미 컨테이너 환경을 사용하는 사용자에게 적합합니다. 세 가지 방식 모두 실행 시 Node.js를 설치할 필요가 없습니다.

• 데스크톱 버전: 설치 패키지로 애플리케이션을 시작하며, 게이트웨이는 애플리케이션 프로세스에서 실행됩니다.
• 서버 버전: 시스템 서비스로 설치하고 브라우저로 관리 패널에 접속하며, 부팅 시 자동 시작을 지원합니다.
• Docker: aimodcc/agent2api:latest 이미지를 사용하며 amd64와 arm64를 지원합니다.

설치 및 최초 설정

방법 1: 데스크톱 버전

프로젝트의 Latest Releases에서 운영 체제에 맞는 설치 패키지를 다운로드합니다. 시작한 후 “계정” 페이지로 이동하여 하나 이상의 제공업체 계정을 추가합니다. 데스크톱 게이트웨이는 기본적으로 로컬 컴퓨터의 3065 포트를 수신합니다.

방법 2: Linux 서버

tar -xzf agent2api-server-linux-amd64.tar.gz && cd agent2api-server-linux-amd64 && sudo bash install.sh

설치가 완료되면 브라우저에서 http://127.0.0.1:3065/에 접속합니다. 서비스가 원격 호스트에서 실행 중이라면 주소의 호스트 이름을 서버 IP 또는 도메인으로 바꿉니다.

방법 3: Windows Server

Expand-Archive agent2api-server-windows-amd64.zip -DestinationPath C:\agent2api-pkg
cd C:\agent2api-pkg
.\install-service.ps1

관리자 권한 PowerShell에서 위 명령을 실행합니다. 설치 스크립트가 서비스를 시스템에 등록합니다.

방법 4: Docker

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

여기서 ./data:/data는 구성과 계정 데이터를 영구 보존하는 데 사용됩니다. 컨테이너가 시작되면 http://127.0.0.1:3065/을 열어 초기화를 완료합니다.

관리자 및 게이트웨이 Key 초기화

1. 관리 패널을 열고 관리자 계정을 등록합니다.
2. “게이트웨이 Key” 페이지로 이동하여 클라이언트 호출에 사용할 Key를 생성합니다.
3. “계정” 페이지로 이동하여 제공업체와 버전을 선택한 후 페이지의 절차에 따라 웹 로그인 또는 로그인 상태 가져오기를 완료합니다.
4. 계정 상태, 유효 기간, 잔액 정보가 정상인지 확인합니다.
5. “모델 관리” 페이지로 이동하여 사용 가능한 모델과 모델 매핑을 확인합니다.

게이트웨이 Key를 구성하지 않으면 프로젝트는 기본적으로 API 요청을 거부합니다. 게이트웨이 Key를 공개 코드, 로그 또는 신뢰할 수 없는 클라이언트에 노출하지 마세요.

계정 및 모델 구성

계정 관리 페이지에서 계정 유효 기간, 잔액, 전역 대기열, 모델별 한도 냉각 상태를 확인할 수 있습니다. 여러 계정을 추가하면 시스템이 우선순위에 따라 예약합니다. 특정 계정에서 429가 발생하거나 냉각 상태에 들어가면 다른 사용 가능한 계정으로 전환할 수 있습니다.

모델 관리 페이지에서는 제공업체별 모델 목록, 배율, 컨텍스트 정보, 매핑 관계를 확인할 수 있습니다. 모델 목록을 온라인에서 자동으로 가져오는 제공업체는 정기적으로 새로 고쳐집니다. 일부 플랫폼은 대체용 기본 정적 목록도 제공합니다.

첫 번째 API 호출

사용자 지정 API 주소를 지원하는 클라이언트에서 Base URL을 다음과 같이 설정합니다.

http://127.0.0.1:3065/v1

API Key에는 방금 생성한 게이트웨이 Key를 입력합니다. 예를 들어 sk-local을 예시 값으로 사용할 수 있지만, 실제 호출에서는 패널에서 생성한 Key를 사용해야 합니다.

먼저 게이트웨이 상태를 확인합니다.

curl http://127.0.0.1:3065/health

그런 다음 모델 목록을 확인합니다.

curl http://127.0.0.1:3065/v1/models \
  -H "Authorization: Bearer YOUR_GATEWAY_KEY"

Chat Completions API 호출 예시는 다음과 같습니다.

curl http://127.0.0.1:3065/v1/chat/completions \
  -H "Authorization: Bearer YOUR_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {"role": "user", "content": "안녕하세요. 자신을 소개해 주세요."}
    ]
  }'

YOUR_GATEWAY_KEY를 게이트웨이 Key로 바꾸고, YOUR_MODEL_ID를 /v1/models에서 반환된 모델 ID로 바꿉니다. Responses와 Messages 프로토콜도 동일한 게이트웨이 주소를 사용하며, 구체적인 요청 필드는 해당 클라이언트 또는 프로토콜 형식을 따라야 합니다.

다중 계정, 프록시 및 예약 작업

다중 계정 순환

동일한 제공업체에 여러 계정을 추가하면 전역 우선순위 대기열과 429 폴백 메커니즘을 활용하여 가용성을 높일 수 있습니다. 계정 한도, 유효 기간, 사용 시나리오에 따라 적절한 우선순위를 설정하고 냉각 중인 계정을 정기적으로 확인하는 것이 좋습니다.

외부 연결 프록시

프로젝트는 계정별 독립 출구를 구성할 수 있도록 지원합니다. 이 기능은 계정별로 외부 네트워크를 관리해야 하는 상황에 적합하지만, 프록시의 가용성, 규정 준수 여부, 계정 위험 관리 문제는 사용자가 직접 평가해야 합니다.

예약 작업

작업 관리 페이지에서 자동 출석 체크, 자격 증명 관리, 모델 목록 새로 고침을 통합 관리하고 작업 활성화 여부와 실행 간격을 설정할 수 있습니다. 제공업체마다 지원 기능이 다르므로 일부 플랫폼은 Token 갱신, 출석 체크 또는 잔액 조회를 지원하지 않을 수 있습니다.

보고서 및 사용량 확인

보고서 페이지에서 요청 수, 성공률, 총 Token 수, 인기 모델, 계정 순위를 확인하고 제공업체별 사용량 분포도 확인할 수 있습니다. 추이 페이지에는 24시간 캐시 적중률, Token 사용량, 일별 통계 데이터가 표시됩니다.

제공업체가 잔액 또는 사용량 조회를 지원하면 계정 페이지에서 관련 정보를 직접 확인할 수도 있습니다. 출석 체크 센터에서는 출석 체크 개요와 일일 출석 체크 그룹을 확인할 수 있습니다.

개발 및 빌드 안내

소스 코드에서 데스크톱 버전을 빌드하려면 Rust 1.77 이상, Tauri 2 도구 체인, Node.js 18.17 이상이 필요합니다. Node.js는 프런트엔드 빌드와 Tauri 스크립트에만 사용되며, 패키징된 데스크톱 버전은 실행 시 Node.js에 의존하지 않습니다.

npm run tauri:install
npm run tauri:dev
npm run tauri:build
npm run build:icon

여기서 tauri:dev는 개발 모드와 핫 리로드에 사용되고, tauri:build는 데스크톱 설치 패키지 빌드에 사용됩니다. macOS용 DMG는 macOS에서만 빌드할 수 있으며 Windows에서 크로스 컴파일할 수 없습니다. 정식 산출물은 프로젝트 CI 워크플로에서 생성됩니다.

자격 증명 보안 및 사용 범위

Agent2API는 학습 및 교류 목적으로만 제공됩니다. 비공식 클라이언트 형태로 사용자의 계정 로그인 상태를 재사용하므로 상위 서비스의 이용 약관을 준수하지 않을 수 있으며, 계정의 속도 제한, 위험 제어, 정지 또는 차단 등의 위험은 사용자가 직접 부담해야 합니다.

프로젝트는 accessToken, refreshToken 등의 계정 자격 증명을 평문으로 로컬 구성 디렉터리에 저장하며, 기본 위치는 ~/.agent2api/입니다. 내보낸 파일에도 평문 자격 증명이 포함될 수 있으므로 구성을 공개 저장소에 커밋하거나 클라우드 저장소에 업로드하거나 다른 사람과 공유하지 마세요.

README에서는 프로젝트를 상업적 용도, 재배포를 통한 영리 활동, 대량 계정 운영, 상위 서비스의 결제 또는 할당량 제한 우회 및 기타 법률과 규정을 위반하는 활동에 사용하는 것을 명확히 금지합니다. 운영 또는 상업적 환경에서는 상위 서비스의 공식 채널과 공식 API를 사용해야 합니다. 사용하기 전에 프로젝트의 LICENSE 및 사용 선언을 읽어 보세요.

맺음말

Agent2API는 여러 데스크톱 클라이언트의 계정을 하나의 로컬 OpenAI 호환 게이트웨이로 통합합니다. 배포를 완료하고 계정을 추가한 뒤 게이트웨이 Key를 생성하면 통합 base_url을 통해 사용자 지정 API 주소를 지원하는 도구에 연결할 수 있습니다. 다중 계정 순환, 모델 관리, 프록시, 예약 작업 및 보고서는 추가적인 로컬 관리 요구에 적합합니다. 사용 시 자격 증명을 안전하게 보호하고 상위 서비스 약관과 프로젝트의 추가 사용 선언을 엄격히 준수하세요.