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) から実行できます。

`ocx restart`

stop に続いて ensure を実行します。プロキシ/サービスを停止し、ネイティブ Codex を復元し、バックグラウンドでプロキシを起動し、ライブポートを Codex に同期します。

`ocx ensure`

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

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

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

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

ocx restore back
ocx eject back

`ocx recover-history --legacy-openai`

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

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

読み取り専用環境と接続の診断を実行します: 状態パスとファイルシステムタイプ、WSL デュアルインストール、プロキシ環境/構成、ChatGPT の到達可能性、Codex プラグインとプロジェクト設定の警告、保留中の履歴の移行。 Codex のアプリとホームのターゲット設定セクションでは、Windows Orca ランタイムとホームの狭い不一致も検出し、該当する場合はサービスの移行について説明します。この診断によって表示されるパスでは、OS ユーザー名が編集されます。医師は修復ヒントを出力しますが、適用しません。

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

カタログの同期

`ocx sync [--restart-codex]`

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

存続期間の長い Codex app-server プロセスがまだ実行されている場合、ocx sync は、opencodex-catalog.json / models_cache.json が更新されても、以前のメモリ内モデルリストを提供し続ける可能性があることを警告します。現在のユーザーが所有する一致する codex … app-server および codex-code-mode-host プロセスにのみ SIGTERM を送信するには、--restart-codex を渡します (アクティブなターンが中断される可能性があります)。広範な 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 タスクスケジューラ) として実行します。サービスは 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 は、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 ターゲットは、正確な実行可能呼び出しの破損を避けるため、変更されないまま残されます。

完了した外部 Codex アップデートがインストールされている shim を上書きした場合、次の通常の ocx コマンドは安定した新しいランチャーをバックアップし、ディスパッチ前に shim を復元します。まだ変更中のランチャーは変更されず、後で再試行されます。修復の失敗は、要求されたコマンドを失敗させることなく警告します。手動フォールバック: 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

`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 が出力されます。

ocx update
ocx update --tag preview

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

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

ocx uninstall・ocx remove

ステータスと健康状態

ocx status [--json]

ocx health [--json]

ocx doctor