Qwen Code CLI 설치 방법: 터미널 AI 코딩 에이전트 단계별 튜토리얼

사전 준비 사항

Qwen Code CLI(Qwen 모델 기반의 공식 터미널 기반 AI 코딩 에이전트)를 설치하기 전에 다음 사항을 확인하세요:

• Node.js 버전 20 이상 (권장: 최신 LTS). nodejs.org에서 다운로드하세요.
• Windows에서는 관리자 권한이 있는 터미널 또는 명령 프롬프트.
• 패키지 및 모델 다운로드를 위한 인터넷 연결.
• 선택 사항이지만 권장: Git(수동 소스 설치용) 및 macOS/Linux용 Homebrew.

Node.js 설치 확인:

node --version
npm --version

예상 출력은 v20.x.x 이상과 같은 버전을 표시합니다.

단계 1: 설치 방법 선택

Qwen Code CLI는 여러 설치 경로를 제공합니다. 대부분의 사용자에게는 빠른 설치 스크립트가 권장되며, 의존성을 자동으로 처리합니다.

빠른 설치 (권장)

Linux / macOS:

bash -c "$(curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.sh)"

Windows (관리자 권한으로 명령 프롬프트 실행):

curl -fsSL -o %TEMP%\install-qwen.bat https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.bat && %TEMP%\install-qwen.bat

실행 후 PATH를 새로 고치기 위해 터미널을 재시작하세요.

단계 2: npm을 통한 수동 설치

수동 제어를 선호하는 경우:

npm install -g @qwen-code/qwen-code@latest

이 명령은 qwen 명령어를 전역으로 설치합니다.

macOS/Linux에서 sudo 사용 (권한 문제 발생 시):

sudo npm install -g @qwen-code/qwen-code@latest

단계 3: Homebrew를 통한 설치 (macOS & Linux)

brew install qwen-code

단계 4: 설치 확인

다음 명령을 실행하여 설치 성공을 확인하세요:

qwen --version

다음과 유사한 출력이 표시되어야 합니다:

Qwen Code CLI v0.x.x

단계 5: 첫 실행 및 인증

대화형 CLI를 실행하세요:

qwen

처음 실행 시 CLI는 Qwen 계정으로 인증을 요청합니다(원클릭 로그인을 위해 브라우저가 열림). 로그인 후 기본 설정을 적용하고 대화형 터미널 UI로 진입합니다.

최상의 결과를 위해 먼저 프로젝트 디렉터리로 이동하세요:

cd /path/to/your/project
qwen

세션 내에서 /help, /model과 같은 명령어를 사용해 모델을 전환하거나 @filename으로 파일을 참조할 수 있습니다.

단계 6: 소스에서 수동 설치 (고급)

출시되지 않은 최신 변경 사항을 원하는 개발자의 경우:

git clone https://github.com/QwenLM/qwen-code.git
cd qwen-code
npm install
npm install -g .

그런 다음 qwen --version으로 확인하세요.

일반적인 문제 및 문제 해결

• 'qwen' 명령어를 찾을 수 없음: 터미널을 재시작하거나 hash -r을 실행하세요(Linux/macOS). Windows에서는 명령 프롬프트를 닫고 다시 열어주세요. Node.js 글로벌 bin 디렉토리가 PATH에 포함되어 있는지 확인하세요.

• npm install 중 권한 오류: Linux/macOS에서는 sudo를 사용하고, Windows에서는 명령 프롬프트를 관리자 권한으로 실행하세요.

• Node.js 버전이 너무 낮음: nvm이나 공식 설치 프로그램을 사용해 Node 20 이상으로 업그레이드하세요.

• Aliyun 자산에 대한 네트워크 문제: 대안으로 npm 방식을 시도해보세요.

• Termux 또는 특정 Linux 배포판에서 설치 실패: --ignore-scripts 플래그를 사용하세요: npm install -g @qwen-code/qwen-code@latest --ignore-scripts.

• 인증이 작동하지 않음: 브라우저가 팝업을 허용하는지와 유효한 Qwen 계정이 있는지 확인하세요.

지속적인 문제가 있다면 공식 GitHub 저장소를 확인하세요: https://github.com/QwenLM/qwen-code.

다음 단계

• 대화형 UI 탐색: 사용 가능한 슬래시 명령어를 보려면 /help를 입력하세요.
• 에이전트 코딩 시도: CLI에 자연어를 사용해 코드 리팩터링, 파일 설명 또는 작업 자동화를 요청해보세요.
• 모델 구성: /model을 사용해 Qwen3-Coder나 기타 지원 백엔드(로컬 Ollama 포함)를 선택하세요.
• VS Code 통합: 원활한 편집기 통합을 위해 Qwen Code Companion 확장을 설치하세요.
• 설정 사용자화: 테마, 기본 모델 및 고급 옵션을 위해 ~/.qwen/settings.json을 편집하세요.

이제 터미널에서 직접 강력한 AI 페어 프로그래머인 Qwen Code CLI를 사용할 준비가 되었습니다. 프로젝트 폴더 내에서 "이 코드베이스를 설명해줘"나 "이 함수를 더 나은 성능을 위해 리팩터링해줘"와 같은 간단한 프롬프트로 시작해보세요.

즐거운 코딩 되세요!