跳转到正文
中文
获取 API 密钥
浏览文档

指南

运行智能体定时任务

复用已批准访问,每个计划时段执行一次搜索,并在恢复时避免意外重复提交。

本页内容

选择任务运行方式

智能体宿主或操作系统调度器负责定时,FlashData 提供数据。选择一种执行方式,并在实际无人值守环境中验证。

方式适用场景需要保留的状态
CLI具有终端访问的智能体、cron 或定时脚本。CLI 配置档、状态目录和原运行 ID。
MCP已连接 FlashData 服务器的智能体宿主。宿主凭据、计划时段记录、任务 ID 及结果。

在调度环境检查访问

复用具有 google_search 权限的已有所有者连接。周期使用前先认领临时访问。使用新的调度进程或会话验证,不仅在交互环境中验证。

使用 Bash 和 jq(Windows 使用 Git Bash),并以保存密钥的系统用户执行。在下方设置已有配置档名及状态目录绝对路径。在同一终端执行两个代码块;运行脚本会复用这些设置。

访问检查必须输出 true。首次搜索前比较 availableCredits 与 estimatedCredits。以下检查不会提交查询。

设置已保存的连接
# 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
免费访问、余额和价格检查
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:每个计划时段保存一个任务

创建下方任务目录,将 request.json 和 run-research.sh 保存在其中。此目录与已有凭据状态目录分开。每个日期代表一次 Google 查询;num 设置结果数。不同工作流程在首次执行前应设置独立的运行 ID 前缀。

创建任务目录
mkdir -p flashdata-research
cd flashdata-research
request.json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}

保存 run-research.sh

在任务目录中、request.json 旁创建 run-research.sh。复制下方完整脚本并保存,再运行或调度任务。

脚本固定每个日期的输入,为每次尝试保留回执、结果和错误文件。只有成功尝试才会在日期目录顶层发布 result.json 和 receipt.json。--recurring 检查所有者访问,不会创建调度。

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"

运行一次,再由新进程测试重试

在任务目录中运行。第一条命令提交搜索;第二条命令使用相同账户、输入、配置档和状态,验证访问仍有效后读取保存结果。

同一时段 · 两次进程启动
# 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

确认结果被复用

第二次回执应显示 cached: true,其中用量属于原搜索。organic 为空数组也可能是成功结果。

检查保存结果和回执
jq '{ok, runId, cached, usage}' runs/2026-11-04/receipt.json
jq '.results[0].organic | map({title, link})' runs/2026-11-04/result.json
第二次回执 · 节选
{
  "schemaVersion": 1,
  "ok": true,
  "runId": "scheduled-research:2026-11-04:Asia-Shanghai",
  "cached": true
}

在运行之间保留文件

文件用途
runs/DATE/request.json该时段的准确输入;修改后脚本会停止。
runs/DATE/result.json + receipt.json最后一次成功尝试。仅在本次命令成功退出后读取。
runs/DATE/attempt.*/每次尝试的结果、回执和错误,包括失败尝试。
FLASHDATA_STATE_DIR受保护凭据及 CLI 运行记录。保留相同配置档和系统用户。

MCP:保存计划时段及任务 ID

将此任务正文用于能持久保存任务状态、且每个时段仅允许一个活动执行的宿主。立即保存返回的任务 ID;重启后读取已接纳任务,而不是再次搜索。

MCP 周期任务 · 保存为 recurring-task.txt
使用调度器原计划时段 ID 和计划时间。
复用已有 FlashData MCP 连接和保存的时段记录。
1. 此时段已完成时,返回保存结果,不再搜索。
2. 已有任务 ID 时,以该 job_id 调用 get_job,读取已有任务。
3. 若记录表明提交已开始却没有任务 ID,停止并检查,不再次提交。
4. 新时段先检查 get_balance 及 get_pricing,确认在批准预算内。
5. 在记录中保存 submission_started,再调用一次 google_search:
   {"query":"battery recycling pilot plant announcements","num":5,"gl":"us","hl":"en","tbs":"qdr:w","mode":"async"}
6. 立即保存返回的任务 ID,用 get_job 读取至终态;失败时停止。
   达到宿主等待期限时保留任务 ID,之后读取。
7. 保存结果、来源 URL 及用量,然后标记此时段完成。
8. 遇到 401、403、402、429 或未知结果时停止;遵循 Retry-After 并报告保存状态。
不创建替代查询或新访问来绕过问题。
在本地保存报告,只有另行配置交付时才发送到目的地。

宿主必须保存的内容

仅靠提示词不能防止重复。MCP 调用不会继承 CLI 运行 ID 保护。宿主必须保存原计划时段、提交状态及任务 ID。无法提供这些能力时,用 CLI 脚本执行数据步骤。下方示例记录属于宿主,不是 MCP 请求。

宿主记录 · 示意
{
  "occurrence": "research:2026-11-04:Asia-Shanghai",
  "state": "accepted",
  "job_id": "<returned job ID>",
  "output": null
}

调度已验证的任务

下方示例使用 OpenClaw,在 Asia/Shanghai 时区每天 09:00 执行。先创建停用任务,手动运行该已保存任务,检查输出,再启用。其他调度器也按相同顺序使用各自的测试运行功能。

设置建议
并发此工作流程同时只有一个活动执行,并保留持久状态。
运行环境使用相同系统用户,以及 CLI、任务目录和凭据状态的绝对路径。已运行的 Gateway 不会自动继承终端中导出的变量。
重试保留原计划时段及计划日期,包括跨午夜重试。手动测试使用其调用时 Asia/Shanghai 时区的日期。
遗漏时段选择跳过或补跑。今天执行的搜索返回当前数据,即使标注为昨天。
交付先保存在本地,发送报告前配置目的地及通知策略。

智能体宿主的 CLI 任务正文

替换配置档及路径占位符,将 recurring-task.txt 保存在任务目录。CLI 执行使用此正文,MCP 执行使用上方 MCP 正文。操作系统调度器也可直接使用这些环境变量运行 Bash 脚本,无需模型。

recurring-task.txt
以保存密钥的系统用户执行已批准的 FlashData 研究任务。
脚本:<run-research.sh 的绝对路径>
为运行脚本进程设置以下环境变量:
FLASHDATA_BIN:<flashdata 的绝对路径>
FLASHDATA_PROFILE:<已有配置档名>
FLASHDATA_STATE_DIR:<已有状态目录的绝对路径>
不设置 FLASHDATA_API_KEY,以复用已保存凭据。
使用 Asia/Shanghai 时区原计划日期,格式 YYYY-MM-DD。
手动运行时,执行前先保存其调用日期。
运行:bash "<run-research.sh 的绝对路径>" YYYY-MM-DD
重试保留该日期,包括跨午夜情况。同时仅允许一个活动执行。
保留相同配置档、request.json 和状态目录。
仅在命令成功退出后读取日期目录中的 result.json。
报告来源链接、运行 ID 和用量,结果保存在本地。
出错时停止并报告保存错误,不创建替代任务或新访问。

1. 创建停用的 OpenClaw 任务

使用正在运行的 Gateway 及已通过访问检查的已有智能体。下方命令使用 OpenClaw 2026.10.10;旧版客户端若不支持 --wait,请先更新。在 recurring-task.txt 所在目录,将 OPENCLAW_AGENT_ID 设为该智能体 ID。

命令保存 openclaw-job.json,不覆盖已有文件。读取后将 OPENCLAW_JOB_ID 设为返回的任务 ID。创建时若未收到响应,先用 automations list --all --json 检查,再决定是否创建新任务。--no-deliver 关闭自动通知,任务正文也要求报告保存在本地。

Bash · 创建停用任务
: "${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. 启用前测试已保存的任务

在调度保持停用时,运行一次已保存任务。预留一次测试搜索及模型费用;匹配已完成时段的 CLI 执行可复用结果。此命令最多等待 10 分钟。

应返回 completionStatus: succeeded,再检查保存结果、来源链接及用量。CLI 读取 runs/DATE/result.json 和 receipt.json;MCP 读取宿主保存的时段及任务结果。仅有 enqueued: true 表示已接纳,不代表已完成。

运行一次 · 保存测试回执
: "${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
)
读取测试回执
cat openclaw-test-run.json

检查超时或失败的测试

超时会停止等待,不会取消 Gateway 任务。回执为空时读取近期历史,将 OPENCLAW_RUN_ID 设为回执或历史中的 OpenClaw runId,再检查该次执行。不要重复运行命令来检查进度。

这是调度器执行 ID,不是 FlashData 周期运行 ID 或 MCP 数据任务 ID。若智能体无法登录或执行数据任务,保持调度停用并先修复该步骤。

检查同一次执行
: "${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. 检查输出后启用

检查已保存的智能体、调度、时区及已完成测试。输出正确且周期费用获准后再启用。之后停用会停止后续调用,不会取消已提交查询。

检查已保存任务及测试历史
: "${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
启用每日调度
openclaw automations enable "$OPENCLAW_JOB_ID"
需要时暂停后续运行
openclaw automations disable "$OPENCLAW_JOB_ID"

设置费用及失败处理规则

情况处理
费用规划每次查询价格 × 计划时段数。模型及宿主费用另计;结果条数不是查询次数。
共享账户余额在调度器或宿主中执行预算限制。本例不对密钥设置独立消费上限。
401 / 403 / 402暂停后续提交,修复凭据、权限或余额,使用原时段及保存状态恢复。
429遵循 Retry-After。检查 CLI 运行或 MCP 时段记录,再判断是否可再次提交。
提交结果未知保留状态并停止,恢复已有任务 ID,不创建新运行 ID 绕过不确定状态。

分别停止调度及撤销访问

  1. 暂停调度器以停止后续调用。
  2. 在控制台撤销智能体连接、OAuth 应用或 API 密钥。撤销会阻止新的认证使用,不会删除已导出文件。
  3. 从新进程重复免费访问检查,撤销后应失败。CLI auth logout 只删除本地凭据,不会撤销远程访问。