什麼是 OpenCode？
OpenCode 是一款開源的 AI 程式碼 agent，可在終端機中執行，也能透過桌面、IDE 及伺服器端工作流程使用。它能協助開發者處理程式碼庫，包括讀取檔案、解釋結構、編輯程式碼、審查變更，以及透過連接的 LLM 供應商執行任務。你可以將它連接到模型供應商，例如 Kimi API，OpenCode 便會利用該供應商在你的開發環境中進行規劃、推理與執行操作。
你可以用 OpenCode 做什麼？
當你想要一套能直接處理你專案的 AI 程式碼工作流程時，可以選擇 OpenCode。舉例來說：
撰寫、編輯與重構程式碼：你可以請 OpenCode 新增功能、修改現有檔案、重構函式，或解釋某個模組應該如何調整。為了獲得最佳效果，請明確指出涉及的檔案或目錄。
除錯與產生測試：OpenCode 可以檢查錯誤輸出、讀取相關檔案、提出修正建議並新增測試。當錯誤與專案的上下文有關時，這特別有用。
審查程式碼變更：你可以在提交（commit）之前，使用 OpenCode 審查本地端的變更，它能找出可能的錯誤、缺少的測試、不一致的寫法以及風險較高的修改。
自動化開發工作流程：OpenCode 也支援非互動式與伺服器端的工作流程。例如，你可以從命令列執行一次性的提示詞，或啟動一個無介面（headless）的 OpenCode 伺服器，讓其他客戶端或整合服務與之連接。
設定 OpenCode 連接 LLM API 的前置條件
在使用 LLM API 設定 OpenCode 之前，請先準備好以下事項：
一個可正常運作的終端機環境，支援 macOS、Linux，建議在 Windows 上使用 WSL。
Node.js、Homebrew 或其他受支援的安裝方式。
一個可以安全用來測試的專案資料夾。
一個模型供應商帳號。
使用 OpenCode 時要注意，供應商憑證屬於敏感資訊。切勿將金鑰貼到公開的 issue、共享截圖、原始碼檔案，或提交到版本控制的設定檔中。
步驟一：安裝 OpenCode
根據 OpenCode 官方文件，最快的安裝方式是使用安裝指令碼。在終端機中執行：
OpenCode 也支援透過 npm、Homebrew 及其他方式安裝。如果你偏好使用桌面版，可以下載符合你裝置的版本。
步驟二：啟動 OpenCode
前往你希望 OpenCode 處理的專案：
啟動 OpenCode：
如果這是你第一次在該專案中使用 OpenCode，請在 TUI 內進行初始化：
如何以 LLM API 設定 OpenCode
在大多數情況下，「OpenCode API」指的是透過 API 金鑰將 OpenCode 連接到外部 LLM 供應商。供應商負責提供模型，OpenCode 則在你的專案中處理程式碼代理（coding agent）的工作流程。以下步驟以 Kimi API 作為供應商範例。
步驟一：建立你的 Kimi API 金鑰
開啟 Kimi API 平台，在主控台中建立 API 金鑰，然後將其存放到密碼管理工具或密鑰管理工具中。如果主控台只會顯示一次完整金鑰，請務必在離開頁面前先複製下來。
步驟二：連接模型供應商
在你的專案中啟動 OpenCode：
在 OpenCode 介面中執行：
搜尋 Moonshot AI，或是你所使用的 OpenCode 版本所顯示的 Kimi 相容供應商項目。OpenCode 官方供應商文件中包含 Moonshot AI 供應商的設定流程：在 Moonshot AI 主控台建立金鑰，執行 /connect，搜尋 Moonshot AI，然後輸入 API 金鑰。
如果你的版本沒有列出 Moonshot AI，請更新 OpenCode 並重新整理模型清單：
步驟三：輸入你的 Kimi API 金鑰
當 OpenCode 要求輸入 API 金鑰時，貼上你的 Kimi API 金鑰。
OpenCode 會將供應商憑證儲存在本機的驗證檔案中。官方供應商文件列出了這個路徑：
一般情況下你不需要手動編輯該檔案，改用 OpenCode 的供應商 /connect 流程即可。
步驟四：選擇 Kimi 模型
連接供應商之後，在 OpenCode 中選擇模型：
選擇你想使用的 Kimi 模型。若是新的程式碼代理工作流程，建議從以下開始：
如果你需要以非互動方式搭配特定模型執行 OpenCode，請使用 OpenCode 模型清單中顯示的「供應商/模型」格式。例如：
接著使用 OpenCode 印出的確切模型識別碼。
步驟五：執行你的第一個程式碼任務
先從風險較低的任務開始，藉此確認供應商、模型、專案存取權限與各項許可都能正常運作：
預期結果：
接著嘗試一個小型的程式碼任務：
這可以確認 OpenCode 能夠讀取專案並對程式碼庫進行推理，之後你再允許它進行實際變更。
為什麼要在 OpenCode 中使用 Kimi API？
如果你想在程式碼與代理工作流程中使用與 OpenAI 相容的模型供應商，Kimi API 與 OpenCode 會是不錯的搭配。
強大的程式碼與推理能力
{{KIMI_MODEL_LATEST_FULL}} 官方定位為適用於長流程編碼、指令遵循、自我修正與 Agent 執行。這使它適合處理 OpenCode 任務,例如多檔案編輯、除錯、重構與程式審查。
支援長上下文,適用於更大型的專案
{{KIMI_MODEL_LATEST_FULL}} 的官方文件列出了 {{KIMI_MODEL_LATEST_FULL}} 及多款 K2 系列模型的長上下文支援。在 Agent 工作流程中,當任務需要讀取多個檔案、比較實作模式,或保留大量任務歷史時,長上下文能力會很有幫助。
相容 OpenAI 的 API,設定更簡單
Kimi API 相容於 OpenAI 的 API 格式。對於已支援 OpenAI 風格聊天補全的工具而言,通常只需設定 API 金鑰、Base URL 與模型名稱即可。
不限於 OpenCode 的彈性用途
你可以在其他相容 OpenAI 的開發者工具、直接腳本或內部工作流程中使用相同的 Kimi API 金鑰。若之後要使用 OpenCode server 或 OpenCode SDK,請先將 Kimi 設定為模型提供者。
你應該了解的關鍵 OpenCode API 設定
以下設定可解決大多數 OpenCode API 與提供者設定問題。
API 金鑰
API 金鑰用於向模型提供者驗證你的請求身分。在 OpenCode 中,你通常會這樣新增它:
提供者
提供者(provider)告訴 OpenCode 該模型來自何處。在本指南中,提供者為 Moonshot AI / Kimi API。其他提供者可以另外設定,但每個提供者都需要自己的憑證與模型清單。
Base URL
Base URL 是用於直接發出相容 OpenAI 的 API 請求的端點。若參考 Kimi API 範例,請使用目前 Kimi API 文件或帳號主控台中顯示的端點。
模型名稱
模型名稱必須與提供者提供的名稱完全一致。一個小小的拼寫錯誤就可能導致「找不到模型」的錯誤。
常見範例:
在 OpenCode 中,可用以下方式確認提供者/模型識別碼:
排除常見的 OpenCode API 錯誤
大多數設定問題來自以下五個環節之一:憑證、端點、提供者、模型名稱,或上下文大小。
驗證失敗
如果 API 金鑰貼錯、被刪除或已輪替,驗證就可能失敗。選錯提供者,或該金鑰所屬帳號、地區與 OpenCode 目前設定的不一致時,也會發生此問題。
解決方法:
重新連接提供者,並貼上一組全新的 API 金鑰。若你是使用環境變數進行直接測試,請重設金鑰:
端點無效錯誤
端點無效錯誤通常代表 OpenCode 無法連上正確的提供者端點。常見原因包括 Base URL 拼寫錯誤、在不同工具間混用 .ai 與 .cn 端點,或代理伺服器/防火牆在請求送達提供者前對其進行了改寫。
解決方法:
請確認目前 Kimi API 文件或主控台顯示的端點。若是直接進行 API 測試,請統一使用同一個端點:
不支援此模型
此錯誤可能發生於模型名稱拼寫錯誤、你的帳號無法使用所選模型,或 OpenCode 的模型清單快取已過時。也可能是 OpenCode 使用的提供者/模型識別碼與提供者文件中顯示的原始模型名稱不同所致。
解決方法:
然後重新選擇模型:
超出速率限制
速率限制錯誤通常代表提供者在短時間內收到過多請求。若同時執行多個 Agent 任務,或某個腳本/整合過於頻繁地重試失敗請求,都可能導致此情況。
解決方法:
暫停任務、減少並行執行數量,並到提供者主控台查看配額或帳務狀態。避免在 OpenCode 或直接呼叫 Kimi API 時撰寫無限重試迴圈。
上下文視窗溢位
上下文視窗溢位通常代表任務對模型來說一次處理的量太大。若納入的檔案過多、OpenCode 被要求檢視整個儲存庫,或長時間的工作階段累積了過多對話歷史,都可能發生此情況。
解決方法：
請 OpenCode 處理範圍較小的任務：
你也可以開啟一個新的工作階段，處理更聚焦的任務。
結語
OpenCode 可以將你的程式碼庫連接到模型供應商，並從終端機執行編碼任務。Kimi API 可以透過相容 OpenAI 的設定，為這些工作流程提供模型後端。如果你想要一個實用的編碼 Agent 工作流程，可以先建立你的 Kimi API 金鑰，在 OpenCode 中連接 Moonshot AI，選擇一個 Kimi 模型，然後執行一個小型專案任務來驗證設定是否正確。
常見問題
/connect 輸入到 OpenCode 中。OpenCode 會將 provider 的憑證儲存在本機，官方文件中列出的憑證檔案路徑為 ~/.local/share/opencode/auth.json。opencode models。若使用 Kimi API，請選擇 OpenCode 模型清單中顯示的確切 Kimi 模型識別碼，例如當你的帳號可用時的 kimi-k2.6。/connect。