故障排查

本页收集日常使用中最常见的问题。排查时先确认问题发生在哪个入口：桌面客户端、Linux Server、浏览器访问、工作区，还是外部应用。

如果需要定位本机日志路径，先参考 本地日志查询。

安装后找不到命令

macOS 或 Linux 安装后，如果终端提示找不到 ncoder 或 north-coder，先确认 PATH：

export PATH="$HOME/.local/bin:$PATH"
which ncoder
which north-coder

兼容软链 north-coder-server 也可能存在。如果仍找不到，重新执行安装命令，并检查安装脚本输出的安装位置。

Windows 安装器被拦截

如果 Windows SmartScreen 拦截安装器：

1. 确认安装器来源是官方发布地址。
2. 点击 More info。
3. 继续运行安装器。

不要运行来源不明的安装包。

浏览器打不开桌面客户端

从桌面客户端外部应用菜单打开浏览器失败时，检查：

• 桌面客户端是否仍在运行。
• 默认浏览器是否可用。
• 本机防火墙是否拦截端口。
• 如果使用局域网地址，访问设备是否在同一网络。
• 链接中的 token 是否完整。

同一台机器上优先使用 127.0.0.1 或 localhost 地址。

Linux Server 无法远程访问

按下面顺序检查：

1. 服务器进程是否仍在运行。
2. --host 是否允许远程连接。
3. --port 是否和浏览器访问的端口一致。
4. 防火墙或安全组是否放通端口。
5. token 是否正确。
6. 反向代理是否正确转发到服务端口。

如果服务只监听 127.0.0.1，外部机器无法直接访问，需要通过反向代理或 SSH tunnel。

外部应用列表不完整

如果 IDE、终端或文件管理器没有出现在外部应用菜单中：

• 确认应用已经安装。
• 确认应用能从系统正常启动。
• 在外部应用菜单中刷新应用列表。
• 重启 North Coder 后再检查。

Windows 上还要确认应用安装路径是否暴露给系统。

文件或 diff 看起来过时

如果你在外部 IDE 或终端里改了文件，North Coder 里的文件和 diff 可能需要刷新。回到对应视图后刷新状态，再让 Agent 继续读取或修改。

Agent 执行命令失败

先看失败类型：

不要只看最后一行错误。构建和测试命令的关键原因经常出现在更早的日志里。

搜索没有结果

如果搜索项目文件没有结果，确认：

• 当前工作区是否正确。
• 文件是否被 .gitignore 或项目规则排除。
• 关键词是否过窄。
• 文件索引是否需要刷新。

文档站搜索只搜索公开文档内容，不搜索你的本地项目代码。

已知限制

以下是当前版本的已知限制，后续版本会逐步解决：

• 对话中不能切换模型供应商：在同一个会话内，不要从 Anthropic 切换到 OpenAI（或反向切换）。如果需要换供应商，请新建会话。
• Agent 输出时滚动需要加大力度：Agent 正在输出内容时，聊天区域的向上滚动需要更大幅度的滚动操作才能生效。