OpenCode 中文教程
基於 OpenCode 官方資料和原始碼重寫的中文教程。
OpenCode 是一個開源 AI coding agent。它可以跑在終端 TUI、CLI、桌面應用、IDE 擴充套件和 Web/server 裡，也可以透過 SDK、GitHub/GitLab 整合、ACP、MCP、LSP、Plugin 和 Skill 接到更大的開發流程裡。
這個中文教程解決兩個問題：第一，幫你快速查到官方功能怎麼用；第二，幫你理解 OpenCode 適合放在什麼工作流裡。讀完以後，你應該能判斷什麼時候用 OpenCode、怎麼連線模型、怎麼配置專案規則、哪些能力可以交給 agent，哪些動作必須繼續人工確認。
先給結論：如果你只是第一次開啟 OpenCode，先走“官方教程中文版”；如果你已經能跑起來，但不知道怎麼把 rules、commands、agents、skills、MCP 和許可權體系連成長期工作流，再讀“從原理到實戰”。
兩條互補路徑
flowchart LR
Start["OpenCode 中文教程"] --> Official["官方教程中文版"]
Start --> Understanding["從原理到實戰"]
Official --> Lookup["安裝 / CLI / TUI / 配置 / 工具 / 許可權"]
Understanding --> Judgment["定位 / 工作流 / 模型策略 / 團隊邊界"]
style Start fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
style Official fill:#dcfce7,stroke:#22c55e
style Understanding fill:#fef3c7,stroke:#f59e0b接下來去哪
官方教程中文版
按官方文件功能分類，適合查命令、配置項和入口位置。
從原理到實戰
8 篇中文講解，理解 OpenCode 的定位、配置體系和團隊使用邊界。
安裝、連線模型與第一次執行
第一次使用時，先跑通安裝、provider、只讀和低風險寫入。
安全、分享與團隊使用
進入真實專案或團隊流程前，先收緊許可權、金鑰、分享和網路邊界。
怎麼選擇閱讀路徑
第一次接觸 OpenCode，不要從複雜配置開始。先把安裝、模型連線和第一輪只讀任務跑通，再進入 agent、skill、plugin、MCP、LSP 和團隊配置。
| 你的狀態 | 先讀什麼 | 目標 |
|---|---|---|
| 還沒安裝 | 官方教程中文版 | 找到安裝方式、啟動 TUI、完成 provider 連線 |
| 能開啟 TUI，但不會穩定使用 | 安裝、連線模型與第一次執行 | 跑通一個低風險任務，確認能讀專案、能解釋、能受控修改 |
| 已經日常使用，但配置很散 | 配置、Rules 與自定義命令 | 把重複提醒沉澱成專案規則和 slash command |
| 想接更多工具 | 工具、MCP、LSP 與格式化器 | 判斷什麼應該用內建工具，什麼才值得接 MCP 或 LSP |
| 準備團隊使用 | 安全、分享與團隊使用 | 控制許可權、分享、金鑰、網路和專案級配置邊界 |
不要反過來讀：還沒跑通第一輪任務，就研究 plugin 和 SDK，很容易把 OpenCode 當成“可配置項合集”。OpenCode 真正的價值來自“能在真實專案里長期、受控、可複用地執行任務”。
這組教程會講清什麼
- OpenCode 和 Claude Code、Codex 的差異：不是誰更強，而是開放配置、多模型和終端優先這三個取捨不同。
- 終端 TUI 的核心動作：
@檔案引用、!shell 命令、/命令、會話壓縮、attach 和 server。 - 配置體系：全域性配置、專案配置、
.opencode/、rules、commands、agents、skills、plugins 各自放什麼。 - 模型策略：provider、model、small model、Zen、備用模型和 agent 繫結模型怎麼取捨。
- 工具系統：內建工具、MCP、LSP、formatter、custom tools 的職責邊界。
- 安全底線：permissions、網路訪問、會話分享、金鑰隔離和團隊公共配置。
事實基準
這裡不會把官方英文文件逐頁直譯。官方頁面負責給事實和引數，本教程負責按中文開發者的學習順序重寫：先解釋這個功能解決什麼問題，再給最小可執行動作，最後補常見坑和下一步。
使用前的安全提醒
OpenCode 能讀檔案、改檔案、跑命令、聯網、呼叫工具、分享會話。這些能力進入真實專案之前，先按低風險順序推進：
- 第一次任務只讀。
- 第一次寫操作限定單檔案。
- 大範圍修改先讓它給計劃。
- 涉及金鑰、賬號、支付、資料刪除、釋出部署時必須人工確認。
- 分享會話前先脫敏；敏感專案直接關閉分享。
這不是保守，而是讓你敢把 OpenCode 放進長期工作流。
延伸學習
- 翔宇工作流主站：xiangyugongzuoliu.com
- 翔宇 AI 程式設計實操課：檢視課程介紹與學習路徑