Goose + JoinGonka Gateway: nhà cung cấp riêng và khóa trong keyring

Bước 1: cài Goose. Các cách chính thức cho CLI từ tài liệu dự án:

# macOS and Linux: the script puts the binary in ~/.local/bin
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

# macOS, Homebrew
brew install block-goose-cli

Biến CONFIGURE=false tắt trình hướng dẫn goose configure, thứ mà script nếu không sẽ chạy ngay sau khi cài đặt: trình cài đặt sẽ cấu hình nhà cung cấp. Nếu thư mục ~/.local/bin không có trong PATH, script sẽ thông báo ngay. Với Windows, trong cùng repository có script download_cli.ps1, còn ứng dụng desktop thì tải từ trang tài liệu; cả nó và CLI đọc cùng một cấu hình, nên mọi thứ bên dưới đều áp dụng cho cả hai. Kiểm tra — goose --version.

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 với tiền tố jg- trong mục "API-keys". Một khóa và một số dư áp dụng 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 goose

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

• tạo tệp nhà cung cấp custom_providers/custom_joingonka.json với địa chỉ gateway và ba mô hình trong mạng cùng cửa sổ ngữ cảnh thực, với quyền 600. Các tên custom_joingonka và CUSTOM_JOINGONKA_API_KEY — giống như Goose tự suy ra từ tên "JoinGonka", nên khóa từ trình hướng dẫn sẽ nằm đúng chỗ;
• đặt JoinGonka làm nhà cung cấp mặc định với mô hình DeepSeek V4 Flash — nhưng chỉ khi nhà cung cấp chưa được chọn hoặc đã chọn nhà cung cấp của chúng tôi với mô hình trống hoặc đã rời khỏi mạng. Lựa chọn của người khác sẽ không bị động đến, mà thay vào đó in ra lệnh để thử: goose session --provider custom_joingonka --model …;
• đặt khóa vào secrets.yaml, chỉ khi kho lưu bí mật của Goose chắc chắn là dạng tệp; nếu không sẽ nói thẳng rằng còn một bước nữa, — chi tiết trong phần về khóa;
• tạo bản sao lưu cho các tệp đã thay đổi và cuối cùng gửi một yêu cầu thực tế đến gateway để kiểm tra ngay khóa, địa chỉ và mô hình.

Trình cài đặt tìm thư mục cấu hình giống như chính Goose: ~/.config/goose trên Linux và macOS, %APPDATA%\Block\goose\config trên Windows, <root>/config khi có đặt GOOSE_PATH_ROOT. 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 lại. Chế độ không hỏi lấy khóa từ biến môi trường:

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

Tất cả những gì trình cài đặt thực hiện, bạn đều có thể tự làm bằng tay. Nhà cung cấp là một tệp JSON riêng biệt ~/.config/goose/custom_providers/custom_joingonka.json; tên tệp trùng với trường name:

{
  "name": "custom_joingonka",
  "engine": "openai",
  "display_name": "JoinGonka",
  "description": "JoinGonka Gateway — Gonka AI inference (OpenAI-compatible)",
  "api_key_env": "CUSTOM_JOINGONKA_API_KEY",
  "base_url": "https://gate.joingonka.ai/v1/chat/completions",
  "models": [
    { "name": "deepseek-ai/DeepSeek-V4-Flash-0731", "context_limit": 380000 },
    { "name": "zai-org/GLM-5.3-Flash", "context_limit": 390000 },
    { "name": "MiniMaxAI/MiniMax-M2.7", "context_limit": 200000 }
  ],
  "supports_streaming": true,
  "requires_auth": true
}

Không có giới hạn phản hồi riêng biệt cho mục nhập mô hình của Goose. Đối với các mô hình này, nó hoàn toàn không truyền giới hạn trong yêu cầu — chúng tôi đã kiểm tra điều này qua nhật ký yêu cầu của nó — và ở chế độ streaming, bản thân cổng sẽ giới hạn phản hồi theo giới hạn của mô hình: 32.768 token cho DeepSeek V4 Flash, 8.192 cho GLM-5.3 Flash và MiniMax M2.7. Bạn không cần đặt biến toàn cục GOOSE_MAX_TOKENS cho việc này: nó áp dụng cho tất cả các nhà cung cấp cùng một lúc.

Goose đọc tệp nhà cung cấp bằng cách phân tích JSON nghiêm ngặt: chỉ cần một nhận xét hoặc dấu phẩy thừa là nhà cung cấp sẽ biến mất khỏi danh sách. Bạn có thể tạo nó bằng trình hướng dẫn (goose configure → Custom Providers), nhưng trình hướng dẫn không hỏi về cửa sổ ngữ cảnh — bạn sẽ phải tự thêm nó bằng tay.

Nhà cung cấp và mô hình mặc định nằm trong ~/.config/goose/config.yaml. Đây là cách Goose tự ghi lại chúng:

active_provider: custom_joingonka
providers:
  custom_joingonka:
    enabled: true
    model: deepseek-ai/DeepSeek-V4-Flash-0731
    configured: true

Cách bố trí cũ — các khóa phẳng GOOSE_PROVIDER và GOOSE_MODEL ở gốc tệp — cũng hoạt động: Goose đọc nó và tự chuyển đổi sang định dạng mới khi lưu cài đặt lần đầu tiên, giống như chúng tôi sau khi chạy goose configure. Trình cài đặt trên tệp trống sẽ viết các khóa phẳng — bất kỳ phiên bản nào cũng hiểu được chúng. Các biến môi trường cùng tên có ưu tiên cao hơn tệp: nếu chúng được đặt trong shell, lựa chọn từ config.yaml sẽ không có hiệu lực, và trình cài đặt sẽ cảnh báo về điều đó.

Trong tệp nhà cung cấp của Goose chỉ có tên secret — CUSTOM_JOINGONKA_API_KEY. Goose tìm giá trị theo thứ tự: trong biến môi trường cùng tên, rồi đến kho secret hệ thống (keyring, trên macOS là Keychain), sau đó là tệp secrets.yaml cạnh tệp cấu hình. Secret chỉ được ghi vào tệp khi kho của Goose là dạng tệp, và nằm đó dưới dạng văn bản thuần với quyền 600. Còn trong config.yaml thì Goose hoàn toàn không tìm khóa (tài liệu).

Kho chuyển sang dạng tệp khi keyring bị tắt — bằng biến GOOSE_DISABLE_KEYRING với bất kỳ giá trị nào hoặc dòng GOOSE_DISABLE_KEYRING: true trong config.yaml — hoặc không khả dụng: máy chủ không có phiên đồ họa, container, CI. Trong trường hợp thứ hai, Goose ghi vào log «Keyring unavailable. Using file storage for secrets.» và tự chuyển sang tệp — đúng như những gì chúng ta thấy trong container. Trình cài đặt không biết ghi vào keyring, mà cũng không tự tắt nó thay bạn: Goose sẽ không còn thấy các secret đã nằm ở đó. Từ đó có các tình huống:

Bước còn lại. Chạy goose configure và trả lời các câu hỏi của wizard — đây là cách chúng hiển thị trong lần chạy của chúng tôi:

• What would you like to configure? → Configure Providers;
• Which model provider should we use? → JoinGonka (trong máy chúng tôi nó đứng đầu);
• Would you like to set CUSTOM_JOINGONKA_API_KEY? (optional) → Yes, rồi tại Enter value for CUSTOM_JOINGONKA_API_KEY dán khóa — các ký tự sẽ được thay bằng ô vuông. Khóa được lưu ngay lập tức;
• Would you like to configure advanced settings? → No;
• Select a model — Goose lấy danh sách từ gateway: MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731, zai-org/GLM-5.3-Flash. Con trỏ đang ở dòng đầu — để giữ model mà trình cài đặt đã chọn, hãy dùng phím mũi tên chọn DeepSeek V4 Flash. Sau một truy vấn kiểm tra, wizard sẽ kết thúc bằng dòng «Configuration saved successfully».

Trong Goose Desktop, đường đi như sau: Settings → Models → Configure providers → JoinGonka → khóa → Submit. Không muốn dán khóa thủ công — hãy đặt nó vào biến môi trường và chạy wizard từ cùng shell đó: Goose sẽ báo «CUSTOM_JOINGONKA_API_KEY is set via environment variable» và đề nghị lưu giá trị:

read -s CUSTOM_JOINGONKA_API_KEY && export CUSTOM_JOINGONKA_API_KEY
goose configure

Còn cho một lần chạy, bạn có thể truyền khóa mà hoàn toàn không lưu: CUSTOM_JOINGONKA_API_KEY=jg-your-key goose session, trong PowerShell là $env:CUSTOM_JOINGONKA_API_KEY = "jg-your-key"; goose session. Biến môi trường có ưu tiên cao hơn giá trị đã lưu, nhưng chỉ tồn tại đến khi đóng shell.

Trước tiên, hãy xem Goose thực sự thấy những cài đặt nào:

goose info -v

Trong khối «goose Configuration» phải có các dòng GOOSE_PROVIDER: custom_joingonka và GOOSE_MODEL với ID của model. Tiếp theo — chạy thử một lần không dùng phiên tương tác: đặt vào một thư mục trống một file có lỗi rõ ràng và yêu cầu nó tìm ra.

goose run --no-session -t "Read calc.py and tell me in one sentence whether it has a bug."

Cờ --no-session không lưu lần chạy vào lịch sử. Ở phần đầu sẽ xuất hiện một dòng kiểu ● new session · custom_joingonka deepseek-ai/DeepSeek-V4-Flash-0731, sau đó là lệnh gọi công cụ — ▸ shell với câu lệnh cat calc.py — và câu trả lời kèm lỗi đã tìm ra. Để dùng model khác cho một lần chạy, dùng --model: zai-org/GLM-5.3-Flash hoặc MiniMaxAI/MiniMax-M2.7. Trong lần chạy ngày 23 tháng 9 năm 2026 của chúng tôi, cả ba model của mạng lưới đều hoàn thành vòng «yêu cầu → công cụ → kết quả → trả lời». Theo mặc định CLI Goose ẩn phần suy luận của model — có thể hiện chúng bằng biến GOOSE_CLI_SHOW_THINKING=1 nếu đầu ra đi vào terminal. 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 model» và «Theo key».

Nếu có gì đó không ổn, chẩn đoán thường đọc được ngay từ thông báo:

Agent tiêu tốn token khác với chat thông thường. Ngay trong cấu hình mặc định, Goose gửi cho model mô tả của mười tám công cụ tích hợp, và trong lần chạy của chúng tôi, mỗi lượt tiêu tốn khoảng 4,6 nghìn token đầu vào trước cả câu hỏi của bạn. Nhiệm vụ «đọc file và tìm lỗi» mất hai-ba lượt và 10-15 nghìn token, gần như tất cả là đầu vào; Goose tự thực hiện thêm một truy vấn ngắn để đặt tên cho phiên. Các tiện ích mở rộng không cần thiết có thể được tắt trong goose configure → Toggle Extensions — đây là cách dễ nhất để giảm đầu vào.

Thông qua JoinGonka Gateway, token có giá $0.0069 cho mỗi triệu token đầu vào và $0.021 cho mỗi triệu token đầu ra — giá này giống nhau cho tất cả các model 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 — cách bạn có thể thanh toán cho các model trong Goose:

Mức tiêu thụ chính xác và số dư còn lại nằm trong bảng điều khiển, trong các mục «Sử dụng» và «Thanh toán». Tại sao DeepSeek V4 Flash được chọn làm mặc định — với giới hạn phản hồi lớn nhất trong mạng — đã được phân tích chi tiết trong bài đánh giá model.

Chế độ xác nhận. Theo mặc định, Goose hoạt động ở chế độ auto — hoàn toàn tự động: tự sửa và xóa file, chạy lệnh và dùng các tiện ích mở rộng mà không hỏi gì. Trên dự án của mình thì tiện, nhưng với mã nguồn của người khác thì nên siết chặt chế độ hơn:

# inside a session
/mode smart_approve

# permanently, as a line in config.yaml
GOOSE_MODE: smart_approve

Đây là thuộc tính của chính Goose, không phụ thuộc vào provider của model.

Đổi model. Trong phiên — lệnh /model kèm ID, ví dụ /model zai-org/GLM-5.3-Flash; cho một lần chạy — cờ --model của goose run và goose session; vĩnh viễn — goose configure hoặc dòng model trong config.yaml. Provider vẫn giữ nguyên. GLM-5.3 Flash có suy luận rất tốt cho logic rối rắm, nhưng giới hạn câu trả lời của nó là 8192 token, và một phần trong đó dành cho suy luận — chi tiết trong bài đánh giá model.

Chạy không cần giám sát. goose run phù hợp cho script và CI: cờ -q chỉ để lại câu trả lời của model trong đầu ra, --output-format json trả kết quả để phân tích. Các giới hạn --max-turns (số lượt agent thực hiện không có con người tham gia) và --max-tool-repetitions (số lần liên tiếp có thể gọi một công cụ với cùng đối số) giúp tránh lặp vô hạn.

Quyền riêng tư. Thống kê sử dụng ẩn danh trong Goose mặc định bị tắt (GOOSE_TELEMETRY_ENABLED). Gateway không lưu nội dung prompt và câu trả lời — trong thống kê chỉ còn lại các số liệu tổng hợp về mức dùng.