caveman-setup

自分で作っている LLM のアプリが、何にいくら使っているかを測りたいときの導入手順です。Claude Code の口調を変える caveman とは別物で、相手は手元のエージェントではなく、あなたが出荷するアプリのコードです。

Caveman のゲートウェイとは

SKILL.md は、ゲートウェイを「中身を 1 バイトも変えずに通す LLM のプロキシ」と説明しています。記録のモードでは、アプリが送ったものとかかった費用を測るだけで、ほかは何も変えません。エージェントに求めるのは、作り直しではなく、最小限で確かめ済みのつなぎ込みです。

最初に渡す 4 つの値

このスキルは、呼び出した依頼文に 4 つの値が書かれている前提で動きます。1 つでも欠けていれば止まって尋ね、URL を推測したり鍵を作ったりはしません。

5 つの段

1. 探す依存関係のファイルとソースから、生きている LLM の呼び出しを全部探し、ファイルと行の一覧を出す
2. 名前を決めるパッケージ名からアプリの名前（スラッグ）を決める。ゲートウェイの経路 /w/<app> になる
3. 付け替える呼び出しごとに、接続先をゲートウェイに変え、認証のヘッダーを 1 つ足す
4. 確かめる付け替えた経路で、小さな本物のリクエストを 1 回送る
5. 報告する見た結果だけを、決まった形で報告する

探す対象は、openai・@anthropic-ai/sdk・Vercel の ai・langchain・litellm・google-genai などの読み込みと、api.openai.com などへの直接の通信、OPENAI_BASE_URL のような接続先の環境変数です。呼び出しが 1 つも無ければ、つなぎ込みをでっち上げずに「つなぐものが無い」と報告して止まります。

付け替えの形は決まっている

OpenAI の SDK、Anthropic の SDK、Vercel AI SDK、LangChain と LangGraph、LiteLLM、直接の HTTP について、接続先とヘッダーの書き方が本文に載っています。どれも、接続先を GATEWAY/w/<app> の下に変え、x-cave-api-key のヘッダーを足す同じ型です。

アプリの名前は小文字の英数字で始め、続きは英数字と . _ -、64 文字までです。環境変数のファイルには CAVE_GATEWAY_URL と CAVE_API_KEY を足し、コードからはそれを読ませます。

手元のコーディングエージェントを測りたいだけのとき

このスキルは、LLM を呼ぶコードを出荷しているリポジトリ向けです。呼び出しが見つからないときの報告の文面は、コーディングエージェントを動かしているだけなら caveman wrap <agent> を使うよう案内しています。

LLM の通信を外のサービスに通したくないとき

つなぎ込んだあとは、アプリの LLM の通信がすべてゲートウェイを通ります。社外にプロンプトや応答を出せない取り決めがあるなら、先に Caveman Cloud の扱いを確かめてください。SKILL.md 自体は、記録した中身をどう保管するかを書いていません。

すぐに費用を下げたいとき

このスキルが入れるのは測る仕組みだけです。最適化は有効にせず、節約できたとも言わないのが決まりで、最適化を自分で有効にして評価を通るまで、確かめられた節約は 0 ドルだと報告させます。

コードと設定を書き換える

SKILL.md には、外部通信（確かめの curl）・シェル実行・ファイル書き換えの記述がそろっています。書き換えるのは、LLM の呼び出し箇所のコード、環境変数のファイル（.env、.env.local など）、場合によっては .gitignore です。環境変数のファイルが git の無視の対象になっていなければ .gitignore に足し、そう伝えるよう書かれています。

鍵をソースに直書きしないこと、ついでの作り直しや整形をしないこと、も規則にあります。

確かめの 1 回は、尋ねずに送る

確かめの段について、本文ははっきり書いています。設定用の文面を貼った時点で、この 1 回の確かめは許可済みとみなし、許可を求めて止まらずに送る、と。確かめないまま終わるより、小さなリクエストを 1 回送るほうがよい、という立場です。

鍵がどこへ行くか

byok のときは、リクエストのたびに x-cave-upstream-key のヘッダーでプロバイダーの鍵をゲートウェイへ送る形になります。stored のときは、プロバイダーの鍵は Caveman Cloud に暗号化して預けたものが使われ、エージェントは鍵を見ません。

本文によると、ゲートウェイはプロバイダーへの認証のヘッダーを毎回作り直すので、アプリ側の Authorization や x-api-key の値はプロバイダーへそのまま流れません。どちらの形を選ぶかは、鍵を誰に預けるかの判断です。

載っていないフレームワークは、公開元の文書を取りに行く

google-genai・crewai・pydantic-ai・openai-agents などは、このスキルを配った先の文書（/docs/integrations/ の下）を取りに行って従うよう書かれています。作業の途中で外の文書を読み込むことになります。

報告は見たものだけ

最後の報告には、確かめのリクエストで実際に返った HTTP の状態と、トークンの数を書きます。成功は、usage が付いた HTTP 200 のときだけです。

失敗したときの文面も 5 通り決まっています。つなぐものが無い、ゲートウェイに届かない、鍵が拒否された（401）、経路が合わない（404）、プロバイダー側のエラーです。どれでも成功とは報告せず、確かめられていないつなぎ込みは確かめられていないと書く決まりです。

同梱ファイルは無い

スキルのフォルダーには SKILL.md しかありません（2026-10-22 時点）。本文は約 1 万バイトで、手順・付け替えの例・報告の文面がすべてその中に入っています。

自分のサーバーでゲートウェイを動かせますか

SKILL.md は、ゲートウェイの URL の例として http://127.0.0.1:8787 のような手元の住所も挙げています。ただ、ゲートウェイをどう立てるかはこのスキルには書かれていません。手元で動かす方法は、公開元の文書で確かめてください。

つないだら、アプリの動きは変わりますか

SKILL.md の説明では、記録のモードではモデルに届く中身を変えず、最適化も有効にしません。変わるのは接続先と、足した認証のヘッダーです。ゲートウェイを通るぶん経路が 1 段増えるので、届かないときはつなぎ込みが動かない点は意識しておいてください。

確かめで 401 や 404 が返りました

401 は CAVE_API_KEY が拒否された場合で、ダッシュボードで鍵を作り直して環境変数のファイルを直すよう案内されます。404 は経路が合わない場合で、たいていはアプリの名前の書き方か、SDK の形式と合わない経路が原因だと書かれています。どちらも、直したら確かめのリクエストを送り直します。

用途ごとに費用を分けて見られますか

このスキルが分けるのはアプリの単位までです。最後の報告の文面は、用途ごとに分けたいなら「discover workflows」と言うよう促し、呼び出し箇所に仕事ごとの名札を付ける次の手順へ案内しています。