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

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 and processed throughout the OAuth toolkit.

The five critical environment variables are:

• KIMI_CODE_HOME – Specifies the directory containing config.json. Default is ~/.kimi-code. Referenced at line 289 in 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.
• 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:

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.

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

kimi config get

Set the default model:

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

Enable thinking mode:

kimi config set thinking.enabled true

Add a custom provider with inline JSON:

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

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:

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.
• 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.

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.

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