DeepSeek Harness 웹 UI가 열리지 않을 때 점검법

DeepSeek Harness 웹 UI가 열리지 않을 때는 재설치보다 dsh web 프로세스와 접속 주소를 먼저 확인해야 합니다. 이번 주에는 로컬 접속을 복구한 뒤 모델 인증, 작업 공간, 승인 대기 순서로 검증하고, 원격 맥은 외부 공개 없이 안전한 원격 통로부터 점검하는 것이 좋습니다.

이 글은 처음 DeepSeek Harness를 실행한 개인 개발자, 화면은 열리지만 모델이나 작업 공간을 사용할 수 없는 AI Agent 엔지니어, 원격 맥 개발 노드의 접속 경로를 관리하는 운영 담당자를 위한 안내서입니다.

마지막 업데이트: 2026년 8월 18일. 실행 흐름은 공식 README와 명령어 안내를 확인하고, 오류 분류와 제한 조건은 공식 API 문서를 대조했습니다. 기본 포트와 설정 경로는 버전에 따라 달라질 수 있으므로 실제 터미널 출력이 우선입니다.

장애를 다음 순서로 나누면 원인을 빠르게 좁힐 수 있습니다.

• 웹 서버가 시작되었는가
• 브라우저가 올바른 장치와 주소에 접속하는가
• 모델 자격 증명과 모델 이름이 맞는가
• 작업 공간 경로와 권한이 정상인가
• 승인 대기나 API 응답 지연으로 작업이 멈춘 것은 아닌가

공식 안내에서 dsh web은 웹 UI를 시작하는 진입점으로 설명됩니다. 설치된 명령어와 세부 옵션은 버전에 따라 다를 수 있으므로 먼저 공식 README의 실행 안내와 dsh web --help 결과를 함께 확인해야 합니다. (github.com)

관찰 신호

터미널이 즉시 프롬프트로 돌아오면 명령어가 실행되지 않았거나 시작 직후 종료된 상태일 수 있습니다. 반대로 프로세스가 계속 남아 있지만 주소가 출력되지 않으면 초기화 중단, 포트 충돌, 설정 오류를 의심합니다. 브라우저에 오류가 표시되더라도 그것만으로 서버가 죽었다고 판단하면 안 됩니다.

확인할 작업

다음 체크리스트를 순서대로 수행합니다.

• [ ] dsh web --help가 정상적으로 출력되는지 확인합니다.
• [ ] dsh web 실행 직후 터미널에 오류와 접속 주소가 남는지 확인합니다.
• [ ] 별도 터미널에서 프로세스가 살아 있는지 확인합니다.
• [ ] 운영 체제의 포트 확인 도구로 해당 주소를 사용하는 프로세스를 확인합니다.
• [ ] 브라우저에 터미널에 표시된 주소를 그대로 붙여 넣습니다.
• [ ] 주소의 장치가 로컬 맥인지 원격 맥인지 다시 확인합니다.

명령어를 찾을 수 없다는 메시지는 브라우저 문제가 아닙니다. 설치 위치가 현재 셸의 경로에 포함되지 않았거나 다른 가상 환경에서 설치했을 가능성이 큽니다. 시작 실패 메시지가 있으면 내용을 보존한 뒤 설정과 권한을 확인해야 합니다. 이미 같은 포트를 사용하는 프로세스가 있다면 임의로 종료하지 말고 해당 프로세스가 다른 서비스인지 먼저 확인합니다.

복구 기준

터미널에 오류 없이 프로세스가 유지되고, 표시된 주소를 같은 맥의 브라우저에서 열 수 있으면 시작 체인은 통과입니다. 주소를 추측해 다른 포트로 바꾸는 것보다 실제 로그에 나온 주소를 기준으로 삼는 편이 안전합니다.

로컬 브라우저에서 열리는 것과 다른 장치에서 열리는 것은 별개의 문제입니다. 기본 로컬 주소는 해당 맥 내부에서만 접근하도록 동작할 수 있습니다. 따라서 원격 맥에서 실행한 뒤 개인 컴퓨터의 브라우저로 접속하려면 네트워크 경로, 인증, 방화벽, 포트 공개 범위를 따로 검증해야 합니다.

관찰 신호

• 같은 맥에서는 화면이 열리지만 다른 장치에서는 시간 초과가 발생합니다.
• 원격 통로는 연결되지만 웹 UI 주소만 접근되지 않습니다.
• 외부 주소로 열었을 때 로그인이나 인증 없이 화면이 노출될 가능성이 있습니다.

확인할 작업

• [ ] 먼저 SSH 같은 인증된 원격 통로가 정상인지 확인합니다.
• [ ] 원격 세션 안에서 로컬 주소 접속이 되는지 확인합니다.
• [ ] 필요하다면 인증된 터널 방식으로 로컬 웹 서비스를 전달합니다.
• [ ] 맥의 방화벽과 클라우드 네트워크 규칙을 확인합니다.
• [ ] 공용 네트워크에 직접 노출하기 전 인증과 접근 허용 범위를 문서화합니다.

로컬 접속이 확인되지 않은 상태에서 외부 주소를 열면 원인은 해결되지 않고 노출 범위만 커집니다. 원격 맥에서는 먼저 로컬 접속, 다음에 인증된 터널, 마지막에 제한된 네트워크 공개 순서로 진행해야 합니다.

복구 기준

원격 브라우저에서 화면이 열리고, 허용되지 않은 외부 장치에서는 접근할 수 없는 상태가 기준입니다. 인증 없는 공개 주소를 임시 해결책으로 사용하지 않는 것이 좋습니다. 원격 맥을 새로 준비해야 한다면 JEXCLOUD의 원격 맥 이용 환경을 검토하되, 접속 방식과 보안 경계는 배포 전에 별도로 확인해야 합니다.

화면이 열린 뒤 모델을 선택할 수 없다면 웹 UI와 API 연결을 분리해서 봐야 합니다. 모델 선택기에 항목이 없으면 모델 목록을 가져오지 못했거나 설정 형식이 맞지 않을 수 있습니다. 항목은 보이지만 실행이 실패하면 자격 증명, 모델 이름, 계정 상태를 확인합니다.

관찰 신호

• API Key를 저장했지만 모델 선택기가 비어 있습니다.
• 모델을 선택해도 인증 실패가 반복됩니다.
• 모델 이름을 직접 입력했지만 알 수 없는 모델이라는 응답이 나옵니다.
• 모델 목록을 불러오는 동안 화면이 계속 대기합니다.

확인할 작업

• [ ] 저장한 API Key가 현재 실행 사용자의 환경에 적용되는지 확인합니다.
• [ ] 키 앞뒤에 공백이나 잘못된 따옴표가 없는지 확인합니다.
• [ ] 선택한 모델 이름과 제공자 설정이 일치하는지 확인합니다.
• [ ] 사용자 설정과 셸 환경 변수 중 어느 값이 우선되는지 확인합니다.
• [ ] 같은 키로 최소 요청을 보내 응답 여부를 확인합니다.
• [ ] 오류 코드와 발생 시각을 함께 기록합니다.

공식 오류 문서는 잘못된 키를 401, 잔액 부족을 402, 형식이나 매개 변수 문제를 400 또는 422로 구분합니다. 요청이 너무 빠르면 429가 반환될 수 있고, 서버 오류나 과부하는 500과 503으로 분류됩니다. 따라서 “모델이 안 된다”는 표현 대신 실제 코드로 원인을 분류해야 합니다. 공식 오류 코드 안내를 기준으로 기록하면 모델 설정 문제와 상위 API 문제를 구분하기 쉽습니다. (api-docs.deepseek.com)

복구 기준

모델이 선택기에 표시되고, 최소 요청에 정상 응답하며, 작업 공간을 읽는 단계까지 진행되면 모델 설정은 통과입니다. 모델 이름이나 제공자 필드를 무작정 바꾸기보다 공식 모델 목록과 요청 형식을 기준으로 현재 버전의 이름을 확인해야 합니다. 모델 이름과 가격 정보는 변경될 수 있으므로 문서의 최신 상태를 우선합니다. (api-docs.deepseek.com)

DeepSeek Harness에서 실행을 시작한 디렉터리는 기본 파일 시스템 위치일 뿐, 새 웹 UI에서 작업 공간으로 자동 선택된다는 뜻은 아닙니다. 먼저 작업 공간을 추가하고 선택해야 하며, 원격 맥에서는 로컬 컴퓨터에 존재하는 경로와 원격 노드의 실제 경로가 다를 수 있습니다.

관찰 신호

• 작업 공간 선택기가 비어 있습니다.
• 경로를 입력해도 선택 항목이 활성화되지 않습니다.
• 작업 공간은 보이지만 저장소 파일을 읽지 못합니다.
• 로컬에서 사용하던 경로를 원격 맥에 그대로 입력했습니다.

확인할 작업

• [ ] 대상 디렉터리가 실제로 존재하는지 확인합니다.
• [ ] 실행 중인 사용자가 디렉터리를 읽고 쓸 수 있는지 확인합니다.
• [ ] 심볼릭 링크가 원격 환경에서 유효한지 확인합니다.
• [ ] 저장소가 완전히 내려받아졌는지 확인합니다.
• [ ] 웹 UI 프로세스의 실행 위치와 작업 공간 경로를 비교합니다.
• [ ] 민감한 상위 디렉터리를 작업 공간으로 지정하지 않습니다.

복구 기준

작업 공간이 선택되고, 파일 목록이 표시되며, 읽기 전용 확인 작업이 성공하면 다음 단계로 넘어갑니다. 처음부터 변경 명령을 실행하지 말고 저장소 상태 확인이나 파일 목록 조회처럼 부작용이 없는 작업으로 검증해야 합니다.

작업 카드가 멈춰 있어도 서비스가 중단된 것은 아닐 수 있습니다. 파일 변경, 셸 실행, 외부 도구 사용은 사용자의 승인을 기다릴 수 있고, 모델 요청은 상위 API 응답을 기다릴 수 있습니다.

관찰 신호와 확인 기준

• 승인 버튼이 남아 있으면 승인 대기 상태입니다.
• 터미널에는 요청이 유지되지만 응답이 없으면 API 대기 가능성이 있습니다.
• 429가 반복되면 요청 속도나 동시성이 원인일 수 있습니다.
• 세션만 멈추고 새 세션은 작동하면 기존 세션 상태를 의심합니다.

공식 제한 안내는 동시 요청을 계정 단위로 계산하며, 요청이 오래 응답하지 않을 때 연결이 유지될 수 있다고 설명합니다. 또한 추론이 시작되지 않은 연결은 일정 시간이 지나면 닫힐 수 있으므로, 대기 시간을 무조건 브라우저 고장으로 해석하면 안 됩니다. 공식 제한과 연결 유지 안내를 확인하고 오류 코드, 시각, 사용 모델, 최소 재현 작업을 함께 남깁니다. (api-docs.deepseek.com)

재시작 전에는 설정 파일, 환경 변수 이름, 작업 공간 경로, 현재 세션 정보를 별도 기록으로 보관합니다. 그다음 새 세션을 만들고 다음 순서로 확인합니다.

• [ ] 브라우저에서 웹 UI가 열립니다.
• [ ] 모델이 선택기에 표시됩니다.
• [ ] API Key로 최소 요청에 응답합니다.
• [ ] 작업 공간의 파일 목록을 읽습니다.
• [ ] 부작용 없는 명령을 실행합니다.
• [ ] 승인 요청이 표시되고 승인 뒤에만 작업이 진행됩니다.
• [ ] 새로 고침 뒤 세션 상태가 의도대로 유지됩니다.

dsh web 실행 자체가 계속 실패하면 기존 설정을 삭제하기보다 새 테스트 환경에서 동일한 명령을 재현합니다. 새 환경에서는 작동하고 기존 환경에서만 실패한다면 설정 또는 세션 상태를 되돌리는 편이 낫습니다. 반대로 장기간 안정적인 무중단 작업이나 물리 장치 접근이 필요하다면 임시 원격 맥보다 고정된 자체 환경이 적합할 수 있습니다.

현재 방식이 개인 맥에만 의존하면 잠자기, 네트워크 변경, 권한 차이, 재부팅 뒤 실행 상태가 관리되지 않는다는 단점이 있습니다. 반대로 원격 맥은 접속 경계와 인증 설정을 별도로 관리해야 하며, 이를 생략하면 장애보다 보안 문제가 커질 수 있습니다. 단기간 테스트나 반복 가능한 AI Agent 환경이 필요하다면 JEXCLOUD의 맥 대여 선택지를 비교해 보고, 배포 후에는 원격 작업 환경의 접근 조건과 함께 복구 기록을 남기는 방식이 더 현실적입니다.

장애가 해결된 뒤에는 설정과 작업 공간을 포함한 원격 맥 환경 스냅샷 또는 전달 기록을 보관하는 것이 좋습니다. 다음 업그레이드에서 다시 설치부터 시작하지 않고, 마지막으로 검증된 환경으로 되돌릴 수 있어야 운영 비용과 복구 시간을 통제할 수 있습니다.