# How to Configure Custom LLM Providers in Kimi Code: Beyond Built-in Models

> Configure custom LLM providers in Kimi Code by adding them to config.toml. Integrate any OpenAI compatible endpoint easily without modifying core files.

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

---

**You configure custom LLM providers in Kimi Code by declaring them in the `[providers]` table of [`config.toml`](https://github.com/MoonshotAI/kimi-code/blob/main/config.toml) using a free-form `type` field, which allows any OpenAI‑compatible endpoint to integrate without modifying the core codebase.**

Kimi Code separates provider configuration from model definitions, enabling you to integrate third-party LLM services alongside the default Kimi models. This architecture, implemented in the `MoonshotAI/kimi-code` repository, relies on the **kosong** abstraction layer to synchronize settings between [`config.toml`](https://github.com/MoonshotAI/kimi-code/blob/main/config.toml) and the runtime registries located at `packages/agent-core-v2/src/app/kosongConfig/`.

## The Kosong Configuration Architecture

At the heart of Kimi Code's provider system is the **kosong** abstraction layer, which manages the synchronization between persistent configuration and in-memory registries.

**`KosongConfigService`** (lines 31-70 in [`packages/agent-core-v2/src/app/kosongConfig/kosongConfigService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/app/kosongConfig/kosongConfigService.ts)) handles the provider and model registries. This service maintains synchronization between the [`config.toml`](https://github.com/MoonshotAI/kimi-code/blob/main/config.toml) file and runtime state, writing changes to disk via `replaceWithRetry` whenever you add or edit providers, then reloading registries on startup.

The configuration schema lives in [`packages/agent-core-v2/src/app/kosongConfig/configSection.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/app/kosongConfig/configSection.ts) (lines 51-84). Here, **`ProviderTypeSchema`** is defined as a free-form string, meaning you can specify any vendor identifier without changing the repository code. Validation occurs at runtime when the provider is resolved, not at configuration time.

## Supported Provider Protocols

Kimi Code ships with built-in support for several LLM protocols (documented in [`docs/en/configuration/providers.md`](https://github.com/MoonshotAI/kimi-code/blob/main/docs/en/configuration/providers.md), lines 5-17):

| Protocol | Type Value | Use Case |
|----------|------------|----------|
| **Kimi** | `kimi` | MoonshotAI managed service (OpenAI‑compatible) |
| **Anthropic** | `anthropic` | Claude family models (Messages API) |
| **OpenAI** | `openai` | OpenAI Chat Completions or compatible services (DeepSeek, Qwen, etc.) |
| **OpenAI Responses** | `openai_responses` | OpenAI Responses API (newer interface) |
| **Google GenAI** | `google-genai` | Gemini models |
| **Vertex AI** | `vertexai` | Google GenAI on Vertex AI |

These types are pre-configured, but the free-form `type` field allows you to add unlisted providers implementing the OpenAI‑compatible HTTP API.

## Configuring Custom Providers in config.toml

Because the `type` field accepts arbitrary strings, you can point Kimi Code at any OpenAI‑compatible service by editing the configuration file directly.

To add a custom provider:

1. **Open** [`config.toml`](https://github.com/MoonshotAI/kimi-code/blob/main/config.toml) in your Kimi Code configuration directory.
2. **Create** a new entry under `[providers.<name>]`.
3. **Set** `type` to `"openai"` (or another supported protocol).
4. **Specify** `base_url` pointing to your service endpoint.
5. **Provide** `api_key` or environment variable bindings.

```toml
[providers.myservice]
type = "openai"
base_url = "https://api.myservice.com/v1"
api_key = "sk-myservice-abc123"

```

After declaring the provider, reference it in a model definition:

```toml
[models."my-gpt-4"]
provider = "myservice"
model = "gpt-4"
max_context_size = 8192

```

You can also include **custom HTTP headers** for authentication or routing:

```toml
[providers.myservice]
type = "openai"
base_url = "https://api.myservice.com/v1"
api_key = "sk-myservice-abc123"
customHeaders = { "X-Custom-Header" = "value", "X-Organization" = "myorg" }

```

## Environment Variable Binding

For security-sensitive deployments, store credentials in environment variables rather than plain text. Use the `[providers.<name>.env]` sub-table to map environment variables to configuration fields:

```toml
[providers.myservice.env]
API_KEY = "MYSERVICE_API_KEY"
BASE_URL = "MYSERVICE_BASE_URL"

```

Then export the variables in your shell:

```bash
export MYSERVICE_API_KEY="sk-myservice-abc123"
export MYSERVICE_BASE_URL="https://api.myservice.com/v1"

```

**Credential priority rules** (lines 20-21 in [`docs/en/configuration/providers.md`](https://github.com/MoonshotAI/kimi-code/blob/main/docs/en/configuration/providers.md)): When a provider has an explicit `api_key` field, it overrides values in the `[providers.<name>.env]` sub-table. If both are missing, Kimi Code aborts startup with an error.

## Interactive TUI Configuration

You can configure providers without manually editing [`config.toml`](https://github.com/MoonshotAI/kimi-code/blob/main/config.toml) by using the built-in TUI:

1. Launch Kimi Code: `kimi`
2. Press `/provider` to open the provider manager.
3. Select **Add New Platform** → **Known third-party provider** → **OpenAI‑compatible**.
4. Enter the base URL and API key when prompted.

The TUI writes the equivalent TOML configuration automatically and triggers a `ConfigSectionChangedEvent`, which `KosongConfigService` handles to update the runtime registries immediately.

## Custom Registry API Import

For organizations maintaining multiple models, Kimi Code supports importing provider catalogs via a custom registry endpoint (lines 32-36 in [`docs/en/configuration/providers.md`](https://github.com/MoonshotAI/kimi-code/blob/main/docs/en/configuration/providers.md)).

In the TUI's "Add New Platform" flow, select **"Custom registry (api.json)"** and provide:

- The registry URL returning a JSON catalog of providers and models
- A bearer token for authentication

Kimi Code automatically creates the necessary `[providers]` and `[models]` entries in [`config.toml`](https://github.com/MoonshotAI/kimi-code/blob/main/config.toml) based on the remote schema.

## Runtime Provider Resolution

Understanding how Kimi Code resolves providers at runtime helps debug connection issues:

1. **Startup**: `KosongConfigService` reads [`config.toml`](https://github.com/MoonshotAI/kimi-code/blob/main/config.toml) and populates registries via `providers.loadAll()` and `models.loadAll()`.
2. **Modification**: UI edits or manual file changes trigger `ConfigSectionChangedEvent`; the service writes changes via `replaceWithRetry` and updates in-memory registries without requiring a restart.
3. **Resolution**: When code requests a model, **`IModelCatalog`** looks up the provider ID from the model entry, then instantiates the appropriate client using the provider's `type`, `base_url`, and authentication credentials.

This architecture ensures that custom providers are treated identically to built-in ones once configured.

## Complete Configuration Example

Here is a full working configuration integrating a self-hosted OpenAI‑compatible service with environment-based credentials:

**config.toml:**

```toml
[providers.local_llm]
type = "openai"
base_url = "http://localhost:8000/v1"

[providers.local_llm.env]
API_KEY = "LOCAL_API_KEY"

[models."local-llama-70b"]
provider = "local_llm"
model = "llama-3.3-70b"
max_context_size = 128000
temperature = 0.7

```

**Environment setup:**

```bash
export LOCAL_API_KEY="sk-local-test-key"
kimi

```

## Summary

- **Kimi Code** uses a free-form provider type system in [`config.toml`](https://github.com/MoonshotAI/kimi-code/blob/main/config.toml) that accepts any OpenAI‑compatible endpoint without code changes.
- **`KosongConfigService`** (at [`packages/agent-core-v2/src/app/kosongConfig/kosongConfigService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/app/kosongConfig/kosongConfigService.ts)) synchronizes configuration between disk and memory, supporting hot reloading when you modify providers.
- **Credential priority** follows explicit `api_key` fields first, then `[providers.<name>.env]` bindings, then failure.
- **Configuration methods** include manual TOML editing, the `/provider` TUI, or importing custom registry APIs.
- **Runtime resolution** happens through `IModelCatalog`, which instantiates clients based on the provider `type` and `base_url` stored in the kosong registries.

## Frequently Asked Questions

### Can I configure non-OpenAI-compatible providers in Kimi Code?

For providers using bespoke protocols, you would need to implement a new provider adapter in the `kosong` package at `packages/agent-core-v2/`. However, most third-party inference services expose an OpenAI‑compatible façade, which works immediately by setting `type = "openai"` and pointing `base_url` to your endpoint. The free-form `type` field in [`configSection.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/configSection.ts) allows runtime validation for custom protocols, but the SDK must have corresponding client logic.

### Where does Kimi Code store provider configurations?

Provider configurations reside in the `[providers]` table of your [`config.toml`](https://github.com/MoonshotAI/kimi-code/blob/main/config.toml) file, typically located in `~/.config/kimi-code/` or the platform equivalent. **`KosongConfigService`** manages this file at [`packages/agent-core-v2/src/app/kosongConfig/kosongConfigService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/app/kosongConfig/kosongConfigService.ts), ensuring atomic writes via `replaceWithRetry` and loading entries into in-memory registries on startup.

### How do I update provider settings without restarting Kimi Code?

When you modify [`config.toml`](https://github.com/MoonshotAI/kimi-code/blob/main/config.toml) manually or through the `/provider` TUI, Kimi Code emits a `ConfigSectionChangedEvent`. The `KosongConfigService` catches this event and updates the runtime provider and model registries immediately. However, active chat sessions may need to be restarted to pick up new provider instances, as the `IModelCatalog` resolves providers at request time based on the current registry state.

### What is the difference between `openai` and `openai_responses` provider types?

The **`openai`** type uses the traditional OpenAI Chat Completions API (`/v1/chat/completions`), compatible with most third-party inference servers. The **`openai_responses`** type targets the newer OpenAI Responses API, which provides structured output and tool-use capabilities through a different endpoint path. Use `openai` for DeepSeek, Qwen, or self-hosted solutions; use `openai_responses` only when integrating with OpenAI's latest native API features.