面向 AI 智能体：配置分步指南 — /docs/agents.md，文档索引 — /llms.txt。
面向 AI 智能体
如何将接入工作交给 AI 智能体：适用于任何工具的现成提示词。下文提供文档的机器可读地址以及智能体用一条命令安装的技能。
智能体提示词#
把这段提示词发送给你的 AI 智能体。它会按照下方的说明配置工具，并向你索要密钥。
智能体提示词
请按照 https://gate.joingonka.ai/docs/agents.md 的说明，将 你的工具 接入 JoinGonka Gateway——Gonka 网络兼容 OpenAI 和 Anthropic 的 API。密钥我会自己提供：不要将其保存到仓库文件中，也不要修改全局环境变量。最后用一条简短请求验证连接，并告知结果。以下是说明本身。智能体可通过 /docs/agents.md 以 Markdown 形式获取。
规则#
- API 密钥由人工创建——在 gate.joingonka.ai 的个人控制台中完成。不要自行注册账号或创建密钥：向用户索要密钥。
- 将密钥保存在终端会话的环境变量
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 | 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 |
验证#
验证密钥——发送余额请求：它不消耗 token，密钥取自 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 | 请求有误。如果未找到模型，错误文本中会列出可用的标识符——可从中或 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 token 的价格与手续费。 |
GET /v1/network-status | 模型状态与故障事件。 |
智能体技能#
可以将该说明安装为智能体的技能（skill）——这样它随时可用，无需提示词：
Bash
npx skills add https://gate.joingonka.ai