Crush 保姆级部署教程：Charm 出品终端 AI 编程助手从零到一完整搭建

Crush 是 Charm（就是做 Bubbles、Glow、Lipgloss 那套终端 UI 库的公司）出品的终端 AI 编程助手，定位是「你终端里的编程新搭档」：你的工具、你的代码、你的工作流，全部接进你选的任意大模型。它是一个纯 TUI（终端图形界面）应用，没有服务端、没有云绑定，装上即用。截至本文写作时，Crush 在 GitHub 上收获约 2.9 万 Star，main 分支每天都有提交，属于高度活跃项目。

为什么值得用它？第一，它原生支持几乎所有主流模型供应商——Anthropic、OpenAI、Gemini、OpenRouter、Groq、DeepSeek，甚至本地 Ollama，你可以在会话中途无缝切换模型而不丢上下文。第二，它带 LSP 增强和 MCP 扩展，能力比普通聊天机器人强得多。第三，Charm 生态的终端 UI 体验在开源界是天花板级别，颜值和交互都在线。本文从零开始，把 Crush 在 Linux / macOS / Windows 上装好、配上 API Key、接上本地 Ollama 模型，直到第一次让它帮你改代码。

一、项目介绍与适用场景

Crush 是一个跑在终端里的 Agent 式编程助手：你在项目目录里敲 crush，它进入一个全屏 TUI，读你的代码库、执行命令、改文件、跑测试，全程在你眼皮底下。它适合：

• 重度终端用户：不想离开 iTerm / Alacritty / VS Code 内置终端，想要一个能直接干活的 AI 搭档。
• 多模型党：今天用 Claude、明天用 GPT、后天想跑本地 Ollama，不想被某一家锁死。
• 服务器 / SSH 场景：没有图形界面的远程开发机，通过 SSH 就能获得完整的 Agent 编程能力。
• 团队内部统一工具链：用 crushrc 把团队约定、MCP 服务器、模型偏好沉淀成可分发的配置。

二、核心功能逐条拆解

1. 多模型接入：官方 README 列出 20+ 环境变量对应的供应商（ANTHROPIC_API_KEY、OPENAI_API_KEY、GEMINI_API_KEY、OPENROUTER_API_KEY 等），按 ctrl+l 打开模型选择器切换。
2. 会话中途切模型：换模型保留上下文，不用重新解释一遍项目背景。
3. 多会话：每个项目维护多个工作会话，会话管理器里挑历史对话继续。
4. LSP 增强：像 IDE 一样加载语言服务器（gopls、typescript-language-server、nil），给 Agent 提供精确的符号上下文。
5. MCP 扩展：支持 stdio、http、sse 三种传输方式接 MCP 服务器，把 GitHub、Linear、数据库等工具接进 Agent。
6. 本地模型：通过 provider add ollama --type ollama --base-url http://localhost:11434/v1/ 自动发现 Ollama 模型，完全离线可用。
7. crushrc 配置：用 Bash 写配置，原生跨平台（含 Windows），优先级从项目级 ./.crushrc 到全局 ~/.config/crush/crushrc。
8. Agent Skills：支持 Agent Skills 开放标准，从 ~/.config/crush/skills/ 等目录自动发现技能包。
9. 权限控制：默认每次工具调用都要你确认，permissions allow view edit 可放行常用工具，--yolo 可跳过全部确认（慎用）。
10. 可观测：日志落在 ./.crush/logs/crush.log，crush logs --follow 实时跟踪。

三、全套官方链接

四、硬件与环境前置要求

Crush 是一个用 Go 编写的单二进制 TUI 程序，自身资源占用极小：

• 操作系统：macOS、Linux、Windows（PowerShell 与 WSL）、Android、FreeBSD、OpenBSD、NetBSD 均为官方支持（README「Works Everywhere」）。
• 终端：任意支持真彩色的现代终端。
• Node.js（仅 npm 安装方式）：需要本机有 Node 18+。
• Go（仅源码安装方式）：需要 Go 1.22+。
• 模型侧：调用云端 API 只需网络；跑本地模型需先装 Ollama 并备好显卡内存。
• 内存 / CPU：Crush 本体 < 100MB 内存即可，真正吃资源的是你选的模型。

出处：官方 README「Installation」「Works Everywhere」段。

五、多平台安装步骤

Crush 官方不提供服务端部署方式，它是纯客户端 TUI，按官方 README 各平台安装方式逐一给出。

5.1 macOS 安装（Homebrew）

官方 README 原文：

brew install charmbracelet/tap/crush

解释：charmbracelet/tap 是 Charm 官方 Homebrew tap，安装后直接可用 crush 命令。

验证：

crush --version

5.2 Linux 安装（Debian/Ubuntu APT 仓库）

官方 README 给出的完整三行：

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
sudo apt update && sudo apt install crush

逐段解释：

• 第一行：建 APT 官方 keyring 目录。
• 第二行：下载 Charm 官方 GPG 公钥并 dearmor 成可被 APT 读取的格式。
• 第三行：把 Charm 仓库写进 sources.list.d。
• 第四行：刷新索引并安装 crush。

Fedora/RHEL 用户按 README：

echo '[charm]
name=Charm
baseurl=https://repo.charm.sh/yum/
enabled=1
gpgcheck=1
gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo
sudo yum install crush

Arch 用户：yay -S crush。

5.3 Windows 安装（Winget / Scoop）

官方 README 原文：

# Winget
winget install charmbracelet.crush

# Scoop
scoop bucket add charm https://github.com/charmbracelet/scoop-bucket.git
scoop install crush

5.4 通用：npm 与 Go 安装

npm（官方 README）：

npm install -g @charmland/crush

Go（官方 README）：

go install github.com/charmbracelet/crush@latest

Solaris 上需加 tag：go install -tags sqlite3_dotlk github.com/charmbracelet/crush@latest（README 原话）。

六、配置文件全部参数解释

Crush 可以零配置开箱即用，但要接自己的模型供应商就要写 crushrc。官方说明：crushrc 就是带 Crush 内置命令的 Bash 脚本，按优先级加载：

官方 README 给出的完整示例：

# Add Ollama.
provider add ollama --type ollama --base-url "http://localhost:11434/v1"

# Register a model on Ollama.
model add ollama/llama3.3 --name "Llama 3.3" --context-window 128000

# Auto-approve some tools.
permissions allow view edit

# Add an MCP server, with a GitHub API token stored in 1Password.
mcp add github \
  --type http \
  --url "https://api.github.com/mcp/" \
  --header Authorization "Bearer $(op read 'op://my-secret-key')"

常用内置命令参数表：

环境变量（官方 README 表格）：

七、启动、后台与日常使用

7.1 启动

cd your-project
crush

首次启动进入 TUI，按 ctrl+l 打开模型选择器，选一个供应商（如 Anthropic）粘贴 API Key，或直接用 Charm 官方 Hyper 订阅。预期：进入对话界面，输入框在底部。

7.2 后台常驻与开机自启

Crush 是交互式 TUI，官方没有提供常驻服务端模式（它是客户端工具，不是服务）。它天然在你当前终端里前台运行；配合 tmux / screen 可以让远程 SSH 会话不断：

tmux new -s dev
crush
# Ctrl+B 然后 D 脱离；下次 tmux attach -t dev 回来

修改端口：Crush 作为客户端不监听端口；它连接的是远程模型 API，所以「端口」概念发生在你自托管模型时（如 Ollama 默认 11434，改 Ollama 的 OLLAMA_HOST 即可，再在 crushrc 里改 --base-url）。

7.3 日志

crush logs              # 最近 1000 行
crush logs --tail 500
crush logs --follow     # 实时跟踪

日志文件位置：./.crush/logs/crush.log（项目相对路径）。

八、功能实操教程

第 1 步：装好后 cd 到一个 Git 仓库，敲 crush 进入 TUI。

第 2 步：按 ctrl+l 在模型选择器里选 Anthropic（或你已配好 Key 的供应商），粘贴 API Key。

第 3 步：输入「/init 让 Crush 分析这个项目」——它会扫描代码库并生成 AGENTS.md 项目上下文文件（官方 README「Initialization」段）。

第 4 步：直接用自然语言下任务，比如「帮我把这个函数加上错误处理并写测试」。Crush 会：读文件 → 提议修改 → 请求你确认 → 落盘 → 跑测试。

第 5 步：中途想换模型？按 ctrl+l 选另一个，上下文保留。

第 6 步（接本地模型，离线场景）：先装好 Ollama 并 ollama pull qwen3:30b，然后在 crushrc 里写：

provider add ollama --type ollama --base-url "http://localhost:11434/v1/" --discover-models true

重启 crush，模型选择器里就能看到本地模型。

第 7 步：按 ctrl+p 打开命令面板，选 Themes 换主题（默认 charmtone-panther，可选 gruvbox-dark、keanu）。

九、全套报错故障排查

报错 1： crush: command not found 原因分析：PATH 没刷新或 shell 没重载。 解决方案：重新打开终端；brew 版确认 brew doctor 正常；deb 版确认 /etc/apt/sources.list.d/charm.list 写对了。

报错 2： 模型选择器里选了供应商但 401 / 403。 原因分析：API Key 没配对或额度用完。 解决方案：echo $ANTHROPIC_API_KEY 确认环境变量在当前 shell 里；或直接在模型选择器里重新粘贴。

报错 3： 连本地 Ollama 报 connection refused。 原因分析：Ollama 没起，或没监听 11434。 解决方案：ollama serve 先跑起来；curl http://localhost:11434 验证；远程服务器上 Ollama 默认只绑 127.0.0.1，需 OLLAMA_HOST=0.0.0.0 ollama serve。

报错 4： Linux 下复制粘贴不好用。 原因分析：官方 Q&A 明确：Linux/BSD + Wayland 需要 wl-copy/wl-paste，X11 需要 xclip/xsel。 解决方案：sudo apt install wl-clipboard（Wayland）或 sudo apt install xclip（X11）。

报错 5： Agent 每次改文件都问一遍，嫌烦。 原因分析：默认安全策略。 解决方案：在 crushrc 里 permissions allow view edit ls grep；完全信任再加 --yolo 启动（官方 WARNING：非常危险）。

报错 6： 公司内网拉不到模型列表更新。 原因分析：Crush 默认从 Catwalk 拉模型元数据。 解决方案：export CRUSH_DISABLE_PROVIDER_AUTO_UPDATE=1，或 option provider-auto-update false。

十、升级、回滚与卸载

升级： - brew：brew upgrade crush - apt：sudo apt update && sudo apt install --only-upgrade crush - npm：npm update -g @charmland/crush - Go：go install github.com/charmbracelet/crush@latest

备份建议：~/.config/crush/（含 crushrc、themes、skills）和项目里的 .crushrc、.crush/ 目录。

回滚：包管理器降级到上一个版本号；或直接 go install github.com/charmbracelet/crush@v具体版本。

卸载：brew uninstall crush / sudo apt remove crush / npm uninstall -g @charmland/crush；配置残留删 ~/.config/crush/ 与各项目下 .crushrc。

十一、商用许可与合规风险提示

Crush 采用 FSL-1.1-MIT（Functional Source License），这是一种「源码可见 + 延时转 MIT」的特殊许可：你可以自由查看、修改源码、内部使用，但在 license 生效满 2 年之前，不能把 Crush 本身作为托管服务对外提供（即不能直接拿它去做一个「类似 Crush 的 SaaS」卖钱）。满 2 年后自动转为 MIT，限制消失。个人、团队内部用它辅助写代码完全合规；但如果你想基于 Crush 二次开发一个商业产品对外卖，需要仔细读 LICENSE.md 的年限与条款。模型侧费用按你选的供应商 API 计费；本地 Ollama 模型另受模型权重协议约束。Crush 默认采集匿名指标，可 export CRUSH_DISABLE_METRICS=1 或 export DO_NOT_TRACK=1 关闭。

参考链接

• GitHub 仓库：https://github.com/charmbracelet/crush
• README（安装 / 配置 / MCP / Skills）：https://github.com/charmbracelet/crush/blob/main/README.md
• License：https://github.com/charmbracelet/crush/blob/main/LICENSE.md
• 发布页（各平台二进制）：https://github.com/charmbracelet/crush/releases