Trae-cli 是字节跳动开源的 AI 编程助手命令行工具。介绍在 macOS/Linux 环境下通过 uv 管理依赖并克隆仓库的方法，包含配置文件（JSON/YAML）设置 API 密钥及模型选择。核心功能涵盖自然语言指令执行、指定 LLM 提供商、强制生成代码补丁、Docker 模式交互及控制台类型配置。支持 OpenAI、Anthropic、Ollama 等多种模型接入，适用于自动化代码任务与 SWE-bench 评测场景。
本文使用的机器为 macOS，Linux 机器也可适用。
#前提条件
python --version #Python：3.12+
git --version #已安装 Git
cmake --version #已安装 cmake
Trae 没有直接公开 CLI，但在 GitHub 中发布了一个项目 Trae Agent，通过运行该项目可以使用 Trae CLI。
git clone https://github.com/bytedance/trae-agent
cd trae-agent
uv sync --all-extras
# 激活虚拟环境
source .venv/bin/activate # Linux/macOS
# 若为 Windows，使用：.venv\Scripts\activate
安装后可使用该命令验证
uv run python3 -m trae_agent.cli --help
# 过程中可能需要安装 docker 和 pexpect 库
uv pip install docker pexpect
使用 uv 因为有两套 python 环境：本地 conda 一套，项目本地 uv 环境一套，所以需要确保安装在 uv 环境中。
安装成功后如下所示。
命令行快捷方式设置：
# 设置配置文件路径，后续可直接使用 trae-cli 命令
export TRAE_CONFIG_FILE="your_trae_config.json"
# 建议添加到~/.bashrc 或~/.zshrc 中，永久生效
echo 'export TRAE_CONFIG_FILE="your_trae_config.json"' >> ~/.zshrc
source ~/.zshrc
Trae-agent 提供了两种格式的配置文件模板，位于项目根目录：
trae_config.json.example：JSON 格式（推荐）trae_config.yaml.example：YAML 格式
配置步骤
复制模板文件并重命名
cp trae_config.json.example trae_config.json
编辑配置文件，更换 API 密钥
{
"api_keys": {
"anthropic": "your_anthropic_api_key",
"openai": "your_openai_api_key",
"doubao": "your_doubao_api_key"
},
"default_provider": "anthropic",
"default_model": "claude-sonnet-4-20250514"
}
支持的模型目录
| 提供商 | 支持模型示例 | 备注 |
|---|---|---|
| OpenAI | gpt-4o | 需 OpenAI API 密钥 |
| Anthropic | claude-sonnet-4-20250514 | 默认推荐模型 |
| gemini-2.5-flash | 需 Google AI Studio 密钥 | |
| Azure | azure/gpt-4o | 需额外配置 endpoint 和 deployment |
| Ollama | llama3:8b, qwen3 | 本地模型，无需 API 密钥 |
| OpenRouter | openai/gpt-4o | 聚合 API 服务 |
| Doubao | doubao-seed-code-preview-251028 | 豆包代码模型 |
Trae-cli 的所有命令通过 trae-cli 执行，核心功能如下：
执行简单任务
# 直接输入自然语言指令，让 Agent 完成任务
trae-cli run "创建一个输出'Hello World'的 Python 脚本"
# 验证当前配置是否正确（API 密钥、模型参数等）
trae-cli show-config
# 进入对话式交互，支持多轮对话
trae-cli interactive
指定 LLM 提供商和模型（临时覆盖配置）
# 使用 Anthropic 的 Claude 模型
trae-cli run "优化这个排序算法" --provider anthropic --model claude-sonnet-4-20250514
# 使用本地 Ollama 模型（无需联网）
trae-cli run "注释这段 Python 代码" --provider ollama --model qwen3:7b
强制生成代码补丁
# 用于 patch 生成，确保任务结束时输出 Git 补丁
trae-cli run "更新用户认证 API 端点" --must-patch
高级用法技巧
# 方式 1：直接输入 prompt 命令
trae-cli run "编写一个 hello world 脚本，使用 Python 3.12 特性"
# 方式 2：读取文件中的文本命令（适合复杂任务描述）
trae-cli run --file task_description.txt
# 错误用法（会导致冲突）
# trae-cli run "任务描述" --file task.txt
自定义模型配置（覆盖配置文件）
# 自定义 model、api-key、model-base-url
trae-cli run "编写一个 hello world 脚本" \
--model doubao-seed-code-preview-251028 \
--model-base-url https://ark.cn-beijing.volces.com/api/v3 \
--api-key "your_doubao_api_key"
Docker 模式与补丁输出
# 执行需要 Docker 环境的任务
trae-cli run "将当前项目打包为 Docker 镜像并导出为 tar 文件" \
--docker-keep true # 任务完成后保留 Docker 容器
# 强制生成 Git 补丁（用于代码审查和版本控制）
trae-cli run "修复用户登录功能的 bug" --must-patch
控制台与 Agent 类型配置
# 使用 rich 控制台（更美观的输出格式）
trae-cli run "分析这个 Python 项目的依赖关系" --console-type rich
# 指定 Agent 类型（当前仅支持 trae_agent）
trae-cli run "生成单元测试" --agent-type trae_agent
运行 trae-cli 后模型输出结果会在当前目录文件下，trace 轨迹文件也就是模型思考记录会在 trajectories 文件中
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online