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

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

Начиная с Claude Code v1.1.1, рекомендуется использовать новый метод настройки разрешений. Стараяtoolsбулева конфигурация всё ещё поддерживается, но рекомендуется перейти на новый синтаксис правил разрешений.

Обзор системы разрешений

Система разрешений Claude Code классифицирует операции по трём типам, и для каждого типа действует своя политика разрешений по умолчанию:

Тип инструмента Пример Требуется одобрение Поведение, разрешённое навсегда
Операции только для чтения Чтение файлов, поиск Grep нет Не применимо
Команды Bash Выполнение команд оболочки Да Бессрочно для каждого каталога проекта и команды
Изменения файлов Редактирование/запись файлов Да До конца сессии

Три действия с разрешениями

Каждое правило разрешений в итоге сводится к одному из следующих трёх действий:

Действие Эффект Применимый сценарий
"allow" Автоматически выполняется без подтверждения Низкорисковые, часто выполняемые операции, такие как git status, npm run build
"ask" Показывает запрос на подтверждение, позволяя вам решить, разрешить ли Операции с некоторым риском, например запись файлов, выполнение опасных команд
"deny" Непосредственно блокируется, не выполняется и не запрашивает подтверждение Явно запрещённые опасные операции, такие как git push, rm -rf

Приоритет правил: deny → ask → allow.Первое совпавшее правило имеет приоритет, поэтому правила deny всегда преобладают над allow и ask.

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

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

1. Шесть доступных режимов

Mode Описание Лучше всего подходит для
default Стандартное поведение: запрашивает разрешение при первом использовании каждого инструмента Адаптация, чувствительная работа, требующая полного надзора
acceptEdits Автоматически принимать разрешения на редактирование файлов для сеанса, кроме защищенных каталогов Итерации по коду, находящемуся на проверке
plan Режим планирования: Claude может анализировать, но не может изменять файлы или выполнять команды Изучение кодовых баз, планирование рефакторинга
auto Автоматически одобрять вызовы инструментов с фоновыми проверками безопасности (исследовательский предпросмотр) Длительные задачи, снижение усталости от запросов
dontAsk Автоматически отклонять вызовы инструментов, если они не предварительно одобрены через правила разрешений Среды с жесткими ограничениями, конвейеры CI
bypassPermissions Пропускать запросы разрешений, но запись в защищенные каталоги все равно запрашивает разрешение Только изолированные контейнеры и виртуальные машины

Примечание о защищённых каталогах:Независимо от режима, записи в.git、.vscode、.idea、.huskyи.claudeникогда не будут автоматически одобрены, за исключением.claude/commands、.claude/agentsи.claude/skills。

2. Переключение режимов разрешений

Переключение во время сеанса:нажмитеShift+TabЦиклическое переключение режимовdefault → acceptEdits → plan → auto

Укажите режим при запуске:

claude --permission-mode plan
claude --permission-mode bypassPermissions

Установить как режим по умолчанию (settings.json):

Пример

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

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

1. Базовый формат

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

Пример

{
  "permissions": {
    "allow": ["Bash", "WebFetch", "Read"],
    "deny": ["Edit"]
  }
}

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

Правила без спецификаторов соответствуют всем случаям использования этого инструмента:

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

Bash(*)ЭквивалентноBash, оба имеют одинаковый эффект.

3. Детальный контроль с помощью спецификаторов

Пример

{
  "permissions": {
    "allow": [
      "Bash(npm run build)",     // Соответствие точным командам
      "Read(./.env)",             // Соответствие чтению файла .env в текущем каталоге
      "WebFetch(domain:example.com)"  // Соответствует запросам fetch к example.com
    ]
  }
}

4. Шаблоны с подстановочными знаками

Правила Bash поддерживают glob-шаблоны с*подстановочными знаками; подстановочные знаки могут появляться в любом месте команды:

Пример

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",         // Соответствует npm run build, npm run test и т. д.
      "Bash(git commit *)",      // Соответствует git commit -m "message" и т. д.
      "Bash(git * main)",        // Соответствует git checkout main, git merge main и т. д.
      "Bash(* --version)",       // Соответствует любой команде с аргументом --version
      "Bash(* --help *)"         // Соответствует любой команде с аргументом --help
    ],
    "deny": [
      "Bash(git push *)"         // Блокирует все операции git push
    ]
  }
}

Обратите внимание на пробел перед подстановочными знаками:Bash(ls *)matchesls -laно не совпадаетlsof；Bash(ls*)совпадает с обоими.

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

1. Команды Bash

Правило Примеры сопоставления
Bash(npm run build) толькоnpm run build
Bash(npm run test *) npm run test、npm run test --coverage
Bash(npm *) Любая команда, начинающаяся с npm
Bash(* install) Любая команда, заканчивающаяся на install
Bash(git * main) git checkout main、git merge main

Важное ограничение:Шаблоны разрешений Bash, которые пытаются ограничить аргументы команды, могут быть ненадёжными. Опции перед URL, разные протоколы, перенаправления, переменные, лишние пробелы — всё это может приводить к несовпадениям. Рекомендуется использовать инструмент WebFetch сdomain:разрешениями для фильтрации URL.

2. Read и Edit (операции с файлами)

Пути к файлам поддерживают несколько шаблонов префиксов пути:

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

Пример

{
  "permissions": {
    "allow": [
      "Edit(/docs/**)",          // Разрешить редактирование файлов в каталоге docs проекта
      "Read(~/.zshrc)",         // Разрешить чтение .zshrc в домашнем каталоге
      "Edit(//tmp/scratch.txt)", // Разрешить редактирование временных файлов по абсолютным путям
      "Read(src/**)"            // Разрешить чтение файлов в подкаталоге src текущего каталога
    ],
    "deny": [
      "Read(*.env)",            // Запретить чтение файлов .env (предотвратить утечку секретов)
      "Edit(//etc/**)"          // Запретить редактирование файлов системного каталога
    ]
  }
}

Примечание:Правила запрета Read и Edit не применяются в подпроцессах Bashcat .env. Чтобы обеспечить принудительное применение на уровне ОС, включите песочницу.

3. WebFetch (сетевые запросы)

Пример

{
  "permissions": {
    "allow": [
      "WebFetch(domain:github.com)",    // Разрешить доступ к GitHub
      "WebFetch(domain:api.example.com)" // Разрешить доступ к внутренним API
    ],
    "deny": [
      "WebFetch(domain:untrusted.com)"  // Заблокировать доступ к недоверенным доменам
    ]
  }
}

4. MCP (Model Context Protocol)

Пример

{
  "permissions": {
    "allow": [
      "mcp__puppeteer",                      // Разрешить любые инструменты, предоставляемые сервером puppeteer
      "mcp__puppeteer__*"                    // Разрешить все инструменты с сервера puppeteer
    ],
    "deny": [
      "mcp__puppeteer__puppeteer_navigate"  // Заблокировать конкретные инструменты
    ]
  }
}

5. Agent (субагент)

Пример

{
  "permissions": {
    "allow": [
      "Agent(Explore)",           // Разрешить использование субагента Explore
      "Agent(Plan)"               // Разрешить использование субагента Plan
    ],
    "deny": [
      "Agent(my-custom-agent)"    // Заблокировать пользовательские субагенты
    ]
  }
}

Настройка рабочего каталога

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

1. Расширенные методы доступа

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

Пример

{
  "additionalDirectories": [
    "~/projects/personal/**",    // Разрешить доступ к каталогам личных проектов
    "~/projects/work/**",        // Разрешить доступ к каталогам рабочего проекта
    "~/dotfiles/**"               // Разрешить доступ к каталогам файлов конфигурации
  ]
}

2. Исключения

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

  • .claude/skills/Навыки в (с живой перезагрузкой)
  • .claude/settings.jsonНастройки плагина в (толькоenabledPluginsиextraKnownMarketplaces）
  • Файлы CLAUDE.md и.claude/rules/(только когдаCLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1задано)

Автоматический режим

Автоматический режим — это новый механизм, представленный в Claude Code, который заменяет ручное одобрение управляемым моделью классификатором, максимально контролируя риски и обеспечивая эффективность.

1. Доступные условия

  • Только для планов Team, Enterprise и API
  • Требуется Claude Sonnet 4.6 или Claude Opus 4.6
  • Недоступно для Haiku, моделей claude-3 или сторонних провайдеров
  • Администраторы должны включить это в административных настройках Claude Code

2. Как это работает

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

Уровни защиты:

  1. Серверные проверки сканируют входящие результаты инструментов
  2. Классификатор никогда не видит результаты работы инструментов, что предотвращает влияние внедрённых инструкций на решения

Порядок оценки операций:

  1. Операции, соответствующие правилам разрешения или запрета, обрабатываются немедленно
  2. Операции только для чтения и правки файлов в рабочей директории автоматически одобряются (кроме защищённых директорий)
  3. Всё остальное отправляется классификатору
  4. Если классификатор блокирует, Claude получает причину и пробует альтернативные методы

3. Поведение классификатора по умолчанию

Тип операции Поведение
Заблокировано по умолчанию
Загрузка и выполнение кода curl | bashожидание
Отправка конфиденциальных данных на внешние эндпоинты Риск утечки данных
Развертывания и миграции в продакшене Изменения в продакшен-среде
Масштабные удаления в облачном хранилище Риск потери данных
Предоставление IAM-разрешений или разрешений репозитория Риск повышения привилегий
Изменение общей инфраструктуры Влияет на других пользователей
Необратимое уничтожение файлов Файлы, существовавшие до начала сессии
Деструктивные операции с системой контроля версий Принудительные push, прямые push в main
Разрешить по умолчанию
Локальные файловые операции в рабочем каталоге В рамках области безопасности
Установка объявленных зависимостей Зависимости уже в package.json
Читать .env и отправлять учётные данные Отправлять в соответствующие API
HTTP-запросы только для чтения GET-запросы
Push в запущенную ветку Безопасные операции с ветками

4. Конфигурация автоматического режима

Пример

{
  "autoMode": {
    "environment": [
      "Контроль версий: github.example.com/acme-corp и все репозитории под ним",
      "Доверенные облачные бакеты: s3://acme-build-artifacts, gs://acme-ml-datasets",
      "Доверенные внутренние домены: *.corp.example.com, api.internal.example.com",
      "Ключевые внутренние сервисы: Jenkins на ci.example.com, Artifactory на artifacts.example.com"
    ],
    "allow": [
      "Развёртывание в пространство имён staging разрешено",
      "Запись в s3://acme-scratch/ разрешена"
    ],
    "soft_deny": [
      "Никогда не запускайте миграции базы данных вне CLI миграций",
      "Никогда не изменяйте файлы в infra/terraform/prod/: изменения производственной инфраструктуры проходят через процесс проверки"
    ]
  }
}

5. Механизм отката

Если классификатор блокирует операции 3 раза подряд или в общей сложности 20 раз за сессию, автоматический режим приостанавливается, и Claude Code возвращается к запросу подтверждения для каждой операции.

/permissions  # 在 "最近拒绝" 选项卡查看被拒绝的操作

Взаимосвязь между песочницей и разрешениями

Песочница и разрешения — это взаимодополняющие слои безопасности, которые работают вместе:

Аспект Разрешения Песочница
Целевой объект управления Определяет, какие инструменты может использовать Claude Code Ограничивает файловую систему и сетевой контент, доступные командам Bash
Время оценки Оценка выполняется до запуска любого инструмента Применяется только к командам Bash и их подпроцессам
Область применения Все инструменты: Bash, Read, Edit, WebFetch, MCP и т. д. Только команды Bash

1. Включение песочницы

/sandbox

Запустите/sandboxкоманда для включения песочницы; откроется меню для выбора режима песочницы.

2. Настройка песочницы

Пример

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"],    // Разрешить запись в эти пути
      "denyWrite": ["~/important/**"],            // Блокировать запись в важные каталоги
      "denyRead": ["~/"]                           // Блокировать чтение домашнего каталога
    },
    "network": {
      "httpProxyPort": 8080,                       // Порт HTTP-прокси
      "socksProxyPort": 8081                       // Порт SOCKS-прокси
    }
  }
}

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

Расширение разрешений с помощью хуков

Хуки PreToolUse выполняются перед запросами разрешений и могут:

  • Запретить вызовы инструментов
  • Принудительно запросить
  • Пропустить запрос и позволить вызову продолжиться

Пример

#!/bin/bash
# Пример хука PreToolUse: перехват опасных команд
COMMAND=$(cat | jq -r '.tool_input.command // empty')

if echo "$COMMAND" | grep -qE 'rm\s+(-[rf]+\s+)*(\/|~|\.\.\/)'; then
    echo "ЗАБЛОКИРОВАНО: rm в чувствительном пути"
    exit 2  # Код выхода 2 блокирует вызов инструмента
fi
exit 0  # Разрешить продолжение

Важно:Пропуск запроса не обходит правила разрешений. Правила deny и ask всё ещё проверяются после того, как хук вернёт "allow". Когда блокирующий хук завершается с кодом выхода 2, он останавливает вызов инструмента до проверки правил разрешений.

Настройка приоритета

Настройки Claude Code действуют в следующем порядке приоритета (от высшего к низшему):

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

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

Практические примеры конфигурации

Пример 1: Консервативный режим (все операции требуют подтверждения)

Подходит для тех, кто только начинает работать с Claude Code, или при работе над важными проектами:

Пример

{
  "permissions": {
    "defaultMode": "default"
  }
}

Пример 2: Типовая конфигурация для разработки (операции чтения открыты, выполнение команд требует подтверждения)

Подходит для повседневной разработки: разрешить Claude свободно читать и искать код, но требовать подтверждения при изменении файлов и выполнении команд:

Пример

{
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Bash(git status *)",      // Просмотр git status
      "Bash(git log *)",         // Просмотр git log
      "Bash(git diff *)",       // Просмотр git diff
      "Bash(npm run *)",         // Запуск npm-скриптов
      "Bash(npm test *)",        // Запуск тестов
      "Bash(ls *)",              // Список каталогов
      "Bash(grep *)"             // Поиск содержимого
    ],
    "deny": [
      "Bash(rm *)",              // Удаление файлов: блокировать напрямую
      "Bash(git push *)",        // Отправка кода: блокировать напрямую
      "Bash(mkdir / *)",         // Создание системных каталогов: блокировать напрямую
      "Edit(*.env)"              // Блокировать редактирование файлов .env
    ]
  }
}

Пример 3: Конфигурация заблокированной среды (разрешены только предварительно одобренные операции)

Подходит для CI-конвейеров или сред, требующих строгого контроля:

Пример

{
  "permissions": {
    "defaultMode": "dontAsk",
    "allow": [
      "Read(*)",                  // Разрешить чтение всех файлов
      "Bash(npm run build *)",    // Разрешить команды сборки
      "Bash(npm test *)"          // Разрешить запуск тестов
    ],
    "deny": [
      "Edit(*)",                  // Запретить все изменения файлов
      "Bash(git *)",              // Запретить все операции git
      "Bash(curl *)",             // Запретить сетевые запросы
      "Bash(ssh *)"               // Запретить SSH-подключения
    ]
  }
}

Пример 4: Разрешение доступа к нескольким проектам

Когда Claude нужно работать в нескольких каталогах проектов:

Пример

{
  "permissions": {
    "allow": [
      "Edit(/src/**)",            // Разрешить редактирование каталога src
      "Edit(/docs/**)"            // Разрешить редактирование каталога документации
    ],
    "deny": [
      "Edit(/docs/**/*.md)"       // Запретить редактирование файлов документации (только для чтения)
    ]
  },
  "additionalDirectories": [
    "~/projects/personal/**",     // Разрешить доступ к личным проектам
    "~/projects/work/**",         // Разрешить доступ к рабочим проектам
    "~/dotfiles/**"               // Разрешить доступ к файлам конфигурации
  ]
}

Пример 5: Использование песочницы для ограничения операций Bash

Включение песочницы обеспечивает дополнительную защиту на уровне ОС:

Пример

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/projects/myapp/**"],
      "denyRead": ["~/secrets/**"]
    },
    "network": {
      "httpProxyPort": 8080
    }
  },
  "permissions": {
    "allow": [
      "Bash(*)",                  // Разрешить все команды внутри песочницы
      "WebFetch(domain:api.github.com)"
    ],
    "deny": [
      "WebFetch(domain:untrusted.com)"
    ]
  }
}

Управляемые настройки (конфигурация администратора)

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

Настройка Описание
allowManagedHooksOnly Запретить загрузку пользовательских, проектных и плагинных хуков
allowManagedMcpServersOnly Учитывать только MCP-серверы из управляемых настроек
allowManagedPermissionRulesOnly Запретить пользовательским и проектным настройкам определять правила разрешений
sandbox.filesystem.allowManagedReadPathsOnly Учитывать только пути чтения из управляемых настроек
sandbox.network.allowManagedDomainsOnly Учитывать только разрешенные домены из управляемых настроек
permissions.disableBypassPermissionsMode Установите значение "disable", чтобы запретить использование режима bypassPermissions
permissions.disableAutoMode Установите значение "disable", чтобы запретить использование автоматического режима

Лучшие практики безопасности

  1. Начните с ограничений: Начните с минимальных привилегий и расширяйте их по мере необходимости
  2. Используйте песочницу: Песочницы обеспечивают дополнительную защиту на уровне ОС, и их следует включать вместе с остальными мерами
  3. Защитите конфиденциальные файлы: Используйтеdenyправила для блокировки доступа.env, ключевые файлы и т. д.
  4. Ограничьте сетевой доступ: Разрешайте доступ только к необходимым доменам, чтобы предотвратить утечку данных
  5. Избегайте bypassPermissions: Используйте только в изолированных средах (контейнерах, виртуальных машинах)
  6. Используйте soft_deny автоматического режима: Обеспечивает рекомендации по безопасности, не будучи чрезмерно ограничительным
  7. Регулярно проверяйте конфигурации: Проверяйте попытки нарушения песочницы и отклонённые операции

Предупреждение по безопасности:bypassPermissionsЭтот режим не обеспечивает защиту от внедрения промптов или непреднамеренных действий. Для более безопасной альтернативы, которая по-прежнему поддерживает фоновые проверки безопасности, используйте автоматический режим.

Другие расширения