다중 계정 설정: 쿼터 풀링 및 로드 밸런싱

학습 완료 후 할 수 있는 것

다수의 Google 계정을 추가하여 총 쿼터 한도 향상
듀얼 쿼터 시스템을 이해하고 Antigravity 및 Gemini CLI 쿼터 풀을 효과적으로 활용
계정 수와 사용 시나리오에 따라 적절한 로드 밸런싱 전략 선택
다중 계정 구성에서 일반적인 문제 해결

현재 직면한 문제

단일 계정 사용 시 다음과 같은 문제에 직면할 수 있습니다:

빈번한 429 속도 제한 오류 발생으로 쿼터 복구 대기 필요
개발/테스트 시나리오에서 동시 요청이 너무 많아 하나의 계정으로 처리 불가
Gemini 3 Pro 또는 Claude Opus 모델의 쿼터 소진 후 다음 날까지 대기
다중 OpenCode 인스턴스 또는 oh-my-opencode 하위 에이전트를 병렬로 실행할 때 계정 간 경쟁

이 방법을 사용해야 할 때

다중 계정 구성은 다음 시나리오에 적합합니다:

시나리오	권장 계정 수	이유
개인 개발	2-3개	백업 계정으로 중단 방지
팀 협업	3-5개	요청 분산, 경쟁 감소
고빈도 API 호출	5개 이상	로드 밸런싱, 처리량 극대화
병렬 에이전트	3개 이상 + PID 오프셋	각 에이전트가 독립적인 계정 사용

사전 확인

본 튜토리얼을 시작하기 전에 다음을 완료했는지 확인하세요:

✅ opencode-antigravity-auth 플러그인 설치
✅ OAuth 인증 성공 및 첫 번째 계정 추가
✅ Antigravity 모델을 사용하여 요청 발신 가능

빠른 설치 튜토리얼 | 첫 로그인 튜토리얼

핵심 개념

다중 계정 구성의 핵심 메커니즘:

쿼터 풀링: 각 Google 계정에는 독립적인 쿼터가 있으며, 여러 계정의 쿼터를 합산하여 더 큰 총 풀 형성
로드 밸런싱: 플러그인이 자동으로 사용 가능한 계정을 선택하고, 속도 제한 시 다음 계정으로 전환
듀얼 쿼터 시스템 (Gemini 전용): 각 계정은 Antigravity 및 Gemini CLI 두 개의 독립적인 쿼터 풀에 액세스 가능
지능형 복구: 속도 제한 중복 제거(2초 윈도우) + 지수 백오프, 무효 재시도 방지

쿼터 계산 예시:

각 계정의 Claude 쿼터가 분당 1000요청이라고 가정:

계정 수	이론적 총 쿼터	실제 사용 가능(캐시 고려)
1	1000/분	1000/분
3	3000/분	~2500/분 (sticky 전략)
5	5000/분	~4000/분 (round-robin)

💡 왜 sticky 전략의 사용 가능 쿼터가 더 낮나요?
sticky 전략은 속도 제한까지 동일한 계정을 계속 사용하여 다른 계정의 쿼터를 유휴 상태로 만듭니다. 하지만 이렇게 하면 Anthropic의 프롬프트 캐시가 유지되어 응답 속도가 향상됩니다.

따라하기

1단계: 두 번째 계정 추가

이유 두 번째 계정을 추가하면 주 계정이 속도 제한에 도달할 때 플러그인이 자동으로 백업 계정으로 전환하여 요청 실패를 방지합니다.

작업

OAuth 로그인 명령 실행:

bash

opencode auth login

이미 계정이 하나 있는 경우 다음 프롬프트가 표시됩니다:

1 account(s) saved:
  1. [email protected]

(a)dd new account(s) or (f)resh start? [a/f]:

a를 입력하고 Enter를 누르면 브라우저가 자동으로 Google 인증 페이지를 엽니다.

보여야 할 내용:

브라우저가 Google OAuth 인증 페이지 열기
두 번째 Google 계정 선택 또는 로그인
인증 동의 후 터미널에 표시:

Account added successfully!

2 account(s) saved:
  1. [email protected]
  2. [email protected]

TIP

브라우저가 자동으로 열리지 않으면 터미널에 표시된 OAuth URL을 복사하여 수동으로 브라우저에 붙여넣으세요.

2단계: 다중 계정 상태 확인

이유 계정이 올바르게 추가되고 사용 가능한지 확인합니다.

작업

계정 저장 파일 보기:

bash

cat ~/.config/opencode/antigravity-accounts.json

보여야 할 내용:

json

{
  "version": 3,
  "accounts": [
    {
      "email": "[email protected]",
      "refreshToken": "1//0abc...",
      "projectId": "project-id-123",
      "addedAt": 1737609600000,
      "lastUsed": 1737609600000
    },
    {
      "email": "[email protected]",
      "refreshToken": "1//0xyz...",
      "addedAt": 1737609700000,
      "lastUsed": 1737609700000
    }
  ],
  "activeIndex": 0,
  "activeIndexByFamily": {
    "claude": 0,
    "gemini": 0
  }
}

보안 경고

antigravity-accounts.json에는 OAuth 리프레시 토큰이 포함되어 있어 비밀번호 파일과 동일한 수준의 보안이 필요합니다. 버전 관리 시스템에 커밋하지 마세요.

3단계: 계정 전환 테스트

이유 다중 계정 로드 밸런싱이 정상 작동하는지 확인합니다.

작업

여러 동시 요청을 보내어 속도 제한 트리거:

bash

# macOS/Linux
for i in {1..10}; do
  opencode run "Test $i" --model=google/antigravity-claude-sonnet-4-5 &
done
wait

# Windows PowerShell
1..10 | ForEach-Object {
  Start-Process -FilePath "opencode" -ArgumentList "run","Test $_","--model=google/antigravity-claude-sonnet-4-5"
}

보여야 할 내용:

처음 N개 요청이 계정 1 사용([email protected])
429 발생 후 자동으로 계정 2로 전환([email protected])
알림이 활성화된 경우 "Switched to account 2" 토스트 메시지 표시

계정 전환 알림

quiet_mode: false(기본값)으로 설정된 경우 플러그인이 계정 전환 알림을 표시합니다. 첫 전환 시 이메일 주소 표시, 이후 계정 인덱스만 표시.

4단계: 듀얼 쿼터 시스템 구성 (Gemini 전용)

이유 듀얼 쿼터 폴백을 활성화하면 Antigravity 쿼터가 소진될 때 플러그인이 동일 계정의 Gemini CLI 쿼터를 자동으로 시도하여 계정 전환 없이 계속 사용 가능.

작업

플러그인 구성 파일 편집:

bash

# macOS/Linux
nano ~/.config/opencode/antigravity.json

# Windows
notepad %APPDATA%\opencode\antigravity.json

다음 구성 추가:

json

{
  "$schema": "https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/main/assets/antigravity.schema.json",
  "quota_fallback": true
}

파일 저장 후 OpenCode 재시작.

보여야 할 내용:

Gemini 모델 사용 시 플러그인이 Antigravity 쿼터를 우선적으로 사용
Antigravity가 429를 반환하면 동일 계정의 Gemini CLI 쿼터로 자동 전환
두 쿼터 모두 제한에 도달한 경우 다음 계정으로 전환

듀얼 쿼터 vs 다중 계정

듀얼 쿼터: 동일 계정의 두 개의 독립적인 쿼터 풀(Antigravity + Gemini CLI)
다중 계정: 여러 계정의 쿼터 풀 중첩
모범 사례: 다중 계정을 추가하기 전에 먼저 듀얼 쿼터 활성화

5단계: 계정 선택 전략 선택

이유 다른 계정 수와 사용 시나리오에 따라 서로 다른 전략이 필요하며, 최적의 성능을 얻으려면 적절한 전략 선택이 필수적.

작업

antigravity.json에서 전략 구성:

json

{
  "account_selection_strategy": "hybrid"
}

계정 수에 따라 선택:

계정 수	권장 전략	구성 값	이유
1	sticky	`"sticky"`	프롬프트 캐시 유지
2-5	hybrid	`"hybrid"`	처리량과 캐시 간 균형
5+	round-robin	`"round-robin"`	처리량 극대화

전략 상세 설명:

sticky (단일 계정 기본값): 속도 제한에 도달할 때까지 동일한 계정을 계속 사용, 개별 개발 세션에 적합
round-robin: 각 요청을 다음 계정으로 순환, 처리량을 극대화하지만 캐시 희생
hybrid (다중 계정 기본값): 건강 점수 + 토큰 버킷 + LRU를 기반으로 한 종합 의사 결정

보여야 할 내용:

hybrid 전략 사용 시 플러그인이 자동으로 현재 최적의 계정 선택
round-robin 전략 사용 시 요청이 모든 계정에 균등하게 분산
sticky 전략 사용 시 동일한 세션이 항상 동일한 계정 사용

6단계: PID 오프셋 활성화 (병렬 에이전트 시나리오)

이유 여러 OpenCode 인스턴스 또는 oh-my-opencode 병렬 에이전트를 실행할 때, 다른 프로세스가 동일한 계정을 선택하여 경쟁이 발생할 수 있음.

작업

antigravity.json에 추가:

json

{
  "pid_offset_enabled": true
}

저장 후 OpenCode 재시작.

보여야 할 내용:

다른 프로세스(다른 PID)가 다른 계정 인덱스에서 시작
병렬 에이전트 간의 계정 경쟁 감소
전체 처리량 향상

PID 오프셋 작동 방식

PID 오프셋은 프로세스 ID를 계정 오프셋에 매핑합니다.

PID 100 → 오프셋 0 → 계정 0에서 시작
PID 101 → 오프셋 1 → 계정 1에서 시작
PID 102 → 오프셋 2 → 계정 2에서 시작

체크포인트 ✅

위의 단계를 완료한 후, 다음을 수행할 수 있어야 합니다:

[ ] opencode auth login을 통해 여러 Google 계정 추가
[ ] antigravity-accounts.json에서 여러 계정 레코드 확인
[ ] 속도 제한 발생 시 플러그인이 자동으로 다음 계정으로 전환
[ ] Gemini 모델에 듀얼 쿼터 폴백 활성화
[ ] 계정 수에 따라 적절한 계정 선택 전략 선택
[ ] 병렬 에이전트 시나리오에서 PID 오프셋 활성화

문제 해결

모든 계정이 속도 제한됨

증상: 모든 계정이 429 오류를 표시하고 요청을 계속할 수 없음

원인: 쿼터 소진 또는 동시 요청 과다

해결 방법:

속도 제한이 자동으로 재설정될 때까지 대기(일반적으로 1-5분)
장기적으로 문제가 발생하는 경우 더 많은 계정 추가
구성의 max_rate_limit_wait_seconds를 확인하고 적절한 대기 상한 설정

계정 전환이 너무 잦음

증상: 각 요청마다 계정을 전환하여 동일한 계정을 사용하지 않음

원인: 전략 선택 부적절 또는 건강 점수 비정상

해결 방법:

전략을 sticky로 변경
health_score 구성을 확인하고 min_usable 및 rate_limit_penalty 조정
계정이 건강하지 않다고 표시되는 빈번한 429 오류가 없는지 확인

Gemini CLI 권한 오류(403)

증상: Gemini CLI 모델 사용 시 Permission denied 오류 반환

원인: 계정에 유효한 Project ID가 없음

해결 방법:

각 계정에 대해 수동으로 projectId 추가:

json

{
  "accounts": [
    {
      "email": "[email protected]",
      "refreshToken": "...",
      "projectId": "your-project-id"
    }
  ]
}

Google Cloud Console에서 Gemini for Google Cloud API가 활성화되어 있는지 확인

토큰 무효(invalid_grant)

증상: 계정이 자동으로 제거되고 invalid_grant 오류가 표시됨

원인: Google 계정 비밀번호 변경, 보안 이벤트 또는 토큰 만료

해결 방법:

무효한 계정을 삭제하고 다시 인증:

bash

rm ~/.config/opencode/antigravity-accounts.json
opencode auth login

빈번하게 발생하는 경우 더 안정적인 Google 계정 사용 고려

수업 요약

다중 계정 구성은 총 쿼터 한도와 시스템 안정성을 향상시킬 수 있음
계정 추가는 매우 간단하며 opencode auth login을 반복 실행하면 됨
듀얼 쿼터 시스템은 각 Gemini 계정의 사용 가능한 쿼터를 두 배로 증가시킴
계정 선택 전략은 계정 수와 사용 시나리오에 따라 조정되어야 함
PID 오프셋은 병렬 에이전트 시나리오에서 매우 중요함

다음 수업 예고

다음 수업에서는 **계정 선택 전략**을 배웁니다.
학습 내용:
sticky, round-robin, hybrid 세 가지 전략의 상세한 작동 원리
시나리오에 따른 최적의 전략 선택 방법
건강 점수 및 토큰 버킷 튜닝 방법

부록: 소스 코드 참조

소스 코드 위치 보기

업데이트 날짜: 2026-01-23

기능	파일 경로	라인 번호
AccountManager 클래스	`src/plugin/accounts.ts`	174-250
로드 밸런싱 전략	`src/plugin/rotation.ts`	전체
구성 스키마	`src/plugin/config/schema.ts`	전체
계정 저장	`src/plugin/storage.ts`	전체

주요 상수:

상수명	값	설명
`QUOTA_EXHAUSTED_BACKOFFS`	`[60000, 300000, 1800000, 7200000]`	쿼터 소진 백오프 시간(1분→5분→30분→2시간)
`RATE_LIMIT_EXCEEDED_BACKOFF`	`30000`	속도 제한 백오프 시간(30초)
`MIN_BACKOFF_MS`	`2000`	최소 백오프 시간(2초)

주요 함수:

calculateBackoffMs(reason, consecutiveFailures, retryAfterMs): 백오프 지연 시간 계산
getQuotaKey(family, headerStyle, model): 쿼터 키 생성(모델 수준 속도 제한 지원)
isRateLimitedForQuotaKey(account, key): 특정 쿼터 키의 속도 제한 여부 확인
selectHybridAccount(accounts, family): hybrid 전략의 계정 선택 로직

구성 항목 (schema.ts에서):

구성 항목	유형	기본값	설명
`account_selection_strategy`	enum	`"hybrid"`	계정 선택 전략
`quota_fallback`	boolean	`false`	Gemini 듀얼 쿼터 폴백 활성화
`pid_offset_enabled`	boolean	`false`	PID 오프셋 활성화
`switch_on_first_rate_limit`	boolean	`true`	첫 번째 속도 제한 시 즉시 전환

다중 계정 설정: 쿼터 풀링 및 로드 밸런싱 ​

학습 완료 후 할 수 있는 것 ​

현재 직면한 문제 ​

이 방법을 사용해야 할 때 ​

핵심 개념 ​

따라하기 ​

1단계: 두 번째 계정 추가 ​

2단계: 다중 계정 상태 확인 ​

3단계: 계정 전환 테스트 ​

4단계: 듀얼 쿼터 시스템 구성 (Gemini 전용) ​

5단계: 계정 선택 전략 선택 ​

6단계: PID 오프셋 활성화 (병렬 에이전트 시나리오) ​

체크포인트 ✅ ​

문제 해결 ​

모든 계정이 속도 제한됨 ​

계정 전환이 너무 잦음 ​

Gemini CLI 권한 오류(403) ​

토큰 무효(invalid_grant) ​

수업 요약 ​

다음 수업 예고 ​

부록: 소스 코드 참조 ​

다중 계정 설정: 쿼터 풀링 및 로드 밸런싱

학습 완료 후 할 수 있는 것

현재 직면한 문제

이 방법을 사용해야 할 때

핵심 개념

따라하기

1단계: 두 번째 계정 추가

2단계: 다중 계정 상태 확인

3단계: 계정 전환 테스트

4단계: 듀얼 쿼터 시스템 구성 (Gemini 전용)

5단계: 계정 선택 전략 선택

6단계: PID 오프셋 활성화 (병렬 에이전트 시나리오)

체크포인트 ✅

문제 해결

모든 계정이 속도 제한됨

계정 전환이 너무 잦음

Gemini CLI 권한 오류(403)

토큰 무효(invalid_grant)

수업 요약

다음 수업 예고

부록: 소스 코드 참조