本ページ： 整合 · 手順 · /v1/models · 排障 · FAQ
OpenClaw ゲートの手前で方針を握り、Helicone で観測する構成の検査点です。経路の対照は LiteLLM 稿、コスト観点は 多モデル料金稿、OpenAI 互換サーバは vLLM 稿、可観測性は OTel GenAI 稿 を参照してください。
狙い
ゲートのルート名と Helicone／ベンダが見る model を一致させ、RPM・TPM・連敗の予算カウンタを Mac 側に残します。観測だけに頼るとソケット詰まり時に手足が遅れます。
ルート整合：どの層がどの文字列を所有するか
| 層 | 所有するもの | 一致させる相手 |
|---|---|---|
| OpenClaw ゲートウェイルート | 安定したルート名やスキル向けエイリアス | Helicone を通過する HTTP クライアントが最終的に送る model 文字列 |
| Helicone フォワーダ | セッション系ヘッダ、キャッシュ属性、プロジェクト鍵 | ベンダの Authorization と許可モデル一覧 |
| 予算サーキット | RPM・TPM・連続 5xx のローリングカウンタ | エージェントへ返す型付き要約（生スタックではない） |
再現手順（OpenClaw 2026.5.x・公式 Getting Started 準拠）
1. 2026.5.x を文書のピン例（openclaw@^2026.5.0 等）で固定し、Node 22 LTS 以上・openclaw doctor 合格後に launchd でループバックのゲートを登録。
2. 上流ベース URL を Helicone の OpenAI 互換フォワーダにし、Authorization にベンダ鍵、Helicone-Auth にプロジェクト鍵（例 URL は Helicone 側ドキュメントの現行値に合わせる）。
3. エージェントはローカルゲートを先に叩き、Helicone ヘッダはゲートの上流脚のみ。OpenClaw・Helicone・ベンダの三種トークンを chmod 0400 の別ファイルへ分離。
4. RPM・TPM・連敗の窓で予算閾値を数え、超過時は circuit / retry_after_ms / route 入りの短い JSON で遮断。失敗はプロンプトを落とし correlation_id と復旧ヒントだけをオーケストレータへ回伝。
5. 二〜三モデルを並列に回してメモリとソケットを見る（LangGraph 実戦 と同様の扇出）。ルート変更時は openclaw doctor とマスク済み env テンプレをスナップショット。
/v1/models でクライアント互換を詰める
本番と同一の gateway→Helicone→provider で GET /v1/models を叩き、マニフェストの model id が一覧に揃うことを確認。ゲート経由と Helicone 直の id 集合を diff し、SDK の /v1 二重付与も確認。
# 例: Helicone 経由でモデル一覧（ホスト・パス・鍵は環境に合わせて調整）
curl -sS "https://oai.hconeai.com/v1/models" \
-H "Authorization: Bearer ${PROVIDER_API_KEY}" \
-H "Helicone-Auth: Bearer ${HELICONE_API_KEY}" | jq '.data[].id'127.0.0.1 のゲートでも同じプローブを打ち id を diff。SDK の /v1 二重付与に注意し、環境ごとにベース URL を一つに固定。
排障メモ
- 401（Helicone のみ）。
Helicone-Authとヘッダ転送を確認。 - model 消失。
/v1/modelsを diff。併用時は LiteLLM 稿。
FAQ
Helicone でサーキットは代替できるか。 不可。観測は Helicone、遮断は Mac 側カウンタ。
開発で Helicone を外す。 別ポートで観測だけ外し、model 名は本番と同一に。
検収環境。 扇出再現性のため クラウド Mac mini M4 相当の専用ノード推奨。