Добавление ноды на canvas

Чтобы продолжить цепочку, нужно вставить новую ноду после существующей или на пустой canvas. Для этого открывают панель выбора нод тремя способами: кнопка Open nodes panel в центре canvas, кнопка Add node на стрелке соединения и + на output-коннекторе любой ноды.

Панель называется What happens next?. В ней сразу видно категории и поле поиска.

Как это работает

• Клик по Open nodes panel или Add node открывает список.
• В поле Search nodes... вводят имя ноды или сервиса (например http, slack, schedule). Список фильтруется по мере ввода.
• Навигация по категориям: AI, Action in an app, Data transformation, Flow, Core, Human review, Add another trigger.
• Клик по названию ноды ставит её на canvas и сразу открывает панель Parameters.
• На пустом canvas можно нажать клавишу Tab — откроется та же панель без клика мышью.

Первая нода любого воркфлоу должна быть триггером (Schedule Trigger, Webhook, Manual и подобные). Обычные ноды-действия в начало ставить нельзя.

Типичные ошибки

• Поставил обычную ноду первой → воркфлоу не из чего стартовать → замени первую ноду на триггер из категории Core или через поиск.
• Ищут ноду по русскому названию → список остаётся пустым → вводи английское имя сервиса в поле Search nodes....
• Целятся мышью в мелкий + на стрелке → промахиваются → нажми Tab прямо на canvas.
• Открывают категорию Add another trigger после уже существующей ноды → добавляют лишний триггер → для обычного шага используй поиск или категории Action in an app и Data transformation.

Типы update'ов в Telegram Trigger: что значит Message, Callback Query, Inline Query

Параметр Updates находится в Telegram Trigger → Parameters → Trigger On. Это выпадающий список с множественным выбором, каждый пункт которого соответствует одному типу события Bot API. По умолчанию включён только Message.

Когда бот получает обновление, n8n передаёт его дальше только если соответствующий тип отмечен. Невключённые типы просто игнорируются.

Зачем это нужно

Без явного выбора типов бот будет реагировать на всё подряд или, наоборот, пропускать нужные события. Например, нажатие inline-кнопки приходит отдельным типом и без галочки Callback Query до ноды не дойдёт.

Как это работает

Каждый выбранный тип добавляет своё поле в $json:

• Message — обычное сообщение в чате. Данные лежат в $json.message.
• Edited Message — исправленное сообщение. Поле $json.edited_message.
• Callback Query — нажатие inline-кнопки. Полезная нагрузка в $json.callback_query.data.
• Inline Query — запрос, когда пользователя упоминают через @ в любом чате.
• Channel Post / Edited Channel Post — посты в канале, где бот является администратором.
• Chosen Inline Result, Shipping Query, Pre Checkout Query, Poll, Poll Answer, My Chat Member, Chat Member — узкие случаи, используются редко.

Типичные ошибки

• Отметили все галочки «на всякий случай» → воркфлоу срабатывает на лишние события → следующие ноды падают на отсутствующих полях $json.
• Ожидают нажатие inline-кнопки, но оставили только Message → Callback Query игнорируется.
• Пытаются прочитать текст отредактированного сообщения через $json.message.text → получают undefined, потому что данные находятся в $json.edited_message.text.

Когда не подходит

Если нужно обрабатывать только сообщения определённого формата или фильтровать по содержимому, используй ноду IF или Filter после триггера, а не отключай типы в Trigger On.

Кнопка ручного запуска для теста

В редакторе workflow внизу canvas есть большая оранжевая кнопка «Execute workflow». Это основной инструмент тестирования: один клик — и весь workflow прогоняется от триггера до конца, прямо в редакторе. На production это никак не влияет — даже если воркфлоу опубликован (Publish), кнопка запускает отдельный тестовый прогон.

Как это работает

1. Нажимаешь Execute workflow внизу canvas.

1. n8n запускает workflow от триггера. Ноды по очереди подсвечиваются: серая → жёлтая (выполняется) → зелёная (готово) или красная (ошибка). Внизу каждой ноды появляется счётчик пришедших на вход элементов.

1. Клик по любой ноде после прогона — видишь её input и output. Это и есть отладка: где данные пропали или пришли не в том виде.

Особый случай: workflow с Chat Trigger

Если в workflow стоит триггер Chat Trigger (встроенный в n8n чат), правила для тестирования другие — Execute workflow появляется не сразу.

• Когда у Chat Trigger ещё нет запиненных данных — внизу canvas вместо Execute workflow стоит кнопка Open chat. Клик открывает встроенный чат-виджет n8n: ты пишешь сообщение, оно идёт в триггер, workflow выполняется от события «новое сообщение в чате». Это и есть основной путь тестирования Chat Trigger.
• Когда данные Chat Trigger запинены (через Pin data в Output триггера) — кнопка Open chat сменяется на привычную Execute workflow. n8n больше не ждёт нового сообщения в чате, а гоняет workflow на запиненных данных. Удобно для отладки downstream-нод без необходимости каждый раз писать в чат.

Логика та же что у обычных триггеров — если есть закреплённый тестовый вход, n8n показывает Execute workflow для запуска на нём; если нет — показывает способ получить реальное событие (для Chat Trigger это Open chat, для Webhook — Test URL и т.д.).

Типичные ошибки

• Нажал кнопку, ничего не происходит → в воркфлоу нет триггера. Добавь триггер (для ручных тестов подойдёт Manual Trigger); если триггеров несколько, запусти нужный кнопкой ▶ на самой ноде.
• Нода красная, дальше ничего не выполнилось → клик по ноде → вкладка с ошибкой. Прогон останавливается на первой упавшей ноде.
• На ноде «0 items» и она не выполнилась → предыдущая нода вернула пустой массив. Это не ошибка, это «нечего обрабатывать». Смотри output предыдущей ноды.

Два режима воркфлоу: Unpublished и Published

В n8n у воркфлоу два состояния. Unpublished — черновик: ты редактируешь и можешь запускать его только вручную через Execute workflow, триггеры молчат. Published — живая версия: триггеры включены, Schedule срабатывает по расписанию, Webhook и Form принимают запросы по Production URL, polling-триггеры (Telegram, Gmail) слушают обновления. Переключает между состояниями кнопка Publish в правом верхнем углу редактора.

Version Name и Describe changes — каждая публикация это новая версия

При нажатии Publish n8n показывает диалог с двумя полями:

• Version Name — обязательное короткое имя версии. Любая строка, по которой ты потом узнаешь эту версию в истории. Хорошие примеры: журнал менеджера добавлен, webhook: новая схема заявки, fix: timezone for cron. Плохие: 123, update, асдф — через неделю ты не поймёшь что в этой версии было.
• Describe changes (опционально) — что именно поменялось с прошлой версии. Это короткий журнал в свободной форме: «добавил Stretch-ветку ai-классификации жалоб», «починил Switch L2 — было kebab-case, стало snake_case». Заполняй обязательно для значимых правок — себе через месяц спасибо скажешь.

Каждая публикация создаёт новую версию workflow. История версий доступна через Versions (рядом с Editor/Executions) — можешь посмотреть какой код был на каждой версии, откатиться на любую из них одной кнопкой Restore. Это и есть встроенный git-подобный version control для воркфлоу.

Sub-Workflow тоже публикуют

Воркфлоу, который вызывается из другого через Execute Workflow Trigger, тоже нужно публиковать. Родитель при вызове берёт последнюю опубликованную версию Sub-WF — если ты внёс правки и не нажал Publish, родитель их не увидит. Управляется той же кнопкой Publish.

Типичные ошибки

• Поправил опубликованный воркфлоу, забыл Publish заново → триггеры исполняют старую версию. После каждой правки — Publish.
• Дёргаешь Production URL у Unpublished воркфлоу → возвращает 404. Либо публикуй, либо открой редактор, нажми Execute workflow и шли на Test URL.
• Хочешь временно остановить воркфлоу → нажми Unpublish. Триггеры замолкают, Production URL перестаёт принимать запросы. Чтобы запустить обратно — снова Publish.

Update — обёртка одного события от Telegram

Объект Update приходит от Telegram Bot API каждый раз, когда происходит событие: новое сообщение, редактирование, нажатие кнопки. Внутри всегда лежит поле update_id и ровно одно поле с полезной нагрузкой.

update_id — это последовательный номер события. Каждое новое событие получает следующий номер. Поле нужно только чтобы отслеживать, какие обновления уже обработаны.

Полезная нагрузка может быть разной: message, edited_message, channel_post, callback_query, inline_query и другие. В одном Update присутствует только одно из этих полей.

Как это работает

Самое частое поле — message. Внутри него лежат:

• message_id — уникальный номер сообщения внутри чата
• from — объект User (кто отправил)
• chat — объект Chat (куда сообщение попало)
• date — unix-время
• text, voice, photo, document — в зависимости от типа сообщения

Объект chat содержит:

• id — идентификатор чата
• type — private, group, supergroup или channel
• title, username, first_name — названия и имена

Объект from (User) содержит:

• id — идентификатор пользователя
• is_bot — флаг, бот это или человек
• first_name, username, language_code

В приватном чате chat.id и from.id совпадают. В группе или супергруппе они разные: chat.id — это идентификатор группы, from.id — идентификатор конкретного участника.

Ключ для хранения контекста диалога всегда chat.id. Если использовать from.id, в группе бот начнёт путать пользователей и отвечать не в тот чат.

Поле text существует только у текстовых сообщений. У голосового сообщения его нет — там будет поле voice. Если обратиться к message.text у голосового сообщения, значение будет отсутствовать.

Типичные ошибки

• Перепутал from.id и chat.id — в личке выглядит одинаково, в группе бот отвечает не туда или ведёт себя странно → используй chat.id для ключей памяти.
• Использовал update_id как идентификатор сессии — каждое сообщение даёт новый update_id, память диалога никогда не находит прошлое → бери chat.id.
• Полез в message.text у голосового сообщения — поле отсутствует, выражение возвращает undefined → проверяй тип сообщения перед обращением к text.
• Не учёл chat.type в группе — бот не видит все сообщения из-за privacy mode → либо добавляй @-упоминание, либо отключай privacy mode у BotFather.

Pin Data в n8n: как зафиксировать тестовый вход ноды

Pin Data — это способ «прибить» к ноде заранее заготовленные данные, которые n8n будет подставлять вместо настоящего входа на каждом тестовом запуске. Полезно, когда дёргать реальный источник (внешний воркфлоу, веб-хук, API) на каждое нажатие Execute workflow неудобно или невозможно.

Зачем это нужно

Часто отлаживается не сам триггер, а ноды после него — логика, маппинг, запрос в базу. Чтобы не звать каждый раз источник данных (другой воркфлоу, бот, форму), удобнее один раз получить пример настоящего входа, зафиксировать его на триггере и потом крутить запуски сколько нужно.

Поэтому Pin Data — это инструмент разработчика на этапе сборки, не часть рабочего воркфлоу. В боевом режиме закреплённые данные перестают использоваться: n8n берёт реальный вход.

Как это работает

К любой ноде с выходом можно прикрепить «запинённый» JSON. После этого:

• При запуске воркфлоу через UI (Execute workflow, тестовый прогон) n8n не вызывает саму ноду, а сразу выдаёт следующим нодам зафиксированные данные.
• Pin Data привязана к конкретной ноде, не к workflow целиком — можно запинить триггер и оставить остальные ноды живыми.
• На холсте у запинённой ноды появляется визуальный значок (булавка/иконка), чтобы не забыть, что данные «искусственные».

Удобнее всего пинить триггер: на нём поле выхода — то, что в боевом режиме приходит снаружи (Telegram-апдейт, тело веб-хука, поля Execute Workflow Trigger). Тестовый JSON собирают с теми же ключами, что отдаёт реальный источник.

Типичные ошибки

• Забыли про пин при отладке — в редакторе тестовые прогоны идут по закреплённым данным, а не по реальным, поэтому новый вход «не доходит». Боевому запуску пин не мешает, но перед проверкой на живых данных его лучше снять.
• Структура запинённого JSON не совпадает с реальным — отладка проходит идеально, но в проде ломается на полях, которых не было в тестовом примере; делайте пин из реальной execution, а не «на глаз».
• Запинили середину воркфлоу, забыли — переименовали поле в ноде до пина, а пин остался со старой структурой. Следующие ноды читают «фантомные» данные.
• Pin Data перепутали с переменными среды — пин не передаётся между воркфлоу и не сохраняется при экспорте на другую инсталляцию n8n как «конфиг»; это именно отладочный фиксаж.

Когда не подходит

Pin Data не заменяет настоящие тесты — это удобство в редакторе, не автоматизация. Если нужна повторяемая проверка с разными входами, лучше делать отдельный тестовый workflow или мини-набор тест-кейсов; пин подходит, когда хочется быстро прогнать «один и тот же» сценарий N раз.

AI-нода как маршрутизатор потока

AI-нода может принимать произвольный текст на вход и возвращать одну из заранее заданных категорий. В этом режиме она работает как фильтр: текст уходит в ту ветку, которую выбрала модель.

Такой подход нужен, когда семантику сложно описать условиями If. Достаточно двух-семи категорий, а цена ошибки не критична — тогда AI-фильтр даёт простой и гибкий маршрутизатор.

Как это работает

Есть три способа собрать такой фильтр.

Первый — кластерная нода Sentiment Analysis или Text Classifier. У неё сразу несколько выходов (Positive, Neutral, Negative и т. д.). После ноды If ставить не нужно: поток уже разошёлся по нужным веткам.

Второй способ — AI Agent + Switch. Агент возвращает категорию в поле, а Switch по этому полю направляет item дальше.

Третий — нода Guardrails в режиме Check Text for Violations. Категорий у неё две: выход Pass — нарушений нет, выход Fail — сработала хотя бы одна проверка. Правило можно выбрать из встроенных или описать словами в проверке Custom. Так проверяют и сообщение покупателя до нейросети, и готовый ответ нейросети до отправки.

Кластерная нода требует подключённой sub-ноды OpenAI Chat Model. Коннектор Model находится снизу ноды. В параметре Sampling Temperature (или Temperature) можно поставить 0 — так модель реже отправляет один и тот же текст в разные ветки. Полностью разброс это не убирает: на пересекающихся категориях модель всё равно путается, и лечится это описаниями категорий, а не температурой.

Типичные ошибки

• Поставил AI-фильтр перед удалением сообщения без буфера → ошибочная категория удалит нужный текст → добавь ветку в карантин и удаляй только после второго прохода.
• Задал 20 категорий «на вырост» → модель путает близкие варианты → оставь 3–5 крупных категорий, дроби при необходимости.
• Один и тот же текст уходит то в одну ветку, то в другую → категории пересекаются по смыслу → разведи их описания или слей в одну; Sampling Temperature = 0 уменьшает разброс, но не убирает его.
• Нет лога «текст → категория» → невозможно понять точность фильтра → пиши пары в Data table.

Нода-«сортировщик» на базе LLM

Text Classifier берёт входной текст, спрашивает у языковой модели «к какой из этих категорий он относится», и отправляет item в соответствующий выход. Каждая категория — отдельный выход ноды, поэтому она автоматически ветвит поток без IF и Switch. Никакого обучения и датасетов — решение принимает та модель, которую ты подключаешь сабнодой.

Как это работает

Конфигурация ноды состоит из трёх частей:

Когда item приходит на вход, нода под капотом собирает один промпт: системная инструкция «отнеси текст к одной из категорий» + список категорий с описаниями + сам входной текст. Модель отвечает JSON с отметкой на каждую категорию и полем fallback — «ни одна не подошла», например {"request":true,"spam":false,"fallback":false}. Нода направляет item в выход отмеченной категории. Сам item она не меняет: поля с категорией в нём не появляется, категорию выражает только выход. Каждый выход — это отдельная ветка workflow, как у Switch.

Дополнительные опции

В Options есть две полезные настройки:

• Allow Multiple Classes To Be True — модель может выбрать сразу несколько категорий. Тогда один item уйдёт сразу в несколько выходов. Полезно для тегов, бесполезно для маршрутизации «один-в-один».
• When No Clear Match — что делать, если модель не отнесла текст ни к одной категории. По умолчанию стоит Discard Item: такой item молча пропадает, выполнение при этом завершается без ошибки. Значение Output on Extra, 'Other' Branch добавляет ноде ещё один выход — Other, и непонятные items уходят туда.

Типичные ошибки

• Слишком короткое описание категории (spam — спам) → модель угадывает по имени категории и путается на близких темах → расширь описание примерами: «рекламные рассылки, фишинг, ссылки на крипту».
• Перекрывающиеся категории (support и complaints без чёткой границы) → модель выбирает то одно, то другое на похожих текстах → в описании каждой явно укажи, что туда не входит.
• Не подключена Chat Model → нода падает с ошибкой про отсутствие language model → проверь, что снизу к ноде прицеплена сабнода Chat Model и у неё валидный credential.
• Оставили When No Clear Match = Discard Item → сообщения, не подходящие ни под одну категорию, теряются молча → выбери Output on Extra, 'Other' Branch и подключи выход Other к ноде, которая их сохранит.
• У модели включён переключатель Use Responses API при работе через школьный прокси → нода падает на каждом элементе, а если разрешить ей продолжать после ошибки, упавшие элементы уходят в первую категорию → выключи переключатель в параметрах модели.

Что такое expression

В n8n expression — это маленький кусочек кода в фигурных скобках, который динамически подставляет значение в поле ноды. Записывается так:

{{ <выражение> }}

В поле интерфейса = перед выражением писать не нужно: поле в режиме Expression уже трактует содержимое как выражение, а знак = n8n сам добавляет в файле воркфлоу (JSON) как маркер. Если напечатать = самому, он попадёт в результат текстом (например, сообщение начнётся с «=🚨»). Если поле осталось в режиме Fixed, {{ ... }} запишется как обычный текст.

Внутри {{ }} пишется JavaScript-выражение. Самое частое — чтение значения из другой ноды.

Зачем нужны expressions

Каждое поле в параметрах ноды может быть либо фиксированным значением (например, URL https://api.example.com), либо expression'ом — формулой, которая считается на лету в момент исполнения ноды. Expressions нужны, когда значение зависит от данных, пришедших из предыдущей ноды.

Как читать значения из других нод

Базовая формула: {{ $('<имя_ноды>').item.json.<поле> }}

Разбор по частям:

• $('<имя_ноды>') — обращение к ноде по имени (то, что написано на холсте под нодой). Имя — в одинарных кавычках, точно как на холсте.
• .item — текущий элемент, который обрабатывается. У большинства нод элементов несколько (массив), item берёт тот, что соответствует текущей итерации.
• .json — содержимое поля json элемента (там лежат все данные, которые нода вернула).
• .<поле> — конкретное поле внутри json. Если поле вложенное — пишется через точку: .config.embedding_model.

Пошагово — как вставить expression в поле

1. Наведи курсор на поле и переключи Fixed → Expression в правом верхнем углу поля (или просто начни вводить {{ — поле само перейдёт в режим expression).
2. В появившемся окне (expression builder) — слева список нод воркфлоу, можно кликать по полям и они вставятся в формулу.
3. Справа — preview: видно, какое значение получится прямо сейчас. Если красным — формула или путь к полю некорректные.
4. Закрой окно, поле остаётся в режиме expression (синий фон + иконка fx).

Типичные ошибки

• Имя ноды не совпадает. В формуле $('Get Config') имя должно точно совпадать с подписью ноды на холсте. Если переименовал ноду — старые expressions, ссылающиеся на неё, сломаются.
• Путь к полю не существует. .item.json.embedding_dimensions упадёт с undefined, если у элемента такого поля нет. Проверка — посмотри preview в expression builder, он сразу показывает значение или ошибку.
• Поле осталось в режиме Fixed. Самая частая ошибка — описана в callout выше.
• Кавычки внутри {{ }}. Внутри expression строки оборачиваются одинарными кавычками: {{ 'Hello ' + $json.name }}; двойные тоже работают. Поля с кириллицей и пробелами читаются как $json["Имя"].

Когда expression не нужен

Иногда поле должно быть фиксированным. Например, метод HTTP-запроса (GET / POST) или имя коллекции, которое одинаково для всего воркфлоу — нет смысла читать его динамически. Простое правило: если значение меняется от итерации к итерации или зависит от пришедших данных — нужен expression; если значение постоянное — оставляй фиксированным.

Перетаскивание полей из Input panel

Когда нужно подставить значение из предыдущей ноды в параметр текущей, не пиши выражение вручную. Открой ноду двойным кликом. Слева откроется Input panel с деревом полей предыдущей ноды. Справа — node parameters.

Раскрой нужное поле в Input panel и перетащи его мышкой в parameter's field. n8n сам сформирует выражение и переключит поле из режима Fixed в Expression.

Как это работает

Input panel показывает данные из OUTPUT предыдущей ноды. Данные приходят в виде дерева: каждое поле можно раскрыть до примитива.

После drop в parameter's field появляется выражение в двойных фигурных скобках. n8n поддерживает два формата:

• $json.<field> — когда данные идут напрямую из предыдущей ноды по главной ветке;
• $('<NodeName>').item.json.<field> — когда нужно явно указать имя ноды-источника.

n8n сам определяет нужный item через item linking. Ручной поиск соответствия не требуется.

Поле автоматически окрашивается и переключается в режим Expression. Альтернатива — открыть expressions editor и написать то же выражение вручную. Результат идентичен.

Вложенные поля раскрываются через точку: $json.body.city.

Типичные ошибки

• Перетащил объект-обёртку вместо примитива → в поле уходит [object Object] → раскрой дерево до листа.
• Дропнул в соседнее поле параметра (Text вместо Chat ID) → нода работает не на тех данных → визуально проверь куда легло выражение.
• Переименовал ноду уже после drag-and-drop → expression $('старое имя') сломался → верни старое имя или перепиши выражение вручную.
• Впечатал статичное значение через drag вместо обычного текста → лишнее выражение там где значение не меняется → для констант просто впечатывай текст.
• Тащишь из ноды через ветку которая не выполнялась → expression вернёт undefined → проверь что нужная ветка реально дошла до текущей ноды.

Fixed и Expression — два режима любого поля ноды в n8n

Каждое поле в Parameters любой ноды работает в одном из двух режимов. В режиме Fixed значение отправляется ровно так, как ты его написал. В режиме Expression значение пересчитывается на каждом item по JavaScript-формуле внутри {{ }}.

Переключатель Fixed | Expression находится справа от поля. Слева — кнопка Focus parameter и три точки с пунктом Reset Value. Никакой шестерёнки и пункта Add Expression в n8n v2 уже нет.

Как это работает

Режим Fixed — значение статично. Ты пишешь текст, число или выбираешь опцию из списка, и нода отправит именно это.

Режим Expression — значение динамическое. n8n показывает знак = слева от поля, оранжевую подсветку, блок Result и Item, а также кнопку Edit Expression. Формула выполняется заново для каждого входящего item.

Переключить режим можно двумя способами:

• кликнуть Expression в radiogroup справа от поля;
• перетащить поле из панели Input прямо в целевое поле параметра — n8n сам включит Expression и подставит {{ $json.field }} или {{ $('Имя ноды').item.json.field }}.

Переключатель есть в текстовых полях, выпадающих списках и в resource locator (там он появляется третьим табом).

Выбирай Expression, когда значение зависит от данных или времени. Оставляй Fixed, когда значение всегда одинаковое.

Типичные ошибки

• Написал {{ $json.name }} в режиме Fixed → n8n отправит литеральную строку со скобками → переключи справа на Expression или перетащи поле из Input заново.
• Переключил Expression → Fixed в resource locator → выбранный объект исчез → вернись в Expression и подставь id формулой или заново выбери из From list в Fixed.
• Ищешь шестерёнку слева по старым инструкциям → её нет в n8n v2 → используй radiogroup Fixed | Expression справа от поля.
• Перетащил поле из Input, но режим не сменился → отпустил над зоной Drag input fields here соседнего параметра → отпускай строго над нужным полем.
• Написал формулу без знака = → n8n считает её текстом → кликни Expression справа, тогда = появится автоматически.

Две формы обращения — разница только в источнике

В n8n у одной и той же ноды есть две формы прочитать поле из данных воркфлоу:

{{ $json.business_idea }}
{{ $('Form Trigger').item.json.business_idea }}

Обе достают одно и то же значение, но смотрят в разные места:

• $json — это выход ноды, которая стоит прямо перед текущей. Короткая форма для «возьми поле из предыдущей ноды».
• $('Имя ноды') — это обращение к любой ноде воркфлоу по имени, в том числе к той, что стоит на 2-3-5 шагов раньше.

Когда писать какую

Правило простое:

• Хочешь взять данные у предыдущей ноды (стрелка идёт прямо в текущую) — пиши $json.поле.
• Хочешь дотянуться до ноды глубже по цепочке (между ней и текущей есть промежуточные ноды) — пиши $('Имя ноды').item.json.поле.

Почему короткая форма вообще существует

$json — это просто синоним для $input.item.json, то есть «текущий обрабатываемый элемент входа». А вход текущей ноды формируется из выхода предыдущей. Поэтому $json.поле и $('Предыдущая нода').item.json.поле всегда дают одно и то же значение — пока стрелка идёт напрямую.

$('Имя ноды') нужна там, где короткая форма не справится: между источником и текущей нодой есть промежуточные шаги, которые этого поля уже не передают (например, OpenAI вернул только текст ответа, и поле формы Email к моменту Send Message живёт только в выходе Form Trigger).

Типичные ошибки

• Написал $json.Email в ноде после OpenAI. OpenAI возвращает output, а не Email. Решение — обратиться по имени: $('Form Trigger').item.json['Email'].
• Имя ноды в $('...') не совпадает с подписью на canvas. В expression имя — буквально то, что написано под нодой на canvas. Переименовал ноду — все старые expressions, ссылавшиеся на её прежнее имя, сломаются.
• Забыл .item после имени ноды. Полная форма — $('Имя').item.json.поле. Без .item обращаешься не к данным, а к самой ноде как объекту — поле не найдётся.

Что такое sub-нода

В n8n AI-ноды устроены как «родитель + дети». Родитель — основная нода (AI Agent, Qdrant Insert, Qdrant Vector Store…). Дети — sub-ноды, которые подключаются к специальным кружкам на нижней стороне родителя. Каждая sub-нода — это «поставщик ресурса» для родителя.

Какие бывают sub-ноды

• Embeddings — поставляет векторы (OpenAI / Cohere / Voyage / Google Gemini / bge / …).
• Chat Model — поставляет LLM для AI Agent, Basic LLM Chain и других AI-нод, например Guardrails.
• Document Loader — поставляет «нарезанные» куски документа.
• Text Splitter — внутри Document Loader, разбивает на чанки.
• Memory — поставляет историю диалога для AI Agent.
• Tool — поставляет инструменты, которые AI Agent может вызвать.

Когда родитель запускается (например, Qdrant Insert получил файл и собирается записать его в БД), он по очереди обращается к sub-нодам: «дай мне чанки», «переведи каждый чанк в вектор». Sub-ноды отвечают, родитель собирает результат.

Как выглядит sub-нода в параметрах родителя

Если открыть параметры родителя двойным кликом — справа выезжает панель параметров, а на нижней границе панели видны кружки sub-нод. Подключённая sub-нода показана как круглый цветной индикатор с иконкой провайдера. При наведении — всплывающая подсказка с именем и статусом.

Как заменить sub-ноду

1. Закрой панель параметров родителя (Esc).
2. На canvas найди подключённую sub-ноду — она расположена под родителем. Кликни на ней, нажми Delete (или правый клик → Delete). Sub-нода удалится, у родителя освободится слот.
3. На родителе освободившийся слот покажет «+» (например, Add document embedding). Нажми — справа откроется список доступных sub-нод нужного типа.

1. Выбери нужную sub-ноду — она автоматически подключится к родителю на освободившемся слоте.
2. Заполни параметры новой sub-ноды (credential, модель, режим).

Один URL вместо ключей всех провайдеров

LiteLLM-прокси — это единый шлюз, который принимает запросы в формате OpenAI и пересылает их к разным платным моделям: OpenAI, Anthropic, DeepSeek, Cohere и другим. Студент работает только с одним адресом и одним набором настроек.

Школа поднимает прокси, чтобы все студенты ходили через общий счёт. Школа платит провайдерам по одному договору и видит расход токенов каждого студента по отдельности. Студенту не нужно заводить личные billing-аккаунты и следить за лимитами.

OpenAI-совместимый интерфейс позволяет использовать прокси в n8n и SDK без изменений кода. Ноды и библиотеки отправляют запросы на школьный адрес, а не напрямую на api.openai.com.

Как это работает

В n8n credential OpenAi account указывает Base URL школьного прокси. Все запросы к моделям DeepSeek, Claude и остальным идут через этот credential. Модель указывается в параметре model как обычно.

Прокси не хранит модели у себя. Он только маршрутизирует запросы к внешним API и возвращает ответы. Поэтому он не заменяет self-hosted решения вроде Ollama.

Прямой ключ провайдера нужен только в двух случаях: когда требуется Assistants API или когда нужны параметры, которые прокси ещё не поддерживает. В остальных задачах весь трафик идёт через OpenAi account.

Типичные ошибки

• Считаешь OpenAi account отдельной моделью → запрос уходит не туда → выбирай имя модели из списка, который даёт школа.
• Меняешь значение model на имя из документации провайдера → модель не находится → уточняй у школы, какое имя доступно через прокси.
• Пытаешься вызвать Assistants API через прокси → запрос падает → используй прямой ключ OpenAI.
• Думаешь, что личный ключ запрещён → можно использовать, но по умолчанию весь учебный трафик должен идти через OpenAi account.
• Путаешь прокси с self-hosted моделью → ждёшь, что модели работают без интернета → LiteLLM только пересылает запросы к платным API.

Два эндпоинта к одним моделям

У OpenAI два разных эндпоинта для одних и тех же моделей: /v1/chat/completions и /v1/responses. Оба принимают запросы к gpt-4o и другим моделям, но формат запроса и ответа у них несовместим.

Chat Completions — старый и до сих пор поддерживаемый путь. Responses API — новый интерфейс, который OpenAI рекомендует для агентских сценариев.

Ключевое отличие не в модели, а в том, как ты передаёшь данные и хранишь контекст.

Как это работает

Chat Completions принимает массив messages. В ответе модель возвращает одно сообщение в choices[0].message. Всю историю разговора клиент должен хранить и отправлять заново при каждом запросе.

Responses API использует параметр input — это может быть строка или массив typed items. Поле instructions вынесено отдельно от сообщений. В ответе приходит массив typed output items (message, reasoning, function_call и другие).

Responses поддерживает stateful-цепочки через previous_response_id: OpenAI хранит предыдущие сообщения на своей стороне. Токены предыдущих запросов при этом всё равно учитываются при биллинге.

В Responses встроены инструменты Web Search, File Search и Code Interpreter — их можно включить без написания собственных функций.

В n8n-ноде OpenAI Chat Model есть переключатель Use Responses API, который меняет эндпоинт запроса. Через школьный прокси LiteLLM результат зависит от ноды, к которой подключена модель: AI Agent отвечает в обоих положениях, но с включённым переключателем n8n записывает в выполнение только оценку расхода — tokenUsageEstimate, где токены ответа модели всегда 0; Text Classifier с включённым переключателем падает на каждом элементе. С выключенным переключателем запрос идёт на /v1/chat/completions, и в выполнении виден настоящий расход — блок tokenUsage. Поэтому в задачах школы переключатель выключают всегда.

Это именно разные эндпоинты: формат Chat Completions, отправленный на /v1/responses, не сработает, и наоборот.

Типичные ошибки

• Оставили Use Responses API включённым при работе через школьный LiteLLM-прокси → у AI Agent в выполнении нет настоящего расхода токенов, только оценка с нулём на ответе, а Text Classifier падает на каждом элементе → выключи переключатель.
• Перенесли готовый воркфлоу с прямого OpenAI на прокси и не тронули тоггл → часть нод падает, у остальных пропадает настоящий расход токенов → проверь состояние переключателя в каждой OpenAI-ноде.
• Передали в запрос к /v1/chat/completions поля input, instructions или previous_response_id → ошибка валидации или поля просто игнорируются → используй только массив messages и храни историю на стороне клиента.
• Решили, что Responses API нужен только для новых моделей → gpt-4o доступен по обоим эндпоинтам, разница только в формате → не путай выбор эндпоинта с выбором модели.

Запустить одну ноду, не дёргая весь workflow

Execute step — это кнопка внутри панели ноды (открывается двойным кликом по ноде). По смыслу — младший брат большой кнопки Execute workflow внизу холста: та запускает весь воркфлоу с начала, эта — только текущую ноду. Удобно, когда настраиваешь параметры и хочешь сразу видеть, что отдаёт нода, не перезапуская всю цепочку.

Как это работает

Когда ты жмёшь Execute step, n8n берёт уже существующие данные на входе ноды (output предыдущей ноды из последнего прогона) и прогоняет через эту ноду. Сама нода выполняется реально: HTTP-запрос уходит, запись в базу пишется, письмо отправляется. Это не «сухой прогон», а полноценное выполнение — только одного шага.

Типичный сценарий: запустил весь воркфлоу один раз (Execute workflow), увидел что нода HTTP Request отдаёт не то, поправил поле URL, нажал Execute step — увидел новый результат за секунду. Предыдущие ноды повторно не выполнялись.

Типичные ошибки

• Жать Execute step на ноде, у которой ещё не было входных данных → «No input data», нода не запустится. Сначала прогони весь воркфлоу через Execute workflow или хотя бы триггер вручную, чтобы у каждой ноды появился output.
• Использовать Execute step для проверки изменений в предыдущих нодах → текущая нода работает со старым output, изменения не подхватятся. Если поправил предыдущую ноду — перезапусти её, а потом уже текущую.
• Тестировать ноду с побочным эффектом (запись в БД, отправка письма) на проде → каждый клик создаёт реальную запись. Использовать тестовый credential или временно подменять параметры на безопасные.

Три типа нод в n8n

Любая нода в n8n относится к одному из трёх типов: триггер, действие или sub-нода. Разница — в том, как нода включается в воркфлоу и какую роль играет в его исполнении. Понимание этой таксономии экономит время при сборке: сразу видно, что куда подключать.

1. Триггер — стартовая нода воркфлоу

Триггер запускает воркфлоу. У него нет входа слева, только выход справа. В воркфлоу триггер всегда первый и обычно один (исключения — несколько триггеров под разные источники запуска).

Примеры: Manual Trigger (запуск кнопкой Execute), Schedule Trigger (по расписанию), Webhook (по HTTP-запросу извне), Execute Workflow Trigger (запуск из другого воркфлоу), Telegram Trigger (новое сообщение в боте).

2. Действие — основная рабочая нода

Действие — нода, которая что-то делает с данными: запрашивает API, читает БД, трансформирует JSON, отправляет сообщение. У неё есть вход слева и выход справа. Действий в воркфлоу обычно много, они выстраиваются в цепочку после триггера.

Примеры: HTTP Request, Postgres, Set, Code, IF, Merge, Telegram (отправить сообщение), OpenAI (вызвать модель). Сюда же относятся AI-родители: AI Agent, Qdrant Vector Store, Embeddings-родительский режим — это действия, к которым подключаются sub-ноды снизу.

3. Sub-нода — поставщик ресурса для родителя

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

Примеры: Chat Model OpenAI для AI Agent, Embeddings Cohere для Qdrant Vector Store, Postgres Chat Memory для AI Agent, любая нода в режиме «as Tool».

Детали про sub-ноды — в отдельной шпаргалке «Что такое sub-нода в n8n и как её заменить».

Telegram: куда отвечать — в chat.id или from.id

В объекте Message от Telegram Trigger приходят два разных идентификатора: message.chat.id и message.from.id. Они совпадают только в личных чатах, а в группах и каналах ведут себя по-разному. От правильного выбора зависит, получит ли бот ответ и сохранится ли контекст разговора.

chat.id — это идентификатор места, куда отправлено сообщение. from.id — идентификатор человека, который его написал. В поле Chat ID любой ноды отправки Telegram всегда подставляется chat.id. from.id используют для проверки прав, ведения логов и хранения сессий по пользователю.

В приватном чате значения совпадают. В группе или супергруппе chat.id один на всех, а from.id у каждого участника свой. В каналах поле from обычно пустое, вместо него приходит sender_chat.

Как это работает

• message.chat.id — целевой чат для ответа. В группах и каналах отрицательный: у супергрупп и каналов — с префиксом -100, у обычной группы — просто со знаком минус.
• message.from.id — отправитель. Положительное число, одинаковое для пользователя во всех чатах.
• При отправке сообщения боту в группе chat.id указывает на группу, from.id — на конкретного участника.
• Ключ памяти AI Agent (Session ID = Define below) выбирай по задаче: chat.id — одна история на весь чат (в группе — общая для всех участников), from.id — своя история у каждого человека, и в группе, и в личке. В личном чате оба ключа дают одно и то же.
• Бот не может начать диалог первым: попытка отправить по from.id из группы выдаст Forbidden: bot can't initiate conversation with a user.

Типичные ошибки

• В Chat ID ноды Send Message подставлен {{ $json.message.from.id }} → в личке работает, в группе бот молчит или падает с Forbidden: bot can't initiate conversation with a user → замени на chat.id.
• Ключ памяти бота в группе — chat.id, а бот отвечает каждому участнику про его дела → история общая на всех, и бот приписывает одному человеку то, что рассказал другой → ключ памяти — from.id. Общий контекст группы (бот ведёт один разговор со всеми) — наоборот, chat.id.
• В БД хранят chat.id как идентификатор пользователя → при повторном сообщении из группы пользователь не находится → используй from.id для идентификации человека, chat.id — только для адреса чата.
• Сохраняют отрицательный chat.id группы как id пользователя → логика авторизации ломается, потому что у личных чатов минусов быть не может → разделяй: минус = группа/канал, плюс = пользователь.

Append n8n Attribution: подпись в конце автоматических сообщений

Параметр Append n8n Attribution находится в ноде Telegram. По умолчанию он добавляет в конец каждого отправленного сообщения строку «This message was sent automatically with n8n».

Параметр спрятан: он появляется только после раскрытия Additional Fields. Значение по умолчанию — On, поэтому подпись появляется автоматически, если ничего не менять.

Зачем это нужно

Когда сообщение уходит реальному пользователю, упоминание n8n выглядит как реклама сервиса. Для тестовых и внутренних рассылок подпись иногда полезна — она сразу показывает источник. Для клиентских сообщений её отключают.

Как это работает

Параметр — простой переключатель внутри Additional Fields.

• On (включён) — в конец текста дописывается фраза «This message was sent automatically with n8n».
• Off (выключен, серый) — фраза не добавляется.

Чтобы добраться до переключателя, открой Parameters → Additional Fields → Add Field → выбери Append n8n Attribution.

Типичные ошибки

• Параметр не виден на основном экране → ищут его в Parameters → нужно раскрыть Additional Fields через Add Field.
• Оставили On для реальных пользователей → получатели видят упоминание n8n → переключи в Off, чтобы переключатель стал серым.
• Перепутали с Parse Mode → правят соседний пункт → Parse Mode отвечает за форматирование, а Append n8n Attribution — только за подпись.
• Выключили, но не проверили → подпись осталась → убедись, что переключатель серый.

Edit Output: как поменять запинённые данные на лету

Когда у ноды зафиксированы данные через Pin Data, в панели Output рядом с иконкой булавки появляется ещё одна кнопка — Edit Output (иконка карандаша). Она открывает запинённый JSON прямо в браузере на редактирование: можно поменять значения полей, не отправляя новый запрос во внешний сервис.

Зачем это нужно

Главный сценарий — тестировать одну и ту же цепочку нод на нескольких разных входах. Запинил один пример → отредактировал ему текст → запустил воркфлоу → отредактировал на другой текст → снова запустил. Особенно полезно при отладке роутеров (Switch, IF, Text Classifier) — каждая ветка требует своего набора входных данных, и звать внешний источник под каждый кейс долго.

Как редактировать

1. У ноды с запинёнными данными в панели Output найди кнопку Edit Output (карандаш рядом с булавкой).
2. JSON в панели станет редактируемым полем — впиши новые значения или поменяй существующие.
3. Нажми Save (или клик за пределами поля). Новые данные останутся запинёнными до следующего редактирования или снятия пина.

Что важно

• Не ломай структуру JSON случайно. Если случайно удалить нужное поле или сломать вложенность, следующие ноды получат не те данные и упадут с ошибкой cannot read properties of undefined. Для проверки веток меняй значения, а не ключи. Можно и заменить пример целиком готовыми данными с другим составом полей — тогда проверь, что следующие ноды читают поля, которые в нём есть.
• Меняй только то, что должно поменяться. Для тестирования ветки роутера обычно достаточно подменить одно поле (например, message.text) — всё остальное оставить.
• Edit Output не вызывает реальный источник. Это локальное редактирование пина в браузере, никакого запроса в Telegram / API / другую систему n8n не делает.
• Чтобы вернуться к настоящим данным от триггера — сними пин и поймай новый event через Execute workflow.