Claude 讀大檔回你 exceeds maximum allowed tokens：25,000 token、256 KB 與 allow_large 各管哪一段

有人在 anthropics/claude-code 的 issue #40357 裡，原封不動貼了 Claude 讀檔回給他的三行：

1
2
3

File content (125085 tokens) exceeds maximum allowed tokens (10000).
Use offset and limit parameters to read specific portions of the file,
or search for specific content instead of reading the whole file.

他要讀的東西很具體：draw.io 圖檔的 XML、DOCX 解開之後的 XML、產生出來的 JSON schema，資料密度高，動不動就很肥。繞路的方法他也寫得很老實，大檔先用 Bash 接 python 或 pandoc 處理過一手，再交給 Claude。

issue 開在 2026 年 3 月 28 日（UTC），標題直接把訴求寫出來：「Make Read tool file size limit configurable」。後半還掛了一段括號，說 Desktop app 上限是 10k tokens、CLI 是 25k。這組對照是回報者自己觀察到的，官方現行文件只寫了 25,000，沒有提 Desktop 另有一套，所以那個 10000 我只能當成「他那台機器上的錯誤訊息印出來的數字」。

一個 12 萬 5 千 token 的檔案，撞上一個 1 萬的上限。差了十二倍多，分頁要翻十幾次。

第一個念頭：把上限調大

看到「maximum allowed tokens」，直覺就是去找那個 maximum 在哪裡改。答案確實存在，而且很早就有了：CHANGELOG 在 2.1.0（npm 上架時間 2026 年 1 月 7 日）加了 CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS。官方 env-vars 頁對它的說明是：「Override the default token limit for file reads, which is 25,000 tokens. Useful when you need to read larger files in full.」

可是調大這條路，有人走得並不順。issue #31674 在 3 月 7 日開出來，回報版本 2.1.71、Windows，標題寫著這個設定被忽略了。回報者在 settings 的 env 區塊這樣設：

1
2
3
4
5

{
  "env": {
    "CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS": "75000"
  }
}

這段 JSON 是回報者貼在 issue 裡的寫法，不是官方文件的範例。他描述的現象是，超過上限的檔案顯示成讀取成功、附上總行數，實際交給 agent 的只有前 2KB。這個 issue 3 月 30 日關了，到底是不是 bug、後來怎麼處理，我沒有往下追，只能說有人這樣回報過。

就算這個變數完全照文件運作，它也是一根很粗的槓桿。它改的是每一次 Read 的預設上限，不管你這次要讀的是 12 萬 token 的 XML，還是一份三百行的設定檔。

一次搬多少，跟整份收不收，是兩把尺

把 Read 想成影印店的櫃台。你遞一份原稿過去，店員一次最多幫你印一疊，疊的厚度有上限；原稿本身太厚的話，他連收都不收，請你指定要印第幾頁到第幾頁。

這兩條規矩，在官方 tools-reference 的「Large files」段落裡是分開寫的：「By default one call returns at most 25,000 tokens, or the value you set in CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS, and refuses a whole file over 256 KB, so Claude reads a larger file in pages with offset and limit.」

25,000 是 token，管的是單次 Read 能回傳多少。256 KB 是檔案大小，管的是整份檔案肯不肯一口氣讀。issue 裡的 10000 是回報者那次錯誤訊息印出來的上限，從措辭看跟 25,000 同樣是 token 數，只是數字不同。三個數字放在一起很容易混成「Claude 的讀檔上限」，可是 256 KB 量的是檔案大小，跟另外兩個 token 數根本不是同一種東西。環境變數文件只說它覆寫 25,000 那個 token 上限，沒提到 256 KB。

同一段接著把超過上限時 Claude 會收到什麼寫成兩種。整份檔案超過 token 上限，它會拿到第一頁，外加一則 PARTIAL view 提示，說明這次拿到了多少、要怎麼用 offset 和 limit 讀後面。整份檔案超過 256 KB，或者是用了 offset／limit 卻還是超過 token 上限，它拿到的是錯誤，叫它改讀其中一段，或改用 Grep 找特定內容。

有個地方很容易讀過去：已經乖乖分頁了，只是那一頁切太大，換來的反而是錯誤，不是 PARTIAL view。印第一疊的通融，只給「整份遞過來」的人。

兩條界線哪一條先觸發，文件沒寫先後。這篇的內容，我只讀了文件與 issue，沒有實際跑過。

三個版本，三次改規矩

照 CHANGELOG 逐版排，跟大檔有關的改動是這三條（日期是 npm 上架時間，UTC）：

#40357 撞到的那三行錯誤，是 2.1.145 之前的行為。2.1.145 之後，整檔讀取如果只是超過 token 上限，Claude 會先拿到第一頁和一張說明紙條，而不是一句退件；檔案要是同時超過 256 KB，照文件拿到的仍是錯誤。那份 12 萬多 token 的檔案有幾 KB，issue 裡沒寫。

文件跟上這個改動，晚了幾天。2.1.145 上架的同一天（5 月 19 日），有人開了 issue #60698，指出當時的文件還寫著「Files over a size threshold return an error rather than partial content」，跟新行為對不上；這個 issue 5 月 23 日關閉，現行文件已經改寫。讀這類行為描述時，文件和版本號最好一起看。

PARTIAL view 還有一個容易漏掉的後果，寫在同一頁的 Edit 段落：「a read cut short with a PARTIAL view notice doesn’t count.」文件說 Claude Opus 4.6、Claude Haiku 4.5 和更舊的模型，改檔之前一律要在這段對話裡讀過那個檔案，而被 PARTIAL view 截斷的那次不算讀過；較新的模型則是在讀檔不需要權限詢問、Read 工具也可用時，才能改沒讀過的檔。所以用前者改一份大檔，光讓它碰一下第一頁是不夠的。

allow_large：看你桌上還剩多少空位

回到影印店。2.1.296 加的 allow_large，等於店員改問另一個問題：你的桌子還放得下嗎？放得下，整份給你。

文件原文是：「On Claude Code v2.1.296 or later it can instead read the whole file, or a long line range, in one call by setting allow_large: true when it needs to, for example because you asked for the entire file. That read is sized against the room left in the session’s context window instead of the default limits.」env-vars 頁也補了一句，用 allow_large 讀的時候，只要 context window 還有空間，可以超過 CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS 設的上限。

這裡的主詞是 Claude。設不設 allow_large: true，是 Claude 在呼叫 Read 時自己判斷，文件舉的觸發例子是「你要求了整個檔案」。我讀到的 tools-reference 與 env-vars 段落裡，沒有任何讓你手動打開它的旗標或設定鍵。所以你能做的事很樸素：在要求裡講清楚，你要的是整份檔案。

例外寫在同一段最後一句：「Images, PDFs, and notebooks keep their limits.」圖片、PDF、notebook 照舊。PDF 超過 10 頁要用 pages 參數分段讀，例如 "1-5"，一次最多 20 頁；notebook 的 cell 加起來超過 256 KB 或超過 token 上限，回的是錯誤。

那現在我會怎麼處理

回頭問一句：你為什麼需要整份檔案？

#40357 那段錯誤訊息自己就給了另一條路，「search for specific content instead of reading the whole file」。一份 12 萬 token 的 XML，你要問的多半是其中某個節點、某個 id、某段 schema 定義，Grep 找到位置再用 offset、limit 讀那幾百行，context 只花在你真正要看的地方。整份讀進來，就是 12 萬多個 token 一次塞進這個 session 的 context。

我的立場是：Claude Code 在 2.1.296 以上，我不會去設 CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS。要片段，讓它搜尋加分頁；真的要整份，例如接下來要它改這個檔，就在要求裡直接說「整個檔案讀進來」，讓 allow_large 照 context 剩餘空間去判斷。全域調大上限，是替每一次讀取都放寬，而我需要放寬的，通常只有那一次。

會讓我改主意的情況有兩種。第一，你的版本還沒到 2.1.296，allow_large 根本不存在，環境變數就是你手上唯一能調的東西。第二，哪天文件把 allow_large 的實際上限怎麼算寫出來，結果發現它在 context 用掉一半之後就幾乎讀不了大檔，那對長 session 來說，事先把預設上限調高可能反而比較穩。這兩件事我現在都沒有證據，只是把條件先擺出來。

還沒解的部分也一樣擺著：Desktop app 是不是真的另有 10000 的上限、PARTIAL view 在 Desktop 上是否同樣生效、256 KB 跟 25,000 token 實際上誰先撞到，這三題我都沒有查證。

如果你想接著往下挖，下一站是 Read 之外的同族限制。圖片從 2.1.302 起超過 128 MB 的來源會被拒絕，PDF 有自己的 pages 分段規則，notebook 也有自己的 256 KB 和 100 MB 兩道門。下次撞到「exceeds」開頭的訊息時，先分清楚它量的是單次回傳的 token，還是整份檔案的大小。前者有環境變數可以調，後者文件沒給你開關，只能分頁、搜尋，或在要求裡講明要整份，讓 Claude 自己用 allow_large。