XXL-JOB AI Executor: Schedule AI Tasks Like Regular Cron Jobs

Introduction

Readers reported issues when calling LLM APIs directly in scheduled tasks: hard-coded API keys, no retry mechanism, and no visibility into execution status. Building a dedicated AI task scheduler felt too heavy. XXL-JOB v3.1.0 introduced the AI Executor , which packages AI calls as standard Bean-mode handlers, integrating with Spring AI, Ollama, Dify, and later OpenClaw (v3.4.0). This means AI tasks share the same scheduling, retry, alerting, and logging infrastructure as ordinary jobs.

What Is the XXL-JOB AI Executor?

The core idea: AI Executor = built-in AI task Handlers + unified scheduling management . The scheduling center only cares about when to trigger, which Handler, and what parameters; the AI Executor handles how to call the AI backend. This returns to the essence of task scheduling: execute the right logic at the right time in the right way.

Architecture

The scheduling center is agnostic to task type. It triggers Handlers with parameters; the AI Executor encapsulates the AI invocation details.

Underlying Principles

3.1 Bean-Mode Handler

XXL-JOB supports Bean mode (recommended) and GLUE mode. Bean mode uses @XxlJob("handlerName") on a Spring bean. All AI Handlers ( ollamaJobHandler, difyWorkflowJobHandler, openClawJobHandler) are standard Bean-mode Handlers.

3.2 ollamaJobHandler

Wraps calls to a local Ollama instance. Core logic (simplified):

@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. Log result
    XxlJobHelper.log("AI task completed, result: {}", result);
    XxlJobHelper.handleSuccess(result);
}

Key design: prompt and input come from the job parameters dynamically, not hard-coded. One executor can run different AI tasks by changing parameters in the admin console.

3.3 difyWorkflowJobHandler

Triggers Dify workflows. Similar structure but calls Dify's workflow API:

@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 config optimization: Early versions required baseUrl and apiKey in executor-side files. Later versions read them from job parameters, enabling multi-Dify-app integration without code changes.

Hands-On Implementation

4.1 Prerequisites

Assume XXL-JOB admin and Ollama are already deployed.

4.2 Configure AI Executor in Admin

Insert executor record (AppName must be xxl-job-executor-sample-ai because the sample code registers with that name):

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

4.3 Add Dependency in Spring Boot Project

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

Configure executor:

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 Console

Executor: AI Executor 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字。"
}

prompt

and input are passed dynamically per execution, so the same Handler serves different analyses.

4.5 View Execution Results

In scheduling logs you see status, duration, and the AI output (logged via XxlJobHelper.log). If the AI call fails (e.g., Ollama down), XXL-JOB's built-in retry mechanism retries automatically — no custom retry code needed.

Pros and Cons

Pros

Unified scheduling management — AI and regular jobs in one console; low ops overhead.

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

Complete execution logs — Every run's result, latency, return value recorded for traceability.

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

Multiple AI backends — Ollama, Dify, OpenClaw, Spring AI supported.

Zero extra infrastructure — If you already use XXL-JOB, just add the AI executor.

Cons

Separate executor deployment required — The xxl-job-executor-sample-ai must be deployed; regular executors cannot run AI tasks.

Job parameter length limit — Long prompts/inputs may hit database field limits.

No streaming output — Execution is synchronous; long text generation blocks the thread.

Limited flexibility of built-in Handlers — General-purpose wrappers; complex orchestration (multi-turn, tool use) needs custom Handlers.

Applicable Scenarios

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

Scheduled AI content generation — ✅✅✅ Strongly recommended : Generate daily/weekly reports, business insights.

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

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

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

Complex AI orchestration tasks — ⚠️ Evaluate : Built-in Handlers limited; custom Handler needed.

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

Conclusion

XXL-JOB's AI integration is not merely adding a chat box to cron; it makes AI invocation a standard execution logic within the scheduler. AI tasks share scheduling, retry, and logging with ordinary tasks. 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 backend support expanded (Ollama, Dify, OpenClaw, Spring AI) and Dify config moved to job parameters for multi-app support — evidence of active refinement.

Limitations remain: suited for "scheduled trigger, synchronous execution, result recording" patterns. For complex multi-turn dialogues, tool use, or streaming, custom Handlers are still required. But for "analyze yesterday's data every morning at 6 AM", XXL-JOB's AI Executor is likely the most hassle-free choice.

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