常见问题

模型列表为空或无法发送

到“设置 → 模型”确认连接已配置、模型已添加且启用。自定义模型需要有效的模型 ID 和连接绑定。桌面端使用应用设置中的 Key，仓库 .env 不会替代它。详细步骤见配置模型。

Agent 不读取文件或不修改文件

检查当前模式。Chat 不提供工具，Plan 只读，修改任务需要 Agent 模式。再确认工具开关、审批状态和工作区目录；等待审批时需要先做出允许或拒绝决定。

文件存在却提示找不到

查看会话实际使用的是原目录还是 Worktree。新 Worktree 不会自动复制忽略文件和未提交修改，依赖与本地配置也可能需要重新准备。不要只凭文件名判断两个会话处于相同环境。

命令运行很久没有结果

展开 Bash 状态，确认是后台运行、等待审批还是已经失败。要求 Agent 读取后台输出，检查是否在等待输入；交互式程序可以改为你在终端中操作。停止不会撤销已有改动。

上下文占用和总 Token 不一致

上下文表示单次请求内容，总 Token 累计多次请求消耗。旧请求缺少容量信息时可能显示 0；未知费用也不代表免费。分别查看上下文和使用统计中的详细记录。

搜索、图片或浏览器不可用

这些能力可能需要独立连接。检查搜索 Key、图片分析模型或图片生成服务；Browser Use 还需要扩展、Native Host 和 Chrome 连通。只连接对话模型不能保证所有工具就绪。

报告问题时提供什么

提供应用版本或源码 commit、操作步骤、实际错误、预期结果，以及能复现问题的最小示例。源码启动可用 pnpm dev:log，日志入口是 logs/latest-dev.log。

只截取相关日志片段，隐藏 Key、个人目录和不相关的会话内容。不要附带整个应用数据目录或 secrets.json。涉及界面时，一张包含操作入口和错误状态的截图通常比单独截取报错文字更有帮助。