硬件控制

硬件控制让 Agent Wallet 在处理敏感操作时，能够切换到 UKey Wallet 硬件钱包完成确认与签名。这也是 UKey Wallet 与仅依赖软件托管或 TEE 签名的 agent wallet 方案之间的重要区别。

什么时候升级到硬件

场景	硬件期望
大额转账	由用户在 UKey Wallet 设备上核对接收方、金额、链和费用
合约交互	Agent 先执行 simulation；设备支持时展示 clear-signing 信息
Swap 执行	Agent 先完成 quote / build；只有在用户确认执行后才进入设备确认
隐藏钱包	明确指定 passphrase mode，Agent 不应自行判断当前是否为隐藏钱包
设备可信检查	先通过 ukey wallet device verify 验证已连接设备，再继续签名

连接并登录

查看当前已连接的设备：

ukey wallet device search

使用硬件钱包完成登录：

ukey wallet auth login --hardware

如果同时连接了多台设备，应显式指定目标设备：

ukey wallet auth login --hardware --device-id <uuid>

在隐藏钱包场景下，非交互环境中必须明确指定 passphrase 的处理方式：

ukey wallet auth login --hardware --passphrase-mode none
ukey wallet auth login --hardware --passphrase-mode on-host
ukey wallet auth login --hardware --passphrase-mode on-device

活动会话

在 ukey wallet auth status 中，硬件会话通常表现为：

字段	预期值
loginMethod	hardware
walletKind	hw
device	当前已连接的 UKey Wallet 设备信息
passphraseMode	none、on_host 或 on_device

登录完成后，后续命令会自动复用当前活动会话。

设备生命周期

ukey wallet device verify
ukey wallet device change-pin
ukey wallet device toggle-passphrase
ukey wallet device settings

不要绕过设备上的物理确认。如果设备锁定、连接断开、要求输入 PIN / Passphrase，或在设备上拒绝请求，Agent 应明确反馈当前状态并立即停止后续操作。