Pular para o conteúdo principal
A Control UI é um pequeno app de página única Vite + Lit servido pelo Gateway:
  • padrão: http://<host>:18789/
  • prefixo opcional: defina gateway.controlUi.basePath (por exemplo, /openclaw)
Ela se comunica diretamente com o WebSocket do Gateway na mesma porta.

​
Abertura rápida (local)

Se o Gateway estiver em execução no mesmo computador, abra: Se a página não carregar, inicie o Gateway primeiro: openclaw gateway.
Em vinculações de LAN nativas do Windows, o Firewall do Windows ou uma Política de Grupo gerenciada pela organização ainda pode bloquear a URL de LAN anunciada mesmo quando 127.0.0.1 funciona no host do Gateway. Execute openclaw gateway status --deep no host Windows; ele relata portas provavelmente bloqueadas, incompatibilidades de perfil e regras de firewall locais que a política pode ignorar.
A autenticação é fornecida durante o handshake do WebSocket por meio de:
  • connect.params.auth.token
  • connect.params.auth.password
  • cabeçalhos de identidade do Tailscale Serve quando gateway.auth.allowTailscale: true
  • cabeçalhos de identidade de proxy confiável quando gateway.auth.mode: "trusted-proxy"
O painel de configurações do dashboard mantém um token para a sessão da aba atual do navegador e a URL do gateway selecionado; senhas não são persistidas. O onboarding geralmente gera um token do gateway para autenticação por segredo compartilhado na primeira conexão, mas a autenticação por senha também funciona quando gateway.auth.mode é "password".

​
Pareamento de dispositivo (primeira conexão)

Quando você se conecta à Control UI por um novo navegador ou dispositivo, o Gateway geralmente exige uma aprovação de pareamento de uso único. Esta é uma medida de segurança para impedir acesso não autorizado. O que você verá: “disconnected (1008): pairing required”
1

Listar solicitações pendentes

openclaw devices list
2

Aprovar por ID da solicitação

openclaw devices approve <requestId>
Se o navegador tentar parear novamente com detalhes de autenticação alterados (função/escopos/chave pública), a solicitação pendente anterior será substituída e um novo requestId será criado. Execute openclaw devices list novamente antes da aprovação. Se o navegador já estiver pareado e você o alterar de acesso de leitura para acesso de escrita/admin, isso será tratado como um upgrade de aprovação, não como uma reconexão silenciosa. O OpenClaw mantém a aprovação antiga ativa, bloqueia a reconexão mais ampla e pede que você aprove explicitamente o novo conjunto de escopos. Depois de aprovado, o dispositivo é lembrado e não exigirá nova aprovação, a menos que você o revogue com openclaw devices revoke --device <id> --role <role>. Consulte CLI de dispositivos para rotação e revogação de tokens. Agentes Paperclip que se conectam por meio do adaptador openclaw_gateway usam o mesmo fluxo de aprovação da primeira execução. Após a tentativa inicial de conexão, execute openclaw devices approve --latest para pré-visualizar a solicitação pendente e depois execute novamente o comando openclaw devices approve <requestId> impresso para aprová-la. Passe valores explícitos de --url e --token para um gateway remoto. Para manter as aprovações estáveis entre reinicializações, configure um adapterConfig.devicePrivateKeyPem persistente no Paperclip em vez de permitir que ele gere uma nova identidade efêmera de dispositivo a cada execução.
  • Conexões diretas do navegador por local loopback (127.0.0.1 / localhost) são aprovadas automaticamente.
  • O Tailscale Serve pode ignorar a ida e volta do pareamento para sessões de operador da Control UI quando gateway.auth.allowTailscale: true, a identidade do Tailscale é verificada e o navegador apresenta sua identidade de dispositivo.
  • Vinculações diretas de Tailnet, conexões de navegador pela LAN e perfis de navegador sem identidade de dispositivo ainda exigem aprovação explícita.
  • Cada perfil de navegador gera um ID de dispositivo exclusivo, portanto trocar de navegador ou limpar os dados do navegador exigirá novo pareamento.

​
Parear um dispositivo móvel

Um administrador já pareado pode criar o QR de conexão para iOS/Android sem abrir um terminal:
1

Abrir pareamento móvel

Selecione Nós e clique em Parear dispositivo móvel no cartão Dispositivos.
2

Conectar o telefone

No app móvel do OpenClaw, abra Configurações → Gateway e escaneie o QR code. Em vez disso, você pode copiar e colar o código de configuração.
3

Confirmar a conexão

O app oficial para iOS/Android se conecta automaticamente. Se Dispositivos mostrar uma solicitação pendente, revise sua função e escopos antes de aprová-la.
Criar um código de configuração exige operator.admin; o botão fica desabilitado para sessões sem essa permissão. Um código de configuração contém uma credencial de bootstrap de curta duração, então trate o QR e o código copiado como uma senha enquanto forem válidos. Para pareamento remoto, o Gateway deve resolver para wss:// (por exemplo, por meio do Tailscale Serve/Funnel); ws:// sem criptografia é limitado a endereços de loopback e LAN privada. Consulte Pareamento para ver todos os detalhes de segurança e fallback.

​
Identidade pessoal (local do navegador)

A Control UI oferece suporte a uma identidade pessoal por navegador (nome de exibição e avatar) anexada a mensagens enviadas para atribuição em sessões compartilhadas. Ela vive no armazenamento do navegador, tem escopo limitado ao perfil atual do navegador e não é sincronizada com outros dispositivos nem persistida no servidor além dos metadados normais de autoria de transcrições nas mensagens que você realmente envia. Limpar os dados do site ou trocar de navegador a redefine para vazio. O mesmo padrão local do navegador se aplica à substituição do avatar do assistente. Avatares de assistente enviados sobrepõem a identidade resolvida pelo gateway apenas no navegador local e nunca fazem ida e volta por config.patch. O campo de configuração compartilhado ui.assistant.avatar ainda está disponível para clientes que não são UI e gravam o campo diretamente (como gateways com scripts ou dashboards personalizados).

​
Endpoint de configuração de runtime

A Control UI busca suas configurações de runtime em /control-ui-config.json, resolvido em relação ao caminho base da Control UI do gateway (por exemplo, /__openclaw__/control-ui-config.json quando a UI é servida sob /__openclaw__/). Esse endpoint é protegido pela mesma autenticação do gateway que o restante da superfície HTTP: navegadores não autenticados não conseguem buscá-lo, e uma busca bem-sucedida exige um token/senha de gateway já válido, identidade do Tailscale Serve ou uma identidade de proxy confiável.

​
Suporte a idiomas

A Control UI pode se localizar no primeiro carregamento com base no locale do seu navegador. Para substituí-lo depois, abra Visão geral -> Acesso ao Gateway -> Idioma. O seletor de locale fica no cartão Acesso ao Gateway, não em Aparência.
  • Locales compatíveis: en, zh-CN, zh-TW, pt-BR, de, es, ja-JP, ko, fr, ar, it, tr, uk, id, pl, th, vi, nl, fa
  • Traduções que não são em inglês são carregadas sob demanda no navegador.
  • O locale selecionado é salvo no armazenamento do navegador e reutilizado em visitas futuras.
  • Chaves de tradução ausentes recorrem ao inglês.
As traduções da documentação são geradas para o mesmo conjunto de locales que não são em inglês, mas o seletor de idiomas integrado do site de docs do Mintlify é limitado aos códigos de locale aceitos pelo Mintlify. A documentação em tailandês (th) e persa (fa) ainda é gerada no repositório de publicação; elas podem não aparecer nesse seletor até que o Mintlify ofereça suporte a esses códigos.

​
Temas de aparência

O painel Aparência mantém os temas integrados Claw, Knot e Dash, além de um slot de importação tweakcn local do navegador. Para importar um tema, abra o editor tweakcn, escolha ou crie um tema, clique em Compartilhar e cole o link do tema copiado em Aparência. O importador também aceita URLs de registro https://tweakcn.com/r/themes/<id>, URLs de editor como https://tweakcn.com/editor/theme?theme=amethyst-haze, caminhos relativos /themes/<id>, IDs brutos de tema e nomes de tema padrão como amethyst-haze. Aparência também inclui uma configuração de Tamanho do texto local do navegador. A configuração é armazenada com o restante das preferências da Control UI, aplica-se ao texto do chat, ao texto do compositor, aos cartões de ferramentas e às barras laterais de chat, e mantém entradas de texto com pelo menos 16px para que o Safari móvel não aplique zoom automático ao receber foco. Temas importados são armazenados apenas no perfil atual do navegador. Eles não são gravados na configuração do gateway e não são sincronizados entre dispositivos. Substituir o tema importado atualiza o único slot local; limpá-lo muda o tema ativo de volta para Claw se o tema importado estava selecionado.

​
O que ela pode fazer (hoje)

  • Converse com o modelo via Gateway WS (chat.history, chat.send, chat.abort, chat.inject).
  • Atualizações do histórico de chat solicitam uma janela recente limitada com tetos de texto por mensagem para que sessões grandes não obriguem o navegador a renderizar uma carga completa de transcrição antes de o chat ficar utilizável.
  • Converse por meio de sessões em tempo real do navegador. A OpenAI usa WebRTC direto, o Google Live usa um token restrito de uso único do navegador via WebSocket, e plugins de voz em tempo real somente de backend usam o transporte de retransmissão do Gateway. Sessões de provedor de propriedade do cliente começam com talk.client.create; sessões de retransmissão do Gateway começam com talk.session.create. A retransmissão mantém as credenciais do provedor no Gateway enquanto o navegador transmite PCM do microfone por meio de talk.session.appendAudio, encaminha chamadas de ferramentas do provedor openclaw_agent_consult por meio de talk.client.toolCall para a política do Gateway e o modelo OpenClaw configurado maior, e roteia o direcionamento por voz da execução ativa por meio de talk.client.steer ou talk.session.steer.
  • Transmita chamadas de ferramentas + cartões de saída de ferramentas ao vivo no Chat (eventos de agente).
  • Aba Atividade com resumos locais do navegador e com redação em primeiro lugar da atividade de ferramentas ao vivo a partir da entrega existente de session.tool / eventos de ferramentas.
  • Canais: status de canais integrados e de plugins empacotados/externos, login por QR e configuração por canal (channels.status, web.login.*, config.patch).
  • Atualizações de sondagem de canal mantêm o snapshot anterior visível enquanto verificações lentas de provedor terminam, e snapshots parciais são rotulados quando uma sondagem ou auditoria excede seu orçamento de UI.
  • Instâncias: lista de presença + atualização (system-presence).
  • Sessões: liste por padrão sessões de agentes configurados, fixe sessões frequentes, renomeie-as, arquive ou restaure sessões inativas, use fallback a partir de chaves obsoletas de sessões de agentes não configurados e aplique substituições por sessão de modelo/thinking/fast/verbose/trace/reasoning (sessions.list, sessions.patch). Sessões fixadas são ordenadas acima de sessões recentes não fixadas; sessões arquivadas ficam na visualização arquivada da página Sessões e mantêm suas transcrições.
  • Sonhos: status de dreaming, alternância de habilitar/desabilitar e leitor do Diário de Sonhos (doctor.memory.status, doctor.memory.dreamDiary, config.patch).
  • Tarefas Cron: listar/adicionar/editar/executar/habilitar/desabilitar + histórico de execução (cron.*).
  • Skills: status, habilitar/desabilitar, instalar, atualizações de chave de API (skills.*).
  • Nós: lista + capacidades (node.list), criar códigos de configuração móvel e aprovar pareamento de dispositivo (device.pair.*).
  • Aprovações de exec: edite allowlists de gateway ou nó + política de solicitação para exec host=gateway/node (exec.approvals.*).
  • Visualize/edite ~/.openclaw/openclaw.json (config.get, config.set).
  • O MCP tem uma página dedicada de configurações para servidores configurados, habilitação, resumos de OAuth/filtro/paralelos, comandos comuns do operador e o editor de configuração mcp com escopo.
  • Aplique + reinicie com validação (config.apply) e desperte a última sessão ativa.
  • As gravações incluem uma proteção por hash-base para evitar sobrescrever edições simultâneas.
  • As gravações (config.set/config.apply/config.patch) fazem uma pré-verificação da resolução de SecretRef ativa para refs no payload de configuração enviado; refs enviadas ativas não resolvidas são rejeitadas antes da gravação.
  • Salvamentos de formulário descartam placeholders redigidos obsoletos que não podem ser restaurados da configuração salva, preservando valores redigidos que ainda mapeiam para segredos salvos.
  • Renderização de esquema + formulário (config.schema / config.schema.lookup, incluindo title / description de campo, dicas de UI correspondentes, resumos de filhos imediatos, metadados de documentação em nós aninhados de objeto/coringa/array/composição, além de esquemas de plugin + canal quando disponíveis); o editor de JSON bruto fica disponível somente quando o snapshot tem uma ida e volta bruta segura.
  • Se um snapshot não puder fazer ida e volta segura de texto bruto, a Control UI força o modo Formulário e desabilita o modo Bruto para esse snapshot.
  • O editor de JSON bruto “Redefinir para salvo” preserva a forma escrita no bruto (formatação, comentários, layout de $include) em vez de renderizar novamente um snapshot achatado, de modo que edições externas sobrevivam a uma redefinição quando o snapshot puder fazer ida e volta com segurança.
  • Valores de objeto SecretRef estruturados são renderizados como somente leitura em entradas de texto de formulário para evitar corrupção acidental de objeto para string.
  • Depuração: snapshots de status/integridade/modelos + log de eventos + chamadas RPC manuais (status, health, models.list).
  • O log de eventos inclui temporizações de atualização/RPC da Control UI, temporizações lentas de renderização de chat/configuração e entradas de responsividade do navegador para quadros de animação longos ou tarefas longas quando o navegador expõe esses tipos de entrada de PerformanceObserver.
  • Logs: acompanhamento ao vivo de logs de arquivo do Gateway com filtro/exportação (logs.tail).
  • Atualização: execute uma atualização de pacote/git + reinicialização (update.run) com um relatório de reinicialização e, depois, consulte update.status após reconectar para verificar a versão do Gateway em execução.
  • Para jobs isolados, a entrega usa resumo de anúncio por padrão. Você pode alternar para none se quiser execuções apenas internas.
  • Campos de canal/destino aparecem quando anúncio está selecionado.
  • O modo Webhook usa delivery.mode = "webhook" com delivery.to definido como uma URL de Webhook HTTP(S) válida.
  • Para jobs de sessão principal, os modos de entrega Webhook e none estão disponíveis.
  • Controles de edição avançada incluem excluir após execução, limpar substituição de agente, opções exatas/escalonadas de Cron, substituições de modelo/raciocínio do agente e alternâncias de entrega de melhor esforço.
  • A validação do formulário é inline com erros em nível de campo; valores inválidos desabilitam o botão de salvar até serem corrigidos.
  • Defina cron.webhookToken para enviar um token bearer dedicado; se omitido, o Webhook é enviado sem cabeçalho de autenticação.
  • Fallback obsoleto: execute openclaw doctor --fix para migrar jobs legados armazenados com notify: true de cron.webhook para Webhook explícito por job ou entrega de conclusão.

​
Página MCP

A página dedicada de MCP é uma visão de operador para servidores MCP gerenciados pelo OpenClaw em mcp.servers. Ela não inicia transportes MCP por conta própria; use-a para inspecionar e editar a configuração salva e, depois, use openclaw mcp doctor --probe quando precisar de comprovação de servidor ao vivo. Fluxo de trabalho típico:
  1. Abra MCP na barra lateral.
  2. Verifique os cartões de resumo para contagens totais, habilitados, OAuth e de servidores filtrados.
  3. Revise cada linha de servidor quanto a transporte, habilitação, autenticação, filtros, timeouts e dicas de comando.
  4. Alterne a habilitação quando um servidor deve permanecer configurado, mas ficar fora da descoberta em tempo de execução.
  5. Edite a seção de configuração mcp com escopo para definições de servidor, cabeçalhos, caminhos TLS/mTLS, metadados OAuth, filtros de ferramentas e metadados de projeção do Codex.
  6. Use Salvar para uma gravação de configuração, ou Salvar e Publicar quando o Gateway em execução deve aplicar a configuração alterada.
  7. Execute openclaw mcp status --verbose, openclaw mcp doctor --probe ou openclaw mcp reload em um terminal quando o processo editado precisar de diagnósticos estáticos, comprovação ao vivo ou descarte de runtime em cache.
A página redige valores semelhantes a URL que contenham credenciais antes de renderizar e coloca nomes de servidor entre aspas em snippets de comando para que comandos copiados ainda funcionem com espaços ou metacaracteres de shell. A referência completa da CLI e de configuração fica em MCP.

​
Aba Atividade

A aba Atividade é um observador efêmero local do navegador para atividade de ferramentas ao vivo. Ela deriva do mesmo fluxo de eventos session.tool / ferramenta do Gateway que alimenta os cartões de ferramentas do Chat; ela não adiciona outra família de eventos do Gateway, endpoint, armazenamento durável de atividades, feed de métricas ou fluxo de observador externo. Entradas de atividade mantêm apenas resumos sanitizados e prévias de saída redigidas e truncadas. Valores de argumentos de ferramentas não são armazenados no estado de Atividade; a UI mostra que os argumentos estão ocultos e registra apenas a contagem de campos de argumento. A lista em memória segue a aba atual do navegador, sobrevive à navegação dentro da Control UI e é redefinida ao recarregar a página, trocar de sessão ou usar Limpar.

​
Terminal do operador

O terminal de operador acoplável é desabilitado por padrão. Para habilitá-lo, defina gateway.terminal.enabled: true e reinicie o Gateway. O terminal exige uma conexão operator.admin e abre um PTY do host no workspace do agente ativo. Novas abas seguem o agente de chat selecionado no momento.
O terminal é um shell de host sem confinamento e herda o ambiente do processo do Gateway. Habilite-o somente para implantações de operador confiáveis. O OpenClaw recusa sessões de terminal para agentes com sandbox.mode: "all"; alterar um agente ativo para esse modo fecha suas sessões de terminal existentes e em andamento.
Use Ctrl + crase para alternar o dock. O layout oferece suporte a acoplamento inferior e à direita, redimensiona com o viewport do navegador e mantém várias abas de shell. Consulte configuração do Gateway para gateway.terminal.enabled e a substituição opcional gateway.terminal.shell. As sessões sobrevivem a desconexões: uma recarga de página, suspensão do laptop ou instabilidade de rede desanexa a sessão no Gateway em vez de encerrá-la, e a mesma aba do navegador se reconecta ao reconectar com a saída recente reproduzida. Sessões desanexadas são encerradas após gateway.terminal.detachedSessionTimeoutSeconds (padrão de 300 segundos; 0 restaura encerramento ao desconectar). terminal.list mostra sessões anexáveis, terminal.attach adota uma delas (tomada de controle estilo tmux), e terminal.text lê a saída recente de uma sessão como texto simples sem anexar — uma conveniência para agente/ferramental.

​
Comportamento do chat

  • chat.send é não bloqueante: confirma imediatamente com { runId, status: "started" } e a resposta é transmitida por eventos chat. Clientes confiáveis da Control UI também podem receber metadados opcionais de tempo de ACK para diagnósticos locais.
  • Uploads no chat aceitam imagens e arquivos que não sejam vídeos. Imagens mantêm o caminho nativo da imagem; outros arquivos são armazenados como mídia gerenciada e exibidos no histórico como links de anexo.
  • Reenviar com o mesmo idempotencyKey retorna { status: "in_flight" } durante a execução e { status: "ok" } após a conclusão.
  • Respostas de chat.history têm tamanho limitado para segurança da UI. Quando entradas da transcrição são grandes demais, o Gateway pode truncar campos de texto longos, omitir blocos pesados de metadados e substituir mensagens grandes demais por um placeholder ([chat.history omitted: message too large]).
  • Quando uma mensagem visível do assistente foi truncada em chat.history, o leitor lateral pode buscar sob demanda a entrada completa da transcrição normalizada para exibição por meio de chat.message.get usando sessionKey, agentId ativo quando necessário, e messageId da transcrição. Se o Gateway ainda não conseguir retornar mais conteúdo, o leitor mostra um estado explicitamente indisponível em vez de repetir silenciosamente a prévia truncada.
  • Imagens do assistente/geradas são persistidas como referências de mídia gerenciada e servidas de volta por URLs de mídia autenticadas do Gateway, para que recarregamentos não dependam de payloads brutos de imagem em base64 permanecerem na resposta do histórico do chat.
  • Ao renderizar chat.history, a Control UI remove do texto visível do assistente tags de diretiva inline somente de exibição (por exemplo [[reply_to_*]] e [[audio_as_voice]]), payloads XML de chamada de ferramenta em texto simples (incluindo <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls> e blocos truncados de chamada de ferramenta), e tokens de controle de modelo vazados em ASCII/largura total, e omite entradas do assistente cujo texto visível inteiro seja apenas o token silencioso exato NO_REPLY / no_reply ou o token de confirmação de heartbeat HEARTBEAT_OK.
  • Durante um envio ativo e a atualização final do histórico, a visualização de chat mantém mensagens locais otimistas do usuário/assistente visíveis se chat.history retornar brevemente um snapshot mais antigo; a transcrição canônica substitui essas mensagens locais quando o histórico do Gateway alcança o estado atual.
  • Eventos chat ao vivo são estado de entrega, enquanto chat.history é reconstruído a partir da transcrição durável da sessão. Após eventos finais de ferramentas, a Control UI recarrega o histórico e mescla apenas uma pequena cauda otimista; o limite da transcrição é documentado em WebChat.
  • chat.inject acrescenta uma nota do assistente à transcrição da sessão e transmite um evento chat para atualizações somente de UI (sem execução de agente, sem entrega por canal).
  • A barra lateral lista sessões recentes com uma ação Nova Sessão, um link Todas as Sessões e um botão de busca de sessão que abre o seletor completo de sessões (escopado pelo agente selecionado, com busca e paginação). Uma nova sessão de dashboard recebe assincronamente um título conciso gerado a partir de sua primeira mensagem que não seja comando; nomes explícitos nunca são substituídos. Defina agents.defaults.utilityModel (ou agents.list[].utilityModel) para rotear essa chamada de modelo separada para um modelo de menor custo. Trocar de agente mostra apenas sessões vinculadas a esse agente e recai para a sessão principal desse agente quando ele ainda não tem sessões de dashboard salvas.
  • Cada linha do seletor de sessões pode renomear, fixar ou arquivar a sessão. Uma execução ativa e a sessão principal de um agente não podem ser arquivadas. Arquivar a sessão selecionada no momento troca o Chat de volta para a sessão principal desse agente.
  • Em larguras de desktop, os controles de chat permanecem em uma única linha compacta e recolhem ao rolar para baixo na transcrição; rolar para cima, voltar ao topo ou chegar ao final restaura os controles.
  • Mensagens consecutivas duplicadas contendo apenas texto são renderizadas como um único balão com um badge de contagem. Mensagens que carregam imagens, anexos, saída de ferramenta ou prévias de canvas não são recolhidas.
  • Os seletores de modelo e thinking do cabeçalho do chat aplicam patch à sessão ativa imediatamente por meio de sessions.patch; eles são substituições persistentes da sessão, não opções de envio válidas apenas por um turno.
  • Se você enviar uma mensagem enquanto uma alteração no seletor de modelo para a mesma sessão ainda estiver sendo salva, o composer aguarda esse patch de sessão antes de chamar chat.send, para que o envio use o modelo selecionado.
  • Digitar /new na Control UI cria e troca para a mesma nova sessão de dashboard que Novo Chat, exceto quando session.dmScope: "main" está configurado e o pai atual é a sessão principal do agente; nesse caso, ela redefine a sessão principal no lugar. Digitar /reset mantém a redefinição explícita no lugar do Gateway para a sessão atual.
  • O seletor de modelo do chat solicita a visualização de modelos configurada no Gateway. Se agents.defaults.models estiver presente, essa allowlist conduz o seletor, incluindo entradas provider/* que mantêm catálogos escopados por provedor dinâmicos. Caso contrário, o seletor mostra entradas explícitas de models.providers.*.models além de provedores com autenticação utilizável. O catálogo completo continua disponível pelo RPC de depuração models.list com view: "all".
  • Quando relatórios recentes de uso de sessão do Gateway incluem tokens de contexto atuais, a barra de ferramentas do composer de chat mostra um pequeno anel de uso de contexto com a porcentagem usada; o detalhe completo dos tokens fica em seu tooltip. O anel muda para estilo de aviso sob alta pressão de contexto e, em níveis recomendados de Compaction, mostra um botão compacto que executa o caminho normal de Compaction da sessão. Snapshots de token obsoletos ficam ocultos até que o Gateway reporte uso recente novamente.
O modo de conversa usa um provedor de voz em tempo real registrado. Configure OpenAI com talk.realtime.provider: "openai" mais um perfil de autenticação de chave de API openai, talk.realtime.providers.openai.apiKey ou OPENAI_API_KEY; perfis OAuth da OpenAI não configuram voz Realtime. Configure Google com talk.realtime.provider: "google" mais talk.realtime.providers.google.apiKey. O navegador nunca recebe uma chave de API de provedor padrão. A OpenAI recebe um segredo efêmero de cliente Realtime para WebRTC. O Google Live recebe um token de autenticação de Live API restrito e de uso único para uma sessão WebSocket no navegador, com instruções e declarações de ferramentas bloqueadas no token pelo Gateway. Provedores que expõem apenas uma ponte realtime de backend executam pelo transporte de relay do Gateway, de modo que credenciais e sockets de fornecedor permanecem no servidor enquanto o áudio do navegador passa por RPCs autenticados do Gateway. O prompt da sessão Realtime é montado pelo Gateway; talk.client.create não aceita substituições de instrução fornecidas pelo chamador.O composer do Chat inclui um botão de opções de conversa ao lado do botão iniciar/parar conversa. As opções se aplicam à próxima sessão de conversa e podem substituir provedor, transporte, modelo, voz, esforço de raciocínio, limiar de VAD, duração de silêncio e preenchimento de prefixo. Quando uma opção está em branco, o Gateway usa padrões configurados quando disponíveis ou o padrão do provedor. Selecionar relay do Gateway força o caminho de relay do backend; selecionar WebRTC mantém a sessão pertencente ao cliente e falha em vez de recorrer silenciosamente ao relay se o provedor não conseguir criar uma sessão de navegador.No composer do Chat, o controle de conversa é o botão de ondas ao lado do botão de ditado por microfone. Quando a conversa começa, a linha de status do composer mostra Connecting Talk..., depois Talk live enquanto o áudio está conectado, ou Asking OpenClaw... enquanto uma chamada de ferramenta em tempo real consulta o modelo maior configurado por meio de talk.client.toolCall.Smoke ao vivo de mantenedor: OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts verifica a ponte WebSocket de backend da OpenAI, a troca SDP de WebRTC no navegador da OpenAI, a configuração de WebSocket no navegador com token restrito do Google Live e o adaptador de navegador do relay do Gateway com mídia de microfone falsa. O comando imprime apenas o status do provedor e não registra segredos.
  • Clique em Parar (chama chat.abort).
  • Enquanto uma execução está ativa, acompanhamentos normais entram na fila. Clique em Direcionar em uma mensagem na fila para injetar esse acompanhamento no turno em execução.
  • Digite /stop (ou frases autônomas de abortar como stop, stop action, stop run, stop openclaw, please stop) para abortar fora de banda.
  • chat.abort aceita { sessionKey } (sem runId) para abortar todas as execuções ativas dessa sessão.
  • Quando uma execução é abortada, texto parcial do assistente ainda pode ser mostrado na UI.
  • O Gateway persiste texto parcial abortado do assistente no histórico da transcrição quando há saída em buffer.
  • Entradas persistidas incluem metadados de abortar para que consumidores da transcrição consigam distinguir parciais abortadas da saída de conclusão normal.

​
Instalação de PWA e Web Push

A Control UI distribui um manifest.webmanifest e um service worker, então navegadores modernos podem instalá-la como uma PWA independente. Web Push permite que o Gateway desperte a PWA instalada com notificações mesmo quando a aba ou janela do navegador não está aberta. Se a página mostrar Incompatibilidade de protocolo logo após uma atualização do OpenClaw, primeiro reabra o dashboard com openclaw dashboard e faça uma atualização forçada da página. Se ainda falhar, limpe os dados do site para a origem do dashboard ou teste em uma janela privada do navegador; uma aba antiga ou cache de service worker do navegador pode continuar executando um pacote da Control UI anterior à atualização contra o Gateway mais novo.
SuperfícieO que faz
ui/public/manifest.webmanifestManifesto PWA. Navegadores oferecem “Instalar app” assim que ele fica acessível.
ui/public/sw.jsService worker que lida com eventos push e cliques em notificações.
push/vapid-keys.json (sob o diretório de estado do OpenClaw)Par de chaves VAPID gerado automaticamente usado para assinar payloads de Web Push.
push/web-push-subscriptions.jsonEndpoints de assinatura de navegador persistidos.
Substitua o par de chaves VAPID por variáveis de ambiente no processo do Gateway quando quiser fixar chaves (para implantações multi-host, rotação de segredos ou testes):
  • OPENCLAW_VAPID_PUBLIC_KEY
  • OPENCLAW_VAPID_PRIVATE_KEY
  • OPENCLAW_VAPID_SUBJECT (o padrão é https://openclaw.ai)
A Control UI usa estes métodos do Gateway restritos por escopo para registrar e testar assinaturas de navegador:
  • push.web.vapidPublicKey — busca a chave pública VAPID ativa.
  • push.web.subscribe — registra um endpoint mais keys.p256dh/keys.auth.
  • push.web.unsubscribe — remove um endpoint registrado.
  • push.web.test — envia uma notificação de teste para a assinatura do chamador.
Web Push é independente do caminho de relay APNS do iOS (consulte Configuração para push apoiado por relay) e do método push.test existente, que mira o pareamento móvel nativo.

​
Embeds hospedados

Mensagens do assistente podem renderizar conteúdo web hospedado inline com o shortcode [embed ...]. A política de sandbox do iframe é controlada por gateway.controlUi.embedSandbox:
Desativa a execução de scripts dentro de embeds hospedados.
Exemplo: 
{
  gateway: {
    controlUi: {
      embedSandbox: "scripts",
    },
  },
}
Use trusted somente quando o documento incorporado realmente precisar de comportamento de mesma origem. Para a maioria dos jogos e canvases interativos gerados por agentes, scripts é a escolha mais segura.
URLs de incorporação externas absolutas http(s) continuam bloqueadas por padrão. Se você quiser intencionalmente que [embed url="https://..."] carregue páginas de terceiros, defina gateway.controlUi.allowExternalEmbedUrls: true.

​
Largura das mensagens de chat

Mensagens de chat agrupadas usam uma largura máxima padrão legível. Implantações em monitores largos podem substituí-la sem modificar o CSS empacotado definindo gateway.controlUi.chatMessageMaxWidth: 
{
  gateway: {
    controlUi: {
      chatMessageMaxWidth: "min(1280px, 82%)",
    },
  },
}
O valor é validado antes de chegar ao navegador. Os valores compatíveis incluem comprimentos simples e porcentagens, como 960px ou 82%, além de expressões de largura restritas min(...), max(...), clamp(...), calc(...) e fit-content(...).

​
Acesso ao tailnet (recomendado)

Mantenha o Gateway em loopback e deixe o Tailscale Serve fazer proxy com HTTPS:
openclaw gateway --tailscale serve
Abra:
  • https://<magicdns>/ (ou seu gateway.controlUi.basePath configurado)
Por padrão, as solicitações do Control UI/WebSocket Serve podem autenticar por cabeçalhos de identidade do Tailscale (tailscale-user-login) quando gateway.auth.allowTailscale é true. O OpenClaw verifica a identidade resolvendo o endereço x-forwarded-for com tailscale whois e comparando-o com o cabeçalho, e só aceita esses cabeçalhos quando a solicitação chega ao loopback com os cabeçalhos x-forwarded-* do Tailscale. Para sessões de operador da Control UI com identidade de dispositivo do navegador, esse caminho Serve verificado também ignora a ida e volta de pareamento do dispositivo; navegadores sem dispositivo e conexões com função de nó ainda seguem as verificações normais de dispositivo. Defina gateway.auth.allowTailscale: false se quiser exigir credenciais explícitas de segredo compartilhado mesmo para tráfego Serve. Então use gateway.auth.mode: "token" ou "password".Para esse caminho assíncrono de identidade Serve, tentativas de autenticação com falha para o mesmo IP de cliente e escopo de autenticação são serializadas antes das gravações de limite de taxa. Portanto, novas tentativas inválidas concorrentes do mesmo navegador podem mostrar retry later na segunda solicitação, em vez de duas incompatibilidades simples competindo em paralelo.
A autenticação Serve sem token pressupõe que o host do gateway é confiável. Se código local não confiável puder ser executado nesse host, exija autenticação por token/senha.

​
HTTP inseguro

Se você abrir o painel por HTTP simples (http://<lan-ip> ou http://<tailscale-ip>), o navegador é executado em um contexto não seguro e bloqueia o WebCrypto. Por padrão, o OpenClaw bloqueia conexões da Control UI sem identidade de dispositivo. Exceções documentadas:
  • compatibilidade de HTTP inseguro somente em localhost com gateway.controlUi.allowInsecureAuth=true
  • autenticação bem-sucedida de operador da Control UI por meio de gateway.auth.mode: "trusted-proxy"
  • recurso de emergência gateway.controlUi.dangerouslyDisableDeviceAuth=true
Correção recomendada: use HTTPS (Tailscale Serve) ou abra a UI localmente:
  • https://<magicdns>/ (Serve)
  • http://127.0.0.1:18789/ (no host do gateway)
{
  gateway: {
    controlUi: { allowInsecureAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}
allowInsecureAuth é apenas uma alternância de compatibilidade local:
  • Ela permite que sessões da Control UI em localhost prossigam sem identidade de dispositivo em contextos HTTP não seguros.
  • Ela não ignora verificações de pareamento.
  • Ela não relaxa os requisitos de identidade de dispositivo remoto (não localhost).
{
  gateway: {
    controlUi: { dangerouslyDisableDeviceAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}
dangerouslyDisableDeviceAuth desativa as verificações de identidade de dispositivo da Control UI e é uma redução grave de segurança. Reverta rapidamente após o uso emergencial.
  • A autenticação trusted-proxy bem-sucedida pode admitir sessões de operador da Control UI sem identidade de dispositivo.
  • Isso não se estende a sessões da Control UI com função de nó.
  • Proxies reversos local loopback no mesmo host ainda não satisfazem a autenticação trusted-proxy; consulte Autenticação de proxy confiável.
Consulte Tailscale para orientações de configuração de HTTPS.

​
Política de segurança de conteúdo

A Control UI é fornecida com uma política img-src restrita: somente ativos de mesma origem, URLs data: e URLs blob: geradas localmente são permitidos. URLs de imagem remotas http(s) e relativas a protocolo são rejeitadas pelo navegador e não geram buscas de rede. O que isso significa na prática:
  • Avatares e imagens servidos em caminhos relativos (por exemplo, /avatars/<id>) ainda são renderizados, incluindo rotas de avatar autenticadas que a UI busca e converte em URLs blob: locais.
  • URLs inline data:image/... ainda são renderizadas (útil para payloads dentro do protocolo).
  • URLs blob: locais criadas pela Control UI ainda são renderizadas.
  • URLs de avatar remotas emitidas por metadados de canais são removidas nos auxiliares de avatar da Control UI e substituídas pelo logotipo/selo integrado, portanto um canal comprometido ou malicioso não pode forçar buscas arbitrárias de imagens remotas a partir do navegador de um operador.
Você não precisa alterar nada para obter esse comportamento — ele está sempre ativo e não é configurável.

​
Autenticação da rota de avatar

Quando a autenticação do gateway está configurada, o endpoint de avatar da Control UI exige o mesmo token do gateway que o restante da API:
  • GET /avatar/<agentId> retorna a imagem do avatar somente a chamadores autenticados. GET /avatar/<agentId>?meta=1 retorna os metadados do avatar sob a mesma regra.
  • Solicitações não autenticadas para qualquer uma das rotas são rejeitadas (correspondendo à rota irmã assistant-media). Isso impede que a rota de avatar vaze a identidade do agente em hosts que, de outra forma, estão protegidos.
  • A própria Control UI encaminha o token do gateway como cabeçalho bearer ao buscar avatares e usa URLs blob autenticadas para que a imagem ainda seja renderizada nos painéis.
Se você desativar a autenticação do gateway (não recomendado em hosts compartilhados), a rota de avatar também se torna não autenticada, alinhada ao restante do gateway.

​
Autenticação da rota de mídia do assistente

Quando a autenticação do gateway está configurada, pré-visualizações de mídia local do assistente usam uma rota em duas etapas:
  • GET /__openclaw__/assistant-media?meta=1&source=<path> exige a autenticação normal de operador da Control UI. O navegador envia o token do gateway como cabeçalho bearer ao verificar disponibilidade.
  • Respostas de metadados bem-sucedidas incluem um mediaTicket de curta duração com escopo limitado ao caminho de origem exato.
  • URLs de imagem, áudio, vídeo e documento renderizadas pelo navegador usam mediaTicket=<ticket> em vez do token ou senha ativo do gateway. O ticket expira rapidamente e não pode autorizar uma origem diferente.
Isso mantém a renderização normal de mídia compatível com elementos de mídia nativos do navegador sem colocar credenciais reutilizáveis do gateway em URLs de mídia visíveis.

​
Compilando a UI

O Gateway serve arquivos estáticos de dist/control-ui. Compile-os com: 
pnpm ui:build
Base absoluta opcional (quando você quer URLs de ativos fixas): 
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
Para desenvolvimento local (servidor de desenvolvimento separado): 
pnpm ui:dev
Então aponte a UI para a URL WS do seu Gateway (por exemplo, ws://127.0.0.1:18789).

​
Página em branco da Control UI

Se o navegador carregar um painel em branco e o DevTools não mostrar nenhum erro útil, uma extensão ou script de conteúdo inicial pode ter impedido que o aplicativo de módulo JavaScript fosse avaliado. A página estática inclui um painel de recuperação em HTML simples que aparece quando <openclaw-app> não é registrado após a inicialização. Use a ação Tentar novamente do painel após alterar o ambiente do navegador, ou recarregue manualmente após estas verificações:
  • Desative extensões que injetam em todas as páginas, especialmente extensões com scripts de conteúdo <all_urls>.
  • Tente uma janela privada, um perfil de navegador limpo ou outro navegador.
  • Mantenha o Gateway em execução e verifique a mesma URL do painel após a alteração no navegador.

​
Depuração/testes: servidor de desenvolvimento + Gateway remoto

A Control UI é composta por arquivos estáticos; o destino WebSocket é configurável e pode ser diferente da origem HTTP. Isso é útil quando você quer o servidor de desenvolvimento Vite localmente, mas o Gateway é executado em outro lugar.
1

Start the UI dev server

pnpm ui:dev
2

Open with gatewayUrl

http://localhost:5173/?gatewayUrl=ws%3A%2F%2F<gateway-host>%3A18789
Autenticação opcional de uso único (se necessário):
http://localhost:5173/?gatewayUrl=wss%3A%2F%2F<gateway-host>%3A18789#token=<gateway-token>
  • gatewayUrl é armazenado em localStorage após o carregamento e removido da URL.
  • Se você passar um endpoint completo ws:// ou wss:// via gatewayUrl, codifique o valor de gatewayUrl em URL para que o navegador analise a query string corretamente.
  • token deve ser passado pelo fragmento da URL (#token=...) sempre que possível. Fragmentos não são enviados ao servidor, o que evita vazamento em logs de solicitação e Referer. Parâmetros de consulta legados ?token= ainda são importados uma vez para compatibilidade, mas apenas como fallback, e são removidos imediatamente após o bootstrap.
  • password é mantido apenas na memória.
  • Quando gatewayUrl está definido, a UI não faz fallback para credenciais de configuração ou ambiente. Forneça token (ou password) explicitamente. A ausência de credenciais explícitas é um erro.
  • Use wss:// quando o Gateway estiver atrás de TLS (Tailscale Serve, proxy HTTPS etc.).
  • gatewayUrl só é aceito em uma janela de nível superior (não incorporada) para impedir clickjacking.
  • Implantações públicas não loopback da Control UI devem definir gateway.controlUi.allowedOrigins explicitamente (origens completas). Carregamentos privados de mesma origem em LAN/Tailnet a partir de loopback, RFC1918/link-local, .local, .ts.net ou hosts CGNAT do Tailscale são aceitos sem ativar fallback por cabeçalho Host.
  • A inicialização do Gateway pode semear origens locais como http://localhost:<port> e http://127.0.0.1:<port> a partir do bind e da porta efetivos em runtime, mas origens de navegadores remotos ainda precisam de entradas explícitas.
  • Não use gateway.controlUi.allowedOrigins: ["*"], exceto para testes locais rigorosamente controlados. Isso significa permitir qualquer origem de navegador, não “corresponder a qualquer host que eu esteja usando.”
  • gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true ativa o modo de fallback por origem do cabeçalho Host, mas é um modo de segurança perigoso.
Exemplo: 
{
  gateway: {
    controlUi: {
      allowedOrigins: ["http://localhost:5173"],
    },
  },
}
Detalhes de configuração de acesso remoto: Acesso remoto.

​
Relacionados