Как подключить сторонний API к n8n со своим ключом

Чтобы подключить AI Agent в n8n к стороннему OpenAI-совместимому API, создайте учётные данные типа OpenAI со своим API-ключом и Base URL провайдера, а затем выберите их в подузле OpenAI Chat Model. Провайдер должен поддерживать именно ту модель и те возможности, которые использует ваш сценарий. Одной успешной проверки учётных данных недостаточно.

В этой статье есть JSON сценария без учётных данных: он классифицирует вымышленное обращение об оплате, вызывает инструмент только для чтения и проверяет результат. Провайдером в примере выступает Ofox — издатель этой статьи. Сценарий использует классический AI Agent, а не отдельный интерфейс Agent Builder. Он не оформляет возвраты и не отправляет сообщения.

20 октября 2026 года мы запустили его через серверный CLI n8n 2.43.8, подключив deepseek/deepseek-v4.1-flash-1017 через Ofox. Исправленный запуск завершился успешным ответом инструмента и проверкой итогового результата. При этом в первом запуске сценарий выглядел успешно завершённым, хотя инструмент вернул ошибку. Поэтому в шаблон включён узел проверки. Это небольшой интеграционный тест на синтетических данных, а не доказательство надёжности в продакшене для всех моделей и версий n8n.

Что понадобится перед импортом

Нужны экземпляр n8n с правом редактирования, аккаунт Ofox с доступом к выбранной модели и достаточным балансом, а также разрешение передавать тестовые данные этому провайдеру. Первый сценарий держите отдельно от рабочих процессов. Мы использовали локальную самостоятельную установку; n8n Cloud и Agent Builder не тестировали.

Прежде чем копировать идентификатор модели, проверьте актуальный каталог моделей Ofox. Наличие записи в каталоге означает заявленную доступность, но не подтверждает успешный вызов инструментов из вашего аккаунта. Если выберете другую модель, повторите проверки ниже. Совместимость с OpenAI не означает поддержку каждого эндпоинта OpenAI, встроенного инструмента или формата ответа.

В импортируемом сценарии пять узлов:

Агент подключается к модели через соединение Chat Model, а к Code Tool — через Tool. Основная цепочка выполнения: Manual Trigger → Classify demo ticket → Validate result. Это разные типы соединений: если провести все связи как обычные основные соединения, тот же сценарий не получится.

Импортируйте шаблон и подключите свои учётные данные

1. Скачайте JSON сценария и изучите его перед импортом. В нём есть промпты и JavaScript, но нет API-ключа, ссылки на учётные данные, закреплённого ответа или реальных клиентских данных.
2. Создайте пустой сценарий в n8n, откройте его меню и выберите Import from File. Укажите скачанный JSON. n8n также поддерживает импорт по URL; доступные способы описаны в документации по экспорту и импорту.
3. Откройте Ofox Chat Model. В поле учётных данных создайте запись типа OpenAI. Этот тип обозначает совместимый интерфейс: ключ не обязательно должен быть выдан OpenAI.
4. Создайте или скопируйте ключ Ofox на странице API Keys. Вставьте его в API Key, а в Base URL укажите https://api.ofox.io/v1. В этом примере оставьте Organization ID пустым. Сохраните учётные данные и выберите их в узле модели.
5. Оставляйте ID deepseek/deepseek-v4.1-flash-1017 только в том случае, если модель по-прежнему доступна вашему аккаунту. Если интерфейс предлагает режим выбора модели, укажите точный ID, а не отображаемое имя. После изменения проверьте сохранённое значение.
6. Для этого шаблона оставьте Use Responses API выключенным: проверялся маршрут Chat Completions. Для первоначальной проверки сохраните Maximum Number of Tokens равным 2048, Timeout — 60000 миллисекунд, Max Retries — 0, а Max Iterations у агента — 3.

Скриншот с английским интерфейсом из нашего предыдущего руководства по учётным данным n8n показывает, куда вводить Base URL. Это не снимок запуска от 20 октября и не доказательство успешного выполнения этого сценария. Названия полей могут отличаться в разных версиях n8n; подтверждение текущего теста — данные выполнения через серверный CLI, описанные ниже.

Не вставляйте полный адрес операции /chat/completions в поле, которое ожидает корневой адрес API, и не добавляйте /v1 дважды. Если проверка учётных данных проходит, а сценарий возвращает 404, воспользуйтесь отдельным руководством по ошибкам Base URL в n8n. Здесь разбирается полноценная задача с проверкой результата, а не повторная диагностика маршрута.

В документации OpenAI Chat Model разграничены Chat Completions и Responses. Отключая Responses в этом примере, вы выбираете проверенный нами маршрут. Это не универсальное исправление ошибок схемы, ответов 403 или неподдерживаемых инструментов. Обычный локальный Code Tool в шаблоне также отличается от встроенных инструментов OpenAI для веб-поиска или поиска по файлам.

Запустите обработку обращения и проверьте оба результата

Входные данные намеренно простые:

Request ID: DEMO-1020
Message: I was charged USD 19.50 twice.
I have not supplied a payment ID.

Сначала агент должен вызвать lookup_demo_ticket, передав request_id со значением DEMO-1020. Инструмент не обращается к реальному аккаунту: его JavaScript возвращает фиксированные локальные тестовые данные:

{"request_id":"DEMO-1020","payment_id_present":false}

Инструмент позволяет проверить полный цикл: модель выбирает инструмент, n8n выполняет его, затем модель получает результат и отвечает. В рабочем сценарии вместо фиксированных данных понадобится реальный запрос с соответствующими правами доступа. Этот пример не подтверждает работоспособность произвольного коннектора CRM или платёжной системы.

Не активируя сценарий, нажмите Execute workflow для ручного запуска. Импорт и текущее выполнение проверены через серверный CLI. Инструкции для редактора опираются на документированный способ импорта n8n и сохранённую конфигурацию узлов; отдельного теста интерфейса Cloud не было.

Посмотрите результат Classify demo ticket. Он должен содержать JSON ровно с такими полями и значениями:

{
  "request_id": "DEMO-1020",
  "category": "billing",
  "amount": 19.5,
  "currency": "USD",
  "action": "request_payment_id"
}

Проверьте и промежуточные шаги. Совпадения имени инструмента недостаточно: в его результате, поле observation, должны быть ID тестового обращения и payment_id_present: false, без ошибки. В шаблоне включён параметр Return Intermediate Steps, чтобы последний узел мог это проверить.

Затем откройте Validate result. При успешной проверке он возвращает те же бизнес-поля, а также validated: true и tool_verified: true. Лишние поля, неправильное действие, некорректный JSON, отсутствие вызова инструмента или ошибка в его результате заставляют узел выбросить исключение. Дальнейшие узлы не отправляют письма и не выполняют запрошенный возврат — таких операций в сценарии нет.

Валидатор намеренно знает правильный ответ для одного конкретного тестового случая. Если изменить только текст обращения, сохранив проверки точных значений, проверка не пройдёт. Перед адаптацией опишите ожидаемые правила для новых случаев, сохраните проверки полей и типов, отдельно протестируйте неизвестные ID и отсутствие данных для поиска. Не разрешайте любой синтаксически корректный JSON только ради зелёного статуса сценария.

Ошибка, которую скрывал первый запуск

В первом локальном запуске модель вызвала инструмент, но в его результате была ошибка:

Received tool input did not match expected schema
Unrecognized key(s) in object: 'toolCallId'

При этом сценарий в целом завершился успешно и выдал ожидаемую классификацию. Первоначальный валидатор проверял факт вызова инструмента, но не получение пригодных данных. Мы признали этот запуск неудачным интеграционным тестом.

В исправленном примере входная схема Code Tool требует строку request_id и допускает дополнительные свойства. Код использует только разрешённый ID обращения и возвращает фиксированные данные; он не пересылает входные параметры другому сервису и ничего не записывает. Так мы учли дополнительное поле, обнаруженное в этой конкретной установленной конфигурации. Схема итогового ответа по-прежнему строгая, а валидатор теперь проверяет и результат инструмента. Не убирайте строгую проверку из рабочего инструмента, выполняющего действия, только ради подавления этой ошибки. Если инструмент меняет данные, сначала разберитесь в поведении узла и среды выполнения и явно определите допустимые входные параметры.

Исправленный запуск потребовал двух вызовов модели: в первом она запросила инструмент, во втором — вернула классификацию после успешного получения данных. n8n зафиксировал 1 019 входных и 101 выходной токен суммарно за два вызова. В отклонённом первом запуске было три вызова. Это зарегистрированное потребление, а не счёт на оплату и не обещание такого же расхода в следующих запусках.

Отдельные локальные тесты подтвердили, что валидатор отклоняет пять отрицательных случаев: некорректный JSON, лишнее поле, неправильное действие, отсутствие вызова инструмента и ошибку инструмента. Для них использовались синтетические входные данные валидатора; мы не вызывали реальный сбой провайдера, ограничение частоты запросов или ошибку оплаты. Обнаруженное поле toolCallId также не является воспроизведением отдельных сообщений об ошибках схемы get_environment в Agent Builder.

Кто выставляет счёт при использовании собственного ключа

Расходы нужно учитывать отдельно:

При использовании учётных данных Ofox проверяйте журнал запросов и начисления за эту модель в аккаунте Ofox. Не рассчитывайте оплатить вызовы по ключу Ofox балансом n8n Gateway credits. И наоборот: пополнение баланса провайдера не пополняет Gateway credits или Assistant credits в n8n. Документация Gateway credits разграничивает эти балансы и подключение собственных учётных данных.

Наш Code Tool выполняет локальный тестовый код и не отправляет запросов внешним сервисам инструментов. Реальный поиск или сбор данных с сайтов может оплачиваться отдельно. Кроме того, за одно выполнение сценария агент способен вызвать модель несколько раз, что видно по обоим тестовым запускам.

При расчёте бюджета суммируйте входные, выходные и отдельно учитываемые категории кеша по всем вызовам, включая повторы и неудачные попытки, которые создали оплачиваемое потребление. Применяйте тарифы конкретной модели, провайдера и аккаунта, затем добавляйте расходы на внешние инструменты. Не применяйте цену выходных токенов текстовой модели ко всем токенам и не приравнивайте одно выполнение n8n к одному API-запросу. В статье не приводится тариф Ofox и не заявляется измеренная экономия.

Начните с синтетических данных и небольшого бюджета. Пока не поняли причину ошибки, оставляйте повторы выключенными; затем задайте ограниченную политику повторов, подходящую для этой ошибки. Одновременное увеличение числа повторов и итераций агента может умножить количество вызовов, не исправив недействительный ключ или неподдерживаемую схему.

Если импортированный сценарий не работает

Если проблема связана с маршрутизацией или сервисом DeepSeek, перейдите к руководству по ошибкам DeepSeek API и резервному переключению. Резервный вариант должен сохранять нужный протокол, инструменты и требования к результату. Одной замены имени модели недостаточно, чтобы считать переход проверенным.

Перед подключением реальной задачи уберите предположения, привязанные к тестовым данным, проверьте доступ к нужным данным и предусмотрите отдельные разрешения и защиту от повторного выполнения для операций записи. Первый результат скромный, но полезный: собственные учётные данные, полный цикл вызова модели и инструмента, ответ, прошедший явные проверки. После этого перенесите те же проверки в рабочий сценарий, опираясь на документацию Ofox по аутентификации и журнал запросов аккаунта.