Using TMUX for Long-Running OpenClaw Agents (Step-by-Step)
Using TMUX for Long-Running OpenClaw Agents (Step-by-Step)
If you've ever kicked off an OpenClaw agent, watched it start cranking through tasks, then closed your laptop and realized you just murdered the process — this post is for you.
Long-running AI agents are only useful if they actually keep running. And the single best tool for making that happen costs zero dollars, has been around since 2007, and is already installed on most Linux boxes: tmux.
I'm going to walk you through exactly how to set up tmux to run OpenClaw agents that persist for hours, days, or however long your workflow demands. No hand-waving. No "just figure it out." Actual commands, actual config, actual code you can steal.
Let's get into it.
Why Your OpenClaw Agents Keep Dying
Here's the problem in one sentence: when you close your terminal, everything running inside it dies.
That SSH session you had open to your server? Dead. The OpenClaw agent that was halfway through processing a 200-item task queue? Gone. The three hours of work it already completed? Depends on whether you built in checkpointing (you probably didn't).
This isn't an OpenClaw-specific problem. It's a Unix process problem. Your shell spawns child processes. When the shell dies, it sends SIGHUP to its children, and they terminate. End of story.
People try to solve this with nohup, with screen, with disown, with background processes and redirect chains that look like summoning spells. Some of these work. Most of them work poorly — especially when you need to come back later and actually see what the agent is doing, interact with it, or debug why it stalled at step 47.
tmux solves all of this. It creates a persistent session that lives independently of your terminal connection. You can detach, close your laptop, fly to another country, SSH back in, and reattach to the exact same session. Your OpenClaw agent never noticed you left.
But there's a right way and a wrong way to set this up for AI agents specifically. Most tmux tutorials are written for humans doing human things. Agents have different needs. Let's address those.
The 5-Minute tmux Setup for OpenClaw
Step 1: Install tmux (If You Somehow Don't Have It)
# Ubuntu/Debian
sudo apt update && sudo apt install tmux -y
# macOS
brew install tmux
# Amazon Linux / RHEL
sudo yum install tmux -y
Confirm it's there:
tmux -V
# tmux 3.3a (or whatever version)
You want version 3.0 or higher. If you're on an ancient system running tmux 1.8, upgrade. The newer versions handle the things agents need (better capture-pane behavior, improved send-keys reliability) much more gracefully.
Step 2: Create an Agent-Optimized tmux Config
This is where most people go wrong. The default tmux config is fine for humans. It's not great for long-running agent processes. Create or edit ~/.tmux.conf:
# ~/.tmux.conf — optimized for OpenClaw agents
# Massive scrollback buffer (default is 2000, which agents blow through)
set-option -g history-limit 100000
# Don't let tmux rename windows automatically
set-option -g allow-rename off
# Start window numbering at 1 (easier to reference)
set-option -g base-index 1
set-option -g pane-base-index 1
# Disable mouse mode (agents send keys programmatically, mouse mode causes issues)
set-option -g mouse off
# Aggressive resize — useful when reattaching from different terminal sizes
set-option -g aggressive-resize on
# Reduce escape time (prevents delays when agents send rapid key sequences)
set-option -sg escape-time 10
# Activity monitoring (get notified if a pane has output)
set-option -g monitor-activity on
set-option -g visual-activity off
# Status bar that actually tells you something useful
set-option -g status-right '#{pane_current_command} | %H:%M'
set-option -g status-left '[#S] '
# Enable logging plugin if you have TPM (optional but recommended)
# set -g @plugin 'tmux-plugins/tmux-logging'
Reload it:
tmux source-file ~/.tmux.conf
The history-limit 100000 is the most important line. OpenClaw agents can produce thousands of lines of output. With the default 2000-line buffer, you lose context. The agent (or you, when debugging) can't scroll back far enough to see what happened. A hundred thousand lines costs almost nothing in RAM and saves you from "what the hell happened three hours ago" blindness.
Step 3: Create a Named Session for Your Agent
Don't just type tmux. Always name your sessions. When you have three agents running plus a monitoring pane plus your actual work, unnamed sessions become a nightmare.
tmux new-session -d -s openclaw-agent-1
The -d flag creates it in detached mode. This is important for scripting — you can create the session, set it up, and then attach to it when you're ready.
Want to attach to it now?
tmux attach -t openclaw-agent-1
Step 4: Launch Your OpenClaw Agent Inside the Session
Now here's where it all comes together. Attach to your session and start your agent. If you're working with the Felix OpenClaw Starter Pack — which I genuinely recommend as your entry point if you're new to OpenClaw because it bundles the agent scaffolding, configuration templates, and task primitives you'd otherwise spend hours assembling yourself — your launch might look something like this:
# Attach to the session
tmux attach -t openclaw-agent-1
# Navigate to your project
cd ~/openclaw-projects/my-agent
# Activate your environment
source venv/bin/activate
# Launch the agent
python run_agent.py --config config.yaml --task-queue tasks.json
Once it's running, detach with Ctrl+b then d. That's the magic moment. Your agent keeps running. You're free.
Come back anytime:
tmux attach -t openclaw-agent-1
Everything is exactly as you left it. Every line of output preserved.
The Multi-Pane Setup (For When You're Serious)
Running a single agent in a single pane is fine for getting started. But real workflows usually look more like this:
- Pane 1: The OpenClaw agent doing its thing
- Pane 2: Tailing a log file
- Pane 3: Monitoring system resources
- Pane 4: A shell ready for ad-hoc commands
Here's how to script that entire layout:
#!/bin/bash
# setup-openclaw-workspace.sh
SESSION="openclaw-workspace"
# Kill existing session if it exists
tmux kill-session -t $SESSION 2>/dev/null
# Create session with first window
tmux new-session -d -s $SESSION -n 'agent'
# Pane 0: Agent runner
tmux send-keys -t $SESSION:1.0 'cd ~/openclaw-projects/my-agent && source venv/bin/activate' Enter
# Split horizontally for logs
tmux split-window -h -t $SESSION:1
tmux send-keys -t $SESSION:1.1 'tail -f ~/openclaw-projects/my-agent/logs/agent.log' Enter
# Split the right pane vertically for monitoring
tmux split-window -v -t $SESSION:1.1
tmux send-keys -t $SESSION:1.2 'htop' Enter
# Create a second window for ad-hoc work
tmux new-window -t $SESSION -n 'shell'
tmux send-keys -t $SESSION:2 'cd ~/openclaw-projects/my-agent && source venv/bin/activate' Enter
# Select the agent pane
tmux select-window -t $SESSION:1
tmux select-pane -t 0
# Attach
tmux attach -t $SESSION
Save that as a script. Run it whenever you start a new working session. Everything is laid out, named, and ready.
Capturing Agent Output Programmatically
One of the most powerful things about running OpenClaw agents inside tmux is that you can programmatically read what the agent is outputting from outside the session. This is critical for building monitoring, alerting, or meta-agent systems.
# Capture the last 500 lines from a specific pane
tmux capture-pane -t openclaw-agent-1:1.0 -p -S -500
You can pipe that into a monitoring script:
#!/usr/bin/env python3
# monitor_agent.py
import subprocess
import time
import re
def get_agent_output(session, lines=100):
"""Capture recent output from the agent's tmux pane."""
result = subprocess.run(
['tmux', 'capture-pane', '-t', f'{session}:1.0', '-p', '-S', f'-{lines}'],
capture_output=True, text=True
)
# Strip ANSI escape codes
clean = re.sub(r'\x1b\[[0-9;]*m', '', result.stdout)
return clean.strip()
def check_for_errors(output):
"""Look for common failure patterns."""
error_patterns = [
r'Traceback \(most recent call last\)',
r'ERROR',
r'Exception:',
r'ConnectionRefused',
r'rate.limit',
]
for pattern in error_patterns:
if re.search(pattern, output, re.IGNORECASE):
return True, pattern
return False, None
def check_for_stall(output, previous_output):
"""Detect if the agent has stalled (output hasn't changed)."""
return output == previous_output
if __name__ == '__main__':
session = 'openclaw-agent-1'
previous = ''
while True:
output = get_agent_output(session, lines=50)
has_error, pattern = check_for_errors(output)
if has_error:
print(f'[ALERT] Error detected matching pattern: {pattern}')
# Send yourself a notification, restart the agent, etc.
if check_for_stall(output, previous):
print('[WARN] Agent output unchanged — possible stall')
previous = output
time.sleep(30)
This is a basic watchdog. In production, you'd wire this into whatever alerting you use — Slack webhook, email, PagerDuty, whatever. The point is: tmux makes the agent's runtime observable without disrupting it.
Sending Commands to a Running Agent
Sometimes you need to interact with a running OpenClaw agent. Maybe it's waiting for input. Maybe you want to gracefully stop it. tmux lets you inject keystrokes from outside:
# Send a command to the agent's pane
tmux send-keys -t openclaw-agent-1:1.0 'status' Enter
# Send Ctrl+C to interrupt
tmux send-keys -t openclaw-agent-1:1.0 C-c
# Send a graceful shutdown signal (if your agent listens for it)
tmux send-keys -t openclaw-agent-1:1.0 'quit' Enter
This is incredibly powerful for automation. You can write scripts that manage fleets of agents:
#!/bin/bash
# restart_all_agents.sh
for i in 1 2 3 4 5; do
SESSION="openclaw-agent-$i"
# Graceful stop
tmux send-keys -t $SESSION:1.0 C-c
sleep 2
# Relaunch
tmux send-keys -t $SESSION:1.0 'python run_agent.py --config config.yaml --resume' Enter
echo "Restarted $SESSION"
done
Surviving Server Reboots
tmux sessions don't survive reboots by default. The tmux server process dies, and everything goes with it. There are two ways to handle this:
Option 1: tmux-resurrect plugin
# Install TPM (Tmux Plugin Manager)
git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
# Add to ~/.tmux.conf
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-resurrect'
# Save session: Ctrl+b, Ctrl+s
# Restore session: Ctrl+b, Ctrl+r
Option 2: systemd service (more reliable for production)
# /etc/systemd/system/openclaw-agent.service
[Unit]
Description=OpenClaw Agent via tmux
After=network.target
[Service]
Type=forking
User=yourusername
ExecStart=/usr/bin/tmux new-session -d -s openclaw-agent-1 'cd /home/yourusername/openclaw-projects/my-agent && source venv/bin/activate && python run_agent.py --config config.yaml'
ExecStop=/usr/bin/tmux send-keys -t openclaw-agent-1 C-c
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
sudo systemctl enable openclaw-agent
sudo systemctl start openclaw-agent
Now your agent starts on boot, restarts on failure, and still runs inside tmux so you can attach and inspect it anytime.
Common Gotchas and How to Fix Them
"My agent's output is full of ANSI garbage when I capture it."
Use the regex strip from the monitoring script above, or capture with -e flag and post-process. This is the single most common complaint I see from people wiring agents to tmux.
"The agent thinks it's in the wrong directory after reattaching."
It's not. You're probably attaching to the wrong pane. Use tmux list-panes -t your-session -F '#{pane_index} #{pane_current_path} #{pane_current_command}' to verify where everything is.
"Output is truncated to 2000 lines."
You didn't set history-limit. Go back to Step 2.
"My agent sent a command that put tmux into copy mode and now it's stuck."
Send q to exit copy mode: tmux send-keys -t session:window.pane q
"I can't figure out which session is which."
tmux list-sessions
# openclaw-agent-1: 1 windows (created Mon Jan 6 14:22:33 2026)
# openclaw-agent-2: 1 windows (created Mon Jan 6 14:23:01 2026)
# openclaw-workspace: 2 windows (created Mon Jan 6 14:25:17 2026)
Name your sessions. Always.
Where to Start
If you've read this far and you don't have an OpenClaw project set up yet, here's what I'd do:
-
Grab the Felix OpenClaw Starter Pack. It gives you the agent scaffolding, pre-built config templates, and task queue primitives so you're not starting from a blank Python file. Seriously — the amount of boilerplate it eliminates is worth it, especially for the tmux integration patterns. You'll have a running agent in minutes instead of hours.
-
Set up your tmux config using the agent-optimized settings from Step 2 above.
-
Write the workspace setup script from the multi-pane section. Customize it for your specific project structure.
-
Deploy the monitoring script. Even a basic one that checks for errors and stalls will save you from discovering at 8 AM that your agent crashed at 11 PM.
-
If you're running on a remote server, add the systemd service so reboots don't kill your work.
That's the whole thing. tmux isn't glamorous. It doesn't have a pretty UI or a marketing page. But it's the backbone of every serious long-running agent deployment I've seen. The people running agents that actually stay up for days? They're using tmux. Or screen, but those people also probably still use flip phones.
Set it up once. Get it right. Then forget about it and focus on what your OpenClaw agents are actually doing — which is the part that matters.