OpenHands + JoinGonka Gateway: đại lý trên endpoint của riêng bạn

Dự án hiện có một vài giao diện, và việc bạn đang chạy cái nào quyết định nơi tìm cài đặt mô hình. Các giá trị cài đặt bản thân chúng giống nhau ở mọi nơi — chỉ có đường dẫn tới chúng là khác biệt.

Đối với Agent Canvas, bạn cần Node.js và uv — nó chạy máy chủ cục bộ của tác nhân (chi tiết trong hướng dẫn cài đặt). Hướng dẫn nhắc đến Node.js 22.12 trở lên, nhưng gói từ phiên bản 1.17 yêu cầu Node.js 24 trở lên — hãy cài đặt bản 24 để tránh cảnh báo về phiên bản không tương thích. Cũng có tùy chọn trong container: image ghcr.io/openhands/agent-canvas cung cấp giao diện tại http://localhost:8000/canvas và chỉ thấy các thư mục bạn đã mount.

Khóa JoinGonka. Đă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 phần "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. Trong danh sách công cụ của trình cài đặt @joingonka/setup không có OpenHands, và đây không phải là sơ suất: các cài đặt của nó nằm trong giao diện và trong bộ lưu trữ an toàn của backend, chứ không phải trong tệp cấu hình văn bản mà bạn có thể sửa thủ công từ bên ngoài.

Bước 1. Chạy Agent Canvas và mở Settings > LLM. Trình hướng dẫn thiết lập ban đầu gợi ý nhà cung cấp OpenHands mặc định — bạn có thể bỏ qua bước này, việc quay lại cài đặt sau đó rất dễ dàng.

Bước 2. Nhấp vào Add LLM Profile và chuyển sang tab Advanced: tab Basic chỉ cung cấp các nhà cung cấp và mô hình từ danh sách có sẵn.

Bước 3. Điền vào ba trường sau:

Bước 4. Lưu hồ sơ. Trước khi lưu, Canvas kiểm tra cấu hình bằng một yêu cầu từ backend: nếu khóa bị từ chối hoặc mô hình không khả dụng, hồ sơ sẽ không được lưu và bạn sẽ thấy thông báo lỗi.

Bước 5. Bắt đầu một cuộc trò chuyện mới và gửi một tin nhắn ngắn. Các cuộc trò chuyện đã mở sẽ tiếp tục hoạt động với mô hình mà chúng đã bắt đầu.

Tại sao là openai/. LiteLLM xác định nhà cung cấp thông qua tiền tố của mô hình. Tiền tố openai/ không có nghĩa là «mô hình từ OpenAI», mà có nghĩa là «giao tiếp với máy chủ theo giao thức OpenAI Chat Completions». Chỉ đoạn đầu tiên được cắt bỏ, do đó mã định danh thực tế — deepseek-ai/DeepSeek-V4-Flash-0731 — sẽ truyền đến cổng gateway. Trong tài liệu của OpenHands, cùng sơ đồ đó được hiển thị thông qua ví dụ openai/qwen/qwen3.6-35b-a3b. Nếu thiếu tiền tố, LiteLLM sẽ từ chối hoạt động với thông báo LLM Provider NOT provided.

Tại sao là /v1 và không gì khác. LiteLLM truy cập máy chủ thông qua ứng dụng khách OpenAI chính thức và chính ứng dụng này sẽ tự động thêm /chat/completions. Do đó, địa chỉ bắt buộc phải kết thúc bằng /v1: nếu không có hậu tố, yêu cầu sẽ không đến được API, còn nếu có thêm thành phần thừa, yêu cầu sẽ đi đến một đường dẫn không tồn tại. Một yêu cầu khác của Canvas: địa chỉ phải có thể truy cập được từ backend chứ không chỉ từ trình duyệt. Cổng gateway là một địa chỉ HTTPS công khai, từ container Docker nó được nhìn thấy giống như từ máy chủ (host); các thủ thuật như host.docker.internal chỉ cần thiết cho các mô hình chạy trên máy cục bộ của bạn.

Hồ sơ cho cả ba mô hình. Hãy tạo một hồ sơ cho mỗi mô hình trong mạng và đặt tên ngắn gọn — ví dụ: deepseek, glm và minimax (tài liệu cho biết giới hạn là mười hồ sơ). Bạn có thể chuyển đổi ngay trong cuộc trò chuyện mà không làm mất ngữ cảnh: bằng nút chọn hồ sơ trong trường nhập liệu hoặc bằng lệnh /model glm; lệnh /model không có đối số sẽ hiển thị danh sách. Để không phải nhập khóa vào mỗi hồ sơ, bạn có thể lưu nó một lần trong phần Provider Connections — phần này khả dụng trên backend cục bộ.

Giao diện cũ trong Docker. Các trường vẫn giống nhau: Settings → tab LLM → bật Advanced → Custom Model, Base URL, API Key → Save Changes.

CLI cài bằng một lệnh qua uv và lần chạy đầu tiên sẽ tự hướng dẫn bạn cấu hình model; sau đó quay lại bằng Ctrl+P → Settings:

uv tool install openhands --python 3.12
openhands

Với script thì biến môi trường tiện hơn. Một điểm quan trọng: mặc định CLI bỏ qua chúng và chỉ áp dụng khi có cờ --override-with-envs — cho một lần chạy, không lưu gì:

export LLM_MODEL="openai/deepseek-ai/DeepSeek-V4-Flash-0731"
export LLM_BASE_URL="https://gate.joingonka.ai/v1"
export LLM_API_KEY="jg-your-key"

openhands --override-with-envs

Cùng bộ đó chạy được không cần giao diện — cho CI và tác vụ hàng loạt:

openhands --headless --override-with-envs -t "Read calc.py and tell me in one sentence whether it has a bug."

Ở chế độ headless, agent luôn hành động với tự động phê duyệt, nên hãy chạy nó ở nơi nó được phép làm mọi thứ: trong thư mục riêng hoặc container. Cờ --json biến đầu ra thành luồng sự kiện JSONL — tiện để xử lý trong pipeline. Đó chính là cách chúng tôi kiểm tra ngày 21 tháng 9 năm 2026 trên CLI 1.16.0: phần đầu CLI in ra Agent initialized with model: openai/deepseek-ai/DeepSeek-V4-Flash-0731, sau đó agent đọc file và trả lời đúng trọng tâm.

Cấu hình CLI đã lưu nằm trong ~/.openhands/agent_settings.json: đổi model trong đó bằng cách sửa ba trường của khối llm — model, api_key và base_url. Đừng tạo file từ đầu: wizard lần chạy đầu còn ghi vào đó các cấu hình khác của agent, kể cả nén lịch sử, mà thiếu nó thì cuộc trò chuyện dài sẽ đụng trần ngữ cảnh.

Nếu bạn nhúng agent vào code của mình, OpenHands SDK cũng nhận đúng ba giá trị đó:

from pydantic import SecretStr
from openhands.sdk import LLM

llm = LLM(
    model="openai/deepseek-ai/DeepSeek-V4-Flash-0731",
    base_url="https://gate.joingonka.ai/v1",
    api_key=SecretStr("jg-your-key"),
)

Giá của các mô hình trên mạng là như nhau, vì vậy việc lựa chọn phụ thuộc vào hành vi. Đối với một tác nhân tự hành, có hai con số quan trọng. Cửa sổ ngữ cảnh (Context window): mỗi bước đều gửi lại lịch sử, và cửa sổ càng dài, tác nhân càng làm việc lâu mà không bị mất dữ liệu. Giới hạn phản hồi (Response limit): bước mà tại đó tác nhân viết toàn bộ một tệp lớn phải nằm gọn trong một phản hồi duy nhất. Bảng dưới đây hiển thị kết quả chạy thử cùng một tác vụ (đọc tệp và tìm lỗi) thông qua OpenHands CLI 1.16.0 với SDK 1.21.0.

Quy trình làm việc hiệu quả cho các tác vụ dài tuân theo lời khuyên từ tài liệu OpenHands — lập kế hoạch bằng một mô hình, thực thi bằng một mô hình khác. Bắt đầu cuộc hội thoại bằng cấu hình glm và yêu cầu lập kế hoạch mà không chỉnh sửa tệp; sau đó gửi /model deepseek và ra lệnh thực thi. Lịch sử, tệp và trạng thái tác vụ được giữ nguyên khi chuyển đổi. Giữ cấu hình minimax làm tùy chọn thứ ba: rất thuận tiện để chuyển sang khi hai mô hình kia hết dung lượng trong giờ cao điểm, và bạn cũng có thể dùng nó trong Settings > Application để tạo tiêu đề cuộc hội thoại.

Nén lịch sử. Ngay cả cửa sổ hàng trăm nghìn token cũng có giới hạn trong các tác vụ kéo dài nhiều giờ. Trong OpenHands, bộ ngưng tụ (condenser) chịu trách nhiệm cho việc này: nó thu gọn các sự kiện cũ thành một bản tóm tắt ngắn gọn, giúp giảm độ trễ và tiêu thụ token trong các cuộc hội thoại dài, theo tài liệu hướng dẫn. Trong Agent Canvas, nó được cấu hình trong mục Settings > Condenser; trong quá trình chạy thử của chúng tôi, CLI đã tự động kích hoạt nó với ngưỡng 80 sự kiện.

Giới hạn mô hình. OpenHands lấy cửa sổ ngữ cảnh và giới hạn phản hồi từ danh mục LiteLLM, và các mã định danh của mạng Gonka không có trong đó (chúng tôi đã kiểm tra trên LiteLLM 1.81), vì vậy tác nhân không có giá trị riêng cho các mô hình này. Điều này không ảnh hưởng đến công việc: cổng (gateway) tự áp dụng giới hạn phản hồi theo bảng trên. Nếu bạn muốn đặt giới hạn một cách rõ ràng — trong SDK đó là các trường max_input_tokens và max_output_tokens, và trong Canvas, tab All sẽ mở ra danh sách đầy đủ các trường cấu hình. Thông tin chi tiết về mô hình mặc định có trong bài đánh giá DeepSeek V4 Flash.

Bạn có thể xác minh xem các yêu cầu có thực sự đi qua cổng gateway hay không từ hai phía. Từ phía OpenHands: thực hiện một cuộc trò chuyện mới và đưa ra một yêu cầu ngắn gọn như "đọc README và tóm tắt trong một câu": tác nhân (agent) phải gọi công cụ và trả lời. Từ phía cổng gateway: truy cập vào bảng điều khiển, phần "Sử dụng": yêu cầu sẽ xuất hiện trong mục "Theo mô hình" (By models), và phần "Theo khóa" (By keys) sẽ cập nhật thời gian của yêu cầu cuối cùng. Nếu trống, có nghĩa là cuộc trò chuyện đang diễn ra trên một cấu hình (profile) khác: hãy kiểm tra xem cấu hình nào đang được đánh dấu là hoạt động.

Theo tài liệu của OpenHands, số lần thử lại và thời gian chờ giữa các lần khi gặp lỗi 429 được cấu hình qua các biến LLM_NUM_RETRIES, LLM_RETRY_MIN_WAIT và LLM_RETRY_MAX_WAIT. Các giá trị mặc định trong tài liệu và SDK có thể khác nhau, vì vậy hãy dựa vào giá trị thực tế: trong trạng thái trò chuyện của CLI 1.16.0, chúng tôi đã thấy 5 lần thử lại với khoảng chờ từ 8 đến 64 giây.

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 — mức giá này áp dụng 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 dữ liệu thực tế.

Các ước tính ở cột bên phải dựa trên giá tháng 9 năm 2026; cách vận hành kinh tế của các tác nhân được giải thích chi tiết trong bài viết về API rẻ nhất cho các tác nhân AI.

Giới hạn chi tiêu. OpenHands khuyến nghị thiết lập giới hạn chi tiêu — gateway đã tích hợp sẵn vào mô hình thanh toán: số dư được trả trước, và tác nhân sẽ không thể tiêu vượt quá số tiền trong tài khoản. Số dư còn lại và mức tiêu thụ hàng ngày có thể xem trong bảng điều khiển. Đối với CI và các tác vụ tự động hóa chạy nền, hãy tạo một khóa riêng biệt để tránh trộn lẫn mức tiêu thụ với tài khoản chính; các khóa con có giới hạn hàng ngày được mô tả trong bài viết về Management Keys.

Ranh giới tin cậy. Agent Canvas chạy qua npm sẽ hoạt động với quyền của người dùng và có thể truy cập toàn bộ hệ thống file. Đối với code lạ, hãy sử dụng phiên bản Docker: tác nhân sẽ chỉ nhìn thấy thư mục được mount. Đây là đặc tính của chính OpenHands, không phụ thuộc vào nhà cung cấp mô hình.

Lịch sử trò chuyện vẫn nằm trong quyền kiểm soát của bạn. OpenHands lưu trữ lịch sử cuộc trò chuyện cục bộ tại ~/.openhands và gửi cho mô hình mỗi khi thực hiện bước tiếp theo; gateway không lưu lại lịch sử — lời nhắc (prompt) và code của bạn sẽ không còn trên đó sau khi nhận phản hồi.

Nếu tác vụ có hình ảnh — ảnh chụp giao diện, sơ đồ — hãy tạo một cấu hình riêng biệt với mô hình vision: các mô hình của mạng Gonka hiện tại là mô hình văn bản. Đối với code, lệnh và file, đây không phải là hạn chế.