Crush 配置指南：安装、API Key 与自定义模型

在 crushrc 中添加 openai-compat provider，将 Crush 接入 BetterToken。在 macOS 搭配 GPT 模型的测试中，Crush 0.98.2 通过 /v1/chat/completions 完成了三次冷启动文本请求和一次文件读取工具调用，文本请求三次均成功。

重点信息

字段	值
API Key	通过 --api-key 传入 BetterToken API Key
Base URL	通过 --base-url 传入 https://bettertoken.ai/v1
Model	bettertoken/YOUR_MODEL_ID
Provider 类型	openai-compat
配置文件	~/.config/crush/crushrc

准备工作

• 下方安装命令需要 Homebrew
• BetterToken API Key：注册并获取
• 从模型广场获取的 Model ID 和上下文上限

安装

使用 Crush 官方仓库中的 Homebrew 命令：

brew install charmbracelet/tap/crush
crush --version

手动配置

在将用于运行 Crush 的终端中设置 BetterToken API Key：

export BETTERTOKEN_API_KEY="YOUR_API_KEY"

使用推荐的 Bash 配置格式创建 ~/.config/crush/crushrc。替换所有 YOUR_MODEL_ID，并将 --context-window 设为所选模型文档中列明的上限。示例中的 128000 是客户端声明值，不是经过验证的 BetterToken 模型上限。

provider add bettertoken --type openai-compat --base-url "https://bettertoken.ai/v1" --api-key "$BETTERTOKEN_API_KEY"
model add bettertoken/YOUR_MODEL_ID --name "YOUR_MODEL_ID" --context-window 128000
model large bettertoken/YOUR_MODEL_ID
model small bettertoken/YOUR_MODEL_ID
permissions allow view

将这些命令保存到 crushrc，Crush 启动时会执行它们。permissions allow view 允许使用文件查看工具。上游已弃用旧版 JSON 配置格式，但该格式仍可用，其文本请求也通过了测试。

验证连接

在同一终端中进入项目目录后运行：

crush run "Reply with only: OK"

确认最终回复为 OK。验证文件访问时，让 Crush 读取项目中的一个已知文件，同时核对 view 工具结果和最终回复。

切换模型

使用 model add 添加另一个模型，在 crushrc 中更新 model large 和 model small 的选择，然后重新运行。

常见错误

现象	排查方式
No providers configured	未加载可用 provider 时，Crush 会在发送请求前报此错误。检查 crushrc 的位置和内容，以及可能覆盖它的项目配置。
401	在启动 Crush 前导出 BETTERTOKEN_API_KEY 并核对其值。
配置未明确列出模型	测试中，仅配置 provider 时，Crush 通过 /v1/models 发现模型。明确添加 model add 条目可指定本例使用的模型。
文件访问需要批准	检查已加载配置中的 permissions allow view。

相关文档

• 对比支持的工具
• API 错误与限流
• Crush 配置参考

技术说明

被测 openai-compat provider 将生成请求发送至 /v1/chat/completions。省略明确的模型条目时，通过 /v1/models 发现模型。