錯誤參考

查詢 Claude Code 執行時錯誤訊息，了解每個錯誤的含義及修復方法。

本頁列出 Claude Code 顯示的執行時錯誤及如何從每個錯誤中復原，以及當回應似乎有問題但沒有錯誤時要檢查的內容。如需安裝錯誤（例如 command not found 或設定期間的 TLS 失敗），請參閱疑難排解安裝和登入。

除了包裝程式和 IDE 錯誤（由啟動程式列印而非 Claude Code 本身列印）外，這些錯誤和復原命令適用於 CLI、桌面應用程式和雲端工作階段，因為這三者都包裝相同的 Claude Code CLI。如需其他使用介面特定的問題，請參閱該使用介面頁面上的疑難排解部分。

找到您的錯誤

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

自動重試

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 會中止停滯的連線，並最多重新發出一次請求，不在上述 10 次嘗試預算內。如果在 Claude 完成思考但在任何文字或工具呼叫之前回應停滯第二次，Claude Code 會以 The response stalled before a response was produced 結束回合。
• 串流請求 API 從未以回應標頭回答，在 first-byte deadline 執行 的連線上：Claude Code 在截止時間中止它，並在重試預算內最多每個模型請求重新發送一次，然後如果該嘗試也未獲得回答，則以 No response from API 結束回合。在其他連線上，請求會等待 API_TIMEOUT_MS。當您設定 CLAUDE_CODE_RETRY_WATCHDOG 時，一次重試上限不適用。
• 暫時性 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 回應：

API Error: 500 Internal server error. This is a server-side issue, usually temporary — try again in a moment. If it persists, check https://status.claude.com.

結尾的句子會指明檢查服務健康狀況的位置，並因提供者而異。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 在顯示此訊息之前已經重試了多次：

API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

結尾的句子因提供者而異，方式與上面的 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 在連線截止時間之前沒有回應。

Request timed out

這可能在高負載期間或模型生成非常大的回應時發生。預設請求逾時為 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 會在調整重試行為中描述的預算下重試。

API Error: No response from API (waited 3m, then 10m on the retry). If a proxy or gateway on your network holds responses until they complete, raise API_TIMEOUT_MS or CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS to wait longer.

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 完成的輸出並附加此通知，而不是丟棄該回合。您看到的變體會指明原因：

API Error: Server error mid-response. The response above may be incomplete.
API Error: Connection lost mid-response. The response above may be incomplete.
API Error: Your computer went to sleep mid-response. The response above may be incomplete.
API Error: The response stopped arriving. The response above may be incomplete.
API Error: Part of the response never arrived. The response above may be incomplete.
API Error: The response stream was malformed. The response above may be incomplete.

• 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

自動模式用來分類動作的模型無法產生決定，因此自動模式沒有自動核准該動作。您看到的訊息取決於分類器如何失敗。

讀取、搜尋和編輯您的工作目錄內的內容會跳過分類器，因此它們在所有這些情況下都能繼續工作。

當分類器模型不可用時：

<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait a moment and then try this action again.

當 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 被重新整理。

當分類器返回無法解析的回應時：

Auto mode could not evaluate this action and is blocking it for safety — run with --debug for details

該怎麼做：

• 重試該動作；這通常在下一次嘗試時成功
• 執行 claude --debug 並重複該動作以在偵錯日誌中查看詳細資訊

當單獨的 API 安全檢查因為早期對話內容而阻止分類器請求時：

Auto mode could not evaluate this action and is blocking it for safety — a safety check separate from auto mode blocked this request because of earlier conversation content — it isn't about the action itself — run with --debug for details

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 上的安全篩選器
• 重試無法幫助；相同的對話內容將再次觸發篩選器
• 在互動式工作階段中，切換到不同的權限模式，以便您可以在提示時核准該動作
• 開始一個新的對話，不包含觸發內容

當對話增長超過分類器的上下文視窗時：

Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)

動作發生的情況取決於 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)：

The server-side auto mode classifier gave no verdict (timed out), so auto mode cannot determine the safety of <tool>.

訊息的其餘部分告訴 Claude 一次重試是否可以幫助。在某些這些拒絕之前，Claude Code 會等待，以便 Claude 的下一次嘗試不會立即跟隨。在互動式工作階段中等待期間，微調器顯示 Auto mode check unavailable 並帶有倒計時，按 Esc 會中斷該回合。

在連續十個回應都沒有判決後，自動模式會停止該回合：

Auto mode is unavailable — the server returned no safety verdict for the last 10 responses, so Claude stopped. Send a message to try again, or switch out of auto mode.

停止訊息在每種工作階段中出現在不同的位置：

• 在互動式工作階段中，訊息作為警告出現在逐字稿中，回合結束
• 在非互動式 -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 的結果一樣。

Agent terminated early due to an API error: <error detail>

該怎麼做：

• 將冒號後的錯誤詳細資訊與此頁面上對應的部分相符，例如用量上限或伺服器錯誤，並遵循該部分的步驟
• 一旦基礎錯誤清除，請要求 Claude 重試任務或恢復 subagent

當速率限制、過載或伺服器錯誤中斷已經產生文字輸出的前景 subagent 時，Claude 會收到該部分輸出標記為不完整，而不是此錯誤。其唯一輸出是工具呼叫的 subagent 也會收到此錯誤；在 v2.1.199 中，該形狀返回了空部分結果。請參閱 subagent 中的 API 錯誤。

使用限制

本節中的大多數錯誤表示與您的帳戶或方案相關的配額已達到。其中三個的運作方式不同：伺服器暫時限制請求 是與您的方案配額無關的伺服器端節流，1M 上下文需要使用額度 是權利檢查而非耗盡的配額，確認提示未獲回應 表示使用額度同意提示已關閉且未獲回應，無論是否達到配額。

您已達到工作階段限制

訂閱方案包括滾動使用額度。當額度用完時，您會看到以下其中一條訊息：

You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am
You've hit your Opus limit · resets 3:45pm
You've hit your Sonnet limit · resets 3:45pm

Claude Code 會阻止進一步的請求，直到訊息中顯示的重設時間。工作階段和每週限制在所有模型中共享，因此切換模型不會恢復存取。Opus 和 Sonnet 限制各自僅適用於對該模型系列的請求，因此使用 /model 切換到該系列外的模型可讓您繼續工作。

在使用 claude.ai 訂閱登入的互動式工作階段中，Claude Code 也可以在開啟的工作階段中等待，並在重設後不久繼續中斷的任務。請參閱等待用量上限重設以了解您看到的內容、如何開始或取消等待，以及如何關閉自動繼續。在 v2.1.234 之前，Claude Code 不提供此等待功能。

使用量同時計入工作階段和每週額度。單次大量活動突發（例如大型工作流程扇出）可能會在工作階段視窗重設之前耗盡每週額度。

該怎麼做：

• 等待錯誤中顯示的重設時間
• 在桌面應用程式的 Code 標籤中，工作階段限制卡片提供達到限制時自動繼續核取方塊。每週限制卡片則不提供。勾選後，桌面應用程式會在重設後重試中斷的回合，並在卡片上顯示重試時間。桌面核取方塊和 CLI 在 /config 中的達到使用限制時自動繼續設定是分開的，因此請分別關閉每一個。
• 對於 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 欄位新增至自訂狀態行，或在桌面應用程式中按一下模型選擇器旁的使用量環。

1M 上下文需要使用額度

選定的模型使用 1M 權杖擴展上下文視窗，而您的方案僅透過使用額度包括它。

API Error: Usage credits required for 1M context · run /usage-credits to turn them on (they take effect after you restart Claude Code), or /model to switch to standard context

在 Claude 桌面應用程式執行的工作階段中，提示不會命名任何命令：它指向 claude.ai 使用量設定頁面，或在 Team 和 Enterprise 方案上說在 claude.ai/admin-settings/usage 開啟使用額度，或要求您的管理員。

這是權利檢查，而非配額耗盡。即使您的工作階段和每週額度有剩餘容量，它也會觸發。請參閱擴展上下文以了解哪些方案直接包括 1M 上下文，哪些需要使用額度。

當此錯誤在對話中期出現，因為上下文增長超過 200K 權杖時，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 結尾，並未提及重新啟動。

確認提示未獲回應

如果您的帳戶需要 Fable 使用額度同意，Claude Code 會要求您在 Fable 請求計費使用額度之前確認。當沒有人在工作階段執行所在的終端回應該同意提示時，Claude Code 會以以下其中一條訊息結束回合：

Fable limit reached · continuing on Fable 5.1 uses usage credits, and the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change
Fable 5.1 now uses usage credits · the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change

訊息會命名工作階段的 Fable 模型，因此在 Fable 5 上它們會讀作 continuing on Fable 5 和 Fable 5 now uses usage credits。在 v2.1.257 之前，第一條訊息以 Fable 5 limit reached 開頭。

這發生在遠端控制工作階段、背景工作階段、代理團隊隊友工作階段，以及另一個應用程式透過 Agent SDK 託管的工作階段中。如需 Claude Code 何時關閉提示，請參閱 Fable 和使用額度。

該怎麼做：

• 在工作階段執行所在的終端或託管它的應用程式中，發送另一個提示，當同意提示重新出現時回答它。對於背景工作階段，請先從代理檢視附加到它。從遠端控制用戶端重新發送會再次顯示此訊息，因為用戶端無法顯示提示。
• 執行 /model 以切換到不計費使用額度的模型
• 若要給自己更多時間，請將 dialogExpiry 設定為更長的值或 "never"

在 v2.1.236 之前，此訊息不會出現：當遠端控制用戶端已連接時，Claude Code 會等待 60 秒以獲得答案，然後在您的預設模型上繼續回合。

伺服器暫時限制請求

API 應用了與您的方案配額無關的短期節流。

API Error: Server is temporarily limiting requests (not your usage limit)

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

該怎麼做：

• 稍等片刻後重試
• 如果問題持續，請檢查 status.claude.com

請求被拒絕 (429)

您已達到為您的 API 金鑰、Amazon Bedrock 專案或 Google Cloud 專案設定的速率限制。

API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.

尾部句子命名檢查服務健康狀況的位置，並因提供者而異。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、避免執行許多平行子代理，或使用 /model 切換到較小的模型以進行高容量指令碼執行

您已達到每月支出限制

您的方案包含的使用量無法涵蓋此請求，而原本會為其付費的使用額度已達到支出限制。這發生在您的方案的其中一個使用視窗已用完時，或當請求是僅由使用額度支付的請求時，例如對計費至使用額度的模型的請求。訊息會命名哪個限制阻止了您。· 後面的文字說明如何提高該限制，並因您的方案和您是否管理計費而異：

You've hit your monthly spend limit · raise it at claude.ai/settings/usage
You've hit your individual spend limit · ask your admin for a higher limit
You've hit your org's monthly spend limit · visit claude.ai/admin-settings/usage to raise it
You've hit your team's shared budget · ask your admin to raise it at claude.ai/admin-settings/usage
You've hit your channel's monthly spend limit · an org owner or channel manager can raise it in the channel's Claude settings

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。

在 v2.1.239 之前，訊息不會命名方案視窗的重設時間。在 v2.1.268 之前，群組的集區預算產生了 individual spend limit 訊息，而不是 team's shared budget。

如果您透過 Claude 應用程式閘道連接並看到小寫 spend limit reached，那是您的閘道運營商的上限；請參閱支出限制已達到。

該怎麼做：

• 在 Pro 和 Max 上，在 claude.ai 的設定 > 使用量中提高您的每月支出限制，或執行 /usage-credits
• 在 Team 和 Enterprise 上，如果您管理計費，請在管理設定 > 使用量中提高限制，或要求管理員提高。/usage-credits 會為您向您的管理員發送該請求
• 對於頻道的限制，要求組織擁有者或頻道的管理員在 claude.ai 上提高它。請參閱 Claude Tag 文件中的每頻道限制
• 如果訊息命名您的方案視窗的重設時間，您可以改為等待它
• 執行 /usage 以查看您的方案視窗和每個視窗何時重設

已達到支出限制

您透過Claude 應用程式閘道連接，並已超過閘道運營商設定的支出上限。閘道會阻止您的請求，直到命名的期間重設或運營商提高上限。它將每個被阻止的 429 回應標記為 x-should-retry: false，因此 Claude Code 會顯示此訊息而不重試。

spend limit reached (daily; resets 2026-08-09 00:00 UTC)

訊息會命名上限的期間和重設時間，當運營商設定了 blocked_message 時，他們的指示會跟在它後面。在 v2.1.225 之前，訊息只讀 spend limit reached；較舊版本上的閘道仍會發送該較短的形式。

該怎麼做：

• 等待訊息命名的重設時間，或如果訊息包含運營商的指示，請遵循它們
• 如果您經常達到上限，請要求您的閘道運營商提高上限

相關訊息 spend limit unavailable 表示閘道無法讀取其支出記錄，並作為預防措施而不是超過您的上限而阻止了請求。它通常會自行清除；如果它持續，請告訴您的閘道運營商。

信用額度餘額過低

您的 Console 組織已用完預付額度，或 Claude Code 正在使用 Console API 金鑰發送您的請求，而您打算使用您的訂閱。

Credit balance is too low

該怎麼做：

• 如果您有 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: <reason from the server>

當伺服器解釋拒絕時，訊息以該原因結尾，重試相同值會再次失敗。當失敗沒有伺服器提供的原因（例如連接中斷）時，訊息會讀作 Could not update your spend limit. Press Enter to retry.，重試可能會成功。在 v2.1.216 之前，Claude Code 為每個失敗顯示通用形式。

該怎麼做：

• 如果訊息包含原因，請選擇滿足它的限制，例如較低的金額
• 如果訊息僅顯示通用形式，請重試；失敗可能是暫時的
• 如果變更持續失敗，請改為在瀏覽器中從您的 claude.ai 計費設定進行變更

身分驗證錯誤

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

未登入

此工作階段沒有可用的有效憑證。

Not logged in · Please run /login

在由 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 執行會將相同狀況回報為未登入，並且只會將此字串寫入其偵錯日誌，因此若您是在日誌中看到它，請改為依照該項目處理。

Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted

在目前的版本中，此錯誤表示 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 的金鑰。

Invalid API key · Fix external 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 會在去除前後空白後，直接傳送命令輸出的任何內容。

Your apiKeyHelper script is failing · This usually means you need to re-authenticate with your provider · Run /status to see the script's error output

在非互動模式中，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 · Fix external auth token
Invalid ANTHROPIC_CUSTOM_HEADERS · Fix the environment variable
Invalid request header from the environment · Fix the environment variable

訊息的第一部分取決於錯誤值的來源：

• 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 指令碼執行失敗失敗。

在第二個 · 之後，訊息會描述問題，如以下完整範例所示：

Invalid auth token · Fix external auth token · Invalid Authorization header value from ANTHROPIC_AUTH_TOKEN: it contains a line break at character 41 (120 characters on 2 lines).

位置從一開始計算字元。描述由固定片語與字元數組成，因此絕不會包含值本身。只有在問題字元是知名的不可見或排版字元時（例如位元組順序標記、零寬度空格或彎引號），描述才會指名該字元，其他字元一律回報為 a non-ASCII character。

處理方式：

• 重新設定訊息所指的變數或設定，重新輸入回報位置附近的字元，而不是再次從相同來源貼上
• 對於 ANTHROPIC_CUSTOM_HEADERS，每行保留一組 Name: Value，並重新撰寫訊息所指出的那一組
• 執行 /status，確認使用中的是哪個憑證來源

此組織已被停用

Claude Code 正在使用來自已停用 Console 組織的過時 ANTHROPIC_API_KEY。當您有已儲存的訂閱登入時，該金鑰會覆寫它。

Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your subscription instead
Your ANTHROPIC_API_KEY belongs to a disabled organization · Update or unset the environment variable
API Error: 400 ... This organization has been disabled.

· 之後的提示取決於您已儲存的憑證：當您取消設定金鑰後有已儲存的 /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 傳送的金鑰。· 之後的復原提示會依金鑰來源而不同：

Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account
Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY to use your claude.ai account instead
Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY and run /login to sign in with your claude.ai account
Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account
Your organization has disabled API key authentication · Sign in again with your claude.ai account

最後一種形式出現在由 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 會傳回相同的錯誤。

Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access

這是伺服器端的組織設定，因此無法透過本機設定、環境變數或 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。

Routines are disabled by your organization's policy.

這是伺服器端設定，因此無法透過本機設定、環境變數或 CLI 旗標覆寫。

處理方式：

• 請您組織中的 Owner 在 claude.ai/admin-settings/claude-code 啟用 Routines 切換開關
• 對於不需要組織層級 routine 的一次性排程工作，請參閱排程任務

Remote Control 需要 Anthropic API

此工作階段並未直接與 Anthropic API 通訊，而這是 Remote Control 所必需的。

Remote Control is only available when using Claude via api.anthropic.com. CLAUDE_CODE_USE_BEDROCK is set, so this session is using Amazon Bedrock — unset it (or run in a shell without it) to use 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 的情況下繼續執行。本節涵蓋以下幾行：

Remote Control disconnected — Claude.ai login expired — run /login to restore Remote Control
Remote Control disconnected — Claude.ai login expired — run /login, then /remote-control
Remote Control disconnected — Claude.ai login was rejected — run /login, then /remote-control
Remote Control disconnected — OAuth token unavailable — run /login to restore Remote Control
Remote Control disconnected — OAuth token refresh failed — run /login to re-authenticate
Remote Control disconnected — JWT refresh failed: no OAuth token — run /login
Remote Control disconnected — Signed out of Claude — run /login, then /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 已停止

在 Remote Control 工作階段期間，當您在這台機器上登入不同的 claude.ai 帳戶或組織時，Claude Code 會顯示此行。您是在 Claude Code 工作階段之外進行切換的，例如在另一個終端機中執行 /login。

您透過 /login 登入時啟動的 Remote Control 工作階段，屬於當時已登入的 claude.ai 帳戶與組織。

Remote Control disconnected — signed-in claude.ai account or organization changed on this machine — run /remote-control to start a session for the current account, or /login to switch back, then /remote-control

一旦 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 stopped — the app running this session is now signed in to a different Claude account
Remote Control stopped — the app running this session is signed out of Claude. Sign in there, then turn Remote Control back on

您的本機工作階段會在沒有 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 過期或被撤銷時，您會看到相同的訊息。

OAuth token revoked · Please run /login
Please run /login · API Error: 401 OAuth token has expired ...

在非互動模式（-p）與 Agent SDK 中，訊息如下，結構化錯誤代碼為 authentication_failed：

Failed to authenticate: OAuth token revoked. Please log in again or contact your administrator.
Failed to authenticate. API Error: 401 OAuth token has expired ...

在 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 查看使用中的是哪一個。

Please run /login · API Error: 401 Invalid authentication credentials

處理方式：

• 如果 /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 失敗，而不是提示您登入。

Login expired · Please run /login

在非互動模式（-p）與 Agent SDK 中，訊息如下，結構化錯誤代碼為 authentication_failed：

Failed to authenticate: OAuth session expired and could not be refreshed

這與 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 會在傳送前停止請求：

Could not refresh your login because another Claude Code process is refreshing it (or exited mid-refresh) · Try again in a minute; if it keeps happening, close other Claude Code windows or sign in again with /login

在非互動模式（-p）與 Agent SDK 中，訊息如下，結構化錯誤代碼為 server_error：

Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh. This is usually transient; retry in a minute, and if it persists close other Claude Code processes or sign in again

以 API 金鑰、CLAUDE_CODE_OAUTH_TOKEN 或第三方供應商進行身分驗證的工作階段不使用已儲存的登入，永遠不會看到此訊息。

處理方式：

• 一分鐘後再試一次。如果另一個程序先完成了重新整理，此工作階段就會使用更新後的登入。
• 如果訊息持續出現，請關閉其他 Claude Code 視窗與程序，然後重試。
• 如果在沒有其他 Claude Code 程序執行的情況下仍出現此訊息，請執行 /login。重新登入不需要等待重新整理鎖。

無法儲存您的登入

您已使用 claude.ai 登入，但 Claude Code 無法將登入儲存至其憑證儲存區，因此登入未完成。在 macOS 上，如果 Claude Code 在同一個工作階段中已經讀取或儲存過登入鑰匙圈中的憑證，之後鑰匙圈被鎖定（例如在睡眠或閒置時），就可能發生這種情況。

Couldn't save your login. If your Mac's keychain is locked, unlock it and log in again.
Couldn't save your login. Try logging in again.

第一種形式出現在 macOS 上，第二種則出現在其他所有平台上。暫時性的憑證儲存區失敗（例如逾時或儲存區無法讀取）也會產生相同的訊息。

處理方式：

• 在 macOS 上，解鎖登入鑰匙圈，然後再次執行 /login
• 在其他平台上，再次執行 /login
• 如果登入仍無法儲存，請參閱未登入或 token 已過期，了解鑰匙圈解鎖命令及其他憑證儲存復原步驟

無法啟動 OAuth 回呼伺服器

當 /login、claude auth login 或 claude setup-token 透過瀏覽器為您登入時，Claude Code 會在 127.0.0.1 上開啟一個監聽埠，讓您的瀏覽器能將登入結果傳回給它。此訊息表示 Claude Code 無法開啟該埠，登入會在瀏覽器視窗或登入 URL 出現之前停止：

Failed to start OAuth callback server: Failed to start server. Is port 0 in use?

如果您的訊息以 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 登入，通常是因為登入已過期或被撤銷。

如果伺服器有提供原因，該行的第一部分會是伺服器本身的原因。否則該行顯示為：

Claude login not accepted · Run /login, then try again

處理方式：

• 執行 /login，完成登入後再次啟動工作階段

Artifact 需要 claude.ai 登入

Claude Code 拒絕了 artifact 的發布或讀取，因為此工作階段沒有可用於 artifact 的 claude.ai 登入。

每種形式的訊息都以相同的文字開頭，後面接著依您工作階段的身分驗證方式而定的補救方法。在沒有競爭憑證的情況下，訊息顯示為：

Artifacts need a claude.ai login. Run /login and select "Claude account with subscription", then retry — the "Anthropic Console account" option does not provide claude.ai credentials.

處理方式：

• 執行 /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 閘道登入。您會看到下列兩種訊息之一：

Not signed in to the Cloud gateway — run /login.

當工作階段沒有閘道登入時，模型請求會以此訊息失敗，例如因為在政策套用到這台機器之後您尚未執行 /login。

如果這台機器還持有 Anthropic 核發的憑證，且受管設定設定了 forceLoginMethod 或 forceLoginOrgUUID，Claude Code 會改為在啟動時結束。該憑證可能是 ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN 變數、apiKeyHelper 設定，或先前 Claude Console 登入所儲存的 API 金鑰。

啟動訊息會指出工作階段所設定的憑證、其設定位置，以及移除它的步驟。例如，若您在 shell 中設定了 ANTHROPIC_API_KEY 變數，訊息會顯示為：

Administrator policy requires a Cloud gateway sign-in on this machine, but this session is configured with an API key from ANTHROPIC_API_KEY, which a gateway machine does not accept.

To continue: unset ANTHROPIC_API_KEY (or run in a shell without it), then run claude and sign in with /login.

處理方式：

• 對於 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 嘗試更新您已儲存的登入並得知暫停狀態時，會顯示第一則訊息；當您在瀏覽器中完成的登入回報此狀態時，會顯示第二則訊息：

Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted
Your account is on hold and can't sign in to Claude Code. View details or appeal: https://claude.ai/restricted

以相同帳戶重新登入不會清除此訊息，因為暫停是針對帳戶而非登入。在非互動模式（-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 會在本機停止每個請求而不重試，因為重試只會讀取相同的過期憑證。

Anthropic profile login expired · Re-authenticate your Anthropic profile
Anthropic profile login expired · Run /login to use your claude.ai account instead, or re-authenticate the profile

只有當使用中的憑證來自 Anthropic 憑證設定檔時才會出現此訊息，該設定檔可能是您以 ANTHROPIC_PROFILE 環境變數選擇的、Claude Code 在您的 Anthropic 設定目錄中探索到的使用中設定檔，或是 Claude Code 在您無 API 金鑰登入時寫入的設定檔。以 API 金鑰、bearer token（例如 ANTHROPIC_AUTH_TOKEN）或第三方供應商進行身分驗證的工作階段永遠不會看到此訊息。

在提供無金鑰登入的機器上，若要更新由無金鑰 Console 登入或 Claude Platform CLI 的 ant auth login 所寫入的設定檔，請執行 /login，選擇 Anthropic Console 帳戶並重新登入。Claude Code 會取代該設定檔中的過期憑證。對於聯合設定檔或由其他工具建立的設定檔，/login 不會更新憑證。您看到哪一種形式，取決於設定檔是您選擇的還是 Claude Code 探索到的：

• 當您明確設定 ANTHROPIC_PROFILE 時，訊息會以 Re-authenticate your Anthropic profile 結尾。
• 當 Claude Code 從您的設定目錄探索到設定檔時，訊息會提供 /login，因為 Claude Code 會讓可用的 /login 優先於探索到的設定檔，並改以您的 claude.ai 或 Console 帳戶進行身分驗證。在 v2.1.234 之前，Claude Code 在這種情況下也會顯示 Re-authenticate your Anthropic profile 形式。

處理方式：

• 重新登入設定檔，然後重試：在提供無金鑰登入的機器上，對於由無金鑰 Console 登入或 Claude Platform CLI 的 ant auth login 所寫入的設定檔，請執行 /login 並選擇 Anthropic Console 帳戶；對於其他設定檔，請使用建立它們的工具
• 如果設定檔的憑證是由管理員佈建的，請要求他們核發新的憑證
• 執行 /status，確認使用中的憑證來源與設定檔名稱
• 若要停止使用該設定檔，請在您有設定的情況下取消設定 ANTHROPIC_PROFILE，然後以其他方式進行身分驗證，例如 /login 或 ANTHROPIC_API_KEY

OAuth 範圍需求

已儲存的 token 早於某個較新功能所需的權限範圍：

OAuth token does not meet scope requirement: user:profile

處理方式：

• 執行 /login 以取得具有目前範圍的新 token。您不需要先登出。

claude.ai 拒絕了工作階段 token

claude.ai 連接器請求失敗，因為 claude.ai 拒絕了來自您 Claude Code 登入的 token。被拒絕的 token 是您的登入，而不是連接器本身在 claude.ai 中的授權，因此重新授權連接器無法解決此問題。在 /mcp 中，該連接器會顯示為 session token rejected，其詳細資訊檢視顯示：

claude.ai rejected the session token. Run /login, then reconnect.

處理方式：

• 執行 /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 server "<name>" needs you to sign in again (run /mcp to re-authenticate)

執行 /mcp，選擇該伺服器，並從其選單重新登入。

對於以 headersHelper 指令碼設定的伺服器，Claude Code 在顯示此訊息之前已經重新執行過 helper 並重試過一次呼叫：

MCP server "<name>" rejected the credential from its headersHelper (check the helper and run /mcp to reconnect, or to authenticate if the server also uses OAuth)

請確認 helper 傳回的憑證是伺服器所接受的，然後從 /mcp 重新連線，這會再次執行 helper。

對於設定中帶有靜態 Authorization 標頭的伺服器：

MCP server "<name>" rejected the Authorization header in its config (update it, then run /mcp to reconnect)

在設定該伺服器的位置更新標頭值，然後從 /mcp 重新連線。

在 v2.1.273 之前，登入過期、headersHelper 與 Authorization 標頭這幾種情況都會顯示 MCP server "<name>" requires re-authorization (token expired)。

伺服器也可能以 HTTP 403 insufficient_scope 拒絕工具呼叫，要求您授權某個範圍，有時是您的 token 已列出的範圍。訊息會指出該範圍：

MCP server "<name>" needs additional permissions (scope: "<scope>") — run /mcp to re-authenticate

執行 /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> 會將此拒絕顯示為：

Couldn't complete authentication for "<name>": This server's URL is missing or not a valid URL, so sign-in can't start. Fix the URL in its MCP config (or set the environment variable it uses) and try again.

處理方式：

• 在設定該伺服器的位置將該項目的 url 設定為伺服器的實際端點，或設定其 ${VAR} 參照所指名的環境變數，然後再次執行登入。

授權回應中的 issuer 不符

在 MCP OAuth 登入期間，授權伺服器重新導向回 Claude Code 時所帶的 iss 參數，並非 Claude Code 根據伺服器 OAuth 中繼資料所預期的 issuer。此步驟出現錯誤的 issuer 正是授權伺服器混淆攻擊的樣貌，因此 Claude Code 會讓登入失敗，而不是交換授權碼。Claude Code 會在瀏覽器登入後於 /mcp 伺服器選單中顯示此錯誤：

Issuer mismatch in authorization response (RFC 9207): expected "https://auth.example.com", received "https://other.example.com"

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 會在伺服器的選單下顯示它：

Refusing to send credentials to non-https token endpoint 'http://192.168.1.50:8123/oauth/token'. OAuth token requests MUST use TLS (localhost / 127.0.0.1 / ::1 are exempt).

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：

AWS credentials expired or invalid · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · API Error: 401 ...

在 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 · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · if credentials are current, check AWS permissions and model access · API Error: 403 ...

中間的動作提示會依您的設定而不同。固定不變的部分是開頭的 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：

Google Cloud credentials expired or invalid · refresh your Google Cloud credentials (application default sign-in, or the key file in GOOGLE_APPLICATION_CREDENTIALS) and retry · API Error: 401 ...

處理方式：

• 如果提示表示憑證由此環境管理，則啟動 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：

Google Cloud authentication failed · refresh your Google Cloud credentials (application default sign-in, or the key file in GOOGLE_APPLICATION_CREDENTIALS) and retry · if credentials are current, check GCP IAM permissions and Vertex AI model access · API Error: 403 ...

處理方式：

• 如果提示指出憑證由此環境管理，表示啟動 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：

Microsoft Foundry authentication failed · refresh your Foundry credential (ANTHROPIC_FOUNDRY_AUTH_TOKEN, ANTHROPIC_FOUNDRY_API_KEY, Azure sign-in for Entra, or your proxy token) and retry · if credentials are current, check access to the Foundry resource · API Error: 401 ...

處理方式：

• 如果提示指出憑證由此環境管理，表示啟動 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 應用程式預設憑證取得可用的憑證，因此沒有任何請求送達您的雲端供應商。Claude Code 會清除其快取的憑證並重試兩次，之後才顯示此訊息。· 之後的詳細資訊會指出具體原因，例如 SSO 工作階段過期、缺少應用程式預設憑證（回報為 Could not load the default credentials），或登入遭撤銷（回報為 invalid_grant）：

API Error: Could not load AWS credentials · Could not load credentials from any providers. Check or refresh your AWS credentials and try again.
API Error: Could not load Google Cloud credentials · invalid_grant. Check or refresh your Google Cloud credentials and try again.

在使用 -p 的非互動模式以及 Agent SDK 中，結構化錯誤代碼為 cloud_credential_error。在 v2.1.267 之前，訊息只會顯示 API Error: 之後的詳細文字，且結構化代碼為 server_error 或 unknown。

處理方式：

• 執行您供應商的登入命令，例如 aws sso login --profile myprofile 或 gcloud auth application-default login，然後重試。Bedrock、Agent Platform 或 Foundry 憑證無法載入說明如何在 Claude Code 之外確認憑證
• 如果詳細資訊顯示 AWS default-chain credential resolve timed out，表示憑證鏈是停滯而非失敗，請改為依照 AWS 預設憑證鏈解析逾時處理

AWS 預設憑證鏈解析逾時

AWS 預設憑證提供者鏈未在 60 秒內產生憑證，因此 Claude Code 停止解析並使請求失敗。此逾時是無法載入 AWS 或 Google Cloud 憑證的原因之一。失敗發生在本機憑證解析階段：請求從未送達 Amazon Bedrock、Claude Platform on AWS 或 Mantle 端點。Claude Code 會在此錯誤出現之前清除其憑證快取並重試，因此當您看到此錯誤時，憑證鏈已在多次嘗試中停滯。

API Error: Could not load AWS credentials · AWS default-chain credential resolve timed out. Check or refresh your AWS credentials and try again.

常見原因包括：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 秒上限內完成。精靈會停止等待，並使驗證步驟失敗：

Timed out after 60s waiting for AWS. Check your network and proxy settings; if a credential helper needs longer to prompt you, raise CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS.

數字反映的是您的上限：預設為 60 秒，或是您在 CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS 中設定的值。

常見原因包括：網路或代理伺服器使對 AWS 的請求（包括 SSO token 重新整理）停滯，以及憑證輔助程式仍在等待您看不到的輸入。只有在輔助程式確實需要更多時間時才提高上限。

單一對 AWS 的停滯請求也可能因其自身的單次請求逾時而失敗，這會在同一步驟顯示較短的訊息：

A request to AWS timed out. Check your network and proxy settings, then try again.

當相同的逾時發生在模型固定步驟時，精靈會將模型標記為 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 時看到這一行，表示工作階段已在未登入閘道的狀態下開啟：

Cloud gateway session expired — run /login to reconnect.

當閘道憑證過期且 Claude Code 無法續期時，同一行也可能在工作階段進行中出現。

在非互動執行、背景或其他無人值守的工作階段，或 claude auth 以外的 claude 子命令中，當閘道不再接受該工作階段時，Claude Code 會改為以此訊息結束：

Cloud gateway <url> no longer accepts this session. Start `claude` and sign in again with /login.

處理方式：

• 在工作階段中執行 /login 並完成瀏覽器登入
• 若為非互動式啟動，請在相同環境中啟動 claude，執行 /login，然後重新執行您的命令

等待您繼續時登入逾時

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

Sign-in timed out while waiting for you to continue. Try again.

處理方式：

• 再次執行 /login，並在登入過期之前確認帳戶

閘道拒絕了請求

您是透過 Claude apps 閘道登入的，而某個請求傳回了 403：閘道或其背後的上游拒絕了該請求。重新登入無法改變拒絕結果，因此訊息會指向您的閘道管理員：

Gateway refused the request · signing in again won't change this — check with your gateway administrator · API Error: 403 ...

處理方式：

• 請您的閘道管理員查詢該請求。API Error: 後面的內容包含閘道傳回的拒絕資訊
• 對管理員而言：閘道上的存取控制規則會傳回 403，並由稽核日誌記錄其原因；上游的授權拒絕則會依照上游錯誤訊息的方式傳遞

在 v2.1.273 之前，閘道工作階段上的 403 會改為顯示通用的 Please run /login 或 Failed to authenticate 訊息，且重新登入也無法解除該拒絕。

網路和連線錯誤

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

無法連線到 API

到 API 的 TCP 連線失敗或從未完成。對於常見的連線錯誤代碼，訊息會命名失敗的類型並在括號中保留代碼：

Unable to connect to API. Check your internet connection
Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)
Can't reach the API server — check your internet or DNS (ENOTFOUND)
No internet route — check your connection or VPN (EHOSTUNREACH)
Couldn't connect through your proxy (ERR_PROXY_TUNNEL) — the proxy refused the tunnel: check its credentials and that it allows this host
Connection dropped (ECONNRESET)
Request timed out. Check your internet connection and proxy settings

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 和類似的容器執行時可以攔截出站流量。退出它們並重試以排除這種可能性。

無法連線到 Anthropic 服務

在首次執行設定期間，Claude Code 會檢查它是否可以到達 api.anthropic.com 和 platform.claude.com，然後才顯示登入步驟。當任一檢查失敗時，Claude Code 會列印原因並退出。

Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: ECONNREFUSED
Connection to api.anthropic.com timed out after 10 seconds
A proxy is configured via HTTPS_PROXY. Check that it allows connections to the host above.

Claude Code 通過與 API 請求相同的代理設定發送檢查，並給每個探測 10 秒。當失敗的探測通過代理時，訊息會命名設定它的環境變數，例如 HTTPS_PROXY。在 v2.1.222 之前，檢查使用不同的代理傳輸，沒有逾時：在具有 https:// 方案的代理 URL 後面，它可能會在 Checking connectivity... 上無限期停滯，然後即使通過同一代理的 API 請求成功也會失敗。

當受管設定檔案、MDM 原則或原則協助程式將 forceLoginMethod 設定為 "gateway"，或設定 forceLoginGatewayUrl 而不設定 forceLoginMethod 時，Claude Code 會跳過此檢查。使用任一設定，Claude Code 會在雲端閘道畫面上開啟登入步驟，而不是 Anthropic 登入方法。當機器上存在受管設定來源但無法讀取時，Claude Code 也會跳過檢查，因為該來源可能保有閘道設定。在 v2.1.247 之前，Claude Code 在此設定下也執行檢查，當 Anthropic 的端點無法到達時以此錯誤退出。

該怎麼做：

• 如果訊息命名代理變數，檢查其值是否指向正確的代理，並要求您的網路團隊允許通過它到訊息中主機的 HTTPS 連線。請參閱網路設定。
• 完成無法連線到 API 中的檢查。那裡的 curl 測試和防火牆指導也適用於此檢查。
• 如果您的網路是開放的，故障仍然存在，Claude Code 可能在您的國家無法使用

Socket 已關閉

Socket is closed 表示承載串流回應的連線在回應仍在到達時被關閉。最常見的原因是 Windows 上的公司代理在回應中途丟棄已建立的隧道。

根據回應進行的距離，Claude Code 會重試請求、保留 Claude 產生的內容，或結束回合。請參閱自動重試。

在 v2.1.214 之前，Claude Code 不會重試此故障，回合會停止並出現包含 Socket is closed 的錯誤。

該怎麼做：

• 如果您看到此錯誤，請使用 claude update 更新到 v2.1.214 或更新版本，然後再次傳送您的訊息
• 如果在更新後回合在同一代理後面持續失敗，請完成無法連線到 API 並檢查網路設定中的代理設定

API 傳回空的或格式不正確的回應

當 Claude Code 對失敗的串流請求進行非串流重試時，如果獲得 HTTP 成功狀態但主體不是 Claude API 訊息，Claude Code 會顯示此錯誤：通常是 HTML 錯誤或登入頁面、空主體或其他格式的 JSON。代理、閘道或網路登入頁面代替 API 回答是常見來源。Claude Code 不會重試請求，回合以此錯誤結束。

API returned an empty or malformed response (HTTP 200) — check for a proxy or gateway intercepting the request.

在該開頭之後，訊息會報告返回的內容以及哪個請求失敗：

• 一個 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 仍然會回退

串流回應在收到任何完整資料之前結束

來自您的模型提供者的串流回應完成，但未傳遞任何可用資料，因此 Claude Code 重新傳送請求而不進行串流以完成回合。Claude Code 每個工作階段顯示一次警告，僅在互動式工作階段中。在 v2.1.239 之前，Claude Code 無聲地重試而不進行串流。

Streaming response ended before any complete data was received. Retrying without streaming. If this keeps happening, check any proxy or gateway between Claude Code and your model provider.

Claude Code 傳送每個受影響的請求兩次：空串流嘗試和重試。常見原因是在回程中消耗或轉換串流回應主體的代理或閘道。

該怎麼做：

• 設定 Claude Code 和您的模型提供者之間的任何代理或閘道，以未修改的方式傳遞串流回應主體及其標頭
• 在 Amazon Bedrock 上，請參閱閘道或代理後面的串流錯誤以了解標頭和主體要求

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

Claude Code 和 Amazon Bedrock 之間的閘道或代理正在轉換串流回應主體或其 Content-Type 標頭。Amazon Bedrock 將回應串流為 application/vnd.amazon.eventstream。Claude Code 不會解碼無法讀取的主體，而是拒絕報告不同 content-type 的成功串流回應。Claude Code 不會重試請求。

Bedrock streaming response has content-type "text/event-stream"; expected "application/vnd.amazon.eventstream". A gateway or proxy between Claude Code and Bedrock is likely transforming the response body — Bedrock's binary event-stream format must be passed through unmodified. Set CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 to suppress this check while the gateway is being fixed.

在 v2.1.208 之前，相同的設定錯誤在整個回應被緩衝後顯示為 API Error: Truncated event message received。

該怎麼做：

• 設定閘道以未修改的方式傳遞 InvokeModelWithResponseStream 回應主體及其 Content-Type 標頭。重新發出串流為伺服器傳送事件的中介是常見原因。
• 設定 CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 會隱藏此錯誤，但 Claude Code 不會在重寫的標頭下解碼二進位主體，因此這些請求會回退到較慢的非串流路徑。請參閱閘道或代理後面的串流錯誤。

SSL 憑證錯誤

您網路上的代理或安全應用程式正在使用自己的憑證攔截 TLS 流量，Claude Code 不信任它。

Unable to connect to API: SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). The certificate comes from an authority Claude Code doesn't trust, usually a TLS-inspecting corporate proxy or a gateway signed by a private CA: set NODE_EXTRA_CA_CERTS to that CA bundle, or add it to the system certificate store · see https://code.claude.com/docs/en/network-config
Unable to connect to API: Self-signed certificate detected (SELF_SIGNED_CERT_IN_CHAIN). The certificate comes from an authority Claude Code doesn't trust, usually a TLS-inspecting corporate proxy or a gateway signed by a private CA: set NODE_EXTRA_CA_CERTS to that CA bundle, or add it to the system certificate store · see https://code.claude.com/docs/en/network-config

在 v2.1.273 之前，兩個訊息都在 Check your proxy or corporate SSL certificates 結束，沒有 OpenSSL 代碼或 NODE_EXTRA_CA_CERTS 提示。

從 v2.1.199 開始，憑證驗證失敗不會重試，因此此錯誤會在第一次嘗試時出現，而不是在完整重試預算後出現。較早的版本在顯示它之前花費幾分鐘重試。暫時性 TLS 條件（例如握手逾時）仍然會重試。

在 /login 和啟動連線檢查期間，相同的故障會產生不同的訊息：

SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run `claude doctor` for details.

在 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，這會完全停用憑證驗證

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

來自雲端工作階段或例行程式的出站 HTTP 請求被環境的網路原則阻止。

HTTP 403
x-deny-reason: host_not_allowed

您也可能看到與目的地的真實憑證不符的 TLS 憑證。雲端工作階段通過代理路由出站流量，該代理強制執行網路原則，因此不符的憑證表示代理終止了連線，而不是目的地。

這不是用戶端網路問題。雲端工作階段和例行程式在沙箱 VM 內執行，其通過工作階段網路的出站流量被過濾到雲端環境的允許清單；GitHub 操作和 MCP 連接器流量使用單獨的通道，這就是為什麼它們可以在其他主機被阻止時繼續工作。預設環境使用信任存取，允許預設允許清單的套件登錄、雲端提供者 API、容器登錄和常見開發網域，並阻止該路徑上的其他網域。

該怎麼做：

這些步驟會變更您自己的環境之一。組織共享環境在選擇器中以唯讀方式開啟，因此請要求擁有者從管理設定中的雲端環境頁面變更其網路存取。

• 開啟您的環境進行編輯，可從 routine 的表單，或從您啟動雲端工作階段的環境選擇器開啟。
• 在編輯雲端環境對話方塊中，將網路存取從信任變更為自訂，然後將被阻止的網域新增到允許的網域。每行輸入一個網域。勾選也包括常見套件管理員的預設清單以在您的自訂網域旁邊保留預設允許清單。如果您想要不受限制的存取，請改為選擇完整。
• 按一下儲存變更。下一次執行使用更新的允許清單。對於已開啟的雲端工作階段，請參閱網路存取變更何時到達現有工作階段。

請參閱網路存取以了解存取層級和預設允許清單。本機 CLI 工作階段不受此原則影響。

代理拒絕了連線

當 Claude 通過您在 HTTPS_PROXY 中設定的代理或相關代理變數讀取成品時，您會看到此訊息。成品內容來自 *.frame.claudeusercontent.com，因此 Claude Code 首先向代理傳送 CONNECT 請求，要求它開啟到該主機的隧道。當代理拒絕時，沒有任何東西到達主機，訊息攜帶代理的 HTTP 狀態：

artifact content fetch failed (proxy refused the connection: HTTP 407)
artifact content fetch failed (proxy refused the connection: HTTP 403)
the proxy refused the connection to the artifact's content host (HTTP 502)

狀態是代理對 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。如果此探測以相同方式失敗，請先修復代理設定。如果成功，拒絕特定於成品主機。
• 如果您的網路讓 Claude Code 直接到達成品主機，將 .frame.claudeusercontent.com 新增到 NO_PROXY。保持條目狹窄：更廣泛的 .claudeusercontent.com 條目也會繞過 bridge.claudeusercontent.com 的代理，具有 IP 允許清單的組織需要將其保留在代理上。

在 v2.1.238 之前，Claude Code 將拒絕的隧道報告為通用網路錯誤。

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

Claude Code 在多個點請求您的雲端環境清單，例如當您從 CLI 建立雲端工作階段或執行 /remote-env 時。當它無法讀取伺服器的回答時，它會顯示以下其中一個訊息：

The cloud environments service returned an empty response (HTTP 200 with no body). This is usually temporary — try again in a moment.
The cloud environments service returned a response in an unexpected format (HTTP 200 with a non-JSON body). This is usually temporary — try again in a moment.
The cloud environments service returned a response in an unexpected format (HTTP 200 without a usable environments list). This is usually temporary — try again in a moment.

伺服器接受了請求，但用不是環境清單的主體回答：空、不是 JSON 或沒有清單的 JSON。這通常伴隨服務端中斷，並自行清除。根據請求清單的表面，Claude Code 可能會新增前綴，例如 /remote-env 對話方塊中的 couldn't list environments:。

該怎麼做：

• 重試該操作。Claude Code 每次都會再次請求清單
• 如果訊息持續出現，請檢查 status.claude.com 以了解活躍的事件

在 v2.1.236 之前，Claude Code 顯示原始 JavaScript TypeError 而不是這些訊息。

無法重新連線到您的 Remote Control 工作階段

Couldn't reconnect to your Remote Control session. Retry, or start a fresh session without --resume.

使用 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。

此機器離線時工作階段已結束

Claude Code 在執行 claude remote-control 的終端中顯示此訊息，在您的機器離線足夠長的時間後，伺服器清理了您的機器正在提供的 Remote Control 環境。該環境中的工作階段已結束，您無法恢復它們。計數是已結束的工作階段數。

2 sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.

該怎麼做：

• 當 Claude Code 在此訊息下列出保留的 worktrees 時，從它們中拿起任何未提交的工作
• 執行 claude remote-control 以啟動新環境

無法共享文字記錄

在您同意從調查提示（例如工作階段品質調查）共享您的工作階段文字記錄後，Claude Code 將其上傳到 Anthropic，或在第三方提供者上、Claude apps 閘道工作階段上以及當沒有 Anthropic 認證可用時改為儲存本機封存。此訊息表示共享未完成。

Couldn't share the transcript.

上傳必須符合 8 MiB 限制。在長工作階段上，Claude Code 逐步丟棄共享的部分，最後一個請求的模型設定優先，然後是結構化對話和子代理文字記錄，並且只在無法傳送任何縮減版本或網路或伺服器錯誤停止上傳時顯示此訊息。當 Claude Code 改為儲存本機封存時，訊息表示它無法寫入封存。

該怎麼做：

• 執行 /feedback 以傳送文字記錄並描述發生了什麼。如果您的環境中無法使用 /feedback，請參閱報告錯誤
• 如果其他請求也失敗，請檢查您的網路連線並查看無法連線到 API

無法傳送意見反應

您從 /feedback、/bug 或 /share 對話方塊傳送了報告，上傳到 Anthropic 失敗。對話方塊會保留您的文字，以便您可以重試。

Couldn't send feedback (couldn't reach the service). If it keeps failing, you can file at https://github.com/anthropics/claude-code/issues instead.

前綴後的文字會命名失敗的內容：

• ：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. 結束，草稿保留在佇列中以供另一次嘗試。

該怎麼做：

• 對於未登入的措辭，執行 /login 並再次傳送
• 否則，再次傳送；如果其他請求也失敗，請檢查您的網路連線並查看無法連線到 API
• 如果它持續失敗，請在 github.com/anthropics/claude-code/issues 提交報告，如訊息所說

在 v2.1.281 之前，每次傳送在 Remote Control Stop 或緊急跨工作階段訊息在對話方塊開啟時到達後都失敗並出現此訊息。在這些版本上，關閉對話方塊，重新開啟它，然後再次傳送。

請求錯誤

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

提示詞過長

對話加上附加檔案超過了模型的上下文視窗。

Prompt is too long

在互動式工作階段中，Claude Code 將此錯誤顯示為：

Context limit reached · /compact or /clear to continue

當設定了 DISABLE_COMPACT 時，該行僅命名 /clear。較長形式的錯誤（例如下面的壓縮失敗形式）保留 Prompt is too long · 的措辭。在 -p 輸出和文字記錄中，文字保持為 Prompt is too long。

當您在使用者設定中關閉自動壓縮時，該行也會說明這一點：

Context limit reached · /compact or /clear to continue · auto-compact is off · /config to turn it on

/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 將該令牌視為與 Prompt is too long 相同。在 v2.1.228 之前，Claude Code 沒有識別該令牌，因此自動壓縮沒有在其上觸發。

當自動壓縮在此輪上執行並因基礎錯誤（例如不可用的模型或驗證失敗）而失敗時，該訊息在分隔符後命名該錯誤：

Prompt is too long · automatic compaction failed: <the underlying error>

首先解決命名的錯誤；在您這樣做之前，/compact 會因相同錯誤而失敗。在 v2.1.229 之前，失敗的自動壓縮會顯示 Prompt is too long 而不顯示原因。

當自動壓縮在此錯誤上執行時，它通常會總結您最舊的交換並保留最新的。作為最後手段，Claude Code 會以不同方式進行總結：

• 當它無法總結任何完整交換時，Claude Code 會逐字保留您最新的提示，並總結其前面的所有內容。
• 在這種情況下，當對話不以您的提示結尾時，Claude Code 會改為總結整個對話。

當它要轉發的內容不包含模型回覆且您自己的文字少於約 1,000 個令牌（例如在超大貼上後發送的簡短重試）時，Claude Code 會跳過此恢復。執行 /clear 以重新開始。在 v2.1.269 之前，每當壓縮無法總結完整交換時，壓縮就會失敗，因此處於該狀態的工作階段在每一輪都會再次遇到此錯誤。

單一交換對話沒有更早的輪次可以總結。當自動壓縮會在其上執行時，Claude Code 會跳過嘗試並解釋請求中填充的內容。當 API 在其錯誤中不報告令牌計數時，訊息讀取為：

Prompt is too long · this conversation is a single exchange and cannot be compacted — the request size comes mostly from system prompt, tool definitions, or attachments.

當 API 在其錯誤中報告令牌計數時，Claude Code 會將其與自己對對話大小的估計進行比較，以判斷請求的大部分是什麼：對話自己的內容，或 Claude Code 與其一起發送的系統提示、工具定義和附加內容。當對話自己的內容是請求的大部分時，訊息讀取為：

Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) and this conversation's own content is most of it. A single-exchange conversation cannot be compacted; start with less content (smaller files or pasted text).

當請求的大部分在對話之外時，訊息讀取為：

Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) but this conversation is only ~<conversation tokens> tokens — the rest is system prompt, tool definitions, and attachment content. A single-exchange conversation cannot be compacted; reduce attached files/tools or start with less context.

在 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。

請參閱探索上下文視窗以獲得上下文如何填滿的互動式檢視。

上下文超過令牌限制

/context 顯示此警告在其輸出頂部，當對話超過模型的上下文視窗時。在您釋放空間之前，請求會因提示詞過長而失敗。互動式工作階段將該錯誤顯示為 Context limit reached 行。

Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.

當您超過的限制是壓縮視窗（例如 1M 上下文模型上的 200K 邊界）時，警告的讀取方式不同。壓縮視窗可以位於模型的上下文視窗下方，因此超過它的請求仍然可以成功。

Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.

當您設定了 DISABLE_COMPACT 時，兩種形式都命名 /clear 而不是 /compact。

該怎麼辦：

• 在多輪對話中，執行 /compact 以總結較早的輪次並釋放空間。若要改為重新開始，請執行 /clear
• 有關減少使用的更多方式，請參閱提示詞過長

在 v2.1.216 之前，/context 顯示超過 100% 的使用情況，沒有警告行解釋這意味著什麼或如何恢復。

請求過大

原始請求正文在令牌化之前超過了 API 的 32MB 限制，通常是因為大型貼上內容、工具結果或附加檔案。此限制與上下文視窗分開。

Request too large (max 32MB). Accumulated images and attachments in the conversation pushed the request over the limit. Run /compact, or double press esc to go back and remove attachments.

當請求直接進入 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 可以分塊讀取它們
• 對於影像，請參閱下面的影像過大

影像過大

貼上或附加的影像超過了 API 的大小或尺寸限制。

Image was too large. Double press esc to go back and try again with a smaller image.
API Error: 400 ... image dimensions exceed max allowed size

Claude Code 用文字佔位符替換無法處理的影像並重試，因此後續訊息成功。在 2.1.142 之前的版本上，貼上的影像可能保留在對話中，並在後續每條訊息上重複相同的錯誤。若要在這些版本上恢復，按 Esc 兩次並回到添加影像的輪次之前。

該怎麼辦：

• 在貼上之前調整影像大小。API 接受單個影像最長邊最多 8000 像素的影像，或當許多影像在上下文中時最多 2000 像素。
• 拍攝相關區域的更緊密螢幕截圖，而不是整個螢幕

無法調整影像大小

Claude Code 無法在將附加影像發送到 API 之前將其縮小。

Unable to resize image — image processing is unavailable and dimensions could not be read from the file header. Please convert the image to PNG, JPEG, GIF, or WebP.
Unable to resize image — dimensions exceed the 2000x2000px limit and image processing failed. Please resize the image to reduce its pixel dimensions.
Unable to resize image (… raw, … base64). The image exceeds the … API limit and compression failed. Please resize the image manually or use a smaller image.
Unable to resize image — could not verify image dimensions are within the 2000x2000px API limit.
Unable to resize image — it is a CMYK JPEG, which Claude Code cannot decode, and at …px it is over the 2000x2000px limit, so it cannot be sent. Re-save it as an RGB PNG or JPEG and try again.
Unable to resize image — it is an animated WebP whose first frame Claude Code cannot decode, and at …px it is over the 2000x2000px limit, so it cannot be sent. Save its first frame as a PNG or JPEG and try again.
Unable to resize image — its pixels could not be decoded (the file may be damaged, or use an encoding Claude Code cannot read), and it is over the … API limit (… raw, … base64), so it cannot be sent. Re-save it as a PNG or JPEG and try again.

Claude Code 通常會自動調整大型影像的大小。這些錯誤意味著影像無法解碼或調整大小以符合 API 限制。

該怎麼辦：

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

PDF 錯誤

您附加的 PDF 無法處理。訊息在此以非互動形式顯示；在互動式工作階段中，它們會提示您按 Esc 兩次並重試。

PDF too large (max 100 pages, 20MB). Try reading the file a different way (e.g., extract text with pdftotext).
PDF is password protected. Try using a CLI tool to extract or convert the PDF.
The PDF file was not valid. Try converting it to text first (e.g., pdftotext).

該怎麼辦：

• 對於超大 PDF，要求 Claude 使用 Read 工具讀取頁面範圍而不是附加整個檔案，或使用 pdftotext 之類的工具提取文字並按路徑參考輸出檔案
• 對於受保護或無效的 PDF，移除密碼或從其來源應用程式重新匯出檔案，然後重試

當 Claude 使用 Read 工具從 PDF 讀取頁面範圍時，讀取可能因不同訊息而失敗：

pdftoppm is not installed. Install poppler-utils (e.g. `brew install poppler` or `apt-get install poppler-utils`) to enable PDF page rendering.

頁面範圍讀取使用 pdftoppm 呈現頁面。使用訊息提供的命令安裝 poppler-utils，或在其他平台上安裝將 pdftoppm 放在您的 PATH 上的 poppler 組建。請參閱Read 工具行為以了解哪些 PDF 按頁面範圍讀取。

不允許額外輸入

Claude Code 和 API 之間的代理或 LLM 閘道去除了 anthropic-beta 請求標頭，因此 API 拒絕了依賴它的欄位。

API Error: 400 ... Extra inputs are not permitted ... context_management

Claude Code 會發送測試版專用欄位（例如 context_management），並附上啟用它們的 anthropic-beta 標頭。當閘道轉發本文但刪除標頭時，API 會看到它無法識別的欄位。

該怎麼辦：

• 配置您的閘道以轉發 anthropic-beta 標頭。請參閱功能傳遞以了解閘道必須轉發的內容。
• 作為備用，在啟動前設定 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1。禁用預發行功能涵蓋確切範圍。

工具輸入架構無效

請求中的工具聲明了 input_schema，該架構未通過 API 的 JSON Schema 驗證，因此 API 拒絕了整個請求。tools. 後面的數字是失敗工具在請求的工具列表中的位置，而不是您可以查找的名稱。

API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid
API Error: 400 ... tools.N.custom.input_schema.properties: Property keys should match pattern '^[a-zA-Z0-9_.-]{1,64}$'

第一種形式意味著架構不是有效的 JSON Schema draft 2020-12。第二種意味著頂級屬性名稱與訊息引用的模式不匹配。

Claude Code 在載入伺服器的工具時排除輸入架構會失敗此驗證的 MCP 工具，因此請求通常永遠不會包含一個。

在標誌擷取關閉的部署上，或在標誌從未到達的機器上，Claude Code 在伺服器的日誌中記錄哪個工具會被拒絕，但無論如何都會發送它，因此此錯誤仍然可能發生。

該錯誤也可能發生在工具的架構在 $schema 中聲明 JSON Schema 方言而不是 draft 2020-12 的情況下。Claude Code 不會根據 JSON Schema 元架構檢查這些架構，儘管頂級屬性名稱檢查仍然適用。

在 v2.1.216 之前，沒有部署執行排除檢查。

該怎麼辦：

• 如果您的 Claude Code 版本早於 v2.1.216，請執行 claude update。
• 移除或禁用聲明無效架構的 MCP 伺服器。該錯誤僅按位置命名工具。在 v2.1.216 或更高版本上，檢查每個伺服器的日誌以查找命名輸入架構會被拒絕的工具的行。如果沒有日誌命名一個，請一次禁用一個伺服器。
• 如果您維護伺服器，請修復工具的 input_schema。架構必須是有效的 JSON Schema，頂級屬性名稱必須是 1 到 64 個字元長，並且只使用 ASCII 字母和數字、_、. 和 -。請參閱輸入架構無效的工具。

tool\_use.name 超過 200 個字元

對話歷史記錄中的工具呼叫攜帶的名稱長度超過 API 在請求中接受的 200 個字元：

API Error: 400 ... tool_use.name: String should have at most 200 characters

Claude Code 在回應到達時以及載入已保存的對話時將此類名稱切割為 200 個字元，因此呼叫失敗並出現普通的 No such tool available 工具錯誤，對話繼續而不出現此 API 錯誤。

該怎麼辦：

• 執行 claude update，然後繼續對話。更新的版本在載入文字記錄時修復超長名稱，因此卡住的對話再次工作。

在 v2.1.281 之前，超長名稱保留在歷史記錄中，API 拒絕了重新發送對話的每個請求，包括 /compact 和 --resume，因此此錯誤重複出現，對話被卡住。

選定的模型有問題

配置的模型名稱未被識別，或您的帳戶缺少對其的存取權限。從 v2.1.160 開始，尾部提示（此處以其互動形式顯示）因表面而異。

There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to pick a different model.

該怎麼辦：

• 互動式 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 登入報告為登入已過期，而不是此錯誤。在 v2.1.206 之前，無法再刷新的過期登入對每個模型都失敗，並出現此錯誤；如果您在較舊版本上看到此錯誤，請執行 /login。
• 對於 Google Cloud 的 Agent Platform 部署，請參閱 Google Cloud 的 Agent Platform 故障排除。

模型不是公認的模型 ID

您傳遞給模型切換的字串不是 Claude Code 可以用作模型的字串，因此它拒絕了切換而不發送請求，工作階段保留其目前模型。當模型通過 Agent SDK setModel() 方法設定時，您可能會收到此錯誤，由為您執行 Claude Code CLI 的應用程式（例如桌面應用程式），或當您從通過遠端控制連接的裝置選擇模型時。在 v2.1.200 之前，Claude Code 保存了字串並在下一個請求時因選定的模型有問題而失敗。

Model "Sonnet5" is not a recognized model id. Did you mean 'claude-sonnet-5'?

在此範例中，應用程式發送了顯示名稱 Sonnet 5，訊息重複時沒有其空格。尾部提示命名最接近的匹配別名或模型 ID。當沒有足夠接近的內容時，它讀取 Run /model to see available models. 代替。在桌面應用程式為您啟動的工作階段中，無匹配提示讀取 Switch to a different model.

當您通過 Agent SDK 或在 Anthropic API 上的應用程式切換時，只有無法成為模型 ID 的字串（例如顯示名稱或空字串）會收到此錯誤。

當您從遠端控制裝置選擇模型時，Claude Code 在本地檢查字串。任何不是模型別名、Claude Code 列出或您配置的模型，或以 claude- 開頭的 ID 的字串都會收到此錯誤，包括拼寫錯誤的 ID（例如 claud-sonnet-5）。在 v2.1.260 之前，此檢查不涵蓋遠端控制選擇，因此無法識別的字串被應用，並在下一個請求時失敗。

該怎麼辦：

• 執行 /model 而不帶引數以開啟選擇器並從您帳戶可用的模型中選擇，然後傳遞那裡顯示的別名或 ID
• 如果您使用了較新 Claude Code 版本支援的別名，請執行 claude update，或傳遞模型的完整 ID 代替。伺服器仍然可以要求該模型的最低 Claude Code 版本；請參閱 Claude Code 不支援此模型。
• v2.1.200 之前保存的模型不會被此檢查修復。如果過時的值不斷出現，請從設定您的模型下列出的位置移除它。
• 在 Anthropic API 以外的任何提供者上，或在閘道或自訂 ANTHROPIC_BASE_URL 後面，只有空字串會收到此錯誤。Claude Code 仍然可以在請求時寫入無法識別的模型診斷行，在每個提供者上。

找不到模型

您使用名稱切換到模型，Claude Code 無法確認存在具有該名稱的模型。當名稱不是模型別名或 Claude Code 在本地接受的其他拼寫時，Claude Code 使用最小 API 請求驗證它，此錯誤通常是您的 API 端點的答案。無法成為模型 ID 的名稱（例如包含空格的名稱）會收到相同訊息。

Model 'claude-opus-9' not found

在具有提供者特定模型 ID 的提供者上，訊息可能會添加 Try '...' instead 建議，該建議命名您提供者的備用模型 ID。

該怎麼辦：

• 執行 /model 而不帶引數並從您帳戶可用的模型中選擇，或使用模型別名（例如 sonnet），該別名解析為維護的預設值
• 如果您輸入了完整 ID，請根據您提供者的模型目錄檢查它。新推出的模型可能在 Anthropic API 上可用，然後您的提供者或地區才提供它。
• 在 Agent SDK 中，setModel() 因此訊息而失敗，工作階段在其先前的模型上繼續執行。在 TypeScript SDK 中，呼叫 supportedModels() 以列出您可以切換到的模型。
• 在 v2.1.265 之前，/model 也以此錯誤拒絕了 opusplan[1m] 別名拼寫。在這些版本上，更新 Claude Code，或在設定中或使用 --model 代替設定模型。

無法使用 API 確認模型

您通過 Agent SDK setModel() 方法或為您執行 Claude Code CLI 的應用程式（例如桌面應用程式）切換了模型，確認模型 ID 與您的 API 端點的請求在五秒內沒有得到答案。工作階段保留其目前模型。

Couldn't confirm model "claude-sonnet-5" with the API. Try again, or run /model to see available models.

在桌面應用程式為您啟動的工作階段中，訊息在 Try again. 結尾。

該怎麼辦：

• 再次切換到模型
• 如果切換不斷失敗，請檢查 Claude Code 是否可以到達您的 API 端點；請參閱網路和連接錯誤

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

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

API error: 429 <the server's explanation> · model not changed

訊息的中間是 HTTP 狀態和伺服器自己的解釋。

該怎麼辦：

• 根據伺服器的解釋採取行動；對於速率限制或 5xx 狀態，等待並再次選擇模型
• 具有自己措辭的拒絕由周圍條目涵蓋，例如找不到模型和模型受您組織的設定限制

Claude Opus 不適用於 Claude Pro 計畫

您的有效訂閱計畫不包括您選擇的模型。

Claude Opus is not available with the Claude Pro plan. If you have updated your subscription plan recently, run /logout and /login for the plan to take effect.

在 Claude 桌面應用程式執行的工作階段中，訊息說改為 sign out and sign in again 而不是命名命令。

該怎麼辦：

• 執行 /model 並選擇您的計畫包括的模型
• 如果您最近升級了計畫但仍然看到此訊息，請執行 /logout 然後 /login。儲存的令牌反映您登入時的計畫，因此在現有工作階段中在 claude.ai 上升級不會生效，直到您重新驗證。
• 請參閱 claude.com/pricing 以了解每個計畫包括哪些模型

Claude Code 不支援此模型

API 因為您的 Claude Code 版本低於所需的最低版本而拒絕了請求，並返回 400。您選擇的模型需要較新版本（伺服器按模型檢查），或您組織的政策需要一個。400 攜帶錯誤代碼 claude_code_version_too_old，訊息說明適用的最低版本。

API Error: 400 Claude Code 2.1.219 does not support this model; version 2.1.255 or newer is required. Run 'claude update', or update the Claude desktop app, then try again.

組織政策措辭讀取為：

API Error: 400 Claude Code 2.1.240 is older than the minimum version required by your organization's policy. Run 'claude update', or update the Claude desktop app, to continue.

發送請求的 Claude Code 二進位檔案報告的版本是 API 檢查的版本。

該怎麼辦：

更新該二進位檔案，然後啟動新工作階段。二進位檔案的來源決定了如何，除了在自託管環境中：

• 對於按模型措辭，您可以通過切換到另一個模型來在目前工作階段中繼續工作：在 CLI 中執行 /model，在 TypeScript SDK 的 Query 物件上呼叫 setModel()（在串流輸入模式中），或在 Python SDK 的 ClaudeSDKClient 上呼叫 set_model()
• 對於組織政策措辭，在繼續之前更新

模型受您組織的設定限制

您的組織管理員在 claude.ai 管理控制台中禁用了此模型，或受管設定通過 availableModels 允許清單或 deniedModels 清單排除了它。當 --model、ANTHROPIC_MODEL 或 model 設定命名受限制的模型時，通知在啟動時出現，並命名工作階段改為使用的模型。如果受管設定沒有為工作階段留下允許的模型，請參閱受管設定阻止預設模型。替換通知也可能在工作階段中期出現，在管理員在 claude.ai 管理控制台中禁用工作階段執行的模型之後。

Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.

為受限制的模型輸入 /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.

前綴為代理、技能或命令名稱的通知意味著限制適用於該子代理的請求模型：子代理在替換模型上執行，您的工作階段模型保持不變。在 v2.1.223 之前，Claude Code 僅對使用 Agent 工具啟動的子代理顯示通知。

Claude Code 將模型系列別名（opus、sonnet、haiku 或 fable 之一）視為對該系列的請求，而不是對其最新版本的請求。在 Anthropic API 和AWS 上的 Claude Platform 上，受限制的系列別名解析為您組織的設定允許的系列的最新版本，替換通知命名該版本。Claude Code 僅當系列的每個版本都受限制時才拒絕 /model <alias>。在 v2.1.205 之前，系列別名基於其最新版本單獨被替換或拒絕，即使允許同一系列的較舊版本。

該怎麼辦：

• 執行 /model 以從您組織允許的模型中選擇。受限制的模型在選擇器中隱藏。
• 如果受限制的模型是在 --model、ANTHROPIC_MODEL、設定檔案的 model 欄位或子代理、技能或命令的 model frontmatter 中設定的，請移除或更新該值，以便通知不會再次出現
• 如果您需要存取受限制的模型，請要求您的組織管理員啟用它。請參閱組織模型限制。

無法切換到預設模型

您選擇了預設模型，例如通過在 /model 選擇器中選擇預設行或輸入 /model default。Claude Code 拒絕了切換，因此工作階段保留其目前模型。

Can't switch to the default model: your organization's managed settings block it (claude-opus-4-6) in "deniedModels", and none of the models they allow can be used as the default instead. Ask your administrator to update "deniedModels" or "availableModels".

冒號後的措辭命名阻止切換的內容：

• 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 訊息，請參閱受管設定阻止預設模型。

模型切換被 PreModelSwitch hook 阻止

PreModelSwitch hook 沒有批准您或用戶端請求的模型切換，因此工作階段保留其目前模型。當切換來自 Agent SDK 主機或遠端控制而不是您輸入的命令時，訊息讀取 Model switch blocked by a PreModelSwitch hook 而不命名目標模型。

Model switch to Opus 4.6 was blocked by a PreModelSwitch hook: Opus 4.6 is retired for this project. Use a newer model.

冒號後的原因說明拒絕切換的原因：

• 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 重試外掛程式載入一次，然後在工作階段中拒絕後續切換，即使您的組織沒有受管外掛程式。在這些版本上重新啟動工作階段以再次執行外掛程式載入。

無法將其保存為您的預設值

您選擇了模型以保存為預設值，例如使用 /model <name> 或 /model 選擇器中的 Enter，Claude Code 無法將選擇寫入您的使用者設定檔案 ~/.claude/settings.json。切換本身已應用，因此目前工作階段在您選擇的模型上執行，但您的預設值保持不變，下一個工作階段在舊值上啟動。

Set model to Fable 5.1 for this session only · couldn't save it as your default: ~/.claude/settings.json can't be written (EROFS)

檔案路徑後的原因說明失敗的內容：

• 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 即使寫入失敗。

此模型不支援 thinking.type.enabled

您的 Claude Code 版本早於所選模型的最低版本。CLI 發送了模型不再接受的思考配置。

API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

該怎麼辦：

• 執行 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

您關閉了延伸思考並以努力級別 high 以上執行。模型不接受該組合，因此 API 拒絕了請求。

API Error: Effort 'xhigh' isn't available with thinking turned off on this model · run /effort high to continue, or turn thinking back on (unset MAX_THINKING_TOKENS=0)

· 後的提示因工作階段而異：在非互動式工作階段中，它讀取 use --effort high (or the effortLevel setting)，在 Claude 桌面應用程式執行的工作階段中，它讀取 you can lower effort to High。

該怎麼辦：

• 降低努力級別至 high 或以下。
• 打開思考，例如通過取消設定 MAX_THINKING_TOKENS 或從您的設定中移除 "alwaysThinkingEnabled": false。

在 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 以您設定的努力級別發送請求，因此 Opus 5 拒絕了關閉思考時 high 以上的每個請求。Claude Code 現在改為向它知道拒絕該組合的模型（例如 Opus 5）發送努力 high。

思考預算超過輸出限制

配置的延伸思考預算超過最大回應長度，因此沒有空間留給實際答案。

API Error: 400 ... max_tokens must be greater than thinking.budget_tokens

該怎麼辦：

• 將 CLAUDE_CODE_MAX_OUTPUT_TOKENS 提高到思考預算以上
• 請參閱延伸思考以了解預算如何與輸出長度互動

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

對話歷史記錄以不一致的狀態到達 API。

API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.
API Error: 400 orphaned tool_result in conversation history. Run /rewind to recover the conversation.
API Error: 400 duplicate tool_use ID in conversation history. Run /rewind to recover the conversation.
API Error: 400 ... unexpected `tool_use_id` found in `tool_result` blocks
API Error: 400 ... thinking blocks ... cannot be modified

所有變體意味著相同的事情：歷史記錄中 tool_use、tool_result 和 thinking 區塊的序列不再與 API 期望的相符。

該怎麼辦：

• 如果您使用 Opus 4.7 或 Opus 4.8，請先執行 claude update。v2.1.156 之前的版本可以在正常工具使用期間觸發此錯誤，/rewind 不會清除它。
• 執行 /rewind 或按 Esc 兩次，以回到損壞輪次之前的檢查點並從那裡繼續。請參閱檢查點以了解檢查點如何建立和恢復。

redacted\_thinking 區塊中的資料無效

API 因為它無法接受對話歷史記錄中較早輪次攜帶的 redacted_thinking 區塊而拒絕了請求，並返回 400。

API Error: 400 ... Invalid `data` in `redacted_thinking` block

Claude Code 將對話的較早思考排除在請求之外並重試一次，因此工作階段繼續而不顯示錯誤。在 v2.1.282 之前，Claude Code 保留了被拒絕的區塊，每個後續輪次都因相同錯誤而失敗。

該怎麼辦：

• 如果您在 v2.1.281 或更早版本上，每一輪都因此錯誤而失敗，請執行 claude update 並繼續工作階段
• 如果錯誤持續，請執行 /clear 以啟動不攜帶該區塊的對話

移除了不支援的工具內容

當 Claude Code 直接連接到 Anthropic API 並載入或預覽已保存的工作階段時，它會移除 Anthropic API 不接受的工具內容，並在移除的內容位於兩個思考區塊之間的位置留下此行：

[Unsupported tool content removed]

當 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 之前的版本不會移除內容。

角色 'system' 必須在 'assistant' 訊息之前

API 因為系統訊息位於它不接受的對話位置而拒絕了請求，並返回 400：

API Error: 400 messages.6: role 'system' must precede an 'assistant' message or end the array; ...

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 本身發送的時，錯誤也出現，對話的每個後續輪次都以相同方式失敗。

搜尋結果區塊中的加密內容無效

API 因為對話歷史記錄包含它無法解密的託管網路搜尋內容而拒絕了請求，並返回 400。措辭命名它無法讀取的欄位：

API Error: 400 ... Invalid `encrypted_content` in `search_result` block
API Error: 400 ... Invalid `encrypted_index` in `text` block
API Error: 400 ... Failed to decrypt web search result content
API Error: 400 ... Invalid `encrypted_stdout` in `encrypted_code_execution_result` block

來自 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 拒絕回應，因為對話中的內容觸發了使用政策檢查。

訊息包括您可以引用給支援的請求 ID 和訊息 ID，如果您認為拒絕不正確。

API Error: Opus 4.6 can't help with this. Start a new session to continue.

Send feedback with /feedback or learn more: https://www.anthropic.com/legal/aup

訊息命名拒絕的模型，或當沒有記錄模型時命名 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 切換到不同的模型也可能在某些情況下解決拒絕。

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

模型的安全措施將對話中的內容標記為網路安全主題。訊息命名標記請求的模型：

API Error: Opus 4.8's safeguards flagged this message. Our intentionally broad safeguards allow us to deliver more capabilities faster, but can sometimes flag legitimate cybersecurity work. Apply to the Cyber Verification Program to reduce these interruptions. Send feedback with /feedback or learn more: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude

訊息連結到網路安全驗證計畫，該計畫為合法網路安全工作授予存取權限。在 Opus 5.5 和 Sonnet 5.5 上，訊息以 <model>'s safeguards flagged this session 開頭。當標記的類別有可用的備用模型時，Claude Code 切換模型而不是顯示此錯誤。

在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，網路安全標記會產生使用政策拒絕訊息。

安全措施本身是伺服器端的，早於 v2.1.203；自那時以來的用戶端版本僅更改了訊息的措辭。 從 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: 後跟豁免表單連結。

該怎麼辦：

• 如果您的工作需要此內容，請通過網路安全驗證計畫申請存取權限
• 如果您的請求不是關於網路安全主題，請執行 /feedback 以報告誤報
• 若要在同一工作階段中繼續工作，請按 Esc 兩次或執行 /rewind 以回到觸發標記的輪次之前的檢查點，然後採取不同的方法。請參閱檢查點。

安裝錯誤

這些錯誤會在安裝或更新 Claude Code 時出現，來自 安裝指令碼、claude install 或 claude update。如需 command not found、PATH、權限和設定期間的 TLS 問題，請參閱 疑難排解安裝和登入。

安裝在完成前被中止

安裝指令碼會在 claude install 步驟被信號終止時報告。在 Linux 上，結束代碼 137 表示程序收到 SIGKILL，在低記憶體主機上通常是核心記憶體不足 (OOM) 殺手。指令碼會列印此說明並以代碼 137 結束：

Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.
Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.

對於任何其他致命信號，以及 macOS 上的結束代碼 137，指令碼會列印 Installation was killed before it could finish (exit code <N>)，其中包含實際結束代碼，並省略記憶體不足的說明。該訊息來自 macOS 和 Linux 使用的安裝指令碼，也涵蓋 WSL 內的安裝；原生 Windows 安裝指令碼永遠不會列印它。在 v2.1.200 之前，指令碼只以 shell 的裸 Killed 行結束。

該怎麼做：

• 停止其他程序以釋放記憶體，然後重新執行安裝程式
• 新增交換空間或移至更大的執行個體。請參閱 在低記憶體 Linux 伺服器上安裝被中止 以取得交換檔案命令。

下載更新時連線中斷

在 claude install 或 claude update 擷取 Claude Code 二進位檔案時，與下載伺服器的連線已關閉，且重試未能復原。Claude Code 會在連線中斷、傳輸停滯或下載的檔案未通過總和檢查時重試下載，總共最多三次嘗試。已完成的 HTTP 錯誤（例如 404）不會重試，因為伺服器已經回應。在 v2.1.202 之前，單一連線中斷會立即導致下載失敗，並顯示裸錯誤 aborted，而不是重試。

The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.

括號中的文字命名失敗的嘗試和基礎網路錯誤。claude update 在 stderr 上以 Error: Failed to install native update 開頭該訊息。

保持連線但未在 10 分鐘內完成的下載會失敗，並顯示 Download timed out: exceeded the total deadline。Claude Code 不會重試逾時的下載，因為連線太慢而無法在期限內完成，在立即重試時也不會完成。以下步驟適用於兩個訊息。

代理或閘道可以在長傳輸完成前關閉它，而 Claude Code 二進位檔案是大型下載。

該怎麼做：

• 再次執行 claude update。在網路狀況良好的情況下，下載通常在下次執行時成功。對於逾時訊息，請從更快或限制較少的網路重新執行。
• 如果您的網路需要代理，請在執行安裝程式或 claude update 之前設定 HTTPS_PROXY。請參閱 檢查網路連線。
• 如果公司代理持續關閉傳輸，請要求您的網路團隊允許從 downloads.claude.ai 進行完整下載。請參閱 網路存取需求。
• 從您的 shell 執行 claude doctor 以進行安裝診斷

命令列錯誤

這些錯誤來自 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 之前，這種組合會默默建立一個永遠無法附加的背景工作。

--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.

處理方式：

• 移除 -p 或 --print。--bg 以位置引數接收提示詞，因此 claude --bg "<task>" 就是完整的命令。請參閱從您的 shell 分派新的 agent。
• 若要以非互動方式執行提示詞並印出結果，而不是建立背景工作階段，請移除 --bg 並執行 claude -p "<task>"

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

您在一次 claude 呼叫中同時傳入了 --append-subagent-system-prompt 與 --append-subagent-system-prompt-file，因此 claude 會以退出碼 1 結束，而不會啟動工作階段：

Error: Cannot use both --append-subagent-system-prompt and --append-subagent-system-prompt-file. Please use only one.

在 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 無論如何都會啟動工作階段。

Error: Invalid --agents configuration:
<what failed>

第一行之後的內容取決於該值失敗的方式。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 也可能以這種方式失敗。請檢查路徑或引號，然後再次執行命令。

處理方式：

• 修正訊息列出的每個問題，然後再次執行命令。請參閱 CLI 定義之 subagent 可接受的欄位。

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

當您以 --restricted 啟動工作階段時，Claude Code 會拒絕從該工作階段建立雲端工作階段，因為新的工作階段會在受限程序之外執行，而不會強制執行受限模式。Claude Code 會在用戶端、聯絡伺服器之前就拒絕，因此不會建立任何雲端工作階段：

Cloud sessions cannot be created from a --restricted session: they would not enforce it.

處理方式：

• 在受限工作階段中於本機執行該任務
• 如果您能控制工作階段的啟動方式，請在不使用 --restricted 的情況下啟動新的 claude 工作階段，並從那裡建立雲端工作階段

在 v2.1.248 之前，Claude Code 沒有 --restricted 旗標；較早的版本會以未知選項錯誤拒絕該旗標本身。

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

您組織的 allow_remote_sessions 政策已關閉，因此無法使用雲端工作階段及使用它們的命令：

Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.

當您從終端機建立雲端工作階段時，以及當您送出需要雲端工作階段的命令（例如 /teleport、/remote-env 或 /web-setup）時，就會出現此訊息。在 v2.1.268 之前，送出這些命令之一會改為回傳 Unknown command。

這是伺服器端的組織政策，因此無法透過本機設定、環境變數或 CLI 旗標覆寫。

如果 Claude Code 尚未載入您組織的政策或無法擷取政策，這些命令會改為回應 Couldn't verify your organization's policy for cloud sessions. Check your network connection, then restart Claude Code and try again.。

處理方式：

• 請您組織中的 Owner 在 claude.ai/admin-settings/claude-code 的 Claude Code 管理設定中啟用雲端工作階段
• 如果訊息表示無法驗證政策，請檢查您的網路連線，然後重新啟動 Claude Code 並再試一次

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

您在非互動模式中傳給 --json-schema 的 schema 未能通過 JSON Schema 編譯，因此 claude 會以退出碼 1 結束，而不會執行提示詞。在 v2.1.205 之前，無效的 schema 會產生非結構化輸出而不報錯，且任何使用 format 關鍵字的 schema 都會被視為無效。

Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values

第二個冒號之後的文字是驗證器的診斷訊息，會指出失敗的關鍵字或位置。使用 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 之類的裝置檔案會讓記憶體無限制地增長。

Error: Settings file exceeds the 2MiB limit: /path/to/settings.json

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 上輸出壓縮過的套件原始碼與原始的 ENOENT ... uv_cwd 堆疊，而不是此訊息。

The current directory no longer exists (it was deleted or moved). Start Claude Code from an existing directory.
error: The current working directory was deleted, so that command didn't work. Please cd into a different directory and try again.

兩種形式的原因與修正方法相同。

當 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: no space left on device, mkdir '/tmp/claude-501'

Temp directory /tmp/claude-501 is not a directory (may be an attacker-planted symlink). Refusing to use it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it.

Temp directory /tmp/claude-501 is owned by uid 502, expected 501. Refusing to use it — another user may have pre-created it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it.

Temp directory /tmp/claude-501 is not readable (its mode may have been altered, or a path component denies search). Refusing to use it — restore its permissions (chmod 0700) or remove it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it.

處理方式：

• 對於 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 無法解析該位置時，它不會載入任何內容，並顯示此訊息：

packages/app couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded. Check that it is a directory inside the working directory and try again.

處理方式：

• 確認該路徑指向工作目錄內的實際目錄，然後再次執行 /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. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog.

另外兩種同樣以 Error: Workspace not trusted. 開頭的變體，會出現在太小而無法顯示信任該目錄會啟用哪些功能的終端機中，或未回報其大小的終端機中。請放大視窗或切換到一般終端機視窗，然後再次執行 claude rc。

在您的家目錄中，訊息會不同，因為工作區信任對話框永遠不會為家目錄儲存信任，因此在那裡接受它無法滿足此檢查。在 v2.1.214 之前，家目錄會顯示上述訊息，而其建議在那裡無法成功。

Error: Workspace not trusted. /Users/you is your home directory, and for security home-directory trust is never saved, so running `claude` here first won't help. Run `claude rc` from a project directory instead (run `claude` there once to accept the trust dialog).

如果您在 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 會改為拒絕啟動，並指出該旗標：

Error: `--settings` before `remote-control` is not carried over to the sessions Remote Control starts, so Remote Control refuses to start rather than drop it — remove it, and give Remote Control's own options after the verb (see `claude remote-control --help`).

Claude Code 不會拒絕那些捨棄後無害的全域旗標，例如 --verbose、--model，或由包裝程式注入的 --session-id 或 --plugin-dir：它會忽略這些旗標，Remote Control 照常啟動。

對於尚未被 Claude Code 認定為無害的全域旗標，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 錯誤失敗。

此建置尚無法使用 claude import

您執行了 claude import，而 Claude Code 發現匯入流程已關閉，因此該命令會以退出碼 1 結束，而不會開始匯入。在 v2.1.222 之前，匯入流程關閉的建置會將 import 當成提示詞，並啟動互動式工作階段，而不是印出此訊息。

`claude import` is not yet available in this build. Run `claude` and use /mcp or edit ~/.claude/settings.json directly.

Claude Code 透過從 Anthropic 擷取並快取在磁碟上的功能旗標來開啟 claude import。此訊息表示快取的值為關閉。原因通常是下列之一：

• 您在安裝後尚未啟動過工作階段，因此 Claude Code 尚未擷取該旗標。即使您可以使用此功能，第一次執行 claude import 也可能印出此訊息。
• 您透過 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Claude Platform on AWS，或透過 Claude apps 閘道使用 Claude Code。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 會啟動互動式工作階段，由其復原對話框處理該檔案。

Could not read Claude Code config — run `claude` with no arguments to recover it.

處理方式：

• 不帶任何引數執行 claude。Claude Code 會偵測到無效的檔案並提供重設選項。然後再次執行 claude import。
• 若要保留您手動進行的編輯，請改為在編輯器中修正 ~/.claude.json 的 JSON 語法，然後重新執行 claude import

無法從 Claude Desktop 匯入伺服器

Claude Code 無法新增您在 claude mcp add-from-claude-desktop 中選取的其中一個伺服器。該命令仍會匯入其他選取的伺服器，並為每個無法新增的伺服器印出一行訊息。在 v2.1.205 之前，第一個失敗的伺服器會中止匯入。

Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.

伺服器名稱之後的文字就是原因。最常見的是名稱檢查：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 伺服器新增到 managed 範圍

您以 --scope managed 執行了 claude mcp add 或 claude mcp add-json。該範圍存放您組織透過 managedMcpServers 受管設定所提供的伺服器。Claude Code 只會從受管設定讀取這些伺服器，因此該命令無法將伺服器寫入該範圍。

Cannot add MCP server to scope: managed

處理方式：

• 將伺服器新增到您可寫入的範圍：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 結束，而不會儲存一個永遠不會載入的伺服器：

Cannot add MCP server: your organization's managed settings allow only MCP servers that plugins provide. Install a plugin that provides this server, or ask your administrator to make it available.

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，因此會以此錯誤結束，而不會讀取該檔案。

Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes. Fix or remove it, then run the command again.

在 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 在寫入後讀回該檔案時，變更並不在檔案中。該命令會以此錯誤結束，而不是顯示其成功訊息。

MCP server "example" was not saved to /home/user/.claude.json. If that file is read-only or protected by a sandbox, make it writable or run the command outside the sandbox, then add the server again.

移除後，訊息會顯示 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 以確認變更。該變更可能已寫入磁碟，也可能沒有。括號中的文字是該次讀取的錯誤。

MCP server "example" may not have been saved: /home/user/.claude.json could not be read to confirm the change (EACCES: permission denied, open '/home/user/.claude.json'). Run `claude mcp get example` to check, then add the server again if it is missing.

移除後，訊息會顯示 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 進行。

"gmail" is Anthropic-hosted and doesn't support local OAuth. Connect it via Settings → Connectors on claude.ai (requires `claude login`), then it'll be available here automatically.

處理方式：

• 以 claude mcp remove <name> 移除您的項目，使其不會遮蔽相同 URL 上的 claude.ai 連接器
• 移除之後，在登入您於 Claude Code 中使用的帳戶時，於 claude.ai/customize/connectors 連接該服務。連接後，如果您目前的身分驗證方式是 claude.ai 訂閱登入，該連接器會自動出現在 Claude Code 中

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

一個由 headersHelper 提供 Authorization 標頭的 MCP 伺服器以 HTTP 401 或 403 回應連線，因此 Claude Code 將連線回報為失敗。由於該輔助程式提供了 Authorization 標頭，Claude Code 不會改用 OAuth 連接該伺服器：

Server rejected the Authorization header minted by the configured headersHelper (HTTP 401). Check that the helper command returns a valid credential for this MCP endpoint — OAuth fallback is disabled when the helper supplies Authorization.

Claude Code 會在每次嘗試連線時重新執行該輔助程式，因此在暫時性拒絕（例如 token 輪替競爭）之後重試，可能會以新的憑證成功。

處理方式：

• 以 Claude Code 執行它的方式自行執行 headersHelper 命令：從 Claude Code 執行它的目錄執行，帶有 Claude Code 為其設定的環境變數，並且對於來自專案 .mcp.json、外掛或專案 agent 檔案的伺服器，不包含 Claude Code 會移除的憑證變數。確認它印出的 Authorization 值能被伺服器的端點接受
• 修正輔助程式或其憑證來源之後，在 /mcp 中選取該伺服器並選擇 Reconnect

在 v2.1.248 之前，Claude Code 會對由輔助程式提供 Authorization 標頭的伺服器執行 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 之前，啟動時不會等待伺服器完成連線，因此啟動緩慢但正常的伺服器也會產生此錯誤。

Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none

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 會挑選一個可用的連接埠。

OAuth callback port <port> is already in use — another process may be holding it. Run `lsof -ti:<port> -sTCP:LISTEN` to find it.

在 Windows 上，建議的命令則是 netstat -ano | findstr :<port>。

處理方式：

• 執行訊息中的命令以找出佔用該連接埠的程序，並停止它或等待它結束
• 如果其他程式需要永久使用該連接埠，請向伺服器註冊不同的重新導向 URI，並以 MCP_OAUTH_CALLBACK_PORT 或 --callback-port（視您使用哪一個）設定其連接埠
• 然後再次啟動登入，例如在 /mcp 中選取該伺服器

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

當您以 OAuth 登入遠端 MCP 伺服器時，Claude Code 會啟動一個本機監聽器來接收登入回呼。當 Claude Code 無法為其綁定本機連接埠時，登入就會以此訊息失敗。機器上有某些東西阻止它在 127.0.0.1 上監聽，例如安全軟體或拒絕本機監聽器的沙箱政策。

No available ports for OAuth redirect

在 v2.1.268 之前，Claude Code 不會改用作業系統指派的連接埠，因此當只有它自行挑選的連接埠無法綁定時，也會出現此訊息。這可能發生在 Windows 主機上，因為 Hyper-V 會保留涵蓋 Claude Code 挑選範圍的連接埠區段。

處理方式：

• 檢查是否有安全軟體或沙箱政策阻擋程序在 127.0.0.1 上監聽，並允許 Claude Code 綁定本機連接埠
• 然後再次啟動登入，例如在 /mcp 中選取該伺服器

/security-review 因缺少 origin/HEAD 而失敗

/security-review 會將您的分支與 origin/HEAD 比較差異來建立其審查脈絡，origin/HEAD 是記錄您 origin 遠端預設分支為何的本機 ref。當該 ref 不存在時，用來收集差異的 git 命令會失敗，審查在開始之前就會停止。

Error: Shell command failed for pattern "!`git diff --name-only origin/HEAD...`": [stderr]
fatal: ambiguous argument 'origin/HEAD...': unknown revision or path not in the working tree.
Use '--' to separate paths from revisions, like this:
'git <command> [<revision>...] -- [<file>...]'

訊息中引用的也可能是 git log 或其他 git diff。只有在遠端公告了預設分支，且您的 fetch refspec 涵蓋該分支時，Git 才會建立 origin/HEAD；對有提交的遠端執行完整的 git clone 就會如此。在下列設定中，該 ref 會缺失：

• 單一分支或 CI 檢出，其擷取的 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 的機器上使用 bash。請安裝 Git for Windows，或將 frontmatter 改為 shell: powershell。請參閱注入命令的執行方式

處理方式：

• 指定您遠端的預設分支來建立該 ref：git remote set-head origin <default-branch>。只要本機追蹤 ref 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> 新增一個，並在建立 ref 之前先擷取。如果遠端是空的，請先以 git push -u origin HEAD 推送您的分支，並在 set-head 命令中指定該分支；origin/HEAD 隨後會指向您剛推送的分支，因此在分支與其分歧之前，/security-review 看到的會是空的差異。

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

單純執行 claude 時，stdout 必須是終端機才能啟動互動式 UI。當 stdout 被重新導向，或主控台不是真正的終端機（例如 PowerShell ISE 和某些 IDE 輸出窗格）時，claude 會改以非互動方式執行。這與 claude -p 是相同的模式，而該模式需要提示詞，因此即使您沒有傳入該旗標，訊息也會提到 --print。在任何地方傳入 -p/--print 卻未提供提示詞，且 stdin 也沒有透過管線傳入任何內容，都會產生相同的錯誤。

Error: Input must be provided either through stdin or as a prompt argument when using --print

處理方式：

• 若要互動使用，請在真正的終端機中執行 claude：使用 Windows Terminal 或 PowerShell 主控台而非 ISE，並使用 IDE 的整合式終端機而非輸出窗格
• 若要單次使用，請傳入提示詞：claude -p "your question"，或以 echo "your question" | claude -p 透過管線傳入

輸入僅包含空白字元

在非互動模式中，Claude Code 會拒絕完全由空格、Tab 或換行組成的提示詞，而不會送出它，因為 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 個字元且沒有換行

您的程式向 claude -p --input-format stream-json 執行的 stdin 傳送了超過 268,435,456 個字元而沒有換行，因此 Claude Code 會將此錯誤印到 stderr 並以退出碼 1 結束，而不會緩衝更多輸入。訊息中將該上限表示為 256M。在 v2.1.257 之前，Claude Code 會無限制地緩衝這類輸入，使記憶體持續增長，直到程序當機或被終止。

Error: stream-json input carried over 256M characters with no newline. Each stream-json message must be a single newline-terminated JSON line: either the producer is not newline-terminating its messages, or one message exceeded this budget.

這麼長而沒有換行的輸入，通常表示產生者根本不是 stream-json 產生者，例如不小心透過管線傳入的二進位檔案或純文字日誌輸出。單一訊息超過上限也會無法通過相同的檢查。

處理方式：

• 檢查透過管線傳入 stdin 的內容。使用 --input-format stream-json 時，每則訊息都必須是一行以換行結尾的 JSON
• 若要改為傳送純文字，請移除 --input-format stream-json；claude -p 預設會從 stdin 讀取純文字提示詞

Unknown command

在互動式終端機工作階段中，您送出了一個不符合此工作階段中任何命令的 / 名稱，因此 Claude Code 會回報該名稱，而不會執行任何動作：

Unknown command: /hepl. Did you mean /help?

Claude Code 會建議選單在此工作階段中列出的最接近的命令名稱或別名。當沒有相近的名稱時，訊息會在名稱之後結束。原因通常是下列之一：

• 打字錯誤，例如將 /help 打成 /hepl。命令選單如何比對您輸入的內容說明了如何在送出前挑選相近的比對結果
• 命令存在，但因為未滿足某項需求（例如您的平台、方案或身分驗證方式）而在此工作階段中無法使用。/web-setup 與 /schedule 的疑難排解項目逐步說明了兩種常見情況。某些命令在您組織的政策停用它們時，會以自己的訊息回應，例如 Cloud sessions are disabled by your organization's policy
• 來自未在此工作階段中安裝或連線之外掛或 MCP 伺服器的命令

Claude Code 只在互動式終端機工作階段中以這種方式回應不相符的 / 名稱。在其他所有工作階段中，它會改將提示詞當成一般訊息送給 Claude，並附上命令未執行的說明，以及 Claude 在該工作階段中可執行的命令清單。這些工作階段包括：

• -p 執行
• Agent SDK 應用程式
• Desktop 應用程式的 Code 分頁
• VS Code 擴充功能的聊天面板
• 雲端工作階段與 routine

對於無法在上述工作階段之一中執行的內建命令，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 之前，訊息只會顯示原始的差異統計。

Diff is too large for ultrareview: 812 files, 96,410 lines changed (limits: 500 files, 8,000 lines). Largest files: package-lock.json (41,904 lines), dist/bundle.js (18,210 lines), src/generated/api.ts (9,876 lines). Pass a closer base branch (`/code-review ultra <branch>`) to narrow the scope, or split the change.

審查 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 物件格式），您會看到此拒絕訊息。

Could not find merge-base with main. Pass the base branch explicitly (e.g. `/code-review ultra develop`) or make sure you're in a git repo with a main branch.

第一句之後的提示取決於 Claude Code 觀察到的情況：

• 您沒有傳入基底分支：Claude Code 與儲存庫的預設分支比較，並建議您明確傳入基底分支，如上例所示
• 您傳入的基底分支原本就在您的複製中：提示為 Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)
• 您傳入的基底分支不在您的複製中：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 無法判斷您的複製是否為淺層複製時，則會改為建議 git fetch --unshallow origin。在 v2.1.221 之前，提示會對每個擷取的基底分支建議 git fetch --unshallow origin，而在完整的複製上，該命令會以 fatal: --unshallow on a complete repository does not make sense 失敗。

處理方式：

• 如果另一個分支才是您真正的基底，請明確傳入它：/code-review ultra <branch>
• 如果您的複製可能沒有完整的歷史記錄，請執行 git fetch --unshallow origin 並重新執行審查

您的檢出沒有任何分支

檢出可能有提交但沒有分支：如果您執行 git init，接著執行 git fetch <url> 與 git checkout FETCH_HEAD，就會得到一個沒有任何 ref 的分離 HEAD。Claude Code 會將您的儲存庫打包成 git bundle 以上傳進行 ultrareview，而它無法打包沒有分支或其他 ref 的儲存庫，因此 /code-review ultra 與 claude ultrareview 子命令會在雲端工作階段啟動前拒絕審查。

Your checkout has no branches (detached HEAD only), which cloud review can't bundle. Create one first — `git checkout -b <name>` — then rerun /code-review ultra.

在 v2.1.221 之前，Claude Code 會嘗試審查此檢出中每個受追蹤的檔案，而上傳會失敗。

處理方式：

• 以 git checkout -b <name> 在您目前的提交上建立分支，然後重新執行審查

沒有 GitHub 帳戶連接到您的 Claude 帳戶

您執行了 /code-review ultra <PR#> 或 claude ultrareview <PR#>，而在建立雲端工作階段之前，Claude Code 會詢問伺服器連接到您 Claude 帳戶的 GitHub 帳戶是否能存取該 PR 的儲存庫。由於沒有連接任何帳戶，或連接已過期，雲端複製將會失敗，因此 Claude Code 拒絕啟動。對於被拒絕的啟動，Claude Code 不會消耗免費執行次數，也不會計費用量點數。

Ultrareview clones <owner>/<repo> in the cloud with the GitHub account connected to your Claude account, and none is connected (or the connection expired). To fix: run /web-setup to reuse your GitHub CLI login, or connect an account at https://claude.ai/connect-github — then re-run /code-review ultra 1234 (allow a minute after connecting).

當您的工作階段中無法使用 /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 不會消耗免費執行次數，也不會計費用量點數。

Your connected GitHub account can't see <owner>/<repo> — usually the Claude GitHub app isn't installed on <owner> or wasn't granted this repo (web-connected accounts need it for private repos), or a different GitHub account is connected. To fix: run /web-setup to reuse your GitHub CLI login, or install the app at https://github.com/apps/claude/installations/new — then re-run /code-review ultra 1234.

當您的工作階段中無法使用 /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>)，並以預檢句子結尾：

Could not upload repo bundle (<error>). The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead

處理方式：

• 稍待片刻後重新執行命令。當 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 會改為拒絕上傳，且不會上傳任何內容：

Not uploading this working tree: core.ignoreCase (which decides whether .gitattributes patterns match file names regardless of letter case) is set in <file>, and the upload cannot follow that setting, so a file git would change before storing it (to encrypt it, for example) could be uploaded as it is on disk. Move the core.ignoreCase line into this repository’s .git/config or directly into your ~/.gitconfig, then retry.

訊息會指出該設定及其設定位置，並以適用於您所遇情況的修正方法作結。對於 core.attributesFile 與 attr.tree 也會出現相同的拒絕訊息，各自附有其修正方法。

訊息可能會指出一個由您的 git 設定透過 include 或 includeIf 指示詞引入的設定檔，即使該指示詞的條件不適用於此儲存庫。

處理方式：

• 套用訊息最後一句中的修正方法

GitHub 未連接到您的 Claude 帳戶

您從本機儲存庫啟動了雲端工作階段，例如使用 /autofix-pr。沒有 GitHub 帳戶連接到您的 Claude 帳戶，或連接已過期，因此 Claude Code 拒絕啟動：

GitHub isn't connected to your Claude account, so this repository can't be cloned in the cloud. Run /web-setup to connect with your GitHub CLI login, or connect on the web at https://claude.ai/connect-github

當您以 /schedule 建立 routine 時，相同的訊息會以指出該儲存庫的設定提醒形式出現；該提醒不會阻擋建立 routine。

處理方式：

• 執行 /web-setup 將您的 GitHub CLI 登入連接到您的 Claude 帳戶，或在 claude.ai/connect-github 連接帳戶。兩者的差異請參閱 GitHub 身分驗證選項。
• 連接後等待一分鐘再重新執行命令

在 v2.1.268 之前，Claude Code 會將此情況回報為 Claude GitHub App 檢查的暫時性失敗，並建議重試或安裝該應用程式；但兩者都無法連接 GitHub 帳戶。

需要單一登入授權

您執行了 /install-github-app，並選擇了一個其組織強制使用 SAML 單一登入的儲存庫。在設定之前，Claude Code 會以 GitHub CLI 檢查您對該儲存庫的存取權，而 GitHub 拒絕了該檢查，因為您的 gh token 尚未獲得該組織的授權。精靈會顯示警告以及授權步驟：

Single sign-on authorization needed
<owner>/<repo> belongs to an organization that enforces SAML single sign-on, and your GitHub CLI token isn't authorized for it yet.

處理方式：

• 執行 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 選擇器中所選工作階段的已儲存逐字稿，因此它會結束程序，而不是在部分載入的狀態下繼續。訊息中包含重試用的命令：

Failed to resume the conversation.
Run claude --resume <session-id> to retry, or claude to start a new session.

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 以啟動新的工作階段

No conversation found with the session ID

您將工作階段 ID 傳給了 claude --resume <session-id>，但沒有任何已儲存的逐字稿與之相符：

No conversation found with session ID: <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 建立的工作階段不會出現在選擇器中，因此請將 ID 與原始執行時印出的 session_id 再次核對

Windows reported an error (EBADF) when Claude Code read this session's transcript file

您在 Windows 上繼續了一個工作階段，其已儲存的逐字稿檔案正常開啟，但隨後讀取時因系統錯誤 EBADF 而失敗。系統錯誤並未說明讀取失敗的原因，因此此訊息會提示可能的原因及可嘗試的做法：

Windows reported an error (EBADF) when Claude Code read this session's transcript file, although the file had opened normally. This can happen when other software intercepts file reads — security, encryption or endpoint-management tools, for example. If it keeps happening for this conversation, try excluding the folder that holds Claude Code's session transcripts from such software (the .claude folder in your user profile, unless the app or CLAUDE_CONFIG_DIR points Claude Code elsewhere), or adding Claude Code to its allowed applications, then resume again.

此訊息會接在命令本身的失敗行之後，例如 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。

Cannot switch renderers in this session

切換渲染器時，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 找到的限制：

Cannot switch renderers in this session — it has restrictions a restart can't carry over (permission rules set for this session only). Nothing was changed. Running /tui fullscreen in a session started without them switches every later session too.

訊息括號中可能顯示的各項原因：

• 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 設定

Couldn't open Claude Desktop

您在工作階段中執行了 /desktop 或其別名 /app，或在 shell 中執行了 claude --desktop，而 Claude Code 用來開啟 Claude Desktop 的系統命令失敗了。執行 /desktop 後，工作階段會留在終端機中；claude --desktop 則會印出不含 Error: 前綴的訊息，並以狀態 1 結束。

括號中的文字指出失敗的命令，若該命令有產生結束狀態及錯誤輸出，也會附上其結束狀態與錯誤輸出的第一行。在 macOS 上，該命令為 open，如下例所示；在 Windows 上則為 rundll32：

Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and try again.

處理方式：

• 自行開啟 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 left your Zed keymap unchanged

您在 Zed 中執行了 /terminal-setup，而 Claude Code 無法完成對您 Zed keymap.json 的更新，因此保留了該檔案的原樣。

每則訊息都會指出您 keymap 的路徑，並在結尾附上需自行新增的快捷鍵區塊：

Couldn't update your Zed keymap, so it was left unchanged.
To add the binding yourself, add this block to the keymap array in <path to keymap.json>:
{ "context": "Terminal", "bindings": { "shift-enter": ["terminal::SendText", "\u001b\r"] } }

訊息的第一行指出原因：

• 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.：合併後的結果未能驗證為帶有該綁定的有效 keymap，因此 Claude Code 捨棄了結果而未寫入。帶有重複鍵的快捷鍵區塊可能會造成此情況

處理方式：

• 將訊息中的區塊複製到訊息所指路徑下 keymap.json 的頂層陣列中
• 對於 isn't a readable list of keybindings，請修正語法錯誤，或將檔案的頂層值改為陣列，然後再次執行 /terminal-setup

在 v2.1.247 之前，/terminal-setup 無法解析使用了 // 註解或尾隨逗號的 Zed keymap，並會將整個檔案替換為僅包含其自身的綁定，同時回報綁定已安裝。若要還原被早期版本替換的 keymap，請使用 Enter multiline prompts 中說明的 .bak 備份檔案。

Skill usage reports are not available on this connection

您透過 Remote Control，從手機或瀏覽器執行了 /skill-doctor。Claude Code 不會透過 Remote Control 傳送 skill 使用報告，而是改以此訊息回覆：

Skill usage reports are not available on this connection.

處理方式：

• 在執行該工作階段的機器上，於終端機中執行 /skill-doctor，或在該處執行 claude -p "/skill-doctor"

Custom output styles can't be selected over Remote Control

您透過 Remote Control 從行動應用程式或網頁執行了 /output-style，或該命令是透過轉送至工作階段的訊息傳入的。由於這類回合可能並非來自帳戶擁有者，Claude Code 在該回合中只會列出及選擇內建風格，並在命令列出風格或無法辨識您提供的名稱時，附加此通知。自訂風格名稱會得到與不存在的名稱相同的回覆：

Custom output styles can't be selected over Remote Control or from a relayed message. Select one in the session itself, or pick a built-in style here.

處理方式：

• 選擇一個內建風格，例如 /output-style concise
• 若要使用自訂風格，請在專案的 .claude/settings.local.json 中設定 outputStyle，或者若工作階段本身有終端機，請在該終端機執行 /output-style <style>

Output styles are saved to local settings which this session doesn't load

您在設定來源排除了 local 的工作階段中，嘗試使用 /output-style <style> 或 /config outputStyle=<style> 切換輸出風格。例如 settingSources 未包含 "local" 的 Agent SDK 工作階段，以及使用未包含 local 的 --setting-sources 值啟動的 CLI 工作階段。這兩個命令都會將風格儲存至 .claude/settings.local.json，而這類工作階段永遠不會讀回該檔案，因此 Claude Code 會拒絕執行，而不是寫入一個不會生效的設定：

Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load, so the style can't be changed here.

處理方式：

• 將 local 加入工作階段的設定來源，然後再次切換
• 在工作階段確實會載入的設定檔中設定 outputStyle 鍵，例如專案中的 .claude/settings.json 或 ~/.claude/settings.json。在 TypeScript SDK 中，請改為在內嵌的 settings 物件中設定 outputStyle；請參閱 Activate an output style

Plugin 錯誤

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

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

您執行了 claude plugin eval 或 claude plugin eval init，它在執行任何操作之前以退出代碼 1 和以下其中一則訊息結束：

`plugin eval` is currently in early access

`plugin eval` is currently unavailable

第一則訊息表示您的組建版本早於 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 之前，名稱只在新增 marketplace 時檢查，因此在其名稱變成保留名稱之前註冊的項目會繼續載入。

Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.

對於來源不是 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 將其視為另一種拼寫。保留的 marketplace 名稱 列出哪些拼寫算作保留名稱。Claude Code 在您新增 marketplace 時拒絕這樣的名稱：

Failed to add marketplace: "claude.code.plugins" is another spelling of "claude-code-plugins", a reserved marketplace name.

當 marketplace 已經以這樣的名稱註冊時，其項目停止載入，而 /plugin、claude plugin install 和 claude plugin update 警告：

known_marketplaces.json has an entry named "claude.code.plugins", another spelling of the reserved marketplace name "claude-code-plugins", so it is ignored. Remove it with: claude plugin marketplace remove claude.code.plugins

當名稱需要 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，訊息開頭為：

Claude Code refuses the marketplace name "anthropic-plugins-v2"

對於模仿名稱，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 名稱命名為原因。

該怎麼做：

• 執行 claude plugin marketplace remove <name>。這也會卸載從 marketplace 安裝的 plugin 並刪除其已儲存的資料
• 若要改為保留 marketplace，請等待其維護者重新命名它，然後執行 claude plugin marketplace update <name>
• 如果您發佈 marketplace，請在您的 marketplace.json 中重新命名它；使用者然後更新 marketplace 而不是移除它

Marketplace 已從不同的來源新增

您透過 /plugin install <plugin> --marketplace <source> 確認新增 marketplace，而 Claude Code 從該來源擷取的目錄將自己命名為與您已從不同來源新增的 marketplace 相同的名稱。Claude Code 保留現有的 marketplace 而不是替換它，plugin 不會被安裝。

Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.

該怎麼做：

• 如果您已新增的 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 報告：

Hook from plugin formatter@acme-tools references ${user_config.*} in a shell-form command. The substituted value would be re-parsed by the shell. Use exec form instead — {"command": "<executable>", "args": ["${user_config.KEY}", ...]} — or read $CLAUDE_PLUGIN_OPTION_<KEY> from the hook's environment. Command: ./scripts/notify.sh ${user_config.webhook_url}

Monitor 報告：

Monitor "deploy-status" from plugin deploy-tools references ${user_config.*} in its command. The substituted value would be passed to a shell. Monitor commands cannot safely reference ${user_config.*}; have the monitor script read the value from a config file or prompt instead.

MCP headersHelper 報告：

headersHelper for MCP server 'internal-api' references ${user_config.*}. The substituted value would be passed to a shell; read the value inside the helper script instead (e.g. from an env var set in the server's "env" block).

該怎麼做：

• 對於 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 archive integrity check failed for https://artifacts.example.com/claude-plugins/my-plugin.zip: expected sha256 6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1, got ac52220c0914ef8ca6a602e4a7362f88d30fb021110f72a6d15b68c3fe7df2b7. The archive was not installed. Verify the sha256 in the marketplace entry, or that the URL serves the intended file.

該怎麼做：

• 如果您發佈 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）命名了宣告路徑的欄位。

commands path escapes plugin directory: ./../shared.md

在 claude plugin 命令輸出中，相同的錯誤讀作 Path escapes plugin directory: ./../shared.md (commands)。

Claude Code 拒絕指向 plugin 外部的路徑（如 ../shared-utils）和導致 plugin 外部的符號連結，以及 marketplace 符號連結規則 不允許的符號連結。對於符號連結，訊息也會說明路徑解析的位置：

commands path escapes plugin directory: ./commands/deploy.md — it resolves to /home/user/shared/deploy.md, outside the plugin directory

在 macOS 和 Linux 上，Claude Code 也拒絕包含反斜線的元件路徑，即使路徑保持在 plugin 內。使用 Windows 風格分隔符的元件路徑的 plugin 在 Windows 上載入並在其他平台上觸發此拒絕：

commands path escapes plugin directory: ./commands\deploy.md — its path contains a backslash, which is not resolved reliably on this platform

在 v2.1.251 之前，Claude Code 載入在 marketplace 項目中宣告的 commands 路徑，即使它指向 plugin 目錄外。Claude Code 已經拒絕在 plugin.json 中宣告的路徑和 marketplace 項目中的其他元件路徑。

在 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 下方，並命名路徑和作業系統傳回的程式碼：

skills path could not be checked: /home/user/my-plugin/skills (ELOOP)

在 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 報告拒絕如下：

Cannot install my-plugin@my-marketplace: its marketplace entry path does not stay inside the marketplace directory (an absolute, climbing, network-shaped, backslash-containing or link-traversing entry, an entry of a fetched marketplace that resolves or opens outside its tree — or a relative entry in a url-catalog marketplace, which has no local directory)

當已安裝的 plugin 的項目失敗相同的檢查時，claude plugin list 將 plugin 顯示為 failed to load，並顯示：

Plugin source path refused: ./my-plugin does not stay inside its marketplace directory. Check that the marketplace entry has a plain relative path.

該怎麼做：

• 如果您維護 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，但其內容與登錄架構不符。

遺失的檔案不是失敗：Claude Code 將其視為沒有 marketplace 的登錄。

使用空檔案時，claude plugin install 報告：

✘ Failed to install plugin "my-plugin": Failed to load marketplace configuration: JSON Parse error: Unexpected EOF

在 v2.1.246 之前，claude plugin install 沒有報告此失敗。

該怎麼做：

• 開啟 ~/.claude/plugins/known_marketplaces.json 並修復 JSON，或修復訊息命名為與登錄架構不符的項目
• 如果您無法修復它，刪除檔案或用 {} 替換其內容，然後使用 claude plugin marketplace add <source> 重新新增每個 marketplace。Claude Code 在您下次在已信任的資料夾中啟動它時，重新註冊您的使用者或受管設定在 extraKnownMarketplaces 中宣告的 marketplace。

Plugin 是您的組織所需的

您執行了 claude plugin disable，或使用 /plugin 已安裝 標籤，以關閉您的組織標記為必需的 從 claude.ai 同步的 plugin：

Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it.

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 保持安裝，它儲存的任何內容都不會被刪除。

✘ Failed to uninstall plugin "formatter": "formatter" was not uninstalled: it is still switched on in /home/user/project/.claude/settings.local.json, although the settings change reported no error. It is still installed. Take it out of "enabledPlugins" in that file yourself, then uninstall it again.

訊息的中間部分命名了檔案和原因：

• 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 會自行修正大多數工具錯誤。當某個錯誤需要您進行變更時，該錯誤的 處理方式 清單會說明需要變更的內容。

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 會在沒有工具的情況下啟動，並可能傳回空白或令人困惑的結果。

Agent 'code-reviewer' would be spawned with zero tools — refusing. Its tools list resolved to nothing: unrecognized [Grpe]. Fix the agent's tools frontmatter or pass a different subagent_type.

處理方式：

• 對照 subagent 可用的工具，修正錯誤中列出的每個項目
• 移除工作階段中不存在之工具的項目，例如來自未連線伺服器的 MCP 工具
• 對於 背景 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 拒絕規則會封鎖編輯。

File is covered by a Read deny rule in your permission settings and cannot be edited.

當 Claude Code 拒絕 Write 工具時，訊息的結尾會改為 and cannot be written。

處理方式：

• 如果 Claude 應該能夠變更該檔案，請在 /permissions 或 設定 中移除或縮小該 Read 拒絕規則
• 如果該檔案必須保持不變，請保留該規則，並為相同路徑新增 Edit 拒絕規則，以同時封鎖 NotebookEdit 工具

Path cannot contain null bytes

檔案工具呼叫的路徑或模式引數包含 null 位元組，而檔案系統和搜尋工具無法接受這種字元。Read、Write、Edit、NotebookEdit、Glob 和 Grep 會檢查這一點，訊息會指出工具和引數：

Read file_path cannot contain null bytes (\0). Remove the null byte and try again.

該工具呼叫會失敗，Claude 會看到錯誤，回合則會繼續進行。

處理方式：

• 您無需採取任何動作：錯誤會作為工具的結果傳回給 Claude，而訊息本身會告知 Claude 移除 null 位元組並重試

在 v2.1.281 之前，Read、Write、Edit 或 NotebookEdit 路徑中的 null 位元組會以指出 Path contains null bytes 的錯誤結束整個回合，且工具從未執行。

subagent\_type is required

subagent_type is required: the general-purpose agent is not available in this session. Available agents: ...

Claude 在未指定 subagent_type 的情況下呼叫了 Agent 工具，而此工作階段沒有可供後備使用的 general-purpose subagent。這會發生在兩種設定中：

• 在非互動模式中設定了 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1，這會移除所有內建 subagent
• 工作階段的主執行緒 agent 具有排除了 general-purpose 的 tools: Agent(...) 允許清單

處理方式：

• 通常無需任何動作：訊息會列出工作階段中確實存在的 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 之前，超過上限的索引會在下次載入時被無聲截斷，且在寫入時不會有任何提示。

Error: this write left the memory index at MEMORY.md at 214 lines, over its 200-line read limit. The write succeeded, but everything past the limit is silently dropped each time the index is loaded — entries at the end are already invisible to readers. Rewrite it to under 140 lines now: keep one line per entry, move detail into topic files, and merge or drop stale entries.

只有會被載入的內容才會計入上限。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 工作階段。

pkill: refusing to run — this pattern matches the Claude CLI process (PID 12345). Narrow the pattern, or target your own children with `pkill -P $$ ...`.

拒絕訊息會出現在 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 重試：

Failed to write to researcher's inbox — nothing was sent. Try again, or message the lead.

結構化的 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 工具結果中的恢復報告之後：

Its agent definition was not restored: the folder its definition file came from is not trusted (source: projectSettings), so the teammate is running with the team-essential tools and no custom instructions. To restore it, the user needs to run Claude Code in that folder once and accept the trust dialog (the --debug log names the folder); do not change trust settings on the user's behalf.

此檢查適用於專案或 --add-dir 目錄之 .claude/agents/ 目錄中的定義，而接受上層資料夾的信任對話框並不能滿足此檢查。

處理方式：

• 在 除錯日誌 指出的資料夾中執行 claude，並接受信任對話框。下次 Claude Code 恢復該隊員時，便會重新套用定義；您不需要重新啟動組長工作階段
• 或者，在 ~/.claude.json 中將 hasTrustDialogAccepted 項目設為 true，並使用除錯日誌印出的確切 projects["<path>"] 鍵

Message too large for cross-session delivery

Claude 傳送給您在此機器上另一個工作階段的 跨工作階段訊息 過長，無法傳送。Claude Code 拒絕了它，接收端工作階段沒有收到任何內容。拒絕訊息會出現在傳送端工作階段的工具結果中，而不是以橫幅形式出現在您的終端機中。它會指出兩個大小以及如何讓訊息符合限制：

Failed to send to api-worker: Message too large for cross-session delivery: the serialized message is 1,203,844 characters and the limit is 1,048,576. Shorten the message text — put bulk content in a file the recipient can read rather than in the message — or split it into smaller messages.

重新傳送相同的文字也會以相同方式失敗。

處理方式：

• 要求 Claude 摘要該訊息，或將大量內容放入檔案並傳送該檔案的路徑
• 要求 Claude 將內容拆分成數則較短的訊息

在 v2.1.235 之前，Claude Code 會將過大的訊息回報為已傳送。接收端工作階段會在未讀取的情況下將其捨棄。

Too many messages to this session just now

Claude 向您在此機器上的某個工作階段快速連續傳送了大量 跨工作階段訊息，而這一連串訊息已達該工作階段收件匣所能接受的量。Claude Code 拒絕了下一次傳送，接收端工作階段沒有從中收到任何內容。拒絕訊息會出現在傳送端工作階段的工具結果中，而不是以橫幅形式出現在您的終端機中：

Failed to send to api-worker: Too many messages to this session just now: 30 were sent recently and more would be dropped by its rate limit, so this one was not sent. Batch what remains into one message, or wait a little before sending more.

處理方式：

• 通常無需任何動作：Claude 會將剩餘內容合併成一則訊息，或在傳送更多訊息前稍候
• 如果是您自己促成了這一連串訊息，請要求 Claude 將剩餘內容合併成單一訊息

在 v2.1.236 之前，Claude Code 會將這些傳送回報為已傳送。接收端工作階段會在未讀取的情況下將其捨棄。

Cross-session message was dropped at the recipient session's inbox

Claude 傳送了一則 跨工作階段訊息 給您在此機器上的另一個工作階段，而該工作階段的收件匣在該工作階段中的 Claude 讀取之前就將其捨棄。這一行會指出收件者的位址，若收件者提供了原因，則會在破折號後附上原因：

Cross-session message was dropped at the recipient session's inbox (recipient: uds:/tmp/cc-socks/13605.sock) and not delivered — its queue of undelivered peer messages was full. Claude was told not to resend right away.

一行可以涵蓋數則被捨棄的訊息，此時開頭會使用複數形式，例如 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 傳送的訊息，拒絕訊息會出現在傳送端工作階段的工具結果中：

Failed to send to api-worker: Refusing to send: reply target is a symlink

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 下

Refusing to read, write, or search a path

Claude Code 會檢查檔案路徑的 權限規則，然後在工具開啟檔案或開始搜尋時再次確認該解析結果。當它無法確認該路徑仍通往檢查所核准的位置時，Claude Code 會拒絕該操作，而不是跟隨它。拒絕訊息會出現在工具結果中：

Refusing to read /path/to/file: its symlink resolution changed after permission was checked (a link on the way now leads somewhere the check did not see). If a link in the working directory is being rewritten concurrently, stop that and retry.

每個拒絕都會指出其原因：

• 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 工具結果中：

task output swap refused (tasks dir moved or linked): /private/tmp/claude-501/-Users-you-my-project/1f0e62dc-4b0a-4f5e-9c2d-8a7b6c5d4e3f/tasks/b7k2f9m3q.output. To recover: restart Claude Code with CLAUDE_CODE_TMPDIR set to a fresh directory; or, if /private/tmp/claude-501/-Users-you-my-project is a stray directory or a symbolic link that should not be there, remove that entry itself (not what it points to) and restart.

括號內的文字會指出失敗的檢查。output symlink was re-pointed、output file identity changed 和 not a regular file 等原因都回報相同的情況：輸出路徑上或沿途的某個東西已不再是 Claude Code 所建立的檔案。只有部分原因會附帶 To recover: 句子。

如果檢查在命令仍在執行時失敗，Claude Code 會停止該命令，其結果會回報：

Command killed: its output file was replaced or could no longer be verified

處理方式：

• 升級至 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 on the filesystem with Claude Code's temp directory /private/tmp/claude-501/-Users-you-my-project/1f0e62dc-4b0a-4f5e-9c2d-8a7b6c5d4e3f/tasks (EDQUOT), so any output this command printed was lost, and it may have failed because it could not write. Delete files you no longer need there, or restart Claude Code with CLAUDE_CODE_TMPDIR set to a directory on another filesystem.

訊息會指出用盡的資源：

• 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 再次執行該命令。它先前印出的輸出已遺失，而不是被截斷

The source file is not valid UTF-8 text

Claude 嘗試從一個位元組無法解碼為文字、或其文字已包含替代字元 U+FFFD 的檔案發佈 artifact，因此 Claude Code 在上傳任何內容之前就拒絕了發佈。訊息會出現在 Artifact 工具結果中，並指出第一個需要修正的位置：

file_path: the source file is not valid UTF-8 text (first invalid byte at line 12, column 40). It may be saved in another encoding or contain binary data. Rewrite it as UTF-8, then publish again. Nothing was published.

file_path: the source file has the replacement character U+FFFD at line 12, column 40, usually left where an earlier edit or paste lost a character. Replace it with the intended text (in HTML, write an intended U+FFFD as �), then publish again. Nothing was published.

Claude Code 會將檔案解碼為 UTF-8，若檔案以小端序 UTF-16 位元組順序標記開頭，則解碼為 UTF-16。當這類 UTF-16 檔案無法解碼時，第一則訊息會指出 UTF-16，但仍會告知您將檔案重寫為 UTF-8。當指出的位置之後還有更多位置時，訊息會在位置後加上計數，例如 (+2 more)。

處理方式：

• 通常無需任何動作：Claude 會重寫檔案並再次發佈
• 如果該檔案是您撰寫或匯出的，請將其重新儲存為 UTF-8，並將每個 U+FFFD 替換為先前的編輯、貼上或轉換所遺失的字元
• 若要在頁面上顯示刻意使用的 U+FFFD，請在 HTML 中將其寫成 �，而不是使用該字元本身

在 v2.1.267 之前，Claude Code 會在未檢查的情況下上傳這類檔案，改由伺服器拒絕發佈。

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

在 Claude Desktop 應用程式中於您的機器上執行的 Cowork 工作階段裡，Claude 為 artifact 指定了一個本機檔案。Claude Code 無法確認該檔案是位於工作階段已連接資料夾內的一般檔案：該路徑位於這些資料夾之外、經過符號連結，或其寫法可能指向與表面上不同的檔案。讀取這類檔案需要您的核准，而在無法向您顯示核准卡片的工作階段中（例如設定為略過所有核准的工作階段），Claude Code 會拒絕該讀取。

拒絕訊息會出現在 Artifact 工具結果中；當檔案完全無法被檢查時，則會改為指出該失敗：

Reading a local file from outside this session's connected folders, or through a link, needs the approval card, and no one can answer it in this Cowork session. Use a plain file inside the connected folders; do not retry this file in this session.

cannot read file_path (ENOENT) — the file could not be examined, and no one can answer the approval card in this Cowork session. Check that the file exists as a plain file inside the connected folders, then retry with that path.

處理方式：

• 通常無需任何動作：訊息會告知 Claude 改用已連接資料夾內的一般檔案
• 若要將該檔案原樣放入 artifact，請將其以一般檔案（而非符號連結）的形式複製到工作階段的其中一個已連接資料夾中，然後再次提出要求

WebFetch cannot fetch localhost

Claude 使用主機名稱不含點的 URL 呼叫了 WebFetch，例如 http://localhost:3000 或像 http://wiki/ 這樣的純內部網路名稱。WebFetch 會在發出任何請求之前拒絕這些 URL：

WebFetch cannot fetch localhost or other hostnames without a dot. To reach a local server, use Bash with curl instead.

處理方式：

• 通常無需任何動作：訊息會引導 Claude 透過 Bash 工具使用 curl，它可以連線至本機與內部網路伺服器

在 v2.1.268 之前，WebFetch 會以通用的 Invalid URL 錯誤回報這些 URL。

WebFetch domain safety check failed

在擷取 URL 之前，WebFetch 會將 URL 的主機名稱傳送至 api.anthropic.com，以對照 Anthropic 的 網域安全封鎖清單 進行檢查。如果檢查無法完成，WebFetch 就無法確認該網域是安全的，因此不會擷取該頁面，工具結果會改為包含下列其中一則訊息：

The safety check for domain example.com is rate-limited (too many domain checks from this network; the limit is shared and can stay exhausted for minutes). Do not retry WebFetch in a loop or sleep to wait it out; continue without this page and report that its safety check was rate-limited. A single later attempt is fine; if that is rate-limited too, stop.

Unable to verify if domain example.com is safe to fetch. This may be due to network restrictions or enterprise security policies blocking claude.ai.

• 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 設定清單報告：

Can't open MCP settings while no terminal is attached to this background session. This session now shows "needs input" in agent view — open it and run /mcp to manage servers, or use `/mcp enable|disable|reconnect <server>` to steer without the panel.

該怎麼做：

• 從 agent 檢視附加到工作階段並再次執行命令
• 或使用訊息命名的形式，例如 /mcp reconnect <server>、/mcp enable 或 /mcp disable，這些在不附加的情況下有效

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

Claude 透過 worktree 隔離防護無法解析為一個可驗證位置的拼寫來定址檔案或工作目錄。防護會檢查任何在 worktree 中隔離的工作階段（無論互動式或背景）以及 worktree 隔離 subagent 中的寫入和命令工作目錄。它在檢查操作不會到達共享簽出之前解析符號連結，當解析失敗時，它會阻止操作而不是讓它落在那裡。訊息命名它拒絕的路徑形式以及如何重試：

This write was blocked because the path is spelled in a form that cannot be safely resolved (for example through a symlink storing a raw dot segment, a network-share or device-namespace shape, or an unreadable ancestor directory). If the file is inside the worktree /path/to/worktree, address it by its direct symlink-free path instead.

被阻止的命令報告其工作目錄的相同原因，並以 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 中隔離工作階段不會解除阻止。訊息命名要改用的路徑形式：

This write was blocked because the path is network-shaped (a UNC share or /net automount spelling) while this session's checkout is local. Isolating cannot unblock it. If the file is genuinely inside the worktree /path/to/worktree, address it by its local, plainly-spelled path instead.

被阻止的命令報告其工作目錄的相同原因，並以 re-run the command from its local, plainly-spelled path 結尾。在 v2.1.217 之前，防護只比較路徑文字，因此透過 UNC 或 /net 路徑定址簽出內的檔案未被阻止。

該怎麼做：

• 通常什麼都不做：Claude 使用訊息要求的本機拼寫重試

命令被 worktree 隔離檢查阻止

Claude 在在 worktree 中隔離的工作階段中執行了 Bash 或 Monitor 命令，Claude Code 因以下兩個原因之一拒絕了它：

• 命令將 git 指向主簽出。
• Claude Code 無法從命令文字驗證命令執行的任何 git 保持在 worktree 內。從未提及 git 的命令仍然可能因此原因被拒絕，因為展開變數間接參照（例如 ${!name}）或執行 Bash 函數替換（例如 ${ command; }）會產生在執行時本身可能是命令的值。

訊息的中間命名無法驗證的內容：

This session is isolated in the worktree /path/to/worktree, but this command evaluates ${!x@P} arithmetically inside a construct too complex to verify, which can run a command hidden in a variable's value. Refusing to run it — a worktree-isolated session's git operations must target its own worktree. Split it into plain, separate commands and run them from /path/to/worktree.

該怎麼做：

• 通常什麼都不做：Claude 讀取訊息並按其最後一句要求的方式重寫命令
• 如果您要求的命令持續被拒絕，按字面拼寫標記的值：用其值替換間接參照或替換，並從 worktree 內將 git 作為獨立的純命令執行
• 要刻意作用於主簽出，請在工作階段外的終端機中自己執行命令

此工作階段沒有已儲存的逐字稿

您附加到已停止的背景工作階段，該工作階段使用 ← 或 /background 從另一個對話背景化，並在其第一個回應完成之前停止。在該第一個回應完成之前，對話仍然只存在於背景化它的工作階段中，因此 claude attach 拒絕啟動已停止的工作階段，而不是在相同工作階段 ID 下開始空白對話。訊息以此工作階段的 claude respawn 命令結尾：

This session has no saved transcript — it was stopped before its first response finished. If it was backgrounded from another conversation, that one is still intact; `claude respawn <id>` starts this one fresh.

在 agent 檢視中開啟相同工作階段的列，會改為在清單下方顯示 Press enter again to restart this session fresh，在該列上第二次按 Enter 會使用空白對話重新啟動工作階段。在 v2.1.212 之前，開啟列會顯示拒絕訊息，無法從 agent 檢視重新啟動。在 v2.1.211 之前，開啟已停止的工作階段會無聲地啟動該空白對話，並可能重新執行工作階段的原始提示詞。

該怎麼做：

• 您背景化的對話完整無缺：使用 claude --resume 繼續它或繼續在其中工作
• 若仍要重新啟動已停止的工作階段，請使用訊息中的 ID 執行 claude respawn <id>，或在 agent 檢視中的其列上按 Enter 兩次
• 如果工作階段確實完成了回應，而您在 v2.1.214 之前的版本上仍看到此拒絕，~/.claude/projects 中的不可讀資料夾可能會使逐字稿掃描遺漏已儲存的對話；請更新到 v2.1.214 或更新版本，其在掃描期間容許不可讀資料夾

此工作階段在另一個終端機中執行

您在 agent 檢視中開啟了已停止工作階段的列，而其已儲存的對話已在此機器上的另一個執行中 Claude Code 程序中開啟，因此 Claude Code 拒絕啟動將寫入相同逐字稿的第二個程序。您看到的訊息取決於持有該對話的是什麼：

Can't open — this session is running in another terminal
This conversation is already open in another running Claude session — use that one, or close it and try again

• running in another terminal：終端機持有該對話，例如您使用 claude --resume 或 /resume 繼續它的終端機。列也會顯示 Open in a terminal。
• already open in another running Claude session：另一個非互動式 Claude Code 程序持有它，例如相同對話中尚未退出的背景工作階段程序。

Claude Code 會儲存您在開啟列時輸入的回覆，並在工作階段下次啟動時將其作為工作階段的下一個提示詞傳送。

該怎麼做：

• 在開啟該對話的程序中繼續對話，或退出該程序並再次開啟列

在 v2.1.248 之前，只有 already open in another running Claude session 拒絕存在：在終端機中繼續的對話不計為開啟，開啟列會啟動寫入相同對話的第二個 Claude Code 程序。

此工作階段的已儲存對話不再在磁碟上

您開啟了在背景服務關閉時結束的背景工作階段，而逐字稿清理已移除其已儲存的對話，例如在機器關閉數週後。通常開啟這樣的列會繼續其已儲存的對話。由於沒有可繼續的內容，Claude Code 會拒絕，而不是在不詢問的情況下重新執行工作階段的原始提示詞：

This session's saved conversation is no longer on disk (it ended while the background service was off, and old transcripts are cleaned up), so there is nothing to resume. `claude rm 7c5dcf5d` deletes the row; `claude respawn 7c5dcf5d` runs its original prompt again instead.

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 命名分支和未推送的提交，並說明如何進行：

kept 7c5dcf5d — its worktree is still at “/home/you/project/.claude/worktrees/fix-login”
  2 unpushed commits on “claude/fix-login”: a1b2c3d “Fix login flow” and 1 more. They exist on no remote, so deleting the worktree would lose them.
  push them and run 'claude rm 7c5dcf5d' again, or discard the worktree and its commits: claude rm 7c5dcf5d --discard-unpushed a1b2c3d000000000000000000000000000000000@0123456789abcdef0123456789abcdef

當 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 之前，在主簽出中簽出的預設分支不計算在內：您已經合併到那裡的分支仍然會觸發此拒絕，直到其提交到達遠端。

終端機主機程序已死亡

每個背景工作階段的終端機在背景服務下的主機程序中執行，該程序在服務仍保持其連線時死亡，因此無法連線到工作階段。

在 Linux 和 WSL 上，背景服務每隔幾秒檢查每個主機程序，當程序已退出但其與服務的連線從未關閉時，將工作階段標記為失敗，並在 agent 檢視中的其列上顯示原因：

terminal host process died — press Enter to restart

從 shell，claude attach <id> 會重新啟動已因主機死亡而標記為失敗的工作階段，否則列印原因並退出：

Couldn't attach to <id> — This session's terminal host process died (the conversation is saved) — run `claude attach <id>` again to restart it on a fresh host.

無論哪種情況，對話都會儲存。

執行 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> 會等待而不報告錯誤。

工作階段沒有回應

您開啟了背景工作階段，背景服務接受了開啟，但約十秒內沒有輸出到達，因此 Claude Code 判定中繼工作階段終端機的程序無法傳遞輸出，並結束嘗試而不是繼續等待。

在 agent 檢視中，Claude Code 在頁腳中提供重新啟動：

Press enter again to restart this session — it isn't responding (its conversation is saved and resumes).

從 shell，claude attach <id> 列印原因並退出：

Couldn't attach to <id> — Session isn't responding — `claude stop <id>`, then `claude attach <id>` restarts it (the conversation is saved).

Claude Code 永遠不會為您重新啟動執行 shell 命令的列，因為重新啟動會再次執行命令。

該怎麼做：

• 在 agent 檢視中，在相同列上再次按 Enter。Claude Code 停止無回應的程序並重新啟動工作階段，對話繼續。沒有第二次按下，什麼都不會停止
• 從 shell，執行 claude stop <id>，然後 claude attach <id>
• 對於 shell 命令列，在 agent 檢視中按 Ctrl+X 或執行 claude stop <id> 停止它；再次分派命令以重新執行它

工作階段在重新生成進行中時被停止

您開啟了背景工作階段，其程序未執行，而當 Claude Code 重新啟動它時，另一個 Claude Code 程序停止了它，例如在另一個終端機中的 claude stop。Claude Code 保持工作階段停止：

Session <id> was stopped while the respawn was in flight

開啟您剛分派、其程序仍在啟動中的工作階段時，會改為等待該程序。在 v2.1.246 之前，在那一刻開啟它可能會停止它並顯示此訊息。

該怎麼做：

• 如果您沒有停止工作階段，在 agent 檢視中再次開啟其列或執行 claude respawn <id> 重新啟動它
• 如果您自己停止了它，就不需要再做任何事：工作階段保持停止

工作階段 agent 不再可用

您繼續了一個執行自訂 agent 的工作階段（使用 --agent 或 agent 設定啟動），而 Claude Code 未找到該名稱的 agent。當您已信任該工作區時，它會先搜尋工作階段的原始目錄，然後搜尋您繼續時所在的目錄。工作階段仍然會繼續，但使用預設工具，因此 agent 的工具限制不再適用：

This session was running agent 'code-reviewer', which is no longer available (no agent by that name in /home/you/project). Continuing with the default tools and system prompt — the agent's tool restrictions no longer apply. To restore it, re-create the agent, or resume with an explicit --agent <name>.

警告只列出 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 一次，接受信任對話框，然後再次繼續

CLAUDE\_CODE\_PROCESS\_WRAPPER 啟動器錯誤

CLAUDE_CODE_PROCESS_WRAPPER 已設定，但其值無法使用，因此 Claude Code 拒絕啟動受影響的程序，而不是在沒有啟動器的情況下執行它。設定問題會以變數名稱開頭並說明原因的訊息報告，例如：

CLAUDE_CODE_PROCESS_WRAPPER: launcher `/opt/corp/launcher` is not an executable regular file

啟動後未以 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 啟動背景工作階段時，會出現此錯誤：

Couldn't reach the background service (spawn background service: EUNKNOWN: unknown error, uv_spawn) — run 'claude daemon status'

在某些帳戶上，訊息會以 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 檢視開啟工作階段時，會出現此錯誤：

Couldn't start the background service — spawn background service: EACCES: permission denied, posix_spawn '/usr/local/lib/node_modules/@anthropic-ai/claude-code/bin/claude'

當您使用 /background 或 claude --bg 啟動工作階段時，相同的原因出現在 Couldn't reach the background service (...) 內。在相同的重新安裝期間，錯誤可能改為顯示另一個代碼，例如 ENOENT 或 ENOEXEC，或 Windows 上的 EUNKNOWN 或 EPERM；在多次重試後仍持續的 EUNKNOWN 有不同的原因。

在 npm 安裝上，Claude Code 會等待重新安裝完成並自動重試：最多十秒，而當機器上明顯仍有 Claude Code 的 npm 安裝在執行時最多兩分鐘，這涵蓋了另一個 Claude Code 程序正在下載更新的情況。當安裝超過該等待時間時，失敗訊息會提及更新，而不是單純的錯誤代碼：

Claude Code is being updated by npm on this machine (still not runnable after 2 min, EACCES) — try again when the update finishes

在 v2.1.257 之前，等待在所有情況下都在十秒停止，因此此錯誤會在另一個 Claude Code 程序仍在下載更新時出現。在 v2.1.246 之前，Claude Code 會立即失敗，不會等待。

該怎麼做：

• 等待幾秒，然後開啟工作階段或再次分派。當訊息說 Claude Code 正在更新時，請在更新完成後重試。
• 如果錯誤在沒有 npm 安裝執行時持續，表示您的使用者無法執行已安裝的二進位檔案。請檢查其權限及其目錄的權限，或重新安裝 Claude Code。

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

Claude Code 作為背景服務啟動的程序在接受連線之前就退出了，因此 Claude Code 無法開啟您的工作階段。當服務在退出前列印了錯誤時，括號中的原因會提供退出碼或訊號以及服務列印的第一行，該行指出使其停止的原因：

Couldn't reach the background service (background service exited before it became reachable (exit code N): <the service's first error line>) — run 'claude daemon status'

當您從 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 不會啟動工作階段，訊息會指出遺失的目錄：

Couldn't start a background session (working directory no longer exists or is not accessible: /tmp/demo)

在 v2.1.257 之前，工作階段看似已啟動，然後在 agent 檢視中顯示為失敗列，原因相同。

在 v2.1.281 之前，當目錄在您啟動工作階段之前就已消失時，也會出現此訊息。該情況會報告 could not be resolved on disk。

該怎麼做：

• 重新建立訊息指出的目錄，或從存在的目錄分派，然後再試一次

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

您在尚未信任的目錄中啟動或重新啟動背景工作階段，而工作區信任對話框無法出現來詢問您。Claude Code 不會啟動工作階段：

Workspace not trusted. Run `claude` in /path/to/project once and accept the trust prompt, then retry.

若從工作階段自己目錄中的終端機執行，相同的命令會改為顯示信任對話框，並在您接受後啟動工作階段。此訊息出現在無法顯示對話框的地方，例如在指令碼中，或當您從非其自身的目錄重新啟動工作階段時。

兩種變體指出不同的原因：

• 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 程序以非零代碼結束。結束代碼本身不會說明失敗的原因：真正的錯誤在於程序自己的輸出，包裝程式會在捕獲時附加該輸出，否則將其保留在日誌中。

Error: Claude Code process exited with code 1

在 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。

Failed to run Claude Code: Error: Could not locate the Claude CLI on PATH. Launching by name in a PowerShell terminal would run a 'claude' from the open folder instead of the installed CLI, so the launch was blocked. Make sure the Claude CLI's install directory is on your system PATH (not only your PowerShell profile), then restart VS Code and try again. VS Code reads PATH when it starts, so PATH changes take effect only after a restart.

該怎麼做：

• 在 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 程序，連線在程序確認或完成訊息之前結束，且沒有錯誤。擴充功能無法判斷訊息是否已被處理，因此它要求您再次傳送訊息：

The connection to Claude Code ended before this message completed — it may not have been processed, so please send it again.

該怎麼做：

• 再次傳送訊息。下一條訊息會啟動一個新的 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 會透過追蹤路徑上的連結進行寫入和刪除，並且不會報告部分還原。

Restored the code, but skipped 2 files: the tracked path is (or became) a link or other non-regular file, its directory changed since the checkpoint, or its backup could not be safely read. Skipped files were left untouched — run with --debug for the paths.

該怎麼做：

• 識別哪些檔案被跳過，以便您可以使用下面的步驟處理每個檔案。訊息只提供計數；位於 ~/.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 無法寫入或刪除該檔案。

Failed to restore the code:
No files were restored: 1 file failed (backup missing, or the file could not be updated)

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 在您工作時將文字記錄儲存到磁碟，其對文字記錄檔案的寫入失敗。該訊息以基礎錯誤代碼命名原因，例如磁碟已滿：

Transcript writes are failing (disk full — ENOSPC) · recent messages may not be saved for resume

警告根據錯誤在不同時間點出現：

• 在不會自行清除的條件首次失敗時：磁碟已滿、超過磁碟配額、檔案系統唯讀、路徑超過檔案系統長度限制，或在 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 不會為其寫入文字記錄或提示歷史記錄：

Transcript saving is off — CLAUDE_CODE_SKIP_PROMPT_HISTORY is set · --resume will not find this session; if unintended, unset it and restart

該變數是針對暫時性指令碼工作階段的有意選擇退出，但它也可以透過殼層設定檔、包裝指令碼或匯出它的父程序到達工作階段。

該怎麼做：

• 如果您有意設定該變數，不需要採取任何行動；該通知確認工作階段不會出現在 --resume、--continue 或向上箭頭歷史記錄中
• 如果您沒有，請從啟動 claude 的殼層或指令碼中移除該變數，然後啟動新工作階段。目前工作階段的訊息不會被追溯儲存。

因為繼承了 CLAUDE\_CODE\_CHILD\_SESSION 標記所以文字記錄儲存已關閉

Claude Code 在它產生的子程序中設定 CLAUDE_CODE_CHILD_SESSION，並將繼承它的互動式工作階段視為巢狀：Claude Code 不會為其儲存文字記錄，因此 Claude 本身啟動的工作階段不會填滿您的 --resume 清單。此通知表示您目前的工作階段繼承了該標記：

Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION marker · restart with CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1 to keep future transcripts

當您從另一個 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 在無法復原的介面錯誤後退出

當 Claude Code 退出時會列印此訊息，因為其終端介面遇到無法復原的錯誤，在任一轉譯器中都是如此。第二句僅在全螢幕轉譯器啟動時發生錯誤時出現：

Claude Code 在無法復原的介面錯誤 (<error>) 後退出。它在全螢幕轉譯器啟動時發生，因此下次啟動將使用傳統轉譯器（CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1 隨時強制執行）。

該怎麼做：

• 再次啟動 Claude Code。若要繼續進行對話，請在同一目錄中執行 claude --resume。
• 如果訊息命名全螢幕轉譯器，全螢幕轉譯會說明下次啟動的作用，這取決於您如何開啟全螢幕，以及如何再次嘗試全螢幕或保持傳統轉譯器。

在 v2.1.236 之前，Claude Code 在此類錯誤後退出而不列印訊息。

代理程式描述超過 15.0k 令牌限制

Claude Code 在對話檢視中顯示此警告作為啟動通知，而不是在 stderr 上。您的子代理程式（除了內建代理程式外）的組合描述超過 15,000 個令牌，如 Claude Code 估計的那樣。每個代理程式計算其名稱加上其 description frontmatter。Claude Code 無論總數是否超過限制都會載入每個代理程式，因此警告不會改變載入的內容。

代理程式描述超過 15.0k 令牌限制（~16.2k 令牌）· 要求 Claude 修剪 .claude/agents/ 中的代理程式描述

該怎麼做：

• 縮短您的代理程式檔案的 description frontmatter，或要求 Claude 為您修剪它們。
• 移除您不再使用的代理程式檔案。

技能、命令或工作流程未被載入，因為其名稱已保留

技能資料夾、frontmatter name、.claude/commands/ 中的檔案或子資料夾，或已儲存的工作流程使用名稱 anthropic-skills 或以 anthropic-skills: 開頭的名稱。Claude Code 保留該名稱用於從 claude.ai 同步的技能，不會載入該項目。

Claude Code 在對話檢視中顯示此警告作為啟動通知，而不是在 stderr 上：

未載入：重新命名 .claude/skills/anthropic-skills，然後重新啟動 — 其名稱使用 "anthropic-skills"，這是為從您的 claude.ai 帳戶同步的技能保留的名稱

通知命名它拒絕的第一個項目要變更的內容：要重新命名的資料夾或檔案、要編輯的 name: 行，或要重新命名的工作流程。當拒絕了多個項目時，通知以計數結尾，例如 · 2 more，偵錯日誌命名每一個。

該怎麼做：

• 重新命名通知命名的項目，或編輯它指向的 name: 行，然後重新啟動工作階段。

在 v2.1.282 之前，Claude Code 載入了具有這些名稱的技能和命令。

工作區尚未受信任

Claude Code 在專案的 .claude/settings.json 或 .claude/settings.local.json 中找到 permissions.allow 規則或 permissions.additionalDirectories 項目，但未應用它們，因為來自專案設定的允許規則需要工作區信任。計數、設定名稱和訊息中命名的檔案因您的設定而異。deny 和 ask 規則不受影響。

忽略來自 .claude/settings.local.json 的 2 個 permissions.allow 項目：此工作區尚未受信任。在此處以互動方式執行 Claude Code 一次並接受信任對話，或在 /Users/you/.claude.json 中設定 projects["/Users/you/project"].hasTrustDialogAccepted: true。

該怎麼做：

• 在目錄中執行 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 啟動時不包含該目錄。

\\server\share 是網路路徑，無法新增為工作目錄。在 Windows 上，將共用對應到磁碟機代號，並在啟動時使用 --add-dir 傳遞它（在工作階段中新增的磁碟機代號尚未帶有遠端讀取信任）。

Claude Code 以此方式拒絕的路徑包括：

• UNC 共用，例如 \\server\share
• 自動掛載路徑，例如 /net/<host>，除非您從該主機的自動掛載下的目錄啟動 Claude Code
• 透過符號連結或連接點到達網路位置的本機路徑

對應的磁碟機代號和 \\wsl$ 路徑不計為網路路徑。

該怎麼做：

• 在 Windows 上，將共用對應到磁碟機代號，例如使用 net use Z: \\server\share，並在啟動時使用 claude --add-dir Z:\ 傳遞磁碟機。
• 在 macOS 或 Linux 上，在本機路徑掛載共用並改為新增該路徑。
• 如果路徑在 permissions.additionalDirectories 中，請從列出它的設定檔中移除它。

在 v2.1.257 之前，Claude Code 接受可到達的網路路徑作為工作目錄。

遠端受管設定無法載入

您的工作階段符合伺服器受管設定的資格，但 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 僅在偵錯日誌中報告設定擷取失敗。

受管設定未獲批准

您的組織的伺服器受管設定包括需要您批准的設定，且您拒絕了安全批准對話，因此 Claude Code 退出而不應用它們：

受管設定未獲批准；退出而不應用它們。

該怎麼做：

• 再次啟動 Claude Code 並批准對話以在您的組織設定下繼續。拒絕的對話不會被記住，因此在下次啟動時會再次出現。
• 如果您對對話列出的設定不確定，在批准前詢問維護您的組織受管設定的人

受管設定阻止預設模型

您的組織的受管設定阻止預設選項解析為的模型以及它可以降級到的每個模型。將在預設選項上啟動的工作階段在啟動時退出，而不是執行被阻止的模型。您看到的訊息取決於阻止它的設定。當 deniedModels 清單阻止它時，訊息讀作：

Claude Code 無法啟動：您的組織的受管設定在 "deniedModels" 中阻止預設模型 (claude-opus-5-5)，且它們允許的模型都無法用作預設模型。要求您的管理員更新 "deniedModels" 或 "availableModels"。

當 availableModels 清單且 availableModelsMatch 設定為 "exact" 時省略它，訊息讀作：

Claude Code 無法啟動：您的組織僅允許 "availableModels" 中列出的模型，且它們都無法用作預設模型 (claude-opus-5-5 未列出)。要求您的管理員更新 "availableModels"。

該怎麼做：

• 如果您管理設定，將您的使用者可以執行的模型新增到 availableModels，或縮小阻止每個後備的 deniedModels 項目。阻止特定模型或版本描述預設選項如何降級
• 如果您不管理它們，將訊息傳送給您的管理員。您自己的設定檔案無法擴大受管 availableModels 或 deniedModels 清單

受管設定不允許此 API 提供者

您的組織的受管設定設定了 allowedProviders 清單，且工作階段的 API 提供者不在其上，或工作階段使用的端點不是以該項目要求的方式固定的。Claude Code 在啟動前、登入前或工作階段下次聯絡 API 時拒絕。訊息以允許的提供者開頭：

您的組織的受管設定允許 Claude Code 使用：Anthropic API、Amazon Bedrock。

當清單為空時，訊息改為讀作：

您的組織的受管設定允許 Claude Code 使用沒有 API 提供者（allowedProviders 是空清單），因此它無法在此機器上啟動。

當每個項目都無法辨識時，括號讀作 (allowedProviders lists only unrecognized entries) 代替。

該怎麼做：

• 遵循訊息的 To continue: 步驟
• 如果您管理設定，訊息的以 Admins: 開頭的行命名要新增的項目或要固定的值，allowedProviders 項目說明哪個來源的 env 區塊可以固定它

MCP 伺服器被企業受管策略阻止

您在 /mcp 中選擇了伺服器上的重新連線，或在那裡重新開啟了已停用的伺服器，且限制 MCP 伺服器的設定阻止該伺服器。Claude Code 拒絕連線它並顯示：

MCP 伺服器 <name> 被企業受管策略阻止

以下任何設定都可能產生訊息：

• 與伺服器相符的 deniedMcpServers 項目，包括您自己的 ~/.claude/settings.json 或專案的 .claude/settings.json 中的項目
• 伺服器不相符的 allowedMcpServers 清單
• strictPluginOnlyCustomization 且 mcp 已鎖定，這會阻止在 ~/.claude.json 和 .mcp.json 中設定的伺服器
• disableClaudeAiConnectors，當伺服器是 claude.ai 連接器時

該怎麼做：

• 檢查您自己的使用者和專案設定檔案中是否有這些設定之一，並變更或移除它
• 如果您自己的設定都不能解釋該阻止，請詢問您的管理員哪個受管設定阻止了伺服器

在 v2.1.257 之前，重新連線和在 /mcp 中重新啟用可以連線伺服器，該伺服器被中途工作階段策略更新阻止。

受管設定文件無法解析

您的組織部署受管設定，且其中一個已部署的文件存在但無法解析為 JSON 物件，因此 Claude Code 在啟動時以代碼 1 退出，而不是執行而不使用文件帶來的策略。行在訊息前命名失敗的來源：

/Library/Application Support/ClaudeCode/managed-settings.json：受管設定文件無法解析為 JSON 物件；其設定都不生效。修復或移除它。

來源是以下其中之一：

• managed-settings.json 檔案的路徑或 managed-settings.d 下的放入檔案
• 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 無法解析的文件中的設定無法強制執行，啟動時不應用組織的控制項會執行工作階段。

可解析文件中的架構問題不會產生此錯誤。尋找 Claude Code 放棄的項目涵蓋 Claude Code 對其所做的操作。

當 managed-settings.d/ 目錄存在但無法列出時，Claude Code 報告 Managed settings drop-in directory could not be read: 後跟基礎錯誤。尋找 Claude Code 放棄的項目涵蓋讀取失敗在啟動時退出的時間。

該怎麼做：

• 如果您管理機器，修復命名的文件使其解析為 JSON 物件，或移除檔案、設定檔或登錄值。空的 managed-settings.json 計為 {} 且不會阻止啟動。
• 如果您不管理，請要求您的管理員修復已部署的文件。您自己的設定檔案中沒有任何內容會導致或清除此錯誤。

無法讀取受管策略設定

您的組織部署受管設定，且其中一個已部署的來源存在但無法讀取，原因例如 I/O 錯誤而不是作業系統拒絕讀取。沒有其他管理來源提供策略，Claude Code 在啟動時退出，而不是執行而不使用來源可能帶來的策略：

無法讀取受管策略設定。
此機器可能需要組織登入強制執行，但策略檔案無法載入。
聯絡您的管理員。

詳細資訊：<source>: <reason>

在相同狀態下，登入流程、來自已執行工作階段的 API 要求，以及 claude gateway 伺服器被拒絕，使用命名 allowedProviders 的第一行變體。

作業系統拒絕的讀取（例如在僅限根的檔案上）不會產生此退出：工作階段啟動時不使用該來源的策略。對於無法解析的來源，Claude Code 以命名來源的不同訊息退出。

該怎麼做：

• 如果您管理機器，修復 Detail: 行命名的問題，以便已部署的來源可以讀取，或移除來源
• 如果您不管理，將訊息傳送給您的管理員。您自己的設定檔案中沒有任何內容會導致或清除此錯誤

在 v2.1.285 之前，僅使用 claude.ai 或 Claude Console 認證登入的工作階段以此訊息退出，作業系統拒絕的讀取也產生了它。

otelHeadersHelper 失敗

Claude Code 在互動工作階段中顯示此警告作為終端介面中的通知，每個工作階段一次，當 otelHeadersHelper 指令碼失敗或列印不符合指令碼要求的輸出時。

當指令碼持續失敗時，匯出失敗，您的遙測後端從工作階段接收不到任何內容。

See /status: 後面的文字說明失敗的內容，例如指令碼的結束代碼後跟其錯誤輸出：

otelHeadersHelper 失敗；遙測未被匯出。請參閱 /status：exited 1: token service unreachable

該怎麼做：

• 執行 /status 以讀取失敗詳細資訊。
• 修復指令碼使其在 30 秒內結束 0 並在 stdout 上列印 JSON 物件的字串標頭值。請參閱指令碼要求。
• 如果您的組織透過受管設定部署指令碼，要求維護它們的人修復它。

在非互動模式中使用 -p，相同的失敗改為在 stderr 上顯示為 otelHeadersHelper failed (OpenTelemetry export headers unavailable): <error>。

headersHelper 未執行

Claude Code 僅使用其靜態 headers 連線了 MCP 伺服器，並跳過了伺服器的 headersHelper，因為協助程式是 shell 命令且資料夾沒有已儲存的信任。當您手動在 ~/.claude.json 中設定其項目時，或在主目錄外，當您在互動工作階段中為其接受信任對話時，資料夾會獲得已儲存的信任。請參閱在 headersHelper 執行前信任資料夾以了解此檢查適用於哪些伺服器。

Claude Code 僅在非互動模式中寫入此行，每個伺服器一次。在互動工作階段中，它改為將相同的拒絕寫入偵錯日誌。

MCP 伺服器 'internal-api'：headersHelper 未執行 — 此工作區沒有持久化信任；在此處以互動方式接受信任對話一次，或在 /Users/you/.claude.json 中設定 projects["/Users/you/project"].hasTrustDialogAccepted。

訊息列印的 projects 金鑰是資料夾專案允許規則和工作區信任說明 Claude Code 信任的金鑰。為父資料夾接受信任對話不滿足檢查，-p 或 SDK 工作階段也不滿足。

該怎麼做：

• 在訊息命名的資料夾中執行 claude，接受信任對話，然後再次執行您的 -p 或 SDK 命令
• 在 ~/.claude.json 中自己設定 hasTrustDialogAccepted 項目，使用訊息列印的確切 projects 金鑰
• 如果您在主目錄中啟動工作階段，請從您已信任的專案目錄工作。當您在主目錄中接受信任對話時，Claude Code 僅在目前工作階段中保持該信任。

格式不正確的 Tool(content) 規則

您的設定檔案中的權限規則沒有 Tool 或 Tool(content) 的形狀，例如因為文字跟在右括號後面或其中一個括號遺失。Claude Code 跳過規則，並在互動工作階段啟動時在無效設定對話中列出它，以及在 claude doctor 輸出中：

無效權限規則 "Bash(ls) x" 已跳過：格式不正確的 Tool(content) 規則。規則採用 Tool 或 Tool(content) 的形式，必須在右括號 ")" 處結束；括號內的內容是字面意思

該怎麼做：

• 在訊息列出的設定檔中，重寫規則使其在其右括號處結束，例如用 Bash(ls *) 代替 Bash(ls) x
• 將括號內的內容保留原樣。它們是字面意思，因此規則如 Edit(./Finance (2024)/*) 無需逃逸即有效

在 v2.1.260 之前，Claude Code 將括號不相符的規則報告為 Mismatched parentheses。

不符合檔案權限檢查

Claude Code 在您的設定檔案、受管設定或 --allowedTools、--disallowedTools 或 --settings 旗標值中找到了具有路徑的 Write、NotebookEdit、MultiEdit 或 Glob權限規則。它僅針對 Edit 和 Read 規則檢查檔案權限，因此它永遠不會查詢命名其他檔案工具之一的路徑規則。它保留規則並不改變其他任何內容；警告命名規則、其在括號中的來源和要寫入的替換：

權限拒絕規則 (.claude/settings.json)：Write(docs/**) 不符合檔案權限檢查 — 僅 Edit(path) 規則。改用 Edit(docs/**)（Edit 規則涵蓋所有檔案編輯工具）。

該怎麼做：

• 將 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 接受這些規則而不警告。

在命令的其餘部分之前有萬用字元

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 保留規則並不改變它相符的方式；警告命名規則及其在括號中的來源：

權限允許規則 (.claude/settings.json)：Bash(git -C * status *) 在命令的其餘部分之前有萬用字元，因此它也符合在該位置插入的任何選項並批准它們而不提示。對於 git，選項如 -c 和 --exec-path 可以執行任意命令。將該 * 替換為您的確切值，或僅在子命令後使用 *（例如 Bash(git status *)）。

該怎麼做：

• 將子命令前的 * 替換為您的確切值：用 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 接受這些規則而不警告。

crossSessionInbound 必須是 accept、hold、refuse 之一

設定檔案將 crossSessionInbound 設定為 Claude Code 無法辨識的值，例如打字錯誤 "reject"。警告的第二句取決於哪個檔案保持該值；在使用者、專案、本機或 --settings 檔案中讀取：

"crossSessionInbound" 必須是 "accept"、"hold"、"refuse" 之一；收到 "reject"。此值被忽略；當它存在時，跨工作階段訊息被保持以供您批准，而不是被傳遞。將其設定為上述值之一。

在受管設定中，Claude Code 將無法辨識的值視為 refuse（最限制的值），警告說跨工作階段訊息被拒絕，直到管理員修復它。有關保持如何與您其他設定檔案中的值結合，請參閱 crossSessionInbound。

該怎麼做：

• 將金鑰設定為 "accept"、"hold" 或 "refuse"，或移除它
• 當警告命名受管設定時，要求管理員修復該值

在 v2.1.248 之前，Claude Code 忽略無法辨識的值而不警告。

200K 限制未強制執行

您設定了 CLAUDE_CODE_DISABLE_1M_CONTEXT=1，這通常使自動壓縮在 1M 上下文模型上保持工作階段至 200K 視窗，但沒有壓縮閾值將此工作階段限制在或低於 200K，因此對話可以超過它。

CLAUDE_CODE_DISABLE_1M_CONTEXT 已設定，但 <model> 的 200K 限制未強制執行，因此此工作階段可以超過它。若要強制執行，設定 CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000（或 autoCompactWindow 設定）。

Claude Code 為它辨識為具有原生 1M 視窗的每個模型自行強制執行 200K 限制，對於它無法辨識的模型 ID，它在它假設的視窗處壓縮。當其他設定擊敗該強制執行時出現警告：

• 模型 ID 不是 Claude Code 辨識的，例如LLM 閘道別名，且您設定了 CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1 或使用 CLAUDE_CODE_MAX_CONTEXT_TOKENS 將假設的視窗提高到 200K 以上。在此情況下，訊息也提供 or update to a Claude Code version that recognizes <model> 作為補救。
• 透過 ANTHROPIC_BETAS 或 --betas 旗標要求的 context-1m 測試版仍要求 API 在接受該測試版的模型上使用 1M 視窗，而沒有任何內容在 200K 處壓縮工作階段

該怎麼做：

• 設定 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 為您的 Claude Code 版本無法辨識的模型 ID 傳送了要求，並找不到將該 ID 對應到它辨識的模型的 modelOverrides 項目。Claude Code 仍使用您設定的 ID 傳送要求，不退出或切換模型。

[claude-code:unrecognized_model] {"model":"my-proxy-model","query_source":"sdk"}

在讀取 stderr 的指令碼或工具中，符合 [claude-code:unrecognized_model] 前綴。在前綴和一個空格之後，Claude Code 寫入一行 JSON 物件。Claude Code 可以在更新版本中向其新增欄位，因此忽略您不期望的任何欄位。它至少寫入這兩個：

• model：您設定的模型字串
• query_source：使用模型的要求路徑。Claude Code 為 -p 執行報告 sdk，為子代理程式報告以 agent: 開頭的值。

Claude Code 根據您執行它的方式將行寫入兩個位置之一：

• 在非互動模式中使用 -p，Claude Code 在每個 --output-format 下將其寫入 stderr，因此您可以解析 stdout 而不過濾行
• 在互動工作階段或背景工作階段中，Claude Code 改為將其寫入偵錯日誌；使用 --debug 在 ~/.claude/debug/<session-id>.txt 處擷取它

Claude Code 每個模型字串每個程序寫入行一次。它為每個進一步的無法辨識的 ID 寫入單獨的行，例如子代理程式或背景功能使用的 ID。

Claude Code 不為它解析為它辨識的模型的提供者 ID 寫入行，例如 Amazon Bedrock us.anthropic.claude-... ID、Google Cloud 的 Agent Platform ID 帶有 @ 版本後綴，以及包含 Claude 模型 ID 的 Microsoft Foundry 部署名稱。Claude Code 檢查 Amazon Bedrock應用程式推論設定檔 ARN 後面的模型，而不是 ARN 本身。它為無法解析的 ARN（例如打字錯誤的 ARN）寫入無行。

該怎麼做：

• 如果您故意設定 ID，例如LLM 閘道別名，將 modelOverrides 項目新增到您的設定檔案，以 ID 作為其值。使用 Anthropic 模型 ID 作為金鑰，而不是家族別名如 opus。對於範例行中的 my-proxy-model，新增此項目：

  {
    "modelOverrides": {
      "claude-opus-4-6": "my-proxy-model"
    }
  }
  

  Claude Code 然後將 my-proxy-model 視為 claude-opus-4-6 並停止寫入行。

• 如果 ID 命名比您的 Claude Code 版本更新的模型，執行 claude update

• 如果 ID 是打字錯誤，在您可以設定模型的位置或別名變數中修復它。如果 query_source 以 agent: 開頭，改為在您設定子代理程式模型的位置修復它。

在 v2.1.233 之前，Claude Code 為無法辨識的模型 ID 傳送要求時未寫入行。

被殺死的工作階段留下的過時沙箱遮罩檔案

claude doctor 在其診斷中列印此警告，/status 列出相同的行。它在 Linux 和 WSL2 上出現，當沙箱啟用且檔案系統隔離開啟時。

當沙箱化命令執行時，沙箱透過在那裡建立 0 位元組唯讀佔位符來保持對尚不存在的檔案的寫入拒絕，並在之後移除它。在該清理執行前被殺死的工作階段（例如透過 SIGKILL）會留下佔位符。後續工作階段在每次啟動時再次唯讀繫結它們，因此設定寫入（例如儲存「是，不要再問」）在其中一個所在的位置失敗。

- 被殺死的工作階段留下的過時沙箱遮罩檔案：/home/you/project/.claude/settings.local.json
  修復：在該專案中沒有其他 Claude Code 工作階段執行時，使用 `rm <path>` 移除每個 — 0 位元組唯讀檔案（其中設定檔案所在）使「是，不要再問」無法儲存，沙箱在每次啟動時再次唯讀繫結它

該怎麼做：

• 退出在該專案中執行的任何其他 Claude Code 工作階段，然後使用 rm 刪除每個列出的檔案。警告命名最多三個檔案並計算其餘的，因此在刪除後重新執行 claude doctor 直到警告不再出現。另一個工作階段的沙箱仍在使用的佔位符是該工作階段寫入保護的活躍部分
• 如果您使用「是，不要再問」儲存的權限選擇未堅持，在刪除佔位符後再次儲存它

在 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 以相同方式拒絕了一些請求。

回報錯誤

如需了解此頁面未涵蓋的元件錯誤，請參閱相關指南：

• MCP 伺服器連線或驗證失敗：MCP
• Hook 指令碼失敗或阻止了工具：Debug hooks
• 安裝期間權限被拒或檔案系統錯誤：Troubleshoot installation and login

如果此處未列出錯誤或建議的修正方法無法幫助：

• 在 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