跳转到主要内容
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」页面 生成。 about about about

​
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 在关键维度上的差异:
维度CrushAiderClaude CodeOpenCode
UI 风格精致 TUI极简 CLI极简 CLITUI
MCP 支持✅❌✅✅
会话中动态切换模型✅✅❌✅
自定义 OpenAI 兼容端点✅✅⚠️ 受限✅
LSP 上下文感知✅⚠️ 部分❌✅
文件排除机制✅✅⚠️✅
多 session 工作区✅❌❌⚠️
配置文件格式JSONYAML / CLI 参数环境变量JSON
GitHub Star 数(2026.05)24.2k30k+闭源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.7claude-opus-4-7多步推理能力领先
日常代码编写、内联编辑Claude Sonnet 4.6claude-sonnet-4-6代码场景下性价比最优
中文代码注释、文档生成DeepSeek V4 Prodeepseek-v4-pro中文语义理解与表达能力出色
大型 monorepo、长上下文场景Gemini 2.5 Progemini-2.5-pro上下文窗口可达 200 万 token 以上
代码评审等成本敏感场景Qwen Maxqwen-max调用成本约为 Opus 的十分之一,推理能力充足
复杂调试、推理密集任务DeepSeek R1deepseek-r1链式思维能力突出,价格低廉
快速补全、规划阶段Claude Haiku 4.5claude-haiku-4-5Claude 家族中响应速度最快
原型验证、Demo 测试GPT 4.1 Nanogpt-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 UnauthorizedAPI 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

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