Cline
在 Cline 中設定和使用 AGTCloud。
Cline 是執行在 IDE 中的程式開發代理程式，可以讀取專案檔案、執行命令並在獲得允許後修改程式碼。透過設定 OpenAI Compatible Provider，可以讓 Cline 使用 AGTCloud 的 Chat Completions 相容入口。
本教學介紹 Cline IDE 擴充。不同模型對工具呼叫、圖片輸入、Computer Use 和上下文長度的支援範圍可能不同，請選擇目前 API Key 可見且支援 Chat Completions 與工具呼叫的模型。
準備工作
開始前，請確認你已經：
- 安裝受支援的 VS Code 相容編輯器或 JetBrains IDE；
- 註冊並登入 AGTCloud；
- 在 API Keys 頁面建立權杖；
- 從模型廣場複製目前權杖可用且支援 Chat Completions 的模型 ID；
- 準備一個不包含敏感程式碼的測試專案。
安裝 Cline
選擇與你使用的 IDE 對應的安裝方式。Cline 也提供 CLI、SDK 和 Kanban 等形態，本教學不展開這些用法。
適用於 VS Code、Cursor、Windsurf、VSCodium 等編輯器：
- 開啟擴充市集，或按
Ctrl/Cmd + Shift + X； - 搜尋
Cline； - 選擇 Cline 官方擴充並點選安裝；
- 點選活動欄中的 Cline 圖示，或從命令面板執行
Cline: Open In New Tab。
Windsurf 和 VSCodium 使用 Open VSX，安裝流程基本相同。
如果首次開啟時出現 Cline 授權或初始化提示，請按照目前版本介面完成。其他安裝方式請檢視 Cline 官方安裝文件。
設定 AGTCloud
開啟 API Configuration
開啟 Cline 面板，點選設定圖示，然後進入 API Configuration。不同 IDE 和 Cline 版本中的設定入口位置可能略有不同。
選擇相容 Provider
在 API Provider 中選擇 OpenAI Compatible。不要選擇內建的 OpenAI Provider。
填寫連線資訊
| Cline 欄位 | 填寫內容 |
|---|---|
API Provider | OpenAI Compatible |
Base URL | https://api.agtcloud.cn/v1 |
OpenAI Compatible API Key | your-api-key |
Model ID 或 Model | MODEL_ID |
Custom Headers | 預設留空 |
請將 your-api-key 和 MODEL_ID 替換為自己的權杖和模型 ID。
驗證並儲存
如果目前版本提供 Verify 按鈕，請先驗證連線。驗證通過後，點選 Done 或目前介面的儲存按鈕完成設定。
Base URL 必須包含 /v1
Cline 的 OpenAI Compatible Provider 需要填寫完整 API Base URL。請使用 https://api.agtcloud.cn/v1，不要只填寫 API Origin，也不要額外追加 /v1 形成 /v1/v1。
選擇和設定模型
MODEL_ID 是需要替換的預留位置，不是真實模型名稱。請從模型廣場複製目前 API Key 可見且支援 Chat Completions 與工具呼叫的模型 ID。
Cline 的 Model Configuration 可能提供 Context Window、Max Output Tokens、Image Support、Computer Use、Input Price 和 Output Price 等進階選項。首次連線時建議保持預設值；只有掌握目標模型的真實限制和能力時再進行調整。
進階設定不是模型能力來源
在 Cline 中勾選圖片或 Computer Use 支援，不會讓不具備該能力的模型獲得新能力。價格欄位主要用於 Cline 的本機用量估算，不代表 AGTCloud 最終計費結果。
啟動並驗證連線
開啟測試專案
使用不包含敏感程式碼的專案，並確認其中存在可安全讀取的 README.md。
保持自動核准關閉
首次驗證時不要啟用 Auto Approve。Cline 準備讀取檔案、執行命令或修改程式碼時，先檢查操作內容再決定是否允許。
檢查結果
Cline 能夠讀取檔案並正常傳回概括，且沒有發生未授權修改，說明基本連線已經建立。本步會產生正常的 API 用量。
常見問題
| 現象 | 優先檢查 | 處理方式 |
|---|---|---|
| Cline 擴充未顯示 | 安裝來源、IDE 相容性和重新啟動狀態 | 確認安裝的是 Cline 官方擴充，重新載入或重新啟動 IDE |
Verify 連線失敗 | 網路和 Base URL | 確認本機可存取 AGTCloud，並使用完整的 https://api.agtcloud.cn/v1 |
傳回 401 | API Key 內容和權杖狀態 | 重新複製有效 API Key，並確認填寫內容沒有多餘空格 |
傳回 403 | 權杖權限、模型權限和帳戶狀態 | 在控制台檢查權杖狀態及目前帳戶的模型可用範圍 |
傳回 404 | Base URL、重複 /v1 和模型 ID | 確認沒有形成 /v1/v1，並重新複製完整模型 ID |
| 提示 Model Not Found | 目前 Key 可見模型和協議支援 | 選擇目前 API Key 可見且支援 Chat Completions 的模型 |
| 對話正常但工具失敗 | 工具呼叫能力和進階設定 | 換用支援工具呼叫的模型，並檢查上下文和輸出上限設定 |
| 圖片或 Computer Use 失敗 | 模型真實能力 | 不要只依賴 Cline 選項；以目標模型實際支援範圍為準 |
| 結果異常或連線中斷 | 網路代理、模型參數和上下文限制 | 先恢復預設進階設定，再檢查代理、防火牆和模型上下文限制 |
遇到無法定位的問題時，請記錄請求時間、模型 ID、HTTP 狀態和去識別化錯誤資訊，然後檢視錯誤與疑難排解。不要提交完整 API Key。
安全建議
- 不要把 API Key 寫入專案檔案、Git 倉庫、截圖、記錄或共享設定；
- 不要在包含正式環境憑證、私有資料或未公開原始碼的專案中進行首次驗證；
- 首次使用保持 Auto Approve 關閉，確認每項操作後再允許執行；
- 多人共用裝置時，使用完畢後清除 Cline 中儲存的 API Key。