BatchJob Async Job Skill

Use this skill when the user wants to run or manage batch jobs through the BatchJob service.

Required Environment

• - INLINECODE0
• INLINECODE1

All HTTP requests must include:

CODEBLOCK0

API Endpoints

• - INLINECODE2
• INLINECODE3
• INLINECODE4
• INLINECODE5
• INLINECODE6
• INLINECODE7

Automation Policy (Default)

• - Always run in full-auto mode.
• Do not ask user for file_id first.
• Resolve file source from current message/context, then upload automatically when needed.
• Ask follow-up questions only when no readable file source can be obtained.
• Accepted input file formats for upload: jsonl, csv, xlsx, xls (BatchJob normalizes to internal JSONL).
• For jsonl, each line must be either:

- canonical Vertex format (contents + optional generationConfig) - simple prompt format (prompt + optional aspect_ratio / image_urls, where image_urls must be publicly reachable URLs)

• - If user gives only model mode after a file message, treat it as confirmation and continue automatically.

Guardrails (Must Follow)

• - Do not auto-retry by creating a second job unless user explicitly asks.
• Do not auto-rewrite dataset format after a terminal failure unless user explicitly asks.
• Before upload, auto-normalization is allowed only once for known safe mappings (e.g. simple prompt JSONL -> Vertex JSONL).
• Upload failure is terminal for this run: do not continue to precheck/submit when upload fails.
• Never submit when row_count <= 0.
• Do not fetch or parse output_summary_url automatically; only do it when user asks for detailed failure reason.
• After reaching terminal status (completed, failed, partially_failed), stop execution and return summary immediately.

JSONL Compatibility Rule (Important)

BatchJob internal execution expects each JSONL line to be a VertexGeminiImageRequest shape.

• - Canonical line format:

- contents[0].parts[0].text contains prompt text - generationConfig.imageConfig.aspectRatio is optional - generationConfig.responseModalities should include IMAGE and TEXT

• - Non-canonical simple JSONL like {"prompt":"...","aspect_ratio":"1:1"} is acceptable; server will normalize it to Vertex format.
• If JSONL has neither contents nor prompt, stop and ask user to provide valid data.
• Explicitly unsupported (must reject before submit):

- OpenAI Batch style lines containing method + url + body (for example /v1/chat/completions payload). - This schema will fail with Vertex error: at least one contents field is required.

Dataset Output Rule (Important)

When user asks you to generate a template/demo file for BatchJob image tasks:

• - Prefer CSV headers: INLINECODE40
• Or JSONL line format with prompt / aspect_ratio / INLINECODE43
• If image_urls is provided, it must be publicly accessible (http/https).
• Do NOT generate OpenAI batch envelope (custom_id + method + url + body) as final upload file

User Template Response (Important)

When user asks for format/template, return:

1. 1. A short explanation (prompt required, aspect_ratio/image_urls optional, and image_urls must be public URLs).
2. One copyable CSV snippet (default).
3. Optionally one JSONL snippet (simple prompt schema).
4. Local template file paths (if available):

- /home/node/.openclaw/workspace/templates/batchjob-input-template.csv - /home/node/.openclaw/workspace/templates/batchjob-input-template.jsonl - INLINECODE55

Do not output OpenAI batch envelope examples in template replies.

File Source Resolver (Strict Order)

1. 1. Existing file_id:

- if provided, skip upload.

1. 2. Public file_url (http:// or https://):

- download to temp local file, then upload.

1. 3. Explicit local file_path:

- if readable, upload.

1. 4. Inbound attachment local path from channel/runtime context:

- examples: /tmp/..., MEDIA:<path>, /tmp/openclaw-media/.... - if readable, upload.

1. 5. Channel private file token/object (no local path, no public URL):

- if runtime has a channel adapter that can download attachment bytes, use it and upload. - if not available, enter fallback interaction.

Resolver output must be normalized to one of:

• - INLINECODE64
• INLINECODE65 (readable local file)

Execution Flow

1. 1. Confirm model and mode; if missing, use safe defaults (model=google/gemini-2.5-flash-image, mode=fast) and tell user.
2. Resolve file source using resolver above.
3. If resolver gives file_path, upload via POST /v1/batch/files:upload to get file_id.

- For .jsonl, inspect a few non-empty lines first: - if contents exists, upload as-is. - if only prompt/aspect_ratio/image_urls exists, upload as-is (server will normalize). - if method + url + body exists, stop and ask user to switch to BatchJob schema. - if structure is unknown, stop and ask user for valid schema. - Backward compatibility fallback: - if upload fails with unsupported file type for csv/xlsx/xls, convert once to JSONL and retry upload once. - do not retry more than once. - If upload returns validation error (unsupported schema, no valid data rows), stop immediately and return fix guidance.

1. 4. Run precheck with record_count (prefer uploaded file row_count).
2. Submit job with file_id.
3. Poll job status until terminal (completed, failed, partially_failed) with bounded timeout:

- interval: 5 seconds - max polls: 12 (about 60 seconds) - if still non-terminal after max polls: return current status and job_id, then stop.

1. 7. Return concise summary with job_id, status, progress, and output_summary_url.

When user only asks for estimate, stop at precheck and do not submit.

Fallback Interaction (Only When Needed)

Use this when resolver cannot read file bytes from current channel/context:

INLINECODE94
1) 直接发一个可公网下载的 URL
2) 提供本机可读路径（如 /tmp/xxx.csv）
INLINECODE97

If the current channel supports resending as direct attachment path in context, also ask user to resend once.

File Source Playbook

A) Public URL -> Local Temp File

CODEBLOCK1

A2) JSONL Schema Sanity Check

Use this before upload to avoid wrong schema submission.

CODEBLOCK2

B) Feishu/Channel Attachment Path

If message context already includes local attachment path, treat it as FILE_PATH directly.

CODEBLOCK3

If only a channel token/link is provided but no downloadable URL and no local path, try channel adapter download first. If adapter is unavailable, use fallback interaction.

Curl Templates

CODEBLOCK4

CODEBLOCK5

CODEBLOCK6

CODEBLOCK7

CODEBLOCK8