◉CLAUDE LABEN
●2.1.296 — サブエージェントごとに autoCompactWindow を指定でき、ワークフロー用のモデルも環境変数で固定できます●HAIKU 5.5 — 2.1.293(10/07)から claude-haiku-5-5 が Anthropic API の既定の Haiku モデルになりました●SONNET 4.5 — Claude API での提供終了は 11/30、残り47日。移行先は Sonnet 5.5●Q&A — Mod が「エラーなしで何も描かれない」ときに見る3か所が共有されています●AGENTS.MD — Codex と Claude Code を同じフォルダで使うとき、AGENTS.md と CLAUDE.md の入口をどう分けるかの整理が出ています●NEW — 「cd して git add して commit」の承認が毎回出るのは、設定の抜けではなく仕様でした●2.1.296 — サブエージェントごとに autoCompactWindow を指定でき、ワークフロー用のモデルも環境変数で固定できます●HAIKU 5.5 — 2.1.293(10/07)から claude-haiku-5-5 が Anthropic API の既定の Haiku モデルになりました●SONNET 4.5 — Claude API での提供終了は 11/30、残り47日。移行先は Sonnet 5.5●Q&A — Mod が「エラーなしで何も描かれない」ときに見る3か所が共有されています●AGENTS.MD — Codex と Claude Code を同じフォルダで使うとき、AGENTS.md と CLAUDE.md の入口をどう分けるかの整理が出ています●NEW — 「cd して git add して commit」の承認が毎回出るのは、設定の抜けではなく仕様でした
記事一覧/API & SDK
⬡ API & SDK/2026-06-15上級

課金変更が発効した日に、headless 実行のコストを工程ごとに計測する仕組みを入れた

6月15日の課金変更で headless 実行とエージェント委譲が月次クレジット制になりました。どの工程がいくら使っているかを response.usage から工程タグ単位で記録し、日次で円換算レポートを出す計測レイヤーの実装を共有します。

claude-agent-sdk6headless13cost-controlmetering課金変更可観測性5

✦ プレミアム記事

月次クレジット制への移行が本日発効し、自動投稿パイプラインの headless 実行が「サブスクの定額内」から「使った分だけクレジットを削る」世界に変わりました。移行前に工程の振り分けは見直していたのですが、いざ初日を迎えて気づいたのは、そもそも自分が「どの工程がいくら使っているか」を数字で把握していなかったということです。

個人開発で4サイトを回している自分にとって、見積もりは立てていました。けれど見積もりは見積もりで、実測ではありません。繰越のないクレジットを月内で配分するなら、推測ではなく「先週この工程は実際にいくら溶かしたか」という台帳が要ります。そこで初日のうちに、各 API 呼び出しのトークン消費を工程タグ単位で記録し、日次で円換算するだけの薄い計測レイヤーを差し込みました。今日はその中身を順番に書いていきます。

派手な可観測性基盤の話ではありません。狙いは「既存のコードにほぼ手を入れず、後から工程別にコストを問い詰められる状態」を最小コストで作ることです。

なぜ Console の請求画面だけでは足りないのか

Anthropic Console の使用状況画面は、アカウント全体・API キー単位での消費は見せてくれます。けれど私の運用では、ひとつの API キーで「記事生成」「品質ゲート判定」「ニュース収集」「翻訳同期」という性質の違う工程が混ざって走っています。Console を開いても、今週クレジットを最も食ったのが生成なのか、それともリトライを繰り返した品質ゲートなのかが分からないのです。

月次クレジットは繰越がありません。つまり「月末に足りなくなる工程」を事前に特定できなければ、優先度の低い工程が高い工程のクレジットを食い潰したまま気づけません。Console の粒度では、この「工程別の取り合い」が見えないのが本質的な問題でした。

必要なのは、API 呼び出しのたびに usage を工程名つきで記録し、後から stage=quality-gate の今月の累計はいくら と聞ける台帳です。これはアプリ側でしか作れません。

response.usage を取りこぼさない

計測の土台は、すべての応答に含まれる usage オブジェクトです。ここで最初の落とし穴がありました。usage は単純な入力・出力の2項目ではありません。プロンプトキャッシュを使っていると、実際には4種類のトークンが返ってきます。

// Anthropic SDK の応答に含まれる usage の実際の形
// (キャッシュを使うと cache_* が非ゼロになる)
type RawUsage = {
  input_tokens: number;             // 非キャッシュの入力
  output_tokens: number;            // 生成された出力
  cache_creation_input_tokens?: number; // キャッシュへの書き込み(割増)
  cache_read_input_tokens?: number;     // キャッシュからの読込(大幅割引)
};

ここを input_tokens + output_tokens だけで集計すると、キャッシュ生成・キャッシュ読込のトークンがまるごと台帳から抜け落ちます。キャッシュ生成は通常の入力より割高、キャッシュ読込は大幅に安い、という非対称な単価がついているので、4種類を別々に持っておかないと円換算が合いません。私は最初これを2項目で集計していて、実測値が Console の請求とどうしても噛み合わず、半日溶かしました。

そこで、4種類を必ず別フィールドで保持する正規化関数を最初に置きます。

// 欠けたフィールドを 0 で埋め、4種類を必ず揃える
export function normalizeUsage(raw: Partial<RawUsage> | undefined) {
  return {
    input: raw?.input_tokens ?? 0,
    output: raw?.output_tokens ?? 0,
    cacheWrite: raw?.cache_creation_input_tokens ?? 0,
    cacheRead: raw?.cache_read_input_tokens ?? 0,
  };
}
✦

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること
✦「今月のクレジットが何に消えたか分からない」状態を、工程タグ単位の実測データで説明できるようになります
✦response.usage の4種類のトークン(入力・出力・キャッシュ生成・キャッシュ読込)を取りこぼさず記録し、円換算する計測ラッパーをコピペで導入できます
✦計測結果から「どの工程を headless に残し、どこをサブスク枠へ戻すか」をクレジット消費の根拠つきで判断できるようになります
Stripe による安全な決済 · いつでもキャンセル可能
✦

この記事を購入する

この先の内容をすべてお読みいただけます。一度のご購入で、いつでも何度でもアクセスできます。このサイトは広告を掲載しておらず、皆さまのご支援がサーバー費用などの運営を支えています。

または
メンバーシップなら全記事が読み放題 →
シェア

お読みいただきありがとうございます

Claude Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

  • ✦コピー&ペーストで使える実装コード付き
  • ✦毎日新しい上級ガイドを追加
  • ✦¥580/月 または ¥2,480 の永久アクセス
メンバーシップを見る →

関連記事

⬡ API & SDK2026-05-07
Claude Agent SDK の Transactional Outbox 実装 — 「副作用の取りこぼし」を本番でゼロにする設計
Claude Agent SDK で発生する「DBには書かれたのにメール/決済/通知が飛ばなかった」事故を防ぐため、Transactional Outbox パターンを Postgres と Cloudflare Queues を例に本番品質で実装する手順をまとめます。
⬡ API & SDK2026-05-02
Claude API の本番運用で予算上限を確実に守る — 日次トークン超過を検知して自動停止するサーキットブレーカー設計
Claude API のコストを「気づいたら月10万円超過」で終わらせない、サーキットブレーカーパターンの実装ガイドです。Cloudflare Workers + KV / Durable Objects で日次・月次予算を強制し、停止・劣化・通知の3戦略を切り替えるコードを示します。
⬡ API & SDK2026-04-24
Claude Agent SDK でシャドウモードを実装する — 本番影響ゼロでエージェント精度を測る段階的ロールアウト設計
AIエージェントを本番に出す前に精度を測りたい。でもユーザーに触れさせるしかない。この矛盾を解くのがシャドウモードです。Claude Agent SDK で既存フローに影響を与えずエージェントを並走させ、差分を記録し、段階的に昇格するまでの実装を解説します。
📚RECOMMENDED BOOKS
大規模言語モデル入門
山田育矢
LLM開発
生成AIプロンプトエンジニアリング入門
我妻幸長
プロンプト
Claude CodeによるAI駆動開発入門
平川知秀
AI駆動開発
※ アフィリエイトリンクを含みます