SpyBara
Go Premium

permissions.md 2026-09-28 22:59 UTC to 2026-09-29 09:02 UTC

This page contains 139 additions and 110 deletions.

2026
Fri 18 23:58 Tue 22 23:59 Mon 28 22:59 Tue 29 10:02

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

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

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

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

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

Тип инструмента Пример Требуется одобрение Поведение "Да, не спрашивать снова"
Только чтение Чтение файлов, Grep Нет, в пределах рабочего каталога и дополнительных каталогов Н/А
Bash команды Выполнение оболочки Да, кроме встроенного набора команд только для чтения Постоянно для каждого репозитория и команды
Изменение файлов Edit/Write файлы Да До конца сеанса
Веб-выборка WebFetch Да, кроме встроенного набора предварительно одобренных доменов документации Постоянно для каждого репозитория и домена
Веб-поиск WebSearch Да Постоянно для каждого репозитория

Когда вы выбираете "Да, не спрашивать снова" и одобрение сохраняется постоянно, например для команды 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.

Режим Описание
default Запрашивает разрешение при первом использовании каждого инструмента. Обозначается как Manual в CLI, расширениях VS Code и JetBrains, а также в приложении для рабочего стола, и Claude Code принимает manual как псевдоним. Метка и псевдоним требуют Claude Code v2.1.200 или более поздней версии. Метка приложения для рабочего стола не зависит от вашей версии CLI
acceptEdits Автоматически принимает редактирование файлов и общие команды файловой системы, такие как mkdir, touch, mv и cp для путей в рабочем каталоге или additionalDirectories
plan Claude читает файлы и запускает команды оболочки только для чтения для исследования, но не редактирует ваши исходные файлы; с доступным режимом auto также запускаются одобренные классификатором команды. Обозначается как Plan в CLI и расширении VS Code
auto Автоматически одобряет вызовы инструментов с проверками безопасности в фоне, которые проверяют, соответствуют ли действия вашему запросу
dontAsk Автоматически отклоняет каждый вызов, который иначе запросил бы подтверждение; чтение файлов в ваших рабочих каталогах и другие действия, которые не требуют одобрения, по-прежнему выполняются, как и инструменты, предварительно одобренные через /permissions или правила permissions.allow. AskUserQuestion, инструменты MCP, отмеченные requiresUserInteraction, и инструменты соединителя установленные вашей организацией на ask в сеансах, где эта настройка достигает Claude Code, отклоняются даже если вы их разрешили
bypassPermissions Пропускает запросы разрешений, за исключением действий, которые ни один режим не одобряет автоматически

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

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

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

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

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

Правило Эффект
Bash Совпадает со всеми Bash командами
WebFetch Совпадает со всеми запросами веб-выборки
Read Совпадает со всеми чтениями файлов

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

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

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

Правило Эффект
Bash(npm run build) Совпадает с точной командой npm run build
Read(./.env) Совпадает с чтением файла .env в текущем каталоге
WebFetch(domain:example.com) Совпадает с запросами выборки на example.com

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

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

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

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

Правило Совпадает
Agent(model:opus) Вызовы Agent, которые запрашивают уровень модели Opus
Agent(isolation:worktree) Вызовы Agent, которые запрашивают git worktree
Bash(run_in_background:true) Вызовы Bash, которые выполняются в фоновом режиме

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

  • Имя параметра должно быть прямым полем входа инструмента, таким как 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(npm run build) npm run build npm run build --watch
Bash(npm run *) npm run build, npm run test --watch, npm run npm install
Bash(git log * main) git log --oneline main, git log -5 main, git log --output=<file> main git log main, git push origin main
Bash(git * main) git merge main, git push origin main, git -c core.fsmonitor=<script> diff main git log
Bash(* --version) node --version, bash -c 'echo hi' --version node -v
Bash(ls *) ls -la, ls lsof
Bash(ls*) ls -la, lsof
Bash(* --help *) npm --help x npm --help

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

  • * стоит вместо того, какой текст находится на его месте. В 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 сопоставляет составные команды и обёртки, что правило не соответствует, команды только для чтения и перенаправления.

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

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

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

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

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

Правило Останавливает Не останавливает
Bash(curl *) curl https://example.com /usr/bin/curl https://example.com, sh -c 'curl https://example.com'
Bash(rm *) rm -rf build/ /bin/rm -rf build/, bash -c 'rm -rf build/'
Bash(git push *) git push origin main git -C . push origin main, git -c push.default=current push origin main, git 'push' origin main

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

Для принудительного применения файловой системы и сети, которое не зависит от текста команды, используйте изоляцию в песочнице. Чтобы проверить полный текст команды с вашей собственной логикой перед её выполнением, используйте 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 выполняются без запроса.

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

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

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

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

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

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

Claude Code также проверяет файлы, которые пишет команда tee, включая в конвейер вроде make | tee build.log. Проверка охватывает ваши правила разрешения и отказа Edit, защищённые пути и рабочие каталоги. Правило разрешения вроде 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 от чтения файла или каталога, добавьте правило отказа Read для его пути, такое как Read(./.env) или Read(./secrets/**) ; Исключить конфиденциальные файлы содержит готовый к вставке пример.

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

Правило отказа Read также блокирует инструменты Edit и Write на том же пути, включая создание нового файла там. NotebookEdit не охватывается, поэтому добавьте правило отказа 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 не предупреждает о правиле имени инструмента без пути, такое как правило отказа для Write; оно соответствует этому правилу на уровне инструмента везде. Требует Claude Code v2.1.210 или позже.

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

Шаблон Значение Пример Соответствует
//path Абсолютный путь от корня файловой системы Read(//Users/alice/secrets/**) /Users/alice/secrets/**
~/path Путь от домашнего каталога Read(~/Documents/*.pdf) /Users/alice/Documents/*.pdf
/path Путь относительно источника параметров Edit(/src/**/*.ts) <primary working directory>/src/**/*.ts в параметрах проекта
path или ./path Путь относительно текущего каталога Read(*.env) <cwd>/*.env

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

Правило определено в /path разрешается в
Параметры проекта в .claude/settings.json <primary working directory>/path
Локальные параметры в .claude/settings.local.json <primary working directory>/path
Параметры пользователя в ~/.claude/settings.json ~/.claude/path
Файл, переданный с --settings <file> <directory of file>/path
Флаги CLI или правила сеанса <primary working directory>/path

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

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

Правило отказа вроде 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/**): как правило разрешения, читает из <current-directory>/src/ только; как правило отказа или запроса, соответствует каталогу src на любой глубине под текущим каталогом

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

Правило отказа Блокирует Не блокирует
Read(.env) или Read(**/.env) любой .env в текущем каталоге или под ним .env в родительском каталоге или другом проекте
Read(//**/.env) любой .env в любом месте файловой системы ничего; правило якорировано в корне файловой системы

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

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

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

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

<current-directory>/
├── src/
│   └── app.ts
└── vendor/
    └── pkg/
        └── src/
            └── lib.js
Правило Соответствует src/app.ts Соответствует vendor/pkg/src/lib.js
Edit(src/**) как правило разрешения Да Нет
Edit(src/**) как правило отказа или запроса Да Да
Edit(/src/**) в любом типе правила Да Нет
Edit(**/src/**) в любом типе правила Да Да

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

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

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

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

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

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

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

Когда путь файла, который запрашивает Claude, проходит через символическую ссылку, проверка разрешения охватывает два пути: запрошенный путь и файл, на который он разрешается. Это применяется к символическим ссылкам на macOS, Linux и Windows, а также к соединениям каталогов на Windows.

Как правила соответствуют символически связанному пути

Правила разрешения и отказа обрабатывают запрошенный путь и файл, на который он разрешается, по-разному:

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

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

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

Если путь, который Claude просит отредактировать или написать, сам является символической ссылкой, инструменты Edit и Write отказывают в записи и направляют Claude к цели ссылки.

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

  • Разрешается вне рабочих каталогов: когда запрошенный путь находится внутри ваших рабочих каталогов, а файл, на который он разрешается, нет, запись не автоматически одобряется в режиме acceptEdits. В автоматическом режиме, если правило разрешения не одобряет запись, вас запрашивают вместо того, чтобы классификатор решал. Запрос называет путь, на который разрешается запись.
  • Разрешается к защищённому пути, который запрошенный путь не называет: таблица защищённых путей даёт результат для каждого режима разрешений, за исключением того, что где таблица маршрутизирует запись к классификатору, эта запись вместо этого запрашивает вас.
Пути, которые не могут быть разрешены или которые изменяются

Когда Claude Code не может определить, где путь ведёт на диск, например потому что символические ссылки на нём образуют цикл, инструменты Read, Edit и Write отказывают в операции.

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

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: также добавляет свой домен в список разрешённых или запрещённых доменов песочницы. Этот раздел перечисляет формы подстановки, которые песочница соблюдает, и версию, которая добавила голый *.

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

Правило В allow В deny
WebFetch Claude выполняет выборку без запроса вас. Не изменяет, какие хосты могут достичь изолированные команды. Claude Code удаляет инструмент WebFetch, поэтому Claude вообще не может выполнять выборку. Не изменяет, какие хосты могут достичь изолированные команды.
WebFetch(domain:*) Claude выполняет выборку без запроса вас, и изолированные команды могут достичь любого хоста. Claude Code сохраняет инструмент и отказывает каждой выборке, и изолированные команды не могут достичь ни один хост.

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

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

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

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

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

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

MCP

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

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

Если ваша организация установила инструмент коннектора claude.ai на ask и эта настройка достигает Claude Code в вашем сеансе, правила разрешения для этого инструмента не вступают в силу: 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 также применяет правила отказа, которые называют весь инструмент Bash или WebFetch, к этим инструментам Cowork, поэтому управляемое правило отказа Bash останавливает Claude от запуска команд оболочки в Cowork. Когда Claude Code блокирует такой вызов, сообщение называет инструмент Cowork: Permission to use mcp__workspace__bash has been denied. Правила разрешения не переносятся: Claude Code никогда не применяет правило разрешения Bash к mcp__workspace__bash.

Agent (подагенты)

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

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

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

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

Cd

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

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

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

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

Правило Соответствует Не соответствует
Cd(~/code/*) ~/code/app ~/code/app/src, ~/code
Cd(~/code/**) ~/code и любой каталог под ним каталоги вне ~/code
Cd(**/node_modules) любой каталог node_modules на любой глубине под текущим каталогом node_modules/pkg

Расширение разрешений с помощью 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:

Конфигурация Загружается из --add-dir
Skills в .claude/skills/ Да, с live reload
Файлы команд в .claude/commands/ Да, без live reload. Когда добавленный каталог и ваш проект оба определяют команду с одинаковым именем, Claude Code запускает команду вашего проекта
Subagents в .claude/agents/ Да, без live reload
Settings в .claude/settings.json и .claude/settings.local.json Только ключи enabledPlugins и extraKnownMarketplaces
CLAUDE.md файлы, .claude/rules/ и CLAUDE.local.md Только когда установлено CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1. CLAUDE.local.md дополнительно требует источник параметра local, который включен по умолчанию

Чтобы загрузить 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 как обычно. См. режимы песочницы для изменения этого поведения.

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

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

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

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

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

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

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

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

Хосты встраивания могут предоставлять дополнительную управляемую политику через опцию SDK managedSettings, включая правила разрешения разрешений, если администратор не устанавливает блокировки allowManaged*Only; раздел Deliver policy to Claude Desktop sessions описывает, когда политика встраивающей стороны применяется вообще.

Правила разрешений проекта и доверие рабочей области

Правила permissions.allow и записи permissions.additionalDirectories в файле .claude/settings.json проекта предоставляют возможности, поэтому Claude Code применяет их только после того, как вы примете диалог доверия рабочей области для этой папки. Диалог перечисляет правила и каталоги, которые папка предоставит, чтобы вы могли их проверить перед принятием. Правила deny и ask не затрагиваются, так как они только ограничивают.

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

  • В репозитории Claude Code привязывает доверие к корню репозитория git, поэтому доверие охватывает весь репозиторий, кроме любого репозитория git, вложенного в него, например подмодуля. В worktree он использует корень основного checkout, как он это делает для сохранённых правил.
  • Вне репозитория Claude Code привязывает доверие к каталогу, из которого вы его запустили, и доверие охватывает любой подкаталог этого каталога, кроме репозитория git, вложенного в него, например клона. Каждый охватываемый подкаталог затем считается папкой, родителю которой вы доверяли.
  • Когда вы начинаете работу в домашнем каталоге, Claude Code сохраняет доверие только для текущего сеанса и не записывает его на диск; см. примечание дополнительные меры безопасности.

Claude Code показывает диалог доверия только в интерактивных сеансах. Запуск claude -p или сеанс SDK никогда не показывает его, и доверие к родительской папке не учитывается для этих правил, поэтому Что выполняется до того, как вы доверяете папке указывает, какое содержимое репозитория Claude Code всё ещё использует в каждой из этих двух ситуаций.

Перед запуском или перезапуском фонового сеанса Claude Code также проверяет доверие рабочей области для каталога, в котором выполняется сеанс. Если вы запустите claude --bg из терминала в каталоге, которому вы не доверяли, диалог доверия появляется в первую очередь, и сеанс начинается после того, как вы его примете. Где диалог не может появиться, например в скрипте, команда вместо этого завершается с ошибкой Workspace not trusted.

Когда ваш локальный файл параметров требует доверия

.claude/settings.local.json обычно является вашим собственным файлом, поэтому Claude Code применяет его правила разрешений и дополнительные каталоги без этапа доверия. Когда файл отслеживается в git или .claude является символической ссылкой, Claude Code рассматривает его как предоставленный репозиторием и сохраняет его правила до тех пор, пока вы не доверяете папке.

Claude Code запускает git, чтобы различить эти два случая, и запускает git только после того, как вы доверяли папке: вы приняли диалог доверия для неё или для родительского каталога, доверие которого распространяется на неё, или вы находитесь в сеансе -p или SDK, который считается принятым. До этого момента то, где вы запустили Claude Code, определяет, что происходит с правилами файла:

  • В вашем конфигурационном домашнем каталоге: Claude Code применяет .claude/settings.local.json этой папки сразу же без запуска git. Ваш конфигурационный домашний каталог — это ваш домашний каталог или каталог, чей подкаталог .claude вы установили как CLAUDE_CONFIG_DIR. Если этот каталог CLAUDE_CONFIG_DIR находится внутри репозитория git и Claude Code сохраняет ваши локальные параметры в корне репозитория, он сохраняет правила, как везде.
  • Везде в другом месте: Claude Code сохраняет правила файла, как параметры проекта. После выполнения проверки Claude Code применяет правила неотслеживаемого файла или файла в каталоге вне любого репозитория git, даже если вы не доверяли этой точной папке.

В версиях 2.1.196–2.1.199 Claude Code сохранял правила файла в вашем конфигурационном домашнем каталоге и вне репозиториев git, и выводил предупреждение this workspace has not been trusted там. До версии 2.1.207 Claude Code применял правила неотслеживаемого файла до того, как вы приняли диалог.

Что выполняется до того, как вы доверяете папке

Каждая строка — это один вид содержимого, который может предоставить репозиторий. Столбцы — это две ситуации, в которых вы не доверяли самой папке: вы доверяли только родительской папке или запустили claude -p или SDK там, что никогда не показывает диалог доверия. Столбец родительской папки не применяется внутри вложенного репозитория: в интерактивном сеансе Claude Code показывает диалог доверия для него, и запуск claude -p или SDK там следует столбцу claude -p.

Что предоставляет репозиторий Вы доверяли только родительской папке claude -p или SDK, папка никогда не была доверена
Hooks в файлах параметров, блок env и вспомогательные команды, такие как apiKeyHelper, и hooks проектного skill и allowed-tools Используется Используется. Доверие рабочей области никогда не блокирует allowed-tools skill в любом сеансе
Правила permissions.allow и additionalDirectories в .claude/settings.json Не используется до тех пор, пока вы не примете диалог доверия, который появляется снова, перечисляя их Не используется. Claude Code выводит предупреждение this workspace has not been trusted в stderr
Hooks frontmatter в проектном subagent, проектном плагине @skills-dir и записях extraKnownMarketplaces из репозитория или каталога --add-dir Не используется, и диалог не предлагается Не используется
Встроенные mcpServers в frontmatter subagent из репозитория или каталога --add-dir. До версии 2.1.238 Claude Code загружал эти серверы в обоих ситуациях Не используется, и диалог не предлагается Не используется
Серверы в .mcp.json, включая те, которые репозиторий одобряет в своих собственных параметрах Claude Code спрашивает вас перед подключением. Собственные одобрения репозитория не учитываются Подключены без запроса, одобрены или нет. SDK загружает их только когда settingSources включает параметры проекта. claude mcp list в той же папке по-прежнему сообщает о таком сервере как ожидающем
headersHelper на сервере в .mcp.json. До версии 2.1.238 Claude Code запускал помощника в обоих ситуациях Не запускается до тех пор, пока вы не примете диалог доверия, который появляется снова, указывая, где объявлен помощник. Claude Code подключает сервер только с его статическими headers до этого момента Не запускается. Claude Code подключает сервер с его статическими headers и выводит строку headersHelper not run на сервер в stderr

Для строк, которым требуется доверие этой точной папки, доверьте ей вручную: установите projects["<path>"].hasTrustDialogAccepted на true в ~/.claude.json, где <path> — это корень репозитория или сама папка вне репозитория. Claude Code выводит точный ключ в строку журнала отладки для пропущенного hook subagent или встроенного MCP сервера, в предупреждение stderr для пропущенных правил разрешений и в строку headersHelper not run для пропущенного помощника.

Перед запуском claude -p в репозитории, который вы не написали, решите, что он может запустить на вашей машине:

  • Передайте --setting-sources user или установите settingSources SDK без параметров проекта, чтобы Claude Code не читал ни файлы параметров проекта, ни его .mcp.json
  • Начните с --bare, чтобы Claude Code не читал hooks, skills, пользовательские команды, subagents, плагины или серверы .mcp.json из проекта. Блок env проекта и помощники, такие как awsAuthRefresh в его файлах параметров, по-прежнему применяются, и Claude Code читает apiKeyHelper только из --settings
  • Передайте --settings '{"disableAllHooks": true}', чтобы отключить hooks для этого запуска. Установка его только в ваших пользовательских параметрах недостаточна, потому что параметры проекта репозитория имеют приоритет над вашими и могут установить его обратно на false
  • Добавьте запись disabledMcpjsonServers, чтобы отклонить сервер .mcp.json по имени в каждом типе сеанса

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

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

См. также

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