What is the default session lock timeout?

The default `SESSION_STORE_LOCK_TIMEOUT` is 10 seconds.

Can I set the timeout per agent?

Currently, the `SESSION_STORE_LOCK_TIMEOUT` is a global environment variable for the Clawbot instance, not configurable per agent.

What if operations are still timing out after increasing the lock timeout?

If operations consistently exceed your increased lock timeout, you need to investigate the operations themselves. They might be too slow, or there could be an issue with the tools or commands they are executing. Look for ways to optimize those specific tasks.

Troubleshooting Session Lock Timeout Failures in OpenClaw

TL;DR — Quick Fix

Session lock timeouts occur because agent operations block the session store lock for too long; increase lock timeout or optimize operations.

Run Diagnostics

Next Step

Fix now, then reduce repeat incidents

If this issue keeps coming back, validate your setup in Doctor first, then harden your config.

Open Doctor Harden Config

Error Signal

Error: timeout acquiring session store lock: /root/.clawdbot/agents/main/sessions/sessions.json.lock

What's Happening

You're seeing your channel handlers, especially Telegram, fail with lock timeouts. This happens when your agent is busy with a long-running task like running commands, making HTTP requests, or tool calls. The error message looks like this: Error: timeout acquiring session store lock: /root/.clawdbot/agents/main/sessions/sessions.json.lock.

This blocks new messages from being processed. It’s not about having multiple channels; even one long operation can cause this.

The Fix

The most direct fix is to adjust the session lock timeout. You can do this by setting the SESSION_STORE_LOCK_TIMEOUT environment variable. The default is 10 seconds. Increasing this can give your long operations enough time to complete without failing.

Try setting it to a much higher value, like 5 minutes (300,000 milliseconds) or even more, depending on how long your operations typically take.

Example using Docker Compose:

services:
  clawdbot:
    image: ghcr.io/openclaw/clawdbot:latest
    environment:
      - SESSION_STORE_LOCK_TIMEOUT=300000 # 5 minutes
    # ... other configurations

If you're running directly, set it before starting your clawdbot instance:

export SESSION_STORE_LOCK_TIMEOUT=300000
npx clawdbot start

Why This Occurs

When an agent starts a long operation, it acquires a lock on the session file (sessions.json.lock). While this lock is held, other parts of the system trying to access or update session data (like processing a new incoming message) will wait. If they wait longer than the SESSION_STORE_LOCK_TIMEOUT (default 10 seconds), they give up and throw the timeout error. Long operations, especially waiting for LLM responses or slow external tools, can easily exceed this 10-second window, leading to the lock timeout.

Prevention

Optimize Long Operations: Review your agent's tools and commands. Can any long-running processes be made faster? Can you break them down into smaller steps?
Increase Timeout: As mentioned in "The Fix", increasing SESSION_STORE_LOCK_TIMEOUT is the primary workaround. Monitor your longest operations to set an appropriate, but not excessively high, value.
Stale Lock Cleanup: Some users have reported stale locks not being cleaned up after errors or timeouts (like in openclaw/openclaw#3092 comments). Ensure your environment is robust. In severe cases, a cron job to clean up stale .lock files in your ~/.clawdbot/agents/<agent-name>/sessions/ directory might be a temporary band-aid, but it doesn't fix the root cause of the long operation blocking the lock.

Consider the maxConcurrent setting in your agent config. While the issue isn't caused by concurrency, too many concurrent long operations could exacerbate the problem by increasing the chance of a lock conflict.

Last Updated: March 2026

Did this guide solve your problem?