Début rapide avec OpenCode : installer, configurer et utiliser l'agent de codage IA en ligne de commande

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 bureau et IDE optionnelles. Voici le Guide de démarrage rapide d’OpenCode : installation, vérification, connexion d’un modèle/fournisseur et exécution de workflows réels (CLI + API).

Note sur la version : OpenCode est livré 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 de développement IA : Le guide complet du développement assisté par IA.

Qu’est-ce qu’OpenCode (et sa place dans l’écosystème)

OpenCode est conçu pour le codage agentique centré sur le terminal, tout en restant flexible en termes de fournisseur/modèle. En pratique, c’est une couche de workflow qui peut :

  • lancer une interface utilisateur terminal (TUI) lorsque vous exécutez opencode
  • exécuter des invites « one-shot » non interactives 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 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 isolé, consultez le Guide de démarrage rapide de l’assistant de codage OpenHands.

Pour l’agent centré 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).
  • L’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 Windows (la guidance officielle recommande généralement WSL pour la meilleure compatibilité). Les alternatives incluent Scoop/Chocolatey ou npm.

# chocolatier (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

Sortie attendue (variera selon la version) :

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

Connecter un fournisseur (deux approches pratiques)

Approche A : TUI /connect (interactif)

Lancez OpenCode :

opencode

Puis exécutez :

/connect

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

Approche 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 dans ~/.local/share/opencode/auth.json.
  • OpenCode peut également charger les clés à partir de 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. 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 points de terminaison compatibles OpenAI, vous pouvez donc utiliser des modèles GGUF avec le même workflow. Si vous préférez un contrôle fin de la mémoire et du runtime, ou une pile plus légère sans Python (BTW, ollama est implémenté en Go), llama.cpp vaut le coup d’essai. 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 la 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 — en termes de tâches de codage et de 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)

Depos votre dépôt :

cd /path/to/your/repo
opencode

Puis initialisez :

/init

Cela analyse votre projet et crée un fichier AGENTS.md à la racine du projet. Il est généralement judicieux de committer ce fichier afin qu’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 "Explain how closures work in JavaScript"

Workflow : générer du code (CLI)

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

opencode run "Write a Go function ParsePort(envVar string, defaultPort int) (int, error). It should read the env var, parse an int, validate 1-65535, and return defaultPort if empty. Include 3 table-driven tests."

Sortie attendue :

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

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 \
  "Refactor this file to reduce complexity. Output: (1) a short plan, (2) a unified diff patch, (3) risks/edge-cases to test. Do not run commands."

Sortie attendue :

  • Une section de plan + un bloc de patch diff --git ... + une liste de contrôle de tests.
  • Le contenu varie. Si cela ne produit pas de diff, relancez l’invite : « Retournez uniquement un diff unifié » ou « Utilisez le format diff --git. »

Workflow : poser des questions au dépôt (CLI)

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

opencode run --agent explore \
  "In this repository, where is authentication validated for API requests? List likely files and explain the flow. If uncertain, say what you checked."

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.

Workflow : 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 fois :

Terminal 1 :

opencode serve --port 4096 --hostname 127.0.0.1

Terminal 2 :

opencode run --attach http://localhost:4096 "Summarize the repo structure and main entrypoints."
opencode run --attach http://localhost:4096 "Now propose 3 high-impact refactors and why."

Sortie attendue :

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

Utilisation programmatique (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émarrer serveur + client, puis inviter

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(`Server running at: ${opencode.server.url}`);

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

// Créer une session et inviter
const session = await opencode.client.session.create({ body: { title: "SDK quickstart demo" } });

const result = await opencode.client.session.prompt({
  path: { id: session.data.id },
  body: {
    parts: [{ type: "text", text: "Generate a small README section describing this repo." }],
  },
});

console.log(result.data);

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

Exécuter :

node scripts/opencode-sdk-demo.mjs

Forme de sortie attendue :

  • « Server running at … »
  • Une réponse de santé incluant une chaîne de version
  • Un objet de réponse d’invite de session (la structure exacte dépend de responseStyle et de la version du SDK)

Configuration OpenCode minimale à 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": "provider/model",

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

  // 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"
  }
}

Aide-mémoire 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 "..." # joindre des fichiers à l'invite
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 jetons/coût

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 (généralement ctrl+x) pour éviter les conflits terminaux. De nombreux raccourcis sont « Leader + touche ».

Tableau aide-mémoire OpenCode imprimable en 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 terminal
Exécuter une invite one-shot opencode run "..." Mode non interactif pour le scripting/automatisation
Joindre des fichiers à l’invite 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èle sont provider/model
Choisir un agent opencode run --agent plan "..." Plan est conçu pour un travail plus sûr « sans modifications » (restrictions de permission)
Lister les modèles opencode models [provider] 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
Joindre 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 remplacé
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 et l’orchestration multi-agent

Une fois OpenCode en cours d’exécution, l’étape naturelle suivante 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 invites sont optimisées.

Trois articles le couvrent en profondeur :

OpenCode a été l’un des premiers outils affectés par la politique d’Anthropic bloquant l’accès aux abonnements Claude tiers — une mesure prise en janvier 2026, un mois avant la même restriction pour OpenClaw. La chronologie de l’essor et de la chute d’OpenClaw documente les deux événements et le modèle plus large qu’ils représentent pour les outils d’agents construits sur le calcul par abonnement.

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.