ndycode/codex-multi-auth

codex-multi-auth는 공식 @openai/codex CLI를 위한 멀티 계정 OAuth 관리자입니다. 이 도구는 공식 codex 바이너리를 점유하지 않으면서도, Codex CLI 사용자에게 명시적인 ChatGPT 계정 로그인, 계정 전환, 상태 확인 (Health checks), 로컬 진단 (Local diagnostics), 프로젝트 범위 저장소 (Project-scoped storage), 그리고 기본 활성화된 런타임 응답 로테이션 (Runtime Responses rotation) 기능을 제공합니다. 계정 관리를 위해서는 codex-multi-auth ...를 사용하고, 선택 사항인 포워딩 래퍼 (Forwarding wrapper)를 의도적으로 사용하고자 할 때만 codex-multi-auth-codex ...를 사용하십시오.

가시적인 계정 상태, 더 안전한 복구 명령, 그리고 요청을 포함하여 전달되는 Codex 세션을 위한 루프백 전용 (Loopback-only) 런타임 로테이션 프록시가 필요한 로컬 Codex CLI 멀티 계정 워크플로우가 필요할 때 이 도구를 사용하십시오.

참고

기존의 범위 지정된 프리릴리스 (Prerelease) 패키지인 @ndycode/codex-multi-auth는 마이그레이션 전용입니다. 모든 신규 설치에는 codex-multi-auth를 사용하십시오.

• 전용 codex-multi-auth ... 명령 제품군을 통한 Codex CLI 멀티 계정 OAuth 관리
• 명시적인 ChatGPT 계정 로그인, 저장된 계정 목록 표시, 계정 전환, 상태 확인 (Health checks) 및 진단 (Diagnostics)
• 래퍼로 실행되는 세션을 선택할 경우를 위한 공식 Codex CLI 명령용 선택적 codex-multi-auth-codex ... 포워딩 래퍼
• 상태 인지형 계정 선택, 할당량 예측 (Quota forecasting), 자동 장애 조치 (Automatic failover) 및 플래그 지정 계정 복구
• 저장소별 워크플로우를 위한 ~/.codex/multi-auth/projects/<project-key>/... 경로 아래의 프로젝트 범위 계정 저장소
• 계정 작업, 설정, 검색 및 단축키를 위한 대화형 터미널 대시보드
• 운영 신뢰성을 위한 forecast, report, fix, doctor, verify, monitor 및 rotation 명령
• 로컬 사용 원장 (Usage ledger), 예산 가드 (Budget guards), 계정 정책 제어, 라우팅 프로필 및 모델/계정 기능 보기
• codex-multi-auth status / codex-multi-auth report를 통한 런타임 카운터, 예산/쿨다운 상태 및 멀티 인증 프로브 (Multi-auth probe) 가시성
• 포워딩된 Codex CLI/앱 세션 내에서 실시간 계정 로테이션을 위한 기본 활성화된 루프백 응답 (Responses) 프록시
• /health, /v1/models 및 /v1/responses를 위한 선택적 루프백 전용 로컬 브리지

, 해시된 로컬 클라이언트 토큰(hashed local client tokens)으로 보호됨 - 공식 앱 바이너리를 패치하지 않으면서 가역적으로 패키징된 Codex 앱 바인딩 및 사용자 수준의 런처 라우팅 헬퍼 제공

• 세션 어피니티 (Session affinity), 실시간 계정 동기화 (live account sync), 선제적 새로고침 (proactive refresh) 및 선제적 할당량 유예 (preemptive quota deferral) 제어
• 엄격한 런타임 처리 및 문서화된 에러 계약 (error contracts)을 갖춘 Codex 지향적 요청/프롬프트 호환성
• 설치, 설정, 문제 해결, 업그레이드, 공개 API, 저장 경로 및 릴리스 노트에 대한 안정적인 문서

codex-multi-auth는 로컬 Codex 계정 상태를 가시화하고 복구 가능하게 만듭니다. 하나의 불투명한 인증 파일 대신, 이름이 지정된 계정 풀 (account pool), 결정론적 계정 전환 (deterministic account switching), 상태 인식 선택 (health-aware selection), 자동화를 위한 JSON 진단 (JSON diagnostics), 그리고 오래되거나 손상된 로컬 상태를 위한 안전한 복구 명령을 제공합니다. 이 아키텍처는 개인 개발 워크플로를 위해 설계되었습니다: 자격 증명은 로컬에 유지되며, 런타임 로테이션 (runtime rotation)은 루프백 (loopback) 전용이며, 공식 Codex 설치 경로가 codex 명령에 대한 소유권을 유지합니다.

codex-multi-auth는 이제 세 가지 별도의 글로벌 바이너리를 제공합니다:

바이너리	용도
codex-multi-auth	기본 계정 관리자; login, status, switch, forecast, rotation status와 같은 순수 인증 서브 명령을 수락함
codex-multi-auth-codex	auth ... 명령을 로컬에서 처리하고 그 외의 모든 명령을 공식 Codex CLI로 전달하는 선택적 래퍼 (wrapper)
codex-multi-auth-app-launcher	지원되는 사용자 수준 바로가기 및 래퍼 앱을 위한 선택적 데스크톱 런처 헬퍼

이 패키지는 글로벌 codex 바이너리를 게시하지 않습니다. codex는 공식 OpenAI 설치 경로가 소유하도록 유지하고, 이 패키지의 전달 래퍼 (forwarding wrapper)를 의도적으로 사용하고자 할 때만 codex-multi-auth-codex ...를 사용하십시오.

약관 및 사용 고지

[!주의] 이 프로젝트는 OAuth 계정 자격 증명을 사용하며 개인 개발 용도로 제작되었습니다.

이 패키지를 사용함으로써 귀하는 다음을 인정합니다:

• 이것은 독립적인 오픈 소스 (open-source) 프로젝트이며, OpenAI의 공식 제품이 아닙니다.
• 귀하는 본인의 사용 및 정책 준수에 대한 책임을 집니다.
• 운영/상업용 워크로드 (workloads)의 경우, OpenAI Platform API를 사용하십시오.

사용자용 (For Humans)

npm i -g codex-multi-auth

npm uninstall -g @ndycode/codex-multi-auth
npm i -g codex-multi-auth

codex --version은 공식 Codex CLI에 접근 가능한지 확인합니다. codex-multi-auth --version은 설치된 매니저 패키지 버전을 확인합니다. codex-multi-auth-codex --version은 선택 사항인 포워딩 래퍼 (forwarding wrapper) 엔트리포인트 (entrypoint)입니다.

codex --version
codex-multi-auth --version
codex-multi-auth status

codex가 PATH에 설정되어 있다면 어떤 공식 설치 경로든 괜찮습니다:

npm i -g @openai/codex,

brew install --cask codex,

또는 공식 릴리스 바이너리 (release binary).

LLM 에이전트용 (For LLM Agents)

• 글로벌 패키지 설치:
  npm i -g codex-multi-auth

• codex-multi-auth login으로 첫 로그인 흐름 실행

• codex-multi-auth status 및 codex-multi-auth check로 상태 검증

• codex-multi-auth forecast --live로 라우팅 (routing) 확인

codex-multi-auth status
codex-multi-auth check

설치 및 로그인:

npm i -g @openai/codex
npm i -g codex-multi-auth
codex-multi-auth login

이미 Homebrew 또는 릴리스 바이너리를 통해 공식 네이티브 CLI를 설치했다면, 다음만 필요합니다:

npm i -g codex-multi-auth
codex-multi-auth login

매니저와 새 계정을 확인하십시오:

codex-multi-auth status
codex-multi-auth check

다음 명령어를 사용하십시오:

codex-multi-auth list
codex-multi-auth switch 2
codex-multi-auth forecast --live

브라우저 실행이 차단된 경우, docs/getting-started.md에 있는 대체 로그인 경로를 사용하십시오.
원격 또는 헤드리스 셸 (headless shells)의 경우, codex-multi-auth login --device-auth를 권장합니다.

명령어	답변 내용
codex-multi-auth login	계정 메뉴를 어떻게 추가하거나 다시 엽니까?
codex-multi-auth status	현재 래퍼 (wrapper)가 활성화되어 있습니까?
codex-multi-auth check	저장된 계정들이 정상적으로 보입니까?

명령 (Command)	답변 내용
codex-multi-auth list	어떤 계정들이 저장되어 있으며, 어떤 계정이 활성화되어 있습니까?
codex-multi-auth switch <index>	저장된 다른 계정으로 어떻게 전환합니까?
codex-multi-auth forecast --live	다음 세션에 어떤 계정이 가장 적합해 보입니까?

명령 (Command)	답변 내용
codex-multi-auth verify-flagged	이전에 플래그 (flagged) 처리된 계정을 복구할 수 있습니까?
codex-multi-auth verify --paths	나의 저장 경로 체인 (storage path chain)과 샌드박스 프로브 (sandbox probes)가 여전히 자체 테스트를 통과합니까?
codex-multi-auth fix --dry-run	어떤 안전한 저장소 또는 계정 복구 작업이 가능합니까?
codex-multi-auth doctor --fix	CLI가 지금 즉시 진단하고 가장 안전한 수정 사항을 적용할 수 있습니까?
codex-multi-auth uninstall	잔류 아티팩트 (residual artifacts)를 제거합니다 (npm uninstall 실행 전에 수행하십시오; npm@7+ 버전부터는 더 이상 preuninstall이 실행되지 않습니다.)

명령 (Command)	답변 내용
codex-multi-auth report --live --json	기계 판독이 가능한 (machine-readable) 전체 상태 보고서를 어떻게 얻습니까?
codex-multi-auth fix --live --model gpt-5.3-codex	선택한 모델을 사용하여 실시간 복구 프로브 (live repair probes)를 어떻게 실행합니까?
codex-multi-auth why-selected --json	선택기 (selector)가 현재 어떤 계정을 선택하며, 그 이유는 무엇입니까?
codex-multi-auth usage --since 24h --by project	최근에 기록된 로컬 사용량은 무엇입니까?
codex-multi-auth monitor --json	통합된 사용량, 정책 (policy), 할당량 (quota), 런타임 (runtime) 및 프로젝트 상태는 무엇입니까?
codex-multi-auth bridge token create --label local-client	로컬 브리지 베어러 토큰 (local bridge bearer token)을 어떻게 생성합니까?
codex-multi-auth integrations --kind python	로컬 브리지 클라이언트 스니펫 (local bridge client snippets)을 어떻게 생성합니까?
codex-multi-auth rotation status	전달된 (forwarded) Codex 세션에 대해 실시간 런타임 계정 로테이션 (live runtime account rotation)이 활성화되어 있습니까?

• 모든 계정이 속도 제한 (rate-limited)에 걸린 경우, 전체 풀 재생 (whole-pool replay)은 기본적으로 비활성화됩니다.
• 활성 요청 (active requests)은 제한된 아웃바운드 요청 예산 (bounded outbound request budget)을 사용하여, 하나의 프롬프트가 무한히 전체 풀을 순회할 수 없도록 합니다.
• 계정 간 반복적인 5xx 버스트 (5xx bursts)가 발생하면 공격적인 로테이션 (rotation)을 계속하는 대신 짧은 쿨다운 (cooldown)이 트리거됩니다.
• 백그라운드 새로고침 버스트 (background refresh bursts)를 줄이기 위해 선제적 새로고침 (proactive refresh)이 분산되어 수행됩니다.
  codex-multi-auth status

최근 런타임 요청 메트릭 (runtime request metrics)을 텍스트 출력으로 보여주며, codex-multi-auth report --json은

기계 판독이 가능한 쿨다운/런타임 스냅샷 (cooldown/runtime snapshot)을 노출합니다.

키 (Key)	동작 (Action)
Up / Down	선택 이동
Enter	선택/열기
1-9	빠른 전환
/	검색
?	도움말 토글
Q	뒤로 가기/취소

키 (Key)	동작 (Action)
S	현재 계정 설정
R	계정 새로고침/재로그인
E	계정 활성화/비활성화
D	계정 삭제

파일 (File)	기본 경로 (Default path)
설정 (Settings)	~/.codex/multi-auth/settings.json
...
CODEX_MULTI_AUTH_DIR=<path>를 사용하여 루트 (root)를 재정의할 수 있습니다.

.

기본 설정 루트 (Primary config root):

~/.codex/multi-auth/settings.json

• 또는 사용자 정의 루트가 설정된 경우
  CODEX_MULTI_AUTH_DIR/settings.json

선택된 런타임/환경 재정의 (Selected runtime/environment overrides):

변수 (Variable)	효과 (Effect)
CODEX_MULTI_AUTH_DIR	settings/accounts 루트 디렉토리 재정의 (Override)
CODEX_MULTI_AUTH_CONFIG_PATH	대체 설정 파일 경로 (Alternate config file path)
CODEX_MODE=0/1	Codex 모드 비활성화/활성화 (Disable/enable)
CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0/1	전달된 Codex CLI/앱 세션에 대한 실시간 Responses 프록시 로테이션 (live Responses proxy rotation) 제외/포함 (Opt out/in)
CODEX_MULTI_AUTH_APP_ROTATION_IDLE_MS=<ms>	자동 Codex 앱 헬퍼 유휴 종료 (automatic Codex app helper idle shutdown) 재정의
CODEX_MULTI_AUTH_APP_BIND_INSTALL=0/1	설치/업데이트 또는 로테이션 활성화 시 패키징된 Codex 앱 바인드 자가 치유 (packaged Codex app bind self-heal) 제외/포함 (Opt out/in)
CODEX_MULTI_AUTH_APP_LAUNCHER_INSTALL=0/1	설치/업데이트 또는 로테이션 활성화 시 지원되는 앱 바로가기 라우팅 (routing supported app shortcuts) 제외/포함 (Opt out/in)
CODEX_TUI_V2=0/1	TUI v2 비활성화/활성화 (Disable/enable)
`CODEX_TUI_COLOR_PROFILE=truecolor	ansi256
`CODEX_TUI_GLYPHS=ascii	unicode
CODEX_AUTH_BACKGROUND_RESPONSES=0/1	상태 유지 Responses background: true 호환성 포함/제외 (Opt in/out)
CODEX_AUTH_FETCH_TIMEOUT_MS=<ms>	요청 타임아웃 재정의 (Request timeout override)
CODEX_AUTH_STREAM_STALL_TIMEOUT_MS=<ms>	스트림 정지 타임아웃 재정의 (Stream stall timeout override)

변경 후 설정을 검증하세요 (Validate config after changes):

codex-multi-auth status
codex-multi-auth check
codex-multi-auth forecast --live

Responses 백그라운드 모드는 선택 사항(opt-in)으로 유지됩니다. background: true를 의도적으로 보내는 호출자에 대해서만 settings의 backgroundResponses를 활성화하거나 CODEX_AUTH_BACKGROUND_RESPONSES=1을 설정하십시오. 해당 요청들은 상태 비저장(stateless) store=false 라우팅에서 상태 유지(stateful) store=true 라우팅으로 전환되기 때문입니다. 배포 가이드는 docs/upgrade.md를 참조하십시오.

런타임 로테이션(Runtime rotation)은 요청을 수반하는 래퍼 실행(wrapper-launched) Codex 세션에 대해 기본적으로 활성화됩니다. 전역 설치/업데이트 시 가능한 경우 패키징된 Codex 앱 바인드 및 사용자 수준의 런처 라우팅에 대한 자가 치유(self-heals)가 수행되지만, codex-multi-auth rotation enable이 명시적인 복구 명령으로 유지됩니다. codex-multi-auth rotation disable은 설정을 끄고 영구적인 앱 바인드를 제거합니다. CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0을 설정하십시오.

, CODEX_MULTI_AUTH_APP_BIND_INSTALL=0,

또는 CODEX_MULTI_AUTH_APP_LAUNCHER_INSTALL=0을 설정하여 일치하는 기본 동작을 거부(opt out)할 수 있습니다.

설치된 래퍼(wrappers)는 일반적인 포워딩된 Codex 시작 중에 최선을 다해 매일 npm 버전을 확인합니다. 더 새로운 패키지가 감지되면, 래퍼는 대화형 TTY 환경이거나 CODEX_MULTI_AUTH_DEBUG=1인 경우에만 수동 알림을 출력합니다:

: npm install -g codex-multi-auth@latest.

래퍼는 사용자를 대신하여 npm install 또는 업데이트 명령을 절대 실행하지 않습니다.

설정(Settings) 메뉴에 이제 단계별 기능(staged features)을 위한 Experimental 섹션이 포함됩니다:

• oc-chatgpt-multi-auth로의 우선 미리보기 동기화 (preview-first sync)
• 파일명 프롬프트가 포함된 이름 지정 로컬 풀 백업 내보내기 (named local pool backup export)
• 새로고침 가드 토글(refresh guard toggle) 및 간격 제어(interval controls)가 백엔드 제어(Backend Controls)에서 이동됨

이러한 흐름은 기본적으로 의도적으로 비파괴적(non-destructive)입니다: 적용 전 동기화 미리보기, 대상 전용 계정 보존, 백업 파일명 충돌 시 안전하게 실패 처리 등이 적용됩니다.

60초 복구 (60-second recovery)

codex-multi-auth doctor --fix
codex-multi-auth check
codex-multi-auth forecast --live

여전히 작동하지 않는 경우:

codex-multi-auth login

일반적인 증상 (Common symptoms)

codex-multi-auth를 인식할 수 없는 경우: where codex-multi-auth 또는 which codex-multi-auth를 실행한 다음, 설치 확인을 위해 docs/troubleshooting.md를 따르십시오.

• 전환(Switch)은 성공했으나 잘못된 계정이 활성화된 경우: codex-multi-auth switch <index>를 실행한 후 세션을 재시작하십시오.
• 풀 쿨다운(pool cooldown) 메시지와 함께 요청이 빠르게 실패하는 경우: 쿨다운 대기 시간을 기다리거나 codex-multi-auth status를 검사하십시오.
• 반복적인 업스트림(upstream) 5xx 오류 후 요청이 빠르게 실패하는 경우: 런타임 트래픽 및 쿨다운 세부 정보를 확인하기 위해 codex-multi-auth report --json을 검사하십시오.
• Windows에서 EBUSY / EPERM 오류로 인해 스토리지 정리(Storage cleanup)가 실패하는 경우: codex-multi-auth doctor --fix를 실행하여 재시도하거나, ~/.codex/multi-auth/<project-key>/를 수동으로 제거하십시오.