CLI 不可用

如果某个 Agent 没显示、无法选择或启动失败，可以按本页排查。多数情况下，你可以先切换到 Aichat CLI 继续使用。

本地 Agent 页面可能会显示“安装”“修复”或“开始会话”：

1. 安装：当前没有检测到这个 Agent。
2. 修复：可能已经安装，但路径、登录、版本或命令识别异常。
3. 开始会话：已经检测到，可以直接使用。

Aichat CLI 不可用

Aichat CLI 是客户端内置默认 Agent。如果它不可用，通常和客户端安装、本地后端或版本有关。

建议处理：

1. 重启客户端。
2. 检查是否提示安装不完整。
3. 检查是否有客户端更新。
4. 从官方入口重新安装最新版。
5. 联系提供方并附上错误截图。

Codex / ChatGPT CLI 没显示

如果你确认本机安装了 Codex / ChatGPT CLI，但客户端没有显示，可以检查：

1. 在终端运行 codex --version 是否正常。
2. 如果新版命令已经变更，确认当前客户端版本是否支持识别。
3. 是否已经完成登录。
4. Codex 或 ChatGPT 命令是否在系统 PATH 中。
5. 重启 Aichat 后是否出现。
6. 当前客户端版本是否支持识别你的安装方式。

如果终端能识别但桌面客户端不能识别，优先使用客户端里的智能识别或修复入口。

PATH 或安装路径问题

很多“已经安装但客户端检测不到”的问题，本质是桌面应用启动时没有继承终端 PATH。

可以尝试：

1. 在终端确认命令可用，例如 codex --version、claude --version、gemini --version。
2. 使用 Aichat 的智能识别或修复入口。
3. 重启 Aichat。
4. 如果是 Windows，确认命令所在目录已经加入系统环境变量。
5. 如果是 macOS，确认 CLI 不是只安装在某个 shell 的临时路径里。

Claude Code 没显示

可以检查：

1. Claude Code 是否安装。
2. 是否已经登录。
3. 在终端运行对应命令是否正常。
4. 当前系统用户是否有权限启动。
5. 客户端是否需要重启后重新检测。

Cursor 不可用

Cursor 能否显示取决于本机安装情况和客户端适配范围。如果不可用，可以先用 Aichat CLI 完成任务。

其他 Agent 不可用

Gemini、Qwen、Goose、OpenCode、OpenClaw、Copilot、Kimi、Hermes、Kiro、Snow、Vibe、Droid、Qoder、CodeBuddy、Auggie 等 Agent 的排查思路类似：

1. 确认该 Agent 已安装。
2. 在终端确认命令能正常运行。
3. 完成首次登录或初始化。
4. 回到 Aichat 使用智能识别或修复入口。
5. 仍失败时，先用 Aichat CLI 完成任务。

启动后立刻失败

如果提示 Agent 在准备完成前退出，常见原因包括：

1. CLI 没有登录。
2. CLI 版本过旧。
3. 系统路径不正确。
4. 当前工作区权限异常。
5. 客户端无法完成初始化握手。

建议先在终端单独运行该 CLI，确认它能正常启动，再回到 Aichat 中重试。