Настройка разрешений

Контролируйте, что Claude Code может использовать и делать, с помощью детальных правил разрешений, режимов и управляемых политик.

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

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

Claude Code использует многоуровневую систему разрешений для баланса между мощностью и безопасностью:

Управление разрешениями

Вы можете просматривать и управлять разрешениями инструментов Claude Code с помощью /permissions. Этот интерфейс отображает все правила разрешений и файлы settings.json, из которых они берутся.

• Правила Allow позволяют Claude Code использовать указанный инструмент без ручного одобрения.
• Правила Ask запрашивают подтверждение каждый раз, когда Claude Code пытается использовать указанный инструмент.
• Правила Deny предотвращают использование Claude Code указанного инструмента.

Правила оцениваются по порядку: deny -> ask -> allow. Первое совпадающее правило побеждает, поэтому правила deny всегда имеют приоритет.

Режимы разрешений

Claude Code поддерживает несколько режимов разрешений, которые контролируют, как инструменты одобряются. См. Permission modes для определения того, когда использовать каждый из них. Установите defaultMode в ваших файлах параметров:

Чтобы предотвратить использование режима bypassPermissions или auto, установите permissions.disableBypassPermissionsMode или permissions.disableAutoMode на "disable" в любом файле параметров. Это наиболее полезно в управляемых параметрах, где они не могут быть переопределены.

Синтаксис правил разрешений

Правила разрешений следуют формату Tool или Tool(specifier).

Совпадение всех использований инструмента

Чтобы совпадать со всеми использованиями инструмента, используйте только имя инструмента без скобок:

Bash(*) эквивалентен Bash и совпадает со всеми Bash командами.

Используйте спецификаторы для детального контроля

Добавьте спецификатор в скобках, чтобы совпадать с конкретными использованиями инструмента:

Шаблоны подстановочных символов

Правила Bash поддерживают glob-шаблоны с *. Подстановочные символы могут появляться в любой позиции команды. Эта конфигурация позволяет npm и git commit команды, блокируя git push:

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Bash(git * main)",
      "Bash(* --version)",
      "Bash(* --help *)"
    ],
    "deny": [
      "Bash(git push *)"
    ]
  }
}

Пробел перед * имеет значение: Bash(ls *) совпадает с ls -la, но не с lsof, в то время как Bash(ls*) совпадает с обоими. Суффикс :* - это эквивалентный способ написания завершающего подстановочного символа, поэтому Bash(ls:*) совпадает с теми же командами, что и Bash(ls *).

Диалог разрешений записывает форму, разделенную пробелами, когда вы выбираете "Да, не спрашивать снова" для префикса команды. Форма :* распознается только в конце шаблона. В шаблоне, таком как Bash(git:* push), двоеточие рассматривается как буквальный символ и не будет совпадать с git командами.

Правила разрешений для конкретных инструментов

Bash

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

• Bash(npm run build) совпадает с точной Bash командой npm run build
• Bash(npm run test *) совпадает с Bash командами, начинающимися с npm run test
• Bash(npm *) совпадает с любой командой, начинающейся с npm
• Bash(* install) совпадает с любой командой, заканчивающейся на install
• Bash(git * main) совпадает с командами, такими как git checkout main и git log --oneline main

Один * совпадает с любой последовательностью символов, включая пробелы, поэтому один подстановочный символ может охватывать несколько аргументов. Bash(git *) совпадает с git log --oneline --all, и Bash(git * main) совпадает с git push origin main, а также с git merge main.

Когда * появляется в конце с пробелом перед ним (например Bash(ls *)), это обеспечивает границу слова, требуя, чтобы префиксу предшествовал пробел или конец строки. Например, Bash(ls *) совпадает с ls -la, но не с lsof. В отличие от этого, Bash(ls*) без пробела совпадает с обоими ls -la и lsof, потому что нет ограничения границы слова.

Составные команды

Когда вы одобряете составную команду с "Да, не спрашивать снова", Claude Code сохраняет отдельное правило для каждой подкоманды, требующей одобрения, а не одно правило для полной составной строки. Например, одобрение git status && npm test сохраняет правило для npm test, поэтому будущие вызовы npm test распознаются независимо от того, что предшествует &&. Подкоманды, такие как cd в подкаталог, генерируют свое собственное правило Read для этого пути. Для одной составной команды может быть сохранено до 5 правил.

Оборачиватели процессов

Перед сопоставлением правил Bash, Claude Code удаляет фиксированный набор оборачивателей процессов, поэтому правило, такое как Bash(npm test *), также совпадает с timeout 30 npm test. Распознаваемые оборачиватели - это timeout, time, nice, nohup и stdbuf.

Голый xargs также удаляется, поэтому Bash(grep *) совпадает с xargs grep pattern. Удаление применяется только когда xargs не имеет флагов: вызов, такой как xargs -n1 grep pattern, совпадает как команда xargs, поэтому правила, написанные для внутренней команды, не охватывают его.

Этот список оборачивателей встроен и не настраивается. Средства выполнения окружения разработки, такие как direnv exec, devbox run, mise exec, npx и docker exec, не входят в список. Потому что эти инструменты выполняют свои аргументы как команду, правило, такое как Bash(devbox run *), совпадает с чем угодно после run, включая devbox run rm -rf .. Чтобы одобрить работу внутри средства выполнения окружения, напишите конкретное правило, которое включает как средство выполнения, так и внутреннюю команду, такое как Bash(devbox run npm test). Добавьте одно правило для каждой внутренней команды, которую вы хотите разрешить.

Оборачиватели exec, такие как watch, setsid, ionice и flock, всегда запрашивают и не могут быть автоматически одобрены правилом префикса, таким как Bash(watch *). То же самое применяется к find с -exec или -delete: правило Bash(find *) не охватывает эти формы. Чтобы одобрить конкретный вызов, напишите правило точного совпадения для полной строки команды.

Команды только для чтения

Claude Code распознает встроенный набор Bash команд как только для чтения и запускает их без запроса разрешения в каждом режиме. Они включают ls, cat, head, tail, grep, find, wc, diff, stat, du, cd и формы git только для чтения. Набор не настраивается; чтобы требовать запрос для одной из этих команд, добавьте правило ask или deny для нее.

Неквотированные glob-шаблоны разрешены для команд, у которых каждый флаг только для чтения, поэтому ls *.ts и wc -l src/*.py запускаются без запроса. Команды с флагами, способными к записи или выполнению, такие как find, sort, sed и git, по-прежнему запрашивают, когда присутствует неквотированный glob, потому что glob может расширяться до флага, такого как -delete.

cd в путь внутри вашего рабочего каталога или дополнительного каталога также только для чтения. Составная команда, такая как cd packages/api && ls, запускается без запроса, когда каждая часть квалифицируется самостоятельно. Объединение cd с git в одну составную команду всегда запрашивает, независимо от целевого каталога.

PowerShell

Правила разрешений PowerShell используют ту же форму, что и правила Bash. Подстановочные символы с * совпадают в любой позиции, суффикс :* эквивалентен конечному *, и голый PowerShell или PowerShell(*) совпадает с каждой командой. Эта конфигурация позволяет команды Get-ChildItem и git commit, блокируя Remove-Item:

{
  "permissions": {
    "allow": [
      "PowerShell(Get-ChildItem *)",
      "PowerShell(git commit *)"
    ],
    "deny": [
      "PowerShell(Remove-Item *)"
    ]
  }
}

Общие псевдонимы канонизируются перед сопоставлением. Правило, написанное для имени cmdlet, также совпадает с его псевдонимами, поэтому PowerShell(Get-ChildItem *) совпадает с gci, ls и dir. Сопоставление не чувствительно к регистру.

Claude Code анализирует AST PowerShell и проверяет каждую команду в составной команде независимо. Операторы конвейера |, разделители операторов ; и на PowerShell 7+ операторы цепочки && и || разделяют составную команду на подкоманды. Правило должно совпадать с каждой подкомандой, чтобы составная команда была разрешена.

Read и Edit

Правила Edit применяются ко всем встроенным инструментам, которые редактируют файлы. Claude прилагает наилучшие усилия для применения правил Read ко всем встроенным инструментам, которые читают файлы, таким как Grep и Glob.

Правила Read и Edit следуют спецификации gitignore с четырьмя различными типами шаблонов:

На Windows пути нормализуются в форму POSIX перед сопоставлением. C:\Users\alice становится /c/Users/alice, поэтому используйте //c/**/.env для сопоставления файлов .env в любом месте на этом диске. Чтобы сопоставить все диски, используйте //**/.env.

Примеры:

• Edit(/docs/**): редактирование в <project>/docs/ (НЕ /docs/ и НЕ <project>/.claude/docs/)
• Read(~/.zshrc): чтение .zshrc вашего домашнего каталога
• Edit(//tmp/scratch.txt): редактирование абсолютного пути /tmp/scratch.txt
• Read(src/**): чтение из <current-directory>/src/

Правило совпадает только с файлами под его якорем, поэтому якорь определяет, насколько далеко распространяется правило deny. Голые имена файлов следуют семантике gitignore и совпадают на любой глубине, поэтому Read(.env) и Read(**/.env) эквивалентны:

Когда Claude получает доступ к символической ссылке, правила разрешений проверяют два пути: саму символическую ссылку и файл, на который она указывает. Правила allow и deny обрабатывают эту пару по-разному: правила allow возвращаются к запросу вас, в то время как правила deny блокируют полностью.

• Правила allow: применяются только когда совпадают как путь символической ссылки, так и его цель. Символическая ссылка внутри разрешенного каталога, которая указывает вне его, по-прежнему запрашивает вас.
• Правила deny: применяются когда совпадает либо путь символической ссылки, либо его цель. Символическая ссылка, которая указывает на запрещенный файл, сама запрещена.

Например, с Read(./project/**) разрешено и Read(~/.ssh/**) запрещено, символическая ссылка в ./project/key, указывающая на ~/.ssh/id_rsa, блокируется: цель не проходит правило allow и совпадает с правилом deny.

WebFetch

• WebFetch(domain:example.com) совпадает с запросами выборки на example.com

MCP

• mcp__puppeteer совпадает с любым инструментом, предоставленным сервером puppeteer (имя настроено в Claude Code)
• mcp__puppeteer__* синтаксис подстановочных символов, который также совпадает со всеми инструментами с сервера puppeteer
• mcp__puppeteer__puppeteer_navigate совпадает с инструментом puppeteer_navigate, предоставленным сервером puppeteer

Agent (subagents)

Используйте правила Agent(AgentName) для контроля, какие subagents может использовать Claude:

• Agent(Explore) совпадает с subagent Explore
• Agent(Plan) совпадает с subagent Plan
• Agent(my-custom-agent) совпадает с пользовательским subagent с именем my-custom-agent

Добавьте эти правила в массив deny в ваших параметрах или используйте флаг CLI --disallowedTools для отключения конкретных агентов. Чтобы отключить агент Explore:

{
  "permissions": {
    "deny": ["Agent(Explore)"]
  }
}

Расширение разрешений с помощью hooks

Claude Code hooks предоставляют способ регистрации пользовательских команд оболочки для выполнения оценки разрешений во время выполнения. Когда Claude Code выполняет вызов инструмента, PreToolUse hooks запускаются перед запросом разрешения. Выход hook может отклонить вызов инструмента, принудить запрос или пропустить запрос, чтобы позволить вызову продолжиться.

Решения hook не обходят правила разрешений. Правила deny и ask оцениваются независимо от того, что возвращает PreToolUse hook, поэтому совпадающее правило deny блокирует вызов и совпадающее правило ask по-прежнему запрашивает даже когда hook вернул "allow" или "ask". Это сохраняет приоритет deny-first, описанный в Управление разрешениями, включая правила deny, установленные в управляемых параметрах.

Блокирующий hook также имеет приоритет над правилами allow. Hook, который выходит с кодом 2, останавливает вызов инструмента перед оценкой правил разрешений, поэтому блокировка применяется даже когда правило allow иначе позволило бы вызову продолжиться. Чтобы запустить все Bash команды без запросов, кроме нескольких, которые вы хотите заблокировать, добавьте "Bash" в список allow и зарегистрируйте PreToolUse hook, который отклоняет эти конкретные команды. См. Block edits to protected files для скрипта hook, который вы можете адаптировать.

Рабочие каталоги

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

• При запуске: используйте аргумент CLI --add-dir <path>
• Во время сеанса: используйте команду /add-dir
• Постоянная конфигурация: добавьте в additionalDirectories в файлы параметров

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

Дополнительные каталоги предоставляют доступ к файлам, а не конфигурацию

Добавление каталога расширяет, где Claude может читать и редактировать файлы. Это не делает этот каталог полным корнем конфигурации: большинство конфигурации .claude/ не обнаруживается из дополнительных каталогов, хотя несколько типов загружаются как исключения.

Следующие типы конфигурации загружаются из каталогов --add-dir:

Все остальное, включая subagents, commands, output styles, hooks и другие параметры, обнаруживается только из текущего рабочего каталога и его родителей, вашего пользовательского каталога в ~/.claude/ и управляемых параметров. Чтобы поделиться этой конфигурацией между проектами, используйте один из этих подходов:

• Конфигурация на уровне пользователя: поместите файлы в ~/.claude/agents/, ~/.claude/output-styles/ или ~/.claude/settings.json, чтобы сделать их доступными в каждом проекте
• Плагины: упакуйте и распространяйте конфигурацию как плагин, который команды могут установить
• Запуск из каталога конфигурации: запустите Claude Code из каталога, содержащего конфигурацию .claude/, которую вы хотите использовать

Как разрешения взаимодействуют с sandboxing

Разрешения и sandboxing являются дополняющими уровнями безопасности:

• Разрешения контролируют, какие инструменты может использовать Claude Code и какие файлы или домены он может использовать. Они применяются ко всем инструментам (Bash, Read, Edit, WebFetch, MCP и другим).
• Sandboxing обеспечивает принудительное применение на уровне ОС, которое ограничивает доступ инструмента Bash к файловой системе и сети. Это применяется только к Bash командам и их дочерним процессам.

Используйте оба для защиты в глубину:

• Правила deny разрешений блокируют Claude от попытки доступа к ограниченным ресурсам
• Ограничения sandbox предотвращают Bash команды от доступа к ресурсам вне определенных границ, даже если инъекция подсказки обходит принятие решений Claude
• Ограничения файловой системы в sandbox объединяют параметры sandbox.filesystem с правилами deny для Read и Edit; оба объединяются в финальную границу sandbox
• Ограничения сети объединяют правила разрешений WebFetch со списками allowedDomains и deniedDomains sandbox

Когда sandboxing включен с autoAllowBashIfSandboxed: true, что является значением по умолчанию, sandboxed Bash команды запускаются без запроса даже если ваши разрешения включают ask: Bash(*). Граница sandbox заменяет запрос для каждой команды. Явные правила deny по-прежнему применяются, и команды rm или rmdir, которые нацелены на /, ваш домашний каталог или другие критические пути системы, по-прежнему вызывают запрос. См. sandbox modes для изменения этого поведения.

Управляемые параметры

Для организаций, которым требуется централизованный контроль над конфигурацией Claude Code, администраторы могут развернуть управляемые параметры, которые не могут быть переопределены параметрами пользователя или проекта. Эти параметры политики следуют тому же формату, что и обычные файлы параметров, и могут быть доставлены через политики MDM/уровня ОС, управляемые файлы параметров или параметры, управляемые сервером. См. файлы параметров для механизмов доставки и расположения файлов.

Параметры только для управления

Следующие параметры эффективны только в управляемых параметрах. Размещение их в файлах параметров пользователя или проекта не имеет эффекта.

disableBypassPermissionsMode обычно размещается в управляемых параметрах для обеспечения организационной политики, но работает из любой области. Пользователь может установить его в своих собственных параметрах, чтобы заблокировать себя из режима bypass.

Приоритет параметров

Правила разрешений следуют тому же приоритету параметров, что и все остальные параметры Claude Code:

1. Управляемые параметры: не могут быть переопределены никаким другим уровнем, включая аргументы командной строки
2. Аргументы командной строки: временные переопределения сеанса
3. Локальные параметры проекта (.claude/settings.local.json)
4. Общие параметры проекта (.claude/settings.json)
5. Параметры пользователя (~/.claude/settings.json)

Если инструмент запрещен на любом уровне, никакой другой уровень не может его разрешить. Например, управляемый параметр deny не может быть переопределен --allowedTools, и --disallowedTools может добавить ограничения сверх того, что определяют управляемые параметры.

Если разрешение разрешено в параметрах пользователя, но запрещено в параметрах проекта, параметр проекта имеет приоритет и разрешение блокируется.

Примеры конфигураций

Этот репозиторий включает начальные конфигурации параметров для распространенных сценариев развертывания. Используйте их как отправные точки и настройте их в соответствии с вашими потребностями.

См. также

• Settings: полный справочник конфигурации, включая таблицу параметров разрешений
• Configure auto mode: скажите классификатору режима auto, какую инфраструктуру ваша организация доверяет
• Sandboxing: изоляция файловой системы и сети на уровне ОС для Bash команд
• Authentication: настройка доступа пользователей к Claude Code
• Security: гарантии безопасности и лучшие практики
• Hooks: автоматизация рабочих процессов и расширение оценки разрешений