故障排查与常见问题

Agent 无法启动

• 打开终端并手动运行该 agent 的 CLI。如果它在那里也失败，那就是 CLI 本身的认证或安装问题 —— 与 DevAgent 无关。
• 确保该 CLI 位于 DevAgent 能看到的 PATH 上（检查 设置 → 智能体）。
• 试试标签页上的 Restart chip。

Diff 视图看起来不对劲 / 卡住

• 点击 diff 工具栏上的刷新图标 —— DevAgent 会重新读取 worktree。
• 外部的 git 操作（rebase、reset）可能夹在两次刷新之间发生。

worktree 创建失败

• 起始 ref 可能尚未获取。在仓库中打开终端并运行 git fetch origin。
• 目标目录可能已经存在该分支的 worktree —— 删除它或另取一个分支名。

DevAgent CLI 提示 "command not found"

在 设置 → 常规 → DevAgent CLI 下注册该 CLI。在 macOS 上它会向 ~/.local/bin 安装一个 shim；请确保该目录在你 shell 的 PATH 上。

SSH 连上了但远程终端失败

• 确认远程有 Node 且有网络访问权限，以便首次安装中继。
• 在 Linux 上，如果终端始终无法启动，请安装 C/C++ 工具链：make、g++/clang++、python3（参见 SSH worktree）。
• 安装工具后重新连接，以便 DevAgent 能重新安装原生模块。

SSH 对文件可用但 "Download Folder" 不行

文件夹下载需要递归 SFTP 传输。在仅系统 SSH 的连接上，文件下载可能仍然可用。可用终端的 tar/scp 作为替代方案。

"Open in VS Code" 被禁用或仅限 Local

• 使用 SSH worktree（而非 Remote DevAgent Server 的活动运行时）。
• 把 Open-in 命令设置为 VS Code / Insiders，而不是 Cursor 或多参数的 shell 命令。
• 如果主机已被移除，刷新 SSH 目标。

Kerberos 登录失败

• 确保 klist 显示了针对该主机 realm 的有效票据。
• 确认 OpenSSH 配置中该 Host 的 GSSAPIAuthentication yes，然后在 设置 → SSH 中重新导入或重新测试该目标。

浏览器提示 browser_no_tab

当前 worktree 中没有打开的标签页。用 devagent tab create --url ... 打开一个，或手动打开浏览器 窗格 并导航。

性能与内存

• 关闭你没有在积极使用的 worktree。每个 worktree 都会保持文件监视器处于活动状态。
• 带许多浏览器标签页的分屏布局是最大的内存占用者 —— 关掉你不需要的浏览器。

GitHub PR 面板 / 检查 / Tasks 错误

速率限制、错误的 gh 认证、缺失的 scope 以及仓库访问问题都会出现在 Source Control 和 PR Checks 面板中。完整的对照表（包括为何 设置 中的 GitHub API Budget 看起来正常而 REST 仍被阻塞）请参见 排查 GitHub 错误。

快速检查：

gh auth status -h github.com
gh api user
gh api rate_limit --jq '.resources.core'

日志

Help → Open Logs 会打开存放 DevAgent 日志的目录。提交 bug 时请附上这些日志。

报告问题

• Help → Send Feedback（应用内）—— 把截图粘贴或拖入对话框，或选择图片文件；提交前会显示缩略图。当 bug 难以复现时请附上日志。
• GitHub Issues —— bug 和功能请求。
• Discord —— 实时帮助。