XXL-JOB Adds AI Support: Schedule Local LLMs, Dify Workflows, and OpenClaw via Spring AI

XXL-JOB is a distributed task scheduling platform open-sourced by Xu Xueli in 2015. It consists of a scheduling center (web console for task creation, Cron management, logging) and executors (worker processes deployed alongside business systems). The platform supports Java Bean tasks, GLUE scripts (Shell, Python, NodeJS), parent-child task chaining, routing strategies, failover, and timeout/retry mechanisms.

AI Integration Approach

Starting with version 3.1.0 (2025-04-30), XXL-JOB added an AI executor sample project ( xxl-job-executor-sample-springboot-ai, AppName xxl-job-executor-sample-ai) built on JDK 17 and Spring Boot 3. The integration does not introduce a separate AI scheduling center; instead, three Spring AI-based JobHandlers are provided as regular Bean tasks: ollamaJobHandler – calls local Ollama models. difyWorkflowJobHandler – triggers Dify workflows. openClawJobHandler (added in 3.4.0, 2026-04-05) – calls OpenAI-compatible endpoints (e.g., OpenClaw on port 18789).

Version progression:

3.1.0: introduced ollamaJobHandler and difyWorkflowJobHandler with model/workflow config in application properties.

3.1.1 (2025-06-23): moved Dify baseUrl and apiKey into task parameters, enabling one executor to target multiple workflows.

3.2.0 (2025-08-24): made Ollama model name a task parameter, allowing model changes without restart.

3.4.0 (2026-04-05): added openClawJobHandler.

Scheduling Flow with AI

The scheduling process remains unchanged: trigger at Cron time, select executor via routing, execute, log, retry on failure. The executor internally invokes the model or workflow. Task parameters are JSON with fields: input (required) – the actual prompt/content sent to the model. prompt (optional) – system prompt; defaults: Ollama uses "You are a software engineer", OpenClaw uses "You are a travel assistant". model (Ollama only) – model name existing in local Ollama. inputs, baseUrl, apiKey, user (Dify only) – workflow input variables and credentials.

Model responses are written to the task's rolling schedule log; no separate UI page is created.

Example 1: Daily Slow SQL Analysis (Ollama)

JobHandler: ollamaJobHandler. Cron: 0 0 9 * * ? (9 AM weekdays). Task parameter JSON:

{
  "input": "Below are last night's three slowest SQLs, explain possible causes and which tables to check in three sentences: SELECT ...",
  "prompt": "You are a software engineer, good at solving technical problems. Keep answer short, no pleasantries.",
  "model": "qwen3.5:0.8b"
}

Empty input or JSON parse failure marks task as failed, enabling retry policies.

Example 2: Fixed Process via Dify Workflow

JobHandler: difyWorkflowJobHandler. Task parameter JSON:

{
  "inputs": {
    "input": "Organize this on-call record into three parts: what happened, who was affected, what to follow up today."
  },
  "user": "xxl-job",
  "baseUrl": "http://localhost/v1",
  "apiKey": "app-your-key"
}

The inputs field names must match the Dify workflow's start node variables. Missing baseUrl or apiKey causes task failure with log details.

Example 3: Travel Planning with OpenClaw

JobHandler: openClawJobHandler. Task parameter JSON:

{
  "input": "Next Friday from Hangzhou to Suzhou, one-day round trip, plan a relaxed itinerary.",
  "prompt": "You are a travel assistant, skilled at travel planning. List itinerary in chronological order."
}

Omitting prompt falls back to the default travel assistant persona.

Custom Business JobHandler

For scenarios requiring database queries before prompt construction, developers can add a custom method in their own executor. Example DailyDigestJob uses OllamaChatModel via Spring AI's ChatClient:

@Component
public class DailyDigestJob {
    @Resource
    private OllamaChatModel ollamaChatModel;

    @XxlJob("dailyDigestJob")
    public void dailyDigestJob() {
        String param = XxlJobHelper.getJobParam();
        if (param == null || param.isBlank()) {
            XxlJobHelper.log("任务参数为空");
            XxlJobHelper.handleFail();
            return;
        }
        ChatClient client = ChatClient.builder(ollamaChatModel)
                .defaultOptions(OllamaChatOptions.builder().model("qwen2.5:1.5b").build())
                .build();
        String answer = client
                .prompt("You are an ops assistant, state in three sentences whether manual intervention is needed.")
                .user(param)
                .call()
                .content();
        XxlJobHelper.log(answer);
    }
}

The model output appears directly in the schedule log, so operators can review the AI-generated summary in the XXL-JOB console without accessing the model's own interface.