---
title: "OpenCode 從原理到實戰"
description: "從定位、終端工作流、配置、Agent、模型、工具和安全邊界理解 OpenCode。"
verifiedAt: "2026-05-09"
---

OpenCode 的難點不在“命令記不住”，而在“能力太開放”。它有六種入口（TUI 終端介面、CLI 命令列、IDE 外掛、桌面端、Web 瀏覽器、ACP 編輯器協議），進入會話後還有十多類可配置項——provider（模型供應商）、rules（專案規則）、commands（自定義命令）、agents（角色）、skills（能力包）、plugins（執行時擴充套件）、MCP（外部工具協議）、LSP（程式碼補全/跳轉引擎）、formatter（程式碼格式化器）、SDK（程式設計接入）、server（HTTP 服務模式）、share（會話分享）——初學者很容易把它當成一堆功能列表。

它最有標誌性的設計藏在第一次會話裡：按 **Tab** 鍵就能在 *Plan mode*（只規劃、不動檔案）和 *Build mode*（按計劃改程式碼）之間切換。先用 Plan 想清楚再切 Build 落地，是 OpenCode 與其他終端 AI 程式設計工具最直觀的差異點。

這一組文章只解決一個問題：**怎樣把 OpenCode 理解成一套可長期使用的 AI 程式設計工作流**。讀完以後，你應該能判斷哪些規則寫進專案、哪些任務交給 agent、什麼時候切模型、什麼工具值得接、什麼許可權必須收緊。

> [!NOTE]
> **這組文章不重複官方手冊**。要查某個命令或配置項，去 [官方教程中文版](/zh-Hant/docs/opencode/official)；要理解功能背後的使用判斷，讀這裡。

## 8 篇文章的主線

```mermaid
flowchart TD
    A["01 定位：OpenCode 是什麼"] --> B["02 跑通：安裝與第一次執行"]
    B --> C["03 工作流：終端 TUI 怎麼用"]
    C --> D["04 沉澱：配置、Rules、Commands"]
    D --> E["05 擴充套件：Agents、Skills、Plugins"]
    E --> F["06 策略：模型與供應商"]
    F --> G["07 工具：MCP、LSP、Formatter"]
    G --> H["08 治理：安全、分享、團隊"]

    style A fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
    style D fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style H fill:#fee2e2,stroke:#ef4444,stroke-width:2px
```

第一篇解決“為什麼用 OpenCode”，第二到第三篇解決“怎麼跑起來並穩定使用”，第四到第七篇解決“怎麼把能力沉澱成系統”，第八篇解決“怎麼把風險收住”。

<Cards>
  <Card title="先跑起來" description="安裝、連線 provider、啟動 TUI，完成第一輪只讀任務。" href="/zh-Hant/docs/opencode/understanding/02-install-first-run" />
  <Card title="再沉澱規則" description="把反覆提醒寫成 rules，把重複流程寫成 slash command。" href="/zh-Hant/docs/opencode/understanding/04-config-rules-commands" />
  <Card title="最後收緊邊界" description="許可權、網路、分享、金鑰和團隊配置先定義，再擴大使用範圍。" href="/zh-Hant/docs/opencode/understanding/08-security-share-team" />
</Cards>

## 推薦閱讀順序

1. [OpenCode 到底是什麼](/zh-Hant/docs/opencode/understanding/01-what-is-opencode)：先建立定位，避免把它當成 Claude Code 或 Codex 的簡單替代品。
2. [安裝、連線模型與第一次執行](/zh-Hant/docs/opencode/understanding/02-install-first-run)：跑通 CLI、TUI、IDE 和 provider 連線。
3. [終端 TUI 工作流](/zh-Hant/docs/opencode/understanding/03-terminal-workflow)：理解檔案引用、命令、會話、壓縮和 attach。
4. [配置、Rules 與自定義命令](/zh-Hant/docs/opencode/understanding/04-config-rules-commands)：把一次性提示詞變成專案約定。
5. [Agents、Skills 與 Plugins](/zh-Hant/docs/opencode/understanding/05-agents-skills-plugins)：區分角色、能力包和執行時擴充套件。
6. [模型與供應商策略](/zh-Hant/docs/opencode/understanding/06-model-provider-strategy)：按任務選擇模型，而不是隻追最新模型。
7. [工具、MCP、LSP 與格式化器](/zh-Hant/docs/opencode/understanding/07-tools-mcp-lsp)：把 OpenCode 接到真實開發環境。
8. [安全、分享與團隊使用](/zh-Hant/docs/opencode/understanding/08-security-share-team)：控制許可權、網路和公開分享邊界。

## 三個學習階段

| 階段 | 先解決的問題 | 過關標準 |
| --- | --- | --- |
| 上手 | OpenCode 能不能在我的專案裡工作 | 能安裝、連線 provider、啟動 TUI，並讓它只讀解釋專案結構 |
| 沉澱 | 怎麼讓一次經驗變成下次自動遵守 | 能區分 config、rules、commands、agents、skills、plugins，各自只放合適內容 |
| 治理 | 怎麼讓它進真實專案不失控 | 能寫出許可權基線，知道什麼時候禁止分享、聯網、部署和讀取金鑰 |

> [!IMPORTANT]
> **別急著追高階功能**：OpenCode 的上限來自開放擴充套件，但穩定性來自低風險起步。第一輪任務如果連“只讀解釋專案結構”都不穩定，就先不要接 MCP、plugin 或自動化。

## 和官方教程中文版的分工

官方教程中文版按功能分類，適合查 API、命令、配置項和入口位置：

- [OpenCode 官方教程中文版](/zh-Hant/docs/opencode/official)
- [CLI / TUI / IDE / 分享](/zh-Hant/docs/opencode/official/00-getting-started)
- [配置 / 命令 / 快捷鍵 / 主題](/zh-Hant/docs/opencode/official/01-customization/config)
- [Agents / Skills / Plugins / Rules](/zh-Hant/docs/opencode/official/02-agents-skills/agents)
- [模型 / Provider](/zh-Hant/docs/opencode/official/03-models/models)
- [工具 / MCP / LSP / Formatter](/zh-Hant/docs/opencode/official/04-tools-mcp/tools)
- [許可權 / 網路](/zh-Hant/docs/opencode/official/05-security/permissions)

從原理到實戰不重複官方手冊，而是把這些能力串成使用判斷：

- **功能是什麼**：只保留足夠理解的定義，不堆引數。
- **為什麼要用**：解釋這個能力解決的真實開發問題。
- **怎麼上手**：給一個低風險最小動作。
- **常見坑**：指出新手最容易誤用的地方。
- **下一步**：把當前文章接到前後篇和官方頁。

## 先記住一張分層圖

OpenCode 可以先拆成 6 層。後面 8 篇都圍繞這張圖展開。

```text
入口层      TUI / CLI / IDE / Desktop / Web / ACP
上下文层    AGENTS.md / rules / @file / session / compact
执行层      read / edit / bash / LSP / formatter / MCP
角色层      commands / agents / skills / plugins
模型层      provider / model / small_model / Zen / API key
治理层      permissions / network / share / team config
```

每一層解決的問題和你需要關心它的時機：

| 層 | 解決的問題 | 什麼時候開始關心 |
| --- | --- | --- |
| 入口層 | OpenCode 在哪裡執行、長什麼樣 | 選 TUI 還是 IDE / 桌面端 / Web 時 |
| 上下文層 | 讓模型知道專案結構和當前會話狀態 | 寫 AGENTS.md、用 @file 引用、對話變長想壓縮時 |
| 執行層 | 模型怎麼讀程式碼、改檔案、跑命令 | 接外部工具、想看模型實際做了什麼時 |
| 角色層 | 把重複任務沉澱成可複用動作 | 想讓一次經驗下次自動遵守時 |
| 模型層 | 用哪個供應商和模型、怎麼管 key | 任務複雜度變化、預算需要分級時 |
| 治理層 | 控制 OpenCode 能做什麼、看什麼 | 進真實專案、對外分享、團隊共用前 |

如果你只想快速使用，先掌握入口層、上下文層和執行層。如果要團隊複用，再進入角色層、模型層和治理層。

## 接下來去哪

<Cards>
  <Card title="OpenCode 到底是什麼" description="先拆清 OpenCode 和 Claude Code、Codex 的差異，建立正確定位。" href="/zh-Hant/docs/opencode/understanding/01-what-is-opencode" />
  <Card title="安裝、連線模型與第一次執行" description="已經理解定位後，進入第一天安全閉環。" href="/zh-Hant/docs/opencode/understanding/02-install-first-run" />
  <Card title="官方教程中文版" description="需要查具體命令、配置項和功能入口時，回到官方查詢手冊。" href="/zh-Hant/docs/opencode/official" />
  <Card title="OpenCode 中文教程" description="回到總入口，在官方查詢和理解路線之間切換。" href="/zh-Hant/docs/opencode" />
</Cards>
