Crush + JoinGonka Gateway：基于 Gonka 网络模型的 Charm 代理

第 1 步：安装 Crush。来自项目 README的官方方式：

# Homebrew
brew install charmbracelet/tap/crush

# npm
npm install -g @charmland/crush

# Arch Linux
yay -S crush-bin

# Windows
winget install charmbracelet.crush

# Go
go install github.com/charmbracelet/crush@latest

README 中同样介绍了适用于 Debian、Ubuntu、Fedora 和 RHEL、Nix 和 Scoop 的软件包仓库，发布页面上还提供了现成的二进制文件。验证方式——crush --version，会返回类似 crush version v0.96.1 的一行。

第 2 步：获取密钥。在 gate.joingonka.ai/register 注册，确认邮箱地址，然后在「API 密钥」页面创建一个以 jg- 为前缀的密钥。一个密钥和一个余额即可用于网络上的所有模型。

第 3 步：运行安装程序。

npx @joingonka/setup --tool crush

安装程序会询问密钥——它不会通过命令行参数传递，以免留在 shell 历史记录中——并完成四件事：

• 将提供商 joingonka 写入 ~/.config/crush/crush.json：类型 openai-compat、网关地址、明文字面量密钥，以及三个网络模型及其上下文窗口、响应上限和每百万 token 的价格，这些价格在安装时会从网关实时获取——Crush 据此计算会话成本。文件权限将设为 600；
• 分配模型：large 槽位为 DeepSeek V4 Flash，small 槽位为 MiniMax M2.7，而 GLM-5.3 Flash 会保留在列表中供手动选择。仅当 large 槽位为空或指向已从网络中下线的我们的模型时才会这样做；他人的选择会保留，输出中会提示如何切换；
• 检查该选择是否生效：Crush 界面中的模型保存在状态文件中，而该文件会覆盖配置——详见 large 和 small 相关章节；
• 创建备份，其他提供商和设置保持不变，最后向网关发起一次实时请求，以便立即验证密钥、地址和模型。

如需指定其他模型，可使用 --model 标志并搭配简写 deepseek、glm 或 minimax；显式指定的模型始终会被写入。对于非标准目录，安装程序的处理方式与 Crush 本身相同：CRUSH_GLOBAL_CONFIG 用于配置，CRUSH_GLOBAL_DATA 用于状态文件，此外还有 XDG_CONFIG_HOME 和 XDG_DATA_HOME。针对服务器和脚本，还提供了无交互模式，密钥从环境变量中读取：

JOINGONKA_API_KEY=jg-your-key npx @joingonka/setup --tool crush --model glm --non-interactive

Crush 的主要格式现在是 crushrc，但安装程序写入的是 crush.json：所有版本都能识别它。如果你已经有 crushrc，Crush 会合并两个文件，键名冲突时以 crushrc 为准，而安装程序本身不会改动它。

安装器所做的每一件事，你都可以手动写出来。下面是一份可以直接用的 ~/.config/crush/crush.json —— 这个文件我们已经在网关里跑过了：

{
  "$schema": "https://charm.land/crush.json",
  "providers": {
    "joingonka": {
      "name": "JoinGonka (Gonka)",
      "type": "openai-compat",
      "base_url": "https://gate.joingonka.ai/v1",
      "api_key": "jg-your-key",
      "models": [
        { "id": "deepseek-ai/DeepSeek-V4-Flash-0731", "name": "DeepSeek V4 Flash (Gonka)",
          "context_window": 380000, "default_max_tokens": 32768,
          "can_reason": true, "supports_attachments": false },
        { "id": "MiniMaxAI/MiniMax-M2.7", "name": "MiniMax M2.7 (Gonka)",
          "context_window": 200000, "default_max_tokens": 8192,
          "can_reason": false, "supports_attachments": false },
        { "id": "zai-org/GLM-5.3-Flash", "name": "GLM-5.3 Flash (Gonka)",
          "context_window": 390000, "default_max_tokens": 8192,
          "can_reason": true, "supports_attachments": false }
      ]
    }
  },
  "models": {
    "large": { "provider": "joingonka", "model": "deepseek-ai/DeepSeek-V4-Flash-0731" },
    "small": { "provider": "joingonka", "model": "MiniMaxAI/MiniMax-M2.7" }
  }
}

Crush 只接受严格 JSON：一个注释或者一个尾随逗号，它就启动不了。价格字段（cost_per_1m_in、cost_per_1m_out 以及两个缓存字段）只是给费用计数器用的：安装器会把网关的实时价格填进去，就算不填 Crush 也能跑，只是显示为零 —— 只有加载了 $schema 中 schema 的编辑器才会把它们标记为必填。

同一个 provider 用 crushrc 格式写出来，就是一段普通的 Bash，加上 Crush 的内置命令。文件 ~/.config/crush/crushrc：

provider add joingonka \
  --name "JoinGonka (Gonka)" \
  --type openai-compat \
  --base-url "https://gate.joingonka.ai/v1" \
  --api-key "${JOINGONKA_API_KEY:?set JOINGONKA_API_KEY}"

model add joingonka/deepseek-ai/DeepSeek-V4-Flash-0731 \
  --name "DeepSeek V4 Flash (Gonka)" \
  --context-window 380000 --default-max-tokens 32768 --can-reason true

model add joingonka/MiniMaxAI/MiniMax-M2.7 \
  --name "MiniMax M2.7 (Gonka)" \
  --context-window 200000 --default-max-tokens 8192

model add joingonka/zai-org/GLM-5.3-Flash \
  --name "GLM-5.3 Flash (Gonka)" \
  --context-window 390000 --default-max-tokens 8192 --can-reason true

model large joingonka/deepseek-ai/DeepSeek-V4-Flash-0731
model small joingonka/MiniMaxAI/MiniMax-M2.7

这里的模型采用 provider/model-id 的形式命名：第一条斜杠之前是 provider 名称，之后是网络标识符本身。用 ${JOINGONKA_API_KEY:?…} 这种形式可以把密钥留在文件之外，但变量没导出的话 Crush 就启动不了 —— 宁可启动时报错，也不要带着空密钥去发请求。

在 Crush 中，不是为所有任务选择单一模型，而是为两个槽位分别选择：

第三种网络模型，即侧重推理的 GLM-5.3 Flash，常用于处理复杂的逻辑问题，需注意其响应上限为 8192，且其中一部分会被推理过程占用——详见模型概览。单次运行时，通过全名指定模型：crush run -m joingonka/zai-org/GLM-5.3-Flash "…"。所有可用名称可通过 crush models joingonka 列出。

状态文件。 通过界面 ctrl+l 选择的模型，Crush 不会将其写入 crush.json，而是存入机器状态文件：~/.local/share/crush/crush.json，在 Windows 上为 %LOCALAPPDATA%\crush\crush.json。该文件的优先级高于用户配置和 crushrc：Crush 按顺序读取它们 /etc/crush/crush.json → ~/.config/crush/crush.json → ~/.config/crush/crushrc → 状态文件，后面的设置会覆盖前面的。只有项目级设置（项目目录下的 crush.json 或 crushrc）拥有最高优先级。运行 crush dirs 可查看本地文件的存储位置。

在我们的一次运行中，我们打开了模型选择菜单——提供商“JoinGonka (Gonka)”显示为“✓ Configured”——并选择了 MiniMax M2.7。Crush 回复“Large model changed to MiniMax M2.7 (Gonka)”并将信息写入状态文件：

{"models":{"large":{"model":"MiniMaxAI/MiniMax-M2.7","provider":"joingonka","max_tokens":8192}}, …}

现在该模型优于 crush.json 中的设置。安装程序能够识别这种情况并采用不同的行为方式：

• 不带 --model 时，它不会修改状态文件（保留您的当前工作选择），但会明确警告 Crush 实际启动时将使用的模型：Heads-up: Crush will still start with joingonka/MiniMaxAI/MiniMax-M2.7, not joingonka/deepseek-ai/DeepSeek-V4-Flash-0731。如果在界面中选择了 GLM-5.3 Flash 或其他提供商的模型，行为也是一样；
• 带明确的 --model 时，它会保存备份后修改状态文件中的唯一条目 models.large，并报告更改内容。否则该标志将无法生效。运行后，我们的 Crush 实例即以标志中指定的模型启动。

首先，确认 Crush 能看到该提供商：

crush models joingonka

你会得到三行输出：

joingonka/MiniMaxAI/MiniMax-M2.7
joingonka/deepseek-ai/DeepSeek-V4-Flash-0731
joingonka/zai-org/GLM-5.3-Flash

接下来，在不使用界面的情况下做一次单次运行。在项目目录中放入一个带有明显 bug 的文件，让它找出来：

crush run -q "Read calc.py and tell me in one sentence whether it has a bug."

Agent 应当主动调用文件读取工具，并给出实质性的回答，包括行号。在我们的运行中，网络上的三个模型都找到了这个 bug，任务耗时 20-40 秒。-q 标志会隐藏等待指示器。在 crush run 模式下，所有工具调用都会自动批准，因此请在你自己的项目中运行它。在常规界面（crush 命令）中，活动模型显示在状态栏中：◇ DeepSeek V4 Flash (Gonka) via JoinGonka (Gonka)。Crush 将会话和日志存储在项目的 .crush 目录中，该目录通过自带的 .gitignore 与 git 隔离；日志由 crush logs 打印。在网关侧，请求在控制台中可见："使用情况"部分，按"按模型"和"按键"细分。

如果出了问题，通常从消息本身就能看出诊断结果：

代理消耗 token 的方式与聊天不同：对于您发送的每一句话，Crush 都会添加系统提示词及其工具说明，且任务通常需要几轮对话。在我们的测试中，每个模型请求携带约 11,500 个输入 token，而“读取文件并查找错误”的任务耗费了 2 到 3 次请求和 23,000–35,000 个 token，其中几乎全部为输入 token。因此，token 价格是此处决定成本的关键因素。

通过 JoinGonka Gateway，输入 token 的价格为每百万 $0.0069，输出 token 为每百万 $0.021——所有网络模型价格相同，并从该页面的实时来源获取。

右栏估算基于 2026 年 9 月的价格。作为参考——关于如何在 Crush 中支付模型费用：

Crush 界面中的成本计数器根据配置中的价格字段进行计算。它捕获的是安装时的网关价格，而网络上的美元价格会随 GNK 汇率波动，因此计数器仅供参考。确切的消耗量和余额可在后台的“使用情况”和“账单”部分查看。为何默认将 DeepSeek V4 Flash 设置为 large 槽位，已在 模型综述 中详细说明。

权限。默认情况下，Crush 界面在调用工具前会先请求权限。--yolo 标志可一次性关闭所有询问，而单独信任的工具则在配置中列出：

# crushrc
permissions allow view ls grep

# crush.json
"permissions": { "allowed_tools": ["view", "ls", "grep"] }

请注意，crush run 会自行批准一切。这是 Crush 自身的特性，与模型提供商无关。

请求超时。如果模型长时间没有返回任何一段响应内容，Crush 就会中断请求：在 0.96.1 版本中，静默时长为两分钟（文档写的是 60 秒，但代码和我们的测试结果都是两分钟）。网关用于保持连接的保活 ping 不会重置这个计时器——我们在本地测试环境验证过。而在高峰时段，网关等待网络返回首个 token 最长可达 150 秒，因此不妨把余量调大：

# crushrc
option request-timeout 300

# crush.json
"options": { "request_timeout": 300 }

提交签名。Crush 创建的提交和拉取请求默认会带上 Assisted-by: Crush:<model> 这一行以及“Generated with Crush”的附注。如果你不需要：

# crushrc
option attribution-trailer-style none
option attribution-generated-with false

# crush.json
"options": { "attribution": { "trailer_style": "none", "generated_with": false } }

指标。Crush 会向开发者发送匿名化的使用统计数据——仅包含元数据，不含提示词和响应。可通过变量 CRUSH_DISABLE_METRICS=1 或 DO_NOT_TRACK=1 关闭。网关这边也不会存储提示词和响应的内容——统计数据中只保留用量汇总。

配置即代码。无论是 crushrc 还是 crush.json，Crush 都会以你 shell 的权限执行：键字段中的 $(…) 会在加载时运行，而项目级的 crushrc 会在你于该目录打开 Crush 的瞬间生效。在别人的仓库里运行 agent 之前，务必先读一读它的配置文件。