models.json 是一个配置文件，用于自定义模型列表和控制模型下拉列表的显示。该配置支持两个级别：

用户级: ~/.codebuddy/models.json - 全局配置，适用于所有项目

项目级: <workspace>/.codebuddy/models.json - 项目特定配置，优先级高于用户级

配置文件位置

用户级配置

~/.codebuddy/models.json

项目级配置

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

配置优先级

配置合并优先级从高到低：

项目级 models.json

用户级 models.json

内置默认配置

项目级配置会覆盖用户级配置中的相同模型定义（基于 id 字段匹配）。availableModels 字段：项目级完全覆盖用户级，不进行合并。

配置结构

{ "models": [ { "id": "model-id", "name": "Model Display Name", "vendor": "vendor-name", "apiKey": "sk-actual-api-key-value", "maxInputTokens": 200000, "maxOutputTokens": 8192, "url": "https://api.example.com/v1/chat/completions", "supportsToolCall": true, "supportsImages": true } ] }

配置字段说明

models

类型： Array<LanguageModel>

定义自定义模型列表。可以添加新模型或覆盖内置模型配置。

LanguageModel 字段

字段类型必填说明

idstring✓模型唯一标识符

namestring-模型显示名称

vendorstring-模型供应商 （如 OpenAI, Google)

apiKeystring-API 密钥（实际密钥值，非环境变量名）

maxInputTokensnumber-最大输入 token 数

maxOutputTokensnumber-最大输出 token 数

urlstring-API 端点 URL (必须是接口完整路径,一般以 /chat/completions 结尾）

supportsToolCallboolean-是否支持工具调用

supportsImagesboolean-是否支持图片输入

supportsReasoningboolean-是否支持推理模式

重要说明：

目前仅支持 OpenAI 接口格式的 API

url 字段必须是接口完整路径,一般以 /chat/completions 结尾

例如: https://api.openai.com/v1/chat/completions 或 http://localhost:11434/v1/chat/completions

availableModels

类型： Array<string>

控制模型下拉列表中显示哪些模型。只有在此数组中列出的模型 ID 才会在 UI 中显示。

如果未配置或为空数组，则显示所有模型

配置后，只显示列出的模型 ID

可以同时包含内置模型和自定义模型的 ID

使用场景

1. 添加自定义模型

在用户级或项目级添加新的模型配置：

{ "models": [ { "id": "my-custom-model", "name": "My Custom Model", "vendor": "OpenAI", "apiKey": "sk-custom-key-here", "maxInputTokens"：128000, "maxOutputTokens"：4096, "url": "https://api.myservice.com/v1/chat/completions", "supportsToolCall": true } ] }

2. 覆盖内置模型配置

修改内置模型的默认参数：

{ "models": [ { "id": "gpt-4-turbo", "name": "GPT-4 Turbo (Custom Endpoint)", "vendor": "OpenAI", "url": "https://my-proxy.example.com/v1/chat/completions", "apiKey": "sk-your-key-here" } ] }

3. 限制可用模型列表

只在下拉列表中显示特定模型：

{ "availableModels": [ "gpt-4-turbo", "gpt-4o", "my-custom-model" ] }

4. 项目特定配置

为特定项目使用不同的模型或 API 端点：

项目 A (.codebuddy/models.json):

{ "models": [ { "id": "project-a-model", "name": "Project A Model", "vendor": "OpenAI", "url": "https://project-a-api.example.com/v1/chat/completions", "apiKey": "sk-project-a-key", "maxInputTokens"：100000, "maxOutputTokens"：4096 } ], "availableModels": ["project-a-model", "gpt-4-turbo"] }

热重载

配置文件支持热重载：

文件变更会被自动检测

使用 1 秒防抖延迟避免频繁重载

配置更新后会自动同步到应用

监听的文件：

~/.codebuddy/models.json （用户级）

<workspace>/.codebuddy/models.json （项目级）

标签系统

通过 models.json 添加的模型会自动标记 custom 标签，便于在 UI 中识别和过滤。

合并策略

配置使用 SmartMerge 策略：

相同 ID 的模型配置会被覆盖

不同 ID 的模型会被追加

项目级配置优先于用户级配置

availableModels 过滤在所有合并完成后执行

示例配置

API 端点 URL 格式说明

必须使用完整路径： 所有自定义模型的 url 字段一般以 /chat/completions 结尾。

✅ 正确示例：

https://api.openai.com/v1/chat/completions https://api.myservice.com/v1/chat/completions http://localhost:11434/v1/chat/completions https://my-proxy.example.com/v1/chat/completions

❌ 错误示例：

https://api.openai.com/v1 https://api.myservice.com http://localhost:11434

OpenRouter 平台配置示例

使用 OpenRouter 访问多种模型：

{ "models": [ { "id": "openai/gpt-4o", "name": "open-router-model", "url": "https://openrouter.ai/api/v1/chat/completions", "apiKey": "sk-or-v1-your-openrouter-api-key", "maxInputTokens"：128000, "maxOutputTokens"：4096, "supportsToolCall": true, "supportsImages": false } ] }

DeepSeek 平台配置示例

使用 DeepSeek 模型：

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

完整示例

{ "models": [ { "id": "gpt-4o", "name": "GPT-4o", "vendor": "OpenAI", "apiKey": "sk-your-openai-key", "maxInputTokens"：128000, "maxOutputTokens"：16384, "supportsToolCall": true, "supportsImages": true }, { "id": "my-local-llm", "name": "My Local LLM", "vendor": "Ollama", "url": "http://localhost:11434/v1/chat/completions", "apiKey": "ollama", "maxInputTokens"：8192, "maxOutputTokens"：2048, "supportsToolCall": true } ], "availableModels": [ "gpt-4o", "my-local-llm" ] }

故障排查

配置未生效

检查 JSON 格式是否正确

确认文件路径是否正确

查看日志输出确认配置是否被加载

确认环境变量中的 API 密钥是否已设置

模型未在列表中显示

检查模型 ID 是否在 availableModels 中列出

确认 models 配置是否正确

验证必填字段 （id, name, provider) 是否都已提供

热重载未触发

配置文件变更有 1 秒防抖延迟

确保文件确实被保存到磁盘

检查文件监听是否正常启动 （查看调试日志）