Skip to content

lifecycle.md

Latest commit

 

History

History
212 lines (146 loc) · 16.4 KB

lifecycle.md

File metadata and controls

212 lines (146 loc) · 16.4 KB
Raw
title CLI ライフサイクル
description セットアップ、開始、停止、サービス、診断、同期、および更新コマンド。

これらのコマンドは、ローカル 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

:::tip[サービス vs シム] 常時オンのバックグラウンド プロキシには 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

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