Qwen Code の設定

設定の階層

設定は以下の優先順位で適用されます（数字が小さいほど優先度が低く、大きいほど上書きされます）：

設定ファイル

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

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

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

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

設定の移行

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

disableAutoUpdate と disableUpdateNag の統合ポリシー

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

settings.json で利用可能な設定

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

top-level

general

output

ui

ide

privacy

model

model.generationConfig の例:

{
  "model": {
    "generationConfig": {
      "timeout": 60000,
      "contextWindowSize": 128000,
      "modalities": {
        "image": true
      },
      "enableCacheControl": true,
      "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 環境変数を使用してください。

contextWindowSize:

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

modalities:

選択したモデルの自動検出された入力モダリティを上書きします。Qwen Code はモデル名パターンマッチングに基づき、サポートされているモダリティ（画像、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 の使用: プロジェクトルートに .qwenignore ファイルを作成し、参照不要な大量のファイルを含むディレクトリ（例：ビルド成果物、ログ、node_modules）を除外します。クロールされるファイルの総数を減らすことが、パフォーマンス向上に最も効果的です。
2. ファジー検索の無効化: ファイルの除外だけでは不十分な場合、settings.json で enableFuzzySearch を false に設定してファジー検索を無効化できます。これにより、より単純な非ファジーマッチングアルゴリズムが使用され、高速化される場合があります。
3. 再帰ファイル検索の無効化: 最終手段として、enableRecursiveFileSearch を false に設定して再帰ファイル検索を完全に無効化できます。プロジェクトの再帰クロールを回避するため、これが最速のオプションになります。ただし、@ 補完使用時にファイルへのフルパスを入力する必要があります。

tools

memory

自動メモリの動作方法および /memory、/remember、/dream コマンドの使用方法については メモリ を参照してください。

permissions

権限システムは、どのツールを実行可能か、どのツールに確認が必要か、どのツールがブロックされるかを細かく制御します。

決定優先順位（高い順）: deny > ask > allow > (デフォルト/インタラクティブモード)

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

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

メタカテゴリ:

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

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

ルール構文の例:

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

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

Read、Edit、WebFetch の権限ルールは、エージェントが同等のシェルコマンドを実行する場合にも適用されます。例えば、deny に Read(./.env) が含まれている場合、エージェントはシェルコマンドで 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] settings.json を直接編集せずに、インタラクティブ CLI で /permissions を使用してルールを表示、追加、削除できます。

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

mcpServers

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

telemetry

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

settings.json の例

以下は、v0.3.0 以降の新しいネスト構造を持つ settings.json ファイルの例です：

{
  "proxy": "http://localhost:7890",
  "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
  },
  "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 20+.

## 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 show コマンドで確認できます。一般的な読み込み順序は以下の通りです：
  1. グローバルコンテキストファイル:
     • 場所: ~/.qwen/<configured-context-filename>（例：ユーザーホームディレクトリの ~/.qwen/QWEN.md）。
     • 適用範囲: すべてのプロジェクトのデフォルト指示を提供。
  2. プロジェクトルートおよび祖先コンテキストファイル:
     • 場所: CLI は現在の作業ディレクトリで設定されたコンテキストファイルを検索し、プロジェクトルート（.git フォルダで識別）またはホームディレクトリのいずれかに到達するまで各親ディレクトリを検索。
     • 適用範囲: プロジェクト全体またはその重要な部分に関連するコンテキストを提供。
• 連結と UI 表示: 見つかったすべてのコンテキストファイルのコンテンツは（出典とパスを示す区切り文字付きで）連結され、システムプロンプトの一部として提供されます。CLI フッターには読み込まれたコンテキストファイルの数が表示され、アクティブな指示コンテキストに関する視覚的な手がかりを提供します。
• コンテンツのインポート: @path/to/file.md 構文を使用して他の Markdown ファイルをインポートすることで、コンテキストファイルをモジュール化できます。詳細は メモリインポートプロセッサードキュメント を参照してください。
• メモリ管理コマンド:
  • /memory refresh を使用して、すべての構成された場所からすべてのコンテキストファイルの再スキャンと再読み込みを強制。これにより AI の指示コンテキストが更新されます。
  • /memory show を使用して、現在読み込まれている結合された指示コンテキストを表示。AI が使用している階層とコンテンツを確認できます。
  • /memory コマンドおよびそのサブコマンド（show および refresh）の詳細については コマンドドキュメント を参照してください。

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

サンドボックス

Qwen Code は、システムを保護するために、サンドボックス環境内で潜在的に安全でない操作（シェルコマンドやファイル変更など）を実行できます。

サンドボックス はデフォルトで無効ですが、以下の方法で有効化できます：

• --sandbox または -s フラグを使用。
• QWEN_SANDBOX 環境変数を設定。
• --yolo または --approval-mode=yolo 使用時はデフォルトでサンドボックスが有効化。

デフォルトでは、事前構築された 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
  }
}