OpenCode Démarrage rapide : installation, configuration et utilisation de l'agent de codage IA en terminal

Comment installer, configurer et utiliser OpenCode

Sommaire

OpenCode est un agent de codage IA open source que vous pouvez exécuter dans le terminal (TUI + CLI) avec des interfaces de bureau et d’IDE optionnelles. C’est le Guide de démarrage rapide d’OpenCode : installation, vérification, connexion d’un modèle/fournisseur et exécution de flux de travail réels (CLI + API).

Note de version : OpenCode évolue rapidement. Les commandes « dernières » ici sont stables, mais les sorties et les valeurs par défaut peuvent changer — vérifiez toujours la documentation officielle de la CLI et le journal des modifications (liés ci-dessous).

Cet article fait partie de Outils pour développeurs IA : Le guide complet du développement assisté par IA.

Qu’est-ce qu’OpenCode (et où il s’insère)

OpenCode est conçu pour le codage agentique d’abord terminal, tout en restant flexible en termes de fournisseur et de modèle. En pratique, c’est une couche de flux de travail qui peut :

  • démarrer une interface utilisateur de terminal lorsque vous exécutez opencode
  • exécuter des prompts « one-shot » non interactifs via opencode run (scripts/automatisation)
  • exposer un serveur HTTP sans interface via opencode serve (et une interface web via opencode web)
  • être contrôlé de manière programmatique via le SDK JS/TS officiel @opencode-ai/sdk

Si vous souhaitez le comparer à un autre assistant agentique open source capable d’exécuter des plans multi-étapes dans un environnement sandboxé, consultez Guide de démarrage rapide de l’assistant de codage OpenHands.

opencode avec LLM qwen3.5 27b auto-hébergé

Si vous construisez un cluster /ai-devtools/, OpenCode est un candidat solide pour un sous-cluster car il s’étend naturellement vers :

  • une plongée profonde dans la CLI
  • le comportement et les coûts des modèles/fournisseurs (comparaison LLM dans OpenCode)
  • la configuration et les agents
  • les intégrations (GitHub/GitLab/Copilot)
  • une fiche mémo
  • Oh My Opencode — une couche d’orchestration multi-agent construite sur OpenCode

Prérequis

Vous aurez besoin de :

  • Un émulateur de terminal moderne (important pour l’expérience TUI).
  • Un accès à au moins un modèle/fournisseur (clés API ou authentification par abonnement, selon le fournisseur). Les options locales comme Ollama ou llama.cpp fonctionnent sans clés API lorsque vous exécutez un serveur compatible localement.

Installer OpenCode (copier-coller)

Script d’installation officiel (Linux/macOS/WSL) :

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

Options de gestionnaire de paquets (exemples officiels) :

# Installation globale Node.js
npm install -g opencode-ai

# Homebrew (recommandé par OpenCode pour les versions les plus à jour)
brew install anomalyco/tap/opencode

# Arch Linux (stable)
sudo pacman -S opencode

# Arch Linux (dernière version de AUR)
paru -S opencode-bin

Notes pour Windows (la documentation officielle recommande généralement WSL pour une meilleure compatibilité). Les alternatives incluent Scoop/Chocolatey ou npm.

# chocolatey (Windows)
choco install opencode

# scoop (Windows)
scoop install opencode

Docker (utile pour un test rapide) :

docker run -it --rm ghcr.io/anomalyco/opencode

Vérifier l’installation

opencode --version
opencode --help

Format de sortie attendu (variera selon la version) :

# Exemple :
# <affiche un numéro de version, ex. vX.Y.Z>
# <affiche l'aide avec les commandes/sous-commandes disponibles>

Connecter un fournisseur (deux chemins pratiques)

Chemin A : TUI /connect (interactif)

Démarrer OpenCode :

opencode

Puis exécuter :

/connect

Suivez les étapes de l’interface pour sélectionner un fournisseur et vous authentifier (certains flux ouvrent un navigateur pour la connexion).

Chemin B : CLI opencode auth login (clés de fournisseur)

OpenCode prend en charge la configuration des fournisseurs via :

opencode auth login

Notes :

  • Les identifiants sont stockés dans ~/.local/share/opencode/auth.json.
  • OpenCode peut également charger les clés depuis des variables d’environnement ou un fichier .env dans votre projet.

Hébergement local de LLM (Ollama, llama.cpp)

OpenCode fonctionne avec n’importe quelle API compatible OpenAI. Pour le développement local, de nombreux utilisateurs exécutent Ollama et pointent OpenCode vers celui-ci. J’ai récemment eu une très bonne expérience en configurant et exécutant OpenCode avec llama.cpp à la place — llama-server expose des endpoints compatibles OpenAI, vous pouvez donc utiliser des modèles GGUF avec le même flux de travail. Si vous préférez un contrôle plus fin sur la mémoire et le runtime, ou souhaitez une pile plus légère sans Python (au passage, ollama est implémenté en Go), llama.cpp vaut la peine d’être essayé. J’ai vraiment apprécié l’opportunité de configurer les couches offloadées, la facilité d’utilisation des modèles au format GGUF, et une compatibilité bien meilleure/plus rapide avec les nouveaux modèles, comme Qwen3.5. Si vous voulez savoir quels modèles performent réellement bien dans OpenCode — à travers les tâches de codage et la précision des sorties structurées — consultez ma comparaison pratique de LLM pour OpenCode.

Démarrer un projet correctement (première exécution recommandée)

Depot votre dépôt :

cd /path/to/your/repo
opencode

Puis initialiser :

/init

Cela analyse votre projet et crée un fichier AGENTS.md dans la racine du projet. Il est généralement judicieux de committer ce fichier afin qu’OpenCode (et les membres de l’équipe) partagent un contexte de projet cohérent.

Flux de travail CLI principaux (exemples copier-coller)

OpenCode prend en charge les exécutions non interactives :

opencode run "Expliquez comment fonctionnent les closures en JavaScript"

Flux de travail : générer du code (CLI)

Objectif : générer une petite fonction testable avec un contexte minimal.

opencode run "Écrivez une fonction Go ParsePort(envVar string, defaultPort int) (int, error). Elle doit lire la variable d'environnement, parser un entier, valider 1-65535, et retourner defaultPort si vide. Incluez 3 tests pilotés par tables."

Sortie attendue :

  • Une explication plus des blocs de code (fonction + tests). Le code exact varie selon le modèle/fournisseur et le prompt.

Flux de travail : refactoriser un fichier en toute sécurité (CLI + agent Plan)

Objectif : refactoriser sans modifications accidentelles en utilisant un agent plus restrictif.

opencode run --agent plan --file ./src/auth.ts \
  "Refactorisez ce fichier pour réduire la complexité. Sortie : (1) un court plan, (2) un patch unifié diff, (3) risques/cas limites à tester. Ne lancez pas de commandes."

Sortie attendue :

  • Une section de plan + un bloc de patch diff --git ... + une checklist de tests.
  • Le contenu varie. Si cela ne produit pas de diff, re-demandez : « Retournez uniquement un diff unifié » ou « Utilisez le format diff --git ».

Flux de travail : poser des questions sur le dépôt (CLI)

Objectif : localiser rapidement les détails d’implémentation.

opencode run --agent explore \
  "Dans ce dépôt, où l'authentification est-elle validée pour les requêtes API ? Listez les fichiers probables et expliquez le flux. Si vous n'êtes pas sûr, dites ce que vous avez vérifié."

Sortie attendue :

  • Une courte carte des chemins de fichiers + description du flux.
  • La sortie dépend de la taille du dépôt et des outils de contexte du modèle/fournisseur.

Flux de travail : accélérer les exécutions CLI répétées avec un serveur persistant

Si vous scriptez ou exécutez plusieurs appels opencode run, vous pouvez démarrer un serveur sans interface une seule fois :

Terminal 1 :

opencode serve --port 4096 --hostname 127.0.0.1

Terminal 2 :

opencode run --attach http://localhost:4096 "Résumez la structure du dépôt et les points d'entrée principaux."
opencode run --attach http://localhost:4096 "Proposez maintenant 3 refactorisations à fort impact et pourquoi."

Sortie attendue :

  • Identique à opencode run, mais généralement avec moins de surcharge de démarrage répété.

Utilisation programmatique (SDK JS/TS officiel)

OpenCode expose un serveur HTTP (OpenAPI) et fournit un client JS/TS typé.

Installation :

npm install @opencode-ai/sdk

Exemple : démarrer serveur + client, puis prompt

Créez scripts/opencode-sdk-demo.mjs :

import { createOpencode } from "@opencode-ai/sdk";

const opencode = await createOpencode({
  hostname: "127.0.0.1",
  port: 4096,
  config: {
    // Le format de chaîne de modèle est fournisseur/modèle (exemple uniquement)
    // model: "anthropic/claude-3-5-sonnet-20241022",
  },
});

console.log(`Serveur en cours d'exécution à : ${opencode.server.url}`);

// Vérification de base de santé/version
const health = await opencode.client.global.health();
console.log("Sain :", health.data.healthy, "Version :", health.data.version);

// Créer une session et un prompt
const session = await opencode.client.session.create({ body: { title: "Démo de démarrage rapide du SDK" } });

const result = await opencode.client.session.prompt({
  path: { id: session.data.id },
  body: {
    parts: [{ type: "text", text: "Générer une petite section README décrivant ce dépôt." }],
  },
});

console.log(result.data);

// Fermer le serveur une fois terminé
opencode.server.close();

Lancer :

node scripts/opencode-sdk-demo.mjs

Format de sortie attendu :

  • « Serveur en cours d’exécution à … »
  • Une réponse de santé incluant une chaîne de version
  • Un objet de réponse de prompt de session (la structure exacte dépend de responseStyle et de la version du SDK)

Configuration minimale OpenCode à copier

OpenCode prend en charge la configuration JSON et JSONC. C’est un point de départ raisonnable pour une configuration locale au projet.

Créez opencode.jsonc dans la racine de votre dépôt :

{
  "$schema": "https://opencode.ai/config.json",

  // Choisissez un modèle par défaut (fournisseur/modèle). Gardez cela aligné avec ce que `opencode models` affiche.
  "model": "fournisseur/modèle",

  // Optionnel : un "petit modèle" moins cher pour les tâches légères (titres, etc.)
  "small_model": "fournisseur/petit-modèle",

  // Optionnel : valeurs par défaut du serveur OpenCode (utilisées par serve/web)
  "server": {
    "port": 4096,
    "hostname": "127.0.0.1"
  },

  // Sécurité optionnelle : exiger une confirmation avant les modifications/commandes
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Fiche mémo courte (référence rapide)

Commandes que vous utiliserez quotidiennement

opencode                       # démarrer TUI
opencode run "..."             # exécution non interactive (automatisation)
opencode run --file path "..." # attacher des fichiers au prompt
opencode models --refresh      # rafraîchir la liste des modèles
opencode auth login            # configurer les identifiants du fournisseur
opencode serve                 # serveur HTTP sans interface (OpenAPI)
opencode web                   # serveur sans interface + interface web
opencode session list          # lister les sessions
opencode stats                 # statistiques de tokens/coûts

Commandes TUI à mémoriser

/connect   # connecter un fournisseur
/init      # analyser le dépôt, générer AGENTS.md
/share     # partager une session (si activé)
/undo      # annuler une modification
/redo      # rétablir une modification
/help      # aide/raccourcis

Concept de « touche leader » par défaut (TUI)

OpenCode utilise une touche « leader » configurable (souvent ctrl+x) pour éviter les conflits de terminal. Beaucoup de raccourcis sont « Leader + touche ».

Tableau de fiche mémo OpenCode imprimable en une page

Cette version est volontairement dense et « imprimable ». (Vous pouvez la coller dans une page dédiée /ai-devtools/opencode/cheatsheet/ plus tard.)

Tâche Commande / raccourci Notes
Démarrer TUI opencode Le comportement par défaut est de lancer l’interface utilisateur de terminal
Exécuter un prompt one-shot opencode run "..." Mode non interactif pour le script/automatisation
Attacher des fichiers au prompt opencode run --file path/to/file "..." Utilisez plusieurs drapeaux --file pour plusieurs fichiers
Choisir un modèle pour une exécution opencode run --model fournisseur/modèle "..." Les chaînes de modèle sont fournisseur/modèle
Choisir un agent opencode run --agent plan "..." Plan est conçu pour un travail « sans modifications » plus sûr (restrictions de permissions)
Lister les modèles opencode models [fournisseur] Utilisez --refresh pour mettre à jour la liste mise en cache
Configurer les identifiants du fournisseur opencode auth login Stocke les identifiants dans ~/.local/share/opencode/auth.json
Lister les fournisseurs authentifiés opencode auth list / opencode auth ls Confirme ce qu’OpenCode voit
Démarrer un serveur sans interface opencode serve --port 4096 --hostname 127.0.0.1 Spécification OpenAPI à http://host:port/doc
Attacher des exécutions au serveur opencode run --attach http://localhost:4096 "..." Utile pour éviter les démarrages à froid répétés
Activer l’authentification de base OPENCODE_SERVER_PASSWORD=... opencode serve Le nom d’utilisateur est par défaut opencode sauf si réécrit
Mode interface web opencode web Démarre le serveur et ouvre le navigateur
Exporter une session opencode export [sessionID] Utile pour l’archivage ou le partage de contexte
Importer une session opencode import session.json Peut également importer depuis une URL de partage
Voir les drapeaux CLI globaux opencode --help / opencode --version --print-logs + --log-level pour le débogage
Concept de touche leader TUI touche leader par défaut souvent ctrl+x Personnalisable dans tui.json

Oh My Opencode — aller plus loin avec OpenCode via l’orchestration multi-agent

Une fois OpenCode en cours d’exécution, l’étape suivante naturelle est Oh My Opencode — un plugin communautaire qui enveloppe OpenCode dans un harnais multi-agent. L’idée principale : tapez ultrawork (ou ulw) dans une session et un orchestrateur (Sisyphus) prend le relais, déléguant des sous-tâches à des agents spécialisés qui s’exécutent en parallèle, chacun sur la famille de modèles pour laquelle ses prompts sont réglés.

Trois articles le couvrent en profondeur :

Sources (officielles en premier)

Officiel :

Référence d’intégration autorisée :

Comparaisons/tutoriels réputés :