Skip to main content
本頁列出 Claude Code 顯示的執行時錯誤及如何從每個錯誤中復原，以及當回應似乎有問題但沒有錯誤時要檢查的內容。如需安裝錯誤（例如 command not found 或設定期間的 TLS 失敗），請參閱疑難排解安裝和登入。 除了包裝程式和 IDE 錯誤（由啟動程式列印而非 Claude Code 本身列印）外，這些錯誤和復原命令適用於 CLI、桌面應用程式和雲端工作階段，因為這三者都包裝相同的 Claude Code CLI。如需其他使用介面特定的問題，請參閱該使用介面頁面上的疑難排解部分。
Claude Code 呼叫 Claude API 以取得模型回應，因此大多數執行時錯誤對應到基礎 API 錯誤代碼。本頁涵蓋每個錯誤在 Claude Code 中的含義及如何復原。如需原始 HTTP 狀態代碼定義，請參閱 Claude Platform 錯誤參考。

​
找到您的錯誤

將您看到的訊息與下面的部分進行比對。

​
自動重試

Claude Code 會在顯示錯誤之前，以指數退避方式重試暫時性故障最多 10 次。它不會總是重試在 Claude 回應中途出現的故障。當您看到本頁面上的其中一個錯誤時，Claude Code 已經對該故障進行了適用的重試。 Claude Code 會重試這些故障：
  • 伺服器錯誤、過載回應，以及在 Claude 回應開始串流之前到達的請求逾時。
  • 在 Claude 完成思考之後、但在開始任何文字或工具呼叫之前到達的伺服器錯誤或過載回應。Claude Code 會在該點重試伺服器錯誤最多兩次。在 v2.1.284 之前，Claude Code 會在該點以錯誤結束回合。
  • 連線中斷。當連線在 Claude 完成其回應的任何部分（包括其思考）之前中途中斷時，Claude Code 會以相同的退避方式重新發出請求，並且回合會繼續，即使某些文字已經開始串流。當連線在 Claude 完成思考之後但在開始任何文字或工具呼叫之前中斷時，Claude Code 會改為快速連續重新發出請求最多兩次，如果連線在該點持續中斷，則以 Connection lost before a response was produced 結束回合。
  • Claude Code 偵測到的連線在您的電腦進入睡眠狀態時在請求中途被中斷。Claude Code 將其計為上述規則下的連線中斷；一旦重試標籤命名了具體原因，它會讀作 Connection lost while your computer was asleep，如果回合在 Claude 完成思考但在任何文字或工具呼叫之前結束，訊息會讀作 Your computer went to sleep before a response was produced。
  • 停滯的回應串流，當回應標頭已到達但 Claude 回應的任何部分都未到達，或當 Claude 完成思考但尚未開始任何文字或工具呼叫時：Claude Code 會中止停滯的連線，並最多再以串流方式發出一次請求。如果在 Claude 完成思考但在任何文字或工具呼叫之前回應停滯第二次，Claude Code 會以 The response stalled before a response was produced 結束回合。
  • 串流請求 API 從未以回應標頭回答，在 first-byte deadline 執行 的連線上：Claude Code 在截止時間中止它，並在重試預算內最多每個模型請求重新發送一次，然後如果該嘗試也未獲得回答，則以 No response from API 結束回合。當您設定 CLAUDE_CODE_RETRY_WATCHDOG 時，一次重試上限不適用。
  • 在 Claude 完成思考或開始任何文字或工具呼叫之前，被 API 輸出內容過濾器停止的串流回應。Claude Code 會在重試預算內重新發送請求一次，如果過濾器也停止了第二個回應，則顯示 Output blocked by content filtering policy。
  • 暫時性 429 節流，但不是閘道的支出限制 429，這不是節流；請參閱 Spend limit reached。
    • 當您使用 claude.ai 訂閱登入時，這包括不帶有您方案配額標頭的 429 節流。在 v2.1.199 之前，Claude Code 僅針對 API 金鑰和 Enterprise 登入重試這些節流。
  • 因為輸入加上 max_tokens 超過上下文限制而被拒絕的請求。以相同方式重新發送它會以相同方式失敗，所以 Claude Code 會以縮減的 max_tokens 重試，並在兩種情況下停止重試並改為壓縮：
    • 當沒有縮減可以容納時，例如當對話本身幾乎填滿上下文視窗時。
    • 當重試無法進一步縮減 max_tokens 時。在 v2.1.218 之前，Claude Code 可能會重新發送仍然無法容納的縮減請求，例如當延伸思考預算超過剩餘上下文時，直到重試預算用盡。
  • 在 Google Cloud 的 Agent Platform 上過期或遺失的 Google Cloud 憑證，或在您的機器上無法載入的 AWS 憑證。Claude Code 會捨棄其快取的憑證並重試最多兩次，然後報告錯誤，以便您可以立即重新驗證，如 Could not load AWS or Google Cloud credentials 下所述。在 v2.1.228 之前，Claude Code 會透過完整重試預算重試失敗的 Google Cloud 憑證，然後才顯示錯誤。
  • 來自 Anthropic API 的 401 或 403，直接或透過 LLM 閘道，而 apiKeyHelper 指令碼提供憑證。Claude Code 會重新執行指令碼並使用其新輸出重試，在完整重試預算內。當指令碼本身在重新執行時失敗時，Claude Code 會改為顯示 Your apiKeyHelper script is failing。
在 v2.1.227 之前，Connection lost before a response was produced 讀作 Connection closed while thinking, before producing a response，The response stalled before a response was produced 讀作 Response stalled while thinking, before producing a response。 Claude Code 不會重試這些故障：
  • TLS 憑證驗證失敗，例如 TLS 檢查代理伺服器、遺失的 NODE_EXTRA_CA_CERTS 套件，或過期的憑證。Claude Code 在第一次嘗試時報告錯誤，以便您可以立即修正憑證設定；請參閱 SSL certificate errors。Claude Code 仍會重試暫時性 TLS 條件，例如握手逾時。在 v2.1.199 之前，Claude Code 會透過完整重試預算重試憑證失敗，然後才顯示錯誤。
  • 伺服器錯誤、連線中斷，或停滯的串流在 Claude 完成文字區塊或工具呼叫之後到達，或在完成思考後開始一個但在完成回應之前。Claude Code 不會重新執行請求，因為這可能會執行相同的工具呼叫兩次。它會保留 Claude 完成的內容，執行 Claude 完成的任何工具呼叫，並從其結果繼續回合。關於您在互動式工作階段和非互動式工作階段中看到的內容，請閱讀 The response above may be incomplete。在 v2.1.199 之前，當伺服器錯誤在串流中途到達時，Claude Code 會捨棄部分輸出並將整個回合報告為錯誤。
  • 在 Claude 完成回應之後到達的故障：不需要重試任何內容，所以 Claude Code 會保留完整回應並正常結束回合。
  • Amazon Bedrock 串流回應具有意外的 content-type，因為重寫回應的閘道或代理伺服器會以相同方式重寫重試。需要 Claude Code v2.1.208 或更新版本。
  • 失敗的串流請求的非串流重試獲得成功狀態但 body 中沒有 Claude API 訊息。Claude Code 以該錯誤結束回合。
  • 您的組織的原則檢查拒絕的請求，其表現為帶有拒絕訊息的 API Error: 行。您的組織管理員使用 Inference hooks（Claude Enterprise 功能）設定檢查，訊息以他們設定的指示結尾，或預設告訴您聯絡他們。Claude Code 不會將被拒絕的請求重新發送到相同的模型或 備援模型，因為拒絕是關於請求的內容而不是模型。在 v2.1.239 之前，Claude Code 可能會在向您顯示拒絕之前，以非串流方式或在設定的備援模型上重新發送被拒絕的請求。

​
當 Claude Code 重試或等待時您看到的內容

重試時，微調器在錯誤標籤後顯示 Retrying in Ns · attempt x/y 倒數計時。標籤命名第一次嘗試的具體原因，用於您可以立即採取行動的故障：網路已關閉、TLS 握手失敗，或您達到速率限制。對於其他錯誤，它最初讀作 API error。從 v2.1.198 開始，它會切換到第三次嘗試的具體原因，或當 CLAUDE_CODE_MAX_RETRIES 允許少於三次時在最後一次嘗試；較早的版本僅在最後一次嘗試時切換。 從 v2.1.198 開始，在重試期間會隱藏通常的微調器提示。一旦錯誤原因被揭示，如果故障是 529 過載，倒數計時下方的行也會命名檢查服務狀態的位置：Anthropic API 上的 status.claude.com，或其他設定上的訊息中命名的提供者或閘道主機。 如果在請求仍待處理時，回應串流上 20 秒內沒有資料到達，微調器會在任何重試開始之前顯示 Waiting for API response · will retry in … · check your network。請求尚未失敗：倒數計時執行到 Claude Code 中止停滯連線的點。中止後，您看到的內容取決於回應已進行的程度：
  • 在 Claude 完成文字區塊或工具呼叫之前，或在完成思考後開始一個之前，Claude Code 會重試請求或以錯誤結束回合。Automatic retries 說明它重試哪些停滯以及重試多少次。
  • 在 Claude 完成文字區塊或工具呼叫之後，或在完成思考後開始一個之後，但在 Claude 完成回應之前，Claude Code 會保留 Claude 完成的內容，從 Claude 完成的任何工具呼叫繼續回合，並顯示 The response above may be incomplete。在非互動式工作階段中，以及在任何工作階段中的 subagent 回應，Claude Code 可能會先提示 Claude 繼續回應；該項目說明何時執行以及何時您仍在那裡看到通知。
  • 在 Claude 完成回應之後，Claude Code 正常結束回合。
一旦資料恢復或重試成功，橫幅會自動清除。如果它在每次嘗試時重新出現，請將其視為 network issue。在 v2.1.185 之前，橫幅在 10 秒後出現，措辭不同。 當 Claude 正在諮詢 advisor 時，橫幅在 90 秒無資料後出現，而不是 20 秒，因為長時間的 advisor 審查可能遠超過 20 秒都未發送任何內容。在 v2.1.214 之前，20 秒的閾值也適用於 advisor 呼叫，所以即使沒有任何問題，橫幅也會在 advisor 審查期間出現。

​
調整重試行為

您可以使用這些環境變數調整重試行為：

​
伺服器錯誤

大多數這些錯誤來自推論提供者：Anthropic 在 Anthropic API 上的服務，以及該提供者在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自訂閘道上的端點後面的服務。自動模式無法判斷動作的安全性和Agent 因 API 錯誤而提前終止也涵蓋您這一方的原因，例如無法叫用分類器模型的 Amazon Bedrock 帳戶或達到用量上限的 subagent。

​
API Error: 500 Internal server error

Claude Code 會顯示任何 5xx 回應的狀態碼和 API 的錯誤訊息。下面的範例顯示 Anthropic API 上的 500 回應：
結尾的句子會指明檢查服務健康狀況的位置，並因提供者而異。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 設定會指明該提供者的服務狀態。自訂 ANTHROPIC_BASE_URL 會指明閘道主機。 來自 API 本身的 5xx 表示 API 內部發生意外故障。它不是由您的提示詞、設定或帳戶引起的。 當代理伺服器、負載平衡器或閘道以 HTML 錯誤頁面回應時，訊息會顯示狀態碼和頁面的標題，例如 API Error: 502 Bad Gateway。對於沒有標題的頁面，訊息會改為顯示狀態碼及其標準名稱。在 v2.1.281 之前，當頁面有標題時狀態碼被丟棄，當頁面沒有標題時列印頁面的原始標記。 該怎麼做：
  • 檢查 status.claude.com 或訊息中指明的提供者狀態頁面，查看是否有活躍的事件
  • 等待一分鐘，然後再次傳送您的訊息。您的原始訊息仍在對話中，因此對於較長的提示詞，您可以輸入 try again 而不是貼上整個內容。
  • 如果錯誤持續存在且沒有發佈的事件，請執行 /feedback，以便 Anthropic 可以使用您的請求詳細資訊進行調查。如果您的環境中無法使用 /feedback，請參閱報告錯誤。

​
API Error: Repeated 529 Overloaded errors

API 在所有使用者中暫時達到容量。Claude Code 在顯示此訊息之前已經重試了多次：
結尾的句子因提供者而異，方式與上面的 500 錯誤相同。 529 不是您的用量上限，也不會計入您的配額。 該怎麼做：
  • 檢查 status.claude.com 或訊息中指明的提供者狀態頁面，查看容量通知
  • 在幾分鐘後重試
  • 執行 /model 並切換到不同的模型以繼續工作，因為容量是按模型追蹤的。Claude Code 會在一個模型負載特別高時提示您執行此操作，例如 Opus is experiencing high load, please use /model to switch to Sonnet。在 Fable 模型上，訊息會指明 Fable。 在 Claude Desktop 應用程式執行的工作階段中，例如 Code 標籤或 Cowork，訊息讀作 Opus is experiencing high load. Switch to Sonnet.，您可以使用應用程式的模型選擇器切換模型。

​
Request timed out

API 在連線截止時間之前沒有回應。
這可能在高負載期間或模型生成非常大的回應時發生。預設請求逾時為 10 分鐘。 該怎麼做：
  • 重試請求
  • 如果緩慢的網路或代理伺服器是原因，請按照自動重試中的說明提高 API_TIMEOUT_MS
  • 如果逾時頻繁且您的網路在其他方面狀況良好，請參閱下面的網路和連線錯誤

​
No response from API

Claude Code 傳送了串流請求，API 在第一個位元組的截止時間內沒有返回回應標頭，因此 Claude Code 中止了請求，而不是等待完整的 API_TIMEOUT_MS 請求逾時（預設為 10 分鐘）。Claude Code 最多再傳送一次請求，如果重試預算允許的話。當重試也沒有得到回應時，該回合以此訊息結束，該訊息顯示每次嘗試等待了多長時間。當您設定 CLAUDE_CODE_RETRY_WATCHDOG 時，一次重試的上限不適用，Claude Code 會在調整重試行為中描述的預算下重試。
Claude Code 分別為第一次嘗試的等待回應標頭和重試的等待設定：
  • 第一次嘗試：當您將其設定為 1 或更多時，CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS，限制在 10 秒到 30 分鐘之間。否則 Claude Code 會使用串流空閒監視程式中列出的位元組級監視程式逾時，因此改變該逾時的變數也會改變此等待。無論哪種方式，Claude Code 都會為請求正文的每 32KB 添加一秒。
  • 重試：比 API_TIMEOUT_MS 少一秒，預設略低於 10 分鐘，以便重試可以超過保持回應直到生成完成的代理伺服器或閘道。在 Amazon Bedrock 上，重試使用與第一次嘗試相同的截止時間，訊息顯示一個持續時間而不是兩個。
兩個等待都不超過正 API_TIMEOUT_MS 少一秒，正 API_TIMEOUT_MS 在 11 秒以下會關閉截止時間。位元組級監視程式僅在回應標頭到達後才開始，因此在此之後停止傳送位元組的回應遵循停滯串流規則而不是此截止時間。 該怎麼做：
  • 再次傳送您的訊息。您的原始訊息仍在對話中，因此對於較長的提示詞，您可以輸入 try again 而不是貼上整個內容。
  • 如果重複出現，將其視為網路或代理伺服器問題。
  • 如果您網路上的代理伺服器或閘道保持回應直到完成，請提高 API_TIMEOUT_MS 以便重試等待更長時間。在 Amazon Bedrock 上，也請提高 CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS。
  • 如果第一次嘗試持續逾時，然後重試成功，請提高 CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS 以便第一次嘗試也等待足夠長的時間。
在 v2.1.242 之前，Claude Code 在未回應的串流請求失敗之前等待完整的 API_TIMEOUT_MS 請求逾時（預設為 10 分鐘）。在 v2.1.261 之前，重試等待與第一次嘗試相同的截止時間，訊息沒有顯示持續時間。

​
The response above may be incomplete

串流請求在回應仍在進行中時失敗，在 Claude 完成一個文字區塊或工具呼叫之後，或在完成思考後開始一個。重新傳送請求可能會執行相同的工具呼叫兩次，因此 Claude Code 會保留 Claude 完成的輸出並附加此通知，而不是丟棄該回合。您看到的變體會指明原因：
  • Server error mid-response：中流過載或 5xx 伺服器錯誤。此變體需要 Claude Code v2.1.199 或更高版本；在此之前，該情況會丟棄部分輸出並將整個回合報告為錯誤。
  • Connection lost mid-response：連線中斷。您也會在代理伺服器或閘道在回應完成之前乾淨地結束回應正文時看到此變體。
  • Your computer went to sleep mid-response：Claude Code 偵測到您的電腦在回應串流時進入睡眠狀態。一旦您的電腦喚醒，Claude Code 會將連線視為中斷並停止從中讀取。
  • Part of the response never arrived：串流事件在 API 和 Claude Code 之間被丟棄，因此稍後的事件參考了從未到達的內容。在 v2.1.281 之前，此情況以 API Error: Content block not found 結束該回合。
  • The response stream was malformed：已完成的內容區塊到達了事件，或事件到達時已損壞。損壞的事件是指其資料不是有效 JSON、其內容遺失或其內容與事件類型不符的事件。在 v2.1.284 之前，當具有無效 JSON 的事件在 Claude 完成其思考、文字區塊或工具呼叫後到達時，解析器的原始錯誤（例如以 API Error: JSON Parse error 開頭的錯誤）會出現。
  • The response stopped arriving：連線保持開啟但停止傳遞資料，因此串流空閒監視程式中止了它。在 v2.1.222 之前，Claude Code 也可能在通過 ANTHROPIC_BASE_URL 或 ANTHROPIC_AWS_BASE_URL 到達的閘道連線上報告此故障，同時伺服器的保活 ping 仍在到達，因為它只計算那裡解析的回應事件；升級會停止這些虛假逾時在這些路由上。通過提供者基礎 URL（例如 ANTHROPIC_BEDROCK_BASE_URL）到達的閘道不被位元組監視程式包裝；請參閱串流空閒監視程式。
在 v2.1.227 之前，Connection lost mid-response 讀作 Connection closed mid-response，The response stopped arriving 讀作 Response stalled mid-stream。 當丟棄、重複或損壞的串流事件在 Claude 開始任何文字或工具呼叫之前到達時，您看不到此通知：
  • 如果 Claude 只完成了其思考，Claude Code 會重新發出請求。當重新發出的串流以相同方式中斷時，該回合以 Part of the response never arrived and no response was produced. Try again. 或 The response stream was malformed and no response was produced. Try again. 結束。
  • 如果沒有完成任何內容，Claude Code 會改為重新傳送請求而不進行串流。如果您使用 CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK 關閉了該備援，該回合會以 API Error: Content block not found 結束丟棄的事件或 API Error: Content block already closed 結束重複的事件。對於損壞的事件且備援關閉，該回合以 API Error: Stream event unreadable 或解析器的原始錯誤結束。
在四種情況下，Claude Code 會在不立即顯示此通知的情況下處理故障：
  • 在回應的早期，Claude Code 要麼重試故障，要麼以不同的錯誤結束回合。請參閱自動重試。
  • 當這些故障之一在 Claude 完成回應後到達時，Claude Code 會保留完整回應並正常結束回合，沒有此通知。在 v2.1.222 之前，Claude Code 在連線中斷或在回應完成後停滯時顯示此通知，並將回合報告為錯誤，儘管回應是完整的。
  • 在非互動式工作階段中，例如 -p 執行、Agent SDK 執行或雲端工作階段，當截斷回應在主對話中且包含文字但沒有工具呼叫時，您不必自己傳送 continue：Claude Code 會保留部分輸出並提示 Claude 從停止的地方繼續，最多連續三次。您只有在 Claude Code 用完這些繼續後才會看到此通知。在 v2.1.246 之前，Claude Code 在第一次截斷時以此通知結束非互動式回合。
  • 在 subagent 中，無論工作階段是否互動：當其截斷回應包含文字但沒有工具呼叫時，Claude Code 會提示 subagent 繼續。通知僅在這些繼續用完後才成為 subagent 的最後一條訊息。在 v2.1.257 之前，subagent 在第一次截斷時顯示此通知。
該怎麼做：
  • 在互動式工作階段中，閱讀螢幕上保留的回應：Claude Code 保留 Claude 在錯誤之前完成的每個區塊，但在回合結束時丟棄中斷的最後區塊，因此最後的句子或工具呼叫可能會遺失。回覆 continue 以讓 Claude 從其最後完成的區塊繼續。
  • 在非互動模式（-p）中：
    • 使用預設文字輸出，Claude Code 會列印它仍然從回合早期保留的最後完成的文字區塊，然後是此訊息。當它沒有保留任何內容時，Claude Code 會單獨列印此訊息，例如因為 Claude Code 在回合中間壓縮了對話並清除了該文字。在 v2.1.219 之前，Claude Code 在 -p 文字輸出中只列印此訊息並丟棄它已經產生的回應。
    • 使用 --output-format json 或 stream-json，Claude Code 會在 result 欄位中報告此訊息。
    • 一旦連線穩定，要繼續該回合，請恢復工作階段並按照繼續對話中的說明傳送 continue。

​
Auto mode cannot determine the safety of an action

自動模式用來分類動作的模型無法產生決定，因此自動模式沒有自動核准該動作。您看到的訊息取決於分類器如何失敗。 讀取、搜尋和編輯您的工作目錄內的內容會跳過分類器，因此它們在所有這些情況下都能繼續工作。 當分類器模型不可用時：
在互動式工作階段中，工具呼叫下方會出現一列淡色的 Not run · auto mode's check had no usable answer，而不是此訊息。按 Ctrl+O 可在逐字稿檢視器中閱讀該訊息。伺服器未傳回安全判決下的拒絕也會顯示相同的列。在 v2.1.296 之前，訊息會以紅色錯誤的形式顯示在呼叫下方。 當 Claude Code 可以判斷故障類別時，它會在 temporarily unavailable 後面的括號中指明該類別，例如 <model> is temporarily unavailable (rate-limited), so auto mode cannot determine the safety of <tool> right now。類別為 (rate-limited)、(overloaded)、(server error)、(timed out) 和 (connection failed)。如果 (timed out) 或 (connection failed) 重複，請檢查您的連線；請參閱無法連線到 API。在 v2.1.229 之前，訊息從不指明類別，讀作 Wait briefly and then try this action again。 當沒有類別符合時，訊息出現時括號中沒有類別；多個故障會產生該形式。在 Amazon Bedrock 上，包括 Mantle 端點，當您的 AWS 帳戶無法叫用訊息中指明的模型時，它也會出現，該故障在每次重試時重複，直到您的帳戶被授予存取該模型的權限。 該怎麼做：
  • 在幾秒後重試；Claude 會看到相同的訊息，通常會自動重試。暫時故障與自動模式資格無關；您不需要變更設定
  • 如果重試持續失敗，請繼續進行唯讀任務，稍後再回到被阻止的動作
  • 在 Amazon Bedrock 上，如果訊息在每次重試時返回，請檢查您的帳戶是否可以叫用它指明的模型：對於標準 Amazon Bedrock 模型，確認您的 IAM 政策允許叫用它；對於 Mantle 模型 ID，聯絡您的 AWS 帳戶團隊
當分類器請求失敗是因為您的 OAuth token 過期或被另一個工作階段輪換時，Claude Code 會重新整理 token 並重試請求一次，因此例行的 token 過期不會作為此訊息出現。在 v2.1.216 之前，過期或輪換的 token 會導致每個分類器請求失敗，自動模式會以此訊息拒絕每個檢查的動作，直到 token 被重新整理。 當分類器返回無法解析的回應時：
該怎麼做：
  • 重試該動作；這通常在下一次嘗試時成功
  • 執行 claude --debug 並重複該動作以在偵錯日誌中查看詳細資訊
當單獨的 API 安全檢查因為早期對話內容而阻止分類器請求時：
Claude Code 拒絕該動作，但告訴 Claude 這不是對該動作不安全的判斷，並繼續進行其他任務而不是重試。這些拒絕不計入自動模式的暫停閾值。在非互動式 -p 執行中，Claude Code 不會停止執行。Claude 接收的內容取決於它在哪裡請求該動作：
  • 對於 -p 執行中沒有 --input-format stream-json 的背景 subagent，Claude Code 會返回包含 Agent aborted: auto mode classifier request refused by the safety safeguard in headless mode 的錯誤結果
  • 在其他地方，包括互動式工作階段和 -p 執行的主對話，Claude Code 會將該拒絕返回給 Claude
在 v2.1.225 之前，Claude Code 計算這些拒絕以達到暫停閾值，並返回與真正分類器區塊相同的拒絕訊息。 該怎麼做：
  • 這不是對您的動作的決定。您對話中已有的內容在自動模式將對話傳送給分類器時觸發了 API 上的安全篩選器
  • 重試無法幫助；相同的對話內容將再次觸發篩選器
  • 在互動式工作階段中，切換到不同的權限模式，以便您可以在提示時核准該動作
  • 開始一個新的對話，不包含觸發內容
當對話增長超過分類器的上下文視窗時：
動作發生的情況取決於 Claude 在哪裡請求它：
  • 在互動式工作階段中，自動模式會改用該動作的正常權限提示，以便您可以手動核准或拒絕它
  • 對於非互動式 -p 執行中沒有 --input-format stream-json 的背景 subagent，Claude Code 會返回包含 Agent aborted: auto mode classifier transcript exceeded context window in headless mode 的錯誤結果，執行繼續
  • 在 -p 執行中的其他地方，沒有 --permission-prompt-tool，沒有提示可以改用，因此動作不執行，執行繼續
該怎麼做：
  • 在互動式工作階段中，在出現的提示中核准或拒絕該動作
  • 在互動式工作階段中，執行 /compact 以減少對話大小，以便後續動作再次適應分類器視窗

​
The server returned no safety verdict

在伺服器端分類器審查下，當伺服器沒有給出判決時，自動模式會拒絕一個動作。拒絕會在 Claude Code 可以判斷一個類別時在括號中指明該類別，例如 (timed out)：
訊息的其餘部分告訴 Claude 一次重試是否可以幫助。在某些這些拒絕之前，Claude Code 會等待，以便 Claude 的下一次嘗試不會立即跟隨。在互動式工作階段中等待期間，微調器顯示 Auto mode check unavailable 並帶有倒計時，按 Esc 會中斷該回合。 在連續十個回應都沒有判決後，自動模式會停止該回合：
停止訊息在每種工作階段中出現在不同的位置：
  • 在互動式工作階段中，訊息作為警告出現在逐字稿中，回合結束
  • 在非互動式 -p 執行中，執行結束並報告執行錯誤。使用預設文字輸出，訊息在 stderr 上列印。
  • 當 subagent 達到限制時，subagent 在完成之前停止，Claude 會收到它產生的任何內容，並附帶自動模式停止它的說明
該怎麼做：
  • 傳送另一條訊息以讓 Claude 再試一次。回應計數重新開始。
  • 如果停止重複且您的請求通過 LLM 閘道或代理伺服器，檢查它是否縮短串流回應或重寫它們。伺服器端分類器審查說明哪個閘道行為會導致拒絕，閘道相容性指南列出要保持不變的內容。
  • 在啟動 Claude Code 之前設定 CLAUDE_CODE_AUTO_MODE_SERVER=0 以改用其自己的分類器請求。在 v2.1.281 之前，Claude Code 在直接連線到 Anthropic API 時不讀取該變數。
  • 要自己核准動作，請改為切換出自動模式
在 v2.1.280 之前，Claude Code 立即拒絕來自沒有判決的回應的每個動作，從不停止該回合。

​
Agent terminated early due to an API error

subagent 的 API 請求終止失敗，例如因為達到用量上限或伺服器錯誤的重試用完，所以 subagent 在完成其任務之前停止。此訊息需要 Claude Code v2.1.199 或更高版本；在此之前，API 錯誤文字被返回給 Claude，就像它是 subagent 的結果一樣。
該怎麼做：
  • 將冒號後的錯誤詳細資訊與此頁面上對應的部分相符，例如用量上限或伺服器錯誤，並遵循該部分的步驟
  • 一旦基礎錯誤清除，請要求 Claude 重試任務或恢復 subagent
當速率限制、過載或伺服器錯誤中斷已經產生文字輸出的前景 subagent 時，Claude 會收到該部分輸出標記為不完整，而不是此錯誤。其唯一輸出是工具呼叫的 subagent 也會收到此錯誤；在 v2.1.199 中，該形狀返回了空部分結果。請參閱 subagent 中的 API 錯誤。

​
用量上限

本節中的大多數錯誤表示與您的帳戶或方案相關的配額已達到。其中三個的運作方式不同：Server is temporarily limiting requests 是與您的方案配額無關的伺服器端節流，Usage credits required for 1M context 是權利檢查而非耗盡的配額，The prompt to confirm went unanswered 表示用量點數同意提示已在未獲回應的情況下關閉，無論是否達到配額。

​
You’ve hit your session limit

訂閱方案包括滾動使用額度。當額度用完時，您會看到以下其中一條訊息：
Claude Code 會阻止進一步的請求，直到訊息中顯示的重設時間。工作階段和每週限制在所有模型中共享，因此切換模型不會恢復存取。Opus 和 Sonnet 限制各自僅適用於對該模型系列的請求，因此使用 /model 切換到該系列外的模型可讓您繼續工作。 在使用 claude.ai 訂閱登入的互動式工作階段中，Claude Code 也可以在開啟的工作階段中等待，並在重設後不久繼續中斷的任務。請參閱等待用量上限重設以了解您看到的內容、如何開始或取消等待，以及如何關閉自動繼續。在 v2.1.234 之前，Claude Code 不提供此等待功能。 使用量同時計入工作階段和每週額度。單次大量活動突發（例如大型工作流程扇出）可能會在工作階段視窗重設之前耗盡每週額度。 該怎麼做：
  • 等待錯誤中顯示的重設時間
  • 在桌面應用程式的 Code 標籤中，工作階段限制卡片提供 Auto-continue when limits reset 核取方塊。每週限制卡片則不提供。勾選後，桌面應用程式會在重設後重試中斷的回合，並在卡片上顯示重試時間。桌面核取方塊和 CLI 在 /config 中的 Continue automatically at usage limit 設定是分開的，因此請分別關閉每一個。
  • 對於 Opus 或 Sonnet 限制，執行 /model 並切換到該系列外的模型以繼續工作。每個模型都有自己的提示快取，因此下一個請求會重新讀取整個對話，沒有快取命中；請參閱切換模型
  • 執行 /usage 以查看您的方案限制和重設時間
  • 執行 /usage-credits 以在 Pro 和 Max 上購買額外使用量，或在 Team 和 Enterprise 上向您的管理員請求。請參閱付費方案的用量點數以了解如何計費。
  • 若要升級您的方案以獲得更高的基本限制，請參閱 claude.com/pricing
在視窗用完之前，Claude Code 可以警告您已使用大部分額度，訊息例如 You've used 85% of your session limit · resets 3:45pm。若要持續監視您的剩餘額度，請將 rate_limits 欄位新增至自訂狀態列，或在桌面應用程式中按一下模型選擇器旁的使用量環。

​
Usage credits required for 1M context

選定的模型使用 1M token 擴展上下文視窗，而您的方案僅透過用量點數包括它。
在 Claude 桌面應用程式執行的工作階段中，提示不會命名任何命令：它指向 claude.ai 使用量設定頁面，或在 Team 和 Enterprise 方案上說在 claude.ai/admin-settings/usage 開啟用量點數，或請您的管理員處理。 這是權利檢查，而非配額耗盡。即使您的工作階段和每週額度有剩餘容量，它也會觸發。請參閱擴展上下文以了解哪些方案直接包括 1M 上下文，哪些需要用量點數。 當此錯誤在對話中途出現，因為上下文增長超過 200K token 時，Claude Code 會自動將對話壓縮回標準上下文限制以下，並之後將工作階段保持在該限制，因此無需採取任何行動。在 v2.1.172 之前的版本上，錯誤會在每個後續請求（包括 /compact）上重複；在這些版本上執行 /clear 以恢復。以下步驟適用於您明確選擇 [1m] 模型的情況。 該怎麼做：
  • 執行 /model 並選擇不帶 [1m] 後綴的變體以回退到標準上下文視窗
  • 訊息提及 /usage-credits 的地方，執行它以在 Pro 和 Max 上為 1M 變體開啟計量計費，或在 Team 和 Enterprise 上向您的管理員請求用量點數。一旦用量點數開啟，請依訊息所說重新啟動 Claude Code 或開始新的工作階段。在此之前，工作階段會保持在標準上下文限制。
  • 如果 /model 後錯誤仍然存在，1M 模型 ID 可能在其他地方設定。請參閱設定您的模型以按優先順序檢查設定位置。
  • 若要從模型選擇器中完全移除 1M 變體，請設定 CLAUDE_CODE_DISABLE_1M_CONTEXT=1
在 v2.1.268 之前，訊息以 run /usage-credits to turn them on, or /model to switch to standard context 結尾，並未提及重新啟動。

​
The prompt to confirm went unanswered

如果您的帳戶需要 Fable 用量點數同意，Claude Code 會要求您在 Fable 請求計費用量點數之前確認。當同意提示在無人回應的情況下關閉時，Claude Code 會以以下其中一條訊息結束回合：
訊息會命名工作階段的 Fable 模型，因此在 Fable 5 上它們會讀作 continuing on Fable 5 和 Fable 5 now uses usage credits。在 v2.1.257 之前，第一條訊息以 Fable 5 limit reached 開頭。 這發生在 Remote Control 工作階段、背景工作階段、agent team 隊友工作階段，以及另一個應用程式透過 Agent SDK 託管的工作階段中。如需 Claude Code 何時關閉提示，請參閱 Fable 和用量點數。 該怎麼做：
  • 在工作階段執行所在的終端機或託管它的應用程式中，發送另一個提示詞，當同意提示重新出現時回答它。對於背景工作階段，請先從 agents 檢視附加到它。從 Remote Control 用戶端重新發送會再次顯示此訊息，因為用戶端無法顯示提示。
  • 執行 /model 以切換到不計費用量點數的模型
  • 若要給自己更多時間，請將 dialogExpiry 設定為更長的值或 "never"
在 v2.1.236 之前，此訊息不會出現：當 Remote Control 用戶端已連接時，Claude Code 會等待 60 秒以獲得答案，然後在您的預設模型上繼續回合。

​
Server is temporarily limiting requests

API 應用了與您的方案配額無關的短期節流。
Claude Code 透過真實限制回應所攜帶的統一配額標頭是否缺失來區分這些情況。自 v2.1.199 起，無論您如何驗證，這都會自動重試並進行退避，然後才顯示。在較早的版本上，使用 claude.ai 訂閱登入的工作階段在第一次出現時即讓回合失敗；只有 API 金鑰和 Enterprise 登入會重試它。 該怎麼做：

​
Request rejected (429)

您已達到為您的 API 金鑰、Amazon Bedrock 專案或 Google Cloud 專案設定的速率限制。
結尾的句子指出檢查服務健康狀況的位置，並因提供者而異。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 設定會指出該提供者的服務狀態，而不是 Anthropic 狀態頁面。自訂 ANTHROPIC_BASE_URL 會指出閘道主機。 當代理伺服器、負載平衡器或 Claude Code 與 API 之間的閘道以其自己的 HTML 429 頁面回應時，· 後面的文字是該頁面的標題（如果有的話），例如 Too Many Requests。在 v2.1.281 之前，整個頁面的標記會被列印在 · 後面。 該怎麼做：
  • 執行 /status 並確認作用中的憑證是您預期的憑證。環境中殘留的 ANTHROPIC_API_KEY 可能會透過低階金鑰而不是您的訂閱路由請求。
  • 檢查您的提供者主控台以了解作用中的限制，並在需要時請求更高的層級
  • 對於 Anthropic API 金鑰，請參閱速率限制參考以了解層級如何運作以及如何設定每個工作區的上限
  • 降低並行性：降低 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY、避免執行許多平行 subagent，或使用 /model 切換到較小的模型以進行高容量指令碼執行

​
You’ve hit your monthly spend limit

您的方案包含的使用量無法涵蓋此請求，而原本會為其付費的用量點數已達到支出限制。這發生在您的方案的其中一個使用視窗已用完時，或當請求是僅由用量點數支付的請求時，例如對計費至用量點數的模型的請求。訊息會指出是誰的限制阻止了您。· 後面的文字說明如何提高該限制，並因您的方案和您是否管理計費而異：
team's shared budget 是管理員分配給您所屬群組的集區預算；訊息不會命名該群組。channel's monthly spend limit 是工作階段執行所在的 Slack 頻道的預算，因此您的組織可能在其外仍有預算。 當您的方案的其中一個視窗是用完的視窗時，訊息也會說明該視窗何時重設，例如 · your session limit resets 3:45pm，存取會在那時恢復，無需任何人提高限制。在採用基於使用量計費的組織上，訊息會說 usage limit 而不是 spend limit，如 You've hit your individual usage limit。 如果您透過 Claude 應用程式閘道連接並看到小寫 spend limit reached，那是您的閘道營運者設定的上限；請參閱 Spend limit reached。 該怎麼做：
  • 在 Pro 和 Max 上，在 claude.ai 的設定 > 使用量中提高您的每月支出限制，或執行 /usage-credits
  • 在 Team 和 Enterprise 上，如果您管理計費，請在組織設定 > 使用量中提高限制，或請管理員提高。/usage-credits 會為您向管理員發送該請求
  • 對於頻道的限制，請組織擁有者或頻道的管理員在 claude.ai 上提高它。請參閱 Claude Tag 文件中的每頻道限制
  • 如果訊息指出您的方案視窗的重設時間，您可以改為等待它
  • 執行 /usage 以查看您的方案視窗和每個視窗何時重設

​
Spend limit reached

您透過 Claude 應用程式閘道連接，並已超過閘道營運者設定的支出上限。閘道會阻止您的請求，直到指定的期間重設或營運者提高上限。它將每個被阻止的 429 回應標記為 x-should-retry: false，因此 Claude Code 會顯示此訊息而不重試。
訊息會指出上限的期間和重設時間，當營運者設定了 blocked_message 時，他們的指示會跟在後面。在 v2.1.225 之前，訊息只顯示 spend limit reached；較舊版本上的閘道仍會發送該較短的形式。 該怎麼做：
  • 等待訊息指出的重設時間，或如果訊息包含營運者的指示，請遵循它們
  • 如果您經常達到上限，請要求您的閘道營運者提高上限
相關訊息 spend limit unavailable 表示閘道無法讀取其支出記錄，並作為預防措施阻止了請求，而不是因為超過您的上限。它通常會自行解除；如果持續發生，請告知您的閘道營運者。

​
Credit balance is too low

您的 Console 組織已用完預付點數，或 Claude Code 正在使用 Console API 金鑰發送您的請求，而您原本打算使用您的訂閱。
該怎麼做：
  • 如果您有 Pro、Max、Team 或 Enterprise 方案並看到此訊息，執行 /status 並檢查 API key 列。環境中已核准的 ANTHROPIC_API_KEY 會透過該金鑰而不是您的訂閱路由請求。在目前的 shell 中取消設定它，並從您的 shell 設定檔中移除它，然後重新啟動 claude。如果您還沒有使用您的訂閱登入，請執行 /login。
  • 在 platform.claude.com/settings/billing 新增點數，並考慮在那裡啟用自動儲值，以便在餘額歸零之前自動補充
  • 在 Console 中設定每個工作區的支出上限，以防止單個專案耗盡組織餘額。請參閱有效管理成本。

​
Could not update your spend limit

伺服器拒絕了您從達到支出限制時出現的提示中進行的支出限制變更。
當伺服器解釋拒絕原因時，訊息以該原因結尾，重試相同值會再次失敗。當失敗沒有伺服器提供的原因（例如連線中斷）時，訊息會顯示 Could not update your spend limit. Press Enter to retry.，重試可能會成功。在 v2.1.216 之前，Claude Code 對每個失敗都顯示通用形式。 該怎麼做：
  • 如果訊息包含原因，請選擇滿足它的限制，例如較低的金額
  • 如果訊息僅顯示通用形式，請重試；失敗可能是暫時的
  • 如果變更持續失敗，請改為在瀏覽器中從您的 claude.ai 計費設定進行變更

​
身分驗證錯誤

這些錯誤表示 Claude Code 無法向 API 證明您的身分。隨時執行 /status 即可查看目前使用中的憑證。

​
未登入

此工作階段沒有可用的有效憑證。
在由 Claude Desktop 應用程式執行的工作階段中（例如 Code 分頁或 Cowork），訊息會顯示為 Authentication required · Sign in again to continue，您需要從應用程式重新登入。 如果您在另一個使用相同設定目錄的 Claude Code 視窗中以 claude.ai 帳戶登入，顯示此訊息的互動式工作階段會自動開始使用該登入，無需重新啟動。 在 macOS 上的 v2.1.286 之前，您從另一個視窗登入後，工作階段可能仍持續顯示此訊息。在這些版本上，請重新啟動顯示此訊息的工作階段。 處理方式：
  • 執行 /login，以您的 Claude 訂閱或 Console 帳戶進行身分驗證
  • 如果您預期由環境變數進行身分驗證，請確認 ANTHROPIC_API_KEY 已在您啟動 claude 的 shell 中設定並匯出
  • 對於無法進行互動式登入的 CI 或自動化作業，請設定一個 apiKeyHelper 指令碼，在啟動時取得金鑰
  • 請參閱身分驗證優先順序，了解存在多個憑證時 Claude Code 會使用哪一個
如果您反覆被要求登入，請參閱未登入或 token 已過期，了解系統時鐘檢查與 macOS 憑證儲存的復原步驟。

​
無法解析身分驗證方式

工作階段在沒有任何憑證的情況下抵達了 API 用戶端。當 worker 在沒有憑證的情況下啟動時，背景工作階段與雲端工作階段會顯示此訊息。互動式、-p 與 Agent SDK 執行會將相同狀況回報為未登入，並且只會將此字串寫入其偵錯日誌，因此若您是在日誌中看到它，請改為依照該項目處理。
在目前的版本中，此錯誤表示 worker 程序沒有可用的憑證。在 v2.1.174 之前，即使已設定有效的憑證，指派給閒置預先初始化 worker 的背景工作階段仍可能以此方式失敗。在 v2.1.176 之前，在被認領前閒置的雲端工作階段也可能如此。請升級以復原。 處理方式：
  • 如果此訊息出現在背景或雲端工作階段中，而您的憑證已經設定好，請升級至 v2.1.176 或更新版本
  • 確認 ANTHROPIC_API_KEY、CLAUDE_CODE_OAUTH_TOKEN 或您的雲端供應商憑證已在啟動 worker 的環境中設定，而不只是在您的互動式 shell 中
  • 若使用 Agent SDK，請參閱快速入門中的身分驗證設定
  • 在相同環境的互動式工作階段中執行 /status，確認實際解析到的是哪個憑證來源

​
無效的 API 金鑰

ANTHROPIC_API_KEY 環境變數或 apiKeyHelper 指令碼傳回了被 API 拒絕的金鑰，或是 Claude Code 在傳送前就封鎖了來自 ANTHROPIC_API_KEY 的金鑰。
當訊息在 Fix external API key 之後還接著一段描述，例如 Invalid X-Api-Key header value from ANTHROPIC_API_KEY: it contains a line break at character 41 (120 characters on 2 lines).，表示 API 從未收到該金鑰。Claude Code 發現了 HTTP 標頭無法承載的字元，並在傳送前停止了請求。請參閱無效的請求標頭值，了解如何解讀該描述並修正值。 處理方式：
  • 檢查是否有拼字錯誤，並在 Console 中確認金鑰未被撤銷
  • 在同一個 shell 中執行 env | grep ANTHROPIC，或在 PowerShell 中執行 Get-ChildItem Env:ANTHROPIC*。direnv、dotenv shell 外掛以及 IDE 終端機等工具，可能會在您未明確設定的情況下，從專案中的 .env 檔案載入過時的金鑰。
  • 取消設定 ANTHROPIC_API_KEY 並執行 /login，改用訂閱進行身分驗證
  • 如果金鑰來自 apiKeyHelper 指令碼，請直接執行該指令碼，確認它會在 stdout 輸出有效的金鑰
  • 執行 /status，確認 Claude Code 實際使用的是哪個憑證來源

​
您的 apiKeyHelper 指令碼執行失敗

Claude Code 執行了您 apiKeyHelper 設定中的命令，但沒有取得金鑰。沒有金鑰時，請求會帶著預留位置憑證抵達 API，API 會以 401 拒絕它。終端機中的 Authentication 面板會顯示發生的是下列哪一種情況：
  • 命令以錯誤結束或逾時
  • 命令沒有在 stdout 輸出任何內容
  • 命令輸出了金鑰以外的內容，例如登入橫幅或日誌行。面板會顯示 returned output that cannot be used as an API key 並說明問題所在，但不會重複該輸出。在 v2.1.227 之前，Claude Code 會在去除前後空白後，直接傳送命令輸出的任何內容。
在非互動模式中，stderr 也會帶有具體原因，並以 apiKeyHelper failed: 為前綴。 在顯示此訊息之前，Claude Code 會重新執行指令碼並最多再重試請求兩次，因此失敗會在三次嘗試內浮現。在 v2.1.208 之前，Claude Code 會用完整個重試額度，以預留位置憑證重新傳送請求，然後回報一般的 401 身分驗證錯誤，而不是指令碼失敗。 在此情況下執行 /login 沒有幫助：只要該設定存在，helper 的輸出就會優先於已儲存的登入。 處理方式：
  • 直接在您的 shell 中執行 apiKeyHelper 中設定的命令，以重現失敗情況
  • 如果命令回報工作階段已過期，請向您的憑證提供者重新進行身分驗證，例如重新登入您的 SSO 或密鑰保管庫
  • 修正命令，使其只將金鑰輸出至 stdout，格式為單一可列印 ASCII token、最多 16,384 個字元，並以退出碼 0 結束。請參閱使用 apiKeyHelper 輪替憑證以取得可用的設定範例。
  • 執行 /status 以查看失敗情況，並確認 apiKeyHelper 是使用中的憑證來源。apiKeyHelper 列會顯示 Failing 以及最近一次失敗的詳細資訊，例如退出碼與命令的錯誤輸出，並會在下一次成功執行後消失。在 v2.1.274 之前，/status 只會顯示憑證來源，不會顯示失敗情況。
  • 每次命令失敗時，其退出碼與錯誤輸出也會出現在終端機中的 Authentication 面板中。在 v2.1.212 之前，該面板的標題為 Cloud authentication。

​
無效的請求標頭值

Claude Code 即將作為請求標頭傳送的值，包含 HTTP 標頭無法承載的字元：換行、NUL 位元組，或高於 U+00FF 的字元，例如彎引號或零寬度空格。Claude Code 會在傳送任何內容之前停止請求，並指出需要修正的變數或設定。常見原因是從文件或聊天中貼上的憑證帶有不可見字元或多餘的換行。 當 Claude Code 直接或透過 LLM 閘道向 Claude API 傳送請求時，會執行此檢查。在第三方雲端供應商（例如 Amazon Bedrock）上，Claude Code 不會在傳送前執行此檢查。
訊息的第一部分取決於錯誤值的來源：
  • Invalid auth token：來自 ANTHROPIC_AUTH_TOKEN 或 CLAUDE_CODE_OAUTH_TOKEN 的 bearer token
  • Invalid ANTHROPIC_CUSTOM_HEADERS：您在 ANTHROPIC_CUSTOM_HEADERS 中設定的標頭名稱或值。描述會指出是第幾個 Name: Value 組合有問題，例如 distinct header 2 of 3 parsed from ANTHROPIC_CUSTOM_HEADERS，但不會重複名稱或值，因為兩者都是您自行選擇的。
  • Invalid request header from the environment：Claude Code 從另一個環境變數複製到請求標頭中的值，例如 CLAUDE_AGENT_SDK_CLIENT_APP。描述會指出需要修正的變數。
Claude Code 會將此檢查攔截到的錯誤 ANTHROPIC_API_KEY 回報為無效的 API 金鑰，並附上相同的結尾描述。對於已儲存的錯誤 /login 憑證，則會回報為未登入；請執行 /login 儲存新的憑證。apiKeyHelper 指令碼的輸出永遠不會經過此檢查：Claude Code 會在指令碼執行時驗證它，HTTP 標頭無法承載的輸出會以您的 apiKeyHelper 指令碼執行失敗失敗。 在第二個 · 之後，訊息會描述問題，如以下完整範例所示：
位置從一開始計算字元。描述由固定片語與字元數組成，因此絕不會包含值本身。只有在問題字元是知名的不可見或排版字元時（例如位元組順序標記、零寬度空格或彎引號），描述才會指名該字元，其他字元一律回報為 a non-ASCII character。 處理方式：
  • 重新設定訊息所指的變數或設定，重新輸入回報位置附近的字元，而不是再次從相同來源貼上
  • 對於 ANTHROPIC_CUSTOM_HEADERS，每行保留一組 Name: Value，並重新撰寫訊息所指出的那一組
  • 執行 /status，確認使用中的是哪個憑證來源

​
此組織已被停用

Claude Code 正在使用來自已停用 Console 組織的過時 ANTHROPIC_API_KEY。當您有已儲存的訂閱登入時，該金鑰會覆寫它。
· 之後的提示取決於您已儲存的憑證：當您取消設定金鑰後有已儲存的 /login 可接手時，會出現第一種形式；當金鑰是您唯一的憑證時，會出現第二種形式。 環境變數優先於 /login，因此即使您有可用的 Pro 或 Max 訂閱，在 shell 設定檔中匯出或從 .env 檔案載入的金鑰仍會被使用。在非互動模式（-p）中，只要金鑰存在就一定會被使用。 處理方式：
  • 在目前的 shell 中取消設定 ANTHROPIC_API_KEY，並從您的 shell 設定檔中移除它，然後重新啟動 claude
  • 如果訊息顯示 Update or unset，表示您沒有可退回使用的已儲存登入。請取消設定金鑰並執行 /login，或將金鑰替換為來自使用中 Console 組織的金鑰。
  • 之後執行 /status，確認使用中的憑證是您的訂閱
  • 如果沒有設定任何環境變數而錯誤仍然存在，請聯絡支援團隊或以其他帳戶登入。

​
您的組織已停用 API 金鑰身分驗證

此訊息需要 Claude Code v2.1.169 或更新版本。您 Console 組織的管理員已關閉 API 金鑰身分驗證，因此 API 會拒絕 Claude Code 傳送的金鑰。· 之後的復原提示會依金鑰來源而不同：
最後一種形式出現在由 Claude Desktop 應用程式執行的工作階段中（例如 Code 分頁或 Cowork），您需要從應用程式重新登入。 環境變數與 apiKeyHelper 優先於 /login，因此只要其中任一項仍在提供金鑰，單獨執行 /login 並無幫助。請參閱身分驗證優先順序。 處理方式：
  • 如果訊息指名 ANTHROPIC_API_KEY，請在目前的 shell 中取消設定它，並從您的 shell 設定檔或 .env 檔案中移除，然後重新啟動 claude
  • 如果訊息指名 apiKeyHelper，請從您的 settings.json 中移除 apiKeyHelper 設定
  • 執行 /login，以您的 claude.ai 帳戶登入
  • 之後執行 /status，確認使用中的憑證是您的訂閱而非 API 金鑰
  • 如果您的自動化作業需要 API 金鑰身分驗證，請要求組織管理員在 Console 中重新啟用

​
您的組織已停用 Claude 訂閱存取

您的 Claude 組織不允許以訂閱登入方式登入 Claude Code。以相同帳戶再次執行 /login 會傳回相同的錯誤。
這是伺服器端的組織設定，因此無法透過本機設定、環境變數或 CLI 旗標覆寫。 Agent SDK 與 -p 非互動模式會將此回報為 oauth_org_not_allowed 錯誤代碼。 處理方式：
  • 請您的管理員為您的組織啟用 Claude Code 存取
  • 改用 Console API 金鑰而非訂閱進行身分驗證。設定方式請參閱 Claude Console 身分驗證。
  • 如果您是管理員卻看不到啟用存取的選項，請聯絡 Anthropic 支援

​
您組織的政策已停用 routine

您 Team 或 Enterprise 組織中的 Owner 已在組織層級關閉 routine。當您嘗試建立或執行 routine 時（例如從 claude.ai/code 上的 Routines UI），就會出現此錯誤。在 Claude Code v2.1.227 或更新版本上，相同的設定也會在 CLI 中隱藏 /schedule。
這是伺服器端設定，因此無法透過本機設定、環境變數或 CLI 旗標覆寫。 處理方式：

​
Remote Control 需要 Anthropic API

此工作階段並未直接與 Anthropic API 通訊，而這是 Remote Control 所必需的。
第二句說明了是什麼讓工作階段繞離了 Anthropic API；在 v2.1.219 之前，訊息只有第一句。視原因而定，訊息會指出：
  • CLAUDE_CODE_USE_* 供應商變數，例如 Amazon Bedrock 的 CLAUDE_CODE_USE_BEDROCK 或 Google Cloud’s Agent Platform 的 CLAUDE_CODE_USE_VERTEX
  • ANTHROPIC_BASE_URL 指向 api.anthropic.com 以外的主機，例如 LLM 閘道或代理伺服器，即使您以 claude.ai 登入亦然；在 v2.1.196 之前，自訂的 base URL 不會封鎖 Remote Control
  • 已設定 ANTHROPIC_UNIX_SOCKET，因此工作階段會透過本機 socket 傳送請求，而不是傳送至 api.anthropic.com
  • 透過 /login 進行的企業雲端閘道登入，此方式不支援 Remote Control，且沒有可取消設定的變數
處理方式：
  • 取消設定訊息所指的變數（例如 CLAUDE_CODE_USE_BEDROCK 或 ANTHROPIC_BASE_URL）並重新啟動工作階段，或從直接與 Anthropic API 通訊的工作階段啟動 Remote Control
  • 如果該變數未在您的 shell 中設定，請檢查設定檔中的 env 鍵，它會將環境變數套用至每個工作階段
  • 關於此訊息及其他 Remote Control 啟動訊息，請參閱 Remote Control 疑難排解

​
Remote Control 無法重新整理您的登入

Claude Code 以短期憑證執行即時的 Remote Control 連線，這些憑證是使用您已儲存的 claude.ai 登入取得並更新的。當 claude.ai 不再接受該登入，或 Claude Code 已沒有已儲存的登入時，Claude Code 會停止 Remote Control，並需要您重新登入。這兩種失敗都可能發生在 Claude Code 仍在連線時，或之後更新憑證時。 當 Claude Code 要求登入服務重新整理您已儲存的登入卻沒有得到回應時，它會讓 Remote Control 繼續執行，並在連線目前的憑證仍有效期間再次嘗試重新整理。當 Claude Code 無法連上登入服務、請求逾時，或服務失敗但未拒絕您的登入時，重新整理就會得不到回應。如果在該憑證到期時登入服務仍未回應，Claude Code 會停止 Remote Control 並回報 OAuth token refresh failed。 當 Claude Code 停止 Remote Control 時，會在警告以及以 Remote Control disconnected 開頭的逐字稿行中顯示原因。您的本機工作階段會在沒有 Remote Control 的情況下繼續執行。本節涵蓋以下幾行：
Claude Code 會在訊息中間指出原因：
  • Claude.ai login expired 與 Claude.ai login was rejected：claude.ai 不再接受您已儲存的登入 token，因為它已過期或被撤銷
  • OAuth token unavailable：當連線的憑證到期需要更新時，Claude Code 沒有已儲存的登入 token
  • OAuth token refresh failed：Claude Code 重新連線時，claude.ai 拒絕了您已儲存的登入 token，且重新整理 token 未產生新的 token
  • JWT refresh failed: no OAuth token：Claude Code 找不到可用於更新的已儲存登入 token
  • Signed out of Claude：您在這台機器上登出了，例如在另一個終端機中執行 /logout，因此 Claude Code 沒有剩餘的已儲存登入可用來更新連線
處理方式：
  • 執行 /login 重新登入
  • 執行 /remote-control 重新連線工作階段。以 run /login to restore Remote Control 結尾的訊息不需要此步驟：您登入後 Claude Code 會自動重新連線。
在 v2.1.224 之前，OAuth token refresh failed — run /login to re-authenticate 顯示為 OAuth token refresh failed — re-authenticate, then re-enable Remote Control，而 JWT refresh failed: no OAuth token — run /login 顯示為 no OAuth token available for recovery (code <N>)。Claude.ai login expired、Claude.ai login was rejected 與 OAuth token unavailable 訊息是在 v2.1.225 新增的。 在 v2.1.238 之前，Claude Code 會將現在顯示為 Signed out of Claude 的情況回報為 JWT refresh failed: no OAuth token — run /login，並且只要有一次登入重新整理沒有得到回應，就會以 Claude.ai login expired — run /login to restore Remote Control 停止 Remote Control。

​
Remote Control could not renew this computer’s connection

當伺服器無法在連線的憑證到期前使用您的 claude.ai 登入為其續期時，此警告會出現在執行 claude remote-control 的終端機中。警告的最後一句會說明目前的憑證還能使用多久，或說明它已經過期：
處理方式：
  • 如果警告要求您執行 claude /login，請在執行伺服器的機器上開啟另一個終端機，在其中執行 claude /login，並以您的 claude.ai 帳戶登入
  • 如果在連線的憑證過期後伺服器仍無法登入，它會輸出包含 Poll: Authentication failed (401) 的錯誤並停止。請依警告第二句的說明重新登入，然後在伺服器停止的終端機中再次執行 claude remote-control。

​
由於登入的帳戶已變更，Remote Control 已停止

在 Remote Control 工作階段期間，當您在這台機器上登入不同的 claude.ai 帳戶或組織時，Claude Code 會顯示此行。您是在 Claude Code 工作階段之外進行切換的，例如在另一個終端機中執行 /login。 您透過 /login 登入時啟動的 Remote Control 工作階段，屬於當時已登入的 claude.ai 帳戶與組織。
一旦 claude.ai 確認帳戶或組織已變更，Claude Code 就會停止 Remote Control 工作階段。您的本機工作階段會在沒有 Remote Control 的情況下繼續執行。 處理方式：
  • 執行 /remote-control，在目前的帳戶或組織下啟動新的 Remote Control 工作階段
  • 若要切換回去，請執行 /login 並重新登入先前的帳戶或組織，然後執行 /remote-control。
在 v2.1.234 之前，當您在 Claude Code 工作階段之外切換到不同的帳戶或組織時，Claude Code 不會察覺。Claude Code 會讓 Remote Control 工作階段保持連線，直到之後對 Remote Control 伺服器的請求以 Remote Control server rejected the request (HTTP 404) 失敗為止。該失敗可能在切換後數小時才出現。

​
由於執行工作階段的應用程式已登出或切換帳戶，Remote Control 已停止

當 Claude 桌面應用程式或 IDE 託管您的工作階段時，Claude Code 會從該應用程式取得登入 token，而不是從 /login。當 claude.ai 拒絕該 token 時，Claude Code 會向應用程式要求新的 token。如果應用程式回應它已登出，或現在已登入不同的 Claude 帳戶，Claude Code 會結束 Remote Control 工作階段，並向應用程式傳送下列其中一行：
您的本機工作階段會在沒有 Remote Control 的情況下繼續執行。 處理方式：
  • 如果應用程式已登出，請重新登入，然後在應用程式中重新開啟 Remote Control
  • 如果應用程式切換了帳戶，Claude Code 無法在新帳戶下繼續已結束的工作階段。請在該帳戶下啟動新的 Remote Control 工作階段。
在 v2.1.238 之前，這兩種情況下 Claude Code 都會向應用程式傳送列於 Remote Control 無法重新整理您的登入中的 run /login 訊息。

​
OAuth token 已撤銷或已過期

您已儲存的登入不再有效。token 被撤銷表示您已在所有地方登出，或管理員移除了存取權；token 過期則表示自動重新整理在工作階段中途失敗。 這兩種訊息都是回報 API 針對 Claude Code 所傳送請求的拒絕。當已儲存的登入在重新整理失敗後已被清除時，您會改為看到登入已過期。如果您以 CLAUDE_CODE_OAUTH_TOKEN 中的長期 token 進行身分驗證，當該 token 過期或被撤銷時，您會看到相同的訊息。
在非互動模式（-p）與 Agent SDK 中，訊息如下，結構化錯誤代碼為 authentication_failed：
在 v2.1.287 之前，在非互動模式與 Agent SDK 中，撤銷訊息顯示為 Your account does not have access to Claude. Please login again or contact your administrator. 處理方式：
  • 在 Claude Code 提示字元執行 /login 重新登入
  • 如果您的 -p 命令或 Agent SDK 程式使用已儲存的登入，請在相同環境中執行 claude，完成 /login，然後重新執行命令或程式。對於無法互動式登入的自動化作業，請以 ANTHROPIC_API_KEY 進行身分驗證，或使用 claude setup-token 產生長期 token。
  • 如果您以 CLAUDE_CODE_OAUTH_TOKEN 環境變數進行身分驗證，在請求以 401 失敗後，Claude Code 會持續傳送您設定的值，而不會切換為已儲存登入的 token。/status 會將此憑證顯示為一列內容為 CLAUDE_CODE_OAUTH_TOKEN 的 Auth token。請使用 claude setup-token 產生新的 token 並以其重新啟動，或取消設定該變數並執行 /login。在 v2.1.225 之前，Claude Code 可能會在工作階段中途以已儲存登入的短期存取 token 取代該變數的值，而當該 token 過期後，工作階段會再次以 401 錯誤失敗。
  • 若每次啟動都反覆要求登入，請參閱疑難排解中的系統時鐘檢查與 macOS 憑證儲存復原步驟
  • 其他失敗（包括 403 Forbidden 與 OAuth 瀏覽器問題），請參閱登入與身分驗證

​
API Error: 401 Invalid authentication credentials

API 辨識了您憑證的格式，但拒絕了其背後的帳戶或組織。當憑證最近被撤銷、組織已被停用或移除了您的存取權，或帳戶本身已被停用時，Anthropic 會傳回此訊息，因此原因並非 token 過期。該憑證可能是您已儲存的登入，也可能是已核准的 ANTHROPIC_API_KEY，而修正方式有所不同，因此請先執行 /status 查看使用中的是哪一個。
處理方式：
  • 如果 /status 顯示一列未標記為未使用的 API key，則已核准的 ANTHROPIC_API_KEY 是使用中的憑證且優先於您的登入，因此 /login 不會取代它。請在 Claude Console 中輪替金鑰，或執行 unset ANTHROPIC_API_KEY（在 PowerShell 中為 Remove-Item Env:ANTHROPIC_API_KEY）退回使用您的訂閱。
  • 如果 /status 只顯示您的登入，請執行一次 /login。如果憑證已被撤銷，新的登入會取代它。
  • 如果相同的登入帳戶再次出現相同訊息，表示該帳戶或組織已不再有效。請檢查 /status 所回報的帳戶與組織，並請您的組織管理員恢復存取權。
  • 如果 ANTHROPIC_BASE_URL 指向 LLM 閘道，401 之後的文字是您閘道的訊息而非 Anthropic 的訊息，/login 無法改變它。請改為修正您閘道所預期的憑證。

​
登入已過期

Claude Code 嘗試更新您已儲存的 claude.ai 登入，但 OAuth 服務拒絕了已儲存的重新整理 token，因此 Claude Code 清除了已儲存的憑證。之後，每個模型請求都會在抵達 API 之前於本機以此訊息停止，因為只有 /login 能建立新的憑證。 在 v2.1.206 之前，Claude Code 仍會使用環境中剩餘的任何憑證傳送模型請求，結果每個模型都以所選模型有問題或 401 失敗，而不是提示您登入。
在非互動模式（-p）與 Agent SDK 中，訊息如下，結構化錯誤代碼為 authentication_failed：
若 Login expired 訊息以 or re-authenticate your Anthropic profile 結尾，請參閱 Anthropic profile login expired。 這與 OAuth token 已撤銷或已過期並非相同狀態。那些訊息回報的是 API 傳回的拒絕。Login expired 是 Claude Code 本身針對已無法更新的登入所產生的訊息，因此不會傳送任何請求。當更新失敗是因為帳戶本身遭到停權而非登入過時，Claude Code 會改為顯示您的帳戶已遭暫停。 以 API 金鑰、CLAUDE_CODE_OAUTH_TOKEN 或第三方供應商進行身分驗證的工作階段不使用已儲存的登入，永遠不會看到此訊息。 您可以在請求失敗之前檢查此狀態：/status 會顯示一列內容為 Expired — log in again 的 Login，以及它為過期登入所儲存的組織與電子郵件。只有當已儲存的登入是您使用中的憑證且已無法重新整理時，才會出現該列。以其他方式進行身分驗證的工作階段不會顯示該列，即使仍有已過期的登入被儲存。在 v2.1.210 之前，/status 在此狀態下不會顯示任何曾經存在登入的跡象，因為被清除的憑證讓它沒有可回報的內容。 處理方式：
  • 執行 /login 重新登入。未登入就重試，每次請求都會顯示相同的訊息。
  • 如果您在另一個 Claude Code 視窗中以 claude.ai 帳戶登入，請參閱未登入，了解此工作階段何時會自動開始使用該登入。
  • 在非互動模式中，請在相同環境中執行 claude，完成 /login，然後重新執行您的命令。對於無法互動式登入的自動化作業，請以 ANTHROPIC_API_KEY 進行身分驗證，或使用 claude setup-token 產生長期 token。
  • 如果登入持續失敗，請參閱登入與身分驗證

​
由於另一個 Claude Code 程序正在重新整理，無法重新整理您的登入

此訊息並不表示您的登入被拒絕。您已儲存的 claude.ai 登入已過期且需要更新。同一台機器上的另一個 Claude Code 程序持有共用的重新整理鎖，或是已結束並遺留該鎖，而在此工作階段等待期間重新整理沒有任何進展。Claude Code 會在傳送前停止請求：
在非互動模式（-p）與 Agent SDK 中，訊息如下，結構化錯誤代碼為 server_error：
以 API 金鑰、CLAUDE_CODE_OAUTH_TOKEN 或第三方供應商進行身分驗證的工作階段不使用已儲存的登入，永遠不會看到此訊息。 處理方式：
  • 一分鐘後再試一次。如果另一個程序先完成了重新整理，此工作階段就會使用更新後的登入。
  • 如果訊息持續出現，請關閉其他 Claude Code 視窗與程序，然後重試。
  • 如果在沒有其他 Claude Code 程序執行的情況下仍出現此訊息，請執行 /login。重新登入不需要等待重新整理鎖。

​
無法儲存您的登入

您已使用 claude.ai 登入，但 Claude Code 無法將登入儲存至其憑證儲存區，因此登入未完成。在 macOS 上，如果 Claude Code 在同一個工作階段中已經讀取或儲存過登入鑰匙圈中的憑證，之後鑰匙圈被鎖定（例如在睡眠或閒置時），就可能發生這種情況。
第一種形式出現在 macOS 上，第二種則出現在其他所有平台上。暫時性的憑證儲存區失敗（例如逾時或儲存區無法讀取）也會產生相同的訊息。 處理方式：
  • 在 macOS 上，解鎖登入鑰匙圈，然後再次執行 /login
  • 在其他平台上，再次執行 /login
  • 如果登入仍無法儲存，請參閱未登入或 token 已過期，了解鑰匙圈解鎖命令及其他憑證儲存復原步驟

​
無法啟動 OAuth 回呼伺服器

當 /login、claude auth login 或 claude setup-token 透過瀏覽器為您登入時，Claude Code 會在 127.0.0.1 上開啟一個監聽埠，讓您的瀏覽器能將登入結果傳回給它。此訊息表示 Claude Code 無法開啟該埠，登入會在瀏覽器視窗或登入 URL 出現之前停止：
如果您的訊息以 Is port 0 in use? 結尾，表示在 IPv4 回送位址 127.0.0.1 上監聽的嘗試直接失敗了。由於失敗發生在登入 URL 產生之前，Paste code here if prompted 流程無法作為替代方案。 處理方式：
  • 若要在不使用本機監聽器的情況下立即登入：如果您使用 claude.ai 訂閱，請在可以正常登入的機器上執行 claude setup-token，並在這台機器上將其輸出的 token 設定為 CLAUDE_CODE_OAUTH_TOKEN。否則，請將 ANTHROPIC_API_KEY 設定為來自 Claude Console 的金鑰。身分驗證優先順序說明了 Claude Code 如何在多個憑證之間做選擇。
  • 若要改為在這台機器上使用瀏覽器登入，Claude Code 必須能夠在 127.0.0.1 上監聽。如果它在沙箱中執行，請確認沙箱的政策允許在本機埠上監聽，然後再次執行 /login。如果它理應可以監聽卻仍然失敗，請執行 /feedback，讓回報中包含您的環境詳細資訊。

​
不接受 Claude 登入

您嘗試啟動雲端工作階段，但伺服器以 401 拒絕建立它：伺服器不接受這台機器所傳送的 Claude 登入，通常是因為登入已過期或被撤銷。 如果伺服器有提供原因，該行的第一部分會是伺服器本身的原因。否則該行顯示為：
處理方式：
  • 執行 /login，完成登入後再次啟動工作階段

​
Artifact 需要 claude.ai 登入

Claude Code 拒絕了 artifact 的發布或讀取，因為此工作階段沒有可用於 artifact 的 claude.ai 登入。 每種形式的訊息都以相同的文字開頭，後面接著依您工作階段的身分驗證方式而定的補救方法。在沒有競爭憑證的情況下，訊息顯示為：
處理方式：
  • 執行 /login 並選擇 Claude account with subscription。Anthropic Console account 選項不提供 claude.ai 憑證。
  • 當訊息指名某個具有優先權的憑證（例如 ANTHROPIC_API_KEY、apiKeyHelper 設定，或先前 /login 所儲存的 Console 金鑰）時，請依訊息所述的方式移除它，然後執行 /login
  • 當訊息表示此遠端工作階段是透過啟動它的機器進行身分驗證時，請在該機器上登入 claude.ai，然後重新連線工作階段
  • 當訊息表示憑證是由工作階段的主機環境注入時，您無法在該工作階段中變更它；請啟動一個已登入 claude.ai 的工作階段
  • 請參閱可用性，了解 artifact 的其他需求，例如方案、模型供應商與組織政策

​
管理員政策要求使用 Cloud 閘道登入

管理員在這台機器上的受管設定將 forceLoginMethod 設定為 "gateway"，或設定了 forceLoginGatewayUrl。除非您透過 CLAUDE_CODE_USE_BEDROCK 等變數選擇雲端供應商，否則 Claude Code 只會接受 Claude apps 閘道登入。您會看到下列兩種訊息之一：
當工作階段沒有閘道登入時，模型請求會以此訊息失敗，例如因為在政策套用到這台機器之後您尚未執行 /login。 如果這台機器還持有 Anthropic 核發的憑證，且受管設定設定了 forceLoginMethod 或 forceLoginOrgUUID，Claude Code 會改為在啟動時結束。該憑證可能是 ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN 變數、apiKeyHelper 設定，或先前 Claude Console 登入所儲存的 API 金鑰。 啟動訊息會指出工作階段所設定的憑證、其設定位置，以及移除它的步驟。例如，若您在 shell 中設定了 ANTHROPIC_API_KEY 變數，訊息會顯示為：
處理方式：
  • 對於 Not signed in to the Cloud gateway，請執行 /login 並在 Cloud gateway 畫面上完成登入
  • 對於啟動訊息，請依照訊息結尾的步驟移除該憑證
  • 如果您認為這台機器不應要求使用閘道，請要求管理該機器的管理員從其受管設定中移除 forceLoginMethod 與 forceLoginGatewayUrl
在 v2.1.284 之前，啟動訊息會列出可能的憑證，而不是指出所設定的那一個。訊息開頭為 Administrator policy requires a Cloud gateway sign-in on this machine; the Anthropic-issued credential configured here (ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, or apiKeyHelper) is not used.。如果您看到這段文字且無法判斷要移除哪個憑證，請更新至 v2.1.284 或更新版本，然後再次啟動 claude。 在 v2.1.265 上，一個迴歸問題也會在某些以 API 金鑰、apiKeyHelper 或自訂標頭進行身分驗證的 LLM 閘道與代理伺服器設定中顯示第一則訊息，即使這台機器上沒有任何管理員要求亦然。請更新至 v2.1.266 或更新版本。您不需要變更設定。 在 v2.1.261 之前，在將 forceLoginMethod 設定為 "gateway" 的機器上，Claude Code 會使用遺留的已儲存登入，而不是讓模型請求失敗，並以 This machine's managed settings require a first-party login 回報已設定的環境憑證，而不是顯示啟動訊息。

​
您的帳戶已遭暫停

您登入所使用的 Claude 帳戶已被停權。當 Claude Code 嘗試更新您已儲存的登入並得知暫停狀態時，會顯示第一則訊息；當您在瀏覽器中完成的登入回報此狀態時，會顯示第二則訊息：
以相同帳戶重新登入不會清除此訊息，因為暫停是針對帳戶而非登入。在非互動模式（-p）與 Agent SDK 中，結構化錯誤代碼為 account_on_hold。在 v2.1.235 之前，Claude Code 會將遭暫停的帳戶回報為 Login expired · Please run /login，而其復原步驟無法解除暫停。 處理方式：
  • 開啟訊息中的連結，查看暫停的詳細資訊或提出申訴
  • 如果您有另一個不受暫停影響的 Claude 帳戶或 API 金鑰，可以在暫停解決期間繼續工作：以該帳戶執行 /login，或以 ANTHROPIC_API_KEY 設定金鑰

​
Anthropic 設定檔登入已過期

Claude Code 正透過 Anthropic 憑證設定檔進行身分驗證，但該設定檔已儲存的登入憑證已過期，且設定檔中沒有 Claude Code 可用來更新它的重新整理憑證。Claude Code 會在本機停止每個請求，且不會重試。
處理方式：
  • 如果訊息以 Login expired 開頭，請執行 /login 重新登入
  • 若要更新由無金鑰 Console 登入或 Claude Platform CLI 的 ant auth login 所寫入的設定檔，請在提供無金鑰登入的機器上執行 /login。選擇 Anthropic Console 帳戶，然後選擇 Sign in with your Console account。Claude Code 會取代該設定檔中已過期的憑證
  • 若要更新由其他工具建立的設定檔，請使用該工具重新登入。如果您改在 /login 選擇 Sign in with your Console account，Claude Code 會保持該設定檔不變，並建立一個 API 金鑰
  • 如果設定檔的憑證是由管理員佈建的，請要求他們核發新的憑證
  • 執行 /status，確認使用中的憑證來源與設定檔名稱
  • 若要停止使用該設定檔，請在您有設定的情況下取消設定 ANTHROPIC_PROFILE，然後以其他方式進行身分驗證，例如 /login 或 ANTHROPIC_API_KEY
訊息的開頭會告訴您 Claude Code 是如何找到該設定檔的：
  • 當 Claude Code 從您的設定目錄中探索到該設定檔，且其驗證模式為 user_oauth 時，訊息會以 Login expired 開頭，並優先建議 /login。Claude Code 會讓可正常運作的 /login 優先於探索到的設定檔，然後改以您的 claude.ai 帳戶進行身分驗證。從 v2.1.234 到 v2.1.277 之前，此形式顯示為 Anthropic profile login expired · Run /login to use your claude.ai account instead, or re-authenticate the profile。在 v2.1.234 之前，Claude Code 在此情況下也會顯示 Re-authenticate your Anthropic profile 形式。
  • 當您使用 ANTHROPIC_PROFILE 選擇該設定檔時，訊息會以 Anthropic profile login expired 開頭。
只有當使用中的憑證來自 Anthropic 憑證設定檔時才會出現此訊息，該設定檔可能是您以 ANTHROPIC_PROFILE 環境變數選擇的、Claude Code 在您的 Anthropic 設定目錄中探索到的使用中設定檔，或是您在不使用 API 金鑰的情況下登入時 Claude Code 寫入的設定檔。以 API 金鑰、ANTHROPIC_AUTH_TOKEN 等 bearer token 或第三方供應商進行身分驗證的工作階段，永遠不會看到此訊息。

​
OAuth 範圍需求

已儲存的 token 早於某個較新功能所需的權限範圍：
處理方式：
  • 執行 /login 以取得具有目前範圍的新 token。您不需要先登出。

​
claude.ai 拒絕了工作階段 token

claude.ai 連接器請求失敗，因為 claude.ai 拒絕了來自您 Claude Code 登入的 token。被拒絕的 token 是您的登入，而不是連接器本身在 claude.ai 中的授權，因此重新授權連接器無法解決此問題。在 /mcp 中，該連接器會顯示為 session token rejected，其詳細資訊檢視顯示：
處理方式：
  • 執行 /login 重新登入
  • 從 /mcp 重新連線連接器，或執行 /mcp reconnect <server>。在重新登入之前重新連線，連接器會維持相同狀態。/mcp 面板的 Reconnect 選項會回報 your claude.ai session token was rejected；而輸入的 /mcp reconnect <server> 形式即使 token 仍被拒絕，也會回報重新連線成功。
在 v2.1.222 之前，Claude Code 會改將連接器標記為需要身分驗證，引導您前往連接器的授權流程，即使完成該流程也無法解決此狀態。

​
MCP 伺服器需要您重新登入

遠端 MCP 伺服器在工作階段中途的工具呼叫時拒絕了憑證，通常是因為登入或 token 已過期，或是 token 缺少工具所需的權限。工具呼叫會失敗，且 /mcp 會將該伺服器標記為需要身分驗證。 對於您從 Claude Code 登入的伺服器（包括 claude.ai 連接器），表示登入已過期或被撤銷：
執行 /mcp，選擇該伺服器，並從其選單重新登入。 對於以 headersHelper 指令碼設定的伺服器，Claude Code 在顯示此訊息之前已經重新執行過 helper 並重試過一次呼叫：
請確認 helper 傳回的憑證是伺服器所接受的，然後從 /mcp 重新連線，這會再次執行 helper。 對於設定中帶有靜態 Authorization 標頭的伺服器：
在設定該伺服器的位置更新標頭值，然後從 /mcp 重新連線。 在 v2.1.273 之前，登入過期、headersHelper 與 Authorization 標頭這幾種情況都會顯示 MCP server "<name>" requires re-authorization (token expired)。 伺服器也可能以 HTTP 403 insufficient_scope 拒絕工具呼叫，要求您授權某個範圍，有時是您的 token 已列出的範圍。訊息會指出該範圍：
執行 /mcp，選擇該伺服器，並從其選單重新進行身分驗證。 當伺服器的設定既未設定 oauth.scopes 也未設定 authServerMetadataUrl 時，Claude Code 會請求伺服器所指出的範圍。若有設定其中任一項，Claude Code 會改為請求該設定的範圍。如果您固定了 oauth.scopes，請在重新進行身分驗證之前，將缺少的範圍加入該清單。 在 v2.1.274 之前，此情況會顯示 needs you to sign in again 訊息，而在 v2.1.273 之前，它會像其他情況一樣顯示 requires re-authorization (token expired)。

​
MCP 伺服器 URL 遺失或不是有效的 URL

Claude Code 拒絕為遠端 MCP 伺服器啟動 OAuth 登入，因為該伺服器所設定的 url 無法解析為 URL。除非 Claude Code 有更具體的伺服器設定問題要回報，否則在您的 shell 中執行 claude mcp login <name> 會將此拒絕顯示為：
處理方式：
  • 在設定該伺服器的位置將該項目的 url 設定為伺服器的實際端點，或設定其 ${VAR} 參照所指名的環境變數，然後再次執行登入。

​
授權回應中的 issuer 不符

在 MCP OAuth 登入期間，授權伺服器重新導向回 Claude Code 時所帶的 iss 參數，並非 Claude Code 根據伺服器 OAuth 中繼資料所預期的 issuer。此步驟出現錯誤的 issuer 正是授權伺服器混淆攻擊的樣貌，因此 Claude Code 會讓登入失敗，而不是交換授權碼。Claude Code 會在瀏覽器登入後於 /mcp 伺服器選單中顯示此錯誤：
expected 是伺服器 OAuth 中繼資料中的 issuer，received 是重新導向所帶的 iss 值。重新導向未帶 iss 參數的登入會通過檢查，除非伺服器的中繼資料設定了 authorization_response_iss_parameter_supported，此時 Claude Code 會讓登入失敗。 處理方式：
  • 從 /mcp 再次嘗試登入
  • 如果錯誤重複出現，請回報給伺服器營運者。修正需在伺服器端進行：授權伺服器必須在 iss 參數中傳回與其中繼資料所公告相同的 issuer
  • 若要在伺服器修正期間連線，請以 MCP_SDK_GENERATION=v1 啟動 Claude Code，其執行階段不會執行此檢查。這會移除對混淆攻擊的防護，因此建議優先採用伺服器端修正
在 v2.1.232 之前，Claude Code 只在逐步推出時或您設定 MCP_SDK_GENERATION=v2 時才使用 v2 執行階段。

​
拒絕將憑證傳送至非 https 的 token 端點

在 v2 執行階段上，Claude Code 只會將 MCP OAuth token 請求傳送至透過 HTTPS 提供，或位於 localhost、127.0.0.1 或 ::1 的 token 端點。此訊息表示伺服器的 token 端點兩者皆非，因此 Claude Code 在傳送請求之前停止了。這發生在瀏覽器登入之後，因此瀏覽器步驟會先成功，之後每當 Claude Code 重新整理該伺服器的 token 時也會再次發生。 完整形式的訊息來自 MCP SDK，並會引用它所拒絕的 token 端點。在偵錯日誌中，它會接在登入的 Error during auth completion: 或重新整理的 Token refresh failed: 之後。在您的 shell 中，claude mcp login <name> 會在 Couldn't complete authentication for "<name>": 之後輸出它；在工作階段中，/mcp 會在伺服器的選單下顯示它：
Claude Code 會將帶有查詢字串或冗長隨機路徑區段的伺服器 URL 視為可能是機密。對於此類伺服器，它會在顯示或記錄 MCP SDK 引發的登入錯誤之前將其遮蔽。此時這個錯誤會顯示為一個可能隨版本變動的簡短名稱（例如 io），後面接著 from the MCP SDK for 以及遮蔽後的伺服器 URL。其他來自 MCP SDK 的錯誤在該處也採用相同形式。只有當伺服器的 token 端點是位於 localhost、127.0.0.1 或 ::1 以外位址的純 http:// 時，遮蔽後的訊息才可能是此錯誤。 處理方式：
  • 透過 HTTPS 提供該 token 端點，例如將伺服器放在終止 TLS 的反向代理伺服器或通道後方，並設定伺服器公告 https:// 位址
  • 若要在不變更伺服器的情況下連線，請以 MCP_SDK_GENERATION=v1 啟動 Claude Code，其執行階段不套用此規則，並會透過純 HTTP 傳送 token 請求。此選擇會持續到您結束為止，並套用至每個伺服器。v1 執行階段也會略過 issuer 檢查，因此建議優先透過 HTTPS 提供端點

​
AWS 憑證已過期或無效

您的 AWS 工作階段 token 已過期或被拒絕。當 Claude Platform on AWS 或 Mantle 端點傳回 401 時會出現此訊息，這是這些供應商回報安全 token 過期的方式。 中間的動作提示會依您的設定而不同。固定不變的部分是開頭的 AWS credentials expired or invalid：
在 v2.1.273 之前，只有在設定了 awsAuthRefresh 時才會出現此訊息。 處理方式：
  • 如果提示表示憑證由此環境管理，則啟動 Claude Code 的應用程式擁有該憑證，此處的其他步驟並不適用：請重試，或聯絡您的管理員
  • 如果設定了 awsAuthRefresh，請在另一個終端機中執行訊息所指的命令（例如 aws sso login --profile myprofile）並完成瀏覽器登入，然後重試。否則，請自行重新整理您所使用的 AWS 憑證：您的 SSO 登入、存取金鑰、API 金鑰或代理伺服器 token
  • 在設定了 awsAuthRefresh 的互動式工作階段中，您也可以改為執行 /login，選擇 3rd-party platform，然後在 Using 3rd-party platforms 下選擇 Claude Platform on AWS · refresh credentials，即可在不重新啟動 Claude Code 的情況下執行相同的命令。請參閱設定 AWS 憑證
  • 如果重新整理命令成功後錯誤仍重複出現，請在相同的 shell 與設定檔中執行 aws sts get-caller-identity，確認該身分在 Claude Code 之外是有效的

​
AWS 身分驗證失敗

您的 AWS 供應商傳回了 403，或 Amazon Bedrock 傳回了 401。 Amazon Bedrock 會將安全 token 過期回報為 403，但 403 也是它回報授權遭拒的方式，例如因缺少 IAM 權限而產生的 AccessDeniedException。Claude Code 無法區分這兩種原因。 來自 Amazon Bedrock 的 401 也會歸到此處，而不是 AWS 憑證已過期或無效，因為 Amazon Bedrock 不會將 token 過期回報為 401。來自該端點的 401 通常源自請求路徑中的其他元件，例如公司的代理伺服器。 重新整理憑證可以修正過期的 token，但無法修正其他原因，因此訊息會同時提供兩者：
中間的動作提示會依您的設定而不同。固定不變的部分是開頭的 AWS authentication failed。 當 403 是 Amazon Bedrock 表示您無權存取指定模型 ID 之模型的回應時，提示會改為要求您在 Amazon Bedrock 主控台中為您的帳戶與區域啟用該模型。 在 v2.1.273 之前，只有在設定了 awsAuthRefresh 時才會出現此訊息。 處理方式：
  • 如果提示表示憑證由此環境管理，則啟動 Claude Code 的應用程式擁有該憑證，此處的其他步驟並不適用：請重試，或聯絡您的管理員
  • 重新整理您的 AWS 憑證，以防原因是憑證過期：若有設定，請執行訊息所指的 awsAuthRefresh 命令，或自行重新整理您的 SSO 登入、存取金鑰、API 金鑰或代理伺服器 token
  • 如果您的憑證是最新的，請確認 IAM 設定中的 IAM 權限已附加至您所使用的身分，且所選模型已為您的帳戶與區域啟用
  • 執行 aws sts get-caller-identity，確認您的請求使用的是哪個身分

​
Google Cloud 憑證已過期或無效

您用於 Google Cloud’s Agent Platform 的 Google Cloud 憑證已過期或被拒絕：請求傳回了 401，這是 Agent Platform 回報憑證過期的方式。 中間的動作提示會依您的設定而不同。固定不變的部分是開頭的 Google Cloud credentials expired or invalid：
處理方式：
  • 如果提示表示憑證由此環境管理，則啟動 Claude Code 的應用程式擁有該憑證，此處的其他步驟並不適用：請重試，或聯絡您的管理員
  • 如果您以應用程式預設憑證進行身分驗證，請執行訊息所指的 gcpAuthRefresh 命令，或 gcloud auth application-default login，完成登入後重試
  • 如果您在設定了 CLAUDE_CODE_SKIP_VERTEX_AUTH 的情況下透過 LLM 閘道進行路由，請重新整理 ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_CUSTOM_HEADERS 中的閘道 token，然後重試
  • 如果您以服務帳戶金鑰檔案進行身分驗證，請確認 GOOGLE_APPLICATION_CREDENTIALS 指向有效的金鑰。請參閱設定 GCP 憑證
  • 如果重新整理後錯誤仍重複出現，請在相同的 shell 中執行 gcloud auth application-default print-access-token，確認該身分在 Claude Code 之外可正常運作
在 v2.1.273 之前，來自 Agent Platform 的 401 會改為顯示一般的 Please run /login 或 Failed to authenticate 訊息，而這些訊息無法重新整理 Google Cloud 憑證。

​
Google Cloud 身分驗證失敗

Google Cloud 的 Agent Platform 傳回了 403，它使用此狀態碼表示授權遭拒，而非憑證過期。通常是您用來進行身分驗證的身分缺少 IAM 權限，或模型尚未在您的專案中啟用。 中間的操作提示會依您的設定而有所不同。固定不變的部分是開頭的 Google Cloud authentication failed：
處理方式：
  • 如果提示指出憑證由此環境管理，表示啟動 Claude Code 的應用程式擁有該憑證，此處的其他步驟不適用：請重試，或聯絡您的管理員
  • 確認 IAM 設定中的角色已授予您用來進行身分驗證的身分
  • 確認模型已在您的專案中啟用。請參閱請求模型存取權
在 v2.1.273 之前，來自 Agent Platform 的 403 會改為顯示通用的 Please run /login 或 Failed to authenticate 訊息，而這無法重新整理 Google Cloud 憑證。

​
Microsoft Foundry 身分驗證失敗

Microsoft Foundry 傳回了 401 或 403：請求上的 Azure 憑證遭到拒絕，或其背後的身分沒有 Foundry 資源的存取權。/login 無法產生 Azure 憑證。中間的操作提示會依您的設定而有所不同。固定不變的部分是開頭的 Microsoft Foundry authentication failed：
處理方式：
  • 如果提示指出憑證由此環境管理，表示啟動 Claude Code 的應用程式擁有該憑證，此處的其他步驟不適用：請重試，或聯絡您的管理員
  • 重新整理您在設定 Azure 憑證中設定的憑證：輪替 ANTHROPIC_FOUNDRY_API_KEY、產生新的 ANTHROPIC_FOUNDRY_AUTH_TOKEN，或執行 az login，讓預設的 Microsoft Entra 憑證鏈能再次登入
  • 如果憑證仍有效，請確認該身分具有 Foundry 資源的存取權。請參閱 Azure RBAC 設定
在 v2.1.273 之前，來自 Microsoft Foundry 的 401 或 403 會改為顯示通用的 Please run /login 或 Failed to authenticate 訊息，而這無法重新整理 Azure 憑證。

​
無法載入 AWS 或 Google Cloud 憑證

Claude Code 無法在其執行的機器上，從 AWS 憑證提供者鏈或您的 Google 應用程式預設憑證取得可用的憑證，因此沒有任何請求送達您的雲端供應商。· 之後的詳細資訊會指出具體原因，例如 SSO 工作階段已過期、缺少應用程式預設憑證（回報為 Could not load the default credentials），或登入已被撤銷（回報為 invalid_grant）：
在使用 -p 的非互動模式以及 Agent SDK 中，結構化錯誤代碼為 cloud_credential_error。在 v2.1.267 之前，訊息只會顯示 API Error: 之後的詳細文字，且結構化代碼為 server_error 或 unknown。 處理方式：

​
AWS 預設憑證鏈解析逾時

AWS 預設憑證提供者鏈未在 60 秒內產生憑證，因此 Claude Code 停止解析並使請求失敗。此逾時是無法載入 AWS 或 Google Cloud 憑證的原因之一。失敗發生在本機憑證解析階段：請求從未送達 Amazon Bedrock、Claude Platform on AWS 或 Mantle 端點。Claude Code 會在此錯誤出現之前清除其憑證快取並重試，因此當您看到此錯誤時，憑證鏈已在多次嘗試中停滯。
常見原因包括：AWS 設定檔中的 credential_process 命令正在等待它無法接收的輸入，以及容器或虛擬機器的執行個體中繼資料服務（IMDS）始終未回應憑證鏈的探測。 在 v2.1.267 之前，訊息為 API Error: AWS default-chain credential resolve timed out。 在 v2.1.207 之前，停滯的憑證鏈會讓請求無限期等待，而不會失敗。 處理方式：
  • 在同一個 shell 中使用相同的 AWS_PROFILE 執行 aws sts get-caller-identity。如果它也停滯，請修正設定檔；以互動方式提示輸入的 credential_process 命令是常見原因。
  • 在啟動 Claude Code 之前完成登入步驟，例如 aws sso login --profile myprofile
  • 如果您的憑證鏈執行的互動式登入確實需要超過 60 秒，例如透過 aws-vault 等包裝工具進行的 SSO 加 MFA，請使用 CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS 以毫秒為單位提高上限

​
Bedrock 設定驗證在等待 AWS 時逾時

在 Bedrock 設定精靈的憑證驗證期間，對 AWS 的某個呼叫（例如憑證查詢或身分檢查）未在 60 秒上限內完成。精靈會停止等待，並使驗證步驟失敗：
數字反映的是您的上限：預設為 60 秒，或是您在 CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS 中設定的值。 常見原因包括：網路或代理伺服器使對 AWS 的請求（包括 SSO token 重新整理）停滯，以及憑證輔助程式仍在等待您看不到的輸入。只有在輔助程式確實需要更多時間時才提高上限。 單一對 AWS 的停滯請求也可能因其自身的單次請求逾時而失敗，這會在同一步驟顯示較短的訊息：
當相同的逾時發生在模型固定步驟時，精靈會將模型標記為 unreachable，而不會顯示上述任一訊息。 處理方式：
  • 在同一個 shell 中執行 aws sts get-caller-identity。如果它也停滯，表示停滯發生在 Claude Code 之外，位於您的網路、代理伺服器或 AWS 設定檔中的憑證輔助程式；請先修正該問題。
  • 在開啟精靈之前完成任何互動式登入，例如 aws sso login --profile myprofile
  • 如果 AWS 設定檔中的憑證輔助程式確實需要超過 60 秒來提示您，請使用 CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS 以毫秒為單位提高上限

​
雲端閘道工作階段已過期

您是透過 Claude apps 閘道登入的，而儲存在此機器上的閘道工作階段已過期且無法續期，或閘道已不再接受它，例如在閘道的 JWT 密鑰被替換之後。如果您在以互動方式啟動 claude 時看到這一行，表示工作階段已在未登入閘道的狀態下開啟：
當閘道憑證過期且 Claude Code 無法續期時，同一行也可能在工作階段進行中出現。 在非互動執行、背景或其他無人值守的工作階段，或 claude auth 以外的 claude 子命令中，當閘道不再接受該工作階段時，Claude Code 會改為以此訊息結束：
處理方式：
  • 在工作階段中執行 /login 並完成瀏覽器登入
  • 若為非互動式啟動，請在相同環境中啟動 claude，執行 /login，然後重新執行您的命令

​
等待您繼續時登入逾時

在 Claude apps 閘道登入期間，閘道指出了登入的帳戶，而 Claude Code 要求您在儲存憑證之前確認該帳戶。您讓確認畫面停留超過了登入本身的有效期限，且閘道未核發可用來續期的 refresh token，因此當您繼續時，Claude Code 沒有儲存任何內容：
處理方式：
  • 再次執行 /login，並在登入過期之前確認帳戶

​
閘道拒絕了請求

您是透過 Claude apps 閘道登入的，而某個請求傳回了 403：閘道或其背後的上游拒絕了該請求。重新登入無法改變拒絕結果，因此訊息會指向您的閘道管理員：
處理方式：
  • 請您的閘道管理員查詢該請求。API Error: 後面的內容包含閘道傳回的拒絕資訊
  • 對管理員而言：閘道上的存取控制規則會傳回 403，並由稽核日誌記錄其原因；上游的授權拒絕則會依照上游錯誤訊息的方式傳遞
在 v2.1.273 之前，閘道工作階段上的 403 會改為顯示通用的 Please run /login 或 Failed to authenticate 訊息，且重新登入也無法解除該拒絕。

​
網路和連線錯誤

大多數這些錯誤表示來自 Claude Code 的網路請求無法到達其目的地，或 Claude Code 和 API 之間的某些東西在回程中改變了回應；如果條目也有本機原因（例如失敗的封存寫入），其內容會說明。它們通常源自您的本機網路、代理伺服器或防火牆，或雲端環境的網路原則。

​
Unable to connect to API

到 API 的 TCP 連線失敗或從未完成。對於常見的連線錯誤代碼，訊息會命名失敗的類型並在括號中保留代碼：
Claude Code 無法識別的代碼會顯示為 Unable to connect to API 後跟括號中的代碼。某些這些訊息可以顯示多個代碼：例如 Connection refused 可以顯示 ConnectionRefused 或 ECONNREFUSED，而 Can't reach the API server 可以顯示 ENOTFOUND 或 FailedToOpenSocket。 在 v2.1.227 之前，這些編碼訊息中的每一個都讀作 Unable to connect to API 後跟代碼，例如 Unable to connect to API (ECONNREFUSED)。 常見原因包括沒有網際網路存取、阻止 api.anthropic.com 的 VPN，或未設定的必需公司代理伺服器。 該怎麼做：
  • 透過從同一個 shell 執行 curl -I https://api.anthropic.com 來確認您可以到達 API 主機。在 Windows PowerShell 上使用 curl.exe -I https://api.anthropic.com，以便不使用內建的 Invoke-WebRequest 別名。
  • 如果您在公司代理伺服器後面，在啟動 Claude Code 之前設定 HTTPS_PROXY 並查看網路設定
  • 如果您透過 LLM 閘道或中繼路由，將 ANTHROPIC_BASE_URL 設定為其位址。請參閱將 Claude Code 連線到 LLM 閘道以進行設定。
  • 確保您的防火牆允許網路存取要求中列出的主機
  • 間歇性故障會自動重試；持續故障指向本機網路問題
如果 curl 成功但 Claude Code 仍然失敗，原因通常是執行時和網路之間的某些東西，而不是網路本身：
  • 透過執行 echo $ANTHROPIC_BASE_URL 檢查 ANTHROPIC_BASE_URL 是否已設定，或在 PowerShell 中執行 echo $env:ANTHROPIC_BASE_URL，並在您的設定檔的 env 區塊中查找它。當它被設定時，Claude Code 會將模型請求傳送到該位址而不是 api.anthropic.com，因此指向不再執行的本機代理伺服器或閘道的過時值會產生 Connection refused，即使 curl 到達 API。從您的 shell 設定檔或設定中移除它，並從新終端機啟動 Claude Code。
  • 在 Linux 和 WSL 上，檢查 /etc/resolv.conf 是否有無法到達的名稱伺服器。特別是 WSL 可以從主機繼承損壞的解析器。
  • 在 macOS 上，已斷開連線或卸載的 VPN 用戶端可能會留下隧道介面或路由規則。檢查 ifconfig 是否有過時的 utun 介面，並在系統設定中移除 VPN 的網路擴充功能。
  • Docker Desktop 和類似的容器執行時可以攔截出站流量。退出它們並重試以排除這種可能性。

​
Unable to connect to Anthropic services

在首次執行設定期間，Claude Code 會檢查它是否可以到達 api.anthropic.com 和 platform.claude.com，然後才顯示登入步驟。當任一檢查失敗時，Claude Code 會列印原因並退出。
Claude Code 透過與 API 請求相同的代理伺服器設定發送檢查，並給每個探測 10 秒。當失敗的探測通過代理伺服器時，訊息會命名設定它的環境變數，例如 HTTPS_PROXY。在 v2.1.222 之前，檢查使用不同的代理伺服器傳輸，沒有逾時：在具有 https:// 方案的代理伺服器 URL 後面，它可能會在 Checking connectivity... 上無限期停滯，然後即使透過同一代理伺服器的 API 請求成功也會失敗。 當受管設定檔、MDM 原則或原則協助程式將 forceLoginMethod 設定為 "gateway"，或設定 forceLoginGatewayUrl 而不設定 forceLoginMethod 時，Claude Code 會跳過此檢查。使用任一設定，Claude Code 會在 Cloud gateway 畫面上開啟登入步驟，而不是 Anthropic 登入方法。當機器上存在受管設定來源但無法讀取時，Claude Code 也會跳過檢查，因為該來源可能保有閘道設定。在 v2.1.247 之前，Claude Code 在此設定下也執行檢查，當 Anthropic 的端點無法到達時以此錯誤退出。 在沒有受管設定的機器上，當您自己的 ~/.claude/settings.json 以 forceLoginMethod 和 forceLoginGatewayUrl 指定閘道時，Claude Code 也會跳過此檢查。在 v2.1.295 之前，Claude Code 在這種情況下會執行檢查。 該怎麼做：
  • 如果訊息命名代理伺服器變數，檢查其值是否指向正確的代理伺服器，並要求您的網路團隊允許透過它到訊息中主機的 HTTPS 連線。請參閱網路設定。
  • 完成 Unable to connect to API 中的檢查。那裡的 curl 測試和防火牆指導也適用於此檢查。
  • 如果您的網路是開放的，故障仍然存在，Claude Code 可能在您的國家無法使用

​
Socket is closed

Socket is closed 表示承載串流回應的連線在回應仍在到達時被關閉。最常見的原因是 Windows 上的公司代理伺服器在回應中途丟棄已建立的隧道。 根據回應進行的距離，Claude Code 會重試請求、保留 Claude 產生的內容，或結束回合。請參閱自動重試。 在 v2.1.214 之前，Claude Code 不會重試此故障，回合會停止並出現包含 Socket is closed 的錯誤。 該怎麼做：
  • 如果您看到此錯誤，請使用 claude update 更新到 v2.1.214 或更新版本，然後再次傳送您的訊息
  • 如果在更新後回合在同一代理伺服器後面持續失敗，請完成 Unable to connect to API 並檢查網路設定中的代理伺服器設定

​
API returned an empty or malformed response

當 Claude Code 對失敗的串流請求進行非串流重試時，如果獲得 HTTP 成功狀態但主體不是 Claude API 訊息，Claude Code 會顯示此錯誤：通常是 HTML 錯誤或登入頁面、空主體或其他格式的 JSON。代理伺服器、閘道或網路登入頁面代替 API 回答是常見來源。Claude Code 不會重試請求，回合以此錯誤結束。
在該開頭之後，訊息會報告返回的內容以及哪個請求失敗：
  • 一個 Response: 子句，包含內容類型、主體類型（例如 body is an HTML page 或 empty body）、其大小（以位元組為單位），以及回應是否攜帶 Anthropic 請求 id。當回應命名可識別的伺服器（例如 nginx 或 cloudflare）或攜帶中介標頭（例如 cf-ray 或 via）時，子句也會列出這些。
  • 一個句子，命名失敗的串流請求的 id 和觸發重試的故障。當串流在故障前開啟時，它也會報告有多少串流事件到達，以及如果有的話，當嘗試失敗時串流已沉默多長時間。
在 v2.1.234 之前，訊息在 intercepting the request 後結束。 在 v2.1.271 之前，在非 JSON 內容類型（例如 text/plain）下攜帶有效 API 訊息的回覆也會以此錯誤結束回合。某些 LLM 閘道對非串流回覆使用該內容類型。 該怎麼做：
  • 閱讀 Response: 子句以查看哪個系統回答。HTML 主體、沒有 Anthropic 請求 id 或命名的伺服器（例如 nginx 或 cloudflare）表示 Claude Code 和 API 之間的某些東西代替它回答
  • 如果您透過 LLM 閘道路由，使用直接請求測試路由，並修復返回非 API 回應的跳躍
  • 在具有登入頁面的網路上（例如訪客 Wi-Fi），在瀏覽器中完成登入，然後重試
  • 如果只有透過您的閘道的非串流路由損壞，設定 CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 以關閉此備援，除非串流端點本身傳回 404，此時 Claude Code 仍然會改用非串流

​
Streaming response ended before any complete data was received

來自您的模型提供者的串流回應完成，但未傳遞任何可用資料，因此 Claude Code 重新傳送請求而不進行串流以完成回合。Claude Code 每個工作階段顯示一次警告，僅在互動式工作階段中。在 v2.1.239 之前，Claude Code 無聲地重試而不進行串流。
Claude Code 傳送每個受影響的請求兩次：空串流嘗試和重試。常見原因是在回程中消耗或轉換串流回應主體的代理伺服器或閘道。 該怎麼做：

​
Bedrock 串流回應具有意外的 content-type

Claude Code 和 Amazon Bedrock 之間的閘道或代理伺服器正在轉換串流回應主體或其 Content-Type 標頭。Amazon Bedrock 將回應串流為 application/vnd.amazon.eventstream。Claude Code 不會解碼無法讀取的主體，而是拒絕報告不同 content-type 的成功串流回應。Claude Code 不會重試請求。
在 v2.1.208 之前，相同的設定錯誤在整個回應被緩衝後顯示為 API Error: Truncated event message received。 該怎麼做：

​
SSL 憑證錯誤

您網路上的代理伺服器或安全設備正在使用自己的憑證攔截 TLS 流量，Claude Code 不信任它。
在 v2.1.273 之前，兩個訊息都在 Check your proxy or corporate SSL certificates 結束，沒有 OpenSSL 代碼或 NODE_EXTRA_CA_CERTS 提示。 從 v2.1.199 開始，憑證驗證失敗不會重試，因此此錯誤會在第一次嘗試時出現，而不是在完整重試預算後出現。較早的版本在顯示它之前花費幾分鐘重試。暫時性 TLS 條件（例如握手逾時）仍然會重試。 在 /login 和啟動連線檢查期間，相同的故障會產生不同的訊息：
在 Amazon Bedrock 上，Claude Code 本身發送給 AWS 的請求（例如 STS 和 SSO 角色憑證呼叫、模型發現和設定精靈的檢查）取決於相同的憑證設定。請參閱TLS 檢查代理伺服器後面的憑證錯誤。 該怎麼做：
  • 匯出您組織的 CA 套件，並使用 NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem 將 Claude Code 指向它
  • 請參閱網路設定以了解完整設定說明
  • 不要設定 NODE_TLS_REJECT_UNAUTHORIZED=0，這會完全停用憑證驗證

​
雲端工作階段中不允許主機

來自雲端工作階段或 routine 的出站 HTTP 請求被環境的網路原則阻止。
您也可能看到與目的地的真實憑證不符的 TLS 憑證。雲端工作階段透過代理伺服器路由出站流量，該代理伺服器強制執行網路原則，因此不符的憑證表示代理伺服器終止了連線，而不是目的地。 這不是用戶端網路問題。雲端工作階段和 routine 在沙箱 VM 內執行，其透過工作階段網路的出站流量被過濾到雲端環境的允許清單；GitHub 操作和 MCP 連接器流量使用單獨的通道，這就是為什麼它們可以在其他主機被阻止時繼續工作。預設環境使用信任存取，允許預設允許清單的套件登錄、雲端提供者 API、容器登錄和常見開發網域，並阻止該路徑上的其他網域。 該怎麼做： 這些步驟會變更您自己的環境之一。組織共享環境在選擇器中以唯讀方式開啟，因此請要求擁有者從管理設定中的雲端環境頁面變更其網路存取。
  • 開啟您的環境進行編輯，可從 routine 的表單，或從您啟動雲端工作階段的環境選擇器開啟。
  • 在編輯雲端環境對話方塊中，將網路存取從信任變更為自訂，然後將被阻止的網域新增到允許的網域。每行輸入一個網域。勾選也包括常見套件管理員的預設清單以在您的自訂網域旁邊保留預設允許清單。如果您想要不受限制的存取，請改為選擇完整。
  • 按一下儲存變更。下一次執行使用更新的允許清單。對於已開啟的雲端工作階段，請參閱網路存取變更何時到達現有工作階段。
請參閱網路存取以了解存取層級和預設允許清單。本機 CLI 工作階段不受此原則影響。

​
The proxy refused the connection

當 Claude 透過您在 HTTPS_PROXY 或相關代理伺服器變數中設定的代理伺服器讀取 artifact 時，您會看到此訊息。Artifact 內容來自 *.frame.claudeusercontent.com，因此 Claude Code 首先向代理伺服器傳送 CONNECT 請求，要求它開啟到該主機的隧道。當代理伺服器拒絕時，沒有任何東西到達主機，訊息攜帶代理伺服器的 HTTP 狀態：
狀態是代理伺服器對 CONNECT 的回答。主機從未回答，因此每個狀態指向不同的修復：
  • HTTP 407：代理伺服器需要它沒有獲得的憑證。將它們放在代理伺服器 URL 中，如基本身分驗證所示。
  • HTTP 403：代理伺服器拒絕建立到 *.frame.claudeusercontent.com 的隧道。要求管理代理伺服器的人允許該主機，網路存取要求會列出該主機。
  • 任何其他狀態，例如 HTTP 502：代理伺服器因其自身原因未開啟隧道，例如無法到達主機。在代理伺服器的日誌中查詢狀態。
  • unreadable reply 代替狀態：代理伺服器位址上的任何東西都沒有用 HTTP 狀態列回答。檢查位址是否為 HTTP 代理伺服器。
該怎麼做：
  • 檢查代理伺服器變數中的位址和憑證，如代理伺服器設定所述，然後從啟動 Claude Code 的 shell 執行 curl -x http://proxy.example.com:8080 -I https://api.anthropic.com，使用您自己的代理伺服器 URL。在 Windows PowerShell 上，執行 curl.exe。如果此探測以相同方式失敗，請先修復代理伺服器設定。如果成功，拒絕特定於 artifact 主機。
  • 如果您的網路讓 Claude Code 直接到達 artifact 主機，將 .frame.claudeusercontent.com 新增到 NO_PROXY。保持條目狹窄：更廣泛的 .claudeusercontent.com 條目也會讓 bridge.claudeusercontent.com 繞過代理伺服器，而具有 IP 允許清單的組織需要將其保留在代理伺服器上。
在 v2.1.238 之前，Claude Code 將拒絕的隧道報告為通用網路錯誤。

​
雲端環境服務傳回空的或意外的回應

Claude Code 在多個點請求您的雲端環境清單，例如當您從 CLI 建立雲端工作階段或執行 /remote-env 時。當它無法讀取伺服器的回答時，它會顯示以下其中一個訊息：
伺服器接受了請求，但用不是環境清單的主體回答：空、不是 JSON 或沒有清單的 JSON。這通常伴隨服務端中斷，並自行清除。根據請求清單的使用介面，Claude Code 可能會新增前綴，例如 /remote-env 對話方塊中的 couldn't list environments:。 該怎麼做：
  • 重試該操作。Claude Code 每次都會再次請求清單
  • 如果訊息持續出現，請檢查 status.claude.com 以了解活躍的事件
在 v2.1.236 之前，Claude Code 顯示原始 JavaScript TypeError 而不是這些訊息。

​
Failed to fetch session from Sessions API

此訊息表示 Claude Code 找到了您要求拉取到終端機的雲端工作階段，但無法從 Anthropic 的伺服器讀取其對話記錄，因此沒有開啟它：
您會在執行 claude --teleport、/teleport，或在 /tasks 清單中選擇該工作階段後看到它。claude --teleport <session-id> 會列印它並以代碼 1 退出。 該怎麼做：
  • 再次執行相同的 teleport。如果以相同方式失敗，請回報問題
在 v2.1.296 之前，Claude Code 不會重試失敗的讀取，並且在讀取失敗後可能會以空白對話開啟該工作階段並回報成功，而不是列印此訊息。

​
Couldn’t reconnect to your Remote Control session

使用 claude --resume 或 claude --continue 恢復會重新連線到該對話中記錄的 Remote Control 工作階段。此訊息表示重新連線因可能是暫時的原因（例如網路中斷或伺服器錯誤）而失敗，因此 Claude Code 無法確認遠端工作階段是否仍然存在。您的本機工作階段在沒有 Remote Control 的情況下繼續執行。 該怎麼做：
  • 執行 /remote-control 以重試連線
  • 使用 claude --remote-control 啟動新工作階段以建立新的 Remote Control 工作階段
  • 對於其他 Remote Control 啟動訊息，請參閱Remote Control 疑難排解
如果伺服器改為報告前一個工作階段已消失，您不會看到此訊息。Claude Code 會在其位置啟動新工作階段或顯示 Previous session is unavailable — run /remote-control to start a new one。

​
Sessions ended while this machine was offline

Claude Code 在執行 claude remote-control 的終端機中顯示此訊息，在您的機器離線足夠長的時間後，伺服器清理了您的機器正在提供的 Remote Control 環境。該環境中的工作階段已結束，您無法恢復它們。計數是已結束的工作階段數。
該怎麼做：
  • 當 Claude Code 在此訊息下列出保留的 worktree 時，從它們中取回任何未提交的工作
  • 執行 claude remote-control 以啟動新環境

​
Couldn’t share the transcript

在您同意從調查提示（例如工作階段品質調查）共享您的工作階段逐字稿後，Claude Code 將其上傳到 Anthropic，或在第三方提供者上、Claude apps 閘道工作階段上以及當沒有 Anthropic 憑證可用時改為儲存本機封存。此訊息表示共享未完成。
上傳必須符合 8 MiB 限制。在長工作階段上，Claude Code 逐步丟棄共享的部分，最後一個請求的模型設定優先，然後是結構化對話和 subagent 逐字稿，並在無法傳送任何縮減版本或網路或伺服器錯誤停止上傳時顯示此訊息。當 Claude Code 改為儲存本機封存時，訊息表示它無法寫入封存。 該怎麼做：
  • 執行 /feedback 以傳送逐字稿並描述發生了什麼。如果您的環境中無法使用 /feedback，請參閱報告錯誤
  • 如果其他請求也失敗，請檢查您的網路連線並查看 Unable to connect to API

​
Couldn’t send feedback

您從 /feedback、/bug 或 /share 對話方塊傳送了報告，上傳到 Anthropic 失敗。對話方塊會保留您的文字，以便您可以重試。
前綴後的文字會命名失敗的內容：
  • : not signed in. Run /login, then retry.：對話方塊僅在 Claude Code 開啟時找到 Anthropic 憑證的情況下上傳，而到您傳送時已沒有可用的憑證。例如，您在此期間在此機器上登出，或您的登入無法再刷新。
  • 括號內容：(server returned <status>) 是服務的回應代碼；(request timed out) 和 (couldn't reach the service) 是網路故障。當 Claude Code 無法命名原因時，括號內容不存在。
在意見反應草稿佇列中，相同的故障改以 The draft is still queued. Try again later. 結束，草稿保留在佇列中以供另一次嘗試。 該怎麼做： 在 v2.1.281 之前，一旦在對話方塊開啟期間收到 Remote Control Stop 或緊急跨工作階段訊息，之後每次傳送都會失敗並出現此訊息。在這些版本上，關閉對話方塊，重新開啟它，然後再次傳送。

​
請求錯誤

這些錯誤與您的請求內容有關。大多數來自 API 在拒絕請求後的回應；少數是由 Claude Code 在發送任何請求之前在本地產生的。

​
Prompt is too long

對話加上附加檔案超過了模型的上下文視窗。
在互動式工作階段中，Claude Code 將此錯誤顯示為：
當設定了 DISABLE_COMPACT 時，該行僅命名 /clear。較長形式的錯誤（例如下面的壓縮失敗形式）保留 Prompt is too long · 的措辭。在 -p 輸出和逐字稿中，文字保持為 Prompt is too long。 當您在使用者設定中關閉自動壓縮時，該行也會說明這一點：
/config 中的自動壓縮切換會將 autoCompactEnabled 寫入使用者設定。該提示僅在 /config 變更會生效時出現。例如，當 DISABLE_AUTO_COMPACT 或 DISABLE_COMPACT 關閉自動壓縮時，它不會出現。當更高優先級的範圍（例如專案或受管設定）將 autoCompactEnabled 設定為 false 時，它也不會出現。在 v2.1.235 之前，該行沒有自動壓縮提示。 Amazon Bedrock 將此狀況報告為 Input is too long for requested model.，Claude Code 以相同方式處理。在 v2.1.217 之前，Claude Code 沒有識別 Bedrock 的措辭，因此自動壓縮從未在其上觸發，/compact 失敗並出現相同錯誤。 Claude 應用程式閘道在雲端上游以提供者自己的錯誤形狀拒絕請求時，將此狀況報告為 capability_rejected: prompt_too_long。Claude Code 將該 token 視為與 Prompt is too long 相同。在 v2.1.228 之前，Claude Code 沒有識別該 token，因此自動壓縮沒有在其上觸發。 當自動壓縮在此回合上執行並因基礎錯誤（例如不可用的模型或身分驗證失敗）而失敗時，該訊息在分隔符後命名該錯誤：
首先解決命名的錯誤；在您這樣做之前，/compact 會因相同錯誤而失敗。在 v2.1.229 之前，失敗的自動壓縮會顯示 Prompt is too long 而不顯示原因。 當自動壓縮在此錯誤上執行時，它通常會總結您最舊的交換並保留最新的。作為最後手段，Claude Code 會以不同方式進行總結：
  • 當它無法總結任何完整交換時，Claude Code 會逐字保留您最新的提示詞，並總結其前面的所有內容。
  • 在這種情況下，當對話不以您的提示詞結尾時，Claude Code 會改為總結整個對話。
當它要轉發的內容不包含模型回覆且您自己的文字少於約 1,000 個 token（例如在超大貼上後發送的簡短重試）時，Claude Code 會跳過此恢復。執行 /clear 以重新開始。在 v2.1.269 之前，每當壓縮無法總結完整交換時，壓縮就會失敗，因此處於該狀態的工作階段在每個回合都會再次遇到此錯誤。 單一交換對話沒有更早的回合可以總結。當自動壓縮會在其上執行時，Claude Code 會跳過嘗試並解釋請求中填充的內容。當 API 在其錯誤中不報告 token 計數時，訊息讀取為：
當 API 在其錯誤中報告 token 計數時，Claude Code 會將其與自己對對話大小的估計進行比較，以判斷請求的大部分是什麼：對話自己的內容，或 Claude Code 與其一起發送的系統提示詞、工具定義和附加內容。當對話自己的內容是請求的大部分時，訊息讀取為：
當請求的大部分在對話之外時，訊息讀取為：
在 v2.1.162 之前，Claude Code 無論如何都嘗試壓縮，並在失敗時顯示裸露的 Prompt is too long。 該怎麼辦：
  • 執行 /compact 以總結較早的回合並釋放空間，或執行 /clear 以重新開始。如果 /compact 回答 Not enough messages to compact.，對話是單一交換，沒有更早的內容可以總結，因此空間由該單一提示詞和 Claude Code 與每個請求一起發送的內容佔用：執行 /clear 並使用較少的貼上文字或較小的附加檔案重新發送，或使用下面的步驟減少工具定義和記憶檔案
  • 執行 /context 以查看視窗中消耗的內容的細目：系統提示詞、工具、記憶檔案和訊息
  • 使用 /mcp disable <name> 禁用您未使用的 MCP 伺服器，以從上下文中移除其工具定義
  • 修剪大型 CLAUDE.md 記憶檔案，或將指示移至路徑範圍規則，這些規則僅在相關時載入
  • 自動壓縮預設為開啟，通常可防止此錯誤。如果您在 /config 中或使用 DISABLE_AUTO_COMPACT 關閉了它，請將其重新開啟。如果您保持關閉，請在視窗填滿之前自己執行 /compact。
  • 若錯誤在接受更多 token 的模型上於接近 200K token 時出現，原因之一是 Claude Code 無法辨識的模型 ID。Claude Code 會為這類 ID 假設 200K 的視窗，因此若要在超過該點後繼續工作，請提供模型的實際上下文視窗。
請參閱探索上下文視窗以獲得上下文如何填滿的互動式檢視。

​
上下文超過 token 限制

/context 顯示此警告在其輸出頂部，當對話超過模型的上下文視窗時。在您釋放空間之前，請求會因 Prompt is too long 而失敗。互動式工作階段將該錯誤顯示為 Context limit reached 行。
當您超過的限制是壓縮視窗（例如 1M 上下文模型上的 200K 邊界）時，警告的讀取方式不同。壓縮視窗可以位於模型的上下文視窗下方，因此超過它的請求仍然可以成功。
當您設定了 DISABLE_COMPACT 時，兩種形式都命名 /clear 而不是 /compact。 該怎麼辦：
  • 在多回合對話中，執行 /compact 以總結較早的回合並釋放空間。若要改為重新開始，請執行 /clear
  • 有關減少使用的更多方式，請參閱 Prompt is too long
在 v2.1.216 之前，/context 顯示超過 100% 的使用情況，沒有警告行解釋這意味著什麼或如何恢復。

​
Request too large

原始請求正文在 token 化之前超過了 API 的 32MB 限制，通常是因為大型貼上內容、工具結果或附加檔案。此限制與上下文視窗分開。
當請求直接進入 Claude API 且 API 本身拒絕它時，Claude Code 會測量對話並根據恢復是否可行來措辭訊息。通過代理伺服器、閘道或雲端提供者，您會收到一般訊息。測量的形式：
  • Request too large (max 32MB; 20.1MB of about 33.4MB is images or documents).：影像或文件將請求推過限制。Claude Code 會在去除它們後重試。
  • Request too large for the API's 32MB request limit：訊息本身超過限制，因此訊息說 compacting cannot make it fit，Claude Code 不會重試。在非互動模式中，訊息告訴您減少輸入或改為開始新工作階段。
在 v2.1.212 之前，具有足夠累積影像的對話在每個回合都因 Request too large (max 32MB). Double press esc to go back and try with a smaller file. 而失敗。在 v2.1.229 之前，Claude Code 對每個拒絕都顯示附加建議，即使壓縮無法幫助。 該怎麼辦：
  • 如果訊息說 compacting cannot make it fit，按 Esc 兩次以回到添加大型內容的回合之前，或執行 /clear 以重新開始
  • 否則，執行 /compact，它會刪除累積的影像和附加檔案
  • 按路徑參考大型檔案而不是貼上其內容，以便 Claude 可以分塊讀取它們
  • 對於影像，請參閱下面的 Image was too large

​
Image was too large

貼上或附加的影像超過了 API 的大小或尺寸限制。
could not be processed and was removed 這一行表示 API 拒絕了對話中的某張圖片，例如超過大小或尺寸上限的圖片。 若其中某個錯誤持續出現，請更新 Claude Code。在較舊的版本中，圖片錯誤可能因下列原因重複出現：
  • 在 v2.1.299 之前，在含有許多圖片的長對話中，Claude Code 可能會移除您最後附加的圖片，而非超過上限的那張。接著 was removed 這一行會在每個回合重複出現，且 Claude 看不到您的新圖片。
  • 在 v2.1.299 之前，在 VS Code、Desktop 應用程式和 Agent SDK 中，您在 Claude 工作期間附加的圖片不會像其他附加圖片一樣經過縮放。它們以原始大小送達 API，導致長對話中重複出現圖片錯誤。
  • 在 v2.1.166 之前，貼上的圖片可能會留在對話中，導致之後的每則訊息都重複出現相同錯誤
該怎麼辦：
  • 在貼上之前調整影像大小。API 接受單個影像最長邊最多 8000 像素的影像，或當上下文中有超過 20 張影像時最多 3000 像素。
  • 拍攝相關區域的更緊密螢幕截圖，而不是整個螢幕

​
Unable to resize image

Claude Code 無法在將附加影像發送到 API 之前將其縮小。
Claude Code 通常會自動調整大型影像的大小。這些錯誤意味著影像無法解碼或調整大小以符合 API 限制。 該怎麼辦：
  • 如果訊息要求您轉換影像，請將其轉換為 PNG、JPEG、GIF 或 WebP 並再次附加。Claude Code 可以從檔案標頭驗證這些格式的尺寸，而無需解碼影像。
  • 如果訊息報告尺寸或大小限制，請在附加之前將影像調整大小或重新壓縮到該限制以下。
  • 如果訊息命名原因（例如 CMYK JPEG、動畫 WebP 或可能損壞的檔案），請以訊息建議的格式重新保存影像並再次附加。

​
Request rejected as unprocessable by the model

API 拒絕了該請求，認為模型無法處理。此訊息來自 API 本身。
Claude Code 可以從被拒絕的請求中移除最舊的圖片和文件，然後重新傳送。在 v2.1.290 之前，Claude Code 遇到此拒絕時不會移除圖片，因此累積了數百張圖片的長時間工作階段可能每個回合都會以此錯誤失敗。 處理方式：
  • 如果此訊息在含有圖片或文件的對話中持續出現，請自行將其移除。按兩次 Esc 回到加入它們的回合之前，或執行 /clear 重新開始。

​
PDF 錯誤

您附加的 PDF 無法處理。訊息在此以非互動形式顯示；在互動式工作階段中，它們會提示您按 Esc 兩次並重試。
該怎麼辦：
  • 對於超大 PDF，要求 Claude 使用 Read 工具讀取頁面範圍而不是附加整個檔案，或使用 pdftotext 之類的工具提取文字並按路徑參考輸出檔案
  • 對於受保護或無效的 PDF，移除密碼或從其來源應用程式重新匯出檔案，然後重試
當 Claude 使用 Read 工具從 PDF 讀取頁面範圍時，讀取可能因不同訊息而失敗：
頁面範圍讀取使用 pdftoppm 呈現頁面。使用訊息提供的命令安裝 poppler-utils，或在其他平台上安裝將 pdftoppm 放在您的 PATH 上的 poppler 建置。請參閱Read 工具行為以了解哪些 PDF 按頁面範圍讀取。

​
Extra inputs are not permitted

Claude Code 和 API 之間的代理伺服器或 LLM 閘道去除了 anthropic-beta 請求標頭，因此 API 拒絕了依賴它的欄位。
Claude Code 會發送測試版專用欄位（例如 context_management），並附上啟用它們的 anthropic-beta 標頭。當閘道轉發本文但刪除標頭時，API 會看到它無法識別的欄位。 該怎麼辦：

​
工具輸入 schema 無效

請求中的工具聲明了 input_schema，該 schema 未通過 API 的 JSON Schema 驗證，因此 API 拒絕了整個請求。tools. 後面的數字是失敗工具在請求的工具列表中的位置，而不是您可以查找的名稱。
第一種形式意味著 schema 不是有效的 JSON Schema draft 2020-12。第二種意味著頂級屬性名稱與訊息引用的模式不匹配。 Claude Code 在載入伺服器的工具時排除輸入 schema 會失敗此驗證的 MCP 工具，因此請求通常永遠不會包含一個。 在旗標擷取關閉的部署上，或在旗標從未到達的機器上，Claude Code 在伺服器的日誌中記錄哪個工具會被拒絕，但無論如何都會發送它，因此此錯誤仍然可能發生。 該錯誤也可能發生在工具的 schema 在 $schema 中聲明 JSON Schema 方言而不是 draft 2020-12 的情況下。Claude Code 不會根據 JSON Schema 元 schema 檢查這些 schema，儘管頂級屬性名稱檢查仍然適用。 在 v2.1.216 之前，沒有部署執行排除檢查。 該怎麼辦：
  • 如果您的 Claude Code 版本早於 v2.1.216，請執行 claude update。
  • 移除或禁用聲明無效 schema 的 MCP 伺服器。該錯誤僅按位置命名工具。在 v2.1.216 或更高版本上，檢查每個伺服器的日誌以查找命名輸入 schema 會被拒絕的工具的行。如果沒有日誌命名一個，請一次禁用一個伺服器。
  • 如果您維護伺服器，請修復工具的 input_schema。schema 必須是有效的 JSON Schema，頂級屬性名稱必須是 1 到 64 個字元長，並且只使用 ASCII 字母和數字、_、. 和 -。請參閱輸入 schema 無效的工具。

​
MCP 工具名稱超過 128 個字元

MCP 伺服器列出的工具完整名稱（例如 mcp__<server>__<tool>）超過 API 接受的 128 個字元。Claude Code 會將該工具排除在傳送給 Claude 的工具之外，而該伺服器的其他工具仍可正常運作。在您從 shell 以 claude --debug 啟動的工作階段中，Claude Code 會將此訊息寫入位於 ~/.claude/debug/<session-id>.txt 的偵錯日誌：
該怎麼辦：
  • 如果您維護該伺服器，請縮短工具的名稱。
  • 如果該伺服器位於您的 MCP 設定中，請在該處為其指定較短的名稱，例如以 db 取代 analytics-database。然後更新以舊名稱參照該伺服器或其工具的項目，例如權限規則和 hook matcher。
  • 如果外掛捆綁了該伺服器，工具的完整名稱也會包含外掛名稱。請要求外掛的維護者縮短伺服器或工具名稱。
在 v2.1.292 之前，Claude Code 仍會傳送該工具，而 API 會以 API Error: 400 ... tools.N.custom.name: String should have at most 128 characters 拒絕包含它的每個請求。

​
tool_use.name 超過 200 個字元

對話記錄中的工具呼叫攜帶的名稱長度超過 API 在請求中接受的 200 個字元：
Claude Code 在回應到達時以及載入已保存的對話時將此類名稱切割為 200 個字元，因此呼叫失敗並出現 No such tool available 工具錯誤，對話繼續而不出現此 API 錯誤。 該怎麼辦：
  • 執行 claude update，然後繼續對話。更新的版本在載入逐字稿時修復超長名稱，因此卡住的對話再次工作。
在 v2.1.281 之前，超長名稱保留在對話記錄中，API 拒絕了重新發送對話的每個請求，包括 /compact 和 --resume，因此此錯誤重複出現，對話被卡住。

​
There’s an issue with the selected model

設定的模型名稱未被識別，或您的帳戶缺少對其的存取權限。從 v2.1.160 開始，尾部提示（此處以其互動形式顯示）因使用介面而異。
該怎麼辦：
  • 互動式 CLI：執行 /model 以從您帳戶可用的模型中選擇。
  • 非互動模式 (-p)：使用有效的別名或 ID 傳遞 --model，或設定 ANTHROPIC_MODEL。錯誤文字在此使用介面上顯示 Run --model。
  • Agent SDK：錯誤文字省略提示，因為模型是以程式設計方式設定的。在 TypeScript 中的 Options 上設定 model，或在 Python 中設定 ClaudeAgentOptions(model=...)，並處理結構化的 model_not_found 錯誤以顯示您自己的重試或模型選擇器。
  • 使用別名（例如 sonnet 或 opus）而不是完整的版本化 ID。別名解析為維護的預設值，因此它們不會過時。請參閱模型設定。
  • 如果錯誤的模型在 CLI 中不斷出現，則某處設定了過時的 ID。按優先順序檢查您可以設定模型的位置，並移除過時的值。
  • Claude Code 將過期的 claude.ai 登入報告為 Login expired，而不是此錯誤。在 v2.1.206 之前，無法再刷新的過期登入對每個模型都失敗，並出現此錯誤；如果您在較舊版本上看到此錯誤，請執行 /login。
  • 對於 Google Cloud 的 Agent Platform 部署，請參閱 Google Cloud 的 Agent Platform 疑難排解。

​
Model is not a recognized model id

您傳遞給模型切換的字串不是 Claude Code 可以用作模型的字串，因此它拒絕了切換而不發送請求，工作階段保留其目前模型。當模型通過 Agent SDK setModel() 方法設定時，您可能會收到此錯誤，由為您執行 Claude Code CLI 的應用程式（例如桌面應用程式），或當您從通過 Remote Control 連接的裝置選擇模型時。在 v2.1.200 之前，Claude Code 保存了字串並在下一個請求時因 There’s an issue with the selected model 而失敗。
在此範例中，應用程式發送了顯示名稱 Sonnet 5，訊息重複時沒有其空格。尾部提示命名最接近的匹配別名或模型 ID。當沒有足夠接近的內容時，它讀取 Run /model to see available models. 代替。在桌面應用程式為您啟動的工作階段中，無匹配提示讀取 Switch to a different model. 當您通過 Agent SDK 或在 Anthropic API 上的應用程式切換時，只有無法成為模型 ID 的字串（例如顯示名稱或空字串）會收到此錯誤。 當您從 Remote Control 裝置選擇模型時，Claude Code 在本地檢查字串。任何不是模型別名、Claude Code 列出或您設定的模型，或以 claude- 開頭的 ID 的字串都會收到此錯誤，包括拼寫錯誤的 ID（例如 claud-sonnet-5）。在 v2.1.260 之前，此檢查不涵蓋 Remote Control 選擇，因此無法識別的字串被應用，並在下一個請求時失敗。 該怎麼辦：
  • 執行 /model 而不帶引數以開啟選擇器並從您帳戶可用的模型中選擇，然後傳遞那裡顯示的別名或 ID
  • 如果您使用了較新 Claude Code 版本支援的別名，請執行 claude update，或傳遞模型的完整 ID 代替。伺服器仍然可以要求該模型的最低 Claude Code 版本；請參閱 Claude Code does not support this model。
  • v2.1.200 之前保存的模型不會被此檢查修復。如果過時的值不斷出現，請從設定您的模型下列出的位置移除它。
  • 在 Anthropic API 以外的任何提供者上，或在閘道或自訂 ANTHROPIC_BASE_URL 後面，只有空字串會收到此錯誤。Claude Code 仍然可以在請求時寫入無法識別的模型診斷行，在每個提供者上。

​
Model not found

您使用名稱切換到模型，Claude Code 無法確認存在具有該名稱的模型。當名稱不是模型別名或 Claude Code 在本地接受的其他拼寫時，Claude Code 使用最小 API 請求驗證它，此錯誤通常是您的 API 端點的答案。使用 /model <name> 時，無法成為模型 ID 的名稱（例如包含空格的名稱）會收到相同訊息。
在具有提供者特定模型 ID 的提供者上，訊息可能會添加 Try '...' instead 建議，該建議命名您提供者的備援模型 ID。 該怎麼辦：
  • 執行 /model 而不帶引數並從您帳戶可用的模型中選擇，或使用模型別名（例如 sonnet），該別名解析為維護的預設值
  • 如果您輸入了完整 ID，請根據您提供者的模型目錄檢查它。新推出的模型可能在 Anthropic API 上可用，然後您的提供者或地區才提供它。
  • 在 Agent SDK 中，setModel() 因此訊息而失敗，工作階段在其先前的模型上繼續執行。在 TypeScript SDK 中，呼叫 supportedModels() 以列出您可以切換到的模型。
  • 在 v2.1.265 之前，/model 也以此錯誤拒絕了 opusplan[1m] 別名拼寫。在這些版本上，更新 Claude Code，或在設定中或使用 --model 代替設定模型。

​
Couldn’t confirm model with the API

您通過 Agent SDK setModel() 方法或為您執行 Claude Code CLI 的應用程式（例如桌面應用程式）切換了模型，確認模型 ID 與您的 API 端點的請求在五秒內沒有得到答案。工作階段保留其目前模型。
在桌面應用程式為您啟動的工作階段中，訊息在 Try again. 結尾。 該怎麼辦：
  • 再次切換到模型
  • 如果切換不斷失敗，請檢查 Claude Code 是否可以到達您的 API 端點；請參閱網路和連接錯誤

​
檢查選定模型時出現 API 錯誤

您使用 /model <name> 選擇了模型，或連接到工作階段的應用程式請求了切換。API 拒絕了 Claude Code 發送以驗證模型的最小請求，原因沒有自己的條目，例如速率限制或伺服器錯誤。工作階段保留其目前模型，訊息以說明這一點結尾：
訊息的中間是 HTTP 狀態和伺服器自己的解釋。 該怎麼辦：

​
Claude Opus is not available with the Claude Pro plan

您的有效訂閱計畫不包括您選擇的模型。
在 Claude 桌面應用程式執行的工作階段中，訊息說改為 sign out and sign in again 而不是命名命令。 該怎麼辦：
  • 執行 /model 並選擇您的計畫包括的模型
  • 如果您最近升級了計畫但仍然看到此訊息，請執行 /logout 然後 /login。儲存的 token 反映您登入時的計畫，因此在現有工作階段中在 claude.ai 上升級不會生效，直到您重新驗證。
  • 請參閱 claude.com/pricing 以了解每個計畫包括哪些模型

​
Claude Code does not support this model

API 因為您的 Claude Code 版本低於所需的最低版本而拒絕了請求，並返回 400。您選擇的模型需要較新版本（伺服器按模型檢查），或您組織的政策需要一個。400 攜帶錯誤代碼 claude_code_version_too_old，訊息說明適用的最低版本。
組織政策措辭讀取為：
發送請求的 Claude Code 二進位檔案報告的版本是 API 檢查的版本。 該怎麼辦： 更新該二進位檔案，然後啟動新工作階段。二進位檔案的來源決定了如何，除了在自託管環境中：
  • 如果您在穩定版發布通道上執行 claude update，它不會讓您超過最新的穩定版本，而該版本仍可能低於所需的最低版本。請切換到最新版通道，然後再次更新。如果您的組織透過受管設定固定您的通道或版本，請要求您的管理員變更它
  • 對於按模型措辭，您可以通過切換到另一個模型來在目前工作階段中繼續工作：在 CLI 中執行 /model，在 TypeScript SDK 的 Query 物件上呼叫 setModel()（在串流輸入模式中），或在 Python SDK 的 ClaudeSDKClient 上呼叫 set_model()
  • 對於組織政策措辭，在繼續之前更新

​
Model is restricted by your organization’s settings

您的組織管理員在 claude.ai 管理控制台中禁用了此模型，或受管設定通過 availableModels 允許清單或 deniedModels 清單排除了它。當 --model、ANTHROPIC_MODEL 或 model 設定命名受限制的模型時，通知在啟動時出現，並命名工作階段改為使用的模型。如果受管設定沒有為工作階段留下允許的模型，請參閱受管設定阻止預設模型。替換通知也可能在工作階段中期出現，在管理員在 claude.ai 管理控制台中禁用工作階段執行的模型之後。
為受限制的模型輸入 /model <name> 會被拒絕，工作階段保留其目前模型。對於在管理控制台中禁用的模型，拒絕讀取 Model '<name>' is restricted by your organization's settings. Run /model to choose a different model. 對於受管設定排除的模型，它讀取 Model '<name>' is not available. Your organization restricts model selection. 前綴為 agent、skill 或命令名稱的通知意味著限制適用於該 subagent 的請求模型：subagent 在替換模型上執行，您的工作階段模型保持不變。在 v2.1.223 之前，Claude Code 僅對使用 Agent 工具啟動的 subagent 顯示通知。 Claude Code 將模型系列別名（opus、sonnet、haiku 或 fable 之一）視為對該系列的請求，而不是對其最新版本的請求。在 Anthropic API 和AWS 上的 Claude Platform 上，受限制的系列別名解析為您組織的設定允許的系列的最新版本，替換通知命名該版本。Claude Code 僅當系列的每個版本都受限制時才拒絕 /model <alias>。在 v2.1.205 之前，系列別名基於其最新版本單獨被替換或拒絕，即使允許同一系列的較舊版本。 該怎麼辦：
  • 執行 /model 以從您組織允許的模型中選擇。受限制的模型在選擇器中隱藏。
  • 如果受限制的模型是在 --model、ANTHROPIC_MODEL、設定檔的 model 欄位或 subagent、skill 或命令的 model frontmatter 中設定的，請移除或更新該值，以便通知不會再次出現
  • 如果您需要存取受限制的模型，請要求您的組織管理員啟用它。請參閱組織模型限制。

​
Can’t switch to the default model

您選擇了預設模型，例如通過在 /model 選擇器中選擇預設行或輸入 /model default。Claude Code 拒絕了切換，因此工作階段保留其目前模型。
冒號後的措辭命名阻止切換的內容：
  • your organization's managed settings block it ... in "deniedModels"：受管拒絕清單阻止預設選項解析為的模型
  • your organization allows only the models listed in "availableModels"：受管 availableModels 允許清單，其中 availableModelsMatch 設定為 "exact" 遺漏了預設選項解析為的模型
  • Claude Code couldn't read your organization's managed settings to check which models they allow：受管設定無法讀取，Claude Code 拒絕切換而不是應用未檢查的切換
該怎麼辦：
  • 對於 deniedModels 和 availableModels 措辭，執行 /model 並按名稱選擇您的組織允許的模型
  • 要求您的管理員更新訊息命名的受管設定
  • 對於 couldn't read 措辭，重新啟動 Claude Code；如果它繼續發生，要求您的管理員檢查受管設定
如果工作階段改為因這些受管設定而無法啟動，並出現 Claude Code can't start 訊息，請參閱受管設定阻止預設模型。

​
Model switch was blocked by a PreModelSwitch hook

PreModelSwitch hook 沒有核准您或用戶端請求的模型切換，因此工作階段保留其目前模型。當切換來自 Agent SDK 主機或 Remote Control 而不是您輸入的命令時，訊息讀取 Model switch blocked by a PreModelSwitch hook 而不命名目標模型。
冒號後的原因說明拒絕切換的原因：
  • hook 寫入的原因：PreModelSwitch hook 在拒絕切換或要求確認時提供了該原因。解決它要求的內容，或選擇您的 hook 允許的模型。
  • PreModelSwitch hook <name> did not respond before its timeout：在其逾時之前沒有回答的 hook 會阻止切換。修復掛起的命令或提高該 hook 的 timeout，然後再次切換。
  • confirmation required, and this session cannot ask：hook 回答了 ask 而沒有原因，控制請求無法顯示確認提示。-p 執行中的 /model 命令以 (run /model interactively to confirm) 報告相同狀況在原因之後。從互動式工作階段進行切換，或更改 hook 對此模型的決定。
  • so organization-managed PreModelSwitch hooks could not be checked：Claude Code 無法判斷您組織的受管外掛提供哪些 PreModelSwitch hook，例如因為受管外掛無法載入。其中一個 hook 可能會阻止切換，因此 Claude Code 拒絕而不是應用未檢查的切換。原因的開始命名失敗的內容。Claude Code 在每次切換嘗試時重新檢查，因此已清除的失敗停止阻止；如果它繼續失敗，請執行 claude --debug 並再次切換以捕獲詳細資訊，然後修復外掛或要求您的管理員修復它。
  • a PreModelSwitch hook failed before answering 或 PreModelSwitch hooks were cancelled (the control stream closed) before answering：hook 執行在沒有判決的情況下結束，Claude Code 不將其視為核准。執行 claude --debug 以查看失敗的內容，然後再次切換。
在 v2.1.260 之前，受管外掛拒絕讀取 plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log。Claude Code 重試外掛載入一次，然後在工作階段中拒絕後續切換，即使您的組織沒有受管外掛。在這些版本上重新啟動工作階段以再次執行外掛載入。

​
Couldn’t save it as your default

您選擇了模型以保存為預設值，例如使用 /model <name> 或 /model 選擇器中的 Enter，Claude Code 無法將選擇寫入您的使用者設定檔 ~/.claude/settings.json。切換本身已應用，因此目前工作階段在您選擇的模型上執行，但您的預設值保持不變，下一個工作階段在舊值上啟動。
檔案路徑後的原因說明失敗的內容：
  • can't be written (<code>)：寫入因作業系統錯誤代碼（括號中）失敗，例如當檔案或它連結到的檔案位於拒絕寫入的檔案系統上時的 EROFS。使檔案可寫入並再次切換。如果另一個工具生成檔案，請在該工具中設定 model 鍵；請參閱您在 Claude Code 中所做的變更在新工作階段中丟失。
  • isn't valid JSON：磁碟上的檔案不解析，Claude Code 保持不動而不是覆蓋它無法讀回的內容。修復語法錯誤，然後再次切換；請參閱修復損壞的設定檔。
以 couldn't confirm it was saved as your default (~/.claude/settings.json is still being written) 結尾的通知意味著寫入在三秒後未完成。它在背景中繼續，因此預設值仍然可能被保存；檢查您的下一個工作階段啟動的模型，或再次執行 /model <name>。 在 v2.1.265 之前，通知說模型是 saved as your default for new sessions 即使寫入失敗。

​
Advisor is less capable than the current main model

您的 advisor 模型排名低於工作階段的主要模型，因此 Claude Code 會保留該選擇，但不會將 advisor 附加到主要模型的請求。
其他訊息也會報告相同狀況：
  • 在互動式工作階段中，通知讀取 Advisor will not activate on the main model (advisor is less capable); subagents may still use it and may use more tokens · /advisor。
  • 使用 --advisor 旗標啟動時，警告讀取 "<advisor>" cannot advise "<main model>" (the advisor must be at least as capable as the main model). The advisor will not be used for the main model.，而工作階段仍會啟動。
該怎麼辦：
  • 選擇排名較高的 advisor 或排名較低的主要模型。選擇 advisor 模型顯示排名，並列出每個主要模型可接受的 advisor。
  • 如果您希望該 advisor 能為其模型提供建議的 subagent 繼續使用它，請保留 advisor 設定
在 v2.1.287 之前，Claude Code 對數種配對的排名不同。它會對搭配 Opus 4.7 或 Opus 4.8 主要模型的 Sonnet 5.5 advisor 顯示此提示，而它現在接受這種配對。它也會附加某些現在會產生此提示的 advisor，例如搭配 Sonnet 5.5 主要模型的 Opus 4.8 advisor。

​
thinking.type.enabled is not supported for this model

您的 Claude Code 版本早於所選模型的最低版本。CLI 發送了模型不再接受的思考設定。
該怎麼辦：
  • 執行 claude update 並重新啟動 Claude Code。Opus 4.7 需要 v2.1.111 或更高版本。Opus 4.8 需要 v2.1.154 或更高版本。Sonnet 5 需要 v2.1.197 或更高版本。Opus 5 需要 v2.1.219 或更高版本。Opus 5.5 需要 v2.1.280 或更高版本。Sonnet 5.5 需要 v2.1.284 或更高版本
  • 在穩定版發布通道上，更新不會讓您超過最新的穩定版本，而該版本仍可能早於這些版本。請切換到最新版通道，然後更新
  • 如果您無法升級，請執行 /model 並改為選擇 Opus 4.6 或 Sonnet 4.6
  • 如果您在 Agent SDK 中遇到此問題，請改為升級 SDK 套件。Opus 4.8 需要 TypeScript SDK v0.3.154 或更高版本和 Python SDK v0.2.88 或更高版本。Sonnet 5 需要 TypeScript SDK v0.3.197 或更高版本。Opus 5 需要 TypeScript SDK v0.3.219 或更高版本。Opus 5.5 需要 TypeScript SDK v0.3.280 或更高版本。Sonnet 5.5 需要 TypeScript SDK v0.3.284 或更高版本

​
Effort isn’t available with thinking turned off

您關閉了延伸思考並以 high 以上的 effort 等級執行。模型不接受該組合，因此 API 拒絕了請求。
· 後的提示因工作階段而異：在非互動式工作階段中，它讀取 use --effort high (or the effortLevel setting)，在 Claude 桌面應用程式執行的工作階段中，它讀取 you can lower effort to High。 該怎麼辦： 在 v2.1.242 之前，Claude Code 顯示 API 自己的訊息：API Error: 400 output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking. 在 v2.1.251 之前，Claude Code 以您設定的 effort 等級發送請求，因此 Opus 5 拒絕了關閉思考時 high 以上的每個請求。Claude Code 現在改為向它知道拒絕該組合的模型（例如 Opus 5）發送 effort high。

​
思考預算超過輸出限制

設定的延伸思考預算超過最大回應長度，因此沒有空間留給實際答案。
該怎麼辦：

​
Response exceeded the output token maximum

Claude 的回覆達到了請求所允許的最大輸出 token 數，並在該處被截斷：
列出 a request sent without streaming 的形式，表示某個串流請求失敗，而 Claude Code 以非串流方式重新送出，這會將回覆限制在 64,000 個輸出 token。在 v2.1.299 之前，在這類重新送出的請求中被截斷的回覆會結束該回合，且不顯示此訊息，就好像回覆已完成一樣。 處理方式：
  • 若 Claude 在回覆被截斷之前已寫出部分文字，請在互動式工作階段中回覆 continue 以要求其餘內容。該文字會保留在對話中。
  • 若訊息要求設定 CLAUDE_CODE_MAX_OUTPUT_TOKENS，請參閱 CLAUDE_CODE_MAX_OUTPUT_TOKENS 了解該值的上限，並參閱設定環境變數了解設定位置
  • 若要讓每則回覆都在上限之內，請要求 Claude 以較小的片段輸出，例如每則回覆一個檔案或一個章節

​
工具使用或思考區塊不匹配

對話記錄以不一致的狀態到達 API。
所有變體意味著相同的事情：記錄中 tool_use、tool_result 和 thinking 區塊的序列不再與 API 期望的相符。 該怎麼辦：
  • 如果您使用 Opus 4.7 或 Opus 4.8，請先執行 claude update。v2.1.156 之前的版本可以在正常工具使用期間觸發此錯誤，/rewind 不會清除它。
  • 執行 /rewind 或按 Esc 兩次，以回到損壞回合之前的檢查點並從那裡繼續。請參閱檢查點功能以了解檢查點如何建立和恢復。

​
Invalid data in redacted_thinking block

API 因為它無法接受對話記錄中較早回合攜帶的 redacted_thinking 區塊而拒絕了請求，並返回 400。
Claude Code 將對話的較早思考排除在請求之外並重試一次，因此工作階段繼續而不顯示錯誤。在 v2.1.282 之前，Claude Code 保留了被拒絕的區塊，每個後續回合都因相同錯誤而失敗。 該怎麼辦：
  • 如果您在 v2.1.281 或更早版本上，每個回合都因此錯誤而失敗，請執行 claude update 並繼續工作階段
  • 如果錯誤持續，請執行 /clear 以啟動不攜帶該區塊的對話

​
Unsupported tool content removed

當 Claude Code 直接連接到 Anthropic API 並載入或預覽已保存的工作階段時，它會移除 Anthropic API 不接受的工具內容，並在移除的內容位於兩個思考區塊之間的位置留下此行：
當 Anthropic API 以外的東西以 API 的格式回答時，此類內容會到達工作階段檔案，通常是通過 ANTHROPIC_BASE_URL 設定的第三方代理伺服器，它轉譯另一個提供者的工具呼叫。Claude Code 僅在工作階段直接連接到 Anthropic API 時移除它，並在工作階段通過代理伺服器或在另一個提供者上執行時按原樣載入已保存的記錄。在 v2.1.246 之前，Claude Code 將工具使用及其結果發送回 API，已繼續工作階段的每個回合都因 400 錯誤（例如 messages.1.content.0.server_tool_use.name: Input should be 'web_search', 'web_fetch', ...）而失敗。 該怎麼辦：
  • 當您看到佔位符行時，無需採取任何行動。工作階段繼續而不包含移除的內容。
  • 如果已繼續工作階段的每個回合都因 400 錯誤而失敗，請執行 claude update 並再次繼續工作階段。v2.1.246 之前的版本不會移除內容。

​
role ‘system’ must precede an ‘assistant’ message

API 因為系統訊息位於它不接受的對話位置而拒絕了請求，並返回 400：
Claude Code 將其某些提醒和附加文字作為系統訊息在對話內發送。當 API 拒絕一個的位置時，Claude Code 重試請求一次，將該文字作為普通使用者訊息發送。API 的同級放置措辭（例如 use the top-level 'system' parameter for the initial system prompt）獲得相同的恢復。 當錯誤確實出現時，被拒絕的系統訊息不是 Claude Code 可以移除的。這通常意味著 Claude Code 和 API 之間的代理伺服器或 LLM 閘道添加了自己的系統訊息。 該怎麼辦：
  • 如果錯誤在通過 ANTHROPIC_BASE_URL 設定的代理伺服器或閘道後面的每個回合上重複，請連接而不使用代理伺服器以確認來源，並向操作它的人報告錯誤
  • 執行 /clear 以啟動新對話。如果錯誤也在那裡返回，原因在請求路徑上，而不是在已保存的對話中。
在 v2.1.280 之前，Claude Code 沒有識別此措辭，因此當被拒絕的系統訊息是 Claude Code 本身發送的時，錯誤也出現，對話的每個後續回合都以相同方式失敗。

​
Invalid encrypted_content in search_result block

API 因為對話記錄包含它無法解密的託管網路搜尋內容而拒絕了請求，並返回 400。措辭命名它無法讀取的欄位：
來自 API 的託管網路搜尋工具的結果攜帶只有 API 可以讀取的加密欄位。encrypted_stdout 措辭命名讀取此類結果的託管程式碼執行程式的輸出，API 也會加密。API 拒絕重播它無法解密的內容的請求，例如為不同組織生成的內容。 Claude Code 自己的 WebSearch 工具將搜尋結果記錄為純文字，因此這些區塊通常通過執行託管網路搜尋本身的代理伺服器或 LLM 閘道到達對話。 對於三個網路搜尋措辭，Claude Code 將搜尋呼叫、結果和引用排除在它發送的內容之外並重試請求一次，因此工作階段繼續而不顯示錯誤。encrypted_stdout 措辭沒有此類恢復，因此該訊息仍然到達您。在 v2.1.282 之前，Claude Code 也保留了被拒絕的網路搜尋區塊，每個後續回合和 /compact 都因相同方式失敗。 該怎麼辦：
  • 如果您在 v2.1.281 或更早版本上，每個回合都因其中一個網路搜尋措辭而失敗，請執行 claude update 並繼續工作階段
  • 如果錯誤持續，或訊息命名 encrypted_stdout，請執行 /rewind 以回到添加內容的回合之前的檢查點，或執行 /clear 以啟動不攜帶它的對話
  • 如果您在代理伺服器或閘道後面執行 Claude Code，請向操作它的人報告錯誤

​
使用政策拒絕

API 拒絕回應，因為對話中的內容觸發了使用政策檢查。 如果訊息包含 Details: `[reasoning_extraction]` 這一行，請參閱安全措施標記了要求提供 Claude 推理過程的請求。 訊息包括您可以引用給支援的請求 ID 和訊息 ID，如果您認為拒絕不正確。
訊息命名拒絕的模型，或當沒有記錄模型時命名 Claude。 檢查評估完整對話，而不僅是您的最新提示詞，因此在同一工作階段中發送新訊息通常會重新觸發相同的拒絕。使用 --continue 或 --resume 退出並重新開啟工作階段時也是如此，因為磁碟上的逐字稿仍然包含觸發內容。在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，此訊息也涵蓋模型的安全措施標記為網路安全主題的請求。請參閱安全措施標記了網路安全主題。 在 v2.1.219 之前，訊息讀取 Claude Code is unable to respond to this request, which appears to violate our Usage Policy (https://www.anthropic.com/legal/aup). Please double press esc to edit your last message or start a new session for Claude Code to assist with a different task. 該怎麼辦：
  • 按 Esc 兩次或執行 /rewind 以回到觸發拒絕的回合之前的檢查點，然後重新措辭或採取不同的方法。請參閱檢查點功能。
  • 如果您無法識別哪個回合導致了它，請執行 /clear 以在同一專案中啟動新對話。您之前的對話保存在磁碟上，並在 /resume 中保持可用。
  • 在非互動模式(-p) 中，其中無法進行倒帶，請在沒有 --continue 的新工作階段中使用重新措辭的提示詞重試。政策檢查因模型而異，因此使用 --model 切換到不同的模型也可能在某些情況下解決拒絕。

​
安全措施標記了網路安全主題

模型的安全措施將對話中的內容標記為網路安全主題。訊息命名標記請求的模型：
如果訊息包含 Details: `[reasoning_extraction]` 這一行，請參閱安全措施標記了要求提供 Claude 推理過程的請求。 此訊息連結到網路安全驗證計畫，該計畫為合法網路安全工作授予存取權限。具有自動模型備援的模型會印出不含此連結的不同訊息；在 Opus 5.5 和 Sonnet 5.5 上，該訊息以 <model>'s safeguards flagged this session 開頭。該章節也說明了 Claude Code 何時改為切換模型。 在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，網路安全標記會產生使用政策拒絕訊息。 該怎麼辦：
  • 如果您的工作需要此內容，請通過網路安全驗證計畫申請存取權限
  • 如果您的請求不是關於網路安全主題，請執行 /feedback 以報告誤報
  • 若要在同一工作階段中繼續工作，請按 Esc 兩次或執行 /rewind 以回到觸發標記的回合之前的檢查點，然後採取不同的方法。請參閱檢查點功能。
如果您看到的訊息措辭與下列其中之一相同，則為較早版本 Claude Code 上的相同旗標：
  • 從 v2.1.219 到 v2.1.296，訊息也可能在結尾句之前包含 Apply to the Cyber Verification Program to reduce these interruptions.
  • 從 v2.1.203 到 v2.1.218，訊息內容為 <model> has safety measures that flagged this message for a cybersecurity topic. To learn about the Cyber Verification Program and apply for access, visit our help center:，後接相同的說明中心連結。在互動式工作階段中，訊息會接著顯示 If you were not engaging in a cybersecurity topic, please send feedback via /feedback.
  • 在 v2.1.203 之前，訊息內容為 <model>'s safeguards flagged this message for a cybersecurity topic. If your work requires this access, you can apply for an exemption:，後接豁免表單連結

​
安全措施標記了要求提供 Claude 推理過程的請求

API 拒絕了該請求，因為安全措施將其標記為要求模型在回應中重現其內部推理。API 將此拒絕類別命名為 reasoning_extraction，拒絕訊息會包含這一行：
在 v2.1.234 之前，拒絕訊息不包含 Details 行。 該怎麼辦：
  • 移除或改寫任何要求 Claude 逐字或以固定格式寫出其思考或推理的指示，例如 <thinking> 區段、草稿區段，或 JSON 輸出中的 reasoning 欄位。該指示可能位於您的提示詞中，或位於 Claude Code 隨之載入的自訂內容中，例如 CLAUDE.md、skill、subagent 提示詞、輸出風格或 MCP 工具描述。
  • 若要檢查自訂內容是否為觸發原因，請在終端機中執行 claude --safe-mode，以停用自訂內容的狀態啟動工作階段，然後發送相同的提示詞
  • 變更自訂內容後，請啟動新的工作階段
  • 若要改寫已發送的提示詞，請參閱倒回並摘要
  • 您仍然可以要求 Claude 解釋其答案。請要求簡短的解釋、結果背後的依據，或其所採取動作的摘要。若要閱讀 Claude 思考的摘要，請參閱 showThinkingSummaries。
  • 如需更多範例，以及改寫後的請求仍被拒絕時該怎麼辦，請參閱將推理保留在思考區塊中

​
Output blocked by content filtering policy

API 的輸出內容篩選器停止了 Claude 正在產生的回應。訊息文字來自 API：
該怎麼辦：
  • 重新措辭您的最後一則訊息，或採取不同的方法
  • 若要回到觸發封鎖的回合之前的檢查點，請按 Esc 兩次或執行 /rewind。請參閱檢查點功能

​
命令列錯誤

這些錯誤來自 claude 命令列及其子命令、您在輸入提示處提交的命令名稱，以及像 /security-review 這類會在其提示詞執行前先執行 shell 命令以收集脈絡的命令。它們也可能來自會重新啟動 CLI 的 /tui。

​
--bg 與 --print 衝突

此訊息需要 Claude Code v2.1.198 或更新版本。您在同一次 claude 呼叫中將 --bg 與 -p 或 --print 合併使用。--bg 會啟動一個背景工作階段，您之後可以使用 claude agents 附加到該工作階段；而 --print 則以非互動方式執行，永遠不會啟動 claude agents 所附加的互動式工作階段。在 v2.1.198 之前，此組合會默默建立一個永遠無法附加的背景工作。
處理方式：
  • 移除 -p 或 --print。--bg 會將提示詞作為其位置引數，因此 claude --bg "<task>" 就是完整的命令。請參閱從 shell 分派新的 agent。
  • 若要以非互動方式執行提示詞並列印結果，而不是建立背景工作階段，請移除 --bg 並執行 claude -p "<task>"

​
Couldn’t tell whether --bg is a flag or text

您執行 claude 時，將 --bg 或 --background 放在 Claude Code 無法判斷您是要將其作為背景旗標還是文字的位置。該命令沒有啟動任何東西，僅列印這一行，並以退出碼 1 結束：
如果您輸入的是 --background，該行會改為列出 --background。 處理方式：
  • 若要啟動背景工作階段，請在 shell 中將旗標放在最前面再次執行命令：claude --bg --name nightly-audit "<task>"

​
系統提示詞旗標與其檔案形式衝突

您在同一次 claude 呼叫中同時傳入了 --append-subagent-system-prompt 與 --append-subagent-system-prompt-file，因此 claude 會以退出碼 1 結束，而不會啟動工作階段：
在 v2.1.283 之前，當您將 --system-prompt 與 --system-prompt-file 一起傳入，或將 --append-system-prompt 與 --append-system-prompt-file 一起傳入時，claude 也會以相同方式結束，因為這些成對的旗標會相互衝突，而不是合併使用。在這些版本中，訊息會指出您合併使用的那一對旗標。 處理方式：
  • 保留旗標的其中一種形式，並移除另一種。若要將固定的提示詞檔案與每次執行的文字結合，請在啟動前將文字合併到檔案中，而不是同時傳入兩個旗標

​
無效的 --agents 設定

您傳給 --agents 的值無效，因此 claude 會以退出碼 1 結束，而不會啟動工作階段。當您傳入 --safe-mode 或設定 CLAUDE_CODE_SAFE_MODE 時，Claude Code 會完全忽略 --agents。搭配 --resume 或 --continue 時，內嵌的 JSON 值不會被檢查，工作階段會照常啟動；從檔案讀取的值則會在每次啟動時檢查。在 v2.1.242 之前，Claude Code 仍會照樣啟動工作階段。
第一行之後的內容取決於該值失敗的方式。Claude Code 會依序執行以下檢查，並在第一個失敗的檢查處停止。如果您的值有兩類問題，您要在修正第一類之後才會看到第二類：
  1. 當值以 { 開頭但無法解析為 JSON，或 --agents 檔案的內容無法解析時，Claude Code 會列印一行 invalid JSON:，其中包含 JSON 剖析器本身的訊息
  2. 當值可以解析，但某個 agent 定義不符合 CLI 定義的 subagent 的 schema 時，Claude Code 會針對每個問題列印一行
  3. 當 agent 名稱以 - 開頭時，Claude Code 會列印 <name>: agent names must not start with '-'
當問題行超過 20 行時，Claude Code 會列印前 20 行，並將其餘部分替換為 …and N more。 搭配 --print 時，--agents 也接受以JSON 檔案的路徑取代內嵌物件。在 v2.1.281 之前，--agents 只接受內嵌 JSON，並將檔案路徑視為無效的 JSON。檔案形式有其自己的拒絕訊息，會取代此訊息列印出來，包括以下幾種：
  • Error: --agents takes a JSON object, or a file path only with --print (-p)：Claude Code 在互動式工作階段中將該值讀取為檔案路徑。請以內嵌 JSON 傳入定義，或加上 -p 以從檔案讀取。
  • Error: --agents file not found: <path>：該路徑上沒有檔案。不以 { 開頭且不是有效 JSON 的值會被讀取為路徑，因此被 shell 弄亂的內嵌 JSON 也可能以此方式失敗。請檢查路徑或引號，然後再次執行命令。
處理方式：

​
無法從 --restricted 工作階段建立雲端工作階段

當您以 --restricted 啟動工作階段時，Claude Code 會拒絕從中建立雲端工作階段，因為新的工作階段會在受限程序之外執行，而且不會強制執行受限模式。Claude Code 會在用戶端、聯絡伺服器之前就拒絕，因此不會建立任何雲端工作階段：
處理方式：
  • 在受限工作階段中於本機執行該任務
  • 如果您能控制工作階段的啟動方式，請啟動一個不帶 --restricted 的新 claude 工作階段，並從那裡建立雲端工作階段
在 v2.1.248 之前，Claude Code 沒有 --restricted 旗標；較早的版本會以未知選項錯誤拒絕該旗標本身。

​
雲端工作階段已被您組織的政策停用

您組織的 allow_remote_sessions 政策已關閉，因此無法使用雲端工作階段以及使用它們的命令：
此訊息會在您從終端機建立雲端工作階段時出現，也會在您提交需要雲端工作階段的命令（例如 /teleport、/remote-env 或 /web-setup）時出現。在 v2.1.268 之前，提交這些命令之一會改為傳回 Unknown command。 如果訊息改為指出此工作階段正在使用的某個憑證，並以 Cloud sessions use your claude.ai login. 結尾，請參閱 Cloud sessions use your claude.ai login。如果 Claude Code 完全無法載入您組織的政策，您會看到另一則訊息。 處理方式：

​
Cloud sessions use your claude.ai login

當政策拒絕訊息指出此工作階段正在使用的某個憑證並以這句話結尾時，表示 Claude Code 檢查的是核發該憑證之組織的雲端工作階段政策。該組織可能與您的 claude.ai 登入所屬的組織不同：
最後一句話表示雲端工作階段是在您的 claude.ai 登入上執行，而不是在該憑證上執行。當您從 shell 啟動、恢復雲端工作階段或傳送訊息給雲端工作階段時（例如使用 --cloud 或 --teleport），就會出現此形式。在 v2.1.296 之前，Claude Code 在這種情況下也會輸出要求您聯絡組織管理員的形式。

​
Couldn’t verify your organization’s policy for cloud sessions

這些訊息表示 Claude Code 無法載入您組織的政策，而它會在建立、恢復雲端工作階段或傳送訊息給雲端工作階段之前檢查該政策。當政策請求尚未完成時，訊息為：
在工作階段中，需要雲端工作階段的命令（例如 /teleport 或 /web-setup）也會顯示此訊息。即使在您的 shell 會輸出 Cloud sessions aren't available: 形式的情況下也是如此，且其第二句為 Check your network connection, then restart Claude Code and try again. 一旦政策請求失敗，訊息就會說明失敗的原因。這適用於您使用 --cloud 或 --teleport 等旗標從 shell 啟動、恢復雲端工作階段或傳送訊息給雲端工作階段的情況。在無法連到 API 時，訊息為：
其他失敗會使用相同的開頭並附上各自的原因，例如代理伺服器以 HTTP 403 拒絕請求、伺服器錯誤，或 API 不接受的憑證。當 API 不接受此工作階段用來取代您 claude.ai 登入的憑證（例如 ANTHROPIC_API_KEY 環境變數）時，訊息也可能指出該憑證並要求您取消設定它：
在 v2.1.296 之前，這些失敗也會輸出 Couldn't verify 訊息。 處理方式：
  • 對於 Couldn't verify 訊息，請檢查網路連線後再試一次。若在工作階段中，請先重新啟動 Claude Code
  • 對於 Cloud sessions aren't available: 訊息，請依其原因採取對應措施，例如檢查代理伺服器或取消設定訊息指出的憑證，然後再次執行命令

​
由於資料夾取代了受追蹤的檔案，未暫存任何內容

此訊息表示您的檢出目錄中，現在有一個資料夾位於原本由 git 追蹤的檔案或連結所在的位置。當您將雲端工作階段拉取到終端機（例如使用 claude --teleport 或 /teleport）並選擇暫存（stash）選項之後，就會出現此訊息。暫存這種狀態可能會刪除資料夾內的檔案，因此 Claude Code 會拒絕暫存，並讓您的檢出目錄與索引保持不變：
處理方式：
  • 依照訊息所述，提交變更或將資料夾移到其他位置，然後再次執行 teleport

​
--json-schema 的值不是有效的 JSON Schema

您在非互動模式中傳給 --json-schema 的 schema 未能通過 JSON Schema 編譯，因此 claude 會以退出碼 1 結束，而不會執行提示詞。在 v2.1.205 之前，無效的 schema 會產生非結構化輸出且不報錯，而且任何使用 format 關鍵字的 schema 都會被視為無效。
第二個冒號之後的文字是驗證器的診斷訊息，會指出失敗的關鍵字或位置。使用 format 關鍵字的 schema（例如 "format": "email"）是有效的：Claude Code 將 format 視為註解接受，而不會強制執行它。 Claude Code 在 schema 編譯之前會執行兩項檢查：對於無法解析的 JSON 值，會以 Error: --json-schema is not valid JSON 拒絕；對於有效但不是物件的 JSON，會以 Error: --json-schema must be a JSON object 拒絕。 處理方式：
  • 修正診斷訊息指出的 schema 部分，然後重新執行命令
  • 請參閱取得結構化輸出，了解可運作的 schema 與命令

​
設定檔超過 2MiB 上限

您傳給 --settings 的檔案大於 2 MiB，因此 claude 會在啟動時以退出碼 1 結束，而不會載入它。在 v2.1.214 之前，Claude Code 讀取該檔案時不做大小檢查，數 GB 的檔案或像 /dev/zero 這樣的裝置檔案會使記憶體無限制地增長。
Claude Code 也會以相同方式拒絕不是一般檔案的 --settings 路徑：裝置、FIFO 或 socket 會回報 Error: Cannot use settings file (Not a regular file (device, FIFO, or socket))，後面接著路徑；而目錄則會回報 EISDIR 原因。 處理方式：
  • 將 --settings 指向小於 2 MiB 的一般 JSON 設定檔。格式請參閱設定。

​
目前的目錄已不存在

您從一個在 shell 進入後被刪除或移動的目錄啟動了 claude，例如被另一個 shell 移除的 worktree 或暫存目錄。Claude Code 無法讀取其工作目錄，因此在啟動工作階段之前就會以退出碼 1 結束，互動模式與非互動模式皆然。在 v2.1.239 之前，Claude Code 會當機，並在 stderr 上輸出壓縮過的 bundle 原始碼與原始的 ENOENT ... uv_cwd 堆疊，而不是此訊息。
兩種形式的原因與修正方式相同。 當 Claude Code 因其他原因（例如權限變更）無法讀取工作目錄時，訊息會改為指出錯誤代碼：Can't read the current directory (EACCES). Start Claude Code from a different directory. 在 macOS 上，若 ~/Desktop、~/Documents、~/Downloads 或 iCloud Drive 中的目錄出現 EPERM，通常表示 macOS 正在阻擋您的終端機應用程式存取該資料夾。讀取該資料夾的其他命令也會以相同方式失敗：在那裡執行 ls 會回報 Operation not permitted，即使使用 sudo 也一樣。 處理方式：
  • 切換到存在的目錄，例如您的家目錄或專案目錄，然後再次執行 claude
  • 如果該目錄已在相同路徑重新建立，您的 shell 仍持有已刪除的那一個。請執行 cd "$PWD"，或離開後重新進入該目錄，然後再次執行 claude
  • 對於 macOS 上的 EPERM，請以 Cmd+Q 結束您的終端機應用程式，再次開啟它，回到該資料夾，然後執行 claude。如果在該資料夾中執行 ls 仍然失敗，請開啟 系統設定 > 隱私權與安全性 > 檔案與檔案夾，為您的終端機應用程式開啟該資料夾，然後重新開啟終端機

​
暫存目錄被拒絕使用或無法建立

在 macOS 與 Linux 上，Claude Code 會在啟動時建立一個私人暫存目錄 claude-<uid>，位於系統暫存目錄或 CLAUDE_CODE_TMPDIR 覆寫值之下。當該目錄無法建立，或該路徑上已存在的項目未通過安全檢查時，Claude Code 會將失敗原因列印到 stderr，並以退出碼 1 結束，而不會啟動工作階段：
處理方式：
  • 對於 ENOSPC，請釋放存放暫存目錄之磁碟區的磁碟空間
  • 對於 Refusing to use it 形式，請移除所指名的項目本身（而不是連結所指向的目標），然後再次啟動 Claude Code；對於 owned by uid 形式，只有管理員或該使用者能夠移除它
  • 對於 is not readable，請對所指名的目錄執行 chmod 0700，或移除它後再次啟動
  • 在上述任何情況下，您都可以將 CLAUDE_CODE_TMPDIR 設為您能控制的目錄，然後再次啟動 Claude Code，而不去動被拒絕的路徑

​
目錄無法解析為實際位置

您對工作目錄的子目錄執行了 /add-dir，而 Claude Code 無法將該目錄解析為其實際位置。 您本來就擁有工作目錄之子目錄的檔案存取權，因此 /add-dir 只會載入其 skill、命令與 agent。在載入之前，Claude Code 會檢查該目錄的實際位置（解析所有符號連結後）是否位於工作目錄內。當 Claude Code 無法解析該位置時，它不會載入任何內容，並顯示此訊息：
處理方式：
  • 確認該路徑指向工作目錄內的一個實際目錄，然後再次執行 /add-dir
  • 此訊息不會變更您的檔案存取權；它只是回報該目錄的 .claude/ 內容未被載入
在 v2.1.261 之前，當工作目錄位於 /net/<host> 自動掛載點時，每次執行 /add-dir <subdirectory> 也都會出現此訊息，因為 Claude Code 在設計上不會解析該處的路徑；該目錄本身沒有問題，重試也無濟於事。

​
啟動 Remote Control 時工作區未受信任

您在尚未信任的目錄中，以 claude remote-control 或其別名 claude rc 啟動了 Remote Control 伺服器模式，而該命令無法詢問您是否信任該目錄。例如，該命令的標準輸入或標準輸出不是終端機，因為其中之一被重新導向或透過管線傳送。該命令會以退出碼 1 結束：
另有兩種同樣以 Error: Workspace not trusted. 開頭的變體，會出現在太小而無法顯示信任該目錄會啟用哪些功能的終端機中，或未回報其大小的終端機中。請放大視窗或切換到一般終端機視窗，然後再次執行 claude rc。 在您的家目錄中，訊息會有所不同，因為工作區信任對話框永遠不會儲存對家目錄的信任，所以在那裡接受信任無法滿足此檢查。在 v2.1.214 之前，家目錄會顯示上述訊息，但其建議在那裡無法奏效。
如果您在 Trust <directory>? 問題回答 n 或按下 Enter，該命令會列印一則指出該目錄的 Remote Control did not start 訊息，並以退出碼 1 結束。請再次執行 claude rc 並回答 y。 處理方式：
  • 先從終端機信任該目錄：在該處執行 claude rc 並回答 y，或在該處執行 claude 並接受工作區信任對話框，然後再次執行您原本的命令
  • 在您的家目錄中，請切換到專案目錄，並在那裡啟動 Remote Control
在 v2.1.284 之前，即使在終端機中，該命令也從不詢問。

​
不會傳遞到 Remote Control 所啟動的工作階段

您在 remote-control 動詞之前加上了全域 claude 旗標來啟動 Remote Control，而該旗標會限制或設定 Remote Control 所啟動的工作階段，例如 --settings、--setting-sources、--permission-mode、--disallowed-tools 或 --mcp-config。放在動詞之前的旗標永遠不會傳到這些工作階段。Claude Code 會改為拒絕啟動，並指出該旗標：
對於捨棄後無害的全域旗標，例如 --verbose、--model，或由包裝程式注入的 --session-id 或 --plugin-dir，Claude Code 不會拒絕：它會忽略這些旗標，Remote Control 會照常啟動。 對於尚未被認定為無害的全域旗標，Claude Code 也會拒絕啟動，因此在較新版本中新增的旗標可能會出現在此訊息中，直到之後的版本將其標記為無害為止。 處理方式：
  • 將該旗標從動詞之前移除，並在動詞之後傳入 Remote Control 自身的選項；claude remote-control --help 會列出這些選項
  • 當被拒絕的旗標是 --permission-mode 時，請執行 claude remote-control --permission-mode <mode>，為 Remote Control 所啟動的工作階段設定權限模式
在 v2.1.248 之前，當全域旗標在前時，claude remote-control 不接受其自身的旗標，該命令會以 unknown option 錯誤失敗。

​
--sandbox or --no-sandbox is not supported by claude remote-control

此錯誤表示啟動您 Remote Control 伺服器的命令在 remote-control 之後傳入了 --sandbox 或 --no-sandbox，而 claude remote-control 兩者皆不接受。伺服器會以退出碼 1 結束，而不會啟動：
處理方式：
  • 從命令中移除該旗標（包括在替您啟動伺服器的指令碼或服務定義中），然後再次執行
  • 若要對伺服器所啟動的工作階段使用沙箱，請在設定檔中將 sandbox.enabled 設為 true，以開啟沙箱機制
這兩個旗標已在 v2.1.300 中從 claude remote-control 移除，因此為較早版本撰寫的命令可能仍帶有其中之一。

​
此建置中尚無法使用 claude import

您執行了 claude import，而 Claude Code 發現匯入流程已關閉，因此該命令會以退出碼 1 結束，而不會開始匯入。在 v2.1.222 之前，匯入流程關閉的建置會將 import 視為提示詞，並啟動互動式工作階段，而不是列印此訊息。
Claude Code 透過從 Anthropic 擷取並快取在磁碟上的功能旗標來開啟 claude import。此訊息表示快取的值為關閉。原因通常是以下其中之一：
  • 您在安裝後尚未啟動過工作階段，因此 Claude Code 尚未擷取該旗標。即使您可以使用此功能，第一次執行 claude import 時也可能列印此訊息。
  • 您透過 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 使用 Claude Code，或透過 Claude apps 閘道使用。Claude Code 在這些工作階段中不會擷取功能旗標，因此 claude import 會一直無法使用。
  • 您設定了 DISABLE_TELEMETRY、DO_NOT_TRACK、DISABLE_GROWTHBOOK 或 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC，這些會關閉功能旗標的擷取，因此 claude import 會一直無法使用。
處理方式：
  • 在全新安裝中，啟動 claude，等待工作階段載入後結束，然後再次執行 claude import
  • 在功能旗標擷取持續關閉的環境中，請自行完成設定：使用 claude mcp add 新增 MCP 伺服器，並建立您想沿用的 CLAUDE.md 檔案、skill 與命令，以及 subagent。訊息中也提到了 ~/.claude/settings.json。在 claude import 所沿用的設定中，該檔案只保存權限模式；Claude Code 不會從中讀取 MCP 伺服器。

​
無法讀取 Claude Code 設定

您在 Claude Code 無法解析 ~/.claude.json（用於儲存您的登入資訊與各專案狀態的檔案）時執行了 claude import。該子命令會讀取此檔案以檢查可用性，但不會顯示互動式工作階段所顯示的復原對話框，因此會以退出碼 1 結束。在 v2.1.222 之前，設定檔無法讀取時執行 claude import 會啟動互動式工作階段，並由其復原對話框處理該檔案。
處理方式：
  • 不帶引數執行 claude。Claude Code 會偵測到無效的檔案並提供重設選項。然後再次執行 claude import。
  • 若要保留您手動做過的編輯，請改為在編輯器中修正 ~/.claude.json 的 JSON 語法，然後重新執行 claude import

​
無法從 Claude Desktop 匯入伺服器

Claude Code 無法新增您在 claude mcp add-from-claude-desktop 中選取的其中一個伺服器。該命令仍會匯入其他選取的伺服器，並針對每個無法新增的伺服器列印一行。在 v2.1.205 之前，第一個失敗的伺服器會中止匯入。
伺服器名稱之後的文字是原因。最常見的是名稱檢查：Claude Desktop 允許伺服器名稱中包含空格與句點等字元，而 claude mcp 將其限制為字母、數字、連字號與底線。其他原因包括伺服器設定未通過驗證，以及伺服器被您組織的 MCP 政策封鎖。 處理方式：
  • 在 claude_desktop_config.json 中將該伺服器重新命名為只使用字母、數字、連字號與底線，然後再次執行 claude mcp add-from-claude-desktop
  • 使用 claude mcp add 或 claude mcp add-json 以有效的名稱直接新增該伺服器。請參閱從 Claude Desktop 匯入 MCP 伺服器。

​
無法將 MCP 伺服器新增到受管範圍

您以 --scope managed 執行了 claude mcp add 或 claude mcp add-json。該範圍保存的是您的組織透過 managedMcpServers 受管設定提供的伺服器。Claude Code 只從受管設定讀取它們，因此該命令無法將伺服器寫入該範圍。
處理方式：
  • 將伺服器新增到您可寫入的範圍：local、user 或 project。若不指定 --scope，該命令會使用 local。請參閱 MCP 安裝範圍
  • 若要將伺服器提供給組織中的每位使用者，請將其新增到您部署的受管設定中的 managedMcpServers

​
受管設定只允許外掛伺服器時無法新增 MCP 伺服器

您在組織的受管設定將 strictPluginOnlyCustomization 設為 true 或設為包含 mcp 的清單時，執行了 claude mcp add 或 claude mcp add-json。在該設定下，Claude Code 不會從 ~/.claude.json 或 .mcp.json 載入 MCP 伺服器，因此該命令會以退出碼 1 結束，而不是儲存一個永遠不會載入的伺服器：
claude mcp add-from-claude-desktop 會將您選取的每個伺服器回報為未匯入，並以此訊息作為原因。/import 會針對它嘗試新增的每個 MCP 伺服器回報此訊息，但仍會匯入它找到的其他項目。 在 v2.1.284 之前，這些命令會儲存伺服器並回報成功，但該伺服器永遠不會載入。 處理方式：
  • 安裝提供該伺服器的外掛
  • 請您的管理員在外掛中發布該伺服器，或者若它是遠端 HTTP 或 SSE 伺服器，則透過 managedMcpServers 提供

​
無法讀取 .mcp.json

讀取專案 .mcp.json 的命令（例如搭配 --scope project 的 claude mcp add 或 claude mcp add-json，或 claude mcp remove）發現目前目錄中的該檔案不是一般檔案，或大於 2 MiB，因此會以此錯誤結束，而不會讀取該檔案。
在 v2.1.257 之前，位於 .mcp.json 的 FIFO 會讓命令無限期等待且沒有任何輸出，而指向 /dev/zero 等裝置檔案的符號連結則會讓記憶體持續增長，直到程序被終止。 處理方式：
  • 檢查目前目錄中 .mcp.json 是什麼。將其替換為專案範圍格式的一般 JSON 檔案，或將其刪除，然後再次執行命令。

​
MCP 伺服器未被儲存或移除

您針對 user 或 local 範圍中的伺服器執行了 claude mcp add、claude mcp add-json 或 claude mcp remove。這兩個範圍都儲存在 ~/.claude.json 中，而 Claude Code 在寫入後讀回該檔案時，變更並不在其中。該命令會以此錯誤結束，而不是顯示其成功訊息。
移除之後，訊息會顯示為 was not removed from，並以 then remove the server again 結尾。對於 local 範圍的伺服器，路徑後面會接著該項目所屬的專案目錄，格式為 (local scope for /path/to/project)。 在 v2.1.283 之前，即使變更沒有寫入檔案，claude mcp add、claude mcp add-json 與 claude mcp remove 也會回報成功。 處理方式：
  • 讓訊息所指名的檔案變為可寫入，或在沙箱之外執行命令，然後再次執行相同的新增或移除命令。

​
MCP 伺服器可能未被儲存或移除

您針對 user 或 local 範圍中的伺服器執行了 claude mcp add、claude mcp add-json 或 claude mcp remove，而 Claude Code 無法讀回 ~/.claude.json 來確認變更。變更可能已寫入磁碟，也可能沒有。括號中的文字是該次讀取的錯誤。
移除之後，訊息會顯示為 may not have been removed，並以 then remove the server again if it is still listed 結尾。 在 v2.1.283 之前，即使無法確認變更，這些命令也會回報成功。 處理方式：
  • 執行 claude mcp get <name> 以檢查變更是否已寫入磁碟。對於 local 範圍的伺服器，請從該伺服器所屬的專案目錄執行，因為 local 範圍是以專案為單位。
  • 如果在新增後伺服器不存在，或在移除後仍被列出，請再次執行相同的新增或移除命令。

​
伺服器由 Anthropic 託管，不支援本機 OAuth

您為某個 MCP 伺服器啟動了登入，而其 URL 指向透過第三方身分識別提供者進行身分驗證、由 Anthropic 託管的連接器主機。這些主機包括 microsoft365.mcp.claude.com、gmail.mcp.claude.com 與 gcal.mcp.claude.com。Claude Code 會拒絕從 /mcp 面板與 claude mcp login 為這些主機啟動本機 OAuth 流程，因為它們的登入只能透過 claude.ai 進行。
處理方式：

​
伺服器拒絕了設定的 headersHelper 所產生的 Authorization 標頭

某個由 headersHelper 提供 Authorization 標頭的 MCP 伺服器以 HTTP 401 或 403 回應連線，因此 Claude Code 將該連線回報為失敗。由於 helper 提供了 Authorization 標頭，Claude Code 不會改用 OAuth 連線該伺服器：
Claude Code 在每次嘗試連線時都會重新執行 helper，因此在暫時性拒絕（例如權杖輪替競爭）之後重試，可能會以新的憑證成功。 處理方式： 在 v2.1.248 之前，對於 helper 提供 Authorization 標頭的伺服器，Claude Code 仍會執行 OAuth 探索。該探索可能會以 Incompatible auth server: does not support dynamic client registration 失敗，而不是回報被拒絕的憑證。

​
找不到 MCP 權限提示工具

您傳給 --permission-prompt-tool 的工具在執行首次需要權限決定時，不在已連線的 MCP 工具之中，原因可能是其伺服器從未連線，或沒有任何已連線的伺服器提供該名稱的工具。Claude Code 仍會傳送您的提示詞：非互動執行會在第一次工具呼叫時以此錯誤與退出碼 1 結束，因此即使已發出請求，也不會產生任何回答。在第一次提示之前，Claude Code 會等待該伺服器連線，最長等待由 MCP_TIMEOUT 設定的每個伺服器 30 秒連線逾時。在 v2.1.206 之前，啟動時不會等待伺服器完成連線，因此啟動緩慢但正常的伺服器也會產生此錯誤。
Available MCP tools: 之後的清單列出已連線的 MCP 工具。 處理方式：
  • 確認伺服器能啟動並保持連線：在相同目錄中執行 claude mcp list，並確認該伺服器被列為已連線
  • 確認工具名稱與伺服器所提供的 mcp__<server>__<tool> 名稱相符
  • 如果伺服器需要超過 30 秒才能啟動，請調高 MCP_TIMEOUT

​
OAuth 回呼連接埠已被使用

當您以 OAuth 登入遠端 MCP 伺服器時，Claude Code 會啟動本機監聽器來接收登入回呼。如果該監聽器所需的連接埠被其他程序佔用，登入就會以此訊息失敗。這大多發生在透過 MCP_OAUTH_CALLBACK_PORT 變數或 --callback-port 設定了固定回呼連接埠時，因為若未設定，Claude Code 會挑選一個可用的連接埠。
在 Windows 上，建議的命令改為 netstat -ano | findstr :<port>。 處理方式：
  • 執行訊息中的命令以找出佔用該連接埠的程序，然後停止它或等待它結束
  • 如果另一個程式需要永久使用該連接埠，請向伺服器註冊不同的重新導向 URI，並以 MCP_OAUTH_CALLBACK_PORT 或 --callback-port（視您使用哪一個而定）設定其連接埠
  • 然後再次開始登入，例如在 /mcp 中選取該伺服器

​
沒有可用於 OAuth 重新導向的連接埠

當您以 OAuth 登入遠端 MCP 伺服器時，Claude Code 會啟動本機監聽器來接收登入回呼。當 Claude Code 無法為其繫結本機連接埠時，登入就會以此訊息失敗。機器上有某些東西阻止它在 127.0.0.1 上監聽，例如安全性軟體或拒絕本機監聽器的沙箱政策。
在 v2.1.268 之前，Claude Code 不會改用作業系統指派的連接埠，因此當只有它自行挑選的連接埠無法繫結時，也會出現此訊息。這可能發生在 Hyper-V 保留的連接埠範圍涵蓋 Claude Code 挑選範圍的 Windows 主機上。 處理方式：
  • 檢查是否有安全性軟體或沙箱政策阻止程序在 127.0.0.1 上監聽，並允許 Claude Code 繫結本機連接埠
  • 然後再次開始登入，例如在 /mcp 中選取該伺服器

​
沒有 origin/HEAD 時 /security-review 失敗

/security-review 會將您的分支與 origin/HEAD 進行比對以建立審查脈絡，origin/HEAD 是記錄 origin 遠端上哪個分支為預設分支的本機參照。當該參照不存在時，收集差異的 git 命令會失敗，審查會在開始前就停止。
訊息可能會改為引用 git log 或其他 git diff。只有當遠端公告了預設分支，且您的 fetch refspec 涵蓋它時，Git 才會建立 origin/HEAD；對含有提交的遠端執行完整的 git clone 就會如此。在以下設定中，該參照會不存在：
  • 單一分支或 CI 的 checkout，其擷取的 refspec 範圍過窄
  • 伺服器端 HEAD 指向無人推送過之分支的遠端
  • 沒有 origin 遠端的儲存庫，或您從未擷取過的遠端
對於任何注入動態上下文的 skill，Claude Code 都會顯示相同的錯誤，而注入的命令失敗會中止該 skill 的呼叫。 以下同類字串會在命令執行之前就觸發：
  • Shell command permission check failed for pattern "..."：該命令的權限檢查不允許執行。注入命令的權限檢查說明了在各權限模式下哪些結果會中止，以及如何使用 allowed-tools 預先核准命令
  • Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found：skill 的 frontmatter 要求 bash，但機器上沒有。請安裝 Git for Windows，或將 frontmatter 改為 shell: powershell。請參閱注入命令如何執行
  • No shell command in <name> was run：檔案中的某個 ! 命令包含 tab 或換行以外的原始控制字元，因此所有命令都不會執行。請參閱如何找出並移除該字元
處理方式：
  • 指定遠端的預設分支來建立該參照：git remote set-head origin <default-branch>。只要本機追蹤參照 origin/<default-branch> 存在，這就能運作。如果它不存在（例如在單一分支複製中），請先擷取該分支：執行 git remote set-branches --add origin <branch>，接著執行 git fetch origin，然後重新執行 set-head 命令。再重新執行 /security-review。
  • 如果您不想指定分支名稱，請執行 git fetch origin，然後執行 git remote set-head origin --auto，它會詢問遠端哪個分支是預設分支。當遠端沒有公告預設分支（因為它是空的，或其 HEAD 指向無人推送的分支）時，它會以 error: Cannot determine remote HEAD 失敗；此時請明確指定分支。當您的複製不擷取該分支時，它會以 error: Not a valid ref 失敗；請先如上所述擴大 refspec。
  • 如果儲存庫沒有遠端，請使用 git remote add origin <url> 新增一個，並在建立參照前先擷取。如果遠端是空的，請先使用 git push -u origin HEAD 推送您的分支，並在 set-head 命令中指定該分支；之後 origin/HEAD 會指向您剛推送的分支，因此在您的分支與其分歧之前，/security-review 看到的差異都會是空的。

​
No shell command in a skill or command was run

skill 或自訂命令檔案中的某個 !`<command>` 動態上下文命令包含 tab 或換行以外的原始控制字元。Claude Code 會在該檔案的任何命令執行之前拒絕整個呼叫。 訊息會列出原本要執行這些命令的 shell 工具（Bash 或 PowerShell），並以遭拒絕的命令結尾。每個此類字元都會以 � 取代，方便您看出其位置：
處理方式：
  • 在訊息結尾所引用的命令中找出每個 �。從 skill 或命令檔案中，或從代入該檔案的引數或選項中，移除它所代表的字元。

​
使用 --print 時必須提供輸入

單獨執行 claude 需要 stdout 是終端機，才能啟動互動式 UI。當 stdout 被重新導向，或主控台不是真正的終端機（例如 PowerShell ISE 與某些 IDE 輸出窗格）時，claude 會改以非互動方式執行。這與 claude -p 是相同的模式，而該模式需要提示詞，因此即使您沒有傳入該旗標，訊息也會提到 --print。在任何地方傳入 -p/--print 卻沒有提示詞、stdin 也沒有透過管線傳入任何內容，都會產生相同的錯誤。
處理方式：
  • 若要互動使用，請在真正的終端機中執行 claude：使用 Windows Terminal 或 PowerShell 主控台而非 ISE，並使用 IDE 的整合式終端機而非輸出窗格
  • 若要單次使用，請傳入提示詞：claude -p "your question"，或以 echo "your question" | claude -p 透過管線傳入

​
Claude Code 無法在此讀取鍵盤

您在不帶 -p 的情況下執行了 claude，這會啟動互動式工作階段，但其標準輸入不是終端機。有東西透過管線傳送或重新導向了它，或是啟動 claude 的程式提供了它自己的輸入串流。 互動式工作階段需要從終端機讀取您的按鍵，而沒有終端機時 Claude Code 的行為取決於您的平台：
  • Windows：Claude Code 會將訊息列印到 stderr 並以退出碼 1 結束，而不會啟動介面
  • macOS 與 Linux：Claude Code 會從 /dev/tty 讀取您的按鍵並啟動工作階段，並以任何透過管線傳入的文字作為您的第一個提示詞。當 /dev/tty 無法開啟時，您會看到此訊息，其第一行會以 /dev/tty 取代 Windows 的措辭。
在 Windows 上，訊息內容如下：
處理方式：
  • 若要互動工作，請直接在終端機中執行 claude，不要透過管線傳送或重新導向其輸入
  • 若要在沒有互動式介面的情況下取得回覆（例如從指令碼），請加上 -p，並以引數或透過 stdin 提供提示詞，例如 claude -p "your question" 或 echo "your question" | claude -p。這也適用於 --continue 與 --resume <session-id>。
在 v2.1.287 之前，Claude Code 會啟動介面而不是列印此訊息，然後要嘛畫面上什麼都不顯示，要嘛以包含 Raw mode is not supported 的錯誤失敗。 如果您是在執行 claude install 時看到 Raw mode is not supported，請參閱安裝期間出現 Raw mode is not supported。

​
輸入只包含空白字元

在非互動模式中，Claude Code 會拒絕完全由空格、定位字元或換行組成的提示詞，而不會傳送它，因為 API 會拒絕沒有可見文字的訊息。您看到哪則訊息取決於空白提示詞的來源：
  • claude -p 的提示詞引數或透過管線傳入的 stdin：claude 會以 Error: Input contained only whitespace. Provide a prompt with text through stdin or as a prompt argument when using --print 結束
  • 提交到執行中的 --input-format stream-json 或 Agent SDK 工作階段的訊息：Claude Code 會在不呼叫模型的情況下結束該回合，工作階段仍可繼續使用。拒絕會以資訊訊息以及該回合的結果文字送達：Blank prompt — the message was only whitespace, so nothing was sent to the model.
在 v2.1.229 之前，Claude Code 會將只含空白的訊息傳送給 API，而 API 會以 400 錯誤拒絕該請求。 處理方式：
  • 在提示詞中加入可見的文字。如果指令碼是從變數或檔案建立提示詞，請在呼叫 Claude Code 之前確認來源不是空的。

​
stream-json 輸入超過 256M 個字元且沒有換行

您的程式在 stdin 上向 claude -p --input-format stream-json 執行傳送了超過 268,435,456 個字元且沒有換行，因此 Claude Code 會將此錯誤列印到 stderr 並以退出碼 1 結束，而不會繼續緩衝更多輸入。訊息中將此上限表示為 256M。在 v2.1.257 之前，Claude Code 會無限制地緩衝此類輸入，使記憶體持續增長，直到程序當機或被終止。
這麼長卻沒有換行的輸入，通常表示產生者根本不是 stream-json 產生者，例如意外透過管線傳入的二進位檔案或純文字日誌輸出。單一訊息超過此上限也會未通過相同的檢查。 處理方式：
  • 檢查透過管線傳入 stdin 的內容。使用 --input-format stream-json 時，每則訊息都必須是以換行結尾的一行 JSON
  • 若要改為傳送純文字，請移除 --input-format stream-json；claude -p 預設會從 stdin 讀取純文字提示詞

​
未知的命令

在互動式終端機工作階段中，您提交了一個與此工作階段中任何命令都不相符的 / 名稱，因此 Claude Code 會回報該名稱，而不會執行任何動作：
Claude Code 會建議選單在此工作階段中列出的最接近的命令名稱或別名。當沒有相近的名稱時，訊息會在名稱之後結束。原因通常是以下其中之一： 只有在互動式終端機工作階段中，Claude Code 才會以這種方式回應不相符的 / 名稱。在其他所有工作階段中，它會改將提示詞作為一般訊息傳送給 Claude，並附上一則說明該命令未執行的備註，以及 Claude 在該工作階段中可執行的命令清單。這些工作階段包括： 對於無法在上述工作階段之一中執行的內建命令，Claude Code 仍會回應該命令無法使用，而不會將其傳送給 Claude。在 v2.1.274 之前，只有雲端工作階段與 routine 會將不相符的名稱傳送給 Claude。在 v2.1.273 之前，它們也會回應 Unknown command。 Claude Code 不會將每個以 / 開頭的提示詞都視為命令。當 / 之後的第一個字以標點符號開頭（例如開啟 Lean 文件註解的 /--），或是像 /var/log/syslog 這樣的路徑時，它會將提示詞作為一般訊息傳送給 Claude。 在 v2.1.236 之前，如果您在命令選單列出與您輸入的名稱相近的符合項目時按下 Enter，Claude Code 會執行該符合項目，因此像 /hepl 這樣的打字錯誤會執行 /help，而不是產生此訊息。 處理方式：
  • 執行建議的名稱，或輸入 / 加上名稱的一部分，以查看此工作階段中可用的命令
  • 如果 Claude Code 將文件中記載的命令回報為未知，請查看命令參考中該命令的列，了解它所指出的需求

​
差異對 ultrareview 而言過大

您的分支與基底分支之間的差異（包括未提交與已暫存的變更）超過了 ultrareview 的大小上限，因此 /code-review ultra 與 claude ultrareview 子命令會在雲端工作階段啟動前拒絕該審查。被拒絕的審查不會使用免費執行次數，也不會收取用量點數。訊息會指出生效的上限、您的差異大小，以及貢獻最多變更行數的檔案。在 v2.1.216 之前，訊息只顯示原始的差異統計資料。
審查 pull request 時也適用相同的上限；該形式的訊息以 PR #<N> is too large for ultrareview 開頭，並指出該 PR 的檔案數與行數。 處理方式：
  • 傳入更接近您工作的基底分支，例如 /code-review ultra develop，讓審查只涵蓋與該分支之間的差異
  • 將變更拆分為較小的分支並逐一審查。訊息所指名的檔案貢獻了最多的變更行數，因此請先將它們移到各自的分支。

​
找不到與基底分支的 merge-base

/code-review ultra 與 claude ultrareview 子命令會審查您的分支與基底分支之間的差異，這需要兩者共同擁有的提交。當 git merge-base 找不到任何共同提交時，Claude Code 會在雲端工作階段啟動前拒絕該審查。在 Claude Code 能驗證為完整、且至少有一個分支的複製上，它會改為審查每個被追蹤的檔案，而不是拒絕。當完全找不到基底分支、Claude Code 無法驗證您的複製是否完整，或在無法進行整棵樹差異比對的少數儲存庫中（例如 SHA-256 物件格式），您會看到此拒絕訊息。
第一句之後的提示取決於 Claude Code 觀察到的情況：
  • 您沒有傳入基底分支：Claude Code 與儲存庫的預設分支進行比較，並建議您明確傳入基底分支，如上例所示
  • 您傳入的基底分支已存在於您的複製中：提示內容為 Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)
  • 您傳入的基底分支不在您的 clone 中：Claude Code 在比較前從 origin 擷取了它。提示為 <branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)；當 Claude Code 無法判斷您的 clone 是否為淺層時，會改為建議 git fetch --unshallow origin。在 v2.1.221 之前，提示會為每個擷取的基底分支建議 git fetch --unshallow origin，而在完整的 clone 上，該命令會以 fatal: --unshallow on a complete repository does not make sense 失敗。
處理方式：
  • 如果另一個分支才是您真正的基底，請明確傳入它：/code-review ultra <branch>
  • 如果您的複製可能沒有完整歷史，請執行 git fetch --unshallow origin 並重新執行審查

​
您的 checkout 沒有任何分支

checkout 可能有提交卻沒有分支：如果您執行 git init，接著執行 git fetch <url> 與 git checkout FETCH_HEAD，就會得到一個沒有任何參照的分離 HEAD。Claude Code 會將您的儲存庫打包為 git bundle 以上傳進行 ultrareview，而它無法打包沒有分支或其他參照的儲存庫，因此 /code-review ultra 與 claude ultrareview 子命令會在雲端工作階段啟動前拒絕該審查。
在 v2.1.221 之前，Claude Code 會嘗試審查此 checkout 中每個被追蹤的檔案，而上傳會失敗。 處理方式：
  • 使用 git checkout -b <name> 在目前的提交上建立分支，然後重新執行審查

​
沒有 GitHub 帳戶連結到您的 Claude 帳戶

您執行了 /code-review ultra <PR#> 或 claude ultrareview <PR#>，而在建立雲端工作階段之前，Claude Code 會詢問伺服器連結到您 Claude 帳戶的 GitHub 帳戶是否能存取該 PR 的儲存庫。由於沒有連結任何帳戶，或連結已過期，雲端複製將會失敗，因此 Claude Code 會拒絕啟動。對於被拒絕的啟動，Claude Code 不會耗用免費執行次數，也不會收取用量點數。
當 /web-setup 在您的工作階段中無法使用時，訊息只會提到 claude.ai 連結。 處理方式：
  • 執行 /web-setup 將您的 GitHub CLI 登入連結到您的 Claude 帳戶，或在 claude.ai/connect-github 連結帳戶
  • 連結後約一分鐘再重新執行審查
在 v2.1.248 之前，Claude Code 不會在啟動前檢查此項目。

​
您連結的 GitHub 帳戶無法看到該儲存庫

您執行了 /code-review ultra <PR#> 或 claude ultrareview <PR#>，而連結到您 Claude 帳戶的 GitHub 帳戶無法讀取該 PR 的儲存庫，因此雲端複製將會失敗，Claude Code 會拒絕啟動。對於被拒絕的啟動，Claude Code 不會耗用免費執行次數，也不會收取用量點數。
當 /web-setup 在您的工作階段中無法使用時，訊息只會提到安裝應用程式。 處理方式：
  • 如果您本機的 gh CLI 能夠讀取該儲存庫，請執行 /web-setup 將該登入連結到您的 Claude 帳戶
  • 完成變更後重新執行審查
在 v2.1.248 之前，Claude Code 不會在啟動前檢查此項目。

​
GitHub App 預檢暫時性失敗

您從本機儲存庫啟動了雲端工作階段，而有兩個步驟同時失敗。Claude Code 無法建置或上傳您儲存庫的 bundle。在上傳之前，它檢查了雲端服務是否能從 GitHub 複製該儲存庫，而該檢查並未得到明確的答案，而是以重試可能排除的錯誤結束，例如網路錯誤、逾時或暫時性的伺服器錯誤。完整訊息會以阻止 bundle 的原因開頭，例如 Could not upload repo bundle (<error>)，並以預檢的句子結尾：
處理方式：
  • 稍後重新執行命令。當 GitHub 檢查通過時，Claude Code 可以從 GitHub 複製啟動工作階段，因此失敗的上傳不再阻擋啟動
  • 如果重試持續失敗，訊息開頭會指出阻止上傳的原因。當該原因是您可以修正的問題時，請加以修正，讓工作階段能改從您的本機儲存庫啟動
在 v2.1.251 之前，即使 GitHub 檢查只是暫時性失敗，Claude Code 也會以 Please set up GitHub on https://claude.ai/code 結束訊息，而設定建議無法排除暫時性失敗。

​
儲存庫上傳無法遵循某項 git 設定

您啟動了上傳本機儲存庫的雲端工作階段，或對某個分支進行 ultrareview，而上傳無法遵循決定哪些屬性規則適用於您檔案的某項 git 設定。如果上傳照常進行並漏掉某條規則，那麼 git 在儲存前會轉換的檔案（例如由 clean 過濾器加密的檔案）可能會以磁碟上的原樣傳到雲端。Claude Code 會改為拒絕上傳，不會上傳任何內容：
訊息會指出該設定及其設定位置，並以針對您所遇情況的修正方式結尾。core.attributesFile 與 attr.tree 也會出現相同的拒絕訊息，各自附有其修正方式。 訊息可能會指出您的 git 設定透過 include 或 includeIf 指示引入的設定檔，即使該指示的條件並不適用於此儲存庫。 處理方式：
  • 套用訊息最後一句中的修正方式

​
GitHub 未連結到您的 Claude 帳戶

您從本機儲存庫啟動了雲端工作階段，例如使用 /autofix-pr。沒有 GitHub 帳戶連結到您的 Claude 帳戶，或連結已過期，因此 Claude Code 會拒絕啟動：
當您使用 /schedule 建立 routine 時，相同的訊息會以指出該儲存庫的設定備註形式出現；該備註不會阻擋建立 routine。 處理方式： 在 v2.1.268 之前，Claude Code 會將此情況回報為 Claude GitHub App 檢查的暫時性失敗，並建議重試或安裝該應用程式；但這兩者都無法連結 GitHub 帳戶。

​
GitHub 組織政策正在封鎖 Claude

您在 Claude Code 提示字元執行了會啟動雲端工作階段的命令，例如 /autofix-pr。在建立工作階段之前，Claude Code 會在 GitHub 上檢查 Claude 對儲存庫的存取權，而 GitHub 拒絕了，因為您的 GitHub 組織有一項封鎖 Claude 的政策。Claude Code 會在此停止，並顯示一則指出該政策的訊息。 當封鎖存取的是 IP 允許清單時，訊息內容為：
當封鎖存取的是單一登入時，訊息內容為：
當封鎖存取的是 Microsoft Entra ID 條件式存取政策時，訊息內容為：
處理方式：
  • IP 允許清單：請 GitHub 組織或企業的擁有者允許 Anthropic 的對外 IP 位址。請參閱 GitHub 允許清單與防火牆，了解相關位址以及需要變更的 GitHub 設定。
  • 單一登入：在 claude.ai/customize/connectors 中中斷 GitHub 的連接，然後再次連接。當 GitHub 詢問時，按一下組織旁的 Authorize，讓新連線獲得該組織單一登入的授權。
  • 條件式存取政策：請您的 GitHub Enterprise 或 Microsoft Entra ID 管理員在該政策中允許 Claude
  • 完成變更後，再次執行該命令

​
需要單一登入授權

您執行了 /install-github-app，並選擇了一個其組織強制使用 SAML 單一登入的儲存庫。在設定之前，Claude Code 會使用 GitHub CLI 檢查您對該儲存庫的存取權，而 GitHub 拒絕了該檢查，因為您的 gh token 尚未獲得該組織的授權。精靈會顯示警告以及授權步驟：
處理方式：
  • 執行 gh auth refresh -h github.com -s repo,workflow，以 repo 和 workflow 範圍重新授權您的 GitHub CLI 登入，並在 GitHub 提示單一登入時授權該組織
  • 如果您使用 GH_TOKEN 中的個人存取 token 進行驗證，請開啟 github.com/settings/tokens，在該 token 上選擇 Configure SSO，並授權該組織
  • 再次執行 /install-github-app
在 v2.1.273 之前，Claude Code 在此情況下會改為顯示 Admin permissions required 警告。

​
無法繼續對話

Claude Code 無法讀取或處理您從 claude --resume 選擇器中選取之工作階段的已儲存逐字稿，因此它會結束程序，而不是在部分載入的狀態下繼續。訊息中包含重試用的命令：
Claude Code 在顯示訊息後會以代碼 1 結束。在執行中的工作階段內使用 /resume 選擇器時，則會在對話中回報 Failed to resume conversation，而您目前的工作階段會繼續執行。在 v2.1.216 之前，從 claude --resume 選擇器繼續失敗時，會無限期停留在 Resuming conversation… 載入動畫上，而不會顯示此訊息。 處理方式：
  • 使用訊息中的工作階段 ID 執行 claude --resume <session-id> 以重試
  • 在 v2.1.285 之前的版本上，如果重試以相同方式失敗，請執行 claude update 後再次繼續。當已儲存的逐字稿包含這些版本無法讀取的項目時，這些版本會讓繼續操作失敗。
  • 如果重試再次失敗，請執行 claude 以開始新的工作階段

​
找不到具有該工作階段 ID 的對話

您將工作階段 ID 傳給 claude --resume <session-id>，但沒有任何已儲存的逐字稿與之相符：
Claude Code 顯示訊息後會以代碼 1 結束。Claude Code 會先搜尋目前的專案，再搜尋這台機器上的所有其他專案來尋找該 ID。在 v2.1.223 之前，查找只會涵蓋目前的專案目錄及其 git worktree，因此請從該工作階段最後工作的目錄進行恢復。 常見原因：
  • ID 輸入錯誤：對於非互動式執行，ID 是 --output-format json 輸出中的 session_id 欄位
  • 逐字稿已刪除：Claude Code 會依照保留清理規則，在保留期限（預設為 30 天）後移除逐字稿
  • 不同的機器：Claude Code 將逐字稿儲存在本機，因此請在執行該工作階段的機器上繼續
  • 重複的副本：如果您複製了 ~/.claude/projects 下的專案目錄，導致兩份逐字稿帶有相同的 ID，Claude Code 會回報此訊息，而不會任意繼續其中一份副本
處理方式：
  • 對於互動式工作階段，請使用 claude --resume 開啟工作階段選擇器，並按 Ctrl+A 將範圍擴大到這台機器上的所有專案，然後選取該工作階段
  • 使用 claude -p 或 Agent SDK 建立的工作階段不會出現在選擇器中，因此請對照原始執行所輸出的 session_id 再次檢查 ID

​
Claude Code 讀取此工作階段的逐字稿檔案時，Windows 回報錯誤（EBADF）

您在 Windows 上繼續一個工作階段，其已儲存的逐字稿檔案正常開啟，但接著讀取時發生系統錯誤 EBADF。此系統錯誤並未說明讀取失敗的原因，因此訊息會提出可能的原因以及可以嘗試的做法：
此訊息會接在命令本身的失敗行之後，例如 Failed to resume session <session-id>。claude --resume 或 claude -p 命令在顯示此訊息後會以代碼 1 結束。在工作階段內使用 /resume 後，您目前的工作階段會繼續執行。 處理方式：
  • 將存放工作階段逐字稿的資料夾從會掃描或攔截檔案讀取的軟體（例如安全性、加密或端點管理工具）中排除。逐字稿預設位於 %USERPROFILE%\.claude\projects 下，或位於 CLAUDE_CONFIG_DIR 所指定的目錄下
  • 如果無法新增排除項目，請改為將 Claude Code 加入該軟體的允許應用程式
  • 再次繼續該工作階段
在 v2.1.282 之前，此失敗不附帶任何說明：claude --resume <session-id> 會停在 Failed to resume session <session-id>，而 -p 執行只會輸出系統錯誤文字，例如 Failed to resume session: EBADF: bad file descriptor, read。

​
無法在此工作階段中切換渲染器

切換渲染器時，Claude Code 會重新啟動其程序。您在一個 Claude Code 拒絕重新啟動的工作階段中執行了 /tui，因此它不會切換，也不會儲存任何內容。您看到的訊息會指出原因：
  • Cannot switch renderers while work is running in the background：您有正在背景執行、重新啟動會將其捨棄的工作，例如背景 shell 或 subagent。請等待工作完成，或使用 /tasks 將其停止，然後再次執行 /tui fullscreen 或 /tui default
  • Cannot switch renderers in this session：該工作階段有 Claude Code 無法傳遞給重新啟動後程序的限制。在 v2.1.234 之前，Claude Code 仍會重新啟動，而重新啟動後的工作階段會在沒有這些限制的情況下執行
在限制訊息中，括號內的部分會指出 Claude Code 找到的限制：
訊息括號內可能顯示的各項原因：
  • launch flags: a custom system prompt, a tool allowlist, or restricted settings：您使用了 Claude Code 不會傳回給重新啟動後程序的旗標來啟動工作階段。這些旗標包括 --system-prompt、--system-prompt-file、--append-system-prompt-file、--tools 允許清單、--setting-sources 以及 --permission-prompt-tool
  • permission rules set for this session only：來自 hook 或 SDK 呼叫端的權限更新以 session 目的地新增了拒絕或詢問規則。限於工作階段範圍的允許規則不會觸發拒絕。重新啟動會捨棄這些規則，而 Claude Code 會改為再次提示
  • ask-before-running rules with no command-line form：來自 hook 或 SDK 呼叫端的權限更新，在 Claude Code 以 --allowed-tools 和 --disallowed-tools 傳回的規則之外新增了詢問規則。詢問規則沒有對應的旗標
  • permission rules a command line cannot carry intact 和 added directories a command line cannot carry intact：權限更新在工作階段中途新增了規則或目錄路徑。重新啟動後程序的命令列無法以相同的值攜帶其文字
處理方式：
  • 在未帶有這些限制而啟動的工作階段中，執行 /tui fullscreen，或執行 /tui default 切換回來。Claude Code 會在該處儲存 tui 設定

​
Claude Code couldn’t restart

當此訊息表示您的對話已儲存時，代表對話已寫入磁碟，您可以從中斷處繼續。Claude Code 當時正在自行重新啟動，例如在您執行 /tui 後切換至或切換出全螢幕渲染，但無法啟動新程序，因此以狀態 1 結束：
當重新啟動時沒有可重新開啟的對話，例如因為 /tui 是您在新工作階段中的第一個輸入，訊息內容為 Claude Code couldn't restart. Start Claude Code again. 處理方式：
  • 在您的 shell 中再次執行 claude。如果訊息表示您的對話已儲存，請在新工作階段中執行 /resume 並選取該對話。如果對話不在清單中，請擴大工作階段選擇器的範圍
  • 若重新啟動持續失敗，請在 shell 中使用 claude --debug-file claude-debug.log 啟動 Claude Code。若從該工作階段重新啟動失敗，您啟動所在目錄中的 claude-debug.log 會記錄一行包含作業系統錯誤的 Failed to relaunch:。在您回報問題時請附上該行

​
無法開啟 Claude Desktop

您在工作階段中執行了 /desktop 或其別名 /app，或在 shell 中執行了 claude --desktop，而 Claude Code 用來開啟 Claude Desktop 的系統命令失敗了。執行 /desktop 後，工作階段會留在終端機中；claude --desktop 會輸出不含 Error: 前綴的訊息，並以狀態 1 結束。 括號內的文字會指出失敗的命令，以及其結束狀態和錯誤輸出的第一行（若有產生）。在 macOS 上該命令為 open，如此範例所示；在 Windows 上則為 rundll32：
處理方式：
  • 自行開啟 Claude Desktop，然後再次執行 /desktop 或 claude --desktop
  • 若要閱讀失敗命令的完整錯誤輸出，請使用 /debug 開啟偵錯日誌並再次執行 /desktop，或執行 claude --desktop --debug-file <path>，然後查看偵錯日誌
在 v2.1.285 之前，訊息的結尾為 Open Claude Desktop and run /desktop again.。在 v2.1.275 之前，訊息為 Failed to open Claude Desktop. Please try opening it manually.，且未說明失敗的內容。

​
/terminal-setup 未變更您的 Zed 按鍵對應

您在 Zed 中執行了 /terminal-setup，而 Claude Code 無法完成對您 Zed keymap.json 的更新，因此維持該檔案原狀。 每則訊息都會指出您按鍵對應檔的路徑，並在結尾附上供您自行新增的快捷鍵區塊：
訊息的第一行會指出原因：
  • Couldn't read your Zed keymap, so it was left unchanged.：Claude Code 無法讀取該檔案，例如因為檔案權限
  • Your Zed keymap isn't a readable list of keybindings, so it was left unchanged.：檔案可以正常讀取，但即使允許 // 註解和結尾逗號，仍無法解析為快捷鍵區塊的陣列
  • Couldn't back up your Zed keymap; not modifying it.：Claude Code 無法將檔案複製為其旁邊的 .bak 備份，因此未做任何變更
  • Couldn't update your Zed keymap, so it was left unchanged.：合併後的結果無法驗證為帶有該快捷鍵的有效按鍵對應，因此 Claude Code 將其捨棄而未寫入。帶有重複鍵的快捷鍵區塊可能導致此情況
處理方式：
  • 將訊息中的區塊複製到訊息所指路徑上 keymap.json 的頂層陣列中
  • 對於 isn't a readable list of keybindings，請修正語法錯誤，或讓檔案的頂層值成為陣列，然後再次執行 /terminal-setup
在 v2.1.247 之前，/terminal-setup 無法解析使用 // 註解或結尾逗號的 Zed 按鍵對應，並會以僅包含其自身快捷鍵的內容取代整個檔案，同時回報快捷鍵已安裝。若要還原被較早版本取代的按鍵對應，請使用輸入多行提示詞中所述的 .bak 備份檔案。

​
此連線無法使用 skill 使用情況報告

您透過 Remote Control，從手機或瀏覽器執行了 /skill-doctor。Claude Code 不會透過 Remote Control 傳送 skill 使用情況報告，而是改為回覆此訊息：
處理方式：
  • 在執行該工作階段之機器的終端機中執行 /skill-doctor，或在該處執行 claude -p "/skill-doctor"

​
無法透過 Remote Control 選擇自訂輸出風格

您透過 Remote Control 從行動應用程式或網頁執行了 /output-style，或者該命令是在轉送至工作階段的訊息中送達。由於這樣的回合可能並非來自帳戶擁有者，Claude Code 在其中只會列出並選擇內建風格，並在命令列出風格或無法辨識您提供的名稱時加上此通知。自訂風格名稱會得到與不存在之名稱相同的回覆：
處理方式：
  • 選擇內建風格，例如 /output-style concise
  • 若要使用自訂風格，請在專案的 .claude/settings.local.json 中設定 outputStyle，或在工作階段本身的終端機（若有）執行 /output-style <style>

​
輸出風格會儲存到此工作階段不會載入的本機設定

您在設定來源排除 local 的工作階段中，嘗試以 /output-style <style> 或 /config outputStyle=<style> 切換輸出風格。例如 settingSources 未包含 "local" 的 Agent SDK 工作階段，以及以未包含 local 的 --setting-sources 值啟動的 CLI 工作階段。這兩個命令都會將風格儲存到 .claude/settings.local.json，而這類工作階段永遠不會讀回該檔案，因此 Claude Code 會拒絕，而不是寫入一個不會生效的設定：
處理方式：
  • 將 local 加入工作階段的設定來源，然後再次切換
  • 在工作階段會載入的設定檔中設定 outputStyle 鍵，例如專案中的 .claude/settings.json 或 ~/.claude/settings.json。在 TypeScript SDK 中，請改為在內嵌的 settings 物件中設定 outputStyle；請參閱啟用輸出風格

​
/recap 只在您親自要求時執行

此 /recap 請求並非來自您自己的輸入。它是在從 Slack、Teams 或專案討論串轉送至工作階段的訊息中送達，或是在 routine 或其他程式所傳送的提示詞中送達。 即使轉送的訊息是您自己撰寫的，也會收到此通知。Claude Code 無法判斷轉送或自動化的訊息是否來自執行該工作階段之帳戶的本人，因此會以此通知回覆，而不是提供摘要：
您傳給 claude -p 的 /recap，或您自己的 Agent SDK 應用程式傳送給其所啟動之工作階段的 /recap，都算是您自己的輸入。 處理方式：

​
Plugin 錯誤

這些錯誤來自 plugin 和 marketplace 設定。對於不會產生此頁面上其中一則訊息的 plugin 問題，例如無法載入的 marketplace URL 或已安裝但未出現的 plugin，請參閱 Plugin 疑難排解。

​
plugin eval 目前處於早期存取階段

您執行了 claude plugin eval 或 claude plugin eval init，它在執行任何操作之前以退出代碼 1 和以下其中一則訊息結束：
第一則訊息表示您的建置版本早於 v2.1.269，這是該命令正式推出的第一個版本。第二則訊息表示 Anthropic 已在伺服器端關閉該命令；您的機器上沒有任何設定可以將其重新開啟。 該怎麼做：
  • 執行 claude --version，然後執行 claude update，並在新的工作階段中再次執行該命令。請參閱 plugin evals 的需求
  • 如果您在目前的建置版本上看到第二則訊息，請在執行另一個 claude update 後稍後再試一次

​
Marketplace 是從不受信任的來源註冊的

Marketplace 是以 為官方 Anthropic marketplace 保留的名稱 註冊的，但其註冊的來源不是 anthropics GitHub 儲存庫。Claude Code 每次載入或重新整理 marketplace 時都會重新檢查保留的名稱，因此 marketplace 及從中安裝的 plugin 會停止載入。在 v2.1.205 之前，在其名稱變成保留名稱之前註冊的項目會繼續載入。
對於來源不是 GitHub 儲存庫或 Git URL 的 marketplace（例如本機目錄），中間句子改為 can only be used with GitHub sources from the 'anthropics' organization。claude plugin marketplace add 執行相同的檢查，並以 Failed to add marketplace: 後跟相同的保留名稱句子拒絕保留的名稱。 該怎麼做：
  • 如果 marketplace 已經註冊，執行 claude plugin marketplace remove <name>，然後從官方 github.com/anthropics 儲存庫重新新增它
  • 如果您發佈了在其名稱變成保留名稱之前使用該名稱的第三方 marketplace，請重新命名它並要求使用者從您的來源重新新增它
  • 請參閱 Marketplace schema 下的保留名稱清單

​
Marketplace 名稱是保留名稱的另一種拼寫

Marketplace 的名稱本身不是保留名稱，但 Claude Code 將其視為某個保留名稱的另一種拼寫。保留名稱 列出哪些拼寫算作保留名稱。Claude Code 在您新增 marketplace 時拒絕這樣的名稱：
當 marketplace 已經以這樣的名稱註冊時，其項目停止載入，而 /plugin、claude plugin install 和 claude plugin update 警告：
當名稱需要 shell 引用時，新增時的拒絕讀作 This marketplace's name is another spelling of "<reserved>", a reserved marketplace name. It is not exactly the reserved name it appears to be. 該怎麼做：
  • 將 marketplace 重新命名為不拼寫保留名稱的名稱，然後重新新增它
  • 對於忽略的項目警告，執行它給出的 claude plugin marketplace remove 命令，或從 ~/.claude/plugins/known_marketplaces.json 移除項目

​
Claude Code 拒絕 marketplace 名稱

已註冊的 marketplace 名稱 冒充官方 Anthropic marketplace，根據該部分列出的規則。 如果 marketplace 是在檢查阻止它之前以這樣的名稱註冊的，marketplace 及從中安裝的 plugin 會停止載入，因為 Claude Code 每次讀取 marketplace 的目錄時都會檢查名稱。當名稱模仿官方名稱時，claude plugin list 和 /plugin 錯誤 標籤會報告每個受影響的 plugin，訊息開頭為：
對於模仿名稱，marketplace 自己的錯誤讀作 Claude Code refuses this marketplace's name: it looks like one of Anthropic's own。claude plugin marketplace add 拒絕任何冒充名稱，並顯示 Marketplace name impersonates an official Anthropic/Claude marketplace。 在 v2.1.282 之前，claude plugin list 和 /plugin 報告模仿名稱的 plugin 也失敗載入，而沒有將 marketplace 名稱命名為原因。 該怎麼做：
  • 若要保留由設定檔以 "source": "settings" 內嵌宣告的 marketplace，請在移除舊名稱之前先重新命名它，因為移除 marketplace 也會從您的設定檔中刪除其項目。Claude Code v2.1.292 或更新版本會在訊息中列出這些步驟：
    1. 在每個於 extraKnownMarketplaces 下列出該 marketplace 的設定檔中，為該項目的鍵及其 source.name 設定同一個新的純 ASCII 名稱，且該名稱看起來不像官方名稱。如果管理員透過您組織的受管設定新增該 marketplace，則由管理員執行此步驟
    2. 執行 claude plugin marketplace remove <old-name>，或在 /plugin 的 Marketplaces 標籤中移除舊名稱。這也會卸載其 plugin，並刪除其資料、選項和機密
    3. 再次啟動 Claude Code；如果該檔案是專案的設定檔，請在專案的資料夾中啟動。然後從重新命名後的 marketplace 安裝 plugin
  • 若要保留任何其他 marketplace，請等待其維護者重新命名它，然後執行 claude plugin marketplace update <name>
  • 若要移除 marketplace，請執行 claude plugin marketplace remove <name>。這也會卸載從 marketplace 安裝的 plugin，並刪除其資料、選項和機密
  • 如果您發佈 marketplace，請在您的 marketplace.json 中重新命名它；使用者然後更新 marketplace 而不是移除它

​
Marketplace 已從不同的來源新增

您在工作階段中或從 shell 使用 安裝命令上的 --marketplace <source> 指定了新的 marketplace 來源。Claude Code 從該來源擷取的目錄，與您已從不同來源新增的 marketplace 名稱相同。Claude Code 保留現有的 marketplace 而不是替換它，plugin 不會被安裝。
該怎麼做：
  • 如果您已新增的 marketplace 是您想要的，請按名稱從中安裝：/plugin install <plugin>@<name>
  • 若要切換到新的來源，執行 /plugin marketplace remove <name>，然後重試安裝

​
Plugin 命令在 shell 命令中參考 user_config

Plugin hook、monitor 或 MCP headersHelper 命令參考 ${user_config.KEY} plugin 選項，而替換後的字串會被傳遞到 shell。設定的值包含 $(...) 、反引號或 ; 會在該處作為程式碼執行，因此 Claude Code 拒絕啟動該元件而不是替換該值。檢查在命令範本上執行，因此即使尚未設定任何值，錯誤也會出現。在 v2.1.207 之前，該值被替換到 shell 命令中。 措辭取決於哪個介面參考了該選項。Shell 形式的 hook 報告：
Monitor 報告：
MCP headersHelper 報告：
該怎麼做：
  • 對於 hook，新增 args 陣列使其以 exec 形式 執行，其中每個 ${user_config.KEY} 變成一個沒有 shell 的單一引數。或者移除參考並在指令碼內讀取 $CLAUDE_PLUGIN_OPTION_<KEY> 環境變數
  • 對於 monitor，移除參考並讓 monitor 指令碼從設定檔讀取該值
  • 對於 headersHelper，將 ${user_config.KEY} 移到伺服器的 headers 欄位（不會進行 shell 解析），或在 helper 指令碼內讀取該值

​
Plugin 封存完整性檢查失敗

Plugin 的 marketplace 項目使用具有 sha256 釘選的 archive 來源，而下載檔案的摘要與釘選不符。Claude Code 拒絕安裝，因此 plugin 快取中沒有任何變更。不符有三個可能的原因：
  • 作者計算釘選後，URL 上的檔案已變更
  • 作者在 marketplace 項目中輸入了錯誤的摘要
  • URL 提供的檔案與作者釘選的檔案不同
該怎麼做：
  • 如果您發佈 plugin，使用 shasum -a 256 my-plugin.zip 或在 PowerShell 中使用 Get-FileHash -Algorithm SHA256 my-plugin.zip 重新計算 URL 提供的確切檔案的摘要，並更新 marketplace 項目中的 sha256
  • 如果您安裝 plugin，執行 /plugin marketplace update <name> 以重新整理目錄以防項目已更正，然後重試安裝
  • 如果在重新整理後摘要仍然不符，請在安裝前詢問 marketplace 擁有者他們釘選了哪個檔案

​
路徑逃逸 plugin 目錄

Plugin 元件路徑（在 plugin 的 plugin.json 或其 marketplace 項目 中宣告）解析到 plugin 自己的目錄之外。Claude Code 捨棄該路徑並載入 plugin 的其餘部分。訊息中的元件名稱（例如 commands 或 hooks）命名了宣告路徑的欄位。
在 claude plugin 命令輸出中，相同的錯誤讀作 Path escapes plugin directory: ./../shared.md (commands)。 Claude Code 會拒絕字面上指向 plugin 外部的路徑（例如 ../shared-utils），以及導向 plugin 外部且不屬於 marketplace 符號連結規則 所允許的符號連結。對於符號連結，訊息也會說明路徑解析的位置：
在 macOS 和 Linux 上，Claude Code 也拒絕任何位置包含反斜線的元件路徑，即使路徑保持在 plugin 內。使用 Windows 風格分隔符的元件路徑的 plugin 在 Windows 上載入並在其他平台上觸發此拒絕：
在 v2.1.251 之前，Claude Code 載入在 marketplace 項目中宣告的 commands 路徑，即使它指向 plugin 目錄外。 在 v2.1.257 之前，檢查只查看路徑的拼寫，而不是符號連結導向的位置。 該怎麼做：
  • 將參考的檔案移到 plugin 目錄內，並使用 ./ 相對路徑指向它
  • 如果路徑是指向 plugin 外部檔案的符號連結，請用檔案副本替換符號連結
  • 如果訊息說路徑包含反斜線，請使用正斜線寫入路徑，例如 ./commands/deploy.md
  • 若要與同一 marketplace 中的其他 plugin 共享檔案，請使用 plugin 目錄內的符號連結連結它們，遵循 符號連結規則

​
無法檢查路徑

Claude Code 詢問作業系統 plugin 路徑是否存在，並收到除「找不到」以外的錯誤，因此它不會載入路徑命名的內容。plugin 的多少部分載入取決於哪個路徑失敗：
  • Plugin 的其中一個 預設元件位置（例如 skills/ 資料夾、monitors/monitors.json 檔案或 plugin 根目錄的 SKILL.md）：plugin 的其他元件仍會載入
  • Plugin 自己的目錄：該 plugin 中沒有任何內容載入
對於根本不存在的路徑，您看不到此錯誤。在 /plugin 中，錯誤出現在 plugin 下方，並命名路徑和作業系統傳回的程式碼：
在 claude plugin list 中，相同的錯誤讀作 Path not found: /home/user/my-plugin/skills (skills, ELOOP)。 產生此錯誤的原因包括：
  • ELOOP：路徑中的符號連結指向自己或形成迴圈
  • EIO 或 ESTALE：路徑在損壞或陳舊的網路掛載上
  • EACCES：路徑上方的其中一個目錄拒絕您遍歷它的權限
該怎麼做：
  • 用真實資料夾替換指向自己的符號連結，或刪除它
  • 如果路徑在網路掛載上，重新掛載共享
  • 如果程式碼是 EACCES，恢復您在路徑上方目錄上的執行權限
  • 修復路徑後執行 /reload-plugins，或重新啟動 Claude Code，以載入 plugin 或元件
在 v2.1.265 之前，Claude Code 將無法檢查的預設元件資料夾視為不存在，並在沒有錯誤的情況下載入 plugin 而不包含該元件。

​
Marketplace 項目路徑不保持在 marketplace 目錄內

Plugin 的 marketplace 項目 宣告了一個來源路徑，Claude Code 無法將其解析到 marketplace 自己的目錄內的位置，因此 plugin 不會安裝或載入。拒絕涵蓋：
  • 絕對的項目路徑、使用 .. 爬出 marketplace 或拼寫成網路路徑的項目路徑
  • 在 macOS 和 Linux 上，項目路徑在前導 ./ 之後的任何地方包含反斜線
  • 從遠端來源（例如 git 或 URL）擷取的 marketplace 中的項目，通過解析到 marketplace 目錄外的符號連結到達其目標
  • 相對項目在從直接 URL 新增到其 marketplace.json 的 marketplace 中：Claude Code 只下載該檔案，因此路徑命名的本機 plugin 檔案不存在。請參閱 相對路徑的 Plugin 在基於 URL 的 marketplace 中失敗
claude plugin install 報告拒絕如下：
當已安裝的 plugin 的項目失敗相同的檢查時，claude plugin list 將 plugin 顯示為 failed to load，並顯示：
該怎麼做：
  • 如果您維護 marketplace，將項目的 source 寫成使用正斜線的純相對路徑（例如 ./plugins/my-plugin），並保持它跨越的任何符號連結指向 marketplace 目錄內
  • 如果您從直接 URL 新增了 marketplace，相對項目無法解析。要求 marketplace 作者使用 另一個 plugin 來源，或改為從其 git 儲存庫新增 marketplace

​
無法載入 marketplace 設定

Claude Code 將您新增的 plugin marketplace 保留在 ~/.claude/plugins/known_marketplaces.json 的登錄檔案中。當 Claude Code 無法使用該檔案時，需要登錄的 plugin 命令（例如 claude plugin install）會失敗，並顯示以下兩則訊息之一：
  • Failed to load marketplace configuration：檔案存在，但不是有效的 JSON，或無法讀取。空檔案也會以這種方式失敗。
  • Marketplace configuration file is corrupted：檔案是有效的 JSON，但其內容與登錄 schema 不符。
使用空檔案時，claude plugin install 報告：
在 v2.1.246 之前，claude plugin install 沒有報告此失敗。 該怎麼做：
  • 開啟 ~/.claude/plugins/known_marketplaces.json 並修復 JSON，或修復訊息命名為與登錄 schema 不符的項目
  • 如果您無法修復它，刪除檔案或用 {} 替換其內容，然後使用 claude plugin marketplace add <source> 重新新增每個 marketplace。Claude Code 在您下次在已信任的資料夾中啟動它時，重新註冊您的使用者或受管設定在 extraKnownMarketplaces 中宣告的 marketplace。

​
Plugin 是您的組織所需的

您執行了 claude plugin disable，或使用 /plugin 已安裝 標籤，以關閉您的組織標記為必需的 從 claude.ai 同步的 plugin：
Claude Code 不會儲存任何內容，plugin 保持啟用。 當您嘗試停用必需 plugin 所依賴的 plugin 時，Claude Code 以相同的方式拒絕，並顯示命名需要它的必需 plugin 的訊息。 該怎麼做：
  • 詢問您的 claude.ai 組織的管理員以變更 plugin 在 claude.ai 上的必需狀態

​
Plugin 未被卸載

您執行了 claude plugin uninstall，或在 /plugin 已安裝 標籤中選擇了 卸載，而卸載停止並顯示以 "<plugin>" was not uninstalled: 開頭的訊息。如果該冒號之後的文字以 installed_plugins.json 開頭而不是命名設定檔案，原因是 installed_plugins.json 中的內容此版本的 Claude Code 無法讀取。對於該形式，請參閱 installed_plugins.json 保存此版本無法讀取的記錄。 當 Claude Code 從 enabledPlugins 移除 plugin 的項目並讀回該範圍的設定檔案時，要麼 plugin 仍在該處被開啟，要麼可以開啟它的檔案無法被讀取或檢查。在設定項目可以將其重新開啟時刪除 plugin 的已儲存選項、機密和資料會遺失它們，因此卸載會停止：plugin 保持安裝，它儲存的任何內容都不會被刪除。
訊息的中間部分命名了檔案和原因：
  • it is still switched on in <file>, although the settings change reported no error：設定寫入報告成功但項目在讀回檔案時仍在那裡
  • it is still switched on in <file>, and the settings change failed (<error>)：檔案無法被儲存，原因在括號中
  • <file> is there and could not be read：檔案存在但無法作為設定讀取，例如因為它不是有效的 JSON，所以它可能仍然啟用 plugin
  • <file> (not read: it is on a network path or is a link to one, or could not be checked)：Claude Code 沒有讀取專案或本機設定檔案，因為檔案或保存它的 .claude 資料夾是指向網路位置的連結，或因為它無法檢查該路徑
claude plugin uninstall 以退出代碼 1 結束，使用 --json 時結果帶有 failureCode: "settings_still_on"。/plugin 顯示相同的訊息。 該怎麼做：
  • 遵循訊息的最後一句：修復或替換它命名的設定檔案，或自己從該檔案中的 enabledPlugins 移除 plugin 的項目，然後再次執行卸載

​
工具錯誤

這些錯誤來自 Claude 的工具呼叫。Claude 會自行修正大多數工具錯誤。當某個錯誤需要您進行變更時，該錯誤的 處理方式 清單會說明需要變更的內容。

​
No such tool available

Claude 以不在工作階段工具清單中的名稱呼叫了工具。Claude Code 會將錯誤作為該工具呼叫的結果傳回給 Claude，回合則會繼續進行。當 Claude Code 能判斷工具缺少的原因時，它會在工具名稱後面加上一句話，說明原因或指出應改為呼叫的工具，如第二行所示：
在您恢復工作階段後不久，當 Claude 呼叫某個 MCP 伺服器的工具時，該伺服器可能仍在進行第一次連線嘗試。Claude Code 接著會 等待該伺服器，若等待結束時工具仍無法使用，便會傳回此錯誤。在 v2.1.284 之前，這類呼叫會立即失敗，而不會等待。 工具名稱被 Claude Code 截斷至 200 個字元 的呼叫也會以此錯誤失敗。 處理方式：
  • 如果只發生一次，您無需採取任何動作。Claude 會讀取錯誤，回合會繼續進行。
  • 如果對某個 MCP 伺服器工具的呼叫持續以此錯誤失敗，請在工作階段中執行 /mcp，或在 shell 中執行 claude mcp list，以檢查該伺服器的 狀態，並從 /mcp 重新連線失敗的伺服器。在 Agent SDK 中，請參閱 錯誤處理。

​
Agent would be spawned with zero tools

subagent 的 tools 清單 中的每個項目都無法比對到可用的工具，因此 Claude Code 拒絕啟動該 subagent：沒有任何工具，它就無法執行動作。訊息會依問題類型將您的項目分組：
  • Unrecognized：該項目不符合任何工具名稱，通常是拼字錯誤，例如將 Grep 寫成 Grpe。
  • Not available to subagents：該項目指定的是實際存在、但 subagent 無法使用 的工具。背景 subagent 保留的內建工具集較小，因此當 subagent 會在背景執行時（這是預設行為），只有前景 subagent 能使用的項目就會歸入此組。如果您列出 Agent，訊息會改將其歸入下一組。
  • Matched no tools in this session：該項目有效，但目前工作階段中沒有任何工具與其相符，例如未連線 GitHub MCP 伺服器時的 mcp__github__*，或是已達 深度上限 的 subagent 所列的 Agent。
省略 tools 欄位永遠不會觸發此拒絕。如果您將 tools 清單留空，或 disallowedTools 移除了其中的每個項目，Claude Code 也會略過此拒絕，並在沒有工具的情況下啟動 subagent。 在 v2.1.208 之前，subagent 會在沒有工具的情況下啟動，並可能傳回空白或令人困惑的結果。
處理方式：
  • 對照 subagent 可用的工具，修正錯誤中列出的每個項目
  • 移除工作階段中不存在之工具的項目，例如來自未連線伺服器的 MCP 工具
  • 如果該項目指定的是已連線的 MCP 伺服器，請將該項目與該伺服器 工具名稱 中所拼寫的伺服器名稱進行比對，例如 mcp__reports__v2__get_totals 中的 reports__v2。對於該伺服器，請寫成 mcp__reports__v2__*，也就是 mcp__ 後接完整名稱再加上 __*。若使用較短的 mcp__reports（其指定的是名為 reports 的伺服器），subagent 將無法取得任何 reports__v2 工具
  • 對於 背景 subagent 會捨棄 的工具（例如 CronCreate），請移除該項目。若要保留該工具，請 關閉 fork 模式，並要求 Claude 在前景執行該 subagent
  • 刪除 tools 欄位而不列出工具，即可讓 subagent 取得每個 subagent 可用的工具
  • 對於只包含 Agent 的 tools 清單，請提高 深度上限，或至少再給該 agent 一個其他工具：Claude Code 會在達到該上限時保留 Agent 不提供，因此除了 Agent 之外沒有任何其他項目的清單會解析為沒有工具

​
File is covered by a Read deny rule

Edit 或 Write 工具被呼叫來操作符合 Read 拒絕規則 的路徑，包括在該路徑建立新檔案。這兩個工具都會變更 Claude 必須能夠讀回的內容，因此 Claude Code 會在存取任何檔案之前拒絕該呼叫。NotebookEdit 不受 Read 拒絕規則涵蓋。在 v2.1.228 之前，該規則只會封鎖 Edit 工具；在 v2.1.208 之前，只有 Edit 拒絕規則會封鎖編輯。
當 Claude Code 拒絕 Write 工具時，訊息的結尾會改為 and cannot be written。 處理方式：
  • 如果 Claude 應該能夠變更該檔案，請在 /permissions 或 設定 中移除或縮小該 Read 拒絕規則
  • 如果該檔案必須保持不變，請保留該規則，並為相同路徑新增 Edit 拒絕規則，以同時封鎖 NotebookEdit 工具

​
Path cannot contain null bytes

檔案工具呼叫的路徑或模式引數包含 null 位元組，而檔案系統和搜尋工具無法接受這種字元。Read、Write、Edit、NotebookEdit、Glob 和 Grep 會檢查這一點，訊息會指出工具和引數：
該工具呼叫會失敗，Claude 會看到錯誤，回合則會繼續進行。 處理方式：
  • 您無需採取任何動作：錯誤會作為工具的結果傳回給 Claude，而訊息本身會告知 Claude 移除 null 位元組並重試
在 v2.1.281 之前，Read、Write、Edit 或 NotebookEdit 路徑中的 null 位元組會以指出 Path contains null bytes 的錯誤結束整個回合，且工具從未執行。

​
subagent_type is required

Claude 在未指定 subagent_type 的情況下呼叫了 Agent 工具，而此工作階段沒有可供後備使用的 general-purpose subagent。這會發生在兩種設定中： 處理方式：
  • 通常無需任何動作：訊息會列出工作階段中確實存在的 subagent，因此 Claude 可以使用其中之一重試
  • 如果 Claude 持續失敗，請將 general-purpose 加入 tools: Agent(...) 允許清單，或取消設定 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS
在 v2.1.235 之前，相同的呼叫會以 Agent type 'general-purpose' not found 失敗。

​
Memory index is over its read limit

Claude 寫入了 自動記憶 索引 MEMORY.md，並使其超過其中一項讀取上限：200 行或 25KB。寫入已成功，但在工作階段開始時只會載入前 200 行或 25KB（以先達到者為準），因此每次讀取索引時，超出上限的所有內容都會被捨棄。在 v2.1.210 之前，超過上限的索引會在下次載入時被無聲截斷，且在寫入時不會有任何提示。
只有會被載入的內容才會計入上限。YAML frontmatter 和區塊層級的 HTML 註解會在載入索引前被移除，因此不計入測量。在 v2.1.211 之前，Claude Code 會測量原始檔案，即使載入的內容符合上限，frontmatter 或註解也可能觸發此錯誤。 Claude Code 會在寫入後將錯誤傳遞給 Claude，而不是在您的終端機中以橫幅形式顯示，因此您可能只會在逐字稿中注意到它。 當 Claude 的寫入使檔案接近上限但未超過時，Claude Code 會傳回較溫和的提醒，要求壓縮索引，而非此錯誤。 處理方式：
  • 讓 Claude 重寫 MEMORY.md，或要求它這麼做：每個項目保留一行，將細節移至主題檔案，並合併或刪除過時的項目
  • 若要自行精簡索引，請參閱 稽核與編輯您的記憶

​
pkill pattern matches the Claude Code process

Bash 工具呼叫中的 pkill 命令使用了符合 Claude Code 程序本身的模式（通常搭配 -f），因此 Claude Code 會拒絕該命令，而不是讓它結束工作階段。Claude Code 會在執行 pkill 之前以 pgrep 測試該模式，若結果中包含其自身的程序 ID 便會拒絕。此檢查僅在 Linux 上執行；在 macOS 上，pkill 會原封不動地執行。在 v2.1.214 之前，該命令會執行，且符合的模式會在回合進行中終止 Claude Code 工作階段。
拒絕訊息會出現在 Bash 工具結果中，而不是以橫幅形式出現在您的終端機中，Claude 通常會自行調整命令。 處理方式：
  • 縮小模式範圍，使其只符合預期的程序，例如使用目標二進位檔的完整路徑，而非簡短的子字串
  • 若要停止由目前 shell 啟動的程序，請將 pkill -P $$ 與模式搭配使用，這會將比對範圍限制在該 shell 自身的子程序

​
Failed to write to a teammate’s inbox

Claude Code 無法將訊息寫入 ~/.claude/teams/{team-name}/inboxes/ 下隊員的信箱檔案，因此收件者沒有收到任何內容。當 Claude Code 無法建立或更新該檔案時，寫入就會失敗，例如磁碟已滿、目錄不可寫入，或另一個 agent 持有收件匣鎖定過久。在 v2.1.224 之前，即使寫入失敗，Claude Code 仍會回報訊息已傳送。 錯誤會出現在傳送端 agent 的工具結果中，而不是以橫幅形式出現在您的終端機中，其文字會告知 Claude 重試：
結構化的 agent team 協定訊息也會以相同方式失敗，且錯誤會指出未送達的訊息：當 Claude Code 無法寫入計畫核准、計畫駁回、關閉請求或關閉拒絕時，錯誤內容為 Failed to write the <message> to <name>'s inbox — nothing was sent。該清單中的 plan approval 是組長核准隊員計畫的決定；隊員提交的計畫則是另一則 plan approval request 訊息。該訊息與另外兩則協定訊息有各自的訊息文字與後果：
  • Failed to write the plan approval request to the lead's inbox — plan not submitted; try again：隊員的計畫從未送達組長，且隊員會停留在 plan mode，直到重新提交成功為止
  • The permission request could not be delivered to the team lead (mailbox write failed)：隊員的權限請求從未送達組長，因此沒有人核准該工具呼叫
  • The confirmation could not be written to team-lead's inbox.：關閉核准本身已生效，隊員會結束；只是缺少給組長的確認
當您自行傳訊息給隊員時（在組長工作階段中輸入 @name 後接訊息），相同的失敗會以通知形式出現，即 Couldn't write to @name's inbox — message not sent. Try again.，且 Claude Code 會將您的文字保留在提示詞輸入框中，以便您再次傳送。 處理方式：
  • 請傳送者重新傳送訊息；收件匣鎖定的爭用是暫時性的，重試時便會解除
  • 檢查可用磁碟空間，並確認 ~/.claude/teams 及其下的檔案可由您的使用者寫入

​
Teammate’s agent definition was not restored

Claude 傳訊息給一位已停止的 agent team 隊員，Claude Code 將其恢復，但沒有重新套用它最初據以產生的 subagent 定義。此通知會接在傳送端 agent 工具結果中的恢復報告之後，並指出原因。當定義檔案來自沒有已儲存信任的資料夾時，內容如下：
此檢查適用於專案或 --add-dir 目錄之 .claude/agents/ 目錄中的定義，而接受上層資料夾的信任對話框並不能滿足此檢查。 處理方式：
  • 在 除錯日誌 指出的資料夾中執行 claude，並接受信任對話框。下次 Claude Code 恢復該隊員時，便會重新套用定義；您不需要重新啟動組長工作階段
  • 或者，在 ~/.claude.json 中將 hasTrustDialogAccepted 項目設為 true，並使用除錯日誌印出的確切 projects["<path>"] 鍵

​
Message too large for cross-session delivery

Claude 傳送給您在此機器上另一個工作階段的 跨工作階段訊息 過長，無法傳送。Claude Code 拒絕了它，接收端工作階段沒有收到任何內容。拒絕訊息會出現在傳送端工作階段的工具結果中，而不是以橫幅形式出現在您的終端機中。它會指出兩個大小以及如何讓訊息符合限制：
重新傳送相同的文字也會以相同方式失敗。 處理方式：
  • 要求 Claude 摘要該訊息，或將大量內容放入檔案並傳送該檔案的路徑
  • 要求 Claude 將內容拆分成數則較短的訊息
在 v2.1.235 之前，Claude Code 會將過大的訊息回報為已傳送。接收端工作階段會在未讀取的情況下將其捨棄。

​
Too many messages to this session just now

Claude 向您在此機器上的某個工作階段快速連續傳送了大量 跨工作階段訊息，而這一連串訊息已達該工作階段收件匣所能接受的量。Claude Code 拒絕了下一次傳送，接收端工作階段沒有從中收到任何內容。拒絕訊息會出現在傳送端工作階段的工具結果中，而不是以橫幅形式出現在您的終端機中：
處理方式：
  • 通常無需任何動作：Claude 會將剩餘內容合併成一則訊息，或在傳送更多訊息前稍候
  • 如果是您自己促成了這一連串訊息，請要求 Claude 將剩餘內容合併成單一訊息
在 v2.1.236 之前，Claude Code 會將這些傳送回報為已傳送。接收端工作階段會在未讀取的情況下將其捨棄。

​
Cross-session message was dropped at the recipient session’s inbox

Claude 傳送了一則 跨工作階段訊息 給您在此機器上的另一個工作階段，而該工作階段的收件匣在該工作階段中的 Claude 讀取之前就將其捨棄。這一行會指出收件者的位址，若收件者提供了原因，則會在破折號後附上原因：
一行可以涵蓋數則被捨棄的訊息，此時開頭會使用複數形式，例如 Cross-session messages (12) were dropped。若要找出某個位址屬於哪個工作階段，請將其與每個工作階段中 /status 顯示的 Peer address 列 進行比對。 在破折號之後，這一行會提供下列一個或多個原因：
  • its queue of undelivered peer messages was full：收件者已持有其佇列所允許的最大數量、來自其他工作階段的未送達訊息
  • you sent faster than that session accepts：傳送端工作階段的訊息抵達速度，超過收件者從單一傳送者所接受的速度
  • it repeated your previous message：該訊息與傳送端工作階段不久前傳送給此收件者的訊息完全相同
  • a relay loop between sessions was cut：該訊息延續了工作階段之間互相傳訊的鏈結，而該鏈結經過收件者的次數過多或長度過長
處理方式：
  • 假設收件者從未看到被捨棄的訊息。Claude Code 也會如此告知 Claude，並告訴它將仍然重要的內容納入稍後的一則訊息中，而不是立即重新傳送
  • 如果您的工作階段會頻繁地互相傳送更新，請要求 Claude 傳送較少但較大的訊息，例如在某個工作階段完成工作時傳送一份報告
  • 對於 a relay loop between sessions was cut，請自行在其中一個工作階段中輸入下一個指令。Claude 為回應您自己的提示詞而傳送的訊息會開始一條新的鏈結
在 v2.1.238 之前，當收件者的收件匣捨棄訊息時，傳送端工作階段不會收到任何報告。

​
Refusing to send a cross-session message

在 Claude Code 將 跨工作階段訊息 寫入您在此機器上的另一個工作階段之前，它會檢查目標工作階段的收件匣 socket 是否就是該訊息所指定的端點。當檢查失敗時，Claude Code 會在傳送端工作階段中拒絕傳送，目標工作階段不會收到任何內容。對於 Claude 傳送的訊息，拒絕訊息會出現在傳送端工作階段的工具結果中：
Refusing to send: 之後的文字會指出失敗的檢查：
  • reply target is a symlink：目標工作階段的 socket 路徑上有一個符號連結。Claude Code 不會透過它傳遞，因為該處的連結可能會將訊息重新導向至非目標工作階段建立的端點。
  • cannot vet reply target：Claude Code 完全無法檢查目標路徑，例如讀取時因權限錯誤而失敗。
處理方式：
  • 通常無需任何動作：這些檢查可防止訊息送達其所指定工作階段以外的端點，且沒有傳送任何內容
  • 如果 reply target is a symlink 在某個工作階段重複出現，請檢查是什麼在該工作階段的 socket 路徑上建立了連結，該路徑會顯示在其 /status 的 Peer address 下
Claude Code 會檢查檔案路徑的 權限規則，然後在工具開啟檔案或開始搜尋時再次確認該解析結果。當它無法確認該路徑仍通往檢查所核准的位置時，Claude Code 會拒絕該操作，而不是跟隨它。拒絕訊息會出現在工具結果中：
每個拒絕都會指出其原因：
  • its symlink resolution changed after permission was checked：路徑上或 Grep、Glob 搜尋根目錄上的符號連結，在權限檢查與操作之間遭到替換。在讀取拒絕中，括號內的文字會指出哪一項比對失敗。
  • its parent-directory symlink resolution changed after permission was checked：寫入路徑所經過的某個目錄不再解析至已核准的位置
  • where it leads on disk could not be determined (a link on the way could not be examined, or the links do not resolve)：Claude Code 無法沿著路徑找到磁碟上的最終位置，例如因為路徑上的符號連結形成迴圈
  • it is a symbolic link. Write to the link's target path instead：要求的寫入位置本身就是符號連結，例如作為指向 AGENTS.md 之符號連結的 CLAUDE.md；訊息會引導 Claude 改用該連結的目標
  • Refusing to write through symlink: <path>. Resolve the symlink and pass the real target path explicitly.：在另一個寫入器開啟檔案時偵測到的相同情況，例如寫入作為符號連結的 .mcp.json
  • Refusing to write into symlinked directory: <path>：存放該檔案的目錄本身就是符號連結，例如連結至其他位置的專案 .claude/ 目錄
  • a path one of its Read deny rules is written through changed while the search was being prepared. Retry.：搜尋所適用的某條 Read 拒絕規則指定了一個經過符號連結的路徑，而該連結在 Claude Code 準備搜尋時發生了變更
  • it could not be opened (EACCES) — it is unreadable, or is being replaced concurrently.：搜尋根目錄存在，但無法開啟；括號內的代碼是作業系統錯誤
  • its permission check expired before it ran (too many concurrent file operations). Retry.：在大量同時進行的檔案操作下，Claude Code 在工具使用核准記錄之前就將其逐出；重試會執行新的權限檢查
  • ripgrep was found only by name on PATH, and a search outside the working directory cannot apply your Read deny rules in that configuration：Claude Code 無法將 rg 二進位檔解析為絕對路徑，因此會拒絕工作目錄以外的搜尋，而不是執行一個您的拒絕規則無法涵蓋的搜尋
處理方式：
  • 通常無需任何動作：拒絕會作為工具結果傳遞給 Claude，被拒絕的操作不會執行
  • 如果符號連結拒絕在某個路徑上重複出現，請找出持續改寫該處連結的來源，例如建置工具或檔案監看程式，或要求 Claude 使用檔案的解析後路徑，而非連結路徑
  • 如果 Claude Code 在 Windows 上於 AppContainer 或受限權杖沙箱中執行時，每個檔案都出現此拒絕，請升級至 v2.1.265 或更新版本
  • 如果在 macOS 上，對於沒有任何程式在改寫的檔案（例如拖曳到提示詞中的螢幕截圖）出現讀取拒絕，請升級至 v2.1.273 或更新版本
  • 對於 ripgrep 拒絕，請使用您的套件管理員安裝 ripgrep，使 rg 能在 PATH 上解析為絕對路徑，或將搜尋保持在工作目錄之下
在 v2.1.251 之前，Claude Code 只會針對檔案寫入重新檢查路徑的解析結果，因此在權限檢查後遭替換的連結可能會在沒有任何訊息的情況下，將讀取或搜尋重新導向至不同的位置。在這些拒絕中，只有上層目錄、透過符號連結寫入，以及符號連結目錄這幾種寫入拒絕會出現在較早的版本中。 在 v2.1.280 之前，where it leads on disk could not be determined 拒絕不會出現。

​
Task output swap refused

Claude Code 會將每個 Bash 命令的輸出儲存到其暫存目錄下的檔案中。每次開啟這些檔案時，它都會檢查路徑是否仍通往它所建立的檔案，且沒有符號連結、額外的硬連結或被移動的目錄將其重新導向。此訊息表示該檢查失敗，因此 Claude Code 拒絕了該操作，而不是透過該路徑寫入或讀取輸出。訊息會出現在 Bash 工具結果中：
括號內的文字會指出失敗的檢查。output symlink was re-pointed、output file identity changed 和 not a regular file 等原因都回報相同的情況：輸出路徑上或沿途的某個東西已不再是 Claude Code 所建立的檔案。只有部分原因會附帶 To recover: 句子。 如果檢查在命令仍在執行時失敗，Claude Code 會停止該命令，其結果會回報：
處理方式：
  • 升級至 v2.1.260 或更新版本。較早的版本有時會在沒有連結或被移動目錄的情況下顯示此訊息
  • 將 CLAUDE_CODE_TMPDIR 設為全新的目錄，然後重新啟動 Claude Code
  • 或者，檢查 Claude Code 暫存目錄下您專案的目錄，也就是範例訊息中的 /private/tmp/claude-501/-Users-you-my-project。如果該路徑是符號連結，或是不應存在的目錄，請移除該連結或目錄本身，而非連結的目標，然後重新啟動 Claude Code
  • 如果拒絕重複出現，表示有某個程序在工作階段執行期間，替換、連結或移除 Claude Code 暫存目錄下的項目。請將 CLAUDE_CODE_TMPDIR 設為沒有其他程式管理的目錄，然後重新啟動

​
Disk quota or temp filesystem is full

Claude Code 會將每個 Bash 和 PowerShell 命令的輸出儲存到其暫存目錄下的檔案中。當命令以非零代碼結束且完全沒有輸出時，Claude Code 會檢查存放該檔案的檔案系統是否已用盡空間或 inode，或您在其上的磁碟配額是否已用完。若是如此，命令的結果中會以診斷訊息取代空白輸出：
訊息會指出用盡的資源：
  • Your disk quota is full ... (EDQUOT)：您自己在該檔案系統上的配額已用完。即使檔案系統仍顯示有可用空間，配額也可能已滿
  • The filesystem with Claude Code's temp directory ..., or your disk quota on it, is full (ENOSPC)：檔案系統或您在其上的配額已沒有剩餘空間
  • Command output was lost: the temp filesystem at ... is full 或 ... is out of inodes：檔案系統幾乎沒有剩餘的可用空間，或 inode 即將用盡
處理方式：
  • 刪除存放 Claude Code 暫存目錄之檔案系統上不再需要的檔案。對於 EDQUOT，請刪除計入您自己配額的檔案。對於 out of inodes，請刪除大量檔案，而不是少數幾個大型檔案，因為無論大小，每個檔案都會佔用一個 inode
  • 或者，將 CLAUDE_CODE_TMPDIR 設為位於有空間之檔案系統上的目錄，然後重新啟動 Claude Code
  • 接著讓 Claude 再次執行該命令。它先前印出的輸出已遺失，而不是被截斷

​
File is not valid UTF-8

Claude 對一個位元組無法解碼為 UTF-8 的檔案使用了 Edit 或 NotebookEdit 工具，而 Claude Code 拒絕了該變更。沒有寫入任何內容，因此檔案維持原狀。這些工具會將整個檔案以 UTF-8 存回，這會把它們無法解碼的每個位元組都變成替代字元 U+FFFD。訊息會出現在工具結果中：
原本應為 UTF-8 的檔案，只要包含即使一個無效的位元組序列，也會出現此訊息，因為檢查涵蓋的是檔案的整體位元組。 處理方式：
  • 若要保留檔案目前的編碼，請讓 Claude 依照訊息的指示，使用以該編碼讀取和寫入檔案的 shell 命令進行變更
  • 若要繼續使用 Edit 工具編輯該檔案，請將其轉換為 UTF-8，或修正原本應為 UTF-8 之檔案中的無效位元組，然後要求 Claude 再次進行編輯
在 v2.1.296 之前，Edit 和 NotebookEdit 會套用這類編輯，並將無法解碼的每個位元組儲存為 U+FFFD。若您使用的是這些版本，請更新 Claude Code。

​
The source file is not valid UTF-8 text

Claude 嘗試從一個位元組無法解碼為文字、或其文字已包含替代字元 U+FFFD 的檔案發佈 artifact，因此 Claude Code 在上傳任何內容之前就拒絕了發佈。訊息會出現在 Artifact 工具結果中，並指出第一個需要修正的位置：
Claude Code 會將檔案解碼為 UTF-8，若檔案以小端序 UTF-16 位元組順序標記開頭，則解碼為 UTF-16。當這類 UTF-16 檔案無法解碼時，第一則訊息會指出 UTF-16，但仍會告知您將檔案重寫為 UTF-8。當指出的位置之後還有更多位置時，訊息會在位置後加上計數，例如 (+2 more)。 處理方式：
  • 通常無需任何動作：Claude 會重寫檔案並再次發佈
  • 如果該檔案是您撰寫或匯出的，請將其重新儲存為 UTF-8，並將每個 U+FFFD 替換為先前的編輯、貼上或轉換所遺失的字元
  • 若要在頁面上顯示刻意使用的 U+FFFD，請在 HTML 中將其寫成 &#xFFFD;，而不是使用該字元本身
在 v2.1.267 之前，Claude Code 會在未檢查的情況下上傳這類檔案，改由伺服器拒絕發佈。

​
Not published: that file is on a network share

Claude 嘗試從路徑指向網路主機的檔案發佈 artifact：
  • 在 Windows 上，不位於您啟動時以 --add-dir 傳入之對應網路磁碟機下的 \\server\share 路徑
  • 在 macOS 或 Linux 上，自動掛載路徑，例如 /net/<host>/page.html
查詢這類路徑會聯繫其所指定的主機，而在 Windows 上，這種聯繫可能會將您的憑證傳送給該主機。Claude Code 會拒絕發佈該檔案，且不會讀取它。拒絕訊息會出現在 Artifact 工具結果中：
處理方式：
  • 如果您不需要該檔案本身，則無需任何動作：訊息會告知 Claude 改為從工作階段自己的資料夾發佈檔案
  • 若要發佈該檔案本身，請將其複製到本機磁碟上的資料夾，然後再次提出要求
  • 在 Windows 上，若要讓 Claude 直接從共用資料夾發佈，請將其對應至磁碟機代號，並在啟動 Claude Code 時傳入該磁碟機。例如在 PowerShell 中，執行 net use Z: \\server\share，然後執行 claude --add-dir Z:\。Claude 便可以從該磁碟機發佈檔案。在工作階段進行中以 /add-dir 新增該磁碟機是不夠的。
  • 在 macOS 或 Linux 上，將共用資料夾掛載至某個目錄，例如 /mnt 或 /Volumes 下的目錄，並從該路徑發佈，而非從自動掛載路徑發佈

​
Reading a local file from outside the connected folders in a Cowork session

在 Claude Desktop 應用程式中於您的機器上執行的 Cowork 工作階段裡，Claude 為 artifact 指定了一個本機檔案。Claude Code 無法確認該檔案是位於工作階段已連接資料夾內的一般檔案：該路徑位於這些資料夾之外、經過符號連結，或其寫法可能指向與表面上不同的檔案。讀取這類檔案需要您的核准，而在無法向您顯示核准卡片的工作階段中（例如設定為略過所有核准的工作階段），Claude Code 會拒絕該讀取。 拒絕訊息會出現在 Artifact 工具結果中；當檔案完全無法被檢查時，則會改為指出該失敗：
處理方式：
  • 通常無需任何動作：訊息會告知 Claude 改用已連接資料夾內的一般檔案
  • 若要將該檔案原樣放入 artifact，請將其以一般檔案（而非符號連結）的形式複製到工作階段的其中一個已連接資料夾中，然後再次提出要求

​
WebFetch cannot fetch localhost

Claude 使用主機名稱不含點的 URL 呼叫了 WebFetch，例如 http://localhost:3000 或像 http://wiki/ 這樣的純內部網路名稱。WebFetch 會在發出任何請求之前拒絕這些 URL：
處理方式：
  • 通常無需任何動作：訊息會引導 Claude 透過 Bash 工具使用 curl，它可以連線至本機與內部網路伺服器
在 v2.1.268 之前，WebFetch 會以通用的 Invalid URL 錯誤回報這些 URL。

​
WebFetch domain safety check failed

在擷取 URL 之前，WebFetch 會將 URL 的主機名稱傳送至 api.anthropic.com，以對照 Anthropic 的 網域安全封鎖清單 進行檢查。如果檢查無法完成，WebFetch 就無法確認該網域是安全的，因此不會擷取該頁面，工具結果會改為包含下列其中一則訊息：
  • rate-limited：檢查端點以 HTTP 429 回應。訊息會告知 Claude 在沒有該頁面的情況下繼續，且稍後最多只重試一次。Claude Code 不會快取失敗的檢查，因此稍後擷取該網域時會再次執行檢查。如果您網路上的工作階段經常遇到此情況，可以在設定中使用 skipWebFetchPreflight: true 略過檢查。
  • Unable to verify：檢查請求失敗、逾時或收到其他錯誤狀態。如果您的網路封鎖了 api.anthropic.com，請將該網域加入允許清單，或在設定中使用 skipWebFetchPreflight: true 略過檢查。
在 v2.1.286 之前，速率限制訊息的內容為 The safety check for domain example.com is temporarily rate-limited (too many domain checks from this network). Retry after about a minute; retrying sooner will fail the same way.。 在 v2.1.285 之前，受速率限制的檢查會改以 Unable to verify 訊息回報。

​
背景工作階段錯誤

背景工作階段在沒有自己的互動式終端機的情況下執行，因此需要終端機的命令在那裡的行為會有所不同。這些訊息會出現在背景工作階段的逐字稿中、附加到背景工作階段的終端機中、您分派的工作階段或 shell 中，或者對於下面的worktree-guard 項目，會出現在任何在 worktree 中隔離或執行 worktree 隔離 subagent 的工作階段中；當訊息特定於某個使用介面時，其項目會說明。

​
在背景工作階段中拒絕的命令

開啟互動式對話框的命令在沒有終端機附加到背景工作階段時無法執行。/install-github-app、/mcp 設定清單和 MCP 伺服器選單中的身分驗證動作會回應一則訊息。對於 /install-github-app 和 /mcp 設定清單，工作階段也會在 agent 檢視中的 Needs input 下出現，以便您可以找到它、附加並再次執行命令。當終端機附加時，這些命令正常運作。 在 v2.1.216 之前，工作階段在 /install-github-app 或 /mcp 設定清單被拒絕後不會在 Needs input 下出現。在 v2.1.213 到 v2.1.215 中，命令在附加終端機時仍然有效，拒絕訊息告訴您附加並再次執行命令。從 v2.1.208 到 v2.1.212，Claude Code 即使在附加終端機時也拒絕它們，訊息如 Can't open MCP settings in a background session；在這些版本上，改為從一般的 claude 工作階段執行命令，或升級。在 v2.1.208 之前，它們在背景工作階段內開啟其對話框。僅在 v2.1.208 中，Claude Code 也拒絕了背景工作階段中的 /model 選擇器，且 /upgrade 列印升級 URL 而不是開啟瀏覽器。 措辭會命名該命令。/mcp 設定清單報告：
該怎麼做：
  • 從 agent 檢視附加到工作階段並再次執行命令
  • 或使用訊息命名的形式，例如 /mcp reconnect <server>、/mcp enable 或 /mcp disable，這些在不附加的情況下有效

​
寫入或命令被阻止，因為路徑無法安全解析

Claude 透過 worktree 隔離防護無法解析為一個可驗證位置的拼寫來定址檔案或工作目錄。防護會檢查任何在 worktree 中隔離的工作階段（無論互動式或背景）以及 worktree 隔離 subagent 中的寫入和命令工作目錄。它在檢查操作不會到達共享簽出之前解析符號連結，當解析失敗時，它會阻止操作而不是讓它落在那裡。訊息命名它拒絕的路徑形式以及如何重試：
被阻止的命令報告其工作目錄的相同原因，並以 re-run the command from its direct symlink-free path 結尾。在 v2.1.217 之前，防護比較路徑拼寫而不解析符號連結，因此這些拼寫未被阻止，透過符號連結路由的寫入可能會落在共享簽出中。 該怎麼做：
  • 通常什麼都不做：完整訊息作為工具錯誤傳遞給 Claude，Claude 使用它命名的直接路徑重試。對於被阻止的檔案編輯，對話檢視只顯示簡短的 Error editing file 行；完整訊息出現在逐字稿檢視中，您可以使用 Ctrl+O 開啟。被阻止的命令在其命令輸出中列印它。
  • 如果同一檔案上的阻止重複，路徑可能透過已提交的符號連結執行，其目標包含 ..，例如 docs/current -> ../README.md；要求 Claude 透過其真實路徑編輯目標檔案，而不是透過連結

​
寫入或命令被阻止，因為路徑命名網路位置

Claude 透過命名不在您機器上的磁碟機、UNC 共享（例如 \\server\share\file）或 /net 自動掛載路徑的路徑來定址檔案或工作目錄，而工作階段的簽出在本機磁碟上。相同的 worktree 隔離防護無法驗證這樣的路徑保持在共享簽出之外，因此它會阻止操作。在 worktree 中隔離工作階段不會解除阻止。訊息命名要改用的路徑形式：
被阻止的命令報告其工作目錄的相同原因，並以 re-run the command from its local, plainly-spelled path 結尾。在 v2.1.217 之前，防護只比較路徑文字，因此透過 UNC 或 /net 路徑定址簽出內的檔案未被阻止。 該怎麼做：
  • 通常什麼都不做：Claude 使用訊息要求的本機拼寫重試

​
命令被 worktree 隔離檢查阻止

Claude 在在 worktree 中隔離的工作階段中執行了 Bash、PowerShell 或 Monitor 命令，Claude Code 因以下原因之一拒絕了它：
  • 命令將在主簽出或另一個 worktree 中執行。訊息會說明其工作目錄 resolved to the shared checkout 或 is in a different worktree。
  • Bash 或 Monitor 命令將 git 指向主簽出。
  • Claude Code 無法從 Bash 或 Monitor 命令的文字驗證命令執行的任何 git 保持在 worktree 內。從未提及 git 的命令仍然可能因此原因被拒絕，因為展開變數間接參照（例如 ${!name}）或執行 Bash 函數替換（例如 ${ command; }）會產生在執行時本身可能是命令的值。
訊息會顯示 is isolated in the worktree <path>, but this command，後接原因，例如 Claude Code 無法驗證其文字的命令：
該怎麼做：
  • Git 指向主簽出，或無法驗證的命令文字：什麼都不做。Claude 讀取訊息並按其最後一句要求的方式重寫命令。如果您要求的命令因其文字中的展開而持續被拒絕，請按字面拼寫標記的值，並從 worktree 內將 git 作為獨立的純命令執行
  • 要刻意作用於主簽出，請在工作階段外的終端機中自己執行命令

​
This session has no saved transcript

您附加到一個您以 ← 或 /background 移至背景、且在執行自己的任何一個回合之前就已停止的工作階段。Claude Code 找不到您將其移出的那個對話，因此該工作階段沒有可繼續的內容。訊息以此工作階段的 claude respawn 命令結尾：
在 agent 檢視中開啟相同工作階段的列，會改為在清單下方顯示 Press enter again to restart this session fresh，在該列上第二次按 Enter 會使用空白對話重新啟動工作階段。 該怎麼做：
  • 若要全新重新啟動已停止的工作階段，請使用訊息中的 ID 執行 claude respawn <id>，或在 agent 檢視中的其列上按 Enter 兩次
  • 如果工作階段確實完成了回應，而您在 v2.1.214 之前的版本上仍看到此拒絕，~/.claude/projects 中的不可讀資料夾可能會使逐字稿掃描遺漏已儲存的對話；請更新到 v2.1.214 或更新版本，其在掃描期間容許不可讀資料夾

​
This session is running in another terminal

您在 agent 檢視中開啟了已停止工作階段的列，而其已儲存的對話已在此機器上的另一個執行中 Claude Code 程序中開啟，因此 Claude Code 拒絕啟動將寫入相同逐字稿的第二個程序。您看到的訊息取決於持有該對話的是什麼：
  • running in another terminal：終端機持有該對話，例如您使用 claude --resume 或 /resume 繼續它的終端機。列也會顯示 Open in a terminal。
  • already open in another running Claude session：另一個非互動式 Claude Code 程序持有它，例如相同對話中尚未退出的背景工作階段程序。
該怎麼做：
  • 在開啟該對話的程序中繼續對話，或退出該程序並再次開啟列
在 v2.1.248 之前，只有 already open in another running Claude session 拒絕存在：在終端機中繼續的對話不計為開啟，開啟列會啟動寫入相同對話的第二個 Claude Code 程序。

​
This session’s saved conversation is no longer on disk

您開啟了在背景服務關閉時結束的背景工作階段，而逐字稿清理已移除其已儲存的對話，例如在機器關閉數週後。通常開啟這樣的列會繼續其已儲存的對話。由於沒有可繼續的內容，Claude Code 會拒絕，而不是在不詢問的情況下重新執行工作階段的原始提示詞：
claude attach <id> 列印此文字。在 agent 檢視中，頁腳較短，以 ctrl+x deletes the row 結尾。 該怎麼做：
  • 執行 claude rm <id> 刪除列。當其中一個保留案例適用時，claude rm 會改為保留列和 worktree，並說明原因
  • 要將工作階段的原始提示詞作為新對話再次執行，請執行 claude respawn <id>
在 v2.1.248 之前，開啟這樣的列會重新執行工作階段的原始提示詞，而不是拒絕，將數週前的任務拉回前景。

​
Worktree 有未推送到任何地方的提交

您嘗試刪除背景工作階段，其 worktree 包含 Claude Code 無法確認已在其他地方儲存的提交。Claude Code 保留 worktree 和工作階段列，而不是在您未察覺的情況下銷毀提交。claude rm 命名分支和未推送的提交，並說明如何進行：
當 Claude Code 無法總結提交時，詳細行改為顯示 The worktree has unpushed commits。在 agent 檢視中，工作階段的列顯示 not deleted，原因相同。 遠端上的提交不會阻止刪除。您的 origin 遠端預設分支的本機副本上的提交也不會，只要該分支在您的主簽出（即儲存庫目錄本身而不是 worktree）中簽出。 該怎麼做：
  • 要保留提交，推送 worktree 的分支，或將其合併到在主簽出中簽出的預設分支，然後再次刪除工作階段
  • 要捨棄提交，執行訊息列印的 claude rm <id> --discard-unpushed 命令，或在 agent 檢視中的工作階段列上再次按 Ctrl+X 兩次。這會移除工作階段和 worktree 以及其分支、未推送的提交和任何未提交的變更。如果 worktree 自拒絕以來新增了提交，Claude Code 會再次保留它並顯示更新的狀態
  • 當訊息說 worktree 也由另一個已完成的工作階段記錄時，再次刪除不會捨棄它：推送提交，然後再次刪除工作階段
在 v2.1.268 之前，claude rm 將提交摘要放在 kept 行本身上。當 claude rm 無法總結提交時，kept 行會以 worktree has commits that are not pushed anywhere 代替摘要。 在 v2.1.260 之前，訊息未命名分支或提交，再次刪除也會以相同方式被拒絕：不推送而刪除工作階段意味著您必須使用 git worktree remove --force <path> 自己移除 worktree，然後再次執行 claude rm <id>。 在 v2.1.248 之前，在主簽出中簽出的預設分支不計算在內：您已經合併到那裡的分支仍然會觸發此拒絕，直到其提交到達遠端。

​
Terminal host process died

每個背景工作階段的終端機在背景服務下的主機程序中執行，該程序在服務仍保持其連線時死亡，因此無法連線到工作階段。 在 Linux 和 WSL 上，背景服務每隔幾秒檢查每個主機程序，當程序已退出但其與服務的連線從未關閉時，將工作階段標記為失敗，並在 agent 檢視中的其列上顯示原因：
從 shell，claude attach <id> 會重新啟動已因主機死亡而標記為失敗的工作階段，否則列印原因並退出：
無論哪種情況，對話都會儲存。 執行 shell 命令的列改為顯示 terminal host process died — its output is gone; the command was not run again，claude attach 列印 This command's terminal host process died — its output is gone and the command was not run again。Claude Code 永遠不會為您重新執行命令。 該怎麼做：
  • 在 agent 檢視中，在失敗的列上按 Enter；工作階段在新主機程序上重新啟動，對話繼續
  • 從 shell，再次執行 claude attach <id>。Claude Code 列印 Session <id>'s terminal host died — restarting it on a fresh one… 並重新開啟工作階段
  • 您無法以這種方式重新啟動 shell 命令列；再次分派命令以重新執行它
在 v2.1.247 之前，已死亡的主機程序可能通過背景服務執行的每個活躍性檢查，因此開啟工作階段會無限期地顯示 opening… · esc to cancel，而 claude attach <id> 會等待而不報告錯誤。

​
Session isn’t responding

您開啟了背景工作階段，背景服務接受了開啟，但約十秒內沒有輸出到達，因此 Claude Code 判定中繼工作階段終端機的程序無法傳遞輸出，並結束嘗試而不是繼續等待。 在 agent 檢視中，Claude Code 在頁腳中提供重新啟動：
從 shell，claude attach <id> 列印原因並退出：
Claude Code 永遠不會為您重新啟動執行 shell 命令的列，因為重新啟動會再次執行命令。 該怎麼做：
  • 在 agent 檢視中，在相同列上再次按 Enter。Claude Code 停止無回應的程序並重新啟動工作階段，對話繼續。沒有第二次按下，什麼都不會停止
  • 從 shell，執行 claude stop <id>，然後 claude attach <id>
  • 對於 shell 命令列，在 agent 檢視中按 Ctrl+X 或執行 claude stop <id> 停止它；再次分派命令以重新執行它

​
Session was stopped while the respawn was in flight

您開啟了背景工作階段，其程序未執行，而當 Claude Code 重新啟動它時，另一個 Claude Code 程序停止了它，例如在另一個終端機中的 claude stop。Claude Code 保持工作階段停止：
開啟您剛分派、其程序仍在啟動中的工作階段時，會改為等待該程序。在 v2.1.246 之前，在那一刻開啟它可能會停止它並顯示此訊息。 該怎麼做：
  • 如果您沒有停止工作階段，在 agent 檢視中再次開啟其列或執行 claude respawn <id> 重新啟動它
  • 如果您自己停止了它，就不需要再做任何事：工作階段保持停止

​
工作階段 agent 不再可用

您繼續了一個執行自訂 agent 的工作階段（使用 --agent 或 agent 設定啟動），而 Claude Code 未找到該名稱的 agent。當您已信任該工作區時，它會先搜尋工作階段的原始目錄，然後搜尋您繼續時所在的目錄。工作階段仍然會繼續，但使用預設工具，因此 agent 的工具限制不再適用：
警告只列出 Claude Code 搜尋過的目錄，無論您是喚醒背景工作階段、執行 /resume 或 claude --resume，還是在非互動模式中繼續，它都會出現在繼續的對話中；在非互動模式中它也會輸出到 stderr。使用 --input-format stream-json 的工作階段不會顯示它，因為 Agent SDK 在啟動後才提供 agent。 Claude Code 不會將此備援儲存到工作階段，因此警告會在每次繼續時重複出現，直到您採取行動。內建 claude agent 不會觸發警告，因為改用預設工具集對它沒有任何變化。在 v2.1.216 之前，Claude Code 會無聲地以預設 agent 繼續，且查詢僅涵蓋您繼續時所在的目錄，因此從另一個目錄繼續時，專案範圍的 agent 就會遺失。 該怎麼做：
  • 在工作階段專案中的 .claude/agents/<name>.md，或針對個人 agent 在 ~/.claude/agents/<name>.md 重新建立 agent 檔案，然後再次繼續
  • 或使用 --agent <name> 繼續，指定確實存在的 agent，以改為作為該 agent 執行工作階段
  • 如果 agent 是專案範圍的，而您尚未信任工作階段的原始目錄，請在那裡執行 Claude Code 一次，接受信任對話框，然後再次繼續

​
This session restarted after its next /loop wakeup was due

背景工作階段中的自行調節步調的 /loop 已停止。工作階段的程序在迴圈等待下一次喚醒時結束，而該次喚醒在工作階段的下一個程序啟動之前就已到期。錯過的喚醒不會延遲觸發。通知會說明工作階段重新啟動時該次喚醒已逾期多久：
在 v2.1.295 之前，迴圈在此情況下會停止而不顯示通知。 該怎麼做：
  • 若要繼續迴圈，請回覆該工作階段並如此說明，例如 keep the loop running。Claude 會連同您的回覆一起讀取通知，並可以排程下一次喚醒
  • 如果您已不需要該迴圈，則什麼都不用做。它已經停止

​
CLAUDE_CODE_PROCESS_WRAPPER 啟動器錯誤

CLAUDE_CODE_PROCESS_WRAPPER 已設定，但其值無法使用，因此 Claude Code 拒絕啟動受影響的程序，而不是在沒有啟動器的情況下執行它。設定問題會以變數名稱開頭並說明原因的訊息報告，例如：
啟動後未以 Claude Code 替換自己就退出的啟動器，會使其正在啟動的工作階段失敗，該工作階段在 agent 檢視中的列會報告啟動器 must exec, not daemonize，後接啟動器列印的任何內容。因啟動器而無法啟動或無法連線到背景服務的工作階段，會將啟動器問題作為 Couldn't reach the background service (...) 內的原因報告。 該怎麼做：
  • 將變數設定為以呼叫 exec "$@" 結尾的可執行檔的絕對路徑。有關完整合約，請參閱啟動器合約
  • 檢查 /status，其在 Self-exec 項目中顯示已解析的啟動命令，並在執行中的背景服務不符合時發出警告，或從 shell 執行 claude daemon status
  • 在設定的 env 區塊中修正值後，使用 claude daemon stop --any 重新啟動背景服務，以便下次分派時啟動經過包裝的服務

​
啟動背景工作階段時 EUNKNOWN

Windows 以沒有標準名稱的錯誤代碼拒絕啟動程式，因此失敗表現為 EUNKNOWN。通常的觸發原因是軟體限制原則（例如群組原則或 AppLocker）阻止正在啟動的程式。當您使用 /background 或 claude --bg 啟動背景工作階段時，會出現此錯誤：
在某些帳戶上，訊息會以 daemon 取代 background service。 在 npm 安裝上，在 npm install -g @anthropic-ai/claude-code 替換二進位檔案時出現的 EUNKNOWN 與重新安裝期間的 EACCES 有相同的原因，並會在安裝完成後重試時消除。 Claude Code 透過 PowerShell 啟動背景服務，以便服務在關閉終端機後仍能存活；已安裝 PowerShell 7 時使用它，否則使用 Windows PowerShell 5.1。當兩個 PowerShell 都無法執行時，Claude Code 改為直接啟動服務，因此只阻止 PowerShell 的原則不會導致此錯誤。 在 v2.1.212 之前，Claude Code 僅使用 Windows PowerShell 5.1 啟動服務，因此任何群組原則阻止 PowerShell 5.1 的機器都會失敗，訊息為 Couldn't start the session — EUNKNOWN: unknown error, uv_spawn，即使已安裝 PowerShell 7 也是如此。 該怎麼做：
  • 如果訊息顯示 Couldn't start the session，請升級到 v2.1.212 或更新版本。在較早的版本上，您也可以先在另一個終端機中執行 claude daemon run，然後再次啟動背景工作階段。該命令在終端機的前景中執行背景服務，因此服務僅在該終端機保持開啟時持續運作。
  • 如果 npm 安裝正在替換二進位檔案，請等待它完成，然後再次啟動背景工作階段
  • 如果錯誤在 v2.1.212 或更新版本上出現，且沒有 npm 安裝正在執行，請向您的 Windows 管理員確認是否有限制原則阻止 Claude Code 可執行檔
  • 如果關閉終端機時背景服務停止，表示 Claude Code 是在沒有 PowerShell 的情況下啟動它的。請安裝 PowerShell 7，或要求您的管理員解除對 PowerShell 的阻止，以便服務可以在終端機關閉後繼續運作。

​
啟動背景工作階段時 EACCES

Claude Code 無法執行其自己的二進位檔案來啟動託管背景工作階段的背景服務。在 npm 安裝上，這通常意味著 npm install -g @anthropic-ai/claude-code 在那一刻正在替換二進位檔案，無論是您執行的還是自動更新程式執行的。當您從 agent 檢視開啟工作階段時，會出現此錯誤：
當您使用 /background 或 claude --bg 啟動工作階段時，相同的原因出現在 Couldn't reach the background service (...) 內。在相同的重新安裝期間，錯誤可能改為顯示另一個代碼，例如 ENOENT 或 ENOEXEC，或 Windows 上的 EUNKNOWN 或 EPERM；在多次重試後仍持續的 EUNKNOWN 有不同的原因。 在 npm 安裝上，Claude Code 會等待重新安裝完成並自動重試：最多十秒，而當機器上明顯仍有 Claude Code 的 npm 安裝在執行時最多兩分鐘，這涵蓋了另一個 Claude Code 程序正在下載更新的情況。當安裝超過該等待時間時，失敗訊息會提及更新，而不是單純的錯誤代碼：
在 v2.1.257 之前，等待在所有情況下都在十秒停止，因此此錯誤會在另一個 Claude Code 程序仍在下載更新時出現。在 v2.1.246 之前，Claude Code 會立即失敗，不會等待。 該怎麼做：
  • 等待幾秒，然後開啟工作階段或再次分派。當訊息說 Claude Code 正在更新時，請在更新完成後重試。
  • 如果錯誤在沒有 npm 安裝執行時持續，表示您的使用者無法執行已安裝的二進位檔案。請檢查其權限及其目錄的權限，或重新安裝 Claude Code。

​
背景服務在可連線之前退出

Claude Code 作為背景服務啟動的程序在接受連線之前就退出了，因此 Claude Code 無法開啟您的工作階段。當服務在退出前列印了錯誤時，括號中的原因會提供退出碼或訊號以及服務列印的第一行，該行指出使其停止的原因：
當您從 agent 檢視開啟工作階段時，相同的原因接在 Couldn't start the background service — 之後。當服務在退出前未列印任何內容時，訊息改為顯示 nothing on stderr。 Claude Code 會連同服務的錯誤行一起報告失敗。在 v2.1.246 之前，失敗僅在等待 45 秒後才以 background service did not become reachable within 45s 的形式出現，且不含服務的錯誤行。 兩種引用的原因有已知的成因：
  • Error: claude native binary not installed.：npm 安裝在那一刻正在替換 Claude Code 二進位檔案，因此服務執行了 npm 的佔位檔。請在安裝完成後重試；如果在沒有安裝執行時該行仍持續出現，請完成 npm 安裝。在 v2.1.257 之前，macOS 上的 npm 自我更新會在安裝期間的每次啟動時產生此失敗。
  • Windows 上每次啟動時都出現 nothing on stderr 且退出碼為 1：daemon.lock 指向一個 Claude Code 既無法傳送訊號、也無法證明已消失的程序，因此每個新服務都判定另一個服務持有鎖定並退出。Claude Code 能證明其寫入者已消失的鎖定會自動被替換，不會產生此失敗。當失敗在每次啟動時重複出現時，請刪除 ~/.claude/daemon.lock，然後開啟工作階段或再次分派。在 v2.1.257 之前，這樣的鎖定會阻止每次啟動，直到您刪除該檔案。
該怎麼做：
  • 如果訊息引用了一行，請修正其指出的問題，然後開啟工作階段或再次分派。下次嘗試會再次啟動服務
  • 執行 claude daemon status 檢查現在是否有服務正在執行

​
啟動背景工作階段時工作目錄不再存在

您啟動背景工作階段時所在的目錄在工作階段啟動期間被移除。Claude Code 不會啟動工作階段，訊息會指出遺失的目錄：
在 v2.1.257 之前，工作階段看似已啟動，然後在 agent 檢視中顯示為失敗列，原因相同。 在 v2.1.281 之前，當目錄在您啟動工作階段之前就已消失時，也會出現此訊息。該情況會報告 could not be resolved on disk。 該怎麼做：
  • 重新建立訊息指出的目錄，或從存在的目錄分派，然後再試一次

​
分派背景工作階段時工作區未信任

您在尚未信任的目錄中啟動或重新啟動背景工作階段，而工作區信任對話框無法出現來詢問您。Claude Code 不會啟動工作階段：
若從工作階段自己目錄中的終端機執行，相同的命令會改為顯示信任對話框，並在您接受後啟動工作階段。此訊息出現在無法顯示對話框的地方，例如在指令碼中，或當您從非其自身的目錄重新啟動工作階段時。 兩種變體指出不同的原因：
  • The home directory is trusted one session at a time：工作階段的目錄是您的家目錄。Claude Code 永遠不會儲存家目錄的信任，因此在較早的工作階段中於該處接受對話框並不算數。
  • <path> could not be resolved on disk：Claude Code 無法在磁碟上找到工作階段的目錄。
在 v2.1.286 之前，在 Windows 上，如果信任記錄儲存時路徑的大小寫不同，此訊息也可能出現在您已信任的目錄中。請更新到 v2.1.286 或更新版本。 該怎麼做：
  • 在訊息指出的目錄中執行 claude 並接受信任對話框，然後再次執行命令
  • 對於家目錄訊息，請從家目錄中的終端機執行命令，以便對話框可以出現，或改為從專案目錄啟動工作階段
  • 對於 could not be resolved on disk 訊息，請重新建立目錄，或從存在的目錄啟動新工作階段

​
包裝程式和 IDE 錯誤

這些錯誤來自啟動 Claude Code 的程式，例如 IDE 擴充功能或 Agent SDK 應用程式，而不是來自 Claude Code 本身。

​
Claude Code 程序以代碼 N 結束

底層 claude 程序以非零代碼結束。結束代碼本身不會說明失敗的原因：真正的錯誤在於程序自己的輸出，包裝程式會在捕獲時附加該輸出，否則將其保留在日誌中。
在 Windows 上，原生組建可能在轉換完成後立即以代碼 4294967295 結束。當該結束發生在轉換邊界，沒有訊息等待且沒有背景工作執行時，VS Code 擴充功能會安靜地關閉工作階段，而不是顯示此錯誤。您的下一條訊息會繼續對話。 在 v2.1.273 之前，擴充功能在每個轉換邊界都會顯示該結束的錯誤，即使沒有任何內容遺失。 該怎麼做：
  • 在 VS Code 中，按照錯誤顯示的檢視輸出日誌連結查看底層失敗
  • 在 Agent SDK 應用程式中，在訊息迴圈周圍捕獲錯誤。CLI 程序結束下的項目涵蓋了您的程式碼在每個 SDK 語言中接收的內容。
  • 在終端機中的同一專案中執行 claude。失敗通常會在那裡重現，並顯示其真實錯誤訊息，您可以在此頁面上查詢。
  • 在終端機中執行 claude doctor 以檢查安裝和設定

​
無法在 PATH 上找到 Claude CLI

當您在整合終端機中開啟 Claude Code、終端機的殼層是 PowerShell，且擴充功能無法在 PATH 上找到已安裝的 claude 可執行檔時，VS Code 擴充功能會在 Windows 上顯示此錯誤。擴充功能拒絕啟動 Claude Code，直到它在 PATH 上找到已安裝的 claude。
該怎麼做：
  • 在 VS Code 外開啟新的 PowerShell 視窗並執行 where.exe claude。如果它沒有列印路徑，CLI 不在您的 PATH 上：按照驗證您的 PATH新增其安裝目錄。如果它列印了路徑，該項目來自您的 PowerShell 設定檔或來自 VS Code 尚未取得的 PATH 變更；接下來的兩個步驟涵蓋了這些情況。
  • 將 PATH 項目設定為使用者或系統環境變數，而不是在您的 PowerShell 設定檔中。擴充功能不執行您的設定檔，因此只存在於那裡的 PATH 編輯永遠無法到達它。
  • 變更 PATH 後重新啟動 VS Code。擴充功能檢查 VS Code 在啟動時捕獲的 PATH，因此 PATH 變更只有在重新啟動後才會生效。

​
Claude Code 的連線在此訊息完成前結束

VS Code 擴充功能將您的訊息傳送到 claude 程序，連線在程序確認或完成訊息之前結束，且沒有錯誤。擴充功能無法判斷訊息是否已被處理，因此它要求您再次傳送訊息：
該怎麼做：
  • 再次傳送訊息。下一條訊息會啟動一個新的 claude 程序，繼續對話。
  • 如果它重複發生，在同一專案中的終端機中執行 claude。持續結束程序的失敗通常會在那裡重現，並顯示其真實錯誤訊息。

​
Rewind 警告和錯誤

這些訊息來自 /rewind 程式碼還原。Restored the code, but skipped N files 是一個警告，表示 Claude Code 跳過了某些路徑。No files were restored 是一個錯誤，表示它沒有還原任何內容。

​
Restored the code, but skipped files

/rewind 程式碼還原跳過了一個或多個追蹤的路徑，而不是透過它們進行寫入或刪除。Claude Code 在以下情況下會跳過路徑：
  • 它是或已成為符號連結、硬連結或其他非一般檔案
  • 其目錄自檢查點以來已變更
  • 其備份無法安全讀取
跳過的路徑保留其目前的內容。在 v2.1.216 之前，/rewind 會透過追蹤路徑上的連結進行寫入和刪除，並且不會報告部分還原。
該怎麼做：
  • 識別哪些檔案被跳過，以便您可以使用下面的步驟處理每個檔案。訊息只提供計數；位於 ~/.claude/debug/<session-id>.txt 的偵錯日誌會在還原執行時列出每個跳過的路徑，因此在下次還原之前使用 /debug 開啟偵錯日誌。在 macOS 或 Linux 上，您可以改為直接找到連結：find . -type l 用於符號連結，find . -type f -links +1 用於硬連結檔案。
  • 如果跳過的檔案是您有意建立的連結，例如由 dotfile 管理器管理的設定檔或由 pnpm 等工具硬連結的檔案，rewind 會保留其內容不變。若要復原工作階段對其所做的變更，請要求 Claude 反轉編輯或自行編輯檔案
  • 如果您沒有建立連結，請在信任其內容之前檢查路徑

​
No files were restored

當您使用 /rewind 還原程式碼，且無法還原該檢查點中的任何檔案時，Claude Code 會顯示此訊息。對於每個檔案，Claude Code 在編輯前儲存的備份遺失，或 Claude Code 無法寫入或刪除該檔案。
Claude Code 在保留掃描中刪除工作階段的備份，預設情況下約在工作階段最後一次儲存後 30 天。如果您在之後恢復工作階段，/rewind 仍會列出其檢查點，但還原到其中一個可能會因此錯誤而失敗。如果訊息還說 N paths were skipped for link safety，請參閱Restored the code, but skipped files 以了解這些路徑。 當您分支工作階段時，例如使用 --fork-session 或 /branch，Claude Code 會將原始工作階段的備份複製到分支中。當 Claude Code 無法複製備份時，例如因為磁碟已滿，該備份在分支中遺失。還原到需要它的檢查點可能會因此錯誤而失敗。 該怎麼做：
  • 以其他方式復原變更：要求 Claude 反轉其編輯，或從版本控制還原檔案。當備份消失時，再次執行 /rewind 會以相同方式失敗。
  • 如果 Claude Code 無法寫入或刪除檔案，請修復阻止寫入的問題，例如檔案權限，然後再次執行 /rewind。
  • 若要在未來的工作階段中保留備份更長時間，請提高 cleanupPeriodDays。
在 v2.1.260 之前，Claude Code 會無聲地跳過備份遺失的檔案，還原似乎成功。

​
工作階段儲存警告

Claude Code 在輸入框下方的持續行上顯示這些警告，當它未儲存您的工作階段文字記錄時。無論哪種方式，工作階段都會繼續運作；警告告訴您工作階段稍後可能會在 --resume 中遺失。

​
文字記錄寫入失敗

Claude Code 在您工作時將文字記錄儲存到磁碟，其對文字記錄檔案的寫入失敗。該訊息以基礎錯誤代碼命名原因，例如磁碟已滿：
警告根據錯誤在不同時間點出現：
  • 在不會自行清除的條件首次失敗時：磁碟已滿、超過磁碟配額、檔案系統唯讀、路徑超過檔案系統長度限制，或在 macOS 和 Linux 上，權限錯誤
  • 在至少跨越一分鐘的重複失敗後，包括 Windows 上的權限錯誤，其中防毒軟體掃描可能會導致單次寫入失敗，然後在重試時成功
在 v2.1.217 之前，Claude Code 會在沒有警告的情況下放棄失敗的寫入，稍後 --resume 遺失最近訊息是第一個跡象。 該怎麼做：
  • 修復錯誤代碼命名的條件：為 ENOSPC 釋放磁碟空間；為 EDQUOT 提高或清除配額；為 EACCES、EPERM 或 EROFS 恢復文字記錄位置的寫入存取
  • 警告在下一次成功寫入時自動清除；不需要重新啟動
  • 在警告顯示時傳送的訊息稍後恢復工作階段時可能仍會遺失

​
因為設定了 CLAUDE_CODE_SKIP_PROMPT_HISTORY 所以文字記錄儲存已關閉

此工作階段啟動時設定了 CLAUDE_CODE_SKIP_PROMPT_HISTORY，因此 Claude Code 不會為其寫入文字記錄或提示歷史記錄：
該變數是針對暫時性指令碼工作階段的有意選擇退出，但它也可以透過殼層設定檔、包裝指令碼或匯出它的父程序到達工作階段。 該怎麼做：
  • 如果您有意設定該變數，不需要採取任何行動；該通知確認工作階段不會出現在 --resume、--continue 或向上箭頭歷史記錄中
  • 如果您沒有，請從啟動 claude 的殼層或指令碼中移除該變數，然後啟動新工作階段。目前工作階段的訊息不會被追溯儲存。

​
因為繼承了 CLAUDE_CODE_CHILD_SESSION 標記所以文字記錄儲存已關閉

Claude Code 在它產生的子程序中設定 CLAUDE_CODE_CHILD_SESSION，並將繼承它的互動式工作階段視為巢狀：Claude Code 不會為其儲存文字記錄，因此 Claude 本身啟動的工作階段不會填滿您的 --resume 清單。此通知表示您目前的工作階段繼承了該標記：
當您從另一個 Claude Code 工作階段內執行 claude 時，該通知是預期的；當標記透過長期存在的中介（例如終端機、screen 工作階段或 Claude Code 工作階段原本啟動的啟動器）洩漏時，它會發出誤分類的訊號。 在 tmux 內，Claude Code 會偵測透過 tmux 伺服器全域環境到達的標記，並繼續儲存，因此該通知不會出現在該情況下。 該怎麼做：
  • 如果您有意從另一個 Claude Code 工作階段內啟動此工作階段，不需要採取任何行動
  • 如果這是頂層工作階段，請結束並使用設定的 CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1 重新啟動。儲存從重新啟動時開始套用，因此在此之前傳送的訊息不會被儲存。
  • 若要修復從相同終端機或啟動器的未來啟動，請從其環境中移除 CLAUDE_CODE_CHILD_SESSION

​
設定警告

Claude Code 會將這些訊息大多寫入 stderr，而非寫入對話中，且大多在啟動時寫入。若某個項目的訊息出現在其他位置（例如除錯日誌中，或在對話檢視中作為啟動通知），或出現在其他時間點（例如在請求時出現的無法辨識模型診斷行），該項目會加以說明。

​
Claude Code exited after an unrecoverable interface error

當 Claude Code 的終端機介面遇到無法復原的錯誤而結束時，無論使用哪一種渲染器，Claude Code 都會印出此訊息。只有在錯誤發生於 fullscreen 渲染器啟動期間時，才會出現第二句：
處理方式：
  • 重新啟動 Claude Code。若要接續先前的對話，請在相同目錄中執行 claude --resume。
  • 若訊息提及 fullscreen 渲染器，全螢幕渲染說明了下次啟動時的行為（取決於您開啟全螢幕的方式），以及如何再次嘗試全螢幕或保留經典渲染器。
在 v2.1.236 之前，Claude Code 遇到這類錯誤後會直接結束，不會印出任何訊息。

​
Agent descriptions are over the 15.0k-token limit

Claude Code 會在對話檢視中以啟動通知的形式顯示此警告，而非寫入 stderr。您的 subagent（內建的除外）合計的描述內容，依 Claude Code 的估算超過 15,000 個 token。每個 agent 計入的是其名稱加上其 description frontmatter。無論總量是否超過上限，Claude Code 都會載入每個 agent，因此此警告不會改變載入的內容。
處理方式：
  • 縮短您 agent 檔案中的 description frontmatter，或請 Claude 為您精簡。
  • 移除您不再使用的 agent 檔案。

​
Hook needs quotes around a path with a space

對話檢視中的此通知表示某個 hook 的腳本未執行，因為其路徑含有空格且未加上引號。該 hook 是 shell 形式的 asyncRewake hook。在其 command 中，python3 之類的直譯器後面接著未加引號的路徑預留位置，而解析後的路徑包含空格。 通知開頭為該 hook 的事件名稱，並指出腳本名稱：
處理方式：
  • 在執行通知所指腳本之 hook 的 command 中，以雙引號包住路徑。在 JSON 檔案中，請寫成 "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/check.py\""。

​
Instruction file not loaded

互動式工作階段對話檢視中的此通知，表示某個存在的記憶檔案未被載入。有一項讀取限制正在生效。
括號內容會指出原因，例如：
  • a Read deny rule covers it：某條 Read 拒絕規則符合該檔案所寫的路徑，或其上的連結所指向的位置
  • it's read from outside your working directories, where reads are blocked：在 permissions.blockReadsOutsideWorkingDirectories 開啟的情況下，該檔案解析到的位置在工作目錄之外
  • where it leads couldn't be worked out：例如，該檔案是直接或透過其他連結指回自身的連結
當 Claude 處理某個子目錄中的檔案，而該子目錄本身的記憶檔案無法載入時，相同的行會在該回合中出現在對話裡。當被保留的檔案多於這些行所列出的數量時，最後一行會計算其餘的數量，例如 and 3 more instruction files not loaded。 處理方式：
  • 若此限制是刻意設定的，則無需處理：工作階段會在沒有該檔案指令的情況下執行。
  • 若要載入因 a Read deny rule covers it 而被保留的檔案，請移除或縮小該規則。然後啟動新的工作階段。
  • 若要載入因 it's read from outside your working directories, where reads are blocked 而被保留的檔案，請將該檔案或其連結目標移至工作目錄內。然後啟動新的工作階段。
  • 若要載入因 where it leads couldn't be worked out 而被保留的檔案，請檢查該檔案是否為指回自身的連結。若是，請將連結指向存在的檔案，或以一般檔案取代它。然後啟動新的工作階段。
在 v2.1.292 之前，此通知會在同一行中、原因之後的結尾處列出該檔案。

​
某個 skill、命令或工作流程因名稱為保留名稱而未載入

某個 skill 資料夾、frontmatter 的 name、.claude/commands/ 中的檔案或子資料夾，或某個已儲存的工作流程使用了 anthropic-skills 這個名稱，或以 anthropic-skills: 開頭的名稱。Claude Code 將該名稱保留給從 claude.ai 同步的 skill，因此不會載入該項目。 Claude Code 會在對話檢視中以啟動通知的形式顯示此警告，而非寫入 stderr：
此通知會針對第一個被拒絕的項目指出需要變更的內容：要重新命名的資料夾或檔案、要編輯的 name: 行，或要重新命名的工作流程。當有多個項目被拒絕時，通知結尾會附上數量，例如 · 2 more，而除錯日誌會列出每一個項目。 處理方式：
  • 重新命名通知所指的項目，或編輯其指向的 name: 行，然後重新啟動工作階段。
在 v2.1.282 之前，Claude Code 會載入使用這些名稱的 skill 和命令。

​
Skill or command name refused

此啟動通知表示 Claude Code 拒絕了至少一個 skill 或自訂命令的名稱，因此該項目未載入，或在未套用其 name 欄位的情況下載入：
  • 未載入：Claude Code 拒絕了 skill 或命令所使用的名稱，例如其目錄名稱，或命令檔案的名稱或子資料夾。該項目不會出現在 / 選單中，Claude 也無法呼叫它。其在除錯日誌中的行為 <name> is not offered。
  • 忽略 name 欄位：Claude Code 拒絕了某個 skill 的 frontmatter name。該 skill 仍會載入，但 / 選單不會顯示 name 的值，輸入該值也無法呼叫此 skill。其在除錯日誌中的行為 <name value> is not shown for <skill>。
處理方式：
  • 從您的 shell 以 claude --debug 啟動 Claude Code，並在除錯日誌中搜尋 [names]。通知所計入的每個名稱在那裡都有一行。該行會將部分隱藏字元以代碼形式寫出，例如以 \u{200B} 表示零寬度空格，讓您能看出它們的位置。
  • 透過重新命名資料夾或檔案，或編輯 name: 行，移除 skill 名稱不能包含的字元，或縮短超過 256 個字元的名稱。接著重新啟動工作階段，除非該檔案位於 Claude Code 會監看變更的目錄中。若是來自非您撰寫之外掛的 skill，請請外掛作者重新命名。

​
Workspace has not been trusted

Claude Code 在專案的 .claude/settings.json 或 .claude/settings.local.json 中找到 permissions.allow 規則或 permissions.additionalDirectories 項目，但未套用它們，因為來自專案設定的允許規則需要工作區信任。訊息中的數量、設定名稱及所列出的檔案會因您的設定而有所不同。deny 和 ask 規則不受影響。
處理方式：
  • 在該目錄中執行 claude 並接受信任對話框。專案允許規則與工作區信任說明了該次接受所涵蓋的資料夾。
  • 在搭配 -p 的非互動模式下不會顯示對話框。請使用訊息所印出的確切 projects 鍵，在 ~/.claude.json 中設定 hasTrustDialogAccepted 項目。
  • 若訊息提及 .claude/settings.local.json，且您是在 git 儲存庫之外或在家目錄中啟動 Claude Code，請更新至 v2.1.200 或更新版本。2.1.196 至 2.1.199 版在這些工作區中會將您自己的 .claude/settings.local.json 視為由儲存庫提供。在 v2.1.207 及更新版本中，若您尚未信任該資料夾，僅更新並不足以解決 git 儲存庫之外的情況：判斷資料夾不在儲存庫內需要執行 git，而 Claude Code 只會在您接受信任對話框後才執行該檢查，因此請使用第一個步驟。您的家目錄及任何其他設定主目錄不受此限制，無需等待對話框。請參閱專案允許規則與工作區信任。

​
工作目錄是網路路徑

Claude Code 不會將網路路徑加入為工作目錄。查詢網路路徑可能會連線到其所指定的主機，而在 Windows 上，該連線可能會將您的憑證傳送給該主機，因此 Claude Code 會在不查詢的情況下直接拒絕該路徑。當您以此類路徑執行 /add-dir 時，或在啟動時以警告形式，您會看到此訊息。若在啟動時出現，Claude Code 會在不包含該目錄的情況下啟動。
Claude Code 以此方式拒絕的路徑包括：
  • UNC 共用，例如 \\server\share
  • 自動掛載路徑，例如 /net/<host>，除非您是從該主機自動掛載下的目錄啟動 Claude Code。在該自動掛載下的讀取仍會經過網路路徑檢查。
  • 透過符號連結或 junction 連到網路位置的本機路徑
對應的磁碟機代號和 \\wsl$ 路徑不算網路路徑。 處理方式：
  • 在 Windows 上，將共用對應到磁碟機代號，例如使用 net use Z: \\server\share，並在啟動時以 claude --add-dir Z:\ 傳入該磁碟機。
  • 在 macOS 或 Linux 上，將共用掛載到本機路徑，改為加入該路徑。
  • 若該路徑位於 permissions.additionalDirectories 中，請從列出它的設定檔中移除。
在 v2.1.257 之前，Claude Code 會接受可連線的網路路徑作為工作目錄。

​
Remote managed settings failed to load

您的工作階段符合使用伺服器管理設定的資格，但 Claude Code 無法擷取這些設定，或無法套用伺服器回傳的內容，因此會在互動式工作階段中顯示此警告。 括號內的原因會指出失敗的項目，例如 network error、request timed out 或 authentication rejected (401)。原因 no setting in the server response could be applied as written 表示伺服器有回應，但其回傳的設定沒有任何一項通過驗證。在 v2.1.282 之前，此原因顯示為 server returned invalid settings。 該行其餘部分會說明工作階段所依循的政策：
  • 有先前成功擷取時快取的設定：Claude Code 會以該快取政策執行工作階段（保留的環境變數除外），該行顯示 using cached policy。
  • 沒有快取：Claude Code 會在沒有伺服器管理設定的情況下執行工作階段，該行顯示 no remote policy applied。
處理方式：
  • 針對訊息所指的原因採取行動：若為網路原因，請確認此機器能連線到 api.anthropic.com；若為身分驗證原因，請以 /status 檢查您的登入狀態
  • 若為 no setting in the server response could be applied as written，請請您的管理員修正伺服器上的設定
  • 執行 /status 或 claude doctor 以取得完整診斷
在 v2.1.248 之前，Claude Code 只會在除錯日誌中回報設定擷取失敗。

​
Managed settings were not approved

您組織的伺服器管理設定包含需要您核准的設定，而您拒絕了安全性核准對話框，因此 Claude Code 會在不套用這些設定的情況下結束：
處理方式：
  • 重新啟動 Claude Code 並核准對話框，以在組織的設定下繼續使用。被拒絕的對話框不會被記住，因此下次啟動時會再次出現。
  • 若您不確定對話框中列出的某項設定，請在核准之前詢問負責維護組織受管設定的人員

​
受管設定封鎖了預設模型

您組織的受管設定封鎖了 Default 選項所解析到的模型，以及它可能降級使用的每一個模型。原本會以 Default 選項啟動的工作階段會在啟動時結束，而不會執行被封鎖的模型。您看到的訊息取決於封鎖它的設定。當 deniedModels 清單封鎖它時，訊息如下：
當 availableModelsMatch 設為 "exact" 的 availableModels 清單未包含它時，訊息如下：
處理方式：
  • 若您負責管理這些設定，請將使用者可以執行的模型加入 availableModels，或縮小封鎖每一個備援模型的 deniedModels 項目。封鎖特定模型或版本說明了 Default 選項的降級方式
  • 若您並未負責管理這些設定，請將訊息傳送給您的管理員。您自己的設定檔無法擴大受管的 availableModels 或 deniedModels 清單

​
受管設定不允許此 API 供應商

您組織的受管設定設定了 allowedProviders 清單，而工作階段的 API 供應商不在清單中，或工作階段使用的端點未依該項目要求的方式固定。Claude Code 會在啟動時、登入前，或在工作階段下次連線 API 時拒絕執行。訊息開頭會列出允許的供應商：
當清單為空時，訊息改為：
當每個項目都無法辨識時，括號內容改為 (allowedProviders lists only unrecognized entries)。 處理方式：
  • 依照訊息中 To continue: 的步驟操作
  • 若您負責管理這些設定，訊息中以 Admins: 開頭的行會指出要加入的項目或要固定的值，而 allowedProviders 項目說明了哪個來源的 env 區塊可以固定它

​
MCP server is blocked by enterprise managed policy

您在 /mcp 中對某個伺服器選擇了 Reconnect，或在那裡重新開啟了已停用的伺服器，而某項限制 MCP 伺服器的設定封鎖了該伺服器。Claude Code 會拒絕連線並顯示：
以下任一設定都可能產生此訊息： 處理方式：
  • 檢查您自己的使用者與專案設定檔中是否有上述設定，並加以變更或移除
  • 若您自己的設定都無法說明此封鎖，請詢問您的管理員是哪一項受管設定封鎖了該伺服器
在 v2.1.257 之前，/mcp 中的 Reconnect 和重新啟用可以連線到在工作階段中途因政策更新而被封鎖的伺服器。

​
MCP 伺服器名稱為保留名稱

此訊息會指出您的某個 MCP 伺服器，其名稱屬於 Claude Code 保留的名稱，例如其內建伺服器的名稱：
處理方式：
  • 在您定義該伺服器的位置重新命名，例如從 workspace 改為 my-workspace
  • 關於其他應避免的保留名稱，請參閱 MCP 設定警告

​
Managed settings document could not be parsed

您的組織部署了受管設定，而其中一份已部署的文件存在，但無法解析為 JSON 物件，因此 Claude Code 會在啟動時以代碼 1 結束，而不會在缺少該文件所含政策的情況下執行。該行會在訊息之前列出失敗的來源：
來源為下列其中之一：
  • managed-settings.json 檔案的路徑，或 managed-settings.d 下某個 drop-in 檔案的路徑
  • macOS 受管偏好設定描述檔，per-user managed preferences 或 device-level managed preferences
  • Windows 登錄值，Registry: HKLM\SOFTWARE\Policies\ClaudeCode\Settings
找出 Claude Code 捨棄的項目列出了導致各來源無法解析的原因。 即使另一個管理來源提供了有效的政策，Claude Code 仍會拒絕啟動。您會在互動式工作階段、claude -p、Agent SDK 工作階段、背景工作階段及大多數子命令（包括 claude doctor）中看到此錯誤。此拒絕刻意採取失敗即封閉的方式：Claude Code 無法解析之文件中的設定無法強制執行，若仍然啟動，工作階段將在缺少組織管控的情況下執行。 可解析文件中的 schema 問題不會產生此錯誤。找出 Claude Code 捨棄的項目說明了 Claude Code 對此類問題的處理方式。 當 managed-settings.d/ 目錄存在但無法列出內容時，Claude Code 會改為回報 Managed settings drop-in directory could not be read:，後面接著底層錯誤。找出 Claude Code 捨棄的項目說明了讀取失敗何時會導致啟動時結束。 處理方式：
  • 若您負責管理此機器，請修正所指的文件使其能解析為 JSON 物件，或移除該檔案、描述檔或登錄值。空的 managed-settings.json 會被視為 {}，不會阻擋啟動。
  • 若您並未負責管理，請請您的管理員修正已部署的文件。您自己設定檔中的任何內容都不會導致或消除此錯誤。

​
Unable to read managed policy settings

您的組織部署了受管設定，而其中一個已部署的來源存在但無法讀取，原因例如 I/O 錯誤，而非作業系統拒絕讀取。在沒有其他管理來源提供政策的情況下，Claude Code 會在啟動時結束，而不會在缺少該來源可能包含之政策的情況下執行：
在相同狀態下，登入流程、來自已在執行中之工作階段的 API 請求，以及 claude gateway 伺服器都會被拒絕，並顯示第一行的變體，其中會提及 allowedProviders。 被作業系統拒絕的讀取（例如針對僅限 root 的檔案）不會導致此結束：工作階段會在沒有該來源之政策的情況下啟動。對於無法解析的來源，Claude Code 會以另一則指出該來源的訊息結束。 處理方式：
  • 若您負責管理此機器，請修正 Detail: 行所指的問題，使已部署的來源能夠讀取，或移除該來源
  • 若您並未負責管理，請將訊息傳送給您的管理員。您自己設定檔中的任何內容都不會導致或消除此錯誤
在 v2.1.285 之前，只有以 claude.ai 或 Claude Console 憑證登入的工作階段會以此訊息結束，而被作業系統拒絕的讀取也會產生此訊息。

​
Managed settings contain invalid entries, including PreToolUse/PermissionRequest hooks that are NOT loaded

-p 執行所輸出的這段 stderr 區塊，表示某個受管設定來源包含 Claude Code 無法載入的 hook 項目。該 hook 不會執行；而當某一行將該來源的 hooks 欄位列為已忽略時，該來源的所有 hook 都不會執行。 每一行會列出來源、欄位（若有的話）以及問題，例如未知的 hook type，或在 hooks 鍵之外宣告的 hook：
處理方式：
  • 若您負責管理該來源，請修正或移除區塊中列出的每個項目。Hook 設定說明了 Claude Code 在 hooks 下預期的結構。
  • 若某一行的來源是 parent managed settings，表示啟動 Claude Code 的應用程式將該項目作為父層設定傳入，因此請向該應用程式的開發者回報
  • 否則，請將此區塊傳送給您的管理員
在 v2.1.300 之前，-p 執行會將此情況列在 Managed settings failed to load; policies from the failed source are NOT in effect: 標題下。

​
otelHeadersHelper failed

當 otelHeadersHelper 腳本失敗，或印出不符合腳本需求的輸出時，Claude Code 會在終端機介面中以通知形式顯示此警告，每個互動式工作階段顯示一次。 在腳本持續失敗期間，匯出會失敗，您的遙測後端不會從該工作階段收到任何內容。 See /status: 之後的文字會說明失敗的內容，例如腳本的退出碼，後面接著其錯誤輸出：
處理方式：
  • 執行 /status 以查看失敗詳細資訊。
  • 修正腳本，使其在 30 秒內以 0 結束，並在 stdout 上印出由字串標頭值組成的 JSON 物件。請參閱腳本需求。
  • 若您的組織透過受管設定部署此腳本，請請負責維護的人員加以修正。
在搭配 -p 的非互動模式下，相同的失敗會改以 otelHeadersHelper failed (OpenTelemetry export headers unavailable): <error> 的形式出現在 stderr 上。

​
headersHelper not run

Claude Code 僅以 MCP 伺服器的靜態 headers 連線該伺服器，並略過了該伺服器的 headersHelper，因為 helper 是 shell 命令，而該資料夾沒有已儲存的信任。當您手動在 ~/.claude.json 中設定資料夾的項目時，或（在家目錄以外的位置）在互動式工作階段中接受該資料夾的信任對話框時，該資料夾就會取得已儲存的信任。關於此檢查適用於哪些伺服器，請參閱在執行 headersHelper 之前信任資料夾。 Claude Code 只會在非互動模式下寫入此行，每個伺服器一次。在互動式工作階段中，它會改將相同的拒絕寫入除錯日誌。
訊息所印出的 projects 鍵，就是專案允許規則與工作區信任中所說 Claude Code 用來作為信任依據的資料夾。接受上層資料夾的信任對話框並不能滿足此檢查，-p 或 SDK 工作階段也無法滿足。 處理方式：
  • 在訊息所指的資料夾中執行 claude，接受信任對話框，然後再次執行您的 -p 或 SDK 命令
  • 使用訊息所印出的確切 projects 鍵，自行在 ~/.claude.json 中設定 hasTrustDialogAccepted 項目
  • 若您是在家目錄中啟動工作階段，請改在您已信任的專案目錄中工作。當您在家目錄中接受信任對話框時，Claude Code 只會在目前的工作階段中保留該信任。

​
Malformed Tool(content) rule

您某個設定檔中的權限規則不符合 Tool 或 Tool(content) 的形式，例如右括號之後還有文字，或缺少其中一個括號。Claude Code 會略過該規則，並在互動式工作階段啟動時於無效設定對話框中列出，也會在 claude doctor 的輸出中列出：
處理方式：
  • 在訊息所列的設定檔中，改寫該規則使其在右括號處結束，例如以 Bash(ls *) 取代 Bash(ls) x
  • 內容中的括號保持原樣即可。它們會被視為字面字元，因此像 Edit(./Finance (2024)/**) 這樣的規則無需跳脫即為有效
在 v2.1.260 之前，Claude Code 會將括號不成對的規則回報為 Mismatched parentheses。

​
Is not matched by file permission checks

Claude Code 在您的某個設定檔、受管設定，或 --allowedTools、--disallowedTools 或 --settings 旗標值中，找到了帶有路徑的 Write、NotebookEdit、MultiEdit 或 Glob 權限規則。它只會依據 Edit 和 Read 規則檢查檔案權限，因此永遠不會參考指定其他檔案工具的路徑規則。它會保留該規則，不做其他變更；警告會列出該規則、括號中的來源，以及應改寫成的替代寫法：
處理方式：
  • 將 Write(path)、NotebookEdit(path) 及舊版的 MultiEdit(path) 規則替換為 Edit(path)。Edit 規則涵蓋所有檔案編輯工具。
  • 除了在 --allowedTools 中（Claude Code 在此接受 Glob 規則且不會發出警告）之外，請將 Glob(path) 規則替換為 Read(path)。
  • 在警告括號中所指的來源修正規則：設定檔路徑，或對於 --allowed-tools 和 --disallowed-tools 則是旗標本身。磁碟上不存在的 claude-settings-<hash>.json 路徑代表的是內嵌的 --settings 值。請修正您傳給該旗標的 JSON。
  • 像 Write 或 Glob 這類僅有工具名稱的規則保持不變即可。Claude Code 會在工具層級比對它們，且不會對其發出警告。
  • 若來源顯示為 managed policy settings，請將警告轉給負責維護受管設定的人員，因為您無法自行消除它。
在背景工作階段中，或使用 --output-format json 或 stream-json 時，Claude Code 會將警告寫入除錯日誌而非 stderr，以保持機器讀取的輸出乾淨。使用 --debug 執行即可在 ~/.claude/debug/<session-id>.txt 中擷取它。在 v2.1.210 之前，Claude Code 會接受這些規則而不發出警告。

​
Has a wildcard before the rest of the command

Claude Code 在您的某個設定檔、受管設定，或 --allowedTools 或 --settings 旗標值中，找到了一條 Bash 允許規則，其 * 出現在決定命令為何的後續字詞之前，例如 Bash(git * main) 或 Bash(git -C * status *)。* 會比對任何文字，包括插入在該位置的選項：Bash(git * main) 也會核准 git -c core.fsmonitor=<script> diff main，其中 -c 會讓 git 執行命令中所指定的程式。萬用字元模式說明了比對規則。 此警告的目的是讓您能縮小萬用字元範圍比預期更廣的規則。Claude Code 會保留該規則，且不會改變其比對方式；警告會列出該規則及括號中的來源：
處理方式：
  • 將子命令之前的 * 替換為您所指的確切值：以 Bash(git checkout main) 取代 Bash(git * main)。
  • 將每個 * 移到子命令之後：以 Bash(git status *) 取代 Bash(git -C * status *)。為每個您想允許的子命令各寫一條規則。
  • 在警告括號中所指的來源修正規則：設定檔路徑，或 --allowed-tools 旗標本身。磁碟上不存在的 claude-settings-<hash>.json 路徑代表的是內嵌的 --settings 值。請修正您傳給該旗標的 JSON。
  • 若來源顯示為 managed policy settings，請將警告轉給負責維護受管設定的人員，因為您無法自行消除它。
在背景工作階段中，或使用 --output-format json 或 stream-json 時，Claude Code 會將警告寫入除錯日誌而非 stderr，以保持機器讀取的輸出乾淨。使用 --debug 執行即可在 ~/.claude/debug/<session-id>.txt 中擷取它。在 v2.1.246 之前，Claude Code 會接受這些規則而不發出警告。

​
Denying Bash also turns off the PowerShell tool

您移除了整個 Bash 工具，例如使用 --disallowedTools Bash，或在某個設定檔中使用僅有 Bash 或 Bash(*) 的拒絕規則。在安裝了 Git Bash 的 Windows 上，拒絕 Bash 也會關閉 PowerShell 工具，因此工作階段啟動時不會有任何 shell 工具。Claude Code 會在啟動時印出此警告：
處理方式：
  • 若要讓 Claude 使用 PowerShell，請依照啟用 PowerShell 工具所示，在您的環境中或設定檔的 env 區塊中將 CLAUDE_CODE_USE_POWERSHELL_TOOL 設為 1。如此一來，PowerShell 工具會與您的 Bash 拒絕規則並存並保持開啟。
  • 若要封鎖特定命令而非整個工具，請在同一個設定檔或旗標中，將僅有 Bash 的項目替換為有範圍限定的規則，例如 Bash(git push *)。Claude 會保留 Bash 工具，而 PowerShell 工具會保持關閉，直到您也設定該變數或加入有範圍限定的 PowerShell 權限規則。
在背景工作階段中，或使用 --output-format json 或 stream-json 時，Claude Code 會將警告寫入除錯日誌而非 stderr。使用 --debug 執行即可在 ~/.claude/debug/<session-id>.txt 中擷取它。在 v2.1.287 之前，Claude Code 會以相同方式關閉 PowerShell 工具，但不會印出警告。

​
crossSessionInbound must be one of accept, hold, refuse

某個設定檔將 crossSessionInbound 設為 Claude Code 無法辨識的值，例如拼錯的 "reject"。警告的第二句取決於哪個檔案包含該值；在使用者、專案、本機或 --settings 檔案中，內容如下：
在受管設定中，Claude Code 會將無法辨識的值視為最嚴格的 refuse，而警告會說明跨工作階段訊息在管理員修正之前都會被拒絕。關於保留行為如何與您其他設定檔中的值結合，請參閱 crossSessionInbound。 處理方式：
  • 將該鍵設為 "accept"、"hold" 或 "refuse"，或將其移除
  • 當警告提及受管設定時，請請管理員修正該值
在 v2.1.248 之前，Claude Code 會忽略無法辨識的值而不發出警告。

​
ANTHROPIC_FOUNDRY_RESOURCE must be a Foundry resource name

您將 ANTHROPIC_FOUNDRY_RESOURCE 設為非單純 Microsoft Foundry 資源名稱的值，例如端點 URL 或其主機名稱。Claude Code 在傳送請求之前就拒絕了該值。此訊息會出現在 Claude 回覆的位置，而非作為啟動警告：
處理方式：
  • 將 ANTHROPIC_FOUNDRY_RESOURCE 僅設為資源名稱，然後重新啟動 Claude Code。對於端點 https://my-resource.services.ai.azure.com/anthropic，名稱為 my-resource。
  • 若要改為提供完整的端點 URL，請將 ANTHROPIC_FOUNDRY_BASE_URL 設為該 URL 並移除 ANTHROPIC_FOUNDRY_RESOURCE，然後重新啟動 Claude Code。Claude Code 只接受這兩個變數的其中一個。

​
The 200K limit isn’t enforced

您設定了 CLAUDE_CODE_DISABLE_1M_CONTEXT=1，這通常會讓自動壓縮將使用 1M 上下文模型的工作階段限制在 200K 視窗內，但沒有任何壓縮閾值將此工作階段限制在 200K 或以下，因此對話可能會超過該上限。
對於 Claude Code 辨識為具有原生 1M 視窗的每個模型，Claude Code 會自行強制執行 200K 上限；對於無法辨識的模型 ID，它會依其假設的視窗大小進行壓縮。當其他設定使該強制執行失效時，就會出現此警告： 處理方式：
  • 設定 CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000，或將 autoCompactWindow 設定設為 200000，讓自動壓縮在 200K 邊界進行壓縮
  • 若訊息提及此版本無法辨識的模型 ID，請執行 claude update。能將該 ID 辨識為 1M 上下文模型的版本，無需額外設定即可強制執行該上限。
  • 若您希望工作階段改為使用模型的完整視窗，請取消設定 CLAUDE_CODE_DISABLE_1M_CONTEXT；此警告只是回報 200K 上限未被強制執行
在背景工作階段中，或使用 --output-format json 或 stream-json 時，Claude Code 會將警告寫入除錯日誌而非 stderr。

​
請求中包含無法辨識的模型 ID

Claude Code 傳送了一個請求，其模型 ID 是您的 Claude Code 版本無法辨識的，且找不到將該 ID 對應到可辨識模型的 modelOverrides 項目。Claude Code 仍會以您所設定的 ID 傳送請求，不會結束或切換模型。
在讀取 stderr 的腳本或測試框架中，請比對 [claude-code:unrecognized_model] 前綴。在前綴和一個空格之後，Claude Code 會寫入一行 JSON 物件。Claude Code 可能會在之後的版本中新增欄位，因此請忽略任何您未預期的欄位。它至少會寫入以下兩個欄位：
  • model：您所設定的模型字串
  • query_source：使用該模型的請求路徑。對於 -p 執行，Claude Code 會回報 sdk；對於 subagent，則會回報以 agent: 開頭的值。
Claude Code 會依您的執行方式，將此行寫入以下兩處之一：
  • 在搭配 -p 的非互動模式下，無論 --output-format 為何，Claude Code 都會將其寫入 stderr，因此您可以直接解析 stdout 而無需過濾掉此行
  • 在互動式工作階段或背景工作階段中，Claude Code 會改將其寫入除錯日誌；使用 --debug 執行即可在 ~/.claude/debug/<session-id>.txt 中擷取它
Claude Code 在每個程序中，對每個模型字串只寫入一次此行。對於其他每個無法辨識的 ID，例如 subagent 或背景功能所使用的 ID，它會另外寫入一行。 對於能解析為可辨識模型的供應商 ID，Claude Code 不會寫入此行，例如 Amazon Bedrock 的 us.anthropic.claude-... ID、帶有 @ 版本後綴的 Google Cloud Agent Platform ID，以及包含 Claude 模型 ID 的 Microsoft Foundry 部署名稱。對於 Amazon Bedrock 應用程式推論設定檔 ARN，Claude Code 會檢查其背後的模型，而非 ARN 本身。對於無法解析的 ARN（例如打錯的 ARN），它不會寫入任何行。 處理方式：
  • 若您是刻意設定該 ID，例如 LLM 閘道別名，請在您的設定檔中加入一個 modelOverrides 項目，並以該 ID 作為其值。請使用 Anthropic 模型 ID 作為鍵，而非 opus 之類的系列別名。對於範例行中的 my-proxy-model，請加入以下項目：
    如此一來，Claude Code 會將 my-proxy-model 視為 claude-opus-4-6，並停止寫入此行。
  • 若該 ID 指的是比您的 Claude Code 版本更新的模型，請執行 claude update
  • 若該 ID 是拼寫錯誤，請在包含它的可設定模型的位置或別名變數中加以修正。若 query_source 以 agent: 開頭，請改在您設定 subagent 模型的位置修正。
在 v2.1.233 之前，Claude Code 在為無法辨識的模型 ID 傳送請求時不會寫入任何行。

​
在受管鎖定下會忽略沙箱允許項目

/status 和 claude doctor 中的此警告表示受管設定設定了 allowManagedReadPathsOnly 或 allowManagedDomainsOnly，因此其所指檔案中的 allowRead 或 allowedDomains 項目不會套用：
對於網路鎖定，警告會提及 sandbox.network.allowedDomains 和 allowManagedDomainsOnly，並說明 only allowed domains (and WebFetch domain rules) from managed settings are honored。 處理方式：
  • 您不必針對此警告採取行動
  • 若您需要這些路徑或網域，且是組織的受管設定設定了該鎖定，請請您的管理員將它們加入這些設定。在您也從所指的檔案中移除這些項目之前，警告會持續存在。
  • 若要消除警告，請從所指的檔案中移除這些項目。對於您共用的檔案，例如專案的 .claude/settings.json，您可以為沒有該鎖定的隊友保留這些項目，並讓警告繼續顯示。

​
Stale sandbox mask files left by a killed session

claude doctor 會在其診斷中印出此警告，/status 也會列出相同的行。當沙箱機制在啟用檔案系統隔離的情況下開啟時，此警告會出現在 Linux 和 WSL2 上。 在沙箱化命令執行期間，沙箱會在尚不存在的檔案位置建立一個 0 位元組的唯讀佔位檔案，藉此對該檔案維持寫入拒絕，並在之後將其移除。若工作階段在清理執行之前被終止（例如被 SIGKILL），就會留下這些佔位檔案。之後的工作階段每次啟動時都會再次以唯讀方式綁定它們，因此在佔位檔案所在的位置進行設定寫入（例如儲存「Yes, and don’t ask again」）會失敗。
處理方式：
  • 結束在該專案中執行的任何其他 Claude Code 工作階段，然後以 rm 刪除每個列出的檔案。警告最多會列出三個檔案並計算其餘數量，因此刪除後請重新執行 claude doctor，直到警告不再出現為止。另一個工作階段的沙箱仍在使用的佔位檔案，是該工作階段寫入保護中正在運作的一部分
  • 若您以「Yes, and don’t ask again」儲存的權限選擇沒有生效，請在刪除佔位檔案後再次儲存
在 v2.1.257 之前，claude doctor 不會標示這些檔案；較早的版本在工作階段被終止時也會留下相同的佔位檔案。

​
回應品質似乎低於預期

如果 Claude 的回答似乎不如您預期的那樣有能力，但沒有顯示錯誤，原因通常是對話狀態而非模型本身。Claude Code 不會無聲地更改模型版本。它只能在這些情況下切換到備用模型：
  • 配置的 --fallback-model 在可用性錯誤後接管該輪次，並在文字記錄中顯示通知
  • Amazon Bedrock 或 Google Cloud 的 Agent Platform 啟動檢查發現您的預設模型不可用，或您的帳戶在工作階段中途失去對它的存取權
  • 自動模型備用在 Fable 5.1、Fable 5、Opus 5.5、Sonnet 5.5 和 Opus 5 上將工作階段移至標記類別的備用模型（當該類別有備用模型時），並在文字記錄中顯示通知
下面的模型選擇檢查可以捕捉第二和第三種情況；第一種情況顯示為文字記錄通知而非 /model 變更。模型設定說明每個備用何時適用。 首先檢查這些項目：
  • 模型選擇：執行 /model 以確認您在預期的模型上。先前的 /model 選擇或 ANTHROPIC_MODEL 環境變數可能使您在比預期更小的模型上。
  • 努力程度：執行 /effort 以檢查目前的推理程度，並為困難的除錯或設計工作提高它。預設值因模型而異，所以在假設您低於最大值之前請先檢查。請參閱調整努力程度以了解每個模型的預設值和 ultrathink 快捷方式。
  • 上下文壓力：執行 /context 以查看視窗有多滿。如果接近容量，請在自然斷點執行 /compact 或執行 /clear 以重新開始。請參閱探索上下文視窗以了解自動壓縮如何影響較早的輪次。
  • 過時的指示：大型或過時的 CLAUDE.md 檔案和 MCP 工具定義會消耗上下文並可能引導回應。/doctor 檢查會標記超大的記憶檔案和未使用的擴充功能，而 /context 會顯示 MCP 工具的權杖使用情況。在 v2.1.205 之前，/doctor 開啟了一個診斷畫面，標記超大的記憶檔案和子代理定義。
當回應出錯時，回溯通常比用更正回覆效果更好。按 Esc 兩次或執行 /rewind 以回到不良輪次之前，然後用更多細節重新表述提示。在執行緒中更正會將錯誤的嘗試保留在上下文中，這可能會將後來的答案錨定到它。請參閱檢查點。 如果在檢查上述項目後品質仍然似乎有問題，請執行 /feedback 並描述您預期的內容與您得到的內容。以這種方式提交的回饋包括對話文字記錄，這是 Anthropic 診斷真實迴歸的最快方式。如果 /feedback 在您的環境中不可用，請參閱報告錯誤。 如果 Claude 警告懷疑提示注入，或因懷疑注入而拒絕請求，而警告命名的文字是 Claude Code 自動添加到對話中的上下文而非檔案或網路內容，請執行 claude update 並重試。如果更新後警告重複出現，請報告它而不是將標記的內容貼回提示中。在 v2.1.201 之前，Sonnet 5 以相同方式拒絕了一些請求。

​
回報錯誤

如需了解此頁面未涵蓋的元件錯誤，請參閱相關指南： 如果此處未列出錯誤或建議的修正方法無法幫助：
  • 在 Claude Code 內執行 /feedback 以將文字記錄和說明傳送給 Anthropic。該命令也提供開啟預先填入的 GitHub issue 的選項。傳送給 Anthropic 需要驗證。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和其他第三方提供者上，或當未設定 Anthropic 認證時，/feedback 會儲存本機封存，您可以改為傳送給您的 Anthropic 帳戶代表。
  • 從您的 shell 執行 claude doctor 以進行安裝的唯讀診斷，或在 Claude Code 內執行 /doctor 檢查以尋找並修正設定問題
  • 檢查 status.claude.com 以了解活躍的事件
  • 在 GitHub 上搜尋現有 issue