#Скилл Битрикс24 для OpenClaw

Скилл Битрикс24 — часть плагина @ihazz/bitrix24, которая даёт агенту OpenClaw доступ к API портала Битрикс24. Через скилл агент работает со сделками, задачами, контактами, календарём и другими данными портала.

#Как устроен скилл

Скилл — это инструкция для агента, как вызывать API Вайбкода. Он не добавляет в OpenClaw отдельный API-инструмент — вместо этого использует стандартный exec-инструмент с curl-командами и набором переменных окружения, которые плагин экспортирует на старте.

Этот подход даёт три выгоды:

  • Агент видит реальные ответы API, а не обёртки. Если в ответе ошибка — агент читает сообщение и исправляет запрос.
  • Любой эндпоинт Вайбкода доступен без обновления плагина — скилл сам читает каталог методов через GET /v1/guide при первом обращении.
  • Документация на сайте Вайбкода — единственный источник правды для скилла. Когда страницы обновляются, агент получает актуальную информацию без релиза npm-пакета.

#Установка

Установить плагин в OpenClaw:

Terminal 
openclaw plugins install @ihazz/bitrix24@latest

Разрешить плагин в openclaw.json:

JSON 
{
  "plugins": {
    "allow": ["bitrix24"]
  }
}

После установки в директории расширений OpenClaw появятся два каталога:

  • skills/bitrix24/ — служебный, для отладки и настройки самого плагина.
  • skills/vibe-platform/ — рабочий, для работы агента с данными портала.

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

При регистрации плагин читает default-аккаунт из конфигурации канала и экспортирует три переменные. Скилл инструктирует агента использовать их в каждом вызове.

Переменная Откуда берётся Что делает
VIBE_KEY channels.bitrix24.providerConfig.apiKey API-ключ Вайбкода. Передаётся в заголовке X-Api-Key каждого запроса.
VIBE_BASE_URL channels.bitrix24.providerConfig.baseUrl или https://vibecode.bitrix24.tech/v1 по умолчанию Базовый URL для вызовов /v1/*.
VIBE_PLATFORM_URL Корень VIBE_BASE_URL без хвоста /v1 Корень сайта документации. Скилл загружает с него страницы docs-content/<topic>.md для справки по эндпоинтам.

Если переменные уже заданы в окружении OpenClaw — плагин их не трогает. Это позволяет хост-процессу задать собственный ключ.

Для конфигураций с несколькими аккаунтами автоинъекция работает только для default-аккаунта. Остальные объявляют переменные явно:

JSON 
{
  "skills": {
    "entries": {
      "vibe-platform": {
        "env": {
          "VIBE_KEY": "vibe_api_…",
          "VIBE_BASE_URL": "https://vibecode.bitrix24.tech/v1"
        }
      }
    }
  }
}

#Какой скоуп нужен на API-ключе

Один API-ключ Вайбкода обслуживает три слоя интеграции, поэтому минимально нужны три категории скоупов:

  • imbot — для коннектора: регистрация бота на портале, опрос событий чата, отправка ответов.
  • vibe:ai — для LLM-провайдера OpenClaw, который через тот же ключ ходит в AI Router Вайбкода (https://vibecode.bitrix24.tech/v1/ai) и берёт оттуда модель агента.
  • Доменные скоупы под задачи самого скилла: crm для CRM, tasks для задач, calendar для расписания, im для пассивного чтения чатов в режиме наблюдения и так далее.

Точный список скоупов на конкретном ключе агент сам читает через GET /v1/me при старте сессии и понимает, какие операции ему доступны. Полный справочник — Ключи и авторизация.

#Как агент находит данные

Скилл инструктирует агента использовать четыре источника в строгом порядке. Полные подробности по каждому — на странице, к которой агент обращается; скилл не дублирует контракт API.

  1. Каталог методов — GET $VIBE_BASE_URL/guide один раз за сессию. Возвращает все доступные ключу эндпоинты с короткими описаниями. Агент держит ответ в контексте и сверяется с ним перед каждым новым типом запроса.
  2. Идентификация — GET $VIBE_BASE_URL/me, когда нужно узнать текущего пользователя, портал, тариф, доступные возможности. Здесь же агент находит свой responsibleId для создания задач.
  3. Поля сущности — GET $VIBE_BASE_URL/<entity>/fields перед записью. Возвращает канонический список полей с пометками обязательности.
  4. Текстовая документация — web_fetch страницы $VIBE_PLATFORM_URL/docs-content/<topic>.md для справки по фильтрам, batch-запросам, кодам ошибок, рецептам сценариев.

Скилл явно запрещает агенту изобретать имена полей, формат body, операторы фильтров. Если в каталоге или справочнике этого нет — этого нет в API.

#Базовые сценарии

Канонический формат вызова — exec-инструмент OpenClaw с curl-командой:

Terminal 
curl -sS --max-time 30 \
  -H "X-Api-Key: $VIBE_KEY" \
  -H "Content-Type: application/json" \
  "$VIBE_BASE_URL/me"

Дальше — типичные пользовательские запросы и как агент их собирает.

#Получить сделки в работе

Terminal 
curl -sS --max-time 30 \
  -H "X-Api-Key: $VIBE_KEY" \
  "$VIBE_BASE_URL/deals?filter[stageSemanticId]=P&limit=20"

Параметр filter[stageSemanticId]=P оставляет только сделки в активной стадии (P — processing). Полные правила фильтрации — Синтаксис фильтрации.

#Создать задачу

Перед записью агент запрашивает подтверждение одним предложением — например, «Создать задачу „Проверить отчёт“ для Сергея с дедлайном пятница?» — и ждёт явного «да». После согласия:

Terminal 
curl -sS --max-time 30 -X POST \
  -H "X-Api-Key: $VIBE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "title": "Проверить отчёт",
      "responsibleId": 79,
      "deadline": "2026-05-09T18:00:00+03:00"
    }
  }' \
  "$VIBE_BASE_URL/tasks"

Если responsibleId не указан — Битрикс24 вернёт INVALID_PARAMS с сообщением «Не указан исполнитель», и скилл инструктирует агента однократно подтянуть ID текущего пользователя из GET /v1/me, прежде чем повторить запрос.

#Прочитать контакт по идентификатору

Terminal 
curl -sS --max-time 30 \
  -H "X-Api-Key: $VIBE_KEY" \
  "$VIBE_BASE_URL/contacts/123"

#Расписание на сегодня

Terminal 
curl -sS --max-time 30 \
  -H "X-Api-Key: $VIBE_KEY" \
  "$VIBE_BASE_URL/calendar-events?filter[from]=2026-05-08T00:00:00%2B03:00&filter[to]=2026-05-08T23:59:59%2B03:00"

Скилл объединяет события календаря и задачи с дедлайном «сегодня» в один ответ пользователю — это поведение скилла, не отдельный эндпоинт.

#Объединить несколько вызовов в один запрос

Когда пользователь спросил утренний отчёт — задачи + календарь + просроченное — скилл собирает batch-запрос:

Terminal 
curl -sS --max-time 30 -X POST \
  -H "X-Api-Key: $VIBE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "calls": [
      { "method": "GET", "path": "/tasks", "params": { "filter[responsibleId]": "79", "filter[<deadline]": "2026-05-08T00:00:00+03:00" } },
      { "method": "GET", "path": "/calendar-events", "params": { "filter[from]": "2026-05-08T00:00:00+03:00", "filter[to]": "2026-05-08T23:59:59+03:00" } }
    ]
  }' \
  "$VIBE_BASE_URL/batch"

Контракт /v1/batch — Batch-запросы.

#Подтверждение перед записью

Скилл требует от агента показывать пользователю короткое описание действия одной фразой перед каждым POST / PATCH / PUT / DELETE и перед любым вызовом /v1/batch — даже если внутри только чтение, потому что batch может содержать запись. Агент дожидается явного «да» и только потом запускает curl.

#Многоязычные ответы

Скилл инструктирует агента отвечать пользователю на том языке, на котором тот пишет. Технические ответы API публикуются на английском, но агент переводит сообщения об ошибках и подтверждения на язык пользователя. Поэтому INVALID_API_KEY пользователь увидит как «Доступ к Вайбкоду истёк, пересоздайте ключ на сайте», а не как сырой код ошибки.

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