> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siflow.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Crush

> 了解如何在 Crush 终端 AI 编程智能体中配置 openai-compat provider，接入 siflow endpoint，并使用算秩模型完成编码任务。

[Crush](https://github.com/charmbracelet/crush) 是 Charm 提供的终端 AI 编程智能体。它可以通过 `openai-compat` provider type 连接任意 OpenAI-compatible service，因此可以接入 siflow endpoint。可用模型请查看 [模型广场](https://console.siflow.cn/model-inference/models)，例如 `glm-5.2`。

## 配置

Crush 会先读取项目级 `.crush.json` / `crush.json`，然后读取全局 `~/.config/crush/crush.json`。在 [API 密钥](https://console.siflow.cn/model-inference/api_keys) 页面创建 API Key 后，在项目根目录创建 `crush.json`：

```json theme={null}
{
  "$schema": "https://charm.land/crush.json",
  "models": {
    "large": { "provider": "siflow", "model": "glm-5.2" },
    "small": { "provider": "siflow", "model": "glm-5.2" }
  },
  "providers": {
    "siflow": {
      "name": "siflow",
      "type": "openai-compat",
      "base_url": "https://api.siflow.cn/model-api/v1",
      "api_key": "$SIFLOW_API_KEY",
      "models": [
        {
          "id": "glm-5.2",
          "name": "glm-5.2",
          "context_window": 131072,
          "default_max_tokens": 8192,
          "cost_per_1m_in": 0,
          "cost_per_1m_out": 0,
          "cost_per_1m_in_cached": 0,
          "cost_per_1m_out_cached": 0,
          "can_reason": true,
          "supports_attachments": false
        }
      ]
    }
  }
}
```

顶层 `models.large` / `models.small` 会显式设置默认 provider。如果您的 shell 中残留了 `OPENAI_API_KEY` 或 `ANTHROPIC_API_KEY` 等变量，这一点很重要；如果没有显式默认值，Crush 可能会自动发现并使用这些官方 providers。

导出 `api_key` 引用的环境变量：

```bash theme={null}
export SIFLOW_API_KEY="<Your API Key>"
```

| 字段                                                      | 说明                                                                               |
| ------------------------------------------------------- | -------------------------------------------------------------------------------- |
| type                                                    | 必须是 `openai-compat`，不是 `openai`                                                  |
| base\_url                                               | siflow OpenAI-compatible endpoint：`https://api.siflow.cn/model-api/v1`           |
| api\_key                                                | 环境变量引用，或直接填写 key（不要提交到代码仓库）。支持 `$VAR`、`${VAR:-default}` 和 `$(command)` expansion |
| context\_window / default\_max\_tokens                  | 设置为所选模型的真实 limits                                                                |
| cost\_per\_1m\_\* / can\_reason / supports\_attachments | custom-provider models 的 config schema 必填字段；cost 可以填 `0`                         |
| models.large / models.small                             | 显式默认模型，避免其他 providers 的环境变量接管。请选择原生支持 tool calling 的模型，否则 Crush 无法执行文件或命令操作      |

如果要完全忽略自动发现的官方 providers，可设置 `"options": { "disable_default_providers": true }`。这样只会使用配置中完整指定的 providers。

如果要自动同步模型列表，可在 provider 下添加 `"discover_models": true`。Crush 会将从 `https://api.siflow.cn/model-api/v1/models` 获取的模型与手写条目合并（手写条目优先）；对于 `openai-compat` providers，`models` 为空也会触发自动发现。

`export` 只在当前 shell 中有效；如需持久化，请添加到 `~/.bashrc` / `~/.zshrc`。

## 验证

```bash theme={null}
cd your-project
crush
```

Crush 会直接使用 `glm-5.2` 启动。`models.large` / `models.small` 已将其固定为默认模型，无需再选择。发送一个任务，例如 "list the current directory and summarize it"，确认 tool calls 和 responses 正常工作。（`Ctrl+L` 可打开 model picker 切换模型。）

也可以以非交互方式运行单个任务：

```bash theme={null}
crush run "introduce this project in one sentence"
```

`crush run` 常用 flags 包括：`-m provider/model`（为本次运行选择模型，例如 `-m siflow/glm-5.2`）、`-q`（quiet，不显示 spinner），以及 stdin piping（`curl -s https://example.com | crush run "Summarize this"`）。注意，`run` 不支持 `--yolo`；请通过 `permissions.allowed_tools` 预先允许所需工具：

```json theme={null}
{
  "permissions": {
    "allowed_tools": ["view", "ls", "grep", "glob", "edit", "write", "bash"]
  }
}
```

## FAQ

* **模型没有出现在 picker 中，或请求走到了 OpenAI 官方 API**：请确认 `crush.json` 位于启动目录（或全局路径），且是合法 JSON；`type` 必须为 `openai-compat`；如果环境变量中设置了其他 providers 的 API key，请添加 `models.large` / `models.small` 来强制默认模型。
* **出现 401 错误**：如果 `api_key` 引用环境变量，请确认该变量已导出。也可以直接设置 key，但不要提交到代码仓库。

Crush 是 Go static binary，因此旧版 Node 上的 npm `EBADENGINE` warnings 可以忽略。