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

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

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

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

Claude Code использует многоуровневую систему разрешений для баланса между мощностью и безопасностью. В таблице показано, для каждого типа инструмента, запрашивает ли режим Manual одобрение перед выполнением действия. Другие режимы разрешений изменяют, какие из них вас спрашивают; в автоматическом режиме классификатор проверяет действия вместо вас, и как классификатор оценивает действия перечисляет, какие из них он видит.

Когда вы выбираете "Да, не спрашивать снова" и одобрение сохраняется постоянно, например для команды Bash или домена WebFetch, Claude Code сохраняет правило в .claude/settings.local.json в корне git репозитория, разрешённого через worktrees к основной копии. Правило применяется к будущим сеансам в любом месте этого репозитория, включая сеансы, запущенные в подкаталогах и в worktrees. Одобрение изменения файла не сохраняется в файл: как показано в таблице, оно действует до конца сеанса. В некоторых случаях, например вне git репозитория или на Windows, Claude Code не использует корень репозитория; Где Claude Code ищет каждый файл перечисляет эти случаи и где вместо этого сохраняется правило.

До версии 2.1.211 Claude Code всегда сохранял правило в начальном каталоге, поэтому одобрение, предоставленное в worktree или подкаталоге, не применялось к остальной части репозитория. Правила, которые более ранние версии сохранили в подкаталоге или worktree, по-прежнему применяются к сеансам, запущенным там.

Иногда запрос разрешения предлагает только одноразовое одобрение, без опции "не спрашивать снова" и без опции разрешить действие на остаток сеанса. Claude Code предлагает эти опции только когда запрос может показать вам всё, что они позволили бы, поэтому правило, которое вы сохраняете из запроса, охватывает только то, что названо его опцией. Когда запрос предлагает только одноразовое одобрение, одобрите действие один раз или добавьте правило самостоятельно в /permissions.

Добавьте комментарий при ответе на запрос разрешения

Вы можете прикрепить заметку к Claude при одобрении или отклонении одного действия. На большинстве запросов разрешений, включая Bash, PowerShell, файл и запросы инструментов MCP, перейдите на Yes или No и нажмите Tab для открытия поля комментария на этой опции. Запросы WebFetch и браузера не предлагают это поле. Опции, которые разрешают действие на остаток сеанса или сохраняют правило, также не принимают его.

С открытым полем введите комментарий и затем нажмите одну из этих клавиш:

• Enter: отправляет ваш ответ с прикреплённым комментарием. Если вы оставите поле пустым, Claude Code отправляет ответ без комментария.
• Tab: закрывает поле без ответа. Claude Code сохраняет введённый вами текст и всё ещё отправляет его, если вы ответите с этой опцией.
• Shift+Tab: на запросе файла, например запросе Edit или Write, закрывает поле так же, как Tab. До версии 2.1.235 нажатие Shift+Tab внутри поля вместо этого выбирало опцию, которая разрешает действие на остаток сеанса, поэтому Claude Code одобрял действие на остаток сеанса и отбрасывал комментарий.

Claude Code доставляет комментарий по-разному в зависимости от того, как вы ответили:

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

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

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

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

Правила оцениваются по порядку: deny, затем ask, затем allow. Первое совпадающее правило в этом порядке определяет результат, и специфичность правила не изменяет порядок.

Широкое правило deny, такое как Bash(aws *), блокирует каждый совпадающий вызов, включая вызовы, которые также совпадают с более узким правилом allow, таким как Bash(aws s3 ls). Правило allow не может создать исключение из правила deny. Тот же приоритет применяется между ask и allow: совпадающее правило ask выдает запрос даже когда более специфичное правило allow также совпадает с тем же вызовом.

Правила Deny ведут себя по-разному в зависимости от того, называют ли они инструмент или определяют область действия шаблона внутри него. Простое имя инструмента, такое как Bash, удаляет инструмент из контекста Claude полностью, поэтому Claude его никогда не видит. Если вы добавите такое правило во время сеанса, Claude не сможет вызвать инструмент со своего следующего вызова инструмента; Отказ от целого инструмента описывает, что происходит с определением, которое Claude уже видел. Правило с областью действия, такое как Bash(rm *), оставляет инструмент доступным и блокирует совпадающие вызовы, когда Claude пытается их выполнить.

Удаление по простому имени применяется ко всем инструментам, кроме EndConversation: правило deny не может удалить его, пока остается любой другой инструмент, и правило ask никогда не выдает запрос для него.

Когда автоматический режим доступен для вашего сеанса, интерфейс также включает правила классификатора автоматического режима. Выберите вкладку Auto mode, чтобы просмотреть их.

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

Claude Code поддерживает несколько режимов разрешений, которые контролируют, как он одобряет вызовы инструментов. См. Permission modes для определения того, когда использовать каждый из них. Чтобы изменить режим, в котором начинаются сеансы, установите defaultMode в ваших файлах параметров. Which mode a session starts in охватывает встроенное значение по умолчанию для каждого плана и то, что читает расширение VS Code.

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

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

Правила разрешений следуют формату Tool или Tool(specifier). Скобки внутри спецификатора являются буквальными, поэтому команда или путь, содержащие их, не требуют экранирования.

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

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

Bash(*) эквивалентен Bash и совпадает со всеми Bash командами. Как правило отказа, обе формы удаляют инструмент из контекста Claude.

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

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

Совпадение по входному параметру

Правила отказа и запроса могут совпадать с параметром верхнего уровня на любом встроенном инструменте с помощью Tool(param:value).

Чтобы совпадать с параметром на инструменте MCP, передайте правило отказа с --disallowedTools. Когда Claude Code загружает файл параметров, он пропускает любое правило mcp__, которое содержит скобки. Claude Code перечисляет пропущенное правило в диалоге invalid-settings при запуске интерактивного сеанса и в выводе claude doctor.

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

Совпадение параметров следует этим правилам:

• Имя параметра должно быть прямым полем входа инструмента, таким как model на инструменте Agent. Поля, вложенные внутри объекта или массива, не совпадают
• Каждое правило называет один параметр. Чтобы ограничить как model, так и isolation, напишите два правила, Agent(model:opus) и Agent(isolation:worktree), вместо того чтобы объединять их в одно правило
• Значение поддерживает * как подстановочный символ, который совпадает с любой последовательностью символов, поэтому Agent(isolation:*) совпадает с любым явным значением изоляции. Без * совпадение точное
• Параметр, который модель опускает, никогда не совпадает, поэтому Agent(model:*) не совпадает с вызовом, который оставляет model неустановленным
• Значение сравнивается с буквальным входом, который отправляет Claude, до любой нормализации. Agent(model:opus) совпадает с псевдонимом opus, но не с полным ID модели. Запустите с --verbose, чтобы увидеть точные имена параметров и значения в каждом вызове инструмента
• Пробелы вокруг двоеточия игнорируются

Вы не можете совпадать с основным полем содержимого инструмента таким образом: command для Bash и PowerShell, file_path для Read, Edit и Write, path для Grep и Glob, notebook_path для NotebookEdit и url для WebFetch. Правило, такое как Bash(command:rm *), можно было бы обойти составной командой, поэтому Claude Code игнорирует его и выдает предупреждение при запуске. Используйте Bash(rm *), Read(./path) или WebFetch(domain:host) вместо этого.

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

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

Напишите команду, которую вы хотите, чтобы Claude выполнил без запроса, и замените части, которые варьируются, на *. С этой конфигурацией Claude Code запускает npm скрипты и git коммиты без запроса и отказывает в командах, которые начинаются с git push. Push, написанный другим способом, такой как git -C . push, не совпадает; см. что правило Bash не совпадает.

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

* может находиться в любом месте правила: в начале, в середине или в конце. Каждая строка показывает правило, команды, которые оно совпадает, и близлежащие команды, которые оно не совпадает:

Три правила совпадения производят эти строки:

• * стоит вместо того, какой текст находится на его месте. В Bash(git * main), он стоит вместо подкоманды, поэтому Claude Code совпадает с каждой подкомандой git и каждой опцией перед ней. Это включает -c, что заставляет git запустить программу, которую вы называете. В Bash(* --version), * стоит вместо программы, поэтому совпадает любая программа.
• * в конце, с пробелом перед ним, также совпадает с голой командой. Bash(ls *) совпадает с ls, и Bash(git log *) совпадает с git log. Это верно только когда завершающий * — единственный подстановочный символ правила: Bash(* --help *) совпадает с npm --help x, но не с npm --help.
• Пробел перед завершающим * является частью правила. Bash(ls *) требует пробел после ls, поэтому lsof не совпадает. Bash(ls*) не имеет пробела, поэтому он совпадает с lsof тоже.

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

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

Подстановочные символы имён инструментов

Правила отказа и запроса также принимают glob-шаблоны в позиции имени инструмента. Шаблон должен совпадать с полным именем инструмента: "*" совпадает с каждым инструментом, и "mcp__*" совпадает с каждым MCP инструментом на всех серверах. Инструмент, совпадающий с правилом отказа с простым именем glob, удаляется из контекста Claude, так же как и простое имя инструмента, включая исключение EndConversation: glob отказ не может удалить его, пока остается любой другой инструмент, и glob запрос никогда не запрашивает его. Эта конфигурация отрицает каждый MCP инструмент:

{
  "permissions": {
    "deny": [
      "mcp__*"
    ]
  }
}

Правила разрешения принимают glob-шаблоны имён инструментов только после буквального префикса mcp__<server>__. Сегмент сервера должен быть свободен от glob, поэтому правило называет конкретный сервер, который вы настроили. mcp__puppeteer__* совпадает с каждым инструментом с сервера puppeteer, и mcp__github__get_* совпадает с его инструментами get_. Неякорированный glob разрешения, такой как "*", "B*" или "mcp__*", пропускается с предупреждением и не одобряет ничего автоматически.

Правило отказа или запроса, имя инструмента которого не совпадает ни с одним известным инструментом, выдает предупреждение при запуске, чтобы поймать опечатки. Имена инструментов, содержащие _ или *, освобождаются от проверки, и так же как и имена инструментов, которые Claude Code удалил, такие как TaskOutput.

Метка, отображаемая для инструмента в стенограмме и диалоге разрешений, может отличаться от его канонического имени. Например, инструмент с меткой Stop Task в стенограмме имеет каноническое имя TaskStop. Правила разрешений и матчеры hook не совпадают с меткой, поэтому правило, написанное как Stop Task, не совпадает. Для правил отказа и запроса предупреждение при запуске выше ловит несоответствие. Используйте канонические имена, указанные в справочнике инструментов.

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

Bash

Правила разрешений Bash совпадают с полным текстом команды, где * обозначает любой текст. Шаблоны подстановочных символов показывает, какие команды совпадают с каждой формой правила и где размещать *. Остальная часть этого раздела охватывает, как Claude Code совпадает с составными командами и оборачивателями, что правило не совпадает, команды только для чтения и перенаправления.

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

Правила deny и ask применяются, когда любая подкоманда совпадает с ними, включая команду, вложенную в подоболочку, подстановку команды или тело управления потоком, такое как цикл for. Правило ask, такое как Bash(git clean *), по-прежнему запрашивает вас для cd /tmp && git clean -f или echo "$(git clean -f)", даже в режиме auto.

Когда && или || не имеет ничего после него, например в npm test &&, Claude Code рассматривает команду как неразбираемую и не разделяет её на подкоманды для сопоставления правил allow, поэтому правило, такое как Bash(npm *), не одобряет её.

Когда вы одобряете составную команду с "Да, не спрашивать снова", 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, плюс встроенные команды оболочки command и builtin, а также noglob в zsh. Каждый запускает свой аргумент как фактическую команду. Две связанные формы не удаляются: форма запроса command -v, которая ищет команду, а не запускает её, и nocorrect в zsh.

Claude Code также удаляет ведущее присваивание определённых известных безопасных переменных окружения, поэтому Bash(npm test *) совпадает с NODE_ENV=test npm test. Правило allow не совпадает с присваиванием любой другой переменной. Правило deny или ask совпадает с любым ведущим присваиванием, поэтому Bash(rm *) в deny по-прежнему совпадает с FOO=bar rm -rf tmp/.

Голый 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 *), поэтому в режиме Manual они всегда запрашивают. То же самое применяется к find с -exec или -delete: правило Bash(find *) не охватывает эти формы. Чтобы одобрить конкретный вызов, напишите правило точного совпадения для полной строки команды.

Что правило Bash не совпадает

Правило Bash совпадает с текстом команды, который пишет Claude, после того как Claude Code разделит составные команды и удалит оборачиватели. Оно не совпадает с одной и той же программой, вызванной в другой форме, поэтому правило deny или ask охватывает вызов, который Claude обычно производит, и не является границей безопасности вокруг программы. Эти правила в deny или ask останавливают первую форму, а не другие:

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

Для принудительного применения файловой системы и сети, которое не зависит от текста команды, используйте sandboxing. Чтобы проверить полный текст команды с вашей собственной логикой перед её выполнением, используйте hook PreToolUse.

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

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

Перенаправление, такое как ls > out.txt, добавляет проверку на цель. См. Перенаправления.

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

В режиме Manual команды из этого набора по-прежнему запрашивают в этих случаях:

• Неквотированные глобы для команд с флагами, способными к записи: команды с флагами, способными к записи или выполнению, такие как find, sort, sed и git, запрашивают, когда присутствует неквотированный глоб, потому что глоб может расширяться до флага, такого как -delete.
• docker, указывающий на другой демон: формы docker только для чтения запрашивают, когда команда содержит флаг, который выбирает другой демон, такой как -H, --context или --url и --connection в Podman.
• file с флагами открытия пути: file запрашивает, когда он передаёт -m/--magic-file или -f/--files-from, потому что эти флаги заставляют file открывать пути, названные в значении флага.
• Сетевые пути в Windows: команда, чьи аргументы включают сетевой путь (UNC), такой как \\server\share\file, запрашивает, потому что доступ к сетевому пути может отправить ваши учётные данные Windows на хост, который он называет. Та же проверка применяется к командам инструмента PowerShell.
• Команды, которые анализ не может разобрать: когда Claude Code не может полностью разобрать команду, он запрашивает одобрение вместо того, чтобы рассматривать команду как только для чтения. Команды длиннее 10 000 символов всегда запрашивают, потому что они превышают то, что анализирует анализ.

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

• cd с git: запрашивает, когда cd переходит в другой каталог, так как запуск git в новом каталоге может выполнить hooks этого каталога. cd, целевой путь которого разрешается в текущий рабочий каталог, является no-op и не вызывает запрос.
• cd с перенаправлением: запрашивает, когда Claude Code не может определить, в какой каталог разрешается целевой путь перенаправления после выполнения cd. Команда, единственной целью перенаправления которой является /dev/null, такая как cd app; grep -r pattern . 2>/dev/null, не запрашивает, потому что /dev/null не зависит от рабочего каталога.

Перенаправления

Когда команда перенаправляет вывод или ввод, Claude Code проверяет цель перенаправления против ваших правил файлов, как если бы Claude напрямую написал или прочитал этот файл:

• Перенаправления вывода: для > file, >> file или 2> file, проверка охватывает ваши правила allow и deny Edit, защищённые пути и рабочие каталоги. Правило, такое как Bash(git commit *), разрешает команду, а не цель. Цель, которая начинается с ~ или содержит символ глоба, требует вашего одобрения.
• Перенаправления ввода: для < file, проверка охватывает ваши правила allow и deny Read и рабочие каталоги. Цель вне рабочих каталогов требует вашего одобрения, если правило allow не охватывает её. Цель, которая содержит шаблон глоба или относительный путь, следующий за cd в одной команде, требует вашего одобрения, даже когда правило allow охватывает её. Claude Code проверяет цели ввода в v2.1.257 и позже.

Цели без файла позади них не проверяются: /dev/null, формы дескриптора файла, такие как 2>&1 и <&3, и here-docs и here-strings.

Claude Code также проверяет файлы, которые пишет команда tee, включая в конвейер, такой как make | tee build.log. Проверка охватывает ваши правила allow и deny Edit, защищённые пути и рабочие каталоги. Правило allow, такое как Bash(tee *), не охватывает назначение вне рабочих каталогов. Claude Code проверяет цели tee в v2.1.269 и позже.

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

Чтобы заблокировать инструменты файлов Claude от чтения файла или каталога, добавьте правило deny Read для его пути, такое как Read(./.env) или Read(./secrets/**); Исключить конфиденциальные файлы содержит готовый к вставке пример.

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

Правило deny Read также блокирует инструменты Edit и Write на том же пути, включая создание нового файла там. NotebookEdit не охватывается, поэтому добавьте правило deny Edit для путей, которые ни один инструмент не может изменять. Проверка требует Claude Code v2.1.208 или позже при редактировании, и v2.1.228 или позже при записи.

Claude Code проверяет разрешения файлов только против правил Edit(path) и Read(path). Если вы напишете правило пути для Write, NotebookEdit, Glob или устаревшего инструмента MultiEdit вместо этого, Claude Code принимает правило, но никогда не консультируется с ним и предупреждает при запуске, за исключением правила Glob, переданного в --allowedTools. Используйте Edit(docs/**) вместо Write(docs/**), NotebookEdit(docs/**) или MultiEdit(docs/**), и Read(docs/**) вместо Glob(docs/**). Claude Code не предупреждает о правиле имени инструмента без пути, такое как правило deny для Write; оно совпадает с этим правилом на уровне инструмента везде. Требует Claude Code v2.1.210 или позже.

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

Шаблон /path якорирует в каталоге, связанном с источником параметров, который его определяет, поэтому одно и то же правило совпадает с разными местоположениями в зависимости от того, где вы его разместите:

Правило, которое вы добавляете через /permissions, следует строке для файла параметров, в который вы его сохраняете.

Локальные параметры правил якорируют в основном рабочем каталоге сеанса, а не в корне репозитория, где Claude Code хранит файл в v2.1.211 и позже. В сеансе, запущенном в корне репозитория, два каталога одинаковые; в сеансе worktree общее правило, такое как Edit(/src/**), совпадает с собственным каталогом src/ этого worktree.

Правило deny, такое как Read(/secrets/**) в параметрах пользователя, блокирует ~/.claude/secrets/**, а не каталог secrets в вашем проекте. Чтобы написать правило в параметрах пользователя, которое применяется внутри каждого проекта, используйте абсолютный путь // или путь относительно дома ~/ вместо этого.

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

Примеры:

• Edit(/docs/**): редактирование в <primary working directory>/docs/, не в /docs/ или <primary working directory>/.claude/docs/
• Read(~/.zshrc): чтение .zshrc вашего домашнего каталога
• Edit(//tmp/scratch.txt): редактирование абсолютного пути /tmp/scratch.txt
• Read(src/**): как правило allow, чтение из <current-directory>/src/ только; как правило deny или ask, совпадает с каталогом src на любой глубине под текущим каталогом

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

Относительный шаблон с одним сегментом каталога, такой как src/**, совпадает на разных глубинах в зависимости от типа правила:

• Правила allow: Edit(src/**) совпадает только с <cwd>/src и файлами под ним. Чтобы разрешить имя каталога на любой глубине, напишите Edit(**/src/**).
• Правила deny и ask: Read(secrets/**) совпадает с каталогом с именем secrets на любой глубине под текущим каталогом, поэтому правило также применяется к вложенным копиям.

Каждая другая форма шаблона совпадает на одной и той же глубине в каждом типе правила: Edit(/src/**) и Edit(src/components/**) совпадают только в их якорированном местоположении, в то время как Edit(**/src/**) совпадает на любой глубине.

Следующий пример показывает каждую форму шаблона против проекта с каталогом src/ верхнего уровня и вложенной копией под vendor/:

<current-directory>/
├── src/
│   └── app.ts
└── vendor/
    └── pkg/
        └── src/
            └── lib.js

Когда вы одобряете путь к файлу с "Да, не спрашивать снова", Claude Code экранирует символы шаблона gitignore в этом пути, такие как [, ] и *, поэтому сгенерированное правило совпадает только с буквальным путем, который вы одобрили. Правила, которые вы пишете сами, не экранируются. До версии 2.1.202 Claude Code сохранял путь без экранирования, поэтому сгенерированное правило для каталога с именем [2024-06] Reports могло не совпадать с его собственным путем или совпадать с непредусмотренными соседними каталогами.

Вам не нужно экранировать скобки в пути, поэтому Edit(./Finance (2024)/**) совпадает с папкой Finance (2024) как написано.

Правило deny или ask, чей путь не пригоден как шаблон gitignore, по-прежнему охраняет этот точный путь. Правило allow с непригодным шаблоном ничего не одобряет.

Шаблон deny или ask, который начинается с !, является отрицанием gitignore. Он вырезает пути, которые он совпадает, из правил path или ./path, перечисленных перед ним. В одном списке deny файла параметров, Read(*.env) с последующим Read(!sample.env) блокирует каждый файл, имя которого заканчивается на .env на любой глубине, за исключением файлов с именем sample.env. Правило !, перечисленное первым, ничего не вырезает.

Вырезание достигает только правил из одного источника. Read(!.env) в параметрах проекта или в --disallowedTools не отменяет Read(./.env) deny из управляемых параметров или любого другого файла параметров.

Два ограничения сужают то, что шаблон ! может вырезать:

• Claude Code читает шаблон ! относительно текущего каталога, даже когда после ! следует /, ~/ или //, поэтому шаблон не может достичь правила, якорированного одним из этих префиксов. Read(!~/notes/public/**) ничего не вырезает из Read(~/notes/**).
• Вырезание не может переоткрыть файл внутри каталога, который правило блокирует целиком. С Read(secrets/**) и Read(!secrets/public/**), Claude Code по-прежнему блокирует secrets/public вместе с остальной частью secrets.

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

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

На macOS и Linux правило deny или ask, написанное через символически связанный каталог с шаблоном //, ~/ или /, также применяется в реальном местоположении каталога. Например, на macOS, где /etc разрешается в /private/etc, Read(//etc/**) также блокирует /private/etc/hosts. До версии 2.1.268 правило deny или ask, написанное через символически связанный каталог, не применялось к пути, заданному его реальным местоположением.

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

Grep и Glob ищут каталог, в который разрешается аргумент path. Claude Code применяет правила deny Read к этому каталогу.

WebFetch

Правила WebFetch используют префикс domain: и совпадают с именем хоста запрашиваемого URL. Сопоставление не чувствительно к регистру, поддерживает подстановочные символы * и удаляет конечную точку из правила и имени хоста, поэтому example.com. и example.com рассматриваются одинаково.

• WebFetch(domain:example.com) совпадает с запросами на example.com
• WebFetch(domain:*.example.com) совпадает с любым поддоменом на любой глубине, таким как api.example.com или a.b.example.com, но не с самим example.com
• WebFetch(domain:*) совпадает с каждым доменом. Это не то же самое, что голое правило WebFetch; см. Разрешить или запретить каждую выборку

В любой позиции, отличной от ведущего *. или голого *, подстановочный символ совпадает только с текстом между двумя точками. WebFetch(domain:example.*) совпадает с example.org, где * становится org, но не с example.evil.com, где * должен был бы стать evil.com и пересечь точку. Это предотвращает совпадение конечного подстановочного символа с доменами, которые может зарегистрировать злоумышленник.

Подстановочные символы в правилах WebFetch требуют Claude Code v2.1.172 или позже для совпадения выборок.

Разрешить или запретить каждую выборку

Голое правило WebFetch - это имя инструмента без части domain:, такое как "deny": ["WebFetch"]. Оно и WebFetch(domain:*) охватывают каждый URL, но Claude Code применяет их по-разному, и только форма domain: также добавляет свой домен в список разрешённых или запрещённых доменов sandbox. Этот раздел перечисляет формы подстановочных символов, которые sandbox поддерживает, и версию, которая добавила голый *.

Каждая строка показывает, что правило делает в списке allow и в списке deny:

Две формы также отличаются при чтении артефактов, страниц, которые инструмент Artifact публикует на claude.ai. Голое правило deny или ask WebFetch не применяется к этим чтениям. Правило domain:, охватывающее claude.ai или хост содержимого *.claudeusercontent.com, такое как WebFetch(domain:claude.ai) или WebFetch(domain:*), отказывает в каждом чтении или запрашивает перед ним. Правило Artifact делает то же самое.

Когда правило блокирует чтение, отказ называет правило. До версии 2.1.268 голое правило deny WebFetch блокировало каждое чтение артефакта, и голое правило ask запрашивало перед каждым.

Чтобы позволить Claude выполнять выборку свободно, сохраняя список разрешений sandbox как есть, используйте голую форму. Этот settings.json делает это:

{
  "permissions": {
    "allow": ["WebFetch"]
  }
}

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

В режиме auto Claude вместо этого называет хост в разрешённых доменах для каждой команды сеанса для проверки классификатором.

MCP

Правила MCP используют имя сервера, настроенное в Claude Code, опционально за которым следует имя инструмента с этого сервера.

• mcp__puppeteer совпадает с любым инструментом, предоставленным сервером puppeteer
• mcp__puppeteer__* использует синтаксис подстановочных символов и также совпадает со всеми инструментами с сервера puppeteer
• mcp__puppeteer__puppeteer_navigate совпадает с инструментом puppeteer_navigate, предоставленным сервером puppeteer

Если ваша организация установила инструмент соединителя claude.ai на ask и эта настройка достигает Claude Code в вашем сеансе, правила allow для этого инструмента не вступают в силу: Claude Code запрашивает при каждом вызове, даже в режимах auto и bypassPermissions. В режиме dontAsk, который никогда не запрашивает, Claude Code отказывает в вызове вместо этого. Инструменты из соединителей, которые Claude Code получает сам, отображаются как mcp__claude_ai_<server>__<tool>.

В сеансе Cowork в приложении Claude Desktop Claude запускает команды оболочки через инструмент mcp__workspace__bash Cowork вместо встроенного инструмента Bash, и Cowork также предоставляет mcp__workspace__web_fetch для выборок в сети. Claude Code также применяет правила deny, которые называют весь инструмент Bash или WebFetch, к этим инструментам Cowork, поэтому управляемое правило deny Bash останавливает Claude от запуска команд оболочки в Cowork. Когда Claude Code блокирует такой вызов, сообщение называет инструмент Cowork: Permission to use mcp__workspace__bash has been denied. Правила allow не переносятся: Claude Code никогда не применяет правило allow Bash к mcp__workspace__bash.

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)"]
  }
}

Cd

Правила Cd контролируют, в какие каталоги команда /cd может переместить сеанс. Cd не является инструментом, вызываемым моделью: Claude не может его вызвать, и правила применяются только когда вы сами запускаете /cd.

Голое правило deny Cd отключает /cd полностью. Правило deny Cd(<path-pattern>) блокирует совпадающие цели. Правила deny проверяют каждое написание цели, включая каждый переход символической ссылки, через который она разрешается, поэтому правило, написанное для одного пути, также блокирует цели, которые разрешаются в него.

Добавление любого правила allow Cd переключает /cd в режим списка разрешений: разрешенный целевой каталог должен совпадать с одним из ваших правил allow, или /cd отказывает. Без настроенных правил Cd, /cd сохраняет своё поведение по умолчанию и запрашивает вас доверять незнакомому каталогу.

Шаблоны путей используют якоря //, ~/ и / из правил Read и Edit, но сопоставление якорировано ко всему пути каталога, а не в стиле gitignore. * совпадает ровно с одним сегментом пути и ** совпадает по сегментам. Конечный /** также совпадает с его названным корнем.

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

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

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

Инструменты MCP, отмеченные requiresUserInteraction, также по-прежнему запрашивают, когда hook возвращает "allow", как и инструменты соединителя установленные вашей организацией на ask в сеансах, где эта настройка достигает Claude Code.

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

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

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

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

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

Вы не можете добавить большинство сетевых путей, таких как общая папка UNC \\server\share, в качестве рабочих каталогов, потому что поиск может связаться с хостом, который она называет. На Windows вместо этого сопоставьте общую папку с буквой диска и передайте диск с помощью --add-dir при запуске.

Установите permissions.blockReadsOutsideWorkingDirectories, чтобы инструменты работы с файлами отказывали в путях, которые она ограничивает, в каждом режиме разрешений. В автоматическом режиме Claude Code предлагает включить это в первый раз, когда Claude читает вне рабочих каталогов.

В фоновых сеансах на macOS хост сеанса запрашивает доступ к защищённым папкам, таким как ~/Desktop, ~/Documents и ~/Downloads, отдельно от вашего терминала, когда Claude нужно читать или писать файлы там; если чтение там завершается с ошибкой Operation not permitted, см. как предоставить доступ к папкам для фоновых сеансов.

Переместить сеанс в другой каталог

Чтобы переместить сеанс в другой основной рабочий каталог, вместо добавления каталога рядом с текущим, запустите /cd <path>. Claude Code сохраняет беседу, загружает CLAUDE.md нового каталога и предлагает вам доверить рабочему пространству, если вы в нём раньше не работали. После этого Claude Code находит перемещённый сеанс, когда вы запускаете --resume из нового каталога.

Как только вы переместитесь, Claude Code применяет конфигурацию проекта нового каталога:

• Его параметры проекта, включая их правила разрешений и hooks
• Его серверы .mcp.json, подлежащие тому же одобрению сервера, что и при запуске, и локальные MCP серверы, которые вы зарегистрировали в нём
• Плагины, которые его параметры включают, его skills и его subagents
• Его значения env, применённые поверх переменных окружения из параметров предыдущего каталога, которые остаются в силе

Claude Code также отключает проект предыдущего каталога и локальные MCP серверы, а также серверы плагинов, которые больше не включены после перемещения. Он берёт дополнительные каталоги из параметров нового каталога вместо параметров предыдущего и сохраняет каталоги, которые вы добавили с помощью --add-dir или /add-dir. Hooks, которые активирует перемещение, по-прежнему получают ${CLAUDE_PROJECT_DIR}, установленный в корень проекта, где сеанс начался.

Когда новый каталог ещё не доверен, Claude Code перечисляет в подсказке доверия правила разрешения, дополнительные каталоги, hooks и вспомогательные команды, которые активировали бы параметры каталога, чтобы вы могли их просмотреть перед принятием. Если вы отклоните, сеанс останется там, где он был. До версии 2.1.246 /cd не применял параметры нового каталога, hooks, MCP серверы или skills до тех пор, пока вы не возобновили сеанс, и его подсказка доверия не перечисляла, что активировали бы параметры каталога.

Ограничьте или отключите цели /cd с помощью правил разрешений Cd.

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

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

Эти исключения применяются только к каталогам, добавленным с флагом --add-dir или командой /add-dir, включая каталоги, которые Agent SDK добавляет через флаг. Каталоги, указанные в permissions.additionalDirectories в файле параметров, предоставляют доступ только к файлам и не загружают никакую конфигурацию ниже.

Agent SDK additionalDirectories опция в TypeScript и add_dirs опция в Python получают исключения тоже, хотя опция TypeScript делит своё имя с ключом параметров. SDK передаёт каждую запись в Claude Code как --add-dir, поэтому эти каталоги ведут себя как каталоги, добавленные флагом. Skills, команды и subagents из любого каталога, добавленного флагом, загружаются через источник параметра project setting source, поэтому они не загружаются, когда вы исключаете этот источник с помощью --setting-sources в CLI или settingSources в SDK, и bare mode пропускает команды и subagents среди них.

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

Чтобы загрузить skills, команды и subagents из подкаталога вашего основного рабочего каталога в середине сеанса, запустите /add-dir с путём этого подкаталога. Claude Code загружает их на оставшуюся часть сеанса без запроса или добавления рабочего каталога, потому что подкаталог уже читаем. Это требует Claude Code версии 2.1.257 или позже.

Claude Code обнаруживает стили вывода из текущего рабочего каталога и его родителей, вашего пользовательского каталога в ~/.claude/ и управляемых параметров. Hooks и другие ключи .claude/settings.json загружаются из папки .claude/ текущего рабочего каталога без резервного варианта для родительского каталога, наряду с вашим пользовательским файлом ~/.claude/settings.json и управляемыми параметрами. .claude/settings.local.json загружается из корня репозитория git вместо этого, даже когда вы запускаете Claude Code в подкаталоге, кроме случаев, когда Claude Code не использует корень репозитория, например на Windows; до версии 2.1.211 он тоже загружался только из текущего рабочего каталога. Сеансы Agent SDK загружают его из рабочего каталога во всех версиях.

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

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

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

Разрешения и песочница — это дополняющие друг друга уровни безопасности:

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

Используйте оба уровня для защиты в глубину, поскольку ограничения песочницы остаются в силе даже если инъекция в подсказку обойдёт принятие решений Claude. Пути и домены из параметров песочницы и правил разрешений объединяются в финальную конфигурацию песочницы.

Когда вы включаете песочницу и оставляете autoAllowBashIfSandboxed со значением по умолчанию true, команды Bash в песочнице выполняются без запроса даже если ваши разрешения включают простое правило запроса Bash, или эквивалентную форму Bash(*): граница песочницы заменяет этот запрос для всего инструмента.

В режиме плана Claude Code пропускает эту замену. Без правила запроса встроенные команды только для чтения по-прежнему выполняются без запроса, и любая другая команда оболочки проходит через обычный поток разрешений пока вы всё ещё планируете; см. режим плана для того, как Claude Code управляет командами там. С простым правилом запроса Bash, каждая команда Bash запрашивается, включая команды только для чтения в песочнице, так же как вне песочницы. До версии v2.1.212 замена применялась также в режиме плана.

Эти проверки по-прежнему применяются:

• Правила запроса с областью действия контента, такие как Bash(git push *), по-прежнему требуют запроса
• Явные правила отказа по-прежнему применяются
• Команды rm или rmdir, которые нацелены на критический путь, по-прежнему проходят через обычный поток разрешений

Команды, которые не будут выполняться в песочнице, такие как исключённые команды, соблюдают простое правило запроса Bash как обычно. См. режимы песочницы для изменения этого поведения.