常见问题

启动后为什么只有托盘图标？

这是设计行为。蓝木偶按会话懒创建宠物，不会启动一个无会话的空窗口。请完成 Hooks 配置并重启 Claude Code，然后提交第一句提问；首个已配置事件到达后，宠物就会出现。

配置已经完成，宠物仍然不出现

依次检查：

1. 蓝木偶进程是否正在运行；
2. 修改 .claude/settings.json 后是否重启了 Claude Code；
3. Hook URL 是否为 http://127.0.0.1:48291/state，或是否与实际自定义端口一致；
4. 托盘是否处于灰色的“停止监听”状态；
5. 48291 是否被另一个残留进程占用。

可访问健康检查确认服务：

curl http://127.0.0.1:48291/health

正常响应为：

{"ok": true}

启动时提示端口失败怎么办？

默认端口具有独占性，同一时刻只能运行一个使用此端口的蓝木偶进程。先检查是否已有实例或残留进程；也可以设置新的 BLUE_PUPPET_PORT，并同步更新所有 Hook URL。

托盘图标变灰了

这表示 Hooks 监听已暂停。HTTP 服务仍然在线并正常应答，但事件会被丢弃。打开托盘菜单，选择 恢复Hooks监听 即可。

暂停期间已经发生的事件不会补放；恢复后从后续新事件开始更新。

为什么显示“暗中使劲”而不是“任务完成”？

Stop 到来时，该会话仍有已启动但未观察到终态的后台任务，因此进入 sneaky。程序会周期性重新读取 transcript，全部任务结束后自动转为 done。

如果怀疑 transcript 中缺少任务启动或终止记录，可检查对应会话文件；读取失败时，程序不会仅凭猜测保持后台任务计数。

如何批量清理桌面宠物？

• 关闭完成：只清理状态为 done 的宠物；
• 关闭所有：清空所有宠物，但保留托盘进程；
• 退出：关闭宠物并结束整个程序。

单个宠物也可以通过右键菜单中的 关闭此宠物 单独关闭。

会话结束后宠物为什么不自动消失？

当前实例需要手动清理。这样任务完成后仍能保留结果状态和会话标识，不会因为 Claude Code 停止而立刻失去桌面反馈。可以使用托盘的“关闭完成”或“关闭所有”。

标题为什么先是一句话，后来又变了？

新会话先截取首条提问作为占位摘要。后台标题监视线程会读取本地 Claude Code 会话文件，发现 AI 生成的 ai-title 后自动替换，因此两种文字都属于正常阶段。

可以只修改一只宠物的形象吗？

可以。在目标宠物上打开右键菜单，选择 切换形象。当前形象会打勾，修改只影响该实例。新会话默认按蓝木偶、金红战神、钢铁侠的顺序循环分配。

宠物未运行会影响 Claude Code 吗？

不会阻塞任务。HTTP Hook 连接失败是非阻塞错误，只是没有桌面状态更新。重新启动蓝木偶后，后续事件可以继续创建或更新宠物。

UPX 压缩被杀软关注怎么办？

直接使用未压缩版本：

cargo build --release

UPX 只缩小发布文件，不改变功能。压缩版本首次启动时需要运行时解压，部分杀软也可能对压缩壳更敏感；它不是蓝木偶运行所必需的依赖。

官网如何部署到 Cloudflare Pages？

官网位于仓库的 website/ 目录，是纯静态 VitePress 站点。Cloudflare Pages 使用以下设置即可：

设置	值
Build command	pnpm build
Build output directory	.vitepress/dist
Root directory	website
Node.js	建议使用 22

website/public/_headers 已为带哈希的构建资源和其他静态图片配置缓存。站点默认以根路径 / 发布，不需要额外 SPA 重定向规则。