Crush

Crush 是 Charmbracelet 推出的终端 AI 编程工具。该团队此前的代表作包括 Bubble Tea、Glow、Lip Gloss 等业界广受认可的 TUI 项目,因此 Crush 在视觉呈现与交互设计层面具备同类工具中较高的水准。截至当前,该项目在 GitHub 累计获得 24,000 余次 Star。

默认情况下,Crush 要求为每个上游 provider(包括 Anthropic、OpenAI、Google、DeepSeek 等)分别完成 API key 配置。通过接入 AIHubMix,仅需一次配置即可在 Crush 中调用 800+ 个模型,涵盖 Claude Opus 4.7、GPT 5.5、Gemini 2.5 Pro、DeepSeek V4 Pro、Qwen Max、Kimi K2 等主流模型。

本文将引导用户在五分钟内完成 Crush 与 AIHubMix 的集成配置。

---

​

快速配置指引：

​

1️⃣ 安装地址

可从官方仓库获取应用

​

2️⃣ 环境变量配置

启动后填入 Aihubmix 然后输入密钥即可使用， 密钥可以在 Aihubmix 「Keys」页面 生成。

​

Crush 工具简介

Crush 是一款基于 TUI 的 agentic AI 编程工具,与 Claude Code、Aider、OpenCode 同属一类产品。其差异化优势主要体现于 Charmbracelet 团队一贯的精致 UI 设计语言,以及对多项高级特性的深度集成。

主要能力如下:

• 多 LLM 支持:会话进行中可随时切换模型
• MCP(Model Context Protocol)集成:兼容 http、stdio、sse 三种 server 协议
• LSP 上下文感知:提升代码语义解析的准确性
• Session 工作区管理:支持多项目独立隔离
• 文件权限控制与 .crushignore:对 agent 可访问的资源范围实现精细化管控
• Agent Skills 扩展机制:遵循开放标准
• 跨平台支持:涵盖 macOS、Linux、Windows、BSD 等主流操作系统

最新版本为 v0.67.0(2026 年 5 月发布),GitHub 累计 24,200 余 Star,由 Charmbracelet 团队持续维护。

---

​

Crush 与同类工具的对比

下表展示了 Crush 与 Aider、Claude Code、OpenCode 在关键维度上的差异:

维度	Crush	Aider	Claude Code	OpenCode
UI 风格	精致 TUI	极简 CLI	极简 CLI	TUI
MCP 支持	✅	❌	✅	✅
会话中动态切换模型	✅	✅	❌	✅
自定义 OpenAI 兼容端点	✅	✅	⚠️ 受限	✅
LSP 上下文感知	✅	⚠️ 部分	❌	✅
文件排除机制	✅	✅	⚠️	✅
多 session 工作区	✅	❌	❌	⚠️
配置文件格式	JSON	YAML / CLI 参数	环境变量	JSON
GitHub Star 数(2026.05)	24.2k	30k+	闭源	18k+
适用场景	精致 TUI 与 MCP 深度集成	极简主义与高启动速度	Anthropic 生态用户	高度可定制化

综合而言,若用户重视终端体验的精致度、MCP 集成的完整性,以及在多家模型之间灵活切换的能力,Crush 是优先推荐的方案。

---

​

准备工作

​

1. 安装 Crush

根据操作系统选择对应的安装命令:

# macOS
brew install charmbracelet/tap/crush

# Linux (Arch)
yay -S crush-bin

# Windows
winget install charmbracelet.crush

# 任意支持 Go 的平台
go install github.com/charmbracelet/crush@latest

# 通过 npm 安装
npm install -g @charmland/crush

​

2. 获取 AIHubMix API Key

访问 aihubmix.com 完成账号注册,前往 aihubmix.com/keys 创建 API Key。新注册账户可获得10。

​

3. 确认配置文件位置

Crush 按以下优先级查找配置文件:

1. ./.crush.json(项目级隐藏配置)
2. ./crush.json(项目级配置)
3. ~/.config/crush/crush.json(全局配置)

需要注意的是,项目级配置将覆盖全局配置中的同名字段。

---

​

核心配置(crush.json 完整模板)

Crush 提供两种与 AIHubMix 兼容的 provider 类型:

• "type": "openai-compat":适用于 GPT、Gemini、DeepSeek、Qwen、Kimi 等绝大多数模型
• "type": "anthropic":适用于 Claude 系列的原生协议调用(prompt caching 等高级特性需通过原生格式访问)

两种类型可在同一配置文件中并存。

以下提供一份开箱即用的完整 crush.json 模板,仅需将 YOUR_AIHUBMIX_KEY 替换为实际 Key 值:

{
  "$schema": "https://charm.land/crush.json",
  "providers": {
    "aihubmix-openai": {
      "id": "aihubmix-openai",
      "name": "AIHubMix (OpenAI 兼容)",
      "base_url": "https://aihubmix.com/v1",
      "type": "openai-compat",
      "api_key": "YOUR_AIHUBMIX_KEY",
      "models": [
        { "id": "claude-opus-4-7", "name": "Claude Opus 4.7" },
        { "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6" },
        { "id": "gpt-5.5", "name": "GPT 5.5" },
        { "id": "gpt-5-mini", "name": "GPT 5 Mini" },
        { "id": "gemini-2.5-pro", "name": "Gemini 2.5 Pro" },
        { "id": "deepseek-v4-pro", "name": "DeepSeek V4 Pro" },
        { "id": "deepseek-r1", "name": "DeepSeek R1" },
        { "id": "qwen-max", "name": "Qwen Max" },
        { "id": "kimi-k2", "name": "Kimi K2" }
      ]
    },
    "aihubmix-anthropic": {
      "id": "aihubmix-anthropic",
      "name": "AIHubMix (Anthropic 原生)",
      "base_url": "https://aihubmix.com",
      "type": "anthropic",
      "api_key": "YOUR_AIHUBMIX_KEY",
      "models": [
        { "id": "claude-opus-4-7", "name": "Claude Opus 4.7(原生)" },
        { "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6(原生)" }
      ]
    }
  }
}

​

字段说明

字段	必填	说明
id	是	Crush 内部唯一标识符,可由用户自定义
name	是	模型选择器界面中显示的名称
base_url	是	API 端点地址。OpenAI 兼容协议为 https://aihubmix.com/v1,Anthropic 协议为 https://aihubmix.com
type	是	取值为 openai-compat 或 anthropic
api_key	是	AIHubMix API Key,支持通过 ${ENV_VAR} 语法引用环境变量
models	是	启用的模型 ID 列表,需与 AIHubMix 模型注册表保持一致

​

推荐:通过环境变量引用 API Key

为避免 Key 以明文形式存储于配置文件中,建议改用环境变量引用方式:

"api_key": "${AIHUBMIX_API_KEY}"

随后在 shell 环境中完成设置:

export AIHUBMIX_API_KEY="sk-..."

---

​

验证配置结果

进入任意项目目录后,启动 Crush:

crush

通过模型选择器快捷键(默认为 Ctrl+P)打开模型列表。配置成功的情况下,可在 AIHubMix (OpenAI 兼容) 与 AIHubMix (Anthropic 原生) 两个分组之下看到先前配置的全部模型。

向模型发送测试消息(例如「你是什么模型?」),以确认响应正常返回。

如需进一步确认请求经由 AIHubMix 转发,可访问 aihubmix.com/usage 查看实时调用记录。

---

​

推荐模型搭配方案

Crush 支持在会话过程中切换模型,因此用户可针对不同任务类型选择最适合的模型,在性能与成本之间取得平衡。下表列出了经过实践验证的推荐方案:

任务类型	推荐模型	模型 ID	选用理由
多文件重构、复杂 agent 流程	Claude Opus 4.7	claude-opus-4-7	多步推理能力领先
日常代码编写、内联编辑	Claude Sonnet 4.6	claude-sonnet-4-6	代码场景下性价比最优
中文代码注释、文档生成	DeepSeek V4 Pro	deepseek-v4-pro	中文语义理解与表达能力出色
大型 monorepo、长上下文场景	Gemini 2.5 Pro	gemini-2.5-pro	上下文窗口可达 200 万 token 以上
代码评审等成本敏感场景	Qwen Max	qwen-max	调用成本约为 Opus 的十分之一,推理能力充足
复杂调试、推理密集任务	DeepSeek R1	deepseek-r1	链式思维能力突出,价格低廉
快速补全、规划阶段	Claude Haiku 4.5	claude-haiku-4-5	Claude 家族中响应速度最快
原型验证、Demo 测试	GPT 4.1 Nano	gpt-4.1-nano-free	完全免费

成本优化建议:在规划阶段使用 claude-opus-4-7,执行阶段切换至 claude-sonnet-4-6 或 qwen-max,可将整体调用成本降至全程使用 Opus 方案的 20%–40%。

完整模型清单请参见 AIHubMix 模型库。

---

​

MCP 服务配置

Crush 对 MCP(Model Context Protocol)提供完整支持,使 agent 能够直接调用文件系统、GitHub、数据库、浏览器等外部工具。

在 crush.json 中添加 MCP server 配置:

{
  "providers": { ... },
  "mcp": {
    "servers": {
      "filesystem": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
      },
      "github": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
        }
      }
    }
  }
}

更多 MCP server 配置范例与高级用法,请参阅 MCP 官方文档。

---

​

常见问题

Crush 通过 AIHubMix 能否调用 DeepSeek、Qwen、Kimi 等国产模型?

可以。通过 openai-compat 类型的 provider,所有主流国产模型均与 GPT、Claude 共用同一调用接口,开发者无需额外学习专有协议。

Crush 与 Aider 应如何选择?

两者均属于 CLI/TUI 形态的 agentic 工具。Aider 历史更悠久、设计更极简、启动速度更快;Crush 在 UI 精致度、MCP 集成深度、模型切换灵活性方面更具优势。长时间在终端环境下进行开发并注重交互体验的用户建议选择 Crush;追求极致速度与最小化配置的用户可优先考虑 Aider。

Crush 是否支持标准 OpenAI SDK 调用格式?

支持。"type": "openai-compat" 遵循标准 OpenAI Chat Completions 协议,AIHubMix 与之完全兼容。

能否在同一配置中并行使用多个 provider?

可以。前文 crush.json 示例即为 OpenAI 兼容与 Anthropic 原生两种 provider 并存的配置范例,Crush 的模型选择器将全部展示。

如何在会话过程中切换模型?

会话进行中按下模型选择器快捷键(默认为 Ctrl+P),选择目标模型后,后续消息将自动路由至新模型,且对话上下文得以完整保留。

如何有效降低使用成本?

低风险任务建议使用免费模型(gpt-4.1-nano-free、deepseek-v3-free 等),日常工作可使用 claude-sonnet-4-6 或 qwen-max,仅在处理复杂场景时启用 claude-opus-4-7。

Crush 的配置文件存储于何处?

按优先级依次为:./.crush.json → ./crush.json → ~/.config/crush/crush.json。项目级配置会覆盖全局配置中的同名字段。

Crush 是否支持本地模型(Ollama、LM Studio 等)?

支持。openai-compat 类型可对接任意符合 OpenAI 协议的端点,包括 http://localhost:11434(Ollama)。本地模型与 AIHubMix 可在同一份配置文件中并行使用。

免费模型应如何启用?

将带 -free 后缀的模型 ID(如 gpt-4.1-nano-free、deepseek-v3-free)添加至 crush.json 的 models 字段即可。完整免费模型清单请参见 aihubmix.com/models?free=true。

如何限制 Crush 可调用的工具范围?

Crush 支持通过 allowed_tools 与 disabled_tools 字段进行精细化权限控制,亦可通过 --yolo 参数跳过全部权限确认(请谨慎使用)。详情请参阅 Crush README。

报错「model not found」应如何处理?

请核对 models 数组中的 id 字段是否与 AIHubMix 模型注册表完全一致(包括大小写与连字符)。新发布的模型可能需要 1 至 2 天才能上线,建议前往 模型列表页 进行确认。

为何选择 AIHubMix 而非 OpenRouter?

两者均与 Crush 兼容。AIHubMix 的差异化优势主要在于:对国产前沿模型(DeepSeek、Qwen、Kimi、GLM、Doubao 等)的接入更为完整,提供 26+ 个免费模型,采用按 token 透明计费的模式。若用户的业务场景不涉及国产模型,OpenRouter 亦是合理选择 —— Crush 与两者均可对接。

---

​

故障排查

错误码	主要原因	解决方案
401 Unauthorized	API Key 错误或包含多余字符	重新从 aihubmix.com/keys 复制 Key,确认无前后空格
404 model not found	模型 ID 拼写错误或 AIHubMix 平台尚未上线	对照 模型列表 进行核对
402 insufficient balance	账户余额不足	前往 aihubmix.com/billing 完成充值
429 rate limit	短时间内请求频次超出限额	增加指数退避重试逻辑,或升级账户等级
context window exceeded	对话历史超出模型上下文窗口容量	中途切换至长上下文模型(如 gemini-2.5-pro)
工具调用在 gpt-4.1-nano-free 上失败	该免费模型不支持 tool use 特性	切换至 claude-sonnet-4-6、gpt-5-mini、deepseek-v4-pro 等支持工具调用的模型
流式输出出现乱码或无响应	provider type 字段配置错误	确认配置为 "type": "openai-compat"(而非 "openai")

---

​

进阶用法

​

按任务类型动态分配模型

Crush 支持会话中动态切换模型这一能力,使得用户可以针对不同任务阶段调用不同模型,从而显著降低整体成本:

• 规划阶段 → claude-opus-4-7
• 代码生成 → claude-sonnet-4-6
• Commit 信息撰写、代码评审 → qwen-max 或 gpt-5-mini
• 复杂调试 → deepseek-r1

经实测,典型会话的整体成本可较全程使用 Opus 的方案降低 60% 至 80%。

​

通过 .crushignore 精简上下文

在项目根目录创建 .crushignore 文件,排除 node_modules、大型数据文件、敏感配置、二进制资源等无关内容,可显著降低 token 消耗,同时提升响应速度。

​

通过 LSP 提升上下文准确度

Crush 通过 LSP 获取类型信息、引用关系与定义位置等元数据。建议项目环境中安装对应语言的 language server,可显著提升模型对代码语义的理解能力。

​

Session 持久化机制

Crush 自动保存会话状态,长任务可通过 crush --resume <session-id> 命令跨日恢复执行。

​

自定义 MCP server

除官方提供的 filesystem、github 等标准 MCP server 之外,用户可使用 Python 或 Node.js 自行实现 MCP server,将项目专属能力(如部署脚本、内部 API、测试 runner 等)以标准协议暴露给 agent。

---

​

延伸阅读

• 完整模型清单 → AIHubMix 模型库
• 其他 CLI agent 集成 → Claude Code / OpenCode
• IDE 类工具集成 → Cursor
• 免费模型配置 → AIHubMix 免费模型
• Crush 官方文档 → github.com/charmbracelet/crush

---

​

为什么选择 AIHubMix

• 一份 Key 接入 800+ 模型:Claude、GPT、Gemini、DeepSeek、Qwen、Kimi 等主流模型统一聚合,免除多账户管理负担
• 26+ 个免费模型:覆盖原型开发、Demo 测试、prompt 调试等多数研发场景
• OpenAI SDK 完全兼容:存量代码仅需修改 base_url 即可完成迁移

**立即注册 AIHubMix → **

最新更新日期：2026年5月12日