完整上手 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-agentTrae Agent 是一个基于 LLM 的通用软件开发任务 CLI 代理你用一句自然语言下达指令它会自动调用文件编辑、bash、思考等工具去完成改代码、跑命令、排错误这类工作读完这篇 Trae Agent 入门你能从零克隆仓库、配好一份可用配置并看懂一次任务从规划、工具调用到留痕的完整执行过程。它和其他闭源 CLI 工具的一个区别在于每执行一步都会写进轨迹文件方便你事后复现和排查这对调试和做消融实验都很实用。三分钟跑起来从克隆仓库到跑通一个任务这一节把系统要求、依赖安装和最小配置合并成一条连续动线等价于一份 Trae Agent 安装教程。先确认前置条件Python 3.12和UVDocker 只在后面做容器化执行时才需要。按下面顺序执行即可# 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.5agents.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-image python:3.12用镜像起新容器可再配--working-dir挂载目录--docker-container-id id附着到已存在的容器此时--working-dir无效--dockerfile-path path用绝对路径指向的 Dockerfile 现场构建环境--docker-image-file tar从本地 tar 镜像包加载任务结束默认保留容器加--docker-keep false可在完成后删除。多 LLM 切换——用--provider/--model覆盖配置无需改文件常用组合模型名取自项目 README 的示例provider示例模型常见用途openaigpt-4o通用开发anthropicclaude-sonnet-4-20250514长上下文、复杂分析googlegemini-2.5-flash多模态任务openrouteropenai/gpt-4o、anthropic/claude-3-5-sonnet一个入口聚合多家doubaodoubao-seed-1.6国内访问、中文场景ollamaqwen3本地模型、数据不外发比如临时换模型跑一次trae-cli run Review this code --provider openrouter --model openai/gpt-4o。避坑手册常见症状对照解法⚠️ 遇到问题先对号入座多数是配置或环境问题而非代理本身症状排查方向解法trae-cli: command not found虚拟环境未激活改用uv run trae-cli run ...或先source .venv/bin/activateImport / Module 相关报错未从仓库根目录运行前缀加PYTHONPATH. trae-cli run ...提示 Config file not found找不到配置文件用--config-file指定或设环境变量TRAE_CONFIG_FILE默认读trae_config.yamlAPI 密钥无效 / 401密钥未生效或填错trae-cli show-config看密钥是否被识别再核对对应 provider 的 keymodel not found模型名 / provider / 权限核对models里的模型名与该 provider 是否支持确认密钥有访问权限--working-dir被拒绝传了相对路径换成以/开头的绝对路径任务卡住 / 步数过多缺步骤上限加--max-steps 30interactive默认 20run未指定时读配置里的max_stepsbash 命令中途被断单条命令超 120 秒用放后台或拆分命令YAML 解析报错缩进用了 Tab配置里只用空格缩进不要用\tDocker 报错守护进程未启动 / 无权限确认dockerCLI 与 daemon 都在运行且当前用户有权限大多数情况下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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考