subagent-timeout-config

Other

One-click subagent timeout configurator for OpenClaw. Configures the three related fields (agents.defaults.timeoutSeconds + subagents.runTimeoutSeconds + acp.runtime.ttlMinutes) atomically with built-in TTL constraint validation (ttlMinutes * 60 ≥ runTimeoutSeconds). Three preset profiles — quick (60s/1h/1h, fast feedback), normal (3min/2h/2h, everyday dev), patient (5min/3h/3h, long-running tasks) — plus --custom for arbitrary values. Auto-backup before write, optional gateway auto-restart, --dry-run preview. Triggers: "set subagent timeout", "subagent 超时", "配置 timeout", "调整超时", "subagent timeout config", "openclaw timeout", "tool call timeout".

Install

openclaw skills install @songhonglei/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)

Ask the user which profile suits their task (or accept --custom).
Show --dry-run diff first when the user is unsure.
Apply with default settings (auto-backup + auto-restart).
Confirm new settings via --status.
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