TronCode›Tron CLI›配置参考

配置参考

使用 JSON 配置文件定制 Tron 的行为

Tron 支持通过 JSON 或 JSONC（带注释的 JSON）配置文件进行全面定制。配置文件使用 Schema 验证，支持编辑器自动补全。

文件格式

推荐使用 tron.jsonc 格式，支持注释，便于说明配置意图：

tron.jsonc
{
  // Schema 提供编辑器自动补全和验证
  "$schema": "https://troncode.cn/config.json",
  // 界面主题
  "theme": "tron",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
}

配置位置

Tron 支持多个配置文件位置，它们按优先级顺序合并（而非替换）。低优先级配置中不冲突的设置会被保留。

ℹ️
注意
配置文件是合并的，而不是替换的。例如全局配置的 theme 和项目配置的 model 会同时生效。

优先级顺序

配置按以下顺序加载，后面的来源覆盖前面的冲突项：

  • 1
    远程配置 .well-known/tron
    组织级默认值，最低优先级
  • 2
    全局配置 ~/.config/tron/tron.json
    用户范围偏好：主题、供应商、快捷键
  • 3
    自定义配置 $TRON_CONFIG
    通过环境变量指定的自定义配置文件
  • 4
    项目配置 tron.json
    项目根目录配置，可提交到 Git
  • 5
    .tron/ 目录
    agents、commands、plugins 等本地扩展
  • 6
    内联配置 $TRON_CONFIG_CONTENT
    运行时覆盖，最高优先级

远程配置

组织可通过 .well-known/tron 端点提供默认配置，登录时自动获取。本地配置可覆盖远程默认值：

来自 .well-known/tron
{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": false
    }
  }
}

全局配置

路径：~/.config/tron/tron.json。用于设置用户范围的偏好，覆盖远程组织默认值。

项目级配置

在项目根目录添加 tron.json。Tron 启动时会从当前目录向上查找到最近的 Git 目录。

💡
提示
项目配置可安全提交到 Git，方便团队共享统一的 Tron 配置。

自定义路径

通过 TRON_CONFIG 环境变量指定任意配置文件路径：

终端
export TRON_CONFIG=/path/to/my/custom-config.json
tron run "Hello world"

Schema 与 IDE 支持

配置 Schema 定义在 troncode.cn/config.json，在文件头部添加 $schema 字段即可获得 VS Code 等编辑器的验证和自动补全。

TUI 设置

通过 tui 选项配置终端界面行为：

tron.json
{
  "$schema": "https://troncode.cn/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    },
    "diff_style": "auto"
  }
}
选项类型默认值说明
scroll_speednumber3滚动速度倍数（最小 1）。启用加速时忽略。
scroll_acceleration.enabledbooleanfalsemacOS 风格滚动加速，优先于 scroll_speed。
diff_stylestring"auto""auto" 根据终端宽度自适应，"stacked" 始终单列。

Server 设置

配置 tron serve 和 tron web 的服务器参数：

tron.json
{
  "$schema": "https://troncode.cn/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "cors": ["http://localhost:5173"]
  }
}
选项类型说明
portnumber监听端口号
hostnamestring监听主机名，启用 mDNS 未设置时默认 0.0.0.0
mdnsboolean启用 mDNS 服务发现，让局域网设备自动找到服务
corsstring[]允许的 CORS 来源，需完整格式如 https://app.example.com

模型配置

通过 model、small_model 和 provider 选项配置使用的模型：

tron.json
{
  "$schema": "https://troncode.cn/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "setCacheKey": true
      }
    }
  }
}
  • model — 主模型，格式为 供应商/模型ID
  • small_model — 轻量任务（如标题生成）使用的低成本模型，默认尝试供应商更便宜的选项
  • provider.options.timeout — 请求超时毫秒数（默认 300000），设为 false 禁用
  • provider.options.setCacheKey — 始终为该供应商设置缓存键

Agent 配置

通过 agent 选项定义专用代理，适用于特定任务场景：

tron.jsonc
{
  "$schema": "https://troncode.cn/config.json",
  "agent": {
    "code-reviewer": {
      "description": "审查代码的最佳实践和潜在问题",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是一个代码审查员。专注于安全性、性能和可维护性。",
      "tools": {
        // 只读审查，禁用文件修改工具
        "write": false,
        "edit": false
      }
    }
  }
}

也可在 ~/.config/tron/agents/ 或 .tron/agents/ 中用 Markdown 文件定义代理。了解更多 →

默认 Agent

通过 default_agent 设置启动时默认使用的代理（"build"、"plan" 或自定义代理名）：

tron.json
{
  "$schema": "https://troncode.cn/config.json",
  "default_agent": "plan"
}

自定义命令

通过 command 选项定义快捷命令，适合重复任务自动化：

tron.jsonc
{
  "$schema": "https://troncode.cn/config.json",
  "command": {
    "test": {
      "template": "运行完整测试套件并生成覆盖率报告，显示任何失败并建议修复。",
      "description": "运行带覆盖率的测试",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "component": {
      "template": "创建一个名为 $ARGUMENTS 的新 React 组件，包含 TypeScript 类型。",
      "description": "创建新组件"
    }
  }
}

权限设置

默认 Tron 允许所有操作无需确认。通过 permission 选项为敏感工具添加交互确认：

tron.json
{
  "$schema": "https://troncode.cn/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

供应商管理

禁用供应商

通过 disabled_providers 阻止特定供应商加载，即使其凭据可用：

tron.json
{
  "$schema": "https://troncode.cn/config.json",
  "disabled_providers": ["openai", "gemini"]
}

启用供应商白名单

通过 enabled_providers 设置允许列表，只启用指定供应商：

tron.json
{
  "$schema": "https://troncode.cn/config.json",
  "enabled_providers": ["anthropic", "google"]
}
⚠️
注意
disabled_providers 的优先级高于 enabled_providers。供应商同时出现在两个列表时，禁用优先。

其他常用选项

自动更新

tron.json
{
  "autoupdate": false   // true | false | "notify"
}

设为 "notify" 时不自动安装，但有新版本时会提示。通过包管理器（如 Homebrew）安装时此选项无效。

上下文压缩

tron.json
{
  "compaction": {
    "auto": true,   // 上下文满时自动压缩
    "prune": true  // 删除旧工具输出节省 token
  }
}

文件监视器

tron.json
{
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

分享

tron.json
{
  "share": "manual"   // "manual" | "auto" | "disabled"
}

实验性功能

⚠️
警告
实验性选项不稳定，可能在没有通知的情况下更改或删除。
json
{
  "$schema": "https://troncode.cn/config.json",
  "experimental": {}
}

变量替换

配置文件支持在字符串值中使用变量，动态引用环境变量或文件内容。

环境变量

格式：{env:VARIABLE_NAME}

tron.json
{
  "$schema": "https://troncode.cn/config.json",
  "model": "{env:TRON_MODEL}",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

若环境变量未设置，将被替换为空字符串。

文件引用

格式：{file:path/to/file}，支持相对路径、/ 绝对路径和 ~ 家目录路径：

tron.json
{
  "$schema": "https://troncode.cn/config.json",
  "instructions": ["./custom-instructions.md"],
  "provider": {
    "troncode": {
      "options": {
        "apiKey": "{file:~/.secrets/troncode-key}"
      }
    }
  }
}

文件引用适用于：将 API 密钥等敏感数据保存在独立文件中，以及在多个配置之间共享通用配置片段。