Настройка разрешений
Контролируйте использование инструментов вашим агентом с помощью режимов разрешений, hooks и декларативных правил allow/deny.
Claude Agent SDK предоставляет элементы управления разрешениями для управления использованием инструментов Claude. Используйте режимы разрешений и правила для определения того, что разрешено автоматически, и callback canUseTool для обработки всего остального во время выполнения.
Как оцениваются разрешения
Когда Claude запрашивает инструмент, SDK проверяет разрешения в следующем порядке:
Hooks
Сначала запустите hooks. Hook может отклонить вызов полностью или передать его дальше. Hook, который возвращает allow, не пропускает правила deny и ask ниже; они оцениваются независимо от результата hook. PreToolUse hook allow также не может одобрить удаление rm или rmdir, нацеленное на критический путь.
Правила deny
Проверьте правила deny (из disallowed_tools и settings.json). Если правило deny совпадает, инструмент блокируется, даже в режиме bypassPermissions. Записи с простым названием, такие как Bash, удаляют инструмент из контекста Claude перед началом этой оценки, поэтому на этом шаге проверяются только правила с областью действия, такие как Bash(rm *).
Правила ask
Проверьте правила ask из settings.json. Если правило ask совпадает, вызов передаётся вашему callback canUseTool для подтверждения, даже в режиме bypassPermissions.
Инструменты, которые требуют взаимодействия с пользователем, ведут себя так же: AskUserQuestion и MCP инструменты, сервер которых устанавливает _meta["anthropic/requiresUserInteraction"], всегда передаются callback, даже когда совпадает правило allow. В режиме dontAsk оба случая отклоняются вместо этого, потому что этот режим никогда не запрашивает подтверждение. Аннотация MCP требует Claude Code v2.1.199 или более поздней версии.
Инструменты claude.ai connector, которые ваша организация установила на ask, также покидают поток на этом шаге. Каждый вызов передаётся callback, даже в режиме bypassPermissions и даже когда совпадает правило allow. Callback получает причину Your organization requires approval for this tool. В режиме dontAsk вызов отклоняется вместо этого, потому что этот режим никогда не запрашивает подтверждение.
Режим разрешений
Примените активный режим разрешений:
- В режиме
bypassPermissionsClaude Code одобряет всё, что достигает этого шага, кроме удаленийrmиrmdir, нацеленных на критический путь, которые передаются дальше вместо этого. - В режиме
acceptEditsClaude Code одобряет операции с файлами, перечисленные в разделе Режим Accept edits. - В режиме
planClaude Code отправляет инструменты file-edit и shell-write вашему callbackcanUseToolнезависимо от правил allow, поэтому операции записи не могут быть автоматически одобрены во время планирования. - В других режимах запрос передаётся дальше.
Правила allow
Проверьте правила allow (из allowed_tools и settings.json). Если правило совпадает, инструмент одобрен. Вызов, который инструмент одобряет самостоятельно, разрешается на этом шаге также без необходимости в правиле: например, чтение файла в ваших рабочих каталогах или команда Bash только для чтения. Удаления rm и rmdir, нацеленные на критический путь, никогда не одобряются правилом allow: они достигают вашего callback в режимах, которые запрашивают подтверждение, переходят к классификатору в режиме auto на Claude Code v2.1.218 или более поздней версии и отклоняются в режиме dontAsk.
Callback canUseTool
Если не разрешено ни одним из вышеперечисленных, вызовите ваш callback canUseTool для принятия решения. В режиме dontAsk этот шаг пропускается и инструмент отклоняется.
В TypeScript SDK, если вы установите permissionPrompts: 'none', ваш callback не вызывается на этом шаге. Hook PermissionRequest всё ещё получает возможность принять решение, и если он этого не делает, Claude Code отклоняет вызов. Опция требует Claude Code v2.1.259 или более поздней версии.
Если вы передаёте callback canUseTool в конфигурации, где TypeScript SDK ожидает, что порядок оценки автоматически одобрит вызовы перед консультацией callback, SDK выдаёт предупреждение процесса Node.js один раз при построении запроса. Код предупреждения — CLAUDE_SDK_CAN_USE_TOOL_SHADOWED. Две конфигурации вызывают его:
permissionMode: 'bypassPermissions', который автоматически одобряет каждый вызов, достигающий шага режима разрешений, кроме действий, которые ни один режим не одобряет автоматически- Каждая запись
allowedToolsс простым названием, такая как"Read", которая автоматически одобряет весь этот инструмент перед консультацией callback, кроме действий, которые ни один режим не одобряет автоматически
Записи со спецификатором, такие как Bash(ls *), и режим acceptEdits не вызывают его, и правила allow из файлов настроек не видны для проверки.
Слушайте с помощью process.on('warning', ...) и сопоставьте код для логирования или подавления его. Чтобы контролировать каждый вызов инструмента независимо от режима и правил, используйте вместо этого hook PreToolUse.
На этой странице основное внимание уделяется правилам allow и deny и режимам разрешений. Для других шагов:
- Hooks: запустите пользовательский код для разрешения, отклонения или изменения запросов инструментов. См. Управление выполнением с помощью hooks.
- Callback canUseTool: запросите у пользователей утверждение во время выполнения, когда ни один из предыдущих шагов не разрешит вызов. См. Обработка утверждений и ввода пользователя.
Правила allow и deny
allowed_tools и disallowed_tools (TypeScript: allowedTools / disallowedTools) добавляют записи в списки правил allow и deny в потоке оценки выше. Если вы назовёте один из инструментов отслеживания задач в allowed_tools, Claude Code также включает сеанс. Любой другой инструмент, не указанный в allowed_tools, всё ещё доступен для Claude, и вызов к нему, требующий одобрения, переходит к режиму разрешений. Правила deny ведут себя по-разному в зависимости от того, называют ли они инструмент или определяют шаблон в пределах одного.
| Опция | Эффект |
|---|---|
allowed_tools=["Read", "Grep"] |
Read и Grep автоматически одобрены. Другие инструменты, не указанные здесь, всё ещё существуют, и вызовы к ним, требующие одобрения, переходят к режиму разрешений и canUseTool. |
disallowed_tools=["Bash"] |
Определение инструмента Bash удаляется из запроса. Claude не видит инструмент и не может попытаться его использовать. |
disallowed_tools=["Bash(rm *)"] |
Bash остаётся доступным. Вызовы, соответствующие rm * как написано, отклоняются в каждом режиме разрешений, включая bypassPermissions. Другие вызовы Bash, включая /bin/rm, переходят к режиму разрешений. |
disallowed_tools=["*"] |
Каждое определение инструмента удаляется из запроса. Глобы имён инструментов поддерживаются в правилах deny: "*" соответствует каждому инструменту и "mcp__*" соответствует каждому инструменту MCP на всех серверах. |
Правила allow принимают глобы имён инструментов только после буквального префикса mcp__<server>__. Сегмент сервера должен быть свободен от глобов, чтобы правило называло конкретный сервер, который вы настроили: mcp__puppeteer__* соответствует каждому инструменту с сервера puppeteer, и mcp__github__get_* соответствует его инструментам get_. Неякорированная запись, такая как allowed_tools=["*"] или allowed_tools=["mcp__*"], игнорируется с предупреждением при запуске и не одобряет ничего автоматически.
Правила с областью действия для Read и Edit принимают шаблон пути. Правила Edit(path) управляют всеми встроенными инструментами, которые записывают файлы, включая Write и NotebookEdit; правило Write(path) никогда не совпадает с проверками разрешений файлов.
Используйте //path для абсолютного пути файловой системы: правило deny Edit(//secrets/**) блокирует записи в любом месте под /secrets на диске. С одной ведущей косой чертой Edit(/secrets/**) якорируется в источнике правила. Для правил, переданных через allowed_tools или disallowed_tools, это означает рабочий каталог сеанса, поэтому правило не блокирует /secrets на диске. См. Правила Read и Edit для четырёх форм якорей и того, как правила из файлов параметров разрешаются.
Для заблокированного агента объедините allowedTools с permissionMode: "dontAsk":
const options = {
allowedTools: ["Read", "Glob", "Grep"],
permissionMode: "dontAsk"
};
Указанные инструменты одобрены, кроме действий, которые ни один режим не одобряет автоматически, и каждый другой вызов, который бы запросил, вместо этого отклоняется. Вызовы, которые не требуют одобрения в режиме default, выполняются независимо от того, указаны ли они, такие как команды Bash только для чтения, инструменты, такие как Agent, которые не запрашивают перед запуском, и чтение файлов в ваших рабочих каталогах. Чтобы полностью исключить инструмент из досягаемости Claude, добавьте его простое имя в disallowedTools.
Вы также можете настроить правила allow, deny и ask декларативно в .claude/settings.json. Эти правила читаются, когда включен источник параметра project, что происходит для параметров query() по умолчанию. Если вы явно установите setting_sources (TypeScript: settingSources), включите "project", чтобы они применялись. См. Параметры разрешений для синтаксиса правил.
Режимы разрешений
Режимы разрешений обеспечивают глобальный контроль над использованием инструментов Claude. Вы можете установить режим разрешений при вызове query() или изменить его динамически во время сеансов потоковой передачи.
Доступные режимы
SDK поддерживает эти режимы разрешений:
| Режим | Описание | Поведение инструмента |
|---|---|---|
default |
Стандартное поведение разрешений | Без автоматических одобрений; вызовы, требующие одобрения и не совпадающие с правилом разрешения, запускают ваш callback canUseTool |
dontAsk |
Отклонение вместо запроса | Любой вызов, который иначе запросил бы разрешение, отклоняется. Вызовы, одобренные allowed_tools или правилами, работают, как и вызовы, которые не требуют одобрения в режиме default, такие как чтение файлов в рабочих каталогах и вызовы Agent; инструменты соединителя которые ваша организация установила на ask и инструменты, требующие взаимодействия с пользователем, отклоняются даже если вы их предварительно одобрили, как и удаления rm и rmdir, нацеленные на критический путь. canUseTool никогда не вызывается |
acceptEdits |
Автоматическое принятие редактирования файлов | Редактирование файлов и операции с файловой системой (mkdir, rm, mv и т. д.) автоматически одобрены |
bypassPermissions |
Обход проверок разрешений | Инструменты работают без запросов разрешений, кроме действий, которые ни один режим не одобряет автоматически. Используйте с осторожностью |
plan |
Режим планирования | Claude исследует и планирует без редактирования исходных файлов; редактирование файлов никогда не одобряется автоматически и запрашивается через ваш callback canUseTool |
auto |
Одобрения, классифицированные моделью | Классификатор модели одобряет или отклоняет запросы разрешений. См. Режим Auto для доступности |
Установка режима разрешений
Вы можете установить режим разрешений один раз при запуске запроса или изменить его динамически во время активного сеанса.
Передайте permission_mode (Python) или permissionMode (TypeScript) при создании запроса. Этот режим применяется для всего сеанса, если не изменён динамически.
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Help me refactor this code",
options=ClaudeAgentOptions(
permission_mode="default", # Установите режим здесь
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
async function main() {
for await (const message of query({
prompt: "Help me refactor this code",
options: {
permissionMode: "default" // Установите режим здесь
}
})) {
if ("result" in message) {
console.log(message.result);
}
}
}
main();
Вызовите set_permission_mode() (Python) или setPermissionMode() (TypeScript) для изменения режима в середине сеанса. Новый режим вступает в силу немедленно для всех последующих запросов инструментов. Это позволяет вам начать с ограничительного режима и ослабить разрешения по мере развития доверия, например переключиться на acceptEdits после проверки первоначального подхода Claude.
import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
async def main():
async with ClaudeSDKClient(
options=ClaudeAgentOptions(
permission_mode="default", # Начните в режиме по умолчанию
)
) as client:
await client.query("Help me refactor this code")
# Измените режим динамически в середине сеанса
await client.set_permission_mode("acceptEdits")
# Обработайте сообщения с новым режимом разрешений
async for message in client.receive_response():
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
async function main() {
const q = query({
prompt: "Help me refactor this code",
options: {
permissionMode: "default" // Начните в режиме по умолчанию
}
});
// Измените режим динамически в середине сеанса
await q.setPermissionMode("acceptEdits");
// Обработайте сообщения с новым режимом разрешений
for await (const message of q) {
if ("result" in message) {
console.log(message.result);
}
}
}
main();
Детали режимов
Режим принятия редактирования (`acceptEdits`)
Автоматически одобряет операции с файлами, чтобы Claude мог редактировать код без запроса. Другие инструменты (например, команды Bash, которые не являются операциями с файловой системой) по-прежнему требуют обычных разрешений.
Автоматически одобренные операции:
- Редактирование файлов (инструменты Edit, Write)
- Команды файловой системы:
mkdir,touch,rm,rmdir,mv,cp,sed
Оба применяются только к путям внутри рабочего каталога или additionalDirectories. В режиме acceptEdits Claude Code не одобряет запрос автоматически, когда Claude:
- Работает с путём вне этой области
- Записывает в защищённый путь
- Удаляет критический путь с помощью
rmилиrmdir
Используйте, когда: вы доверяете редактированию Claude и хотите более быстрой итерации, например во время прототипирования или при работе в изолированном каталоге.
Режим без запроса (`dontAsk`)
Преобразует любой запрос разрешения в отклонение без вызова canUseTool. Инструменты, предварительно одобренные allowed_tools, правилами разрешения в settings.json или hook, работают нормально, как и вызовы, которые не требуют одобрения в режиме default, такие как чтение файлов в рабочих каталогах и вызовы Agent. Инструменты соединителя которые ваша организация установила на ask, инструменты, требующие взаимодействия с пользователем, и удаления rm и rmdir, нацеленные на критический путь, отклоняются даже если правило разрешения совпадает. Allow hook не очищает удаление критического пути.
Используйте, когда: вы хотите фиксированную, явную поверхность инструментов для автономного агента и предпочитаете жёсткое отклонение молчаливому полаганию на отсутствие canUseTool.
Режим обхода разрешений (`bypassPermissions`)
Автоматически одобряет использование инструментов без запросов, кроме случаев, перечисленных в предупреждении ниже. Hooks всё ещё выполняются и могут блокировать операции при необходимости.
Режим планирования (`plan`)
Claude исследует кодовую базу и создаёт план без редактирования исходных файлов. Инструменты только для чтения работают как в режиме default разрешений.
Редактирование файлов никогда не одобряется автоматически в режиме планирования, даже если правило allow совпадает. Вместо этого они запрашиваются через ваш callback canUseTool. На Claude Code v2.1.212 или позже команды оболочки, которые изменяют файлы, такие как touch и rm, достигают вашего callback canUseTool таким же образом.
Claude может использовать AskUserQuestion для уточнения требований перед завершением плана. См. Обработка утверждений и ввода пользователя для обработки этих запросов.
Используйте, когда: вы хотите, чтобы Claude предложил изменения без их выполнения, например при проверке кода или когда вам нужно одобрить изменения перед их внесением.
Связанные ресурсы
Для других шагов в потоке оценки разрешений:
- Обработка утверждений и ввода пользователя: интерактивные запросы утверждения и уточняющие вопросы
- Руководство по hooks: запуск пользовательского кода в ключевых точках жизненного цикла агента
- Правила разрешений: декларативные правила allow/deny в
settings.json