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, gatewayInternalNetworks 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 ninguna 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 Claude Tag: las sesiones de Claude Tag se ejecutan en entornos en la nube pero no reciben configuración administrada por servidor. En un entorno autohospedado, aún leen el archivo de configuración administrada en la imagen del ejecutor. Configure Claude Tag en los ajustes de administrador de Claude Tag.
• 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.
  Dondequiera que se ejecute la sesión, claude.ai aplica por sí mismo las listas strictKnownMarketplaces y blockedMarketplaces de la consola de administración cuando alguien agrega un marketplace desde un repositorio de git en claude.ai o desde Personalizar en Cowork. Cómo funcionan las restricciones describe esa verificación. La tabla cobertura de superficie compara Cowork con las otras superficies.
• Sesiones en ejecución: la mayoría de los cambios llegan a una sesión en ejecución en el cronograma de la tabla de mecanismo de entrega, sin un reinicio.
  • Los cambios a forceRemoteSettingsRefresh, requiredMinimumVersion y algunas claves editables por el usuario surten efecto en el próximo inicio de sesión.
  • Una entrada policyHelper nueva o cambiada surte efecto en el próximo lanzamiento. Si la configuración administrada por servidor sombrea el asistente en ese lanzamiento, el asistente se ejecuta tan pronto como una obtención informa que esa configuración se ha eliminado.
• 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. Puedes implementar cualquiera de estos archivos como un enlace simbólico, y Claude Code lee el archivo al que apunta el enlace. La política se sigue aplicando cuando el enlace apunta fuera del directorio del sistema o Claude Code no puede confirmar que permanece dentro. En ese caso, aparece una advertencia que nombra el archivo en /status y claude doctor. Para eliminar la advertencia, apunta el enlace a un destino dentro del directorio del sistema.
• 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 y managedMcpServers: 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 valor predeterminado: Claude Code utiliza la fuente con mayor rango que entrega al menos una clave de política e ignora el resto en lugar de combinarlas, aparte de las claves en Claves leídas de cada fuente de administrador. Claude Code no muestra ninguna advertencia para las fuentes que omite; /status nombra la fuente que utilizó 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 se aplica el valor de la fuente con mayor rango, 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 una de las dos claves de control, wslInheritsWindowsSettings y managedSourcesBehavior. Un archivo de configuración administrada o una política MDM que contenga solo esas no cuenta, y Claude Code pasa a la siguiente fuente.
• Fuente de administrador: una de las tres primeras fuentes a continuación. El registro HKCU es escribible por el usuario y no es una.

1. Configuración remota, entregada desde claude.ai como configuración administrada por servidor o por un gateway de aplicaciones Claude. Claude Code obtiene esta fuente solo cuando la sesión se autentica en la API de Anthropic directamente con una credencial elegible, inicia sesión en un gateway con /login, o se ejecuta en la pestaña Code de Claude Desktop detrás de un gateway que sirve configuración a esa sesión. En otros proveedores, o cuando ANTHROPIC_BASE_URL apunta a algún lugar que no sea la API de Anthropic, comienza en la siguiente fuente
2. Políticas de MDM o de nivel del SO: el plist de macOS o la clave de registro HKLM
3. Archivos de configuración administrada, managed-settings.d/*.json y managed-settings.json combinados
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 no hay ningún documento de administrador presente por encima de él y ninguna configuración principal suministrada por el host suministra una clave restrictiva

​

Cuándo un documento de administrador cuenta como presente

• Establece cualquier clave de política en un valor que no sea null, incluso un valor que Claude Code no puede leer
• Es un valor HKLM, un archivo de configuración administrada o un directorio managed-settings.d que existe pero no se puede leer

​

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 allow WebFetch(domain:...), o sandbox.filesystem.allowRead, en todas las fuentes de administrador. Sin el bloqueo, Claude Code trata la lista de permitidos como cualquier otra clave, por lo que con "first-wins" la lista de permitidos de una fuente de administrador no seleccionada se ignora
• allowAllClaudeAiMcps
• allowManagedMcpServersOnly: un true en cualquier fuente de administrador activa el bloqueo de la lista de servidores MCP permitidos. Mientras el bloqueo está activo, la lista allowedMcpServers administrada proviene de la fuente de administrador con mayor rango que establece una. Una lista administrada por servidor reemplaza la lista de una fuente inferior en lugar de combinarse con ella. Si ninguna fuente de administrador establece una lista, se carga cada servidor que pase la lista de denegados, a menos que la configuración principal suministre una lista. Sin el bloqueo, Claude Code lee allowedMcpServers de la fuente administrada que aplica, por lo que con "first-wins" la lista de una fuente de administrador no seleccionada se ignora. Requiere Claude Code v2.1.273 o posterior
• deniedMcpServers y disableClaudeAiConnectors: se aplica una entrada o un true en cualquier fuente de administrador. Requiere Claude Code v2.1.273 o posterior
• 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, syncClaudeAiSkills y syncClaudeAiPlugins, 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 denegar
• enableArtifact, donde un false de cualquier fuente de administrador desactiva la herramienta Artifact. Un false en la configuración de usuario, de proyecto o local del desarrollador también la desactiva, y ninguna fuente la vuelve a activar; consulta qué valores de nivel inferior aún cuentan. Requiere Claude Code v2.1.242 o posterior
• maxEffortLevel, donde se aplica el límite más bajo de cualquier fuente de administrador. Si un desarrollador establece un límite más bajo en su propia configuración o con --settings, Claude Code aplica ese; ninguna fuente puede aumentar el límite. Requiere Claude Code v2.1.267 o posterior
• Una exclusión del trailer de commit en attribution, o en el obsoleto includeCoAuthoredBy, desde cualquier nivel
• forceRemoteSettingsRefresh
• env, combinado por variable en las fuentes de administrador: cada variable proviene de la fuente de mayor prioridad que la define, por lo que las fuentes inferiores completan las 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, incluso para las claves que de otro modo lee de cada fuente de administrador, aparte de forceRemoteSettingsRefresh, que tiene su propia regla de inicio

​

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

• Cuando cualquier fuente de administrador establece allowManagedPermissionRulesOnly, Claude Code descarta las reglas allow de permisos suministradas por el host principal y additionalDirectories a medida que las lee, incluso cuando una fuente de mayor prioridad deja la clave sin establecer. El efecto de la clave en tus propias reglas de permisos proviene de la configuración administrada que Claude Code aplica, o de la configuración principal que hayas elegido combinar
• Claude Code aplica el valor forceLoginOrgUUID o allowedMcpServers de la configuración administrada que aplica y bloquea uno suministrado por el host principal. Fuera del bloqueo de la lista de servidores MCP permitidos, un valor en una fuente de administrador inferior que Claude Code no aplica ni se aplica ni bloquea el del host principal. En Claude Code v2.1.273 o posterior, mientras allowManagedMcpServersOnly está activo, la lista allowedMcpServers de la fuente de administrador con mayor rango que establece una se aplica y bloquea la del host principal, como clave entre fuentes. La lista del host principal se aplica solo cuando ninguna fuente de administrador establece una. La entrada managedSourcesBehavior dice qué fuente suministra cada clave con "merge". Antes de v2.1.223, un valor en cualquier fuente de administrador bloqueaba el del host principal
• Para availableModels, Claude Code aplica el valor de la configuración administrada que aplica y bloquea una lista suministrada por el host principal
• Para strictKnownMarketplaces, Claude Code asimismo aplica la lista de la configuración administrada que aplica y bloquea una suministrada por el host principal. La lista del host principal se aplica solo cuando ninguna fuente administrada aplicada establece una. Requiere Claude Code v2.1.282 o posterior
• Para allowedProviders, una lista en la fuente administrada seleccionada bloquea una suministrada por el host principal, y con la opción "merge" de managedSourcesBehavior lo hace una lista en cualquier fuente de administrador. Requiere Claude Code v2.1.285 o posterior
• Un blockedMarketplaces suministrado por el host principal se aplica además de cualquier lista de denegados que establezca una fuente administrada. Requiere Claude Code v2.1.282 o posterior

​

Mantener el acceso a las carpetas 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 valor predeterminado, no un bloqueo. --model y ANTHROPIC_MODEL aún seleccionan el modelo para esa sesión, así que implementa availableModels para restringir la elección.
• La ventana de compactación automática para una sesión: un autoCompactWindow administrado también es un valor predeterminado. El flag --autocompact y la variable CLAUDE_CODE_AUTO_COMPACT_WINDOW aún establecen la ventana de compactación automática para esa sesión.
• Derechos de administrador local: un desarrollador que es administrador en la máquina puede editar la propia fuente administrada; por eso las herramientas MDM pueden volver a implementar el perfil o el archivo de forma programada, y por eso existen el registro HKLM y el dominio de preferencias administradas de macOS.
• La caché de configuración administrada por servidor: la configuración administrada por servidor proviene de los servidores de Anthropic, y una edición en la caché local dura solo hasta la siguiente obtención exitosa.
• Otras herramientas: la configuración administrada solo se aplica a Claude Code. Un desarrollador que llama a la API desde otra herramienta no está sujeto a ella.

​

Verificar que una política está en vigor

​

Leer la fuente en /status

• (remote): configuración administrada por servidor desde claude.ai o un gateway
• (plist) o (HKLM): una política MDM o del sistema operativo
• (file), (drop-ins) o (file + drop-ins): managed-settings.json, el directorio drop-in o ambos
• (remote + file, merged) u otra lista que termina en , merged: tu organización compone cada fuente administrada, y Claude Code combinó 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 respaldo que el usuario puede escribir
• (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 implementaste un archivo de configuración administrada, verifica que se encuentre en la ruta del sistema operativo 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; en su lugar, Claude Code se niega a iniciar. Si en cambio implementaste a través de configuración administrada por servidor, ejecuta claude doctor, que reporta el resultado de obtención.
• La línea nombra una fuente que no es la que implementaste: una fuente de mayor prioridad está presente y Claude Code ignoró la tuya, 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 drop-in: 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 el usuario puede escribir, nunca bloquea el lanzamiento. En su lugar, Claude Code lo reporta como un aviso en /status y claude doctor.

• Si el sistema operativo denegó la lectura, por ejemplo en un archivo de solo root, cada sesión se inicia sin las políticas de esa fuente. /status y claude doctor registran el fallo, y una ejecución con -p también lo imprime en stderr.
• Para cualquier otro fallo de lectura, como un error de E/S, cada sesión sale al inicio con un mensaje para contactar a un administrador.

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

​

Claves que fallan cerradas

• Un null elimina la clave.
• Un disableAllHooks inválido, incluso un booleano entrecomillado, se descarta con una advertencia, porque aplicar true también descargaría los hooks que tu propia configuración administrada implementa.
• Para cualquier otra clave booleana que cubre la regla, la cadena "true" o "false" se lee como ese booleano, con un aviso en /status que te pide eliminar las comillas.

• Un bloqueo dentro de uno, como permissions.disableBypassPermissionsMode, se lee como su valor restrictivo.
• Un permissions.defaultMode inválido se lee como default.
• Mientras una lista deny o ask en permissions no se pueda leer en absoluto, Claude Code retiene allow y additionalDirectories, por lo que las concesiones nunca se aplican sin las restricciones escritas a su lado. El informe nombra cada concesión retenida y la lista que no se pudo leer.
• En autoMode, una lista soft_deny o hard_deny que no se puede leer, o que perdió una entrada inválida, retiene allow y environment de la misma manera.

​

Valores inválidos dentro de sandbox

• Si estableces una clave booleana en un "true" o "false" entrecomillado, el valor cuenta como ese booleano. En lugar de una advertencia, /status muestra un aviso que te pide eliminar las comillas.
• Si failIfUnavailable es inválido, Claude Code descarta el valor en lugar de tratarlo como true, por lo que un valor ilegible nunca impide que se inicien sesiones en toda tu flota.
• Claude Code trata cualquier otro booleano inválido como el valor que mantiene el sandbox más estricto hasta que lo corrijas. Una clave que activa el sandbox o una de sus restricciones, como enabled o network.allowManagedDomainsOnly, cuenta como true. Una clave que lo flexibiliza, como allowUnsandboxedCommands, cuenta como false.
• En una lista fuera de credentials, como excludedCommands o network.allowedDomains, Claude Code descarta una entrada inválida y mantiene el resto de la lista. Una lista que no es una matriz, o que no tiene ninguna entrada válida, no se aplica en absoluto.
• Mientras network.deniedDomains o cualquier entrada en ella sea inválida, Claude Code también retiene network.allowedDomains, por lo que la lista de dominios permitidos administrada no otorga nada hasta que corrijas la lista de denegación.
• Mientras filesystem.denyRead, filesystem.denyWrite o cualquier entrada en alguna de ellas sea inválida, Claude Code también retiene tanto filesystem.allowRead como filesystem.allowWrite hasta que corrijas la lista de denegación.

​

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