CLI 수명 주기

이 명령들은 로컬 opencodex 프록시와 Codex 연동을 설치, 실행, 점검, 복구, 업데이트합니다.

설정

`ocx init` · `ocx setup`

대화형 설정 마법사입니다 (setup은 init의 별칭입니다). 공급자(프리셋 또는 사용자 지정), API 키(리터럴 또는 ${ENV}), 기본 모델, 프록시 포트를 묻고 ~/.opencodex/config.json에 저장합니다. 원하면 프록시를 $CODEX_HOME/config.toml(기본값 ~/.codex/config.toml)에 주입하고, Codex 자동 시작 shim도 설치합니다.

프록시 수명 주기

`ocx start [--port <port>]`

프록시 서버를 시작합니다(권장 포트는 10100). 해당 포트가 이미 사용 중이면 opencodex가 다른 사용 가능한 포트를 골라 기록합니다. PID와 런타임 포트 상태를 기록하고, 두 번째 활성 인스턴스는 시작하지 않습니다. 시작할 때는 각 공급자의 모델을 Codex 카탈로그로 동기화합니다. 종료할 때는 기본 Codex를 복원합니다. 단, 관리형 서비스로 실행한 경우(OCX_SERVICE=1)는 예외입니다.

ocx start
ocx start --port 8080

`ocx stop`

실행 중인 프록시를 PID 기준으로 중지하고, PID 파일을 삭제한 뒤 기본 Codex를 복원합니다. 관리형 백그라운드 서비스가 설치되어 있으면 ocx stop이 먼저 그 서비스를 중지하므로 프록시가 다시 올라올 수 없습니다. 웹 대시보드의 Stop 버튼도 같은 동작(POST /api/stop)을 하지만, Windows 작업 스케줄러는 예외입니다. 작업이 끝나도 래퍼가 프록시를 다시 띄울 수 있어서, 대시보드는 respawnable_service로 거절하고 아무것도 바꾸지 않은 채 ocx stop 실행을 안내합니다.

프록시가 종료된 것만으로 Codex/Grok 공유 설정 복원까지 성공했다고 판단하지 않습니다. 종료 응답이 실패를 보고하거나, 읽을 수 없거나, 요청한 복원 처리 방식을 확인해 주지 않으면 기존 소유권·재시작 검사를 거친 부모 CLI가 복원을 맡습니다. 이미 종료가 확인된 프로세스를 강제 종료하는 경로로는 넘어가지 않습니다. 영수증에 근거한 지연 복원도 최종 복원과 영수증 정리를 부모가 담당하며, 부모의 공유 설정 복원이 실패하면 종료 실패로 남기고 미완료 영수증을 보존합니다.

`ocx restart`

프록시가 실행 중이면 확인된 정확한 PID와 포트에 in-place 재시작을 요청하고, 정상 드레인을 기다린 뒤 같은 포트에 다른 런타임 PID가 올라왔는지 확인합니다. 이 과정에서 관리형 라우팅과 서비스 감시는 유지되며, 요청 결과가 불확실해도 별도의 stop/start로 재실행하지 않습니다. 실행 중인 프록시가 없을 때만 일반 ensure 시작 동작으로 전환합니다. 실행 중인 리스너를 런타임 PID로 증명할 수 없으면(업데이트 전 프록시 포함) ensure나 stop/start 대체 동작 없이 안전하게 실패합니다. 소유권을 확인한 뒤 ocx stop과 ocx start를 순서대로 한 번 실행하세요.

중지·업데이트 후 포트 회수 중에는 종료 전에 기록한 PID라도 OCX 프로세스 확인 실패를 무시하지 않습니다. 확인이 거부된 살아 있는 프로세스는 종료하지 않으며 TCP 연결 정보도 정리하지 않습니다. 계속 확인할 수 없으면 포트가 사용 중인 채로 대기 제한 시간에 도달할 수 있습니다. 현재 포트 사용 프로세스를 확인하고 충돌을 해소한 뒤 재시작을 다시 시도하세요.

`ocx ensure`

백그라운드 프록시가 실행 중인지 멱등적으로 보장한 다음, 살아 있는 모델 카탈로그를 동기화합니다. codexAutoStart가 false이면 자동 시작이 비활성화되었다고 출력하고 아무것도 하지 않습니다.

`ocx restore [back]` · `ocx eject [back]`

프록시를 중지하지 않고 기본 Codex를 복원합니다. 주입된 설정 줄과 라우팅된 카탈로그 항목을 제거하므로 일반 codex가 다시 네이티브로 동작합니다. eject는 restore의 별칭입니다.

복원된 카탈로그에서는 gpt-5.3-codex-spark 등 지원이 종료된 네이티브 모델의 bare id와 신뢰된 계정 한정 항목을 제외합니다. 카탈로그 백업 유무와 관계없이 적용되며, 원본 백업과 사용자가 저장한 과거 모델 선택 설정은 보존합니다.

저장된 저널에 해당 파일의 주입 상태 해시가 없으면, 변경된 설정 파일을 덮어쓰는 대신 복원 실패를 보고합니다. 현재 파일과 저널은 검토용으로 보존됩니다. 해시 없는 저널의 복구 규칙을 참고하세요.

둘 중 어느 표기든 back을 붙이면 이미 실행 중인 프록시를 가리키도록 일반 codex를 다시 연결하되, 프록시 수명 주기는 바꾸지 않습니다.

ocx restore back
ocx eject back

`ocx recover-history --legacy-openai --yes`

역방향 복구 지원이 생기기 전, 초기 개발 빌드에서 Codex App 기록을 재매핑하던 오래된 빌드를 위한 명시적 복구 명령입니다. 기록 데이터베이스가 잠겨 있으면 먼저 Codex를 종료해 주세요.

이 명령은 광범위하고 파괴적인 재태깅입니다. 사용자 메시지가 있고 현재 opencodex로 표시된 모든 thread를 openai로 바꾸고, exec를 cli로 정규화하며 event marker를 설정합니다. 정상적인 dedicated-provider history도 포함됩니다. 상태를 백업하고 이 전체 범위를 의도한 경우에만 실행하세요.

`ocx recover-history --ocx-compaction <thread-id> --yes`

라우팅된 provider를 통해 압축된 작업을 native Codex에서 다시 열기 전에 해당 기록을 복구합니다. 이 명령은 UUID로 정확히 하나의 작업을 선택하고 비공개 바이트 단위 백업을 저장한 뒤, OpenCodeX가 소유한 ocx1: 압축 상태만 native Codex가 재생할 수 있는 일반 요약으로 변환합니다. native 암호화 콘텐츠와 다른 작업은 변경하지 않습니다. 실행 전에 선택한 작업을 닫으십시오. 처리 중 rollout이 변경되면 파일을 교체하지 않고 복구를 중단합니다.

`ocx uninstall` · `ocx remove`

서비스와 프록시를 중지하고, 서비스와 Codex shim을 제거한 뒤, 기본 Codex를 복원합니다. 그 다음 복원 단계가 모두 성공했을 때만 opencodex 로컬 설정을 제거합니다. remove는 uninstall의 별칭입니다. 설정 정리에는 새 설치로 만들어진 소유권 메타데이터가 필요하며, 오래된 디렉터리나 공유 디렉터리는 그대로 남깁니다.

상태 및 헬스

`ocx status [--json]`

status와 ocx doctor는 현재 CLI와 실행 중인 프록시의 버전을 비교합니다. CLI가 더 새로우면 원하는 최신 설치로 프록시를 재시작하십시오. 백그라운드 서비스라면 ocx service restart를 실행합니다. 버전 불일치는 서비스 정의를 그대로 두기 때문에 ocx service repair는 아무것도 reload하지 않고 예전 프로세스가 계속 서비스합니다. 프록시가 더 새로우면 CLI를 업그레이드하거나 PATH가 원하는 설치를 가리키도록 수정하십시오. 이 진단은 서비스를 복구하거나 요청 허용 여부를 바꾸지 않습니다.

버전 문자열이 같거나 어느 쪽이 unknown / 0.0.0이면 경고하지 않으며, 프록시 버전이 없어도 경고하지 않습니다. doctor는 placeholder를 버전 일치로 확정하지 않습니다. 엄격한 SemVer로 해석할 수 없는 서로 다른 문자열이나 build metadata만 다른 버전은 어느 쪽이 오래됐다고 단정하지 않는 중립 경고를 표시합니다. 공백을 제거하거나 앞의 v를 정규화하지 않습니다. JSON의 versionSkew에도 같은 안내가 들어가며 필드는 cliVersion, proxyVersion, skewed, warning 그대로입니다.

읽기 전용 진단 요약을 출력합니다. 프록시 PID, /healthz 도달 가능 여부, 대시보드 URL, 설정 경로, 기본 공급자, Codex 자동 시작 설정, 서비스 상태, shim 상태, 그리고 마스킹된 실제로 적용되는 Codex 홈이 포함됩니다. 명시적이고 높은 신뢰도의 Windows Orca 런타임 홈 시그니처만 실행 가능한 App 홈 불일치 경고를 추가하며, CODEX_HOME을 자동으로 바꾸지는 않습니다.

일반 출력에는 OAuth 로그인 요약 뒤에 OAuth health 블록도 표시합니다. 모든 알려진 계정이 정상이면 OAuth health: ok를, 그렇지 않으면 OAuth health: warning과 함께 건강하지 않은 각 계정마다 한 줄씩(공급자, 마스킹된 계정 ID, 재인증 필요, 속도 또는 할당량 제한, 갱신 충돌 같은 상태), 그리고 선택적인 Action: 힌트를 보여줍니다. 계정 ID는 마스킹되며 토큰과 이메일은 절대 출력하지 않습니다. --json 계약에는 이 헬스 블록이 아직 포함되지 않습니다.

ocx status
ocx status --json

축약 예시 형태는 다음과 같습니다.

{
  "schemaVersion": 1,
  "proxy": {
    "running": false,
    "pid": null,
    "health": {
      "ok": false,
      "url": "http://127.0.0.1:10100/healthz",
      "message": "unreachable"
    }
  },
  "dashboard": {
    "url": "http://localhost:10100/"
  },
  "paths": {
    "config": "/Users/example/.opencodex/config.json",
    "pid": "/Users/example/.opencodex/ocx.pid",
    "runtime": "/path/to/bun"
  },
  "runtime": {
    "source": "bundled"
  },
  "codexHome": {
    "effectiveCodexHome": "C:\\Users\\[USER]\\.codex",
    "appCodexHome": "C:\\Users\\[USER]\\.codex",
    "mismatch": false,
    "warning": null,
    "action": null
  },
  "codexAutostart": true,
  "defaultProvider": "openai",
  "service": {
    "summary": "not installed (logs: /Users/example/.opencodex/service.log)"
  },
  "codexShim": {
    "summary": "Codex autostart shim: not installed"
  }
}

실제 객체에는 listen(포트, 호스트명, 런타임/설정 소스), 설정 로드 진단, 번들 Codex 플러그인 진단도 포함됩니다. JSON 스키마는 추가만 허용합니다. 앞으로 버전에서 필드가 추가될 수는 있지만, 기존 필드는 안정적으로 유지되어야 합니다. 이 스키마는 API 키, OAuth 토큰, Authorization 헤더, 요청 내용, 이메일, 계정 식별자를 의도적으로 제외합니다.

`ocx health [--json]`

실행 중인 프록시의 신원 확인을 수행합니다. 일반 출력은 PID/포트를 보고하고, --json은 {ok, pid, port}를 내보냅니다. 이 명령은 정상일 때만 종료 코드 0을, 그렇지 않으면 1을 반환하므로 서비스 프로브에 적합합니다.

`ocx ready [--json] [--wait [--timeout <seconds>]]`

인증이 필요 없는 GET /readyz 엔드포인트로 동기화 후 준비 상태를 확인합니다. 준비되면 200, pending 또는 종단 상태인 failed이면 Retry-After: 1과 함께 503을 반환합니다. HTTP의 정제된 식별 필드는 {service, version, uptime, pid, port, status, protocol, minimumClientProtocol, managementUrl}입니다. protocol은 허브의 현재 원격 프로토콜, minimumClientProtocol은 호환되는 최소 클라이언트 프로토콜, managementUrl은 브라우저에서 보이는 표준 관리 origin입니다. /readyz가 없는 이전 프록시는 unreachable로 fail-closed하며, /healthz는 준비 상태가 아닌 별도의 liveness 확인입니다. 기본값은 한 번의 probe이며, --wait는 준비 또는 timeout까지 polling하지만 종단 failed를 확인하면 즉시 종료합니다. 기본 timeout은 45초이며, --timeout <seconds>는 --wait와 함께 써야 하고 양의 정수인 1~300초 범위를 받습니다. CLI JSON은 {ready, status, pid, port}를 출력하며 status는 ready, pending, failed, unreachable 중 하나입니다. 종료 코드는 ready가 0, not-ready/pending/failed/timeout/unreachable이 1, 잘못된 인수가 64입니다.

`ocx doctor`

읽기 전용 환경 및 연결 진단을 실행합니다. 상태 경로와 파일시스템 유형, WSL 이중 설치, 프록시 환경/설정, ChatGPT 도달 가능성, Codex 플러그인 및 프로젝트 설정 경고, 보류 중인 기록 마이그레이션이 포함됩니다. Codex 앱 홈 대상 지정 섹션은 좁은 범위의 Windows Orca 런타임 홈 불일치도 감지하고, 해당할 때 서비스 마이그레이션을 설명합니다. 이 진단에 표시되는 경로는 OS 사용자 이름을 마스킹합니다. doctor는 복구 힌트를 보여 주지만 직접 적용하지는 않습니다.

프로젝트 설정 진단은 developer_instructions 같은 TOML 여러 줄 문자열 안의 공급자 예시를 무시합니다. 종료 구분자 바로 앞에 이스케이프된 따옴표가 있어도, 문자열이 끝난 뒤의 실제 공급자 및 프로필 설정은 계속 검사합니다.

OAuth 안정성 섹션은 자격 증명 저장소에 쓰기 가능한지, OPENCODEX_HOME 아래에 refresh single-flight/lock 파일을 만들 수 있는지, 건강하지 않은 OAuth 또는 Codex pool 계정(마스킹된 ID)과 복구용 Action:, 그리고 Codex 전달 경로가 공식 클라이언트 메타데이터를 꾸며 내지 않는다는 정적 OK를 보고합니다. doctor는 자격 증명을 변경하거나 복구를 적용하지 않습니다.

카탈로그 동기화

`ocx sync [--restart-codex] [--restart-app-server-only]`

설정된 모든 공급자에서 라이브 모델 목록을 가져와 병합된 카탈로그를 Codex에 다시 주입합니다. 공급자를 추가한 뒤나 사용 가능한 모델을 새로 고칠 때 실행합니다.

오래 실행 중인 Codex app-server 프로세스가 아직 살아 있으면, opencodex-catalog.json / models_cache.json가 업데이트되었더라도 이전 인메모리 모델 목록을 계속 서비스할 수 있다고 경고합니다. --restart-codex를 붙이면 일치하는 codex … app-server와 codex-code-mode-host 프로세스를 재시작하는 데 더해, macOS·Linux·Windows에서 Codex 데스크톱 앱을 완전히 종료했다가 다시 띄웁니다. 모델 선택기가 카탈로그를 다시 읽도록 하기 위해서이며, 진행 중인 대화는 끝납니다. 광범위한 pkill -f codex 매칭은 의도적으로 피합니다.

--restart-desktop-app은 --restart-codex의 폐기 예정 별칭입니다. 여전히 동작하고 폐기 안내를 출력하며, Windows 전용이 아닙니다.

--restart-app-server-only는 예전처럼 좁은 범위만 수행합니다. 현재 사용자가 소유한 일치 app-server / code-mode-host 프로세스에만 SIGTERM을 보내고 데스크톱 앱은 그대로 둡니다(활성 작업이 중단될 수 있습니다). --restart-codex나 --restart-desktop-app과 함께 쓰면 좁은 범위가 이깁니다. 진행 중인 대화를 잃는 것은 되돌릴 수 없고, 오래된 선택기는 그렇지 않기 때문입니다.

명령을 Codex 앱 안에서 실행하면 재시작은 분리된 helper에 넘기고, 이 세션은 앱과 함께 종료됩니다.

`ocx sync-cache [--restart-codex] [--restart-app-server-only]`

Codex의 로컬 모델 선택기 캐시를 무효화하여, 활성 opencodex 카탈로그에서 다시 빌드되게 합니다. ocx sync와 같은 오래된 app-server 경고와 선택적 재시작 플래그가 적용됩니다.

`ocx catalog pull <https-url> [--auth-env <NAME>] [--json] [--restart-codex] [--restart-app-server-only]`

다른 OpenCodex 인스턴스의 /v1/catalog 엔드포인트가 제공하는 완성된 카탈로그를 설치한 뒤 models_cache.json을 맞춥니다. URL은 HTTPS여야 하고 HTTP는 루프백만 허용합니다. URL에 박힌 자격증명, 쿼리, 프래그먼트, 리다이렉트, 크기를 넘는 응답, 잘못된 카탈로그는 로컬에 쓰기 전에 거절합니다. 인증은 선택이며 환경변수 이름(--auth-env)으로만 읽고 argv로는 받지 않습니다.

HTTP_PROXY 또는 http_proxy가 적용되고 NO_PROXY 또는 no_proxy에 일치하는 우회 항목이 없으면 루프백 HTTP 요청은 인증 헤더를 붙이거나 요청을 보내기 전에 거부됩니다. ALL_PROXY/all_proxy 또는 HTTPS_PROXY/https_proxy만 설정한 경우에는 이 HTTP 제한에 해당하지 않으며, HTTPS 카탈로그 취득은 계속 허용됩니다. 거부 메시지에는 프록시 주소나 인증 토큰이 포함되지 않습니다. 값이 비어 있지 않은 http_proxy와 no_proxy는 각각 HTTP_PROXY와 NO_PROXY보다 우선합니다. Bun과 호환되는 우회 규칙에는 호스트 이름, 일치하는 host:port, [::1]처럼 대괄호로 감싼 IPv6 주소 또는 *를 사용하고, URL·경로·*. 접두사는 사용하지 마세요.

카탈로그와 캐시는 공유 Codex 카탈로그 잠금 아래에서 쓰고, 실패하면 직전까지 정상이던 파일을 그대로 둡니다. 바이트가 같으면 mtime까지 건드리지 않는 no-op입니다. --restart-codex, --restart-app-server-only, 폐기 예정 별칭 --restart-desktop-app은 실제로 쓴 뒤에만 적용되며, ocx sync / ocx sync-cache와 같은 뜻입니다. ETag 조건부 요청은 이 명령에 없습니다. --json envelope 필드와 종료 코드는 영문 레퍼런스를 보세요.

백그라운드 서비스

`ocx service [install|repair|restart|start|stop|status|uninstall|remove]`

로그인 관리형 백그라운드 서비스로 opencodex를 실행합니다(macOS launchd, Linux systemd 사용자 유닛, Windows Task Scheduler). 로그인 시 자동 시작하고 충돌 시 자동 재시작합니다. 서비스 실행은 OCX_SERVICE=1을 설정하므로 재시작해도 Codex 설정이 흔들리지 않습니다.

Windows 작업 스케줄러로 설치하는 서비스는 보통 프로세스 우선순위(Priority=4)를 사용합니다. 이전의 백그라운드 우선순위(7, 생략 시에도 스케줄러 기본값은 7)에서는 CPU 경합으로 상태 확인 응답이 늦어져 프로세스가 살아 있어도 트레이에 Offline이 표시될 수 있습니다. 업그레이드 후 ocx service repair를 실행하면 등록된 해당 우선순위를 변경하고 서비스를 재시작합니다. 이 과정에서 UAC 승인이 필요할 수 있습니다. 이미 보통 또는 높음 우선순위인 경우 우선순위만을 이유로 다시 등록하지 않습니다.

하위 명령	동작
없음	서비스가 없으면 설치하고 시작하며, 이미 있으면 `repair`를 수행합니다. 정상인 Windows 작업 스케줄러 정의는 재사용하지만, 오래된 정의는 다시 등록되어 관리자 권한 승인이 필요할 수 있습니다.
`install`	서비스를 생성하고 시작합니다.
`repair`	설치된 서비스를 제자리에서 새로 고치고, 바뀐 것이 있을 때만 관리자를 reload합니다. macOS에서 정상이고 변경이 없는 작업은 그대로 실행된 채 남으므로 repair가 장애가 되지 않습니다. 정상인 Windows 작업 스케줄러 정의는 재사용하지만, 오래된 정의는 다시 등록되어 관리자 권한 승인이 필요할 수 있습니다.
`restart`	같은 갱신이지만 항상 재시작합니다. macOS에서 변경이 없고 이미 로드된 작업은 제자리에서 kickstart됩니다. `repair`의 별칭이 아닙니다.
`start`	설치된 서비스를 시작합니다.
`stop`	서비스를 중지하고 기본 Codex를 복원합니다.
`status`	서비스와 프록시 진단, 로그 경로를 보고합니다.
`uninstall`	서비스를 제거하고 기본 Codex를 복원합니다.
`remove`	`uninstall`의 별칭입니다.

ocx service
ocx service install
ocx service repair
ocx service restart
ocx service status
ocx service uninstall

Windows에서는 bare ocx service가 Task Scheduler와 WinSW 양쪽 모두 부재가 입증된 후에만 설치 경로를 실행합니다. 상태 조회 중 하나라도 불확실하면 아무것도 등록하지 않고 ocx service status 실행을 안내합니다. 부재를 확인한 뒤에만 명시적인 ocx service install을 사용하세요.

Windows에서는 ocx service status가 Task Scheduler 등록 상태를 ID가 검증된 OpenCodex 프록시 도달 가능성과 별도로 보고합니다. 로컬라이즈된 schtasks 표는 출력하지 않으므로, 요약은 Windows 코드 페이지에서도 읽기 쉽습니다.

Windows에서 Task Scheduler 항목을 만들려면 권한 상승이 필요합니다. 인식되는 로컬라이즈된 접근 거부 텍스트는 기존 안내 경로를 유지합니다. 그 텍스트를 읽을 수 없으면, 대체 경로는 소유된 명령 형태 /create /tn opencodex-proxy /xml <non-empty-path> /f, 상태 1, 그리고 상승하지 않은 토큰의 확인이 필요합니다. 그러면 대시보드의 Startup Safety 작업이 UAC를 자동으로 요청할 수 있습니다. 그 대체 경로로도 토큰 상태를 판별할 수 없으면 원래 스케줄러 오류를 유지합니다. 외부 작업이나 외부 연산은 자동 권한 상승 표시를 절대 내지 못합니다. 대시보드 UAC 프롬프트를 승인하거나 상승된 PowerShell 창에서 ocx service install을 다시 실행해 주세요.

`ocx codex-shim <install|status|uninstall|remove>`

PATH 위의 스크립트 기반 codex 런처를 가벼운 자동 시작 스크립트로 감쌉니다. 정확한 실행 파일 호출을 깨지 않도록 실제 codex.exe 대상은 손대지 않습니다.

설치나 복구를 확정하기 전에 OpenCodex는 서비스 시작을 우회한 상태에서 저장된 런처를 --version으로 실행합니다. 런처가 codex를 shim으로 다시 해석해 재귀하거나, 0이 아닌 코드로 종료하거나, 5초를 초과하거나, 실행 중인 자식 프로세스를 남기거나, 안전하게 검증·정리할 수 없으면 변경을 거부하고 롤백합니다. 따라서 codex-shim install은 무조건 성공하는 명령이 아닙니다. 거부되면 PATH 항목이 구체적인 실행 파일 또는 런처를 가리키도록 Codex를 다시 설치한 뒤 재시도하세요. 동적 명령 관리자의 런처가 이 검증을 충족할 수 없다면 대신 ocx service install을 사용하세요. 업그레이드할 때 현재 검증 가드가 없는 기존 Unix shim은 다시 생성하고 검증합니다. 저장된 런처가 안전하지 않으면 OpenCodex는 위험한 wrapper를 그대로 두지 않고 구버전 shim을 제거한 뒤 원래 런처를 복원합니다.

완료된 외부 Codex 업데이트가 설치된 shim을 덮어쓰면, 다음 일반 ocx 명령이 안정적인 새 런처를 백업하고 명령을 처리하기 전에 shim을 복원합니다. 부작용 없는 검사 명령 ocx system codex-cli-update check와 예약된 ocx system codex-cli-update namespace의 잘못된 호출은 이 복구를 수행하지 않습니다. 아직 변경 중인 런처는 건드리지 않고 나중에 다시 시도합니다. 복구 실패는 요청한 명령을 실패시키지 않고 경고만 표시합니다. 수동 대체 수단은 ocx codex-shim install 입니다. codexShimAutoRestore를 false로 설정하거나, 프로세스 수준에서 제외하려면 OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0을 설정합니다.

하위 명령	동작
`install`	shim을 설치합니다(오래된 경우 복구도 수행합니다).
`uninstall`	shim을 제거하고 원래 Codex 바이너리를 복원합니다.
`remove`	`uninstall`의 별칭입니다.
`status`	shim 상태(설치됨, 오래됨, 누락)를 보고합니다.

ocx codex-shim install
ocx codex-shim status
ocx codex-shim uninstall

Codex에 토큰 주입

루프백이 아닌 주소에 바인딩하면 주입된 공급자에 env_key = "OPENCODEX_API_AUTH_TOKEN"이 포함됩니다. 이 줄은 Codex가 읽을 변수를 지정할 뿐, 변수를 생성하지는 않습니다. 변수가 없으면 Codex는 요청 시작을 거부하며(Missing environment variable: OPENCODEX_API_AUTH_TOKEN), 요청은 프록시에 도달하지 않습니다. 값은 $OPENCODEX_HOME/service-api-token에 저장되며, 실행을 시작하는 프로세스가 Codex의 환경에 이 값을 제공해야 합니다.

ocx codex-shim install로 설치되는 shim을 사용하세요. 실행 환경에서 이 shim이 선택되면 OpenCodex가 생성한 토큰 파일을 읽고 Codex에 변수를 제공합니다. 데스크톱, cron, 서비스에서 실행할 때는 shim을 선택하는 PATH 또는 실행기 경로를 사용해야 합니다. 설치 과정에서 이러한 환경이 자동으로 구성되지는 않습니다. Codex 자체의 자식 프로세스도 토큰을 상속할 수 있습니다.

이 Bearer 토큰을 셸 시작 파일에서 내보내거나 config.toml에 복사하지 마세요. service-api-token 파일에는 NAME=value 형식의 대입문이 아닌 토큰 원문이 들어 있으므로 systemd의 EnvironmentFile=로 직접 사용할 수 없습니다.

opencodex-proxy.service의 EnvironmentFile= 또는 OCX_API_TOKEN_FILE은 프록시 프로세스만 구성하며, 별도로 실행된 codex exec에 전달되지 않습니다.

실행기를 교체하는 Codex 업그레이드는 shim을 제거합니다. 다음 일반 ocx 명령이 shim을 복원하지만(위 내용 참조), 그보다 먼저 실행되는 codex exec는 실패합니다. ocx doctor는 이 상태(env_key 구성됨, 변수 미설정, shim 누락 또는 비정상, 토큰 파일 존재)를 “Codex env_key launch readiness” 항목에서 복구 명령과 함께 보고하며, 토큰은 출력하지 않습니다. 토큰 파일 읽기는 주입된 env_key의 계약에 포함되지 않습니다. 실행을 시작하는 프로세스가 해당 변수를 제공해야 합니다.

`ocx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]`

Windows 상태 트레이 아이콘을 설치하고 제어합니다. Windows 로그인 시 시작되며, 프록시를 원클릭으로 제어할 수 있습니다. start와 stop은 아이콘만 제어합니다. 프록시 제어는 메뉴를 사용하세요. --no-start는 install에 적용되며, 트레이를 바로 실행하지 않고 설치합니다.

대시보드

`ocx gui`

프록시가 실행 중이 아니면 자동으로 시작하면서 웹 대시보드를 http://localhost:<port>에서 엽니다. 허브에서 관리 리스너를 켜 두면 http://127.0.0.1:<관리 포트>에서 엽니다.

업데이트

ocx update는 OpenCodex 자체를 업데이트하며 Codex CLI를 업데이트하지 않습니다. system 검사 명령의 ocx system codex-cli-update check로 설정된 Codex CLI 후보의 provenance를 제한된 읽기 전용 방식으로 확인할 수 있습니다. 이 명령은 package registry를 조회하거나 업데이트를 설치하지 않습니다.

`ocx update [--tag latest|preview]`

npm에서 opencodex를 자체 업데이트합니다. 안정판 설치는 @latest를 사용하고, 미리보기 설치는 --tag latest|preview를 주지 않으면 @preview를 유지합니다. 소스 체크아웃을 감지하면 대신 git pull && bun install을 실행하라고 안내하고, 해당 태그에서 이미 최신 버전이면 아무 동작도 하지 않습니다. npm 설치에서는 어떤 프로세스도 중지하기 전에 Unix 캐시의 소유권과 접근 가능성을 제한된 범위에서 검사합니다. 중첩 심볼릭 링크는 lstat으로 확인하되 따라가지 않으며, Windows에서는 이 Unix 전용 검사를 명시적으로 건너뜁니다. 검사에 실패하면 트레이와 프록시가 실행 중인 상태에서 업데이트를 중단합니다. 그 다음 실행 중인 프록시가 있으면 파일을 교체하기 전에 중지합니다. 설치된 서비스는 자동으로 다시 빌드해 시작하며, 포그라운드 설치에서는 다음 단계로 ocx start를 출력합니다. 대시보드 업데이트 기록은 저장 전에 프로필/캐시 경로와 UID/GID 값을 가립니다.

ocx update
ocx update --tag preview

새 버전은 Release workflow가 npm에 게시하면 사용할 수 있게 됩니다.

Remote Hub 클라이언트 라이프사이클

ocx connect <url> --pairing-code-stdin, ocx connect status, ocx sync, ocx connect rotate --pairing-code-stdin을 사용합니다. ocx disconnect는 오프라인에서도 로컬 상태를 복원하지만 허브 키는 폐기하지 않습니다. 연결 중에는 ocx connect revoke --admin-token-stdin으로 저장된 apiKeyId를 폐기할 수 있고, 연결을 끊은 뒤에는 허브의 Integrations → API Keys를 사용해야 합니다. 비밀값은 stdin으로만 전달하고 argv에 넣지 마세요.

CLI 수명 주기

설정

ocx init · ocx setup

프록시 수명 주기

ocx start [--port <port>]

ocx stop

ocx restart

ocx ensure

ocx restore [back] · ocx eject [back]

ocx recover-history --legacy-openai --yes

ocx recover-history --ocx-compaction <thread-id> --yes

ocx uninstall · ocx remove