指南文档
先检查这两点
- 把应用更新到最新版本,很多问题在新版本中已经修复。与手机或其他 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”
- 确认 Agent Switchboard 及相关进程已全部退出。
- 如果因初始化时被强制终止,只留下了
.secure-storage-bootstrap.lock锁文件,请先把该文件复制到别处备份,再删除它并重新启动。 - 请勿删除或修改
Local State文件和credentials文件夹。保持原样,并与我们联系。
提示无法确认是否支持该推理强度
无法确认是否支持的推理强度,会按工具默认值发送,并给出提示。如果旧版本因为这条提示而无法开始对话,请更新应用。
Windows 上 OAuth 登录窗口只打开一个空白终端
这是用户的 PowerShell 启动配置文件拦截了登录命令导致的。从 0.61.2 起,认证窗口会跳过启动配置文件。请更新应用。
联系我们
报告安全问题时,请不要附上 API 密钥、OAuth 令牌、认证文件或完整的设置文件。只需提供连接地址、操作系统、应用版本、复现步骤,以及隐去敏感值的错误提示。联系邮箱:hello@twentyoz.kr。