How to Set Up a Custom Model with kimi-cli: Complete Configuration Guide

To set up a custom model with kimi-cli, define a provider and model entry in ~/.kimi/config.toml, then reference it as the default or select it per-invocation using the --model flag.

The MoonshotAI/kimi-cli repository provides a Python-based command-line interface that reads runtime configuration from a user-wide TOML file. Adding a custom model requires mapping an API endpoint through a provider configuration and registering the model's capabilities, allowing the CLI to route requests to any OpenAI-compatible, Anthropic, or custom HTTP endpoint.

Locate the Configuration File

kimi-cli stores user settings in ~/.kimi/config.toml. The configuration loader is implemented in src/kimi_cli/config.py within the load_config() function, which automatically creates this file on first run if it does not exist. You can also programmatically regenerate it using save_config() as defined at line 82 of the same file.

Verify the file exists and is readable:

ls ~/.kimi/config.toml

If missing, initialize the CLI once to trigger the automatic creation logic, or manually create the directory and file.

Step 1: Define a Custom Provider

Providers encapsulate the HTTP client details required to communicate with an LLM service. In src/kimi_cli/config.py, the LLMProvider model (line 35) defines the schema for these entries, while the ProviderType enum in src/kimi_cli/llm.py enumerates supported backend types.

Add a provider under the [providers.<name>] table:

[providers.my_openai]
type = "openai_legacy"               # Must match a ProviderType value

base_url = "https://api.openai.com/v1"
api_key = "sk-XXXXXXXXXXXXXXXXXXXX"  # Stored internally as SecretStr

Supported type values include openai, anthropic, together, custom_http, and openai_legacy. Optional fields include env for environment variable injection and custom_headers for additional HTTP headers.

Step 2: Register the Model Configuration

Models link a provider to a specific model identifier and declare its operational constraints. The LLMModel class in src/kimi_cli/config.py (line 60) validates these entries, requiring a reference to a defined provider and a list of capabilities from the ModelCapability enum in src/kimi_cli/llm.py.

Define your custom model under [models.<key>]:

[models.gpt4o_custom]
provider = "my_openai"               # References [providers.my_openai]

model = "gpt-4o-mini"                # Provider-specific model identifier

max_context_size = 128000            # Token limit for context window

capabilities = ["image_in"]          # List of supported ModelCapability values

display_name = "GPT-4o Mini (Custom)" # Optional human-readable label

The capabilities field must accurately reflect what the underlying provider supports; otherwise, the runtime will raise validation errors when attempting to use unsupported features.

Step 3: Set the Default Model (Optional)

To use your custom model automatically without specifying --model on every command, set the default_model key at the top level of the configuration file. The validator in Config.validate_model ensures this key exists in the [models] section.

default_model = "gpt4o_custom"

If omitted, you must explicitly select the model via CLI arguments for each invocation.

Step 4: Verify and Use the Configuration

The CLI reads the configuration on each startup via load_config(). You can verify the setup programmatically before running commands:

from kimi_cli.config import load_config

cfg = load_config()
print(f"Default: {cfg.default_model}")
print(f"Provider URL: {cfg.providers['my_openai'].base_url}")
print(f"Model ID: {cfg.models['gpt4o_custom'].model}")

Use the custom model via command line:

# Use as default (if configured)

kimi "Explain quantum computing"

# Override for a single invocation

kimi --model gpt4o_custom "Generate a Python script"

When executing commands, the CLI passes the selected model to the application layer in src/kimi_cli/app.py (around line 190 in KimiCLI.create), which retrieves the associated provider configuration and instantiates the appropriate client from src/kimi_cli/llm.py.

Troubleshooting Common Configuration Errors

Symptom	Root Cause	Solution
"Model does not support required capability: image_in"	Capability listed in model config but not supported by provider	Verify capabilities against the ModelCapability enum in src/kimi_cli/llm.py and provider documentation
"Default model not found in models"	default_model key mismatch	Ensure the string exactly matches a key in the [models] table
Authentication failures	Missing or malformed api_key	Verify the key format; use the env field to reference shell environment variables instead of hardcoding
Context length exceeded	max_context_size too low for input	Increase the value in the model configuration to match the provider's actual limits (e.g., 128000 for GPT-4o)

Summary

• Configuration Location: kimi-cli uses ~/.kimi/config.toml parsed by load_config() in src/kimi_cli/config.py
• Provider Setup: Define [providers.name] entries with type, base_url, and api_key corresponding to the LLMProvider model
• Model Registration: Create [models.name] entries referencing the provider, specifying model identifier, max_context_size, and capabilities
• Activation: Set default_model globally or use --model <key> per command
• Validation: The Config class validates provider references and model capabilities at runtime using Pydantic models defined in the source code

Frequently Asked Questions

What file format does kimi-cli use for configuration?

kimi-cli uses TOML format for its configuration file located at ~/.kimi/config.toml. The file is parsed using Pydantic models defined in src/kimi_cli/config.py, specifically the Config class which validates the structure of providers and models on every CLI startup.

Can I use environment variables instead of hardcoding API keys?

Yes. Instead of setting api_key directly in the provider configuration, you can use the optional env field to specify environment variable names and values. The LLMProvider model in src/kimi_cli/config.py supports this field for injecting variables into the provider's runtime environment, keeping sensitive credentials out of the configuration file.

How do I switch between multiple custom models?

You can define multiple entries under [models] in the configuration file. Switch between them either by changing the default_model value in the TOML file and restarting the CLI, or by using the --model flag followed by the model key (e.g., kimi --model my_model_name "prompt") to override the default for a single invocation.

What provider types are supported for custom endpoints?

The ProviderType enum in src/kimi_cli/llm.py defines supported types including openai, openai_legacy, anthropic, together, and custom_http. For self-hosted or non-standard endpoints, openai_legacy or custom_http typically provide the necessary compatibility with OpenAI-style API specifications.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}