AI Agent / 系统课时
使用非交互模式
使用非交互模式
非交互模式适合脚本、批处理和 CI 中的一次性任务。本课使用 claude -p 执行只读代码分析,并通过模型、轮次、工具集合和权限模式建立可预测的运行边界。
学习目标
- 使用打印模式执行一次性任务并读取退出结果
- 区分工具可用范围与免确认权限
- 设置模型、最大轮次和输出格式
理解打印模式
claude -p 接收提示词,完成任务后把结果写到标准输出并退出。它不会像交互会话那样等待后续输入,因此提示词必须一次写清任务对象、输出要求和禁止事项。
非交互运行最常见的风险不是“回答不够好”,而是工具权限过宽、任务没有停止边界,或输出不便被脚本判断。应把控制参数写进命令,而不是只依赖自然语言承诺。
执行只读分析
下面的命令只允许读取、搜索和匹配文件,不允许编辑文件或执行 Shell。--max-turns 3 限制代理循环,--permission-mode plan 要求以计划方式运行,--output-format text 便于人直接阅读。
# 通过工具白名单把本次任务限制为只读分析
claude -p \
"检查当前仓库的身份认证模块,指出三个最重要的安全风险。引用文件路径和行号,不要修改文件。" \
--model sonnet \
--max-turns 3 \
--permission-mode plan \
--tools "Read,Grep,Glob" \
--output-format text预期输出
<READ_ONLY_SECURITY_ANALYSIS_WITH_FILE_REFERENCES>实际分析内容取决于仓库。若命令因达到轮次上限退出,应缩小检查范围或适当增加轮次,而不是直接取消所有限制。
分清 --tools 与 --allowedTools
--tools 决定 Claude 能看到并使用哪些内置工具,是能力边界。设置为 "Read,Grep,Glob" 后,编辑和 Bash 工具根本不可用。
--allowedTools 只表示匹配的工具调用可以免去权限询问,并不会自动隐藏其他工具。自动化环境中,若目标是最小权限,应先用 --tools 缩小工具集合,再按需要配置免确认规则。以下两种配置意义不同:
--tools "Read,Grep,Glob"
--allowedTools "Read" "Grep" "Glob"第一行限制能力,第二行降低确认频率。不要把 --dangerously-skip-permissions 当作解决 CI 卡住的默认方案,它只适合经过隔离、无敏感凭据且可随时销毁的环境。
控制成本与终止条件
--max-turns 控制代理工具往返次数,适合防止简单任务不断扩展。还可以使用预算参数限制 API 花费,但预算到达后任务可能在中途停止,因此脚本必须检查退出码和输出是否完整。
模型别名适合跟随当前默认版本;固定模型 ID 适合需要可复现行为的受控流水线。无论选择哪种方式,都应把模型配置写进日志,便于复盘结果差异。
让脚本正确判断结果
打印模式成功不代表业务结论一定正确。脚本至少应检查三层:进程退出码是否为零、输出是否存在、输出是否满足预期结构。自由文本适合人工阅读,机器消费应改用下一课的 JSON 或结构化输出。
常见失败处理
命令长时间运行时,先检查任务是否允许 Bash、是否在扫描过大的目录、轮次是否过高。出现权限错误时,应补充精确工具规则,而不是整体绕过权限。输出过长时,应要求固定条数、指定目录或返回摘要加证据。