Qwen Code가 하는 일: 터미널에서 코드를 읽고 고치는 오픈소스 에이전트

Qwen Code는 알리바바 Qwen 팀이 공개한 오픈소스 코딩 에이전트입니다. 프로젝트 폴더에서 qwen을 실행하고 "이 저장소 구조를 설명해 줘", "이 버그를 고쳐 줘"처럼 말로 시키면 파일을 읽고, 명령을 돌리고, 코드를 고친 뒤 결과를 보여 줍니다. 클로드 코드나 제미나이 CLI를 써 봤다면 익숙한 방식이고, 실제로 이 프로젝트는 구글 제미나이 CLI 0.8.2 버전에서 출발해 0.1 버전부터 따로 개발되고 있다고 README에 적혀 있습니다.

요즘 이 저장소가 다시 눈에 띄는 이유는 쓰는 곳이 넓어졌기 때문입니다. 터미널 말고도 데스크톱 앱, 브라우저에서 여는 웹 화면, VS Code와 JetBrains 같은 편집기 연동, 텔레그램 같은 메신저 연결까지 한 저장소에서 제공합니다. 스크립트 안에서 qwen -p로 한 번만 묻고 끝내는 방식도 있어서 반복 작업을 자동으로 돌리는 데도 쓸 수 있습니다.

가장 큰 특징은 모델을 고르는 폭입니다. README는 OpenAI, Anthropic, Gemini, Qwen 방식의 API를 모두 받을 수 있고 직접 띄운 로컬 모델도 붙일 수 있다고 소개합니다. 같은 도구로 회사 API, 다른 업체 모델, 내 컴퓨터 모델을 바꿔 가며 쓸 수 있다는 뜻이라, 특정 회사 구독에 묶이기 싫은 사람이 관심을 갖는 지점입니다.

근거 [1]

Qwen Code 설치 방법: npm 한 줄, Node.js 22 이상 필요

설치 방법은 세 가지입니다. 리눅스와 맥은 공식 설치 스크립트를 curl로 받아 실행하고, 윈도우는 PowerShell에서 irm 명령으로 받습니다. 이미 Node.js를 쓰고 있다면 npm 전역 설치가 가장 간단하고, 맥이나 리눅스에서 Homebrew를 쓰면 brew install qwen-code도 됩니다.

npm으로 설치할 때 먼저 볼 것은 Node.js 버전입니다. 패키지 정보에 Node.js 22 이상이 필요하다고 적혀 있어서, 우분투 기본 저장소에 들어 있는 오래된 Node.js나 20 버전으로는 실행 단계에서 막힐 수 있습니다. node -v로 버전을 먼저 보고, 낮으면 nvm 같은 버전 관리 도구로 22 이상을 깔아 두는 편이 편합니다.

이번에는 윈도우 서버에서 Node.js 26으로 빈 폴더에 npm install @qwen-code/qwen-code@latest를 실행했습니다. 패키지 12개가 들어왔고 내려받는 데 4분 정도 걸렸습니다. 음성 입력용 보조 패키지의 설치 스크립트가 허용되지 않았다는 npm 경고가 한 줄 나왔지만, 버전 확인과 실행에는 영향이 없었고 qwen --version은 0.27.4를 보여 줬습니다.

bash · 윈도우는 PowerShell에서 공식 install-qwen-standalone.ps1 스크립트를 irm으로 받는다.
# 리눅스, 맥 공식 설치 스크립트
curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.sh | bash

# Node.js 22 이상이 있으면 npm으로
npm install -g @qwen-code/qwen-code@latest

# 설치 확인과 실행
qwen --version
cd 내-프로젝트-폴더
qwen

근거 [1] [3]

Qwen Code 무료로 쓸 수 있나: 지금 인증 메뉴 다섯 가지

검색하면 Qwen Code를 무료로 쓰는 법이라는 글이 많이 나오는데, 지금 공식 인증 문서를 기준으로 보면 이야기가 다릅니다. 처음 실행하거나 /auth를 입력하면 다섯 가지 길이 나옵니다. Qwen 계정 로그인, QwenCloud, 알리바바 ModelStudio, 다른 업체 API, 직접 연결하는 사용자 지정 공급자입니다.

이 가운데 Qwen 계정으로 로그인하는 방식은 chat.qwen.ai의 Plus 또는 Pro 구독이 있어야 한다고 문서에 적혀 있습니다. 구독이 없으면 먼저 가입하고 돌아오라고 안내합니다. QwenCloud는 월 크레딧이 붙는 Token Plan이나 쓴 만큼 내는 API 키이고, ModelStudio의 Coding Plan은 월 정액에 주간 사용량이 정해진 상품입니다. 다른 업체 메뉴에는 DeepSeek, Grok, MiniMax, Z.AI, Kimi, OpenRouter 같은 이름이 있고 모두 그 회사 API 키가 필요합니다.

Qwen Code 프로그램 자체는 무료 오픈소스지만, 모델을 돌리는 비용은 따로입니다. 별도 비용 없이 쓰는 길은 이미 가진 구독이나 무료 한도가 있는 API를 붙이거나, 마지막 메뉴인 사용자 지정 공급자로 내 컴퓨터에 띄운 로컬 모델을 연결하는 것 정도입니다. 그래서 로컬 모델 쪽을 직접 붙여 봤습니다.

Qwen Code 공식 문서 Authentication 페이지. Qwen Account with Subscription은 Plus or Pro subscription으로 로그인한다는 설명, QwenCloud, Alibaba ModelStudio, Third-party Providers, Custom Provider 다섯 항목이 이어진다
첫 번째 Qwen 계정 로그인은 Plus 또는 Pro 구독이 있어야 쓸 수 있다.Qwen Code Docs · 원문

근거 [2]

Qwen Code 로컬 모델 연결: llama.cpp로 Qwen3 1.7B 붙여 본 결과

로컬 모델은 OpenAI 방식 주소를 열어 주는 프로그램이면 어느 것이든 붙일 수 있습니다. 이번에는 llama.cpp의 윈도우용 CPU 빌드에서 llama-server를 켜고, 1.1GB 정도인 Qwen3 1.7B 4비트 모델 파일을 올렸습니다. 대화 길이는 3만 2천 토큰으로 잡았습니다. 그다음 OPENAI_BASE_URL에 llama-server 주소를, OPENAI_MODEL에 모델 이름을 넣고 OPENAI_API_KEY에는 아무 값이나 넣으면 Qwen Code가 이 서버를 모델로 씁니다.

시험 과제는 단순하게 골랐습니다. 다섯 줄짜리 지출 기록 CSV 파일을 두고 "항목별 합계를 계산해서 summary.md로 저장해 줘"라고 시켰습니다. 처음에는 qwen -p로 한 번 묻는 방식, 그다음은 qwen serve로 웹 화면을 열어 같은 요청을 보냈습니다. 웹 화면 아래쪽 모델 칸에 qwen3-1.7b가 그대로 잡혀서 연결 설정 자체는 문제없이 됐습니다.

결과는 답 없이 끝났습니다. llama-server 기록을 보면 첫 요청의 프롬프트가 1만 2천 토큰 안팎이었고, 4코어 CPU는 이걸 초당 14토큰 정도로 읽었습니다. 다 읽는 데만 15분 가까이 걸리는 속도입니다. Qwen Code는 4분쯤 기다리다 요청을 끊고 다시 보냈고, 10분 동안 기다려도 첫 글자가 나오지 않았습니다. 웹 화면에서 보낸 요청은 1만 5천 토큰 안팎으로 더 길었고 속도는 초당 17토큰 정도였습니다.

연결이 제대로 됐는지는 Qwen Code 안에서 /doctor를 입력해 지금 인증 상태를 보는 방법이 문서에 나와 있습니다. 예전 안내 글에 자주 나오는 qwen auth 명령은 지금 버전에서 빠졌고, 대화형 /auth나 settings.json, 환경변수로 설정하도록 바뀌었습니다. 같은 설정을 계속 쓸 거라면 홈 폴더 아래 .qwen 폴더의 settings.json에 공급자 주소와 모델 이름을 적어 두면 실행할 때마다 환경변수를 넣지 않아도 됩니다.

Qwen Code 웹 화면. 왼쪽 목록에 같은 요청 세 개가 있고 오른쪽 대화에는 expenses.csv 파일을 읽고 항목별 합계를 summary.md로 저장해줘라는 요청만 있다. 아래 입력창에 Classifier Approval과 qwen3-1.7b 모델이 보인다
모델 칸에 qwen3-1.7b가 잡혔지만 요청 뒤로 답이 나오지 않는다.BlueBWorks · 원문
bash · --jinja는 모델의 도구 호출 형식을 쓰게 하는 옵션이다. 모델 이름은 llama-server의 --alias 값과 맞춘다.
# 1. 로컬 모델 서버 켜기 (llama.cpp)
llama-server -m Qwen3-1.7B-Q4_K_M.gguf --jinja -c 32768 --port 8089

# 2. Qwen Code가 그 서버를 쓰게 하기 (리눅스, 맥)
export OPENAI_BASE_URL="http://127.0.0.1:8089/v1"
export OPENAI_MODEL="qwen3-1.7b"
export OPENAI_API_KEY="local"
qwen

# 윈도우 PowerShell이라면
$env:OPENAI_BASE_URL="http://127.0.0.1:8089/v1"
$env:OPENAI_MODEL="qwen3-1.7b"
$env:OPENAI_API_KEY="local"

근거 [2] [4] [5]

로컬 모델이 느린 이유: 코딩 에이전트는 첫 요청부터 길다

채팅 앱에 짧은 질문을 던질 때와 달리 코딩 에이전트는 매 요청마다 긴 안내문을 함께 보냅니다. 어떤 도구를 쓸 수 있는지, 파일을 어떻게 읽고 고치는지, 어떤 순서로 일해야 하는지가 모두 들어가서 사용자가 쓴 한 줄짜리 요청이 1만 토큰이 넘는 프롬프트가 됩니다. 이 앞부분을 다 읽어야 첫 글자가 나오기 때문에, 그래픽카드 없이 CPU만 쓰는 환경에서는 대기 시간이 바로 몇 분 단위로 늘어납니다.

메모리도 함께 봐야 합니다. 대화 길이를 3만 2천 토큰으로 잡은 llama-server는 1.1GB 모델을 올렸는데도 메모리를 3GB 넘게 썼고, 8GB 서버의 남은 메모리가 400MB대까지 내려갔습니다. 같은 컴퓨터에서 브라우저나 다른 프로그램을 같이 쓰면 전체가 느려지는 수준입니다. 1.7B는 작은 모델이라 도구를 정확히 부르는 능력도 약한 편이니, 속도 문제가 풀려도 결과물 품질은 따로 따져 봐야 합니다.

로컬로 제대로 쓰려면 그래픽카드가 있는 PC에서 7B 이상 코딩 모델을 올리는 쪽이 현실적입니다. 그래픽카드가 없는 노트북이나 저가 서버라면 로컬 모델은 맛보기 정도로 생각하고, 이미 결제하고 있는 서비스의 API를 붙이거나 쓴 만큼 내는 API 키로 시작하는 편이 시간 낭비가 적습니다.

근거 [2] [4]

Qwen Code와 클로드 코드, 제미나이 CLI 차이

쓰는 모습은 셋이 거의 같습니다. 터미널에서 프로젝트 폴더를 열고 말로 일을 시키면, 에이전트가 파일을 읽고 명령을 돌리고 고친 내용을 보여 줍니다. Qwen Code는 제미나이 CLI에서 갈라져 나온 만큼 화면 구성과 명령 이름에 비슷한 부분이 남아 있습니다.

차이는 모델 쪽에서 납니다. 클로드 코드와 제미나이 CLI는 각 회사 계정과 모델을 기본으로 쓰도록 만들어졌고, Qwen Code는 처음부터 여러 회사 API와 로컬 모델을 바꿔 끼우는 것을 내세웁니다. README에는 같은 Qwen 3.7 Max 모델로 SWE-bench Verified 500문제를 세 번씩 풀게 했을 때 Qwen Code 일곱 개 버전의 평균이 76.40%에서 77.80% 사이였다는 숫자도 있는데, 이건 큰 상용 모델을 붙였을 때 이야기이고 작은 로컬 모델에 그대로 기대할 수치는 아닙니다.

웹 화면을 띄우는 qwen serve는 기본으로 127.0.0.1:4170에서 열리고, 같은 컴퓨터 안의 다른 프로그램은 인증 없이 코드 실행까지 할 수 있다고 README가 경고합니다. 여러 사람이 쓰는 서버에서 켠다면 QWEN_SERVER_TOKEN을 정하고 --require-auth를 붙여야 합니다. 받아 쓰는 기능이 많은 만큼, 처음에는 개인 PC의 연습용 폴더에서 승인 모드를 켠 채로 써 보는 편이 안전합니다.

근거 [1]