ACP-Ant
Google 공식 **Antigravity CLI(agy)**를 **ACP 프로토콜(Agent Client Protocol)**을 통해 표준 대규모 언어 모델 인터페이스로 변환합니다:
OpenAI Chat Completions, OpenAI Responses, Anthropic Messages 세 가지 형식을 모두 지원하며, 함수 호출(function calling) 기능을 제공하여 Agent와 애플리케이션이 직접 연결할 수 있습니다.
여러 Google 계정을 순차적으로 사용할 수 있으며, 각 계정은 자체 프록시 노드를 사용합니다.
1.5.0 버전부터는 Google AI Studio를 두 번째 출처로 연결하는 것도 가능합니다: 동일한 주소와 키를 사용하여, aistudio/<모델명>으로 AI Studio를 이용하고 나머지는 Antigravity를 이용할 수 있어, 하나의 Google 계정의 할당량을 양쪽에서 모두 사용할 수 있습니다.
- 공식 Google 명령줄 프로그램과 프로토콜을 사용하므로, 패킷 스니핑이나 웹 로그인 자격 증명 프록시가 필요 없습니다.
- Codex CLI, OpenAI SDK, LangChain, Dify, Cline, OpenCode 등 OpenAI 또는 Anthropic 인터페이스를 지원하는 모든 도구에서 주소, 키, 모델명을 입력하여 사용할 수 있습니다.
- 계정이 많으면 자동으로 분산 처리됩니다. 특정 계정의 할당량이 소진되거나 속도 제한(rate-limited)이 걸리거나 인증을 요구할 경우 다음 계정으로 자동 전환됩니다.
- AI Studio 두 번째 출처 (선택 사항): 한 명령어로 AIStudio2API를 실행하고, 패널에서 서버의 브라우저로 Google에 로그인하여 사용합니다. 로컬 컴퓨터에 의존하지 않으며 세션이 장기간 유효합니다. Gemini 4 Hydrogen 등 AI Studio 모델을 사용할 수 있습니다. 자세한 내용은 AI Studio 두 번째 출처를 참조하세요.
- 웹 제어판: 계정 추가, Google 로그인, 프록시 변경, 각 계정의 할당량 확인, 계정 활성화/비활성화, 자동 점검 등 모든 작업을 웹에서 클릭만으로 처리할 수 있어 명령어를 입력할 필요가 없습니다. Antigravity와 AI Studio 두 경로 모두 이메일로 동일한 계정 카드에 표시됩니다.
English
🎬 추천: COOL AI — 전자상거래 AI 비디오 및 이미지 원스톱 제작
상품 이미지를 하나 업로드하면, 라이브 커머스 판매 영상, 스토리텔링 쇼츠 드라마, 그리고 전체 전자상거래 상세 페이지를 만들 수 있습니다.
- 라이브 커머스 판매 영상: 스크립트, 샷 구성(분경), 대사를 자동으로 작성하여 원클릭으로 실제 인물 라이브 커머스 영상을 생성합니다.
- 스토리텔링 판매 영상: 반전 드라마, 대화 드라마, 스토리 삽입 등을 통해 자동 각본 작성, 샷 구성 및 결과물을 만듭니다.
- 전자상거래 상세 이미지: 흰 배경의 이미지를 하나만으로 메인 이미지, 장면 이미지, 핵심 포인트 이미지, 디테일 이미지, 비교 이미지 등 전체 세트를 원클릭으로 생성합니다.
- AI 이미지 및 도구: 상품 보정, GIF 애니메이션, 디지털 휴먼, 자막 제거, 화질 향상
👉 지금 바로 체험하기: www.coolai.mov
이 도구가 하는 일
Agent / 애플리케이션 ──OpenAI 또는 Anthropic 인터페이스──▶ ACP-Ant (127.0.0.1:8095)
(도구는 Agent가 직접 실행) │ 여유 계정 선택
├─▶ agy acp (계정 g1, HOME=accounts/g1, 프록시 A 사용)──▶ Google Antigravity
...
- 세 가지 인터페이스:
/v1/chat/completions (OpenAI), /v1/responses (OpenAI의 새로운 인터페이스, Codex용), /v1/messages (Anthropic) 모두 스트리밍 출력을 지원합니다.
- 도구 호출(Tool Calling): Agent가 선언한 도구(OpenAI
tools, Anthropic tools, Responses의 function / custom 도구)는 프롬프트에 포함되어 모델에게 전달됩니다. 모델이 도구를 사용해야 할 경우, 게이트웨이가 그 응답을 표준 tool_calls / tool_use / function_call 형식으로 변환하여 Agent에게 반환합니다. Agent가 직접 도구를 실행하고 결과를 다시 보내는 방식입니다. 한 번의 호출로 여러 도구 사용이 가능하며, tool_choice도 지원합니다.
- 이미지: data URL, http(s) 이미지 링크(게이트웨이가 대신 다운로드), 그리고 도구 결과 내 이미지를 모두 사용할 수 있습니다. 순수 텍스트 파일(txt / md / json / csv 등)은 문자로 변환됩니다. 한 번의 요청으로 최대 200장의 이미지를 처리할 수 있습니다 (
AGY_MAX_IMAGES. 실제 테스트에서 Gemini 3.8 Flash는 200장을 순서대로 모두 확인했으며, 250장은 상위 시스템에서 오류가 발생했습니다). 최신 메시지의 이미지는 절대 손실되지 않으며, 초과 시 400 에러를 반환합니다. 다중 대화에서 이미지가 너무 많을 경우, 가장 오래된 것부터 순차적으로 설명 문구 한 줄로 대체됩니다.
- 장문 대화: 공식 CLI는 매우 긴 입력 내용을 끝부분부터 잘라냅니다(약 18만 8천 자). 이 경우 최신 질문이 손실될 수 있습니다. 게이트웨이는 전체 입력 내용이
AGY_MAX_PROMPT_CHARS (기본값 150,000, 0 = 제한 없음)를 초과할 경우, 먼저 오래된 도구 출력을 축소하고 가장 초기 기록부터 생략하며 모델에게 알려줍니다. 최신 입력은 항상 온전하게 전달됩니다.
- 비디오, 오디오, PDF 등 파일: 기본적으로 지원하지 않으며, 400 에러를 반환합니다(Gemini가 비디오를 보게 하려면 아래 비디오 모드 참고). Antigravity의 ACP 인터페이스는 텍스트와 이미지만을 모델에 전달하며, 비디오, 오디오, PDF를 보내면 조용히 무시됩니다. 모델은 응답을 하지만 내용은 꾸며낸 것일 수 있습니다(실제 테스트에서 agy 1.5.3, Gemini 4 Argon / Gemini 3.8 Flash 모두 동일). 따라서 게이트웨이는 이러한 종류의 내용(OpenAI
file / input_audio / video_url, Responses input_file, Anthropic PDF document 등)을 감지하면 즉시 400 에러를 반환하고 어떤 항목인지 명시합니다. 호출자는 다른 채널로 전환하거나 비디오를 이미지 프레임으로 추출하여 보낼 수 있습니다.
- 계정별 독립 디렉토리:
agy의 HOME 경로는 이 디렉토리를 가리키며, 로그인 자격 증명은 이곳에만 존재하므로 계정 간에 서로 섞이지 않습니다.
- 계정별 독립 프록시(선택 사항):
http://, https://, socks5://를 지원하며 사용자 이름과 비밀번호를 포함할 수 있습니다. 추가 시에는 출구 IP와 국가를 테스트하며, 두 계정이 같은 IP를 사용할 경우 경고합니다.
- Antigravity는 사용자의 기기를 건드리지 않습니다: 게이트웨이가
agy에 등록한 Agent는 내장된 도구가 없으며, 권한 요청은 일체 거부됩니다. 도구는 오직 Agent 측에서만 실행됩니다.
- 자동 계정 전환: 본문 출력을 하기 전에 오류가 발생하면 다음 계정으로 전환하여 재시도합니다. 할당량 소진 시 30분 대기, 속도 제한 시 90초 대기, 인증 요청 시 10분 대기하며, 로그인에 실패한 계정은 사용이 중단됩니다.
- Antigravity의 '소프트 에러' 인식: 검열 차단, 계정 인증 필요, 상위 시스템 오류(예:
RESOURCE_EXHAUSTED) 등의 경우, Antigravity는 오류를 반환하는 대신 고정된 문구를 답변으로 보내며 때로는 백그라운드에서 몇 분 동안 재시도하기도 합니다. 게이트웨이는 이 상황을 수 초 내에 감지하여 표준 에러 코드를 반환하며, Agent가 정상적으로 재시도하거나 채널을 전환할 수 있게 합니다.
- 모델명 기본값 처리: Agent가 Antigravity가 지원하지 않는 모델 이름(예: 하드코딩된
gpt-4o)을 요청하면 자동으로 기본 모델로 변경하여 사용합니다(비활성화 가능).
- 개인 정보 보호:
agy는 모든 대화 기록을 로컬에 저장하며, 게이트웨이는 매시간 6시간이 지난 기록을 삭제합니다(설정 가능).
- 새 계정 추가 시 재시작 불필요: 게이트웨이가 새로운 계정을 자동으로 감지합니다.
요구 사항
- Linux (x86_64 또는 arm64), Python 3.10+,
curl, git이 필요하거나, Docker만 사용 가능합니다.
- Antigravity를 사용할 수 있는 하나 이상의 Google 계정(예: Google AI Pro).
- 선택 사항: 각 계정별 프록시 노드.
설치 방법
세 가지 방식 중 원하는 것을 선택하여 설치한 후 웹 페이지 제어판에서 작업할 수 있습니다.
방식 1: 시스템 서비스 (권장, sudo 필요)
git clone https://github.com/czg86389-hub/ACP-Ant.git
cd ACP-Ant
./install.sh
설치 스크립트는 다음 작업을 수행합니다:
- 공식 주소(
https://antigravity.google/cli/install.sh)에서 agy를 /opt/acp-ant/bin에 설치합니다.
- Python 가상 환경을 생성하고 의존성(FastAPI, Uvicorn)을 설치합니다. 만약
python3-venv가 누락된 경우, apt 패키지 관리자를 통해 자동으로 보충하거나 어떤 패키지를 설치해야 하는지 안내합니다.
- 무작위 게이트웨이 키를 생성하여
/opt/acp-ant/gateway.env에 기록합니다(권한 600).
acp-ant라는 systemd 서비스로 등록하고, 127.0.0.1:8095만 리스닝하도록 설정합니다.
환경 변수를 사용하여 설치 위치와 포트를 변경할 수 있습니다: AGY_ROOT=/srv/acp-ant AGY_PORT=9000 ./install.sh; 서비스를 설치하고 싶지 않다면 --no-systemd 플래그를 추가하세요.
방식 2: 사용자 서비스 (sudo 불필요)
git clone https://github.com/czg86389-hub/ACP-Ant.git
cd ACP-Ant
./install.sh --user
현재 사용자의 홈 디렉토리(~/acp-ant)에 설치되며, 현재 사용자 계정의 서비스로 실행됩니다 (systemctl --user status acp-ant, 로그는 journalctl --user -u acp-ant -f에서 확인).
스크립트는 부가적으로 'SSH 연결 종료 후에도 계속 실행'(loginctl enable-linger) 기능을 활성화합니다. 일부 서버에서는 일반 사용자가 이 기능을 켤 수 없으므로, 스크립트가 관리자에게 sudo loginctl enable-linger 사용자이름을 한 번 실행해 달라고 안내할 것입니다.
주의: 반드시 SSH로 해당 사용자 계정에 직접 로그인하여 설치해야 합니다 (su 명령어를 사용하지 마세요). 그렇지 않으면 해당 사용자의 systemd에 접근할 수 없습니다.
방식 3: Docker
git clone https://github.com/czg86389-hub/ACP-Ant.git
cd ACP-Ant
docker compose up -d --build
...
- 최초 실행 시 키가 생성되고, 공식
agy가 데이터 디렉토리에 설치됩니다. 계정, 키, 패널 비밀번호, 통계 정보는 모두 ./data 폴더에 저장되므로, 컨테이너를 삭제하고 재구축해도 데이터가 유실되지 않습니다.
- 기본적으로 로컬 호스트(
127.0.0.1:8095)만 리스닝합니다. 도메인 바인딩이 필요하면 앞에 Caddy 또는 Nginx를 추가해야 합니다 (아래 참조). 포트 및 기타 설정은 docker-compose.yml 파일에서 수정할 수 있습니다.
- 명령줄을 통해 계정을 관리하려면:
docker compose exec acp-ant account.sh list를 사용합니다 (일반적으로 패널만으로 충분합니다).
GitHub Actions를 이용한 Docker 이미지 수동 배포
저장소는 Publish Docker image 워크플로우를 제공하며, 이를 통해 Docker Hub에 이미지를 수동으로 빌드하고 푸시할 수 있습니다. 동일한 이미지 태그가 linux/amd64와 linux/arm64 (ARM64 / aarch64) 모두를 지원합니다.
- Docker Hub에서 이미지 레지스트리를 생성하고 쓰기 권한을 가진 Access Token을 만듭니다.
- GitHub 저장소 Settings → Secrets and variables → Actions → New repository secret에 다음 내용을 추가합니다:
DOCKERHUB_USERNAME: Docker Hub 사용자 이름.
DOCKERHUB_TOKEN: 위에서 만든 Access Token.
- 워크플로우를 기본 브랜치에 커밋한 후, Actions → Publish Docker image → Run workflow로 이동하여 빌드할 브랜치를 선택하고 다음을 입력합니다:
| 매개변수 | 예시 | 설명 |
|---|
image_name | yourname/acp-ant | Docker Hub의 전체 이미지 이름이며, 소문자를 사용해야 합니다. 계정은 해당 레지스트리에 쓰기 권한이 있어야 합니다. |
version | 1.5.0 | yourname/acp-ant:1.5.0으로 배포되며, v1.5.0 등 유효한 Docker 태그도 지원합니다. |
latest | 체크 (기본값) | yourname/acp-ant:latest를 동시에 배포합니다. 체크 해제 시 버전 태그만 배포됩니다. |
배포가 성공하면 docker pull yourname/acp-ant:1.5.0을 실행할 수 있으며, Docker는 자동으로 현재 머신에 맞는 아키텍처를 선택합니다. 이 과정은 사용자가 Run workflow 버튼을 수동으로 클릭했을 때만 배포됩니다.
업데이트
- 웹 제어판은 6시간마다 GitHub의 CHANGELOG.md를 읽습니다(이 공개 파일만 읽으며, 데이터를 업로드하지는 않습니다). 새 버전이 있을 경우 상단에 알림을 표시하고 업데이트 내용을 나열합니다. '설정'에서 이 기능을 끌 수 있으며,
gateway.env 파일에 ACPANT_UPDATE_CHECK_HOURS=0을 작성하여 완전히 비활성화할 수도 있습니다.
- 방식 1, 방식 2 (
git clone 설치): 패널에서 '즉시 업데이트' 버튼을 누르기만 하면 됩니다. 패널이 최신 코드를 가져오고(pull), 필요한 종속성(dependency)을 설치한 후, 현재 처리 중인 요청이 완료되면 자동으로 재시작됩니다. 보통 1분 이내에 완료되며, 계정, 키, 패널 비밀번호 및 통계 정보는 모두 유지됩니다.
- 수동 업데이트: 소스 코드 디렉토리에서
git pull && ./install.sh을 실행합니다(사용자 서비스의 경우 --user 추가). Docker를 사용하는 경우: git pull && docker compose up -d --build를 사용합니다.
- 개인 포크 사용:
gateway.env 파일에 ACPANT_UPDATE_REPO=당신의 사용자명/ACP-Ant을 작성합니다.
웹 제어판
게이트웨이의 기본 페이지가 바로 제어판입니다. 로컬에서 접속할 경우 http://127.0.0.1:8095/를, 도메인을 바인딩한 후에는 https://당신의도메인/으로 접속합니다.
- 로그인: 관리자 비밀번호가 필요합니다. 최초 초기 비밀번호는 서버의
/opt/acp-ant/panel-initial-password.txt 파일(cat 명령어로 확인 가능)에 있으며, 패널 '설정'에서 본인의 비밀번호로 변경하면 이 파일은 자동으로 삭제됩니다. 또한 gateway.env 파일에 AGY_PANEL_PASSWORD=를 작성하여 지정할 수도 있습니다.
패널 비밀번호와 클라이언트가 사용하는 API 키는 별개입니다.
- 계정 카드: 상태(정상 / 비활성화됨 / Google 인증 필요 / 냉각 중 / 재로그인 필요), 프록시 및 아웃바운드 IP, 사용량 (Gemini 모델, Claude/GPT 모델, Gemini 4 Argon 세 그룹 각각에 대해 주간 및 5시간 잔여 백분율과 초기화 시간), 오늘과 최근 7일 동안의 성공/실패 횟수와 토큰 사용량, 최근 오류 기록이 표시됩니다.
- 스위치: 각 계정 오른쪽 상단에 스위치가 있습니다. 이 스위치를 끄면 해당 계정은 더 이상 호출되지 않습니다(파일
accounts/<이름>/disabled). 다시 켜면 즉시 복구됩니다.
- 버튼: 감지(실제 문장 전송 테스트; Google 인증 요구 시 직접 인증 링크 제공), 사용량 새로고침, 재로그인, 프록시 변경, 냉각 해제, 삭제 기능이 있습니다.
- 계정 추가 마법사: 이름과 프록시를 입력 → 아웃바운드 IP 자동 측정(동일 IP가 다른 계정에 의해 이미 사용된 경우 경고) → 버튼을 눌러 Google 로그인 페이지를 열고, 인증 코드 또는 착륙지 URL을 패널에 붙여넣기 → 로그인이 정상적으로 확인되면 자동으로 활성화됩니다. 이 과정에서 사용량은 읽히거나 테스트 메시지가 전송되지 않습니다. 사용량을 확인하려면 계정 카드에서 '사용량 새로고침'을 누르고, 실제 문장으로 테스트하려면 '감지'를 누릅니다. 로그인 과정 전체는 본인의 브라우저에서 완료되며, 패널은 인증 코드만 전달하고 저장하지 않습니다.
- refresh_token으로 로그인: 이미 해당 Google 계정을 가지고 있는 refresh_token(예: Antigravity 계정 관리 도구에서 내보낸 것)이 있다면, '계정 추가' 메뉴에서 Refresh Token 탭으로 이동하여 직접 붙여넣기만 하면 됩니다(단독 토큰 또는
refresh_token을 포함한 전체 JSON 모두 가능). 브라우저를 열 필요가 없습니다. 자세한 내용은 아래 'refresh_token으로 계정 추가하기'를 참고하세요.
- 연결 정보: 인터페이스 주소, 키 한 번에 복사 기능, 모든 모델 이름 목록, Codex / PI-Desktop / curl 설정 예시 등이 제공됩니다. 온라인 테스트에서는 모델을 선택하여 문장 하나를 전송할 수 있습니다. 최근 이벤트 기록에는 계정 변경, 오류 발생, 스위치 상태 등의 기록이 남습니다.
- 버전 업데이트: 상단에 새 버전과 업데이트 내용이 표시됩니다. 'git clone'으로 설치한 경우의 '즉시 업데이트' 버튼을 누르면 자동으로 가져오기(pull), 설치, 재시작이 진행됩니다(상단의 '업데이트' 참고).
- 동시 요청 수: 홈 화면에는 '처리 중 / 최대 동시 처리 가능 수'와 대기열 수가 표시됩니다. '설정'에서 각 계정이 동시에 몇 개를 처리할지 수정할 수 있습니다(1~10, 기본값 3). 저장하면 즉시 적용됩니다.
- 자동 순찰 (유지): 기본적으로 활성화된 모든 계정에 대해 6시간마다 사용량을 읽어옵니다. 사용량은 소모되지 않습니다. 이 과정에서 Google 로그인 토큰을 새로고침하고, 프록시 및 로그인이 정상인지 확인합니다. 로그인이 만료되면 '재로그인 필요'로 표시됩니다. 선택적으로 매일 문장 하나를 전송하여 'Google 인증 필요' 상태를 미리 감지할 수 있습니다(매일 아주 적은 사용량이 소모됨).
유지보수 관련: Google의 로그인 토큰은 공식 agy가 사용할 때마다 자동으로 갱신되므로, 장기간 사용하지 않아도 일반적으로 만료되지 않습니다. 따라서 엄밀히 말해 유지보수는 필수적이지 않습니다.
순찰의 의미는 요청이 실제로 발생했을 때 알게 되는 것이 아니라, 프록시 장애나 로그인 만료 같은 문제를 미리 발견하는 데 있습니다.
패널 인터페이스는 모두 /panel/api/ 아래에 있습니다. 세션 쿠키(HttpOnly, SameSite=Strict)를 사용하며, 수정 관련 요청에는 X-ACP-Panel: 1 헤더가 필요합니다. 로그인 실패 시 IP 기반으로 횟수 제한이 적용됩니다.
계정 추가하기 (명령줄 방식)
패널에서 계정을 추가할 수 있지만, 명령줄을 선호하는 경우 스크립트를 사용할 수도 있습니다. 각 계정에 이름(문자, 숫자 및 - _ . @ + 사용 가능하며 Google 이메일도 직접 사용 가능)을 지정합니다. 예를 들어 g1과 같이 설정합니다:
/opt/acp-ant/account.sh add g1
- 프록시 주소 입력 (입력 시 화면에 표시되지 않으며, 붙여넣기 후 바로 엔터): 예를 들어
socks5://사용자명:비밀번호@1.2.3.4:1080과 같이 입력합니다. 스크립트는 이 프록시의 출구 IP와 국가를 테스트합니다.
- Google 로그인: 화면에 인증 URL이 나타납니다. 이를 본인 컴퓨터의 브라우저에 복사하여 열고, 해당 계정을 선택한 후 동의합니다. 브라우저는 마지막에 접근할 수 없는
localhost 주소로 이동하거나 일련의 인증 코드를 표시합니다. 이 전체 URL 또는 인증 코드를 터미널로 다시 복사하여 붙여넣고 엔터를 누릅니다.
- 「로그인 성공, 사용 가능한 모델: …」이 표시되면 됩니다.
도중에 종료해도 괜찮습니다. add g1을 다시 실행하면 중단된 지점부터 이어서 진행됩니다. 다른 명령어:
| 명령어 | 역할 |
|---|
account.sh list | 모든 계정, 프록시(호스트와 포트만 표시), 출구 IP, 로그인 상태 및 사용 가능한 모델 목록을 나열합니다 |
| ... | |
프록시는 선택 사항입니다 (1.4.0 버전부터): 패널에서 비워두거나, account.sh add 실행 시 엔터를 치면 해당 계정은 서버 본체 네트워크를 사용합니다. 모든 계정에 강제로 프록시를 적용하려면, gateway.env 파일에 AGY_REQUIRE_PROXY=1을 작성해야 합니다 (account.sh의 환경 변수도 동일하게 설정). | |
refresh_token으로 계정 추가하기
이미 특정 Google 계정의 refresh_token이 있는 경우, 브라우저 로그인을 거치지 않을 수 있습니다:
- 패널: 계정 추가 → 「Refresh Token」 탭으로 이동 → 이름 입력 (프록시 선택 사항) → 붙여넣기 → 「확인 추가」; 기존 계정의 경우 「재로그인」을 누르면 동일하게 두 개의 탭이 나타납니다.
- 명령줄:
/opt/acp-ant/account.sh token g1 실행 후, (화면에 표시되지 않으며) 붙여넣기하고 엔터를 누릅니다.
요구 사항 및 방법:
- Antigravity로 로그인하여 얻은 refresh_token만 사용 가능합니다 (Antigravity 에디터 또는 다양한 Antigravity 계정 관리 도구에서 내보낸 것). 일반적으로
1//로 시작합니다. Google의 refresh_token은 이를 발급한 프로그램과 바인딩되므로, Gemini CLI 등 다른 프로그램의 refresh_token은 여기서 사용할 수 없습니다.
- 게이트웨이는 이 내용을 해당 계정 디렉터리 내부의 공식
agy 로그인 파일(accounts/<이름>/.gemini/antigravity-cli/antigravity-oauth-token, 권한 600)에 작성합니다. 형식은 브라우저 로그인 후와 동일하며, 이후 agy가 자체적으로 새로운 액세스 토큰을 교체하고 계정 이메일을 읽어옵니다. 게이트웨이는 Google의 클라이언트 키를 가지고 있지 않으며 Google에 직접 요청하지도 않습니다.
- 작성 완료 후 즉시 테스트합니다: 사용할 수 없거나(만료, 취소됨, Antigravity가 아닌 경우, 프록시 연결 불가) 문제가 있으면 원래 로그인 파일을 복구하며, 계정에는 영향을 주지 않습니다.
- refresh_token은 표시되지 않고, 로그로 기록되지 않으며, 패널에 반환되지 않습니다. 로그인 성공 시 계정 이메일만 표시됩니다. 동일한 Google 계정이 다른 계정에 이미 사용된 경우 알림이 옵니다.
- refresh_token으로 로그인할 때도 해당 계정의 프록시를 따릅니다. 하나의 refresh_token은 이 Google 계정의 장기적인 로그인을 의미하므로, 비밀번호처럼 보관해야 합니다.
Agent 및 애플리케이션 연결
어떤 Agent를 사용하든 다음 세 가지 정보를 입력해야 합니다:
- 주소:
http://127.0.0.1:8095/v1 (Anthropic 형식의 클라이언트는 http://127.0.0.1:8095를 사용합니다)
- 키:
grep AGY_GATEWAY_KEY /opt/acp-ant/gateway.env에서 확인되는 문자열
- 모델명:
gemini-3.8-flash-medium을 권장합니다 (다른 모델은 아래 「모델명」 참고)
Agent는 본인 컴퓨터에, 게이트웨이는 서버에 있을 때, 가장 간단하고 안전한 방법은 SSH 터널링입니다. 본인 컴퓨터에서 다음 명령어를 실행하고 창을 열어둔 상태를 유지하며, 주소는 여전히 http://127.0.0.1:8095/v1로 입력합니다:
ssh -N -L 8095:127.0.0.1:8095 사용자명@서버
포트 8095를 공용 인터넷에 직접 노출하지 마십시오. 정말로 공용 인터넷에서 접근해야 한다면, Nginx / Caddy를 사용하여 HTTPS 리버스 프록시를 사용하십시오.
테스트 완료
| Agent | 인터페이스 | 결과 |
|---|
| Codex CLI 0.134 | OpenAI 응답 | ✅ 성공적으로 작동함: 쉘 도구를 사용해 파일을 생성하고 다시 읽어오는 과정, 15초 소요 |
| ... | | |
Codex CLI (~/.codex/config.toml):
model_provider = "acpant"
model = "gemini-3.8-flash-medium"
...
그런 다음 export ACPANT_KEY=당신의 게이트웨이 키를 실행하고, codex를 실행합니다. 새 버전의 Codex는 더 이상 wire_api = "chat"을 지원하지 않으며, 반드시 responses를 사용해야 합니다.
Claude Code에 대하여: Google의 Antigravity 서비스 서버는 Claude Code 특징이 포함된 요청을 거부합니다. Claude Code는 요청할 때마다 x-anthropic-billing-header와 고정된 신원 소개 문구를 한 줄씩 첨부하며, 서버 측은 이 두 가지를 감지하면 계정 할당량과는 무관하게 RESOURCE_EXHAUSTED (429)을 반환합니다. 이는 Google 측의 의도적인 제한이며, ACP-Ant는 이를 우회하지 않습니다(우회 시 계정 정지 위험이 있습니다). 게이트웨이는 2~3초 내에 이를 429로 처리하여 반환하며, 시스템이 멈추지는 않습니다.
OpenAI 호환 인터페이스를 사용하면 됩니다 (인터페이스는 테스트 완료되었으나, 소프트웨어 자체는 개별적으로 실측하지 않았습니다)
| 소프트웨어 | 설정 방법 |
|---|
OpenAI SDK, LangChain (ChatOpenAI), LlamaIndex, AutoGen, CrewAI 등 | base_url에 주소를, api_key에 키를, model에 모델명을 기입합니다 |
| ... | |
| Python 예시 (도구 포함): | |
from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:8095/v1", api_key="당신의 게이트웨이 키")
r = client.chat.completions.create(
...
직접 검증: python3 /opt/acp-ant/agent_test.py (세 가지 인터페이스의 도구 호출을 모두 테스트합니다. 약 1~2분 소요).
도구 호출은 어떻게 구현되나요
ACP 프로토콜 자체는 Antigravity가 자신 측의 도구를 호출하게만 할 수 있으며, 도구 호출 권한을 사용자의 Agent에게 넘겨줄 수는 없습니다. 따라서 게이트웨이는 Agent의 도구 목록(이름, 설명, 매개변수 형식)을 시스템 프롬프트에 작성하고, 모델이 <tool_calls>[...]</tool_calls>와 같은 형식으로 호출을 제안하도록 규정합니다. 게이트웨이가 이 내용을 표준 도구 호출로 파싱하여 Agent에게 반환하며, Agent가 되돌려준 도구 결과는 다시 대화 내용에 기록됩니다.
- Gemini 3.8 Flash는 이러한 방식으로 성공률이 매우 높습니다 (위의 테스트 모두 통과).
- 모델은 가끔 형식을 따르지 않을 수 있습니다. 이 경우 게이트웨이는 원문을 일반 답변으로 간주하여 반환하며, Agent는 일반적으로 재시도하거나 계속 진행합니다.
- 스트리밍 출력 시, 일반 텍스트는 평소처럼 실시간으로 출력되며, 도구 호출 부분은 작성 완료 후 한 번에 전송됩니다.
AI Studio 두 번째 경로 (선택 사항, 1.5.0부터)
Antigravity 외에도 게이트웨이는 Google AI Studio를 두 번째 출처로 사용할 수 있으며, 이는 오픈 소스 프로젝트 AIStudio2API에서 제공합니다. 동일한 주소와 동일한 키를 사용합니다:
- 일반 모델명 (예:
gemini-3.8-flash-medium) → Antigravity (변경 없음)
aistudio/<모델명> (예: aistudio/gemini-3.8-flash, aistudio/gemini-4-hydrogen) → AI Studio, 모델명을 원문 그대로 사용하며 다른 모델로 은밀하게 변경되지 않습니다.
활성화 (Docker 필요):
/opt/acp-ant/aistudio.sh setup
이후 웹 제어판에서 '+ AI Studio 연결'을 누르고 Google 이메일을 기입한 뒤, 패널에 표시되는 서버 브라우저에서 해당 계정으로 로그인합니다 (최초 접속 시 약 1.2 GB의 브라우저가 다운로드됩니다). 이 이메일로 로그인하지 않으면 거부됩니다.
⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.
- 서버 브라우저에 로그인해야 하는 이유: Windows 버전 Chrome은 현재 Google 로그인을 이 컴퓨터(장치 바인딩 세션)에 연결합니다. Chrome에서 복사된 쿠키는 해당 컴퓨터가 갱신되지 않으면 약 2시간 후에 만료됩니다. 서버의 브라우저 로그인은 어떤 컴퓨터에도 바인딩되지 않아, 실제 테스트 결과 9시간 이상 연속으로 사용 가능했습니다.
- 이메일별 매칭: Antigravity 계정의 실제 이메일(공식 CLI에 기록된)과 AI Studio 계정 이메일이 동일하면 하나의 카드에 표시됩니다. 해당 이메일에 Antigravity 계정이 있는 경우, AI Studio는 자동으로 같은 프록시 출구를 사용하며, 언어와 시간대는 출구 지역에 따라 설정됩니다.
- 계정 지정: 요청 헤더
X-ACP-Account: <계정명 또는 이메일>을 사용하면 두 서비스 모두 인식합니다. 지정된 계정이 대응되는 출처가 없으면 오류를 발생시키고 다른 이메일로 변경되지 않습니다. 이 헤더 없이 사용할 경우 평소대로 순환됩니다.
- 할당량(Quota): Google은 AI Studio의 남은 할당량을 제공하지 않으며, 패널에는 「남은 미지정」으로 표시됩니다. 또한 본 게이트웨어가 기록한 오늘의 호출 횟수와 Token 수, 그리고 Google에 의해 제한된 모델과 복구 시간이 별도로 표시되며, 이는 Antigravity의 백분율과 합산되지 않습니다.
- 비활성화:
/opt/acp-ant/aistudio.sh remove를 사용합니다 (데이터를 동시에 삭제하려면 --purge 추가). Docker 방식으로 설치된 게이트웨어는 AIStudio2API를 직접 실행해야 하며, ACPANT_STUDIO_CONFIG 환경 변수를 사용하여 base_url, api_key, admin_password를 포함하는 JSON 파일을 지정해야 합니다.
- AIStudio2API는 서드파티(third-party) 프로젝트이므로, 사용 전에 설명서와 라이선스를 읽어보십시오. Google 서비스를 자동화하여 사용하는 것은 해당 약관을 위반할 수 있으며, 위험은 사용자 본인이 부담합니다.
모델 이름