接入 Crush

Crush 是由 Charm 团队开发的开源终端 AI 编程 Agent，以现代华丽的终端界面、低资源占用、原生开发工具链集成为核心特色，支持多模型无缝切换、LSP（语言服务器协议）集成、MCP 服务器对接、代理式编码工作流，能够直接在终端内完成代码读取、修改、调试、运行全流程，无需切换至浏览器或其他GUI工具，是终端重度开发者的效率利器。

将 DeepSeek V4 系列模型接入 Crush，可充分发挥 DeepSeek 超强的代码理解能力、百万级上下文窗口，结合 Crush 的 LSP 集成能力，无需手动粘贴代码即可直接理解整个项目的结构、类型定义、依赖关系，在复杂项目重构、Bug 排查、功能迭代等场景下获得远超通用AI助手的体验。本教程将指导你完成全流程配置，阅读完成后你将能够使用 DeepSeek 模型作为 Crush 的默认编程助手，享受终端原生的AI编码体验。

1. 安装 Crush

操作目的：全局安装 Crush 命令行工具，实现系统任意路径下的快速调用。 前置环境检查：Crush 依赖 Node.js 运行时，执行 node -v 确认已安装 Node.js，官方推荐使用 LTS 版本以获得最佳兼容性。国内用户可通过 Node.js 中文网 下载安装，或使用 nvm 进行版本管理。

• 安装 Node.js。
• 在命令行界面，执行以下命令安装 Crush：

npm install -g @charmland/crush

国内用户优化：npm 下载速度慢可追加淘宝镜像参数：npm install -g @charmland/crush --registry=https://registry.npmmirror.com 权限问题解决：Linux/macOS 提示权限不足可追加 sudo，Windows 用户需以管理员身份运行 PowerShell。

• 安装结束后，执行以下命令，若显示版本号则安装成功：

crush --version

注意： macOS 用户也可以通过 Homebrew 安装：brew install charmbracelet/tap/crush。 该方式适合 macOS 用户，自动处理依赖与环境变量配置，后续可通过 brew upgrade charmbracelet/tap/crush 一键升级到最新版本。

预期结果：执行 crush --version 正常输出版本号（如 v0.9.2）即表示安装成功。若首次运行 crush 命令，会自动生成默认配置文件与目录结构。

2. 配置 DeepSeek 供应商

操作目的：将 DeepSeek 添加为 Crush 的自定义模型供应商，使 Crush 能够识别并调用 DeepSeek 系列模型。 前置操作：若配置文件路径不存在，先执行一次 crush 命令，程序会自动生成对应的配置目录与默认配置文件，无需手动创建。

Crush 支持通过 OpenAI 兼容 API 添加自定义供应商。在配置文件中添加 DeepSeek：

• Linux / macOS：~/.config/crush/crush.json
• Windows：%USERPROFILE%\.config\crush\crush.json

{
  "$schema": "https://charm.land/crush.json",
  "providers": {
    "deepseek": {
      "type": "openai-compat",
      "base_url": "https://api.deepseek.com",
      "api_key": "$DEEPSEEK_API_KEY",
      "models": [
        {
          "id": "deepseek-v4-pro",
          "name": "DeepSeek-V4-Pro",
          "context_window": 1048576,
          "default_max_tokens": 32768,
          "can_reason": true
        },
        {
          "id": "deepseek-v4-flash",
          "name": "DeepSeek-V4-Flash",
          "context_window": 1048576,
          "default_max_tokens": 32768,
          "can_reason": true
        }
      ]
    }
  }
}

配置字段说明：

其中 API Key 在 DeepSeek 开放平台 获取。

设置环境变量： 操作目的：将 DeepSeek API Key 存储在环境变量中，既避免明文泄露，又可以在多个工具间共享配置。

Linux / Mac 用户：

export DEEPSEEK_API_KEY="<你的 DeepSeek API Key>"

Windows 用户：

$env:DEEPSEEK_API_KEY="<你的 DeepSeek API Key>"

永久生效配置：Linux/macOS 用户可将 export 命令添加至 ~/.zshrc、~/.bashrc 等配置文件；Windows 用户可添加至系统环境变量，避免每次重启终端重新设置。 可选配置：若你不使用环境变量，也可直接将 api_key 字段替换为你的 sk- 开头的 API Key，但该方式安全性较低，不推荐在公共设备上使用。 验证方法：执行 echo $DEEPSEEK_API_KEY（Linux/macOS）或 echo $env:DEEPSEEK_API_KEY（Windows），正确输出你的 API Key 即表示设置成功。

3. 运行并选择模型

操作目的：进入目标项目目录启动 Crush，Crush 会自动读取项目下的代码、Git 记录、LSP 信息，实现项目级上下文感知。

• 进入项目目录并执行 crush 命令：

cd /path/to/my-project
crush

• 按 Ctrl+L（或输入 /model）打开模型切换器。
• 选择 DeepSeek 供应商，然后选择 DeepSeek-V4-Pro 或 DeepSeek-V4-Flash。
• 开始与你的终端编程新搭档一起编码 💘

操作细节说明：打开模型切换器后，可通过方向键上下选择供应商与模型，按回车键确认切换。切换完成后，界面左下角会显示当前使用的模型名称。 测试方法：输入测试指令（如「帮我检查当前项目下 src/index.js 文件的语法错误，并给出修复方案」），若 Crush 能够自动读取文件内容并返回正确结果，即表示配置成功。 最佳实践：简单代码生成、快速问答场景选择 DeepSeek-V4-Flash，响应速度更快、使用成本更低；复杂 Bug 排查、架构设计、大文件重构场景选择 DeepSeek-V4-Pro，推理能力更强、结果更准确。

注意事项与避坑指南

1. 配置文件不生效：若修改配置后模型未出现在选择器中，检查 JSON 格式是否正确，是否存在多余逗号、引号不匹配等问题；确认配置文件保存到了正确的路径，Crush 会自动检测配置文件变化，无需重启程序。
2. API 认证错误：检查环境变量 DEEPSEEK_API_KEY 是否正确设置，是否存在多余空格；确认 API Key 未过期、有可用配额。
3. 网络访问超时：国内用户可将配置中的 base_url 替换为中国区端点 https://api.deepseeki.com，降低网络延迟。
4. LSP 功能不生效：确保你已安装对应编程语言的 LSP 服务器（如 TypeScript 的 typescript-language-server、Python 的 pyright），Crush 会自动检测并连接已安装的 LSP 服务器。

常见问题（FAQ）

1. Crush 无法读取项目文件怎么办？

   • 排查步骤：确认你已 cd 到正确的项目目录，且对目录下的文件有读取权限；检查是否有 .gitignore 或 .crushignore 文件屏蔽了目标文件的读取权限。

2. 提示 rate limit exceeded 速率限制错误怎么办？

   • 解决方案：稍等片刻后重试，或前往 DeepSeek 开放平台控制台提升速率限制；若为批量任务场景，可适当降低请求频率，避免触发限流。

3. 模型输出的代码存在截断怎么办？

   • 解决方案：调整配置文件中对应模型的 default_max_tokens 为更大的值（最大支持 128000），允许模型输出更长的内容。

参考资料

• awesome-deepseek-agent：可查看更多 DeepSeek 生态的 Agent 工具与最佳实践。