安裝 OpenCode 時，若設定錯誤中斷流程，或工具未如預期執行，可能會讓人感到困惑。從找不到指令到 Node.js 相容性問題，使用者經常在初次安裝時遇到困難。本 OpenCode 安裝指南提供完整解決方案，協助您排除常見錯誤，並在 Mac 與 Windows 上成功設定 OpenCode。無論您使用桌面版或 CLI/TUI，都能順利開始程式設計，不必延誤。
什麼是 OpenCode？
OpenCode 是一款開源 AI 程式設計 agent，協助開發人員直接在偏好的環境中撰寫、編輯、偵錯及管理程式碼，不論是終端機、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 Desktop？
安裝 OpenCode Desktop 的流程很直接，只需幾個簡單步驟即可讓應用程式開始運作。請依照以下步驟操作。
步驟 1：下載 OpenCode Desktop
前往 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 上啟動「終端機」App。您可從「應用程式」>「工具程式」>「終端機」開啟，也可使用 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。為獲得最佳相容性與使用體驗，官方文件建議使用適用於 Linux 的 Windows 子系統（WSL）。以下步驟採用 WSL 安裝方式。若已安裝 WSL，可略過第一個步驟。
步驟 1：安裝 WSL（建議）
以系統管理員身分開啟 PowerShell，然後執行以下指令：
wsl --install此指令會啟用適用於 Linux 的 Windows 子系統（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 金鑰後，您便能使用不同的語言模型，並選擇最符合程式設計流程的模型。
將外部 API 整合至 OpenCode（一般步驟）
以下說明如何將外部 API 整合至 OpenCode：imi
步驟 1：建立帳戶並產生 API 金鑰
首先，向您偏好的 AI 服務供應商建立帳戶，例如 Kimi 或其他支援的服務。完成帳戶設定後，前往該供應商的 API 金鑰管理頁面，產生新的 API 金鑰。請妥善保管此金鑰，因為將供應商連線至 OpenCode 時需要使用它。
步驟 2：開啟供應商連線選單
啟動 OpenCode 並開啟工作區。在命令介面中執行以下命令：
/connect此命令會開啟供應商連線選單，您可在此新增及管理外部 AI 服務。
步驟 3：新增 API 金鑰
從可用選項清單中選取您要使用的供應商。出現提示時，貼上先前產生的 API 金鑰，並確認連線。OpenCode 會安全地儲存此金鑰，並用於驗證向所選供應商發出的請求。
┌ API key
│
│ your_api_key_here
│
└ enter步驟 4：查看可用模型
連線供應商後，執行以下命令即可查看該 API 提供的所有模型：
/modelsOpenCode 會顯示支援的模型清單，以及各模型的名稱與設定選項。
步驟 5：選取模型並開始使用
從可用清單中選擇您要使用的模型。選取後，OpenCode 會透過該模型處理您的請求，讓您能使用已連線的 API 產生程式碼、偵錯應用程式及執行其他開發工作。若需求改變，之後也可以切換模型。
將 Kimi API 整合至 OpenCode
OpenCode 支援多個 AI 供應商，讓開發者能透過 API 金鑰連接外部模型，享有更高的彈性。其中一個強大的選項是 Kimi API。
Kimi API 由 Moonshot AI 開放平台提供，透過與 OpenAI 相容的介面，讓您存取進階 Kimi 語言模型。您可使用安全的 API 金鑰，輕鬆將其整合至程式設計工具、應用程式及 AI 驅動的工作流程。平台提供多種 Kimi 模型，針對程式設計、推理及長上下文理解等工作進行最佳化。
請依照以下步驟將 Kimi API 整合至 OpenCode。
步驟 1：建立 Moonshot AI 帳戶並產生 API 金鑰
前往 Kimi AI 開放平台 並登入您的帳戶。
在儀表板中前往 API Keys，然後按一下 Create API Key。
金鑰產生後（以
sk-開頭），請立即複製並安全保存。此金鑰只會顯示一次，用於驗證 OpenCode 與 Moonshot AI 之間的請求。
步驟 2：將 Moonshot AI 連線至 OpenCode
開啟您的 OpenCode 工作區並執行：
/connect供應商連線選單會隨即出現。在內建供應商清單中搜尋 Moonshot AI（或 Kimi）並選取它。OpenCode 會提示您輸入 API 金鑰。
出現提示時，貼上您從 Moonshot AI 主控台產生的 API 金鑰，然後按 Enter：
┌ API key
│ sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
│
└ enter驗證完成後，OpenCode 會將憑證安全地儲存至 ~/.local/share/opencode/auth.json，並將其與您的 Moonshot AI 供應商設定建立關聯。
注意：為了安全起見，OpenCode 會將 API 金鑰與主要設定檔分開儲存。
/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-k3": {"name": "Kimi K3"},"kimi-k2.7-code": {"name": "Kimi K2.7 Code"}}}}}儲存檔案後重新啟動 OpenCode，以套用變更。
步驟 4：查看可用的 Kimi 模型
連線供應商後，執行：
/modelsOpenCode 會顯示您 Moonshot AI 帳戶可用的所有模型，包括：
| 模型 | 說明 |
|---|---|
| kimi-k3 | 最新旗艦模型，具備 100 萬 token 上下文視窗，以及進階程式設計與推理能力 |
| kimi-k2.7-code | 專用程式設計模型，具備 256K 上下文與思考模式 |
| kimi-k2.7-code-highspeed | 程式設計模型的高速版本，可更快產生輸出 |
| kimi-k2.6 | 通用模型，具備 256K 上下文、思考與非思考模式 |
步驟 5：選取 Kimi 模型並開始撰寫程式碼
選取 moonshotai/kimi-k3 並將其設為使用中的模型。選取後，OpenCode 會使用所選的 Kimi 模型進行程式碼產生、偵錯、重構及其他 AI 輔助開發工作。
您隨時都可以透過相同的模型選擇選單切換至其他模型。
提示：如果您在 Agent/Tool 模式中遇到問題（例如 JSON Schema 驗證錯誤），這是 Moonshot AI 的嚴格結構描述要求與 OpenCode 工具參數格式之間已知的相容性問題。為取得最佳穩定性，建議使用 Chat 模式，或安裝
opencode-moonshot-compatibility外掛程式，自動處理 temperature 相容性。
使用 Kimi API 的優點
Kimi API 旨在支援現代開發工作流程，協助團隊更有效率地將想法化為實作。除了產生程式碼外，它還能理解不同類型的輸入、配合專案需求，並自動化例行工程工作。以下是幾項主要優點：
將多模態輸入轉化為可運作的實作
Kimi API 能解讀多種格式的資訊，包括設計稿、架構圖、流程圖和影片。它會運用這些脈絡來理解專案需求，並將其轉化為技術規格或可運作的程式碼。因此，團隊能以更少的人工轉譯步驟，從概念推進至實作。
處理長週期程式開發與複雜工程任務
Kimi API 可協助 OpenCode 處理需要規劃、一致性與反覆完善的大型程式開發任務。它適合用於建置功能、重構程式碼及解決複雜的工程問題。
透過多步驟工具呼叫推理問題
Kimi API 能針對多步驟任務進行推理，並在需要時呼叫工具。這有助於除錯、程式碼分析，以及無法在單次回應中完成的工作流程。
安裝 OpenCode 時遇到問題該如何排除？
安裝 OpenCode 通常很簡單，但使用者可能因環境不相容、相依套件或設定問題而遇到常見的安裝錯誤。以下提供清楚實用的指南，協助您快速有效地排除最常見的安裝問題。
找不到指令：opencode
若看到此錯誤，表示系統無法在您的 PATH 中找到 OpenCode 執行檔。通常是因為安裝未完成，或環境變數設定不正確。
若要修正此問題，請先確認安裝狀態，並確保二進位檔目錄已加入系統 PATH。若是透過 npm 安裝，請檢查全域 npm bin 路徑，並據此更新 shell 設定。完成修正後，重新啟動終端機通常就能解決問題。
Node.js 版本過舊
只有透過 npm 安裝時才需要 Node.js 環境；安裝指令碼與套件管理工具（Homebrew、Scoop、Chocolatey）會安裝不需要 Node.js 的獨立二進位檔。
若您透過 npm 安裝時遇到版本錯誤，請使用 node --version 檢查目前版本，並透過 nvm 等版本管理工具升級 Node.js。升級後，請重新安裝 OpenCode，以確保與更新後的執行階段環境相容。
npm 權限錯誤
當 npm 嘗試安裝全域套件卻沒有適當的寫入權限時，通常會發生權限錯誤。
請勿使用 sudo，改在家目錄中設定專用的 npm 全域目錄，並更新 PATH 設定。這能讓安裝更安全且更穩定。修正權限後，重新執行安裝指令即可順利完成設定。
網路／防火牆問題
在受限網路或企業環境中，OpenCode 可能因 npm registry 存取遭封鎖或下載速度緩慢而安裝失敗。
若要修正此問題，請切換至其他 npm registry，或使用 curl 或下載二進位檔等直接安裝方式。此外，請確認防火牆允許 Node.js 和 npm 流量，因為遭封鎖的連線常會中斷套件安裝。
TUI 顯示問題
若 OpenCode 能開啟但畫面顯示異常、排列錯位或出現亂碼，通常是終端機相容性問題。
請使用支援真實色彩和 Unicode 顯示的現代終端機模擬器，例如 Windows Terminal、WezTerm 或 iTerm2。更新終端機設定或切換環境，通常可立即解決顯示問題。
結語
正確安裝與設定 OpenCode，可確保它在不同系統上順暢運作，並降低常見設定錯誤的風險。妥善管理相依套件、終端機設定與 API 連線後，使用者便能快速排除問題並維持穩定的開發環境。整合 Kimi API 等外部服務，還能在工作流程中存取進階模型，進一步提升彈性。