OpenCode 設定

1. OpenCode とは何か、必要なもの

OpenCode はオープンソースの AI コーディングエージェントです。ターミナルでリポジトリを読み取り、コードを変更し、コマンドを実行できます。また、デスクトップ、Web インターフェース、IDE 拡張と組み合わせて使用できます。

RouteAPI 経由で OpenCode に接続する前に、次の準備を推奨します。

正常に使用できるターミナル環境
あなたの RouteAPI キー
RouteAPI コンソールで利用可能で、コーディングタスクに適したモデル
OpenAI-compatible プロトコルとツール呼び出しに対応するモデルを優先してください。

2. OpenCode のインストール

CLI をインストールする

macOS / Linux / WSL を使用している場合、公式推奨のインストール方法は次のとおりです。

curl -fsSL https://opencode.ai/install | bash

Node.js でグローバルインストールする方に慣れている場合は、次も使用できます。

npm install -g opencode-ai

Windows PowerShell ネイティブ環境を使用している場合は、直接次を実行できます。

npm install -g opencode-ai

インストール確認

opencode --version

バージョン番号が出力されれば、OpenCode CLI は正常にインストールされています。

3. 推奨方式: 先にキーを保存し、その後プロジェクト設定を書く

OpenCode 公式ドキュメントでは、先に /connect で認証情報を保存し、その後設定ファイルで provider と model を宣言する方法が推奨されています。RouteAPI のように内蔵リストにないゲートウェイでは、Other を選択します。

OpenCode に RouteAPI キーを保存する

まず OpenCode を起動します。

opencode

会話内で次を実行します。

/connect

続いて、順番に完了します。

Other を選択します。
provider ID に routeapi を入力します。
あなたの RouteAPI キーを貼り付けます。

認証情報は OpenCode によってローカルの ~/.local/share/opencode/auth.json に自動的に書き込まれるため、通常は手動編集不要です。

プロジェクトルートに `opencode.json` を作成する

OpenCode 公式ドキュメントでは、グローバル設定 ~/.config/opencode/opencode.json とプロジェクトルートの opencode.json の両方がサポートされています。チームでの共同作業では、通常、機密ではない設定をプロジェクトルートに置く方法を推奨します。

{
      "$schema": "https://opencode.ai/config.json",
      "provider": {
        "routeapi": {
          "npm": "@ai-sdk/openai-compatible",
          "name": "RouteAPI",
          "options": {
            "baseURL": "https://www.routeapi.ai/v1"
          },
          "models": {
            "your-routeapi-model-id": {
              "name": "RouteAPI Model"
            }
          }
        }
      },
      "model": "routeapi/your-routeapi-model-id"
}

上記の設定では、次の意味になります。

routeapi: カスタム provider の一意な ID で、/connect 時に入力した provider ID と完全に一致している必要があります。
npm: /v1/chat/completions では @ai-sdk/openai-compatible を使用し、/v1/responses では @ai-sdk/openai を使用します。
options.baseURL: https://www.routeapi.ai/v1
models: キー名には RouteAPI コンソールで実際に利用可能なモデル ID を指定します。表示名は使わないでください。
model: 既定モデルの形式は provider_id/model_id です。ここでは routeapi/your-routeapi-model-id になります。

4. `/connect` を使わない場合: 環境変数を使用する

キーを環境変数から読み取る運用に慣れている場合は、opencode.json の options.apiKey に直接指定することもできます。これは OpenCode 公式ドキュメントでサポートされている変数記法です。

4.1 環境変数を設定する

macOS / Linux / WSL の bash、zsh、sh を使用している場合:

export ROUTEAPI_KEY="あなたの RouteAPI キー"

Windows PowerShell を使用している場合:

$env:ROUTEAPI_KEY="あなたの RouteAPI キー"

4.2 `opencode.json` で環境変数を参照する

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
"routeapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "RouteAPI",
      "options": {
        "baseURL": "https://www.routeapi.ai/v1",
        "apiKey": "{env:ROUTEAPI_KEY}"
      },
      "models": {
        "your-routeapi-model-id": {
          "name": "RouteAPI Model"
        }
      }
}
  },
  "model": "routeapi/your-routeapi-model-id"
}

5. モデルを選択して OpenCode を起動する

設定が完了したら、次のようにモデルを選択して起動できます。

OpenCode を起動します。

opencode

会話内で次を実行します。

/models

routeapi 配下のモデルを選択します。opencode.json で model を設定済みの場合、OpenCode はそれを既定で使用します。

現在のセッションだけ一時的にモデルを切り替えたい場合は、コマンドライン引数も使用できます。

opencode -m routeapi/your-routeapi-model-id

タイトル生成などの軽量タスクに別の安価なモデルを指定したい場合は、設定に次を追加できます。

{
  "small_model": "routeapi/your-small-model-id"
}

6. よくあるトラブルシューティング

opencode auth list を実行し、ローカルに routeapi の認証情報が保存されていることを確認してください。
/models にカスタム provider が表示されない場合は、/connect 時に入力した provider ID が opencode.json の routeapi と完全に一致しているかを確認してください。
モデルは表示されるのにリクエストでプロトコルエラーが出る場合は、npm パッケージの選択を優先して確認してください。/v1/chat/completions では @ai-sdk/openai-compatible、/v1/responses では @ai-sdk/openai を使います。
Windows でファイルアクセスが遅い、ターミナルの動作が不安定、パスが一致しないなどの問題がある場合は、WSL で OpenCode を実行することを優先してください。
他の RouteAPI クライアント接続方式と比較したい場合は、Codex 設定ガイド、Cursor 設定ガイド、Claude Code 設定ガイドも続けて参照してください。