日本語
ドキュメント
設定

設定

OpenCode JSON 設定の使用方法。

JSON 設定ファイルを使用して OpenCode を設定できます。

フォーマット

OpenCode は JSON と JSONC（コメント付き JSON）の両方の形式をサポートしています。

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  // テーマ設定
  "theme": "opencode",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true
}

場所

設定ファイルはいくつかの異なる場所に配置でき、それぞれ異なる優先順位があります。

注意： 設定ファイルは置き換えではなくマージされます。

設定ファイルは置き換えではなくマージされます。以下の設定場所からの設定が組み合わされます。後の設定は競合するキーのみを上書きします。すべての設定からの競合しない設定は保持されます。

例えば、グローバル設定で theme: "opencode" と autoupdate: true を設定し、プロジェクト設定で model: "anthropic/claude-sonnet-4-5" を設定した場合、最終的な設定には 3 つすべての設定が含まれます。

優先順位

設定ソースは以下の順序で読み込まれます（後のソースが前のソースを上書き）：

  • リモート設定（.well-known/opencode から）- 組織のデフォルト
  • グローバル設定（~/.config/opencode/opencode.json）- ユーザー設定
  • カスタム設定（OPENCODE_CONFIG 環境変数）- カスタムオーバーライド
  • プロジェクト設定（プロジェクト内の opencode.json）- プロジェクト固有の設定
  • .opencode ディレクトリ - エージェント、コマンド、プラグイン
  • インライン設定（OPENCODE_CONFIG_CONTENT 環境変数）- ランタイムオーバーライド

これは、プロジェクト設定がグローバルデフォルトを上書きでき、グローバル設定がリモート組織デフォルトを上書きできることを意味します。

注意： .opencode と ~/.config/opencode ディレクトリのサブディレクトリは複数形の名前を使用します：agents/、commands/、modes/、plugins/、skills/、tools/、themes/。後方互換性のため、単数形の名前（例：agent/）もサポートされています。

リモート

組織は .well-known/opencode エンドポイントを通じてデフォルト設定を提供できます。これをサポートするプロバイダーで認証すると自動的に取得されます。

リモート設定は最初に読み込まれ、ベースレイヤーとして機能します。他のすべての設定ソース（グローバル、プロジェクト）はこれらのデフォルトを上書きできます。

例えば、組織がデフォルトで無効な MCP サーバーを提供している場合：

.well-known/opencode からのリモート設定
{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": false
    }
  }
}

ローカル設定で特定のサーバーを有効にできます：

opencode.json
{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

グローバル

グローバル OpenCode 設定を ~/.config/opencode/opencode.json に配置します。テーマ、プロバイダー、キーバインドなどのユーザー全体の設定にグローバル設定を使用します。

グローバル設定はリモート組織デフォルトを上書きします。

プロジェクト単位

プロジェクトルートに opencode.json を追加します。プロジェクト設定は標準設定ファイルの中で最も高い優先順位を持ちます - グローバルとリモート設定の両方を上書きします。

ヒント： プロジェクト固有の設定はプロジェクトルートに配置してください。

OpenCode が起動すると、現在のディレクトリで設定ファイルを探すか、最も近い Git ディレクトリまで上方向に探索します。

これは Git にコミットしても安全で、グローバル設定と同じスキーマを使用します。

カスタムパス

OPENCODE_CONFIG 環境変数を使用してカスタム設定ファイルパスを指定します。

export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"

カスタム設定は優先順位でグローバル設定とプロジェクト設定の間に読み込まれます。

カスタムディレクトリ

OPENCODE_CONFIG_DIR 環境変数を使用してカスタム設定ディレクトリを指定します。このディレクトリは標準の .opencode ディレクトリと同様にエージェント、コマンド、モード、プラグインを検索し、同じ構造に従う必要があります。

export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"

カスタムディレクトリはグローバル設定と .opencode ディレクトリの後に読み込まれるため、それらの設定を上書きできます。

スキーマ

設定ファイルには opencode.ai/config.json (opens in a new tab) で定義されたスキーマがあります。

エディターはスキーマに基づいて検証とオートコンプリートができるはずです。

TUI

tui オプションを通じて TUI 固有の設定を構成できます。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    },
    "diff_style": "auto"
  }
}

利用可能なオプション：

  • scroll_acceleration.enabled - macOS スタイルのスクロール加速を有効にします。scroll_speed より優先されます。
  • scroll_speed - カスタムスクロール速度倍率（デフォルト：3、最小：1）。scroll_acceleration.enabled が true の場合は無視されます。
  • diff_style - diff レンダリングを制御します。"auto" はターミナル幅に適応し、"stacked" は常に単一列を表示します。

TUI の使用方法についてはこちら。

サーバー

server オプションを通じて opencode serve と opencode web コマンドのサーバー設定を構成できます。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}

利用可能なオプション：

  • port - リッスンするポート。
  • hostname - リッスンするホスト名。mdns が有効でホスト名が設定されていない場合、デフォルトは 0.0.0.0。
  • mdns - mDNS サービスディスカバリを有効にします。これにより、ネットワーク上の他のデバイスが OpenCode サーバーを発見できます。
  • mdnsDomain - mDNS サービスのカスタムドメイン名。デフォルトは opencode.local。同じネットワーク上で複数のインスタンスを実行する場合に便利です。
  • cors - ブラウザベースのクライアントから HTTP サーバーを使用する際に許可する追加の CORS オリジン。値は完全なオリジン（スキーム + ホスト + オプションのポート）である必要があります。例：https://app.example.com。

サーバーについてはこちら。

ツール

tools オプションを通じて LLM が使用できるツールを管理できます。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": false,
    "bash": false
  }
}

ツールについてはこちら。

モデル

provider、model、small_model オプションを通じて OpenCode 設定で使用するプロバイダーとモデルを構成できます。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {},
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

small_model オプションはタイトル生成などの軽量タスク用に別のモデルを設定します。デフォルトでは、プロバイダーからより安価なモデルが利用可能な場合は OpenCode がそれを使用しようとし、そうでなければメインモデルにフォールバックします。

プロバイダーオプションには timeout と setCacheKey を含めることができます：

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "setCacheKey": true
      }
    }
  }
}
  • timeout - リクエストタイムアウト（ミリ秒）（デフォルト：300000）。無効にするには false に設定。
  • setCacheKey - 指定されたプロバイダーに対して常にキャッシュキーが設定されるようにします。

ローカルモデルも設定できます。詳細はこちら。

プロバイダー固有のオプション

一部のプロバイダーは、汎用の timeout と apiKey 設定以外の追加設定オプションをサポートしています。

Amazon Bedrock

Amazon Bedrock は AWS 固有の設定をサポートしています：

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": {
      "options": {
        "region": "us-east-1",
        "profile": "my-aws-profile",
        "endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
      }
    }
  }
}
  • region - Bedrock の AWS リージョン（デフォルトは AWS_REGION 環境変数または us-east-1）
  • profile - ~/.aws/credentials からの AWS 名前付きプロファイル（デフォルトは AWS_PROFILE 環境変数）
  • endpoint - VPC エンドポイント用のカスタムエンドポイント URL。これは AWS 固有の用語を使用した汎用 baseURL オプションのエイリアスです。両方が指定された場合、endpoint が優先されます。

注意： Bearer トークン（AWS_BEARER_TOKEN_BEDROCK または /connect）はプロファイルベースの認証より優先されます。詳細は認証の優先順位を参照してください。

Amazon Bedrock 設定についてはこちら。

テーマ

theme オプションを通じて OpenCode 設定で使用するテーマを構成できます。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "theme": ""
}

詳細はこちら。

エージェント

agent オプションを通じて特定のタスク用の専門エージェントを構成できます。

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        // レビュー専用エージェントのファイル変更ツールを無効化
        "write": false,
        "edit": false
      }
    }
  }
}

~/.config/opencode/agents/ または .opencode/agents/ で markdown ファイルを使用してエージェントを定義することもできます。詳細はこちら。

デフォルトエージェント

default_agent オプションを使用してデフォルトエージェントを設定できます。これは明示的に指定されていない場合に使用されるエージェントを決定します。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "plan"
}

デフォルトエージェントはプライマリエージェント（サブエージェントではない）である必要があります。これは "build" や "plan" などの組み込みエージェント、または定義したカスタムエージェントにできます。指定されたエージェントが存在しないかサブエージェントの場合、OpenCode は警告とともに "build" にフォールバックします。

この設定はすべてのインターフェースに適用されます：TUI、CLI（opencode run）、デスクトップアプリ、GitHub Action。

共有

share オプションを通じて共有機能を構成できます。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "share": "manual"
}

以下の値を取ります：

  • "manual" - コマンドによる手動共有を許可（デフォルト）
  • "auto" - 新しい会話を自動的に共有
  • "disabled" - 共有を完全に無効化

デフォルトでは、共有は手動モードに設定されており、/share コマンドを使用して明示的に会話を共有する必要があります。

コマンド

command オプションを通じて繰り返しタスク用のカスタムコマンドを構成できます。

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Create a new component"
    }
  }
}

~/.config/opencode/commands/ または .opencode/commands/ で markdown ファイルを使用してコマンドを定義することもできます。詳細はこちら。

キーバインド

keybinds オプションを通じてキーバインドをカスタマイズできます。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "keybinds": {}
}

詳細はこちら。

自動更新

OpenCode は起動時に新しい更新を自動的にダウンロードします。autoupdate オプションでこれを無効にできます。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "autoupdate": false
}

更新は不要だが新しいバージョンが利用可能になったときに通知を受けたい場合は、autoupdate を "notify" に設定します。これは Homebrew などのパッケージマネージャーを使用してインストールされていない場合にのみ機能することに注意してください。

フォーマッター

formatter オプションを通じてコードフォーマッターを構成できます。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": true
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

フォーマッターについてはこちら。

権限

デフォルトでは、opencode は明示的な承認なしにすべての操作を許可します。permission オプションを使用してこれを変更できます。

例えば、edit と bash ツールにユーザー承認を必要とするには：

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

権限についてはこちら。

圧縮

compaction オプションを通じてコンテキスト圧縮の動作を制御できます。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": true
  }
}
  • auto - コンテキストがいっぱいになったときにセッションを自動的に圧縮（デフォルト：true）。
  • prune - トークンを節約するために古いツール出力を削除（デフォルト：true）。

ウォッチャー

watcher オプションを通じてファイルウォッチャーの無視パターンを構成できます。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

パターンは glob 構文に従います。ファイル監視からノイズの多いディレクトリを除外するために使用します。

MCP サーバー

mcp オプションを通じて使用する MCP サーバーを構成できます。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {}
}

詳細はこちら。

プラグイン

プラグインはカスタムツール、フック、統合で OpenCode を拡張します。

プラグインファイルを .opencode/plugins/ または ~/.config/opencode/plugins/ に配置します。plugin オプションを通じて npm からプラグインを読み込むこともできます。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

詳細はこちら。

指示

instructions オプションを通じて使用するモデルの指示を構成できます。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

これは指示ファイルへのパスと glob パターンの配列を取ります。ルールについてはこちら。

無効化されたプロバイダー

disabled_providers オプションを通じて自動的に読み込まれるプロバイダーを無効にできます。これは、資格情報が利用可能であっても特定のプロバイダーが読み込まれないようにしたい場合に便利です。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": ["openai", "gemini"]
}

注意： disabled_providers は enabled_providers より優先されます。

disabled_providers オプションはプロバイダー ID の配列を受け入れます。プロバイダーが無効になると：

  • 環境変数が設定されていても読み込まれません。
  • /connect コマンドで API キーが設定されていても読み込まれません。
  • プロバイダーのモデルはモデル選択リストに表示されません。

有効化されたプロバイダー

enabled_providers オプションを通じてプロバイダーの許可リストを指定できます。設定すると、指定されたプロバイダーのみが有効になり、他のすべては無視されます。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "enabled_providers": ["anthropic", "openai"]
}

これは、プロバイダーを 1 つずつ無効にするのではなく、OpenCode を特定のプロバイダーのみに制限したい場合に便利です。

注意： disabled_providers は enabled_providers より優先されます。

プロバイダーが enabled_providers と disabled_providers の両方に表示される場合、後方互換性のために disabled_providers が優先されます。

実験的

experimental キーには活発に開発中のオプションが含まれています。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {}
}

注意： 実験的オプションは安定していません。予告なく変更または削除される可能性があります。

変数

設定ファイルで変数置換を使用して、環境変数とファイル内容を参照できます。

環境変数

{env:VARIABLE_NAME} を使用して環境変数を置換します：

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "models": {},
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

環境変数が設定されていない場合、空の文字列に置き換えられます。

ファイル

{file:path/to/file} を使用してファイルの内容を置換します：

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["./custom-instructions.md"],
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

ファイルパスは以下のいずれかです：

  • 設定ファイルディレクトリからの相対パス
  • / または ~ で始まる絶対パス

これらは以下の場合に便利です：

  • API キーなどの機密データを別のファイルに保存する。
  • 設定を乱雑にせずに大きな指示ファイルを含める。
  • 複数の設定ファイル間で共通の設定スニペットを共有する。
はじめにプロバイダー