Qwen Code nasıl kullanılır? Adım adım rehber

Qwen Code’u kullanmak için qwen CLI’ı resmi betikle, npm ya da Homebrew ile kurarsın, bir proje klasöründe qwen çalıştırırsın, /auth ile bir model sağlayıcısı seçersin ve ne istediğini anlatırsın. Qwen Code kodunu okur, dosyaları düzenler ve komut çalıştırır; ne zaman onay isteyeceğini seçtiğin onay modu belirler. Ücretsiz Qwen OAuth katmanı 15 Nisan 2026’da sona erdiği için bir sağlayıcıdan API anahtarına ya da plana veya yerel bir modele ihtiyacın var.

Temel döngü bu. Bu rehber gerisini anlatıyor: giriş seçenekleri ve ücretsiz katmanın yerini ne aldı, OpenAI uyumlu anahtarlar ve yerel modeller, model seçimi, onay modları, QWEN.md, MCP sunucuları, betikler için başsız mod ve Qwen Code’u diğer ajanların yanında çalıştırmak. Buradaki her şey Ekim 2026 itibarıyla Qwen Code’un resmi deposuna ve belgelerine dayanıyor.

Qwen Code nedir?

Qwen Code, Alibaba’daki Qwen ekibinin Apache-2.0 lisansıyla yayımladığı bir terminal kodlama ajanı. Gemini CLI’dan yola çıktı, bu yüzden Google’ın ajanını kullandıysan düzeni tanıdık gelecek; ama uzun zamandır ayrı geliştiriliyor. Qwen’in kendi kodlama modelleri için ayarlanmış, yine de onlara bağlı değil: OpenAI, Anthropic ve Gemini API formatlarını konuşur ve yerel modellerle çalışır.

Terminalin yanında projenin bir masaüstü uygulaması, VS Code, Zed ve JetBrains entegrasyonları ve TypeScript, Python ve Java SDK’ları da var. Bu rehber CLI’a odaklanıyor.

1. Adım: Qwen Code’u kur

Betikle kurduktan sonra qwen komutu PATH’e girsin diye terminalini yeniden başlat. npm paketi Node.js 22 ya da daha yenisini ister. Güncellemek için aynı npm ya da Homebrew komutunu tekrar çalıştır.

2. Adım: /auth ile giriş yap

Bir projeye geç ve Qwen Code’u başlat:

cd my-project
qwen

İlk çalıştırmada ve sonra istediğin zaman /auth ile Qwen Code bir model bağlamanın dört yolunu gösterir:

Hangi kimlik doğrulamanın etkin olduğunu görmek için oturumun içinde /doctor çalıştır. Eski qwen auth kabuk komutu kaldırıldı; sağlayıcı değiştirmenin yeri artık /auth.

Ücretsiz Qwen OAuth katmanına ne oldu?

Uzun süre en kolay başlangıç, Qwen OAuth ile bir qwen.ai hesabıyla giriş yapıp ücretsiz günlük kota almaktı. Belgeler artık Qwen OAuth ücretsiz katmanının 15 Nisan 2026’da kaldırıldığını söylüyor. Artık /auth içinde görünmüyor ve önbellekte eski bir token kalmış olsa bile bu yoldan gelen yeni istekler reddediliyor. Eski bir eğitimi izlediysen ve ajan birden yanıt vermeyi bıraktıysa sebebi bu. Bunun yerine yukarıdaki seçeneklerden birini seç. 2026’da hâlâ ücretsiz olanları ücretsiz yapay zeka kodlama araçları derlememiz anlatıyor.

OpenAI uyumlu herhangi bir API anahtarı kullan

Betikler ve sunucular için en hızlı kurulum üç ortam değişkeni:

export OPENAI_API_KEY="sk-..."
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export OPENAI_MODEL="your-model-id"
qwen

Bunlar, sağlayıcıların çoğunu kapsayan OpenAI uyumlu protokolün değişkenleri. Anthropic ve Gemini formatlarının kendi değişkenleri var (ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, ANTHROPIC_MODEL ve GEMINI_API_KEY, GEMINI_MODEL).

Anahtarları her kabukta dışa aktarmak yerine bir .env dosyasında tutabilirsin. Qwen Code projede ve üst klasörlerinde .qwen/.env ile .env dosyalarını, ardından ~/.qwen/.env ve ~/.env dosyalarını arar ve yalnızca bulduğu ilkini yükler. Komut satırı bayrakları kabuk değişkenlerini, kabuk değişkenleri .env dosyasını, .env de settings.json içindeki env bloğunu geçersiz kılar.

Kalıcı bir kurulum için sağlayıcıyı ~/.qwen/settings.json içinde tanımla. envKey, anahtarı tutan değişkenin adını verir:

{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3-coder-plus",
        "name": "qwen3-coder-plus",
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "description": "Qwen3-Coder via Dashscope",
        "envKey": "DASHSCOPE_API_KEY"
      }
    ]
  },
  "security": { "auth": { "selectedType": "openai" } },
  "model": { "name": "qwen3-coder-plus" }
}

Dosya anahtarın kendisini içeren bir env bloğunu da kabul eder, ama anahtar orada düz metin olarak durur. Belgeler proje sırları için Git dışında tutulan .qwen/.env dosyasını öneriyor.

Ollama ile yerel modeller

Ollama, vLLM ve LM Studio OpenAI uyumlu bir API sunar; yani yerel bir model, baseUrl değeri yerel olan bir openai sağlayıcısından ibaret. Ollama gerçek bir anahtar istemez, herhangi bir yer tutucu yeter:

{
  "env": { "OLLAMA_API_KEY": "ollama" },
  "modelProviders": {
    "openai": [
      {
        "id": "qwen2.5-7b",
        "name": "Qwen2.5 7B (Ollama)",
        "envKey": "OLLAMA_API_KEY",
        "baseUrl": "http://localhost:11434/v1",
        "generationConfig": { "contextWindowSize": 32768 }
      }
    ]
  }
}

id, Ollama’daki model adıyla aynı olmalı. Küçük bir yerel model uzun ajan oturumlarında zorlanır; hangi modellerin ve ne kadar belleğin işi görür hale getirdiğini yerel model ile kodlama ajanı rehberimiz anlatıyor.

3. Adım: bir model seç

Oturumun içinde /model, sağlayıcılarının sunduğu modellerle bir seçici açar; /model <model-id> doğrudan geçiş yapar. Kabuktan qwen --model qwen3-coder-plus (ya da -m) modeli tek bir çalıştırma için ayarlar. Düşünen modellerde /effort, sağlayıcı destekliyorsa akıl yürütme düzeyini belirler.

Hangi modelleri alacağın sağlayıcıya bağlı. Ekim 2026 itibarıyla Alibaba Coding Plan; qwen3-coder-plus, qwen3-coder-next ve qwen3.7-plus gibi Qwen modellerinin yanında GLM, Kimi ve MiniMax gibi üçüncü taraf modelleri listeliyor. Kullandıkça öde bir anahtar, o sağlayıcının API’si neyi sunuyorsa onu verir.

4. Adım: bir oturumun temelleri

Qwen Code ekranı, projenle bir sohbet. Sürekli kullanacağın birkaç şey:

• @yol mesajına bir dosya ekler; @klasör/ bir klasördeki metin dosyalarını okur.
• !komut bir kabuk komutu çalıştırır, örneğin !git status. Tek başına ! yazınca, tekrar ! yazana kadar kabuk moduna geçersin.
• Shift+Tab (Windows’ta Tab) onay modları arasında döner.

Kabuktan qwen --continue mevcut projenin son oturumunu, qwen --resume <id> ise belirli bir oturumu açar.

5. Adım: onay modları

Qwen Code’un, sormadan neler yapabileceğini belirleyen beş onay modu var:

Qwen Code kutudan Auto modunda çıkar: model tabanlı bir sınıflandırıcı güvenli işlemleri onaylar, riskli olanları engeller. Geçmek için /approval-mode plan ya da Shift+Tab kullan veya qwen --approval-mode plan ile başla. Önemsiz olmayan her iş için iyi bir alışkanlık: Plan’da başla, bir yaklaşımda anlaş, sonra uygulamak için Auto-Edit’e ya da Auto’ya geç. YOLO’yu yanlış bir komutun kalıcı zarar veremeyeceği konteynerlere ya da atılabilir makinelere sakla.

6. Adım: QWEN.md ve proje bağlamı

QWEN.md, Qwen Code’un her oturumun başında yüklediği brifing: derleme ve test komutları, kurallar, uzak durulacak klasörler. Üç yerde durabilir ve hepsi yüklenir:

/init çalıştırınca Qwen Code projeyi tarar ve bir başlangıç QWEN.md dosyası yazar; dosya zaten varsa üzerine yazmak yerine eklemeler önerir. Depoda diğer araçlar için zaten bir AGENTS.md varsa Qwen Code onu da okur. QWEN.md içinde @docs/git-workflow.md başka bir dosyayı içeri alır.

# Proje kuralları

- Paket yöneticisi: pnpm. Bir görevi bitirmeden önce `pnpm test` çalıştır.
- TypeScript strict modu; yeni kodda `any` yok.
- src/generated/ içindeki dosyaları asla düzenleme.
- Git iş akışı: @docs/git-workflow.md

Kısa tut; belgeler, dosya uzadıkça Qwen’in ona daha az güvenilir şekilde uyduğunu belirtiyor. Qwen Code ayrıca ~/.qwen/projects/<proje>/memory/ içinde kendi otomatik belleğini tutar; düzenleyebileceğin ya da /memory içinden kapatabileceğin düz Markdown dosyaları. Yalnızca bazı dosyalar için geçerli kurallar için .qwen/rules/, paths: alanı olan Markdown dosyaları alır. Böyle bir dosyaya ne yazılacağını CLAUDE.md ve AGENTS.md nasıl yazılır anlatıyor; QWEN.md için de aynen geçerli.

7. Adım: MCP sunucuları

MCP sunucuları Qwen Code’a tarayıcı, iş takip sistemi ya da belge arama gibi yeni araçlar verir. Bir sunucu eklemenin en hızlı yolu qwen mcp komutu:

# HTTP üzerinden uzak bir sunucu
qwen mcp add --transport http my-server http://localhost:3000/mcp

# süreç olarak başlatılan yerel bir sunucu (varsayılan taşıma stdio)
qwen mcp add pythonTools -e DATABASE_URL=$DB_CONNECTION_STRING python -m my_mcp_server

# geri kaldır
qwen mcp remove my-server

Sunucular ~/.qwen/settings.json dosyasının mcpServers bloğuna (varsayılan kullanıcı kapsamı) ya da --scope project ile .qwen/settings.json dosyasına yazılır. Bu bloğu elle de düzenleyebilirsin: yerel bir süreç için command ve args, HTTP sunucusu için httpUrl. --include-tools ve --exclude-tools bir sunucunun hangi araçları sunacağını sınırlar. Qwen Code zaten çalışıyorsa yeniden başlat, sonra sunucunun bağlandığını kontrol etmek ve araçlarını görmek için /mcp yaz.

8. Adım: betikler ve CI için başsız mod

-p (ya da --prompt) etkileşimli arayüz olmadan tek bir görev çalıştırır; stdin de çalışır:

qwen -p "Summarize what changed in src/ since the last tag"
cat error.log | qwen -p "Explain this stack trace"
qwen -p "List the TODOs in this repo" --output-format json > todos.json

--output-format; text, json ya da stream-json alır. qwen --continue -p "..." son oturumdan devam eder, böylece bir betik birkaç adımda çalışabilir. Başsız bir çalıştırmanın dosya düzenlemesine izin vermek için --approval-mode auto-edit gibi bir onay modu ayarla ya da yalıtılmış bir çalıştırıcıda --yolo kullan. Belgeler açıkça söylüyor: --yolo bir sandbox açmaz, kabuk komutları kullanıcının yetkileriyle çalışır. Bütçeler, gözetimsiz bir çalıştırmanın kontrolden çıkmasını önler:

qwen -p "Fix the failing unit tests" --yolo \
  --max-session-turns 30 --max-wall-time 10m --output-format json

--max-wall-time ya da --max-tool-calls sınırını aşan bir çalıştırma 55, --max-session-turns sınırını aşan 53 koduyla çıkar; böylece CI iki durumu ayırt edebilir. Gerçek yalıtım için qwen -s araçları bir sandbox içinde çalıştırır (macOS’ta Seatbelt, diğerlerinde Docker ya da Podman).

Sık yapılan hatalar

• Ajan Nisan 2026’dan sonra çalışmayı bıraktı. Kaldırılan ücretsiz Qwen OAuth katmanındaydın. /auth çalıştır ve başka bir sağlayıcı seç.
• “qwen auth” bir kaldırılma uyarısı yazdırıyor. Komut artık yok; oturumda /auth kullan, kontrol için /doctor çalıştır.
• QWENCLOUD_API_KEY ya da DASHSCOPE_API_KEY içindeki anahtar yok sayılıyor. Sağlayıcıya özel değişkenler ancak settings.json içindeki bir sağlayıcı onları envKey olarak verdiğinde çalışır. Aksi halde OPENAI_API_KEY kullan.
• Yeni bir MCP sunucusu görünmüyor. Qwen Code çalışırken eklendi. Aynı projede yeniden başlat.
• Uzun oturumlar yavaşlıyor ve pahalılaşıyor. /compress ya da /clear kullan, QWEN.md’yi kısa tut ve ihtiyacın olmayan MCP sunucularını kapat.

Qwen Code’u diğer CLI’ların yanında çalıştırmak

Qwen Code’un kendi alt ajanları ve worktree desteği var, ama bunlar Qwen Code’un içinde kalıyor. Bir görevde Qwen Code’u, başka birinde Claude Code’u, üçüncüsünde Gemini CLI’ı istiyorsan yine terminal sekmeleri arasında koşturmaya dönersin. AgentVera bu CLI’ları kendi kurulumların ve girişlerinle, gerçek terminallerde yan yana çalıştıran bir masaüstü uygulaması. Qwen Code desteği şöyle çalışır:

• Senin girişin. Qwen Code kendi girişini kullanır; ajanın terminali ilk açılışta sorar. qwen kurulu değilse AgentVera onu npm i -g @qwen-code/qwen-code ile kurar.
• Her ajana bir oturum. Her ajan kendi oturum kimliğiyle (--session-id) başlar; kaydedilmiş bir oturum --resume ile yeniden açılır.
• Rol ve model. Ajanın rolü --append-system-prompt ile Qwen Code’un sistem prompt’una eklenir. Qwen Code’un varsayılanı için Model alanını boş bırak ya da bir model seç; AgentVera onu --model ile verir.
• Her açılışta MCP. AgentVera’nın MCP yöneticisindeki sunucular ve AgentVera’nın tarayıcısı --mcp-config ile verilir; kendi settings.json dosyan olduğu gibi kalır.
• Bölmeler, inceleme ve akışlar. Qwen Code’u çalışma alanı ızgarasında Claude Code’un yanında çalıştır; her ajan kendi git worktree kopyasında çalışır ve bir tur bittiğinde otomatik kod incelemesi devreye girer. Qwen Code ajanları toplu mesajlarda, zamanlanmış görevlerde ve bir ajanın yanıtının sıradakine gittiği akışlarda (Pro ve Team) da çalışır.
• Birden fazla hesap. Ayarlar → Hesaplar → Diğer ajanların hesapları altında API anahtarlarıyla çalışan ek Qwen hesapları ekleyebilir ve bir yedek sırası belirleyebilirsin (Pro ve Team).

Dengeleri de dürüstçe söyleyelim: yalnızca ücretsiz, barındırılan bir model istiyorsan Qwen Code artık bunu sunmuyor; yukarıda bağlantısını verdiğimiz derlemedeki ücretsiz araçlar daha iyi bir başlangıç. Farklı bir iş akışına sahip, sağlayıcıdan bağımsız bir ajan istiyorsan en yakın alternatif opencode. Izgara, worktree’ler, kod incelemesi ve MCP yöneticisi ücretsiz planda. Denemek için AgentVera’yı indir.

Toparlarsak

Qwen Code’u kullanmak için kur, bir projede qwen çalıştır ve ücretsiz Qwen OAuth katmanı artık olmadığına göre /auth ile bir sağlayıcı seç. OpenAI uyumlu her anahtar, yerel modeller dahil, OPENAI_* değişkenleri ya da settings.json üzerinden çalışır. Riskli işe Plan modunda başla, proje kurallarını QWEN.md’ye koy, araçları qwen mcp add ile ekle ve bir betik ya da CI işi ajana ihtiyaç duyduğunda bütçelerle birlikte qwen -p kullan. Bundan sonra asıl karar, bütçene hangi sağlayıcının ve modelin uyduğu; Qwen Code ikisini de istediğin an değiştirmene izin veriyor.