Claude CodeГайд

Настройка Claude Code: полный гайд по settings.json

Где лежат файлы настроек Claude Code, какой из них главный и какие ключи стоит поменять. Все примеры проверены на версии 2.1.319 со скриншотами.

Настройка Claude Code: полный гайд по settings.json

Где в Claude Code поменять модель по умолчанию, запретить агенту читать .env и убрать подпись из коммитов? Вся настройка Claude Code живёт в файле settings.json. Там же задают хуки, переменные окружения и внешний вид. Файлов четыре уровня: личный ~/.claude/settings.json, общий для команды .claude/settings.json, личный для одного проекта .claude/settings.local.json и корпоративный managed-settings.json.

Я впервые писал этот гайд в феврале 2026 года. За девять месяцев Claude Code сменил модель по умолчанию на Opus 5.5, сделал auto mode стартовым режимом и перестал брать часть переменных из проектного файла. Поэтому 6 ноября я заново прогнал все примеры на версии 2.1.319 в чистом демо-проекте и снял каждый шаг.

В статье разберём:

  • где лежат файлы настроек и какой из них главный;
  • как открыть и поменять настройки;
  • стартовый settings.json для проекта;
  • какие ключи стоит знать: модель, разрешения, sandbox, хуки, подпись, интерфейс;
  • переменные окружения в блоке env;
  • как настроить Claude Code, если ты не разработчик;
  • как проверить настройки и какие ошибки встречаются.

Где лежат настройки Claude Code и какой файл главный

Claude Code читает настройки из четырёх мест, и у каждого свой круг людей, на которых оно действует. Сама установка ни одного файла не создаёт: они появляются, когда ты меняешь что-то в /config или впервые жмёшь «больше не спрашивать» в запросе разрешения.

Уровень Файл На кого действует Что туда класть
User ~/.claude/settings.json Ты, во всех проектах Тема, модель по умолчанию, личные правила
Shared project .claude/settings.json Все, кто работает в проекте (файл коммитят) Права для команды, хуки, плагины, переменные проекта
Project local .claude/settings.local.json Ты, только в этом проекте Личные исключения, проба перед тем, как делиться
Managed managed-settings.json, MDM или консоль claude.ai Вся организация Политики безопасности

Если один ключ задан в нескольких местах, побеждает верхний уровень. Порядок такой: managed, затем флаг --settings при запуске, затем local, shared project и в самом низу user. Так это описано в документации Anthropic по файлам настроек на ноябрь 2026 года.

Схема приоритета настроек Claude Code: managed сверху, затем командная строка, project local, shared project и user
Пять уровней настроек: верхний перекрывает тот же ключ во всех нижних. Скриншот: документация Anthropic

Списки работают иначе, чем одиночные ключи. Правила permissions.allow из всех файлов складываются: командный файл разрешает тесты, твой локальный добавляет git add, и действуют оба правила. Исключения есть только у ключей со списками моделей вроде fallbackModel, там берётся целый список с верхнего уровня.

Есть и пятый файл, ~/.claude.json. Его Claude Code ведёт сам: учётная запись, MCP-серверы, решения о доверии к папкам. Руками его править не нужно.

Командный файл действует не сразу. Когда коллега впервые открывает проект, Claude Code показывает, какие разрешения файл выдаёт заранее, и ждёт подтверждения. До этого правила allow и большая часть env не работают, а запреты deny применяются сразу.

Диалог доверия к папке в Claude Code с предупреждением о двух заранее одобренных командах из .claude/settings.json
При первом запуске в проекте Claude Code перечисляет, что командный settings.json разрешает без вопросов. Скриншот: терминал / matveev.tech

Как открыть и поменять настройки

Способов три: меню /config, правка файла и флаг на одну сессию. Я в основном правлю файл, а меню открываю, когда лень вспоминать имя ключа.

Меню /config. Внутри Claude Code набери /config и открой вкладку Config. Там короткий список личных опций: тема, подсказки, анимация, время хода, режим разрешений по умолчанию. Большинство из них Claude Code сохраняет в ~/.claude/settings.json, а «Show tips» почему-то пишет в локальный файл проекта. Одну опцию можно поменять и без меню: /config verbose=true.

Вкладка Config в /config Claude Code со списком опций: Show tips, Reduce motion, Show turn duration и режим разрешений
В /config видна лишь часть настроек: всего в справочнике больше 230 ключей. Скриншот: терминал / matveev.tech

Правка файла. Для всего, чего нет в меню, открываешь нужный settings.json в редакторе. Первой строкой добавь $schema: VS Code и Cursor начнут подсказывать ключи и подсвечивать ошибки. Схема иногда отстаёт от свежих версий CLI, поэтому предупреждение на новом ключе ещё не значит, что ключ неверный.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json"
}

Флаг на одну сессию. Попробовать значение, не трогая файлы, можно так:

claude --settings '{"model": "claude-sonnet-5-5"}'

Значение действует до конца сессии и перебивает все файлы, кроме корпоративного. Ещё один полезный флаг --setting-sources: с ним Claude Code читает только перечисленные уровни. Все кадры для этой статьи я снимал с --setting-sources project,local, чтобы в них не попали мои личные настройки.

Большинство правок Claude Code подхватывает на лету, в том числе permissions и hooks. Модель и уровень effort он читает только при старте, их в работающей сессии меняют командами /model и /effort.

Стартовый settings.json для проекта

С этого файла я начинаю каждый новый проект. Он разрешает линтер и тесты без вопросов, закрывает файлы с секретами, переводит ответы на русский и убирает подсказки под спиннером.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "language": "russian",
  "spinnerTipsEnabled": false
}

Ключ language принимает любое название языка: Claude Code передаёт его модели как есть и не проверяет. Тот же язык он берёт для голосового ввода и для автоматических названий сессий.

Я проверил файл в демо-проекте в ручном режиме разрешений. npm run test прошёл без запроса, ответ пришёл на русском, а Claude ещё и заметил, что тестов в проекте нет и скрипт просто печатает строку.

Claude Code запускает npm run test без запроса разрешения и отвечает на русском
Правило allow сработало: тесты запустились без вопроса, ответ на русском из-за ключа language. Скриншот: терминал / matveev.tech

Потом я попросил показать .env. Claude Code отказал в чтении по правилу deny, а модель сама не стала обходить запрет через cat. Запреты действуют в любом режиме, даже в bypassPermissions.

Claude Code отказывается читать файл .env из-за правила deny в настройках
Правило deny закрыло .env, модель предложила посмотреть файл самому через ! cat .env. Скриншот: терминал / matveev.tech

Какие ключи settings.json стоит знать

В справочнике All settings на 6 ноября 2026 года больше 230 ключей, и половина из них нужна только администраторам. Ниже то, что я реально меняю.

Модель и effort

С версии 2.1.280 модель по умолчанию на всех тарифах (Pro, Max, Ultra, Team, Enterprise и API) это Opus 5.5, сказано в разделе о настройке модели. Раньше Pro и Team Standard стартовали на Sonnet 5. Про саму модель подробно в обзоре Claude Opus 5.5.

Стартовый экран Claude Code 2.1.319: модель Opus 5.5 и уведомление, что auto mode теперь режим по умолчанию
Без ключа model сессия стартует на Opus 5.5 и сразу в auto mode. Скриншот: терминал / matveev.tech
{
  "model": "sonnet",
  "effortLevel": "high"
}

В model пиши псевдоним (opus, sonnet, haiku, fable, opusplan) или полный ID вроде claude-opus-5-5. Псевдоним сам переедет на новую версию, полный ID закрепит текущую. Переменная ANTHROPIC_MODEL в shell перебивает этот ключ из любого файла, а флаг --model перебивает обоих.

С effort есть тонкость. Команда /effort с версии 2.1.251 сохраняет уровень для конкретной модели в блоке modelSettings, а не в effortLevel. Opus 5.5 и более новые модели старый ключ effortLevel из личного файла игнорируют. Как выбирать уровень, я разбирал в статье про модель и effort level в Claude Code.

Ключ alwaysThinkingEnabled в старой версии гайда включал размышления. Сейчас они включены по умолчанию, а на Opus 5.5, Sonnet 5.5 и Haiku 5.5 их вообще нельзя выключить, так что ключ можно удалить.

Разрешения и режим auto

Режим разрешений задаёт ключ permissions.defaultMode. С версии 2.1.283 интерактивные сессии в терминале и VS Code по умолчанию стартуют в auto mode: фоновый классификатор проверяет каждое действие и сам пропускает безопасные.

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

Значения: default (он же manual), acceptEdits, plan, auto, dontAsk и bypassPermissions. Ловушка тут такая: auto и bypassPermissions из проектного и локального файла не применяются. Это защита от чужого репозитория, который включил бы себе полную свободу. Хочешь auto по умолчанию, пиши его в ~/.claude/settings.json. Мне это ограничение нравится: я часто открываю чужие репозитории и не хочу, чтобы они сами себе выдавали свободу.

Когда ты отвечаешь на запрос «Yes, and don't ask again», Claude Code записывает правило в .claude/settings.local.json. Я проверил это на git add.

Запрос разрешения на git add в Claude Code с вариантом «Yes, and don't ask again for: git add *»
Второй вариант ответа сохранит правило для всех команд git add в этом проекте. Скриншот: терминал / matveev.tech

После ответа в проекте появился локальный файл с правилом Bash(git add *). В git status его нет: Claude Code сам добавляет **/.claude/settings.local.json в глобальный список исключений git, если файл ещё не игнорируется.

Содержимое .claude/settings.local.json с правилом Bash(git add *) и вывод git status без этого файла
Правило попало в локальный файл, git его не видит, в коммит он не уйдёт. Скриншот: терминал / matveev.tech
Разрешения в Claude Code: allow, deny, sandbox
Синтаксис правил, режимы разрешений и настройка песочницы подробно и с примерами.

Sandbox

Песочница изолирует bash-команды на уровне ОС. Включается ключом sandbox.enabled или из панели /sandbox, которая пишет его в локальный файл проекта.

{
  "sandbox": {
    "enabled": true,
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

autoAllowBashIfSandboxed теперь по умолчанию true: команды внутри песочницы идут без запроса, а deny и узкие правила ask вроде Bash(git push *) продолжают работать. На Linux и WSL2 для песочницы нужны bubblewrap и socat. Если она не стартует, Claude Code молча запустит команды без изоляции. Чтобы вместо этого он завершался с ошибкой, добавь "failIfUnavailable": true.

Хуки

Хуки выполняют твои команды до или после действий Claude. Самый частый пример: отформатировать файл после правки.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs ruff format 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

В феврале я показывал здесь переменную $CLAUDE_FILE_PATH. В справочнике хуков её нет: данные о вызове приходят в хук JSON-объектом на stdin, путь к файлу лежит в tool_input.file_path. Остальные события и типы хуков разобраны в гайде по хукам Claude Code.

Подпись в коммитах

По умолчанию Claude Code дописывает в коммит трейлер Co-Authored-By, а в описание PR строку и ссылку на сессию. С версии 2.1.281 всё это убирает одна строка:

{
  "attribution": false
}

Если файл читают и более старые версии, пиши подробно: "attribution": {"commit": "", "pr": "", "sessionUrl": false}. Старые версии значение false не понимают и пропускают весь файл. Ключ includeCoAuthoredBy устарел ещё в 2.0.62, хотя продолжает работать, у меня он до сих пор лежит в личном файле.

Интерфейс и обновления

{
  "showTurnDuration": true,
  "spinnerTipsEnabled": false,
  "prefersReducedMotion": true,
  "autoUpdatesChannel": "stable"
}

showTurnDuration после каждого ответа пишет, сколько длился ход, и по умолчанию включён. prefersReducedMotion убирает анимацию спиннера и мерцание. autoUpdatesChannel: "stable" ставит версию примерно недельной давности без крупных регрессий, без ключа Claude Code идёт по latest. Если ставил через Homebrew, ключ не работает: канал там задаёт сам пакет (claude-code идёт по stable, claude-code@latest по latest).

Новые ключи settings.json появляются почти в каждом релизе Claude Code, самые полезные я разбираю в канале: подписывайся в телеге.

Как задать переменные окружения в блоке env

Блок env заменяет export в терминале. Переменные из проектного файла получат все, кто открыл проект.

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "300000",
    "DISABLE_AUTOUPDATER": "1"
  }
}

BASH_DEFAULT_TIMEOUT_MS поднимает таймаут bash-команды с 2 минут по умолчанию до 5, это удобно для долгих тестов. Полный список с описанием собран в справочнике переменных окружения Claude Code, а через тот же блок env подключают сторонние модели вместо Claude.

Часть переменных проектный и локальный файлы задать не могут: те, что включают телеметрию (с версии 2.1.282), меняют папки Claude Code или вход в аккаунт. В старой версии статьи у меня в примере стояла CLAUDE_CODE_ENABLE_TELEMETRY, и я проверил, что с ней стало. Claude Code её пропустил и объяснил это в /status.

Блок System diagnostics в /status Claude Code: переменная CLAUDE_CODE_ENABLE_TELEMETRY из .claude/settings.json проигнорирована
Телеметрию из проектного файла можно только выключить, включают её в личном файле или в shell. Скриншот: терминал / matveev.tech

Под этот запрет попадают CLAUDE_CONFIG_DIR, HOME, TMPDIR, переменные OpenTelemetry, токены входа в claude.ai и ещё несколько групп. Список есть в справочнике. Их задают в shell или в ~/.claude/settings.json.

Как настроить Claude Code, если ты не разработчик

Если ты пользуешься Claude Code для текстов, таблиц или разбора документов, JSON можно почти не трогать. Хватит трёх шагов.

Язык и внешний вид через /config. Тема, режим редактора, подсказки, длительность хода меняются в меню. Язык ответов в меню не вынесен, поэтому один раз скажи Claude: «Добавь в мой ~/.claude/settings.json ключ language со значением russian». Он сам поправит файл.

Правила работы в CLAUDE.md. Как оформлять ответы, какие папки главные, о чём спрашивать перед действием, пишут обычным текстом в файл CLAUDE.md. Claude читает этот файл как инструкцию, поэтому писать можно своими словами, без синтаксиса JSON. Подробно в статье CLAUDE.md: как писать инструкции для Claude Code.

Что агенту трогать нельзя, через deny. Если в папке лежат договоры или личные документы, закрой их правилом: "deny": ["Read(./Личное/**)", "Edit(./Договоры/**)"]. Модель может забыть инструкцию из CLAUDE.md, а запрет из deny Claude Code проверяет сам до того, как выполнить действие.

CLAUDE.md: как написать инструкции для Claude Code
Что писать в CLAUDE.md, где он лежит и чем инструкции отличаются от настроек.

Как проверить настройки и какие ошибки встречаются

Первая команда после любой правки это /status. Строка Setting sources показывает, какие файлы Claude Code загрузил в этой сессии.

Вкладка Status в Claude Code: модель Opus 5.5 по умолчанию и строка Setting sources с двумя загруженными файлами
Setting sources перечисляет загруженные файлы, но не говорит, из какого пришёл конкретный ключ. Скриншот: терминал / matveev.tech

Вторая проверка нужна, когда настройка «не работает». Вот ошибки, на которые я натыкался сам или видел у коллег.

Висячая запятая или комментарий в JSON. Файл строгий: // или запятая после последнего элемента ломают его целиком. Claude Code при старте показывает Settings Error и предлагает починить файл, выйти или продолжить без него. Пропускается именно весь файл: из него не применится ни один ключ, даже правильный.

Окно Settings Error в Claude Code: .claude/settings.json пропущен из-за неверного JSON
Одна лишняя запятая после правила в allow, и Claude Code пропускает весь файл. Скриншот: терминал / matveev.tech

Ошибку не видно в claude -p. В неинтерактивном режиме диалога нет, сломанный файл пропускается молча. После такого прогона запусти claude doctor: в блоке Invalid settings он назовёт файл и причину.

Вывод claude doctor с блоком Invalid settings и путём к сломанному settings.json
claude doctor заодно показывает версию, канал обновлений и управляемые настройки. Скриншот: терминал / matveev.tech

auto в командном файле. Ключ молча игнорируется, сессия стартует в обычном режиме. Перенеси его в ~/.claude/settings.json.

Ключ из проекта не доходит до коллег. Правила allow, additionalDirectories и большая часть env ждут, пока коллега подтвердит доверие к папке. Есть и ключи, которые из проектного файла не читаются вообще: в справочнике у них в колонке Scope стоит User, User or managed или Managed.

Модель «сбрасывается». Обычно виновата забытая ANTHROPIC_MODEL в ~/.zshrc или ключ model в проектном файле: оба выше по приоритету, чем твой выбор в /model.

Правишь не тот файл. Если в команде договорились о правилах, а тебе нужно исключение, клади его в .claude/settings.local.json. Правка общего файла поменяет поведение для всех после следующего коммита.

Чек-лист после правки settings.json

Сохрани этот список и пробегай по нему каждый раз, когда меняешь настройки.

  • Первой строкой стоит $schema, и редактор подсвечивает неизвестные ключи.
  • В файле нет // и запятой после последнего элемента.
  • auto и bypassPermissions записаны в ~/.claude/settings.json, а не в проектный файл.
  • Телеметрия, CLAUDE_CONFIG_DIR и другие запрещённые для проекта переменные заданы в shell или в личном файле.
  • Файлы с секретами закрыты правилом deny, а не просьбой в CLAUDE.md.
  • Личные исключения лежат в .claude/settings.local.json, общий файл команды не тронут.
  • В ~/.zshrc нет забытой ANTHROPIC_MODEL, которая перебивает /model.
  • Строка Setting sources в /status перечисляет нужные файлы.
  • После прогона через claude -p запущен claude doctor.

Больше гайдов по агенту собрано в разделе о Claude Code.

Читайте также

CTO говорит

Разбираю релизы моделей и инструментов: что вышло и стоит ли переходить.

Читать в Telegram

Ещё в разделе Claude Code

Весь раздел