Claude Code 無效 API key：找出 VPS 殘留設定

Claude Code 顯示無效 API key 錯誤的原因

Claude Code 顯示 Invalid API key 可能有兩種不同原因，而兩者的處理方式相反。第一種情況是你原本就要使用 API key，但該 key 錯誤、已撤銷，或屬於其他帳戶。第二種情況是你根本不打算使用 key，但伺服器環境中遺留的 ANTHROPIC_API_KEY 優先於你登入時使用的訂閱。Anthropic 的文件截至 2026 年 9 月明確指出第二種情況：即使你已登入，只要環境中設定了 key，系統就會改用該 key，而不使用 Claude Pro、Max、Team 或 Enterprise 訂閱。

在變更任何設定前，先確認自己屬於哪一種情況。啟動 Claude Code，然後執行 /status。文件說明輸出中會有 Login method 列，顯示你的訂閱帳戶；使用 API key 時，則會出現 API key 列。如果你只曾在該伺服器上執行 /login，卻看到 API key 列，問題就在環境設定中，而重新驗證不會修改這項設定。

以下所有內容都是要在你自己的伺服器上執行的命令。執行後先閱讀輸出，再採取後續操作。

憑證順序，以及為何 /login 沒有作用

存在多個憑證時，Claude Code 會依照文件記載的順序選擇憑證：

• 雲端供應商憑證，當 CLAUDE_CODE_USE_BEDROCK、CLAUDE_CODE_USE_VERTEX 或 CLAUDE_CODE_USE_FOUNDRY 已設定時。
• ANTHROPIC_AUTH_TOKEN 變數，會以 Authorization: Bearer 標頭傳送。
• ANTHROPIC_API_KEY 變數，會以 X-Api-Key 標頭傳送。
• apiKeyHelper script 的輸出。
• CLAUDE_CODE_OAUTH_TOKEN 變數，其中包含來自 claude setup-token 的 token。
• Anthropic profile 與 federation 憑證。
• /login 寫入的訂閱 OAuth 憑證。

請從清單底部往上查看。/login 會寫入最後一項憑證；在 Linux 上，該憑證會存放於 ~/.claude/.credentials.json，檔案模式為 0600。位於它上方的所有環境變數憑證都具有較高優先權。因此，重新登入只會更新工作階段根本不會使用的憑證：登入成功了，但憑證仍未生效。這就是看似合理的修正沒有作用的完整原因。

互動式工作階段還有一個容易造成混淆的步驟。文件指出，當環境中找到 API key 時，系統會提示你核准或拒絕一次，並記住你的選擇。你數個月前點選的核准仍然有效。請在 /config 中使用「使用自訂 API key」切換開關來變更設定；只有在環境中設定 ANTHROPIC_API_KEY 時，才會顯示這個切換開關。在非互動模式中，也就是 script 或 cron job 內的 claude -p，系統完全不會顯示提示：只要存在該 key，就一定會使用它。

如何找出 VPS 上殘留的 ANTHROPIC_API_KEY？

首先，確認該變數存在於你啟動 Claude Code 的 shell 中。

env | grep -i anthropic

接著執行 Anthropic 官方疑難排解頁面提供的修正指令；這也可同時用來測試：

unset ANTHROPIC_API_KEY
claude

如果 Claude Code 啟動後，/status 現在顯示你的訂閱資訊，就能確認原因。下一個 shell 中變數會再次出現，因為 unset 只會變更你執行指令的那個 shell。本節其餘內容將說明如何找出設定該變數的位置。

Shell 設定檔與全系統環境檔案

grep -rn ANTHROPIC ~/.bashrc ~/.bash_profile ~/.profile ~/.zshrc \
  ~/.config/fish/config.fish /etc/environment /etc/profile /etc/profile.d/ 2>/dev/null

Anthropic 的頁面列出 ~/.zshrc、~/.bashrc 和 ~/.profile。在伺服器上，應擴大搜尋範圍。使用者登入時，PAM（可插拔驗證模組）會讀取 /etc/environment，而且會套用至該伺服器上的每個使用者；同事設定的 key 因此可能出現在你的工作階段中。登入 shell 會執行 /etc/profile.d/ 中的檔案。請注意，只有互動式 shell 會讀取 .bashrc，因此它不可能造成 systemd 服務中的錯誤。實際需要檢查的檔案取決於 Claude Code 的啟動方式。

systemd 單元

單元不會讀取你的 shell 設定檔。其環境來自單元及任何 drop-in 中的 Environment= 與 EnvironmentFile= 設定。

systemctl cat claude-agent.service
systemctl show -p Environment claude-agent.service

systemctl cat 會輸出單元檔案，接著輸出 /etc/systemd/system/claude-agent.service.d/ 中的所有 drop-in；覆寫設定通常藏在這裡。systemctl show -p Environment 會輸出 systemd 實際傳遞給程序的內容。如果服務以你自己的使用者身分執行，請在兩個指令中都加入 --user。編輯單元後，執行 sudo systemctl daemon-reload 並重新啟動服務，因為環境會在程序啟動時組合，而執行中的程序會保留啟動時取得的環境副本。

超過設定檔修改時間仍持續執行的 tmux 與 screen 工作階段

這個問題常讓人耗費數小時。tmux 伺服器會保留啟動時的環境，新建立的窗格會繼承伺服器的環境，而不是你目前 shell 的環境。你從 .bashrc 移除 export、開啟新的窗格後，舊的 key 仍然存在。

tmux show-environment | grep -i ANTHROPIC
tmux set-environment -r ANTHROPIC_API_KEY

set-environment -r 指定要從 tmux 傳遞給新程序的環境中移除的名稱；加入 -g 則會從伺服器的全域環境中移除相同項目。已開啟的窗格會保留自己的副本，因為程序的環境只能從該程序內部變更。移除 export 後，可靠的做法是先 detach，執行 tmux kill-server，再建立新的工作階段。screen 的行為也相同。在 VPS 上設定 長時間執行的 Claude Code tmux 工作階段前，應先了解這點，因為這類工作階段很容易在多次設定檔修改後仍持續執行。

若要讀取已在執行中程序的環境，請向核心要求：

tr '\0' '\n' < /proc/$(pgrep -n claude)/environ | grep -i anthropic

這會輸出程序在 exec 時取得的值，也就是程序實際使用的環境。你必須是該程序的擁有者或 root，才能讀取該檔案；pgrep -n claude 會選取最新的符合項目，因此有多個程序執行時，請檢查 PID。

Docker 與 Compose

docker exec claude-agent env | grep -i anthropic
docker compose config

第一個指令會顯示執行中容器內的環境，包括來自 --env-file、environment: 區塊或映像檔內 ENV 設定的內容。docker compose config 會輸出解析變數後的 compose 檔案，因此你看到的是實際傳遞的值，而不是你撰寫的 ${ANTHROPIC_API_KEY} 佔位符。兩個指令都會將 secret 輸出到終端機，請在可接受清除內容的工作階段中執行。Compose 也會自動載入放在 compose 檔案旁邊的 .env 檔案，即使沒有明確指定；這通常就是沒有人記得加入的 key 來源。

每次修正 shell 後仍會保留的設定檔

Claude Code 設定檔包含 env 區塊，文件也明確說明了衝突處理方式：相同變數同時設定於 shell 和設定檔的 env 區塊時，會套用設定檔中的值。寫在那裡的 key 會覆蓋你輸入的所有 unset。

grep -rn ANTHROPIC ~/.claude/settings.json .claude/settings.json .claude/settings.local.json 2>/dev/null

請同時檢查專案檔案與使用者檔案。.claude/settings.json 通常會提交至版本控制，因此所有複製該 repository 的人都會共用。組織也可以推送受管理的設定，其優先順序高於你自己的檔案。如果你找到無法移除的 key，請向組織管理者詢問。

另一個分支：API key 確實不正確

如果 /status 顯示 API key，而且這是預期結果，請直接依錯誤內容判斷。Anthropic 的錯誤參考文件列出 Invalid API key 的以下原因：

• key 格式錯誤或內容不正確。
• key 已撤銷或已過期。
• key 隸屬於不同的組織或帳戶。

在不將值輸出到終端機歷程的情況下檢查它：

echo "len=${#ANTHROPIC_API_KEY} tail=${ANTHROPIC_API_KEY: -6}"

如果長度比預期多 1 或 2 個字元，通常表示複製貼上時一併帶入了結尾換行或引號，或是 $(cat keyfile) 擷取了檔案結尾的換行。這個值會以 X-Api-Key 標頭送出，因此多出的字元表示實際傳送的憑證不是你建立的那組 key。

也請在相同輸出中檢查 ANTHROPIC_AUTH_TOKEN，因為它在順序上位於 API key 之前。代理伺服器測試遺留的 bearer token，表示你正在修正的 key 根本不是實際送出的憑證。該輸出中的 ANTHROPIC_BASE_URL 也值得查看，因為舊值可能會將用戶端指向已不存在的 gateway。如需了解標頭層級的完整情況，請參閱 Anthropic API key 驗證的運作方式，其中說明各項內容的用途。在決定這台機器究竟應保存哪一種憑證之前，請先閱讀 訂閱登入與 API key 之間的取捨。

這個錯誤並非容量問題。如果工作階段已完成驗證，但執行期間的請求開始失敗，表示你遇到的是 模型過載錯誤，不需要變更憑證。

為什麼我的 apiKeyHelper 指令碼執行失敗？

apiKeyHelper 是一個設定鍵，用來指定 Claude Code 取得憑證時要執行的指令碼。它適合用於輪替或短效權杖，例如從 vault 取得的金鑰。這項介面很簡單：將目前的金鑰輸出至標準輸出，並正常結束。文件指出，若指令碼以錯誤結束、逾時，或沒有輸出內容，請求會在三次嘗試內因 Your apiKeyHelper script is failing 而失敗。

手動執行指令碼，並檢查這項介面的兩個部分：

out=$(/usr/local/bin/anthropic-key.sh)
echo "exit=$? len=${#out} tail=${out: -6}"

即使金鑰輸出正確，以非零狀態結束仍然表示失敗。若輔助指令碼在金鑰前先將 Fetching credential... 輸出至標準輸出，也會導致失敗，因為該行會成為憑證的一部分。請將進度訊息改送至標準錯誤。

接著，以服務實際執行的方式測試：

env -i HOME="$HOME" PATH=/usr/bin:/bin /usr/local/bin/anthropic-key.sh
echo "exit=$?"

env -i 會以幾乎為空的環境啟動指令碼。若輔助指令碼需要從 .bashrc 加入 PATH 的目錄呼叫 aws、vault 或 gcloud，手動測試時可能正常，但實際執行時會失敗，因為執行中的 Claude Code 程序從未讀取你的 .bashrc。請確認指令碼具有可執行權限，且它呼叫的所有項目都使用絕對路徑；或者直接在指令碼中設定 PATH。

伺服器上還有兩項文件記載的行為需要注意。Claude Code 預設會在五分鐘後重新執行輔助指令碼，而 CLAUDE_CODE_API_KEY_HELPER_TTL_MS 可設定不同的間隔。因此，若設定在啟動時正常，過了一小時後卻失敗，問題出在重新整理，而不是啟動。若輔助指令碼花費超過十秒才回傳金鑰，Claude Code 會在提示列顯示包含經過時間的警告通知。這項通知表示呼叫速度緩慢，不代表已損壞；它是逾時轉為錯誤前的早期警示。

你確定要在這台機器上保留 API key 嗎？

修正方式不一定是移除。當這台機器需要獨立計費時，應保留該 key：

• 在由 Console 計費的 VPS 上執行 unattended agent，不會消耗個人的訂閱額度。
• 執行非互動工作時，claude -p 沒有終端機可核准操作；只要存在該 key，就會一律使用它。
• 未綁定任何訂閱的機器。
• 共用機器或客戶端機器，完全不應儲存個人的訂閱登入資訊。

通常由成本決定這項選擇；可參考API 與訂閱方案的價格比較進行評估。

如果這台機器屬於你，而且使用的是你已經付費的訂閱，請移除該 key。接著要確保移除設定持續生效。不要將 key 匯出到 ~/.bashrc，讓每個互動式 shell 都繼承它；應只將 key 提供給需要它的服務：

[Service]
EnvironmentFile=/etc/claude-agent.env

將該檔案的權限設為 600，並由執行該服務的使用者擁有。你的互動式工作階段不會看到它，因此你自己的 claude 仍會使用訂閱，而該服務則繼續使用 key。如果你需要在沒有瀏覽器的環境中設定訂閱憑證，claude setup-token 會輸出 OAuth token，供你貼到 CLAUDE_CODE_OAUTH_TOKEN。在依賴這項功能前，應先了解文件記載的限制：它只能提出模型請求，因此無法使用 Remote Control 工作階段和 claude.ai connectors。每台機器各自決定一次，並將設定寫入 unit file，才能避免本頁所述的故障，因為該故障源自一個沒有人記得設定過的 key。憑證設定完成後，限制它可存取的範圍是另一項工作，請參閱在 VPS 上安全執行 Claude Code。

在使用最後手段前，請注意一點。/logout 會移除已儲存的憑證；文件也指出，它會一併清除已儲存的 MCP（model context protocol）伺服器登入資訊和 plugin secrets，因此之後必須重新授權這些項目。

FAQ

為什麼我已付費訂閱，Claude Code 仍顯示 API 金鑰無效？

因為環境中的 ANTHROPIC_API_KEY 優先於訂閱登入狀態。Anthropic 的文件指出，只要環境中設定了金鑰，系統就會改用該金鑰，而不使用 Pro、Max、Team 或 Enterprise 訂閱，即使你已登入也是如此。在非互動模式搭配 -p 時，只要金鑰存在，就一定會使用該金鑰。請在 Claude Code 中執行 /status，查看工作階段選用了哪一組認證。如果出現 API key 列，而你從未刻意設定該項目，請執行 unset ANTHROPIC_API_KEY，再重新啟動 claude，以確認原因。

執行 /login 能修正 API 金鑰無效錯誤嗎？

環境變數仍存在時，無法修正。/login 會寫入訂閱用的 OAuth 認證，而這類認證在 Claude Code 的認證順序中優先級最低，排在環境變數及 apiKeyHelper 之後。登入雖然成功，之後仍會被略過，因此重複登入不會改變結果。請從設定該變數的位置移除它，或在 /config 中關閉「使用自訂 API 金鑰」切換選項。文件指出，只有在環境中設定 ANTHROPIC_API_KEY 時，才會顯示此選項。

如何查看 Claude Code 使用哪種驗證方式？

請在工作階段中執行 /status。文件說明，Login method 列會顯示你的訂閱帳戶；使用 API 金鑰時，則會出現 API key 列。請在啟動 Claude Code 的同一個 shell 中，將結果與 env | grep -i anthropic 比對。如果服務或容器執行 Claude Code，請改用 tr '\0' '\n' < /proc/<pid>/environ 讀取程序環境，因為執行中的程序會保留啟動時取得的環境，而不是目前 shell 的環境。

我的 apiKeyHelper 指令碼可以正常執行，為什麼 Claude Code 仍然失敗？

通常是環境或結束狀態造成的問題。Claude Code 會從自身的程序執行 helper；該程序不會讀取你的 shell 設定檔，因此依賴 PATH 中 .bashrc 項目的 helper，可能在 Claude Code 中失敗，卻能在終端機中正常執行。請使用 env -i HOME="$HOME" PATH=/usr/bin:/bin /path/to/helper 測試，並在完成後檢查 echo $?。文件列出的失敗情況包括指令碼以錯誤結束、逾時或沒有輸出，這些情況會顯示為 Your apiKeyHelper script is failing。除了金鑰以外輸出至標準輸出的任何內容，都會成為認證內容的一部分，因此進度訊息應輸出至標準錯誤。