CodeBuddy IDE 高级配置：如何灵活接入第三方与本地 AI 接口

目录

背景说明

CodeBuddy 是一款现代化的 AI 辅助编程 IDE。虽然它预设了主流的 AI 服务商，但在实际开发中，开发者往往需要接入性价比更高的第三方转发 API（如 DeepSeek、OpenRouter、OneAPI）或者运行在本地的私有化模型（如通过 Ollama 运行的 Llama 或 Qwen）。

CodeBuddy 提供了基于 models.json 的配置机制，允许用户通过符合 OpenAI 标准的接口协议，实现对任何兼容大模型的无缝集成。

核心知识点：models.json 配置文件

CodeBuddy 的模型扩展核心在于 models.json 文件。它支持两个维度的配置：

  1. ​全局级别​: 位于 ~/.codebuddy/models.json，配置后所有项目均可使用。
  2. ​项目级别​: 位于项目根目录的 .codebuddy/models.json，适用于特定项目的特殊模型需求。

1. 标准 OpenAI 兼容格式模板

要接入第三方接口，必须确保 vendor 字段设置为 OpenAI，并提供完整的 url 端点。

{
  "models": [
    {
      "id": "custom-model-id", 
      "name": "显示在界面上的名称",
      "vendor": "OpenAI",
      "apiKey": "你的API密钥", 
      "url": "https://api.your-provider.com/v1/chat/completions",
      "maxInputTokens": 128000,
      "maxOutputTokens": 4096,
      "supportsToolCall": true
    }
  ],
  "availableModels": [
    "custom-model-id"
  ]
}

2. 关键参数解析

  • ​**url**​: 必须是完整的聊天完成路径。如果第三方文档只给出了 Base URL，请务必手动补全 /v1/chat/completions。
  • ​**vendor**​: 强制填写为 OpenAI。这决定了 IDE 内部采用何种报文格式进行通信。
  • ​**availableModels​: ​至关重要**​。只有在该数组中声明过的 id，才会出现在 IDE 的模型切换下拉菜单中。

典型场景示例

场景 A：接入 DeepSeek 官方 API

DeepSeek 以极高的性价比成为首选，其配置如下：

{
  "models": [
    {
      "id": "deepseek-chat",
      "name": "DeepSeek-V3",
      "vendor": "OpenAI",
      "apiKey": "sk-xxxxxxxxxxxx",
      "url": "https://api.deepseek.com/v1/chat/completions"
    }
  ],
  "availableModels": ["deepseek-chat"]
}

场景 B：接入本地 Ollama 模型

对于追求代码私密性的开发者，可以使用本地部署的模型。

  • ​前提​: 确保 Ollama 已启动。
  • ​接口地址​: 通常为 http://localhost:11434/v1/chat/completions。
  • ​API Key​: Ollama 默认不检查 Key，可随意填写字符串。

问题排查指南

现象 可能原因分析 定位与解决方案
模型列表中找不到新加的模型 availableModels未包含该 ID 检查models中的id与availableModels中的字符串是否完全一致。
请求报错 404 URL 路径不完整 确认 URL 是否以/v1/chat/completions结尾。
连接超时/无法访问 网络防火墙或代理拦截 检查 IDE 的代理设置，或在终端尝试curl该接口地址。
JSON 配置不生效 语法错误 使用 JSON 校验工具检查是否有多余的逗号或缺失引号。

官方文档: https://www.codebuddy.ai/docs/zh/ide/Features/models

总结

通过自定义 models.json，CodeBuddy 不再局限于官方提供的固定选项。只要接口符合 OpenAI 规范，开发者就可以自由地在云端高性能模型与本地私有化模型之间切换，极大地提升了开发环境的灵活性与可扩展性。配置完成后，建议点击 IDE 设置中的 Refresh 按钮或重启 IDE 以确保配置实时生效。

↑