XXL-JOB AI Executor: Run AI Tasks as Scheduled Jobs with Ollama, Dify, OpenClaw

Introduction

Scheduled tasks + AI = turning "batch runs" into "intelligent runs." Users reported pain points when calling LLM APIs directly from cron jobs: hard-coded API keys, no retry logic, no visibility into success or failure. Building a dedicated AI task scheduler felt too heavy. XXL-JOB answers this by introducing an AI Executor starting from v3.1.0, with built-in handlers for Spring AI, Ollama, Dify, and (from v3.4.0) OpenClaw via openClawJobHandler.

This means AI tasks and ordinary tasks share the same scheduling system, retry mechanism, alerting, and logging — no separate infrastructure required.

What Is the XXL-JOB AI Executor?

Some may ask: "XXL-JOB is a cron scheduler; running AI tasks seems off-mission."

Quite the opposite. The core mission of a scheduler is to execute the right logic at the right time in the right way. AI tasks are no different. 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 wraps AI invocations as standard Bean-mode handlers so they reuse the same scheduling, retry, and logging stack.

In one sentence: AI Executor = built-in AI task handlers + unified scheduling management.

Architecture

Key insight: The scheduler center does not 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 Handlers

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

3.2 ollamaJobHandler

This handler standardizes calls to local models via Ollama. Its 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 are read dynamically from the job parameters , not hard-coded in the executor. This allows a single handler to run different AI tasks by changing only the parameters in the admin console.

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 dynamic 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 the AI Executor in Admin

Insert a new executor group (SQL):

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

Maven dependency:

<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 an AI Task in Admin Console

Executor: AI Executor Sample Job 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 in job parameters are passed dynamically per run , so the same handler can execute different AI analyses.

4.5 View Execution Results

After triggering, the scheduling log shows:

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 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 are traceable.

Dynamic configuration — prompt, input, Dify baseUrl, apiKey all come 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 requires separate deployment — The xxl-job-executor-sample-ai executor must be deployed; ordinary executors cannot run AI tasks.

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

No streaming output — Execution is synchronous; long text generation may take noticeable 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 — ✅✅✅ Highly recommended. Daily AI summaries with auto-retry.

Scheduled AI content generation — ✅✅✅ Highly recommended. Generate daily/weekly reports, business insights on a cron.

Scheduled Dify workflow triggering — ✅✅✅ Highly recommended. difyWorkflowJobHandler works out of the box.

Scheduled AI data cleansing — ✅✅✅ Highly recommended. Batch processing enhanced with AI.

Projects already using XXL-JOB — ✅✅✅ Highly recommended. Zero extra infrastructure; direct integration.

Tasks requiring complex AI orchestration — ⚠️ Evaluate. Built-in handlers limited; custom handler needed.

Tasks requiring streaming output — ❌ Not recommended. Synchronous execution only; no streaming support.

Conclusion

What did XXL-JOB actually integrate? Not a chat box inside a cron job, but making AI invocation a standard execution logic of scheduled tasks . 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," nor write retry logic, nor manage execution logs yourself.

From v3.1.0 to v3.4.0, XXL-JOB's AI capabilities have steadily 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 this feature.

Of course, the AI executor has limits. It fits "scheduled trigger, synchronous execution, result recording" standardized AI tasks. For complex multi-turn conversations, tool calling, 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 plumbing.

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