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

# 在 Agent 运行的位置进行认证

> 在 Agent 运行的服务器或容器上放置一个 difyctl 会话，使其无需人工值守即可调用 Dify 应用

Agent 本身从不登录，而是复用所在机器上的 `difyctl` 会话，并以登录者的身份行事：可以是账户用户，也可以是仅限其获准应用的外部 SSO 用户。如何把会话放到那台机器上，取决于机器的类型：

* **你自己的机器**：登录（[账户](/zh/3.11.x/develop/cli/account-users/authenticate) 或 [SSO](/zh/3.11.x/develop/cli/sso-users/authenticate)）即可。
* **可登录的服务器或虚拟机**：直接在上面登录（方式一）。
* **容器、CI runner 或预构建镜像**：把会话复制进去（方式二）。

## 方式一：在目标机器上登录

以 Agent 要扮演的身份，在目标机器上登录。Agent 会继承该身份能访问的一切：账户用户可访问其工作空间中的应用，外部 SSO 用户则可访问其获准运行的应用。

`--host` 使用 [控制台 API URL](/zh/3.11.x/deploy/advanced-configuration/environment-variables#console_api_url)。

机器没有浏览器时，加上 `--no-browser`：

```bash theme={null}
difyctl auth login --host https://dify.example.com --no-browser
```

`difyctl` 会打印一个一次性验证码和一个验证 URL。在任意设备上打开该 URL，登录后输入验证码。批准的瞬间，会话就会写入这台机器。

确认会话已就绪：

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

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

外部 SSO 用户看到的则是 `<your-email> (external SSO, issuer: <your-identity-provider>)`。

## 方式二：复制已有的会话

当你无法在目标机器上直接登录时使用此方式，例如预构建镜像或临时容器。

<Steps>
  <Step title="在没有操作系统钥匙串的机器上登录">
    使用无界面的 Linux 服务器或容器。在没有钥匙串时，`difyctl` 会把 token 保存到配置目录下的 `tokens.yml`，使整个目录可移植。

    复制之前，先确认配置目录（默认为 `~/.config/difyctl`）中存在 `tokens.yml`。如果文件缺失，说明 token 已被钥匙串捕获，且无法导出；请在目标机器上直接通过 [方式一：在目标机器上登录](#方式一：在目标机器上登录) 登录。
  </Step>

  <Step title="将配置目录复制到目标机器">
    复制后，用 [`DIFY_CONFIG_DIR`](/zh/3.11.x/develop/cli/reference/environment-variables) 让 `difyctl` 指向该目录。对于容器，应在运行时挂载该目录，而不是把它打包进镜像：

    ```bash theme={null}
    docker run \
      -v /path/to/difyctl-config:/config:ro \
      -e DIFY_CONFIG_DIR=/config \
      your-agent-image
    ```

    `tokens.yml` 是有效的凭据。保持其 `0600` 权限，且不要将它放入镜像或纳入版本控制。挂载设为只读，是因为只负责运行应用的 Agent 从不写入配置目录。
  </Step>
</Steps>

## 会话过期时

服务端过期或被吊销的会话，会以退出码 4 报告，`error.code` 为 `auth_expired`。Agent 无法自行恢复：新会话需要有人批准登录，也就是与方式一相同的一次性验证码步骤。

因此它应当停止并报告失败，交由人工重新登录，而不是重试。如何据此分支处理，参见 [处理错误与重试](/zh/3.11.x/develop/cli/integrate-agents/error-handling-and-retries-for-agents#根据退出码分支处理)。

要吊销你怀疑已泄露的会话，在任意已登录的机器上运行 [`auth devices revoke`](/zh/3.11.x/develop/cli/reference/auth-and-contexts#撤销会话)。