langchain · difficulty ◆◆
default_headers: Custom HTTP Header Injection for OpenRouter
No more monkey-patching httpx for headers
Injecting gateway and tracing headers used to mean monkey-patching your HTTP client.
$ pip install -U langchain-openrouter>=0.2.6What it does
ChatOpenRouter now accepts a default_headers parameter that injects custom HTTP headers into every request sent to the OpenRouter API. Previously this low-level, opt-in hook was missing, forcing you to subclass or monkey-patch the underlying httpx client.
Why it matters
Enterprise setups routinely need headers for API gateway authentication, request tracing (like X-Trace-ID), and multi-tenant routing. With default_headers this is now a first-class constructor parameter: one line of setup, zero monkey-patching.
Example
$ Construct ChatOpenRouter with custom request headers.Your summarised Q3 financials show total revenue of $4.2M,
up 18% YoY, with gross margin holding at 62%. Key wins
included the enterprise tier expansion and reduced churn
in the SMB segment.No header-related warnings should appear; exact text depends on model output.
Common flags
- ChatOpenRouter
- OpenAI-compatible chat model backed by OpenRouter
- default_headers
- Dict of HTTP headers injected into every request
- ChatAnthropic
- Direct Anthropic integration, no header hook
- ChatOpenAI
- Direct OpenAI integration, uses the extra_headers param
History
Origin
Injecting custom headers previously required subclassing or patching the httpx client, a fragile pattern in production.
The fix
PR #36582 added the default_headers parameter as a first-class constructor option on ChatOpenRouter.
Fun facts
Pros & cons
pros
- + First-class header injection
- + Supports gateway auth and tracing
- + Removes monkey-patching
cons
- − OpenRouter-specific
- − Low-level opt-in hook, not automatic
Takeaways
- 1Use default_headers for gateway auth
- 2Verify with httpx logging
- 3Keep secrets out of default headers