Jason
a058ebeafc
Refresh the user manual to cover the v3.13.0 feature set so users can discover and correctly use new functionality without cross-referencing the release notes. All three language versions are updated line-by-line symmetric. Highlights: - Lightweight Mode: tray-only running state added in 1.5-settings, with a comparison table against "Minimize to tray" and a new OAuth Auth Center (Beta) section - Quota & Balance display restructured in 2.5-usage-query: split into auto-query (Claude/Codex/Gemini official, Copilot, Codex OAuth) vs manual-enable (Token Plan, third-party balances). Explains why manual enabling is required: the same API URL may expose both plan-quota and balance query modes - Codex OAuth reverse proxy: full usage guide in 2.1-add with two entry points (Add Provider panel / OAuth Auth Center), Device Code login flow, token auto-refresh, multi-account management, quota display, common failures, and risk notice - Full URL Endpoint Mode: new advanced option in 2.1-add - Per-app tray submenus: 2.2-switch refactored to reflect the 5-app submenu structure and cross-link to Lightweight Mode - Skills workflow: remove obsolete "automatic update not supported" section in 3.3-skills, add SHA-256 update detection, single/batch update, storage location switch, and skills.sh registry search - Directory picker for Claude terminal resume in 3.4-sessions - Usage stats in 4.4-usage: document the new CLI session log source (no proxy required) and per-app filtering for Claude/Codex/Gemini; note CNY->USD pricing corrections and MiniMax quota fixes - Stream Check coverage extended to OpenCode/OpenClaw in 4.5-model-test - New FAQs in 5.2-questions: quota visibility (auto vs manual), Codex OAuth risks and login flow, deep link wake in Lightweight Mode - v3.13.0 highlights navigation block added to top-level README and each per-language README; version bumped to v3.13.0 / 2026-04-08
12 KiB
5.2 よくある質問 FAQ
インストールに関する問題
macOS のインストール
CC Switch の macOS 版は Apple のコード署名と公証を受けています。追加の操作なしで直接ダウンロードしてインストールできます。問題が発生した場合は、Releases ページ から最新版をダウンロードしてください。
Windows でインストール後に起動できない
考えられる原因：
- WebView2 ランタイムが不足
- ウイルス対策ソフトによるブロック
解決方法：
- Microsoft Edge WebView2 をインストール
- CC Switch をウイルス対策ソフトのホワイトリストに追加
Linux で起動エラー
問題：AppImage が起動しない
解決方法：
# 実行権限を追加
chmod +x CC-Switch-*.AppImage
# それでも失敗する場合
./CC-Switch-*.AppImage --no-sandbox
プロバイダーに関する問題
プロバイダーを切り替えても反映されない
原因：CLI ツールが設定を再読み込みする必要がある
解決方法：
- Claude Code：ターミナルを閉じて再度開く、または IDE を再起動
- Codex：ターミナルを閉じて再度開く
- Gemini：トレイからの切り替えで即時反映、再起動不要
API Key が無効
確認手順：
- API Key が正しくコピーされているか（余分なスペースがないか）
- API Key が期限切れでないか
- エンドポイントアドレスが正しいか
- 速度テストで接続を確認
公式ログインに戻すには
操作手順：
- 「公式ログイン」プリセット（Claude/Codex）または「Google 公式」プリセット（Gemini）を選択
- 「有効化」をクリック
- 対応する CLI ツールを再起動
- CLI ツールのログインフローに従って操作
プロキシに関する問題
プロキシサービスの起動に失敗する
考えられる原因：ポートが使用中
解決方法：
- ポートの使用状況を確認：
# macOS/Linux lsof -i :49152 # Windows netstat -ano | findstr :49152 - ポートを使用しているプログラムを終了
- または設定を変更してデフォルトポートに復旧：
- 「設定 → プロキシサービス」を開く
- 「デフォルトに戻す」ボタンをクリック
プロキシモードでリクエストがタイムアウトする
考えられる原因：
- ネットワークの問題
- プロバイダーのサーバーの問題
- プロキシ設定のエラー
解決方法：
- ネットワーク接続を確認
- プロバイダーの API に直接アクセスを試みる（プロキシを無効にして）
- プロバイダーの設定が正しいか確認
プロキシを無効にしても設定が復元されない
考えられる原因：プロキシの異常終了
解決方法：
- 現在のプロバイダーを編集
- エンドポイントアドレスが正しいか確認
- 保存して設定を更新
フェイルオーバーに関する問題
フェイルオーバーがトリガーされない
チェックリスト：
- プロキシサービスが実行中か
- アプリケーション接管が有効か
- 自動フェイルオーバーが有効か
- キューにバックアッププロバイダーがあるか
フェイルオーバーが頻繁にトリガーされる
考えられる原因：
- メインプロバイダーが不安定
- サーキットブレーカーの閾値が低すぎる
解決方法：
- メインプロバイダーの状態を確認
- 失敗閾値を引き上げる（例：3 → 5）
- メインプロバイダーの変更を検討
すべてのプロバイダーがサーキットブレーカー発動中
解決方法：
- サーキットブレーカー期間満了を待つ（デフォルト 60 秒）
- またはプロキシサービスを再起動して状態をリセット
データに関する問題
設定が消えた
考えられる原因：
- 設定ディレクトリが削除された
- データベースが破損
解決方法：
~/.cc-switch/ディレクトリが存在するか確認- バックアップから復元：
~/.cc-switch/backups/ - または以前にエクスポートした設定ファイルからインポート
設定のインポートに失敗する
考えられる原因：
- ファイル形式のエラー
- バージョンの非互換性
解決方法：
- ファイルが CC Switch からエクスポートされた JSON ファイルであることを確認
- ファイル内容が完全であるか確認
- テキストエディタで開いてフォーマットを確認
使用量統計のデータが空
チェックリスト：
- プロキシサービスが実行中か
- アプリケーション接管が有効か
- ログ記録が有効か
- プロキシ経由でリクエストがあったか
クォータ・残高
なぜ一部のプロバイダーは自動的にクォータが表示され、他は手動で有効化する必要があるのですか？
公式サブスクリプション系（Claude / Codex / Gemini 公式ログイン、GitHub Copilot、Codex OAuth リバースプロキシ）のみ、プロバイダーを有効化すると自動的にクォータが表示されます。その他すべてのプロバイダー（Token Plan および第三者残高クエリを含む）は、プロバイダーカードの「使用量クエリ」パネルで手動でスイッチをオンにし、内蔵テンプレートを選択する必要があります。同じリクエスト URL が「プラン」と「残高」の両方のクエリモードを持つ可能性があるため、ユーザー自身が選択する必要があるからです。詳細は 2.5 使用量クエリ → 手動有効化 を参照してください。
公式サブスクリプションのプロバイダーにクォータが表示されない
確認事項：
- プロバイダーが「現在有効」状態であることを確認（非アクティブ時はクエリがトリガーされません）
- Copilot / Codex OAuth の場合、OAuth Token がまだ有効期限内か確認。カードに「セッション期限切れ」と表示されたら OAuth 認証センター で再ログインしてください
- ネットワーク接続を確認
- カード上の更新アイコンをクリックして手動で再取得
Token Plan や第三者残高を有効化しても表示されない
確認事項：
- 「使用量クエリ」パネルで「使用量クエリを有効にする」スイッチがオンになっているか
- 適切な内蔵テンプレートが選択されて保存されているか
- 「スクリプトをテスト」をクリックして具体的なエラーを確認
- プロバイダーが「現在有効」状態のときのみバックグラウンド自動更新が動作します
Codex の使用量が直接接続時と合わない
v3.13.0 で Codex の使用量が推定値から JSONL セッションログに基づく精密解析 に切り替わり、モデル名が正規化されて料金検索の整合性が保たれます。新しいデータは公式の請求と一致します。古い推定データが残っている場合は、履歴エントリを削除するか、新しいセッションデータによる上書きを待ってください。
Codex OAuth リバースプロキシ
Codex OAuth のログイン方法は？
完全な Device Code ログインフロー（認証コード + ブラウザ認証）、2 つの入口（プロバイダー追加パネル / OAuth 認証センター）、マルチアカウント管理、よくある失敗シナリオは 2.1 プロバイダーの追加 → Codex OAuth リバースプロキシ（Claude プロバイダー） を参照してください。
Codex OAuth リバースプロキシを有効化するリスクは？
Codex OAuth リバースプロキシは リバースエンジニアリングされた OAuth フロー で ChatGPT アカウントの Codex サービスにアクセスします。OpenAI の利用規約に違反する可能性があり、アカウント制限や停止のリスクがあり、長期的な可用性も保証されません。有効化すると自己責任となります。
完全な免責事項は v3.13.0 Release Notes → リスク通知 と 2.1 プロバイダーの追加 → Codex OAuth リバースプロキシ を参照してください。
Codex OAuth にログインしたがクォータが表示されない
解決方法：
- OAuth 認証センター（設定 → OAuth 認証センター、Beta ラベル付き）で OAuth ログインフローが完了していることを確認
- Token がまだ有効期限内か確認。カードに「セッション期限切れ」と表示される場合は Token が更新できない状態
- 期限切れの場合は、OAuth 認証センターでアカウントを削除して再ログインしてください
その他の問題
トレイアイコンが表示されない
macOS：
- システム設定のメニューバーアイコン設定を確認
Windows：
- タスクバーの設定で、CC Switch のアイコンが非表示になっていないか確認
Linux：
- システムトレイのサポート（例：
libappindicator）がインストールされている必要あり
インターフェースの表示が異常
解決方法：
- テーマを切り替えてみる（ライト/ダーク）
- アプリを再起動
~/.cc-switch/settings.jsonを削除して設定をリセット
更新に失敗する
解決方法：
- ネットワーク接続を確認
- 最新版を手動でダウンロードしてインストール
- Homebrew を使用する場合：
brew upgrade --cask cc-switch
軽量モード
軽量モードに入るには？
システムトレイメニューから「軽量モード」をトグルします。メインウィンドウが閉じ、CC Switch はトレイ専用アプリとして動作します。再度トグルするか「メインウィンドウを開く」をクリックすると終了します。
軽量モードではメモリ使用量が少なくなる？
はい。軽量モードではメインウィンドウとその Web ビューを破棄するため、トレイメニュー機能を維持しながらメモリ使用量を大幅に削減します。
軽量モードでもディープリンクでメインウィンドウを呼び出せる？
はい。CC Switch v3.13.0 より、すべてのウィンドウ再表示パス（通常起動、ディープリンク、シングルトン起動、トレイ show_main、軽量モードからの復帰）をカバーしています。ccswitch:// リンクをクリックするとメインウィンドウが 必要に応じて再構築 され、インポート確認ダイアログが表示されます。初回起動は通常状態より若干遅くなります（ウィンドウの再構築が必要なため）が、以降の切り替えは通常速度に戻ります。
ヘルプの入手
Issue の提出
上記の方法で問題が解決しない場合：
- GitHub Issues にアクセス
- 類似の問題がないか検索
- なければ新しい Issue を作成
- 以下の情報を提供：
- オペレーティングシステムとバージョン
- CC Switch のバージョン
- 問題の説明と再現手順
- エラーメッセージ（ある場合）
ログファイル
Issue を提出する際にログファイルを添付できます：
- macOS/Linux：
~/.cc-switch/logs/ - Windows：
%APPDATA%\cc-switch\logs\