Démarrage rapide d'OpenCode : Installez, configurez et utilisez l'agent de codage AI Terminal

Comment installer, configurer et utiliser OpenCode

Sommaire

OpenCode est un agent d’IA open source que vous pouvez exécuter en terminal (TUI + CLI) avec des surfaces de bureau et d’IDE optionnels. Voici le guide de démarrage rapide OpenCode : installez, vérifiez, connectez un modèle/fournisseur, et exécutez des workflows réels (CLI + API).

Note de version : OpenCode évolue rapidement. Les commandes « latest » ici sont stables, mais la sortie et les paramètres par défaut peuvent changer — vérifiez toujours les documents officiels du CLI et le journal des modifications (liés ci-dessous).

Cet article fait partie du guide complet des outils d’IA : le guide complet du développement alimenté par l’IA.

Ce qu’est OpenCode (et où il s’inscrit)

OpenCode est conçu pour le codage agentif en premier lieu, en terminal, tout en restant flexible en termes de fournisseurs/modèles. En pratique, il s’agit d’une couche de workflow qui peut :

  • démarrer une interface utilisateur en terminal lorsque vous exécutez opencode
  • exécuter des prompts non interactifs « one-shot » 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 programmable via le SDK officiel JS/TS @opencode-ai/sdk

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

Si vous construisez un cluster /ai-devtools/, OpenCode est un candidat fort pour un sous-cluster car il s’adapte naturellement à :

  • Découverte approfondie CLI
  • Comportement et coûts des modèles/fournisseurs (comparaison des LLM à l’intérieur d’OpenCode)
  • Configuration & agents
  • Intégrations (GitHub/GitLab/Copilot)
  • Feuille de triche

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.

Installez OpenCode (copiez-colliez)

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

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

Options du gestionnaire de paquets (exemples officiels) :

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

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

# Arch Linux (stable)
sudo pacman -S opencode

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

Notes pour Windows (la documentation officielle recommande souvent WSL pour la meilleure compatibilité). D’autres alternatives incluent Scoop/Chocolatey ou npm.

# Chocolatey (Windows)
choco install opencode

# Scoop (Windows)
scoop install opencode

Docker (utile pour un essai rapide) :

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

Vérifiez l’installation

opencode --version
opencode --help

Forme attendue de la sortie (variera selon la version) :

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

Connectez un fournisseur (deux chemins pratiques)

Chemin A : /connect TUI (interactif)

Démarrer OpenCode :

opencode

Ensuite, exécuter :

/connect

Suivez les étapes de l’interface utilisateur pour sélectionner un fournisseur et vous authentifier (certains flux ouvrent un navigateur/login 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 à ~/.local/share/opencode/auth.json.
  • OpenCode peut également charger les clés à partir des variables d’environnement ou d’un fichier .env dans votre projet.

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

OpenCode fonctionne avec toute API compatible OpenAI. Pour le développement local, de nombreux utilisateurs exécutent Ollama et pointent OpenCode vers celui-ci. Récemment, j’ai 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, donc vous pouvez utiliser des modèles GGUF avec le même workflow. Si vous préférez un contrôle fin sur la mémoire et le runtime, ou si vous souhaitez un stack plus léger sans Python (par ailleurs, ollama est implémenté en Go), llama.cpp vaut le détour. J’ai vraiment apprécié l’opportunité de configurer des couches déchargées, l’ease d’utilisation des modèles en format GGUF, et une compatibilité bien meilleure/plus rapide avec les nouveaux modèles, comme Qwen3.5.

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

À partir de votre dépôt :

cd /chemin/vers/votre/dépôt
opencode

Ensuite, initialiser :

/init

Cela analyse votre projet et crée un fichier AGENTS.md à la racine du projet. Il est généralement utile de commiter ce fichier afin qu’OpenCode (et les collègues) partagent un contexte de projet cohérent.

Workflow CLI principal (exemples copier-coller)

OpenCode prend en charge les exécutions non interactives :

opencode run "Expliquez comment fonctionnent les fermetures en JavaScript"

Workflow : 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 basés sur des tableaux."

Sortie attendue :

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

Workflow : 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 bloc de diff unifié, (3) les risques/cas limites à tester. Ne lancez pas de commandes."

Sortie attendue :

  • Une section de plan + un bloc diff --git ... + une liste de tests.
  • Le contenu varie. Si aucun diff n’est produit, relancez le prompt : « Retournez uniquement un diff unifié » ou « Utilisez le format diff --git ».

Workflow : 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ù est validée l'authentification pour les requêtes API ? Listez les fichiers probables et expliquez le flux. Si incertain, indiquez ce que vous avez 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.

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

Si vous scriptez ou exécutez plusieurs 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 entrées principales."
opencode run --attach http://localhost:4096 "Proposez maintenant 3 refactorisations à impact élevé et pourquoi."

Sortie attendue :

  • La même que opencode run, mais généralement avec moins de surcoût de démarrage répétitif.

Utilisation programmable (SDK JS/TS officiel)

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

Installer :

npm install @opencode-ai/sdk

Exemple : démarrez le serveur + le client, puis posez une question

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: {
    // 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("Sain :", health.data.healthy, "Version :", health.data.version);

// Créez une session et posez une question
const session = await opencode.client.session.create({ body: { title: "Démonstration de démarrage rapide SDK" } });

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

console.log(result.data);

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

Exécuter :

node scripts/opencode-sdk-demo.mjs

Forme attendue de la sortie :

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

Configuration OpenCode minimale que vous pouvez copier

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

Créez opencode.jsonc à 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 modèle « petit » moins cher pour les tâches légères (titres, etc.)
  "small_model": "fournisseur/modèle-petit",

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

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

Feuille de triche 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 à la question
opencode models --refresh      # actualiser 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 un changement
/redo      # rétablir un changement
/help      # aide/raccourcis

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

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

Tableau de feuille de triche imprimable d’une seule page d’OpenCode

Cette version est intentionnellement dense et « imprimable ». (Vous pouvez la coller ultérieurement sur une page dédiée /ai-devtools/opencode/cheatsheet/.)

Tâche Commande / raccourci Notes
Démarrer TUI opencode Le comportement par défaut est de lancer l’interface utilisateur du terminal
Exécuter un prompt one-shot opencode run "..." Mode non interactif pour le scripting/automatisation
Attacher des fichiers à un 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 provider/model "..." Les chaînes de modèles sont provider/model
Choisir un agent opencode run --agent plan "..." Plan est conçu pour un travail « sans changement » plus sûr (restreint par les permissions)
Lister les modèles opencode models [provider] Utilisez --refresh pour mettre à jour la liste 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 que 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 redémarrages répétés
Activer l’authentification de base OPENCODE_SERVER_PASSWORD=... opencode serve Le nom d’utilisateur par défaut est opencode sauf s’il est modifié
Mode interface web opencode web Démarrer le serveur + ouvrir le navigateur
Exporter une session opencode export [sessionID] Utile pour l’archivage ou le partage du contexte
Importer une session opencode import session.json Peut également importer à partir d’une URL de partage
Voir les drapeaux CLI globaux opencode --help / opencode --version --print-logs + --log-level pour le débogage
Concept de clé « leader » TUI clé leader par défaut souvent ctrl+x Personnalisable dans tui.json

Sources (officielles en premier)

Officielles :

Référence d’intégration autoritaire :

Comparaisons/tutoriels réputés :