跳转到主要内容
Agent 本身从不登录，而是复用所在机器上的 difyctl 会话，并以登录者的身份行事：可以是账户用户，也可以是仅限其获准应用的外部 SSO 用户。如何把会话放到那台机器上，取决于机器的类型：
  • 你自己的机器：登录（账户 或 SSO）即可。
  • 可登录的服务器或虚拟机：直接在上面登录（方式一）。
  • 容器、CI runner 或预构建镜像：把会话复制进去（方式二）。

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

以 Agent 要扮演的身份，在目标机器上登录。Agent 会继承该身份能访问的一切：账户用户可访问其工作空间中的应用，外部 SSO 用户则可访问其获准运行的应用。 --host 使用 控制台 API URL。 机器没有浏览器时，加上 --no-browser： 
difyctl auth login --host https://dify.example.com --no-browser
difyctl 会打印一个一次性验证码和一个验证 URL。在任意设备上打开该 URL，登录后输入验证码。批准的瞬间，会话就会写入这台机器。 确认会话已就绪： 
difyctl auth whoami

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

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

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

在没有操作系统钥匙串的机器上登录

使用无界面的 Linux 服务器或容器。在没有钥匙串时，difyctl 会把 token 保存到配置目录下的 tokens.yml，使整个目录可移植。复制之前，先确认配置目录（默认为 ~/.config/difyctl）中存在 tokens.yml。如果文件缺失，说明 token 已被钥匙串捕获，且无法导出；请在目标机器上直接通过 方式一：在目标机器上登录 登录。
2

将配置目录复制到目标机器

复制后，用 DIFY_CONFIG_DIR 让 difyctl 指向该目录。对于容器，应在运行时挂载该目录，而不是把它打包进镜像：
docker run \
  -v /path/to/difyctl-config:/config:ro \
  -e DIFY_CONFIG_DIR=/config \
  your-agent-image
tokens.yml 是有效的凭据。保持其 0600 权限，且不要将它放入镜像或纳入版本控制。挂载设为只读，是因为只负责运行应用的 Agent 从不写入配置目录。

​
会话过期时

服务端过期或被吊销的会话，会以退出码 4 报告，error.code 为 auth_expired。Agent 无法自行恢复：新会话需要有人批准登录，也就是与方式一相同的一次性验证码步骤。 因此它应当停止并报告失败，交由人工重新登录，而不是重试。如何据此分支处理，参见 处理错误与重试。 要吊销你怀疑已泄露的会话，在任意已登录的机器上运行 auth devices revoke。