> ## Documentation Index > Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt > Use this file to discover all available pages before exploring further. # Crush [Crush](https://github.com/charmbracelet/crush) 是 [Charmbracelet](https://charm.sh/) 推出的终端 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️⃣ 安装地址 可从[官方仓库](https://github.com/charmbracelet/crush)获取应用 ### 2️⃣ 环境变量配置 启动后填入 Aihubmix 然后输入密钥即可使用， 密钥可以在 Aihubmix [「Keys」页面](https://aihubmix.com/token) 生成。 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 在关键维度上的差异: | 维度 | 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 根据操作系统选择对应的安装命令: ```bash theme={null} # 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](https://aihubmix.com) 完成账号注册,前往 [aihubmix.com/keys](https://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 值**: ```json theme={null} { "$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 以明文形式存储于配置文件中,建议改用环境变量引用方式: ```json theme={null} "api_key": "${AIHUBMIX_API_KEY}" ``` 随后在 shell 环境中完成设置: ```bash theme={null} export AIHUBMIX_API_KEY="sk-..." ``` *** ## 验证配置结果 进入任意项目目录后,启动 Crush: ```bash theme={null} crush ``` 通过模型选择器快捷键(默认为 `Ctrl+P`)打开模型列表。配置成功的情况下,可在 `AIHubMix (OpenAI 兼容)` 与 `AIHubMix (Anthropic 原生)` 两个分组之下看到先前配置的全部模型。 向模型发送测试消息(例如「你是什么模型?」),以确认响应正常返回。 如需进一步确认请求经由 AIHubMix 转发,可访问 [aihubmix.com/usage](https://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 模型库](https://aihubmix.com/models)。 *** ## MCP 服务配置 Crush 对 MCP(Model Context Protocol)提供完整支持,使 agent 能够直接调用文件系统、GitHub、数据库、浏览器等外部工具。 在 `crush.json` 中添加 MCP server 配置: ```json theme={null} { "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 官方文档](https://modelcontextprotocol.io/)。 *** ## 常见问题 **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](https://aihubmix.com/models?free=true)。 **如何限制 Crush 可调用的工具范围?** Crush 支持通过 `allowed_tools` 与 `disabled_tools` 字段进行精细化权限控制,亦可通过 `--yolo` 参数跳过全部权限确认(请谨慎使用)。详情请参阅 [Crush README](https://github.com/charmbracelet/crush#permissions)。 **报错「model not found」应如何处理?** 请核对 `models` 数组中的 `id` 字段是否与 AIHubMix 模型注册表完全一致(包括大小写与连字符)。新发布的模型可能需要 1 至 2 天才能上线,建议前往 [模型列表页](https://aihubmix.com/models) 进行确认。 **为何选择 AIHubMix 而非 OpenRouter?** 两者均与 Crush 兼容。AIHubMix 的差异化优势主要在于:**对国产前沿模型(DeepSeek、Qwen、Kimi、GLM、Doubao 等)的接入更为完整,提供 26+ 个免费模型,采用按 token 透明计费的模式**。若用户的业务场景不涉及国产模型,OpenRouter 亦是合理选择 —— Crush 与两者均可对接。 *** ## 故障排查 | 错误码 | 主要原因 | 解决方案 | | ----------------------------- | --------------------------- | ----------------------------------------------------------------- | | `401 Unauthorized` | API Key 错误或包含多余字符 | 重新从 [aihubmix.com/keys](https://aihubmix.com/keys) 复制 Key,确认无前后空格 | | `404 model not found` | 模型 ID 拼写错误或 AIHubMix 平台尚未上线 | 对照 [模型列表](https://aihubmix.com/models) 进行核对 | | `402 insufficient balance` | 账户余额不足 | 前往 [aihubmix.com/billing](https://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 ` 命令跨日恢复执行。 ### 自定义 MCP server 除官方提供的 filesystem、github 等标准 MCP server 之外,用户可使用 Python 或 Node.js 自行实现 MCP server,将项目专属能力(如部署脚本、内部 API、测试 runner 等)以标准协议暴露给 agent。 *** ## 延伸阅读 * **完整模型清单** → [AIHubMix 模型库](https://aihubmix.com/models) * **其他 CLI agent 集成** → [Aider](./aider) / [Claude Code](./claude-code) / [OpenCode](./opencode) * **IDE 类工具集成** → [Cursor](./cursor) / [Windsurf](./windsurf) / [Antigravity](./antigravity) * **免费模型配置** → [AIHubMix 免费模型](https://aihubmix.com/models?free=true) * **Crush 官方文档** → [github.com/charmbracelet/crush](https://github.com/charmbracelet/crush) *** ## 为什么选择 AIHubMix * **一份 Key 接入 800+ 模型**:Claude、GPT、Gemini、DeepSeek、Qwen、Kimi 等主流模型统一聚合,免除多账户管理负担 * **26+ 个免费模型**:覆盖原型开发、Demo 测试、prompt 调试等多数研发场景 * **OpenAI SDK 完全兼容**:存量代码仅需修改 `base_url` 即可完成迁移 [\*\*立即注册 AIHubMix → \*\*](https://aihubmix.com/register) 最新更新日期：2026年5月12日