Crush + JoinGonka Gateway: tác nhân Charm trên các mô hình mạng lưới Gonka

Bước 1: cài đặt Crush. Các cách chính thức từ README của dự án:

# 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

Tại đó cũng mô tả các kho gói cho Debian, Ubuntu, Fedora và RHEL, Nix và Scoop, còn trên trang phát hành có sẵn các tệp nhị phân. Kiểm tra bằng crush --version, sẽ nhận được dòng có dạng crush version v0.96.1.

Bước 2: lấy khóa. Đăng ký tại gate.joingonka.ai/register, xác nhận địa chỉ và tạo khóa có tiền tố jg- trong mục «Khóa API». Một khóa và một số dư dùng chung cho tất cả các mô hình trong mạng.

Bước 3: chạy trình cài đặt.

npx @joingonka/setup --tool crush

Trình cài đặt sẽ hỏi khóa — khóa không được truyền trong đối số dòng lệnh để tránh lưu lại trong lịch sử shell — và thực hiện bốn việc:

• ghi nhà cung cấp joingonka vào ~/.config/crush/crush.json: loại openai-compat, địa chỉ gateway, khóa dạng literal và ba mô hình của mạng với cửa sổ ngữ cảnh, giới hạn phản hồi và giá trên mỗi triệu token, mà tại thời điểm cài đặt nó lấy trực tiếp từ gateway, — dựa vào đó Crush tính chi phí phiên. Tệp sẽ có quyền 600;
• gán mô hình: vào slot large — DeepSeek V4 Flash, vào small — MiniMax M2.7, còn GLM-5.3 Flash sẽ nằm trong danh sách để chọn thủ công. Nó chỉ làm điều này nếu slot large trống hoặc trỏ tới mô hình của chúng ta đã rời mạng; lựa chọn của người khác được giữ nguyên, và trong đầu ra sẽ có gợi ý cách chuyển đổi;
• kiểm tra rằng lựa chọn sẽ có hiệu lực: mô hình từ giao diện Crush được lưu trong tệp trạng thái, và tệp đó ghi đè cấu hình, — về điều này có mục nói về large và small;
• tạo bản sao lưu, giữ nguyên các nhà cung cấp và cài đặt khác, và kết thúc bằng một yêu cầu trực tiếp tới gateway để kiểm tra ngay khóa, địa chỉ và mô hình.

Mô hình khác được chỉ định bằng cờ --model với viết tắt deepseek, glm hoặc minimax; mô hình được chỉ định rõ ràng luôn được ghi. Các thư mục không tiêu chuẩn được trình cài đặt xử lý giống như chính Crush: CRUSH_GLOBAL_CONFIG cho cấu hình, CRUSH_GLOBAL_DATA cho tệp trạng thái, cũng như XDG_CONFIG_HOME và XDG_DATA_HOME. Dành cho máy chủ và script có chế độ không hỏi, trong đó khóa được lấy từ biến môi trường:

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

Định dạng chính của Crush giờ đây là crushrc, nhưng trình cài đặt ghi crush.json: mọi phiên bản đều hiểu nó. Nếu bạn đã có crushrc, Crush sẽ hợp nhất cả hai tệp, khi trùng khóa thì crushrc thắng, còn trình cài đặt không đụng tới nó.

Mọi thứ mà trình cài đặt làm đều có thể viết tay. Đây là file ~/.config/crush/crush.json đang hoạt động — file này chúng tôi đã chạy qua gateway:

{
  "$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 chỉ chấp nhận JSON nghiêm ngặt: một comment hay dấu phẩy thừa là nó không khởi động. Các trường giá (cost_per_1m_in, cost_per_1m_out và hai trường cho cache) chỉ cần cho bộ đếm chi phí: trình cài đặt ghi giá thực tế của gateway vào đó, còn nếu thiếu thì Crush vẫn chạy và hiển thị số không — chỉ có trình soạn thảo với schema từ $schema mới đánh dấu chúng là bắt buộc.

Cùng một provider ở định dạng crushrc — đây là Bash thông thường với các lệnh tích hợp của Crush. File ~/.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

Ở đây model được gọi theo dạng provider/model-id: trước dấu gạch chéo đầu tiên là tên provider, sau đó là định danh mạng giữ nguyên như gốc. Dạng ${JOINGONKA_API_KEY:?…} giữ khóa nằm ngoài file, nhưng nếu biến chưa được export thì Crush sẽ không khởi động — thà lỗi ngay lúc khởi động còn hơn gửi yêu cầu với khóa rỗng.

Mô hình trong Crush không được chọn cho mọi thứ, mà cho hai khe cắm:

Mô hình thứ ba của mạng, GLM-5.3 Flash (suy luận), được chọn cho logic phức tạp, cần lưu ý giới hạn phản hồi là 8192 và một phần dành cho suy luận — chi tiết xem tại đánh giá mô hình. Đối với mỗi lần chạy, mô hình được xác định bằng tên đầy đủ: crush run -m joingonka/zai-org/GLM-5.3-Flash "…". Tất cả tên có sẵn được liệt kê bởi crush models joingonka.

Tệp trạng thái. Mô hình được chọn trong giao diện qua ctrl+l không được Crush ghi vào crush.json, mà vào tệp trạng thái máy: ~/.local/share/crush/crush.json, trên Windows là %LOCALAPPDATA%\crush\crush.json. Tệp này có quyền ưu tiên cao hơn tệp cấu hình người dùng và crushrc: Crush đọc theo thứ tự /etc/crush/crush.json → ~/.config/crush/crush.json → ~/.config/crush/crushrc → tệp trạng thái, và mỗi tệp sau sẽ ghi đè tệp trước. Chỉ các cài đặt dự án — crush.json hoặc crushrc trong thư mục dự án — là có quyền ưu tiên cao hơn. crush dirs sẽ cho biết các tệp này nằm ở đâu trên máy của bạn.

Trong ví dụ chạy của chúng tôi, chúng tôi đã mở phần chọn mô hình — nhà cung cấp “JoinGonka (Gonka)” xuất hiện với dấu “✓ Configured” — và chọn MiniMax M2.7. Crush đã phản hồi “Large model changed to MiniMax M2.7 (Gonka)” và ghi vào tệp trạng thái:

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

Giờ đây, mô hình này quan trọng hơn những gì được viết trong crush.json. Trình cài đặt nhận ra tình huống này và xử lý theo các cách khác nhau:

• không có --model nó không chạm vào tệp trạng thái — vì đây là lựa chọn làm việc của bạn — nhưng sẽ cảnh báo rõ ràng về mô hình mà Crush thực sự sẽ khởi chạy: Heads-up: Crush will still start with joingonka/MiniMaxAI/MiniMax-M2.7, not joingonka/deepseek-ai/DeepSeek-V4-Flash-0731. Nó cũng sẽ làm như vậy nếu GLM-5.3 Flash hoặc mô hình của nhà cung cấp khác được chọn trong giao diện;
• với --model rõ ràng nó sửa chính xác một mục trong tệp trạng thái — models.large — sau khi đã lưu một bản sao, và báo cáo những gì đã thay đổi. Nếu không, cờ sẽ không có tác dụng. Sau khi chạy như vậy, Crush trong ví dụ của chúng tôi đã khởi chạy với mô hình được chỉ định trong cờ.

Trước tiên, hãy đảm bảo Crush nhìn thấy nhà cung cấp:

crush models joingonka

Kết quả trả về ba dòng:

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

Tiếp theo, chạy thử một lần không giao diện. Đặt vào thư mục dự án một tệp có lỗi rõ ràng và yêu cầu tìm ra nó:

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

Agent phải tự gọi công cụ đọc tệp và trả lời đúng trọng tâm, kèm số dòng. Trong lần chạy của chúng tôi, cả ba mô hình của mạng đều tìm ra lỗi, thời gian xử lý mất 20-40 giây. Cờ -q ẩn chỉ báo chờ. Trong chế độ crush run, mọi lệnh gọi công cụ đều được tự động phê duyệt, vì vậy hãy chạy nó trong dự án của bạn. Trong giao diện thông thường (lệnh crush), mô hình đang hoạt động hiển thị trên dòng trạng thái: ◇ DeepSeek V4 Flash (Gonka) via JoinGonka (Gonka). Crush lưu phiên làm việc và nhật ký trong thư mục .crush của dự án, được bảo vệ khỏi git bằng .gitignore riêng; nhật ký in bằng lệnh crush logs. Từ phía gateway, yêu cầu hiển thị trong bảng điều khiển: mục «Sử dụng», phân tách «Theo mô hình» và «Theo khóa».

Nếu có sự cố, chẩn đoán thường đọc được ngay từ thông báo:

Tác nhân tiêu tốn token khác với trò chuyện: với mỗi câu của bạn, Crush thêm một prompt hệ thống và mô tả các công cụ của nó, và nhiệm vụ thường mất vài lượt. Trong lần thử nghiệm, mỗi yêu cầu đến mô hình chứa khoảng 11,5 nghìn token đầu vào, và nhiệm vụ «đọc tệp và tìm lỗi» tốn hai-ba yêu cầu và 23-35 nghìn token, hầu hết là đầu vào. Do đó, giá mỗi token ở đây rất quan trọng.

Thông qua JoinGonka Gateway, token có giá $0.0069 mỗi triệu token đầu vào và $0.021 mỗi triệu token đầu ra — giá này giống nhau cho tất cả các mô hình trong mạng và được lấy từ nguồn trực tiếp trên trang này.

Các ước tính ở cột bên phải dựa trên giá tháng 9 năm 2026. Để so sánh — làm thế nào để thanh toán cho các mô hình trong Crush:

Bộ đếm chi phí trong giao diện Crush tính toán dựa trên các trường giá từ tệp cấu hình. Nó sử dụng giá của gateway tại thời điểm cài đặt, nhưng giá USD trong mạng biến động theo tỷ giá GNK, vì vậy bộ đếm chỉ mang tính tham khảo. Chi tiêu chính xác và số dư còn lại nằm trong bảng điều khiển, trong các phần «Sử dụng» và «Thanh toán». Tại sao DeepSeek V4 Flash được chọn mặc định cho vị trí large, đã được phân tích chi tiết trong bài đánh giá mô hình.

Quyền. Mặc định, giao diện Crush sẽ hỏi quyền trước khi gọi công cụ. Cờ --yolo tắt toàn bộ câu hỏi cùng lúc, còn những công cụ được tin cậy có chọn lọc sẽ được liệt kê trong tệp cấu hình:

# crushrc
permissions allow view ls grep

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

Xin nhắc lại, crush run tự phê duyệt mọi thứ. Đây là đặc tính của Crush, không phụ thuộc vào nhà cung cấp mô hình.

Thời gian chờ yêu cầu. Crush sẽ ngắt yêu cầu nếu mô hình không gửi về bất kỳ đoạn phản hồi nào trong thời gian dài: ở phiên bản 0.96.1 là hai phút im lặng (tài liệu ghi 60 giây, nhưng trong mã nguồn và qua kiểm tra của chúng tôi là hai phút). Các gói ping dịch vụ mà cổng dùng để duy trì kết nối không làm mới bộ đếm này — chúng tôi đã kiểm chứng trên môi trường thử nghiệm cục bộ. Còn cổng vào giờ cao điểm chờ token đầu tiên từ mạng tới 150 giây, vì vậy nên nâng khoảng dự phòng:

# crushrc
option request-timeout 300

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

Chữ ký trong commit. Các commit và pull request do Crush tạo mặc định sẽ có dòng Assisted-by: Crush:<model> và chú thích "Generated with Crush". Nếu không cần điều này:

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

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

Số liệu đo lường. Crush gửi cho nhà phát triển thống kê sử dụng dưới dạng bút danh — chỉ siêu dữ liệu, không có prompt và phản hồi. Có thể tắt bằng biến CRUSH_DISABLE_METRICS=1 hoặc DO_NOT_TRACK=1. Về phía mình, cổng không lưu nội dung prompt và phản hồi — trong thống kê chỉ còn lại các số liệu tổng hợp về mức tiêu thụ.

Cấu hình chính là mã. Crush thực thi cả crushrc lẫn crush.json với quyền của shell bạn đang dùng: $(…) trong trường khóa sẽ chạy ngay khi tải, và crushrc của dự án sẽ kích hoạt ngay khi bạn mở Crush trong thư mục đó. Đừng chạy agent trong kho lưu trữ của người khác mà chưa đọc cấu hình của nó.