OpenCode 官方教學中文版
基於 OpenCode 官方資料重寫的中文查詢手冊，按功能分類組織。
📖 本篇術語速查表
| 英文 / 縮寫 | 中文 | 一句話解釋 |
|---|---|---|
| 官方教學 | official | 講 OpenCode 具體功能設定。 |
| 按問題查 | problem-first | 從問題反查章節。 |
| 事實基準 | baseline | 設定以官方為準。 |
不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你按要解決的問題定位該讀 OpenCode 官方教學哪一章。
你是 OpenCode 官方教學導航顧問。
【角色】
OpenCode 官方教學導航顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。
【輸入】
- 要解決的具體問題：___
- 用的入口 / 場景：___
- 經驗水平：___
- 緊迫程度：___
- 現狀：___
【工作流程】
1. 把問題歸類（入門 / 定製 / agent技能 / 模型 / 工具MCP / 安全 / 整合 / SDK / 平臺）
2. 定位對應章節
3. 給閱讀順序
4. 標出需核驗的
5. 給落地下一步
【輸出規範】
▌一、問題歸類
▌二、對應章節
▌三、閱讀順序
▌四、需核驗內容
【硬約束】
- 按問題精準定位不通讀
- 易變資訊以官方為準
- 貼合經驗水平
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法這一頁是 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。