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

# 鉴权与登录

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

选择登录方式时，先确定后续任务：

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

完成浏览器授权后，用 `agentkit whoami` 确认当前身份。账号身份正确仍需具备目标资源对应的权限

## auth login

通过浏览器完成当前云厂商的控制台登录，或使用指定 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` |

```bash lines theme={null}
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`](/productions/agentkit-cli/preview/zh/commands/chat) 解析 Runtime ID 与 HTTPS endpoint。 | — |

```bash lines theme={null}
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。

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

## auth logout

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

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

```bash lines theme={null}
agentkit auth logout
```

## auth whoami

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

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

```bash lines theme={null}
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` |

```bash lines theme={null}
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

列出已保存的配置。

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

```bash lines theme={null}
agentkit auth profile list
```

## auth profile show

显示某个配置的坐标。

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

```bash lines theme={null}
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` | 跳过凭证托管前置条件检查 | — |

```bash lines theme={null}
agentkit auth admin doctor --account <account-id> --region cn-beijing
```

## auth admin create-userpool

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

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

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

```bash lines theme={null}
agentkit auth admin create-userpool --name agentkit-cli-pool --account <account-id>
```

## auth admin provision

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

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

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

```bash lines theme={null}
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>` 地址。交互终端会询问是否复用用户池、是否配置上游身份提供方和是否使用自定义域名；非交互环境使用默认值或显式标志。

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

| 标志/参数 | 说明 | 默认值 |
| - | - | - |
| `-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 内置名称 |

```bash lines theme={null}
# 交互配置；敏感的上游身份凭证可在隐藏输入提示中填写
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>
```

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

## auth admin publish

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

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

| 标志/参数 | 说明 | 默认值 |
| - | - | - |
| `--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；仅发布模式必填，且必须属于当前鉴权账号。 | — |

```bash lines theme={null}
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` 同时使用

```bash lines theme={null}
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，也不会关闭浏览器中的云控制台会话。若退出后命令仍能访问资源，先检查当前终端是否仍导出了有效云端凭证