OpenCodeのモデル変更が反映されない｜default_agentの確認手順

OpenCodeの設定で model を書き換えたのに、画面に出るモデル名が変わらない。そんなとき、同じ設定ファイルを何度も直しても解決しないことがあります。

原因になりやすいのが、default_agent に指定したagent側のモデル設定です。グローバルの既定値が正しく読み込まれていても、agentに別の model があれば、選択中のagentではそちらが使われます。

最初に見るのは設定ファイルではなく、OpenCodeが解決したあとの値です。

この記事では、opencode debug config と opencode debug agent を使い、上書き元を切り分ける順番を整理します。掲載しているagent名、パス、モデルID、出力値は、すべて説明用に置き換えた例です。

グローバルを変えても表示が変わらない理由

たとえば、グローバル設定が次の状態だったとします。

// ~/.config/opencode/opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "model": "provider/global-model",
  "default_agent": "custom-agent"
}

一方、プロジェクト内のagent定義には別のモデルがあります。

# <project-root>/.opencode/agents/custom-agent.md
---
model: provider/agent-model
variant: example-variant
mode: primary
---

この場合、グローバル設定の provider/global-model は消えていません。custom-agent を使う場面だけ、agent固有の provider/agent-model が選ばれます。

設定を直す前に「解決後の値」を見る

確認は、問題が起きるプロジェクトのディレクトリで行います。起動場所が違うと、読み込まれる opencode.jsonc や .opencode も変わるためです。

cd <project-root>
opencode --version

全体は opencode debug config で確認する

まず、グローバル設定とプロジェクト設定を読み込んだ結果を確認します。

opencode debug config

出力全体は長いため、見る場所はルートの model、default_agent、対象agentの model の3点に絞ります。

{
  "model": "provider/global-model",
  "default_agent": "custom-agent",
  "agent": {
    "custom-agent": {
      "model": "provider/agent-model",
      "variant": "example-variant"
    }
  }
}

ここでルートとagentに別々のモデルが出ていれば、グローバル設定が無視されたわけではありません。全体の既定値に、agent固有の値が追加されています。

選択中agentは opencode debug agent で確認する

次に、default_agent に表示された名前を指定します。

opencode debug agent custom-agent

確認するのは model.providerID、model.modelID、variant です。

{
  "name": "custom-agent",
  "mode": "primary",
  "model": {
    "providerID": "provider",
    "modelID": "agent-model"
  },
  "variant": "example-variant"
}

modelID が画面の表示と一致していれば、上書き元はグローバル設定ではなくagent定義です。

設定は置き換えではなくマージされる

OpenCodeの設定は、複数の場所から読み込まれて組み合わされます。競合するキーは優先度の高い設定が上書きしますが、競合しない値はそのまま残ります。

今回の切り分けで見る場所は次の3つです。

1. グローバル設定 ~/.config/opencode/opencode.jsonc
2. プロジェクト直下の opencode.jsonc
3. プロジェクトの .opencode/agents/*.md

agentに model が指定されている場合、その値はagent用の上書きとして使われます。primary agentにモデル指定がなければグローバルのモデルを使うため、agent定義の有無で結果が変わります。

ルートの model と、選択中agentの model は別の設定として確認します。

直す場所は変更したい範囲で決める

原因が分かっても、複数の設定ファイルをまとめて書き換える必要はありません。変更したい範囲に合わせて、触る場所を一つに絞ります。

すべてのプロジェクトの既定値を変える

グローバル設定の model を変更します。ただし、個別agentに model がある場合は、agent側の指定が引き続き使われます。

特定のagentだけ変える

プロジェクト内の .opencode/agents/<agent-name>.md を変更します。他のagentやプロジェクトに影響を広げずに済みます。

---
model: <provider>/<available-model-id>
variant: <available-variant>
mode: primary
---

モデルIDやvariantは推測せず、現在のモデル一覧で確認します。変更後は同じagentに対して opencode debug agent <agent-name> を実行し、期待する値になったことを確かめます。

agentにグローバル設定を継承させる

agent固有のモデル固定が不要なら、agent定義から model を外す方法があります。ただし、その指定が互換性やコスト管理のために置かれている場合もあります。

理由を確認せず、複数のagentファイルから model を一括削除しないでください。一つだけ変更し、解決結果と実際の起動を確認します。

変更後は新しいセッションで確認する

設定変更後は、次の順番で確認します。

1. opencode debug config でルートのモデルと default_agent を確認
2. opencode debug agent <agent-name> でagentの実値を確認
3. 上書き元を1か所だけ変更
4. 新しいセッションまたはOpenCode再起動後に、同じ2コマンドで再確認

既存セッションで手動選択したモデルと、新規セッションの既定値は分けて見ます。設定変更後も既存セッションだけを見ていると、セッション側の選択なのか、設定の上書きなのかを判断しにくくなります。

まだ変わらないときに見る4点

起動したフォルダが違わないか

Windows、WSL、Desktop版、別のターミナルで作業フォルダが違うと、参照するプロジェクト設定も変わります。pwd または Get-Location で現在地を確認します。

--model または -m を付けていないか

起動時にモデルを明示していると、通常の既定値とは別の結果になります。ショートカットや起動スクリプトに引数が残っていないかも確認します。

default_agent が想定どおりか

別のprimary agentが選ばれていれば、修正したagentのモデルは画面へ反映されません。debug config の default_agent と、画面で選択中のagent名を照らし合わせます。

モデルIDとvariantを利用できるか

モデル名は記事の例から決めず、現在のモデル一覧に出るIDを使います。プロバイダー、認証方法、OpenCodeのバージョンによって、選べるモデルやvariantは変わります。

最短の確認手順

モデル表示が想定と違うときは、設定ファイルを探し回る前に次の2コマンドを実行します。

opencode debug config
opencode debug agent <default_agentの名前>

「全体の既定値」と「選択中agentの実値」を分けて見る。この2点が分かれば、上書き元と変更範囲を判断できます。

参考にした公式情報

• OpenCode CLI
• OpenCode Config
• OpenCode Agents
• OpenCode Models