Headless 非交互模式接收一个任务，完成后输出结果并退出，适合 Shell、持续集成和持续交付 （CI/CD）、定时任务和后端作业。本文介绍提示词输入、输出格式、退出码和权限控制。
前提条件
已完成安装和配置 IaC Code。
已在交互环境中验证模型配置可用。Headless 不会启动认证向导。
查询云资源时，已配置只读阿里云权限；执行写操作时，已设计精确的权限规则。
快速开始
通过命令参数执行一次只读云资源查询：
iac-code --prompt "查询 cn-hangzhou 的 ROS 资源栈，汇总状态异常的资源栈，不要执行任何写操作"
预期结果：标准输出显示资源栈状态摘要，任务完成后进程退出。
从标准输入传入任务：
printf '%s\n' '检查当前目录的云资源方案，列出安全和费用风险，不要修改文件或云资源' \
| iac-code --prompt -
--prompt - 适合由文件、模板系统或上游命令生成提示词的场景。
选择输出格式
格式 |
参数 |
适用场景 |
文本，默认 |
|
直接显示给用户。 |
JSON |
|
调用方解析一个最终结果。 |
流式 JSON |
|
调用方增量处理文本、工具和状态事件。 |
获取最终 JSON：
iac-code \
--prompt "查询 cn-hangzhou 的 ROS 资源栈并输出状态摘要，不要执行任何写操作" \
--output-format json \
--max-turns 20 \
--permission-mode dont_ask
调用方应只从标准输出解析 JSON，并将标准错误作为诊断日志单独处理。
处理退出码
退出码 |
含义 |
|
任务正常完成。 |
|
配置、认证或执行过程中发生错误。 |
|
达到 |
自动化系统应同时检查结构化结果和退出码，并为 IaC Code 进程设置外部超时。
控制工具权限
Headless 无法弹出交互式审批。--permission-mode dont_ask 会拒绝原本需要询问的操作，适合只读查询和检查。需要写文件或管理云资源时，应通过 --allowed-tools 和
--disallowed-tools 精确约束命令或云 API。
例如，仅允许指定 ROS 写 API 的自动化任务，应使用对应工具的精确授权模式。不要仅为了消除审批而使用 bypass_permissions；如果确实使用该模式，仍需依赖运行环境隔离、RAM
最小权限、审计和人工变更门禁。
脚本示例
以下脚本将结构化结果写入构建产物目录，并保留 IaC Code 的退出码：
#!/usr/bin/env bash
set -u
mkdir -p build
if printf '%s\n' '查询 cn-hangzhou 的 ROS 资源栈，汇总异常状态，不要执行任何写操作' \
| iac-code --prompt - \
--output-format json \
--max-turns 20 \
--permission-mode dont_ask \
> build/iac-code-result.json; then
echo "IaC Code 查询完成"
else
status=$?
echo "IaC Code 查询失败，退出码：${status}" >&2
exit "${status}"
fi
常见问题
输出不是有效 JSON
确认使用 --output-format json，且调用方没有把标准错误合并进标准输出。需要增量事件时，
改用 stream-json 并按事件类型逐行解析。
任务因为权限被拒绝
检查任务是否需要写文件、执行命令或调用云上写 API。只读任务应明确“不执行写操作”； 写任务应由平台配置精确授权，不能等待 Headless 运行时询问用户。
任务提前达到最大轮数
查看当前结果和日志，判断任务是否可以拆小。确需更多步骤时提高 --max-turns，并同步调整外部超时和成本控制。
需要多轮会话或实时权限审批
普通的一次性 Headless 不适合这种场景。终端交互使用 REPL，浏览器交互使用 Web；IDE 或自定义客户端集成使用 ACP。长驻 JSON 子进程模式属于高级用法，请参见 GitHub 文档。