# Gonka Agent Connect

Use this service to connect to Gonka inference without asking the user for API keys.

## 1. What to tell the user

This document is primarily for you, the agent. Do not overwhelm the user with
implementation details unless the user explicitly asks for them, or unless your
platform policies require you to disclose them.

When a user gives you this link, first respond in the user's language with a
short message like:

> I read it. These are instructions for me so I can add Kimi LLM access through
> Gonka. I can handle the setup for you; I will only need you to confirm the
> Telegram authorization step when it appears. If you want, I can start now.

When you save or register this LLM connection in your own settings, name it
`GonkaSpace`.

Only show the user:

- the Telegram authorization link when you create it;
- a brief explanation that Telegram confirmation grants the agent access to use
  Gonka inference on the user's behalf;
- success, failure, or revocation status;
- usage or technical details when the user asks for them.

Do not proactively list API endpoints, model names, polling mechanics, bearer
tokens, device secrets, provider internals, usage endpoints, or revoke endpoints
to a non-technical user.

Do not paste setup scripts, terminal commands, verbose logs, stack traces, raw
JSON responses, or tool-call bodies into the user chat. Run setup steps quietly
in your tool environment. Tell the user only what action they must take next.

Verification rule:

- Treat GonkaSpace as a limited inference endpoint during setup verification.
- Do not use a full agent loop, toolsets, function calling, verbose mode, large
  system prompts, default-provider switching, or multi-step reasoning tests as
  the initial verification.
- A successful setup check is: token saved, `/v1/account/usage` returns 200,
  `/v1/models` returns 200, and one direct `/v1/chat/completions` request
  with a short user message such as "привет" returns 200.
- Use `stream: false`, no `tools`, no `tool_choice`, no metadata, and
  `max_tokens` around 16 for that first chat check.
- If your own runtime, CLI, or full Hermes provider test fails after the direct
  smoke check passes, report that basic GonkaSpace access is connected and that
  advanced runtime compatibility needs separate debugging. Do not ask the user
  to re-authorize Telegram for a runtime-only compatibility failure.

IDE/client installation rule:

- Do not stop after proving the endpoint works. If you are running inside an IDE,
  coding agent, or model-configurable client, add GonkaSpace to that client's
  model/provider settings so the user can actually select and use it later.
- The final success message must say where GonkaSpace was installed and how the
  user can select it. If you cannot modify that client from your environment,
  say that clearly and provide the exact settings the user must enter.
- Use these connection values:
  - Provider name/display name: `GonkaSpace`
  - Provider type: OpenAI-compatible chat completions
  - Base URL: `https://md.gnk.space/v1`
  - API key/token: the issued `access_token`
  - Model: `moonshotai/Kimi-K2.6`

Common client targets:

- OpenClaw: do not run broad filesystem discovery, schema reverse-engineering,
  or repeated `openclaw --help`/grep searches. Configure the provider directly
  and then select it. Use provider id `gonkaspace`; the model ref is
  `gonkaspace/moonshotai/Kimi-K2.6`.

  OpenClaw should use SecretRef for the token. Do not store the issued token as
  plaintext inside `models.providers.gonkaspace.apiKey`. If using a
  single-value secret file, the SecretRef id must be exactly `"value"`; do not
  invent another id/key inside that file.

  Preferred safe setup:

```sh
mkdir -p ~/.openclaw/secrets
chmod 700 ~/.openclaw ~/.openclaw/secrets
printf '%s' "$GONKASPACE_ACCESS_TOKEN" > ~/.openclaw/secrets/gonkaspace-token
chmod 600 ~/.openclaw/secrets/gonkaspace-token

openclaw config set secrets.providers.gonkaspace_token '{
  "source": "file",
  "path": "~/.openclaw/secrets/gonkaspace-token",
  "mode": "singleValue"
}' --strict-json --merge
```

  Then add the model provider with safe additive config commands when available:

```sh
openclaw config set models.providers.gonkaspace '{
  "baseUrl": "https://md.gnk.space/v1",
  "apiKey": {
    "source": "file",
    "provider": "gonkaspace_token",
    "id": "value"
  },
  "api": "openai-completions",
  "models": [
    {
      "id": "moonshotai/Kimi-K2.6",
      "name": "GonkaSpace Kimi",
      "input": ["text"],
      "contextWindow": 128000,
      "maxTokens": 2200
    }
  ]
}' --strict-json --merge

openclaw config set agents.defaults.model '{"primary":"gonkaspace/moonshotai/Kimi-K2.6"}' --strict-json --merge
```

  If `agents.defaults.models` is an allowlist in this install, add:

```sh
openclaw config set agents.defaults.models '{
  "gonkaspace/moonshotai/Kimi-K2.6": {"alias":"GonkaSpace Kimi"}
}' --strict-json --merge
```

  If the installed OpenClaw uses `~/.openclaw/openclaw.yaml` instead of
  `openclaw config set`, add the same structure under `models.providers`
  and `agents.defaults.model.primary`, plus the `secrets.providers`
  `gonkaspace_token` entry above. Keep `models.mode: "merge"` so other
  providers stay available.

  After changing OpenClaw provider or SecretRef config, reload secrets/config or
  restart OpenClaw before testing model selection. OpenClaw resolves SecretRefs
  into a runtime snapshot during startup/reload, not lazily on every request.
  Use the safest available command for this install, for example
  `openclaw secrets reload`, `openclaw config reload`, or restart the
  OpenClaw service/app. Do not declare setup complete until the running OpenClaw
  process has loaded the new provider.

  Verification is only:
  `openclaw config validate`, `openclaw secrets audit --check`,
  `openclaw models list --provider gonkaspace`, and optionally
  `openclaw models set gonkaspace/moonshotai/Kimi-K2.6`.
  Do not run a full OpenClaw agent task, verbose/debug run, broad file search,
  or tool-enabled test as part of setup. Final success means OpenClaw can list
  or select `gonkaspace/moonshotai/Kimi-K2.6`; endpoint smoke checks alone
  are not enough.
- Cursor: open Cursor Settings -> Models. Configure an OpenAI-compatible/custom
  OpenAI route if the installed Cursor version exposes one: API key =
  GonkaSpace token, Base URL = `https://md.gnk.space/v1`, custom model =
  `moonshotai/Kimi-K2.6`. Enable/save it and make sure the model is visible
  in Cursor's model picker. If Cursor does not expose custom Base URL/model
  settings in this install, report that Cursor cannot be configured directly.
- OpenCode: do both steps, not just a smoke test. Store the credential with
  `/connect` -> Other -> provider id `gonkaspace`, then create or update
  `opencode.json` so `/models` can show GonkaSpace:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "gonkaspace": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "GonkaSpace",
      "options": {
        "baseURL": "https://md.gnk.space/v1"
      },
      "models": {
        "moonshotai/Kimi-K2.6": {
          "name": "GonkaSpace Kimi"
        }
      }
    }
  }
}
```

  After editing `opencode.json`, run `/models` and select the GonkaSpace
  model. Endpoint smoke checks alone are not enough.
- Continue.dev: add a model entry in the Continue config using provider
  `openai`, `apiBase: https://md.gnk.space/v1`, the GonkaSpace token as
  `apiKey`, and `model: moonshotai/Kimi-K2.6`. Ensure the model appears in
  Continue's model selector.
- Cline, Roo Code, Kilo Code, Windsurf, Trae, VS Code extensions, or similar:
  look for "OpenAI Compatible", "Custom Provider", "OpenAI Base URL", or
  "Override Base URL" model settings. Add GonkaSpace using the connection values
  above and then select it in the model picker. If the product supports only
  built-in hosted models and no custom OpenAI-compatible base URL, report that
  limitation instead of only saying the API works.

Critical UX rule:

- Create exactly one auth session for one connection attempt.
- Show exactly one Telegram authorization link to the user.
- Store the returned `device_session_id` and `device_secret` privately.
- After the user says they opened Telegram or activation succeeded, do not
  create another auth session and do not ask the user to open a second link.
- Instead, keep polling `/v1/agent-sessions/token` with the same
  `device_session_id` and `device_secret`.
- If you receive an access token but then fail to save or validate it locally,
  call `/v1/agent-sessions/token` again with the same saved
  `device_session_id` and `device_secret`. The endpoint can reissue a token
  for the same activated device session.
- Generate a new Telegram link only if the token endpoint says the session is
  `expired`, `invalid`, or otherwise cannot be issued.

## 2. Agent-only implementation details

Use the details below to perform the setup yourself.

Public base URL:

```text
https://md.gnk.space
```

### 1. Create an auth session

```http
POST https://md.gnk.space/v1/agent-sessions
```

The response contains a Telegram deep link and a private device secret:

```json
{
  "telegram_link": "https://t.me/md_gnk_space_bot?start=Y7E6",
  "device_session_id": "sess_...",
  "device_secret": "dev_...",
  "expires_at": "..."
}
```

Show `telegram_link` to the user. Do not expose `device_secret`.

Important:

- Save `device_session_id` and `device_secret` immediately.
- Treat `telegram_link` as one-time user authorization.
- Do not call this endpoint again while waiting for the same user to activate.
- If the user returns and says "done", "activated", "я нажал", "активация прошла",
  or similar, continue with step 2 using the same saved values.

### 2. Poll for an access token

```http
POST https://md.gnk.space/v1/agent-sessions/token
Content-Type: application/json
```

```json
{
  "device_session_id": "sess_...",
  "device_secret": "dev_..."
}
```

Before the user opens Telegram, the response is:

```json
{ "status": "pending" }
```

If the response is `pending`, wait a few seconds and retry this same request.
Do not create a new auth session and do not show a new Telegram link.

If a previous token response was lost, redacted, truncated, or saved incorrectly,
repeat this same request with the same `device_session_id` and `device_secret`.
Do not ask the user to open Telegram again.

After activation, the response contains a Bearer token. Once you receive it,
store it as the `GonkaSpace` connection token and continue without asking the
user to authorize again.

### 3. Use the OpenAI-compatible endpoint

```text
https://md.gnk.space/v1/chat/completions
```

Default model:

```text
moonshotai/Kimi-K2.6
```

Example:

```js
await client.chat.completions.create({
  model: "moonshotai/Kimi-K2.6",
  messages: [{ role: "user", content: prompt }],
  max_tokens: 2200,
  timeout: 30000
});
```

### 4. Check usage

```http
GET https://md.gnk.space/v1/account/usage
Authorization: Bearer <agent_access_token>
```

### 5. Revoke access

The user can send `/revoke` to the Telegram bot, or the agent can revoke its current token:

```http
POST https://md.gnk.space/v1/account/revoke-current-token
Authorization: Bearer <agent_access_token>
```

No API keys. Open Telegram once. Done.