How to Configure Model Aliases and Overrides in Kimi Code's config.toml

Kimi Code reads runtime configuration from ~/.kimi-code/config.toml, where the [models] section supports an aliases array for alternate model names and an overrides table for property customization, validated against the schema in packages/agent-core-v2/docs/config-manifest.toml.

The MoonshotAI/kimi-code repository centralizes all runtime settings in a single TOML file. The [models] section allows you to define custom model entries with alternate identifiers and modified properties that propagate through the CLI, REST API, and Node SDK.

Understanding the Models Section Structure

Each model definition resides under the [models] section as a TOML table named models."<identifier>". The Config Manifest at packages/agent-core-v2/docs/config-manifest.toml (lines 20-44) defines the valid schema for these entries, specifying that each model table must contain provider_id and model fields, alongside optional aliases and overrides.

The aliases field accepts an array of strings that serve as alternate human-readable names. The overrides field accepts a nested object that replaces default model properties such as context limits, capabilities, or display names. When Kimi Code starts, the server loads ~/.kimi-code/config.toml, merges values against the manifest defaults at packages/kap-server/src/start.ts (line 332), and constructs an in-memory Model Catalog exposed via the GET /models REST endpoint defined in packages/kap-server/src/routes/modelCatalog.ts.

Adding Model Aliases in config.toml

To create an alias, add the aliases array to your model table. Users can then reference any string in this array when selecting models via the CLI, TUI, or API.

[models.my-gemini]
provider_id = "google"
model = "gemini-1.5-flash"
aliases = ["gemini-flash", "g-flash"]

After saving the file, Kimi Code automatically rebuilds the Model Catalog. You can verify alias registration through the SDK's listModels() method or by querying the GET /models endpoint.

Applying Property Overrides

The overrides table allows per-model customization without modifying upstream provider definitions. Only specified properties are replaced; all others fall back to base model defaults.

[models.my-gemini]
provider_id = "google"
model = "gemini-1.5-flash"
aliases = ["gemini-flash"]

[models.my-gemini.overrides]
max_context_size = 8192
display_name = "Gemini Flash-Pro"
capabilities = ["text", "image"]

Common override fields include max_context_size to adjust context windows, display_name for UI-friendly labels, and capabilities to expose specific features like vision or reasoning. These overrides apply after the model loads, affecting both runtime limits and UI representation.

Validation and Runtime Behavior

Kimi Code validates config.toml against the Config Manifest automatically. Invalid keys generate warnings but do not prevent the engine from starting, as implemented in commit #689. The packages/kap-server/src/routes/modelCatalog.ts route handles dynamic updates to the models section, rebuilding aliases and applying overrides on each configuration change.

The Model Catalog service populates during server startup at packages/kap-server/src/start.ts (line 332), making configured aliases and overrides immediately available to the REST API and SDK.

Accessing Configured Models via the Node SDK

The Node SDK exposes the Model Catalog through packages/node-sdk/src/kimi-harness.ts (line 260), providing methods to list models and set defaults using alias names.

import { createKimiClient } from '@moonshot-ai/kimi-code-sdk';

const client = await createKimiClient();
const models = await client.listModels(); // Returns aliases and override values

await client.setDefaultModel('gemini-flash'); // Selects using alias

The setDefaultModel() function resolves aliases to their canonical model entries, honoring any overrides defined in config.toml.

Summary

• Configure model aliases and overrides in ~/.kimi-code/config.toml under the [models] section.
• Use the aliases array to define alternate selectable names for any model entry.
• Use the overrides table to customize max_context_size, display_name, capabilities, and other properties.
• Changes are validated against packages/agent-core-v2/docs/config-manifest.toml and applied at runtime via packages/kap-server/src/routes/modelCatalog.ts.
• Access aliases programmatically through the Node SDK at packages/node-sdk/src/kimi-harness.ts using listModels() and setDefaultModel().

Frequently Asked Questions

Can I use aliases to switch between different providers without changing configuration files?

No. Aliases map to a single model entry defined in config.toml and cannot redirect to different provider_id values. To switch providers, define separate model entries under [models] and select the appropriate identifier or alias.

What happens if I define conflicting overrides for the same model?

Kimi Code applies the overrides table defined in your model entry last, overwriting any defaults from the Config Manifest. If you define the same override key multiple times within a single table, TOML parsing rules apply the last defined value.

Do model aliases work with the Kimi Code REST API?

Yes. The GET /models endpoint defined in packages/kap-server/src/routes/modelCatalog.ts returns the complete Model Catalog including all configured aliases. When selecting models via API calls, you can pass any alias string defined in the aliases array.

Where does Kimi Code store the configuration file on different operating systems?

Kimi Code stores config.toml at ~/.kimi-code/config.toml, resolving the home directory according to platform conventions ($HOME on Unix systems, %USERPROFILE% on Windows). The server loads this path during startup at packages/kap-server/src/start.ts (line 332).

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