Claude Code settings

概要

settings.json による Claude Code の設定。スコープ（managed / user / project / local）、設定キーの一覧、優先順位を扱う。対話セッションでは /config で設定 UI を開く。v2.1.181 から /config key=value で UI を開かずに 1 項目を変更できる。

仕様

スコープ

• Windows では ~/.claude は %USERPROFILE%\.claude に解決される

settings ファイル

• .claude/settings.local.json に設定を保存するとき、リポジトリがまだ無視していなければ **/.claude/settings.local.json をグローバル git excludes ファイルに追加する。そのファイルは、絶対パスまたは ~/ 始まりで設定されていればグローバル git config の core.excludesFile、無ければ $XDG_CONFIG_HOME/git/ignore、無ければ ~/.config/git/ignore
• .claude/settings.local.json は git リポジトリルート（worktree はメイン checkout に解決）で読み書きされ、1 ファイルでリポジトリ内のどのサブディレクトリ・worktree のセッションもカバーする。起動ディレクトリに残るのは 3 つの場合: git リポジトリ外、リポジトリルートがホームディレクトリ、Agent SDK セッション
• 恒久的な「don't ask again」の permission 承認もこのファイルに保存される
• このファイルはリポジトリのものではなく自分のものなので、allow ルールは .claude/settings.json が要求する workspace trust のステップなしで有効になる。リポジトリが供給した場合（コミットされている等）は workspace trust が適用される

managed settings の配布方法:

• Server-managed settings: サインイン時にリモート配布（claude.ai admin console または self-hosted Claude apps gateway）

• MDM / OS レベルのポリシー

  • macOS: com.anthropic.claudecode managed preferences ドメイン。plist のトップレベルキーは managed-settings.json に対応し、ネストした設定は dictionary、配列は plist array
  • Windows: HKLM\SOFTWARE\Policies\ClaudeCode レジストリキーの Settings 値（REG_SZ または REG_EXPAND_SZ の JSON）
  • Windows（ユーザーレベル）: HKCU\SOFTWARE\Policies\ClaudeCode（ポリシー優先度は最低。admin レベルのソースが無いときのみ使われる）

• ファイルベース: システムディレクトリに配置する managed-settings.json と managed-mcp.json

  • macOS: /Library/Application Support/ClaudeCode/
  • Linux / WSL: /etc/claude-code/
  • Windows: C:\Program Files\ClaudeCode\
  • レガシーの C:\ProgramData\ClaudeCode\managed-settings.json は v2.1.75 以降サポートされない
  • 同じシステムディレクトリの managed-settings.d/ ドロップインディレクトリもサポートする。systemd の慣習に従い managed-settings.json をベースにマージし、その上にドロップインディレクトリの *.json をアルファベット順でマージする。スカラー値は後のファイルが優先、配列は連結・重複排除、オブジェクトは deep merge。. で始まる隠しファイルは無視される。マージ順は 10-telemetry.json のような数値接頭辞で制御する

• その他の設定は ~/.claude.json に保存される（OAuth セッション、user / local スコープの MCP サーバー設定、プロジェクトごとの状態、各種キャッシュ）

• Claude Code は設定ファイルのタイムスタンプ付きバックアップを自動作成し、最新 5 件を保持する

• $schema に https://json.schemastore.org/claude-code-settings.json を指定するとエディタの補完と検証が効く。公開スキーマは定期更新のため、最新リリースで追加された設定は含まれないことがある

反映のタイミング

• 設定ファイルは監視され、変更されると再読み込みされる。permissions、hooks、apiKeyHelper などのキーは再起動なしに反映される。user / project / local / managed のすべてが対象で、変更ごとに ConfigChange hook が発火する
• セッション開始時に一度だけ読まれ、次回起動から反映されるキー
  • model: セッション中は /model で切り替える
  • outputStyle: システムプロンプトの一部で、/clear か再起動で再構築される

managed settings の不正エントリ

• managed settings は寛容にパースされる。スキーマ検証に失敗したエントリを除去し、警告を記録し、残りの有効なポリシーをすべて強制する。/doctor で除去されたエントリを出所ファイル・フィールドとともに一覧できる。v2.1.169 以降が必要
• security-enforcement のフィールドは丸ごと除去されず、フィールドごとに扱われる

• requiredMinimumVersion と requiredMaximumVersion は設計上 fail open。不正な値は強制されず除去される
• 検証エラーは 3 箇所に出る: 対話セッションの起動時ダイアログ、-p の headless 実行の stderr サマリ、claude doctor
• この寛容さは managed settings のみ。user / project / local の settings ファイルは厳格で、検証に失敗したファイルは全体が拒否され報告される

主な設定キー（settings.json）

~/.claude.json の global config settings

これらは settings.json ではなく ~/.claude.json に保存される。settings.json に書くと起動時に黙って無視される。

worktree 設定

permission 設定（permissions）

sandbox 設定（sandbox）

sandbox のパス接頭辞:

• 古い //path の絶対パス接頭辞も動く。プロジェクト相対を意図して /path を使っていた場合は ./path に変える

attribution 設定

• 既定の commit attribution: Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>（モデル名はセッションのアクティブなモデルを反映する）
• 既定の pull request attribution: 🤖 Generated with [Claude Code](https://claude.com/claude-code)
• attribution は非推奨の includeCoAuthoredBy より優先される

file suggestion 設定

• fileSuggestion に type: "command" と command を設定する
• コマンドは hooks と同じ環境変数（CLAUDE_PROJECT_DIR を含む）で実行され、stdin で {"query": "src/comp"} の JSON を受け取る
• stdout に改行区切りのファイルパスを出力する（現在は 15 件まで）

footer link badges

• footerLinksRegexes の各エントリの pattern はターン出力（ツール結果、取得したページを含むファイル内容、Claude の応答）に対して照合される
• url と label の {name} プレースホルダは pattern の名前付き捕捉グループから埋められる

• ターン完了時にメインスレッドで正規表現を照合するため、遅い正規表現は UI をブロックする。(a+)+$ のようなネストした量指定子は避ける

hook 関連の設定

allowManagedHooksOnly が true のとき:

• managed hooks と SDK hooks は読み込まれる

• managed settings の enabledPlugins で強制有効化した plugin の hooks は読み込まれる。信頼は plugin@marketplace の完全な ID 単位で与えられる

• user hooks、project hooks、それ以外の plugin hooks はブロックされる

• allowedHttpHookUrls: HTTP hook が対象にできる URL を制限する。* をワイルドカードとしてサポート。ホスト名の照合は大小文字を区別せず、末尾の FQDN ドットを無視する

• httpHookAllowedEnvVars: HTTP hook がヘッダー値に補間できる環境変数名を制限する

policyHelper

• ヘルパーは JSON envelope を stdout に書く。設定はトップレベルではなく managedSettings キーの下に置く
• ヘルパーが managedSettings を出力すると、それがその実行で唯一の managed settings ソースになり、remote / MDM / ファイルベースより優先される
• 起動時にヘルパーが非ゼロで終了すると、Claude Code はエラーを出して起動を拒否する

優先順位

1. Managed settings（server-managed、MDM / OS レベルポリシー、managed settings ファイル）
2. コマンドライン引数（--settings <file-or-json> は他の層と同じルールでマージされる）
3. Local project settings（.claude/settings.local.json）
4. Shared project settings（.claude/settings.json）
5. User settings（~/.claude/settings.json）

managed を上書きできる例外:

• disableClaudeAiConnectors の true はどのスコープからでも適用される（managed が false でも）
• remoteControlAtStartup の false は project / local settings からでも適用される（managed が true でも）。逆に project / local の true は無視される
• isolatePeerMachines の true はどのスコープからでも適用される
• crossSessionInbound は、project / local の値が accept < hold < refuse のラダーでより厳しい場合に適用される
• CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST を設定する埋め込みホストは、model / fallbackModel / modelOverrides と managed env のモデル選択環境変数について managed ソースより優先される。managed の availableModels はホストが自前のものを供給しない限り有効なまま

managed 層内の優先順位（1 つのソースのみが使われ、他はマージされずに無視される。高い順）:

1. policyHelper の出力（設定されていればこれが唯一の managed ソース）
2. Remote（claude.ai server-managed または Claude apps gateway 配布）
3. MDM / OS レベルポリシー
4. ファイルベース（managed-settings.d/*.json と managed-settings.json をマージしたもの）
5. HKCU レジストリ（Windows のみ）

• ただし次のキーは、勝ったソースだけでなく admin 管理の任意の managed ソースが設定していれば尊重される（HKCU は除く。policyHelper があるときはその出力のみ）
  • sandbox のロックキー sandbox.network.allowManagedDomainsOnly と sandbox.filesystem.allowManagedReadPathsOnly、およびそれぞれの allowlist
  • allowAllClaudeAiMcps
  • sandbox のバイナリパス sandbox.bwrapPath と sandbox.socatPath
  • forceRemoteSettingsRefresh
  • env（admin 管理ソース間でキー単位にマージされる。各環境変数について最も優先度の高いソースが勝ち、低いソースが未設定分を埋める。v2.1.223 以降）

配列設定のマージ:

• 同じ配列値の設定が複数スコープに現れると、連結・重複排除される（置き換えではない）
• 例外 2 つ
  • fallbackModel は位置に意味がある順序付きチェーンなので、定義する最上位のファイルが値全体を供給する
  • availableModels は最上位の managed ソースが定義するとそのリストがそのまま適用され、user / project / local のエントリは拡張できない。managed でないスコープ間では通常どおりマージされる

有効な設定の確認

• /status の Status タブの Setting sources 行に、そのセッションで読み込まれた層が並ぶ。managed settings が効いている場合は配布チャネルが括弧付きで表示される（(remote) / (plist) / (HKLM) / (HKCU) / (file)）
• 少なくとも 1 つのキーを持って読み込まれたソースのみが一覧に現れるため、空の一覧は設定ソースが見つからなかったことを意味する
• Setting sources 行はどのソースが読まれているかを示すだけで、各キーをどの層が供給したかは示さない
• user / project / local の settings ファイルにエラー（不正な JSON、検証に失敗する値）があると、対話セッションは起動時に Settings Error ダイアログを出す。継続後は /status が該当ファイルを一覧し、claude doctor で詳細を見られる

plugin 設定

• enabledPlugins: "plugin-name@marketplace-name": true/false の形式。どのスコープにもエントリが無い plugin はその defaultEnabled にフォールバックする
  • project settings は user settings より優先されるため、~/.claude/settings.json で false にしても project の .claude/settings.json が有効にした plugin は無効にならない。自分のマシンで外すには .claude/settings.local.json で false にする
  • managed settings が強制有効化した plugin はこの方法で無効化できない
• pluginConfigs: plugin の userConfig プロンプトが集めた非機微なオプション値を plugin ID をキーに保存する。user settings / --settings / managed settings のみから読まれる（v2.1.207 より前は project / local も読まれた）。機微なオプションは macOS Keychain、または ~/.claude/.credentials.json に保存される
• extraKnownMarketplaces: リポジトリで利用可能にする追加の marketplace を定義する
• strictPluginOnlyCustomization でロックした面ごとの挙動

• 認識できない面の名前はエラーにせず無視される

設定

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf"
  },
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.acme.com"
  ]
}

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
      "deniedDomains": ["uploads.github.com"],
      "allowUnixSockets": ["/var/run/docker.sock"],
      "allowLocalBinding": true
    }
  }
}

{
  "enabledPlugins": {
    "formatter@acme-tools": true,
    "analyzer@security-plugins": false
  },
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    }
  }
}

{
  "footerLinksRegexes": [
    {
      "type": "regex",
      "pattern": "\\b(?<key>PROJ-\\d+)\\b",
      "url": "https://issues.example.com/browse/{key}",
      "label": "{key}"
    }
  ]
}

制約・注意点

• Claude Code の内部システムプロンプトは公開されていない。カスタム指示を加えるには CLAUDE.md か --append-system-prompt を使う
• 機微なファイルを除外するには permissions.deny を使う。これは非推奨の ignorePatterns を置き換える。パターンに一致するファイルはファイル検出と検索結果から除外され、読み取りも拒否される

関連

• facts/claude-code/permissions.md
• facts/claude-code/permission-modes.md
• facts/claude-code/sandboxing.md
• facts/claude-code/hooks.md
• facts/claude-code/mcp.md
• facts/claude-code/plugins.md
• facts/claude-code/model-config.md
• facts/claude-code/env-vars.md
• facts/claude-code/statusline.md
• facts/claude-code/skills.md
• facts/claude-code/sub-agents.md
• facts/claude-code/memory.md