---
url: /v6.2/cli-faq.md
---
# 排障与 FAQ

## HENGSHI CLI 主要给谁用？

严格来说，CLI 既可以给人直接用，也可以给 Agent 用；在很多实际场景里，它也很适合作为 Agent 或自动化流程的稳定命令入口。

## skills 是必须的吗？

对 Agent 来说，基本可以认为是。

* 如果你要让 OpenClaw 等 Agent 稳定复用 HENGSHI CLI 工作流，官方 skills 很重要
* 它们负责把执行顺序、`--dry-run` 策略和输出约束沉淀成可复用的标准流程

对人工直接在终端里执行命令来说，CLI 本身可以工作，因此不是硬性前置条件。

## 我应该怎么选认证方式？

通常可以按下面方式选：

1. **本地人工终端**：优先 `hbi auth login --device-login`
2. **Agent runtime / CI**：优先 `HBI_HOST` + `HBI_CLIENT_ID` + `HBI_CLIENT_SECRET`
3. **已有现成访问令牌**：最后才用 `HBI_HOST` + `HBI_TOKEN` 或一次性的 `--token`

如果需要最明确的一次性登录入口，推荐直接运行：

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

这里的 `HBI_HOST` 不要求写完整 URL；裸 host 和 `platform.hengshi.org/bi` 这类带路径的写法都可以。省略 scheme 时 CLI 会先探测 `https://`，失败后再试 `http://`。

## 怎么确认 CLI 本身安装没问题？

先跑这三条：

```bash
hbi --version
hbi --help
hbi auth status
```

如果前两条正常，而第三条只是提示未登录，说明 CLI 本体已可用。

## 登录后，CLI 会自动复用登录态吗？

会。在常见登录路径下，CLI 会把本地登录态缓存下来，后续命令自动复用；如果当前环境里还能拿到有效的 client credentials，后续需要认证的命令也可以继续自动换取或刷新访问令牌。

## 为什么还会看到系统钥匙串弹窗，或者我想在容器 / 远程环境里不保存凭据？

当前正式 CLI 的认证刷新不再使用系统钥匙串；默认使用 CLI 本地配置凭据存储。如果仍反复看到系统钥匙串弹窗，请先确认运行的是当前官方 `hbi`，而不是旧安装产物，升级后重新登录。

容器、远程开发机、CI 中优先使用显式的 `HBI_HOST` + `HBI_CLIENT_ID` + `HBI_CLIENT_SECRET`。如果当前环境完全不想保存 client credentials，则使用一次性的 `HBI_TOKEN` / `--token`。

## device login 生成的个人 Client 去哪里看？

在 **个人中心 > 个人访问令牌**。

首次成功完成 device login 后，系统会为当前用户创建或复用一个个人 Client。该面板展示 `Client ID` 和 `Client Secret`，但不会展示 access token；access token 仍由 CLI 在本地缓存和续用。

## 为什么登录了却还是看不到目标资源？

优先检查：

1. `HBI_HOST` 或当前保存的本机默认 host 指向的是不是正确实例
2. 当前账号对目标应用、数据集、数据连接是否真的有权限
3. Agent 运行时继承的环境变量是不是和你当前终端一致

## 为什么 Agent 执行高风险动作前总被建议先 `--dry-run`？

因为授权、配置更新、部分写动作本身就更适合进入审查流。`--dry-run` 的价值不是“多一步”，而是让 Agent 先把它准备改什么、改到哪里、影响什么讲清楚，再决定是否真正落库。

## 为什么页面上看不到 Autopilot 指示器？

最常见的原因有：

1. 管理员已在系统环境中关闭 `GENERAL_CONFIG_ENABLE_SSE`，当前实例不再展示 Autopilot / SSE 实时回显 UI（前端系统偏好里会体现为 `enableSse=false`）
2. 当前页面不在支持实时回显的页面范围里
3. 当前是移动端，或该页面本身不展示顶部状态提示
4. 当前会话并没有建立可用的 SSE 连接
5. 当前用户尚未登录或当前页面本身没有进入实时回显路径

当前页面支持边界，可以直接参考 [实时回显与 Autopilot](cli-autopilot.md) 里的“当前页面支持边界”。

## 为什么 CLI / Agent 改了资源，页面却没有自动刷新？

这通常不意味着 CLI 没生效，更常见的是下面几类原因：

1. 管理员已在系统环境中关闭 `GENERAL_CONFIG_ENABLE_SSE`
2. 当前页面不在实时回显覆盖范围里
3. 变更资源不属于当前 detail 页或当前活跃列表
4. 当前动作本身属于执行、执行记录或 DAG 这类以同步等待 / 轮询为主的路径
5. 当前连接中断，Autopilot 指示器已断开
6. 反向代理或网关打断了 `/api/sse/subscribe` 长连接，或把 SSE 响应缓冲了
7. 页面存在本地未保存编辑，不适合被外部更新直接覆盖

## 排障时应该带哪些信息

建议至少附带下面这些信息：

* CLI 版本
* 安装方式（静态分发 / 发布资产）
* 操作系统
* `HBI_HOST`（如果依赖本机默认 host / instance alias，也一起说明）
* 认证方式（device login / client credentials / 访问令牌临时注入）
* 执行的命令
* 是否带了 `--dry-run`
* 最好附一份 `--output json` 的结果
* 如果涉及 UI 回显，再补充页面路径、Autopilot 状态和是否为移动端

## 推荐的排障顺序

1. 先确认 CLI 本体是否正常
2. 再确认目标实例与认证
3. 再确认当前实例、目标资源与权限
4. 最后才看 UI 实时回显是不是落在当前页面范围里

这样排查会比一上来只盯着浏览器页面更快。