yandex-metrika-assistant

OpenClaw + Яндекс.Метрика API — stat/Logs/management, OAuth, presets, UTM, цели, CSV, квоты; плагин yandex-metrika-assistant.

Artur Horosheff@horosheff

Install

openclaw skills install @horosheff/yandex-metrika-assistant

Яндекс.Метрика API — заточка под OpenClaw

Плагин: yandex-metrika-assistant (openclaw.plugin.json в этой папке).
Цель: ноль сюрпризов — сначала конфиг и секреты, потом правильный endpoint, без выдуманных метрик и без утечки токена.

Онбординг человека (порядок ответов агента)

Если токена ещё нет (пользователь только ставит навык или не настроил ключ):

Сначала дай ссылку и краткое резюме установки: {baseDir}/docs/INSTALL-FOR-HUMANS-RU.md (шаги OpenClaw + OAuth + куда вставить ключ).
Обязательно перечисли, какие галочки в приложении Яндекс OAuth нужны для Метрики (таблица из того же файла / шаг 2): статистика и чтение, создание/изменение счётчиков, при необходимости расходы, параметры пользователей, офлайн-данные.
Укажи канал поддержки: https://t.me/maya_pro — вопросы по установке и сценариям; не проси кидать токен в Telegram публично.
Затем — получение токена: {baseDir}/docs/INSTRUCTION-GET-TOKEN-RU.md (или ссылка authorize с oauthClientId из конфига).
Напомни: ключ хранить в oauthToken плагина или в YANDEX_METRIKA_OAUTH_TOKEN, не в чате.

После того как ключ добавлен (пользователь сообщил, что сохранил токен в конфиг, или токен уже есть в конфиге/окружении):

Не проси продиктовать токен.
Заверши ответ блоком «С чего начать» — предложи 3–5 коротких вариантов (нумерованный список), например:
1. Показать список счётчиков Метрики.
2. Визиты по дням за последние 7 дней.
3. Сводка по источникам трафика.
4. Топ страниц по просмотрам.
5. Конверсии по цели (если есть цели).

Полный список идей — {baseDir}/docs/INSTALL-FOR-HUMANS-RU.md (раздел «После добавления ключа») и {baseDir}/docs/10-user-intents-matrix.md.

Типовые формулировки пользователей («откуда трафик», «цели», «UTM», «география», «сравни периоды», «выгрузи CSV», «сырые логи») — смотри матрицу: {baseDir}/docs/10-user-intents-matrix.md (разбивка по разделам A–J + ссылки на официальные примеры и пресеты).

OpenCLaw: порядок работы (строго)

Токен брать только из:
- настроек плагина oauthToken (см. configSchema в openclaw.plugin.json), или
- переменной окружения YANDEX_METRIKA_OAUTH_TOKEN (если хост OpenClaw так настроен), или
- пользователь явно передал токен один раз для текущей сессии — тогда использовать, но не повторять токен обратно в ответе и не вставлять в файлы репозитория.
Если токена нет — не вызывать API и не придумывать ответ Метрики. Следуй разделу «Онбординг человека» выше: сначала {baseDir}/docs/INSTALL-FOR-HUMANS-RU.md, галочки OAuth, @maya_pro, затем {baseDir}/docs/INSTRUCTION-GET-TOKEN-RU.md; при наличии oauthClientId — ссылка authorize?response_type=token&client_id=....
defaultCounterId из конфига: если пользователь не назвал счётчик — используй это значение и одной строкой напиши: «использую счётчик по умолчанию из конфига OpenClaw».
Любые curl/команды в чат — только с плейсхолдером $env:YANDEX_METRIKA_OAUTH_TOKEN или «подставь токен из секрета OpenClaw», не вставляй токен целиком.
Windows / PowerShell: если curl -H "Authorization: OAuth …" даёт ошибки из‑за кавычек — используй Invoke-RestMethod с -Headers @{ Authorization = 'OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN }** или заголовок через конкатенацию в скобках: -H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN). Подробно: {baseDir}/docs/OPENCLAW-AGENT.md, {baseDir}/docs/EXAMPLES.md.

Быстрые рецепты (копипаста для пользователя, Windows PowerShell)

Подстановка токена из env (удобно рядом с OpenClaw):

powershell

$env:YANDEX_METRIKA_OAUTH_TOKEN = "<секрет, не коммитить>"
$cid = "<COUNTER_ID>"
# Надёжнее без вложенных кавычек вокруг токена:
curl.exe -s -H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN) `
  "https://api-metrika.yandex.net/management/v1/counters?per_page=20"

Отчёт «визиты за последние 7 дней» (проверь ids и метрики по задаче):

powershell

curl.exe -s -G "https://api-metrika.yandex.net/stat/v1/data" `
  --data-urlencode "ids=$cid" `
  --data-urlencode "metrics=ym:s:visits" `
  --data-urlencode "date1=7daysAgo" `
  --data-urlencode "date2=yesterday" `
  -H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN)

Сценарий: «пришли ежедневную статистику по сайту maya»

Так OpenClaw должен отработать запрос (и что увидит человек в ответе).

Внутренние шаги агента

Токен — из oauthToken / YANDEX_METRIKA_OAUTH_TOKEN. Нет токена → стоп, ссылка на {baseDir}/docs/INSTRUCTION-GET-TOKEN-RU.md.
Счётчик — если в конфиге есть defaultCounterId и пользователь не просил другой сайт, можно спросить: «использовать счётчик по умолчанию?» или сразу использовать, если контекст однозначен.
Иначе: GET /management/v1/counters с search_string=maya (или фрагмент домена: mayai, blog.mayai). Если несколько счётчиков — перечислить id, name, site и попросить выбрать один id.
Период — если не сказан, предложить по умолчанию, например вчера − 29 дней … вчера (без «сегодня» для стабильности данных) или уточнить у пользователя.
Ежедневная разбивка — API отчётов:
- вариант А: GET .../stat/v1/data с группировкой по дню визита dimensions=ym:s:date, metrics по задаче (часто ym:s:visits, при необходимости ym:s:pageviews, ym:s:users — имена проверять в справочнике);
- вариант Б: GET .../stat/v1/data/bytime — если удобнее именно «по времени» (см. openapi в доке stat).
Вызвать API (или дать пользователю одну готовую команду с плейсхолдерами), распарсить JSON.
Если в ответе contains_sensitive_data": true — кратко предупредить про ограничение раскрытия данных.

Как выглядит ответ человеку (шаблон)

Агент пишет короткое резюме, затем таблицу или список по дням (дата → визиты / просмотры / и т.д.), без сырого JSON на экран целиком, если пользователь не просил сырой вывод.

Пример формулировки:

«Счётчик: LAYMI (id …), сайт blog.mayai.ru, период …. Ниже визиты по дням. Данные из API Метрики, токен из конфига OpenClaw.»
Далее строки вида: 2025-03-01 — визиты: 120, …
Примечание при 429: «Сработала квота отчётов; повтори через несколько минут» ({baseDir}/docs/04-quotas.md).

Пример цепочки запросов (PowerShell, без секрета в логах чата)

powershell

# 1) Найти счётчик по подстроке (maya / mayai)
curl.exe -s -G "https://api-metrika.yandex.net/management/v1/counters" `
  --data-urlencode "search_string=maya" `
  --data-urlencode "per_page=50" `
  -H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN)

# 2) Ежедневные визиты (подставь $cid из шага 1)
curl.exe -s -G "https://api-metrika.yandex.net/stat/v1/data" `
  --data-urlencode "ids=$cid" `
  --data-urlencode "dimensions=ym:s:date" `
  --data-urlencode "metrics=ym:s:visits" `
  --data-urlencode "date1=30daysAgo" `
  --data-urlencode "date2=yesterday" `
  --data-urlencode "sort=ym:s:date" `
  -H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN)

Точные metrics/dimensions при спорных отчётах — только из официальной доки, не по памяти модели.

Сценарий: «на какую страницу больше трафика?»

Запрос про страницы — это снова API отчётов GET .../stat/v1/data, после того же разрешения счётчика (id / defaultCounterId / search_string), что и в сценарии выше.

Смысл «трафика»

Чаще всего пользователь имеет в виду просмотры страниц (хиты): группировка по URL страницы + метрика просмотров. Тогда в одном запросе используется только префикс ym:pv: (визиты и хиты в основном наборе не смешивать).
Если нужны входы / визиты с первой страницы (лендинги), это другой отчёт: группировки уровня визита (ym:s:...), другие метрики — уточнить у пользователя или дать оба коротко («по просмотрам лидирует …, по визитам на входе …»), опираясь на справочник группировок.

Типовой запрос (топ URL по просмотрам)

Параметры (имена перепроверять в доке при смене версии API):

dimensions — URL страницы на уровне хита, например ym:pv:URL.
metrics — ym:pv:pageviews (и при необходимости ещё метрики из того же множества ym:pv:).
sort — по убыванию просмотров, в доке Метрики для сортировки по убыванию часто используется - перед метрикой (см. {baseDir}/docs/05-reports-api-stat.md).
limit — топ 10–20 URL, чтобы ответ был читаемым.
date1 / date2 — как в других сценариях (если не заданы — default или вопрос пользователю).

Как выглядит ответ человеку

Коротко: период, счётчик, что считали (просмотры по URL). Затем список: URL → число просмотров (топ N). Длинные URL можно обрезать визуально с «…», полный URL — по наведению или второй строкой при необходимости.

Пример `curl` (PowerShell)

powershell

curl.exe -s -G "https://api-metrika.yandex.net/stat/v1/data" `
  --data-urlencode "ids=$cid" `
  --data-urlencode "dimensions=ym:pv:URL" `
  --data-urlencode "metrics=ym:pv:pageviews" `
  --data-urlencode "sort=-ym:pv:pageviews" `
  --data-urlencode "limit=15" `
  --data-urlencode "date1=30daysAgo" `
  --data-urlencode "date2=yesterday" `
  -H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN)

Если API вернёт ошибку совместимости группировки и метрики — не «угадывать» замену, а свериться с актуальным openapi для /stat/v1/data на сайте Метрики.

Маршрутизация: что дергать

Запрос пользователя	Куда	Файл
Отчёт, метрики, период, сегменты	`GET .../stat/v1/data` (и др. из stat)	`{baseDir}/docs/05-reports-api-stat.md`
Топ страниц, «куда больше трафика»	`stat/v1/data`, группировка URL (`ym:pv:`)	сценарий ниже, `{baseDir}/docs/05-reports-api-stat.md`
Сырые логи, выгрузка	`management/v1/counter/{id}/logrequests...`	`{baseDir}/docs/06-logs-api.md`
Список счётчиков, цели, настройки	`management/v1/...`	`{baseDir}/docs/08-management-quickstart.md`
Загрузка расходов, CRM, офлайн	data-import	`{baseDir}/docs/07-data-import.md`
401/403, scope	OAuth	`{baseDir}/docs/03-auth-oauth.md`, `{baseDir}/docs/INSTRUCTION-GET-TOKEN-RU.md`
429	Квоты	`{baseDir}/docs/04-quotas.md`
«Что ещё спрашивают / не знаю какой отчёт»	Матрица намерений	`{baseDir}/docs/10-user-intents-matrix.md`

Смешанная задача: сначала counters или defaultCounterId, потом stat/logs.

Железные правила API

Заголовок: Authorization: OAuth <access_token> (слово OAuth и пробел обязательны).
Хост: https://api-metrika.yandex.net
В одном запросе stat не смешивать ym:s: и ym:pv: в основных metrics/dimensions (детали в {baseDir}/docs/05-reports-api-stat.md).
Лимиты: до 20 метрик, 10 группировок в /stat/v1/data; 200 запросов / 5 мин на этот endpoint на пользователя; Logs с IP — 10/с.
Имена метрик/группировок не выдумывать — только из официального справочника (ссылки в {baseDir}/docs/01-links-and-hub.md).
После скачивания Logs — clean, квота хранилища 10 ГБ на счётчик ({baseDir}/docs/06-logs-api.md).

Формат ответа агента OpenClaw

Что сделано / что предлагается (1 фраза).
Откуда взяты токен и счётчик (конфиг / env / спросил у пользователя).
Команда или URL-шаблон без секрета.
Как проверить успех (HTTP 200, поля JSON).
Риски: квоты, contains_sensitive_data, 429.

Карта файлов

Файл	Назначение
`openclaw.plugin.json`	Контракт OpenClaw: `oauthToken`, `defaultCounterId`, `oauthClientId`
`{baseDir}/docs/INSTALL-FOR-HUMANS-RU.md`	Установка: OpenClaw, OAuth-галочки, TG, после ключа — с чего начать
`{baseDir}/docs/INSTRUCTION-GET-TOKEN-RU.md`	Токен для людей
`{baseDir}/docs/OPENCLAW-AGENT.md`	Установка: нет HOOK.md; PowerShell без ловушек кавычек
GitHub: `Horosheff/yandex-metrika-assistant` → `scripts/exchange-yandex-oauth-code.ps1`	Обмен `code` → token (в этом пакете не включён)
`{baseDir}/docs/01`–`09`	Справка по разделам API
`{baseDir}/docs/10-user-intents-matrix.md`	Матрица вопросов пользователей → API (ресёрч по примерам и пресетам)

Официальный хаб: https://yandex.ru/dev/metrika

yandex-metrika-assistant

Install

Яндекс.Метрика API — заточка под OpenClaw

Онбординг человека (порядок ответов агента)

OpenCLaw: порядок работы (строго)

Быстрые рецепты (копипаста для пользователя, Windows PowerShell)

Сценарий: «пришли ежедневную статистику по сайту maya»

Внутренние шаги агента

Как выглядит ответ человеку (шаблон)

Пример цепочки запросов (PowerShell, без секрета в логах чата)

Сценарий: «на какую страницу больше трафика?»

Смысл «трафика»

Типовой запрос (топ URL по просмотрам)

Как выглядит ответ человеку

Пример curl (PowerShell)

Маршрутизация: что дергать

Железные правила API

Формат ответа агента OpenClaw

Карта файлов

Related skills

Пример `curl` (PowerShell)