认证与连接
先明确目标 host
CLI 执行任何业务动作前，都需要先明确自己要连接哪一个 HENGSHI SENSE host。
HBI_HOST="<你的-hengshi-sense-实例>" hbi auth login --device-loginHBI_HOST 可以直接写裸 host，也可以带二级路径，例如 platform.hengshi.org/bi。如果省略 scheme，CLI 会先探测 https://，失败后再试 http://。
如果你需要在本机长期保存一个默认 host，可以使用下面这个本地便捷机制：
# 最简单的本机默认 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）路径：在当前机器提示输入并保存到系统钥匙串/本地凭据存储；不是第三套认证模型 |
| 已有现成 token，只做一次性覆盖 | HBI_TOKEN 或 --token | 仅临时 override；不会创建可复用登录态，也不承诺自动续期/刷新 |
说明：这里的 “openclaw / SSH” 仅表示 CLI 运行在远程机器/容器里；浏览器批准页可以在任意有浏览器的设备上完成，不要求远端能打开浏览器。
对外文档统一使用 HBI_* 环境变量。
方式一：优先使用浏览器 device login
这是默认推荐路径，最接近 gh auth login / glab auth login 的心智模型：先显式指定 host，再完成登录。
最小可用示例：
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 交给批准人。
浏览器端会进入一个专门的批准页，用来确认"当前是哪个实例、哪个设备码、由哪个登录身份来批准"：
下一步常见动作：
# 确认登录状态
hbi auth status --output json
# 主动刷新访问令牌
hbi auth refreshdevice login 后，去哪里看个人 Client / PAT 凭据？
首次成功完成 device login 后，系统会为当前用户创建或复用一个个人 Client。你可以在 个人中心 > 个人访问令牌 面板里查看它：
这个面板有几个要点：
- 展示的是可长期复用的
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 非交互：通过环境变量注入
HBI_HOST="<你的-hengshi-sense-实例>" \
HBI_CLIENT_ID="<client_id>" \
HBI_CLIENT_SECRET="<client_secret>" \
hbi auth loginCLI 会把登录态缓存到本地；只要当前环境里仍能拿到有效的 client credentials，后续命令就可以继续自动换取或刷新访问令牌。
2.2 非交互：通过命令行参数直接传值
如果你不想通过环境变量注入 client_id / client_secret，也可以直接用参数传入：
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 交互式：在当前机器输入并保存到钥匙串
HBI_HOST="<你的-hengshi-sense-实例>" hbi auth login --interactive--interactive 会在当前机器提示输入 client_id / client_secret，并保存到系统钥匙串（或本地凭据存储）。它仍然属于 client credentials（direct credentials） 路径，只是输入方式不同，并不是第三套认证模型；更适合人工使用的本地桌面环境。
方式三：直接注入 access token
如果你已经有现成的访问令牌，也可以直接注入：
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 的场景
常用认证命令
查看当前认证状态
最小可用示例：
hbi auth status --output 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续期
主动刷新访问令牌
最小可用示例：
hbi auth refresh典型输出：
Refreshing token.
Token refreshed.
Expires in: 2529 seconds退出登录
最小可用示例：
hbi auth logout清除本地 token 缓存和已保存凭据。
其他命令
# 列出系统支持的认证方式
hbi auth methods
# 查看当前激活的认证方式
hbi auth active对外使用建议
本地人工终端
优先使用：
HBI_HOST="<你的-hengshi-sense-实例>" hbi auth login --device-login如果你已经在当前机器保存了默认 host，也可以直接运行 hbi auth login --device-login。但对文档示例、脚本和多环境场景，仍优先显式写出 HBI_HOST=...。
Agent runtime / CI
优先使用：
HBI_HOST="<你的-hengshi-sense-实例>" \
HBI_CLIENT_ID="<client_id>" \
HBI_CLIENT_SECRET="<client_secret>" \
hbi auth login如果运行时不希望依赖系统钥匙串，也可以只走环境变量与本地凭据缓存。
已有现成 access token
优先使用：
export HBI_TOKEN="<token>"如果只是临时覆盖一次，也可以改用全局参数：
hbi --token "<token>" auth status凭据安全建议
- 不要把访问令牌、client secret 硬编码到脚本、文档或仓库里
- 自动化环境优先使用 Secret / 环境变量注入
- 人工桌面环境优先使用浏览器 device login
- 不要把完整的
auth status输出原样贴到公开渠道
如果某些容器或受限环境不适合访问系统钥匙串，可以显式设置：
export HBI_DISABLE_KEYRING=true如果你在容器、远程开发环境或桌面会话不完整的机器上反复看到系统钥匙串弹窗，通常说明当前环境不适合交互式保存凭据。此时优先改用显式的 HBI_HOST + HBI_CLIENT_ID + HBI_CLIENT_SECRET（或一次性的 HBI_TOKEN）注入，并配合 HBI_DISABLE_KEYRING=true 关闭系统钥匙串集成。
常见连接问题
HBI_HOST 或本机默认 host 未设置
CLI 不知道当前该访问哪个 host，通常会在第一次请求时失败。先检查：
echo "$HBI_HOST"
hbi instance current如果你不想依赖本机默认值，直接在命令前显式写 HBI_HOST=...。
登录成功但没有看到目标资源
优先排查这几类问题：
- 当前连到的不是预期 host / 实例
- 当前账号没有对应应用、数据连接或空间的访问权限
- Agent 执行时继承的环境变量与当前终端不一致
token 过期或认证状态不稳定
建议优先检查：
hbi auth status --output json
hbi auth refresh如果你使用的是 client credentials，也请确认 HBI_CLIENT_ID 和 HBI_CLIENT_SECRET 仍然有效。