配置 OpenCode

OpenCode 使用 JSON 或 JSONC（JSON with Comments，比標準 JSON 多了 // 行註釋和尾隨逗號支援，除錯團隊配置時方便很多）配置。新手不需要先複製完整官方示例，先理解配置檔案如何合併、哪個位置適合放什麼、哪些設定不該一開始就改。

先給結論：配置越少，越容易排錯

OpenCode 配置的目標是讓行為可預測，不是把所有能力一次性開啟。第一次只需要讓 provider、模型和專案規則可用；server、tools、provider options、MCP、formatter、Agent、Plugin 都應該按需要逐步加。

flowchart LR
  Connect["/connect 儲存憑據"] --> Models["/models 確認可用模型"]
  Models --> Global["全域性配置：個人偏好"]
  Models --> Project["專案配置：團隊共享預設值"]
  Project --> Validate["Schema / 型別檢查"]
  Validate --> Minimal["出錯時回到最小配置重測"]

  style Connect fill:#dbeafe,stroke:#3b82f6
  style Project fill:#dcfce7,stroke:#22c55e,stroke-width:2px
  style Minimal fill:#fee2e2,stroke:#ef4444

配置是合併，不是隻讀一個檔案

OpenCode 的配置不是簡單替換，而是多層合併。後載入的配置在鍵衝突時覆蓋前面的配置，非衝突設定會保留。

這意味著：你在全域性配置裡設定主題，在專案配置裡設定模型，最終兩者都會生效。排錯時不要只看一個檔案，要看所有配置來源。

載入優先順序怎麼記

官方配置會從多個來源載入，後面的來源優先順序更高：

1. 遠端組織配置（透過 .well-known/opencode 端點）。
2. 全域性配置（~/.config/opencode/opencode.json）。
3. OPENCODE_CONFIG 指定的自定義配置。
4. 專案根目錄 opencode.json。
5. .opencode 目錄裡的 agents、commands、plugins 等結構化擴充套件。
6. OPENCODE_CONFIG_CONTENT 內聯配置。
7. 託管配置檔案（macOS /Library/Application Support/opencode/、Linux /etc/opencode/、Windows %ProgramData%\opencode）——管理員級別，需 root/admin 許可權寫入。
8. macOS 託管偏好（透過 MDM 推送的 .mobileconfig）——優先順序最高，使用者無法覆蓋。

新手最常用的是全域性配置和專案配置，其他入口先不要碰。OPENCODE_CONFIG_CONTENT 這類內聯覆蓋適合臨時或自動化場景，不適合長期靠記憶維護。最後兩層（託管配置 + MDM）一般只在企業部署裡出現：如果你發現某些設定改不動，先用 opencode debug config 看實際生效值，確認是不是被託管配置接管了。

新手應該把配置放哪裡

如果一個設定只服務你自己，放全域性；如果團隊成員都應該遵守，放專案；如果只是臨時試驗，用環境變數，試完清理。

最小配置策略

第一次配置只需要解決一個問題：讓 OpenCode 在當前專案裡可控可用。

優先順序：

1. 透過 /connect 配 provider 憑據。
2. 用 /models 確認模型可用。
3. 只在需要時寫預設 model。
4. 只在團隊需要共享時寫專案 opencode.json。
5. 使用 schema 做校驗。

不要為了“完整”一次性配置 TUI、server、tools、provider、theme、agent、MCP、formatter。改得越多，排錯越難。

tools 和 server 先保守

tools 會影響 Agent 能做什麼，例如是否能寫檔案、執行 bash、訪問外部工具。server 會影響 opencode serve 和 opencode web 的網路暴露方式。

新手原則：

• 不需要 Web 或遠端訪問，就不要改 server。
• 不理解風險前，不要放寬 tools。
• 需要瀏覽器客戶端訪問 server 時，才考慮 CORS（跨源資源共享白名單）。
• 共享配置裡不要寫只適合你本機的埠和 hostname。
• 如果要繫結 0.0.0.0，先處理認證和網路邊界。

配置排錯順序

配置出問題時，先回到最小可用狀態：

确认 /connect 凭据
  ↓
确认 /models 能看到模型
  ↓
临时移除项目级复杂配置
  ↓
检查环境变量覆盖
  ↓
再逐项恢复 server / tools / provider options

不要一邊改 provider、一邊改 tools、一邊改 server。一次只改一個變數，才能知道問題是誰引入的。

新手常見坑

• 全量複製官方 config 示例。
• 不知道配置會合並，誤判某個舊設定已經失效。
• 把專案配置當個人配置用。
• 用環境變數覆蓋後忘記清理。
• 不看 schema 提示，靠試錯改 JSON。
• 一次改很多項，無法定位問題。

怎麼判斷配置健康

健康標準：

• 全域性配置和專案配置職責分開。
• 專案 opencode.json 可以提交給團隊。
• 本機私有資訊沒有進儲存庫。
• 當前模型、tools 和 instructions 來源可解釋。
• 配置能透過 schema 校驗。
• 出問題時可以回到最小配置重測。

接下來去哪

官方資料

• OpenCode Config：https://opencode.ai/docs/config
• OpenCode Models：https://opencode.ai/docs/models
• OpenCode Tools：https://opencode.ai/docs/tools
• OpenCode Server：https://opencode.ai/docs/server