Feb 23, 2026

Claude Context Engineering 完整指南：從 Context Window 到 Prompt Caching 的全面解析

在大型語言模型的應用開發中，Context Engineering（上下文工程）已經成為與 Prompt Engineering 同等重要的核心技能。Anthropic 在 Claude API 中提供了一套完整的 Context Management 工具鏈，涵蓋從基礎的 Context Window 理解、到進階的 Compaction 壓縮、Context Editing 精細編輯、Prompt Caching 快取優化，再到 Token Counting 預估工具。本文將逐一深入解析這五大核心主題，確保不遺漏任何一個知識點。

一、Context Window：理解上下文窗口

基本概念

Context Window（上下文窗口）是指語言模型在生成回覆時能夠參考的所有文本總和，包含回覆本身。它不同於模型訓練時使用的龐大語料庫，而更像是模型的「工作記憶」（working memory）。較大的 context window 允許模型處理更複雜、更長的提示；較小的 context window 則可能限制模型在長對話中維持連貫性的能力。

標準 Context Window 行為

對於 API 請求，context window 具有以下特性：

漸進式 token 累積：隨著對話推進，每輪的用戶訊息和助手回覆都會累積在 context window 中，之前的輪次會被完整保留
線性增長模式：context 使用量隨每輪對話線性增長
200K token 容量：標準 context window 的總容量為 200,000 tokens
輸入-輸出流：每輪對話由輸入階段（包含所有歷史對話加當前用戶訊息）和輸出階段（生成文字回覆，成為未來輸入的一部分）組成

Extended Thinking 下的 Context Window

當啟用 Extended Thinking（延伸思考）時，所有輸入和輸出 token（包括思考用的 token）都會計入 context window 限制，但在多輪對話中有一些特殊機制：

Thinking budget tokens 是 max_tokens 參數的子集，按輸出 token 計費，並計入速率限制
搭配 Adaptive Thinking 時，Claude 會動態決定思考分配，因此實際思考 token 使用量會因請求而異
核心機制：自動剝離先前的思考區塊 — 之前輪次的 thinking blocks 會被 Claude API 自動從 context window 計算中剝離，不會成為模型在後續輪次中「看到」的對話歷史的一部分
你不需要自己手動剝離 thinking blocks，如果你把它們傳回 API，API 會自動處理
Thinking tokens 只在生成時作為輸出 token 計費一次
有效的 context window 計算公式變為：context_window = (input_tokens - previous_thinking_tokens) + current_turn_tokens
Thinking tokens 包括 thinking 區塊和 redacted_thinking 區塊

這個架構在 token 使用上非常高效，允許模型進行大量推理而不浪費 token。

Extended Thinking + Tool Use 的 Context Window

當結合 extended thinking 與 tool use 時，context window 的管理更為複雜，分為三個階段：

第一輪（First Turn）：

輸入包含：工具配置 + 用戶訊息
輸出包含：extended thinking + 文字回覆 + 工具使用請求
所有輸入和輸出元件都計入 context window

第二輪（Tool Result Handling）：

輸入包含：第一輪的所有區塊 + tool_result
重要：extended thinking 區塊必須與相應的工具結果一起回傳。這是唯一必須回傳 thinking blocks 的情況
在工具結果回傳後，Claude 只會回覆文字（不會有額外的 extended thinking，直到下一個 user 訊息）

第三輪（Third Step）：

前一輪的所有輸入和輸出會被帶入，但 thinking block 可以被丟棄（因為 Claude 已完成整個工具使用週期）
API 會自動為你剝離 thinking block（如果你傳回的話），你也可以在此階段自行剝離
由於有新的 User 輪次在工具使用週期之外，Claude 會生成新的 extended thinking block

關鍵注意事項：

在發布工具結果時，必須包含伴隨該特定工具請求的完整、未修改的 thinking block（包括簽名/已修訂部分）
系統使用加密簽名來驗證 thinking block 的真實性。如果你修改了 thinking blocks，API 會返回錯誤
Claude 4 模型支援 Interleaved Thinking（交錯思考），允許 Claude 在工具呼叫之間進行思考
Claude Sonnet 3.7 不支援 interleaved thinking

1M Token Context Window

Claude Opus 4.6、Sonnet 4.6、Sonnet 4.5 和 Sonnet 4 支援 100 萬 token 的 context window。要使用它，需要在 API 請求中包含 context-1m-2025-08-07 beta header：

from anthropic import Anthropic

client = Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Process this large document..."}],
    betas=["context-1m-2025-08-07"],
)

重要限制與須知：

Beta 狀態：功能可能在未來版本中修改或移除
使用層級要求：僅適用於 Usage Tier 4 或具有自訂速率限制的組織
可用平台：Claude API、Microsoft Foundry、Amazon Bedrock、Google Cloud Vertex AI
定價：超過 200K token 的請求自動以溢價計費（輸入 2 倍、輸出 1.5 倍）
速率限制：長 context 請求有專屬的速率限制
多模態考量：處理大量圖片或 PDF 時，要注意可能觸及請求大小限制

Context Awareness（上下文感知）

Claude Sonnet 4.6、Sonnet 4.5 和 Haiku 4.5 具備 Context Awareness 功能。此能力讓模型能夠追蹤其剩餘的 context window（即「token 預算」），從而更有效地執行任務和管理上下文。

運作方式：

在對話開始時，Claude 會收到關於其總 context window 的資訊：

<budget:token_budget>200000</budget:token_budget>

預算設為 200K tokens（標準）、500K tokens（claude.ai Enterprise）、或 1M tokens（beta，符合資格的組織）。

在每次工具呼叫後，Claude 會收到剩餘容量的更新：

<system_warning>Token usage: 35000/200000; 165000 remaining</system_warning>

這個感知能力的好處類似於在烹飪比賽中有計時器——Claude 4.5+ 模型明確告知模型剩餘的上下文，讓它能最大程度利用可用的 tokens。圖片 token 也包含在這些預算中。

特別適用場景：

需要持續專注的長時間 agent session
狀態轉換很重要的多 context window 工作流
需要精細 token 管理的複雜任務

較新模型的行為變化

從 Claude Sonnet 3.7 開始，當 prompt 和輸出 token 超過 context window 時，較新的 Claude 模型會返回驗證錯誤，而不是靜默截斷。這個變化提供了更可預測的行為，但需要更謹慎的 token 管理。

二、Compaction：伺服器端上下文壓縮

核心概念

Compaction 是 Anthropic 推薦的長對話 context 管理策略。它通過在接近 context window 限制時自動摘要較早的上下文，來延伸長對話和任務的有效 context 長度。

適用場景：

基於聊天的多輪對話，希望用戶能長時間使用同一個聊天
需要大量後續工作（通常是 tool use）且可能超過 200K context window 的任務導向提示

目前狀態：Beta 版，需要在 API 請求中包含 beta header compact-2026-01-12。支援 Zero Data Retention (ZDR)。

支援模型：Claude Opus 4.6、Claude Sonnet 4.6。

運作機制

當啟用 compaction 時：

偵測：當輸入 token 超過你指定的觸發閾值時
生成摘要：產生當前對話的摘要
建立 compaction block：建立包含摘要的 compaction 區塊
繼續回覆：用壓縮後的上下文繼續回覆

在後續請求中，將回覆附加到你的訊息中。API 會自動丟棄 compaction 區塊之前的所有訊息區塊，從摘要繼續對話。

基本用法

import anthropic

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Help me build a website"}]

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-6",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

# 附加回覆（包括任何 compaction block）以繼續對話
messages.append({"role": "assistant", "content": response.content})

參數配置

參數	類型	預設值	說明
`type`	string	必填	必須為 `"compact_20260112"`
`trigger`	object	150,000 tokens	觸發壓縮的時機，至少 50,000 tokens
`pause_after_compaction`	boolean	`false`	是否在生成壓縮摘要後暫停
`instructions`	string	`null`	自訂摘要提示，提供時會完全取代預設提示

觸發配置

可以配置何時觸發壓縮：

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-6",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": 150000},
            }
        ]
    },
)

自訂摘要指令

預設摘要提示會要求 Claude 寫下有助於在未來 context 中繼續完成任務的摘要，包括狀態、下一步、學習收穫等，並以 <summary></summary> 包裹。你可以透過 instructions 參數完全替換它：

"instructions": "Focus on preserving code snippets, variable names, and technical decisions."

壓縮後暫停（pause_after_compaction）

啟用 pause_after_compaction 後，API 會在生成壓縮摘要後暫停，讓你能在 API 繼續回覆前新增額外的內容區塊（例如保留最近的訊息或特定的指令導向訊息）。此時 API 會返回帶有 compaction stop reason 的訊息：

if response.stop_reason == "compaction":
    messages.append({"role": "assistant", "content": response.content})
    # 可以在這裡新增額外內容，然後繼續請求
    response = client.beta.messages.create(...)

強制執行總 Token 預算

結合 pause_after_compaction 和壓縮計數器，可以估算累計使用量，在達到預算時優雅地結束任務：

TRIGGER_THRESHOLD = 100_000
TOTAL_TOKEN_BUDGET = 3_000_000
n_compactions = 0

# ... 在壓縮發生時 ...
if response.stop_reason == "compaction":
    n_compactions += 1
    if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET:
        messages.append({
            "role": "user",
            "content": "Please wrap up your current work and summarize the final state.",
        })

處理 Compaction Blocks

當壓縮觸發時，API 在助手回覆開頭返回一個 compaction 區塊：

{
  "content": [
    {
      "type": "compaction",
      "content": "Summary of the conversation: The user requested help..."
    },
    {
      "type": "text",
      "text": "Based on our conversation so far..."
    }
  ]
}

你必須在後續請求中回傳 compaction 區塊以繼續對話。最簡單的方式是將整個回覆內容附加到你的訊息中。當 API 收到 compaction 區塊時，它之前的所有內容區塊都會被忽略。你可以選擇保留原始訊息讓 API 自動處理移除，或手動丟棄被壓縮的訊息。

Streaming 行為

在啟用 compaction 的串流回覆中，compaction 區塊的串流方式與文字區塊不同：你會收到一個 content_block_start 事件，接著是一個帶有完整摘要內容的 content_block_delta（沒有中間串流），然後是 content_block_stop 事件。

搭配 Prompt Caching

Compaction 與 prompt caching 配合良好。你可以在 compaction 區塊上添加 cache_control 斷點來快取摘要內容。原始被壓縮的內容會被忽略。

最大化快取命中率的技巧：在 system prompt 結尾添加 cache_control 斷點，這樣系統提示會與對話分開快取。當壓縮發生時，系統提示的快取保持有效，只有壓縮摘要需要被寫入新的快取條目。

理解 Usage

Compaction 需要額外的取樣步驟，會影響速率限制和計費：

{
  "usage": {
    "input_tokens": 45000,
    "output_tokens": 1234,
    "iterations": [
      {"type": "compaction", "input_tokens": 180000, "output_tokens": 3500},
      {"type": "message", "input_tokens": 23000, "output_tokens": 1000}
    ]
  }
}

重要：頂層的 input_tokens 和 output_tokens 不包含壓縮迭代的使用量。要計算實際計費的總 token，需要加總 usage.iterations 陣列中的所有條目。重新應用之前的 compaction 區塊不會產生額外的壓縮費用。

與其他功能結合

Server Tools：使用伺服器工具（如 web search）時，壓縮觸發在每個取樣迭代開始時檢查。根據觸發閾值和生成的輸出量，可能在單一請求中多次發生壓縮
Token Counting：token 計數端點會應用已有的 compaction 區塊但不會觸發新的壓縮

目前限制

用於摘要的模型與請求中指定的模型相同，沒有選項使用不同（例如更便宜的）模型來生成摘要。

三、Context Editing：精細化的上下文編輯

概覽

Context Editing 允許你在對話歷史增長時選擇性地清除特定內容，幫助你優化成本並保持在 context window 限制內。包含三種策略：

Tool Result Clearing — 最適合大量使用工具的 agentic 工作流
Thinking Block Clearing — 管理 extended thinking 時的 thinking blocks
Client-side SDK Compaction — SDK 端的摘要式 context 管理（推薦使用伺服器端 compaction）

伺服器端 vs 客戶端

方式	執行位置	策略	運作方式
伺服器端	API	Tool result clearing、Thinking block clearing	在 prompt 到達 Claude 之前應用，清除對話歷史中的特定內容
客戶端	SDK	Compaction	在 Python/TypeScript SDK 使用 `tool_runner` 時可用，生成摘要並替換完整對話歷史

Beta 狀態：需要 beta header context-management-2025-06-27。

支援模型：Claude Opus 4.6、Opus 4.5、Opus 4.1、Opus 4、Sonnet 4.6、Sonnet 4.5、Sonnet 4、Haiku 4.5。

Tool Result Clearing

clear_tool_uses_20250919 策略在對話 context 超過閾值時清除工具結果。API 自動按時間順序清除最舊的工具結果，每個被清除的結果會被替換為佔位文字，讓 Claude 知道它已被移除。

配置選項：

配置項	預設值	說明
`trigger`	100,000 input tokens	定義何時觸發清除
`keep`	3 tool uses	清除後保留多少最近的工具使用/結果對
`clear_at_least`	None	每次觸發時確保清除的最少 token 數
`exclude_tools`	None	永遠不應被清除的工具名稱列表
`clear_tool_inputs`	`false`	是否一併清除工具呼叫參數（預設只清除工具結果）

範例：

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    messages=messages,
    tools=[...],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},
                "keep": {"type": "tool_uses", "value": 3},
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                "exclude_tools": ["web_search"],
            }
        ]
    },
)

Thinking Block Clearing

clear_thinking_20251015 策略管理 extended thinking 啟用時的 thinking 區塊。

預設行為：當 extended thinking 啟用但未配置此策略時，API 自動只保留最後一個助手輪次的 thinking blocks（等同於 keep: {type: "thinking_turns", value: 1}）。

配置選項：

keep: {type: "thinking_turns", value: N} — 保留最後 N 個含有 thinking blocks 的助手輪次（N 必須 > 0）
keep: "all" — 保留所有 thinking blocks（最大化快取命中率）

// 保留最後 3 個助手輪次的 thinking blocks
{
  "type": "clear_thinking_20251015",
  "keep": {"type": "thinking_turns", "value": 3}
}

// 保留所有 thinking blocks
{
  "type": "clear_thinking_20251015",
  "keep": "all"
}

組合策略

可以同時使用 thinking block clearing 和 tool result clearing。重要：clear_thinking_20251015 策略必須在 edits 陣列中排在前面：

context_management={
    "edits": [
        {
            "type": "clear_thinking_20251015",
            "keep": {"type": "thinking_turns", "value": 2},
        },
        {
            "type": "clear_tool_uses_20250919",
            "trigger": {"type": "input_tokens", "value": 50000},
            "keep": {"type": "tool_uses", "value": 5},
        },
    ]
}

Context Editing 的重要特性

伺服器端執行：Context editing 在伺服器端、prompt 到達 Claude 之前應用。你的客戶端應用程式維護完整、未修改的對話歷史，不需要將客戶端狀態與編輯版本同步。

與 Prompt Caching 的互動：

Tool result clearing：清除內容時會使已快取的 prompt prefix 失效。使用 clear_at_least 參數確保每次清除足夠的 token，使快取失效值得
Thinking block clearing：當 thinking blocks 被保留時，prompt cache 被保留，啟用快取命中；當 thinking blocks 被清除時，清除點處的快取會失效

回覆中的 Context Editing 資訊

API 回覆中的 context_management 欄位會告訴你哪些 context edits 被應用了：

{
  "context_management": {
    "applied_edits": [
      {
        "type": "clear_thinking_20251015",
        "cleared_thinking_turns": 3,
        "cleared_input_tokens": 15000
      },
      {
        "type": "clear_tool_uses_20250919",
        "cleared_tool_uses": 8,
        "cleared_input_tokens": 50000
      }
    ]
  }
}

搭配 Memory Tool

Context editing 可以與 Memory Tool 結合使用。當對話上下文接近閾值時，Claude 會收到自動警告以保存重要資訊。這使 Claude 能在工具結果被清除前，將它們保存到記憶檔案中。例如，在檔案編輯工作流中，Claude 可以在 context 增長時將已完成的更改摘要寫入記憶檔案。

Client-side SDK Compaction

SDK 層面的 compaction 可透過 Python/TypeScript SDK 的 tool_runner 方法使用。但 Anthropic 推薦使用伺服器端 compaction。

運作方式：

SDK 在每次模型回覆後監控 token 使用量
當閾值被超過時，注入摘要提示作為用戶輪次
Claude 生成 <summary></summary> 標籤包裹的結構化摘要
SDK 提取摘要並替換整個訊息歷史

runner = client.beta.messages.tool_runner(
    model="claude-opus-4-6",
    max_tokens=4096,
    tools=[...],
    messages=[{"role": "user", "content": "Analyze all files..."}],
    compaction_control={"enabled": True, "context_token_threshold": 100000},
)

配置選項：

參數	預設值	說明
`enabled`	-	是否啟用自動壓縮
`context_token_threshold`	100,000	觸發壓縮的 token 數
`model`	與主模型相同	用於生成摘要的模型
`summary_prompt`	內建提示	自訂摘要提示

限制：使用伺服器端工具（如 web search）時，SDK 可能錯誤計算 token 使用量。cache_read_input_tokens 值包含了伺服器端工具多次內部 API 呼叫的累積讀取，而非你的實際對話上下文。

四、Prompt Caching：提示快取優化

核心概念

Prompt Caching 透過允許從提示中的特定前綴恢復來優化 API 使用。它能大幅降低重複任務或具有一致元素的提示的處理時間和成本。

隱私說明：Prompt caching 儲存 KV cache 表示和已快取內容的加密雜湊，但不儲存原始提示或回覆文本。

兩種啟用方式

Automatic Caching（自動快取）：在請求頂層新增一個 cache_control 欄位。系統自動將快取斷點應用到最後一個可快取的區塊，並隨對話增長向前移動。最適合多輪對話。
Explicit Cache Breakpoints（顯式快取斷點）：將 cache_control 直接放在個別內容區塊上，精細控制快取內容。

Automatic Caching

最簡單的啟用方式：

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are a helpful assistant.",
    messages=[...],
)

在多輪對話中的行為：

請求	快取行為
請求 1：System + User:A + Asst:B + User:C	全部寫入快取
請求 2：... + Asst:D + User:E	System~User:C 從快取讀取；Asst:D + User:E 寫入快取
請求 3：... + Asst:F + User:G	System~User:E 從快取讀取；Asst:F + User:G 寫入快取

TTL 支援：預設使用 5 分鐘 TTL，可指定 1 小時 TTL（2 倍基礎輸入 token 價格）：

"cache_control": {"type": "ephemeral", "ttl": "1h"}

與 block-level caching 結合：自動快取與顯式快取斷點相容。自動快取斷點使用 4 個可用斷點槽位中的一個。

邊界情況：

如果最後一個區塊已有相同 TTL 的顯式 cache_control，自動快取為 no-op
如果最後一個區塊有不同 TTL 的顯式 cache_control，API 返回 400 錯誤
如果已有 4 個顯式 block-level 斷點，API 返回 400 錯誤
如果最後一個區塊不符合自動快取斷點目標資格，系統會向後尋找最近的符合資格區塊

Explicit Cache Breakpoints

將靜態內容放在 prompt 開頭，用 cache_control 參數標記可重用內容的結尾。

快取前綴的建立順序：tools → system → messages。每個層級建立在前一個層級之上。

自動前綴檢查的三個核心原則：

快取金鑰是累積的：每個區塊的快取雜湊金鑰由依序雜湊所有前面的區塊生成
向後循序檢查：系統從你的顯式斷點向後檢查每個前面的區塊，確保獲得最長的快取命中
20 區塊回溯窗口：系統只在每個顯式 cache_control 斷點前檢查最多 20 個區塊。超過 20 個區塊未匹配就停止

理解回溯窗口的實例：

假設有 30 個內容區塊，你只在區塊 30 設了 cache_control：

不修改，發送區塊 31：系統檢查區塊 30（命中）。快取命中在區塊 30
修改區塊 25，發送區塊 31：系統向後檢查到區塊 25（未命中）→ 24（命中）。快取命中在區塊 24
修改區塊 5，發送區塊 31：系統向後檢查 20 個區塊後停止（到區塊 11）。區塊 5 超出 20 區塊窗口，無快取命中。但若你在區塊 5 設了顯式斷點，系統會從該斷點繼續檢查

何時使用多個斷點：最多可定義 4 個快取斷點，適用於：

不同區段以不同頻率變更
需要精確控制快取內容
確保超過最後斷點 20 個區塊前的內容也能被快取
在可編輯內容前放置斷點以保證快取命中

快取斷點本身不增加任何成本。

定價

類別	費用倍率
5 分鐘快取寫入	基礎輸入 token 價格的 1.25 倍
1 小時快取寫入	基礎輸入 token 價格的 2 倍
快取讀取	基礎輸入 token 價格的 0.1 倍

以 Claude Sonnet 4.5/4.6 為例：基礎輸入 $3/MTok，5 分鐘快取寫入$ 3.75/MTok，1 小時快取寫入 $6/MTok，快取命中$ 0.30/MTok。

支援模型

Claude Opus 4.6、Opus 4.5、Opus 4.1、Opus 4、Sonnet 4.6、Sonnet 4.5、Sonnet 4、Sonnet 3.7（已棄用）、Haiku 4.5、Haiku 3.5（已棄用）、Haiku 3。

快取限制

最低可快取 prompt 長度：

Claude Opus 4.6、Opus 4.5：4096 tokens
Claude Sonnet 4.6、Sonnet 4.5、Opus 4.1、Opus 4、Sonnet 4、Sonnet 3.7：1024 tokens
Claude Haiku 4.5：4096 tokens
Claude Haiku 3.5、Haiku 3：2048 tokens

更短的 prompt 即使標記了 cache_control 也無法被快取。

對於並行請求，快取條目只在第一個回覆開始後才可用。如果需要並行請求的快取命中，要等第一個回覆後再發送後續請求。

可快取的內容

Tools：tools 陣列中的工具定義
System messages：system 陣列中的內容區塊
Text messages：messages.content 陣列中的內容區塊（用戶和助手輪次）
Images & Documents：用戶輪次中的內容區塊
Tool use 和 tool results

不可快取的內容

Thinking blocks 不能直接用 cache_control 快取，但當出現在之前的助手輪次中時可以隨其他內容一起被快取
子內容區塊（如 citations）不能直接快取，應快取頂層區塊
空白文字區塊不能快取

什麼會使快取失效

快取遵循層級結構：tools → system → messages。

變更	Tools 快取	System 快取	Messages 快取
工具定義	失效	失效	失效
Web search 開關	保留	失效	失效
Citations 開關	保留	失效	失效
Speed 設定	保留	失效	失效
Tool choice	保留	保留	失效
圖片	保留	保留	失效
Thinking 參數	保留	保留	失效

追蹤快取效能

API 回覆中的 usage 欄位包含：

cache_creation_input_tokens：寫入快取的 token 數
cache_read_input_tokens：從快取讀取的 token 數
input_tokens：最後一個快取斷點之後的未快取 token 數

總輸入 token 計算：

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

Caching with Thinking Blocks

thinking blocks 的快取有特殊行為：

雖然不能用 cache_control 直接標記，但在後續 API 呼叫中傳回工具結果時，它們會作為請求內容的一部分被快取
從快取讀取時，thinking blocks 算作輸入 token
只提供 tool results 作為用戶訊息時，快取保持有效
新增非 tool-result 用戶內容時，所有之前的 thinking blocks 會被剝離，快取失效

快取儲存與共享

組織隔離：不同組織之間的快取完全隔離
精確匹配：快取命中要求 100% 完全相同的 prompt 段落
不影響輸出：prompt caching 不會影響輸出 token 生成

重要變更：自 2026 年 2 月 5 日起，prompt caching 從組織級隔離改為工作區級隔離。不同工作區即使在同一組織內也不共享快取。

1 小時快取持續時間

如果 5 分鐘太短，可以使用 1 小時快取（2 倍基礎輸入 token 價格）：

"cache_control": {"type": "ephemeral", "ttl": "1h"}

適用場景：

prompt 使用頻率低於每 5 分鐘但高於每小時
agentic 子代理需要超過 5 分鐘
儲存長聊天對話且用戶可能不會在 5 分鐘內回覆
延遲很重要且後續 prompt 可能在 5 分鐘後發送
想改善速率限制利用率（快取命中不計入速率限制）

混合不同 TTL：可以在同一請求中使用 1 小時和 5 分鐘快取，但較長 TTL 的快取條目必須出現在較短 TTL 之前。

搭配 Batches API

可以在 Batches API 請求中使用 prompt caching，但由於異步批次請求可以並行且順序不定，快取命中以盡力方式提供。1 小時快取可以改善命中率。

最佳實踐

多輪對話從 automatic caching 開始
需要不同變更頻率的區段時使用 explicit block-level breakpoints
快取穩定、可重用的內容（系統指令、背景資訊、大型上下文、常用工具定義）
將快取內容放在 prompt 開頭
在對話結尾和可編輯內容前設置快取斷點
定期分析快取命中率並調整策略

五、Token Counting：Token 計數

核心功能

Token Counting 讓你在將訊息發送給 Claude 之前確定其中的 token 數量，幫助你：

主動管理速率限制和成本
做出智慧的模型路由決策
優化 prompt 到特定長度

此功能符合 Zero Data Retention (ZDR) 資格。

基本用法

Token counting 端點接受與建立訊息相同的結構化輸入，支援 system prompts、tools、images 和 PDFs：

import anthropic

client = anthropic.Anthropic()

response = client.messages.count_tokens(
    model="claude-opus-4-6",
    system="You are a scientist",
    messages=[{"role": "user", "content": "Hello, Claude"}],
)

print(response.json())  # {"input_tokens": 14}

重要提醒：

Token 計數應視為估計值，實際建立訊息時使用的輸入 token 可能有小幅差異
Token 計數可能包含 Anthropic 為系統優化自動新增的 token，但你不會為系統新增的 token 付費
所有活躍模型都支援 token counting

支援的內容類型

基本訊息：文字訊息和系統提示
含工具的訊息：Server tool token 計數只適用於第一次取樣呼叫
含圖片的訊息：支援 base64 編碼的圖片
含 Extended Thinking 的訊息：之前助手輪次的 thinking blocks 會被忽略，不計入輸入 token；當前助手輪次的 thinking 則計入
含 PDF 的訊息：支援 base64 編碼的 PDF，與 Messages API 相同的限制

與 Context Management 結合

Token counting 端點支援 context management，可以預覽 context editing 應用後的 token 使用量：

response = client.beta.messages.count_tokens(
    model="claude-opus-4-6",
    messages=[...],
    tools=[...],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [{"type": "clear_tool_uses_20250919", ...}]
    },
)

print(f"Original tokens: {response.context_management['original_input_tokens']}")
print(f"After clearing: {response.input_tokens}")

回覆會顯示 context management 應用後的最終 token 計數（input_tokens）和清除前的原始 token 計數（original_input_tokens）。

定價與速率限制

Token counting 免費使用，但受每分鐘請求數（RPM）速率限制：

使用層級	每分鐘請求數 (RPM)
1	100
2	2,000
3	4,000
4	8,000

Token counting 和訊息建立有獨立的速率限制，使用一個不會計入另一個的限制。

Token counting 不使用 prompt caching——雖然你可以在 token counting 請求中提供 cache_control 區塊，但 prompt caching 只在實際建立訊息時發生。

策略選擇指南

面對 Claude API 提供的多種 context management 工具，如何選擇？

長對話 / Agentic 工作流：首選 Server-side Compaction，零整合複雜度且效果最佳。

大量工具呼叫的 Agent：搭配 Tool Result Clearing，自動清除不再需要的舊工具結果，同時可結合 Memory Tool 保存重要資訊。

使用 Extended Thinking：配置 Thinking Block Clearing，根據是否需要快取優化來決定保留策略。

重複性高的請求：使用 Prompt Caching（自動或顯式），可大幅降低成本（快取命中只需基礎價格的 10%）。

發送前預估：使用 Token Counting API，免費且不影響其他速率限制。

處理超大文件：申請 1M Token Context Window（Beta），搭配 Prompt Caching 優化成本。

這五個工具可以靈活組合。例如，一個典型的 agentic 工作流可能同時使用 Prompt Caching（快取系統提示和工具定義）、Compaction（處理超長對話）、Tool Result Clearing（清理舊工具結果）、和 Token Counting（監控 token 使用量）。理解每個工具的適用場景和互動方式，是構建高效、可靠的 Claude 應用的關鍵。