Skip to content

Latest commit

 

History

History
216 lines (136 loc) · 13.6 KB

TROUBLESHOOTING.md

File metadata and controls

216 lines (136 loc) · 13.6 KB

トラブルシューティング

🌐 Languages: 🇺🇸 English | 🇧🇷 Português (Brasil) | 🇪🇸 Español | 🇫🇷 Français | 🇮🇹 Italiano | 🇷🇺 Русский | 🇨🇳 中文 (简体) | 🇩🇪 Deutsch | 🇮🇳 हिन्दी | 🇹🇭 ไทย | 🇺🇦 Українська | 🇸🇦 العربية | 🇯🇵 日本語 | 🇻🇳 Tiếng Việt | 🇧🇬 Български | 🇩🇰 Dansk | 🇫🇮 Suomi | 🇮🇱 עברית | 🇭🇺 Magyar | 🇮🇩 Bahasa Indonesia | 🇰🇷 한국어 | 🇲🇾 Bahasa Melayu | 🇳🇱 Nederlands | 🇳🇴 Norsk | 🇵🇹 Português (Portugal) | 🇷🇴 Română | 🇵🇱 Polski | 🇸🇰 Slovenčina | 🇸🇪 Svenska | 🇵🇭 Filipino

OmniRoute の一般的な問題と解決策。

クイックフィックス

問題 ソリューション
最初のログインが機能しない .env の INITIAL_PASSWORD を確認します (デフォルト: 123456)。
ダッシュボードが間違ったポートで開きます PORT=20128 と NEXT_PUBLIC_BASE_URL=http://localhost:20128 を設定します。
logs/ の下にリクエスト ログがありません ENABLE_REQUEST_LOGS=true を設定
EACCES: 許可が拒否されました DATA_DIR=/path/to/writable/dir を設定して ~/.omniroute をオーバーライドする
ルーティング戦略が保存されない v1.4.11+ に更新 (設定永続性のための Zod スキーマ修正)

プロバイダーの問題

「言語モデルがメッセージを提供しませんでした」

原因: プロバイダーの割り当てが枯渇しました。

修正:

  1. ダッシュボードのクォータ トラッカーを確認する
  2. フォールバック層とのコンボを使用する
  3. より安価な/無料枠に切り替える

レート制限

原因: サブスクリプション割り当てを使い果たしました。

修正:

  • フォールバックを追加: cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking
  • 安価なバックアップとして GLM/MiniMax を使用する

OAuth トークンの有効期限が切れました

OmniRoute はトークンを自動更新します。問題が解決しない場合:

  1. ダッシュボード → プロバイダー → 再接続
  2. プロバイダー接続を削除して再度追加します。

クラウドの問題

クラウド同期エラー

  1. BASE_URL が実行中のインスタンス (例: http://localhost:20128) を指していることを確認します。
  2. CLOUD_URL がクラウド エンドポイント (例: https://omniroute.dev) を指していることを確認します。
  3. NEXT_PUBLIC_* 値をサーバー側の値と一致させておく

クラウド stream=false は 500 を返します

症状: 非ストリーミング通話のクラウド エンドポイントで Unexpected token 'd'... が発生します。

原因: クライアントが JSON を期待しているのに、アップストリームは SSE ペイロードを返します。

回避策: クラウド直接呼び出しには stream=true を使用します。ローカル ランタイムには SSE→JSON フォールバックが含まれます。

クラウドは接続済みだが「API キーが無効です」と表示します

  1. ローカル ダッシュボードから新しいキーを作成します (/api/keys)
  2. クラウド同期を実行します: [クラウドを有効にする] → [今すぐ同期]
  3. 古い/非同期キーはクラウド上でも 401 を返すことができます

Docker の問題

CLI ツールがインストールされていないと表示される

  1. 実行時フィールドを確認します: curl http://localhost:20128/api/cli-tools/runtime/codex | jq
  2. ポータブル モードの場合: イメージ ターゲット runner-cli (バンドルされた CLI) を使用します。
  3. ホスト マウント モードの場合: CLI_EXTRA_PATHS を設定し、ホストの bin ディレクトリを読み取り専用としてマウントします。
  4. installed=true および runnable=false の場合: バイナリは見つかりましたが、ヘルスチェックに失敗しました

迅速なランタイム検証

curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
curl -s http://localhost:20128/api/cli-tools/claude-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'

コストの問題

高コスト

1.「ダッシュボード」→「使用状況」で使用状況統計を確認します。2. プライマリ モデルを GLM/MiniMax に切り替える 3. 重要ではないタスクには無料枠 (Gemini CLI、iFlow) を使用する 4. API キーごとにコスト予算を設定します: [ダッシュボード] → [API キー] → [予算]

デバッグ

リクエストログを有効にする

.env ファイルに ENABLE_REQUEST_LOGS=true を設定します。ログは logs/ ディレクトリの下に表示されます。

プロバイダーの健全性を確認する

# Health dashboard
http://localhost:20128/dashboard/health

# API health check
curl http://localhost:20128/api/monitoring/health

ランタイムストレージ

  • メイン状態: ${DATA_DIR}/db.json (プロバイダー、コンボ、エイリアス、キー、設定)
  • 使用法: ${DATA_DIR}/usage.json、${DATA_DIR}/log.txt、${DATA_DIR}/call_logs/
  • リクエストログ：<repo>/logs/...（ENABLE_REQUEST_LOGS=trueの場合）

サーキットブレーカーの問題

プロバイダーが OPEN 状態でスタックしている

プロバイダーのサーキット ブレーカーが OPEN の場合、リクエストはクールダウンが期限切れになるまでブロックされます。

修正:

  1. ダッシュボード → 設定 → レジリエンス に移動します
  2. 影響を受けるプロバイダーのサーキット ブレーカー カードを確認します。
  3. [すべてリセット] をクリックしてすべてのブレーカーをクリアするか、クールダウンが期限切れになるまで待ちます。
  4. リセットする前に、プロバイダーが実際に利用可能であることを確認します。

プロバイダーがサーキットブレーカーを落とし続けます

プロバイダーが繰り返し OPEN 状態になる場合:

  1. ダッシュボード → ヘルス → プロバイダーのヘルス で障害パターンを確認します。
  2. [設定] → [復元力] → [プロバイダー プロファイル] に移動し、失敗のしきい値を増やします。
  3. プロバイダーが API 制限を変更したか、再認証が必要かどうかを確認します。
  4. レイテンシーテレメトリを確認します - レイテンシーが長いとタイムアウトベースのエラーが発生する可能性があります

音声文字起こしの問題

「サポートされていないモデル」エラー

  • 正しいプレフィックスを使用していることを確認してください: deepgram/nova-3 または assemblyai/best
  • **「ダッシュボード」→「プロバイダー」**でプロバイダーが接続されていることを確認します。

文字起こしが空を返すか失敗する

  • サポートされているオーディオ形式を確認します: mp3、wav、m4a、flac、ogg、webm
  • ファイル サイズがプロバイダーの制限内であることを確認します (通常は < 25MB)
  • プロバイダー カードのプロバイダー API キーの有効性を確認します。

トランスレータのデバッグ

ダッシュボード → トランスレーター を使用して、形式変換の問題をデバッグします。

モード いつ使用するか
遊び場 入力/出力形式を並べて比較します。失敗したリクエストを貼り付けて、それがどのように変換されるかを確認します。
チャット テスター ライブ メッセージを送信し、ヘッダーを含む完全なリクエスト/レスポンス ペイロードを検査します。
テストベンチ フォーマットの組み合わせ全体でバッチ テストを実行して、どの翻訳が壊れているかを見つけます。
ライブモニター リアルタイムのリクエスト フローを監視して断続的な翻訳の問題を検出

一般的な形式の問題

  • 思考タグが表示されない — ターゲットプロバイダーが思考と思考予算設定をサポートしているかどうかを確認してください
  • ツール呼び出しのドロップ — 一部の形式変換では、サポートされていないフィールドが削除される場合があります。プレイグラウンド モードで確認する
  • システム プロンプトがありません — クロードとジェミニはシステム プロンプトの処理方法が異なります。翻訳出力を確認する
  • SDK はオブジェクトではなく生の文字列を返します — v1.1.0 で修正されました: 応答サニタイザーは、OpenAI SDK Pydantic 検証エラーの原因となる非標準フィールド (x_groq、usage_breakdown など) を削除するようになりました。
  • GLM/ERNIE が system ロールを拒否します — v1.1.0 で修正: ロール ノーマライザーは、互換性のないモデルのシステム メッセージをユーザー メッセージに自動的にマージします
  • developer ロールが認識されない — v1.1.0 で修正: 非 OpenAI プロバイダーの場合は自動的に system に変換されます
  • json_schema が Gemini で動作しない — v1.1.0 で修正: response_format は Gemini の responseMimeType + responseSchema に変換されるようになりました。

復元力の設定

自動レート制限がトリガーされない

  • 自動レート制限は API キープロバイダーにのみ適用されます (OAuth/サブスクリプションには適用されません)
  • 設定 → 復元力 → プロバイダー プロファイル で自動レート制限が有効になっていることを確認します
  • プロバイダーが 429 ステータス コードまたは Retry-After ヘッダーを返すかどうかを確認します。

指数バックオフの調整

プロバイダー プロファイルは次の設定をサポートします。

  • 基本遅延 — 最初の失敗後の初期待機時間 (デフォルト: 1 秒)
  • 最大遅延 — 最大待機時間の上限 (デフォルト: 30 秒)
  • 乗数 — 連続した失敗ごとにどれだけ遅延を増加させるか (デフォルト: 2x)

対雷の群れ

多くの同時リクエストがレート制限プロバイダーに到達すると、OmniRoute はミューテックスと自動レート制限を使用してリクエストをシリアル化し、連鎖的な失敗を防ぎます。これは API キープロバイダーの場合は自動的に行われます。

まだ行き詰まっていますか?

  • GitHub の問題: github.com/diegosouzapw/OmniRoute/issues
  • アーキテクチャ: 内部の詳細については、OMNI_TOKEN_55 を参照してください。
  • API リファレンス: すべてのエンドポイントについては、OMNI_TOKEN_56 を参照してください。
  • ヘルス ダッシュボード: リアルタイムのシステム ステータスについては、ダッシュボード → ヘルス を確認してください。
  • トランスレータ: ダッシュボード → トランスレータを使用して形式の問題をデバッグします