鉴权与登录

auth 命令组用于控制台登录与 SSO 鉴权：通过浏览器登录并存储短时 STS 凭据或仅保存用户 OIDC 会话、清除会话、查看当前身份、管理登录配置，以及为组织准备 CLI SSO 登录资源。login、logout、whoami 同时提供为顶层命令（如 agentkit login）。选择登录方式时，先确定后续任务：

任务	登录方式
构建、部署和管理资源	控制台登录、能换取 STS 的组织 SSO，或所选平台的 AK/SK
使用组织共享 Harness 聊天	组织 SSO 的 `--identity-only`，并使用管理员发布的别名
只保存登录地址供以后使用	`auth profile set`；保存配置本身不会完成登录

完成浏览器授权后，用 agentkit whoami 确认当前身份。账号身份正确仍需具备目标资源对应的权限通过浏览器完成当前云厂商的控制台登录，或使用指定 SSO 地址登录。SSO 模式使用 OIDC 登录结果换取短时 STS 凭据；--identity-only 只保存用户 OIDC 会话，可供 harness invoke 在匹配的 custom_jwt Runtime 上自动转发用户 id_token，但不创建 AgentKit 管理凭据。通用 invoke run 调用 custom_jwt Runtime 时仍需通过 --headers 显式传入 Authorization。

标志/参数	说明	默认值
`[address]`	登录地址	无
`-p, --profile <name>`	使用预置的命名配置，替代直接传入地址	无
`--duration <seconds>`	请求的 STS 凭据有效期（秒）	`3600`
`--identity-only`	只保存用户 OIDC 会话，不执行 STS 角色交换。	`false`
`--no-open`	仅打印登录 URL，不打开浏览器；远程控制台登录使用 `--remote`	`false`
`--console`	强制使用当前云厂商的控制台登录，即使已有 SSO profile	`false`
`--remote`	在另一设备完成控制台授权，将授权码粘贴回当前终端	`false`

agentkit auth login
agentkit auth login --identity-only <sso-address>

登录地址与发现文档

传入 [address] 时，CLI 会从该地址读取 /.well-known/agentkit-cli 登录发现文档。地址可以省略 https://；正式远程地址必须使用 HTTPS，只有本地测试地址可以使用 http://localhost、http://127.0.0.1 或 http://[::1]。地址不能包含用户名、密码、查询参数或 fragment。使用共享登录域名时，可以在域名后追加一个租户路径，例如 https://login.example.com/team-a；该路径必须是单段小写 slug，不能包含多级路径、路径遍历或编码后的路径分隔符。远程发现文档必须直接返回 JSON 对象，不能依赖重定向，响应体大小不能超过 64 KiB。自定义租户地址的发现文档只能使用以下字段：

字段	说明	默认值
`issuer`	UserPool issuer，必须是官方 UserPool 的 HTTPS origin。	必填
`client_id`	公开 OAuth client id。	必填
`role_trn`	STS role TRN；普通登录必填，身份仅登录可省略。	—
`provider_trn`	IAM OIDC provider TRN；与 `role_trn` 同时提供或同时省略。	—
`cloud_provider`	云厂商：`volcengine` 或 `byteplus`，必须与 `issuer` 匹配。	必填
`region`	云区域，必须与 `issuer` 中的区域一致。	必填
`transport`	使用 STS 坐标时必须为 `sts`。	—
`scope`	OAuth scope 列表，必须包含 `openid`。	`openid profile email offline_access`
`shared_harnesses`	可选的共享 Harness 别名映射，供 `chat` 解析 Runtime ID 与 HTTPS endpoint。	—

agentkit auth login https://login.example.com/team-a
agentkit auth login --identity-only ./local-discovery.json

shared_harnesses 中最多发布 32 个别名；每个别名长度为 2 到 63，必须以小写字母或数字开头和结尾，中间可包含小写字母、数字和连字符。每个条目包含 runtime_id 与 endpoint，其中 endpoint 必须是无凭证、无路径、无查询参数、无 fragment 的 HTTPS origin。

身份仅登录不会提供控制面权限。需要解析 Runtime、管理资源或查询项目时，请另外配置 AK/SK，或使用普通 agentkit login 获取 STS 凭据。通过远程发现文档登录时，CLI 只会在浏览器登录和后续凭据处理成功后保存 profile。

auth logout

清除已存储的 SSO 会话（刷新令牌与缓存的 STS 凭据）。

标志/参数	说明	默认值
`-p, --profile <name>`	SSO 配置名称	当前活跃配置
`--all`	清除所有配置的会话	`false`

agentkit auth logout

auth whoami

显示当前凭据背后的身份。

标志/参数	说明	默认值
`-p, --profile <name>`	SSO 配置名称	当前活跃配置

agentkit auth whoami

auth profile set

创建或更新某个配置的登录坐标（非机密信息）。

标志/参数	说明	默认值
`<name>`	配置名称（必填）	无
`--issuer <url>`	OIDC issuer URL	无
`--client-id <id>`	公开的 OAuth client id	无
`--role-trn <trn>`	STS role TRN；未使用 `--identity-only` 时必填。	无
`--provider-trn <trn>`	IAM OIDC provider TRN	无
`--region <region>`	区域	`cn-beijing`
`--identity-only`	保存无需 STS 角色的 OIDC-only profile。	`false`

agentkit auth profile set my-profile \
  --issuer https://example.com \
  --client-id abc123 \
  --identity-only

登录状态保存在 ~/.agentkit/auth。长效 refresh token 会优先写入操作系统密钥环；无法使用密钥环时，CLI 将会话文件以 0600 权限写入本地。身份仅会话不会保留 OAuth access token，CLI 也不会打印已存储的 token。

auth profile list

列出已保存的配置。

标志/参数	说明	默认值
（无业务选项）	列出本机保存的登录配置	—

agentkit auth profile list

auth profile show

显示某个配置的坐标。

标志/参数	说明	默认值
`[name]`	配置名称	当前活跃配置

agentkit auth profile show my-profile

auth admin 子命令需要能管理 Identity、IAM 和 TOS 资源的云端凭证。可以使用 AK/SK，也可以使用当前 CLI SSO profile 中仍然有效的 STS 凭据。为避免管理操作被项目或全局端点覆盖影响，auth admin 会使用内置服务端点。

auth admin doctor

以只读方式检查账号能否完成 CLI SSO 接入，包括身份资源权限与凭证托管前置条件。检查未通过时命令返回非零退出码，并输出修复建议。

标志/参数	说明	默认值
`--account <account>`	预期的账号 ID；当前凭证不属于该账号时拒绝继续	—
`--region <region>`	云区域	当前云厂商的默认区域
`--data-plane`	同时检查凭证托管前置条件	`true`
`--no-data-plane`	跳过凭证托管前置条件检查	—

agentkit auth admin doctor --account <account-id> --region cn-beijing

auth admin create-userpool

创建用于 CLI SSO 登录的用户池，并以 JSON 输出用户池 ID。

该命令会在指定账号和区域创建身份资源。执行前先用 auth admin doctor 检查账号、区域和权限。

标志/参数	说明	默认值
`--name <name>`	用户池名称（必填）	—
`--account <account>`	预期的账号 ID；当前凭证不属于该账号时拒绝继续	—
`--region <region>`	云区域	当前云厂商的默认区域

agentkit auth admin create-userpool --name agentkit-cli-pool --account <account-id>

auth admin provision

为已有用户池创建或复用公开 CLI 客户端、IAM OIDC provider 和 STS 角色，并输出可发布的登录发现配置。

该命令会修改用户池和 IAM 资源。确认用户池属于目标账号与区域，并仅授予终端用户所需的角色权限。

标志/参数	说明	默认值
`--user-pool <uid>`	用户池 ID（必填）	—
`--account <account>`	预期的账号 ID；当前凭证不属于该账号时拒绝继续	—
`--region <region>`	云区域	当前云厂商的默认区域

agentkit auth admin provision --user-pool <user-pool-id> --account <account-id>

auth admin sso-setup

一次性准备用户池、公开 CLI 客户端、IAM OIDC provider、STS 角色和 TOS 登录发现文档，最后输出可分发给终端用户的 agentkit login <address> 地址。交互终端会询问是否复用用户池、是否配置上游身份提供方和是否使用自定义域名；非交互环境使用默认值或显式标志。

该命令会创建或修改身份、IAM 和 TOS 资源，并发布可公开访问的登录发现文档。上游身份提供方的 secret 属于敏感凭证；优先在交互提示中输入，避免把它写入仓库或 shell 历史。

标志/参数	说明	默认值
`-y, --yes`	非交互执行，接受默认值和显式传入的标志	`false`
`--user-pool <uid>`	复用已有用户池	—
`--create-pool <name>`	创建指定名称的用户池	`agentkit-cli-pool`
`--account <account>`	预期的账号 ID；当前凭证不属于该账号时拒绝继续	当前凭证所属账号
`--region <region>`	云区域	当前云厂商的默认区域
`--idp <type>`	上游身份提供方：`bytedance` \| `feishu`	不配置上游身份提供方
`--idp-client-id <id>`	上游身份提供方 Client ID；非交互模式下与 `--idp-secret` 一同使用	—
`--idp-secret <secret>`	上游身份提供方 Client Secret	—
`--bucket <bucket>`	托管登录发现文档的 TOS bucket	`agentkit-cli-<account-id>`
`--domain <domain>`	已完成 CNAME 与 HTTPS 证书配置的自定义登录域名；只填写主机名，不包含协议、端口或路径。	TOS bucket 的 HTTPS 地址
`--client-name <name>`	公开 CLI 用户池客户端名称	CLI 内置名称
`--provider-name <name>`	IAM OIDC provider 名称	CLI 内置名称
`--role-name <name>`	STS 角色名称	CLI 内置名称

# 交互配置；敏感的上游身份凭证可在隐藏输入提示中填写
agentkit auth admin sso-setup --account <account-id> --region cn-beijing

# 在自动化环境中复用已有用户池
agentkit auth admin sso-setup --yes \
  --user-pool <user-pool-id> \
  --account <account-id> \
  --bucket <discovery-bucket>

传入 --domain 时，命令会在发布后通过该 HTTPS 域名读取发现文档并校验内容。请先完成 CNAME 和证书配置；未通过公开访问校验时，命令不会把自定义域名作为最终登录地址输出。

auth admin publish

为已有用户池创建或复用 CLI 登录资源，并把 /.well-known/agentkit-cli 发现文档发布到指定 TOS bucket。也可以传入已有的 OIDC 与 IAM 坐标，仅发布发现文档而不重新创建 CLI 客户端、OIDC provider 或角色。

未传入显式坐标时，该命令会修改身份和 IAM 资源，并向指定 bucket 写入公开登录配置。确认 bucket、账号、用户池和显式坐标均属于目标环境；使用 --domain 前还需完成 CNAME 与 HTTPS 证书配置。

标志/参数	说明	默认值
`--user-pool <uid>`	用户池 ID（必填）	—
`--bucket <bucket>`	托管发现文档的 TOS bucket（必填）	—
`--account <account>`	预期的账号 ID；当前凭证不属于该账号时拒绝继续	—
`--region <region>`	云区域	当前云厂商的默认区域
`--domain <domain>`	已完成 CNAME 与 HTTPS 证书配置的自定义登录域名；输出会包含需要指向的 TOS 域名。	TOS bucket 的 HTTPS 地址
`--issuer <url>`	已有 OIDC issuer；与 `--client-id`、`--role-trn`、`--provider-trn` 同时传入后进入仅发布模式。	—
`--client-id <id>`	已有公开 OAuth client id；仅发布模式必填。	—
`--role-trn <trn>`	已有目标账号 STS role TRN；仅发布模式必填，且必须属于当前鉴权账号。	—
`--provider-trn <trn>`	已有目标账号 IAM OIDC provider TRN；仅发布模式必填，且必须属于当前鉴权账号。	—

agentkit auth admin publish \
  --user-pool <user-pool-id> \
  --bucket <discovery-bucket> \
  --account <account-id>

agentkit auth admin publish \
  --user-pool <user-pool-id> \
  --bucket <discovery-bucket> \
  --domain login.example.com \
  --issuer https://userpool-<id>.userpool.auth.id.cn-beijing.volces.com \
  --client-id <client-id> \
  --role-trn trn:iam::<account-id>:role/<role-name> \
  --provider-trn trn:iam::<account-id>:oidc-provider/<provider-name> \
  --account <account-id>

仅发布模式要求 --issuer、--client-id、--role-trn 和 --provider-trn 四个参数同时提供。--issuer 必须是 HTTPS URL，不能包含用户名、密码、查询参数或 fragment；--role-trn 与 --provider-trn 必须属于当前鉴权账号。--bucket 必须是 3 到 63 个小写字母、数字或连字符组成的 TOS bucket 名称，并以字母或数字开头和结尾。

控制台登录与凭据优先级

不传地址时优先使用当前云厂商已有的登录配置；无配置时进入控制台登录。--console 强制切换到控制台，--remote 用于远程服务器或无法接收本地浏览器回调的终端。控制台模式不能与 SSO 地址或 --identity-only 同时使用

agentkit login --console
agentkit --provider byteplus login --console
agentkit login --console --remote
agentkit whoami

火山引擎与 BytePlus 的控制台会话分别保存，whoami 和 logout 按当前云厂商选择会话。已配置的有效环境凭据仍优先于登录缓存，不会被登录覆盖需要云凭据的命令在交互终端缺少凭据时可启动浏览器登录。全局 --no-auto-login 禁止自动登录；CI、--json、--raw、--yes 或非交互终端也不会弹出自动登录，需事先提供凭据。纯本地操作和 --dry-run 不触发此流程退出登录只清除 CLI 保存的会话，不会撤销环境变量中的 AK/SK，也不会关闭浏览器中的云控制台会话。若退出后命令仍能访问资源，先检查当前终端是否仍导出了有效云端凭证

开始使用

AI-Friendly

命令参考

登录地址与发现文档

auth logout

auth whoami

auth profile set

auth profile list

auth profile show

auth admin doctor

auth admin create-userpool

auth admin provision

auth admin sso-setup

auth admin publish

控制台登录与凭据优先级

​auth login

​登录地址与发现文档

​auth logout

​auth whoami

​auth profile set

​auth profile list

​auth profile show

​auth admin doctor

​auth admin create-userpool

​auth admin provision

​auth admin sso-setup

​auth admin publish

​控制台登录与凭据优先级

auth login

登录地址与发现文档

auth logout

auth whoami

auth profile set

auth profile list

auth profile show

auth admin doctor

auth admin create-userpool

auth admin provision

auth admin sso-setup

auth admin publish

控制台登录与凭据优先级