문제 해결

서버의 머신은 응답했지만, 그 포트에서 연결을 받는 프로그램이 없습니다.

• 서버가 실행 중인지, 그리고 주소의 포트에서 실행 중인지 확인하세요. 3000에서 실행 중인 로컬 서버는 localhost:8080으로는 접속되지 않습니다.
• 변수가 채워진 뒤의 주소를 확인하세요. {{variable}} 알약 위에 포인터를 올려 값을 보고, 페이지 헤더에서 어떤 환경이 활성인지 확인합니다.
• Docker나 가상 머신 안의 서버는 포트를 Mac으로 공개해야 합니다.

이름이 주소로 해석되지 않습니다. 철자, 네트워크, VPN을 확인하세요. 회사 네트워크 안에만 있는 호스트는 그 네트워크나 VPN이 필요합니다.

…에서 제시간에 응답이 없습니다는 연결은 되었지만 응답이 요청의 시간 초과보다 오래 걸렸다는 뜻입니다. 서버가 느리면 요청의 설정 탭에서 시간 초과를 늘리세요. …에 제시간에 연결하지 못했습니다는 연결 자체가 열리지 않았다는 뜻입니다. 방화벽, VPN, 또는 꺼져 있는 서버가 원인입니다.

Echolot은 열려 있는 연결을 재사용합니다. 요청이 나가는 바로 그 순간 서버가 연결 하나를 닫았고 응답이 돌아오지 않았습니다.

두 번 보내도 되는 요청(GET 등 안전하거나 멱등한 메서드, 또는 Idempotency-Key 헤더가 있는 요청)은 Echolot이 새 연결로 한 번 자동으로 재시도합니다. POST 같은 다른 요청은 서버가 이미 요청을 처리했을 수 있으므로 재시도하지 않습니다. 다시 보내기 전에 확인하세요.

연결할 수 없습니다는 네트워크에 서버로 가는 경로가 없다는 뜻입니다. Wi-Fi, 네트워크, VPN을 확인하세요. 연결을 재설정했습니다는 서버나 중간의 무언가가 연결을 끊었다는 뜻이며, 방화벽이거나 프로토콜을 거부하는 서버인 경우가 많습니다(예: HTTPS 포트로 보낸 일반 HTTP).

데모 API는 공유되며 주소당 분당 120개 요청으로 제한하고, 크거나 느리거나 스트리밍하는 엔드포인트(내보내기, bytes, delay, WebSocket, SSE)는 분당 10개로 제한합니다. Retry-After 응답 헤더에 있는 초만큼 기다린 뒤 다시 보내세요. 데모에 대해 반복이 많은 실행을 하면 한도에 금방 도달하므로 반복 횟수를 줄이세요.

서버의 인증서가 자체 서명되었거나, 만료되었거나, Mac이 신뢰하는 기관이 서명하지 않았습니다. 메시지에 어느 쪽인지 표시됩니다.

• 회사나 개발용 인증 기관이라면 검사를 끄는 대신 작업 공간 설정 › 인증서에서 그 호스트에 대한 CA 인증서를 추가하세요. 요청 설정을 참조하세요.
• 개발 서버인 경우에만 요청의 설정 탭에서 TLS 인증서 확인을 끄세요.

인증서는 유효하지만 다른 호스트를 가리키고 있습니다. 인증서가 발급된 호스트 이름을 사용하거나 서버의 인증서를 고치세요.

서버와의 TLS 핸드셰이크에 실패했습니다. 콜론 뒤의 텍스트는 TLS 라이브러리가 알려 주는 이유입니다. 흔한 원인은 클라이언트 인증서를 요구하는 서버입니다. 작업 공간 설정 › 인증서에서 그 호스트에 인증서를 추가하세요.

인증서 설정이 이동된 파일이나 다른 형식의 파일을 가리키고 있습니다. 작업 공간 설정 › 인증서에서 파일을 다시 선택하세요. Echolot은 PEM 인증서를 읽습니다.

설정 › 네트워크 › 프록시가 결정합니다.

작업 공간은 작업 공간 설정 › 프록시에서 자체 프록시를 설정할 수 있으며, 앱의 프록시보다 우선합니다. 회사에서 PAC 파일을 사용한다면 그 프록시를 수동에 입력하세요. 명령줄 도구는 HTTPS_PROXY, HTTP_PROXY, NO_PROXY를 읽습니다.

프록시에 로그인해야 합니다. 설정 › 네트워크 또는 작업 공간의 프록시 설정에서 프록시에 사용자 이름과 비밀번호를 추가하세요.

프록시는 작동하지만 해당 서버에 접속하지 않거나 접속할 수 없습니다. 프록시의 규칙이 막고 있거나, 프록시가 있는 위치에서 서버가 꺼져 있습니다. 서버가 로컬이나 내부 서버라면 직접 연결에 추가하세요.

HTTP/3은 macOS 27 이상에서 작동합니다. 이전 macOS에서는 요청의 설정 탭에서 HTTP/2 또는 자동을 선택하세요.

Echolot은 HTTP/3을 프록시(브라우저처럼 시스템 프록시 포함), 사용자 지정 CA 파일, 클라이언트 인증서와 함께 보내지 않습니다. 그 요청에는 HTTP/2 또는 자동을 선택하세요. 자동에서는 서버가 HTTP/3을 제공하고 방해되는 것이 없을 때에만 Echolot이 저절로 HTTP/3으로 전환하며, QUIC 연결을 열 수 없으면 TCP로 대체합니다.

서버 검사에서 서버 시작이 실패로 표시됩니다.

• 먼저 승인하세요. Echolot은 MCP 서버 페이지에서 신뢰하고 확인으로 승인한 뒤에만 로컬 서버의 명령을 시작합니다. 그때까지 호출은 Echolot은 “…” MCP 서버를 시작한 적이 없습니다. MCP 서버 페이지에서 명령을 검토하고 먼저 신뢰하십시오.라고 표시합니다. 명령, 인수, 환경이 바뀌면 다시 묻습니다.
• 명령을 찾을 수 없습니다. 해결 방법은 “npx”이(가) 설치되어 있고 PATH에 있는지 확인하거나 전체 경로를 입력하십시오.라고 안내합니다. Echolot은 로그인 셸의 PATH로 서버를 시작하므로, 새 터미널 윈도우에서 작동하는 npx, uvx, 버전 관리자의 shim은 Echolot에서도 작동합니다. 셸이 대화형으로 하는 일을 거친 뒤에야 작동하는 명령이라면 전체 경로를 입력하세요(터미널에서 which npx로 찾을 수 있습니다).
• 시작했다가 멈춥니다. 같은 명령을 터미널에서 실행해 이유를 확인하세요. 서버의 오류 출력은 메시지 로그에도 있습니다.

서버 추가를 참조하세요.

Mac App Store 에디션을 사용 중이며, 이 에디션은 Mac에서 프로그램을 시작할 수 없습니다. 서버는 작업 공간에 그대로 남아 있습니다. 서버가 HTTP를 제공하면 HTTP로 추가하거나, 명령줄 도구(echolot mcp check -- <command>)로 실행하거나, 직접 다운로드 버전을 사용하세요. 에디션을 참조하세요.

검사의 해결 안내 줄이 무엇을 할지 알려 줍니다. OAuth를 요구하는 서버는 로그인, 토큰을 요구하는 서버는 Authorization 헤더, 404라면 올바른 경로(MCP 엔드포인트는 흔히 /mcp)입니다.

Mac App Store 에디션에서 Echolot은 사용자가 선택한 뒤에만 작업 공간 밖의 파일을 읽을 수 있습니다. 파일에서 스트리밍하는 본문, 폼 파트, 클라이언트 인증서, Echolot 밖에서 경로를 적은 .proto 파일에서 이런 일이 생깁니다. 실패한 응답에서 접근 허용…을 선택하고 파일을 고른 다음 다시 보내세요. Echolot이 이를 기억합니다.

직접 다운로드 버전에서는 이 메시지가 파일 자체의 권한 때문에 읽을 수 없다는 뜻입니다.

요청, 요청의 폴더, 또는 작업 공간에 다른 곳에서 온 스크립트가 있습니다. 가져오기, git pull, Echolot 밖의 편집 등입니다. 스크립트는 신뢰한 뒤에만 실행됩니다. 스크립트 검토…를 선택하고 읽어 본 다음 신뢰하세요. 스크립트와 테스트를 참조하세요.

Echolot이 요청의 파일을 기록할 수 없었습니다. 디스크가 가득 찼거나, 폴더가 읽기 전용이거나, 작업 공간이 이동했습니다. 재시도는 다시 시도하고, 계속 편집은 편집 내용을 탭에 그대로 두며 탭은 저장될 때까지 열려 있습니다.

탭에 저장되지 않은 편집이 있는 동안 다른 앱이나 Git이 파일을 변경했습니다. 디스크 버전 사용은 편집 내용을 버리고 파일을 불러오고, 내 변경 사항 유지는 편집 내용을 유지하고 파일에 덮어씁니다.

항목이 다른 Echolot 사본, 다른 에디션, 또는 명령줄 도구가 만든 것입니다. macOS는 항목마다 한 번 묻습니다. 항상 허용을 선택하세요.

직접 다운로드 버전의 릴리스된 베타 빌드는 릴리스 30일 뒤에, 또는 개발자가 빌드를 종료하면 그보다 일찍 만료됩니다. echolot.dev에서 최신 버전을 내려받아 이전 버전 위에 설치하세요. 작업 공간은 그대로 열립니다. 이 Mac의 날짜가 잘못된 것 같다는 알림이 뜬다면 시계가 Echolot이 이미 본 날짜보다 하루 넘게 이전이라는 뜻이므로 시스템 설정에서 날짜와 시간을 설정하세요. 설치를 참조하세요.

명령줄 도구가 아직 PATH에 없습니다. Echolot › 명령줄 도구 설치…를 선택한 다음 새 터미널 윈도우를 여세요(열려 있는 윈도우는 이전 PATH를 유지합니다). 설정 › 일반 › 명령줄 도구에 링크가 있는 위치가 표시됩니다. 경고가 표시되면 링크가 이동된 Echolot 사본을 가리키고 있는 것이므로 다시 설치를 선택하세요. App Store 에디션에서는 도구를 따로 설치하세요. 명령줄 도구를 참조하세요.

키체인이 없으면(Linux, CI, 또는 ECHOLOT_KEYCHAIN=0) 도구는 ECHOLOT_SECRET_<NAME>이라는 환경 변수에서 비밀 값을 읽습니다. 예를 들어 비밀 변수 password에는 ECHOLOT_SECRET_PASSWORD입니다. CI의 비밀 값 설정에서 지정하세요. CI를 참조하세요.

Echolot이 저장 폴더를 만들 수 없었으며, 보통 여유 공간이나 권한이 부족해서입니다. Echolot을 다시 시작할 때까지 응답은 임시 폴더에 보관됩니다. 공간을 확보하거나 폴더의 권한을 고친 다음(설정 › 정보 › 응답 및 기록 › Finder에서 보기로 위치를 확인할 수 있습니다) 다시 시작하세요.