settings.json : Référence complète de la configuration

Les 5 niveaux de configuration

Claude Code résout la configuration finale en fusionnant cinq sources, du plus prioritaire au moins prioritaire. Quand une option est définie à plusieurs niveaux, c'est toujours la valeur du niveau le plus haut qui s'applique.

Niveau 1 : Managed settings

Les managed settings sont déployés par un administrateur Anthropic depuis le dashboard de l'organisation. Ils s'appliquent à tous les membres, quelle que soit leur configuration locale.

Cas d'usage typiques :

• Imposer un modèle précis à toute l'équipe
• Interdire des outils jugés risqués (Bash, WebFetch)
• Forcer un proxy d'entreprise via customApiUrl

L'utilisateur ne peut pas les surcharger, même avec un argument CLI ou un fichier local.

Niveau 2 : Arguments CLI

Les flags passés directement à la commande claude ont la deuxième priorité. Ils sont utiles pour des sessions ponctuelles sans toucher aux fichiers de configuration.

# Utiliser Opus pour cette session uniquement
claude --model claude-opus-4-5

# Désactiver un outil pour cette invocation
claude --disallowedTools Bash

# Spécifier un fichier de configuration différent
claude --settings /chemin/vers/settings.json

Niveaux 3 à 5 : Fichiers de configuration

Les trois niveaux restants correspondent à des fichiers JSON. Ils sont fusionnés au démarrage de chaque session.

Structure complète annotée

{
  // Modèle par défaut pour toutes les sessions
  "model": "claude-sonnet-4-6",

  // Activation de l'Extended Thinking
  "alwaysThinkingEnabled": false,

  // Compactage automatique du contexte
  "autoCompact": true,

  // Fournisseur d'API (anthropic par défaut)
  "apiProvider": "anthropic",

  // URL d'API personnalisée (proxies, bedrock, vertex)
  "customApiUrl": "https://api.anthropic.com",

  // Permissions globales par outil
  "permissions": {
    "allow": ["Bash(git:*)", "Read"],
    "deny": ["Bash(rm -rf:*)"]
  },

  // Liste des outils autorisés
  "allowedTools": ["Read", "Write", "Bash", "Glob", "Grep"],

  // Liste des outils désactivés
  "disabledTools": [],

  // Variables d'environnement injectées dans chaque session
  "env": {
    "NODE_ENV": "development",
    "MY_VAR": "valeur"
  },

  // Configuration des serveurs MCP
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/projets"],
      "env": {}
    }
  }
}

Option : model

Le modèle Claude à utiliser par défaut pour toutes les sessions.

{
  "model": "claude-sonnet-4-6"
}

Peut être surchargé en session avec /model ou --model en CLI.

Option : alwaysThinkingEnabled

Active l'Extended Thinking par défaut. Claude réserve des tokens pour son raisonnement interne avant de répondre.

{
  "alwaysThinkingEnabled": true
}

• Défaut : false
• Toggle en session : Alt+T (Windows/Linux) ou Option+T (macOS)
• Budget : contrôlé par MAX_THINKING_TOKENS (variable d'environnement)

Option : autoCompact

Compacte automatiquement le contexte quand la fenêtre de tokens approche la limite. Claude génère un résumé des échanges précédents.

{
  "autoCompact": true
}

• Défaut : true
• Manuel : commande /compact en session

Option : permissions

Contrôle fin des autorisations par outil. Deux listes : allow (autorisations explicites) et deny (interdictions).

Syntaxe des permissions

Outil(filtre)

{
  "permissions": {
    "allow": [
      "Read",
      "Bash(git:*)",
      "Bash(npm run:*)",
      "Bash(npm test:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "WebFetch"
    ]
  }
}

Option : allowedTools

Liste blanche des outils que Claude Code peut utiliser. Si définie, seuls les outils listés sont disponibles.

Outils disponibles

{
  "allowedTools": ["Read", "Bash", "Glob", "Grep"]
}

Option : disabledTools

Liste des outils explicitement désactivés (blacklist). Complément de allowedTools.

{
  "disabledTools": ["WebFetch", "WebSearch"]
}

Option : env

Variables d'environnement injectées automatiquement dans toutes les sessions Claude Code et les sous-processus qu'elles lancent.

{
  "env": {
    "NODE_ENV": "development",
    "DATABASE_URL": "postgresql://localhost/myapp",
    "LOG_LEVEL": "debug"
  }
}

Option : apiProvider

Fournisseur d'API à utiliser. Utile pour les proxies d'entreprise ou les déploiements via Amazon Bedrock / Google Vertex.

{
  "apiProvider": "anthropic",
  "customApiUrl": "https://mon-proxy.entreprise.com/anthropic"
}

Option : customApiUrl

URL de base personnalisée pour les appels API. Utile pour les proxies d'entreprise, les gateways ou les déploiements auto-hébergés.

{
  "customApiUrl": "https://api-proxy.mon-entreprise.com"
}

La clé API (ANTHROPIC_API_KEY) reste nécessaire même avec une URL personnalisée.

Option : effortLevel

Contrôle l'effort cognitif que Claude alloue à chaque réponse. Utile pour calibrer le rapport vitesse/qualité sans changer de modèle.

{
  "effortLevel": "medium"
}

Peut être surchargé en session ou via --effort-level en CLI.

Option : attribution

Personnalise ou supprime les mentions Co-Authored-By que Claude ajoute dans les commits et pull requests.

{
  "attribution": {
    "commit": "Co-Authored-By: Claude <claude@anthropic.com>",
    "pr": false
  }
}

Option : worktree

Configuration pour les dépôts Git utilisant des worktrees. Particulièrement utile dans les monorepos.

{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".next", "dist"],
    "sparsePaths": ["packages/mon-service/**", "shared/**"]
  }
}

Option : sandbox

Active le mode sandbox pour isoler les exécutions de Claude dans un environnement contrôlé.

{
  "sandbox": {
    "enabled": true
  }
}

Quand le sandbox est activé, les commandes Bash s'exécutent dans un environnement restreint sans accès réseau ni écriture en dehors du répertoire de projet.

Option : autoMode

Personnalise le classifieur de permissions utilisé en mode automatique. Permet d'ajuster le seuil à partir duquel Claude demande confirmation avant d'exécuter une action.

{
  "autoMode": {
    "permissionLevel": "default"
  }
}

Option : companyAnnouncements

Affiche un message personnalisé au démarrage de chaque session. Utile pour communiquer des instructions ou des rappels à toute l'équipe via le fichier settings.json commité.

{
  "companyAnnouncements": "Rappel : ce projet utilise Node 22. Lancer 'nvm use' avant toute session."
}

Le message s'affiche une fois dans le terminal, au lancement de Claude Code.

Option : mcpServers

Configuration des serveurs MCP. Chaque entrée est un serveur MCP nommé.

Structure d'un serveur MCP

{
  "mcpServers": {
    "<nom-du-mcp>": {
      "command": "<exécutable>",
      "args": ["<arg1>", "<arg2>"],
      "env": {
        "VAR": "valeur"
      },
      "transport": "stdio"
    }
  }
}

Exemples de configuration MCP

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/home/user/projets",
        "/tmp"
      ]
    },

    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_votre_token"
      }
    },

    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/mydb"
      ]
    },

    "mon-api-sse": {
      "transport": "sse",
      "url": "https://mon-serveur.com/mcp"
    }
  }
}

Configuration en entreprise

Les managed settings permettent à un administrateur d'imposer une configuration à toute l'organisation. Voici les cas d'usage les plus courants.

Imposer un modèle à toute l'équipe

// Managed settings (déployé via le dashboard Anthropic)
{
  "model": "claude-sonnet-4-5",
  "effortLevel": "medium"
}

Les développeurs peuvent encore choisir un modèle différent via --model en CLI, sauf si cette option est verrouillée par l'admin.

Interdire des commandes dangereuses

// Managed settings
{
  "permissions": {
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Bash(curl:*)",
      "WebFetch"
    ]
  }
}

Forcer l'attribution dans les commits

// Managed settings
{
  "attribution": {
    "commit": "Co-Authored-By: Claude <claude@anthropic.com>",
    "pr": "Generated with assistance from Claude Code"
  }
}

Forcer un proxy d'entreprise

// Managed settings
{
  "apiProvider": "anthropic",
  "customApiUrl": "https://api-gateway.mon-entreprise.com/anthropic"
}

Tous les appels à l'API Anthropic passeront par le proxy, quel que soit le fichier de configuration local du développeur.

Diffuser des instructions à l'équipe

// .claude/settings.json (commité dans le repo)
{
  "companyAnnouncements": "Sprint 14 en cours. Branche principale : main. Ne pas merger sans review de 2 personnes."
}

Exemples de configurations complètes

Configuration développeur solo

// ~/.claude/settings.json
{
  "model": "claude-sonnet-4-6",
  "alwaysThinkingEnabled": false,
  "autoCompact": true,
  "permissions": {
    "allow": ["Read", "Write", "Bash(git:*)", "Bash(npm:*)"],
    "deny": ["Bash(sudo:*)"]
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/projets"]
    }
  }
}

Configuration équipe (commitée dans le repo)

// .claude/settings.json
{
  "model": "claude-sonnet-4-6",
  "allowedTools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"],
  "permissions": {
    "deny": ["Bash(rm -rf:*)", "Bash(sudo:*)", "WebFetch"]
  },
  "env": {
    "NODE_ENV": "development"
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"]
    }
  }
}

Configuration sécurisée (lecture seule)

// Pour les audits ou environnements sensibles
{
  "allowedTools": ["Read", "Glob", "Grep", "LS"],
  "permissions": {
    "deny": ["Write", "Edit", "Bash", "WebFetch", "WebSearch"]
  }
}

Prochaines étapes

• Cheatsheet : Référence rapide : Vue d'ensemble de toutes les commandes
• CLI : Référence complète : Tous les flags de la commande claude
• Variables d'environnement : Variables reconnues par Claude Code