Auxiliares de depuração para saída de streaming, especialmente quando um provedor mistura raciocínio ao texto normal.Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
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 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 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
UseOPENCLAW_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:
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:OPENCLAW_RUN_NODE_CPU_PROF_DIR:
.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:
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: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:
--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:
--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:
--devglobal (perfil): isola estado em~/.openclaw-deve define a porta padrão do gateway como19001(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).
pnpm openclaw ....
O que isso faz:
-
Isolamento de perfil (
--devglobal)OPENCLAW_PROFILE=devOPENCLAW_STATE_DIR=~/.openclaw-devOPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.jsonOPENCLAW_GATEWAY_PORT=19001(browser/canvas se deslocam de acordo)
-
Bootstrap de desenvolvimento (
gateway --dev)- Escreve uma configuração mínima se ausente (
gateway.mode=local, vincular ao loopback). - Define
agent.workspacecomo 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).
- Escreve uma configuração mínima se ausente (
--dev é uma flag de perfil global e é consumida por alguns executores. Se você precisar escrevê-la explicitamente, use a forma de variável de ambiente:--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:~/.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-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çõeslaunch.json incluídas miram o serviço Gateway, mas podem ser adaptadas rapidamente para outros fins:
- Rebuild and Debug Gateway - Depura o serviço Gateway após criar um novo build
- 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:
- Abra o painel Run and Debug na Activity Bar ou pressione
Ctrl+Shift+D - 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
- 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
- Linux/macOS:
- No mesmo terminal, recompile o projeto:
pnpm clean:dist && pnpm build - 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
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
/diste executará umpnpm buildcompleto 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.jsonparaargspara depurar outras seções do projeto - Se você precisar usar a CLI compilada do OpenClaw para outras tarefas (ou seja,
dashboard --no-opense sua sessão de depuração gerar um novo token de autenticação), pode executá-la em outro terminal comonode ./openclaw.mjsou criar um alias de shell comoalias openclaw-build="node $(pwd)/openclaw.mjs"