​

Interface de controle (navegador)

• padrão: http://<host>:18789/
• prefixo opcional: defina gateway.controlUi.basePath (por exemplo, /openclaw)

​

Abertura rápida (local)

• http://127.0.0.1:18789/ (ou http://localhost:18789/)

• 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"

​

Pareamento de dispositivo (primeira conexão)

# Listar solicitações pendentes
openclaw devices list

# Aprovar por ID da solicitação
openclaw devices approve <requestId>

• Conexões diretas locais do navegador por local loopback (127.0.0.1 / localhost) são aprovadas automaticamente.
• Conexões de navegador por Tailnet e LAN ainda exigem aprovação explícita, mesmo quando se originam da mesma máquina.
• Cada perfil de navegador gera um ID de dispositivo único, então trocar de navegador ou limpar os dados do navegador exigirá novo pareamento.

​

Suporte a idiomas

• Localidades compatíveis: en, zh-CN, zh-TW, pt-BR, de, es
• Traduções que não estão em inglês são carregadas sob demanda no navegador.
• A localidade selecionada é salva no armazenamento do navegador e reutilizada em visitas futuras.
• Chaves de tradução ausentes recorrem ao inglês.

​

O que ela pode fazer (hoje)

• Conversar com o modelo via Gateway WS (chat.history, chat.send, chat.abort, chat.inject)
• Transmitir chamadas de ferramentas + cartões de saída de ferramentas ao vivo no Chat (eventos do agente)
• Canais: status de canais integrados e de plugins empacotados/externos, login por QR e configuração por canal (channels.status, web.login.*, config.patch)
• Instâncias: lista de presença + atualização (system-presence)
• Sessões: lista + substituições por sessão para modelo/thinking/fast/verbose/reasoning (sessions.list, sessions.patch)
• Jobs 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: listar + limites (node.list)
• Aprovações de exec: editar listas de permissões do gateway ou nó + política de solicitação para exec host=gateway/node (exec.approvals.*)
• Configuração: visualizar/editar ~/.openclaw/openclaw.json (config.get, config.set)
• Configuração: aplicar + reiniciar com validação (config.apply) e ativar a última sessão ativa
• Gravações de configuração incluem uma proteção por hash-base para evitar sobrescrever edições simultâneas
• Gravações de configuração (config.set/config.apply/config.patch) também fazem uma verificação preliminar da resolução ativa de SecretRef para refs na carga de configuração enviada; refs ativos não resolvidos na carga enviada são rejeitados antes da gravação
• Esquema de configuração + renderização de formulário (config.schema / config.schema.lookup, incluindo title / description do campo, dicas de UI correspondentes, resumos imediatos de filhos, metadados de documentação em nós de objeto curinga/aninhado/array/composição, além de esquemas de plugins + canais quando disponíveis); o editor JSON bruto está disponível apenas quando o snapshot tem um round-trip bruto seguro
• Se um snapshot não puder fazer round-trip de texto bruto com segurança, a Interface de controle força o modo Formulário e desabilita o modo Bruto para esse snapshot
• 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/saúde/modelos + log de eventos + chamadas RPC manuais (status, health, models.list)
• Logs: tail ao vivo dos logs de arquivo do gateway com filtro/exportação (logs.tail)
• Atualização: executar uma atualização de pacote/git + reinício (update.run) com um relatório de reinício

• Para jobs isolados, a entrega usa por padrão resumo de anúncio. Você pode alternar para nenhum se quiser execuções somente internas.
• Os campos de canal/destino aparecem quando anúncio é 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.
• Os 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/thinking de agente e alternâncias de entrega em regime de melhor esforço.
• A validação do formulário é inline com erros no nível do 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: jobs legados armazenados com notify: true ainda podem usar cron.webhook até serem migrados.

​

Comportamento do chat

• chat.send é não bloqueante: ele confirma imediatamente com { runId, status: "started" } e a resposta é transmitida por eventos chat.
• Reenviar com a mesma idempotencyKey retorna { status: "in_flight" } durante a execução e { status: "ok" } após a conclusão.
• As respostas de chat.history são limitadas em 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 superdimensionadas por um placeholder ([chat.history omitted: message too large]).
• chat.history também remove tags de diretiva inline apenas de exibição do texto visível do assistente (por exemplo [[reply_to_*]] e [[audio_as_voice]]), cargas 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 do modelo ASCII/largura total vazados, e omite entradas de assistente cujo texto visível inteiro seja apenas o token silencioso exato NO_REPLY / no_reply.
• chat.inject acrescenta uma observação de 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).
• Os seletores de modelo e thinking do cabeçalho do chat aplicam patch na sessão ativa imediatamente por meio de sessions.patch; são substituições persistentes da sessão, não opções de envio para apenas um turno.
• Interrupção:
  • Clique em Stop (chama chat.abort)
  • Digite /stop (ou frases autônomas de interrupção 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
• Retenção parcial em abortos:
  • Quando uma execução é abortada, texto parcial do assistente ainda pode ser exibido 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 possam distinguir parciais de abortos da saída normal de conclusão

​

Acesso Tailnet (recomendado)

​

Tailscale Serve integrado (preferido)

openclaw gateway --tailscale serve

• https://<magicdns>/ (ou o gateway.controlUi.basePath configurado)

​

Vincular à tailnet + token

openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"

• http://<tailscale-ip>:18789/ (ou o gateway.controlUi.basePath configurado)

​

HTTP inseguro

• compatibilidade de HTTP inseguro somente para localhost com gateway.controlUi.allowInsecureAuth=true
• autenticação bem-sucedida da Interface de controle do operador por meio de gateway.auth.mode: "trusted-proxy"
• uso emergencial de gateway.controlUi.dangerouslyDisableDeviceAuth=true

• 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" },
  },
}

• Permite que sessões da Interface de controle em localhost prossigam sem identidade de dispositivo em contextos HTTP não seguros.
• Não ignora verificações de pareamento.
• Não flexibiliza requisitos remotos (não localhost) de identidade de dispositivo.

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

• autenticação bem-sucedida de proxy confiável pode permitir sessões de operador da Interface de controle sem identidade de dispositivo
• isso não se estende a sessões da Interface de controle com papel de nó
• proxies reversos em loopback no mesmo host ainda não satisfazem a autenticação de proxy confiável; consulte Autenticação de proxy confiável

​

Como compilar a UI

pnpm ui:build # instala automaticamente as dependências da UI na primeira execução

OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build

pnpm ui:dev # instala automaticamente as dependências da UI na primeira execução

​

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

1. Inicie o servidor de desenvolvimento da UI: pnpm ui:dev
2. Abra uma URL como:

http://localhost:5173/?gatewayUrl=ws://<gateway-host>:18789

http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-token>

• gatewayUrl é armazenado em localStorage após o carregamento e removido da URL.
• 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 legados de consulta ?token= ainda são importados uma vez por compatibilidade, mas apenas como fallback, e são removidos imediatamente após o bootstrap.
• password é mantido apenas em memória.
• Quando gatewayUrl está definido, a UI não recorre a credenciais de configuração ou de 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 é aceito apenas em uma janela de nível superior (não incorporada) para evitar clickjacking.
• Implantações não loopback da Interface de controle devem definir gateway.controlUi.allowedOrigins explicitamente (origens completas). Isso inclui configurações remotas de desenvolvimento.
• Não use gateway.controlUi.allowedOrigins: ["*"] exceto em testes locais estritamente 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.

{
  gateway: {
    controlUi: {
      allowedOrigins: ["http://localhost:5173"],
    },
  },
}

​

Relacionado

• Dashboard — dashboard do gateway
• WebChat — interface de chat baseada em navegador
• TUI — interface de usuário de terminal
• Verificações de integridade — monitoramento de integridade do gateway