> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 登录与认证

<div id="overview">
  # 概述
</div>

在使用 Qoder 之前需要完成身份验证。首次执行命令时，Qoder CLI 会自动提示你登录。

Qoder CLI 使用 Qoder 自有的认证体系，主要提供两种认证方式：

* **交互式登录（推荐）**：在终端里通过浏览器或粘贴令牌完成登录，适合日常本地使用。
* **环境变量**：通过 Personal Access Token 认证，适合 CI/CD 流水线和无浏览器的自动化环境。

<div id="interactive-login">
  # 交互式登录
</div>

在终端中启动 Qoder CLI，然后在交互式提示符中输入 `/login`：

```shell theme={null}
# 在终端中启动 Qoder CLI
qodercli

# 在交互式提示符中，输入 /login
/login
```

随后选择需要的登录方式：

* **Login with Qoder Platform (Browser)**：打开浏览器窗口，使用你的 Qoder 账号完成身份验证。
* **Use Qoder Personal Access Token (QODER\_PERSONAL\_ACCESS\_TOKEN)**：用你在 Qoder 设置中生成的 token 设置 `QODER_PERSONAL_ACCESS_TOKEN` 环境变量。

做出选择后，Qoder CLI 会引导你完成剩余步骤。

> `/login` 也可以使用别名 `/signin`。

## 无法自动打开浏览器时

如果运行环境不支持自动打开浏览器（例如远程服务器、容器），设置环境变量 `NO_BROWSER=true` 后，Qoder CLI 会打印登录 URL，供你手动复制到浏览器访问：

```shell theme={null}
export NO_BROWSER=true
qodercli
```

## 令牌自动刷新

完成浏览器登录后，Qoder CLI 会在后台自动刷新令牌，日常使用无需手动重新登录。

<div id="pat">
  # 使用 Personal Access Token
</div>

对于非交互式会话或自动化环境（例如 CI/CD 流水线），你可以使用 Personal Access Token（PAT）进行认证。

## 获取 Token

在以下页面创建和管理 Personal Access Token：

> [https://qoder.com/account/integrations](https://qoder.com/account/integrations)

## 通过环境变量认证

把令牌设置到 `QODER_PERSONAL_ACCESS_TOKEN` 环境变量中：

```shell theme={null}
# Linux / macOS 示例
export QODER_PERSONAL_ACCESS_TOKEN="your_personal_access_token_here"
```

```shell theme={null}
# Windows 示例（命令提示符），注意不要加引号，CMD 会把引号存进变量值
set QODER_PERSONAL_ACCESS_TOKEN=your_personal_access_token_here
```

```shell theme={null}
# Windows 示例（PowerShell）
$env:QODER_PERSONAL_ACCESS_TOKEN="your_personal_access_token_here"
```

设置后，Qoder CLI 会自动使用 PAT 完成认证。

> 如果同时通过 `/login` 命令和该环境变量设置了有效令牌，则以 `/login` 提供的令牌为准。

<div id="env-vars">
  # 认证相关环境变量
</div>

| 环境变量                          | 说明                                   |
| :---------------------------- | :----------------------------------- |
| `QODER_PERSONAL_ACCESS_TOKEN` | Personal Access Token，设置后自动使用 PAT 认证 |
| `QODER_CONFIG_DIR`            | 自定义配置目录，默认 `~/.qoder`                |
| `NO_BROWSER`                  | 设置后禁止自动打开浏览器，改为打印登录 URL              |

<div id="check-status">
  # 查看认证状态
</div>

在交互式会话中输入 `/status`，可以打开状态面板，包含 Usage 和 Status 两个标签页：Usage 展示当前会话的 API 配额与 token 用量（套餐类型、额度使用、会话时长、代码改动量等），Status 展示当前 CLI 的状态信息。当你怀疑认证出现问题时，这是最直接的排查入口。

<div id="logout">
  # 退出登录
</div>

需要登出 Qoder 时，在交互式提示符中输入 `/logout`：

```shell theme={null}
# 在交互式提示符中，输入 /logout
/logout
```

> `/logout` 也可以使用别名 `/signout`，退出时会要求确认。

如果你是通过 `QODER_PERSONAL_ACCESS_TOKEN` 环境变量完成认证的，在运行 `/logout` 之前必须先清除该环境变量，否则下次启动会再次使用该令牌自动登录。

<div id="troubleshooting">
  # 常见问题
</div>

* **浏览器没有自动打开**：设置 `NO_BROWSER=true` 后手动访问打印出的 URL。
* **登录回调失败或长时间无响应**：确认本地网络能访问 Qoder 服务，必要时检查代理设置，见 网络与代理。
* **PAT 无效或过期**：前往账号集成页面重新生成令牌，并更新 `QODER_PERSONAL_ACCESS_TOKEN`。

更多排查步骤见 登录与认证问题。