Présentation d'OpenCode : Agent Autonome en Ligne de Commande

OpenCode se distingue des assistants traditionnels comme GitHub Copilot ou Cursor par son architecture centrée sur le terminal. Alors que Copilot se concentre sur la complétion de code ligne par ligne et Cursor intègre l'IA dans l'éditeur, OpenCode agit comme un agent autonome capable d'exécuter des tâches complexes : analyse de projet, planification, modification de fichiers, exécution de commandes et validation des erreurs.

Cette aprpoche le rend particulièrement adapté aux refactorisations multi-fichiers, au débogage d'erreurs intermittentes et à la modification batch de tests. Cependant, pour les utilisateurs recherchant uniquement une autocomplétion fluide dans l'IDE, des solutions intégrées restent souvent plus ergonomiques.

Installation et Configuration Initiale

Gestion des Paquets et Versions

L'installation s'effectue via npm, mais une confusion fréquente concerne le nom du paquet. Le package officiel est opencode-ai et non opencode. Une installation incorrecte conduit à des erreurs de commande.

npm install -g opencode-ai
opencode --version

Il est recommandé d'utiliser Node.js version 20 ou supérieure. Les versions antérieures (comme la 18) peuvent rencontrer des problèmes de compatibilité avec le moteur d'exécution de la version 2.x d'OpenCode. Sous Windows, PowerShell gère l'installation globale correctement si le PATH est configuré. Sur macOS avec nvm, vérifiez que le répertoire bin global est bien accessible.

Intégration des Modèles et Providers

OpenCode propose un tier gratuit via son provider console, mais celui-ci est restreint à l'utilisation interne de l'outil. Pour une utilisation en tant que gateway ou pour d'autres clients, une clé API persnonelle ou un abonnement payant (OpenCode Go) est requis.

La configuration des clés API se fait via un fichier .env à la racine du projet :

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
CUSTOM_MODEL_ENDPOINT=https://api.monservice.io/v1

Pour intégrer des modèles locaux comme Ollama, un fichier de configuration opencode.json doit être défini. Voici une structure adaptée pour un modèle Llama :

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "local_ollama": {
      "npm": "@ai-sdk/ollama",
      "name": "Ollama Local",
      "options": {
        "baseURL": "http://127.0.0.1:11434/api"
      },
      "models": {
        "llama3:8b": {
          "name": "Llama 3 8B Instruct"
        }
      }
    }
  }
}

Un redémarrage de l'instance est nécessaire après modification de ce fichier pour que le provider soit chargé correctement.

Système de Skills et Automatisation

Définition et Structure des Skills

Les Skills (compétences) permettent de définir des workflows réutilisables. Chaque skill est encapsulé dans un dossier contenant un fichier SKILL.md qui décrit le déclencheur et la procédure à suivre. Cela évite de répéter les instructions à chaque interaction.

Exemple de structure pour un skill d'optimisation de performance :

~/.config/opencode/skills/optimize-perf/
└── SKILL.md

Contenu du fichier SKILL.md :

---
name: optimize-perf
description: Utilisé pour analyser et améliorer les performances d'une fonction spécifique
---

# Procédure d'Optimisation
1. Identifier la fonction cible et mesurer le temps d'exécution actuel
2. Analyser la complexité algorithmique (Big O)
3. Proposer des refactorisations pour réduire la complexité
4. Implémenter les changements et fournir le diff
5. Exécuter les benchmarks pour valider le gain de performance
6. Si aucun gain n'est observé, annuler les modifications

La précision de la description description est cruciale pour que le modèle déclenche le bon skill au bon moment.

Workflow de Correction Automatisée

Pour exploiter la correction de bugs, le projet doit être versionné avec Git afin de permettre des retours arrière (rollback). L'agent modifie le code de manière non déterministe, et un historique propre est indispensible.

Une requête typique devrait inclure le contexte, le symptôme et la commande de validation :

Le endpoint /api/user renvoie une erreur 500 aléatoire. Analysez server.js, identifiez les risques de null pointer, corrigez le code et lancez npm run test pour valider.

L'agent proposera un plan d'action. Il est conseillé de restreindre les permissions d'exécution de commandes dangereuses (comme rm ou drop) en mode manuel plutôt qu'en approval global.

Sécurité, Réseau et Dépannage

Stockage des Données et Confidentialité

Les historiques de session sont stockés localement. Sur Linux/macOS, cherchez dans ~/.local/share/opencode ou ~/.opencode. Sous Windows, les données résident dans le dossier AppData. Aucune donnée n'est envoyée vers le cloud sauf si un provider API externe est configuré.

Pour les projets sensibles, il est recommandé de désactiver la télémétrie dans la configuration :

telemetry: false

L'utilisation de modèles locaux (Ollama, vLLM) garantit que le code ne quitte jamais la machine.

Partage en Réseau Local

La commande opencode serve permet d'exposer l'interface via HTTP. Par défaut, le service écoute sur localhost. Pour un accès局域网 (LAN), il faut spécifier l'interface réseau :

opencode serve --hostname 0.0.0.0 --port 9000

Les appareils du réseau peuvent alors accéder à l'outil via http://IP_MACHINE:9000. Attention, ce service ne dispose pas d'authentification native. Il ne doit être exposé que sur des réseaux de confiance ou protégés par un tunnel.

Résolution des Problèmes Courants

• Commande introuvable après installation : Vérifiez le nom du paquet. Désinstallez opencode et installez opencode-ai.
• Erreur Free Tier : Le message "free tier can only be used from within opencode" indique une tentative d'utilisation externe. Configurez une clé API personnelle.
• Liste de modèles vide (Desktop) : Aucun provider n'est configuré. Ajoutez une clé API dans les paramètres.
• Extension VSCode introuvable : Recherchez opencode-ai sur le marketplace officiel, pas dans l'écosystème Cursor.
• Modèles locaux non détectés : Validez la syntaxe de opencode.json et redémarrez le service.
• Accès LAN refusé : Vérifiez le firewall et l'option --hostname 0.0.0.0.
• Historique perdu après mise à jour : Les chemins de données peuvent changer. Utilisez la commande /sessions pour migrer ou retrouver les chats.