3行でいうと

  • 足せるものは大きく6つあります。MCPサーバー、拡張（extensions）、スキル、サブエージェント、カスタムコマンド、ヘッドレス実行の仕組みです。拡張は、MCPサーバー、スキル、サブエージェント、コマンドなどを1つの箱にまとめて配る形だと、公式は説明しています。
  • 置き場所は、ほとんどが「自分の全プロジェクト用の ~/.qwen/ 以下」と「そのプロジェクト用の .qwen/ 以下」の2段です。同じ名前がぶつかったときの優先順位は、機能ごとに公式が書いていて、機能ごとに違います。
  • 人がいない実行では、qwen -p に承認の方針と上限（ターン数、実行時間、ツール呼び出し数）を渡します。公式は、--yolo はサンドボックスを有効にしない、と明記しています。
  • 公式ドキュメントの中に、ページどうしで書き方が食い違う点がいくつかありました（qwen mcp add の既定の範囲、カスタムコマンドの書式など）。本文で「どちらが書かれていたか」を並べます。

この記事は公式ドキュメントを2026年10月24日に読んでまとめたもので、実際に使って確かめた記録ではありません。運営者はQwenを入れていますが、使い心地はこの記事には書いていません。コマンド、設定のキー、ファイルの例は、公式のページに書かれていたものを写したもので、動作確認はしていません。公式ページは要約の形で取得したため、長い引用はせず言い換えています。取得した要約が途中で切れていたページ（フックのページ、カスタムコマンドのページの末尾、設定ページの一部）は、読めていない部分を本文で「読めていない」と書きました。バージョンや日付は、各ページに表示されていた「Last updated」の日付（2026年10月22日から24日）のものです。

先に結論

前提：用語をそろえる

全体の地図：何をどこに置くか

公式のページに書かれていた置き場所と書式を、機能ごとに並べます。

機能 置き場所（公式の記載） 書式 呼び出し方 公式のどこに書かれているか
MCPサーバー ~/.qwen/settings.json（user、既定）または .qwen/settings.json（project）の mcpServers JSON モデルが道具として使う。/mcp で管理 MCPのページ
拡張 <home>/.qwen/extensions/<名前>/qwen-extension.json JSON（マニフェスト）と各種フォルダ qwen extensions ... と /extensions 拡張の導入のページ、開発者向けの拡張のページ
スキル ~/.qwen/skills/、.qwen/skills/（ほかに ~/.agents/skills/、.agents/skills/） <名前>/SKILL.md モデルが判断して使う。/<スキル名> でも呼べる Skillsのページ
サブエージェント .qwen/agents/（最優先）、~/.qwen/agents/（その次） YAMLの見出し付きMarkdown 自動の委任、名前を指定、/agents で管理 SubAgentsのページ
カスタムコマンド ~/.qwen/commands/（優先度は低）、.qwen/commands/（高い） Markdown（TOMLは非推奨） /<ファイル名>、フォルダは : でつなぐ Commandsのページ
ヘッドレス実行 コマンドライン フラグと環境変数 qwen -p "..." Headless Modeのページ

設定ファイルの優先順位は、設定のページに、弱い順に「既定値、システムの既定ファイル、ユーザー、プロジェクト、システム、環境変数、コマンドライン引数」と書かれています。システムの設定ファイルはLinuxなら /etc/qwen-code/settings.json で、ユーザーとプロジェクトの設定より強い、とあります。会社のパソコンでは、この層で制限がかかっていることがあります。

MCP：足し方、範囲、つなぎ方

最小の足し方

公式のクイックスタートは、次の順です。

qwen mcp add --transport http my-server http://localhost:3000/mcp
qwen
/mcp

すでにQwen Codeを起動していた場合は、同じプロジェクトで起動し直してから、モデルにそのサーバーの道具を使うよう頼みます。設定ファイルを直接編集してもよく、どちらも同じ mcpServers の項目になる、と公式は書いています。

つなぎ方（トランスポート）は3種類

種類 向いているもの JSONのキー 公式の位置づけ
http リモートのサービス httpUrl（必要なら headers） 推奨
sse SSEだけに対応した古いサーバー url（必要なら headers） 古い方式、非推奨
stdio 手元のプログラム（スクリプト、CLI、Docker） command、args（必要なら cwd、env） ―

HTTPとSSEの両方に対応しているサーバーなら、HTTPを選ぶよう書かれています。開発者向けのページによると、どの方式になるかは、書いたキーで決まります（httpUrl ならストリーミングHTTP、url ならSSE、command ならstdio）。複数を書いたときにどうなるかは、読んだ範囲では書かれていませんでした。

設定ファイルの書き方（公式の例）

stdioのサーバーです。

{
  "mcpServers": {
    "pythonTools": {
      "command": "python",
      "args": ["-m", "my_mcp_server", "--port", "8080"],
      "cwd": "./mcp-servers/python",
      "env": {
        "DATABASE_URL": "$DB_CONNECTION_STRING",
        "API_KEY": "${EXTERNAL_API_KEY}"
      },
      "timeout": 15000
    }
  }
}

同じものをコマンドで足す形も、公式に載っています。

qwen mcp add pythonTools -e DATABASE_URL=$DB_CONNECTION_STRING -e API_KEY=$EXTERNAL_API_KEY \
  --timeout 15000 python -m my_mcp_server --port 8080

HTTPのサーバーにトークンを渡す例です。

{
  "mcpServers": {
    "httpServerWithAuth": {
      "httpUrl": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token"
      },
      "timeout": 5000
    }
  }
}

env の値には $VAR_NAME と ${VAR_NAME} が使えます。環境変数に鍵を置き、設定ファイルには名前だけを書く形です。開発者向けのページには、env が親プロセスの環境を引き継ぐかどうかは書かれていませんでした。

qwen mcp add のオプション

公式の表にあるものを写します。形は qwen mcp add [options] <name> <commandOrUrl> [args...] です。

オプション 意味 既定（公式の記載）
-s, --scope user か project MCPのページは user
-t, --transport stdio、sse、http stdio
-e, --env 環境変数（KEY=value） ―
-H, --header SSE・HTTPのヘッダー ―
--timeout ミリ秒 ―
--trust 信頼できる作業場所で確認を省く false
--include-tools、--exclude-tools 使う道具、隠す道具（カンマ区切り） すべて、なし
--oauth-client-id ほか --oauth-* OAuthの設定 ―

削除は qwen mcp remove <name> です。--oauth-* はsseとhttp専用で、stdioと組み合わせると拒否される、と書かれています。

食い違いを1つ：qwen mcp add の既定の範囲

MCPのページ（ユーザー向け）は、範囲の既定を user（~/.qwen/settings.json）と書いています。一方、開発者向けの「MCP Servers」のページは、同じオプション表で既定を project と書いています。どちらも2026年10月22日の更新表示です。どちらが現在の動作かは、僕らは確かめられていません。足したあとに、どちらのファイルに書かれたかを自分の目で確かめるのが安全です（これは僕らの見立てです）。

範囲と優先順位

認証

道具を絞る

{
  "mcp": {
    "allowed": ["my-trusted-server", "*-internal"],
    "excluded": ["experimental-server"]
  }
}

プロンプトとリソース

サーバーが公開するプロンプトは / で始まるコマンドとして現れ、リソースは @サーバー名:URI の形でプロンプトに差し込めます。信頼していないフォルダでは、リソースの読み込みは無効だと書かれています。

タイムアウト

安全に関わる点（公式の記載）

拡張（extensions）：入れる、作る、配る

入れ方

公式の導入のページに、入れ方が並んでいます。

入れ元 コマンドの例（公式） 備考（公式の記載）
Gitのリポジトリ qwen extensions install https://github.com/github/github-mcp-server 認証つきなどの一部の入れ元にはGit 2.37以上が必要
GitHubの短縮形 qwen extensions install <owner>/<repo> Gemini CLIの拡張も同じ形で入れられ、TOMLのコマンドはMarkdownに変換される
Claudeのマーケットプレイス qwen extensions install <マーケットプレイス名>（URLも可。末尾に :<プラグイン名> を足すと1つだけ選べる） Claudeのプラグインは自動で変換される
ローカルのフォルダ、アーカイブ qwen extensions install /path/to/your/extension コピーが作られるので、変更の反映には qwen extensions update が要る
npm qwen extensions install @scope/my-extension スコープ付きのパッケージだけ。パッケージのルートに何のファイルが要るかは、読んだ範囲では確かめられていません
アーカイブのURL qwen extensions install https://example.com/your/extension.zip zipまたはtar.gz

https://github.com/github/github-mcp-server を入れたあとに、鍵の入力を尋ねられるか、どの設定に書かれるかは、読んだ範囲では確かめられていません。拡張の settings（sensitive: true の値を入れるときに尋ねる仕組み）の説明は、下の「拡張の中身」にあります。

入れる範囲は、既定がユーザー（全体）で、--scope project を付けると今のワークスペースだけです。止める、再開する、更新するは、次のとおりです。

qwen extensions disable extension-name
qwen extensions disable extension-name --scope=workspace
qwen extensions enable extension-name
qwen extensions update extension-name
qwen extensions update --all
qwen extensions uninstall extension-name

Qwen Codeの中では、/extensions（または /extensions manage）で、探す（Discover）、入れた拡張（Installed）、入れ元（Sources）の3つのタブを持つ画面が開きます。CLIの変更は、起動中のセッションには再起動後に反映される、と書かれています。実行中のセッションでの /extensions install は、再起動なしで反映されます。

食い違いを1つ：一覧と「list」

導入のページは、qwen extensions list を載せていません（一覧は /extensions manage のInstalledタブと、マーケットプレイスの sources list だけ）。開発者向けのページは「/extensions list で一覧が出る」と書いています。どちらが現在のものか、僕らは確かめられていません。

拡張の中身：qwen-extension.json

公式の導入のページの例です（channels と workflows のキーは省いて載せています）。

{
  "name": "my-extension",
  "version": "1.0.0",
  "mcpServers": {
    "my-server": {
      "command": "node my-server.js"
    }
  },
  "contextFileName": "QWEN.md",
  "commands": "commands",
  "skills": "skills",
  "agents": "agents",
  "settings": [
    {
      "name": "API Key",
      "description": "Your API key for the service",
      "envVar": "MY_API_KEY",
      "sensitive": true
    }
  ]
}

作る：公式のチュートリアルの流れ

開発者向けの「Getting Started with Qwen Code Extensions」は、次の順です。

  1. qwen extensions new my-first-extension mcp-server で、ひな形を作る（example.ts、qwen-extension.json、package.json、tsconfig.json）。ひな形には、ほかに context、custom-commands、exclude-tools があります。
  2. npm install のあと npm run build で dist/example.js を作る。
  3. qwen extensions link . で、開発フォルダへのリンクを作る。変更のたびに update しなくて済みます。
  4. Qwen Codeを再起動して、ひな形の道具（fetch_posts）を試す。
  5. commands/fs/grep-code.toml を足して、/fs:grep-code "some pattern" を試す。
  6. QWEN.md を置き、contextFileName に書く。

公式のチュートリアルは、カスタムコマンドにTOMLを使っています。後述のとおり、コマンドのページはMarkdownを推奨してTOMLを非推奨と書いているので、ここも食い違いです。

配る

「Extension Releasing」のページは、2つの方法を挙げています。

読んだ範囲では、このページにnpmでの配り方は書かれていませんでした（入れ方のほうにはnpmがあります）。また、同じページのGitHub Actionsの例は、ビルドで作るファイル名とアップロードするファイル名が合っていません（linux.x64 を作って linux.arm64 を上げる形）。そのまま写さず、自分のものに合わせて直す必要があります。

Agent Plugins v1とMod（短く）

公式の「Agent Plugins」のページによると、plugin.json と mcp.json と SKILL.md を持つ形式のパッケージを、変換せずに読み込めます。使えるのは、スキルと、stdioおよびストリーミングHTTPのMCPサーバーだけで、コマンド、サブエージェント、フック、旧式のSSEのMCPは有効になりません。ほかに「Experimental Mod commands」という別のページがあり、公式は、既定ではオフの実験で、Claude CodeのMod APIの一部だけを動かすと書いています。この記事ではこの2つの細部は扱いません。

スキル：モデルが「必要になったら読む」指示の束

置き場所と書式

公式の SKILL.md の形です。

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
priority: 10
---

Provide clear, step-by-step guidance for Qwen Code.

公式の例は、見出しの後ろに、手順（Instructions）と例（Examples）の節を置く形です。

name と description は必須です。説明には、何をするかと、いつ使うかの両方を書く、と公式は書いています。そのほかのキーには、paths（該当ファイルに触れるまでモデルの一覧に出さない）、user-invocable: false（/ の候補から隠す）、disable-model-invocation: true（モデルから隠す）、hooks（フック）があります。

作り方、確かめ方

安全に関わる点（公式の記載）

サブエージェント：役割を絞った分身

置き場所と書式

tools を書かないと、親のすべての道具（MCPの道具を含む）を引き継ぎます。絞るなら、tools で許可するか、disallowedTools で禁止します。公式の例は、読み取り専用の code-reviewer と、書き込みも実行もできる testing-expert の2つが対になっています。見出し（フロントマター）は次のとおりです。本文（指示文）は長いので写さず、公式の「Development Workflow Agents」の節で読んでください。

---
name: code-reviewer
description: Reviews code for best practices, security issues, performance, and maintainability
tools:
  - read_file
  - read_many_files
---

---
name: testing-expert
description: Writes comprehensive unit tests, integration tests, and handles test automation with best practices
tools:
  - read_file
  - write_file
  - read_many_files
  - run_shell_command
---

tools を並べる書き方（YAMLの箇条書き）は、取得した要約から組み立てた形で、公式の字面そのものではないかもしれません。本文の中身は、公式の要約によると、code-reviewer は品質・安全性・保守性の観点で、重大な問題、重要な改善、軽い提案、良い点に分けて返す役、testing-expert は単体テスト・結合テストを正常系と異常系の両方で書く役です。違いは tools の1行で、後者は write_file と run_shell_command を持つので、ファイルを書き換え、コマンドを動かせます。

呼ばれ方

安全に関わる点（公式の記載）

カスタムコマンド：自分用の / コマンド

置き場所、名前、書式

---
description: Optional description (displayed in /help)
---

Your prompt content here.
Use {{args}} for parameter injection.

引数、ファイル、シェルの差し込み

以下は、その形を僕らが組み立て直した見本です（公式の本文そのものではありません）。

<!-- .qwen/commands/git/commit.md → /git:commit -->
---
description: Generate Commit message based on staged changes.
---

Write a concise commit message for the following staged changes.

```diff
!{git diff --staged}
```

実行前にシェルの確認の画面が出るので、中身を見てから許可します。 - 読んだ範囲では、$ARGUMENTS という書き方は、コマンドのページには書かれていませんでした。

このページは、全体が約11万2千字あり、僕らが読めたのは先頭10万字です。残りの約1万2千字（別のセッションへのメッセージを扱う節の途中から後）は読めていません。

ヘッドレス実行：人がいない場所でQwen Codeを動かす

基本の形

qwen -p "What is the capital of France?"
cat README.md | qwen --prompt "Summarize this documentation"
qwen --continue -p "Run the tests again and summarize failures"
result=$(git diff --cached | qwen -p "Write a concise commit message for these changes" --output-format json)

セッションは ~/.qwen/projects/<名前を整えた作業ディレクトリ>/chats にJSONLで保存され（設定 general.chatRecording が既定でオン）、--continue で直近、--resume <sessionId> で指定の会話を続けられます。chatRecording をオフにすると、--continue と --resume も使えなくなります。

出力の形

形式 中身（公式の記載）
text（既定） 人が読む最終回答だけ
json メッセージのJSON配列。終了時にまとめて出る。最後の result に成功か失敗かと結果が入る
stream-json 1行ずつのJSON。出来事のたびに出る。--include-partial-messages で途中経過も出る

道具の結果の文字は、65,536バイトで切られる、と書かれています。入力は --input-format stream-json もありますが、公式は「工事中」で、SDKとの連携用と書いています。

主なフラグ

フラグ 意味
--prompt、-p ヘッドレスで実行
--output-format、-o text、json、stream-json
--approval-mode plan、default、auto-edit、auto、yolo
--yolo、-y すべての操作を自動で承認
--max-session-turns ターン数の上限。超えると終了コード53
--max-wall-time 実行時間の上限（90、30s、5m、1h など）
--max-tool-calls 最上位のツール呼び出しの回数の上限
--safe-mode 多くのカスタマイズを無効にして問題を切り分ける
--append-system-prompt 組み込みのプロンプトに指示を足す

終了コードは、53（ターン数の超過）、55（予算の超過）、130（SIGINT）が書かれています。それ以外の終了コードは、ページには書かれていませんでした。実行時間（--max-wall-time）とツール呼び出し数（--max-tool-calls）の上限は、単発の qwen -p と --input-format stream-json のときに効き、qwen serve やACPのセッションには効かない、と書かれています。

決まった形のJSONで受け取る

公式の「Structured Output」のページの例です。

qwen --prompt "Summarize the changes in HEAD with risk_level" \
  --json-schema '{
    "type": "object",
    "properties": {
      "summary":    { "type": "string" },
      "risk_level": { "type": "string", "enum": ["low", "medium", "high"] }
    },
    "required": ["summary", "risk_level"],
    "additionalProperties": false
  }'

@./schemas/summary.json のようにファイルを指す書き方もあります。既定の text では、検証済みの結果が1行のJSONで標準出力に出ます。json と stream-json では、最後の result の structured_result に入ります。モデルが道具を呼ばずに文章で答えると終了コード1、ターン数の上限なら53、中断なら130です。スキーマは4MiBまでで、ルートに $ref は置けません。スキーマは毎ターンモデルに送られ、検証のやり直しも1ターンに数えられます。

承認と鍵：自動化で決めておくこと

公式のCIの例は、次の形です。

- name: Automated code review
  env:
    QWEN_CODE_UNATTENDED_RETRY: '1'
  run: |
    qwen -p "Review all files in src/ for security issues" \
      --output-format json \
      --yolo > review.json

この例は --yolo と無期限の再試行が組み合わさっています。上限（--max-session-turns、--max-wall-time）を付けない例なので、そのまま写すと、止まらない実行になりうる点に注意してください（これは僕らの見立てです）。

道は3つ：CLI、GitHub Actions、SDK

信頼とサンドボックス：足したものを「どこまで動かすか」

最初の10分でやること

ここは、公式に書かれている手順を並べたものです。順番と組み合わせは僕らの整理です。

  1. まず空のプロジェクトで試す。 qwen mcp add --transport http my-server <URL> で1つだけ足し、qwen を起動して /mcp で、サーバー、道具、状態を見ます。
  2. どのファイルに書かれたか見る。 ~/.qwen/settings.json と .qwen/settings.json のどちらに mcpServers が増えたかを開いて確かめます（既定の範囲の食い違いがあるため）。
  3. 道具を絞る。 includeTools か excludeTools を入れ、trust は付けません。
  4. 自分用のコマンドを1つ作る。 ~/.qwen/commands/ に hello.md を置き、見出しの description と本文を書いて、/hello を試します。
  5. スキルを1つ作る。 .qwen/skills/my-skill/SKILL.md に、名前と説明を書き、/skills で見えるか確かめます。
  6. サブエージェントを読み取り専用で作る。 /agents create で、tools を read_file と read_many_files だけにします。
  7. /mcp に出ないときの見直し。 公式のMCPのページのトラブルシューティングは、次の3点です。qwen mcp list で Disconnected と出るなら、URLかコマンドを確かめて timeout を延ばす。stdioが起動しないなら、command を絶対パスで書き、cwd と env を確かめる。環境変数が展開されないなら、その変数が「Qwen Codeを起動した環境」に存在するかを確かめる（シェルとGUIアプリで環境が違うことがあります）。ほかに、Qwen Codeを起動したまま足したなら同じプロジェクトで起動し直す、includeTools／excludeTools や mcp.allowed／mcp.excluded で道具やサーバーが隠れていないか見る、という点が本文の別の節に書かれています。接続の確認だけを待つ時間は discoveryTimeoutMs で、道具の呼び出しの timeout とは別です。MCPのページには qwen --debug の記載は見つかりませんでした（スキルの読み込みエラーを見るときの --debug は、スキルのページに書かれています）。非対話の起動の待ちを昔の動きに戻す QWEN_CODE_LEGACY_MCP_BLOCKING=1 も、同じページにあります。
  8. ヘッドレスは上限つきで。 qwen -p "..." --output-format json --max-session-turns 5 --max-wall-time 5m のように、承認の方針と上限を付けてから、スクリプトに組み込みます。

僕らの見立て

ここからは僕らの見立てです。公式の記載から組み立てたもので、公式の推奨そのものではありません。

気をつけること

出典