> Dành cho AI agent: hướng dẫn từng bước để thiết lập — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), chỉ mục tài liệu — [`/llms.txt`](https://gate.joingonka.ai/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.

```text
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](https://gate.joingonka.ai/docs/agents.md).

## Quy tắc

- API key do con người tạo — trong trang cá nhân tại [gate.joingonka.ai](https://gate.joingonka.ai/keys). Đừ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_KEY` củ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ặc `x-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ồi `GET /v1/capabilities`, trường `limits`.

## 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.

```bash
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/v1` cho client OpenAI API hoặc `https://gate.joingonka.ai` cho client Anthropic API;
- key — trong trường API key trong cài đặt của công cụ;
- model — `MiniMaxAI/MiniMax-M2.7` hoặc một model khác từ `GET /v1/models`.

### Công cụ và hướng dẫn

| Công cụ | `--tool` |
| --- | --- |
| [Cursor](https://joingonka.ai/vi/knowledge/cursor/) | `cursor` |
| [Claude Code](https://joingonka.ai/vi/knowledge/claude-code/) | `claude-code` |
| [OpenClaw](https://joingonka.ai/vi/knowledge/openclaw/) | `openclaw` |
| [OpenCode](https://joingonka.ai/vi/knowledge/opencode/) | `opencode` |
| [Continue](https://joingonka.ai/vi/knowledge/continue-dev/) | `continue` |
| [Cline](https://joingonka.ai/vi/knowledge/cline/) | `cline` |
| [Aider](https://joingonka.ai/vi/knowledge/aider/) | `aider` |
| [LangChain](https://joingonka.ai/vi/knowledge/langchain/) | — |
| [n8n](https://joingonka.ai/vi/knowledge/n8n/) | — |
| [Open WebUI](https://joingonka.ai/vi/knowledge/open-webui/) | — |
| [LibreChat](https://joingonka.ai/vi/knowledge/librechat/) | — |
| [Hermes](https://joingonka.ai/vi/knowledge/hermes/) | `hermes` |
| [Kilo Code](https://joingonka.ai/vi/knowledge/kilo-code/) | `kilo` |
| [Roo Code](https://joingonka.ai/vi/knowledge/roo-code/) | `roo` |
| [LlamaIndex](https://joingonka.ai/vi/knowledge/llamaindex/) | — |
| [PydanticAI](https://joingonka.ai/vi/knowledge/pydantic-ai/) | — |
| [Vercel AI SDK](https://joingonka.ai/vi/knowledge/vercel-ai-sdk/) | — |
| [TanStack AI](https://joingonka.ai/vi/knowledge/tanstack-ai/) | — |
| [ZCode](https://joingonka.ai/vi/knowledge/zcode/) | `zcode` |
| [JetBrains](https://joingonka.ai/vi/knowledge/jetbrains/) | `jetbrains` |
| [Copilot BYOK](https://joingonka.ai/vi/knowledge/copilot-byok/) | `copilot-byok` |
| [Zed](https://joingonka.ai/vi/knowledge/zed/) | `zed` |
| [Pi](https://joingonka.ai/vi/knowledge/pi/) | `pi` |
| [Codex CLI](https://joingonka.ai/vi/knowledge/codex/) | `codex` |
| [DeepSeek Harness](https://joingonka.ai/vi/knowledge/deepseek-harness/) | — |
| [MiniMax Code](https://joingonka.ai/vi/knowledge/minimax-code/) | `minimax-code` |
| [Warp](https://joingonka.ai/vi/knowledge/warp/) | — |
| [Trae](https://joingonka.ai/vi/knowledge/trae/) | — |
| [Cherry Studio](https://joingonka.ai/vi/knowledge/cherry-studio/) | — |
| [omp (Oh My Pi)](https://joingonka.ai/vi/knowledge/omp/) | `omp` |
| [OpenHands](https://joingonka.ai/vi/knowledge/openhands/) | — |
| [Qwen Code](https://joingonka.ai/vi/knowledge/qwen-code/) | `qwen-code` |
| [Goose](https://joingonka.ai/vi/knowledge/goose/) | `goose` |
| [Crush](https://joingonka.ai/vi/knowledge/crush/) | `crush` |
| [Zoo Code](https://joingonka.ai/vi/knowledge/zoo-code/) | `zoo` |
| [Kimi Code](https://joingonka.ai/vi/knowledge/kimi-code/) | `kimi-code` |
| [Factory Droid](https://joingonka.ai/vi/knowledge/factory-droid/) | `droid` |
| [MiMo Code](https://joingonka.ai/vi/knowledge/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`:

```bash
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:

```bash
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](https://gate.joingonka.ai/vi/status). |

Tất cả mã phản hồi và giới hạn — trong mục [Lỗi và giới hạn](https://gate.joingonka.ai/vi/docs/errors).

## 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](https://gate.joingonka.ai/llms.txt) | Chỉ mục tài liệu dành cho mô hình ngôn ngữ. |
| [/llms-full.txt](https://gate.joingonka.ai/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](https://gate.joingonka.ai/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:

```bash
npx skills add https://gate.joingonka.ai
```