微信扫一扫paperclip-resilience
Production-grade resilience for AI agents running on Paperclip, orchestrated through OpenClaw.
The Problem
Paperclip agents die silently when providers hit rate limits, sessions crash on gateway restarts, and failed runs leave agents stuck in error state with no recovery path. If you're running agents overnight or in parallel, you need automated recovery — not manual babysitting.
What's Included
| Module | File | Purpose |
|--------|------|---------|
| Spawn with Fallback | src/spawn-with-fallback.js | Wraps openclaw session spawn with automatic provider failover. If your primary model 429s, it tries the configured fallback. |
| Model Rotation | src/model-rotation.js | Tracks fix attempts per PR/task and rotates through models + thinking levels after repeated failures. |
| Run Recovery | src/run-recovery.js | Detects failed Paperclip heartbeat runs (gateway errors, timeouts, 429s) and re-invokes agents with model fallback. |
| Blocker Routing | src/blocker-routing.js | Scans agent session transcripts for blocked/stuck signals and routes them to configurable destinations (file, stdout, webhook). |
| Task Injection | src/task-injection.js | Enriches spawn task descriptions with issue tracking metadata, PR requirements, and UX design checklists before agent execution. |
Quick Start
1. Install
clawhub install paperclip-resilience
2. Configure
cd skills/paperclip-resilience
cp config.example.json config.json
# Edit config.json with your model aliases and fallback pairs
3. Use Spawn with Fallback
# CLI
node skills/paperclip-resilience/src/spawn-with-fallback.js \
--model sonnet --task "Fix the login bug" --mode run
# Dry run to see what would happen
node skills/paperclip-resilience/src/spawn-with-fallback.js \
--model opus --task "Refactor auth" --dry-run
// Programmatic
const { spawnWithFallback, loadConfig } = require('./skills/paperclip-resilience/src/spawn-with-fallback');
const config = loadConfig('./my-config.json');
const result = await spawnWithFallback({ model: 'sonnet', task: 'Fix bug', config });
4. Set Up Run Recovery (Cron)
Add to your OpenClaw cron schedule to auto-recover failed runs:
node skills/paperclip-resilience/src/run-recovery.js --dry-run --verbose
Once verified, schedule it:
*/15 * * * * node skills/paperclip-resilience/src/run-recovery.js
5. Model Rotation for PR Fixes
# Check if a PR needs model rotation
node skills/paperclip-resilience/src/model-rotation.js check --pr 42 --repo owner/repo
# Record an attempt
node skills/paperclip-resilience/src/model-rotation.js record --pr 42 --repo owner/repo --model anthropic/claude-sonnet-4-6
Configuration
All modules read from config.json in the skill directory, with sensible defaults if no config is provided.
See config.example.json for the full documented schema, and config.schema.json for validation.
Key Configuration Sections
aliases — Map short model names to full provider/model strings:
{
"aliases": {
"sonnet": "anthropic/claude-sonnet-4-6",
"opus": "anthropic/claude-opus-4-6",
"codex": "openai-codex/gpt-5.3-codex"
}
}
fallbacks — Define provider failover pairs:
{
"fallbacks": {
"anthropic/claude-sonnet-4-6": "openai-codex/gpt-5.3-codex",
"openai-codex/gpt-5.3-codex": "anthropic/claude-sonnet-4-6"
}
}
failurePatterns — Regex patterns that trigger fallback:
{
"failurePatterns": {
"patterns": ["credits", "quota", "402", "rate[\\s_-]?limit"]
}
}
Architecture
┌──────────────────┐ ┌──────────────────┐
│ Task Injection │────▶│ Spawn w/ Fallback │
│ (enrich task) │ │ (provider retry) │
└──────────────────┘ └────────┬───────────┘
│
▼
┌──────────────────────┐
│ Paperclip Agent │
│ (heartbeat runs) │
└──────────┬───────────┘
│
┌──────────┴───────────┐
│ │
▼ ▼
┌────────────────┐ ┌──────────────────┐
│ Run Recovery │ │ Blocker Routing │
│ (detect + wake) │ │ (escalate stuck) │
└────────────────┘ └──────────────────┘
│
▼
┌────────────────┐
│ Model Rotation │
│ (escalate model)│
└────────────────┘
Requirements
- OpenClaw (for session spawning and agent management)
- Paperclip (for heartbeat run monitoring and agent lifecycle)
- Node.js 18+
- At least two LLM provider API keys configured (for fallback to work)
Security
This skill was security-reviewed for ClawHub publication in SUP-453. The code paths that accept user-controlled input now enforce validation up front and fail closed.
Hardened Surfaces
| Surface | Protection |
|---|---|
| Model names | Character allowlist with support for provider suffixes like :free; rejects empty path segments and . / .. traversal segments |
| Task files (@file) | Blocks explicit ../, canonicalizes symlinks with realpath, rejects system paths like /etc/ and /usr/, requires a regular file |
| Task payloads | 1MB max size limit for inline and file-backed task content |
| Spawn mode + labels | Allowlist validation for mode (run, session) and safe-character validation for labels |
| Failure regex config | Caps pattern count/length and drops invalid regexes to reduce ReDoS risk |
| Paperclip issue metadata | Sanitizes API strings, constrains issue identifier extraction, normalizes priority values |
Security Boundaries
- Process execution: uses
execFile, not shell execution - Dynamic code execution: none (
eval/Functionnot used) - Credentials: read from environment or external auth files; not embedded in the skill
- File access: limited to explicitly requested files, with traversal and symlink tunnel protections
- Dependencies: zero external runtime dependencies in this package
Verification
# Functional coverage
node skills/paperclip-resilience/tests/test-spawn-with-fallback.js
# Full security suite
node skills/paperclip-resilience/tests/test-security.js
# Quick smoke test
node skills/paperclip-resilience/tests/test-security-quick.js
Audit Record
- Last audit: 2026-03-27
- Tracking issue: SUP-453
- Status: ✅ Approved for ClawHub publication
- Details: see SECURITY-AUDIT-REPORT.md
Related Paperclip Issues
These are the upstream gaps this skill works around:
- #276 — Auto-requeue agent on failure
- #1845 — No crash-recovery wakeup after restart
- #1861 — Agent death on 429 with no model fallback
License
MIT