문제 해결
이 가이드는 일반적인 문제에 대한 해결 방법과 디버깅 팁을 제공합니다. 다음 주제를 다룹니다:
- 인증 또는 로그인 오류
- 자주 묻는 질문 (FAQ)
- 디버깅 팁
- 기존 GitHub Issue 검색 또는 새 Issue 생성
인증 또는 로그인 오류
-
오류:
UNABLE_TO_GET_ISSUER_CERT_LOCALLY,UNABLE_TO_VERIFY_LEAF_SIGNATURE또는unable to get local issuer certificate- 원인: SSL/TLS 트래픽을 가로채고 검사하는 방화벽이 있는 기업 네트워크에 있을 수 있습니다. 이 경우 Node.js에서 커스텀 루트 CA 인증서를 신뢰하도록 설정해야 합니다.
- 해결 방법:
NODE_EXTRA_CA_CERTS환경 변수를 기업 루트 CA 인증서 파일의 절대 경로로 설정하세요.- 예시:
export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt
- 예시:
-
오류: 자체 서명된 엔드포인트에 대한
Connection error. (cause: fetch failed)- 원인:
https://배후의 로컬 모델과 같이 자체 서명된 TLS 인증서를 가진 자체 호스팅 서버로 Qwen Code를 지정하고 있어 Node.js가 이를 거부합니다. - 해결 방법:
NODE_EXTRA_CA_CERTS(위 참조)를 통해 인증서를 신뢰하는 것을 우선적으로 시도하세요. 신뢰할 수 있는 실험실/사설 네트워크에서 이것이 실용적이지 않은 경우--insecure플래그(또는QWEN_TLS_INSECURE=1)로 검증을 건너뛰세요:- 예시:
qwen --insecure --openaiBaseUrl https://192.168.1.10:8080 ... - 경고: 검증을 비활성화하면 중간자 공격으로부터의 보호가 제거됩니다. 완전히 신뢰하는 엔드포인트에만 사용하세요.
- 예시:
- 원인:
-
오류:
Device authorization flow failed: fetch failed- 원인: Node.js가 Qwen OAuth 엔드포인트에 접근할 수 없습니다(종종 프록시 또는 SSL/TLS 신뢰 문제). 사용 가능한 경우 Qwen Code는 기본 오류 원인도 출력합니다(예:
UNABLE_TO_VERIFY_LEAF_SIGNATURE). 참고: 이 오류는 레거시 Qwen OAuth 흐름에만 해당됩니다. - 해결 방법:
- 여전히 Qwen OAuth를 사용 중이라면
/auth를 통해 API Key 또는 Coding Plan으로 전환하세요. - 프록시 뒤에 있는 경우
qwen --proxy <url>(또는settings.json의proxy설정)을 통해 설정하세요. - 네트워크에서 기업 TLS 검사 CA를 사용하는 경우 위에서 설명한 대로
NODE_EXTRA_CA_CERTS를 설정하세요.
- 여전히 Qwen OAuth를 사용 중이라면
- 원인: Node.js가 Qwen OAuth 엔드포인트에 접근할 수 없습니다(종종 프록시 또는 SSL/TLS 신뢰 문제). 사용 가능한 경우 Qwen Code는 기본 오류 원인도 출력합니다(예:
-
문제: 인증 실패 후 UI가 표시되지 않음
- 원인: 인증 유형을 선택한 후 인증이 실패하면
security.auth.selectedType설정이settings.json에 지속될 수 있습니다. 재시작 시 CLI가 실패한 인증 유형으로 인증을 시도하다가 UI를 표시하지 못할 수 있습니다. - 해결 방법:
settings.json파일에서security.auth.selectedType구성 항목을 제거하세요:~/.qwen/settings.json(또는 프로젝트별 설정의 경우./.qwen/settings.json)을 엽니다security.auth.selectedType필드를 제거합니다- CLI를 재시작하여 인증을 다시 요청하도록 합니다
- 원인: 인증 유형을 선택한 후 인증이 실패하면
자주 묻는 질문 (FAQ)
-
Q: Qwen Code를 최신 버전으로 업데이트하려면 어떻게 하나요?
- A: 독립 실행형 설치 프로그램으로 Qwen Code를 설치한 경우 독립 실행형 설치 명령어를 다시 실행하세요.
npm을 통해 전역으로 설치한 경우npm install -g @qwen-code/qwen-code@latest명령어로 업데이트하세요. 소스에서 컴파일한 경우 저장소에서 최신 변경 사항을 pull한 후npm run build명령어로 다시 빌드하세요.
- A: 독립 실행형 설치 프로그램으로 Qwen Code를 설치한 경우 독립 실행형 설치 명령어를 다시 실행하세요.
-
Q: Qwen Code 구성 또는 설정 파일은 어디에 저장되나요?
-
A: Qwen Code 구성은 두 개의
settings.json파일에 저장됩니다:- 홈 디렉토리:
~/.qwen/settings.json. - 프로젝트 루트 디렉토리:
./.qwen/settings.json.
자세한 내용은 Qwen Code 구성을 참조하세요.
- 홈 디렉토리:
-
-
Q: 통계 출력에서 캐시된 토큰 수가 표시되지 않는 이유는 무엇인가요?
- A: 캐시된 토큰 정보는 캐시된 토큰이 사용 중일 때만 표시됩니다. 이 기능은 API 키 사용자(예: Alibaba Cloud Model Studio API 키 또는 Google Cloud Vertex AI)에게 제공됩니다.
/stats명령어를 사용하여 총 토큰 사용량을 확인할 수 있습니다.
- A: 캐시된 토큰 정보는 캐시된 토큰이 사용 중일 때만 표시됩니다. 이 기능은 API 키 사용자(예: Alibaba Cloud Model Studio API 키 또는 Google Cloud Vertex AI)에게 제공됩니다.
-
Q: 커스터마이제이션(확장, hook, skill, MCP 서버 또는 서브에이전트)이 Qwen Code를 손상시키는 것 같습니다. 어떻게 격리하나요?
- A:
--safe-mode플래그와 함께 Qwen Code를 시작하여 세션 동안 모든 커스터마이제이션을 비활성화하세요 — 컨텍스트 파일, hook, 확장, skill, MCP 서버, 커스텀 서브에이전트(내장 서브에이전트만 로드), 권한 규칙, 설정 기반 승인 모드 오버라이드, 메모리 기능 및 샌드박스 설정. 참고: CLI 플래그--yolo및--approval-mode는 안전 모드에서도 계속 적용됩니다. 안전 모드에서 문제가 사라지면 커스터마이제이션을 하나씩 다시 활성화하여 원인을 찾으세요.- 예시:
qwen --safe-mode - 대안: CLI가 플래그를 받을 수 없는 경우 환경 변수
QWEN_CODE_SAFE_MODE=true를 설정하세요. - 참고: 여기서 “MCP 서버”는
settings.json/ 프로젝트.mcp.json에 구성된 서버를 의미합니다 — 안전 모드가 격리하려는 로컬/환경 상태입니다. 현재 호출을 위해 명시적으로 제공하는 MCP 서버(임베딩 ACP 클라이언트의session/newmcpServers또는--mcp-config)는 로컬/환경 상태가 아니며 안전 모드에서도 계속 적용됩니다.
- 예시:
- A:
리버스 프록시 뒤에서 첨부 파일 업로드 시 HTTP 413 반환
프록시는 첨부 파일이 데몬의 8 MiB 파일 제한 내에 있더라도 qwen serve에 도달하기 전에 요청을 거부할 수 있습니다. 데몬 본문 제한만 높여서는 프록시 제한이 변경되지 않습니다.
session_attachment_chunk_upload을 지원하는 데몬 및 TypeScript SDK/Web Shell 빌드를 사용하세요. 그러면 512 KiB를 초과하는 첨부 파일이 바이트나 이미지 품질을 변경하지 않고 512 KiB 요청으로 분할 업로드됩니다. 이전 데몬은 단일 요청 업로드 경로를 유지합니다. 프록시를 직접 운영한다면 원래 첨부 파일 요청을 수용하도록 요청 본문 제한을 높일 수도 있습니다. 제한이 512 KiB 미만인 프록시는 여전히 구성 변경이 필요합니다.
첨부 파일 제한은 8 MiB로 유지됩니다. 업로드가 만료되거나 데몬이 재시작되면 UI에서 첨부 파일을 재시도하세요. 응답이 유실된 완료된 업로드는 세션의 첨부 파일에 남아 있을 수 있습니다. 취소는 이미 완료된 파일을 제거하지 않습니다.
일반적인 오류 메시지와 해결 방법
-
오류: MCP 서버 시작 시
EADDRINUSE(Address already in use).- 원인: 다른 프로세스가 MCP 서버가 바인딩하려는 포트를 이미 사용 중입니다.
- 해결 방법: 포트를 사용 중인 다른 프로세스를 중지하거나 MCP 서버가 다른 포트를 사용하도록 구성하세요.
-
오류: Command not found(
qwen으로 Qwen Code를 실행하려고 할 때).- 원인: CLI가 올바르게 설치되지 않았거나 시스템의
PATH에 없습니다. - 해결 방법:
업데이트 방법은 Qwen Code 설치 방식에 따라 다릅니다:
qwen을 독립 실행형 설치 프로그램으로 설치한 경우 독립 실행형 설치 명령어를 다시 실행한 후 새 터미널을 여세요.qwen을 전역으로 설치한 경우npm전역 바이너리 디렉토리가PATH에 있는지 확인하세요.npm install -g @qwen-code/qwen-code@latest명령어로 업데이트할 수 있습니다.- 소스에서
qwen을 실행하는 경우 올바른 명령어로 호출하고 있는지 확인하세요(예:node packages/cli/dist/index.js ...). 업데이트하려면 저장소에서 최신 변경 사항을 pull한 후npm run build명령어로 다시 빌드하세요.
- 원인: CLI가 올바르게 설치되지 않았거나 시스템의
-
오류:
MODULE_NOT_FOUND또는 import 오류.- 원인: 의존성이 올바르게 설치되지 않았거나 프로젝트가 빌드되지 않았습니다.
- 해결 방법:
npm install을 실행하여 모든 의존성이 존재하는지 확인하세요.npm run build를 실행하여 프로젝트를 컴파일하세요.npm run start로 빌드가 성공적으로 완료되었는지 확인하세요.
-
오류: “Operation not permitted”, “Permission denied” 또는 유사한 오류.
- 원인: 샌드박싱이 활성화되어 있을 때 Qwen Code가 샌드박스 구성에 의해 제한되는 작업(프로젝트 디렉토리 또는 시스템 임시 디렉토리 외부에 쓰기 등)을 시도할 수 있습니다.
- 해결 방법: 자세한 내용은 구성: 샌드박싱 문서를 참조하세요. 샌드박스 구성을 커스터마이즈하는 방법도 포함되어 있습니다.
-
Qwen Code가 “CI” 환경에서 대화형 모드로 실행되지 않음
- 문제:
CI_로 시작하는 환경 변수(예:CI_TOKEN)가 설정되어 있으면 Qwen Code가 대화형 모드로 진입하지 않습니다(프롬프트가 표시되지 않음). 이는 기본 UI 프레임워크에서 사용하는is-in-ci패키지가 이러한 변수를 감지하여 비대화형 CI 환경으로 가정하기 때문입니다. - 원인:
is-in-ci패키지는CI,CONTINUOUS_INTEGRATION또는CI_접두사가 있는 환경 변수의 존재를 확인합니다. 이러한 변수 중 하나라도 발견되면 환경이 비대화형임을 신호하여 CLI가 대화형 모드로 시작되는 것을 방지합니다. - 해결 방법:
CI_접두사 변수가 CLI 작동에 필요하지 않은 경우 명령어에 대해 일시적으로 해제할 수 있습니다. 예:env -u CI_TOKEN qwen
- 문제:
-
프로젝트 .env 파일에서 DEBUG 모드가 작동하지 않음
- 문제: 프로젝트의
.env파일에DEBUG=true를 설정해도 CLI의 디버그 모드가 활성화되지 않습니다. - 원인:
DEBUG및DEBUG_MODE변수는 CLI 동작과의 간섭을 방지하기 위해 프로젝트.env파일에서 자동으로 제외됩니다. - 해결 방법: 대신
.qwen/.env파일을 사용하거나settings.json에서advanced.excludedEnvVars설정을 구성하여 더 적은 변수를 제외하세요.
- 문제: 프로젝트의
-
tmux에서 트랙패드 스크롤링이 대화를 스크롤하는 대신 프롬프트 기록을 변경함
- 문제: tmux 세션에서 트랙패드 또는 휠 스크롤링이
Up Arrow또는Down Arrow를 누르는 것과 유사하게 이전 프롬프트를 순환할 수 있습니다. - 원인: tmux는 휠 제스처를 단순한 방향키 시퀀스로 변환할 수 있습니다. 이러한 시퀀스는 qwen-code가 받을 때 실제 방향키 누름과 구별할 수 없습니다.
- 해결 방법: 스크린 리더 모드가 비활성화되어 있으면
ui.useTerminalBuffer가 활성화되어 있는지 확인한 후Shift+Up/Shift+Down을 사용하거나 tmux가 휠 이벤트를 앱으로 전달할 때 마우스 휠을 사용하세요(ui.mouseTracking필요). 호스트 스크롤백을 선호하는 경우 휠 이벤트에 대한 tmux 마우스 바인딩을 조정하세요.
- 문제: tmux 세션에서 트랙패드 또는 휠 스크롤링이
-
오른쪽 클릭이 작동하지 않고, 링크가 열리지 않으며, 터미널에서 텍스트를 선택할 수 없음
- 문제: Qwen Code가 실행 중인 동안 네이티브 오른쪽 클릭 컨텍스트 메뉴, OSC 8 하이퍼링크 클릭 및 터미널 네이티브 텍스트 선택이 작동하지 않습니다.
- 원인:
ui.mouseTracking이 활성화되어 있을 때(기본값), Qwen Code는 SGR 마우스 추적을 통해 모든 마우스 이벤트를 캡처하여 앱 내 텍스트 선택, 클릭으로 위치 이동, 행 호버, 기록 항목 토글 및 뷰포트 스크롤링을 구동합니다. 터미널은 모든 마우스 이벤트를 네이티브로 처리하지 않고 앱으로 전달합니다. Qwen Code는 추적이 켜져 있는 동안 자체 대체 기능을 제공합니다: 단일 클릭으로 http(s) OSC 8 하이퍼링크가 열리고, 링크나 텍스트 선택 영역에서 오른쪽 클릭하면 앱 내 컨텍스트 메뉴가 열립니다. - 해결 방법: 터미널의 네이티브 처리를 선호하는 경우
settings.json에서"ui.mouseTracking": false로 설정하세요. 이렇게 하면 앱 내 링크 열기 및 컨텍스트 메뉴를 포함한 모든 앱 내 마우스 상호작용이 꺼집니다. Virtualized History(ui.useTerminalBuffer: true, 기본값)에서는 휠이 더 이상 트랜스크립트를 스크롤하지 않습니다 —Shift+↑/↓,PgUp/PgDn또는Ctrl+Home/End를 대신 사용하세요. 네이티브 터미널 스크롤백도 복원하려면"ui.useTerminalBuffer": false로 설정하세요. 재시작이 필요합니다.
IDE Companion이 연결되지 않음
- VS Code에 단일 작업 공간 폴더가 열려 있는지 확인하세요.
- 확장 프로그램 설치 후 통합 터미널을 재시작하여 다음을 상속하도록 하세요:
QWEN_CODE_IDE_WORKSPACE_PATHQWEN_CODE_IDE_SERVER_PORT
- 컨테이너에서 실행 중인 경우
host.docker.internal이 확인되는지 확인하세요. 그렇지 않으면 호스트를 적절히 매핑하세요. /ide install로 companion을 재설치하고 Command Palette에서 “Qwen Code: Run”을 사용하여 시작되는지 확인하세요.
일부 네트워크에서의 연결 리셋(TLS 스택 선택적 미들박스)
- 문제: 일부 통신사 또는 기업 네트워크에서 API 엔드포인트로의 HTTPS 연결이 TLS ClientHello 직후에 리셋(TCP RST)됩니다. Qwen Code는 예산이 소진될 때까지 재시도를 계속하고(
ECONNRESET은 재시도 가능한 전송 오류), 이후 일반적인 연결 오류를 표시합니다. 반면curl, Python 및 기타 도구는 동일한 머신과 네트워크에서 동시에 정상적으로 작동합니다. - 원인: 일부 미들박스는 TLS ClientHello 핑거프린트별로 연결을 필터링하고 특정 TLS 스택 세대에서 생성된 연결을 리셋합니다. 영향을 받는 링크에서는 OpenSSL 3.0 세대 스택과 Electron/BoringSSL(VS Code 확장 및 데몬에서 사용)이 리셋되는 반면, OpenSSL 3.5 세대 스택(현재 Node.js 빌드 포함)은 정상적으로 연결됩니다.
- 해결 방법: 3.5 세대 TLS 스택으로 연결을 설정하세요:
- CLI: 지원되는 Node.js 라인의 최신 빌드를 사용하세요(현재 Node 22/24/25 빌드는 모두 3.5 세대 OpenSSL을 포함). 동일한 메이저의 이전 빌드는 아직 영향을 받는 세대에 있을 수 있습니다. 오래된 마이너에 고정하지 말고 업데이트하세요.
- VS Code 확장 / 데몬: 확장은 Electron의 TLS 스택에서 실행되며 클라이언트 측에서 변경할 수 없습니다. 작은 로컬 릴레이(3.5 세대 스택의 로컬 프로세스)를 실행하고 모델 베이스 URL 재정의(
settings.json의 커스텀 엔드포인트 또는 CLI의--openaiBaseUrl)를 통해 Qwen Code를 가리키면 TLS 송신이 더 새로운 스택으로 발생합니다.
- 불안정한 네트워크와 구별하는 방법:
- 리셋은 결정론적입니다. 모든 시도가 즉시 실패하고, 재시도해도 회복되지 않습니다.
- 동일한 머신과 시점에 다른 TLS 스택은 동일한 엔드포인트에 대해 성공합니다.
- TLS 버전을 고정하거나 DNS 확인을 변경해도 도움이 되지 않습니다.
종료 코드
Qwen Code는 종료 이유를 나타내기 위해 특정 종료 코드를 사용합니다. 이는 스크립팅 및 자동화에 특히 유용합니다.
| 종료 코드 | 오류 유형 | 설명 |
|---|---|---|
| 41 | FatalAuthenticationError | 인증 프로세스 중에 오류가 발생했습니다. |
| 42 | FatalInputError | CLI에 유효하지 않거나 누락된 입력이 제공되었습니다. (비대화형 모드만) |
| 44 | FatalSandboxError | 샌드박스 환경(예: Docker, Podman 또는 Seatbelt)에서 오류가 발생했습니다. |
| 52 | FatalConfigError | 구성 파일(settings.json)이 유효하지 않거나 오류가 포함되어 있습니다. |
| 53 | FatalTurnLimitedError | 세션의 최대 대화 턴 수에 도달했습니다. (비대화형 모드만) |
디버깅 팁
-
CLI 디버깅:
- CLI 명령어와 함께
--verbose플래그(사용 가능한 경우)를 사용하면 더 자세한 출력을 얻을 수 있습니다. - CLI 로그를 확인하세요. 일반적으로 사용자별 구성 또는 캐시 디렉토리에 있습니다.
- CLI 명령어와 함께
-
코어 디버깅:
- 서버 콘솔 출력에서 오류 메시지나 스택 트레이스를 확인하세요.
- 구성 가능한 경우 로그 상세도를 높이세요.
- 서버 측 코드를 단계별로 실행해야 하는 경우 Node.js 디버깅 도구(예:
node --inspect)를 사용하세요.
-
도구 문제:
- 특정 도구가 실패하는 경우 해당 도구가 수행하는 명령이나 작업의 가장 간단한 버전을 실행하여 문제를 격리해 보세요.
run_shell_command의 경우 셸에서 직접 명령이 작동하는지 먼저 확인하세요.- _파일 시스템 도구_의 경우 경로가 올바른지 확인하고 권한을 확인하세요.
-
프리플라이트 검사:
- 코드를 커밋하기 전에 항상
npm run preflight를 실행하세요. 포매팅, 린팅 및 타입 오류와 관련된 많은 일반적인 문제를 잡을 수 있습니다.
- 코드를 커밋하기 전에 항상
기존 GitHub Issue 검색 또는 새 Issue 생성
이 _문제 해결 가이드_에서 다루지 않은 문제에 직면한 경우 Qwen Code GitHub의 Issue 트래커 를 검색해 보세요. 여러분의 문제와 유사한 이슈를 찾을 수 없다면 자세한 설명과 함께 새 GitHub Issue를 생성하는 것을 고려하세요. Pull Request도 환영합니다!