Trae CLI 调研与接入方案

> 调研日期：2026-07-20 > 官方文档：https://docs.trae.cn/cli

---

一、Trae CLI 是什么？

TRAE CLI 是 TRAE 官方推出的命令行 AI 编程智能体（Code Agent），定位为终端原生的 AI 开发助手。只需在终端输入自然语言指令，即可让它完成从代码编写、测试到 Git 操作等一系列开发任务。

它和 TRAE IDE、TRAE Work 是独立产品，但共享同一套 Skill/MCP/规则/记忆体系。

核心能力

产品优势

• 开箱即用：安装简单，cd 到项目目录直接启动
• 高度可扩展：支持自定义 Agent、自定义斜杠命令、自定义 Skill、自定义 MCP
• 非交互模式：支持 -p 参数在 CI/CD 脚本中调用
• Worktree 隔离：-w 参数在隔离 Git worktree 中执行任务

---

二、使用限制（重要！）

> ⚠️ 仅 TRAE CN 企业版旗舰版套餐客户可使用 TRAE CLI。 > > 默认使用 Max 模式，注意用量消耗。

这是一个关键门槛——需要企业旗舰版账号才能使用。如果个人用户，暂时无法使用。

---

三、安装与快速开始

3.1 系统要求

3.2 安装命令

macOS & Linux:

sh -c "$(curl -L https://trae.cn/trae-cli/install.sh)" && export PATH=~/.local/bin:$PATH

Windows (PowerShell):

irm https://trae.cn/trae-cli/install.ps1 | iex

3.3 启动

cd /your/project
traecli

首次启动会唤起浏览器进行企业账号登录授权。

3.4 升级

traecli update   # 手动升级
# 也支持自动升级（启动时检测）

---

四、核心功能详解

4.1 斜杠命令（Slash Commands）

自定义斜杠命令

在项目根目录创建 .traecli/commands/ 目录，放入 Markdown 文件即可。例如创建 .traecli/commands/deploy.md：

---
description: Deploy service to target environment
argument-hint: <service-name> <environment>
tools: Read,Bash
model: kimi-k2
---

## Deploy Request

Service: $1
Environment: ${2:-staging}

Current git status: !`git status --short`

## Task
Deploy $1 to $2 environment following the project's deployment SOP.

支持变量：$ARGUMENTS（全部参数）、$1/$2/...（位置参数）、${N:-default}（默认值）、` !command （执行命令并插入输出）。

通过 /agent-new 或手动在 .traecli/agents/ 创建 Markdown 文件定义领域专属 Agent，例如专门写测试的 Agent、专门写前端的 Agent。

调用方式：在对话中 @agent-name 指定使用某个智能体，CLI 也会自动拆分任务给合适的 Agent。

• 项目级 Skill：.traecli/skills/<skill-name>/SKILL.md
• 全局 Skill：~/.traecli/skills/<skill-name>/SKILL.md
• 兼容 IDE 目录：自动读取 .trae/skills/（项目级）和 ~/.trae-cn/skills/（全局）

对本项目的意义：我们现有的 .trae/skills/ 目录下的所有 Skill（brainstorming、executing-plans 等）CLI 可以直接复用！

- CLI 自动加载当前目录及所有上级目录的 AGENTS.md - 下级目录的 AGENTS.md 在读取该目录文件时才加载 - 兼容 IDE 根目录的 AGENTS.md

- 项目规则：.trae/rules/（我们现有的 superpowers.md 可以直接被读取！） - 全局规则：~/.trae-cn/rules/

对本项目的意义：我们现有的 .trae/rules/superpowers.md 和 .claude/CLAUDE.md 等项目知识，CLI 可以直接加载使用！

支持 stdio、SSE、Streamable HTTP 三种传输协议，配置在 trae_cli.yaml 的 mcp_servers 中。

• 兼容 IDE 的项目级 MCP：自动读取 .trae/mcp.json

启动时可用 -y / --yolo 参数快速进入无授权模式。

• 内置模型通过 /model 切换
• 自定义模型（OpenAI/Claude 兼容）在 trae_cli.yaml 的 models 中配置
• 运行时可通过 -c model.name=xxx 动态切换

# 单次执行模式：打印响应并退出
traecli -p "解释这个项目的架构"

# 指定允许的工具（跳过授权确认）
traecli --allowed-tool Bash,Edit,Write -p "运行所有测试并修复失败用例"

# JSON 格式完整输出（含工具调用过程）
traecli --json -p "..."

# 在隔离 worktree 中执行
traecli -w -p "实现 xxx 功能"

# 会话恢复
traecli --resume <session-id>

• 在企业版控制台生成令牌（格式：trae-lt-xxx）
• 通过环境变量登录：

`bash TRAECLI_PERSONAL_ACCESS_TOKEN="trae-lt-xxx" traecli -p "..." `

• macOS: ~/Library/Application Support/trae_cli/trae_cli.yaml
• Linux: ~/.config/trae_cli/trae_cli.yaml（或 $XDG_CONFIG_HOME）
• Windows: %USERPROFILE%\AppData\Roaming\trae_cli\trae_cli.yaml

编辑命令：traecli config edit

permission_mode: default          # 权限模式

models:                           # 自定义模型
  - name: "my-gpt"
    open_ai:
      base_url: https://xxx
      api_key: "sk-xxx"
      model: "gpt-4.1"

mcp_servers:                      # MCP Server
  - name: "my-tool"
    type: stdio
    command: "/path/to/tool"

allowed_tools:                    # 全局允许的工具
  - Bash
  - Edit
  - Write

disallowed_tools:                 # 全局禁用的工具
  - Bash(rm -rf /)

sh -c "$(curl -L https://trae.cn/trae-cli/install.sh)" && export PATH=~/.local/bin:$PATH

cd /Users/aohan/PycharmProjects/adata
traecli
# 登录后执行
/init    # 生成 AGENTS.md

将 .claude/CLAUDE.md 中的核心内容（项目速览、目录结构、开发铁律、部署命令、沙箱避坑指南等）迁移/引用到 AGENTS.md，确保 CLI 了解项目约束。

/skills   # 查看是否识别了 .trae/skills/ 下的所有 Skill

检查所有 SKILL.md 的 name 字段，确保不含中文字符。如果有中文 name，CLI 会退回到目录名，需修复。

如果需要在 CLI 中也使用 Chrome DevTools、Computer Use 等 MCP 工具，需要在全局 trae_cli.yaml 中配置。

在 .traecli/commands/ 下创建项目专用命令，例如：

• /restart-web：重启网站服务（env -u PYTHONHOME -u PYTHONPATH bash restart.sh）
• /run-backtest：运行回测
• /check-data：检查数据新鲜度
• /deploy：通过 Cloudflare Tunnel 发布

• 权限安全：默认模式下写操作（Edit/Write/Bash非只读）需要手动确认；使用 YOLO 模式（-y）要谨慎
• Python 环境：CLI 的 Bash 执行环境可能需要手动激活 venv（source .venv/bin/activate），或在 AGENTS.md 中说明
• 成本：默认 Max 模式，Token 消耗较大，注意企业版额度
• 沙箱差异：CLI 直接运行在本地终端，不像 IDE 有沙箱隔离，可以直接操作文件系统、执行任意命令——能力更强但风险也更高
• Git worktree：做实验性改动时建议用 -w 参数在隔离 worktree 中执行，避免搞乱主分支