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

Note sur la version : OpenCode est publié rapidement. Les commandes « récentes » présentées ici sont stables, mais les sorties et les valeurs par défaut peuvent changer — vérifiez toujours la documentation CLI officielle 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 propulsé par l’IA. Si vous maintenez également un assistant auto-hébergé comme Nous Hermes, la fiche de triche CLI de l’agent Hermes présente l’ensemble de commandes hermes en parallèle de ce guide de démarrage rapide OpenCode.

Ce qu’est OpenCode (et sa place dans l’écosystème)

OpenCode est conçu pour le codage agentique axé sur le terminal, tout en restant flexible en matière de fournisseurs/modèles. En pratique, c’est une couche de flux de travail qui peut :

  • démarrer une interface utilisateur en terminal (TUI) lorsque vous exécutez opencode
  • exécuter des invites non interactives « one-shot » via opencode run (scripts/automatisation)
  • exposer un serveur HTTP sans interface graphique 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 le Guide de démarrage rapide de l’assistant de codage OpenHands.

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

Pour une approche délibérément minimale de l’idée du même agent terminal — quatre outils par défaut, pas de sandbox intégré, le reste via des extensions — consultez la critique de l’agent de codage Pi.

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

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 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 (les conseils officiels recommandent généralement 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

Format de sortie attendu (varie 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 approches pratiques)

Approche A : TUI /connect (interactif)

Démarrez OpenCode :

opencode

Puis exécutez :

/connect

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

Approche 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 de 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 points de terminaison 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 fin sur la mémoire et le temps d’exécution, ou souhaitez une pile plus légère sans Python (au fait, ollama est implémenté en Go), llama.cpp vaut le coup d’être essayé. J’ai vraiment apprécié l’occasion de configurer les couches déchargées, la facilité d’utilisation des modèles au format GGUF, et la compatibilité bien meilleure/plus rapide implémentée avec les nouveaux modèles, comme Qwen3.5. Si vous voulez savoir quels modèles fonctionnent réellement bien dans OpenCode — en matière 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 utile de committer ce fichier afin qu’OpenCode (et les coéquipiers) partagent un contexte de projet cohérent.

Flux de travail CLI de base (exemples à copier-coller)

OpenCode prend en charge les exécutions non interactives :

opencode run "Explain how closures work in JavaScript"

Pour les modèles de flux de travail en ligne de commande — acheminer la sortie git, cibles Makefile et CI, politiques de permissions pour les exécutions non surveillées — et les modes de défaillance à prévoir, consultez le guide pratique CLI OpenCode. Il s’appuie sur ce guide de démarrage rapide sans le répéter.

Flux de travail : 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 ainsi que des blocs de code (fonction + tests). Le code exact varie selon le modèle/fournisseur et l’invite.

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

Objectif : confirmer que l’agent plan plus restrictif s’exécute avant de vous en servir.

opencode run --agent plan --file ./src/auth.ts \
  "Refactor this file to reduce complexity. Output a short plan only. Do not run commands."

Sortie attendue : une section de plan, aucune modification de fichier, aucune commande exécutée.

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

Objectif : confirmer que l’agent explore peut localiser les détails d’implémentation.

opencode run --agent explore \
  "Where is authentication validated for API requests in this repository?"

Sortie attendue : une courte carte des chemins de fichiers et une description du flux.

Ces deux-là sont des tests de fumée one-shot. Pour la version production contrainte des mêmes tâches — sortie explicite des risques/cas limites, patchs unified-diff, invites d’exploration sensibles aux permissions, et quoi faire lorsque le modèle ne se conforme pas — consultez la section « Meilleurs cas d’utilisation CLI OpenCode » du guide pratique CLI OpenCode.

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 graphique une seule 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é.

Installation :

npm install @opencode-ai/sdk

Exemple : démarrer le serveur + client, puis envoyer une invite

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 la 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 envoyer une invite
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écution :

node scripts/opencode-sdk-demo.mjs

Format de sortie attendu :

  • « 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 minimale OpenCode à copier

OpenCode prend en charge les configurations JSON et JSONC. Voici 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 montre `opencode models`.
  "model": "provider/model",

  // Optionnel : un modèle « petit » 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é 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"
  }
}

Pour une politique de permissions plus complète visant les travaux opencode run non surveillés, consultez le guide pratique CLI OpenCode.

Fiche de triche courte (référence rapide)

Commandes que vous utiliserez quotidiennement

opencode                       # démarrer la 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 graphique (OpenAPI)
opencode web                   # serveur sans interface graphique + interface web
opencode session list          # lister les sessions
opencode stats                 # statistiques de jetons/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 (généralement ctrl+x) pour éviter les conflits de terminal. De nombreux raccourcis sont « Leader + touche ».

Tableau de fiche de triche OpenCode imprimable sur une page

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

Tâche Commande / raccourci Notes
Démarrer la TUI opencode Le comportement par défaut est de lancer l’interface utilisateur du 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 fournisseur/modèle
Choisir un agent opencode run --agent plan "..." Plan est conçu pour un travail plus sûr « sans modifications » (permissions restreintes)
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 voit OpenCode
Démarrer un serveur sans interface graphique opencode serve --port 4096 --hostname 127.0.0.1 Spécification OpenAPI sur 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 modifié
Mode interface web opencode web Démarre le serveur + ouvre le navigateur
Exporter une session opencode export [sessionID] Utile pour archiver ou partager le contexte
Importer une session opencode import session.json Peut aussi 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 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-agents

Une fois OpenCode en fonctionnement, l’étape suivante naturelle est Oh My Opencode — un plugin communautaire qui enveloppe OpenCode dans un harnais multi-agents. L’idée principale : taper ultrawork (ou ulw) dans une session et un orchestrateur (Sisyphus) prend le relais, en 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 couvrent le sujet en profondeur :

OpenCode a été l’un des premiers outils touchés par la politique d’Anthropic de bloquer l’accès par des tiers aux abonnements Claude — une mesure prise en janvier 2026, un mois avant que la même restriction ne frappe OpenClaw. La chronologie de la montée et de la chute d’OpenClaw documente ces deux événements et le schéma plus large qu’ils représentent pour les outils agentiques construits sur un calcul par abonnement.

Sources (officielles en premier)

Officielles :

Référence d’intégration faisant autorité :

Comparaisons/tutoriels réputés :

S'abonner

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