XXL-JOB AI Executor: Schedule LLM Calls 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 success. Building a dedicated AI task scheduler felt too heavy. The solution: XXL-JOB's AI executor, introduced in v3.1.0 and enhanced in v3.4.0 with OpenClaw integration.

Scheduled tasks + AI = turning "batch runs" into "intelligent runs".

What Is the XXL-JOB AI Executor?

The core idea: wrap AI calls as standard Bean-mode handlers so AI tasks share the same scheduling, retry, and logging infrastructure as ordinary jobs. The scheduler only cares about when to trigger, which handler, and what parameters; the AI executor handles how to call the model.

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

Architecture

The scheduling center is agnostic to task type. It triggers handlers with parameters; the AI executor encapsulates the AI invocation logic.

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") for auto-registration. All AI handlers — 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. Log result
    XxlJobHelper.log("AI task completed, result: {}", result);
    XxlJobHelper.handleSuccess(result);
}

Key design: prompt and input are read dynamically from the job parameters, not hard-coded. The same executor can run different AI tasks by changing parameters in the scheduling center.

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 configuration improvement: Early versions required baseUrl and apiKey in executor-side config files. Later versions moved these to job parameters, enabling multi-Dify-app integration and boosting 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

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());

AppName must be xxl-job-executor-sample-ai because the sample AI executor registers with this name.

4.3 Add AI Executor to Spring Boot Project

<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 Scheduling Center

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

The prompt and input are passed dynamically per execution , so one handler serves many AI analyses.

4.5 View Execution Results

In the scheduling center's "Scheduling Log" you see:

Execution status (success/failure)

Execution time

AI response (logged 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 regular tasks in one center; low ops overhead.

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

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

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

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

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

Cons

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

Job parameter length limit — prompt and input passed via job parameters; very long content may hit database 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) 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: Generate daily/weekly reports, business insights on a schedule.

Scheduled Dify Workflow Trigger — ✅✅✅ Strongly Recommended. Reason: difyWorkflowJobHandler works out of the box.

Scheduled AI Data Cleansing — ✅✅✅ Strongly Recommended. Reason: Batch data processing enhanced with AI.

Projects Already Using XXL-JOB — ✅✅✅ Strongly Recommended. Reason: Zero extra infrastructure; direct integration.

Tasks Requiring Complex AI Orchestration — ⚠️ 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 is not merely adding a chat box to cron jobs; it makes AI invocation a standard execution logic within the scheduler. AI tasks and ordinary tasks share the same scheduling, retry, and logging stack. 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 has grown: Ollama, Dify, OpenClaw, Spring AI. Dify config moved from executor to job parameters, enabling multi-app integration — evidence the team is seriously refining this feature.

Limitations exist: the executor suits "scheduled trigger, synchronous execution, result recording" standardized AI tasks. For complex multi-turn conversations, tool use, or streaming, you still need custom handlers. But for "analyze yesterday's data every morning at 6 AM", XXL-JOB's AI executor is likely 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