OpenCode 官方教程中文版
基於 OpenCode 官方資料重寫的中文查詢手冊，按功能分類組織。
這一頁是 OpenCode 官方能力的中文查詢入口。你不用從頭讀完，按自己當前卡住的問題進入對應章節：安裝看“入門”，專案規則看“個性化”，角色分工看“Agents & Skills”，工具接入看“工具與 MCP”，團隊安全看“安全與網路”。
這頁解決什麼問題：把 OpenCode 官方文件拆成可查詢的功能地圖。讀完你應該知道“我要查的功能在哪一組”，而不是在 CLI、TUI、config、agent、tool、provider 這些詞之間來回找。
事實來源：opencode.ai/docs/zh-cn · OpenCode 官方維護的中文文件。具體引數、命令和行為變化以官方頁面為準；本頁只做中文路徑重組和學習順序建議。
先按問題選入口
| 你現在要做什麼 | 進入哪組 | 先看哪一頁 |
|---|---|---|
| 第一次安裝和啟動 | 入門 | 入門 |
| 只想知道 TUI 怎麼操作 | 入門 | 使用 TUI |
| 想把配置寫進專案 | 個性化 | 配置 OpenCode |
| 想沉澱重複任務 | 個性化 | 建立自定義命令 |
| 想拆角色或專用 agent | Agents & Skills | 配置 Agents |
| 想接外部系統 | 工具與 MCP | 連線 MCP 伺服器 |
| 想控制讀寫和命令許可權 | 安全與網路 | 管理許可權 |
| 想把 OpenCode 接進團隊流程 | 整合 / SDK & 服務 | 接入 GitHub 或 使用 SDK |
閱讀順序建議
第一次學習按這個順序走，不要直接跳到 plugin 或 SDK：
- 入門：安裝、provider、TUI、IDE、分享。
- 個性化：配置檔案、快捷鍵、主題、自定義命令。
- Agents & Skills：agent、skill、plugin、rules 的職責邊界。
- 模型與供應商：先理解 provider/model，再考慮預設模型和備用模型。
- 工具與 MCP：先掌握內建工具，再擴充套件 MCP、LSP、formatter 和 custom tools。
- 安全與網路：真實專案使用前必須回頭檢查許可權、網路和分享。
不要只看能做什麼：OpenCode 的危險點也來自“能做什麼”。凡是涉及 edit、bash、webfetch、websearch、MCP 寫操作、分享會話，都應該同時查許可權和安全頁面。
完整目錄
入門
入門階段只驗證三件事：命令能啟動、provider 能連線、OpenCode 能在一個真實專案裡完成只讀解釋。先不要讓它大範圍改程式碼。
個性化
個性化不是換皮膚那麼簡單。真正有長期價值的是把預設模型、許可權、instructions、commands、agents、MCP 和 formatter 放到合適的配置層級。
Agents & Skills
這一組最容易混淆。可以先記住一句話：rules 是專案長期約定，commands 是重複任務入口，agents 是角色和許可權邊界，skills 是可複用能力包，plugins 是執行時擴充套件。
模型與供應商
OpenCode 的多模型能力適合做任務分層：輕量解釋用低成本模型，跨檔案修改用更強模型，安全和釋出相關任務必須保留人工確認。
工具與 MCP
先用內建工具跑通讀檔案、改檔案、執行測試和檢視 diff，再接 MCP。工具越多，許可權和誤操作風險越高。
安全與網路
安全頁面不是最後才看的附錄。只要 OpenCode 能讀寫儲存庫、執行命令、聯網或分享會話，就應該先定義許可權邊界。
整合
整合類頁面適合已經有團隊流程的人讀。個人上手階段不需要一開始就接 GitHub/GitLab 自動化。
SDK & 服務
SDK 和 server 說明 OpenCode 不只是終端工具，也能作為服務能力被嵌入系統。但這部分維護成本更高，先確認普通 TUI 工作流穩定，再進入這一層。
平臺與故障
平臺差異和故障排查最好按症狀查。Windows 使用者優先看 WSL；provider 不穩定或不想自己篩模型時，看 Zen；IDE/協議整合再看 ACP。