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

You configure custom LLM providers in Kimi Code by declaring them in the [providers] table of 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 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) handles the provider and model registries. This service maintains synchronization between the 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 (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, 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 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.

[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:

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

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

[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:

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

Then export the variables in your shell:

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

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

[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:

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

Summary

• Kimi Code uses a free-form provider type system in config.toml that accepts any OpenAI‑compatible endpoint without code changes.
• KosongConfigService (at 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 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 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, 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 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.

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