opencodex/docs-site/src/content/docs/ko/reference/cli/lifecycle.md at c297dba307506eca9d3ee85750f12570b2e65749 · lidge-jun/opencodex

title	CLI 수명 주기
description	설정, 시작, 중지, 서비스, 진단, 동기화, 업데이트 명령입니다.

이 명령들은 로컬 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)에서도 사용할 수 있습니다.

`ocx restart`

stop 다음에 ensure를 실행합니다. 즉, 프록시/서비스를 중지하고 기본 Codex를 복원한 뒤, 프록시를 백그라운드에서 다시 시작하고 살아 있는 포트를 Codex에 다시 동기화합니다.

`ocx ensure`

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

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

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

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

ocx restore back
ocx eject back

`ocx recover-history --legacy-openai`

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

`ocx uninstall` · `ocx remove`

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

상태 및 헬스

`ocx status [--json]`

읽기 전용 진단 요약을 출력합니다. 프록시 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 doctor`

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

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

카탈로그 동기화

`ocx sync [--restart-codex]`

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

오래 실행 중인 Codex app-server 프로세스가 아직 살아 있으면, opencodex-catalog.json / models_cache.json가 업데이트되었더라도 이전 인메모리 모델 목록을 계속 서비스할 수 있다고 경고합니다. --restart-codex를 붙이면 현재 사용자가 소유한 codex … app-server와 codex-code-mode-host 프로세스 중 일치하는 것에만 SIGTERM을 보냅니다(활성 작업이 중단될 수 있습니다). 광범위한 pkill -f codex 매칭은 의도적으로 피합니다.

`ocx sync-cache [--restart-codex]`

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

백그라운드 서비스

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

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

하위 명령	동작
없음	서비스를 생성/업데이트하고 시작합니다.
`install`	서비스를 생성하고 시작합니다.
`start`	설치된 서비스를 시작합니다.
`stop`	서비스를 중지하고 기본 Codex를 복원합니다.
`status`	서비스와 프록시 진단, 로그 경로를 보고합니다.
`uninstall`	서비스를 제거하고 기본 Codex를 복원합니다.
`remove`	`uninstall`의 별칭입니다.

ocx service
ocx service install
ocx service status
ocx service uninstall

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 대상은 손대지 않습니다.

완료된 외부 Codex 업데이트가 설치된 shim을 덮어쓰면, 다음 일반 ocx 명령이 안정적인 새 런처를 백업하고 명령을 처리하기 전에 shim을 복원합니다. 아직 변경 중인 런처는 건드리지 않고 나중에 다시 시도합니다. 복구 실패는 요청한 명령을 실패시키지 않고 경고만 표시합니다. 수동 대체 수단은 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

:::tip[서비스와 shim] 항상 켜져 있는 백그라운드 프록시에는 ocx service를 사용합니다(권장). 데몬 없이 가볍게 필요할 때만 시작하려면 ocx codex-shim을 사용합니다. 이 경우 프록시는 codex를 실행할 때만 시작됩니다. :::

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

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

대시보드

`ocx gui`

프록시가 실행 중이 아니면 자동으로 시작하면서 웹 대시보드를 http://localhost:<port>에서 엽니다.

업데이트

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

npm에서 opencodex를 자체 업데이트합니다. 안정판 설치는 @latest를 사용하고, 미리보기 설치는 --tag latest|preview를 주지 않으면 @preview를 유지합니다. 소스 체크아웃을 감지하면 대신 git pull && bun install을 실행하라고 안내하고, 해당 태그에서 이미 최신 버전이면 아무 동작도 하지 않습니다. 실행 중인 프록시가 있으면 파일을 교체하기 전에 중지합니다. 설치된 서비스는 자동으로 다시 빌드해 시작하며, 포그라운드 설치에서는 다음 단계로 ocx start를 출력합니다.

Unix에서는 업데이트 전에 설정된 npm 캐시가 현재 사용자 소유인지 확인합니다. 다른 소유자의 항목이 있거나 캐시를 검사할 수 없으면 실행 중인 프록시를 중지하기 전에 업데이트를 중단합니다.

프록시가 중지된 뒤 업데이트 명령 자체가 실패하면 자동 복구를 시도하지 않습니다. 실패한 설치 프로그램이 전역 패키지 트리를 아직 바꾸는 중일 수 있기 때문입니다. 업데이트 작업은 실패로 남고, 로그에 수동 복구 경로(패키지를 복원한 뒤 ocx service install 또는 ocx start --port <port>)가 안납니다.

ocx update
ocx update --tag preview

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

설정

`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`

`ocx uninstall` · `ocx remove`

상태 및 헬스

`ocx status [--json]`

`ocx health [--json]`

`ocx doctor`

카탈로그 동기화

`ocx sync [--restart-codex]`

`ocx sync-cache [--restart-codex]`

백그라운드 서비스

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

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

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

대시보드

`ocx gui`

업데이트

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

FilesExpand file tree

lifecycle.md

Latest commit

History

lifecycle.md

File metadata and controls

설정

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

ocx uninstall · ocx remove

상태 및 헬스

ocx status [--json]

ocx health [--json]

ocx doctor

카탈로그 동기화

ocx sync [--restart-codex]

ocx sync-cache [--restart-codex]

백그라운드 서비스

ocx service [install|start|stop|status|uninstall|remove]

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

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

대시보드

ocx gui

업데이트

ocx update [--tag latest|preview]

`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`

`ocx uninstall` · `ocx remove`

`ocx status [--json]`

`ocx health [--json]`

`ocx doctor`

`ocx sync [--restart-codex]`

`ocx sync-cache [--restart-codex]`

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

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

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

`ocx gui`

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