Custom Models

Constraints

• Only third-party custom enterprise models using the OpenAI-compliant Chat Completions APIs and Anthropic-compliant Messages APIs can be integrated.
• The custom models created on the console can be invoked by all agents. However, those created on the client can be invoked only by the system built-in agents, AgentTeam, and custom agents.
• The provider and model ID combination of each model you add must be unique.

Prerequisites

• Your account has been added as an enterprise member and assigned a seat.
• If you have purchased CodeArts Agent professional edition, ensure that the enterprise administrator has enabled model customization for members on the console. For details, see Configuring Custom Models.

Custom Model Configuration File

CodeArts Agent CLI allows you to manage custom models using a configuration file. On the CLI or TUI, you cannot create, modify, or delete custom models using commands. Instead, you can edit all configurations only by editing the file.

The configuration file for custom models is codearts_cli.json, which is stored in ~/.codeartsdoer/. The tilde (~) indicates the home directory of the current user. In Windows, it is equivalent to C:\Users\Username\. In macOS, it is equivalent to /Users/Username/. In Linux, it is equivalent to /home/Username/.

In the configuration file, provider is the top-level key. Each provider ID matches a configuration block. The complete structure of the configuration file is as follows:

{
  "provider": {
    "<Provider ID>": {
      "name": "<Provider name>",
      "npm": "<SDK package name>",
      "api": "<Provider API URL>",
      "env": ["<Environment variable name>", ...],
      "whitelist": ["<Model ID>", ...],
      "blacklist": ["<Model ID>", ...],
      "options": {
        "apiKey": "<API key>",
        "baseURL": "<Base API URL>",
        "enterpriseUrl": "<Enterprise edition URL>",
        "setCacheKey": true,
        "timeout": 300000,
        "chunkTimeout": 60000
      },
      "models": {
        "<Model ID>": {
          "id": "<Model API ID>",
          "name": "<Displayed name>",
          "family": "<Model family>",
          "reasoning": true,
          "attachment": true,
          "temperature": true,
          "tool_call": true,
          "limit": { "context": 128000, "input": 120000, "output": 8000 },
          "cost": {
            "input": 3.0,
            "output": 15.0,
            "cache_read": 0.5,
            "cache_write": 2.0,
            "context_over_200k": {
              "input": 6.0,
              "output": 30.0,
              "cache_read": 1.0,
              "cache_write": 4.0
            }
          },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          },
          "headers": { "X-Custom-Header": "value" },
          "status": "active",
          "provider": { "npm": "<SDK package name>", "api": "<API URL>" },
          "variants": { ... }
        }
      }
    }
  }
}

apiKey is your core asset. Do not disclose it. After you configure apiKey and restart the TUI or CLI, apiKey will be automatically encrypted. The ciphertext apiKey will then be displayed in the configuration file.

The provider ID is a top-level key in the configuration file and is used to identify the model source. Table 1 lists common provider IDs. You can also use any custom string (for example, my-server) as the provider ID, as long as the corresponding model supports OpenAI-compatible API formats.

Custom Model Configuration Example

The following steps describe how to customize a model with the minimum configuration in Windows by setting the provider ID, API key, and model.

1. Go to the %USERPROFILE%/.codeartsdoer directory and find and open the codearts_cli.json configuration file.
2. Add the following provider information to the codearts_cli.json file:

   {
     "$schema": "https://opencode.ai/config.json",
     "provider": {
       "deepseek": {
         "options": {
           "apiKey": "sk-***",
           "baseURL": "https://api.deepseek.com/v1"
         },
         "models": {
           "deepseek-chat": {
             "name": "DeepSeek Chat"
           },
           "deepseek-reasoner": {
             "name": "DeepSeek Reasoner",
             "reasoning": true
           }
         }
       }
     },
     "mcp": {},
     "lsp": false
   }

   You need to purchase an API key from the DeepSeek official website and then set apiKey.

3. Save the file and exit.
4. Check whether the custom model has been added.
   • Run the following command in the CLI environment and check whether the custom model is included in the model list displayed in the command output:

     codearts models

   • In the TUI environment, run the following slash command to go to the Select model page and check whether the custom model is available:

     /models

Specifying the Model to Run

In CodeArts Agent CLI, you can specify a model to run your task. In the following command, provider indicates the model provider, and model indicates the model name.

• TUI development environment
  • When starting TUI, you can run the following command to specify the model to run:

    codearts --model provider/model
    You can also use a short parameter.
    codearts -m provider/model

  • In the TUI development environment, you can enter the /models command to quickly switch models.
• CLI development environment

  codearts run --model provider/model "Your question"