---
url: /v6.2/cli-auth.md
---
# 认证与连接

## 先明确目标 host

CLI 执行任何业务动作前，都需要先明确自己要连接哪一个 HENGSHI SENSE host。

```bash
HBI_HOST="<你的-hengshi-sense-实例>" hbi auth login --device-login
```

`HBI_HOST` 可以直接写裸 host，也可以带二级路径，例如 `platform.hengshi.org/bi`。如果省略 scheme，CLI 会先探测 `https://`，失败后再试 `http://`。

如果你需要在本机长期保存一个默认 host，可以使用下面这个本地便捷机制：

```bash
# 最简单的本机默认 host 方式
hbi auth use --host "<你的-hengshi-sense-实例>"
```

`auth use` 更适合“我已经知道这个 host，只想把它设成当前机器的本地默认值”。如果你长期维护一组命名别名，也可以继续使用 `instance add` / `instance use`；但对脚本、Agent、多环境切换和 cron，更推荐始终显式传 `HBI_HOST=... hbi xxx`，不要把本机默认值机制当作主路径。

先记住一条对外心智模型（决策表）：

| 场景 | 推荐 | 说明 |
| --- | --- | --- |
| 本地人工终端 / 有人可以在浏览器批准（包括远程 openclaw / SSH） | `HBI_HOST=... hbi auth login --device-login` | 需要在浏览器批准页确认；CLI 会按 **当前 host** 保存并复用可续期登录态 |
| 远程自动化 / 服务账号 / CI | `HBI_HOST=... HBI_CLIENT_ID=... HBI_CLIENT_SECRET=... hbi auth login` | 使用 client credentials，可持续换取/刷新访问令牌 |
| 已有 `client_id` / `client_secret`，想直接在命令行传值（不走凭据 env 注入，也不提示输入） | `HBI_HOST=... hbi auth login --client-id "<client_id>" --client-secret "<client_secret>"`（或短参数 `-i/-s`） | 直接传入凭据值；`-i/-s` 是 **Client ID / Secret 的取值参数**，不是交互式输入快捷键。仅建议在受控环境使用（避免 shell 历史泄露） |
| 想在本机交互式输入并保存 client credentials | `HBI_HOST=... hbi auth login --interactive` | 仍属于 client credentials（direct credentials）路径：在**当前机器**提示输入并保存到 CLI 本地凭据存储；不是第三套认证模型 |
| 已有现成 token，只做一次性覆盖 | `HBI_TOKEN` 或 `--token` | **仅临时 override**；不会创建可复用登录态，也不承诺自动续期/刷新 |

说明：这里的 “openclaw / SSH” 仅表示 CLI 运行在远程机器/容器里；浏览器批准页可以在任意有浏览器的设备上完成，不要求远端能打开浏览器。

对外文档统一使用 `HBI_*` 环境变量。

## 方式一：优先使用浏览器 device login

这是默认推荐路径，最接近 `gh auth login` / `glab auth login` 的心智模型：先显式指定 host，再完成登录。

**最小可用示例**：

```bash
HBI_HOST="<你的-hengshi-sense-实例>" hbi auth login --device-login

# 等价入口：直接进入 auth device-login 子命令
HBI_HOST="<你的-hengshi-sense-实例>" hbi auth device-login
```

**典型输出**：

```
Device login initiated.
Please visit: https://<你的-hengshi-sense-实例>/auth/device
Enter this code: ABCD-1234

Waiting for authorization...
```

`hbi auth login --device-login` 和 `hbi auth device-login` 走的是同一条 device login 流程；前者更适合放在统一的 `auth login` 心智模型里理解，后者更适合你已经明确要走浏览器批准流时直接调用。

完成后，CLI 会把当前 host 的登录态缓存到本地，后续同一 host 的命令会自动复用。

即使你是在远程终端（openclaw / SSH / 跳板机 / 容器）里运行 CLI，也依然推荐走 `--device-login`：只要有人能在任意浏览器里打开批准页并确认即可。远端 CLI 只需要把终端里打印出来的 device code / verification URL 交给批准人。

浏览器端会进入一个专门的批准页，用来确认"当前是哪个实例、哪个设备码、由哪个登录身份来批准"：

![](/images/cli-auth/device-login-approval.png)

**下一步常见动作**：

```bash
# 确认登录状态
hbi auth status --output json

# 主动刷新访问令牌
hbi auth refresh
```

### device login 后，去哪里看个人 Client / PAT 凭据？

首次成功完成 device login 后，系统会为当前用户创建或复用一个**个人 Client**。你可以在 **个人中心 > 个人访问令牌** 面板里查看它：

![](/images/cli-auth/personal-access-token-panel.png)

这个面板有几个要点：

* 展示的是可长期复用的 `Client ID` / `Client Secret`
* 页面**不会**展示 access token；CLI 会在本地凭据缓存中自行保存与续用
* 如果你后续想切到 `client credentials` 模式，或需要给 Agent runtime / CI 配置可续期凭据，可以从这里复制对应的 client credentials
* 如果怀疑 `client_secret` 泄露，可以直接在这个面板删除当前 PAT client；删除后旧 client 会失效，后续 device login / PAT token 生成会重新建立一份新的 personal credential
* 本地人工终端日常使用时，仍然优先推荐 `hbi auth login --device-login`

## 方式二：使用 client credentials（direct credentials）登录

这条路径适合服务账号、CI、Agent runtime，或你已经拿到了 `client_id` / `client_secret` 的场景。

### 2.1 非交互：通过环境变量注入

```bash
HBI_HOST="<你的-hengshi-sense-实例>" \
HBI_CLIENT_ID="<client_id>" \
HBI_CLIENT_SECRET="<client_secret>" \
hbi auth login
```

CLI 会把登录态缓存到本地；只要当前环境里仍能拿到有效的 client credentials，后续命令就可以继续自动换取或刷新访问令牌。

### 2.2 非交互：通过命令行参数直接传值

如果你不想通过环境变量注入 `client_id` / `client_secret`，也可以直接用参数传入：

```bash
HBI_HOST="<你的-hengshi-sense-实例>" hbi auth login --client-id "<client_id>" --client-secret "<client_secret>"

# 短参数等价写法（它们是“取值参数”，不是交互快捷键）
HBI_HOST="<你的-hengshi-sense-实例>" hbi auth login -i "<client_id>" -s "<client_secret>"
```

注意：把 secret 写在命令行可能会被 shell history、进程列表或 CI 日志采集到；自动化环境仍优先用 Secret / 环境变量注入。

### 2.3 交互式：在当前机器输入并保存到本地凭据存储

```bash
HBI_HOST="<你的-hengshi-sense-实例>" hbi auth login --interactive
```

`--interactive` 会在**当前机器**提示输入 `client_id` / `client_secret`，并保存到 CLI 的本地凭据存储（随 CLI 配置保存，不写系统钥匙串）。它仍然属于 **client credentials（direct credentials）** 路径，只是输入方式不同，并不是第三套认证模型；更适合人工使用的本地桌面环境。

## 方式三：直接注入 access token

如果你已经有现成的访问令牌，也可以直接注入：

```bash
HBI_HOST="<你的-hengshi-sense-实例>" HBI_TOKEN="<token>" hbi auth status
```

对用户心智来说，这里只有一个概念：**访问令牌**。`HBI_TOKEN`（环境变量）和 `--token`（全局参数）只是把**同一个访问令牌**注入给 CLI 的两种方式；它们会覆盖已保存登录态，但不是另一套独立认证体系。

注意：token 注入不会把 token“升级”为可复用登录态，也不会自动 refresh；token 过期后需要再次注入或改回前两种可续期路径。

这条路径适合：

* 已有外部系统统一分发短期 token
* 临时自动化任务
* 不希望在当前环境保存 client credentials 的场景
* 明确接受 token 过期且不承诺 refresh / durable auth 的场景

## 常用认证命令

### 查看当前认证状态

**最小可用示例**：

```bash
hbi auth status --output json
```

**典型输出**：

```json
{
  "currentHost": "https://<your-hengshi-sense-instance>",
  "hosts": [
    {
      "apiUrl": "https://<your-hengshi-sense-instance>",
      "authMethod": "unknown",
      "authState": "authenticated",
      "credentialSource": "config-token-cache",
      "current": true,
      "host": "https://<your-hengshi-sense-instance>",
      "identity": "user",
      "refreshable": false,
      "source": "config-token-cache"
    }
  ]
}
```

**下一步常见动作**：

* 如果 `authState` 为 `unauthenticated`，先执行 `hbi auth login --device-login`
* 如果 `refreshable` 为 `true`，可以执行 `hbi auth refresh` 续期

### 主动刷新访问令牌

**最小可用示例**：

```bash
hbi auth refresh
```

**典型输出**：

```
Refreshing token.
Token refreshed.
   Expires in: 2529 seconds
```

### 退出登录

**最小可用示例**：

```bash
hbi auth logout
```

清除本地 token 缓存和已保存凭据。

### 其他命令

```bash
# 列出系统支持的认证方式
hbi auth methods

# 查看当前激活的认证方式
hbi auth active
```

## 对外使用建议

### 本地人工终端

优先使用：

```bash
HBI_HOST="<你的-hengshi-sense-实例>" hbi auth login --device-login
```

如果你已经在当前机器保存了默认 host，也可以直接运行 `hbi auth login --device-login`。但对文档示例、脚本和多环境场景，仍优先显式写出 `HBI_HOST=...`。

### Agent runtime / CI

优先使用：

```bash
HBI_HOST="<你的-hengshi-sense-实例>" \
HBI_CLIENT_ID="<client_id>" \
HBI_CLIENT_SECRET="<client_secret>" \
hbi auth login
```

这条路径不依赖系统钥匙串；CLI 使用配置文件支持的本地凭据存储保存可续期登录态。

### 已有现成 access token

优先使用：

```bash
export HBI_TOKEN="<token>"
```

如果只是临时覆盖一次，也可以改用全局参数：

```bash
hbi --token "<token>" auth status
```

## 凭据安全建议

* 不要把访问令牌、client secret 硬编码到脚本、文档或仓库里
* 自动化环境优先使用 Secret / 环境变量注入
* 人工桌面环境优先使用浏览器 device login
* 不要把完整的 `auth status` 输出原样贴到公开渠道

当前版本的 CLI 不再集成系统钥匙串 / OS keyring。默认行为和 `--credential-store config` 都使用 CLI 配置目录里的本地凭据存储；`--credential-store keyring` 仅作为兼容入口保留，并会明确报错。

如果你在 macOS、容器、远程开发环境或桌面会话不完整的机器上仍反复看到系统钥匙串弹窗，通常说明正在运行旧版或非当前正式发布的 `hbi`。请先按 [安装与升级](cli-install.md) 升级到正式版并重新登录。若当前环境完全不想保存 client credentials，则改用一次性的 `HBI_TOKEN` / `--token`。

## 常见连接问题

### `HBI_HOST` 或本机默认 host 未设置

CLI 不知道当前该访问哪个 host，通常会在第一次请求时失败。先检查：

```bash
echo "$HBI_HOST"
hbi instance current
```

如果你不想依赖本机默认值，直接在命令前显式写 `HBI_HOST=...`。

### 登录成功但没有看到目标资源

优先排查这几类问题：

1. 当前连到的不是预期 host / 实例
2. 当前账号没有对应应用、数据连接或空间的访问权限
3. Agent 执行时继承的环境变量与当前终端不一致

### token 过期或认证状态不稳定

建议优先检查：

```bash
hbi auth status --output json
hbi auth refresh
```

如果你使用的是 client credentials，也请确认 `HBI_CLIENT_ID` 和 `HBI_CLIENT_SECRET` 仍然有效。