株式会社ホコサキ

OmniRouteをDocker Composeでセルフホストしてクォータ問題を構造的に解決する

天京祐輔
天京祐輔
OmniRouteをDocker Composeでセルフホストしてクォータ問題を構造的に解決する

Claude Codeをヘビーに使っていると、ある日請求額を見てギョッとする瞬間がやってきます。
Morph社の試算によれば、典型的な1セッションのコストは約$0.34（45Kインプット・13Kアウトプット・38Kキャッシュリードトークン）です。
50セッション/日を超えると月$5,600を超えることがあり、20人チームが同じペースで動けば月$10,200超という数字にもなります。

コスト以外に、レート制限の壁もあります。
Claudeのクォータに引っかかった瞬間、作業が止まります。
単一プロバイダーへの依存がアーキテクチャに焼き付いている以上、ツールを使いながらこれを回避するのは構造的に難しい。

そこで選択肢として出てくるのが OmniRoute です。
MITライセンスのセルフホストLLMゲートウェイで、Docker Composeで立ち上げてエンドポイントを差し替えるだけで、コストとクォータ問題の両方に正面から対処できます。
RTK+Caveman圧縮・自動フォールバックの仕組みと実運用で気をつけることも、あわせて整理します。

Claude Codeのコストとレート制限、「ツール側を直す」アプローチの限界

この状況に直面したとき、最初に思いつくのは「ツール側を改造して複数プロバイダーに対応させる」アプローチです。
aisuiteやLangChainのような抽象レイヤーを挟んで、コードの中でプロバイダーを切り替えられるようにする方法がこれにあたります。
アプリケーションコードを自分で書いているなら有効な選択肢ですが、Claude Codeのような既製のエージェントツールはソースを直接書き換えることが難しいか、改修コストが見合わないかのどちらかです。

OmniRouteはこの発想を逆転させます。
ツールのコードには一切手を入れず、 エンドポイントだけを差し替える という設計です。
ローカルに立ち上げたOmniRouteがAnthropicと同じインターフェースを提供するため、Claude Codeからは「いつもと同じAnthropicのエンドポイント」に見えます。
その裏でプロバイダーのルーティング・圧縮・フォールバックをOmniRouteが肩代わりします。

MITライセンスのセルフホスト型ゲートウェイで、350以上のプロバイダー（うち150以上が無料）と1,200以上のモデルに対応しています。
OpenRouterのような中間業者を挟まないため、中間手数料が発生しないのも特徴です。

Docker ComposeでOmniRouteをセルフホストする

前提環境はNode ≥22.22.2とDocker Composeです。
起動に必要な環境変数は3つあります。
まずシークレットを生成します。

openssl rand -base64 48   # JWT_SECRET 用
openssl rand -hex 32      # API_KEY_SECRET 用

生成した値を、docker-compose.ymlと同じディレクトリの.envファイルに書きます。

JWT_SECRET=ここに openssl rand -base64 48 の出力を貼る
API_KEY_SECRET=ここに openssl rand -hex 32 の出力を貼る
INITIAL_PASSWORD=任意の初期パスワード

docker-compose.ymlはこの構成を起点にします。

services:
  omniroute:
    image: ghcr.io/diegosouzapw/omniroute:latest
    ports:
      - "20128:20128"
    volumes:
      - ./data:/root/.omniroute
    environment:
      JWT_SECRET: ${JWT_SECRET}
      API_KEY_SECRET: ${API_KEY_SECRET}
      INITIAL_PASSWORD: ${INITIAL_PASSWORD}
    restart: unless-stopped
    stop_grace_period: 40s

stop_grace_period を40秒に設定しているのは、SQLite WALモードのチェックポイント完了を待つためです。
OmniRouteはデータをstorage.sqliteに書き込んでいて、docker stopのシグナルが来たタイミングでチェックポイントが終わっていないとストレージが壊れる可能性があります。
公式のCompose設定にはすでに含まれていますが、docker runで直接起動する場合は --stop-timeout 40 を明示的に付ける必要があります。

./dataのボリュームマウントは、SQLiteのデータと設定を永続化するためのものです。
コンテナを再作成しても設定が消えないよう、必ずホスト側のディレクトリを指定します。

今回はghcr.ioのプレビルドイメージを利用するため、起動コマンドに --build フラグは不要です。

docker compose --profile base up -d

baseプロファイルはプロバイダーCLIを同梱しない最小構成です。
Claude CodeやCodexなどのCLIをコンテナ内で動かしたい場合はcliプロファイルを使いますが、Webダッシュボードのみを使う用途であればbaseで十分です。
起動後、ブラウザでlocalhost:20128を開くと管理ダッシュボードにアクセスできます。

Claude Codeのエンドポイントを差し替えて動作確認する

まずOmniRoute側でAnthropicのAPIキーをダッシュボードから登録し、ルーティング設定を入れます。
ログインパスワードは.envの INITIAL_PASSWORD で設定した値です。
設定が完了すると、OmniRoute発行のAPIキーが手に入ります。

次はClaude Code側の設定です。
Claude CodeはAnthropicのSDKを内部で使っており、ベースURLを環境変数で上書きできる仕組みを持っています。
AnthropicのSDKが参照するベースURL変数（ ANTHROPIC_BASE_URL ）にOmniRouteのアドレスを設定し、APIキーをOmniRoute発行のものに差し替えます。

export ANTHROPIC_BASE_URL=http://localhost:20128
export ANTHROPIC_API_KEY=<OmniRouteが発行したAPIキー>

ANTHROPIC_API_KEY をOmniRoute発行のキーに差し替えるのがポイントです。
AnthropicのオリジナルAPIキーはOmniRoute側のダッシュボードに登録済みなので、Claude Codeからは参照させません。

疎通確認はcurlで手早くできます。

curl http://localhost:20128/v1/messages \
  -H "Authorization: Bearer <OmniRoute発行のAPIキー>" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "hi"}]
  }'

レスポンスが返ってきたら、ダッシュボードのログ画面にリクエストのエントリが流れているはずです。
ここを確認できれば、Claude Codeからの実際のリクエストも同じ経路を通ります。

CursorやClineも同じ要領で対応できます。
各ツールが参照するエンドポイント設定をlocalhost:20128に向けるだけで、あとはOmniRouteが受け取ります。

RTK+Caveman圧縮と自動フォールバックが実際に何をしているか

OmniRouteには2つの目玉機能があります。
RTK+Caveman圧縮 と クォータ対応の自動フォールバック です。

RTK+Cavemanは、プロンプトのトークン列を圧縮してAPIに送るサイズを削減する仕組みです。
公式には「15〜95%のトークン削減」という幅広い数字が出ていますが、この幅には前提があります。
コードの差分が少ない反復的なセッション、つまり「同じファイルを何度も参照しながら少しずつ修正する」ような使い方では効果が大きく出ます。
逆に、初回の長いコンテキスト構築や初めてプロジェクトを読み込むフェーズでは、繰り返しパターンが少ないため恩恵が薄くなります。
「毎回50%減る」と期待すると実態と乖離しやすいので、自分のセッションパターンで実測してから判断するのが正直なところです。

自動フォールバックは、クォータ超過やエラー発生時に次のプロバイダーへ自動で切り替える機能です。
350以上のプロバイダーが対象で、ClaudeがレートリミットにかかったタイミングでGeminiやDeepSeekに切り替わるようなイメージです。

フォールバックが実際に動いているかは、意図的にエラーを誘発して確認するのが手っ取り早いです。
ダッシュボードで確認したいポイントはこの辺りです。

  • リクエストログにプロバイダー切り替えのエントリが記録されているか
  • フォールバック先のモデル名が想定通りのものになっているか
  • エラー後のリトライが正常に完了しているか
  • レスポンスタイムに異常な遅延が発生していないか

ひとつ現実的なトレードオフにも触れておきます。
フォールバック先が無料プロバイダーになった場合、モデルの性能は本番で使っているClaudeとは異なります。
「止まらない」と「品質が維持される」は別の話なので、フォールバック先のモデルを意識して設定しておくのが無難です。

本番運用で押さえておきたいこと

セルフホストである以上、インフラの責任は自分たちに乗ってきます。

一番気をつけたいのは APIキーの扱い です。
.envに書くJWT_SECRET・API_KEY_SECRET・各プロバイダーのAPIキーは、コンテナの外に置いてGitには絶対に入れないのが前提です。
個人開発や単一サーバーであれば.envでの管理で十分ですが、チーム運用やマルチホスト構成になってきたらDocker Secretsやクラウドのシークレットマネージャーへの移行を検討します。
判断の目安は「何人の開発者がキーにアクセスできる状態になっているか」です。
平文の.envで説明がつかなくなってきたら、そのタイミングが移行のサインです。

ログと外部公開については、ダッシュボード上でリクエスト単位の履歴を確認できます。
DatadogやGrafana Lokiなど外部の基盤に流したい場合は、サイドカーコンテナでログドライバーを設定するのが一般的なアプローチです。
外部に公開する場合は、nginxやCaddyでTLSを終端してから20128番ポートに流す構成が必須です。
チームメンバーがVPN外からアクセスするシナリオでは、最初からTLS構成にしておくほうが後からの改修がなくて済みます。

MITライセンスゆえのサポート体制については正直に書いておきます。
商用SLAは存在しません。
バグや障害時の窓口はコミュニティのIssueトラッカーで、550人超のコントリビューターが活発に動いていますが、ビジネスクリティカルな用途で何かあっても誰も補償してくれません。
OmniRoute自体が落ちたときに直接Anthropicへ切り替えられる手順を別途用意しておくのが現実的な備えです。
OSSに頼るのはいいけど、障害時の逃げ道はセルフで用意する、というのが付き合い方の基本です。

株式会社ホコサキは山口県宇部市を拠点に、Web制作・業務システム開発・AI活用支援を手がけています。
OmniRouteのようなセルフホストゲートウェイの導入支援や、開発フローへのAI組み込みについてはお気軽にご相談ください。
お問い合わせは こちら からどうぞ。