デスクトップアプリ

OpenCodex デスクトップアプリはネイティブのトレイとウェブダッシュボードを統合します。同梱 CLI が既存のローカルプロキシを特定し、存在しないと確認できた場合にだけアプリが同梱ランタイムを起動します。

ダッシュボードは特定されたローカルプロキシのエンドポイントから提供されます（既定のポートは 10100）。デスクトップアプリは、そのダッシュボードと同梱ランタイムを包むローカルアプリです。

インストール

macOS

最新リリースから OpenCodex-<version>-macos.dmg をダウンロードします。DMG を開き、OpenCodex.app を Applications にドラッグします。macOS 13 以降が必要です。

リリース版の OpenCodex.app は Developer ID で署名され、Apple による公証を受けています。そのため初回起動時、通常はダウンロードしたアプリの標準的な確認だけが表示されます。それでも macOS がブロックする場合は System Settings → Privacy & Security → Open Anyway を使ってください。

Windows

OpenCodex-<version>-windows-x64.msi をダウンロードしてインストーラーを実行します。まだコード署名されていないため、Windows SmartScreen が警告することがあります。リリースページからダウンロードしたことを確認してから More info → Run anyway を選んでください。

Linux

リリースページから OpenCodex-<version>-linux-x86_64.AppImage または OpenCodex-<version>-linux-amd64.deb をダウンロードします。

AppImage の場合:

chmod +x OpenCodex-<version>-linux-x86_64.AppImage
./OpenCodex-<version>-linux-x86_64.AppImage

Debian 系ディストリビューションの場合:

sudo apt install ./OpenCodex-<version>-linux-amd64.deb

トレイアイコンには AppIndicator に対応したデスクトップ環境が必要です。

初回起動

アプリは同梱 CLI に ocx resolve --json を実行させ、到達可能なローカルプロキシが既に動いていれば接続します。CLI が不在を証明した場合にだけ同梱ランタイムを起動します。結果が不確かな場合は起動エラーとして表示します。その後、特定されたループバックエンドポイントのダッシュボードがアプリ内の WebView で開きます。ログイン時にトレイへ隠れて起動した場合は軽量な起動画面のままにし、トレイから初めて開いたときかアプリを再度起動したときにダッシュボードを読み込みます。

トレイの Open dashboard または Open in browser で、埋め込みダッシュボードと通常のブラウザを切り替えられます。トレイから更新の確認もできます。

macOS では、ダッシュボードを閉じてもアプリはメニューバーで動作し続けます。Dock または Finder から OpenCodex を再度開くと、プロキシを再起動せずにダッシュボードが再表示されます。

Codex の起動でプロキシが見つからない場合、同梱 CLI は独立して検証された Desktop の復旧を待ちます。Desktop に記録された所有権クレームがない場合も同様です。一致する Desktop がプロキシを停止済みか復旧を検証できないときはエラーになりますが、実行イメージ検証のないプラットフォームでは、記録された所有権クレームがありアプリが実行中なら既存の制限付き待機を維持します。プロセス名や検出ファイルだけでは通常の CLI 起動を妨げません。shim は macOS でアプリが終了しており、記録された所有権が有効な Start at Login 登録と一致すれば OpenCodex を開きます。自動で開き直すときはその登録の app バンドルパスを選択し、宣言されたメイン実行ファイルが登録済み Desktop の実行ファイルと一致するか確認します。登録がない・古い・不整合の場合は OpenCodex を手動で開いてください。同じバンドル識別子を持つ別コピーは代替として選択されません。shim が “activation not confirmed” と表示する場合は、シェル起動ファイルの他の PATH 設定の後に . ~/.opencodex/codex-shell-env.sh を追加してください。

復旧検証の対象は、macOS/Linux の一致する同梱 CLI と保護されたシステム Debian インストールです。古い npm 製の shim は別の Bun/CLI インストールを固定し、Desktop のターミナルコマンド受け渡しを迂回する場合があります。そのエントリポイントでは、公式署名コピーを含む macOS/Windows の Desktop や任意のユーザー単位 Linux コピーを検証できません。Desktop の Startup ページで shim を作り直すか、同梱 CLI を実行してください。Windows はこの復旧証明に必要な実行イメージの同一性をまだ確立できません。識別された実行中の兄弟プロセスは復旧クレジットを得られず、記録された Desktop クレームがなければ CLI プロキシを起動する代わりにエラーを報告します（ディスク上の署名が有効でも同様です）。記録されたクレームがありアプリが実行中なら、CLI は Desktop のプロキシへの既存の制限付き待機を維持します。

トレイでの使用量表示

macOS と Windows ではトレイアイコンをクリックするとコンパクトな使用量ウィンドウが開きます。トレイの Show usage 操作でも開けます。これはトレイのクリックイベントを転送しない Linux デスクトップでも使えます。Linux では、デスクトップ環境にトレイアイコンが表示されなくても起動時にダッシュボードが開きます。

使用量ウィンドウには Today と過去 30 日間の合計、設定された使用量チャート、コンパクトなモデル一覧、プロバイダーとアカウントの制限が表示されます。クォータのリセットまでの時間はバーの横に表示され、ホバーすると正確なリセット時刻を確認できます。表示するセクションとチャートは既存の Menu bar & widget 設定で制御します。非表示のプロバイダーはタイトル、合計、クォータ、チャートから除外されます。チャートは現在の時間区間の活動も含みます。部分データの表示は、チャートの一部を確実に帰属できないことを意味します。測定値の欠落は使用量ゼロとして表示しません。Windows と Linux では、アカウント一覧が長い場合、ウィンドウ内をスクロールすると末尾の Refresh と Dashboard に進めます。

macOS ではこのウィンドウにネイティブの SwiftUI コントロールとスクロール可能な AppKit パネルを使用します。macOS 26 以降では Apple Liquid Glass、それ以前ではネイティブのポップオーバー素材を使います。長いアカウント一覧をスクロールしても、ヘッダーと Refresh、Dashboard のボタンは表示されたままです。View → Show Usage (Command-Shift-U) からも開けます。Escape を押すかパネル外をクリックすると閉じます。

トレイメニューには今日のリクエスト数とトークン数が表示され、有効なら推定コストも表示されます。ウィジェットと同じローカル日付の使用量を使います。Refresh now を選ぶとすぐに更新され、アプリも 60 秒ごとに更新します。表示設定はダッシュボードの Menu bar & widget セクションにあります。Today をオフにすると要約が隠れ、Cost をオフにすると要約からコストが消えます。

利用できない、または明示的に未測定の使用量は、測定されたゼロではなく — と表示されます。アイコンのみの見出しを選ぶと以前のカウンターは消えます。省略表記でも整数のゼロは保たれ、1,000 万トークンは 1M ではなく 10M です。

更新

トレイメニューの Check for Updates… を選ぶとすぐに確認できます。リリース版は起動後と 6 時間ごとにも自動確認します。

Tauri updater が新しいアプリのバージョンを見つけると、macOS のメニューバーアイコン、または tray ホストがある場合の Windows/Linux のトレイアイコンに青い点が表示されます。埋め込みダッシュボードにも同じ更新状態が表示されます。同じプロキシにつながる通常のブラウザにはプロキシパッケージの更新状態が表示されます。シェルからの報告が約3分間止まると、再接続するまで埋め込みバッジは unknown になります。点は更新の有無を示すだけで、インストールには明示的な操作が必要です。

デスクトップアプリでは、ダッシュボードの更新ボタンからアプリ専用の更新ページを開けます。そこで再確認、保留中の署名済み更新のインストール、ダッシュボードへの戻る操作を行えます。同じインストール操作はトレイメニューからも利用できます。インストールに失敗しても更新は再試行できます。トレイアイコンのない Linux デスクトップでもこのページを使えます。通常のブラウザのダッシュボードでは、代わりにそのプロキシのパッケージを更新します。

更新はインストール前にプロジェクトの署名済み更新用公開鍵で検証されます。macOS のアプリ内更新では OpenCodex-<version>-macos.app.tar.gz をダウンロードします。DMG は初回インストール用です。リリースマニフェストは更新用キーのシークレットが設定された場合にのみ生成され、その場合は 4 プラットフォームすべての署名が必要です。

ウィジェット

macOS アプリには OpenCodex WidgetKit 拡張が含まれます。ウィジェットの設定とローカルスナップショットの詳細は、macOS メニューバーアプリのガイドを参照してください。

アンインストール

macOS では Applications から OpenCodex.app をゴミ箱へ移動します。Windows では Installed apps から OpenCodex を削除します。Debian 系 Linux では次を実行します。

sudo apt remove opencodex

AppImage の場合はダウンロードしたファイルを削除します。

保存済みのメニューバー設定を読み取れない場合、ファイル保護のため部分的な編集は拒否されます。再編集するにはファイルを復元するか、コンパニオン設定を明示的にリセットしてください。