crush:基于 Charm 生态的多模型终端 AI 助手项目

Glamourous agentic coding for all 💘

Branch148Tags198
This repository is empty

Crush

Charm Crush 徽标
最新版本 构建状态

你的新编程搭子,现已登陆你喜爱的终端。
你的工具、你的代码、你的工作流,深度接入你选定的 LLM。

终端里的编程新搭档,
无缝接入你的工具、代码与工作流,全面兼容主流 LLM 模型。

Crush 演示

功能

  • 多模型: 可从众多 LLM 中选择,也可通过兼容 OpenAI 或 Anthropic 的 API 添加自己的模型
  • 灵活: 可在会话中途切换 LLM,同时保留上下文
  • 基于会话: 每个项目可维护多个工作会话与上下文
  • LSP 增强: Crush 会像你一样借助 LSP 获取额外上下文
  • 可扩展: 通过 MCP 添加能力(httpstdiosse
  • 全平台可用: 在 macOS、Linux、Windows(PowerShell 与 WSL)、Android、FreeBSD、OpenBSD 和 NetBSD 的所有终端中均提供一流支持
  • 工业级: 基于 Charm 生态构建,为 25k+ 应用提供支撑,从头部开源项目到关键业务基础设施

安装

使用包管理器:

# Homebrew
brew install charmbracelet/tap/crush

# NPM
npm install -g @charmland/crush

# Arch Linux (btw)
yay -S crush-bin

# Nix
nix run github:numtide/nix-ai-tools#crush

# FreeBSD
pkg install crush

Windows 用户:

# Winget
winget install charmbracelet.crush

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

Crush 可通过官方 Charm 的 NUR 中的 nur.repos.charmbracelet.crush 获取,这是在 Nix 中使用 Crush 的最新方式。

你也可以使用 nix-shell 在 NUR 中试用 Crush:

# Add the NUR channel.
nix-channel --add https://github.com/nix-community/NUR/archive/main.tar.gz nur
nix-channel --update

# Get Crush in a Nix shell.
nix-shell -p '(import <nur> { pkgs = import <nixpkgs> {}; }).repos.charmbracelet.crush'

通过 NUR 使用 NixOS 与 Home Manager 模块

Crush 通过 NUR 提供 NixOS 和 Home Manager 模块。 你可以在 flake 中直接从 NUR 导入并使用这些模块。由于它会自动检测当前是 Home Manager 还是 NixOS 上下文,因此可以用完全相同的方式导入 😃

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    nur.url = "github:nix-community/NUR";
  };

  outputs = { self, nixpkgs, nur, ... }: {
    nixosConfigurations.your-hostname = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        nur.modules.nixos.default
        nur.repos.charmbracelet.modules.crush
        {
          programs.crush = {
            enable = true;
            settings = {
              providers = {
                openai = {
                  id = "openai";
                  name = "OpenAI";
                  base_url = "https://api.openai.com/v1";
                  type = "openai";
                  api_key = "sk-fake123456789abcdef...";
                  models = [
                    {
                      id = "gpt-4";
                      name = "GPT-4";
                    }
                  ];
                };
              };
              lsp = {
                go = { command = "gopls"; enabled = true; };
                nix = { command = "nil"; enabled = true; };
              };
              options = {
                context_paths = [ "/etc/nixos/configuration.nix" ];
                tui = { compact_mode = true; };
                debug = false;
              };
            };
          };
        }
      ];
    };
  };
}
Debian/Ubuntu
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
Fedora/RHEL
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

或者,直接下载:

  • 提供 Debian 和 RPM 格式的 软件包
  • 提供适用于 Linux、macOS、Windows、FreeBSD、OpenBSD 和 NetBSD 的 二进制文件

也可以使用 Go 直接安装:

go install github.com/charmbracelet/crush@latest

在 illumos(OpenIndiana、OmniOS)上,上述命令可直接使用。那里仅原生 OS 通知不可用;基于终端的通知(OSC)和终端铃声仍可正常工作。在 Oracle Solaris 上,添加 -tags sqlite3_dotlk,使本地数据库使用 dot-file 锁定:

go install -tags sqlite3_dotlk github.com/charmbracelet/crush@latest

Warning

使用 Crush 可能会提升你的生产力;初次使用时,你也可能会发现自己被极客话题深深“上头”。如果这种症状持续,请加入 SlackDiscord,把这份“上头”传染给其他伙伴。

快速入门

入门最快的方式,是在模型选择器中选择一个 Hyper 模型。按步骤完成认证,即可开始使用。

来自 Charm 的 Hyper 是 Crush 的官方提供商。它采用订阅制,提供免费层级,并针对 Crush 优化。它注重隐私,支持零数据留存(ZDR),并旨在符合 GDPR。了解 Hyper 的更多信息

Charm Hyper

API 密钥

你也可以使用 Crush 搭配许多其他提供商,例如 Anthropic、OpenAI、Gemini、OpenRouter 等。按下 ctrl+l 打开模型选择器,选择你偏好的提供商,然后粘贴你的 API 密钥。

当然,你也可以为常用提供商设置环境变量:

环境变量 提供商
HYPER_API_KEY Charm Hyper
ANTHROPIC_API_KEY Anthropic
OPENAI_API_KEY OpenAI
VERCEL_API_KEY Vercel AI Gateway
GEMINI_API_KEY Google Gemini
ZAI_API_KEY Z.ai
MINIMAX_API_KEY MiniMax
SYNTHETIC_API_KEY Synthetic
HF_TOKEN Hugging Face Inference
CEREBRAS_API_KEY Cerebras
OPENROUTER_API_KEY OpenRouter
IONET_API_KEY io.net
ALIBABA_SINGAPORE_API_KEY Alibaba (Singapore)
ALIBABA_US_API_KEY Alibaba (United States)
GROQ_API_KEY Groq
AVIAN_API_KEY Avian
OPENCODE_API_KEY OpenCode Zen & Go
VERTEXAI_PROJECT Google Cloud VertexAI(Gemini)
VERTEXAI_LOCATION Google Cloud VertexAI(Gemini)
AWS_ACCESS_KEY_ID Amazon Bedrock(Claude)
AWS_SECRET_ACCESS_KEY Amazon Bedrock(Claude)
AWS_REGION Amazon Bedrock(Claude)
AWS_PROFILE Amazon Bedrock(自定义配置)
AWS_BEARER_TOKEN_BEDROCK Amazon Bedrock
AZURE_OPENAI_API_ENDPOINT Azure OpenAI 模型
AZURE_OPENAI_API_KEY Azure OpenAI 模型(使用 Entra ID 时可选)
AZURE_OPENAI_API_VERSION Azure OpenAI 模型
MOONSHOT_API_KEY Moonshot

另外请注意,Crush 几乎支持任何提供商,包括 本地模型。更多信息请参见下文的 自定义提供商

顺便一提

你是否希望在 Crush 中支持某个提供商?是否有现有模型需要更新?

Crush 的默认模型列表由 Catwalk 管理,它是一个社区支持的开源仓库,收录兼容 Crush 的模型,欢迎参与贡献。

Catwalk Badge

配置

Tip

Crush 自带一个用于配置自身的内置技能。大多数情况下, 你只需告诉它想要配置的内容,它就能完成相应设置。

Crush 无需任何配置也能出色运行。当然,如果你确实需要或想要定制 Crush,可以通过 crushrc 来实现。

crushrc 只是在 Bash 中加入了一些 Crush 专属的内置命令。它非常像 .bashrc,只不过专门服务于你的 Crush。由于 Crush 拥有原生内置的 Bash 解释器,基于 Bash 的配置在所有平台(包括 Windows)上都能保持一致。

例如:

# 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

# Include some other file on a specific machine.
if [[ $HOSTNAME == "babysquid" ]]; then
    source ~/my-stuff/babysquid.sh
fi

# 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')"

配置可以添加在项目本地,也可以全局设置,优先级如下:

优先级 Unix 类 Windows
1 ./.crushrc .\.crushrc
2 ./crushrc .\crushrc
3 ~/.config/crush/crushrc %USERPROFILE%\.config\crush\crushrc

(Crush 遵循 XDG 基础目录规范,因此你的路径可能会因 XDG_CONFIG_HOME 的取值不同而有所差异。像 ~/.local/share/crush%LOCALAPPDATA%\crush 这类数据目录仅包含 JSON 状态数据;Crush 不会执行其中的 crushrc 文件。)

那么旧的 JSON 格式呢?它仍然受支持,但应视为已弃用。详情见:配置文档

Tip

可通过设置以下变量来覆盖用户配置和数据配置位置:

  • CRUSH_GLOBAL_CONFIG
  • CRUSH_GLOBAL_DATA

补充说明:Crush 还会在另一个额外位置保存临时数据,例如应用状态。这些是状态数据,不应手动编辑,也不应视为配置。

# Unix
$HOME/.local/share/crush/crush.json

# Windows
%LOCALAPPDATA%\crush\crush.json

安全提示

crushrccrush.json 都是可信代码;crushrc 会在完整 Shell 中运行, crush.json 中的任何 $(...) 都会在加载时执行。不要在未审阅其配置的目录中启动 Crush, 也不要随意将来自互联网的文件通过 source 引入你的配置。

环境变量

顶层 env 字段会在启动时、在配置提供商之前设置环境变量。 对于影响提供商身份验证的变量(例如 AWS SDK 凭证链),这非常有用, 无需将 crush 命令封装在 Shell 脚本中,也无需在 Shell 配置文件中导出它们:

{
  "$schema": "https://charm.land/crush.json",
  "env": {
    "AWS_PROFILE": "my-sso-profile"
  }
}

值支持与其他配置字段相同的 $VAR$(command) 展开,因此你可以引用现有环境变量,或执行 shell 命令来获取某个值。

LSPs

Crush 可以借助 LSPs 获取额外上下文,辅助其做出决策,就像你会做的那样。LSPs 可按如下方式手动添加:

# crushrc

lsp add go --command "gopls" --env "GOTOOLCHAIN go1.24.5"
lsp add typescript --command "typescript-language-server" --args --stdio
lsp add nix --command "nil"

MCPs

Crush 同样支持 Model Context Protocol (MCP) 服务器,涵盖三种传输类型:stdio 面向命令行服务器,http 面向 HTTP 端点,sse 面向 Server-Sent Events。

# crushrc

# Add a local MCP server that runs a Node.js script.
mcp add filesystem --command node --args /path/to/mcp-server.js \
  --timeout 10 --disabled-tools some-tool-name --env NODE_ENV production

# Add a GitHub MCP server that uses an API token.
mcp add github --type http --url https://api.github.com/mcp/ \
  --timeout 10 --header Authorization "Bearer $GH_PAT" \
  --disabled-tools create_issue --disabled-tools create_pull_request

# Add a streaming MCP server that uses SSE.
mcp add streaming-service --type sse --url "https://example.com/mcp/sse" \
  --timeout 10 --header API-Key "$API_KEY"

MCP OAuth

需要 OAuth 的 HTTP 和 SSE MCP 服务器可以使用 Crush 内置的 授权码流程,而不是静态 Authorization 请求头。设置 "oauth": true 即可启用:

{
  "mcp": {
    "linear": {
      "type": "http",
      "url": "https://mcp.linear.app/mcp",
      "oauth": true
    }
  }
}
预注册客户端

部分服务器(GitHub、Slack)不支持动态客户端注册。 对于此类服务器,请在服务提供商处注册一个 OAuth 应用,并直接提供 凭据。所有值均支持 shell 展开:

{
  "mcp": {
    "github": {
      "type": "http",
      "url": "https://api.github.com/mcp/",
      "oauth": true,
      "oauth_client_id": "Iv1.abc123def456",
      "oauth_client_secret": "$GITHUB_MCP_SECRET",
      "oauth_callback_port": 40704
    }
  }
}

当设置 oauth_client_id 时,Crush 会跳过动态客户端注册,并以指定客户端的身份进行身份验证。若省略该值,Crush 会自动尝试动态注册(适用于 Linear、Notion 以及其他支持 RFC 7591 的服务器)。

无会话服务器

某些 HTTP MCP 服务器是无会话的——它们从不颁发 Mcp-Session-Id,并拒绝 Crush 为接收列表变更通知而打开的 subscriptions/listen 流,否则会导致连接中断。Crush 会自动检测已知的无会话服务器(GitHub MCP、api.githubcopilot.com/mcp),因此这些服务器无需额外配置。

对于其他无会话服务器,请显式添加 "sessionless": true 进行标记(或在 crushrc 中设置 --sessionless true);若将其设置为 false,则对自动检测到的 URL 强制使用默认行为。相应的取舍是,无会话服务器不会实时推送工具/提示词/资源的列表变更通知。

Hooks

Crush 已初步支持 Hooks。详情参见 Hooks 指南

跨客户端共享工作区

当 Crush 运行在共享后端上时(例如两个 TUI 连接同一个 crush serve),客户端会按其解析后的 --cwd 分组到 工作区 中。拥有相同 --cwd 的两个客户端会加入同一个底层工作区,因此共享会话列表、消息历史、权限队列、LSP 和 MCP 状态。

加入过程是隐式的:将第二个客户端指向同一工作目录,就会将其附加到现有工作区。不过,每次新启动默认都会开启一个全新会话。要接手另一个客户端已打开的对话,请使用会话管理器(会话选择器)并选中该会话。会话管理器中会显示两个信号:

  • IsBusy 在该会话有代理回合正在执行时会被置位。
  • AttachedClients 会报告当前有多少客户端正在查看该会话。

非零的 AttachedClients(通常与 IsBusy 一起出现)表示该会话正在另一个客户端上“进行中”,加入后会实时镜像该视图。

第一个创建工作区的客户端会固定该工作区的进程级标志。具体来说,--yolo--debug 遵循 首个客户端优先 规则:之后携带不同标志值到达同一 --cwd 的客户端不会改变正在运行的工作区。系统会输出一条调试日志以记录该不一致,工作区仍保留创建时所使用的标志。

只要至少有一个客户端针对该工作区保持打开 SSE 事件流,工作区就会持续存在。当最后一个流断开时,工作区会被销毁。POST /v1/workspaces 之后有一个短暂的宽限窗口,确保已创建工作区但尚未打开事件流的客户端在成功附加前不会被回收。

全局上下文文件

Crush 会自动包含两个文件,用于存放跨项目指令。可以将其理解为对系统提示词的个性化补充。

  • ~/.config/crush/CRUSH.md:仅适用于 Crush 的规则,这些规则可能让其他智能体编程工具感到困惑。如果你只使用 Crush,那么这是唯一需要编辑的文件。
  • ~/.config/AGENTS.md:通用指令,其他编程工具也可能读取。请避免在此处提及 Crush 特有的功能或工作流。如果你同时使用多个智能体编程工具,并希望在这些工具之间共享指令,可能才会关注这个文件。

你可以使用 option global-context-path 自定义这些路径。重复执行该命令以添加多个路径:

# Load a single markdown file.
option global-context-path "~/path/to/custom/context/file.md"

# Recursively load all Markdown files in the folder.
option global-context-path "/full/path/to/folder/of/files/"

忽略文件

默认情况下,Crush 会遵循 .gitignore 文件。你也可以创建一个 .crushignore 文件,用来指定 Crush 需要额外忽略的文件和目录。这在你想让某些文件保留在版本控制中,但不希望 Crush 在提供上下文时考虑这些文件时非常有用。

.crushignore 文件使用与 .gitignore 相同的语法,可以放在项目根目录或子目录中。

允许工具

默认情况下,Crush 在执行工具调用前会向你请求权限。如果你需要,可以允许工具在没有权限提示的情况下直接执行。请谨慎使用。

permissions allow view ls grep edit mcp_context7_get-library-doc

禁用内置工具

你也可以禁用工具,使其对智能体完全隐藏:

permissions deny bash sourcegraph

如需禁用来自 MCP 服务器的工具,请参阅 MCP 配置部分

人生只有一次

你还可以通过添加 --yolo 标志运行 Crush,完全跳过所有权限提示。请务必格外谨慎地使用此功能。

禁用技能

你可以完全禁止 Crush 使用某些技能。被禁用的技能将对智能体隐藏,包括内置技能以及从磁盘中发现的技能。

option disable-skill crush-config

Agent Skills

Crush 支持 Agent Skills 开放标准,用于通过可复用的技能包扩展代理能力。技能是包含 SKILL.md 文件的文件夹,其中保存供 Crush 按需发现和激活的说明。

我们会在全局以下路径查找技能:

  • $CRUSH_SKILLS_DIR
  • $XDG_CONFIG_HOME/agents/skills~/.config/agents/skills/
  • $XDG_CONFIG_HOME/crush/skills~/.config/crush/skills/
  • ~/.agents/skills/
  • ~/.claude/skills/
  • 在 Windows 上,我们_也会_查看
    • %LOCALAPPDATA%\agents\skills\%USERPROFILE%\AppData\Local\agents\skills\
    • %LOCALAPPDATA%\crush\skills\%USERPROFILE%\AppData\Local\crush\skills\
  • 通过 options.skills_paths 配置的其他路径

除此之外,我们_还会_从以下相对路径加载项目中的技能:

  • .agents/skills
  • .crush/skills
  • .claude/skills
  • .cursor/skills

或者在配置中明确指定要加载的技能目录:

option skill-path "$HOME/squid-skills" "./other-skills"

你可以从 anthropics/skills 中的示例技能入手:

# Unix
mkdir -p ~/.config/crush/skills
cd ~/.config/crush/skills
git clone https://github.com/anthropics/skills.git _temp
mv _temp/skills/* . && rm -rf _temp
# Windows (PowerShell)
mkdir -Force "$env:LOCALAPPDATA\crush\skills"
cd "$env:LOCALAPPDATA\crush\skills"
git clone https://github.com/anthropics/skills.git _temp
mv _temp/skills/* . ; rm -r -force _temp

用户可调用技能

技能可被设置为命令,并通过命令面板 (ctrl+p) 调用。在技能的 YAML frontmatter 中添加 user-invocable: true

---
name: my-hot-skill
description: A skill that can be invoked as a command.
user-invocable: true
---

可由用户调用的技能会在命令面板中以 user:project: 前缀显示:

  • 来自全局目录的技能显示为 user:skill-name
  • 来自项目目录的技能显示为 project:skill-name

调用时,技能的说明会加载到对话上下文中。

若要阻止模型自动触发某个技能(同时仍允许用户调用),请添加 disable-model-invocation: true

---
name: my-skill
description: Only invocable by users, not the model.
user-invocable: true
disable-model-invocation: true
---

带有 disable-model-invocation 的技能不会显示在模型的可用技能列表中,但仍可由用户手动调用。

桌面通知

在工具调用需要权限,以及智能体结束当前轮次时,Crush 会发送桌面通知。 它们只在终端窗口未处于聚焦状态 并且 终端支持上报焦点状态时才会发送。

# Choose auto, native, osc, bell, or disabled.
option notifications disabled

auto 在本地使用原生通知,并在支持时通过 SSH 使用 OSC 通知。

初始化

初始化项目时,Crush 会分析你的代码库,并创建一个上下文文件,帮助它在后续会话中更高效地工作。默认情况下,该文件名为 AGENTS.md,但你可以通过 initialize-as 选项自定义其名称和位置:

# crushrc
option initialize-as AGENTS.md

如果你在意的命名约定不同,或希望将文件放置在特定目录中(例如 CRUSH.mddocs/LLMs.md),这一点会很有用。Crush 会向该文件写入项目专属上下文,例如在初始化过程中发现的构建命令、代码模式和约定。

署名设置

默认情况下,Crush 会在其创建的 Git 提交和 Pull Request 中添加署名信息。你可以通过 option 命令自定义该行为:

option attribution-trailer-style co-authored-by
option attribution-generated-with true
  • trailer_style: 控制添加到提交信息中的署名 trailer (默认值:assisted-by
    • assisted-by: 按照规范添加 Assisted-by: Crush:[ModelID]
    • co-authored-by: 添加 Co-Authored-By: Crush <crush@charm.land>
    • none: 不添加署名 trailer
  • generated_with: 当为 true(默认值)时,会在提交信息和 PR 描述中添加 💘 Generated with Crush 一行

自定义提供商

Crush 同时支持 OpenAI 兼容 API 和 Anthropic 兼容 API 的自定义提供商配置。

Note

请注意,针对 OpenAI,我们支持两种“类型”。请确保选择正确的一种, 以获得最佳体验!

  • 当通过 OpenAI 代理或路由请求时,应使用 openai
  • 当使用具有 OpenAI 兼容 API 的非 OpenAI 提供商时,应使用 openai-compat

OpenAI 兼容 API

以下是一个 Deepseek 示例配置,该配置使用 OpenAI 兼容 API。请别忘了在环境变量中设置 DEEPSEEK_API_KEY

provider add deepseek --type openai-compat \
  --base-url "https://api.deepseek.com/v1" \
  --api-key "$DEEPSEEK_API_KEY"

model add deepseek/deepseek-chat \
  --name "Deepseek V3" \
  --context-window 64000 \
  --default-max-tokens 5000 \
  --price-input 0.27 \
  --price-output 1.1 \
  --price-cache-create 1.1 \
  --price-cache-hit 0.07

Anthropic 兼容 API

自定义 Anthropic 兼容提供商遵循此格式:

provider add custom-anthropic \
  --type anthropic \
  --base-url "https://api.anthropic.com/v1" \
  --api-key "$ANTHROPIC_API_KEY" \
  --extra-header anthropic-version 2023-06-01

model add custom-anthropic/claude-sonnet-4-20250514 \
  --name "Claude Sonnet 4" \
  --context-window 200000 \
  --default-max-tokens 50000 \
  --can-reason true \
  --supports-images true \
  --price-input 3 \
  --price-output 15 \
  --price-cache-create 3.75 \
  --price-cache-hit 0.3

Amazon Bedrock

Crush 目前支持通过 Bedrock 运行 Anthropic 模型,但已禁用缓存。

一旦 Crush 找到 AWS 凭据,就会显示 Bedrock 提供商。你可以使用以下两种认证方式之一:

API 密钥。AWS_BEARER_TOKEN_BEDROCK 设置为 Bedrock API 密钥。这是最简单的选项,且不会在会话中途过期。

AWS 凭据链(SSO、配置文件、访问密钥)。 使用 aws configureaws configure sso 按常规方式配置 AWS。Crush 会获取 AWS SDK 凭据链解析出的任意凭据,包括 AWS_PROFILEAWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY,或 SSO 会话。如需选择特定配置文件,请在 shell 中设置 AWS_PROFILE(如 AWS_PROFILE=myprofile crush),或在顶层 env 配置中设置。

如果你通过 AWS SSO 进行认证,会话会定期过期。请将 aws_auth_refresh 设置为用于刷新该会话的命令。当 Bedrock 返回凭据错误时,Crush 会执行该命令,然后就地重试请求(不会产生重复消息,也无需手动重启):

{
  "$schema": "https://charm.land/crush.json",
  "env": {
    "AWS_PROFILE": "my-sso-profile"
  },
  "providers": {
    "bedrock": {
      "aws_auth_refresh": "aws sso login --profile my-sso-profile"
    },
    "bedrock-europe": {
      "aws_auth_refresh": "aws sso login --profile my-eu-sso-profile"
    }
  }
}
  • aws_auth_refresh — 当 AWS 凭证过期时执行的 shell 命令(例如 aws sso login

Vertex AI 平台

当设置 VERTEXAI_PROJECTVERTEXAI_LOCATION 时,Vertex AI 会出现在可用提供商列表中。此外,你还需要完成身份验证:

$ gcloud auth application-default login

要将特定模型添加到配置中,请配置如下:

# crushrc — authentication still comes from gcloud and the VERTEXAI_* env vars.
provider add vertexai --type google-vertex

model add vertexai/claude-sonnet-4@20250514 \
  --name "VertexAI Sonnet 4" \
  --context-window 200000 \
  --default-max-tokens 50000 \
  --can-reason true \
  --supports-images true \
  --price-input 3 \
  --price-output 15 \
  --price-cache-create 3.75 \
  --price-cache-hit 0.3

本地模型

Crush 可自动发现来自本地提供商的模型。添加一个自定义提供商,将 type 设置为 llamacppomlxlmstudiolitellmollama,并省略模型列表。Crush 会自动填充模型列表。

# Piece of cake.
provider add ollama \
  --name Ollama \
  --type ollama \
  --base-url "http://localhost:11434/v1/"

对于 llama.cpp(llama-server),请指定服务器的 base URL:

provider add llamacpp \
  --name "llama.cpp" \
  --type llamacpp \
  --base-url "http://localhost:2222"

手动模型配置

你仍然可以显式列出模型。用户定义的模型始终优先于自动发现的模型,而你设置的任何字段都不会被自动发现覆盖。当任一 openai-compat 提供商的模型列表为空,或者你传入 "discover_models": true 时,将执行自动发现,并将发现的模型与你手动配置的模型合并。

# crushrc
provider add ollama \
  --name Ollama \
  --type ollama \
  --base-url "http://localhost:11434/v1/" \
  --discover-models true

model add ollama/qwen3:30b \
  --name "Qwen 3 30B" \
  --context-window 256000 \
  --default-max-tokens 20000

--discover-models true 标志会将发现的模型与上面的模型合并; 出现冲突时,你显式指定的模型字段优先。

日志

有时你需要查看日志。好在 Crush 会记录各种信息。日志会保存在项目目录下的 ./.crush/logs/crush.log

CLI 中还包含一些辅助命令,方便查看最近的日志:

# Print the last 1000 lines
crush logs

# Print the last 500 lines
crush logs --tail 500

# Follow logs in real time
crush logs --follow

想要更多日志?运行 crush 时添加 --debug 参数,或在你的 crushrc 中启用该功能:

# crushrc
option debug true
option debug-lsp true

Provider 自动更新

默认情况下,Crush 会自动从开源的 Crush Provider 数据库 Catwalk 获取最新、最全的 Provider 与模型列表。这意味着,当有新的 Provider 或模型可用,或模型元数据变更时,Crush 会自动更新本地配置。

自定义 Provider 目录

您也可以覆盖 Catwalk 的默认 URL(例如测试时使用 fork)。

设置 CATWALK_URL 环境变量即可。(例如 export CATWALK_URL=http://localhost:8000

禁用自动 Provider 更新

如果网络访问受限,或偏好离线隔离环境,该功能可能并非您所需,可以将其禁用。

若要在 crushrc 中禁用自动 Provider 更新:

option provider-auto-update false

或设置 CRUSH_DISABLE_PROVIDER_AUTO_UPDATE 环境变量:

export CRUSH_DISABLE_PROVIDER_AUTO_UPDATE=1

手动更新提供商

可以使用 crush update-providers 命令手动更新提供商:

# Update providers remotely from Catwalk.
crush update-providers

# Update providers from a custom Catwalk base URL.
crush update-providers https://example.com/

# Update providers from a local file.
crush update-providers /path/to/local-providers.json

# Reset providers to the embedded version, embedded at crush at build time.
crush update-providers embedded

# For more info:
crush update-providers --help

指标

Crush 会记录经过假名化的使用指标(与设备特定哈希绑定), 维护者可据此确定开发和支持的优先级。这些 指标仅包含使用元数据;提示词与响应绝不会 被收集。

关于具体收集内容的详细说明位于源代码中(这里这里)。

你可以通过在你的环境中设置以下环境变量, 随时退出指标收集:

export CRUSH_DISABLE_METRICS=1

Crush 也遵循 DO_NOT_TRACK 约定, 可通过 export DO_NOT_TRACK=1 启用。

常见问题

为什么剪贴板复制和粘贴无法使用?

在类 Unix 环境中,可能需要额外安装工具。

环境 工具
Windows 原生支持
macOS 原生支持
Linux/BSD + Wayland wl-copywl-paste
Linux/BSD + X11 xclipxsel

贡献

请参阅贡献指南

您怎么看?

我们很乐意听到您对这个项目的想法。需要帮助?我们随时为您服务。您可以通过以下方式找到我们:

许可证

FSL-1.1-MIT


Charm 旗下项目。

The Charm logo

Charm热爱开源 • Charm loves open source

Introduction

您钟爱的终端专属魅力AI编码助手 💘【此简介由AI生成】

Customize your domain
15228.01 K2.23 KVisit GitHub