完整上手 Trae Agent：从克隆仓库到看懂它如何执行任务

完整上手 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 是一个基于 LLM 的通用软件开发任务 CLI 代理，你用一句自然语言下达指令，它会自动调用文件编辑、bash、思考等工具去完成改代码、跑命令、排错误这类工作；读完这篇 Trae Agent 入门，你能从零克隆仓库、配好一份可用配置，并看懂一次任务从规划、工具调用到留痕的完整执行过程。

它和其他闭源 CLI 工具的一个区别在于：每执行一步都会写进轨迹文件，方便你事后复现和排查，这对调试和做消融实验都很实用。

三分钟跑起来：从克隆仓库到跑通一个任务

这一节把系统要求、依赖安装和最小配置合并成一条连续动线，等价于一份 Trae Agent 安装教程。先确认前置条件：Python 3.12+和UV；Docker 只在后面做容器化执行时才需要。

按下面顺序执行即可：

# 1) 安装 UV（已有可跳过） curl -LsSf https://astral.sh/uv/install.sh | sh # 2) 克隆仓库并进入 git clone https://gitcode.com/gh_mirrors/tr/trae-agent cd trae-agent # 3) 建虚拟环境并激活 uv sync --all-extras source .venv/bin/activate # 4) 由示例生成你的配置文件 cp trae_config.yaml.example trae_config.yaml # 5) 填好密钥后跑第一个任务 trae-cli run "Create a hello world Python script"

配置文件trae_config.yaml只有三块需要关注，Trae Agent 怎么配置基本就是填对这三块：

• model_providers：登记 API 密钥，按你要用的提供商填，例如anthropic/openai/doubao。
• models：定义一个模型名，写明它用哪个 provider、模型名、max_tokens、temperature。
• agents.trae_agent：把上面定义的模型绑给代理，设置max_steps步骤上限和tools工具列表。

最小可用的模型绑定长这样（agents块省略，结构见下）：

model_providers: anthropic: api_key: your_anthropic_api_key provider: anthropic models: trae_agent_model: model_provider: anthropic model: claude-sonnet-4-20250514 max_tokens: 4096 temperature: 0.5

agents.trae_agent下通常再写model: trae_agent_model、max_steps: 200，以及一个tools列表（如bash、str_replace_based_edit_tool、sequentialthinking、task_done）。🔑 想先确认密钥和参数是否被正确读取，运行trae-cli show-config，它会把当前生效的 provider、模型、max_tokens 等以表格打印出来。

第一条命令跑通后，终端里会给出工作目录和轨迹文件位置：

Using current directory as working directory: /path/to/your/project Trajectory saved to: trajectories/trajectory_20251103_145807.json

如果提示trae-cli命令找不到，改用uv run trae-cli run "..."即可，说明是虚拟环境没激活的问题。

看它怎么干活：一次任务的规划、调用与留痕

拿上面那句 "Create a hello world Python script" 当线索，看一次任务内部发生了什么。代理每一步都会切换状态：thinking（让 LLM 分析并规划）→calling_tool（真正调用工具）→ 拿到结果后再回到thinking判断下一步，直到通过task_done标记完成，状态机定义见 agent 基础类。

整个过程大致是这样一条循环：

两点值得留意：

• 每一步都留痕。所有 LLM 交互、工具调用与结果都会实时写进轨迹文件，默认存到trajectories/trajectory_YYYYMMDD_HHMMSS.json；用--trajectory-file my_session.json可自定义文件名。轨迹格式（agent_steps、tool_calls、tool_results、token 用量等字段）在 docs/TRAJECTORY_RECORDING.md 里有逐字段说明。
• 步骤摘要。配置里enable_lakeview: true会启用 Lakeview，对每一步给出一句简短概括，长任务时更容易跟上代理到底在做什么。

所以「执行一个任务」对 Trae Agent 而言不是黑盒：规划、调用、留痕三段都看得见、可回放。

认识工具箱：五个内置工具怎么用

代理能改文件、跑命令，靠的是这几个内置工具，源码都在 trae_agent/tools/。下面每个只讲关键点加一个参数示例，细节可查 docs/tools.md。

• str_replace_based_edit_tool— 文件和目录操作，支持view/create/str_replace/insert四种动作。注意它要求绝对路径，且str_replace的匹配串必须唯一、含空白完全一致。关键参数：command: create、path: /repo/hello.py。
• bash— 在持久会话里执行 shell 命令，会话状态跨命令保留，单条命令120 秒超时；长任务用&放后台，需要重置会话时传restart: true。关键参数：command: "uv run pytest"。
• sequentialthinking— 把复杂问题拆成有序思考步骤，可修订、可分支，适合先想清楚再动手的分析类任务。关键参数：thought、total_thoughts。
• task_done— 无参数，用于标记任务完成；约定在真正验证通过后才调用，避免「假完成」。
• json_edit_tool— 用 JSONPath 精确改 JSON 文件，支持view/set/add/remove。关键参数：json_path: $.config.database.host。

说明：配置文件tools列表里写的是注册表名，例如顺序思考工具写作sequentialthinking（无下划线）。

进阶玩法：容器化执行与多 LLM 切换

跑稍复杂的任务时，两个能力最常用：给代理指定工作目录并留一份自定义轨迹，以及在不同 LLM 提供商之间切换。

复杂任务示例——带工作目录、自定义轨迹，并可强制生成补丁：

trae-cli run "为 utils 模块补全单元测试并修复失败用例" \ --working-dir /abs/path/to/project \ --trajectory-file add_tests.json

--working-dir必须是绝对路径，否则会被拒绝；需要交互界面时加--console-type rich。

Trae Agent 容器化执行——把任务放进 Docker，避免污染本机环境。下面四个 Docker 选项互斥，一次只能用其一：

任务结束默认保留容器，加--docker-keep false可在完成后删除。

多 LLM 切换——用--provider/--model覆盖配置，无需改文件，常用组合（模型名取自项目 README 的示例）：

比如临时换模型跑一次：trae-cli run "Review this code" --provider openrouter --model "openai/gpt-4o"。

避坑手册：常见症状对照解法

⚠️ 遇到问题先对号入座，多数是配置或环境问题，而非代理本身：

大多数情况下，trae-cli show-config加上打开轨迹文件看tool_results里的错误信息，就能定位到具体是哪一步、哪个工具出错的。

相关资源

• 工具与参数说明：docs/tools.md
• 轨迹文件字段详解：docs/TRAJECTORY_RECORDING.md
• 路线图与参与贡献：docs/roadmap.md、CONTRIBUTING.md
• 技术报告：arXiv:2507.23370

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