---
title: "GPT Codex Router: 멀티 계정 로테이션과 페일오버를 지원하는 로컬 프록시"
slug: "gpt-codex-router-multi-account"
canonicalUrl: "https://moonshotnotes.com/posts/gpt-codex-router-multi-account/"
sourceUrl: "https://moonshotnotes.com/posts/gpt-codex-router-multi-account/"
markdownUrl: "https://moonshotnotes.com/agent/posts/gpt-codex-router-multi-account.md"
language: "ko"
category: "AI Development"
updatedAt: "2026-09-16"
agentTokenEstimate: 2213
---

# GPT Codex Router: 멀티 계정 로테이션과 페일오버를 지원하는 로컬 프록시

Codex Desktop과 CLI의 사용량 한도(429) 문제를 해결하고, 여러 ChatGPT 계정을 공식 로그인으로 격리 관리하며 자동 페일오버하는 GPT Codex Router 사용법을 정리합니다.

## Agent metadata

- Source: https://moonshotnotes.com/posts/gpt-codex-router-multi-account/
- Markdown: https://moonshotnotes.com/agent/posts/gpt-codex-router-multi-account.md
- Language: ko
- Category: AI Development
- Tags: Codex, OpenAI Codex, Docker, Failover, Multi Account
- Updated: 2026-09-16
- Estimated tokens: 2213

OpenAI Codex는 복잡한 코드베이스 분석부터 단위 테스트 작성, 대규모 리팩토링에 이르기까지 개발자의 작업 속도를 획기적으로 높여주는 도구입니다. 특히 Codex Desktop과 CLI 환경은 로컬 파일 시스템과 긴밀하게 맞물려 뛰어난 완성도를 보여줍니다.

하지만 프로젝트 단위의 긴 호흡으로 코딩 에이전트를 돌리다 보면 반드시 마주치는 병목이 있습니다. 바로 ChatGPT 구독 플랜의 사용량 한도(Rate Limit / Quota)입니다.

집중해서 아키텍처를 개편하거나 대형 PR을 작업하던 중 갑작스럽게 429 `usage_limit_reached` 에러가 발생하면, 리셋 시간(보통 몇 시간)까지 모든 코딩 에이전트 작업이 올스톱됩니다. 만약 업무용 계정과 개인용 계정 등 복수의 유료 ChatGPT 플랜을 보유하고 있더라도, Codex Desktop은 기본적으로 단 하나의 로그인 컨텍스트만 지원하기 때문에 매번 수동으로 로그아웃하고 브라우저 인증을 거쳐야 하는 번거로움이 있었습니다.

오픈소스 프로젝트 [codex-account-pool (GPT Codex Router)](https://github.com/munlucky/codex-account-pool)은 이 문제를 우아하고 안전하게 해결하기 위해 만들어진 로컬 전용 라우팅 프록시입니다.

> **프로젝트 핵심 요약 (info)**
>
> GPT Codex Router는 공식 Codex 바이너리 변조 없이, 공식 `codex login` 흐름을 통해 여러 ChatGPT 계정을 프로필별로 격리 관리합니다. 작업 중 429 구독 한도를 감지하면 다음 계정으로 자동 전환하고 진행 중인 요청을 매끄럽게 재생(replay)합니다.

| 비교 항목 | 단일 계정 기본 사용 | 브라우저 세션 추출 스크립트 | 앱 바이너리 패칭 | **GPT Codex Router** |
| :--- | :--- | :--- | :--- | :--- |
| **한도(429) 도달 시** | 수 시간 동안 전면 중단 | 토큰 수동 재추출 필요 | 세션 중단 및 앱 불안정 | **0초 만에 자동 전환 & 재시도** |
| **인증 신뢰성** | 공식 인증 | 쿠키 만료 시 빈번한 장애 | 비공식 방식 위험 노출 | **공식 `codex login` 브라우저 인증** |
| **앱 무결성** | 변조 없음 | 변조 없음 | **앱 업데이트 시 충돌/파손** | **공식 앱 100% 무변조 (`_base_url`)** |
| **에이전트 맥락 유지** | 세션 단절 | 컨텍스트 유실 위험 | 에러 반환으로 중단 | **투명한 Request Replay로 작업 유지** |
| **지원 클라이언트** | Codex Desktop/CLI | 특정 스크립트 한정 | 특정 바이너리 한정 | **Codex Desktop, CLI, Qwen Code (/v1)** |

## 왜 이 프로젝트가 필요한가

Codex Desktop을 멀티 계정으로 운용하려고 할 때 기존 방식들이 가진 한계는 명확했습니다.

- 비공식 세션 토큰 추출의 위험: 브라우저 쿠키나 세션 토큰을 손으로 긁어서 스크립트에 넣는 방식은 토큰 만료 시 재인증이 어렵고 보안상 취약합니다.
- 애플리케이션 변조(Patching)의 불안정성: Codex 앱 바이너리나 MSIX 패키지를 직접 수정하는 방식은 Codex 업데이트가 발생할 때마다 앱이 깨질 위험이 큽니다.
- 수동 전환의 비효율: 세션 중간에 한도에 걸리면 현재까지 진행된 에이전트의 컨텍스트를 잃어버리거나 다음 세션으로 이어받기가 매우 까다롭습니다.

GPT Codex Router는 Codex가 기본적으로 지원하는 정식 설정 인터페이스인 `chatgpt_base_url`과 `openai_base_url`을 활용합니다. 즉, 공식 앱을 단 1바이트도 수정하지 않고 순수하게 로컬 프록시 계층에서 트래픽을 중계합니다.

## 시스템 동작 구조와 주요 기능

GPT Codex Router의 전체 데이터 흐름과 핵심 설계 원칙은 다음과 같습니다.

```mermaid
flowchart TD
    subgraph Clients [로컬 클라이언트]
        CD[Codex Desktop / Codex CLI]
        QC[Qwen Code / OpenAI 호환 클라이언트]
    end

    subgraph Router [GPT Codex Router - Docker localhost:8317]
        GW[Gateway & Failover Engine]
        V1[OpenAI 호환 /v1 Adapter]
        PROF[격리된 계정 프로필 풀]
        subgraph Accounts [CODEX_HOME auth.json]
            A1[account-1 / personal]
            A2[account-2 / work]
            AN[account-N / backup]
        end
    end

    subgraph OpenAI [OpenAI Upstream]
        CGW[chatgpt.com / backend-api]
    end

    CD -->|chatgpt_base_url| GW
    QC -->|v1 chat/completions| V1
    V1 --> GW
    GW --> PROF
    PROF --> A1
    PROF --> A2
    PROF --> AN
    GW -->|인증 헤더 주입| CGW
```

### 1. 공식 `codex login` 기반의 프로필 격리

GPT Codex Router는 임의의 인증 방식을 쓰지 않습니다. 호스트에 설치된 공식 `codex` CLI의 로그인 명령을 그대로 호출하여 브라우저에서 공식 ChatGPT 로그인을 완료합니다.

각 계정의 자격 증명은 호스트의 전용 데이터 디렉토리에 분리되어 보관됩니다.

- Windows: `%APPDATA%\GPTCodexRouter\profiles\codex\<profile>\auth.json`
- macOS: `~/Library/Application Support/GPTCodexRouter/profiles/codex/<profile>/auth.json`

```mermaid
flowchart LR
    subgraph HostZone ["호스트 OS 환경 (인증 안전 영역)"]
        direction TB
        CLI["공식 codex CLI 실행"] --> LOGIN["codex login<br/>브라우저 공식 인증 완료"]
        LOGIN --> PROFILES["데이터 격리 디렉토리<br/>%APPDATA% 또는 ~/Library"]
        PROFILES --> DIR_A["profiles/codex/personal/auth.json"]
        PROFILES --> DIR_B["profiles/codex/work/auth.json"]
        PROFILES --> DIR_C["profiles/codex/backup/auth.json"]
    end

    subgraph ContainerZone ["Docker 컨테이너 (로컬 프록시)"]
        PROXY_APP["GPT Codex Router 게이트웨이"]
    end

    DIR_A -.->|읽기 전용 볼륨 마운트| PROXY_APP
    DIR_B -.->|읽기 전용 볼륨 마운트| PROXY_APP
    DIR_C -.->|읽기 전용 볼륨 마운트| PROXY_APP
```

Docker 컨테이너는 이 디렉토리를 마운트하여 사용하므로, 소스 코드 저장소 안으로 비밀 인증 정보가 유입될 위험이 원천 차단됩니다.

### 2. 반응형 사용량 한도 페일오버 (Reactive Failover)

라우터의 계정 회전은 철저하게 반응형(Reactive)으로 동작합니다.
평소에는 사용자가 지정한 활성 계정(예: `account-1`)으로 모든 요청을 통과시킵니다. 그러다 상위 ChatGPT 백엔드로부터 명시적인 429 `usage_limit_reached` 응답을 수신하는 순간:

1. 현재 활성 계정을 응답 헤더에 명시된 리셋 시각까지 일시적으로 억제 목록에 등록합니다.
2. 프로필 풀에 등록된 다음 사용 가능한 계정(예: `account-2`)을 선택합니다.
3. 방금 실패했던 동일한 요청을 새 계정의 세션으로 즉시 다시 전송(Replay)합니다.

```mermaid
flowchart TD
    subgraph Step1 ["1. 일반 요청 프록시"]
        REQ["Codex 에이전트 요청"] --> ROUTER["GPT Codex Router<br/>(localhost:8317)"]
        ROUTER --> ACC_A["활성 계정 1<br/>(auth.json 토큰 주입)"]
        ACC_A --> BACKEND["OpenAI ChatGPT 백엔드"]
    end

    subgraph Step2 ["2. 429 감지 및 계정 스위칭"]
        BACKEND -->|429 usage_limit_reached| DETECT["429 사용량 한도 응답 감지"]
        DETECT --> COOLDOWN["계정 1 쿨다운 등록<br/>(헤더 리셋 시각까지 대기)"]
        COOLDOWN --> SELECT["풀에서 다음 가용 계정 2 선택"]
    end

    subgraph Step3 ["3. 투명한 요청 재생 (Replay)"]
        SELECT --> REPLAY["동일 요청 Replay 재전송"]
        REPLAY --> ACC_B["대기 계정 2<br/>(새 토큰 주입)"]
        ACC_B --> BACKEND2["OpenAI ChatGPT 백엔드"]
        BACKEND2 -->|200 OK 스트리밍| SUCCESS["Codex로 정상 응답 반환<br/>(작업 중단 제로)"]
    end
```

> **실제 개발 시나리오 (tip)**
>
> Codex로 20개 이상의 타입스크립트 모듈을 일괄 리팩토링하는 대규모 작업을 걸어두고 자리를 비워도, 중간에 429 한도에 걸리면 라우터가 계정 2로 스스로 전환해 작업을 끝까지 완수해 둡니다. 에이전트가 멈춰 있을까 봐 주기적으로 확인할 필요가 없습니다.

> **네트워크 오류와 한도 분리 (tip)**
>
> 단순 네트워크 불안정, 일시적인 5xx 서버 오류, 토큰 갱신 실패 등의 일반적인 에러에서는 계정을 함부로 회전하지 않습니다. 오직 확정된 구독 사용량 제한 응답일 때만 안전하게 페일오버를 수행합니다.

### 3. OpenAI 호환 `/v1` 엔드포인트 지원

Codex 트래픽을 프록시하는 것 외에도, 라우터는 로컬 `/v1` 호환 엔드포인트를 제공합니다.

- `/v1/responses`
- `/v1/chat/completions`
- `/v1/models`

이를 통해 Qwen Code와 같은 서드파티 오픈소스 코딩 도구나 로컬 스크립트에서도 동일한 ChatGPT 계정 풀과 자동 페일오버의 혜택을 그대로 누릴 수 있습니다.

### 4. 메타데이터 전용 Context Observability

GPT Codex Router는 대화 내용이나 소스 코드, 프롬프트 본문을 일체 저장하거나 유출하지 않는 엄격한 보안 모델을 갖추고 있습니다. 대신 개발자가 요청의 흐름을 파악할 수 있도록 구조화된 JSONL 메타데이터를 수집합니다.

- Wire Size 및 Decoded Context Size: 요청 전송 크기와 압축 해제된 실제 컨텍스트 크기를 추적합니다. (zstd 압축 디코딩 옵저버 내장)
- 구조적 구성비: 컨텍스트 내에서 도구 실행 결과, 시스템 지시문, 추론 토큰 등이 차지하는 비율을 계산합니다.
- 토큰 카운터 및 컨텍스트 재사용률: 실제 캐시된 토큰 비율과 컨텍스트 재사용 비율을 산출합니다.

## 설치 및 시작하기 (Quick Start)

GPT Codex Router는 Docker Compose v2가 설치된 Windows 및 macOS 환경을 공식 지원합니다. 호스트에 Go 언어를 별도로 설치할 필요가 없습니다.

### 사전 준비

- Windows 10/11 또는 macOS 12+
- Docker Desktop 실행 중
- 공식 `codex` CLI가 PATH에 등록되어 있을 것

### 1단계: 저장소 클론 및 셋업 실행

터미널을 열고 저장소를 클론한 뒤 셋업 스크립트를 실행합니다.

**Windows 환경:**
```powershell
git clone https://github.com/munlucky/codex-account-pool.git gpt-codex-router
cd gpt-codex-router
.\setup.cmd
```

**macOS 환경:**
```bash
git clone https://github.com/munlucky/codex-account-pool.git gpt-codex-router
cd gpt-codex-router
./setup.sh
```

### 2단계: 대화형 브라우저 로그인

셋업 스크립트가 실행되면 공식 `codex login` 프로세스가 대화형으로 실행됩니다.

```text
[1/2] account-1 계정 로그인 진행 중...
브라우저에서 ChatGPT 로그인을 완료하세요.
-> 다른 계정을 추가하시겠습니까? (y/n): y
[2/2] account-2 계정 로그인 진행 중...
브라우저에서 두 번째 ChatGPT 계정으로 로그인을 완료하세요.
-> 다른 계정을 추가하시겠습니까? (y/n): n
```

원하는 만큼 계정을 등록하고 나면 스크립트가 다음 작업을 자동으로 처리합니다.

- 로컬 프로필 레지스트리 생성
- 로컬 클라이언트 키 발급
- Docker 컨테이너 빌드 및 백그라운드 구동
- `localhost:8317/healthz` 헬스체크 검증
- 호스트의 `~/.codex/config.toml` 자동 백업 및 라우터 주소 등록

### 3단계: Codex Desktop 재시작

설정이 끝난 후 **Codex Desktop을 완전히 종료한 뒤 다시 실행**합니다. 이제 Codex Desktop에서 코딩 작업을 시작하면 모든 백엔드 트래픽이 로컬 라우터를 거치게 되며, 한 계정이 쿼터에 도달해도 작업이 중단되지 않고 다음 계정으로 자연스럽게 이어집니다.

## 자주 쓰는 운영 명령어

컨테이너가 동작 중인 상태에서 유용하게 사용할 수 있는 명령어들입니다.

### 1. 등록된 계정 프로필 목록 확인

현재 라우터에 등록된 계정 목록과 현재 활성화된 계정을 조회합니다.

```bash
docker compose exec gpt-codex-router gpt-codex-router auth list
```

### 2. 활성 계정 수동 지정

특정 계정(예: `personal` 또는 `account-2`)을 기본 계정으로 우선 사용하고 싶다면 언제든지 수동으로 변경할 수 있습니다.

```bash
docker compose exec gpt-codex-router gpt-codex-router auth use codex account-2
```

새로 들어오는 요청부터 지정된 계정으로 라우팅됩니다. 이미 스트리밍 중인 요청은 기존 세션을 안전하게 유지합니다.

### 3. 실시간 로그 모니터링

요청이 어떤 계정으로 전송되고 페일오버가 일어나는지 JSONL 로그로 실시간 확인합니다.

```bash
docker compose logs -f --tail=50 gpt-codex-router
```

### 4. 컨텍스트 관측 리포트 생성

지난 3시간 동안의 컨텍스트 크기 변화와 토큰 소비 패턴을 시각적인 표로 확인합니다.

```bash
docker compose exec gpt-codex-router gpt-codex-router report --since 3h --timezone Asia/Seoul
```

### 5. 원상 복구 및 삭제

라우터 사용을 중단하고 이전 상태로 되돌리고 싶다면 컨테이너를 내리고 백업 파일을 복원하면 됩니다.

```bash
docker compose down
```

그리고 `~/.codex/config.toml` 위치에 생성되어 있는 `config.toml.gpt-codex-router.bak` 파일을 원래 이름(`config.toml`)으로 덮어쓰면 즉시 기존 공식 설정으로 복원됩니다.

## 보안 원칙과 주의점

GPT Codex Router는 안전한 로컬 개발을 최우선 가치로 두고 개발되었습니다.

- 루프백 전용: 기본적으로 외부 네트워크나 공용 IP로 포트를 개방하지 않으며, 단일 사용자 로컬 환경(`127.0.0.1:8317`)에서만 수신 대기합니다.
- 토큰 헤더 제거: 클라이언트로부터 유입된 외부 인증 헤더나 쿠키는 상위 백엔드로 전달되기 전에 제거되며, 라우터가 안전하게 보관하는 프로필 토큰으로 교체됩니다.
- 쿼터 우회 도구가 아님: 이 프로젝트는 OpenAI의 사용량 한도를 강제로 해제하거나 무단 조작하는 도구가 아닙니다. 개발자가 정당하게 구독 중인 여러 계정의 세션을 교대 운용하는 안전한 라우터입니다.

## 마치며

장시간 이어지는 자율 코딩 에이전트 환경에서 작업 연속성은 작업의 품질과 직결됩니다. 모델이 한창 코드 구조를 파악하고 검증 스크립트를 작성하는 도중에 사용량 한도로 세션이 끊기는 경험은 매우 소모적입니다.

복수의 ChatGPT 계정을 효과적으로 활용해 끊김 없는 개발 흐름을 유지하고 싶다면, [codex-account-pool 저장소](https://github.com/munlucky/codex-account-pool)를 살펴보시길 권합니다. Docker 기반의 간단한 설정만으로 안정적인 멀티 계정 코딩 환경을 구축할 수 있습니다.