Qwen CLI: Qwen Code 설치 및 사용 방법 (2026)
Qwen CLI(Qwen Code)는 오픈소스 터미널 코딩 에이전트입니다. 설치 방법과 무료 OAuth 티어가 사라진 지금 설정하는 방법은 다음과 같습니다.
TL;DR
- Qwen CLI(공식 명칭 Qwen Code)는 Alibaba의 오픈 소스 터미널 코딩 에이전트입니다 — Qwen 모델에 맞게 조정된 Gemini CLI의 포크입니다. Node.js 22+에서
npm install -g @qwen-code/qwen-code@latest로 설치하세요. - 대부분의 가이드가 놓치는 큰 변화: 무료 Qwen OAuth 티어는 2026-04-15에 중단되었습니다. 예전의 "하루 2,000회 무료 요청"은 더 이상 작동하지 않습니다 — 이제 API 제공자가 필요합니다.
- OpenAI 호환 엔드포인트를 가리키도록 세 가지 환경 변수
OPENAI_API_KEY,OPENAI_BASE_URL,OPENAI_MODEL을 설정하면 됩니다. 이것이 전체 설정입니다. - 하나의 엔드포인트로 Qwen *및* 다른 모델을 실행할 수 있습니다.
OPENAI_BASE_URL을 [Velokey](https://api.velokey.ai)로 지정하면 단일 키로qwen3.7-max, GPT, Claude 또는 GLM을 사용해 Qwen Code를 구동할 수 있습니다.
Qwen CLI(Qwen Code)란 무엇인가요?
Qwen CLI는 Alibaba의 Qwen 팀이 만든, 터미널에서 실행되는 오픈 소스 AI 코딩 에이전트인 Qwen Code의 일반적인 이름입니다. 코드베이스를 읽고 편집하며, 명령을 실행하고, 작업을 에이전트 방식으로 처리합니다 — Claude Code나 Gemini CLI와 같은 형태입니다. 실제로 이는 Qwen 모델에 맞게 조정된 프롬프트와 파서를 적용한 Gemini CLI의 포크로 시작했습니다.
설치하기 전에 알아둘 만한 점이 두 가지 있습니다. 첫째, 패키지 이름은 @qwen-code/qwen-code이므로 "qwen cli," "qwen-cli," "qwen code cli"는 모두 같은 도구를 가리킵니다. 둘째 — 이 부분에서 사람들이 자주 헷갈립니다 — Qwen의 서버에 고정되어 있지 않습니다. OpenAI 호환 프로토콜을 사용하므로 Qwen의 API, OpenRouter, 로컬 모델 또는 게이트웨이에 연결해 실행할 수 있습니다. 무료 경로가 바뀐 지금은 이 점이 그 어느 때보다 중요합니다.
Qwen Code CLI는 어떻게 설치하나요?
Node.js 22 이상에서 npm으로 Qwen Code를 전역 설치하세요:
npm install -g @qwen-code/qwen-code@latest
qwen --versionmacOS를 사용 중이라면 Homebrew도 작동하며(brew install qwen-code), Linux 및 Windows용 독립 실행형 설치 프로그램도 있습니다. 설치 시 실제로 중요한 사항은 다음과 같습니다:
| 요구 사항 | 세부 정보 |
|---|---|
| Node.js | 22+ — 터미널 UI(Ink 7 / React 19)에 필요합니다; Node 20은 실행에 실패하는 경우가 많습니다 |
| 설치 명령 | npm install -g @qwen-code/qwen-code@latest |
| 확인 | qwen --version, 그런 다음 qwen으로 대화형 UI 열기 |
| 첫 실행 | UI 안에서 /auth를 사용해 제공자 선택 |
설치 후 qwen: command not found가 표시되면 전역 npm bin 디렉터리가 PATH에 없는 것입니다 — npm config get prefix를 실행하고, 해당 경로의 /bin을 PATH에 추가하세요. Linux에서 전역 설치 중 권한 오류가 발생하면 보통 sudo가 필요하다는 뜻이거나, 더 나은 방법으로는 전역 설치가 시스템 디렉터리를 건드리지 않도록 nvm으로 관리되는 Node를 사용하는 것이 좋습니다.
무료 티어가 사라진 지금 Qwen CLI를 어떻게 설정하나요?
Qwen Code는 OpenAI 호환 API 키로 설정합니다. 무료 Qwen OAuth 티어가 [2026-04-15에 중단되었기](https://github.com/QwenLM/qwen-code/issues/3203) 때문입니다 — 캐시된 토큰은 잠시 남아 있을 수 있지만, 새 로그인은 거부됩니다. 해당 무료 티어는 예전에 하루 2,000회 요청과 분당 60회를 제공했습니다. 아직도 "Qwen Code를 무료로 사용"하는 튜토리얼 상당수가 이를 설명하고 있는데, 이제는 틀린 내용입니다.
현재 설정은 세 가지 환경 변수입니다. 이를 설정하고 qwen을 실행한 뒤 인증 메뉴에서 "OpenAI"를 선택하세요:
export OPENAI_API_KEY="your_api_key"
export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
export OPENAI_MODEL="qwen3-coder-plus"
qwen설정 파일을 선호하시나요? Qwen Code는 ~/.qwen/settings.json(또는 프로젝트 로컬 .qwen/settings.json)을 읽으며, 여기에서 모델 제공자를 한 번 정의할 수 있습니다:
{
"modelProviders": {
"openai": {
"protocol": "openai",
"models": [{
"id": "qwen3-coder-plus",
"envKey": "DASHSCOPE_API_KEY",
"baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1"
}]
}
},
"security": { "auth": { "selectedType": "openai" } }
}현재 제공자 옵션은 Alibaba Cloud의 ModelStudio Coding Plan(고정 월 구독), DashScope 종량제 토큰 API, OpenRouter, Fireworks 또는 기타 OpenAI 호환 엔드포인트입니다. 공식 인증 문서에는 현재 세트가 나와 있습니다 — 오래된 블로그보다 이 문서를 확인하세요. 바로 이 부분이 오래되어 잘못되기 쉬운 영역이기 때문입니다.
하나의 엔드포인트를 통해 어떤 모델이든 Qwen CLI로 실행하려면 어떻게 하나요?
OPENAI_BASE_URL을 게이트웨이로 지정하면 하나의 키로 여러 모델에 대해 Qwen Code를 실행할 수 있습니다 — 제공자별 계정을 이리저리 전환할 필요가 없습니다. Qwen Code는 OpenAI 호환 엔드포인트만 필요하므로 Velokey는 바로 대체해 사용할 수 있습니다: 하나의 키로 동일한 기본 URL을 통해 Qwen, GPT, Claude, GLM에 접근할 수 있습니다.
export OPENAI_API_KEY="sk-your-velokey-key"
export OPENAI_BASE_URL="https://api.velokey.ai/v1"
export OPENAI_MODEL="qwen3.7-max"
qwen실질적인 장점은 다시 인증하지 않고 백엔드를 전환할 수 있다는 점입니다. Qwen Code는 Qwen 모델에 맞게 조정되어 있으므로 [qwen3.7-max](/model/qwen3.7-max)가 자연스러운 기본값입니다 — 하지만 작업에 다른 모델이 필요하면 변수 하나만 바꾸면 됩니다:
OPENAI_MODEL에 설정할 값 | 사용 시점 |
|---|---|
qwen3.7-max | 기본값 — Qwen Code는 Qwen 모델에 맞게 조정되어 있습니다 |
gpt-5.6 | 어려운 리팩터링에서 GPT-5.6의 추론을 원할 때 |
claude-sonnet-5 | Claude의 코딩 스타일을 선호할 때 |
glm-5.2 | 비용에 민감한 코딩 실행 |
크레딧을 통한 토큰당 과금이므로 별도 구독이나 일일 요청 제한이 없습니다 — 에이전트가 실제로 사용한 만큼만 지불합니다. 계산 방식이 궁금하다면 Claude API 가격 가이드를 참고하세요. 동일한 토큰당 모델이 Qwen 및 나머지에도 적용됩니다.
Qwen CLI가 작동하지 않는 이유는 무엇인가요? 흔한 오류
대부분의 Qwen CLI 실패는 버그가 아니라 환경 또는 인증 문제이며, 몇 가지 원인으로 모입니다. qwen --safe-mode를 시작해 사용자 지정 설정을 비활성화하세요. 문제가 사라지면 설정을 하나씩 다시 활성화하여 원인을 찾으세요.
| 증상 | 원인 | 해결 |
|---|---|---|
qwen: command not found | 전역 npm bin이 PATH에 없음 | $(npm config get prefix)/bin을 PATH에 추가 |
| 실행되지 않음 / 시작 시 충돌 | Node.js < 22 | Node를 22+로 업그레이드(nvm 사용) |
| 인증 거부 / 401 | 무료 OAuth 티어 중단 또는 잘못된 키 | OpenAI 호환 키 + 기본 URL 설정 |
시작 시 EADDRINUSE | MCP 서버의 포트가 이미 사용 중 | 포트를 비우거나 MCP 설정 변경 |
MODULE_NOT_FOUND | 손상된 설치 / 의존성 | 재설치: npm install -g @qwen-code/qwen-code@latest |
| 비-Qwen 모델에서 모델 오류 | 도구 호출 형식 불일치 | OPENAI_MODEL을 Qwen 모델 또는 강력한 도구 사용 모델로 변경 |
키가 환경 변수가 아니라 브라우저 기반 도구에 저장되어 있다면, 세션 누락으로 별도의 오류가 발생할 수 있습니다 — "API key not found in cookies" 수정 가이드를 참고하세요. API 키를 클라이언트에 연결하는 전체 과정을 보려면 API 키로 모델 호출하는 방법에서 설정 패턴을 다룹니다.
자주 묻는 질문
Qwen CLI는 어떻게 설치하나요?
Node.js 22 이상에서 npm install -g @qwen-code/qwen-code@latest를 실행한 다음, qwen --version으로 확인하세요. macOS에서는 brew install qwen-code도 사용할 수 있습니다. command not found가 발생하면 전역 npm bin 디렉터리(npm config get prefix + /bin)를 PATH에 추가하세요.
Qwen CLI는 무료로 사용할 수 있나요?
내장 경로를 통해서는 더 이상 아닙니다 — 무료 Qwen OAuth 티어는 2026-04-15에 중단되었습니다. CLI 자체는 오픈 소스이며 무료이지만, 이제 API 제공자가 필요합니다: Alibaba의 ModelStudio Coding Plan, DashScope 종량제 토큰, OpenRouter 또는 자체 키로 설정한 OpenAI 호환 엔드포인트입니다.
내 API 키로 Qwen CLI를 어떻게 사용하나요?
세 가지 환경 변수 — OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MODEL — 를 설정한 뒤 qwen을 실행하고 인증 메뉴에서 "OpenAI"를 선택하세요. ~/.qwen/settings.json에 제공자를 정의할 수도 있습니다. 기본 URL은 사용 중인 OpenAI 호환 제공자를 가리킵니다.
Qwen Code CLI는 어떤 모델을 지원하나요?
Qwen Code는 Qwen3-Coder 같은 Qwen 모델에 맞게 조정되어 있지만, OpenAI 호환 프로토콜을 사용하므로 OpenAI, Anthropic, Gemini, OpenRouter, Ollama 또는 vLLM을 통한 로컬 모델, 그리고 게이트웨이에 대해 실행됩니다. 제공자가 노출하는 모델 ID로 OPENAI_MODEL을 설정하세요.
Qwen CLI가 "command not found"라고 표시하는 이유는 무엇인가요?
전역 npm bin 디렉터리가 PATH에 없기 때문입니다. npm config get prefix를 실행해 설치 prefix를 찾은 다음, 해당 /bin 하위 폴더를 PATH에 추가하고 셸을 다시 시작하세요. 이는 설치 후 가장 흔한 오류이며 도구 자체와는 관련이 없습니다.
Qwen의 API 대신 게이트웨이에 대해 Qwen CLI를 실행할 수 있나요?
네. Qwen Code는 모든 OpenAI 호환 엔드포인트를 허용하므로 OPENAI_BASE_URL을 게이트웨이로 지정하고 하나의 키로 여러 모델에 접근할 수 있습니다. 원하는 모델로 OPENAI_MODEL을 설정하세요 — 최고의 도구 호출 충실도를 위해서는 Qwen 모델을, 또는 작업별로 다른 모델을 사용할 수 있습니다.
