Trae Agent 参数调优实战

【免费下载链接】trae-agentTrae Agent is an LLM-based agent for general purpose software engineering tasks.项目地址: https://gitcode.com/gh_mirrors/tr/trae-agent

Trae Agent 跑着跑着报exceeded maximum steps，或同一任务连跑三次输出几乎一字不差——多半是 max_steps 和 temperature 没设对：前者管 Agent 还能走多少步，后者管输出有多少变化空间。

参数速查卡：默认值先记下来

先记住默认值，后面的讨论都围绕它展开。

max_steps 管的是"还能再走几轮"

源码里是怎么数步骤的

Agent 每走一步就向模型发一轮请求；一轮里可以顺带调用若干工具，但步数只加一。计数的地方在 trae_agent/agent/base_agent.py 的执行循环：

while step_number <= self._max_steps: step = AgentStep(step_number=step_number, state=AgentStepState.THINKING) messages = await self._run_llm_step(step, messages, execution) if execution.agent_state == AgentState.COMPLETED: break step_number += 1

跑满预算还没成功，收尾判定会直接判负：

if step_number > self._max_steps and not execution.success: execution.final_result = "Task execution exceeded maximum steps without completion."

这就是终端那句报错的来源，也是"跑到一半停了"的全部原因。

不同体量的任务给多少步

• 单文件改动（修一个函数、改一处配置）：给 10~15 步。读文件、改动、验证三五轮就够，给多了只是留了乱跑的空间。
• 多模块联调（新增跨文件功能、补齐测试）：给 30~50 步。默认的 20 步常常不够，因为定位、改动、验证、返工每一轮只挪一小步。
• 部署流水线级的大改（搭脚手架、多阶段验证）：60 起步，按需放到 100 以上。步数随环节数线性上涨，token 开销也跟着涨。

步数给多了会怎么翻车

一种是绕圈：Agent 反复执行同一条报错的命令、来回读同一个文件；另一种是注水：任务早已完成，它还在"补充优化"。排查思路比较固定——打开轨迹文件看agent_steps的最后几段：若 tool_calls 在重复，问题多半在任务描述缺了关键信息，加步数没用；若每一步都在推进只是没走完，再加 20~30 步通常就够。

temperature 调高之后输出会有什么变化

temperature 怎么透传到模型 API

配置里的值会原样进 API 请求。以 OpenAI 客户端为例（trae_agent/utils/llm_clients/openai_client.py）：

return self.client.responses.create( model=model_config.model, temperature=model_config.temperature if "o3" not in model_config.model else openai.NOT_GIVEN, )

留意这行条件：o3、o4-mini、gpt-5 这类推理模型不接受该参数，请求里会被跳过——对它们调 temperature 没有效果。Anthropic、Google 等客户端则是直接透传。

低、中、高值各适合什么活

• 0.1~0.3：确定性强、答案唯一的活，比如按模板批量生成配置文件，要的是每次输出都长一样。
• 0.5（默认值）：日常改 bug、写功能，稳定为主，允许少量措辞变化。
• 0.7~0.9：需要模型自己找路径的活，比如"给这个慢查询想出三种优化方案"，低温度下它容易反复给出同一种写法。

两个参数都要动时先动哪个

先定 max_steps，再动 temperature。步数是预算，温度是预算内的花钱方式：预算不够时把温度调高，Agent 只能探索到一半就被掐断，留下一堆半成品；预算充足时温度再高，也有完整的轮次兜底。反过来，步数给得很大、温度也拉高，最常见的结果就是绕圈加烧钱。所以一次只动一个，动完拿同一个任务跑两遍对比轨迹。

参数写进去的三种途径，谁压谁

CLI 一行搞定 max_steps：

trae-cli run --max-steps 40 "重构配置模块并补上单元测试"

环境变量层面，常用的是指定配置文件位置和注入密钥：

export TRAE_CONFIG_FILE=~/trae/trae_config.yaml

配置文件以 trae_config.yaml.example 为模板，在本地工作目录建一份 trae_config.yaml：agents.trae_agent下写max_steps，models对应模型下写temperature。官方示例文件里 max_steps 直接给了 200。temperature 目前没有独立的 CLI 开关，走配置文件；max_steps 两者皆可，冲突时 CLI 赢。

裁决规则由 trae_agent/utils/config.py 里的 resolve_config_value 统一处理：

def resolve_config_value( *, cli_value: int | str | float | None, config_value: int | str | float | None, env_var: str | None = None, ) -> int | str | float | None: """Resolve configuration value with priority: CLI > ENV > Config > Default."""

也就是 CLI > 环境变量 > 配置文件 > 默认值。环境变量这一层目前主要承接 TRAE_CONFIG_FILE 和ANTHROPIC_API_KEY之类的密钥，max_steps 的解析并未接 env_var。

调不动时按三步排查

1. 看轨迹：带--trajectory-file run1.json跑一次，打开 JSON 数agent_steps的长度，对照文件里的max_steps字段——正好顶到上限，就是步数问题。轨迹格式详见 docs/TRAJECTORY_RECORDING.md。
2. 确认生效：trae-cli show-config会打印 Max Steps 和 Temperature 的实际取值，防止你以为改的是 A 份配置、程序实际读的是 B 份。
3. 换路再试：仍不稳定就换--model换一家模型对比，或把 top_p 与 temperature 联动微调——不同模型对温度的敏感度差很多。

max_steps 和 temperature 没有银弹：先判断任务要走几轮，再看输出稳不稳，就知道该拧哪颗旋钮。遇到代码没覆盖到的行为，去仓库的 issues 和 docs 目录继续提问。

【免费下载链接】trae-agentTrae Agent is an LLM-based agent for general purpose software engineering tasks.项目地址: https://gitcode.com/gh_mirrors/tr/trae-agent