ACP Fallback System - Resilient Agent Execution\r

\r

Overview\r

This skill provides automatic fallback for ACP vendors (Codex → Claude → Pi → API) and model fallback for subagents. If one vendor fails, it automatically tries the next.\r \r

Usage\r

\r

For Agents - Use acp_exec Function\r

\r

# Instead of direct acpx calls, use this wrapper\r
source scripts/acp-fallback.sh && acp_exec "your task here"\r
```\r
\r
### ACP Vendor Priority (in order):\r
1. **codex** - Primary (fast, reliable)\r
2. **claude** - Fallback #1 (high quality)\r
3. **pi** - Fallback #2 (lightweight)\r
4. **direct-api** - Final fallback (uses OpenClaw's built-in models)\r
\r
### What Happens on Failure:\r
- Vendor fails → Auto-retry with next vendor\r
- All vendors fail → Log error, return failure status\r
- Success → Return result immediately\r
\r
## Implementation\r
\r
### Core Functions\r
\r
```bash\r
# acp_exec - Main entry point\r
# Usage: acp_exec "task description"\r
# Returns: Vendor used + result\r
\r
# acp_exec_with_fallback - Full fallback chain\r
# Tries: codex → claude → pi → direct-api\r
# Returns: First successful result\r
\r
# model_fallback - For subagent model switching\r
# Tries: MiniMax → DeepSeek → OpenAI → GLM-5\r
```\r
\r
### Agent Integration\r
\r
Agents should call these functions instead of direct acpx commands:\r
- Replace `npx acpx codex exec "..."` with `acp_exec "..."`\r
- Replace single-model subagent with fallback-enabled wrapper\r
\r
## Error Handling\r
\r
- Network errors: Retry with next vendor after 3s\r
- Auth errors: Skip to next vendor immediately  \r
- Rate limits: Wait 10s, then retry\r
- Timeout (>120s): Move to next vendor\r
\r
## Logging\r
\r
All fallback attempts logged to:\r
- `logs/acp-fallback.log`\r
\r
## Success Metrics\r
\r
Tracked:\r
- Vendor used\r
- Number of retries\r
- Total time\r
- Success/failure status\r