概述

--max-turns 标志允许您限制非交互模式中代理的轮数（对话轮次）。这对于控制执行时间、资源使用和防止无限循环非常有用。

基本语法

claude --max-turns <数字>

参数说明

使用场景

1. 限制执行时间

# 限制代理最多执行 5 轮
claude --max-turns 5 -p "分析项目中的所有文件"
# 代理会在 5 轮后停止，即使任务未完成

2. 控制资源使用

# 限制轮数以控制 API 调用次数
claude --max-turns 10 -p "生成完整的测试套件"
# 避免过多的 API 调用和资源消耗

3. 防止无限循环

# 防止代理陷入无限循环
claude --max-turns 3 -p "递归处理所有子目录"
# 即使代理尝试继续，也会在 3 轮后停止

4. 快速原型开发

# 快速获取初步结果
claude --max-turns 2 -p "设计系统架构"
# 获取初步想法，不进行深入分析

高级用法

1. 与其他标志组合

# 限制轮数 + 指定模型
claude --max-turns 5 --model opus -p "生成代码"

# 限制轮数 + 限制工具
claude --max-turns 3 --allowedTools "Read" "Grep" -p "搜索代码"

# 限制轮数 + JSON 输出
claude --max-turns 10 --output-format json -p "分析数据"

2. 渐进式执行

#!/bin/bash
# progressive-execution.sh
# 第一轮：快速分析
echo "第一轮：快速分析"
claude --max-turns 1 -p "分析项目结构" > analysis-round1.txt
# 第二轮：深入分析
echo "第二轮：深入分析"
claude --max-turns 2 -p "基于初步分析，深入分析代码" > analysis-round2.txt
# 第三轮：生成建议
echo "第三轮：生成建议"
claude --max-turns 3 -p "基于分析结果，生成改进建议" > suggestions.txt
echo "渐进式执行完成"

3. 动态调整轮数

#!/bin/bash
# dynamic-turns.sh

# 根据任务复杂度动态调整轮数
TASK=$1

case "$TASK" in
    "simple")
        MAX_TURNS=2
        ;;
    "medium")
        MAX_TURNS=5
        ;;
    "complex")
        MAX_TURNS=10
        ;;
    *)
        MAX_TURNS=3
        ;;
esac

echo "执行任务: $TASK (最大轮数: $MAX_TURNS)"
claude --max-turns "$MAX_TURNS" -p "完成这个任务"

4. 超时控制

#!/bin/bash
# timeout-control.sh
MAX_TURNS=5
TIMEOUT=60
# 使用 timeout 命令限制总时间
timeout "$TIMEOUT" claude --max-turns "$MAX_TURNS" -p "生成代码"
if [ $? -eq 124 ]; then
echo "任务超时"
else
echo "任务完成"
fi

实际应用示例

示例 1: 代码审查

#!/bin/bash
# code-review.sh

FILE=$1

# 第一轮：快速审查
echo "快速审查..."
claude --max-turns 2 -p "快速审查 $FILE 的代码质量" > quick-review.txt

# 第二轮：详细审查
echo "详细审查..."
claude --max-turns 5 -p "详细审查 $FILE，包括安全性、性能和可维护性" > detailed-review.txt

# 第三轮：生成修复建议
echo "生成修复建议..."
claude --max-turns 3 -p "基于审查结果，生成具体的修复建议" > fixes.txt

echo "代码审查完成"

示例 2: 文档生成

#!/bin/bash
# generate-docs.sh
# 第一轮：生成大纲
echo "生成大纲..."
claude --max-turns 2 -p "为项目生成文档大纲" > outline.md
# 第二轮：生成内容
echo "生成内容..."
claude --max-turns 10 -p "基于大纲，生成完整的文档内容" > docs.md
# 第三轮：完善文档
echo "完善文档..."
claude --max-turns 3 -p "完善文档，添加示例和说明" > final-docs.md
echo "文档生成完成"

示例 3: 测试生成

#!/bin/bash
# generate-tests.sh

# 第一轮：分析代码
echo "分析代码..."
claude --max-turns 3 -p "分析 src/ 目录下的代码结构" > analysis.txt

# 第二轮：生成测试用例
echo "生成测试用例..."
claude --max-turns 5 -p "基于分析结果，生成测试用例" > test-cases.txt

# 第三轮：生成测试代码
echo "生成测试代码..."
claude --max-turns 10 -p "将测试用例转换为 pytest 代码" > tests.py

echo "测试生成完成"

示例 4: 重构代码

#!/bin/bash
# refactor-code.sh
FILE=$1
# 第一轮：分析问题
echo "分析问题..."
claude --max-turns 2 -p "分析 $FILE 中的代码问题" > problems.txt
# 第二轮：设计重构方案
echo "设计重构方案..."
claude --max-turns 3 -p "设计重构方案" > refactor-plan.txt
# 第三轮：执行重构
echo "执行重构..."
claude --max-turns 10 -p "执行重构，生成重构后的代码" > refactored-code.py
echo "重构完成"

轮数选择建议

1. 简单任务：1-2 轮

# 简单查询
claude --max-turns 1 -p "解释什么是递归"

# 快速检查
claude --max-turns 2 -p "检查代码语法"

2. 中等任务：3-5 轮

# 代码审查
claude --max-turns 3 -p "审查代码质量"
# 文档生成
claude --max-turns 5 -p "生成 API 文档"

3. 复杂任务：6-10 轮

# 完整功能开发
claude --max-turns 10 -p "开发一个 REST API"

# 系统设计
claude --max-turns 8 -p "设计微服务架构"

4. 非常复杂的任务：10+ 轮

# 大型项目重构
claude --max-turns 15 -p "重构整个项目"
# 完整测试套件生成
claude --max-turns 20 -p "为整个项目生成测试"

最佳实践

1. 从小轮数开始

# 先用小轮数测试
claude --max-turns 2 -p "生成代码"

# 如果需要，增加轮数
claude --max-turns 5 -p "生成代码"

2. 监控执行进度

#!/bin/bash
# monitor-progress.sh
MAX_TURNS=5
for i in $(seq 1 $MAX_TURNS); do
echo "轮次 $i/$MAX_TURNS"
claude --max-turns 1 -p "继续任务" > "turn-$i.txt"
# 检查是否完成
if grep -q "完成" "turn-$i.txt"; then
echo "任务已完成"
break
fi
done

3. 保存中间结果

#!/bin/bash
# save-intermediate.sh

MAX_TURNS=5

for i in $(seq 1 $MAX_TURNS); do
    claude --max-turns 1 -p "继续任务" > "intermediate-$i.txt"

    # 检查是否需要继续
    if [ $? -ne 0 ]; then
        echo "任务失败"
        break
    fi
done

4. 错误处理

#!/bin/bash
# error-handling.sh
MAX_TURNS=5
claude --max-turns "$MAX_TURNS" -p "生成代码" 2>&1 | tee output.txt
# 检查是否达到最大轮数
if grep -q "max turns" output.txt; then
echo "警告：达到最大轮数，任务可能未完成"
fi

常见问题

Q1: 如何选择合适的轮数？

A: 根据任务复杂度选择。简单任务 1-2 轮，中等任务 3-5 轮，复杂任务 6-10 轮。

Q2: 达到最大轮数后会发生什么？

A: 代理会停止执行，即使任务未完成。建议检查输出并决定是否增加轮数。

Q3: 可以在交互模式中使用吗？

A: 不可以。--max-turns 只适用于非交互模式（使用 -p 标志）。

Q4: 如何知道任务是否完成？

A: 检查输出中是否包含完成指示，或者根据输出内容判断。

Q5: 轮数限制会影响结果质量吗？

A: 可能会。如果轮数太少，任务可能无法完成。建议根据任务复杂度选择合适的轮数。

与其他标志的组合示例

与其他标志的组合示例

1. 完整的开发流程

#!/bin/bash
# full-development.sh

# 分析阶段
claude --max-turns 3 -p "分析需求" > analysis.txt

# 设计阶段
claude --max-turns 5 -p "设计系统架构" > design.txt

# 实现阶段
claude --max-turns 10 -p "实现功能" > implementation.txt

# 测试阶段
claude --max-turns 5 -p "生成测试" > tests.txt

echo "开发流程完成"

2. 迭代优化

#!/bin/bash
# iterative-optimization.sh
for i in 1 2 3; do
echo "迭代 $i"
claude --max-turns 3 -p "优化代码" > "optimization-$i.txt"
# 检查是否需要继续
if grep -q "无需优化" "optimization-$i.txt"; then
echo "优化完成"
break
fi
done

3. 分阶段执行

#!/bin/bash
# staged-execution.sh

# 阶段 1：快速原型
claude --max-turns 2 -p "创建快速原型" > prototype.txt

# 阶段 2：完善功能
claude --max-turns 5 -p "完善原型功能" > refined.txt

# 阶段 3：最终实现
claude --max-turns 10 -p "实现最终版本" > final.txt

echo "分阶段执行完成"

总结

--max-turns 标志提供了一种控制非交互模式中代理执行轮数的方式。通过使用此标志，您可以：

• 限制执行时间和资源使用
• 防止无限循环
• 实现渐进式执行
• 控制成本和效率

合理使用 --max-turns 可以帮助您更好地控制代理行为，特别是在需要限制执行时间或资源的场景中。

上一页6.12 --verbose - 启用详细日志记录

下一页6.14 --model - 设置会话模型