OpenCode 從原理到實戰

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、什麼時候切模型、什麼工具值得接、什麼許可權必須收緊。

這組文章不重複官方手冊。要查某個命令或配置項，去官方教程中文版；要理解功能背後的使用判斷，讀這裡。

8 篇文章的主線

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”，第二到第三篇解決“怎麼跑起來並穩定使用”，第四到第七篇解決“怎麼把能力沉澱成系統”，第八篇解決“怎麼把風險收住”。

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

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

和官方教程中文版的分工

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

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

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

先記住一張分層圖

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

入口层      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 能做什麼、看什麼	進真實專案、對外分享、團隊共用前

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

OpenCode 從原理到實戰

8 篇文章的主線

先跑起來

再沉澱規則

最後收緊邊界

推薦閱讀順序

三個學習階段

和官方教程中文版的分工

先記住一張分層圖

接下來去哪

OpenCode 到底是什麼

安裝、連線模型與第一次執行

官方教程中文版

OpenCode 中文教程

本頁目錄