문제 해결

재현 가능한 사례부터 시작하기#

설정을 변경하기 전에 다음을 기록합니다.

• 워크스페이스/사이트, 공개 경로 또는 API 엔드포인트, 시간대 포함 정확한 시간.
• 예상 결과와 실제 결과.
• 브라우저/기기 또는 외부 제공자 채널.
• 소유자 미리보기, 남은 호스팅 데모 페이지, 임베드, 커넥터, API 중 어디에 영향이 있는지.
• 안전한 상태/오류 문구, 응답 x-request-id, 커넥터 마지막 오류, 제공자 전달 이벤트 ID.
• 마지막 정상 시간과 가장 작은 최근 변경.

평문 API/제공자/커넥터 자격 증명, 웹훅 시크릿, 비공개 고객 데이터, 전체 Authorization 헤더, 불필요한 대화 콘텐츠를 포함하지 마세요.

사이트 변경이 나타나지 않음#

1. 대시보드 URL이 대상 사이트/워크스페이스인지 확인합니다.
2. 저장 작업이 성공을 보고했는지 확인합니다.
3. 페이지 문구, 지식, 페르소나는 검토 후 공개에서 다시 게시합니다.
4. Look(및 브랜딩 배지)은 저장 성공만으로 라이브 임베드가 갱신됩니다. 재게시를 건너뛰고 비공개 창을 여세요.
5. 비공개 창에서 실제 임베드(또는 남은 호스팅 슬러그)를 엽니다.
6. 소셜 미리보기만 오래됐다면 해당 플랫폼 캐시/디버거를 사용합니다.

게시 해제와 편집은 다릅니다. 임베드가 꺼져 있어도 연결된 메시징 커넥터는 계속 답할 수 있습니다.

에이전트 답변이 약하거나 잘못됨#

소유자 테스터와 새 공개 대화에서 같은 질문을 보냅니다. 관련 지식 소스가 인덱싱됐고 명시적 답을 포함하며 최신이고 다른 소스와 충돌하지 않는지 확인합니다. 언어/페르소나 규칙이 답변을 막는 경계를 갖는지도 확인하세요.

소스에 답이 없으면 추측하도록 지시하지 말고 폴백/에스컬레이션 동작을 개선하세요. 지식 소스에서 직접/바꿔 말하기/경계 승인 세트를 만듭니다.

임베드 실행 버튼이 없거나 차단됨#

사이트 게시, 임베드 활성화, 스크립트의 정확한 사이트 슬러그, 브라우저 최종 상위 오리진(스킴/호스트/포트 포함) 허용을 확인합니다. DevTools에서 embed.js 요청, CSP 오류, 동의 관리자 상태, iframe 요청, 단일 data-maf-embed 루트를 점검하세요.

텍스트는 되지만 마이크가 실패하면 HTTPS, 브라우저 권한, iframe allow 권한, 호스트 Permissions Policy를 확인합니다. 전체 임베드 개요와 보안 및 CSP를 따르세요.

음성이 작동하지 않음#

음성 메시지, 실시간 통화, 복제, 커넥터 음성 중 실패 모드를 분리합니다. 텍스트 경로 성공은 언어 모델 키만 증명합니다.

전사, TTS, 실시간, 복제 제공자 키를 각각 확인한 뒤 요금제 권한, 크레딧, 실시간 시간, 브라우저 권한, 설정 언어, 샘플 제한, 동의를 확인합니다. 길거나 시끄러운 파일을 조사하기 전에 짧고 깨끗한 녹음으로 테스트하세요.

커넥터가 메시지를 받지 못함#

채널 가이드를 사용해 양쪽을 비교합니다. 커넥터 활성, 자격 증명 유효, 제공자 웹훅/인터랙션/스킬 URL이 현재 값인지, 필수 이벤트/페이지/번호/블록 구독, 앱 모드 테스트 사용자 포함, 공개 HTTPS 전달을 확인합니다.

웹훅 검증 성공은 런타임 이벤트 구독이나 발신 권한을 증명하지 않습니다. 제공자 전달 로그와 마지막 메시지, 커넥터 저장 오류를 비교하세요. 음성 전에 텍스트를 테스트합니다.

사용자 지정 도메인은 제공하지 않음#

고객 도메인을 판매하거나 연결하지 않습니다. 이미 있는 사이트에 임베드로 에이전트를 넣으세요. 남아 있는 Polar 도메인 추가 기능 이벤트는 무시되거나 취소되며 크레딧을 만들지 않습니다.

API 요청 실패#

메서드, 버전 경로, 상태, 안정 오류 코드, 응답 x-request-id, 관련 속도 제한 헤더를 기록합니다. 그다음 분류하세요.

자격 증명 및 토큰, 범위 및 오류, 요청 한도를 사용하세요. API 오류를 해결하려고 서버 자격 증명을 브라우저 코드로 옮기지 마세요.

결제 또는 사용량이 이상함#

플랫폼 접근, 월 크레딧, 구매 크레딧, 사이트 수, 실시간 시간, 복제 슬롯, API 속도를 구분합니다. 추가 구매는 크레딧만 바꿉니다. BYOK 제공자 비용은 Make Agent Fast 결제와 별도입니다.

예상치 못한 사용량은 조사 전에 가능한 원인을 차단하세요. 커넥터를 끄고, 키를 폐기하고, 의도하지 않은 임베드 오리진을 제거하거나 API 재시도 루프를 중지합니다. 비밀 값을 노출하지 않고 시간 범위와 요청/제공자 ID를 보존합니다.

안전한 지원 정보 수집하기#

계속 차단되면 가장 관련된 가이드의 피드백 컨트롤 또는 대시보드 지원을 사용하고 다음을 포함하세요.

• 사이트/워크스페이스 식별자와 영향 기능.
• 정확한 타임스탬프/시간대와 재현 단계.
• 예상 결과와 실제 결과.
• 관련된 경우 공개 비밀 아닌 URL.
• HTTP 상태, 안정 오류 코드, x-request-id, 제공자 이벤트 ID.
• 비밀 값과 개인정보를 제거한 스크린샷 또는 최소 페이로드.

이미 확인한 내용을 적으세요. 반복 설정 안내를 줄이고 실패 경계를 명확하게 합니다.