排查常见问题

安装后找不到 crux

重新打开终端，再运行 crux --version。默认目录为 ~/.crux/bin；若使用 --no-modify-path，需要自行加入 PATH。Windows 安装脚本需要 bash 环境，不能直接把 bash 管道命令当作 PowerShell 语法执行。

无法连接模型

• 用 /provider 检查服务商和凭据，用 /model 确认当前模型。
• 检查账户额度、模型权限和接口地址。
• 检查网络与代理配置。Crux 的系统代理回退不能保证绕过所有网络限制。
• 提交问题时附上已脱敏的错误消息，不要附 API key 或登录 token。

没有 TLDR 或额度数据

TLDR 需要可用的辅助模型，自动生成还取决于回复长度。先检查 /auxiliary 配置，再试 /tldr。Coding Plan usage 只对支持该能力且成功连接的 Provider 显示；空缺并不代表零额度。

插件没有出现

检查 .crux/plugins 下的 TOML 是否有效、id 是否与文件名一致、placement 是否正确。等待下一次扫描。状态数据路径相对于项目根目录解析。先用 manual 中的最小示例验证，再接入外部数据。

语义搜索首次运行较慢

首次使用可能需要下载模型资源和建立索引。检查网络及模型资源是否准备完成，后续查询再比较耗时。发布包里的 third_party 资源应保持原有相对位置。

反馈问题

到 GitHub Issues 提交版本号、操作系统、终端、复现步骤及脱敏的错误输出。说明问题发生在启动、交互、模型响应还是工具执行阶段。