> 面向 AI 智能体：配置分步指南 — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md)，文档索引 — [`/llms.txt`](https://gate.joingonka.ai/llms.txt)。

# 面向 AI 智能体

如何将接入工作交给 AI 智能体：适用于任何工具的现成提示词。下文提供文档的机器可读地址以及智能体用一条命令安装的技能。

## 智能体提示词

把这段提示词发送给你的 AI 智能体。它会按照下方的说明配置工具，并向你索要密钥。

```text
请按照 https://gate.joingonka.ai/docs/agents.md 的说明，将 你的工具 接入 JoinGonka Gateway——Gonka 网络兼容 OpenAI 和 Anthropic 的 API。密钥我会自己提供：不要将其保存到仓库文件中，也不要修改全局环境变量。最后用一条简短请求验证连接，并告知结果。
```

以下是说明本身。智能体可通过 [/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_*`——无论是 shell 配置文件还是系统层面：用户的其他工具会读取它们。密钥和地址写入工具自身的配置——安装程序就是这么做的。

## 关键信息

- OpenAI API 客户端的基地址：`https://gate.joingonka.ai/v1`
- Anthropic API 客户端的基地址，不含 `/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 个请求，超出限制会返回 429，并带有 `Retry-After` 响应头。速率限制和超时信息见 `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>` | 模型标识符：推荐 `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` | 配置已写入，但验证请求未通过：请检查密钥和模型标识符。 |

如果工具之前已在运行，请重启它：配置在启动时读取。

### 手动配置

对于没有安装程序的工具，打开其指南（链接见下方表格）并设置三个值：

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

## 验证

验证密钥——发送余额请求：它不消耗 token，密钥取自 `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` | 请求有误。如果未找到模型，错误文本中会列出可用的标识符——可从中或 `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/zh/status) 页面。 |

所有响应码和限制见 [错误与速率限制](https://gate.joingonka.ai/zh/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 token 的价格与手续费。 |
| `GET /v1/network-status` | 模型状态与故障事件。 |

## 智能体技能

可以将该说明安装为智能体的技能（skill）——这样它随时可用，无需提示词：

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