认证（dev-auth 种子预置）

为什么需要身份预置（Auth Seeding）

如果只需认证一次，就能在各个栈之间复用该身份，大多数工作流都会顺畅得多：

• 无需每次创建新栈时都重新登录
• 可以快速创建或复用 PR 栈（hstack stack pr … --seed-auth）

hstack 推荐的做法是建立一个名为 dev-auth 的专用种子栈。

身份预置采用尽力而为（best-effort）策略，且刻意不在栈之间完整复制数据库；它主要关注：

• UI 和 CLI 所需的凭据及配置文件
• 必要的最小化数据库记录（以确保栈能够干净利落地启动）

创建种子栈（推荐）

hstack auth seed

如果需要为现有的种子栈重新认证（例如凭据已失效或不正确，但 CLI 仍提示“already authenticated”），请运行：

hstack auth seed --force

该命令会启动完整的引导流程：

• 创建 dev-auth 栈（作为全新身份）
• 引导你完成 UI 登录，让种子栈立即可用
• （可选）持久化默认配置，以便后续创建的栈能自动复用它

如需以非交互模式运行（用于脚本编写），请查看：

hstack auth seed --help

将其设为默认种子（推荐）

如果希望新栈在未初始化时自动进行预置，请在你的主目录覆盖配置中设置以下两项：

• Kaiwu_STACK_AUTH_SEED_FROM=dev-auth
• Kaiwu_STACK_AUTO_AUTH_SEED=1

这些配置通常位于：

• ~/.Kaiwu-stack/env.local

有关环境变量文件的优先级，请参阅路径、目录与环境优先级。

为特定栈使用种子

要将身份信息预置到某个栈中：

hstack stack auth <stack> copy-from dev-auth

如果希望保持凭据同步（隔离性稍弱，但更方便），可以创建身份文件的符号链接：

hstack stack auth <stack> copy-from dev-auth --link

复制与链接的对比：

• copy（默认）：隔离性更好，对测试更安全
• link：更便捷（凭据保持同步），但各栈之间会共享认证状态

一次预置多个栈

hstack auth copy-from dev-auth --all --except=main,dev-auth

对于全服务端栈（Kaiwu-server），预置操作可能需要 Docker 基础设施处于运行状态。

存储 UI 开发密钥（可选）

部分 UI 自动化工作流需要在你的设备上存储本地“开发密钥”：

hstack auth dev-key --set "<key>"
hstack auth dev-key --print

提示：在从 UI 登录或向智能体传递密钥时，--print 正是你所需要的。

帮助信息：

hstack auth --help

登录（本地优先）

hstack auth login 用于认证当前栈（默认为 main）。

在 TTY 终端环境下，hstack auth login 采用本地优先策略：

• 优先针对你的本地栈进行认证（而非托管版 Kaiwu 应用）
• 引导你打开栈的 Web UI 并连接终端
• 如果栈尚未运行，它可以为你自动在后台启动该栈

默认情况下，审批流程会使用栈的本地 UI：

• 对于基于源码构建的栈，通常指 Expo Web UI
• 对于包含活跃运行时快照的命名栈，则优先使用基于运行时的服务端 UI

首次构建 Expo Web 可能需要几分钟（属于正常现象）。

基础用法：

hstack auth login

无头环境 / 适合远程操作（输出移动端 App 可用的二维码或深层链接，无需浏览器）：

hstack auth login --method=mobile --no-open

如果你使用的不是 main 栈：

hstack stack auth <stack> login

强制重新认证：

hstack auth login --force
hstack stack auth <stack> login --force

当某个栈是使用旧凭据预置的、目前表现异常时，--force 是最合适的修复工具。

在当前版本中，login --force 会在重新认证前真正执行栈作用域内的清理：

• 清理该栈陈旧的栈级服务端别名
• 保留该栈之外其他无关的凭据
• 避免在下一次守护进程启动时重新激活旧版遗留的认证文件

当你遇到以下症状时，可以使用该工具：

• 即使已预置身份，栈 UI 仍显示未登录
• 守护进程报告认证失败或 401
• 全新的临时主目录下可以正常登录，但该栈默认的 cli/ 目录却不行

如果要修复具名栈，建议使用带栈作用域的命令形式：

hstack stack auth <stack> login --force

目标 Web 应用配置

控制登录浏览器流程所使用的 UI 源（origin）：

hstack auth login --webapp=auto|stack|expo|public|hosted
hstack auth login --webapp-url=http://localhost:8081

说明：

• auto（默认）：在 TTY 环境下采用引导式本地优先策略
• stack：强制使用栈的 Web UI 源（环境变量覆盖 → 激活状态下的运行时/服务端 UI → 运行中的 Expo → 栈服务端）
• expo：使用正在运行的 Expo 开发服务器 Web UI（若没有运行中的 Expo Web 应用则会失败）
• public：使用栈的公开/服务端 URL
• hosted：使用托管 Web 应用（https://kaiwu.wujilabs.cn）作为审批 UI（在你的栈未提供 Web UI 服务时最为稳妥）

如果 auto 选择了 Expo，但 Expo 未能就绪，hstack 将：

• 在你的栈没有公开 URL 时直接报错退出（托管端/移动端无法访问 localhost）
• 否则，提示你继续等待（推荐），或回退到 --webapp=hosted / --method=mobile，以便继续完成登录

必要时启动栈

如果栈未在运行，hstack auth login 会提示是否启动。若无需提示直接自动启动：

hstack auth login --start-if-needed