OpenCode はプロバイダーディレクトリで 75 種類以上の LLM プロバイダーをサポートしていますが、カスタムプロバイダーも欠かせません。ゲートウェイ、ローカルランタイム、社内の推論エンドポイント、まだディレクトリに登録されていないモデルを追加できるからです。

手順はシンプルです。認証情報を保存し、プロバイダーブロックを追加し、OpenCode を再起動して、/models からモデルを選ぶだけです。

Haimaker をセットアップしたい場合は、手動手順をスキップできます。npx -y @haimaker/connect --opencode を実行すると、CLI がプロバイダーブロックを書き込み、認証情報を自動保存します（--project を付けるとプロジェクトローカルの設定になります）。以下の手順は、あらゆる OpenAI 互換プロバイダー（Ollama、LM Studio、社内ゲートウェイ、ディレクトリにまだ載っていないものなど）に使える一般的な方法です。ワンコマンドで完了したい場合は接続ガイドを参照してください。

カスタムプロバイダーを使う場面

モデルやエンドポイントが OpenCode の組み込みプロバイダー一覧にない場合は、カスタムプロバイダーを使います。

具体的な例：

  • Haimaker - 1 つの API キーで OpenAI 互換ゲートウェイ経由の複数のモデルファミリーにアクセスできます。
  • Ollama - http://localhost:11434/v1 でローカルモデルを実行できます。
  • LM Studio - http://127.0.0.1:1234/v1 でローカルモデルを実行できます。
  • 社内ゲートウェイ - 企業がホストする OpenAI 互換エンドポイント。
  • 新規プロバイダー - OpenCode のディレクトリに反映される前の、OpenAI 互換チャット API を提供するもの。

プロバイダーがすでに OpenCode に存在する場合は、まず組み込みのものを優先してください。カスタム設定が役立つのは、カスタムベース URL、ゲートウェイ、またはデフォルト一覧にないモデルが必要な場合です。

ステップ 1：認証情報の追加

現在の OpenCode ドキュメントでは、プロバイダー認証情報の登録に opencode auth login を使うよう説明されています。カスタムの OpenAI 互換プロバイダーの場合は Other を選び、プロバイダー ID を入力して API キーをペーストします。

opencode auth login

設定ファイルでも使う短いプロバイダー ID を選んでください。例：

haimaker
ollama
mygateway

OpenCode は認証情報を次の場所に保存します。

~/.local/share/opencode/auth.json

必要に応じてこのファイルを直接編集できますが、opencode auth login を使えばキーの形式の入力ミスを防げます。

ステップ 2：プロバイダーの設定

OpenCode の設定ファイルを開くか作成します。環境に応じて、プロジェクト内の opencode.json または ~/.config/opencode/ 配下のグローバルファイルになります。

認証時に使ったのと同じプロバイダー ID で provider ブロックを追加します。haimaker.ai を例にしたパターンは次のとおりです。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "haimaker": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Haimaker",
      "options": {
        "baseURL": "https://api.haimaker.ai/v1"
      },
      "models": {
        "z-ai/glm-4.6": {
          "name": "GLM 4.6"
        },
        "minimax/minimax-m2.5": {
          "name": "MiniMax M2.5"
        },
        "qwen/qwen3-coder": {
          "name": "Qwen3 Coder"
        }
      }
    }
  }
}

各フィールドの役割は次のとおりです。

  • npm：SDK アダプター。OpenAI 互換 API であれば @ai-sdk/openai-compatible を使います。OpenCode はアダプターをオンデマンドで読み込みます。
  • name：OpenCode に表示される名前です。
  • options.baseURL：プロバイダー API のベース URL です。末尾は /v1 にするか、プロバイダーが使うバージョンプレフィックスに合わせてください。
  • models：OpenCode で使えるようにするモデルです。キーは、プロバイダー API が completion リクエストの model フィールドで受け付ける値と完全に一致させる必要があります。

カスタムプロバイダーはいくつでも追加でき、それぞれを provider の下の個別エントリとして記述します。

ステップ 3：再起動と確認

OpenCode は再起動するまでプロバイダーの変更を反映しないことがあります。完全に終了して再起動し、次を実行します。

/models

プロバイダーの表示名と設定したモデルが表示されます。実際のコードに使う前に、モデルを 1 つ選んで短いプロンプトで動作確認してください。

設定例：Haimaker ゲートウェイ

複数のモデルファミリーに対して 1 つの OpenAI 互換エンドポイントを使いたい場合に便利です。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "haimaker": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Haimaker",
      "options": {
        "baseURL": "https://api.haimaker.ai/v1"
      },
      "models": {
        "anthropic/claude-sonnet-4-6": {
          "name": "Claude Sonnet 4.6"
        },
        "openai/gpt-5.4-mini": {
          "name": "GPT-5.4 Mini"
        },
        "minimax/minimax-m2.5": {
          "name": "MiniMax M2.5"
        },
        "qwen/qwen3-coder": {
          "name": "Qwen3 Coder"
        }
      }
    }
  }
}

この構成が便利な理由は、OpenCode からは 1 つのプロバイダーとして見え、Haimaker が複数のアップストリームモデルファミリーへのアクセスをまとめて処理してくれることです。OpenCode の設定はコンパクトに保たれ、モデルの切り替えもスムーズになります。

設定例：Ollama ローカルプロバイダー

Ollama は http://localhost:11434/v1 で OpenAI 互換のローカルエンドポイントを公開しています。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder:30b": {
          "name": "Qwen3 Coder 30B"
        },
        "gemma4:e4b": {
          "name": "Gemma 4 E4B"
        }
      }
    }
  }
}

OpenCode を起動する前にモデルをプルしておきます。

ollama pull qwen3-coder:30b
ollama pull gemma4:e4b

OpenCode がローカルプロバイダーに認証を要求する場合は、opencode auth login を実行し、Other を選び、プロバイダー ID に ollama を使い、ollama のような空でない任意の文字列を入力してください。Ollama はローカル API キーを検証しません。

よくあるエラーと対処法

プロバイダーが /models に表示されない

次の 4 点を確認してください。

  1. opencode auth login で入力したプロバイダー ID が、設定ファイルのプロバイダーキーと一致していること。
  2. 設定ファイルが有効な JSON または JSONC であること。
  3. プロバイダー設定を編集したあとに OpenCode を再起動したこと。
  4. モデルがプロバイダーの models オブジェクトに記載されていること。

最初のリクエストで認証が失敗する

認証情報がないか、誤ったプロバイダー ID に紐付けられています。次を実行してください。

opencode auth list

プロバイダー ID が設定と完全に一致していることを確認してください。キーのフィールドに Bearer を含めないでください。

モデルは表示されるがリクエストが失敗する

モデル ID がアップストリーム API の期待する形式と一致していない可能性があります。カスタムプロバイダーはモデル ID をそのまま渡します。設定に qwen/qwen3-coder と書いてある場合、API は qwen/qwen3-coder をそのまま受け付ける必要があります。

Haimaker の場合は、キーとエンドポイントを次のようにテストします。

curl https://api.haimaker.ai/v1/models \
  -H "Authorization: Bearer your-haimaker-api-key"

Ollama の場合は、ローカルモデルを確認します。

ollama list

この出力に表示されるモデル名をそのまま使ってください。

ローカルモデルでツールコールが失敗する

ローカルモデルはコンテキスト長の制限やツールコールの形式の影響を受けやすいです。エージェントコーディングが得意なモデル（Qwen3 Coder など）から始め、コンテキストサイズは小さめに抑えましょう。OpenCode のドキュメントでは、ツールコールがうまくいかない場合に Ollama の num_ctx を増やすことも推奨されています。

組み込みプロバイダーが動作しなくなった

意図せず設定を必要以上に書き換えてしまった可能性があります。カスタムプロバイダーは provider オブジェクト内に配置し、既存のプロバイダーエントリを削除しないでください。迷ったら、設定変更は最小限にしてください。プロバイダー ID を 1 つとモデルを 1 つ追加し、再起動してテストし、問題がなければ追加してください。

実践的な構成

ほとんどの OpenCode ユーザーにとって、シンプルな構成は次のとおりです。

  1. Haimaker - 1 つの API キーによるクラウドモデルの利用とルーティングに。
  2. Ollama - ローカルでのプライベートな作業に。
  3. プレミアムモデル 1 つ - 難しいデバッグや複数ファイルのリファクタリング用に。

これにより、プライバシーが重要な場面ではローカルで処理し、日常的な作業には低コストのクラウドモデルを使い、高度な集中力を要するコーディングタスクにはより高性能なモデルを使えます。

OpenCode で Haimaker を使う

ローカルセットアップについては OpenCode で Ollama を使う を参照してください。ローカルモデルの比較については コーディングエージェント向けのおすすめ Ollama モデル を参照してください。