故障排查

常见问题诊断与解决方案

💡

提示

如果以下方法未能解决你的问题，可以在 GitHub Issues 提交详细的问题反馈，我们会尽快跟进处理。

安装问题

安装脚本失败

如果一键安装脚本执行失败，通常是因为 curl 权限不足或网络问题。可以尝试使用 sudo 执行：

终端

curl -fsSL https://upgrade.lianwo123.com/troncode/cli/install | sudo bash

PATH 未配置

安装成功但命令找不到时，说明安装目录未在 PATH 中。手动添加到 shell 配置文件：

终端

# 对于 bash 用户：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

source ~/.bashrc

# 对于 zsh 用户：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

source ~/.zshrc

版本冲突

如果系统中存在旧版本的 Tron，可能导致冲突。先完全卸载旧版本再重新安装：

终端

# 查找旧版本位置

which tron

# 删除旧版本

rm $(which tron)

# 重新安装

curl -fsSL https://upgrade.lianwo123.com/troncode/cli/install | bash

连接问题

API 密钥无效

如果出现 401 Unauthorized 或 Invalid API key 错误，请检查 TRON_API_KEY 环境变量是否正确设置：

终端

# 检查当前 API Key 是否已设置

echo $TRON_API_KEY

# 重新设置

export TRON_API_KEY=your_correct_api_key

确保 API Key 没有多余的空格或换行符。也可以在 Tron TUI 中重新运行 /connect 命令重置密钥。

网络超时

如果请求持续超时，可能是网络受限。请参考网络代理配置文档，配置合适的代理服务器。

TLS 证书错误

出现 CERT_HAS_EXPIRED 或 UNABLE_TO_VERIFY_LEAF_SIGNATURE 错误时，需要配置企业自定义证书。详见自定义证书部分。

性能问题

如果 Tron 响应速度变慢，常见原因和解决方法：

Context 太大导致响应变慢：使用 /clear 命令清空当前上下文，开始新的对话会话
模型响应速度慢：在 TUI 中运行 /connect 切换到更快的模型，例如 Claude Haiku 或 GPT-4o-mini
大文件处理慢：避免一次性引用过多大文件，分批次处理

Tron TUI

# 清空上下文

/clear

# 切换更快的模型

/connect

运行时错误

文件权限错误

如果 Tron 无法读取或写入文件，检查文件和目录的权限：

终端

# 检查文件权限

ls -la ~/.config/tron/

# 修复配置目录权限

chmod 755 ~/.config/tron/

chmod 644 ~/.config/tron/config.json

LSP 无法启动

LSP 功能依赖项目中安装的语言服务器。确保对应语言的 LSP 已正确安装，例如 TypeScript 需要安装 typescript-language-server。检查 tron --log-level debug 的输出获取详细错误信息。

MCP 服务连接失败

MCP 服务连接失败时，检查以下几点：

MCP 服务进程是否正在运行
配置文件中的 MCP 服务地址和端口是否正确
防火墙是否允许对应端口的连接

查看日志

开启详细日志模式，可以获取更多诊断信息：

终端

tron --log-level debug

日志文件默认保存在以下位置：

Linux / macOS：~/.local/share/tron/logs/tron.log
Windows：%APPDATA%\tron\logs\tron.log

重置配置

当配置文件损坏或出现无法解释的异常时，可以使用 tron --reset 将配置重置为默认值：

终端

# 重置前建议先备份配置

cp ~/.config/tron/config.json ~/.config/tron/config.json.bak

tron --reset

注意：重置操作会清除所有自定义配置，包括 API 密钥、主题设置、快捷键等。重置后需要重新运行 /connect 配置供应商。