# 故障排查与卸载

> 解决 nsq 的常见问题——nsq doctor、终端模块（node-pty、ConPTY）、依赖 curl 的钩子、密钥库——以及如何干净地卸载 nsq。

Source: https://docs.neurosquad.ai/zh/cli/troubleshooting

## 先运行 `nsq doctor`

```sh
nsq doctor
```

它会打印 nsq 和 Node 的版本、数据文件夹、守护进程是否在运行、每个智能体 CLI 的位置、`curl` 和终端模块是否正常、是否有 OpenRouter 密钥，以及你的终端和尺寸。提交问题报告时请附上它的输出。

守护进程日志位于 `~/.neurosquad-cli/daemon.log`。

## 智能体显示「not found」

nsq 从你的 `PATH` 以及常见的安装文件夹中启动 CLI（在 Windows 上还会读取注册表中当前的 `PATH`，所以刚安装一分钟的 CLI 也能找到）。确认 `claude`、`codex` 或 `opencode` 在你的终端里能运行；`nsq doctor` 会显示 nsq 找到了什么。如果 CLI 安装在不常见的位置，先运行 `nsq down`，再从能运行该 CLI 的终端重新启动 nsq（正在运行的智能体会继续原会话）。

## 状态一直不变，或者「需要你」从不出现

Claude Code 和 Codex 通过 `curl` 上报状态。如果 `nsq doctor` 显示 `curl MISSING`，请安装 curl（Windows 10 及更新版本、macOS 和大多数 Linux 发行版都自带）。普通命令（`nsq run -- …`）没有钩子，永远不会显示「需要你」。

## 终端模块无法加载（node-pty）

nsq 用 node-pty 驱动终端，它已为每个受支持的平台预编译——安装时无需编译任何东西。如果 `nsq doctor` 显示 `node-pty FAILED`：

- 确认 `node --version` 为 22.13 或更新版本，切换 Node 版本后请重新安装 nsq（`npm install -g neurosquad`）；
- 确认这次安装没有禁用安装脚本（`--ignore-scripts`）；
- 在 Windows 上，nsq 使用 ConPTY，即 Windows 伪控制台（需要 Windows 10 1809 或更新版本）。仪表盘在 Windows Terminal 中效果最好；旧式控制台窗口也能用，但显示效果较差。

## 字符乱码、颜色不对或标志显示异常

你的终端可能不支持 nsq 检测到的功能。试试 `NSQ_GLYPHS=ascii`、`NSQ_COLOR=256` 或 `NSQ_LOGOS=glyphs`（或 `none`）；如果在 CJK 环境中边框错位，试试 `NSQ_AMBIGUOUS_WIDE=1`。见[配置](https://docs.neurosquad.ai/zh/cli/configuration)。

## 收不到通知

见[通知](https://docs.neurosquad.ai/zh/cli/notifications)：在 macOS 上安装 `terminal-notifier`，或允许「脚本编辑器」发送通知；在 Linux 上，桌面需要运行通知服务。通过 SSH 时请保持仪表盘打开——它会让终端发出提醒。

## OpenRouter 密钥没有保存下来

密钥保存在操作系统的密钥库中。在 Linux 上这需要 Secret Service（GNOME Keyring、KWallet），而服务器上通常没有；请改为在启动守护进程的环境中设置 `OPENROUTER_API_KEY`。

## 卸载

```sh
nsq down                          # 停止守护进程及其智能体
nsq openrouter clear-key          # 从密钥库中删除 OpenRouter 密钥
nsq logout                        # 仅当你登录过账号时
npm uninstall -g neurosquad
```

然后删除 `~/.neurosquad-cli`（或你的 `NSQ_HOME`）——其中有智能体列表、设置、日志、语音输入模型以及智能体的 worktree，所以请先检查 `worktrees/` 里有没有你想保留的工作。nsq 创建的分支（`nsq/<名称>`）会留在你的仓库中，直到你用 git 删除它们。你的智能体 CLI 及其自身设置从未被改动。