에이전트 연결 문제 해결

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은 인증 정보는 유효하지만 요청한 작업에 대한 권한이 없음을 뜻합니다. 넓은 관리자 액세스를 부여하는 대신, 인증 정보나 필요한 권한을 바로잡으세요.

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

다음을 실행합니다.

chorus daemon status
chorus daemon logs
chorus daemon restart

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

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

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

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

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

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

다음을 확인합니다.

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

고정된 연결을 복구하거나 새 대상을 명시적으로 선택하세요. 빠진 대상을 나타나게 하려고 파일 시스템 접근을 넓히지 마세요.

중단이나 재개가 실패한다

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

프로세스가 크래시했다면, 재개하기 전에 부분적인 파일 시스템 변경을 살펴봅니다. 전체 복구 절차는 세션 중단과 재개를 보세요.

유용한 진단 정보 수집하기

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

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

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