概要
OpenCodeは、設定のカスタマイズに多数の環境変数をサポートしている。
認証、モデル選択、設定ファイルパス、ネットワーク、LSP設定等、動作の細部にわたる制御が環境変数を通じて可能である。
OpenCodeは、75以上のLLMプロバイダをサポートしており、環境変数によってプロバイダごとのAPIキーや接続設定を柔軟に管理できる。
主要カテゴリは以下の通りである。
- 認証関連
- APIキー、対話的認証、サーバ認証
- モデル設定
- デフォルトモデル、プロバイダ固有オプション、モデル変種
- 設定ファイル関連
- カスタム設定パス、インライン設定
- ネットワーク・プロキシ
- カスタムエンドポイント、プロキシ設定
- LSP関連
- LSPサーバの制御、実験的機能
環境変数の設定方法
シェル環境変数
export コマンドを使用して、現在のシェルセッションに環境変数を一時的に設定できる。
Fishシェルでは、set -x コマンド または set -Ux コマンドを使用することもできる。
永続化する場合は、~/.profile、~/.zprofile 等に設定する。
# 一時的な設定 (現在のセッションのみ有効)
export ANTHROPIC_API_KEY="sk-ant-xxxx"
# Bash / Zsh での永続化 (~/.profile または ~/.zprofile 等に設定)
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxx"' >> ~/.bashrc
# Fishでの設定
set -x ANTHROPIC_API_KEY "sk-ant-xxxx"
# Fishでの永続化
set -Ux ANTHROPIC_API_KEY "sk-ant-xxxx"
opencode.jsonによる参照
opencode.json では、{env:変数名} 形式を使用して環境変数を参照することができる。
APIキー等の機密情報をJSONファイルに直接記載することなく、環境変数から読み込める。
使用例を以下に示す。
{
"providers": {
"anthropic": {
"apiKey": "{env:ANTHROPIC_API_KEY}"
},
"openai": {
"apiKey": "{env:OPENAI_API_KEY}"
}
}
}
また、プロジェクトルートの .envファイル は、OpenCode起動時に自動的にロードされる。
プロジェクト固有のAPIキーや設定を .envファイル で管理する場合に有用である。
設定の優先度
OpenCodeの設定は階層的に管理されており、複数の場所で同じ設定が定義された場合は、より高い優先度の設定が適用される。
| 優先度 | 設定場所 | 説明 |
|---|---|---|
| 1 (最高) | リモート設定 | .well-known/opencode による設定 |
| 2 | グローバル設定 | ~/.config/opencode/opencode.json |
| 3 | カスタム設定 | 環境変数 OPENCODE_CONFIG で指定したファイル
|
| 4 | プロジェクト設定 | プロジェクトルートのopencode.json |
| 5 | .opencodeディレクトリ | .opencode/ディレクトリ内の設定 |
| 6 (最低) | インライン設定 | 環境変数 OPENCODE_CONFIG_CONTENT
|
認証関連
APIキーの設定
OpenCodeは75以上のLLMプロバイダをサポートしており、各プロバイダに対応するAPIキーを環境変数で設定する。
下表に、主要なプロバイダのAPIキー環境変数を示す。
| 環境変数 | 説明 |
|---|---|
ANTHROPIC_API_KEY |
Anthropic Claudeモデルの認証に使用する。 |
OPENAI_API_KEY |
OpenAI GPTモデルの認証に使用する。 |
GEMINI_API_KEY |
Google Geminiモデルの認証に使用する。 |
GROQ_API_KEY |
Groqのモデルの認証に使用する。 |
XAI_API_KEY |
X AI (Grok) モデルの認証に使用する。 |
GITHUB_TOKEN |
GitHub Copilotモデルの認証に使用する。 |
OPENROUTER_API_KEY |
OpenRouter経由のモデルの認証に使用する。 |
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_REGION |
AWS Bedrockモデルの認証に使用する。 |
AZURE_API_KEY / AZURE_ENDPOINT |
Azure OpenAIモデルの認証に使用する。 |
設定例を以下に示す。
# Anthropic Claude
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxx"
# OpenAI
export OPENAI_API_KEY="sk-xxxxxxxxxxxx"
# Google Gemini
export GEMINI_API_KEY="AIzaXXXXXXXXXXXX"
# AWS Bedrock
export AWS_ACCESS_KEY_ID="AKIAXXXXXXXXXXXXXXXX"
export AWS_SECRET_ACCESS_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export AWS_REGION="us-east-1"
opencode auth loginコマンド
環境変数によるAPIキーの手動設定に加え、対話的な認証フローを提供する opencode auth login コマンドも利用できる。
# コマンドラインから実行 opencode auth login
# OpenCodeセッション内から実行 /connect
コマンドを実行すると、Webブラウザが起動して認証フローが開始される。
認証が完了すると、認証情報は以下のパスに保存される。
- 保存先
- ~/.local/share/opencode/auth.json
このファイルのパーミッション管理に注意すること。
機密情報が含まれるため、適切なアクセス権限を設定することを推奨する。
また、環境変数 OPENCODE_SERVER_PASSWORD を設定することにより、OpenCodeのHTTPサーバに基本認証を設定することができる。
本番環境では必ず設定することを推奨する。
モデル設定
デフォルトモデルの指定
opencode.jsonファイル の model フィールドを使用して、デフォルトのLLMモデルを指定する。
モデルの指定形式は、<プロバイダID>/<モデルID> である。
設定例を以下に示す。
{
"model": "anthropic/claude-sonnet-4-5",
"small_model": "anthropic/claude-haiku-4-5"
}
small_model フィールドは、軽量タスク向けの小型モデルを指定する。
コスト効率を高めるために、重い処理には model を、軽い処理には small_model を使い分けることができる。
モデルの設定優先度は以下の通りである。
| 優先度 | 方法 | 説明 |
|---|---|---|
| 1 (最高) | --model <CLIフラグ> | 起動時にコマンドラインで直接指定 |
| 2 | opencode.jsonファイルの model フィールド |
設定ファイルで指定 |
| 3 (最低) | 前回使用したモデル | 自動引き継ぎ |
プロバイダ固有オプション
opencode.jsonファイル の providers セクションを使用して、プロバイダごとの接続設定を記述することができる。
設定例を以下に示す。
{
"providers": {
"anthropic": {
"apiKey": "{env:ANTHROPIC_API_KEY}"
},
"openai": {
"apiKey": "{env:OPENAI_API_KEY}",
"baseURL": "https://api.openai.com/v1"
},
"ollama": {
"baseURL": "http://localhost:11434"
}
}
}
baseURL フィールドを使用することにより、カスタムエンドポイントを指定できる。
OllamaやLiteLLM等のローカルLLMサーバを使用する場合に有用である。
モデル変種 (Variants)
OpenCodeでは、モデル変種 (Variants) を定義することにより、プロンプトパラメータをカスタマイズしたモデル設定を作成できる。
Variants設定の例を以下に示す。
{
"model": "anthropic/claude-sonnet-4-5",
"modelVariants": {
"fast": {
"model": "anthropic/claude-haiku-4-5",
"temperature": 0.3
},
"creative": {
"model": "anthropic/claude-opus-4-5",
"temperature": 0.9
}
}
}
定義したVariantsはセッション内でモデルを切り替える際に選択できる。
用途に応じて最適なモデルと設定を素早く切り替えることが可能になる。
設定ファイル関連
環境変数 OPENCODE_CONFIG
環境変数 OPENCODE_CONFIG は、カスタム設定ファイルのパスを指定する環境変数である。
デフォルトの設定ファイルパスではなく、任意のパスの設定ファイルを使用する場合に設定する。
# カスタム設定ファイルを指定する
export OPENCODE_CONFIG="/path/to/custom/opencode.json"
# 指定した設定ファイルでOpenCodeを起動する
opencode
CI/CD環境や複数の設定プロファイルを切り替えて使用する場合に有用である。
環境変数 OPENCODE_CONFIG_DIR
環境変数 OPENCODE_CONFIG_DIR は、OpenCodeの設定ディレクトリのパスを指定する環境変数である。
デフォルト値は ~/.config/opencodeディレクトリ である。
# カスタム設定ディレクトリを指定する
export OPENCODE_CONFIG_DIR="/path/to/custom/config"
opencode
複数のOpenCode環境を並行して使用する場合や、設定ディレクトリを標準的な場所以外に配置する場合に使用する。
環境変数 OPENCODE_CONFIG_CONTENT
環境変数 OPENCODE_CONFIG_CONTENT は、JSON文字列として設定内容を直接指定する環境変数である。
設定ファイルを配置できない環境や、CI/CDパイプラインで動的に設定を生成する場合に有用である。
# JSON文字列で設定を直接指定する
export OPENCODE_CONFIG_CONTENT='{"model": "anthropic/claude-sonnet-4-5"}'
opencode
この環境変数は設定の優先度において最も低い位置に位置するため、他の設定方法で上書きされることに注意する。
ネットワーク・プロキシ
OpenCodeをプロキシ環境下やカスタムエンドポイントで使用する場合は、以下の設定を行う。
# HTTPSプロキシの設定
export HTTPS_PROXY="http://proxy.example.com:8080"
export HTTP_PROXY="http://proxy.example.com:8080"
# プロキシを経由しないホストの設定
export NO_PROXY="localhost,127.0.0.1,.internal.example.com"
# 自己署名証明書を使用するプロキシ環境
export NODE_EXTRA_CA_CERTS="/path/to/ca-bundle.crt"
カスタムエンドポイントの設定は、opencode.jsonファイル の providers セクションの baseURL フィールドで行う。
{
"providers": {
"openai": {
"apiKey": "{env:OPENAI_API_KEY}",
"baseURL": "https://custom-endpoint.example.com/v1"
}
}
}
LSP関連
OpenCodeは言語サーバプロトコル (LSP) との統合をサポートしており、LSPサーバの動作を環境変数で制御できる。
| 環境変数 | 説明 |
|---|---|
OPENCODE_DISABLE_LSP_DOWNLOAD |
値を true に設定して、LSPサーバの自動ダウンロードを無効化する。 オフライン環境や、手動でLSPサーバを管理する場合に使用する。 |
OPENCODE_EXPERIMENTAL_LSP_TOOL |
値を true に設定して、実験的なLSPツールを有効化する。 この機能は実験的であり、予告なく変更または削除される可能性がある。 |
LSPサーバの個別設定は、opencode.jsonファイル の lsp セクションで行うこともできる。
{
"lsp": {
"typescript": {
"command": "typescript-language-server",
"args": ["--stdio"],
"env": {
"NODE_PATH": "/usr/local/lib/node_modules"
}
},
"python": {
"command": "pylsp",
"args": []
}
}
}
lsp セクションの env フィールドを使用することにより、LSPサーバごとに個別の環境変数を設定できる。
環境変数一覧
下表に、主要な環境変数のクイックリファレンスを示す。
| 環境変数 | カテゴリ | 説明 | デフォルト値 |
|---|---|---|---|
ANTHROPIC_API_KEY |
認証 | Anthropic Claude APIキー | - |
OPENAI_API_KEY |
認証 | OpenAI APIキー | - |
GEMINI_API_KEY |
認証 | Google Gemini APIキー | - |
GROQ_API_KEY |
認証 | Groq APIキー | - |
XAI_API_KEY |
認証 | X AI (Grok) APIキー | - |
GITHUB_TOKEN |
認証 | GitHub Copilot トークン | - |
OPENROUTER_API_KEY |
認証 | OpenRouter APIキー | - |
AWS_ACCESS_KEY_ID |
認証 | AWS アクセスキーID | - |
AWS_SECRET_ACCESS_KEY |
認証 | AWS シークレットアクセスキー | - |
AWS_REGION |
認証 | AWS リージョン | - |
AZURE_API_KEY |
認証 | Azure OpenAI APIキー | - |
AZURE_ENDPOINT |
認証 | Azure OpenAI エンドポイント | - |
OPENCODE_SERVER_PASSWORD |
認証 | HTTPサーバ基本認証パスワード | - |
OPENCODE_CONFIG |
設定ファイル | カスタム設定ファイルパス | - |
OPENCODE_CONFIG_DIR |
設定ファイル | カスタム設定ディレクトリパス | ~/.config/opencode |
OPENCODE_CONFIG_CONTENT |
設定ファイル | JSON文字列による直接設定 | - |
HTTPS_PROXY |
ネットワーク | HTTPSプロキシ | - |
HTTP_PROXY |
ネットワーク | HTTPプロキシ | - |
NO_PROXY |
ネットワーク | プロキシ除外ホスト | - |
NODE_EXTRA_CA_CERTS |
ネットワーク | CA証明書パス | - |
OPENCODE_DISABLE_LSP_DOWNLOAD |
LSP | LSPサーバ自動ダウンロード無効化 | - |
OPENCODE_EXPERIMENTAL_LSP_TOOL |
LSP | 実験的LSPツール有効化 | - |
ユースケース
複数プロバイダの併用
用途に応じて複数のLLMプロバイダを使い分けるための設定例を以下に示す。
# 複数プロバイダのAPIキーを設定する
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxx"
export OPENAI_API_KEY="sk-xxxxxxxxxxxx"
export GEMINI_API_KEY="AIzaXXXXXXXXXXXX"
{
"model": "anthropic/claude-sonnet-4-5",
"providers": {
"anthropic": {
"apiKey": "{env:ANTHROPIC_API_KEY}"
},
"openai": {
"apiKey": "{env:OPENAI_API_KEY}"
},
"google": {
"apiKey": "{env:GEMINI_API_KEY}"
}
}
}
CI/CD環境での設定
CI/CDパイプラインにおいて、OpenCodeを使用するための設定例を以下に示す。
# CI/CD環境変数として設定する
# (GitHub Actionsの場合は、secretsとして管理)
export ANTHROPIC_API_KEY="${{ secrets.ANTHROPIC_API_KEY }}"
# インライン設定でモデルを指定する
export OPENCODE_CONFIG_CONTENT='{"model": "anthropic/claude-haiku-4-5"}'
opencode --headless --prompt "コードをレビューしてください"
ローカルLLMの使用
Ollama等のローカルで動作するLLMサーバをOpenCodeから使用するための設定例を以下に示す。
{
"model": "ollama/llama3.2",
"providers": {
"ollama": {
"baseURL": "http://localhost:11434"
}
}
}
ローカルLLMを使用する場合はAPIキーの設定は不要であり、baseURL フィールドでローカルサーバのエンドポイントを指定する。
企業環境でのプロキシ設定
企業ネットワークでプロキシサーバを経由してOpenCodeを使用する場合の設定例を以下に示す。
# 企業プロキシ設定
export HTTPS_PROXY="http://proxy.corporate.com:8080"
export HTTP_PROXY="http://proxy.corporate.com:8080"
export NO_PROXY="localhost,127.0.0.1,.internal.corporate.com"
# 企業内の自己署名CA証明書の設定
export NODE_EXTRA_CA_CERTS="/etc/ssl/certs/corporate-ca-bundle.crt"
セキュリティ上の注意事項
- APIキーをシェルの履歴に記録されないよう注意する。
exportコマンドで設定する場合、シェル履歴にAPIキーが記録される可能性がある。- .envファイル を使用するか、シェルのヒストリ機能を一時的に無効化することを検討する。
- ~/.local/share/opencode/auth.jsonファイル のパーミッション管理を行う。
- このファイルには認証情報が含まれるため、適切なファイルパーミッション (600) を設定する。
- ソース管理 (Git) にAPIキーを含めない。
- .envファイル は必ず .gitignoreファイル に追加する。
- opencode.jsonファイル には
{env:変数名}形式を使用してAPIキーを直接記載しない。
- リモートURLは信頼できるもののみ使用する。
- opencode.jsonファイル の
instructionsフィールドで指定するリモートURLは、組織が管理するリポジトリのURLのみを使用する。
- opencode.jsonファイル の
- 本番環境では、環境変数
OPENCODE_SERVER_PASSWORDを必ず設定する。- OpenCodeをHTTPサーバモードで運用する場合は、基本認証を設定して不正アクセスを防ぐ。
参考リンク