Summary

Capture upstream LLM API response headers (request-id, x-request-id, trace-id) and propagate them through diagnostic events, OTEL spans, and error logs.

Problem to solve

When an LLM request times out or fails, the lane task error log only contains:

lane task error: lane=main durationMs=25736 error="FailoverError: LLM request timed out."

Upstream LLM providers (Anthropic, OpenAI, etc.) return request-id / x-request-id / trace-id headers that are essential for cross-referencing failures with provider-side diagnostics. Currently these headers are available in buildManagedResponse() but discarded — they are not recorded in logs, not attached to FailoverError, not included in DiagnosticUsageEvent, and not exposed to OTEL spans or plugin diagnostic listeners.

This makes it very difficult to troubleshoot intermittent timeouts or provider-side errors, since there is no correlation key to take to the provider's support/dashboard.

Proposed solution

1. Provider transport streams (anthropic-transport-stream.ts, openai-transport-stream.ts, etc.): extract request-id / x-request-id from SDK response headers and attach to the output metadata.
2. FailoverError: add an optional upstreamRequestId field so timeout/failure logs carry the correlation ID.
3. DiagnosticUsageEvent (model.usage): add an optional upstreamRequestId field.
4. agent-runner.ts: pass the captured ID when emitting model.usage events.
5. Error logging (command-queue.ts): include upstreamRequestId in lane task error when available.
6. diagnostics-otel: record the ID as a span attribute on openclaw.model.usage.

This approach requires no changes to the Plugin SDK transport abstraction, StreamFn signature, or buildGuardedModelFetch return type — it stays within each provider's stream handler and the existing diagnostic event pipeline.

Alternatives considered

• Intercepting at buildGuardedModelFetch level: would require changing the fetch wrapper return type from standard Response to a custom object, breaking the contract with Anthropic/OpenAI SDKs that expect a standard fetch response.
• Exposing raw HTTP Response to plugins via SDK: high-cost change that breaks the intentional transport abstraction boundary. The diagnostic event approach gives plugins the correlation ID without leaking HTTP internals.
• Plugin-side interception: third-party plugins currently cannot access raw HTTP responses by design. Even provider plugins only get the abstract StreamFn, not transport details.

Impact

• Affected: anyone debugging LLM request failures, timeouts, or rate limiting — operators, self-hosters, and plugin authors using OTEL
• Severity: medium — not a blocker, but significantly increases debugging time
• Frequency: every time an LLM request fails or times out (intermittent but recurring)
• Consequence: without upstream request IDs, operators cannot correlate OpenClaw errors with provider-side logs/dashboards, leading to blind troubleshooting and slower incident resolution

Evidence/examples

Current error log with no upstream correlation:

13:40:10 error diagnostic lane task error: lane=main durationMs=25736 error="FailoverError: LLM request timed out."

Desired error log:

13:40:10 error diagnostic lane task error: lane=main durationMs=25736 error="FailoverError: LLM request timed out." upstreamRequestId=req_01J5K...

Anthropic API returns request-id header; OpenAI returns x-request-id. Both are accessible from their respective SDK response objects (stream.response.headers).

Additional information

• The minimax-vlm.ts file already demonstrates the pattern of extracting Trace-Id from response headers for error messages — this proposal generalizes that approach across all providers.
• Change is additive (all new fields are optional) and backward-compatible with existing plugin diagnostic listeners.
• Provider-specific header names can be mapped to a single canonical upstreamRequestId field.