---
title: "配置 OpenCode"
description: "理解 opencode.json、配置合併、載入優先順序和新手最小配置策略。"
verifiedAt: "2026-05-09"
---

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

> [!NOTE]
> **這一篇用 8 分鐘換什麼**：你會知道全域性配置和專案配置怎麼分工，為什麼配置會互相合並，哪些覆蓋入口優先順序更高，以及出問題時怎麼回到最小配置。

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

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

```mermaid
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
```

> [!IMPORTANT]
> 真實 API key、個人路徑、本機實驗配置和臨時代理不要進專案儲存庫。專案配置應該能被團隊 review、提交和回復。

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

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.json` | 專案模型、tools、instructions、團隊預設值 | 個人金鑰、本機路徑 |
| `.opencode/` | agents、commands、plugins、skills、themes | 雜亂臨時筆記 |
| 環境變數 | 臨時測試、CI、一次性覆蓋 | 長期團隊規範 |

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

## 最小配置策略

第一次配置只需要解決一個問題：讓 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`，先處理認證和網路邊界。

## 配置排錯順序

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

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

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

## 新手常見坑

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

## 怎麼判斷配置健康

健康標準：

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

## 接下來去哪

<Cards>
  <Card title="配置 Rules" description="把專案長期約束寫清楚，不要靠每次臨時提醒。" href="/zh-Hant/docs/opencode/official/02-agents-skills/rules" />
  <Card title="選擇模型" description="配置預設模型前，先確認 provider/model/variant 的官方邊界。" href="/zh-Hant/docs/opencode/official/03-models/models" />
  <Card title="工具總覽" description="放寬工具能力前，先理解內建工具和 permission 的關係。" href="/zh-Hant/docs/opencode/official/04-tools-mcp/tools" />
  <Card title="快捷鍵" description="TUI 體驗類偏好放到 `tui.json`，不要和 OpenCode runtime 配置混在一起。" href="/zh-Hant/docs/opencode/official/01-customization/keybinds" />
</Cards>

## 官方資料

- OpenCode Config：[https://opencode.ai/docs/config](https://opencode.ai/docs/config)
- OpenCode Models：[https://opencode.ai/docs/models](https://opencode.ai/docs/models)
- OpenCode Tools：[https://opencode.ai/docs/tools](https://opencode.ai/docs/tools)
- OpenCode Server：[https://opencode.ai/docs/server](https://opencode.ai/docs/server)
