Environment variables

August 20, 2026 · View on GitHub

Kimi Code CLI uses environment variables to control a small number of runtime behaviors — relocating the data directory, turning off telemetry, and temporarily switching models without touching the config file.

::: warning Important: API keys are not configured here Credential variables such as KIMI_API_KEY, ANTHROPIC_API_KEY, and OPENAI_API_KEY are not read automatically from shell environment variables. Running export KIMI_API_KEY=xxx in the terminal does not give any provider its key — they must be written in config.toml under [providers.<name>] or the [providers.<name>.env] sub-table.

The only exception is the KIMI_MODEL_* family, which is an explicit channel that does read credentials from the shell — see Define a model from environment variables.

For background, see Config overrides: provider credentials. :::

Core paths

`KIMI_CODE_HOME`

Overrides the data root directory; the default is ~/.kimi-code. Once set, the config file, sessions, logs, OAuth credentials, and all other data land under the new path:

export KIMI_CODE_HOME="/path/to/custom/kimi-code"

Make sure the directory is writable. Multiple kimi instances sharing the same KIMI_CODE_HOME will share config and credential files.

For the complete data directory structure, see Data locations.

`KIMI_DISABLE_TELEMETRY`

Set to 1 to turn off anonymous telemetry reporting (also accepts true, yes, y, case-insensitive):

export KIMI_DISABLE_TELEMETRY=1

`KIMI_MODEL_*` family

Switch models temporarily without modifying config.toml — when KIMI_MODEL_NAME is set, the CLI synthesizes a temporary provider in memory; the change does not persist after restart. See Define a model from environment variables.

`KIMI_CODE_CUSTOM_HEADERS`

Attaches custom HTTP headers to every outbound model request — both LLM chat requests (across all provider protocols) and /models listing requests. Useful when a gateway routes by header, for example to pin a specific cluster:

export KIMI_CODE_CUSTOM_HEADERS=$'X-Gateway-Cluster: my-cluster\nX-Custom-Tag: debug'

The format mirrors ANTHROPIC_CUSTOM_HEADERS: newline-separated Name: Value lines. Names and values are trimmed, and lines without a colon are ignored.

::: info Added Added in 0.20.2. :::

Precedence: the Kimi identity headers (User-Agent, X-Msh-*) and a provider's custom_headers in config.toml (see Config files) override same-named entries here. Authentication is protocol-dependent: on the kimi, openai, and openai_responses protocols an exact Authorization entry replaces the generated bearer token, while /models listing requests keep their own authentication. A case variant such as authorization is never treated as the same name — it is combined with the real header, which can break requests. Do not use this variable for authentication or other reserved headers. Use custom_headers when headers need to differ per provider.

Provider credential key names (written in config.toml)

The key names below are not read directly from the shell — they are key names written inside the [providers.<name>.env] sub-table of config.toml, serving as fallback values for api_key / base_url. The CLI reads only from the config file, not from process.env.

This design lets you keep familiar key name conventions while centralizing secret management in the config file:

[providers.kimi.env]
KIMI_API_KEY = "sk-xxx"
KIMI_BASE_URL = "https://api.moonshot.ai/v1"

Key names per provider:

Key	Applicable provider	Default
`KIMI_API_KEY`	Kimi / Moonshot	None
`KIMI_BASE_URL`	Kimi / Moonshot	`https://api.moonshot.ai/v1`
`ANTHROPIC_API_KEY`	Anthropic	None
`ANTHROPIC_BASE_URL`	Anthropic	Follows Anthropic SDK default
`OPENAI_API_KEY`	OpenAI (`openai` and `openai_responses`)	None
`OPENAI_BASE_URL`	OpenAI (`openai` and `openai_responses`)	`https://api.openai.com/v1`
`GOOGLE_API_KEY`	Google GenAI, Vertex AI	None
`VERTEXAI_API_KEY`	Vertex AI	None
`GOOGLE_CLOUD_PROJECT`	Vertex AI	None
`GOOGLE_CLOUD_LOCATION`	Vertex AI	None

::: warning GOOGLE_APPLICATION_CREDENTIALS (path to a service account JSON file) is the only exception that goes through the system environment variable mechanism — it is read by the Google SDK directly via the standard ADC flow, and the CLI does not participate. All other key names must be placed in the [providers.<name>.env] sub-table to take effect. :::

For the full provider type and field reference, see Providers and models.

OAuth and managed services

This group of variables redirects OAuth authentication and managed service endpoints to a self-hosted or test environment. They are not needed for everyday use.

Variable	Purpose	Default
`KIMI_CODE_OAUTH_HOST`	OAuth auth host; highest priority	Falls back to `KIMI_OAUTH_HOST` when unset
`KIMI_OAUTH_HOST`	OAuth auth host; fallback for `KIMI_CODE_OAUTH_HOST`	Falls back to `https://auth.kimi.com` when unset
`KIMI_CODE_BASE_URL`	Managed API base URL used after OAuth login	`https://api.kimi.com/coding/v1`

::: warning KIMI_CODE_BASE_URL (OAuth-managed service, targeting kimi.com) and KIMI_BASE_URL (direct API key connection, targeting moonshot.ai) are two distinct variables. Use each one in its appropriate context. :::

Define a model from environment variables (`KIMI_MODEL_*`)

Want to switch models for testing without touching config.toml? When KIMI_MODEL_NAME is set, the CLI synthesizes a temporary provider and model alias from the KIMI_MODEL_* variables in memory — nothing is written back to the config file. These variables take priority over default_model in config.toml, but the -m <alias> option at startup still has the highest priority.

export KIMI_MODEL_NAME="kimi-for-coding"
export KIMI_MODEL_API_KEY="YOUR_API_KEY"
export KIMI_MODEL_BASE_URL="https://api.example.com/v1"
export KIMI_MODEL_MAX_CONTEXT_SIZE="262144"
export KIMI_MODEL_CAPABILITIES="image_in,thinking"
kimi

Complete variable list:

Variable	Required	Purpose	Default
`KIMI_MODEL_NAME`	Yes (also the enable switch)	Model id sent to the API	—
`KIMI_MODEL_API_KEY`	Yes	API key	—
`KIMI_MODEL_PROVIDER_TYPE`	No	Provider type: `kimi`, `anthropic`, `openai`	`kimi`
`KIMI_MODEL_BASE_URL`	No	API base URL	Each type has its own default
`KIMI_MODEL_MAX_CONTEXT_SIZE`	No	Maximum context length (tokens)	`262144` (256 K)
`KIMI_MODEL_CAPABILITIES`	No	Comma-separated capability tags, unioned with auto-detected capabilities	`image_in,thinking`
`KIMI_MODEL_DISPLAY_NAME`	No	Name shown in `/model`	Falls back to `KIMI_MODEL_NAME`
`KIMI_MODEL_MAX_OUTPUT_SIZE`	No	Per-request output cap (`anthropic` only); when set, overrides the built-in Claude ceiling	Model default
`KIMI_MODEL_REASONING_KEY`	No	Reasoning field name override (`openai` only)	Auto-detected
`KIMI_MODEL_THINKING_EFFORT`	No	Thinking effort level: `low`/`medium`/`high`/`xhigh`/`max`	—
`KIMI_MODEL_ADAPTIVE_THINKING`	No	Force adaptive thinking on or off (`anthropic` only)	Inferred from model name

If KIMI_MODEL_NAME is set but a required variable is missing, startup fails immediately with a clear error message.

Runtime switches

Switches that control the behavior of subsystems such as telemetry, background tasks, and the plugin marketplace:

Variable	Purpose	Valid values
`KIMI_DISABLE_TELEMETRY`	Disable anonymous telemetry reporting	`1`, `true`, `yes`, `y` (case-insensitive)
`KIMI_CODE_PASSWORD`	Set a parallel auth credential for the `kimi web` local server, valid alongside the bearer token; recommended when binding the server beyond loopback — see Local server and API	Any non-empty string; when unset, only the token is valid
`KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT`	Whether to keep background tasks when the session closes; takes higher priority than `config.toml`. The default is to stop them on exit	Truthy: `1`/`true`/`yes`/`on`; falsy: `0`/`false`/`no`/`off`
`KIMI_CODE_BACKGROUND_MAX_RUNNING_TASKS`	Cap on concurrently running background tasks; takes higher priority than `[background] max_running_tasks` in `config.toml` (unset means no cap)	Positive integer; invalid values are ignored
`KIMI_IMAGE_MAX_EDGE_PX`	Longest-edge ceiling (px) for image compression; takes higher priority than `[image] max_edge_px` in `config.toml` (default `2000`)	Positive integer; invalid values are ignored
`KIMI_IMAGE_READ_BYTE_BUDGET`	Per-image byte budget for model-initiated image reads (`ReadMediaFile` default reads); takes higher priority than `[image] read_byte_budget` in `config.toml` (default `262144`, i.e. 256 KB)	Positive integer; invalid values are ignored
`KIMI_CODE_PLUGIN_MARKETPLACE_URL`	Override the plugin marketplace JSON loaded by `/plugins`; useful for dev loopback servers, staging CDN files, or alternate marketplace directories	`https://code.kimi.com/kimi-code/plugins/marketplace.json`; also accepts `http://`, `file://` URLs, and local paths
`KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY`	Cap how many AgentSwarm subagents run concurrently during the initial ramp; leave unset for no cap	Positive integer; invalid values fail fast
`KIMI_SUBAGENT_TIMEOUT_MS`	Maximum wall-clock time (ms) a single subagent (`Agent` / `AgentSwarm`) may run; takes higher priority than `[subagent] timeout_ms` in `config.toml` (default `7200000`, i.e. 2 hours)	Positive integer; invalid values fall back to the config or default
`KIMI_CODE_IDENTITY_NAME`	Display name the agent calls itself in the system prompt; takes higher priority than `[identity] name` in `config.toml` and is never written back to it	Any non-empty string; blank values read as unset
`KIMI_CODE_IDENTITY_SLUG`	Protocol identifier for the `User-Agent` product token sent to third-party providers and the MCP client name; takes higher priority than `[identity] slug`. Derived from the name when unset	Any non-empty string; normalized to lowercase with non-alphanumeric runs folded to `-`
`KIMI_CODE_BUILTIN_PRODUCT_SKILLS`	Whether the built-in skills documenting Kimi Code itself are offered to the model; takes higher priority than `builtin_product_skills` in `config.toml` (default enabled)	Truthy: `1`/`true`/`yes`/`on`; falsy: `0`/`false`/`no`/`off`
`KIMI_CODE_TUI_FULL_SCREEN`	Enable the experimental fullscreen alternate-screen UI: scrollable transcript viewport, mouse text selection, clickable links, and Ctrl-Shift-F transcript search	`1` enables it; anything else keeps the regular inline UI
`KIMI_CODE_EXPERIMENTAL_SECONDARY_MODEL`	Enable the experimental subagent model pool in every launch mode, including the interactive TUI; the master `KIMI_CODE_EXPERIMENTAL_FLAG=1` also enables it	Truthy: `1`/`true`/`yes`/`on`; falsy: `0`/`false`/`no`/`off`
`KIMI_CODE_EXPERIMENTAL_SUBAGENT_FORK`	Enable the experimental `fork` parameter on the `Agent` and `AgentSwarm` tools, letting the model start a subagent with a snapshot of the calling agent's conversation history instead of an empty context; the master `KIMI_CODE_EXPERIMENTAL_FLAG=1` also enables it	Truthy: `1`/`true`/`yes`/`on`; falsy: `0`/`false`/`no`/`off`
`KIMI_MCP_STARTUP_TIMEOUT_MS`	Global default connection timeout (ms) for all MCP servers; takes higher priority than `[mcp] startup_timeout_ms` in `config.toml`, but a per-server `startupTimeoutMs` in `mcp.json` still wins (default `30000`)	Integer from `1` to `2147483647`; invalid values are ignored
`KIMI_MCP_TOOL_TIMEOUT_MS`	Global default single tool-call timeout (ms) for all MCP servers; takes higher priority than `[mcp] tool_timeout_ms` in `config.toml`, but a per-server `toolTimeoutMs` in `mcp.json` still wins (default `60000`)	Integer from `1` to `2147483647`; invalid values are ignored
`KIMI_LOOP_MAX_STEPS_PER_TURN`	Maximum Agent steps per turn; takes higher priority than `[loop_control] max_steps_per_turn` in `config.toml` (unset or `0` means unlimited)	Non-negative integer; invalid values are ignored
`KIMI_LOOP_MAX_ATTEMPTS_PER_STEP`	Maximum total attempts for a failing step (including the initial attempt); takes higher priority than `[loop_control] max_attempts_per_step` in `config.toml` (default `10`). The deprecated `KIMI_LOOP_MAX_RETRIES_PER_STEP` is still honored with a warning when this variable is unset	Non-negative integer; invalid values are ignored
`KIMI_TOKEN_COUNTING_STRATEGY`	Which context token count is reported externally (the context-size display); takes higher priority than `[token_counting] strategy` in `config.toml` (default `measured+estimated`)	`measured+estimated`, `measured`, `estimated` (case-insensitive); invalid values are ignored
`KIMI_WEB_SEARCH_BASE_URL`	API URL of the web search (`WebSearch`) service; takes higher priority than `[services.moonshot_search] base_url` in `config.toml`, and enables the service without that config section. Persisted credentials and custom headers are not forwarded to an env-selected endpoint	Non-blank string; blank values are ignored
`KIMI_WEB_SEARCH_API_KEY`	API key of the web search (`WebSearch`) service; replaces both the configured API key and OAuth credential when set	Non-blank string; blank values are ignored
`KIMI_WEB_FETCH_BASE_URL`	API URL of the web fetch (`FetchURL`) service; takes higher priority than `[services.moonshot_fetch] base_url`. Persisted credentials and custom headers are not forwarded to an env-selected endpoint. Without an env or config endpoint, signed-in users try the managed Kimi OAuth fetch service before direct local requests	Non-blank string; blank values are ignored
`KIMI_WEB_FETCH_API_KEY`	API key of the web fetch (`FetchURL`) service; replaces both the configured API key and OAuth credential when set	Non-blank string; blank values are ignored
`KIMI_CODE_EXPERIMENTAL_FLAG`	Enable all registered experimental features for this process; it does not select the agent engine	`1`, `true`, `yes`, `on`
`KIMI_CODE_LEGACY_FLAG`	Use the legacy `agent-core` engine for `kimi`, `kimi -p`, `kimi doctor`, `kimi acp`, `kimi export`, and `kimi provider`; these commands use `agent-core-v2` by default	`1`, `true`, `yes`, `on`
`KIMI_SHELL_PATH`	Override the Git Bash path on Windows (used when auto-detection fails)	Absolute path
`KIMI_MODEL_MAX_COMPLETION_TOKENS`	Hard cap on `max_completion_tokens` per LLM step; applies to the `kimi` provider only	Positive integer; `0` or negative disables clamping
`KIMI_MODEL_TEMPERATURE`	Sampling temperature for every request; applies to the `kimi` provider only (global — independent of `KIMI_MODEL_NAME`)	Number, e.g. `0.3`
`KIMI_MODEL_TOP_P`	Nucleus-sampling `top_p` for every request; applies to the `kimi` provider only (global)	Number, e.g. `0.95`
`KIMI_MODEL_THINKING_EFFORT`	Force a specific thinking effort on the wire (`thinking.effort`), bypassing the model's declared `support_efforts`; applies to the `kimi` provider only, and only while Thinking is on	An effort value, e.g. `max`
`KIMI_MODEL_THINKING_KEEP`	Preserved-thinking passthrough; on `kimi` sent as `thinking.keep`, on `anthropic` (Claude and Kimi's Anthropic-compatible mode) sent as a `context_management` `clear_thinking_20251015` edit (enabling keep routes Anthropic requests to the beta Messages API); overrides `[thinking] keep` (which defaults to `"all"`); only injected while Thinking is on	A value the API accepts, e.g. `all`; an off-value (`false`/`0`/`no`/`off`/`none`/`null`) disables it
`KIMI_CODE_NO_AUTO_UPDATE`	Fully disable the update preflight — no check, background install, or prompt. Legacy alias `KIMI_CLI_NO_AUTO_UPDATE` is also honored	Truthy: `1`/`true`/`yes`/`on`
`KIMI_DISABLE_CRON`	Disable the scheduled-task tool (`CronCreate` rejects new schedules; existing tasks do not fire)	`1` to disable

The three KIMI_CODE_IDENTITY_* / KIMI_CODE_BUILTIN_PRODUCT_SKILLS variables are read by the default agent-core-v2 engine. The legacy kimi / kimi -p path selected with KIMI_CODE_LEGACY_FLAG=1 ignores them.

Diagnostic logs

These variables control log level and file rotation, read once at process startup:

Variable	Purpose	Default
`KIMI_LOG_LEVEL`	Log level: `off`, `error`, `warn`, `info`, `debug`	`info`
`KIMI_LOG_GLOBAL_MAX_BYTES`	Maximum bytes per global log file	`6291456` (6 MB)
`KIMI_LOG_GLOBAL_FILES`	Number of global log files to retain	`5`
`KIMI_LOG_SESSION_MAX_BYTES`	Maximum bytes per session log file	`5242880` (5 MB)
`KIMI_LOG_SESSION_FILES`	Number of session log files to retain	`3`

System environment variables

The CLI also reads several standard system variables to detect the runtime environment; it does not modify them:

HOME: used to resolve the default data path
VISUAL, EDITOR: external editor command (VISUAL takes precedence)
PATH: used to locate dependencies such as rg, fd, fdfind, and git; on Windows, Git Bash detection checks each git.exe found on PATH, including package-manager shims such as Scoop
NO_COLOR, FORCE_COLOR: control color output (following the no-color.org convention)
CI: when non-empty and not "0", disables theme detection and falls back to the dark theme
TERM_PROGRAM, TERM, TMUX: detect terminal features and notification support
DISPLAY, WAYLAND_DISPLAY, XDG_SESSION_TYPE: detect Linux graphical sessions (for clipboard and image features)
WSL_DISTRO_NAME, WSLENV: detect WSL for the clipboard PowerShell bridge
LOCALAPPDATA: used on Windows as a fallback when probing for the Git Bash installation path

HTTP proxy

Kimi Code honors the standard proxy environment variables for all outbound traffic — model API calls, MCP servers, web tools, telemetry, sign-in, and update checks:

HTTP_PROXY / http_proxy: proxy for http:// requests
HTTPS_PROXY / https_proxy: proxy for https:// requests
ALL_PROXY / all_proxy: fallback proxy used when the scheme-specific variable is unset; this is where a SOCKS proxy is usually set
NO_PROXY / no_proxy: comma-separated hosts that bypass the proxy

Both HTTP(S) and SOCKS proxies are supported. A SOCKS proxy is recognized by its scheme — socks5://, socks5h://, socks4://, or socks:// (an alias for socks5://) — and is typically set via ALL_PROXY (the form used by tools like Clash and V2RayN). An HTTP(S) proxy takes precedence over ALL_PROXY for HTTP/HTTPS traffic.

The proxy is applied only when one of these variables is set; otherwise connections are made directly. Loopback hosts (localhost, 127.0.0.1, ::1) always bypass the proxy, so a local server such as a localhost MCP server keeps working when a proxy is configured — add your own internal hosts to NO_PROXY to exempt them too.

Stdio MCP servers that run as Node child processes honor HTTP_PROXY / HTTPS_PROXY / NO_PROXY automatically when the child's Node version supports NODE_USE_ENV_PROXY (Node ≥ 22.21 or ≥ 24.5); SOCKS proxying applies to Kimi Code's own traffic only.

Next steps

Config overrides — how environment variables, CLI options, and the config file interact by priority
Data locations — directory structure affected by KIMI_CODE_HOME
Providers and models — full connection examples per provider type