Depuração

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 tempo de execução

Use /debug no chat para definir substituições de configuração somente em tempo de execução (memória, não disco). /debug fica desabilitado 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 da sessão

Use /trace quando quiser ver linhas de rastreamento/depuração pertencentes ao Plugin em uma sessão sem ativar o modo detalhado completo.

Exemplos:

/trace/trace on/trace off

Use /trace para diagnósticos de Plugin, como resumos de depuração da Active Memory. Continue usando /verbose para saída detalhada normal de status/ferramentas, e continue usando /debug para substituições de configuração somente em tempo de execução.

Rastreamento do ciclo de vida do Plugin

Use OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 quando os comandos de ciclo de vida do 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 permanece analisável.

Exemplo:

OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force

Exemplo de saída:

[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 do ciclo de vida do 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 ... depois de pnpm build; pnpm openclaw ... também mede a sobrecarga do executor de código-fonte.

Inicialização da CLI e perfilamento de comandos

Use o benchmark de inicialização versionado quando um comando parecer lento:

pnpm test:startup:bench:smokepnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu

Para perfilamento 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 escreve 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 do sistema de arquivos ou do 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 desabilitada por padrão para o processo filho do 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 se anexa automaticamente a terminais interativos. Shells não interativos, CI e chamadas exec de agentes permanecem desanexados e imprimem instruções de anexação. 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# orOPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch

Desabilite a anexação automática mantendo o gerenciamento por tmux:

OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch

Faça o perfilamento 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 escreve um .cpuprofile do V8 por encerramento de processo filho do Gateway em .artifacts/gateway-watch-profiles/. Pare ou reinicie o gateway monitorado para descarregar o perfil atual, então 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 processo filho medido ignore a limpeza de porta --force padrão e falhe rapidamente 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 stack traces de E/S síncrona do Node. No modo benchmark, esses blocos de rastreamento são escritos em gateway-watch-output.log dentro do diretório de benchmark e filtrados do painel do terminal; logs normais do Gateway permanecem visíveis.

O wrapper tmux leva 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 processo filho do Gateway. Use OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 quando quiser a falha de inicialização original sem a passagem de reparo exclusiva de desenvolvimento. O painel tmux gerenciado também usa logs coloridos do Gateway por padrão para legibilidade; defina FORCE_COLOR=0 ao iniciar pnpm gateway:watch para desabilitar 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 de metadados de extensão reiniciam o gateway sem forçar um rebuild do tsdown; alterações de código-fonte e configuração ainda recompilam 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 processos pais de observador duplicados sejam substituídos em vez de se acumularem.

Perfil de desenvolvimento + gateway de desenvolvimento (--dev)

Use o perfil de desenvolvimento para isolar estado e subir uma configuração segura e descartável para depuração. Existem duas flags --dev:

• --dev global (perfil): isola estado em ~/.openclaw-dev e define a porta padrão do gateway como 19001 (portas derivadas se deslocam junto).
• gateway --dev: informa ao Gateway para criar automaticamente uma configuração padrão + workspace quando ausentes (e ignorar BOOTSTRAP.md).

Fluxo recomendado (perfil de desenvolvimento + bootstrap de desenvolvimento):

pnpm gateway:devOPENCLAW_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 se deslocam de acordo)

2. Bootstrap de desenvolvimento (gateway --dev)

   • Escreve uma configuração mínima se ausente (gateway.mode=local, vincular ao loopback).
   • Define agent.workspace como o workspace de desenvolvimento.
   • Define agent.skipBootstrap=true (sem BOOTSTRAP.md).
   • Semeia 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 de desenvolvimento (OPENCLAW_SKIP_CHANNELS=1).

Fluxo de reset (início limpo):

pnpm gateway:dev:reset

--reset limpa configuração, credenciais, sessões e o workspace de desenvolvimento (usando trash, não rm), então recria a configuração de desenvolvimento padrão.

Registro de stream bruto (OpenClaw)

O OpenClaw pode registrar o stream bruto do assistente antes de qualquer filtragem/formatação. Essa é a melhor forma de ver se o raciocínio está chegando como deltas de texto simples (ou como blocos de thinking separados).

Habilite via CLI:

pnpm gateway:watch --raw-stream

Substituição de caminho opcional:

pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl

Variáveis de ambiente equivalentes:

OPENCLAW_RAW_STREAM=1OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl

Arquivo padrão:

~/.openclaw/logs/raw-stream.jsonl

Registro de chunks brutos (pi-mono)

Para capturar chunks brutos compatíveis com OpenAI antes de serem analisados em blocos, pi-mono expõe um registrador separado:

PI_RAW_STREAM=1

Caminho opcional:

PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl

Arquivo padrão:

~/.pi-mono/logs/raw-openai-completions.jsonl

Observação: isso é emitido apenas por processos que usam o provedor openai-completions do pi-mono.

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 miram 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 vem com tudo incluído; ela excluirá automaticamente a pasta /dist e recompilará o projeto com depuração habilitada:

1. Abra o painel Run and Debug na Activity Bar ou pressione Ctrl+Shift+D
2. Na IDE, garanta 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 você 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, recompile 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 de código-fonte TypeScript (diretório src/) e o depurador mapeará corretamente os breakpoints para o JavaScript compilado via source maps. Você poderá inspecionar variáveis, avançar pelo código e examinar call stacks como esperado.

Observações

• Se estiver usando 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 estiver usando 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 para habilitar a depuração e gerenciar o ciclo de build
• Modifique as configurações de launch.json para args para depurar outras seções do projeto
• Se você precisar usar a CLI compilada do OpenClaw para outras tarefas (ou seja, dashboard --no-open se sua sessão de depuração gerar um novo token de autenticação), pode executá-la em outro terminal como node ./openclaw.mjs ou criar um alias de shell como alias openclaw-build="node $(pwd)/openclaw.mjs"

Relacionados

• Solução de problemas
• FAQ