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 ファイル内の対応する最上位レベルのカテゴリオブジェクト内に配置する必要があります。

一般

出力

ui

IDE

プライバシー

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
      }
    }
  }
}

contextWindowSize:

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

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 にログを保存

コンテキスト

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

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

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

ツール

mcp

lsp

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

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

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

セキュリティ

高度な設定

mcpServers

カスタムツールの検出および利用のため、1 つ以上のモデル・コンテキスト・プロトコル (MCP) サーバーへの接続を設定します。Qwen Code は、設定された各 MCP サーバーに接続して利用可能なツールを検出しようと試みます。複数の MCP サーバーが同じ名前のツールを公開している場合、競合を回避するために、ツール名には設定で定義したサーバーエイリアスがプレフィックスとして付加されます（例：serverAlias__actualToolName）。なお、互換性のため、システムが MCP ツール定義の一部のスキーマプロパティを除外する場合があります。command、url、httpUrl のいずれか 1 つ以上を指定する必要があります。複数が指定された場合、優先順位は httpUrl → url → command です。

テレメトリ

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

例: settings.json

以下は、v0.3.0 から導入された入れ子構造の settings.json ファイルの例です。

{
  "general": {
    "vimMode": true,
    "preferredEditor": "code"
  },
  "ui": {
    "theme": "GitHub",
    "hideTips": false,
    "customWittyPhrases": [
      "あなたは毎日千のことを忘れています。これがそのうちの一つであるようにしましょう",
      "AGI に接続中"
    ]
  },
  "tools": {
    "approvalMode": "yolo",
    "sandbox": "docker",
    "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 を実行する際に直接渡された引数は、そのセッションに限り他の設定を上書きします。

コマンドライン引数一覧表

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

CLI の 動作 に関する厳密な設定ではありませんが、コンテキストファイル（デフォルトは QWEN.md で、context.fileName 設定により変更可能）は、指示コンテキスト（別名「メモリ」）の設定に不可欠です。この強力な機能により、プロジェクト固有の指示、コーディングスタイルガイド、またはその他の関連する背景情報を AI に提供でき、応答をあなたの要件に合わせてより適切かつ正確なものにします。CLI には、フッターに読み込まれたコンテキストファイル数を示すインジケーターなどの UI 要素が含まれており、現在有効なコンテキストを常に把握できるようになっています。

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

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

TypeScript プロジェクトのルートに配置されるコンテキストファイルの概念的な例を以下に示します。

# プロジェクト：My Awesome TypeScript Library

## 一般的な指示：
- 新しい TypeScript コードを生成する際は、既存のコーディングスタイルに従ってください。
- 新しく追加する関数およびクラスには、必ず JSDoc コメントを付与してください。
- 適切な場合は、関数型プログラミングのパラダイムを優先してください。
- すべてのコードは TypeScript 5.0 および Node.js 20+ と互換性を持つ必要があります。

## コーディングスタイル：
- インデントには半角スペースを 2 文字使用してください。
- インターフェース名には `I` を接頭辞として付けること（例：`IUserService`）。
- クラス内のプライベートメンバーには、アンダースコア (`_`) を接頭辞として付けること。
- 厳密な等価比較（`===` および `!==`）を常に使用してください。

## 特定のコンポーネント：`src/api/client.ts`
- このファイルは、すべての外部向け API リクエストを処理します。
- 新しい API 呼び出し関数を追加する際は、堅牢なエラー処理とログ出力を確実に含めてください。
- GET リクエストには、既存の `fetchWithRetry` ユーティリティを使用してください。

依存関係について：

• 必須でない限り、新しい外部依存関係を導入しないでください。
• 新しい依存関係が必要な場合は、その理由を明記してください。

この例では、プロジェクト全体のコンテキスト、特定のコーディング規約、さらには特定のファイルやコンポーネントに関するメモを提供する方法を示しています。コンテキストファイルが関連性が高く、正確であるほど、AI の支援効果が高まります。プロジェクト固有のコンテキストファイルを作成し、規約やコンテキストを確立することを強く推奨します。

- **階層的な読み込みと優先順位：** CLI は、複数の場所（例：`QWEN.md`）からコンテキストファイルを読み込むことで、階層的なメモリーシステムを実装しています。このリストの下位（より具体的）にあるファイルの内容は、上位（より一般的）にあるファイルの内容を通常、上書きまたは補完します。結合順序および最終的なコンテキストは、`/memory show` コマンドで確認できます。典型的な読み込み順序は以下の通りです：
  1. **グローバルコンテキストファイル：**
     - 位置：`~/.qwen/<設定されたコンテキストファイル名>`（例：ユーザーのホームディレクトリ内の `~/.qwen/QWEN.md`）。
     - スコープ：すべてのプロジェクトに適用されるデフォルトの指示を提供します。
  2. **プロジェクトルートおよび祖先ディレクトリのコンテキストファイル：**
     - 位置：CLI は、現在の作業ディレクトリおよび `.git` フォルダーでプロジェクトルートを識別するか、あるいはホームディレクトリに達するまで、各親ディレクトリ内で設定されたコンテキストファイルを検索します。
     - スコープ：プロジェクト全体またはその大部分に関連するコンテキストを提供します。
- **結合と UI 上の表示：** 見つかったすべてのコンテキストファイルの内容は、それぞれの出所とパスを示す区切り文字とともに結合され、システムプロンプトの一部として提供されます。CLI のフッターには読み込まれたコンテキストファイルの数が表示され、現在有効な指示コンテキストを視覚的に素早く把握できます。
- **コンテンツのインポート：** `@path/to/file.md` 構文を使用して、他の Markdown ファイルをインポートすることで、コンテキストファイルをモジュール化できます。詳細については、[メモリーインポートプロセッサのドキュメント](../configuration/memory) を参照してください。
- **メモリ管理のためのコマンド：**
  - `/memory refresh` を使用すると、すべての設定済み場所からコンテキストファイルを強制的に再スキャン・再読み込みし、AI の指示コンテキストを更新できます。
  - `/memory show` を使用すると、現在読み込まれている統合された指示コンテキストを表示でき、AI が使用している階層構造およびコンテンツを確認できます。
  - `/memory` コマンドおよびそのサブコマンド（`show` および `refresh`）の詳細については、[コマンドのドキュメント](../features/commands) を参照してください。

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

## サンドボックス

Qwen Code は、シェルコマンドの実行やファイルの変更など、潜在的に危険な操作をサンドボックス化された環境内で実行することで、システムを保護します。

[サンドボックス](../features/sandbox) はデフォルトで無効になっていますが、以下のいずれかの方法で有効化できます：

- `--sandbox` または `-s` フラグを使用する。
- `QWEN_SANDBOX` 環境変数を設定する。
- `--yolo` または `--approval-mode=yolo` を使用した場合、デフォルトでサンドボックスが有効になります。

デフォルトでは、事前にビルド済みの `qwen-code-sandbox` Docker イメージが使用されます。

プロジェクト固有のサンドボックス要件がある場合は、プロジェクトのルートディレクトリに `.qwen/sandbox.Dockerfile` を作成し、カスタム Dockerfile を定義できます。この Dockerfile は、ベースとなるサンドボックスイメージを継承できます：

FROM qwen-code-sandbox

ここにカスタムの依存関係や設定を追加してください

例：

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
  }
}