---
title: "CLI 認證"
description: "基於 Cursor 官方 Authentication 文件解釋瀏覽器登入、API key、狀態檢查、登出、CI secrets 和認證排障。"
verifiedAt: "2026-05-09"
---

Cursor CLI 支援兩類認證：瀏覽器登入和 API key。個人終端優先用瀏覽器登入；指令碼、CI/CD 和自動化環境使用 API key。

> [!NOTE]
> **閱讀目標**：讀完本章，你應該能判斷當前場景該用 `agent login` 還是 `CURSOR_API_KEY`，並能處理未登入、SSL 和 endpoint 類問題。

## 1. 認證方式怎麼選

| 場景 | 推薦方式 | 原因 |
| --- | --- | --- |
| 個人本機終端 | Browser authentication | 操作最簡單，憑據本地安全儲存 |
| 新人 onboarding | Browser authentication | 容易確認賬號和授權狀態 |
| CI / GitHub Actions | API key | 無瀏覽器互動，適合 secrets 注入 |
| 自動化指令碼 | API key | 可透過環境變數控制生命週期 |
| 臨時排障 | `agent status` | 先確認身份，不要盲目重登 |

不要把 API key 當成本地登入的預設替代。能用瀏覽器登入的本機場景，用 `agent login` 更清晰。

## 2. 瀏覽器登入

官方推薦的瀏覽器登入流程：

```bash
agent login
agent status
agent logout
```

`agent login` 會開啟預設瀏覽器並要求你用 Cursor 賬號認證。完成後，憑據會安全儲存在本地。

登入後先跑：

```bash
agent status
```

它會顯示：

- 是否已經認證。
- 當前賬號資訊。
- 當前 endpoint 配置。

登出用：

```bash
agent logout
```

這會清除本地儲存的認證資訊。共享機器、錄屏環境和排障結束後都應該顯式登出。

## 3. API key 認證

API key 用在 automation、scripts、CI/CD。先從 Cursor Dashboard 的 Integrations 下生成 user API key。

推薦用環境變數：

```bash
export CURSOR_API_KEY=your_api_key_here
agent "implement user authentication"
```

也可以用命令列 flag：

```bash
agent --api-key your_api_key_here "implement user authentication"
```

商業級實踐裡，環境變數優於命令列 flag。命令列引數更容易進入 shell history、process list、CI log 或排障截圖。

## 4. CI secrets 邊界

GitHub Actions 中用 repository 或 organization secrets 注入：

```yaml
env:
  CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
```

上線前檢查：

- key 不寫進儲存庫。
- key 不寫進 prompt。
- key 不列印到日誌。
- 只給需要的 repo 或 org scope。
- 離職、洩露、runner 異常後能輪換。

API key 是自動化身份，不是“團隊萬能鑰匙”。不同專案和環境最好使用不同 secret，方便審計和吊銷。

## 5. 認證排障

`Not authenticated`

- 本機執行 `agent login`。
- CI 檢查 `CURSOR_API_KEY` 是否存在。
- 確認 secret 名稱和 workflow env 名稱一致。

SSL certificate errors

- 開發或受管網路中可按官方說明使用 `--insecure`。
- 企業環境優先配置可信 CA，不要長期依賴 insecure。

Endpoint issues

- 使用 `--endpoint` 指定自定義 API endpoint。
- 用 `agent status` 檢查當前 endpoint。

賬號不對

- 先 `agent status` 看當前賬號。
- 再 `agent logout`，重新 `agent login`。

<details>
<summary>深讀：為什麼 CI 不應該複用個人登入態</summary>

CI 是共享、可複製、可審計的執行環境。個人登入態通常繫結本機互動和本地憑據，不適合遷移到 runner。

CI 應該使用可輪換、可最小授權、可審計的 API key，並透過 secrets 系統注入。這樣出現問題時可以直接吊銷和更換，而不是排查某個人機器上的登入狀態。
</details>

## 本章自檢

完成本章後，用這 3 個問題檢查自己是否真正理解：

1. 為什麼個人本機優先用 `agent login`？
2. 為什麼 CI 中推薦 `CURSOR_API_KEY` 環境變數，而不是 `--api-key` 明文引數？
3. `agent status` 能幫助確認哪些認證事實？

透過標準：你能為本機、GitHub Actions 和自託管 runner 分別寫出認證方案，並說明 key 儲存、日誌和輪換邊界。

## 官方來源

- [Cursor CLI Authentication](https://cursor.com/docs/cli/reference/authentication.md) —— 官方瀏覽器登入、API key、狀態檢查和排障說明。
- [Cursor GitHub Actions](https://cursor.com/docs/cli/github-actions.md) —— 官方 CI 中 `CURSOR_API_KEY` 使用方式。
- [Cursor CLI Parameters](https://cursor.com/docs/cli/reference/parameters.md) —— 官方 `--api-key` 引數說明。

## 接下來去哪

<Cards>
  <Card title="CLI 許可權" description="繼續學習 Shell、Read、Write、WebFetch 和 MCP permissions。" href="/zh-Hant/docs/cursor/official/03-cli-automation/40-permissions" />
  <Card title="GitHub Actions" description="回到 CI secrets 和 restricted autonomy workflow。" href="/zh-Hant/docs/cursor/official/03-cli-automation/36-github-actions" />
</Cards>
