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

> Learn to configure model aliases and overrides in Kimi Code's config.toml. Customize your AI model behavior with aliases and property overrides for enhanced control.

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

---

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

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

```toml
[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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk/src/kimi-harness.ts) (line 260), providing methods to list models and set defaults using alias names.

```typescript
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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/docs/config-manifest.toml) and applied at runtime via [`packages/kap-server/src/routes/modelCatalog.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/kap-server/src/routes/modelCatalog.ts).
- Access aliases programmatically through the Node SDK at [`packages/node-sdk/src/kimi-harness.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/kap-server/src/start.ts) (line 332).