CH 07 · 문제 해결 치트시트
본장 목표
실행에 성공한 뒤 문제를 만나도 당황하지 마십시오. 이 지도를 보고 매칭하면 됩니다. 가장 흔한 시작, 구성, 실행 관련 이슈를 한곳에 다 모았습니다.
시작할 수 없을 때
dsh web 시작 시 흔한 함정은 단 세 가지뿐입니다.
| 증상 | 원인 | 해결 |
|---|---|---|
| 시작 시 포트 점유라고 보고함 | 3080이 다른 프로그램이 사용 중 | 실행 시 포트 변경: dsh web --port 8080(이는 실행 명령의 일부이며, 실행 중에는 바꿀 수 없습니다) |
| 브라우저가 자동으로 열리지 않음 | 일부 환경은 브라우저를 자동으로 띄우지 않음 | 수동으로 http://127.0.0.1:3080에 접속(포트 변경 시 해당 포트 사용) |
| 사용 중에 서비스가 스스로 종료됨 | dsh 서비스가 스스로 종료되는 경우가 있음 | 고장이 아니므로, 필요할 때 다시 실행 |
구성 관련 오류
모델 구성 중 오류는 몇 가지 범주로 나뉩니다. 해당 항목을 찾으십시오.
| 오류 | 의미 | 해결 |
|---|---|---|
MISSING_CREDENTIAL | 키 미설정 | 설정 → 모델에서 키 저장, 또는 참조되는 환경 변수를 제공 |
INVALID_CREDENTIAL | Key 형식 오류 | Key에 불필요한 공백이나 빠진 문자가 없는지 확인 |
UNKNOWN_MODEL | 모델이 없거나 설정되지 않음 | Model ID가 설정되어 있는지, 그리고 해당 제공자가 이 모델을 지원하는지 확인 |
UNSUPPORTED_REASONING_EFFORT | 지원하지 않는 추론 강도 | off / low / high / max 중 하나 사용 |
| 사용 가능한 모델 가져오기 401 반환 | Key가 틀림 | Key 확인. 모델 디스커버리는 OpenAI 호환 GET /models 엔드포인트를 호출합니다. 해당 엔드포인트를 제공하지 않는 서비스는 수동으로 모델 입력 |
실행 중 요청 오류
요청을 보낸 뒤 HTTP 오류 코드가 돌아오면, 대부분 DeepSeek 서버 쪽 상태이며 구성과 무관합니다. 공식 오류 코드 치트시트.
| 코드 | 의미 | 해결 |
|---|---|---|
| 401 | 인증 실패 | API Key가 유효한지, 만료되지 않았는지 확인 |
| 402 | 잔액 부족 | DeepSeek 오픈 플랫폼에서 충전 |
| 422 | 파라미터 오류 | 오류 메시지에 따라 요청 파라미터 수정 |
| 429 | 요청이 너무 빈번 | 요청 빈도를 낮추고 잠시 후 재시도(도배하지 말 것) |
| 500 | 서버 내부 오류 | 잠시 후 재시도. 계속 실패하면 공식 팀에 문의 |
| 502 | 게이트웨이 오류 | 상류 모델 서비스 불가. 잠시 후 재시도 |
| 503 | 서버 과부하 | 서버 부하가 큼. 나중에 재시도 |
dsh는 오류를 안정적인 내부 코드 몇 가지로도 분류합니다(AUTH 인증 실패, QUOTA 쿼터, RATE_LIMIT 속도 제한, CONTEXT_WINDOW_EXCEEDED 컨텍스트 초과, TRANSPORT 네트워크 전송 실패 등). 이 코드를 보면 있는 그대로 받아들이면 됩니다. 대체로 문자 그대로의 의미입니다.
인터페이스의 작은 함정 두 가지
- 모델 선택기가 "모델 선택"으로 멈춰 있고 입력란이 입력을 받지 못함: 이전에 설정한 기본 모델이 삭제된 제공자를 가리키고 있습니다. 다시 모델을 고르면 복구됩니다.
- headless로 돌린 작업을 찾을 수 없음: 세션 목록의 미분류(Ungrouped) 를 보십시오(CH 05에서 설명. 파일은 작업 폴더별로 저장, UI 표시는 미분류. 두 가지가 별개).
먼저 시도할 세 가지 한 수
묘사가 어려운 문제를 만나면, 이 순서로 가 보십시오. 대부분 해결됩니다.
- 로그 확인: 시작 시 터미널 출력, 또는 리다이렉트된 시작 로그(예:
dsh web > .dsh-startup.log 2>&1)에 오류 코드가 그대로 있습니다. - AI에게 구성 트리 자체를 확인시키기: 어떤 세션에서
--dump-config로 구성을 확인하고, "기본 모델이 내가 원하는 모델이 아닌 이유" 류의 질문을 던져서 위치를 찾게 하십시오(CH 05에서 다룬 트릭). - 서비스 재시작: 어차피 dsh 서비스는 스스로 종료되므로, 다시 실행하면 잘 되는 경우가 많습니다.
세 가지로도 해결이 안 되면 본인의 수준에 따라 두 갈래입니다.
- 완전 초심자(dsh가 첫 Agent): 공식 저장소의 Issues에서 같은 오류 키워드로 검색해 보십시오. 이미 누군가가 만났을 가능성이 큽니다.
- 이미 Claude Code나 Codex 같은 도구를 써 본 분: 그냥 그 도구들에게 문제 해결을 맡기면 됩니다.
이 장에서 배운 것
- [ ] 시작 시 흔한 세 가지 함정(포트 점유 / 브라우저 미열림 / 서비스 자체 종료)과 각각의 처리법을 알고 있다
- [ ] 구성 오류 표를 써서
MISSING_CREDENTIAL,UNKNOWN_MODEL,UNSUPPORTED_REASONING_EFFORT를 처리할 수 있다 - [ ] 흔한 실행 중 HTTP 오류 코드(401 / 402 / 429 / 500 / 502 / 503)의 의미와 기본 대응을 알고 있다
- [ ] "모델 선택"이 입력란을 잠그는 현상은 기본 모델이 삭제된 제공자를 가리키고 있다는 뜻임을 알고 있다
- [ ] 새로운 문제를 만나면 먼저 세 가지 한 수(로그 확인 / dump-config / 재시작)를 시도한다