XXL-JOB AI Executor: Schedule AI Tasks Like Cron Jobs with Unified Retry & Logging

Introduction

Readers reported issues when calling LLM APIs directly from scheduled jobs: hard-coded API keys, no retry mechanism, no visibility into success or failure. Building a dedicated AI task scheduler felt too heavy. The answer: XXL-JOB's AI executor, introduced in v3.1.0 and extended in v3.4.0 with OpenClaw integration.

Key point: You don't need a separate scheduling system for AI tasks. AI tasks and ordinary tasks share the same scheduling, retry, alerting, and logging infrastructure.

What Is the XXL-JOB AI Executor?

Some may ask whether a cron framework should run AI jobs. The article argues it's a return to the core mission of scheduling: execute the right logic at the right time in the right way. Previously, a daily business-insight job required custom code for model API calls, retry handling, logging, and alerting — all things XXL-JOB already provides. The AI executor simply swaps the execution logic from "query database" to "call LLM".

One-sentence summary: AI Executor = built-in AI task Handlers + unified scheduling management.

Architecture

Key understanding: The scheduling center doesn't care whether a task is AI or ordinary. It only manages when to trigger, which Handler to invoke, and what parameters to pass. The AI executor handles how to call the AI backend.

Underlying Principles

3.1 Bean-Mode Handler

XXL-JOB supports two handler modes: Bean mode (recommended) and GLUE mode . Bean mode uses a Java class annotated with @XxlJob("handlerName"); XXL-JOB auto-registers it as a schedulable handler. All AI executors ( ollamaJobHandler, difyWorkflowJobHandler, openClawJobHandler) are standard Bean-mode handlers.

3.2 ollamaJobHandler

Standardized wrapper for calling local models via Ollama. Core logic (simplified):

// Simplified logic
@XxlJob("ollamaJobHandler")
public void ollamaJobHandler() throws Exception {
    // 1. Parse prompt and input from job parameters
    String param = XxlJobHelper.getJobParam();
    JSONObject json = JSON.parseObject(param);
    String input = json.getString("input");
    String prompt = json.getString("prompt");

    // 2. Call Ollama API
    String result = ollamaClient.chat(prompt, input);

    // 3. Record execution result
    XxlJobHelper.log("AI任务执行完成，结果：{}", result);
    XxlJobHelper.handleSuccess(result);
}

Key design: prompt and input are read dynamically from the job parameters , not hard-coded in the executor. This allows a single executor to run different AI tasks by changing only the scheduler-side parameters.

3.3 difyWorkflowJobHandler

Triggers Dify workflows. Logic is similar but calls Dify's workflow engine:

@XxlJob("difyWorkflowJobHandler")
public void difyWorkflowJobHandler() throws Exception {
    String param = XxlJobHelper.getJobParam();
    JSONObject json = JSON.parseObject(param);
    String inputs = json.getString("inputs");
    String user = json.getString("user");

    // Call Dify workflow API
    String result = difyClient.runWorkflow(inputs, user);

    XxlJobHelper.handleSuccess(result);
}

Dify configuration improvement: Early versions required baseUrl and apiKey in executor-side config files. Later versions moved these to the scheduler's job parameters , enabling multi-Dify-app integration and improving developer efficiency.

Hands-On Implementation

4.1 Prerequisites

Assume XXL-JOB admin and Ollama service are already deployed. Refer to official docs if not.

4.2 Configure AI Executor in Admin

Create executor via SQL (AppName must be xxl-job-executor-sample-ai because the sample code registers with this name):

INSERT INTO `xxl_job_group`(`app_name`, `title`, `address_type`, `address_list`, `update_time`)
VALUES ('xxl-job-executor-sample-ai', 'AI执行器Sample', 0, NULL, now());

4.3 Add AI Executor to Spring Boot Project

Dependency (version 3.4.0):

<dependency>
    <groupId>com.xuxueli</groupId>
    <artifactId>xxl-job-core</artifactId>
    <version>3.4.0</version>
</dependency>

Executor configuration (YAML):

xxl:
  job:
    admin:
      addresses: http://localhost:8080/xxl-job-admin
    executor:
      appname: xxl-job-executor-sample-ai
      port: 9999

4.4 Create AI Task in Admin

Executor: AI执行器Sample

Description: Daily business insight generation

Cron: 0 0 6 * * ? (6 AM daily)

Run Mode: BEAN

JobHandler: ollamaJobHandler Job Parameters:

{
  "input": "请基于昨天的销售数据生成一段业务洞察。数据：华东区销售额120万，环比下降12%；华南区销售额98万，环比上升8%。",
  "prompt": "你是一个数据分析师，请用简洁的语言生成业务洞察，不超过100字。"
}

Note: prompt and input are passed dynamically per execution, so the same handler can run different AI analyses.

4.5 View Execution Results

In the admin's scheduling logs you can see:

Execution status (success/failure)

Execution time

AI response (recorded via XxlJobHelper.log)

Failure retry: If the AI call fails (e.g., Ollama unavailable), XXL-JOB's built-in retry mechanism retries automatically — no custom retry code needed.

Pros and Cons

Pros

Unified scheduling management — AI and ordinary tasks in one admin console; low ops overhead.

Built-in failure retry — Handles model service downtime, timeouts automatically.

Complete execution logs — Every run's result, duration, and return value stored for traceability.

Dynamic configuration — prompt, input, Dify baseUrl, apiKey all from job parameters; no code changes to adjust.

Multi-AI-backend support — Ollama, Dify, OpenClaw, Spring AI, etc.

Zero extra infrastructure — If you already use XXL-JOB, AI capability adds no new systems.

Cons

AI executor must be deployed separately — The xxl-job-executor-sample-ai executor is required; ordinary executors cannot run AI tasks.

Job parameter length limit — prompt and input passed via job parameters; very long content may hit DB field limits.

No streaming output — Execution is synchronous; long text generation may take considerable time.

Limited flexibility of built-in handlers — ollamaJobHandler and difyWorkflowJobHandler are generic wrappers. Complex orchestration (multi-turn dialogue, tool use) still requires custom handlers.

Applicable Scenarios

Scheduled AI data summarization — ✅✅✅ Strongly recommended. Reason: Daily AI summaries with auto-retry on failure.

Scheduled AI content generation — ✅✅✅ Strongly recommended. Reason: Periodic report, weekly summary, business insight generation.

Scheduled Dify workflow trigger — ✅✅✅ Strongly recommended. Reason: difyWorkflowJobHandler works out of the box.

Scheduled AI data cleansing — ✅✅✅ Strongly recommended. Reason: Batch data processing + AI enhancement.

Projects already using XXL-JOB — ✅✅✅ Strongly recommended. Reason: Zero extra infrastructure, direct integration.

Complex AI orchestration tasks — ⚠️ Evaluate. Reason: Built-in handlers limited; custom handler needed.

Tasks requiring streaming output — ❌ Not recommended. Reason: Synchronous execution, no streaming support.

Conclusion

XXL-JOB's AI integration isn't just adding a chat box to cron; it turns AI invocation into a standard execution logic for scheduled tasks. AI tasks and ordinary tasks share the same scheduling, retry, and logging.

You don't need a separate system for "run AI analysis every morning at 6 AM", no custom retry logic, no manual result logging.

From v3.1.0 to v3.4.0, AI capabilities have continuously improved: Ollama, Dify, OpenClaw, Spring AI — backend support grows richer. Dify config moved from executor to job parameters, enabling multi-app integration. These iterations show the team is seriously polishing the feature.

Limitations exist: the executor suits "scheduled trigger, synchronous execution, result recording" standardized AI tasks. For complex multi-turn dialogue, tool use, or streaming, you still need custom handlers.

But if you just want "AI to analyze yesterday's data every morning at 6 AM" — XXL-JOB's AI executor may be the most hassle-free choice. No new systems, no retry code, no log management.

References:

XXL-JOB v3.1.0 Release Notes : https://github.com/xuxueli/xxl-job/releases/tag/3.1.0

XXL-JOB Official Documentation : https://www.xuxueli.com/xxl-job