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

오픈소스 AI 코딩 에이전트인 Qwen Code CLI 설치 방법을 배우세요. Windows, macOS, Linux에서 npm, 빠른 설치 스크립트, Homebrew 및 문제 해결에 대한 단계별 안내입니다.

Canonical URL: https://a2a-mcp.org/blog/qwen-cli-install-ko

Language: ko

Published: 2026-04-07

Updated: 2026-04-07

## 사전 준비 사항

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

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

**Node.js 설치 확인**:

```bash
node --version
npm --version
```

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

## 단계 1: 설치 방법 선택

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

### 빠른 설치 (권장)

**Linux / macOS**:

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

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

```cmd
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을 통한 수동 설치

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

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

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

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

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

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

```bash
brew install qwen-code
```

## 단계 4: 설치 확인

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

```bash
qwen --version
```

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

```
Qwen Code CLI v0.x.x
```

## 단계 5: 첫 실행 및 인증

대화형 CLI를 실행하세요:

```bash
qwen
```

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

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

```bash
cd /path/to/your/project
qwen
```

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

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

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

```bash
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를 사용할 준비가 되었습니다. 프로젝트 폴더 내에서 "이 코드베이스를 설명해줘"나 "이 함수를 더 나은 성능을 위해 리팩터링해줘"와 같은 간단한 프롬프트로 시작해보세요.

즐거운 코딩 되세요!