你有没有遇到过这种情况：给 Claude Code Agent 一个看似简单的任务，比如“修复这个项目的测试失败”，结果它开始疯狂读取文件、运行命令、修改代码，一轮接一轮地循环执行，最后要么成功修复，要么因为超出预算或轮次限制而中断？这种“自主循环”正是 Claude Code Agent 的核心能力，但很多人第一次接触时，往往会被它的运行方式搞糊涂。

更让人困惑的是，Claude Code Agent 实际上支持四种不同的运行方式，从最简单的单次 Prompt 响应，到完全自主的多轮 Loop 循环，每种方式对应着不同的控制粒度、适用场景和工程化复杂度。如果你只是把 Agent 当作一个“更聪明的命令行工具”来用，很可能只触及其能力的冰山一角。

今天，我们就来彻底拆解 Claude Code Agent 的四种运行方式，帮你理解从“一次提问”到“自主循环”的完整光谱。无论你是想快速验证一个想法，还是构建一个能长期运行的生产级 AI 代理，这篇文章都会给你清晰的路径。

1. 先搞清楚：Agent 的“循环”到底是什么？

在深入四种运行方式之前，我们必须先理解 Claude Code Agent 最核心的概念：代理循环（Agent Loop）。很多人误以为 Agent 只是“一个能执行命令的 AI”，但实际上，它的核心价值在于能够自主决策、采取行动、观察结果，并基于结果调整策略——这一整套流程就是代理循环。

1.1 代理循环的基本工作流程

一个完整的代理循环包含以下几个关键步骤：

1. 接收提示：Claude 接收你的初始提示，同时加载系统提示、工具定义和对话历史。SDK 会产生一个SystemMessage，标志着会话开始。

2. 评估并响应：Claude 分析当前状态，决定下一步行动。它可能直接返回文本响应，也可能请求调用一个或多个工具。SDK 会产生AssistantMessage，包含文本内容和工具调用请求。

3. 执行工具：SDK 执行被请求的工具，并收集执行结果。你可以通过 hooks 在工具运行前进行拦截、修改或阻止。

4. 重复循环：步骤 2 和 3 会不断重复，每个完整的“请求-响应-执行”循环称为一个轮次（turn）。Claude 持续调用工具并处理结果，直到产生不含工具调用的最终响应。

5. 返回结果：SDK 产生最终的AssistantMessage（纯文本响应），然后是ResultMessage，包含最终文本、令牌使用量、成本和会话 ID。

1.2 轮次与预算：循环的控制机制

理解轮次的概念至关重要。一个简单的查询（"这里有什么文件？"）可能只需要 1-2 个轮次，调用Glob工具后直接返回结果。而复杂的任务（"重构认证模块并更新测试"）可能涉及数十个轮次，Claude 会读取文件、编辑代码、运行测试，并根据每个结果调整策略。

你可以通过两个关键参数控制循环：

• 最大轮次（max_turns）：限制工具使用的往返次数。例如，设置max_turns=10会在第 10 个工具调用轮次后强制停止。
• 最大预算（max_budget_usd）：基于成本阈值停止循环。当累计成本超过设定值时，代理会立即终止。

如果没有这些限制，代理会一直运行直到 Claude 自行判断任务完成。这对于范围明确的任务很有效，但对于开放式提示（如"改进这个代码库"）可能导致长时间运行。在生产环境中，设置合理的预算是明智的选择。

2. 四种运行方式：从简单到复杂的完整光谱

现在我们来具体分析 Claude Code Agent 的四种主要运行方式。每种方式都对应不同的控制粒度和适用场景，理解它们的区别能帮助你在不同需求下做出正确选择。

2.1 方式一：单次查询（One-shot Query）

这是最简单直接的用法，适合快速验证和简单任务。

核心特征：

• 单轮交互：输入提示，获取最终结果
• 自动工具调用：Agent 自主决定是否需要以及如何使用工具
• 有限控制：主要通过提示词和基础参数进行约束

典型代码示例：

from claude_agent_sdk import query async def simple_query(): async for message in query(prompt="列出当前目录下的所有 .py 文件"): if message.type == "result" and message.subtype == "success": print(f"结果: {message.result}")

适用场景：

• 文件查找、内容搜索等简单操作
• 快速原型验证和概念测试
• 不需要复杂交互的一次性任务

局限性：

• 无法在运行过程中进行干预
• 不适合需要多轮复杂决策的任务
• 错误处理能力有限

2.2 方式二：流式会话（Streaming Session）

这种方式提供了实时交互能力，让你能够观察代理的思考过程和执行进度。

核心特征：

• 实时消息流：可以观察到每个轮次的详细执行过程
• 中间状态可见：能看到工具调用、执行结果等中间步骤
• 可中断性：在某些情况下可以中断执行

典型代码示例：

async def streaming_session(): async for message in query( prompt="分析这个项目的依赖关系并建议优化", options={"include_partial_messages": True} # 启用流式消息 ): if message.type == "assistant": print(f"Claude 正在执行: {message.content}") elif message.type == "user": # 工具执行结果 print(f"工具返回: {message.content}") elif message.type == "result": print(f"最终结果: {message.result}")

适用场景：

• 需要监控复杂任务执行过程的场景
• 调试和问题诊断
• 教育演示和理解 Agent 工作原理

优势：

• 提供完整的可观测性
• 有助于理解 Agent 的决策逻辑
• 便于及时发现问题并进行干预

2.3 方式三：受控循环（Controlled Loop）

这是最常用的生产级用法，在自主性和控制性之间取得平衡。

核心特征：

• 精细权限控制：通过工具权限列表控制 Agent 能做什么
• 预算和轮次限制：防止无限循环和成本超支
• hooks 机制：在关键执行点插入自定义逻辑

典型配置示例：

from claude_agent_sdk import ClaudeAgentOptions options = ClaudeAgentOptions( allowed_tools=["Read", "Glob", "Grep"], # 只允许读取操作 disallowed_tools=["Edit", "Write", "Bash"], # 禁止修改操作 max_turns=20, max_budget_usd=1.0, # 最大预算1美元 effort="medium", permission_mode="default" )

权限控制详解：

Claude Code Agent 提供了多层次的权限控制机制：

1. 允许工具列表（allowed_tools）：列出的工具会被自动批准，无需人工干预。这对于创建只读代理特别有用。

2. 禁止工具列表（disallowed_tools）：无论其他设置如何，这些工具都会被完全阻止。

3. 权限模式（permission_mode）：控制未被明确允许或禁止的工具的处理方式：

   • "default"：需要人工批准
   • "acceptEdits"：自动批准文件编辑和常见文件系统命令
   • "plan"：Claude 只规划不执行实际修改
   • "dontAsk"：完全自主运行，但受工具列表限制

适用场景：

• 生产环境中的自动化任务
• 需要平衡效率和安全性的场景
• 团队协作中的权限管理

2.4 方式四：完全自主循环（Fully Autonomous Loop）

这是最 advanced 的用法，Agent 在设定的边界内完全自主运行。

核心特征：

• 最小人工干预：Agent 自主决策和执行
• 长期运行能力：支持会话恢复和连续性
• 复杂任务处理：能够处理需要多步骤协作的任务

高级功能：

1. 会话连续性：

# 保存会话ID以便后续恢复 session_id = None async for message in query(prompt="开始一个长期任务"): if message.type == "system" and message.subtype == "init": session_id = message.session_id # 稍后恢复会话 async for message in query( prompt="继续之前的任务", options={"session_id": session_id} ): # 处理消息

2. 子代理协调： 对于复杂任务，可以使用子代理将工作分解：

# 主代理创建子代理处理特定子任务 options = ClaudeAgentOptions( tools=["Agent"] # 启用子代理功能 )

3. 上下文管理： 长时间运行的任务需要有效的上下文管理：

• 自动压缩：当上下文接近限制时自动总结旧历史
• 手动压缩：通过/compact命令主动触发压缩
• 子代理隔离：每个子代理有独立上下文，避免主上下文膨胀

适用场景：

• 复杂的代码重构任务
• 长期的项目维护工作
• 需要高度自主性的自动化流程

3. 选择策略：如何根据需求匹配合适的运行方式

了解了四种运行方式后，最关键的问题是：在什么情况下应该选择哪种方式？下面是一个实用的决策框架。

3.1 基于任务复杂度的选择

简单查询任务→单次查询

• 任务特征：明确、单一、结果导向
• 示例：文件查找、内容搜索、简单代码分析
• 选择理由：快速、简单、资源消耗少

中等复杂度任务→流式会话或受控循环

• 任务特征：需要多步骤执行，但逻辑相对清晰
• 示例：代码质量检查、依赖分析、测试执行
• 选择理由：需要一定程度的监控和控制，但不需要完全自主

高复杂度任务→受控循环或完全自主循环

• 任务特征：开放式、多维度、需要适应性策略
• 示例：代码重构、系统架构优化、复杂bug修复
• 选择理由：需要Agent的自主决策能力，同时要控制风险和成本

3.2 基于安全要求的选择

高安全要求→受控循环（严格权限）

• 使用allowed_tools严格限制工具访问
• 设置较低的预算和轮次限制
• 启用工具批准回调进行人工审核

中等安全要求→受控循环（宽松权限）

• 使用acceptEdits模式自动批准安全操作
• 设置合理的预算监控
• 通过hooks进行审计和日志记录

低安全要求/隔离环境→完全自主循环

• 在容器或沙箱环境中运行
• 使用bypassPermissions模式最大化效率
• 确保有有效的回滚和恢复机制

3.3 基于工程化成熟度的选择

初期探索阶段→单次查询或流式会话

• 重点：理解Agent能力和限制
• 策略：从小任务开始，逐步增加复杂度
• 工具：简单脚本和交互式测试

中期集成阶段→受控循环

• 重点：将Agent集成到现有工作流
• 策略：定义清晰的接口和边界
• 工具：配置管理、权限控制、监控告警

成熟生产阶段→完全自主循环

• 重点：最大化自动化价值
• 策略：建立完整的运维体系
• 工具：会话管理、成本控制、错误处理、性能优化

4. 实战建议：避免常见陷阱的最佳实践

无论选择哪种运行方式，都有一些通用的最佳实践可以帮助你避免常见陷阱。

4.1 环境准备和配置管理

项目级配置： 在项目根目录创建CLAUDE.md文件，定义Agent的行为准则：

# 项目指导原则 ## 代码风格 - 使用4空格缩进 - 遵循项目现有的命名约定 - 优先使用async/await而非回调 ## 测试要求 - 所有修改必须包含测试 - 保持测试覆盖率不降低 - 运行完整测试套件 before 提交 ## 总结指令 当压缩对话时，请保留： - 当前任务目标和验收标准 - 已读取或修改的文件路径 - 测试结果和错误信息 - 已做出的决策及其理由

工具权限配置： 根据最小权限原则配置工具访问：

# 只读代理配置 readonly_agent = ClaudeAgentOptions( allowed_tools=["Read", "Glob", "Grep", "WebSearch"], disallowed_tools=["Edit", "Write", "Bash"], permission_mode="dontAsk" ) # 开发代理配置 dev_agent = ClaudeAgentOptions( allowed_tools=["Read", "Edit", "Bash", "Glob"], permission_mode="acceptEdits", max_turns=50, max_budget_usd=5.0 )

4.2 成本控制和性能优化

effort级别选择： 根据任务复杂度选择合适的推理深度：

• "low"：文件查找、目录列表等简单任务
• "medium"：常规编辑、标准代码任务
• "high"：重构、调试等复杂任务
• "xhigh"：深度编码和代理任务（推荐用于复杂场景）

上下文管理策略：

• 使用子代理分解长任务，避免主上下文膨胀
• 定期压缩对话历史，释放上下文空间
• 选择性加载工具，减少不必要的上下文开销

4.3 错误处理和恢复机制

健壮的错误处理：

async def robust_agent_execution(prompt, options): try: async for message in query(prompt=prompt, options=options): if message.type == "result": if message.subtype == "success": return {"status": "success", "result": message.result} else: return {"status": message.subtype, "session_id": message.session_id} except Exception as e: return {"status": "error", "error": str(e)}

会话恢复策略：

async def resume_session(session_id, new_prompt): """恢复中断的会话""" async for message in query( prompt=new_prompt, options={"session_id": session_id, "max_turns": 100} # 增加轮次限制 ): # 处理消息流 pass

4.4 监控和可观测性

基础监控指标：

• 轮次计数和成本统计
• 工具使用频率和模式
• 会话持续时间和完成状态

高级可观测性：

• 使用OpenTelemetry集成
• 自定义hooks记录详细日志
• 实时流式传输监控仪表板

5. 从实验到生产：构建可持续的Agent工作流

将Claude Code Agent从实验工具转变为生产系统需要系统性的方法。以下是关键的实施阶段和建议。

5.1 阶段一：能力验证（1-2周）

目标：验证Agent在特定任务上的有效性活动：

• 选择2-3个代表性任务进行测试
• 比较人工执行和Agent执行的效率差异
• 评估结果质量和一致性

交付物：

• 任务成功率统计
• 成本效益初步分析
• 风险识别清单

5.2 阶段二：流程集成（2-4周）

目标：将Agent集成到现有开发流程活动：

• 定义清晰的接口规范
• 建立权限控制和审计机制
• 创建标准化配置模板

交付物：

• 集成架构文档
• 配置管理方案
• 团队培训材料

5.3 阶段三：规模化运营（4-8周）

目标：建立可持续的Agent运营体系活动：

• 实现自动化部署和监控
• 建立成本控制和优化机制
• 制定故障恢复和升级流程

交付物：

• 生产就位的Agent系统
• 运维手册和SOP
• 性能基线和服务等级协议

5.4 持续优化循环

建立基于数据的持续优化机制：

# 简单的性能追踪框架 class AgentPerformanceTracker: def __init__(self): self.metrics = { 'success_rate': [], 'avg_cost': [], 'avg_turns': [], 'common_errors': [] } def record_session(self, result_message): self.metrics['success_rate'].append(result_message.subtype == 'success') if result_message.total_cost_usd: self.metrics['avg_cost'].append(result_message.total_cost_usd) self.metrics['avg_turns'].append(result_message.num_turns)

通过定期分析这些指标，你可以识别优化机会，比如调整effort级别、优化提示词设计、改进工具配置等。

Claude Code Agent 的四种运行方式构成了一个完整的能力光谱，从简单的单次查询到复杂的自主循环。选择合适的方式不仅取决于技术复杂度，更需要考虑团队成熟度、安全要求和业务价值。最重要的是记住：Agent 不是要完全替代人工，而是通过人机协作最大化整体效率。开始小规模验证，逐步建立信心，最终构建出真正为你所用的智能编码伙伴。