| 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"] |
OpenClaw-Configure Skill
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 guide
IMPORTANT — 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.
Core Principles
Config Files
- Main config:
~/.openclaw/openclaw.json
- Agent models:
~/.openclaw/agents/<agent>/agent/models.json (auto-synced)
- Auth profiles:
~/.openclaw/agents/<agent>/agent/auth-profiles.json
- Workspace:
~/.openclaw/workspace/ (AGENTS.md, SOUL.md, IDENTITY.md, etc.)
The Plugin Gate
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.
Gateway Restart
Config changes require gateway restart:
openclaw gateway stop && sleep 2 && openclaw gateway
Or: openclaw gateway --force (kills existing, starts fresh).
Config Validation
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.
Non-Interactive vs Interactive
- Non-interactive:
channels add, models set, config set, direct JSON edits
- Interactive (needs TTY):
configure, models auth setup-token, models auth paste-token, onboard
- When Claude can't run interactive commands, instruct user to run manually.
Channels
Supported
telegram, whatsapp, discord, irc, googlechat, slack, signal, imessage, feishu, nostr, msteams, mattermost, nextcloud-talk, matrix, bluebubbles, line, zalo, zalouser, tlon, twitch
Add Channel Workflow
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
Channel-Specific Notes
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.
- Stream preview mode (v2026.2.21): Live draft replies with
partial or block options, configurable chunking
- Lifecycle status reactions: Configurable emoji feedback during agent processing (queued/thinking/tool/done/error phases)
- Voice channels: Join/leave/status via
/vc, auto-join for realtime voice conversations
- Ephemeral defaults: Configurable ephemeral responses for slash commands
- Forum tag management:
available_tags editing
- Channel topics: Included in trusted inbound metadata
- Thread-bound subagents: Per-thread sessions with focus/list controls
- Thread lifecycle (v2026.3.1+): Inactivity-based lifecycle (
idleHours default 24h) + optional maxAgeHours hard limit, /session idle + /session max-age commands
Telegram 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.
Per-Channel Model Overrides (v2026.2.21+)
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.
Per-Account defaultTo Routing (v2026.2.21+)
Set outbound routing fallback per account: channels.<ch>.accounts.<id>.defaultTo for openclaw agent --deliver.
Channel Commands
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
Models
Provider Format
provider/model-id: anthropic/claude-opus-4-6, ollama/minimax-m2.5:cloud, openai-codex/gpt-5.3-codex
Provider Config Block (openclaw.json -> models.providers)
"<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
}]
}
API Types
"anthropic-messages" — Anthropic direct + MiniMax Portal"ollama" — Ollama native (baseUrl WITHOUT /v1)"openai-completions" — OpenAI-compatible
Provider Setup Recipes
Ollama (local):
"ollama": {
"baseUrl": "http://127.0.0.1:11434",
"apiKey": "ollama-local",
"api": "ollama",
"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):
- REQUIRES
claude CLI logged in with Pro/Max (/login first!)
- Generate:
claude setup-token -> token starts with sk-ant-oat01-
- Register:
openclaw models auth setup-token --provider anthropic (interactive, user must run)
- Or paste into
auth-profiles.json -> anthropic:manual.token
- GOTCHA: Unauthenticated session -> invalid token -> 401 error
- Same
api: "anthropic-messages" — OpenClaw handles bearer auth internally
OpenAI (GPT Plus via Codex OAuth):
- Install:
npm i -g @openai/codex
- Run:
openclaw configure -> select "OpenAI Codex" (OAuth, NOT API key)
- Browser opens for OAuth
- Models: GPT 5.2, GPT 5.2 Codex, GPT 5.3 Codex
Google Gemini (subscription):
- Install:
npm install -g @google/gemini-cli
- Enable:
openclaw plugins enable google-gemini-cli-auth
- Run:
openclaw configure -> Google -> "Google Gemini CLI Auth"
- Models: Gemini 3 Pro, Gemini 3 Flash (~1M context), Gemini 3.1 Pro Preview (v2026.2.21+)
Volcano Engine / Doubao (v2026.2.21+):
- Run:
openclaw configure -> Volcano Engine -> follow onboarding auth flow
- Models: Doubao series
- api:
"openai-completions" (OpenAI-compatible)
BytePlus (v2026.2.21+):
- Run:
openclaw configure -> BytePlus -> follow onboarding auth flow
- api:
"openai-completions" (OpenAI-compatible)
MiniMax Portal (free OAuth):
- Enable:
openclaw plugins enable minimax-portal-auth
- Run:
openclaw configure or openclaw models auth login --provider minimax-portal
- api:
"anthropic-messages" (Anthropic-compatible)
Kilo Code Gateway (v2026.2.23+):
- Run:
openclaw configure → Kilo Gateway → follow onboarding auth flow
- Default model:
kilocode/anthropic/claude-opus-4.6
- api:
"anthropic-messages" (Anthropic-compatible routing)
Vercel AI Gateway (v2026.2.23+):
- Accepts Claude shorthand refs:
vercel-ai-gateway/claude-* (auto-normalized to canonical Anthropic IDs)
- Configure like any OpenAI-compatible provider
Model Switching — Full Workflow
Switching the default model requires more than models set:
openclaw models set "provider/model-id"
openclaw models fallbacks clear
openclaw models fallbacks add "fallback1/model"
openclaw models fallbacks add "fallback2/model"
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
openclaw gateway stop && sleep 2 && openclaw gateway
openclaw agent --agent main --message "What model are you?" --json --local 2>&1 | grep '"model"'
Purging Models
To remove a model entirely:
- Remove from
openclaw.json -> models.providers.<provider> block
- Remove from
openclaw.json -> agents.defaults.models entries
- Remove from fallbacks:
openclaw models fallbacks remove "provider/model"
- Also clean
~/.openclaw/agents/<agent>/agent/models.json (agent-level copy)
- Restart gateway
Fallback Chain Gotcha — Model Identity Leak
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.
Session Architecture
- Session index:
~/.openclaw/agents/<agent>/sessions/sessions.json — maps session keys to metadata
- Session history:
~/.openclaw/agents/<agent>/sessions/<uuid>.jsonl — JSONL with full conversation
- Session keys:
agent:<agent>:main (DM/CLI), agent:<agent>:discord:channel:<id> (per-channel), etc.
- System prompt: NOT stored in JSONL — dynamically generated from workspace files (IDENTITY.md, SOUL.md, etc.) and injected at runtime
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.
Key Session Fields (sessions.json)
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
JSONL Entry Types
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
Verifying Actual Model vs Reported Model
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.
Model Commands
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
Commands
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
Key Plugin IDs
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
Commands
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
Container Probes (v2026.3.1+)
Built-in HTTP liveness/readiness endpoints for Docker/Kubernetes:
/health, /healthz — liveness/ready, /readyz — readiness
Fallback routing preserves existing handlers on those paths.
Config (openclaw.json -> gateway)
"gateway": {
"port": 18789, "mode": "local", "bind": "loopback",
"auth": {"mode":"token","token":"<token>"},
"tailscale": {"mode":"off"},
"nodes": {"denyCommands":["camera.snap","screen.record",...]}
}
Agents
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
Thinking Defaults (v2026.3.1+)
Claude 4.6 models now default to adaptive thinking level. Other reasoning-capable models default to low unless configured.
Config (openclaw.json -> agents.defaults)
"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}
}
}
Multi-Agent Setup (Multiple Bots, One Instance)
Run N agents from one OpenClaw instance, each with their own Telegram bot, workspace, and identity.
Full Recipe: Add a New Agent
openclaw channels add --channel telegram --account <agent-id> --token "<bot-token>"
openclaw agents add --workspace ~/.openclaw/workspace-<agent-id> --bind telegram:<agent-id> --non-interactive
openclaw agents set-identity
Agent Routing via Bindings (v2026.2.26+)
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
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.
Telegram Multi-Account Config
"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.
Inter-Agent Communication
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.
Agent Workspace Structure
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 |
Agent Self-Awareness (Portraits & Selfies)
For agents to generate selfies from their portrait:
- Place
portrait.png in the agent's workspace
- Copy to
~/.openclaw/media/<name>-portrait.png (for sending)
- In
IDENTITY.md, add a ## My Appearance section with detailed physical description
- In
SOUL.md, add a ## Self-Awareness section explaining how to generate selfies and resumes
- Set
identity.avatar to portrait.png in openclaw.json
Media Path Security
CRITICAL: 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.
Device Scope for sessions_spawn
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.
Clearing Stale Agent Sessions
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.
Running an Agent Turn via CLI
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 specified
Config
config 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
Common Paths
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
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
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
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.
Security Hardening (v2026.2.21+)
Major security overhaul with 40+ fixes:
- Owner-ID obfuscation uses dedicated HMAC secret (decoupled from gateway token)
- SHA-256 replaces SHA-1 for gateway lock and tool-call synthetic IDs
- Heredoc substitution allowlist bypass blocked
- Shell startup-file env injection blocked (
BASH_ENV, ENV, BASH_FUNC_*, LD_*, DYLD_*)
- Browser local file reads via
file:, data:, javascript: protocols blocked
- ACP resource link prompt injection prevention
- TTS model-driven provider switching now opt-in by default
- Sandbox browser containers default to dedicated Docker network
Security Hardening (v2026.3.8+)
system.run approved scripts pinned to on-disk file snapshots — post-approval rewrites denied before execution- Skills download installs pin validated per-skill tools root — path rebinding cannot redirect writes outside tools dir
- MS Teams
groupPolicy: "allowlist" now enforces sender allowlists even when route allowlists are configured
- Browser SSRF: private-network intermediate redirect hops blocked in strict navigation flows
- Cron files enforced to owner-only (
0600), directories to 0700
Heartbeat DM Delivery Control (v2026.2.25+)
Replace the old boolean DM toggle with explicit policy field:
"agents": {
"defaults": {
"heartbeat": {
"directPolicy": "allow"
}
}
}
Also supported per-agent via agents.list[].heartbeat.directPolicy. Default is allow (DMs permitted).
Slack Session Thread Token Limit (v2026.2.25+)
Cap parent-session token inheritance for thread sessions to avoid bricking new threads:
"session": {
"parentForkMaxTokens": 100000
}
Multi-User / Shared Runtime Hardening (v2026.2.24+)
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
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
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).
QMD Improvements (v2026.2.21+)
- Per-agent enable/disable for QMD
- Per-collection search splitting for targeted queries
- Boot retry on transient embedding/provider failures
- BM25-only mode support (no embedding provider needed)
- Global embed serialization (prevents parallel embed races)
- Mixed-source search ranking diversification (session transcripts no longer crowd out memory files)
- Explicit
unavailable warnings from memory_search on embedding/provider failures
Message
message 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 & Devices
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
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 (40+ subcommands)
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)
Nodes
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
Other Domains
Secrets (v2026.2.26+)
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
dns setup --domain <domain> [--apply] CoreDNS for wide-area Bonjour
Approvals
approvals get Fetch exec approvals
approvals set Replace from JSON file
approvals allowlist Edit per-agent allowlist
System
system event Enqueue system event
system heartbeat [enable|disable|last] Heartbeat controls
system presence [--json] Presence entries
Webhooks
webhooks gmail Gmail Pub/Sub hooks (via gogcli)
ACP (Agent Control Protocol) (v2026.2.26+)
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).
Skills (Runtime — 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>
openclaw skills list
openclaw skills check
openclaw gateway stop && openclaw gateway
See the ClawHub section below for the full registry CLI.
Update
update [--channel stable|beta|dev --yes] Update OpenClaw
update status Version + channel status
update wizard Interactive update
Diagnostics
doctor [--fix] [--deep] Health checks + fixes
health [--json] Gateway health
status [--deep] [--usage] Channel health + sessions
logs [--follow] [--limit <n>] Tail gateway logs
Backup (v2026.3.8+)
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).
Web Search Configuration (v2026.3.8)
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:
openclaw config set tools.web.search.provider brave
openclaw config set tools.web.search.brave.mode llm-context
openclaw config set tools.web.search.provider perplexity
openclaw config set tools.web.search.provider grok
openclaw config set tools.web.search.provider kimi
New Config Keys (v2026.3.8+)
| 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.
Other
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
External Secrets Management (v2026.2.26+)
Manage credentials and auth profiles via external secrets providers (HashiCorp Vault, AWS Secrets Manager, etc.)
openclaw secrets audit
openclaw secrets configure
openclaw secrets apply --file <path>
openclaw secrets reload
Key Features:
- Runtime snapshot activation: Secrets applied at runtime without restart
- Strict target-path validation: Prevents accidental overwrites to wrong config paths
- Safer migration scrubbing: Cleaner transitions from inline keys to external refs
- Ref-only auth-profiles: Auth profiles can now reference external secret values via
$secret:provider/path syntax
- Built-in providers: Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault
Example Auth Profile with External Secret:
"auth-profiles.json": {
"anthropic:vault": {
"type": "anthropic-bearer",
"key": "$secret:vault/secret/data/anthropic#api_key"
}
}
ClawHub (Skill Registry CLI)
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"
Global Options
--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
Environment Variables
CLAWHUB_SITE Site base URL
CLAWHUB_REGISTRY Registry API base URL
CLAWHUB_WORKDIR Working directory
(CLAWDHUB_* also supported)
Authentication
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
Discovery & Browsing
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 & Update
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)
Publishing
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)
Social
star <slug> [--yes] Add a skill to your highlights
unstar <slug> [--yes] Remove a skill from your highlights
Moderation (moderator/admin only)
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
Common Workflows
Browse and install a skill:
clawhub explore --sort trending --limit 10
clawhub inspect <slug> --files
clawhub install <slug>
Publish a skill:
clawhub login
clawhub publish ./my-skill --slug my-skill --name "My Skill" --version 1.0.0
Bulk sync local skills:
clawhub sync --dry-run
clawhub sync --all --bump patch
Update all installed skills:
clawhub update --all
Troubleshooting
| 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 |
What's New in v2026.4.29
(npm jumped 4.27 → 4.29; no 4.28 published.)
Breaking / Noteworthy Defaults
- Restrictive profiles no longer auto-widen (v2026.4.29): Configured
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.
- Active-run queue default =
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.
- Doctor migrates legacy TTS toggles (v2026.4.29):
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.
New Features
Providers / Models:
- NVIDIA bundled provider (v2026.4.29):
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).
- DeepSeek V4
xhigh / max thinking (v2026.4.29): Native thinking levels exposed through resolveThinkingProfile. /think xhigh|max now applies intended effort instead of falling back.
- Bedrock Opus 4.7 thinking parity (v2026.4.29): Full
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.
- Vercel AI Gateway xhigh (v2026.4.29): Provider-owned
/think xhigh for trusted OpenAI/Codex upstream refs; Claude adaptive thinking for Anthropic upstream refs.
- Custom OpenAI-compat xhigh (v2026.4.29): Honor
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.- Codex
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 (v2026.4.29): Channel catalog adds
"yuanbao" alias; plugin moved to YuanbaoTeam/yuanbao-openclaw-plugin.
Memory / People Wiki:
- People wiki (v2026.4.29): Agent-facing people metadata, canonical aliases, person cards, relationship graphs, privacy/provenance reports, evidence-kind drilldown, search modes for person lookup, question routing, source evidence, raw claims.
- Active Memory chat-id filters (v2026.4.29): Optional per-conversation
activeMemory.allowedChatIds / deniedChatIds filters so operators enable recall only for selected DMs, groups, or channels.
- Active Memory partial recall on timeout (v2026.4.29): When the hidden memory sub-agent times out, returns bounded partial recall summaries (default temporary-transcript path) so useful recovered context isn't discarded.
- REM dreaming preview RPC (v2026.4.29): Read-only
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:
- Inferred follow-up commitments (v2026.4.29): Opt-in
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:
- Startup diagnostics timeline (v2026.4.29): Opt-in config flag emits gateway lifecycle and plugin-load phase timing so slow-start diagnosis no longer needs bespoke instrumentation.
- Event loop in
/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.- Stuck-session recovery (v2026.4.29): Conservative recovery releases only stale session lanes while active embedded runs, reply ops, and lane tasks remain serialized.
- Bounded restart deferral (v2026.4.29): Default restart-deferral and SIGUSR1 drain bounded to 5 min (explicit
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.).- NVIDIA + Yuanbao docs entries (v2026.4.29): Channel listing and sidebar nav.
OPENCLAW_SKIP_ONBOARDING Docker env (already in 4.27, restated): Automated Docker installs skip interactive onboarding while still applying gateway defaults.
Channels:
- Telegram polling/webhook liveness (v2026.4.29): Channel status and doctor warn when a long-poller has not completed
getUpdates after startup grace, transport activity is stale, or setWebhook has not completed after grace.
- Telegram durable edit streaming (v2026.4.29): Streaming previews use durable message edits instead of native draft state, eliminating draft-to-message flicker that looked like duplicates.
- Telegram quote retry (v2026.4.29): On
QUOTE_TEXT_INVALID, retries native quote replies without reply_parameters.quote so stale/truncated excerpts don't drop the whole reply.
- Telegram exec approvers from owner allowlist (v2026.4.29): Telegram now infers native exec approvers from
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.
- Discord rate-limit cooldown (v2026.4.29): Cloudflare/Error 1015 HTML 429s during startup application lookup and
/gateway/bot metadata fetches now cool down properly. New channels.discord.applicationId for app-id lookup bypass. HTML bodies sanitized before logging.
- Discord text-only intent drop (v2026.4.29): Text-only configs can drop
GuildVoiceStates gateway intent. Bounded /gateway/bot metadata timeout with rate-limited fallback logs.
- Discord CJK chunking (v2026.4.29): Long CJK replies split at punctuation and code-point-safe boundaries.
- WhatsApp keepalive timings (v2026.4.29): Explicit Baileys socket timings on every WhatsApp Web socket. New
web.whatsapp.* keepalive, connect, and query timeout settings.
- WhatsApp recovery on quiet sockets (v2026.4.29): Recovers recently active listeners when post-408 reconnect keeps receiving transport frames but stops delivering app messages. Forces earlier reconnects on silent transport stalls.
- Slack Block Kit limits (v2026.4.29): Auto-truncates buttons/selects/fallback text to Slack's value, count, and message limits across native commands, exec approvals, message sends/edits, command argument menus, and confirmation dialogs.
- Slack
already_reacted idempotent (v2026.4.29): Repeated reaction adds no longer surface as tool failures.
- Mattermost ping/pong keepalive (v2026.4.29): Protocol ping/pong with stale-pong reconnect.
- Matrix verify confirm-sas (v2026.4.29):
openclaw matrix verify confirm-sas now completes the cross-signing handshake.
- WhatsApp pairing tightened (v2026.4.29): Pairing verification replies restricted to real inbound user content; receipts/typing/presence ignored.
Security:
- OpenGrep rulepack (v2026.4.29): Precise OpenGrep rulepack, source-rule compiler, provenance metadata check, and PR/full scan workflows uploading SARIF to GitHub Code Scanning.
- GHSA triage policy (v2026.4.29): Media/base64 decode and format-conversion overhead after configured acceptance limits classified as performance-only unless a report demonstrates a limit bypass, crash, exhaustion, data exposure, or boundary bypass.
<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.- Telegram DM
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.
- All-channels DM open semantics aligned (v2026.4.29): Discord, Slack, Mattermost, Matrix, Feishu, LINE, IRC, Google Chat, Zalo, Zalo User, QQ Bot, Synology Chat —
dmPolicy="open" is public only with effective wildcard; otherwise still respects sender allowlists.
- Group-scoped tool policy auth (v2026.4.29): Validates caller group IDs against session/spawned context before applying group-scoped tool policies. Forged group IDs can't unlock more permissive tools.
- Subagent
/focus boundary (v2026.4.29): Leaf subagents rejected from /focus; fallback target resolution scoped to requesting subagent's children.
- Bootstrap pairing scopes capped (v2026.4.29): Bootstrap handoff token issuance, redemption, and approved pairing baselines bounded to documented per-role scope allowlist. Bootstrap approvals can't persistently grant
operator.admin, operator.pairing, or node.exec.
Key Fixes (highlights)
- Telegram
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.
- Anthropic Meridian content_block_start preservation (v2026.4.29): Text and thinking content seeded on
content_block_start is preserved so [thinking, text] replies don't persist as empty turns.
- Codex Responses input items (v2026.4.29): Sends a non-empty Responses input item when a turn only has systemPrompt-backed instructions (avoids ChatGPT 400 on
input: []).
- OpenAI-compat malformed SSE (v2026.4.29): Malformed event-only or blank-data SSE frames dropped before the OpenAI SDK stream parser sees them. No more
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.- Ollama
: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.
- Ollama provider-prefixed tool calls (v2026.4.29): Normalizes
functions.exec to exec at the native stream boundary.
- Local model context-window guard (v2026.4.29): Derives thresholds from effective model window with 4k/8k safety floors. Small local models no longer rejected by fixed 16k/32k preflight cutoffs.
- Plugin Windows fast path (v2026.4.29): Native
require() for bundled plugin modules on Windows. Startup ~39s → ~2s on typical 6-plugin setups.
- macOS attach-only mode (v2026.4.29):
--attach-only / --no-launchd no longer uninstall the Gateway LaunchAgent or drop active sessions.
- PDF.js standard fonts (v2026.4.29): Resolves from installed package root with filesystem path fallback. Built-in font PDFs render without
file:// lookup failures.
- Cron timeout cleanup (v2026.4.29): Aborts and bounded-cleans timed-out isolated agent turns before recording the timeout. Stale cron sessions can't leave Discord/etc. stuck in
processing.
- Cron heartbeat coordination (v2026.4.29): Defers missed isolated agent-turn catch-up out of the channel startup window.
New Config Keys (v2026.4.29)
| 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) |
New Troubleshooting Entries (v2026.4.29)
| 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 |
What's New in v2026.4.24–4.27
Breaking / Noteworthy Defaults
- Discord group/channel reply visibility default = silent (v2026.4.27): Group/channel replies are private by default unless the agent explicitly uses the message tool. Always-on rooms can lurk without leaking automatic finals, blocks, previews, or status reactions. Restore legacy auto-posting with
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.- WebChat New Session button now confirms (v2026.4.27): Toolbar New Session button asks for confirmation before dispatching
/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.- Discord interaction listener owned by OpenClaw (v2026.4.27): Carbon interaction listener handed off async. Compaction or long session locks no longer trip listener timeouts.
- CLI parent commands return exit 0 (v2026.4.27):
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.
New Features
Providers / Models:
- DeepInfra bundled provider (v2026.4.27):
DEEPINFRA_API_KEY onboarding, dynamic OpenAI-compatible model discovery, image generation/editing, image/audio media understanding, TTS, text-to-video, memory embeddings.
- Cerebras bundled plugin (v2026.4.26): Onboarding, static model catalog, manifest-owned endpoint metadata.
- Tencent Yuanbao channel (v2026.4.27): External plugin (
openclaw-plugin-yuanbao) registered in official channel catalog. WebSocket bot DMs and group chats.
- QQBot full group chat (v2026.4.27): History tracking, @-mention gating, activation modes, per-group config, FIFO message queue, C2C
stream_messages streaming, unified sendMedia with chunked upload.
- Codex Computer Use (v2026.4.27):
/codex computer-use status/install, marketplace discovery, optional auto-install, fail-closed MCP server checks before Codex-mode turns.
- Matrix encryption setup (v2026.4.26):
openclaw matrix encryption setup enables E2EE, bootstraps recovery, prints verification status from one flow.
- Claude Code migration importer (v2026.4.26):
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:
- Operator-managed outbound proxy (v2026.4.27):
proxy.enabled + proxy.proxyUrl / OPENCLAW_PROXY_URL with strict http:// forward-proxy validation, loopback-only Gateway bypass, cleanup on exit.
- Sandbox GPU passthrough (v2026.4.27): Opt-in
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.- Ollama retrieval query prefixes (v2026.4.26): Model-specific prefixes for
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.- Native typing cue on inbound (v2026.4.27): Best-effort typing cue immediately after inbound accept, before queueing/compaction/model/tool work starts. Shows liveness on slow pre-dispatch turns.
- TTS → BlueBubbles voice memo (v2026.4.27): Pre-transcoded MP3 → opus-in-CAF (mono, 24 kHz) on macOS so iMessage renders TTS as native voice-memo bubble (proper duration + waveform UI). Opt-in via
tts.voice.preferAudioFileFormat.
- Per-WhatsApp-group system prompts (v2026.4.27):
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.
Key Fixes (highlights)
- DeepSeek V4 reasoning replay (v2026.4.27):
reasoning_content backfilled on plain assistant replay messages, not just tool-call turns. Fixes thinking sessions with prior tool use failing follow-up requests.
- Slack auto-reply leak (v2026.4.27): Fully consumed text reset triggers like
new session no longer leak into the fresh model turn.
- Slack Socket Mode timeouts (v2026.4.27): 15s pong timeout default + new
clientPingTimeout / serverPingTimeout / pingPongLoggingEnabled overrides. Stale-websocket handling decoupled from app-event health heuristics.
- WebChat New Session race (v2026.4.27): Pending run + typing state attached to the active client run. Unowned final/inject/announce events no longer unlock unrelated active runs.
- WebChat large attachment crash (v2026.4.27): Lit state no longer holds large attachment payloads. Object URL previews + send-time payload serialization. Fixes
RangeError: Maximum call stack size exceeded on PDF/image uploads.
- Telegram polling watchdog token failures (v2026.4.27): Fail fast when Telegram rejects startup
getMe with 401. Surface as token auth failure instead of misleading deleteWebhook cleanup error.
- Telegram
/bot<TOKEN> apiRoot fix (v2026.4.27): Normalize accidental full-token apiRoot values at runtime. openclaw doctor --fix strips the suffix.
- Cron Telegram thread routing (v2026.4.27): Session-derived Telegram topic thread IDs preserved when isolated cron explicitly targets parent chat. Bare chat targets stay in active forum topic.
- Cron agentId inference (v2026.4.27):
cron.add infers creating session's agentId when omitted. Scheduled agentTurn jobs route to session agent.
- Cron local provider preflight (v2026.4.27): Probe local Ollama / OpenAI-compatible endpoints before isolated cron turns. Records unreachable as skipped, caches dead-endpoint probes.
- CLI parent commands exit 0 (v2026.4.27):
openclaw memory / channels / plugins / etc. without subcommand prints help and exits 0.
- Memory pre-compaction flush prompts (v2026.4.27): Kept runtime-only. Session transcripts and
chat.history no longer expose them as normal user turns.
- Plugin runtime mirror (v2026.4.27): Reuse unchanged bundled plugin runtime mirrors instead of rebuilding on every load. Cuts I/O on slow storage. Restart no longer reinstalls full retained dependency set when one is absent.
- Auto-reply pending tool-result drain (v2026.4.27): Bounded with progress-aware idle timeout. Never-settling tool tasks no longer leave session active forever. Slow healthy deliveries can still drain.
- Backup excludes plugin
node_modules (v2026.4.27): Skips installed plugin dependency trees but keeps manifests + source files. Avoids rebuildable npm payload bloat.
- OTEL diagnostic events (v2026.4.27): Privacy-safe model-call request payload bytes, streamed response bytes, first-response latency, total duration captured in events, plugin hooks, stability snapshots, OTEL spans/metrics. Raw model content not logged.
New Config Keys (v2026.4.24–4.27)
| 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 |
New Troubleshooting Entries (v2026.4.24–4.27)
| 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 |
