Kiro API Key及Headless模式使用

一、背景

Kiro-CLI在本机完成登陆后，可使用Kiro-CLI chat --no-interactive命令提交后台任务，不过这样做的前提是当前环境已经进行了Kiro-CLI的认证。这是当前已经被广泛使用的后台任务调用方式。

如果在本机启动多个临时环境（例如容器），在其中运行多个Kiro-CLI副本的时候，提前进行登陆是复杂不便的，需要一种方式无需登陆，直接启动任务。此时可使用Kiro API Key完成身份认证，并以Headless方式执行任务。

本特性需要Kiro-CLI版本2.0或更高版本，并且Kiro API Key仅针对企业SSO订阅用户，个人使用Github/Google账号登陆的不可用。同时，还需要企业后台订阅开启这一功能，允许用户自行创建API Key。

二、在企业订阅后台开启API Key

进入Kiro服务后台，点击左侧菜单Settings按钮。在右侧的Kiro settings菜单下，找到API keys设置，点击Enable users to generate and use API keys。如下截图。

需要注意的是，本选项对所有人生效，只要开启后，被SSO认证下的所有用户都可以使用这个功能。

后台配置完成。

三、用户创建属于自己账户的API Key

访问 https://app.kiro.dev/ 网址。点击Your Organization选项进行企业认证登陆。如下截图。

输入企业SSO的Start URL和Region。此信息可通过执行kiro-cli whoami命令查看，或者查看您的登陆说明。如下截图。

输入用户信息登陆（或者是SSO自动跳转）。如下截图。

登陆成功后，来到当前用户自己的Kiro服务页面，点击API Keys菜单展开，输入名称，点击Create Key生成新Key。如下截图。

API Key生成完毕。将其复制下来。如下截图。

接下来在运行环境上配置。

四、在运行环境上配置并执行

在Linux/MacOS上：

export KIRO_API_KEY=ksk_xxxxxxxx
kiro-cli chat --trust-all-tools --no-interactive "your prompt here"

在Windows上：

$env:KIRO_API_KEY = "ksk_xxxxxxxx"
kiro-cli chat --trust-all-tools --no-interactive "your prompt here"

即可让Kiro以Headless方式执行特定任务。

注意: 一些Kiro Tools在Kiro的default agent下运行Headless模式（即non-interactive mode）下不可用，例如web_search。因此您需要组合--trust-all-tools和-no-interactive这两个参数。

五、创建Custom Agent专门用于Headless调用

例如使用mykiro作为agent名称，首先创建一个agent配置文件，执行如下命令编辑：

vim ~/.kiro/agents/mykiro.json

在配置文件中指定模型版本、指定AGENTS.md加载路径，指定Steering文件加载路径、指定Skill加载路径。样本内容如下：

{
  "name": "mykiro",
  "description": "Full-featured agent with all built-in tools and MCP servers, auto-trusted for seamless usage",
  "model": "claude-opus-4.6",
  "tools": ["*"],
  "allowedTools": ["*","@*"],
  "includeMcpJson": true,
  "resources": [
    "file:///Users/your-username/AGENTS.md",
    "file:///Users/your-username/.kiro/steering/**/*.md",
    "skill:///Users/your-username/.kiro/skills/**/SKILL.md",
    "file://AGENTS.md",
    "file://.kiro/steering/**/*.md",
    "skill://.kiro/skills/**/SKILL.md"
  ]
}

保存退出。执行如下命令设置为默认agent。

kiro-cli agent set-default --name mykiro

调用时候指定Agent名称：

kiro-cli chat --agent mykiro --trust-all-tools --no-interactive "your prompt here"

六、参考文档

Kiro Headless mode

Kiro Authenticate with an API key (headless mode)

最后修改于 2026-04-22