Настройки и иерархия конфигурации

Каждый раз, запуская Claude Code, вы работаете в рамках четырёхуровневой системы настроек — даже если никогда явно не трогали ни один settings.json. Разобраться в этой иерархии важно по двум причинам: она определяет, что можно, а что нельзя делать агенту, и она решает, какие настройки распространяются на всю команду, а какие остаются сугубо личными.

Четыре уровня и их расположение

Читайте таблицу снизу вверх: каждый следующий уровень перекрывает предыдущий.

Уровень	Файл	Область действия	В git?
Managed (enterprise)	`/etc/claude-code/managed-settings.json` (Linux)	Все пользователи машины	Нет — деплоится IT
Local	`.claude/settings.local.json`	Только вы в этом репо	Нет (gitignore)
Project	`.claude/settings.json`	Вся команда в репо	Да
User	`~/.claude/settings.json`	Вы во всех проектах	Нет

CLI-флаги (--model, --allowedTools и т. д.) перекрывают всё, кроме managed-настроек, — и действуют только в рамках одного запуска.

Полный порядок приоритета, от наименьшего к наибольшему:

User → Project → Local → CLI-флаги → Managed

Практически это значит: если в managed-settings.json выставлен запрет Bash(curl *), никакой settings.local.json его не отменит. А настройки в .claude/settings.json автоматически применяются ко всем, кто клонирует репозиторий.

flowchart TD M["🏢 Managed settings\n/etc/claude-code/managed-settings.json\n(задаётся IT, нельзя переопределить)"] --> U U["👤 User settings\n~/.claude/settings.json\n(личные, все проекты)"] --> P P["📁 Project settings\n.claude/settings.json\n(команда, в git)"] --> L L["💻 Local settings\n.claude/settings.local.json\n(только вы, gitignored)"] --> C C["⚡ CLI-флаги\n--model, --allowedTools\n(текущий запуск)"] style M fill:#ff6b6b,color:#fff style U fill:#ffa94d,color:#fff style P fill:#51cf66,color:#fff style L fill:#339af0,color:#fff style C fill:#cc5de8,color:#fff

flowchart TD
    M["🏢 Managed settings\n/etc/claude-code/managed-settings.json\n(задаётся IT, нельзя переопределить)"] --> U
    U["👤 User settings\n~/.claude/settings.json\n(личные, все проекты)"] --> P
    P["📁 Project settings\n.claude/settings.json\n(команда, в git)"] --> L
    L["💻 Local settings\n.claude/settings.local.json\n(только вы, gitignored)"] --> C
    C["⚡ CLI-флаги\n--model, --allowedTools\n(текущий запуск)"]

    style M fill:#ff6b6b,color:#fff
    style U fill:#ffa94d,color:#fff
    style P fill:#51cf66,color:#fff
    style L fill:#339af0,color:#fff
    style C fill:#cc5de8,color:#fff

Иерархия настроек Claude Code: каждый уровень перекрывает предыдущий; CLI-флаги в приоритете

Структура файла

Все четыре файла имеют одинаковую схему JSON. Минимальный рабочий пример:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
    "deny": ["Read(./.env)", "Read(./secrets/**)", "Bash(curl *)"]
  },
  "model": "claude-sonnet-4-6"
}
}

Схема доступна на JSON Schema Store — редакторы с поддержкой JSON Schema (VS Code и JetBrains) дадут автодополнение и валидацию прямо в файле.

Check yourself

Вы добавили `"model": "claude-opus-4-5"` в `.claude/settings.json` (project-уровень), а коллега имеет в своём `~/.claude/settings.json` (user-уровень) `"model": "claude-haiku-4-5"`. Какая модель будет использоваться у коллеги?

Система разрешений

Разрешения — самая критичная часть конфигурации. Claude Code спрашивает подтверждение перед каждым потенциально опасным действием (запись в файл, выполнение команды), и именно permissions определяет, что разрешено молча, что запрещено всегда, а о чём нужно спрашивать.

"permissions": {
  "allow": [
    "Bash(npm run lint)",
    "Bash(npm run test *)",
    "Bash(git *)",
    "Read(~/.zshrc)"
  ],
  "deny": [
    "Bash(curl *)",
    "Bash(rm -rf *)",
    "Read(./.env)",
    "Read(./.env.*)",
    "Read(./secrets/**)",
    "WebFetch(*)"
  ]
}

Формат правил. Каждое правило — это строка вида ИнструментName(glob-паттерн). Поддерживаемые инструменты: Bash, Read, Edit, Write, WebFetch, mcp__ИмяСервера__ИмяТула.

Глоб-символы работают стандартно:

* — любые символы, кроме /
** — любые символы включая / (рекурсия)
npm run * — разрешить любой скрипт через npm run

Порядок обработки. Deny всегда выигрывает у allow — это не зависит от порядка записей в файле. Если одно правило разрешает Bash(curl *), а другое запрещает Bash(curl *), запрос будет отклонён.

Объединение уровней. Разрешения из всех файлов конкатенируются, а не перезаписываются. Если в user-настройках стоит allow: ["Bash(git *)"], а в project — allow: ["Bash(npm run test)"], итоговый allow-список содержит оба правила. Deny-листы тоже объединяются — и если хоть один уровень запрещает действие, оно запрещено.

Check yourself

В project-settings стоит `allow: ["Bash(curl *)"]`. В managed-settings стоит `deny: ["Bash(curl *)"]`. Что произойдёт, когда Claude попытается выполнить `curl https://api.example.com`?

Что куда класть: практическое распределение

Самая распространённая ошибка — положить всё в один файл. Рабочая схема:

~/.claude/settings.json (user) — личные предпочтения, которые нужны во всех проектах:

{
  "editorMode": "vim",
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Read(~/.zshrc)",
      "Read(~/.gitconfig)"
    ]
  }
}

.claude/settings.json (project) — правила команды, коммитятся в репо:

{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(npm run build)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Read(./.env*)",
      "Read(./secrets/**)"
    ]
  },
  "attribution": {
    "commit": "🤖 Claude Code"
  }
}

.claude/settings.local.json (local) — личные перегрузки для этого репо, которые не нужны коллегам:

{
  "model": "claude-opus-4-5",
  "permissions": {
    "allow": ["Bash(./scripts/dev-reset.sh)"]
  }
}

Важно: .claude/settings.local.json должен попасть в .gitignore. Если его там нет, Claude Code предупредит об этом при первом создании файла.

Check yourself

Нужно добавить `DATABASE_URL` для разработки в Claude Code, но не хочется коммитить этот URL в репо. В какой файл и в какое поле его правильно поместить?

Переменные окружения

Часть настроек удобнее держать в переменных окружения, а не в JSON — особенно секреты и параметры CI/CD:

Переменная	Назначение
`ANTHROPIC_API_KEY`	Ключ API (обязателен без OAuth)
`ANTHROPIC_MODEL`	Модель по умолчанию
`CLAUDE_CODE_EFFORT_LEVEL`	Уровень усилий: `low`, `medium`, `high`, `xhigh`
`MAX_THINKING_TOKENS`	Бюджет extended thinking
`DISABLE_AUTOUPDATER`	Отключить автообновление (`1`)
`CLAUDE_CODE_DISABLE_AUTO_MEMORY`	Отключить авто-память (`1`)
`CLAUDE_CODE_ENABLE_TELEMETRY`	Телеметрия OpenTelemetry (`1`)
`CLAUDE_CODE_SKIP_PROMPT_HISTORY`	Не писать транскрипты (`1`)

Кроме того, в settings.json есть поле env, которое передаёт переменные в дочерние процессы и инструменты:

{
  "env": {
    "NODE_ENV": "development",
    "DATABASE_URL": "postgres://localhost:5432/mydb",
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  }
}

Это полезно, когда нужно гарантировать, что Claude запускает npm run test всегда с определёнными переменными — без необходимости экспортировать их вручную в каждом терминале.

Когда изменения вступают в силу

Не все настройки применяются мгновенно:

Горячая перезагрузка (без рестарта):

permissions — allow/deny правила обновляются сразу после сохранения файла
hooks — изменения подхватываются на лету
apiKeyHelper и credential helpers

Только после перезапуска:

model — выбранная модель фиксируется при старте
outputStyle — стиль вывода
editorMode — режим редактора

Если после правки model в settings.json Claude продолжает использовать старую — это нормально, просто нужно перезапустить сессию.

Enterprise: managed-settings и MDM

Для корпоративных развёртываний есть уровень managed-settings, который не может переопределить ни один пользователь:

/Library/Application Support/ClaudeCode/managed-settings.json  # macOS
/etc/claude-code/managed-settings.json                         # Linux
C:\Program Files\ClaudeCode\managed-settings.json              # Windows

IT-отдел также может распределять настройки через Jamf, Kandji (macOS) или групповые политики Windows (реестр HKLM\SOFTWARE\Policies\ClaudeCode). Типичное использование:

{
  "forceLoginOrgUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "allowManagedMcpServersOnly": true,
  "deniedMcpServers": [{"serverName": "filesystem"}],
  "availableModels": ["claude-sonnet-4-6", "claude-haiku-4-5"],
  "enforceAvailableModels": true,
  "companyAnnouncements": ["Используйте только внутренние MCP-серверы компании"]
}

Для проверки корректности конфигурации перед деплоем: claude doctor.

Мodular merge через managed-settings.d/ позволяет разным командам вносить отдельные политики без конфликтов — файлы обрабатываются в алфавитном порядке, массивы конкатенируются, объекты deep-merge.

Быстрый рецепт: первоначальная настройка нового проекта

# 1. Создать директорию
mkdir -p .claude

# 2. Добавить локальный файл в gitignore
echo '.claude/settings.local.json' >> .gitignore
echo '.claude/CLAUDE.local.md' >> .gitignore

# 3. Создать project-настройки
cat > .claude/settings.json << 'EOF'
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Read(./.env*)",
      "Read(./secrets/**)",
      "Bash(git push --force*)",
      "Bash(rm -rf *)"
    ]
  }
}
EOF

# 4. Закоммитить
git add .claude/settings.json
git commit -m "feat: add Claude Code project settings"

После этого каждый, кто клонирует репозиторий и запустит Claude Code, получит те же базовые разрешения. Личные перегрузки — в settings.local.json, глобальные предпочтения — в ~/.claude/settings.json.