Subagent timeout config

subagent-timeout-config

• Author: Evan Song · github.com/Songhonglei
• Repository: https://github.com/Songhonglei/better-agent-skills
• License: MIT

One-click timeout configurator for OpenClaw subagents. Set the three related timeout fields atomically with built-in constraint validation, automatic backup, and optional gateway restart.

⚠️ OpenClaw-only by default — reads/writes ~/.openclaw/openclaw.json. Use --config <path> to target a different runtime's JSON config file.

---

Why this skill exists

OpenClaw timeouts are split across three nested fields that must be tuned together:

Field	Path	What it controls
timeoutSeconds	agents.defaults.timeoutSeconds	Per-tool-call wait
runTimeoutSeconds	agents.defaults.subagents.runTimeoutSeconds	Per-subagent task budget
ttlMinutes	acp.runtime.ttlMinutes	ACP session lifetime

Hidden trap: ttlMinutes * 60 must be ≥ runTimeoutSeconds, otherwise sessions die before subagents finish. Default OpenClaw values (30s / 30min / 30min) are too tight for many real-world tasks (codex/claude-code planning, large refactors, complex analysis).

This skill picks the right combination in one command, validates the constraint, backs up the original config, and restarts the gateway.

---

Preset Profiles

Profile	timeoutSeconds	runTimeoutSeconds	ttlMinutes	Use case
quick	60s (1min)	3600s (1h)	60min (1h)	Fast feedback, interactive debugging
normal	180s (3min)	7200s (2h)	120min (2h)	Everyday development
patient	300s (5min)	10800s (3h)	180min (3h)	Long-running tasks, big codebases

Aliases: impatient / fast → quick, slow → patient.

---

Usage

Preview before applying (recommended first time)

python3 <skill-install-path>/scripts/set_timeout.py --profile normal --dry-run

Apply a profile (with auto-restart)

python3 <skill-install-path>/scripts/set_timeout.py --profile patient

Apply without restarting Gateway

python3 <skill-install-path>/scripts/set_timeout.py --profile normal --no-restart
# Then later, when you're ready:
openclaw gateway restart

Custom values

# Format: timeoutSeconds,runTimeoutSeconds,ttlMinutes
python3 <skill-install-path>/scripts/set_timeout.py --custom 240,9000,150

Check current configuration

python3 <skill-install-path>/scripts/set_timeout.py --status

List all profiles

python3 <skill-install-path>/scripts/set_timeout.py --list

Target a non-default config path

python3 <skill-install-path>/scripts/set_timeout.py \
  --profile normal --config /path/to/your/openclaw.json
# Or via env:
OPENCLAW_CONFIG=/path/to/openclaw.json python3 <...>/set_timeout.py --profile normal

---

Workflow (when the agent invokes this skill)

1. Ask the user which profile suits their task (or accept --custom).
2. Show --dry-run diff first when the user is unsure.
3. Apply with default settings (auto-backup + auto-restart).
4. Confirm new settings via --status.
5. If validation fails (e.g. TTL too small), explain the constraint and offer a corrected value.

---

Safety Features

• Auto-backup: Before every write, the original config is copied to <config>.bak.<YYYYMMDD-HHMMSS>. Restore by cp if needed.
• Atomic write: New config is written to a .tmp file then renamed, so a crash mid-write never leaves a corrupt JSON.
• Constraint validation: Refuses to apply invalid combos (e.g. ttlMinutes too small for runTimeoutSeconds). Validation runs before any file modification — --dry-run and real applies both validate.
• Restart opt-out: --no-restart lets you defer the Gateway restart (useful when you have a long-running task you don't want to interrupt).

---

CLI Reference

Flag	Description
--profile <name>	Apply preset: quick / normal / patient (+ aliases)
--custom T,R,TTL	Apply custom values (3 comma-separated integers)
--status	Print current configuration
--list	List all available profiles
--config <path>	Override config file path (default ~/.openclaw/openclaw.json)
--dry-run	Preview diff; do not write file or restart Gateway
--no-restart	Skip openclaw gateway restart after writing

Exit codes: 0 = success, 1 = error (bad args, IO, validation failure).

---

Dependencies

• Python 3.8+ (standard library only — no pip dependencies)
• openclaw CLI on PATH (only needed for the auto-restart step; use --no-restart if you don't have it)

---

What This Skill Is NOT

• Not a generic timeout tool — it only knows about OpenClaw's three specific fields. For other agent runtimes' config formats, use --config to point at a custom JSON path but be aware the schema is OpenClaw-specific.
• Not a persistent daemon — it's a one-shot CLI invocation.
• Not a profile editor — to add a new preset, edit PROFILES in scripts/set_timeout.py.

---

Key Files

File	Purpose
scripts/set_timeout.py	Configurator: profiles, validation, backup, restart