常见问题与故障排查 — Noea Code 文档

遇到问题时，先看当前操作的具体提示，再检查项目、Agent 和任务状态。以下按常见现象列出处理入口。

一直无法进入工作台

首次引导要求至少一个 Agent 已安装、已登录并通过验证。只有安装完成或登录窗口关闭还不够，需要清单显示“就绪”。

打开该 Agent 的详情面板，按提示处理登录、网络或验证问题，再次检查。步骤见安装与准备。

先检查网络及系统 HTTP(S) 代理。环境变量配置的代理优先，SOCKS 代理不在当前支持范围内。下载停止接收数据时会显示“正在准备”，可以继续观察状态；出现失败提示后使用重试。

如果反复失败，复制 Agent 的诊断信息，并记录失败发生在下载运行环境、安装 Agent 还是验证连接的阶段。

Noea 以验证结果判断 Agent 是否可用。检查登录的账号或供应商是否正确，额度是否可用，以及模型配置是否有效。OpenCode 用户可以刷新供应商列表，确认连接后重新验证。

如果模型显示“连接后可选”，先建立会话再检查。Agent 不支持某项配置时，不会因为在其他 Agent 中可用而自动获得同样能力。

提示或情况	处理方式
选择的文件夹不是 Noea 项目	代码目录请用“打开实现文件夹”；已有项目请选它的项目目录
项目目录被移动	从“打开现有 Noea 项目”重新选择当前位置
项目目录被删除	先从废纸篓、回收站或备份恢复，再重新打开
配置无效	保留原内容，检查配置或提交诊断，不要直接覆盖初始化
数据来自更新版本	更新应用后再打开
数据版本不兼容	先保留项目和应用数据副本，再按具体提示处理；不兼容数据不要直接覆盖

到“设置 → 当前项目 → 项目”检查实现文件夹。未关联时先关联；原目录不可访问时，重新定位原代码目录。

同时检查 Agent 是否就绪。意图文件可以读取，不表示实现目录和 Agent 都已准备好。

先保存意图，然后对相关段落执行“调查”，或从侧栏运行“解释”。需要修改实现的要求，可以先通过对话实现，再调查。

“先前文字”表示说明针对改前的意图；“可能已过时”表示其依据文件后来变化。两者都需要结合当前内容重新检查，详见让说明跟上变化。

侧栏的“未发现更改”不代表所有测试通过，也不代表当前项目不存在缺口。

检查“设置 → 当前项目 → 自动化 → 实现后自动解释”。普通对话仅改代码、选择“直接实现”、实现失败或被停止，都不会自动触发解释。

需要更新说明时，手动点击“解释”。任务已结束但仍有检查失败或未完成的内容时，展开结果，处理原因后再次运行。完整触发规则见让说明跟上变化。

提议提示文档已经变化时，点击“请智能体基于当前版本重新提议”。整理方案提示过期时，使用“重新整理”。

普通提议可以编辑新增和替换后的文字，但不支持逐处或逐文件接受。整理稿的正文只读，可以选择保留建议删除的内容，再接受整份方案。

界面说明“消息未交给智能体”时，可以重试发送。如果提示消息可能已送达，先检查执行轨迹和文件是否已经变化，避免重复执行。

Agent 已收到消息但处理途中停止时，发送一条新的继续指令，让它先检查当前状态。提议实现卡片显示“实现未完成”时，可以使用“继续实现”。

编辑消息、分叉对话和停止运行都不会回滚已经修改的文件。

MCP 先使用“测试连接”，按结果检查命令、地址、授权和环境变量。测试成功后，还要确认当前对话选择了它，以及当前 Agent 支持该连接方式。

修改 MCP 配置后，需要重新连接 Agent；新增或删除 Skill 后，需要新建对话。解释和整理任务不使用这些扩展，详细设置见添加 MCP 与 Skill。

保存冲突表示磁盘文件在你编辑期间被其他操作修改过。可以另存当前内容，或重新载入磁盘版本；重新载入会放弃未保存编辑。

引用打不开时，检查文件或材料是否仍存在、实现目录是否可访问。旧说明不再匹配当前文档时，回到对应段落查看最新说明，必要时重新调查。

通过侧栏“反馈”描述你要完成的操作、实际结果和出现问题的步骤。留下邮箱便于后续沟通，也可以联系 [email protected]。

需要补充诊断时，到“设置 → 关于”导出诊断信息，或在 Agent 的详情面板复制诊断。诊断可能包含本机状态和日志，发送前先查看内容。主动反馈不会自动附带这些文件。