構成ファイルと適用順序

Qoder CLI の動作は、JSON 形式の構成ファイル（settings.json）を使用してカスタマイズできます。構成は階層設計を採用しており、同じ構成項目を異なるレベルで個別に設定でき、最終的に固定の優先順位に従ってマージされ、有効な値となります。この階層化とマージのルールを理解することは、個人の設定やチームの規約を管理する上で不可欠です。本ページでは、構成ファイルの場所、マージの優先順位、およびよく使用される構成項目について説明します。構成項目と環境変数の完全なリストについては、構成項目リファレンスを参照してください。

構成ファイルの場所

Qoder CLI は 3 つのレベルの構成ファイルを読み取ります。

レベル	パス	説明
ユーザーレベル	`~/.qoder/settings.json`	個人の環境設定。現在のユーザーのすべてのプロジェクトに適用されます。
プロジェクトレベル	`<プロジェクト>/.qoder/settings.json`	プロジェクト共有の構成。リポジトリにコミットされ、チームメンバー間で共有されます。
ローカルレベル	`<プロジェクト>/.qoder/settings.local.json`	プロジェクト内の個人用オーバーライド構成。通常、リポジトリにはコミットされません。

構成ディレクトリのデフォルトは ~/.qoder ですが、環境変数 QODER_CONFIG_DIR で変更できます。.qoder/ ディレクトリの完全な構造については、.qoder ディレクトリを参照してください。

マージの優先順位

同じ構成項目が複数のレベルに存在する場合、Qoder CLI は以下の優先順位に従って低いものから高いものへとマージします。高い優先順位が低い優先順位を上書きします。

組み込みのデフォルト値（スキーマのデフォルト）
ユーザーレベルの設定（~/.qoder/settings.json）
プロジェクトレベルの設定（<プロジェクト>/.qoder/settings.json）
ローカルレベルの設定（<プロジェクト>/.qoder/settings.local.json）
コマンドライン --settings で指定された構成（最高優先順位）

つまり、ローカルレベルはプロジェクトレベルを上書きし、プロジェクトレベルはユーザーレベルを上書きします。コマンドラインで明示的に渡された構成は、すべてのファイルよりも優先されます。

マージの方式

構成は全体を置き換えるのではなく、ディープマージ（deep merge）を採用しています。

オブジェクト：フィールドごとに再帰的にマージされ、存在するフィールドのみが上書きされ、残りは低い優先順位の値が保持されます。
単一値（文字列、数値、ブール値）：高い優先順位の値が直接上書きされます。
配列：一部の構成項目（無効化リストや除外リストなど）は「和集合マージ」を採用し、各レベルの値をマージして重複を排除します。その他の配列はデフォルトで上書きとして処理されます。

したがって、プロジェクトレベルでは上書きしたいフィールドのみを記述すればよく、ユーザー構成全体をコピーする必要はありません。

フォルダー信頼の影響

セキュリティ上の理由から、プロジェクトレベルとローカルレベルの構成は、現在の作業ディレクトリが信頼されている場合にのみ適用されます。作業ディレクトリが信頼されていない場合、Qoder CLI はユーザーレベルの構成のみを読み込み、プロジェクト内の settings.json と settings.local.json を無視します。フォルダー信頼は security.folderTrust.enabled（デフォルトで有効）によって制御されます。

ファイル形式

構成ファイルは JSON 形式（// コメントをサポート、下文参照）で、最上位はオブジェクトとなります。構成項目のほとんどはグループごとにネストされていますが、一部の構成項目は最上位に直接配置されます（outputStyle、language、agent など）。例：

{
  "outputStyle": "concise",
  "ui": {
    "theme": "Tokyo Night",
    "autoThemeSwitching": true
  },
  "model": {
    "name": "auto",
    "maxSessionTurns": -1
  },
  "tools": {
    "useRipgrep": true
  }
}

説明：

構成ファイルにはコメントを含めることができます（解析時に無視されます）。チームの規約に関する説明を記述する際に便利です。
値の中で環境変数を参照でき、実行時に解決されて置き換えられます。
一部の構成項目の変更は、Qoder CLI を再起動しないと有効になりません（以下の注釈を参照）。

よく使用される構成項目

以下に、最も頻繁に調整される構成項目をグループ別にリストアップします。「要再起動」と記載されている項目は、変更後に再起動しないと有効になりません。

最上位の構成項目

以下の構成項目は構成ファイルの最上位に直接記述され、どのグループにも属しません。

構成項目	型	デフォルト値	説明
`outputStyle`	string	なし	有効化する出力スタイルの名前（要再起動）。`general.outputStyle` の記述と互換性があり、最上位が優先されます。出力スタイルを参照してください。
`language`	string	なし	AI の応答に使用する優先言語（要再起動）。
`agent`	string	なし	メインスレッドで使用するエージェントの名前（要再起動）。

ui（インターフェース）

構成項目	型	デフォルト値	説明
`ui.theme`	string	なし	カラーテーマの名前。
`ui.autoThemeSwitching`	boolean	`true`	ターミナルの背景色に応じてライト/ダークテーマを自動切り替え。
`ui.customThemes`	object	`{}`	カスタムテーマの定義。
`ui.hideBanner`	boolean	`false`	起動バナーを非表示にする。
`ui.showLineNumbers`	boolean	`true`	会話内で行番号を表示する。
`ui.loadingPhrases`	enum	`off`	読み込み時の表示内容：`tips` / `witty` / `all` / `off`。
`ui.accessibility.screenReader`	boolean	`false`	スクリーンリーダーモード。プレーンテキストを出力する（要再起動）。

その他の UI とショートカットの構成については、UIとショートカットを参照してください。

model（モデル）

構成項目	型	デフォルト値	説明
`model.name`	string	なし	会話に使用するモデル。
`model.reasoningEffort`	enum	なし	推論エフォートレベル：`low` / `medium` / `high` など。
`model.maxSessionTurns`	number	`-1`	セッションに保持する最大ターン数。`-1` で無制限。

tools（ツール）

構成項目	型	デフォルト値	説明
`tools.sandbox`	string/boolean/object	なし	サンドボックス実行環境（要再起動）。
`tools.sandboxAllowedPaths`	string[]	`[]`	サンドボックスが追加でアクセスできるパス（要再起動）。
`tools.sandboxNetworkAccess`	boolean	`false`	サンドボックスのネットワークアクセスを許可するかどうか（要再起動）。
`tools.useRipgrep`	boolean	`true`	コンテンツ検索に ripgrep を使用する。
`tools.shell.inactivityTimeout`	number	`300`	シェルコマンドの出力がない場合のタイムアウト秒数。
`tools.core`	string[]	なし	組み込みツールの許可リスト。リストされたツールのみを許可する（要再起動）。
`tools.exclude`	string[]	なし	検出から除外するツール名（要再起動）。

security（セキュリティ）

構成項目	型	デフォルト値	説明
`security.folderTrust.enabled`	boolean	`true`	フォルダー信頼を有効にするかどうか（要再起動）。
`security.toolSandboxing`	boolean	`false`	ツールレベルのサンドボックス分離（要再起動）。
`security.disableYoloMode`	boolean	`false`	`bypass_permissions`（YOLO）権限モードを無効化する（要再起動）。
`security.blockGitExtensions`	boolean	`false`	Git からの拡張機能のインストールと読み込みをブロックする（要再起動）。
`security.environmentVariableRedaction.enabled`	boolean	`false`	鍵を含む可能性のある環境変数をマスキングする（要再起動）。

mcp（MCP サーバー）

構成項目	型	デフォルト値	説明
`mcpServers`	object	`{}`	MCP サーバーの構成（要再起動）。MCP を参照してください。
`mcp.allowed`	string[]	なし	許可する MCP サーバーのリスト（要再起動）。
`mcp.excluded`	string[]	なし	除外する MCP サーバーのリスト（要再起動）。

statusLine（ステータスバー）

構成項目	型	デフォルト値	説明
`statusLine.type`	string	`command`	ステータスバーのタイプ。現在は `command` のみサポート。
`statusLine.command`	string	`""`	ステータスバーを生成するシェルコマンド。stdin を介してセッションデータの JSON を受け取る。
`statusLine.padding`	number	`0`	ステータスバーの水平方向の埋め文字数。

構成の編集

構成を変更するには 2 つの方法があります。

インタラクティブインターフェースで：/settings を実行して設定パネルを開き、よく使用される構成項目を直接確認および調整します。
ファイルを手動で編集する：エディターで対応するレベルの settings.json を開き、上記の表に従ってフィールドを追加または変更します。

変更後、「要再起動」と記載されていない項目は通常すぐに有効になりますが、「要再起動」と記載されている項目は Qoder CLI の再起動が必要です。

次のステップ

すべての構成項目と環境変数を確認する：構成項目リファレンス。
/model ウィザードからカスタムモデルを追加する：カスタムモデル。
UI とショートカットをカスタマイズする：UIとショートカット。
構成の問題をトラブルシューティングする：構成のトラブルシューティング。

​構成ファイルの場所

​マージの優先順位

​マージの方式

​フォルダー信頼の影響

​ファイル形式

​よく使用される構成項目

​最上位の構成項目

​ui（インターフェース）

​model（モデル）

​tools（ツール）

​security（セキュリティ）

​mcp（MCP サーバー）

​statusLine（ステータスバー）

​構成の編集

​次のステップ