paperclip-resilience（回形针弹性）

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

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

Security Boundaries

• Process execution: uses execFile, not shell execution
• Dynamic code execution: none (eval / Function not 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