> AI 에이전트용: 단계별 설정 안내 — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), 문서 인덱스 — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# AI 에이전트용

AI 에이전트에게 연동을 맡기는 방법: 어떤 도구든 사용할 수 있는 완성된 프롬프트. 아래에서는 문서의 기계 판독 가능 주소와 에이전트가 명령 하나로 설치하는 스킬을 소개합니다.

## 에이전트용 프롬프트

이 프롬프트를 AI 에이전트에게 보내세요. 에이전트는 아래 안내서에 따라 도구를 설정하고, 키는 사용자에게 요청합니다.

```text
나만의 도구을(를) JoinGonka Gateway — Gonka 네트워크의 OpenAI 및 Anthropic 호환 API — 에 https://gate.joingonka.ai/docs/agents.md 안내에 따라 연결해 주세요. 키는 제가 직접 제공하겠습니다. 저장소 파일에 저장하거나 전역 환경 변수를 변경하지 마세요. 마지막에 짧은 요청으로 연결을 확인하고 결과를 알려주세요.
```

아래가 안내서입니다. 에이전트는 [/docs/agents.md](https://gate.joingonka.ai/docs/agents.md)에서 Markdown 형식으로 받습니다.

## 규칙

- API 키는 사람이 만듭니다 — [gate.joingonka.ai](https://gate.joingonka.ai/keys)의 대시보드에서. 직접 계정을 등록하거나 키를 만들지 마세요: 사용자에게 키를 요청하세요.
- 키는 터미널 세션의 환경 변수 `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](https://joingonka.ai/ko/knowledge/cursor/) | `cursor` |
| [Claude Code](https://joingonka.ai/ko/knowledge/claude-code/) | `claude-code` |
| [OpenClaw](https://joingonka.ai/ko/knowledge/openclaw/) | `openclaw` |
| [OpenCode](https://joingonka.ai/ko/knowledge/opencode/) | `opencode` |
| [Continue](https://joingonka.ai/ko/knowledge/continue-dev/) | `continue` |
| [Cline](https://joingonka.ai/ko/knowledge/cline/) | `cline` |
| [Aider](https://joingonka.ai/ko/knowledge/aider/) | `aider` |
| [LangChain](https://joingonka.ai/ko/knowledge/langchain/) | — |
| [n8n](https://joingonka.ai/ko/knowledge/n8n/) | — |
| [Open WebUI](https://joingonka.ai/ko/knowledge/open-webui/) | — |
| [LibreChat](https://joingonka.ai/ko/knowledge/librechat/) | — |
| [Hermes](https://joingonka.ai/ko/knowledge/hermes/) | `hermes` |
| [Kilo Code](https://joingonka.ai/ko/knowledge/kilo-code/) | `kilo` |
| [Roo Code](https://joingonka.ai/ko/knowledge/roo-code/) | `roo` |
| [LlamaIndex](https://joingonka.ai/ko/knowledge/llamaindex/) | — |
| [PydanticAI](https://joingonka.ai/ko/knowledge/pydantic-ai/) | — |
| [Vercel AI SDK](https://joingonka.ai/ko/knowledge/vercel-ai-sdk/) | — |
| [TanStack AI](https://joingonka.ai/ko/knowledge/tanstack-ai/) | — |
| [ZCode](https://joingonka.ai/ko/knowledge/zcode/) | `zcode` |
| [JetBrains](https://joingonka.ai/ko/knowledge/jetbrains/) | `jetbrains` |
| [Copilot BYOK](https://joingonka.ai/ko/knowledge/copilot-byok/) | `copilot-byok` |
| [Zed](https://joingonka.ai/ko/knowledge/zed/) | `zed` |
| [Pi](https://joingonka.ai/ko/knowledge/pi/) | `pi` |
| [Codex CLI](https://joingonka.ai/ko/knowledge/codex/) | `codex` |
| [DeepSeek Harness](https://joingonka.ai/ko/knowledge/deepseek-harness/) | — |
| [MiniMax Code](https://joingonka.ai/ko/knowledge/minimax-code/) | `minimax-code` |
| [Warp](https://joingonka.ai/ko/knowledge/warp/) | — |
| [Trae](https://joingonka.ai/ko/knowledge/trae/) | — |
| [Cherry Studio](https://joingonka.ai/ko/knowledge/cherry-studio/) | — |
| [omp (Oh My Pi)](https://joingonka.ai/ko/knowledge/omp/) | `omp` |
| [OpenHands](https://joingonka.ai/ko/knowledge/openhands/) | — |
| [Qwen Code](https://joingonka.ai/ko/knowledge/qwen-code/) | `qwen-code` |
| [Goose](https://joingonka.ai/ko/knowledge/goose/) | `goose` |
| [Crush](https://joingonka.ai/ko/knowledge/crush/) | `crush` |
| [Zoo Code](https://joingonka.ai/ko/knowledge/zoo-code/) | `zoo` |
| [Kimi Code](https://joingonka.ai/ko/knowledge/kimi-code/) | `kimi-code` |
| [Factory Droid](https://joingonka.ai/ko/knowledge/factory-droid/) | `droid` |
| [MiMo Code](https://joingonka.ai/ko/knowledge/mimo-code/) | `mimo-code` |

## 확인

키 확인 — 잔액 요청: 토큰을 소모하지 않으며 키는 `JOINGONKA_API_KEY`에서 가져옴:

```bash
curl -s https://gate.joingonka.ai/api/balance \
  -H "Authorization: Bearer $JOINGONKA_API_KEY"
```

주소, 키, 모델 확인 — 모델에 대한 짧은 요청:

```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}'
```

모델 텍스트가 포함된 `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` | 게이트웨이 또는 네트워크 측 장애 — 키 문제가 아닙니다. 나중에 다시 시도하세요. 네트워크 상태는 [네트워크 상태](https://gate.joingonka.ai/ko/status) 페이지에서 확인할 수 있습니다. |

모든 응답 코드와 제한은 [오류 및 한도](https://gate.joingonka.ai/ko/docs/errors) 섹션에 있습니다.

## 보고서

마지막으로 사용자에게 알리세요:

- 어떤 도구가 설정되었고 어떤 설정 파일이 기록되었는지(경로는 설치 프로그램이 출력하고, 이전 복사본은 그 옆에 있습니다);
- 기본 주소와 모델 식별자;
- 검사 결과: 응답 코드와 모델의 응답 — 또는 검사를 수행하지 못한 이유;
- 사용자가 직접 해야 할 남은 작업: 예를 들어 도구 재시작이나 잔액 충전.

보고서에 키를 포함하지 마세요.

## 머신용 주소

| 주소 | 내용 |
| --- | --- |
| [/llms.txt](https://gate.joingonka.ai/llms.txt) | 언어 모델용 문서 인덱스. |
| [/llms-full.txt](https://gate.joingonka.ai/llms-full.txt) | 전체 문서를 하나의 파일로. |
| `/docs/<page>.md` | 문서 페이지의 Markdown 버전: 같은 주소 끝에 `.md`를 붙이거나([/docs/models.md](https://gate.joingonka.ai/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
```