Aller au contenu
Usage

Serveur

La commande opencode serve exécute un serveur HTTP sans tête qui expose un point de terminaison OpenAPI qu’un client opencode peut utiliser.

Terminal
opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]

Options

DrapeauDescriptifPar défaut
--portPort à écouter sur4096
--hostnameNom d’hôte sur lequel écouter127.0.0.1
--mdnsActiver la découverte mDNSfalse
--mdns-domainNom de domaine personnalisé pour le service mDNSopencode.local
--corsOrigines de navigateur supplémentaires à autoriser[]

--cors peut être transmis plusieurs fois :

Terminal
opencode serve --cors http://localhost:5173 --cors https://app.example.com

Définissez OPENCODE_SERVER_PASSWORD pour protéger le serveur avec l’authentification de base HTTP. Le nom d’utilisateur est par défaut opencode, ou définissez OPENCODE_SERVER_USERNAME pour le remplacer. Cela s’applique à la fois à opencode serve et à opencode web.

Terminal
OPENCODE_SERVER_PASSWORD=your-password opencode serve

Lorsque vous exécutez opencode, il démarre un TUI et un serveur. Où le TUI est le client qui parle au serveur. Le serveur expose une spécification OpenAPI 3.1 point final. Ce point de terminaison est également utilisé pour générer un SDK.

Cette architecture permet à opencode de prendre en charge plusieurs clients et vous permet d’interagir avec opencode par programme.

Vous pouvez exécuter opencode serve pour démarrer un serveur autonome. Si vous avez le opencode TUI en cours d’exécution, opencode serve démarrera un nouveau serveur.

Connectez-vous à un serveur existant

Lorsque vous démarrez le TUI, il attribue de manière aléatoire un port et un nom d’hôte. Vous pouvez à la place transmettre les --hostname et --port flags. Utilisez-le ensuite pour vous connecter à son serveur.

Le point de terminaison /tui peut être utilisé pour piloter le TUI via le serveur. Par exemple, vous pouvez pré-remplir ou exécuter une invite. Cette configuration est utilisée par les plugins OpenCode IDE.

Le serveur publie une spécification OpenAPI 3.1 qui peut être consultée à l’adresse :

http://<hostname>:<port>/doc

Par exemple, http://localhost:4096/doc. Utilisez la spécification pour générer des clients ou inspecter les types de requêtes et de réponses. Ou visualisez-le dans un explorateur Swagger.

Le serveur opencode expose les API suivantes.

MéthodeCheminDescriptifRéponse
GET/global/healthObtenir l’état et la version du serveur{ healthy: true, version: string }
GET/global/eventObtenez des événements mondiaux (flux SSE)Flux d’événements

MéthodeCheminDescriptifRéponse
GET/projectLister tous les projetsProject[]
GET/project/currentObtenez le projet en coursProject

MéthodeCheminDescriptifRéponse
GET/pathObtenir le chemin actuelPath
GET/vcsObtenir des informations VCS pour le projet en coursVcsInfo

MéthodeCheminDescriptifRéponse
POST/instance/disposeSupprimer l’instance actuelleboolean

MéthodeCheminDescriptifRéponse
GET/configObtenir des informations de configurationConfig
PATCH/configMettre à jour la configurationConfig
GET/config/providersListe des fournisseurs et modèles par défaut{ providers: Provider[], default: { [key: string]: string } }

MéthodeCheminDescriptifRéponse
GET/providerListe de tous les fournisseurs{ all: Provider[], default: {...}, connected: string[] }
GET/provider/authObtenir les méthodes d’authentification du fournisseur{ [providerID: string]: ProviderAuthMethod[] }
POST/provider/{id}/oauth/authorizeAutoriser un fournisseur en utilisant OAuthProviderAuthAuthorization
POST/provider/{id}/oauth/callbackGérer le rappel OAuth pour un fournisseurboolean

MéthodeCheminDescriptifRemarques
GET/sessionListe toutes les sessionsRenvoie Session[]
POST/sessionCréer une nouvelle sessioncorps : { parentID?, title? }, renvoie Session
GET/session/statusObtenir l’état de la session pour toutes les sessionsRenvoie { [sessionID: string]: SessionStatus }
GET/session/:idObtenez les détails de la sessionRenvoie Session
DELETE/session/:idSupprimer une session et toutes ses donnéesRenvoie boolean
PATCH/session/:idMettre à jour les propriétés de la sessioncorps : { title? }, renvoie Session
GET/session/:id/childrenObtenir les sessions enfants d’une sessionRenvoie Session[]
POST/session/:id/initAnalysez l’application et créez AGENTS.mdcorps : { messageID, providerID, modelID }, renvoie boolean
POST/session/:id/forkForkez une session existante à un messagecorps : { messageID? }, renvoie Session
POST/session/:id/abortAbandonner une session en coursRenvoie boolean
GET/session/:id/diffObtenez le diff pour cette sessionrequête : messageID?, renvoie FileDiff[]
POST/session/:id/summarizeRésumer la séancecorps : { providerID, modelID }, renvoie boolean
POST/session/:id/revertRétablir un messagecorps : { messageID, partID? }, renvoie boolean
POST/session/:id/unrevertRestaurer tous les messages annulésRenvoie boolean
POST/session/:id/permissions/:permissionIDRépondre à une demande d’autorisationcorps : { response, remember? }, renvoie boolean

MéthodeCheminDescriptifRemarques
GET/session/:id/messageListe des messages dans une sessionrequête : limit?, renvoie { info: Message, parts: Part[]}[]
POST/session/:id/messageEnvoyer un message et attendre une réponsecorps : { messageID?, model?, agent?, noReply?, system?, tools?, parts }, renvoie { info: Message, parts: Part[]}
GET/session/:id/message/:messageIDObtenir les détails du messageRenvoie { info: Message, parts: Part[]}
POST/session/:id/prompt_asyncEnvoyer un message de manière asynchrone (pas d’attente)body : identique à /session/:id/message, renvoie 204 No Content
POST/session/:id/commandExécuter une commande slashcorps : { messageID?, agent?, model?, command, arguments }, renvoie { info: Message, parts: Part[]}
POST/session/:id/shellExécuter une commande shellcorps : { agent, model?, command }, renvoie { info: Message, parts: Part[]}

MéthodeCheminDescriptifRéponse
GET/commandListe toutes les commandesCommand[]

MéthodeCheminDescriptifRéponse
GET/find?pattern=<pat>Rechercher du texte dans des fichiersTableau d’objets correspondant avec path, lines, line_number, absolute_offset, submatches
GET/find/file?query=<q>Rechercher des fichiers et des répertoires par nomstring[] (chemins)
GET/find/symbol?query=<q>Rechercher des symboles d’espace de travailSymbol[]
GET/file?path=<path>Liste des fichiers et répertoiresFileNode[]
GET/file/content?path=<p>Lire un fichierFileContent
GET/file/statusObtenir le statut des fichiers suivisFile[]

Paramètres de requête /find/file

  • query (obligatoire) — chaîne de recherche (correspondance floue)
  • type (facultatif) — limiter les résultats à "file" ou "directory"
  • directory (facultatif) — remplace la racine du projet pour la recherche
  • limit (facultatif) — résultats maximum (1 à 200)
  • dirs (facultatif) — indicateur hérité ("false" renvoie uniquement les fichiers)

MéthodeCheminDescriptifRéponse
GET/experimental/tool/idsRépertorier tous les ID d’outilsToolIDs
GET/experimental/tool?provider=<p>&model=<m>Répertorier les outils avec des schémas JSON pour un modèleToolList

MéthodeCheminDescriptifRéponse
GET/lspObtenir l’état du serveur LSPLSPStatus[]
GET/formatterObtenir le statut du formateurFormatterStatus[]
GET/mcpObtenir l’état du serveur MCP{ [name: string]: MCPStatus }
POST/mcpAjouter dynamiquement le serveur MCPcorps : { name, config }, renvoie l’objet d’état MCP

MéthodeCheminDescriptifRéponse
GET/agentListe tous les agents disponiblesAgent[]

MéthodeCheminDescriptifRéponse
POST/logÉcrire une entrée de journal. Corps : { service, level, message, extra? }boolean

MéthodeCheminDescriptifRéponse
POST/tui/append-promptAjouter du texte à l’inviteboolean
POST/tui/open-helpOuvrir la boîte de dialogue d’aideboolean
POST/tui/open-sessionsOuvrez le sélecteur de sessionboolean
POST/tui/open-themesOuvrez le sélecteur de thèmeboolean
POST/tui/open-modelsOuvrez le sélecteur de modèleboolean
POST/tui/submit-promptSoumettre l’invite actuelleboolean
POST/tui/clear-promptEffacez l’inviteboolean
POST/tui/execute-commandExécuter une commande ({ command })boolean
POST/tui/show-toastAfficher le toast ({ title?, message, variant })boolean
GET/tui/control/nextAttendre la prochaine demande de contrôleObjet de demande de contrôle
POST/tui/control/responseRépondre à une demande de contrôle ({ body })boolean

MéthodeCheminDescriptifRéponse
PUT/auth/:idDéfinissez les informations d’authentification. Le corps doit correspondre au schéma du fournisseurboolean

MéthodeCheminDescriptifRéponse
GET/eventFlux d’événements envoyés par le serveur. Le premier événement est server.connected, puis les événements de busFlux d’événements envoyés par le serveur

MéthodeCheminDescriptifRéponse
GET/docSpécification OpenAPI 3.1Page HTML avec spécification OpenAPI