Pular para o conteúdo
PT
Obter chave API
Explorar documentação

Guias

Executar tarefas de agente recorrentes

Reutilizar acesso aprovado, fazer uma busca por ocorrência programada, e se recuperar sem acidentalmente enviar o mesmo trabalho novamente.

Nesta página

Escolha como a tarefa corre

Seu agente anfitrião ou programador OS fornece o tempo. FlashData fornece os dados. Escolha um caminho de execução e teste-o no ambiente que será executado sem vigilância.

UsePor..Estado a preservar
CLIUm agente com acesso terminal, cron, ou um roteiro agendado.O perfil CLI, o diretório de estado e a execução original ID.
MCPUm host de agente com um servidor FlashData conectado.Credenciais do anfitrião, registro de ocorrência, trabalho IDs e resultados.

Verifique o acesso no ambiente programado

Reutilize uma conexão existente com a permissão google_search. Reivindicar acesso temporário antes do uso recorrente. Teste de um novo processo ou sessão programada, não apenas interativo.

Use Bash e jq (Git Bash em Windows), sob o usuário OS que salvou a chave. Defina seu perfil e diretório de estado absoluto abaixo. Executar ambos os blocos no mesmo terminal, o corredor reutiliza essas configurações.

A verificação de acesso deve imprimir true. Compare availableCredits com estimatedCredits antes da primeira busca. Esses verificações não enviam uma pergunta.

Defina sua conexão salva
# Use the profile and state directory that already hold your owner key.
export FLASHDATA_PROFILE='research'
export FLASHDATA_STATE_DIR='/absolute/path/to/existing/flashdata-state'
export FLASHDATA_BIN="$(command -v flashdata)"
unset FLASHDATA_API_KEY
Livre acesso, equilíbrio e verificação de preços
set -euo pipefail
export FLASHDATA_BIN="${FLASHDATA_BIN:-$(command -v flashdata)}"
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
: "${FLASHDATA_BIN:?Set the absolute path to the FlashData executable}"
profile=${FLASHDATA_PROFILE:-research}
test -d "$FLASHDATA_STATE_DIR" || { echo 'Existing state directory not found.' >&2; exit 1; }
"$FLASHDATA_BIN" --version
jq --version
"$FLASHDATA_BIN" auth status --profile "$profile" \
  --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive |
  jq -e '.ok and .data.accessVerified
    and (.data.identity.identity.recurringAllowed == true)
    and (.data.identity.permittedSources | index("google_search") != null)'
"$FLASHDATA_BIN" account balance --profile "$profile" \
  --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive
"$FLASHDATA_BIN" account pricing --source google_search --request-count 1 \
  --profile "$profile" --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive

CLI Salvar uma tarefa por ocorrência

Crie a pasta de tarefas abaixo e salve request.json e run-research.sh dentro dela. Mantenha esta pasta separada do diretório de estado credencial existente. Uma data representa uma consulta Google; num define o número de resultados. Dê a um fluxo de trabalho diferente seu próprio prefixo run-ID antes de sua primeira execução.

Crie a pasta de tarefas
mkdir -p flashdata-research
cd flashdata-research
request.json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}

Salve run-research.sh

Crie run-research.sh ao lado de request.json na pasta de tarefas. Copie o script completo abaixo e salve-o antes de executar ou agendar a tarefa.

O script congela a entrada para cada data e mantém um recibo, resultado e arquivo de erro para cada tentativa. Apenas tentativas bem sucedidas publicam result.json e... receipt.json No nível superior da pasta datada. --recurring Verifica o acesso do proprietário, não cria uma programação.

run-research.sh
#!/usr/bin/env bash
set -euo pipefail
umask 077
slot=${1:?Pass the scheduled date as YYYY-MM-DD}
[[ "$slot" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]] || exit 2
: "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
: "${FLASHDATA_BIN:?Set the absolute path to the FlashData executable}"
profile=${FLASHDATA_PROFILE:-research}
cd -- "$(dirname -- "$0")"
dir="runs/$slot"
mkdir -p "$dir"
if [[ -e "$dir/request.json" ]]; then
  cmp -s request.json "$dir/request.json" || {
    echo 'Input changed for this slot. Inspect its saved run.' >&2; exit 1;
  }
else
  (set -C; cat request.json > "$dir/request.json")
fi
attempt=$(mktemp -d "$dir/attempt.XXXXXX")
if ! "$FLASHDATA_BIN" query --input "$dir/request.json" --recurring \
  --run-id "scheduled-research:$slot:Asia-Shanghai" \
  --profile "$profile" --state-dir "$FLASHDATA_STATE_DIR" \
  --output "$attempt/result.json" --timeout 2m --json --non-interactive \
  > "$attempt/receipt.json" 2> "$attempt/error.json"; then
  cat "$attempt/error.json" >&2
  exit 1
fi
jq -e '.ok == true' "$attempt/receipt.json" >/dev/null
jq -e '.source == "google_search" and .status == "done"
  and (.results[0].organic | type == "array")' "$attempt/result.json" >/dev/null
# Publish a stable path only after the query and its receipt both succeed.
cp "$attempt/result.json" "$dir/result.next.json"
mv "$dir/result.next.json" "$dir/result.json"
cp "$attempt/receipt.json" "$dir/receipt.next.json"
mv "$dir/receipt.next.json" "$dir/receipt.json"
jq '{runId, cached, usage}' "$attempt/receipt.json"
printf 'Saved result: %s\n' "$dir/result.json"

Corra uma vez, então teste uma nova tentativa de processo

Corra da pasta de tarefas. O primeiro comando envia uma busca. O segundo usa a mesma conta, entrada, perfil e estado para ler o resultado salvo depois de verificar que o acesso ainda é válido.

Uma ocorrência, dois processos começam
# Use the date of the intended occurrence, including on retries.
bash run-research.sh 2026-11-04

# Same account, input, profile and state: reuse the completed run.
bash run-research.sh 2026-11-04

Confirme que o resultado foi reutilizado

O segundo recibo deve mostrar cached: true. Seu uso pertence à busca original. Uma matriz orgânica vazia ainda pode ser um resultado bem sucedido.

Inspecione o resultado salvo e o recibo
jq '{ok, runId, cached, usage}' runs/2026-11-04/receipt.json
jq '.results[0].organic | map({title, link})' runs/2026-11-04/result.json
Segundo recibo · Excerto
{
  "schemaVersion": 1,
  "ok": true,
  "runId": "scheduled-research:2026-11-04:Asia-Shanghai",
  "cached": true
}

Mantenha os arquivos entre as corridas

ArquivoUse
runs/DATE/request.jsonEntrada exata para essa ocorrência, mudando-a faz o corredor parar.
runs/DATE/result.json + receipt.jsonA última tentativa bem sucedida. Só os consuma depois que o comando sair com sucesso.
runs/DATE/attempt.*/Resultado, recibo e erro para cada tentativa, incluindo falhas.
FLASHDATA_STATE_DIRCredenciais protegidos e CLI executam registros. Mantenha o mesmo perfil e use OS.

MCP: persistir na ocorrência e no trabalho ID

Use este corpo de tarefas com um hospedeiro que mantenha o estado de tarefa durável e permita uma execução ativa por ocorrência. Salve o trabalho de volta ID imediatamente; após um reinício, leia o trabalho aceito em vez de procurar novamente.

MCP tarefa recorrente · salvar como recurring-task.txt
Use a ocorrência original do programador ID e horário agendado.
Reutilize a conexão FlashData MCP existente e salve o registro de ocorrência.
1. Se esta ocorrência estiver completa, devolva seu resultado salvo sem procurar.
2. Se ele tem um trabalho ID, ligue para get_job com esse job_id para ler o trabalho existente.
3. Se uma submissão começou mas não tem resultado ou trabalho ID, pare para revisão.
4. Para uma nova ocorrência, verifique get_balance e get_pricing para um google_search.
   Continue apenas dentro do orçamento aprovado por tarefa e equilíbrio disponível.
5. Persista em submission_started antes de chamar google_search uma vez com:
   {"query":"battery recycling pilot plant announcements","num":5,"gl":"us","hl":"en","tbs":"qdr:w","mode":"async"}
6. Salve o trabalho de volta ID imediatamente. Leia com get_job até o terminal, pare com a falha.
   Mantenha o ID em intervalos e pare de esperar no prazo do anfitrião.
7. Salve o resultado, fonte URLs e uso, então marque esta ocorrência completa.
Em 401, 403, 402, 429 ou um resultado desconhecido, pare e relate o registro salvo.
Honrar Retry-After. Não crie acesso de substituição ou outra consulta paga.
Mantenha o relatório local, use um destino de entrega somente se configurado separadamente.

O que o hospedeiro deve persistir

Um alerta sozinho não pode evitar duplicatas. Chamadas MCP não herdam proteção CLI run-ID. Seu anfitrião deve persistir na ocorrência original, estado de submissão e trabalho ID. Se não puder, use o corredor CLI para a etapa de dados. Este registro de exemplo pertence ao seu anfitrião, não é um pedido MCP.

Registro de hospedeiras... ilustrativo
{
  "occurrence": "research:2026-11-04:Asia-Shanghai",
  "state": "accepted",
  "job_id": "<returned job ID>",
  "output": null
}

Agende a tarefa testada

O exemplo abaixo usa OpenClaw em 09:00 Asia/Shanghai. Crie o trabalho desativado, execute o trabalho salvo manualmente, inspecione sua saída, e então habilite-o. Para outro programador, siga a mesma sequência com seus controles de teste.

AjustandoUse
ConcurrênciaUma execução ativa para esse fluxo de trabalho, com estado durável.
Tempo de corridaUse o mesmo usuário OS e caminhos absolutos para CLI, pasta de tarefas e estado credencial. Exportações de terminais não são automaticamente herdadas por um Gateway.
RepetiçõesMantenha a ocorrência original e data marcada, inclusive depois da meia-noite. Um teste manual usa sua data de invocação em Asia/Shanghai.
Ocorrências perdidasEscolha se deve pular ou pôr o papo em dia. Uma busca hoje devolve dados atuais, mesmo que marcados com a data de ontem.
EntregaSalve a região primeiro. Configure uma política de destino e notificação antes de enviar relatórios.

CLI corpo de tarefas para um hospedeiro de agentes

Substitua os placeholders do perfil e do caminho, então salve recurring-task.txt na pasta de tarefas. Use este corpo para execução CLI, ou o corpo MCP acima para execução MCP. Um programador OS direto pode executar o script Bash com essas variáveis de ambiente sem um modelo.

recurring-task.txt
Execute a tarefa de pesquisa FlashData aprovada sob o usuário OS que salvou a chave.
Corredor: <caminho absoluto para run-research.sh>
Defina estas variáveis de ambiente para o processo de corredor:
FLASHDATA_BIN* Caminho absoluto para flashdata>
FLASHDATA_PROFILE: <Nome do perfil existente>
FLASHDATA_STATE_DIR: <Relatório de estado absoluto existente>
Mantenha FLASHDATA_API_KEY desligado para reutilizar a credencial salva.
Use a data agendada original em Asia/Shanghai, como YYYY-MM-DD.
Para uma execução manual, guarde sua data de invocação antes da execução.
Correr: bash "<absolute path to run-research.sh>" YYYY-MM-DD
Mantenha essa data em repetições, mesmo depois da meia-noite. Permita uma execução ativa.
Mantenha o mesmo perfil, request.json e diretório de estado.
Apenas leia o result.json datado após as saídas de comando com sucesso.
Relate links de origem, execute ID e use. Mantenha as saídas locais.
No erro, pare e relate o erro salvo. Não comece a substituir o trabalho ou criar um novo acesso.

1. Criar um trabalho OpenClaw deficiente

Use uma Gateway e um agente existente que passou na verificação de acesso. Os comandos abaixo usam OpenClaw 2026.10.10; atualizem clientes mais velhos se --wait não estiver disponível. Na pasta que contém recurring-task.txt, defina OPENCLAW_AGENT_ID para ID daquele agente.

O comando salva openclaw-job.json sem sobrescrever um arquivo existente. Leia e coloque OPENCLAW_JOB_ID para o trabalho devolvido ID. Se a criação perder sua resposta, inspecione a lista de automação. --all --json Antes de criar outro trabalho. --no-deliver Desativa o anúncio automático, o corpo de tarefas também mantém relatórios locais.

Bash · cria um trabalho deficiente
: "${OPENCLAW_AGENT_ID:?Set the existing OpenClaw agent ID}"
test -s recurring-task.txt || exit 1
# Keep the receipt. An existing file blocks accidental recreation.
(
  set -o noclobber
  openclaw automations add --name flashdata-daily-research \
    --agent "$OPENCLAW_AGENT_ID" \
    --cron "0 9 * * *" --tz Asia/Shanghai --exact \
    --session isolated --disabled --no-deliver \
    --message "$(cat recurring-task.txt)" --json > openclaw-job.json
)

2. Teste o trabalho salvo antes de permitir

Faça o trabalho salvo uma vez enquanto sua agenda fica desativada. Orçamento para uma pesquisa de teste e custos do modelo, uma ocorrência completa de CLI pode reutilizar seu resultado. Este comando espera até 10 minutos.

Espere completionStatus: sucesso, então verifique o resultado salvo, links de origem e uso. Por... CLI, leia runs/DATE/result.json e... receipt.json- Por quê? MCP, leia a ocorrência salva do anfitrião e o resultado do trabalho. enqueued: true Sozinho significa aceito, não completado.

Corra uma vez, guarde o recibo do teste
: "${OPENCLAW_JOB_ID:?Set the saved OpenClaw job ID}"
# Run the saved job once; its schedule stays disabled.
(
  set -o noclobber
  openclaw automations run "$OPENCLAW_JOB_ID" \
    --wait --wait-timeout 10m --json > openclaw-test-run.json
)
Leia o recibo do teste
cat openclaw-test-run.json

Inspecione um teste cronometrado ou falhou

Um intervalo para esperar, não a tarefa do Gateway. Leia o histórico recente se o recibo estiver vazio. Defina OPENCLAW_RUN_ID para OpenClaw runId a partir do recibo ou histórico, em seguida, inspecione essa execução. Não repita o comando para verificar o progresso.

Esta é a execução do programador ID, não a execução recorrente FlashData ID ou um trabalho MCP ID. Se o agente não conseguiu entrar ou executar a tarefa de dados, mantenha o cronograma desativado e repare esse passo primeiro.

Inspecione a mesma execução
: "${OPENCLAW_JOB_ID:?Set the saved OpenClaw job ID}"
cat openclaw-test-run.json
openclaw automations runs "$OPENCLAW_JOB_ID" --limit 5 --json

# Set this from the receipt or history; this is OpenClaw's run ID.
: "${OPENCLAW_RUN_ID:?Set the OpenClaw test run ID}"
openclaw automations runs "$OPENCLAW_JOB_ID" \
  --run-id "$OPENCLAW_RUN_ID" --json

3. Activar depois de verificar a saída

Revise o agente salvo, o horário, o fuso horário e o teste completo. Ativar somente após a saída estar correta e o custo recorrente ser aprovado. Desativar depois para futuras invocações, não cancela uma consulta já submetida.

Revise o trabalho salvo e teste histórico
: "${OPENCLAW_JOB_ID:?Set the saved OpenClaw job ID}"
openclaw automations show "$OPENCLAW_JOB_ID" --json
openclaw automations runs "$OPENCLAW_JOB_ID" --limit 5 --json
Activar a programação diária
openclaw automations enable "$OPENCLAW_JOB_ID"
Pausa para o futuro quando necessário
openclaw automations disable "$OPENCLAW_JOB_ID"

Definir o custo e as regras de falha

SituaçãoAção
Planejamento de custosPreço por consulta × ocorrências planejadas. Adicione custos de modelo e host separadamente, contagem de resultados não é contagem de consultas.
Saldo da conta compartilhadaForçar seu orçamento no agendador ou anfitrião. Esses exemplos não impõem um limite de gastos em chave separada.
401 / 403 / 402Pausar futuras mensagens. Conserte credenciais, permissão ou equilíbrio, retome com a ocorrência original e o estado salvo.
429Respeito Retry-After. Inspecione a corrida CLI ou a ocorrência MCP antes de decidir se uma nova submissão é segura.
Resultado desconhecido da submissãoMantenha o estado salvo e pare. Recupere um trabalho conhecido ID; não crie uma nova corrida ID para contornar a incerteza.

Pare o horário e revogue o acesso separadamente

  1. Pause o agendador para parar as futuras invocações.
  2. Revogue a conexão do agente, aplicativo OAuth ou chave API no console. A revogação bloqueia o novo uso autenticado, não apaga arquivos exportados.
  3. Repita a verificação de acesso livre de um novo processo. Deve falhar após a revogação. CLI logout só remove credenciais locais, não revoga o acesso remoto.