Environment variables
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.
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, 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
kimiinstances sharing the sameKIMI_CODE_HOMEwill 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=1KIMI_MODEL_* family
Switch models temporarily without modifying config.toml: when KIMI_MODEL_NAME is set, the CLI synthesizes a temporary provider in memory, and the change does not persist after restart. See Define a model from environment variables.
KIMI_CODE_CUSTOM_HEADERS
Added
Added in 0.20.2.
Attaches custom HTTP headers to every outbound model request: both LLM chat requests (across all provider protocols) and /models listing requests carry them. 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.
Precedence: the Kimi identity headers (
User-Agent,X-Msh-*) and a provider'scustom_headersinconfig.toml(see Config files) override same-named entries here. Authentication is protocol-dependent: on thekimi,openai, andopenai_responsesprotocols an exactAuthorizationentry replaces the generated bearer token, while/modelslisting requests keep their own authentication. A case variant such asauthorizationis never treated as the same name. It merges with the real header, which can break requests. Do not use this variable for authentication or other reserved headers. Usecustom_headerswhen 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; 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"
kimiComplete 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 | Parallel auth credential for kimi web, recommended when binding beyond loopback (see Security notes) | Any non-empty string; when unset, only the token is valid |
KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT | Keep background tasks when the session closes; higher priority than config.toml (default: 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; higher priority than [background] max_running_tasks (unset = no cap) | Positive integer; invalid values are ignored |
KIMI_IMAGE_MAX_EDGE_PX | Longest-edge ceiling (px) for image compression; higher priority than [image] max_edge_px (default 2000) | Positive integer; invalid values are ignored |
KIMI_IMAGE_READ_BYTE_BUDGET | Per-image byte budget for model-initiated image reads; higher priority than [image] read_byte_budget (default 262144) | Positive integer; invalid values are ignored |
KIMI_CODE_PLUGIN_MARKETPLACE_URL | Override the marketplace JSON loaded by /plugins; default https://code.kimi.com/kimi-code/plugins/marketplace.json | Also accepts http://, file:// URLs, and local paths |
KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY | Cap on AgentSwarm subagents running concurrently during the initial ramp; unset = no cap | Positive integer; invalid values fail fast |
KIMI_SUBAGENT_TIMEOUT_MS | Max wall-clock time (ms) a single Agent subagent may run; higher priority than [subagent] timeout_ms | Positive integer; invalid values fall back to the config or default |
KIMI_CODE_SWARM_TIMEOUT_MS | Max wall-clock time (ms) an AgentSwarm subagent may run; higher priority than [swarm] timeout_ms | Positive integer; invalid values fall back to the config or default |
KIMI_CODE_IDENTITY_NAME | Name the agent calls itself in the system prompt; higher priority than [identity] name, never written back | Any non-empty string; blank values read as unset |
KIMI_CODE_IDENTITY_SLUG | User-Agent product token and MCP client name; 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 | Offer the built-in skills documenting Kimi Code itself to the model; higher priority than builtin_product_skills | Truthy: 1/true/yes/on; falsy: 0/false/no/off |
KIMI_CODE_TUI_FULL_SCREEN | Experimental fullscreen UI: scrollable transcript, mouse selection, clickable links, Ctrl-Shift-F search | 1 enables it; anything else keeps the regular inline UI |
KIMI_CODE_EXPERIMENTAL_SECONDARY_MODEL | The subagent model pool is enabled by default in all launch modes; set a falsy value to disable it; KIMI_CODE_EXPERIMENTAL_FLAG=1 also enables it | Truthy: 1/true/yes/on; falsy: 0/false/no/off |
KIMI_CODE_EXPERIMENTAL_SUBAGENT_FORK | Experimental fork parameter on Agent/AgentSwarm: start the subagent from a snapshot of the caller's history instead of an empty context; 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 MCP servers; overrides the config file, but mcp.json startupTimeoutMs still wins | Integer from 1 to 2147483647; invalid values are ignored |
KIMI_MCP_TOOL_TIMEOUT_MS | Global default single tool-call timeout (ms) for MCP servers; overrides the config file, but mcp.json toolTimeoutMs still wins | Integer from 1 to 2147483647; invalid values are ignored |
KIMI_LOOP_MAX_STEPS_PER_TURN | Max Agent steps per turn; higher priority than [loop_control] max_steps_per_turn (0 = unlimited) | Non-negative integer; invalid values are ignored |
KIMI_LOOP_MAX_ATTEMPTS_PER_STEP | Max total attempts for a failing step (including the first); higher priority than [loop_control] max_attempts_per_step | Non-negative integer; invalid values are ignored |
KIMI_CODE_INFINITE_RETRY | Retry failed LLM requests indefinitely; exponential backoff (32 s cap) honoring Retry-After; aborting still cancels immediately | Truthy: 1/true/yes/on; falsy: 0/false/no/off |
KIMI_TOKEN_COUNTING_STRATEGY | Context token count reported externally; higher priority than [token_counting] strategy | measured+estimated, measured, estimated (case-insensitive); invalid values are ignored |
KIMI_WEB_SEARCH_BASE_URL | Web search (WebSearch) service API URL; higher priority than the config file; credentials and custom headers not forwarded | Non-blank string; blank values are ignored |
KIMI_WEB_SEARCH_API_KEY | Web search (WebSearch) service API key; replaces both the configured key and the OAuth credential | Non-blank string; blank values are ignored |
KIMI_WEB_FETCH_BASE_URL | Web fetch (FetchURL) service API URL; higher priority than the config file; credentials not forwarded. Without an endpoint, signed-in users get the managed Kimi OAuth fetch service before direct local requests | Non-blank string; blank values are ignored |
KIMI_WEB_FETCH_API_KEY | Web fetch (FetchURL) service API key; replaces both the configured key and the OAuth credential | Non-blank string; blank values are ignored |
KIMI_CODE_EXPERIMENTAL_FLAG | Enable all registered experimental features for this process; does not select the agent engine | 1, true, yes, on |
KIMI_CODE_LEGACY_FLAG | Legacy agent-core engine for kimi, kimi -p, kimi doctor, kimi export, and kimi provider (default: agent-core-v2) | 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; 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; kimi provider only (global) | Number, e.g. 0.95 |
KIMI_MODEL_THINKING_EFFORT | Force a thinking effort (thinking.effort), bypassing the model's declared support_efforts; kimi provider only | An effort value, e.g. max |
KIMI_MODEL_THINKING_KEEP | Preserved-thinking passthrough: thinking.keep on kimi, a clear_thinking_20251015 edit on anthropic; overrides [thinking] keep | 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 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 KIMI_CODE_INFINITE_RETRY, KIMI_CODE_IDENTITY_*, and 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 pathVISUAL,EDITOR: external editor command (VISUALtakes precedence)PATH: used to locate dependencies such asrg,fd,fdfind, andgit; on Windows, Git Bash detection checks eachgit.exefound onPATH, including package-manager shims such as ScoopNO_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 themeTERM_PROGRAM,TERM,TMUX: detect terminal features and notification supportDISPLAY,WAYLAND_DISPLAY,XDG_SESSION_TYPE: detect Linux graphical sessions (for clipboard and image features)WSL_DISTRO_NAME,WSLENV: detect WSL for the clipboard PowerShell bridgeLOCALAPPDATA: 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 forhttp://requestsHTTPS_PROXY/https_proxy: proxy forhttps://requestsALL_PROXY/all_proxy: fallback proxy used when the scheme-specific variable is unset; this is where a SOCKS proxy is usually setNO_PROXY/no_proxy: comma-separated hosts that bypass the proxy
Proxy types and precedence
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://). It 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.
Activation conditions and loopback addresses
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.
MCP child processes
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