Trae Agent 离线模式上手：Ollama 本地模型部署与 3 步跑通教程

Trae Agent 离线模式上手：Ollama 本地模型部署与 3 步跑通教程

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

航班上、偏远机房里、隧道施工现场——外网一断，很多工程师的工作就停摆了。Trae Agent 离线模式解决的就是这个问题：把推理交给你机器上的本地模型，工具仍在本地执行，整个任务不依赖任何云端 API。读完这篇，你能做到：

• 本地跑模型：用 Ollama 拉起一个本地模型，让 Trae Agent 指向它
• 3 步验证：装环境、拉模型、跑通第一个无网任务
• 独立干活：在断网环境下修 bug、查故障、重构代码

先跑起来：最短路径验证离线环境

不用读完原理，先让环境转起来。一共 3 条命令。

git clone https://gitcode.com/gh_mirrors/tr/trae-agent cd trae-agent && uv sync --all-extras source .venv/bin/activate

然后在另一条终端里装好 Ollama 并拉一个模型（有网时下载好，之后离线用）：

ollama pull qwen3

把仓库里的trae_config.yaml.example复制成trae_config.yaml，改两处：model_providers里加一个provider: ollama的条目，models里model_provider指回它、model填qwen3。最后跑通第一句：

trae-cli run "给 utils 模块补一个测试" --working-dir /绝对路径/你的项目

看到它执行 bash 工具、写文件、最后打印Task done.，离线环境就通了。

硬件底线：

• 内存：16GB 起步，32GB 更稳
• CPU：8 核以上
• GPU：可选，NVIDIA 显卡能明显提速
• 磁盘：留 100GB 给模型缓存

软件清单：

• Python：3.12 及以上
• 包管理：uv
• 本地模型服务：Ollama（默认监听http://localhost:11434/v1）
• 系统：Linux 或 macOS 均可

底层怎么工作：模型与工具链如何配合

离线模式没有魔法，关键只有一条：所有推理都发生在你机器上的 Ollama 服务里，全程没有任何云端请求。

数据流大致是这一圈：

1. 你敲trae-cli run，CLI 读取 YAML 配置
2. LLMClient根据provider: ollama把请求转给 Ollama 客户端，默认走本地http://localhost:11434/v1
3. 模型返回"调用 bash 工具"的指令，Trae 在本机执行
4. 执行结果回灌给模型，进入下一轮，直到它调用task_done收尾

工具都是本地进程，由 tools 注册表统一管理，离线场景默认开这四个：

• bash：跑 Shell 命令，单条 120 秒超时
• str_replace_based_edit_tool：精确字符串替换改文件
• sequentialthinking：把复杂问题拆成步骤
• task_done：验证通过后才允许标记完成

另外，客户端内置随机退避重试（默认max_retries: 10），本地服务偶发抖动时它会自动等几秒再试，不用你盯着。

三类真实场景实战

场景一：航班上修线上 bug。任务明确、改动能小，用单次 run 最合适：

trae-cli run "修复 main.py 第 45 行空指针异常，并补一个复现用例" --working-dir /绝对路径/项目

预期：模型读文件、str_replace修掉空指针、写测试、跑 bash 验证，最后打印Task done.，轨迹存进trajectories/。

场景二：机房断网查故障。日志要反复看，用交互模式省去重复敲 run：

trae-cli interactive -p ollama -m qwen3

进去后输入status可确认当前模型，clear清屏，exit退出；直接把"分析 access.log 里 5xx 的共性"这类任务丢给它即可。

场景三：无网重构 + 补测试。改动面大，用--must-patch强制产出 patch 便于回看，再用--trajectory-file留一份完整记录：

trae-cli run "重构 config 模块并补齐单测" --working-dir /绝对路径/项目 --must-patch --trajectory-file refactor.json

预期：生成.patch文件 +refactor.json轨迹，两者都方便断网期间离线复查。

调优与避坑手册

启动就报连接错误。现象：Connection refused或超时。排查：先确认 Ollama 服务在跑、trae_config.yaml里没写错base_url。解决：ollama serve启动服务，或核对端口就是11434。

报模型不存在。现象：model not found。排查：ollama list看本地到底有哪些模型名。解决：把配置里的model改成完全一致的名字，别加多余前缀。

推理太慢。现象：一步要等几十秒。排查：看内存和 CPU 占用，判断是不是模型太大。解决：换 7B 左右的模型，或把max_tokens从 4096 降到 2048 压低单步开销。

模型不调工具、只会说废话。现象：一直输出文字，从不触发 bash。排查：确认所选模型支持 function calling。解决：换qwen3这类对工具调用支持较好的本地模型，别用纯文本小模型。

命令行找不到 trae-cli。现象：command not found。排查：是否激活了.venv。解决：用uv run trae-cli ...绕过环境问题，或重新source .venv/bin/activate。

一页速查

出发前检查清单

• 跑一遍ollama list，确认模型真的在本地
• trae_config.yaml里 provider 是ollama，model 名与本地完全一致
• 默认四个离线工具都在配置里，工作目录填的是绝对路径
• 先拿一个小任务试跑，确认能输出Task done.再上正事

断网时少一点慌乱，靠的就是这份提前备好的离线环境。把模型拉好、配置写好，剩下的就交给 trae-cli 了。

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