> AI エージェント向け：セットアップの手順ガイド — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md)、ドキュメントのインデックス — [`/llms.txt`](https://gate.joingonka.ai/llms.txt)。

# AIエージェント向け

AI エージェントに接続作業を任せる方法：あらゆるツールで使えるプロンプトを用意。以下ではドキュメントの機械可読アドレスと、エージェントがコマンド1つで導入できるスキルを紹介します。

## エージェント用プロンプト

このプロンプトを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`
- 1キーあたり毎分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を確認してください。 |

ツールが起動中だった場合は再起動してください。設定は起動時に読み込まれます。

### 手動で

インストーラーのないツールの場合は、そのガイド（下の表のリンク）を開き、3つの値を設定してください：

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

すべてのレスポンスコードと制限は[エラーと制限](https://gate.joingonka.ai/ja/docs/errors)セクションにあります。

## レポート

最後にユーザーに以下を伝えてください：

- どのツールが設定され、どの設定ファイルが書き込まれたか（パスはインストーラーが出力し、以前のコピーはその隣にあります）；
- ベースアドレスとモデルID。
- チェック結果：レスポンスコードとモデルの応答、またはチェックできなかった理由。
- ユーザー自身がまだ行う必要があること：たとえば、ツールの再起動や残高のチャージ。

レポートにキーを含めないでください。

## マシン向けアドレス

| アドレス | 内容 |
| --- | --- |
| [/llms.txt](https://gate.joingonka.ai/llms.txt) | 言語モデル向けドキュメントインデックス。 |
| [/llms-full.txt](https://gate.joingonka.ai/llms-full.txt) | 全ドキュメントを1ファイルにまとめたもの。 |
| `/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` | モデルごとの100万トークンあたりの料金と手数料。 |
| `GET /v1/network-status` | モデルのステータスとインシデント。 |

## エージェント用スキル

この手順はエージェントのスキル（skill）としてインストールできます。そうすればプロンプトなしでいつでも使えます：

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