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保存本次执行记录。
• 预期结果：测试文件生成并在本机跑通；结果不满意时，看轨迹文件里哪一步偏了，改措辞重跑。

资源与性能的取舍

这一节回答"模型怎么选，参数怎么定"。

决策建议：先从中型模型起步。agent 频繁在多步推理上卡住就换更大；机器明显跑不动就换更小。另外max_tokens给够但不贪长，输出长不等于输出好。

故障速查

这一节回答"出问题时第一步该查什么"。

现在就动手

• 趁有网，先在一台常备机器上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