OpenCode 完整使用手冊 — 終端機、桌面版與 IDE 的 AI 程式開發助手
OpenCode 是一套開源的 AI 程式開發助手，能直接在你的電腦上讀取專案檔案、執行終端機指令、實際修改程式碼。它支援終端機、桌面版與 IDE 擴充三種使用方式，並可自由連接 Claude、GPT、Gemini 或官方精選模型。本手冊從安裝、設定到桌面版操作，一步步帶新手完成。
目錄
- OpenCode 是什麼？
- 三種使用方式比較
- 安裝 OpenCode
- 首次設定：連接 AI 模型
- 桌面版完整使用流程
- 初始化專案
- 核心用法
- 常用斜線指令速查
- 桌面版 vs 終端機版
- 常見問題 FAQ
- 給新手的實用建議
- 總結
OpenCode 是什麼？
如果你對「AI 幫你寫程式」的印象，還停留在網頁聊天室裡複製貼上程式碼，那 OpenCode 會讓你改觀。
它是一套開源的 AI 程式開發助手，不是待在網頁裡，而是直接跑在你自己的電腦上。它能：
- 看見你的整個專案：自動載入檔案與語言伺服器（LSP），理解專案結構。
- 執行終端機指令：需要安裝套件、跑測試、查日誌時，它會自己動手。
- 實際修改程式碼：不只是給建議，而是直接編輯檔案。
- 讀懂圖片：把設計稿或截圖拖進去，它就能當作參考。
- 多工作業：同一個專案可以同時開多個代理（Agent）並行處理不同任務。
- 分享會話：產生連結，方便團隊一起看某次對話。
它最大的特色是不綁定模型：透過 Models.dev 支援 75 種以上的供應商，包含 Claude、GPT、Gemini，也可以使用官方測試過的 Zen 模型、每月 10 美元的 Go 訂閱，甚至連接本地模型。
三種使用方式比較
OpenCode 提供三種介面，背後是同一個引擎，你可以依習慣自由選擇，甚至混著用。
| 使用方式 | 適合對象 | 特色 |
|---|---|---|
| 終端機（TUI） | 熟悉命令列的人 | 最輕量、最快、彈性最高 |
| 桌面版（Desktop） | 剛入門的新手 | 圖形介面、支援分頁、直覺好上手 |
| IDE 擴充 | 習慣留在編輯器的人 | 整合 VS Code、Cursor、Zed、Windsurf |
安裝 OpenCode
方法一：終端機版（老手最愛）
開啟終端機，貼上這行指令即可：
curl -fsSL https://opencode.ai/install | bash
macOS / Linux 也能使用 Homebrew：
brew install anomalyco/tap/opencode
習慣 Node.js 生態的話：
npm install -g opencode-ai
方法二：桌面版（新手最友善）
不想打指令？直接前往官方下載頁：https://opencode.ai/download
依照你的作業系統選擇：
- macOS（Apple Silicon）：下載
.dmg - macOS（Intel）：下載對應版本
- Windows（x64）：下載安裝檔
- Linux：
.deb或.rpm
macOS 也能用 Homebrew 一行安裝：
brew install --cask opencode-desktop
下載後就像安裝一般軟體：雙擊、拖進「應用程式」資料夾、開啟即可。
方法三：IDE 擴充套件
在 VS Code、Cursor、Windsurf、VSCodium 等編輯器中，打開整合終端機並執行：
opencode
擴充套件會自動安裝。也可以在擴充套件市集搜尋 OpenCode 手動安裝。
驗證安裝
opencode --version
若顯示版本號，代表安裝成功。
首次設定：連接 AI 模型
不論使用哪一種版本，第一次打開都需要設定「要用哪個 AI 模型」。
在終端機或桌面版裡
輸入斜線指令：
/connect
接著選擇供應商（Provider），把 API Key 貼進去即可。如果不知道選哪個，官方的 OpenCode Zen 是經過測試的精選清單，對新手最省事。
設定完成後，用這個指令查看可用模型：
/models
用指令列登入（選用）
也可以在終端機直接登入：
opencode auth login
查看目前已登入的供應商：
opencode auth list
憑證會儲存在 ~/.local/share/opencode/auth.json。
桌面版完整使用流程
桌面版把設定與操作變成點選式介面，對不熟悉命令列的新手最友善。大致流程如下：
第一步：下載與安裝
前往 https://opencode.ai/download，選擇對應系統的版本下載並安裝。
第二步：首次啟動
打開 OpenCode Desktop，首次啟動時選擇要連接的供應商，並貼上 API Key。設定與終端機版共用，所以你在終端機設定過的模型，桌面版也會沿用。
第三步：選擇專案資料夾
選擇你要開啟的專案資料夾，OpenCode 便能讀取其中的檔案並開始協作。
第四步：開始對話
在輸入框描述你的需求即可。桌面版支援分頁（Tabs），你可以同時開好幾個會話，在不同專案或任務之間切換，不必像終端機一樣一次只盯著一個畫面。對於「一邊修 bug、一邊寫新功能」的情境特別方便。
小提醒：桌面版與終端機版共用同一套設定與會話。你在終端機開的對話，桌面版也看得到；反之亦然。
初始化專案
第一次在某個專案裡使用時，建議先執行：
/init
OpenCode 會分析你的專案結構，產生一個 AGENTS.md 檔案，記錄這個專案的技術棧、風格與規範。
請把這個檔案提交到 Git。 之後每次對話，OpenCode 都會參考它，回答與修改會準確非常多，團隊成員也能共享同一份理解。
核心用法
1. 問問題，讀懂陌生程式碼
最基本的用法就是直接提問。用 @ 可以模糊搜尋並引用檔案：
@src/api/index.ts 裡面的登入驗證是怎麼做的？
引用後，該檔案內容會自動加入對話，你不必手動複製貼上。接手別人的專案時，這招能省下大量翻找時間。
2. 用 ! 直接跑指令
在訊息開頭加上 !，就能執行終端機指令，輸出會自動進入對話：
!ls -la
3. 先規劃，再動手（Plan / Build 模式）
OpenCode 有兩種模式，用 Tab 鍵切換：
- Plan 模式：只提出方案，不會改動任何程式碼。
- Build 模式：實際執行修改。
遇到較複雜的功能時，建議先在 Plan 模式把需求講清楚，來回討論到滿意，再切回 Build 模式讓它動手。描述時就當在跟一位新同事溝通——背景、範例、期望結果講得越清楚越好：
使用者刪除筆記時，我們想在資料庫標記為「已刪除」。
再做一個「最近刪除」頁面，可以還原或永久刪除。
你還可以直接把設計稿截圖拖進終端機，OpenCode 能讀取圖片當作參考。
4. 改錯了？一鍵還原
/undo
會撤銷上一次的修改與對話，可以連續執行多次。想恢復就用：
/redo
注意：
/undo與/redo依賴 Git 管理檔案變更，所以你的專案必須是 Git 儲存庫。
5. 分享給同事
/share
會產生一個連結並複製到剪貼簿，方便團隊一起檢視這次對話。會話預設不會公開。
6. 非互動模式（腳本與自動化）
如果只想快速問一個問題、不進入互動介面：
opencode run "解釋 JavaScript 的閉包是什麼"
這在寫腳本或自動化時特別好用。
常用斜線指令速查
| 指令 | 功能 |
|---|---|
/connect |
連接 AI 供應商、設定 API Key |
/init |
初始化專案，產生 AGENTS.md |
/models |
列出可用模型 |
/new |
開新會話（別名 /clear） |
/sessions |
切換不同會話 |
/compact |
壓縮對話長度，節省 token |
/undo |
還原上一次修改 |
/redo |
重做已還原的修改 |
/share |
分享目前會話 |
/export |
匯出對話為 Markdown |
/editor |
用外部編輯器撰寫訊息 |
/help |
顯示說明 |
多數指令也有快捷鍵，預設以 Ctrl+X 作為前置鍵。
桌面版 vs 終端機版
| 終端機版 | 桌面版 | |
|---|---|---|
| 適合對象 | 熟悉命令列的人 | 剛入門的新手 |
| 操作方式 | 鍵盤指令 | 圖形介面點選 |
| 多工 | 一次一個畫面 | 支援分頁，多會話並行 |
| 資源佔用 | 極低 | 稍高 |
| 彈性 | 最高，可搭配腳本 | 直覺、好上手 |
其實不用二選一。兩者共用設定與會話，你可以平常用桌面版，需要自動化時切到終端機。
常見問題 FAQ
Q1：OpenCode 需要額外訂閱 AI 服務嗎？
不一定。OpenCode 本身開源免費，但你需要一個模型來源。可以自備 API Key、使用官方 Zen 精選模型，或訂閱每月 10 美元的 Go（含多款開源模型）。也有免費模型可以使用。
Q2：只能在終端機使用嗎？
不是。除了終端機，還提供桌面版與 IDE 擴充套件，三者共用同一個引擎。
Q3：/undo 沒有作用？
/undo 與 /redo 依賴 Git 管理檔案變更，請確認你的專案是 Git 儲存庫，且已初始化。
Q4：桌面版和終端機版的資料是分開的嗎？
不是。兩者共用同一套設定與會話，可以在不同介面間無縫切換。
Q5：OpenCode 會上傳我的程式碼嗎？
官方強調隱私優先，不會儲存你的程式碼或上下文資料。實際傳送內容取決於你選擇的模型供應商，建議依自身需求選擇信任的供應商。
Q6：如何更新 OpenCode？
opencode upgrade
或依照原本的安裝方式更新（例如 brew upgrade opencode）。
Q7：如何完全移除 OpenCode？
opencode uninstall
可加上 --keep-config 保留設定，或 --keep-data 保留會話資料。
給新手的實用建議
- 給足上下文：背景、範例、期望結果講清楚，結果會好很多。
- 善用 Plan 模式：牽涉多檔案或架構調整時，先看方案再動手，能省下大量返工。
- 提交
AGENTS.md：讓整個團隊共享一致的專案理解，是長期使用的關鍵。 - 先從小任務開始：從解釋程式碼、修一個小 bug 入手，熟悉後再挑戰大功能。
總結
| 專案 | 說明 |
|---|---|
| 定位 | 開源 AI 程式開發助手 |
| 介面 | 終端機、桌面版、IDE 擴充 |
| 模型 | 支援 75+ 供應商，可自由切換 |
| 特色 | 讀取專案、執行指令、修改程式碼、讀取圖片、分享會話 |
| 適合新手 | 桌面版圖形介面，支援分頁多工 |
OpenCode 的價值，在於把 AI 真正接進你的開發流程，而不是停留在「複製聊天室的程式碼」。不管你選擇終端機、桌面版還是 IDE 擴充，它都能看見你的檔案、遵守你的專案規範，成為每天都能派上用場的助手。
現在就到 https://opencode.ai/download 下載，或複製一行安裝指令，開始你的第一個 AI 協作專案吧。
官方資源
- 官方網站：https://opencode.ai
- 下載頁面：https://opencode.ai/download
- 使用文件：https://opencode.ai/docs
- GitHub：https://github.com/anomalyco/opencode
- 問題回報：https://github.com/anomalyco/opencode/issues
- Discord 社群：https://opencode.ai/discord