第 23 章：常见问题排查——出了问题不慌
这一章是排障手册：把各章节的常见问题集中在一起，建议收藏，出问题时回来翻。
预计阅读 15 分钟。
23.1 命令执行不可用 / 被自动禁用
可能原因：Termux 没装、没开外部应用调用、设置里开关没开。
解决（按顺序检查）：
- Termux 里确认
allow-external-apps=true已写入，并执行过termux-reload-settings（见第 2 章 2.6）； - Lyra Code 设置页的「Termux 权限」开关打开。
23.2 文件工具报「路径越界」
原因：你把绝对路径（如 /storage/emulated/0/...）传给了工作区工具。
解决：工作区外的文件改用 global_* 工具；或者先把文件移进工作区；不要传 Termux 私有路径。
23.3 edit_file 提示「匹配数不符」
原因：要替换的文本不唯一，或者文件已经被改过。
解决：重新读一遍文件，改用行号区间或更长的唯一上下文。别盲改重试。
23.4 命令输出被截断/看不全
解决：把输出存到文件再读：命令 > out.txt 2>&1；或缩小查询范围（head / tail / rg 精确匹配）。
23.5 微型服务器 404 / 页面异常
解决：让 AI 看 read_mini_server_logs：
- 404 → 路径不对或文件不存在；
- 认证失败 → 用户名密码不匹配；
- JS 报错 → 脚本有语法/路径问题；
- SPA 刷新 404 → 开
spa_fallback； - 确认服务根目录里真的有你要的文件。
23.6 定时任务没触发
解决：检查任务启停状态、时间/时区/星期设置（1=周一）；手机电源管理/杀后台会影响触发，把 App 加入电池白名单；任务提示词里写清输出位置，方便事后核对。
23.7 邮件发送失败
解决：多数邮箱需要应用专用密码而非登录密码；检查 IMAP/SMTP 端口和加密（SSL/STARTTLS）；重复或不确定的投递不会被自动重试——先确认上次到底发了没有。
23.8 WebDAV / FTP 连不上
解决：先列目录测试可达性（webdav_list / file_transfer_list）；检查协议（https/davs/ftps/sftp）、端口、用户名、被动模式；改过密码后重新列账号拿新 id。
23.9 模型一直报错/转圈
解决：见第 8 章 8.6——检查 Key、模型名、网络、Base URL，四选一多半是它。
23.10 我忘了把权限开在哪
快速索引：
| 权限 | 位置 |
|---|---|
| 存储/通知 | 系统设置 → 应用 → Lyra Code → 权限 |
| 所有文件访问 | 系统设置 → 应用 → Lyra Code → 权限 → 所有文件访问权限 |
| Termux 命令通道 | Lyra Code 设置页 → Termux 权限 |
| Shizuku | Shizuku App 激活 + Lyra Code 设置页授权 |
| 工具开关 | Lyra Code → Agent 工具页 |
23.11 新手 FAQ
Q：AI 会不会把我的聊天记录上传？ A：不会。对话只发给你配置的模型服务商，不经过第三方中转；用量统计也是本地估算。
Q：我把 API Key 发到网上了，怎么办？ A：立刻去服务商后台吊销并重新生成，然后把新 Key 填进 App。
Q：手机上没 Root，能用全部功能吗？ A：能。Root 只是少数系统级操作才需要，日常功能完全不受影响。
本章完 · 下一章：实战工作流——6 个真实场景照着做就学会