Implementar configuración administrada

​

Implementar un archivo de configuración administrada

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

​

Elegir un mecanismo de entrega

• Controles de entrega: policyHelper, wslInheritsWindowsSettings y managedSourcesBehavior
• Claves de inicio de sesión de puerta de enlace: forceLoginGatewayUrl y el valor "gateway" de forceLoginMethod

​

Dónde y cuándo se aplica una política

• Superficies: en la máquina del desarrollador, la terminal, las extensiones de VS Code y JetBrains, la pestaña Code de la aplicación de escritorio y las sesiones de Agent SDK leen todas estas fuentes. Las sesiones de Agent SDK cargan la configuración administrada incluso cuando settingSources excluye los archivos de usuario, proyecto y local.
• Sesiones en la nube: una sesión en un entorno alojado por Anthropic no lee un perfil MDM o archivo de dispositivo, por lo que la política para ella debe provenir de la configuración administrada por servidor. Una sesión en un entorno autohospedado también lee el archivo de configuración administrada en su imagen de ejecutor, por defecto solo cuando la configuración administrada por servidor no entrega una clave de política, aparte de las claves que Claude Code lee de cada fuente de administrador. Cómo Claude Code combina fuentes administradas cubre la opción de participación que aplica ambas.
• Sesiones de Cowork: Cowork en la aplicación Claude Desktop ejecuta sus sesiones en Claude Code. En una sesión de Cowork, Claude Code nunca obtiene la configuración administrada por servidor de la consola de administración de claude.ai, incluso cuando el usuario inicia sesión con una cuenta de Team o Enterprise, por lo que la política que se aplica depende de dónde se ejecute la sesión:
  • En la máquina del usuario: por defecto, Claude Code en una sesión de Cowork lee la política MDM o a nivel de SO y el archivo de configuración administrada en ese dispositivo, así que implemente la política allí.
  • En un sandbox de VM completa: cuando su configuración administrada de Claude Desktop establece requireCoworkFullVmSandbox, Claude Code se ejecuta dentro de una máquina virtual donde la política MDM del dispositivo y el archivo de configuración administrada no están presentes.
  • Sesiones remotas de Cowork: se ejecutan en máquinas virtuales administradas por Anthropic, donde Claude Code no tiene política de dispositivo para leer.
  La tabla cobertura de superficie compara Cowork con las otras superficies.
• Sesiones en ejecución: una sesión recoge la mayoría de los cambios en el cronograma de la tabla sin un reinicio. Claude Code lee forceRemoteSettingsRefresh y requiredMinimumVersion solo al inicio de la sesión, arma una entrada policyHelper nueva o cambiada en el próximo lanzamiento, y lee algunas claves editables por el usuario una sola vez al inicio de la sesión.
• Cambios que necesitan aprobación: aparte de las actualizaciones que esperan el próximo lanzamiento, un cambio administrado por servidor en una configuración que necesita aprobación, como un hook o una variable env, espera a que el desarrollador acepte el diálogo en una sesión interactiva, y se aplica para la ejecución actual en una sesión que una extensión IDE o el Agent SDK aloja. Otros cambios administrados por servidor se aplican en el próximo sondeo.
• Sesiones de larga duración: una sesión dejada abierta durante semanas aún puede retrasarse en un despliegue. requiredMinimumVersion bloquea un binario desactualizado de iniciarse y no termina una sesión que ya se está ejecutando.

​

Dónde cada mecanismo almacena la política

• Administrada por servidor: los servidores de Anthropic, o su puerta de enlace, mantienen la política. Claude Code mantiene una caché local que aplica al inicio y reemplaza en cada obtención exitosa.
• Perfil de configuración de macOS: el dominio de preferencias administradas com.anthropic.claudecode. Use las mismas claves de nivel superior que managed-settings.json, con configuraciones anidadas como diccionarios y listas como matrices plist.
• Registro HKLM de Windows: el JSON como un valor REG_SZ o REG_EXPAND_SZ llamado Settings bajo HKLM\SOFTWARE\Policies\ClaudeCode.
• Basado en archivo: managed-settings.json, un directorio opcional managed-settings.d/ y managed-mcp.json en el directorio del sistema: /Library/Application Support/ClaudeCode/ en macOS, /etc/claude-code/ en Linux y WSL, y C:\Program Files\ClaudeCode\ en Windows. Claude Code no lee la ruta heredada de Windows C:\ProgramData\ClaudeCode\managed-settings.json.
• Registro HKCU de Windows: el mismo valor Settings bajo HKCU\SOFTWARE\Policies\ClaudeCode.

​

Dividir una política basada en archivo entre equipos

• Valores únicos, como "model": "opus" o "cleanupPeriodDays": 7: el valor del archivo posterior reemplaza al anterior
• Listas, como permissions.deny o sandbox.network.allowedDomains: las dos listas se combinan, con duplicados eliminados
• Bloques anidados, como env o sandbox: los dos bloques se fusionan clave por clave, y cada clave dentro sigue estas mismas reglas
• fallbackModel: la cadena posterior reemplaza la anterior completamente
• extraKnownMarketplaces: una entrada posterior con el mismo nombre reemplaza la anterior completamente
• modelPicker: la alineación posterior reemplaza la anterior completamente

​

Cómo Claude Code combina fuentes administradas

• "first-wins", el predeterminado: Claude Code usa la fuente de mayor rango que entrega al menos una clave de política e ignora el resto en lugar de fusionarlas, aparte de las pocas claves en Claves leídas de cada fuente de administrador. Claude Code no muestra advertencia para las fuentes que omite; /status nombra la fuente que usó y las que omitió.
• "merge": Claude Code aplica cada fuente de administrador que entrega una clave de política y las combina por tipo de clave: en la mayoría de las claves el valor de la fuente de mayor rango se aplica, las listas se unen y los bloqueos toman el valor más restrictivo. Componer cada fuente administrada dice dónde establecer la clave y cómo se combina cada tipo de clave. Requiere Claude Code v2.1.242 o posterior.

• Clave de política: cualquier clave de configuración que no sea las dos claves de control, wslInheritsWindowsSettings y managedSourcesBehavior. Un archivo de configuración administrada o política MDM que contiene solo esas no cuenta, y Claude Code pasa a la siguiente fuente.
• Fuente de administrador: una de las primeras tres fuentes a continuación. El registro HKCU que se puede escribir por el usuario no es una.

1. Configuración remota, entregada desde claude.ai como configuración administrada por servidor o por una puerta de enlace de aplicaciones Claude. Claude Code obtiene esta fuente solo cuando la sesión se autentica en la API de Anthropic directamente con un inicio de sesión o clave elegible, o inicia sesión en una puerta de enlace con /login. En otros proveedores, o cuando ANTHROPIC_BASE_URL apunta a otro lugar que no sea la API de Anthropic, comienza en la siguiente fuente
2. Políticas MDM o a nivel de SO: la plist de macOS o la clave de registro HKLM
3. Archivos de configuración administrada, managed-settings.d/*.json y managed-settings.json fusionados juntos
4. El registro HKCU, en Windows, y en WSL una vez que el registro HKLM o el archivo de configuración administrada de Windows activa wslInheritsWindowsSettings y el valor HKCU también lo establece. Claude Code lo lee solo cuando ninguna fuente anterior entrega una clave de política y ninguna configuración principal suministrada por el host proporciona una clave restrictiva

​

Claves leídas de cada fuente de administrador

• sandbox.network.allowManagedDomainsOnly y sandbox.filesystem.allowManagedReadPathsOnly: un true en cualquier fuente de administrador activa el bloqueo. Mientras un bloqueo está activo, Claude Code une la lista de permitidos que bloquea, sandbox.network.allowedDomains junto con reglas de permitidos WebFetch(domain:...), o sandbox.filesystem.allowRead, en cada fuente de administrador. Sin el bloqueo, Claude Code trata la lista de permitidos como cualquier otra clave, por lo que bajo "first-wins" la lista de permitidos de una fuente de administrador no seleccionada se ignora
• allowAllClaudeAiMcps
• Las rutas binarias de sandbox sandbox.bwrapPath y sandbox.socatPath
• El binario ripgrep de sandbox, sandbox.ripgrep
• sandbox.filesystem.disabled y sandbox.network.strictAllowlist
• useAutoModeDuringPlan y syncClaudeAiSkills, donde un false de cualquier fuente de administrador desactiva el comportamiento. Un false en la configuración de usuario o local del desarrollador también lo desactiva; cada clave solo puede negar
• enableArtifact, donde un false de cualquier fuente de administrador desactiva la herramienta Artifact. Un false en la configuración de usuario, proyecto o local del desarrollador también lo desactiva, y ninguna fuente lo vuelve a activar; consulte qué valores de nivel inferior aún cuentan. Requiere Claude Code v2.1.242 o posterior
• Un rechazo de remolque de confirmación en attribution, o en el includeCoAuthoredBy deprecado, de cualquier nivel
• forceRemoteSettingsRefresh
• env, fusionado por variable en las fuentes de administrador: cada variable viene de la fuente de mayor prioridad que la define, por lo que las fuentes inferiores llenan variables que las superiores dejan sin establecer. Algunas variables siguen sus propias reglas; Excepciones por clave en fuentes administradas nombra cada una. Requiere Claude Code v2.1.223 o posterior. Antes de v2.1.223, Claude Code aplicaba solo el bloque env completo de la fuente seleccionada

​

Componer cada fuente administrada

​

Calcular la política con un programa auxiliar

• El objeto managedSettings emitido es la única configuración administrada para la sesión, incluido para las claves que de otro modo lee de cada fuente de administrador, aparte de forceRemoteSettingsRefresh, que Claude Code verifica en cada fuente de administrador al inicio antes de que se ejecute el auxiliar. Para qué ejecuciones de auxiliar fallan y qué hace Claude Code cuando una lo hace, consulte Fallos de auxiliar

​

Permitir que un host de incrustación agregue política

• Cuando cualquier fuente de administrador establece allowManagedPermissionRulesOnly, Claude Code descarta reglas de permitidos de permisos suministradas por el padre y additionalDirectories mientras las lee, incluso cuando una fuente de mayor prioridad deja la clave sin establecer. El efecto de la clave en sus propias reglas de permisos proviene de la configuración administrada que Claude Code aplica, o de la configuración principal que ha elegido fusionar
• Claude Code aplica el valor forceLoginOrgUUID o allowedMcpServers en la configuración administrada que aplica y bloquea uno suministrado por el padre. Un valor en una fuente de administrador inferior que Claude Code no aplica ni se aplica ni bloquea el del padre. La entrada managedSourcesBehavior dice qué fuente proporciona cada clave bajo "merge". Antes de v2.1.223, un valor en cualquier fuente de administrador bloqueaba el del padre
• Un valor availableModels sigue la misma regla que allowedMcpServers

​

Mantener el acceso a la carpeta de Cowork cuando solo se aplican reglas administradas

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

​

Lo que un desarrollador puede cambiar

• El modelo para una sesión: un model administrado es un predeterminado, no un bloqueo. --model y ANTHROPIC_MODEL aún eligen el modelo para esa sesión, así que implemente availableModels para restringir la opción.
• Derechos de administrador local: un desarrollador que es administrador en la máquina puede editar la fuente administrada en sí, por lo que el tooling MDM puede reimplementar el perfil o archivo en un cronograma y por lo que existen el registro HKLM y el dominio de preferencias administradas de macOS.
• La caché administrada por servidor: la configuración administrada por servidor proviene de los servidores de Anthropic, y una edición a la caché local dura solo hasta la próxima obtención exitosa.
• Otras herramientas: la configuración administrada vincula solo Claude Code. Un desarrollador que llama a la API desde otra herramienta no está bajo ellas.

​

Verificar que una política está en vigor

​

Leer la fuente en /status

• (remote): configuración administrada por servidor desde claude.ai o una puerta de enlace
• (plist) o (HKLM): una política MDM u OS
• (file), (drop-ins) o (file + drop-ins): managed-settings.json, el directorio de complementos o ambos
• (remote + file, merged) u otra lista que termina en , merged: su organización compone cada fuente administrada, y Claude Code fusionó las fuentes enumeradas en la política. Una fuente inferior aún puede proporcionar variables env sin aparecer en la lista. Requiere Claude Code v2.1.242 o posterior
• (HKCU): el registro de reserva que se puede escribir por el usuario
• (parent process): un host de incrustación proporcionó configuración restrictiva
• (helper): un policyHelper configurado por la fuente MDM o de archivo seleccionada

• La línea falta: Claude Code no encontró ninguna fuente administrada que entregue una clave de política. Si implementó un archivo de configuración administrada, verifique que se encuentre en la ruta del SO y que contenga una clave de política en lugar de solo las claves de control. Un archivo que no es JSON válido no produce este estado; Claude Code se niega a iniciar en su lugar. Cuando implementó a través de configuración administrada por servidor en su lugar, ejecute claude doctor, que reporta el resultado de obtención.
• La línea nombra una fuente que no es la que implementó: una fuente de mayor prioridad está presente y Claude Code ignoró la suya, y Skipped sources la enumera. Cómo Claude Code combina fuentes administradas da el orden.

​

Encontrar entradas que Claude Code descartó

• Archivo de configuración administrada o archivo de complemento: el archivo no es JSON válido, o su nivel superior no es un objeto
• Plist MDM: plutil de macOS reporta la plist malformada, o su contenido convertido no es un objeto JSON
• Valor de registro HKLM: el valor Settings no es una cadena, está vacío o no contiene un objeto JSON

• Un archivo, perfil o valor de registro ausente no es un fallo; Claude Code se ejecuta sin esa fuente.
• Un archivo de configuración administrada vacío cuenta como {}.
• Un valor malformado en la clave de registro HKCU que se puede escribir por el usuario nunca bloquea el lanzamiento. Claude Code lo reporta como un aviso en /status y claude doctor en su lugar.

• Las sesiones interactivas muestran un diálogo al inicio que enumera las entradas inválidas.
• Las ejecuciones no interactivas con -p imprimen un resumen a stderr.
• claude doctor enumera cada entrada inválida con su fuente y campo.

​

Claves que fallan cerradas

​

Claves que solo una fuente administrada puede establecer

​

Desactivar la telemetría para su organización

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

​

Ver también

• Configurar Claude Code para su organización: decidir qué aplicar y cómo
• Configuración administrada por servidor: entregar política desde la consola de claude.ai o una puerta de enlace
• Configuración MCP administrada: controlar qué servidores MCP pueden usar los desarrolladores
• Toda la configuración: cada clave, con si una fuente administrada puede establecerla
• Archivos de configuración de ejemplo: un managed-settings.json completo que muestra la forma de las claves administradas