## Свой агент на подписке

Сторонний агентный клиент — OpenCode, Crush, Cline, Aider или собственный код — работает с моделями по ключу подписки Cowork/Code. Запросы такого ключа расходуют квоту подписки, а не кошелёк портала.

**Скоуп:** `vibe:ai` + `vibe:cowork` | **Базовый URL:** `https://vibecode.bitrix24.tech/v1` | **Авторизация:** `X-Api-Key` или `Authorization: Bearer`

Отдельного адреса и отдельного протокола у такого ключа нет: это тот же OpenAI-совместимый [AI Router](/docs/ai), меняется только тарификация. Всё, что описано в разделе AI, работает и здесь.

## Как получить ключ

1. Откройте раздел [Cowork/Code](/cowork) в личном кабинете платформы Вайбкод.
2. Нажмите «Получить ключ» — откроется диалог создания ключа, в котором тарификация уже переключена на подписку.
3. Отметьте нужные права и создайте ключ.
4. Скопируйте значение ключа сразу. Оно показывается один раз, восстановить его нельзя: потерянный ключ отзывают и выписывают заново.

Кнопки «Получить ключ» на странице нет, пока доступ к Cowork/Code не получен — заявка подаётся на той же странице. Кнопка видна, но не нажимается, когда администратор портала запретил сторонние клиенты, и рядом с ней стоит поясняющая надпись.

## Что этот ключ может и чего не может

**По умолчанию ключ несёт все права портала Битрикс24.** Диалог открывается с отмеченными правами на данные, и агент с таким ключом читает и меняет данные портала от вашего имени. Снимаются они одной кнопкой «Снять все» в группе прав Битрикс24: тогда у ключа остаётся только право на AI, и данные портала агенту закрыты.

**Инфраструктура ключу подписки недоступна всегда.** Создание серверов, деплой и выполнение команд закрыты для любого ключа с правом Cowork/Code — такой запрос отвечает `403 INFRA_FORBIDDEN_FOR_COWORK_KEY`. Снятая в диалоге отметка «Инфраструктура» это отражает, а не ограничивает: вернуть отметку и получить инфраструктуру нельзя. Отдельный ключ с правом деплоя выдаёт настольное приложение — [Проектный ключ для деплоя](/docs/cowork/deploy-key). Ключу стороннего агента этот эндпоинт отвечает `403 COWORK_HARNESS_KEY_FORBIDDEN`.

**Право Cowork/Code с выданного ключа не снимается.** Ключ либо остаётся на подписке, либо отзывается целиком. Перевести его на кошелёк портала нельзя, обратная замена тоже не предусмотрена: ключ с оплатой из кошелька создаётся отдельно, в разделе «API-ключи».

**Пункт «Переподключить» у такого ключа не появляется.** Он предназначен для ключей, которые платформа не ведёт сама, а у ключа подписки платформенное назначение. Если вебхук ключа перестанет работать, отзовите ключ и выпишите новый.

**Перевыпуск проходит те же проверки, что и выдача.** Ротация ключа подписки требует, чтобы доступ к Cowork/Code был открыт, политика портала разрешала сторонние клиенты и подписка была активна. Коды отказа — на странице [Менеджмент-ключи](/docs/management-keys).

## Подключение

Все клиенты настраиваются одинаково: базовый адрес `https://vibecode.bitrix24.tech/v1`, ключ в заголовке `Authorization: Bearer` или `X-Api-Key`, формат запросов и ответов — OpenAI-совместимый. Ниже готовые фрагменты конфигурации, те же самые диалог показывает сразу после создания ключа.

Ключ в конфигурацию не вписывается: файлы `opencode.json` и `.crush.json` лежат рядом с кодом и попадают в репозиторий, поэтому оба клиента читают значение из переменной окружения.

### OpenCode

Файл `opencode.json`.

```bash
# Сначала положите ключ в переменную окружения
export VIBECODE_API_KEY=<ваш ключ>
```

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "bitrix24": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Bitrix24 CoworkCode",
      "options": {
        "baseURL": "https://vibecode.bitrix24.tech/v1",
        "apiKey": "{env:VIBECODE_API_KEY}"
      },
      "models": {
        "bitrix/bitrixgpt-5.5": { "name": "BitrixGPT" }
      }
    }
  }
}
```

### Crush

Файл `.crush.json`.

```bash
# Сначала положите ключ в переменную окружения
export VIBECODE_API_KEY=<ваш ключ>
```

```json
{
  "providers": {
    "bitrix24": {
      "type": "openai-compat",
      "base_url": "https://vibecode.bitrix24.tech/v1",
      "api_key": "$VIBECODE_API_KEY",
      "models": [
        { "id": "bitrix/bitrixgpt-5.5", "name": "BitrixGPT", "context_window": 128000, "default_max_tokens": 8000 }
      ]
    }
  }
}
```

### Cline

Настройки расширения. Cline хранит ключ в защищённом хранилище редактора, файла конфигурации рядом с кодом у него нет, поэтому значение вставляется прямо в форму.

```
API Provider: OpenAI Compatible
Base URL: https://vibecode.bitrix24.tech/v1
API Key: <ваш ключ> (то же значение, что в $VIBECODE_API_KEY)
Model ID: bitrix/bitrixgpt-5.5
```

### Aider

Переменные окружения.

```bash
export OPENAI_API_BASE=https://vibecode.bitrix24.tech/v1
export OPENAI_API_KEY=$VIBECODE_API_KEY
aider --model openai/bitrix/bitrixgpt-5.5
```

### curl

Проверка ключа одним запросом.

```bash
# Сначала положите ключ в переменную окружения
export VIBECODE_API_KEY=<ваш ключ>

curl -X POST https://vibecode.bitrix24.tech/v1/chat/completions \
  -H "Authorization: Bearer $VIBECODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"bitrix/bitrixgpt-5.5","messages":[{"role":"user","content":"ping"}]}'
```

## Список моделей

Идентификаторы для поля `model` возвращает `GET /v1/models`. Ключу подписки этот список приходит уже суженным: в нём остаются только модели, разрешённые для Cowork/Code. Набор задаёт платформа, и он меняется — берите его запросом, а не списком, выписанным в конфигурацию однажды.

```bash
curl https://vibecode.bitrix24.tech/v1/models \
  -H "X-Api-Key: YOUR_API_KEY"
```

Поля ответа и данные одной модели — [Модели](/docs/ai/models).

## Лимиты и расход

Тариф подписки и расход трёх окон квоты в процентах отдаёт `GET /v1/cowork/me` — тем же ключом, дополнительных прав не нужно.

```bash
curl https://vibecode.bitrix24.tech/v1/cowork/me \
  -H "X-Api-Key: YOUR_API_KEY"
```

```json
{
  "tier": "FREE",
  "state": "ACTIVE",
  "quotaPct": { "fiveHour": 40, "week": 24, "month": 20 },
  "resetAt": {
    "fiveHour": "2026-08-22T17:30:00.000Z",
    "week": "2026-08-25T09:00:00.000Z",
    "month": "2026-09-01T00:00:00.000Z"
  },
  "nextChargeAt": null
}
```

Окна вложены друг в друга и считаются одновременно — 5 часов, неделя и месяц. Работа останавливается при исчерпании любого из них, у каждого окна свой момент сброса в `resetAt`. Абсолютных чисел квоты наружу нет, только доли. Полный состав ответа — [Сводка по подписке Cowork/Code](/docs/cowork/me), развёрнутое состояние с рекомендациями и каталогом тарифов — [Состояние подписки Cowork/Code](/docs/cowork/state).

## Что означают ошибки

У стороннего клиента нет своего интерфейса — он показывает поле `message` из ответа дословно. Тело отказа AI-эндпоинтов идёт в формате OpenAI, `{ "error": { "message", "type", "code" } }`, и `code` там в нижнем регистре. Ответы `/v1/cowork/*` идут в общем формате платформы, `{ "success": false, "error": { "code", "message" } }`, и `code` там в верхнем.

**Окно квоты кончилось — `402`, код `cowork_quota_exhausted`.** Поле `window` называет исчерпанное окно (`5h`, `week` или `month`), `resetAt` — момент сброса, `nextTier` — следующий тариф. Заголовок `Retry-After` даёт паузу в секундах до сброса. Блокировку снимает и ожидание сброса, и переход на тариф выше.

```json
{
  "error": {
    "message": "Cowork/Code quota exhausted for the 5h window. Wait until 2026-08-22T17:30:00.000Z or upgrade your tier.",
    "type": "insufficient_quota",
    "code": "cowork_quota_exhausted",
    "window": "5h",
    "resetAt": "2026-08-22T17:30:00.000Z",
    "nextTier": "PRO"
  }
}
```

**Подписка не активна — `402`, код `cowork_subscription_inactive`.** Подписка владельца ключа приостановлена или отменена, и квоты у неё больше нет. Возобновляется она в разделе [Cowork/Code](/cowork), ключ при этом остаётся прежним.

**Слишком много запросов — `429`, код `rate_limit_exceeded`.** Превышен минутный лимит запросов. Дождитесь паузы из заголовка `Retry-After` и повторите запрос, уровень лимита назван в поле `scope` и в заголовке `X-RateLimit-Scope`. Другие ответы `429` этого эндпоинта разбирает страница [Лимиты запросов и повторы](/docs/ai/chat/rate-limits).

**Cowork/Code выключен на платформе — `503`, код `cowork_feature_disabled`.** Возможность остановлена целиком, ключ и подписка тут ни при чём. Повторите запрос позже.

Если в описании не указан другой эндпоинт, отказ приходит на `POST /v1/chat/completions`.

| HTTP | Код | Описание |
|------|-----|----------|
| 402 | `cowork_quota_exhausted` | Исчерпано одно из окон квоты подписки. Тело несёт `window`, `resetAt` и `nextTier`, заголовок `Retry-After` — число секунд до сброса |
| 402 | `cowork_subscription_inactive` | У владельца ключа нет активной подписки Cowork/Code на этом портале |
| 402 | `cowork_model_not_allowed` | Модель не разрешена для Cowork/Code. Поле `allowedModelIds` перечисляет разрешённые |
| 403 | `scope_missing` | У ключа нет права `vibe:ai` |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | Запрос к инфраструктуре, например `POST /v1/infra/servers`. Ключу с правом Cowork/Code инфраструктура закрыта |
| 403 | `COWORK_HARNESS_KEY_FORBIDDEN` | `POST /v1/cowork/deploy-key`: проектный ключ с правом деплоя ключу стороннего агента не выписывается |
| 404 | `COWORK_NOT_ACTIVATED` | `GET /v1/cowork/me`: подписка Cowork/Code не найдена для пары пользователь и портал |
| 429 | `rate_limit_exceeded` | Превышен минутный лимит запросов. Пауза — в заголовке `Retry-After`, уровень — в `X-RateLimit-Scope` |
| 503 | `cowork_feature_disabled` | Cowork/Code отключён на уровне платформы |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Смотрите также

- [AI Router](/docs/ai)
- [Создать чат-комплишен](/docs/ai/chat/completions)
- [Модели](/docs/ai/models)
- [Cowork/Code](/docs/cowork)
- [Сводка по подписке Cowork/Code](/docs/cowork/me)
- [Менеджмент-ключи](/docs/management-keys)
- [Ошибки](/docs/errors)