Aller au contenu
OpenCode
app.header.homeapp.header.docs

Dépannage

Problèmes courants et comment les résoudre.

Pour déboguer les problèmes avec OpenCode, commencez par vérifier les journaux et les données locales qu’il stocke sur le disque.

Journaux

Les fichiers journaux sont écrits dans :

  • macOS/Linux : ~/.local/share/opencode/log/
  • Windows : appuyez sur WIN+R et collez %USERPROFILE%\.local\share\opencode\log

Les fichiers journaux sont nommés avec des horodatages (par exemple, 2025-01-09T123456.log) et les 10 fichiers journaux les plus récents sont conservés.

Vous pouvez définir le niveau de journalisation avec l’option de ligne de commande --log-level pour obtenir des informations de débogage plus détaillées. Par exemple, opencode --log-level DEBUG.

Stockage

opencode stocke les données de session et autres données d’application sur le disque à l’emplacement :

  • macOS/Linux : ~/.local/share/opencode/
  • Windows : appuyez sur WIN+R et collez %USERPROFILE%\.local\share\opencode

Ce répertoire contient :

  • auth.json - Données d’authentification telles que les clés API, les jetons OAuth
  • log/ - Journaux d’applications
  • project/ - Données spécifiques au projet telles que les données de session et de message
    • Si le projet se trouve dans un dépôt Git, il est stocké dans ./<project-slug>/storage/
    • S’il ne s’agit pas d’un dépôt Git, il est stocké dans ./global/storage/

Application de bureau

OpenCode Desktop exécute un serveur OpenCode local (le side-car opencode-cli) en arrière-plan. La plupart des problèmes sont causés par un plugin qui se comporte mal, un cache corrompu ou un mauvais paramètre du serveur.

Vérifications rapides

  • Quittez complètement et relancez l’application.
  • Si l’application affiche un écran d’erreur, cliquez sur Redémarrer et copiez les détails de l’erreur.
  • macOS uniquement : menu OpenCode -> Recharger la vue Web (aide si l’interface utilisateur est vide/gelée).

Désactiver les plugins

Si l’application de bureau plante au lancement, se bloque ou se comporte étrangement, commencez par désactiver les plugins.

Vérifiez la configuration globale

Ouvrez votre fichier de configuration global et recherchez une clé plugin.

  • macOS/Linux : ~/.config/opencode/opencode.jsonc (ou ~/.config/opencode/opencode.json)
  • macOS/Linux (anciennes installations) : ~/.local/share/opencode/opencode.jsonc
  • Windows : appuyez sur WIN+R et collez %USERPROFILE%\.config\opencode\opencode.jsonc

Si vous avez configuré des plugins, désactivez-les temporairement en supprimant la clé ou en la définissant sur un tableau vide :

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [],
}

Vérifiez les répertoires des plugins

OpenCode peut également charger des plugins locaux à partir du disque. Écartez-les temporairement (ou renommez le dossier) et redémarrez l’application de bureau :

  • Plugins mondiaux
    • macOS/Linux : ~/.config/opencode/plugins/
    • Windows : appuyez sur WIN+R et collez %USERPROFILE%\.config\opencode\plugins
  • Plugins de projet (uniquement si vous utilisez une configuration par projet)
    • <your-project>/.opencode/plugins/

Si l’application recommence à fonctionner, réactivez les plugins un par un pour trouver celui à l’origine du problème.

Vider le cache

Si la désactivation des plugins ne résout pas le problème (ou si l’installation d’un plugin est bloquée), videz le cache afin que OpenCode puisse le reconstruire.

  1. Quittez complètement OpenCode Desktop.
  2. Supprimez le répertoire cache :
  • macOS : Finder -> Cmd+Shift+G -> coller ~/.cache/opencode
  • Linux : supprimez ~/.cache/opencode (ou exécutez rm -rf ~/.cache/opencode)
  • Windows : appuyez sur WIN+R et collez %USERPROFILE%\.cache\opencode
  1. Redémarrez le bureau OpenCode.

Résoudre les problèmes de connexion au serveur

OpenCode Desktop peut soit démarrer son propre serveur local (par défaut), soit se connecter à un serveur URL que vous avez configuré.

Si vous voyez une boîte de dialogue « Échec de la connexion » (ou si l’application ne dépasse jamais l’écran de démarrage), recherchez un serveur personnalisé URL.

Effacer le serveur par défaut du bureau URL

Depuis l’écran d’accueil, cliquez sur le nom du serveur (avec le point d’état) pour ouvrir le sélecteur de serveur. Dans la section Serveur par défaut, cliquez sur Effacer.

Supprimez server.port / server.hostname de votre configuration

Si votre opencode.json(c) contient une section server, supprimez-la temporairement et redémarrez l’application de bureau.

Vérifier les variables d’environnement

Si OPENCODE_PORT est défini dans votre environnement, l’application de bureau tentera d’utiliser ce port pour le serveur local.

  • Désactivez OPENCODE_PORT (ou choisissez un port libre) et redémarrez.

Linux : Problèmes Wayland / X11

Sur Linux, certaines configurations Wayland peuvent provoquer des fenêtres vides ou des erreurs de composition.

  • Si vous êtes sur Wayland et que l’application est vide/plante, essayez de la lancer avec OC_ALLOW_WAYLAND=1.
  • Si cela aggrave les choses, supprimez-le et essayez plutôt de le lancer sous une session X11.

Windows : exécution WebView2

Sur Windows, OpenCode Desktop nécessite Microsoft Edge WebView2 Runtime. Si l’application s’ouvre sur une fenêtre vide ou ne démarre pas, installez/mettez à jour WebView2 et réessayez.

Windows : problèmes de performances généraux

Si vous rencontrez des performances lentes, des problèmes d’accès aux fichiers ou des problèmes de terminal sur Windows, essayez d’utiliser WSL (Windows Sous-système pour Linux). WSL fournit un environnement Linux qui fonctionne de manière plus transparente avec les fonctionnalités de OpenCode.

Les notifications ne s’affichent pas

OpenCode Desktop affiche uniquement les notifications système lorsque :

  • les notifications sont activées pour OpenCode dans les paramètres de votre système d’exploitation, et
  • la fenêtre de l’application n’est pas ciblée.

Réinitialiser le stockage des applications de bureau (dernier recours)

Si l’application ne démarre pas et que vous ne pouvez pas effacer les paramètres depuis l’interface utilisateur, réinitialisez l’état enregistré de l’application de bureau.

  1. Quittez le bureau OpenCode.
  2. Recherchez et supprimez ces fichiers (ils se trouvent dans le répertoire de données de l’application OpenCode Desktop) :
  • opencode.settings.dat (serveur de bureau par défaut URL)
  • opencode.global.dat et opencode.workspace.*.dat (état de l’interface utilisateur comme les serveurs/projets récents)

Pour trouver rapidement le répertoire :

  • macOS : Finder -> Cmd+Shift+G -> ~/Library/Application Support (puis recherchez les noms de fichiers ci-dessus)
  • Linux : recherchez sous ~/.local/share les noms de fichiers ci-dessus
  • Windows : appuyez sur WIN+R -> %APPDATA% (puis recherchez les noms de fichiers ci-dessus)

Obtenir de l’aide

Si vous rencontrez des problèmes avec OpenCode :

  1. Signaler les problèmes le GitHub

La meilleure façon de signaler des bogues ou de demander des fonctionnalités consiste à utiliser notre référentiel GitHub :

github.com/anomalyco/opencode/issues

Avant de créer un nouveau problème, recherchez les problèmes existants pour voir si votre problème a déjà été signalé.

  1. Rejoignez notre Discord

Pour obtenir de l’aide en temps réel et une discussion communautaire, rejoignez notre serveur Discord :

opencode.ai/discord

Problèmes courants

Voici quelques problèmes courants et comment les résoudre.

OpenCode ne démarre pas

  1. Vérifiez les journaux pour les messages d’erreur
  2. Essayez d’exécuter avec --print-logs pour voir la sortie dans le terminal
  3. Assurez-vous d’avoir la dernière version avec opencode upgrade

Problèmes d’authentification

  1. Essayez de vous réauthentifier avec la commande /connect dans le TUI
  2. Vérifiez que vos clés API sont valides
  3. Assurez-vous que votre réseau autorise les connexions au API du fournisseur.

Modèle non disponible

  1. Vérifiez que vous êtes authentifié auprès du fournisseur
  2. Vérifiez que le nom du modèle dans votre configuration est correct
  3. Certains modèles peuvent nécessiter un accès ou des abonnements spécifiques

Si vous rencontrez ProviderModelNotFoundError, vous avez probablement tort faire référence à un modèle quelque part. Les modèles doivent être référencés comme suit : <providerId>/<modelId>

Exemples :

  • openai/gpt-4.1
  • openrouter/google/gemini-2.5-flash
  • opencode/kimi-k2

Pour déterminer à quels modèles vous avez accès, exécutez opencode models

ErreurInit du fournisseur

Si vous rencontrez une ProviderInitError, vous avez probablement une configuration non valide ou corrompue.

Pour résoudre ce problème :

  1. Tout d’abord, vérifiez que votre fournisseur est correctement configuré en suivant le guide du fournisseur

  2. Si le problème persiste, essayez d’effacer votre configuration stockée :

    Fenêtre de terminal
    rm -rf ~/.local/share/opencode

Sur Windows, appuyez sur WIN+R et supprimez : %USERPROFILE%\.local\share\opencode

  1. Ré-authentifiez-vous auprès de votre fournisseur à l’aide de la commande /connect dans le TUI.

Problèmes liés à AI_APICallError et au package du fournisseur

Si vous rencontrez des erreurs d’appel API, cela peut être dû à des packages de fournisseurs obsolètes. opencode installe dynamiquement les packages du fournisseur (OpenAI, Anthropic, Google, etc.) selon les besoins et les met en cache localement.

Pour résoudre les problèmes liés au package du fournisseur :

  1. Videz le cache du package du fournisseur :

    Fenêtre de terminal
    rm -rf ~/.cache/opencode

Sur Windows, appuyez sur WIN+R et supprimez : %USERPROFILE%\.cache\opencode

  1. Redémarrez opencode pour réinstaller les derniers packages du fournisseur

Cela forcera opencode à télécharger les versions les plus récentes des packages du fournisseur, ce qui résout souvent les problèmes de compatibilité avec les paramètres du modèle et les modifications de API.

Le copier/coller ne fonctionne pas sur Linux

Les utilisateurs de Linux doivent disposer de l’un des utilitaires de presse-papiers suivants installés pour que la fonctionnalité copier/coller fonctionne :

Pour les systèmes X11 :

Fenêtre de terminal
apt install -y xclip
# or
apt install -y xsel

Pour les systèmes Wayland :

Fenêtre de terminal
apt install -y wl-clipboard

Pour les environnements sans tête :

Fenêtre de terminal
apt install -y xvfb
# and run:
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0

opencode détectera si vous utilisez Wayland et préférez wl-clipboard, sinon il essaiera de trouver les outils du presse-papiers dans l’ordre : xclip et xsel.