在 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） 模式或订阅计划。使用自己的 API Key 可以突破 CodeGPT 平台的交互次数限制，模型消耗的 Token 费用直接结算给对应的模型服务商。
配置提供商与密钥的步骤
- 安装并同步账号：在 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 模式重要操作提示：配置好自己的 Key 之后，必须在聊天面板顶部的模型选择下拉框中明确选中具体模型。如果未选择模型就直接发送对话，插件会报错提示“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，根据语义关联检索最相关的代码段送入上下文。
- 手动添加文件与引用：点击输入框下方的
+Add Context按钮，选择#Files可精确锁定某些文件作为上下文；也可以在输入框中使用@符号快速引用当前打开的文件或函数。 - 自动包含当前文件：在 CodeGPT 设置（点击
⚙️图标）中，可开启将当前活动编辑器文件自动附加到提示词中的选项。
3. 结合工作区上下文解释代码
阅读老项目或复杂的业务逻辑时，脱离上下文的解释往往只能浮于表面语法。
推荐的运行模式：Search Mode（搜索模式）
CodeGPT 在聊天窗口提供了三种预设的 Profile 模式：
- Chat Mode（聊天模式）：不调用任何工作区与文件工具，仅处理通用问答与即时片段。
- Search Mode（搜索模式，推荐用于代码解释）：只读模式。允许 AI 探索工作区目录树、执行语义代码搜索、读取依赖文件，但不会修改任何本地文件。既保证了分析的深度，又杜绝了误改风险。
- Agent Mode（智能体模式）：具备创建、修改、删除文件和执行终端命令的完全权限，适合动手编码与重构。
代码解释的标准流程
- 选中目标代码：在 VS Code 编辑器中高亮需要理解的函数、类定义或疑难业务块。
- 触发
/Explain命令：- 在 CodeGPT 聊天输入框中输入快捷命令
/Explain并按回车。 - 或者在编辑器中右键点击选中区域，在右键菜单中选择 Explain CodeGPT。
- 在 CodeGPT 聊天输入框中输入快捷命令
- 基于全局上下文的分析：因为工作区已建立索引，CodeGPT 不仅能解释语法逻辑，还会结合语义搜索指出所调用的工具函数在何处定义、入参从哪个控制器传入、遵循了项目中的何种设计模式。
- 追问细节：在 Search Mode 下，可以进一步就跨文件关联进行提问，例如：
- “这个中间件在工作区里哪些路由中生效了？”
- “解释这个类型定义与数据访问层的映射关系。”
4. 深度重构与渐进式应用
代码重构最忌讳“修了这里，坏了那里”。借助已索引的工作区上下文，CodeGPT 能够在重构时兼顾调用签名一致性与项目既有规范。
重构执行流程
- 选定重构目标：在编辑器中高亮待重构的代码块。
- 触发
/Refactor命令：- 在聊天框中输入
/Refactor并附带具体要求（例如：/Refactor 将此处的嵌套回调改写为 async/await，并提取数据验证逻辑），按回车提交。 - 或者直接右键选择 Refactor CodeGPT。
- 在聊天框中输入
- 评估与采纳修改：
- 在 Search Mode 或 Chat Mode 下：CodeGPT 会在聊天面板中生成格式规范的重构代码对比与说明。确认无误后，点击代码块右上角的 Insert code（箭头图标），即可直接将重构结果插入或覆盖到当前活动文件。
- 在 Agent Mode 下：CodeGPT 能够调用内置的
Edit File工具直接在磁盘上更新文件。如果你在设置中开启了确认审批模式，插件会先向你展示改动，待你确认后再写入。
提升重构可靠性的实战建议
- “先 Search，后 Agent”的双阶段工作流：先在 Search Mode 下让 AI 扫描整个代码库，评估修改该函数会牵扯哪些下游调用；确认方案完备后，再切换到 Agent Mode 实施文件修改。
- 执行终端验证：在 Agent Mode 下，可以指示 CodeGPT 运行项目的测试命令（如
npm test或pytest），通过内置的Run Terminal Command工具直接在终端中验证重构后测试是否通过。 - 及时更新索引：在完成大规模重构、执行大型 Git 分支合并或添加大量依赖之后，建议再次点击 Codebase 菜单中的重新索引，确保语义向量库与当前最新代码保持一致。