openclaw-optimizer

# OpenClaw Optimizer **Aligned with: OpenClaw v2026.3.11** | v2026.3.11.1 | Updated: 2026-03-12 | CLI-first advisor Optimize and troubleshoot OpenClaw workspaces: cost-aware routing, provider configuration, context discipline, lean automation, multi-agent architectures, and error resolution. **Reference files (load when needed):** - `references/providers.md` — all 40+ providers, custom provider schema, failover config - `references/troubleshooting.md` — full error reference, 7 failure categories, GitHub issue workarounds - `references/cli-reference.md` — complete CLI command reference - `references/identity-optimizer.md` — agent identity/personality audit checklist, file roles, walkthrough workflow --- ## Version Awareness This skill tracks OpenClaw releases via two mechanisms: 1. **GitHub Actions** — daily workflow checks for new releases, opens an issue on drift, auto-closes when resolved 2. **Runtime check** — lightweight cached version comparison at session start ### Runtime Check (once per session) ```bash python3 ~/.claude/skills/openclaw-optimizer/scripts/version-check.py --status ``` - **`CURRENT`** → note the version and proceed. - **`STALE`** → inform the user: "OpenClaw v`<new>` is available (skill is at v`<current>`). Run `update-skill.sh` to review what changed." - **`UNCHECKED`** → note "Version check unavailable (offline)" and proceed. ### Update Workflow (user-initiated, never automatic) ```bash # Show drift report, changelog, and affected sections bash ~/.claude/skills/openclaw-optimizer/scripts/update-skill.sh # After updating content in SKILL.md and references/: bash ~/.claude/skills/openclaw-optimizer/scripts/update-skill.sh --apply # bump versions bash ~/.claude/skills/openclaw-optimizer/scripts/update-skill.sh --commit # bump + commit + push ``` Updates are deliberate — this skill never auto-modifies its own content or pushes to git without explicit user action. --- ## Quick Start (copy/paste prompts) **Full audit (safe, no changes):** > Audit my OpenClaw setup for cost, reliability, and context bloat. Prioritized plan with rollback. Do NOT apply changes. **Troubleshoot a specific problem:** > [Describe your symptom or paste the error message]. Diagnose it and give me the exact fix. **Add or configure a provider:** > Add [provider name] as a model provider. Walk me through the CLI steps and show me the exact config before applying. **Model routing optimization:** > Propose a tiered routing plan: cheap for heartbeats/cron, mid for daily tasks, premium for coding/reasoning. Exact config + rollback. Do NOT apply. **Silent cron job:** > Create a cron job that runs [task] every [interval]. Isolated session, NO_REPLY on nothing-to-do. Show me the command first. **Audit agent personality & identity:** > Audit my agent's personality and identity files. Check for conflicts, bloat, and bad practices. Walk me through improvements. --- ## Safety Contract (non-negotiable) - This skill is **advisory by default** — not an autonomous control-plane. - **Never** mutate config (`config.apply`, `config.patch`), cron jobs, or persistent settings without explicit user approval. - Before any approved change: show (1) exact CLI command or config patch, (2) expected impact, (3) rollback command. - If an optimization reduces monitoring coverage, present Options A/B/C and require the user to choose. --- ## Backup Strategy Four backup layers exist — don't stack manual backups on top unnecessarily: | Layer | What | Retention | When It's Enough | |---|---|---|---| | **CLI rolling `.bak`** | Auto-created on every `config set`, `models set`, `cron edit` | Rolling (overwritten each write) | Single-command undo | | **Nightly GitHub backup** | Full config committed by cron job (3 AM) | Git history (unlimited) | Any rollback to a previous day's state | | **`openclaw backup create`** | Local state archive with manifest verification (v2026.3.8+) | Until manually deleted | Pre-upgrade safety net; use `openclaw backup verify` to validate | | **Manual dated backup** | `cp <file> <file>.YYYY-MM-DD-<reason>` | Until next nightly covers it, then delete | Major upgrades, multi-file restructuring, direct JSON edits | **Rule:** For routine CLI changes (model swaps, cron edits, config sets), do NOT create manual backups. The CLI `.bak` + nightly GitHub backup are sufficient. Only create a manual backup when: (1) upgrading OpenClaw versions, (2) editing multiple config files simultaneously (identity audits), or (3) editing JSON directly without the CLI. For upgrades, prefer `openclaw backup create` over manual copies. --- ## 1. Model Providers 40+ providers supported. For full docs (auth commands, config schemas, all model names, custom provider setup): **read `references/providers.md`** **Quick lookup — slug, auth env, primary model format:** | Provider | Slug | Auth Env | Model Format | |---|---|---|---| | Anthropic | `anthropic` | `ANTHROPIC_API_KEY` | `anthropic/claude-opus-4-6` | | OpenAI (API key) | `openai` | `OPENAI_API_KEY` | `openai/gpt-5.4` | | **OpenAI Codex (subscription)** | `openai-codex` | **ChatGPT OAuth** | `openai-codex/gpt-5.4` | | Google Gemini | `google` | `GEMINI_API_KEY` | `google/gemini-3.1-pro-preview` | > **WARNING — Provider Bans (Mar 2026):** > > **Google:** Actively cracking down on Gemini CLI OAuth and AntiGravity access through third-party tools. Accounts are being banned or rate-limited without warning or refunds. Use API key auth (`google` provider) instead of OAuth (`google-gemini-cli` / `google-antigravity`). Production API keys: 150-300 RPM, no ban risk. See GitHub Issue #14203. > > **Anthropic:** Has banned users linking flat-rate Claude Code subscription tokens to OpenClaw. Using Claude Code OAuth tokens directly in OpenClaw may trigger account suspension. However, using Claude Code through the **Agent SDK / ACP dispatch** (where OpenClaw spawns Claude Code as a sub-agent via the ACP protocol) is the supported pattern and should not cause issues — this is how OpenClaw's built-in `acp` integration works. > > **General:** Always prefer pay-per-token API keys over subscription OAuth for third-party tool integrations. Subscription-based OAuth through third-party tools violates most providers' ToS except OpenAI, which explicitly permits Codex OAuth in third-party tools. | Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` | | Groq | `groq` | `GROQ_API_KEY` | `groq/<model-id>` | | xAI | `xai` | `XAI_API_KEY` | `xai/grok-code-fast-1` | | OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | `openrouter/anthropic/claude-sonnet-4-5` | | Bedrock | `amazon-bedrock` | AWS env chain | `amazon-bedrock/us.anthropic.claude-opus-4-6-v1:0` | | **Kilo Gateway** | `kilocode` | `KILOCODE_API_KEY` | `kilocode/anthropic/claude-opus-4.6` | | Moonshot/Kimi | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.5` | | Kimi Coding | `kimi-coding` | `KIMI_API_KEY` | `kimi-coding/k2p5` | | Z.AI / GLM | `zai` | `ZAI_API_KEY` | `zai/glm-5` | | MiniMax | `minimax` | `MINIMAX_API_KEY` | `minimax/MiniMax-M2.5-highspeed` | | MiniMax VL-01 | `minimax-portal` | `MINIMAX_API_KEY` | `minimax-portal/MiniMax-VL-01` | | Venice AI | `venice` | `VENICE_API_KEY` | `venice/kimi-k2-5` | | Hugging Face | `huggingface` | `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` | | Synthetic | `synthetic` | `SYNTHETIC_API_KEY` | `synthetic/hf:MiniMaxAI/MiniMax-M2.1` | | Together AI | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` | | Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` | | OpenCode Zen | `opencode` | `OPENCODE_API_KEY` | `opencode/claude-opus-4-6` | | OpenCode Go | `opencode-go` | `OPENCODE_API_KEY` | `opencode-go/claude-opus-4-6` | | Ollama (local) | `ollama` | `OLLAMA_API_KEY` (any) | `ollama/llama3.3` | | vLLM (local) | `vllm` | `VLLM_API_KEY` (any) | `vllm/<model-id>` | **Add a provider (API key):** ```bash openclaw onboard --auth-choice <provider>-api-key openclaw models auth login --provider <slug> openclaw models set <provider/model> ``` **Add a provider (OAuth / subscription):** ```bash openclaw onboard --auth-choice openai-codex # ChatGPT subscription openclaw models auth login --provider openai-codex openclaw models set openai-codex/gpt-5.4 ``` ### OAuth Providers (Subscription-Based Access) Some providers offer OAuth authentication tied to a consumer subscription (e.g., ChatGPT Plus/Pro) instead of — or in addition to — a pay-per-token API key. OpenClaw supports these via device-flow OAuth. **Currently supported OAuth providers:** | Provider | Slug | Subscription Required | Top Models | |---|---|---|---| | **OpenAI Codex** | `openai-codex` | ChatGPT Plus ($20/mo) or Pro ($200/mo) | `gpt-5.4`, `gpt-5.3-codex`, `codex-mini-latest` | | GitHub Copilot | `github-copilot` | Copilot subscription | `github-copilot/gpt-4o` | **OpenAI Codex setup (full walkthrough):** ```bash # 1. Authenticate (opens browser for ChatGPT sign-in) openclaw models auth login --provider openai-codex # → Prints a URL. Open it in a browser, sign in to ChatGPT, paste redirect URL back. # 3. Verify auth openclaw models status --probe --probe-provider openai-codex # 4. Set as primary OR add to fallback chain openclaw models set openai-codex/gpt-5.4 # as primary openclaw models fallbacks add openai-codex/gpt-5.4 # or as fallback # 5. Restart gateway launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway # macOS LaunchAgent ``` **Headless / SSH gateway:** The OAuth flow prints a URL. Open it in any browser (doesn't need to be on the gateway machine), complete sign-in, then paste the redirect URL back into the SSH terminal. Alternatively, complete OAuth on a machine with a browser and copy `~/.openclaw/credentials/oauth.json` to the gateway. **Available Codex models:** | Model | Plan | Notes | |---|---|---| | `openai-codex/gpt-5.4` | Plus, Pro, Business | Latest (Mar 2026), 1,050,000-token context, 128K max tokens | | `openai-codex/gpt-5.3-codex` | Plus, Pro, Business | Previous flagship, most capable coding model | | `openai-codex/gpt-5.3-codex-spark` | **Pro only** | Research preview, low-latency | | `openai-codex/gpt-5.2-codex` | Plus, Pro | Previous gen, stable | | `openai-codex/codex-mini-latest` | Plus, Pro | Lightweight, fast, cheapest | **Usage limits (per 5-hour window):** - **Plus ($20/mo):** 30–150 messages - **Pro ($200/mo):** 300–1,500 messages - Extra credits purchasable when limits are hit **Gotchas:** - **No embeddings.** Codex OAuth does NOT grant access to OpenAI embeddings. You still need a separate `OPENAI_API_KEY` for `text-embedding-3-small` etc. - **Token refresh is automatic** — active sessions continue without re-login. Credentials stored in `~/.openclaw/credentials/oauth.json`. - **Don't use both Codex CLI and OpenClaw simultaneously** — some providers invalidate older refresh tokens when a new one is issued. Logging in via one tool can log you out of the other. - **"Model not supported" errors** — some users report this with `gpt-5.3-codex` on certain accounts. Fall back to `gpt-5.2-codex` if this happens. - **Dual-config registration required (Issue #13189):** The built-in catalog uses wrong API type (`openai-completions`) for gpt-5.3-codex. Must register manually in **both** `models.json` (API type: `openai-codex-responses`) **AND** `openclaw.json` (API type: `openai-responses` — `openai-codex-responses` is only valid in models.json per schema). v2026.2.26 includes a schema fix — verify with `openclaw models status --probe` after upgrade. - **Community context (Feb 2026):** After Anthropic and Google updated their ToS to block subscription-based OAuth in third-party tools, the OpenClaw community migrated heavily to `openai-codex`. OpenAI explicitly permits Codex OAuth in third-party tools, though fair-use limits still apply. ### Provider Removal Checklist Removing a provider requires cleaning **6 locations** — `config unset` alone is not enough: 1. `models.providers.<slug>` in openclaw.json — `openclaw config unset models.providers.<slug>` 2. `auth.profiles.<slug>:*` in openclaw.json — must edit JSON directly (colons in keys break `config unset`) 3. `profiles` dict in `~/.openclaw/agents/main/agent/auth-profiles.json` — edit with python3/jq 4. `agents.defaults.models.<provider/model>` aliases in openclaw.json — `openclaw config unset` each alias 5. `plugins.entries.<slug>-auth` in openclaw.json — `openclaw config unset plugins.entries.<slug>-auth` 6. `lastGood.<slug>` and `usageStats.<slug>:*` in auth-profiles.json — edit directly For providers with LaunchAgent env vars (Ollama, etc.), also clean: 7. `launchctl unsetenv <KEY>` — session-level env persists independently of plist 8. PlistBuddy delete from `~/Library/LaunchAgents/ai.openclaw.gateway.plist` 9. `launchctl bootout` + `launchctl bootstrap` to pick up the clean plist (kickstart alone doesn't reload env from plist) **Known CLI limitation:** `openclaw config unset` cannot handle colons in config keys (e.g., `auth.profiles.google-gemini-cli:email@gmail.com`). The parser treats colons as path separators. Edit the JSON file directly for these entries. **Ollama for memory embeddings (v2026.3.2+):** ```bash openclaw config set memorySearch.provider ollama openclaw config set memorySearch.fallback ollama ``` Runs memory search embeddings locally — no external API calls. Honors `models.providers.ollama` settings. **Gemini embedding for memory search (v2026.3.11+):** ```bash openclaw config set memorySearch.provider google openclaw config set memorySearch.model gemini-embedding-2-preview ``` Supports configurable output dimensions and automatic reindexing. Opt-in multimodal image and audio indexing available via `memorySearch.extraPaths`.