Kiro CLI Custom Agents 排障主要围绕四类问题：JSON 或 schema 配置错误、agent 加载路径错误、tools 和 allowedTools 权限不匹配、resources/hooks/MCP 未生效。按 /agent schema、/agent list、/tools 和手动测试逐步定位。

Kiro CLI Custom Agents 排障：配置、加载、工具权限和 MCP 问题

Custom agents 的问题通常不是模型能力不足，而是配置没有被正确加载、工具名写错、权限范围不匹配，或 MCP server 没启动。排查时不要一次性改很多字段，最好按“配置格式 → agent 加载 → tools 权限 → resources/MCP”顺序定位。

JSON 配置错误

Invalid JSON syntax

现象：

• 报错中出现 invalid JSON 或 syntax error。
• custom agent 不出现在 /agent list 中。
• Kiro 回退到默认 agent 行为。

解决：

• 用 JSON validator 或 linter 检查文件。
• 检查数组或对象之间是否缺少逗号。
• 删除最后一个元素后的 trailing comma。
• 检查括号、花括号是否匹配。
• 字符串中的引号要正确转义。
• 用 /agent schema 校验配置结构。

Schema validation errors

现象：

• 出现 unknown configuration fields 警告。
• agent 行为和配置不一致。
• 提示缺少 required fields。

解决：

• 对照 /agent schema 检查字段。
• 检查字段拼写，例如 allowedTools 不要写成 allowedTool。
• 确认类型正确：数组不要写成字符串，布尔值不要写成字符串。

Custom agent 找不到

现象：

• /agent list 看不到你的 agent。
• 指定 agent 时回退到默认 agent。

解决：

• 确认文件放在正确位置：
  • Global：~/.kiro/agents/[name].json
  • Workspace：.kiro/agents/[name].json
• 确认文件可读。
• 确认文件名和要使用的 agent name 匹配。
• 确认扩展名是 .json。

加载了错误版本

如果本地和全局有同名 agent，Kiro 会优先加载本地版本。

现象：

• 行为不是你刚改的版本。
• 出现 custom agent conflict warning。
• tools 或 permissions 和预期不同。

解决：

• 检查 .kiro/agents/ 和 ~/.kiro/agents/ 是否有同名文件。
• 用 /agent list 查看实际加载版本。
• 删除、重命名或合并冲突配置。

Tool 不可用

现象：

• 报 unknown 或 unavailable tool。
• allowedTools 中的工具仍然要求确认。
• MCP server tools 不工作。

解决：

• 确认 tool 名称拼写正确，大小写敏感。
• MCP tools 要确认 server 已配置在 mcpServers。
• 检查 MCP server 是否启动、可访问。
• MCP tool 使用正确格式：@server_name/tool_name。
• 对照 built-in tools 文档确认内置 tool 名称。

/tools 返回空列表

现象：

• /tools 显示空列表或工具少于预期。
• custom agent 看起来没有能力。

常见原因：

• custom agent 配置里 tools 数组为空。
• tools 中工具名拼写错误。
• MCP tool 名称缺少 server prefix。
• MCP server 配置失败，导致工具没有加载。

解决：

• 确认 tools 数组包含有效工具。
• 对 MCP tools 使用 server 前缀格式。
• 用默认 agent 运行 /tools 对比工具是否可用。
• 检查 MCP server 状态和日志。

意外权限提示

现象：

• 工具写在 allowedTools 中，但仍弹出权限确认。
• 工作流被频繁确认打断。

解决：

• 确认工具同时在 tools 和 allowedTools 中。
• 检查两个数组中的工具名是否完全一致。
• MCP tools 在 allowedTools 中要写完整 server prefix。
• 如果用了 toolAliases，确认 alias 是否正确生效。

缺少 context 或 resources

现象：agent 像是没有读到预期项目文档或资源。

解决：

• 检查 resources 中路径是否正确，文件是否存在。
• 检查 glob 是否匹配到目标文件。
• 确认 hook 命令是否成功执行并输出内容。
• 手动运行 hook 命令，验证在当前环境可用。
• 如果 hook 被截断，调大 timeout 或减少输出。

MCP server 问题

解决步骤：

• 确认 MCP server command 正确。
• 确认可执行文件在 PATH 中。
• 检查所需环境变量是否存在。
• 单独测试 MCP server。
• 查看 MCP server logs。
• 如果 server 启动慢，增加 timeout。

系统化测试 custom agent

建议按这个清单测试：

1. 用 JSON validator 校验语法。
2. 用 /agent schema 检查结构。
3. 用 /agent list 确认 agent 能加载。
4. 用 /agent swap [name] 切换到该 agent。
5. 用 /tools 检查工具列表。
6. 分别测试每个 tool 的访问和权限。
7. 验证 resources 和 hooks 是否提供了预期上下文。
8. 跑一遍常见 workflow，确认行为符合预期。

常见问题

Q: Kiro custom agent 不出现在 /agent list 怎么办？

A: 先确认文件位置、扩展名、JSON 语法和读取权限，再用 /agent schema 检查配置结构。

Q: allowedTools 写了为什么还弹确认？

A: 工具必须同时出现在 tools 和 allowedTools，并且名称要完全匹配；MCP tools 要带 server 前缀。

Q: MCP tools 不显示怎么办？

A: 检查 mcpServers 配置、命令路径、环境变量、server 日志和 timeout。