Buckets:

GHHG10
/

CodeServer

Files

xet

GHHG10/CodeServer / opencode /packages /web /src /content /docs /pt-br /server.mdx

GHHG10

about 2 months ago

download

raw

19.9 kB

	---
	title: Servidor
	description: Interaja com o servidor opencode via HTTP.
	---

	import config from "../../../../config.mjs"
	export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types.gen.ts`

	O comando `opencode serve` executa um servidor HTTP sem cabeça que expõe um endpoint OpenAPI que um cliente opencode pode usar.

	---

	### Uso

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

	#### Opções

	\| Flag \| Descrição \| Padrão \|
	\| --------------- \| ------------------------------------------------- \| ---------------- \|
	\| `--port` \| Porta para escutar \| `4096` \|
	\| `--hostname` \| Nome do host para escutar \| `127.0.0.1` \|
	\| `--mdns` \| Habilitar descoberta mDNS \| `false` \|
	\| `--mdns-domain` \| Nome de domínio personalizado para o serviço mDNS \| `opencode.local` \|
	\| `--cors` \| Origens adicionais de navegador a permitir \| `[]` \|

	`--cors` pode ser passado várias vezes:

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

	---

	### Autenticação

	Defina `OPENCODE_SERVER_PASSWORD` para proteger o servidor com autenticação básica HTTP. O nome de usuário padrão é `opencode`, ou defina `OPENCODE_SERVER_USERNAME` para substituí-lo. Isso se aplica tanto ao `opencode serve` quanto ao `opencode web`.

	```bash
	OPENCODE_SERVER_PASSWORD=your-password opencode serve
	```

	---

	### Como funciona

	Quando você executa `opencode`, ele inicia um TUI e um servidor. Onde o TUI é o cliente que se comunica com o servidor. O servidor expõe um endpoint de especificação OpenAPI 3.1. Este endpoint também é usado para gerar um [SDK](/docs/sdk).

	:::tip
	Use o servidor opencode para interagir com o opencode programaticamente.
	:::

	Essa arquitetura permite que o opencode suporte múltiplos clientes e permite que você interaja com o opencode programaticamente.

	Você pode executar `opencode serve` para iniciar um servidor autônomo. Se você tiver o TUI do opencode em execução, `opencode serve` iniciará um novo servidor.

	---

	#### Conectar a um servidor existente

	Quando você inicia o TUI, ele atribui aleatoriamente uma porta e um nome de host. Você pode passar os [flags](/docs/cli) `--hostname` e `--port`. Em seguida, use isso para se conectar ao seu servidor.

	O endpoint [`/tui`](#tui) pode ser usado para controlar o TUI através do servidor. Por exemplo, você pode preencher ou executar um prompt. Essa configuração é usada pelos plugins do opencode [IDE](/docs/ide).

	---

	## Especificação

	O servidor publica uma especificação OpenAPI 3.1 que pode ser visualizada em:

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

	Por exemplo, `http://localhost:4096/doc`. Use a especificação para gerar clientes ou inspecionar tipos de requisição e resposta. Ou visualize em um explorador Swagger.

	---

	## APIs

	O servidor opencode expõe as seguintes APIs.

	---

	### Global

	\| Método \| Caminho \| Descrição \| Resposta \|
	\| ------ \| ---------------- \| --------------------------------- \| ------------------------------------ \|
	\| `GET` \| `/global/health` \| Obter saúde e versão do servidor \| `{ healthy: true, version: string }` \|
	\| `GET` \| `/global/event` \| Obter eventos globais (fluxo SSE) \| Fluxo de eventos \|

	---

	### Projeto

	\| Método \| Caminho \| Descrição \| Resposta \|
	\| ------ \| ------------------ \| ------------------------ \| --------------------------------------------- \|
	\| `GET` \| `/project` \| Listar todos os projetos \| <a href={typesUrl}><code>Project[]</code></a> \|
	\| `GET` \| `/project/current` \| Obter o projeto atual \| <a href={typesUrl}><code>Project</code></a> \|

	---

	### Caminho & VCS

	\| Método \| Caminho \| Descrição \| Resposta \|
	\| ------ \| ------- \| --------------------------------------------- \| ------------------------------------------- \|
	\| `GET` \| `/path` \| Obter o caminho atual \| <a href={typesUrl}><code>Path</code></a> \|
	\| `GET` \| `/vcs` \| Obter informações do VCS para o projeto atual \| <a href={typesUrl}><code>VcsInfo</code></a> \|

	---

	### Instância

	\| Método \| Caminho \| Descrição \| Resposta \|
	\| ------ \| ------------------- \| --------------------------- \| --------- \|
	\| `POST` \| `/instance/dispose` \| Descartar a instância atual \| `boolean` \|

	---

	### Configuração

	\| Método \| Caminho \| Descrição \| Resposta \|
	\| ------- \| ------------------- \| ---------------------------------- \| ---------------------------------------------------------------------------------------- \|
	\| `GET` \| `/config` \| Obter informações de configuração \| <a href={typesUrl}><code>Config</code></a> \|
	\| `PATCH` \| `/config` \| Atualizar configuração \| <a href={typesUrl}><code>Config</code></a> \|
	\| `GET` \| `/config/providers` \| Listar provedores e modelos padrão \| `{ providers: `<a href={typesUrl}>Provider[]</a>`, default: { [key: string]: string } }` \|

	---

	### Provedor

	\| Método \| Caminho \| Descrição \| Resposta \|
	\| ------ \| -------------------------------- \| ------------------------------------------- \| ----------------------------------------------------------------------------------- \|
	\| `GET` \| `/provider` \| Listar todos os provedores \| `{ all: `<a href={typesUrl}>Provider[]</a>`, default: {...}, connected: string[] }` \|
	\| `GET` \| `/provider/auth` \| Obter métodos de autenticação do provedor \| `{ [providerID: string]: `<a href={typesUrl}>ProviderAuthMethod[]</a>` }` \|
	\| `POST` \| `/provider/{id}/oauth/authorize` \| Autorizar um provedor usando OAuth \| <a href={typesUrl}><code>ProviderAuthAuthorization</code></a> \|
	\| `POST` \| `/provider/{id}/oauth/callback` \| Lidar com o callback OAuth para um provedor \| `boolean` \|

	---

	### Sessões

	\| Método \| Caminho \| Descrição \| Notas \|
	\| -------- \| ---------------------------------------- \| ----------------------------------------------------- \| ----------------------------------------------------------------------------------- \|
	\| `GET` \| `/session` \| Listar todas as sessões \| Retorna <a href={typesUrl}><code>Session[]</code></a> \|
	\| `POST` \| `/session` \| Criar uma nova sessão \| corpo: `{ parentID?, title? }`, retorna <a href={typesUrl}><code>Session</code></a> \|
	\| `GET` \| `/session/status` \| Obter status da sessão para todas as sessões \| Retorna `{ [sessionID: string]: `<a href={typesUrl}>SessionStatus</a>` }` \|
	\| `GET` \| `/session/:id` \| Obter detalhes da sessão \| Retorna <a href={typesUrl}><code>Session</code></a> \|
	\| `DELETE` \| `/session/:id` \| Deletar uma sessão e todos os seus dados \| Retorna `boolean` \|
	\| `PATCH` \| `/session/:id` \| Atualizar propriedades da sessão \| corpo: `{ title? }`, retorna <a href={typesUrl}><code>Session</code></a> \|
	\| `GET` \| `/session/:id/children` \| Obter as sessões filhas de uma sessão \| Retorna <a href={typesUrl}><code>Session[]</code></a> \|
	\| `GET` \| `/session/:id/todo` \| Obter a lista de tarefas para uma sessão \| Retorna <a href={typesUrl}><code>Todo[]</code></a> \|
	\| `POST` \| `/session/:id/init` \| Analisar o app e criar `AGENTS.md` \| corpo: `{ messageID, providerID, modelID }`, retorna `boolean` \|
	\| `POST` \| `/session/:id/fork` \| Fazer um fork de uma sessão existente em uma mensagem \| corpo: `{ messageID? }`, retorna <a href={typesUrl}><code>Session</code></a> \|
	\| `POST` \| `/session/:id/abort` \| Abortar uma sessão em execução \| Retorna `boolean` \|
	\| `POST` \| `/session/:id/share` \| Compartilhar uma sessão \| Retorna <a href={typesUrl}><code>Session</code></a> \|
	\| `DELETE` \| `/session/:id/share` \| Descompartilhar uma sessão \| Retorna <a href={typesUrl}><code>Session</code></a> \|
	\| `GET` \| `/session/:id/diff` \| Obter a diferença para esta sessão \| query: `messageID?`, retorna <a href={typesUrl}><code>FileDiff[]</code></a> \|
	\| `POST` \| `/session/:id/summarize` \| Resumir a sessão \| corpo: `{ providerID, modelID }`, retorna `boolean` \|
	\| `POST` \| `/session/:id/revert` \| Reverter uma mensagem \| corpo: `{ messageID, partID? }`, retorna `boolean` \|
	\| `POST` \| `/session/:id/unrevert` \| Restaurar todas as mensagens revertidas \| Retorna `boolean` \|
	\| `POST` \| `/session/:id/permissions/:permissionID` \| Responder a um pedido de permissão \| corpo: `{ response, remember? }`, retorna `boolean` \|

	---

	### Mensagens

	\| Método \| Caminho \| Descrição \| Notas \|
	\| ------ \| --------------------------------- \| ------------------------------------------- \| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- \|
	\| `GET` \| `/session/:id/message` \| Listar mensagens em uma sessão \| query: `limit?`, retorna `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}[]` \|
	\| `POST` \| `/session/:id/message` \| Enviar uma mensagem e aguardar resposta \| corpo: `{ messageID?, model?, agent?, noReply?, system?, tools?, parts }`, retorna `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` \|
	\| `GET` \| `/session/:id/message/:messageID` \| Obter detalhes da mensagem \| Retorna `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` \|
	\| `POST` \| `/session/:id/prompt_async` \| Enviar uma mensagem assíncrona (sem espera) \| corpo: igual a `/session/:id/message`, retorna `204 No Content` \|
	\| `POST` \| `/session/:id/command` \| Executar um comando de barra \| corpo: `{ messageID?, agent?, model?, command, arguments }`, retorna `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` \|
	\| `POST` \| `/session/:id/shell` \| Executar um comando shell \| corpo: `{ agent, model?, command }`, retorna `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` \|

	---

	### Comandos

	\| Método \| Caminho \| Descrição \| Resposta \|
	\| ------ \| ---------- \| ------------------------ \| --------------------------------------------- \|
	\| `GET` \| `/command` \| Listar todos os comandos \| <a href={typesUrl}><code>Command[]</code></a> \|

	---

	### Arquivos

	\| Método \| Caminho \| Descrição \| Resposta \|
	\| ------ \| ------------------------ \| ---------------------------------------- \| ------------------------------------------------------------------------------------------------------- \|
	\| `GET` \| `/find?pattern=<pat>` \| Pesquisar texto em arquivos \| Array de objetos de correspondência com `path`, `lines`, `line_number`, `absolute_offset`, `submatches` \|
	\| `GET` \| `/find/file?query=<q>` \| Encontrar arquivos e diretórios por nome \| `string[]` (caminhos) \|
	\| `GET` \| `/find/symbol?query=<q>` \| Encontrar símbolos do workspace \| <a href={typesUrl}><code>Symbol[]</code></a> \|
	\| `GET` \| `/file?path=<path>` \| Listar arquivos e diretórios \| <a href={typesUrl}><code>FileNode[]</code></a> \|
	\| `GET` \| `/file/content?path=<p>` \| Ler um arquivo \| <a href={typesUrl}><code>FileContent</code></a> \|
	\| `GET` \| `/file/status` \| Obter status para arquivos rastreados \| <a href={typesUrl}><code>File[]</code></a> \|

	#### Parâmetros de consulta `/find/file`

	- `query` (obrigatório) — string de pesquisa (correspondência difusa)
	- `type` (opcional) — limitar resultados a `"file"` ou `"directory"`
	- `directory` (opcional) — substituir a raiz do projeto para a pesquisa
	- `limit` (opcional) — resultados máximos (1–200)
	- `dirs` (opcional) — flag legada (`"false"` retorna apenas arquivos)

	---

	### Ferramentas (Experimental)

	\| Método \| Caminho \| Descrição \| Resposta \|
	\| ------ \| ------------------------------------------- \| --------------------------------------------------- \| -------------------------------------------- \|
	\| `GET` \| `/experimental/tool/ids` \| Listar todos os IDs de ferramentas \| <a href={typesUrl}><code>ToolIDs</code></a> \|
	\| `GET` \| `/experimental/tool?provider=<p>&model=<m>` \| Listar ferramentas com esquemas JSON para um modelo \| <a href={typesUrl}><code>ToolList</code></a> \|

	---

	### LSP, Formatadores & MCP

	\| Método \| Caminho \| Descrição \| Resposta \|
	\| ------ \| ------------ \| ------------------------------------ \| -------------------------------------------------------- \|
	\| `GET` \| `/lsp` \| Obter status do servidor LSP \| <a href={typesUrl}><code>LSPStatus[]</code></a> \|
	\| `GET` \| `/formatter` \| Obter status do formatador \| <a href={typesUrl}><code>FormatterStatus[]</code></a> \|
	\| `GET` \| `/mcp` \| Obter status do servidor MCP \| `{ [name: string]: `<a href={typesUrl}>MCPStatus</a>` }` \|
	\| `POST` \| `/mcp` \| Adicionar servidor MCP dinamicamente \| corpo: `{ name, config }`, retorna objeto de status MCP \|

	---

	### Agentes

	\| Método \| Caminho \| Descrição \| Resposta \|
	\| ------ \| -------- \| ----------------------------------- \| ------------------------------------------- \|
	\| `GET` \| `/agent` \| Listar todos os agentes disponíveis \| <a href={typesUrl}><code>Agent[]</code></a> \|

	---

	### Registro

	\| Método \| Caminho \| Descrição \| Resposta \|
	\| ------ \| ------- \| --------------------------------------------------------------------- \| --------- \|
	\| `POST` \| `/log` \| Escrever entrada de log. Corpo: `{ service, level, message, extra? }` \| `boolean` \|

	---

	### TUI

	\| Método \| Caminho \| Descrição \| Resposta \|
	\| ------ \| ----------------------- \| ---------------------------------------------- \| ---------------------------- \|
	\| `POST` \| `/tui/append-prompt` \| Anexar texto ao prompt \| `boolean` \|
	\| `POST` \| `/tui/open-help` \| Abrir o diálogo de ajuda \| `boolean` \|
	\| `POST` \| `/tui/open-sessions` \| Abrir o seletor de sessões \| `boolean` \|
	\| `POST` \| `/tui/open-themes` \| Abrir o seletor de temas \| `boolean` \|
	\| `POST` \| `/tui/open-models` \| Abrir o seletor de modelos \| `boolean` \|
	\| `POST` \| `/tui/submit-prompt` \| Enviar o prompt atual \| `boolean` \|
	\| `POST` \| `/tui/clear-prompt` \| Limpar o prompt \| `boolean` \|
	\| `POST` \| `/tui/execute-command` \| Executar um comando (`{ command }`) \| `boolean` \|
	\| `POST` \| `/tui/show-toast` \| Mostrar toast (`{ title?, message, variant }`) \| `boolean` \|
	\| `GET` \| `/tui/control/next` \| Aguardar o próximo pedido de controle \| Objeto de pedido de controle \|
	\| `POST` \| `/tui/control/response` \| Responder a um pedido de controle (`{ body }`) \| `boolean` \|

	---

	### Auth

	\| Método \| Caminho \| Descrição \| Resposta \|
	\| ------ \| ----------- \| ------------------------------------------------------------------------------------- \| --------- \|
	\| `PUT` \| `/auth/:id` \| Definir credenciais de autenticação. O corpo deve corresponder ao esquema do provedor \| `boolean` \|

	---

	### Eventos

	\| Método \| Caminho \| Descrição \| Resposta \|
	\| ------ \| -------- \| ------------------------------------------------------------------------------------------------------ \| --------------------------------------- \|
	\| `GET` \| `/event` \| Fluxo de eventos enviados pelo servidor. O primeiro evento é `server.connected`, depois eventos de bus \| Fluxo de eventos enviados pelo servidor \|

	---

	### Docs

	\| Método \| Caminho \| Descrição \| Resposta \|
	\| ------ \| ------- \| ------------------------- \| --------------------------------------- \|
	\| `GET` \| `/doc` \| Especificação OpenAPI 3.1 \| Página HTML com a especificação OpenAPI \|

Xet Storage Details

Size:: 19.9 kB
Xet hash:: ad038e97eaf38a835f96f4a4604dc28d28c8815dd018232552d223703e7aabcb

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.