Skip to content

LeoYeAI/agent-master-skills / skills/bengii-gemini-fix

openclaw

Flagged

Comprehensive 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.

FileKindSize
README.mdmarkdown7.5 KB
README_CN.mdmarkdown7.3 KB
SKILL.mdskill md18.7 KB
_meta.jsonconfig286 B
references/acp_agents.mdmarkdown12.6 KB
references/agent_runtime.mdmarkdown5.6 KB
references/architecture.mdmarkdown3.8 KB
references/automation.mdmarkdown5.8 KB
references/bonjour.mdmarkdown3.3 KB
references/browser.mdmarkdown8.5 KB
references/channel_routing.mdmarkdown4.0 KB
references/channel_troubleshooting.mdmarkdown11.6 KB
references/channels.mdmarkdown6.2 KB
references/clawhub.mdmarkdown3.6 KB
references/config_reference.mdmarkdown11.2 KB
references/diffs_firecrawl.mdmarkdown3.3 KB
references/elevated.mdmarkdown2.8 KB
references/exec.mdmarkdown6.5 KB
references/exec_approvals.mdmarkdown3.1 KB
references/gateway_internals.mdmarkdown7.7 KB
references/gateway_ops.mdmarkdown9.6 KB
references/heartbeat.mdmarkdown4.9 KB
references/hooks.mdmarkdown14.6 KB
references/install.mdmarkdown4.1 KB
references/llm_task.mdmarkdown2.6 KB
references/lobster.mdmarkdown7.8 KB
references/media.mdmarkdown4.2 KB
references/memory.mdmarkdown11.9 KB
references/model_failover.mdmarkdown3.1 KB
references/multi_agent.mdmarkdown4.4 KB
references/nodes.mdmarkdown8.8 KB
references/openprose.mdmarkdown2.6 KB
references/pairing.mdmarkdown3.1 KB
references/pdf_tool.mdmarkdown3.5 KB
references/platforms.mdmarkdown2.7 KB
references/plugins.mdmarkdown6.9 KB
references/polls.mdmarkdown2.2 KB
references/presence_discovery.mdmarkdown2.2 KB
references/providers.mdmarkdown6.0 KB
references/queue.mdmarkdown2.1 KB
references/remote_access.mdmarkdown4.7 KB
references/sandboxing.mdmarkdown5.6 KB
references/secrets.mdmarkdown5.4 KB
references/security.mdmarkdown24.5 KB
references/sessions.mdmarkdown8.9 KB
references/skills.mdmarkdown4.4 KB
references/slash_commands.mdmarkdown5.1 KB
references/streaming.mdmarkdown1.8 KB
references/subagents.mdmarkdown12.3 KB
references/thinking.mdmarkdown2.8 KB
references/tools.mdmarkdown13.3 KB
references/tui.mdmarkdown4.0 KB
references/voice.mdmarkdown2.7 KB
references/web_tools.mdmarkdown2.7 KB
references/web_ui.mdmarkdown4.5 KB

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).
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall