Cavemanセットアップ

リポジトリをCaveman Cloudゲートウェイに配線し、LLMリクエストをすべて測定します。動作は変更せず、LLM支出の可視性を追加します。

Cavemanセットアップ とは?

このスキルは、開発者が既存のLLM対応アプリケーションをCavemanゲートウェイプロキシに統合するためのものです。Cavemanはバイト保存型LLMプロキシで、レコードモードではアプリの送信内容とそのコストを測定しますが、コード自体は一切変更しません。OpenAI、Anthropic、Vercel AI SDK、LangChain、LiteLLMなど、主要なLLMフレームワークとSDKをサポートしています。このスキルは、ゲートウェイURLとAPIキーの設定から、各LLMコールサイトの特定と配線、実際のリクエストによる検証、そして詳細なレポートの生成までを自動化します。目標は、最小限の介入でアプリのLLM使用状況を可視化し、ダッシュボードで支出を追跡できるようにすることです。

対応✓Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/JuliusBrussee/caveman/tree/main/skills/caveman-setup

Installed? Explore more 生産性&コラボレーション skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

あなたはこのリポジトリをCavemanゲートウェイに配線しています。Cavemanはバイト保存型のLLMプロキシです。レコードモードでは、アプリが送信する内容とそのコストを測定し、それ以外は何も変更しません。あなたの仕事は最小限で検証済みの統合を行うことであり、リファクタリングではありません。

このプロンプトは4つの値を提供します。次のように参照してください。

  • GATEWAY — ゲートウェイのベースURL(例: https://gateway.caveman.so または http://127.0.0.1:8787)
  • CAVE_API_KEY — ゲートウェイ認証シークレット(APIキーと同様に扱い、環境変数のみに格納し、コミットや全文表示は絶対に行わない)
  • PROVIDER_KEYS — stored(プロバイダキーはCaveman Cloudに暗号化されて保存されます)または byok(このアプリがリクエストごとに独自のプロバイダキーを送信します)
  • DASHBOARD — ダッシュボードのベースURL(例: https://app.caveman.so)

いずれかの値が欠けている場合は、停止してそれを要求してください。URLを推測したり、キーを生成したりしないでください。

ルール(絶対遵守)

  1. 一貫性のある統合。 すべての有効なLLMコールサイトを、既存の設定と適切な継ぎ目を通じて配線します。正しさに必要なレイヤーにのみタッチします。ついでのリファクタリングやフォーマットの一掃は行わず、所有権を明確にしたりライフサイクルコストを下げたりする場合にのみ抽象化を追加します。
  2. シークレットは環境変数にのみ保存。 CAVE_API_KEYは、リポジトリがすでに使用しているenvファイル(.env、.env.localなど)に保存します。そのファイルがgitignoreされていない場合は、.gitignoreに追加してその旨を伝えます。キーをソースコードにハードコードしないでください。
  3. 観測したものだけを報告。 最終報告書には、実際の検証応答からのHTTPステータスと使用量の数値を記載します。成功を決して仮定しないでください。検証が失敗した場合は、代わりに失敗テンプレートを報告します。
  4. レコードモードのみ。 あなたは測定を追加しています。最適化は一切有効にせず、削減額も主張しません。検証された削減額は、オプティマイザーが明示的にオンにされ、その評価ゲートを通過するまでは0ドルです。
  5. プロバイダキーはあなたの管轄外。 PROVIDER_KEYS: storedの場合、プロバイダキーを見ることはありません。byokの場合、アプリの既存のプロバイダキーはそのままの場所に保持されます。

ステップ1 — すべての有効なLLMコールサイトを見つける

依存関係ファイル(package.json、requirements.txt、pyproject.toml、go.mod、ロックファイル)を読み、ソース内のLLMクライアントを検索します。

  • SDKインポート: openai、@anthropic-ai/sdk、anthropic、ai + @ai-sdk/*(Vercel)、langchain*、litellm、google-genai / @google/genai、crewai、pydantic_ai、openai-agents / agents
  • api.openai.com、api.anthropic.com、generativelanguage.googleapis.comへの生のHTTP
  • 既存のベースURL環境変数: OPENAI_BASE_URL、OPENAI_API_BASE、ANTHROPIC_BASE_URL、GEMINI_BASE_URL、GOOGLE_GEMINI_BASE_URL

何も変更する前に、見つけたもの(ファイル:行ごと)をリストアップしてください。LLMコールサイトが見つからなかった場合は、停止してこのファイル末尾の「配線するものがない」テンプレートを報告してください。統合をでっち上げないでください。

ステップ2 — アプリスラッグを選ぶ

1つのスラッグがゲートウェイパス内でこのアプリを識別します: GATEWAY/w/<app>。パッケージ/モジュール名から派生させてください(例: support-bot、acme-api)。文法: 最初は小文字[a-z0-9]、その後は[a-z0-9._-]、最大64文字。このアプリ全体の支出は、ダッシュボード上でそのスラッグの下にグループ化されます。

ステップ3 — 各コールサイトを配線する

パターンは常に同じです: ベースURL → /w/<app> 付きのゲートウェイ、プラス1つの認証ヘッダー。 ゲートウェイ認証は x-cave-api-key: CAVE_API_KEY です(Authorization: Bearer CAVE_API_KEY も、ヘッダーが不自然な場合は機能します)。PROVIDER_KEYS: byok の場合は、x-cave-upstream-key: <アプリがすでに使用しているプロバイダキー> も送信します。

配線を安全にする2つの事実(両方ともゲートウェイによって強制されるものであり、希望的観測ではありません): ゲートウェイは上流の認証ヘッダーをゼロから再構築するため、クライアントのAuthorization/x-api-key値がプロバイダに転送されることはありません。また、storedモードでは、上流の認証はサーバー側の暗号化接続から行われます。したがって、storedモードでSDKがapi-keyパラメータを必須とする場合、Caveキーを設定してください。これはゲートウェイを認証し、それ以上は送信されません。

正確な形状(各コールサイトに一致するものを使ってください — これらは製品の公開レシピであり、提案ではありません):

OpenAI SDK (TS) — Chat CompletionsとResponsesの両方が以下を経由します:

const client = new OpenAI({
  baseURL: `${process.env.CAVE_GATEWAY_URL}/w/<app>/openai/v1`,
  apiKey: process.env.OPENAI_API_KEY,           // byok: 変更なし · stored: CAVE_API_KEYを使用
  defaultHeaders: {
    "x-cave-api-key": process.env.CAVE_API_KEY!,
    // byokのみ:
    "x-cave-upstream-key": process.env.OPENAI_API_KEY!,
  },
});

OpenAI SDK (Python) — 同じ形状: base_url=f"{gw}/w/<app>/openai/v1"、default_headers={"x-cave-api-key": ..., "x-cave-upstream-key": ...}。

Anthropic SDK (TS/Python) — SDK自体が/v1/messagesを追加します。ここでは両方のモードでx-cave-api-keyヘッダーが必要です(このSDKの独自のキーパラメータはx-api-keyに乗りますが、これはゲートウェイ認証ヘッダーではありません):

client = anthropic.Anthropic(
    base_url=f"{os.environ['CAVE_GATEWAY_URL']}/w/<app>",
    api_key=os.environ["ANTHROPIC_API_KEY"],      # byok: 変更なし · stored: CAVE_API_KEYを使用
    default_headers={
        "x-cave-api-key": os.environ["CAVE_API_KEY"],
        # byokのみ:
        "x-cave-upstream-key": os.environ["ANTHROPIC_API_KEY"],
    },
)

Vercel AI SDK — createOpenAICompatible({ baseURL: ${gw}/w//openai/v1、headers: { "x-cave-api-key": ... } }); Anthropicモデルは createAnthropic({ baseURL: ${gw}/w//v1、headers: { ... } }) を使用します。

LangChain / LangGraph — ChatOpenAI(base_url=f"{gw}/w/<app>/openai/v1"、default_headers={...}); ChatAnthropic(base_url=f"{gw}/w/<app>"、default_headers={...})。LangGraphは渡されたモデルをそのまま継承します。

LiteLLM — 呼び出しごとに api_base=f"{gw}/w/<app>/openai/v1" + extra_headers={...}、または LiteLLM プロキシ config.yaml でフリート全体に設定します。

生のHTTP / その他 — ホストを交換し、プロバイダのネイティブパスを維持します: GATEWAY/w/<app>/v1/chat/completions(OpenAIプロトコル)または GATEWAY/w/<app>/v1/messages(Anthropicプロトコル)、ヘッダーを追加します。

具体的には、スラッグが support-bot でホスト型ゲートウェイの場合、OpenAI SDKのベースURLは https://gateway.caveman.so/w/support-bot/openai/v1 のようになります。また、stored モードでは、すべての x-cave-upstream-key 行を完全に削除してください。これは byok のみのものです。

リストにないフレームワーク(google-genai、crewai、pydantic-ai、openai-agents)については、このスキルが提供されたのと同じオリジンの <docs origin>/docs/integrations/ にある該当ページを参照し、それに従ってください。

リポジトリのenvファイルに追加します(コードから参照します。リテラル値は使用しません):

CAVE_GATEWAY_URL=<GATEWAY>
CAVE_API_KEY=<CAVE_API_KEY>

ステップ4 — 1つの実際のリクエストで検証する

ユーザーがセットアッププロンプトを貼り付けたのは、これを正確に承認するためです: 1つの小さな検証リクエスト。ためらわずに今すぐ送信してください。ためらいのために未検証で終わる統合は、1つの小さなリクエストよりもはるかに悪い結果です。検証とレポートを自律的に完了することが、このスキルのポイントです。

構築した配線を通じて1つの最小限のリクエストを送信します。アプリにスクリプトがあれば最も安価なパスで、そうでなければ配線したプロトコルに一致するパスでcurlを使用し、アプリ独自のモデルと小さな上限(max_tokens ≤ 32)を指定します:

# OpenAIプロトコルの配線:
curl -sS "$CAVE_GATEWAY_URL/w/<app>/v1/chat/completions" \
  -H "x-cave-api-key: $CAVE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"<モデル>","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

# Anthropicプロトコルの配線:
curl -sS "$CAVE_GATEWAY_URL/w/<app>/v1/messages" \
  -H "x-cave-api-key: $CAVE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"<モデル>","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

(byok: -H "x-cave-upstream-key: $PROVIDER_KEY" を追加してください。)これは1つの実際の、課金されるプロバイダリクエストです。それがポイントです: 実際のトラフィック、実際の測定。

応答を読み取ります。成功 = usageブロックを含むHTTP 200。それ以外 = 以下の該当する失敗テンプレート。

ステップ5 — 報告する

以下の形状で正確に終了します。値は実際に行い、見た内容から埋めてください:

## Cavemanがこのリポジトリで有効になりました

配線: <n>ファイル内<n>コールサイト
  - <ファイル> — <1行で何を変更したか>
アプリスラッグ: <app> — このアプリの支出はこのスラッグの下にグループ化されます
検証: HTTP 200 · モデル <モデル> · <入力> in / <出力> out トークン(1つの実際のリクエスト)
モード: レコード — 測定のみ。モデルに表示されるバイトは変更されず、最適化も有効になっていません。検証された削減額は、オプティマイザーをオンにして評価ゲートを通過するまでは0ドルです。その正直さが製品です。

ダッシュボードで確認: <DASHBOARD>/traces — あなたのリクエストが一番上の行に表示され、公開カタログから価格設定されます。<DASHBOARD>/getting-started が「最初のリクエストを受信しました」に変わります。

支出をアプリごとだけでなく、ワークフロー(例: サポート返信 vs 夜間ダイジェスト)ごとに分割したいですか?「workflowsを探索」と言ってください。<docs origin>/docs/discover-workflows.md を取得し、すべてのコールサイトをそのジョブでラベル付けします。

失敗テンプレート(そのまま使用し、埋めてください。決して和らげないでください)

  • 配線するものがない: 「このリポジトリにLLMコールサイトは見つかりませんでした(SDK、生のプロバイダHTTP、ベースURL環境変数を検索しました)。このリポジトリがLLMコードを出荷するのではなく、コーディングエージェントを実行する場合は、代わりにcaveman wrap <agent>を使用してください。詳細: /getting-started。」
  • ゲートウェイに到達できない: 「検証リクエストがGATEWAYに到達できませんでした(<エラー>)。配線は整っていますが、未検証です。ゲートウェイに到達可能になるまで何も測定されません。URLとネットワークを確認し、上記の検証curlを再実行してください。」
  • 401 cave_invalid_api_key: 「ゲートウェイがCAVE_API_KEYを拒否しました。/getting-started で新しいキーを生成し、envファイルを更新してください。配線自体は変更されていません。」
  • 404 cave_route_not_found: 「ゲートウェイがルートに一致しませんでした。通常は、/w/スラッグの形式が正しくない(最初は小文字[a-z0-9]、その後[a-z0-9._-]、最大64文字)か、パスがSDKのプロトコルと一致していません。URLを修正して再検証してください。」
  • プロバイダエラー(ゲートウェイ経由の4xx/5xx): ステータスと本文をそのまま報告します。ゲートウェイには到達可能で認証は成功しましたが、上流の呼び出しが失敗しました。通常は、アプリ自体のプロバイダキーまたはモデル名の問題です。

これらのいずれかで成功と報告しないでください。検証されていない統合は、未検証として報告されます。```

Individual skills in this repo

This repo contains 12 individual skills — each has its own dedicated page.

JuliusBrussee/caveman-discover

Find and label every LLM workflow in the repository so Caveman Cloud groups spend by workflow instead of one bucket. Use for "discover workflows" or breaking LLM spend down by workflow.

JuliusBrussee/caveman-evidence-review

Read-only review of Caveman Cloud evidence: cost, Cave Score, workflows, traces, latency, errors, routing, savings. Use when asked what Caveman found or where LLM spend goes.

JuliusBrussee/caveman-explore

Read-only repository explorer for cold-start orientation, broad cross-file localization, or when a direct search failed. Skip it when the exact file or symbol is already named. Returns path:line citations only; its reads stay out of main context.

JuliusBrussee/caveman-learn

Act on a Caveman learn report - review the ranked token sinks, apply cost-lowering fixes with per-edit consent, and report what those fixes returned. Use when asked to lower an agent's token cost, what caveman has saved, to trim a heavy CLAUDE.md, or to offload re-pasted context into cavemem.

JuliusBrussee/caveman-manage

Inspect Caveman Cloud's experiment lifecycle and block unsafe execution. Use when asked to start, approve, cancel, promote or roll back a Caveman experiment.

JuliusBrussee/caveman-optimize

Turn a Caveman optimization observation into an operator-chosen candidate with a paired baseline evaluation. Use when asked to inspect or evaluate a Caveman optimization report. Needs explicit approval.

JuliusBrussee/investigate-first

Diagnose ambiguous failures before editing. Use for unknown causes, intermittent behavior, performance regressions, or investigations needing evidence-ranked hypotheses.

JuliusBrussee/lean-build

Build feature work with high overbuilding risk. Use for new behavior, product slices, or integrations where repository reuse, strict scope, and an explicit stop condition matter.

JuliusBrussee/migration

Implement reversible compatibility-safe transitions. Use for schema, data, API, protocol, configuration, or dependency migrations requiring rollback and preservation proof.

JuliusBrussee/safe-refactor

Restructure code while preserving behavior. Use for extraction, consolidation, ownership moves, or cleanup where verification must bracket structural edits.

JuliusBrussee/surgical-patch

Fix bugs and small behavior changes at the narrowest responsible layer. Use when regression proof, preserved surrounding behavior, and task-relevant tests matter.

JuliusBrussee/verify-and-stop

Prove existing work meets acceptance conditions without expanding scope. Use for validation-only tasks, completion checks, focused gate runs, and last-mile proof.

関連スキル