Feature Request: Reconsider dynamic custom request headers in OpenAI API Compatible provider — now required by OpenCode Go

[sevenjay]

Self Checks

• I have read the Contributing Guide and Language Policy.
• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report, otherwise it will be closed.
• Please do not modify this template :) and fill in all the required fields.

1. Is this request related to a challenge you're experiencing? Tell me about your story.

I would like to ask the team to reconsider, and if appropriate reopen, the previous request for supporting custom HTTP request headers in the OpenAI API Compatible provider.

Related issue: #3012

This has recently become more important because this is no longer only a customization or optimization use case.

OpenCode Go now requires clients to provide a stable session identifier for each conversation via the x-opencode-session request header. Requests without a session ID may fail, and users are already reporting HTTP 400 MissingSessionID errors.

This means that, for Dify users who want to use OpenCode Go through the OpenAI API Compatible provider, dynamic custom headers are effectively required for the integration to work correctly.

OpenCode Go requirement

OpenCode Go's documentation requires clients to send a stable session ID for every conversation:

x-opencode-session: <stable-session-id>

The session ID must remain stable for all requests belonging to the same conversation.

This is used by OpenCode Go for:

• session-aware routing
• provider affinity
• prompt caching
• request optimization

OpenCode Go has also started enforcing this requirement. Requests without the session header can now fail with an error such as:

400 MissingSessionID
Request is missing x-opencode-session and cannot be routed efficiently.

Therefore, this is no longer simply a request to support arbitrary vendor-specific metadata.

For OpenCode Go, the lack of dynamic request-header support can make the Dify OpenAI API Compatible provider unusable.

Dify already has the ideal session identifier

Dify already provides:

{{#sys.conversation_id#}}

This value is exactly what is needed for this use case:

Dify Conversation A
    ↓
sys.conversation_id = abc-123
    ↓
x-opencode-session: abc-123

Next message in Conversation A
    ↓
x-opencode-session: abc-123

New Conversation B
    ↓
sys.conversation_id = def-456
    ↓
x-opencode-session: def-456

So ideally, the OpenAI API Compatible provider could expose a model parameter such as:

- name: extra_headers
  type: string
  required: false
  label:
    en_US: Extra Headers

Then the LLM node could configure:

{
  "x-opencode-session": "{{#sys.conversation_id#}}"
}

and Dify would send:

POST /v1/chat/completions
Authorization: Bearer ...
Content-Type: application/json
x-opencode-session: abc-123

Why dynamic headers are important

A static extra_headers configuration would not fully solve this problem.

For OpenCode Go, this would be incorrect:

{
  "x-opencode-session": "one-global-static-id"
}

because unrelated Dify conversations would all appear as the same OpenCode session.

What is needed is the ability to resolve Dify variables at invocation time:

{
  "x-opencode-session": "{{#sys.conversation_id#}}"
}

This allows each Dify conversation to have its own stable session ID.

This is also useful beyond OpenCode Go

Although OpenCode Go is now a concrete case where this functionality is required, generic dynamic request headers would also support many other OpenAI-compatible services that use headers for:

• session affinity
• distributed tracing
• request routing
• tenant identification
• gateway metadata
• cache affinity
• vendor-specific OpenAI-compatible extensions

So I believe supporting this generically in the OpenAI API Compatible provider would be preferable to adding OpenCode-specific logic.

2. Additional context or comments

Current workarounds

Without this functionality, Dify users currently need to:

1. fork and modify the OpenAI API Compatible provider plugin,
2. implement a custom provider plugin,
3. put a custom reverse proxy between Dify and OpenCode Go, or
4. stop using the LLM node and manually invoke the API through an HTTP Request node.

These are significant workarounds for an API that is otherwise OpenAI-compatible.

In particular, using an HTTP Request node means losing much of the functionality normally provided by the Dify LLM node.

Why this may be worth reconsidering now

My understanding is that newer Dify versions already support resolving workflow/system variables in string-type model parameters.

Therefore, Dify now appears to have most of the infrastructure required for this use case.

The missing piece is allowing the OpenAI API Compatible provider to expose an extra_headers (or equivalent) parameter and forward those resolved headers to the underlying OpenAI-compatible request.

Conceptually:

Dify LLM Node
      │
      │ {{#sys.conversation_id#}}
      ▼
extra_headers
      │
      ▼
OpenAI API Compatible Provider
      │
      │ x-opencode-session: <conversation_id>
      ▼
OpenCode Go

Requested behavior

It would be great if the OpenAI API Compatible provider could support something like:

Extra Headers:

{
  "x-opencode-session": "{{#sys.conversation_id#}}"
}

with Dify resolving the variable for each LLM invocation before passing the headers to the provider.

Why I am asking to reconsider #3012

I understand that the previous custom-header request was closed as not planned.

However, I believe the situation has materially changed:

1. Dify now has support for resolving variables in model parameters.
2. OpenCode Go now requires a stable per-conversation session header.
3. Missing this header can cause actual API requests to fail with HTTP 400 errors.
4. Dify already has sys.conversation_id, which maps naturally to this requirement.
5. The inability to dynamically set this header prevents an otherwise OpenAI-compatible API from being used normally through Dify's LLM node.

For these reasons, could the team please reconsider supporting dynamic custom HTTP headers in the OpenAI API Compatible provider, or reopen #3012 for further discussion?

Thank you!

3. Can you help us with this feature?

• I am interested in contributing to this feature.

[Souravrajvi0]

I've opened a PR for this in #3866.

Approach: expose an extra_headers model parameter on the OpenAI API Compatible LLM provider. Dify resolves variables like {{#sys.conversation_id#}} in model parameters at invocation time; the plugin parses the JSON and forwards the headers on each request.

Example LLM node configuration:

{
  "x-opencode-session": "{{#sys.conversation_id#}}"
}

This works for both Chat Completions and Responses API paths. Model-parameter headers merge with any credential-level extra_headers (model parameter values take precedence on key conflicts).

8 unit tests added and passing.

[Souravrajvi0]

Correction: the PR is #3869 (not #3866).

[DaweiTian]

When will the update for this feature be completed?