# 5.2 よくある質問 FAQ

## インストールに関する問題

### macOS のインストール

CC Switch の macOS 版は Apple のコード署名と公証を受けています。追加の操作なしで直接ダウンロードしてインストールできます。問題が発生した場合は、[Releases ページ](https://github.com/farion1231/cc-switch/releases) から最新版をダウンロードしてください。

### Windows でインストール後に起動できない

**考えられる原因**：
- WebView2 ランタイムが不足
- ウイルス対策ソフトによるブロック

**解決方法**：
1. [Microsoft Edge WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) をインストール
2. CC Switch をウイルス対策ソフトのホワイトリストに追加

### Linux で起動エラー

**問題**：AppImage が起動しない

**解決方法**：
```bash
# 実行権限を追加
chmod +x CC-Switch-*.AppImage

# それでも失敗する場合
./CC-Switch-*.AppImage --no-sandbox
```

## プロバイダーに関する問題

### プロバイダーを切り替えても反映されない

**原因**：CLI ツールが設定を再読み込みする必要がある

**解決方法**：
- Claude Code：ターミナルを閉じて再度開く、または IDE を再起動
- Codex：ターミナルを閉じて再度開く
- Gemini：トレイからの切り替えで即時反映、再起動不要

### API Key が無効

**確認手順**：
1. API Key が正しくコピーされているか（余分なスペースがないか）
2. API Key が期限切れでないか
3. エンドポイントアドレスが正しいか
4. 速度テストで接続を確認

### 公式ログインに戻すには

**操作手順**：
1. 「公式ログイン」プリセット（Claude/Codex）または「Google 公式」プリセット（Gemini）を選択
2. 「有効化」をクリック
3. 対応する CLI ツールを再起動
4. CLI ツールのログインフローに従って操作

## プロキシに関する問題

### プロキシサービスの起動に失敗する

**考えられる原因**：ポートが使用中

**解決方法**：
1. ポートの使用状況を確認：
   ```bash
   # macOS/Linux
   lsof -i :49152

   # Windows
   netstat -ano | findstr :49152
   ```
2. ポートを使用しているプログラムを終了
3. または設定を変更してデフォルトポートに復旧：
   - 「設定 → プロキシサービス」を開く
   - 「デフォルトに戻す」ボタンをクリック

### プロキシモードでリクエストがタイムアウトする

**考えられる原因**：
- ネットワークの問題
- プロバイダーのサーバーの問題
- プロキシ設定のエラー

**解決方法**：
1. ネットワーク接続を確認
2. プロバイダーの API に直接アクセスを試みる（プロキシを無効にして）
3. プロバイダーの設定が正しいか確認

### プロキシを無効にしても設定が復元されない

**考えられる原因**：プロキシの異常終了

**解決方法**：
1. 現在のプロバイダーを編集
2. エンドポイントアドレスが正しいか確認
3. 保存して設定を更新

## フェイルオーバーに関する問題

### フェイルオーバーがトリガーされない

**チェックリスト**：
- [ ] プロキシサービスが実行中か
- [ ] アプリケーション接管が有効か
- [ ] 自動フェイルオーバーが有効か
- [ ] キューにバックアッププロバイダーがあるか

### フェイルオーバーが頻繁にトリガーされる

**考えられる原因**：
- メインプロバイダーが不安定
- サーキットブレーカーの閾値が低すぎる

**解決方法**：
1. メインプロバイダーの状態を確認
2. 失敗閾値を引き上げる（例：3 → 5）
3. メインプロバイダーの変更を検討

### すべてのプロバイダーがサーキットブレーカー発動中

**解決方法**：
1. サーキットブレーカー期間満了を待つ（デフォルト 60 秒）
2. またはプロキシサービスを再起動して状態をリセット

## データに関する問題

### 設定が消えた

**考えられる原因**：
- 設定ディレクトリが削除された
- データベースが破損

**解決方法**：
1. `~/.cc-switch/` ディレクトリが存在するか確認
2. バックアップから復元：`~/.cc-switch/backups/`
3. または以前にエクスポートした設定ファイルからインポート

### 設定のインポートに失敗する

**考えられる原因**：
- ファイル形式のエラー
- バージョンの非互換性

**解決方法**：
1. ファイルが CC Switch からエクスポートされた SQL バックアップファイルであることを確認
2. ファイル内容が完全であるか確認
3. テキストエディタで開いてフォーマットを確認

### 使用量統計のデータが空

**チェックリスト**：
- [ ] プロキシサービスが実行中か
- [ ] アプリケーション接管が有効か
- [ ] ログ記録が有効か
- [ ] プロキシ経由でリクエストがあったか

## クォータ・残高

### なぜ一部のプロバイダーは自動的にクォータが表示され、他は手動で有効化する必要があるのですか？

**公式サブスクリプション系**（Claude / Codex / Gemini 公式ログイン、GitHub Copilot、Codex OAuth リバースプロキシ）のみ、プロバイダーを有効化すると自動的にクォータが表示されます。**その他すべてのプロバイダー**（Token Plan および第三者残高クエリを含む）は、プロバイダーカードの「使用量クエリ」パネルで手動でスイッチをオンにし、内蔵テンプレートを選択する必要があります。同じリクエスト URL が「プラン」と「残高」の両方のクエリモードを持つ可能性があるため、ユーザー自身が選択する必要があるからです。詳細は [2.5 使用量クエリ → 手動有効化](../2-providers/2.5-usage-query.md#手動有効化内蔵テンプレート--カスタムスクリプト) を参照してください。

### 公式サブスクリプションのプロバイダーにクォータが表示されない

**確認事項**：
1. プロバイダーが「現在有効」状態であることを確認（非アクティブ時はクエリがトリガーされません）
2. Copilot / Codex OAuth の場合、OAuth Token がまだ有効期限内か確認。カードに「セッション期限切れ」と表示されたら **OAuth 認証センター** で再ログインしてください
3. ネットワーク接続を確認
4. カード上の更新アイコンをクリックして手動で再取得

### Token Plan や第三者残高を有効化しても表示されない

**確認事項**：
1. 「使用量クエリ」パネルで「使用量クエリを有効にする」スイッチがオンになっているか
2. 適切な内蔵テンプレートが選択されて保存されているか
3. 「スクリプトをテスト」をクリックして具体的なエラーを確認
4. プロバイダーが「現在有効」状態のときのみバックグラウンド自動更新が動作します

### Codex の使用量が直接接続時と合わない

v3.13.0 で Codex の使用量が推定値から **JSONL セッションログに基づく精密解析** に切り替わり、モデル名が正規化されて料金検索の整合性が保たれます。新しいデータは公式の請求と一致します。古い推定データが残っている場合は、履歴エントリを削除するか、新しいセッションデータによる上書きを待ってください。

## Codex OAuth リバースプロキシ

### Codex OAuth のログイン方法は？

完全な Device Code ログインフロー（認証コード + ブラウザ認証）、2 つの入口（プロバイダー追加パネル / OAuth 認証センター）、マルチアカウント管理、よくある失敗シナリオは [2.1 プロバイダーの追加 → Codex OAuth リバースプロキシ（Claude プロバイダー）](../2-providers/2.1-add.md#codex-oauth-リバースプロキシclaude-プロバイダー) を参照してください。

### Codex OAuth リバースプロキシを有効化するリスクは？

Codex OAuth リバースプロキシは **リバースエンジニアリングされた OAuth フロー** で ChatGPT アカウントの Codex サービスにアクセスします。OpenAI の利用規約に違反する可能性があり、アカウント制限や停止のリスクがあり、長期的な可用性も保証されません。**有効化すると自己責任となります**。

完全な免責事項は [v3.13.0 Release Notes → リスク通知](../../../release-notes/v3.13.0-ja.md#️-リスク通知) と [2.1 プロバイダーの追加 → Codex OAuth リバースプロキシ](../2-providers/2.1-add.md#codex-oauth-リバースプロキシclaude-プロバイダー) を参照してください。

### Codex OAuth にログインしたがクォータが表示されない

**解決方法**：
1. **OAuth 認証センター**（設定 → OAuth 認証センター、Beta ラベル付き）で OAuth ログインフローが完了していることを確認
2. Token がまだ有効期限内か確認。カードに「セッション期限切れ」と表示される場合は Token が更新できない状態
3. 期限切れの場合は、OAuth 認証センターでアカウントを削除して再ログインしてください

## その他の問題

### トレイアイコンが表示されない

**macOS**：
- システム設定のメニューバーアイコン設定を確認

**Windows**：
- タスクバーの設定で、CC Switch のアイコンが非表示になっていないか確認

**Linux**：
- システムトレイのサポート（例：`libappindicator`）がインストールされている必要あり

### インターフェースの表示が異常

**解決方法**：
1. テーマを切り替えてみる（ライト/ダーク）
2. アプリを再起動
3. `~/.cc-switch/settings.json` を削除して設定をリセット

### 更新に失敗する

**解決方法**：
1. ネットワーク接続を確認
2. 最新版を手動でダウンロードしてインストール
3. Homebrew を使用する場合：`brew upgrade --cask cc-switch`

## 軽量モード

### 軽量モードに入るには？

システムトレイメニューから「軽量モード」をトグルします。メインウィンドウが閉じ、CC Switch はトレイ専用アプリとして動作します。再度トグルするか「メインウィンドウを開く」をクリックすると終了します。

### 軽量モードではメモリ使用量が少なくなる？

はい。軽量モードではメインウィンドウとその Web ビューを破棄するため、トレイメニュー機能を維持しながらメモリ使用量を大幅に削減します。

### 軽量モードでもディープリンクでメインウィンドウを呼び出せる？

はい。CC Switch v3.13.0 より、すべてのウィンドウ再表示パス（通常起動、ディープリンク、シングルトン起動、トレイ `show_main`、軽量モードからの復帰）をカバーしています。`ccswitch://` リンクをクリックするとメインウィンドウが **必要に応じて再構築** され、インポート確認ダイアログが表示されます。初回起動は通常状態より若干遅くなります（ウィンドウの再構築が必要なため）が、以降の切り替えは通常速度に戻ります。

## ヘルプの入手

### Issue の提出

上記の方法で問題が解決しない場合：

1. [GitHub Issues](https://github.com/farion1231/cc-switch/issues) にアクセス
2. 類似の問題がないか検索
3. なければ新しい Issue を作成
4. 以下の情報を提供：
   - オペレーティングシステムとバージョン
   - CC Switch のバージョン
   - 問題の説明と再現手順
   - エラーメッセージ（ある場合）

### ログファイル

Issue を提出する際にログファイルを添付できます：

- macOS/Linux：`~/.cc-switch/logs/`
- Windows：`%APPDATA%\cc-switch\logs\`