> ## Documentation Index
> Fetch the complete documentation index at: https://dify-6c0370d8-release-1-15-0.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 认证

> 从 CLI 登录你的 Dify 主机，了解 token 的存储位置，并管理你的会话

> 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/cli/authenticate)。

登录通过浏览器完成，使用 OAuth 2.0 设备流程，`difyctl` 全程接触不到你的密码。

## 登录

<Steps>
  <Step title="运行登录命令">
    传入 Dify 主机的 URL。使用 Dify Cloud 时，填写 `https://cloud.dify.ai`；自部署时，使用 [控制台 API URL](/zh/self-host/deploy/configuration/environments#console_api_url)。

    ```bash theme={null}
    difyctl auth login --host https://cloud.dify.ai
    ```

    `difyctl` 会打印一次性验证码，在默认浏览器中打开验证 URL，然后等待：

    ```text theme={null}
    ! Copy this one-time code: WDJP-XKLM
      Open: https://cloud.dify.ai/device
    ```

    <Tip>
      若不想自动打开浏览器，可传入 `--no-browser`。
    </Tip>

    如果没有浏览器打开（通过 SSH 或在无图形界面的会话中属正常现象），可自行在任意设备上打开该 URL。
  </Step>

  <Step title="在浏览器中确认登录">
    在打开的浏览器标签页中，用 Dify 凭据登录并输入一次性验证码。

    验证码 15 分钟后过期。若已过期，重新运行 `difyctl auth login` 获取一个新的。
  </Step>

  <Step title="确认会话">
    回到终端：

    ```text theme={null}
    ✓ Logged in to cloud.dify.ai as <your-email> (<your-name>)
      Workspace: <your-workspace>
    ```

    第二行是你的工作空间。
  </Step>
</Steps>

## 重新登录

如果某条命令以 `auth_expired`（退出码 4）失败，说明服务器已使你的会话过期或将其吊销。

重新运行 `difyctl auth login`。无需先登出，新的登录会刷新已存储的 token。

## 查看当前登录身份

```bash theme={null}
difyctl auth whoami
```

```text theme={null}
<your-email> (<your-name>)
```

要在脚本中读取身份信息，加上 `--json`：

```bash theme={null}
difyctl auth whoami --json
```

你会得到相同的字段（以 JSON 对象形式返回），外加你的账户 ID：

```json theme={null}
{"id":"3c90c3cc-0d44-4b50-8888-8dd25736052a","email":"<your-email>","name":"<your-name>"}
```

## 登出

```bash theme={null}
difyctl auth logout
```

```text theme={null}
✓ Logged out of cloud.dify.ai
```

这会吊销服务器上的会话，并从你的机器上删除 token 和会话记录。即便服务器端的吊销失败，本地凭据仍会被清除。

## Token 的存储位置

登录后会存储一个 OAuth bearer token，可通过 `dfoa_` 前缀识别。它代表你本人：你的账户在工作空间中能做什么，这个 token 在 CLI 中就能做什么。

只要操作系统提供凭据存储，`difyctl` 就会把 token 存入其中：macOS 上是 Keychain，Windows 上是 Credential Manager，Linux 上是 Secret Service。如果没有可用的凭据存储，则回退到 `difyctl` 配置目录下一个权限为 `0600` 的 `tokens.yml` 文件。

`difyctl` 在你登录时选定存储位置，此后整个会话都使用它。会话元数据（主机、账户、工作空间）与 token 一同保存在 `hosts.yml` 中。

配置目录在 macOS 和 Linux 上是 `~/.config/difyctl`（Linux 遵循 `XDG_CONFIG_HOME`），在 Windows 上是 `%APPDATA%\difyctl`。设置 [`DIFY_CONFIG_DIR`](/zh/cli/reference/environment-variables) 可覆盖此路径。

## 故障排查

| 问题                        | 处理方法                                                                                 |
| :------------------------ | :----------------------------------------------------------------------------------- |
| 浏览器始终未打开                  | 从终端复制 URL，在任意设备上打开。                                                                  |
| 主机被拒绝                     | 只接受 `https://` 主机；不带协议的主机默认按 `https://` 处理。对于纯 `http://` 主机（仅限本地开发），加上 `--insecure`。 |
| 后续某条命令以 `auth_expired` 失败 | 你的会话已过期或被吊销。[重新登录](#重新登录)。                                                           |

其余问题详见完整的 [故障排查](/zh/cli/troubleshooting) 页面。