"}
```
O campo `user` é opcional: quando omitido ou vazio, o nome de usuário usa como padrão a [configuração do servidor](/pt-BR/reference/settings/server-settings/settings) `default_session_user` (ou sua sobrescrita por endpoint em uma configuração de [protocolos componíveis](/pt-BR/concepts/features/configuration/server-config/composable-protocols)), que é `default`, salvo configuração em contrário. Se `default_session_user` for definido como uma string vazia, conexões sem nome de usuário serão proibidas: uma mensagem `auth` com `user` omitido ou vazio falha na autenticação, o servidor fecha o WebSocket com o código `1008` e, quando a seção `session_log` está habilitada na configuração do servidor, a recusa é registrada em [`system.session_log`](/pt-BR/reference/system-tables/session_log) como um evento `LoginFailure` com `user` vazio.
Isso evita colocar credenciais em parâmetros de consulta da URL ou em cabeçalhos `Authorization` incluídos na solicitação de upgrade, onde elas poderiam acabar no histórico do navegador, nos logs de acesso do servidor e nos logs do proxy reverso. Os parâmetros de URL, o HTTP Basic e os cabeçalhos `X-ClickHouse-User`/`X-ClickHouse-Key` na solicitação de upgrade intencionalmente **não** são considerados pelo `/webterminal`.
Credenciais inválidas fazem o servidor fechar o WebSocket com o código `1008`; a interface do navegador solicita as credenciais novamente.
## Como funciona a sessão
Após a autenticação, o servidor executa o `clickhouse-client` conectado a um pseudoterminal e encaminha sua entrada e saída via WebSocket. A sessão oferece a experiência completa do `clickhouse-client`, incluindo:
* Realce de sintaxe.
* Autocompletar.
* Consultas de várias linhas.
* Histórico de comandos (armazenado no servidor durante a sessão).
O terminal usa [xterm.js](https://xtermjs.org/) para renderização. Todos os recursos são fornecidos pelo próprio binário do ClickHouse — nenhum CDN de terceiros é carregado.
## Integração com `/play`
A interface Web SQL [`/play`](/pt-BR/concepts/features/interfaces/http) incorpora o terminal web como um painel acoplável. Ative-o pelo ícone de terminal na barra lateral ou pressione a tecla `~` quando o editor de consulta estiver vazio. A página `/play` detecta a disponibilidade de `/webterminal` ao carregar e oculta os controles do terminal quando o endpoint não está disponível (por exemplo, quando `enable_webterminal` está definido como `false`).
## Integração com o site de documentação
Este site de documentação incorpora o mesmo terminal em uma barra estreita para desenvolvedores na parte inferior da página, conectado ao [ClickHouse playground](https://play.clickhouse.com) como o usuário `play`, somente leitura, para que seja possível testar os exemplos de qualquer página sem sair dela. A barra fixa reserva um espaço correspondente no fim da página para não ocultar os controles do rodapé. Enquanto o terminal está aberto, a página de documentação fica bloqueada e sua barra de rolagem é ocultada. A rolagem sobre o terminal fica restrita ao seu histórico e não move a página de documentação por trás dele. Clique na barra "ClickHouse terminal" ou pressione a tecla `~` para abrir o painel com preenchimento acima da barra. Clique novamente na barra, use o chevron, pressione `~` ou `Escape`, ou arraste a borda superior do painel para baixo para recolhê-lo; essa borda também permite redimensioná-lo. Encerrar a sessão — `exit` ou `Ctrl+D` — também recolhe o painel.
Ao fechar o painel, a sessão e seu histórico são mantidos: ao reabrir o terminal, você retorna ao mesmo prompt. A sessão permanece na página e, portanto, é preservada ao navegar entre páginas da documentação, mas não ao recarregar a aba do navegador — após recarregá-la, o painel retorna com uma nova sessão.
A barra do terminal faz parte do layout para desktop do site e não está disponível em viewports estreitos.
## Considerações de segurança
O terminal web expõe uma sessão interativa semelhante a um shell para qualquer pessoa que consiga se autenticar no endpoint HTTP do ClickHouse, portanto as mesmas ressalvas aplicáveis ao protocolo HTTP também se aplicam aqui:
* Sempre disponibilize `/webterminal` por HTTPS em ambientes não confiáveis para proteger as credenciais e o tráfego da sessão.
* Restrinja o acesso no nível da rede (firewall, proxy reverso ou a configuração `listen_host`) da mesma forma que você restringe o acesso ao protocolo HTTP.
* O endpoint valida o cabeçalho `Origin` em relação ao `Host` para mitigar o sequestro de WebSocket entre origens; configure os proxies reversos adequadamente se você encerrar o TLS externamente.
* Por trás de um proxy reverso que encerra TLS, a conexão upstream com o ClickHouse usa `http` simples, embora o navegador use `https`; por isso, a verificação estrita de mesma origem rejeitaria conexões legítimas. Para essas implantações, defina `webterminal_allowed_origins` como uma lista, separada por vírgulas, de origens completas autorizadas a abrir sessões WebSocket; quando essa configuração não está vazia, ela substitui a verificação padrão de mesma origem. Exemplo: `https://example.com,https://app.example.com:8443`.
O handler também impõe conformidade com o protocolo WebSocket de acordo com a RFC 6455: frames de cliente sem máscara, opcodes reservados, frames de controle grandes demais ou fragmentados e bits RSV reservados são rejeitados com códigos de fechamento por erro de protocolo.
## Disponibilidade da plataforma
O handler é compilado em todas as plataformas suportadas pelo ClickHouse. A camada de pseudoterminal usada pelo executor integrado do `clickhouse-client` é implementada com base em primitivas POSIX portáveis (`posix_openpt`/`grantpt`/`unlockpt`), com uma implementação específica para Linux que usa o `ptsname_r`, que é seguro para threads. Os links para `/webterminal` na página inicial do ClickHouse e em `/play` ficam ocultos automaticamente quando o endpoint não está disponível (por exemplo, quando `enable_webterminal` está definido como `false`).