進階設定（opencode.json）

摘要

opencode.json 是 OpenCode 的核心設定檔，控制從模型選擇、主題樣式、快捷鍵到自訂指令與代理的一切行為。本章詳細解析設定檔格式、位置優先順序、所有可用選項，以及實用的變數系統。

學習目標

• 理解設定檔格式（JSON/JSONC）與 Schema 驗證
• 掌握設定檔位置與載入優先順序
• 熟悉所有頂層 Schema 選項
• 學會使用變數系統（環境變數與檔案變數）
• 能夠建立完整的多環境設定

設定檔格式與 Schema 驗證

opencode.json 使用 JSON 或 JSONC（附註解版本）格式撰寫。OpenCode 支援完整的 JSON Schema 驗證，編輯時會自動提示可用選項與型別：

{
  // JSONC 支援註解（以 // 開頭）
  "$schema": "https://opencode.ai/schemas/opencode.json",
  "model": "claude-sonnet-4-20250514",
  "provider": "anthropic"
}

加入 $schema 欄位可以在支援的編輯器中獲得自動完成與驗證。

設定檔位置與優先順序

OpenCode 會依照以下順序載入設定，後載入的選項會覆蓋先前的值：

1. 遠端設定 — 透過 OpenCode 雲端同步的設定（最低優先）
2. 全域設定 — ~/.config/opencode/opencode.json
3. 自訂路徑 — --config CLI flag 指定的路徑
4. 專案設定 — 專案根目錄的 opencode.json
5. 巢狀設定 — .opencode/opencode.json（在子目錄中）
6. 內嵌設定 — AGENTS.md 中的 YAML frontmatter（最高優先）

這讓你可以建立「基底 + 專案覆蓋」的分層設定策略。

Schema 頂層選項

以下是 opencode.json 中可用的主要欄位：

TUI 與外觀

{
  "theme": "dark",           // 主題：dark, light, 或自訂主題名稱
  "locale": "zh-TW",         // 語言設定
  "font-size": 14,           // 字體大小
  "font-family": "Cascadia Code",
  "tab-size": 2              // 縮排寬度
}

模型與提供商

{
  "model": "claude-sonnet-4-20250514",
  "provider": "anthropic",
  "model-aliases": {         // 模型別名
    "fast": "claude-haiku-4",
    "smart": "claude-opus-4"
  },
  "providers": {             // 自訂提供商
    "ollama": {
      "baseURL": "http://localhost:11434"
    }
  }
}

伺服器與工具

{
  "mcp-servers": {           // MCP 伺服器設定
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  },
  "custom-tools": { ... },   // 自訂工具
  "formatters": { ... }      // 格式化器
}

指令與代理

{
  "commands": { ... },       // 自訂斜線指令
  "agents": { ... },         // 自訂代理
  "instructions": "...",     // 全域系統提示
  "permissions": {           // 權限管理
    "bash": "ask",
    "write": "allow",
    "read": "allow"
  }
}

壓縮與分享

{
  "compaction": {
    "enabled": true,         // 自動壓縮對話
    "threshold": 100000      // 超過此 token 數啟動壓縮
  },
  "share": {
    "enabled": true          // 啟用分享功能
  }
}

自動更新與進階

{
  "auto-update": true,       // 自動更新 OpenCode
  "telemetry": false,        // 遙測資料
  "keybindings": {           // 自訂快捷鍵
    "ctrl+k": "commands.clear"
  }
}

啟用 / 停用提供商

你可以選擇性的啟用或停用特定提供商：

{
  "providers": {
    "anthropic": { "enabled": true },
    "openai": { "enabled": true },
    "ollama": { "enabled": true },
    "google-vertex": { "enabled": false }  // 停用
  }
}

停用的提供商不會出現在模型選擇清單中，也無法被使用。

變數系統

OpenCode 支援強大的變數系統，避免在設定檔中硬編碼敏感資訊：

環境變數 {env:...}

{
  "providers": {
    "anthropic": {
      "apiKey": "{env:ANTHROPIC_API_KEY}"
    },
    "openai": {
      "apiKey": "{env:OPENAI_API_KEY}",
      "organization": "{env:OPENAI_ORG_ID}"
    }
  }
}

檔案變數 {file:...}

{
  "providers": {
    "custom": {
      "apiKey": "{file:~/.secrets/custom-key.txt}"
    }
  }
}

檔案變數會讀取指定檔案的第一行內容作為值。這對於與其他工具共用金鑰特別有用。

快速鍵與格式化器

自訂快捷鍵

{
  "keybindings": {
    "ctrl+p": "commands.search",
    "ctrl+shift+p": "commands.commandPalette",
    "alt+enter": "agents.switch",
    "ctrl+l": "panel.toggle"
  }
}

格式化器設定

{
  "formatters": {
    "python": {
      "command": "ruff",
      "args": ["format", "-"]
    },
    "typescript": {
      "command": "prettier",
      "args": ["--parser", "typescript"]
    },
    "go": {
      "command": "gofmt"
    }
  }
}

格式化器會在你使用 /format 或自動格式化功能時被呼叫。

實戰練習

{
  "model": "claude-sonnet-4-20250514",
  "provider": "anthropic",
  "theme": "dark",
  "locale": "zh-TW",
  "tab-size": 2
}

{
  "model-aliases": {
    "work": "claude-opus-4-20250514",
    "local": "llama3.1"
  },
  "providers": {
    "anthropic": {
      "apiKey": "{env:ANTHROPIC_API_KEY}",
      "enabled": true
    },
    "ollama": {
      "baseURL": "http://localhost:11434",
      "enabled": true
    }
  }
}

{
  "model": "claude-sonnet-4-20250514",
  "theme": "dark",
  "keybindings": {
    "ctrl+k": "commands.clear"
  },
  "formatters": {
    "javascript": { "command": "prettier", "args": ["--parser", "babel"] },
    "css": { "command": "prettier", "args": ["--parser", "css"] }
  },
  "mcp-servers": {
    "playwright": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-playwright"]
    }
  },
  "permissions": {
    "bash": "ask",
    "write": "allow",
    "read": "allow"
  }
}