Kiro CLI 配置分为 Global、Project 和 Agent 三层作用域。MCP servers、prompts、custom agents、steering 和 settings 可以放在不同路径；冲突时通常选择离当前项目或当前 agent 更近的配置。

Kiro CLI 配置：Global、Project 和 Agent 三层作用域

Kiro CLI 可以按个人偏好、项目规则和特定 agent 配置不同上下文。理解配置作用域很重要，否则很容易出现“为什么这个 MCP 或 steering 没生效”的问题。

Kiro CLI 主要有三层作用域：

1. Global：适用于所有项目，位于 <user-home>/.kiro/。
2. Project：只适用于当前项目，位于 <project-root>/.kiro。
3. Agent：定义在 agent 配置文件中，位于 <user-home | project-root>/.kiro/agents。

配置文件路径

常见配置路径：

配置	Global Scope	Project Scope
MCP servers	~/.kiro/settings/mcp.json	.kiro/settings/mcp.json
Prompts	~/.kiro/prompts	.kiro/prompts
Custom agents	~/.kiro/agents	.kiro/agents
Steering	~/.kiro/steering	.kiro/steering
Settings	~/.kiro/settings/cli.json	无项目级 settings

哪些配置支持哪些作用域

配置	User Scope	Project Scope	Agent Scope
MCP servers	支持	支持	支持
Prompts	支持	支持	不支持
Custom agents	支持	支持	不适用
Steering	支持	支持	支持
Settings	支持	不支持	不支持

如果你想把团队规则固定在某个仓库里，优先放在 project scope；如果只是个人偏好，放在 global scope。

冲突如何解决

Kiro CLI 会优先选择离当前交互位置更近的配置。

常见优先级：

配置	优先级
MCP servers	Agent > Project > Global
Prompts	Project > Global
Custom agents	Project > Global
Steering	Project > Global

例如，你在 global 和 project 都配置了 MCP，当你在项目目录里和 Kiro CLI 对话时，会优先使用 project 下的 MCP 配置。

如果 custom agents 在 global 和 project 里同名，项目级配置优先。若同层级中 agent 配置也有冲突，Kiro CLI 会选择 agent 配置中的版本。

MCP 的特殊点

MCP servers 可以在 Global、Project、Agent 三个作用域配置，而且 agent 配置中还有 includeMcpJson 设置。因此 MCP 的加载优先级比其他配置更复杂。

如果你遇到 MCP 工具缺失或加载异常，优先检查：

• 当前目录是否是你预期的项目目录。
• .kiro/settings/mcp.json 是否覆盖了 global 配置。
• agent 配置是否显式包含或排除了 MCP。
• 是否使用了特定 agent 启动 CLI。

配置建议

• 个人常用 prompts 放 global。
• 团队规则、项目 steering 放 project。
• 特定任务角色，例如 reviewer、tester，放 custom agent。
• 和安全或权限有关的 MCP，尽量在 project 或 agent 中明确控制。
• 不要把敏感信息直接写进可提交的配置文件。

常见问题

Q: Kiro CLI 配置优先读全局还是项目？

A: 冲突时通常项目级优先，因为它离当前项目更近。MCP 则还要考虑 agent 作用域。

Q: settings 可以放项目级吗？

A: 官方表格中 settings 只列出 user scope，对应 ~/.kiro/settings/cli.json。

Q: 为什么我的 global MCP 没生效？

A: 可能被项目级或 agent 级 MCP 配置覆盖了，也可能 agent 配置没有包含对应 MCP。