tencent cloud

Tencent WorkBuddy Enterprise

문서Tencent WorkBuddy EnterpriseCodeBuddyCodeBuddy IDEUser GuideAdvanced Featuresmodels.json Configuration Guide

models.json Configuration Guide

다운로드
포커스 모드
폰트 크기
마지막 업데이트 시간: 2026-10-08 10:00:54
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",
      "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 (the actual key value, not the environment variable name)
maxInputTokens
number
No
Maximum input tokens
maxOutputTokens
number
No
Maximum output tokens
url
string
No
API endpoint URL (must be the full API path, typically ending with /chat/completions)
supportsToolCall
boolean
No
Tool call support or not
supportsImages
boolean
No
Image input support or not
supportsReasoning
boolean
No
Reasoning mode support or not
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

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:
{
  "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
    }
  ]
}

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).

이전 주제: Smart Commit다음 주제: Plan Mode

도움말 및 지원

문제 해결에 도움이 되었나요?

피드백

키워드로 검색
    Enter keywords to search documentation