环境变量

开篇导读

环境变量是Kimi Code CLI的辅助配置方式，用于控制少数特殊运行时行为，无需修改配置文件即可临时调整运行参数，适合自动化脚本、测试、临时调整等场景。与配置文件不同，环境变量仅对当前shell会话生效，重启后失效，不会永久修改配置。

掌握本页面内容后，你将能够：

1. 通过环境变量自定义数据目录、临时切换模型
2. 配置代理、调整日志级别、控制功能开关
3. 适配特殊运行环境（如WSL、CI环境）
4. 理解环境变量与配置文件的优先级关系，避免配置冲突

设计说明

API密钥不读取shell环境变量是出于安全考虑：shell环境变量可能被其他进程读取、被命令历史记录泄露，集中存储在配置文件中便于统一管控权限，降低密钥泄露风险。

核心路径

KIMI_CODE_HOME

操作目的

覆盖默认数据根目录，实现多环境隔离、数据目录迁移等需求。

覆盖数据根目录，默认 ~/.kimi-code。设置后，配置文件、会话、日志、OAuth 凭据等全部数据都落到新路径下：

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

确保目录可写。多个 kimi 实例共用同一个 KIMI_CODE_HOME 会共享配置和凭证。

数据目录的完整结构见数据路径。

场景示例

• 多环境隔离：工作与个人场景分别设置KIMI_CODE_HOME为~/.kimi-work与~/.kimi-personal，实现配置、会话、密钥完全隔离。
• 自动化脚本：在CI/CD脚本中设置临时数据目录，脚本执行完成后删除即可，不会污染全局环境。
• 数据迁移：将数据目录迁移到非系统盘，避免系统盘空间不足或重装系统导致数据丢失。

KIMI_DISABLE_TELEMETRY

操作目的

临时关闭匿名遥测上报，无需修改配置文件。

设为 1 关闭匿名遥测上报（也接受 true/yes/y，不区分大小写）：

export KIMI_DISABLE_TELEMETRY=1

补充说明

关闭遥测后不会上报任何匿名数据（包括使用频率、错误类型等），不会影响正常功能使用，仅用于帮助开发者优化产品体验。

KIMI_MODEL_* 系列

操作目的

无需修改配置文件即可临时切换模型，适合测试新模型、临时使用第三方服务等场景，重启后失效。

不修改 config.toml 临时切换模型——设置 KIMI_MODEL_NAME 后，CLI 在内存里合成一个临时供应商，重启后失效。详见用环境变量定义模型。

供应商凭证键（写在 config.toml 里）

说明

以下键名不是从shell环境变量读取，而是作为[providers.<name>.env]子表的配置键名，仅在配置文件中生效，方便用户沿用熟悉的密钥命名习惯。

下面这些键名不是直接从 shell 读取的——它们是写在 config.toml 的 [providers.<name>.env] 子表里、作为 api_key / base_url 备用来源的键名。CLI 只从配置文件读取，不从 process.env 读取。

这样设计是为了让你保留熟悉的键名写法，同时把密钥放在配置文件里统一管理：

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

各供应商对应的键名：

供应商类型与字段的完整说明见平台与模型。

注意事项

• 键名严格区分大小写，必须与表格中的名称完全一致，否则会导致凭证读取失败。
• GOOGLE_APPLICATION_CREDENTIALS需在shell环境中设置，或配置到系统环境变量中，供Google SDK读取。

OAuth 与托管端点

说明

这组变量用于将OAuth认证与托管服务指向自建或测试环境，普通用户日常使用无需设置，仅适用于二次开发或私有部署场景。

这组变量用于将 OAuth 认证和托管服务端点指向自建或测试环境，日常使用不需要设置。

注意事项

• 混淆两个base_url变量会导致登录失败或API调用错误，OAuth托管登录场景使用KIMI_CODE_BASE_URL，API密钥直连Kimi平台使用KIMI_BASE_URL。

用环境变量定义模型（KIMI_MODEL_*）

操作目的

无需修改配置文件即可临时接入新模型，适合测试、临时使用第三方服务、自动化脚本等场景，重启后失效，不会修改永久配置。

测试时想换个模型但不想动 config.toml？设置 KIMI_MODEL_NAME 后，CLI 会从 KIMI_MODEL_* 系列变量在内存里合成出一个临时供应商和模型别名，不写回配置文件。优先级高于 config.toml 的 default_model，但低于启动时 -m <alias> 选项。

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

使用示例（临时接入DeepSeek模型）

# 临时配置DeepSeek V3模型，无需修改config.toml
export KIMI_MODEL_NAME="deepseek-chat"
export KIMI_MODEL_API_KEY="sk-xxxxxx"
export KIMI_MODEL_BASE_URL="https://api.deepseek.com"
export KIMI_MODEL_PROVIDER_TYPE="openai"
export KIMI_MODEL_MAX_CONTEXT_SIZE="131072"
kimi

启动后即可直接使用DeepSeek模型，退出当前shell后配置自动失效，不影响原有配置。

完整变量列表：

设置了 KIMI_MODEL_NAME 但缺少必填变量时，启动会立即失败并给出明确提示。

补充说明

• 临时模型优先级：启动参数-m > KIMI_MODEL_*环境变量 > 配置文件default_model。
• KIMI_MODEL_CAPABILITIES使用逗号分隔多个能力标签，无需空格，例如image_in,thinking,tool_use。
• 若第三方OpenAI兼容服务使用非标准推理字段名，可通过KIMI_MODEL_REASONING_KEY指定，例如reasoning。

运行时开关

说明

控制各子系统的运行行为，无需修改配置文件即可临时调整，适合特定场景下的临时需求。

控制遥测、后台任务、plugin marketplace 等子系统行为的开关变量：

场景示例

• 服务器长任务场景：执行export KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT=1后启动CLI，退出后后台任务继续运行，不会被终止。
• 编码场景调优：执行export KIMI_MODEL_TEMPERATURE=0.2降低输出随机性，提升代码生成的一致性与准确性。
• CI环境使用：执行export KIMI_CODE_NO_AUTO_UPDATE=1禁用自动更新，避免CI过程中因更新导致流程中断。
• Windows环境适配：若CLI自动探测Git Bash失败，执行export KIMI_SHELL_PATH="C:\Program Files\Git\bin\bash.exe"指定路径。

诊断日志

说明

控制日志输出级别与滚动策略，便于问题排查与调试，进程启动时读取一次，修改后需重启生效。

这组变量控制日志级别和文件滚动，进程启动时读取一次：

补充说明

• 遇到问题需要排查时，执行export KIMI_LOG_LEVEL=debug后启动CLI，可获取详细的调试日志，便于定位问题。
• 日志文件默认自动滚动，超过最大大小后会自动生成新文件，保留指定份数的历史日志，不会无限占用磁盘空间。
• 若需要保留更多历史日志，可适当调大KIMI_LOG_GLOBAL_FILES与KIMI_LOG_SESSION_FILES的值。

系统环境变量

说明

CLI会读取标准系统环境变量检测运行环境，自动适配不同系统与终端特性，不会修改这些变量。

CLI 还会读取一些标准系统变量来检测运行环境，不会修改它们：

• HOME：解析默认数据路径
• VISUAL、EDITOR：外部编辑器命令（VISUAL 优先）
• PATH：定位 rg、fd、fdfind、git 等依赖；在 Windows 上，Git Bash 探测会检查 PATH 中找到的每个 git.exe，包括 Scoop 等包管理器提供的 shim
• NO_COLOR、FORCE_COLOR：控制颜色输出（遵循 no-color.org 约定）
• CI：非空且非 "0" 时关闭主题检测，回退深色主题
• TERM_PROGRAM、TERM、TMUX：检测终端特性和通知支持
• DISPLAY、WAYLAND_DISPLAY、XDG_SESSION_TYPE：检测 Linux 图形会话（用于剪贴板和图片功能）
• WSL_DISTRO_NAME、WSLENV：检测 WSL，用于剪贴板 PowerShell 桥接
• LOCALAPPDATA：Windows 上探测 Git Bash 安装路径时作为 fallback 使用

适配说明

• 若需指定外部编辑器，可设置VISUAL或EDITOR环境变量，例如export VISUAL=code默认使用VS Code作为编辑器。
• 非交互式脚本场景可设置NO_COLOR=1关闭颜色输出，避免日志中出现颜色控制字符。
• CI环境中CI变量会自动被识别，CLI会禁用交互特性，适配非交互式运行。
• WSL环境下会自动适配剪贴板功能，支持与Windows系统剪贴板互通。

HTTP 代理

操作目的

配置网络代理，解决国内用户访问国外API速度慢、网络不通的问题，支持HTTP/HTTPS/SOCKS代理。

Kimi Code 会遵循标准代理环境变量，让所有出网流量——模型 API 调用、MCP 服务、网络工具、遥测、登录、更新检查——都走代理：

• HTTP_PROXY / http_proxy：用于 http:// 请求的代理
• HTTPS_PROXY / https_proxy：用于 https:// 请求的代理
• ALL_PROXY / all_proxy：当对应 scheme 的变量未设置时使用的兜底代理；SOCKS 代理通常设在这里
• NO_PROXY / no_proxy：以逗号分隔的、绕过代理的主机列表

同时支持 HTTP(S) 代理和 SOCKS 代理。SOCKS 代理通过 scheme 识别——socks5://、socks5h://、socks4:// 或 socks://（socks5:// 的别名）——通常设在 ALL_PROXY（Clash、V2RayN 等工具使用的形式）。对 HTTP/HTTPS 流量，HTTP(S) 代理优先于 ALL_PROXY。

仅当设置了其中任一变量时才启用代理，否则直连。回环地址（localhost、127.0.0.1、::1）始终绕过代理，因此配置了代理后，本地服务（例如 localhost 上的 MCP 服务）仍能正常工作——你也可以把自己的内网主机加入 NO_PROXY 一并放行。

以 Node 子进程运行的 stdio MCP 服务，在其 Node 版本支持 NODE_USE_ENV_PROXY 时（Node ≥ 22.21 或 ≥ 24.5）会自动遵循 HTTP_PROXY / HTTPS_PROXY / NO_PROXY；SOCKS 代理仅作用于 Kimi Code 自身的流量。

配置示例

# HTTP代理配置
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890

# SOCKS5代理配置（Clash/V2RayN等工具常用）
export ALL_PROXY=socks5://127.0.0.1:7890

# 配置绕过代理的内网地址
export NO_PROXY=localhost,127.0.0.1,192.168.1.0/24,internal.example.com

注意事项

• 回环地址默认绕过代理，本地运行的MCP服务、本地部署的模型无需额外配置NO_PROXY即可正常访问。
• 若内网服务无法访问，可将内网IP段或域名加入NO_PROXY列表，避免走代理导致访问失败。
• Node版本低于22.21或24.5的stdio MCP服务不会自动遵循代理配置，需手动在MCP服务中配置代理。
• 国内用户访问OpenAI、Anthropic等国外API时，配置代理可大幅提升访问速度，减少超时错误。