Troubleshooting (日本語)

クイックリファレンス

OmniRoute を初めて使用しますか？ まずはこちらを確認してください。問題の 90% はこれで解決できます。

表示される内容	意味	対処方法
「接続できない」	OmniRoute が起動していない	omniroute または docker restart omniroute を実行する
「無効な API キー」	キーが間違っているか、有効期限が切れている	プロバイダーのウェブサイトからキーを再度コピーする
「レート制限を超過」	送信しているリクエストが多すぎる	1 分待つか、model: "auto" を使用して自動的にフォールバックする
「クォータを超過」	無料または有料のクォータを使い切った	プロバイダーを追加で接続するか、無料プロバイダー（Kiro、Pollinations）を使用する
「応答が遅い」	プロバイダーが混雑しているか、遠隔地にある	model: "auto/fast" を使用するか、より高速なプロバイダー（Groq、Cerebras）に接続する
「誤ったプロバイダーが使用された」	auto が別のプロバイダーを選択した	これは正常です！auto は最適なものを選択します。model: "openai/gpt-4o" で特定のプロバイダーを強制指定できます
「502 Bad Gateway」	プロバイダーが停止している	待ってから再試行するか、model: "auto" を使用してプロバイダーを切り替える
「401 Unauthorized」	認証情報が間違っている	API キーを確認するか、OAuth で再認証する
「omniroute が認識されない」	Windows PATH にグローバル node モジュールが含まれていない	npm のグローバルプレフィックスを Windows PATH に追加する。npm config get prefix で確認できます。
「429 Too Many Requests」	レート制限を受けている	1 分待つか、プロバイダーを追加で接続する

まだ解決しませんか？ 以下の詳細なトラブルシューティングを確認するか、Discord で質問してください。

---

詳細なトラブルシューティング

---

無料プロバイダーでのレート制限（429 / 400 / 401）

症状：無料または認証不要のプロバイダー（opencode、auggie など）で model: "auto" を使用すると、回答の代わりに断続的に HTTP 429、400、または 401 が返されます。少し後に同じプロンプトを再試行するとリクエストは成功しますが、自動処理（cron ジョブ、エージェント、スクリプト）は最初の失敗で停止します。

根本原因：次の 3 つの独立した障害モードが重なっています。

1. プロバイダーのレート制限（429）：無料枠では、一定時間枠ごとのクォータが適用されることがあります。並列呼び出しが集中するとクォータを使い切るため、時間枠がリセットされるまで後続のリクエストが拒否されます。
2. パススルー内の壊れたモデル（400/401）：auto/* プールには、カタログに登録されていても有効な認証情報が存在しない opencode のパススルーモデルが含まれる場合があります（例：oc/north-mini-code-free → 401）。自動ルーターがそのようなモデルを試して失敗すると、フォールバックが作動する前にエラーが伝播します。
3. 同時実行による増幅（負荷時の 429）：複数のエージェントまたは cron セッションが同時に auto にアクセスすると、リクエストの合計レートが無料プロバイダーの許容範囲を超え、正当な呼び出しまで不正利用として判定されます。

検証済みの修正方法（コミュニティ報告、2026-08-10）：次の 3 つの環境変数を調整し、無料枠の不安定さによって処理が停止するのではなく、ローテーション、同時実行制御、フォールバックによって吸収されるようにします。

export OMNIROUTE_ROTATE_ON_400=true           # 400/401 の場合は別のモデルまたはプロバイダーへ切り替える（壊れたパススルーモデルをスキップ）
export OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT=4   # 高負荷リクエストの明示的な受付上限（デフォルトでは未設定：リクエスト数の上限なし。下記の注記を参照）
export OMNIROUTE_CHAT_ADMISSION_QUEUE_MS=5000 # 即時に再試行可能な 503 を返す代わりに、高負荷処理の空きを待つ時間を制限付きで延長

これらを OmniRoute プロセスの環境（デーモン。例：LaunchAgent plist または systemctl edit 経由）に設定し、OmniRoute を再起動してください。ローテーションフラグは、最も大きな効果をもたらす単一の設定です。ハードエラーを、プール内の正常なプロバイダーに対する透過的な再試行へ変換します。

注記：OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT は、同時に実行される高負荷（長いコンテキスト）のリクエスト数を制限します。この上限は受付ゲートであり、プロバイダーのレートリミッターではありません。**#503-fanout の更新：**この変数はデフォルトでは設定されなくなりました（上記のように明示的に設定した場合にのみ制限が適用されます）。代わりに、高負荷リクエストの受付は、ホストの実際のメモリ上限に応じて自動調整されるバイト予算（OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES）によって制御されます。そのため、新規デプロイでは、この変数を設定しなくても 503 chat_admission_busy による拒否が大幅に減るはずです。ここで明示的に設定した場合も、記載どおりに動作します。明示的なバイト予算のオーバーライドは、8 MiB～2 GiB の範囲に制限されます。413 body_exceeds_budget は一時的なエラーではありません。そのバイト予算を増やすか、OMNIROUTE_CHAT_HARD_MAX_BODY_BYTES を下げるか、プロセスのメモリ上限を増やしてください。inflight_bytes_budget による負荷遮断は一時的な競合であり、引き続き再試行可能です。プロバイダーごとのレート制限（open-sse/services/rateLimitManager.ts）は、RATE_LIMIT_MAX_WAIT_MS、RATE_LIMIT_MAX_QUEUE_DEPTH、RATE_LIMIT_AUTO_ENABLE によって個別に制御されます。.env.example を参照してください。

動作確認方法: エージェント/cron を短時間に続けて2回実行し、両方が成功することを確認してください。修正前は通常、2回目の実行で 429/401 が発生します。修正後は、エラー（発生した場合）が透過的に再試行され、呼び出しが完了します。また、curl /monitoring/health を実行し、プロバイダー接続の rateLimitedUntil フィールドと、影響を受けるプロバイダーの circuitBreakers.providerBreakers[].state を監視することもできます。状態は CLOSED、DEGRADED、OPEN、HALF_OPEN のいずれかです（src/shared/utils/circuitBreaker.ts を参照）。失敗し続けるプロバイダーは、リセット期間の経過後にプローブが許可される（HALF_OPEN）まで、CLOSED → DEGRADED → OPEN と遷移します。

それでも 429 が発生する場合: そのプロバイダーで現在使用中のアカウントが、単なるレート制限ではなく、実際に_クォータ_を使い果たしています。OmniRoute ダッシュボードの Providers → Accounts で、同じプロバイダー用の2つ目のアカウントを追加するか、別の無料プロバイダー（例: routeway、auggie）も組み合わせてください。ローテーションが有効なのは一時的なレート制限/400/401に対してのみです。クォータを完全に使い果たした場合は、2つ目の認証情報または別のプロバイダーが必要です。

ビジョンモデル（auto/vision、bazaarlink/*）で 403 が発生する場合: 接続されているアカウントにビジョンを含む有料プランがないか、API キーの権限が不十分です。プロバイダーのダッシュボードで、キーのスコープにビジョン/マルチモーダルが含まれていることを確認するか、有料プランのアカウントを接続し、ビジョン用のターゲットとして設定したままにしてください。

---

npm install の警告（ERESOLVE / peer / deprecated）

npm install -g omniroute を実行すると、npm warn ERESOLVE、peer dependency に関する通知、deprecated メッセージなど、大量の警告が表示される場合があります。これらは想定内であり、問題ありません。 出力に added <N> packages と表示されていれば、インストールは成功しています。

peer dependency の解決に関する警告を抑制するには、OmniRoute がサポートする次の形式でインストールしてください。

npm install -g omniroute --legacy-peer-deps

--legacy-peer-deps で抑制されるのは、ERESOLVE と peer dependency に関する通知のみです。非推奨の通知は推移的に依存しているサードパーティパッケージから発生するため、引き続き表示されますが、インストールの失敗を示すものではありません。

これらの警告は、OmniRoute が管理していないサードパーティパッケージにある、古い peer dependency のバージョン範囲が原因です。

1. marked-terminal は marked >=1 <16 を要求しているが、marked@18 が検出された — 実際には問題なく動作します。upstream の peer dependency の範囲が古いだけです。
2. deprecated prebuild-install@7.1.3 — 推移的に依存している、ネイティブバイナリ取得用のヘルパーです。固定バージョンの wreq-js トランスポートバインディングのインストールには使用されず、web-cookie プロバイダーのトランスポート設定が失敗したことを示すものでもありません。

対応は不要です — upstream パッケージをフォークしない限り、これらの警告を完全に抑制することはできません。

---

Gemini Web と Playwright Chromium

Gemini Web リクエストで、Playwright Chromium がインストールされていないというメッセージとともに 503 が返される場合、 npm パッケージは存在しますが、ブラウザのバイナリがありません。 Playwright では意図的に、ブラウザのダウンロードが npm パッケージの インストールとは分離されているため、ブラウザをインストールするまではこのレスポンスが返されます。

npm をグローバルインストールした場合は、ブラウザキャッシュが同じ Playwright インストールに属するよう、 OmniRoute パッケージのディレクトリから Chromium をインストールしてください。

cd "$(npm root -g)/omniroute"
npx playwright install chromium

インストール後に OmniRoute を再起動し、Gemini Web リクエストを再試行してください。 Docker イメージから OmniRoute を実行する場合は、Chromium とその依存関係が含まれている -web イメージ（または runner-web ビルドターゲット）を使用してください。ベースイメージには含まれて いません。

---

クイック修正

問題	解決策
初回ログインが機能しない	.env で INITIAL_PASSWORD を設定してください（ハードコードされたデフォルト値はありません）
ダッシュボードが誤ったポートで開く	PORT=20128 と NEXT_PUBLIC_BASE_URL=http://localhost:20128 を設定してください
ログがディスクに書き込まれない	APP_LOG_TO_FILE=true を設定し、呼び出しログのキャプチャが有効になっていることを確認してください
EACCES: 権限が拒否された	DATA_DIR=/path/to/writable/dir を設定して ~/.omniroute を上書きしてください
ルーティング戦略が保存されない	最新の v3.x リリースに更新してください（設定の永続化に関する Zod スキーマの修正は以前のバージョンで提供済みです）
ログイン時のクラッシュ / 空白ページ	Node.js のバージョンを確認してください — 以下の Node.js Compatibility を参照してください
dlopen / slice is not valid mach-o file (macOS)	cd $(npm root -g)/omniroute/app && npm rebuild better-sqlite3 && omniroute を実行してください — 以下の macOS native module rebuild を参照してください
プロキシでの「fetch failed」	プロキシ設定が正しいレベルに設定されていることを確認してください — 以下の Proxy Issues を参照してください
Docker の curl: (56) Recv failure: Connection reset by peer	Docker のポートバインドが IPv6 に接続されている可能性があります。-p 127.0.0.1:20128:20128 を使用して IPv4 を強制するか、curl -4 でテストしてください。以下の Docker IPv6 を参照してください
ウイルス対策ソフトが README.md を隔離する	誤検知です — 以下の Antivirus false positives を参照してください
Kaspersky がデスクトップアプリをトロイの木馬として検出する	署名されていないインストーラーに対する挙動ベースの誤検知です — 以下の Antivirus false positives を参照してください

---

アンチウイルスの誤検知

Avast/AVG が README.md を MD:HttpRequest-inf[Susp] として隔離する

これは誤検知です。何も感染しておらず、対処は不要です。

Avast と AVG は、HTTP リクエストのように見えるリンクを多数含むプレーンテキスト/Markdown ファイルを検出するヒューリスティックを実行します。OmniRoute の README.md は npm パッケージに同梱されているため（package.json → files に記載されています）、グローバルインストール時に node_modules/omniroute/README.md に配置されます。また、このファイルには約15個の http://localhost:20128/... の例（MCP HTTP/SSE エンドポイント、A2A の .well-known URL、および curl スニペット）が含まれています。このリンク密度が、ヒューリスティックを作動させるのに十分な高さになっています。

最近になってのみ発生し始めた場合でも、ファイルの性質が変わったわけではありません。README のエンドポイント表が拡充され（MCP HTTP + SSE + A2A が追加されました）、curl の例も増えたため、しきい値を超えただけです。

このファイルは実行可能な内容を一切含まない、何の動作もしないドキュメントです。隔離から安全に復元できます。

対処方法：

1. 通知を停止する — アンチウイルスでインストールディレクトリを除外し（Avast: Settings → Exceptions）、グローバルの node_modules パスや OmniRoute のデータディレクトリ（~/.omniroute/）を追加します。
2. 誤検知を報告する — https://www.avast.com/false-positive-file-form.php から、隔離された README.md を添付して報告してください。テキストファイルに対してベンダーのヒューリスティックが過剰反応しているため、これがすべての利用者に役立つ解決策となります。

当方で「修正」しない理由： すべての例は http://localhost であり、localhost で https を使用すると、自己署名証明書に伴う煩雑さを避けられません。ある1社のヒューリスティックを回避するためにドキュメントを不自然に改変することは、スキャナーのバグに対応するために、すべての読者の利便性を損なうことになります。

Kaspersky がデスクトップアプリを PDM:Trojan.Win32.Generic として検出する

これは挙動ベースのヒューリスティックによる誤検知です。何も感染していません。 Kaspersky の PDM: プレフィックスは、この判定が Proactive Defense Module（System Watcher）によるものであることを意味します。これは既知のマルウェアとの一致ではなく、インストーラーが実行する_動作_を基に判定します。検知されると、Kaspersky はインストール全体を「ロールバック」し、すでに書き込まれたファイルも削除するため、アプリが破損した状態になるか、なくなってしまいます。

検出対象となるファイルは、デスクトップアプリにバンドルされた、明示済みのオープンソース依存関係に含まれる標準的な構成要素です。例：

• resources/app/.build/next/node_modules/playwright-<hash>/lib/…/agentParser.js および workerProcessEntry.js — Playwright。アプリ内でのプロバイダーログインとブラウザベースのチャットに使用される、ブラウザ自動化ライブラリです。
• resources/app/.build/next/node_modules/@wreq-js/binding-win32-<arch>-msvc-<hash>/wreq-js.win32-<arch>-msvc.node — Web Cookie を使用するプロバイダーで、ブラウザフィンガープリントを伴う HTTP 通信に使用される、バージョン固定済みの wreq-js ネイティブバインディングです（<arch> は x64 または arm64）。

検知される理由： Windows インストーラーはまだコード署名されていないため、未署名の NSIS インストーラーにはレピュテーションがなく、挙動ヒューリスティックが最大限に厳しい状態で実行されます。これに加えて、バンドルされたネイティブ DLL と、%LOCALAPPDATA%\Programs\OmniRoute 配下に書き込まれる数百個の .js ファイル（Next.js スタンドアロンビルドによる、ハッシュサフィックス付きのパッケージディレクトリを含む）が、ヒューリスティックを作動させるのに十分な条件となっています。コード署名は予定されていますが、導入されるまでは新しいリリースのたびに再発する可能性があります。

対処方法：

1. 最初にダウンロードを検証する（改ざんされたファイルではないことを確認します）。各リリースでは latest.yml が公開されており、その sha512 フィールド（base64）は OmniRoute.Setup.<version>.exe インストーラーを対象としています。インストーラーがあるフォルダーで、PowerShell から次を実行します：

   $b = [System.Security.Cryptography.SHA512]::Create().ComputeHash(
     [System.IO.File]::ReadAllBytes("$PWD\OmniRoute.Setup.<version>.exe"))
   [Convert]::ToBase64String($b)

   出力は latest.yml → sha512 と一致する必要があります。一致しない場合はファイルを削除し、GitHub releases page からのみ再ダウンロードしてください。
2. 復元して除外する — ロールバックされた項目を隔離から復元し、%LOCALAPPDATA%\Programs\OmniRoute を除外対象に追加して（Kaspersky → Settings → Threats and Exclusions）、再インストールします。
3. 誤検知を報告する — https://opentip.kaspersky.com/。ユーザーから提出される誤検知レポートは、許可リストへの登録を実際に迅速化します。

---

Node.js の互換性

ログインページがクラッシュする、または「Module self-registration」エラーが表示される

原因: OmniRoute が承認している安全なランタイムの最低要件を満たさないバージョンの Node.js を実行しています。最も一般的なケースは、OmniRoute が要求するセキュリティ修正済みの最低バージョンより古い Node 22 または 24 のパッチバージョンを実行している場合です。

症状:

• ログインページに空白の画面またはサーバーエラーが表示される
• コンソールに Error: Module did not self-register、または同様のネイティブバインディングエラーが表示される
• ランタイムがサポート対象の安全なポリシー範囲外の場合、ログインページに使用中の Node バージョンを示すオレンジ色の警告バナーが表示される

修正方法:

1. サポートされている Node.js LTS リリースをインストールします（推奨: Node.js 24.x）。

   nvm install 24
   nvm use 24

2. バージョンを確認します。24.x LTS 系では、node --version に v24.0.0 以降が表示される必要があります
3. OmniRoute を再インストールします: npm install -g omniroute
4. 再起動します: omniroute

サポートされている安全なバージョン: >=22.22.2 <23 または >=24.0.0 <27。Node.js 24.x LTS (Krypton) および Node.js 26 は完全にサポートされています。

npm v11+: better-sqlite3 がインストールされない（Cannot find module）

原因: npm v11（Node.js 24+ に同梱）は、オプションの依存関係に対するインストールスクリプトをデフォルトでブロックします。better-sqlite3 は optionalDependencies に記載されており、ネイティブコンパイル（node-gyp rebuild）が必要なため、npm によって通知なくスキップされます。

症状:

• サーバーの起動時に Cannot find module 'better-sqlite3' が発生してクラッシュする
• ls node_modules/better-sqlite3 を実行すると「No such file or directory」と表示される
• npm ls better-sqlite3 を実行すると (empty) と表示される

修正方法:

1. インストールスクリプトを承認して再インストールします。

   npm approve-scripts better-sqlite3
   npm install

2. または、ビルド済みパッケージを手動でインストールします。

   npm pack better-sqlite3@13.0.1
   tar -xzf better-sqlite3-*.tgz -C node_modules
   mv node_modules/package node_modules/better-sqlite3
   rm better-sqlite3-*.tgz

3. 正常に動作することを確認します: node -e "require('better-sqlite3')(':memory:').close(); console.log('OK')"

macOS: dlopen / 「slice is not valid mach-o file」

原因: グローバルで npm install -g omniroute を実行した後、パッケージ内の better-sqlite3 ネイティブバイナリが、ローカルで実行されているものとは異なるアーキテクチャまたは Node.js ABI 向けにコンパイルされている場合があります。これは、ビルド済みバイナリが使用環境と一致しない場合に、macOS（Apple Silicon と Intel の両方）でよく発生します。

症状:

• サーバーが起動直後に dlopen エラーで停止する
• エラーに slice is not valid mach-o file が含まれる
• 完全な例:

dlopen(/Users/<user>/.nvm/versions/node/v24.14.1/lib/node_modules/omniroute/app/node_modules/better-sqlite3/build/Release/better_sqlite3.node, 0x0001): tried: '...' (slice is not valid mach-o file)

修正方法 — ローカル環境向けに再ビルドします（Node.js のダウングレードは不要です）:

cd $(npm root -g)/omniroute/app
npm rebuild better-sqlite3
omniroute

注: これにより、ローカルの Node.js バージョンおよび CPU アーキテクチャに合わせてネイティブバインディングが再コンパイルされ、バイナリの不一致が解消されます。公式にサポートされているランタイムの範囲は >=22.22.2 <23 または >=24.0.0 <27 です（src/shared/utils/nodeRuntimeSupport.ts の SUPPORTED_NODE_RANGE。package.json の engines フィールドと整合しています）。Node.js 24.x LTS (Krypton) および Node.js 26 は、better-sqlite3 v12.x で完全にサポートされています。

---

プロキシの問題

プロバイダー検証で「fetch failed」と表示される

原因: API キー検証エンドポイント（POST /api/providers/validate）が以前はプロキシ設定を経由していなかったため、プロキシ経由の通信が必要な環境で失敗していました。

修正（v3.5.5+）: この問題は修正済みです。プロバイダー検証は runWithProxyContext を経由するようになり、プロバイダー単位およびグローバルのプロキシ設定が自動的に適用されます。

トークンの正常性チェックが「fetch failed」で失敗する

原因: バックグラウンドでの OAuth トークン更新時に、接続ごとのプロキシ設定が解決されていませんでした。

修正（v3.5.5+）: トークンの正常性チェックスケジューラーは、更新を試行する前に接続ごとのプロキシ設定を解決するようになりました。v3.5.5+ に更新してください。

SOCKS5 プロキシで「invalid onRequestStart method」が返される

原因: Node.js 22 では、undici@8 のディスパッチャーは Node の組み込み fetch() 実装と互換性がありません。

修正（v3.5.5+）: OmniRoute は、プロキシディスパッチャーが有効な場合に undici 独自の fetch() 関数を使用するようになり、一貫した動作が保証されます。v3.5.5+ に更新してください。

WSL 環境の MITM プロキシで、Windows ホスト上のデスクトップアプリが傍受されない

原因: MITM プロキシとその CA 証明書は、OmniRoute が実行されている環境にインストールされます。WSL では、その環境は Linux ゲストですが、AI デスクトップアプリ（Kiro、Trae、Copilot、Zed、…）は Windows ホスト上で実行されます。ホストアプリはゲストの証明書ストアを信頼せず、ゲストのシステムプロキシも経由しないため、デスクトップ通信の傍受は機能しません。

推奨事項: 傍受対象のデスクトップアプリと同じ OS 上で OmniRoute をネイティブ実行してください（Windows アプリの場合は Windows、macOS/Linux の場合も同様です）。ホストアプリを対象にしながら OmniRoute を WSL 内で実行し続けるには、生成された CA 証明書を Windows ホストで手動で信頼し、各ホストアプリのネットワーク／プロキシ設定で WSL のプロキシエンドポイントを指定する必要があります。この構成はサポート対象外であり、壊れやすいものです。

---

プロバイダーの問題

「Language model did not provide messages」

原因: プロバイダーのクォータを使い切っています。

修正:

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

レート制限

原因: サブスクリプションのクォータを使い切っています。

修正:

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

OAuth トークンの有効期限切れ

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

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

Kiro の複数アカウント利用で、2 つ目のアカウントによって 1 つ目が無効になる

原因: Kiro のバックエンドでは、OIDC クライアント登録ごとに有効なセッションが 1 つに制限されています。 2 つのアカウントが同じ登録済みクライアントを共有している場合（v3.8.0 より前にインポートされた接続）、 一方のアカウントのトークンを更新すると、もう一方のリフレッシュトークンが無効になります。

修正（v3.8.0+）: 影響を受ける接続を再インポートしてください。 v3.8.0 以降、Import Token、 Google/GitHub ソーシャルログイン、または Auto-Import を使用して新しく作成された Kiro 接続には、 それぞれ専用の OIDC クライアントが自動的に登録されます。そのため、接続は完全に分離され、 一方のアカウントを更新しても他のアカウントには影響しません。

v3.8.0 より_前_にインポートされた接続には、接続ごとのクライアント登録がありません。 これらの接続では、引き続き共有のソーシャル認証更新エンドポイントが使用されます。 接続を分離するには、ダッシュボード → プロバイダーから古い接続を削除し、 3 つのインポートフローのいずれかを使用して再度追加してください。

詳細情報、および 2 つの Kiro アカウントを並行して追加するための手順については、 docs/guides/KIRO_SETUP.md を参照してください。

---

クラウドの問題

クラウド同期エラー

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 のフォールバックが含まれています。

クラウドでは接続済みと表示されるが「Invalid API key」となる

1. ローカルダッシュボード（/api/keys）から新しいキーを作成します
2. クラウド同期を実行します: Cloud を有効化 → 今すぐ同期
3. 古いキーや未同期のキーでは、クラウドで引き続き 401 が返される場合があります

---

Docker の問題

Docker の IPv6 / 接続リセット

症状: curl http://localhost:20128/v1/models が curl: (56) Recv failure: Connection reset by peer を返します。ダッシュボードと未認証エンドポイントは動作しますが、認証済みエンドポイントは失敗します。認証の問題のように見えますが、実際にはそうではありません。

原因: docker run -p 20128:20128 は 0.0.0.0（IPv4）と ::（IPv6）の両方でポートを公開しますが、コンテナ内のプロセスは IPv4 でのみリッスンしています。localhost が最初に ::1 に解決されるホストでは、接続先が IPv6 で公開されたポートになりますが、その背後にリスナーが存在しないため、接続がリセットされます。

修正方法:

1. 簡易診断: curl -4 http://localhost:20128/v1/models を実行します。-4 を指定すると動作し、指定しないと失敗する場合は、IPv6 のバインドが一致していません。
2. 恒久的な修正: docker run コマンドで -p 127.0.0.1:20128:20128 を使用し、IPv4 に明示的にバインドします:

   docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
     -p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest

   これにより IPv4 へのバインドが強制され、プロキシがホストのすべてのインターフェースで公開されることも防げます。

---

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. 重要度の低いタスクには無料枠（Qoder、Kiro）を使用します
4. API キーごとにコスト予算を設定します: ダッシュボード → API キー → 予算

---

デバッグ

ログファイルを有効にする

.env ファイルで APP_LOG_TO_FILE=true を設定します。アプリケーションログは logs/ 配下に書き込まれます。 設定で呼び出しログパイプラインが有効になっている場合、リクエストのアーティファクトは ${DATA_DIR}/call_logs/ 配下に保存されます。 パイプラインキャプチャが有効になっている場合、ストリームチャンクのペイロードを除外するには CALL_LOG_PIPELINE_CAPTURE_STREAM_CHUNKS=false を設定します。または、アーティファクトの上限（KB）を変更するには CALL_LOG_PIPELINE_MAX_SIZE_KB を調整します。

プロバイダーの正常性を確認する

# ヘルスダッシュボード
http://localhost:20128/dashboard/health

# API ヘルスチェック
curl http://localhost:20128/api/monitoring/health

ランタイムストレージ

• メイン状態: ${DATA_DIR}/storage.sqlite（プロバイダー、コンボ、エイリアス、キー、設定）
• 使用状況: storage.sqlite 内の SQLite テーブル（usage_history、call_logs、proxy_logs）+ オプションの ${DATA_DIR}/call_logs/
• アプリケーションログ: <repo>/logs/...（APP_LOG_TO_FILE=true の場合）
• 呼び出しログのアーティファクト: 呼び出しログパイプラインが有効な場合は ${DATA_DIR}/call_logs/YYYY-MM-DD/...

リクエストログページの 履歴を消去 アクションは、call_logs、従来の request_detail_logs、およびローカルの ${DATA_DIR}/call_logs/ アーティファクトディレクトリを消去します。

---

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

プロバイダーが OPEN 状態のままになる

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

解決方法：

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

プロバイダーでサーキットブレーカーが繰り返し作動する

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

1. ダッシュボード → ヘルス → プロバイダーのヘルス で障害のパターンを確認します
2. 設定 → レジリエンス → プロバイダープロファイル に移動し、障害しきい値を引き上げます
3. プロバイダーが API の制限を変更していないか、または再認証が必要でないかを確認します
4. レイテンシのテレメトリを確認します。レイテンシが高いと、タイムアウトによる障害が発生する可能性があります

---

音声文字起こしの問題

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

• 最初のセグメントが、認証情報を設定済みのプロバイダーであるモデル ID（openai/whisper-1、openrouter/deepgram/nova-3）を使用してください。単独の deepgram/nova-3 には、Deepgram ネイティブキーが必要です。
• ダッシュボード → プロバイダー で、プロバイダーが接続されていることを確認します

文字起こし結果が空になる、または失敗する

• サポートされている音声形式（mp3、wav、m4a、flac、ogg、webm）を確認します
• ファイルサイズがプロバイダーの制限内（通常は 25MB 未満）であることを確認します
• プロバイダーカードで、プロバイダーの API キーが有効であることを確認します

---

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

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

モード	使用する場面
プレイグラウンド	入出力形式を横に並べて比較します。失敗したリクエストを貼り付けて、どのように変換されるか確認します
チャットテスター	ライブメッセージを送信し、ヘッダーを含むリクエストとレスポンスの完全なペイロードを確認します
テストベンチ	形式の組み合わせに対してバッチテストを実行し、どの変換に問題があるかを特定します
ライブモニター	リアルタイムのリクエストフローを監視し、断続的な変換の問題を検出します

よくある形式の問題

• Thinking タグが表示されない — 対象プロバイダーが Thinking に対応しているか、および Thinking のバジェット設定を確認してください
• ツール呼び出しが欠落する — 一部の形式変換では、サポートされていないフィールドが削除される場合があります。プレイグラウンドモードで確認してください
• システムプロンプトが欠落する — Claude と Gemini ではシステムプロンプトの処理方法が異なります。変換後の出力を確認してください
• SDK がオブジェクトではなく生の文字列を返す — v1.x で解決済みです。レスポンスサニタイザーにより、OpenAI SDK の Pydantic 検証エラーを引き起こす非標準フィールド（x_groq、usage_breakdown など）が削除されます。v3.x+ でもこの問題が発生する場合は、Issue を報告してください。
• GLM/ERNIE が system ロールを拒否する — v1.x で解決済みです。ロールノーマライザーにより、互換性のないモデルではシステムメッセージがユーザーメッセージに自動的に統合されます。v3.x+ でもこの問題が発生する場合は、Issue を報告してください。
• developer ロールが認識されない — v1.x で解決済みです。OpenAI 以外のプロバイダーでは、自動的に system に変換されます。v3.x+ でもこの問題が発生する場合は、Issue を報告してください。
• Gemini で json_schema が機能しない — v1.x で解決済みです。response_format は Gemini の responseMimeType + responseSchema に変換されるようになりました。v3.x+ でもこの問題が発生する場合は、Issue を報告してください。

---

レジリエンス設定

自動レート制限が発動しない

• 自動レート制限は API キープロバイダーにのみ適用されます（OAuth/サブスクリプションには適用されません）
• Settings → Resilience → Provider Profiles で自動レート制限が有効になっていることを確認してください
• プロバイダーが 429 ステータスコードまたは Retry-After ヘッダーを返しているか確認してください

指数バックオフの調整

プロバイダープロファイルでは、次の設定がサポートされています。

• Base delay — 最初の失敗後の初期待機時間（デフォルト: 1s）
• Max delay — 最大待機時間の上限（デフォルト: 30s）
• Multiplier — 連続する失敗ごとに遅延をどれだけ増やすか（デフォルト: 2x）

サンダリングハード対策

多数の同時リクエストがレート制限中のプロバイダーに到達した場合、OmniRoute は mutex と自動レート制限を使用してリクエストを直列化し、連鎖的な障害を防ぎます。API キープロバイダーでは、これは自動的に行われます。

チャットリクエストが 503 / chat_admission_busy で失敗する

症状:

• チャット補完エンドポイントが、エラーコード chat_admission_busy の再試行可能な 503 レスポンスを返します。
• レスポンスには Retry-After が含まれます。#12135 以降、この値は観測された 占有状況から算出されます。具体的には、リクエストがすでに待機した OMNIROUTE_CHAT_ADMISSION_QUEUE_MS の時間枠と、現在の高負荷リースが保持されている時間のうち大きい方を、秒単位に 切り上げ、最大 60 秒に制限した値です。ゲートがアイドル状態の場合は、従来の下限値が維持されます。 バイトベースのパスでは 2 秒、構造ベースのパスでは 1 秒です（後者には reason: "structure_limit" も含まれます）。
• これは、別の高負荷チャットまたは長時間実行されるストリーミングレスポンスがまだ 処理中の場合に発生することがあります。

バイトベースのレスポンス本文は次のとおりです。

{
  "error": {
    "message": "Chat admission capacity is temporarily unavailable. Retry shortly.",
    "type": "server_error",
    "code": "chat_admission_busy"
  }
}

構造ベースのレスポンスでは、同じタイプとコードが使用され、メッセージは Local chat admission capacity is busy for this structurally heavy request; upstream provider routing was not attempted. Retry shortly. となり、reason: "structure_limit" も含まれます。 デフォルトのしきい値では、メッセージが 200 件以上、ツールが 64 個以上、 推定トークンが 32,000 以上のいずれかに該当する場合、または制限付き構造推定が 走査ノード数 10,000 または深さ 12 の上限に達した場合、リクエストは構造的に高負荷と見なされます。

原因: これは OmniRoute 内部で意図的に行われる負荷遮断であり、アップストリームプロバイダーの障害ではありません。 各プロセスはプロセスローカルなガードを使用し、大きなリクエスト本文を保持して 解析する前に、限られた高負荷処理容量を予約します。高負荷リースは、SSE レスポンスの存続期間中、保持され続けます。

#503 の連鎖: この修正以前は、ホストのメモリ容量に関係なく、ガードが固定のリクエスト数 （OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT、デフォルト 1）で同時実行数を制限していたため、コーディングエージェントの ファンアウト（複数のサブエージェント/CLI、通常 256 KB を超える本文）によって、実効同時実行数が 約 1 まで低下し、まったく正常な負荷でも 503 が発生していました。現在、ガードは自己調整されます。 プロセスの実際のメモリ上限に基づいて設定される、自動算出された取り込みバイト予算 （OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES）によって制御され、さらにリアルタイムのリソース圧迫シグナルも参照します。 そのため、複数の高負荷リクエストが同時に到着したというだけではなく、ホストが実際にメモリ不足に 陥っている場合にのみ負荷を遮断します。従来の件数上限（OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT）も 引き続き適用されますが、明示的に設定した場合に限られます。

容量が使用中の場合、高負荷リクエストは、再試行可能な 503 を返す前に、 スロットが空くまで最大 OMNIROUTE_CHAT_ADMISSION_QUEUE_MS（デフォルト 2000、0 で待機を無効化）の間、最初に待機します。 この制限付き待機により、高負荷のサブリクエストを同時にファンアウトするエージェント形式のクライアント （OpenCode、Claude Code、Cursor）が、即時拒否によって再試行枠をすべて使い果たしてタスクの途中で停止するのではなく、 バーストを直列化できるようになります。 現在の高負荷リース占有状況、確定したバイト予算、およびリアルタイムの圧迫度は、 GET /api/monitoring/health → chatAdmission（inflightBytes、maxInflightBytes、 budgetSource、pressureSeverity、countCapEnabled）で確認できます。環境変数を変更する前に、これらを確認してください。 Settings → Resilience → Request Queue → Concurrent Requests はこれを制御しません。この設定は、 別のプロバイダーリクエストキュー機構を制御します。

修正方法:

1. まず再試行してください。クライアントはリクエストを即座に繰り返すのではなく、 Retry-After に従い、バックオフを使用する必要があります。
2. 何かを調整する前に、/api/monitoring/health → chatAdmission を確認してください。countCapEnabled: false かつ maxInflightBytes が十分に大きい場合、自動算出された予算はすでに適切に 機能しています。pressureSeverity が high/critical の場合、ホストは実際にメモリ不足です。 これはアドミッション関連の環境変数では修正できず、RAM の増設またはワークロードの縮小が必要です。
3. /api/monitoring/health によって、自動算出された予算がホストに対して本当に小さすぎることが 示された場合にのみ（これはまれです。コンテナからベアメタルまで、すでに自動でスケーリングされます）、 従来のリクエスト件数上限に戻すのではなく、OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES で直接上書きしてください。

正式なアドミッション設定については、環境変数リファレンス を参照してください。

---

オプションの RAG / LLM 障害分類（16 の問題）

一部の OmniRoute ユーザーは、RAG またはエージェントスタックの前段にゲートウェイを配置しています。このような構成では、奇妙なパターンがよく見られます。OmniRoute は正常に見える（プロバイダーは稼働中、ルーティングプロファイルは正常、レート制限アラートもなし）にもかかわらず、最終的な回答が間違っているというものです。

実際には、こうしたインシデントは通常、ゲートウェイ自体ではなく、後段の RAG パイプラインに起因します。

これらの障害を説明するための共通用語が必要な場合は、WFGY ProblemMap を利用できます。これは、繰り返し発生する 16 種類の RAG / LLM 障害パターンを定義した、MIT ライセンスの外部テキストリソースです。概要として、以下を扱っています。

• 検索のドリフトとコンテキスト境界の破綻
• 空または古くなったインデックスとベクトルストア
• 埋め込みとセマンティクスの不一致
• プロンプト構築とコンテキストウィンドウの問題
• 論理の崩壊と過度に確信的な回答
• 長いチェーンとエージェント連携の障害
• マルチエージェントのメモリと役割のドリフト
• デプロイとブートストラップの順序に関する問題

考え方はシンプルです。

1. 不適切な応答を調査する際は、以下を記録します。
   • ユーザーのタスクとリクエスト
   • OmniRoute で使用したルートまたはプロバイダーの組み合わせ
   • 後段で使用された RAG コンテキスト（取得したドキュメント、ツール呼び出しなど）
2. インシデントを 1 つまたは 2 つの WFGY ProblemMap 番号（No.1 … No.16）に対応付けます。
3. OmniRoute のログと併せて、自社のダッシュボード、ランブック、またはインシデントトラッカーにその番号を保存します。
4. 対応する WFGY ページを使用して、RAG スタック、リトリーバー、またはルーティング戦略のどれを変更する必要があるかを判断します。

全文と具体的な手順はこちらにあります（MIT ライセンス、テキストのみ）。

WFGY ProblemMap README

OmniRoute の後段で RAG またはエージェントパイプラインを実行していない場合は、このセクションを無視して構いません。

---

v3.8.0 の既知の問題

v3.8.0 リリース固有の問題と、現在の回避策です。修正が後続のパッチに含まれた場合、この項目は更新または削除されます。

Devin CLI の認証失敗

症状：

• Devin を利用するツールの呼び出し時に「Devin CLI not found」または「auth failed」と表示される
• CLI ランタイムチェックで installed=false と報告される

原因：

• CLI_DEVIN_BIN が存在しないパスを指している
• ホストに Devin CLI がインストールされていない

修正方法：

1. お使いのプラットフォーム用の Devin CLI をインストールします
2. .env で CLI_DEVIN_BIN=/usr/local/bin/devin（または実際のパス）を設定します
3. OmniRoute を再起動し、ダッシュボード → CLI ツールから再テストします

モデルのクールダウンが解除されない（手動リセット）

症状：

• 有効期限を過ぎても、モデルがクールダウン中として表示され続ける
• タイムスタンプが過去になっているにもかかわらず、組み合わせルーティングで引き続きそのモデルがスキップされる

手動リセット：

• ダッシュボード： 設定 → モデルのクールダウン → 影響を受けているカードの 再有効化 をクリックします
• API： 管理認証ヘッダーを付けて DELETE /api/resilience/model-cooldowns を実行します

Command Code プロバイダーへの接続が 403 で失敗する

症状：

• Command Code プロバイダーへの接続テスト時に 403 が発生する
• 新規追加後、プロバイダーカードに「unauthorized」と表示される

原因： OAuth フローが完了していません（コールバックが受信されなかったか、トークンが永続化されませんでした）。

修正方法：

• CLI から omniroute providers を実行して OAuth フローを再度開始するか、
• ダッシュボード → プロバイダー → Command Code → 再接続から OAuth を再実行します

ModelScope で過度な 429 クールダウンが返される

症状：

• 少量のリクエストを短時間に送信しただけで、ModelScope に非常に短い、または即時のクールダウンが発生する
• 組み合わせルーティングで、想定より早く ModelScope がスキップされる

原因： ModelScope はプロバイダー固有の Retry-After ヘッダーを返します。v3.8.0 ではこれらのヘッダー専用の処理が導入されているため、それ以前のバージョンでは汎用的なレート制限のヒントとして誤って解釈されます。

修正方法：

• v3.8.0 以降を使用していることを確認します
• 設定 → レジリエンスで useUpstream429BreakerHints トグルが有効になっていることを確認します

本番環境で OMNIROUTE_WS_BRIDGE_SECRET が設定されていない

症状：

• リモートの本番ホストで実行している場合、Codex/Responses WebSocket ブリッジへのすべてのリクエストで 401 が発生する
• 接続直後に WebSocket ブリッジのハンドシェイクが終了する

原因： 本番環境に OMNIROUTE_WS_BRIDGE_SECRET 環境変数が設定されていません。

修正方法：

1. ランダムなシークレットを生成します：openssl rand -hex 32
2. 本番サーバーの環境（およびブリッジと通信するすべてのクライアント）に OMNIROUTE_WS_BRIDGE_SECRET=<random-secret> を設定します
3. OmniRoute を再起動します

Responses API：バックグラウンドモードが同期実行に縮退する

症状：

• 次の警告がログに記録される：background mode degraded to synchronous
• background: true を指定したリクエストが、バックグラウンドジョブのハンドルではなく、通常の同期レスポンスを返す

原因： v3.8.0 では、Responses API の background: true は意図的に同期実行へ縮退し、その際に警告が出力されます。完全な非同期バックグラウンド実行は、今後提供される予定です。

修正方法：

• background を指定せずに呼び出すようクライアントを調整するか、
• 完全な非同期バックグラウンドモードが提供される後続リリースを待ちます（変更履歴を確認してください）

---

起動の遅延 / 準備完了タイムアウト

CLI に ⚠ Server did not respond within 60s と表示されてもサーバーが実際には動作している場合、お使いの環境に対して準備完了プローブの待機時間が短すぎます。

これは、Windows（ウイルス対策ソフト、ファイルシステム監視）や、起動時の負荷が高いコンテナでよく発生します。

解決策 — 待機時間を延長する：

# 環境変数を使用（再起動後も維持）：
export OMNIROUTE_READY_TIMEOUT_MS=180000   # 3 分
omniroute serve

# CLI フラグを使用（今回のみ）：
omniroute serve --ready-timeout 180000

デフォルトは 60 000 ms（60 秒）です。この警告は情報提供のみを目的としており、サーバーはバックグラウンドで起動を続け、起動が完了するとアクセス可能になります。

OMNIROUTE_READY_TIMEOUT_MS の詳細については、docs/reference/ENVIRONMENT.mdを参照してください。

---

まだ解決しない場合

• GitHub Issues: github.com/diegosouzapw/OmniRoute/issues
• アーキテクチャ: 内部の詳細については、docs/architecture/ARCHITECTURE.mdを参照してください
• API リファレンス: すべてのエンドポイントについては、docs/reference/API_REFERENCE.mdを参照してください
• ヘルスダッシュボード: システムのリアルタイムステータスを確認するには、Dashboard → Health を開いてください
• トランスレーター: フォーマットの問題をデバッグするには、Dashboard → Translator を使用してください

---

OmniRoute ソースコード (a58000c7685f)