常见问题
❓ 常见问题解答
这里汇总了使用 VibeTerminal 时的常见问题和解决方案。
🔧 安装和配置
Q: 支持哪些 Android 版本？
A: VibeTerminal 支持 Android 8.0 (API 26) 及以上版本。建议使用 Android 10+ 以获得最佳体验。
Q: 为什么推荐使用 Tailscale？
A: Tailscale 提供了多项优势：
- 🔐 安全：端到端加密的 WireGuard 隧道
- 🌐 便捷：自动穿透 NAT，无需配置端口转发
- ⚡ 快速：点对点直连，延迟低
- 🎯 稳定：IP 地址固定，不会变化
当然，你也可以使用其他 VPN 方案或直接通过公网 IP + 端口转发连接。
Q: 可以同时连接多个服务器吗？
A: 可以！VibeTerminal 支持配置多个 SSH 服务器，并为每个服务器创建多个项目。
📱 项目管理
Q: One Project = One Session 是什么意思？
A: 每个项目对应一个独立的 Zellij 会话，这意味着：
- 每个项目有自己的终端面板、编辑器状态
- 项目之间完全隔离，互不干扰
- 可以在项目间快速切换，状态保持不变
Q: 如何删除项目？
A: 长按项目卡片，选择"删除项目"。注意：这只会从 App 中移除项目配置，不会删除服务器上的文件或 Zellij 会话。
Q: 可以重命名项目吗？
A: 可以。点击项目卡片右上角的菜单图标，选择"编辑项目"，即可修改项目名称和路径。
💬 对话历史
Q: 支持哪些 AI 编程助手？
A: 目前支持：
- ✅ Claude Code（官方）
- ✅ OpenCode（开源替代）
- ✅ Codex（OpenAI）
VibeTerminal 会自动检测并解析这些工具的对话 JSON 文件。
Q: 对话历史存储在哪里？
A: 对话历史分两部分：
- 服务器端：原始 JSON 文件在
~/.claude/等目录 - 手机端：App 会缓存解析后的对话数据，存储在加密的本地数据库
Q: 对话历史不显示或不更新？
A: 尝试以下步骤：
- 下拉刷新对话列表
- 点击右上角的"刷新"按钮强制重新加载
- 检查服务器上是否有
~/.claude/目录和 JSON 文件 - 确保 SSH 连接正常
Q: 可以搜索历史对话吗？
A: 可以！点击搜索图标，输入关键词，App 会进行全文检索，支持跨会话搜索。搜索结果会高亮显示，点击可直接跳转。
🔔 推送通知
Q: 推送通知是如何工作的？
A: VibeTerminal 在手机上运行一个轻量级的 Webhook HTTP 服务器。当 Claude Code 完成任务或需要输入时，通过 curl 向手机发送 POST 请求，触发推送通知。
Q: 推送通知不工作，如何排查？
A: 按以下顺序检查：
手机端：
- 确保通知权限已授予
- Webhook 服务器已在设置中启用
- 查看 Webhook 配置对话框中显示的 IP 和令牌
服务器端：
- 检查
~/.claude/settings.json配置是否正确 - 确认 IP 和令牌与手机显示的一致
- 测试连接：
curl -X POST 'http://<phone-ip>:8765/notify' -H 'Authorization: Bearer <token>' -d '{"event":"test","project":"test"}'
- 检查
网络：
- 确保手机和服务器在同一 Tailscale 网络
- 运行
tailscale status检查双方是否在线
Q: 推送通知有延迟吗？
A: 正常情况下延迟在 1-2 秒内。如果延迟较大，检查：
- Tailscale 是否正常连接
- 网络质量是否稳定
- 手机是否处于省电模式（可能限制后台网络）
Q: 支持其他通知方式吗？
A: 目前仅支持 Webhook 推送。未来可能会添加：
- Telegram Bot 通知
- 企业微信通知
- 邮件通知
欢迎在 GitHub 提 Issue 反馈需求！
🔄 连接和会话
Q: SSH 连接断开后会发生什么？
A: 不用担心！Zellij 会话仍在服务器上运行：
- Claude Code 的任务继续执行
- 终端输出被保存
- 重新连接后可以继续查看
这是 Zellij 会话持久化的优势，非常适合移动场景。
Q: 如何手动重连？
A: 点击项目卡片右上角的连接状态指示器，或在终端界面点击顶部的连接按钮。
Q: 支持多设备同时连接同一个项目吗？
A: 可以，但需要注意：
- Zellij 支持多客户端连接同一会话
- 所有客户端会看到相同的终端输出
- 输入会被所有客户端共享（可能导致冲突）
建议：用手机查看输出，用电脑进行主要操作，避免冲突。
⚡ 性能和体验
Q: 对话历史很长时，App 会卡顿吗？
A: 不会。VibeTerminal 使用了多项优化：
- LazyColumn 虚拟化滚动（只渲染可见部分）
- 增量加载（分批加载历史记录）
- 本地缓存（减少网络请求）
- 后台同步（不阻塞 UI）
即使有数千条对话，滚动依然流畅。
Q: 横屏和竖屏有什么区别？
A:
| 特性 | 竖屏模式 | 横屏模式 |
|---|---|---|
| 终端视图 | 标准 | 更宽敞 |
| Minimap | 无 | 有（右侧导航） |
| 输入框 | 底部 | 底部 |
| 适用场景 | 查看对话、浏览 | 终端操作、阅读代码 |
Q: 支持平板吗？
A: 支持！在平板上体验更好：
- 更大的屏幕查看代码
- 横屏模式下可同时看到更多内容
- Minimap 导航更实用
🔐 安全和隐私
Q: 我的代码和密钥安全吗？
A: 是的，VibeTerminal 采用多项安全措施：
- 🔐 SSH 密钥：加密存储在 Android Keystore
- 🔐 本地数据库：使用 SQLCipher 加密
- 🔐 网络传输：通过 SSH 或 Tailscale 加密
- ❌ 不上传云端：所有数据仅在本地和你的服务器之间传输
Q: 会收集我的使用数据吗？
A: 不会。VibeTerminal 是开源项目，不包含任何数据收集代码。你可以在 GitHub 上审查源码。
Q: 可以自己编译 APK 吗？
A: 当然可以！项目完全开源：
git clone https://github.com/yourusername/VibeTerminal
cd VibeTerminal
./gradlew assembleRelease编译后的 APK 位于 app/build/outputs/apk/release/。
🐛 故障排除
Q: App 崩溃或闪退
A: 尝试：
- 清除 App 缓存（设置 → 应用 → VibeTerminal → 清除缓存）
- 重启 App
- 重启手机
- 重新安装（会保留 SSH 配置，但请先备份）
如果问题持续，请在 GitHub 提 Issue，附上崩溃日志。
Q: 如何导出日志？
A: 在设置页面点击"导出日志"，日志会保存到下载目录。提 Issue 时附上日志有助于快速定位问题。
Q: 遇到 Bug 如何反馈？
A: 欢迎在 GitHub 提 Issue！请包含：
- App 版本号
- Android 版本
- 复现步骤
- 预期行为 vs 实际行为
- 日志文件（如果有）
💡 其他问题
Q: 有使用教程视频吗？
A: 目前暂时没有。如果你愿意制作教程视频，欢迎联系我们！
Q: 支持其他终端复用器吗（如 tmux）？
A: 目前仅支持 Zellij。未来可能会添加 tmux 支持，但 Zellij 的现代化设计和更好的布局系统使其成为首选。
Q: 可以贡献代码吗？
A: 非常欢迎！VibeTerminal 是开源项目，欢迎提交 PR：
- 修复 Bug
- 添加新功能
- 改进文档
- 优化性能
请先查看 CONTRIBUTING.md 了解贡献指南。
Q: 未来有哪些计划？
A: 路线图包括：
- 📊 更智能的对话解析
- 🎨 更多主题和配色方案
- 🔍 更强大的搜索功能
- 📱 iPad 适配优化
- 🤖 更多 AI 助手支持
关注 GitHub 仓库了解最新进展！