Kiro CLI 的 headless 模式允许你在没有交互式终端的情况下运行 agent，把代码审查、测试生成、构建失败分析接入 CI/CD。本文说明 KIRO_API_KEY、--no-interactive、工具信任参数和 MCP 启动检查的用法，并强调最小权限与密钥安全。

Kiro CLI headless：把 agent 接入 CI/CD 自动化

headless 模式让 Kiro CLI 可以在没有交互式终端的环境中运行，例如 GitHub Actions、GitLab CI、Jenkins 或公司内部流水线。你提供 API key 和 prompt，Kiro 就能端到端执行任务，不需要中途等待用户确认。

这类模式适合自动化代码审查、生成测试、解释构建失败、扫描 TODO 注释等任务。但也因为没有人在中途确认工具调用，所以权限边界必须提前设计好。

认证：使用 KIRO_API_KEY

headless 模式需要通过环境变量提供 API key：

export KIRO_API_KEY="your-api-key"

如果还没有 API key，请先参考 Generate an API key。如果你需要了解不同认证方式的优先级，可以查看 Authentication。

在 CI/CD 平台中，应该把 KIRO_API_KEY 放进 secret 管理功能里，例如 GitHub Actions Secrets、GitLab CI Variables 或 Jenkins Credentials。不要把 API key 写进仓库，也不要写进 pipeline 配置的明文字段。

基本命令

headless 的核心参数是 --no-interactive，并且必须把初始 prompt 作为参数传入：

kiro-cli chat --no-interactive "your prompt here"

因为没有交互式确认，涉及工具调用时还需要提前声明信任范围。

信任所有工具

kiro-cli chat --no-interactive --trust-all-tools "Write tests for the auth module and run them"

这适合一次性、隔离环境、权限可控的任务。但在真实 CI 里，不建议默认使用 --trust-all-tools，因为它会自动批准所有工具调用。

只信任特定工具类别

kiro-cli chat --no-interactive --trust-tools=read,grep "Find all TODO comments in src/"

更推荐这种方式。比如只做代码扫描时，只给 read 和 grep；需要生成测试时，再考虑是否开放 write；需要执行测试时，再开放 shell 或对应命令类别。

CI/CD 示例：GitHub Actions 中做代码审查

下面是一个 pull request 触发的示例：

name: Kiro Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Kiro CLI
        run: curl -fsSL https://cli.kiro.dev/install | bash
      - name: Review PR changes
        env:
          KIRO_API_KEY: ${{ secrets.KIRO_API_KEY }}
        run: kiro-cli chat --no-interactive --trust-tools=read,grep "Review the changes in this PR for security issues"

这个例子只授予 read 和 grep，因此更像“只读审查”。如果你希望 Kiro 自动修改代码，需要额外开放写入和命令执行权限，并配套分支隔离、diff 检查和人工 review。

更多自动化模式

生成并运行测试

kiro-cli chat --no-interactive --trust-all-tools "Write tests for the auth module and run them"

如果在 CI 中使用，建议改成更精细的权限配置，并确保运行在临时工作区。测试生成后最好把 diff 作为 artifact 或 PR comment 输出，避免无人审查的代码直接进入主分支。

分析构建失败

cat build-error.log | kiro-cli chat --no-interactive "Explain this build failure and suggest a fix"

这种用法很适合只读分析。你也可以把 git diff、测试日志、编译日志一起管道输入，让 Kiro 基于更完整的上下文判断问题。

依赖 MCP 的流水线

如果你的任务依赖 MCP server，例如数据库、内部文档或云服务工具，可以加上：

kiro-cli chat --no-interactive --require-mcp-startup "Run the release checklist"

--require-mcp-startup 会在 MCP server 连接失败时快速退出，避免流水线一直挂起或在缺少工具的情况下继续执行。失败处理可参考 Exit codes。

参数速查

参数	作用
--no-interactive	以非交互方式运行，必须提供初始 prompt
--trust-all-tools	自动批准所有工具调用
--trust-tools=<categories>	只自动批准指定工具类别，例如 read,grep,write
--require-mcp-startup	MCP server 无法连接时立即失败

安全建议

1. 把 KIRO_API_KEY 存在 CI/CD secret 中，不要硬编码。
2. 优先使用 --trust-tools，不要默认使用 --trust-all-tools。
3. 写权限和 shell 权限只在隔离分支或临时工作区中开放。
4. 对自动生成的代码保留人工 review，不要直接推送到主分支。
5. 使用 --require-mcp-startup 让依赖外部工具的流水线快速失败。
6. 定期轮换 API key，并在 Kiro portal 撤销不再使用的 key。
7. 在 pipeline 中处理 Exit codes，避免失败被误判为成功。

限制

headless 模式不是普通 chat session 的完全替代品，它有这些限制：

• 必须提供初始 prompt；
• 运行中不能等待用户补充输入；
• 交互式 slash commands 不可用，例如 /model picker、/agent picker；
• 终端 UI 功能会被禁用。

因此，headless 更适合“输入清晰、上下文可由文件或日志提供、输出可被脚本消费”的任务。

推荐落地方式

如果你刚开始接入，建议按下面顺序推进：

1. 先做只读任务，例如 PR 安全审查或构建日志解释。
2. 使用 --trust-tools=read,grep 限制工具范围。
3. 确认输出质量稳定后，再引入写文件或运行测试。
4. 所有自动修改都走独立分支和人工 review。
5. 最后再考虑让 Kiro 参与更复杂的 CI/CD 修复流程。

相关页面

• Authentication
• Exit codes
• CLI commands

常见问题

headless 模式可以在本地脚本里用吗？

可以。只要设置了 KIRO_API_KEY，本地 shell 脚本也可以用 kiro-cli chat --no-interactive。但仍然要谨慎授予工具权限。

什么时候可以使用 --trust-all-tools？

只建议在隔离、可回滚、权限明确的环境使用，例如临时容器或一次性分支。生产仓库和共享环境中更推荐 --trust-tools。

headless 模式能执行交互式 slash commands 吗？

不能。headless 没有中途交互能力，像 /model picker、/agent picker 这类依赖选择界面的命令不可用。