菜单
Expert-level OpenClaw CLI configuration skill. Covers channels, models, plugins, gateway, agents, hooks, cron, security, sandbox, memory, browser, nodes, DNS, webhooks, approvals, backup, ACP provenance, ClawHub skill registry, tasks, and more. Self-evolving: updates itself after learning new patterns.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
Build premium, TV-commercial-grade product highlight-reel promo videos from a handful of screen recordings. Music-only by default (optional VO-narrated cut), HyperFrames + paused GSAP, rendered and muxed locally. Ships a full kit — 16:9 + 9:16 films and matching key-art posters — in three swappable, production-proven themes. Use when the user asks for a product promo / launch film / hero reel / app commercial / "video like <reference>" / feature sizzle from screen captures, or says "highlight reel", "product TV commercial", "aurora theme", "minimal / notion-style promo". Three theme presets: AURORA (dark, glowing, chromatic, bold), MINIMAL (light Notion-white, floating cards, one accent, confident restraint), and LINE ART (cream paper, bold navy ink, one gold accent, hand-drawn framed panels). Ships a self-contained EnConvo scaffold (bundled logo, keycaps, SFX, music bed) that reproduces the launch film by dropping in new product clips.
Turn screen recordings into polished videos — marketing promos, user guides, product demos, and more. Goal-aware pipeline: detects user intent, selects strategy, recommends a plan, then executes. Full pipeline: intent detection → strategy selection → source analysis → storyboard planning → source prep → VO generation → frame-by-frame compositing → audio mixing → final encode. Supports animated presenters (AI animal/character with rembg cutout), per-word caption sync (pop, karaoke, static styles), multi-zoom animations, overlay dissolve transitions, time-mapped VO-to-source sync, CJK-aware captions, letterbox-aware cropping, and keypress + shortcut animation overlays with frame-aligned tick/tock SFX (canonical pattern for product demos that show hotkeys; ships proven SFX library at assets/sfx/). Use when: (1) user has screen recordings and wants a polished video — marketing, tutorial, demo, or changelog, (2) user says "make a promo video", "tutorial from this recording", "TikTok video", "marketing video", "use
Unified financial analysis & portfolio management toolkit. Routes to the right sub-system based on intent. Covers: daily market briefings, macro risk monitoring, sentiment scanning, strategy evolution & signals, options analysis, 禅動 chart analysis, COT smart-money reports, and full portfolio checking (structured notes, sell puts, FX options, accumulators) with XLSX report generation. Use when user says /financial-analysis, 'daily briefing', 'morning briefing', 'macro risk', 'liquidity check', 'sentiment scan', 'market sentiment', 'evolve strategy', 'create strategy', 'strategy signal', 'what does the strategy say', 'quick look', 'scan ticker', 'ride the rally', 'catch dips', 'play safe', '禅動', 'chandong', 'analyze ticker', 'fcn check', 'fcn status', 'check fcn', 'portfolio check', 'portfolio report', 'structured products', 'are my fcns safe', 'sell puts', 'accumulators', 'options analysis', 'cot report', 'smart money'.
Visible step-by-step walkthrough mentor for live browser/app tutoring across OptionCharts.io, TradingView, and EnConvo Settings. Use when the user wants to be walked through a page, chart, setup flow, tool, or concept viewport by viewport, including options/stock analysis with option chains, GEX, DEX, open interest, max pain, Greeks, volatility, P&L charts, TradingView charts, indicators, drawing tools, watchlists, screeners, alerts, layouts, paper trading, or EnConvo setup tasks such as global providers, AI models, credentials, agents, tools, skills, shortcuts, dictation, knowledgebase, account, and developer settings.
Conduct rigorous, McKinsey-style industry / sector research and produce a structured research report. Use when the user says /industry-research-mckinsey or asks to research an industry/sector/market/value chain, wants market sizing (TAM/SAM/SOM), competitive landscape, value-chain / industry-chain analysis, profit pools, demand-supply dynamics, industry drivers, or trend/outlook analysis, or asks for a 行业研究 / 产业研究 / 行业报告 / 赛道分析 / 投研报告 / industry report / sector deep-dive / market analysis. Also fires when the user wants to find supply bottlenecks, pricing-power chokepoints, or the source of excess returns (超额收益) along a value chain (the 产业投资人 / bottleneck lens). Bilingual: follows the user's language. Do NOT use for company-only financial modeling unrelated to an industry, or for pure document formatting.
Produce multi-act long-form Mandarin financial analysis videos for social-media upload (TikTok/Bilibili/YouTube/WeChat视频号/X). Given any input source (news article, earnings call, IPO filing, macro print, chart, tweet thread, raw data), build a broadcast-grade anchor-led explainer using a locked pipeline — script in tight 5字/second cadence, render anchor with xAI Grok Imagine Video i2v with baked Mandarin VO and locked identity, composite editorial GSAP overlay panels via HyperFrames in the right 40% of frame, concat acts, mix BGM, ship MP4. Use when the user gives a finance/markets/macro/equity/options/IPO/crypto source and asks for a viral video, a 解读视频, a 拆解视频, an explainer, a TG/SNS-ready clip, or simply says "make a video about this". Also use when the user says "finance-capital-markets-video-maker", "FCM video", "market video", "anchor video", or "Vivieen video".
| name | openclaw-configure |
| description | Expert-level OpenClaw CLI configuration skill. Covers channels, models, plugins, gateway, agents, hooks, cron, security, sandbox, memory, browser, nodes, DNS, webhooks, approvals, backup, ACP provenance, ClawHub skill registry, tasks, and more. Self-evolving: updates itself after learning new patterns. |
| version | 2026.4.29 |
| author | zanearcher |
| category | infrastructure |
| openclaw_version | 2026.4.29 |
| tags | ["openclaw","cli","gateway","channels","models","plugins","agents","hooks","cron","security","sandbox","memory","browser","nodes","dns","webhooks","approvals","backup","acp","clawhub","skills","secrets","tasks"] |
Configure any aspect of OpenClaw via CLI. Battle-tested from real setup sessions.
Trigger on: "openclaw", "clawhub", "add channel", "switch model", "configure gateway", "openclaw setup", "add telegram", "switch to claude", "openclaw cron", "openclaw hooks", "openclaw doctor", "install skill", "publish skill", "search skills", or any OpenClaw/ClawHub configuration task.
Reference files (same directory as this skill):
commands.md — condensed CLI reference, all 25 domainscli-reference.md — full --help for 142+ commandsoauth2-setup.md — OAuth2 model setup guideIMPORTANT — Auto-Update Check: Before answering any OpenClaw question, Claude MUST run the Version Check & Auto-Update Protocol (see bottom of this file). This checks installed vs latest vs skill versions, asks the user whether to update if a newer version exists, and auto-syncs the skill to match the local installed version.
~/.openclaw/openclaw.json~/.openclaw/agents/<agent>/agent/models.json (auto-synced)~/.openclaw/agents/<agent>/agent/auth-profiles.json~/.openclaw/workspace/ (AGENTS.md, SOUL.md, IDENTITY.md, etc.)Many features are plugins. Before adding a channel or auth provider, check openclaw plugins list. If disabled, run openclaw plugins enable <id> first. Forgetting this causes "Unknown channel" errors.
Config changes require gateway restart:
openclaw gateway stop && sleep 2 && openclaw gateway
Or: openclaw gateway --force (kills existing, starts fresh).
openclaw.json is schema-validated. Provider blocks need the full object (baseUrl, apiKey, api, models[]). For simple values use openclaw config set. For complex objects, edit JSON directly.
channels add, models set, config set, direct JSON editsconfigure, models auth setup-token, models auth paste-token, onboardtelegram, whatsapp, discord, irc, googlechat, slack, signal, imessage, feishu, nostr, msteams, mattermost, nextcloud-talk, matrix, bluebubbles, line, zalo, zalouser, tlon, twitch
1. openclaw plugins list # check plugin status
2. openclaw plugins enable <channel> # enable if disabled
3. openclaw channels add --channel <name> --token <token> # add
4. openclaw gateway stop && sleep 2 && openclaw gateway # restart
5. openclaw channels status # verify
6. openclaw pairing list <channel> # check pending pairing
7. openclaw pairing approve <channel> <code> # approve
Telegram: Bot token from @BotFather. --token <token>. Default dmPolicy: "pairing" (users /start then get approved). Streaming: channels.telegram.streaming: "partial" (default since v2026.3.2; uses sendMessageDraft for live preview with separated reasoning/answer lanes). Lifecycle status reactions: configurable emoji for queued/thinking/tool/done/error phases. Per-topic agentId overrides for forum groups and DM topics (v2026.3.7). Voice mention gating: disableAudioPreflight to skip transcription-based mention detection. Plugin: telegram.
WhatsApp: openclaw channels login --channel whatsapp (QR code). dmPolicy: "allowlist" with E.164 numbers. selfChatMode: true for self-messaging. Plugin: whatsapp.
Discord: Bot token from Developer Portal. --token <token>. Configure guild/channel access in channels.discord.guilds. Plugin: discord.
partial or block options, configurable chunking/vc, auto-join for realtime voice conversationsavailable_tags editingidleHours default 24h) + optional maxAgeHours hard limit, /session idle + /session max-age commandsTelegram DM Topics (v2026.3.1+): Per-DM direct + topic config (allowlists, dmPolicy, skills, systemPrompt, requireTopic). DM topics route as distinct sessions.
Feishu (v2026.3.1+): Docx table creation/cell writing, image/file uploads, reactions, chat tooling, group session scopes (group/group_sender/group_topic/group_topic_sender), replyInThread config, multi-account defaultAccount routing.
iMessage: Uses imsg CLI. --cli-path imsg. dmPolicy: "allowlist". Plugin: imessage.
Signal: Needs signal-cli. --signal-number <e164>. Plugin: signal.
Matrix: --homeserver <url> --user-id <id> --password <pw> or --access-token. Plugin: matrix.
Slack: --bot-token <xoxb-...> --app-token <xapp-...>. Plugin: slack.
Route different models to different channels via channels.modelByChannel:
"channels": {
"modelByChannel": {
"discord": "anthropic/claude-opus-4-6",
"telegram": "google/gemini-3.1-pro-preview",
"whatsapp": "openai/gpt-5.3-codex"
}
}
This overrides the default model on a per-channel basis without needing separate agents.
Set outbound routing fallback per account: channels.<ch>.accounts.<id>.defaultTo for openclaw agent --deliver.
channels add --channel <name> --token <token> --account <id>
channels remove --channel <name> --account <id> --delete
channels login --channel <ch> --account <id> --verbose
channels logout --channel <ch> --account <id>
channels list --json --no-usage
channels status --probe --json --timeout <ms>
channels capabilities --channel <name> --json --target <dest>
channels resolve --channel <name> --kind <auto|user|group> --json
channels logs --channel <name> --lines <n> --json
provider/model-id: anthropic/claude-opus-4-6, ollama/minimax-m2.5:cloud, openai-codex/gpt-5.3-codex
"<provider-id>": {
"baseUrl": "<endpoint>",
"apiKey": "<key-or-placeholder>",
"api": "<api-type>",
"models": [{
"id": "<model-id>", "name": "<display>", "reasoning": bool,
"input": ["text"] or ["text","image"],
"cost": {"input":0,"output":0,"cacheRead":0,"cacheWrite":0},
"contextWindow": 200000, "maxTokens": 8192
}]
}
"anthropic-messages" — Anthropic direct + MiniMax Portal"ollama" — Ollama native (baseUrl WITHOUT /v1)"openai-completions" — OpenAI-compatibleOllama (local):
"ollama": {
"baseUrl": "http://127.0.0.1:11434", // NO /v1
"apiKey": "ollama-local", // dummy, required
"api": "ollama", // NOT "openai-chat"
"models": [{"id":"minimax-m2.5:cloud", ...}]
}
Anthropic (API key):
"anthropic": {
"baseUrl": "https://api.anthropic.com",
"apiKey": "sk-ant-api03-...",
"api": "anthropic-messages",
"models": [{"id":"claude-opus-4-6", ...}]
}
Anthropic (Claude subscription via setup-token):
claude CLI logged in with Pro/Max (/login first!)claude setup-token -> token starts with sk-ant-oat01-openclaw models auth setup-token --provider anthropic (interactive, user must run)auth-profiles.json -> anthropic:manual.tokenapi: "anthropic-messages" — OpenClaw handles bearer auth internallyOpenAI (GPT Plus via Codex OAuth):
npm i -g @openai/codexopenclaw configure -> select "OpenAI Codex" (OAuth, NOT API key)Google Gemini (subscription):
npm install -g @google/gemini-cliopenclaw plugins enable google-gemini-cli-authopenclaw configure -> Google -> "Google Gemini CLI Auth"Volcano Engine / Doubao (v2026.2.21+):
openclaw configure -> Volcano Engine -> follow onboarding auth flow"openai-completions" (OpenAI-compatible)BytePlus (v2026.2.21+):
openclaw configure -> BytePlus -> follow onboarding auth flow"openai-completions" (OpenAI-compatible)MiniMax Portal (free OAuth):
openclaw plugins enable minimax-portal-authopenclaw configure or openclaw models auth login --provider minimax-portal"anthropic-messages" (Anthropic-compatible)Kilo Code Gateway (v2026.2.23+):
openclaw configure → Kilo Gateway → follow onboarding auth flowkilocode/anthropic/claude-opus-4.6"anthropic-messages" (Anthropic-compatible routing)Vercel AI Gateway (v2026.2.23+):
vercel-ai-gateway/claude-* (auto-normalized to canonical Anthropic IDs)Switching the default model requires more than models set:
# 1. Set the new default
openclaw models set "provider/model-id"
# 2. Configure fallback chain (order matters!)
openclaw models fallbacks clear
openclaw models fallbacks add "fallback1/model"
openclaw models fallbacks add "fallback2/model"
# 3. Delete existing main session (or model identity will be stale)
# Session files: ~/.openclaw/agents/<agent>/sessions/
# Session index: ~/.openclaw/agents/<agent>/sessions/sessions.json
python3 -c "
import json, os
path = os.path.expanduser('~/.openclaw/agents/main/sessions/sessions.json')
with open(path) as f: data = json.load(f)
sid = data.pop('agent:main:main', {}).get('sessionId','')
with open(path, 'w') as f: json.dump(data, f, indent=2)
print(f'Removed session {sid}')
"
rm ~/.openclaw/agents/main/sessions/<session-id>.jsonl
# 4. Restart gateway to pick up config
openclaw gateway stop && sleep 2 && openclaw gateway
# 5. Verify
openclaw agent --agent main --message "What model are you?" --json --local 2>&1 | grep '"model"'
To remove a model entirely:
openclaw.json -> models.providers.<provider> blockopenclaw.json -> agents.defaults.models entriesopenclaw models fallbacks remove "provider/model"~/.openclaw/agents/<agent>/agent/models.json (agent-level copy)CRITICAL: When model A is in the fallback chain and OpenClaw uses it for the first API turn (system prompt delivery), the agent's identity gets baked as model A — even if model B is the configured default. Subsequent turns use model B, but the agent self-reports as model A because that's what the system prompt said.
Fix: Remove unwanted models from the fallback chain. Only keep models you're OK with the agent identifying as. The fallback chain should only contain models you actually want to fall back to.
~/.openclaw/agents/<agent>/sessions/sessions.json — maps session keys to metadata~/.openclaw/agents/<agent>/sessions/<uuid>.jsonl — JSONL with full conversationagent:<agent>:main (DM/CLI), agent:<agent>:discord:channel:<id> (per-channel), etc.systemSent flag: Tracks whether system prompt was already sent. Set to false to force re-injection.authProfileOverride: If set, LOCKS the session to a specific auth provider regardless of default model. Clear it (set to null) if session is stuck on wrong provider.sessionId → links to .jsonl file
model / modelProvider → current model (metadata, not authoritative)
systemSent → true = system prompt already sent
authProfileOverride → LOCKS provider (set null to clear)
deliveryContext → where replies go (channel, target)
totalTokens → context usage
type: "session" → header (version, ID, timestamp)
type: "model_change" → records active model/provider switch
type: "thinking_level_change" → reasoning level
type: "custom" / "model-snapshot" → model metadata at request time
type: "message" role: "user" → incoming message
type: "message" role: "assistant" → agent response (thinking + text)
type: "message" role: "toolResult" → tool/skill output
The agent's text response may not match the actual model (due to system prompt identity). Always check JSON:
openclaw agent --message "hi" --json --local 2>&1 | grep '"model"'
The "model" field in JSON is the truth. The agent's text response is just what it thinks it is based on the system prompt.
models set <provider/model> Set default model
models set-image <provider/model> Set image model
models list [--all] [--provider <name>] List models
models status [--probe] Full model + auth status
models scan Scan OpenRouter free models
models aliases [add|list|remove] Manage aliases
models fallbacks [add|list|remove|clear] Manage fallback chain
models image-fallbacks Manage image fallbacks
models auth add Interactive auth helper
models auth login --provider <id> Run OAuth flow
models auth paste-token --provider <id> Paste token (interactive)
models auth setup-token --provider anthropic Claude Code token flow
models auth order Manage auth priority
plugins list [--enabled] [--json] List all plugins
plugins enable <id> Enable plugin
plugins disable <id> Disable plugin
plugins install <spec> Install from npm/path/archive
plugins uninstall <id> Remove plugin
plugins update [id] [--all] Update npm plugins
plugins info <id> Show plugin details
plugins doctor Report load issues
Channels: telegram, whatsapp, discord, imessage, signal, slack, matrix, googlechat, msteams, mattermost, irc, nostr, feishu, line, zalo, zalouser, tlon, bluebubbles, nextcloud-talk, twitch Auth: minimax-portal-auth, google-gemini-cli-auth, google-antigravity-auth, copilot-proxy Features: memory-core, memory-lancedb, device-pair, phone-control, talk-voice, diagnostics-otel, voice-call, open-prose, lobster, llm-task, thread-ownership
gateway Start gateway (foreground)
gateway --port 18789 --force Specify port, kill existing
gateway start Start as service (launchd/systemd)
gateway stop Stop service
gateway restart Restart service
gateway install / uninstall Manage service installation
gateway status [--deep] Show status + probe
gateway health Fetch health
gateway call Call RPC method directly
gateway discover Discover via Bonjour
gateway probe Reachability + health summary
gateway usage-cost Usage cost from session logs
Built-in HTTP liveness/readiness endpoints for Docker/Kubernetes:
/health, /healthz — liveness/ready, /readyz — readiness
Fallback routing preserves existing handlers on those paths."gateway": {
"port": 18789, "mode": "local", "bind": "loopback",
"auth": {"mode":"token","token":"<token>"},
"tailscale": {"mode":"off"},
"nodes": {"denyCommands":["camera.snap","screen.record",...]}
}
agents list [--bindings] [--json] List agents
agents add Add new agent (interactive)
agents delete <id> [--force] Delete agent
agents set-identity Update name/theme/emoji/avatar
agents bindings List routing bindings
agents bind Add routing binding for an agent
agents unbind Remove routing binding for an agent
Claude 4.6 models now default to adaptive thinking level. Other reasoning-capable models default to low unless configured.
"agents": {
"defaults": {
"model": {"primary":"anthropic/claude-opus-4-6"},
"models": {"<provider/model>": {"alias":"opus"}},
"workspace": "~/.openclaw/workspace",
"compaction": {
"mode": "safeguard",
"reserveTokens": 4096,
"keepRecentTokens": 8192
},
"maxConcurrent": 4,
"subagents": {"maxConcurrent": 8, "maxSpawnDepth": 2}
}
}
Run N agents from one OpenClaw instance, each with their own Telegram bot, workspace, and identity.
# 1. Create a Telegram bot via @BotFather, get the token
# 2. Register the Telegram account
openclaw channels add --channel telegram --account <agent-id> --token "<bot-token>"
# 3. Create the agent (auto-creates workspace + agent dir)
openclaw agents add --workspace ~/.openclaw/workspace-<agent-id> --bind telegram:<agent-id> --non-interactive
# 4. Name the agent
openclaw agents set-identity # interactive — pick the agent, set name/emoji/avatar
Route channel messages to specific agents with the top-level bindings array in openclaw.json:
"bindings": [
{"agentId": "main", "match": {"channel": "telegram", "accountId": "main"}},
{"agentId": "dev", "match": {"channel": "telegram", "accountId": "dev"}},
{"agentId": "content", "match": {"channel": "telegram", "accountId": "content"}}
]
Each Telegram account routes to the matching agent. The main agent also serves as the default (no explicit rules needed beyond the binding).
CLI Management (v2026.2.26+):
openclaw agents bindings # List all bindings
openclaw agents bind --agentId <id> --channel <ch> --accountId <id>
openclaw agents unbind <agentId> --channel <ch> --accountId <id>
Features: Account-scoped route management, channel-only to account-scoped binding upgrades, role-aware binding identity handling, plugin-resolved binding account IDs, and optional account-binding prompts in openclaw channels add.
"channels": {
"telegram": {
"enabled": true,
"botToken": "<main-bot-token>",
"dmPolicy": "pairing",
"accounts": {
"main": {"enabled": true, "dmPolicy": "pairing", "botToken": "<main-token>", "groupPolicy": "open", "streamMode": "partial"},
"dev": {"enabled": true, "dmPolicy": "pairing", "botToken": "<dev-token>", "groupPolicy": "open", "streamMode": "partial"},
"content": {"enabled": true, "dmPolicy": "pairing", "botToken": "<content-token>", "groupPolicy": "open", "streamMode": "partial"}
}
}
}
The top-level botToken is for the default account. Each accounts.<id> entry gets its own bot.
Agents can delegate tasks to each other via sessions_spawn / sessions_send. Requires TWO config blocks:
1. agentToAgent (global):
"tools": {
"agentToAgent": {
"enabled": true,
"allow": ["main", "dev", "content", "ops", "law"]
}
}
2. subagents.allowAgents (per-agent):
Each agent in agents.list needs its own subagents.allowAgents listing which agents IT can reach:
{
"id": "dev",
"workspace": "~/.openclaw/workspace-dev",
"agentDir": "~/.openclaw/agents/dev/agent",
"identity": {"name": "Timothy", "emoji": "💻", "avatar": "portrait.png"},
"subagents": {"allowAgents": ["main", "content", "ops", "law"]}
}
GOTCHA: If only main has allowAgents, communication is one-way. For full mesh (any agent can reach any other), ALL agents need allowAgents.
Each agent's workspace (~/.openclaw/workspace-<id>/) should contain:
| File | Purpose |
|---|---|
SOUL.md | Personality, work style, boundaries |
IDENTITY.md | Name, role, appearance description, self-intro, resume info |
AGENTS.md | Team roster with names, workspace guide, media rules |
TOOLS.md | Local tool notes, media path instructions |
MEMORY.md | Long-term memory (agent updates this) |
portrait.png | Agent's portrait for selfie generation |
For agents to generate selfies from their portrait:
portrait.png in the agent's workspace~/.openclaw/media/<name>-portrait.png (for sending)IDENTITY.md, add a ## My Appearance section with detailed physical descriptionSOUL.md, add a ## Self-Awareness section explaining how to generate selfies and resumesidentity.avatar to portrait.png in openclaw.jsonCRITICAL: OpenClaw's assertLocalMediaAllowed() BLOCKS workspace-* directories from outbound media sending. This is hardcoded — no config override exists.
Allowed directories for outbound media:
~/.openclaw/media/ (canonical shared media dir)~/.openclaw/agents/~/.openclaw/workspace/ (default workspace ONLY, not workspace-*)~/.openclaw/sandboxes//tmp/Workaround: Agents save files in their own workspace for storage, but copy/save to ~/.openclaw/media/ when they need to SEND media via Telegram/WhatsApp.
sessions_spawn requires operator.write scope on the device. If the device was paired before multi-agent was configured, it may only have operator.admin, operator.approvals, operator.pairing, operator.read.
Fix: Edit ~/.openclaw/devices/paired.json — add operator.write to both the top-level scopes array AND tokens.operator.scopes. Also update ~/.openclaw/identity/device-auth.json. Clear ~/.openclaw/devices/pending.json ({}). Restart gateway.
After config changes (identity, workspace files), clear agent sessions so they pick up fresh context:
echo '{}' > ~/.openclaw/agents/<agent>/sessions/sessions.json
This forces a new session with updated SOUL.md/IDENTITY.md on next message.
openclaw agent \
--agent <agent-id> \
--message "Your message" \
--channel telegram \
--deliver \
--reply-account <agent-id> \
--to <user-phone-or-chat-id>
--agent overrides routing bindings--deliver sends the reply to the channel (not just stdout)--reply-account selects which Telegram bot sends the reply--channel defaults to whatsapp if not specifiedconfig get <dot.path> Read config value
config set <dot.path> <value> Set config value
config unset <dot.path> Remove config value
config file Print active config file path (v2026.3.1+)
configure [--section <name>] Interactive wizard
Sections: workspace, model, web, gateway, daemon, channels, skills, health
agents.defaults.model.primary Default model
channels.<ch>.enabled Channel on/off
channels.<ch>.dmPolicy pairing|allowlist|open
channels.<ch>.allowFrom Allowed senders
gateway.port Gateway port
plugins.entries.<id>.enabled Plugin on/off
messages.tts.edge.enabled TTS on/off
cron list [--all] [--json] List jobs
cron add --name <n> --cron <expr> --message <text> [--deliver] [--tz <iana>]
cron rm <id> Remove job
cron enable/disable <id> Toggle job
cron run <id> Run now (debug)
cron edit Patch fields
cron runs Run history
cron status Scheduler status
Schedule types: --at (one-shot ISO 8601), --every (interval ms), --cron (5-field expr)
hooks list [--eligible] [--json] List hooks
hooks enable / disable Toggle hook
hooks info Hook details
hooks install <spec> Install hook pack
hooks check Check eligibility
hooks update Update npm hooks
security audit [--deep] [--fix] [--json] Audit config + state
Best practices: chmod 700 ~/.openclaw, bind gateway to loopback, use allowlist/pairing dmPolicy, restrict node commands with denyCommands.
Major security overhaul with 40+ fixes:
BASH_ENV, ENV, BASH_FUNC_*, LD_*, DYLD_*)file:, data:, javascript: protocols blockedsystem.run approved scripts pinned to on-disk file snapshots — post-approval rewrites denied before executiongroupPolicy: "allowlist" now enforces sender allowlists even when route allowlists are configured0600), directories to 0700Replace the old boolean DM toggle with explicit policy field:
"agents": {
"defaults": {
"heartbeat": {
"directPolicy": "allow" // "allow" (default) | "block"
}
}
}
Also supported per-agent via agents.list[].heartbeat.directPolicy. Default is allow (DMs permitted).
Cap parent-session token inheritance for thread sessions to avoid bricking new threads:
"session": {
"parentForkMaxTokens": 100000 // default 100000; set 0 to disable limit
}
For shared-user setups (multiple people using one OpenClaw instance):
"security": {
"trust_model": {
"multi_user_heuristic": true
}
}
When enabled, flags likely shared-user ingress and provides hardening guidance. For intentional multi-user deployments: sandbox.mode="all", workspace-scoped FS, reduced tool surface, avoid personal/private identities on shared runtimes.
sandbox list [--browser] [--json] List containers
sandbox recreate [--all] [--session <id>] Force recreation
sandbox explain Explain effective policy
Config: tools.sandbox.tools.allow / tools.sandbox.tools.deny
memory search <query> [--query <text>] [--max-results <n>] Search memory (positional or --query)
memory index [--force] Reindex files
memory status [--json] Index status
Requires embedding provider (OpenAI/Gemini key or local). Plugin: memory-core (default), memory-lancedb (advanced).
unavailable warnings from memory_search on embedding/provider failuresmessage send --channel <ch> --target <dest> --message <text> [--media <path>] [--json]
message read --channel <ch> --target <dest> [--limit <n>]
message edit / delete / broadcast / search
message react --emoji <emoji> --message-id <id>
message poll --poll-question <text> --poll-option <opt>
message pin / unpin / pins
message ban / kick / timeout Moderation
message thread / channel / member / role / emoji / sticker / event / voice
pairing list [channel] Pending requests
pairing approve <channel> <code> Approve sender
devices list [--json] List devices
devices approve / reject Handle pairing
devices remove <id> Remove device
devices revoke / rotate Token management
devices clear Clear all
directory self [--channel <name>] Own IDs
directory peers list [--channel <name> --query <text>]
directory groups list [--channel <name>]
directory groups members [--channel <name> --group-id <id>]
browser start/stop/status Lifecycle
browser open <url> / close / tabs / focus / navigate
browser screenshot [--full-page] / snapshot [--format ai|aria]
browser click <ref> / type <ref> <text> / press <key> / hover / drag / select
browser fill --fields <json> / upload <path> / dialog --accept
browser wait --text <text> / evaluate --fn <js>
browser console / errors / requests / cookies / storage
browser resize <w> <h> / pdf / download
browser profiles / create-profile / delete-profile / reset-profile
browser extension / responsebody / waitfordownload / trace
v2026.3.8 config:
browser.relayBindHost — bind Chrome relay to explicit non-loopback address for WSL2/cross-namespace setups (default: loopback only)node run [--host <ip> --port <port>] Start node host (foreground)
node install / uninstall / restart / stop / status
nodes list [--connected] List gateway nodes
nodes status / pending Connection + pairing status
nodes approve / reject / rename Manage pairing
nodes describe Node capabilities
nodes invoke --node <id> --command <cmd> --params <json>
nodes run --node <id> --raw <cmd> Shell command (mac only)
nodes camera / canvas / screen / location / notify / push
secrets audit [--deep] [--fix] Audit secrets storage
secrets configure Interactive secrets setup
secrets apply [--file <path>] Apply secrets snapshot (target-path validation)
secrets reload Hot-reload running gateway secrets
Features: Full external secrets management workflow with runtime snapshot activation, strict target-path validation, safer migration scrubbing, ref-only auth-profile support, and dedicated docs.
dns setup --domain <domain> [--apply] CoreDNS for wide-area Bonjour
approvals get Fetch exec approvals
approvals set Replace from JSON file
approvals allowlist Edit per-agent allowlist
system event Enqueue system event
system heartbeat [enable|disable|last] Heartbeat controls
system presence [--json] Presence entries
webhooks gmail Gmail Pub/Sub hooks (via gogcli)
acp [--url --token --session --verbose] Run ACP bridge
acp client Interactive ACP client
acp --provenance off|meta|meta+receipt ACP provenance mode (v2026.3.8+)
NEW in v2026.2.26: ACP agents are now first-class runtimes for thread sessions with acp spawn/send dispatch integration, acpx backend bridging, lifecycle controls, startup reconciliation, runtime cleanup, and coalesced thread replies. Thread-bound subagents can now be dispatched via ACP for enhanced realtime capabilities.
NEW in v2026.3.8: ACP provenance metadata — agents can retain and report ACP-origin context with session trace IDs. Modes: off (disabled), meta (ingress metadata only), meta+receipt (metadata + visible receipt injection).
openclaw skills)OpenClaw's built-in skill commands manage locally installed skills at runtime:
skills list [--eligible] [--json] List skills available to agents
skills info <name> Skill details + requirements
skills check Check which skills are ready vs missing requirements
Relationship to ClawHub: openclaw skills reads from the local skills directory. clawhub (separate CLI) manages the registry — install, publish, search, update. Typical flow:
clawhub install <slug> # download skill from ClawHub registry
openclaw skills list # verify it appears locally
openclaw skills check # confirm requirements met
openclaw gateway stop && openclaw gateway # restart to pick up new skill
See the ClawHub section below for the full registry CLI.
update [--channel stable|beta|dev --yes] Update OpenClaw
update status Version + channel status
update wizard Interactive update
doctor [--fix] [--deep] Health checks + fixes
health [--json] Gateway health
status [--deep] [--usage] Channel health + sessions
logs [--follow] [--limit <n>] Tail gateway logs
backup create [--only-config] [--no-include-workspace] Create local state archive
backup verify <path> Validate manifest + payload of archive
Features: Full local backup of OpenClaw state (config, workspace, agents). --only-config for config-only snapshots. Archives named for date sorting. Guidance shown in destructive flows (reset, uninstall).
The web_search tool is configured via tools.web.search. The config path is tools.web.search, NOT tools.webSearch (which is rejected by schema validation).
Supported providers (v2026.3.8): brave, perplexity, grok, gemini, kimi
GOTCHA: Tavily is NOT a valid native provider in v2026.3.8. A community PR (#11978) adds Tavily support — expected in v2026.3.9+. Until then, use the openclaw-tavily plugin from ClawHub or set TAVILY_API_KEY env var with the plugin installed.
Default behavior: If no provider is configured, agents use whatever search grounding their model provider offers (e.g., Gemini uses Google Search grounding natively).
Setting a provider:
openclaw config set tools.web.search.provider gemini
Provider-specific config:
# Brave with LLM Context mode
openclaw config set tools.web.search.provider brave
openclaw config set tools.web.search.brave.mode llm-context
# Perplexity
openclaw config set tools.web.search.provider perplexity
# Requires PERPLEXITY_API_KEY env var or config
# Grok
openclaw config set tools.web.search.provider grok
# Requires GROK_API_KEY env var or config
# Kimi
openclaw config set tools.web.search.provider kimi
| Config Path | Type | Description |
|---|---|---|
talk.silenceTimeoutMs | number | How long Talk mode waits for silence before auto-sending transcript. Platform default used when unset. |
tools.web.search.provider | string | Web search provider: brave, perplexity, grok, gemini, kimi. NOT tavily in v2026.3.8. |
tools.web.search.brave.mode | string | Set to "llm-context" to use Brave's LLM Context endpoint (returns extracted grounding snippets with source metadata instead of raw search results). |
browser.relayBindHost | string | Bind Chrome relay to non-loopback address for WSL2/cross-namespace setups. Default: loopback only. |
TUI theme (v2026.3.8+): Auto-detects light terminal backgrounds via COLORFGBG and picks a WCAG AA-compliant light palette. Override with OPENCLAW_THEME=light|dark.
dashboard Open Control UI
tui [--session <key>] Terminal UI
sessions [--active <min>] List sessions
sessions cleanup [--agent <id>] [--max-disk-bytes <n>] Clean up old sessions (v2026.2.23+)
agent --to <num> --message <text> [--deliver] [--thinking <level>] Run agent turn
onboard [--flow quickstart|advanced] Onboarding wizard
setup [--mode local|remote] Init config + workspace
reset [--scope config|full] Reset state
uninstall [--all] Remove gateway + data
qr [--json] iOS pairing QR
completion Shell completion
docs <query> Search live docs
Manage credentials and auth profiles via external secrets providers (HashiCorp Vault, AWS Secrets Manager, etc.)
openclaw secrets audit # Audit current secrets storage
openclaw secrets configure # Interactive setup wizard
openclaw secrets apply --file <path> # Apply snapshot with strict target-path validation
openclaw secrets reload # Hot-reload running gateway
Key Features:
$secret:provider/path syntaxExample Auth Profile with External Secret:
"auth-profiles.json": {
"anthropic:vault": {
"type": "anthropic-bearer",
"key": "$secret:vault/secret/data/anthropic#api_key"
}
}
Separate CLI from OpenClaw. Manages the ClawHub skill marketplace — install, search, publish, and browse community skills.
CLI: clawhub (v0.6.1)
Trigger on: "clawhub", "install skill", "publish skill", "search skills", "browse skills", "skill registry"
--workdir <dir> Working directory (default: cwd)
--dir <dir> Skills directory (relative to workdir, default: skills)
--site <url> Site base URL (for browser login)
--registry <url> Registry API base URL
--no-input Disable prompts
CLAWHUB_SITE Site base URL
CLAWHUB_REGISTRY Registry API base URL
CLAWHUB_WORKDIR Working directory
(CLAWDHUB_* also supported)
login [--token <token>] [--label <label>] [--no-browser]
Log in (opens browser or stores token)
--token: API token (skip browser)
--label: Token label for browser flow (default: "CLI token")
--no-browser: Don't open browser (requires --token)
logout Remove stored token
whoami Validate token
auth login [options] Same as top-level login
auth logout Same as top-level logout
auth whoami Same as top-level whoami
explore [--limit <n>] [--sort <order>] [--json]
Browse latest updated skills from the registry
--limit: Number of skills (max 200, default 25)
--sort: newest|downloads|rating|installs|installsAllTime|trending (default: newest)
search <query...> [--limit <n>]
Vector search skills by query string
inspect <slug> [options]
Fetch skill metadata and files without installing
--version <version> Version to inspect
--tag <tag> Tag to inspect (default: latest)
--versions List version history (first page)
--limit <n> Max versions to list (1-200)
--files List files for the selected version
--file <path> Fetch raw file content (text <= 200KB)
--json Output JSON
install <slug> [--version <version>] [--force]
Install skill into <dir>/<slug>
--version: Specific version to install
--force: Overwrite existing folder
update [slug] [--all] [--version <version>] [--force]
Update installed skills
--all: Update all installed skills
--version: Update to specific version (single slug only)
--force: Overwrite when local files don't match any version
list List installed skills (from lockfile)
publish <path> [options]
Publish skill from folder
--slug <slug> Skill slug
--name <name> Display name
--version <version> Version (semver)
--fork-of <slug[@version]> Mark as fork of existing skill
--changelog <text> Changelog text
--tags <tags> Comma-separated tags (default: "latest")
sync [options] Scan local skills and publish new/updated ones
--root <dir...> Extra scan roots (one or more)
--all Upload all new/updated without prompting
--dry-run Show what would be uploaded
--bump <type> Version bump: patch|minor|major (default: patch)
--changelog <text> Changelog for updates (non-interactive)
--tags <tags> Comma-separated tags (default: "latest")
--concurrency <n> Concurrent registry checks (default: 4)
star <slug> [--yes] Add a skill to your highlights
unstar <slug> [--yes] Remove a skill from your highlights
delete <slug> [--yes] Soft-delete a skill
hide <slug> [--yes] Hide a skill
undelete <slug> [--yes] Restore a deleted skill
unhide <slug> [--yes] Unhide a hidden skill
ban-user <handleOrId> [options] Ban user and delete owned skills
--id: Treat argument as user id
--fuzzy: Fuzzy user search (admin only)
--reason <reason>: Ban reason
--yes: Skip confirmation
set-role <handleOrId> <role> Change user role: user|moderator|admin (admin only)
--id: Treat argument as user id
--fuzzy: Fuzzy user search (admin only)
--yes: Skip confirmation
Browse and install a skill:
clawhub explore --sort trending --limit 10 # browse popular skills
clawhub inspect <slug> --files # preview files before install
clawhub install <slug> # install to ./skills/<slug>
Publish a skill:
clawhub login # authenticate first
clawhub publish ./my-skill --slug my-skill --name "My Skill" --version 1.0.0
Bulk sync local skills:
clawhub sync --dry-run # preview what would be published
clawhub sync --all --bump patch # publish all new/updated
Update all installed skills:
clawhub update --all
| Symptom | Cause | Fix |
|---|---|---|
| "Unknown channel: X" | Plugin disabled | openclaw plugins enable X |
| 401 Invalid bearer token | setup-token from unauthenticated Claude Code | /login in Claude Code first, regenerate token |
| "Config validation failed" | Incomplete provider block | Need full: baseUrl, apiKey, api, models[] |
| Gateway won't start / port in use | Existing process | openclaw gateway --force |
| Channel status: no messages | Gateway not restarted | Restart after config changes |
| Ollama "Unknown model" | Missing apiKey | apiKey: "ollama-local" (dummy) |
| Ollama wrong api | Used "openai-chat" | Must be "ollama", baseUrl without /v1 |
| "BOT_COMMANDS_TOO_MUCH" (Telegram) | Too many slash commands | Non-blocking, ignore |
| OAuth token expired | Past expiry | Re-run: openclaw models auth login --provider <id> |
| "Gateway service not loaded" | Service vs foreground mismatch | Use gateway --force or install service |
| Agent reports wrong model after switch | Old session has stale system prompt | Delete session from sessions.json + remove .jsonl file, restart gateway |
| Model switched but agent still uses old one | authProfileOverride locked to old provider | Set authProfileOverride: null in sessions.json, or delete session |
| Fallback model used for first turn | OpenClaw tries fallback for system prompt delivery | Remove unwanted models from fallback chain (models fallbacks remove) |
models set works but agent ignores it | Gateway cached old config in memory | Full restart: gateway stop && sleep 2 && gateway install |
| JSON shows correct model but text says wrong | System prompt identity baked from first-turn model | Delete session for clean start; check grep '"model"' in JSON for truth |
sessions_spawn fails "pairing required" (1008) | Device missing operator.write scope | Add operator.write to devices/paired.json (scopes + tokens.operator.scopes) and identity/device-auth.json, clear devices/pending.json, restart gateway |
| Agent refuses to retry after prior failure | Persistent session remembers past errors | Clear session: echo '{}' > ~/.openclaw/agents/<agent>/sessions/sessions.json |
| Media "not under an allowed directory" | workspace-* dirs blocked by assertLocalMediaAllowed() | Save media to ~/.openclaw/media/ for sending. No config override exists |
| Agent defaults to wrong channel (e.g. WhatsApp) | openclaw agent defaults to --channel whatsapp | Always specify --channel telegram --reply-account <id> |
sessions_spawn works from main but not between other agents | Only main has subagents.allowAgents | Add subagents.allowAgents to ALL agents that need to spawn others |
openclaw gateway stop doesn't kill old process | PID still holding port | kill -9 <pid> then openclaw gateway install --force |
| Config changes not taking effect after restart | Old gateway process still running on port | Check lsof -i :18789, kill stale PID, then restart |
iMessage imsg rpc exited (code 1) in gateway health | Node.js LaunchAgent lacks Full Disk Access to chat.db | System Settings → Privacy & Security → Full Disk Access → add /opt/homebrew/bin/node (symlink survives upgrades) |
| Heartbeat sending to DMs (v2026.2.25+) | Default is allow again (v2026.2.24 block is reverted) | To block DM heartbeat: set agents.defaults.heartbeat.directPolicy: "block" (or per-agent agents.list[].heartbeat.directPolicy) |
Browser network: "container:<id>" blocked | BREAKING: Docker container-namespace join blocked by default | Set agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true to re-enable |
| Browser SSRF private network errors (v2026.2.23+) | BREAKING: browser.ssrfPolicy.allowPrivateNetwork renamed | Use browser.ssrfPolicy.dangerouslyAllowPrivateNetwork; run openclaw doctor --fix to auto-migrate |
memory search "query" errors | v2026.2.24+ accepts both positional and --query <text> | Both forms work: memory search "text" or memory search --query "text" |
Secrets apply fails with "invalid target" | Target path doesn't exist or is restricted | Run openclaw secrets audit to see valid paths; use --fix to auto-correct |
Secrets not reloading after apply | Gateway not responding to reload signal | Run openclaw secrets reload or restart gateway manually |
| ACP agent won't initialize in thread | Missing startup reconciliation config | Ensure agent has subagents.allowAgents includes the ACP agent ID |
| Thread-bound subagent spawns to wrong channel | ACP dispatch not honoring thread context | Check acp config in agent workspace and verify thread session metadata |
| Bindings command errors with "account not found" | Plugin registry hasn't populated account IDs | Run openclaw plugins doctor to check plugin health and retry bindings command |
| BREAKING Node exec approval fails (v2026.3.1+) | Approval payloads now require systemRunPlan | Add systemRunPlan to node host=node approval requests |
BREAKING Node system.run path mismatch (v2026.3.1+) | Commands now pinned to canonical realpath | Update allowlists/tests to use canonical paths (e.g. /usr/bin/tr not tr) |
| OpenAI streaming fails silently (v2026.3.1+) | WebSocket transport is now default for OpenAI | Set params.openaiWsWarmup: false per-model if WS issues; or configure transport: "sse" to force SSE |
| Gateway WS insecure on private network (v2026.3.1+) | Plaintext ws:// now loopback-only by default | Set OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 for private network access |
| Cron job runs at ~1/3 of configured timeout (v2026.3.1+) | Stale CLI session ID reused | Fixed in v2026.3.1 — isolated cron runs use fresh watchdog profiles |
cron run returns 0 on failure | Exit code was always 0 | Fixed in v2026.3.1 — returns exit 1 for non-run/error outcomes |
(npm jumped 4.27 → 4.29; no 4.28 published.)
tools.exec / tools.fs sections stop implicitly widening the messaging and minimal profiles. Add explicit alsoAllow entries to keep behavior. Startup warning identifies affected configs.steer (v2026.4.29): messages.queue now defaults to steer (drains all pending Pi steering messages at the next model boundary) with a 500ms followup-fallback debounce. Legacy one-at-a-time behavior is queue.openclaw doctor --fix now migrates legacy messages.tts.enabled, agent TTS, channel TTS, and voice-call plugin TTS toggles to auto mode.agents.defaultId no longer accepted (v2026.4.29): Use agents.list[].default for Set Default. Old field is rejected by config validation.Providers / Models:
NVIDIA_API_KEY onboarding, setup docs, static catalog metadata, literal model-ref picker support so NVIDIA-hosted models can be selected with prefix intact. Bundled NVIDIA Chat Completions models marked as string-content compatible (fixes NIM model loading and OpenAI-compatible subagent calls).xhigh / max thinking (v2026.4.29): Native thinking levels exposed through resolveThinkingProfile. /think xhigh|max now applies intended effort instead of falling back.xhigh, adaptive, and max thinking profile exposed for Bedrock Claude Opus 4.7. Sonnet/Opus 4.6 stay on adaptive-by-default. Bedrock omits deprecated temperature for Opus 4.7 model ids./think xhigh for trusted OpenAI/Codex upstream refs; Claude adaptive thinking for Anthropic upstream refs.models.providers.<id>.models.<id>.compat.supportedReasoningEfforts entries that include xhigh so /think xhigh is exposed and validated consistently across command menus, Gateway sessions, agent CLI, and llm-task.openai-codex/gpt-5.4-mini restored (v2026.4.29): Live OAuth proof restored for ChatGPT/Codex OAuth PI runs. Manifest, forward-compat metadata, docs, and regression tests aligned. Stale cron and heartbeat configs resolve again.gpt-5.4-mini inline suppression (v2026.4.29): Explicitly configured openai-codex/gpt-5.4-mini inline entries are suppressed so a stale models config written by openclaw doctor --fix cannot bypass the manifest capability block."yuanbao" alias; plugin moved to YuanbaoTeam/yuanbao-openclaw-plugin.Memory / People Wiki:
activeMemory.allowedChatIds / deniedChatIds filters so operators enable recall only for selected DMs, groups, or channels.doctor.memory.remHarness RPC for previewing bounded REM dreaming output without running mutation paths.memory.qmd.update.startup (v2026.4.29): Make gateway-start QMD refresh opt-in. Normal memory access stays lazy.openclaw ltm list (v2026.4.29): Returns real memory records (with --limit and createdAt ordering) instead of placeholder.Agents / Commitments:
commitments.enabled / commitments.maxPerDay config. Hidden batched extraction, per-agent/per-channel scoping, heartbeat delivery, CLI management, and heartbeat-interval due-time clamping (so check-ins don't echo immediately).messages.visibleReplies (v2026.4.29): Global require-visible-output gate. Forces replies through message(action=send) for any source chat. messages.groupChat.visibleReplies stays as group/channel override.spawnedBy on subagent events (v2026.4.29): Subagent chat and agent broadcast payloads now carry spawnedBy so clients can route child session events without an extra session lookup.heartbeat.skipWhenBusy (v2026.4.29): Defer heartbeat turns while cron is active or queued. Retries busy skips without advancing the schedule. Local Ollama hosts no longer run heartbeat and cron concurrently.Gateway / Diagnostics:
/readyz (v2026.4.29): Local or authenticated /readyz now includes eventLoop block (delay p99/max, utilization, CPU core ratio, degraded flag).gateway.handshakeTimeoutMs (v2026.4.29): Configurable WebSocket pre-auth handshake timeout (env OPENCLAW_HANDSHAKE_TIMEOUT_MS still wins). Loaded/low-powered hosts can tune without patching dist files. Pre-auth timeout raised to 15s.deferralTimeoutMs: 0 still indefinite).CLI / Migration:
openclaw plugins deps (v2026.4.29): New inspection and repair subcommand with script-free package-manager defaults so operators can repair missing bundled runtime deps without corrupting JSON output.openclaw infer image describe flags (v2026.4.29): --prompt and --timeout-ms for media-understanding providers (Ollama, OpenAI, Google, OpenRouter).openclaw infer model run images (v2026.4.29): Repeatable --file inputs for local/gateway multimodal model smokes (Ollama Qwen VL, Gemini, etc.).OPENCLAW_SKIP_ONBOARDING Docker env (already in 4.27, restated): Automated Docker installs skip interactive onboarding while still applying gateway defaults.Channels:
getUpdates after startup grace, transport activity is stale, or setWebhook has not completed after grace.QUOTE_TEXT_INVALID, retries native quote replies without reply_parameters.quote so stale/truncated excerpts don't drop the whole reply.commands.ownerAllowFrom and auto-enables the approval client when an owner resolves. Owner-only /diagnostics etc. can be approved in Telegram without per-channel approver config./gateway/bot metadata fetches now cool down properly. New channels.discord.applicationId for app-id lookup bypass. HTML bodies sanitized before logging.GuildVoiceStates gateway intent. Bounded /gateway/bot metadata timeout with rate-limited fallback logs.web.whatsapp.* keepalive, connect, and query timeout settings.already_reacted idempotent (v2026.4.29): Repeated reaction adds no longer surface as tool failures.openclaw matrix verify confirm-sas now completes the cross-signing handshake.Security:
<system-reminder> strip on outbound (v2026.4.29): Internal runtime scaffolding stripped at the final channel delivery boundary so degraded harness replies can't leak those tags.dmPolicy="open" tightened (v2026.4.29): Fails closed when account-level public DM settings conflict with restrictive top-level allowFrom. Requires effective wildcard before dmPolicy="open" is public.dmPolicy="open" is public only with effective wildcard; otherwise still respects sender allowlists./focus boundary (v2026.4.29): Leaf subagents rejected from /focus; fallback target resolution scoped to requesting subagent's children.operator.admin, operator.pairing, or node.exec.ALL_PROXY / OPENCLAW_PROXY_URL (v2026.4.29): Honored when constructing the HTTP/1-only Telegram Bot API transport so Windows/service installs don't fall back to direct egress.content_block_start is preserved so [thinking, text] replies don't persist as empty turns.input: []).Unexpected end of JSON input from split proxies.<final> tag splitting on streaming (v2026.4.29): Stripped before reaching SSE clients so /v1/chat/completions no longer emits tag remnants when final-answer wrappers cross chunk boundaries.:cloud model resolution (v2026.4.29): Resolves explicitly selected signed-in :cloud models through /api/show when /api/tags omits them. Models like gemini-3-flash-preview:cloud and deepseek-v4-pro:cloud no longer fail dynamic resolution.functions.exec to exec at the native stream boundary.require() for bundled plugin modules on Windows. Startup ~39s → ~2s on typical 6-plugin setups.--attach-only / --no-launchd no longer uninstall the Gateway LaunchAgent or drop active sessions.file:// lookup failures.processing.| Config Path | Type | Description |
|---|---|---|
commitments.enabled | boolean | Opt-in inferred follow-up commitments |
commitments.maxPerDay | number | Cap on commitments per day |
messages.queue | string | steer (default v2026.4.29) | queue | replace | coalesce | drop |
messages.visibleReplies | string | Global require-visible-output gate (auto | tool-only) |
activeMemory.allowedChatIds | array | Per-conversation Active Memory recall whitelist |
activeMemory.deniedChatIds | array | Per-conversation Active Memory recall blacklist |
memory.qmd.update.startup | boolean | Opt-in QMD refresh at gateway start (default off) |
gateway.handshakeTimeoutMs | number | WebSocket pre-auth handshake timeout (default 15s) |
tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange | boolean | Allow fc00::/7 for trusted fake-IP proxy stacks |
web.whatsapp.keepalive.* / connect.* / query.* | numbers | WhatsApp Web Baileys socket timings |
channels.discord.applicationId | string | Bypass /gateway/bot app-id lookup |
heartbeat.skipWhenBusy | boolean | Defer heartbeat while cron/subagent lanes are busy |
agents.list[].default | boolean | Set the default agent (replaces deprecated agents.defaultId) |
| Symptom | Cause | Fix |
|---|---|---|
tools.exec / tools.fs config under messaging profile silently no-ops | v2026.4.29 stops implicit profile widening | Add explicit alsoAllow entries; check startup warning for affected configs |
agents.defaultId rejected by config validation | Field deprecated in v2026.4.29 | Use agents.list[].default: true instead |
| Telegram messages flicker between draft and message | Pre-v2026.4.29 used native draft state for streaming previews | Upgrade to v2026.4.29+ — uses durable message edits |
| Telegram polling claims healthy but messages stop flowing | Silent polling failure | v2026.4.29 surfaces polling liveness warnings in channel status / doctor |
Slack message rejected with msg_too_long | Long context fallback not capped | v2026.4.29 caps Block Kit fallback while preserving rendered blocks |
| Discord startup failing on Cloudflare 429 HTML | Pre-v2026.4.29 didn't cool down HTML 429s | v2026.4.29 honors Retry-After + falls back to conservative cooldown; set channels.discord.applicationId to bypass |
| WhatsApp transport silently dies after 408 reconnect | Listeners didn't recover when frames kept arriving but app messages stopped | Fixed v2026.4.29 |
Unknown package 'sqlite-vec' after upgrade | Memory bundled-plugin dep not mirrored | Fixed v2026.4.29 — mirrored into runtime deps |
Ollama signed-in :cloud model fails to load | /api/tags omitted the model | v2026.4.29 falls through to /api/show |
[assistant copied inbound metadata omitted] in chat output | Metadata-only assistant replay turns leaked as model output | Fixed v2026.4.29 — dropped before provider replay |
Discord/Slack dmPolicy="open" allowing all senders despite allowFrom | Pre-v2026.4.29 inconsistent semantics | v2026.4.29 — dmPolicy="open" is public only with effective wildcard; otherwise still respects allowlists |
| Group-scoped tool policy applied to forged group ID | Caller group IDs not validated | Fixed v2026.4.29 — validated against session/spawned context |
Bootstrap approval persistently grants operator.admin | Pairing scopes weren't capped | Fixed v2026.4.29 — bounded to documented per-role allowlist |
<final> or <system-reminder> tag remnants in user-facing replies | Pre-v2026.4.29 didn't strip across chunk boundaries | Fixed v2026.4.29 |
Bedrock Opus 4.7 /think xhigh doesn't take effect | Pre-v2026.4.29 only adaptive exposed | Fixed v2026.4.29 — full xhigh/adaptive/max profile |
models list shows providers user has not authenticated | UI was always-show | Fixed v2026.4.29 — hides unauthenticated providers from default; use models list --all to browse all |
messages.groupChat.visibleReplies: "automatic"./reset and /new no longer fall through (v2026.4.27): Bare /reset / /new stop after reset hooks acknowledge — no empty provider call. /reset <message> and /new <message> still seed the next turn./new. Typed /new and /reset commands stay immediate.session.maintenance.rotateBytes deprecated (v2026.4.27): Auto-rotation of oversized sessions.json removed. openclaw doctor --fix strips the ignored key.openclaw <parent> (memory, channels, plugins, approvals, devices, cron, mcp) without subcommand now prints help and exits 0 (was 1). Fixes shell && chains and pnpm wrappers.Providers / Models:
DEEPINFRA_API_KEY onboarding, dynamic OpenAI-compatible model discovery, image generation/editing, image/audio media understanding, TTS, text-to-video, memory embeddings.openclaw-plugin-yuanbao) registered in official channel catalog. WebSocket bot DMs and group chats.stream_messages streaming, unified sendMedia with chunked upload./codex computer-use status/install, marketplace discovery, optional auto-install, fail-closed MCP server checks before Codex-mode turns.openclaw matrix encryption setup enables E2EE, bootstraps recovery, prints verification status from one flow.openclaw migrate with plan/dry-run/JSON, pre-migration backup, archive-only reports. Imports Claude Code/Desktop instructions, MCP servers, skills, command prompts. Bundled Hermes importer for config, memory/plugin hints, model providers, MCP, skills, credentials.Gateway / Security:
proxy.enabled + proxy.proxyUrl / OPENCLAW_PROXY_URL with strict http:// forward-proxy validation, loopback-only Gateway bypass, cleanup on exit.sandbox.docker.gpus for Docker sandbox containers when host Docker supports --gpus.trustedProxy.allowLoopback (v2026.4.27): Explicit support for same-host loopback reverse proxies. Loopback trusted-proxy auth fails closed by default.models.pricing.enabled (v2026.4.27): Set false to skip startup OpenRouter and LiteLLM pricing-catalog fetches. Useful for offline / restricted-network installs.Memory:
memorySearch.inputType (v2026.4.26): Optional inputType, queryInputType, documentInputType for asymmetric embedding endpoints. Includes direct query embeddings + provider batch indexing.nomic-embed-text, qwen3-embedding, mxbai-embed-large queries. Document batches unchanged.memorySearch.recallMaxChars (v2026.4.27): Bound memory recall embedding queries. Auto-recall now prefers the latest user message over channel prompt metadata. Helps small Ollama embedding models avoid context-length failures.Telegram / Channels:
--thread-id for cron (v2026.4.27): openclaw cron add / cron edit accept --thread-id for Telegram forum topic delivery preservation across scheduled announcements.tts.voice.preferAudioFileFormat.channels.whatsapp.accounts.<id>.groups.<id>.systemPrompt and direct.<id>.systemPrompt forwarded as GroupSystemPrompt ("*" wildcard supported).Compaction / Sessions:
compaction.maxActiveTranscriptBytes preflight trigger (v2026.4.26): Opt-in. Runs normal local compaction when active JSONL grows too large. Successful compaction moves future turns onto a smaller successor file instead of raw byte-splitting.compaction.memoryFlush.model override (v2026.4.27): Use exact override (e.g. ollama/qwen3:8b) without inheriting active session fallback chain. Lets local housekeeping avoid paid conversation models.reasoning_content backfilled on plain assistant replay messages, not just tool-call turns. Fixes thinking sessions with prior tool use failing follow-up requests.new session no longer leak into the fresh model turn.clientPingTimeout / serverPingTimeout / pingPongLoggingEnabled overrides. Stale-websocket handling decoupled from app-event health heuristics.RangeError: Maximum call stack size exceeded on PDF/image uploads.getMe with 401. Surface as token auth failure instead of misleading deleteWebhook cleanup error./bot<TOKEN> apiRoot fix (v2026.4.27): Normalize accidental full-token apiRoot values at runtime. openclaw doctor --fix strips the suffix.cron.add infers creating session's agentId when omitted. Scheduled agentTurn jobs route to session agent.openclaw memory / channels / plugins / etc. without subcommand prints help and exits 0.chat.history no longer expose them as normal user turns.node_modules (v2026.4.27): Skips installed plugin dependency trees but keeps manifests + source files. Avoids rebuildable npm payload bloat.| Config Path | Type | Description |
|---|---|---|
proxy.enabled | boolean | Enable operator-managed outbound proxy routing |
proxy.proxyUrl (or OPENCLAW_PROXY_URL env) | string | Forward proxy URL (must be http://) |
sandbox.docker.gpus | string | GPU passthrough for Docker sandbox containers |
models.pricing.enabled | boolean | Skip startup OpenRouter/LiteLLM pricing fetches |
messages.groupChat.visibleReplies | string | "silent" (default v2026.4.27) or "automatic" |
tts.voice.preferAudioFileFormat | string | Opt-in opus-in-CAF for iMessage native voice memo |
agents.defaults.compaction.maxActiveTranscriptBytes | number | Preflight trigger for transcript rotation |
agents.defaults.compaction.memoryFlush.model | string | Override flush model without inheriting session fallback chain |
memorySearch.inputType / queryInputType / documentInputType | string | Asymmetric embedding endpoint hints |
memorySearch.recallMaxChars | number | Cap memory recall embedding query size |
streaming.preview.toolProgress | boolean | Stream tool-progress into Matrix preview edits (default true) |
channels.slack.socketMode.clientPingTimeout | number | Slack pong timeout (default 15s) |
channels.slack.socketMode.serverPingTimeout | number | Server ping timeout |
channels.slack.socketMode.pingPongLoggingEnabled | boolean | Enable ping/pong logging |
channels.whatsapp.accounts.<id>.groups.<id>.systemPrompt | string | Per-WhatsApp-group system prompt |
channels.whatsapp.accounts.<id>.direct.<id>.systemPrompt | string | Per-direct-chat system prompt |
| Symptom | Cause | Fix |
|---|---|---|
| Discord group replies stopped showing automatic finals/blocks/previews | v2026.4.27 default flipped to silent | Set messages.groupChat.visibleReplies: "automatic" to restore auto-posting |
Bare /reset produces empty model reply | Pre-v2026.4.27 fell through to provider call | Upgrade to v2026.4.27+; use /reset <message> to seed next turn |
| WebChat New Session button instantly resets | Pre-v2026.4.27 dispatched immediately | Upgrade — toolbar button now confirms first |