# How to Configure Kimi-Code Settings: Environment Variables, Config Files, and CLI Commands

> Configure Kimi-Code settings using environment variables, the config.json file, or CLI commands. Learn to manage models, credentials, and providers for effective development.

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

---

**Configure Kimi-Code by setting environment variables for global overrides, editing the JSON config file at `$KIMI_CODE_HOME/config.json`, or using the `kimi config` CLI commands to manage settings like default models, OAuth credentials, and MCP providers.**

Kimi-Code, the AI coding assistant from the MoonshotAI/kimi-code repository, relies on a layered configuration system that reads settings at startup from multiple sources. Understanding how to configure Kimi-Code settings properly allows you to customize API endpoints, authentication tokens, and model preferences while ensuring the CLI and UI share the same configuration state.

## Environment Variables for Global Overrides

Kimi-Code checks specific environment variables before reading the user config file, allowing you to override paths and endpoints without modifying JSON. These variables are defined in [`packages/oauth/src/constants.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/oauth/src/constants.ts) and processed throughout the OAuth toolkit.

The five critical environment variables are:

- **KIMI_CODE_HOME** – Specifies the directory containing [`config.json`](https://github.com/MoonshotAI/kimi-code/blob/main/config.json). Default is `~/.kimi-code`. Referenced at line 289 in [`packages/oauth/src/toolkit.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/oauth/src/toolkit.ts).
- **KIMI_CODE_BASE_URL** – Sets the MCP server endpoint. Default is `https://api.moonshot.ai/v1`. Referenced at line 121 in [`packages/oauth/src/identity.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/oauth/src/identity.ts).
- **KIMI_CODE_OAUTH_HOST** – Defines the host for OAuth exchanges when using custom providers.
- **KIMI_CODE_OAUTH_KEY** – Determines the key name for storing OAuth tokens in the config file. Default is `"kimi-code"`.
- **KIMI_CODE_FLOW_CONFIG** – Optional flags for controlling OAuth flow behavior.

Set these in your shell profile to apply them globally:

```bash
export KIMI_CODE_HOME=$HOME/.kimi-code
export KIMI_CODE_BASE_URL=https://gw.example.com/
export KIMI_CODE_OAUTH_HOST=https://auth.example.com/

```

## User Config File Structure

The persistent user configuration lives in `$KIMI_CODE_HOME/config.json` (defaulting to `~/.kimi-code/config.json`). This file conforms to the **ManagedKimiConfigShape** type and is read by the `Toolkit.readConfig()` function in [`packages/oauth/src/toolkit.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/oauth/src/toolkit.ts).

Key configuration fields include:

- **defaultModel** – The model identifier used when none is specified, such as `"moonshot-cn/kimi-k2-0712-preview"`.
- **thinking.enabled** – Boolean flag to enable the reasoning mode feature.
- **providers** – Map of provider names to definitions, including OAuth configuration blocks.
- **models** – Map of model identifiers to their provider assignments and capabilities.

The file is parsed with Zod validation to ensure type safety. When you modify this JSON directly or via the CLI, the changes take effect immediately on the next Kimi-Code startup.

## MCP Configuration Schema

Kimi-Code communicates with Model-Context-Protocol (MCP) servers to discover available models. The configuration response follows the **ConfigResponse** type defined in [`packages/protocol/src/rest/config.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/protocol/src/rest/config.ts) (lines 11-33).

When the client queries the `/mcp-config` endpoint, the server returns a payload matching `configResponseSchema`. Kimi-Code merges this data into your user config under the `providers` and `models` keys, enabling you to select from dynamically available models without manual JSON editing.

## CLI Commands for Configuration

The `kimi` CLI provides the `config` subcommand for safe, validated edits to your settings without manually opening the JSON file. These commands call `Toolkit.readConfig()` and `Toolkit.writeConfig()` internally, ensuring Zod schema compliance.

View your current configuration:

```bash
kimi config get

```

Set the default model:

```bash
kimi config set defaultModel moonshot-cn/kimi-k2-0712-preview

```

Enable thinking mode:

```bash
kimi config set thinking.enabled true

```

Add a custom provider with inline JSON:

```bash
kimi config set providers.mycustom '{"type":"custom","oauth":{"host":"https://login.myco.com"}}'

```

## Step-by-Step Configuration Workflow

To properly initialize or modify your Kimi-Code installation:

1. **Set the home directory** (optional) by exporting `KIMI_CODE_HOME` to change where [`config.json`](https://github.com/MoonshotAI/kimi-code/blob/main/config.json) is stored.
2. **Initialize the config** using `kimi config get` to verify the file exists, or create it manually at `$KIMI_CODE_HOME/config.json`.
3. **Configure authentication** either by setting `KIMI_CODE_OAUTH_KEY` or running `kimi login` to store tokens securely.
4. **Adjust endpoints** by setting `KIMI_CODE_BASE_URL` if targeting a non-default MCP server.
5. **Verify settings** with `kimi config get` to confirm the JSON structure is valid and your changes persist.

Because the configuration is read on every startup, modifications apply immediately to subsequent CLI invocations or UI sessions.

## Programmatic Configuration Access

When extending Kimi-Code or building internal tools, you can access configuration programmatically using the same utilities the CLI employs.

Load and inspect the current configuration:

```typescript
import { Toolkit } from '#/packages/oauth/src/toolkit';

// Automatically resolves $KIMI_CODE_HOME
const cfg = await Toolkit.readConfig();   // Returns ManagedKimiConfigShape

console.log('Default model:', cfg.defaultModel);

```

Override settings via environment variables in Node.js:

```typescript
process.env.KIMI_CODE_BASE_URL = 'https://gw.example.com/';

import { getBaseUrl } from '#/packages/oauth/src/identity';
console.log(getBaseUrl());   // Outputs: https://gw.example.com/

```

## Summary

- **Environment variables** provide global overrides for paths, base URLs, and OAuth settings without touching the config file.
- **User config file** at `$KIMI_CODE_HOME/config.json` stores persistent preferences including default models and provider definitions, validated against `ManagedKimiConfigShape` in [`packages/oauth/src/toolkit.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/oauth/src/toolkit.ts).
- **CLI commands** (`kimi config get/set`) offer a safe interface for editing JSON values while maintaining Zod schema compliance.
- **MCP configuration** dynamically populates available models by merging server responses into the user config under the `providers` and `models` keys.
- **Immediate effect**: All configuration changes apply on the next startup since Kimi-Code reads these sources fresh each session.

## Frequently Asked Questions

### Where is the Kimi-Code config file stored?

By default, Kimi-Code stores its configuration in `~/.kimi-code/config.json`. You can override this location by setting the `KIMI_CODE_HOME` environment variable to a custom directory path, which the toolkit reads at line 289 in [`packages/oauth/src/toolkit.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/oauth/src/toolkit.ts).

### How do I change the default model in Kimi-Code?

Use the CLI command `kimi config set defaultModel <model-id>` or manually edit the `defaultModel` field in `$KIMI_CODE_HOME/config.json`. The value should match a model identifier defined in your `models` configuration, such as `"moonshot-cn/kimi-k2-0712-preview"`.

### Can I use environment variables instead of editing the config file?

Yes. Kimi-Code supports environment variables like `KIMI_CODE_BASE_URL` and `KIMI_CODE_OAUTH_HOST` that take precedence over file-based settings. These are processed directly by the OAuth toolkit and identity modules, allowing you to inject configuration in CI/CD pipelines or containerized environments without mounting config files.

### What is the ManagedKimiConfigShape type?

**ManagedKimiConfigShape** is the TypeScript type definition that describes the valid structure of the user configuration file, including fields for `defaultModel`, `thinking.enabled`, `providers`, and `models`. It is defined in the OAuth package and enforced via Zod validation when `Toolkit.readConfig()` is called in [`packages/oauth/src/toolkit.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/oauth/src/toolkit.ts).