Claude Code proxy 請求失敗：2.1.307 gateway 修正與 400 排錯

2.1.307：先分清 beta header 與 model alias 問題#

官方 v2.1.307 release於 2026-10-21 22<17> UTC 發布，台灣時間為 10 月 22 日 06<17>。它修正 custom ANTHROPIC_BASE_URL gateway 與 Foundry 路徑仍帶上 prompt-caching-scope beta header 的行為；官方說明該 header 在這些路徑沒有作用。若錯誤明確指向這個 beta header，應對照含 2.1.307 修正的版本，而非只套用 ToolSearch 的 2.1.305 門檻。

同版另修正設定 CLAUDE_CODE_DISABLE_1M_CONTEXT，同時使用 opus[1m] 這類帶 [1m] 後綴的 model alias，導致 model-not-found 的問題。這需要兩項條件同時核對，不能看到任何 model-not-found 就判定是這個回歸；真正的模型名稱錯誤、provider 沒提供該模型或帳號無權使用，仍需另外排查。

更新前後各做一次相同入口的最小請求，讓結果可比較：

1. 記錄 claude --version、啟動器與 provider 類型，並確認 IDE、終端或 runner 實際啟動的是哪個 binary。
2. 若錯誤指向 beta header，在內部 gateway 診斷中只保留相關 header 名稱及是否存在，不公開 header 值或完整請求。
3. 若錯誤是 model-not-found，核對實際 alias 及上述環境變數是否設定；保留同一 provider 路由，不把切換到另一個模型視為原條件已修復。
4. 用含修正的 client，經相同 gateway、啟動器與非敏感 prompt 再驗收。若仍失敗，依新的錯誤欄位繼續分流。

2.1.307 也記錄修正了 Claude apps gateway session 忽略 CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS 的問題，但這和不支援欄位的 HTTP 400 不同。設定有被採用，不代表任意拉長 timeout 就能解決 schema 錯誤。

以上依 release notes 與 gateway 文件檢閱，查核日期為 2026-10-22；沒有在真實 Foundry、企業 gateway 或上述 model alias 組合執行請求，也沒有把這些條件宣稱為使用者錯誤的已確認根因。

2.1.305 修正 ToolSearch 被拒絕後的請求失敗#

官方 v2.1.305 release於 2026-10-20 20<46> UTC 發布，台灣時間為 10 月 21 日 04<46>。它記錄一項 2.1.304 回歸：Vertex、Bedrock 或其他 provider 的 endpoint／gateway 拒絕 tool search，以及 gateway 禁止 ToolSearch 或 --tools 沒列出它的情況，可能使每次請求失敗。修正後 client 會在這條被拒絕的路徑重試時不帶它。

這是特定失敗的相容處理，不是允許繞過 gateway 政策，也不保證每個第三方 gateway 都相容。不要為了測試就把 ToolSearch 加回企業禁止清單之外，或移除原本必須經過的代理。

另一個容易混淆的修正已在 v2.1.304：gateway 回報 context_management: Extra inputs are not permitted 時，client 會不帶該欄位重送。它和 2.1.304 新引入的 ToolSearch 回歸是不同項目；看到 context_management 的錯誤，不要改稱 ToolSearch 問題。

歷史案例：2.1.275 的 advisor_20260301#

如果你在 2026 年 9 月 18 日更新 Claude Code 後，所有請求都在 proxy 或 gateway 回傳類似下面的錯誤：

1
400 ... Input tag 'advisor_20260301' ...

先不要把它當成一般 API key、網路或 prompt 問題。Claude Code 官方在 v2.1.276 的 release notes 明確記錄：v2.1.275 曾造成 ANTHROPIC_BASE_URL 指向 proxy 或 gateway 時，每個請求都失敗；v2.1.276 修正這個回歸。

本節保留的歷史症狀範圍是：版本是 2.1.275 附近、所有請求都失敗、錯誤包含 advisor_20260301，而且請求經過自訂代理路徑。其他 400 錯誤仍要依照代理、帳號與 API 回應內容另外排查。

先用三個條件確認是不是同一個問題#

如果只有某個模型、某種 prompt 或某個 workspace 失敗，先不要直接套用本文結論。先保存不含 token、prompt 內容與個資的錯誤摘要，並用一個空白測試請求確認範圍。

最短修復路徑：更新後走同一個 proxy 重測#

官方 release note 的修復版本是 v2.1.276。因此安全的第一步是更新 Claude Code，再確認實際執行的 binary 已經切換：

1
claude --version
2
claude update
3
claude --version

如果你的 Claude Code 是由套件管理器、企業軟體目錄或自動部署流程安裝，請使用那個安裝來源的更新方式；重點不是某一個指令，而是最後執行的版本至少是 2.1.276，或更晚的修正版。

更新後不要先移除 proxy，也不要改成另一個 API endpoint 來「證明」問題消失。用同一個 ANTHROPIC_BASE_URL、同一組非敏感測試 prompt 和同一個 workspace 重測，才能知道原本的代理路徑已恢復。

不暴露秘密的本機確認#

在 macOS 或 Linux，可以先確認版本、binary 路徑和代理變數是否存在；不要把完整 URL、query string 或環境變數值貼到 issue：

1
claude --version
2
command -v claude
3
claude doctor
4

5
if [ -n "${ANTHROPIC_BASE_URL:-}" ]; then
6
  echo "ANTHROPIC_BASE_URL is configured"
7
else
8
  echo "ANTHROPIC_BASE_URL is not configured"
9
fi

Windows PowerShell 可用：

1
claude --version
2
Get-Command claude
3
claude doctor
4

5
if ($env:ANTHROPIC_BASE_URL) {
6
  'ANTHROPIC_BASE_URL is configured'
7
} else {
8
  'ANTHROPIC_BASE_URL is not configured'
9
}

若版本輸出已是 2.1.276，卻仍看見同一個錯誤，下一個檢查點是「你更新的 binary 是否就是實際執行的 binary」。command -v、Get-Command、企業 wrapper 和 shell cache 都可能讓終端仍呼叫舊版本；完成檢查後重開 shell，再用同一個命令確認。

更新後仍失敗，怎麼切開問題#

若已確認版本和執行路徑，請依序保留以下證據：

1. Client 版本：記錄 claude --version，不要只記「已更新」。
2. 代理是否存在：只記錄 ANTHROPIC_BASE_URL 已設定，不要公開完整值或 credential。
3. 錯誤摘要：保留 HTTP status、錯誤 tag 與 request timestamp；移除 prompt、token、header 與個資。
4. 代理觀測：在 proxy 的安全 log 中確認 request 是否有被改寫、拒絕或轉送到錯誤的 upstream。
5. 最小重現：用不含專案內容的簡短測試請求，在同一個 endpoint 再試一次。

這時不要把所有 400 都歸因於 2.1.275 回歸。若錯誤已改成 authentication、model not found、payload schema 或 upstream timeout，就應回到企業 proxy／gateway 文件檢查 header、路由與支援的 API 版本。Anthropic 的 proxy 文件也提醒，代理設定需依安裝方式和組織網路政策配置，不能只靠客戶端重試。

團隊部署時的防呆#

如果團隊用集中式安裝或容器執行 Claude Code，可以把以下檢查放在更新流程：

• 歷史 advisor 問題以 2.1.276 為修復起點；若涉及 2.1.304 ToolSearch 回歸，驗收門檻需提高到含 2.1.305 修正的版本。
• 在 CI 或開發環境用固定的無敏感測試請求，經過真實 proxy path 做 smoke test。
• 只在內部安全 log 紀錄 client version、proxy route、status 與 timestamp。
• 文件中明確說明 ANTHROPIC_BASE_URL 是否由 shell、wrapper、container 或管理工具注入。
• 不要用「直接連 Anthropic 成功」取代「經過公司 proxy 成功」的驗證。

這類 regression 的處理重點是讓版本、binary 和代理路徑可觀測。只貼一張 IDE 錯誤截圖，通常無法分辨是舊 client、代理重寫，還是 upstream 本身拒絕。

用相同入口確認修復，保留新的錯誤線索#

先以錯誤欄位與 client 版本對上官方記錄，再經原本的 provider、gateway 與啟動器驗收。舊 advisor 問題的修復起點是 2.1.276；2.1.304 的 ToolSearch 回歸則對照 2.1.305；custom gateway 的 prompt-caching-scope 及特定 [1m] alias 問題再對照 2.1.307。更新後若錯誤欄位或失敗範圍改變，保留新證據另行排查，不要繼續沿用同一個根因。

常見問題#