npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@rlquilez/n8n-nodes-openai-litellm

v1.0.22

Published

n8n community node: OpenAI-compatible LLM provider with structured JSON metadata injection

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

rlquilezrlquilez

Keywords

n8n-community-node-packagelangchainopenailitellm

Readme

🚀 n8n-nodes-openai-litellm

A simplified n8n community node for OpenAI-compatible LLM providers with advanced structured JSON metadata injection capabilities.

npm version License: MIT n8n Community Node

🙏 Credits

This project is based on the excellent work by rorubyy and their original n8n-nodes-openai-langfuse project. This version has been simplified and refocused to provide a clean, dependency-free solution for structured JSON metadata injection with OpenAI-compatible providers.

Special thanks to rorubyy for the foundation and inspiration! 🎉

✨ Key Features

🎯 Universal Compatibility

  • Full support for OpenAI-compatible chat models (gpt-4o, gpt-4o-mini, o1-preview, etc.)
  • Seamless integration with LiteLLM and other OpenAI-compatible providers
  • Works with Azure OpenAI, LocalAI, and custom APIs

🔧 Structured Metadata Injection

  • Inject custom JSON data directly into your LLM requests
  • Add structured context for tracking and analysis
  • Flexible metadata for projects, environments, workflows, and more

⚡ Simplified Architecture

  • No external tracing dependencies
  • Quick and easy setup
  • Optimized for performance and reliability

📦 NPM Package: @rlquilez/n8n-nodes-openai-litellm

🏢 About n8n: n8n is a fair-code licensed workflow automation platform.

📋 Table of Contents

🚀 Installation

Follow the official installation guide for n8n community nodes.

🎯 Community Nodes (Recommended)

For n8n v0.187+, install directly from the UI:

  1. Go to Settings → Community Nodes
  2. Click Install
  3. Enter @rlquilez/n8n-nodes-openai-litellm in the "Enter npm package name" field
  4. Accept the risks of using community nodes
  5. Select Install

🐳 Docker Installation (Recommended for Production)

A pre-configured Docker setup is available in the docker/ directory:

  1. Clone the repository and navigate to the docker/ directory

    git clone https://github.com/rlquilez/n8n-nodes-openai-litellm.git
cd n8n-nodes-openai-litellm/docker

  2. Build the Docker image

    docker build -t n8n-openai-litellm .

  3. Run the container

    docker run -it -p 5678:5678 n8n-openai-litellm

You can now access n8n at http://localhost:5678

⚙️ Manual Installation

For a standard installation without Docker:

# Go to your n8n installation directory
cd ~/.n8n 

# Install the node
npm install @rlquilez/n8n-nodes-openai-litellm

# Restart n8n to apply the node
n8n start

🔐 Credentials

This credential is used to authenticate your OpenAI-compatible LLM endpoint.

OpenAI Settings

| Field | Description | Example | |-------|-------------|---------| | OpenAI API Key | Your API key for accessing the OpenAI-compatible endpoint | sk-abc123... | | OpenAI Organization ID | (Optional) Your OpenAI organization ID, if required | org-xyz789 | | OpenAI Base URL | Full URL to your OpenAI-compatible endpoint | default: https://api.openai.com/v1 |

💡 LiteLLM Compatibility: You can use this node with LiteLLM by setting the Base URL to your LiteLLM proxy endpoint (e.g., http://localhost:4000/v1).

✅ After saving the credential, you're ready to use the node with structured JSON metadata injection.

⚙️ Configuration

This node allows you to inject structured JSON metadata into your OpenAI requests, providing additional context for your model calls.

🎯 JSON Metadata

Supported Fields

| Field | Type | Description | |-------|------|-------------| | Custom Metadata (JSON) | object | Custom JSON object with additional context (e.g., project, env, workflow) | | Session ID | string | Used for trace grouping and session management | | User ID | string | Optional: for trace attribution and user identification |

🧪 Configuration Example

| Input Field | Example Value | |-------------|---------------| | Custom Metadata (JSON) | See example below | | Session ID | default-session-id | | User ID | user-123 |

{
  "project": "example-project",
  "env": "dev",
  "workflow": "main-flow",
  "version": "1.0.0",
  "tags": ["ai", "automation"]
}

💡 How It Works

The node uses LiteLLM-compatible metadata transmission through the extraBody.metadata parameter, ensuring proper integration with LiteLLM proxies and observability tools.

Metadata Flow:

  1. Session ID and User ID are automatically added to the custom metadata
  2. All metadata is transmitted via LiteLLM's standard extraBody.metadata parameter
  3. Compatible with LiteLLM logging, Langfuse, and other observability platforms
  4. Maintains full compatibility with OpenAI-compatible endpoints

Common Use Cases:

  • Session Management: Track conversations across multiple interactions
  • User Attribution: Associate requests with specific users
  • Project Tracking: Identify which project generated the request
  • Environment Control: Differentiate between dev, staging, and production
  • Workflow Analysis: Track performance by workflow type
  • Debugging: Add unique identifiers for debugging purposes
  • Observability: Integration with Langfuse, LiteLLM logging, and custom analytics

🔧 Compatibility

  • Minimum n8n version: 1.0.0 or higher
  • Compatible with:
    • Official OpenAI API
    • Any OpenAI-compatible LLM (e.g., via LiteLLM, LocalAI, Azure OpenAI)
    • All providers that support OpenAI-compatible endpoints

Tested Models

✅ OpenAI Models:

  • gpt-4o, gpt-4o-mini
  • gpt-4-turbo, gpt-4
  • gpt-3.5-turbo
  • o1-preview, o1-mini

✅ Compatible Providers:

  • LiteLLM - Proxy for 100+ LLMs
  • Azure OpenAI - Microsoft's enterprise API
  • LocalAI - Self-hosted local LLMs
  • Ollama - Local models via OpenAI-compatible API

📚 Resources

Official Documentation

Useful Links

🔗 LiteLLM + Langfuse Configuration

To use this node with LiteLLM and Langfuse for observability, you need to configure your LiteLLM proxy properly:

1. LiteLLM Configuration (config.yaml)

model_list:
  - model_name: gpt-4o-mini
    litellm_params:
      model: gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY

litellm_settings:
  success_callback: ["langfuse"]  # Enable Langfuse logging
  
# Langfuse environment variables (set these in your environment)
# LANGFUSE_PUBLIC_KEY=pk-xxx
# LANGFUSE_SECRET_KEY=sk-xxx  
# LANGFUSE_HOST=https://cloud.langfuse.com (or your self-hosted URL)

2. Environment Variables

Set these environment variables where you run LiteLLM:

export LANGFUSE_PUBLIC_KEY="pk-xxx"
export LANGFUSE_SECRET_KEY="sk-xxx"
export LANGFUSE_HOST="https://cloud.langfuse.com"
export OPENAI_API_KEY="sk-xxx"

3. Start LiteLLM Proxy

litellm --config config.yaml --port 4000

4. Configure n8n Node

  • Base URL: http://localhost:4000 (or your LiteLLM proxy URL)
  • API Key: Any value (LiteLLM will use the configured API key)
  • Metadata: Will be automatically forwarded to Langfuse with fields like:
    • langfuse_user_id (from User ID field)
    • langfuse_session_id (from Session ID field)
    • Custom metadata from JSON field

📈 Version History

v1.0.15 - Current

  • 🔧 Fixed LiteLLM + Langfuse integration - Changed metadata format to work correctly with LiteLLM proxy
  • ✅ Proper Langfuse fields - Added langfuse_user_id and langfuse_session_id for proper trace attribution
  • 🎯 Simplified approach - Removed complex extra_body approach in favor of direct metadata field
  • 📚 Enhanced documentation - Added comprehensive LiteLLM + Langfuse configuration guide

v1.0.14

  • 🔧 Enhanced metadata transmission - Added dual approach with both direct extra_body and modelKwargs.extra_body for maximum compatibility
  • 📊 Improved logging - Enhanced console logging to show both extra_body and modelKwargs configuration

v1.0.13

  • 🔧 Multiple transmission approaches - Attempted various methods to ensure metadata reaches LLM endpoint
  • 📊 Enhanced debugging - Added comprehensive logging for troubleshooting

v1.0.12

  • 🔧 Enhanced metadata transmission - Added dual approach with both direct extra_body and modelKwargs.extra_body for maximum compatibility
  • 📊 Improved logging - Enhanced console logging to show both extra_body and modelKwargs configuration
  • 📚 Documentation - Updated README with comprehensive version history and troubleshooting guide

v1.0.11

  • 🔧 Critical Fix: Proper extra_body parameter application - Reorganized ChatOpenAI configuration to prevent options spread from overriding extra_body
  • ✅ Enhanced payload transmission - Ensures metadata is properly included in the request payload to LiteLLM/OpenAI endpoints
  • 📊 Added detailed logging - Better visibility into extra_body configuration for debugging

v1.0.10

  • 📝 Documentation update - Updated version history with v1.0.9 critical fix details

v1.0.9

  • 🔧 Critical Fix: Corrected extra_body parameter name - Fixed extraBody to extra_body to match LangChain ChatOpenAI API specification
  • ✅ Verified metadata transmission - Ensures metadata is properly sent to LiteLLM and OpenAI-compatible endpoints
  • 📚 Based on official documentation - Implementation follows LangChain and LiteLLM examples

v1.0.8

  • 📝 Enhanced documentation - Updated README with detailed metadata features and version history
  • 🎯 Improved use cases - Added comprehensive examples and observability integration details

v1.0.7

  • 🔧 Fixed LiteLLM metadata payload transmission - Implemented proper extra_body.metadata parameter for LiteLLM compatibility
  • 📊 Added Session ID and User ID fields - Separate fields for better trace attribution and session management
  • 🎯 Improved metadata structure - Based on LiteLLM documentation and reference implementation
  • ✅ Enhanced observability - Better integration with Langfuse and LiteLLM logging systems

v1.0.6

  • 🆕 Added Session ID and User ID fields - Separate input fields for better metadata organization
  • 🔧 Improved metadata handling - Enhanced processing and logging of metadata values
  • 📝 Simplified default JSON example - Cleaner default metadata structure

v1.0.5

  • 🔄 Repository synchronization - Updated with latest remote changes
  • 📚 Documentation improvements - Enhanced README and node descriptions

v1.0.2

  • 🔧 Documentation and examples improvements
  • 🎯 Focus on custom JSON metadata injection
  • 📝 Documentation completely rewritten

v1.0.1

  • 🎨 Updated icons to official OpenAI icons from n8n repository
  • 🔧 Minor compatibility fixes

v1.0.0

  • 🎉 Initial release with OpenAI-compatible providers
  • 📊 Structured JSON metadata injection
  • ⚡ Simplified architecture without external tracing dependencies

💝 Contributing

Developed with ❤️ for the n8n community

If this project was helpful, consider giving it a ⭐ on GitHub!