Qwen Code の設定

設定のレイヤー

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

設定ファイル

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

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

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

• カスタムサンドボックスプロファイル（例: .qwen/sandbox-macos-custom.sb、.qwen/sandbox.Dockerfile）。
• .qwen/skills/ 配下の Agent Skills（各 Skill は 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
      }
    }
  }
}

timeout (リクエストタイムアウト):

timeout はリクエストごとのタイムアウト時間（ミリ秒単位、デフォルト 120000）です。リクエストを中止するのではなく、リクエストタイムアウトを無効にするには 0 に設定します（QWEN_STREAM_IDLE_TIMEOUT_MS=0 の規約に準拠）。QWEN_CODE_API_TIMEOUT_MS 環境変数を通じて設定することもできます。これは、ストリーミングチャンク間の非アクティブ時間を制限する QWEN_STREAM_IDLE_TIMEOUT_MS とは異なります。

max_tokens (出力トークン制限):

samplingParams.max_tokens も QWEN_CODE_MAX_OUTPUT_TOKENS も設定されていない場合、Qwen Code は一般的に、選択されたモデルの宣言された出力制限をリクエストのデフォルト出力制限として使用します。それでも応答がその制限に達した場合、Qwen Code はエスカレートされた制限（64K を下限とする）でリトライし、継続ターンにわたって回復を試みることがあります。

OpenAI 互換プロバイダーの場合、samplingParams はワイヤーシェイプのエスケープハッチとしても機能します。これが設定されると、そのキーはそのまま透過的に渡され、Qwen Code は max_tokens のデフォルト値を合成しません。max_completion_tokens などのプロバイダー固有のパラメータにこれを使用します。

固定の出力制限を強制するには、設定で samplingParams.max_tokens を設定するか、QWEN_CODE_MAX_OUTPUT_TOKENS 環境変数を使用します。明示的な制限は、自動的な出力トークンのエスカレーションを無効にします。

toolResultContentFormat:

OpenAI 互換リクエストにおいて、テキストのみのツール結果がどのようにシリアライズされるかを制御します。デフォルトの "parts" は、標準のコンテンツパート配列の形状を維持します。古い GLM-5.1 vLLM/SGLang テンプレートなど、ツールテンプレートがテキストコンテンツパートを無視するレガシーな OpenAI 互換ランタイムに対してのみ "string" を設定します。ツールから返されるメディアは引き続き splitToolMedia によって制御されます。

contextWindowSize:

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

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

modalities:

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

customHeaders:

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

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

model.openAILoggingDir の例:

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

fastModel

visionModel

voiceModel

modelFallbacks

modelPricing

context

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

ファイル検索（@ 補完など）でパフォーマンスの問題が発生している場合、特にファイル数が非常に多いプロジェクトでは、推奨順に以下の対処法を試してください。

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

tools

memory

自動メモリの仕組みと、/memory、/remember、/dream コマンドの使用方法の詳細については、Memory を参照してください。

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 などのキーボードショートカットをインターセプトすることはありません。

skills

モデルに公開される Skills を制御します。

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 の順です。

telemetry

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

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 のアプローチについては、Authentication を参照してください。

環境変数テーブル

コマンドライン引数

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/<configured-context-filename>（例: ユーザーホームディレクトリ内の ~/.qwen/QWEN.md）。
     • 範囲: すべてのプロジェクトに対するデフォルトの指示を提供します。
  2. プロジェクトルートおよび祖先のコンテキストファイル:
     • 場所: CLIは、現在の作業ディレクトリで設定されたコンテキストファイルを検索し、次にプロジェクトルート（.git フォルダで識別）またはホームディレクトリまでの各親ディレクトリで検索します。
     • 範囲: プロジェクト全体またはその大部分に関連するコンテキストを提供します。
• 連結とUI表示: 見つかったすべてのコンテキストファイルのコンテンツは（その由来とパスを示すセパレータ付きで）連結され、システムプロンプトの一部として提供されます。CLIフッターには読み込まれたコンテキストファイルの数が表示され、アクティブな指示コンテキストに関するクイックな視覚的な手がかりを提供します。
• コンテンツのインポート: @path/to/file.md 構文を使用して他のMarkdownファイルをインポートすることで、コンテキストファイルをモジュール化できます。詳細については、Memory documentation を参照してください。
• メモリ管理のコマンド:
  • /memory を使用して、メモリ管理ダイアログを開きます。
  • ダイアログからメモリを更新して、設定されたすべての場所からコンテキストファイルを再スキャンおよび再読み込みします。
  • /memory コマンドの完全な詳細については、Commands documentation を参照してください。

これらの設定レイヤーとコンテキストファイルの階層的な性質を理解して活用することで、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
  }
}