Crush AI 编码助手安装与上生产：一份实操手册
【免费下载链接】crushGlamourous agentic coding for all 💘项目地址: https://gitcode.com/gh_mirrors/crush3/crush
这篇文章讲 Crush 部署的完整流程：从一行命令装好 AI 编码助手、配置模型提供商，到上生产环境前必须改什么，以及日常维护和排错怎么做。适合第一次接触 Crush 的开发者，也适合想把它放到团队服务器上跑的同学。读完你能独立完成安装、配置、审计和排查。
三步装好 Crush 并跑通第一条命令
按你的环境选安装方式
Crush 是终端里的程序，装法取决于你在什么系统上，不用纠结，对号入座就行：
# macOS，Homebrew 最省心 brew install charmbracelet/tap/crush # 已经装了 Node 的机器（macOS / Linux / Windows 通用） npm install -g @charmland/crush # Windows winget install charmbracelet.crush # Debian / Ubuntu 服务器，走官方 apt 源 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/sources.list.d/charm.list sudo apt update && sudo apt install crush怎么选：个人 Mac 开发机用 brew；公司服务器走 apt 或 rpm，方便走包管理统一升级；跨平台且已装 Node 的团队用 npm，三个系统版本一致。装完crush --version能出版本号就算成功。
接上模型提供商，打开第一个会话
Crush 本身不带模型，需要接一个 LLM 提供商。最快的方式是把 API Key 放进环境变量，比如：
export ANTHROPIC_API_KEY=你的key export OPENAI_API_KEY=你的key然后cd进你的项目目录直接运行crush。首次进入会提示你选择模型，也可以随时按ctrl+l打开模型选择器切换提供商、粘贴 API key。选中之后它就可以在你仓库里读文件、改代码、执行命令了。
让 Crush 真正读懂你的项目代码
装好只是开始，下面这几个配置决定了它"读代码"的准确度。
先说清配置体系：Crush 的配置文件叫crushrc，本质是一段带内置命令的 Bash 脚本，可以写if、source这些逻辑。查找顺序是：项目根目录的./.crushrc最高优先级，其次是./crushrc，最后是全局的~/.config/crush/crushrc。项目配置会覆盖全局配置，所以团队共享的写全局、个人差异写项目级即可。
启用 LSP，给它和你一样的代码上下文
LSP（Language Server Protocol，就是让你的编辑器能"跳转定义""查引用"的那套协议）装到 Crush 上之后，模型就能像你的 IDE 一样基于真实的符号解析来定位代码，而不是纯靠文本搜索猜。在crushrc里两行搞定：
lsp add go --command "gopls" --env "GOTOOLCHAIN go1.24.5" lsp add typescript --command "typescript-language-server" --args --stdio前提是对应的语言服务器（gopls、typescript-language-server）已装好并在 PATH 里。更多可用命令参考 配置文档。
权限白名单和忽略文件
默认情况下 Crush 每执行一个工具（读文件、改文件、跑命令）都会先征求你的同意。生产或高频使用场景下，可以把只读类工具加白名单，一行解决：
permissions allow view ls grep edit反过来，觉得某些工具不该让模型碰，直接拒绝并让它"看不见"：
permissions deny bash sourcegraph还有一个.crushignore文件，语法和.gitignore一样，放在项目根目录即可。比如你想把/build、/dist这类编译产物排除在上下文之外，写进去就行。
上生产之前要改什么
数据目录、更新策略与遥测
Crush 的运行时状态（会话、消息记录等）存在~/.local/share/crush/（Unix）或%LOCALAPPDATA%\crush\（Windows），里面是自动维护的 JSON，不要手改。备份时把这部分目录连同项目的crushrc一起打包即可。
默认情况下 Crush 会自动拉取最新的模型提供商目录（托管在开源仓库 Catwalk 上）。内网或离线环境要在crushrc里关掉：
option provider-auto-update false之后需要时手动更新，甚至可以用本地文件兜底：
crush update-providers /path/to/local-providers.json crush update-providers embedded # 重置为内置版本另外它默认上报匿名使用指标（不含任何 prompt 内容），介意可以在环境里设CRUSH_DISABLE_METRICS=1或DO_NOT_TRACK=1关掉。
安全审计清单
部署到共享服务器前过一遍这四条：
crushrc是会被执行的 shell 脚本，属于"受信代码"。上服务器前先人工 review 一遍项目里所有crushrc，不要从陌生来源source别人的配置。- 重新核对
permissions allow的白名单，只放行你确认过的工具；--yolo（跳过所有确认）除非隔离环境，否则别用。 - 全局上下文文件
~/.config/crush/CRUSH.md和~/.config/AGENTS.md会注入每一次会话，内容错了影响面很大，建议纳入版本控制。 - 注意共享后端（
crush serve）场景下，--yolo和--debug是"首个客户端生效"的规则，后来者带不同参数也不会改变已运行的工作区。
日常维护与排错
出问题时先看日志
日志写在项目目录下的./.crush/logs/crush.log，CLI 内置了查看命令：
crush logs # 看最后 1000 行 crush logs --tail 500 # 看最后 500 行 crush logs --follow # 实时跟踪需要更详细的输出时，用--debug参数启动，或在crushrc里写option debug true；怀疑是 LSP 的问题就再加option debug-lsp true。
改了配置不生效，按这个顺序排查
- 确认改对了文件：项目级
./.crushrc覆盖全局，检查你是不是改了全局配置却被项目级覆盖，或者相反——在错误的目录里改。 - 别往数据目录里写配置：
~/.local/share/crush和%LOCALAPPDATA%\crush只存运行时状态，Crush 不会从那里加载任何crushrc。 - 检查脚本是否中途失败：
crushrc是 Bash 脚本，前面的命令出语法错误时，后面的配置根本不会执行。可以把同样的内容贴进本地 bash 跑一遍验证。 - 确认改动确实加载了：打开
crush logs --follow再看一次启动过程，配置合并时的告警（比如同一目录 JSON 与 crushrc 并存）会打在这里。
后续可以扩展什么：接入 MCP
MCP（Model Context Protocol）是给你的模型"外挂工具"的标准协议，Crush 支持三种接入方式，用大白话说：stdio是 Crush 在本地起一个命令行进程、通过标准输入输出和它对话，适合本地服务；http是连远程 HTTP 端点，适合云端服务；sse（Server-Sent Events）是一种服务端持续推送的 HTTP 变体，适合需要实时回流的流式服务。加一个远程 MCP 服务器长这样：
mcp add remote-tools \ --type http \ --url "https://mcp.example.com/mcp" \ --header Authorization "Bearer $YOUR_TOKEN"除了 MCP，Crush 还内置了 hooks 机制（在 agent 生命周期的各个事件点执行你自己的脚本，比如拦截危险命令），感兴趣可以看 hooks 指南。
下一步：打开终端，挑一种方式把 Crush 装上，然后直接在你今天正在写的项目里跑起来——配置可以等它跑通了再逐项加。
【免费下载链接】crushGlamourous agentic coding for all 💘项目地址: https://gitcode.com/gh_mirrors/crush3/crush
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
