openclaw agent

Execute uma rodada de agente via Gateway (use --local para incorporado). Use --agent <id> para direcionar diretamente a um agente configurado.

Passe pelo menos um seletor de sessão:

• --to <dest>
• --session-key <key>
• --session-id <id>
• --agent <id>

Relacionado:

• Ferramenta de envio do agente: Envio do agente

Opções

• -m, --message <text>: corpo da mensagem
• --message-file <path>: lê o corpo da mensagem de um arquivo UTF-8
• -t, --to <dest>: destinatário usado para derivar a chave da sessão
• --session-key <key>: chave de sessão explícita a ser usada para roteamento
• --session-id <id>: id de sessão explícito
• --agent <id>: id do agente; substitui as vinculações de roteamento
• --model <id>: substituição de modelo para esta execução (provider/model ou id do modelo)
• --thinking <level>: nível de raciocínio do agente (off, minimal, low, medium, high, além de níveis personalizados compatíveis com o provedor, como xhigh, adaptive ou max)
• --verbose <on|off>: persiste o nível detalhado da sessão
• --channel <channel>: canal de entrega; omita para usar o canal principal da sessão
• --reply-to <target>: substituição do destino de entrega
• --reply-channel <channel>: substituição do canal de entrega
• --reply-account <id>: substituição da conta de entrega
• --local: executa o agente incorporado diretamente (após o pré-carregamento do registro de plugins)
• --deliver: envia a resposta de volta ao canal/destino selecionado
• --timeout <seconds>: substitui o tempo limite do agente (padrão 600 ou valor de configuração)
• --json: gera JSON

Exemplos

openclaw agent --to +15555550123 --message "status update" --deliveropenclaw agent --agent ops --message "Summarize logs"openclaw agent --agent ops --message-file ./task.mdopenclaw agent --agent ops --model openai/gpt-5.4 --message "Summarize logs"openclaw agent --session-key agent:ops:incident-42 --message "Summarize status"openclaw agent --agent ops --session-key incident-42 --message "Summarize status"openclaw agent --session-id 1234 --message "Summarize inbox" --thinking mediumopenclaw agent --to +15555550123 --message "Trace logs" --verbose on --jsonopenclaw agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"openclaw agent --agent ops --message "Run locally" --local

Observações

• Passe exatamente um de --message ou --message-file. --message-file preserva o conteúdo multilinha do arquivo após remover um BOM UTF-8 opcional e rejeita arquivos que não sejam UTF-8 válido.
• O modo Gateway recorre ao agente incorporado quando a solicitação ao Gateway falha. Use --local para forçar a execução incorporada desde o início.
• --local ainda pré-carrega primeiro o registro de plugins, portanto provedores, ferramentas e canais fornecidos por plugins permanecem disponíveis durante execuções incorporadas.
• --local e execuções de fallback incorporado são tratadas como execuções avulsas. Recursos MCP loopback agrupados e sessões Claude stdio aquecidas abertas para esse processo local são encerrados após a resposta, para que invocações por script não mantenham processos filhos locais ativos.
• Execuções com suporte do Gateway deixam recursos MCP loopback pertencentes ao Gateway sob o processo Gateway em execução; clientes mais antigos ainda podem enviar a flag histórica de limpeza, mas o Gateway a aceita como uma operação sem efeito por compatibilidade.
• --channel, --reply-channel e --reply-account afetam a entrega da resposta, não o roteamento da sessão.
• --session-key seleciona uma chave de sessão explícita. Chaves com prefixo de agente devem usar agent:<agent-id>:<session-key>, e --agent deve corresponder ao id do agente da chave quando ambos forem fornecidos. Chaves nuas que não sejam sentinelas ficam no escopo de --agent quando fornecido, ou do agente padrão configurado caso contrário; por exemplo, --agent ops --session-key incident-42 roteia para agent:ops:incident-42. Literais global e unknown permanecem sem escopo somente quando nenhum --agent é fornecido; nesse caso, o fallback incorporado e a propriedade do armazenamento usam o agente padrão configurado.
• --json mantém stdout reservado para a resposta JSON. Diagnósticos de Gateway, plugins e fallback incorporado são roteados para stderr para que scripts possam analisar stdout diretamente.
• O JSON do fallback incorporado inclui meta.transport: "embedded" e meta.fallbackFrom: "gateway" para que scripts possam distinguir execuções de fallback de execuções Gateway.
• Se o Gateway aceitar uma execução de agente, mas a CLI atingir o tempo limite aguardando a resposta final, o fallback incorporado usa um novo id explícito de sessão/execução gateway-fallback-* e relata meta.fallbackReason: "gateway_timeout" mais os campos de sessão do fallback. Isso evita disputar o bloqueio da transcrição pertencente ao Gateway ou substituir silenciosamente a sessão original da conversa roteada.
• Para execuções com suporte do Gateway, SIGTERM e SIGINT interrompem a solicitação da CLI em espera. Se o Gateway já tiver aceitado a execução, a CLI também envia chat.abort para esse id de execução aceito antes de sair. Execuções locais com --local e execuções de fallback incorporado recebem o mesmo sinal de aborto, mas não enviam chat.abort. Se um --run-id duplicado chegar ao Gateway enquanto a execução original do agente ainda estiver ativa, a resposta duplicada relata status: "in_flight" e a CLI não JSON imprime um diagnóstico em stderr em vez de uma resposta vazia. Para wrappers externos cron/systemd, mantenha um limite externo de encerramento forçado, como timeout -k 60 600 openclaw agent ..., para que o supervisor ainda possa recolher o processo se o desligamento não puder ser esvaziado.
• Quando este comando aciona a regeneração de models.json, credenciais de provedor gerenciadas por SecretRef são persistidas como marcadores não secretos (por exemplo, nomes de variáveis de ambiente, secretref-env:ENV_VAR_NAME ou secretref-managed), não como texto simples de segredo resolvido.
• Escritas de marcadores têm a fonte como autoridade: o OpenClaw persiste marcadores do snapshot de configuração da fonte ativa, não dos valores secretos resolvidos em tempo de execução.

Status de entrega JSON

Quando --json --deliver é usado, a resposta JSON da CLI pode incluir deliveryStatus no nível superior para que scripts possam distinguir envios entregues, suprimidos, parciais e com falha:

{  "payloads": [{ "text": "Report ready", "mediaUrl": null }],  "meta": { "durationMs": 1200 },  "deliveryStatus": {    "requested": true,    "attempted": true,    "status": "sent",    "succeeded": true,    "resultCount": 1  }}

deliveryStatus.status é um de sent, suppressed, partial_failed ou failed. suppressed significa que a entrega intencionalmente não foi enviada, por exemplo, um hook de envio de mensagem a cancelou ou não havia resultado visível; ainda assim, é um resultado terminal sem nova tentativa. partial_failed significa que pelo menos um payload foi enviado antes que um payload posterior falhasse. failed significa que nenhum envio durável foi concluído ou que a pré-validação da entrega falhou.

Respostas da CLI com suporte do Gateway também preservam o formato bruto do resultado do Gateway, no qual o mesmo objeto está disponível em result.deliveryStatus.

Campos comuns:

• requested: sempre true quando o objeto está presente.
• attempted: true depois que o caminho de envio durável foi executado; false para falhas de pré-validação ou ausência de payloads visíveis.
• succeeded: true, false ou "partial"; "partial" acompanha status: "partial_failed".
• reason: um motivo em snake-case minúsculo da entrega durável ou da validação de pré-execução. Motivos conhecidos incluem cancelled_by_message_sending_hook, no_visible_payload, no_visible_result, channel_resolved_to_internal, unknown_channel, invalid_delivery_target e no_delivery_target; envios duráveis com falha também podem relatar a etapa que falhou. Trate valores desconhecidos como opacos porque o conjunto pode se expandir.
• resultCount: número de resultados de envio do canal quando disponível.
• sentBeforeError: true quando uma falha parcial enviou pelo menos um payload antes do erro.
• error: booleano true para envios com falha ou parcialmente com falha.
• errorMessage: incluído somente quando uma mensagem de erro de entrega subjacente é capturada. Falhas de pré-validação carregam error e reason, mas nenhum errorMessage.
• payloadOutcomes: resultados opcionais por payload com index, status, reason, resultCount, error, stage, sentBeforeError ou metadados de hook quando disponíveis.

Relacionado

• Referência da CLI
• Runtime do agente