Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix [Feature]: Add Agent ID header to LLM requests for per-agent usage tracking [1 pull requests, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#50117•Fetched 2026-04-08 00:59:00
View on GitHub
Comments
0
Participants
1
Timeline
3
Reactions
0
Author
stevensiastevensia
Participants
stevensiastevensia
Timeline (top)
cross-referenced ×1labeled ×1referenced ×1

Allow OpenClaw to automatically include an X-OpenClaw-Agent header in LLM API requests, so proxy servers can track usage per-agent.

Root Cause

Allow OpenClaw to automatically include an X-OpenClaw-Agent header in LLM API requests, so proxy servers can track usage per-agent.

Fix Action

Fix / Workaround

Current workaround: Create separate provider configs per agent with static headers - doesn't scale.

PR fix notes

PR #50206: feat: add opt-in X-OpenClaw-Agent header for per-agent LLM tracking

Description (problem / solution / changelog)

Summary

Closes #50117

  • Adds injectAgentHeader boolean to ModelProviderConfig so users can opt-in to X-OpenClaw-Agent: <agentId> header injection on outgoing LLM requests
  • Injects via a new createAgentIdHeaderWrapper in the existing applyExtraParamsToAgent pipeline, following the same pattern as Kilocode/OpenRouter header wrappers
  • Only fires when injectAgentHeader: true is set on the matching provider config AND an agentId is present

Config example

models:
  providers:
    my-proxy:
      baseUrl: http://localhost:8080/v1
      injectAgentHeader: true
      models:
        - id: gpt-4o
          name: GPT-4o

Every request to my-proxy will include X-OpenClaw-Agent: main (or whichever agent ID is active).

Files changed

FileChange
src/config/types.models.ts+1: type field
src/config/zod-schema.core.ts+1: Zod schema
src/config/schema.labels.ts+1: label
src/config/schema.help.ts+2: help text
src/agents/pi-embedded-runner/extra-params.ts+20: wrapper + wiring
src/agents/pi-embedded-runner/extra-params.test-support.ts+2: agentId passthrough
src/agents/pi-embedded-runner/extra-params.agent-header.test.tsNEW: 6 tests

Test plan

  • pnpm tsgo — no new type errors
  • New test file passes (6/6): injects header, skips when disabled/missing agentId/false/wrong provider, overrides caller-supplied header
  • Existing extra-params tests unaffected (kilocode, cache-retention, xai-tool-payload all pass)
  • pnpm format clean

🤖 Generated with Claude Code

Changed files

  • src/agents/pi-embedded-runner/extra-params.agent-header.test.ts (added, +99/-0)
  • src/agents/pi-embedded-runner/extra-params.test-support.ts (modified, +2/-0)
  • src/agents/pi-embedded-runner/extra-params.ts (modified, +20/-0)
  • src/config/schema.help.ts (modified, +2/-0)
  • src/config/schema.labels.ts (modified, +1/-0)
  • src/config/types.models.ts (modified, +1/-0)
  • src/config/zod-schema.core.ts (modified, +1/-0)
RAW_BUFFERClick to expand / collapse

Summary

Summary

Allow OpenClaw to automatically include an X-OpenClaw-Agent header in LLM API requests, so proxy servers can track usage per-agent.

Problem to solve

Use Case

When running multiple agents (main, grace, commander, etc.) through a local LLM proxy for usage tracking, there's no way to distinguish which agent made each request.

Current workaround: Create separate provider configs per agent with static headers - doesn't scale.

Proposed solution

Proposed Solution

Add agent ID to outgoing requests as HTTP header: X-OpenClaw-Agent: main

This enables:

  • Per-agent usage tracking
  • Cost allocation
  • Audit trails

Context

  • Multiple agents (Telegram, WhatsApp, etc.)
  • Local proxy with usage dashboard
  • Current user-agent only shows OpenAI/JS 6.26.0 for all

Suggestion

Could be opt-in:

models:
  providers:
    my-proxy:
      injectAgentHeader: true

### Alternatives considered

_No response_

### Impact

no

### Evidence/examples

_No response_

### Additional information

_No response_

extent analysis

Fix Plan

To add an X-OpenClaw-Agent header to LLM API requests, follow these steps:

  • Update the provider configuration to include an injectAgentHeader option
  • Modify the request logic to include the agent ID in the X-OpenClaw-Agent header

Example code:

import requests

def send_llm_request(agent_id, provider_config, request_data):
    # Check if injectAgentHeader is enabled
    if provider_config.get('injectAgentHeader', False):
        # Add X-OpenClaw-Agent header with agent ID
        headers = {'X-OpenClaw-Agent': agent_id}
        response = requests.post(provider_config['url'], json=request_data, headers=headers)
    else:
        response = requests.post(provider_config['url'], json=request_data)
    return response

# Example usage:
provider_config = {
    'url': 'https://my-proxy.com/llm',
    'injectAgentHeader': True
}
agent_id = 'main'
request_data = {'prompt': 'Hello, world!'}
response = send_llm_request(agent_id, provider_config, request_data)

Verification

To verify that the fix worked, check the proxy server logs for the presence of the X-OpenClaw-Agent header in incoming requests. You can also use a tool like curl to inspect the headers sent by the client:

curl -X POST \
  https://my-proxy.com/llm \
  -H 'Content-Type: application/json' \
  -H 'X-OpenClaw-Agent: main' \
  -d '{"prompt": "Hello, world!"}'

Check the response headers to ensure that the X-OpenClaw-Agent header is present and correctly set.

Extra Tips

  • Make sure to update the provider configuration to include the injectAgentHeader option.
  • Consider adding error handling to handle cases where the injectAgentHeader option is not enabled or the agent ID is not provided.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#ssr#installation#tensor shape#autograd error#model loading#dependency error#configuration error#environment variable

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING