Démarrage rapide d'OpenCode : 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. Voici 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 la sortie et les valeurs par défaut peuvent changer — vérifiez toujours la documentation officielle CLI et le journal des modifications (liens 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 un codage agentique axé sur le terminal, tout en restant flexible quant au fournisseur et au modèle. En pratique, c’est une couche de flux de travail capable de :

  • lancer une interface utilisateur de terminal (TUI) 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 officiel JS/TS @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.

Pour l’agent axé sur le terminal d’Anthropic avec la même histoire de « modèle local via HTTP » (Ollama ou llama.cpp, permissions, tarification), consultez Installation et configuration de Claude Code pour Ollama, llama.cpp, tarification.

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

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.

Installation d’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 depuis AUR)
paru -S opencode-bin

Notes Windows (les conseils officiels recommandent couramment WSL pour une meilleure compatibilité). Les alternatives incluent Scoop/Chocolatey ou npm.

# chocoloatey (Windows)
choco install opencode

# scoop (Windows)
scoop install opencode

Docker (utile pour un essai 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, par exemple vX.Y.Z>
# <affiche l'aide avec les commandes/sous-commandes disponibles>

Connecter un fournisseur (deux chemins pratiques)

Chemin A : TUI /connect (interactif)

Lancer OpenCode :

opencode

Puis exécuter :

/connect

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

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 LLM local (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 en exécutant OpenCode avec llama.cpp à la place — llama-server expose des endpoints compatibles OpenAI, vous permettant d’utiliser des modèles GGUF avec le même flux de travail. Si vous préférez un contrôle granulaire sur la mémoire et l’exécution, ou souhaitez une pile plus légère sans Python (PS : ollama est implémenté en Go), llama.cpp vaut la peine d’être essayé. J’ai vraiment apprécié la possibilité de configurer les couches déchargées, la facilité d’utilisation des modèles au format GGUF et une compatibilité implémentée bien meilleure et plus rapide avec les nouveaux modèles, comme Qwen3.5. Si vous voulez savoir quels modèles performants réellement bien dans OpenCode — à travers les tâches de codage et la précision de la sortie structurée — consultez ma comparaison pratique de LLMs pour OpenCode.

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

Depos votre dépôt :

cd /path/to/your/repo
opencode

Puis initialiser :

/init

Cela analyse votre projet et crée un fichier AGENTS.md à la racine du projet. Il est généralement utile 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 "Expliquer comment fonctionnent les fermetures 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 "Écrire une fonction Go ParsePort(envVar string, defaultPort int) (int, error). Elle doit lire la variable d'environnement, parser un int, valider 1-65535, et retourner defaultPort si vide. Inclure 3 tests pilotés par table."

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 \
  "Refactoriser ce fichier pour réduire la complexité. Sortie : (1) un plan court, (2) un patch de diff unifié, (3) risques/cas limites à tester. Ne pas exécuter de commandes."

Sortie attendue :

  • Une section de plan + un bloc de patch diff --git ... + une liste de vérification de tests.
  • Le contenu varie. Si cela ne produit pas de diff, re-promptez : « Renvoyer uniquement un diff unifié » ou « Utiliser 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 ? Lister les fichiers probables et expliquer le flux. Si incertain, indiquer ce qui a été vérifié."

Sortie attendue :

  • Une carte courte 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ésumer la structure du dépôt et les points d'entrée principaux."
opencode run --attach http://localhost:4096 "Proposer maintenant 3 refactorisations à fort impact et pourquoi."

Sortie attendue :

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

Utilisation programmatique (SDK officiel JS/TS)

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éer 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 santé/version de base
const health = await opencode.client.global.health();
console.log("En bonne santé :", 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 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();

Exécuter :

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 que vous pouvez copier

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

Créer opencode.jsonc à la racine de votre dépôt :

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

  // Choisir un modèle par défaut (fournisseur/modèle). Garder 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"
  },

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

Mémo court (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. De nombreux raccourcis sont « Leader + touche ».

Tableau de mémo OpenCode imprimable sur une page

Cette version est intentionnellement 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 de terminal
Exécuter un prompt one-shot opencode run "..." Mode non interactif pour le script/automatisation
Attacher fichier(s) au prompt opencode run --file path/to/file "..." Utiliser plusieurs drapeaux --file pour plusieurs fichiers
Choisir le modèle pour une exécution opencode run --model fournisseur/modèle "..." Les chaînes de modèle sont fournisseur/modèle
Choisir l’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] Utiliser --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 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 par défaut est opencode sauf si redéfini
Mode interface web opencode web Démarre le serveur + 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 aussi 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 grâce à 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 : taper 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èle 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 autoritaire :

Comparaisons/tutoriels réputés :

S'abonner

Recevez de nouveaux articles sur les systèmes, l'infrastructure et l'ingénierie IA.