排障与常见问题

这页按“现象 -> 可能原因 -> 3 步排查”组织，优先解决首次使用中最常见的问题。

1) 启动失败：neocode 命令不存在

现象

• 终端提示 command not found / neocode 不是内部或外部命令

可能原因

• 安装脚本没有执行完成
• 二进制目录没有加入 PATH

3 步排查

1. 运行 neocode version 和 neocode --help。
2. 如果命令不存在，重新执行安装脚本（见 安装与运行）。
3. 重开一个终端会话后再次执行 neocode version。

2) API Key 明明设置了，仍报认证失败

现象

• 启动后请求模型时报 unauthorized、invalid api key 或 provider 认证错误

可能原因

• 只在一个终端会话里设置了环境变量，当前会话没有继承
• selected_provider 对应的环境变量和你实际设置的不一致

3 步排查

1. 用 /provider 确认当前选中的 Provider。
2. 对照 配置指南 的映射表，确认对应环境变量已设置。
3. 关闭并重新打开终端后再次启动 neocode。

3) 切换 Provider / Model 后不生效

现象

• 你已经切换了 Provider 或 Model，但请求仍像在走旧配置

可能原因

• 当前会话还在使用旧上下文状态
• 新模型在当前 Provider 下不可用

3 步排查

1. 在会话中执行 /provider 和 /model 再确认一次当前选择。
2. 执行 /status 查看当前会话状态。
3. 新建会话后重试同一个请求，确认是否恢复正常。

4) 工具调用频繁被拦截或反复弹审批

现象

• 写文件或执行命令时经常弹出权限确认
• 你以为已允许，但还在重复询问

可能原因

• 当前决策是 Ask
• 工具参数变化导致被视为不同请求

3 步排查

1. 阅读 工具与权限 中 Allow / Ask / Deny 决策表。
2. 对稳定、可控的操作选择 Allow，减少重复确认。
3. 若任务风险高或仓库未知，保持 Ask 并逐次确认。

5) Gateway 连不上 / URL Dispatch 失败

现象

• neocode gateway 启动后外部请求仍失败
• url-dispatch 返回连接错误或鉴权错误

可能原因

• Gateway 未就绪或监听地址不匹配
• 本地鉴权 token 不一致
• 请求来源不在允许范围

3 步排查

1. 单独启动 neocode gateway，确认进程已正常运行。
2. 使用默认本地监听地址 127.0.0.1:8080 先验证最小链路。
3. 对照 Gateway 与 URL Dispatch 检查鉴权与来源限制。

6) 对话越长越“跑偏”或质量下降

现象

• 回答开始重复、遗漏上下文、执行效率下降

可能原因

• 会话上下文过长，输入预算不足
• 历史消息噪声过多

3 步排查

1. 先手动执行一次 /compact。
2. 在配置中检查 context.compact.*（见 配置指南）。
3. 对于新任务，建议新建会话，避免历史噪声干扰。

仍未解决怎么办

• 回到 开始使用 重新走最小路径
• Gateway 问题：看 Gateway 使用
• 日常操作问题：看 日常使用