CLI 제공자, 계정, 모델

이 명령들은 상위 제공자를 설정하고, 계정을 인증하고, 자격 증명 풀을 관리하고, Codex에 노출되는 모델 카탈로그를 제어합니다.

제공자

ocx provider <subcommand>

비대화형 제공자 관리입니다. 레지스트리 항목은 이름으로 시드되며, 사용자 지정 이름을 쓰려면 --adapter와 --base-url을 둘 다 지정해야 합니다.

하위 명령	지원 플래그	동작
list	--json, --jsonl	설정된 제공자와 남아 있는 레지스트리 항목을 나열합니다. --jsonl은 설정된 제공자마다 JSON 객체를 한 줄씩 출력합니다.
add <name>	--adapter <adapter>, --base-url <url>, --api-key <key>, --default-model <model>, --set-default, --force, --json, --sync	로컬에 제공자를 저장합니다. --force는 덮어쓰기를 허용하며, --sync는 JSON·일반 출력 모두에서 동기화를 시도합니다.
edit <name>	제공자 필드 플래그, --headers <json>, --json	키 풀을 바꾸지 않고 검증된 실시간 제공자 필드를 수정합니다. --headers는 사용자 지정 요청 헤더를 병합하며, {} 또는 -로 지울 수 있습니다.
test <name>	--json	실제 상위 모델 엔드포인트를 확인합니다.
show <name>	--json	API 키를 마스킹한 설정을 보여줍니다.
remove <name>	--json	기본값이 아닌 제공자를 제거합니다. 마지막 제공자는 제거할 수 없습니다.
set-default <name>	--json	기존 제공자를 기본값으로 선택합니다.
selected <name>	--set <ids>, --clear, --json	제공자 모델 허용 목록을 읽거나 업데이트합니다.
quota	--refresh, --json	제공자 할당량 보고서를 읽습니다.
presets	--json	대시보드 제공자 프리셋을 나열합니다.
account-mode	pool, direct, --json	Codex 계정 라우팅을 풀 기반으로 할지 직접 연결로 할지 선택합니다.
import-cc-switch	--source <FILE>, --provider <id>, --apply, --restore, --allow-private-network, --json	CC-Switch SQLite(cc-switch.db) 또는 레거시 JSON 파일에서 키 없는 프로바이더 항목을 미리보기·선택 적용·복원합니다.

기본 add, remove, set-default는 로컬 설정을 바꿉니다. 실행 중인 프록시를 바꾸려면 --live를 지정하세요. 실시간 삭제에는 --yes도 필요합니다. --sync --json도 저장 후 동기화를 실제로 시도하며, 실패하면 저장은 유지한 채 0이 아닌 코드와 needsSync: true를 반환합니다. --live와 --sync는 함께 쓸 수 없습니다. pacing·snapshot/apply 절차는 영문 명령 안내를 참고하세요.

ocx provider list --json
ocx provider list --jsonl
ocx provider test ark
ocx provider add anthropic --api-key sk-ant-... --set-default --sync
ocx provider add local-dev --adapter openai-chat --base-url http://localhost:11434/v1
ocx provider show anthropic --json
ocx models --provider anthropic --json
ocx models live --provider ark --json

--jsonl은 설정된 제공자만 JSON 객체 하나당 한 줄로 출력합니다. 각 객체의 필드는 --json의 configured 배열 항목과 같으며, registryCount 요약은 포함하지 않습니다. 스크립트에서 각 줄의 객체를 순서대로 처리할 수 있습니다. --json과 --jsonl은 함께 사용할 수 없습니다.

커스텀 헤더는 자격증명 통로가 아닙니다

--headers는 비밀이 아닌 요청 메타데이터용입니다 — 라우팅 힌트, 테넌트나 프로젝트 선택자, 추적 id 같은 것들이요. 인증 정보를 넣는 자리가 아니고, 검증기는 표준 자격증명 헤더 이름(Authorization, X-Api-Key, Cookie 등)을 apiKey / authMode를 쓰라는 안내와 함께 거부합니다.

다만 X-My-Token 같은 임의 이름까지 알아볼 수는 없으니 그 경계는 사용자가 지켜야 합니다. 이유는 두 가지입니다.

• JSON이 명령줄 인자라서, 비밀이 들어가면 셸 히스토리와 프로세스 목록에 남습니다. CLI가 무엇을 가리기도 전에 같은 머신의 다른 프로세스가 읽을 수 있습니다.
• 헤더 값은 config.json에 평문으로 저장됩니다. 별도 저장·마스킹 경로가 있는 API 키와 다릅니다.

비밀에 해당하는 값은 --api-key나 OAuth 로그인을 쓰세요.

키 없는 CC-Switch 프로바이더 가져오기

ocx provider import-cc-switch --source ~/.cc-switch/cc-switch.db
ocx stop
ocx provider import-cc-switch --source ~/.cc-switch/cc-switch.db --provider my-provider --apply
# 다른 터미널에서 프록시를 시작(또는 ocx ensure 실행)한 뒤 키를 등록:
ocx start
printf '%s\n' "$API_KEY" | ocx account add-key my-provider

# 별도의 롤백 경로(먼저 프록시를 중지; 수정되지 않은 키 없는 항목만 제거):
ocx stop
ocx provider import-cc-switch --restore

ocx provider import-cc-switch는 일반 CC-Switch SQLite 데이터베이스나 레거시 JSON 파일에서 명시적으로 허용된 비비밀 메타데이터 필드(프로바이더 ID, 앱 유형, 기본 URL, 프로토콜 어댑터, 기본 모델)의 값만 투영합니다. 입력을 스캔하기 위해 소스와 내장 설정 바이트를 일시적으로 읽지만, 비밀 필드·자유 텍스트 표시 이름·TOML 주석은 바이트 수준에서 건너뛰어 문자열로 디코딩하거나 기록·로깅하지 않으며 임시 바이트 버퍼는 finally에서 0으로 지워집니다. 좁은 기본 URL 경로 규칙(http(s)://host[:port]와 빈 경로 또는 /v1, /api/v1, /compatible-mode/v1 같은 1~4개의 소문자 [a-z0-9._-] API 경로 세그먼트)과 식별자/모델 구문 검사는 심층 방어로 동작하며 부적합한 값을 에코하지 않고 거부합니다. 소스 파일은 O_NOFOLLOW | O_NONBLOCK 디스크립터 검증과 함께 한 번만 열리고 SQLite는 임시 파일 없이 메모리에서 읽기 전용으로 역직렬화됩니다. 여러 하드 링크(nlink > 1)를 가진 SQLite 파일은 별칭 경로를 통한 사이드카 검사 우회를 막기 위해 거부되며, 인접한 -wal 또는 -journal 파일이 비어 있지 않으면 CC-Switch를 종료(또는 데이터베이스 체크포인트)한 뒤 다시 시도하라고 안내하며 거부합니다. 신뢰할 수 있는 로컬 CC-Switch 소스만 사용하고, 출력된 모든 ID·모델·baseUrl을 확인한 뒤 자격 증명을 추가하세요:

• 미리보기(기본값): --source <FILE>이 필요하며 아무것도 쓰지 않고 발견·적격·충돌·무효 항목 수를 보고합니다.
• 적용(--apply): --source <FILE>과 중지된 프록시(ocx stop)가 필요하며 Remote Link Child에서는 거부됩니다. 선택한 항목만 가져오려면 --provider <id>를 반복하고, 루프백이나 사설 네트워크 기본 URL을 허용하려면 --allow-private-network를 지정하세요. 사전 미리보기 없이 실행하더라도 --apply는 키 없는 프로바이더 항목과 롤백 저널($OPENCODEX_HOME/cc-switch-provider-import-journal.json)을 기록하기 전에 가져올 모든 프로바이더 ID·기본 모델·대상 URL을 먼저 출력합니다(텍스트 모드에서는 stdout, --json 모드에서는 stderr). 활성 저널이 있는 동안 두 번째 --apply는 거부됩니다. 출력된 항목을 확인한 뒤 프록시를 시작(다른 터미널에서 ocx start 또는 ocx ensure)하고 printf '%s\n' "$API_KEY" | ocx account add-key <provider>(파이프 표준 입력) 또는 ocx login <provider>로 자격 증명을 등록하세요.
• 복원(--restore): 자격 증명 추가의 연속이 아닌 별도의 롤백 경로로, 중지된 프록시(ocx stop)가 필요하며 Remote Link Child에서는 거부되고 --source·--provider·--allow-private-network는 받지 않습니다. auth.json을 바이트 수준에서 읽기 전용으로 검사(읽을 수 없거나 형식이 잘못되면 안전하게 보류)하며, 가져온 키 없는 상태와 여전히 일치하고 defaultProvider로 선택되지 않았으며 라우팅·콤보(combos)·폴백 정책(fallback policy)·OAuth 계정·API 키 어디에서도 참조되지 않은 프로바이더만 활성 저널에서 제거합니다.

인증

ocx login <provider>

제공자에 등록된 로그인 흐름을 시작합니다. OAuth 제공자는 브라우저를 열고 자동 갱신되는 자격 증명을 ~/.opencodex/ 아래에 저장합니다. API 키 로그인 제공자는 키 대시보드를 열고, 키 입력을 요청한 뒤, 가능한 경우 검증하고, 그 결과 나온 제공자 설정을 저장합니다. 이름이 없거나 알 수 없으면 현재 허용되는 OAuth 및 API 키 제공자 id를 출력합니다.

ocx status / ocx doctor가 재인증 필요 또는 터미널 새로고침 실패를 보고한 뒤에는 같은 명령으로 재인증하면 됩니다(대시보드의 Reauthenticate를 써도 됩니다). Codex 풀 계정은 위 OAuth·API 키 제공자 중 하나가 아니지만 ocx login codex로 닿습니다. 이 명령은 계정 풀 로그인으로 연결되므로 ocx login codex --reauth는 ocx account reauth codex와 같습니다. 대시보드의 Codex 계정 풀(Reauthenticate)로도 됩니다. 이 경로는 프록시 안에서 돌기 때문에 프록시가 실행 중이어야 합니다.

ocx login xai
ocx login anthropic

ocx logout <provider>

제공자에 저장된 OAuth 자격 증명을 제거합니다.

계정과 키 풀

메인 계정 사용량 보호

Codex 설정 → 다중 인증 → 고급 설정에서 Ultra Fast 옆의 메인 계정 차단이 기본으로 켜져 있습니다. 끄면 바로 적용되고, 다시 켤 때는 영향 안내가 먼저 나오며 취소하면 설정은 바뀌지 않습니다. 고급 설정을 접어도 메인 계정 카드에 보호 상태와 사용량 확인 필요 여부, 현재 차단 여부가 표시됩니다.

이 기본값은 메인 계정을 완전히 소진했을 때 Codex Desktop에서 벌어지는 일 때문입니다. ChatGPT 계정 창이 **0%**를 보고하면 Desktop은 전송 버튼을 비활성화하고, 창이 리셋될 때까지 그 계정으로 턴을 보낼 수 없습니다. ocx 트래픽이 그 지점까지 닿지 않게 막아 계정을 계속 쓸 수 있게 유지합니다 (#5694). 대가는 Luna Reserve입니다. 차단 중에는 그 메인 계정의 Reserve를 활성화할 수 없으므로, 메인 계정을 끝까지 쓰고 Reserve로 넘어가려면 스위치를 끄세요.

5h 창과 주간 창은 각각 따로 차단합니다. 5h 창이 90%, 주간 창이 98%에 닿으면 다른 창에 여유가 있어도 바로 차단합니다. 월간 전용 계정은 월간을 기준으로 합니다. 차단한 창이 모두 새 사용률 각 기준 미만(0% 리셋 포함)을 보고하면 자동으로 차단을 풀고, 스위치는 켜 둡니다. 이후 다시 각 기준에 닿으면 차단합니다. 5h 수치를 읽지 못해도 주간 차단은 그대로 유지됩니다. config.json의 codexMainAccountHardLockThresholds에 short와 long을 설정할 수 있습니다. 기본값은 { "short": 90, "long": 98 }입니다. 둘 다 80~100 범위의 정수여야 하고, short는 long보다 클 수 없습니다. 생략한 값은 기본값을 사용합니다. 설정 API도 같은 객체를 받으며 mainAccountHardLock.thresholds에 실제 적용값을 반환합니다.

같은 리셋 구간에서 최신 사용량이 1%포인트 이상 늘었는데 이 프록시를 통한 메인 계정 활동이 최근에 없었다면 대시보드와 ocx status에 opencodex 밖에서 사용량이 늘었을 수 있음을 표시합니다. 오래 실행한 턴도 같은 현상을 만들 수 있어 외부 사용의 확정 증거는 아닙니다. 외부 사용 때문에 차단해도 한도를 소진할 수 있습니다. 알림은 프로세스 메모리에만 유지되며 계정이나 리셋 구간이 바뀌면 지워지고, 6시간 경과 또는 관측한 리셋 시각 중 이른 시점에 만료됩니다. ocx status --json은 실행 중인 관리 API에서 읽은 상태, 적용 기준, 차단 창 종류와 선택적 externalUsage 알림을 mainAccountHardLock에 담습니다.

값이 빠진 응답을 0%로 보지 않으며, 이미 확인한 차단 수치를 누락된 응답만으로 지우지도 않습니다. 예정된 리셋 시간이 지났다는 이유만으로 풀지는 않습니다. 차단 중에는 1분 주기 점검이 알려진 차단 창의 리셋 시각까지 기다린 뒤 계정의 실제 사용량을 확인합니다. 이후에도 차단 상태이거나 미래 리셋 시각을 모르면 5·10·20·40·60분 간격으로 재시도하며, 더 긴 Retry-After가 있으면 프로필 및 토큰 준비도 그 시각까지 미룹니다. 유효한 최신 수치나 창이 없음을 명시한 응답만 차단을 해제합니다. Pool 모드에서 사용량 조회의 --refresh는 캐시 유효기간을 무시하지만 실패 후 대기 시간은 지킵니다. 조회가 연기되면 새 진단 시도로 기록하지 않습니다. 일시정지, 재인증, 서버의 사용량 제한은 별도로 적용됩니다.

새로운 유효한 WHAM 응답에서 1차 창이 24시간 이상이고 사용량 수치가 있으면 이전 5h 수치를 대체할 수 있습니다. 1차 창이 명시적 null이고 2차 창에 유효한 주간 사용량이 있어도 같습니다. 어느 경우든 2차·3차 창은 명시적 null이거나 기간이 24시간 이상이고 유효한 사용량 수치가 있어야 합니다. 파서의 단기·장기 구분 기준을 따르므로 주간·월간뿐 아니라 하루짜리 창도 해당합니다. 현재 장기 창에는 설정된 장기 기준(기본 98%)을 적용합니다. 이 판단은 응답 한 건의 정보에 의존하며 연속 관측을 요구하지 않습니다. 창 필드가 하나라도 생략되었거나, 창의 기간을 모르거나, 응답 헤더만 일부 도착한 경우에는 이전 차단을 해제하지 않습니다. 모든 창이 null이고 크레딧만 있거나, 보조 월간 수치만 있는 응답도 차단을 풀지 않습니다. 지연 응답을 반영하기 전에 저장된 인증정보를 다시 확인합니다. 파일을 읽을 수 없거나 같은 계정의 인증 토큰이 교체되었다면 별도 사용량 조회가 없어도 이전 응답은 사용량 캐시나 차단 상태를 갱신하거나 새 토큰을 재인증 대상으로 표시하지 않습니다. 해당 요청자에게 파싱된 조회 결과를 반환할 수는 있지만, 공유 상태나 차단 해제 근거에는 반영하지 않습니다. 계정 카드에는 공유 캐시에 반영된 사용량만 표시하여 차단 상태와 수치가 일치하도록 합니다. Direct 모드의 공급자 사용량 보고서에서도 공유 상태에 반영되지 않은 응답과 이전 캐시 보고서를 표시하지 않습니다. 계정 정보가 충돌하거나 이전 토큰의 401/403 응답이 늦게 도착한 경우에는 현재 캐시를 유지하고 재인증 상태를 변경하지 않습니다.

저장되는 옵션은 OpenCodex의 config.json에 있는 "codexMainAccountHardLock"입니다. 값이 없거나 true이면 켜짐이고, false일 때만 꺼집니다. 스위치를 끄면 이 false가 저장됩니다. 기본값이 바뀐 지점입니다. 예전에는 옵트인이었고 스위치를 끌 때 키를 지웠기 때문에, 꺼 두었던 설치도 지금은 켜진 상태로 읽힙니다. 예전 동작을 유지하려면 스위치를 한 번 꺼서 옵트아웃을 기록하세요. 식별된 메인 계정의 새 요청을 막는 기능이지 마지막 2%를 예약하는 기능은 아닙니다. 진행 중 요청, 식별되지 않은 키링 계정, 프록시 밖 요청은 사용량을 더 쓸 수 있습니다. 추가 계정과 다른 공급자는 계속 사용할 수 있습니다.

보호 기능이 켜져 있으면 소유권이 확인된 시작 과정에서 native 프로필 복구와 정리를 마친 뒤 메인 인증정보의 메모리 내 식별 연결을 복원하므로, 저장된 정책 차단이 재시작 후에도 유지됩니다. 연결을 준비하는 동안 호출자 인증정보를 쓰는 Direct, 메인 계정 지정, 메인 fallback, 메인 pin 요청은 잠시 503을 받을 수 있고, 저장된 Pool 계정은 그동안에도 그대로 쓸 수 있습니다. 이 초기화를 위해 다른 서비스 소유이거나 소유권이 미확인인 홈의 인증정보를 읽지는 않습니다.

차단 중에는 해당 메인 계정의 Luna Reserve도 쓸 수 없습니다. 일반 사용량이 소진되지 않으면 Reserve가 활성화되지 않을 수 있습니다. 스위치를 끄면 원래 처리 방식으로 돌아가지만 서버가 허용하는 사용량이 늘어나지는 않습니다. 계정의 사용량 새로고침으로 최신 수치를 확인할 수 있으며, 리셋 크레딧을 자동으로 소비하지는 않습니다.

Luna Reserve와 다른 공급자 모델 함께 쓰기

선택 기능인 Desktop 로그인 생략 모드를 쓰면 Desktop의 Reserve 전용 모델 선택 제한이 작동하지 않습니다. 대신 Desktop의 자동 Reserve 전환도 꺼지므로, Reserve는 직접 선택해야 합니다.

기본 OpenAI 공급자를 ChatGPT 전달 모드로 켜 두고, 계정별 모델 선택기를 켠 뒤 저장된 메인 계정의 공개 선택자 이름을 지정합니다. 로컬 루프백 로그인 생략 모드가 실제로 적용된 상태에서 ocx sync를 실행하면 <메인-선택자>/gpt-reserve가 다른 공급자 모델과 함께 추가됩니다. 접두사 없는 gpt-reserve, 추가 계정 선택자, API 키용 모델 목록에는 추가하지 않습니다. 원격 클라이언트나 별도 접근 헤더가 필요한 리스너에서는 이 모드를 적용하지 않습니다. 공개 리스너와 로컬 리스너를 함께 켜도 Reserve 호환 모드는 로컬 리스너로 받은 요청에만 적용됩니다. 같은 컴퓨터에서 보냈더라도 공개 리스너로 인증한 요청은 원래 경로를 유지하며, 요청 헤더로 로컬 정책을 고를 수는 없습니다.

ocx system settings --desktop-authless on으로 Desktop 로그인 생략 모드를 켜고, ocx sync를 실행한 다음 Codex Desktop을 완전히 종료했다가 다시 여세요. 다시 쓴 설정과 모델 목록을 읽으려면 이 순서가 필요합니다. 자세한 절차는 Desktop 로그인 생략 모드 가이드를 따르세요.

각 요청은 해당 자격 증명에 묶인 서버 허용 결과를 확인하며, 캐시는 최대 60초만 유지합니다. 메인 계정 사용량을 조회할 때 Reserve 기능 헤더를 보내고, 일반 사용량 불허·Luna Reserve 안내· 허용된 Reserve 항목 하나가 모두 있는지 확인합니다. 근거가 없거나 오래됐거나 계정이 맞지 않으면 요청을 거절합니다. 다른 계정이나 일반 Luna로 몰래 바꾸지 않습니다. 일반 사용량 조회는 기존 허용을 취소할 수 있지만 새로 허용하지는 않습니다.

전체 쿨다운, 일시정지, 재인증, 메인 계정 하드락은 여전히 적용됩니다. 소진된 메인 계정에서 Reserve를 쓰려면 하드락을 꺼야 하지만, 껐다고 서버의 사용 권한이 생기지는 않습니다. 이 호환 경로는 대화와 대화 압축용입니다. 이미지 설명·웹 검색 보조 모델이나 독립 검색 릴레이에 Reserve를 지정하는 용도는 지원하지 않으므로, 그 기능에는 다른 모델을 선택하세요.

모델 정보는 실제 Reserve 관측값을 우선합니다. 없으면 Desktop의 Reserve/Luna 매핑을 참고한 Luna 메타데이터임을 표시해 사용합니다. 목록에 보인다는 사실만으로 사용 가능하다고 보장하지 않습니다. Desktop 소스와 테스트용 응답 경로를 확인했으며, 실제 Reserve 활성 계정으로는 이 호환 경로를 검증하지 않았습니다.

ocx account <subcommand>

실행 중인 프록시를 통해 제공자 계정과 API 키 풀을 나열하고 전환합니다. 제공되는 도움말 표면은 다음과 같습니다:

Usage: ocx account <list|history|current|use|clear|refresh|auto-switch|alias|priority|pause|resume|pause-exhausted|strategy|sticky|remove|clear-cooldown|add-key|import|import-orca|login|reauth|code|cancel|reset-credits|grok-reset-coupons|main> ...

list [provider]     Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them).
history openai <pool-account-id> [--limit <1-200>]  Recent routing decisions for one Codex pool account.
current <provider>  Show the active account or key.
use <provider> <id|alias|main|auto> Switch the active credential; 'main' selects the Codex App login, 'auto' clears the selection unless an account carries that id.
clear <provider>  Clear the manual Codex account selection unconditionally.
refresh <provider>  Force-refresh Codex or provider quota reports.
auto-switch <provider> <on|off|status|threshold N>  Control the Codex pool threshold.
alias <provider> <id|alias> <display-name|->  Set or clear an account's display name; '-' clears it.
pause <provider> <id|alias|main>  Hold an account out of automatic selection.
resume <provider> <id|alias|main>  Return a paused account to automatic selection.
pause-exhausted <provider>  Pause every account whose quota is spent.
clear-cooldown <openai|anthropic> <id|alias|main>  Drop a cooldown the proxy set after an upstream failure.
strategy <provider> [<quota|round-robin|fill-first|reset-first>]  Pool placement strategy; omit the value to read it.
sticky <provider> [<1-100>]  Requests a bound thread keeps on one account; omit the value to read it.
priority <provider> <id|alias|main> [first|earlier|normal|later|last|-100..100|reset]  Selection order; omit the value to read it.
remove <provider> <id|alias|main> --yes  Remove a stored account or key after an existence check.
add-key <provider> [--label <label>]  Add a key read only from piped stdin.
login/reauth/code/cancel  Run browser or manual-code auth from a headless shell.
reset-credits <id|main> [--consume --yes]  Inspect or consume Codex reset credits.
grok-reset-coupons [<id>] [--consume --yes] [--token-id <token-id>] [--operation-id <uuid>]  Inspect or redeem Grok reset coupons.
import <provider> --format <format> (--file <path>|--stdin)  Import credentials from a named external format.
import-orca --source <dir> --registry <file> [--apply]  Preview or apply imports from Orca-managed Codex homes.
main <doctor|list|register|add|reauth|switch|recover>  Manage the Codex App login the pool calls 'main'.
Codex pool selection applies to the next request after clearing existing affinity; in-flight requests keep their captured account.

하위 명령은 프록시가 실행 중이어야 하며 기록된 런타임 포트를 자동으로 찾습니다. 다만 import-orca는 예외로, 미리보기는 로컬 전용이고 import-orca --apply는 프록시가 멈춰 있어야 합니다. 성공한 작업은 종료 코드 0으로 끝납니다. 잘못된 사용, 알 수 없는 제공자 또는 계정/키 id, 도달할 수 없는 프록시, API 실패는 종료 코드 1로 끝납니다. 자격 증명 필드는 관리 API가 반환한 그대로 표시됩니다(마스킹도 그대로 포함됩니다). 원시 API 키와 OAuth 토큰은 절대 반환하지 않습니다. 표시 편의 기능은 대시보드와 마찬가지로 클라이언트 쪽에서 합성합니다. main은 openai 계정 풀의 Codex App 로그인에 대한 CLI 별칭이고, 이메일이 없는 OAuth 계정은 Account N으로 표시되며, plan/label 열은 plan, 마스킹된 이메일, label, 마스킹된 키 순으로 대체합니다.

--json 계정 행은 다음 공통 형태를 사용합니다(사용할 수 없는 필드는 생략됩니다):

{
  "provider": "openai",
  "type": "codex | oauth | api-key",
  "id": "__main__",
  "label": "plus",
  "email": "m***@example.com",
  "plan": "plus",
  "priority": 0,
  "masked": "sk-ab****wxyz",
  "active": true,
  "needsReauth": false,
  "quota": null
}

ocx account list [provider] [--json] [--all] [--quota [--refresh]]

저장된 ChatGPT 풀 계정은 네이티브 Codex 홈이 없는 호스트에서도 대시보드와 계정 새로 고침을 포함해 계속 나열할 수 있습니다. 목록 조회는 Codex 홈을 만들거나 네이티브 메인 계정에서 로그아웃하지 않습니다. Codex 클라이언트 통합을 비활성화해도 기존 네이티브 로그인의 할당량 관측은 비활성화되지 않습니다. 명시적으로 지정한 CODEX_HOME 경로가 유효하지 않으면 계속 설정 오류를 반환합니다. OPENCODEX_HOME 저장소가 안전하지 않으면 네이티브 Codex 홈이 없어도 오류를 반환합니다. 기본 Codex 홈의 경로를 확인할 때도 파일, 대상이 없는 심볼릭 링크, 탐색할 수 없는 상위 디렉터리는 오류를 발생시킵니다.

제공자를 지정하지 않으면 Codex 풀, OAuth 계정, 설정된 API 키 풀을 나열합니다. --all이 없으면 비어 있는 제공자는 건너뜁니다. 제공자를 지정하면 해당 자격 증명 계열만 나열합니다. 사람이 보는 출력은 PROVIDER TYPE ID PLAN/LABEL PRIORITY STATUS 형식을 사용하며, 수동으로 선택한 Codex 행에는 selected가 표시됩니다. 사용 가능한 Kiro 계정이 두 개 이상 저장되어 있으면 기본적으로 429 응답 시 다른 계정으로 자동 전환하며, 알려진 잔여 할당량이 가장 많은 계정을 우선합니다. 이 전환은 계정 존재만으로 활성화되며 끌 수 없습니다. oauthAccountFailover.enabled: false는 429 복구가 아니라 요청을 보내기 전 계정을 고르는 동작만 거부합니다. ocx account login kiro는 계정을 한 번에 하나씩 풀에 추가합니다. 빈 결과도 성공입니다. --json은 다음을 반환합니다:

{ accounts: AccountRow[], notes: string[] }

Codex JSON 행에는 등록된 id와 같은 slotId, 그리고 native-main 또는 pool인 slotKind가 포함됩니다. 프록시가 상위 계정과 사용자 식별값을 모두 확인하면 uai1_ 뒤에 소문자 16진수 64자리가 붙는 upstreamAccountKey도 제공합니다. 같은 openai 제공자에서 키가 같으면 한 상위 사용자의 슬롯이며, 각 슬롯과 한도 상태는 그대로 유지해야 합니다. 키는 이 설치 환경에 한정되고 관리자 토큰이 바뀌면 달라질 수 있습니다. 키가 없을 때는 가려진 이메일이나 한도가 비슷하다는 이유로 묶지 않습니다. 상위 계정 ID·사용자 식별값·인증 정보 원문은 목록에 포함되지 않습니다.

ocx account current <provider> [--json]

활성 계정이나 키를 보여줍니다. 수동 고정이 없는 Codex 풀은 우선순위를 고려한 자동 선택을 보고합니다. 가장 우선순위가 높은 적격 tier를 고르고, 그 tier 안에서 할당량 라우팅 기준으로 가장 적게 사용한 항목을 선택합니다. 활성 자격 증명이 없는 다른 계열은 그 상태를 보고하고도 종료 코드 0으로 끝납니다. --json은 다음을 반환합니다:

{ provider, type, activeId: string | null, autoSwitchThreshold?: number, account: AccountRow | null }

ocx account use <provider> <account-or-key-id|alias|main|auto> [--json]

auto는 수동 선택을 지워 풀이 다시 자체 전략으로 작업을 배치하게 합니다 — 단 id가 auto인 Codex 계정이 있으면 정확한 id 일치가 우선되며 ocx account clear <provider>는 항상 자동 선택을 복원합니다. Codex 계정은 id 대신 ocx account alias로 지정한 별칭으로도 가리킬 수 있으며, priority, pause, resume, clear-cooldown, remove, alias에서도 마찬가지입니다. Codex 계정에서 auto, main, __main__은 대소문자 구분 없이 예약어이므로 별칭으로 지정할 수 없습니다. OAuth 계정과 API 키의 표시 이름에는 기존 규칙이 그대로 적용됩니다.

기존 Codex 계정, OAuth 계정 또는 API key를 선택합니다. openai에서 main은 Codex App 로그인을 선택합니다. Codex Pool 선택은 프로세스 로컬 affinity를 지우고 기존에 보이던 작업을 포함한 다음 요청부터 적용됩니다. 프록시 재시작이나 affinity eviction 뒤에도 작업이 바인딩 없는 상태가 될 수 있지만, 진행 중인 요청은 이미 확보한 계정을 유지합니다. 이 선택은 Pool 라우팅만 제어하며 Direct mode는 호출자 소유/native main credential을 계속 사용합니다. 사용량 기반 선제 전환, 401/403 재인증, 429/retry-after cooldown, 제외, 출력 전 429/402 실패 복구는 나중에 다른 적격 Pool 계정을 선택할 수 있습니다. 이러한 복구 경로는 사용량 기반 전환이 꺼져 있어도 동작합니다. 계정이 바뀌어도 OpenCodex는 대화 문맥을 재생하지만 프로바이더 측 prompt cache는 다시 예열해야 할 수 있습니다. 알 수 없는 프로바이더나 id는 종료 코드 1입니다. --json은 다음을 반환합니다. 401/403이 발생하면 해당 계정의 프로세스 로컬 affinity를 해제하고 재인증을 요구합니다. 429에서는 Retry-After를 준수해 계정 cooldown을 시작하고 affinity를 해제한 뒤, 다른 적격 Pool 계정으로 요청을 전환할 수 있습니다. 이러한 실패 복구는 autoSwitchThreshold: 0에서도 계속 작동하며, 0은 사용량 기반 선제 전환만 비활성화합니다.

{ ok: true, provider, type, activeId }

ocx account pause|resume anthropic <id|alias> [--json]

Anthropic의 자동 대체 계정 선택은 기존 계정 순서를 유지하며, 일시 정지되었거나 재인증이 필요한 계정과 60초 이내에 만료되는 Claude Code 가져오기를 건너뜁니다. 출처가 기록되지 않은 레거시 계정도 선택할 수 있지만, 자체 저장 자격 증명과 일반적인 저장 토큰 갱신만 사용하며 CLI 디스크 자격 증명을 가져오지 않습니다. 60초 넘게 남은 유효한 Claude Code 계정은 선택할 수 있습니다. 이후 자동 가져오기는 비어 있지 않은 access 또는 refresh 토큰이 일치하면 허용됩니다. 두 토큰이 모두 바뀌면 저장된 bearer와 새 bearer에서 인증된 계정 UUID가 같아야 합니다. 로그인·갱신·프로필 조회에서 얻은 증명은 비공개로 저장하며, 계정 라벨·이메일·조직·파일 경로로 대체하지 않습니다.

기존 bearer가 만료되었고 해당 토큰에 묶인 계정 증명이 없으면 자동 복구가 불가능할 수 있습니다. 프로필을 조회할 수 없거나 교체된 토큰의 계정을 확인하지 못하면 저장된 계정을 유지하고, 이미 소비되었을 수 있는 refresh 토큰을 다시 사용하지 않습니다. 현재 Claude Code 자격 증명을 가져오려면 명시적으로 로그인하세요. 가져오기는 관련 없는 신원 미확인 슬롯을 보존하므로 별도 계정이 생길 수 있습니다. 사용할 계정을 선택하고 확인한 뒤 오래된 슬롯을 삭제하세요. 프로필 조회에 실패한 새 가져오기도 신원 미확인 상태로 남으며 같은 자동 복구 제한이 적용됩니다.

허용된 대체 계정이 없으면 사용 가능한 활성 계정이 선택될 때까지 할당량 조회와 실시간 모델 검색이 대기합니다. ocx account use anthropic <account-id-or-alias>로 일시 정지되지 않은 기존 레거시 계정을 명시적으로 선택할 수 있습니다. 원래 자격 증명의 출처가 기록되지 않았더라도 해당 계정의 유효한 자격 증명과 일반적인 저장 토큰 갱신을 계속 사용할 수 있습니다.

CLI 명령은 Anthropic OAuth 계정을 id 또는 유일한 alias로 일시 정지하거나 재개합니다. alias는 정확히 일치하는 값을 먼저 찾고, 없으면 대소문자를 구분하지 않고 찾습니다. 대시보드와 같은 PUT /api/oauth/accounts/pause에 { provider: "anthropic", accountId, paused }를 보냅니다. 계정에 저장되는 paused 상태는 GET /api/oauth/accounts에도 표시됩니다. 사전 계정 전환 풀이 꺼져 있어도 정지된 계정은 선택, 세션 바인딩, 429 대체 후보에서 제외됩니다. 모든 계정이 정지되면 하나를 재개할 때까지 요청은 403을 반환합니다. 이미 전송한 요청은 유지하며 자격 증명과 건강 상태를 지우지 않습니다. 재시작·재로그인 후에도 정지는 유지되고, 계정을 삭제하면 함께 제거됩니다. 계정별 전환 임계값은 이 기능에 포함되지 않습니다.

ocx account clear <provider> [--json]

계정 id를 해석하지 않고 Codex 계정의 수동 선택을 지우므로 auto라는 id의 계정이 있어도 동작합니다. Codex 풀 전용이며 다른 공급자 유형에는 복원할 자동 선택이 없습니다.

ocx account clear-cooldown <openai|anthropic> <id|alias|main> [--json]

저장된 자격 증명은 바꾸지 않고 프로세스 로컬 실패 cooldown을 해제합니다. Codex Pool 계정에는 openai, Anthropic OAuth 계정에는 anthropic을 사용하며 다른 provider는 거부됩니다. 두 경로 모두 계정 id 또는 고유 alias를 받지만 main은 Codex Pool에서만 사용할 수 있습니다.

ocx account clear-cooldown anthropic <id-or-alias>

활성 cooldown이 없어도 명령은 성공하고 JSON에는 cleared: false가 표시됩니다. Anthropic cooldown을 해제하면 계정 generation도 전진하므로 이전 quota probe가 해제된 상태를 되살리거나 오래된 quota 기반 eligibility를 게시할 수 없습니다.

API 키 풀의 키별 할당량은 ocx account list <provider> --quota [--refresh] --json으로 조회합니다. --quota를 생략하면 할당량 확인을 요청하지 않습니다. 명시한 경우 공급자에 요청을 보낼 수 있으므로 반복 조회에 주의하세요. quotaMode, quotaUnavailable, 실제 quota를 함께 확인해야 하며, 측정하지 못한 값을 0으로 해석하면 안 됩니다. 공급자 전체 보고서를 읽는 아래 account refresh와는 별도 조회입니다.

ocx account refresh <provider> [--json]

Codex 풀에는 ocx account refresh openai [--json]를 사용합니다. 계정 할당량을 강제로 새로 고치고 사용 가능 주간/월간 비율과 재설정 시간을 출력합니다. 할당량 데이터가 없으면 0%가 아니라 알 수 없음으로 보고합니다. JSON 봉투는 { accounts: AccountRow[] }이며, Codex 행마다 quota가 붙습니다.

OAuth 및 API 키 제공자에는 제공자의 할당량 보고 엔드포인트를 강제로 새로 고칩니다. 토큰 재로그인이나 단순한 계정 목록 재읽기가 아닙니다. --json은 { provider, report: ProviderQuotaReport | null }를 반환합니다. 지원되는 할당량 보고가 없는 제공자는 no quota report available for <provider>를 출력하고 종료 코드 0으로 끝납니다. 알 수 없는 제공자와 관리 API 실패는 종료 코드 1로 끝납니다. 상위 할당량 확인이 실패하거나 시간 초과되면 대시보드의 할당량 막대와 맞추어 null 또는 오래된 보고로만 떨어집니다(종료 코드 0).

ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]

openai Codex 풀의 임계값을 제어하거나 일반 OAuth 풀의 임계값을 저장합니다. on은 80%, off는 0%, threshold <n>은 0–100을 저장합니다. 일반 풀의 임계값은 pool.kernel이 켜져 있고 strategy: "fill-first"일 때만 선택에 반영됩니다. 플래그가 꺼져 있으면 저장해도 임계값 기반 전환이 켜지지 않습니다. 어느 쪽이든 제공자 활성화 설정은 바뀌지 않고, 429 오류에 따른 회전도 비활성화되지 않습니다. 일반 풀의 조회와 변경 결과는 서버가 확인한 값을 사용합니다. 일반 풀의 poolEnabled는 저장된 제공자별 설정이며 null은 미지정입니다. 전역 설정을 상속한 실제 상태를 뜻하지 않습니다. inert: true는 임계값이 저장만 되고 적용되지 않는 상태, inert: false는 풀이 실제로 적용하고 있는 상태를 뜻합니다. inert가 아예 없으면 기능 지원을 알 수 없는 경우이며, 이때도 enabled: true로 표시하지 않습니다. API 키 제공자 및 잘못된 값은 거부합니다.

ocx account auto-switch anthropic … --account <id>

Anthropic OAuth는 ocx account auto-switch anthropic threshold 90 --account <id>로 계정별 정수 0–100을 저장합니다. off --account <id>는 0, on --account <id>는 80, inherit --account <id>는 상속 복원, status --account <id>는 조회입니다. --json도 지원합니다. 계정 카드에서 같은 사용자 지정 임계값을 편집합니다. 미설정/null은 풀 기본값 anthropicAccountPool.autoSwitchThreshold(기본 80)를 상속하고, 0은 해당 계정의 사용량 기반 전환만 끕니다. 재시작·재로그인 후에도 유지되고 계정 삭제 시 제거됩니다. 수동 선택, 세션 affinity, 사용량 미확인·전체 소진 시 fallback, 모델 경로 제한은 유지됩니다. 풀이 꺼져 있으면 임계값은 적용되지 않으며 pause와 429 복구는 계속 동작합니다.

openai: { provider, autoSwitchThreshold: number, enabled: boolean }
generic OAuth: { provider, autoSwitchThreshold: number | null, enabled: boolean, poolEnabled: boolean | null, inert: boolean | null }

ocx account priority <provider> <account-id|alias|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]

Codex pool 계정 하나의 선택 순서를 읽거나 설정합니다. 값이 클수록 먼저 쓰이고 기본값은 0, 범위는 -100부터 100까지입니다. 순서를 갖는 것은 openai Codex pool뿐이므로 다른 프로바이더는 종료 코드 1입니다. main은 Codex Desktop 로그인을 가리키며 다른 pool 계정과 똑같이 정렬됩니다. ocx account priority openai main last로 예비 계정으로 남겨 둘 수 있습니다.

프리셋 단어는 작은 정수의 다른 이름입니다. first는 +2, earlier는 +1, normal은 0, later는 -1, last는 -2입니다. reset은 기본값으로 되돌리고 저장된 항목을 지웁니다. 값을 생략하면 읽기가 되어 현재 순서를 바꾸지 않습니다.

순서는 어떤 계정을 먼저 볼지 정할 뿐 어떤 계정을 쓸 수 있는지는 정하지 않습니다. 선택은 여전히 적격한 계정 안에서 이루어지며, quota 여유가 남은 최상위 tier를 고른 뒤 그 안은 accountPoolStrategy가 정합니다. 일시 중지, cooldown, 재인증에는 영향을 주지 않습니다. 변경은 새 세션뿐 아니라 다음 미바인딩 요청 부터 적용됩니다. 상위 순서에 여유가 돌아오면 preemption이 미바인딩 요청을 곧바로 끌어올립니다. 이미 계정에 바인딩된 thread는 보통 그 계정이 소진될 때까지 유지하지만, 재인증 실패나 quota cooldown은 그보다 먼저 바인딩을 해제할 수 있습니다. 연속된 일시적 실패는 더 이상 live 바인딩을 삭제하지 않습니다. 받아들여진 쓰기는 어떤 계정에 걸려 있든 수동 “지금 이 계정 사용” 고정도 해제합니다. 이미 설정된 순서를 그대로 쓰는 경우에도 마찬가지이며, 이는 현재 선택된 계정을 그대로 두고 고정만 해제하는 유일한 방법입니다(관리 API로 활성 계정을 비우면 고정도 풀리지만 그 선택까지 사라집니다). 프록시에 연결할 수 없거나, 없는 계정 id, 허용되지 않는 값은 모두 종료 코드 1입니다. --json은 다음을 반환합니다.

{ ok: true, provider, id, priority: number, preset: string | null }

ocx account login|reauth|code|cancel ...

헤드리스 셸에서 브라우저나 수동 코드로 계정을 인증합니다. 제공자별 문법은 ocx account --help에서 확인하세요. Codex 로그인이 저장돼도 검증이나 모델 카탈로그 갱신이 남아 있으면 일반 출력과 --json 모두 종료 코드 1을 반환합니다. 저장된 로그인은 유지되므로 보류 상태만 보고 인증을 다시 시작하지 마세요. 일반 출력은 카탈로그 갱신이 보류됐을 때 stderr에 ocx sync 안내를 표시합니다. --json은 안내 문구 없이 상태와 보류 플래그를 stdout에 출력합니다.

ocx account remove <provider> <id|alias|main> --yes [--json]

이 보호된 비대화형 삭제는 --yes를 요구합니다. 삭제하기 전에 id가 존재하는지 확인하며, 없는 id는 DELETE를 보내지 않고 종료 코드 1로 끝납니다. Codex App의 main 로그인은 제거할 수 없으므로 remove openai main --yes는 거부됩니다. 삭제 후에는 해당 계열을 다시 읽습니다. 고정된 Codex 계정을 제거하면 고정이 풀리고 자동 선택으로 돌아갑니다. OAuth는 남아 있는 첫 번째 계정으로 승격하거나 없다고 보고합니다. API 키 풀은 남아 있는 첫 번째 키로 승격하거나 없다고 보고합니다. --json의 성공 및 실패 형식은 다음과 같습니다:

{ ok: true, provider, id, removedActive: boolean, promotedActiveId: string | null, catalogRefreshPending?: boolean }
{ error: string } // stderr, exit 1

catalogRefreshPending는 Codex 삭제에만 포함됩니다. true여도 삭제는 이미 저장되었으며 human output은 stderr에 ocx sync 안내를 표시하고 종료 코드 0을 유지합니다. OAuth account와 API key 삭제 형식은 바뀌지 않습니다.

ocx account add-key <provider> [--label <label>] [--json]

API 키 제공자에 키를 추가하고 활성화합니다. 키는 비TTY 파이프/리디렉션 stdin에서만 읽습니다. 대화형 TTY 입력, 빈 입력, OAuth/Codex 제공자, API 실패는 종료 코드 1로 끝납니다. 라벨 안에 들어 있더라도 키는 절대 출력되지 않습니다. 비밀 관리자나 here-string을 쓰는 편이 좋습니다:

ocx account add-key openrouter --label personal <<< "$OPENROUTER_API_KEY"
security find-generic-password -w openrouter | ocx account add-key openrouter --json

--json은 { ok: true, id: string | null, label?: string }를 반환하며 키를 절대 포함하지 않습니다.

ocx account reset-credits <id|main> [--consume --yes]

계정의 Codex reset credits를 확인합니다. credit을 소비하는 동작은 파괴적이므로 --consume와 --yes를 둘 다 요구합니다.

ocx account grok-reset-coupons [<account-id>] [--consume --yes [--token-id <id>] [--operation-id <uuid>]] [--json]

xAI / Grok 계정의 남은 reset coupon을 확인하거나 하나를 교환합니다.

--consume 없이 실행하면 사용 가능한 쿠폰 토큰과 유효 기간을 반환합니다:

ocx account grok-reset-coupons
ocx account grok-reset-coupons acc_xai_01 --json

reset coupon을 교환하면 billing 상태가 변경되고 쿠폰 토큰 하나를 영구적으로 소진합니다. --consume에는 --yes가 엄격하게 요구됩니다:

ocx account grok-reset-coupons --consume --yes
ocx account grok-reset-coupons --consume --yes --token-id <token-id>

--operation-id <uuid>(유효한 UUIDv4여야 함)를 전달하면 멱등한 정산이 보장됩니다. 네트워크가 끊기거나 명령이 재시도되더라도 동일한 operation id는 쿠폰을 다시 소진하는 대신 저장된 결과를 재생합니다.

ocx account main <subcommand>

OpenCodex 계정 풀 라우팅을 변경하지 않고 이름이 지정된 네이티브 Codex 기본 로그인 프로필을 관리합니다.

ocx account main doctor [--json]
ocx account main list [--json]
ocx account main register <label> [--json]
ocx account main add <label>
ocx account main reauth --device [--no-wait] [--json]
ocx account main reauth status --flow <id> [--json]
ocx account main reauth cancel --flow <id> [--json]
ocx account main switch <profile-id-or-label> --yes [--json]
ocx account main recover [--rollback --yes] [--json]

ocx account main reauth --device --no-wait --json은 성공 시 stdout에 JSON 객체 하나만 출력하며, 사람이 읽는 follow up: 안내 줄은 출력하지 않습니다. 반환된 flowId를 ocx account main reauth status --flow <id> --json에 지정하면 진행 상태를 확인할 수 있습니다.

각 변경 명령은 실행 중인 프록시가 반환한 정규화된 유효 CODEX_HOME을 표시합니다. 이 경로는 호출자의 CODEX_HOME과 다를 수 있으며, JSON을 지원하는 명령은 같은 값을 effectiveCodexHome으로 반환합니다.

버전 1은 파일 기반 Codex 인증을 지원하고 저장된 프로필을 AES-256-GCM으로 암호화하며 암호화 키를 운영 체제 자격 증명 저장소에 보관합니다. add는 생성된 자격 증명을 가져오기 전에 공식 Codex 로그인을 스테이징합니다. 프로필을 전환하기 전에 Codex를 종료하십시오. 전환에 성공하면 로컬 작업과 기록은 보존되지만 계속하기 전에 Codex를 다시 시작해야 합니다. doctor로 프로필 상태를 확인하고 recover로 중단된 전환을 완료하거나 롤백할 수 있습니다. switch에는 프로필 ID 또는 라벨을 지정할 수 있습니다.

v1 복구 매트릭스는 트랜잭션 파일이 rename으로 게시된 뒤 OpenCodex 프로세스가 종료되는 경우를 다룹니다. 운영 체제 또는 커널 충돌이나 갑작스러운 전원 손실에 대한 내구성은 보장하지 않습니다. atomicWriteFileAsync()는 파일이나 부모 디렉터리에 fsync를 수행하지 않습니다.

암호화된 볼트, 전환 저널, 복구 마커 및 저널 격리 파일은 정규 <real CODEX_HOME>/.opencodex-native-main-profiles 디렉터리에 저장됩니다. 따라서 해당 Codex 홈을 공유하는 모든 OpenCodex 인스턴스는 동일한 단일 소유자와 단일 복구 상태를 관찰합니다. 평문 로그인 스테이징은 각 <OPENCODEX_HOME>/native-main-profile-staging 디렉터리 아래에 서로 분리된 채 유지됩니다.

native-main 트래픽이나 저널 복구를 허용하기 전에 수명 주기 소유자가 자격 증명에 대한 배타적 점유권을 획득하고, 이름이 정확히 auth.json.ocx.<pid>.<sequence>.tmp인 충돌 잔여 파일만 제거합니다. 각 후보는 변경되지 않은 정규 CODEX_HOME 아래에서 하드 링크 수가 1인 일반 파일로 유지되어야 하며, 내용을 잘라내고 flush한 다음 unlink합니다. 링크나 재분석 지점(reparse point)으로의 바꿔치기, 파일 식별 정보 변경 또는 그 밖의 모호성이 있으면 native-main 트래픽은 계속 차단되며, 이름이 비슷할 뿐 정확히 일치하지 않는 파일은 자동으로 제거하지 않습니다. 이는 정상적으로 협력하는 OpenCodex 프로세스의 충돌을 방어하지만, 이미 같은 운영 체제 사용자로 실행 중인 악의적 프로세스까지 방어하지는 않습니다. 해당 사용자와 CODEX_HOME이 있는 파일 시스템은 계속 신뢰 대상으로 간주되며, 내용을 잘라내더라도 copy-on-write 저장소, 스냅샷 또는 SSD 잔류 데이터에서 물리적으로 지워진다고 보장할 수 없습니다.

프리뷰 빌드는 <OPENCODEX_HOME>/native-main-profiles를 사용했습니다. 이 레이아웃은 절대로 자동으로 가져오지 않습니다. doctor가 레거시 프로필 상태를 보고하면 동일한 CODEX_HOME을 공유하는 모든 OpenCodex 프록시를 중지하십시오. 그런 다음 해당하는 *.vault.json, *.journal.json, 복구 마커 및 참조된 journal-quarantine 파일을 백업하고, 소유자 전용 권한을 유지한 채 모두 함께 정규 디렉터리로 옮기십시오. 또는 이전 프리뷰 파일 세트를 제거하고 ocx account main register를 다시 실행하십시오. 동일한 CODEX_HOME을 공유하는 프록시가 하나라도 실행 중인 동안에는 여러 이전 루트 중 하나를 선택하거나 두 레이아웃을 동시에 사용하지 마십시오. Windows에서는 이전의 대소문자를 구분하지 않는 홈 식별자를 키로 사용한 프리뷰 상태를 옮기지 말고 재설정해야 합니다. 암호화된 AAD와 운영 체제 키링 식별자는 의도적으로 재사용하지 않기 때문입니다.

모델

ocx models [subcommand] · ocx model <subcommand>

ocx model은 ocx models의 별칭입니다. 하위 명령이 없으면 설정된 제공자에 사전 등록된 모델을 나열합니다. --provider는 설정된 제공자 하나를 필터링하고 --json은 모델 메타데이터를 반환합니다. live는 실행 중인 카탈로그를 읽습니다. add, edit, remove, list-custom은 수동 카탈로그 항목을 관리합니다. enable, disable, provider는 가시성을 제어합니다. selected는 제공자 허용 목록을 제어합니다. context는 제공자 컨텍스트 한도를 제어합니다. shadow는 백그라운드 shadow-call 가로채기를 관리합니다.

add·remove는 기본적으로 로컬 저장이며 --live를 주면 실행 중인 프록시를 바꿉니다. 로컬 --json 저장은 프록시가 없으면 sync.status: "not-attempted", needsSync: true, 종료 코드 0을 반환합니다. 실제 동기화 시도가 실패하면 저장은 유지하고 0이 아닌 코드로 끝납니다. list-custom은 로컬 목록입니다. 발견된 모델의 표시 이름은 raw upstream ID를 받는 display-name으로 바꾸고, picker 순서는 public ID를 받는 order로 바꿉니다. 영문 절차에서 전체 목록·featured 접두부·native 순서 초기화 제약을 확인하세요.

하위 명령	지원 플래그	동작
list (기본값)	--provider <name>, --json	설정된 제공자에 사전 등록된 모델을 나열합니다.
live	--provider <name>, --json	런타임에 발견된 모델을 포함해 실행 중인 카탈로그를 읽습니다. 행에는 native/routed, custom, enabled/disabled 표시가 붙습니다.
add <provider> <modelId>	--display-name <name>, --context-window <tokens>, --modalities <text,image,audio>, --live, --json	사용자 정의 모델을 로컬에 등록하거나 --live로 실행 중인 프록시에 등록합니다.
edit <custom-id>	--model-id <id>, --display-name <name|->, --context-window <tokens|0>, --modalities <text,image,audio|->, --json	사용자 지정 모델을 수정합니다. -는 필드를 지우고, 0은 컨텍스트 창을 지웁니다.
remove <custom-id|provider/modelId>	--yes, --live, --json	사용자 정의 모델을 삭제합니다. --live 또는 --json이면 --yes가 필요합니다.
list-custom	--json	다른 하위 명령이 사용하는 custom-id와 함께 모든 사용자 지정 모델을 보여줍니다.
enable <provider/model|native-model>	--native, --json	Codex에 하나의 모델을 보이게 합니다.
disable <provider/model|native-model>	--native, --json	Codex에서 하나의 모델을 숨깁니다.
provider <name> <on|off>	--json	한 제공자의 모든 모델을 한 번의 쓰기로 활성화하거나 비활성화합니다.
selected <provider>	--set <id,id...>, --clear, --json	제공자 모델 허용 목록을 읽거나 교체합니다. --clear는 허용 목록을 제거해 모든 모델을 제공하도록 합니다.
context <status|value <tokens> [--set-all]|provider <name> on [--value <tokens>]|provider <name> off|all <on|off>>	--json	전역 또는 제공자별로 컨텍스트 창 한도를 읽거나 설정합니다. value <tokens> --set-all은 모든 라우팅된 공급자에도 값을 다시 적용합니다(대시보드 토글과 동일). 지정하지 않으면 값은 기본값만 변경됩니다. provider ... on --value <tokens>는 해당 제공자에만 별도 한도를 설정합니다(--value는 on에서만 사용할 수 있습니다).
shadow <status|set> [model|-]	--enabled <on|off>, --json	Codex의 백그라운드 헬퍼 호출에 사용할 대체 모델을 읽거나 설정합니다. -는 모델을 지웁니다. status는 프록시가 가로채는 헬퍼 슬러그인 sourceModels도 보고합니다(기본값: gpt-6-luna, gpt-5.6-luna; 0.144.x 이하 클라이언트가 사용한 gpt-5.4-mini는 명시적인 sourceModels 재정의로 복원할 수 있습니다).

ocx models live --json                                  # what Codex can actually see right now
ocx models disable anthropic/claude-haiku-4             # hide one routed model
ocx models enable gpt-5.6-sol                           # no slash, so it is treated as native
ocx models provider zenmux off                          # hide a noisy provider wholesale
ocx models selected anthropic --set claude-opus-5,claude-fable-5
ocx models selected anthropic --clear                   # drop the allowlist again
ocx models add deepseek deepseek-v4 --display-name 'DeepSeek V4' --context-window 128000 --modalities text,image
ocx models list-custom --json                           # read the custom-id for edit/remove
ocx models remove deepseek/deepseek-v4 --yes

슬래시가 있는 모델 선택기는 라우팅됩니다(anthropic/claude-opus-5). 슬래시가 없는 id는 native OpenAI 모델로 취급되므로, 라우팅된 것처럼 보일 수 있는 id에 대해 그 읽기를 강제하려면 --native가 필요합니다.

--modalities는 text, image, audio만 허용합니다. Codex는 이 필드를 닫힌 enum으로 해석하고 다른 값이 하나라도 있으면 카탈로그 전체를 거부하므로, add, edit, 관리 API는 나중에 카탈로그 작성기가 정리해야 할 값을 저장하지 않도록 잘못된 값을 바로 거부합니다(#759).

저장된 쿼터 기록

ocx account history openai <pool-account-id> [--limit 1-200] [--json]은 제공자에게 요청하지 않고 저장된 관측을 읽습니다. 관측 시각, WHAM·응답 헤더 출처, 한도 종류와 사용률을 구분해 표시합니다. 계정마다 최대 200개를 30일간 보관하며 전체 저장량에도 제한이 있습니다.

일반 토큰 갱신은 기록을 유지합니다. 재로그인·삭제·계정 교체는 이전 기록과 분리합니다. 네이티브 메인 계정과 로그인 저장 전 조회는 포함하지 않습니다. 기록이 없다는 것은 관측 부족이며 사용량 0을 뜻하지 않습니다. 이 명령은 쿼터를 소비하지 않습니다. 관측을 바탕으로 한 용량 추정에는 아래 한계가 적용됩니다.

같은 초기화 구간의 관측과 계정별 사용 기록이 있으면 보고된 토큰 기준 용량 추정도 표시합니다. 표본 수와 낮은 신뢰도를 함께 표시하며, 쿼터 반올림·외부 사용량·로그 라벨 유지 여부 때문에 제공자의 실제 토큰 한도와 다를 수 있습니다. 기록이 없거나 잘렸으면 근거 부족으로 표시합니다. --limit은 표시할 기록 수만 제한하며 추정 입력은 전체 보관 범위입니다.