에이전트 연결 문제 해결

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

로컬 계정 로그인이나 초대가 실패함

관리형 로컬 계정은 DEFAULT_USER / DEFAULT_PASSWORD 데모 로그인과 다릅니다. 슈퍼 관리자에게 전용 워크스페이스와 첫 관리자 초대를 요청하세요. 이후 사용자와 재설정은 해당 관리자가 관리합니다. 환경 변수나 메일 서비스로 이 기능을 켜는 것은 아닙니다.
사용자 이름 또는 이메일을 입력하고 선택 화면에서 원하는 워크스페이스나 역할을 고르세요. 로컬 계정은 OIDC 워크스페이스에 로그인할 수 없습니다. 일반적인 자격 증명 오류는 잘못된 비밀번호, 없는 계정, 초대 미완료, 비활성화 또는 삭제 모두에서 발생할 수 있으므로 계정 존재 여부를 추론하지 마세요.
로그인 전에 초대를 수락해야 합니다. 초대·재설정 링크는 24시간 동안 유효하고 한 번만 사용할 수 있으며 재발급이나 관련 계정 변경 시 무효화됩니다. 담당 관리자에게 새 링크를 요청하세요. Chorus는 자동 이메일을 보내지 않습니다. 비밀번호 설정 후 별도로 로그인합니다. 비밀번호는 최소 8자, UTF-8 기준 최대 72바이트입니다.
비밀번호 재설정이나 계정 변경 후 오래된 버전의 로컬 세션이 거부될 수 있습니다. 비활성화·삭제된 사용자나 호환되지 않는 워크스페이스 모드는 거부되며 현재 계정 상태를 읽지 못해도 접근을 허용하지 않습니다. 계정 검사를 우회하지 말고 데이터베이스 연결을 복구하세요.
로그인 직후 세션이 사라지면 공개 오리진, 쿠키 설정, 모든 레플리카가 공유하는 영구적인 NEXTAUTH_SECRET을 확인하세요. HTTPS에서는 COOKIE_SECURE=true를 사용하고 false는 신뢰할 수 있는 HTTP 전용 시험 환경에만 사용합니다. Default Auth 변수를 제거해도 관리형 로컬 비밀번호 로그인은 유지됩니다.

인증 설정과 운영 가이드를 참고하세요. 진단 정보에 자격 증명 링크 URL, 토큰, 비밀번호, 쿠키, 서명 키를 포함하지 마세요.

로그인이 429를 반환하거나 레플리카별 제한이 다름

HTTP 429와 RATE_LIMITED는 인증 한도를 초과했다는 뜻입니다. Retry-After의 초만큼 기다린 뒤 다시 시도하세요. 연속 재시도는 복구 방법이 아닙니다. 식별자 조회는 60초당 30회, 로컬 비밀번호 로그인과 초대·재설정 확정은 각각 60초당 10회입니다. 신뢰하는 프록시 주소를 사용하면 같은 주소의 사용자가 작업 한도를 공유할 수 있습니다.

모든 레플리카가 같은 Redis 설정을 사용하는지 확인하세요. 비어 있지 않은 REDIS_URL이 host 기반 TLS 설정보다 우선합니다. REDIS_URL과 REDIS_HOST가 모두 없으면 프로세스 내부 제한입니다. Redis 장애 시 보조 카운터도 프로세스 내부 제한만 유지합니다. auth-throttle과 Redis 로그에서 READONLY/OOM을 포함한 연결·명령 오류를 확인하세요. SSE가 정상이어도 독립된 인증 연결이 정상인 것은 아닙니다. 예상치 못한 제한 백엔드 오류는 허용할 수 있으므로 에지 제한을 유지하세요. Redis 장애는 모든 로그인을 거부하는 fail-closed 정책이 아닙니다.

임의의 클라이언트 헤더가 아닌 실제 강제 적용되는 프록시 체인을 기준으로 AUTH_TRUST_PROXY와 AUTH_TRUST_PROXY_HOPS를 확인하세요. 신뢰할 수 있는 주소가 없거나 잘못되어도 식별자 제한은 유지됩니다. 오류를 없애려고 신뢰를 켜거나 프록시를 우회하는 직접 접근을 허용하지 마세요. 기본값, 시간 제한, 복구 경계는 공유 인증 요청 제한을 참고하세요. 자격 증명이나 원시 요청 헤더 대신 시각과 민감 정보를 제거한 오류 코드를 수집하세요.

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

chorus agents를 실행해 이 컴퓨터에 에이전트가 구성되어 있는지 확인합니다(각 에이전트의 이름, UUID, 백엔드를 나열하며, API 키는 절대 출력하지 않습니다).
의도한 작업 디렉터리에서 chorus daemon을 실행합니다.
선택한 백엔드 CLI가 설치되어 있고 PATH에서 사용 가능한지 확인합니다.
인증 정보가 없거나 잘못되었다면, 올바른 Chorus URL과 에이전트 API 키로 chorus agents add(또는 chorus login)를 실행합니다.
설정 → 에이전트(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-only 위반(Claude Code, Chorus 0.22.2 이상). 세부 정보에 --chorus-only is not being enforced by this Claude Code build가 표시되고 여전히 사용 가능한 도구가 나열된다면, 데몬이 깨우기를 시작할 때 Chorus 허용 목록 밖의 도구를 발견한 것입니다. 데몬은 프로세스 트리를 종료하고 이후 아무것도 전달하지 않았으므로, 그 Claude Code 빌드에서는 제한된 깨우기를 실행할 수 없습니다. 데몬이 안내하는 해결책은 --yolo입니다. 에이전트에 전체 도구를 줄 의도가 있을 때만 전환하고, 그렇지 않으면 --chorus-only를 유지한 채 다른 Claude Code 버전을 시도하세요. --chorus-only가 강제하는 것을 참고하세요.

오류 세부 정보에 포함된 알려진 인증 정보는 [redacted]로 바뀝니다. 다른 텍스트는 가려지지 않으므로 공유하기 전에 검토하세요.

Linux 데몬이 SSH 로그아웃이나 재부팅 후 오프라인이 되면 chorus daemon status와 lingering 설정을 확인하세요. Codex가 구성 후에도 이전 인증 정보를 사용하면 chorus daemon restart만 실행하지 말고 안전한 App Server 재시작을 따르세요.

유용한 진단 정보 수집하기

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

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

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