浏览文档
指南
复用已批准访问,每个计划时段执行一次搜索,并在恢复时避免意外重复提交。
本页内容
选择任务运行方式
智能体宿主或操作系统调度器负责定时,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_KEYset -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在新的调度会话执行以下检查。由宿主复用并刷新已批准的 OAuth 凭据,每次执行时应能连接 FlashData,而无需交互式登录。
复用此调度环境中已有的 FlashData MCP 连接。
以 {} 调用 get_balance。
以 {"source":"google_search","request_count":1} 调用 get_pricing。
报告余额和预估价格,不执行搜索或创建新访问。CLI:每个计划时段保存一个任务
创建下方任务目录,将 request.json 和 run-research.sh 保存在其中。此目录与已有凭据状态目录分开。每个日期代表一次 Google 查询;num 设置结果数。不同工作流程在首次执行前应设置独立的运行 ID 前缀。
mkdir -p flashdata-research
cd flashdata-research{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
}
}保存 run-research.sh
在任务目录中、request.json 旁创建 run-research.sh。复制下方完整脚本并保存,再运行或调度任务。
脚本固定每个日期的输入,为每次尝试保留回执、结果和错误文件。只有成功尝试才会在日期目录顶层发布 result.json 和 receipt.json。--recurring 检查所有者访问,不会创建调度。
#!/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;重启后读取已接纳任务,而不是再次搜索。
使用调度器原计划时段 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 脚本,无需模型。
以保存密钥的系统用户执行已批准的 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 关闭自动通知,任务正文也要求报告保存在本地。
: "${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" --json3. 检查输出后启用
检查已保存的智能体、调度、时区及已完成测试。输出正确且周期费用获准后再启用。之后停用会停止后续调用,不会取消已提交查询。
: "${OPENCLAW_JOB_ID:?Set the saved OpenClaw job ID}"
openclaw automations show "$OPENCLAW_JOB_ID" --json
openclaw automations runs "$OPENCLAW_JOB_ID" --limit 5 --jsonopenclaw automations enable "$OPENCLAW_JOB_ID"openclaw automations disable "$OPENCLAW_JOB_ID"设置费用及失败处理规则
| 情况 | 处理 |
|---|---|
| 费用规划 | 每次查询价格 × 计划时段数。模型及宿主费用另计;结果条数不是查询次数。 |
| 共享账户余额 | 在调度器或宿主中执行预算限制。本例不对密钥设置独立消费上限。 |
| 401 / 403 / 402 | 暂停后续提交,修复凭据、权限或余额,使用原时段及保存状态恢复。 |
| 429 | 遵循 Retry-After。检查 CLI 运行或 MCP 时段记录,再判断是否可再次提交。 |
| 提交结果未知 | 保留状态并停止,恢复已有任务 ID,不创建新运行 ID 绕过不确定状态。 |
分别停止调度及撤销访问
- 暂停调度器以停止后续调用。
- 在控制台撤销智能体连接、OAuth 应用或 API 密钥。撤销会阻止新的认证使用,不会删除已导出文件。
- 从新进程重复免费访问检查,撤销后应失败。CLI auth logout 只删除本地凭据,不会撤销远程访问。