OpenCode OpenAI互換プロバイダーのセットアップ：Flatkey経由でコーディングエージェントモデルをルーティング

OpenCode OpenAI互換プロバイダーのセットアップは、チームがキーの所有権、モデルのルーティング、使用状況のレビューを1つのゲートウェイで管理しながら、OpenCodeがOpenAI Chat Completions APIのように動作するモデルルートと通信させたい場合に便利です。

重要な点は、OpenCodeには文書化されたカスタムプロバイダーパスがあることです。2026年7月8日に確認されたOpenCodeプロバイダーのドキュメントによると、フローは次のとおりです：/connectで認証情報を追加し、まだリストされていないプロバイダーに対してその他を選択し、そのプロバイダーに覚えやすいIDを付け、opencode.jsonでプロバイダーを設定し、その後/modelsを実行して設定済みのモデルから選択します。

Flatkeyは、そのプロバイダーの背後にあるゲートウェイとして、このパターンに適合します。OpenCodeをコーディングエージェントとして維持し、プロバイダーをFlatkeyのOpenAI互換APIベースURLに向け、デフォルトルートにする前にOpenCodeモデルのトラフィックがFlatkeyの使用状況またはリクエストログに表示されることを確認します。

OpenCode OpenAI互換プロバイダーセットアップのクイックアンサー

モデルエンドポイントがChat Completions互換である場合は、このセットアップ形式を使用してください。

このOpenCode OpenAI互換プロバイダーガイドでは、テンプレートを使用しています。本番のコーディングエージェントの作業をルーティングする前に、Flatkeyアカウントに対して正確なモデルエイリアスとエンドポイントファミリーを検証してください。

OpenCodeの要件

OpenCodeには、カスタムプロバイダー用に2つの独立した状態があります。

OpenCodeの設定はJSONまたはJSONCにすることができます。グローバルに~/.config/opencode/opencode.jsonに配置するか、プロジェクトのルートにopencode.jsonとして配置できます。プロジェクトの設定が標準的な優先順位が高いため、すべてのOpenCodeワークスペースを変更せずに1つのリポジトリでFlatkeyをテストしたい場合は、プロジェクトファイルを使用してください。

ステップ1：OpenCode用のFlatkeyキーを作成する

このワークロード用にFlatkeyキーを作成し、3つの値をソース管理外に記録します。

FLATKEY_API_KEY=sk-fk-your-key
FLATKEY_BASE_URL=https://router.flatkey.ai/v1
FLATKEY_MODEL=your-current-flatkey-model-alias

APIルートはエンドポイントパスとは別にしてください。OpenCodeプロバイダーの設定では、options.baseURLとしてhttps://router.flatkey.ai/v1を使用する必要があります。直接的なHTTPスモークテストでは/chat/completionsを追加します。

OpenCodeを接続する前に、同じFlatkeyキーとモデルエイリアスに対して直接テストを実行します。

curl "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "messages": [
      { "role": "user", "content": "Reply with exactly: flatkey route ok" }
    ]
  }'

この直接リクエストが失敗した場合は、OpenCodeをデバッグする前に、Flatkeyキー、モデルエイリアス、エンドポイントファミリー、またはアカウントルートを修正してください。OpenCode OpenAI互換プロバイダーは、ゲートウェイアカウントが呼び出せないモデルエイリアスを補うことはできません。

ステップ2：OpenCodeにFlatkeyの認証情報を追加する

OpenCodeは/connectを介してプロバイダーの認証情報を保存します。OpenCode TUIで：

/connect

その他を選択し、flatkeyなどのプロバイダーIDを入力してから、Flatkey APIキーを貼り付けます。認証情報のプロンプトにベースURLを貼り付けないでください。キーはIDを証明するものであり、ベースURLはopencode.jsonに属します。

単純なプロバイダーIDを使用してください。モデルIDやロールバックのメモに入力することになるため、flatkeyはflatkey-prod-openai-compatible-gateway-v2よりも優れています。

ステップ3：OpenCodeプロバイダー設定を追加する

テストしたいプロジェクトのルートにopencode.jsonを作成または更新します。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "flatkey": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Flatkey",
      "options": {
        "baseURL": "https://router.flatkey.ai/v1"
      },
      "models": {
        "your-current-flatkey-model-alias": {
          "name": "Flatkey primary model"
        }
      }
    }
  },
  "model": "flatkey/your-current-flatkey-model-alias"
}

これは最小のOpenCode OpenAI互換プロバイダー設定です。これにより、OpenCodeにflatkeyという名前のプロバイダーが与えられ、OpenCodeにOpenAI互換のAI SDKパッケージを使用するように指示し、モデルピッカーに1つのモデルエイリアスを公開します。

OpenCodeに軽量な作業のためにより小さなルートを使用させたい場合は、プライマリルートが機能した後にのみsmall_modelを追加してください。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "flatkey": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Flatkey",
      "options": {
        "baseURL": "https://router.flatkey.ai/v1"
      },
      "models": {
        "primary-flatkey-model-alias": {
          "name": "Flatkey primary"
        },
        "lighter-flatkey-model-alias": {
          "name": "Flatkey lightweight"
        }
      }
    }
  },
  "model": "flatkey/primary-flatkey-model-alias",
  "small_model": "flatkey/lighter-flatkey-model-alias"
}

Flatkeyキーが実際に呼び出せるモデルエイリアスを使用してください。アカウントが認証済みの/v1/modelsルートを公開している場合は、設定されたモデルIDをそのレスポンスと比較してください。そうでない場合は、現在のFlatkeyダッシュボードまたはモデルディレクトリからエイリアスをコピーし、実際のリクエストでそれらを検証してください。

ステップ4：OpenCodeでモデルを選択してテストする

設定を保存した後、モデルピッカーを開きます。

/models

Flatkeyプロバイダーモデルを選択します。次に、OpenCodeで小さなプロンプトを実行します。

Reply with exactly: opencode flatkey route ok

まだコーディングワークフロー全体を移行しないでください。まず、コンパクトな検証パケットを保存します。

これにより、OpenCode OpenAI互換プロバイダーの移行が、闇雲なプロバイダーの交換ではなく、小さな運用上の変更になります。

ステップ5：Chat CompletionsとResponsesを分離しておく

OpenCodeのカスタムプロバイダーのドキュメントでは、パッケージの境界について言及しています。/v1/chat/completionsを使用するOpenAI互換プロバイダーには@ai-sdk/openai-compatibleを使用し、プロバイダーまたはモデルが/v1/responsesを使用する場合は@ai-sdk/openaiを使用します。

つまり、選択したモデルとクライアントパスが異なるエンドポイントファミリーを使用するという現在の証拠がない限り、最初のFlatkeyルートはChat Completions形式のモデルであるべきです。

モデルを追加する前に、この決定表を使用してください。

ほとんどのセットアップ作業では、1つのChat Completionsルートから始めます。ストリーミング、ツール呼び出し、セカンダリモデルエイリアスは、最初のOpenCode OpenAI互換プロバイダーのスモークテストがFlatkeyで確認できた後に追加します。

ステップ6：ルートが機能した後にチームコントロールを追加する

OpenCodeがFlatkeyを呼び出せるようになったら、ルートを監視可能にします。

ここでFlatkeyは単なるベースURL以上のものになります。機能するOpenCode OpenAI互換プロバイダーは、プラットフォーム、財務、および運用チームに、すべての開発者に個別のプロバイダーアカウントの管理を依頼することなく、モデルの使用状況を確認し、ルートを変更する場所も提供する必要があります。

より広範な移行計画については、このガイドをFlatkeyのOpenAI互換API移行ガイドと組み合わせてください。隣接するコーディングツールを比較している場合は、Continue.dev OpenAI互換プロバイダーガイドおよびRoo Code OpenAI互換セットアップガイドを参照してください。

OpenCode OpenAI互換プロバイダーのトラブルシューティング

最初のリクエストが失敗した場合は、まだプロンプト、エージェント、権限、またはリポジトリコードを変更しないでください。OpenCode OpenAI互換プロバイダーのデバッグ対象を、認証情報、プロバイダーID、ベースURL、パッケージ、モデルエイリアス、および1つのプレーンなチャットリクエストに絞り込みます。

最終チェックリスト

FlatkeyをデフォルトのOpenCodeルートとして使用する前に、以下を確認してください：

1. /connectに、opencode.jsonで使用されているのと同じプロバイダーIDの下にFlatkey認証情報がある。
2. Chat Completionsルートの場合、provider.flatkey.npmが@ai-sdk/openai-compatibleである。
3. provider.flatkey.options.baseURLがhttps://router.flatkey.ai/v1である。
4. modelが設定済みのflatkey/<model-alias>値を指している。
5. /modelsに設定済みのFlatkeyモデルが表示される。
6. 1行のOpenCodeプロンプトが正常に返される。
7. Flatkeyの使用状況またはリクエストログにOpenCodeテストリクエストが表示される。
8. 以前のプロバイダー/モデルルートがロールバック用に文書化されている。

OpenCode OpenAI互換プロバイダーのセットアップは、プロバイダーが設定され、選択可能で、Flatkeyログで検証され、元に戻せる状態になったときに完了します。コーディングエージェントモデルのトラフィックを1つのキーでルーティングする準備ができたら、Flatkeyキーを取得し、単一の低リスクのOpenCodeプロンプトから始めます。