常駐コンテキストコスト

セッションが送信するすべてのリクエストは、会話の前に同じプレフィックスを帯びています。システムプロンプト、宣言されたすべてのツールのスキーマ、コンテキスト（QWEN.md）ファイル、そしてスキル一覧です。このプレフィックスはすべてのターンで課金されます。質問に答えるだけのターンでもそうです。このページでは、その計測方法と削減方法を説明します。

Token cachingはプレフィックスの_価格_を下げるものです。このページは_プレフィックス_を小さくするものです。両者は組み合わせられます — プレフィックスが小さければ、キャッシュ時のコストも安くなります。

何に対して課金されているかを確認する


/context detail

/context はカテゴリごとの内訳を出力します。detail を付けると項目ごとの行 — 各組み込みツール、各MCPツール、各コンテキストファイル、各リストされたスキル — が追加され、どの項目が最もコストが高いかを確認できます。セッションの最初のターンで確認してください。会話がまだ空で、見えているものがすべてプレフィックスの状態です。

カテゴリは /context が報告するものに、2つの管理用行を加えたものです：startupContext（最初のユーザーターンとして送信される環境ブロック）と、カテゴリが割り当てられない残差を明示的に示す行です。これにより、各部分の合計が常に全体と一致します。

ウィンドウの割合ではなくアイドルコストを使う

コンテキストウィンドウの割合は維持できる目標にはなりません。分母が任意だからです。同じ設定でも、1Mコンテキストのモデルでは6.5%、128kのモデルでは37%と表示されます — テキストは同じ、コストも同じ、なのに数値は大きく異なります。代わりに以下を使います：

アイドルコスト — 1つの質問をしてツールを一切呼ばないセッションの入力トークン数。

これはモデルにもウィンドウにも依存せず、ツールスキーマからコンテキストファイルへテキストを移動しても見かけ上改善できません。もう1つの有用な指標は会話がプレフィックスを上回るまでにかかるターン数です：償却に20ターンかかるプレフィックスは、5ターンのセッションでは決して償却されません。

レバー（対策）、効果の高い順

1. 使っていない機能をオフにする

モデルに宣言される各ツールは、そのスキーマをすべてのリクエストに追加します。そのため、常駐ツールが大きいオプション機能をオフにすると、リクエストトークンを節約できる場合があります。遅延ツールは代わりに短いカタログエントリと、後での検索や呼び出しのコストだけで済みます。機能を無効化すると、そのツールはサブエージェントからも除去されますが、次のレバーでは必ずしもそうとは限りません。

2. 実際の使用に合わせて先行読み込みツールを絞り込む

tools.eager は、初期リクエストにスキーマを残す組み込みツールの許可リストです。それ以外は遅延になります：登録はされたまま、/tools にも表示されたまま、呼び出しも可能です — モデルが必要になったときに tool_search → tool_call ブリッジ経由でアクセスします。

許可リストの測定は、正しいベースラインに対して行ってください。_独自_のデフォルトでオンデマンドのツールは最初のリクエストにすでに存在せず、tools.toolSearch.threshold がデフォルトで 0 になるようになってからは何もプリロードされないため、許可リストが節約できるのは先行読み込みデフォルトのツールのうち保留するもののスキーマだけです — 組み込み表面全体ではありません。リストに数値を割り当てる前に、実際に実行しているバージョンで /context を再測定してください。


{
  "tools": {
    "eager": [
      "read_file",
      "write_file",
      "edit",
      "glob",
      "grep_search",
      "run_shell_command",
      "skill",
    ],
  },
}

使用する前に知っておくべき4つのポイント：

無効化ではない。 格下げされたツールも引き続き到達可能です。ツールを除去したい場合は、ツール全体の permissions.deny ルールまたは tools.disabled を使用してください。
一部ツールは対象外 であり、リストの設定に関わらず通常の読み込み動作を維持します：tool_search と tool_call（保留されたツールに到達するブリッジの2つの部分）、structured_output、プランモードのライフサイクルツール（enter_plan_mode、exit_plan_mode、ask_user_question）、task_stop、MCPツール（mcp__*）、Computer Useツール（computer_use__*）。task_stop と Computer Use ファミリーはデフォルトでオンデマンドなので、制限しても節約になりません。MCPツールは tools.toolSearch.* とサーバーごとの includeTools / excludeTools フィルターで管理され、tools.eager では残りのいずれも削除できません：それにはツール全体の permissions.deny ルール、tools.disabled エントリ、または --exclude-tools が必要です — ブリッジペアについては、tools.toolSearch.enabled: false で両方を一度に削除できます。ブリッジの半分を削除することは許可リストからの中立な回避策ではありません：通常の遅延ツール（すべてのMCPツール、オンデマンドのComputer Useファミリー）はその後すべてのリクエストに強制的に宣言されますが、保留されたツールはモデルに提供されず、ブリッジ経由で再読み込みできません — 登録は維持されるため、名前による直接呼び出しは通常の承認を経由します。
permissions.allow は節約にならない。 これは純粋な自動承認です：ツールの格下げ、非表示化、削除は行いません。承認モードも同様です。
ブリッジの両方が必要。 保留されたツールは tool_search で確認され、tool_call 経由で呼び出されます。tool_search 単体では呼び出せないスキーマを読むことしかできません。どちらかが未登録の場合 — tools.toolSearch.enabled: false は両方を拒否します。tool_search/tool_call のdenyルール、--exclude-tools エントリ、または tools.disabled エントリは一方を削除します — 許可リストは引き続きスキーマを保留し、それらを読み戻す手段はなくなり、格下げされたツールはそのセッションではモデルに提供されません（警告がログに記録されます）。登録は維持されるため、名前による直接呼び出しは通常の承認を経由します。通常の遅延ツールはその場合に先行読み込みで宣言されるフォールバックをしますが、tools.eager で格下げしたツールはしません。

tools.visible は、デフォルトでは遅延のツールであっても、事前に宣言しておきたい1つのツール用の脱出ハッチです。

エージェントとゴールの調整（agent、list_agents、get_goal、update_goal、propose_goal）はデフォルトで遅延です。tools.eager の設定は必要ありません。モデルは完全なスキーマの代わりに短い検出エントリを確認します。初回使用時にはブリッジ経由の検出が必要なので、最初のリクエストだけでなく、タスク全体のコストと委任/ゴール完了の成功率を比較してください。これらは通常の遅延ツールです：tools.visible、プリロード、および上記の不完全なブリッジの先行読み込みフォールバックが引き続き適用されます。プリロードは遅延候補プール全体で全か無かであり、これら5つの宣言は大きいため、セッション開始時にすべての遅延ツールを表示していた tools.toolSearch.threshold が、今度はそれらのうち何も表示しない場合があります。いずれかを変更した後は、/context を再測定してください。

3. シナリオのガイダンスをコンテキストファイルからスキルへ移動する

コンテキストファイルは、それが適用されるすべてのセッションのすべてのリクエストに、関連性のフィルタリングなしで連結されます。スキルは名前と説明のみがリストされます — ある計測サンプルでは、84スキルが平均約55トークンでした — そして呼び出されたときに本体が読み込まれます。また paths: でゲートされたスキルは、一致するファイルに触れられるまでリストされさえしません。

コンテキストファイルには常に真実であるものだけを残してください — アイデンティティ、用語、ハード制約 — 「XをするときはYをする」はスキルまたは paths: 条件付きルールに記述します。/context detail は各コンテキストファイルの名前を表示し、拡張機能のファイルについてはそれを所有する拡張機能の名前も表示します。

4. システムプロンプト、最後に

ベースプロンプトはすでに常駐カテゴリの中で最小であり、その約3分の1は編集すべきでないセキュリティと権限のテキストです。ゲートされたツールのガイダンスは宣言セットに従いますが、ブリッジ経由で到達可能なエージェントについては例外があります。それらのエントリで名前が挙げられている他のツールは引き続き宣言を必要とします。そのため、ツール表面をトリミングすると、そのガイダンスも縮小される場合があります。--system-prompt で全体を置き換えることは可能ですが、このページの中で最もリスクの高い変更です。行う場合は、アップグレードごとにアップストリームのプロンプトの差分を確認してください。

注意点

サブエージェントも遅延ツールを受け取る。 明示的なツールリストを宣言しないサブエージェントは、遅延ツールを含めすべての登録ツールのスキーマを受け取り、ToolSearchを経由しません。tools.eager と permissions.deny がそれに到達する唯一の制御手段です。プリロードしきい値は対象外です。
バックグラウンドメモリエージェントには完全なツールリストが必要であり、2つのリストは異なります。 プロジェクトDreamワーカーには6つのツール（read_file、grep_search、glob、run_shell_command、write_file、edit）が必要です。自動抽出には5つ — run_shell_command を除いた同じセットで、設計上これを拒否します。いずれかのエージェントが実際に保持するツールを拒否すると、エラーではなくサイレントに劣化します。そのため、宣言を削除するためだけに run_shell_command をグローバルに拒否しないでください。Dreamはまだそれを必要とします。
トークンは消えるのではなく移動する場合がある。 grep_search と glob を取り上げると、モデルはシェル経由で grep や find を使うかもしれず、その出力が会話に_land_します。新しい出力は最初に送信されたときに入力トークンを追加し、それを含む変更されていない履歴は後続のリクエストでプロバイダーのプレフィックスキャッシュにヒットするかもしれません。変更は、タスクごとの総入力トークン数、プロバイダーが報告するキャッシュ済みおよび未キャッシュの入力、および実際の請求額で判断し、プレフィックスだけでは判断しないでください。
再開されたセッションは必要なものを再送信する。 格下げされたツールが再開されたセッションの履歴に現れると、そのスキーマは自動的に戻ります。拒否されたツールは戻りません。
保留されたツールへの到達は、もはやプレフィックスを書き換えません — ただし以前は書き換えており、古いアドバイスはそう前提としています。 検出は tool_search → tool_call ブリッジを経由し、宣言されたツールリストはバイト単位で安定したままです。そのため、プロンプトキャッシュのプレフィックスはセッション途中の検出でも維持されます。コストは、保留されたツールの初回使用前の1回の追加ラウンドトリップだけです。これが tools.toolSearch.threshold がデフォルトで 0 になった理由です。遅延セットを毎ターン保持することが、もはやトレードの安い側ではなくなりました。_通常の_遅延ツール（MCPツールとオンデマンドの組み込み）のためにそのラウンドトリップを取り戻すためにのみ閾値を上げてください。それらは certainly に必要になるセッションでのみです — tools.eager で格下げしたツールは、どの閾値でもブリッジの後ろに残ります。プリロードはセッション開始時に実行され、MCPサーバーは通常その後に接続するため、新しい起動では閾値に関わらずMCPツールを宣言しません。それらは次のセッション開始（CLIでは /clear の後）、または QWEN_CODE_LEGACY_MCP_BLOCKING=1 の下で即座にプリロードに到達します。
プレフィックスキャッシュモデルは以前このトレードを反転させていました。遅延については、もはやそうではありません。 ディスカウントが変更されていないプレフィックスに依存するモデルでは、かつては宣言リストを同一に保つことが小さく保つことよりも重要でした — そのため、一部のデプロイメントではToolSearchを手動で無効化していました。保留されたツールへの到達はそのリストをバイト単位で安定したままにするため、その特定の理由は期限切れになりました — ただし tool_search の説明自体に記載されている1つの例外があります。ライブ履歴にそれへの直接呼び出しが含まれている場合、ツールセットの更新は保留されたツールを再宣言する可能性があり、それはプレフィックスを移動させます。プレフィックスの安定性は、セッション途中でプレフィックスを書き換える他のあらゆること（ターン間でコンテキストファイルを編集するなど）に対して引き続き反対の論拠となります。
スコープが漏洩する。 設定はそれらを読み取るすべてのクライアント（CLI、Web Shell、serve）に適用されるため、デプロイごとのツール表面には独自のスコープ設定が必要です。

節約を確認する

変更前のアイドルコストを記録する：新しいセッションで、簡単な質問を1つ、最初のターンに /context を実行。
1つずつレバーを適用してセッションを再起動し繰り返す — これらの設定のほとんどは起動時に読み込まれます。
独自のタスクセットで機能が生存したことを確認する：ツール呼び出しの成功率、tool_search が呼ばれる頻度、タスクの成果。モデルが探すことを思いつかない格下げツールは大きなエラーを出しません。ただ使われなくなるだけです。
プレフィックスだけでなく請求額を確認する — トークンが会話に移動する件の注意点を参照。