前言

OpenCode 這個開源 AI Coding Agent 最近在 GitHub 上爆紅，星數已經突破 160K。但很多新手裝好之後就直接開始 opencode run，結果遇到各種問題：token 爆炸、模型選錯、工具亂開、MCP server 連不上……

其實 OpenCode 的設定檔 opencode.jsonc 提供了超多進階選項，只要設對，效能和體驗可以直接提升好幾個等級。

- 廣告 -

這篇文章我會整理 10 個最重要的設定項目，幫你一次搞定 OpenCode 的最佳化配置。

1. 設定 $schema 讓編輯器自動補完

很多人在寫 opencode.jsonc 的時候都沒有加 schema，結果編輯器無法提供自動補完和語法檢查。

{
  "$schema": "https://opencode.ai/config.json",
  // ... 你的設定
}

加上這行之後，VS Code 或其他支援 JSON Schema 的編輯器就能自動提示可用的設定項目，再也不怕打錯欄位名稱。

2. 用 model 和 small 分工，省 token 又快速

OpenCode 支援雙模型設定：model 負責主要編碼任務，small 負責輕量任務（像是自動產生對話標題、簡短摘要等）。

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

這樣設的好處是：

  • 主要任務用強大的模型，保證輸出品質
  • 輕量任務用便宜的模型，大幅節省 token 費用
  • 避免每個小操作都消耗昂貴模型的 token

如果你用的是 OpenRouter，可以這樣寫：

{
  "model": "openrouter/anthropic/claude-sonnet-4",
  "small": "openrouter/anthropic/claude-haiku-3-5"
}

3. 設定 timeout 和 chunktimeout，避免請求超時

當你用比較慢的模型或網路不穩的時候，OpenCode 可能會因為預設超時而中斷請求。建議根據你的模型供應商調整：

{
  "models": {
    "anthropic": {
      "timeout": 60000,
      "chunktimeout": 30000
    }
  }
}

這裡的數值單位是毫秒：

  • timeout：整個請求的超時時間（預設 30000ms = 30 秒）
  • chunktimeout：兩個回應 chunk 之間的最大等待時間，如果超過這個時間沒收到新資料，請求會被中斷

如果你用 Claude Sonnet 4 這種大模型，建議把 timeout 拉到 60000 以上，避免複雜任務被切斷。

4. 用 permission 控制工具權限，避免亂改檔案

OpenCode 的 permission 設定讓你能控制每個工具的行為模式。有三種選項："auto"（自動執行）、"ask"（每次詢問）、"deny"（禁止使用）。

{
  "permission": {
    "edit": "ask",
    "bash": "ask",
    "glob": "auto",
    "read": "auto",
    "web_fetch": "ask"
  }
}

推薦的設定策略：

  • 開發環境："ask" 或 "auto" 都可以，反正改壞了可以 undo
  • 生產環境："ask" 比較安全，避免誤改
  • CI/CD 環境：全部 "auto"，因為不需要人工介入

5. 啟用 MCP servers，擴充 OpenCode 能力

MCP（Model Context Protocol）是 OpenCode 的插件系統，讓你能連接外部工具和服务。

{
  "mcp": {
    "github": {
      "url": "https://github.com/modelcontextprotocol/servers/tree/main/src/github",
      "args": ["github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxx"
      }
    },
    "filesystem": {
      "url": "https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem",
      "args": ["/path/to/allowed/dir"]
    }
  }
}

常見的 MCP server 有：

  • GitHub：讀取 PR、issue、repo 資訊
  • filesystem：限制 OpenCode 可讀寫的目錄
  • PostgreSQL：直接查詢資料庫
  • Slack：發送訊息到頻道

6. 設定 tools 只開需要的，減少上下文開銷

OpenCode 預設會啟用所有工具，但這會增加模型的上下文負擔。建議只開啟你真正需要的：

{
  "tools": {
    "bash": { "enabled": true },
    "edit": { "enabled": true },
    "read": { "enabled": true },
    "glob": { "enabled": true },
    "web_fetch": { "enabled": true },
    "mcp": { "enabled": true }
  }
}

如果你主要在寫前端，可以关掉 mcp 和 web_fetch。如果你主要做後端，可以关掉 edit 和 glob。

7. 用 rules 和 instructions 統一團隊規範

OpenCode 支援透過 rules 和 instructions 設定全局規範，確保每次對話都遵循相同的程式碼風格和最佳實踐。

{
  "instructions": [
    "CONTRIBUTING.md",
    ".cursorrules",
    "docs/coding-standards.md"
  ]
}

你可以把團隊的程式碼規範、命名規則、測試要求等放在這些檔案裡，OpenCode 在每次對話時都會自動載入。

8. 設定 policies 控制 provider 存取權

如果你在公司環境使用 OpenCode，可以用 policies 限制某些 provider 的存取：

{
  "policies": [
    {
      "effect": "deny",
      "providers": ["openai"],
      "resource": "gpt-4"
    },
    {
      "effect": "allow",
      "providers": ["anthropic", "openrouter"]
    }
  ]
}

這能讓你的團隊統一使用指定的模型供應商，避免有人偷偷用其他 provider 產生額外費用。

9. 設定 compaction 和 snapshot，控制記憶體使用

OpenCode 會自動壓縮（compaction）對話上下文，避免 token 超出限制。你可以調整壓縮策略：

{
  "compaction": {
    "auto": true,
    "reserved": 10000
  },
  "snapshot": true
}
  • compaction.auto：是否自動壓縮上下文（預設 true）
  • compaction.reserved：壓縮時保留的 token 緩衝區大小
  • snapshot：是否啟用快照功能，讓你能 undo agent 的修改

對於大型專案，建議把 reserved 設大一點（15000-20000），避免壓縮時 token 溢出。

10. 用 watcher 忽略不需要的目錄，提升檔案監控效能

OpenCode 的檔案監控（file watcher）預設會追蹤整個專案的檔案變化。如果專案包含 node_modules、dist 等大量檔案，會拖慢效能。

{
  "watcher": {
    "ignore": [
      "node_modules/**",
      "dist/**",
      ".git/**",
      "vendor/**",
      "__pycache__/**"
    ]
  }
}

這些 glob 模式會從檔案監控中排除，大幅減少不必要的檔案讀取和事件觸發。

總結：完整的最佳化範例

把上面 10 個設定整合起來，你的 opencode.jsonc 應該長這樣：

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

  "model": "anthropic/claude-sonnet-4",
  "small": "anthropic/claude-haiku-3-5",

  "models": {
    "anthropic": {
      "timeout": 60000,
      "chunktimeout": 30000
    }
  },

  "permission": {
    "edit": "ask",
    "bash": "ask",
    "glob": "auto",
    "read": "auto",
    "web_fetch": "ask"
  },

  "mcp": {
    "github": {
      "url": "https://github.com/modelcontextprotocol/servers/tree/main/src/github",
      "args": ["github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxx"
      }
    }
  },

  "tools": {
    "bash": { "enabled": true },
    "edit": { "enabled": true },
    "read": { "enabled": true },
    "glob": { "enabled": true },
    "web_fetch": { "enabled": true },
    "mcp": { "enabled": true }
  },

  "instructions": [
    "CONTRIBUTING.md",
    ".cursorrules"
  ],

  "policies": [
    {
      "effect": "deny",
      "providers": ["openai"],
      "resource": "gpt-4"
    }
  ],

  "compaction": {
    "auto": true,
    "reserved": 15000
  },

  "snapshot": true,

  "watcher": {
    "ignore": [
      "node_modules/**",
      "dist/**",
      ".git/**",
      "vendor/**"
    ]
  }
}

結語

OpenCode 的設定檔雖然看起來複雜，但只要掌握上面這 10 個核心設定，就能大幅提升使用體驗。記住一個原則：越精確的設定，越好的效能。

如果你有其他好用的設定技巧，歡迎在評論區分享！

- 廣告 -