OpenClaw Tmux Persistent Process
Run programs that survive OpenClaw exec session cleanup and gateway restarts.
Why every OpenClaw user should have this
OpenClaw runs shell commands via exec. But exec has a critical limitation that most users don't realize until something breaks:
- - Background processes are tied to the exec session. When the session cleans up (idle timeout, context compaction, or gateway restart), all background processes receive SIGKILL and die immediately.
- Gateway restarts kill everything. Updates, config changes, or
openclaw gateway restart — all running exec processes are gone. - No warning. Your tunnel, dev server, or build task just silently disappears.
This means anything you expect to keep running — a tunnel for a client demo, a dev server, a long build — can die at any moment without notice.
The solution: Use tmux to create virtual terminals completely decoupled from the exec lifecycle. Programs in tmux survive gateway restarts, exec cleanup, and session timeouts. tmux runs independently of OpenClaw — even if the gateway goes down, your processes keep running.
Rule of thumb: If a command might run longer than 2 minutes, use tmux.
Socket convention
All operations use a dedicated socket to avoid interfering with the user's own tmux:
CODEBLOCK0
Start a process
CODEBLOCK1
Monitor
CODEBLOCK2
Interact
CODEBLOCK3
Stop / cleanup
CODEBLOCK4
Start interactive programs (wait for ready)
For programs that need startup time (e.g. coding agents, REPLs):
CODEBLOCK5
Common use cases
| Use case | Session name | Command example |
|---|
| Dev server | INLINECODE2 | INLINECODE3 |
| Tunnel (ngrok) |
tunnel-ngrok |
ngrok http 3000 |
| Tunnel (localhost.run) |
tunnel-lr |
ssh -R 80:localhost:3000 nokey@localhost.run |
| Background worker |
worker |
python worker.py |
| Build task |
build-app |
npm run build |
Session naming
Lowercase + hyphens. No spaces.
CODEBLOCK6
Important notes
- - Reboot = gone. tmux doesn't survive system restarts. Re-create sessions after reboot.
- Scrollback limit. Default 2000 lines. Increase with: INLINECODE12
- Socket stale. If
list-sessions says "error connecting", delete the socket and recreate. - Environment. tmux inherits env at creation time. Set vars in the command: INLINECODE14
- No conflict. Dedicated socket means zero interference with user's own tmux.
Requirements
- - tmux 2.6+ (for
send-keys -l literal mode) - Check: INLINECODE16
- Install:
brew install tmux (macOS) or apt install tmux (Linux)
OpenClaw Tmux 持久化进程
运行能够抵御 OpenClaw exec 会话清理和网关重启的程序。
为什么每个 OpenClaw 用户都应拥有此工具
OpenClaw 通过 exec 运行 shell 命令。但 exec 有一个关键限制，大多数用户直到出问题才会意识到：
- - 后台进程与 exec 会话绑定。 当会话被清理（空闲超时、上下文压缩或网关重启）时，所有后台进程都会收到 SIGKILL 并立即终止。
- 网关重启会杀死一切。 更新、配置变更或 openclaw gateway restart——所有正在运行的 exec 进程都会消失。
- 没有警告。 你的隧道、开发服务器或构建任务就这样悄无声息地消失了。
这意味着你期望持续运行的任何东西——客户演示的隧道、开发服务器、长时间构建——都可能随时无故终止。
解决方案： 使用 tmux 创建与 exec 生命周期完全解耦的虚拟终端。tmux 中的程序能够抵御网关重启、exec 清理和会话超时。tmux 独立于 OpenClaw 运行——即使网关宕机，你的进程也会继续运行。
经验法则： 如果某个命令可能运行超过 2 分钟，请使用 tmux。
Socket 约定
所有操作都使用专用 socket，以避免干扰用户自己的 tmux：
bash
SOCK=/tmp/openclaw-tmux/openclaw.sock
mkdir -p /tmp/openclaw-tmux
启动进程
bash
SESSION=my-server
检查是否已在运行
if tmux -S $SOCK has-session -t $SESSION 2>/dev/null; then
echo 已在运行
else
tmux -S $SOCK new -d -s $SESSION \
cd /path/to/project && npm run dev
echo 已启动
fi
监控
bash
列出所有会话
tmux -S $SOCK list-sessions
查看最后 30 行输出
tmux -S $SOCK capture-pane -t $SESSION -p -S -30
检查进程是否空闲（回到 shell 提示符）
tmux -S $SOCK capture-pane -t $SESSION -p -S -3 \
| grep -qE \$\s*$|❯ && echo 空闲 || echo 运行中
交互
bash
发送命令
tmux -S $SOCK send-keys -t $SESSION command Enter
发送纯文本（推荐，不解析特殊键）
tmux -S $SOCK send-keys -t $SESSION -l -- 纯文本
tmux -S $SOCK send-keys -t $SESSION Enter
Ctrl+C 中断
tmux -S $SOCK send-keys -t $SESSION C-c
停止 / 清理
bash
终止一个会话
tmux -S $SOCK kill-session -t $SESSION
终止所有
tmux -S $SOCK kill-server
清理过期 socket
rm -f $SOCK
启动交互式程序（等待就绪）
对于需要启动时间的程序（例如编码代理、REPL）：
bash
SESSION=my-task
tmux -S $SOCK new -d -s $SESSION
tmux -S $SOCK send-keys -t $SESSION cd ~/project && node Enter
在发送命令前等待提示符
for i in $(seq 1 15); do
OUTPUT=$(tmux -S $SOCK capture-pane -t $SESSION -p -S -5)
if echo $OUTPUT | grep -qE ❯|>\s*$|ready; then
break
fi
sleep 1
done
现在可以安全发送输入
tmux -S $SOCK send-keys -t $SESSION -l your command
tmux -S $SOCK send-keys -t $SESSION Enter
常见用例
| 用例 | 会话名称 | 命令示例 |
|---|
| 开发服务器 | dev-server | npm run dev |
| 隧道 (ngrok) |
tunnel-ngrok | ngrok http 3000 |
| 隧道 (localhost.run) | tunnel-lr | ssh -R 80:localhost:3000 nokey@localhost.run |
| 后台工作进程 | worker | python worker.py |
| 构建任务 | build-app | npm run build |
会话命名
小写字母加连字符。不要有空格。
dev-server — 开发服务器
tunnel-{name} — 隧道（ngrok、cloudflared 等）
build-{project} — 构建任务
worker-{name} — 后台工作进程
重要说明
- - 重启 = 消失。 tmux 无法抵御系统重启。重启后需重新创建会话。
- 回滚限制。 默认 2000 行。可通过以下命令增加：tmux set-option -t $SESSION history-limit 10000
- Socket 过期。 如果 list-sessions 显示 error connecting，请删除 socket 并重新创建。
- 环境变量。 tmux 在创建时继承环境变量。在命令中设置变量：tmux new -d -s name export KEY=val && cmd
- 无冲突。 专用 socket 意味着与用户自己的 tmux 零干扰。
要求
- - tmux 2.6+（支持 send-keys -l 纯文本模式）
- 检查：tmux -V
- 安装：brew install tmux（macOS）或 apt install tmux（Linux）
