问题排查

首先检查

• 将应用更新到最新版本。许多问题已在新版本中修复。与手机或其他 PC 配合使用的功能，要求所连接的 PC 也是最新版本。
• 如实确认错误提示。应用会针对不同原因显示不同的说明。

安装与更新

Windows 上出现 SmartScreen 警告

这是因为 Windows 安装文件目前还没有 Authenticode 代码签名。确认文件是从官方下载页面获取的之后，点击 更多信息 → 仍要运行。详细内容请参阅安装与首次运行。

Portable 版本不会自行更新

Windows Portable 不支持应用内自动安装。请从下载页面获取新文件进行替换。如需自动更新，请使用 Setup 版本。

无法连接到更新服务器

如果应用无法访问更新地址，会在默认浏览器中打开发布页面，您可以在那里直接获取安装文件。更新不需要账号或访问令牌。

收不到更新通知

• 如果选择了 나중에（稍后），在本次运行期间 4 小时内不会再次提醒。
• 如果选择了 이번 버전 건너뛰기（跳过此版本），该版本不会再自动提醒。
• 通过顶部的下载图标手动检查时，会重新显示暂缓的版本和已跳过的版本。

更新安装失败

失败原因会显示在更新窗口和重启确认窗口中。

• macOS：如果安装验证过程中出错或超时 120 秒，可以重试。
• Linux .deb：安装时应弹出管理员权限窗口。如果 3 分钟内没有弹出权限窗口，将停止安装，并给出在终端中直接安装的命令。会区分在权限窗口中取消的情况和未获得权限的情况分别说明。
• Linux，在沙箱 shell 中启动应用时：由于 NoNewPrivs 限制，权限提升可能被阻止。应用会通过用户级 systemd 弹出认证窗口；如果仍然不行，会说明如何在应用外的终端中用 sudo 安装。

手机连接与二维码

无法点击“연결 QR 만들기”（生成连接二维码）

只有在 PC 连接到中继服务器后才能生成二维码。请在 환경 설정 › 휴대폰（偏好设置 › 手机）中确认 휴대폰 연결 켜기（开启手机连接）已开启，且状态为已连接。

无法开启手机连接

如果 PC 无法使用操作系统的安全存储，就无法开启手机连接。应用不会改用明文保存。如果是 Linux，请启用 Secret Service 等 keyring 后重新启动应用。

提示二维码已过期或已被使用

二维码仅在 5 分钟内有效，且只能使用一次。请在 PC 上生成新的二维码重新连接。

出现“연결 시도가 너무 잦습니다”（连接尝试过于频繁）

认证失败的连接会被 PC 通过中继服务器暂时（约 1 分钟）阻止。请等待约 1 分钟后，使用新的二维码重试。

出现“연결이 해제되었습니다”（连接已断开）

这是因为 PC 断开了此手机的连接，或重新生成了桌面身份。请在 PC 上生成新的二维码重新连接。如果是通过 Google 账号连接的，在 PC 的审批窗口中重新允许即可。

提示 PC 已关机

请确认 PC 已开机且 Agent Switchboard 正在运行。PC 开机后会自动重新连接。

Android 应用只显示“네트워크 연결을 확인하세요”（请检查网络连接）

使用发布密钥签名的 Android 应用（0.6.0 及以上）只能在 PC 0.65.2 及以上版本上进行 Google 账号连接。请更新 PC 应用。

出现“Google 계정을 확인하지 못했습니다”（无法确认 Google 账号）

如果 PC 的时钟偏慢，Google 登录凭证的确认可能会失败。PC 0.65.3 修复了时钟略微偏慢的情况。请更新 PC 应用，并开启操作系统的自动时间同步。

PC 上出现“Google에 다시 로그인해 주세요”（请重新登录 Google）

这是 PC 的 Google 登录已过期。请点击 偏好设置 › 手机 中的 Google 다시 로그인（重新登录 Google）。重新登录之前，无法接受其他设备的新连接。

无法重新安装 Android 应用

如果之前安装过使用其他签名构建的 APK，新的 APK 无法覆盖安装。请卸载现有应用，安装新的 APK，然后重新连接 PC 并重新进行 Google 登录。

Web 应用地址变更后 PC 列表为空

手机 Web 应用由 https://app.switchboard.twentyoz.kr 提供。在旧地址使用的连接信息不会迁移到新地址。请通过二维码重新连接；如果之前使用的是 Google 账号，请重新登录以加载 PC 列表。

密钥与认证

“저장 후 적용”（保存并应用）按钮不可用（Linux）

在无法使用操作系统安全存储（keyring）的 PC 上无法保存 API 密钥，按钮上方会显示原因。请启用 keyring 后重新启动应用。

没有应用所选模型

连接测试和应用时，会确认所选模型是否确实可用。不可用时会停止应用。请在列表中重新选择可用的模型。

CLI 报错“credential is not configured”

在文件夹连接变更后，使用旧的运行配置文件启动 CLI 时可能出现此问题。请在工具设置中重新应用该连接，并重新启动 CLI。如果文件夹中有 Codex 设置但文件夹连接配置文件丢失，应用会根据已保存的设置重新创建配置文件。

持续出现“SECURE_STORAGE_BOOTSTRAP_FAILED”

1. 确认 Agent Switchboard 及相关进程已全部退出。
2. 如果因初始化过程中被强制终止，只留下了 .secure-storage-bootstrap.lock 锁文件，请先另行保存该文件，再将其删除并重新运行。
3. 请不要删除或更改 Local State 文件或 credentials 文件夹。请保留原始文件并与我们联系。

提示无法确认是否支持该推理强度

未能确认支持的推理强度会改用工具的默认值发送，并留下提示。如果在旧版本中因出现此提示而无法开始对话，请更新应用。

Windows 上 OAuth 登录窗口只打开一个空白终端

这是用户的 PowerShell 启动配置文件阻止了登录命令所导致的问题。从 0.61.2 开始，认证窗口会跳过启动配置文件。请更新应用。

联系我们时

报告与安全相关的问题时，请不要附上 API 密钥、OAuth 令牌、认证文件或完整的设置文件。只需发送连接地址、操作系统、应用版本、复现步骤，以及隐去敏感值的错误提示。咨询请发送至 hello@twentyoz.kr。