AI コーディング

ロシアでOpenCodeを使う: インストール、API設定、最初のリクエスト

OpenCodeをインストールし、/connectでAPI Keyを保存。BetterToken providerを設定して最初のリクエストをDashboardで検証する手順。

BetterToken

編集チーム

2026年8月3日2 分で読めます

自分のAPI KeyでOpenCodeを動かしたい場合は、BetterTokenで自分のアカウントとAPI Keyを作成し、OpenCodeの設定ガイドを開いて、/connectまたはopencode.jsonで設定します。Base URLにはhttps://www.bettertoken.ai/v1を指定し、現在のModel IDを選び、短いリクエストを実行してください。最後にDashboardでモデル、ステータス、Token使用量を照合します。

ロシアでOpenCodeを起動する前に必要なもの

OpenCodeはターミナルで動くコーディングエージェントです。プロジェクト内のファイルを読み、選択したモデルと作業し、リポジトリ内で操作を行えます。最初の起動には次のものを用意します。

公式のインストール方法を使えるmacOS、Linux、またはWindows環境
自分のBetterToken API Key
BetterTokenの現在のモデル一覧で確認したModel ID
エージェントの応答を安全に試せるテスト用ディレクトリ

この構成でBetterTokenが担当するのは外部APIリクエストです。OpenCodeのサイト、インストーラ、GitHub、更新サービスの利用可否を保証するものではありません。ロシアからBetterTokenのAPI Endpointへ接続する際はVPNを必要としませんが、この条件は第三者サイトへのアクセスやダウンロードには及びません。

公式ソースからOpenCodeをインストールする

以下から一つの方法を選びます。Node.jsが必要なのはnpm経由でインストールする場合だけです。同じ環境に複数の方法で重ねて入れる前に、まず一つの方法でopencode --versionが動くことを確認してください。

macOSとLinux: 公式インストーラ


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

インストール後は新しいターミナルを開くか、シェル設定を読み直してからバイナリを確認します。インストーラの出力にエラーがあれば、次の方法へ進む前にその内容とインストール先を確認してください。

npm


npm install -g opencode-ai

npmのグローバル実行ファイル用ディレクトリがPATHに含まれていないと、インストールに成功してもコマンドは見つかりません。パッケージを再インストールする前に、npmがどこへ実行ファイルを置いたかを確認します。

Homebrew


brew install anomalyco/tap/opencode

OpenCodeは専用tapを案内しています。Homebrew側が管理するbrew install opencodeのformulaは将来変わる可能性があるため、記事内では専用tapのコマンドを使います。インストール方法によって設定ファイルの優先順位が変わるわけではありません。

Windows

公式ドキュメントではChocolateyまたはScoopが案内されています。


choco install opencode

または次を使います。


scoop install opencode

どのOSでも、インストール直後に次のコマンドを実行します。


opencode --version

command not foundなどのエラーが出ず、バージョンが表示されれば、コマンドは利用可能です。具体的なバージョン番号はリリースごとに変わるため、ここでは固定しません。

`/connect`と`opencode.json`の役割

OpenCodeでは、認証情報とprovider設定を別々に管理できます。通常の設定では、/connectがAPI Keyを~/.local/share/opencode/auth.jsonに保存します。ユーザー全体のproviderとモデルは~/.config/opencode/opencode.jsonで指定し、プロジェクトのルートに置くopencode.jsonはそのリポジトリだけの設定を変更します。

設定ファイルは結合され、競合した値は後から読み込まれるソースが前の値を上書きします。通常のローカル設定では、グローバル設定 → OPENCODE_CONFIGで指定したファイル → プロジェクトのopencode.jsonの順序が重要です。組織が管理する設定には、これとは別に最上位の優先順位があります。

1. `/connect`でAPI Keyを保存する

まず、実際のリポジトリではなくテスト用ディレクトリでOpenCodeを起動します。


mkdir opencode-first-test
cd opencode-first-test
opencode

TUIで次を実行します。


/connect

Otherを選び、provider idとしてbettertokenを入力してから、credential欄に自分のAPI Keyを貼り付けます。本物のKeyをプロンプト、opencode.json、スクリーンショット、Gitへ入れてはいけません。

保存後はOpenCodeを終了し、providerが登録されたことを確認します。


opencode auth list

このコマンドにはproviderが表示されますが、Keyそのものは表示されない状態が正しい結果です。

2. BetterToken providerを追加する

すべてのプロジェクトで使う場合は、次のファイルを作成または更新します。


~/.config/opencode/opencode.json

一つのリポジトリだけで使う場合は、そのルートにopencode.jsonを置きます。最小構成は次のとおりです。


{
  "$schema": "https://opencode.ai/config.json",
  "model": "bettertoken/YOUR_MODEL_ID",
  "provider": {
    "bettertoken": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "BetterToken",
      "options": {
        "baseURL": "https://www.bettertoken.ai/v1"
      },
      "models": {
        "YOUR_MODEL_ID": {
          "name": "YOUR_MODEL_ID"
        }
      }
    }
  }
}

YOUR_MODEL_IDは、現在のBetterTokenのモデル一覧にある正確なIDへ置き換えます。同じ値を最上位のmodel、modelsオブジェクトのキー、その中のnameに使います。Base URLへ/chat/completionsを追加しないでください。OpenCodeと@ai-sdk/openai-compatibleがリクエストのパスを組み立てます。自動設定コマンドや現在のモデルグループの制限は、BetterTokenのOpenCodeドキュメントで確認します。モデル一覧は変動するため、記事内でIDを固定しません。

3. どの設定ファイルが優先されたかを確認する

プロジェクトのopencode.jsonは、グローバルのモデルやproviderを上書きできます。意図しないendpointやモデルが選ばれた場合は、次の順に確認します。

~/.config/opencode/opencode.json
設定されている場合はOPENCODE_CONFIGの値
現在のプロジェクト、またはGitルートまでの最も近い親ディレクトリにあるopencode.json

ファイルを推測で削除しないでください。見つけた設定すべてでmodel、provider.bettertoken.options.baseURL、provider.bettertoken.modelsの値を比べます。通常のファイル間ではプロジェクト設定の優先順位が高いため、グローバル設定だけを直しても結果が変わらないことがあります。

最初のリクエストを実行して検証する

JSONを変更した後はOpenCodeを再起動します。


opencode

モデル選択を開きます。


/models

bettertoken/YOUR_MODEL_IDを選び、ファイルを変更しない短い問い合わせを送ります。たとえば次のようにします。


JSONだけを返してください: {"tool":"opencode","sum":4}。ファイルは変更しないでください。

最初のリクエストは、次の四つが一致して初めて確認済みと考えます。

OpenCodeが有効なJSONを返し、ファイルを変更していない。
TUIでbettertoken/YOUR_MODEL_IDが選択されている。
BetterToken Dashboardに、想定したモデルとステータスのリクエストが記録されている。
Dashboardにinput、output、該当するcache Token、および対応する消費が表示されている。

Dashboardはプロンプトや応答本文を保管する場所として扱う必要はありません。ここで確認するのはToken使用量と消費に関する記録です。記録が現れない場合、設定の上書きにより別のproviderから応答した可能性があります。まず設定の優先順位へ戻り、短いリクエストで再確認します。

よくあるエラーを修正する

`opencode: command not found`

ターミナルを閉じて開き直します。npmで導入した場合は、npmのグローバル実行ファイル用ディレクトリがPATHに入っているかを確認します。最初のバイナリがどこに入ったかを確認する前に、別のインストーラを実行しないでください。複数の導入経路を重ねると、どの実行ファイルを使っているか追跡しにくくなります。

`401`またはcredentialエラー

/connectを再度実行し、provider idにbettertokenを選びます。結果はopencode auth listで確認します。短い確認のためでも、KeyをコマンドラインやJSONへ直接貼り付けないでください。認証情報は/connectの保存先に任せ、設定ファイルにはproviderの構造だけを残します。

`404`またはAPIエラー

provider.bettertoken.options.baseURLには次のBase URLを設定します。


https://www.bettertoken.ai/v1

/chat/completionsを末尾へ追加しません。URLを修正したらOpenCodeを再起動し、長いタスクではなく先ほどの短いリクエストをもう一度実行します。URLが正しいのにエラーが続く場合は、現在のModel IDと設定の上書きを確認します。

`model not found`

現在のドキュメントとモデル一覧でModel IDのつづりを確認します。最上位のmodelはbettertoken/YOUR_MODEL_IDの形であり、provider.bettertoken.modelsには同じYOUR_MODEL_IDをキーとして持つ必要があります。古い記事や別のproviderのモデル名をコピーしても、現在のカタログにないIDは選択できません。

OpenCodeが別のモデルまたはendpointを使う

多くの場合、設定の上書きが原因です。グローバル設定、OPENCODE_CONFIG、プロジェクトの設定ファイルを比較します。標準の設定ファイル間ではプロジェクト側の設定が優先されます。修正後はOpenCodeを完全に再起動し、/modelsとDashboardの両方で、選択したモデルと実際のリクエストを確認します。

FAQ

API Keyを`opencode.json`に保存する必要はありますか？

ありません。通常の設定では/connectを使います。OpenCodeがcredentialを~/.local/share/opencode/auth.jsonに保存するため、設定ファイルには本物のKeyを入れずに済みます。リポジトリに置くopencode.jsonは、誤ってコミットされないよう内容を確認してください。

OpenCodeに必要なBase URLは何ですか？

BetterTokenのOpenAI-compatible providerにはhttps://www.bettertoken.ai/v1を使います。これはBase URLなので、/chat/completionsを手動で追加しません。www付きの別URLや、Claude Code向けのBase URLを混ぜないようにします。

グローバルとプロジェクトのどちらの`opencode.json`を選ぶべきですか？

一つのproviderとモデルを多くのリポジトリで共通利用するなら、グローバルファイルが便利です。特定のリポジトリだけ別のModel IDや権限を必要とするなら、プロジェクトファイルを使います。競合時にはプロジェクトの設定が上書きするため、問題が起きたときは両方を確認します。

BetterToken providerを使うためにOpenCodeのアカウントは必要ですか？

custom providerは、選択したAPIサービスのcredentialを使います。BetterTokenは自分のAPI Keyを提供しますが、OpenCodeのサイト、アカウント、その他のサービスを置き換えるものではありません。OpenCode自体に現在必要なアカウント条件は、OpenCode公式ドキュメントで確認してください。

LLM ワークフローを最適化しませんか？

単一 API でモデルを接続し、キーと AI コストを管理できます。