排障与常见问题
这页按“现象 -> 可能原因 -> 怎么处理”组织，优先覆盖日常使用最常见的问题。
1) neocode 命令不存在
现象
- 终端提示
command not found - Windows 提示
neocode 不是内部或外部命令
可能原因
- 安装没有完成
- 安装目录没有加入
PATH - 当前终端还没加载新的环境变量
怎么处理
- 重新执行 安装与首次运行 中的安装命令。
- 关闭并重新打开终端。
- 执行
neocode version确认命令可用。
2) API Key 明明设置了，仍然认证失败
现象
- 模型请求返回
unauthorized、invalid api key或类似认证错误
可能原因
- API Key 只设置在另一个终端会话里
- 当前选中的 Provider 和你设置的环境变量不匹配
- Key 已失效或没有目标模型权限
怎么处理
- 用
/provider确认当前 Provider。 - 对照 配置指南 里的环境变量表，确认变量名正确。
- 在启动 NeoCode 的同一个终端里重新设置环境变量，然后重启 NeoCode。
3) 切换 Provider 或模型后不生效
现象
- 已经切换了 Provider 或模型，但回答看起来仍像旧模型
- 模型列表为空或选择后请求失败
可能原因
- 当前会话里仍有旧任务上下文
- 新 Provider 的 API Key 没有设置
- 目标模型在当前账号下不可用
怎么处理
- 执行
/provider和/model，确认当前选择。 - 执行
/compact，减少旧上下文影响。 - 新建会话后再试一次同样的问题。
4) 工具调用频繁弹权限确认
现象
- 写文件或执行命令时总是弹出确认
- 以为已经允许，但后续仍然询问
可能原因
- 当前会话尚未对相似请求选择
Allow session - 工具参数变化，被视为新的操作
- 操作风险较高，需要再次确认
怎么处理
- 对稳定、可信的重复操作选择
Allow session。 - 对未知仓库或高风险命令逐次确认；只对明确安全的单次请求选择
Allow once。 - 路径、命令或影响范围不符合预期时选择
Reject。 - 不确定时让 Agent 先解释它要执行的命令和影响范围。
更多说明见 工具与权限。
5) 长会话开始跑偏
现象
- 回复开始重复
- 忘记刚才的要求
- 对新任务仍引用旧任务上下文
可能原因
- 当前会话太长
- 历史消息噪声太多
- 当前任务和旧任务关系不大
怎么处理
- 先执行
/compact。 - 如果仍然跑偏，新建会话。
- 对不相关的新任务，直接新建会话并重新说明目标。
6) MCP 工具不可用
现象
- Agent 看不到你配置的 MCP 工具
- 工具能看到但调用失败
可能原因
- MCP server 没启用
- 启动命令、工作目录或环境变量写错
- 工具参数不符合 MCP server 要求
怎么处理
- 确认
enabled: true。 - 在同一个终端里确认所需环境变量已设置。
- 按 MCP 工具接入 的验证步骤，让 Agent 先列出工具，再做一次简单调用。
7) 外部集成连不上
如果你在做脚本、浏览器插件或其他外部集成，问题通常和本地服务是否启动、监听地址或认证配置有关。
普通对话使用不需要处理这些内容。需要做外部集成时，请从 Gateway 集成参考 进入相关设计文档。