登入與認證

安裝完成後，第一件事不是急著跑任務，而是確認 Claude Code 到底用哪一種身份在工作。訂閱賬號、API Key、企業雲憑據同時存在時，真正生效的可能不是你以為的那一個。——翔宇

這一章用 12 分鐘換什麼：上一章把 Claude Code 裝到了本機。這一章講登入和認證：個人訂閱怎麼登入，團隊和 Console 怎麼開通，Bedrock / Vertex AI / Foundry 怎麼接入，多個憑據同時存在時誰優先。

1. 先分清“登入”和“認證”

新手常把兩件事混在一起：

登入：瀏覽器裡授權 Claude Code 使用你的 Claude.ai 訂閱。
認證：Claude Code 每次請求模型時，用哪一種憑據證明“我是誰、賬單走哪裡”。

大多數個人使用者只有第一種：

claude
浏览器登录 Claude.ai
回到终端开始用

團隊和企業使用者可能同時有多種：

Claude.ai 订阅 OAuth
Claude Console API key（API 密钥）
Amazon Bedrock credentials（凭据）
Google Vertex AI credentials（凭据）
Microsoft Foundry credentials（凭据）
LLM gateway bearer token（网关令牌）
apiKeyHelper 动态脚本

第一性原理：認證不是“能不能開啟 Claude Code”，而是“這次請求使用哪套身份、許可權、賬單和組織策略”。

2. 第一次登入怎麼走

瀏覽器登入 Claude.ai

用 Claude.ai 賬號登入後，瀏覽器通常會自動跳回終端，終端繼續進入 Claude Code 會話。

如果瀏覽器沒有自動開啟，按 c 複製登入 URL，再貼上到瀏覽器裡登入。

如果瀏覽器顯示 login code（登入碼），而不是自動跳回終端，把 code 貼上回終端的提示位置。

這常見於幾種場景：

WSL2：瀏覽器和 Linux 環境之間 callback（回撥）不通。
SSH：遠端終端沒有本地瀏覽器回撥。
容器：容器裡的本地 callback server（回撥服務）瀏覽器訪問不到。
遠端開發機：瀏覽器在本機，Claude Code 在遠端。

驗證或重新登入

確認當前認證狀態：

/status

退出並重新登入：

/logout

新手判斷法：瀏覽器沒跳回終端不一定是登入失敗。只要頁面給了 code（登入碼），就複製回終端繼續。

3. 哪類賬號可以用 Claude Code

官方 Authentication 文件列了幾類入口。

賬號 / 接入方式	適合誰	怎麼認證
Claude Pro / Max	個人開發者	Claude.ai 瀏覽器登入
Claude for Teams	小團隊	管理員邀請後用 Claude.ai 登入
Claude for Enterprise	大組織 / 合規要求	SSO、域名捕獲、RBAC、managed settings
Claude Console	API 計費和開發平臺使用者	Console 憑據和角色
Amazon Bedrock	AWS 企業環境	AWS 憑據 + 環境變數
Google Vertex AI	GCP 企業環境	GCP ADC + 環境變數
Microsoft Foundry	Azure 企業環境	API key 或 Entra ID + 環境變數

注意一個硬邊界：Claude.ai 免費計劃不包含 Claude Code 訪問許可權。

如果你是個人使用者，優先用 Pro / Max 訂閱登入。不要一開始就去折騰 API Key，除非你明確要按 API 計費或接閘道器。

選擇認證入口時按這張表判斷：

你的情況	優先選什麼
個人學習或個人開發	Claude.ai OAuth，使用 Pro / Max
團隊統一訂閱和成員管理	Claude for Teams / Enterprise
按 API 計費或由開發平臺分配 key	Claude Console
公司要求走 AWS / GCP / Azure	Bedrock / Vertex AI / Foundry

4. Team、Enterprise 和 Console 的區別

這三類看起來都像“團隊用”，但管理方式不同：

Claude for Teams：訂閱式團隊管理，適合小團隊協作和統一賬單。
Claude for Enterprise：企業級管理，適合 SSO、域名、合規、組織策略。
Claude Console：API 平臺管理，適合按 API / 開發平臺方式分配訪問。

Console 場景裡，管理員需要先邀請使用者，並分配角色：

Claude Code role：只能建立 Claude Code API keys。
Developer role：可以建立更多型別的 API key。

不要混用概念：Claude.ai 訂閱登入和 Claude Console API key（API 金鑰）是兩條賬單和許可權路徑。你有訂閱，不代表環境裡的 API key 就該保留。

5. 雲供應商接入：不是瀏覽器登入

如果組織走 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry，認證就不靠 /login。

雲供應商接入的共同點：

先按供應商開通 Claude 模型訪問。
本機或 CI 環境先完成雲 CLI / 預設憑據配置。
再設定 Claude Code 環境變數啟用對應 provider（供應商）。
使用 provider 時，/login 和 /logout 通常會停用，因為認證由雲憑據處理。

Bedrock 最小配置：

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1

Vertex AI 最小配置：

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

Microsoft Foundry 最小配置：

export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource

Foundry 還可以用 API key：

export ANTHROPIC_FOUNDRY_API_KEY=your-azure-api-key

如果沒設定 ANTHROPIC_FOUNDRY_API_KEY，Claude Code 會走 Azure SDK default credential chain（預設憑據鏈），常見本地方式是先：

az login

雲接入不是新手預設路徑：除非公司明確要求走 AWS / GCP / Azure，否則個人學習不要從雲供應商認證開始。先用 Claude.ai 訂閱登入，把基礎工作流跑通。

6. 憑據存在哪裡

Claude Code 會安全管理認證憑據：

macOS：加密的 macOS Keychain。
Linux：~/.claude/.credentials.json，許可權 0600。
Windows：~/.claude/.credentials.json，繼承使用者 profile ACL。
自定義配置目錄：$CLAUDE_CONFIG_DIR 下對應位置。

還有一個容易混淆的檔案：~/.claude.json。官方 settings 文件說明，它會儲存 OAuth session、MCP 配置、專案狀態、allowed tools、trust settings 和各種快取。

安全邊界：不要把 .credentials.json、~/.claude.json、API key、OAuth token 提交進儲存庫。團隊共享配置要寫 project settings，不要共享個人憑據。

7. 多個憑據同時存在時，誰優先

這是認證章最重要的一節。

當多個憑據同時存在，Claude Code 按官方順序選擇：

雲供應商憑據：CLAUDE_CODE_USE_BEDROCK / VERTEX / FOUNDRY。
ANTHROPIC_AUTH_TOKEN：LLM gateway / proxy 的 bearer token。
ANTHROPIC_API_KEY：Claude Console API key（API 金鑰）。
apiKeyHelper：從 vault（金鑰庫）動態取短期 key。
CLAUDE_CODE_OAUTH_TOKEN：claude setup-token 生成的長期 token。
/login 訂閱 OAuth：Pro / Max / Team / Enterprise 預設登入。

這解釋了一個常見坑：

你明明有 Claude Max 訂閱，但 shell 裡還殘留了一個失效的 API key。

export ANTHROPIC_API_KEY=old-disabled-key

一旦你批准使用這個 API key，它會優先於訂閱 OAuth；這個批准會被 Claude Code 記住，下次啟動仍然走 API key。要改回訂閱，在 /config 裡關掉 "Use custom API key" toggle，或先 unset 環境變數再啟動。在 -p 非互動模式裡，只要環境變數存在就會直接使用，不會問你。結果就是：你以為走訂閱，實際上走了一個壞掉的 Console key。

回到訂閱登入：

unset ANTHROPIC_API_KEY
unset ANTHROPIC_AUTH_TOKEN

再看：

/status

排障口訣：認證不對，先看 /status；訂閱使用者異常，先查 shell 裡有沒有 ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN。

8. `apiKeyHelper` 適合什麼

apiKeyHelper 是 settings（設定檔案）裡的一個配置：Claude Code 呼叫指令碼，指令碼返回 API key。

它適合：

公司用 vault（金鑰庫）管短期憑據。
API key 會定期輪換。
不希望把 key 放進環境變數。

它不適合：

新手個人登入。
把複雜 shell 指令碼當萬能認證入口。
每次呼叫都很慢的指令碼。

官方說明裡，apiKeyHelper 預設在 5 分鐘後或 HTTP 401 時重新呼叫；需要自定義重新整理間隔時，可以設定 CLAUDE_CODE_API_KEY_HELPER_TTL_MS。指令碼超過 10 秒才返回時，Claude Code 會在提示欄顯示 slow helper notice（慢 helper 提醒）。

不要把慢指令碼塞進認證鏈：認證發生在請求路徑上。helper 慢，會讓每次模型請求都變慢或不穩定。

9. 長期 token：CI 和無瀏覽器環境

CI、指令碼或無瀏覽器環境，可以生成一年期 OAuth token：

claude setup-token

命令會引導你完成 OAuth 授權，並把 token 列印到終端。它不會自動儲存。你需要自己設定：

export CLAUDE_CODE_OAUTH_TOKEN=your-token

注意邊界：

需要 Pro、Max、Team 或 Enterprise 計劃。
作用域限於 inference（模型推理）。
不能建立 Remote Control session。
bare mode（裸模式）不讀取 CLAUDE_CODE_OAUTH_TOKEN。
如果指令碼使用 --bare，應改用 ANTHROPIC_API_KEY 或 apiKeyHelper。

長期 token 不是普通配置：它雖然方便，但仍然是憑據。放 CI secret，不要寫進儲存庫、日誌或示例文件。

10. Desktop、Web、Remote 和 CLI 不完全一樣

認證還有一個容易誤解的點：環境變數主要影響終端 CLI session。

官方認證文件明確說：

apiKeyHelper
ANTHROPIC_API_KEY
ANTHROPIC_AUTH_TOKEN

這些只作用於 terminal CLI sessions（終端 CLI 會話）。

Claude Desktop 和 remote sessions 使用 OAuth，不呼叫 apiKeyHelper，也不讀取 API key 環境變數。

這意味著：

終端 claude：受環境變數和 CLI 憑據優先順序影響。
Claude Code on the Web（網頁版）：始終使用訂閱憑據；即使 sandbox 環境裡有 ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN，也不會覆蓋訂閱。
Desktop / remote session：使用 OAuth。
雲供應商模式：走對應雲 provider 憑據。

不要拿 CLI 的環境變數解釋所有入口：Web、Desktop、remote 和 CLI 的認證路徑不同。排障時先確認你正在用哪個入口。

11. 常見登入問題

瀏覽器不自動開啟：按 c 複製 URL。
瀏覽器給 login code：把 code 貼上回終端。
OAuth error / invalid code：重新 /logout，再登入。
403 Forbidden：檢查賬號是否有 Claude Code 許可權、地區是否支援。
有訂閱但提示 API key 問題：檢查 ANTHROPIC_API_KEY 是否殘留。
Bedrock 找不到 credentials：確認當前 shell 的 AWS 憑據是否有效。
Vertex 找不到預設憑據：確認 ADC、專案 ID、CLOUD_ML_REGION 是否設定。
Foundry token chain 失敗：先 az login 或設定 ANTHROPIC_FOUNDRY_API_KEY。

排障順序也可以壓成四步：

順序	先看什麼	常見處理
1	`/status`	確認當前到底走 OAuth、API key 還是雲供應商
2	環境變數	有殘留 `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` 就先 unset
3	訂閱 OAuth	失效就 `/logout` 後重新登入
4	雲供應商憑據	Bedrock / Vertex / Foundry 分別檢查 AWS、GCP、Azure 憑據

12. 本章自檢

試著用自己的話回答：

登入和認證有什麼區別？對應 §1。
為什麼 WSL、SSH、容器裡經常要手動複製 login code？對應 §2。
Claude for Teams、Enterprise、Console 的區別是什麼？對應 §4。
為什麼有訂閱時，殘留的 ANTHROPIC_API_KEY 仍然可能導致認證失敗？對應 §7。
CLAUDE_CODE_OAUTH_TOKEN 適合什麼場景，為什麼不能寫進儲存庫？對應 §9。

過關標準：你能開啟 /status，判斷當前 Claude Code 正在使用哪種認證方式，並知道要回到訂閱 OAuth 時該 unset 哪些環境變數。

本篇術語速查表

OAuth：授權登入，Claude.ai 訂閱登入時使用的授權機制。
Claude.ai subscription：Claude 訂閱，Pro、Max、Team、Enterprise 等訂閱入口。
Claude Console：Claude 開發平臺，API key、成員、角色和開發平臺賬單管理入口。
ANTHROPIC_API_KEY：Anthropic API Key，Console API key，作為 X-Api-Key header 傳送。
ANTHROPIC_AUTH_TOKEN：Bearer token，常用於 LLM gateway / proxy 的 Authorization header。
apiKeyHelper：動態取 key 指令碼，從 vault 或指令碼動態返回 API key 的設定。
CLAUDE_CODE_OAUTH_TOKEN：長期 OAuth token，claude setup-token 生成的一年期 token。
Bedrock：Amazon Bedrock，AWS 上的 Claude 模型接入方式。
Vertex AI：Google Vertex AI，GCP 上的 Claude 模型接入方式。
Microsoft Foundry：Microsoft Foundry，Azure / Foundry 上的 Claude 模型接入方式。
ADC：Application Default Credentials，Google Cloud 預設憑據鏈。
Entra ID：Microsoft Entra ID，Azure 的身份認證體系。

登入與認證

1. 先分清“登入”和“認證”

2. 第一次登入怎麼走

啟動 Claude Code

瀏覽器登入 Claude.ai

驗證或重新登入

3. 哪類賬號可以用 Claude Code

4. Team、Enterprise 和 Console 的區別

5. 雲供應商接入：不是瀏覽器登入

6. 憑據存在哪裡

7. 多個憑據同時存在時，誰優先

8. `apiKeyHelper` 適合什麼

9. 長期 token：CI 和無瀏覽器環境

10. Desktop、Web、Remote 和 CLI 不完全一樣

11. 常見登入問題

12. 本章自檢

官方來源

接下來去哪

選擇平臺與整合

安裝和更新 Claude Code（上一篇）

配置 Claude Code

本頁目錄