Kiro CLI Agent 配置参考说明 custom agent JSON 文件的主要字段。你可以定义 agent 名称、prompt、MCP servers、可用 tools、免确认 allowedTools、resources、hooks、模型、快捷键和欢迎语，从而把不同工作流固化为专用 agent。

Kiro CLI Agent 配置参考：tools、resources、hooks 和模型设置 #

Kiro CLI custom agent 通过 JSON 配置文件定义行为。文件名通常就是 agent 名称，也可以在 name 字段中显式指定。

这份配置参考适合在你已经理解 custom agents 价值后使用：先从最小可用配置开始，再逐步增加 tools、resources、hooks 和 MCP。

核心字段总览 #

Agent 配置可以包含这些字段：

name 和 description #

name 用于识别和展示：

{
  "name": "aws-expert"
}

description 帮助用户区分不同 agents：

{
  "description": "An agent specialized for AWS infrastructure tasks"
}

描述要写清“什么时候用这个 agent”，否则团队成员很难选择正确 agent。

prompt #

prompt 是 agent 的高层上下文，可以写内联文本：

{
  "prompt": "You are an expert AWS infrastructure specialist"
}

也可以引用外部文件：

{
  "prompt": "file://./my-agent-prompt.md"
}

相对路径会相对于 agent 配置文件所在目录解析；绝对路径会直接使用。长 prompt 建议拆到独立文件，便于版本管理。

mcpServers #

mcpServers 定义 agent 可访问的 MCP servers：

{
  "mcpServers": {
    "git": {
      "command": "git-mcp",
      "args": [],
      "env": {
        "GIT_CONFIG_GLOBAL": "/dev/null"
      },
      "timeout": 120000
    }
  }
}

常见字段：

• command：必填，启动 MCP server 的命令。
• args：可选，命令参数。
• env：可选，环境变量。
• timeout：可选，MCP 请求超时，默认 120000ms。
• oauth：可选，HTTP MCP server 的 OAuth 配置。

HTTP MCP server 需要 OAuth 时，可以配置 redirectUri 和 oauthScopes。

tools #

tools 列出 agent 可以使用的工具：

{
  "tools": [
    "read",
    "write",
    "shell",
    "@git",
    "@rust-analyzer/check_code"
  ]
}

工具引用规则：

• Built-in tools：直接写名称，例如 read、shell。
• MCP server 所有工具：@server_name。
• MCP server 单个工具：@server_name/tool_name。
• 所有工具：*。
• 所有 built-in tools：@builtin。

toolAliases #

当不同 MCP servers 有同名工具时，用 toolAliases 改名：

{
  "toolAliases": {
    "@github-mcp/get_issues": "github_issues",
    "@gitlab-mcp/get_issues": "gitlab_issues"
  }
}

也可以把很长的工具名缩短，例如把 CloudFormation 部署工具改成 deploy_cf。

allowedTools #

allowedTools 表示无需用户确认即可使用的工具：

{
  "allowedTools": [
    "read",
    "@git/git_status",
    "@server/read_*",
    "@fetch"
  ]
}

支持精确匹配和 glob 风格通配符：

• * 匹配任意字符序列。
• ? 匹配单个字符。
• 精确匹配优先于 pattern。
• @server_name 表示允许该 server 的全部工具。
• 匹配区分大小写。

注意：allowedTools 不支持用 "*" 允许所有工具。要免确认使用工具，必须写具体工具、server 或 pattern。

toolsSettings #

toolsSettings 为具体 tool 提供配置：

{
  "toolsSettings": {
    "write": {
      "allowedPaths": ["src/**", "tests/**"]
    },
    "shell": {
      "allowedCommands": ["git status", "npm test"],
      "deniedCommands": ["git push .*"],
      "autoAllowReadonly": true
    }
  }
}

它适合限制 write 路径、shell 命令、AWS services 等高风险能力。

resources #

resources 给 agent 提供上下文资源：

{
  "resources": [
    "file://README.md",
    "file://.kiro/steering/**/*.md",
    "skill://.kiro/skills/**/SKILL.md"
  ]
}

资源类型：

• file://：启动时直接加载到上下文。
• skill://：启动时只加载 metadata，完整内容按需加载。
• knowledgeBase：索引大型文档或代码库，按需搜索。

Knowledge base 示例：

{
  "resources": [
    {
      "type": "knowledgeBase",
      "source": "file://./docs",
      "name": "ProjectDocs",
      "description": "Project documentation",
      "indexType": "best",
      "autoUpdate": true
    }
  ]
}

大文档集不要直接塞进 file://docs/**/*.md，更适合 knowledge base。

hooks #

hooks 可以在 agent 生命周期或工具调用前后运行命令：

{
  "hooks": {
    "agentSpawn": [
      { "command": "git status" }
    ],
    "preToolUse": [
      {
        "matcher": "execute_bash",
        "command": "{ echo \"$(date) - Bash:\"; cat; } >> /tmp/audit.log"
      }
    ],
    "postToolUse": [
      {
        "matcher": "fs_write",
        "command": "cargo fmt --all"
      }
    ]
  }
}

可用触发点：

• agentSpawn
• userPromptSubmit
• preToolUse
• postToolUse
• stop

preToolUse 和 postToolUse 的 matcher 使用内部工具名，例如 fs_read、fs_write、execute_bash、use_aws。

includeMcpJson #

{
  "includeMcpJson": true
}

设为 true 时，agent 会同时加载全局和当前 workspace 的 MCP 配置文件中的 servers。安全敏感场景建议显式控制，而不是盲目继承所有 MCP。

model、快捷键和欢迎语 #

指定模型：

{
  "model": "claude-sonnet-4"
}

如果模型不可用，Kiro 会回退到默认模型并显示 warning。

配置快捷键：

{
  "keyboardShortcut": "ctrl+a"
}

支持 ctrl、shift 加字母或数字。再次按同一快捷键会切回之前的 agent。冲突快捷键会被禁用。

欢迎语：

{
  "welcomeMessage": "What would you like to build today?"
}

本地和全局 agent #

本地 agents：

.kiro/agents/

只在当前 workspace 及其子目录可用，适合项目规则和团队共享。

全局 agents：

~/.kiro/agents/

跨项目可用，适合个人通用工作流。

同名时，本地 agent 优先于全局 agent。

安全建议 #

• 从最小 tools 开始，需要时再增加。
• allowedTools 用具体 pattern，少用宽泛通配。
• write、shell、aws 一定配 toolsSettings 限制范围。
• 启用 write tools 后，agent 拥有当前用户的文件系统权限。
• Skills 是文本指令，不能自己执行代码；但如果 agent 允许 shell，就可能执行 skill 中引用的命令。
• 安装第三方 skills 和 resources 前先审查内容。

常见问题 #

Q: Kiro custom agent 配置文件是什么格式？

A: JSON。文件可以放在 .kiro/agents/ 或 ~/.kiro/agents/。

Q: tools 和 allowedTools 有什么区别？

A: tools 表示 agent 能看到哪些工具；allowedTools 表示哪些工具可以免确认使用。

Q: 大量文档应该放 resources 还是 knowledge base？

A: 大型文档集优先 knowledge base，避免每次启动都占用上下文窗口。