CodeBuddy 配置（models.json）

本页整理了 CodeBuddy CLI 的 models.json 配置指南，便于你自定义模型列表并控制下拉显示。

概述

models.json 用于自定义模型列表和控制模型下拉显示，支持两个级别：

• 用户级：~/.codebuddy/models.json（全局配置，适用于所有项目）
• 项目级：<workspace>/.codebuddy/models.json（项目专用，优先级更高）

配置文件位置

用户级

~/.codebuddy/models.json

项目级

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

配置优先级

合并优先级从高到低：

1. 项目级 models.json
2. 用户级 models.json
3. 内置默认配置

项目级会覆盖用户级中 相同 id 的模型配置。availableModels 在项目级配置中会完全覆盖用户级配置（不合并）。

配置结构

{
  "models": [
    {
      "id": "claude-sonnet-4.5",
      "name": "Claude Sonnet 4.5",
      "vendor": "OPE.AI",
      "apiKey": "sk-xxxx",
      "maxInputTokens": 200000,
      "maxOutputTokens": 8192,
      "url": "https://api.platform.ope.ai/v1/chat/completions",
      "temperature": 0.7,
      "supportsToolCall": true,
      "supportsImages": true,
      "supportsReasoning": true
    }
  ],
  "availableModels": ["claude-sonnet-4.5", "claude-haiku-4.5", "claude-opus-4.5"]
}

配置字段说明

models

类型：Array<LanguageModel>

用于定义自定义模型列表，可新增模型或覆盖内置模型配置。

LanguageModel 字段

• id（string，必填）：模型唯一标识符
• name（string）：模型显示名称
• vendor（string）：模型供应商（如 OpenAI、Google）
• apiKey（string）：API 密钥（实际密钥值）
• maxInputTokens（number）：最大输入 token 数
• maxOutputTokens（number）：最大输出 token 数
• url（string）：API 端点 URL（必须是完整路径，一般以 /chat/completions 结尾）
• temperature（number）：采样温度，范围 0-2
• supportsToolCall（boolean）：是否支持工具调用
• supportsImages（boolean）：是否支持图片输入
• supportsReasoning（boolean）：是否支持推理模式

重要说明：

• 目前仅支持 OpenAI 接口格式 的 API
• url 必须是接口完整路径，通常以 /chat/completions 结尾
• 例如：https://api.openai.com/v1/chat/completions、http://localhost:11434/v1/chat/completions

availableModels

类型：Array<string>

控制模型下拉列表显示哪些模型：

• 未配置或为空数组：显示全部模型
• 配置后：仅显示列表中的模型 ID
• 可同时包含内置模型与自定义模型的 ID

标签系统

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

合并策略（SmartMerge）

• 相同 ID 的模型配置会被覆盖
• 不同 ID 的模型会被追加
• 项目级配置优先于用户级配置
• availableModels 过滤在所有合并完成后执行

热重载

models.json 支持热重载：

• 文件变更会被自动检测
• 使用 1 秒防抖延迟避免频繁重载
• 配置更新后会自动同步到应用

监听文件：

• ~/.codebuddy/models.json
• <workspace>/.codebuddy/models.json

参考资料

• CodeBuddy CLI 模型配置