Installer Claude Code sur macOS Tahoe

Introduction

Cet article documente l'installation de Claude Code sur macOS Tahoe (macOS 26.x), très largement au-dessus du minimum requis par Claude Code (macOS 13.0+). L'installation peut se faire indifféremment depuis le Terminal local du Mac, ou via SSH depuis un autre poste — la procédure est identique. Seule l'étape d'authentification diverge légèrement entre les deux contextes.

Contrairement à FreeBSD qui propose un paquet pkg natif, ou Alpine qui passe par l'installateur bash officiel, la voie la plus propre sur macOS est le cask Homebrew claude-code — un seul brew install, et le binaire est en place.

(Toutes les commandes s'exécutent en tant qu'utilisateur standard. Sudo n'est nécessaire à aucune étape, Homebrew refuse même de tourner en root.)

Pré-requis

Avant de commencer :

• Homebrew installé — voir Installer et utiliser homebrew pour la procédure complète.
• Accès au Terminal — soit en local via Terminal.app, soit via SSH depuis un autre poste. Dans le second cas, le serveur SSH doit être activé sur la machine cible (Réglages système > Général > Partage > Session à distance) — voir Activer et configurer le serveur SSH sur macOS Tahoe.

1. Préparation du système

Vérification de la version de macOS, que Homebrew répond, et mise à jour du catalogue des formules et casks.

sw_vers
brew --version
brew update

(sw_vers doit afficher ProductVersion: 26.x. brew --version doit retourner un numéro sans erreur — sur Apple Silicon, Homebrew est installé dans /opt/homebrew, et son binaire est par défaut dans le PATH.)

2. Installation via Homebrew

Homebrew publie deux casks pour Claude Code : claude-code suit le canal stable (environ une semaine de décalage, sans les régressions majeures), et claude-code@latest suit le canal latest (mises à jour dès leur sortie). Pour un usage courant, le cask stable suffit largement.

brew install --cask claude-code

(Le cask installe le binaire natif dans /opt/homebrew/Caskroom/claude-code/<version>/claude et crée un lien symbolique dans /opt/homebrew/bin/claude. Aucun runtime Node.js requis. Aucune manipulation de PATH à prévoir si Homebrew est correctement initialisé dans le shell.)

3. Vérification de l'installation

claude --version
claude doctor

À la date de rédaction, la version stable est 2.1.142. claude doctor effectue un diagnostic complet (chemin du binaire, gestionnaire de paquets détecté, ripgrep embarqué, canal de mise à jour, état du serveur en arrière-plan).

Si l'installation se fait via une session SSH, claude doctor signale presque toujours un avertissement Keychain de ce type :

⚠ macOS Keychain is not writable
 (security: SecKeychainItemCreateFromContent...
 add-generic-password: returned -25308).
 Console login will fail to save your API key.

Ce n'est pas un défaut d'installation, mais la conséquence directe du fait que le login.keychain-db macOS n'est pas déverrouillable sans interaction graphique. C'est l'objet de la section suivante.

4. Authentification

4.1 OAuth ou clé API ?

Claude Code propose deux modes d'authentification :

• OAuth via navigateur, lié à un compte Pro/Max/Team/Enterprise ou Console Anthropic.
• Clé API générée sur la Console Anthropic et exposée via la variable ANTHROPIC_API_KEY.

Sur le Terminal en local, OAuth fonctionne sans accroc : Claude Code ouvre Safari pour la phase d'authentification, et stocke le token résultant dans le Keychain macOS — qui est déjà déverrouillé par la session graphique de l'utilisateur.

Sur une session SSH headless en revanche, deux obstacles se cumulent :

• Aucun navigateur n'est disponible côté serveur. Le code d'appariement peut bien être copié-collé dans un navigateur local, mais...
• ...le login.keychain-db reste verrouillé tant qu'aucune session graphique n'est ouverte sur la machine cible, et Claude Code échoue à y écrire le token (erreur -25308).

Une option existe : déverrouiller manuellement le Keychain au début de chaque session SSH.

security unlock-keychain ~/Library/Keychains/login.keychain-db

(Le mot de passe demandé est celui du compte macOS local, pas une clé API. Faisable pour un usage ponctuel, mais ajoute une étape interactive à chaque connexion SSH — peu compatible avec un usage automatisé.)

La voie la plus fiable, tant en local que via SSH, et la seule réellement pratique pour de l'automatisation, est de passer par une clé API. C'est l'objet de la section suivante.

4.2 La méthode du token API

Une clé API générée sur la Console Anthropic contourne complètement le Keychain :

• Se connecter à console.anthropic.com depuis un poste local.
• Aller dans Settings > API Keys et créer une clé dédiée à cette machine (lui donner un nom explicite, par exemple macos-tahoe-dev).
• Copier la clé immédiatement — elle ne sera plus affichée ensuite.
• L'ajouter au profil zsh (shell par défaut sur macOS récent) et recharger l'environnement :

echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
chmod 600 ~/.zshrc
exec zsh
echo $ANTHROPIC_API_KEY

Conséquences à connaître

• La clé est stockée en clair dans ~/.zshrc. Le chmod 600 en restreint la lecture au seul propriétaire. Ne jamais la versionner dans un dépôt git ni la copier dans un fichier de configuration partagé.
• L'usage est facturé en pay-as-you-go sur la Console, même si un abonnement Pro/Max est actif sur le même compte : la clé contourne l'abonnement. C'est visible dans le bandeau d'accueil de Claude Code (API Usage Billing).
• La clé peut être révoquée à tout moment depuis la Console si elle fuite (commit accidentel, partage de machine, etc.).

5. Premier lancement

claude

Au tout premier lancement, Claude Code affiche un écran Quick safety check qui demande de confirmer la confiance dans le dossier courant avant de le lire, l'éditer ou y exécuter des commandes. Lancé depuis le home (~/), ce prompt est légitime : le home contient typiquement des fichiers privés (.ssh, .zshrc, .aws...) qu'on ne veut pas exposer.

Le plus propre est de quitter avec Esc, de créer un dossier projet dédié, et de relancer claude depuis ce dossier :

mkdir ~/PROJET && cd ~/PROJET
claude

Depuis le dossier projet, l'écran d'accueil de Claude Code apparaît avec :

• La version installée (ex. Claude Code v2.1.142).
• Le modèle actif (ex. Opus 4.7 (1M context)).
• Le mode de facturation (API Usage Billing puisqu'on utilise une clé API Console).
• Le répertoire de travail (~/PROJET).

6. Choix du modèle

Le cask stable suit le canal officiel avec environ une semaine de décalage : la 2.1.142 supporte largement Opus 4.7, qui requiert 2.1.111 ou supérieur. En session, trois commandes utiles :

• /model ouvre le sélecteur interactif des modèles disponibles selon le plan ou la clé utilisée.
• /model claude-opus-4-7 bascule directement sur Opus 4.7 pour la session courante.
• /status affiche le modèle actuellement actif et la consommation de la session.

Pour fixer Opus 4.7 comme modèle par défaut de toutes les sessions futures, l'ajouter à la configuration shell :

echo 'export ANTHROPIC_MODEL="claude-opus-4-7"' >> ~/.zshrc
exec zsh

(Sur clé API Console, Opus 4.7 est accessible sans contrainte de plan. En revanche, sur abonnement Pro le sélecteur masquera Opus et basculera silencieusement sur Sonnet — c'est aussi pour ça que la voie clé API est préférable sur une machine dédiée à du travail Opus.)

7. Mises à jour

À la différence de l'installateur natif officiel (curl ... | bash) qui se met à jour seul en arrière-plan, le cask Homebrew n'auto-update pas. Les mises à jour se font manuellement :

brew update
brew upgrade claude-code

(Pour suivre le canal latest plutôt que stable, le cask alternatif est claude-code@latest ; la commande de mise à jour devient alors brew upgrade claude-code@latest. Homebrew conserve les anciennes versions sur disque après upgrade — lancer brew cleanup périodiquement pour récupérer l'espace.)

Conclusion

L'installation de Claude Code sur macOS Tahoe se résume à un brew install --cask claude-code, à condition d'avoir préalablement Homebrew en place. Le vrai sujet sur macOS n'est pas l'installation elle-même mais l'authentification : OAuth fonctionne nativement en Terminal local, mais le Keychain ne suit pas en session SSH headless. La voie la plus simple et la plus robuste, qui marche dans tous les contextes, est de passer par une clé API Console exportée dans ~/.zshrc — exactement la même approche que sur les VMs Alpine ou FreeBSD, et pour les mêmes raisons de fond.

Une fois en place, la version 2.1.142 du cask permet d'utiliser Opus 4.7 avec contexte 1M sans contrainte, et le cycle de mise à jour se fait via brew upgrade comme tout autre paquet Homebrew.