Skip to main content
Auxiliares de depuração para saída em streaming, iteração do Gateway e criação de perfis de inicialização.

​
Substituições de depuração em tempo de execução

/debug define substituições de configuração somente em tempo de execução (na memória, não no disco). Desativado por padrão; ative com commands.debug: true.
/debug reset limpa todas as substituições e retorna à configuração armazenada em disco.

​
Saída de rastreamento da sessão

/trace mostra linhas de rastreamento/depuração pertencentes ao plugin para uma sessão, sem ativar o modo totalmente detalhado. Use-o para diagnósticos de plugins, como resumos de depuração da Active Memory; use /verbose para a saída normal de status/ferramentas.

​
Rastreamento do ciclo de vida do Plugin

Defina OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 para obter uma análise fase a fase de metadados, descoberta, registro, espelho de tempo de execução, mutação de configuração e trabalho de atualização dos plugins. A saída é gravada em stderr, portanto a saída JSON dos comandos permanece analisável.
Use isso antes de recorrer a um criador de perfil de CPU. Em um checkout do código-fonte, meça o tempo de execução compilado com node dist/entry.js ... após pnpm build; pnpm openclaw ... também mede a sobrecarga do executor do código-fonte.

​
Inicialização da CLI e criação de perfil de comandos

Benchmarks de inicialização versionados:
Para uma criação de perfil pontual pelo executor normal do código-fonte, defina OPENCLAW_RUN_NODE_CPU_PROF_DIR:
O executor do código-fonte adiciona os sinalizadores de perfil de CPU do Node e grava um arquivo .cpuprofile para o comando. Use isso antes de adicionar instrumentação temporária ao código do comando. Para travamentos na inicialização que pareçam trabalho síncrono do sistema de arquivos ou do carregador de módulos, adicione o sinalizador de rastreamento de E/S síncrona do Node por meio do executor do código-fonte:
pnpm gateway:watch mantém esse sinalizador desativado por padrão para o processo filho monitorado do Gateway; defina OPENCLAW_TRACE_SYNC_IO=1 quando também quiser a saída de rastreamento de E/S síncrona no modo de monitoramento.

​
Modo de monitoramento do Gateway

Por padrão, isso inicia ou reinicia uma sessão tmux chamada openclaw-gateway-watch-<profile> (por exemplo, openclaw-gateway-watch-main), com um sufixo de porta, como openclaw-gateway-watch-dev-19001, adicionado somente quando OPENCLAW_GATEWAY_PORT difere da porta padrão 18789. A sessão é anexada automaticamente em terminais interativos; shells não interativos, CI e chamadas de execução de agentes permanecem desanexados e exibem instruções de conexão:
O painel do tmux executa o monitor bruto:
Interrompa um serviço do Gateway instalado antes de monitorar a mesma porta:
O --force do monitor libera o listener atual, mas não desativa um serviço supervisionado. Caso contrário, um serviço launchd, systemd ou Scheduled Task pode reiniciar e substituir o Gateway monitorado. Modo em primeiro plano sem tmux:
Mantenha o gerenciamento pelo tmux, mas desative a conexão automática:
Crie um perfil do tempo de CPU do Gateway monitorado ao depurar pontos críticos de inicialização/tempo de execução:
O wrapper de monitoramento consome --benchmark antes de invocar o Gateway e grava um arquivo V8 .cpuprofile por encerramento de processo filho do Gateway em .artifacts/gateway-watch-profiles/. Interrompa ou reinicie o gateway monitorado para descarregar o perfil atual e depois abra-o com o Chrome DevTools ou o Speedscope:
  • --benchmark-dir <path>: grava os perfis em outro local.
  • --benchmark-no-force: ignora a limpeza padrão da porta feita por --force e falha imediatamente se a porta do Gateway já estiver em uso.
Por padrão, o modo de benchmark suprime o excesso de rastreamentos de E/S síncrona. Defina OPENCLAW_TRACE_SYNC_IO=1 com --benchmark para obter tanto os perfis de CPU quanto os rastreamentos de pilha de E/S síncrona; no modo de benchmark, esses blocos de rastreamento são gravados em gateway-watch-output.log no diretório do benchmark (filtrados do painel do terminal), enquanto os logs normais do Gateway permanecem visíveis. O wrapper do tmux transfere seletores comuns e não secretos do tempo de execução para o painel, incluindo OPENCLAW_PROFILE, OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, OPENCLAW_GATEWAY_PORT e OPENCLAW_SKIP_CHANNELS. Coloque as credenciais do provedor no seu perfil/configuração normal ou use o modo bruto em primeiro plano para segredos efêmeros pontuais. Se o Gateway monitorado encerrar durante a inicialização, o monitor executará openclaw doctor --fix --non-interactive uma vez e reiniciará o processo filho do Gateway. Defina OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 para ver a falha de inicialização original sem a etapa de reparo exclusiva para desenvolvimento. Por padrão, o painel tmux gerenciado exibe logs coloridos do Gateway; defina FORCE_COLOR=0 ao iniciar pnpm gateway:watch para desativar a saída ANSI. O monitor reinicia quando há alterações em arquivos relevantes para a compilação em src/, arquivos-fonte de extensões, metadados package.json e openclaw.plugin.json das extensões, tsconfig.json, package.json e tsdown.config.ts. Alterações nos metadados das extensões reiniciam o gateway sem forçar uma recompilação; alterações no código-fonte e na configuração ainda recompilam dist primeiro. Adicione sinalizadores da CLI do gateway após gateway:watch, e eles serão repassados a cada reinicialização. Executar novamente o mesmo comando de monitoramento recria o painel tmux nomeado; o monitor bruto mantém um bloqueio de monitor único para que processos-pai de monitoramento duplicados sejam substituídos em vez de se acumularem.

​
Perfil de desenvolvimento + gateway de desenvolvimento (—dev)

Dois sinalizadores --dev separados:
  • --dev global (perfil): isola o estado em ~/.openclaw-dev e define a porta padrão do gateway como 19001 (as portas derivadas mudam junto com ela).
  • gateway --dev: instrui o Gateway a criar automaticamente uma configuração e um espaço de trabalho padrão quando estiverem ausentes (e ignorar o bootstrap).
Fluxo recomendado (perfil de desenvolvimento + bootstrap de desenvolvimento):
Sem uma instalação global, execute a CLI por meio de pnpm openclaw .... O que isso faz:
  1. Isolamento do perfil (--dev global)
    • OPENCLAW_PROFILE=dev
    • OPENCLAW_STATE_DIR=~/.openclaw-dev
    • OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
    • OPENCLAW_GATEWAY_PORT=19001 (as portas do navegador/canvas mudam de acordo)
  2. Bootstrap de desenvolvimento (gateway --dev)
    • Grava uma configuração mínima caso esteja ausente (gateway.mode=local, vinculação a local loopback).
    • Define agents.defaults.workspace como o espaço de trabalho de desenvolvimento e agents.defaults.skipBootstrap=true.
    • Cria os arquivos do espaço de trabalho caso estejam ausentes: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md.
    • Identidade padrão: C3-PO (droide de protocolo).
    • pnpm gateway:dev também define OPENCLAW_SKIP_CHANNELS=1 para ignorar os provedores de canais.
Fluxo de redefinição (novo começo):
--dev é um sinalizador de perfil global e é consumido por alguns executores. Se precisar especificá-lo explicitamente, use a forma com variável de ambiente:
--reset apaga a configuração, as credenciais, as sessões e o espaço de trabalho de desenvolvimento (movido para a lixeira, não excluído) e depois recria a configuração de desenvolvimento padrão.
Se um gateway que não seja de desenvolvimento já estiver em execução (launchd ou systemd), interrompa-o primeiro:

​
Registro do stream bruto

O OpenClaw pode registrar o stream bruto do assistente antes de qualquer filtragem/formatação. Essa é a melhor maneira de verificar se o raciocínio está chegando como deltas de texto simples (ou como blocos de pensamento separados). Ative-o por meio da CLI:
Substituição opcional do caminho:
Variáveis de ambiente equivalentes:
Arquivo padrão: ~/.openclaw/logs/raw-stream.jsonl

​
Observações de segurança

  • Os logs do stream bruto podem incluir prompts completos, saída de ferramentas e dados do usuário.
  • Mantenha os logs localmente e exclua-os após a depuração.
  • Se compartilhar os logs, remova primeiro os segredos e dados de identificação pessoal.

​
Depuração no VSCode

Mapas de código-fonte são necessários porque a compilação aplica hashes aos nomes dos arquivos gerados. O launch.json incluído tem como alvo o serviço do Gateway:
  1. Rebuild and Debug Gateway - exclui /dist e recompila com a depuração ativada antes de iniciar o Gateway.
  2. Debug Gateway - depura uma compilação existente sem alterar /dist.

​
Configuração

  1. Abra Run and Debug (na Activity Bar ou com Ctrl+Shift+D).
  2. Selecione Rebuild and Debug Gateway e pressione Start Debugging.
Para gerenciar manualmente o ciclo de compilação/depuração:
  1. Ative os mapas de código-fonte em um terminal:
    • Linux/macOS: export OUTPUT_SOURCE_MAPS=1
    • Windows (PowerShell): $env:OUTPUT_SOURCE_MAPS="1"
    • Windows (CMD): set OUTPUT_SOURCE_MAPS=1
  2. Recompile: pnpm clean:dist && pnpm build
  3. Selecione Debug Gateway e pressione Start Debugging.
Defina pontos de interrupção nos arquivos TypeScript em src/; o depurador os mapeia para o JavaScript compilado por meio dos mapas de código-fonte.

​
Observações

  • Rebuild and Debug Gateway exclui /dist e executa um pnpm build completo com mapas de código-fonte em cada inicialização.
  • Debug Gateway pode ser iniciado/interrompido sem afetar /dist, mas você gerencia o ciclo de compilação em um terminal separado.
  • Edite os args de launch.json para depurar outros subcomandos da CLI.
  • Para usar a CLI compilada em outras tarefas (por exemplo, dashboard --no-open caso sua sessão de depuração gere um novo token de autenticação), execute-a em outro terminal: node ./openclaw.mjs ou use um alias como alias openclaw-build="node $(pwd)/openclaw.mjs".

​
Relacionados