OpenCode 設定ファイル

OpenCode は JSON 形式を使用して設定します。

まずグローバル設定ファイルを見てみましょう~/.config/opencode/opencode.json：

touch ~/.config/opencode/opencode.json

モデルプロバイダーと設定情報が含まれています：

{
  // JSON Schema（用于编辑器校验和自动补全）
  "$schema": "https://opencode.ai/config.json",

  "provider": {
    // 自定义 Provider 名称（使用时：deepseek/xxx）
    "deepseek": {

      // 使用 OpenAI 兼容适配器（适用于 DeepSeek 这类兼容接口）
      "npm": "@ai-sdk/openai-compatible",

      "options": {
        // API 基础地址（必须是 OpenAI 兼容格式）
        "baseURL": "https://api.deepseek.com/v1",

        // API Key
        "apiKey": "sk-xxxx",

        // 是否强制设置缓存 key（提升缓存命中率，降低成本）
        "setCacheKey": true
      },

      "models": {
        // 本地模型别名（CLI/TUI 中使用：deepseek/Deepseek-v4）
        "Deepseek-v4": {
          // 实际调用的模型名称（API 层）
          "name": "deepseek-v4-pro"
        }
      }
    }
  }
}

最小限の動作可能な設定例

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
  "theme": "default"
}

一般的なグローバル設定項目：

設定項目 型 説明
model string デフォルトのメインモデル
small_model string 軽量タスク用モデル（例：タイトル生成）
autoupdate boolean / "notify" 自動更新ポリシー
theme string UIテーマ
provider object モデルプロバイダー設定

プロバイダー例:

{
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "setCacheKey": true
      }
    }
  }
}

設定の「マージメカニズム」を理解する

OpenCode の設定は上書きではなく、階層的なマージ。

読み込み順序（低→高）
順序 ソース 説明
1 リモート.well-known/opencode 組織のデフォルト設定
2 グローバル設定 ~/.config/opencode/opencode.json
3 カスタムパス OPENCODE_CONFIG
4 プロジェクト設定 プロジェクト内のopencode.json
5 .opencode/ディレクトリ 拡張機能
6 インライン設定 OPENCODE_CONFIG_CONTENT

マージルール

  • 競合しないフィールド：すべて保持
  • 競合するフィールド：後者が前者を上書き

例

グローバル設定：

{
  "autoupdate": true
}

プロジェクト設定：

{
  "model": "anthropic/claude-sonnet-4-5"
}

最終結果：

{
  "autoupdate": true,
  "model": "anthropic/claude-sonnet-4-5"
}

プロジェクト設定

プロジェクトのルートディレクトリに作成：

opencode.json

機能：

  • プロジェクト固有のAI動作を定義
  • Gitにコミット可能
  • グローバル設定を上書き

例：プロジェクトレベルの設定 
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "tools": {
    "write": true,
    "bash": true
  }
}

コア設定モジュールの詳細

{
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

モデルとプロバイダー

{
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}
フィールド 説明
model メインタスクモデル
small_model 低コストタスクモデル

ツール制御

{
  "tools": {
    "write": false,
    "bash": false
  }
}
ツール 機能
write ファイル書き込み
bash コマンド実行

これはセキュリティ制御の第一層。

権限制御

{
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}
值 意味
allow 自動実行
ask 毎回確認
deny 禁止

エージェント（中核機能）

{
  "agent": {
    "code-reviewer": {
      "description": "代码审查",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer",
      "tools": {
        "write": false
      }
    }
  }
}

本質：AIに役割 + 能力範囲を定義する

コマンド（自動化プロンプト）

{
  "command": {
    "test": {
      "template": "Run tests and fix failures",
      "description": "运行测试"
    }
  }
}

本質：プロンプトテンプレートシステム

TUI設定

{
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    },
    "diff_style": "auto"
  }
}

サーバー設定（API / Web）

{
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true
  }
}

コンテキスト圧縮（トークン最適化）

{
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  }
}

プラグインシステム

{
  "plugin": [
    "opencode-helicone-session",
    "@my-org/custom-plugin"
  ]
}

MCP（拡張エコシステム）

{
  "mcp": {}
}

外部ツール（Jira、データベースなど）を接続するために使用

命令システム（AIルール）

{
  "instructions": [
    "CONTRIBUTING.md",
    "docs/*.md"
  ]
}

プロバイダー制御

{
  "enabled_providers": ["anthropic"],
  "disabled_providers": ["openai"]
}

優先順位：

disabled > enabled

変数システム

環境変数：

{
  "model": "{env:OPENCODE_MODEL}"
}

ファイル参照

{
  "apiKey": "{file:~/.secrets/key}"
}

ディレクトリ拡張メカニズム

OpenCode は JSON 設定だけでなく、ディレクトリ拡張もサポートしています：

.opencode/
├── agents/
├── commands/
├── plugins/
├── tools/
├── themes/

機能：

  • Markdownでエージェントを定義
  • ファイルレベルのコマンド
  • プラグイン拡張

おすすめの入門設定

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "autoupdate": "notify",
  "tools": {
    "write": true,
    "bash": true
  },
  "permission": {
    "bash": "ask"
  },
  "compaction": {
    "auto": true,
    "prune": true
  }
}

まとめ（アーキテクチャの視点）

OpenCode の設定は4層構造として理解できます：

配置层（多级 merge）
    ↓
能力层（agent / tools / mcp）
    ↓
执行层（model / provider）
    ↓
交互层（tui / server / web）

本質的には、これは単純な設定ファイルではなく、次のようなものです：

プログラマブルAIエージェントOSの設定センター

その他の拡張