Openclaw

OpenClaw (Operator Playbook)

This skill is self-contained and includes operational documentation directly in this file.

Links

• Documentation
• Releases
• GitHub

Quick Navigation

• Installation / migration: references/installation.md
• Configuration model & workspace bootstrap: references/configuration.md
• Architecture & multi-agent routing: references/architecture.md
• Extended concepts: references/concepts.md
• Tool governance & safety: references/tools.md
• Gateway runbook & security: references/gateway.md
• Onboarding & first-run: references/getting-started.md
• Channels & providers: references/channels-and-providers.md
• Nodes & remote execution: references/nodes.md
• CLI operations & troubleshooting: references/operations.md

Core Model

• OpenClaw is gateway-centric: one long-lived Gateway per host is the control plane.
• Clients and nodes connect via typed WebSocket API; channels/providers are orchestrated by gateway.
• Session safety depends on deterministic routing + queueing + explicit policy controls.

Day-1 Setup

1. Run onboarding with daemon install. 2. Confirm the active config path and validate config before first edits. 3. Verify gateway health/status. 4. Open Control UI/dashboard for first chat. 5. Add channels/providers only after baseline health is stable.

If OpenClaw is not installed, use references/installation.md.

Gateway Operations

• Keep default posture loopback + auth enabled.
• For remote access, prefer Tailscale Serve or SSH tunnel over public bind.
• Non-loopback binds require strict token/password controls.
• Use supervised process mode (launchd/systemd) for reliability.
• For config changes, treat config.apply as controlled rollout and config.patch as targeted merge.
• Remember patch semantics: objects merge, arrays replace, null deletes.
• Treat restart boundaries explicitly: channels/agents/messages/tools often hot-apply, while bind/port and other gateway infra settings commonly require openclaw gateway restart.

Release Updates (v2026.3.11-v2026.3.13)

• Security: browser-originated WebSocket connections now enforce origin validation even in trusted-proxy mode; keep browser clients on approved origins only and do not treat proxy headers as a bypass.
• BREAKING: isolated cron delivery is stricter; legacy cron storage and legacy notify/webhook metadata should be migrated with openclaw doctor --fix after upgrade.
• Gateway/onboarding: remote macOS onboarding now detects when a shared gateway auth token is required and explains where to retrieve it on the gateway host.
• Gateway/control UI: token-auth dashboard sessions now keep auth in session-scoped browser storage instead of long-lived local storage; same-tab refresh should survive, but browser restarts should not be treated as persistent auth.
• Gateway reachability: scope-limited probe RPC now reports degraded reachability instead of looking fully healthy; use that signal during incident triage.
• Channels: Slack adds opt-in interactive reply directives; Telegram inbound media fetching now has IPv4 retry fallback.
• Plugins/tooling: plugin channel/binding collisions now fail fast instead of producing ambiguous runtime behavior.
• Nodes: gateway exposes node.pending.enqueue / node.pending.drain primitives as the foundation for dormant-node pending work delivery.

Release Updates (v2026.3.14–v2026.3.28)

• MCP remote servers: mcp.servers now supports remote HTTP/SSE URLs with auth headers and safer credential redaction. Bundled MCP tools use provider-safe names (serverName__toolName), support streamable-http transport, per-server connection timeouts, and preserve tool results from aborted turns.
• Plugin `before_install` hook: structured request with provenance, built-in scan status, and install-target metadata for external security scanners. --dangerously-force-unsafe-install as break-glass override. Gateway-backed skill dependency installs blocked on dangerous-code critical findings unless override is set.
• Background tasks → unified control plane: ACP, subagent, cron, and background CLI unified under one SQLite-backed ledger with audit/maintenance/status visibility, auto-cleanup, and lost-run recovery.
• ClawFlow: first linear flow control surface (openclaw flows list|show|cancel). Multi-task flows separate from one-task auto-sync flows. Doctor recovery hints for orphaned flow/task linkage.
• Memory/QMD: per-agent memorySearch.qmd.extraCollections for cross-agent search; CJK-aware chunk sizing; session indexer includes reset/deleted transcripts; memory.qmd.searchTool as mcporter tool override.
• WhatsApp reactions: agents can react with emoji on incoming WhatsApp messages.
• Matrix: channels.matrix.historyLimit for room history context in group triggers; per-DM threadReplies overrides; proxy config via channels.matrix.proxy.
• Slack: native Slack exec approval routing with approver authorization.
• LINE: image/video/audio outbound sends on LINE-specific delivery path.
• Android: notification-forwarding controls with package filtering, quiet hours, rate limiting.
• Agents/LLM: configurable idle-stream timeout for embedded runner; text.verbosity forwarded across Responses HTTP/WebSocket transports.
• Security: Nostr inbound DM signature verification; LINE webhook timing-safe HMAC compare; sandbox browser CJK fonts; gateway auth hardening (origin validation, local-direct token enforcement).

Release Updates (v2026.5.12)

• Leaner installs: Slack, WhatsApp, Amazon Bedrock, Anthropic Vertex, and related provider/plugin dependency cones moved out of the core runtime, so installs only pull what you actually use.
• Telegram resilience: isolated polling, durable local spooling, safer group-media handling, and preserved HTML/Markdown formatting improve operator confidence on the default channel path.
• Codex/OpenAI/media: auth-profile-backed media tools, MCP server projection, context-engine thread rotation, and runtime fallback behavior were tightened.
• Ops/security/UI: plugin install/update flows, pnpm 11 handling, gateway/browser/sandbox/node-pairing hardening, and Control UI/WebChat reply delivery all received a significant polish pass.
• ACP fallbacks: ACP turns can try configured backup runtime backends before emitting output, which matters for graceful degraded operation.

Release Updates (v2026.5.22)

• Meeting notes plugin: a source-only external meeting-notes path lands with auto-start capture config, manual transcript import, read-only openclaw meeting-notes CLI access, and Discord voice as the first live source.
• Gateway readiness: startup now lazy-loads idle plugin work, core handler trees, and the embedded ACPX runtime, so health/ready checks no longer wait on unused subsystems.
• Plugin metadata caching: immutable plugin metadata snapshots are reused across startup/config/secret readers, which reduces repeated manifest and file-stat churn during operations.
• Channel/runtime tuning: channel catalog reads are reused, Signal gets configPath, Telegram gains wildcard topic defaults, and backup archives use local-time names.
• Media quality control: model-aware image compression now follows agents.defaults.imageQuality, so operators can choose token-efficient, balanced, or high-detail handling explicitly.
• Plugin SDK migration: row-level session workflow helpers are added and loadSessionStore is deprecated; plugin maintenance should move away from whole-store session access.
• Provider auth reuse: xAI OAuth auth profiles can now back Grok web_search, and provider-side media operations have clearer default timeout behavior.

Release Updates (v2026.5.29-v2026.6.6)

• Security: boundaries tightened across transcripts, sandbox binds, host env inheritance, MCP stdio, and Codex HTTP access; exec-approval timeouts now fail closed; Feishu no longer leaks prompt-preface runtime context into replies; WebSocket payload handling hardened; Skill Workshop symlink writes validated before metadata commits.
• Channels: Telegram routes account-scoped topics correctly, streams text across tool calls, extends /compact to generic ingress, and excludes unauthorized DM text from cache/prompt; iMessage gains always-on inbound restart, durable echo markers, block streaming, idle approval discovery, and startup diagnostics.
• Providers/models: Kimi K2.7 Code with tool-call ID repair and reasoning replay fixes, Claude Fable 5 adaptive thinking, more robust Mistral schema handling, Fireworks manifest-sourced catalog params, repaired Anthropic thinking replay, and Vertex/ADC catalog recovery.
• MCP/browser: existing-session Chrome DevTools Protocol support, WebSocket discovery validation, streamable HTTP loopback transport, safer browser-output boundaries, and MCP tool-result coercion of resource_link/resource/audio/malformed images at the materialize boundary.
• Plugins: npm publishing moved to trusted paths with ClawHub publishing split, plugin version drift reported to operators, managed installs keep trusted integrity pins, and prerelease fallback integrity checks avoid stale carryforward.
• UI/performance: cached model metadata and removed startup catalog wait cut Control UI latency, lazy slash-command loading, first-event tracing with slow-reply diagnostics, accessibility fixes, and explicit user intent required before opening chat sessions.

Release Updates (v2026.5.27-v2026.5.28)

• Runtime recovery: Codex/app-server and subagent paths preserve workspace/cwd separation, route workspace memory through tools, keep native hook relay generations alive across restarts, release session locks on timeout abort, and avoid stale restart continuations.
• Security and input boundaries: group prompt metadata stays out of system prompts, repeated-dot hostnames normalize, unsafe command wrappers and Node env overrides are rejected, no-auth Tailscale exposure is blocked, Teams service URLs are trusted explicitly, and malformed numeric, browser, cron, media, schema, and Telegram callback inputs fail earlier.
• Channels and mobile surfaces: Telegram delivery is more durable, Slack final replies survive late cleanup, Matrix/iMessage/Discord/WhatsApp/Teams paths preserve identity and approval context more carefully, and iOS/WebChat/Talk surfaces keep more state across reconnects.
• Provider/media coverage: OpenAI-compatible embeddings are core, Pixverse video, DeepInfra catalog loading, Claude Opus 4.8, Fal Krea schemas, NVIDIA catalogs, MiniMax streaming music, provider voice catalogs, encrypted PDF extraction, GitHub Copilot runtime, and Codex Supervisor plugin coverage landed.
• Plugin and work coordination: ClawHub display/trust surfaces, reply payload sending hooks, install-on-demand GitHub Copilot/Tokenjuice plugins, and Workboard coordination tools expand plugin/operator workflows while preserving stricter catalog and cache behavior.

Release Updates (v2026.4.15)

• Anthropic/model defaults: bundled Anthropic defaults and opus aliases now target Claude Opus 4.7, including bundled image understanding.
• Google TTS: bundled google plugin now exposes text-to-speech with voice selection, WAV replies, and PCM telephony output.
• Control UI / gateway: model auth status card backed by models.authStatus shows OAuth token health and provider rate-limit pressure.
• Memory: LanceDB can use cloud object storage, GitHub Copilot is available as a memory-search embedding provider, and Dreaming defaults to separate storage instead of inline daily memory blocks.
• Agents/tools: agents.defaults.experimental.localModelLean: true trims heavyweight default tools for weaker local models; unknown-tool loop guard is now enabled by default; skills-snapshot invalidation is stricter on skills.* config writes.
• Security hardening: built-in tool-name collisions are rejected, /mcp auth uses constant-time comparison with browser-origin checks, HTTP bearer rotation applies immediately after secret reload, and webchat/media paths enforce stronger local-root/file restrictions.

Release Updates (v2026.3.13-1)

• This is a recovery Git tag for the broken v2026.3.13 release path; the npm/runtime version remains 2026.3.13.
• Gateway/UI: control-ui connect failures are classified more clearly, and insecure-control-ui shared-auth behavior is restored for the intended compatibility path.
• Operations: post-compaction sanity now checks full-session token counts, which makes compaction regressions easier to detect during incident triage.
• Sessions/channels: session reset preserves lastAccountId and lastThreadId; Telegram inbound media retries keep IPv4 fallback behavior.
• Runtime/platforms: Docker adds OPENCLAW_TZ; gateway probe handling and unanswered client-request bounding are more operator-visible when reachability degrades.

Release Updates (v2026.3.7)

• BREAKING: Gateway auth now requires explicit gateway.auth.mode (token or password) when both gateway.auth.token and gateway.auth.password are configured (including SecretRefs). Set before upgrade to avoid startup/pairing failures.
• Agents: ContextEngine plugin interface with full lifecycle hooks (bootstrap, ingest, assemble, compact, afterTurn, prepareSubagentSpawn, onSubagentEnded). Enables alternative context management strategies (e.g. lossless-claw) without modifying core compaction.
• Agents: configurable postCompactionSections to choose which AGENTS.md sections re-inject after compaction.
• Agents: head+tail truncation for oversized tool results (preserves tail diagnostics).
• Telegram: per-topic agentId overrides in forum groups and DM topics for dedicated agent routing with isolated sessions.
• Telegram/ACP: durable topic binding (--thread here|auto), approval buttons with prefixed-id resolution, bind pin confirmations.
• ACP: persistent Discord channel and Telegram topic binding storage surviving restarts.
• Plugins: prependSystemContext/appendSystemContext for static guidance in system prompt space (provider caching, lower repeated cost).
• Plugins: hooks.allowPromptInjection policy and runtime validation of unknown hook names.
• Hooks: session:compact:before/session:compact:after events with session/count metadata.
• Config: recentTurnsPreserve and quality-guard retry knobs exposed through validated config.
• Tools/Web search: Perplexity provider switched to Search API with structured results + language/region/time filters.
• Tools/Diffs: guidance moved from prompt-hook injection to companion skill path (reduces unrelated-turn noise).
• Gateway: SecretRef support for gateway.auth.token with auth-mode guardrails.
• Docker: multi-stage build producing minimal runtime image; OPENCLAW_VARIANT=slim build arg; OPENCLAW_EXTENSIONS for pre-baking extension dependencies.
• TTS: messages.tts.openai.baseUrl config support for OpenAI-compatible endpoints.
• Google: first-class gemini-3.1-flash-lite-preview support.
• Slack: typingReaction for DM processing status when assistant typing unavailable.
• Discord: allowBots: "mentions" to gate bot messages by mention.
• Mattermost: interactive /oc_model provider/model browsing.
• Cron: jobs.json.bak preserved as pre-edit snapshot for recovery.

Release Updates (v2026.3.2)

• BREAKING: New installs default tools.profile to messaging (not broad coding/system). If you expect coding tools on day-1, set tools.profile explicitly.
• BREAKING: ACP dispatch defaults to enabled unless explicitly disabled (acp.dispatch.enabled=false).
• BREAKING: Plugin SDK removed api.registerHttpHandler(...); use api.registerHttpRoute(...).
• BREAKING: Zalo personal plugin (@openclaw/zalouser) no longer uses external CLI transports; after upgrade re-login with openclaw channels login --channel zalouser.
• Secrets/SecretRef coverage expanded across user-supplied credential surfaces; unresolved refs fail fast on active surfaces.
• Tools: first-class pdf tool (native Anthropic/Google support + fallback extraction, with configurable limits).
• CLI: openclaw config validate (and --json) to validate config before gateway startup.
• Telegram: streaming defaults to partial for new setups; DM preview streaming behavior updated.
• Memory: embeddings via Ollama supported for memory search (memorySearch.provider/fallback = "ollama").
• Tools/diffs plugin: PDF output support and rendering quality controls for diff artifacts.

Release Updates (v2026.3.1)

• Gateway: built-in container probe endpoints (/healthz, /readyz, plus aliases /health, /ready) for Docker/Kubernetes.
• CLI: openclaw config file prints the active config path (resolves OPENCLAW_CONFIG_PATH or default).
• Discord: thread-bound session lifecycle now supports inactivity (idleHours) and hard max age (maxAgeHours), plus /session idle and /session max-age.
• Telegram: per-DM direct + DM topics config surface (topic-aware policy, skills, system prompt, allowlists).
• Nodes (Android): expanded node tool surface (camera/device/notifications/photos/contacts/calendar/motion).
• Tools: optional diffs plugin tool for read-only diff views and PNG rendering.

Release Updates (v2026.2.23)

• Providers: first-class kilocode provider support (auth, onboarding, implicit provider detection, and model defaults).
• Tools/web_search: add provider "kimi" (Moonshot) and correct the two-step $web_search tool flow (echo tool results before synthesis).
• Gateway: optional HSTS via gateway.http.securityHeaders.strictTransportSecurity for direct HTTPS deployments.
• Sessions: hardened maintenance via openclaw sessions cleanup with disk-budget controls and safer transcript/archive cleanup.
• Breaking: browser SSRF policy defaults changed and config key renamed (browser.ssrfPolicy.allowPrivateNetwork -> browser.ssrfPolicy.dangerouslyAllowPrivateNetwork); use openclaw doctor --fix to migrate.

Architecture and Runtime Concepts

Agent Loop

• Agent loop is serialized per session (and optionally globally) to avoid tool/history races.
• Run lifecycle emits assistant/tool/lifecycle streams for observability.
• Wait timeout and runtime timeout are different controls.

System Prompt and Context

• System prompt is OpenClaw-composed per run (not provider default prompt).
• Prompt mode can be full, minimal, or none depending on run context.
• Context includes system prompt, transcript, tools/results, attachments, schemas.
• Bootstrap files are injected into context window and consume budget.

Workspace and Memory

• Workspace is default execution directory and memory surface, not a hard sandbox.
• Use sandbox settings when strict filesystem isolation is required.
• Memory is markdown-first: daily notes + curated durable memory.
• Compaction persists summary to transcript; pruning trims old tool results in-memory.
• Bootstrap files such as AGENTS.md, SOUL.md, USER.md, TOOLS.md, HEARTBEAT.md, IDENTITY.md, and MEMORY.md all consume context budget; keep them deliberate and compact.

Messaging, Queueing, Presence

• Message processing uses dedupe, optional inbound debounce, queue modes, and channel-aware delivery.
• Queue/streaming/chunking behavior is policy-driven and tunable per channel.
• Presence is best-effort observability; stable instanceId is required to avoid duplicate entries.

Tools Governance

• Start with least-privilege profile, then explicitly allow required tools.
• Deny list overrides allow list.
• Treat exec, sessions_*, gateway, nodes as high-impact surfaces.
• Require explicit user consent for media-capture operations.
• Enable loop-detection when tools may form no-progress cycles.

Channels and Provider Strategy

• Start with fastest stable channel path (commonly Telegram) for baseline verification.
• Add WhatsApp and advanced channels only after pairing/allowlists are proven.
• Keep provider selection explicit via provider/model and avoid implicit model drift.
• Isolate auth profiles per agent when separating work/personal contexts.

Nodes and Remote Execution

• Nodes are capability executors, not gateway replacements.
• Pair nodes explicitly and verify capabilities before invoking actions.
• Keep node exec approvals local to node host and audited.
• Use explicit node binding for deterministic remote execution targeting.

Security Baseline

• Assume prompt injection is always possible.
• Apply controls in this order: identity (pairing/allowlist) -> scope (tools/sandbox/mentions) -> model policy.
• Keep control UI in secure context (loopback/HTTPS); avoid insecure auth downgrades.
• Use strict filesystem permissions for config/state and redact sensitive logs.

Troubleshooting Ladder

1. openclaw status 2. openclaw gateway status 3. openclaw logs --follow 4. openclaw doctor 5. openclaw channels status --probe

Common triage map:

• No replies -> pairing/allowlist/mention policy.
• Connect loop -> auth mode + endpoint + secure context.
• Startup fail -> mode/bind/auth/port conflict.
• Tool failure -> permissions/approvals/foreground constraints.

Concepts URLs Status (from left navigation)

• Extracted concepts are integrated directly into this skill.
• Some source URLs in docs navigation currently return 404 or empty content.
• Coverage for those pages is consolidated in references/concepts.md with fallback guidance.

When to Use

• You need to design or operate an OpenClaw deployment.
• You need to connect channels, providers, and tools safely.
• You need a practical checklist for onboarding and gateway setup.

Core Operating Workflow

1. Confirm topology and responsibilities from architecture notes. 2. Shape openclaw.json around the six operator blocks: gateway, agents, channels, bindings, session/messages, heartbeat/tools/cron/hooks. 3. Choose channels/providers and required tools. 4. Configure gateway access, secrets, and remote connectivity. 5. Validate onboarding flow, config health, and control UI accessibility. 6. Run troubleshooting and hardening checklist.

Critical Prohibitions

• Do not copy large verbatim chunks from vendor docs into this skill.
• Do not invent defaults or hidden behavior without doc evidence.
• Do not weaken safety controls (pairing, allowlists, auth, sandbox) for convenience in production.

Links

• Documentation
• Releases

Key docs pages: Architecture, Tools, Gateway

OpenClaw Architecture

Operator summary

• OpenClaw centers around one long-lived Gateway process per host.
• The Gateway owns external messaging surfaces and provider connections.
• Clients and nodes connect to the Gateway via typed WebSocket protocol.
• The Gateway also serves HTTP endpoints for canvas/A2UI web surfaces.

Core components

• Gateway: control plane, channel ownership, provider multiplexing, event source.
• Clients: macOS app, CLI, web/admin automations using request/response/event WS API.
• Nodes: role-specific workers advertising explicit capabilities and commands.
• Web surfaces: canvas and A2UI hosted under Gateway HTTP routes.

Connection and protocol model

• Transport uses JSON text WebSocket frames.
• First frame must be connect; invalid first frame causes hard close.
• Requests use req/res correlation IDs and typed methods.
• Server pushes typed events (agent, presence, health, etc.).
• Side-effecting methods require idempotency keys for safe retries.

Routing and execution model

• Messaging ingress is centralized in Gateway (single host authority).
• Agent and send operations are request-driven; updates stream by events.
• Nodes expose executable command namespaces (for example, canvas/media/device actions).
• Clients must handle non-replayed event streams and refresh state on sequence gaps.

Security and trust constraints

• Optional gateway token auth applies to every connection.
• Device identity + pairing trust is required for new device IDs.
• Local endpoints may be auto-approved, remote endpoints require explicit trust flow.
• Remote setups should use VPN/Tailscale or SSH tunnel; enable TLS when exposed.

Deployment notes

• Run exactly one Gateway per host to avoid channel/session conflicts.
• Keep Gateway supervised (launchd/systemd) and logs observable from stdout.
• Separate concerns: Gateway as orchestrator, nodes as capability executors.

Do / Don’t

• Do treat Gateway as single source of truth for channel sessions.
• Do implement reconnect and dedupe behavior in client integrations.
• Don’t assume event replay exists.
• Don’t run multiple gateways for the same host-bound messaging sessions.

Capability map (feature-level)

• Channel layer supports major messaging platforms through one gateway abstraction.
• Routing layer supports isolated multi-agent session handling.
• Interaction layer supports media I/O and long-response streaming.
• Surface layer includes Web Control UI, desktop companion, and mobile nodes with canvas workflows.
• Extension model allows additional channel/plugins beyond built-ins.

Multi-agent routing rules

• Agents are isolated by workspace, state directory, credentials, and session store.
• Binding resolution is deterministic and prioritizes most-specific peer matches before broader channel/account rules.
• Peer-targeted rules override channel-wide defaults.
• Avoid shared agent directories across agents to prevent session/auth collisions.

Multi-agent operator patterns

• Use separate workspace and agentDir paths per agent; sharing them across agents usually causes memory, auth, and routing bleed.
• Prefer account- or peer-specific bindings over broad channel defaults when different agents serve different roles.
• Topic- or chat-level routing works best when the corresponding session scope and mention policy are kept equally explicit.
• Give each agent its own heartbeat policy; keep heartbeat off globally until each agent has a clear HEARTBEAT.md contract.

OpenClaw Channels and Providers

Channels overview

• OpenClaw supports many chat surfaces in parallel and routes by chat/channel context.
• Core channels include WhatsApp, Telegram, Slack, Discord, Signal, IRC, and WebChat.
• Several integrations are plugin-delivered (for example Teams, Matrix, LINE, Mattermost).
• iMessage legacy path is deprecated; BlueBubbles is the preferred approach.

Pairing and trust model

• Some channels require explicit pairing flows (for example QR/token onboarding).
• DM pairing and allowlist controls are key safety boundaries.
• Group behavior differs by platform and must be validated per channel.

Operations notes

• Text support is broad; media/reactions capabilities vary by connector.
• Multi-channel operation is expected; keep channel-specific routing explicit.
• Maintain channel troubleshooting playbooks per connector family.
• In the v2026.5.12 line, some provider/channel dependency cones moved out of the core runtime. If Slack, WhatsApp, Bedrock, or Anthropic Vertex stops appearing after upgrade, validate optional package/plugin presence before debugging config.

Discord thread-bound sessions (v2026.3.1)

Discord can bind a thread to a session/subagent target so follow-up messages keep routing consistently.

Commands:

• /focus <target>
• /unfocus
• /session idle <duration|off>
• /session max-age <duration|off>

Config shape (from Discord channel docs):

{
  session: {
    threadBindings: { enabled: true, idleHours: 24, maxAgeHours: 0 },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false,
      },
    },
  },
}

Practical channel strategy

• Start with Telegram for fastest bootstrap and operator validation.
• Add WhatsApp only after pairing and persistence paths are verified.
• For iMessage workflows, standardize on BlueBubbles and document known feature gaps.

Provider options and model naming

• Providers span hosted APIs and local runtimes (for example OpenAI/Anthropic plus Ollama/vLLM).
• The effective model selector uses provider/model naming.
• OpenClaw supports both direct providers and gateway-style aggregation providers.

Configuration baseline

• Authenticate provider credentials during onboarding flow.
• Set default model via agents.defaults.model.primary.
• Keep environment-specific provider choices explicit to avoid accidental model drift.

Provider operations guidance

• Begin with one stable primary provider before introducing alternates.
• Add local providers only after resource and latency constraints are validated.
• Treat provider credentials as secrets and rotate through your secret-management process.
• Codex/OpenAI paths were tightened in the May 2026 line: media-tool auth profiles, MCP server projection, and runtime fallback behavior are more explicit, so keep those integrations fully configured instead of relying on accidental fallback.

Provider/runtime updates (v2026.5.27-v2026.5.28)

• OpenAI-compatible embedding providers are now core, including local and hosted OpenAI-style endpoints. Prefer the core path over memory-plugin-specific embedding registration, which is kept as deprecated compatibility.
• DeepInfra model browsing now loads the full credential-aware catalog and preserves configured API-key catalogs; re-test onboarding model pickers before maintaining local catalog patches.
• New or refreshed provider/media surfaces include Pixverse video generation with API region selection, Claude Opus 4.8, Fal Krea image schemas, NVIDIA featured model catalogs, MiniMax streaming music responses, provider-backed voice model catalogs, encrypted PDF extraction, and GitHub Copilot agent runtime support.
• VLLM thinking params, bare direct Anthropic model ids, OpenAI-compatible cache retention, OpenAI Responses replay tool ids, and provider retry-after fallback handling were tightened. Keep explicit provider/model pins in config when avoiding automatic catalog drift.

Provider/runtime updates (v2026.4.15)

• Anthropic defaults and opus aliases now point bundled image-understanding flows at Claude Opus 4.7.
• The bundled google plugin now supports TTS with voice selection plus WAV/PCM output paths.
• GitHub Copilot is available as a memory-search embedding provider, which is useful when memory search should align with Copilot-authenticated environments.
• Bundled Microsoft and ElevenLabs speech providers now auto-enable for TTS-oriented setups.

Telegram channel playbook

• Configure bot token, DM policy, and group mention policy before production use.
• Keep numeric user IDs in allowlists; avoid username-only ACLs.
• Treat DM policy and group policy as independent controls and test both paths.
• If non-mention group behavior is required, align Telegram privacy mode/admin state accordingly.
• Use pairing approvals and channel status probes during onboarding validation.

May 2026 operational update:

• Telegram polling/reply delivery is more resilient via isolated polling, durable local spooling, safer group-media handling, and better HTML/Markdown preservation.
• If you previously added local retry/formatting workarounds, re-test after upgrade before keeping them.

Late May 2026 delivery update:

• Telegram sendMessage actions use durable outbound delivery and preserve SecretRef prompt config. Validate long-running Telegram workflows before keeping custom resend queues.
• Slack delivered final replies survive late cleanup, iMessage approval polling continues after denied reactions, Matrix mention previews/finals remain mention-inert, and Discord recovered tool warnings stay out of successful replies.
• WhatsApp resolves auth roots from the active profile, while Teams service URLs are trust-checked. Re-test multi-profile channel installs after rotating profiles or channel secrets.

Telegram DM topics (v2026.3.1)

In addition to group forum topics, Telegram supports per-DM "direct" configuration with optional topics.

Config surface (from config schema/types):

• channels.telegram.direct.<chatId>.topics.<threadId>.*
• channels.telegram.direct.<chatId>.requireTopic (require a topic when topics are enabled)

Minimal example:

{
  channels: {
    telegram: {
      direct: {
        "123456789": {
          requireTopic: true,
          topics: {
            "1": { enabled: true, skills: ["calendar"], systemPrompt: "Personal admin" },
          },
        },
      },
    },
  },
}

Telegram per-topic agent routing (v2026.3.7)

Forum group topics and DM topics support per-topic agentId overrides so each topic routes to a dedicated agent with an isolated session.

ACP persistent channel bindings (v2026.3.7)

• Durable Discord channel and Telegram topic binding storage that survives restarts.
• ACP spawn --thread here|auto for Telegram topic binding.
• Actionable Telegram approval buttons with prefixed approval-id resolution.
• Successful bind confirmations are pinned in-topic.

Slack DM typing feedback (v2026.3.7)

channels.slack.typingReaction enables reaction-based processing status in Socket Mode DMs when native assistant typing is unavailable.

Slack interactive replies (v2026.3.13)

• Slack now supports opt-in interactive reply directives for richer response handling in supported flows.
• Treat this as a channel-specific behavior toggle to validate in staging before broad rollout, especially if you already depend on custom Slack reply formatting.

Slack exec approvals (v2026.3.28)

• Native Slack approval routing with approver authorization so exec approval prompts stay in Slack instead of falling back to Web UI or terminal.

WhatsApp reactions (v2026.3.28)

• Agents can react with emoji on incoming WhatsApp messages for more natural conversational interactions.

LINE outbound media (v2026.3.28)

• LINE image, video, and audio outbound sends on the LINE-specific delivery path with explicit preview/tracking handling for videos.

Matrix improvements (v2026.3.28)

• channels.matrix.historyLimit for optional room history context in group triggers, with per-agent watermarks and retry-safe snapshots.
• Per-DM threadReplies overrides with thread session isolation.
• channels.matrix.proxy for routing Matrix traffic through HTTP(S) proxy.

Discord allowBots mention gating (v2026.3.7)

allowBots: "mentions" accepts bot-authored messages only when they mention the bot.

Mattermost model picker (v2026.3.7)

Interactive /oc_model and /oc_models commands for Telegram-style provider/model browsing with callback-based selection.

Apple Watch and APNs delivery notes (v2026.2.19)

• Apple Watch companion flows depend on reliable gateway-to-iOS notification relay.
• APNs registration/signing configuration is now an explicit operational dependency for iOS/watch delivery reliability.
• If watch/iOS commands appear delayed or missing, validate APNs push path before changing model/tool policy.

Telegram media reliability (v2026.3.13)

• Telegram inbound media downloads retry with an IPv4 fallback when the primary fetch path fails.
• If media ingestion still fails, keep checking SSRF/media policy and network reachability rather than assuming the connector lacks retry behavior.

Mistral provider (v2026.2.22)

OpenClaw supports Mistral for:

• Text/image model routing (mistral/...)
• Audio transcription via Voxtral (media understanding)
• Memory embeddings (memorySearch.provider = "mistral")

Onboarding examples:

openclaw onboard --auth-choice mistral-api-key

# non-interactive
openclaw onboard --mistral-api-key "$MISTRAL_API_KEY"

Minimal config shape (example):

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "mistral/mistral-large-latest"
      }
    }
  }
}

Audio transcription model wiring example:

{
  "tools": {
    "media": {
      "audio": {
        "enabled": true,
        "models": [{ "provider": "mistral", "model": "voxtral-mini-latest" }]
      }
    }
  }
}

Operational notes:

• Auth uses MISTRAL_API_KEY.
• Default base URL: https://api.mistral.ai/v1.
• Embeddings endpoint: /v1/embeddings (commonly mistral-embed).
• Audio transcriptions endpoint: /v1/audio/transcriptions.

Synology Chat channel (plugin) (v2026.2.22)

Synology Chat is plugin-based (not included in default core channel install).

Install the plugin from a local checkout:

openclaw plugins install ./extensions/synology-chat

High-level setup:

1. Create an incoming webhook in Synology Chat and copy its URL. 2. Create an outgoing webhook with a secret token. 3. Point the outgoing webhook to your gateway (default: /webhook/synology). 4. Configure channels.synology-chat and restart the gateway.

Minimal config example:

{
  "channels": {
    "synology-chat": {
      "enabled": true,
      "token": "synology-outgoing-token",
      "incomingUrl": "https://nas.example.com/webapi/entry.cgi?api=SYNO.Chat.External&method=incoming&version=2&token=...",
      "webhookPath": "/webhook/synology",
      "dmPolicy": "allowlist",
      "allowedUserIds": ["123456"],
      "rateLimitPerMinute": 30,
      "allowInsecureSsl": false
    }
  }
}

Safety defaults:

• Prefer dmPolicy: "allowlist" in production.
• Keep allowInsecureSsl: false unless you explicitly trust your NAS TLS setup.

Provider notes (v2026.2.23)

• kilocode provider is supported with first-class auth/onboarding and implicit provider detection.
• Moonshot/Kimi surfaces: web_search supports provider "kimi", and media understanding adds a native Moonshot video provider.

OpenClaw Concepts (Additional Coverage)

Confirmed concepts (content extracted)

Agent loop

• Agent loop is a serialized run path: intake, prompt assembly, model inference, tools, streaming, persistence.
• Queue lanes prevent race conditions across concurrent requests.
• Lifecycle/tool/assistant streams provide observability and wait/timeout semantics.

System prompt and context

• System prompt is OpenClaw-composed per run and supports full / minimal / none prompt modes.
• Context window includes prompt, transcript, tool results, attachments, and schema overhead.
• Bootstrap files are injected into context and should remain concise.

Workspace, OAuth, and memory

• Workspace is default execution root and memory surface, but not a hard sandbox by itself.
• OAuth profiles are per-agent and refreshed with lock-safe credential handling.
• Memory is markdown-first (daily + durable layers) with optional semantic/hybrid retrieval.

Session pruning and compaction

• Session pruning trims old tool results in-memory (non-persistent).
• Compaction summarizes older context and persists the summary in transcript.
• Use both as complementary controls for long-running sessions.
• (v2026.3.7) postCompactionSections controls which AGENTS.md sections re-inject after compaction.
• (v2026.3.7) recentTurnsPreserve and quality-guard retry knobs are tunable via config.
• (v2026.3.7) session:compact:before/session:compact:after events emitted with session/count metadata for plugin/automation hooks.

Context Engine plugins (v2026.3.7)

• ContextEngine plugin slot with lifecycle hooks: bootstrap, ingest, assemble, compact, afterTurn, prepareSubagentSpawn, onSubagentEnded.
• Slot-based registry with config-driven resolution enables alternative context strategies (e.g. lossless-claw) without modifying core compaction logic.
• LegacyContextEngine wrapper preserves existing compaction behavior when no plugin is configured.
• Scoped subagent runtime for plugin runtimes via AsyncLocalStorage.

Plugin prompt injection controls (v2026.3.7)

• prependSystemContext/appendSystemContext place static plugin guidance in system prompt space for provider caching and lower repeated cost.
• plugins.entries.<id>.hooks.allowPromptInjection controls whether plugins can mutate prompts.
• Unknown typed hook names are validated at runtime; legacy before_agent_start overrides preserved while stripping prompt-mutating fields when injection is disabled.

Presence and messages

• Presence is best-effort gateway/client/node visibility; stable instanceId prevents duplicate entries.
• Message flow includes dedupe, optional inbound debounce, queue modes, and channel-aware outbound behavior.

Background tasks and flows (v2026.3.28)

• Background tasks unified into a shared SQLite-backed control plane (ACP, subagent, cron, background CLI under one ledger).
• Detached lifecycle updates routed through the executor seam with audit/maintenance/status visibility.
• Auto-cleanup and lost-run recovery tightened.
• ClawFlow: first linear flow control surface — openclaw flows list|show|cancel.
• Multi-task manual flows separate from one-task auto-sync flows.
• Blocked state persisted on one-task flows; same flow can reopen cleanly on retry.
• Doctor recovery hints for obviously orphaned or broken flow/task linkage.

Memory/QMD improvements (v2026.3.28)

• Per-agent memorySearch.qmd.extraCollections for cross-agent session search.
• CJK-aware chunk sizing (weight CJK text correctly, preserve surrogate-pair characters).
• Session indexer includes .jsonl.reset.* and .jsonl.deleted.* transcripts.
• memory.qmd.searchTool as exact mcporter tool override for custom QMD MCP tools.
• memory.qmd.update.embedInterval as dedicated embed-cadence maintenance timer.

Source availability notes

The following Concepts URLs were listed in navigation during ingestion but returned 404 or non-extractable content:

• https://docs.openclaw.ai/concepts/agent-runtime
• https://docs.openclaw.ai/concepts/bootstrapping
• https://docs.openclaw.ai/concepts/session-management
• https://docs.openclaw.ai/concepts/sessions
• https://docs.openclaw.ai/concepts/session-tools
• https://docs.openclaw.ai/concepts/multi-agent-routing
• https://docs.openclaw.ai/concepts/streaming-and-chunking
• https://docs.openclaw.ai/concepts/retry-policy
• https://docs.openclaw.ai/concepts/command-queue

Fallback coverage for these topics is integrated in SKILL.md and supporting references (architecture, operations, tools, gateway).

OpenClaw Configuration and Workspace Bootstrap

Operator mental model for openclaw.json

Treat the config as six blocks that should be reviewed in order:

1. gateway 2. agents 3. channels 4. bindings 5. session and messages 6. heartbeat, tools, cron, and hooks

This keeps debugging local: gateway issues first, routing next, then behavior/policy.

Config format and validation

• The main config is typically ~/.openclaw/openclaw.json.
• OpenClaw uses strict schema validation; unknown keys, wrong types, and malformed structure should be treated as startup blockers.
• Run openclaw config validate before restart/reload after manual edits.
• If you are unsure whether a change hot-applies, validate first and then use openclaw gateway restart instead of guessing.

Includes and composition

• Use $include to split large configs into logical files such as agents and channels.
• Keep include boundaries stable so operators know where to look during incidents.
• Prefer composition for multi-agent or multi-channel deployments instead of one oversized config blob.

Example shape:

{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  channels: { $include: "./channels.json5" },
}

Secrets and environment sources

• Environment variables can come from the process, a local .env, or ~/.openclaw/.env.
• Do not hardcode channel tokens or provider secrets when an env-based path is available.
• After changing secret sources, rerun validation and health checks before testing channels.
• Late-May 2026 releases ignore workspace dotenv provider credentials and migrate legacy non-canonical api_key auth profiles to canonical form. Keep provider credentials in the intended OpenClaw auth/profile source instead of relying on workspace-local dotenv leakage.

Hot-reload vs restart boundaries

• Runtime behavior such as agents, channels, heartbeat, messages, and some tools settings often hot-apply.
• Gateway server settings such as bind, port, and related HTTP exposure should be treated as restart-bound unless verified otherwise.
• When rollout safety matters more than speed, prefer an explicit restart and status check over assuming live reload.

Local-model lean mode (v2026.4.15)

• agents.defaults.experimental.localModelLean: true drops heavyweight default tools such as browser, cron, and message for weaker local-model deployments.
• Treat this as an opt-in low-context profile for constrained local runtimes, not as the normal default for strong hosted models.

Workspace bootstrap files

Common workspace/bootstrap surfaces include:

• AGENTS.md
• SOUL.md
• USER.md
• TOOLS.md
• HEARTBEAT.md
• IDENTITY.md
• MEMORY.md
• memory/YYYY-MM-DD.md

These files are part of the agent context surface. Keep them short, current, and role-specific.

Memory backend updates (v2026.4.15)

• memory-lancedb can now store durable indexes on cloud object storage instead of local disk only.
• Dreaming now defaults to separate storage mode; Dreaming phase files go under memory/dreaming/... instead of inflating the daily memory file.
• If you want the old inline behavior, set the corresponding dreaming storage mode explicitly instead of assuming the legacy default.

Heartbeat guidance

• Do not enable proactive heartbeat just because the feature exists.
• Add a clear HEARTBEAT.md contract first, including when to stay silent.
• Use lightweight context for heartbeat when bootstrap files are large.
• Give each agent its own heartbeat settings in multi-agent deployments.

Safe initial tool posture

• Start from least privilege and open up only the tools you need.
• tools.deny is a practical way to block high-risk surfaces such as browser automation or canvas while the deployment is still being proven.
• Revisit tool policy after channel trust, allowlists, and routing rules are stable.

Config parsing hardening (v2026.5.27-v2026.5.28)

• Partial numeric parsing is rejected for gateway timeouts, model limits, directory limits, message options, webhook values, cron epochs, media content lengths, sandbox stat fields, and duration values. Use exact typed values in generated config.
• Empty config path segments, noncanonical schema array refs, unsafe Telegram callback pages, and invalid Teams attachment-fetch DNS targets fail earlier. Treat these as config bugs to fix at source instead of retrying the same generated payload.
• Explicit agent runtime pins are preserved during Codex model migration, and provider auth health labels are clearer. Keep runtime pins intentional when migrating Codex/GitHub Copilot/OpenAI profiles.

OpenClaw Gateway

Role of the gateway

• The gateway is the always-on control plane and message routing hub.
• It multiplexes WebSocket control, HTTP APIs, UI surfaces, and channel connectivity.
• Default posture is local-first bind with authentication required.

Startup and baseline checks

• Start with explicit port and optional verbose mode during bring-up.
• Confirm runtime health (running + RPC probe success) before channel testing.
• Probe channel readiness separately after gateway health passes.
• Monitor logs continuously during initial setup and rollout changes.

Container probe endpoints (v2026.3.1)

For Docker/Kubernetes liveness/readiness checks, the gateway exposes unauthenticated probe endpoints:

• Liveness: /healthz (alias: /health)
• Readiness: /readyz (alias: /ready)

Use these for process/container probes only; for authenticated deeper checks, use openclaw health and channel probe commands.

Bind/auth rules you must enforce

• Port precedence: CLI flag, then env var, then config, then default.
• Bind precedence follows explicit override before config default.
• Non-loopback binds must be protected by token/password auth.
• Clients must supply auth even when reaching gateway through SSH tunnel.
• (v2026.3.7) When both gateway.auth.token and gateway.auth.password are configured (including SecretRefs), set gateway.auth.mode to token or password explicitly. Omitting it causes startup/pairing/TUI failures.
• SecretRef is supported for gateway.auth.token with auth-mode guardrails.

Remote access patterns

• Preferred: private overlay network (for example Tailscale/VPN).
• Fallback: SSH local tunnel to loopback gateway endpoint.
• Keep public exposure minimal and pair remote access with strict auth.
• For remote onboarding on macOS, expect a shared gateway token flow when paired-device auth is not sufficient; retrieve the token from the gateway host instead of guessing or reusing stale local credentials.

Configuration levers

• Use dedicated config and state paths for profile isolation.
• Keep reload mode intentional (hot, off, restart, hybrid).
• For multi-gateway setups, isolate port, state dir, config path, and workspace.

Operations checklist

• Health: gateway status + deep/json where needed.
• Readiness: channel probe + health endpoints.
• Lifecycle: install/restart/stop under launchd or systemd supervision.
• Recovery: on event-sequence gaps, refresh state before continuing actions.

Failure signatures and fixes

• Bind refused without auth: add token/password before non-loopback bind.
• Address in use: resolve competing process or change port.
• Start blocked by mode mismatch: align gateway mode in config.
• Unauthorized connect: verify token/password parity between client and gateway.

Do / Don’t

• Do run one gateway per host by default.
• Do supervise the process for auto-restart and persistence.
• Don’t rely on unauthenticated remote bindings.
• Don’t continue workflows after event gaps without explicit state refresh.

Web surfaces and exposure model

• Control UI is served by gateway on the same endpoint surface and can be path-prefixed.
• Keep same-origin WS defaults unless explicit trusted origins are required.
• Tailscale serve/funnel modes are preferred for remote web exposure over direct public bind.
• Funnel mode should be paired with strong password auth and explicit exposure review.

Control UI operations

• Control UI is a first-class operations surface for chat, channels, sessions, cron, skills, nodes, and config.
• Remote browser/device access follows pairing trust workflow; new devices require explicit approval.
• Prefer secure contexts (loopback or HTTPS via Tailscale Serve) to preserve device-identity protections.
• Use config.apply workflows with validation and conflict guards for safer live config edits.
• Control UI token auth is intentionally session-scoped in the browser; refresh in the same tab should survive, but operators should expect to re-authenticate after a fresh browser session.

Model auth status (v2026.4.15)

• Control UI now exposes a model-auth status card showing OAuth token health and provider rate-limit pressure.
• The backing models.authStatus gateway method strips credentials and caches results briefly (60s) for operator visibility without exposing secrets.
• Use this card during incident triage before re-running onboarding flows or manually rotating tokens.

Gateway and web updates (v2026.5.12)

• Control UI/WebChat now has persisted auto-scroll modes, so operators can choose "follow streaming", near-bottom behavior, or manual new-message handling.
• Gateway/browser/sandbox/transcript paths received another security/provenance hardening pass; after upgrade, re-test browser-origin expectations, sandbox assumptions, and paired-device trust instead of carrying old exceptions forward.
• If reply delivery or UI continuity changed after upgrade, inspect the new UI mode and the hardened auth/provenance path before assuming model/provider instability.

Gateway and runtime updates (v2026.5.27-v2026.5.28)

• No-auth Tailscale exposure is rejected; keep remote gateway exposure on authenticated Serve/Funnel or tunnel paths instead of relying on tailnet reachability alone.
• Browser tokens expire after auth rotation, stale restart continuations are avoided, probe client closes drain cleanly, and retry-after/rate-limit cooldown fallbacks are preserved. Treat post-rotation reconnect tests as part of upgrade validation.
• Browser and Gateway inputs now reject invalid tab indexes, excessive viewport resizes, explicit zero CDP ports, malformed geolocation values, unsafe screenshot/permission timeouts, explicit zero Gateway ports, and loose response-body limits. Update automation harnesses that used placeholder zero/NaN values.
• Runtime-config message actions resolve against the active runtime config, and session active-run buffers are cleared after completion. If messages land in the wrong context after upgrade, inspect runtime-config selection before changing channel policy.

Tailscale modes and policy

• serve: recommended tailnet HTTPS proxy while gateway stays loopback-bound.
• funnel: public exposure mode and must use password-based auth.
• tailnet bind: direct tailnet endpoint without serve/funnel proxy behavior.
• If explicit credentials are required even on Serve, disable identity-header auth allowance.

Configuration and reload behavior

• Config is schema-strict; invalid keys/types can block gateway startup.
• Use full replace (config.apply) for controlled rollouts and patch merge (config.patch) for targeted updates.
• Patch semantics: object keys merge, arrays replace, null deletes keys.
• Gateway server and infra-level settings typically require restart, while many runtime settings hot-apply.
• Include/env substitution errors should be treated as startup blockers and validated early.

Remote access pattern

• Recommended remote pattern keeps gateway loopback-bound and accesses it over SSH tunnel or Tailscale Serve.
• Remote CLI mode should carry explicit URL + credentials configuration.
• When explicit --url is used in CLI calls, always pass auth credentials explicitly as well.
• Nodes remain WS clients; they do not host gateway service state.

Security hardening essentials

• Assume prompt injection and hostile input are possible on every channel.
• Apply identity controls first (pairing/allowlists), then scope controls (mentions/tools/sandbox), then model policy.
• Keep gateway loopback-bound by default and require strong token/password for non-loopback access.
• Disable insecure control UI auth downgrades in production environments.
• For direct HTTPS deployments, you can enable HSTS via gateway.http.securityHeaders.strictTransportSecurity.
• Enforce strict file permissions for config/state and enable sensitive-data redaction in logs.
• Browser-originated WebSocket connections must pass origin validation even behind trusted-proxy; never rely on forwarded headers as a substitute for allowed-origin policy.
• Repeated-dot hostnames normalize before policy checks, and untrusted Microsoft Teams service URLs are blocked. Keep DNS/service-url allowlists canonical rather than matching raw inbound strings.

Auth and media hardening notes (v2026.4.15)

• HTTP bearer auth is now resolved per request on the server and upgrade paths, so secret rotation via reload/hot config applies immediately instead of waiting for a gateway restart.
• /mcp bearer checks now use constant-time comparison and reject non-loopback browser-origin requests before the auth gate runs.
• Webchat audio/media embedding enforces localRoots containment and rejects remote-host file:// URLs.

New security and reachability notes (v2026.3.11-v2026.3.13)

• Scope-limited probe RPC should be treated as degraded reachability, not full health, when downstream permissions or visibility are incomplete.
• Gateway/client request handling now bounds unanswered client requests more aggressively; if UI/API calls appear to hang, inspect gateway logs for timed-out pending requests instead of assuming the request is still live.
• If local gateway.auth.* uses SecretRefs, treat missing secret resolution as a hard failure and fix the secret source before retrying startup.

Recovery release notes (v2026.3.13-1)

• The v2026.3.13-1 tag is a release-path recovery tag; do not treat the -1 suffix as a new npm/runtime version line.
• If the control UI is reached through an insecure compatibility path, shared-auth behavior has been restored; still prefer loopback or HTTPS/Tailscale contexts for normal operations.
• Connect failures are classified more explicitly now, so incident triage should distinguish auth/connectivity failures from generic UI breakage.
• Docker deployments can set OPENCLAW_TZ to keep gateway/container timezone behavior explicit.

New audit finding: gateway.http.no_auth (v2026.2.19)

• Trigger condition: gateway.auth.mode="none" with reachable Gateway HTTP APIs.
• Risk model: loopback exposure is warning-level; remote/public exposure is critical.
• Operational rule: never run no-auth mode on non-loopback endpoints.
• Remediation: re-enable auth (token/password), revert to loopback bind, and re-run audit checks.

iOS wake/reconnect behavior (v2026.2.19)

• Gateway can trigger APNs wake before nodes.invoke for disconnected iOS nodes.
• Silent-push wake helps restore gateway sessions while app is backgrounded.
• If invoke reliability drops, validate APNs registration/signing first, then run push-test pipeline.

OpenClaw Getting Started

This reference assumes OpenClaw is already installed.

If not installed, use references/installation.md first.

Platform and runtime guidance

• Prefer Node runtime for gateway workloads.
• Avoid Bun for gateway/channel-critical deployments due to known connector instability.
• On Windows, prefer WSL2 for gateway operation.
• Treat mobile/macOS apps as node/companion surfaces, not gateway replacements.

Service deployment patterns

• Recommended bootstrap: openclaw onboard --install-daemon.
• Alternative lifecycle path: openclaw gateway install and service-specific commands.
• Use openclaw doctor for repair/migration and configuration drift checks.

Minimal first-run path

1. Run onboarding with daemon install. 2. Print the active config path with openclaw config file and inspect the generated workspace/bootstrap files. 3. Validate the config with openclaw config validate before manual edits. 4. Verify gateway status. 5. Open dashboard/control UI and run first chat.

Fast verification checklist

• openclaw config file resolves the config you expect to operate.
• openclaw config validate passes before restart/reload.
• openclaw gateway status returns healthy runtime.
• openclaw dashboard opens local control surface successfully.
• Optional: send a test message only after channel provisioning is complete.

Onboarding decision points

• Choose CLI wizard for full control of gateway/workspace/channels/skills.
• Choose macOS app for guided local first run on Mac hardware.
• For custom providers, capture endpoint type, base URL, API key, model ID, alias, and endpoint ID explicitly.

Onboarding output expectations

• Provisioned runtime with gateway and workspace defaults.
• Channel and skill baseline from wizard choices.
• Reusable provider endpoint entries for multi-endpoint environments.

CLI wizard execution map

1. Configure model/provider and default model. 2. Select workspace path and bootstrap files. 3. Configure gateway port/bind/auth/remote exposure. 4. Select channels and pairing prompts. 5. Install daemon/service unit. 6. Run health checks. 7. Install recommended skills.

Wizard pitfalls to avoid

• Re-running wizard is non-destructive unless reset is explicitly chosen.
• Invalid/legacy config should be repaired with openclaw doctor before rerun.
• Remote mode configures local client targeting only; it does not provision remote host.
• --json does not imply non-interactive mode; use --non-interactive explicitly.

macOS app onboarding specifics

• First-run flow includes local network/security prompts and explicit local-vs-remote gateway choice.
• Remote gateway mode requires credentials prepared on the remote host.
• App onboarding requests OS permissions for automation/media/device integrations.
• Dedicated onboarding chat session is created to bootstrap user guidance separately from normal chats.

Personal assistant bootstrap

• Recommended pattern uses a dedicated assistant number and strict sender allowlist.
• Start conservative: keep proactive heartbeat disabled until trust and safety prompts are tuned.
• Validate control UI access and token-based auth before external messaging tests.

Workspace and session defaults

• Workspace acts as persistent memory context and can be managed as a git repository.
• Bootstrap creates core identity/tools/persona files for first-run guidance.
• Session reset/compact flows should be part of standard operator controls.

Recommended bootstrap files to review early:

• AGENTS.md for top-level operating rules.
• SOUL.md and IDENTITY.md for assistant persona and role stability.
• USER.md for user-specific context.
• TOOLS.md for tool-use policy.
• HEARTBEAT.md before enabling proactive turns.
• MEMORY.md and memory/YYYY-MM-DD.md for durable and daily memory load.

Keep these files concise; they directly affect context cost and can drown out live conversation if they become bloated.

Day-1 safety baseline

• Enforce channel allowlist constraints before exposing assistant to contacts.
• Require mention-based activation in groups for noise reduction.
• Use per-sender session scope for cleaner isolation and incident triage.

Quickstart acceptance criteria

• Gateway is running, authentication is configured, and control UI is reachable.
• Quick validation uses node version, gateway status, and dashboard open checks.
• Message send checks are optional and only valid after channel provisioning.

OpenClaw Installation

Use this reference only when OpenClaw is not installed yet or when migrating environments.

Supported install paths

• Official installer script (recommended for fresh hosts).
• Global npm/pnpm install for managed environments.
• Source build path for contributors.

Prerequisites

• Node 22+ runtime.
• Windows deployments should prefer WSL2 for gateway compatibility.
• pnpm users must approve build scripts when prompted.

Post-install validation

1. Verify runtime health and status. 2. Open dashboard/control UI. 3. Confirm global binary path resolution. 4. Run diagnostics (doctor) if startup is inconsistent.

Platform notes

• Node runtime is preferred for gateway workloads.
• Bun is not recommended for channel-critical gateway usage.
• Keep config/state paths explicit in automation.

Migration / maintenance

• Re-run onboarding/configuration when environment changes.
• Use service install/repair commands for daemon lifecycle alignment.

Install-surface update (v2026.5.12)

• Recent releases externalize several provider/channel dependency cones from the core install, including WhatsApp, Slack, Amazon Bedrock, and Anthropic Vertex.
• Treat upgrades as "install only what you use" rather than assuming the core runtime still ships every optional provider/channel path by default.
• After upgrade, re-check plugin/provider availability before blaming auth or routing. Missing optional packages can now be an expected cause, not a broken install.
• Plugin install/update flows were hardened and pnpm 11 is supported, so prefer current package-manager paths instead of freezing on older pnpm behavior.

Discord voice dependency note (v2026.2.22)

• Discord voice now treats @discordjs/opus as an optional dependency.
• If native Opus builds fail, install/update should no longer hard-fail; runtime decoding falls back to opusscript.
• If you still see voice failures: validate Node toolchain/native build prerequisites on the host and confirm the voice path in your channel configuration.

OpenClaw Nodes

Node role and boundary

• Nodes are companion executors connected to gateway WebSocket with role node.
• Nodes do not host channels or gateway state; they expose command capabilities only.
• Gateway remains the orchestration authority and routes node invocations.

Pairing and lifecycle

• Node devices require explicit pairing approval for trusted operation.
• Use device/node status and describe commands to validate capability visibility.
• Distinguish transport pairing/trust from node-specific approval stores.

Execution model

• Gateway model loop decides when node commands are invoked.
• Node host executes system commands locally when host=node execution is selected.
• Exec approvals are enforced on node host and should be managed as per-host policy.

Capability families

• Canvas/A2UI interaction and rendering commands.
• Camera, screen recording, and location capture commands.
• System execution and notification commands.
• Optional platform-specific capabilities (for example SMS on Android nodes).

Android node surface expansion (v2026.3.1)

Recent Android nodes expose additional command families commonly used in automation runs:

• device.permissions, device.health
• notifications.actions (open / dismiss / reply)
• system.notify
• photos.latest
• contacts.search, contacts.add
• calendar.events, calendar.add
• motion.activity, motion.pedometer

Pending work queue primitives (v2026.3.11)

• Gateway exposes node.pending.enqueue and node.pending.drain as narrow in-memory primitives for pending work delivery to dormant or waking nodes.
• Treat them as gateway-coordinated queue helpers, not as durable job storage.
• If node wake/reconnect flows are flaky, inspect pending-work behavior alongside APNs/push signaling before blaming the node executor itself.

Safeguards

• Keep explicit allowlists for high-risk system execution.
• Validate node foreground/permission constraints before media commands.
• Use dedicated node display names and stable IDs for repeatable routing.
• Treat node pairing and access like operator-level trust.

OpenClaw Operations

CLI operating model

• CLI supports profile/dev isolation and broad command families for gateway, channels, models, sessions, and security.
• Use profile scoping for multi-environment separation instead of mixing state directories manually.
• Keep status/health checks as first responders before deep troubleshooting.

Core operator command sets

• Runtime checks: status, health, gateway status, channels status --probe.
• Config lifecycle: configure, config file, config get/set/unset, onboarding/setup commands.
• Log inspection: logs --follow, structured JSON logs for automation pipelines.
• Gateway lifecycle: install/start/stop/restart/service status.
• Channel lifecycle: list/add/login/logout/remove and channel log inspection.

Recommended local iteration loop after manual config edits:

1. openclaw config file 2. openclaw config validate 3. openclaw doctor 4. openclaw gateway restart when touching gateway infra settings or when hot-reload behavior is unclear.

Config file path (v2026.3.1)

Print the active config file location:

openclaw config file

Resolution rule (per docs): uses OPENCLAW_CONFIG_PATH if set; otherwise uses the default config location.

Config validation (v2026.3.2)

Validate a config file before starting the gateway:

openclaw config validate
openclaw config validate --json

Use this as a first step when the gateway fails fast on invalid config keys or paths.

As of v2026.3.11, top-level config.set, config.patch, and config.apply errors surface multiple validation issues in the summary. Read the first few issues carefully before making another write attempt.

Cron/heartbeat lightweight context (v2026.3.1)

When you want automation turns to run with a smaller bootstrap payload:

• Cron agent turns: --light-context
• Heartbeat: agents.*.heartbeat.lightContext

Use this when bootstrap files are large and you want to reduce token/context overhead for scheduled runs.

Updating (v2026.2.22)

Prefer controlled, observable updates:

1. Preview the update plan (--dry-run). 2. Run the update (manual or wizard). 3. Validate with doctor + health.

Key commands:

openclaw update
openclaw update --dry-run
openclaw update status
openclaw update wizard
openclaw update --channel stable
openclaw update --channel beta
openclaw update --channel dev
openclaw update --no-restart
openclaw update --json

Channel semantics and install method alignment:

• stable / beta: installs from npm using the matching dist-tag.
• dev: ensures a git checkout (default ~/openclaw, override with OPENCLAW_GIT_DIR), then updates it.

Operational notes:

• Treat downgrades as risky (older versions can break config); require explicit confirmation.
• If the gateway is supervised (launchd/systemd), prefer openclaw gateway restart after updates.
• After upgrading to v2026.3.11+, run openclaw doctor --fix to migrate legacy cron storage and legacy cron notify/webhook metadata before trusting scheduled delivery.
• For v2026.3.13-1, remember that the -1 suffix is only a GitHub release/tag recovery marker; runtime versioning still tracks 2026.3.13.
• After upgrading to v2026.5.12, explicitly verify optional provider/channel/plugin presence because several dependency cones are now externalized from the core install.
• Plugin install/update handling is safer in the May 2026 line and supports pnpm 11, so prefer the current install path over preserving old package-manager workarounds.
• ACP can now use configured fallback runtimes before output is emitted; if a primary backend is flaky, validate acp.fallbacks before treating the whole ACP path as down.
• After upgrading to v2026.5.27 or v2026.5.28, re-run doctor, channel probes, provider auth checks, and any custom browser/Codex harnesses. The release line intentionally rejects malformed numeric/version options, workspace dotenv provider credentials, unsafe browser inputs, and stale restart continuations earlier.

Automatic updates (Gateway core auto-updater)

The Gateway has an optional built-in auto-updater. It is off by default.

Minimal example:

{
  "update": {
    "channel": "stable",
    "auto": {
      "enabled": true,
      "stableDelayHours": 6,
      "stableJitterHours": 12,
      "betaCheckIntervalHours": 1
    }
  }
}

Behavior summary:

• stable: waits stableDelayHours, then applies a deterministic per-install jitter up to stableJitterHours.
• beta: checks on betaCheckIntervalHours cadence (typically hourly).
• dev: does not auto-apply; use manual openclaw update.

After any update (manual or automated), use:

openclaw doctor
openclaw gateway restart
openclaw health

Safe operations pattern

1. Validate config path and schema before rollout. 2. Validate gateway health and RPC reachability. 3. Probe channels and providers before functional tests. 4. Tail logs during rollout or incident triage. 5. Run doctor and security audit when warnings persist. 6. Apply config changes with explicit profile targeting.

Security and reliability controls

• Prefer security audit workflows to detect risky defaults.
• Use deep checks only when necessary (they may trigger live provider calls).
• Keep remote gateway calls authenticated and timeout-bounded.
• Avoid Bun runtime for gateway in channel-critical environments.
• Child commands launched from OpenClaw now carry OPENCLAW_CLI; use that marker in wrapper scripts when you need different behavior for CLI-spawned subprocesses.
• Side-effecting command wrappers and unsafe Node runtime environment overrides are blocked in the late-May release line. Move required behavior into explicit config or approved wrapper paths rather than relying on inherited process state.

CLI output hygiene (security)

• As of v2026.2.22, openclaw config get redacts sensitive values before printing.
• Treat any config output as potentially sensitive anyway (paths, scopes, and non-redacted values can still reveal operational details).

Help entry workflow

• Use docs-driven triage order: install sanity, gateway troubleshooting, logging, then doctor repairs.
• Keep this escalation order in runbooks to reduce random debugging paths.
• When incidents are unclear, collect logs + status snapshots before escalating.

Documentation navigation strategy

• Use start/hubs as index to discover deep pages not visible in sidebar navigation.
• Route day-1 issues to Getting Started/Quickstart/Help hubs first.
• Route operational incidents to Gateway + Operations hub branch.

Troubleshooting command ladder

1. openclaw status 2. openclaw gateway status 3. openclaw logs --follow 4. openclaw doctor 5. openclaw channels status --probe

Paired-device hygiene commands (v2026.2.19)

• Remove a specific paired entry: openclaw devices remove <device-id>.
• Remove via gateway/device-pair flow: device.pair.remove.
• Bulk cleanup with confirmation: openclaw devices clear --yes.
• Include pending requests during cleanup when needed: openclaw devices clear --yes --pending.
• Run cleanup before re-pairing when stale pair records cause routing/auth anomalies.

Incident triage patterns

• No replies: inspect pairing, mention gating, and allowlist policy first.
• Connectivity loops: validate auth mode, secure context, and gateway reachability.
• Startup failure: check gateway mode, auth for bind mode, and port conflicts.
• Channel flow failure: validate API scopes, policy gates, and pairing approvals.
• Node/browser tool failures: isolate permissions, approvals, foreground constraints, and runtime dependencies.
• Codex/app-server failures: check runtime model resolution, app-server helper startup, native hook relay generation, and session-lock cleanup before deleting shared runtime state.

Patch-level triage additions (v2026.3.13-1)

• If compaction quality regresses after update, inspect post-compaction sanity using full-session token counts before tuning prompt/summary policies.
• If session continuity breaks after reset flows, verify whether lastAccountId / lastThreadId were preserved instead of assuming channel routing drift.
• If gateway/UI requests look stuck, check for bounded unanswered client requests in logs rather than waiting indefinitely.

Cron migration note (BREAKING, v2026.3.11)

• Isolated cron delivery no longer falls back to ad hoc agent sends or main-session summaries.
• Legacy notify/webhook metadata should be migrated with openclaw doctor --fix after upgrade.
• If scheduled jobs appear "silent" after updating, inspect cron storage and doctor output before changing routing or agent policy.

OpenClaw Tools

What matters operationally

• OpenClaw tools are policy-controlled capabilities exposed to agents and sessions.
• Effective permissions are computed by profile + provider overrides + allow/deny.
• Node and gateway tools are high-impact surfaces and need explicit gating.

Tool governance model

• Start from tools.profile (minimal, coding, messaging, full).
• Narrow per provider with tools.byProvider.
• Apply explicit tools.allow / tools.deny (deny takes precedence).
• Use group aliases (for example group:fs, group:web, group:nodes) to keep policy readable.

Onboarding default tools profile (BREAKING, v2026.3.2)

For new local installs, onboarding now defaults tools.profile to messaging. If you expect coding/system tools, set tools.profile explicitly (and keep it as least-privilege).

High-impact tools and constraints

• exec runs shell commands; prefer bounded timeout and background session control.
• process manages running sessions (poll, log, kill, remove) and is required for non-blocking flows.
• apply_patch is experimental and typically workspace-scoped.
• nodes controls approval lifecycle and remote actions (run, camera, screen, location).
• sessions_* spawns and communicates with sub-agents, subject to visibility restrictions.

Optional plugin tool: diffs (v2026.3.1)

OpenClaw can enable an optional read-only diff renderer that produces a gateway-hosted viewer URL and/or a PNG.

Enable:

{
  plugins: {
    entries: {
      diffs: { enabled: true },
    },
  },
}

Operational notes:

• Intended for view-only rendering (before/after or unified patch).
• Viewer pages are served by the gateway under /plugins/diffs/....
• PNG rendering requires a Chromium-compatible browser; configure browser.executablePath if auto-detect fails.

v2026.3.2 adds PDF output support and quality controls for diff artifacts.

Safety practices

• Enable loop detection to prevent repetitive no-progress tool loops.
• Require explicit consent before camera/screen recording operations.
• Treat elevated execution as exceptional and policy-gated.
• Validate node status/capabilities before invoking remote actions.
• Prefer least-privilege profile first, then add explicit allow entries.

Plugin and binding safety (v2026.3.13)

• Channel/binding collisions in plugins now fail fast instead of silently competing at runtime.
• Treat collision errors as configuration bugs to resolve explicitly; do not work around them by retrying the same plugin load order.

Plugin install security (v2026.3.28)

• before_install hook with structured request provenance, built-in scan status, and install-target metadata for external security scanners.
• --dangerously-force-unsafe-install as break-glass override for built-in dangerous-code false positives.
• Gateway-backed skill dependency installs blocked on dangerous-code critical findings unless override is set.

Plugin and coordination updates (v2026.5.27-v2026.5.28)

• ClawHub package/catalog listings now surface plugin display metadata, skill verification, and trust signals. Treat those as operator hints, not as a replacement for install policy and provenance review.
• The Plugin SDK exposes plugin approval action metadata and a reply payload sending hook for plugins that must deliver channel-owned replies. Avoid custom channel-send workarounds when the hook can preserve delivery ownership.
• GitHub Copilot and Tokenjuice are externalized as official install-on-demand plugins with npm and ClawHub metadata. Verify optional plugin presence after upgrading lean installs.
• Workboard adds agent coordination tools for tracking and handing off active agent work. Gate these like other session/agent-control tools because they affect live coordination state.
• MCP structured content now surfaces in agent tool results, and malformed tool-argument repair is stricter for smart-quoted edit arrays and exact escaped arguments.

Loop guards and tool identity (v2026.4.15)

• The unknown-tool stream guard is now enabled by default. Keep tools.loopDetection.unknownToolThreshold explicit only when you need to raise or lower the tolerance.
• Client-defined tool names can no longer normalize-collide with built-ins or with another client tool in the same request.
• Trusted local MEDIA: passthrough is anchored to the exact raw name of the built-in tool registered for the current run; do not assume a lookalike client tool will inherit built-in media trust.

Skills snapshot invalidation (v2026.4.15)

• Config writes touching skills.* now bump the cached skills-snapshot version.
• Existing sessions still keep the snapshot that was frozen at session creation, so if a disabled skill/tool continues to be called, restart the affected session instead of repeatedly toggling config.

MCP remote servers (v2026.3.28)

• mcp.servers now supports remote HTTP/SSE URLs with auth headers.
• Bundled MCP tools use provider-safe names (serverName__toolName).
• streamable-http transport selection and per-server connection timeouts available.
• Real tool results preserved from aborted/error turns unless truncation explicitly drops them.

Browser SSRF policy (v2026.2.23)

• Config key rename: browser.ssrfPolicy.allowPrivateNetwork -> browser.ssrfPolicy.dangerouslyAllowPrivateNetwork.
• Default behavior changed when unset; treat this as a post-update verification item.
• After updating, run openclaw doctor --fix to migrate legacy config and re-check safety posture.

Practical operator recipes

• Disable a risky tool globally via deny list.
• Use messaging profile for chat workflows; coding profile only where command execution is needed.
• Restrict selected providers to minimal tools when model behavior is less predictable.
• For browser automation: verify status before snapshot/act to reduce flaky sequences.
• For browser automation after v2026.5.28: avoid placeholder or non-finite viewport, tab, timeout, geolocation, and cookie values; the Browser tool rejects malformed inputs earlier.
• For web search: provider "kimi" is supported (Moonshot); expect a two-step tool flow where results are echoed before final synthesis.
• For long-running shell tasks: use exec(background=true) + process.poll instead of blocking calls.

Troubleshooting checklist

• If a tool is unavailable, check profile, provider override, and deny list order.
• If background tasks appear stalled, inspect process session scope and poll cadence.
• If web results seem stale, account for built-in cache interval.
• If elevated mode has no effect, verify sandbox mode and elevated policy flags.