계정 선택 전략: sticky, round-robin, hybrid 모범 사례

학습 목표

Google 계정 수와 사용 시나리오에 따라 적합한 계정 선택 전략을 선택하고 설정합니다:

• 1개 계정 → sticky 전략으로 프롬프트 캐시 유지
• 2-3개 계정 → hybrid 전략으로 지능적 요청 분산
• 4개 이상 계정 → round-robin 전략으로 처리량 극대화

"모든 계정이 속도 제한에 걸렸는데 실제 할당량은 남아있는" 난감한 상황을 방지합니다.

현재 겪고 있는 문제

여러 Google 계정을 설정했지만:

• 할당량 활용률을 극대화하려면 어떤 전략을 사용해야 할지 모르겠음
• 모든 계정이 속도 제한에 걸렸는데 특정 계정의 할당량은 아직 남아있는 경우가 자주 발생
• 병렬 에이전트 시나리오에서 여러 하위 프로세스가 항상 같은 계정을 사용하여 속도 제한 발생

핵심 개념

계정 선택 전략이란

Antigravity Auth 플러그인은 여러 Google 계정 간에 모델 요청을 분배하는 방법을 결정하는 세 가지 계정 선택 전략을 지원합니다:

전략	동작	적용 시나리오
sticky	현재 계정이 속도 제한에 걸리지 않는 한 계속 같은 계정 사용	단일 계정, 프롬프트 캐시 필요 시
round-robin	매 요청마다 다음 사용 가능한 계정으로 순환	다중 계정, 처리량 극대화
hybrid(기본값)	건강 점수 + Token bucket + LRU를 결합한 지능적 선택	2-3개 계정, 성능과 안정성 균형

왜 전략이 필요한가요?

Google은 각 계정에 속도 제한을 적용합니다. 계정이 하나뿐이면 빈번한 요청으로 쉽게 속도 제한에 걸립니다. 다중 계정은 로테이션이나 지능적 선택을 통해 요청을 분산시켜 단일 계정의 과도한 할당량 소비를 방지할 수 있습니다.

세 가지 전략의 작동 원리

1. Sticky 전략 (고정)

핵심 로직: 속도 제한에 걸릴 때까지 현재 계정을 유지합니다.

장점:

• 프롬프트 캐시 유지, 동일 컨텍스트에서 더 빠른 응답
• 계정 사용 패턴이 안정적이어서 위험 감지 트리거 가능성 낮음

단점:

• 다중 계정 할당량 활용 불균형
• 속도 제한 복구 전까지 다른 계정 사용 불가

적용 시나리오:

• 계정이 하나뿐인 경우
• 프롬프트 캐시 중시 (예: 장기 대화)

2. Round-Robin 전략 (순환)

핵심 로직: 매 요청마다 다음 사용 가능한 계정으로 순환하며 반복 사용합니다.

장점:

• 가장 균형 잡힌 할당량 활용
• 동시 처리량 극대화
• 고동시성 시나리오에 적합

단점:

• 계정 건강 상태를 고려하지 않아 속도 제한에서 막 복구된 계정을 선택할 수 있음
• 프롬프트 캐시 활용 불가

적용 시나리오:

• 4개 이상의 계정
• 최대 처리량이 필요한 배치 작업
• 병렬 에이전트 시나리오 (pid_offset_enabled와 함께 사용)

3. Hybrid 전략 (혼합, 기본값)

핵심 로직: 세 가지 요소를 종합적으로 고려하여 최적의 계정을 선택합니다:

점수 공식:

총점 = 건강 점수 × 2 + Token 점수 × 5 + 신선도 점수 × 0.1

• 건강 점수 (0-200): 계정의 성공/실패 이력 기반

  • 성공 요청: +1점
  • 속도 제한: -10점
  • 기타 실패 (인증, 네트워크): -20점
  • 초기값: 70점, 최소 0점, 최대 100점
  • 매시간 2점 회복 (사용하지 않아도)

• Token 점수 (0-500): Token bucket 알고리즘 기반

  • 각 계정 최대 50 token, 초기 50 token
  • 분당 6 token 회복
  • 요청당 1 token 소비
  • Token 점수 = (현재 token / 50) × 100 × 5

• 신선도 점수 (0-360): 마지막 사용 이후 경과 시간 기반

  • 마지막 사용 이후 시간이 길수록 점수가 높음
  • 최대 3600초 (1시간) 후 최대값 도달

장점:

• 건강도가 낮은 계정을 지능적으로 회피
• Token bucket으로 집중 요청으로 인한 속도 제한 방지
• LRU (가장 오래 미사용 우선)로 계정에 충분한 휴식 시간 제공
• 성능과 안정성을 종합적으로 고려

단점:

• 알고리즘이 복잡하여 round-robin만큼 직관적이지 않음
• 2개 계정일 때 효과가 뚜렷하지 않음

적용 시나리오:

• 2-3개 계정 (기본 전략)
• 할당량 활용률과 안정성의 균형 필요 시

전략 선택 빠른 참조표

README와 CONFIGURATION.md의 권장 사항 기준:

설정	권장 전략	이유
1개 계정	sticky	로테이션 불필요, 프롬프트 캐시 유지
2-3개 계정	hybrid(기본값)	지능적 로테이션, 과도한 속도 제한 방지
4개 이상 계정	round-robin	처리량 극대화, 가장 균형 잡힌 할당량 활용
병렬 에이전트	round-robin + pid_offset_enabled: true	다른 프로세스가 다른 계정 사용

🎒 시작 전 준비

사전 확인

다음을 완료했는지 확인하세요:

• [x] 다중 계정 설정 (최소 2개 Google 계정)
• [x] 이중 할당량 시스템 이해

따라하기

1단계: 현재 설정 확인

왜 필요한가 현재 설정 상태를 먼저 파악하여 중복 수정을 방지합니다.

작업

플러그인 설정 파일을 확인합니다:

cat ~/.config/opencode/antigravity.json

예상 결과:

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

파일이 없으면 플러그인은 기본 설정을 사용합니다 (account_selection_strategy = "hybrid").

2단계: 계정 수에 따른 전략 설정

왜 필요한가 계정 수에 따라 적합한 전략이 다르며, 잘못된 전략 선택은 할당량 낭비나 빈번한 속도 제한을 초래할 수 있습니다.

1개 계정 - Sticky 전략

cat > ~/.config/opencode/antigravity.json << 'EOF'
{
  "$schema": "https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/main/assets/antigravity.schema.json",
  "account_selection_strategy": "sticky"
}
EOF

2-3개 계정 - Hybrid 전략(기본값)

cat > ~/.config/opencode/antigravity.json << 'EOF'
{
  "$schema": "https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/main/assets/antigravity.schema.json",
  "account_selection_strategy": "hybrid"
}
EOF

4개 이상 계정 - Round-Robin 전략

cat > ~/.config/opencode/antigravity.json << 'EOF'
{
  "$schema": "https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/main/assets/antigravity.schema.json",
  "account_selection_strategy": "round-robin"
}
EOF

예상 결과: 설정 파일이 해당 전략으로 업데이트됩니다.

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

왜 필요한가 oh-my-opencode 등의 플러그인으로 병렬 에이전트를 생성하면 여러 하위 프로세스가 동시에 요청을 보낼 수 있습니다. 기본적으로 모두 같은 시작 계정에서 선택을 시작하여 계정 경쟁과 속도 제한이 발생합니다.

작업

설정을 수정하여 PID 오프셋을 추가합니다:

cat > ~/.config/opencode/antigravity.json << 'EOF'
{
  "$schema": "https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/main/assets/antigravity.schema.json",
  "account_selection_strategy": "round-robin",
  "pid_offset_enabled": true
}
EOF

예상 결과: pid_offset_enabled가 true로 설정됩니다.

작동 원리:

• 각 프로세스는 PID (프로세스 ID)를 기반으로 오프셋을 계산
• 오프셋 = PID % 계정 수
• 다른 프로세스는 다른 시작 계정을 우선 사용
• 예시: 3개 계정, PID 100, 101, 102의 프로세스는 각각 계정 1, 2, 0을 사용

4단계: 전략 적용 확인

왜 필요한가 설정이 올바르고 전략이 예상대로 작동하는지 확인합니다.

작업

여러 동시 요청을 보내고 계정 전환을 관찰합니다:

# 디버그 로그 활성화
export OPENCODE_ANTIGRAVITY_DEBUG=1

# 5개 요청 보내기
for i in {1..5}; do
  opencode run "Test $i" --model=google/antigravity-gemini-3-pro &
done
wait

예상 결과:

• 로그에서 다른 요청이 다른 계정을 사용하는 것을 확인
• account-switch 이벤트에서 계정 전환 기록

예시 로그 (round-robin 전략):

[DEBUG] Selected account: [email protected] (index: 0) - reason: rotation
[DEBUG] Selected account: [email protected] (index: 1) - reason: rotation
[DEBUG] Selected account: [email protected] (index: 2) - reason: rotation
[DEBUG] Selected account: [email protected] (index: 0) - reason: rotation
[DEBUG] Selected account: [email protected] (index: 1) - reason: rotation

5단계: 계정 건강 상태 모니터링 (Hybrid 전략)

왜 필요한가 Hybrid 전략은 건강 점수를 기반으로 계정을 선택하므로, 건강 상태를 파악하면 설정이 적절한지 판단하는 데 도움이 됩니다.

작업

디버그 로그에서 건강 점수를 확인합니다:

export OPENCODE_ANTIGRAVITY_DEBUG=2 opencode run "Hello" --model=google/antigravity-gemini-3-pro

예상 결과:

[VERBOSE] Health scores: {
  "0": { "score": 85, "consecutiveFailures": 0 },
  "1": { "score": 60, "consecutiveFailures": 2 },
  "2": { "score": 70, "consecutiveFailures": 0 }
}
[DEBUG] Selected account: [email protected] (index: 0) - hybrid score: 270.2

해석:

• 계정 0: 건강 점수 85 (우수)
• 계정 1: 건강 점수 60 (사용 가능, 연속 2회 실패)
• 계정 2: 건강 점수 70 (양호)
• 최종 선택: 계정 0, 종합 점수 270.2

체크포인트 ✅

설정 적용 확인 방법

1. 설정 파일에서 account_selection_strategy 값 확인
2. 여러 요청을 보내고 로그에서 계정 전환 동작 관찰
3. Hybrid 전략: 건강 점수가 낮은 계정의 선택 빈도가 낮아야 함
4. Round-robin 전략: 계정이 순환 사용되며 특정 계정 선호 없음

주의사항

❌ 계정 수와 전략 불일치

잘못된 행동:

• 2개 계정만 있는데 round-robin 사용, 빈번한 전환 발생
• 5개 계정이 있는데 sticky 사용, 할당량 활용 불균형

올바른 방법: 빠른 참조표에 따라 전략을 선택합니다.

❌ 병렬 에이전트에서 PID 오프셋 미활성화

잘못된 행동:

• 여러 병렬 에이전트가 동시에 같은 계정 사용
• 계정이 빠르게 속도 제한에 걸림

올바른 방법: pid_offset_enabled: true를 설정합니다.

❌ 건강 점수 무시 (Hybrid 전략)

잘못된 행동:

• 특정 계정이 자주 속도 제한에 걸리는데도 계속 높은 빈도로 사용
• 건강 점수를 활용하여 문제 계정을 회피하지 않음

올바른 방법: 디버그 로그에서 건강 점수를 정기적으로 확인하고, 이상이 있으면 (예: 특정 계정의 연속 실패 횟수 > 5) 해당 계정 제거 또는 전략 변경을 고려합니다.

❌ 이중 할당량 풀과 단일 할당량 전략 혼용

잘못된 행동:

• Gemini 모델에 :antigravity 접미사를 사용하여 Antigravity 할당량 풀 강제 사용
• 동시에 quota_fallback: false 설정
• 특정 할당량 풀이 소진되면 다른 풀로 fallback 불가

올바른 방법: 이중 할당량 시스템을 이해하고 필요에 따라 quota_fallback을 설정합니다.

이번 강의 요약

전략	핵심 특징	적용 시나리오
sticky	속도 제한까지 계정 유지	1개 계정, 프롬프트 캐시 필요 시
round-robin	계정 순환 사용	4개 이상 계정, 처리량 극대화
hybrid	건강 + Token + LRU 지능적 선택	2-3개 계정, 성능과 안정성 균형

주요 설정:

• account_selection_strategy: 전략 설정 (sticky / round-robin / hybrid)
• pid_offset_enabled: 병렬 에이전트 시나리오에서 활성화 (true)
• quota_fallback: Gemini 이중 할당량 풀 fallback (true / false)

확인 방법:

• 디버그 로그 활성화: OPENCODE_ANTIGRAVITY_DEBUG=1
• 계정 전환 로그와 건강 점수 확인
• 다른 요청이 사용하는 계정 인덱스 관찰

다음 강의 예고

다음 강의에서는 **속도 제한 처리**를 학습합니다.

배울 내용:

• 다양한 유형의 429 오류 이해 (할당량 소진, 속도 제한, 용량 소진)
• 자동 재시도와 백오프 알고리즘의 작동 원리
• 언제 계정을 전환하고 언제 리셋을 기다려야 하는지

---

부록: 소스 코드 참조

클릭하여 소스 코드 위치 보기

업데이트 시간: 2026-01-23

기능	파일 경로	라인 번호
계정 선택 전략 진입점	src/plugin/accounts.ts	340-412
Sticky 전략 구현	src/plugin/accounts.ts	395-411
---	---	---
Hybrid 전략 구현	src/plugin/accounts.ts	358-383
건강 점수 시스템	src/plugin/rotation.ts	14-163
Token bucket 시스템	src/plugin/rotation.ts	290-402
LRU 선택 알고리즘	src/plugin/rotation.ts	215-288
PID 오프셋 로직	src/plugin/accounts.ts	387-393
설정 Schema	src/plugin/config/schema.ts	파일 참조

주요 상수:

• DEFAULT_HEALTH_SCORE_CONFIG.initial = 70: 새 계정 초기 건강 점수
• DEFAULT_HEALTH_SCORE_CONFIG.minUsable = 50: 계정 최소 사용 가능 건강 점수
• DEFAULT_TOKEN_BUCKET_CONFIG.maxTokens = 50: 각 계정 최대 token 수
• DEFAULT_TOKEN_BUCKET_CONFIG.regenerationRatePerMinute = 6: 분당 회복 token 수

주요 함수:

• getCurrentOrNextForFamily(): 전략에 따른 계정 선택
• selectHybridAccount(): Hybrid 전략 점수 선택 알고리즘
• getScore(): 계정 건강 점수 조회 (시간 회복 포함)
• hasTokens() / consume(): Token bucket 확인 및 소비
• sortByLruWithHealth(): LRU + 건강 점수 정렬