Qwen Code：ターミナルで動作するコードエージェント（ Ollama

#Qwen Codeとは何か、なぜローカルで動かすのか

Qwen Codeは、GoogleのオープンソースのターミナルエージェントであるGemini CLIをフォークし、QwenチームがQwen3-Coderモデル向けに適応したものです。GitHub（QwenLM/qwen-code）でApache 2.0ライセンスの下に公開され、npmでインストールし、qwenコマンドで使用します。現代的なコードエージェントの仕組みを引き継いでおり、モデルがリクエストを受け取り、ツール（ファイルの読み書き、リポジトリ内検索、シェル実行、Webリクエスト、MCPサーバー）を利用して、検証可能な結果を生成するまでそれらを繰り返し実行します。

デフォルトでは、Qwen Codeは「Qwen OAuth」接続を優先します。Qwenアカウントで認証し、リクエストはAlibaba Cloudのサーバーに送られます。この経路には無料プランがありますが、クォータは変更される可能性があり、地域によって異なります。そのため、ここでは数値を示しません。最新情報の唯一の情報源は、公式ドキュメントの認証ページです。変わらないのは、もう一つの「OpenAI互換」モードです。Qwen Codeは、OpenAI APIを公開する任意のサーバーを受け入れます。その中には、マシン上のOllamaとLM Studioも含まれます。

プライバシー

ローカルモードでは、ソースコード、実行したコマンド、その出力が端末の外に出ることはありません。これは、顧客のコードや機密保持契約の対象となるコードにとって決定的な利点です。

コスト

クォータもトークン単位の請求もありません。唯一のコストは電気代と、すでに購入したハードウェアです。

入手可能性

サービス停止もピーク時の待ち行列もありません。GPUが動作している限り、エージェントは応答します。

デメリット

量子化 Q4 の 7～30B パラメータモデルは、数千億パラメータ規模のクラウドモデルと同等の水準ではありません。タスクをより細かく分割し、より入念に確認する必要があります。

#前提条件

Node.js 20以降

Qwen Code は npm パッケージです。node --version で確認してください。Linux と macOS では、nvm または fnm を使うとグローバルインストール時の権限問題を避けられます。

Ollamaがインストールされ、動作している状態

デーモンは http://localhost:11434 で待ち受けます。ollama list がエラーなしで応答する必要があります。そうでない場合は、まずOllamaのインストールガイドを確認してください。

ツール呼び出しに対応したモデル

これは譲れない条件です。コードエージェントは構造化されたツール呼び出しを連続して実行します。Qwen3-Coder および Qwen2.5-Coder ファミリーのモデルと Devstral は、Ollama のもとでこれに対応しています。tools に対応していないモデルはアクションの代わりにテキストを生成し、エージェントは行き詰まります。

GPU メモリ

Q4_K_Mでの目安：7Bは約5 GB、14Bは約9 GB、32Bは約19 GBのVRAMを占有します（コンテキストを除く）。エージェントが必要とする長いコンテキストで数GBが追加されるため、余裕を持って見積もってください。

Gitリポジトリ

必須ではありませんが、強く推奨します。エージェントはファイルを変更するため、git diffとgit checkoutが安全網になります。

#1. Qwen Codeをインストールする

リポジトリが推奨するインストール方法は、npm のグローバルインストールです。macOS では Homebrew パッケージも公開されています。バイナリ名は qwen です。

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

brew install qwen-code
qwen --version

設定なしでqwenを初めて起動すると、認証方法の選択を求められます。ローカル利用が目的ならQwen OAuthを選択せず、OpenAIオプションを選ぶか、よりよい方法として、いったん終了し、次の手順で説明する設定を先に準備してください。後からセッション中に/authコマンドで方法を変更できます。

#2. Qwen CodeをOllamaに接続する

Ollama はポート11434の /v1 パスでOpenAI互換APIを公開します。Qwen Codeはこのモードで、ベースURL、APIキー、モデル名という三つの環境変数を読み取ります。Ollama ではキーは必要ありませんが、Qwen Codeは空の値を受け付けないため、任意の文字列を設定します。

1. 01
   toolsに対応するコードモデルをダウンロードする

   Qwen3-Coder 30B-A3Bを例にします。これは300億パラメーターの専門家混合（MoE）モデルで、各トークンで30億パラメーターがアクティブになるため、規模の割に高速です。Q4では約19 GBで、GPUに完全に載せるには24 GBのVRAM、または少なくとも32 GBのユニファイドメモリを備えたApple Siliconマシンが必要です。12 GBのカードなら、qwen2.5-coder:7bまたは14Bモデルを選んでください。
2. 02
   OllamaのOpenAI APIが応答することを確認する

   /v1/modelsへのリクエストでは、モデル一覧が表示されるはずです。失敗する場合は、Ollamaが起動していないか、別のアドレスで待ち受けています。
3. 03
   プロジェクトのルートに.envファイルを作成する

   Qwen Codeは、カレントディレクトリ、プロジェクトの.qwenサブディレクトリ、またはグローバル設定用の~/.qwenにある.envファイルを自動的に読み込みます。作業ディレクトリに最も近いファイルが優先されます。
4. 04
   プロジェクトでqwenを起動する

   ウィンドウ下部にアクティブなモデルが表示されます。モデル名Ollamaが表示されていれば、接続は完了しています。まずはリポジトリの構造を要約するなど、簡単なリクエストを入力し、読み取りツールが機能することを確認してください。

ollama pull qwen3-coder:30b
curl http://localhost:11434/v1/models

OPENAI_API_KEY=ollama
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=qwen3-coder:30b

cd mon-projet
qwen

同じパラメーターをコマンドラインオプションとして渡せば、.envファイルに触れずに一時的なセッションで使用できます。動作している設定を壊さずに、別のモデルを試せるので便利です。

qwen --openai-api-key ollama \
  --openai-base-url http://localhost:11434/v1 \
  --model qwen2.5-coder:14b

#3. 変形：LM Studioをサーバーとして使う

LM Studioを使いたい場合も、原則は同じです。アプリケーションにコードモデルを読み込み、Developerタブを開いてローカルサーバーを起動します。デフォルトではポート1234で待ち受け、同じOpenAI互換APIを公開します。サーバーのオプションでツール呼び出しのサポートがまだ有効になっていない場合は有効にし、インターフェースでモデルのコンテキスト長を設定してください（次の手順を参照）。

OPENAI_API_KEY=lm-studio
OPENAI_BASE_URL=http://localhost:1234/v1
OPENAI_MODEL=qwen2.5-coder-14b-instruct

指定するモデル名は、読み込まれたモデルの一覧で LM Studio が表示する識別子、または http://localhost:1234/v1/models へのリクエストで返される識別子です。Ollama の名前とは異なります。

#4. コンテキストウィンドウを調整する：誰もが省略する手順

これがローカルで Qwen Code が失敗する最大の原因です。コードエージェントは毎回、長いシステムプロンプト（ツールの説明、動作規則、QWEN.mdの内容）、続いてセッション履歴、さらに読み込んだファイルを送信します。最初の数回のやり取りで、10 000トークンを超えます。一方、Ollama はデフォルトで短いウィンドウ（最近のバージョンでは4 096トークン）を開きます。超過分は黙って切り詰められるため、モデルはツールの指示を「忘れ」、行動する代わりに文章で回答したり、同じアクションを繰り返したりします。

したがって、少なくとも32 000トークンのコンテキストを設定する必要があります。Ollama では二つの方法があります。デーモンにグローバル環境変数を設定する方法と、特定のモデルのnum_ctxを固定するModelfileを使用する方法です。

sudo systemctl edit ollama
# Ajouter dans le bloc [Service] :
# Environment="OLLAMA_CONTEXT_LENGTH=32768"
sudo systemctl restart ollama

launchctl setenv OLLAMA_CONTEXT_LENGTH 32768
# puis relancer l'application Ollama

cat > Modelfile.qwen-code <<'EOF'
FROM qwen3-coder:30b
PARAMETER num_ctx 32768
EOF
ollama create qwen3-coder-32k -f Modelfile.qwen-code
# puis OPENAI_MODEL=qwen3-coder-32k dans le .env

二つ目の方法のほうが適切です。他のモデルには影響せず、派生モデルの名前から設定内容も分かります。代償はメモリです。キー・バリューキャッシュはコンテキストに応じて大きくなります。Q4の7Bモデルでは、32 000トークンのコンテキストによって、キャッシュのアーキテクチャと量子化方式に応じて、おおよそ2～4 GBが追加で必要になります。モデルがGPUに収まらなくなると、Ollama はレイヤーの一部をCPUに移し、速度が急激に低下します。ollama ps のPROCESSOR列を監視し、100 % GPUと表示されることを確認してください。

Qwen Code側にもセッション制限があります。設定ファイルのsessionTokenLimitは、会話で累積できるトークン数に上限を設定します。上限に達すると、ツールは/compressで履歴を圧縮するか、/clearで最初からやり直すよう促します。この値はモデルが実際にサポートする値に合わせてください。num_ctx 32768で提供されるモデルに32 000という上限を設定すると、Ollama側での予期しない切り詰めを避けられます。

#5. 設定ファイルとQWEN.md

Qwen Codeはsettings.jsonファイルを二つの場所から読み取ります。ユーザー用の ~/.qwen/settings.json と、プロジェクト内の .qwen/settings.json で、後者が優先されます。ローカル利用で特に役立つキーは、セッション上限、アクションの承認モード、MCPサーバーです。正確な名前はバージョン間で変更されているため、以下の例は公開ドキュメントに基づいており、お使いのバージョンのSettingsページと照合する必要があります。

{
  "sessionTokenLimit": 32000,
  "contextFileName": "QWEN.md",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/moi/mon-projet"]
    }
  }
}

QWEN.mdファイルは、Claude CodeにおけるCLAUDE.mdや、他のエージェントにおけるAGENTS.mdと同じ役割を果たします。各セッションに挿入される恒久的なメモです。そこには、スタック、ビルドとテストのコマンド、命名規則、エージェントが決して変更してはならないものを記述します。/init コマンドはリポジトリから最初のバージョンを生成し、/memory show はエージェントが実際に読み込んだ内容を表示します。

# Projet API Facturation

- Python 3.12, FastAPI, tests avec pytest (`make test`).
- Ne jamais modifier les migrations existantes dans alembic/versions/.
- Toute nouvelle route doit avoir un test dans tests/api/.
- Style : ruff, lignes de 100 caractères max.

承認モードは、エージェントがあなたに確認せず実行できることを制御します。デフォルトでは、ファイルへの書き込みとシェルコマンドの実行はすべて、あなたの承認を待ちます。--approval-mode auto-edit オプションを使うとファイル変更は許可されますが、コマンドは許可されません。--yolo を使うと確認がすべて省略されます。クラウドモデルより頻繁に間違えるローカルモデルを使う場合は、信頼できるようになるまでデフォルトモードを維持し、--yolo はクリーンでコミット済みのリポジトリに限定してください。

#6. 最初の作業セッション

Qwen Codeのセッションは、自然言語といくつかのショートカットで操作します。@プレフィックスはファイルまたはフォルダーをリクエストに挿入し（@src/api/routes.py）、!プレフィックスはモデルを介さずにシェルコマンドを実行し、/で始まるコマンドはツール自体を操作します。

/help

お使いのバージョンで利用可能なコマンドの一覧。

/auth

認証方法を変更します。ローカルとクラウドの切り替えに便利です。

/model

セッション中のモデルを表示または変更します。

/stats

消費したトークン数とセッション時間：応答が悪化したときにまず確認すること。

/compress

履歴を要約して、流れを失わずにコンテキストを解放します。

/clear

空の会話を開始します。QWEN.mdは読み込まれたままです。

/init et /memory

プロジェクトのコンテキストファイルを生成してから検査します。

/mcp

設定済みのMCPサーバーの状態と、それらが公開するツール。

/quit

セッションを終了します。

ローカルモデルでうまく機能する進め方は、まず読み取りを依頼し（「@src/auth/ で認証がどのように処理されているか説明してください」）、次に範囲を限定した変更を依頼し（「verify_token にトークンの有効期限チェックを追加し、対応するテストも追加してください」）、最後に検証を依頼する（「make test を実行し、失敗する箇所を修正してください」）というものです。各段階を数千トークン程度に収めることで、モデルは文脈を維持できます。「モジュール全体をリファクタリングしてください」のような依頼は、7～30B のモデルが確実に処理できる範囲を超えます。

自動化では、非対話モードに引数として依頼を渡すと、完了後に制御を返します。スクリプトや Git フックに組み込めます。

qwen -p "Relis le diff de git diff --cached et liste les problèmes potentiels, sans modifier de fichier"

#ローカルでの Qwen Code の制限

Qwen Code はAlibaba Cloudが提供するQwen3-Coderモデルを中心に設計されているため、より小さなローカルモデルで動かすと、その影響がすぐに現れます。受け入れるべき点は次のとおりです。

重いシステムプロンプト

このツールは毎回、長いツール説明を送信します。7Bモデルでは、この指示だけでコンテキストとモデルの注意の一部を占有するため、大規模モデルほどツール呼び出しの形式を適切に守れません。OpenCodeやAiderよりも、ループしたり、アクションの代わりに文章で回答したりすることが多くなります。これらはよりコンパクトなプロンプトを使用しています。

ビジョン機能はクラウド限定

画像（スクリーンショット、モックアップ）のサポートは、オンラインで提供されるビジョンモデルに依存します。ローカルでは、サーバーが互換性のあるマルチモーダルモデルを公開している場合にのみ機能しますが、ほとんどのコードモデルは該当しません。

ローカルモデルのネイティブ管理機能はない

モデルを Ollama メニューに一覧表示するOpenCodeとは異なり、Qwen Codeではファイルまたはオプションにモデル名とURLを入力する必要があります。モデルを変更するには、.envを編集するか、--model を付けて再起動します。

変化の激しい設定形式

このプロジェクトはまだ新しく、settings.json の構造はバージョンを重ねる中で変わってきました。フォーラムで見つけた例は、もはや有効でない可能性があります。閲覧時点の公式ドキュメントを正しい情報として扱ってください。

書き換えによる編集

派生元であるGemini CLIと同様に、Qwen Codeはブロックの置換によってファイルを変更します。一方Aiderは統合diffを適用し、変更ごとに自動的にコミットするため、履歴が読みやすくなります。変更ごとにコミットしたい場合は、Aiderのほうが適しています。

その一方で、Qwen Codeは完全なMCPサポート、Gemini CLIから受け継いだ成熟したセッション管理コマンド、整備された非対話モード、拡張機能によってIDEへ広がる統合を提供します。すでにQwenモデルを使用しており、AlibabaのクラウドとGPUを切り替えるための単一のツールを求めている場合に適しています。目的がローカル利用だけなら、OpenCodeまたはAiderのほうが少ない設定で同じ結果に到達できます。数値による比較は公開していません。品質はエージェントではなく、まず選択したモデルに左右されるためです。

#トラブルシューティング

エージェントがアクションを実行せず、テキストで応答する

モデルがツール呼び出しに対応していない（仕様書 Ollama を確認してください）か、コンテキストが短すぎてツールの説明が切り詰められています。手順4を実行し、ollama ps でモデルが正しい num_ctx とともに読み込まれていることを確認してください。

404エラーまたは「model not found」

OPENAI_MODEL の名前が ollama list と完全には一致していません。タグを含めた名前をコピー＆ペーストしてください。

localhost:11434への接続エラー

Ollama が起動していないか、別のインターフェース（OLLAMA_HOST）で待ち受けています。curl http://localhost:11434/v1/models で確認してください。

数回やり取りすると回答が非常に遅くなる

コンテキストが大きくなり、モデルがGPUの容量を超えています。ollama ps にCPUの割合が表示される場合は、num_ctxを減らすか、より小さなモデルに切り替えるか、セッション中に早めに /compress を実行してください。

Qwen Code がOAuth認証を再度要求する

環境変数が読み込まれていません。.envがカレントディレクトリまたは~/.qwenにありません。セッションで/authを実行してOpenAIオプションを選ぶか、コマンドラインパラメーターを渡して問題を切り分けてください。

モデルがQWEN.mdを無視する

/memory showでファイルが読み込まれていることを確認してください。settings.jsonでcontextFileNameを変更した場合は、名前が一致している必要があります。

EACCESで失敗するnpmインストール

npm のグローバルフォルダーに対する権限が不足しています。システムパッケージ経由ではなく nvm または fnm で Node をインストールしてから、インストールを再実行してください。

#さらに詳しく

Qwen Codeは、ローカルサーバーを受け入れるターミナルエージェントの一つにすぎません。以下のガイドでは、代替手段とモデルの選択を扱います。この記事では意図的に取り上げていません。

• OpenCode + Ollama：ターミナル内のコードエージェント
• Aider + Ollama：100%ローカルのエージェントでターミナル上でコーディングする
• Goose（Block）：ターミナルで使うローカルAIエージェント
• コーディングに最適なローカル LLM：Devstral、Qwen3-Coder

このガイドは 2026 年 10 月 11 日に執筆しました。参照したのは GitHub リポジトリと Qwen Code のドキュメント、および Ollama のドキュメントです。この記事では速度や品質の測定は行っておらず、メモリ使用量の目安は概算です。コマンドとキー名はバージョンによって変わるため、コピーする前に以下のページで確認してください。

• GitHubリポジトリ QwenLM/qwen-code（README、インストール、ライセンス）
• Qwen Code 公式ドキュメント（認証、settings、コマンド）
• Ollama のドキュメント（OpenAI互換API、環境変数）