常见问题
故障排查与高频疑问
Runtime CLI 检测不到
GUI 应用的 PATH 与终端不同是最常见原因：
- 终端里确认
which claude（或对应 CLI）有输出 - 在设置 → Runtime 自定义配置里直接填 CLI 绝对路径
- 重启 Yoda（PATH 规范化在启动时进行）
worktree 创建失败
- 检查仓库是否有未提交的 rebase / merge 状态
- 分支名冲突：清理同名的历史分支，或修改
branchPrefix - 磁盘空间与目录写权限
新 worktree 里agent 跑不起来（缺 .env / 依赖）
这是设计行为——worktree 是干净目录。在仓库根添加 .yoda.json，用 preservePatterns 复制环境文件、用 scripts.setup 装依赖。见 .yoda.json 参考。
SSH 连接问题
先用终端 ssh user@host 验证基础连通性，再检查认证方式（ssh-agent 是否加载密钥：ssh-add -l）。详见 SSH 远程开发。
手机扫码连不上
手机和电脑需在同一局域网；检查防火墙是否放行网关端口；重新生成二维码。见 移动端。
我的代码会被上传吗？
Yoda 是本地优先的：
- 所有数据（任务、会话、设置）存在本地 SQLite
- AI 功能（任务命名、会话摘要）通过你本机的 Runtime CLI 完成，Yoda 自身不调用任何模型 API
- 代码只会经由你配置的 Runtime CLI 发给对应的模型服务商——和你直接在终端用这些 CLI 完全一致
- 遥测可用
TELEMETRY_ENABLED=false关闭
数据存在哪里？怎么备份？
数据库是单个 SQLite 文件，路径可用 YODA_DB_FILE 自定义。备份即复制该文件。
怎么彻底关闭移动网关？
YODA_MOBILE_GATEWAY_DISABLED=1终端显示异常 / 乱码
- 调整设置中的终端字体为支持对应字符的等宽字体
- tmux 包装模式下的渲染问题，可尝试关闭该任务的 tmux
- 回滚行数过大可能影响性能，默认 1000 行