macOS メニューバーアプリ

macOS のメニューバー項目は OpenCodex デスクトップアプリの一部です。ローカルプロキシから取得した使用量を表示し、ネイティブの使用量パネルを開きます。同じアプリにはダッシュボードと WidgetKit 拡張も含まれます。他のプラットフォームへのインストール方法はデスクトップアプリのガイドを参照してください。

インストール

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

初回起動

リリース版の OpenCodex.app は Developer ID で署名され、強化ランタイムを使用し、Apple の公証を受けたチケットがアプリに添付されています。初回起動時、通常はインターネットからダウンロードしたアプリの標準的な確認だけが表示されます。それでも macOS がブロックする場合は System Settings → Privacy & Security を開き、OpenCodex の Open Anyway を選んでください。自分でビルドしたアプリはアドホック署名になります。ソースからビルドを参照してください。

アプリを開くと起動の進行状況がウィンドウに表示されます。初回起動時に Start at Login が一度有効になりますが、トレイメニューからオフにできます。その後ログイン項目から起動すると、ウィンドウは隠れた状態で開始し、トレイは利用できます。

メニューバーと使用量パネル

メニューバーの見出しには既定で今日の合計トークン数が表示されます。ダッシュボードの Menu bar & widget 設定では、リクエスト数、トークン数、推定コスト、クォータ、アイコンのみのいずれかを選べます。

トレイメニューの Show Usage でネイティブパネルを開きます。パネルには表示設定に従って、今日と過去 30 日間の合計、使用量チャート、モデル一覧、プロバイダーとアカウントの制限が表示されます。合計にはトークン数とリクエスト数が含まれ、有効なら推定コストも含まれます。クォータ行には期間、割合、リセット時刻が表示されます。測定値がない場合は — と表示され、部分的な使用量は不完全と示されます。

パネルには Refresh、Dashboard、Settings があります。Dashboard はデスクトップウィンドウの使用量画面を開き、Settings はそこでコンパニオン設定を開きます。トレイメニューには Open Dashboard、Open in Browser、Start at Login、Stop proxy、Check for Updates…、更新がある場合の Install update、Quit もあります。Stop proxy は常に表示されますが、アプリ自身がプロキシを起動した場合にのみ有効です。別に起動したプロキシは動作を続けます。トレイが利用できる場合、ウィンドウを閉じるか Command-Q を押すとアプリは隠れます。終了にはトレイの Quit を使ってください。

トレイの見出しは 60 秒ごとに更新されます。ネイティブパネルを開いている間もデータは 60 秒ごとに更新され、Refresh で直ちに更新できます。

ウィジェット

macOS 14 以降では、OpenCodex.app を一度開いた後、デスクトップの空白部分を Control キーを押しながらクリックして Edit Widgets を選び、OpenCodex を検索して希望するサイズを追加します。サイズによって、プロキシの状態、今日のトークン数とリクエスト数、推定コスト、クォータ、使用量チャートの組み合わせが異なります。拡張はデスクトップアプリが書き込むローカルスナップショットを読み取ります。このスナップショットに含まれるのは表示用データで、API キーや生のアカウントデータではありません。プロキシへの接続中、アプリは 60 秒間隔のトレイ更新の 5 回ごと、約 5 分ごとにウィジェットのスナップショットを更新します。WidgetKit も 5 分後に新しいタイムラインを要求します。

プロキシへの接続

デスクトップアプリは同梱 CLI に ocx resolve --json を実行させます。到達可能な既存のローカルプロキシへ接続するか、CLI が稼働中のランタイムがないと証明した場合にのみ同梱ランタイムを起動します。検出結果が不確かな場合、二つ目のプロキシを起動せず問題を報告します。アプリは特定されたポートへ 127.0.0.1 経由で通信します。

管理リクエストでは、アプリはまずトークンなしで試みます。プロキシが HTTP 401 を返した場合、アプリの環境変数 OPENCODEX_ADMIN_AUTH_TOKEN、または特定された設定ホームの admin-api-token ファイルを使って再試行します。このトークンに macOS Keychain は使いません。アプリからループバックで到達できないアドレスにのみバインドされたプロキシへは、デスクトップアプリから接続できません。

ソースからビルド

macOS 13 以降で Bun、Rust、macOS の Swift/Xcode ツールが利用できる場合、リポジトリのルートでダッシュボードをビルドし、次に desktop/ からデスクトップ用コマンドを実行します。

bun install
bun run build:gui
cd desktop
bun install
bun run prepare-sidecar
bun run prepare-widget
bun run build:local

build:local は Tauri 更新用の署名キーなしでローカルアプリと DMG を生成します。直接 bunx tauri build を実行すると更新用成果物も生成するため、TAURI_SIGNING_PRIVATE_KEY が必要です。ウィジェットのビルドでは MACOS_SIGN_IDENTITY を設定しない限りアドホック署名が使われ、ローカルのデスクトップバンドルもアドホック署名になります。アプリは動作しますが、macOS はアドホック署名されたウィジェット拡張を登録しないため、ローカルビルドでは通常 OpenCodex ウィジェットが表示されません。build:local は常にアプリをアドホック署名するので、MACOS_SIGN_IDENTITY だけを設定しても解決しません。ウィジェットが登録されるのは、リリースビルドと同様にアプリと拡張の両方が同じ Developer ID チームで署名された場合だけです。ウィジェットが必要ならリリースビルドを使ってください。

アンインストール

有効にしていた場合はトレイメニューの Start at Login をオフにしてから、Applications の OpenCodex.app をゴミ箱へ移動します。同梱 CLI とウィジェット拡張は削除されますが、プロキシの $OPENCODEX_HOME 状態や別にインストールした ocx サービスは削除されません。デスクトップアプリは、アプリ設定ディレクトリにインストール ID とログイン項目のマーカー、さらに ~/Library/Containers/com.opencodex.desktop.widget/Data/Library/Application Support/OpenCodex/snapshot.json にウィジェットのスナップショットも書き込みます。アプリをゴミ箱へ移動しても、これらのファイルは削除されません。