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).

Remarque sur les versions : OpenCode évolue rapidement. Les commandes « latest » ici sont stables, mais les sorties 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 de Outils d’IA pour développeurs : Le guide complet des outils d’IA pour le développement.

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

OpenCode est conçu pour le codage agentic en premier lieu, via le terminal, tout en restant flexible en matière 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 programmatoire 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 une option forte pour un sous-cluster car il s’adapte naturellement à :

  • une immersion profonde en CLI
  • le comportement et les coûts des modèles/fournisseurs (comparaison des LLM dans OpenCode)
  • la configuration & les agents
  • les intégrations (GitHub/GitLab/Copilot)
  • un guide de trucs et astuces

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).

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 via 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é). Les 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érifier 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/subcommandes disponibles>

Se connecter à un fournisseur (deux chemins pratiques)

Chemin A : /connect via TUI (interactif)

Démarrer OpenCode :

opencode

Puis exécuter :

/connect

Suivre les étapes de l’interface utilisateur pour sélectionner un fournisseur et vous authentifier (certaines flux ouvrent un navigateur/connexion appareil).

Chemin B : CLI opencode auth login (clés 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 depuis les variables d’environnement ou un fichier .env dans votre projet.

Démarrer un projet correctement (recommandé pour la première utilisation)

À partir de votre dépôt :

cd /chemin/vers/votre/dépôt
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 commiter ce fichier afin que OpenCode (et les collègues) partagent un contexte de projet cohérent.

Workflows CLI principaux (exemples copier-coller)

OpenCode prend en charge les exécutions non interactives :

opencode run "Expliquez comment les closures fonctionnent 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, analyser un entier, valider entre 1 et 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 éditions 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) risques/cas limites à tester. Ne lancez pas de commandes."

Sortie attendue :

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

Workflow : poser des questions sur un 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 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 répétées du CLI avec un serveur persistant

Si vous scriptez ou exécutez plusieurs opencode run, vous pouvez démarrer un serveur sans interface une 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 :

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

Utilisation programmatoire (SDK JS/TS officiel)

OpenCode expose un serveur HTTP (OpenAPI) et fournit un client JS/TS type-safe.

Installer :

npm install @opencode-ai/sdk

Exemple : démarrer le serveur + client, puis poser une question

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: {
    // 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 poser une question
const session = await opencode.client.session.create({ body: { title: "Démonstration rapide du SDK" } });

const result = await opencode.client.session.prompt({
  path: { id: session.data.id },
  body: {
    parts: [{ type: "text", text: "Générez une section courte de 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

Sortie attendue :

  • « 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 JSON et JSONC. C’est un point de départ raisonnable pour une configuration locale au projet.

Créer 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 coûteux 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é : exiger une confirmation avant les éditions/commandes
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Feuille de rappel minimale (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      # 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   # se 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 ».

FAQ

Qu’est-ce qu’OpenCode ?

OpenCode est un agent d’IA open source conçu pour fonctionner dans votre terminal (TUI + CLI) avec des surfaces supplémentaires de bureau/IDE.

OpenCode est-il gratuit ?

L’outil est open source. Le coût d’utilisation dépend du modèle/fournisseur auquel vous vous connectez. Certains fournisseurs peuvent proposer une authentification basée sur un abonnement ou des niveaux gratuits.

Comment exécuter OpenCode sans ouvrir le TUI ?

Utilisez opencode run "..." pour le mode non interactif (utile pour les scripts/automatisation).

Où OpenCode stocke-t-il les identifiants des fournisseurs ?

opencode auth login stocke les identifiants à ~/.local/share/opencode/auth.json.

OpenCode a-t-il une API / SDK ?

Oui. OpenCode peut exécuter un serveur HTTP sans interface (opencode serve) avec une spécification OpenAPI à /doc, et il fournit un SDK officiel JS/TS : @opencode-ai/sdk.

Puis-je utiliser GitHub Copilot avec OpenCode ?

GitHub a annoncé que Copilot prend en charge l’authentification avec OpenCode via une intégration formelle. La disponibilité exacte dépend de votre plan Copilot et du flux actuel d’authentification du fournisseur.

Tableau imprimable en une page de feuille de rappel OpenCode

Cette version est intentionnellement dense et « imprimable ». (Vous pouvez la coller plus tard 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 scriptage/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 modification » plus sûr (restrictions de permission)
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 à ~/.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 basique OPENCODE_SERVER_PASSWORD=... opencode serve Le nom d’utilisateur par défaut est opencode sauf si 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 depuis une URL de partage
Afficher les drapeaux CLI globaux opencode --help / opencode --version --print-logs + --log-level pour le débogage
Concept de « leader key » 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 :