에이전트 진단
이 가이드에서는 에이전트가 실행을 만들어 내지 않는 이유를 찾는 방법을 설명합니다.
위에서 아래로 살펴보세요. 먼저 에이전트 자체의 실행, 다음으로 그 백엔드, 그다음으로 서버, 마지막으로 호스트입니다.
1. 에이전트의 실행 기록 확인
섹션 제목: “1. 에이전트의 실행 기록 확인”설정 → 워크스페이스 → 에이전트 → 에이전트 선택 → 로그.
각 실행에는 상태 배지, 소요 시간(진행 중일 때는 “Running…”), 시작 및 완료 시각, PID, 사용한 어댑터가 표시됩니다. 보기는 그 실행의 원시 이벤트 스트림을 엽니다. 중지는 실행 중인 프로세스를 종료하고 그 실행을 “Killed by user”로 표시합니다. 헤더의 실행 중 강제 종료는 그 에이전트의 진행 중인 모든 실행에 같은 일을 합니다.
다음과 같이 읽으면 됩니다:
- 실행이 전혀 없음 — 디스패치가 일어나지 않은 것입니다. 컴포저 멘션은
@에 단어 문자(영문자, 숫자, 밑줄)를 붙인 형태입니다. 해석은 에이전트 이름에 대한 정확 일치 또는 접두사 일치이므로,@code-reviewer는code로 파싱되며code-reviewer라는 이름의 에이전트를 여전히 깨울 수 있습니다. 공백이 든 이름은 하나의 토큰으로 멘션할 수 없습니다. 그런 다음 2단계로 넘어갑니다. - 오류로 즉시 끝난 실행 — 보기를 엽니다. 백엔드 실행 실패가 여기에는 프로세스 오류로 나타납니다.
- “Running…“에 멈춘 실행 — 중지한 다음 설정 탭에서 에이전트의 무응답 제한 시간을 확인합니다. 설정하지 않은 제한 시간은 모드별 기본값을 사용합니다.
- 유용한 출력 없이 완료된 실행 — 선언한 산출물 없이 끝난 실행도 실행 로그의
상태는
completed로 남습니다. 정직한 신호는 배지가 아니라 요약 텍스트입니다.
로그 탭에는 비용이 표시되지 않습니다. 지출은 옵저버빌리티 → 인사이트의 에이전트별 표를 사용하세요.
2. 에이전트의 백엔드 확인
섹션 제목: “2. 에이전트의 백엔드 확인”설정 → 서버 → 모델 제공업체 (/settings/server/providers).
감지된 러너 목록에는 프로브 결과(설치된 버전, “확인 중…”, “찾을 수 없음” 중 하나)와 함께 해석된 경로, CLI가 발견된 경우 그 기능 칩이 어댑터마다 표시됩니다. 페이지 헤더의 새로 고침을 눌러 다시 프로브하세요.
프로브는 지금 보고 있는 머신이 아니라 cc_server를 호스팅하는 머신에서
실행됩니다. 웹 클라이언트나 페어링한 기기를 사용 중이라면 “찾을 수 없음”은 서버
호스트에 CLI가 없다는 뜻입니다.
확인할 두 가지:
- 에이전트에 어댑터가 설정되어 있는지. 어댑터가 비어 있는 에이전트는
**Control Center (built-in)**으로 디스패치되고 실행 로그에
cc-harness가 기록되므로, 트랜스크립트에 무엇이 실행되었는지 남습니다. 모델도 없으면 Anthropic에 기본 모델을 요청하며, Anthropic 계정을 연결하지 않았다면No credential for provider "anthropic"오류로 실패합니다. 시드되는 전문가 에이전트는 어댑터 없이 제공됩니다. - 내장 어댑터에 모델이 있는지. 그 모델 목록은 바로 이 페이지의 아래쪽에서 연결한 제공업체에서 실시간으로 옵니다. 따라서 저장된 자격 증명이 없는 제공업체는 모델을 하나도 제공하지 않습니다.
어댑터 카탈로그 자체는 고정되어 있습니다. 새 어댑터를 등록할 방법은 없습니다. 여기서 어댑터별로 바꿀 수 있는 것은 실행 인수와 환경 변수입니다. 자격 증명을 해석할 때 어댑터별 환경 재정의가 연결된 제공업체 계정을 조용히 앞지른다는 점을 기억하세요.
3. 서버 확인
섹션 제목: “3. 서버 확인”설정 → 서버 → 연결 및 상태 (/settings/server/connection)에는 이 클라이언트가
어느 서버와 통신하는지, 그 서버가 무엇을 보고하는지 표시됩니다.
헤드리스 서버라면 GET /healthz가 클라이언트 없이 같은 정보를 제공합니다. 이
엔드포인트는 설계상 인증이 필요 없고 CORS에 열려 있습니다:
curl http://localhost:9030/healthz서버의 상태, 초 단위 가동 시간, 활성 연결 수, 바인드된 포트, 빌드 버전과 git SHA,
워크스페이스 스키마 버전, RPC 카탈로그 버전, 서버 id, 이름과 아이덴티티 지문,
바인드의 비보안 여부, 그리고 watching / indexing / pending 개수를 담은
codeGraph 블록을 반환합니다. 캐시가 트래픽을 처리한 적이 있으면 caches 블록도
포함하며, 데모 서버는 demo: true를 덧붙입니다.
변경이 “테스트에서는 되는데 앱에서는 안 될” 때 알아 둘 만한 두 가지:
- 데스크톱은 소스보다 사전 빌드된
cc_server바이너리를 우선 실행합니다. 새 RPC op나 MCP 도구는 바이너리를 다시 빌드할 때까지 나타나지 않으며, 자식의 git SHA가 앱의 것과 다르면 부팅 로그가 경고를 남깁니다. - 데스크톱은 20초 안에 준비 배너를 출력하지 않은 스폰한 서버를 종료하고 오류 화면으로 전환합니다.
4. 호스트 확인
섹션 제목: “4. 호스트 확인”설정 → 서버 → 진단 및 개인정보 보호 (/settings/server/diagnostics)는 호스트
수준 페이지입니다. 여기에는 다음이 있습니다:
- 샌드박싱 — 마스터 토글, 감지된 백엔드, 설치 힌트. 서버에서 오는 것은 감지된 백엔드뿐입니다. 아래의 주의를 참고하세요. 초기화 컨트롤은 없습니다.
- 시맨틱 검색 — 온디바이스 임베딩 모델의 수명 주기: 설치됨, 백분율과 함께 다운로드 중, 설치되지 않음, 설치 오류. 설치되기 전까지 메모리와 코드 검색은 키워드 전용으로 남습니다.
- 시스템 동작 — 에이전트가 실행되는 동안 컴퓨터를 깨어 있게 유지합니다.
- 로그 수준 — 실패를 재현하기 전에 높입니다.
- 개인정보 — 원시 diff 내용을 에이전트의 모델로 전달할 수 있는지와 충돌 보고서를 보내는지 여부.
자주 발생하는 실패
섹션 제목: “자주 발생하는 실패”실행이 시작되지 않고 어댑터가 “찾을 수 없음”으로 표시됨
섹션 제목: “실행이 시작되지 않고 어댑터가 “찾을 수 없음”으로 표시됨”CLI를 서버 호스트에 설치한 다음 모델 제공업체 페이지에서 새로 고침을 누릅니다. 또는 CLI가 필요 없는 내장 어댑터로 에이전트를 전환하고 같은 페이지에서 제공업체를 연결합니다.
에이전트가 푸시하거나 풀 리퀘스트를 열 수 없음
섹션 제목: “에이전트가 푸시하거나 풀 리퀘스트를 열 수 없음”git이나 에이전트가 출력한 내용을 읽으세요. Control Center policy: …는 작업
규칙이 거부했거나 승인에 응답이 없었다는 뜻입니다: 설정 → 워크스페이스 →
에이전트 권한에서 리모트에 푸시와 풀 리퀘스트 열기를 확인하세요.
Control Center에 푸시할 수 있는 GitHub 자격 증명이 없다고 git이 알리면, 그
저장소에 GitHub App을 설치하거나 GitHub를 연결하세요.
시맨틱 검색이 유용한 결과를 반환하지 않음
섹션 제목: “시맨틱 검색이 유용한 결과를 반환하지 않음”설정 → 서버 → 진단 및 개인정보 보호 → 시맨틱 검색을 확인합니다. 임베딩 모델이 설치되기 전까지 검색은 키워드 전용입니다. 모델을 설치하기 전에 작성된 행은 백필되지 않으므로 그 뒤에도 계속 키워드 전용으로 남습니다.
서버가 아예 부팅되지 않음
섹션 제목: “서버가 아예 부팅되지 않음”네이티브 라이브러리가 필요하며 성능 저하 모드는 없습니다. dylib가 없으면 cc_server가
시작을 거부하고 오류 메시지에 문제가 된 라이브러리 이름을 밝힙니다.
scripts/natives/build_natives.sh로 네이티브를 준비한 뒤 서버 바이너리를 다시
빌드하세요.
동작이 조용히 거부됨
섹션 제목: “동작이 조용히 거부됨”승인자가 연결되지 않은 prompt 가드레일 결정은 설계상 거부됩니다. 설정 →
워크스페이스 → 에이전트 권한에서 워크스페이스의 규칙을 확인하세요.