一、v1.27 的三项核心更新

2026 年 3 月 2 日发布的 Kiro CLI v1.27 对自定义 Agent 的创建体验做了重大升级，值得专门梳理。

1. /agent create 统一 AI 辅助模式

此前版本中，/agent generate（AI 生成）和 /agent create（手动创建）是两条独立路径，容易让人困惑。v1.27 将两者合并：/agent create 默认进入 AI 辅助模式，只需输入 Agent 描述，配置文件自动生成。

> /agent create

✔ Enter agent name: · backend-specialist
✔ Enter agent description: · You are a specialist in backend coding practices
✔ Agent scope · Local (current workspace)
Select MCP servers: markdown-downloader (node), code-analysis (uv)

✓ Agent 'backend-specialist' has been created successfully!

需要手动编写配置文件时，添加 --manual 标志：

/agent create my-agent --manual

2. Granular Tool Trust（细粒度工具信任）

工具执行权限的授权粒度大幅提升，不再只是"允许/拒绝"二选一：

• Shell 命令：精确匹配 / 允许参数变化 / 通配符三档授权
• read/write 工具：特定文件 / 目录级别 / 整个工具类型三档授权

这对生产环境的安全控制意义重大——可以精确限制 Agent 只能操作哪些文件、执行哪类命令。

3. Session Settings Tool

会话内动态调整配置的能力：切换模型、启用/禁用功能，无需修改配置文件，会话结束自动重置。适合临时切换到更强的模型处理复杂任务。

---

二、什么是自定义 Agent

Kiro CLI 的自定义 Agent 本质上是一个 JSON 配置文件，定义了一个具有特定能力边界和行为模式的 AI 助手实例。你可以控制：

• 可用工具的种类与范围
• 哪些工具无需确认直接执行（allowedTools）
• 启动时自动加载的上下文（文件、技能、知识库）
• MCP 服务器连接
• 系统提示词
• 使用的模型
• 生命周期钩子（hooks）

与直接使用默认 Agent 相比，自定义 Agent 的核心价值在于约束：通过明确的权限边界和专用上下文，让 Agent 在特定领域内更精准、更安全地工作。

---

三、创建方式

AI 辅助模式（推荐）

在聊天会话中执行（支持内联参数）：

/agent create backend-specialist -D "Backend coding specialist" -m code-analysis

或从终端直接调用：

kiro-cli agent create backend-specialist

常用参数：

参数	说明
--directory	保存位置：workspace（当前项目）/ global（全局）/ 自定义路径
--description / -D	Agent 描述，AI 根据此生成配置
--mcp-server / -m	指定 MCP 服务器（可多次使用）
--manual	切换到手动模式
--from	基于已有 Agent 作为模板

保存位置

值	保存路径	适用场景
workspace	.kiro/agents/	项目专属 Agent
global	~/.kiro/agents/（默认）	跨项目通用 Agent
自定义路径	指定目录	CI/CD 或团队共享

同名 Agent 存在冲突时，本地（workspace）优先于全局，并会给出警告。

---

四、配置文件结构详解

Agent 配置文件是 JSON 格式，文件名（去掉 .json 后缀）即为 Agent 名称。

最小配置

{
  "name": "my-agent",
  "description": "A custom agent for my workflow",
  "tools": ["read", "write"],
  "prompt": "You are a helpful coding assistant"
}

完整字段一览

字段	是否必填	说明
name	否	Agent 名称（默认取文件名）
description	否	Agent 描述，影响 AI 自动选择
prompt	否	系统提示词（内联或 file:// URI）
tools	否	可用工具列表
allowedTools	否	无需确认直接执行的工具
toolsSettings	否	工具细粒度配置（路径限制等）
mcpServers	否	MCP 服务器配置
resources	否	自动加载的上下文资源
hooks	否	生命周期钩子
model	否	指定模型 ID
keyboardShortcut	否	快捷键切换
welcomeMessage	否	切换时显示的欢迎语

---

五、核心字段深度解析

5.1 prompt — 系统提示词

支持内联和外部文件两种形式：

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

// 外部文件（推荐用于长提示词）
{
  "prompt": "file://./prompts/aws-expert.md"
}

file:// URI 的路径解析规则：

• 相对路径 → 以 Agent 配置文件所在目录为基准
• 绝对路径 → 直接使用

最佳实践： 超过 20 行的提示词建议外置到 .md 文件，方便版本管理和复用。

5.2 tools — 可用工具

{
  "tools": [
    "read",                    // 内置工具
    "write",
    "shell",
    "aws",
    "@git",                    // MCP 服务器的全部工具
    "@rust-analyzer/check_code" // MCP 服务器的指定工具
  ]
}

工具指定语法：

写法	含义
"read"	内置工具
"@server_name"	MCP 服务器的所有工具
"@server/tool_name"	MCP 服务器的特定工具
"*"	所有可用工具
"@builtin"	所有内置工具

5.3 allowedTools — 自动信任工具

列在此处的工具在执行时不会弹出确认提示，支持 glob 匹配：

{
  "allowedTools": [
    "read",
    "@git/git_status",
    "@server/read_*",   // 通配符：所有以 read_ 开头的工具
    "@fetch"
  ]
}

匹配规则：

• * 匹配任意长度字符串
• ? 匹配单个字符
• 区分大小写

⚠️ 安全提示： allowedTools 中的工具跳过用户确认直接执行。遵循最小权限原则，优先用精确工具名而非通配符。

5.4 mcpServers — MCP 服务器

stdio 模式（本地命令）：

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

HTTP 模式（含 OAuth）：

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.github.com/mcp",
      "oauth": {
        "redirectUri": "127.0.0.1:8080",
        "oauthScopes": ["repo", "user"]
      }
    }
  }
}

5.5 resources — 上下文资源

三种资源类型，按加载方式分：

{
  "resources": [
    "file://README.md",              // 启动时全文读入
    "file://.kiro/steering/**/*.md", // 支持 glob 匹配
    "skill://.kiro/skills/**/SKILL.md", // 元数据即时加载，正文按需加载
    {
      "type": "knowledgeBase",
      "source": "file://./docs",
      "name": "ProjectDocs",
      "description": "Project documentation",
      "indexType": "best",
      "autoUpdate": true
    }
  ]
}

类型	加载时机	适用场景
file://	启动时全量加载	始终需要的核心上下文
skill://	元数据即时，正文按需	大量文档，避免 context 浪费
knowledgeBase	索引化后语义检索	超大规模文档集

5.6 hooks — 生命周期钩子

在 Agent 生命周期的关键节点自动执行命令：

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

触发点	时机
agentSpawn	Agent 初始化时
userPromptSubmit	用户发送消息时
preToolUse	工具执行前（可阻断）
postToolUse	工具执行后
stop	助手响应完成时

实用技巧： postToolUse + fs_write 的组合可以在每次写文件后自动运行格式化工具（Prettier、cargo fmt、black 等），彻底免除手动格式化。

---

六、生产级完整配置示例

以接入 Openclaw 的编码 Agent 为例，展示各字段的协同使用：

{
  "name": "openclaw-coding-agent",
  "description": "Openclaw 专用编码 Agent，负责代码生成、执行验证与重构",
  "prompt": "file://./prompts/coding-agent.md",
  "mcpServers": {
    "fetch": {
      "command": "fetch3.1",
      "args": []
    },
    "git": {
      "command": "git-mcp",
      "args": []
    }
  },
  "tools": [
    "read", "write", "shell", "aws",
    "@git", "@fetch/fetch_url"
  ],
  "allowedTools": [
    "read",
    "@git/git_status",
    "@git/git_diff"
  ],
  "toolsSettings": {
    "write": {
      "allowedPaths": [
        "src/**",
        "tests/**",
        "scripts/**",
        "requirements.txt",
        "package.json"
      ]
    },
    "subagent": {
      "availableAgents": ["reviewer", "tester", "docs-*"],
      "trustedAgents": ["reviewer", "tester"]
    }
  },
  "resources": [
    "file://README.md",
    "file://src/**/*.py",
    "skill://.kiro/skills/**/SKILL.md"
  ],
  "hooks": {
    "agentSpawn": [
      { "command": "git status" }
    ],
    "postToolUse": [
      {
        "matcher": "fs_write",
        "command": "black . --quiet 2>/dev/null || true"
      }
    ]
  },
  "model": "claude-sonnet-4.6",
  "keyboardShortcut": "ctrl+k",
  "welcomeMessage": "编码 Agent 就绪，当前项目：Openclaw"
}

配置要点说明：

• toolsSettings.write.allowedPaths 将写权限限制在 src/、tests/、scripts/ 目录，防止 Agent 意外修改根目录配置文件
• allowedTools 只开放只读的 git 操作（status、diff），写操作（commit、push）仍需确认
• postToolUse 钩子在每次写文件后自动运行 black 格式化，|| true 防止格式化失败阻断主流程
• resources 中的 skill:// 避免将所有技能文档全量加载到 context，按需获取

---

七、子 Agent 架构

自定义 Agent 不只是主对话 Agent，还可以作为子 Agent 被其他 Agent 调用，构成多层 Agent 协作架构。

子 Agent 的特性

• 由主 Agent 按需自动 spawn，无需手动触发
• 每个子 Agent 拥有独立的 context window，不污染主 Agent 的上下文
• 支持多个子 Agent 并发执行
• 执行完成后结果自动返回主 Agent

调用方式

自然语言描述任务，Kiro 自动匹配合适的子 Agent：

> 用 backend agent 对 payment 模块做重构

或由主 Agent 基于 description 字段自动选择匹配的子 Agent。

访问控制

在父 Agent 的配置中控制可用的子 Agent 范围：

{
  "toolsSettings": {
    "subagent": {
      "availableAgents": ["reviewer", "tester", "docs-*"],
      "trustedAgents": ["reviewer", "tester"]
    }
  }
}

• availableAgents：限制哪些 Agent 可被 spawn 为子 Agent（支持 glob）
• trustedAgents：列表中的子 Agent 执行时不需要确认提示

CLI vs IDE 的差异

维度	Kiro IDE	Kiro CLI
配置格式	Markdown + YAML frontmatter	JSON
内置子 Agent	2 个（context gathering + general purpose）	1 个（default subagent）
Hooks 在子 Agent 中	不触发	正常触发
受限工具	—	web_search、use_aws、grep、glob 等有限制

---

八、Agent 切换与使用

会话内切换

> /agent swap

Choose one of the following agents
❯ openclaw-coding-agent
  kiro_default
  backend-specialist

启动时指定

kiro-cli --agent openclaw-coding-agent

快捷键切换

配置 keyboardShortcut 后，按下对应快捷键即可切换；再次按下恢复上一个 Agent。

---

九、最佳实践

✅ 最小权限原则

tools 和 allowedTools 从最小集合出发，按需扩展。宁可多一次确认提示，也好过 Agent 误操作关键文件。

✅ 提示词外置

超过 20 行的系统提示使用 file:// URI 引用外部 .md 文件，结合 Git 做版本管理，方便 diff 和 review。

✅ Workspace vs Global 合理分层

项目特定的 Agent（含项目上下文、特定 MCP 服务器）放 .kiro/agents/；通用工具类 Agent 放 ~/.kiro/agents/，跨项目复用。

✅ allowedTools 优先用精确名称

@server/specific_tool 比 @server/* 更安全。只有充分理解某类工具的所有可能操作后，再考虑通配符。

✅ 钩子自动化重复工作

postToolUse + fs_write 绑定格式化工具；agentSpawn 初始化时执行 git status 获取当前项目状态；preToolUse 做审计日志。

✅ 合理利用 resources 类型

小文件（README、配置）用 file://；大量文档用 skill:// 避免 context 浪费；超大规模文档集用 knowledgeBase 做语义检索。

---

十、总结

Kiro CLI v1.27 的 /agent create AI 辅助模式大幅降低了自定义 Agent 的创建门槛——从"需要理解 JSON 配置"到"描述你想要什么"。但真正的生产价值在于配置文件的精细化：通过 toolsSettings 限制操作范围、用 hooks 自动化重复操作、用 resources 类型组合控制 context 开销，可以构建出既安全又高效的专用 Agent。

结合子 Agent 架构，Kiro CLI 的自定义 Agent 体系足以支撑复杂的 Multi-Agent 工作流——这也是 Openclaw 等 Agent 平台将 Kiro CLI 作为编码子 Agent 集成的技术基础。

---

参考文档

• Creating custom agents
• Agent configuration reference
• Subagents (CLI)
• Subagents (IDE)
• Kiro CLI v1.27 Changelog