---
title: "登入與認證"
description: "Claude Code 登入不是隻有訂閱賬號。個人用 Claude.ai，團隊可用 Teams、Enterprise、Console、Bedrock、Vertex AI 或 Microsoft Foundry。"
canonical: "https://xiangyugongzuoliu.com/tag/claude-code"
verifiedAt: "2026-05-08"
---

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

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

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

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

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

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

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

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

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

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

## 2. 第一次登入怎麼走

<Steps>

<Step>

### 啟動 Claude Code

在專案目錄裡跑：

```bash
claude
```

第一次啟動會自動開啟瀏覽器。

</Step>

<Step>

### 瀏覽器登入 Claude.ai

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

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

</Step>

<Step>

### 遠端或隔離環境：手動複製 login code

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

這常見於幾種場景：

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

</Step>

<Step>

### 驗證或重新登入

確認當前認證狀態：

```text
/status
```

退出並重新登入：

```text
/logout
```

</Step>

</Steps>

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

## 3. 哪類賬號可以用 Claude Code

官方 [Authentication](https://code.claude.com/docs/en/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。

> [!WARNING]
> **不要混用概念**：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 最小配置：

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

Vertex AI 最小配置：

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

Microsoft Foundry 最小配置：

```bash
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource
```

Foundry 還可以用 API key：

```bash
export ANTHROPIC_FOUNDRY_API_KEY=your-azure-api-key
```

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

```bash
az login
```

> [!CAUTION]
> **雲接入不是新手預設路徑**：除非公司明確要求走 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 和各種快取。

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

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

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

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

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

這解釋了一個常見坑：

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

```bash
export ANTHROPIC_API_KEY=old-disabled-key
```

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

回到訂閱登入：

```bash
unset ANTHROPIC_API_KEY
unset ANTHROPIC_AUTH_TOKEN
```

再看：

```text
/status
```

> [!TIP]
> **排障口訣**：認證不對，先看 `/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 提醒）。

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

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

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

```bash
claude setup-token
```

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

```bash
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`。

> [!CAUTION]
> **長期 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 憑據。

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

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

<details id="glossary">
<summary><b>本篇術語速查表</b></summary>

- **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 的身份認證體系。

</details>

## 官方來源

- [Authentication](https://code.claude.com/docs/en/authentication)
- [Troubleshoot installation and login](https://code.claude.com/docs/en/troubleshoot-install)
- [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock)
- [Google Vertex AI](https://code.claude.com/docs/en/google-vertex-ai)
- [Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry)

## 接下來去哪

<Cards>
  <Card href="/zh-Hant/docs/claude-code/official/00-getting-started/platforms" title="選擇平臺與整合" description="登入完成後，下一步判斷 CLI、Desktop、IDE、Web、Mobile 和團隊整合應該怎麼選。" />
  <Card href="/zh-Hant/docs/claude-code/official/00-getting-started/install" title="安裝和更新 Claude Code（上一篇）" description="認證問題很多時候其實是安裝路徑、PATH 或混裝問題。先確認安裝入口清晰。" />
  <Card href="/zh-Hant/docs/claude-code/official/01-core-capabilities/settings" title="配置 Claude Code" description="團隊認證常常要配 settings、managed settings 和環境變數。核心配置篇會繼續展開。" />
</Cards>

如果只記一個判斷：**認證排障先看當前生效憑據，不要只看自己“以為登入的是哪個賬號”；`/status` 比猜更可靠。**
