在 Visual Studio Code 中使用 CodeGPT 時，若僅將其作為標準對話視窗，它僅能看到手動貼上的局部程式碼。要讓 CodeGPT 真正理解專案整體架構，並在多檔案之間準確進行程式碼解說與重構，關鍵在於完成兩大核心設定：連接自訂 API Key（BYOK 模式與自訂模型端點） 以及 對本地工作區建立索引（Codebase Indexing）。完成配置後，結合 CodeGPT 內建的語意搜尋工具（Semantic Search Tool）與多 Profile 模式，開發者便能直接在編輯器內跨檔案追蹤邏輯並進行精準重構。
1. 連接自訂 API Key（BYOK 與自訂端點）
CodeGPT 採取彈性的混合運作模式：新使用者享有免費體驗額度（每月 30 次互動），但在真實的專案開發中，通常推薦採用 BYOK（Bring Your Own Key） 模式或團隊訂閱。透過自備金鑰，開發者可以解除 CodeGPT 平台的訊息次數限制，模型 Token 消耗費用則直接與對應的 AI 服務商結算。
提供商與金鑰設定步驟
- 安裝擴充功能並同步帳號：在 VS Code 擴充功能市集中搜尋並安裝由
DanielSanMedium發布的 CodeGPT: AI Coding Agents & Chat。安裝後點擊活動列的 CodeGPT 圖示，透過 Google、GitHub 或電子郵件登入以同步帳號狀態。 - 開啟提供商管理介面：
- 在 CodeGPT 聊天側邊欄底部點擊 Manage Models 按鈕，切換至 Providers 分頁。
- 或者使用快速鍵開啟 VS Code 命令選擇區（Windows/Linux 按
Ctrl+Shift+P，macOS 按Cmd+Shift+P），輸入並執行CodeGPT: Set API KEY。
- 選取 AI 提供商：
- CodeGPT 原生支援 OpenAI、Anthropic、Google AI Studio、DeepSeek、Mistral、Cohere、Groq、Cerebras、Perplexity，以及本地運行的 Ollama 與 LM Studio。
- 在選取的服務商欄位中貼上官方主控台產生的 API Key（若帳號有組織劃分，可一併輸入 Organization ID）。
- 設定自訂 OpenAI 相容端點（Custom Provider）：
- 若使用企業內部私有部署的大型語言模型（如 vLLM、遠端 Ollama 執行個體）或第三方轉發閘道，可在提供商清單中選擇 Custom。
- 輸入目標模型名稱（例如
cognitivecomputations/dolphin3.0-mistral-24b:free或專案自訂模型名稱）。 - 輸入對應的 API Key。
- 填寫完整的補全端點網址（Custom Link，即
/chat/completions的 HTTP URL）。 - 點擊 Connect 完成連線。
- BYOK 模式重要操作細節：設定完成後，必須在聊天面板頂部的模型選單中明確選取具體模型。若未選取模型即發送訊息，系統將顯示「You must select a model first」的錯誤提示。
2. 建立本地工作區索引（Augmented Context）
大型語言模型預設無法得知工作區內未開啟的檔案或跨模組關聯。CodeGPT 提供了**程式碼庫索引（Codebase Indexing）**功能，透過在本地建立向量資料庫，為 AI 賦予全局上下文認知能力。
反白選取程式碼 vs. 程式碼庫索引
- 反白選取（Highlighting）：適用於單一函式解析、除錯特定錯誤訊息或快速提問，無需調用整個專案。
- 程式碼庫索引（Codebase Indexing）：適用於涉及多檔案互動、介面定義分散在不同目錄，或需要確保重構符合專案既有架構的大型開發工作。
如何建立工作區程式碼庫索引
- 開啟 CodeGPT 側邊欄，在主選單的 Augmented Context 區域找到 Codebase 按鈕。
- 點擊 Create Codebase Index。
- 在彈出的資料夾選取視窗中，選擇目前工作區的專案根目錄。
- CodeGPT 會掃描專案檔案結構並在本地建立向量索引。
- 索引完成後，AI 助手將自動啟用內建的 Semantic Search Tool（語意搜尋工具）。
在對話中動態載入上下文
- 自動語意檢索：提問涉及全域概念或跨模組功能時，CodeGPT 會自動調用 Semantic Search Tool，將相關程式碼片段納入 Prompt 上下文中。
- 手動附加檔案與參考：點擊聊天視窗下方的
+Add Context並選擇#Files，可精確釘選指定檔案；亦可在輸入框輸入@符號快速參照作用中的編輯檔案或符號。 - 自動包含作用中檔案：在 CodeGPT 設定（點擊
⚙️圖示）中，可開啟自動將目前編輯中檔案附加至對話的選項。
3. 結合工作區上下文進行程式碼解說
在維護既有系統或探索大型程式碼庫時，若缺少上下文，AI 僅能解說語法表面。
建議採用的設定檔模式：Search Mode（搜尋模式）
CodeGPT 在聊天面板提供了三種預設 Profile 模式：
- Chat Mode（聊天模式）：不啟用任何檔案工具，專注於通用問答與語法概念探討。
- Search Mode（搜尋模式，推薦用於程式碼解說）：唯讀探索模式。AI 可以主動搜尋專案結構、調用語意搜尋並讀取關聯檔案，但不會對磁碟檔案進行任何修改，兼具深度探索與作業安全。
- Agent Mode（代理模式）：具備建立、編輯、刪除檔案與執行終端機指令的完整權限，適用於主動開發與重構。
程式碼解說的操作流程
- 反白目標程式碼：在 VS Code 編輯器中選取欲深入理解的函式、類別或複雜邏輯片段。
- 執行
/Explain指令：- 在 CodeGPT 聊天視窗中輸入
/Explain並按下 Enter。 - 或在編輯器中點擊右鍵，由快捷選單中選擇 Explain CodeGPT。
- 在 CodeGPT 聊天視窗中輸入
- 整合專案架構的深度解說：受惠於工作區索引，CodeGPT 會自動追蹤被選取函式的相依套件、跨檔案呼叫來源與資料流走向，提供具備專案脈絡的結構化說明。
- 深入延伸詢問：在 Search Mode 下，可進一步針對專案全域關聯提問，例如：
- 「這個驗證邏輯在哪些 API 路由中被引用過？」
- 「請說明此類別與資料庫儲存庫（Repository）之間的互動流程。」
4. 具備全域認知的安全程式碼重構
跨檔案重構最常遇到的痛點是修改了介面卻破壞了調用端。CodeGPT 透過斜線指令與可控權限，協助開發者完成可靠重構。
程式碼重構操作流程
- 標記重構目標：在編輯器中反白待改進的程式碼區塊。
- 觸發
/Refactor指令：- 在聊天框中輸入
/Refactor並指明改進目標（例如：/Refactor 將回呼函式重構為 async/await，並抽出獨立的資料驗證輔助函式），按下 Enter。 - 或直接透過編輯器右鍵選單點擊 Refactor CodeGPT。
- 在聊天框中輸入
- 檢視與套用修改：
- 在 Search Mode 或 Chat Mode 中：CodeGPT 會在對話面板中輸出重構後的程式碼區塊。檢查邏輯無誤後，點擊該程式碼區塊右上角的 Insert code（箭頭圖示），即可直接將重構結果套用至作用中的檔案。
- 在 Agent Mode 中：CodeGPT 會調用內建的
Edit File工具直接對磁碟檔案執行編輯。若設定中未開啟 Auto-Approve，系統會在每一次檔案變更前請求你的確認。
確保重構品質的實務建議
- 先 Search 後 Agent 的漸進流程：重構前先在 Search Mode 中評估改動對專案其他檔案的衝擊；擬定修改策略後，再切換到 Agent Mode 執行檔案落地修改。
- 整合終端機測試驗證：在 Agent Mode 下，可要求 CodeGPT 執行專案的自動化測試指令（如
npm test或pytest），透過其Run Terminal Command工具直接在整合終端機中驗證重構成果。 - 維持最新索引狀態：在執行大型分支合併或大量檔案搬移後，建議前往 Codebase 選單重新執行索引，以確保語意向量資料庫與目前工作區檔案完全同步。