Qwen Code 사용법: 설치, 계정·모델 선택, API 설정

Qwen Code는 Alibaba Qwen 팀이 공개한 오픈소스(Apache-2.0) AI 코딩 에이전트입니다. 사용법은 ‘설치 → 프로젝트에서 qwen 실행 → /auth로 연결 대상 설정 → 작업 요청’의 네 단계입니다. 다만 2026년 4월 15일에 무료 Qwen OAuth 등급이 끝나서, 그 전에 나온 사용법대로 로그인하면 더 이상 무료로 동작하지 않습니다. 그리고 한국어 사용자가 먼저 알아 둘 점: Qwen Code에는 한국어 UI가 없습니다. 이 페이지는 현재 /auth 메뉴 기준의 시작 방법, 한국어 답변 설정, Claude·GPT를 쓰는 커스텀 설정, 자주 쓰는 명령어를 차례로 설명합니다. 최신 버전은 2026년 9월 29일 npm에 올라온 v0.24.7이고 릴리스가 매주 이상 나오니, 설치된 버전은 qwen --version으로 확인하세요.

설치

공식 README의 명령입니다. 단독 설치 스크립트를 쓰면 Node.js를 직접 준비할 필요가 없고, npm으로 설치할 때만 Node.js 22 이상이 필요합니다.

# macOS / Linux (공식 단독 설치 스크립트)
curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.sh | bash

# Windows (PowerShell)
irm https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.ps1 | iex

# npm (Node.js 22 이상 필요)
npm install -g @qwen-code/qwen-code@latest

# Homebrew (macOS / Linux)
brew install qwen-code

설치 후 환경 변수가 적용되도록 터미널을 다시 여세요. Qwen Code는 원래 Google Gemini CLI v0.8.2를 기반으로 했지만 v0.1부터는 원본과 동기화하지 않고 독자적으로 개발되고 있습니다. Gemini CLI의 설정이나 무료 할당량이 그대로 적용되지 않습니다.

처음 실행과 한국어 답변

cd /path/to/your-project
qwen

# 세션 안에서:
/language output Korean   # 모델 답변을 한국어로 (UI는 한국어 미지원)
/auth                     # 공급자와 API 키 설정

내장 UI 언어는 중국어 간체, 영어, 러시아어, 독일어, 일본어, 브라질 포르투갈어, 프랑스어, 카탈루냐어뿐이고 저장소의 UI 번역 파일에도 한국어가 없습니다(2026년 10월 1일 확인). 그래서 메뉴는 영어로 나오며, 이 페이지는 화면에 보이는 영어 문구를 그대로 인용합니다. 모델 답변 언어는 UI와 별개라서 /language output Korean으로 한국어로 고정할 수 있습니다.

터미널 외에도 데스크톱 앱, 브라우저에서 여는 웹 UI(qwen serve --open, 실험 기능), VS Code·Zed·JetBrains 연동, 스크립트와 CI용 헤드리스 실행(qwen -p "...")이 있습니다. 모두 같은 무료 저장소에 들어 있고, 추론 비용은 따로 냅니다.

/auth로 연결 대상 고르기

/auth(별칭 /login)를 열면 ‘Select authentication method:’ 화면이 나오고, 최상위 선택지는 세 가지입니다. Qwen OAuth를 고르려 하면 ‘Discontinued — switch to Coding Plan or API Key’라는 안내가 뜹니다.

ModelStudio의 세 가지는 같은 청구서를 내는 세 방법이 아닙니다. 문서는 각각에 별도 엔드포인트와 별도 키를 두며, 키 종류와 baseUrl이 맞지 않으면 동작하지 않습니다. Coding Plan은 2026년 10월 1일 기준 ‘수량 한정·선착순, 매일 0시(UTC+8)에 보충’으로 표시되어 있어 날에 따라 가입이 안 될 수 있습니다. Coding Plan에서 작업 하나는 여러 번의 모델 호출로 계산되며, Alibaba는 단순 작업 5~10회, 복잡한 작업 10~30회 이상이 보통이라고 설명합니다. 요금 비교는 영어 페이지 Qwen Code pricing에서 자세히 다룹니다.

Claude나 GPT 쓰기: settings.json의 Custom Provider

Qwen Code 인증 문서는 OpenAI, Anthropic, Google, OpenRouter, 자체 엔드포인트 같은 서드파티 연결에 ~/.qwen/settings.json의 modelProviders를 권장합니다. Kunavo라면 다음과 같습니다.

{
  "modelProviders": {
    "openai": [
      {
        "id": "claude-sonnet-5",
        "name": "Claude Sonnet 5 (Kunavo)",
        "baseUrl": "https://api.kunavo.com/v1",
        "description": "Kunavo, OpenAI 호환",
        "envKey": "KUNAVO_API_KEY"
      }
    ]
  },
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "claude-sonnet-5"
  }
}

# 키는 settings.json에 직접 쓰지 말고 .qwen/.env 나 환경 변수로
echo 'KUNAVO_API_KEY=sk-kn-...' >> ~/.qwen/.env

디버깅 시간을 아껴 주는 네 가지:

• baseUrl은 /v1까지. 모델 공급자 참조 문서는 ‘/v1/chat/completions 전체 경로가 아니라 API의 /v1 루트를 지정하라, 요청 경로는 SDK가 붙인다’고 명시합니다. 경로까지 쓰면 인증 오류가 아니라 404가 납니다.
• 키를 두는 곳. Qwen Code는 envKey에 적은 이름의 환경 변수에서 키를 읽습니다. 우선순위는 셸 export, .env 파일(.qwen/.env 권장, 처음 찾은 파일 하나만), settings.json의 env 순이고, 마지막은 평문 저장이라 권하지 않습니다.
• CLI 플래그보다 설정 파일이 이깁니다. 결정 순서는 /auth 입력값 → 선택된 modelProviders 항목 → CLI 인자 → 환경 변수 → settings.json입니다. --openai-base-url이 무시되는 것처럼 보이는 이유입니다. 예전 설명에 나오는 security.auth.apiKey와 security.auth.baseUrl은 지원 중단 예정입니다.
• 처음엔 Chat Completions로. wireApi를 생략하면 Chat Completions 형식입니다. "responses"로 바꾸면 엔드포인트 자동 판별도, 실패 시 자동 전환도 없습니다. modelProviders 수정은 실행 중인 세션에도 바로 반영됩니다(/model을 다시 열면 보입니다).

Kunavo 카탈로그에는 Qwen 텍스트 모델이 없습니다. 이건 Qwen을 싸게 쓰는 방법이 아니라, Qwen Code 안에서 Claude와 GPT를 선불 잔액 하나로 쓰는 방법입니다. 또한 Kunavo는 Qwen Code를 자사 엔드포인트에 실제로 돌려 본 검증을 하지 않았습니다. 설정은 영어 Qwen Code 설정 페이지와 마찬가지로 공식 문서를 보고 작성했습니다. 지금 쓰는 경로는 남겨 둔 채로 시험하세요.

첫 작업과 자주 쓰는 명령어

README가 예로 드는 첫 요청은 ‘이 저장소를 설명하고 어디서부터 보면 되는지 알려 줘’ 같은 것입니다. 파일 읽기와 도구 호출이 한 번에 확인되니까요. 인사만 해서는 연결 문제를 찾을 수 없습니다.

yolo 같은 자동 승인 모드는 문서 스스로 ‘신뢰할 수 있거나, 샌드박스이거나, 버려도 되는 환경에서만 쓰라’고 경고합니다. /stats model의 추정 비용은 Qwen Code의 계산이지 청구 금액이 아닙니다. 실제 금액은 연결한 공급자의 사용 기록에서 확인하세요.

알아 둘 제한

• 내장 web_search는 연결 대상에 따라 켜지고 꺼집니다. DashScope 서버 측 검색을 쓰기 때문에, ModelStudio Standard API Key와 Token Plan, 인식되는 DashScope 호스트를 가리키는 항목에서는 켜지고, Coding Plan에서는 꺼지며(그 엔드포인트에서 미검증), 서드파티나 다른 호스트의 커스텀 엔드포인트에서도 꺼집니다(web_search 문서). 필요하면 MCP 검색 서버를 붙이세요.
• Kunavo 경로는 채팅만. Kunavo에는 임베딩, 음성 합성, 음성 인식 모델이 없습니다. Qwen Code의 Live Voice는 DashScope 엔드포인트가 필수라, 채팅 모델을 어디로 돌리든 별도 키를 그대로 씁니다.

Kunavo로 시험할 때 결제

Kunavo는 월정액 없는 선불 충전 방식이고 토큰 단위로 잔액에서 차감합니다. 최소 충전액은 $10이며, Stripe 체크아웃에서 카드(Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Link를 쓸 수 있습니다. 카카오페이·네이버페이 같은 국내 간편결제는 없습니다. 결제 안내를 확인하고 계정을 만들어 키를 발급하세요. 첫 요청 뒤에는 사용 기록에서 실제 금액을 확인하는 것이 가장 확실합니다.

FAQ

2026년 10월 1일 확인: Qwen Code README, 인증·모델 공급자·명령어·web_search 문서(main 브랜치), 저장소의 UI 번역 파일 목록, npm의 @qwen-code/qwen-code 0.24.7, Alibaba Cloud의 Coding Plan과 Token Plan 페이지. Kunavo는 Qwen Code를 자사 엔드포인트에 실행해 보지 않았습니다.