Qwen Code 初心者ガイド — 無料で使えるオープンソース CLI コーディングエージェント

qwen-code-beginner-guide-free-cli-coding-agent.md

Qwen Code 初心者ガイド — 無料で使えるオープンソース CLI コーディングエージェント

Claude Code の無料オープンソース代替として注目を集めている Qwen Code。Alibaba Cloud の Qwen チームが開発したターミナルベースの AI コーディングエージェントで、1日1,000リクエストまで無料で利用できます。この記事では、初めて使う人にもわかるように、インストールから実践的な使い方まで解説します。

Qwen Code とは何か

Qwen Code は、ターミナル（コマンドライン）で動く AI コーディングアシスタントです。自然言語で指示を出すと、コードの理解・生成・編集・実行を自律的に行います。

一言で言うと

「無料で使える Claude Code のオープンソース版」

Claude Code との違い

観点	Qwen Code	Claude Code
料金	無料（OAuth で1日1,000リクエスト）	従量課金（API 使用量に応じて）
ライセンス	Apache 2.0（オープンソース）	プロプライエタリ
ベースモデル	Qwen3-Coder	Claude
インターフェース	ターミナル CLI	ターミナル CLI
IDE 統合	VS Code, Zed, JetBrains	VS Code, JetBrains
MCP サポート	あり	あり
コード品質	実用的（オープンモデルとしてトップクラス）	最高品質
カスタマイズ	完全にカスタマイズ可能	限定的

できること

• コードベース全体を理解して質問に答える
• ファイルの作成・編集・削除
• シェルコマンドの実行
• Git 操作（コミット、diff 確認等）
• バグの発見と修正
• テストの作成と実行
• MCP サーバーとの連携

インストール手順

前提条件

Node.js 20 以上が必要です。まだインストールしていない場合は nodejs.org からダウンロードしてください。

# Node.js のバージョン確認
node --version
# v20.x.x 以上であること

インストール方法（3つから選択）

方法1: npm（推奨）

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

方法2: Homebrew（macOS / Linux）

brew install qwen-code

方法3: インストールスクリプト（Linux / macOS）

curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.sh | bash

インストール確認

qwen --version

バージョン番号が表示されれば成功です。

初回セットアップ — 認証

Qwen Code を使うには認証が必要です。2つの方法があります。

方法1: Qwen OAuth（推奨・無料）

最も簡単な方法です。

# Qwen Code を起動
qwen

# セッション内で認証コマンドを実行
/auth

ブラウザが開くので、qwen.ai のアカウントでログインします。アカウントがなければ無料で作成できます。

項目	内容
無料枠	1日1,000リクエスト
認証方法	ブラウザでの OAuth ログイン
認証情報の保存先	~/.qwen/ ディレクトリ
制約	SSH やコンテナ内では使用不可

方法2: API キー

他のモデルプロバイダー（OpenAI、Anthropic、Google 等）の API キーを使う方法です。

~/.qwen/settings.json を編集します。

{
  "env": {
    "DASHSCOPE_API_KEY": "sk-your-key-here"
  },
  "security": {
    "auth": {
      "selectedType": "openai-compatible"
    }
  },
  "model": {
    "name": "qwen3-coder"
  }
}

対応プロバイダー

プロバイダー	プロトコル	備考
Alibaba Cloud DashScope	OpenAI 互換	Qwen モデルの公式 API
ModelScope	OpenAI 互換	中国国内向け
OpenAI	OpenAI	GPT シリーズ
Anthropic	Anthropic	Claude シリーズ
Google	GenAI / Vertex AI	Gemini シリーズ
OpenRouter	OpenAI 互換	複数モデルのゲートウェイ
Ollama	OpenAI 互換	ローカル実行

基本的な使い方

起動

プロジェクトのディレクトリで qwen コマンドを実行します。

cd ~/my-project
qwen

ウェルカム画面が表示され、対話モードが始まります。

自然言語で指示を出す

日本語でも英語でも指示を出せます。

> このプロジェクトのフォルダ構成を説明して

> main.py にhello world関数を追加して

> 最近変更したファイルを教えて

> このバグを修正して: TypeError: 'NoneType' object is not subscriptable

> テストを書いて実行して

ファイルを参照する

@ を使ってファイルを直接参照できます。

> @src/app.py この関数のバグを見つけて

> @README.md の内容を日本語に翻訳して

主要コマンド一覧

セッション中に使えるスラッシュコマンドです。

コマンド	機能	使いどころ
/help	ヘルプ表示	使えるコマンドを確認したい時
/auth	認証方法の変更	別のプロバイダーに切り替える時
/compress	チャット履歴を圧縮	トークンを節約したい時
/clear	画面クリア	会話をリセットしたい時
/theme	テーマ変更	見た目を変えたい時
/language	言語設定	応答言語を変えたい時
/stats	セッション情報表示	トークン使用量を確認したい時
/quit	終了	セッションを終了する時

キーボードショートカット

ショートカット	機能
Ctrl+C	現在の処理をキャンセル
Ctrl+D	終了（空行で）
↑ / ↓	コマンド履歴の移動
Tab	補完

実践例 — よくある使い方5選

1. コードベースの理解

> このプロジェクトの全体的なアーキテクチャを説明して

> @src/auth/ 認証の仕組みを解説して

> データベースのスキーマを一覧にして

大規模なコードベースに初めて触れる時に有効です。Qwen Code がファイルを読み、構造を分析して説明してくれます。

2. バグ修正

> テストを実行して失敗したものを修正して

> このエラーログを見て原因を特定して: [エラーメッセージ]

> @src/api/handler.py 42行目付近のnullチェックが抜けてるので修正して

3. リファクタリング

> この関数を小さな関数に分割して

> このクラスにTypeScriptの型定義を追加して

> 重複しているコードを共通関数に抽出して

4. テスト作成

> @src/utils/parser.py のユニットテストを作成して

> 既存のテストを参考にして、新しい機能のテストを書いて

5. Git 操作

> 変更したファイルを確認して

> 変更内容を要約したコミットメッセージを作って

> 最近のコミット履歴を見せて

ヘッドレスモード — 自動化と CI/CD

対話モードだけでなく、スクリプトから非対話的に実行することもできます。

# 単発の質問
qwen -p "このプロジェクトのREADMEを生成して"

# JSON 出力（CI/CD 向け）
qwen -p "テストを実行して結果を報告して" --output-format json

CI/CD での活用例

# GitHub Actions での例
- name: AI Code Review
  run: |
    qwen -p "最新のコミットのコードレビューをして" --output-format json

ヘッドレスモードでは OAuth 認証が使えないため、API キー認証を設定してください。

MCP サーバーとの連携

Qwen Code は MCP（Model Context Protocol）に対応しており、外部ツールやデータソースと連携できます。

設定方法

~/.qwen/settings.json に MCP サーバーを追加します。

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token"
      }
    }
  }
}

MCP でできること

MCP サーバー	できること
GitHub	Issue の操作、PR の作成・レビュー
ファイルシステム	指定ディレクトリのファイル操作
データベース	SQL クエリの実行
Slack	メッセージの送受信

MCP サーバーのツールは、Qwen Code の内蔵ツールと同じように自然言語で呼び出せます。

IDE 統合

ターミナルだけでなく、お気に入りの IDE から使うこともできます。

IDE	統合方法
VS Code	拡張機能をインストール
Zed	ネイティブサポート
JetBrains	プラグインをインストール

VS Code の場合、コマンドパレット（Cmd+Shift+P）から「Qwen Code」を検索して拡張機能をインストールします。

設定ファイルの構成

ユーザーレベル（全プロジェクト共通）

~/.qwen/settings.json

{
  "model": {
    "name": "qwen3-coder"
  },
  "security": {
    "auth": {
      "selectedType": "qwen-oauth"
    }
  }
}

プロジェクトレベル（特定プロジェクトのみ）

.qwen/settings.json（プロジェクトルートに配置）

プロジェクトレベルの設定はユーザーレベルの設定を上書きします。チームで共有する設定はこちらに記述します。

TypeScript SDK — プログラムから使う

Qwen Code は TypeScript SDK も提供しており、Node.js アプリケーションから直接 Qwen Code の機能を利用できます。

import { QwenCode } from '@qwen-code/sdk';

const qwen = new QwenCode({
  model: 'qwen3-coder',
  apiKey: process.env.DASHSCOPE_API_KEY,
});

const response = await qwen.chat('このコードをレビューして');
console.log(response);

独自の AI 開発ツールやワークフロー自動化を構築したい場合に有効です。

Qwen Code と Qwen-Agent の関係

Qwen Code は、Qwen-Agent フレームワークの上に構築されています。

Qwen-Agent（SDK / フレームワーク）
  ├── BrowserQwen（ブラウザエージェント）
  ├── Code Interpreter（コード実行エージェント）
  ├── Custom Assistant（カスタムエージェント）
  └── Qwen Code（CLI コーディングエージェント）← これ

• Qwen-Agent は「エージェントを作るための SDK」
• Qwen Code は「Qwen-Agent で作られた完成品のコーディングエージェント」

独自のエージェントを構築したい場合は Qwen-Agent を、すぐにコーディング支援を使いたい場合は Qwen Code を選んでください。

Mac Mini で Qwen Code を動かす — 構築ガイド

Mac Mini は静音・低消費電力・Apple Silicon の高メモリ帯域という特性から、ローカル LLM の実行に適しています。ここでは2つの構成を紹介します。

構成A: クラウド API を使う（最も簡単・5分で完了）

Mac Mini のスペックに関係なく、Qwen の無料クラウド API を使う方法です。

必要なもの:

• Mac Mini（スペック不問、Intel Mac でも可）
• インターネット接続
• Node.js 20+

手順:

# 1. Homebrew がなければインストール
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. Node.js インストール
brew install node

# 3. Qwen Code インストール
npm install -g @qwen-code/qwen-code@latest

# 4. 起動
qwen

# 5. セッション内で認証（ブラウザが開く）
/auth
# → qwen.ai アカウントでログイン（無料で作成可能）

これだけで 1日1,000リクエスト無料で利用開始できます。モデルはクラウド側の Qwen3-Coder が処理するため、Mac Mini のメモリや GPU は関係ありません。

構成B: 完全ローカルで動かす（Ollama 併用・オフライン対応）

コードを外部に送信せず、Mac Mini 内でモデルも動かす構成です。

ステップ1: Mac Mini のメモリに応じたモデル選択

Mac Mini	メモリ	推奨モデル	ダウンロードサイズ	推論速度
M4	16GB	qwen3:8b	約5GB	28-35 tok/s
M4	24GB	qwen3-coder:14b	約9GB	20-25 tok/s
M4 Pro	24GB	qwen3-coder:14b	約9GB	25-30 tok/s
M4 Pro	48GB	qwen3-coder:30b	約19GB	12-18 tok/s
M4 Pro	64GB	qwen3-coder:30b（Q5）	約25GB	15-20 tok/s

重要: コーディングエージェントとして実用的に使うには 24GB 以上を推奨します。16GB でも動きますが、8B モデルではツール呼び出しの精度が低下する場合があります。

ステップ2: Ollama のインストールとモデルダウンロード

# 1. Ollama インストール
brew install ollama

# 2. Ollama サービスを起動（バックグラウンドで常駐）
brew services start ollama

# 3. モデルをダウンロード（メモリに応じて選択）

# --- 16GB Mac Mini の場合 ---
ollama pull qwen3:8b

# --- 24GB 以上の場合（推奨）---
ollama pull qwen3-coder:14b

# --- 48GB 以上の場合（最高品質）---
ollama pull qwen3-coder:30b

# 4. 動作確認（簡単な質問を投げてみる）
ollama run qwen3-coder:14b "Hello, write a Python hello world"
# → レスポンスが返ってくれば成功。Ctrl+D で終了

ステップ3: Qwen Code のインストールと設定

# 1. Node.js インストール（未導入の場合）
brew install node

# 2. Qwen Code インストール
npm install -g @qwen-code/qwen-code@latest

# 3. 設定ファイルを作成
mkdir -p ~/.qwen
cat > ~/.qwen/settings.json << 'EOF'
{
  "model": {
    "name": "qwen3-coder:14b"
  },
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "apiKey": "EMPTY"
    }
  },
  "security": {
    "auth": {
      "selectedType": "openai-compatible"
    }
  }
}
EOF

# 4. 起動
cd ~/my-project
qwen

ステップ4: パフォーマンス最適化

# 同時にロードするモデルを1つに制限（メモリ節約）
echo 'export OLLAMA_MAX_LOADED_MODELS=1' >> ~/.zshrc
source ~/.zshrc

# Ollama のメモリ使用状況を確認
ollama ps

Mac Mini を常時稼働させれば、SSH 経由で他の PC からもアクセスできます。brew services start ollama でサービスを自動起動に設定しておけば、再起動後も自動で使える状態になります。

どちらを選ぶか — 判断フローチャート

Qwen Code を使いたい
  │
  ├── コードの外部送信が気にならない
  │     └── 構成A（クラウド API）→ 5分でセットアップ完了
  │
  └── コードを外部に出したくない / オフラインで使いたい
        │
        ├── Mac Mini のメモリが 24GB 以上
        │     └── 構成B（Ollama + qwen3-coder:14b 以上）
        │
        └── Mac Mini のメモリが 16GB
              └── 構成B は可能だが品質に制限あり
                    → まず構成A を試してから検討

観点	構成A（クラウド API）	構成B（完全ローカル）
セットアップ時間	5分	30分〜1時間
コスト	無料（1日1,000リクエスト）	完全無料（制限なし）
コード品質	高い（クラウドの大規模モデル）	メモリ依存（8B→低、30B→高）
応答速度	ネットワーク依存	ローカル処理（低遅延）
プライバシー	コードがクラウドに送信される	コードが外部に出ない
オフライン利用	不可	可能
必要スペック	Mac Mini（スペック不問）	24GB 以上推奨
ディスク容量	最小限	モデルで 5〜25GB 必要

初心者にはまず構成Aをおすすめします。 試してみて、プライバシーやリクエスト制限が気になったら構成Bに移行するのが現実的です。

注意点と制限事項

コード品質について

Qwen3-Coder はオープンモデルとしてトップクラスの性能（SWE-bench で67.0%）ですが、Claude Code（70.4%）と比較すると差があります。特に以下の場面で差が出やすいです。

場面	Qwen Code	Claude Code
簡単なコード生成	十分実用的	十分実用的
複雑なリファクタリング	やや不安定	安定
大規模コードベースの理解	実用的	優秀
日本語での指示理解	良好	優秀
ツール呼び出しの精度	良好	優秀

無料枠の制限

• 1日1,000リクエストの制限あり
• 複雑なタスクは複数リクエストを消費する
• 業務で頻繁に使う場合は DashScope の有料プランを検討

ローカル実行の場合

Ollama でローカル実行する場合、14B 以上のモデルが推奨されます。8B モデルではツール呼び出しの精度が低下する場合があります。

まとめ

• Qwen Code は無料で使えるオープンソース CLI コーディングエージェント: Qwen OAuth で1日1,000リクエストまで無料。Apache 2.0 ライセンスで完全にオープンソース
• インストールは1コマンド: npm install -g @qwen-code/qwen-code@latest または brew install qwen-code。Node.js 20 以上が必要
• Claude Code と同じ体験をオープンソースで: ターミナルで自然言語の指示を出すだけ。ファイル編集、コマンド実行、Git 操作、テスト作成を自律的に実行
• マルチプロバイダー対応: Qwen OAuth だけでなく、OpenAI・Anthropic・Google・Ollama 等の API キーも利用可能
• MCP サーバーで機能拡張: GitHub、データベース、Slack 等の外部ツールと標準プロトコルで連携
• IDE 統合: VS Code、Zed、JetBrains に対応。ターミナルに閉じない使い方も可能
• ヘッドレスモードで CI/CD 自動化: -p フラグでスクリプトから非対話実行。JSON 出力でパイプライン統合
• Qwen-Agent フレームワーク上に構築: 独自エージェント構築には Qwen-Agent SDK、すぐ使うなら Qwen Code
• Mac Mini で構築可能: クラウド API なら5分で開始。完全ローカル（Ollama）なら24GB以上推奨で、コードを外部に出さずオフラインでも利用可能

参考

• Qwen Code GitHub リポジトリ
• Qwen Code 公式ドキュメント
• Qwen Code QuickStart ガイド
• Qwen Code CLI: A Guide With Examples - DataCamp
• Qwen Code CLI: How to Set Up Qwen3-Coder for Free - F22 Labs
• Getting Started with Qwen Code for Coding Tasks - My Developer Planet
• Qwen Code Leverages Qwen3 as a CLI Agentic Programming Tool - KDnuggets
• Qwen3-Coder: Agentic Coding in the World - Qwen Blog
• Qwen-Agent GitHub リポジトリ
• MCP servers with Qwen Code
• Qwen Code Headless Mode
• Ollama で Qwen をローカル実行 - Qwen 公式
• Mac Mini M4 で LLM を動かす - archy.net
• Best Mac Mini for Running Local LLMs - Starmorph
• Qwen3-Coder 30B Hardware Requirements - Arsturn