otelHeadersHelper失敗時の警告

動的ヘッダー

動的な認証が必要なエンタープライズ環境向けに、ヘッダーを動的に生成するスクリプトを設定できます。動的ヘッダーが適用されるのは http/protobuf と http/json プロトコルのみです。grpc プロトコルでは、Claude Code は静的ヘッダー用の変数、OTEL_EXPORTER_OTLP_HEADERS とそのシグナルごとのバリアントのみを使用します。

設定方法

.claude/settings.json に、パスを自分のスクリプトに置き換えて追加します。

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

値には、実行可能ファイルへのパス（空白を含むパスも可）、または引数付きのシェルコマンドラインを指定できます。Windows では、この値は常にシェル経由で実行されるため、空白を含むパスは JSON の値の中で引用符で囲んでください。

スクリプトの要件

スクリプトは、HTTP ヘッダーを表す文字列のキーと値のペアからなる、正しい形式の JSON を出力する必要があります。

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

ヘルパーが失敗した場合、またはこれらの要件を満たさない出力を表示した場合、エクスポートは失敗し、ヘルパーが再び動作するまで、そのセッションからテレメトリバックエンドには何も送られません。Claude Code は、この失敗を次の箇所で報告します。

• 対話セッションでの警告通知 otelHeadersHelper failed; telemetry is not being exported（ヘルパーが最初に失敗したときにセッションごとに 1 回表示されます）
• /status の出力
• --debug を付けて実行した場合、またはセッション内で /debug を実行した後のデバッグログ
• -p で開始した非対話セッションでの stderr

更新の挙動

ヘッダーヘルパースクリプトは、起動時と、その後はトークンの更新をサポートするために定期的に実行されます。デフォルトでは、このスクリプトは 29 分ごとに実行されます。この間隔は、CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS 環境変数でカスタマイズできます。