Chorus에서 보이는 증상부터 시작하세요. 가능하면 진단하는 동안 데몬을 포그라운드에서 실행하세요. 시작 시 발생하는 오류를 더 쉽게 확인할 수 있기 때문입니다.

## 에이전트가 온라인이 되지 않는다

1. `chorus agents`를 실행해 이 컴퓨터에 에이전트가 구성되어 있는지 확인합니다(각 에이전트의 이름, UUID, 백엔드를 나열하며, API 키는 절대 출력하지 않습니다).
2. 의도한 작업 디렉터리에서 `chorus daemon`을 실행합니다.
3. 선택한 백엔드 CLI가 설치되어 있고 `PATH`에서 사용 가능한지 확인합니다.
4. 인증 정보가 없거나 잘못되었다면, 올바른 Chorus URL과 에이전트 API 키로 `chorus agents add`(또는 `chorus login`)를 실행합니다.
5. **설정 → 에이전트**(Settings → Agents)를 열고 **온라인**(Online) 하트비트가 새로 들어오는지 확인합니다.

HTTP `401`은 대개 키가 무효이거나 폐기되었음을 뜻합니다. HTTP `403`은 인증 정보는 유효하지만 요청한 작업에 대한 권한이 없음을 뜻합니다. 광범위한 관리자 액세스를 부여하지 말고, 인증 정보나 필요한 권한을 바로잡으세요.

## 서비스가 멈추거나 계속 재시작된다

다음을 실행합니다.

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

에이전트 CLI가 서비스의 `PATH`에 없으면, 설치를 고치고 의도한 백엔드와 작업 디렉터리로 `chorus daemon install`을 다시 실행합니다. Linux에서는 Chorus가 생성한 서비스를 사용하고, 분리(`-d`) 모드와 함께 쓰지 마세요.

## Chorus가 잘못된 작업 디렉터리를 표시한다

데몬을 멈추고 의도한 경로로 다시 시작합니다.

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

프로젝트가 여러 개라면 `--cwd`를 반복합니다. 설치된 서비스를 바꿨다면, 원하는 전체 목록으로 다시 설치합니다. 그런 다음 기대하는 모든 경로가 **설정 → 에이전트**(Settings → Agents)의 연결 아래에 나타나는지 확인합니다.

## 원격 작업을 시작해도 아무 일도 일어나지 않는다

다음을 확인합니다.

- 선택한 연결이 아직 **온라인**(Online)인지.
- 프로젝트나 작업이 다른 오프라인 연결에 고정되어 있지 않은지.
- 작업 디렉터리가 데몬에 등록되어 있는지.
- 에이전트가 그 항목을 읽고 요청된 액션을 수행할 권한이 있는지.

고정된 연결을 복구하거나 새 대상을 명시적으로 선택하세요. 보이지 않는 대상을 나타나게 하려는 목적만으로 파일 시스템 접근 범위를 넓히지 마세요.

## 중단이나 재개가 실패한다

대화를 열고, 대화의 현재 상태에서 요청한 중단이나 재개가 가능한지 확인합니다. 그 세션을 소유한 데몬이 온라인이어야 합니다. 재개는 항상 원래의 연결과 작업 디렉터리로 돌아갑니다.

프로세스가 비정상 종료되었다면, 재개하기 전에 일부만 반영된 파일 시스템 변경 사항을 살펴봅니다. 전체 복구 절차는 [세션 중단과 재개](/ko/guides/session-recovery/)를 보세요.

## 응답 전에 턴이 실패함

실패한 대화 턴에서 **에이전트 시작 또는 실행 실패** 요약을 읽고 제공되면 **오류 세부 정보 펼치기**를 선택하세요. 응답이 없어도 진단이 기록될 수 있습니다. 재시도 전에 [실패한 턴 진단](/ko/guides/session-recovery/#실패한-턴의-진단-읽기)을 확인하세요.

Linux 데몬이 SSH 로그아웃이나 재부팅 후 오프라인이 되면 `chorus daemon status`와 [lingering 설정](/ko/guides/daemon-operations/#로그아웃-후에도-linux-데몬-유지)을 확인하세요. Codex가 구성 후에도 이전 인증 정보를 사용하면 `chorus daemon restart`만 실행하지 말고 [안전한 App Server 재시작](/ko/reference/agents/codex/#실행-중인-app-server에-구성-적용)을 따르세요.

## 유용한 진단 정보 수집하기

제한된 포그라운드 모드에서 문제를 한 번 재현합니다.

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

실패한 단계, 시각, 백엔드, 상태 메시지, 관련 로그 줄을 기록합니다. API 키는 절대 공유하지 마세요. 비공개 URL, 사용자 이름, 저장소 경로, 프롬프트, 그리고 문제와 무관한 명령 출력을 제거하세요.