先从 Chorus 中可见的症状入手。排查时尽可能在前台运行后台服务，因为启动错误在前台更容易看到。

## 智能体一直不上线

1. 运行 `chorus agents`，确认该智能体已在本机配置（它会列出每个智能体的名称、UUID 和运行后端；绝不会打印 API 密钥）。
2. 在预期的工作目录中运行 `chorus daemon`。
3. 确认所选运行后端的 CLI 已安装，并且可以在 `PATH` 中找到。
4. 如果凭据缺失或有误，运行 `chorus agents add`（或 `chorus login`），填入正确的 Chorus 网址和智能体 API 密钥。
5. 打开**设置 → 智能体**，检查是否出现新的**在线**心跳。

HTTP `401` 通常表示密钥无效或已撤销。HTTP `403` 表示凭据有效，但缺少执行当前操作所需的权限。请修正凭据或补上所需权限，不要为此授予宽泛的管理员访问权限。

## 服务已停止或反复重启

运行：

```sh
chorus daemon status
chorus daemon logs
chorus daemon restart
```

如果服务的 `PATH` 中找不到智能体 CLI，请修复安装，然后带上预期的运行后端和工作目录重新运行 `chorus daemon install`。在 Linux 上，请使用 Chorus 生成的服务，不要再同时使用 `-d` 后台分离模式。

## Chorus 显示的工作目录不对

停止后台服务，并用预期的路径启动它：

```sh
chorus daemon --cwd /path/to/your/project --chorus-only
```

有多个项目时，重复使用 `--cwd`。如果你修改的是已安装的服务，请用完整的目标目录列表重新安装它。然后在**设置 → 智能体**中确认每个预期路径都出现在该连接下。

## 发起远程工作后没有反应

请检查：

- 所选连接仍处于**在线**状态；
- 项目或任务没有固定到另一个已离线的连接；
- 工作目录已由后台服务注册；
- 智能体有权读取该条目并执行所请求的操作。

请恢复已固定的连接，或明确选择一个新目标。不要仅仅为了让缺失的目标出现而扩大文件系统访问范围。

## 无法打断或恢复

打开对话，检查它的当前状态是否允许你请求的打断或恢复。持有该会话的后台服务必须在线。恢复始终回到原来的连接和工作目录。

如果进程崩溃了，恢复之前请检查文件系统中已产生的部分修改。完整的恢复步骤见[中断与恢复会话](/zh/guides/session-recovery/)。

## 智能体尚未回复，回合就失败了

打开失败的对话回合，阅读 **Agent 唤醒失败**摘要；有详情时选择**展开错误详情**。没有回复不代表没有记录诊断，重试前先看[失败回合诊断](/zh/guides/session-recovery/#查看失败回合的诊断信息)。

若 Linux 后台服务在 SSH 退出或重启后离线，请检查 `chorus daemon status` 和[用户驻留设置](/zh/guides/daemon-operations/#退出登录后继续运行-linux-后台服务)。若 Codex 配置后仍用旧凭据，请按 [App Server 安全重启流程](/zh/reference/agents/codex/#让已有-app-server-使用新配置)操作，而不只是运行 `chorus daemon restart`。

## 收集有用的诊断信息

在受限的前台模式下复现一次问题：

```sh
chorus daemon --verbose --chorus-only --cwd /path/to/your/project
```

记录失败的步骤、时间、运行后端、状态信息和相关日志行。绝不要分享 API 密钥。删除与问题无关的私有网址、用户名、仓库路径、提示词和命令输出。