Model Configuration

ダウンロード

フォーカスモード

フォントサイズ

最終更新日: 2026-09-30 18:15:48

AI翻訳

Overview
models.json is a configuration file for customizing the model list and controlling the display of the model dropdown list. This configuration supports two levels:
User-level: ~/.codebuddy/models.json - Global configuration that applies to all projects.
Project-level: <workspace>/.codebuddy/models.json - Project-specific configuration that takes precedence over the user-level configuration.
Configuration File Location
User-Level Configuration
~/.codebuddy/models.json
Project-Level Configuration
<project-root>/.codebuddy/models.json
Configuration Precedence
The configuration merge priority from highest to lowest:
1. Project-level models.json
2. User-level models.json
3. Built-in default configuration
Project-level configuration overrides identical model definitions in the user-level configuration, matched by the id field. For the availableModels field, the project-level configuration completely overrides the user-level configuration without merging.
Configuration Structure
{
  "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"]
}
Configuration Field Descriptions
models
Type: Array<LanguageModel>
Define a custom model list. You can add new models or override built-in model configurations.
LanguageModel Field
Field
Type
Required
Description
id
string
Yes
Unique identifier of the model
name
string
No
Model display name
vendor
string
No
Model vendor (for example, OpenAI, Google)
apiKey
string
No
API key, supports environment variable references (see the security configuration instructions below).
maxInputTokens
number
No
Maximum input tokens
maxOutputTokens
number
No
Maximum output tokens
url
string
No
API endpoint URL, supports environment variable references (must be the full API path, typically ending with /chat/completions).
temperature
number
No
Sampling temperature, ranging from 0 to 2. Higher values produce more random output, while lower values produce more deterministic output.
supportsToolCall
boolean
No
Tool call support or not
supportsImages
boolean
No
Image input support or not
supportsReasoning
boolean
No
Reasoning mode support or not
relatedModels
object
No
Related model configuration, specifies which model id to use in different scenarios (lite/reasoning/vision/longContext/subagent). For details, see Configure Related Models.
Important Note:
Currently, only APIs in the OpenAI interface format are supported.
The url field must be the full API path, typically ending with /chat/completions.
For example: https://api.openai.com/v1/chat/completions or http://localhost:11434/v1/chat/completions
Security Configuration: Using Environment Variable References
To prevent API keys from being stored in plaintext in configuration files, the apiKey and url fields support the environment variable reference syntax ${VAR_NAME}.
Syntax: ${ENV_VAR_NAME}
Configuration example:
{
  "models": [
    {
      "id": "gpt-4o",
      "name": "GPT-4o",
      "vendor": "OpenAI",
      "apiKey": "${OPENAI_API_KEY}",
      "url": "https://api.openai.com/v1/chat/completions"
    }
  ]
}
Set environment variables:
# Add to ~/.zshrc or ~/.bashrc
export OPENAI_API_KEY="sk-your-actual-api-key"
﻿
# Or set it temporarily at startup.
OPENAI_API_KEY="sk-xxx" codebuddy
Use the system Keychain (macOS):
# Store the key in the Keychain
security add-generic-password -a "$USER" -s "openai-api-key" -w "sk-xxx"
﻿
# Configure automatic export in ~/.zshrc
export OPENAI_API_KEY=$(security find-generic-password -s "openai-api-key" -w 2>/dev/null)
Note:
Environment variables are parsed when the CLI starts.
If the environment variable does not exist, the original placeholder will be retained, which will cause the API call to fail.
It is recommended to set the permissions of models.json to 600 (readable and writable only by the owner).
Do not commit configuration files that contain actual keys to the version control system.
availableModels
Type: Array<string>
Controls which models appear in the model dropdown list. Only model IDs listed in this array are displayed in the UI.
If it is not configured or is an empty array, all models are displayed.
After configuration, only the listed model IDs are displayed.
It can contain both built-in model IDs and custom model IDs.
Scenarios
1. Adding a Custom Model
Add a new model configuration at the user level or project level:
{
  "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. Overriding Built-in Model Configurations
Modify the default parameters of the built-in model:
{
  "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. Restricting the List of Available Models
Display only specific models in the dropdown list:
{
  "availableModels": [
    "gpt-4-turbo",
    "gpt-4o",
    "my-custom-model"
  ]
}
4. Project-Specific Configuration
Use different models or API endpoints for specific projects:
Project 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"]
}
Hot Reloading
The configuration file supports hot reloading:
File changes are automatically detected.
Use a 1-second debounce delay to avoid frequent reloads.
After a configuration update, the changes are automatically synced to the application.
Watched files:
~/.codebuddy/models.json (user level)
<workspace>/.codebuddy/models.json (project level)
Tag System
Models added through models.json are automatically tagged with the custom tag for easy identification and filtering in the UI.
Merge Policy
Configure the SmartMerge policy:
Model configurations with the same ID are overwritten.
Models with different IDs are appended.
Project-level configuration takes precedence over user-level configuration.
availableModels filtering is performed after all merges are complete.
Sample Configuration
API Endpoint URL Format
You must use a full path:
The url field for all custom models typically ends with /chat/completions.
Correct example:
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
Incorrect example:
https://api.openai.com/v1
https://api.myservice.com
http://localhost:11434
OpenRouter Platform Configuration Example
Use OpenRouter to access multiple models:
{
  "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 Platform Configuration Example
Use the DeepSeek model (after url is configured, it takes effect with "full replacement" semantics even if the id is the same as the cloud, and it will not be merged or overwritten by cloud defaults):
{
  "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"
  ]
}
Start after setting the API key environment variable:
export DEEPSEEK_API_KEY="<your-deepseek-api-key>"
codebuddy --model deepseek-v4-pro
Note:
If you prefer not to maintain models.json, you can also integrate with DeepSeek entirely through environment variables. See Environment Variables for Integrating with DeepSeek Example.
Configuring Associated Models
CodeBuddy Code switches models based on the scenario within a session, avoiding the use of large models for simple tasks or general-purpose models for requests that require reasoning, vision, or long context. These scenarios are declared through the relatedModels field of a model entry.
Supported scenarios (variant types):
Scenario
Purpose
Current status
lite
A lightweight and fast model for low-value requests such as backend extraction and summarization. It is also the model corresponding to the model: "lite" parameter of the Agent tool.
Effective
reasoning
Reasoning-enhanced model for complex reasoning that requires deep thinking; the model corresponding to the model: "reasoning" parameter of the Agent tool.
Effective
subagent
Default model used by subagents and team members
Reserved and not enabled—subagents use an independent subagents parsing chain and do not read this field.
vision
Vision understanding model for requests that require image processing
Reserved and not enabled—the type is defined, but no call site consumes this variant yet.
longContext
Long-context model for requests with extremely long contexts
Reserved and not enabled—the type is defined, but no call site consumes this variant yet.
Currently available: Only the lite and reasoning variants are consumed in agent-manager and mapped to the model switching logic. The subagent / vision / longContext items are only retained in the type definitions and reserved for future iterations. Writing them into relatedModels now will not cause an error, but they will not take effect either.
Key rules (required reading for custom models):
Custom models added through models.json do not inherit the built-in defaultRelatedModels.
If a custom main model does not declare relatedModels, and no environment variables or variantModels overrides are present, lite and reasoning fall back to the main model. Subagents do not read relatedModels.subagent, but subagents configured as lite or reasoning still go through this scenario variant resolution chain.
Configuration example (DeepSeek as the main model + flash as 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"
  ]
}
Scenario variant resolution priority (from highest to lowest, currently only lite / reasoning go through this resolution chain):
1. Corresponding environment variables (CODEBUDDY_SMALL_FAST_MODEL corresponds to lite, and CODEBUDDY_BIG_SLOW_MODEL corresponds to reasoning)
2. Project-level variantModels[variant]
3. User-level global variantModels[variant]
4. relatedModels[variant] in the current main model entry
5. Built-in defaultRelatedModels[variant] (applies only to built-in models, and custom models skip this step)
6. fall back to the main model itself
variantModels is stored in settings.json and can also be edited through the /model:lite / /model:reasoning commands. It is suitable for fixed mapping of lite / reasoning to specific models at the user or project level, while relatedModels is suitable for making the mapping follow the current main model.
Built-in subagent resolution priority (from highest to lowest):
1. CODEBUDDY_CODE_SUBAGENT_MODEL uniformly overrides all subagents.
2. The model input parameter of this Agent tool call
3. Project-level subagents.agents.<subagent_name>.model
4. User-level global subagents.agents.<subagent_name>.model
5. Built-in product declarations, such as Explore using lite
6. Inherit the main conversation model.
Subagent models do not read relatedModels.subagent. When a subagent is configured as lite or reasoning, it continues through the scenario variant resolution chain above to obtain a specific model.
The following configuration should be written to the user-level or project-level settings.json:
{
  "subagents": {
    "agents": {
      "Explore": { "model": "lite" },
      "Plan": { "model": "reasoning" }
    }
  },
  "variantModels": {
    "lite": "<fast-model-id>",
    "reasoning": "<reasoning-model-id>"
  }
}
Applicable scenarios for different configuration methods:
Use relatedModels to make scenario mappings follow the main model.
Use variantModels or /model to pin the specific model for lite / reasoning at the user or project level.
Use subagents.agents.<subagent_name>.model or /agents to select a model or scenario variant for each built-in subagent.
Use model environment variables for Ops or CI-level overrides. Environment variables take precedence over persistent settings. After the environment variables are removed, the lower-priority settings take effect again.
Complete Examples
{
  "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"
  ]
}
Troubleshooting
Configuration Not Taking Effect
1. Check whether the JSON format is correct.
2. Check whether the file path is correct.
3. Check the log output to confirm whether the configuration is loaded.
4. Confirm whether the API key in the environment variable is set.
Model Not Displayed in the List
1. Check whether the model ID is listed in availableModels.
2. Confirm whether the models configuration is correct.
3. Verify that all required fields (id, name, provider) are provided.
Hot Reload Not Triggered
Configuration file changes have a 1-second debounce delay.
Ensure that the file is actually saved to disk.
Check whether file watching has started properly (check the debug logs).

ヘルプとサポート

この記事はお役に立ちましたか？

営業担当者にお問い合わせいただくかチケットを提出してサポートを求めることができます。

フィードバック

Scenario	Purpose	Current status
`lite`	A lightweight and fast model for low-value requests such as backend extraction and summarization. It is also the model corresponding to the `model: "lite"` parameter of the Agent tool.	Effective
`reasoning`	Reasoning-enhanced model for complex reasoning that requires deep thinking; the model corresponding to the `model: "reasoning"` parameter of the Agent tool.	Effective
`subagent`	Default model used by subagents and team members	Reserved and not enabled—subagents use an independent `subagents` parsing chain and do not read this field.
`vision`	Vision understanding model for requests that require image processing	Reserved and not enabled—the type is defined, but no call site consumes this variant yet.
`longContext`	Long-context model for requests with extremely long contexts	Reserved and not enabled—the type is defined, but no call site consumes this variant yet.

tencent cloud

Tencent WorkBuddy Enterprise

Model Configuration

Overview

Configuration File Location

User-Level Configuration

Project-Level Configuration

Configuration Precedence

Configuration Structure

Configuration Field Descriptions

models

LanguageModel Field

Security Configuration: Using Environment Variable References

availableModels

Scenarios

1. Adding a Custom Model

2. Overriding Built-in Model Configurations

3. Restricting the List of Available Models

4. Project-Specific Configuration

Hot Reloading

Tag System

Merge Policy

Sample Configuration

API Endpoint URL Format

OpenRouter Platform Configuration Example

DeepSeek Platform Configuration Example

Configuring Associated Models

Complete Examples

Troubleshooting

Configuration Not Taking Effect

Model Not Displayed in the List

Hot Reload Not Triggered

ヘルプとサポート

Field	Type	Required	Description
`id`	string	Yes	Unique identifier of the model
`name`	string	No	Model display name
`vendor`	string	No	Model vendor (for example, OpenAI, Google)
`apiKey`	string	No	API key, supports environment variable references (see the security configuration instructions below).
`maxInputTokens`	number	No	Maximum input tokens
`maxOutputTokens`	number	No	Maximum output tokens
`url`	string	No	API endpoint URL, supports environment variable references (must be the full API path, typically ending with `/chat/completions`).
`temperature`	number	No	Sampling temperature, ranging from 0 to 2. Higher values produce more random output, while lower values produce more deterministic output.
`supportsToolCall`	boolean	No	Tool call support or not
`supportsImages`	boolean	No	Image input support or not
`supportsReasoning`	boolean	No	Reasoning mode support or not
`relatedModels`	object	No	Related model configuration, specifies which model id to use in different scenarios (`lite`/`reasoning`/`vision`/`longContext`/`subagent`). For details, see Configure Related Models.