Trae Agent 离线模式：不联网也能跑通 Agent 的三步教程
【免费下载链接】trae-agentTrae Agent is an LLM-based agent for general purpose software engineering tasks.项目地址: https://gitcode.com/gh_mirrors/tr/trae-agent
公司内网与外网完全隔离，但你当天就得在机器上修完一个 bug。这个教程就以这个场景为例，带你走通 Trae Agent 离线模式：用 Ollama 接入本机模型，让 agent 全程无网络请求地完成开发任务。🛠️
这套方案能做什么
这一节回答"什么时候该用这套方案，什么时候别硬用"。
能做什么
- 把 Trae Agent 接到本机模型上。它通过 ollama_client.py 与本机 11434 端口的 Ollama 服务通信，请求不出机器。
- 工具调用全部本地执行：bash 执行命令、编辑文件、修改 JSON、用 task_done 收尾。工具细节见 docs/tools.md。
- 代码和提示词都不外发，适合对代码隐私敏感的项目。
适合谁
- 内网隔离环境、出差途中、偏远地区等断网场景
- 不想把敏感项目交给云端 API 的开发者
不适合谁
- 多步推理、大规模重构：本地中小模型的能力上限明显低于云端的旗舰模型
- 需要 MCP（让 agent 连接外部服务的工具协议）调用外部资源的任务
- 对一次成功率要求极高的生产流程
先认清边界，再动手，能省掉后面大量的调参时间。
从零跑通：三步实操
这一节回答"如何从零走到第一个离线任务，并且每一步都能验证"。
好处先说：三步都在终端完成，做完即闭环，全程不需要外网。
第一步：装好项目本体
好处：一次装齐依赖，后续不用再手动解决导入报错。
git clone https://gitcode.com/gh_mirrors/tr/trae-agent cd trae-agent uv sync --all-extras source .venv/bin/activate验证：执行trae-cli show-config。能打印出默认配置且不报错，说明环境就绪。
第二步：把模型服务跑在本机
好处：模型下载一次即可，之后推理完全不依赖互联网。
Ollama 是一个本地模型管理工具，负责下载模型并对外暴露本地 API。没装过就先按官网说明安装（有一键脚本），然后拉模型、起服务：
ollama pull qwen3 ollama serve验证：再开一个终端执行ollama list，能看到 qwen3 就说明模型就位；ollama serve保持运行，默认监听 11434 端口。
第三步：写离线配置，跑第一个任务
好处：配置写一次，之后所有离线任务直接复用，不用重复传参数。
把 trae_config.yaml.example 复制为trae_config.yaml，只改与模型相关的字段：
model_providers: ollama: api_key: ollama provider: ollama base_url: http://localhost:11434/v1 models: offline_model: model_provider: ollama model: qwen3两个注意点：api_key填ollama是 Ollama 约定的占位值，不是真实密钥。如果不用 Lakeview（每步生成一句话进度摘要的功能），把 agents 段里的enable_lakeview设为 false，省得为它再配一个模型。
然后对任意目录跑一个真实任务：
trae-cli run "写一个 Python 脚本输出前 10 个斐波那契数" --working-dir ~/demo验证：输出里能看到 agent 调用编辑和 bash 工具，最后以 Task done 收尾；trajectories/目录下多了一个执行轨迹文件（记录每一步动作的 JSON），闭环成立。
跑通后的自检清单
这一节回答"它真的跑通了，还是某个环节悄悄断了"。
trae-cli show-config显示的 provider 是 ollama，模型名与配置一致ollama list有对应模型，且ollama serve进程还在- 一个真实任务完整跑完，日志里没有连接超时、DNS 解析失败等网络报错
- trajectories/ 下生成了轨迹文件，里面能看到工具调用和模型回复，可对照 docs/TRAJECTORY_RECORDING.md 解读
- 配置里只启用了本地工具，没有挂任何需要外网的服务
五条都打勾，才可以把真实任务交给它。
典型工作场景
这一节回答"跑通之后，哪些活儿值得放进来做"。
内网隔离环境的应急修复
- 背景：客户现场的测试机连不上外网，线上模块抛异常，需要当场修。
- 做法：
--working-dir指向项目根目录，用trae-cli run下达一句话任务，例如"修复 utils.py 的空指针并补一个最小复现测试"。 - 预期结果：agent 用编辑工具读改代码、用 bash 跑测试验证后收尾，全程零外网流量。
出差途中的持续重构
- 背景：高铁上改代码，信号时断时续，云端 API 一断线就报错。
- 做法：
trae-cli interactive用本地模型开交互模式，需求逐条说，agent 逐条改。 - 预期结果：体验接近在线版；到站恢复网络后，用命令行参数切回云端模型即可。
新仓库批量补测试
- 背景：新接手仓库没有文档和测试，想先把单元测试补齐。
- 做法：任务写成"为 utils 模块写单元测试并保证全部通过"，加
--trajectory-file保存本次执行记录。 - 预期结果：测试文件生成并在本机跑通；结果不满意时，看轨迹文件里哪一步偏了，改措辞重跑。
资源与性能的取舍
这一节回答"模型怎么选，参数怎么定"。
| 选项 | 资源消耗 | 能力 | 什么时候选 |
|---|---|---|---|
| 4B 以下小模型 | 内存轻、响应快 | 简单脚本、局部小改动 | 机器配置低，任务重复且简单 |
| 7B~14B 中型模型 | 内存中等 | 覆盖大多数日常开发任务 | 默认选择，建议 16GB 内存起步 |
| 30B 以上大模型 | 内存高，无 GPU 时很慢 | 多步推理、较大范围重构 | 有 GPU，任务确实复杂 |
| 云端大模型（对照） | 需要联网 | 目前最强 | 网络可用时切回去 |
决策建议：先从中型模型起步。agent 频繁在多步推理上卡住就换更大；机器明显跑不动就换更小。另外max_tokens给够但不贪长，输出长不等于输出好。
故障速查
这一节回答"出问题时第一步该查什么"。
| 现象 | 可能原因 | 处理动作 |
|---|---|---|
trae-cli提示命令不存在 | 虚拟环境没激活 | 改用uv run trae-cli ...，或先source .venv/bin/activate |
| 连接超时或被拒绝 | Ollama 服务没启动 | 执行ollama serve，确认 11434 端口在监听 |
| 报模型不存在 | 模型没拉取，或配置里的名字对不上 | 用ollama list查实际名字，与trae_config.yaml对齐 |
| 工具调用失败、任务中断 | --working-dir路径不对或缺项目依赖 | 确认路径真实存在，重新跑一次uv sync --all-extras |
现在就动手
- 趁有网，先在一台常备机器上
ollama pull一个中型模型，之后离线随用随取。 - 复制
trae_config.yaml.example为离线配置，只改 ollama 相关字段，别整文件重写。 - 用斐波那契这种小任务验证闭环，再逐步把真实开发任务交出去。
模型搬进本机那一刻，网络就不再是瓶颈，离线只是 Trae Agent 的一种默认运行方式。💪
【免费下载链接】trae-agentTrae Agent is an LLM-based agent for general purpose software engineering tasks.项目地址: https://gitcode.com/gh_mirrors/tr/trae-agent
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
