Crush + JoinGonka Gateway: агент Charm на моделях мережі Gonka

Крок 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

Там же описано репозиторії пакетів для Debian, Ubuntu, Fedora і RHEL, Nix та Scoop, а на сторінці релізів лежать готові бінарники. Перевірка — crush --version, у відповідь прийде рядок вигляду crush version v0.96.1.

Крок 2: отримати ключ. Зареєструйтеся на gate.joingonka.ai/register, підтвердьте адресу та створіть ключ із префіксом jg- у розділі «API-ключі». Один ключ і один баланс діють для всіх моделей мережі.

Крок 3: запустити інсталятор.

npx @joingonka/setup --tool crush

Інсталятор запитає ключ — в аргументах командного рядка він не передається, щоб не осісти в історії оболонки, — і зробить чотири речі:

• пропише провайдера joingonka у ~/.config/crush/crush.json: тип openai-compat, адресу шлюзу, ключ літералом і три моделі мережі з вікнами контексту, стелями відповіді та цінами за мільйон токенів, які він у момент встановлення бере у шлюзу живими, — за ними 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 підсвітить їх як обов'язкові.

Той самий провайдер у форматі 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: до першої косої риски — ім'я провайдера, далі — ідентифікатор мережі як є. Форма ${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

Далі — разовий прогін без інтерфейсу. Покладіть у каталог проєкту файл з очевидною помилкою та попросіть її знайти:

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

Агент має сам викликати інструмент читання файлу й відповісти по суті, із номером рядка. У нашому прогоні помилку знайшли всі три моделі мережі, на завдання йшло 20-40 секунд. Прапорець -q ховає індикатор очікування. У режимі crush run усі виклики інструментів схвалюються автоматично, тож запускайте його у своєму проєкті. У звичайному інтерфейсі (команда crush) активна модель видна в рядку стану: ◇ DeepSeek V4 Flash (Gonka) via JoinGonka (Gonka). Сесії та журнал Crush зберігає в каталозі .crush проєкту, закритому від git власним .gitignore; журнал друкує crush logs. З боку шлюзу запит видно в кабінеті: розділ «Використання», розбивка «За моделями» та «За ключами».

Якщо щось пішло не так, діагноз зазвичай читається прямо з повідомлення:

Агент витрачає токени інакше, ніж чат: до кожної вашої фрази Crush додає системний промпт і описи своїх інструментів, а задача зазвичай займає кілька ходів. У нашому прогоні кожен запит до моделі ніс близько 11,5 тисячі вхідних токенів, а задача «прочитати файл і знайти помилку» зайняла два-три запити і 23-35 тисяч токенів, майже все — вхід. Тому ціна за токен тут вирішує.

Через JoinGonka Gateway токени коштують $0.0069 за мільйон на вході і $0.021 за мільйон на виході — ціна однакова для всіх моделей мережі і підставляється на цій сторінці з живого джерела.

Оцінки в правій колонці — за цінами на вересень 2026. Для порівняння — як взагалі можна платити за моделі в Crush:

Лічильник вартості в інтерфейсі Crush рахує за полями ціни з конфігу. Туди потрапляє ціна шлюзу на момент установки, а доларова ціна в мережі плаває разом із курсом GNK, тому лічильник — орієнтир. Точна витрата і залишок — у кабінеті, в розділах «Використання» та «Білінг». Чому в слот large за замовчуванням встає DeepSeek V4 Flash, детально розібрано в огляді моделі.

Дозволи. В інтерфейсі Crush за замовчуванням питає дозвіл перед викликом інструмента. Прапорець --yolo вимикає всі питання разом, а точково довірені інструменти перелічуються в конфізі:

# crushrc
permissions allow view ls grep

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

Нагадаємо, що crush run схвалює все сам. Це властивість Crush, від провайдера моделі вона не залежить.

Таймаут запиту. Crush обриває запит, якщо від моделі довго не надходить жодного фрагмента відповіді: у версії 0.96.1 це дві хвилини тиші (документація називає 60 секунд, але в коді та на нашій перевірці — дві хвилини). Службові пінги, якими шлюз тримає з'єднання, цей лічильник не скидають — ми перевірили на локальному стенді. Шлюз же в години навантаження чекає першого токена від мережі до 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 виконує з правами вашої оболонки: $(…) у полі ключа запуститься при завантаженні, а проєктний crushrc спрацює, щойно ви відкриєте Crush у цьому каталозі. Не запускайте агент у чужому репозиторії, не прочитавши його конфіги.