models.json 是一个配置文件，用于自定义模型列表和控制模型下拉列表的显示。该配置支持两个级别：~/.codebuddy/models.json - 全局配置，适用于所有项目<workspace>/.codebuddy/models.json - 项目特定配置，优先级高于用户级<project-root>/.codebuddy/models.jsonid 字段匹配）。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","temperature": 0.7,"supportsToolCall": true,"supportsImages": true}],"availableModels": ["model-id-1", "model-id-2"]}
Array<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 | 否 | 是否支持推理模式 |
relatedModels | object | 否 |
url 字段必须是接口完整路径,一般以 /chat/completions 结尾https://api.openai.com/v1/chat/completions 或 http://localhost:11434/v1/chat/completionsapiKey 和 url 字段支持环境变量引用语法 ${VAR_NAME}。${环境变量名}{"models": [{"id": "gpt-4o","name": "GPT-4o","vendor": "OpenAI","apiKey": "${OPENAI_API_KEY}","url": "https://api.openai.com/v1/chat/completions"}]}
# 在 ~/.zshrc 或 ~/.bashrc 中添加export OPENAI_API_KEY="sk-your-actual-api-key"# 或者在启动时临时设置OPENAI_API_KEY="sk-xxx" codebuddy
# 存储密钥到 Keychainsecurity add-generic-password -a "$USER" -s "openai-api-key" -w "sk-xxx"# 在 ~/.zshrc 中配置自动导出export OPENAI_API_KEY=$(security find-generic-password -s "openai-api-key" -w 2>/dev/null)
models.json 文件权限设置为 600（仅所有者可读写）Array<string>{"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}]}
{"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"}]}
{"availableModels": ["gpt-4-turbo","gpt-4o","my-custom-model"]}
.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"]}
~/.codebuddy/models.json （用户级）<workspace>/.codebuddy/models.json （项目级）models.json 添加的模型会自动标记 custom 标签，便于在 UI 中识别和过滤。SmartMerge 策略：availableModels 过滤在所有合并完成后执行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
{"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}]}
url 后，即使与云端同 id 也会按"完全替换"语义生效，不会被云端默认项合并覆盖）：{"models": [{"id": "deepseek-v4-pro","name": "DeepSeek V4 Pro","vendor": "DeepSeek","url": "https://api.deepseek.com/v1/chat/completions","apiKey": "${DEEPSEEK_API_KEY}","maxInputTokens": 128000,"maxOutputTokens": 8192,"supportsToolCall": true,"supportsImages": false},{"id": "deepseek-v4-flash","name": "DeepSeek V4 Flash","vendor": "DeepSeek","url": "https://api.deepseek.com/v1/chat/completions","apiKey": "${DEEPSEEK_API_KEY}","maxInputTokens": 128000,"maxOutputTokens": 8192,"supportsToolCall": true,"supportsImages": false}],"availableModels": ["deepseek-v4-pro","deepseek-v4-flash"]}
export DEEPSEEK_API_KEY="<your-deepseek-api-key>"codebuddy --model deepseek-v4-pro
relatedModels 字段声明。场景 | 用途 | 当前状态 |
lite | 轻量快速模型，用于后台提取、摘要等低价值请求；也是 Agent 工具 model: "lite" 参数对应的模型 | 已生效 |
reasoning | 推理增强模型，用于需要深度思考的复杂推理；Agent 工具 model: "reasoning" 参数对应的模型 | 已生效 |
subagent | 子代理和团队成员默认使用的模型 | 预留未启用——子代理使用独立的 subagents 解析链，不读取本字段 |
vision | 视觉理解模型，用于需要处理图片的请求 | 预留未启用——类型已定义，尚无调用点消费此 variant |
longContext | 长上下文模型，用于上下文超长的请求 | 预留未启用——类型已定义，尚无调用点消费此 variant |
lite 和 reasoning 两个 variant 在 agent-manager 中被消费并映射到模型切换逻辑。subagent / vision / longContext 三项仅保留在类型定义中，为后续迭代预留，现在写进 relatedModels 不会报错但也不会生效。models.json 添加的自定义模型不会继承产品内置的 defaultRelatedModels。relatedModels，且没有环境变量或 variantModels 覆盖，lite 和 reasoning 会回退到主模型。子代理不读取 relatedModels.subagent，但配置为 lite 或 reasoning 的子代理仍会走这条场景变体解析链。{"models": [{"id": "deepseek-v4-pro","name": "DeepSeek V4 Pro","vendor": "DeepSeek","url": "https://api.deepseek.com/v1/chat/completions","apiKey": "${DEEPSEEK_API_KEY}","maxInputTokens": 128000,"maxOutputTokens": 8192,"supportsToolCall": true,"relatedModels": {"lite": "deepseek-v4-flash","reasoning": "deepseek-v4-pro"}},{"id": "deepseek-v4-flash","name": "DeepSeek V4 Flash","vendor": "DeepSeek","url": "https://api.deepseek.com/v1/chat/completions","apiKey": "${DEEPSEEK_API_KEY}","maxInputTokens": 128000,"maxOutputTokens": 8192,"supportsToolCall": true}],"availableModels": ["deepseek-v4-pro","deepseek-v4-flash"]}
lite / reasoning 会走这个解析链）：CODEBUDDY_SMALL_FAST_MODEL 对应 lite、CODEBUDDY_BIG_SLOW_MODEL 对应 reasoning）variantModels[variant]variantModels[variant]relatedModels[variant]defaultRelatedModels[variant]（仅对内置模型生效，自定义模型跳过这步）variantModels 保存在 settings.json 中，也可通过 /model:lite / /model:reasoning 命令编辑。它适合在用户或项目范围内将 lite / reasoning 固定映射到具体模型；relatedModels 则适合让映射跟随当前主模型。CODEBUDDY_CODE_SUBAGENT_MODEL，统一覆盖所有子代理model 入参subagents.agents.<子代理名>.modelsubagents.agents.<子代理名>.modelExplore 使用 literelatedModels.subagent。当子代理配置为 lite 或 reasoning 时，会继续通过上面的场景变体解析链得到具体模型。settings.json：{"subagents": {"agents": {"Explore": { "model": "lite" },"Plan": { "model": "reasoning" }}},"variantModels": {"lite": "<fast-model-id>","reasoning": "<reasoning-model-id>"}}
relatedModels，让场景映射跟随主模型。variantModels 或 /model，在用户或项目范围内固定 lite / reasoning 的具体模型。subagents.agents.<子代理名>.model 或 /agents，为内置子代理分别选择模型或场景变体。{"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"]}
availableModels 中列出models 配置是否正确id, name, provider) 是否都已提供文档反馈