Servidor
Interactúa con el servidor de opencode a través de HTTP.
El comando opencode serve ejecuta un servidor HTTP headless que expone un endpoint OpenAPI que un cliente de opencode puede usar.
Uso
opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]Opciones
| Opción | Descripción | Por defecto |
|---|---|---|
--port | Puerto en el que escuchar | 4096 |
--hostname | Nombre de host en el que escuchar | 127.0.0.1 |
--mdns | Habilita el descubrimiento mDNS | false |
--mdns-domain | Nombre de dominio personalizado para el servicio mDNS | opencode.local |
--cors | Orígenes de navegador adicionales a permitir | [] |
--cors se puede pasar varias veces:
opencode serve --cors http://localhost:5173 --cors https://app.example.comAutenticación
Establece OPENCODE_SERVER_PASSWORD para proteger el servidor con autenticación básica HTTP. El nombre de usuario por defecto es opencode, o establece OPENCODE_SERVER_USERNAME para anularlo. Esto se aplica tanto a opencode serve como a opencode web.
OPENCODE_SERVER_PASSWORD=your-password opencode serveCómo funciona
Cuando ejecutas opencode, este inicia una TUI y un servidor, donde la TUI es el cliente que se comunica con el servidor. El servidor expone un endpoint de especificación OpenAPI 3.1. Este endpoint también se usa para generar un SDK.
Consejo: Usa el servidor de opencode para interactuar con opencode de forma programática.
Esta arquitectura permite que opencode admita varios clientes y te permite interactuar con opencode de forma programática.
Puedes ejecutar opencode serve para iniciar un servidor independiente. Si tienes la TUI de opencode en ejecución, opencode serve iniciará un nuevo servidor.
Conectar a un servidor existente
Cuando inicias la TUI, esta asigna aleatoriamente un puerto y un nombre de host. En su lugar, puedes pasar las opciones --hostname y --port. Luego usa esto para conectarte a su servidor.
El endpoint /tui se puede usar para controlar la TUI a través del servidor. Por ejemplo, puedes prellenar o ejecutar un prompt. Esta configuración la usan los plugins del IDE de OpenCode.
Especificación
El servidor publica una especificación OpenAPI 3.1 que se puede ver en:
http://<hostname>:<port>/docPor ejemplo, http://localhost:4096/doc. Usa la especificación para generar clientes o inspeccionar los tipos de solicitud y respuesta. O visualízala en un explorador de Swagger.
APIs
El servidor de opencode expone las siguientes APIs.
Global
| Método | Ruta | Descripción | Respuesta |
|---|---|---|---|
GET | /global/health | Obtiene el estado y la versión del servidor | { healthy: true, version: string } |
GET | /global/event | Obtiene los eventos globales (flujo SSE) | Flujo de eventos |
Project
| Método | Ruta | Descripción | Respuesta |
|---|---|---|---|
GET | /project | Lista todos los proyectos | Project[] (opens in a new tab) |
GET | /project/current | Obtiene el proyecto actual | Project (opens in a new tab) |
Path y VCS
| Método | Ruta | Descripción | Respuesta |
|---|---|---|---|
GET | /path | Obtiene la ruta actual | Path (opens in a new tab) |
GET | /vcs | Obtiene la información de VCS del proyecto actual | VcsInfo (opens in a new tab) |
Instance
| Método | Ruta | Descripción | Respuesta |
|---|---|---|---|
POST | /instance/dispose | Desecha la instancia actual | boolean |
Config
| Método | Ruta | Descripción | Respuesta |
|---|---|---|---|
GET | /config | Obtiene la información de configuración | Config (opens in a new tab) |
PATCH | /config | Actualiza la configuración | Config (opens in a new tab) |
GET | /config/providers | Lista los proveedores y los modelos por defecto | { providers: Provider[] (opens in a new tab), default: { [key: string]: string } } |
Provider
| Método | Ruta | Descripción | Respuesta |
|---|---|---|---|
GET | /provider | Lista todos los proveedores | { all: Provider[] (opens in a new tab), default: {...}, connected: string[] } |
GET | /provider/auth | Obtiene los métodos de autenticación de los proveedores | { [providerID: string]: ProviderAuthMethod[] (opens in a new tab) } |
POST | /provider/{id}/oauth/authorize | Autoriza un proveedor usando OAuth | ProviderAuthAuthorization (opens in a new tab) |
POST | /provider/{id}/oauth/callback | Gestiona el callback de OAuth de un proveedor | boolean |
Sessions
| Método | Ruta | Descripción | Notas |
|---|---|---|---|
GET | /session | Lista todas las sesiones | Devuelve Session[] (opens in a new tab) |
POST | /session | Crea una nueva sesión | body: { parentID?, title? }, devuelve Session (opens in a new tab) |
GET | /session/status | Obtiene el estado de todas las sesiones | Devuelve { [sessionID: string]: SessionStatus (opens in a new tab) } |
GET | /session/:id | Obtiene los detalles de la sesión | Devuelve Session (opens in a new tab) |
DELETE | /session/:id | Elimina una sesión y todos sus datos | Devuelve boolean |
PATCH | /session/:id | Actualiza las propiedades de la sesión | body: { title? }, devuelve Session (opens in a new tab) |
GET | /session/:id/children | Obtiene las sesiones hijas de una sesión | Devuelve Session[] (opens in a new tab) |
GET | /session/:id/todo | Obtiene la lista de tareas de una sesión | Devuelve Todo[] (opens in a new tab) |
POST | /session/:id/init | Analiza la app y crea AGENTS.md | body: { messageID, providerID, modelID }, devuelve boolean |
POST | /session/:id/fork | Bifurca una sesión existente en un mensaje | body: { messageID? }, devuelve Session (opens in a new tab) |
POST | /session/:id/abort | Aborta una sesión en ejecución | Devuelve boolean |
POST | /session/:id/share | Comparte una sesión | Devuelve Session (opens in a new tab) |
DELETE | /session/:id/share | Deja de compartir una sesión | Devuelve Session (opens in a new tab) |
GET | /session/:id/diff | Obtiene el diff de esta sesión | query: messageID?, devuelve FileDiff[] (opens in a new tab) |
POST | /session/:id/summarize | Resume la sesión | body: { providerID, modelID }, devuelve boolean |
POST | /session/:id/revert | Revierte un mensaje | body: { messageID, partID? }, devuelve boolean |
POST | /session/:id/unrevert | Restaura todos los mensajes revertidos | Devuelve boolean |
POST | /session/:id/permissions/:permissionID | Responde a una solicitud de permiso | body: { response, remember? }, devuelve boolean |
Messages
| Método | Ruta | Descripción | Notas |
|---|---|---|---|
GET | /session/:id/message | Lista los mensajes de una sesión | query: limit?, devuelve { info: Message (opens in a new tab), parts: Part[] (opens in a new tab)}[] |
POST | /session/:id/message | Envía un mensaje y espera la respuesta | body: { messageID?, model?, agent?, noReply?, system?, tools?, parts }, devuelve { info: Message (opens in a new tab), parts: Part[] (opens in a new tab)} |
GET | /session/:id/message/:messageID | Obtiene los detalles del mensaje | Devuelve { info: Message (opens in a new tab), parts: Part[] (opens in a new tab)} |
POST | /session/:id/prompt_async | Envía un mensaje de forma asíncrona (sin esperar) | body: igual que /session/:id/message, devuelve 204 No Content |
POST | /session/:id/command | Ejecuta un comando slash | body: { messageID?, agent?, model?, command, arguments }, devuelve { info: Message (opens in a new tab), parts: Part[] (opens in a new tab)} |
POST | /session/:id/shell | Ejecuta un comando de shell | body: { agent, model?, command }, devuelve { info: Message (opens in a new tab), parts: Part[] (opens in a new tab)} |
Commands
| Método | Ruta | Descripción | Respuesta |
|---|---|---|---|
GET | /command | Lista todos los comandos | Command[] (opens in a new tab) |
Files
| Método | Ruta | Descripción | Respuesta |
|---|---|---|---|
GET | /find?pattern=<pat> | Busca texto en los archivos | Array de objetos de coincidencia con path, lines, line_number, absolute_offset, submatches |
GET | /find/file?query=<q> | Encuentra archivos y directorios por nombre | string[] (rutas) |
GET | /find/symbol?query=<q> | Encuentra símbolos del espacio de trabajo | Symbol[] (opens in a new tab) |
GET | /file?path=<path> | Lista archivos y directorios | FileNode[] (opens in a new tab) |
GET | /file/content?path=<p> | Lee un archivo | FileContent (opens in a new tab) |
GET | /file/status | Obtiene el estado de los archivos rastreados | File[] (opens in a new tab) |
Parámetros de consulta de /find/file
query(obligatorio) — cadena de búsqueda (coincidencia difusa)type(opcional) — limita los resultados a"file"o"directory"directory(opcional) — anula la raíz del proyecto para la búsquedalimit(opcional) — máximo de resultados (1-200)dirs(opcional) — opción heredada ("false"devuelve solo archivos)
Tools (Experimental)
| Método | Ruta | Descripción | Respuesta |
|---|---|---|---|
GET | /experimental/tool/ids | Lista todos los IDs de herramientas | ToolIDs (opens in a new tab) |
GET | /experimental/tool?provider=<p>&model=<m> | Lista las herramientas con esquemas JSON para un modelo | ToolList (opens in a new tab) |
LSP, Formateadores y MCP
| Método | Ruta | Descripción | Respuesta |
|---|---|---|---|
GET | /lsp | Obtiene el estado de los servidores LSP | LSPStatus[] (opens in a new tab) |
GET | /formatter | Obtiene el estado de los formateadores | FormatterStatus[] (opens in a new tab) |
GET | /mcp | Obtiene el estado de los servidores MCP | { [name: string]: MCPStatus (opens in a new tab) } |
POST | /mcp | Agrega un servidor MCP dinámicamente | body: { name, config }, devuelve un objeto de estado de MCP |
Agents
| Método | Ruta | Descripción | Respuesta |
|---|---|---|---|
GET | /agent | Lista todos los agentes disponibles | Agent[] (opens in a new tab) |
Logging
| Método | Ruta | Descripción | Respuesta |
|---|---|---|---|
POST | /log | Escribe una entrada de log. Body: { service, level, message, extra? } | boolean |
TUI
| Método | Ruta | Descripción | Respuesta |
|---|---|---|---|
POST | /tui/append-prompt | Agrega texto al prompt | boolean |
POST | /tui/open-help | Abre el diálogo de ayuda | boolean |
POST | /tui/open-sessions | Abre el selector de sesiones | boolean |
POST | /tui/open-themes | Abre el selector de temas | boolean |
POST | /tui/open-models | Abre el selector de modelos | boolean |
POST | /tui/submit-prompt | Envía el prompt actual | boolean |
POST | /tui/clear-prompt | Limpia el prompt | boolean |
POST | /tui/execute-command | Ejecuta un comando ({ command }) | boolean |
POST | /tui/show-toast | Muestra un toast ({ title?, message, variant }) | boolean |
GET | /tui/control/next | Espera la siguiente solicitud de control | Objeto de solicitud de control |
POST | /tui/control/response | Responde a una solicitud de control ({ body }) | boolean |
Auth
| Método | Ruta | Descripción | Respuesta |
|---|---|---|---|
PUT | /auth/:id | Establece las credenciales de autenticación. El body debe coincidir con el esquema del proveedor | boolean |
Events
| Método | Ruta | Descripción | Respuesta |
|---|---|---|---|
GET | /event | Flujo de eventos enviados por el servidor (SSE). El primer evento es server.connected, luego los eventos del bus | Flujo de eventos enviados por el servidor |
Docs
| Método | Ruta | Descripción | Respuesta |
|---|---|---|---|
GET | /doc | Especificación OpenAPI 3.1 | Página HTML con la especificación OpenAPI |