メインコンテンツへ移動
AIチュートリアル

My Free Codeでマルチプロバイダー対応のコーディングエージェントゲートウェイを構築

My Free Code v0.8のインストール方法、プロバイダー接続型またはローカルモデルの設定、コーディングエージェントの接続、ティア別ルーティングと順序付きフォールバックの管理、管理UIの確認方法、ローカル利用時のゲートウェイのセキュリティ確保について解説します。

約16分で読了
My Free Codeでマルチプロバイダー対応のコーディングエージェントゲートウェイを構築

無料コードでできること

My Free Code v0.8は、Claude Codeやその他のコーディングエージェントに対応する、独立したマルチプロバイダーゲートウェイです。エージェントからのリクエストを受け付け、設定されたモデルを選択し、該当するプロバイダー向けにリクエストを変換して、レスポンスをクライアントへストリーミングするローカルFastAPIゲートウェイとして動作します。本プロジェクトはAnthropicとは提携していません。

ゲートウェイは、/v1/messagesのAnthropic Messagesプロトコル、/v1/messages/count_tokensのAnthropicトークンカウント、/v1/responsesのOpenAI Responses互換エンドポイントに対応しています。また、/v1/modelsによるモデル検出、/healthのヘルスエンドポイント、/adminのローカル管理UI、/api/admin/*配下の認証済み管理APIも提供します。

主な機能

  • 複数のエージェントプロトコル: 1つのゲートウェイでAnthropic MessagesとOpenAI Responses互換のリクエストを受け付けます。
  • エージェント機能: ストリーミングServer-Sent Events、ツール定義、ツール呼び出し、ツール結果、画像、推論メタデータのパススルーに対応します。
  • Claudeティアのルーティング: Fable、Opus、Sonnet、Haikuのリクエストに異なる上流モデルを割り当てます。
  • 堅牢なルーティング: モデルの優先フォールバック、プロバイダーのヘルスバックオフ、プロバイダーごとの同時実行制御、レートウィンドウ制御を使用します。
  • 安定したモデル識別子: ルーターがリクエストを別のプロバイダーへ送信する場合でも、ゲートウェイの公開モデル識別子を維持します。
  • 推論の正規化: Claude形式の思考意図を、プロバイダー固有のリクエストフィールドから分離して保持します。
  • ローカルモデル対応: OpenAI互換エンドポイントを介して、Ollama、LM Studio、llama.cppに接続できます。
  • エージェントランチャー: Claude Code、Codex、Pi、OpenCode、Cline、Hermes、DeepSeek Harness、Grok Build、Muse Code向けにプロキシ環境を準備します。

プロバイダーカタログには、さまざまなクラウドサービスとローカルランタイムが含まれています。一般的なOpenAI互換プロバイダーは共通トランスポートを使用しますが、認証方式やプロトコルが特殊なプロバイダーには専用アダプターが必要です。したがって、プロバイダー固有の設定なしに、カタログの項目を普遍的な対応を保証するものと解釈しないでください。

アーキテクチャの仕組み

             Coding Agents / IDEs
                      |
          +-----------+-----------+
          |                       |
    Anthropic Messages       OpenAI Responses
          |                       |
          +-----------+-----------+
                      |
                FastAPI Gateway
                      |
                Model Router
                      |
          +-----------+-----------+
          |                       |
       Primary                  Fallbacks
          |                       |
          +-----------+-----------+
                      |
              Provider Runtime
                      |
       +--------------+--------------+
       |              |              |
 OpenAI-compatible  Specialized   Local
     adapter          adapter     runtime
       |              |              |
     APIs          provider API  Ollama/LM Studio

この設計では、受信する通信プロトコル、ルーティング、プロバイダー統合を分離しています。HTTPアダプターがリクエストを受信し、アプリケーション層がルートを選択して実行し、プロバイダーランタイムが共通のOpenAI互換トランスポート、専用アダプター、またはローカルランタイムと通信します。CLIランチャーは独立した層として、クライアント環境を設定し、インストール済みのコーディングエージェントへ実行を委譲します。

ゲートウェイをインストールする

前提条件

  • Python 3.10以降。
  • リポジトリのローカルコピー。
  • 使用するリモートプロバイダーの認証情報。
  • 起動するコーディングエージェントのクライアントがインストールされ、PATHから利用できること。

1. 仮想環境を作成する

python -m venv .venv

2. 仮想環境を有効化して依存関係をインストールする

Windows PowerShellでは、次を実行します。

.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
copy .env.example .env

macOSまたはLinuxでは、次を実行します。

source .venv/bin/activate
python -m pip install -r requirements.txt
cp .env.example .env

3. My Free Codeを起動する

python -m my_free_code

デフォルトでは、ゲートウェイはhttp://127.0.0.1:8082で利用できます。http://127.0.0.1:8082/healthでサービスを確認し、http://127.0.0.1:8082/adminでローカル管理UIを開けます。

モデルとプロバイダーを設定する

生成された.envファイルを編集して、デフォルトモデルの選択、Claudeティアへのモデル割り当て、優先フォールバックの定義を行います。次の例では、複数のプロバイダーのモデルを使用しています。

MODEL=open_router/openrouter/free
MODEL_SONNET=deepseek/deepseek-chat
MODEL_HAIKU=groq/llama-3.3-70b-versatile
MODEL_OPUS=nvidia_nim/meta/llama-3.3-70b-instruct
FALLBACK_MODELS=deepseek/deepseek-chat,ollama/llama3.1

対応するプロバイダーのAPIキーを.envに追加します。対応する設定フィールドについては.env.exampleを参考にしてください。環境変数を変更した後は、ゲートウェイを再起動します。

MODELは、ゲートウェイ全体で使用するモデルを選択します。MODEL_SONNET、MODEL_HAIKU、MODEL_OPUSなどのティア固有の変数を使うと、ルーターはClaudeのモデルティアごとに異なる上流サービスへ振り分けられます。FALLBACK_MODELSは、カンマ区切りで指定する優先順付きの代替モデル一覧です。

Claude Codeを接続する

オプション1: 環境変数を手動で設定する

Windows PowerShellで、Claude Codeの接続先をローカルのAnthropic互換ゲートウェイに設定します。

$env:ANTHROPIC_BASE_URL="http://127.0.0.1:8082"
$env:ANTHROPIC_AUTH_TOKEN="local"
$env:CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"
claude

ベースURLはClaude CodeのリクエストをMy Free Codeへリダイレクトし、モデルディスカバリーによってクライアントはゲートウェイのモデルカタログを照会できます。

オプション2：ランチャーアダプターを使用する

python -m my_free_code.cli.mfc claude

ランチャーはローカルプロキシ環境を準備し、インストール済みのClaude Codeクライアントに引数を渡します。クライアント自体のインストールは行いません。

他のコーディングエージェントを起動する

同じランチャー抽象化で、複数の追加クライアントをサポートしています。

python -m my_free_code.cli.mfc codex
python -m my_free_code.cli.mfc pi
python -m my_free_code.cli.mfc opencode
python -m my_free_code.cli.mfc cline
python -m my_free_code.cli.mfc hermes
python -m my_free_code.cli.mfc deepseek-harness
python -m my_free_code.cli.mfc grok
python -m my_free_code.cli.mfc muse

これらのコマンドを実行する前に、対応するクライアントがインストールされ、PATHから利用できることを確認してください。ランチャーはゲートウェイ環境を設定し、既存のプログラムを呼び出すだけです。

順序付きフォールバックを理解する

環境に次のルーティング設定が含まれているとします。

MODEL_SONNET=deepseek/deepseek-chat
FALLBACK_MODELS=groq/llama-3.3-70b-versatile,ollama/llama3.1

Sonnetリクエストはまずdeepseek/deepseek-chatに送られます。出力を生成する前にその試行が失敗すると、ルーターはgroq/llama-3.3-70b-versatileを試します。2回目の試行も出力前に失敗した場合は、ollama/llama3.1を試します。

Claude Code
    |
    v
deepseek/deepseek-chat
    |
    | output前に失敗
    v
groq/llama-3.3-70b-versatile
    |
    | output前に失敗
    v
ollama/llama3.1

ストリーミングレスポンスが出力を確定した後、ゲートウェイがプロバイダーをひそかに切り替えることはありません。これにより、ターンの重複や、異なるモデルからの部分レスポンスの結合を防ぎます。

ローカルモデルを使用する

Ollama

Ollamaサービスを別途起動し、OpenAI互換のベースURLとモデルを設定します。

OLLAMA_BASE_URL=http://127.0.0.1:11434/v1
MODEL=ollama/llama3.1

LM Studio

LM Studioのローカルサーバーを起動し、次を使用します。

LM_STUDIO_BASE_URL=http://127.0.0.1:1234/v1
MODEL=lmstudio/qwen3.5-coder

llama.cpp

llama.cppサーバーを実行し、次を設定します。

LLAMACPP_BASE_URL=http://127.0.0.1:8080/v1
MODEL=llamacpp/my-model

ローカルランタイムはFALLBACK_MODELSにも指定できます。これにより、リモートリクエストが出力を生成する前に失敗した場合に、ローカルモデルを代替として使用できます。

推論動作を設定する

ゲートウェイはClaude形式の思考インテントを受け付け、プロバイダーアダプターがリクエストを変換する前に正規化します。サポートされるモードは次のとおりです。

auto
on
off

任意で推論の強度も指定できます。

low
medium
high

この分離により、エージェント側の推論ポリシーをプロバイダー固有のフィールドから独立させられます。各プロバイダーアダプターは、正規化されたモードと強度を、接続先プロバイダーが文書化しているフィールドにマッピングできます。

ゲートウェイを監視する

ローカルでAdmin UIを次のURLから開きます。

http://127.0.0.1:8082/admin

認証済みのJSON Admin APIには次のエンドポイントがあります。

GET /api/admin/status
GET /api/admin/models
GET /api/admin/providers

これらのエンドポイントを使用して、ゲートウェイの状態、モデルカタログ、設定済みプロバイダーを確認します。管理用エンドポイントには認証が必要であり、非公開のままにしてください。

高度なヒント

公開モデルIDを安定させる

リクエストは階層別モデルやフォールバックプロバイダーにルーティングされる場合がありますが、ゲートウェイは公開モデルIDを維持します。そのため、クライアントアプリケーションは、すべての接続先のルーティング判断を追跡せずにゲートウェイモデルとやり取りできます。

フォールバック順を意図的に設計する

FALLBACK_MODELSには、試行する正確な順序でモデルを記述します。プロバイダーの可用性と、ローカルランタイムを最後の選択肢にするかどうかを検討してください。フォールバックが発生するのは、ストリーミング出力が確定する前だけです。

プロバイダーの違いを考慮する

多くのプロバイダーは共通のOpenAI互換トランスポートを使用しますが、特殊な認証方式やプロトコルには専用アダプターが必要です。すべてのカタログエントリが同じように動作すると想定せず、該当するプロバイダーアダプターと認証情報が利用可能であることを確認してください。

必要に応じてプロトコルエンドポイントを直接使用する

  • Anthropic Messagesリクエストを/v1/messagesに送信します。
  • /v1/messages/count_tokensでAnthropic形式のトークン数を数えます。
  • /v1/responsesでOpenAI Responses互換インターフェースを使用します。
  • /v1/modelsでモデルを検出します。
  • /healthでサービスの健全性を確認します。

テストスイートを実行する

pytest -q

リポジトリには、ルーティング、プロトコル変換、認証、推論、モデルカタログ、ストリーミングの基本機能に関する決定論的なテストが含まれています。ゲートウェイ、ルーティング、プロバイダーのコードを変更した後に実行してください。

セキュリティガイドライン

My Free Codeはローカル利用を想定しています。次の予防策を適用してください。

  • サービスがローカルマシンにバインドされるよう、HOST=127.0.0.1を維持します。
  • 推測されにくいPROXY_AUTH_TOKENを設定します。
  • .envファイルをソース管理に決してコミットしません。
  • Adminエンドポイントをインターネットに直接公開しません。
  • プロバイダーの認証情報は環境変数または設定に保持します。ゲートウェイがあるプロバイダーの認証情報を別のプロバイダーに送信することはありません。

まとめ

My Free Codeは、コーディングエージェントと複数のクラウドまたはローカルモデルプロバイダーの間をつなぐ、ローカルの互換性およびルーティングレイヤーを提供します。Python依存関係をインストールし、モデルと認証情報を設定してゲートウェイを起動すると、Claude Codeなどの対応クライアントを接続し、Claudeのティアごとにモデルを割り当て、制御されたフォールバックチェーンを構築できます。プロトコル、ルーティング、プロバイダー、ランチャーの各レイヤーが分離されているため、プロジェクトの確認やテストも容易です。