OmniRoute のインストール:クイックスタートと Claude Code 設定

OmniRoute は OpenAI 互換の AI ゲートウェイです。複数の上流モデルプロバイダーを 1 つのローカル API の背後にまとめるので、Claude Code、Codex CLI、IDE 拡張、自作スクリプトの設定は一度で済みます。このページはインストールから最初のリクエスト成功までの最短ルートです。トピック別の詳しいガイドは専用サイトで管理しています。

この 2 つのアドレスを覚えておく

ダッシュボード:http://localhost:20128
OpenAI 互換の Base URL:http://localhost:20128/v1

クライアントに設定するのはダッシュボードのアドレスではなく、2 つ目のほうです。

前提条件

Node.js >=22.22.2 <23 または >=24.0.0 <27。Node.js 24 LTS を推奨します。この範囲外だとダッシュボードが真っ白になったり、ネイティブモジュールのエラーが出たりすることがあります。必要なら先に Node.js をインストールしてください。
ローカルのポート 20128 が空いていること。
OmniRoute 経由でルーティングする予定の上流プロバイダーのアカウントまたはキーが 1 つ以上あること。

インストールと起動

方法を 1 つ選びます。

# npm(推奨)
npm install -g omniroute
omniroute

# Docker
docker run -d --name omniroute -p 20128:20128 diegosouzapw/omniroute:latest

OmniRoute GitHub Releases から Windows、macOS、Linux 向けの Desktop インストーラーをダウンロードすることもできます。:latest は最新の公開済み安定版を指します。再現性のあるデプロイが必要な場合は、バージョンを固定してください。

起動したら http://localhost:20128 を開きます。ログインパスワードは環境変数 INITIAL_PASSWORD で決まります。上流のセルフホスト構成では初回起動時に生成されてログに出力され、Docker なら docker logs omniroute | grep -i password で確認できます。サービスをネットワークに公開する前に、必ず自分で決めた強力なパスワードに設定してください。

プロバイダーの接続とキーの作成

ダッシュボードで Providers → Add Provider を開き、プロバイダーを接続します。
API Keys ページで新しいキーを作成して保管します。表示されるのは一度だけです。このキーはクライアントが OmniRoute にアクセスするためのもので、上流プロバイダーのキーではありません。

上流のドキュメントには、キー不要の無料プロバイダーも載っています。提供状況や利用条件は変わるため、使う前に各サービスの規約を自分で確認してください。

サービスの確認

export OMNIROUTE_API_KEY="API Keys ページで作成したキーを貼り付ける"

curl http://localhost:20128/v1/models \
  -H "Authorization: Bearer ${OMNIROUTE_API_KEY}"

モデル一覧が返れば、OpenAI 互換エンドポイントと認証はどちらも正常です。続けて最小のチャットリクエストを送り、モデルが実際にルーティングされることを確認します。

curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer ${OMNIROUTE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{ "role": "user", "content": "Reply with ok." }]
  }'

auto を指定すると、OmniRoute が速度・コスト・可用性に基づいてプロバイダーを選びます。/v1/models が返した具体的なモデル ID を指定することもできます。

ツールを接続する

OpenAI 形式に対応したツールなら、次のように入力します。

Base URL: http://localhost:20128/v1
API Key:  作成した OmniRoute のキー
Model:    auto

OmniRoute には 1 コマンドで起動するランチャーもあります。たとえば omniroute launch-codex --model auto があり、汎用形式の omniroute run <target> は claude、codex、aider、goose、opencode、qwen、gemini に対応しています。HagiCode で Agent CLI を使う場合は、先に AI Agent CLI のインストールを済ませてください。

よくある問題

ダッシュボードが真っ白、または未対応の Node.js バージョンという警告が出る:Node.js 24 LTS に切り替え、npm install -g omniroute をもう一度実行してから omniroute を実行してください。
npm 11 で better-sqlite3 が見つからない:npm 11 は既定でオプション依存のインストールスクリプトをブロックします。トラブルシューティングガイドの手順に従って手動で再ビルドしてください。
macOS で slice is not valid mach-o file と出る:$(npm root -g)/omniroute/app で npm rebuild better-sqlite3 を実行してから、もう一度起動してください。