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

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

Claude Code 顯示 Invalid API key 時，可能是兩種不同原因造成的，對應的修正方式也完全相反。第一種情況是，您原本就要使用 API key，但該金鑰錯誤、已撤銷，或屬於其他帳戶。第二種情況是，您根本不打算使用金鑰，但伺服器環境中殘留的 ANTHROPIC_API_KEY 優先於您登入時使用的訂閱。根據 Anthropic 截至 2026 年 10 月的文件，第二種情況的規則很明確：環境中設定的金鑰一旦獲准使用，就會取代您的 Claude Pro、Max、Team 或 Enterprise 訂閱，即使您已登入也是如此；使用 claude -p 時，只要金鑰存在，就一定會使用該金鑰。

變更任何設定前，先確認您屬於哪一種情況。啟動 Claude Code，然後執行 /status。文件說明，Login method 列會顯示您的訂閱帳戶；使用 API key 時，則會出現 API key 列。如果您只曾在該伺服器上執行 /login，卻看到 API key 列，請檢查環境、設定及 apiKeyHelper；重新驗證不會移除這些憑證。

以下內容中的每個指令都應在您自己的伺服器上執行。先閱讀輸出結果，再採取任何動作。

憑證使用順序，以及為何 /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 指令碼的輸出。
• CLAUDE_CODE_OAUTH_TOKEN 變數，其中包含來自 claude setup-token 的 token。
• 透過 ANTHROPIC_PROFILE 明確選取的 Anthropic 設定檔、透過環境變數選取的 federation 憑證，以及使用 oidc_federation 驗證的作用中或預設設定檔。
• /login 寫入的訂閱 OAuth 憑證。
• 使用 user_oauth 驗證的作用中或預設 Anthropic 設定檔，除非 ANTHROPIC_PROFILE 明確選取該設定檔。

請從清單底部往上看。/login 會寫入訂閱 OAuth 憑證；在 Linux 上，這些憑證會儲存在 ~/.claude/.credentials.json，檔案模式為 0600。除非 ANTHROPIC_PROFILE 明確選取該設定檔，否則這些憑證的優先順序高於作用中或預設的 user_oauth 設定檔，但低於環境憑證與 apiKeyHelper。已核准的環境 API key 仍會優先於訂閱登入。因此，重新登入只會更新工作階段根本不會使用的憑證：登入成功了，但該憑證仍未被使用。這就是看似合理的修正沒有作用的完整原因。使用 CLAUDE_CODE_OAUTH_TOKEN 時，/login 會將目前工作階段切換至新的登入狀態；但新工作階段仍會再次讀取該變數，直到你將其移除為止。已登入的 Claude apps gateway 工作階段不在此優先順序中；它會使用 gateway token，而不是這些憑證，即使已設定雲端服務供應商變數也是如此。

互動式工作階段還會多一個容易造成混淆的步驟。文件指出，系統會提示你一次，讓你核准或拒絕環境中的 API key，並記住你的選擇。如果你幾個月前已核准，該核准仍然有效，這個 key 會持續優先於登入狀態。如果你拒絕了，系統會忽略該 key，且不再詢問，因而產生相反的疑問：變數已設定，env 也顯示該變數，但工作階段始終不使用它。你可以在 /config 中使用「使用自訂 API key」切換開關，變更這項選擇；只有在環境中設定 ANTHROPIC_API_KEY 時，才會顯示該切換開關。在非互動模式中，也就是指令碼或 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_env 模組的登入 PAM（可插拔驗證模組）設定會讀取 /etc/environment，這就是全系統金鑰進入工作階段的方式。登入 shell 的 profile 載入 /etc/profile.d/ 中的檔案時，這些檔案會執行。systemd 服務不會自動讀取 .bashrc；請確認其命令是否明確啟動 shell 或載入 profile。實際需要檢查的檔案，取決於 Claude Code 的啟動方式。

systemd 單元

單元不會讀取你的 shell profile。其環境包含單元本身及任何 drop-in 中的 Environment= 和 EnvironmentFile= 行，以及服務管理程式提供的變數。

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

systemctl cat 會列出單元檔案及其 drop-in，包括 /etc/systemd/system/claude-agent.service.d/ 下的覆寫設定。systemctl show -p Environment 會顯示單元的 Environment= 設定；也請檢查任何 EnvironmentFile= 檔案，因為程序啟動時會另外讀取其內容。若服務由你自己的使用者帳號執行，請在兩個命令中都加入 --user。編輯單元後，請執行 sudo systemctl daemon-reload 並重新啟動服務，因為環境會在程序啟動時組合，而執行中的程序會保留啟動時取得的環境副本。

存活至設定修改後的 tmux 與 screen 工作階段

這個問題常讓人花上數小時。tmux server 會保留啟動時取得的環境，新 pane 會繼承合併後的全域環境與工作階段環境。你從 .bashrc 移除 export、開啟新的 pane，舊金鑰卻仍然存在。

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

set-environment -r 會標記要從 tmux 傳給新程序的環境中移除的名稱，加入 -g 則會對 server 的全域環境執行相同操作。已開啟的 pane 仍保留自己的副本，因為程序的環境只能從該程序內部變更。移除 export 後，可靠的做法是先 detach，執行 tmux kill-server，再啟動新的工作階段。在 VPS 上設定 長時間執行的 tmux Claude Code 工作階段 前，值得先了解這點，因為這類工作階段正是會存活於多次設定修改之後的程序。

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

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

這會列出程序在 exec 時取得的值，不會反映之後的變更，例如 Claude Code 從設定載入的值。你必須是該程序的擁有者或 root，才能讀取該檔案；pgrep -n claude 會選取最新的比對結果，因此若有多個程序正在執行，請檢查 PID。

Docker 與 Compose

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

第一個命令會顯示執行中容器內的環境，包括來自 --env-file、environment: 區塊，或寫入 image 的 ENV 行的內容。docker compose config 會輸出解析變數後的 compose 檔案，因此你看到的是實際傳入的值，而不是撰寫時使用的 ${ANTHROPIC_API_KEY} 預留位置。兩個命令都會將 secret 顯示在終端機上，因此請在可接受清除紀錄的工作階段中執行。Compose 預設也會從專案目錄載入 .env 檔案以進行插值；當 Compose 設定將其中的值傳遞出去時，該值就會進入容器。

每次修正 shell 後仍然存在的設定檔

Claude Code 設定檔包含 env 區塊，文件也明確說明這項衝突：同一變數同時設定於 shell 和設定檔的 env 區塊時，多數工作階段會套用設定檔中的值。例外是由 Claude Desktop 應用程式或自架環境 runner 啟動的工作階段，此時以啟動環境為準。對於在伺服器終端機中啟動的 claude，其中寫入的金鑰會覆寫你輸入的所有 unset。

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

請同時檢查專案檔案與使用者檔案。.claude/settings.json 通常會提交至版本庫，因此所有 clone 該 repository 的人都能取得。組織也可能推送受管理的設定，其優先順序高於你自己的檔案。如果找到無法移除的金鑰，請詢問負責管理的人員。

另一個分支：金鑰確實不正確

如果 /status 顯示 API key，而且這是預期結果，請直接依錯誤訊息判斷。Anthropic 的錯誤參考指出，Invalid API key · Fix external API key 表示 API 拒絕了來自 ANTHROPIC_API_KEY 或 apiKeyHelper script 的 key，或 Claude Code 在送出前封鎖了該 key。此錯誤的檢查項目如下：

• 檢查 key 是否有拼字錯誤。
• 在 Console 中確認該 key 尚未被撤銷。
• 確認 direnv、dotenv shell plugin 或 IDE terminal 等工具沒有從專案的 .env 檔案載入過期的 key。

在不將值輸出到終端機回捲內容的情況下檢查該值：

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

如果長度比預期多 1 或 2 個字元，通常表示複製貼上時一併帶入了換行或引號，或是以 Windows 換行格式儲存的 key 檔案留下了 carriage return。使用 $(cat keyfile) 讀取檔案時，純粹位於結尾的換行不會保留，因為 Bash 會從 command substitution 的輸出中刪除結尾換行。但它不會刪除該換行前的 carriage return，因此使用 Windows 換行格式的檔案仍會在變數中留下 1 個額外字元。近期版本會在送出前攔截 header 無法承載的字元：當訊息在 Fix external API key 之後繼續出現 Invalid X-Api-Key header value from ANTHROPIC_API_KEY: it contains a line break 等描述時，Claude Code 已停止該請求，API 根本沒有收到 key。彎引號也會被相同檢查攔截，但直引號是合法的 header 字元，因此會作為 X-Api-Key header 的一部分送出，實際傳送的憑證並不是你建立的 key。

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

這個錯誤不是容量問題。如果請求因 529 Overloaded 而失敗，請參閱 模型過載錯誤；這種情況不需要變更憑證。

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

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

手動執行指令碼，並檢查這兩項要求：

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

即使金鑰輸出正確，只要結束狀態非 0，仍然算是失敗。若 helper 在金鑰前先將 Fetching credential... 輸出至標準輸出，也會失敗：自 v2.1.227 起，Claude Code 會拒絕包含金鑰以外內容的輸出，並回報 helper returned output that cannot be used as an API key；較舊版本則會將該行一併當作憑證內容傳送。請將進度訊息改送至標準錯誤。在工作階段中，/status 會顯示一列 apiKeyHelper，內容為 Failing，其中包含上次的結束狀態與錯誤輸出。

接著，使用服務實際執行時的方式測試：

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

env -i 會以幾乎為空的環境啟動指令碼。若 helper 從 .bashrc 加入 PATH 的目錄中呼叫 aws、vault 或 gcloud，在測試時可能正常，但在啟動環境不含該目錄的服務中就會失敗。請確認指令碼具有可執行權限，且其呼叫的所有項目都使用絕對路徑；或者直接在指令碼中設定 PATH。

伺服器上還有兩項文件記載的行為需要注意。Claude Code 預設會在五分鐘後重新執行 helper，而 CLAUDE_CODE_API_KEY_HELPER_TTL_MS 可設定不同的間隔。因此，若設定在啟動時正常，執行一小時後才失敗，問題出在重新整理，而非啟動。若 helper 超過十秒才回傳金鑰，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 key 無效？

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

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

如果已核准的環境 API key 仍在使用中，無法修正。/login 會將訂閱 OAuth 認證資訊寫入環境認證資訊與 apiKeyHelper 之下，但優先順序高於作用中的或預設的 user_oauth 設定檔；除非由 ANTHROPIC_PROFILE 明確選取該設定檔。登入會成功，但之後仍會被略過，因此重複登入不會改變結果。請從設定該變數的位置移除它，或在 /config 中關閉「Use custom API key」切換開關。文件指出，只有在環境中設定 ANTHROPIC_API_KEY 時，才會顯示這個開關。

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

在工作階段中執行 /status。文件說明，Login method 列會顯示你的訂閱帳戶；使用 API key 時，則會出現 API key 列。將結果與啟動 Claude Code 的相同 shell 中的 env | grep -i anthropic 比較。如果服務或容器執行 Claude Code，請使用 tr '\0' '\n' < /proc/<pid>/environ 檢查其啟動環境；該檔案會顯示 exec 時提供的值，因此也要檢查 Claude Code 之後載入值的設定檔。

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

通常是環境或結束狀態造成的。Claude Code 會使用自己的程序環境執行 helper，因此服務若缺少終端機環境中的 PATH 項目，就無法找到你在終端機中測試時可以正常執行的命令。請使用 env -i HOME="$HOME" PATH=/usr/bin:/bin /path/to/helper 測試，並在之後檢查 echo $?。文件列出的失敗情況包括指令碼以錯誤結束、逾時、沒有輸出，或輸出不是 key；這些情況會顯示為 Your apiKeyHelper script is failing。自 v2.1.227 起，若標準輸出包含 banner 或日誌行，helper 會直接失敗，因此請將進度訊息傳送至標準錯誤。