配置文件

​

🔔

Kimi Code CLI 把所有长期偏好写进 ~/.kimi-code/ 下的 TOML（一种结构清晰的纯文本配置格式）文件——比如使用哪个模型、Agent 每轮最多跑几步。改一次，每次启动都生效。Agent 与运行时设置放在 config.toml，终端界面与客户端偏好（主题、编辑器、通知、自动更新）放在配套的 tui.toml。​

​

默认位置：~/.kimi-code/config.toml，首次运行时自动创建。​

配置文件位置​

CLI 从 ~/.kimi-code/config.toml 读取配置。如需把数据目录迁移到别处，可用 KIMI_CODE_HOME 环境变量覆盖：​

​

代码块​

Plain Text

export KIMI_CODE_HOME=/path/to/kimi-home​

​

此时配置文件路径变为 $KIMI_CODE_HOME/config.toml。无论目录在哪里，文件名固定是 config.toml。​

TIP​

TOML 字段名一律用下划线（snake_case），如 default_model、max_context_size。字段名里若含 .，需用引号包住，例如 [models."gpt-4.1"]——否则 TOML 会把 . 解释为嵌套表分隔符。​

完整示例​

以下示例覆盖最常用的配置项，可直接复制后按需修改：​

​

代码块​

Bash

default_model = "kimi-code/k3"​

default_permission_mode = "manual"​

default_plan_mode = false​

merge_all_available_skills = true​

telemetry = true​

​

[providers."managed:kimi-code"]​

type = "kimi"​

base_url = "https://api.kimi.com/coding/v1"​

api_key = ""​

​

[models."kimi-code/k3"]​

provider = "managed:kimi-code"​

model = "k3"​

max_context_size = 1048576​

capabilities = [ "thinking", "always_thinking", "image_in", "video_in", "tool_use" ]​

display_name = "K3"​

support_efforts = [ "max" ]​

default_effort = "max"​

​

[models."kimi-code/kimi-for-coding"]​

provider = "managed:kimi-code"​

model = "kimi-for-coding"​

max_context_size = 262144​

capabilities = [ "thinking", "always_thinking", "image_in", "video_in", "tool_use" ]​

​

顶层字段​

配置文件里的字段分两类：顶层标量直接控制默认行为，嵌套表（providers、models、thinking 等）各有独立结构，在下文各节单独说明。​

​

​

以下各节对 providers、models、thinking、loop_control、background、image、services、permission 等嵌套表逐一展开。​

providers​

providers 表的每一项定义一个 API 供应商，以唯一名称为 key。CLI 只从这里读取凭证，不会从 shell 环境变量自动取后备值——在终端里 export KIMI_API_KEY 不会让供应商自动获得密钥，必须显式写在配置文件里（详见配置覆盖）。​

​

​

env 子表：可以把供应商惯用的键名（如 KIMI_API_KEY）写在 [providers..env] 里，作为 api_key / base_url 的备用来源。这个子表只在配置文件里读取，不会修改 shell 环境：​

​

代码块​

Plain Text

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

​

优先级：api_key 字段 > env 子表键 > 两者都缺时启动报错。​

models​

models 表的每一项定义一个模型别名（即 default_model 或 -m 参数里使用的名称），以唯一名称为 key。​

​

​

别名中含 . 时需要加引号：​

​

代码块​

Plain Text

[models."gpt-4.1"]provider = "openai"model = "gpt-4.1"max_context_size = 1047576​

​

模型覆盖项​

如果某些用户覆盖需要在 provider-model 刷新后保留，请写到 [models."".overrides]。运行时读取的是 effective 值：有 override 时用 override，否则用顶层字段。​

​

代码块​

Plain Text

[models."kimi-code/kimi-for-coding"]provider = "managed:kimi-code"model = "kimi-for-coding"max_context_size = 262144[models."kimi-code/kimi-for-coding".overrides]max_context_size = 131072display_name = "Kimi for Coding (custom)"​

​

[models."".overrides] 接受普通模型字段，例如 max_context_size、max_output_size、capabilities、display_name、reasoning_key、adaptive_thinking、support_efforts 和 default_effort。不接受身份 / 路由字段：provider、model、protocol 和 beta_api。​

无需修改配置文件也可以临时切换模型——通过 KIMI_MODEL_* 环境变量在内存里合成一个临时供应商，详见用环境变量定义模型。​

thinking​

thinking 设置 Thinking 模式的全局默认行为。​

​

​

已废弃字段​

​

​

loop_control​

loop_control 控制 Agent 执行循环的步数上限、单步重试次数，以及触发上下文自动压缩的阈值。​

​

​

background​

background 控制后台任务（通过 Bash 工具或 Agent 工具的 run_in_background=true 参数启动）的并发数。​

​

​

keep_alive_on_exit 可被环境变量 KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT 覆盖，优先级高于配置文件。​

在 print 模式（kimi -p ""）下，只要还有未决的后台任务，Kimi Code 在主 agent 的 turn 结束后不会退出：每个任务完成都会以合成 user 消息回馈给主 agent，steer 出新的 turn（默认 print_background_mode = "steer"），直到某 turn 结束时没有任何未决任务才退出。该循环受 print_wait_ceiling_s 与 print_max_turns 约束，默认值都近似不设限。print 模式下后台工作也不会被墙钟超时杀掉：后台 Bash 任务默认无超时（bash_task_timeout_s = 0），子代理默认无超时（[subagent] timeout_ms = 0），只有模型自己能停止任务。将 print_background_mode 设为 "drain" 可等待任务结束但不回馈结果，设为 "exit" 则在主 agent 结束后立即退出。​

subagent​

​

​

timeout_ms 可被环境变量 KIMI_SUBAGENT_TIMEOUT_MS 覆盖，优先级高于配置文件。​

image​

image 控制图片发送给模型前的压缩行为，对所有图片入口生效（粘贴图片、ReadMediaFile 读图、MCP 工具结果里的图片等）。​

​

​

max_edge_px 可被环境变量 KIMI_IMAGE_MAX_EDGE_PX 覆盖，read_byte_budget 可被 KIMI_IMAGE_READ_BYTE_BUDGET 覆盖，优先级均高于配置文件。​

services​

services 配置网页搜索（moonshot_search）和网页抓取（moonshot_fetch）两项内置服务。只识别这两个固定 key，其他 key 会被忽略。两项字段相同：​

​

​

​

代码块​

Plain Text

​

permission​

permission 设置会话启动时自动加载的权限规则，控制 Agent 调用工具时是否需要用户确认。规则用 [[permission.rules]] 数组表写出，按顺序匹配，第一条命中即生效。​

​

​

内置工具名见内置工具。大多数支持规则参数的内置工具会定义自己的匹配对象，例如 Bash(command-pattern) 或 Read(path-pattern)。AgentSwarm、MCP 工具和自定义工具只能按工具名匹配，不支持参数模式。​

​

代码块​

Plain Text

[[permission.rules]]decision = "allow"pattern = "Read"[[permission.rules]]decision = "allow"pattern = "Grep"[[permission.rules]]decision = "deny"pattern = "Bash(rm -rf*)"[[permission.rules]]decision = "ask"pattern = "Bash"​

​

TIP​

MCP server 的声明配置写在 ~/.kimi-code/mcp.json 或项目内 .kimi-code/mcp.json 中，不在 config.toml 里。交互式配置入口是 /mcp-config，详见 Model Context Protocol。​

tui.toml​

除了 config.toml，CLI 还在同一目录下用一份配套的 tui.toml 保存终端界面与客户端偏好（~/.kimi-code/tui.toml，或覆盖后的 $KIMI_CODE_HOME/tui.toml）。它在首次运行时以默认值创建，交互式命令 /config、/theme、/editor 会自动写入，通常无需手动编辑。文件格式有误时，CLI 会回退到默认值并给出提示，而不是启动失败。​

​

​

​

代码块​

Plain Text

# ~/.kimi-code/tui.tomltheme = "auto" # "auto" | "dark" | "light" | 自定义主题名disable_paste_burst = false # true 表示禁用非 bracketed paste 的粘贴突发兜底[editor]command = "" # 留空则使用 $VISUAL / $EDITOR[notifications]enabled = truenotification_condition = "unfocused" # "unfocused" | "always"[upgrade]auto_install = true​

​

修改在下次启动时生效，或用 /reload-tui 立即生效（只重载 tui.toml）；/reload 会同时重载 config.toml 和 tui.toml。​

项目级本地配置​

除了 ~/.kimi-code 下的用户级文件，Kimi Code 还会读取位于 <项目根目录>/.kimi-code/local.toml 的项目级本地配置文件。它保存的是与某一个项目检出相关、通常不应与队友共享的设置。​

该文件会在你通过 /add-dir 添加额外工作目录并选择记入项目时自动创建，通常无需手动编辑。​

[workspace]​

[workspace] 表用于存放项目级的工作区设置：​

​

​

​

代码块​

Plain Text

[workspace]additional_dir = ["/absolute/path/to/shared"]​

​

目录以绝对路径存储，与具体机器相关。因此建议把 .kimi-code/local.toml 加入项目的 .gitignore，避免被提交。​