# Crush 接入

> **最后核实**：2026-09-18 · 📄 依据官方文档（Crush v0.95.0，2026-09-16 发布）

## 接入速览

| 项目 | 说明 |
|---|---|
| 可用模型 | Claude ✅（`type: anthropic`）· GPT ✅ · 国产 ✅（`openai-compat`）· Gemini ❌（本页未写 Gemini 接法） |
| 协议与 Base URL | Anthropic：`https://api.qcode.cc/api` · OpenAI：`https://api.qcode.cc/openai/v1` |
| 配置位置 | 项目级 `crush.json` / 用户级 `~/.config/crush/crush.json` |
| 官方文档 | [charmbracelet/crush](https://github.com/charmbracelet/crush) |

[Crush](https://github.com/charmbracelet/crush) 是 Charm 出品的终端 AI 编程 Agent（Go 编写，TUI 优先）。它支持**自定义 provider**，可以把 QCode.cc 配成上游。

> **命名提示**：Crush 的仓库原名 `charmbracelet/opencode`，后改名 `crush`（旧 URL 现为 301 跳转；改名动机官方未说明）。它与 [OpenCode](/docs/ide/opencode)（opencode.ai）是**两个不同项目**——另外 Crush 内置有一个名为 `opencode` 的模型上游 provider，那是 Charm 侧的另一个东西，别混淆。

## 走哪条腿

Crush 的自定义 provider 支持 `anthropic` 与 `openai-compat` 两种 `type`。**要用 Claude 就选 `anthropic`**——QCode 的 OpenAI 端点不接受 Claude 模型（见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)）。

| 你想用的模型 | `type` | `base_url` |
|---|---|---|
| Claude | `anthropic` | `https://api.qcode.cc/api` |
| GPT 系 / 国产四家族 | `openai-compat` | `https://api.qcode.cc/openai/v1` |

## 安装

```bash
# Homebrew
brew install charmbracelet/tap/crush

# 或从 Releases 下载预编译二进制
# https://github.com/charmbracelet/crush/releases
```

验证（**以实际输出为准，不要对照文档里的版本号**）：

```bash
crush --version
```

## 配置

在项目根目录建 `crush.json`，或放用户级 `~/.config/crush/crush.json`（即 `$XDG_CONFIG_HOME/crush/crush.json`；注意 `~/.local/share/crush/` 下是状态文件，官方明示不要手改）。新版官方另推 `crushrc`（Bash DSL）格式，JSON 配置仍被读取：

```json
{
  "$schema": "https://charm.land/crush.json",
  "providers": {
    "qcode": {
      "type": "anthropic",
      "base_url": "https://api.qcode.cc/api",
      "api_key": "$QCODE_KEY",
      "extra_headers": { "anthropic-version": "2023-06-01" },
      "models": [
        {
          "id": "claude-sonnet-5",
          "name": "QCode Sonnet 5",
          "cost_per_1m_in": 2,
          "cost_per_1m_out": 10,
          "context_window": 1000000,
          "default_max_tokens": 8192,
          "cost_per_1m_in_cached": 0.2,
          "cost_per_1m_out_cached": 2.5,
          "can_reason": true,
          "supports_attachments": true
        },
        {
          "id": "claude-haiku-4-5",
          "name": "QCode Haiku 4.5",
          "cost_per_1m_in": 1,
          "cost_per_1m_out": 5,
          "context_window": 200000,
          "default_max_tokens": 4096,
          "cost_per_1m_in_cached": 0.1,
          "cost_per_1m_out_cached": 1.25,
          "can_reason": true,
          "supports_attachments": true
        }
      ]
    }
  }
}
```

密钥用环境变量注入，不写进配置文件：

```bash
export QCODE_KEY="cr_你的QCode密钥"
```

字段说明：

| 字段 | 说明 |
|------|------|
| `type` | `anthropic` = 走 Anthropic 原生 Messages 协议 |
| `base_url` | 填到 `/api` 为止。**Crush 会自己拼 `/v1/messages`** |
| `api_key` | 支持 `$变量名` 形式的环境变量展开 |
| `extra_headers` | Anthropic 协议需要 `anthropic-version` |
| `models[]` | 显式列出可覆盖成本 / 窗口等参数；整段不写时 Crush 默认打 `<base>/v1/models` 自动发现（`discover_models` 默认开）。`id` 要与 [qcode.cc/models](https://qcode.cc/models) 上的 id 逐字符一致 |

> **国内用户**把域名换成 `https://asia.qcode.cc/api`（亚洲节点，韩国 / 台湾 / 香港就近），Key 不变。
> `cost_per_1m_*`（含 `*_cached` 两个缓存价键，官方 schema 要求填齐）只影响 Crush 自己的用量估算显示，不影响实际计费——示例里的数字按输入/输出的常见缓存比例给，请按 [qcode.cc/models](https://qcode.cc/models) 上的实际缓存价调整。

## 验证

```bash
crush run "reply with exactly: OK"
```

返回 `OK` 即接通。

**判断是不是真的走到了 QCode**：故意把 `base_url` 改成一个不存在的路径再跑一次，
应当看到明确的 404 并回显完整 URL，例如：

```text
404 Not Found {"error":"Not Found","message":"Route /api/xxx/v1/messages not found"}
```

看到这个报错说明 Crush 确实在拼 `base_url + /v1/messages`，配置生效了。
（这一步是阴性对照：只看到成功不能证明配置生效，可能是走了别的 provider。）

## 常用用法

```bash
# 交互模式
crush

# 非交互
crush run "把这个函数改成异步的"

# 管道
cat README.md | crush run "把它写得更清楚" > README.new.md

# 指定工作目录 + 调试日志
crush --debug --cwd /path/to/project

# 自动接受全部权限（谨慎）
crush --yolo
```

## 常见问题

### `model_not_available_on_endpoint`

`type` 写成了 `openai-compat` 而模型是 Claude。改成 `type: "anthropic"`，
`base_url` 填 `https://api.qcode.cc/api`。

### 401 Invalid API key

环境变量没注入，或密钥带了空格。确认 `echo $QCODE_KEY` 输出以 `cr_` 开头。

### 模型下拉里看不到

不写 `models[]` 时 Crush 靠 `<base>/v1/models` 自动发现（QCode 的 `/api/v1/models` 与 `/openai/v1/models` 路径存在，返回在售清单）；写了 `models[]` 则以你列出的为准。列少了就补一条记录再重启。

## 相关文档

- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) — 协议 × 模型家族真源表
- [OpenCode 集成](/docs/ide/opencode) — 另一个终端 Agent（与 Crush 是不同项目）
- [国产模型接入](/docs/usage/cn-models) — GLM / Kimi / DeepSeek / Qwen