Qwen Code 設定

設定レイヤー

設定は以下の優先順位で適用されます（番号が小さいものほど、番号が大きいものによって上書きされます）。

設定ファイル

Qwen Code は、永続的な設定に JSON 設定ファイルを使用します。ファイルには4つの場所があります。

プロジェクト内の .qwen ディレクトリ

プロジェクト設定ファイルに加えて、プロジェクトの .qwen ディレクトリには、Qwen Code の操作に関連する他のプロジェクト固有のファイルを含めることができます。例：

• カスタムサンドボックスプロファイル（例: .qwen/sandbox-macos-custom.sb、.qwen/sandbox.Dockerfile）。
• .qwen/skills/ 配下の Agent スキル（各スキルは SKILL.md を含むディレクトリです）。

設定の移行

Qwen Code は、レガシー設定を新しい形式に自動的に移行します。古い設定ファイルは移行前にバックアップされます。以下の設定は、否定 (disable*) から肯定 (enable*) の命名に変更されました。

disableAutoUpdate と disableUpdateNag の統合ポリシー

両方のレガシー設定が存在し、異なる値を持つ場合、移行は次のポリシーに従います: disableAutoUpdate または disableUpdateNag のいずれかが true の場合、enableAutoUpdate は false になります。

settings.json で利用可能な設定

設定はカテゴリ別に整理されています。ほとんどの設定は、settings.json ファイル内の対応するトップレベルのカテゴリオブジェクト内に配置する必要があります。proxy や plansDirectory などのいくつかのトップレベル設定は、互換性のために直接のルートキーのまま残されています。

general

output

ui

ide

privacy

model

{
  "model": {
    "generationConfig": {
      "timeout": 60000,
      "contextWindowSize": 128000,
      "modalities": {
        "image": true
      },
      "enableCacheControl": true,
      "toolResultContentFormat": "parts",
      "customHeaders": {
        "X-Client-Request-ID": "req-123"
      },
      "extra_body": {
        "enable_thinking": true
      },
      "samplingParams": {
        "temperature": 0.2,
        "top_p": 0.8,
        "max_tokens": 1024
      }
    }
  }
}

max_tokens（適応型出力トークン）:

samplingParams.max_tokens が設定されていない場合、Qwen Code は適応型出力トークン戦略を使用して GPU リソースの使用を最適化します：

1. リクエストはデフォルトの 8K 出力トークン制限で開始されます
2. 応答が切り捨てられた場合（モデルが制限に達した場合）、Qwen Code は自動的に 64K トークンで再試行します
3. 部分的な出力は破棄され、再試行からの完全な応答に置き換えられます

これはユーザーには透過的です — エスカレーションが発生した場合、再試行インジケーターが一時的に表示されることがあります。応答の 99% は 5K トークン未満であるため、再試行はめったに発生しません（リクエストの 1% 未満）。

この動作をオーバーライドするには、設定で samplingParams.max_tokens を設定するか、QWEN_CODE_MAX_OUTPUT_TOKENS 環境変数を使用します。

toolResultContentFormat:

テキストのみのツール結果を OpenAI 互換のリクエストでシリアライズする方法を制御します。デフォルトの "parts" は標準の content-parts 配列形式を維持します。"string" は、テキスト content parts を無視するレガシーな OpenAI 互換ランタイム（古い GLM-5.1 vLLM/SGLang テンプレートなど）でのみ設定します。ツールが返すメディアは引き続き splitToolMedia で制御されます。

contextWindowSize:

選択したモデルのデフォルトのコンテキストウィンドウサイズをオーバーライドします。Qwen Code は、モデル名の一致に基づく組み込みのデフォルトを使用してコンテキストウィンドウを決定し、定数のフォールバック値を持ちます。プロバイダーの実効コンテキスト制限が Qwen Code のデフォルトと異なる場合にこの設定を使用します。この値は、モデルの想定される最大コンテキスト容量を定義し、リクエストごとのトークン制限ではありません。

選択したモデルが modelProviders で定義されている場合、トップレベルの model.generationConfig ではなく、そのプロバイダーエントリの generationConfig に contextWindowSize を設定します。プロバイダーモデルエントリはシールされているため、トップレベルの生成設定は欠落しているプロバイダーフィールドを補完しません。

modalities:

選択したモデルの自動検出された入力モダリティをオーバーライドします。Qwen Code は、モデル名のパターンマッチングに基づいてサポートされているモダリティ（画像、PDF、音声、動画）を自動検出します。この設定は、自動検出が正しくない場合 — 例えば、認識されないが PDF をサポートしているモデルに対して pdf を有効にする場合 — に使用します。形式: { "image": true, "pdf": true, "audio": true, "video": true }。キーを省略するか false に設定すると、サポートされていない型として扱われます。

customHeaders:

すべての API リクエストにカスタム HTTP ヘッダーを追加できます。これは、リクエストトレーシング、モニタリング、API ゲートウェイルーティング、または異なるモデルに異なるヘッダーが必要な場合に便利です。プロバイダーモデルの場合、modelProviders[].generationConfig.customHeaders で customHeaders を定義します。一致するプロバイダーエントリがないランタイムモデルの場合、model.generationConfig.customHeaders で定義します。2つのレベルの間でマージは行われません。

extra_body フィールドを使用すると、API に送信されるリクエスト本文にカスタムパラメーターを追加できます。これは、標準の設定フィールドでカバーされていないプロバイダー固有のオプションに便利です。注: このフィールドは OpenAI 互換プロバイダー (openai、qwen-oauth) でのみサポートされています。Anthropic および Gemini プロバイダーでは無視されます。 プロバイダーモデルの場合、modelProviders[].generationConfig.extra_body で extra_body を定義します。一致するプロバイダーエントリがないランタイムモデルの場合、model.generationConfig.extra_body で定義します。

model.openAILoggingDir の例:

• "~/qwen-logs" - ~/qwen-logs ディレクトリにログを出力
• "./custom-logs" - カレントディレクトリからの相対パス ./custom-logs にログを出力
• "/tmp/openai-logs" - 絶対パス /tmp/openai-logs にログを出力

fastModel

context

ファイル検索パフォーマンスのトラブルシューティング

ファイル検索（例: @ 補完）でパフォーマンスの問題が発生している場合、特にファイル数が非常に多いプロジェクトでは、推奨順に以下の方法を試すことができます。

1. 無視ファイルを使用する: プロジェクトルートに .qwenignore または設定されたカスタム無視ファイルを作成して、参照する必要のない大量のファイルを含むディレクトリ（ビルドアーティファクト、ログ、node_modules など）を除外します。クロールされるファイルの総数を減らすことが、パフォーマンスを向上させる最も効果的な方法です。
2. ファジー検索を無効にする: ファイルの無視だけでは不十分な場合、settings.json ファイルで enableFuzzySearch を false に設定してファジー検索を無効にできます。これにより、よりシンプルで非ファジーのマッチングアルゴリズムが使用され、高速になる可能性があります。
3. 再帰的ファイル検索を無効にする: 最後の手段として、enableRecursiveFileSearch を false に設定して再帰的ファイル検索を完全に無効にできます。これによりプロジェクトの再帰的クロールが回避されるため、最も高速なオプションになります。ただし、@ 補完を使用する際にファイルの完全パスを入力する必要があります。

tools

memory

自動記憶の動作と、/memory、/remember、/dream コマンドの使い方の詳細は Memory を参照してください。

permissions

permissions システムは、どのツールを実行できるか、どのツールに確認が必要か、どのツールをブロックするかをきめ細かく制御します。

決定優先順位（高い順）: deny > ask > allow > (デフォルト/対話モード)

最初に一致したルールが適用されます。ルールは "ToolName" または "ToolName(specifier)" の形式を使用します。

ツール名のエイリアス（ルール内ではどれでも使用可能）:

メタカテゴリ:

一部のルール名は複数のツールを自動的にカバーします:

[!important] Read(/path/**) は 4つすべて の読み取りツール（ファイル読み取り、grep、glob、ディレクトリ一覧）に一致します。 ファイル読み取りのみに制限するには、ReadFile(/path/**) または read_file(/path/**) を使用してください。

ルール構文の例:

パスパターンのプレフィックス:

シェルコマンドのバイパス防止:

Read、Edit、WebFetch の権限ルールは、エージェントが同等のシェルコマンドを実行する場合にも適用されます。たとえば、Read(./.env) が deny にある場合、エージェントはシェルコマンドの cat .env でそれを回避できません。サポートされているシェルコマンドには、cat、grep、curl、wget、cp、mv、rm、chmod などがあります。不明または安全なコマンド（例: git）はファイル/ネットワークルールの影響を受けません。

レガシー設定からの移行:

設定例:

{
  "permissions": {
    "allow": ["Bash(git *)", "Bash(npm run *)", "Read(//Users/alice/code/**)"],
    "ask": ["Bash(git push *)", "Edit"],
    "deny": ["Bash(rm -rf *)", "Read(.env)", "WebFetch(malicious.com)"]
  }
}

[!tip] 対話型CLIで /permissions を使用すると、settings.json を直接編集せずにルールを表示、追加、削除できます。

slashCommands

CLIで使用可能なスラッシュコマンドを制御します。マルチテナントやエンタープライズデプロイメントでコマンドサーフェスを制限する場合に便利です。

同じ拒否リストは、--disabled-slash-commands CLIフラグ（カンマ区切りまたは繰り返し）および QWEN_DISABLED_SLASH_COMMANDS 環境変数でも指定できます。3つのソースの値はすべて結合されます。

例 — サンドボックスデプロイメントの組み込みコマンドをロックダウン:

{
  "slashCommands": {
    "disabled": ["auth", "mcp", "extensions", "ide", "quit"]
  }
}

システムレベルの settings.json（/etc/qwen-code/settings.json または QWEN_CODE_SYSTEM_SETTINGS_PATH）にこれらの値を設定すると、ユーザーは自分のスコープで拒否リストを縮小できず、無効化されたコマンドはオートコンプリートに表示されず、入力しても実行されません。

[!note] この設定はスラッシュコマンド（例: /auth、/mcp）のみを制限します。ツールの権限には影響しません（それについては permissions.deny を参照）。また、Ctrl+C や Esc などのキーボードショートカットもインターセプトしません。

mcp

lsp

[!warning] 実験的機能: LSP サポートは現在実験的であり、デフォルトでは無効になっています。--experimental-lsp コマンドラインフラグを使用して有効にしてください。

Language Server Protocol (LSP) は、定義への移動、参照の検索、診断などのコードインテリジェンス機能を提供します。

LSP サーバーの設定は、settings.json ではなく、プロジェクトルートディレクトリの .lsp.json ファイルを介して行われます。設定の詳細と例については、LSP ドキュメント を参照してください。

security

advanced

experimental

mcpServers

1つ以上の Model-Context Protocol (MCP) サーバーへの接続を構成し、カスタムツールを検出して使用します。Qwen Code は、設定された各 MCP サーバーに接続して利用可能なツールを検出しようとします。複数の MCP サーバーが同じ名前のツールを公開している場合、競合を避けるために、設定で定義したサーバーエイリアスをツール名に前置します（例: serverAlias__actualToolName）。互換性のために、システムが MCP ツール定義から特定のスキーマプロパティを削除する場合があることに注意してください。command、url、httpUrl のうち少なくとも1つを指定する必要があります。複数指定する場合、優先順位は httpUrl、url、command の順です。

テレメトリー

Qwen Code のログとメトリクス収集を設定します。詳細については、テレメトリー を参照してください。

settings.json の例

以下は、v0.3.0 で新しくなったネスト構造の settings.json ファイルの例です。

{
  "proxy": "http://localhost:7890",
  "plansDirectory": "./.qwen/plans",
  "general": {
    "vimMode": true,
    "preferredEditor": "code"
  },
  "ui": {
    "theme": "GitHub",
    "hideTips": false,
    "customWittyPhrases": [
      "You forget a thousand things every day. Make sure this is one of 'em",
      "Connecting to AGI"
    ]
  },
  "tools": {
    "approvalMode": "yolo",
    "sandbox": "docker",
    "sandboxImage": "ghcr.io/qwenlm/qwen-code:0.14.1",
    "discoveryCommand": "bin/get_tools",
    "callCommand": "bin/call_tool",
    "exclude": ["write_file"]
  },
  "mcpServers": {
    "mainServer": {
      "command": "bin/mcp_server.py"
    },
    "anotherServer": {
      "command": "node",
      "args": ["mcp_server.js", "--verbose"]
    }
  },
  "telemetry": {
    "enabled": true,
    "target": "local",
    "otlpEndpoint": "http://localhost:4317",
    "logPrompts": true,
    "includeSensitiveSpanAttributes": false,
    "sensitiveSpanAttributeMaxLength": 1048576
  },
  "privacy": {
    "usageStatisticsEnabled": true
  },
  "model": {
    "name": "qwen3-coder-plus",
    "maxSessionTurns": 10,
    "enableOpenAILogging": false,
    "openAILoggingDir": "~/qwen-logs",
  },
  "context": {
    "fileName": ["CONTEXT.md", "QWEN.md"],
    "includeDirectories": ["path/to/dir1", "~/path/to/dir2", "../path/to/dir3"],
    "loadFromIncludeDirectories": true,
    "fileFiltering": {
      "respectGitIgnore": false
    }
  },
  "advanced": {
    "excludedEnvVars": ["DEBUG", "DEBUG_MODE", "NODE_ENV"]
  }
}

シェル履歴

CLI は実行したシェルコマンドの履歴を保持します。異なるプロジェクト間での競合を避けるため、この履歴はユーザーのホームフォルダ内のプロジェクト固有のディレクトリに保存されます。

• 保存場所: ~/.qwen/tmp/<project_hash>/shell_history
  • <project_hash> はプロジェクトのルートパスから生成される一意の識別子です。
  • 履歴は shell_history というファイルに保存されます。

環境変数と .env ファイル

環境変数は、特にトークンなどの機密情報や環境間で変わる可能性のある設定について、アプリケーションを構成する一般的な方法です。

Qwen Code は .env ファイルから環境変数を自動的に読み込むことができます。 認証関連の変数（OPENAI_* など）および推奨される .qwen/.env の方法については、認証 を参照してください。

環境変数一覧

コマンドライン引数

CLI の実行時に直接渡された引数は、その特定のセッションの他の設定を上書きできます。

サンドボックスイメージの選択における優先順位は次のとおりです： --sandbox-image > QWEN_SANDBOX_IMAGE > tools.sandboxImage > 組み込みのデフォルトイメージ。

コマンドライン引数テーブル

コンテキストファイル（階層型指示コンテキスト）

CLIの動作設定そのものではありませんが、コンテキストファイル（デフォルトではQWEN.md、context.fileName設定で変更可能）は、指示コンテキスト（「メモリ」とも呼ばれます）を設定するために重要です。この強力な機能を使用すると、プロジェクト固有の指示、コーディングスタイルガイド、または関連する背景情報をAIに提供でき、応答をニーズに合わせてより適切かつ正確にできます。CLIには、フッターにロードされたコンテキストファイルの数を示すインジケーターなどのUI要素が含まれており、アクティブなコンテキストを把握できます。

• 目的: これらのMarkdownファイルには、Qwenモデルが対話中に認識すべき指示、ガイドライン、またはコンテキストが含まれています。このシステムは、この指示コンテキストを階層的に管理するように設計されています。

コンテキストファイルの内容例（例：QWEN.md）

以下は、TypeScriptプロジェクトのルートにあるコンテキストファイルの概念的な例です。

# Project: My Awesome TypeScript Library

## General Instructions:
- When generating new TypeScript code, please follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.
- Prefer functional programming paradigms where appropriate.
- All code should be compatible with TypeScript 5.0 and Node.js 22+.

## Coding Style:
- Use 2 spaces for indentation.
- Interface names should be prefixed with `I` (e.g., `IUserService`).
- Private class members should be prefixed with an underscore (`_`).
- Always use strict equality (`===` and `!==`).

## Specific Component: `src/api/client.ts`
- This file handles all outbound API requests.
- When adding new API call functions, ensure they include robust error handling and logging.
- Use the existing `fetchWithRetry` utility for all GET requests.

## Regarding Dependencies:
- Avoid introducing new external dependencies unless absolutely necessary.
- If a new dependency is required, please state the reason.

この例は、一般的なプロジェクトコンテキスト、特定のコーディング規約、特定のファイルやコンポーネントに関するメモなどをどのように提供できるかを示しています。コンテキストファイルがより関連性が高く正確であるほど、AIはより適切に支援できます。プロジェクト固有のコンテキストファイルを使用して、規約やコンテキストを確立することを強く推奨します。

• 階層的読み込みと優先順位: CLIは、複数の場所からコンテキストファイル（例：QWEN.md）を読み込むことで、階層的なメモリシステムを実装しています。このリストの下位（より具体的）にあるファイルの内容は、上位（より一般的）にあるファイルの内容を上書きまたは補足する傾向があります。正確な連結順序と最終的なコンテキストは、/memoryダイアログから確認できます。一般的な読み込み順序は以下のとおりです。
  1. グローバルコンテキストファイル:
     • 場所: ~/.qwen/<設定されたコンテキストファイル名>（例：ホームディレクトリの~/.qwen/QWEN.md）。
     • スコープ: すべてのプロジェクトにデフォルトの指示を提供します。
  2. プロジェクトルートおよび上位ディレクトリのコンテキストファイル:
     • 場所: CLIは、現在の作業ディレクトリから始めて、プロジェクトルート（.gitフォルダで識別）またはホームディレクトリに達するまで、各親ディレクトリで設定されたコンテキストファイルを検索します。
     • スコープ: プロジェクト全体またはその重要な部分に関連するコンテキストを提供します。
• 連結とUI表示: 見つかったすべてのコンテキストファイルの内容は連結され（出所とパスを示す区切り文字付き）、システムプロンプトの一部として提供されます。CLIのフッターにはロードされたコンテキストファイルの数が表示され、アクティブな指示コンテキストをすぐに視覚的に確認できます。
• コンテンツのインポート: @path/to/file.md構文を使用して、他のMarkdownファイルをインポートすることで、コンテキストファイルをモジュール化できます。詳細については、メモリのドキュメントを参照してください。
• メモリ管理のためのコマンド:
  • /memoryを使用してメモリ管理ダイアログを開きます。
  • ダイアログからメモリを更新して、設定されたすべての場所からコンテキストファイルを再スキャンおよび再読み込みします。
  • /memoryコマンドの詳細については、コマンドのドキュメントを参照してください。

これらの設定レイヤーとコンテキストファイルの階層的な性質を理解して活用することで、AIのメモリを効果的に管理し、Qwen Codeの応答を特定のニーズやプロジェクトに合わせて調整できます。

サンドボックス

Qwen Codeは、危険な可能性のある操作（シェルコマンドやファイル変更など）をサンドボックス環境内で実行して、システムを保護できます。

サンドボックスはデフォルトで無効になっていますが、以下の方法で有効にできます。

• --sandboxまたは-sフラグを使用する。
• QWEN_SANDBOX環境変数を設定する。
• 設定でtools.sandboxを設定する。

⚠️ --yoloはサンドボックスを自動的に有効化しません。 YOLOモードはツール呼び出しを自動承認するだけです。サンドボックスは--sandbox、QWEN_SANDBOX、またはtools.sandboxを介して明示的にオプトインする必要があります。--yolo（または--approval-mode=yolo）を使用したヘッドレス/非対話型実行でサンドボックスがない場合、モデルは現在のプロセスの権限レベルでシェル、書き込み、編集ツールを実行できます。その場合、Qwen Codeは警告をstderrに出力します。トレードオフを確認したら、QWEN_CODE_SUPPRESS_YOLO_WARNING=1で抑制できます。

デフォルトでは、プリビルドのqwen-code-sandbox Dockerイメージを使用します。

プロジェクト固有のサンドボックス設定が必要な場合は、プロジェクトのルートディレクトリに.qwen/sandbox.DockerfileというカスタムDockerfileを作成できます。このDockerfileはベースのサンドボックスイメージに基づいて作成できます。

FROM qwen-code-sandbox
# Add your custom dependencies or configurations here
# For example:
# RUN apt-get update && apt-get install -y some-package
# COPY ./my-config /app/my-config

.qwen/sandbox.Dockerfileが存在する場合、Qwen Codeを実行するときにBUILD_SANDBOX環境変数を使用して、カスタムサンドボックスイメージを自動的にビルドできます。

BUILD_SANDBOX=1 qwen -s

使用統計

Qwen Codeの改善に役立てるため、匿名化された使用統計を収集しています。このデータは、CLIの使用方法の把握、一般的な問題の特定、新機能の優先順位付けに役立ちます。

収集するもの:

• ツール呼び出し: 呼び出されたツールの名前、成功または失敗の有無、実行にかかった時間を記録します。ツールに渡された引数やツールから返されたデータは収集しません。
• APIリクエスト: 各リクエストで使用されたモデル、リクエストの期間、成功したかどうかを記録します。プロンプトや応答の内容は収集しません。
• セッション情報: 有効なツールや承認モードなど、CLIの設定に関する情報を収集します。

収集しないもの:

• 個人識別情報（PII）: 名前、メールアドレス、APIキーなどの個人情報は収集しません。
• プロンプトと応答の内容: プロンプトの内容やモデルからの応答は記録しません。
• ファイルの内容: CLIによって読み取りまたは書き込みが行われたファイルの内容は記録しません。

オプトアウト方法:

いつでも使用統計の収集をオプトアウトするには、settings.jsonファイルのprivacyカテゴリの下にあるusageStatisticsEnabledプロパティをfalseに設定します。

{
  "privacy": {
    "usageStatisticsEnabled": false
  }
}