AI 에이전트용: 단계별 설정 안내 — /docs/agents.md, 문서 인덱스 — /llms.txt.
AI 에이전트용
AI 에이전트에게 연동을 맡기는 방법: 어떤 도구든 사용할 수 있는 완성된 프롬프트. 아래에서는 문서의 기계 판독 가능 주소와 에이전트가 명령 하나로 설치하는 스킬을 소개합니다.
에이전트용 프롬프트#
이 프롬프트를 AI 에이전트에게 보내세요. 에이전트는 아래 안내서에 따라 도구를 설정하고, 키는 사용자에게 요청합니다.
에이전트용 프롬프트
나만의 도구을(를) JoinGonka Gateway — Gonka 네트워크의 OpenAI 및 Anthropic 호환 API — 에 https://gate.joingonka.ai/docs/agents.md 안내에 따라 연결해 주세요. 키는 제가 직접 제공하겠습니다. 저장소 파일에 저장하거나 전역 환경 변수를 변경하지 마세요. 마지막에 짧은 요청으로 연결을 확인하고 결과를 알려주세요.아래가 안내서입니다. 에이전트는 /docs/agents.md에서 Markdown 형식으로 받습니다.
규칙#
- API 키는 사람이 만듭니다 — gate.joingonka.ai의 대시보드에서. 직접 계정을 등록하거나 키를 만들지 마세요: 사용자에게 키를 요청하세요.
- 키는 터미널 세션의 환경 변수
JOINGONKA_API_KEY에 보관하세요. git 관리 대상 파일에 쓰거나 커밋하거나 보고서에 출력하지 마세요. - 전역 변수
OPENAI_*와ANTHROPIC_*을 변경하지 마세요 — 셸 프로필에서도, 시스템에서도: 사용자의 다른 도구가 이들을 참조합니다. 키와 주소는 도구 자체의 설정 파일에 기록됩니다 — 설치 프로그램이 그렇게 합니다.
사실#
- OpenAI API 클라이언트용 기본 URL:
https://gate.joingonka.ai/v1 - Anthropic API 클라이언트용 기본 URL,
/v1없이:https://gate.joingonka.ai - 키는
Authorization: Bearer jg-…또는x-api-key: jg-…헤더로 전달됩니다 - 모델 호출용 키는
jg-로 시작합니다; 관리 키gm-로는 모델에 접근할 수 없습니다. - 권장 모델:
MiniMaxAI/MiniMax-M2.7 - 사용 가능한 모델 목록:
GET https://gate.joingonka.ai/v1/models - 키당 분당 최대 120 요청, 초과 시
Retry-After헤더가 포함된 429 응답. 요청 제한과 타임아웃은GET /v1/capabilities응답의limits필드에 있습니다.
설정#
섹션 끝의 표에서 사용자의 도구를 찾으세요. --tool 값이 있으면 설치 프로그램으로 설정하고, 없으면 가이드에 따라 수동으로 설정하세요.
설치 프로그램 사용#
질문 없는 단일 명령: 키는 환경 변수에서, 모델은 플래그로 지정. 설치 프로그램이 도구 설정을 기록하고 이전 복사본을 저장하며 게이트웨이 요청으로 연결을 확인합니다.
Bash
JOINGONKA_API_KEY=<key> npx -y @joingonka/setup --tool <id> --model MiniMaxAI/MiniMax-M2.7 --non-interactive| 플래그 | 동작 |
|---|---|
--tool <id> | 설정할 도구 — 도구 표의 값. |
--model <id> | 모델 ID: 권장은 MiniMaxAI/MiniMax-M2.7, 사용 가능한 전체는 GET /v1/models. |
--non-interactive | 질문 없음: 키는 JOINGONKA_API_KEY에서 가져옴. |
--scope local | 설정을 홈 디렉터리가 아닌 현재 프로젝트에 저장. Claude Code 전용; 설정 파일이 .gitignore에 추가됩니다. |
--no-verify | 설정 기록 후 연결 확인 생략. |
| 종료 코드 | 의미 |
|---|---|
0 | 완료: 설정이 기록되고 확인 요청이 성공. 네트워크나 잔액 문제로 확인하지 못한 경우 설치 프로그램은 경고를 출력하지만 종료 코드 0으로 끝납니다 — 사용자에게 알려주세요. |
1 | 설정 실패, 원인은 출력에서 확인: 예를 들어 알 수 없는 --tool 값, JOINGONKA_API_KEY 미설정, 키가 jg-로 시작하지 않음 등. |
2 | 설정은 기록되었지만 확인 요청이 실패: 키와 모델 ID를 확인하세요. |
도구가 실행 중이었다면 재시작하세요: 설정은 시작 시 읽힙니다.
수동으로#
설치 프로그램이 없는 도구의 경우 해당 가이드(아래 표의 링크)를 열고 세 가지 값을 설정하세요:
- 베이스 URL — OpenAI API 클라이언트는
https://gate.joingonka.ai/v1, Anthropic API 클라이언트는https://gate.joingonka.ai; - 키 — 도구 설정의 API 키 필드에;
- 모델 —
MiniMaxAI/MiniMax-M2.7또는GET /v1/models의 다른 모델.
도구와 가이드#
| 도구 | --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 |
확인#
키 확인 — 잔액 요청: 토큰을 소모하지 않으며 키는 JOINGONKA_API_KEY에서 가져옴:
cURL
curl -s https://gate.joingonka.ai/api/balance \
-H "Authorization: Bearer $JOINGONKA_API_KEY"주소, 키, 모델 확인 — 모델에 대한 짧은 요청:
cURL
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}'모델 텍스트가 포함된 200 응답이 오면 연결이 정상입니다. 설치 프로그램이 이 확인을 자동으로 수행하므로 종료 코드 0이면 충분합니다.
문제가 생겼을 때#
오류는 응답 본문의 error 필드에 원인 유형과 텍스트와 함께 반환됩니다.
| 응답 | 대응 |
|---|---|
401 authentication_error | 키가 거부되었습니다. 전체가 복사되었는지, Authorization: Bearer 또는 x-api-key로 전달되었는지 확인하세요. 새 키는 사용자가 만듭니다. |
402 insufficient_funds | 잔액이 부족합니다. 사용자에게 알리세요: 잔액은 대시보드에서 충전합니다. |
402 child_key_limit_exceeded | 하위 키 한도가 소진되었습니다. 다른 키나 더 큰 한도가 필요합니다 — 키 소유자가 처리합니다. |
403 forbidden | 이것은 관리 키 gm-입니다: 모델에 접근할 수 없습니다. jg- 키가 필요합니다. |
400 invalid_request_error | 요청 오류. 모델을 찾을 수 없는 경우 오류 텍스트에 사용 가능한 ID 목록이 있습니다 — 거기나 GET /v1/models에서 가져오세요. |
404 model_not_found | 해당 모델은 현재 없습니다 — GET /v1/models에서 다른 것을 고르세요. |
429 | 요청이 너무 많거나 네트워크가 혼잡합니다. Retry-After 헤더에 표시된 초만큼 기다린 후 다시 시도하세요. |
503 model_unavailable | 네트워크가 현재 해당 모델을 제공하지 않습니다. 오류 텍스트의 모델이나 GET /v1/models의 다른 모델로 전환하세요. |
504 upstream_timeout | 네트워크가 제때 응답을 시작하지 않았습니다. 요청을 다시 시도하세요. 긴 응답에는 stream: true을 활성화하세요. |
502 | 게이트웨이 또는 네트워크 측 장애 — 키 문제가 아닙니다. 나중에 다시 시도하세요. 네트워크 상태는 네트워크 상태 페이지에서 확인할 수 있습니다. |
모든 응답 코드와 제한은 오류 및 한도 섹션에 있습니다.
보고서#
마지막으로 사용자에게 알리세요:
- 어떤 도구가 설정되었고 어떤 설정 파일이 기록되었는지(경로는 설치 프로그램이 출력하고, 이전 복사본은 그 옆에 있습니다);
- 기본 주소와 모델 식별자;
- 검사 결과: 응답 코드와 모델의 응답 — 또는 검사를 수행하지 못한 이유;
- 사용자가 직접 해야 할 남은 작업: 예를 들어 도구 재시작이나 잔액 충전.
보고서에 키를 포함하지 마세요.
머신용 주소#
| 주소 | 내용 |
|---|---|
| /llms.txt | 언어 모델용 문서 인덱스. |
| /llms-full.txt | 전체 문서를 하나의 파일로. |
/docs/<page>.md | 문서 페이지의 Markdown 버전: 같은 주소 끝에 .md를 붙이거나(/docs/models.md) Accept: text/markdown 헤더와 함께 페이지를 요청하세요. |
GET /v1/capabilities | 게이트웨이의 기능과 한도 — limits 필드. |
GET /v1/models | 현재 사용 가능한 모델. |
GET /api/pricing | 모델별 1M 토큰당 가격과 수수료. |
GET /v1/network-status | 모델 상태와 인시던트. |
에이전트용 스킬#
이 안내를 에이전트의 스킬(skill)로 설치할 수 있습니다. 그러면 프롬프트 없이도 항상 곁에 두고 쓸 수 있습니다:
Bash
npx skills add https://gate.joingonka.ai