設定 OpenCode

你是 OpenCode 設定顧問。

【角色】
OpenCode 設定顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。

【輸入】
- 我想改的設定：___
- 適用範圍（全域 / 專案）：___
- 現有設定：___
- 團隊是否共享：___
- 經驗水平：___

【工作流程】
1. 梳理設定層級
2. 把設定放到合適層
3. 說明優先順序
4. 標出常見衝突
5. 給驗證

【輸出規範】
▌一、設定層級
▌二、設定歸層
▌三、優先順序
▌四、衝突處理 + 驗證

【硬約束】
- 設定放對層級
- 專案設定隨儲存庫管理
- 改後驗證生效
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述

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