配置覆盖

开篇导读

Kimi Code CLI提供三种配置方式：配置文件、命令行选项、环境变量，三者面向不同使用场景，作用范围与优先级各不相同，并非简单的线性覆盖关系。了解配置覆盖规则可帮助你避免配置冲突，明确不同场景下的最优配置方式。

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

1. 理解三种配置方式的优先级与适用场景
2. 掌握供应商凭证的解析规则，避免配置不生效问题
3. 灵活使用命令行选项实现临时配置调整
4. 针对典型场景选择最合适的配置方案

Kimi Code CLI 有三个地方可以影响运行参数：配置文件、命令行选项、环境变量。它们不是简单的"谁优先级高谁赢"——三者面向不同场景，作用范围互不相同：

• 配置文件 保存长期偏好（模型、密钥、循环控制等），每次启动都生效
• 命令行选项 做本次启动的临时切换，退出后失效
• 环境变量 主要负责数据目录定位、OAuth 端点切换，以及少数运行时开关——不是配置字段的通用后备来源

这个区别很关键：很多人会在 shell 里 export KIMI_API_KEY=xxx，以为 CLI 会自动取到，但实际上不会。原因见下文供应商凭证。

设计说明

不将shell环境变量作为通用配置后备，是出于安全与可维护性考虑：集中式配置文件便于权限管控与备份，避免分散在不同shell配置文件中的参数导致配置混乱、密钥泄露。

环境变量的三类作用

环境变量按作用分三类，不能合并成一条线性优先级：

1. 定位配置文件：KIMI_CODE_HOME 决定数据根目录，配置文件路径因此变为 $KIMI_CODE_HOME/config.toml。这一步先于其他所有解析，不是普通参数的后备来源。
2. 运行时开关：KIMI_DISABLE_TELEMETRY 等少量变量直接关闭对应子系统——即使 config.toml 里 telemetry = true，只要这个变量是真值，遥测就会被禁用。语义是"额外禁用"，不是"普通覆盖"。
3. 运行端点与诊断：KIMI_CODE_OAUTH_HOST、KIMI_CODE_BASE_URL、KIMI_LOG_LEVEL 等在 OAuth 或日志子系统初始化时读取。完整列表见环境变量。

补充说明

• KIMI_CODE_HOME是最先解析的环境变量，决定了后续所有配置文件的读取路径，若需自定义数据目录必须在启动CLI前设置。
• 运行时开关类环境变量的优先级高于配置文件，属于强制控制项，用于临时禁用或启用特定功能。
• 运行端点与诊断类环境变量仅在子系统初始化时读取，修改后需重启CLI生效，不支持热重载。

普通运行参数的优先级

对模型别名、Plan 模式、yolo 模式、Skills 目录等普通运行参数，优先级从高到低：

1. 命令行选项（-m、--plan、--yolo 等）：仅对本次启动生效
2. 用户配置文件（~/.kimi-code/config.toml）：保存长期偏好

少数环境变量明确覆盖特定配置字段，例如 KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT 的优先级高于 [background].keep_alive_on_exit。这类例外在环境变量和配置文件对应字段里都有标注。

目前 CLI 只读取一份用户级配置文件，没有项目级配置文件机制。需要在不同项目间隔离配置时，用 KIMI_CODE_HOME 指向不同的数据目录——见下文典型场景。

最佳实践

• 长期固定的配置（如常用模型、API密钥、权限规则）写入配置文件，永久生效。
• 单次启动需要调整的参数（如临时切换模型、开启Plan模式）使用命令行选项，无需修改配置文件。
• 多项目配置隔离使用KIMI_CODE_HOME，为每个项目设置独立的数据目录，避免配置互相干扰。
• 可在项目根目录下创建.kimi-code目录并加入.gitignore，通过export KIMI_CODE_HOME="$PWD/.kimi-code"实现项目级配置隔离。

供应商凭证

供应商凭证（api_key、base_url）有独立的解析规则，不走普通参数的优先级链。

对单个供应商，凭证按以下顺序解析：

1. [providers.<name>].api_key — 配置文件里直接写的密钥，优先级最高
2. [providers.<name>.env] 子表里的对应键（KIMI_API_KEY、ANTHROPIC_API_KEY 等）— api_key 为空时才读这里
3. 两者都缺 → 启动报错，提示该供应商缺少凭证

base_url 的解析方式相同：先读 [providers.<name>].base_url，再读 [providers.<name>.env] 里的 *_BASE_URL 键。

[providers.<name>.env] 子表只是配置文件里的一段 TOML，不会真正写入 shell 环境变量。仅当对应的直接字段（api_key / base_url）为空时，CLI 才会查这里。

完整的凭证键名列表见环境变量：供应商凭证键。

示例说明

# 示例1：直接填写api_key，优先级最高
[providers.kimi]
type = "kimi"
api_key = "sk-123" # 会使用这个密钥
[providers.kimi.env]
KIMI_API_KEY = "sk-456" # 不会生效

# 示例2：api_key为空，读取env子表
[providers.kimi]
type = "kimi"
api_key = "" # 为空，读取env子表
[providers.kimi.env]
KIMI_API_KEY = "sk-456" # 会使用这个密钥

常见问题排查

• 若启动时提示「供应商缺少凭证」，优先检查api_key是否填写正确，env子表的键名是否大小写完全匹配。
• 不要在shell中export供应商密钥变量，这类变量不会被CLI读取，必须写入配置文件。

命令行选项

启动时传入的选项优先级最高，只对本次启动生效：

互斥规则（违反时启动报错）：

• --output-format 只能配合 -p 使用
• --prompt 不能同时用 --yolo 或 --plan
• --continue 和 --session 不能同时用
• 非 prompt 模式下，--yolo 和 --plan 不能配合 --continue 或 --session

选项详细说明

• -S, --session [id]：适合恢复历史会话，不带ID时会显示所有会话列表，可交互式选择要恢复的会话。
• -C, --continue：快速恢复当前工作目录的最近会话，无需手动选择，适合继续上一次未完成的工作。
• -y, --yolo：适合自动化批处理场景，确认任务安全时使用，避免手动确认的繁琐，使用前需验证任务逻辑安全性。
• --plan：适合复杂多步骤任务，Agent会先输出执行计划，用户确认后再执行，避免不符合预期的操作。
• -m, --model <model>：临时切换模型，优先级高于配置文件与环境变量，适合快速对比不同模型的效果。
• -p, --prompt <prompt>：非交互模式，适合脚本自动化，可直接将输出结果写入文件或通过管道传递给其他命令。
• --skills-dir <dir>：适合测试新开发的Skill，无需修改全局配置，测试完成后删除即可。

典型场景

隔离测试环境

需求：测试新模型、新插件或新配置，不影响主环境的配置与会话。 方案：使用独立的临时数据目录，测试完成后直接删除即可。

KIMI_CODE_HOME="$PWD/.kimi-sandbox" kimi

所有测试数据都会存放在当前目录的.kimi-sandbox目录下，不会污染主环境，测试完成后删除该目录即可完全清理。

一次性使用测试密钥

需求：临时使用测试API密钥，不想写入主配置文件。 方案1：在配置文件的env子表中填写测试密钥，使用完成后删除。

[providers.kimi.env]
KIMI_API_KEY = "sk-test" # 测试完成后删除该行即可

方案2：使用KIMI_MODEL_*环境变量临时配置模型，无需修改配置文件。

跳过审批运行批处理任务

需求：批量执行安全的重复任务，无需手动确认每次工具调用。 方案：使用--yolo与--prompt参数非交互执行。

kimi --yolo -p "批量重命名当前目录下所有jpg文件，格式为photo_001.jpg递增"

CLI会自动执行所有工具调用，无需用户确认，适合已经验证过安全性的批处理任务。

临时进入Plan模式

需求：本次会话需要执行复杂任务，临时开启Plan模式，不修改永久配置。 方案：使用--plan参数启动。

kimi --plan

本次会话默认使用Plan模式，下次启动恢复配置文件的默认设置，无需手动修改配置。