第3章：設定與組態入門

3.1 設定檔概覽

OpenCode 的設定集中於 opencode.json 這個檔案。它採用標準 JSON 格式，包含一個 $schema 欄位以提供編輯器自動補全與驗證支援。

多層級設定優先順序

OpenCode 的設定採用三層級結構，從高到低依次為：

當多個層級同時存在時，專案層級會覆蓋遠端層級，遠端層級會覆蓋全域層級。這種設計讓你可以將通用設定放在全域，而為每個專案保留彈性調整的空間。

3.2 opencode.json 完整範例

以下是一個完整的 opencode.json 設定檔，展示了常用的設定項目：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4",
  "permission": {
    "*": "ask",
    "bash": "allow",
    "read": "allow",
    "write": "ask"
  },
  "theme": "dark",
  "keybind": {
    "toggleTheme": "ctrl+t",
    "openPanel": "ctrl+p",
    "newSession": "ctrl+n"
  },
  "editor": {
    "default": "code",
    "wrap": 80
  },
  "variables": {
    "API_KEY": "$ENV_API_KEY",
    "PROJECT_ROOT": ".project-root"
  }
}

各欄位說明

3.3 權限系統

OpenCode 的權限系統讓你可以精細控制 AI 代理能夠執行的操作。每個工具可以設定三種權限等級：

在設定中使用萬用字元 * 來設定全域預設值：

{
  "permission": {
    "*": "ask",      // 所有工具預設為詢問
    "read": "allow",  // 讀取檔案自動允許
    "bash": "allow",  // Shell 命令自動允許
    "write": "ask"    // 寫入檔案需要確認
  }
}

3.4 變數系統

OpenCode 支援在設定檔中使用變數，讓你可以動態參考環境變數或檔案內容：

{
  "variables": {
    "OPENAI_KEY": "$ENV_OPENAI_API_KEY",
    "PROJECT_NAME": ".project-name"
  }
}

變數參考有兩種形式：

• $ENV_ 前綴 — 參考環境變數，例如 $ENV_OPENAI_API_KEY 會讀取 OPENAI_API_KEY 環境變數的值
• 一般文字 — 參考檔案路徑（相對於專案根目錄），OpenCode 會讀取該檔案的內容作為值

變數可以在 opencode.json 的任何欄位中使用 ${變數名稱} 語法來引用：

{
  "variables": {
    "MY_KEY": "$ENV_MY_SECRET_KEY"
  },
  "model": "openai/gpt-5.2",
  // 在其他欄位中引用變數（語法範例）
  "custom_header": "${MY_KEY}"
}

3.5 AGENTS.md：專案自訂指令

如果說 opencode.json 是 OpenCode 的「系統設定」，那麼 AGENTS.md 就是它的「行為指南」。這個 Markdown 檔案位於專案根目錄，用來告訴 OpenCode 你的專案慣例、技術選擇與開發偏好。

你可以透過 /init 指令快速產生 AGENTS.md：

產生的 AGENTS.md 內容範例如下：

# my-api-service

## 技術棧
- 語言：TypeScript
- 執行環境：Node.js 22
- 測試：Vitest
- 程式碼風格：Prettier + ESLint + Biome

## 開發慣例
- 使用 pnpm 管理相依套件
- 所有新增功能需附單元測試
- API 路由集中在 src/routes/ 目錄下
- 錯誤處理統一使用 AppError 類別

## 注意事項
- 不要修改 src/types/ 下的自動產生檔案
- 資料庫遷移檔案位於 migrations/ 目錄

3.6 設定管理實用指令

OpenCode 提供了幾個方便管理設定的指令：

章節測驗

測試你對本章內容的理解程度：

常見問題