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

> Learn how to set up a custom model with kimi-cli. Configure your provider and model in config.toml for seamless integration and flexible model selection.

- Repository: [Moonshot AI/kimi-cli](https://github.com/MoonshotAI/kimi-cli)
- Tags: how-to-guide
- Published: 2026-07-25

---

**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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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:

```bash
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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/llm.py) enumerates supported backend types.

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

```toml
[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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/llm.py).

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

```toml
[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.

```toml
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:

```python
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:

```bash

# 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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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.