Kiro CLI 运行环境配置详细指南

本文档详细描述 Kiro CLI 的所有配置项、配置文件位置、参数说明及示例。

1. 配置体系概览

Kiro CLI 的配置分为多个层级，优先级从高到低：

Session（会话级）> Workspace（工作区级）> Global（全局级）

层级	说明	适用范围
Session	当前会话临时设置	仅当前会话
Workspace	项目目录下的`.kiro/`	仅当前项目
Global	用户主目录下的`~/.kiro/`	所有项目

2. 目录结构

全局目录 `~/.kiro/`

~/.kiro/
├── agents/                    # 全局 Agent 配置
│   ├── my-agent.json
│   └── rust-expert.json
├── prompts/                   # 全局提示词文件
│   └── rust-expert.txt
├── skills/                    # 全局技能文件
│   └── my-skill/
│       └── SKILL.md
├── steering/                  # 全局引导文件
│   ├── coding-standards.md
│   └── preferences.md
├── settings/
│   ├── cli.json               # 全局设置
│   └── mcp.json               # 全局 MCP 配置
├── hooks/                     # 钩子脚本存放目录（可自定义）
│   └── validate-write.sh
├── sessions/cli/              # 保存的聊天会话
└── .cli_bash_history          # Shell 命令历史

工作区目录 `.kiro/`（项目根目录下）

.kiro/
├── agents/                    # 工作区 Agent 配置（优先级高于全局）
│   └── project-helper.json
├── skills/                    # 工作区技能文件
│   └── db-helper/
│       └── SKILL.md
├── steering/                  # 工作区引导文件
│   └── team-conventions.md
└── settings/
    ├── cli.json               # 工作区设置（覆盖全局）
    └── mcp.json               # 工作区 MCP 配置

项目根目录其他配置文件

项目根目录/
├── AGENTS.md                  # 项目 Agent 指令（自动加载）
├── README.md                  # 项目说明（自动加载）
├── AmazonQ.md                 # 旧版项目指令（如存在则加载）
├── lsp.json                   # LSP 代码智能配置
└── .amazonq/                  # 旧版配置（向后兼容）
    ├── mcp.json
    └── rules/**/*.md

3. 全局设置 (cli.json)

文件位置

作用域	文件路径
全局	`~/.kiro/settings/cli.json`
工作区	`.kiro/settings/cli.json`

完整设置项列表

3.1 Chat 聊天相关

设置项	类型	默认值	说明
`chat.defaultAgent`	string	(无)	新会话使用的默认 Agent 名称
`chat.defaultModel`	string	(无)	默认 AI 模型 ID
`chat.enableThinking`	boolean	-	启用思考工具
`chat.showThinking`	boolean	`false`	显示思考/推理块（仅启动时生效）
`chat.enableKnowledge`	boolean	-	启用知识库功能
`chat.enableCodeIntelligence`	boolean	-	启用代码智能（LSP）
`chat.enableSubagent`	boolean	-	启用子 Agent 功能
`chat.enableTodoList`	boolean	-	启用待办列表功能
`chat.enableNotifications`	boolean	-	启用桌面通知
`chat.greeting.enabled`	boolean	-	启动时显示欢迎消息
`chat.allowAnimations`	boolean	`true`	启用加载动画（旋转、进度条）
`chat.allowAsciiArt`	boolean	`true`	启用 Unicode 符号，false 则降级为纯 ASCII
`chat.allowIcons`	boolean	`true`	显示状态指示图标
`chat.terminalTitle`	boolean	`false`	通过 OSC 0 更新终端窗口标题
`chat.disableAutoCompaction`	boolean	-	禁用自动上下文压缩
`chat.disableGranularTrust`	boolean	-	禁用细粒度信任选项
`chat.disableInheritingDefaultResources`	boolean	`false`	禁用自定义 Agent 继承默认资源
`chat.autoExpandToolOutput`	boolean	-	始终展示完整工具输出
`chat.disableWrap`	boolean	-	禁用聊天输出自动换行
`chat.historyMode`	string	`session`	提示历史范围：`session` 或 `global`

3.2 快捷键

设置项	类型	默认值	说明
`chat.keybindings.cancelStream`	string	`esc`	取消流式输出
`chat.keybindings.closeMenu`	string	`esc`	关闭菜单/面板
`chat.keybindings.quit`	string	`ctrl+c`	退出（需双击）

快捷键语法：修饰符+键，大小写不敏感。

修饰符：ctrl、shift、alt（别名 meta、cmd）
键名：esc、enter、tab、up/down/left/right、space、backspace、delete、home、end、pageup/pagedown、a-z、0-9

3.3 遥测

设置项	类型	默认值	说明
`telemetry.enabled`	boolean	-	启用/禁用遥测（全局设置，不可工作区覆盖）

3.4 知识库

设置项	类型	默认值	说明
`knowledge.defaultIncludePatterns`	array	-	索引时包含的文件 glob 模式
`knowledge.defaultExcludePatterns`	array	-	索引时排除的文件 glob 模式
`knowledge.maxFiles`	number	-	索引的最大文件数
`knowledge.chunkSize`	number	-	文本分块大小
`knowledge.chunkOverlap`	number	-	分块之间的重叠大小
`knowledge.indexType`	string	-	索引类型：`fast`（BM25）或 `best`（语义搜索）

3.5 API

设置项	类型	默认值	说明
`api.timeout`	number	-	API 请求超时（毫秒）
`api.codewhisperer.service`	string	-	CodeWhisperer 端点（全局设置）
`api.q.service`	string	-	Q 服务端点（全局设置）

3.6 MCP

设置项	类型	默认值	说明
`mcp.initTimeout`	number	-	MCP 服务器初始化超时（毫秒）
`mcp.noInteractiveTimeout`	number	-	非交互式 MCP 超时（毫秒）

3.7 上下文压缩

设置项	类型	默认值	说明
`compaction.excludeContextWindowPercent`	number	-	从压缩中排除的上下文窗口百分比
`compaction.excludeMessages`	number	-	从压缩中排除的最近消息数量

3.8 Hooks

设置项	类型	默认值	说明
`hooks.showStatus`	boolean	-	是否显示 hook 执行状态（设为 false 则静默运行）

cli.json 完整示例

文件位置：~/.kiro/settings/cli.json

{
  "chat.defaultAgent": "my-vue-agent",
  "chat.defaultModel": "anthropic.claude-3-5-sonnet-20241022-v2:0",
  "chat.enableThinking": true,
  "chat.showThinking": false,
  "chat.enableKnowledge": true,
  "chat.enableCodeIntelligence": true,
  "chat.enableSubagent": true,
  "chat.enableTodoList": true,
  "chat.enableNotifications": true,
  "chat.greeting.enabled": true,
  "chat.allowAnimations": true,
  "chat.allowAsciiArt": true,
  "chat.allowIcons": true,
  "chat.terminalTitle": false,
  "chat.disableAutoCompaction": false,
  "chat.disableGranularTrust": false,
  "chat.disableInheritingDefaultResources": false,
  "chat.autoExpandToolOutput": false,
  "chat.disableWrap": false,
  "chat.historyMode": "global",
  "chat.keybindings.cancelStream": "esc",
  "chat.keybindings.closeMenu": "esc",
  "chat.keybindings.quit": "ctrl+c",
  "telemetry.enabled": true,
  "knowledge.defaultIncludePatterns": ["**/*.ts", "**/*.vue", "**/*.md"],
  "knowledge.defaultExcludePatterns": ["node_modules/**", "dist/**"],
  "knowledge.maxFiles": 1000,
  "knowledge.chunkSize": 512,
  "knowledge.chunkOverlap": 50,
  "knowledge.indexType": "best",
  "api.timeout": 30000,
  "mcp.initTimeout": 120000,
  "mcp.noInteractiveTimeout": 30000,
  "compaction.excludeContextWindowPercent": 10,
  "compaction.excludeMessages": 5
}

4. Agent 配置

文件位置

作用域	文件路径	优先级
工作区	`.kiro/agents/<name>.json`	高（覆盖同名全局 Agent）
全局	`~/.kiro/agents/<name>.json`	低

文件名（不含 .json）即为 Agent 名称。

所有字段说明

字段	类型	必填	说明
`name`	string	否	Agent 名称标识
`description`	string	否	人类可读描述
`prompt`	string	否	系统提示词（支持内联文本或`file:///path` 引用外部文件）
`model`	string	否	指定模型 ID，未指定则使用默认模型
`tools`	array	否	可用工具列表
`allowedTools`	array	否	自动批准的工具（无需用户确认），支持通配符
`toolsSettings`	object	否	工具级别的详细配置
`resources`	array	否	上下文资源列表
`hooks`	object/array	否	触发器钩子配置
`mcpServers`	object	否	MCP 服务器配置
`toolAliases`	object	否	工具名称重映射（解决命名冲突）
`useLegacyMcpJson`	boolean	否	是否加载旧版`mcp.json` 配置
`keyboardShortcut`	string	否	快速切换到此 Agent 的快捷键
`welcomeMessage`	string	否	切换到此 Agent 时显示的欢迎消息

内置工具列表

以下工具可在 tools 字段中使用：

工具名	别名	说明
`read`	`fs_read`, `fsRead`	读取文件/目录/图片
`write`	`fs_write`, `fsWrite`	创建/编辑文件
`shell`	`execute_bash`, `execute_cmd`	执行终端命令
`grep`	-	正则文本搜索
`glob`	-	文件路径模式匹配
`code`	-	代码智能（AST 搜索、LSP）
`use_aws`	-	AWS CLI API 调用
`web_fetch`	`webFetch`	获取 URL 内容
`web_search`	-	网络搜索
`knowledge`	-	知识库索引和搜索
`subagent`	`agent_crew`, `use_subagent`	子 Agent 流水线
`todo_list`	`task`, `todo`	待办任务管理
`introspect`	-	查询 Kiro CLI 自身文档

特殊值：

"*" — 所有工具（仅用于 tools 字段）
"@builtin" — 所有内置工具（可用于 allowedTools）

tools 与 allowedTools 的区别

tools：Agent 能使用哪些工具（能力范围）
allowedTools：哪些工具使用时无需用户确认（信任范围）

allowedTools 通配符模式

{
  "allowedTools": [
    "read",              // 精确匹配内置工具
    "fs_*",             // 前缀通配：匹配 fs_read, fs_write
    "@git/git_status",  // 精确匹配 MCP 工具
    "@server/read_*",   // MCP 工具通配
    "@git",             // 该 MCP 服务器的所有工具
    "@builtin"          // 所有内置工具
  ]
}

toolsSettings 详细配置

write 工具设置

{
  "toolsSettings": {
    "write": {
      "allowedPaths": ["src/**", "tests/**"],
      "deniedPaths": ["node_modules/**", "/etc/**"]
    }
  }
}

参数	类型	说明
`allowedPaths`	array	允许写入的路径 glob 模式
`deniedPaths`	array	禁止写入的路径 glob 模式

shell 工具设置

{
  "toolsSettings": {
    "shell": {
      "allowedCommands": ["git status", "npm test", "pnpm build"],
      "deniedCommands": ["rm -rf *", "sudo *", "shutdown"],
      "autoAllowReadonly": true,
      "denyByDefault": false
    }
  }
}

参数	类型	默认值	说明
`allowedCommands`	array	-	自动批准的命令（正则模式）
`deniedCommands`	array	-	始终拒绝的命令（正则模式）
`autoAllowReadonly`	boolean	-	自动批准只读命令（如`ls`、`cat`、`git status`）
`denyByDefault`	boolean	`false`	默认拒绝未在 allowedCommands 中的命令

web_fetch 工具设置

{
  "toolsSettings": {
    "web_fetch": {
      "trusted": [".*docs\\.aws\\.amazon\\.com.*", ".*vuejs\\.org.*"],
      "blocked": [".*pastebin\\.com.*"]
    }
  }
}

参数	类型	说明
`trusted`	array	自动允许的 URL 正则模式
`blocked`	array	始终阻止的 URL 正则模式（优先级高于 trusted）

resources 资源配置

支持两种 URI 协议：

协议	加载方式	说明
`file://`	始终加载	内容始终存在于上下文窗口
`skill://`	按需加载	仅元数据（名称、描述）初始加载，内容按需加载

{
  "resources": [
    "file://README.md",
    "file://src/**/*.vue",
    "file://docs/api.md",
    "skill://.kiro/skills/**/SKILL.md"
  ]
}

默认资源继承

自定义 Agent 默认会自动继承以下资源：

资源	说明
`file://AGENTS.md`	项目 Agent 指令
`file://README.md`	项目说明
`skill://.kiro/skills/*/SKILL.md`	工作区技能
`skill://~/.kiro/skills/*/SKILL.md`	全局技能
`file://~/.kiro/steering/*/.md`	全局引导文件
`file://.kiro/steering/*/.md`	工作区引导文件
`file://AmazonQ.md`	旧版指令（如存在）

设置 chat.disableInheritingDefaultResources 为 true 可禁用此继承。

Agent 完整示例

文件位置：.kiro/agents/vue-dev.json

{
  "name": "vue-dev",
  "description": "Vue 3 + TypeScript 开发助手",
  "prompt": "你是一个 Vue 3 + TypeScript 专家。使用 Composition API、Naive UI 组件库和 UnoCSS。遵循项目现有的代码风格和架构。",
  "model": "anthropic.claude-3-5-sonnet-20241022-v2:0",
  "tools": [
    "read", "write", "shell", "grep", "glob", "code", "web_fetch", "knowledge"
  ],
  "allowedTools": [
    "read", "grep", "glob", "code"
  ],
  "toolsSettings": {
    "write": {
      "allowedPaths": ["src/**", "docs/**", "tests/**"],
      "deniedPaths": ["node_modules/**", "dist/**"]
    },
    "shell": {
      "allowedCommands": [
        "pnpm (dev|build|test|lint)",
        "git (status|diff|log|branch)",
        "npx vue-tsc"
      ],
      "deniedCommands": ["rm -rf", "sudo"],
      "autoAllowReadonly": true
    },
    "web_fetch": {
      "trusted": [".*vuejs\\.org.*", ".*naiveui\\.com.*"],
      "blocked": [".*pastebin\\.com.*"]
    }
  },
  "resources": [
    "file://src/**/*.vue",
    "file://src/**/*.ts",
    "file://package.json",
    "file://tsconfig.json",
    "skill://.kiro/skills/**/SKILL.md"
  ],
  "hooks": {
    "agentSpawn": [
      { "command": "git branch --show-current && node -v" }
    ],
    "preToolUse": [
      {
        "matcher": "write",
        "command": "echo 'Writing file...'"
      }
    ]
  },
  "mcpServers": {
    "git": {
      "command": "mcp-server-git",
      "args": ["--stdio"]
    }
  },
  "keyboardShortcut": "ctrl+shift+v",
  "welcomeMessage": "Vue 3 开发助手已就绪！有什么可以帮你的？"
}

5. Steering 文件（引导文件）

Steering 文件是持久化的指令文档，用于在所有会话中引导 Agent 行为。

文件位置

作用域	目录路径
工作区	`.kiro/steering/`
全局	`~/.kiro/steering/`

目录会被递归扫描，任何层级的 .md 文件都会被加载。

加载规则

内置默认 Agent (kiro_default)：自动加载 steering 文件
自定义 Agent：需要手动在 resources 中声明：
```
{ "resources": ["file://.kiro/steering/**/*.md"] }
```

inclusion 控制

Steering 文件支持可选的 YAML frontmatter 来控制加载时机：

inclusion 值	行为
`always`	始终加载（默认，等同于无 frontmatter）
`fileMatch`	仅在处理匹配文件时加载（排除自动加载）
`manual`	仅通过`/context add` 手动加载
(无 frontmatter)	始终加载

Steering 文件示例

文件位置：.kiro/steering/coding-standards.md

# 项目编码规范

## Vue 组件
- 使用 Composition API + `<script setup>` 语法
- 组件命名使用 PascalCase
- Props 必须使用 TypeScript 类型定义
- 使用 Naive UI 组件库

## TypeScript
- 严格模式，禁止 `any`
- 函数参数和返回值必须有类型标注
- 使用 `es-toolkit` 代替 lodash

## 样式
- 使用 UnoCSS 原子类
- 避免写自定义 CSS，除非必要
- 暗色模式必须适配

文件位置：~/.kiro/steering/personal-preferences.md

# 个人偏好

- 回答使用中文
- 代码注释使用英文
- 优先给出完整可运行的代码
- 修改代码前先阅读现有实现
- 保持简洁，不要过度设计

带 inclusion 控制的示例：.kiro/steering/vue-rules.md

---
inclusion: always
---

# Vue 开发规则

- 所有组件必须定义 `name` 选项
- 使用 `defineProps` 和 `defineEmits` 宏
- 大型表单使用 Naive UI 的 NForm

6. Skills 技能文件

Skills 是按需加载的资源，启动时仅加载元数据，实际内容在需要时才加载，节省上下文窗口空间。

文件位置

作用域	目录路径
工作区	`.kiro/skills/<skill-name>/SKILL.md`
全局	`~/.kiro/skills/<skill-name>/SKILL.md`

格式要求

Skill 文件必须以 YAML frontmatter 开头：

---
name: vue-component-patterns
description: Vue 3 组件设计模式指南。在设计新组件或重构现有组件时使用。
---

# Vue 3 组件设计模式

## Compound Components Pattern

...详细内容...

frontmatter 字段	必填	说明
`name`	是	技能名称
`description`	是	描述（Agent 根据此决定是否加载完整内容）

在 Agent 中引用 Skills

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

Skills 示例

文件位置：.kiro/skills/naive-ui-patterns/SKILL.md

---
name: naive-ui-patterns
description: Naive UI 组件库常用模式和最佳实践。在使用 Naive UI 组件开发界面时参考。
---

# Naive UI 常用模式

## 表格 (DataTable)

使用 `NDataTable` 时的标准模式：

\`\`\`vue
<script setup lang="ts">
import { NDataTable } from 'naive-ui'
import type { DataTableColumns } from 'naive-ui'

interface RowData {
  id: string
  name: string
}

const columns: DataTableColumns<RowData> = [
  { title: 'ID', key: 'id' },
  { title: '名称', key: 'name' }
]
</script>
\`\`\`

## 表单 (Form)

...

7. Hooks 钩子系统

Hooks 允许在 Agent 生命周期的特定时间点执行自定义命令。

配置位置

Hooks 配置在 Agent 配置文件 中（.kiro/agents/<name>.json 或 ~/.kiro/agents/<name>.json）。

触发时机

触发器	时机	可否阻止工具执行
`agentSpawn`	Agent 初始化时	-
`userPromptSubmit`	用户提交消息时	-
`preToolUse`	工具执行前	✅ 可通过退出码 2 阻止
`postToolUse`	工具执行后	-
`stop`	Assistant 完成回复时	-

退出码含义

退出码	含义
`0`	成功，STDOUT 加入 Agent 上下文
`2`	（仅 preToolUse）阻止工具执行，STDERR 返回给 LLM
其他	失败，STDERR 作为警告显示给用户

两种配置格式

Object 格式（推荐）

{
  "hooks": {
    "agentSpawn": [
      {
        "command": "git status && git branch --show-current",
        "timeout_ms": 5000,
        "cache_ttl_seconds": 0
      }
    ],
    "userPromptSubmit": [
      { "command": "date '+%Y-%m-%d %H:%M:%S'" }
    ],
    "preToolUse": [
      {
        "matcher": "write",
        "command": "~/.kiro/hooks/validate-write.sh",
        "timeout_ms": 10000,
        "max_output_size": 10240
      }
    ],
    "postToolUse": [
      {
        "matcher": "shell",
        "command": "echo 'Command executed'"
      }
    ],
    "stop": [
      { "command": "echo 'Turn complete'" }
    ]
  }
}

Object 格式字段：

字段	必填	类型	默认值	说明
`command`	是	string	-	要执行的命令
`matcher`	否	string	-	工具匹配模式（仅 preToolUse/postToolUse）
`timeout_ms`	否	number	`10000`	最大执行时间（毫秒）
`max_output_size`	否	number	`10240`	最大输出字节数（超出则截断）
`cache_ttl_seconds`	否	number	`0`	缓存成功结果的秒数（0=不缓存）

Array 格式

{
  "hooks": [
    {
      "name": "show-git-status",
      "trigger": "agentSpawn",
      "action": { "type": "command", "command": "git status" },
      "timeout": 10,
      "enabled": true
    },
    {
      "name": "validate-write",
      "trigger": "preToolUse",
      "matcher": "write",
      "action": { "type": "command", "command": "~/.kiro/hooks/validate-write.sh" },
      "timeout": 30,
      "enabled": true
    }
  ]
}

Array 格式字段：

字段	必填	类型	默认值	说明
`name`	否	string	-	可读名称
`trigger`	是	string	-	触发器名称
`matcher`	否	string	-	工具匹配模式
`action`	是	object	-	`{ "type": "command", "command": "..." }`
`timeout`	否	number	`10`	最大执行时间（秒）
`enabled`	否	boolean	`true`	设为 false 可禁用而不删除

Matcher 匹配模式

模式	说明	示例
精确匹配	匹配特定工具	`"write"`、`"shell"`
通配符	匹配工具名模式	`"fs_*"`
MCP 服务器全部工具	匹配某个 MCP 服务器	`"@git"`
MCP 特定工具	匹配 MCP 服务器的特定工具	`"@git/status"`
所有工具	匹配所有	`"*"`
所有内置工具	仅内置	`"@builtin"`
无 matcher	应用于所有工具	(不设置)

Hook 收到的 STDIN 数据

Hook 通过 STDIN 接收 JSON 格式的事件数据：

{
  "hook_event_name": "preToolUse",
  "cwd": "/home/user/project",
  "tool_name": "fs_write",
  "tool_input": {
    "path": "/home/user/project/src/App.vue",
    "command": "create",
    "content": "..."
  }
}

环境变量

Hook 脚本可访问 KIRO_SESSION_ID 环境变量（当前会话 UUID）。

Hook 脚本示例

文件位置：~/.kiro/hooks/validate-write.sh

#!/bin/bash
# 读取 hook 事件
EVENT=$(cat)

# 提取文件路径
FILE=$(echo "$EVENT" | jq -r '.tool_input.path // empty')

# 阻止写入 .env 文件
if [[ "$FILE" == *".env"* ]]; then
  echo "禁止修改 .env 文件" >&2
  exit 2  # 退出码 2 = 阻止工具执行
fi

exit 0  # 允许执行

8. MCP 服务器配置

MCP (Model Context Protocol) 服务器为 Agent 提供额外的工具能力。

配置位置

MCP 服务器可在以下位置配置：

位置	路径	说明
Agent 配置	`.kiro/agents/<name>.json` 的 `mcpServers` 字段	特定 Agent 专用
全局 MCP	`~/.kiro/settings/mcp.json`	所有 Agent 可用
工作区 MCP	`.kiro/settings/mcp.json`	当前项目所有 Agent 可用
旧版全局	`~/.aws/amazonq/mcp.json`	需要`useLegacyMcpJson: true`
旧版工作区	`.amazonq/mcp.json`	需要`useLegacyMcpJson: true`

三种服务器类型

8.1 本地 (stdio) 服务器

通过子进程启动，使用标准输入/输出通信。

{
  "mcpServers": {
    "git": {
      "command": "mcp-server-git",
      "args": ["--stdio"],
      "env": {
        "GIT_DIR": "/path/to/repo"
      },
      "timeout": 120000,
      "disabled": false,
      "disabledTools": ["dangerous_tool"]
    }
  }
}

字段	必填	类型	默认值	说明
`command`	是	string	-	启动服务器的命令
`args`	否	array	-	命令参数
`env`	否	object	-	环境变量
`timeout`	否	number	`120000`	请求超时（毫秒）
`disabled`	否	boolean	`false`	是否禁用此服务器
`disabledTools`	否	array	-	禁用该服务器的特定工具

8.2 远程 (HTTP) 服务器

通过 HTTP/SSE 连接远程服务器。

{
  "mcpServers": {
    "remote-api": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer $API_TOKEN"
      },
      "timeout": 120000,
      "disabled": false,
      "disabledTools": [],
      "forceAuth": false
    }
  }
}

字段	必填	类型	默认值	说明
`url`	是	string	-	HTTP 端点 URL
`headers`	否	object	-	HTTP 请求头
`oauth`	否	object	-	OAuth 配置对象
`oauthScopes`	否	array	-	OAuth 作用域
`timeout`	否	number	`120000`	请求超时（毫秒）
`disabled`	否	boolean	`false`	是否禁用
`disabledTools`	否	array	-	禁用特定工具
`forceAuth`	否	boolean	`false`	跳过无认证尝试，直接走 OAuth

OAuth 配置对象：

{
  "mcpServers": {
    "slack": {
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "clientId": "my-app-id",
        "clientSecret": "my-secret",
        "redirectUri": "http://localhost:7778/oauth/callback",
        "oauthScopes": ["search:read", "channels:read"]
      }
    }
  }
}

oauth 字段	说明
`clientId`	预注册的 OAuth 客户端 ID（设置后跳过动态客户端注册）
`clientSecret`	OAuth 客户端密钥（机密客户端）
`redirectUri`	回调 URI（格式：`host:port`、`:port` 或完整 URL）
`oauthScopes`	请求的 OAuth 作用域

8.3 Registry 服务器

从组织 MCP 注册表解析的服务器（企业版功能）。

{
  "mcpServers": {
    "github": {
      "type": "registry",
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN"
      },
      "timeout": 60000
    }
  }
}

字段	必填	类型	说明
`type`	是	string	必须为`"registry"`
`env`	否	object	环境变量（覆盖注册表默认值）
`headers`	否	object	HTTP 头（远程 registry 服务器）
`timeout`	否	number	请求超时
`oauth`	否	object	OAuth 配置（远程 registry 服务器）

MCP 配置完整示例

在 Agent 配置中（.kiro/agents/full-stack.json）：

{
  "name": "full-stack",
  "tools": ["read", "write", "shell", "code"],
  "mcpServers": {
    "git": {
      "command": "mcp-server-git",
      "args": ["--stdio"]
    },
    "github": {
      "command": "mcp-server-github",
      "args": ["--stdio"],
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN"
      }
    },
    "postgres": {
      "command": "mcp-server-postgres",
      "args": ["--stdio"],
      "env": {
        "DATABASE_URL": "$DATABASE_URL"
      },
      "disabledTools": ["drop_table", "truncate"]
    }
  }
}

9. LSP 代码智能配置

文件位置

项目根目录下的 lsp.json。

初始化

# 在聊天中执行
/code init

# 强制重新初始化
/code init -f

首次执行 /code init 后会创建 lsp.json，后续启动时自动加载。删除 lsp.json 即可禁用。

预配置的语言服务器

语言	文件扩展名	服务器	安装命令
TypeScript/JS	`.ts` `.js` `.tsx` `.jsx`	typescript-language-server	`npm install -g typescript-language-server typescript`
Rust	`.rs`	rust-analyzer	`rustup component add rust-analyzer`
Python	`.py`	pyright	`pip install pyright`
Go	`.go`	gopls	`go install golang.org/x/tools/gopls@latest`
Java	`.java`	jdtls	`brew install jdtls` (macOS)
Kotlin	`.kt` `.kts`	kotlin-lsp	GitHub 下载
Ruby	`.rb`	solargraph	`gem install solargraph`
C/C++	`.c` `.cpp` `.h` `.hpp`	clangd	`apt install clangd` (Linux)

自定义语言服务器

文件位置：项目根目录 lsp.json

{
  "languages": {
    "vue": {
      "name": "vue-language-server",
      "command": "vue-language-server",
      "args": ["--stdio"],
      "file_extensions": ["vue"],
      "project_patterns": ["package.json", "vite.config.ts"],
      "exclude_patterns": ["**/node_modules/**", "**/dist/**"],
      "multi_workspace": false,
      "initialization_options": {
        "typescript": {
          "tsdk": "node_modules/typescript/lib"
        }
      },
      "request_timeout_secs": 60
    }
  }
}

字段	必填	类型	默认值	说明
`name`	是	string	-	语言服务器显示名
`command`	是	string	-	启动命令
`args`	否	array	-	命令参数（通常`["--stdio"]`）
`file_extensions`	是	array	-	处理的文件扩展名
`project_patterns`	否	array	-	项目根标识文件
`exclude_patterns`	否	array	-	排除的 glob 模式
`multi_workspace`	否	boolean	`false`	是否支持多工作区
`initialization_options`	否	object	-	LSP 初始化选项
`request_timeout_secs`	否	number	`60`	请求超时（秒）

10. 环境变量

以下环境变量可影响 Kiro CLI 的运行行为：

变量名	说明
`KIRO_HOME`	覆盖全局配置目录（默认`~/.kiro`）
`KIRO_DATA_DIR`	覆盖运行时数据目录（默认因平台而异）
`KIRO_ASCII_MODE=1`	强制 ASCII 模式，忽略`chat.allowAsciiArt` 设置
`KIRO_CHAT_LOG_FILE`	自定义日志文件路径
`KIRO_LOG_NO_COLOR=1`	禁用日志中的 ANSI 颜色
`KIRO_SESSION_ID`	（Hook 脚本可用）当前会话 UUID
`$EDITOR`	编辑 Agent 配置时使用的编辑器

数据目录默认位置

平台	路径
macOS	`~/Library/Application Support/kiro-cli`
Linux	`~/.local/share/kiro-cli`
Windows	`%LOCALAPPDATA%\kiro-cli`

日志文件默认位置

平台	路径
macOS	`$TMPDIR/kiro-log/kiro-chat.log`
Linux	`$XDG_RUNTIME_DIR/kiro-log/kiro-chat.log`
Windows	`%TEMP%/kiro-log/logs/kiro-chat.log`

示例

# 使用自定义配置目录
KIRO_HOME=/opt/team/kiro kiro-cli chat

# 使用自定义数据目录（企业部署场景）
KIRO_DATA_DIR=/opt/kiro/data kiro-cli chat

# 自定义日志路径
KIRO_CHAT_LOG_FILE=/tmp/kiro-debug.log kiro-cli chat

# 强制 ASCII 模式（SSH/无 Unicode 终端）
KIRO_ASCII_MODE=1 kiro-cli chat

11. 常用命令速查

设置管理

# 查看所有可用设置
kiro-cli settings list --all

# 获取设置值
kiro-cli settings chat.defaultModel

# 修改设置
kiro-cli settings chat.defaultModel "anthropic.claude-3-5-sonnet-20241022-v2:0"
kiro-cli settings chat.defaultAgent "vue-dev"
kiro-cli settings telemetry.enabled false
kiro-cli settings knowledge.indexType "best"

# 删除设置（恢复默认）
kiro-cli settings --delete chat.defaultModel

# 通配符删除
kiro-cli settings --delete "knowledge.*"

# 在编辑器中打开设置文件
kiro-cli settings open

Agent 管理

# 列出所有 Agent
kiro-cli agent list

# 创建 Agent
kiro-cli agent create my-agent
kiro-cli agent create my-agent --from kiro_default
kiro-cli agent create my-agent --directory .kiro/agents

# 编辑 Agent
kiro-cli agent edit my-agent

# 验证配置
kiro-cli agent validate --path .kiro/agents/my-agent.json

# 设置默认 Agent
kiro-cli agent set-default my-agent

聊天会话

# 启动聊天
kiro-cli chat

# 使用指定 Agent 和模型
kiro-cli chat --agent vue-dev --model <model-id>

# 信任所有工具（无需确认）
kiro-cli chat --trust-all-tools

# 信任特定工具
kiro-cli chat --trust-tools=read,grep,code

# 恢复上次会话
kiro-cli chat --resume

# 选择会话恢复
kiro-cli chat --resume-picker

# 无头模式（自动化）
kiro-cli chat --no-interactive --trust-all-tools "运行测试并汇总结果"

# 设置推理强度
kiro-cli chat --effort high "Review this code"

TUI 内斜杠命令

/settings              打开设置菜单
/settings display      显示设置（动画、ASCII、图标）
/settings theme        主题设置
/settings terminal     终端多行输入配置
/settings history      历史记录范围

/agent                 列出/切换 Agent
/agent create          创建新 Agent
/agent edit            编辑当前 Agent

/model                 切换模型
/tools                 查看可用工具
/hooks                 查看当前 Hook 配置
/context               查看上下文窗口使用情况
/context show          显示上下文文件详情
/context add <path>    添加临时上下文文件

/code init             初始化代码智能
/code init -f          强制重新初始化
/code status           查看 LSP 状态
/code overview         代码库概览

/mcp                   查看 MCP 服务器状态
/mcp add               添加 MCP 服务器
/mcp remove            移除 MCP 服务器

/chat save             保存当前会话
/chat load             加载历史会话

/guide                 切换到帮助 Agent
/help                  查看所有斜杠命令

快速上手：为当前项目配置 Kiro CLI

步骤 1：创建工作区配置目录

mkdir -p .kiro/agents .kiro/steering .kiro/skills

步骤 2：创建项目 Agent

创建 .kiro/agents/project-dev.json：

{
  "name": "project-dev",
  "description": "FranklinWH ToolBox 项目开发助手",
  "prompt": "你是一个 Vue 3 + TypeScript + Naive UI 项目的开发助手。项目使用 Vite 构建，pnpm 管理依赖，UnoCSS 编写样式。",
  "tools": ["read", "write", "shell", "grep", "glob", "code", "web_fetch"],
  "allowedTools": ["read", "grep", "glob", "code"],
  "toolsSettings": {
    "shell": {
      "allowedCommands": ["pnpm", "npx", "git (status|diff|log|branch)"],
      "autoAllowReadonly": true
    },
    "write": {
      "deniedPaths": ["node_modules/**", "dist/**"]
    }
  },
  "resources": [
    "file://src/**/*.vue",
    "file://src/**/*.ts",
    "file://package.json"
  ],
  "hooks": {
    "agentSpawn": [
      { "command": "git branch --show-current" }
    ]
  }
}

步骤 3：添加引导文件

创建 .kiro/steering/project-rules.md：

# 项目规范

- 使用 Vue 3 Composition API + <script setup>
- UI 库：Naive UI
- 样式：UnoCSS 原子类
- 工具函数库：es-toolkit
- 日期处理：dayjs
- 图表：@antv/g2 和 uplot
- 包管理器：pnpm（使用 pnpm@10）

步骤 4：设为默认 Agent

kiro-cli settings chat.defaultAgent project-dev

本文档基于 Kiro CLI 官方文档整理，配置项可能随版本更新而变化。使用 kiro-cli settings list --all 查看当前版本支持的所有设置。

kiro-cli-configuration-guide.md 44 KB Historie Surový

Kiro CLI 运行环境配置详细指南

目录

1. 配置体系概览

2. 目录结构

全局目录 ~/.kiro/

工作区目录 .kiro/（项目根目录下）

项目根目录其他配置文件

3. 全局设置 (cli.json)

文件位置

完整设置项列表

3.1 Chat 聊天相关

3.2 快捷键

3.3 遥测

3.4 知识库

3.5 API

3.6 MCP

3.7 上下文压缩

3.8 Hooks

cli.json 完整示例

4. Agent 配置

文件位置

所有字段说明

内置工具列表

tools 与 allowedTools 的区别

allowedTools 通配符模式

toolsSettings 详细配置

write 工具设置

shell 工具设置

web_fetch 工具设置

resources 资源配置

默认资源继承

Agent 完整示例

5. Steering 文件（引导文件）

文件位置

加载规则

inclusion 控制

Steering 文件示例

6. Skills 技能文件

文件位置

格式要求

在 Agent 中引用 Skills

Skills 示例

7. Hooks 钩子系统

配置位置

触发时机

退出码含义

两种配置格式

Object 格式（推荐）

Array 格式

Matcher 匹配模式

Hook 收到的 STDIN 数据

环境变量

Hook 脚本示例

8. MCP 服务器配置

配置位置

三种服务器类型

8.1 本地 (stdio) 服务器

8.2 远程 (HTTP) 服务器

8.3 Registry 服务器

MCP 配置完整示例

9. LSP 代码智能配置

文件位置

初始化

预配置的语言服务器

自定义语言服务器

10. 环境变量

数据目录默认位置

日志文件默认位置

示例

11. 常用命令速查

设置管理

Agent 管理

聊天会话

TUI 内斜杠命令

快速上手：为当前项目配置 Kiro CLI

步骤 1：创建工作区配置目录

步骤 2：创建项目 Agent

步骤 3：添加引导文件

步骤 4：设为默认 Agent

kiro-cli-configuration-guide.md 44 KB

Historie Surový

全局目录 `~/.kiro/`

工作区目录 `.kiro/`（项目根目录下）