Claude Code API key 與訂閱登入差異

Claude Code 工作階段使用哪個憑證？

Claude Code 登入有兩種方式。您可以使用 claude.ai 的 Claude 訂閱帳戶登入，也可以對 Anthropic Console 組織進行驗證。後者會將每個 token 的用量計入該組織的 API（application programming interface）餘額。請在執行中的工作階段內執行 /status，查看目前使用哪種方式：Status 分頁會顯示您登入帳戶的 Login method 列；如果憑證由 API key 提供，還會額外顯示 API key 列。

工具是否包含在您的方案內，是另一個問題。相關說明請參閱Claude Code 是否包含在 Claude Pro 訂閱中；Claude API 的 key 驗證機制則請參閱Claude API 驗證的運作方式。以下內容不涵蓋這兩個主題，而是說明工作階段實際採用哪個憑證，以及如何變更憑證。

以下行為來自 Anthropic 的 Claude Code 驗證文件，文件查閱日期為 6 October 2026。Claude Code 經常發布新版本，其中數項行為要求最低版本。因此，請先執行 claude --version，再判斷您的機器是否故障。

可共用同一個電子郵件地址的兩個帳戶

claude.ai 帳戶與 platform.claude.com 上的 Claude Console 帳戶是不同帳戶。兩者可以使用相同的電子郵件地址，但仍是分開的登入身分，分屬不同組織，餘額也各自獨立。建立其中一個帳戶不會同時建立另一個帳戶。訂閱 Max 方案不會為 Console 組織增加額度，為 Console 組織儲值也不會增加方案額度。

餘額不同，是因為計費模式不同。訂閱登入會使用方案的用量額度；該額度會依 5 小時滾動視窗和每週視窗重設，且與 Claude 網頁版共用。Console 憑證則按 token 向組織計費，正式數據以 Console usage 頁面為準。這項差異對實際工作的費用影響，請參閱按 token 計費與訂閱付費的比較。

其中一種帳戶類型完全無法使用訂閱登入方式。Anthropic 列出的可登入帳戶包括 Pro 或 Max 訂閱、Claude for Teams 或 Enterprise 席位、Claude Console 帳戶、雲端服務提供者，以及 Cloud gateway；後者是由組織自行執行的 self-hosted Claude apps gateway，並透過 /login 使用企業 SSO（single sign-on）登入。免費 claude.ai 帳戶不在清單中，因此免費方案使用者沒有可用於登入的訂閱憑證，而Claude 免費方案包含與不包含的功能也不適用於命令列工具。剩下的方式，是使用具備 API 額度的 Console 組織；這是另一種形式的付費帳戶。

路徑一：使用 Claude 訂閱登入

在專案目錄中執行 claude。第一次啟動時，程式會開啟瀏覽器視窗，讓您使用持有方案的 claude.ai 帳戶登入。

claude

在伺服器上，有兩種情況的行為不同。如果瀏覽器沒有開啟，請按 c 將登入 URL 複製到剪貼簿，再貼到您自己電腦上的瀏覽器。如果該瀏覽器顯示登入代碼，而不是將您導回終端機，請把代碼貼回要求輸入代碼的提示中。在 SSH（secure shell）、WSL2 及容器中，第二種情況都屬正常，因為瀏覽器無法連線到 Claude Code 在遠端機器上啟動的本機回呼伺服器。

登入完成後，請檢查登入狀態，不要直接假設已成功。啟動工作階段並執行 /status。Status 索引標籤會列出登入方法，以及儲存的組織與電子郵件地址。/login 會使用另一個帳戶重新執行登入流程，/logout 則會移除儲存的憑證。登出也會重設首次啟動設定狀態，因此下一次執行 claude 時，系統會再次引導您完成初始設定。

重建伺服器或將伺服器交接給其他人時，了解憑證的儲存位置很重要：

• Linux：~/.claude/.credentials.json，檔案模式為 0600。
• macOS：加密的 Keychain。Keychain 拒絕寫入時，通常是因為在 SSH 工作階段中處於鎖定狀態，Claude Code 會退回使用相同的 0600 檔案。使用 Console 登入建立 API key 不會採用這項備援，必須等到 Keychain 可寫入後才會成功。
• Windows：%USERPROFILE%\.claude\.credentials.json，並由 profile 目錄本身的存取控制限制為您的使用者。
• 設定 CLAUDE_CONFIG_DIR 的任何平台：檔案會移至該目錄下，而 macOS Keychain 項目也會以此目錄作為索引。因此，使用不同 CLAUDE_CONFIG_DIR 啟動的工作階段會讀取不同的憑證。

Claude Code 會透過 /login 和 /logout 管理該檔案。手動編輯檔案不是切換帳戶的支援方式。

路徑 2：向 Console 組織進行驗證

Console 存取權限由管理員開始設定。管理員會在 Console 依序開啟 Settings、Members，再選取 Invite 邀請您，也會指派角色：Claude Code 角色只能建立 Claude Code API keys，Developer 角色則可建立任何 key。接著，您會在 /login 提示中選擇 Anthropic Console 帳戶。

從 Claude Code v2.1.242 起，Console 提供兩種登入路徑，且儲存的內容不同。使用 Console 帳戶登入時，Claude Code 會保留該瀏覽器登入工作階段取得的 OAuth（開放授權）token，並將其儲存為 Anthropic profile，完全不建立 API key。Claude Code 會自行更新該登入狀態；更新失敗時，請求會失敗，直到您再次登入為止。這種不使用 key 的登入方式，也會將電腦上儲存的 claude.ai 登入狀態登出。建立 API key 時，提示會將其標示為 legacy；此操作會建立 Console key，並將其與其他憑證一同儲存。靜態 key 不會自動更新，因此在有人撤銷前都能持續運作。這對建置伺服器很有用，但在筆記型電腦上則會增加風險。

開始使用不含 key 的 Console 登入前，請取消設定 ANTHROPIC_API_KEY。若設定了此變數，Claude Code 會完全略過登入提示，改為要求您核准它找到的 key。

您不一定能選擇登入方式。當工作階段使用 cloud provider，任何設定檔設定了 forceLoginOrgUUID，或將 forceLoginMethod 固定為 "claudeai" 或 "console" 時，Claude Code 會在不詢問的情況下建立 key。如果電腦上存在 managed settings source，且 Claude Code 無法讀取該來源，也會採用相同處理。這些都是管理員的決策；如果您始終看不到不含 key 的選項，請詢問管理整個機隊的人員。/status 也會輸出一行 Setting sources，列出該工作階段載入的所有設定檔；若有 managed source 適用於您，也會列出該來源。

您第一次將 Claude Code 向 Console 組織進行驗證時，Console 會為其建立名為 "Claude Code" 的 workspace。建立此 workspace 是為了集中追蹤 Claude Code 的支出，且您無法在其中建立 API keys。

登入後為何 ANTHROPIC_API_KEY 會優先使用

Claude Code 不會詢問您偏好使用哪個憑證。它會依固定順序檢查來源，並使用第一個找到的來源。根據 2026 年 10 月的文件，順序如下：

1. 雲端服務提供者憑證，當 CLAUDE_CODE_USE_BEDROCK、CLAUDE_CODE_USE_VERTEX 或 CLAUDE_CODE_USE_FOUNDRY 已設定時。
2. ANTHROPIC_AUTH_TOKEN，以 Authorization: Bearer 標頭傳送，供使用 bearer token 進行驗證的 gateway 使用。
3. ANTHROPIC_API_KEY，以 X-Api-Key 標頭傳送。
4. 設定檔中指定的 apiKeyHelper script 輸出。
5. CLAUDE_CODE_OAUTH_TOKEN，來自 claude setup-token 的長期 token。
6. Anthropic profile 與 federation 憑證，也就是 ant CLI 和 Workload Identity Federation 使用的憑證。
7. /login 寫入的訂閱憑證。

這份清單有兩個例外。如果您在 ANTHROPIC_PROFILE 中指定 profile、設定 federation 變數，或目前使用的 profile 是 Workload Identity Federation profile，該 profile 會排在第 6 順位。處於 user_oauth 模式的 active profile，也就是由 ant auth login 或不使用 key 的 Console 登入所寫入的 profile，則會排在可正常運作的 /login 憑證之後。此外，已登入 Claude apps gateway 的工作階段完全不在這份清單中，優先順序高於清單中的所有來源，包括雲端服務提供者變數。當管理員管理的設定要求使用 gateway 登入時，Claude Code 會略過其他來源，並要求您透過 /login 登入。

這兩個例外都無法讓訂閱帳戶優先於已匯出的 key。在沒有 gateway 的情況下，第 1 至第 5 順位的所有來源都優先於您登入的帳戶。因此，只要程序環境中的任何位置匯出了 ANTHROPIC_API_KEY，就會使用該 key；即使您以為系統正在使用訂閱方案，該工作階段仍會向 Console organisation 計費。這不是故障。系統只是依文件所述的順序運作，因此不會顯示警告。

有兩個細節容易造成誤判。在互動式工作階段中，Claude Code 只會詢問一次是否使用找到的 key，並記住您的選擇，因此一個月前做出的選擇今天仍會套用。在使用 -p 的非互動模式中，系統完全不會提示；只要 key 存在，就一定會使用。-p 是 cron job 或 CI（continuous integration）步驟執行時使用的模式，因此無人值守的工作正是最容易長時間忽略錯誤憑證的情況。

您可以在工作階段中快速查看狀態。設定 ANTHROPIC_API_KEY 時，/config 會顯示「Use custom API key」切換開關。只有在變數已設定時才會顯示此開關，因此看不到開關表示環境中沒有該變數。

尋找伺服器上遺留的金鑰

匯出的金鑰可能存在於 shell 設定檔以外的多個位置：

• ~/.bashrc、~/.bash_profile、~/.profile 或 ~/.zshrc，每個新的登入 shell 都會讀取這些檔案。
• systemd unit 透過 Environment= 或 EnvironmentFile= 設定的環境，適用於以服務方式執行的程式。
• tmux server 會保留啟動時取得的環境副本。即使你上週已從設定檔刪除某個變數，今天開啟的 pane 仍可能繼承該變數，因為 server 在修改前就已經持續執行。
• 容器映像或 CI job 定義，其中的變數設定在 shell 內部無法讀取的檔案之外。
• Claude Code 設定檔的 env 區塊。這是一般的設定鍵，並遵循一般設定優先順序。

在進行其他操作前，先檢查這些位置：

[ -n "$ANTHROPIC_API_KEY" ] && echo "ANTHROPIC_API_KEY is set" || echo "not set"
env | grep -E '^(ANTHROPIC_|CLAUDE_CODE_)' | cut -d= -f1
grep -n 'ANTHROPIC_API_KEY' ~/.bashrc ~/.bash_profile ~/.profile ~/.zshrc 2>/dev/null
tmux show-environment 2>/dev/null | grep ANTHROPIC
grep -n 'ANTHROPIC_API_KEY\|apiKeyHelper' ~/.claude/settings.json .claude/settings.json .claude/settings.local.json 2>/dev/null

第二個命令刻意透過 cut 傳送輸出，因此只會顯示變數名稱，不會將 secret 值顯示在可能正在分享或錄製的畫面上。第一個命令會直接判定結果：如果顯示已設定該變數，接著從此 shell 啟動的 claude 就會使用該金鑰。五個位置都沒有輸出，表示環境中不存在憑證，因此從此處啟動的工作階段會改用你的 /login 憑證。

對任何執行 Claude Code 的服務加入 systemctl cat your-unit.service | grep -i environment，因為 unit 檔案會自行設定環境，且不會讀取你的 shell 設定檔。

將工作階段從一組憑證切換至另一組

若要切換回訂閱：

unset ANTHROPIC_API_KEY
[ -n "$ANTHROPIC_API_KEY" ] && echo "still set" || echo "clear"
claude

等待 clear，然後在新的工作階段中執行 /status，並確認 API key 列已消失。對已在執行中的 Claude Code 程序而言，在 shell 中取消設定該變數不會產生任何作用，因為程序會保留啟動時取得的環境。請重新啟動工作階段。

接著，從設定該變數的檔案中刪除 export，否則下一次登入 shell 會再次設定它。在 tmux 中，tmux set-environment -u ANTHROPIC_API_KEY 會清除該變數；此變更只會套用至工作階段中之後開啟的窗格，已開啟的窗格仍保留各自的副本。

若要反向切換，請在環境中設定 ANTHROPIC_API_KEY，或執行 /login 並選取 Console 帳戶。若要完全清除已儲存的登入資訊，請執行 /logout。完成無金鑰 Console 登入後，/logout 會移除並撤銷該次登入寫入的憑證。

如果 /status 顯示的內容仍與預期不符，請執行 claude doctor。這會列出 Claude Code 拒絕的設定項目，可找出語法解析失敗、因此完全未套用的設定檔。

沒有瀏覽器時進行驗證

claude setup-token 會開啟與 /login 相同的瀏覽器授權流程，並將有效期一年的 OAuth 權杖輸出到終端機。

claude setup-token

它不會在任何位置儲存權杖，因此權杖出現時請立即複製。將它設定為需要使用該權杖之機器上的 CLAUDE_CODE_OAUTH_TOKEN。此權杖會以您的訂閱方案進行驗證，因此需要 Pro、Max、Team 或 Enterprise 方案，且只能發出模型請求。Bare mode 不會讀取此權杖，因此傳遞 --bare 的指令碼需要 ANTHROPIC_API_KEY，或改用 apiKeyHelper。

這裡同樣會受到優先順序影響。如果 CLAUDE_CODE_OAUTH_TOKEN 位於 shell 設定檔中，執行 /login 會將目前工作階段切換至新的登入狀態；在移除該變數前，每個新的工作階段都會再次讀取它。

如果您的組織透過 Amazon Bedrock、Google Cloud 或 Microsoft Foundry 執行推論，這些憑證會位於優先順序的最前端，完全不會進行瀏覽器登入。相關設定是另一項工作，請參閱 讓 Claude Code 連線至 Bedrock 或 Vertex。

VPS（virtual private server）上的長時間工作階段最容易出現這些問題，因為啟動該工作階段的 shell 可能在數個月前就已完成設定，之後從未重新啟動。在 VPS 的 tmux 內執行 Claude Code 說明此設定的工作階段部分。

檢查各憑證實際消耗的額度

在訂閱登入狀態下，/usage會顯示方案用量列，以及各項消耗的明細。其 Session 區塊中的金額，是根據 token 數量與牌價在本機計算，因此只能視為估算值，主要供 API 使用者參考，並非帳單金額。訂閱者應查看用量列，不要查看金額。

使用 Console 憑證時，應以 Console 中的數據為準：使用量頁面用於查看支出，Claude Code 儀表板則用於查看各成員的數據。終端機中顯示的任何內容，都不是該計費資訊的權威來源。

如果你工作時方案用量列始終沒有變化，表示環境憑證在憑證優先順序中勝出。這個單一現象是判斷目前使用錯誤憑證的最可靠跡象；追蹤 Claude Code 工作階段的消耗會進一步說明如何測量。如果用量列先變化，之後停止變化，則表示已達到方案上限；Claude 用量限制與重設時段的運作方式會說明相關內容。

失敗模式與檢查重點

所有功能都正常，但方案用量始終沒有變化。 環境憑證正在生效。/status 顯示一列 API key，上方的 shell 檢查也顯示了該變數。

訂閱狀態正常，但請求仍然失敗。 屬於已停用或已過期 Console 組織的金鑰，優先於你的登入憑證。執行 unset ANTHROPIC_API_KEY，啟動新的工作階段，然後再次檢查 /status。如果錯誤訊息指出 API key 無效，修正 Claude Code 的無效 API key 錯誤會詳細說明這種情況，也會解釋為何再次執行 /login 仍無法清除問題。

啟動時顯示登入即將到期的警告。 最近版本會在 /login 憑證距離到期不到三天時發出警告。憑證實際到期後，/status 會將登入列顯示為已過期，並列出儲存的組織與電子郵件。執行 /login 以續期。警告不會阻止請求，因此很容易被忽略，直到無人值守的工作階段停止處理請求。

apiKeyHelper 執行緩慢或失敗。 Claude Code 預設每五分鐘重新執行一次此輔助程式，可使用 CLAUDE_CODE_API_KEY_HELPER_TTL_MS 調整。若一次執行超過十秒，提示列會顯示通知。無論是發生錯誤或逾時，只要輔助程式未回傳金鑰，請求就會在三次嘗試內失敗。

憑證正確，但組織錯誤。 同一個電子郵件地址可能屬於兩個組織。/status 會列出通過驗證的組織，因此應閱讀該列，不要自行假設目前登入的是哪個組織。

FAQ

如何判斷 Claude Code 目前使用哪個帳號？

在工作階段中執行 /status。Status 索引標籤會針對您登入的帳號顯示 Login method 列；使用 API key 提供憑證時，還會加入 API key 列。改用 Anthropic profile 或 federation credential 時，Profile 列會取代登入列。在工作階段外，檢查 shell 中是否設定 ANTHROPIC_API_KEY，即可判斷是否存在優先於登入憑證的環境憑證。

為什麼 Claude Pro 或 Max 訂閱沒有生效？

因為環境憑證的優先順序較高。Claude Code 會依固定順序使用第一個找到的憑證，而 /login 訂閱憑證的優先順序低於雲端供應商變數、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY、apiKeyHelper、CLAUDE_CODE_OAUTH_TOKEN，以及您透過 ANTHROPIC_PROFILE 或 federation variables 選取的 Anthropic profile 或 federation credential。只有 user_oauth 模式中的啟用 profile 優先順序低於它；已登入的 Claude apps gateway 工作階段則優先於整個清單。執行 unset ANTHROPIC_API_KEY，啟動新的工作階段，再使用 /status 確認。接著從設定該變數的 shell profile、systemd unit、tmux environment 或 container definition 中移除 export，否則下一次登入 shell 時它會再次出現。

我可以使用 Claude Code 搭配免費 Claude 帳號嗎？

不行。Anthropic 列出的登入帳號類型包括 Pro 或 Max 訂閱、Claude for Teams 或 Enterprise seat、Claude Console 帳號、雲端供應商，以及 Cloud gateway。Cloud gateway 是透過 /login 使用 corporate SSO 登入的 self-hosted Claude apps gateway。免費 claude.ai 帳號不在其中，因此沒有可供 Claude Code 儲存的訂閱憑證。訂閱以外的付費方式，是使用具有 API credit 的 Claude Console organisation，依 token 計費。即使使用相同的 email address，這仍是不同的帳號。

claude.ai 帳號和 Console 帳號共用同一個餘額嗎？

不共用。即使兩者使用相同的 email address，也是不同帳號，並分別計費。訂閱用量會扣除方案額度；此額度與 Claude 網頁版共用，並以滾動的五小時視窗及每週視窗重設。Console 用量則依 token 向 organisation 計費，並顯示在 Console usage page。為其中一個帳號新增 credit，不會影響另一個帳號。

如何在無頭伺服器上驗證 Claude Code？

有兩種方式。透過 SSH 執行 claude，並在自己的電腦上完成瀏覽器登入：按下 c 複製 URL，前往該網址登入；如果瀏覽器顯示 code 而未重新導向，再將 code 貼回終端機。另一種方式是在具備瀏覽器的電腦上執行 claude setup-token，複製其輸出的一年期 token，再於伺服器上將它設定為 CLAUDE_CODE_OAUTH_TOKEN。該 token 需要 Pro、Max、Team 或 Enterprise 方案，且只能提出 model requests。因此，使用 --bare 的 script 需要 API key 或 apiKeyHelper。