AI コーディング

OpenCodeのAPI Keyと認証設定：Astra、Grok、プロキシ、Webパスワード

OpenCodeのAPI Key、カスタムプロバイダー、GPT-6 Astra、Grokの直接認証、OpenCode Go、Astra Linux、地域・社内プロキシ、Webパスワード、よくあるエラーをまとめた実践ガイドです。

BetterToken

編集チーム

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

OpenCodeのAPI Keyと認証設定：Astra、Grok、プロキシ、Webパスワード

OpenCodeの認証に関する質問は似て見えますが、実際には別々の層を指しています。モデルプロバイダーのAPI Key、OpenCode Goへのログイン、xAIのOAuth認証、opencode webを保護するパスワードは、それぞれ用途が異なります。

この記事ではそれらを切り分け、BetterTokenをカスタムプロバイダーとして動かす設定を示します。gpt-6-astraを使うコピー可能な例、LinuxやAstra Linuxでのネットワーク設定、Grokの直接認証、OpenCode Webを安全に公開する方法まで一つずつ説明します。

OpenCodeは更新が速いプロジェクトです。本番で使う前に、以下のコマンドを最新のOpenCode公式ドキュメントと照合し、正確なモデルIDをBetterTokenのモデル一覧で確認してください。

先に結論

やりたいこと	正しい場所またはコマンド
プロバイダーのAPI Keyを対話形式で保存する	OpenCode内で`/connect`を実行
保存済みプロバイダーを確認する	`opencode auth list`を実行
カスタムプロバイダー、Base URL、モデルを定義する	`opencode.json`または`opencode.jsonc`
BetterTokenを使う	Base URL: `https://www.bettertoken.ai/v1`
GPT-6 Astraを使う	モデルID: `gpt-6-astra`。現在のアカウントで利用可能な場合のみ
OpenCode Goにサインインする	`/connect` → OpenCode Go → `https://opencode.ai/auth`
xAI/Grokへ直接認証する	`/connect` → xAI → OAuth対象サブスクリプションまたはAPI Key
OpenCode Webを保護する	`opencode web`の前に`OPENCODE_SERVER_PASSWORD`を設定
地域・社内プロキシを使う	`HTTP_PROXY`、`HTTPS_PROXY`、`NO_PROXY`を設定

準備するもの

次のものを用意してください。

新しいバージョンのOpenCode
本番共有キーではなく、テスト専用のAPI Key
プロバイダーのカタログに表示される正確なモデルID
エージェントが重要ファイルを変更しないようにできる小さなテスト用リポジトリ
OpenCodeのインストーラーとAPIエンドポイントへ接続できるターミナル環境

API Keyはパスワードと同じように扱ってください。実際のキーをプロンプト、スクリーンショット、Issue、記事、Gitリポジトリへ貼り付けてはいけません。

OpenCodeをインストールする

公式インストーラーはmacOSとLinuxで使えます。

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

npmからのインストールも可能です。

npm install -g opencode-ai

Windowsでは、互換性を高めるためにWSLが推奨されています。ChocolateyとScoopも公式ドキュメントに記載されています。

choco install opencode

scoop install opencode

インストールを確認します。

opencode --version

バージョン番号が表示されれば成功です。command not foundと出る場合は、ターミナルを開き直し、インストール先がPATHに含まれているか確認してください。

4種類の認証を区別する

1. プロバイダーのAPI Key

BetterToken、xAI、OpenAIなどのモデルプロバイダーへの呼び出しを許可するキーです。OpenCodeでは/connectで保存するか、設定ファイルから参照した環境変数を読み取らせます。

2. OpenCode GoまたはOpenCode Zenの認証

OpenCode GoとZenは、OpenCodeが運営するモデルサービスです。認証ではhttps://opencode.ai/authを開き、ログインと必要な課金設定を完了し、発行されたAPI Keyをコピーして/connectへ戻します。

このキーはBetterTokenのキーとは無関係です。

3. xAI/Grokの認証

現在のOpenCodeのプロバイダーフローでは、対象のxAIサブスクリプションをデバイスコードOAuthで認証する方法と、従量課金のxAI API Keyを使う方法があります。これはxAIへの直接接続であり、BetterToken経由ではありません。

4. OpenCode Webのパスワード

OPENCODE_SERVER_PASSWORDは、ローカルのOpenCode HTTPサーバーとブラウザー画面をBasic認証で保護します。モデル呼び出しを許可するものではなく、プロバイダーのAPI Keyの代わりにもなりません。

OpenCodeにAPI Keyを設定する方法

OpenCodeはJSONとJSONCの両方に対応しています。公式例ではopencode.jsonがよく使われますが、コメントを書きたいときはJSONCが便利です。重要なのは、資格情報の保存とプロバイダー定義は別の設定だという点です。

方法1：`/connect`でキーを保存する

安全なテスト用ディレクトリでOpenCodeを起動します。

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

TUI内で次を実行します。

/connect

BetterTokenの場合は次の手順です。

Otherを選びます。
プロバイダーIDとしてbettertokenを入力します。
資格情報欄へBetterTokenのAPI Keyを貼り付けます。
プロバイダー設定を追加した後、OpenCodeを終了または再起動します。

/connectで追加した資格情報は、次の場所に保存されます。

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

秘密情報を表示せずに、プロバイダーが登録されたか確認します。

opencode auth list

/connectで使ったプロバイダーIDは、設定ファイルのIDと完全に一致させる必要があります。bettertokenと入力したなら、設定側のキーもbettertokenにしてください。

方法2：`opencode.json`または`opencode.jsonc`を設定する

すべてのプロジェクトで同じプロバイダーを使う場合は、グローバル設定を使います。

~/.config/opencode/opencode.json

特定のリポジトリだけに専用のモデルやエンドポイントが必要なら、プロジェクト直下のopencode.jsonまたはopencode.jsoncを使います。

次の例はBetterTokenと現在のAPIモデルID gpt-6-astraを使用します。

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

使用前に、gpt-6-astraが現在のBetterTokenカタログとアカウントのアクセスグループに表示されるか確認してください。別のモデルIDが表示されている場合は、bettertoken/gpt-6-astraとmodels内のgpt-6-astraキーを両方置き換えます。

Base URLの末尾に/chat/completionsを追加しないでください。リクエストパスはアダプターが組み立てます。

`/connect`の代わりに環境変数を使う

macOSまたはLinuxでは次のように設定します。

export BETTERTOKEN_API_KEY="YOUR_API_KEY"

PowerShellでは次のとおりです。

$env:BETTERTOKEN_API_KEY = "YOUR_API_KEY"

その後、プロバイダーのオプションから変数を参照します。

{
  "$schema": "https://opencode.ai/config.json",
  "model": "bettertoken/gpt-6-astra",
  "provider": {
    "bettertoken": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "BetterToken",
      "options": {
        "baseURL": "https://www.bettertoken.ai/v1",
        "apiKey": "{env:BETTERTOKEN_API_KEY}"
      },
      "models": {
        "gpt-6-astra": {
          "name": "GPT-6 Astra"
        }
      }
    }
  }
}

JSONへ秘密情報を直接書くより安全です。環境変数が存在しない場合、OpenCodeは空文字列へ置換するため、通常は401エラーになります。

設定が無視される理由

OpenCodeは複数の設定ソースをマージします。同じ項目が競合した場合、後に読み込まれるソースが先の値を上書きします。主な順序は次のとおりです。

組織のリモートデフォルト
~/.config/opencode/opencode.jsonのグローバル設定
OPENCODE_CONFIGで指定したカスタムファイル
プロジェクトのopencode.jsonまたはopencode.jsonc
OPENCODE_CONFIG_CONTENTのインライン設定
管理者が管理する設定。ユーザーファイルより優先される場合があります

違うモデルやエンドポイントが選ばれたときに、ファイルを手当たり次第に削除してはいけません。有効な設定をすべて探し、次を比較してください。

トップレベルのmodel
provider.bettertoken.options.baseURL
provider.bettertoken.models内のモデルキー
現在のシェルにあるOPENCODE_CONFIGとOPENCODE_CONFIG_CONTENT

プロバイダー設定を変更したらOpenCodeを再起動してください。

OpenCode Astraはモデル名か、Astra Linuxか

「OpenCode Astra」という検索語には二つの意味があります。

OpenCodeでGPT-6 Astraを使う

OpenAIのモデルを指す場合は、正確なAPI ID gpt-6-astraを使います。上のBetterToken設定では次を選択します。

bettertoken/gpt-6-astra

OpenCode内でモデル選択画面を開きます。

/models

モデルが表示されない場合は、プロバイダーID、modelsマップ、BetterTokenのアクセスグループ、現在のカタログを確認してください。表示名からモデルIDを推測しないでください。

Astra LinuxでOpenCodeを動かす

OpenCodeのドキュメントにはLinux向けのインストール方法がありますが、Astra Linux専用のサポート保証は公開されていません。Astra LinuxをLinux環境として扱い、互換性を決めつけず、実際のマシンで検証してください。

アーキテクチャと必要なツールを確認します。

uname -m
command -v curl
command -v bash

次に、インストーラーとAPIへの経路を別々にテストします。モデルAPIへ接続できても、OpenCodeのインストーラー、npmレジストリ、GitHub、更新サーバーまで接続できるとは限りません。

一般的なプロキシは次のように設定します。

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,::1
opencode

NO_PROXYは重要です。TUIはローカルのOpenCode HTTPサーバーと通信するため、ループバック通信までプロキシへ送ると、接続ループや画面が固まったように見える問題が起きる可能性があります。

組織内のプライベート認証局を使う場合は、次のように設定します。

export NODE_EXTRA_CA_CERTS=/etc/company/ca.pem
opencode

実際のプロキシ資格情報を共有シェルスクリプトへ直接書かないでください。組織のシークレット管理機能や保護された環境設定を使いましょう。

OpenCodeのGrok認証：xAIへ直接接続するか、ゲートウェイを使うか

xAIへ直接接続する

次を実行します。

/connect

xAIを選びます。現在のOpenCodeドキュメントには、次の二つの認証方法が示されています。

対象のxAIサブスクリプションを使うデバイスコードOAuth
xAIコンソールで取得したAPI Keyの手動入力

認証後、次を実行します。

/models

利用できるGrokモデルを選択します。

BetterTokenまたは別のゲートウェイ経由でGrokを使う

カスタムゲートウェイを使えるのは、そのゲートウェイが現時点で有効なGrokモデルと対応プロトコルを公開している場合だけです。GrokのモデルIDを作り出したり、OpenAI互換ゲートウェイなら必ずxAIモデルがあると仮定したりしないでください。

先に現在のプロバイダーカタログを確認します。GrokがなければOpenCodeのxAIプロバイダーへ直接接続してください。Grok認証拡張のようなコミュニティプラグインは公式フローとは別物です。インストール前に、保守状況、要求権限、資格情報の扱いを評価してください。

OpenCode Goの認証

OpenCode Goは、すべてのプロバイダーを認証するためのコマンドではありません。OpenCodeが提供するサブスクリプションサービスです。

接続手順は次のとおりです。

/connectを実行します。
OpenCode Goを選びます。
https://opencode.ai/authを開きます。
サインインし、必要に応じて課金設定を完了して、発行されたキーをコピーします。
そのキーをOpenCodeへ貼り付けます。
/modelsを実行し、プランに含まれるモデルを選びます。

OpenCode Goを使う場合だけこのフローを使用してください。BetterTokenの場合は、プロバイダーIDとキーをbettertokenとして管理します。

OpenCode Webのパスワードは環境変数で設定する

opencode web passwordはよく検索される語ですが、一部の例ではパスワード用の-pフラグが誤って紹介されています。公式に記載されている方法はOPENCODE_SERVER_PASSWORD環境変数です。

macOSまたはLinuxでは次のように起動します。

OPENCODE_SERVER_PASSWORD='replace-with-a-strong-password' opencode web

ユーザー名も変更する場合は次のとおりです。

OPENCODE_SERVER_USERNAME='developer' \
OPENCODE_SERVER_PASSWORD='replace-with-a-strong-password' \
opencode web

PowerShellでは次のように設定します。

$env:OPENCODE_SERVER_USERNAME = "developer"
$env:OPENCODE_SERVER_PASSWORD = "replace-with-a-strong-password"
opencode web

既定のユーザー名はopencodeです。127.0.0.1だけで使うならパスワードなしでも許容できる場合がありますが、ネットワーク越しにアクセスするなら保護が必要です。認証とネットワーク制御を用意する前に、0.0.0.0へバインドしたり、トンネルで公開したりしないでください。

Webパスワードが守るのはOpenCodeサーバーです。別の場所でプロバイダーキーが漏れた場合に、そのプロバイダーアカウントまで守るものではありません。

最初のリクエストを検証する

JSONを編集したらOpenCodeを再起動します。

opencode

モデル選択を開きます。

/models

bettertoken/gpt-6-astraを選び、結果を確認しやすい小さなプロンプトを送ります。

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

設定が正しければ、次のすべてを満たすはずです。

OpenCodeが有効なJSONを返す
プロジェクト内のファイルが変更されない
選択中のモデルがbettertoken/gpt-6-astraである
BetterTokenのダッシュボードに対応するリクエストが表示される
モデル、ステータス、入力トークン、出力トークン、料金が妥当に見える

OpenCodeから応答があるのにBetterToken側へリクエストが表示されない場合、優先度の高い別の設定が他のプロバイダーへルーティングしている可能性があります。

トラブルシューティング

`401`または資格情報エラー

/connectをもう一度実行し、プロバイダーIDにbettertokenを使います。
opencode auth listを実行します。
{env:BETTERTOKEN_API_KEY}を使っている場合、秘密そのものを表示せず、変数が存在するかだけ確認します。
キーが有効で、残高や権限が足りているか確認します。

`404`またはAPIパスのエラー

BetterTokenのBase URLは次です。

https://www.bettertoken.ai/v1

/chat/completionsを手動で追加しないでください。

`model not found`

モデルカタログで現在の正確なIDを確認します。トップレベルのmodelとmodels内のキーは、呼び出したいプロバイダーとモデルに一致させる必要があります。

違うエンドポイントやモデルが使われる

グローバル、カスタム、プロジェクト、インライン、管理対象の各設定を確認します。その後OpenCodeを再起動し、/modelsでモデルを選び直します。

プロキシを有効にするとOpenCodeが止まる

ループバックアドレスを除外してください。

export NO_PROXY=localhost,127.0.0.1,::1

OpenCode Webが`Unauthorized`を返す

ブラウザーで設定済みのユーザー名とパスワードを使っているか確認します。シェル環境に古いOPENCODE_SERVER_PASSWORDが残っていないか、クライアントプロセスが別の値を継承していないかも確認してください。

`opencode: command not found`

ターミナルを開き直し、PATHを確認して、パッケージマネージャーのグローバルバイナリ位置を表示するコマンドを実行します。どの実行ファイルが使われているか分かるまでは、複数のパッケージマネージャーで同じツールを重複インストールしないでください。

よくある質問

OpenCodeにAPI Keyを設定するには？

推奨される対話形式の方法は/connectです。カスタムプロバイダーならOtherを選び、プロバイダーIDとキーを入力します。それとは別に、opencode.jsonまたはopencode.jsoncでカスタムプロバイダーとモデルを定義する必要があります。

ファイル名は`opencode.json`ですか、それとも`opencode.jsonc`ですか？

OpenCodeはJSONとJSONCの両方に対応しています。コメントが必要ならJSONCを使います。複数の設定ソースがどのようにマージされるかを理解して使い分けるのでなければ、プロジェクト設定は一つだけ有効にしてください。

OpenCodeはAPI Keyをどこに保存しますか？

/connectで追加した資格情報は~/.local/share/opencode/auth.jsonに保存されます。このファイルを公開、同期、コミットしないでください。

API Keyを設定ファイルへ直接書けますか？

OpenCodeはoptions.apiKeyに対応していますが、追跡対象のJSONへ秘密情報を直書きするのは危険です。/connect、{env:VARIABLE_NAME}、または{file:path/to/secret}を優先してください。

OpenCode Goの認証とプロバイダー認証は同じですか？

違います。OpenCode Goは独立したOpenCodeのサービスです。BetterToken、xAI、その他のプロバイダーキーとは別に管理されます。

OpenCode Webにパスワードを設定するには？

opencode webを実行する前にOPENCODE_SERVER_PASSWORDを設定します。公式の方法は環境変数であり、汎用的な-pパスワードフラグではありません。

OpenCodeでGrokを認証するには？

/connectを実行してxAIを選び、対応するサブスクリプションOAuthまたはAPI Keyの手動入力を選びます。ゲートウェイ経由で使えるのは、そのゲートウェイが実際にGrokモデルを掲載している場合だけです。

「OpenCode Astra」はGPT-6 AstraとAstra Linuxのどちらですか？

どちらを指す場合もあります。モデルならgpt-6-astraを使います。Astra LinuxならLinux向けのインストールとネットワーク確認を行い、対象ディストリビューションの実際のビルドで検証してください。

ロシアからOpenCodeを使うにはVPNが必要ですか？

一律には答えられません。インストール用ダウンロード、GitHub、npm、OpenCodeのWebサイト、モデルAPIは、それぞれ別の通信経路です。個別に接続を確認し、必要に応じて法令や社内規程に沿った地域・企業ネットワーク設定を使ってください。

公式リファレンス

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

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

無料で始める