當設定過程中出現錯誤，或工具無法如預期執行時，安裝 OpenCode 有時會讓人感到困惑。從缺少指令到 Node.js 相容性問題，使用者在初次安裝時常常會遇到困難。這篇 OpenCode 安裝指南提供完整的解決方案，協助你修正常見錯誤，並在 Mac 與 Windows 上順利完成 OpenCode 的安裝，無論你使用的是桌面版還是 CLI/TUI 版本，都能立即開始撰寫程式碼，不必再耽誤時間。
什麼是 OpenCode？
OpenCode 是一款開源的 AI 程式碼撰寫代理，旨在協助開發者直接在偏好的環境中撰寫、編輯、除錯與管理程式碼，無論是終端機、IDE 還是桌面應用程式皆可使用。與主要著重程式碼建議的傳統 AI 程式碼輔助工具不同，OpenCode 能夠理解整個程式碼庫、修改檔案、執行指令，並自動化開發流程。它同時支援多種 AI 模型與本地模型，讓開發者在建構軟體時擁有更高的彈性與掌控度。
安裝 OpenCode 的前置條件
在安裝 OpenCode 之前，請確認你的系統符合基本需求。實際的前置條件取決於你打算使用桌面應用程式還是終端機介面，但事先做好正確的環境設定，有助於確保安裝過程順利進行。
桌面版
作業系統： macOS / Windows / Linux
OpenCode 提供主要作業系統的桌面應用程式，讓開發者可以在偏好的環境中安裝並使用此工具。請確認你的系統使用的是相容的作業系統，例如 macOS（Apple Silicon 或 Intel）、Windows（x64）或 Linux（.deb、.rpm）。
應用程式安裝權限： 你可能需要管理員或系統層級的權限，才能在裝置上下載並安裝軟體。這在職場或受管理的 IT 環境中尤其重要，因為這些環境可能會限制安裝權限。
穩定的網路連線： 下載 OpenCode、安裝更新，以及在設定與使用過程中連接受支援的 AI 模型與服務，都需要穩定的網路連線。
終端機/TUI
終端機存取權限： OpenCode 可直接透過命令列安裝與使用。請確認你能使用終端機應用程式，例如 macOS 上的 Terminal、Windows 上的命令提示字元或 PowerShell，或 Linux shell。
一種安裝方式： OpenCode 支援多種安裝方式，以配合不同的作業系統與開發者的偏好。請選擇最適合你環境的套件管理工具或安裝工具，例如 npm、curl、brew、Scoop、Chocolatey 或 WSL。
基本命令列操作能力： 熟悉常見的終端機指令能讓安裝與日常使用更加順手。雖然不需要進階技能，但建議了解基本的導覽方式與指令執行方法。
如何安裝 OpenCode 桌面版？
安裝 OpenCode 桌面版是一個簡單的過程，只需幾個步驟即可讓應用程式順利運作。以下是安裝步驟。
步驟 1：下載 OpenCode 桌面版
前往 OpenCode 官方下載頁面，選擇適用於 Windows 或 macOS 的版本。安裝程式會自動下載到你的系統。請務必從官方來源下載，以確保安全性與正版性。
步驟 2：執行安裝程式
找到下載好的安裝程式檔案，雙擊以開始安裝。依照畫面上的指示完成設定。
步驟 3：完成安裝
依照設定流程逐步進行，並在系統提示時選擇你偏好的安裝目錄。接著讓安裝程式在你的系統上完成整個設定過程。
步驟 4：啟動 OpenCode Desktop
安裝完成後，透過開始功能表或桌面捷徑開啟 OpenCode Desktop。接著新建專案或開啟現有資料夾即可開始工作。工作區載入完成後，你就可以與 AI 助手互動，生成程式碼、除錯，或直接在專案中開發功能。
如何在 Mac 上安裝 OpenCode Terminal/TUI？
在 Mac 上，可以直接使用官方套件管理工具或一行安裝指令來安裝 OpenCode Terminal（TUI）。它專為偏好在終端機中工作、而非使用圖形介面的開發者所設計。請依照以下步驟在 Mac 上安裝 OpenCode TUI。
步驟 1：選擇 OpenCode Terminal 的安裝方式
前往 OpenCode 官方下載頁面，導覽至 OpenCode Terminal 區塊。這裡提供多種安裝方式，包括 curl、Homebrew、npm 和 bun。選擇最符合你開發環境的方式，並複製對應的安裝指令。
步驟 2：在 Mac 上開啟終端機應用程式
在 Mac 上啟動終端機應用程式。你可以透過「應用程式」>「工具程式」>「終端機」開啟，或使用 Spotlight 搜尋快速尋找。這裡就是你執行 OpenCode 安裝指令的地方。
步驟 3：安裝 OpenCode Terminal
將以下安裝指令貼到終端機中並按下 Enter：
curl -fsSL https://opencode.ai/install | bash等待安裝完成。OpenCode 會自動下載所需檔案並設定好 CLI。
步驟 4：啟動 OpenCode 終端機介面
安裝完成後，在終端機中執行 OpenCode 指令以啟動終端機使用者介面（TUI）。互動式介面會直接在終端機視窗中開啟，讓你連接 AI 供應商、進行設定，並開始使用 OpenCode。
如何在 Windows 上安裝 OpenCode Terminal/TUI？
OpenCode 在 Windows 上支援多種安裝方式，包括 WSL、npm、bun。為獲得最佳相容性與使用體驗，官方文件建議使用 Windows Subsystem for Linux（WSL）。以下步驟採用 WSL 安裝方式。若你已安裝 WSL，可跳過第一步。
步驟 1：安裝 WSL（建議）
以系統管理員身分開啟 PowerShell，接著執行以下指令：
wsl --install這道指令會啟用 Windows Subsystem for Linux（WSL）並預設安裝 Ubuntu。安裝完成後，請重新啟動電腦。第一次開啟 Ubuntu 時，Windows 會自動完成 Linux 環境的設定。
步驟 2：開啟 WSL 並安裝 OpenCode
從 Windows 開始功能表啟動你的 WSL 終端機（例如 Ubuntu）。若這是你第一次開啟，請完成初始設定。接著執行以下指令安裝 OpenCode：
curl -fsSL https://opencode.ai/install | bash請等待安裝完成後再繼續。
步驟 3：驗證安裝結果
安裝完成後，執行以下指令：
opencode如果 OpenCode Terminal/TUI 順利啟動，就代表安裝已完成，你可以開始使用 OpenCode 進行 AI 輔助程式開發。
如何將外部 API 整合進 OpenCode？
OpenCode 的一大優勢在於能透過 API 整合連接外部 AI 模型供應商。只要新增自己的 API key，就能存取不同的語言模型，選出最適合自己開發流程的那一個。
將外部 API 整合進 OpenCode（一般步驟）
以下是將外部 API 整合進 OpenCode 的步驟：
步驟 1：建立帳號並產生 API key
首先為你偏好的 AI 供應商（例如 Kimi 或其他支援的服務）建立帳號。帳號設定完成後，前往該供應商的 API key 管理頁面，產生新的 API key。請妥善保管這組 key，因為稍後需要用它將供應商連接到 OpenCode。
步驟 2：開啟供應商連接選單
啟動 OpenCode 並開啟你的工作區。在命令介面中，執行以下命令：
/connect此命令會開啟供應商連接選單，你可以在這裡新增及管理外部 AI 服務。
步驟 3：新增你的 API key
從可用選項清單中選擇你想使用的供應商。系統提示時，貼上你先前產生的 API key 並確認連接。OpenCode 會安全地儲存這組 key，並用它來驗證對所選供應商的請求。
┌ API key
│
│ your_api_key_here
│
└ enter步驟 4：查看可用模型
連接供應商後，執行以下命令，查看透過該 API 可用的所有模型：
/modelsOpenCode 會顯示支援的模型清單，包含名稱與設定選項。
步驟 5：選擇模型並開始使用
從可用清單中選擇你想使用的模型。選定後，OpenCode 會將你的請求導向該模型，讓你能透過連接的 API 產生程式碼、除錯應用程式，並執行其他開發任務。若需求改變，之後也可以隨時切換模型。
將 Kimi API 整合進 OpenCode
OpenCode 支援多個 AI 供應商，讓開發者能透過 API key 連接外部模型，獲得更大的彈性。其中最強大的選項之一就是 Kimi API。
由 Moonshot AI 開放平台提供的 Kimi API，透過與 OpenAI 相容的介面，讓你能存取先進的 Kimi 語言模型。只需一組安全的 API key，就能輕鬆將其整合進開發工具、應用程式與 AI 驅動的工作流程中。此平台提供多款針對程式設計、推理與長上下文理解任務優化的 Kimi 模型。
請依照以下步驟，將 Kimi API 整合進 OpenCode。
步驟 1：建立 Moonshot AI 帳號並產生 API key
前往 Kimi AI 開放平台並登入你的帳號。
在儀表板中前往 API Keys，點擊 Create API Key。
產生 key（以
sk-開頭）後，請立即複製並妥善保管。這組 key 只會顯示一次，用於驗證 OpenCode 與 Moonshot AI 之間的請求。
步驟 2：將 Moonshot AI 連接至 OpenCode
開啟你的 OpenCode 工作區並執行：
/connect供應商連接選單會隨即出現。從內建供應商清單中搜尋 Moonshot AI（或 Kimi）並選取。OpenCode 會提示你輸入 API key。
系統提示時，貼上你從 Moonshot AI 控制台產生的 API key 並按下 Enter：
┌ API key
│ sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
│
└ enter驗證通過後，OpenCode 會將憑證安全地儲存在 ~/.local/share/opencode/auth.json，並將其與你的 Moonshot AI 供應商設定關聯起來。
注意：基於安全考量，OpenCode 會將 API key 與主設定檔分開儲存。
/connect命令負責處理憑證儲存，而供應商行為則在opencode.json中設定。
步驟 3：在 opencode.json 中設定供應商（如有需要）
如果連接後出現 No endpoints found 錯誤，或你需要自訂供應商設定，請將 Moonshot AI 的設定加入你的 opencode.json 檔案：
{"$schema": "https://opencode.ai/config.json","provider": {"moonshotai": {"name": "Moonshot AI","options": {"baseURL": "https://api.moonshot.ai/v1"},"models": {"kimi-k2.6": {"name": "Kimi K2.6"},"kimi-k2.5": {"name": "Kimi K2.5"}}}}}儲存檔案並重新啟動 OpenCode 以套用變更。
步驟 4：查看可用的 Kimi 模型
連接供應商後，執行：
/modelsOpenCode 會顯示透過你的 Moonshot AI 帳號可用的所有模型，包括：
| 模型 | 說明 |
|---|---|
| kimi-k2.6 | 最新旗艦模型，採用 1T MoE 架構，具備進階的程式碼撰寫與推理能力 |
| kimi-k2.5 | 針對程式碼撰寫與長上下文任務優化的高效能模型 |
| moonshot-v1-128k | 適用於文件分析的長上下文模型 |
| moonshot-v1-32k | 適合一般任務的均衡型模型 |
| moonshot-v1-8k | 適合快速回應的短上下文模型 |
步驟 5：選擇 Kimi 模型並開始編寫程式碼
選擇 moonshotai/kimi-k2.6 並將其設為使用中模型。選定後，OpenCode 會使用所選的 Kimi 模型執行程式碼生成、除錯、重構及其他 AI 輔助開發任務。
你隨時可以透過同一個模型選擇選單切換至其他模型。
提示：如果你在 Agent/Tool 模式下遇到問題（例如 JSON Schema 驗證錯誤），這是 Moonshot AI 嚴格的 schema 要求與 OpenCode 工具參數格式之間已知的相容性問題。建議使用 Chat 模式以獲得最佳穩定性，或安裝
opencode-moonshot-compatibility外掛程式，自動處理溫度參數的相容性問題。
使用 Kimi API 的優勢
Kimi API 旨在支援現代開發流程，協助團隊更有效率地將想法落實為實際成果。除了程式碼生成外，它還能理解多種類型的輸入內容，配合專案需求進行調整，並自動處理常規的工程任務。以下是它的幾項主要優勢：
將多模態輸入轉化為可執行的實作
Kimi API 能夠解讀多種格式的資訊，包括設計稿、架構圖、流程圖和影片。它會運用這些內容來理解專案需求，並將其轉換為技術規格或可執行的程式碼。因此，團隊可以減少人工轉換的步驟，更快從概念邁向實作。
處理長流程編碼與複雜工程任務
Kimi API 協助 OpenCode 處理需要規劃、一致性與反覆調整的較大型編碼任務，適用於功能開發、程式碼重構以及解決複雜的工程問題。
透過多步驟工具呼叫進行推理
Kimi API 能對多步驟任務進行推理，並在需要時呼叫工具，有助於除錯、程式碼分析，以及無法在單次回應中完成的工作流程。
安裝 OpenCode 時遇到問題該如何解決？
安裝 OpenCode 通常很簡單，但使用者可能會因為環境不匹配、依賴套件或設定問題而遇到常見的安裝錯誤。以下提供清晰實用的指引，協助你快速有效地解決最常見的安裝問題。
Command not found: opencode
若出現此錯誤，表示系統在 PATH 中找不到 OpenCode 的可執行檔。這通常是因為安裝未完成，或環境變數設定不正確所致。
要解決此問題，請先確認安裝是否完成，並確保二進位檔目錄已加入系統 PATH。若透過 npm 安裝，請檢查全域 npm bin 路徑，並相應更新你的 shell 設定。修正後重新啟動終端機通常就能解決問題。
Node.js 版本過舊
OpenCode 需要 Node.js 18 或更高版本，過舊的版本會導致安裝或執行失敗。
要解決此問題，請使用 node --version 檢查目前版本。若版本過舊，請使用像 nvm 這類版本管理工具升級 Node.js。升級後重新安裝 OpenCode，以確保與更新後的執行環境相容。
npm 權限錯誤
權限錯誤通常發生在 npm 嘗試安裝全域套件卻沒有足夠的寫入權限時。
不要使用 sudo，而是在你的家目錄中設定專屬的 npm 全域目錄，並更新 PATH 設定，這樣能確保安裝更安全、更穩定。修正權限問題後，重新執行安裝指令即可完成設定。
網路／防火牆問題
在受限網路或企業環境中，OpenCode 安裝可能因 npm 註冊表被封鎖或下載速度過慢而失敗。
要解決此問題，可切換至其他 npm 註冊表，或使用 curl 之類的直接安裝方式或二進位檔下載。此外，請確保防火牆允許 Node.js 與 npm 的網路流量，因為連線被封鎖常會中斷套件安裝。
TUI 顯示問題
若 OpenCode 能開啟但畫面錯亂、排版異常或出現亂碼，問題通常出在終端機相容性上。
請使用支援真色彩與 Unicode 顯示的現代終端機模擬器，例如 Windows Terminal、WezTerm 或 iTerm2。更新終端機設定或更換執行環境通常能立即解決顯示問題。
結語
正確安裝並設定 OpenCode，可確保在不同系統上都能順暢運作，同時降低常見安裝錯誤的發生機率。只要妥善管理依賴套件、終端機設定與 API 連線，使用者就能快速排除問題，維持穩定的開發環境。整合像 Kimi API 這類外部服務，能進一步提升靈活性，讓工作流程中可運用更進階的模型能力。