openclaw-debugging

Depuração do OpenClaw

O comportamento difere entre testes locais, modelos ao vivo, provedores, code-mode, Tool Search, Crabbox e CI: obtenha sinal de depuração antes de adivinhar.

Leia Primeiro

• docs/logging.md: arquivos de log, openclaw logs, flags de depuração direcionadas.
• docs/reference/test.md: comandos de teste local.
• docs/tools/code-mode.md: execução/espera do code-mode + regras do catálogo de ferramentas.
• $openclaw-testing: escolha da faixa de teste.
• $crabbox: prova ampla, Docker, pacote, Linux, chave ao vivo, paridade com CI.

Loop Padrão

1. Declare a fronteira suspeita: configuração, construção de ferramenta, payload do provedor, fetch, stream/SSE, reprodução de transcrição, worker/runtime, pacote/dist, CI.
2. Adicione/ative o sinal mais estreito que prova a fronteira.
3. Reproduza com o mesmo provedor/modelo/config. Nunca troque de modelo aleatoriamente, a menos que o próprio modelo seja a variável testada.
4. Compare o estado configurado com a ativação real da execução.
5. Corrija a causa raiz.
6. Execute novamente a sonda exata que falhou; amplie apenas se o contrato exigir.

Logs de Transporte do Modelo

Forma da requisição do modelo/timing do stream: flags de ambiente direcionadas sobre depuração global:

OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gateway
OPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway
OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted OPENCLAW_DEBUG_SSE=peek openclaw gateway

Flags úteis:

• OPENCLAW_DEBUG_MODEL_TRANSPORT=1: início da requisição, resposta do fetch, cabeçalhos do SDK, primeiro evento SSE, stream concluído, erros de transporte em nível info.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=summary: resumo limitado do payload.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=tools: todos os nomes de ferramentas visíveis ao modelo.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted: payload JSON limitado e redigido. Use apenas durante depuração; textos de prompts/mensagens ainda podem aparecer.
• OPENCLAW_DEBUG_SSE=events: timing do primeiro evento + conclusão do stream.
• OPENCLAW_DEBUG_SSE=peek: primeiros cinco eventos SSE redigidos.
• OPENCLAW_DEBUG_CODE_MODE=1: diagnóstico da superfície de ferramentas do code-mode.

Observe os logs:

openclaw logs --follow

Fronteiras Comuns

• Config vs ativação: uma configuração ativada pode coexistir com ferramentas de execução desativadas, execução bruta, lista de permissões vazia, suporte a ferramentas do modelo ausente. Verifique as ferramentas realmente visíveis antes de impor invariantes do payload do provedor.
• Superfície de ferramentas: inspecione os nomes finais das ferramentas visíveis ao modelo, não apenas o registro/config. Code-mode = exatamente exec + wait apenas após a ativação real.
• Payload do provedor: antes da chamada ao SDK, registre campos, id do modelo, nível de serviço, raciocínio, tamanho da entrada, chaves de metadados, presença de chave de cache de prompt, nomes de ferramentas.
• Fetch vs SSE: a resposta do fetch prova que os cabeçalhos HTTP chegaram; o primeiro evento SSE prova o progresso do corpo do provedor. A lacuna aqui = problema de stream/corpo/provedor, não de execução de ferramenta.
• Worker/dist: ao mexer em workers, importações dinâmicas, exportações de pacotes, fronteiras de runtime lazy, caminhos publicados → pnpm build.
• Chaves ao vivo: chaves de provedor ausentes → fluxo de trabalho de segredo configurado antes de declarar prova ao vivo bloqueada. Verificações de ambiente apenas de presença; nunca imprima segredos.

Buscando Sessões e Transcrições

Relatório de bug de sessão de chat: busque a transcrição real, atribuição do remetente, anexos como evidência.

CLI primeiro (precisa de instalação configurada; segura contra gateway ao vivo):

openclaw sessions list --agent <agentId> --json
openclaw sessions tail
openclaw sessions export-trajectory

Documentação: layout do armazenamento docs/reference/database-schemas.md; CLI https://docs.openclaw.ai/cli/sessions.

Armazenamento bruto: CLI indisponível (ex.: host remoto via SSH) ou necessidade de detalhes no nível do evento:

• Plano de dados por agente: ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. Esquema canônico: src/state/openclaw-agent-schema.sql.
• Estado hospedado/systemd: home do usuário do serviço (ex.: /home/openclaw/.openclaw/...), não do root. Root pode ter uma instalação separada e órfã com agentes diferentes. Diretório de agente esperado ausente: localize o DB real com find / -maxdepth 6 -name openclaw-agent.sqlite.
• Fragmento de ID de sessão da URL do chat web: /chat/<agentId>/<slug>-<hex>. Resolva em session_nodes: session_key LIKE '%<hex>%' → current_session_id, display_name. Formato da chave: agent:<agentId>:<surface>:<uuid>; sessões de subagente usam surface subagent.
• Transcrição: transcript_events (session_id, seq, event_json). event_json.message: role (user/assistant/toolResult) + content (string ou partes do tipo text/toolCall/image).
• Proveniência do remetente: mensagens de usuário reais carregam message.__openclaw (senderId, senderName, senderIsOwner); entradas sintetizadas pelo runtime não. Distinga texto criado pelo operador de prompts injetados com isso.
• Busca de texto completo na transcrição: session_transcript_fts.
• Anexos: URLs media://inbound/<file> → <state-dir>/media/inbound/<file>.
• Imagens anexadas pelo usuário ≠ partes de conteúdo image. O envelope da mensagem carrega entradas message.__openclaw.media[]: url (media://inbound/<file>), contentType, kind, fileName. Um extrator apenas de partes perde todas as imagens; grep no event_json bruto por media://. Host remoto: faça scp dos arquivos localmente (um caminho remoto por argumento scp); leia lá.

Hosts sem o binário sqlite3 ainda têm Node: node:sqlite não precisa de dependências.

node -e 'const {DatabaseSync}=require("node:sqlite");
const db=new DatabaseSync(process.argv[1],{readOnly:true});
console.log(JSON.stringify(db.prepare(
  "SELECT seq,event_json FROM transcript_events WHERE session_id=? ORDER BY seq"
).all(process.argv[2])))' <db-path> <session-id>

• Sempre abra armazenamentos ao vivo com readOnly: true; nunca escreva no estado do gateway em execução (regras de validação do AGENTS.md raiz).
• Trabalho com dados realistas: copie o DB para o diretório de estado de desenvolvimento primeiro.

Ponteiros de Código

• Payload do modelo + stream Responses: src/agents/openai-transport-stream.ts
• Fetch/timing protegido: src/agents/provider-transport-fetch.ts
• Wrappers de provedor OpenAI/Codex: src/llm/providers/stream-wrappers/openai.ts
• Construção de ferramentas, Tool Search, ativação do code-mode: src/agents/embedded-agent-runner/run/attempt.ts
• Runtime do code-mode e worker: src/agents/code-mode.ts src/agents/code-mode.worker.ts
• Catálogo do Tool Search: src/agents/tool-search.ts

Escolha da Prova

• Bug de helper/payload único: Vitest local direcionado.
• Apenas docs/logging: pnpm check:docs + git diff --check.
• Superfície de worker/dist/importação lazy/pacote: testes direcionados + pnpm build.
• Comportamento de provedor/modelo ao vivo: mesmo provedor/modelo, flags de depuração, chave real se disponível.
• Docker/pacote/Linux/paridade com CI: worker Linux dedicado atual quando capaz; caso contrário, $crabbox.
• Falha de CI: SHA exato, apenas o job relevante; logs apenas após falha/conclusão.

Hábito de Saída

Relate:

• fronteira testada
• comando exato/forma do ambiente, redigido
• sinal observado, ex.: nomes de ferramentas ou timing do primeiro evento SSE
• local da correção
• prova estreita + risco restante