codebuddy 第三方大模型 api 配置教程：OpenRouter、DeepSeek 与本地模型接入

核心要点（TL;DR）

如果你正在找 codebuddy 第三方大模型 api 配置教程，先记住一个结论：CodeBuddy Code 接第三方模型主要有两条路线。第一条是用环境变量快速指定 CODEBUDDY_API_KEY、CODEBUDDY_BASE_URL 和 CODEBUDDY_MODEL；第二条是写 models.json，把 OpenRouter、DeepSeek、OpenAI 兼容网关或本地 Ollama 模型加入自定义模型列表。

这篇 codebuddy 第三方大模型 api 配置教程 更推荐第二种方式，因为 models.json 能明确写出模型 ID、接口地址、上下文长度、输出长度和工具调用能力，适合长期使用和团队共享。临时测试用环境变量，正式项目用 models.json，这是最稳的配置顺序。

适合谁阅读这篇教程

这篇文章适合三类人：

已经安装 CodeBuddy Code，但想把模型换成 OpenRouter、DeepSeek 或内部网关。
想写一份可复用的 codebuddy 第三方大模型 api 配置教程 给团队成员。
遇到 Base URL、model id、chat/completions 路径、API Key 不生效等问题，需要一套排障清单。

本文基于 CodeBuddy 官方文档里的配置项整理：settings.json 用于环境变量、权限和默认模型；models.json 用于自定义模型列表；环境变量可以控制 API Key、Base URL、默认模型和代理。[^1][^2][^3]

一、先理解 CodeBuddy 第三方大模型 API 的配置层级

在真正动手前，先把配置层级分清楚。否则你会遇到一个常见问题：明明改了一个文件，但 CodeBuddy 仍然在用旧模型。

CodeBuddy 的模型配置大致可以分为三层：

配置位置	作用	适合场景
临时环境变量	当前终端会话生效	快速测试第三方 API
`~/.codebuddy/models.json`	用户级自定义模型	个人长期使用
`<project>/.codebuddy/models.json`	项目级自定义模型	团队项目统一模型

官方文档说明，项目级 models.json 的优先级高于用户级 models.json，内置默认配置排在最后。换句话说，如果你在项目里写了 .codebuddy/models.json，它会优先覆盖全局模型配置。[^2]

二、快速方式：用环境变量配置第三方模型 API

如果你只是想先跑通一条链路，这种 codebuddy 第三方大模型 api 配置教程 的最短路径是环境变量。

以 OpenAI 兼容接口为例：

bash

export CODEBUDDY_API_KEY="sk-your-api-key"
export CODEBUDDY_BASE_URL="https://api.example.com/v1"
export CODEBUDDY_MODEL="your-model-id"

codebuddy

如果你只是临时启动一次，也可以写成一行：

bash

CODEBUDDY_API_KEY="sk-your-api-key" \
CODEBUDDY_BASE_URL="https://api.example.com/v1" \
CODEBUDDY_MODEL="your-model-id" \
codebuddy

官方环境变量参考里，CODEBUDDY_API_KEY 用于模型接口调用，CODEBUDDY_BASE_URL 用于覆盖 API 端点地址，CODEBUDDY_MODEL 用于覆盖默认代理模型。[^3]

这种方式适合测试，但不适合团队长期维护。原因很简单：环境变量只告诉 CodeBuddy 用哪个入口和哪个模型，不适合精细描述 maxInputTokens、maxOutputTokens、supportsToolCall、supportsImages 等能力。

三、推荐方式：用 models.json 配置第三方大模型

正式写 codebuddy 第三方大模型 api 配置教程 时，核心应该放在 models.json。官方文档说明，models.json 支持用户级和项目级两种位置：

text

~/.codebuddy/models.json
<project-root>/.codebuddy/models.json

如果你是个人使用，写到 ~/.codebuddy/models.json。如果你希望团队项目统一使用同一组模型，可以写到项目的 .codebuddy/models.json，但不要把真实 API Key 提交到 Git 仓库。

一个最小可用配置如下：

json

{
  "models": [
    {
      "id": "my-custom-model",
      "name": "My Custom Model",
      "vendor": "OpenAI Compatible",
      "apiKey": "${MY_LLM_API_KEY}",
      "url": "https://api.example.com/v1/chat/completions",
      "maxInputTokens": 128000,
      "maxOutputTokens": 4096,
      "supportsToolCall": true,
      "supportsImages": false
    }
  ],
  "availableModels": ["my-custom-model"]
}

然后在 shell 里设置：

bash

export MY_LLM_API_KEY="sk-your-real-key"
codebuddy --model my-custom-model

这才是比较完整的 codebuddy 第三方大模型 api 配置教程 写法：密钥放环境变量，模型能力写 models.json，启动时用 --model 或配置默认模型。

四、关键字段怎么填

CodeBuddy 官方文档给出的自定义模型字段里，最关键的是这几个：

字段	用法	注意点
`id`	模型唯一标识	启动时 `--model` 要用它
`name`	展示名称	方便在 UI 或列表里识别
`vendor`	模型供应商	可写 OpenAI、DeepSeek、Ollama、OpenRouter
`apiKey`	API 密钥	推荐写 `${ENV_NAME}`
`url`	接口完整路径	一般以 `/chat/completions` 结尾
`maxInputTokens`	最大输入 token	按供应商实际能力填写
`maxOutputTokens`	最大输出 token	不要盲目写太大
`supportsToolCall`	是否支持工具调用	编程 Agent 场景建议确认后再开启
`supportsImages`	是否支持图片输入	模型不支持就写 `false`

这里最容易踩坑的是 url。官方文档明确说，自定义模型目前仅支持 OpenAI 接口格式，url 字段必须是接口完整路径，一般以 /chat/completions 结尾。也就是说，下面这种写法更稳：

text

https://api.example.com/v1/chat/completions

不要只写：

text

https://api.example.com/v1

很多 codebuddy 第三方大模型 api 配置教程 写得不够细，导致读者把 Base URL 和完整 chat/completions URL 混用，最后出现 404、Unauthorized 或模型列表不显示。

五、OpenRouter 配置示例

OpenRouter 适合用来统一访问多种模型。下面是一个面向 OpenRouter 的 models.json 示例：

json

{
  "models": [
    {
      "id": "openai/gpt-4o",
      "name": "OpenRouter GPT-4o",
      "vendor": "OpenRouter",
      "url": "https://openrouter.ai/api/v1/chat/completions",
      "apiKey": "${OPENROUTER_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 4096,
      "supportsToolCall": true,
      "supportsImages": false
    }
  ],
  "availableModels": ["openai/gpt-4o"]
}

启动前设置：

bash

export OPENROUTER_API_KEY="sk-or-v1-your-openrouter-api-key"
codebuddy --model openai/gpt-4o

如果你要写团队内部的 codebuddy 第三方大模型 api 配置教程，建议把 models.json 模板提交到仓库，但让每个人在本机设置 OPENROUTER_API_KEY，不要把真实密钥写进项目。

六、DeepSeek 配置示例

DeepSeek 的 OpenAI 兼容接口也可以按同样方式接入。示例：

json

{
  "models": [
    {
      "id": "deepseek-chat",
      "name": "DeepSeek Chat",
      "vendor": "DeepSeek",
      "url": "https://api.deepseek.com/v1/chat/completions",
      "apiKey": "${DEEPSEEK_API_KEY}",
      "maxInputTokens": 32000,
      "maxOutputTokens": 4096,
      "supportsToolCall": true,
      "supportsImages": false
    }
  ],
  "availableModels": ["deepseek-chat"]
}

启动前设置：

bash

export DEEPSEEK_API_KEY="sk-your-deepseek-api-key"
codebuddy --model deepseek-chat

DeepSeek 这类模型适合做代码解释、重构建议、脚本生成和中文技术问答。但如果你要让 CodeBuddy 做复杂跨文件修改，最好先确认该模型的工具调用能力是否稳定，再把 supportsToolCall 设置为 true。

七、本地 Ollama 或内网网关配置示例

如果你有本地模型或公司内网模型网关，也可以按 OpenAI 兼容格式接入。比如本地 Ollama：

json

{
  "models": [
    {
      "id": "my-local-llm",
      "name": "Local LLM",
      "vendor": "Ollama",
      "url": "http://localhost:11434/v1/chat/completions",
      "apiKey": "ollama",
      "maxInputTokens": 8192,
      "maxOutputTokens": 2048,
      "supportsToolCall": true,
      "supportsImages": false
    }
  ],
  "availableModels": ["my-local-llm"]
}

这类接法的优势是成本可控、数据链路更短，适合内网项目、低敏任务和离线演示。缺点也很明显：本地模型能力、上下文长度和工具调用稳定性通常不如成熟云模型。写 codebuddy 第三方大模型 api 配置教程 时，必须把这个边界讲清楚，否则读者会误以为所有 OpenAI 兼容接口都能提供同等质量。

八、如何把配置放进项目而不泄露密钥

推荐做法是项目里只提交结构，不提交密钥：

json

{
  "models": [
    {
      "id": "team-coder",
      "name": "Team Coding Model",
      "vendor": "OpenAI Compatible",
      "url": "${TEAM_LLM_CHAT_COMPLETIONS_URL}",
      "apiKey": "${TEAM_LLM_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 4096,
      "supportsToolCall": true
    }
  ],
  "availableModels": ["team-coder"]
}

团队成员在自己的 shell 配置里写：

bash

export TEAM_LLM_CHAT_COMPLETIONS_URL="https://gateway.example.com/v1/chat/completions"
export TEAM_LLM_API_KEY="sk-team-member-key"

如果你要进一步降低泄露风险，可以参考官方建议，把密钥放到系统 Keychain，再通过 shell 自动导出环境变量。官方文档也提醒，不要把包含真实密钥的配置文件提交到版本控制系统，并建议给 models.json 设置更严格的文件权限。[^2]

九、常见问题排查

1. 模型没有出现在列表里

先检查 availableModels 是否包含你的模型 id。如果配置了 availableModels，CodeBuddy 只显示这个数组里列出的模型。

2. 提示 API Key 不合法

优先检查环境变量是否真的生效：

bash

echo "$OPENROUTER_API_KEY"
echo "$DEEPSEEK_API_KEY"

如果你在 models.json 里写的是 ${DEEPSEEK_API_KEY}，但 shell 没有导出这个变量，CodeBuddy 启动时就拿不到真实密钥。

3. 接口返回 404

高概率是 url 写错了。models.json 里的 url 一般要写完整到：

text

/v1/chat/completions

不要只写供应商根地址，也不要只写 /v1。

4. 工具调用失败

不要只看模型能不能聊天，还要确认它是否稳定支持 tool calling。如果供应商没有明确支持，先把 supportsToolCall 改成 false，跑通普通问答后再开启。

5. 改了文件但配置没生效

官方文档说明 models.json 支持热重载，但仍建议你在排障时重启 CodeBuddy。排查顺序是：JSON 格式、文件路径、环境变量、模型 ID、availableModels。

十、推荐配置流程

如果你要把这篇 codebuddy 第三方大模型 api 配置教程 变成团队 SOP，可以按下面 6 步执行：

先用环境变量快速验证 API Key 和接口可用。
再写 models.json，明确模型 ID、完整 URL 和 token 参数。
把真实密钥改成 ${ENV_NAME}，不要写死在配置文件里。
用 availableModels 限制团队可见模型，避免误选测试模型。
用 codebuddy --model <model-id> 做一次真实代码任务测试。
最后补一份排障说明，覆盖 401、404、模型不显示和工具调用失败。

FAQ

Q1：codebuddy 第三方大模型 api 配置教程里最重要的一步是什么？

最重要的是确认第三方服务兼容 OpenAI 接口格式，并且在 models.json 里把 url 写成完整的 /chat/completions 接口路径。

Q2：只设置 CODEBUDDY_BASE_URL 可以吗？

临时测试可以，但长期使用不够清晰。更推荐写 models.json，因为它能描述模型能力、上下文长度、输出长度和可见模型列表。

Q3：API Key 应该写在哪里？

不要明文写进仓库。推荐写环境变量，比如 ${OPENROUTER_API_KEY}、${DEEPSEEK_API_KEY}，然后在本机 shell 或 Keychain 里维护真实密钥。

Q4：CodeBuddy 支持所有第三方大模型 API 吗？

不支持“所有”。官方模型配置文档说明，目前自定义模型只支持 OpenAI 接口格式的 API。只要第三方服务不兼容这个格式，就需要先经过网关转换。

Q5：为什么同一个模型在聊天工具里能用，在 CodeBuddy 里不稳定？

CodeBuddy 是编程 Agent 场景，不只是普通聊天。跨文件读取、编辑、工具调用、长上下文和结构化输出都会放大模型差异，所以 codebuddy 第三方大模型 api 配置教程 不能只看“能不能回复”，还要看“能不能稳定完成代码任务”。

结语

一篇真正可用的 codebuddy 第三方大模型 api 配置教程，重点不是罗列 API Key，而是把配置层级、完整接口路径、模型能力字段和安全边界讲清楚。个人测试时可以用环境变量快速启动；团队长期使用时，建议统一维护 .codebuddy/models.json，用环境变量注入密钥，再用 availableModels 控制可见模型。

如果你今天就要落地，建议先选一个供应商跑通最小链路：API Key、chat/completions URL、model id、一次真实代码修改。只要这 4 个点稳定，再扩展到多模型、多项目和团队共享配置。

[^1]: CodeBuddy Code 设置配置 [^2]: CodeBuddy Code models.json 配置指南 [^3]: CodeBuddy Code 环境变量参考

核心要点（TL;DR） ​

适合谁阅读这篇教程 ​

一、先理解 CodeBuddy 第三方大模型 API 的配置层级 ​

二、快速方式：用环境变量配置第三方模型 API ​

三、推荐方式：用 models.json 配置第三方大模型 ​

四、关键字段怎么填 ​

五、OpenRouter 配置示例 ​

六、DeepSeek 配置示例 ​

七、本地 Ollama 或内网网关配置示例 ​

八、如何把配置放进项目而不泄露密钥 ​

九、常见问题排查 ​

1. 模型没有出现在列表里 ​

2. 提示 API Key 不合法 ​

3. 接口返回 404 ​

4. 工具调用失败 ​

5. 改了文件但配置没生效 ​

十、推荐配置流程 ​

FAQ ​

Q1：codebuddy 第三方大模型 api 配置教程里最重要的一步是什么？ ​

Q2：只设置 CODEBUDDY_BASE_URL 可以吗？ ​

Q3：API Key 应该写在哪里？ ​

Q4：CodeBuddy 支持所有第三方大模型 API 吗？ ​

Q5：为什么同一个模型在聊天工具里能用，在 CodeBuddy 里不稳定？ ​

结语 ​

核心要点（TL;DR）

适合谁阅读这篇教程

一、先理解 CodeBuddy 第三方大模型 API 的配置层级

二、快速方式：用环境变量配置第三方模型 API

三、推荐方式：用 models.json 配置第三方大模型

四、关键字段怎么填

五、OpenRouter 配置示例

六、DeepSeek 配置示例

七、本地 Ollama 或内网网关配置示例

八、如何把配置放进项目而不泄露密钥

九、常见问题排查

1. 模型没有出现在列表里

2. 提示 API Key 不合法

3. 接口返回 404

4. 工具调用失败

5. 改了文件但配置没生效

十、推荐配置流程

FAQ

Q1：codebuddy 第三方大模型 api 配置教程里最重要的一步是什么？

Q2：只设置 CODEBUDDY_BASE_URL 可以吗？

Q3：API Key 应该写在哪里？

Q4：CodeBuddy 支持所有第三方大模型 API 吗？

Q5：为什么同一个模型在聊天工具里能用，在 CodeBuddy 里不稳定？

结语