トラブルシューティング: カスタムOpenAI互換バックエンドでのコンテキストトークン使用量のトラッキングが動作しない

症状

カスタムまたは非標準のOpenAI互換バックエンド（llama-cpp、LM Studio、またはその他のローカル推論サーバーなど）を使用している場合、特定のバージョンにアップグレードした後、以下の症状が発生することがあります。

• ストリーミング応答でトークン使用量が常に0%または0トークンと表示される
• モデルが確かにトークンを消費しているにもかかわらず、コンテキストウィンドウのトラッキングが動作していないように見える
• ストリーミング要求と非ストリーミング要求の間で動作に一貫性がない（非ストリーミング要求では正確な使用量が表示されるが、ストリーミングでは0%が表示される）

この問題は、代替バックエンドからのストリーミング応答にのみ影響し、標準のOpenAI APIエンドポイントでは引き続き正しく使用量が報告されます。

原因

OpenAIトランスポート層の buildOpenAICompletionsParams() 関数は、compat.supportsUsageInStreaming が true と評価された場合にのみ、要求ペイロードに stream_options: { include_usage: true } フィールドを含めていました。

標準のOpenAIエンドポイントでは、この互換性フラグが正しく解決され、ゲートウェイの resolveIncludeUsageForStreaming() 関数が使用量を適切にトラッキングできました。しかし、llama-cpp や LM Studio などのカスタムバックエンドでは、このフラグが false に解決され、フィールドが完全に省略されました。このフィールドが要求に存在しない場合、ゲートウェイが処理できるデータがなくなり、コンテキストトークン使用量が常にゼロと表示されます。

解決手順

v2026.4.19-beta.2 バージョンにアップグレードすると、この問題は自動的に解決されます。設定の変更は不要です。

1. OpenClawパッケージ を v2026.4.19-beta.2 以降にアップグレードします
2. ゲートウェイサービス を再起動して、更新されたトランスポート層を読み込みます
3. 修正を確認する ために、カスタムバックエンドへのストリーミング要求を開始します

検証

修正が機能していることを確認するには：

1. カスタムバックエンド（llama-cpp、LM Studioなど）にストリーミング補完要求を送信します
2. 応答ペイロードを監視して、ストリーミングチャンクに usage フィールドが表示されることを確認します
3. コンテキストトークントラッキングが0%ではなく実際のトークン数を表示することを確認します

// 検証の例: ストリーミング応答に使用量が表示されることを確認
const response = await openai.chat.completions.create({
  model: 'your-model',
  messages: [{ role: 'user', content: 'Hello' }],
  stream: true,
  stream_options: { include_usage: true }  // 常に含まれるようになりました
});

for await (const chunk of response) {
  if (chunk.usage) {
    console.log('使用量がトラッキングされました:', chunk.usage);
  }
}

よくある落とし穴

• プロキシの干渉: 一部のAPIプロキシまたは ミドルウェアが不明なフィールドを要求ペイロードから取り除く可能性があります。カスタムプロキシレイヤーを使用する場合は、stream_options が変更されずにバックエンドに転送されることを確認してください。

• バックエンド固有の設定: フィールドは常に含まれるようになり、サポートしていないバックエンドは安全に無視しますが、古いカスタムバックエンドでは不明なフィールドに遭遇했을 때予期しない動作が発生する場合があります。まずステージング環境でテストしてください。

• 混在環境: 複数のゲートウェイインスタンスが異なるバージョンで実行されている場合、トークントラッキングは 要求間で一貫性がありません。均一な動作を確保するには、すべてのインスタンスを v2026.4.19-beta.2 にアップグレードしてください。

関連するエラー

• コンテキストウィンドウの枯渇が検出されない: 使用量が常に0%であったため、システムはストリーミング要求中にコンテキスト制限に近づいているときに正確に警告を発することができませんでした。
• 使用量レポートの一貫性のなさ: ストリーミングでは常に使用量ゼロを報告していたため、ストリーミングと非ストリーミング要求の使用量メトリクスを比較することができませんでした。

影響を受けるバージョン: v2026.4.19-beta.2 イシュー参照: #68707 変更されたファイル: src/agents/openai-transport-stream.ts, src/agents/openai-transport-stream.test.ts