Dành cho AI agent: hướng dẫn từng bước để thiết lập — /docs/agents.md, chỉ mục tài liệu — /llms.txt.
Dành cho AI agent
Cách giao việc tích hợp cho một AI agent: prompt có sẵn cho mọi công cụ. Dưới đây — địa chỉ tài liệu dạng máy đọc và một skill mà agent cài đặt chỉ bằng một lệnh.
Prompt cho agent#
Gửi prompt này cho AI agent của bạn. Nó sẽ thiết lập công cụ theo hướng dẫn bên dưới và sẽ hỏi bạn key.
Kết nối công cụ của bạn với JoinGonka Gateway — API tương thích OpenAI và Anthropic của mạng Gonka — theo hướng dẫn tại https://gate.joingonka.ai/docs/agents.md. Tôi sẽ tự đưa key: đừng lưu key vào file trong repo và đừng thay đổi biến môi trường toàn cục. Cuối cùng, kiểm tra kết nối bằng một request ngắn và báo kết quả.Dưới đây là hướng dẫn. Agent nhận nó dưới dạng Markdown tại địa chỉ /docs/agents.md.
Quy tắc#
- API key do con người tạo — trong trang cá nhân tại gate.joingonka.ai. Đừng tự đăng ký tài khoản hay tạo key: hãy hỏi key từ người dùng.
- Giữ key trong biến môi trường
JOINGONKA_API_KEYcủa phiên terminal. Đừng ghi nó vào các file nằm trong git, đừng commit và đừng in ra trong báo cáo. - Đừng thay đổi biến toàn cục
OPENAI_*vàANTHROPIC_*— dù trong profile shell hay trong hệ thống: các công cụ khác của người dùng cũng đọc chúng. Key và địa chỉ được ghi vào config của chính công cụ — trình cài đặt làm đúng như vậy.
Thông tin cần biết#
- Base URL cho client OpenAI API:
https://gate.joingonka.ai/v1 - Base URL cho client Anthropic API, không có
/v1:https://gate.joingonka.ai - Key được truyền trong header
Authorization: Bearer jg-…hoặcx-api-key: jg-… - Key để gọi model bắt đầu bằng
jg-; key quản lýgm-không cho truy cập vào model. - Mô hình đề xuất:
MiniMaxAI/MiniMax-M2.7 - Danh sách mô hình khả dụng:
GET https://gate.joingonka.ai/v1/models - Mỗi key — tối đa 120 yêu cầu mỗi phút, vượt giới hạn sẽ trả về 429 kèm header
Retry-After. Giới hạn và timeout — trong phản hồiGET /v1/capabilities, trườnglimits.
Thiết lập#
Tìm công cụ của người dùng trong bảng ở cuối mục. Nếu có giá trị --tool — thiết lập bằng trình cài đặt, nếu không — làm thủ công theo hướng dẫn.
Qua trình cài đặt#
Một lệnh không cần hỏi gì: key — từ biến môi trường, model — qua flag. Trình cài đặt sẽ ghi config của công cụ, lưu bản sao của bản cũ và kiểm tra kết nối bằng yêu cầu đến gateway.
JOINGONKA_API_KEY=<key> npx -y @joingonka/setup --tool <id> --model MiniMaxAI/MiniMax-M2.7 --non-interactive| Flag | Tác dụng |
|---|---|
--tool <id> | Công cụ nào cần thiết lập — giá trị từ bảng công cụ. |
--model <id> | ID model: khuyến nghị là MiniMaxAI/MiniMax-M2.7, tất cả các model có sẵn — GET /v1/models. |
--non-interactive | Không hỏi gì: key được lấy từ JOINGONKA_API_KEY. |
--scope local | Config trong dự án hiện tại, không phải trong thư mục home. Chỉ dành cho Claude Code; file config được thêm vào .gitignore. |
--no-verify | Không kiểm tra kết nối sau khi ghi config. |
| Mã thoát | Ý nghĩa |
|---|---|
0 | Xong: config đã được ghi, yêu cầu kiểm tra đã thành công. Nếu không thể kiểm tra do mạng hoặc số dư, trình cài đặt sẽ in cảnh báo nhưng vẫn thoát với mã 0 — hãy thông báo cho người dùng. |
1 | Thiết lập thất bại, nguyên nhân nằm trong output: ví dụ, giá trị --tool không xác định, JOINGONKA_API_KEY chưa được đặt hoặc key không bắt đầu bằng jg-. |
2 | Config đã được ghi nhưng yêu cầu kiểm tra không thành công: hãy kiểm tra lại key và ID model. |
Nếu công cụ đang chạy, hãy khởi động lại: config được đọc khi khởi động.
Thủ công#
Với công cụ không có trình cài đặt, hãy mở hướng dẫn của nó (link trong bảng bên dưới) và đặt ba giá trị:
- địa chỉ base —
https://gate.joingonka.ai/v1cho client OpenAI API hoặchttps://gate.joingonka.aicho client Anthropic API; - key — trong trường API key trong cài đặt của công cụ;
- model —
MiniMaxAI/MiniMax-M2.7hoặc một model khác từGET /v1/models.
Công cụ và hướng dẫn#
| Công cụ | --tool |
|---|---|
| Cursor | cursor |
| Claude Code | claude-code |
| OpenClaw | openclaw |
| OpenCode | opencode |
| Continue | continue |
| Cline | cline |
| Aider | aider |
| LangChain | — |
| n8n | — |
| Open WebUI | — |
| LibreChat | — |
| Hermes | hermes |
| Kilo Code | kilo |
| Roo Code | roo |
| LlamaIndex | — |
| PydanticAI | — |
| Vercel AI SDK | — |
| TanStack AI | — |
| ZCode | zcode |
| JetBrains | jetbrains |
| Copilot BYOK | copilot-byok |
| Zed | zed |
| Pi | pi |
| Codex CLI | codex |
| DeepSeek Harness | — |
| MiniMax Code | minimax-code |
| Warp | — |
| Trae | — |
| Cherry Studio | — |
| omp (Oh My Pi) | omp |
| OpenHands | — |
| Qwen Code | qwen-code |
| Goose | goose |
| Crush | crush |
| Zoo Code | zoo |
| Kimi Code | kimi-code |
| Factory Droid | droid |
| MiMo Code | mimo-code |
Kiểm tra#
Kiểm tra key — gọi số dư: không tốn token, key được lấy từ JOINGONKA_API_KEY:
curl -s https://gate.joingonka.ai/api/balance \
-H "Authorization: Bearer $JOINGONKA_API_KEY"Kiểm tra địa chỉ, key và model — một yêu cầu ngắn đến model:
curl -s https://gate.joingonka.ai/v1/chat/completions \
-H "Authorization: Bearer $JOINGONKA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "MiniMaxAI/MiniMax-M2.7", "messages": [{"role": "user", "content": "Say OK"}], "max_tokens": 32}'Phản hồi 200 kèm văn bản của model — kết nối hoạt động. Trình cài đặt tự làm kiểm tra như vậy: sau đó chỉ cần mã thoát 0 là đủ.
Nếu có gì đó không ổn#
Lỗi xuất hiện trong trường error của body phản hồi — kèm loại lỗi và nội dung nguyên nhân.
| Phản hồi | Cần làm gì |
|---|---|
401 authentication_error | Key không được chấp nhận. Kiểm tra rằng nó đã được copy đầy đủ và truyền trong Authorization: Bearer hoặc x-api-key; key mới do người dùng tạo. |
402 insufficient_funds | Số dư không còn tiền. Hãy báo cho người dùng: số dư được nạp trong trang cá nhân. |
402 child_key_limit_exceeded | Đã hết hạn mức của key con. Cần key khác hoặc hạn mức lớn hơn — điều này do chủ key quyết định. |
403 forbidden | Đây là key quản lý gm-: nó không cho truy cập vào model. Cần key jg-. |
400 invalid_request_error | Lỗi trong yêu cầu. Nếu không tìm thấy model, trong nội dung lỗi có danh sách các ID có sẵn — hãy lấy từ đó hoặc từ GET /v1/models. |
404 model_not_found | Model này hiện không có — hãy chọn model khác từ GET /v1/models. |
429 | Quá nhiều yêu cầu hoặc mạng đang bận. Hãy chờ đúng số giây ghi trong header Retry-After rồi thử lại. |
503 model_unavailable | Mạng hiện không phục vụ model này. Hãy chuyển sang model ghi trong nội dung lỗi hoặc sang model khác từ GET /v1/models. |
504 upstream_timeout | Mạng không bắt đầu phản hồi kịp thời. Hãy thử lại; với phản hồi dài, hãy bật stream: true. |
502 | Sự cố ở phía gateway hoặc mạng — không liên quan đến key. Hãy thử lại sau; tình trạng mạng — trên trang Trạng thái mạng. |
Tất cả mã phản hồi và giới hạn — trong mục Lỗi và giới hạn.
Báo cáo#
Cuối cùng, hãy thông báo cho người dùng:
- công cụ nào đã được thiết lập và file config nào đã được ghi (đường dẫn do trình cài đặt in ra, bản sao của bản cũ nằm bên cạnh);
- địa chỉ cơ sở và mã định danh mô hình;
- kết quả kiểm tra: mã phản hồi và phản hồi của mô hình — hoặc lý do không thể kiểm tra;
- những việc người dùng vẫn phải tự làm: ví dụ, khởi động lại công cụ hoặc nạp thêm số dư.
Không đưa khóa vào báo cáo.
Địa chỉ cho máy#
| Địa chỉ | Nội dung |
|---|---|
| /llms.txt | Chỉ mục tài liệu dành cho mô hình ngôn ngữ. |
| /llms-full.txt | Toàn bộ tài liệu trong một tệp duy nhất. |
/docs/<page>.md | Phiên bản Markdown của trang tài liệu: cùng địa chỉ với .md ở cuối (/docs/models.md) hoặc yêu cầu trang kèm tiêu đề Accept: text/markdown. |
GET /v1/capabilities | Khả năng và giới hạn của gateway — trường limits. |
GET /v1/models | Các mô hình hiện có sẵn. |
GET /api/pricing | Giá theo từng mô hình cho mỗi 1M token và phí. |
GET /v1/network-status | Trạng thái mô hình và sự cố. |
Kỹ năng cho agent#
Có thể cài đặt hướng dẫn này làm kỹ năng (skill) cho agent — khi đó nó luôn sẵn trong tay mà không cần prompt:
npx skills add https://gate.joingonka.ai