Kiro CLI 使用三个退出码：0（成功）、1（通用失败）、3（MCP 服务器启动失败）。退出码 3 需要配合 --require-mcp-startup 参数触发，适用于 MCP 工具对任务不可缺少的 CI/CD 场景。除主程序退出码外，Hooks 系统还使用独立的退出码语义（0/2/其他），用于控制工具执行的放行或拦截。本文提供 Bash 脚本和 CI/CD 配置示例，帮助你在自动化流程中可靠处理各种退出状态。

退出码速查

代码	名称	说明
0	Success	命令执行成功
1	Failure	通用失败（认证错误、参数无效、操作失败等）
3	MCP Startup Failure	MCP 服务器启动失败（需配合 --require-mcp-startup 使用）

强制要求 MCP 服务器就绪

默认情况下，MCP 服务器启动失败只会记录为警告，不影响退出码。当你的任务依赖 MCP 工具时，加上 --require-mcp-startup 可快速失败：

kiro-cli chat --require-mcp-startup --no-interactive "Run task"

若任何已配置的 MCP 服务器启动失败，CLI 立即以退出码 3 退出。

脚本处理示例

Bash 脚本

#!/bin/bash
kiro-cli chat --require-mcp-startup --no-interactive --trust-all-tools "Run analysis"
exit_code=$?

case $exit_code in
    0) echo "Success" ;;
    3) echo "MCP servers failed to start"; exit 1 ;;
    *) echo "Failed with code $exit_code"; exit $exit_code ;;
esac

CI/CD 流水线（GitHub Actions 示例）

- name: Run Kiro task
  run: |
    kiro-cli chat --require-mcp-startup --no-interactive --trust-all-tools "Analyze code"
  continue-on-error: false

Hooks 退出码

Hooks 使用独立的退出码语义，用于控制工具执行：

代码	行为
0	Hook 执行成功，继续后续流程
2	（仅 PreToolUse）拦截工具执行；STDERR 内容返回给 LLM
其他	Hook 失败；STDERR 内容作为警告显示

退出码 2 是 Hooks 最关键的机制之一：当 PreToolUse Hook 以 2 退出时，Kiro 会将 STDERR 的内容原样传回给 LLM，使其能感知拦截原因并调整策略。

最佳实践

• 在 CI/CD 中使用 MCP 工具时，始终加上 --require-mcp-startup，避免 MCP 服务器静默失败导致任务以错误数据完成
• 调试退出码问题时，配合 -v 或 -vv 开启详细日志
• 在脚本中显式检查退出码，不要依赖 shell 的隐式行为
• 将 MCP 启动失败（代码 3）和通用失败（代码 1）分别处理，以便向用户提供更清晰的错误信息

常见问题

Q：什么情况下会返回退出码 1，而不是退出码 3？

A：退出码 1 是通用失败，涵盖认证错误（未登录）、命令参数无效、任务执行过程中发生的错误等。退出码 3 专门表示 MCP 服务器启动失败，且必须配合 --require-mcp-startup 参数才会触发；如果不加这个参数，MCP 启动失败只会打印警告，整体命令仍以 0 退出（或视任务结果而定）。

Q：在 Hook 中如何用退出码 2 向 LLM 传递拦截原因？

A：在 PreToolUse Hook 脚本中，将拦截原因写入 STDERR，然后以 exit 2 退出。例如：echo "危险操作：目标路径包含生产数据" >&2; exit 2。Kiro 会把这段 STDERR 文本原封不动地传回 LLM，LLM 会据此调整行动策略。

Q：脚本中如何区分"Kiro 任务执行失败"和"MCP 服务器未就绪"？

A：加上 --require-mcp-startup 参数后，退出码 3 专门标识 MCP 问题；退出码 1 则表示任务本身失败。可以在 case 语句或 if [ $? -eq 3 ] 中分别处理，3 时检查 MCP 配置，1 时检查任务输入或权限。