配置文件

开篇导读

Kimi Code CLI 是面向开发者的原生AI编码助手命令行工具，具备本地优先、高度可定制、多模型兼容、强Agent执行能力等核心优势，适用于全栈开发、运维自动化、AI应用构建、项目重构等多种场景。配置文件是整个工具的核心控制中枢，所有长期使用偏好、模型接入规则、Agent行为逻辑、安全权限策略都通过配置文件定义，一次配置永久生效，无需每次启动重复设置。

掌握本配置文档后，你将能够：

1. 完全自定义符合个人工作流的AI助手行为
2. 灵活接入多家主流LLM平台与自定义部署模型
3. 配置安全的工具调用权限规则，规避危险操作
4. 调整Agent执行逻辑与上下文管理策略，平衡性能与成本
5. 定制终端界面交互体验，提升使用效率

本文所有配置参数、路径、默认值均为官方指定标准，请勿随意修改核心字段名称，避免配置加载失败。

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

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

配置文件位置

操作目的

明确配置文件的默认存放路径，以及自定义数据目录的方法，支持多环境配置隔离（如工作/个人环境分离、测试/生产环境隔离），避免不同场景的配置互相干扰。

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

export KIMI_CODE_HOME=/path/to/kimi-home

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

预期结果

设置 KIMI_CODE_HOME 后启动CLI，程序将自动在指定路径下创建所需的子目录与配置文件，不再读写默认 ~/.kimi-code/ 路径下的内容，实现完全的环境隔离。

注意事项

• KIMI_CODE_HOME 路径建议避免使用空格、中文或特殊字符，否则可能导致TOML解析异常或路径识别错误
• Windows系统下路径需使用正斜杠（/）或双反斜杠（\\），如 export KIMI_CODE_HOME=C:/Users/xxx/kimi-work
• 若指定路径不存在，CLI首次启动时会自动创建完整目录结构，无需手动提前创建

补充说明

TOML语法中蛇形命名是配置文件的通用约定，可避免大小写敏感带来的识别问题。带.的模型别名（如版本号后缀）若未加引号，会被TOML解析为嵌套表结构，例如[models.gpt-4.1]会被误解析为models表下的gpt-4子表中的1字段，导致配置加载失败，启动时会抛出「模型别名解析错误」提示，遇到此类报错可优先检查带特殊字符的别名是否正确添加引号。

完整示例

操作目的

提供开箱即用的配置模板，覆盖绝大多数用户的常用配置场景，减少手动编写配置的成本，避免遗漏必填项。新手可直接复制模板后仅修改API密钥等核心字段，即可快速完成基础配置。

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

default_model = "kimi-code/kimi-for-coding"
default_thinking = true
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/kimi-for-coding"]
provider = "managed:kimi-code"
model = "kimi-for-coding"
max_context_size = 262144

[thinking]
mode = "auto"

[loop_control]
max_retries_per_step = 3
reserved_context_size = 50000

[background]
max_running_tasks = 4
keep_alive_on_exit = false

[experimental]
micro_compaction = true

[[permission.rules]]
decision = "allow"
pattern = "Read"

[[permission.rules]]
decision = "deny"
pattern = "Bash(rm -rf*)"

[[hooks]]
event = "PreToolUse"
matcher = "Bash"
command = "node ~/.kimi-code/hooks/check-bash.mjs"
timeout = 5

预期结果

将上述模板复制到config.toml并填写正确的API密钥后，启动CLI不会报配置错误，默认使用Kimi for Coding模型，自动允许所有读操作、禁止rm -rf开头的危险命令，符合大多数用户的安全使用需求。

最佳实践

• 新手首次配置时建议仅修改api_key等必填字段，其余参数保持默认，待熟悉各配置项含义后再逐步调整
• 敏感配置（如API密钥）建议单独存储，避免将包含密钥的配置文件提交到公共代码仓库
• 可将常用配置模板备份到云存储或私有Git仓库，换机或重装系统时可快速恢复配置

顶层字段

操作目的

顶层字段直接控制CLI的全局默认行为，无需进入嵌套表即可调整核心运行逻辑，所有字段均为可选，未显式设置时将使用官方默认值。

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

字段详细解释

• default_model：必须与下方models表中定义的别名完全一致，不可直接填写模型API ID，否则启动时会抛出「默认模型不存在」错误。
• default_thinking：开启后新会话默认使用深度推理模式，适合复杂编码、Debug、架构设计等需要高准确率的场景，推理精度更高但响应速度稍慢；简单问答、代码补全场景可设为false提升响应效率。
• default_permission_mode：
  • manual：最安全模式，所有工具调用均需用户手动确认，推荐新手使用
  • auto：自动批准读文件、查目录等无修改风险的操作，平衡安全与效率，推荐有一定使用经验的用户选择
  • yolo：自动批准所有工具调用，仅适合完全信任CLI的自动化批处理场景，使用时需严格验证任务安全性，避免执行危险操作
• default_plan_mode：开启后Agent执行任务前会先输出完整执行计划，用户确认后再逐步执行，适合复杂多步骤任务（如项目重构、服务部署），避免Agent执行不符合预期的操作。
• merge_all_available_skills：开启后会自动合并全局、用户级、项目级的所有Agent Skill，建议保持true确保自定义技能全部生效。
• extra_skill_dirs：可添加多个自定义Skill存储目录，例如将通用技能存放在~/my-kimi-skills，添加后CLI会自动扫描该目录下的所有技能文件。
• telemetry：匿名遥测仅上报使用频率、错误类型等非敏感数据，不会上传代码、对话内容、API密钥等隐私信息，用于帮助开发者优化产品体验，介意可设为false关闭。

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

providers

操作目的

定义LLM供应商的接入凭证与API端点，支持同时配置多个供应商，实现多模型快速切换，满足不同场景的模型需求。

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

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

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

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

补充说明与最佳实践

• type字段必须严格使用文档指定的枚举值，不可自定义，例如写moonshot不会被识别，必须填写kimi。
• 配置文件存储在本地，建议将~/.kimi-code/目录权限设为0700（Linux/macOS），仅当前用户可读写，避免API密钥泄露。
• base_url使用官方服务时无需填写，将自动使用对应供应商的默认端点；使用第三方兼容服务或本地部署模型时，需填写对应服务的API地址。
• oauth字段由/login命令自动生成与更新，请勿手动修改，否则可能导致OAuth登录失效。
• env子表仅作为api_key与base_url的备用存储，不会读取shell环境变量，需显式将密钥写入配置文件方可生效。

models

操作目的

为模型定义易记的别名，屏蔽不同供应商的模型ID差异，实现快速切换模型；同时可自定义模型的上下文长度、能力标签等元数据，适配不同模型的特性。

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

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

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

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

补充说明与最佳实践

• provider必须与providers表中定义的供应商名称完全一致，否则会抛出「供应商不存在」错误。
• model字段必须与供应商官方支持的模型ID完全匹配，例如Kimi的kimi-for-coding、Claude的claude-3-5-sonnet-20240620，填写错误会导致API返回「模型不存在」错误。
• max_context_size需与模型官方标注的上下文长度一致，例如Kimi for Coding为262144（256K），填写过小会导致上下文未充分利用就被压缩，填写过大会超出模型限制导致API报错。
• 建议将模型别名设置为短而易记的名称，例如kimi、claude、gpt，方便启动时通过-m参数快速切换。
• 第三方开源模型（如DeepSeek V3、Qwen 2.5）若未被CLI自动识别能力，可通过capabilities字段手动追加thinking、tool_use等标签，启用对应功能。
• display_name可设置为友好的显示名称，例如将claude-3-5-sonnet-20240620的显示名设为Claude 3.5 Sonnet，提升TUI界面的可读性。

thinking

操作目的

全局控制深度推理模式的默认行为，平衡推理精度与响应速度，适配不同使用场景的需求。

thinking 设置 Thinking 模式的全局默认行为。mode = "off" 会强制关闭 Thinking，即使顶层 default_thinking = true 也不例外。

补充说明与最佳实践

• mode设为auto时，模型会自动判断问题复杂度，简单问题直接回答，复杂问题自动开启思考，兼顾响应速度与推理精度，是大多数场景的推荐选择。
• mode设为on时，所有请求均强制开启思考模式，适合全场景需要高准确率的用户（如专业编码、复杂问题Debug）。
• mode设为off时，完全关闭思考功能，响应速度最快，但复杂问题准确率会显著下降，适合简单问答、代码补全等轻量场景。
• effort等级越高，推理越细致，准确率越高，但耗时越长、token消耗越多：编码、架构设计等场景推荐使用high或max，普通问答场景推荐使用low或medium。

loop_control

操作目的

控制Agent执行循环的行为边界，避免无限循环、上下文溢出等异常情况，提升任务执行的稳定性。

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

补充说明与最佳实践

• max_steps_per_turn建议新手设置为10-20，避免Agent因逻辑错误陷入无限循环，浪费token与系统资源；进阶用户可根据任务复杂度调整或设置为0无限制。
• max_retries_per_step默认3次可覆盖大多数网络波动、API限流等临时错误场景，网络环境较差的用户可适当调高至5次。
• reserved_context_size建议设置为模型最大上下文长度的1/5左右，例如256K上下文模型设置为50000，既避免上下文溢出导致输出截断，又不会频繁压缩历史对话丢失上下文；经常需要长输出的场景可适当调大至100000。
• 若reserved_context_size设置过大，会导致频繁触发上下文压缩，丢失过多历史对话信息；设置过小则可能导致模型输出被截断，需根据实际使用场景平衡调整。

background

操作目的

控制后台任务的并发数量与生命周期，避免后台任务占用过多系统资源，同时支持任务在会话退出后继续运行。

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

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

补充说明与最佳实践

• max_running_tasks可根据设备性能调整，普通办公设备建议设置为2-4，高性能服务器可设置为8-16，避免后台任务占用过多CPU、内存资源影响正常使用。
• keep_alive_on_exit设为true时，退出CLI后后台任务（如模型训练、文件下载、服务部署）会继续在后台运行，适合服务器场景；桌面用户建议保持默认false，避免后台残留进程占用资源。
• 若需要临时覆盖配置文件的keep_alive_on_exit设置，可在启动前设置对应环境变量，无需修改配置文件。

experimental

操作目的

控制实验性功能的开关，允许用户尝鲜新特性，同时可回退到稳定版本逻辑避免异常。

experimental 存放实验功能 flag 的持久化覆盖。目前 micro_compaction 是唯一用户可见的字段，默认值为 true；只有在需要关闭自动清理较旧的大型工具结果时，才需要把它设为 false。

补充说明

• micro_compaction开启后会自动清理旧的大型工具输出（如超过1000行的bash命令结果），避免上下文被无效内容快速占满，同时保留完整的对话历史，是推荐开启的优化特性。
• 若需要保留所有历史工具输出（如审计、调试场景），可将该字段设为false，但需注意上下文占用会快速增长，可能触发更频繁的全量上下文压缩。
• 实验性功能均经过初步测试，但仍可能存在不稳定因素，若遇到上下文丢失、对话异常等问题，可尝试关闭该字段并反馈给开发者。

services

操作目的

配置内置的网页搜索与网页抓取服务，让Agent能够获取实时网络信息、抓取网页内容，提升信息获取能力。

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

[services.moonshot_search]
base_url = "https://api.moonshot.cn/v1/search"
api_key = "sk-xxx"

[services.moonshot_fetch]
base_url = "https://api.moonshot.cn/v1/fetch"
api_key = "sk-xxx"

补充说明与最佳实践

• 配置搜索与抓取服务后，Agent可自动获取最新技术文档、报错解决方案、实时资讯等网络信息，无需用户手动搜索，大幅提升任务处理效率。
• 使用Kimi官方服务时，base_url与api_key可与Kimi供应商配置保持一致，无需单独申请。
• 若使用自建的搜索/抓取服务，填写对应服务的API地址与密钥即可。

permission

操作目的

定义工具调用的权限规则，实现安全的Agent执行控制，避免危险操作对系统造成破坏。

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

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

[[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"

补充说明与最佳实践

• 规则按从上到下的顺序匹配，第一条命中的规则立即生效，因此需将高优先级的严格规则放在前面，例如禁止rm -rf的规则需放在允许Bash的规则之前，否则禁止规则会失效。
• pattern支持通配符*匹配任意字符，例如Bash(rm -rf*)匹配所有以rm -rf开头的bash命令，Read(*.md)匹配所有读取md文件的操作。
• scope字段可控制规则的生效范围：
  • turn-override：仅当前轮次对话生效
  • session-runtime：仅当前会话生效
  • project：仅当前工作目录的项目生效
  • user：全局所有会话生效（默认）
• 新手推荐配置基础安全规则：先允许Read、Grep等只读工具，再禁止rm -rf、format等危险命令，最后将Bash设为ask，既保障安全又不会过度干扰使用。
• MCP工具、自定义工具仅支持按工具名匹配，不支持参数模式匹配，例如自定义工具Deploy只能写pattern = "Deploy"，无法按参数匹配。
• 可通过reason字段标注规则的添加原因，方便后续维护与审计。

tui.toml

操作目的

存储终端界面的个性化偏好设置，无需手动编辑，通过TUI内置命令即可快速配置，修改后可热重载生效。

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

# ~/.kimi-code/tui.toml
theme = "auto" # "auto" | "dark" | "light" | 自定义主题名

[editor]
command = "" # 留空则使用 $VISUAL / $EDITOR

[notifications]
enabled = true
notification_condition = "unfocused" # "unfocused" | "always"

[upgrade]
auto_install = true

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

补充说明与最佳实践

• theme设为auto时会自动跟随系统终端的主题设置，无需手动切换，适配大多数用户的使用习惯。
• [editor].command可配置为你常用的编辑器，例如VS Code填写code --wait，Vim填写vim，编写长提示词时会自动打开外部编辑器，提升输入体验。
• 桌面通知功能开启后，Agent完成长任务时会自动弹出桌面通知，无需一直盯着终端，unfocused模式仅在终端后台运行时通知，避免使用过程中被打扰。
• auto_install开启后会自动下载安装新版本，无需手动升级；若希望手动控制更新节奏，可设为false，自行从官网下载安装包。
• 若tui.toml格式错误，CLI会自动使用默认配置并提示错误，不会导致启动失败，只需修正格式即可恢复自定义配置。
• 修改配置后无需重启CLI，执行/reload-tui即可立即应用新的界面配置，执行/reload可同时重载运行时配置与界面配置。