{ "schemaVersion": "1.0", "item": { "slug": "openclaw-optimizer", "name": "Openclaw Optimizer", "source": "tencent", "type": "skill", "category": "AI 智能", "sourceUrl": "https://clawhub.ai/jacob-bd/openclaw-optimizer", "canonicalUrl": "https://clawhub.ai/jacob-bd/openclaw-optimizer", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/openclaw-optimizer", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=openclaw-optimizer", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "SKILL.md", "metadata/knowledge-map.json", "metadata/last-checked.txt", "metadata/latest-version.txt", "metadata/update-log.md", "references/cli-reference.md" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-30T16:55:25.780Z", "expiresAt": "2026-05-07T16:55:25.780Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/openclaw-optimizer" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/openclaw-optimizer", "agentPageUrl": "https://openagent3.xyz/skills/openclaw-optimizer/agent", "manifestUrl": "https://openagent3.xyz/skills/openclaw-optimizer/agent.json", "briefUrl": "https://openagent3.xyz/skills/openclaw-optimizer/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "OpenClaw Optimizer", "body": "Aligned with: OpenClaw v2026.3.8 | Skill v1.19.0 | Updated: 2026-03-09 | CLI-first advisor\n\nOptimize and troubleshoot OpenClaw workspaces: cost-aware routing, provider configuration, context discipline, lean automation, multi-agent architectures, and error resolution.\n\nReference files (load when needed):\n\nreferences/providers.md — all 40+ providers, custom provider schema, failover config\nreferences/troubleshooting.md — full error reference, 7 failure categories, GitHub issue workarounds\nreferences/cli-reference.md — complete CLI command reference\nreferences/identity-optimizer.md — agent identity/personality audit checklist, file roles, walkthrough workflow" }, { "title": "Version Awareness", "body": "This skill tracks OpenClaw releases via two mechanisms:\n\nGitHub Actions — daily workflow checks for new releases, opens an issue on drift, auto-closes when resolved\nRuntime check — lightweight cached version comparison at session start" }, { "title": "Runtime Check (once per session)", "body": "python3 ~/.claude/skills/openclaw-optimizer/scripts/version-check.py --status\n\nCURRENT → note the version and proceed.\nSTALE → inform the user: \"OpenClaw v is available (skill is at v). Run update-skill.sh to review what changed.\"\nUNCHECKED → note \"Version check unavailable (offline)\" and proceed." }, { "title": "Update Workflow (user-initiated, never automatic)", "body": "# Show drift report, changelog, and affected sections\nbash ~/.claude/skills/openclaw-optimizer/scripts/update-skill.sh\n\n# After updating content in SKILL.md and references/:\nbash ~/.claude/skills/openclaw-optimizer/scripts/update-skill.sh --apply # bump versions\nbash ~/.claude/skills/openclaw-optimizer/scripts/update-skill.sh --commit # bump + commit + push\n\nUpdates are deliberate — this skill never auto-modifies its own content or pushes to git without explicit user action." }, { "title": "Quick Start (copy/paste prompts)", "body": "Full audit (safe, no changes):\n\nAudit my OpenClaw setup for cost, reliability, and context bloat. Prioritized plan with rollback. Do NOT apply changes.\n\nTroubleshoot a specific problem:\n\n[Describe your symptom or paste the error message]. Diagnose it and give me the exact fix.\n\nAdd or configure a provider:\n\nAdd [provider name] as a model provider. Walk me through the CLI steps and show me the exact config before applying.\n\nModel routing optimization:\n\nPropose a tiered routing plan: cheap for heartbeats/cron, mid for daily tasks, premium for coding/reasoning. Exact config + rollback. Do NOT apply.\n\nSilent cron job:\n\nCreate a cron job that runs [task] every [interval]. Isolated session, NO_REPLY on nothing-to-do. Show me the command first.\n\nAudit agent personality & identity:\n\nAudit my agent's personality and identity files. Check for conflicts, bloat, and bad practices. Walk me through improvements." }, { "title": "Safety Contract (non-negotiable)", "body": "This skill is advisory by default — not an autonomous control-plane.\nNever mutate config (config.apply, config.patch), cron jobs, or persistent settings without explicit user approval.\nBefore any approved change: show (1) exact CLI command or config patch, (2) expected impact, (3) rollback command.\nIf an optimization reduces monitoring coverage, present Options A/B/C and require the user to choose." }, { "title": "Backup Strategy", "body": "Four backup layers exist — don't stack manual backups on top unnecessarily:\n\nLayerWhatRetentionWhen It's EnoughCLI rolling .bakAuto-created on every config set, models set, cron editRolling (overwritten each write)Single-command undoNightly GitHub backupFull config committed by cron job (3 AM)Git history (unlimited)Any rollback to a previous day's stateopenclaw backup createLocal state archive with manifest verification (v2026.3.8+)Until manually deletedPre-upgrade safety net; use openclaw backup verify to validateManual dated backupcp .YYYY-MM-DD-Until next nightly covers it, then deleteMajor upgrades, multi-file restructuring, direct JSON edits\n\nRule: 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." }, { "title": "1. Model Providers", "body": "40+ providers supported. For full docs (auth commands, config schemas, all model names, custom provider setup): read references/providers.md\n\nQuick lookup — slug, auth env, primary model format:\n\nProviderSlugAuth EnvModel FormatAnthropicanthropicANTHROPIC_API_KEYanthropic/claude-opus-4-6OpenAI (API key)openaiOPENAI_API_KEYopenai/gpt-5.4OpenAI Codex (subscription)openai-codexChatGPT OAuthopenai-codex/gpt-5.4Google GeminigoogleGEMINI_API_KEYgoogle/gemini-3.1-pro-preview\n\nWARNING — Provider Bans (Mar 2026):\nGoogle: 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.\nAnthropic: 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.\nGeneral: 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.\n\n| Mistral | mistral | MISTRAL_API_KEY | mistral/mistral-large-latest |\n| Groq | groq | GROQ_API_KEY | groq/ |\n| xAI | xai | XAI_API_KEY | xai/grok-code-fast-1 |\n| OpenRouter | openrouter | OPENROUTER_API_KEY | openrouter/anthropic/claude-sonnet-4-5 |\n| Bedrock | amazon-bedrock | AWS env chain | amazon-bedrock/us.anthropic.claude-opus-4-6-v1:0 |\n| Kilo Gateway | kilocode | KILOCODE_API_KEY | kilocode/anthropic/claude-opus-4.6 |\n| Moonshot/Kimi | moonshot | MOONSHOT_API_KEY | moonshot/kimi-k2.5 |\n| Kimi Coding | kimi-coding | KIMI_API_KEY | kimi-coding/k2p5 |\n| Z.AI / GLM | zai | ZAI_API_KEY | zai/glm-5 |\n| MiniMax | minimax | MINIMAX_API_KEY | minimax/MiniMax-M2.5-highspeed |\n| MiniMax VL-01 | minimax-portal | MINIMAX_API_KEY | minimax-portal/MiniMax-VL-01 |\n| Venice AI | venice | VENICE_API_KEY | venice/kimi-k2-5 |\n| Hugging Face | huggingface | HF_TOKEN | huggingface/deepseek-ai/DeepSeek-R1 |\n| Synthetic | synthetic | SYNTHETIC_API_KEY | synthetic/hf:MiniMaxAI/MiniMax-M2.1 |\n| Together AI | together | TOGETHER_API_KEY | together/moonshotai/Kimi-K2.5 |\n| Cerebras | cerebras | CEREBRAS_API_KEY | cerebras/zai-glm-4.7 |\n| Ollama (local) | ollama | OLLAMA_API_KEY (any) | ollama/llama3.3 |\n| vLLM (local) | vllm | VLLM_API_KEY (any) | vllm/ |\n\nAdd a provider (API key):\n\nopenclaw onboard --auth-choice -api-key\nopenclaw models auth login --provider \nopenclaw models set \n\nAdd a provider (OAuth / subscription):\n\nopenclaw onboard --auth-choice openai-codex # ChatGPT subscription\nopenclaw models auth login --provider openai-codex\nopenclaw models set openai-codex/gpt-5.4" }, { "title": "OAuth Providers (Subscription-Based Access)", "body": "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.\n\nCurrently supported OAuth providers:\n\nProviderSlugSubscription RequiredTop ModelsOpenAI Codexopenai-codexChatGPT Plus ($20/mo) or Pro ($200/mo)gpt-5.4, gpt-5.3-codex, codex-mini-latestGitHub Copilotgithub-copilotCopilot subscriptiongithub-copilot/gpt-4o\n\nOpenAI Codex setup (full walkthrough):\n\n# 1. Authenticate (opens browser for ChatGPT sign-in)\nopenclaw models auth login --provider openai-codex\n# → Prints a URL. Open it in a browser, sign in to ChatGPT, paste redirect URL back.\n\n# 3. Verify auth\nopenclaw models status --probe --probe-provider openai-codex\n\n# 4. Set as primary OR add to fallback chain\nopenclaw models set openai-codex/gpt-5.4 # as primary\nopenclaw models fallbacks add openai-codex/gpt-5.4 # or as fallback\n\n# 5. Restart gateway\nlaunchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway # macOS LaunchAgent\n\nHeadless / 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.\n\nAvailable Codex models:\n\nModelPlanNotesopenai-codex/gpt-5.4Plus, Pro, BusinessLatest (Mar 2026), 1,050,000-token context, 128K max tokensopenai-codex/gpt-5.3-codexPlus, Pro, BusinessPrevious flagship, most capable coding modelopenai-codex/gpt-5.3-codex-sparkPro onlyResearch preview, low-latencyopenai-codex/gpt-5.2-codexPlus, ProPrevious gen, stableopenai-codex/codex-mini-latestPlus, ProLightweight, fast, cheapest\n\nUsage limits (per 5-hour window):\n\nPlus ($20/mo): 30–150 messages\nPro ($200/mo): 300–1,500 messages\nExtra credits purchasable when limits are hit\n\nGotchas:\n\nNo embeddings. Codex OAuth does NOT grant access to OpenAI embeddings. You still need a separate OPENAI_API_KEY for text-embedding-3-small etc.\nToken refresh is automatic — active sessions continue without re-login. Credentials stored in ~/.openclaw/credentials/oauth.json.\nDon'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.\n\"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.\nDual-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.\nCommunity 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." }, { "title": "Provider Removal Checklist", "body": "Removing a provider requires cleaning 6 locations — config unset alone is not enough:\n\nmodels.providers. in openclaw.json — openclaw config unset models.providers.\nauth.profiles.:* in openclaw.json — must edit JSON directly (colons in keys break config unset)\nprofiles dict in ~/.openclaw/agents/main/agent/auth-profiles.json — edit with python3/jq\nagents.defaults.models. aliases in openclaw.json — openclaw config unset each alias\nplugins.entries.-auth in openclaw.json — openclaw config unset plugins.entries.-auth\nlastGood. and usageStats.:* in auth-profiles.json — edit directly\n\nFor providers with LaunchAgent env vars (Ollama, etc.), also clean:\n7. launchctl unsetenv — session-level env persists independently of plist\n8. PlistBuddy delete from ~/Library/LaunchAgents/ai.openclaw.gateway.plist\n9. launchctl bootout + launchctl bootstrap to pick up the clean plist (kickstart alone doesn't reload env from plist)\n\nKnown 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.\n\nOllama for memory embeddings (v2026.3.2+):\n\nopenclaw config set memorySearch.provider ollama\nopenclaw config set memorySearch.fallback ollama\n\nRuns memory search embeddings locally — no external API calls. Honors models.providers.ollama settings.\n\nCustom OpenAI-compatible provider (LM Studio, LiteLLM, etc.): See references/providers.md" }, { "title": "Tiered Routing (50–95% cost reduction)", "body": "TierModelsUse CasesT1 Cheapzai/glm-5, google/gemini-3-flash-preview, google/gemini-3.1-flash-lite-preview, synthetic/hf:deepseek-ai/DeepSeek-V3.2Heartbeats, simple checks, greetings, cronT2 Midmoonshot/kimi-k2.5, minimax/MiniMax-M2.5-highspeedDaily chat, Q&A, calendar, schedulingT3 Smartanthropic/claude-sonnet-4-5, openai/gpt-5.4, openai-codex/gpt-5.4 (subscription)Code, refactors, researchT4 Premiumanthropic/claude-opus-4-6, openai/gpt-5.2Complex reasoning, orchestration\n\nModel preference by task:\n\nTaskModelWhyHeartbeats / cronzai/glm-5Cheapest; reliable structured outputCalendar / schedulingmoonshot/kimi-k2.5Community #1 for date/time reasoningCoding / refactoringanthropic/claude-sonnet-4-5 or openai-codex/gpt-5.4Sonnet: community #1 for code quality; Codex: flat-rate via subscriptionAgent orchestrationanthropic/claude-opus-4-6Best multi-step reasoningLong-context tasksgoogle/gemini-3-flash-preview or openai-codex/gpt-5.4Gemini: 1M token window; Codex 5.4: 1.05M tokensSubscription-capped codingopenai-codex/gpt-5.4Fixed cost via ChatGPT Plus/Pro; no per-token billingPrivacy-sensitivevenice/kimi-k2-5 or OllamaNever logged/storedUltra-cheap batchgoogle/gemini-3.1-flash-lite-previewMinimal cost; good for lightweight cron/heartbeat\n\nKey rules:\n\nNever switch models mid-conversation — destroys Anthropic prompt cache\nUse anthropic direct (not through proxies) to preserve caching for Opus/Sonnet\nSwitch only at session boundaries (/new)" }, { "title": "Built-in Model Aliases (v2026.3.7+)", "body": "AliasResolves Toopusanthropic/claude-opus-4-6sonnetanthropic/claude-sonnet-4-6gptopenai/gpt-5.4gpt-miniopenai/gpt-5-minigeminigoogle/gemini-3.1-pro-previewgemini-flashgoogle/gemini-3-flash-previewgemini-flash-litegoogle/gemini-3.1-flash-lite-preview" }, { "title": "Thinking Levels (v2026.3.1+)", "body": "LevelBehaviorBest ForoffNo extended thinkingSimple queries, heartbeatsminimalLight reasoning (~1.1s)Routine tasks; community tip: set as default to halve latencylowStandard reasoningDefault for non-Claude-4.6 reasoning modelsmedium / highDeeper reasoningComplex tasksxhigh\"Ultrathink+\"GPT-5.2 + Codex models onlyadaptiveProvider-managedDefault for Claude 4.6 — auto-scales reasoning to task complexity\n\nopenclaw config set agents.defaults.thinkingDefault adaptive # recommended for Claude 4.6\nopenclaw config set agents.defaults.thinkingDefault minimal # cost-saver for routine workloads\n\nIn-chat: /think low · /think adaptive · /think off" }, { "title": "Per-Agent Config", "body": "openclaw models set anthropic/claude-opus-4-6 # set global primary\nopenclaw config set agents.defaults.model.primary anthropic/claude-opus-4-6\nopenclaw models fallbacks add openrouter/anthropic/claude-sonnet-4-5\n\n{\n agents: {\n list: [\n { id: \"main\", model: \"anthropic/claude-opus-4-6\", heartbeat: { every: \"30m\" } },\n { id: \"ops\", model: { primary: \"anthropic/claude-sonnet-4-5\", fallbacks: [\"zai/glm-5\"] },\n tools: { profile: \"minimal\" } },\n ],\n defaults: {\n model: { primary: \"anthropic/claude-opus-4-6\", fallbacks: [\"minimax/MiniMax-M2.5-highspeed\"] },\n thinkingDefault: \"adaptive\",\n timeoutSeconds: 600,\n contextTokens: 200000,\n maxConcurrent: 3,\n params: { cacheRetention: \"long\" },\n },\n },\n}\n\nIn-chat model switch (no restart): /model list → /model anthropic/claude-sonnet-4-5" }, { "title": "Session Pruning (v2026.3.1+)", "body": "Automatically trims stale tool results from conversation history to preserve cache and reclaim context:\n\n{\n agents: { defaults: { contextPruning: {\n mode: \"cache-ttl\", // \"off\" (default) | \"cache-ttl\"\n ttl: \"5m\",\n keepLastAssistants: 3,\n softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },\n hardClear: { enabled: true },\n } } },\n}\n\nAnthropic smart defaults auto-enable cache-ttl pruning when using API key auth with heartbeat enabled." }, { "title": "3. Context Management", "body": "What burns tokens: System prompt (5–10K tokens/call) + bootstrap files + conversation history. Bootstrap files injected on every turn (source: docs.openclaw.ai/concepts/system-prompt): AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md (first-run only), plus MEMORY.md and/or memory.md when present. Daily memory/*.md files are NOT auto-injected (on-demand via memory tools). Bootstrap cap: 150K chars total, 20K per file (both configurable).\n\nMEMORY.md warning (from docs): \"Keep them concise — especially MEMORY.md, which can grow over time and lead to unexpectedly high context usage and more frequent compaction.\" MEMORY.md is the most common source of bootstrap bloat. Unlike AGENTS.md or SOUL.md which users actively edit, MEMORY.md tends to grow unchecked as the agent appends to it.\n\nCheck context: /status · /context list · /context detail · /usage tokens · /usage cost" }, { "title": "Prompt Modes", "body": "ModeBootstrap Files LoadedUse Casefull (default)All — AGENTS, SOUL, TOOLS, IDENTITY, USER, HEARTBEAT, MEMORYMain interactive sessionsminimal (sub-agents)AGENTS.md + TOOLS.md onlySub-agent spawns — no SOUL, IDENTITY, USER, HEARTBEAT, MEMORYnoneBase identity line onlyBare-minimum sessions" }, { "title": "Light Bootstrap (v2026.3.1+)", "body": "Skip all workspace bootstrap files for automated runs:\n\nopenclaw cron add --light-context --cron \"*/30 * * * *\" --message \"Quick check\"\n\n{\n agents: { defaults: { heartbeat: {\n lightContext: true, // only loads HEARTBEAT.md, skips all other bootstrap files\n } } },\n}\n\nMassive token savings for heartbeats and cron — eliminates 5-10K tokens/call of bootstrap overhead." }, { "title": "Bootstrap Truncation Warning (v2026.3.7+)", "body": "openclaw config set agents.defaults.bootstrapPromptTruncationWarning once # off | once | always\n\nWhen a bootstrap file exceeds bootstrapMaxChars (default 20K), the agent receives a warning. Set to always during identity audits to catch truncated files." }, { "title": "Compaction Config", "body": "# Manual: /compact [focus instructions]\n# Auto: triggers near context limit — count visible in /status\n\nopenclaw config set agents.defaults.compaction.mode safeguard\nopenclaw config set agents.defaults.compaction.reserveTokensFloor 32000\nopenclaw config set agents.defaults.contextTokens 100000\nopenclaw config set agents.defaults.compaction.model google/gemini-3-flash-preview # cheaper compaction (v2026.3.7+)\nopenclaw config set agents.defaults.compaction.recentTurnsPreserve 4 # quality-guard (v2026.3.7+)\n\n{\n agents: { defaults: { compaction: {\n mode: \"safeguard\",\n model: \"google/gemini-3-flash-preview\", // route compaction through a cheaper model\n reserveTokensFloor: 32000,\n recentTurnsPreserve: 4, // keep last N turns intact during compaction\n postCompactionSections: [\"Session Startup\", \"Red Lines\"], // AGENTS.md sections re-injected after compaction\n memoryFlush: {\n enabled: true,\n prompt: \"Write lasting notes to memory/YYYY-MM-DD.md; reply NO_REPLY if nothing to store.\",\n },\n }, contextTokens: 100000 } },\n}\n\nKnown bug — memory flush threshold gap (Issue #25880): Set reserveTokensFloor equal to reserveTokens (both 62500) to fix compaction firing before flush completes.\n\nKnown bug — compaction timeout (Issue #38233): Both /compact and auto compaction can timeout at ~300s with openai-codex/gpt-5.3-codex, freezing the session. Fix: override compaction model to google/gemini-3-flash-preview with thinking: \"off\". Tune: maxHistoryShare: 0.6, reserveTokensFloor: 40000, maxAttempts: 3." }, { "title": "Context Engine Plugin (v2026.3.7+)", "body": "Replace the built-in context assembly pipeline with a custom plugin:\n\n{\n plugins: { slots: { contextEngine: \"lossless-claw\" } }, // default: \"legacy\" (built-in)\n}\n\nContext Engine plugins get full lifecycle hooks: bootstrap, ingest, assemble, compact, afterTurn, prepareSubagentSpawn, onSubagentEnded. This enables alternative context management strategies (lossless context, semantic chunking, etc.) without modifying OpenClaw core." }, { "title": "Bootstrap File Size Targets (optimization recommendations)", "body": "These are optimization targets for keeping context lean, not hard limits. All files are subject to bootstrapMaxChars (default 20K) and bootstrapTotalMaxChars (default 150K).\n\nFileTarget SizePurposeInjected?SOUL.md< 1K tokens (~4K chars)Personality + absolute constraintsAlways (main + full prompt mode)AGENTS.md< 2K tokens (~8K chars)Workflows, rules, operating proceduresAlways (main + sub-agents)TOOLS.md< 2K tokens (~8K chars)Tool-specific notes, local conventionsAlways (main + sub-agents)IDENTITY.md< 500 tokens (~2K chars)Name, vibe, emoji, presentationAlways (main only)USER.md< 1K tokens (~4K chars)User profile, preferences, contextAlways (main only)HEARTBEAT.md< 200 tokens (~800 chars)Heartbeat checklist (keep minimal)Always (main only); skipped with lightContextMEMORY.md< 5K tokens (~20K chars)Curated long-term facts ONLYAlways in main sessions (auto-injected when present)\n\nCritical: MEMORY.md is auto-injected on every turn in main sessions, NOT loaded on-demand. It burns tokens continuously. Keep it as small as possible with only curated facts. Operational protocols belong in AGENTS.md. Tool notes belong in TOOLS.md." }, { "title": "Bootstrap Content Placement (What Goes Where)", "body": "Users commonly dump all content into SOUL.md because it feels like \"who the agent is.\" This bloats the file (burns tokens every turn) and confuses lighter models that can't prioritize across a noisy instruction set. Place content in the correct file:\n\nContent TypeCorrect FileCommon MistakePersonality, voice, humor, constraintsSOUL.md-Protocols, workflows, checklists, operational rulesAGENTS.mdDumping in SOUL.mdUser bio, preferences, working hours, communication styleUSER.mdDuplicating in SOUL.mdTool configs, API templates, channel IDs, env varsTOOLS.mdScattering in AGENTS.mdCurated long-term facts (lean)MEMORY.mdGrowing uncheckedProactivity rules, initiative behaviorAGENTS.mdPutting in SOUL.md\n\nCross-file duplication burns tokens silently. If the same protocol appears in both SOUL.md and AGENTS.md, it's injected twice on every turn. Deduplicate aggressively — pick one canonical location.\n\nStale model references are silent saboteurs. When you change models via CLI (openclaw models set), update any AGENTS.md sections that reference specific model names (e.g., Model Selection, Sub-Agent defaults). The agent follows bootstrap instructions and may try to use models that are no longer configured.\n\nPersistence stack: SOUL.md → AGENTS.md → TOOLS.md → IDENTITY.md → USER.md → MEMORY.md (all auto-injected in main sessions) → memory/YYYY-MM-DD.md (on-demand via memory tools) → conversation-state.md → ACTIVE-TASK.md" }, { "title": "Session Maintenance", "body": "openclaw config set session.maintenance.mode enforce\nopenclaw config set session.maintenance.maxDiskBytes 500mb\nopenclaw sessions cleanup --dry-run # preview\nopenclaw sessions cleanup --enforce # apply\nopenclaw sessions cleanup --fix-missing # prune store entries whose transcript files are missing (v2026.2.26+)" }, { "title": "Cron Job Schema (key fields)", "body": "{\n \"jobId\": \"daily-brief\", \"name\": \"Morning Briefing\", \"enabled\": true,\n \"agentId\": \"main\",\n \"schedule\": { \"kind\": \"cron\", \"expr\": \"0 8 * * *\", \"tz\": \"America/New_York\" },\n \"sessionTarget\": \"isolated\",\n \"payload\": { \"kind\": \"agentTurn\", \"message\": \"Morning briefing.\", \"model\": \"anthropic/claude-sonnet-4-5\", \"timeoutSeconds\": 300 },\n \"delivery\": { \"mode\": \"announce\", \"channel\": \"telegram\", \"to\": \"\" },\n \"lightContext\": true\n}\n\nsessionTarget: \"isolated\" (recommended — fresh session) | \"main\" (injects as systemEvent)\npayload.kind: \"agentTurn\" (isolated) | \"systemEvent\" (main session)\ndelivery.mode: \"announce\" | \"webhook\" | \"none\"\nlightContext: true skips all workspace bootstrap files — massive token savings for automated runs (v2026.3.1+)" }, { "title": "CLI", "body": "openclaw cron add --cron \"0 9 * * *\" --message \"Daily report\" --agent main --announce --channel slack --to \"channel:CXXX\"\nopenclaw cron add --cron \"0 9 * * *\" --message \"Quick check\" --light-context # skip bootstrap files\nopenclaw cron add --at \"2026-03-01T08:00:00\" --message \"One-time task\" --keep-after-run\nopenclaw cron add --cron \"0 9 * * *\" --exact # no stagger jitter\nopenclaw cron run # test immediately (--force bypasses not-due)\nopenclaw cron list / status / runs\nopenclaw cron edit [flags] # patch fields: --cron, --message, --model, --name, --tz, etc.\nopenclaw cron enable/disable \nopenclaw cron rm \nopenclaw config set cron.sessionRetention 24h\nopenclaw config set cron.maxConcurrentRuns 1 # circuit breaker" }, { "title": "Cron Defer-While-Active (v2026.3.7+)", "body": "Skip main-session cron jobs when the user is actively chatting:\n\nopenclaw config set cron.deferWhileActive.quietMs 300000 # defer if user active within last 5 minutes\n\nPrevents cron jobs from interrupting active conversations. Only affects sessionTarget: \"main\" jobs; isolated jobs always run." }, { "title": "Cron Restart Staggering (v2026.3.8+)", "body": "On gateway startup, missed cron jobs are staggered to prevent gateway starvation. Top-of-hour cron expressions get up to 5 minutes of deterministic stagger. Use --exact or schedule.staggerMs: 0 to disable." }, { "title": "Silent Patterns", "body": "NO_REPLY — agent outputs this literal string when nothing to report; system suppresses delivery entirely.\nHEARTBEAT_OK — heartbeat token; reply ≤300 chars after stripping it → silently dropped.\n\n{\n agents: { defaults: { heartbeat: {\n every: \"30m\",\n target: \"last\",\n ackMaxChars: 300,\n directPolicy: \"allow\",\n lightContext: false, // set true to skip bootstrap files (v2026.3.1+)\n activeHours: { start: \"08:00\", end: \"22:00\", timezone: \"America/New_York\" },\n } } },\n}\n\nv2026.2.25 BREAKING: The heartbeat DM toggle was replaced with directPolicy. Default is now allow. If you had DMs blocked in v2026.2.24, explicitly set agents.defaults.heartbeat.directPolicy: \"block\" (or per-agent via agents.list[].heartbeat.directPolicy).\n\nCost trap: 5-minute heartbeat loading full MEMORY.md = ~2.9M tokens/day. Keep heartbeat context minimal — use lightContext: true or extend intervals.\n\nRedundant cron jobs: The built-in openclaw memory indexes sessions natively. Custom session archiver cron jobs that convert .jsonl to markdown for a separate RAG database are likely redundant. Check whether any cron job feeds a custom system that duplicates built-in functionality before assuming it's needed.\n\nKnown bugs: Cron current-day skip (Issue #25902) — restart the gateway with launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway to recompute (do NOT use openclaw gateway restart — it causes duplicate processes; see Section 10). Cron announce → Telegram failure (Issue #25906) — switch to directMessage mode.\n\nv2026.2.25 fixes: Cron model override failures now auto-recover — if an isolated job's payload.model is no longer allowlisted, it gracefully falls back to the default model instead of failing the job. Cron announce duplicate sends are also fixed (duplicate guard tracks attempted vs confirmed delivery). Multi-account cron routing now properly honors delivery.accountId." }, { "title": "5. Skills & Plugins", "body": "metadata.openclaw.requires — gates skill visibility:\n\nmetadata:\n openclaw:\n requires:\n bins: [\"ffmpeg\"] # ALL must exist on PATH\n anyBins: [\"gh\", \"hub\"] # AT LEAST ONE must exist\n env: [\"GITHUB_TOKEN\"] # env vars that must be set\n config: [\"browser.enabled\"]\n os: [\"darwin\", \"linux\"]\n\ndisable-model-invocation: true — removes skill from model's tool list; user can still invoke manually. Use for high-impact or security-sensitive skills.\n\nSkills directory: ~/.openclaw/workspace/skills/ — this is the filesystem path where all skills are stored. Each skill lives in its own subdirectory (e.g., ~/.openclaw/workspace/skills/my-skill/SKILL.md). When manually installing or copying skills, always use this path — not ~/.openclaw/skills/.\n\nClawHub:\n\nnpx clawhub install # install\nclawhub update --all # update all\nopenclaw skills list --eligible # what's loaded\nopenclaw skills check # validate requirements\n\nSecurity: Before installing any skill, read its SKILL.md manually. Community scans found 341+ malicious skills (reverse shells, credential exfiltration, Atomic Stealer, crypto miners). New accounts with popular skills = red flag. The #1 most-downloaded ClawHub skill was confirmed malware.\n\nSession watcher: Skills snapshot at session start. If skills.load.watch is disabled, start a new session after installing." }, { "title": "Plugin Slots (v2026.3.7+)", "body": "{\n plugins: {\n slots: {\n contextEngine: \"legacy\", // or custom plugin id (e.g., \"lossless-claw\")\n memory: \"memory-core\", // or \"none\" to disable memory entirely\n },\n entries: {\n \"\": {\n enabled: true,\n hooks: { allowPromptInjection: false }, // block plugin from mutating system prompt\n },\n },\n },\n}" }, { "title": "6. Multi-Agent & Sub-Agent Architecture", "body": "/subagents spawn ops \"Audit logs from last 24h\" # via chat\n\n// sessions_spawn tool (programmatic)\n{ \"task\": \"Audit logs\", \"agentId\": \"ops\", \"model\": \"anthropic/claude-sonnet-4-5\",\n \"thinking\": \"low\", \"runTimeoutSeconds\": 300, \"mode\": \"minimal\",\n \"attachments\": [\"/path/to/file.md\"] } // inline file attachments (v2026.3.2+)\n\n// Nesting config\n{ agents: { defaults: { subagents: {\n maxSpawnDepth: 2, // 0=off; 1=spawn; 2=orchestrator\n maxConcurrency: 8,\n maxChildrenPerAgent: 5,\n model: \"anthropic/claude-sonnet-4-5\", // default model for spawned sub-agents\n runTimeoutSeconds: 900,\n} } } }\n\nCommunity pattern: Orchestrator (opus-4-6) → Code sub-agent (sonnet-4-5) → Research sub-agent (kimi-k2.5) → Cron/monitoring (zai/glm-5, isolated)\n\nCommunity insight — single agent with skills beats multiple agents for most use cases. Multiple agent instances multiply context costs (each agent loads its own bootstrap). Use one agent with good skills instead, and only split into multiple agents when you need genuinely different identity/personality/permissions (e.g., a public-facing agent vs an ops agent).\n\nSandbox isolation:\n\n{ agents: { list: [{ id: \"untrusted\", sandbox: { mode: \"docker\" },\n tools: { profile: \"minimal\", deny: [\"exec\", \"browser\"] } }] } }" }, { "title": "ACP Dispatch (v2026.3.2+)", "body": "Agent Client Protocol enables OpenClaw to spawn external coding harnesses (Claude Code, Codex CLI, Gemini CLI, OpenCode) as sub-agents:\n\n{\n acp: {\n enabled: true,\n dispatch: { enabled: true }, // default true since v2026.3.2\n defaultAgent: \"codex\",\n allowedAgents: [\"claude\", \"codex\", \"opencode\", \"gemini\", \"kimi\"],\n maxConcurrentSessions: 8,\n },\n}\n\nIn-chat: /acp spawn · /acp status · /acp steer · /acp close" }, { "title": "7. High-ROI Optimization Levers", "body": "LeverImpactHowTiered model routing50–95% cost reductionT1 for cron/heartbeat, T4 only for orchestrationPrompt caching60–90% input token reductionKeep system prompt stable; use anthropic directBootstrap file discipline2K–10K tokens/call savedSOUL.md <1K, AGENTS.md <2K, MEMORY.md <5KLight bootstrap for cron/heartbeat5-10K tokens/call savedlightContext: true on heartbeat; --light-context on cronAdaptive thinkingAuto-scales token usethinkingDefault: adaptive for Claude 4.6; minimal for routineSession pruningReclaims stale contextcontextPruning.mode: cache-ttl with AnthropicSilent cron (NO_REPLY)Eliminates delivery tokensInstruct: \"Reply NO_REPLY if nothing actionable\"Compaction tuningPrevents overflow disasterssafeguard mode, reserveTokensFloor: 32000Cheaper compaction modelReduces compaction costRoute compaction through gemini-3-flash-previewSession maintenancePrevents disk/perf degradationmode: enforce, maxDiskBytes: 500mbBatch heartbeat checks10x fewer API callsOne heartbeat for 10 checks > 10 cron jobsIsolated cron sessionsZero context contaminationsessionTarget: \"isolated\" on all cron jobsSingle agent with skillsUp to 80% cost reductionOne agent + skills beats multiple agent instancesGateway securityPrevents exposuregateway.bind: loopback; Tailscale for remoteNever switch mid-sessionPreserves prompt cacheOnly switch model at /new boundariesBackup before upgradesPre-change safety netopenclaw backup create before openclaw update" }, { "title": "8. CLI Reference", "body": "Best practice (v2026.2.25+): Before editing config or asking config-field questions, have the agent call the config.schema tool in-chat. This returns the current schema with valid keys, types, and defaults — avoids guessing or using stale field names. Note: this is an agent in-chat tool, NOT a CLI command.\n\nMost common commands:\n\nopenclaw doctor --fix # auto-fix config issues\nopenclaw gateway status # check runtime + RPC probe\nopenclaw models set \nopenclaw models status --probe\nopenclaw cron run # test a cron job immediately\nopenclaw sessions cleanup --dry-run\nopenclaw sessions cleanup --fix-missing # prune entries with missing transcripts (v2026.2.26+)\nopenclaw config validate [--json] # validate config against schema (v2026.3.2+)\nopenclaw config file # print active config file path (v2026.3.1+)\nopenclaw backup create [--only-config] # local state archive (v2026.3.8+)\nopenclaw backup verify # validate backup integrity (v2026.3.8+)\nopenclaw update\nopenclaw security audit # post-upgrade check\nopenclaw secrets audit # scan bootstrap files for hardcoded secrets (v2026.2.26+)\nopenclaw secrets configure # configure external secrets (v2026.2.26+)\nopenclaw secrets apply # apply secrets with strict target-path validation (v2026.2.26+)\nopenclaw agents bindings # list account-scoped agent route bindings (v2026.2.26+)\nopenclaw agents bind # bind agent to channel account (v2026.2.26+)\nopenclaw agents unbind # unbind agent from channel account (v2026.2.26+)\n\nopenclaw onboard --reset scope change (v2026.2.26): Default reset scope is now config+creds+sessions. Workspace deletion (bootstrap files, skills, memory) now requires --reset-scope full. Do NOT run openclaw onboard --reset without specifying --reset-scope explicitly — the default no longer wipes the workspace." }, { "title": "In-Chat Commands (v2026.3.x)", "body": "/session idle manage thread inactivity auto-unfocus\n/session max-age manage hard max-age for thread bindings\n/usage cost local cost summary from session logs\n/usage tokens show per-reply token usage\n/export-session [path] export current session to HTML (/export alias)\n/steer steer a running sub-agent immediately (/tell alias)\n/kill abort one or all running sub-agents\n/think off | minimal | low | medium | high | xhigh | adaptive\n/model switch model without restart\n/compact [instructions] manual compaction with optional focus\n/context detail per-file, per-tool, per-skill token breakdown\n/acp spawn|status|steer|close ACP session control\n/check-updates quick update summary" }, { "title": "Environment Variables (v2026.3.x)", "body": "OPENCLAW_LOG_LEVEL= # override log level: silent|fatal|error|warn|info|debug|trace\nOPENCLAW_DIAGNOSTICS= # targeted debug logs (e.g., \"telegram.*\" or \"*\" for all)\nOPENCLAW_SHELL= # set across shell-like runtimes (exec, acp, tui-local)\nOPENCLAW_THEME=light|dark # TUI theme override (v2026.3.8+)\n\nGateway restart (macOS LaunchAgent):\n\n# SAFE restart — single atomic operation, no duplicate processes\nlaunchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway\n\n# DO NOT use `openclaw gateway restart` — it races with KeepAlive and spawns\n# duplicate processes that loop \"Port already in use\" every ~10s at 100%+ CPU.\n\n# Recovery if duplicates already exist:\nlaunchctl bootout gui/$(id -u)/ai.openclaw.gateway # stop launchd service + kill managed process\nkill # kill orphans\nlaunchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist # re-register + start clean\n\nFull CLI reference (all commands, flags, in-chat commands): Read references/cli-reference.md" }, { "title": "9. Ops Hygiene Checklist", "body": "Daily:\n\nopenclaw health --json via cron (→ HEARTBEAT_OK if clean)\nclawhub whoami to verify ClawHub auth\nToken budget check (cost-sensitive providers)\n\nWeekly:\n\nopenclaw update --dry-run → review → openclaw update\nclawhub update --all --dry-run → review → clawhub update --all\nCurate MEMORY.md — archive old daily logs, promote key insights\nopenclaw sessions cleanup --dry-run → openclaw sessions cleanup\nopenclaw cron status — check for errors\nClean stale backup files: find ~/.openclaw -name \"*.bak.*\" -mtime +7 -not -name \"*.bak\" | xargs rm -v (preserves CLI's rolling .bak files, removes old named/dated backups)\n\nQuarterly:\n\nReview custom scripts (scripts/) for redundancy with built-in OpenClaw features. Users often build custom solutions (RAG pipelines, session archivers, memory indexers) that become redundant when OpenClaw adds equivalent built-in functionality. Check whether each script and its associated cron job still serves a purpose that the platform doesn't already handle.\n\nBefore/After Updates:\n\nBefore update: openclaw backup create (pre-change safety net — v2026.3.8+)\nAfter update: openclaw doctor --fix (handles config migrations automatically)\nAfter update: openclaw config validate --json (catch fail-closed config errors — v2026.3.2+)\nv2026.2.23 breaking change: allowPrivateNetwork → dangerouslyAllowPrivateNetwork — auto-fixed by doctor\nManual backup only needed for major upgrades or multi-file restructuring (see Backup Strategy above)\n\nv2026.3.x Breaking Changes:\n\ngateway.auth.mode required (v2026.3.7): When both gateway.auth.token AND gateway.auth.password are configured, you must set gateway.auth.mode to \"token\" or \"password\". Gateway will not start without this.\ntools.profile defaults to \"messaging\" (v2026.3.2): New installs no longer start with coding/system tools. Existing installs are unaffected.\nACP dispatch defaults to enabled (v2026.3.2): Set acp.dispatch.enabled: false to disable.\nConfig fail-closed (v2026.3.2+): Invalid configs cause gateway startup failure instead of silently falling back to permissive defaults.\nNode.js v22.12+ enforced: Attempting to run on Node 18/20 causes immediate failure.\n\nOn Every System Assessment (mandatory data collection):\n\nopenclaw cron list + read ~/.openclaw/cron/jobs.json — capture full cron inventory: job IDs, names, schedules, model overrides (from payload.model), status, last run times\nFlag any jobs in error state — these are active problems\nFlag jobs with stale last-run times (>24h for daily jobs) — may indicate silent failures\nCheck timezone consistency — jobs using (exact) instead of named timezones may fire at wrong times\nRecord whether jobs use isolated or main session target\nMap cron schedule to day/night distribution — heavy jobs should cluster overnight\nDocument all findings in the system profile's ## Cron Jobs section before making recommendations\nWithout this data, recommendations will duplicate existing automation and waste time\n\nSecurity:\n\nopenclaw config get gateway.bind → must be loopback\nNo public port exposure — use Tailscale for remote\nAPI keys not in skill files or version control\nAudit ClawHub skills before installing — 341+ malicious skills confirmed\nCVE-2026-25253 (ClawJacked): WebSocket authentication bypass allowing one-click RCE. 42,000+ exposed instances. Patched in v2026.1.29+. Verify you are on v2026.2.26+ minimum.\nopenclaw security audit --deep for live Gateway probe" }, { "title": "10. Troubleshooting", "body": "Log file paths (macOS):\n\nError log: ~/.openclaw/logs/gateway.err.log — primary source for errors, 502s, plugin failures, tool errors\nMain log: /tmp/openclaw/openclaw-YYYY-MM-DD.log — verbose debug output (lane events, session activity)\n\nAlways check gateway.err.log first when troubleshooting — it contains only errors and warnings, making root cause identification much faster than grepping the main log.\n\nFirst — always run this triage sequence:\n\nopenclaw status\nopenclaw gateway status # must show \"Runtime: running\" + \"RPC probe: ok\"\nopenclaw doctor\nopenclaw channels status --probe\nopenclaw config validate --json # catch config errors before restart (v2026.3.2+)\ntail -50 ~/.openclaw/logs/gateway.err.log | grep -v DEP0040 # skip Node deprecation noise\n\nQuick fix by symptom:\n\nSymptomFirst CommandMost Likely FixNo response from agentopenclaw gateway statusGateway not running or pairing pendingGateway won't startopenclaw logs --followEADDRINUSE or gateway.mode not set to local\"Port already in use\" loopps aux | grep openclaw-gatewayDuplicate processes from CLI restart vs LaunchAgent KeepAlive. Fix: launchctl bootout → kill orphans → launchctl bootstrap (see Section 8)\"Gateway start blocked: set gateway.auth.mode\"openclaw config get gateway.authBoth token and password set but gateway.auth.mode missing. Fix: openclaw config set gateway.auth.mode token (v2026.3.7 breaking change)\"unauthorized\" on Control UIlaunchctl getenv OPENCLAW_GATEWAY_TOKENRemove stale launchctl env overrideConfig file wiped on restartBack up config firstKnown bug #40410 — gateway restart can wipe openclaw.json. Use openclaw backup create before restarts.Cron job never firesopenclaw cron statusCron disabled or timezone mismatchHeartbeat always skippedopenclaw config get agents.defaults.heartbeat.activeHoursWrong timezone, outside active hours, or directPolicy set to block (v2026.2.25 changed default to allow)Cron job fails with \"model not allowlisted\"openclaw cron statusv2026.2.25+ auto-recovers by falling back to default model. On older versions: update payload.model in the job or re-add the model to the allowlist.Channel message droppedopenclaw logs --followMention required or sender not paired\"RPC probe: failed\"openclaw gateway status --deepAuth token mismatch or port conflictPost-upgrade breakageopenclaw doctor --fixAutomatic config migrationProvider 401 errorsopenclaw models status --probeToken expired or wrong key typeChrome browser won't start (Linux)openclaw browser statusSnap Chromium conflict → install Google Chrome .debSilent tool execution failureCheck modelKnown bug #40069 — agent claims tool use but no calls made. Confirmed with kimi-coding/k2p5. Switch model.Compaction freezes sessionOverride compaction modelKnown bug #38233 — /compact times out at ~300s with Codex models. Use compaction.model: google/gemini-3-flash-previewOllama stuck \"typing\" foreverSwitch to non-Ollama modelKnown bug #40434 — local Ollama models stuck via TelegramFallback doesn't escalate on outageTest fallback chainKnown bug #32533 — retries auth profiles instead of escalating to fallback providersALL providers timeout simultaneouslygrep \"delivery-recovery\" gateway.err.logNot a provider issue. Two common causes: (A) Context bloat — contextTokens unset (unlimited), payload too large for any provider to process within timeoutSeconds. Fix: set contextTokens: 100000, timeoutSeconds: 180, reserveTokensFloor: 32000. See Section 10d. (B) Event loop overload — stuck delivery-queue, skills-remote probes, Gemini OAuth cycling, too many concurrent sessions. Fix: clear delivery queue, set cron.maxConcurrentRuns: 1. See Section 10b.Delivery recovery loop (\"21 entries deferred\")ls ~/.openclaw/delivery-queue/Stuck entries (wrong channel, message too long) retry forever on every restart. Move to ~/.openclaw/delivery-queue/failed/ to stop the loop.Ollama \"fetch failed\" (instant, ~100ms)Check gateway err log for Failed to discover Ollama modelsKnown bug: OpenClaw hardcodes 127.0.0.1:11434 for Ollama discovery (Issue #8663). On macOS, LaunchAgent processes are sandboxed and can't reach private LAN IPs like 192.168.x.x (Issue #21494). Fix: reverse SSH tunnel from Ollama machine to gateway (ssh -fN -R 127.0.0.1:11434:127.0.0.1:11434 user@gateway), set baseUrl to http://127.0.0.1:11434, add OLLAMA_HOST and OLLAMA_API_KEY to LaunchAgent env. See Section 10a below.Ollama \"Connection error\"Same as aboveSame root cause. Switching api from ollama to openai-completions changes the error message but doesn't fix it — the sandbox blocks all LAN connections.Ollama probes spike memorycurl http://host:11434/api/psSet OLLAMA_KEEP_ALIVE=0 on the Ollama machine so models unload immediately after probes. No OpenClaw config to disable probes per-provider.Gemini CLI \"API rate limit reached\"openclaw logs | grep rateGoogle OAuth crackdown (Feb 2026). Switch to API key auth. See Section 1 warning.Provider removal didn't stop probesCheck all 6 locations in Provider Removal ChecklistStale auth-profiles.json, launchctl env, or plist env vars. See Section 1.config unset fails on auth profile keysEdit JSON directlyColons in keys break the config path parser. Use python3/jq.models status --probe mass timeoutsTest individual providers with curlProbe contention — 16+ simultaneous targets saturate the event loop. Not real failures." }, { "title": "10a. Remote Ollama on macOS (Known Bug Workaround)", "body": "Problem: OpenClaw on macOS cannot connect to a remote Ollama server on the LAN. curl works, but the gateway process fails with \"fetch failed\" or \"Connection error.\" This affects all API modes (ollama and openai-completions).\n\nRoot causes (two bugs stacking):\n\nHardcoded localhost discovery (Issue #8663): OpenClaw always probes 127.0.0.1:11434 for Ollama, ignoring baseUrl.\nmacOS LaunchAgent sandbox (Issue #21494): The gateway process running under launchd gets EHOSTUNREACH for private network IPs (192.168.x.x, 10.x.x.x).\n\nFix — reverse SSH tunnel:\n\n# Run on the Ollama machine (not the gateway):\nssh -fN -R 127.0.0.1:11434:127.0.0.1:11434 user@gateway-host\n\n# On the gateway:\nopenclaw config set models.providers..baseUrl 'http://127.0.0.1:11434'\nopenclaw config set models.providers..api ollama\n\nAdd to the gateway's LaunchAgent plist:\n\nOLLAMA_HOST\nhttp://127.0.0.1:11434\nOLLAMA_API_KEY\nollama\n\nImportant: Kill any local Ollama on the gateway first — it will conflict with the tunnel on port 11434. Make the tunnel persistent with a LaunchAgent on the Ollama machine." }, { "title": "10b. Multi-Provider Timeout Storms (Event Loop Overload)", "body": "Symptom: ALL providers (Kimi, KiloCode, Google, Anthropic, etc.) timeout simultaneously within a 30-90 minute window, even though they are independent services. FailoverError: LLM request timed out. on every model in the fallback chain. May cause gateway crash/restart.\n\nRoot cause: The gateway's Node.js event loop is saturated by a pile-up of concurrent operations. Outbound HTTPS responses arrive, but the process can't process them before its own timeout timer fires. The providers are NOT down — the gateway can't handle the responses.\n\nCommon overload contributors (check all of these):\n\nStuck delivery-recovery queue — Files in ~/.openclaw/delivery-queue/ that will never succeed (wrong channel, message too long) retry on every restart and periodically. Each retry burns event loop time.\n\nDiagnose: ls ~/.openclaw/delivery-queue/*.json | wc -l and grep \"delivery-recovery\" gateway.err.log | tail -20\nFix: mv ~/.openclaw/delivery-queue/*.json ~/.openclaw/delivery-queue/failed/\n\n\n\nSkills-remote bin probes to offline nodes — Gateway probes paired nodes for skill binary requirements. If nodes don't have the node service running, each probe hangs until timeout.\n\nDiagnose: grep \"skills-remote.*timed out\" gateway.err.log | wc -l\nFix: Remove offline nodes from paired devices, or ensure nodes have the node service running.\n\n\n\nGoogle Gemini CLI OAuth account cycling — If the agent switches to Gemini CLI in-session, it cycles through OAuth accounts. Each expired/slow account hangs for 90 seconds. 6 accounts = up to 540s of hung connections.\n\nDiagnose: grep \"google-gemini-cli.*timed out\" gateway.err.log | tail -10\nFix: Ensure OAuth tokens are fresh, or use the google (API key) provider instead of google-gemini-cli for fallbacks.\n\n\n\nNo cron concurrency limit — Multiple cron jobs firing simultaneously all compete for the same event loop and hit the same provider chain, creating a thundering herd.\n\nFix: openclaw config set cron.maxConcurrentRuns 1\n\n\n\nProxy providers as early fallbacks — KiloCode is a proxy. When it degrades, ALL models through it fail simultaneously (appears as multiple independent failures but is one SPOF). Put direct-API providers (Anthropic, Google API key) before proxies in the fallback chain.\n\nRecovery: After fixing underlying causes, restart gateway: launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway" }, { "title": "10c. launchctl setenv Persistence (macOS)", "body": "Problem: Removing an env var from the LaunchAgent plist does NOT remove it from the launchd session environment. The gateway process still sees the old value after a kickstart -k restart.\n\nRoot cause: launchctl setenv sets variables at the launchd domain level, independent of any plist. These persist until the user logs out or they are explicitly unset. kickstart -k re-reads the plist for ProgramArguments and EnvironmentVariables, but the domain-level env set by setenv takes precedence.\n\nFix:\n\n# 1. Remove from plist\n/usr/libexec/PlistBuddy -c 'Delete :EnvironmentVariables:' ~/Library/LaunchAgents/ai.openclaw.gateway.plist\n\n# 2. Remove from launchd session\nlaunchctl unsetenv \n\n# 3. Full service re-register (not just kickstart)\nlaunchctl bootout gui/$(id -u)/ai.openclaw.gateway\nlaunchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist\n\nKey lesson: Always clean both plist AND launchctl unsetenv when removing provider env vars. Use launchctl getenv to verify removal. If the command returns output (even empty), the var is still set. \"Not set\" means launchctl getenv exits with an error." }, { "title": "10d. Context Bloat Cascade Timeouts", "body": "Symptom: ALL providers in the fallback chain timeout simultaneously on the same request. The same runId appears across multiple providers in 90-second intervals. Looks like a massive outage but providers are actually fine.\n\nPattern in logs:\n\n14:17:24 Profile openai-codex:default timed out. Trying next account...\n14:18:54 Profile kimi-coding:default timed out. Trying next account...\n14:20:25 [diagnostic] lane task error ... FailoverError: LLM request timed out.\n14:21:55 Profile anthropic:manual timed out. Trying next account...\n\nRoot cause: contextTokens is unset (defaults to unlimited). The main session accumulates conversation history until the payload is so large that no provider can respond within timeoutSeconds. Each provider in the fallback chain gets the same oversized payload, times out, and passes to the next one — creating a cascade that takes timeoutSeconds × number_of_providers to fully fail.\n\nThe deadly trio:\n\nUnlimited contextTokens — payload grows unchecked\nShort timeoutSeconds (e.g., 90) — not enough time for large payloads\nLong fallback chain (4-5 providers) — each one gets a full timeout cycle before failing\n\nFix — recommended baseline for any mixed-provider fallback chain:\n\nopenclaw config set agents.defaults.contextTokens 100000\nopenclaw config set agents.defaults.timeoutSeconds 180\nopenclaw config set agents.defaults.compaction.reserveTokensFloor 32000\nopenclaw config set agents.defaults.compaction.mode safeguard\n\nHow this works together:\n\ncontextTokens: 100000 — caps context so all providers can handle it\nCompaction triggers at ~68K tokens (100K minus 32K reserve)\nMemory flush runs first (if enabled), then compaction compresses history\ntimeoutSeconds: 180 — gives providers 3 minutes per attempt (vs 90s)\nThe cap ensures every provider in the chain can respond in time\n\nTradeoff: Models with large context windows (Gemini: 1M, GPT-5.4: 1.05M) are capped at 100K. This is intentional — the cap must match the weakest provider in the fallback chain. For dedicated large-context sessions, temporarily increase contextTokens.\n\nFull troubleshooting reference (7 failure categories, per-channel error tables, node error codes, GitHub issue workarounds): Read references/troubleshooting.md" }, { "title": "11. System Learning", "body": "This skill maintains system profiles — persistent knowledge files that capture everything learned about specific OpenClaw deployments. Each deployment gets a unique profile that grows over time, turning the skill into an expert on that particular system." }, { "title": "How It Works", "body": "Directory: ~/.openclaw-optimizer/systems/ — one profile per deployment, plus TEMPLATE.md for new deployments. This is a centralized location outside the skill directory so that: (1) system profiles are never accidentally pushed to git, (2) multiple AI tools (Claude Code, OpenClaw, Gemini CLI, etc.) on the same machine can read/write the same profiles without drift. Cross-machine sync is still manual via SCP.\n\nDeployment ID: Each deployment has a unique slug (e.g., jbd-home, prod-cluster-east, dev-standalone).\n\nProfile formats (two supported):\n\nDirectory format (preferred): ~/.openclaw-optimizer/systems// — directory containing INDEX.md (always-loaded summary, ~1-4K tokens) plus topic files loaded on-demand. Dramatically reduces session-start context cost.\nSingle-file format (legacy): ~/.openclaw-optimizer/systems/.md — monolith file containing everything. Still supported for backwards compatibility.\n\nTopology types:\n\nTypeDescriptiongateway-onlySingle gateway, no remote nodeshub-spokeOne gateway, one or more client nodes connecting to itmulti-gatewayMultiple gateways, nodes may connect to different onesmeshNodes interconnected, multiple gateways with cross-routing" }, { "title": "Session Workflow", "body": "First-run setup (once per machine):\n\nCheck if ~/.openclaw-optimizer/systems/ exists\nIf not: inform the user that this skill stores deployment profiles in ~/.openclaw-optimizer/systems/ (centralized, outside git, shared across AI tools), confirm they're OK with creating it, then: mkdir -p ~/.openclaw-optimizer/systems/ and copy TEMPLATE.md from the skill's systems/ directory into it\nIf the directory exists but is empty (no TEMPLATE.md): copy TEMPLATE.md from the skill's systems/ directory\n\nAt session start (identify the deployment):\n\nAsk which deployment the user is working on, or identify it from context (SSH target, hostnames, IPs)\nCheck if ~/.openclaw-optimizer/systems// directory exists\nIf directory found: read INDEX.md only (~1-4K tokens). Use the File Manifest table at the bottom to load topic files on-demand during the session — do NOT read all files upfront.\nIf directory NOT found but .md file exists: read the monolith (legacy mode). Consider migrating to directory format.\nIf neither found: create a new profile from ~/.openclaw-optimizer/systems/TEMPLATE.md during the session\n\nOn any system assessment or audit (mandatory — run before making recommendations):\n\nopenclaw cron list — capture full cron inventory: job IDs, names, schedules, status, last run times\nopenclaw config get agents.defaults.model — capture model routing (primary + fallbacks)\nls ~/.openclaw/delivery-queue/*.json 2>/dev/null | wc -l — check for stuck delivery entries\nopenclaw nodes list — check paired nodes and connection status\nFlag any cron jobs in error state — these are active problems\nFlag jobs with stale last-run times (>24h for daily jobs) — may indicate silent failures\nCheck timezone consistency — jobs using (exact) instead of named timezones may fire at wrong times\nDocument ALL findings in the system profile before making recommendations\nWithout this data, recommendations will duplicate existing automation and miss hidden drains.\n\nDuring the session (on-demand file loading):\n\nReference INDEX.md for SSH access, IPs, routing, and cron status\nWhen diagnosing any issue: read lessons.md FIRST (check if it's already solved), then the relevant topic file\nWhen troubleshooting cron: read cron.md for full job IDs, schedules, and observations\nWhen investigating providers/connectivity: read providers.md and/or topology.md\nWhen checking channels/Telegram: read channels.md for group API IDs and mapping\nWhen reviewing history: read issues/YYYY-MM.md for the relevant month\nApply lessons learned to avoid repeating mistakes\n\nAt session end (update the profile):\n\nFor directory-based profiles:\n\nUpdate the specific topic file(s) that changed (e.g., routing.md if fallbacks were reordered)\nUpdate INDEX.md only if summary-level data changed (new provider added/removed, routing swap, cron status change, machine added/removed)\nAdd new issues to issues/YYYY-MM.md (current month file, newest first) with: symptom, root cause, fix, rollback, lesson\nAdd new lessons to lessons.md (permanent, never archived)\nUpdate the Last updated date in INDEX.md\nSync only changed files to the gateway: scp ~/.openclaw-optimizer/systems// @:~/.openclaw-optimizer/systems//\nNote: system profiles live in ~/.openclaw-optimizer/systems/, NOT in the skill directory. Do not commit them to git.\n\nFor legacy single-file profiles:\n\nAdd any new issues to the Issue Log (newest first) with: symptom, root cause, fix, rollback, lesson\nUpdate Lessons Learned with new patterns discovered\nUpdate machine details if anything changed (IPs, versions, config)\nUpdate the Last updated date\nSync the profile to the gateway: scp ~/.openclaw-optimizer/systems/.md @:~/.openclaw-optimizer/systems/" }, { "title": "What Gets Captured", "body": "TopicFile (directory format)PurposeMachines, Network, Paired Devicestopology.mdEvery machine: role, SSH, IPs, OS, paths, config. Tailnet, auth, connectivity. Device entries from paired.json.Providersproviders.mdActive model providers with slugs, auth details, notes. Removed providers with context.Model Routingrouting.mdTiered routing table, fallback chain, heartbeat configChannels, Delivery Queuechannels.mdMessaging channels, Telegram group mapping, stuck delivery entriesCron Jobscron.mdFull inventory: job ID, name, schedule, model, status, observationsIssuesissues/YYYY-MM.mdEvery problem encountered: symptom → root cause → fix → rollback → lessonLessons Learnedlessons.mdAccumulated patterns and gotchas specific to this deployment (permanent)SummaryINDEX.mdAlways-loaded overview with key tables and file manifest" }, { "title": "Issue Lifecycle (directory format)", "body": "New issues go into issues/YYYY-MM.md (current month file, newest first)\nAfter 14 days: full detail stays in the monthly file, a one-liner is added to issues/archive.md\nMonthly files are never deleted — they're the permanent record\nLessons extracted from issues go to lessons.md (permanent, never archived)" }, { "title": "Rules", "body": "Never store full secrets in profiles — use first 12 chars + ... for tokens, never store full API keys\nAlways read the profile before troubleshooting — don't rediscover what's already known\nAlways update the profile after fixes — future sessions depend on accurate knowledge\nOne profile per gateway — nodes are documented within the gateway's profile\nKeep lessons actionable — not \"TLS was broken\" but \"macOS app rejects ws:// for remote gateways — always use wss://\"\nRely on built-in backup layers — don't create manual backups for routine changes. OpenClaw's CLI creates rolling .bak files on every config write, and the nightly GitHub backup cron captures the full config in git history. Manual dated backups (cp .YYYY-MM-DD-) are only needed for: (1) major version upgrades, (2) multi-file restructuring (identity audits), (3) direct JSON edits where the CLI isn't used. For routine CLI changes (model swaps, cron edits, config sets), the CLI .bak + GitHub nightly are sufficient. Clean up old manual backups after they're covered by the nightly backup." }, { "title": "12. Continuous Improvement", "body": "This skill is a living document. Every troubleshooting session, every CLI interaction, and every failure is an opportunity to make it more accurate. Future sessions must actively update the skill based on real-world experience." }, { "title": "When to Update SKILL.md", "body": "TriggerActionA CLI command in the skill doesn't work as documentedFix the command, add a note about what changedA troubleshooting step is missing or incompleteAdd it to Section 10's symptom tableA workaround is discovered that isn't documentedAdd it to the relevant sectionAdvice in the skill caused a failureCorrect the advice and add a warningA new openclaw flag or subcommand is discovered during useUpdate Section 8 (CLI Reference)A new known bug or GitHub issue is foundAdd it to the relevant section with issue numberA config key is renamed, deprecated, or newUpdate the relevant config examples" }, { "title": "What to Update", "body": "Two targets — always update both when applicable:\n\nSKILL.md — general knowledge that applies to ALL deployments (CLI commands, config patterns, troubleshooting steps, known bugs, process workflows)\nSystem profile (systems/.md) — deployment-specific knowledge (IPs, paths, credentials, topology, issue log, lessons learned)" }, { "title": "How to Update", "body": "During the session: When you discover something new, update the relevant section immediately — don't wait until the end. Corrections to bad advice are urgent.\nBe specific: Don't write \"TLS can be tricky.\" Write \"macOS app rejects ws:// for remote gateways — always use wss://. The ws:// scheme is only valid for loopback connections.\"\nInclude the why: Don't just say \"use X instead of Y.\" Explain what goes wrong when you use Y.\nPreserve what works: Only change what's actually wrong. Don't rewrite sections that are accurate.\nSync to remote: After updating, sync the skill and system profiles to any remote OpenClaw instances:\n# Sync SKILL.md (skill code — lives in the skill directory)\nscp ~/.claude/skills/openclaw-optimizer/SKILL.md @:~/.openclaw/workspace/skills/openclaw-optimizer/SKILL.md\n# Sync system profiles — directory format (sync only changed files)\nscp ~/.openclaw-optimizer/systems// @:~/.openclaw-optimizer/systems//\n# Sync system profiles — legacy single-file format\nscp ~/.openclaw-optimizer/systems/.md @:~/.openclaw-optimizer/systems/" }, { "title": "Versioning", "body": "The skill uses semver (MAJOR.MINOR.PATCH) independent of OpenClaw's version:\n\nPATCH (1.3.0 → 1.3.1): Fixing a typo, correcting a command, small clarification\nMINOR (1.3.0 → 1.4.0): Adding a new section, new troubleshooting entries, new workflow\nMAJOR (1.3.0 → 2.0.0): Restructuring sections, breaking changes to the skill's own workflow\n\nOn every commit that changes SKILL.md:\n\nBump version: in the YAML frontmatter\nUpdate the Updated: date in the header\nUpdate the Skill v tag in the header" }, { "title": "Self-Audit Checklist (run mentally at session end)", "body": "Did I discover any CLI behavior that contradicts the skill? → Fix Section 8 or 10\nDid I find a workaround that future sessions would need? → Add to relevant section\nDid I hit an error that's not in the troubleshooting table? → Add to Section 10\nDid I learn something deployment-specific? → Update the system profile\nDid any advice in this skill lead me astray? → Correct it with a warning\nDid I change SKILL.md? → Bump version, update date, commit, push, sync to gateway" }, { "title": "13. Agent Identity Optimizer", "body": "Audit and optimize OpenClaw bootstrap/identity files for conflicts, bloat, misplaced content, and best practice violations. Interactive issue-by-issue walkthrough with preview diffs.\n\nCore files audited: SOUL.md, IDENTITY.md, AGENTS.md, USER.md\nSupporting files (if present): TOOLS.md, HEARTBEAT.md, MEMORY.md, BOOT.md\n\nWhat it checks (36 items): Structural issues (truncation risk, bloat), content in the wrong file, conflicting/overlapping directives, best practice violations (official AGENTS.md template), USER.md completeness gaps, token efficiency.\n\nWorkflow: Collect files (local or SSH) → run checklist → present findings by severity → walk through each issue (approve/modify/skip) → apply changes → report token savings.\n\nContext-aware (v2026.3.7+): When auditing, consider lightContext and postCompactionSections — files used only in lightContext mode (HEARTBEAT.md) or re-injected after compaction (postCompactionSections headings in AGENTS.md) have different optimization priorities. Ensure critical instructions appear under postCompactionSections headings (default: Session Startup, Red Lines) so they survive compaction.\n\nFull audit checklist, file role definitions, and detailed workflow: Read references/identity-optimizer.md" }, { "title": "Output Shape", "body": "Executive summary — what matters most + why\nTop offenders — cost drivers, context drivers, reliability risks\nOptions A/B/C — tradeoffs made explicit\nRecommended plan — smallest change first\nExact change proposals — CLI commands or config patches, all with rollback\nRollback — exact command to undo every change\n\nSources: docs.openclaw.ai, github.com/openclaw/openclaw, r/openclaw, r/myclaw, r/OpenClawUseCases" } ], "body": "OpenClaw Optimizer\n\nAligned with: OpenClaw v2026.3.8 | Skill v1.19.0 | Updated: 2026-03-09 | CLI-first advisor\n\nOptimize and troubleshoot OpenClaw workspaces: cost-aware routing, provider configuration, context discipline, lean automation, multi-agent architectures, and error resolution.\n\nReference files (load when needed):\n\nreferences/providers.md — all 40+ providers, custom provider schema, failover config\nreferences/troubleshooting.md — full error reference, 7 failure categories, GitHub issue workarounds\nreferences/cli-reference.md — complete CLI command reference\nreferences/identity-optimizer.md — agent identity/personality audit checklist, file roles, walkthrough workflow\nVersion Awareness\n\nThis skill tracks OpenClaw releases via two mechanisms:\n\nGitHub Actions — daily workflow checks for new releases, opens an issue on drift, auto-closes when resolved\nRuntime check — lightweight cached version comparison at session start\nRuntime Check (once per session)\npython3 ~/.claude/skills/openclaw-optimizer/scripts/version-check.py --status\n\nCURRENT → note the version and proceed.\nSTALE → inform the user: \"OpenClaw v is available (skill is at v). Run update-skill.sh to review what changed.\"\nUNCHECKED → note \"Version check unavailable (offline)\" and proceed.\nUpdate Workflow (user-initiated, never automatic)\n# Show drift report, changelog, and affected sections\nbash ~/.claude/skills/openclaw-optimizer/scripts/update-skill.sh\n\n# After updating content in SKILL.md and references/:\nbash ~/.claude/skills/openclaw-optimizer/scripts/update-skill.sh --apply # bump versions\nbash ~/.claude/skills/openclaw-optimizer/scripts/update-skill.sh --commit # bump + commit + push\n\n\nUpdates are deliberate — this skill never auto-modifies its own content or pushes to git without explicit user action.\n\nQuick Start (copy/paste prompts)\n\nFull audit (safe, no changes):\n\nAudit my OpenClaw setup for cost, reliability, and context bloat. Prioritized plan with rollback. Do NOT apply changes.\n\nTroubleshoot a specific problem:\n\n[Describe your symptom or paste the error message]. Diagnose it and give me the exact fix.\n\nAdd or configure a provider:\n\nAdd [provider name] as a model provider. Walk me through the CLI steps and show me the exact config before applying.\n\nModel routing optimization:\n\nPropose a tiered routing plan: cheap for heartbeats/cron, mid for daily tasks, premium for coding/reasoning. Exact config + rollback. Do NOT apply.\n\nSilent cron job:\n\nCreate a cron job that runs [task] every [interval]. Isolated session, NO_REPLY on nothing-to-do. Show me the command first.\n\nAudit agent personality & identity:\n\nAudit my agent's personality and identity files. Check for conflicts, bloat, and bad practices. Walk me through improvements.\n\nSafety Contract (non-negotiable)\nThis skill is advisory by default — not an autonomous control-plane.\nNever mutate config (config.apply, config.patch), cron jobs, or persistent settings without explicit user approval.\nBefore any approved change: show (1) exact CLI command or config patch, (2) expected impact, (3) rollback command.\nIf an optimization reduces monitoring coverage, present Options A/B/C and require the user to choose.\nBackup Strategy\n\nFour backup layers exist — don't stack manual backups on top unnecessarily:\n\nLayer\tWhat\tRetention\tWhen It's Enough\nCLI rolling .bak\tAuto-created on every config set, models set, cron edit\tRolling (overwritten each write)\tSingle-command undo\nNightly GitHub backup\tFull config committed by cron job (3 AM)\tGit history (unlimited)\tAny rollback to a previous day's state\nopenclaw backup create\tLocal state archive with manifest verification (v2026.3.8+)\tUntil manually deleted\tPre-upgrade safety net; use openclaw backup verify to validate\nManual dated backup\tcp .YYYY-MM-DD-\tUntil next nightly covers it, then delete\tMajor upgrades, multi-file restructuring, direct JSON edits\n\nRule: 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.\n\n1. Model Providers\n\n40+ providers supported. For full docs (auth commands, config schemas, all model names, custom provider setup): read references/providers.md\n\nQuick lookup — slug, auth env, primary model format:\n\nProvider\tSlug\tAuth Env\tModel Format\nAnthropic\tanthropic\tANTHROPIC_API_KEY\tanthropic/claude-opus-4-6\nOpenAI (API key)\topenai\tOPENAI_API_KEY\topenai/gpt-5.4\nOpenAI Codex (subscription)\topenai-codex\tChatGPT OAuth\topenai-codex/gpt-5.4\nGoogle Gemini\tgoogle\tGEMINI_API_KEY\tgoogle/gemini-3.1-pro-preview\n\nWARNING — Provider Bans (Mar 2026):\n\nGoogle: 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.\n\nAnthropic: 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.\n\nGeneral: 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.\n\n| Mistral | mistral | MISTRAL_API_KEY | mistral/mistral-large-latest | | Groq | groq | GROQ_API_KEY | groq/ | | 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 | | Ollama (local) | ollama | OLLAMA_API_KEY (any) | ollama/llama3.3 | | vLLM (local) | vllm | VLLM_API_KEY (any) | vllm/ |\n\nAdd a provider (API key):\n\nopenclaw onboard --auth-choice -api-key\nopenclaw models auth login --provider \nopenclaw models set \n\n\nAdd a provider (OAuth / subscription):\n\nopenclaw onboard --auth-choice openai-codex # ChatGPT subscription\nopenclaw models auth login --provider openai-codex\nopenclaw models set openai-codex/gpt-5.4\n\nOAuth Providers (Subscription-Based Access)\n\nSome 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.\n\nCurrently supported OAuth providers:\n\nProvider\tSlug\tSubscription Required\tTop Models\nOpenAI Codex\topenai-codex\tChatGPT Plus ($20/mo) or Pro ($200/mo)\tgpt-5.4, gpt-5.3-codex, codex-mini-latest\nGitHub Copilot\tgithub-copilot\tCopilot subscription\tgithub-copilot/gpt-4o\n\nOpenAI Codex setup (full walkthrough):\n\n# 1. Authenticate (opens browser for ChatGPT sign-in)\nopenclaw models auth login --provider openai-codex\n# → Prints a URL. Open it in a browser, sign in to ChatGPT, paste redirect URL back.\n\n# 3. Verify auth\nopenclaw models status --probe --probe-provider openai-codex\n\n# 4. Set as primary OR add to fallback chain\nopenclaw models set openai-codex/gpt-5.4 # as primary\nopenclaw models fallbacks add openai-codex/gpt-5.4 # or as fallback\n\n# 5. Restart gateway\nlaunchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway # macOS LaunchAgent\n\n\nHeadless / 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.\n\nAvailable Codex models:\n\nModel\tPlan\tNotes\nopenai-codex/gpt-5.4\tPlus, Pro, Business\tLatest (Mar 2026), 1,050,000-token context, 128K max tokens\nopenai-codex/gpt-5.3-codex\tPlus, Pro, Business\tPrevious flagship, most capable coding model\nopenai-codex/gpt-5.3-codex-spark\tPro only\tResearch preview, low-latency\nopenai-codex/gpt-5.2-codex\tPlus, Pro\tPrevious gen, stable\nopenai-codex/codex-mini-latest\tPlus, Pro\tLightweight, fast, cheapest\n\nUsage limits (per 5-hour window):\n\nPlus ($20/mo): 30–150 messages\nPro ($200/mo): 300–1,500 messages\nExtra credits purchasable when limits are hit\n\nGotchas:\n\nNo embeddings. Codex OAuth does NOT grant access to OpenAI embeddings. You still need a separate OPENAI_API_KEY for text-embedding-3-small etc.\nToken refresh is automatic — active sessions continue without re-login. Credentials stored in ~/.openclaw/credentials/oauth.json.\nDon'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.\n\"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.\nDual-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.\nCommunity 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.\nProvider Removal Checklist\n\nRemoving a provider requires cleaning 6 locations — config unset alone is not enough:\n\nmodels.providers. in openclaw.json — openclaw config unset models.providers.\nauth.profiles.:* in openclaw.json — must edit JSON directly (colons in keys break config unset)\nprofiles dict in ~/.openclaw/agents/main/agent/auth-profiles.json — edit with python3/jq\nagents.defaults.models. aliases in openclaw.json — openclaw config unset each alias\nplugins.entries.-auth in openclaw.json — openclaw config unset plugins.entries.-auth\nlastGood. and usageStats.:* in auth-profiles.json — edit directly\n\nFor providers with LaunchAgent env vars (Ollama, etc.), also clean: 7. launchctl unsetenv — 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)\n\nKnown 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.\n\nOllama for memory embeddings (v2026.3.2+):\n\nopenclaw config set memorySearch.provider ollama\nopenclaw config set memorySearch.fallback ollama\n\n\nRuns memory search embeddings locally — no external API calls. Honors models.providers.ollama settings.\n\nCustom OpenAI-compatible provider (LM Studio, LiteLLM, etc.): See references/providers.md\n\n2. Model Routing Strategy\nTiered Routing (50–95% cost reduction)\nTier\tModels\tUse Cases\nT1 Cheap\tzai/glm-5, google/gemini-3-flash-preview, google/gemini-3.1-flash-lite-preview, synthetic/hf:deepseek-ai/DeepSeek-V3.2\tHeartbeats, simple checks, greetings, cron\nT2 Mid\tmoonshot/kimi-k2.5, minimax/MiniMax-M2.5-highspeed\tDaily chat, Q&A, calendar, scheduling\nT3 Smart\tanthropic/claude-sonnet-4-5, openai/gpt-5.4, openai-codex/gpt-5.4 (subscription)\tCode, refactors, research\nT4 Premium\tanthropic/claude-opus-4-6, openai/gpt-5.2\tComplex reasoning, orchestration\n\nModel preference by task:\n\nTask\tModel\tWhy\nHeartbeats / cron\tzai/glm-5\tCheapest; reliable structured output\nCalendar / scheduling\tmoonshot/kimi-k2.5\tCommunity #1 for date/time reasoning\nCoding / refactoring\tanthropic/claude-sonnet-4-5 or openai-codex/gpt-5.4\tSonnet: community #1 for code quality; Codex: flat-rate via subscription\nAgent orchestration\tanthropic/claude-opus-4-6\tBest multi-step reasoning\nLong-context tasks\tgoogle/gemini-3-flash-preview or openai-codex/gpt-5.4\tGemini: 1M token window; Codex 5.4: 1.05M tokens\nSubscription-capped coding\topenai-codex/gpt-5.4\tFixed cost via ChatGPT Plus/Pro; no per-token billing\nPrivacy-sensitive\tvenice/kimi-k2-5 or Ollama\tNever logged/stored\nUltra-cheap batch\tgoogle/gemini-3.1-flash-lite-preview\tMinimal cost; good for lightweight cron/heartbeat\n\nKey rules:\n\nNever switch models mid-conversation — destroys Anthropic prompt cache\nUse anthropic direct (not through proxies) to preserve caching for Opus/Sonnet\nSwitch only at session boundaries (/new)\nBuilt-in Model Aliases (v2026.3.7+)\nAlias\tResolves To\nopus\tanthropic/claude-opus-4-6\nsonnet\tanthropic/claude-sonnet-4-6\ngpt\topenai/gpt-5.4\ngpt-mini\topenai/gpt-5-mini\ngemini\tgoogle/gemini-3.1-pro-preview\ngemini-flash\tgoogle/gemini-3-flash-preview\ngemini-flash-lite\tgoogle/gemini-3.1-flash-lite-preview\nThinking Levels (v2026.3.1+)\nLevel\tBehavior\tBest For\noff\tNo extended thinking\tSimple queries, heartbeats\nminimal\tLight reasoning (~1.1s)\tRoutine tasks; community tip: set as default to halve latency\nlow\tStandard reasoning\tDefault for non-Claude-4.6 reasoning models\nmedium / high\tDeeper reasoning\tComplex tasks\nxhigh\t\"Ultrathink+\"\tGPT-5.2 + Codex models only\nadaptive\tProvider-managed\tDefault for Claude 4.6 — auto-scales reasoning to task complexity\nopenclaw config set agents.defaults.thinkingDefault adaptive # recommended for Claude 4.6\nopenclaw config set agents.defaults.thinkingDefault minimal # cost-saver for routine workloads\n\n\nIn-chat: /think low · /think adaptive · /think off\n\nPer-Agent Config\nopenclaw models set anthropic/claude-opus-4-6 # set global primary\nopenclaw config set agents.defaults.model.primary anthropic/claude-opus-4-6\nopenclaw models fallbacks add openrouter/anthropic/claude-sonnet-4-5\n\n{\n agents: {\n list: [\n { id: \"main\", model: \"anthropic/claude-opus-4-6\", heartbeat: { every: \"30m\" } },\n { id: \"ops\", model: { primary: \"anthropic/claude-sonnet-4-5\", fallbacks: [\"zai/glm-5\"] },\n tools: { profile: \"minimal\" } },\n ],\n defaults: {\n model: { primary: \"anthropic/claude-opus-4-6\", fallbacks: [\"minimax/MiniMax-M2.5-highspeed\"] },\n thinkingDefault: \"adaptive\",\n timeoutSeconds: 600,\n contextTokens: 200000,\n maxConcurrent: 3,\n params: { cacheRetention: \"long\" },\n },\n },\n}\n\n\nIn-chat model switch (no restart): /model list → /model anthropic/claude-sonnet-4-5\n\nSession Pruning (v2026.3.1+)\n\nAutomatically trims stale tool results from conversation history to preserve cache and reclaim context:\n\n{\n agents: { defaults: { contextPruning: {\n mode: \"cache-ttl\", // \"off\" (default) | \"cache-ttl\"\n ttl: \"5m\",\n keepLastAssistants: 3,\n softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },\n hardClear: { enabled: true },\n } } },\n}\n\n\nAnthropic smart defaults auto-enable cache-ttl pruning when using API key auth with heartbeat enabled.\n\n3. Context Management\n\nWhat burns tokens: System prompt (5–10K tokens/call) + bootstrap files + conversation history. Bootstrap files injected on every turn (source: docs.openclaw.ai/concepts/system-prompt): AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md (first-run only), plus MEMORY.md and/or memory.md when present. Daily memory/*.md files are NOT auto-injected (on-demand via memory tools). Bootstrap cap: 150K chars total, 20K per file (both configurable).\n\nMEMORY.md warning (from docs): \"Keep them concise — especially MEMORY.md, which can grow over time and lead to unexpectedly high context usage and more frequent compaction.\" MEMORY.md is the most common source of bootstrap bloat. Unlike AGENTS.md or SOUL.md which users actively edit, MEMORY.md tends to grow unchecked as the agent appends to it.\n\nCheck context: /status · /context list · /context detail · /usage tokens · /usage cost\n\nPrompt Modes\nMode\tBootstrap Files Loaded\tUse Case\nfull (default)\tAll — AGENTS, SOUL, TOOLS, IDENTITY, USER, HEARTBEAT, MEMORY\tMain interactive sessions\nminimal (sub-agents)\tAGENTS.md + TOOLS.md only\tSub-agent spawns — no SOUL, IDENTITY, USER, HEARTBEAT, MEMORY\nnone\tBase identity line only\tBare-minimum sessions\nLight Bootstrap (v2026.3.1+)\n\nSkip all workspace bootstrap files for automated runs:\n\nopenclaw cron add --light-context --cron \"*/30 * * * *\" --message \"Quick check\"\n\n{\n agents: { defaults: { heartbeat: {\n lightContext: true, // only loads HEARTBEAT.md, skips all other bootstrap files\n } } },\n}\n\n\nMassive token savings for heartbeats and cron — eliminates 5-10K tokens/call of bootstrap overhead.\n\nBootstrap Truncation Warning (v2026.3.7+)\nopenclaw config set agents.defaults.bootstrapPromptTruncationWarning once # off | once | always\n\n\nWhen a bootstrap file exceeds bootstrapMaxChars (default 20K), the agent receives a warning. Set to always during identity audits to catch truncated files.\n\nCompaction Config\n# Manual: /compact [focus instructions]\n# Auto: triggers near context limit — count visible in /status\n\nopenclaw config set agents.defaults.compaction.mode safeguard\nopenclaw config set agents.defaults.compaction.reserveTokensFloor 32000\nopenclaw config set agents.defaults.contextTokens 100000\nopenclaw config set agents.defaults.compaction.model google/gemini-3-flash-preview # cheaper compaction (v2026.3.7+)\nopenclaw config set agents.defaults.compaction.recentTurnsPreserve 4 # quality-guard (v2026.3.7+)\n\n{\n agents: { defaults: { compaction: {\n mode: \"safeguard\",\n model: \"google/gemini-3-flash-preview\", // route compaction through a cheaper model\n reserveTokensFloor: 32000,\n recentTurnsPreserve: 4, // keep last N turns intact during compaction\n postCompactionSections: [\"Session Startup\", \"Red Lines\"], // AGENTS.md sections re-injected after compaction\n memoryFlush: {\n enabled: true,\n prompt: \"Write lasting notes to memory/YYYY-MM-DD.md; reply NO_REPLY if nothing to store.\",\n },\n }, contextTokens: 100000 } },\n}\n\n\nKnown bug — memory flush threshold gap (Issue #25880): Set reserveTokensFloor equal to reserveTokens (both 62500) to fix compaction firing before flush completes.\n\nKnown bug — compaction timeout (Issue #38233): Both /compact and auto compaction can timeout at ~300s with openai-codex/gpt-5.3-codex, freezing the session. Fix: override compaction model to google/gemini-3-flash-preview with thinking: \"off\". Tune: maxHistoryShare: 0.6, reserveTokensFloor: 40000, maxAttempts: 3.\n\nContext Engine Plugin (v2026.3.7+)\n\nReplace the built-in context assembly pipeline with a custom plugin:\n\n{\n plugins: { slots: { contextEngine: \"lossless-claw\" } }, // default: \"legacy\" (built-in)\n}\n\n\nContext Engine plugins get full lifecycle hooks: bootstrap, ingest, assemble, compact, afterTurn, prepareSubagentSpawn, onSubagentEnded. This enables alternative context management strategies (lossless context, semantic chunking, etc.) without modifying OpenClaw core.\n\nBootstrap File Size Targets (optimization recommendations)\n\nThese are optimization targets for keeping context lean, not hard limits. All files are subject to bootstrapMaxChars (default 20K) and bootstrapTotalMaxChars (default 150K).\n\nFile\tTarget Size\tPurpose\tInjected?\nSOUL.md\t< 1K tokens (~4K chars)\tPersonality + absolute constraints\tAlways (main + full prompt mode)\nAGENTS.md\t< 2K tokens (~8K chars)\tWorkflows, rules, operating procedures\tAlways (main + sub-agents)\nTOOLS.md\t< 2K tokens (~8K chars)\tTool-specific notes, local conventions\tAlways (main + sub-agents)\nIDENTITY.md\t< 500 tokens (~2K chars)\tName, vibe, emoji, presentation\tAlways (main only)\nUSER.md\t< 1K tokens (~4K chars)\tUser profile, preferences, context\tAlways (main only)\nHEARTBEAT.md\t< 200 tokens (~800 chars)\tHeartbeat checklist (keep minimal)\tAlways (main only); skipped with lightContext\nMEMORY.md\t< 5K tokens (~20K chars)\tCurated long-term facts ONLY\tAlways in main sessions (auto-injected when present)\n\nCritical: MEMORY.md is auto-injected on every turn in main sessions, NOT loaded on-demand. It burns tokens continuously. Keep it as small as possible with only curated facts. Operational protocols belong in AGENTS.md. Tool notes belong in TOOLS.md.\n\nBootstrap Content Placement (What Goes Where)\n\nUsers commonly dump all content into SOUL.md because it feels like \"who the agent is.\" This bloats the file (burns tokens every turn) and confuses lighter models that can't prioritize across a noisy instruction set. Place content in the correct file:\n\nContent Type\tCorrect File\tCommon Mistake\nPersonality, voice, humor, constraints\tSOUL.md\t-\nProtocols, workflows, checklists, operational rules\tAGENTS.md\tDumping in SOUL.md\nUser bio, preferences, working hours, communication style\tUSER.md\tDuplicating in SOUL.md\nTool configs, API templates, channel IDs, env vars\tTOOLS.md\tScattering in AGENTS.md\nCurated long-term facts (lean)\tMEMORY.md\tGrowing unchecked\nProactivity rules, initiative behavior\tAGENTS.md\tPutting in SOUL.md\n\nCross-file duplication burns tokens silently. If the same protocol appears in both SOUL.md and AGENTS.md, it's injected twice on every turn. Deduplicate aggressively — pick one canonical location.\n\nStale model references are silent saboteurs. When you change models via CLI (openclaw models set), update any AGENTS.md sections that reference specific model names (e.g., Model Selection, Sub-Agent defaults). The agent follows bootstrap instructions and may try to use models that are no longer configured.\n\nPersistence stack: SOUL.md → AGENTS.md → TOOLS.md → IDENTITY.md → USER.md → MEMORY.md (all auto-injected in main sessions) → memory/YYYY-MM-DD.md (on-demand via memory tools) → conversation-state.md → ACTIVE-TASK.md\n\nSession Maintenance\nopenclaw config set session.maintenance.mode enforce\nopenclaw config set session.maintenance.maxDiskBytes 500mb\nopenclaw sessions cleanup --dry-run # preview\nopenclaw sessions cleanup --enforce # apply\nopenclaw sessions cleanup --fix-missing # prune store entries whose transcript files are missing (v2026.2.26+)\n\n4. Cron & Automation\nCron Job Schema (key fields)\n{\n \"jobId\": \"daily-brief\", \"name\": \"Morning Briefing\", \"enabled\": true,\n \"agentId\": \"main\",\n \"schedule\": { \"kind\": \"cron\", \"expr\": \"0 8 * * *\", \"tz\": \"America/New_York\" },\n \"sessionTarget\": \"isolated\",\n \"payload\": { \"kind\": \"agentTurn\", \"message\": \"Morning briefing.\", \"model\": \"anthropic/claude-sonnet-4-5\", \"timeoutSeconds\": 300 },\n \"delivery\": { \"mode\": \"announce\", \"channel\": \"telegram\", \"to\": \"\" },\n \"lightContext\": true\n}\n\n\nsessionTarget: \"isolated\" (recommended — fresh session) | \"main\" (injects as systemEvent) payload.kind: \"agentTurn\" (isolated) | \"systemEvent\" (main session) delivery.mode: \"announce\" | \"webhook\" | \"none\" lightContext: true skips all workspace bootstrap files — massive token savings for automated runs (v2026.3.1+)\n\nCLI\nopenclaw cron add --cron \"0 9 * * *\" --message \"Daily report\" --agent main --announce --channel slack --to \"channel:CXXX\"\nopenclaw cron add --cron \"0 9 * * *\" --message \"Quick check\" --light-context # skip bootstrap files\nopenclaw cron add --at \"2026-03-01T08:00:00\" --message \"One-time task\" --keep-after-run\nopenclaw cron add --cron \"0 9 * * *\" --exact # no stagger jitter\nopenclaw cron run # test immediately (--force bypasses not-due)\nopenclaw cron list / status / runs\nopenclaw cron edit [flags] # patch fields: --cron, --message, --model, --name, --tz, etc.\nopenclaw cron enable/disable \nopenclaw cron rm \nopenclaw config set cron.sessionRetention 24h\nopenclaw config set cron.maxConcurrentRuns 1 # circuit breaker\n\nCron Defer-While-Active (v2026.3.7+)\n\nSkip main-session cron jobs when the user is actively chatting:\n\nopenclaw config set cron.deferWhileActive.quietMs 300000 # defer if user active within last 5 minutes\n\n\nPrevents cron jobs from interrupting active conversations. Only affects sessionTarget: \"main\" jobs; isolated jobs always run.\n\nCron Restart Staggering (v2026.3.8+)\n\nOn gateway startup, missed cron jobs are staggered to prevent gateway starvation. Top-of-hour cron expressions get up to 5 minutes of deterministic stagger. Use --exact or schedule.staggerMs: 0 to disable.\n\nSilent Patterns\n\nNO_REPLY — agent outputs this literal string when nothing to report; system suppresses delivery entirely. HEARTBEAT_OK — heartbeat token; reply ≤300 chars after stripping it → silently dropped.\n\n{\n agents: { defaults: { heartbeat: {\n every: \"30m\",\n target: \"last\",\n ackMaxChars: 300,\n directPolicy: \"allow\",\n lightContext: false, // set true to skip bootstrap files (v2026.3.1+)\n activeHours: { start: \"08:00\", end: \"22:00\", timezone: \"America/New_York\" },\n } } },\n}\n\n\nv2026.2.25 BREAKING: The heartbeat DM toggle was replaced with directPolicy. Default is now allow. If you had DMs blocked in v2026.2.24, explicitly set agents.defaults.heartbeat.directPolicy: \"block\" (or per-agent via agents.list[].heartbeat.directPolicy).\n\nCost trap: 5-minute heartbeat loading full MEMORY.md = ~2.9M tokens/day. Keep heartbeat context minimal — use lightContext: true or extend intervals.\n\nRedundant cron jobs: The built-in openclaw memory indexes sessions natively. Custom session archiver cron jobs that convert .jsonl to markdown for a separate RAG database are likely redundant. Check whether any cron job feeds a custom system that duplicates built-in functionality before assuming it's needed.\n\nKnown bugs: Cron current-day skip (Issue #25902) — restart the gateway with launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway to recompute (do NOT use openclaw gateway restart — it causes duplicate processes; see Section 10). Cron announce → Telegram failure (Issue #25906) — switch to directMessage mode.\n\nv2026.2.25 fixes: Cron model override failures now auto-recover — if an isolated job's payload.model is no longer allowlisted, it gracefully falls back to the default model instead of failing the job. Cron announce duplicate sends are also fixed (duplicate guard tracks attempted vs confirmed delivery). Multi-account cron routing now properly honors delivery.accountId.\n\n5. Skills & Plugins\n\nmetadata.openclaw.requires — gates skill visibility:\n\nmetadata:\n openclaw:\n requires:\n bins: [\"ffmpeg\"] # ALL must exist on PATH\n anyBins: [\"gh\", \"hub\"] # AT LEAST ONE must exist\n env: [\"GITHUB_TOKEN\"] # env vars that must be set\n config: [\"browser.enabled\"]\n os: [\"darwin\", \"linux\"]\n\n\ndisable-model-invocation: true — removes skill from model's tool list; user can still invoke manually. Use for high-impact or security-sensitive skills.\n\nSkills directory: ~/.openclaw/workspace/skills/ — this is the filesystem path where all skills are stored. Each skill lives in its own subdirectory (e.g., ~/.openclaw/workspace/skills/my-skill/SKILL.md). When manually installing or copying skills, always use this path — not ~/.openclaw/skills/.\n\nClawHub:\n\nnpx clawhub install # install\nclawhub update --all # update all\nopenclaw skills list --eligible # what's loaded\nopenclaw skills check # validate requirements\n\n\nSecurity: Before installing any skill, read its SKILL.md manually. Community scans found 341+ malicious skills (reverse shells, credential exfiltration, Atomic Stealer, crypto miners). New accounts with popular skills = red flag. The #1 most-downloaded ClawHub skill was confirmed malware.\n\nSession watcher: Skills snapshot at session start. If skills.load.watch is disabled, start a new session after installing.\n\nPlugin Slots (v2026.3.7+)\n{\n plugins: {\n slots: {\n contextEngine: \"legacy\", // or custom plugin id (e.g., \"lossless-claw\")\n memory: \"memory-core\", // or \"none\" to disable memory entirely\n },\n entries: {\n \"\": {\n enabled: true,\n hooks: { allowPromptInjection: false }, // block plugin from mutating system prompt\n },\n },\n },\n}\n\n6. Multi-Agent & Sub-Agent Architecture\n/subagents spawn ops \"Audit logs from last 24h\" # via chat\n\n// sessions_spawn tool (programmatic)\n{ \"task\": \"Audit logs\", \"agentId\": \"ops\", \"model\": \"anthropic/claude-sonnet-4-5\",\n \"thinking\": \"low\", \"runTimeoutSeconds\": 300, \"mode\": \"minimal\",\n \"attachments\": [\"/path/to/file.md\"] } // inline file attachments (v2026.3.2+)\n\n// Nesting config\n{ agents: { defaults: { subagents: {\n maxSpawnDepth: 2, // 0=off; 1=spawn; 2=orchestrator\n maxConcurrency: 8,\n maxChildrenPerAgent: 5,\n model: \"anthropic/claude-sonnet-4-5\", // default model for spawned sub-agents\n runTimeoutSeconds: 900,\n} } } }\n\n\nCommunity pattern: Orchestrator (opus-4-6) → Code sub-agent (sonnet-4-5) → Research sub-agent (kimi-k2.5) → Cron/monitoring (zai/glm-5, isolated)\n\nCommunity insight — single agent with skills beats multiple agents for most use cases. Multiple agent instances multiply context costs (each agent loads its own bootstrap). Use one agent with good skills instead, and only split into multiple agents when you need genuinely different identity/personality/permissions (e.g., a public-facing agent vs an ops agent).\n\nSandbox isolation:\n\n{ agents: { list: [{ id: \"untrusted\", sandbox: { mode: \"docker\" },\n tools: { profile: \"minimal\", deny: [\"exec\", \"browser\"] } }] } }\n\nACP Dispatch (v2026.3.2+)\n\nAgent Client Protocol enables OpenClaw to spawn external coding harnesses (Claude Code, Codex CLI, Gemini CLI, OpenCode) as sub-agents:\n\n{\n acp: {\n enabled: true,\n dispatch: { enabled: true }, // default true since v2026.3.2\n defaultAgent: \"codex\",\n allowedAgents: [\"claude\", \"codex\", \"opencode\", \"gemini\", \"kimi\"],\n maxConcurrentSessions: 8,\n },\n}\n\n\nIn-chat: /acp spawn · /acp status · /acp steer · /acp close\n\n7. High-ROI Optimization Levers\nLever\tImpact\tHow\nTiered model routing\t50–95% cost reduction\tT1 for cron/heartbeat, T4 only for orchestration\nPrompt caching\t60–90% input token reduction\tKeep system prompt stable; use anthropic direct\nBootstrap file discipline\t2K–10K tokens/call saved\tSOUL.md <1K, AGENTS.md <2K, MEMORY.md <5K\nLight bootstrap for cron/heartbeat\t5-10K tokens/call saved\tlightContext: true on heartbeat; --light-context on cron\nAdaptive thinking\tAuto-scales token use\tthinkingDefault: adaptive for Claude 4.6; minimal for routine\nSession pruning\tReclaims stale context\tcontextPruning.mode: cache-ttl with Anthropic\nSilent cron (NO_REPLY)\tEliminates delivery tokens\tInstruct: \"Reply NO_REPLY if nothing actionable\"\nCompaction tuning\tPrevents overflow disasters\tsafeguard mode, reserveTokensFloor: 32000\nCheaper compaction model\tReduces compaction cost\tRoute compaction through gemini-3-flash-preview\nSession maintenance\tPrevents disk/perf degradation\tmode: enforce, maxDiskBytes: 500mb\nBatch heartbeat checks\t10x fewer API calls\tOne heartbeat for 10 checks > 10 cron jobs\nIsolated cron sessions\tZero context contamination\tsessionTarget: \"isolated\" on all cron jobs\nSingle agent with skills\tUp to 80% cost reduction\tOne agent + skills beats multiple agent instances\nGateway security\tPrevents exposure\tgateway.bind: loopback; Tailscale for remote\nNever switch mid-session\tPreserves prompt cache\tOnly switch model at /new boundaries\nBackup before upgrades\tPre-change safety net\topenclaw backup create before openclaw update\n8. CLI Reference\n\nBest practice (v2026.2.25+): Before editing config or asking config-field questions, have the agent call the config.schema tool in-chat. This returns the current schema with valid keys, types, and defaults — avoids guessing or using stale field names. Note: this is an agent in-chat tool, NOT a CLI command.\n\nMost common commands:\n\nopenclaw doctor --fix # auto-fix config issues\nopenclaw gateway status # check runtime + RPC probe\nopenclaw models set \nopenclaw models status --probe\nopenclaw cron run # test a cron job immediately\nopenclaw sessions cleanup --dry-run\nopenclaw sessions cleanup --fix-missing # prune entries with missing transcripts (v2026.2.26+)\nopenclaw config validate [--json] # validate config against schema (v2026.3.2+)\nopenclaw config file # print active config file path (v2026.3.1+)\nopenclaw backup create [--only-config] # local state archive (v2026.3.8+)\nopenclaw backup verify # validate backup integrity (v2026.3.8+)\nopenclaw update\nopenclaw security audit # post-upgrade check\nopenclaw secrets audit # scan bootstrap files for hardcoded secrets (v2026.2.26+)\nopenclaw secrets configure # configure external secrets (v2026.2.26+)\nopenclaw secrets apply # apply secrets with strict target-path validation (v2026.2.26+)\nopenclaw agents bindings # list account-scoped agent route bindings (v2026.2.26+)\nopenclaw agents bind # bind agent to channel account (v2026.2.26+)\nopenclaw agents unbind # unbind agent from channel account (v2026.2.26+)\n\n\nopenclaw onboard --reset scope change (v2026.2.26): Default reset scope is now config+creds+sessions. Workspace deletion (bootstrap files, skills, memory) now requires --reset-scope full. Do NOT run openclaw onboard --reset without specifying --reset-scope explicitly — the default no longer wipes the workspace.\n\nIn-Chat Commands (v2026.3.x)\n/session idle manage thread inactivity auto-unfocus\n/session max-age manage hard max-age for thread bindings\n/usage cost local cost summary from session logs\n/usage tokens show per-reply token usage\n/export-session [path] export current session to HTML (/export alias)\n/steer steer a running sub-agent immediately (/tell alias)\n/kill abort one or all running sub-agents\n/think off | minimal | low | medium | high | xhigh | adaptive\n/model switch model without restart\n/compact [instructions] manual compaction with optional focus\n/context detail per-file, per-tool, per-skill token breakdown\n/acp spawn|status|steer|close ACP session control\n/check-updates quick update summary\n\nEnvironment Variables (v2026.3.x)\nOPENCLAW_LOG_LEVEL= # override log level: silent|fatal|error|warn|info|debug|trace\nOPENCLAW_DIAGNOSTICS= # targeted debug logs (e.g., \"telegram.*\" or \"*\" for all)\nOPENCLAW_SHELL= # set across shell-like runtimes (exec, acp, tui-local)\nOPENCLAW_THEME=light|dark # TUI theme override (v2026.3.8+)\n\n\nGateway restart (macOS LaunchAgent):\n\n# SAFE restart — single atomic operation, no duplicate processes\nlaunchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway\n\n# DO NOT use `openclaw gateway restart` — it races with KeepAlive and spawns\n# duplicate processes that loop \"Port already in use\" every ~10s at 100%+ CPU.\n\n# Recovery if duplicates already exist:\nlaunchctl bootout gui/$(id -u)/ai.openclaw.gateway # stop launchd service + kill managed process\nkill # kill orphans\nlaunchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist # re-register + start clean\n\n\nFull CLI reference (all commands, flags, in-chat commands): Read references/cli-reference.md\n\n9. Ops Hygiene Checklist\n\nDaily:\n\nopenclaw health --json via cron (→ HEARTBEAT_OK if clean)\nclawhub whoami to verify ClawHub auth\nToken budget check (cost-sensitive providers)\n\nWeekly:\n\nopenclaw update --dry-run → review → openclaw update\nclawhub update --all --dry-run → review → clawhub update --all\nCurate MEMORY.md — archive old daily logs, promote key insights\nopenclaw sessions cleanup --dry-run → openclaw sessions cleanup\nopenclaw cron status — check for errors\nClean stale backup files: find ~/.openclaw -name \"*.bak.*\" -mtime +7 -not -name \"*.bak\" | xargs rm -v (preserves CLI's rolling .bak files, removes old named/dated backups)\n\nQuarterly:\n\nReview custom scripts (scripts/) for redundancy with built-in OpenClaw features. Users often build custom solutions (RAG pipelines, session archivers, memory indexers) that become redundant when OpenClaw adds equivalent built-in functionality. Check whether each script and its associated cron job still serves a purpose that the platform doesn't already handle.\n\nBefore/After Updates:\n\nBefore update: openclaw backup create (pre-change safety net — v2026.3.8+)\nAfter update: openclaw doctor --fix (handles config migrations automatically)\nAfter update: openclaw config validate --json (catch fail-closed config errors — v2026.3.2+)\nv2026.2.23 breaking change: allowPrivateNetwork → dangerouslyAllowPrivateNetwork — auto-fixed by doctor\nManual backup only needed for major upgrades or multi-file restructuring (see Backup Strategy above)\n\nv2026.3.x Breaking Changes:\n\ngateway.auth.mode required (v2026.3.7): When both gateway.auth.token AND gateway.auth.password are configured, you must set gateway.auth.mode to \"token\" or \"password\". Gateway will not start without this.\ntools.profile defaults to \"messaging\" (v2026.3.2): New installs no longer start with coding/system tools. Existing installs are unaffected.\nACP dispatch defaults to enabled (v2026.3.2): Set acp.dispatch.enabled: false to disable.\nConfig fail-closed (v2026.3.2+): Invalid configs cause gateway startup failure instead of silently falling back to permissive defaults.\nNode.js v22.12+ enforced: Attempting to run on Node 18/20 causes immediate failure.\n\nOn Every System Assessment (mandatory data collection):\n\nopenclaw cron list + read ~/.openclaw/cron/jobs.json — capture full cron inventory: job IDs, names, schedules, model overrides (from payload.model), status, last run times\nFlag any jobs in error state — these are active problems\nFlag jobs with stale last-run times (>24h for daily jobs) — may indicate silent failures\nCheck timezone consistency — jobs using (exact) instead of named timezones may fire at wrong times\nRecord whether jobs use isolated or main session target\nMap cron schedule to day/night distribution — heavy jobs should cluster overnight\nDocument all findings in the system profile's ## Cron Jobs section before making recommendations\nWithout this data, recommendations will duplicate existing automation and waste time\n\nSecurity:\n\nopenclaw config get gateway.bind → must be loopback\nNo public port exposure — use Tailscale for remote\nAPI keys not in skill files or version control\nAudit ClawHub skills before installing — 341+ malicious skills confirmed\nCVE-2026-25253 (ClawJacked): WebSocket authentication bypass allowing one-click RCE. 42,000+ exposed instances. Patched in v2026.1.29+. Verify you are on v2026.2.26+ minimum.\nopenclaw security audit --deep for live Gateway probe\n10. Troubleshooting\n\nLog file paths (macOS):\n\nError log: ~/.openclaw/logs/gateway.err.log — primary source for errors, 502s, plugin failures, tool errors\nMain log: /tmp/openclaw/openclaw-YYYY-MM-DD.log — verbose debug output (lane events, session activity)\n\nAlways check gateway.err.log first when troubleshooting — it contains only errors and warnings, making root cause identification much faster than grepping the main log.\n\nFirst — always run this triage sequence:\n\nopenclaw status\nopenclaw gateway status # must show \"Runtime: running\" + \"RPC probe: ok\"\nopenclaw doctor\nopenclaw channels status --probe\nopenclaw config validate --json # catch config errors before restart (v2026.3.2+)\ntail -50 ~/.openclaw/logs/gateway.err.log | grep -v DEP0040 # skip Node deprecation noise\n\n\nQuick fix by symptom:\n\nSymptom\tFirst Command\tMost Likely Fix\nNo response from agent\topenclaw gateway status\tGateway not running or pairing pending\nGateway won't start\topenclaw logs --follow\tEADDRINUSE or gateway.mode not set to local\n\"Port already in use\" loop\tps aux | grep openclaw-gateway\tDuplicate processes from CLI restart vs LaunchAgent KeepAlive. Fix: launchctl bootout → kill orphans → launchctl bootstrap (see Section 8)\n\"Gateway start blocked: set gateway.auth.mode\"\topenclaw config get gateway.auth\tBoth token and password set but gateway.auth.mode missing. Fix: openclaw config set gateway.auth.mode token (v2026.3.7 breaking change)\n\"unauthorized\" on Control UI\tlaunchctl getenv OPENCLAW_GATEWAY_TOKEN\tRemove stale launchctl env override\nConfig file wiped on restart\tBack up config first\tKnown bug #40410 — gateway restart can wipe openclaw.json. Use openclaw backup create before restarts.\nCron job never fires\topenclaw cron status\tCron disabled or timezone mismatch\nHeartbeat always skipped\topenclaw config get agents.defaults.heartbeat.activeHours\tWrong timezone, outside active hours, or directPolicy set to block (v2026.2.25 changed default to allow)\nCron job fails with \"model not allowlisted\"\topenclaw cron status\tv2026.2.25+ auto-recovers by falling back to default model. On older versions: update payload.model in the job or re-add the model to the allowlist.\nChannel message dropped\topenclaw logs --follow\tMention required or sender not paired\n\"RPC probe: failed\"\topenclaw gateway status --deep\tAuth token mismatch or port conflict\nPost-upgrade breakage\topenclaw doctor --fix\tAutomatic config migration\nProvider 401 errors\topenclaw models status --probe\tToken expired or wrong key type\nChrome browser won't start (Linux)\topenclaw browser status\tSnap Chromium conflict → install Google Chrome .deb\nSilent tool execution failure\tCheck model\tKnown bug #40069 — agent claims tool use but no calls made. Confirmed with kimi-coding/k2p5. Switch model.\nCompaction freezes session\tOverride compaction model\tKnown bug #38233 — /compact times out at ~300s with Codex models. Use compaction.model: google/gemini-3-flash-preview\nOllama stuck \"typing\" forever\tSwitch to non-Ollama model\tKnown bug #40434 — local Ollama models stuck via Telegram\nFallback doesn't escalate on outage\tTest fallback chain\tKnown bug #32533 — retries auth profiles instead of escalating to fallback providers\nALL providers timeout simultaneously\tgrep \"delivery-recovery\" gateway.err.log\tNot a provider issue. Two common causes: (A) Context bloat — contextTokens unset (unlimited), payload too large for any provider to process within timeoutSeconds. Fix: set contextTokens: 100000, timeoutSeconds: 180, reserveTokensFloor: 32000. See Section 10d. (B) Event loop overload — stuck delivery-queue, skills-remote probes, Gemini OAuth cycling, too many concurrent sessions. Fix: clear delivery queue, set cron.maxConcurrentRuns: 1. See Section 10b.\nDelivery recovery loop (\"21 entries deferred\")\tls ~/.openclaw/delivery-queue/\tStuck entries (wrong channel, message too long) retry forever on every restart. Move to ~/.openclaw/delivery-queue/failed/ to stop the loop.\nOllama \"fetch failed\" (instant, ~100ms)\tCheck gateway err log for Failed to discover Ollama models\tKnown bug: OpenClaw hardcodes 127.0.0.1:11434 for Ollama discovery (Issue #8663). On macOS, LaunchAgent processes are sandboxed and can't reach private LAN IPs like 192.168.x.x (Issue #21494). Fix: reverse SSH tunnel from Ollama machine to gateway (ssh -fN -R 127.0.0.1:11434:127.0.0.1:11434 user@gateway), set baseUrl to http://127.0.0.1:11434, add OLLAMA_HOST and OLLAMA_API_KEY to LaunchAgent env. See Section 10a below.\nOllama \"Connection error\"\tSame as above\tSame root cause. Switching api from ollama to openai-completions changes the error message but doesn't fix it — the sandbox blocks all LAN connections.\nOllama probes spike memory\tcurl http://host:11434/api/ps\tSet OLLAMA_KEEP_ALIVE=0 on the Ollama machine so models unload immediately after probes. No OpenClaw config to disable probes per-provider.\nGemini CLI \"API rate limit reached\"\topenclaw logs | grep rate\tGoogle OAuth crackdown (Feb 2026). Switch to API key auth. See Section 1 warning.\nProvider removal didn't stop probes\tCheck all 6 locations in Provider Removal Checklist\tStale auth-profiles.json, launchctl env, or plist env vars. See Section 1.\nconfig unset fails on auth profile keys\tEdit JSON directly\tColons in keys break the config path parser. Use python3/jq.\nmodels status --probe mass timeouts\tTest individual providers with curl\tProbe contention — 16+ simultaneous targets saturate the event loop. Not real failures.\n10a. Remote Ollama on macOS (Known Bug Workaround)\n\nProblem: OpenClaw on macOS cannot connect to a remote Ollama server on the LAN. curl works, but the gateway process fails with \"fetch failed\" or \"Connection error.\" This affects all API modes (ollama and openai-completions).\n\nRoot causes (two bugs stacking):\n\nHardcoded localhost discovery (Issue #8663): OpenClaw always probes 127.0.0.1:11434 for Ollama, ignoring baseUrl.\nmacOS LaunchAgent sandbox (Issue #21494): The gateway process running under launchd gets EHOSTUNREACH for private network IPs (192.168.x.x, 10.x.x.x).\n\nFix — reverse SSH tunnel:\n\n# Run on the Ollama machine (not the gateway):\nssh -fN -R 127.0.0.1:11434:127.0.0.1:11434 user@gateway-host\n\n# On the gateway:\nopenclaw config set models.providers..baseUrl 'http://127.0.0.1:11434'\nopenclaw config set models.providers..api ollama\n\n\nAdd to the gateway's LaunchAgent plist:\n\nOLLAMA_HOST\nhttp://127.0.0.1:11434\nOLLAMA_API_KEY\nollama\n\n\nImportant: Kill any local Ollama on the gateway first — it will conflict with the tunnel on port 11434. Make the tunnel persistent with a LaunchAgent on the Ollama machine.\n\n10b. Multi-Provider Timeout Storms (Event Loop Overload)\n\nSymptom: ALL providers (Kimi, KiloCode, Google, Anthropic, etc.) timeout simultaneously within a 30-90 minute window, even though they are independent services. FailoverError: LLM request timed out. on every model in the fallback chain. May cause gateway crash/restart.\n\nRoot cause: The gateway's Node.js event loop is saturated by a pile-up of concurrent operations. Outbound HTTPS responses arrive, but the process can't process them before its own timeout timer fires. The providers are NOT down — the gateway can't handle the responses.\n\nCommon overload contributors (check all of these):\n\nStuck delivery-recovery queue — Files in ~/.openclaw/delivery-queue/ that will never succeed (wrong channel, message too long) retry on every restart and periodically. Each retry burns event loop time.\n\nDiagnose: ls ~/.openclaw/delivery-queue/*.json | wc -l and grep \"delivery-recovery\" gateway.err.log | tail -20\nFix: mv ~/.openclaw/delivery-queue/*.json ~/.openclaw/delivery-queue/failed/\n\nSkills-remote bin probes to offline nodes — Gateway probes paired nodes for skill binary requirements. If nodes don't have the node service running, each probe hangs until timeout.\n\nDiagnose: grep \"skills-remote.*timed out\" gateway.err.log | wc -l\nFix: Remove offline nodes from paired devices, or ensure nodes have the node service running.\n\nGoogle Gemini CLI OAuth account cycling — If the agent switches to Gemini CLI in-session, it cycles through OAuth accounts. Each expired/slow account hangs for 90 seconds. 6 accounts = up to 540s of hung connections.\n\nDiagnose: grep \"google-gemini-cli.*timed out\" gateway.err.log | tail -10\nFix: Ensure OAuth tokens are fresh, or use the google (API key) provider instead of google-gemini-cli for fallbacks.\n\nNo cron concurrency limit — Multiple cron jobs firing simultaneously all compete for the same event loop and hit the same provider chain, creating a thundering herd.\n\nFix: openclaw config set cron.maxConcurrentRuns 1\n\nProxy providers as early fallbacks — KiloCode is a proxy. When it degrades, ALL models through it fail simultaneously (appears as multiple independent failures but is one SPOF). Put direct-API providers (Anthropic, Google API key) before proxies in the fallback chain.\n\nRecovery: After fixing underlying causes, restart gateway: launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway\n\n10c. launchctl setenv Persistence (macOS)\n\nProblem: Removing an env var from the LaunchAgent plist does NOT remove it from the launchd session environment. The gateway process still sees the old value after a kickstart -k restart.\n\nRoot cause: launchctl setenv sets variables at the launchd domain level, independent of any plist. These persist until the user logs out or they are explicitly unset. kickstart -k re-reads the plist for ProgramArguments and EnvironmentVariables, but the domain-level env set by setenv takes precedence.\n\nFix:\n\n# 1. Remove from plist\n/usr/libexec/PlistBuddy -c 'Delete :EnvironmentVariables:' ~/Library/LaunchAgents/ai.openclaw.gateway.plist\n\n# 2. Remove from launchd session\nlaunchctl unsetenv \n\n# 3. Full service re-register (not just kickstart)\nlaunchctl bootout gui/$(id -u)/ai.openclaw.gateway\nlaunchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist\n\n\nKey lesson: Always clean both plist AND launchctl unsetenv when removing provider env vars. Use launchctl getenv to verify removal. If the command returns output (even empty), the var is still set. \"Not set\" means launchctl getenv exits with an error.\n\n10d. Context Bloat Cascade Timeouts\n\nSymptom: ALL providers in the fallback chain timeout simultaneously on the same request. The same runId appears across multiple providers in 90-second intervals. Looks like a massive outage but providers are actually fine.\n\nPattern in logs:\n\n14:17:24 Profile openai-codex:default timed out. Trying next account...\n14:18:54 Profile kimi-coding:default timed out. Trying next account...\n14:20:25 [diagnostic] lane task error ... FailoverError: LLM request timed out.\n14:21:55 Profile anthropic:manual timed out. Trying next account...\n\n\nRoot cause: contextTokens is unset (defaults to unlimited). The main session accumulates conversation history until the payload is so large that no provider can respond within timeoutSeconds. Each provider in the fallback chain gets the same oversized payload, times out, and passes to the next one — creating a cascade that takes timeoutSeconds × number_of_providers to fully fail.\n\nThe deadly trio:\n\nUnlimited contextTokens — payload grows unchecked\nShort timeoutSeconds (e.g., 90) — not enough time for large payloads\nLong fallback chain (4-5 providers) — each one gets a full timeout cycle before failing\n\nFix — recommended baseline for any mixed-provider fallback chain:\n\nopenclaw config set agents.defaults.contextTokens 100000\nopenclaw config set agents.defaults.timeoutSeconds 180\nopenclaw config set agents.defaults.compaction.reserveTokensFloor 32000\nopenclaw config set agents.defaults.compaction.mode safeguard\n\n\nHow this works together:\n\ncontextTokens: 100000 — caps context so all providers can handle it\nCompaction triggers at ~68K tokens (100K minus 32K reserve)\nMemory flush runs first (if enabled), then compaction compresses history\ntimeoutSeconds: 180 — gives providers 3 minutes per attempt (vs 90s)\nThe cap ensures every provider in the chain can respond in time\n\nTradeoff: Models with large context windows (Gemini: 1M, GPT-5.4: 1.05M) are capped at 100K. This is intentional — the cap must match the weakest provider in the fallback chain. For dedicated large-context sessions, temporarily increase contextTokens.\n\nFull troubleshooting reference (7 failure categories, per-channel error tables, node error codes, GitHub issue workarounds): Read references/troubleshooting.md\n\n11. System Learning\n\nThis skill maintains system profiles — persistent knowledge files that capture everything learned about specific OpenClaw deployments. Each deployment gets a unique profile that grows over time, turning the skill into an expert on that particular system.\n\nHow It Works\n\nDirectory: ~/.openclaw-optimizer/systems/ — one profile per deployment, plus TEMPLATE.md for new deployments. This is a centralized location outside the skill directory so that: (1) system profiles are never accidentally pushed to git, (2) multiple AI tools (Claude Code, OpenClaw, Gemini CLI, etc.) on the same machine can read/write the same profiles without drift. Cross-machine sync is still manual via SCP.\n\nDeployment ID: Each deployment has a unique slug (e.g., jbd-home, prod-cluster-east, dev-standalone).\n\nProfile formats (two supported):\n\nDirectory format (preferred): ~/.openclaw-optimizer/systems// — directory containing INDEX.md (always-loaded summary, ~1-4K tokens) plus topic files loaded on-demand. Dramatically reduces session-start context cost.\nSingle-file format (legacy): ~/.openclaw-optimizer/systems/.md — monolith file containing everything. Still supported for backwards compatibility.\n\nTopology types:\n\nType\tDescription\ngateway-only\tSingle gateway, no remote nodes\nhub-spoke\tOne gateway, one or more client nodes connecting to it\nmulti-gateway\tMultiple gateways, nodes may connect to different ones\nmesh\tNodes interconnected, multiple gateways with cross-routing\nSession Workflow\n\nFirst-run setup (once per machine):\n\nCheck if ~/.openclaw-optimizer/systems/ exists\nIf not: inform the user that this skill stores deployment profiles in ~/.openclaw-optimizer/systems/ (centralized, outside git, shared across AI tools), confirm they're OK with creating it, then: mkdir -p ~/.openclaw-optimizer/systems/ and copy TEMPLATE.md from the skill's systems/ directory into it\nIf the directory exists but is empty (no TEMPLATE.md): copy TEMPLATE.md from the skill's systems/ directory\n\nAt session start (identify the deployment):\n\nAsk which deployment the user is working on, or identify it from context (SSH target, hostnames, IPs)\nCheck if ~/.openclaw-optimizer/systems// directory exists\nIf directory found: read INDEX.md only (~1-4K tokens). Use the File Manifest table at the bottom to load topic files on-demand during the session — do NOT read all files upfront.\nIf directory NOT found but .md file exists: read the monolith (legacy mode). Consider migrating to directory format.\nIf neither found: create a new profile from ~/.openclaw-optimizer/systems/TEMPLATE.md during the session\n\nOn any system assessment or audit (mandatory — run before making recommendations):\n\nopenclaw cron list — capture full cron inventory: job IDs, names, schedules, status, last run times\nopenclaw config get agents.defaults.model — capture model routing (primary + fallbacks)\nls ~/.openclaw/delivery-queue/*.json 2>/dev/null | wc -l — check for stuck delivery entries\nopenclaw nodes list — check paired nodes and connection status\nFlag any cron jobs in error state — these are active problems\nFlag jobs with stale last-run times (>24h for daily jobs) — may indicate silent failures\nCheck timezone consistency — jobs using (exact) instead of named timezones may fire at wrong times\nDocument ALL findings in the system profile before making recommendations\nWithout this data, recommendations will duplicate existing automation and miss hidden drains.\n\nDuring the session (on-demand file loading):\n\nReference INDEX.md for SSH access, IPs, routing, and cron status\nWhen diagnosing any issue: read lessons.md FIRST (check if it's already solved), then the relevant topic file\nWhen troubleshooting cron: read cron.md for full job IDs, schedules, and observations\nWhen investigating providers/connectivity: read providers.md and/or topology.md\nWhen checking channels/Telegram: read channels.md for group API IDs and mapping\nWhen reviewing history: read issues/YYYY-MM.md for the relevant month\nApply lessons learned to avoid repeating mistakes\n\nAt session end (update the profile):\n\nFor directory-based profiles:\n\nUpdate the specific topic file(s) that changed (e.g., routing.md if fallbacks were reordered)\nUpdate INDEX.md only if summary-level data changed (new provider added/removed, routing swap, cron status change, machine added/removed)\nAdd new issues to issues/YYYY-MM.md (current month file, newest first) with: symptom, root cause, fix, rollback, lesson\nAdd new lessons to lessons.md (permanent, never archived)\nUpdate the Last updated date in INDEX.md\nSync only changed files to the gateway: scp ~/.openclaw-optimizer/systems// @:~/.openclaw-optimizer/systems//\nNote: system profiles live in ~/.openclaw-optimizer/systems/, NOT in the skill directory. Do not commit them to git.\n\nFor legacy single-file profiles:\n\nAdd any new issues to the Issue Log (newest first) with: symptom, root cause, fix, rollback, lesson\nUpdate Lessons Learned with new patterns discovered\nUpdate machine details if anything changed (IPs, versions, config)\nUpdate the Last updated date\nSync the profile to the gateway: scp ~/.openclaw-optimizer/systems/.md @:~/.openclaw-optimizer/systems/\nWhat Gets Captured\nTopic\tFile (directory format)\tPurpose\nMachines, Network, Paired Devices\ttopology.md\tEvery machine: role, SSH, IPs, OS, paths, config. Tailnet, auth, connectivity. Device entries from paired.json.\nProviders\tproviders.md\tActive model providers with slugs, auth details, notes. Removed providers with context.\nModel Routing\trouting.md\tTiered routing table, fallback chain, heartbeat config\nChannels, Delivery Queue\tchannels.md\tMessaging channels, Telegram group mapping, stuck delivery entries\nCron Jobs\tcron.md\tFull inventory: job ID, name, schedule, model, status, observations\nIssues\tissues/YYYY-MM.md\tEvery problem encountered: symptom → root cause → fix → rollback → lesson\nLessons Learned\tlessons.md\tAccumulated patterns and gotchas specific to this deployment (permanent)\nSummary\tINDEX.md\tAlways-loaded overview with key tables and file manifest\nIssue Lifecycle (directory format)\nNew issues go into issues/YYYY-MM.md (current month file, newest first)\nAfter 14 days: full detail stays in the monthly file, a one-liner is added to issues/archive.md\nMonthly files are never deleted — they're the permanent record\nLessons extracted from issues go to lessons.md (permanent, never archived)\nRules\nNever store full secrets in profiles — use first 12 chars + ... for tokens, never store full API keys\nAlways read the profile before troubleshooting — don't rediscover what's already known\nAlways update the profile after fixes — future sessions depend on accurate knowledge\nOne profile per gateway — nodes are documented within the gateway's profile\nKeep lessons actionable — not \"TLS was broken\" but \"macOS app rejects ws:// for remote gateways — always use wss://\"\nRely on built-in backup layers — don't create manual backups for routine changes. OpenClaw's CLI creates rolling .bak files on every config write, and the nightly GitHub backup cron captures the full config in git history. Manual dated backups (cp .YYYY-MM-DD-) are only needed for: (1) major version upgrades, (2) multi-file restructuring (identity audits), (3) direct JSON edits where the CLI isn't used. For routine CLI changes (model swaps, cron edits, config sets), the CLI .bak + GitHub nightly are sufficient. Clean up old manual backups after they're covered by the nightly backup.\n12. Continuous Improvement\n\nThis skill is a living document. Every troubleshooting session, every CLI interaction, and every failure is an opportunity to make it more accurate. Future sessions must actively update the skill based on real-world experience.\n\nWhen to Update SKILL.md\nTrigger\tAction\nA CLI command in the skill doesn't work as documented\tFix the command, add a note about what changed\nA troubleshooting step is missing or incomplete\tAdd it to Section 10's symptom table\nA workaround is discovered that isn't documented\tAdd it to the relevant section\nAdvice in the skill caused a failure\tCorrect the advice and add a warning\nA new openclaw flag or subcommand is discovered during use\tUpdate Section 8 (CLI Reference)\nA new known bug or GitHub issue is found\tAdd it to the relevant section with issue number\nA config key is renamed, deprecated, or new\tUpdate the relevant config examples\nWhat to Update\n\nTwo targets — always update both when applicable:\n\nSKILL.md — general knowledge that applies to ALL deployments (CLI commands, config patterns, troubleshooting steps, known bugs, process workflows)\nSystem profile (systems/.md) — deployment-specific knowledge (IPs, paths, credentials, topology, issue log, lessons learned)\nHow to Update\nDuring the session: When you discover something new, update the relevant section immediately — don't wait until the end. Corrections to bad advice are urgent.\nBe specific: Don't write \"TLS can be tricky.\" Write \"macOS app rejects ws:// for remote gateways — always use wss://. The ws:// scheme is only valid for loopback connections.\"\nInclude the why: Don't just say \"use X instead of Y.\" Explain what goes wrong when you use Y.\nPreserve what works: Only change what's actually wrong. Don't rewrite sections that are accurate.\nSync to remote: After updating, sync the skill and system profiles to any remote OpenClaw instances:\n# Sync SKILL.md (skill code — lives in the skill directory)\nscp ~/.claude/skills/openclaw-optimizer/SKILL.md @:~/.openclaw/workspace/skills/openclaw-optimizer/SKILL.md\n# Sync system profiles — directory format (sync only changed files)\nscp ~/.openclaw-optimizer/systems// @:~/.openclaw-optimizer/systems//\n# Sync system profiles — legacy single-file format\nscp ~/.openclaw-optimizer/systems/.md @:~/.openclaw-optimizer/systems/\n\nVersioning\n\nThe skill uses semver (MAJOR.MINOR.PATCH) independent of OpenClaw's version:\n\nPATCH (1.3.0 → 1.3.1): Fixing a typo, correcting a command, small clarification\nMINOR (1.3.0 → 1.4.0): Adding a new section, new troubleshooting entries, new workflow\nMAJOR (1.3.0 → 2.0.0): Restructuring sections, breaking changes to the skill's own workflow\n\nOn every commit that changes SKILL.md:\n\nBump version: in the YAML frontmatter\nUpdate the Updated: date in the header\nUpdate the Skill v tag in the header\nSelf-Audit Checklist (run mentally at session end)\nDid I discover any CLI behavior that contradicts the skill? → Fix Section 8 or 10\nDid I find a workaround that future sessions would need? → Add to relevant section\nDid I hit an error that's not in the troubleshooting table? → Add to Section 10\nDid I learn something deployment-specific? → Update the system profile\nDid any advice in this skill lead me astray? → Correct it with a warning\nDid I change SKILL.md? → Bump version, update date, commit, push, sync to gateway\n13. Agent Identity Optimizer\n\nAudit and optimize OpenClaw bootstrap/identity files for conflicts, bloat, misplaced content, and best practice violations. Interactive issue-by-issue walkthrough with preview diffs.\n\nCore files audited: SOUL.md, IDENTITY.md, AGENTS.md, USER.md Supporting files (if present): TOOLS.md, HEARTBEAT.md, MEMORY.md, BOOT.md\n\nWhat it checks (36 items): Structural issues (truncation risk, bloat), content in the wrong file, conflicting/overlapping directives, best practice violations (official AGENTS.md template), USER.md completeness gaps, token efficiency.\n\nWorkflow: Collect files (local or SSH) → run checklist → present findings by severity → walk through each issue (approve/modify/skip) → apply changes → report token savings.\n\nContext-aware (v2026.3.7+): When auditing, consider lightContext and postCompactionSections — files used only in lightContext mode (HEARTBEAT.md) or re-injected after compaction (postCompactionSections headings in AGENTS.md) have different optimization priorities. Ensure critical instructions appear under postCompactionSections headings (default: Session Startup, Red Lines) so they survive compaction.\n\nFull audit checklist, file role definitions, and detailed workflow: Read references/identity-optimizer.md\n\nOutput Shape\nExecutive summary — what matters most + why\nTop offenders — cost drivers, context drivers, reliability risks\nOptions A/B/C — tradeoffs made explicit\nRecommended plan — smallest change first\nExact change proposals — CLI commands or config patches, all with rollback\nRollback — exact command to undo every change\n\nSources: docs.openclaw.ai, github.com/openclaw/openclaw, r/openclaw, r/myclaw, r/OpenClawUseCases" }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/jacob-bd/openclaw-optimizer", "publisherUrl": "https://clawhub.ai/jacob-bd/openclaw-optimizer", "owner": "jacob-bd", "version": "1.19.0", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/openclaw-optimizer", "downloadUrl": "https://openagent3.xyz/downloads/openclaw-optimizer", "agentUrl": "https://openagent3.xyz/skills/openclaw-optimizer/agent", "manifestUrl": "https://openagent3.xyz/skills/openclaw-optimizer/agent.json", "briefUrl": "https://openagent3.xyz/skills/openclaw-optimizer/agent.md" } }