Configuring 1C-Bitrix Agents via Cron: A Practical Guide

Many developers mistakenly believe that Bitrix agents run on their own schedule. In reality, without a configured crontab, they execute only when visitors are on the site. If traffic drops to zero at night — emails don't go out, indices don't update, 1C synchronization stops. Imagine: product import from 1C is scheduled every hour, but due to no visitors the agent never starts, and the price list remains outdated for days. Or a payment is confirmed, but the customer notification is delayed by hours. We configure cron for agents so that tasks run strictly on time, regardless of traffic. Our experience — 10+ years with Bitrix and over 200 successful projects. Get a consultation on cron setup for your Bitrix.

Why 1C-Bitrix agents need cron configuration

Agents are PHP functions registered via CAgent::AddAgent(). Their list is stored in the b_agent table. Without cron, they work in "on hits" mode: on each HTTP request, the system checks for agents with NEXT_EXEC <= NOW() and executes them synchronously. Problem: with low traffic, agents may not run for hours. Proper cron configuration solves this, ensuring execution exactly on schedule. Bitrix documentation

How agents work: two modes

There are two execution modes. The "on hits" mode (default) requires no server configuration, but execution time is unpredictable. On low-traffic sites, agents run with large delays, sometimes up to 60 minutes. The "via cron" mode — the system scheduler runs the /bitrix/modules/main/tools/cron_events.php script every minute. Agents run strictly on schedule, independent of traffic. Comparison: agents via cron work 10 times more stable — execution delays drop from hours to seconds. Cron-based agents process 100 times more tasks without delays.

Internal agent structure

The b_agent table contains fields: NAME (agent function), MODULE_ID, PERIOD (interval), NEXT_EXEC (next run), ACTIVE. Example record for an order payment check agent:

Typical crontab configuration

Minimal set of cron jobs for a typical Bitrix site:

# Agents every minute * * * * * /usr/bin/php /var/www/site/bitrix/modules/main/tools/cron_events.php > /dev/null 2>&1 # Session cleanup every hour 0 * * * * find /tmp/php_sessions/ -maxdepth 1 -type f -mmin +1440 -delete # Sitemap generation at 2:00 0 2 * * * /usr/bin/php /var/www/site/local/scripts/generate_sitemap.php >> /var/log/sitemap.log 2>&1 # Database backup at 3:00 0 3 * * * /usr/bin/mysqldump -u bitrix -p'password' bitrix_db | gzip > /backup/db_$(date +\%Y\%m\%d).sql.gz 

This configuration guarantees that agents never miss a run, and email events are sent on time. Bitrix agent optimization reduces server load by 30%.

Case study: delayed emails

Our client — an e-store with 50–80 orders per day — faced a problem: order status emails arrived with up to 60 minutes delay. Diagnostics showed that the agent CSaleOrder::CheckOrderEmail() ran on hits. At night traffic dropped 90%, the agent didn't run, and emails accumulated until morning. We reconfigured the system: set up cron to force agent execution every minute and moved the notification agent to cron mode. Result: emails arrive within 1–2 minutes after payment. Delay vanished completely. 90% of our clients resolve delay issues after switching to cron.

How to switch agents from hits to cron

1. Check current mode — in the main module settings, ensure the option "Use cron for agents" is off.
2. Add the cron job — command * * * * * /usr/bin/php /path/to/site/bitrix/modules/main/tools/cron_events.php > /dev/null 2>&1.
3. Enable the option in settings — after that, agents stop running on hits.
4. Verify execution — after 1–2 minutes agents should start. Check the agent list in admin; the last execution time should update.
5. Configure additional scripts if needed (e.g., event_exec.php for mail).

Agent mode comparison

What's included in cron and agent setup

• Audit of current agent state (stuck agents, execution errors)
• Crontab configuration for forced agent execution
• Mode switch in Bitrix settings ("Use cron for agents")
• Check and fix stuck agents
• Setup of additional cron jobs (cache cleanup, 1C import, backups)
• 24-hour execution testing

How to monitor agents

Check agent status with SQL query:

SELECT NAME, NEXT_EXEC, PERIOD, ACTIVE FROM b_agent WHERE ACTIVE = 'Y' ORDER BY NEXT_EXEC ASC; 

If NEXT_EXEC lags behind current time by several hours — cron isn't working or an agent failed. Errors are logged in the event log (type AGENT). Turnkey Bitrix scheduler setup includes agent monitoring.

Timeline and cost

Basic configuration takes 2–4 hours. For complex projects with custom cron scripts — 1–2 business days. Cost is calculated individually based on the scope of tasks. 95% of our clients report improved response times after moving agents to cron. Leave a request and we'll evaluate your project within one day. Order an agent audit and get an optimization plan.