Pular para o conteúdo principal
Auxiliares de depuração para saída de streaming, especialmente quando um provedor mistura raciocínio ao texto normal.

​
Substituições de depuração em runtime

Use /debug no chat para definir substituições de configuração somente em runtime (memória, não disco). /debug é desativado por padrão; habilite com commands.debug: true. Isso é útil quando você precisa alternar configurações obscuras sem editar openclaw.json. Exemplos: 
/debug show
/debug set messages.responsePrefix="[openclaw]"
/debug unset messages.responsePrefix
/debug reset
/debug reset limpa todas as substituições e retorna à configuração em disco.

​
Saída de rastreamento de sessão

Use /trace quando quiser ver linhas de rastreamento/depuração pertencentes ao Plugin em uma sessão sem ativar o modo verboso completo. Exemplos: 
/trace
/trace on
/trace off
Use /trace para diagnósticos de Plugin, como resumos de depuração de Active Memory. Continue usando /verbose para saída verbosa normal de status/ferramentas, e continue usando /debug para substituições de configuração somente em runtime.

​
Rastreamento de ciclo de vida do Plugin

Use OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 quando comandos de ciclo de vida de Plugin parecerem lentos e você precisar de uma decomposição de fases integrada para metadados de Plugin, descoberta, registro, espelho de runtime, mutação de configuração e trabalho de atualização. O rastreamento é opcional e escreve em stderr, então a saída JSON do comando continua analisável. Exemplo: 
OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force
Saída de exemplo: 
[plugins:lifecycle] phase="config read" ms=6.83 status=ok command="install"
[plugins:lifecycle] phase="slot selection" ms=94.31 status=ok command="install" pluginId="tokenjuice"
[plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed"
Use isso para investigação de ciclo de vida de Plugin antes de recorrer a um profiler de CPU. Se o comando estiver sendo executado a partir de um checkout de código-fonte, prefira medir o runtime compilado com node dist/entry.js ... após pnpm build; pnpm openclaw ... também mede a sobrecarga do executor de código-fonte.

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

Use o benchmark de inicialização versionado quando um comando parecer lento: 
pnpm test:startup:bench:smoke
pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3
pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu
Para criação de perfil pontual pelo executor de código-fonte normal, defina OPENCLAW_RUN_NODE_CPU_PROF_DIR: 
OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status
O executor de código-fonte adiciona flags de perfil de CPU do Node e grava um .cpuprofile para o comando. Use isso antes de adicionar instrumentação temporária ao código do comando. Para travamentos de inicialização que parecem trabalho síncrono de sistema de arquivos ou carregador de módulos, adicione a flag de rastreamento de E/S síncrona do Node pelo executor de código-fonte: 
OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force
pnpm gateway:watch deixa essa flag desativada por padrão para o filho Gateway monitorado. Defina OPENCLAW_TRACE_SYNC_IO=1 quando você quiser explicitamente a saída de rastreamento de E/S síncrona do Node no modo watch.

​
Modo watch do Gateway

Para iteração rápida, execute o gateway sob o observador de arquivos: 
pnpm gateway:watch
Por padrão, isso inicia ou reinicia uma sessão tmux chamada openclaw-gateway-watch-main (ou uma variante específica de perfil/porta, como openclaw-gateway-watch-dev-19001) e anexa automaticamente a partir de terminais interativos. Shells não interativos, CI e chamadas de execução de agentes permanecem desanexados e imprimem instruções de anexação em vez disso. Anexe manualmente quando necessário: 
tmux attach -t openclaw-gateway-watch-main
O painel tmux executa o observador bruto: 
node scripts/watch-node.mjs gateway --force
Use o modo em primeiro plano quando tmux não for desejado: 
pnpm gateway:watch:raw
# or
OPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch
Desative a anexação automática mantendo o gerenciamento do tmux: 
OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch
Crie perfil do tempo de CPU do Gateway monitorado ao depurar pontos críticos de inicialização/runtime: 
pnpm gateway:watch --benchmark
O wrapper de watch consome --benchmark antes de invocar o Gateway e grava um .cpuprofile V8 por saída de filho Gateway em .artifacts/gateway-watch-profiles/. Pare ou reinicie o gateway monitorado para liberar o perfil atual, depois abra-o com Chrome DevTools ou Speedscope: 
npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile
Use --benchmark-dir <path> quando quiser perfis em outro lugar. Use --benchmark-no-force quando quiser que o filho submetido a benchmark ignore a limpeza de porta padrão --force e falhe rápido se a porta do Gateway já estiver em uso. O modo benchmark suprime spam de rastreamento de E/S síncrona por padrão. Defina OPENCLAW_TRACE_SYNC_IO=1 com --benchmark quando quiser explicitamente perfis de CPU e rastreamentos de pilha de E/S síncrona do Node. No modo benchmark, esses blocos de rastreamento são gravados em gateway-watch-output.log sob o diretório de benchmark e filtrados do painel do terminal; logs normais do Gateway permanecem visíveis. O wrapper tmux carrega seletores comuns de runtime não secretos, como OPENCLAW_PROFILE, OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, OPENCLAW_GATEWAY_PORT e OPENCLAW_SKIP_CHANNELS para dentro do painel. Coloque credenciais de provedor no seu perfil/configuração normal ou use o modo bruto em primeiro plano para segredos efêmeros pontuais. Se o Gateway monitorado sair durante a inicialização, o observador executa openclaw doctor --fix --non-interactive uma vez e reinicia o filho Gateway. Use OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 quando quiser a falha original de inicialização sem a etapa de reparo exclusiva de desenvolvimento. O painel tmux gerenciado também usa por padrão logs coloridos do Gateway para legibilidade; defina FORCE_COLOR=0 ao iniciar pnpm gateway:watch para desativar a saída ANSI. O observador reinicia em arquivos relevantes para build sob src/, arquivos de código-fonte de extensão, metadados package.json e openclaw.plugin.json de extensão, tsconfig.json, package.json e tsdown.config.ts. Alterações em metadados de extensão reiniciam o gateway sem forçar um rebuild tsdown; alterações de código-fonte e configuração ainda reconstroem dist primeiro. Adicione quaisquer flags da CLI do gateway após gateway:watch e elas serão repassadas em cada reinicialização. Executar novamente o mesmo comando de watch recria o painel tmux nomeado, e o observador bruto ainda mantém seu bloqueio de observador único para que pais observadores duplicados sejam substituídos em vez de se acumularem.

​
Perfil dev + gateway dev (—dev)

Use o perfil dev para isolar o estado e iniciar uma configuração segura e descartável para depuração. Há duas flags --dev:
  • --dev global (perfil): isola o estado em ~/.openclaw-dev e define a porta padrão do gateway como 19001 (portas derivadas mudam junto com ela).
  • gateway --dev: informa ao Gateway para criar automaticamente uma configuração + workspace padrão quando ausentes (e ignorar BOOTSTRAP.md).
Fluxo recomendado (perfil dev + bootstrap dev): 
pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui
Se você ainda não tiver uma instalação global, execute a CLI via pnpm openclaw .... O que isso faz:
  1. Isolamento de perfil (--dev global)
    • OPENCLAW_PROFILE=dev
    • OPENCLAW_STATE_DIR=~/.openclaw-dev
    • OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
    • OPENCLAW_GATEWAY_PORT=19001 (browser/canvas mudam conforme necessário)
  2. Bootstrap dev (gateway --dev)
    • Grava uma configuração mínima se ausente (gateway.mode=local, bind loopback).
    • Define agent.workspace para o workspace dev.
    • Define agent.skipBootstrap=true (sem BOOTSTRAP.md).
    • Inicializa os arquivos do workspace se ausentes: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md.
    • Identidade padrão: C3-PO (droide de protocolo).
    • Ignora provedores de canal no modo dev (OPENCLAW_SKIP_CHANNELS=1).
Fluxo de redefinição (início limpo): 
pnpm gateway:dev:reset
--dev é uma flag de perfil global e é consumida por alguns executores. Se você precisar explicitá-la, use a forma de variável de ambiente:
OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
--reset apaga configuração, credenciais, sessões e o workspace dev (usando trash, não rm), depois recria a configuração dev padrão.
Se um gateway não dev já estiver em execução (launchd ou systemd), pare-o primeiro:
openclaw gateway stop

​
Registro de stream bruto (OpenClaw)

OpenClaw pode registrar o stream bruto do assistente antes de qualquer filtragem/formatação. Essa é a melhor maneira de ver se o raciocínio está chegando como deltas de texto simples (ou como blocos de pensamento separados). Habilite via CLI: 
pnpm gateway:watch --raw-stream
Substituição opcional de caminho: 
pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl
Variáveis de ambiente equivalentes: 
OPENCLAW_RAW_STREAM=1
OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl
Arquivo padrão: ~/.openclaw/logs/raw-stream.jsonl

​
Registro de chunks OpenAI compatíveis brutos

Para capturar chunks OpenAI compatíveis brutos antes que sejam analisados em blocos, habilite o registrador de transporte: 
OPENCLAW_RAW_STREAM=1
Caminho opcional: 
OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-openai-completions.jsonl
Arquivo padrão: ~/.openclaw/logs/raw-openai-completions.jsonl

​
Notas de segurança

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

​
Depuração no VSCode

Source maps são necessários para habilitar a depuração em IDEs baseadas em VSCode porque muitos dos arquivos gerados acabam com nomes com hash como parte do processo de build. As configurações launch.json incluídas têm como alvo o serviço Gateway, mas podem ser adaptadas rapidamente para outros fins:
  1. Rebuild and Debug Gateway - Depura o serviço Gateway após criar um novo build
  2. Debug Gateway - Depura o serviço Gateway de um build preexistente

​
Configuração

A configuração padrão Rebuild and Debug Gateway é completa, ela excluirá automaticamente a pasta /dist e reconstruirá o projeto com depuração habilitada:
  1. Abra o painel Run and Debug na Activity Bar ou pressione Ctrl+Shift+D
  2. Na IDE, certifique-se de que Rebuild and Debug Gateway esteja selecionado no menu suspenso de configuração e então pressione o botão Start Debugging
Como alternativa - se preferir gerenciar manualmente os processos de build e depuração:
  1. Abra um terminal e habilite source maps:
    • Linux/macOS: export OUTPUT_SOURCE_MAPS=1
    • Windows (PowerShell): $env:OUTPUT_SOURCE_MAPS="1"
    • Windows (CMD): set OUTPUT_SOURCE_MAPS=1
  2. No mesmo terminal, reconstrua o projeto: pnpm clean:dist && pnpm build
  3. Na IDE, selecione a opção Debug Gateway no menu suspenso de configuração Run and Debug e então pressione o botão Start Debugging
Agora você pode definir breakpoints nos seus arquivos-fonte TypeScript (diretório src/) e o depurador mapeará corretamente os breakpoints para o JavaScript compilado via source maps. Você poderá inspecionar variáveis, percorrer o código passo a passo e examinar call stacks conforme esperado.

​
Observações

  • Se usar a opção “Rebuild and Debug Gateway” - cada vez que o depurador for iniciado, ele excluirá completamente a pasta /dist e executará um pnpm build completo com source maps habilitados antes de iniciar o Gateway
  • Se usar a opção “Debug Gateway” - sessões de depuração podem ser iniciadas e interrompidas a qualquer momento sem afetar a pasta /dist, mas você deve usar um processo de terminal separado tanto para habilitar a depuração quanto para gerenciar o ciclo de build
  • Modifique as configurações launch.json de args para depurar outras seções do projeto
  • Se você precisar usar a CLI OpenClaw compilada para outras tarefas (ou seja, dashboard --no-open se sua sessão de depuração gerar um novo token de autenticação), poderá executá-la em outro terminal como node ./openclaw.mjs ou criar um alias de shell como alias openclaw-build="node $(pwd)/openclaw.mjs"

​
Relacionados