Qwen Code 사용법: 설치, /auth, 일본어 설정과 API 설정

Qwen Code는 Alibaba의 Qwen 팀이 공개한 오픈 소스(Apache-2.0) AI 코딩 에이전트입니다. 사용 흐름은 「설치 → 프로젝트에서 qwen 실행 → /auth로 연결 대상을 설정 → 작업 요청」의 4단계입니다. 다만 2026년 4월 15일 무료 Qwen OAuth 할당량이 종료되었으므로, 이전 설명대로 로그인해도 무료로는 작동하지 않습니다.이 페이지에서는 현재 /auth 메뉴에 따른 시작 방법, 한국어 표시로 전환하는 방법, Claude나 GPT를 사용하기 위한 사용자 지정 설정, 자주 사용하는 명령어를 순서대로 설명합니다. 최신 버전은 2026년 9월 29일 npm에 공개된 v0.24.7이며, 릴리스는 주 1회 이상 이루어지므로 현재 버전은 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 ui ja-JP          # 画面表示を日本語に
/language output Japanese   # モデルの回答を日本語に
/auth                       # 接続先と API キーを設定

/language ui ja-JP을 실행하면 화면이 일본어로 바뀌고, 이후 화면에 「인증 방법 선택」「도구 승인 모드」와 같은 Qwen Code 자체의 일본어 표시가 나타납니다. 이 페이지에서도 같은 표기를 사용합니다. 응답 언어는 UI 언어와 별개이며, /language output Japanese로 지정합니다.

터미널 외에도 데스크톱 앱, 브라우저에서 여는 Web UI(qwen serve --open, 실험적 기능), VS Code·Zed·JetBrains용 통합, 스크립트나 CI용 헤드리스 실행(qwen -p "...")이 제공됩니다. 모두 동일한 무료 저장소에 포함되며, 추론 비용은 별도입니다.

/auth로 연결 대상 선택

/auth(별칭 /login)을 열면 「인증 방법 선택」 화면이 나타나며, 최상위 선택지는 세 가지입니다. Qwen OAuth를 선택하려 하면 「종료 — Coding Plan 또는 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）, Apple Pay, Google Pay 및 Link를 사용할 수 있습니다. 결제 안내를 확인한 후 계정을 생성하고 키를 발급하세요. 첫 요청을 보낸 후에는 사용 기록에서 실제 청구 금액을 확인하는 것이 가장 확실합니다.

자주 묻는 질문

2026년 10월 1일 확인: Qwen Code의 README, 인증·모델 프로바이더·명령어·web_search 각 문서(main 브랜치), 일본어 UI 문자열(packages/cli/src/i18n/locales/ja.js), npm의 @qwen-code/qwen-code 0.24.7, Alibaba Cloud의 Coding Plan 및 Token Plan 페이지. Kunavo는 Qwen Code를 자체 엔드포인트에서 실행하지 않았습니다.