Ulanzi Studio 如何同步 Codex / Claude 状态到 Vibe Key
连接 Vibe Key 后，Ulanzi Studio 会尝试为本机的 Codex 与 Claude Code 自动安装 Hooks。当你在 Codex 或 Claude 中开启新会话并开始工作时，Ulanzi Studio 会监听 Agent 状态，并把状态同步到 Vibe Key 的按键和旋钮灯，帮助你感知当前任务是否在运行、是否需要确认，或是否需要人工介入。
开始使用
- 打开 Ulanzi Studio：确保软件已安装并正常运行。
- 连接 Vibe Key：连接设备，等待 Ulanzi Studio 识别成功。
- 自动安装 Hooks：如果本机已安装 Codex 或 Claude Code，Ulanzi Studio 会自动尝试安装对应 Hooks。
- 开启新会话：打开 Codex 或 Claude，新建一个会话并开始工作。
- 查看灯效反馈：当 Agent 状态变化时，Vibe Key 会同步显示对应灯效。
灯效说明
- 按键 K1：表示语音输入状态。正在听你说话时呼吸，其他状态熄灭。
- 按键 K2：表示当前有待确认事项。需要确认、批准或继续时呼吸。
- 按键 K3：表示可取消、可打断，或当前需要人工介入时呼吸。
- 旋钮灯：表示 Agent 仍在推进任务。思考中、执行中、后台整理中会常亮。
灯效规则
- Vibe Key 同一时刻只显示一个焦点会话的状态。
- 多个会话不会同时抢灯显示。
- 呼吸只有一个统一节奏。
- 1 个审批和多个审批的灯效相同，不会叠加多个呼吸。
- 待处理数量通过界面、语音或列表表达，不通过灯效节奏表达。
锁屏与睡眠
锁屏通常不影响 Agent 继续工作，状态同步一般也会继续。
睡眠通常会暂停本地进程，Agent 与 Hooks 一般不会继续运行，Vibe Key 状态同步也会中断。
建议长任务执行时避免电脑自动睡眠；只锁屏通常没有问题，但睡眠可能导致任务暂停。
常见问题
为什么 Vibe Key 没亮？
可能是设备未成功连接、灯光模式不是工作模式、Ulanzi Studio 未运行、Hooks 未安装成功、当前没有活跃会话，或电脑进入了睡眠状态。
为什么 Codex / Claude 在工作，但 Vibe Key 没反应？
请检查 Ulanzi Studio 是否仍在后台运行、Hooks 是否已成功注册、当前是否是新会话或发生了状态变化，以及电脑是否进入睡眠。
如何确认 Hooks 是否安装成功？
Claude Code 可在终端中使用 /hooks 查看。
Codex 可检查 ~/.codex/ 或项目 .codex/ 中的 Hooks 配置，也可在 Codex → 设置 → 钩子 → 用户配置中查看。
为什么多个审批只显示一个呼吸？
这是设计如此。Vibe Key 只表达“当前有待处理事项”，不表达数量；多个审批不会叠加多个呼吸。
锁屏后任务会停止吗？
一般不会，锁屏通常不影响任务继续执行。
睡眠后任务会停止吗？
一般会，睡眠通常会暂停本地进程与状态同步。
重装系统或升级客户端后不生效怎么办？
建议回到 Ulanzi Studio，重新执行 Hooks 安装或修复。
排查步骤
- 确认 Vibe Key 已连接。
- 确认 Ulanzi Studio 正在运行。
- 确认 Codex 或 Claude 已开启新会话。
- 检查 Hooks 是否安装成功。
- 检查电脑是否进入睡眠。
- 如仍未恢复，重新安装或修复 Hooks。