Crush 使用指南：在终端部署你的 LLM 命令行 AI 助手

1. Crush 是什么为什么要在命令行里养一个 AI 助手1.1 终端 LLM 工具的定位先说说我为什么会对 Crush 产生兴趣。平时在终端里干活最烦的就是三件事命令记不全、报错看不懂、脚本写半天。尤其是那些“你明明知道大概意思但就是想不起来具体参数”的命令每次都要切到浏览器去查 man 手册一查就是五分钟。后来我开始用各种 AI 编程助手但发现绝大多数都是网页版或者 IDE 插件真正工作在命令行里的不多而 Crush 就是那个“把 LLM 直接塞进终端”的另类。Crush 本质上是一个基于大语言模型LLM的命令行助手。它跟普通聊天机器人最大的区别在于它能直接读取你当前目录的文件结构、环境变量、最近执行的命令历史甚至能把你的自然语言直接转换成可在终端执行的命令。说得直白一点你把它装好、配好 API Key 之后就可以在终端里跟它说“帮我看看哪个进程占了 8080 端口”它会告诉你一条lsof -i :8080然后问你要不要直接执行。这种体验跟自己在键盘上敲命令完全不同更像是在带了一个随叫随到的助手。这个工具适合谁第一类是刚从 Windows 转到 Linux/macOS 的开发者命令不熟遇到问题不知道用什么工具第二类是每天要处理大量运维、数据处理、批量文件操作的工程师重复命令多需要快速生成脚本第三类是纯粹想体验“用自然语言操作终端”的极客用户。无论你是哪一类只要你的日常工作离不开命令行Crush 都能帮你省下不少时间。需要提前说明的是Crush 本身只是一个壳它要跑起来必须有 LLM 模型的 API 支持。你可以配置官方的 OpenAI 接口也可以配置任何兼容的模型服务。这个配置过程我会在后面详细讲。1.2 为什么选择命令行环境而不是图形界面可能有人会问我有 ChatGPT 网页版也有各种带 AI 的 IDE为什么还要专门在命令行里用一个 Crush这个问题的答案得从实际工作流说起。说一个我自己的场景。我在调一个后端服务的时候日志文件特别大几十万行我想快速找到某几个关键字附近的日志。如果切到浏览器里去问 AI我得先把日志内容复制粘贴过去还要担心上下文长度不够体验非常割裂。但用 Crush 就不一样了它直接运行在终端里可以用管道把日志内容喂给模型也可以让它直接生成一条grep命令帮我处理文件。模型生成的命令我确认后就直接执行整个过程不需要离开终端也不需要复制粘贴。另外还有一个很实际的原因很多服务器环境没有图形界面你只有 SSH 和一个黑乎乎的终端。这种时候就算是再强的网页版 AI 助手也帮不上忙因为 AI 看不到你的服务器环境。但 Crush 可以它就在终端里运行跟你在同一台机器上能感知当前目录、环境变量、甚至命令执行的结果。这个“本地感知”能力是网页版 AI 根本做不到的。所以 Crush 解决的并不是“能不能对话”的问题而是“AI 能不能跟我工作在同一个环境里”的问题。它把 LLM 从“回答问题”变成了“参与干活”这是本质区别。2. 环境准备与安装从零开始把 Crush 跑起来2.1 安装前的环境检查Crush 是用 Node.js 写的所以安装前你机器上必须要有 Node.js 环境。这里我建议使用 Node.js 18 及以上版本因为新版本对 ES Module 的支持更完善Crush 的依赖包在低版本 Node 上跑起来容易出一些莫名其妙的问题。先检查一下你本机的 Node 环境node -v npm -v如果没装或者版本太老我建议用 nvm 安装。nvm 的好处是可以多版本共存而且不需要 sudo 权限对开发机很友好。安装命令如下curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc # 如果你用的是 zsh就写 source ~/.zshrc nvm install 20 nvm use 20注意如果你用的是 macOS推荐直接用 Homebrew 安装 nvmbrew install nvm按照终端里的提示配置环境变量。如果你用的是 Windows建议先装 WSL2然后在 WSL 里操作体验会好很多。原生 Windows 的 CMD 和 PowerShell 也能跑但一些管道符和通配符的处理规则跟 Linux 不一样容易踩坑。装好 Node 之后顺便确认下 npm 源。国内网络环境下如果 npm 默认源下载太慢建议切换镜像源这个操作可以大幅提升后续安装速度npm config set registry https://registry.npmmirror.com注意这个镜像是用来加速 npm 包的不是用来替代什么网络工具的纯粹是为了下载依赖快点你可以放心使用。2.2 安装 Crush 的三种方式Crush 的安装方式有三种我分别说下适用场景。方式一npm 全局安装推荐这是最推荐的方式一条命令搞定后续升级也方便。在终端执行npm install -g crush-cli安装完成后验证crush --version如果能输出版本号说明安装成功。我实测中全局安装最省心因为crush命令会被自动放到 PATH 里任何时候打开终端都能直接用。方式二npx 临时运行如果你只是想在某个项目里试一下不想全局安装污染环境可以用 npx 直接跑npx crush-cli 你好介绍一下你自己npx 会临时下载并运行这个包用完不会有残留。这种方式适合尝鲜但每次调用都会经过 npx 的解析速度比全局安装慢一点。方式三源码安装如果你有二次开发需求或者想改 Crush 的代码那就要从源码装git clone https://github.com/crush-cli/crush.git cd crush npm install npm linknpm link会把当前目录链接到全局命令之后你在任何目录都能运行crush而且改完源码立刻生效。我自己的折腾经验是源码安装最容易出问题的是依赖版本冲突如果npm install报错多半是某个依赖包版本不对可以先删掉node_modules和package-lock.json再重新装。这三种方式的区别我整理成一张表方便你对号入座安装方式命令适用场景升级方式全局安装npm install -g crush-cli日常主力使用npm update -g crush-clinpx 临时运行npx crush-cli ...尝鲜、临时使用无需升级源码安装clone npm link二次开发、调试源码git pull npm install2.3 配置 LLM 模型服务Crush 装好之后还不能直接用需要配置模型服务。这一步的难点不在于操作而在于理解 Crush 的配置逻辑。Crush 的配置主要通过两个途径一是环境变量二是配置文件。推荐用配置文件因为方便多项目共用。首次运行 Crush 时它会自动在用户目录下创建配置文件夹。在 Linux/macOS 上是~/.crush/在 Windows 上是C:\Users\你的用户名\.crush\。你需要在这个目录下新建一个config.json文件内容大概是这样的{ provider: openai, apiKey: sk-你的密钥, model: gpt-4o-mini, temperature: 0.2, maxTokens: 2048, systemPrompt: 你是一个资深的命令行助手。回答问题要简洁优先给出可执行的命令。 }各字段含义provider模型服务商。如果用的是 OpenAI 官方接口就填openai如果用的是其他兼容服务也可以填自定义值后面配 baseUrl。apiKey你的 API 密钥注意不要提交到 Git 仓库里建议用环境变量注入。model模型名称。如果用的是 OpenAI可以填gpt-4o-mini或gpt-4o如果用的是国内模型服务就填对应的模型名。temperature随机性0 到 1 之间。命令行场景建议设低一点0.1 到 0.3 最合适减少模型“发挥失常”的概率。maxTokens单次回复的最大 token 数不用太大命令行场景 2048 够用了。systemPrompt系统提示词这是 Crush 的灵魂。你希望它用什么样的风格回答你都可以在这里定义。我见过很多人配置完发现不生效多半是格式问题。JSON 文件里不能有注释不能有尾随逗号这些都是新手最容易踩的坑。另外如果你不想明文把 API Key 写在配置文件里Crush 也支持从环境变量读取可以这样写export CRUSH_API_KEYsk-你的密钥然后在config.json里把apiKey字段的值写成${CRUSH_API_KEY}Crush 在启动时会自动替换。2.4 验证安装是否成功配置完成之后先别急着用高级功能跑一条最简单的命令验证crush 用一句话介绍你自己正常情况下Crush 会先显示“思考中”的动画然后输出一段文字。如果出现 HTTP 401 错误说明 API Key 不对如果出现超时说明网络访问模型服务时被卡住了。这里补充一个我自己的经验第一次配置的时候建议先用crush doctor命令做一次体检。这个命令会检查 Node 环境、配置文件、API Key 连通性等关键环节能帮你快速定位问题crush doctor如果所有检查项都通过就可以正式进入使用环节了。3. 核心功能实操把 AI 变成你的终端副驾3.1 自然语言直接执行命令Crush 最核心的功能就是把你说的自然语言翻译成命令。但要注意它不是简单地做命令翻译而是结合你当前的工作目录、文件类型、甚至之前的操作上下文来给出建议。举个例子。我有个目录里放了一堆.png截图想统一压缩一下于是输入crush 把当前目录下所有 png 图片压缩到原来的一半大小Crush 会返回类似下面这样的建议# 使用 ImageMagick 批量压缩 PNG 图片 for img in *.png; do convert $img -resize 50% compressed_$img done然后它会问你是否执行。这里有两个选择输入y直接执行输入n只保留建议不执行。我觉得这种“先确认再执行”的设计非常合理因为 AI 生成的命令不一定完全符合你的意图多一道确认环节能避免误操作。如果你想跳过确认直接执行可以在 Crush 里开启自动执行模式crush --force 删除当前目录下所有的 .tmp 文件但我个人非常不建议新手这么干。命令这个东西一旦执行错了轻则文件丢失重则环境损坏。我自己的习惯是默认开启确认只有在非常信任的、只读性的操作上才用自动执行。3.2 报错自动分析和修复第二个高频使用场景是报错分析。说实话我刚用 Crush 的时候主要就是拿它当“命令行报错翻译器”用。遇到报错你可以把报错信息直接粘贴给 Crushcrush 我运行 npm install 报错了错误信息是EACCES: permission denied, unlink ...帮我看看怎么解决Crush 会根据报错内容分析原因并给出解决方案。比如EACCES权限问题它会提示你当前 npm 缓存目录属于 root 用户建议修复权限或者改用 nvm 安装 Node。更进阶的用法是配合管道。如果你有一段命令的输出特别长可以把它直接喂给 Crush让它帮你定位关键信息npm install 21 | crush 帮我分析一下这个安装日志里有没有报错这个用法非常强大因为传统的grep只能按关键字过滤而 Crush 能理解整段日志的语义。我实测过几百行的安装日志它能很快定位到真正的错误位置并给出修复建议不需要我自己一行行翻。3.3 多步骤任务编排如果说前面两个功能还只是“命令翻译”那多步骤任务编排就是 Crush 真正拉开差距的地方。它能把一个复杂的任务拆解成多个步骤按顺序执行。举个例子。我之前有个任务是把项目目录下的.log文件都按日期归档到logs/2024/文件夹同时把 30 天前的日志压缩成.tar.gz。这个任务如果用 Shell 脚本写得先建目录、再移动文件、再压缩、再清理每一步都有坑。我用 Crush 试了一下crush 把当前目录下所有 .log 文件移动到 logs/2024-05 目录下然后压缩其中的老文件Crush 生成了一整段 Bash 脚本还带了注释每一步干什么写得清清楚楚。我确认后它逐行执行遇到错误还会停下来问我怎么处理。这种多步骤任务对 Crush 来说其实是“吃上下文”的过程它需要知道你当前目录下有哪些文件、哪些文件夹已经存在、哪些文件不能乱动。所以使用这类功能时我建议先cd到目标目录再跟 Crush 对话否则它只能凭“想象”生成命令很容易出错。3.4 上下文记忆与会话管理Crush 还有一个容易被忽略但很实用的功能——会话管理。默认情况下Crush 的每一次交互都是独立的它不记得你之前说过什么。但如果你开启会话模式它就能记住上下文像聊天一样连续对话。开启会话模式crush chat进入会话模式后CRUSH 的提示符会变成crush你可以连续输入多条指令它会结合之前的对话来理解新指令。比如你先问它“帮我看看这个目录下有哪些大文件”它列出了几个超大文件然后你接着问“把最大的那个删掉”它能根据前文理解你说的“最大的那个”指哪个文件。会话记录默认保存在~/.crush/sessions/目录下以时间戳命名。你可以用crush sessions查看历史会话也可以crush resume 会话ID恢复之前的对话。这个功能适合那种需要反复调试的复杂任务——做到一半去吃饭了回来还能接着聊不会丢失上下文。我自己使用了很长一段时间发现最实用的场景是配合“操作历史”Crush 能知道你之前让终端执行过哪些命令当你说“刚才那条命令报错了”时它能智能地联系上下文不用你重新粘贴一堆报错信息。4. 实用技巧与安全边界防坑指南4.1 权限与命令执行的确认机制刚才提到过Crush 默认所有命令都需要确认才能执行。但这里有一个细节值得单独说说Crush 可以区分为安全的只读命令和可能有副作用的写命令。我自己使用的版本里对于ls、pwd、cat这类安全命令Crush 会绿色显示并直接执行对于rm、mv、chmod这类可能影响系统的命令Crush 会黄色高亮并强制要求确认甚至还会在确认前提示一句“此命令有较高风险是否真的要执行”所以我的使用习惯是越是对系统影响大的操作越要让 Crush 多“啰嗦”几步。万一它生成了一条rm -rf而且指向了错误路径你又刚好手滑按了确认那真的是后悔都来不及。为了避免这种灾难我强烈建议你在配置里加上一条限制{ dangerouslyIgnoreConfirmation: false }把这个值保持为false就永远不会关闭确认机制。4.2 自定义系统提示词让 Crush 更懂你Crush 默认的 system prompt 是按通用场景配置的但你完全可以改造成适合自己工作流的“私人助手”。我自己在配置里加了这样一段{ systemPrompt: 你是运行在 Linux 终端里的资深运维工程师。回答要求1. 优先给出最简洁、最安全的命令2. 解释命令时不超过两句话3. 如果存在风险操作必须先提醒风险再执行4. 涉及文件删除时必须额外确认。 }加了这段提示词之后Crush 的回答风格立刻就不一样了废话少了建议更谨慎了删除操作前一定会多问一句。这个效果比调任何参数都明显建议每个用户都根据自己的工作场景定制一段 prompt。有些用户可能希望在项目里用不同的 prompt可以用crush --prompt-file ./crush-prompt.txt指定提示词文件实现“一项目一配置”。我在团队里就把这个文件放到了 Git 仓库新同事克隆下来就能获得一致的 AI 助手行为。4.3 长输出与大文件处理技巧Crush 同样面临 LLM 的上下文长度限制。如果你让它读取的文件太大或者让它分析的日志太多它可能会截断内容导致判断不准确。解决这个问题有几种思路。第一种是让 Crush 不是直接读文件内容而是生成一条命令来处理文件。比如别问它“这个日志文件的错误在哪”而是问它“帮我写一条命令统计这个日志文件里 ERROR 级别的错误出现次数”。这种方式模型不需要读取文件内容只负责生成命令绕开了上下文限制。第二种是用管道做预筛选。比如tail -200 app.log | crush 分析一下这几行日志里有没有异常先把大文件用tail、grep、awk等命令缩小到几百行再交给 Crush 处理这样既保留了关键信息又不会超出模型的上下文窗口。我在分析线上问题时经常用这个组合拳效果比直接crush 分析 app.log好得多因为后者往往会把模型“撑爆”。4.4 与其他终端工具的整合Crush 不是孤立的它跟终端里的其他工具配合起来效果更好。我自己最常用的组合是fzf模糊查找crush命令理解。比如我用fzf找历史命令觉得某条命令不够对就可以把它作为输入塞给 Crush 改写history | fzf | crush 优化这条命令加上错误处理这个用法真的让我觉得“终端是我的第二大脑”。类似地Crush 还可以跟tmux联动。由于 Crush 本质上是终端里的一个 TUI 程序它可以直接跑在 tmux 的某个窗格里左边是终端操作区右边是 Crush 会话区互不干扰。我日常开发就开一个全屏 tmux左侧编辑代码右侧开 Crush 随时提问体验接近“AI 结对编程”。如果你用zshoh-my-zsh还可以把 Crush 设置成 shell 的 alias比如在.zshrc里加一行alias ccrush chat这样只需要输入c就能进入 Crush 对话模式省去了每次敲完整命令的麻烦。5. 常见问题排查与技巧实录5.1 安装失败权限、网络、版本兼容安装 Crush 最常见的报错就是 EACCES 权限不足。这个问题在 Linux 和 macOS 上很普遍尤其是你直接用系统自带 Node 而不是 nvm 安装时。解决办法很简单不要用 sudo 去装 npm 全局包正确做法是用 nvm 管理 Node这样 npm 全局目录就在你自己用户权限下不会出现权限问题。另一种情况是安装时网络超时或下载缓慢。这通常跟 npm 源有关可以按我前面说的方式切换镜像源后再试。如果切换后依然失败可以清理 npm 缓存npm cache clean --force rm -rf node_modules package-lock.json npm install如果是 Node 版本太低导致编译失败升级 Node 到 18 基本能解决。具体报错信息各种各样但如果安装了node-gyp相关的错误那多半是系统缺少编译工具链macOS 上要装 Xcode Command Line Toolsxcode-select --installLinux 上要装build-essential。5.2 认证失败与 API 配置错误经常有人问我“明明配置了 key为什么 Crush 还是报 401”这个问题九成是环境变量没生效。Crush 读取 key 的顺序是配置文件优先环境变量次之。如果你在配置文件的apiKey里写了${CRUSH_API_KEY}但环境变量没有导出就会变成字面量${CRUSH_API_KEY}自然通不过认证。解决办法是检查两处一是echo $CRUSH_API_KEY确认环境变量有值二是把环境变量加到~/.zshrc或~/.bashrc里并重新加载source ~/.zshrc。如果你用的是自定义模型接口还要检查baseUrl是否配置正确。很多兼容 OpenAI 的服务商其接口地址并不是根域名而是/v1开头的完整路径。我见过一个哥们把地址填成了https://api.example.com而实际需要的地址是https://api.example.com/v1结果折腾了一下午。这个问题通过crush doctor其实可以提前发现它会发送一个极简请求来测试连通性如果接口地址不对会直接报出来。5.3 响应慢或卡住不动Crush 卡住不动最常见的原因是网络问题。这里有个小技巧可以在配置里给模型请求加一个超时设置{ timeoutMs: 30000 }这个值表示请求超过 30 秒就超时返回报错而不是无限期等待。另外如果使用自定义接口排查超时问题可以用 curl 手动测试接口连通性curl -X POST https://api.example.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $CRUSH_API_KEY \ -d {model:your-model,messages:[{role:user,content:ping}]}如果 curl 能快速返回结果说明接口没问题问题出在 Crush 的配置或参数上如果 curl 也卡住那就是网络或服务端的问题了。5.4 模型输出格式与单次回复长度控制有些模型回复特别啰嗦明明一条命令能解决的事非要给你写 100 字的解释。这种问题可以在 systemPrompt 里强调“只输出命令不要解释”也可以调整maxTokens和temperature来约束。但我更推荐的做法是把maxTokens调低一点比如 1024。因为命令行场景下一个 1024 token 的输出已经足够包含命令和简短备注了。如果模型因为输出截断导致命令不完整可以告诉 Crush “命令被截断了请从断点继续”它会尽力续上。当然最稳妥的还是生成后直接人工检查一遍再执行毕竟任何 AI 工具都是辅助不是替你做决定。5.5 资源占用与日志排查Crush 本身很轻量系统资源占用主要来自 Node.js 运行时通常几十 MB 内存对现代电脑来说毫无压力。但如果你开启了大量会话并且每个会话都存了大量上下文磁盘占用会逐步增大。想清理历史会话可以直接删除~/.crush/sessions/下不需要的文件也可以用 Crush 自带的清理命令crush sessions clean --keep 10意思是保留最近 10 个会话其余删除。Crush 的运行日志保存在~/.crush/logs/如果你遇到无法解释的崩溃可以查看日志定位问题。V 在开源工具里算常规操作了也不复杂。这里再分享一个我的工作习惯我每天开工第一件事是crush sessions clean --keep 3保证会话目录不膨胀每周五会跑一次crush doctor做健康检查顺便更新一下依赖包npm update -g crush-cli。这个组合我跑了很久一直没出过什么大问题。根据我个人这段实际使用的经验Crush 真正打动我的地方在于它不是把聊天窗口搬进终端而是让 AI 直接参与命令的生成、确认和执行。这种“AI 在劳动你在审核”的工作模式跟传统的“AI 在回答你在执行”完全不是一回事。如果你是命令行重度用户强烈建议花半个下午把它配置好然后试着让 Crush 处理一次之前需要半小时的手工命令你会感受到那种“人机协同”的痛快。最后再补充一个小技巧遇到拿不准风险大小的命令时先让 Crush 输出命令但不执行然后你手动拆解每一步的意图确认无误后再逐条执行放心这个流程你操作几回之后就会彻底信任它了。