OpenCodeの設定 - 環境変数

提供: MochiuWiki : SUSE, EC, PCB

概要

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サーバごとに個別の環境変数を設定できる。


環境変数一覧

下表に、主要な環境変数のクイックリファレンスを示す。

OpenCode 環境変数一覧
環境変数 カテゴリ 説明 デフォルト値
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_SERVER_PASSWORD を必ず設定する。
    OpenCodeをHTTPサーバモードで運用する場合は、基本認証を設定して不正アクセスを防ぐ。



参考リンク



「https://mochiu.net/index.php?title=OpenCodeの設定_-_環境変数&oldid=14370」から取得