Warn when otelHeadersHelper fails

Dynamic headers

For enterprise environments that require dynamic authentication, you can configure a script to generate headers dynamically. Dynamic headers apply only to the http/protobuf and http/json protocols. With the grpc protocol, Claude Code uses only the static headers variables, OTEL_EXPORTER_OTLP_HEADERS and its per-signal variants.

Settings configuration

Add to your .claude/settings.json, replacing the path with your own script:

{
  "otelHeadersHelper": "/path/to/generate-otel-headers.sh"
}

The value can be the path to an executable file, including a path that contains spaces, or a shell command line with arguments. On Windows, the value always runs through the shell, so quote a path that contains spaces inside the JSON value.

Script requirements

The script must output valid JSON with string key-value pairs representing HTTP headers:

#!/bin/bash
# Example: Multiple headers
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

If the helper fails or prints output that doesn't meet these requirements, exports fail and your telemetry backend receives nothing from the session until the helper works again. Claude Code reports the failure in:

• A warning notification in interactive sessions, otelHeadersHelper failed; telemetry is not being exported, shown once per session when the helper first fails
• /status output
• The debug log, when running with --debug or after running /debug in the session
• stderr, in non-interactive sessions started with -p

Refresh behavior

The headers helper script runs at startup and periodically thereafter to support token refresh. By default, the script runs every 29 minutes. Customize the interval with the CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS environment variable.