Развертывание управляемых параметров

​

Развертывание файла управляемых параметров

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "allowManagedPermissionRulesOnly": true
}

​

Выберите механизм доставки

• Элементы управления доставкой: policyHelper, wslInheritsWindowsSettings и managedSourcesBehavior
• Ключи входа Gateway: forceLoginGatewayUrl, gatewayInternalNetworks и значение "gateway" параметра forceLoginMethod

​

Где и когда применяется политика

• Поверхности: на машине разработчика, в терминале, расширениях VS Code и JetBrains, вкладке Code настольного приложения и сеансах Agent SDK читают все эти источники. Сеансы Agent SDK загружают управляемые параметры даже когда settingSources исключает пользовательские, проектные и локальные файлы.
• Облачные сеансы: сеанс в среде, размещённой Anthropic, не читает профиль MDM или файл устройства, поэтому политика для него должна поступать из server-managed settings. Сеанс в самостоятельно размещаемой среде также читает файл управляемых параметров в образе своего runner, по умолчанию только когда server-managed settings не доставляют ключ политики, кроме ключей, которые Claude Code читает из каждого источника администратора. Как Claude Code объединяет управляемые источники охватывает согласие, которое применяется к обоим.
• Сеансы Claude Tag: сеансы Claude Tag работают в облачных средах, но не получают server-managed settings. В самостоятельно размещаемой среде они всё ещё читают файл управляемых параметров в образе runner. Настройте сам Claude Tag в параметрах администратора Claude Tag.
• Сеансы Cowork: Cowork в приложении Claude Desktop запускает свои сеансы на Claude Code. В сеансе Cowork Claude Code никогда не получает server-managed settings из консоли администратора claude.ai, даже когда пользователь входит с учётной записью Team или Enterprise, поэтому то, какая политика применяется, зависит от того, где запускается сеанс:
  • На машине пользователя: по умолчанию Claude Code в сеансе Cowork читает политику MDM или уровня ОС и файл управляемых параметров на этом устройстве, поэтому разверните политику там.
  • В полной песочнице VM: когда ваша управляемая конфигурация Claude Desktop устанавливает requireCoworkFullVmSandbox, Claude Code работает внутри виртуальной машины, где политика MDM устройства и файл управляемых параметров отсутствуют.
  • Удалённые сеансы Cowork: они работают на управляемых Anthropic виртуальных машинах, где Claude Code не имеет политики устройства для чтения.
  Где бы ни запускался сеанс, claude.ai применяет списки strictKnownMarketplaces и blockedMarketplaces консоли администратора сам по себе, когда кто-либо добавляет marketplace из git репозитория на claude.ai или из Customize на вкладке Cowork. Как работают ограничения описывает эту проверку. Таблица покрытия поверхностей сравнивает Cowork с другими поверхностями.
• Запущенные сеансы: большинство изменений достигают запущенного сеанса по расписанию в таблице механизма доставки, без перезагрузки.
  • Изменения forceRemoteSettingsRefresh, requiredMinimumVersion и некоторых редактируемых пользователем ключей вступают в силу при следующем запуске сеанса.
  • Новая или изменённая запись policyHelper вступает в силу при следующем запуске. Если server-managed settings затеняют помощника при этом запуске, помощник запускается как только fetch сообщает об удалении этих параметров.
• Изменения, требующие одобрения: кроме обновлений, которые ждут следующего запуска, изменение server-managed параметра, которое требует одобрения, такого как hook или переменная env, ждёт, пока разработчик примет диалог в интерактивном сеансе, и применяется для текущего запуска в сеансе, который размещает расширение IDE или Agent SDK. Другие изменения server-managed применяются при следующем опросе.
• Долгоживущие сеансы: сеанс, оставленный открытым на недели, всё ещё может отставать от развёртывания. requiredMinimumVersion блокирует запуск устаревшего двоичного файла и не завершает сеанс, который уже работает.

​

Где каждый механизм хранит политику

• Server-managed: серверы Anthropic или ваш шлюз содержат политику. Claude Code хранит локальный кэш, который применяет при запуске и заменяет при каждой успешной выборке.
• Профиль конфигурации macOS: домен управляемых предпочтений com.anthropic.claudecode. Используйте те же ключи верхнего уровня, что и managed-settings.json, с вложенными параметрами как словари и списки как массивы plist.
• Реестр Windows HKLM: JSON как значение REG_SZ или REG_EXPAND_SZ с именем Settings под HKLM\SOFTWARE\Policies\ClaudeCode.
• На основе файла: managed-settings.json, необязательный каталог managed-settings.d/ и managed-mcp.json в системном каталоге: /Library/Application Support/ClaudeCode/ на macOS, /etc/claude-code/ на Linux и WSL, и C:\Program Files\ClaudeCode\ на Windows. Claude Code не читает устаревший путь Windows C:\ProgramData\ClaudeCode\managed-settings.json.
• Реестр Windows HKCU: то же значение Settings под HKCU\SOFTWARE\Policies\ClaudeCode.

​

Разделите политику на основе файла между командами

• Одиночные значения, такие как "model": "opus" или "cleanupPeriodDays": 7: значение более позднего файла заменяет более раннее
• Списки, такие как permissions.deny или sandbox.network.allowedDomains: два списка объединяются, с удалением дубликатов
• Вложенные блоки, такие как env или sandbox: два блока объединяются ключ за ключом, и каждый ключ внутри следует этим же правилам
• fallbackModel: более поздняя цепь полностью заменяет более раннюю
• extraKnownMarketplaces и managedMcpServers: более позднее значение с тем же именем полностью заменяет более раннее
• modelPicker: более поздний набор полностью заменяет более ранний

​

Как Claude Code объединяет управляемые источники

• "first-wins", по умолчанию: Claude Code использует источник с наивысшим рейтингом, который доставляет по крайней мере один ключ политики, и игнорирует остальные, а не объединяет их, за исключением ключей в Ключи, читаемые из каждого источника администратора. Claude Code не показывает предупреждение для источников, которые он пропускает; /status называет источник, который он использовал, и те, которые он пропустил.
• "merge": Claude Code применяет каждый источник администратора, который доставляет ключ политики, и объединяет их по типу ключа: для большинства ключей применяется значение источника с более высоким рейтингом, списки объединяются, а блокировки принимают наиболее строгое значение. Составьте каждый управляемый источник указывает, где установить ключ и как объединяется каждый тип ключа. Требует Claude Code v2.1.242 или позже.

• Ключ политики: любой ключ настроек, кроме двух управляющих ключей, wslInheritsWindowsSettings и managedSourcesBehavior. Файл управляемых настроек или политика MDM, которые содержат только эти ключи, не учитываются, и Claude Code переходит к следующему источнику.
• Источник администратора: один из первых трёх источников ниже. Реестр HKCU доступен для записи пользователем и не является источником администратора.

1. Удалённые настройки, доставленные с claude.ai как настройки, управляемые сервером, или через шлюз приложений Claude. Claude Code получает этот источник только когда сессия аутентифицируется в API Anthropic напрямую с помощью подходящих учётных данных, входит в шлюз с помощью /login или работает на вкладке Code в Claude Desktop за шлюзом, который предоставляет этой сессии настройки. На других поставщиках или когда ANTHROPIC_BASE_URL указывает на что-то другое, чем API Anthropic, он начинает со следующего источника
2. Политики MDM или уровня ОС: plist macOS или ключ реестра HKLM
3. Файлы управляемых настроек, managed-settings.d/*.json и managed-settings.json, объединённые вместе
4. Реестр HKCU в Windows, а также в WSL после того, как реестр HKLM или файл управляемых настроек Windows включит wslInheritsWindowsSettings и значение HKCU тоже задаст его. Claude Code читает его, только когда над ним нет присутствующего документа администратора и никакие родительские настройки, предоставленные хостом, не задают ограничивающий ключ

​

Когда документ администратора считается присутствующим

• Он задаёт любому ключу политики значение, отличное от null, даже если это значение Claude Code не может прочитать
• Это значение HKLM, файл управляемых настроек или каталог managed-settings.d, который существует, но не может быть прочитан

​

Ключи, читаемые из каждого источника администратора

• sandbox.network.allowManagedDomainsOnly и sandbox.filesystem.allowManagedReadPathsOnly: true в любом источнике администратора включает блокировку. Пока блокировка включена, Claude Code объединяет список разрешённых значений, который она блокирует, sandbox.network.allowedDomains вместе с разрешающими правилами WebFetch(domain:...) или sandbox.filesystem.allowRead из каждого источника администратора. Без блокировки Claude Code обрабатывает список разрешённых значений как любой другой ключ, поэтому при "first-wins" список разрешённых значений невыбранного источника администратора игнорируется
• allowAllClaudeAiMcps
• allowManagedMcpServersOnly: true в любом источнике администратора включает блокировку списка разрешённых MCP-серверов. Пока блокировка включена, управляемый список allowedMcpServers поступает из источника администратора с наивысшим рейтингом, который его устанавливает. Список, управляемый сервером, заменяет список нижнего источника, а не объединяется с ним. Если ни один источник администратора не устанавливает список, каждый сервер, который проходит список запрещённых, загружается, если только родительские настройки не предоставляют список. Без блокировки Claude Code читает allowedMcpServers из управляемого источника, который он применяет, поэтому при "first-wins" список невыбранного источника администратора игнорируется. Требует Claude Code v2.1.273 или позже
• deniedMcpServers и disableClaudeAiConnectors: запись или true в любом источнике администратора применяется. Требует Claude Code v2.1.273 или позже
• Пути двоичных файлов песочницы sandbox.bwrapPath и sandbox.socatPath
• Двоичный файл песочницы ripgrep, sandbox.ripgrep
• sandbox.filesystem.disabled и sandbox.network.strictAllowlist
• useAutoModeDuringPlan, syncClaudeAiSkills и syncClaudeAiPlugins, где false из любого источника администратора отключает поведение. false в пользовательских или локальных настройках разработчика также отключает его; каждый ключ может только отрицать
• enableArtifact, где false из любого источника администратора отключает инструмент Artifact. false в пользовательских, проектных или локальных настройках разработчика также отключает его, и ни один источник не включает его обратно; см. какие значения более низкого уровня всё ещё учитываются. Требует Claude Code v2.1.242 или позже
• maxEffortLevel, где применяется наименьший лимит из любого источника администратора. Если разработчик устанавливает более низкий лимит в своих собственных настройках или с помощью --settings, Claude Code применяет этот; ни один источник не может повысить лимит. Требует Claude Code v2.1.267 или позже
• Отказ от трейлера коммита в attribution или в устаревшем includeCoAuthoredBy из любого уровня
• forceRemoteSettingsRefresh
• env, объединённый для каждой переменной из источников администратора: каждая переменная поступает из источника с наивысшим приоритетом, который её определяет, поэтому нижние источники заполняют переменные, которые оставляют неустановленными более высокие. Несколько переменных следуют своим собственным правилам; Исключения для каждого ключа из управляемых источников называет каждое. Требует Claude Code v2.1.223 или позже. До v2.1.223 Claude Code применял только весь блок env выбранного источника

​

Составьте каждый управляемый источник

​

Вычислите политику с помощью вспомогательной программы

• Выданный объект managedSettings — это единственные управляемые настройки для сессии, включая ключи, которые он иначе читает из каждого источника администратора, кроме forceRemoteSettingsRefresh, который имеет своё собственное правило запуска

​

Позвольте хосту встраивания добавить политику

• Когда любой источник администратора устанавливает allowManagedPermissionRulesOnly, Claude Code удаляет предоставленные родителем разрешающие правила и additionalDirectories по мере их чтения, даже когда источник с более высоким приоритетом оставляет ключ неустановленным. Эффект ключа на ваши собственные правила разрешений исходит из управляемых настроек, которые применяет Claude Code, или из родительских настроек, которые вы выбрали для объединения
• Claude Code применяет значение forceLoginOrgUUID или allowedMcpServers в управляемых настройках, которые он применяет, и блокирует предоставленное родителем. Вне блокировки списка разрешённых MCP-серверов значение в нижнем источнике администратора, который Claude Code не применяет, ни применяется, ни блокирует родителя. На Claude Code v2.1.273 или позже, пока allowManagedMcpServersOnly включена, список allowedMcpServers из источника администратора с наивысшим рейтингом, который его устанавливает, применяется и блокирует родителя, как кросс-источниковый ключ. Список родителя применяется только когда ни один источник администратора не устанавливает один. Запись managedSourcesBehavior говорит, какой источник предоставляет каждый ключ при "merge". До v2.1.223 значение в любом источнике администратора блокировало родителя
• Для availableModels Claude Code применяет значение в управляемых настройках, которые он применяет, и блокирует предоставленный родителем список
• Для strictKnownMarketplaces Claude Code аналогично применяет список в управляемых настройках, которые он применяет, и блокирует предоставленный родителем. Список родителя применяется только когда ни один применённый управляемый источник не устанавливает один. Требует Claude Code v2.1.282 или позже
• Для allowedProviders список в выбранном управляемом источнике блокирует предоставленный родителем, а при включённом значении "merge" для managedSourcesBehavior его блокирует список в любом источнике администратора. Требует Claude Code v2.1.285 или позже
• Предоставленный родителем blockedMarketplaces применяется в дополнение к любому списку блокировок, который устанавливает управляемый источник. Требует Claude Code v2.1.282 или позже

​

Сохраните доступ к папке Cowork, когда применяются только управляемые правила

{
  "allowManagedPermissionRulesOnly": true,
  "permissions": {
    "allow": [
      "Edit(~/CoworkProjects/**)"
    ]
  }
}

​

Что может изменить разработчик

• Модель для сессии: управляемая model — это значение по умолчанию, а не блокировка. --model и ANTHROPIC_MODEL всё ещё выбирают модель для этой сессии, поэтому развёртывайте availableModels для ограничения выбора.
• Окно автосжатия для сессии: управляемый autoCompactWindow — тоже значение по умолчанию. Флаг --autocompact и переменная CLAUDE_CODE_AUTO_COMPACT_WINDOW всё ещё задают окно автосжатия для этой сессии.
• Локальные права администратора: разработчик, который является администратором на машине, может редактировать сам управляемый источник, поэтому инструменты MDM могут переразвёртывать профиль или файл по расписанию и почему существуют реестр HKLM и домен управляемых предпочтений macOS.
• Кэш, управляемый сервером: настройки, управляемые сервером, поступают с серверов Anthropic, и редактирование локального кэша длится только до следующей успешной выборки.
• Другие инструменты: управляемые настройки привязывают только Claude Code. Разработчик, который вызывает API из другого инструмента, не подчиняется им.

​

Проверьте, что политика действует

​

Прочитайте источник в /status

• (remote): управляемые сервером настройки из claude.ai или шлюза
• (plist) или (HKLM): политика MDM или ОС
• (file), (drop-ins) или (file + drop-ins): managed-settings.json, каталог drop-in или оба
• (remote + file, merged) или другой список, заканчивающийся на , merged: ваша организация объединяет каждый управляемый источник, и Claude Code объединил перечисленные источники в политику. Нижний источник всё ещё может предоставлять переменные env без появления в списке. Требуется Claude Code v2.1.242 или позже
• (HKCU): резервный вариант реестра, доступный для записи пользователем
• (parent process): хост встраивания предоставил ограничивающие настройки
• (helper): policyHelper, настроенный выбранным источником MDM или файла

• Строка отсутствует: Claude Code не нашёл управляемый источник, который доставляет ключ политики. Если вы развернули файл управляемых настроек, проверьте, что он находится по пути для ОС и что он содержит ключ политики, а не только ключи управления. Файл, который не является допустимым JSON, не создаёт это состояние; вместо этого Claude Code отказывается запускаться. Если вместо этого вы развернули через управляемые сервером настройки, запустите claude doctor, который сообщает результат получения.
• Строка называет источник, отличный от того, который вы развернули: присутствует источник с более высоким приоритетом, и Claude Code проигнорировал ваш, а Skipped sources его перечисляет. Как Claude Code объединяет управляемые источники описывает порядок.

​

Найдите записи, которые Claude Code отбросил

• Файл управляемых настроек или файл drop-in: файл не является допустимым JSON или его верхний уровень не является объектом
• MDM plist: plutil macOS сообщает, что plist неправильно сформирован, или его преобразованное содержимое не является объектом JSON
• Значение реестра HKLM: значение Settings не является строкой, пусто или не содержит объект JSON

• Отсутствующий файл, профиль или значение реестра не является сбоем; Claude Code работает без этого источника.
• Пустой файл управляемых настроек считается {}.
• Неправильное значение в доступном для записи пользователем ключе реестра HKCU никогда не блокирует запуск. Вместо этого Claude Code сообщает об этом как уведомление в /status и claude doctor.

• Если операционная система отказала в чтении, например для файла, доступного только root, каждая сессия запускается без политик этого источника. /status и claude doctor записывают сбой, а запуск с -p также выводит его в stderr.
• При любом другом сбое чтения, например ошибке ввода-вывода, каждая сессия завершается при запуске с сообщением о необходимости связаться с администратором.

• Интерактивные сессии показывают диалоговое окно при запуске, в котором перечислены неправильные записи.
• Неинтерактивные запуски с -p выводят сводку в stderr.
• claude doctor перечисляет каждую неправильную запись с её источником и полем.

​

Ключи, которые не проходят закрыто

• null удаляет ключ.
• Неправильный disableAllHooks, даже логическое значение в кавычках, отбрасывается с предупреждением, потому что применение true также выгрузило бы хуки, которые развёртывают ваши собственные управляемые настройки.
• Для каждого другого логического ключа, который охватывает правило, строка "true" или "false" читается как соответствующее логическое значение, с уведомлением в /status, предлагающим вам удалить кавычки.

• Блокировка внутри одного из них, такая как permissions.disableBypassPermissionsMode, читается как её ограничивающее значение.
• Неправильный permissions.defaultMode читается как default.
• Пока список deny или ask в permissions вообще не может быть прочитан, Claude Code удерживает allow и additionalDirectories, поэтому разрешения никогда не применяются без ограничений, записанных рядом с ними. Отчёт называет каждое удержанное разрешение и список, который не удалось прочитать.
• В autoMode список soft_deny или hard_deny, который не может быть прочитан или потерял неправильную запись, таким же образом удерживает allow и environment.

​

Неправильные значения внутри sandbox

• Если вы установите логический ключ в "true" или "false" в кавычках, значение считается соответствующим логическим значением. Вместо предупреждения /status показывает уведомление, предлагающее вам удалить кавычки.
• Если failIfUnavailable неправилен, Claude Code отбрасывает значение, а не рассматривает его как true, поэтому нечитаемое значение никогда не мешает запуску сессий во всём вашем парке.
• Каждое другое неправильное логическое значение Claude Code рассматривает как значение, которое сохраняет песочницу максимально строгой, пока вы его не исправите. Ключ, который включает песочницу или одно из её ограничений, например enabled или network.allowManagedDomainsOnly, считается true. Ключ, который ослабляет её, например allowUnsandboxedCommands, считается false.
• В списке вне credentials, таком как excludedCommands или network.allowedDomains, Claude Code отбрасывает неправильную запись и сохраняет остальную часть списка. Список, который не является массивом или не имеет ни одной допустимой записи, вообще не применяется.
• Пока network.deniedDomains или любая запись в нём неправильны, Claude Code также удерживает network.allowedDomains, поэтому управляемый список разрешённых доменов ничего не разрешает, пока вы не исправите список запрещённых.
• Пока filesystem.denyRead, filesystem.denyWrite или любая запись в любом из них неправильны, Claude Code также удерживает и filesystem.allowRead, и filesystem.allowWrite, пока вы не исправите список запрещённых.

​

Ключи, которые может установить только управляемый источник

​

Отключите телеметрию для вашей организации

{
  "env": {
    "DISABLE_TELEMETRY": "1"
  }
}

​

Смотрите также

• Настройте Claude Code для вашей организации: решите, что применять и как
• Управляемые параметры сервера: доставляйте политику из консоли claude.ai или шлюза
• Управляемая конфигурация MCP: контролируйте, какие MCP серверы могут использовать разработчики
• Все параметры: каждый ключ, с указанием, может ли управляемый источник его установить
• Примеры файлов параметров: полный managed-settings.json, показывающий форму управляемых ключей