3行でいうと

  • インストールは公式の「Quick Install」（シェルのスクリプト）が推奨で、npm（Node.js 22以上）とHomebrewの手動の方法もあります。ログインは、初回起動か /auth で、QwenCloud、Alibaba ModelStudio、サードパーティ、カスタムの4つから選びます。Qwen OAuthは2026年4月15日に終了した、と公式にあります。
  • 承認の基準は5つのモード（plan、default、auto-edit、auto、yolo）です。ただし、公式の中で「始まりのモード」の書き方が食い違っていました。起動したら、まず今のモードを確かめてください。yolo は確認を全部飛ばし、サンドボックスも有効にしません。
  • サンドボックスは3種類（Linuxのbwrap／Landlock、macOSのSeatbelt、Docker／Podman）で、信頼フォルダーは既定で無効です。
  • 設定は ~/.qwen/settings.json と .qwen/settings.json が中心で、APIキーは .env に置くのが公式の勧めです。指示書は QWEN.md、読ませたくないものは .qwenignore です。

この記事は、公式ドキュメントとGitHubのページを2026年10月24日に読んでまとめたものです。この記事は、実際に使って確かめた記録ではありません。運営者はQwenを入れていますが、使い心地はこの記事には書いていません。コマンド、環境変数、設定のキーは公式に書かれていたとおりに写しましたが、動作確認はしていません。公式の文章は要約として取得したため、引用は最小限にして言い換えています。権限ルール（permissions.allow など）の書式の全体は、読めたページの範囲では見つからなかったので、書いていません（Autoモードのページに例として出てくる指定の形だけ、第4章に写しました）。

先に結論

前提：用語をそろえる

1. インストール

公式のOverviewとQuickstartに載っている方法は、次のとおりです（どちらも2026年10月22日更新と表示）。

方法 コマンド（公式の記載） 条件 公式のどこ
Quick Install（Linux、macOS） curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.sh \| bash 公式が推奨と書いている Quickstart
Quick Install（Windows） irm https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.ps1 \| iex 同上 Quickstart
npm npm install -g @qwen-code/qwen-code@latest Node.js 22以上 Quickstart、README
Homebrew（macOS、Linux） brew install qwen-code Homebrewが入っていること Quickstart、README

インストーラーについて、Overviewは次のように書いています。

確かめる方法として、サンドボックスのページは qwen --version を使っています。公式のGitHubのReleasesのページには v0.23.0、v0.23.1-preview.2 のようにプレビューとナイトリーが並び、安定版の表示や日付は見つからなかったので、最新の安定版は断言できません。

アンインストール（公式のUninstallのページ）。 npmで入れた場合は npm uninstall -g @qwen-code/qwen-code。Quick Installで入れた場合は、uninstall-qwen-standalone.sh（Windowsは .ps1）を同じ形で実行します。後者は、設定フォルダー ~/.qwen を既定では残す、と書かれています。npm版では ~/.qwen が消えるかどうか、書かれていませんでした。

僕らの見立てです。curl ... | bash は、ネット上のスクリプトをそのまま実行する形です。気になる人は、npmかHomebrewを選ぶか、スクリプトを先に読む、という選び方もあります。

2. ログインとAPIキー

認証の4つの入口

初回起動のメニューと、公式の認証のページ（2026年10月22日更新と表示）の整理です。

メニュー 中身 キーや請求 公式のどこ
QwenCloud（公式が推奨） Token Plan、または Standard API Key。プラットフォームは「China」または「International」を選ぶ Token Planは月のクレジット枠つきの定額。Standard API Keyは従量課金 Authentication
Alibaba ModelStudio Coding Plan、Token Plan、Standard API Key Coding Planは個人の開発者向けで週ごとの枠。Token Planはチームや会社向けで使った分の請求 Authentication
Third-party Providers DeepSeek、Grok、MiniMax、Z.AI、Kimi、Idealab、ModelScope、OpenRouter、Requesty APIキーでつなぐ。請求と規約はそのプロバイダーのもの Authentication
Custom Provider 自分のサーバー、プロキシ、メニューにないプロバイダー。OpenAI、Anthropic、Geminiなどの互換の窓口 キーや請求は接続先による Authentication

QwenCloudとAlibaba ModelStudioの2つの入口では、Token PlanとStandard API Keyのどちらでも、組み込みの web_search（ウェブ検索）ツールが使える、と書かれています。Coding Planについては、この文は読めていません。Coding PlanはQwenCloudにはなく、Alibaba ModelStudio側のものです。

終了したもの：Qwen OAuth

画面を使う方法

qwen

を起動して、初回のメニューで選びます。あとから変えるときは、/auth です（別名は /connect、/login）。モデルの切り替えは /model、または qwen --model "<model-id>" です。診断には /doctor があり、認証の確認にもこれを使うよう、公式が書いています。なお、以前あった qwen auth というコマンドは削除済みで、qwen auth status のような古いコマンドは、削除のお知らせを表示するだけです。

環境変数で渡す方法（公式に載っているもの）

つなぎ先 キーの環境変数 接続先のアドレス（公式の記載） キーの形
QwenCloud（International）の従量課金 QWENCLOUD_API_KEY https://maas.qwencloudapi.com/compatible-mode/v1 sk- または sk-ws-
QwenCloud（International）のToken Plan QWENCLOUD_TOKEN_PLAN_API_KEY https://token-plan.maas.qwencloudapi.com/compatible-mode/v1 sk-sp-
Alibaba ModelStudioのCoding Plan（国際） BAILIAN_CODING_PLAN_API_KEY https://coding-intl.dashscope.aliyuncs.com/v1 sk-sp-
Alibaba ModelStudioのToken Plan（シンガポール） BAILIAN_TOKEN_PLAN_API_KEY https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1 形の指定なし

China側（北京）のアドレスも、同じページに載っています。公式のヘッドレス向けの例は、キーの変数、OPENAI_BASE_URL、OPENAI_MODEL の3つを設定する形で、International・従量課金の例のモデルは qwen3.8-max です。Coding Planの例のモデルは qwen3-coder-plus で、qwen3.7-plus、glm-5、kimi-k2.5 なども対応として並んでいます。

自分のキーを直接使う方式（Standard API Key）の環境変数は、プロトコルごとに決まっています。OpenAI互換は OPENAI_API_KEY、OPENAI_BASE_URL、OPENAI_MODEL（別名 QWEN_MODEL）、Anthropicは ANTHROPIC_API_KEY、ANTHROPIC_BASE_URL、ANTHROPIC_MODEL、Google GenAIは GEMINI_API_KEY、GEMINI_MODEL、Vertex AIは GOOGLE_API_KEY と GOOGLE_MODEL（または GOOGLE_CLOUD_PROJECT と GOOGLE_MODEL）です。

settings.jsonに書く方法

公式の「Model Providers」のページにある書き方の形は、次のとおりです（OpenAI互換の1件。id と baseUrl の値は例で、ページの例の逐語までは確かめきれていません）。

"modelProviders": {
  "openai": [
    {
      "id": "gpt-4o",
      "envKey": "OPENAI_API_KEY",
      "baseUrl": "https://api.openai.com/v1"
    }
  ]
}

envKey に書くのは、キーそのものではなく、キーが入っている環境変数の名前です。本物のキーは .env か、settings.json の env ブロックに入れます。baseUrl は /v1 までで、/v1/chat/completions まで書かない、と案内されています。自分のサーバーは、openai に、Ollamaなら http://localhost:11434/v1、vLLMなら http://localhost:8000/v1 を書きます。認証のいらないサーバーには export OLLAMA_API_KEY="ollama" のような仮の値を入れます。認証のページには、security.auth.selectedType を "openai" にする、model.name を書く、といった項目もありますが、1枚のJSONとしては写せませんでした。

キーの探され方と優先順位（認証のページ）。 .env は、①.qwen/.env（推奨）、②.env、③~/.qwen/.env、④~/.env の順に探して、最初に見つかった1つだけを使います（合算しません）。値の強さは、強い順に、①コマンドの旗（例：--openai-api-key）、②システムの環境変数、③.env、④settings.json の env です。安全上の注意は、キーをバージョン管理に入れないこと、プロジェクトの秘密は .qwen/.env に置いてgitから外すこと、の2つです。

ログインで詰まったとき

サポートのトラブルシューティングのページによると、認証のエラーでUIが出ないほど詰まった場合は、~/.qwen/settings.json（または ./.qwen/settings.json）の security.auth.selectedType を消して、再起動します。会社のネットワークで証明書のエラーが出る場合は、NODE_EXTRA_CA_CERTS に社内のルート証明書のファイルを指定します。プロキシは qwen --proxy <url> か、settings.json の proxy です。ただし、このプロキシの説明は、読んだ範囲では古いQwen OAuthの流れの「fetch failed」の話として書かれています。

3. 最初の10分でやること

公式のQuickstartに書かれている手順。

  1. （任意）プロジェクトのフォルダーに入る：cd /path/to/your/project
  2. qwen を起動する。初回は、モデルの接続（認証）の設定が求められる。
  3. /help で、使えるコマンドの一覧を見る。
  4. 最初の質問として、公式は explain the folder structure、what can Qwen Code do? などを挙げている。変更を伴う例は add a hello world function to the main file、commit my changes with a descriptive message など。
  5. 覚えておくコマンド：/auth（認証を変える）、/doctor（設定を確認する）、/clear（会話をリセットする）、/quit（終わる）。

Quickstartは、ファイルを変更する前に許可を求める、変更は1つずつ承認することも、セッションの間はまとめて承認（Accept all）することもできる、と書いています。

ここから先は僕らの整理です。 公式に書かれた機能を、安全に始める順に並べました。

  1. 最初のプロジェクトは、コミット済みで、捨てても困らないものにする。 戻す方法として、/restore（ツール実行前のチェックポイントへ）と /rewind（会話を前の回へ）がコマンド一覧にあります。ただし、チェックポイントが既定で作られるかは、読んだページからは分かりませんでした。
  2. 起動したら、今の承認モードを確かめる。 /approval-mode で選択画面が開きます。Shift+Tab で切り替わります（Windowsは Tab）。
  3. まず読むだけの質問から。 慣れたら /plan <やりたいこと> で計画だけを作らせます（公式の例：/plan I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.）。
  4. /init で QWEN.md の下書きを作る。 コマンド一覧では、ディレクトリを分析して最初のコンテキストファイルを作るコマンドとされています（すでにある場合の扱いは読めていません）。
  5. 使った量を見る。 /context はコンテキストの使用量、/stats（別名 /usage）は使用状況です。金額に換算されるかは読めていません。
  6. 続きから再開する。 qwen --continue（直近の会話）、qwen --resume（選ぶ画面）。履歴は手元に保存される、とcommon-workflowのページにあります。
  7. 固まったら /auth と /doctor に戻ります。

4. 承認モード：何を確認なしで通すか

承認モードのページ（2026年10月22日更新と表示）の表を整理します。

画面の名前 設定の値 ファイル編集 シェルコマンド 公式が書くリスク
Plan plan 読むだけ（分析） 実行しない 最も低い
Ask Permissions default 手動で承認 手動で承認 低い
Auto-Edit auto-edit 自動で承認 手動で承認 中くらい
Auto auto 分類器が判定 分類器が判定 中くらい
YOLO yolo 自動で承認 自動で承認 最も高い

以前「Default」と呼ばれていたモードは、「Ask Permissions」に名前が変わりました。設定の値 default と、/approval-mode default は変わりません。

切り替え方。

公式の中で食い違っていた点。 始まりのモードの書き方が、ページによって違います。

YOLOの警告。 公式は、YOLOでは「AIが、あなたのターミナルの権限で、どんなコマンドも実行できる」と書き、信頼できるコードか確かめ、重要なファイルはバックアップかコミットをしてから、と注意しています。ヘッドレスのページには、--yolo はサンドボックスを有効にせず、ツールは手元のプロセスの権限のまま動く、起動時に警告が1行出る、とあります。警告は QWEN_CODE_SUPPRESS_YOLO_WARNING=1 で消せますが、消すのは、危険を分かったうえでにしてください（公式も、確かめてからと書いています）。別に、コマンド一覧のページには、/config からは tools.approvalMode を yolo にできない、とあります。

Autoモード：別のAIが見張る

Autoモードのページ（2026年10月22日更新と表示）の要点です。

{
  "permissions": {
    "autoMode": {
      "hints": {
        "allow": ["Running poetry install and poetry update in this Python project"],
        "softDeny": ["Running migration scripts that touch the production DB"],
        "hardDeny": ["Sending secrets or .env contents to any network endpoint"]
      },
      "environment": ["Production credentials live in 1Password, never in plain files"],
      "classifyAllShell": true
    }
  }
}

hardDeny は依頼があっても止まりますが、分類器の方針であって確定的なルールではない、と書かれています。1項目200文字まで、1種類50項目まで、environment は20項目までです。承認モードのページの設定例は旧名の hints.deny を使っていますが、Autoモードのページは、hints.deny は後方互換のため今も受け付け、softDeny として扱う、と書いています。食い違いではなく、旧名と新名です。 - 公式の限界の説明。 分類器は最善の努力で、deny の代わりにはなりません。MCPのツールの注釈は自己申告で、検証されません。分類器へ渡す引数を mcp.forwardArguments: false で名前だけにすると、ほとんどのMCP呼び出しが控えめに止められる、と公式が注意しています（MCPの深い話は別のガイドに任せます）。決して実行してはいけないコマンドは permissions.deny に書く、と書かれています。

5. サンドボックス：コマンドの触れる範囲を囲う

サンドボックスのページ（2026年10月22日更新と表示）の整理です。

方法 何を囲うか 条件 公式の説明
Linuxの実行サンドボックス（bwrap、またはLandlock） ツールの実行（シェル、! のコマンド、Read／Write／Editなど）。CLI本体、モデルとの通信、認証は囲いの外 bwrapは /usr/bin/bwrap。LandlockはABI 3以上のカーネル bwrapが最も強い。Landlockは network が open のときだけの代替
macOS Seatbelt sandbox-exec による囲い macOS 既定のプロファイルは、プロジェクト外への書き込みを制限し、通信は許す
Docker、Podman CLI全体をコンテナの中で動かす docker か podman QWEN_SANDBOX=true のとき、LinuxとWindowsではDockerかPodmanが自動で選ばれる

入れ方と優先順位。 強い順に、①環境変数 QWEN_SANDBOX=true|false|docker|podman|sandbox-exec、②旗 -s、--sandbox、③設定 tools.sandbox です。環境変数があれば、旗と設定ファイルの両方に勝ちます。公式の最小の例は次のとおりです。

qwen -s -p "analyze the code structure"
export QWEN_SANDBOX=true
qwen -p "run the test suite"

Linuxの実行サンドボックスは、旗ではなく tools.executionSandbox で設定します。filesystem と network は必須です。

{
  "tools": {
    "executionSandbox": {
      "backend": "auto",
      "filesystem": "workspace-write",
      "network": "closed"
    }
  }
}

backend は auto（既定。まずbwrap）、bwrap、landlock。filesystem は read-only か workspace-write。network は closed か open です。これはLinuxだけで、変更に再起動が要り、プロジェクトの .qwen/settings.json の値は無視されます（「オペレーター専用」の項）。確かめるコマンドは qwen sandbox --verify などです。

macOSでは SEATBELT_PROFILE で6種類（permissive-open（既定）から restrictive-proxied まで）を選びます。コンテナは、公開のイメージ（ghcr.io/qwenlm/qwen-code:<version> の形）を使い、ワークスペースと ~/.qwen をマウントします。足りないもの（公式の例はJava）は .qwen/sandbox.Dockerfile で足します。

公式の警告と限界。

僕らの見立てです。コンテナ方式は、認証情報と設定が入る ~/.qwen をコンテナの中に見せる作りだと、公式の記述から読めます。また、--yolo はサンドボックスを有効にしないので、組み合わせるなら別に有効にします。

6. 信頼フォルダー（Trusted Folders）

初めて開くフォルダーの設定を、勝手に読み込まないための機能です。Trusted Foldersのページ（2026年10月22日更新と表示）の整理です。

僕らの見立てです。有効にしていないと、他人のリポジトリを git clone して、その中で qwen を起動したとき、そのリポジトリの .qwen/settings.json や .env が読み込まれる、という読み方になります（公式の文章は、「無効のときは読み込まれる」とは明記していません）。他人のコードを開く機会がある人は、この機能を有効にするかどうかを、最初に決めておくのがよいと思います。

7. 設定ファイルと、指示書

settings.jsonの場所と強さ

設定リファレンスのページ（取得できた範囲に日付の表示なし）の整理です。ファイルはJSONで、文字列の中で $VAR_NAME や ${VAR_NAME} と書くと、読み込み時に環境変数に置き換えられます。コメントが使えるかどうかは、そのページには書かれていませんでした（なお、信頼フォルダーのファイルは、コメントと末尾のカンマを受け付ける、と別のページにあります）。

層 場所（公式の記載） 備考
システムの既定値 /etc/qwen-code/system-defaults.json（Linux。WindowsとmacOSの場所も記載あり） QWEN_CODE_SYSTEM_DEFAULTS_PATH で変更可。ファイルの中で最も弱い
ユーザー ~/.qwen/settings.json 自分のすべてのセッション
プロジェクト プロジェクトの根の .qwen/settings.json そのプロジェクトだけ
システム /etc/qwen-code/settings.json（Linux。他OSの場所も記載あり） 管理者向け。QWEN_CODE_SYSTEM_SETTINGS_PATH で変更可

強さの順は、弱い順に、①組み込みの既定値、②システムの既定値、③ユーザー、④プロジェクト、⑤システム、⑥環境変数（.env 由来を含む）、⑦コマンドラインの旗です。プロジェクトより「システム」が強い点に注意してください。review.*、ui.brand.*、ui.allowedApprovalModes、tools.executionSandbox は「オペレーター専用」で、ワークスペースの .qwen/settings.json に書いても無視される、と書かれています。プロジェクトの .qwen フォルダーには、サンドボックスのプロファイルと、エージェントのスキル（.qwen/skills/ の SKILL.md）も置けます。

目についた設定のキー（既定値は公式の表示）

キーは大きな分類（general、ui、model、tools など）の下に入ります。

キー 既定値 意味（公式の記載から）
tools.approvalMode auto 既定の承認モード（5つの値）
tools.sandbox 未設定 サンドボックス（真偽値か文字列）
tools.disabled 未設定 道具を登録しない。permissions.deny と違い、モデルが見つけることも呼ぶこともできない
tools.allowed、tools.exclude、tools.core 未設定 非推奨。permissions.allow、permissions.deny などを使う、と書かれている
privacy.usageStatisticsEnabled true 使用統計の収集
general.enableAutoUpdate、general.chatRecording どちらも true 自動更新、会話の記録。chatRecording を切ると --continue と --resume も使えなくなる（再起動が必要）
model.maxSessionTurns、model.maxToolCalls、model.maxWallTimeSeconds いずれも -1 回数、ツール呼び出し、実行時間の上限。-1 の意味の説明は読めていない
security.folderTrust.enabled 既定でオフ 信頼フォルダー

大切なのは、回数や時間の上限の既定が -1 という点です。僕らの見立てです。従量課金のキーで長い自動作業を任せるなら、これらの設定や、ヘッドレスの旗（--max-session-turns、--max-tool-calls、--max-wall-time）で、上限を自分で決めておくのが安全です。超えたときの終了コードは、53（回数）と55（予算）と、ヘッドレスのページにあります。

そのほかの公式の注意は、手で書き換えた model.baseUrl は同じモデルIDの別のプロバイダーに通信を向けてしまうことがある、古いキー（disableAutoUpdate など）はバックアップのうえ新しい名前に移行される、の2つです。設定リファレンスは長く、permissions.*（許可・確認・禁止のルールの書き方）、security.* の全体、telemetry、環境変数の一覧表は、取得した範囲では読めませんでした。権限ルールの書式は、このガイドでは書きません。

始め方の設定例（僕らの整理）

ここまでに公式から写したキーを、1つにまとめた例です。公式の1枚の例ではなく、この記事で並べたもので、動作確認はしていません。~/.qwen/settings.json（自分の全体の設定）に置く想定です。

{
  "tools": {
    "approvalMode": "default",
    "executionSandbox": {
      "backend": "auto",
      "filesystem": "workspace-write",
      "network": "closed"
    }
  },
  "security": {
    "folderTrust": {
      "enabled": true
    }
  }
}

指示書 QWEN.md と、自動メモリ

メモリのページ（2026年10月22日更新と表示）の整理です。

ファイル 範囲 注意
~/.qwen/QWEN.md 自分のすべてのプロジェクト ―
プロジェクトの根の QWEN.md チーム全体 ソース管理に入れる想定
.qwen/QWEN.local.md 自分だけ、そのプロジェクトだけ 公式は「自分で gitignore すること」と書く。自動では追加されない

存在するファイルは、セッションの開始時にすべて読み込まれます。リポジトリに AGENTS.md があれば、それも読みます。@path/to/file で、別のファイルを参照できます。公式の書き方の助言は、ビルドとテストのコマンド、決まりごと、設計の判断、個人の好みを入れること、コードを読めば分かることは入れないこと、短く具体的にすること（長いと守られにくい）、です。

自動メモリ。 Qwen自身が、会話のあとに、好み、指摘、プロジェクトの文脈、外部の参照をメモとして保存します。保存先は ~/.qwen/projects/<プロジェクト>/memory/ で、平文のMarkdownです。設定 memory.enableManagedAutoMemory は既定でオンです。公式の書き方では、自動メモリは「最善の努力」で、必ず覚えてほしいことは QWEN.md に書く、とされています。関連のコマンドは、/memory（パネル。自動保存と整理の切り替え、ファイルを開く）、/remember <テキスト>、/forget <テキスト>、/dream（整理を今すぐ）です。チームメモリ（memory.enableTeamMemory）は既定でオフで、オンにするとリポジトリの中にコミットされて、アクセスできる全員に見えます。秘密のスキャンはあるが、「保証ではなく補助」と書かれています。

僕らの見立てです。自動メモリは、既定でオンの設定で、あなたの作業内容に関するメモを、手元のファイルに書き続けます。共有のパソコンや、秘密を含む作業では、/memory で止めるか、保存先を見直す価値があります。なお、メモがモデルの提供元に送られるかどうかは、読んだページには書かれていませんでした（次の会話で文脈として読み込まれれば、送る内容の一部になる、というのは僕らの推測です）。

読ませたくないもの：.qwenignore

プロジェクトの根の .qwenignore、.agentignore、.aiignore に、.gitignore と同じような書き方で、ツールが避けるパスを書きます（context.fileFiltering.customIgnoreFiles で、.cursorignore なども足せます）。公式の例は、/packages/、apikeys.txt、*.md と !README.md です。公式の注意は、無視のルールを守るのは、それを尊重するツールだけであること、Gitなどのほかのサービスからは見えること、変更は再起動後に効くこと、.gitignore と完全には同じでないことです。秘密の置き場所の対策としては、.qwenignore だけでは足りません（これは僕らの見立てで、公式が書いているのは上の限界までです）。

カスタムコマンド

~/.qwen/commands/ か <プロジェクト>/.qwen/commands/ にMarkdownのファイルを置くと、/ のコマンドになります（名前が重なるとプロジェクトが優先。git/commit.md は /git:commit）。本文がプロンプトで、{{args}} で引数を入れられます。旧来のTOML形式は非推奨です。

8. データと規約：Qwen Codeで分かること

前のガイド（01）に、認証ごとに規約が変わる表を書きました。ここでは、追加で読めた点だけを書きます（Terms of Service and Privacy Notice、2026年10月22日更新の表示）。

9. 今回読んでいないもの

公式のOverviewには、サブエージェント、スキル、フック、MCP、LSP、IDE連携、GitHub Actions、デーモン（qwen serve、READMEは実験的と書く）、SDK、チャットアプリ連携なども並んでいます。深くは読んでいません。ヘッドレス（qwen -p "..."）の終了コードは、認証の失敗が41、入力の不備が42、サンドボックスのエラーが44、設定ファイルの不正が52、回数の上限が53と、トラブルシューティングのページに載っています。

気をつけること

出典