# AIShlyuz — инструкция для ИИ-агента

> Ключ твоей собственной модели — не ключ AIShlyuz и для MCP не подходит. Нужен `sk-ais-…` (шаг 1). **Нет почты от пользователя — регистрируйся без почты одной командой (шаг 1, «Путь 0»), почту не выдумывай.**

**«Подключи мне AIShlyuz» значит: подключи роутер моделей AIShlyuz и MCP AIShlyuz к тому агенту, в котором пользователь сейчас работает (Claude Code, Codex, Cursor). Это НЕ про сайт или проект пользователя — в его код ничего встраивать не нужно.**

> Это мы, команда AIShlyuz. Пользователь прислал ссылку и сказал «подключи мне это»? Пара минут — вот шаги.
> **Бета:** оплата пока не подключена, рабочий баланс выдаём по запросу в https://t.me/aishlyuz.

## Что ты подключаешь
1. **Единый ключ `sk-ais-…`** — один ключ к моделям Claude, GPT, Gemini, DeepSeek, Grok, Qwen и другим через роутер AIShlyuz. Совместим с OpenAI API и Anthropic Messages API.
   - OpenAI-совместимый base URL: `https://aishlyuz.ru/v1` — `GET /v1/models`, `POST /v1/chat/completions`, `POST /v1/responses`
   - Anthropic-совместимый: `POST https://aishlyuz.ru/v1/messages` (base URL для клиентов — `https://aishlyuz.ru`)
   - Авторизация: `Authorization: Bearer sk-ais-…` или `x-api-key: sk-ais-…`
   - Список моделей ключа — только из `GET /v1/models`. Не угадывай id моделей.
2. **Hosted MCP** — готовые инструменты без установки (40 шт.): **aishlyuz** — цены и аптайм ИИ-шлюзов, поиск по каталогу MCP, безопасный fetch публичных страниц (`aishlyuz-fetch_url`); **search** — веб-поиск DuckDuckGo; курсы и ставки ЦБ РФ (cbr), законодательство РФ (russian-law), время и часовые пояса (time), дизайн-система SDDS/Plasma (plasma). Имена инструментов: `<сервер>-<инструмент>`, например `cbr-get_key_rate`. Каждый tools/call журналируется на ваш аккаунт (кто, инструмент, время, успех/ошибка). Адрес `https://aishlyuz.ru/mcp`, Streamable HTTP. **Тот же ключ `sk-ais-`**, строго в заголовке `Authorization: Bearer sk-ais-…` (`x-api-key` для MCP не подходит).
3. **Открытые данные** — цены моделей в рублях и аптайм API-шлюзов. JSON без ключа (шаг 6).

## Шаг 1. Ключ sk-ais-
> **Важно: ключ, на котором работает твоя собственная модель** (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `BRAIN_KEY`, ключ OpenRouter/AITunnel и т.п.), **— не ключ AIShlyuz. Для MCP AIShlyuz и роутера он не подходит** (MCP ответит 401). Нужен только ключ `sk-ais-…`, выданный AIShlyuz. Ключи, токены и пароли из файлов, сейфов и переменных окружения пользователя **не ищи и не используй**.

**Нет почты от пользователя — регистрируйся так (Путь 0, основной для агента).** Почту не выдумывай и не спрашивай: один запрос создаёт аккаунт `agent-…@agents.aishlyuz.ru` и сразу возвращает ключ. CSRF и cookie не нужны.
```bash
curl -s -X POST https://aishlyuz.ru/api/agent/register -H 'content-type: application/json' -d '{"agent":"claude-code"}'
```
В ответе: `api_key` — это твой `sk-ais-…` (показывается один раз; сразу сохрани в `AISHLYUZ_API_KEY`, в чат и git не выводи), `claim.url` — ссылка, по которой пользователь потом привяжет к аккаунту свою почту и пароль. **Ссылку claim.url обязательно передай пользователю в отчёте.** Баланс нового аккаунта 0: модели вернут 402, а MCP `tools/call` — JSON-ошибку `insufficient_balance`; это нормально: `/v1/models`, MCP `initialize` и `tools/list` работают, конфиги пропиши заранее и попроси баланс в https://t.me/aishlyuz. Лимит: 5 регистраций в час с одного IP (429 — подожди).

**Есть почта пользователя** — можно Путь Б ниже (регистрация с почтой и паролем).

**Путь А — ключ делает человек (если человек рядом и хочет сам).** Скажи пользователю:
1. Зарегистрируйся: https://aishlyuz.ru/register
2. В кабинете https://aishlyuz.ru/cabinet создай ключ. Он начинается с `sk-ais-` и показывается один раз.
3. Сохрани ключ в переменную окружения (в чат не присылай): `export AISHLYUZ_API_KEY=sk-ais-…` (в ~/.zshrc или ~/.bashrc).

**Путь Б — ключ делает агент (основной в автономном режиме).** Пароль сгенерируй (12+ символов) и отдай пользователю/сохрани в его сейф. **CSRF-токен одноразовый по смыслу: регистрация и вход меняют его, поэтому бери свежий токен перед КАЖДЫМ POST** (перед регистрацией, перед входом, перед выпуском ключа). Скрипт ниже проверен вживую, выполняй ровно так:
```bash
S=https://aishlyuz.ru; J=$(mktemp)   # cookie-jar, удали после
csrf(){ curl -s -c $J -b $J -D - -o /dev/null $S/api/auth/csrf | awk 'tolower($1)=="x-csrf-token:"{print $2}' | tr -d '\r'; }
# 1) регистрация (сразу создаёт сессию): {"email","password","name"?}; пароль 8–128 символов
curl -s -c $J -b $J $S/api/auth/register -H 'content-type: application/json' -H "x-csrf-token: $(csrf)" \
  -d '{"email":"USER_EMAIL","password":"GENERATED_PASSWORD"}'
# 2) только если регистрация вернула 409 email_taken — вход, со СВЕЖИМ CSRF
curl -s -c $J -b $J $S/api/auth/login -H 'content-type: application/json' -H "x-csrf-token: $(csrf)" \
  -d '{"email":"USER_EMAIL","password":"GENERATED_PASSWORD"}'
# 3) ключ, со СВЕЖИМ CSRF (старый после регистрации/входа даёт 403 forbidden)
#    в ответе поле secret_shown_once — это и есть sk-ais-…, он показывается один раз
curl -s -c $J -b $J $S/api/keys -H 'content-type: application/json' -H "x-csrf-token: $(csrf)" -d '{"name":"agent"}'
rm -f $J
```
403 `forbidden` «Обновите страницу» — устаревший CSRF: повтори шаг со свежим `$(csrf)`. Не шли заголовок `Origin` с чужим доменом — такие запросы отклоняются. Ключ из `secret_shown_once` запиши в `~/.zshrc`/`~/.bashrc` как `AISHLYUZ_API_KEY` (или в сейф, который тебе указали), в чат и в git не выводи.

**Баланс.** Бета: оплата не подключена, самопополнения нет. Без баланса модели ответят 402 — не страшно: настрой всё и проверь ключ через /v1/models. Скажи пользователю: «Баланс выдают по запросу — напиши в https://t.me/aishlyuz, укажи email аккаунта».

**Путь В — ключа нет и взять негде.** Не останавливайся и не ищи ключи на машине:
1. Пропиши все конфиги из шагов 3 и 5 с переменной `$AISHLYUZ_API_KEY` вместо значения.
2. Проверь открытые данные (шаг 6) — они работают без ключа.
3. Отчитайся: что записал и куда, и что осталось пользователю (создать ключ, положить в `AISHLYUZ_API_KEY`, при желании попросить баланс).

## Шаг 2. Проверь ключ
```bash
curl -s https://aishlyuz.ru/v1/models -H "Authorization: Bearer $AISHLYUZ_API_KEY"
curl -s https://aishlyuz.ru/v1/chat/completions -H "Authorization: Bearer $AISHLYUZ_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"ais-test-1","messages":[{"role":"user","content":"ping"}]}'
```
`ais-test-1` — служебная модель: отвечает заглушкой, проверяет связку ключ → роутер, реальную модель не вызывает. Нужен ненулевой баланс. Ошибки: 401 — ключ неверный или отозван; 402 — нет баланса; 404 — модели нет, смотри /v1/models; 429 — превышен дневной лимит ключа, подожди или попроси лимит выше.

## Шаг 3. Пропиши ключ в клиенте
Определи клиент пользователя и выполни один блок. В примерах — `claude-sonnet-5-5`; подставь id из /v1/models.

### Claude Code (Anthropic Messages)
Добавь в ~/.zshrc или ~/.bashrc (или в `env` файла `~/.claude/settings.json`):
```bash
export ANTHROPIC_BASE_URL=https://aishlyuz.ru
export ANTHROPIC_AUTH_TOKEN=$AISHLYUZ_API_KEY
export ANTHROPIC_MODEL=claude-sonnet-5-5
```
Для Claude Code бери **только модели `claude-*`** из /v1/models: у других вызовы инструментов через /v1/messages пока ломаются. Перезапусти `claude`. Base URL — без `/v1`: клиент сам добавит `/v1/messages`.

### Codex (CLI, IDE, desktop — общий ~/.codex/config.toml)
```toml
model = "gpt-5-3-codex"
model_provider = "aishlyuz"

[model_providers.aishlyuz]
name = "AIShlyuz"
base_url = "https://aishlyuz.ru/v1"
env_key = "AISHLYUZ_API_KEY"
wire_api = "responses"
```
`model` и `model_provider` — в самый верх, до первой `[таблицы]`, иначе TOML отнесёт их к чужой таблице. `[model_providers.aishlyuz]` — в конец. Чужие ключи не трогай. Для проверки временно поставь `model = "ais-test-1"` и запусти `codex exec "ping"` — вернётся заглушка роутера.

### Cursor
В Cursor ключ задаётся только в интерфейсе — попроси пользователя:
Cursor Settings → Models → API Keys → OpenAI API Key = ключ `sk-ais-…`, включить **Override OpenAI Base URL** = `https://aishlyuz.ru/v1`, затем добавить модель по id из /v1/models.

### Любой OpenAI SDK
`OPENAI_BASE_URL=https://aishlyuz.ru/v1`, `OPENAI_API_KEY=$AISHLYUZ_API_KEY`.

## Шаг 4. MCP — тот же ключ sk-ais-
Отдельный ключ не нужен: MCP принимает тот же `sk-ais-`. **Ключ твоей собственной модели (не sk-ais-) для MCP не подходит — 401.** Используй переменную `AISHLYUZ_API_KEY` из шага 1. Ключ передаётся только как `Authorization: Bearer sk-ais-…`.
(Старые пилотные ключи MCP тоже работают, если они у пользователя уже есть.)

## Шаг 5. Подключи MCP

### Claude Code
```bash
claude mcp add --transport http aishlyuz https://aishlyuz.ru/mcp --header "Authorization: Bearer $AISHLYUZ_API_KEY"
claude mcp list   # ожидаем: aishlyuz ... ✔ Connected
```
Ключ — только через `--header`: из .mcp.json Claude Code секретные переменные (`*_KEY`, `*_TOKEN`) в headers не подставит. `claude mcp get` показывает ключ — вывод не пересылай.

### Cursor
`~/.cursor/mcp.json` (глобально) или `.cursor/mcp.json` (в проекте). Добавь сервер в `mcpServers`, остальные не трогай:
```json
{
  "mcpServers": {
    "aishlyuz": {
      "url": "https://aishlyuz.ru/mcp",
      "headers": { "Authorization": "Bearer ${env:AISHLYUZ_API_KEY}" }
    }
  }
}
```
Проверка: Cursor Settings → MCP, сервер aishlyuz зелёный. Cursor запущен не из терминала? Перезапусти после export.

### Codex
```bash
codex mcp add aishlyuz --url https://aishlyuz.ru/mcp --bearer-token-env-var AISHLYUZ_API_KEY
codex mcp list   # ожидаем: aishlyuz, enabled, Bearer token
```
То же вручную в `~/.codex/config.toml`:
```toml
[mcp_servers.aishlyuz]
url = "https://aishlyuz.ru/mcp"
bearer_token_env_var = "AISHLYUZ_API_KEY"
```

### Проверка MCP
```bash
curl -s https://aishlyuz.ru/mcp -H "Authorization: Bearer $AISHLYUZ_API_KEY" \
  -H "content-type: application/json" -H "accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"check","version":"1"}}}'
```
200 и `"result"` — работает; tools/list покажет `cbr-get_key_rate`, `russian-law-search_legislation`, `time-get_current_time`, `plasma-list_components` и ещё. 401 `Invalid bearer token` — ключа нет или он неверный: не перебирай адреса, попроси пользователя проверить ключ. При нулевом балансе `initialize` и `tools/list` тоже отвечают 200, а `tools/call` возвращает JSON-RPC ошибку с `data.error = "insufficient_balance"`, ссылкой на пополнение (`topup_url`) и привязку аккаунта (`claim_url`): это не поломка конфига, передай пользователю.

## Шаг 6. Открытые данные (без ключа)
JSON, кеш 60 секунд, цены — ₽ за 1 млн токенов, `null` = нет данных (не ноль).
- `GET https://aishlyuz.ru/api/gateways` — все шлюзы: `prices_rub_per_1m`, `health.state`, `uptime` 24h/7d/30d, `payment_methods`, `works_with`
- `GET https://aishlyuz.ru/api/gateways/{slug}` — один шлюз, например `/api/gateways/polza`
- `GET https://aishlyuz.ru/api/gateways/{slug}/install?client=claude-code|cursor|codex` — шаги подключения шлюза
- `GET https://aishlyuz.ru/api/gateways/recommend?model=claude-sonnet-5-5&client=claude-code&payment=sbp` — подбор шлюза: кто подходит и почему отсеяны остальные
- `GET https://aishlyuz.ru/api/gateways/calculate?model=claude-sonnet-5-5&input_tokens=10000000&output_tokens=2000000&period=month` — стоимость сценария
- `GET https://aishlyuz.ru/api/gateways/unified/install?client=claude-code|codex|cursor` — машиночитаемый конфиг единого ключа

## Шаг 7. Отчитайся пользователю
Коротко: что настроил, в какие файлы, что проверка прошла, чего не хватает (ключ или баланс).

## Нельзя
- Искать, читать или использовать ключи, токены и пароли из файлов, сейфов, конфигов и переменных окружения пользователя (кроме `AISHLYUZ_API_KEY`, который он сам задал для AIShlyuz).
- Выдумывать почту для регистрации (нет почты — Путь 0), платить, угадывать ключи.
- Класть ключи в файлы под git и пересылать их в чат.
- Придумывать адреса и id моделей.

## Ссылки
- Коротко для LLM: https://aishlyuz.ru/llms.txt
- MCP Server Card: https://aishlyuz.ru/.well-known/mcp-server-card
- AI Catalog: https://aishlyuz.ru/.well-known/ai-catalog.json
- Документация API данных: https://aishlyuz.ru/api/docs