Kiro CLI 的配置项通过 kiro-cli settings 命令管理，配置文件存储在 ~/.kiro/settings/cli.json。本文列出全量配置项，分类包括：遥测与隐私（telemetry）、对话界面（chat）、知识库（knowledge）、快捷键（classic 界面专用）、Tool Search、功能开关（实验性功能）、API 超时、MCP 服务器配置等。每项均附类型、说明和命令行示例，并提供典型场景下的组合配置示范。
基本操作
# 列出所有已配置的项
kiro-cli settings list
# 列出所有可用配置项（含说明）
kiro-cli settings list --all
# 读取某个配置项
kiro-cli settings telemetry.enabled
# 设置某个配置项
kiro-cli settings telemetry.enabled true
# 删除某个配置项
kiro-cli settings --delete chat.defaultModel
# 在默认编辑器中打开配置文件
kiro-cli settings open输出格式
kiro-cli settings list # 纯文本（默认）
kiro-cli settings list --format json
kiro-cli settings list --format json-pretty配置项速查
遥测与隐私
| 配置项 | 类型 | 说明 | 示例 |
|---|---|---|---|
| telemetry.enabled | boolean | 开启/关闭遥测数据收集 | kiro-cli settings telemetry.enabled true |
| telemetryClientId | string | 遥测的客户端标识符 | kiro-cli settings telemetryClientId "client-123" |
对话界面
| 配置项 | 类型 | 说明 | 示例 |
|---|---|---|---|
| chat.defaultModel | string | 默认 AI 模型 | kiro-cli settings chat.defaultModel "claude-3-sonnet" |
| chat.defaultAgent | string | 默认 Agent 配置 | kiro-cli settings chat.defaultAgent "my-agent" |
| chat.diffTool | string | 外部 diff 工具（仅 classic） | kiro-cli settings chat.diffTool "delta" |
| chat.greeting.enabled | boolean | 启动时显示欢迎语 | kiro-cli settings chat.greeting.enabled false |
| chat.editMode | boolean | 开启 Vi 编辑模式（仅 classic） | kiro-cli settings chat.editMode true |
| chat.enableNotifications | boolean | 开启桌面通知 | kiro-cli settings chat.enableNotifications true |
| chat.notificationMethod | string | 通知方式：auto、bel 或 osc9 | kiro-cli settings chat.notificationMethod "osc9" |
| chat.disableMarkdownRendering | boolean | 关闭 Markdown 格式渲染（仅 classic） | kiro-cli settings chat.disableMarkdownRendering false |
| chat.disableAutoCompaction | boolean | 关闭对话自动摘要压缩 | kiro-cli settings chat.disableAutoCompaction true |
| compaction.excludeMessages | number | 压缩时保留的最小消息对数 | kiro-cli settings compaction.excludeMessages 2 |
| compaction.excludeContextWindowPercent | number | 压缩时保留的最小上下文窗口百分比 | kiro-cli settings compaction.excludeContextWindowPercent 2 |
| chat.enablePromptHints | boolean | 启动时显示提示与快捷键（v1.26.0+，默认 true） | kiro-cli settings chat.enablePromptHints false |
| chat.enableHistoryHints | boolean | 显示对话历史提示（仅 classic） | kiro-cli settings chat.enableHistoryHints true |
| chat.uiMode | string | UI 显示变体 | kiro-cli settings chat.uiMode "compact" |
| chat.ui | string | UI 引擎：tui（默认）或 classic | kiro-cli settings chat.ui "classic" |
| chat.disableGranularTrust | boolean | 关闭工具权限的分级信任选项（仅 terminal UI） | kiro-cli settings chat.disableGranularTrust true |
| chat.autoExpandToolOutput | boolean | 自动展开工具输出，不折叠（仅 terminal UI） | kiro-cli settings chat.autoExpandToolOutput true |
| chat.enableContextUsageIndicator | boolean | 在提示符中显示上下文使用百分比（仅 classic） | kiro-cli settings chat.enableContextUsageIndicator true |
知识库
| 配置项 | 类型 | 说明 | 示例 |
|---|---|---|---|
| chat.enableKnowledge | boolean | 开启知识库功能 | kiro-cli settings chat.enableKnowledge true |
| knowledge.defaultIncludePatterns | array | 默认包含的文件模式 | kiro-cli settings knowledge.defaultIncludePatterns '["*.py", "*.js"]' |
| knowledge.defaultExcludePatterns | array | 默认排除的文件模式 | kiro-cli settings knowledge.defaultExcludePatterns '["*.log", "node_modules"]' |
| knowledge.maxFiles | number | 索引的最大文件数 | kiro-cli settings knowledge.maxFiles 1000 |
| knowledge.chunkSize | number | 文本分块大小 | kiro-cli settings knowledge.chunkSize 512 |
| knowledge.chunkOverlap | number | 文本分块之间的重叠量 | kiro-cli settings knowledge.chunkOverlap 50 |
| knowledge.indexType | string | 知识索引类型 | kiro-cli settings knowledge.indexType "fast" |
快捷键（仅 classic 界面）
以下快捷键配置仅适用于 classic 界面，在 terminal UI 中无效。
| 配置项 | 类型 | 说明 | 示例 |
|---|---|---|---|
| chat.skimCommandKey | char | 模糊搜索命令快捷键 | kiro-cli settings chat.skimCommandKey "f" |
| chat.autocompletionKey | char | 接受自动补全提示的快捷键 | kiro-cli settings chat.autocompletionKey "Tab" |
| chat.tangentModeKey | char | 切换 tangent 模式的快捷键 | kiro-cli settings chat.tangentModeKey "t" |
| chat.delegateModeKey | char | 委托命令快捷键 | kiro-cli settings chat.delegateModeKey "d" |
Tool Search
按需发现并加载 MCP 工具，避免全量工具定义占用上下文 token。详见 Tool Search。
| 配置项 | 类型 | 说明 | 示例 |
|---|---|---|---|
| toolSearch.enabled | boolean | 开启 Tool Search（默认 false） | kiro-cli settings toolSearch.enabled true |
| toolSearch.minPct | number | MCP 工具规格超过此上下文窗口百分比时激活（默认 5） | kiro-cli settings toolSearch.minPct 0 |
| toolSearch.minTokens | number | MCP 工具规格超过此 token 数时激活（默认 50000） | kiro-cli settings toolSearch.minTokens 0 |
功能开关
| 配置项 | 类型 | 说明 | 示例 |
|---|---|---|---|
| chat.enableThinking | boolean | 开启 thinking 工具，用于复杂推理 | kiro-cli settings chat.enableThinking true |
| chat.enableTangentMode | boolean | 开启 tangent 模式（仅 classic） | kiro-cli settings chat.enableTangentMode true |
| introspect.tangentMode | boolean | 自动进入 tangent 模式处理 introspect 问题（仅 classic） | kiro-cli settings introspect.tangentMode true |
| chat.enableTodoList | boolean | 开启 ToDo 列表功能（仅 classic） | kiro-cli settings chat.enableTodoList true |
| chat.enableCheckpoint | boolean | 开启 checkpoint 功能（仅 classic） | kiro-cli settings chat.enableCheckpoint true |
| chat.enableDelegate | boolean | 开启 delegate 工具（仅 classic） | kiro-cli settings chat.enableDelegate true |
| app.disableAutoupdates | boolean | 关闭后台自动更新 | kiro-cli settings app.disableAutoupdates true |
API 与服务
| 配置项 | 类型 | 说明 | 示例 |
|---|---|---|---|
| api.timeout | number | API 请求超时（秒） | kiro-cli settings api.timeout 30 |
MCP 配置
| 配置项 | 类型 | 说明 | 示例 |
|---|---|---|---|
| mcp.initTimeout | number | MCP 服务器初始化超时 | kiro-cli settings mcp.initTimeout 10 |
| mcp.noInteractiveTimeout | number | 非交互模式下的 MCP 超时 | kiro-cli settings mcp.noInteractiveTimeout 5 |
| mcp.loadedBefore | boolean | 记录 MCP 服务器是否曾成功加载 | kiro-cli settings mcp.loadedBefore true |
典型场景配置示例
基本初始化
# 开启遥测
kiro-cli settings telemetry.enabled true
# 设置默认模型
kiro-cli settings chat.defaultModel "claude-3-sonnet"
# 关闭启动欢迎语
kiro-cli settings chat.greeting.enabled false知识库配置
# 开启知识库
kiro-cli settings chat.enableKnowledge true
# 设置包含的文件类型
kiro-cli settings knowledge.defaultIncludePatterns '["*.py", "*.js", "*.md", "*.txt"]'
# 设置排除的路径
kiro-cli settings knowledge.defaultExcludePatterns '["*.log", "node_modules", ".git", "*.pyc"]'
# 最大索引文件数
kiro-cli settings knowledge.maxFiles 2000开启实验性功能
kiro-cli settings chat.enableThinking true
kiro-cli settings chat.enableTangentMode true
kiro-cli settings chat.enableTodoList true
kiro-cli settings chat.enableCheckpoint true
# 配置快捷键
kiro-cli settings chat.tangentModeKey "t"
kiro-cli settings chat.delegateModeKey "d"性能调优
# 增大 API 超时（网络较慢时）
kiro-cli settings api.timeout 60
# 调整知识库分块大小
kiro-cli settings knowledge.chunkSize 1024
# 关闭长对话的自动压缩
kiro-cli settings chat.disableAutoCompaction true常见问题排查
配置值类型错误
布尔值必须使用小写：
kiro-cli settings telemetry.enabled true # ✓ 正确
kiro-cli settings telemetry.enabled True # ✗ 错误数组值使用 JSON 格式，外层用单引号：
kiro-cli settings knowledge.defaultIncludePatterns '["*.py", "*.js"]' # ✓ 正确字符串值中如有空格需加引号：
kiro-cli settings chat.defaultModel "claude-3-sonnet" # ✓ 正确重置配置
# 删除单个配置项
kiro-cli settings --delete setting.name
# 在编辑器中手动编辑
kiro-cli settings open
# 查看所有当前配置
kiro-cli settings list --all配置文件损坏时的恢复步骤
- 备份当前配置：
kiro-cli settings list --format json > backup.json - 打开配置文件：
kiro-cli settings open - 验证 JSON 语法或从备份恢复
配置文件位置
配置存储在 ~/.kiro/settings/cli.json。
建议优先使用 kiro-cli settings 命令操作，直接编辑文件时需确保 JSON 格式正确。
环境变量
| 变量 | 说明 |
|---|---|
| KIRO_LOG_NO_COLOR | 设为 1 时关闭日志彩色输出 |
| NO_COLOR | 设为任意值时关闭 terminal UI 中的所有颜色 |
| KIRO_CLI_TOOL_SEARCH_MATCHING_THRESHOLD | Tool Search 关键词结果的最低相关性分数（默认 1.5） |
常见问题
Q：chat.ui 设为 classic 和保持默认 tui 有什么实际区别？
A：tui（默认）是新版 terminal UI，支持更丰富的交互，包括工具输出折叠展开、分级信任等功能；classic 是旧版行界面，更接近传统 CLI 风格，部分功能仅在 classic 模式下有效（如 Vi 编辑模式、Markdown 渲染开关、切换键绑定等）。如果你在 CI/CD 或 SSH 环境中遇到渲染问题，可以尝试切换到 classic。
Q：chat.disableAutoCompaction 关掉之后会有什么副作用？
A：关掉自动压缩后，对话历史会持续累积，上下文窗口用量不断增加。在超长对话中，这可能导致达到模型最大上下文限制，使后续消息被截断。建议只在需要完整保留对话细节的场景下关闭，普通使用保持默认自动压缩即可。
Q：Tool Search 的 toolSearch.minPct 和 toolSearch.minTokens 如何配合使用？
A：两个阈值是"或"关系，任意一个被触发都会激活 Tool Search。将两者都设为 0 可强制始终使用 Tool Search（按需加载工具定义），适合 MCP 工具数量很多、工具定义 token 占用高的场景，可以显著减少每次请求消耗的上下文。