Factory Droid + JoinGonka Gateway: BYOK trên các mô hình mạng Gonka

Bước 1: cài Droid. Các cách chính thức từ tài liệu Factory:

# macOS and Linux
curl -fsSL https://app.factory.ai/cli | sh

# Homebrew
brew install --cask droid

# Windows (PowerShell)
irm https://app.factory.ai/cli/windows | iex

# via npm
npm install -g droid

Script đặt binary vào ~/.local/bin và gợi ý cách thêm thư mục vào PATH; trên Linux tài liệu yêu cầu cài thêm gói xdg-utils. Kiểm tra bằng droid --version.

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

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

npx @joingonka/setup --tool droid

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

• thêm vào mảng customModels của file ~/.factory/settings.json (trên Windows là %USERPROFILE%\.factory\settings.json) một bản ghi cho mỗi model của mạng lưới: địa chỉ gateway, loại provider generic-chat-completion-api, key dạng literal, cửa sổ ngữ cảnh và giới hạn phản hồi thực tế; file sẽ có quyền 600;
• đặt model mặc định — sessionDefaultSettings.model — thành DeepSeek V4 Flash, nhưng chỉ khi chưa chọn model nào hoặc model đang trỏ đến một model đã rời mạng lưới. Model từ catalog của Factory hoặc bản ghi BYOK của người khác sẽ không bị ghi đè, mà chỉ gợi ý cách chuyển đổi;
• lưu bản sao của file cũ, giữ nguyên các bản ghi khác trong customModels, các cài đặt còn lại và chú thích; file không thể phân tích sẽ không bị ghi đè mà sẽ thông báo cần sửa gì;
• cuối cùng gửi một request trực tiếp đến gateway và cho biết key, địa chỉ và model có được chấp nhận hay không.

Model mặc định khác được chỉ định bằng cờ --model với viết tắt deepseek, glm hoặc minimax — model được chỉ định rõ ràng luôn được ghi lại. Với dotfile và server có chế độ không hỏi, key trong chế độ này lấy từ biến môi trường:

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

Không cần khởi động lại Droid: nó tự nhận ra thay đổi trong settings.json. Dòng ! Could not verify right now với phản hồi 429 ở cuối nghĩa là model đang bận, không phải lỗi cấu hình — cấu hình đã được ghi xong.

Mọi thứ trình cài đặt thực hiện đều có thể viết tay. Cài đặt người dùng của Droid được lưu trong ~/.factory/settings.json; nếu tệp chưa tồn tại, Droid sẽ tạo nó trong lần chạy đầu tiên. Đối với mạng Gonka, bạn cần mảng customModels và một model mặc định:

{
  "customModels": [
    {
      "model": "deepseek-ai/DeepSeek-V4-Flash-0731",
      "id": "custom:deepseek-ai/DeepSeek-V4-Flash-0731",
      "displayName": "DeepSeek V4 Flash (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 32768,
      "maxContextLimit": 380000,
      "noImageSupport": true
    },
    {
      "model": "zai-org/GLM-5.3-Flash",
      "id": "custom:zai-org/GLM-5.3-Flash",
      "displayName": "GLM 5.3 Flash (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192,
      "maxContextLimit": 390000,
      "noImageSupport": true
    },
    {
      "model": "MiniMaxAI/MiniMax-M2.7",
      "id": "custom:MiniMaxAI/MiniMax-M2.7",
      "displayName": "MiniMax M2.7 (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192,
      "maxContextLimit": 200000,
      "noImageSupport": true
    }
  ],
  "sessionDefaultSettings": {
    "model": "custom:deepseek-ai/DeepSeek-V4-Flash-0731"
  }
}

Model mặc định được lưu trong sessionDefaultSettings.model và tham chiếu đến bản ghi qua id của nó. Tài liệu Factory có nhắc đến cả khóa model ở gốc tệp, nhưng trong lần chạy thử của chúng tôi, droid exec không có cờ -m lại lấy model từ sessionDefaultSettings — và vẫn như vậy sau khi đổi giá trị.

Khóa nằm trong tệp dưới dạng văn bản thuần: hãy đóng tệp bằng lệnh chmod 600 ~/.factory/settings.json và đừng chuyển các bản ghi chứa khóa vào .factory/settings.json của dự án — tệp này thường bị đưa vào kho mã nguồn. Còn nếu sau khi chạy Droid tệp trông khác đi thì cũng bình thường: mỗi khi lưu bất kỳ cài đặt nào, Droid ghi lại toàn bộ tệp — sắp xếp các khóa, thêm trường index cho các bản ghi và không giữ lại chú thích. Quyền 600 vẫn được giữ nguyên, và trình cài đặt vẫn cập nhật những bản ghi như vậy một cách bình thường.

Droid hiển thị các bản ghi của riêng mình tách biệt với danh mục: theo tài liệu, ở chế độ tương tác, lệnh /model liệt kê chúng trong mục Custom models, còn Ctrl+N chuyển đổi giữa các model ngay tại ô nhập. Ở chế độ chạy một lần, model được chỉ định bằng cờ -m với giá trị từ trường id, dấu gạch chéo được viết nguyên như vậy: droid exec -m custom:zai-org/GLM-5.3-Flash "…".

Nếu bạn gõ sai tên, Droid sẽ trả lời Invalid model và liệt kê tất cả các model mà nó thấy, bao gồm cả các model của riêng bạn dưới dạng custom:… (display name): qua đó cũng thấy được rằng các bản ghi đã tải thành công. Tên theo kiểu tài liệu Factory, từ nhãn hiển thị và số thứ tự (custom:DeepSeek-V4-Flash-(Gonka)-0), sẽ không hoạt động khi có id rõ ràng — trong lần chạy thử của chúng tôi, nó cũng cho ra Invalid model.

Những gì cần tài khoản Factory. Các model của riêng bạn giải quyết vấn đề thanh toán token, nhưng không giải quyết việc đăng nhập vào chính sản phẩm. Đây là những gì lần chạy Droid 0.225.1 mà không đăng nhập tài khoản cho thấy:

Để làm việc trong giao diện, hãy tạo tài khoản Factory và đăng nhập qua trình duyệt — mục Login hoặc lệnh /login; trên máy không có trình duyệt, tài liệu đề xuất dùng khóa từ cài đặt tài khoản trong biến FACTORY_API_KEY. Việc chạy droid exec mà không đăng nhập thì tiện để thử nghiệm, nhưng không được mô tả chính thức — đừng dựa vào nó trong CI. Theo trang giá của Factory, BYOK nằm trong tất cả các gói cá nhân với hạn mức miễn phí, và vượt hạn mức thì việc dùng BYOK được tính phí theo điều kiện của gói; điều kiện hiện hành — tại factory.ai/pricing. Token của các model mạng lưới thì được thanh toán riêng — từ số dư JoinGonka.

Nên chọn model nào. Giá của tất cả các model mạng lưới đều như nhau, nên lựa chọn là về hành vi. Đây là cách chúng hoạt động trong lần chạy droid exec của chúng tôi trên cùng một tác vụ — đọc file và tìm lỗi:

Cờ -r (mức độ suy luận), theo tài liệu Factory, không được áp dụng cho các model BYOK. Lý do vì sao DeepSeek V4 Flash được chọn làm mặc định được phân tích trong bài đánh giá model.

Hãy đặt vào một thư mục trống tệp calc.py có một lỗi rõ ràng — chẳng hạn, diện tích hình chữ nhật mà các cạnh được cộng thay vì nhân — rồi yêu cầu Droid tìm ra lỗi đó:

droid exec "Read the file calc.py in the current project directory and tell me in one sentence whether it has a bug."

Không có cờ nào, droid exec hoạt động ở chế độ chỉ đọc: xem tệp thì được, sửa thì không. Agent sẽ tự gọi công cụ đọc và trả lời đúng trọng tâm, kèm chỉ ra biểu thức bị lỗi. Với cờ -o json, câu trả lời đến dưới dạng một đối tượng duy nhất, rất tiện để xử lý bằng script (kết quả được rút gọn):

{"type":"result","subtype":"success","is_error":false,"duration_ms":2239,"num_turns":2,
 "result":"Yes, the file has a bug: the rectangle area is computed as the sum of the side lengths, but it should be their product (width * height). …",
 "usage":{"input_tokens":19016,"output_tokens":146,"factory_credits":0,"ttft_ms":747}}

Trường factory_credits: 0 xác nhận rằng công việc chạy trên model của bạn, chứ không phải bằng credit của Factory. Để agent có thể sửa tệp, hãy thêm mức tự chủ: droid exec --auto low "Fix the bug in calc.py and change nothing else." — trong lần chạy thử của chúng tôi, DeepSeek V4 Flash đã đọc tệp, thay phép cộng bằng phép nhân và tự chạy script để chắc chắn rằng kết quả in ra là 12.

Kiểm tra thứ ba — từ phía gateway: trong trang quản lý ở mục «Sử dụng», yêu cầu sẽ xuất hiện trong phần phân tách «Theo model», còn trong khối «Theo key» thì thời gian của yêu cầu gần nhất sẽ được cập nhật.

Nếu có gì đó không ổn, hãy lưu ý một đặc điểm của Droid: trên console, droid exec chỉ in ra Error during droid execution: Exec failed (trong JSON là "result":"Exec failed"), còn nguyên nhân thật vẫn nằm trong log. Có thể lấy ra bằng một lệnh duy nhất:

grep agent_error_count ~/.factory/logs/droid-log-single.log | grep -o '"errorMessage":"[^,]*' | tail -1

Công cụ đại lý tiêu tốn token khác với chat: với mỗi câu lệnh của bạn, Droid thêm vào đó lời nhắc hệ thống, mô tả công cụ và bản chụp thư mục làm việc, và một tác vụ có thể mất vài lượt thực hiện. Trong lần chạy thử của chúng tôi, mỗi lượt tiêu tốn khoảng 9,5 nghìn token đầu vào ngay cả trước câu hỏi của bạn: tác vụ «đọc tệp và tìm lỗi» mất hai lượt và khoảng 19 nghìn token, «sửa và kiểm tra» — bốn lượt và khoảng 44 nghìn token. Vì vậy, giá mỗi token ở đây rất quan trọng.

Thông qua JoinGonka Gateway, token có giá $0.0069 cho một triệu token đầu vào và $0.021 cho một 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 cập nhật trên trang này từ nguồn trực tiếp.

Các ước tính trong 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 mô hình trong Droid:

Lệnh /cost trong giao diện Droid hiển thị thống kê phiên, và mức tiêu thụ chính xác cũng như số dư còn lại cho các mô hình BYOK — nằm trong bảng điều khiển của cổng, tại mục «Sử dụng» (Usage) và «Thanh toán» (Billing). Hãy tạo một khóa riêng cho Droid — lưu lượng của nó sẽ hiển thị ở một dòng riêng biệt.

Tính tự chủ. Ở chế độ chạy một lần, mặc định Droid chỉ đọc, còn quyền hạn được mở rộng theo các mức: --auto low — sửa tệp, --auto medium — thêm cả cài đặt dependency, build, test và commit cục bộ, --auto high — cho tới cả push và deploy. Cờ --skip-permissions-unsafe gỡ bỏ mọi kiểm tra — chỉ dùng cho container dùng một lần. Ở chế độ tương tác, mức được chuyển bằng Ctrl+L, còn mức khởi đầu do sessionDefaultSettings.autonomyLevel quy định; mặc định ở đó là off — mọi thứ đều phải xác nhận.

Chữ ký trong commit. Tùy chọn includeCoAuthoredByDroid mặc định được bật: Droid thêm vào thông điệp commit một dòng ghi nhận đồng tác giả. Nếu không cần, hãy ghi "includeCoAuthoredByDroid": false vào settings.json.

Phiên làm việc được lưu ở đâu. Sau khi đăng nhập tài khoản, mặc định Droid đồng bộ các phiên CLI lên bản web của Factory — việc này do cloudSessionSync đảm nhiệm. Theo tài liệu, các key BYOK vẫn ở lại cục bộ; nếu muốn cả nội dung trao đổi cũng chỉ nằm trên máy, hãy đặt "cloudSessionSync": false. Về phía mình, 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 tiêu thụ.

Cập nhật. Bản cài bằng script tự cập nhật; có thể ghim phiên bản bằng biến FACTORY_DROID_AUTO_UPDATE_ENABLED=false hoặc bằng lệnh droid update --version <version>; các bản build từ npm không tự cập nhật. Sau khi cập nhật, chỉ cần một lệnh droid exec để kiểm tra rằng các model của mạng vẫn còn nguyên.

Hình ảnh. Các model của mạng là model văn bản; để xử lý ảnh chụp màn hình, hãy để sẵn một bản ghi với model có khả năng nhìn hình, ở nhà cung cấp khác.

Nếu bắt buộc phải làm việc mà không có tài khoản nhà cung cấp. Chính những model của mạng này cũng kết nối được với các terminal agent mở, vốn không cần đăng nhập — chẳng hạn với OpenCode bằng cùng bộ cài đó, với cờ --tool opencode.