OpenCode Claude Agent : configuration, limites et règles

Utilisez le fournisseur Claude Agent d’OpenCode avec votre propre installation locale de Claude Code. Installez les deux outils, exécutez claude auth login, puis choisissez Claude Agent dans /connect. Si votre équipe exige une méthode d’authentification documentée pour une application tierce, choisissez une clé API.

Au 2026-11-05, OpenCode propose un guide de configuration dédié à Claude Agent. Le fournisseur utilise l’authentification active de Claude Code. L’abonnement n’est donc pas forcément le mode de facturation retenu.

Que change Claude Agent ?

Claude Agent conserve l’interface et l’exécution des outils d’OpenCode, tandis que Claude Code communique avec le modèle. OpenCode appelle votre exécutable claude installé au moyen du Claude Agent SDK d’Anthropic.

Le fournisseur intégré est arrivé dans OpenCode v2.2.3. La version v2.2.4 a ajouté une configuration guidée au sélecteur de fournisseurs de l’application. Vous n’avez pas besoin d’un plugin d’abonnement distinct.

Selon la conception du fournisseur, OpenCode gère les opérations sur les fichiers, les commandes shell et les permissions. Les outils intégrés de Claude Code sont désactivés.

OpenCode gère aussi le compactage du contexte et les sous-agents, comme l’explique son guide actuel de Claude Agent. L’intégration ne charge pas vos paramètres natifs de Claude Code, ses hooks, ses serveurs MCP, ses skills ou sa mémoire. Les hooks exécutent des actions lors d’événements définis.

Les instructions et les outils d’OpenCode déterminent donc le traitement du projet. Vérifiez-les avant d’autoriser des modifications ou l’exécution de commandes. Si votre travail dépend des hooks natifs ou des équipes d’agents de Claude Code, continuez à l’utiliser jusqu’à disposer d’une solution équivalente.

Ce fournisseur convient surtout si vous voulez conserver l’interface d’OpenCode et sa manière de changer de modèle. Son installation ne reproduit pas l’ensemble des fonctions de Claude Code.

Installer et connecter Claude Agent

Utilisez OpenCode V2 et Claude Code sur la même machine que le serveur OpenCode. Ce fournisseur n’est pas disponible dans les espaces de travail distants d’OpenCode.

La connexion par abonnement suppose un abonnement individuel Pro, Max ou Ultra actif.

Installer les bonnes versions

Installez OpenCode V2, avec v2.2.3 comme version minimale pour cette fonction. Utilisez v2.2.4 ou une version ultérieure pour la configuration guidée dans l’application.

Ces commandes sont destinées à Bash sous macOS, Linux ou WSL. Elles suivent les instructions d’installation d’OpenCode V2 et les instructions d’installation de Claude Code :

curl -fsSL https://opencode.ai/v2/install | bash
curl -fsSL https://claude.ai/install.sh | bash

Ouvrez un nouveau terminal, puis vérifiez les deux versions :

opencode --version
claude --version

Claude Code doit être en version 2.1.248 ou ultérieure, comme l’exige la vérification de version du fournisseur. Mettez à jour les anciennes installations natives avec claude update. Pour une installation gérée par un gestionnaire de paquets, utilisez ce gestionnaire.

Si vous utilisez déjà V1, lisez d’abord le guide de migration vers V2. Les deux versions utilisent la commande opencode et partagent les emplacements de configuration.

L’installation n’inclut pas l’utilisation des modèles. Consultez les options d’installation, d’abonnement et d’accès API de Claude Code si vous n’avez pas encore choisi votre mode d’accès.

Se connecter et vérifier le compte

Authentifiez-vous avec la procédure de connexion propre à Claude Code. Sélectionnez le compte de votre abonnement si vous voulez utiliser son quota :

claude auth login
claude auth status --text

Vérifiez que l’état indique le compte et la méthode d’authentification prévus. La référence de la CLI distingue cette procédure de claude auth login --console, qui sélectionne la facturation API de Console.

Avant d’essayer votre abonnement, vérifiez les identifiants hérités de l’environnement. Anthropic précise que les clés API du shell peuvent avoir priorité sur l’authentification par abonnement. Si une ancienne clé est définie par erreur dans votre shell personnel, supprimez cette variable :

unset ANTHROPIC_API_KEY
claude auth status --text

Vérifiez aussi si ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL ou les paramètres d’un fournisseur cloud sont définis par erreur. Consultez l’ordre de priorité de l’authentification d’Anthropic. La connexion par abonnement n’a pas priorité sur tous les autres identifiants.

Inspectez providers.claude-agent.settings dans la configuration d’OpenCode pour repérer apiKey, authToken ou baseURL. Les valeurs définies au niveau du modèle comptent également. Le code de connexion applique ces paramètres après l’environnement du serveur.

Connecter le fournisseur et vérifier une vraie requête

Lancez un serveur OpenCode privé pour la première vérification :

opencode --standalone

Le mode standalone utilise un serveur privé. Ce serveur utilise l’environnement du shell actuel, sans dépendre d’un service partagé déjà lancé. Les valeurs définies dans la configuration restent prioritaires.

Dans OpenCode, exécutez /connect et sélectionnez Claude Agent. Exécutez ensuite /models et choisissez un modèle parmi ceux fournis par Claude Code. Les références de modèles du fournisseur peuvent utiliser des alias comme claude-agent/opus. Ne supposez pas qu’ils correspondent aux identifiants des modèles de l’API directe.

Dans l’application, la configuration guidée propose l’installation, la connexion, la vérification de la connexion et la reprise après une erreur. Une vérification réussie mène à la sélection du modèle. Ces commandes de l’application sont distinctes des instructions de terminal ci-dessus.

Utilisez un dépôt contenant README.md, puis envoyez :

Read README.md and summarize the project in three sentences. Do not modify files or run shell commands.

La demande exige un résumé du projet en trois phrases, sans modifier de fichiers ni lancer de commandes. Vérifiez qu’OpenCode affiche une lecture de fichier par un outil et une réponse pertinente. Cela vérifie l’accès au modèle et le retour du résultat de l’outil.

La présence de modèles dans le sélecteur ne suffit pas : la vérification de connexion n’envoie aucun prompt au modèle.

Définir OPENCODE_CLAUDE_PATH si la détection échoue

Indiquez au serveur l’exécutable réel de Claude Code si son PATH ne trouve pas l’installation souhaitée. Vérifiez d’abord que command -v claude renvoie le chemin du bon exécutable dans votre terminal.

Pour une nouvelle vérification avec un serveur privé :

export OPENCODE_CLAUDE_PATH="$(command -v claude)"
opencode --standalone

Pour le service partagé en arrière-plan, utilisez son environnement géré :

opencode service set env OPENCODE_CLAUDE_PATH "$(command -v claude)"

Modifier l’environnement du service arrête le service en cours. La prochaine commande ayant besoin du serveur local le relance avec la nouvelle valeur. Reconnectez Claude Agent et répétez la petite requête.

Les instructions sur l’environnement du serveur expliquent pourquoi une modification limitée au terminal du client peut ne pas suffire.

Quel quota Claude Agent utilise-t-il ?

Planifiez les requêtes selon l’authentification active de Claude Code. Avec une authentification par abonnement, les requêtes Claude Agent font partie de votre quota Claude existant.

OpenCode indique que cette connexion utilise l’abonnement. Anthropic confirme que Claude et Claude Code partagent les limites de l’abonnement. Ces deux règles impliquent qu’un changement d’interface ne crée pas de second quota.

Distinguez ces trois cas :

Authentification de Claude Code	Prise en charge de l’utilisation
Abonnement Claude	Quota inclus, avec ses limites et les éventuels crédits d’utilisation payants activés
Compte Anthropic API ou compte cloud pris en charge	Facturation et limites API de ce compte
Passerelle personnalisée	Règles de facturation du compte de la passerelle

Une estimation absente ne prouve pas que l’utilisation est gratuite. La logique de calcul des coûts du fournisseur omet aussi les estimations pour les URL de base personnalisées.

Consultez la consommation et les heures de réinitialisation dans Claude Settings > Usage. La vue native /usage de Claude Code n’est pas disponible dans OpenCode. Vérifiez également les crédits d’utilisation payants : leur activation peut entraîner des frais supplémentaires une fois le quota inclus épuisé.

Pour choisir votre mode d’accès, comparez les abonnements Claude et la facturation API.

Que précisent les conditions d’utilisation ?

Évaluez l’autorisation pour l’implémentation et le mode d’utilisation concernés. Le SDK officiel ne donne pas automatiquement à toute application tierce le droit d’utiliser les identifiants d’un abonnement.

Les trois documents concernent des situations différentes :

Source officielle	Ce qu’elle indique	Conséquence pour cette configuration
Ancienne page des fournisseurs d’OpenCode	Elle avertit qu’Anthropic interdit les plugins d’abonnement Pro/Max et qu’OpenCode a cessé de les inclure depuis 1.3.0.	Cet avertissement sur les anciens plugins ne décrit pas l’implémentation du nouveau fournisseur V2.
Présentation du Claude Agent SDK d’Anthropic	Les développeurs tiers doivent obtenir une autorisation préalable pour proposer la connexion à un compte Claude ou ses limites de requêtes dans leurs produits.	L’utilisation du SDK ne prouve pas à elle seule qu’une autorisation existe.
Conditions juridiques et de conformité de Claude Code	Elles restreignent l’intermédiation des identifiants par des tiers, mais permettent de se connecter au binaire Claude Code non modifié avec son propre abonnement.	Conservez la connexion native ; n’étendez pas cette exception à la mise en commun d’identifiants ou à un nouveau service commercial.

Il existe aussi une déclaration sur cette implémentation. Le 2026-10-30, Tarquinen, auteur de la PR, a déclaré qu’Anthropic avait donné son accord et que l’intégration respectait les conditions. Cette déclaration vient du contributeur d’OpenCode. Ce n’est pas un document publié par Anthropic qui définit la portée de l’autorisation.

Pour un usage personnel, utilisez votre propre compte dans une installation non modifiée de Claude Code. N’exportez pas les jetons de session vers un autre plugin. Pour un déploiement en entreprise ou une intégration dans un produit, obtenez une confirmation couvrant ce cas ou utilisez la méthode documentée par clé API.

Une authentification réussie confirme qu’une requête fonctionne. Elle ne détermine pas si les conditions contractuelles couvrent toutes les formes de déploiement.

Corriger l’erreur observée

Choisissez la vérification correspondant au symptôme, puis répétez la petite requête de lecture de fichier.

Symptôme	Vérification et suite
`Claude Code is not installed`	Installez Claude Code sur la machine du serveur OpenCode ou définissez `OPENCODE_CLAUDE_PATH` sur ce serveur. Reconnectez-vous.
`Claude Code is not logged in`	Exécutez `claude auth login` sur cette machine avec le même utilisateur. Vérifiez l’état, puis reconnectez-vous.
L’erreur contient `2.1.248 or later is required`	Mettez Claude Code à jour et confirmez la version de l’exécutable avant de réessayer.
La connexion fonctionne, mais aucun modèle ou aucune réponse n’est disponible	Vérifiez l’exécutable et la connexion au compte sur le serveur. Reconnectez-vous ; la détection des modèles ne prouve pas que l’inférence fonctionne.

Les erreurs de connexion documentées couvrent l’absence d’installation et de connexion au compte. Si une requête atteint plutôt une limite de l’abonnement, consultez la page d’utilisation du compte. Une reconnexion ne renouvelle pas le quota.

Quand utiliser une clé API ?

Choisissez une clé API pour une facturation séparée ou un serveur sans installation locale de Claude Code. Préférez aussi cette méthode si votre produit tiers exige une authentification documentée. Gardez son budget et ses limites distincts de l’abonnement Claude.

Accès direct à l’API Anthropic

Créez votre propre clé dans Claude Console. Dans OpenCode, sélectionnez Anthropic via /connect et choisissez l’authentification par clé API.

La commande d’authentification équivalente de V2 demande le secret de manière interactive :

opencode auth login anthropic --method key
opencode run --standalone --model anthropic/claude-sonnet-5-5 "Reply with only: OK"

Vérifiez la réponse OK et l’utilisation sur le compte API prévu. Si le compte ou le modèle sélectionné est incorrect, corrigez-le via /connect ou /models avant de réessayer.

Accès par une API compatible avec OpenAI

Au 2026-11-05, BetterToken répertorie aussi claude-sonnet-5-5 et claude-opus-5-5. Son intégration documentée avec OpenCode utilise une API compatible avec OpenAI et votre propre clé BetterToken. Cet accès API est facturé séparément.

Créez une clé dans votre espace de travail. Pour une nouvelle configuration native V2, ajoutez ce fournisseur au fichier opencode.jsonc du projet en conservant les autres paramètres :

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "bettertoken": {
      "name": "BetterToken",
      "env": ["BETTERTOKEN_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://www.bettertoken.ai/v1"
      },
      "models": {
        "claude-sonnet-5-5": {
          "name": "Claude Sonnet 5.5"
        }
      }
    }
  }
}

Cet exemple suit le format natif des fournisseurs personnalisés de V2. Il utilise providers, package et settings. Ne mélangez pas les noms de champs de V1 dans cette entrée de fournisseur.

Saisissez la clé sans l’afficher, puis lancez la vérification dans le même terminal Bash :

read -rs BETTERTOKEN_API_KEY && export BETTERTOKEN_API_KEY
opencode run --standalone --model bettertoken/claude-sonnet-5-5 "Reply with only: OK"

Le résultat attendu est une réponse normale contenant OK. Vérifiez ensuite la requête et les frais dans l’espace de travail. Si vous avez déjà enregistré un compte BetterToken dans OpenCode, vérifiez le compte actif : les comptes enregistrés ont priorité sur les connexions par l’environnement.

Consultez les tarifs actuels avant une tâche plus importante. Cet accès API n’inclut pas d’abonnement Claude et n’autorise pas d’autres intégrations utilisant la connexion par abonnement.