CLI ライフサイクル

これらのコマンドは、ローカル opencodex プロキシとその Codex 統合をインストール、実行、検査、修復、および更新します。

設定

`ocx init`・`ocx setup`

対話型セットアップウィザード (setup は init のエイリアスです)。プロバイダー (プリセットまたはカスタム)、API キー (リテラルまたは ${ENV})、デフォルトのモデル、およびプロキシポートの入力を求めるプロンプトが表示されます。 ~/.opencodex/config.json を保存します。オプションでプロキシを $CODEX_HOME/config.toml (デフォルトは ~/.codex/config.toml) に挿入します。オプションで Codex 自動起動シムをインストールします。

プロキシのライフサイクル

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

プロキシサーバー (優先ポート 10100) を起動します。そのポートが占有されている場合、opencodex は別の使用可能なポートを選択して記録します。 PID/ランタイムポートの状態を書き込み、2 番目のライブインスタンスの起動を拒否します。開始時に、各プロバイダーのモデルを Codex のカタログに同期します。マネージドサービス (OCX_SERVICE=1) として起動されていない限り、シャットダウン時にネイティブ Codex が復元されます。

ocx start
ocx start --port 8080

`ocx stop`

実行中のプロキシを (PID によって) 停止し、PID ファイルを削除して、ネイティブ Codex を復元します。マネージドバックグラウンドサービスがインストールされている場合、ocx stop はそれを最初に停止するため、プロキシを再起動できません。Web ダッシュボードの停止ボタンは同じ処理 (POST /api/stop) を実行しますが、Windows タスクスケジューラだけは例外です。タスク終了後もラッパーがプロキシを再起動しうるため、ダッシュボードは respawnable_service で拒否し、何も変更せずに ocx stop の実行を促します。

`ocx restart`

プロキシが実行中の場合、検証済みの正確な PID とポートに対して in-place 再起動を要求し、通常のドレインを待ってから、同じポートに別のランタイム PID が起動したことを確認します。管理対象ルーティングとサービス監視は維持され、不確実な要求を別の stop/start として再実行しません。実行中のプロキシがない場合に限り、通常の ensure 起動にフォールバックします。

稼働中のリスナーをランタイム PID に結び付けて検証できない場合（更新前のプロキシを含む）、ensure や stop/start へのフォールバックは行わず安全側で失敗します。所有権を確認してから ocx stop、ocx start の順に一度実行してください。

`ocx ensure`

バックグラウンドプロキシが実行されていることを冪等的に確認してから、そのライブモデルカタログを同期します。 codexAutoStart が false の場合、自動起動が無効であることが出力され、何も行われません。

`ocx restore [back]`・`ocx eject [back]`

プロキシを停止せずに**ネイティブ Codex を復元します。挿入された設定行とルーティングされたカタログエントリを削除し、プレーンな codex が再びネイティブに動作するようにします。 eject は restore の別名です。

復元後のカタログでは、gpt-5.3-codex-spark など提供終了したネイティブモデルの bare ID と信頼済みのアカウント修飾エントリを除外します。バックアップの有無にかかわらず適用され、元のバックアップとユーザーが保存した過去のモデル選択設定は保持します。

プロキシのライフサイクルを変更せずに、既に実行されているプロキシでプレーン codex を再指定するには、back をどちらかのスペルに渡します。

ocx restore back
ocx eject back

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

可逆バックアップサポートが存在する前に Codex App 履歴を再マップした古い開発ビルドの明示的なリカバリ。履歴データベースがロックされている場合は、まず Codex を閉じてください。

これは広範囲で破壊的な再ラベル付けです。ユーザーメッセージを持ち、現在 opencodex とタグ付けされているすべてのスレッドを openai に変更し、exec を cli に正規化してイベントマーカーを設定します。正当な専用プロバイダー履歴も対象です。状態をバックアップし、この全範囲を意図する場合にのみ実行してください。

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

ルーティングされたプロバイダーで圧縮されたタスクをネイティブ Codex で再開する前に、その履歴を修復します。このコマンドは UUID で 1 つのタスクだけを選択し、非公開のバイト単位バックアップを保存してから、OpenCodeX 所有の ocx1: 圧縮状態だけをネイティブ Codex が再生できる通常の要約に変換します。ネイティブの暗号化コンテンツと他のタスクは変更しません。実行前に対象タスクを閉じてください。処理中に rollout が変更された場合、ファイルを置き換えずに修復を中止します。

`ocx uninstall`・`ocx remove`

すべての復元手順が成功した場合にのみ、サービスとプロキシを停止し、サービスと Codex シムを削除し、ネイティブ Codex を復元してから、opencodex ローカル設定を削除します。 remove は uninstall の別名です。設定のクリーンアップには、新規インストールによって作成された所有権メタデータが必要です。従来のディレクトリまたは共有ディレクトリはそのまま残ります。

ステータスと健康状態

`ocx status [--json]`

読み取り専用の診断概要を出力します: プロキシ PID、/healthz 到達可能性、ダッシュボード URL、構成パス、デフォルトプロバイダー、Codex 自動起動設定、サービス状態、シム状態、および編集された有効な Codex ホーム。明示的で信頼性の高い Windows Orca ランタイムホーム署名のみが、実用的なアプリとホームの不一致の警告を追加します。 CODEX_HOME が自動的に変更されることはありません。

人間の出力には、OAuth ログイン概要の後の OAuth health ブロックも含まれます。つまり、既知のすべてのアカウントが正常な場合は OAuth health: ok、または正常でないアカウントごとに 1 行が編集された 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 トークン、認証ヘッダー、リクエストコンテンツ、電子メール、アカウント ID は意図的に除外されます。

`ocx health [--json]`

稼働中のプロキシの ID を確認します。ヒューマン出力は 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 は hub の現在の remote protocol、minimumClientProtocol は互換性のある最小 client protocol、managementUrl は browser から見える canonical management origin です。/readyz がない旧プロキシは unreachable として fail-closed し、/healthz は readiness ではなく別の liveness 確認です。デフォルトでは 1 回だけ 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 ユーザー名が編集されます。医師は修復ヒントを出力しますが、適用しません。

OAuth の信頼性 セクションでは、資格情報ストレージが書き込み可能かどうか、リフレッシュシングルフライト/ロックファイルが OPENCODEX_HOME で作成できるかどうか、回復 Action: を持つ正常でない OAuth または Codex プールアカウント (編集された ID)、および Codex 転送パスが公式クライアントメタデータを作成しない静的 OK が報告されます。 Doctor は資格情報を変更したり、修復を適用したりすることはありません。

カタログの同期

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

構成されているすべてのプロバイダーからライブモデルリストを取得し、マージされたカタログを Codex に再挿入します。プロバイダーを追加した後、または利用可能なモデルを更新するために実行します。

存続期間の長い Codex app-server プロセスがまだ実行されている場合、ocx sync は、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 アプリ内から実行すると、再起動は切り離されたヘルパーに引き渡され、このセッションはアプリとともに終了します。

`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 カタログロックの下で書き込まれ、失敗時は last-known-good のファイルが保持されます。バイトが同一の場合は mtime を保持する no-op です。--restart-codex、 --restart-app-server-only、非推奨エイリアス --restart-desktop-app は、実際の書き込みの後にのみ適用され、ocx sync および ocx sync-cache と同じ意味です。ETag 条件付きリクエストはこのコマンドには含まれません。--json エンベロープと終了コードの詳細は英語版リファレンスを参照してください。

バックグラウンドサービス

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

opencodex を、ログイン時に自動起動し、クラッシュ時に自動再起動するログイン管理バックグラウンドサービス (macOS launchd、Linux systemd ユーザーユニット、Windows タスクスケジューラ) として実行します。サービスは OCX_SERVICE=1 を設定して実行されるため、再起動によって Codex 設定が変更されることはありません。

Windows タスクスケジューラでインストールするサービスは、通常のプロセス優先度（Priority=4）を使用します。以前のバックグラウンド優先度（7。省略時もスケジューラの既定値は 7）では、CPU の競合によりヘルスチェックへの応答が遅れ、プロセスが動作中でもトレイに Offline と表示されることがあります。アップグレード後に ocx service repair を実行すると、この登録済み優先度を移行してサービスを再起動します。移行時に UAC の承認が必要になる場合があります。すでに通常または高優先度の場合、優先度だけを理由に再登録しません。

サブコマンド	アクション
なし	未インストールなら作成して開始し、既存なら更新して再起動します。正常な Windows タスクスケジューラ定義は再利用しますが、古い定義は再登録され、昇格が必要になる場合があります。
`install`	サービスを作成して開始します。
`repair`	既存のサービスを更新して再起動します。正常な Windows タスクスケジューラ定義は再利用しますが、古い定義は再登録され、昇格が必要になる場合があります。
`restart`	`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 は、タスクスケジューラと WinSW の両方について不在が確認された後にのみ、インストールパスを実行します。どちらかのステータス照会が不確実な場合、何も登録せず、ocx service status の実行を案内します。不在を確認した後にのみ、明示的な ocx service install を使用してください。

Windows では、ocx service status は、ID 検証済みの OpenCodex プロキシの到達可能性とは別に、タスクスケジューラの登録を報告します。ローカライズされた schtasks テーブルは出力されないため、概要は Windows コードページ間で読み取れるままです。

Windows では、タスクスケジューラエントリを作成するには昇格が必要です。認識されたローカライズされたアクセス拒否テキストは、既存のガイダンスパスを維持します。そのテキストが判読できない場合、フォールバックには、所有されているコマンド形状 /create /tn opencodex-proxy /xml <non-empty-path> /f、ステータス 1、および確認済みの非昇格トークンが必要です。ダッシュボードのスタートアップセーフティアクションは、UAC を自動的に要求できるようになります。そのフォールバックがトークンの状態を判断できない場合、元のスケジューラエラーが保持されます。外部タスクおよび操作は、自動昇格マーカーを発行することはできません。ダッシュボードの UAC プロンプトを承認するか、管理者特権の PowerShell ウィンドウで ocx service install を再実行します。

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

軽量の自動起動スクリプトを使用して、スクリプトベースの codex ランチャーを PATH 上にラップします。実際の 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 名前空間の不正な呼び出しは、この修復を行いません。まだ変更中のランチャーは変更されず、後で再試行されます。修復の失敗は、要求されたコマンドを失敗させることなく警告します。手動フォールバック: ocx codex-shim install。 codexShimAutoRestore を false に設定するか、プロセスレベルのオプトアウトの場合は OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0 を設定します。

サブコマンド	アクション
`install`	シムを取り付けます（または古い場合は修理します）。
`uninstall`	シムを削除し、元の Codex バイナリを復元します。
`remove`	`uninstall`の別名。
`status`	シムの状態 (インストール済み、古い、または欠落) を報告します。

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 でインストールされる、保守対象のシムを使用してください。起動コンテキストでこのシムが選択されると、シムは OpenCodex が作成したトークンファイルを読み取り、変数を Codex に渡します。デスクトップ、cron、サービスから起動する場合は、このシムが選択される PATH またはランチャーパスを使用する必要があります。インストールによって、それらの環境が自動的に設定されるわけではありません。Codex 自身の子プロセスにも、トークンが継承される可能性があります。

この Bearer トークンをシェルの起動ファイルからエクスポートしたり、config.toml にコピーしたりしないでください。service-api-token ファイルに含まれるのは NAME=value 形式の代入ではなくトークンそのものなので、systemd の EnvironmentFile= として直接使用することはできません。

opencodex-proxy.service の EnvironmentFile= または OCX_API_TOKEN_FILE は、プロキシプロセスだけを設定するものであり、独立して起動された codex exec に渡されることはありません。

ランチャーを置き換える Codex のアップグレードによって、シムは削除されます。次に通常の ocx コマンドを実行すると復元されますが（上記参照）、その前に実行された codex exec は失敗します。ocx doctor は、この状態（env_key が設定済み、変数が未設定、シムが存在しないか正常でない、トークンファイルは存在する）を修復コマンドとともに “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

新しいバージョンは、リリースワークフローが npm に公開すると利用可能になります。

Remote Hub クライアントのライフサイクル

ocx connect <url> --pairing-code-stdin、ocx connect status、ocx sync、ocx connect rotate --pairing-code-stdin を使います。ocx disconnect はオフラインでローカル状態を復元しますが hub のキーは失効させません。接続中は ocx connect revoke --admin-token-stdin が保存済み apiKeyId を失効させ、切断後は hub の 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

ステータスと健康状態

ocx status [--json]

ocx health [--json]

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

ocx doctor