常见问题排查

排查安装、钩子、终端、手机连接与中央会话问题。

macOS 提示无法打开

当前桌面版本尚未完成 Developer ID 签名或公证。只从你信任的发布来源获取安装包。若系统阻止打开，先取消提示，再使用安装包内的启动辅助脚本。确认来源后，也可对已安装应用执行：

xattr -cr "/Applications/AI Agent Session Center.app"

更新应用后可能需要重新处理。完整说明见下载页面。

默认端口为 3333。当前服务会强制结束占用该端口的进程后重试。运行第二个实例时请使用其他端口：

npm start -- --port 8080

修改已有配置文件中的端口字段即可，请勿覆盖其他设置和凭据。

切换 Node 版本后，better-sqlite3 或 node-pty 可能需要重新编译。请在项目目录、匹配项目要求的 Node 版本下执行：

npm rebuild better-sqlite3 node-pty

编译 node-pty 需要对应操作系统的编译工具链。

先在「设置 → HOOKS」检查状态并重新安装。确认 Claude 配置中存在 AASC 钩子，脚本存在且可执行；发送提示词时观察文件队列是否追加事件。

rg dashboard-hook ~/.claude/settings.json
ls -l ~/.claude/hooks/dashboard-hook.sh
tail -f /tmp/claude-session-center/queue.jsonl

实际脚本和队列名称以安装器输出为准。macOS/Linux 优先使用文件队列，HTTP 为备用路径。降低钩子密度后需要重新安装，以使配置一致。

检查 jq --version。macOS 可通过 brew install jq 安装，Debian/Ubuntu 可使用 sudo apt install jq。缺失 jq 可能造成元数据不完整，并不代表所有钩子都未运行。

查看调试日志与钩子统计。各密度都包含 SessionStart。没有对应终端的会话不会生成普通实时卡片；较早启动的交互式 Claude 可能需等待约 20 秒的进程扫描。同一目录内同时运行多个会话时，也需检查是否匹配到了错误会话。

客户端从一秒开始逐步增加重连间隔，最长十秒，并尝试重放最近 500 个事件。连接恢复后若界面仍停留在旧状态，可刷新页面。检查网络、反向代理和远程认证配置，不要把认证令牌贴到公开日志中。

检查 SHELL 指向真实可执行的 shell，node-pty 是否可加载，以及系统编译依赖是否完整。当前上限为 50 个会话、130 个终端。

恢复 SSH 会话时，私钥路径必须仍然可访问。可通过 ssh-add -l 检查代理中已加载的密钥，并先在普通终端测试同一主机的 SSH 配置。

三维场景默认关闭。可保持关闭，减少保留的已结束会话，并降低外观效果强度。还应检查系统硬件加速是否可用；基本会话管理不依赖三维视图。

2.10.60 起中央会话默认关闭。在「设置 → 高级」开启中央会话并重启。创建入口仅限本机控制面板；范围已被其他中央会话占用时会禁用。

若输入被拒绝，检查目标会话是否禁止接管、最近 60 秒内有人操作或处于 Esc 暂停。等待人工确认的卡片显示在右下角，五分钟后过期。更多规则见中央会话。

npm run reset

该命令先备份仓库的 data/ 到 data/backups/，再清理钩子、脚本、配置、数据库和临时队列，并通知浏览器清除本地数据。随后需重新完成设置。它不重置桌面应用自己的数据目录。

在电脑「设置 → 高级 → 关于」复制版本信息；手机版本位于「更多 → 此手机」。提交问题时描述复现步骤、系统版本及脱敏后的错误信息。

调试日志按约 5 MB 轮转。钩子与消息队列统计也可帮助定位问题。技术缺陷可提交至 GitHub 项目；体验码、套餐与购买问题请联系官方客服。