概述
产品内置主流大模型，覆盖推理、多模态及图像处理能力，并支持自定义模型。自定义模型可通过可视化界面配置，也可以手动编辑配置文件，支持添加、编辑和删除模型。
自定义模型管理
模型列表：已配置的自定义模型以列表形式展示，每条记录显示模型名称与供应商图标。
对话入口联动：对话界面的模型选择器展示自定义模型分组。
在模型列表下拉框底部点击配置自定义模型，通过图形界面管理自定义模型：
说明：
配置在保存后自动持久化，选择标准供应商时，工具调用、图片输入等能力标记会自动写入，无需手动配置。
接入方式
提供商接入
从提供商列表中选择或选择自定义 API 后，URL、模型列表、能力标记（工具调用、图片输入、推理模式等）会自动填充，仅需补全 API Key 即可保存使用，全程无需手动修改任何配置文件。
Token Plan
腾讯云 Token Plan 专为 AI 编程和 CodeBuddy 场景打造，提供面向个人、企业多种类型的订阅套餐，兼容混元、MiniMax、Kimi、GLM 等主流大模型，满足从个人开发到企业规模化 AI 应用的需求。如果您已经购买了腾讯云 Token Plan 套餐，可将套餐支持的模型添加到自定义模型配置中。
第一步：在添加模型页面，根据您购买的套餐类型，选择对应的供应商，可选择如下：
第二步：填入套餐对应的 API Key。不同套餐的 API Key 可查看如下指引获取：
注意：
请勿将 API Key 分享给他人。API Key 关联您的账户与套餐额度，泄露可能导致他人盗用您的配额、产生额外费用或造成数据安全风险。
请确认供应商可信。接入第三方模型前，建议阅读该模型服务方的服务协议与隐私政策，确保其符合您对数据安全与合规的要求。
第三步：选择套餐支持的模型，不同套餐的可用模型不一样。
Coding Plan
Coding Plan 是为 AI Coding 场景推出的专属订阅套餐，支持接入腾讯云 Coding Plan、智谱 Coding Plan 和 Kimi Coding Plan。
自定义 API
内置了主流厂商的预设入口，可一键完成接入：
本地部署
Ollama 是一个开源的本地大模型运行工具，安装后通过一行命令即可拉取并运行开源模型。Ollama 启动后会在本地监听 HTTP 端口（默认 11434），并自动提供兼容 OpenAI 协议的接口供 CodeBuddy 对接。
适用场景：
1. 数据隐私 / 内网合规：代码与对话内容不出本机，适合金融、政企、敏感项目场景。
2. 零成本试用：不用消耗 Token、不用付费 API Key，把硬件当算力。
3. 离线可用：飞机上、内网开发机、没网的环境也能用 CodeBuddy。
自定义
如果你的模型服务不在上方列表中，可选择 Custom，手动填写 URL、API Key 与模型名接入。
自定义协议
当模型服务使用非标准 URL 路径（如经过网关或代理层封装）时，可在高级配置中开启自定义协议开关。开启后 CodeBuddy 将直接按填写的 URL 发起请求，跳过路径校验与自动补全。
状态 | 行为 |
关闭（默认） | 使用标准 /chat/completions 路径，自动校验并补全接口地址 |
开启 | 直接使用用户填写的接口地址发起请求，跳过路径校验与自动补全逻辑 |
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": "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,"supportsReasoning":true}]}
配置字段说明
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 结尾） |
supportsToolCall | boolean | - | 是否支持工具调用 |
supportsImages | boolean | - | 是否支持图片输入 |
supportsReasoning | boolean | - | 是否支持推理模式 |
注意：
目前仅支持 OpenAI 接口格式的 API
url 字段必须是接口完整路径,一般以
/chat/completions 结尾。例如: https://api.openai.com/v1/chat/completions 或 http://localhost:11434/v1/chat/completionsavailableModels
类型：
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"]}
注意：
删除配置中的 "availableModels" 字段后，需要同步删除对应的配置，然后保存配置。
项目A修改示例：
热重载
配置文件支持热重载：
文件变更会被自动检测
使用 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/completionshttps://api.myservice.com/v1/chat/completionshttp://localhost:11434/v1/chat/completionshttps://my-proxy.example.com/v1/chat/completions
错误示例：
https://api.openai.com/v1https://api.myservice.comhttp://localhost:11434
OpenRouter 平台配置示例
使用 OpenRouter 访问多种模型：
{"models": [{"id": "openai/gpt-4o","name": "open-router-model","url": "https://openrouter.ai/api/v1/chat/completions","apiKey": "","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": "","maxInputTokens":32000,"maxOutputTokens":4096,"supportsToolCall": true,"supportsImages": false}]}
完整示例
{"models": [{"id": "gpt-4o","name": "GPT-4o","vendor": "OpenAI","apiKey": "","maxInputTokens":128000,"maxOutputTokens":16384,"supportsToolCall": true,"supportsImages": false,"supportsImages": true},{"id": "my-local-llm","name": "My Local LLM","vendor": "Ollama","url": "http://localhost:11434/v1/chat/completions","apiKey": "","maxInputTokens":8192,"maxOutputTokens":2048,"supportsToolCall": true}],"availableModels": ["gpt-4o","my-local-llm"]}
故障排查
配置未生效
1. 检查 JSON 格式是否正确。
2. 确认文件路径是否正确。
3. 查看日志输出确认配置是否被加载。
4. 确认环境变量中的 API 密钥是否已设置。
模型未在列表中显示
1. 检查模型 ID 是否在
availableModels 中列出。2. 确认
models 配置是否正确。3. 验证必填字段 （
id, name) 是否都已提供。热重载未触发
配置文件变更有 1 秒防抖延迟。
确保文件确实被保存到磁盘。
检查文件监听是否正常启动 （查看调试日志）。
