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>] [--socks5 [host:port] | --socks5-off]`

프록시 서버를 시작합니다(권장 포트는 10100). PID와 런타임 포트 상태를 기록하고, 두 번째 활성 인스턴스는 시작하지 않습니다. 권장 포트가 이미 사용 중이면 start가 점유자를 확인한 뒤 어느 경우든 실행을 멈춥니다. opencodex가 응답하면 시작을 거부하고, 그렇지 않으면 점유자를 식별할 수 없다고 알립니다. 첫 번째 프록시를 실행한 채 Codex가 두 번째 프록시를 가리키게 되므로, 리스너를 다른 포트로 자동 이동하지 않습니다. 활성 프록시와 같은 OPENCODEX_HOME을 사용하면 다른 --port를 명시해도 시작을 거부합니다. 관찰 전용과 제한 적용 모드 모두 같은 지출 저널에 기록하기 때문입니다. 독립된 형제 인스턴스에는 별도의 OPENCODEX_HOME을 사용하세요. port: 0은 포트만 OS에 맡기며 상태를 분리하지 않습니다. 시작할 때는 각 공급자의 모델을 Codex 카탈로그로 동기화합니다. 종료할 때는 기본 Codex를 복원합니다. 단, 관리형 서비스로 실행한 경우(OCX_SERVICE=1)는 예외입니다. 이미 실행 중인 프록시 옆에서 시작한 형제 인스턴스는 ocx stop이나 시그널로 멈출 때도 동기화와 복원을 하지 않고 자신의 포트에서 직접 요청만 처리하며, Codex, Grok, Claude는 원래 실행 중이던 프록시를 계속 가리킵니다. 별도의 OPENCODEX_HOME에서 시작할 때는 기본 홈의 런타임 기록과 OpenCodex가 관리하는 Grok·Codex 루프백 주소로 활성 프록시를 확인합니다. 활성 소유자가 없는 단독 사용자 지정 홈은 평소대로 동기화하며, 명시적인 ocx sync와 ocx grok apply도 계속 사용할 수 있습니다.

--socks5(기본값 127.0.0.1:10808)는 SOCKS5 URL을 config.proxy에 저장하고 실제 SOCKS5 터널을 통해 송신 HTTP(S) 요청을 전달합니다. --socks5-off는 저장된 SOCKS5 프록시만 지우며 HTTP 프록시는 삭제하지 않습니다. 값은 구성에 저장되므로 ocx update 후에도 유지됩니다. URL에 사용자 이름과 비밀번호를 포함할 수 있지만 시작 로그에서는 숨겨집니다.

ocx start
ocx start --port 8080
ocx start --port 10100 --socks5
ocx start --socks5-off

`ocx stop`

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

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

연결된 hub 클라이언트에서는 성공한 API 종료를 포함해 ocx stop이 연결 소유의 Codex 라우팅, 모델 카탈로그와 Grok 설정을 보존합니다. ocx start는 라우팅을 다시 주입하지 않고 보존한 설정으로 서비스를 재개합니다. Codex를 자체 계정으로 돌리려면 ocx disconnect를, 이미 기본 라우팅으로 복원했다면 다시 연결하려고 ocx sync --restart-codex를 실행하세요.

Remote Link Child를 명시적으로 중지하면 공유 설정 복원에 성공한 경우 기본 Codex 라우팅, 카탈로그와 백업된 재개 이력 메타데이터를 복원하고 관리형 Grok 설정을 제거합니다. 저장된 Home 연결은 유지하며 ocx disconnect로 제거할 수 있습니다. Codex에서 Home을 다시 쓰려면 ocx start(서비스가 설치되어 있으면 ocx service start) 후 ocx sync --restart-codex를 실행하세요. 시작만으로 라우팅을 다시 적용하지 않으며, sync는 Grok 블록을 다시 만들지 않습니다.

서비스 중지 전에 연결 소유권을 확인할 수 없으면 종료 API는 HTTP 409와 sharedTeardown: "refused"를 반환하고 프록시와 서비스 관리자를 실행 상태로 둡니다. 진행 중인 연결 또는 연결 해제가 끝난 뒤 다시 시도하세요.

연결된 클라이언트를 중지할 때는 보호된 로컬 런타임 기록과 리스너의 신원 증명을 대조합니다. 클라이언트 리스너와 일반 프록시 모두 이 검증이 필요하며, 일반 프록시는 인증된 조회로 설정 보존 기능도 확인합니다. 오래되었거나 검증할 수 없는 런타임은 서비스나 프로세스를 중지하기 전에 거절합니다. 런타임을 관리하는 앱이나 서비스에서 업데이트·재시작한 뒤 다시 시도하세요.

이미 중지된 클라이언트는 서비스 관리자가 비활성이고 알려진 로컬 주소에 런타임이 없음을 확인한 뒤 정상적인 미실행 결과를 반환합니다.

`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:/ocx2: 압축 상태만 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를 실행합니다. macOS에서는 버전 불일치가 서비스 정의를 바이트 단위로 그대로 두기 때문에 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 헤더, 요청 내용, 이메일, 계정 식별자를 의도적으로 제외합니다.

실시간 읽기는 제한된 서비스 진단이 끝날 때까지 기다립니다. 진단 캐시가 비어 있거나 만료되면 macOS/Linux에서는 최대 6.5초, Windows에서는 최대 16.5초입니다. 캐시된 결과는 신속하게 반환됩니다. 시간 초과 시에는 기존대로 로컬 진단으로 전환합니다. /healthz가 정상이라는 사실만으로 재시작 보호가 유효함을 확인할 수는 없습니다.

`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, features}입니다. 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]`

Remote Link Child: ocx sync는 Home의 Codex 설정도 적용하며, 클라이언트 런타임이 그 적용보다 먼저 시작되었으면 재시작 플래그 없이도 런타임을 재시작합니다. 재시작이 실패하면 이전 런타임이 계속 서비스하고 명령은 0이 아닌 코드로 끝납니다. ocx status --json과 ocx link status --json의 관련 필드는 Remote Link apply parity(영문)를 참고하세요.

재시작 플래그를 명시하면 카탈로그와 캐시 바이트가 같아도 config.toml 변경이 성공적으로 커밋된 뒤 재시작합니다. 설정만 다루는 작업이 변경 없음, 거부, 사전 검증 또는 롤백으로 끝나면 재시작하지 않습니다. 재시작 플래그가 없으면 sync는 Codex를 자동으로 재시작하지 않습니다.

설정된 모든 공급자에서 라이브 모델 목록을 가져와 병합된 카탈로그를 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 --expect-link <linkId>(Remote Link Child)와 ocx sync --expect-hub-key <apiKeyId>(hub 클라이언트)는 이 머신이 여전히 그 링크나 그 키로 연결되어 있을 때만 동기화합니다. 그렇지 않으면 아무것도 바꾸지 않고 로컬 공급자도 동기화하지 않으며, 종료 코드 5로 끝나고 stderr 마지막 줄에 {"phase":"child_link_mismatch"|"hub_client_mismatch","reason":...}를 출력합니다. 형식이 잘못되었거나 반복된 플래그는 종료 코드 2로 끝납니다. 자세한 내용은 영어 레퍼런스를 참고하세요.

`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 승인이 필요할 수 있습니다. 이미 보통 또는 높음 우선순위인 경우 우선순위만을 이유로 다시 등록하지 않습니다.

Linux에서 systemd 유닛은 설치 시 PATH에서 찾은 첫 번째 일반 실행 가능 ocx 파일을 호출하며, 설치된 패키지 트리 안의 Bun 및 CLI 경로를 사용하지 않습니다. mise, asdf 같은 버전 관리자는 버전이 붙은 디렉터리에 설치하고 업그레이드 시 이전 디렉터리를 삭제하지만, 안정적인 shim이 유닛의 해석을 유지합니다. ocx 런처가 없는 소스 체크아웃은 직접 Bun + CLI 형태를 유지합니다. Bun 시작 전에 선택된 신뢰할 수 있는 OPENCODEX_BUN_PATH는 shim을 통해 보존되며, 패키지에 번들된 Bun 경로는 업그레이드 후 다시 검색됩니다.

macOS에서 launchd는 대신 설치 또는 repair 때 선택한 패키지 내부 Bun 및 CLI 경로를 사용합니다. 이는 가변 PATH shim이 이후 재시작에서 서비스 API 토큰과 구성된 프록시 환경을 받지 못하게 합니다. 버전 관리자 설치를 업그레이드한 뒤에는 서비스를 재시작하기 전에 ocx service repair를 실행해 해당 경로를 새로 고치세요.

이 변경 이전에 설치된 정의는 여전히 이전 버전 경로를 지니고 스스로 마이그레이션할 수 없습니다. 이전 실행 파일이 삭제되면 이를 고칠 opencodex 코드가 실행되지 않습니다. 업그레이드 후 ocx service repair를 한 번 실행하세요. 이후 Linux 서비스 시작은 런처를 따르고, macOS repair는 새 패키지 경로를 launchd 정의에 기록합니다. 이미 실행 중인 프록시는 외부 업그레이드로 교체되지 않습니다. 설치된 CLI가 실행 중인 프록시보다 새로우면 새 빌드가 서비스하도록 ocx service restart를 실행하세요. macOS에서는 이 경우 repair로 충분하지 않습니다. 정의가 바뀌지 않았고, 아무것도 바꾸지 않는 repair는 아무것도 reload하지 않습니다. 반대로 프록시가 더 새로우면 ocx status에 설명된 대로 CLI 설치와 PATH를 확인하세요.

하위 명령	동작
없음	서비스가 없으면 설치하고 시작하며, 이미 있으면 `repair`를 수행합니다. 정상인 Windows 작업 스케줄러 정의는 재사용하지만, 오래된 정의는 다시 등록되어 관리자 권한 승인이 필요할 수 있습니다.
`install`	서비스를 생성하고 시작합니다.
`repair`	설치된 서비스를 제자리에서 새로 고칩니다. macOS에서는 바뀐 것이 있을 때만 launchd를 reload하므로, 정상이고 변경이 없는 작업은 그대로 실행된 채 남아 repair가 장애가 되지 않습니다. Linux와 Windows에서는 서비스를 재시작합니다. 정상인 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을 다시 실행해 주세요.

시작할 때 another process owns the runtime mutation lease가 보고되거나 ocx service status에 Runtime mutation lease busy가 표시되면, 프록시가 실행 중이 아니더라도 이 리스가 시작이나 서비스 변경을 막고 있는 것입니다. 메시지에는 잠금 경로, 기록된 PID, 그 PID가 현재 살아 있는지 여부, 확인할 수 있는 경우 실행 파일 이름, 리스 경과 시간이 들어 있습니다. 프로세스의 신원은 검증되지 않습니다. PID가 재사용되었을 수 있으므로, 생존 여부와 실행 파일 이름은 지금 그 PID를 쓰고 있는 프로세스에 대한 정보입니다. 작업이 끝날 때까지 기다린 뒤 다시 시도하세요. 이 PID만 보고 잠금을 삭제하거나 프로세스를 중지하지 마세요. 리스 경과 시간이 30초를 넘고 기록된 PID가 더 이상 살아 있지 않으면 이후의 변경 시도가 오래된 리스를 회수할 수 있습니다. ocx service status는 리스를 확인만 합니다.

Windows에서는 이 공용 Node/Bun 진단 경로가 실행 파일 이름 조회용 프로그램을 실행하지 않습니다. 기록된 PID, 생존 여부, 리스 경과 시간과 복구 안내는 계속 표시됩니다.

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

macOS와 Linux에서 ocx codex-shim install은 확정된 OpenCodex 홈에 전용 wrapper <OPENCODEX_HOME>/bin/codex와 셸에서 읽을 <OPENCODEX_HOME>/codex-shell-env.sh를 설치합니다. 원래 런처는 brew, npm, fnm이 설치한 위치에 그대로 있어 패키지 관리자 업데이트와 버전 롤백 뒤에도 다시 감쌀 필요가 없습니다. Windows는 기존처럼 스크립트 런처를 제자리에서 감싸며 실제 codex.exe는 건드리지 않습니다. Windows에서 codex.exe만 제공된다면 ocx service install을 사용하세요.

brew/fnm 등의 PATH 설정이 끝난 뒤 설치 명령이 출력한 활성화 명령을 실행하세요. 기본 홈에서는 다음과 같습니다.

. "$HOME/.opencodex/codex-shell-env.sh"

사용자 지정 홈에서는 출력된 따옴표 포함 경로를 사용하세요. 여러 번 읽어도 전용 bin의 중복 항목을 제거하고 PATH 맨 앞에 배치합니다. 이후 셸에서도 사용하려면 셸 시작 파일의 PATH 설정 뒤에 이 줄을 직접 추가하세요. OpenCodex는 셸 시작 파일을 수정하지 않으며 설치 명령은 부모 셸의 PATH를 바꿀 수 없습니다. wrapper가 실행 가능하면 현재 셸에서 아직 활성화되지 않아도 설치는 성공합니다. 설치가 거부되거나 wrapper를 실행할 수 없으면 실패 종료 코드를 반환합니다. ocx status, ocx codex-shim status, ocx doctor, ocx connect는 PATH에서 선택되지 않은 wrapper를 not active로 표시하고 활성화 명령을 안내합니다. connect 경고는 종료 상태를 바꾸지 않습니다. 별칭, 함수, 데스크톱과 서비스 실행 환경은 별도 설정이 필요합니다.

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

Unix 자동 복구는 전용 wrapper만 갱신하며 패키지 관리자 런처를 다시 작성하거나 기존 제자리 shim을 이전하지 않습니다. Windows에서는 완료된 외부 업데이트가 shim을 덮어쓰면 다음 일반 ocx 명령이 안정적인 새 런처를 백업하고 shim을 복원합니다. 변경 중인 런처는 건드리지 않고 나중에 재시도합니다. ocx status, ocx doctor, ocx codex-shim status, ocx system codex-cli-update check와 해당 예약 namespace의 잘못된 호출은 shim 자동 복구를 실행하지 않습니다. 복구 실패는 요청한 명령의 종료 상태를 바꾸지 않고 경고만 표시합니다. 수동 복구 명령은 ocx codex-shim install입니다. codexShimAutoRestore를 false로 설정하거나 프로세스별로 OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0을 설정하면 자동 복구를 끕니다.

하위 명령	동작
`install`	shim을 설치합니다(오래된 경우 복구도 수행합니다).
`uninstall`	Unix 전용 파일만 제거하고 원래 Codex는 유지합니다. Windows에서는 원래 런처를 복원합니다.
`remove`	`uninstall`의 별칭입니다.
`status`	shim 상태와 전용 wrapper의 PATH 활성화 여부를 보고합니다.

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

Unix에서 제거한 뒤 셸 시작 파일의 source 줄을 삭제하고 셸을 다시 시작하거나 PATH에서 전용 bin을 제거하세요. 소유한 wrapper, 셸 환경 파일, 상태만 삭제하며 패키지 관리자 런처는 그대로 둡니다. 기존 제자리 Unix shim은 기록된 복원 정보를 이용해 해제합니다.

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에 전달되지 않습니다.

Unix 패키지 관리자 업데이트는 전용 wrapper를 그대로 둡니다. 비활성 상태라면 출력된 활성화 파일을 읽으세요. Windows 또는 기존 제자리 shim에서는 런처를 교체하는 업데이트가 shim을 제거합니다. Windows에서는 다음 일반 ocx 명령이 shim을 복원하지만(위 내용 참조), 그보다 먼저 실행되는 codex exec는 실패합니다. ocx doctor는 이 상태와 비활성 wrapper(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에 적용되며, 트레이를 바로 실행하지 않고 설치합니다. 지원 중단 예정: OpenCodex 데스크톱 앱이 Windows, macOS, Linux에서 트레이를 제공합니다. ocx tray는 데스크톱 앱이 없는 설치를 위해 계속 사용할 수 있습니다. 새 패키지 버전이 확인되면 트레이는 온라인, 경고, 오프라인 아이콘에 파란 점을 표시하고 Update available을 보여 줍니다. 로컬 캐시 배지를 약 1분마다 확인하며, 오래되었거나 사용할 수 없는 결과가 되면 점을 제거합니다. 이 메뉴 항목은 대시보드를 열고 그곳에서 패키지 업데이트를 시작할 수 있게 합니다. 자동으로 설치하지는 않습니다.

대시보드

`ocx gui`

프록시가 실행 중이 아니면 자동으로 시작하면서 웹 대시보드를 http://127.0.0.1:<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]`

OpenCodex가 mise를 통해 설치된 경우 이 명령은 프록시를 중지하거나 패키지 파일을 변경하기 전에 실패하며 검증된 로컬 mise 별칭을 사용한 mise upgrade <tool>을 표시합니다. 업데이트 확인은 계속 사용할 수 있고 외부 관리 설치로 보고합니다. mise 소유권 메타데이터를 읽을 수 없거나 일관되지 않아도 도구 이름을 추측하지 않고 변경을 거부하며, --tag preview는 mise에 구성된 선택을 변경하지 않습니다.

Linux에서 기록된 런처가 mise 패키지 런처(mise shim이 아닌 <tool>/latest/node_modules/.bin/ocx)인 백그라운드 서비스는 mise upgrade를 스스로 따라갑니다. 새 버전이 안정된 뒤 약 10초 안에 진행 중인 요청을 드레인하고 새 버전으로 재시작하며, 실행 중이던 버전을 mise가 나중에 정리해도 같은 방식으로 복구합니다. macOS, mise shim으로 설치한 서비스, 포그라운드 프록시는 업그레이드 후 직접 재시작하세요(macOS에서는 먼저 ocx service repair).

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를 폐기할 수 있고, 연결을 끊은 뒤에는 허브의 연결 → API 키를 사용해야 합니다. 비밀값은 stdin으로만 전달하고 argv에 넣지 마세요.

Setup port validation

ocx init의 포트는 1–65535 범위의 십진 정수입니다. Enter만 누르면 10100을 사용합니다. 0, 10100oops, 1.5 같은 잘못된 값은 임의로 바꾸거나 자르지 않고, 오류를 알린 뒤 포트를 다시 묻습니다.

Linux의 ocx service install은 linger가 이미 켜졌는지 확인하고, 비활성 상태일 때만 활성화 안내를 제공합니다. 확인할 수 없으면 불확실성을 표시합니다. macOS의 유효하고 활성화된 Desktop 로그인 등록은 현재 세션에 로드되지 않아도 다음 로그인용으로 인정합니다. ocx service status와 ocx status가 이를 구분하며, 잘못된 plist·비활성 등록·불명확한 검사 결과는 보호 근거로 사용하지 않습니다.

CLI 수명 주기

설정

ocx init · ocx setup

프록시 수명 주기

ocx start [--port <port>] [--socks5 [host:port] | --socks5-off]

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