CLIコーディングエージェントは、請求書が届くまでは自由気ままに感じられます。Claude CodeやCodexにリポジトリを指示し、モジュールのリファクタリングを依頼すると、10分後には40のファイルを読み込み、テストスイートを3回実行し、必要ないはずのコンテキストに何十万ものトークンを費やしています。これを8人のエンジニアチームが一日中エージェントを実行すると考えると、請求額は誤差の範囲では済みません。コーディングエージェントのトークン消費のほとんどは無駄であり、そのほとんどはモデルを変更したり、出力品質を落とすことなく、コマンドラインから修正可能です。
TL;DR
エージェントのトークンコストを削減するには、モデルに到達する前にコンテキストをトリミングします。作業セットのスコープを絞り、メモリファイルを短く保ち、長いセッションを圧縮します。安定したプレフィックスにはプロンプトキャッシュをオンにします（繰り返しの読み込みで約90%オフ）。安価なサブタスクは小さなモデルにルーティングします。ツールの出力を制限します。何が実際に変更されたかを知るために、実行ごとのコストを測定します。
はじめに
この問題は2つの形で現れます。週ごとまたはセッションの制限を超過してタスクの途中で突然壁にぶつかるか、または月々のAPI請求書が届き、「AIアシスタント」がジュニアコントラクターよりも費用がかかる理由を問われるかのどちらかです。どちらも根本原因は同じです。CLIエージェントはデフォルトでトークンを大量に消費します。10行必要な時にファイル全体を読み込み、毎回会話全体を再生し、生のコマンド出力をコンテキストにダンプし、同じシステムプロンプトとリポジトリマップを1日に何千回も再送信します。
これらのいずれも作業に固有のものではありません。2,000トークンのコードについて本当に推論する必要があるリファクタリングに、180,000トークンのコンテキストは必要ありません。この2つの数値の差が節約できる部分であり、そのほとんどは今日から採用できるフラグ、設定ファイル、習慣で回収できます。
このガイドでは、CLIエージェントの実行でトークンが実際にどこに費やされるかを説明し、その後、コンテキストの衛生管理とメモリファイル、プロンプトキャッシュ、モデルルーティング、ツール出力と検索のトリミング、そして節約が推測ではなく実際の費用であることを確認するための実行ごとのコスト測定といった、各カテゴリを削減するための具体的な戦術を提示します。例はClaude CodeとCodexを想定していますが、メカニズムはトークン課金APIと対話するすべてのエージェントに適用されます。
早期に言及すべき隣接するコストが一つあります。エージェントのトークン消費の多くはデバッグによるものです。不安定な内部APIを呼び出すエージェントは、再試行し、エラーボディを読み込み、ドキュメントを再読み込みし、ループし、そのたびに全額のトークンを費やします。
CLIエージェント実行でトークンが実際に費やされる場所
最適化する前に、請求額のメンタルモデルが必要です。エージェントの1回の「ターン」は、入力ペイロードをモデルに送信し、出力ペイロードを受け取ります。両方に対して料金を支払い、ほとんどのプロバイダーでは出力コストは入力よりもトークンあたり3〜6倍高くなります。2026年半ばのフロンティアモデルファミリーの1つでは、入力は約100万トークンあたり3ドル、出力は約15ドルです。同じファミリーの安価なモデルでは、入力は約1ドル、出力は約5ドルです。これらは例示であり、見積もりではありません。プロバイダーが改定するため、ライブの料金ページを確認してください。正確な数値に関わらず、構造上のポイントは変わりません。出力は高価であり、入力ボリュームが膨らむ原因です。
一般的な実行で入力ペイロードを満たすものは次のとおりです。
- システムプロンプトとツール定義。 エージェントの指示と各ツールのJSONスキーマ。ターンごとに固定で、多くの場合5,000〜15,000トークンが毎回再送信されます。
- メモリとプロジェクトファイル。
CLAUDE.md、リポジトリの規則、永続的な指示など。関連性があるかどうかにかかわらず、毎回読み込まれます。 - 会話履歴。 以前のすべてのユーザーメッセージ、モデル応答、ツール呼び出し、ツール結果が毎回完全に再生されます。これは際限なく増加し、長いセッションでは通常最大の項目となります。
- 取得されたファイルコンテンツ。 エージェントが読み取ったファイル。1,200行のファイルを1回
Readすると、約12,000〜18,000トークンになり、エージェントはファイル全体を読み込むことを好みます。 - ツールの出力。 テストランナーのログ、
npm installのノイズ、生成されたロックファイルのgit diff、スタックトレース。デフォルトでは生で冗長です。
出力ペイロードは、モデルの推論、コード編集、説明です。ほとんどの実行では入力よりも小さいですが、トークンあたりの価格が最も高いため、「計画を6つの段落で説明させてください」のような冗長な動作は費用がかかります。
最も重要な事実：会話履歴は毎回再生されます。30ターンのセッションは、1ターンの30倍の費用がかかるわけではありません。増加するプレフィックスの合計に近く、後のターンはそれ以前のすべての内容の全負担を負います。そのため、長く、曲がりくねったセッションは最も費用がかかるものであり、以下の戦術が再送信されるコンテキストを不釣り合いにターゲットにする理由でもあります。
セッションと制限の会計が実際にどのように機能するかを深く知りたい場合は、Claude Codeのトークンウィンドウがどのようにリセットされるかの解説がこのセクションの役立つ補足資料となります。これは、「短いと感じる」セッションでも予算を使い果たす可能性がある理由を説明しています。
コンテキストの衛生管理とメモリファイル
最も安価なトークンは、決して送信されないトークンです。コンテキストの衛生管理は、残りのセッションのすべてのターンで入力ペイロードを縮小するため、最も影響の大きい習慣です。
開始前に作業セットのスコープを絞ります。 リポジトリのルートでエージェントを開いて「課金ロジックをリファクタリングして」と言わないでください。それはクロールします。代わりに、どのファイルが重要かを正確に伝えます。
# 広範な探索を誘発する漠然としたプロンプトの代わりに:
claude "指数関数的バックオフを使用するようにリトライロジックをリファクタリングして。
src/payments/retry.tsとそのテストファイル内のみで"
ファイルを指定することで、エージェントが関連する2つのファイルを見つけるために20個の候補ファイルを読み込むことを防ぎます。探索させる必要がある場合は、ルートではなくディレクトリを指示します。
メモリファイルを短く安定させます。 CLAUDE.md（または同等のプロジェクトメモリファイル）は、すべてのターンでコンテキストに読み込まれます。チームはそれをWikiのように扱い、4,000トークンものオンボーディング散文に成長させることがあります。例えば、8人のエンジニアが1日に50ターン実行すると、肥大化したメモリファイルは、追加の利点がないにもかかわらず、毎日何百回も再送信されます。監査してください。
# メモリファイルのトークン数の概算チェック（文字数 / 4 が妥当な推定値）:
wc -c CLAUDE.md | awk '{print "≈", int($1/4), "トークン/ターン"}'
ファイルは簡潔に保つことを目指します。ビルド/テストコマンド、厳密な規則、そして詳細なドキュメントの場所へのポインタを含め、ドキュメント自体は含めません。月に一度しか関連しないセクションは、常に読み込まれるファイルには含めるべきではありません。エージェントが必要に応じて読み込むドキュメントに移動します。
長いセッションを圧縮またはリセットします。 セッションがその役割を終え、無関係なタスクに移行する場合、同じコンテキストに入力し続けないでください。新しいターンごとに、以前のトランスクリプト全体が引きずられます。エージェントの圧縮またはクリアコマンドを使用します。
# Claude Codeで会話が長くなった場合:
/compact # 履歴を短い要約に圧縮し、生のトランスクリプトを破棄する
# または、新しいタスクで完全に切り替える場合:
/clear # 新しいセッションを開始。古いコンテキストは再送信されない
/compactは通常、数万トークンの生の履歴を10分の1のサイズの要約に置き換えます。そして、その小さいプレフィックスが後続のすべてのターンで引き継がれます。規律はシンプルです。1つのセッションにつき1つの論理タスク、タスク間で圧縮またはクリアを行います。Claude Codeのワークフローのパターンは、このスコープ設定の習慣に強く依存しており、全体的に採用する価値があります。
プロジェクトの無視ファイルを使用します。 生成されたアーティファクト、ロックファイル、ビルド出力、ベンダー依存関係をエージェントの手の届かないところに置きます。エージェントがdist/やnode_modules/を見なければ、それらを読み取ったり差分を取ったりするためにトークンを費やすことはありません。ほとんどのエージェントは無視ファイルを尊重します。一度設定すれば、節約は永続的です。
プロンプトキャッシュ: 同じプレフィックスに全額を払うのをやめる
これは、繰り返しの実行において最も大きなレバーであり、行動的というよりは機械的なものです。プロンプトキャッシュを使用すると、プロバイダーはリクエストのプレフィックス（ツール、システムプロンプト、安定したコンテキスト）を保存でき、そのプレフィックスを共有する後続のリクエストは、再処理する代わりに大幅な割引でそれを読み込みます。
Anthropicのプロンプトキャッシュのドキュメントによると、その経済性は次のとおりです。キャッシュ書き込みは通常の入力トークンよりも高価です（デフォルトの5分キャッシュでベース入力の約1.25倍、1時間キャッシュで約2倍）。しかし、キャッシュ読み込みはベース入力の約0.1倍、つまりキャッシュされた部分で約90%の割引になります。書き込みのプレミアムは小さく、読み込みの割引は大きいため、キャッシュは短寿命キャッシュでの1回のキャッシュヒット後、および長寿命キャッシュでの約2回のヒット後に元が取れます。デフォルトのキャッシュ寿命は短く（約5分、ヒットするたびにリフレッシュ）、1時間オプションも利用可能です。最小キャッシュ可能サイズがあり、小さなモデルや最大のモデルでは、プレフィックスが対象となるまでに数千トークンが必要となるため、キャッシュは最も重要な場所で役立ちます。つまり、大きな安定したプレフィックスです。
構造的なルールは、安定したコンテンツを最初に置き、揮発性のコンテンツを最後に置き、その後境界をキャッシュすることです。順序はtools → system → messagesであり、何かを変更するとそのレベルとそれ以降のすべてが無効になります。したがって、タイムスタンプ、ユーザーの入力メッセージ、新しく取得されたファイルコンテンツは、キャッシュのブレークポイントの後ではなく、前に来るようにしたいです。
独自のCLIラッパーからモデルを直接駆動する場合、これを明示的に設定します。
# 安定したプレフィックス（システム + ツール定義 + リポジトリ規則）をキャッシュする。
# 揮発性のユーザーターンは後から来て、キャッシュされたプレフィックスの一部ではない。
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=2048,
system=[
{
"type": "text",
"text": SYSTEM_PROMPT + REPO_CONVENTIONS, # 実行間で安定
"cache_control": {"type": "ephemeral"}, # ここがキャッシュのブレークポイント
}
],
messages=[{"role": "user", "content": user_task}], # 実行ごとに変更
)
# 実際にキャッシュされたものを検査する:
u = response.usage
print("キャッシュ書き込み:", u.cache_creation_input_tokens)
print("キャッシュ読み込み:", u.cache_read_input_tokens) # これらのトークンは約10%の課金
print("新規入力:", u.input_tokens)
毎日、同じシステムプロンプトと8,000トークンのリポジトリ規約ブロックを60回実行する日常のリファクタリングエージェントは、典型的なケースです。キャッシュなしでは、その8,000トークンブロックに対して60回全額の入力料金を支払います。キャッシュありでは、書き込みプレミアムを1回（またはキャッシュ期限切れごとに1回）支払い、残りの回数では約10%の読み込み料金を支払います。規約ブロックだけでも約90%の削減となり、これはここでの他のすべての戦術と積み重なります。
運用上の注意点が2つあります。まず、プレフィックスをバイト単位で安定させます。ブレークポイント前の文字が1つでも変更されるとキャッシュが無効になり、再度書き込み料金が発生します。システムプロンプトと規約を固定し、タイムスタンプを補間しないでください。次に、キャッシュはデフォルトで短命であるため、関連する実行をまとめてバッチ処理する（一日中分散させるのではなく）ことで、ウォームキャッシュにヒットし続けることができます。OpenAIのAPIは、サポートされているモデルでキャッシュされた入力に同様の割引を自動的に適用します。ノブは異なりますが、原則は同じです。キャッシュだけでは不十分な場合、Codexを介してGPT-5.5を無料で実行するのフリーティアとルーティングのトリックは、補完的なものとして役立ちます。
モデルルーティング: 安価な作業には安価なモデルを
すべてのエージェントアクションにフロンティアモデルが必要なわけではありません。3つのファイルにわたる変数名の変更、コミットメッセージの作成、差分の要約、ボイラープレートテストの生成には、アーキテクチャを設計するモデルと同じモデルは必要ありません。しかし、ほとんどのCLIエージェントのデフォルトの動作は、セッション全体で高価なモデルを介してすべてを実行することです。
ルーティングとは、リスクの低いサブタスクを意図的に小型で安価なモデルに送信し、高価なモデルを真の推論のために温存することです。価格差は大きく、特定のファミリーの小型モデルは、フラッグシップモデルよりもトークンあたり3〜5倍安価になることがあり、機械的なタスクでは出力品質の差はごくわずかです。
CLIからルーティングする実用的な方法:
# 1. タスクに基づいて呼び出しごとにモデルを選択する。
claude --model haiku "ステージングされた差分に対してconventional-commitメッセージを記述する"
claude --model sonnet "支払いサービスのキャッシングレイヤーを再設計する"
# 2. 頻度が高くリスクの低いループに安価なモデルを使用する
# （コミットメッセージ、チェンジログエントリ、簡単なリンターの説明）
# そして、明示的に難しいタスクを呼び出す場合にのみ強力なモデルを使用する。
デフォルトを高価なモデルに設定して決してダウングレードしないのではなく、デフォルトを安価なモデルに設定して意識的にエスカレートします。ほとんどのチームは極性を逆にしており、すべてを「安全のため」フラッグシップモデルで実行し、コミットメッセージのために5倍の費用を支払っています。
2番目のルーティング軸はサブエージェントです。エージェントフレームワークが狭いサブタスクを子エージェントに委譲することをサポートしている場合、その子に安価なモデルとごくわずかなコンテキストを与えます。子エージェントは、高価な親エージェントが全額で全コンテキストを使って自ら雑用をする代わりに、（検索、要約、ドラフト作成などの）雑用をわずかな費用で行い、短い結果を高価な親に報告します。CodexとClaude Codeにおける目標コマンドでの自律ループパターンは、高価なモデルが蒸留された結果のみを見るように、その委譲をどのように構造化するかを示しています。
ドルだけでなく、制限に関する注意点です。純粋な従量課金制ではなく、使用量制限付きプランの場合、ルーティングは割り当てをどれだけ長く使用できるかを拡張します。プレミアムモデルの予算をコミットメッセージに費やすことで、チームは木曜日までに壁にぶつかります。最近のClaude Codeの週次制限の増加は助けになりますが、割り当てを持続させるのはやはりルーティングです。
ツール出力と検索のトリミング
ツール出力は、気づかないうちに予算を食いつぶす静かな殺人者です。エージェントが実行するすべてのコマンドはテキストを返し、そのテキストはそのままコンテキストに戻され、その後、後続のすべてのターンで再生されます。単一のnpm installで数千行が返されることがあります。冗長なロギングを伴うテスト実行では数万トークンが返されることがあります。再生成されたロックファイルを含むgit diffは膨大になる可能性があります。エージェントがそのすべてを必要とすることはめったにありません。必要なのは合否と関連する失敗です。
これをきれいに削減する戦術:
ソースでコマンドを静かにする。 エージェントは、コマンドが出力するすべてのものに対して料金を支払います。ツールを簡潔に設定します。
# 冗長（エージェントはすべての行に料金を支払う）:
npm test
# 静か（失敗と要約のみが返される）:
npm test --silent -- --reporter=dot
# 冗長:
npm install
# 静か:
npm install --silent --no-audit --no-fund
エージェントが見る前にフィルタリングする。 エージェントが実行するコマンドを制御できる場合、ノイズをパイプで除外し、シグナルのみが返るようにします。
# 重要な行のみがコンテキストに戻る:
pytest -q 2>&1 | tail -n 30
# 4,000行の完全な差分ではなく、差分統計:
git diff --stat
# 全ログをダンプする代わりに、失敗をgrepで検索:
npm test 2>&1 | grep -E "(FAIL|✗|Error)" | head -n 20
ファイル全体を読み込むよりも、ターゲットを絞った読み込みを優先する。 1つの関数を変更するために1,500行のファイルを読み込むのは純粋な無駄です。エージェントには、シンボルをgrepで検索し、ファイル全体ではなくその周辺のウィンドウを読み込むように促します。多くのエージェントは、プロンプトが誘導するとこれを行います（「ファイル全体ではなく、リトライを処理する関数のみを見つけて読み込んでください」）。大きなファイルの場合、これは約18,000トークンと約800トークンの差になります。
検索範囲を制限する。 エージェントがコードベース検索やドキュメントに対するRAGを行う場合、取得するチャンクの数とサイズを制限します。質問に答える200トークンのスニペットが10個あれば、質問を埋もれさせる800トークンのスニペットが50個あるよりも優れています。モデルが使用するかどうかにかかわらず、取得されたすべてのトークンに対して料金を支払います。
これらの変更はほとんどが一度限りの設定（テストレポーター、インストールフラグ、無視ファイル）であり、その後はすべての実行で永続的に効果を発揮するため、このリスト全体で最も費用対効果の高いものの一部です。
実行ごとのコストの測定と帰属
測定できないものは管理できません。「請求額が下がった」だけでは測定とは言えません。戦術が機能したかどうかを知るには、実行ごと、理想的にはタスクごとにコストを帰属させる必要があります。
APIがすでに提供しているデータから始めます。すべての応答には使用量オブジェクトが含まれています。これをキャプチャします。
u = response.usage
# ドル単位のおおよそのコスト; モデルのリアルタイム料金に置き換える。
INPUT_RATE = 3.00 / 1_000_000 # ベース入力 $/トークン (例示)
OUTPUT_RATE = 15.00 / 1_000_000 # 出力 $/トークン (例示)
CACHE_READ = 0.30 / 1_000_000 # ベース入力の約10%
CACHE_WRITE = 3.75 / 1_000_000 # ベース入力の約1.25倍 (5分キャッシュ)
cost = (
u.input_tokens * INPUT_RATE +
u.output_tokens * OUTPUT_RATE +
u.cache_read_input_tokens * CACHE_READ +
u.cache_creation_input_tokens * CACHE_WRITE
)
print(f"実行コスト ≈ ${cost:.4f} "
f"(入力={u.input_tokens} 出力={u.output_tokens} "
f"キャッシュ読み込み={u.cache_read_input_tokens})")
独自のラッパーではなく、エージェントCLIを使用する場合、3つのアプローチが機能します。
# 1. ほとんどのエージェントCLIは、セッションの使用量/コストコマンドを公開しています。
# 代表的なタスクの後にそれを確認し、その数値を記録します。
claude /cost
# 2. プロバイダーのコンソールはAPIキーごとの支出を報告します。
# 支出が1つの追跡不能な合計にプールされるのではなく、帰属できるように、
# エージェントごとまたはプロジェクトごとに専用のAPIキーを発行します。
# 3. 実行にタグを付けます。エージェントの呼び出しを、
# タイムスタンプ、タスクラベル、報告されたトークン数をCSVにログ記録する
# スクリプトでラップします。1週間分のそのCSVは、
# どのタスクが高価であるかを示します。
大規模なものについては、実行前に見積もりを行います。プロンプトと含める予定のファイルをトークナイザーに貼り付け（OpenAIの公開トークナイザーはサイズの健全性チェックに迅速な方法です）、カウントを確認します。「モジュール全体を含める」が90,000トークンで、ターゲットを絞ったバージョンが6,000トークンである場合、料金を支払う前に意思決定を見たことになります。
代表的なタスクごとに1つの数値を時系列で追跡します。「日々のリファクタリング実行」のコスト、「PRレビュー実行」のコストなどです。キャッシングをオンにしたり、サブタスクを安価なモデルに切り替えたりすると、その数値は変動するはずです。変動しない場合、その戦術はあなたが思っているほど機能しておらず、1ヶ月分の請求書ではなく、1回の実行の料金でそれを学んだことになります。
戦術の比較
| 戦術 | 典型的なトークン削減量 | 労力 |
|---|---|---|
| 作業セットのスコープを絞る（ファイル名を指定し、クロールさせない） | 実行あたりの入力で30～60% | 低 |
| 短く安定したメモリファイル | ターンごとに5～15% | 低 |
タスク間の/compactまたは/clear |
長いセッションで40～80% | 低 |
| 安定したプレフィックスでのプロンプトキャッシュ | キャッシュされたプレフィックスで約90% | 中 |
| モデルルーティング（安価な作業には安価なモデル） | ルーティングされたサブタスクで50～80% | 中 |
| 静か/フィルタリングされたツール出力 | ツールを多用する実行で20～50% | 低（一度限り） |
| ファイル全体を読み込むよりも、ターゲットを絞った読み込み | 大きなファイルの編集で70～95% | 低 |
| 制約された検索範囲 | RAGを多用するエージェントで30～60% | 中 |
| 実行ごとのコスト測定 | 直接的には0%；上記のすべてを可能にする | 低 |
節約範囲は例示であり、乗算的に積み重なります。個々の戦術による効果は、ベースラインの無駄によって異なります。
結論
エージェントのトークンコストのほとんどは自己責任であり、コマンドラインでそれを修正できます。無駄は、再送信されるコンテキスト、読み取らない出力、および現在のタスクには高価すぎるモデルに存在します。これらに対処すれば、作業の品質を損なうことなく請求額を削減できます。
まず低労力な項目から着手してください。スコープの絞り込み、静かな出力、簡潔なメモリファイルはコストがかからず、今後はすべての実行で効果を発揮します。その上にキャッシュとルーティングを重ねれば、その差は予算に計上できるほどになります。