LeoYeAI/agent-master-skills / skills/bengii-gemini-fix
openclaw
FlaggedComprehensive guide for installing, configuring, operating, and troubleshooting OpenClaw — a self-hosted, multi-channel AI agent gateway. Use when the user asks about OpenClaw setup, configuration, channel management (WhatsApp/Telegram/Discord/Slack/iMessage/etc.), model provider setup, Gateway operations, multi-agent routing, security hardening, troubleshooting, or any maintenance task related to their local OpenClaw installation. Also use when encountering errors from `openclaw` CLI commands or the Gateway daemon.
references/model_failover.md
View on GitHub# Model Failover & OAuth
> Sources:
> - https://docs.openclaw.ai/concepts/model-failover
> - https://docs.openclaw.ai/concepts/oauth
## Auth Storage (Keys + OAuth)
- Secrets live in `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (legacy: `~/.openclaw/agent/auth-profiles.json`).
- Config `auth.profiles` / `auth.order` are metadata + routing only (no secrets).
- Legacy import-only OAuth file: `~/.openclaw/credentials/oauth.json` (imported into `auth-profiles.json` on first use).
### Profile Types
- `type: "api_key"` → `{ provider, key }`
- `type: "oauth"` → `{ provider, access, refresh, expires, email? }` (+ `projectId`/`enterpriseUrl` for some providers)
### Profile IDs
- Default: `provider:default` when no email is available.
- OAuth with email: `provider:<email>` (e.g. `google-antigravity:user@gmail.com`).
## Rotation Order
1. Explicit config: `auth.order[provider]` (if set).
2. Configured profiles: `auth.profiles` filtered by provider.
3. Stored profiles: entries in `auth-profiles.json` for the provider.
- Primary key: profile type (OAuth before API keys).
- Secondary key: `usageStats.lastUsed` (oldest first, within each type).
- Cooldown/disabled profiles are moved to the end, ordered by soonest expiry.
### Session Stickiness (Cache-Friendly)
- Auth profile is pinned for the duration of a session when possible to improve cache hit rates.
## Cooldowns
- Error-based backoff: 1 min → 5 min → 25 min → 1 hour (cap).
- Tracked in `auth-profiles.json` under `usageStats`:
```json
{
"usageStats": {
"provider:profile": {
"lastUsed": 1736160000000,
"cooldownUntil": 1736160600000,
"errorCount": 2
}
}
}
```
## Billing Disables
- Billing backoff starts at 5 hours, doubles per billing failure, and caps at 24 hours.
- Backoff counters reset if the profile hasn't failed for 24 hours (configurable).
## Model Fallback
- Primary: `agents.defaults.model.primary`
- Fallbacks: `agents.defaults.model.fallbacks` (tried in order when primary fails)
## Related Config
| Config Path | Purpose |
|---|---|
| `auth.profiles` / `auth.order` | Profile metadata + routing |
| `auth.cooldowns.billingBackoffHours` | Initial backoff |
| `auth.cooldowns.billingBackoffHoursByProvider` | Per-provider overrides |
| `auth.cooldowns.billingMaxHours` | Max billing backoff |
| `auth.cooldowns.failureWindowHours` | Reset window |
| `agents.defaults.model.primary` / `fallbacks` | Model selection |
| `agents.defaults.imageModel` | Image model routing |
---
## OAuth
### Anthropic Setup-Token (Subscription Auth)
- `openclaw models auth add` → select Anthropic → paste setup token.
- The Gateway exchanges the setup token for an OAuth access + refresh token pair.
### OpenAI Codex (ChatGPT OAuth)
- `openclaw models auth add` → select OpenAI → browser-based OAuth flow.
### Refresh + Expiry
- OAuth tokens are auto-refreshed before expiry.
- Refresh failures trigger cooldown (like API errors).
### Multiple Accounts (Profiles + Routing)
1. Preferred: separate agents with different profiles.
2. Advanced: multiple profiles in one agent (use `auth.order` to control rotation).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |