Interface de controle

• Converse por chat 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 limites de texto por mensagem, para que sessões grandes não obriguem o navegador a renderizar um payload de transcrição completo antes que o chat fique utilizável.
• Converse por sessões em tempo real no navegador. A OpenAI usa WebRTC direto, o Google Live usa um token de navegador limitado a um único uso por WebSocket, e plugins de voz em tempo real somente de backend usam o transporte de relay do Gateway. Sessões de provedor pertencentes ao cliente começam com talk.client.create; sessões de relay do Gateway começam com talk.session.create. O relay mantém as credenciais do provedor no Gateway enquanto o navegador transmite PCM do microfone por talk.session.appendAudio e encaminha chamadas de ferramenta do provedor openclaw_agent_consult por talk.client.toolCall para a política do Gateway e o modelo OpenClaw maior configurado.
• Transmita chamadas de ferramentas + cards de saída de ferramenta ao vivo no Chat (eventos do agente).

• Canais: status de canais integrados e de plugin bundled/externos, login por QR e configuração por canal (channels.status, web.login.*, config.patch).
• Atualizações de sondagem de canais mantêm o snapshot anterior visível enquanto verificações lentas do 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: lista + substituições por sessão de modelo/pensamento/rápido/verboso/trace/raciocínio (sessions.list, sessions.patch).
• Sonhos: status de Dreaming, alternância para ativar/desativar e leitor do Diário de Sonhos (doctor.memory.status, doctor.memory.dreamDiary, config.patch).

• Jobs do Cron: listar/adicionar/editar/executar/ativar/desativar + histórico de execução (cron.*).
• Skills: status, ativar/desativar, instalar, atualizações de chave de API (skills.*).
• Nós: lista + limites (node.list).
• Aprovações de exec: editar allowlists do gateway ou do nó + política de solicitação para exec host=gateway/node (exec.approvals.*).

• Veja/edite ~/.openclaw/openclaw.json (config.get, config.set).
• Aplique + reinicie com validação (config.apply) e desperte a última sessão ativa.
• Gravações incluem uma proteção de hash-base para evitar sobrescrever edições concorrentes.
• Gravações (config.set/config.apply/config.patch) fazem uma pré-verificação da resolução de SecretRef ativo para refs no payload de configuração enviado; refs enviados ativos não resolvidos são rejeitados antes da gravação.
• Renderização de esquema + formulário (config.schema / config.schema.lookup, incluindo title / description de campo, dicas de UI correspondentes, resumos imediatos de filhos, metadados de documentação em nós aninhados de objeto/curinga/array/composição, além de esquemas de plugin + canal quando disponíveis); o editor JSON bruto fica disponível apenas 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 desativa o modo Bruto para esse snapshot.
• O editor JSON bruto "Redefinir para salvo" preserva a forma criada no bruto (formatação, comentários, layout de $include) em vez de renderizar novamente um snapshot achatado, para que edições externas sobrevivam a uma redefinição quando o snapshot puder fazer ida e volta com segurança.
• Valores estruturados de objeto SecretRef são renderizados como somente leitura em entradas de texto do formulário para impedir 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 tempos de atualização/RPC da Control UI, tempos lentos 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 PerformanceObserver.
• Logs: cauda ao vivo dos logs de arquivo do gateway com filtro/exportação (logs.tail).
• Atualização: execute uma atualização de pacote/git + reinício (update.run) com um relatório de reinício e depois consulte update.status após reconectar para verificar a versão do gateway em execução.

• Para jobs isolados, a entrega usa por padrão anunciar resumo. Você pode mudar para nenhuma se quiser execuções apenas internas.
• Campos de canal/destino aparecem quando anunciar 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 nenhuma estão disponíveis.
• Controles avançados de edição incluem excluir após execução, limpar substituição de agente, opções exatas/escalonadas de cron, substituições de modelo/pensamento do agente e alternâncias de entrega em melhor esforço.
• A validação do formulário é inline com erros em nível de campo; valores inválidos desativam 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: jobs legados armazenados com notify: true ainda podem usar cron.webhook até serem migrados.

• chat.send é não bloqueante: confirma imediatamente com { runId, status: "started" } e a resposta é transmitida por eventos chat.
• Uploads de chat aceitam imagens e arquivos que não sejam vídeo. Imagens mantêm o caminho de imagem nativo; 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.
• As respostas de chat.history têm limite de tamanho 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]).
• 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, então recarregamentos não dependem de payloads brutos de imagem em base64 permanecerem na resposta do histórico de chat.
• Ao renderizar chat.history, a Control UI remove tags de diretivas inline apenas de exibição do texto visível do assistente (por exemplo [[reply_to_*]] e [[audio_as_voice]]), payloads XML de chamadas 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 chamadas de ferramenta), e tokens de controle do modelo vazados em ASCII/largura completa, 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 ferramenta, a Control UI recarrega o histórico e mescla apenas uma pequena cauda otimista; o limite da transcrição está documentado em WebChat.
• chat.inject anexa uma nota do assistente à transcrição da sessão e transmite um evento chat para atualizações apenas de UI (sem execução de agente, sem entrega por canal).
• O cabeçalho do chat mostra o filtro de agente antes do seletor de sessão, e o seletor de sessão é escopado pelo agente selecionado. 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 painel salvas.
• Em larguras de desktop, os controles de chat permanecem em uma única linha compacta e se recolhem ao rolar para baixo na transcrição; rolar para cima, voltar ao topo ou chegar ao fim restaura os controles.
• Mensagens consecutivas duplicadas somente de texto são renderizadas como um único balão com um selo de contagem. Mensagens que contêm imagens, anexos, saída de ferramenta ou prévias de canvas não são recolhidas.
• Os seletores de modelo e raciocínio do cabeçalho do chat aplicam patch imediatamente à sessão ativa por meio de sessions.patch; são substituições persistentes da sessão, não opções de envio para apenas um turno.
• Digitar /new na Control UI cria e alterna para a mesma sessão nova de painel que New Chat. Digitar /reset mantém a redefinição explícita in-place do Gateway para a sessão atual.
• O seletor de modelo de chat solicita a visualização de modelos configurada do Gateway. Se agents.defaults.models estiver presente, essa lista permitida controla o seletor. Caso contrário, o seletor mostra entradas explícitas de models.providers.*.models mais provedores com autenticação utilizável. O catálogo completo permanece disponível pelo RPC de depuração models.list com view: "all".
• Quando relatórios recentes de uso da sessão do Gateway mostram alta pressão de contexto, a área do compositor de chat mostra um aviso de contexto e, em níveis recomendados de Compaction, um botão compacto que executa o caminho normal de Compaction da sessão. Snapshots obsoletos de tokens ficam ocultos até o Gateway relatar uso recente novamente.

O modo de fala usa um provedor de voz em tempo real registrado. Configure a OpenAI com talk.realtime.provider: "openai" mais talk.realtime.providers.openai.apiKey, ou configure o Google com talk.realtime.provider: "google" mais talk.realtime.providers.google.apiKey. O navegador nunca recebe uma chave de API padrão do provedor. 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 de uso único para uma sessão WebSocket do navegador, com instruções e declarações de ferramenta travadas no token pelo Gateway. Provedores que expõem apenas uma ponte de tempo real de backend executam pelo transporte de relay do Gateway, então credenciais e sockets de fornecedores ficam 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ções fornecidas pelo chamador.

No compositor de chat, o controle Talk é o botão de ondas ao lado do botão de ditado por microfone. Quando Talk inicia, a linha de status do compositor 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 para mantenedores: OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts verifica a troca SDP de WebRTC do navegador da OpenAI, a configuração de WebSocket do navegador com token restrito do Google Live e o adaptador de navegador do relay do Gateway com mídia falsa de microfone. O comando imprime apenas o status do provedor e não registra segredos.

• Clique em Stop (chama chat.abort).
• Enquanto uma execução está ativa, acompanhamentos normais entram na fila. Clique em Steer em uma mensagem na fila para injetar esse acompanhamento no turno em execução.
• Digite /stop (ou frases autônomas de aborto como stop, stop action, stop run, stop openclaw, please stop) para abortar fora de banda.
• chat.abort oferece suporte a { 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 existe saída em buffer.
• Entradas persistidas incluem metadados de aborto para que consumidores da transcrição consigam distinguir parciais abortadas de saída de conclusão normal.

{
  gateway: {
    controlUi: { allowInsecureAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}

allowInsecureAuth é apenas um alternador de compatibilidade local:

• Ele permite que sessões da UI de controle em localhost prossigam sem identidade do dispositivo em contextos HTTP não seguros.
• Ele não contorna verificações de pareamento.
• Ele não afrouxa os requisitos de identidade do dispositivo remoto (não localhost).

{
  gateway: {
    controlUi: { dangerouslyDisableDeviceAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}

• A autenticação bem-sucedida por proxy confiável pode admitir sessões da UI de controle de operador sem identidade do dispositivo.
• Isso não se estende a sessões da UI de controle com função de nó.
• Proxies reversos de loopback no mesmo host ainda não satisfazem a autenticação por proxy confiável; consulte Autenticação por proxy confiável.

• gatewayUrl é armazenado em localStorage após o carregamento e removido da URL.
• Se você passar um endpoint ws:// ou wss:// completo via gatewayUrl, codifique o valor de gatewayUrl para URL para que o navegador analise a string de consulta 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 por 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. Credenciais explícitas ausentes são 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 da UI de controle que não sejam loopback devem definir gateway.controlUi.allowedOrigins explicitamente (origens completas). Isso inclui configurações de desenvolvimento remoto.
• 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 tempo de execução, mas origens de navegador remotas ainda precisam de entradas explícitas.
• Não use gateway.controlUi.allowedOrigins: ["*"] exceto para testes locais rigidamente controlados. Isso significa permitir qualquer origem de navegador, não "corresponder a qualquer host que eu esteja usando".
• gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true habilita o modo de fallback de origem por cabeçalho Host, mas é um modo de segurança perigoso.