常见问题

按问题分类逐条排查；80% 的问题都在前 3 个。

连接类

「无法连接桌面，请检查网络或确认桌面端已启动」

按下面的顺序逐项排查：

桌面端「远程访问」是否在跑？状态条是不是绿灯？
公网 URL 在浏览器能否打开 https://你的地址/api/v1/ping？应返回 {"ok":true,...}
frp 服务端口是否被防火墙封？
- ICP 备案的 80/443 走 https 没问题
- 自定义端口（如 7000、7420）可能被运营商封 — 改用 443
手机 WiFi 是否能访问公网 URL？切到 4G/5G 再试一次（排查 WiFi 路由器问题）

启动前可达性检测

桌面端 v3.5.0 起，启动 frpc 前会自动 ping 一次 frps 服务端，不可达直接弹错。

「证书验证失败」 / TLS 错误

公网地址的 HTTPS 证书有问题：过期、域名对不上、或是手机系统不信任的自签证书
通常发生在：换了域名 / 换了 frp tunnel / 反向代理的证书没跟着更新
排查：用手机浏览器打开 https://你的地址/api/v1/ping，看浏览器是否报证书错误；先把证书修好
如果是换了公网地址：手机端「设备」页删除该桌面 → 用新地址重新配对

鉴权类

「鉴权失败，可能 Token 已被吊销」

可能原因：

原因	解决
桌面端「已配对设备」表里手动吊销了本设备	删除设备记录 → 移动端重新配对
多次输错 PIN 触发 IP 锁定 5 分钟	等 5 分钟再试
桌面端清空所有 token（紧急下线）	重新配对
桌面端升级后数据库迁移异常	桌面端「设置 → 远程访问 → 一键安全自检」检查

「PIN 错误或当前没有进行中的配对」

PIN 60 秒过期，回桌面端重新生成
检查输入的 6 位是否全对
多次输错会触发 IP 锁定 5 分钟

配对类

扫码不工作

排查	操作
相机权限	系统设置 → 应用权限 → AICoder → 相机 → 允许
二维码内容	桌面端的"公网 URL"必须先填好，再点「配对新设备」，否则二维码不包含完整信息
二维码亮度	桌面屏幕调亮一点；或拉近距离让摄像头清晰对焦
摄像头被其他 App 占用	关掉别的相机 App 再试

配对成功但收不到 AI 输出

通常是 WebSocket 连不上：

公网 URL 是否包含 wss:// 支持？（浏览器测试 wss://地址/api/v1/sessions/SID/ws）
frps 是否支持 WebSocket 升级？默认支持；如果用 Caddy/Nginx 反代到 frps，需要确认反代规则没拦截 Upgrade 头
手机 → 设备页 → 切换一次桌面（前端会强制重连）

通知类

通知开关开了但收不到

现在的「AI 回复完成提醒」是 App 顶部弹出的横幅，不走系统通知栏，所以和系统通知权限无关。按下面排查：

排查	操作
App 是否在前台	横幅和提示音都只在 App 处于前台时生效；锁屏、切到别的 App 或被系统清掉后收不到（不是 bug）
是不是正看着那个会话	你正在看的那个会话答完不弹横幅（看着别的会话照弹）；想在对话页也有提醒，请打开「回复完成提示音」
「我的」页测试	开启提醒后点「发送测试 banner」，能弹出说明横幅正常
桌面端版本	连 v6.1.0 及更早的桌面端时，按终端输出停顿几秒判断答完，可能偏早或偏晚；把桌面端升级到 v6.1.1 及以上后与电脑端判定一致，聊天模式会话也会提醒

开了提示音却没声音

排查	操作
媒体音量	提示音走手机媒体音量（不是铃声音量），把媒体音量调大
App 内音量	「我的 → 通知」里的音量滑块别拉到 0，点「试听」确认
App 是否在前台	只保证 App 在前台时响

静音 / 勿扰模式下提示音同样会响，介意的话在「我的 → 通知」里关掉即可。

麦克风类

按住说话报「未授予权限」（已经允许过）

Tauri Mobile WebView 在 Android 上需要同时拥有 RECORD_AUDIO 和 MODIFY_AUDIO_SETTINGS 两项权限才能激活麦克风。v0.1.0 已在 AndroidManifest.xml 同时声明这两项；如果仍报错：

系统设置 → 应用权限 → AICoder → 麦克风 → 允许
重启 App
还不行：卸载重装 v0.1.0+ APK（旧的 debug 版本可能缺权限）

录音很短就报「录音太短」

按住时间需要 ≥ 0.3 秒。v0.1.0 已修复一个 React 状态闭包陷阱（之前会立即报"录音太短"）。确认你装的是 v0.1.0+ APK。

对话类

对话页一直是「暂无历史消息」

手机端 v0.9.1 起会在「暂无历史消息」下面直接写明原因，照提示处理即可。常见情况：

原因	解决
桌面端太旧，读不了 Codex 等非 Claude 会话的历史	桌面端升级到 v6.1.2 及以上，手机端升级到 v0.9.0 及以上
会话刚建、还没关联上 CLI 的会话记录	发一条消息，等 AI 开始回答后会自动关联
远程会话所在的主机桌面端没连上	在桌面端把那台远程主机连上
网络问题导致读取失败	检查网络后重新进入会话

拉历史时偶尔失败，已显示的历史会保留，不会被清空；没有历史时终端原文会直接显示出来兜底。

发了消息 AI 没反应，提示「需要登录」

CLI 停在登录页时，这一页没有输入框，发进去的字会被吞掉。手机端会显示「需要登录」提示卡，并在你点发送时先拦一次（输入内容保留）。请在电脑上完成 CLI 登录；或按提示卡上的说明，用「按键」按 Esc 后选设备码登录。登录完成后提示卡会自己消失。需要桌面端 v6.1.2 及以上才能识别。

AI 停下来问我选哪一项，怎么回答

对话页底部会出现「AI 在等你选择」卡片，直接点选项按钮即可；识别不出选项时，用卡片下方的按键条（方向键 / Enter / Esc / Tab）对照终端画面操作。卡片没自动出现时，点快捷条上的「按键」手动调出按键条。选项按钮需要桌面端 v5.8.1 及以上。

点「中断」会不会把 CLI 退掉

不会。「中断」只在 AI 正在回答时出现，点一下只打断当前这一轮，连点几下也不会把 CLI 连同上下文一起退出（v0.7.0 起）。

聊天模式的会话发不出消息 / 一直转圈

聊天模式会话需要桌面端 v5.9.0 及以上、手机端 v0.7.1 及以上才能收发消息；状态条正确显示「聊天模式 · 已连上桌面」需要桌面端 v6.1.0 及以上。两端都升级后再试。

多设备类

一台手机怎么管多个桌面

「设备」页 → 「+ 添加桌面」 → 重复配对流程。每台桌面独立 token，互不影响。

多台手机连同一桌面

桌面端可以配对多台手机，每台独立 token。同一时刻多台手机看同一桌面，所有 PTY 输出都会同时推送到所有连接的手机。

桌面端「已配对设备」表里能看到所有配对过的设备 + 单独吊销。

安全类

手机丢了，怎么紧急下线？

桌面端 → 设置 → 远程访问 → 「紧急下线」按钮：

立即吊销所有已配对设备的 token
关闭 axum 网关
所有连接的手机立即收到「鉴权失败」断开
你自己跑的 frp / cloudflared 等反向代理由你自己关停（与 App 解耦）

之后需要重新配对所有想保留的设备。

公网 URL 是不是不安全？

只要满足以下三条，被攻破概率极低：

强制 HTTPS / WSS（默认开启，HTTP 部署会被自检阻断）
token 是随机 256 位，无法暴力枚举
熔断：失败 10 次/60s 触发 5 分钟 IP 锁定

桌面端「设置 → 远程访问 → 一键安全自检」会扫描以下风险：

是否暴露明文 HTTP
是否有过期 token
是否启用了熔断
frpc 配置文件权限（避免泄露）

安装与升级类

覆盖安装新版时提示签名不一致 / 安装失败

先看你手机上装的是不是 v0.7.0（「我的」页最底部有版本号）：

当前版本	处理
v0.7.0	那一版误用了临时调试签名，与其他各版不一致，只能先卸载再装新版；卸载会清掉已配对的桌面，装好后重新配对
v0.1.0 ~ v0.3.5	同样需要卸载重装一次（一次性）
其他版本（含 v0.7.1）	可直接覆盖安装；仍失败请确认下载的是官方渠道的 APK

「关于」页的版本号和实际装的对不上

较早版本「关于」页里的版本号是写死的（一直显示 v0.1），以「我的」页最底部显示的版本号为准；v0.9.1 起「关于」页已改为显示安装包的真实版本号。

其它

移动端版本号比桌面端小很多，是 Bug 吗？

不是 Bug。移动端与桌面端版本号完全独立，各自迭代各自发版：

桌面端 v6.2.1 = 桌面应用第 6 大版本第 2 小版本的第 1 个修订
移动端 v0.9.2 = 移动伴侣 v0.9 的第 2 个修订

桌面端升级时移动端可能原地不动，移动端发版时桌面端也可能不跟。两条版本线不会合并。

版本号进位规则

自桌面端 v5.0.0 起，版本号每一位满 10 进 1：5.0.9 的下一版是 5.1.0，5.9.9 的下一版是 6.0.0，不会出现 4.55.0 这样的两位数段。

iOS 什么时候发布？

阻塞 macOS 设备 + Apple Developer 账号（$99/年）+ 审核流程。当前优先级低于桌面端核心功能迭代，暂无明确时间表。

我能在 iPad / 平板上装吗？

Android 平板可以，APK 是 universal-release，按 Android 8.0+ 系统都能装；只是 UI 是按手机设计的，平板上会有大量留白。