# Compressed OpenClaw Docs 2026 11 19

Source: https://rickcarlino.com/notes/note-dump-and-ai-summaries/compressed-openclaw-docs-2026-11-19.html

# OpenClaw documentation

## Getting started

On Linux, setup has one goal. Get the Gateway running, connect a model, and see a reply in the Control UI. The Gateway is the service that runs OpenClaw and keeps your channels connected.

### Prepare the host and a chat model

OpenClaw recommends Node 26. If you use Node 24, choose a supported release with the current security fixes. The installation guide gives the exact version requirements. [Node setup](https://docs.openclaw.ai/install/node)

For OpenAI, have an API key or an eligible Codex sign-in ready. For Ollama, start the local server and download a chat model before onboarding. You can add TypeSafe Jev later for decisions. The agent still needs a chat model for conversation. [Model providers](#model-providers-for-a-linux-gateway)

### Install and onboard

Follow the Linux installation guide to install OpenClaw and open onboarding. Choose Quick start if you already have working model access. OpenClaw can test a detected credential with a real model response, save your settings, and open the dashboard. If it cannot find a working connection, it opens manual provider setup. Choose Custom setup if you want to walk through all the options. [Linux installation](https://docs.openclaw.ai/install) and [onboarding](https://docs.openclaw.ai/start/wizard)

When asked whether OpenClaw should keep running in the background, choose Yes for an always-on host. On Linux this registers the Gateway as a systemd user service. If you decline, the Gateway runs in the current terminal until you stop it. Your settings stay saved, so you can install the service later.

Service registration can finish before the Gateway is ready. Wait for its health check before opening the dashboard. A standard local installation listens on port 18789. [Operating the Gateway](#operating-the-gateway)

### Send a message

Open the dashboard and send a short message in chat. A reply confirms that the browser reached the Gateway and that the agent could use its model. If the Gateway is running on another machine, establish private access and complete browser authentication and pairing first. [Control UI](#control-ui)

Once chat works, connect one channel and send a message there as well. Telegram is a straightforward first integration if you already have a bot token. Set who may contact the bot before sharing it. [Telegram setup](https://docs.openclaw.ai/channels/telegram) and [channel routing](#chat-channels-and-routing)

### If setup stops

Start by finding which connection failed. The Gateway status can show whether the service is running and reachable. If the dashboard works and a chat reply fails, check the selected model and its credentials. If Web chat works and a channel fails, inspect that channel's connection and who is permitted to message it.

The diagnostic triage can run read-only health checks and prepare a sanitized report. You can inspect the report yourself or choose an agent to help investigate. The report preparation excludes credentials, raw chat payloads, and raw logs. Doctor also offers local diagnosis and repair. [Troubleshooting](https://docs.openclaw.ai/help/troubleshooting)

[Source page on OpenClaw Docs](https://docs.openclaw.ai/start/getting-started)

## Control UI

The Control UI is the browser application served by the Gateway. The dashboard and its live connection normally share port 18789 on the Gateway host. A regular Linux install listens on the local machine. For a browser on another machine, use the private connection described in the Gateway runbook. [Operating the Gateway](#operating-the-gateway)

Use a recent supported browser. After a Gateway restart, a tab running the same dashboard build can reconnect on its own. The dashboard protects unsaved work when a new build needs a reload. A newly initialized agent database may take a few minutes to prepare. The chat shows Starting up until it is ready, or gives repair guidance if preparation fails.

### Sign in and pair the browser

Gateway authentication comes first. In the Gateway secret field, enter the token or password for this Gateway. That field is on the sign-in screen and in Gateway settings. If you need to recover a configured token, use the interactive administrative procedure on the Gateway host.

The browser also has its own device identity. Approve pairing when prompted. A paired browser can use its device token on later connections. The shared Gateway token, when used, is kept for the current tab and Gateway origin. A Gateway password stays in memory. [Connect and pair](https://docs.openclaw.ai/web/control-ui/connect-and-pair)

Onboarding normally creates a persistent token and honors an existing password. A Gateway started in token mode without a saved token can create a temporary one. If your browser has no usable token, generate a persistent token with Doctor and restart the Gateway.

An operator can disable dashboard serving while leaving bots and existing Gateway connections running. Turning it back on resumes serving without a restart. Changing where the dashboard is served requires a restart. If the installation marks configuration read-only, the dashboard shows a notice and continues to allow inspection.

### Work in a conversation

When an agent asks a question, choose an answer above the message box and submit it. You can skip the question or keep drafting a follow-up. An ordinary chat message is a separate input.

If the model rejects your latest message, Edit message can put it back in the composer. Send or clear your existing draft first. The older branch stays available for inspection, while the revised conversation uses the new branch. If you simply want the agent to continue, choose Try again. That continues the conversation without resending the original message. Check any external action before repeating it, since changing chat history cannot undo something the agent already did.

A session's menu offers two ways to branch your work. New child session opens an empty conversation under the parent. Fork session carries forward the parent's history. Both require write access to the parent. You can rename a writable session from the sidebar or chat header.

### Start work with a particular agent or workspace

Choose the agent before opening a new conversation. If you have several agents, Show all groups conversations under their agents. Pages such as Automations and Usage can also use a single-agent or all-agent view. The conversation itself still belongs to its own agent.

The command palette can find a session or prepare a new background session. In Compose, enter a task and choose the agent and workspace before starting it. Adding an attachment alone leaves it in draft. A rejected file can cancel a pending automatic start. The palette keeps its draft during the current browser session, so save anything you need before reloading.

The workspace picker offers saved projects and recent folders. For Git work, you can start a separate worktree from the branch or revision you want. The project search draws from the saved catalog. If a saved selection is no longer available, OpenClaw uses the agent workspace. [Session and workspace controls](https://docs.openclaw.ai/web/control-ui/sessions-and-sidebar)

### Manage channels, threads, and jobs

Use Channels to set up a connection and see whether its account is live. A slow provider check can leave the previous status visible with a partial-result notice. Consult the channel's setup guide for its credential and admission rules.

Threads brings together conversations from the dashboard and chat channels. Snooze temporarily hides a thread from the active sidebar while work and incoming messages can continue. Archive keeps it available for inspection or restoration. Use a thread's settings when its model or thinking level needs to differ from the agent default.

In Automations, check the next scheduled run and open Run history to inspect failures or results. A conversation that displays an automation input links back to the originating run. The Memory tab shows the selected agent's dreaming status and diary. Subagents opens delegated work beside its parent conversation. [Control UI features](https://docs.openclaw.ai/web/control-ui/feature-reference)

### Recover from a disconnect

Reconnecting means the browser is trying to restore its live connection. During that time it can display older page data and keep local drafts in memory. Once connected, it can retry a failed read. Messages, approvals, and configuration changes are never replayed automatically. Check their state before trying again.

Switching accounts or Gateways, signing out, or losing access clears the affected data and drafts. A full browser reload can also lose a draft. For error reporting, Help opens a public form with a fixed template. Review anything you add before submitting it. The form does not attach chats, logs, or credentials on its own. [Reconnecting and recovery](https://docs.openclaw.ai/web/control-ui/offline-and-reconnect)

[Source page on OpenClaw Docs](https://docs.openclaw.ai/web/control-ui)

## Model providers for a Linux Gateway

Start by choosing a conversational model. OpenAI gives you a hosted option. Ollama lets you serve a model on your own Linux machine or private network. TypeSafe Jev fills a separate role. It evaluates evidence for features that request a decision. An agent using Jev still needs a conversational model.

Model selection, authentication, and runtime are separate choices. The model determines what will answer. Authentication determines which account pays or grants access. The runtime determines which software manages the model and tool loop.

### OpenAI for conversation

In the Control UI, open Models in Settings and connect OpenAI. For usage billed through the OpenAI Platform, choose API key and use a project that has access to the model you want. Select the intended agent before connecting a shared agent credential. Personal account connections live in Profile settings. A personal default can apply to new chats, while an existing chat retains its account selection.

For subscription access, choose an eligible ChatGPT or Codex sign-in. On a headless Linux host, device sign-in lets you begin on the Gateway and finish in a browser on another machine. The OpenAI connection is separate from the token or password that gets you into the Control UI. Adding or refreshing credentials normally preserves your existing primary model. Choose a new model explicitly if you want to switch. [OpenAI setup](https://docs.openclaw.ai/providers/openai/setup) and [authentication](https://docs.openclaw.ai/providers/openai/authentication)

An eligible official OpenAI route can use the bundled Codex runtime automatically. A custom endpoint or request adapter generally uses the OpenClaw runtime by default. If your workflow relies on behavior specific to one runtime, check which is active. Native Codex sign-in and OpenClaw's agent credentials have separate homes. Doctor can migrate old Codex model references while retaining the intended runtime. [OpenAI runtime selection](https://docs.openclaw.ai/providers/openai/runtimes)

OpenAI also has a separate decision-model option. It requires access to the Decisions API and a Platform key. A ChatGPT or Codex subscription alone cannot authenticate that API. As with Jev, selecting it supplies a model to eligible decision consumers.

### Ollama on Linux

Install and start Ollama, then download the chat model you want. In onboarding, choose Ollama and Local only. Supply the address of the Ollama service. The standard local port is 11434. Use the native Ollama server address. The OpenAI-compatible endpoint can interfere with tool calls and make their data appear in chat as ordinary text. [Ollama setup](https://docs.openclaw.ai/providers/ollama/setup)

A loopback or private-network address can use the local credential marker instead of a real bearer token. A public remote endpoint requires an actual credential. The provider settings describe where Ollama is running. Authentication profiles hold credentials.

Automatic onboarding looks for an already loaded model whose server reports tool support and at least sixteen thousand tokens of context. If a downloaded model is idle, use the explicit connection flow to prepare and test it. OpenClaw saves the selected route only after it completes a real response. An embedding-only model is useful for search and cannot serve as the default for chat.

Once connected, OpenClaw can discover other installed chat models. A newly downloaded model can appear after the model list refreshes. You can restrict that list to models you configured explicitly. A failed discovery attempt retains the last successful inventory for the same connection. A successful check that finds no models clears that inventory. Repeating onboarding replaces the Ollama provider's catalog, so preserve any custom entries first. [Ollama model discovery](https://docs.openclaw.ai/providers/ollama/model-discovery)

### TypeSafe Jev for decisions

Jev appears in the Decision picker. The TypeSafe integration needs a compatible OpenClaw host and plugin with the second version of the Decision API. The TypeSafe page describes the required pairing and the source-checkout option while a compatible packaged release is pending. Check that page before installing. [TypeSafe AI plugin](https://docs.openclaw.ai/plugins/typesafe)

For hosted Jev, store a protected credential in Secrets and point the enabled TypeSafe plugin to it. Select Jev in the Decision picker. An agent with no override inherits the Gateway's decision model. An explicitly empty override disables decisions for that agent. With no global selection, decisions are off by default. After rotating the credential, refresh secrets so later requests use it.

You can choose a pinned Jev version when a workflow depends on consistent evaluation behavior. The latest alias can move. Selecting a decision model lets enabled decision features send their selected evidence to that endpoint. Hosted requests can incur charges. Using Jev leaves job scheduling and approval rules in the hands of the features that call it.

If you choose a local System One model such as Kev, start that server separately and point the plugin at its local address. OpenClaw uses the checkpoint the server has loaded. A model label alone cannot change those weights. A separate inference host needs an explicit provider entry with its own endpoint and authentication. A failure at a local endpoint does not switch evidence to hosted Jev. [TypeSafe endpoint and credential options](https://docs.openclaw.ai/plugins/typesafe)

### Test the whole route

Select an available chat model as the agent's primary. Add fallbacks in the order you want them tried. Credential rotation can keep the same model while switching accounts. Model fallback changes the model route. An explicit model choice in a chat can require that exact route and surface its error if it is unreachable. An isolated scheduled job using local Ollama can be skipped if its endpoint is down.

When diagnosing Ollama, test the model connection by itself. If that succeeds, send a normal message through the Control UI or a channel. A successful chat exercises the complete route, including agent context and tool selection. [Ollama troubleshooting](https://docs.openclaw.ai/providers/ollama/troubleshooting)

## Gateway architecture

The Gateway is the long-running process at the center of OpenClaw. It keeps channel accounts connected, routes inbound messages, and makes agent runs available to the Control UI. A normal self-hosted installation uses one Gateway. In particular, only one Gateway on a host should own the same WhatsApp connection.

The Control UI uses a live connection to request work and receive updates. A paired node uses the same Gateway to offer capabilities from another machine. Each node declares what it can do. The Gateway authorizes access before it sends work there.

### Follow a request

When the browser connects, the Gateway checks admission and sends a snapshot of current health and presence. The browser can then request work and subscribe to updates. An agent request is acknowledged with a run identifier before the work is finished. Streamed progress and the final reply are tied to that run.

This distinction matters when a connection drops. An accepted request may still be running after its browser disconnects. Refresh the run or session state before submitting it again. The event stream does not replay missed updates. API clients making requests that can change state supply a unique retry identifier so a safe retry does not start the same action twice. [Gateway protocol](https://docs.openclaw.ai/gateway/protocol)

### Authenticate and pair

Authentication identifies an allowed connection. Pairing approves a particular operator device or node. Both checks apply to the Control UI. A direct local connection can qualify for automatic pairing, while a private-network connection generally needs explicit approval. Once paired, the device gets its own token.

The device proves its identity on connection. The Gateway remembers paired device information and can require pairing repair when it changes. Private access through a virtual private network or an SSH tunnel still reaches the same Gateway, with the same authentication requirements. Use the Gateway's local bind and an authenticated path to reach it remotely. Configure any proxy-based identity according to the deployment guide. [Operating the Gateway](#operating-the-gateway) and [network model](https://docs.openclaw.ai/network)

### Schedule work and shut down

The Gateway coordinates scheduled jobs and maintenance through a shared scheduler. Each feature that schedules work owns the records needed to reconstruct its deadlines after restart. After sleep, due work can wake once and periodic work waits for its previous invocation to settle. Missed ticks can be combined, so a pause need not cause a burst of identical runs.

During shutdown the Gateway stops accepting new work, cancels pending wakeups, and waits for active callbacks and their tracked work within its shutdown budget. Plugin services can use a scheduler tied to their service or channel-account lifetime. The host closes that lifetime on retirement, and the plugin is responsible for the order in which it closes connections and flushes persistent data. [Agent loop](#agent-loop) and [automations](#automations)

[Source page on OpenClaw Docs](https://docs.openclaw.ai/concepts/architecture)

## The trust boundary

The Gateway owns channel connections, credentials, and authorization. A typical Linux installation listens only on the local machine. It requires a working authentication path before accepting connections on a wider network. Operators, channel senders, and other agents each come through the access rules that apply to them. [Gateway architecture](#gateway-architecture)

### Choose where tools run

A shell command can run on the Gateway host, in a sandbox, or on a paired node. By default, OpenClaw assumes one trusted operator, leaves sandboxing off, and lets exec run on the Gateway host without prompts. Set isolation and approvals deliberately before allowing a broader audience or giving an agent tools with side effects.

When a tool call explicitly requests a sandbox, the request fails if a suitable sandbox is unavailable. A sandboxed run rejects a per-call attempt to escape to the host. On Linux, the default Docker or Podman sandbox runs as a non-root user with a read-only root filesystem and no network access. Other supported sandbox backends can enforce a different boundary. [Sandbox and tool policy](#sandbox-tool-policy-and-elevated-execution)

A host directory mounted into a sandbox becomes visible inside it. The host checks both the requested path and its resolved location. That matters when a directory or one of its parents is a link. OpenClaw keeps its protected credential and system path rules even when it permits a broader set of ordinary mount locations.

### Treat another machine as a separate execution boundary

A paired node that hosts sessions receives a sealed worker artifact. The node verifies its hash when it downloads and reuses it. It does not install packages or run package lifecycle scripts as part of opening that hosted session. The node can impose its own requirement for a separate container per session.

Inspect the effective sandbox for the actual session when testing isolation. Use the security audit to find unexpected settings. Review command approval policy on the machine that would execute the command. [Security audit](https://docs.openclaw.ai/gateway/security/audit-checks) and [exec approvals](#exec-approvals)

[Source page on OpenClaw Docs](https://docs.openclaw.ai/start/why-openclaw/the-trust-boundary)

## Agent runtime

The runtime turns a message into work. It assembles the model's instructions and context, makes allowed tools available, and runs the conversation until it has a reply or needs to wait. OpenClaw has its own embedded runtime. Some model routes can also use an external harness, such as the bundled Codex integration. The model and runtime can affect what happens at each step. [Model providers](#model-providers-for-a-linux-gateway)

### Give the agent a home

Each agent has a workspace, a session store, and its own operating instructions. Set an ordinary workspace for the agent, and use sandbox settings to decide what files a restricted session can see. A non-main session can have a separate sandbox workspace. Active history is stored by agent. Older transcript files can remain as archives or migration inputs.

When a session starts, the runtime includes useful workspace files in its system prompt. The Agents file gives instructions for doing the work. The Soul file sets tone and boundaries. The identity file describes how the agent presents itself. Separate notes can hold stable user preferences or long-term memory. Very large files are shortened in the prompt, so an agent can read them separately if it needs more detail. [Agent workspace](#agent-workspace)

A fresh workspace can get one-time bootstrap instructions. Remove those instructions after initialization. A restart will not recreate completed bootstrap work. If a previously initialized workspace disappears, restore it or use the documented reset procedure. A template-managed or pre-seeded workspace can skip bootstrap creation entirely.

### Give it the right tools and skills

Tool policy determines which actions the model can call. The workspace instructions can explain when to use an action. An instruction about editing files cannot grant a denied editing tool.

A skill gives the model a reusable procedure. An eligible workspace skill takes precedence over a bundled skill with the same name. Grouping files inside folders can help organize a workspace while the skill remains callable by its declared name. [Skills](#skills)

### Steer work already in progress

By default, a new message arriving during a run can steer that run. Work already started continues under its own rules. In a sequence of tool calls, steering can affect calls that have yet to start once an executable call has begun. A parallel batch runs together. After the batch settles, the runtime checks new steering input before the next model call.

Choose a follow-up or collection queue when the new message should wait for a later turn. Choose interruption when the current run should stop. Stopping the run cannot undo a tool action that has already taken effect. [Command queue](https://docs.openclaw.ai/concepts/queue) and [agent loop](#agent-loop)

Streaming controls what the user sees while work is underway. The Control UI can display live agent events. Channel settings determine whether completed pieces of a reply are sent as separate updates. Block streaming is off by default at the agent level, and channels can have their own requirements.

### Resolve a model and a sender

A full model selection names both the provider and model. A shorter name may resolve through an alias, a unique configured match, or the default provider. Choose the provider explicitly when the same model name could refer to several routes.

For a channel, set who can send the agent messages. That access decision is separate from which tools the run can use. [Chat channels and routing](#chat-channels-and-routing)

[Source page on OpenClaw Docs](https://docs.openclaw.ai/concepts/agent)

## Agent workspace

A workspace is the agent's working folder. It gives file tools a starting location and supplies the instructions, notes, and skills particular to that agent. OpenClaw keeps credentials and session data in a separate state area. Backing up the workspace preserves its files. Preserving sessions requires backing up the corresponding agent state as well.

The workspace sets a default location. A tool on the host may still use an absolute path elsewhere if permitted. Use [sandboxing and tool policy](#sandbox-tool-policy-and-elevated-execution) to control what the agent can reach.

### Choose and verify the folder

A normal single-agent installation gets a default workspace during onboarding. For several agents, assign distinct folders and verify each selection in the agent roster. An agent can inherit its workspace from the shared base. Pin the main agent explicitly if it needs to stay at an existing location while the base changes. Named profiles and custom state locations can change the defaults.

Onboarding can create missing bootstrap files. Existing instructions stay in place. If you manage a complete set of files yourself, you can disable one-time bootstrap creation. When switching back to an older workspace, stop the Gateway, set the intended folder, and use Doctor to check old setup state before restarting. [Workspace paths and setup](https://docs.openclaw.ai/concepts/agent-workspace)

A sandbox can give sessions separate working copies. Choose whether the sandbox has no access, read-only access, or read and write access to the host workspace. On the host, workspace-contained file tools can use registered linked worktrees of that repository. The host checks registration and the resolved location on writes. Copying worktree metadata does not grant permission to another repository.

### Give each file one job

Use Files under the agent's settings in the Control UI to review or edit workspace instructions. Put operating procedures and project conventions in the Agents file. Use the Soul file for tone and boundaries, and the Identity file for how the agent is named and presented. The optional user profile holds stable preferences and current context. A short startup checklist can run through the boot hook if you enable it. One-time bootstrap instructions belong to a new workspace and can be removed once setup is done.

Use dated notes for observations and ongoing work. Keep the long-term memory file for durable facts, decisions, and short summaries. Treat long-term private memory as private context when designing groups or shared rooms. Workspace skills are a good home for project-specific procedures. [Memory](#memory) and [creating skills](#creating-skills)

The full file on disk and the copy in the model's prompt have different size limits. If a file is shortened in the prompt, place important guidance first and link or refer to supporting notes for detail. Optional files can be absent. The editor rejects a file that exceeds its save limit before replacing the existing document.

### Share generated notes carefully

The core memory plugin creates new long-term memory and dreaming reports with private permissions by default. You can grant a trusted local group limited read or write access to selected new reports. Existing files keep their permissions. Directory access and the writing process's permission mask still apply. Daily notes and the underlying session corpus stay private under this setting.

### Back up and move the workspace

A private Git repository can track the instructions and memory files you want to recover. Review the files before the first commit, especially if the workspace predates the current installation. Keep credentials, personal exports, and sensitive conversation material out of the repository. An incomplete Git repository or missing worktree metadata may need repair before OpenClaw can use it safely.

To move the workspace, clone or restore it on the destination host and point the intended agent at that folder. Verify the exact workspace in the roster before starting work. Restore the agent's session database separately if you need its conversations. Legacy archives may need separate handling. Confirm which files you need before retiring the old location. [Session state and archives](#session-management)

[Source page on OpenClaw Docs](https://docs.openclaw.ai/concepts/agent-workspace)

## Session management

A session is the conversation an agent carries forward from one turn to the next. It holds history, model preferences, and the context used to pick up work. The Gateway owns that state. The dashboard and channels ask it for the current view.

### Decide which messages belong together

By default, an agent's direct messages share its main session. Groups and rooms get separate sessions. Scheduled runs and webhooks have their own routing rules. Even when two agents use the same session key, each agent keeps its own history and work.

A shared main session fits one trusted person. If several people can message the agent, choose a direct-message scope that separates them. Isolating by channel and sender is a common choice. Include the account too if several logins use the same channel. You can also link the identities of one person across channels when you want their messages to share context. Use the security audit to verify the result. [Direct-message isolation](https://docs.openclaw.ai/concepts/session#dm-isolation)

Groups normally keep one conversation per room. A specific binding can route a room into the main session or another scope when that is intentional. That choice changes which history the agent sees. The room's mention rules and reply destination continue to apply. [Channel routing](#chat-channels-and-routing)

### Name and manage conversations

A new dashboard conversation can get a title from its opening task while the agent starts work. Rename it if you want a stable title. Use the Sessions page to see which agent owns a conversation and inspect its model, history, or recent activity.

The initiating person and the assigned owner can be different. Reassigning a session or automation changes who is responsible without moving the creator's rights over public links, sharing, archive, or restore. Publication still requires its own action. Stopping or archiving one agent's session only affects that agent's work.

The Gateway recognizes a retry of an already accepted input. It can acknowledge that input without appending or answering it again. It rejects a retry that uses the same identity for different content or a different sender. A later edit or deletion in a channel does not rewrite an earlier entry in the stored transcript.

### Understand what incognito protects

Enable Incognito before starting a new thread. The Gateway keeps the session, transcript, and compaction state in memory. It expires the session after twenty-four hours or a Gateway restart, whichever happens first. Time spent chatting does not extend that limit. Expiry stops the work without keeping an archive, and the automatic memory flush is skipped.

The provider still receives model input. An explicit file write or tool action can still leave data behind. The operator can observe live activity, and uploads, approval records, or configured diagnostics have their own storage rules. Codex also writes submitted messages to its diagnostic database even when its session thread is temporary. Use the OpenClaw runtime when you need to avoid that particular Codex record. [Incognito sessions](https://docs.openclaw.ai/concepts/session#incognito-sessions)

### Start fresh or carry context forward

A session normally continues until you decide to reset it. Compaction summarizes older history as the context fills. You can also choose an automatic reset at a particular hour or after real user inactivity. A service event or scheduled job does not extend an idle conversation. If both policies apply, whichever expires first starts the next message in a new session. Set different rules for direct messages, groups, and threads if they need different lifetimes. [Compaction](#compaction)

A trusted personal agent can optionally recall relevant excerpts from its other private conversations. Each session still holds its own transcript. By default, group and channel conversations do not supply or receive that private context. The active memory provider needs to support protected recall. [Memory](#memory)

### Recover interrupted work

During a graceful restart, the Gateway can record which root sessions had active work. On startup it asks each eligible root to inspect what already happened before deciding how to continue. A crash can also leave enough durable run identity for recovery. Child runs do not resume independently. The parent can inspect their state and decide what to delegate again. Scheduled jobs and external harnesses keep their own lifecycle rules.

Recovery checks the current owner, permissions, and tool policy. It skips work if the session was removed or access was revoked. Accepted queued messages keep the original sender's authority and are revalidated before they run. Before repeating an external action, check its actual outcome. A restart can settle the conversation without telling you whether a previous send or write already happened.

### Maintain session history

The Gateway stores active history in each agent's database. Archives and older imports can live separately. If the Gateway reports a legacy store, stop it and back up state before using Doctor to migrate the old history. Restart after the migration completes. [Session storage and migration](https://docs.openclaw.ai/concepts/session#where-state-lives)

Maintenance can archive inactive dashboard conversations and remove disposable records from scheduled or delegated work. A pinned conversation, active run, or session with a durable external reference can be protected from ordinary cleanup. A dashboard session can be archived after seven inactive days while many other durable sessions use a thirty-day window. Check retention before relying on a dormant thread.

Manual archives and archives made to reclaim capacity can have different protections. A capacity archive normally remains searchable and restorable, but disk pressure may make it eligible for deletion. Preview maintenance before enforcing it, and export work you need to keep. [Session maintenance](https://docs.openclaw.ai/concepts/session#session-maintenance)

[Source page on OpenClaw Docs](https://docs.openclaw.ai/concepts/session)

## Memory

OpenClaw's workspace memory is stored in files the agent can read and update. Some files supply a short starting context, while search can pull in more detail when a task calls for it. The active memory plugin controls retrieval and consolidation. The workspace files are still useful without a search plugin.

### Put the information in the right place

Use the user profile for stable preferences and current personal context. When a preference changes, update it in the profile and record any useful history in a dated note. Use the long-term memory file for durable facts and decisions. Put running observations, work logs, and detailed summaries in daily notes. A fresh or reset session can load the notes for today and yesterday, while older detail is normally retrieved when relevant.

Files included at startup have a size budget. If the prompt inspection shows a shortened file, keep the important guidance near the start and move supporting detail to daily notes. The original remains intact on disk. OpenClaw can also exclude files it cannot trust. Doctor can explain when a file's provenance prevented it from being included. [Memory provenance](https://docs.openclaw.ai/concepts/memory-provenance)

Make a note useful for future decisions. For example, record that findings from a trial can inform a proposal and that rollout waits for the owner's review. Include who made the decision and when it expires if those details affect the next action. Use sandboxing and approvals to enforce hard limits. Use a scheduled automation for something that must happen at a particular time. [Exec approvals](#exec-approvals) and [automations](#automations)

### Import earlier notes

Use Import Memory in the Control UI to preview detected Markdown notes and choose the destination agent. A Codex import copies its consolidated notes and keeps the original files in place. Imported material sits in a separate workspace area where search can retrieve it. Review any conflicts before replacing an existing import.

### Retrieve relevant context

Keyword search helps with exact phrases, identifiers, and project names. Semantic search helps when a query and a note express the same idea in different words. Hybrid search uses both. OpenAI embeddings are the default, and a local Ollama embedding model is another option. The embedding model is a separate choice from the chat model. [Memory search](https://docs.openclaw.ai/concepts/memory-search)

The built-in engine uses SQLite by default. A supported PostgreSQL setup can provide keyword and semantic search with the required database extensions. Different engines can rank the same results differently. If you only need keyword search, choose that mode and omit vector support. A rebuild refreshes derived index data while preserving your source notes.

When search returns a result from a transcript, use the session-history tools to retrieve an authorized excerpt. The result points to a conversation entry, so opening it like a workspace file will fail. Session visibility still applies. Automatic recall has a short preparation budget and may skip a slow search. Explicit retrieval remains available when permitted. [Session management](#session-management)

### Save important context before compaction

As a conversation approaches its context limit, OpenClaw can run a quiet memory flush. The flush asks the agent to preserve durable facts before older conversation detail is summarized. With Memory Core, the workspace must be writable. If session or sandbox policy disallows that access, the file flush is skipped. A plugin with its own authorized persistence tool can follow its own path.

A file flush appends new material to the daily note. Replaying the entire note or copying an existing paragraph is rejected. A failed optional flush does not prevent the conversation from compacting. The flush uses the session model and its fallbacks, so choose a local model and local fallbacks if this work must stay on your machine. Inspect the saved note if you need to confirm what was retained. [Compaction](#compaction)

### Review what dreaming promotes

Dreaming is a background process that brings useful observations into long-term memory. It scores recent recall signals and checks their provenance. Qualified material can be merged with what is already known or replace an older fact. Untrusted or system-generated candidates are excluded. The diary records the results so you can inspect what changed.

Historical backfill reads older dated notes and produces review material in the diary. You can stage eligible findings for future consolidation. Staging leaves the long-term file alone until the normal promotion process runs. Backfill can be rolled back independently of ordinary diary entries. Use the memory documentation when migrating an old dreaming store. [Dreaming and backfill](https://docs.openclaw.ai/concepts/dreaming)

If you enable Memory Wiki, it compiles a separate collection of claims and supporting sources you can browse from the Control UI. Look there for contradictions or stale information. The active memory engine still handles recall and promotion. [Memory Wiki](https://docs.openclaw.ai/plugins/memory-wiki)

[Source page on OpenClaw Docs](https://docs.openclaw.ai/concepts/memory)

## Multi-agent routing

A single Gateway can host several agents and several channel accounts. Give each agent its own instructions, workspace, credentials, and sessions. Then use bindings to decide which agent receives a message from a channel, account, or conversation.

A second agent can represent a different job. For example, a personal assistant and a code reviewer can share a Gateway while using different models, tools, and working folders.

### Set up each agent's state

Use the Agents page in the Control UI to create or inspect the roster. Check each agent's workspace, primary model, and fallbacks. Keep state directories separate to avoid mixing authentication or conversations. For a single-agent setup, the main agent can use the default workspace. Pin it explicitly if it needs to stay at an existing location after you add other agents.

An agent can inherit access to a shared authentication profile. If its local credential needs renewal, OpenClaw can use the inheritance owner's matching credential under the documented rules. Connect a separate account from that agent if you want its own identity for model access. Copy credentials only through the supported profile mechanism and treat refresh tokens as belonging to their owner. [Model providers](#model-providers-for-a-linux-gateway)

A per-agent skill allowlist replaces the shared default. Tool policy controls which actions the skills can use. A second agent also needs its own plugin storage settings if you want a plugin's data kept apart. For example, two agents can use separate Memory Wiki vaults. A workspace defines a starting location. Use sandboxing or a separate Gateway when you need a real host or trust boundary.

### Bind accounts and conversations

An account is a login for a channel. An agent is the worker that handles its messages. Connect the account first, then create the binding and verify it with a test message. Keep the credentials and sender allowlist for each account separate. For example, use one Telegram bot for personal work and another for an agent that handles project updates.

More specific bindings take priority. A rule for a particular conversation beats a rule for its account. A rule for an account beats a rule for the whole channel. The full precedence order covers parent conversations, wildcards, and platform roles. At the same level, the first matching binding wins. Every condition in a binding must match. [Binding precedence](https://docs.openclaw.ai/concepts/multi-agent#routing-rules)

By default, a binding that names a channel with no account targets the default account. To cover all accounts, use an explicit channel-wide binding. Once several agents exist, an unbound message needs a configured fallback, such as the system agent. The Gateway does not send it to an arbitrary agent. Some adapters retry temporarily, so check the binding and the account status when a message goes unanswered.

For example, send everything on the personal WhatsApp account to your home agent. Add a narrower rule to send one project group on that same account to the work agent. The specific rule wins and replies still go through the original account. Choose session isolation separately if several people can contact an agent. [Chat channels and routing](#chat-channels-and-routing) and [session management](#session-management)

### Use a team when tasks need distinct roles

A team template can create a coordinator and specialists, each with a separate workspace and role. The coordinator receives the request, assigns bounded work, checks the results, and reports back. A researcher might gather evidence while a reviewer checks the proposed change. Each specialist returns its result to the coordinator.

If you want delegation to be limited to the coordinator, allow it to spawn only the intended specialists. The team preset supplies that structure and leaves ordinary tool policy in effect. The preset's preference for delegation is guidance for the model. Job scheduling and channel ownership remain separate choices. [Sub-agents](#sub-agents) and [standing orders](#standing-orders)

### Set the boundaries you actually need

Separate agents have separate state. By default they can still have cross-agent session access. Narrow which agents can reach each other and which conversations they can inspect. The visibility rules for a parent's delegated child also matter. Use separate Gateways for a stronger separation between operators or workloads.

The built-in memory engine does not search another agent's transcript corpus by default. Share a reference folder deliberately if both agents should retrieve the same material. Prefer distinct vaults when they need separate compiled knowledge. Treat transcript access as access to potentially sensitive text even when the returned excerpt omits internal tool details.

When migrating an older installation, Doctor can turn implicit owners into explicit bindings. Check each account after migration. An account with unresolved ownership can stay blocked while the rest of the Gateway runs. If workspaces diverged, reconcile the instructions and memory deliberately. [Chat channels and routing](#chat-channels-and-routing)

[Source page on OpenClaw Docs](https://docs.openclaw.ai/concepts/multi-agent)

## Sub-agents

A sub-agent is a background run started by another agent. It has its own session and context, and normally reports its result to the parent. This allows research, reviews, coding, or slow work to proceed independently. Each child has its own token cost, and may use a cheaper model. Depth and child limits bound delegation.

### Follow the work

In the Control UI, open Subagents from the parent conversation to see running and completed children. Select one to read its transcript beside the parent. The transcript is view-only, and the task title identifies the work. A directly opened child also offers Open parent session. Stop is available when the run can be stopped and session access permits it.

An ordinary hidden helper reports through its parent. A visible persistent session is interactive and remains in the session tree. The user can return to it and steer it. Visible sessions can use conversation and session tools that hidden helpers do not normally receive. Configured tool policy, sandbox, sender and channel restrictions, and delegation limits still apply. Use a visible session when the user needs a separate conversation, rather than simply because a task is long.

### Give a clear assignment

Give a child a concrete deliverable and the constraints it needs. An isolated child starts with a fresh assignment. A same-agent fork carries the current user turn and completed tool results. Thread-bound children normally fork by default.

The parent model normally carries into a same-agent child unless a default or explicit choice changes it. A child assigned to another agent normally uses that agent's model and authentication order. It does not inherit the requester's personal account selection. A child can inherit a sandbox or require one. Set a timeout when the work needs a deadline.

The parent can inspect active work and yield while waiting. It should review the result before responding. In a nested delegation, each result goes to its immediate parent, which passes the useful outcome upward. Eligible hidden runs can return privately to the parent without automatic delivery to the channel.

The [tool reference](https://docs.openclaw.ai/tools/subagents/tool-reference), [nesting rules](https://docs.openclaw.ai/tools/subagents/nesting), and [completion guide](https://docs.openclaw.ai/tools/subagents/announce) cover exact options.

[Source page on OpenClaw Docs](https://docs.openclaw.ai/tools/subagents)

## Sandbox, tool policy, and elevated execution

Sandbox settings determine where tools run. Tool policy determines which tools are available. Elevated execution affects shell execution and can take it outside an ordinary sandbox, subject to its own gates and approvals. A creator-required sandbox cannot be bypassed this way.

Use the sandbox inspector to see the effective settings for a session or agent. It reports sandbox scope and workspace access, tool rules and their sources, and elevated access gates. The [source guide](https://docs.openclaw.ai/gateway/sandbox-vs-tool-policy-vs-elevated) has the exact inspection command.

### Where tools run

Sandbox mode can leave sessions on the host, sandbox non-main sessions, or sandbox every session. Group and channel sessions count as non-main. Workspace access can be absent, read-only, or read-write. A creator role that requires a sandbox overrides the agent's mode. If that sandbox cannot start, execution is blocked.

Bind mounts expose selected host files to the sandbox. Choose read-only access for sources and secrets where possible. A mount defaults to read-write if its mode is omitted. Shared sandbox scope uses global binds rather than per-agent binds. OpenClaw checks resolved paths to prevent symlink escapes. Giving a container access to the Docker socket effectively gives it control of the host. Workspace access and bind permissions are separate decisions.

### Which tools can run

Global and agent profiles, provider-specific profiles, allow and deny rules, and sandbox policy all contribute to the effective tool set. A denial wins. A nonempty allowlist excludes tools it does not name. Policy can target a provider or a particular model.

A shell command cannot override a denied execution tool. Tool policy filters tool calls, however, and does not inspect every side effect of a shell command. An agent with shell access can still modify files even if direct editing tools are denied. Enforce read-only access with a sandbox or host boundary and restrict runtime tools as well as file mutation tools.

Tool groups make policy easier to manage. They cover families such as runtime, files, sessions, memory, web, messaging, and plugins. The OpenClaw group excludes low-level filesystem and runtime tools and provider plugins. The plugins group includes loaded plugin tools, including MCP tools. Gateway tool-policy logs show which rule removed or blocked a tool.

Sandboxed MCP tools must also pass the sandbox tool allow gate. Allow the MCP bundle, the plugins group, or the relevant server tools there, then reload and check the tool list. Doctor checks managed MCP server names, although it does not enumerate every bundled plugin source.

### Elevated execution and diagnosis

Elevated execution affects the execution tool only. It grants no additional tools and cannot override tool policy. Ordinary elevated execution remains subject to approvals. Full elevated mode skips execution approvals for that session. When execution already runs directly, elevation usually changes nothing. It does not freely select another host, and it preserves a node target only when that node is already the target. Global and agent settings and sender allowlists control access.

When a tool is blocked, inspect the effective policy and audit record. Adjust the relevant deny or allow rule if the access is appropriate. Disabling an ordinary sandbox is another consequential option, but cannot override a creator-required sandbox. See [session permission modes](#session-permission-modes) and [exec approvals](#exec-approvals) for related controls.

## Skills

Skills are instructions that teach an agent when and how to use tools. A skill lives in a directory with a Markdown instruction file and metadata. Discovery, eligibility, and visibility are separate. A discovered skill may lack a prerequisite or be hidden from an agent. Use the skills check in the OpenClaw command line to diagnose it. Read third-party skills before enabling them.

### Where skills come from

For skills with the same name, OpenClaw checks the agent workspace first, including its regular skills directory and then its dot-agents skills directory. With the default state directory, the user's dot-agents directory follows. Managed skills, the agent's Workshop skills, and bundled skills come next. Extra directories and plugin skills have the lowest precedence. The Custodian library receives bundled precedence for the configured Custodian agent. Personal library skills use identity and revision selection instead.

Each agent has its own workspace. Managed state skills are shared among agents using that state, while Workshop skills belong to one agent. A nondefault state directory excludes home-scoped personal and compatibility roots. Codex's native skills directory is not an OpenClaw root. OpenClaw offers a migration plan and copy operation for moving Codex skills into a workspace.

Discovery searches grouped directories up to six levels deep and stops at a skill instruction file. Its declared name determines its identity and command, with the directory name as a fallback. Invalid files are skipped and reported. Collisions are reported when content differs, including overrides of bundled skills.

When a run uses a different workspace, that workspace's skills follow the agent catalog in precedence. Its regular skills directory wins over its dot-agents directory. Both synchronize to sandboxes. Managed worktrees retain their recorded source workspace for discovery. Selecting the worktree as the agent workspace changes that precedence. Discovery does not walk upward to a parent repository. Sandboxed copies are reconciled as source files change or disappear.

A connected headless node can publish its skills while connected. A collision keeps the local name and gives the node skill a stable prefixed name. Its files and binaries remain on the node, so execution must target that node. Restart its host after changing skill files.

### Visibility and invocation

An agent's skill allowlist is independent of source precedence. An omitted default allows unrestricted visibility. An omitted agent setting inherits the default. An explicitly empty selection exposes none, while a per-agent selection replaces the default.

This selection affects prompts, command discovery, sandbox synchronization, and snapshots. It does not prevent shell access to files or programs. Use sandboxing, operating-system isolation, command policies, and resource credentials for that boundary.

In the Control UI composer, open the skill picker with the dollar sign and select a skill. A message can reference up to eight distinct eligible user-invocable skills. The agent is told to read each one. Hidden or excess references produce an error.

In a chat channel, slash commands can dispatch directly to a tool when configured, or expand into instructions for an agent turn. A skill can be excluded from automatic model invocation while remaining available for explicit selection. Plugin-provided skills load only while the plugin is enabled and still have their own eligibility requirements. Eligibility does not grant tool access.

### The shared Gateway library

A signed-in Gateway profile can create, import, or install personal skills in Plugins, then Skills. A shared token does not identify a person. New managed skills belong to their creator. Share with team makes a skill available without edit rights. Transfer to team changes management ownership while preserving the author. Stable identities survive both actions. A shared Gateway remains one trust domain, and skills are session input rather than secret storage.

Saving creates an immutable revision of instructions and supporting files. Content, paths, sizes, and executable flags affect the revision. Identical saves do nothing, and stale edits conflict. Sessions pin selected revisions across restarts and ownership changes. New sessions get published changes. Attach or refresh a skill to use a new revision in an existing session. Rollback selects a retained revision. Removing a skill prevents new selection but preserves pinned revisions. Disabling it removes it from new-session defaults while allowing explicit attachment.

A new session can select up to 64 enabled library skills, with personal skills first. Normal allowlists and prerequisites still apply. Bundle and delivery limits may omit supporting files, with a notice. Instructions are delivered whole when they fit, otherwise an explicit unavailability notice replaces them. Use the library editor or authorized tools to manage revisions rather than editing the Gateway's internal storage.

### Install and maintain

OpenClaw can install skills from ClawHub, Git repositories, local directories, and other supported sources. The workspace is the normal destination, with a shared managed destination available. Tracked ClawHub installs can be updated. Git and local sources must be reinstalled to refresh them. Verify a skill's trust information and review its scan details before relying on it. Owner-qualified names avoid ambiguity.

Private archive uploads are disabled unless an administrator enables them. A trusted local install policy can inspect staged content before installations and updates. An invalid or missing decision blocks installation. Workspace and extra roots enforce resolved-path containment unless an administrator explicitly trusts a symlink target. Workshop links cannot escape their directory. Managed and personal skills may use linked folders, but their instruction files must resolve inside the skill directory.

### Requirements and configuration

Skills declare a name and description and can specify required executables, environment variables, configuration, or operating systems. These checks govern eligibility. A skill can also identify a primary credential and offer installation guidance. Skill settings can enable or disable it and supply a credential through supported secret mechanisms. Host environment injection does not automatically reach a sandbox.

Keep instructions concise and specific. See [Creating skills](#creating-skills) for the authoring workflow and the [official skills guide](https://docs.openclaw.ai/tools/skills) for exact metadata and command syntax.

## Creating skills

A skill teaches an agent when and how to use tools. Create a directory in the workspace skills area and give it a Markdown instruction file with metadata and a body. The name and short description help both the agent and command discovery. Use a lowercase name with digits or hyphens as needed, and keep the directory and declared names aligned. Grouping directories do not change the skill's command name.

Write instructions for a specific task, including when to use the skill, what to inspect, and how to handle failures. Keep them concise. Refer to bundled resources through the skill's base directory rather than a machine-specific absolute path. If a skill runs shell commands, design it so untrusted input cannot become a command.

### Test and control availability

Check the skills list to confirm discovery, then ask the agent to perform the task. File watching normally picks up changes. If watching is disabled or an existing session does not see the change, start a new chat or restart the Gateway.

Metadata can make a skill user-invocable, exclude it from automatic model invocation, or dispatch its command directly to a named tool. Requirements can check executables, environment variables, configuration, and the operating system. A skill can name a primary credential. Configure credentials through supported secret mechanisms. Credentials injected into the host turn are not automatically available inside a sandbox.

### Personal skills and publishing

On a shared Gateway, open Plugins, then Skills, then My skills to create or import a skill for your signed-in profile. Review its saved revision and activation. An authorized agent can also create or improve a personal skill through the library service. Request the new revision in an existing session, or share it with the team when needed.

Skill Workshop stores learned skills with version history. You can inspect changes, archive a skill with a reason, and restore it later.

Before publishing, complete the name, description, requirements, and any homepage. Test locally and check ClawHub for an existing solution. Sign in to the ClawHub command line and publish under a personal or organization owner with the appropriate publishing rights. The [publishing guide](https://docs.openclaw.ai/clawhub/publishing) explains versions, ownership, and exact commands.

[Source page on OpenClaw Docs](https://docs.openclaw.ai/tools/creating-skills)

## Connect MCP servers

Model Context Protocol servers expose tools, resources, and prompts to OpenClaw. A connection does not itself grant permission to use their tools. Normal tool profiles and session policy still apply. This chapter covers third-party servers connected to OpenClaw. OpenClaw can also serve its own channel conversations to another MCP client.

Server initialization instructions reach directly available tools in the system prompt. Deferred tools expose them through discovery. When discovery indicates more instructions are available, read the tool description before use. OpenClaw limits embedded instructions from each server and marks truncation.

### Add and verify a server

In the Control UI, open Settings, then MCP, and choose Add server under Configured servers. Give it a unique name and choose Streamable HTTP, SSE, or standard input and output. Enter the server address, or its executable and arguments. The scoped editor also supports credentials, authentication, timeouts, parallel-call hints, and tool filters. Save the definition.

An administrator can also choose Plus, Plugins, and Add MCP server in the composer. This session enables it for the current session. Everywhere enables it globally. Both save a global definition, and session policy remains separate. Plus, Plugins, Tool access lets you inspect or deny individual tools for the session. Denials take effect before the next turn.

A saved definition does not prove that the server is reachable. Run the MCP diagnostic with a live probe, and inspect its capabilities. For HTTP OAuth, sign in when prompted, approve in the browser, and send another message afterward. The [MCP guide](https://docs.openclaw.ai/tools/mcp) gives exact diagnostic and login commands.

Choose one transport per server. An HTTP server needs an address and HTTP settings. A local standard-input server needs an executable, its arguments, and an appropriate working directory. New or edited definitions containing both are rejected. Existing mixed definitions retain their old behavior with a warning until repaired. Disable a definition to retain it without connecting. Store sensitive headers and environment values using supported secret mechanisms.

MCP Apps are optional sandboxed interactive views and plugin extensions. Connecting a server does not automatically enable its interface or bypass permissions.

### Changes and recovery

With Gateway hot reload, changed or removed servers retire immediately. New definitions appear in discovery on the next turn. Unchanged servers keep their connections and cached tools. If a server exits, its last successful catalog can remain visible while recovery runs, but it does not grant execution. A successful listing replaces that catalog. Configuration changes and plugin reloads retire the affected runtime.

Failed startup retries back off from 30 seconds up to ten minutes. Recovery runs in the background after the initial failure, and recovered tools appear at the next turn boundary. A successful connection, configuration publication, or explicit reload clears the backoff. Reload the process that owns the connection. Reloading a separate command-line process does not reset the Gateway.

OAuth authorization failures wait for the affected credential or server configuration to change, or for an explicit reload. Another user's credential change does not clear the failure. Status and Doctor provide guidance. Legacy SSE can preserve a session when its endpoint is unchanged. A new endpoint needs fresh initialization. HTTP cleanup can finish locally even if the server does not confirm deletion, leaving the remote session to expire. Failed local cleanup blocks replacement.

### Approvals and scopes

Codex MCP approvals follow the session permission posture. Full permission normally does not prompt. Stricter modes check tools without safety annotations and may use automatic review or ask the user. Where offered, Allow Always grants an agent access to the exact server and tool regardless of arguments. It applies only when a Gateway-hosted Codex run can unambiguously match the call. Ambiguous calls retain their native or session behavior. Codex apps, native plugin servers, and computer-use servers are excluded.

A server can override the posture with an approval mode. Automatic mode can use stored grants, while prompt mode continues to ask. Grants survive restarts and take effect with the next thread configuration and hook registration. The current session uses Codex's remembered choice. Consult the [MCP guide](https://docs.openclaw.ai/tools/mcp) for inspection and revocation.

### Diagnose and sign in

If expected tools are missing, probe the server and inspect its include and exclude filters. For a local server, verify that the executable resolves in the Gateway environment and its working directory and arguments are correct. Server standard error is drained but omitted from normal logs because it may contain private content. Startup errors still provide diagnostics.

An HTTP authentication refusal calls for checking credentials or signing in again. In Settings, an administrator can select Sign in for an enabled HTTP server with shared native OAuth credentials. Authentication saved confirms storage on the selected Gateway. Probe afterward to confirm reachability. Changing Gateway or agent closes the dialog, and a restart ends an unfinished sign-in.

Browser sign-in needs Settings on the Gateway's own secure address, local loopback, or published Tailscale address so the callback can return. A separately hosted interface cannot receive it. Other identity mappings have their own sign-in paths. The command-line login on the installation owning the server is an alternative. If a redirect cannot reach the Gateway, the complete failed redirect can be supplied through the original direct chat or the login flow. Preserve its state and issuer information. See the [official guide](https://docs.openclaw.ai/tools/mcp) for the exact procedure.

Sign out of a plugin-declared server from its Accounts page. Uninstalling that plugin removes its saved sign-ins. A separately configured server retains its own credentials. Successful structured results are validated against the server's output schema. Error results carry their error content to the agent for recovery.

## Automation

OpenClaw offers several ways to start background work. Choose one based on what starts the work and which runtime owns it.

Automations provide one-time reminders, recurring reports, scheduled monitoring, and authenticated inbound webhook triggers. Each job has its own schedule, context, delivery policy, and history. Quiet hours and idle-only settings can keep work out of the way. A job can keep a small scratch checklist and stay silent when nothing needs attention. Results can go to a chat channel or a webhook.

The IMAP plugin can start isolated reader sessions for permitted senders. External services can use authenticated Gateway webhooks. Sub-agents handle delegated agent runs, while ACP runs coding-harness sessions. Lobster runs local pipelines with resumable approvals. Internal hooks respond to lifecycle events, and typed plugin hooks can intercept operations in process. The former shared Tasks ledger and TaskFlow orchestration services have been removed.

Standing orders are persistent workspace instructions supplied to sessions. Combine them with an automation when a standing policy needs a scheduled check. Existing heartbeat monitors migrate through Doctor into editable jobs. Setup creates an ambient owner check, and later reloads and restarts preserve edits and deletions.

### Create and verify a job

Open Automations in the Control UI. Choose a time or delay for a one-time reminder, or an interval or schedule for recurring work. An isolated run suits a bounded report with its own model choice. A main, current, or custom session can retain continuity with a particular conversation. The session choice affects the context available to the job and what later work can see.

Write a self-contained task. Say what to inspect, what makes a result worth delivering, and where it should go. For example, a weekday project inbox check could report to a configured channel only when something needs attention. Verify the recipient and thread. Choose silent delivery when results only need to appear in run history.

Check the next wake in Automations. After the job runs, open Run history for its status, duration, and result. If it ran but no message appeared, inspect delivery status and the channel destination.

See [scheduled automations](#automations), [session and payload choices](https://docs.openclaw.ai/automation/cron-jobs/payloads), and [delivery and failure notifications](https://docs.openclaw.ai/automation/cron-jobs/delivery) for exact settings.

[Source page on OpenClaw Docs](https://docs.openclaw.ai/automation)

## Building plugins

A plugin adds capabilities without changing OpenClaw's core. A tool gives the agent an operation to call. A channel plugin connects a messaging service. A provider changes how OpenClaw reaches a model. A feature plugin can add operations and Control UI pages. These shapes share package and manifest conventions, while their registration details differ.

Plugin APIs are experimental. Pin the host version during development and test the versions you claim to support. The documented baseline uses a recent supported Node.js release, TypeScript, and ES modules. An external plugin can live in its own repository and be published through ClawHub. Bundled plugins use the OpenClaw source checkout and its workspace tooling.

### Build a small tool first

Start with a simple tool that returns a string. It exercises discovery, registration, input, and output without depending on an external service. Give the package a name, version, and module type. Declare runtime dependencies and the OpenClaw peer dependency. Record compatible API and Gateway versions and the SDK version used to build it. A local development entry can use TypeScript. Publish built JavaScript and include its runtime dependencies.

Give the plugin a stable identity, description, category, and configuration schema in its manifest. The schema is required even when there are no settings. Declare the tool's exact name in the manifest so the host can identify its owner before loading runtime code. Register the same name in the entry point with a description, input schema, and implementation. A stable structured result can also have an output schema. Channel plugins use their own entry convention. The [entry point reference](https://docs.openclaw.ai/plugins/sdk-entrypoints) supplies exact syntax.

Host-authority surfaces need matching manifest declarations. This includes tool-result middleware targets and trusted tool policies. Keep those declarations aligned with runtime registration.

### Set boundaries

An enabled plugin's required tools remain subject to effective tool policy. Mark a tool optional when its side effects, unusual binaries, or capabilities warrant explicit operator consent. Keep its runtime and manifest metadata aligned. An operator can allow a tool or its plugin, while explicit denies still apply. [Plugin permission requests](https://docs.openclaw.ai/plugins/plugin-permission-requests) can ask for approval after selection and before an action.

Declare when a tool needs the workspace. A factory that reads working files needs the workspace before it is built. A tool that only needs files during execution can allow preparation to proceed later. A workspace-independent tool can declare that it does not need access. Associate usage guidance with the tools it describes so OpenClaw supplies it when those tools are callable.

A factory may receive the current route and conversation identity. During an eligible channel turn it may use the host's delivery capability. The host controls the destination, account, thread, and policy, and the capability expires with the turn.

Version two factories can receive sandbox and model capabilities. These use the prepared environment and effective model policy. Their authority is limited to what the host grants, and they expire with the run or plugin. Model output is subject to the initiating model's budget. Full-value catalog calls use Code Mode admission.

### Test the installed package

Inspect the live plugin runtime and exercise its registered commands. Test valid and invalid inputs, structured details, model-visible text, and disabled or denied access. If a tool is optional, test with and without explicit permission. A fixture tests implementation behavior. A Gateway-backed smoke test also confirms that the host accepts the registration.

Build and pack the plugin, install the package in a separate test environment, and inspect it again. This checks the entry and dependency path users will receive. Development-only dependencies are not installed as runtime dependencies. If official catalog trust matters, test a catalog-backed install too. See [plugin testing](#plugin-testing) for fixture and runtime patterns.

### Publish and maintain

Use focused SDK imports for the surfaces the plugin needs. Use a plugin-specific prefix for custom Gateway methods. A handler forwarding authenticated requests must declare the corresponding bridge surface. The host preserves the client and cancellation signal, checks the target scope, and rechecks authority before a mutation.

Review reload behavior and deprecated SDK use before shipping. Test supported beta versions early. Publish through the ClawHub command line, review a dry run, then install the published package on the Linux Gateway and inspect its runtime. The [SDK overview](#plugin-sdk-overview), [runtime helpers](https://docs.openclaw.ai/plugins/sdk-runtime), and [publishing guide](https://docs.openclaw.ai/clawhub/publishing) provide details.

[Source page on OpenClaw Docs](https://docs.openclaw.ai/plugins/building-plugins)

## Plugin manifest

A native plugin has a manifest at its root. OpenClaw reads it before loading plugin code, so it can discover capabilities and validate settings safely at startup. A missing or invalid manifest or schema produces a plugin error and can block configuration validation. Other compatible bundle formats have their own discovery rules.

The manifest describes the plugin's identity and surfaces the host needs in advance. Package metadata describes its runtime entry, distribution, and compatibility. Runtime code registers behavior. The [manifest reference](https://docs.openclaw.ai/plugins/manifest) gives the exact fields and syntax.

### Identity and configuration

Every native manifest needs an identity and configuration schema. Use a stable identity and provide a name, description, and version for people inspecting it. A package with multiple entries gives each entry a distinct identity. Previous identities can be declared so references normalize to the current one.

Even a plugin without settings needs a schema. For settings, describe their types and add useful Control UI labels. Mark credentials sensitive. Add a property to the schema before adding it to the plugin's settings. The host validates reads and writes against this schema and reports missing required values after applying defaults.

### Declare capabilities

Declare exact tool names, including optional tools, in the manifest's capability contracts. Add availability metadata for discovery and profile eligibility. The runtime still supplies the implementation. Declare plugin skill directories relative to the plugin root. An enabled plugin can also expose per-agent learned skills. Those sit between bundled and managed skills in precedence. Missing declared plugin dependencies produce a warning, though the plugin can still load.

A memory or context-engine plugin declares its exclusive kind so the operator can select its owner. A context engine can declare its identities in advance. One declared engine can be selected automatically at installation. Multiple engines require a choice. Keep activation metadata inexpensive so the host can plan loading around startup, a provider, a channel, a command, or another capability. Operator configuration still controls enablement.

### Provider, channel, and interface metadata

A channel plugin declares its channel identities and configuration so the host can validate them before loading. Account selection metadata describes how stored accounts are chosen.

A provider can declare identities, setup choices, aliases, credential environment names, and model catalog information. A lightweight catalog can describe model aliases and compatibility before activation. Inference authentication and usage lookup credentials have separate purposes. Plugin trust and activation policy still govern use of setup metadata. A provider can manage capacity cooldown behavior, while authentication and subscription restrictions continue to apply.

The manifest can describe commands, Control UI contributions, dashboard widgets, quality checks, backup resources, and static MCP servers. Dashboard bindings must match methods from the same plugin and the required read or write scope. Operators can override or disable a plugin's MCP server. Backup declarations can cover retained databases even when their plugin is disabled.

Choose a catalog category that reflects the plugin's main purpose. Up to three starter prompts can help users begin. The Control UI places a selected prompt in an editable draft after the relevant installation or enablement flow. The user still sends it.

### Replacement and retained state

Plugin replacement is normally serialized. A plugin with no per-turn state needed by a later call can permit a running turn to hand over to the new version at its next model step. A separate overlap option allows old and new generations to run concurrently only when both versions opt in and their surfaces qualify. Overlap takes precedence when both options are declared. Exclusive surfaces such as channels still replace serially.

Use overlap only when startup, runtime state, and cleanup have independent ownership. A successor must not take a port, subscription, or singleton still needed by the old version. Coordinate shared writes and ensure a failed replacement leaves the predecessor usable. Each instance must stop its own timers and watchers. Authorization and approvals remain in force for both generations.

A source plugin can provide a retained-state inspection for upgrades. The staged Gateway can check matching official or bundled owners before replacement. A failed inspection can stop the upgrade while preserving the running Gateway and original files.

### Validation and repair

Unknown active channel settings usually fail validation. Stale references to unavailable plugins can produce warnings instead. Disabled plugin configuration is retained and reported, allowing intentional uninstall markers. An unknown memory slot owner is normally an error. If a manifest or schema is broken, use Doctor and repair the package.

For field details see [host surfaces](https://docs.openclaw.ai/plugins/manifest/surfaces), [configuration and secrets](https://docs.openclaw.ai/plugins/manifest/config-and-secrets), and [package metadata](https://docs.openclaw.ai/plugins/manifest/package-json).

[Source page on OpenClaw Docs](https://docs.openclaw.ai/plugins/manifest)

## Tool plugins

A tool plugin gives the agent an operation it can call. The tool has a stable name, a description, an input schema, and an implementation. Choose a specific, unique name so it does not collide with another tool. The [official tool plugin guide](https://docs.openclaw.ai/plugins/tool-plugins) contains exact SDK syntax and examples.

A simple declarative plugin can define its configuration and a static set of tools. The SDK infers types from their schemas. A quote tool, for example, might accept a symbol and use an optional service credential. Its structured result could include the symbol and whether a credential is configured. Never return the credential itself. Use cancellation support for work that can be interrupted.

### Workspace and validation

Declare whether the tool needs working files. A factory that reads the workspace during creation needs it prepared before the factory runs. A tool that needs files only when called can wait until execution. A workspace-independent tool can say so. These declarations help the host respond promptly while a checkout is prepared.

Keep input schemas shallow. OpenClaw limits nesting, including expanded local references, to 128 levels. Deeper portions become permissive and no longer validate those constraints. This limit also applies to MCP tools.

Define open dictionaries explicitly. On native OpenAI Responses routes, compatibility normalization can close an object with no declared properties, causing it to reject keys. Use the SDK's open dictionary support when arbitrary keys are intended. For a fixed object, declare its properties and whether extra ones are accepted. Registration diagnostics warn about affected nested objects. Factory schemas are checked when factories produce tools, so use runtime health or Doctor for those checks. Warnings do not reject registration or change normalization.

Validate application-specific constraints before execution. Use the SDK's typed argument validation error for invalid input so the runtime can report and account for it correctly. Other preparation and execution errors retain their usual classifications.

### Optional tools and factories

Mark a tool optional when an operator must explicitly allow it before the model sees it. Keep its generated manifest metadata aligned. A factory is useful when creation depends on runtime context, such as sandbox state. It can provide one tool, several tools, or none. Factory tools use a different execution signature from declarative tools. Consult the [tool plugin guide](https://docs.openclaw.ai/plugins/tool-plugins) when implementing one.

An eligible factory can use turn-bound delivery to send to the active conversation. The host chooses the destination, account, thread, and policy. The capability expires after the turn and is unavailable when another transport owns delivery.

The host may provide a resolved memory audience for an admitted session turn. Use that prepared audience rather than inferring authority from sender identity or session naming. After awaited work, check both invocation and audience currency immediately before releasing data or performing an effect. Version two context provides the live checks needed for this pattern.

Other context can report facts such as local browser capability, selected approval devices, run identity, input provenance, and the source of a background fork. These facts are not independent authority. The host's policy, invocation guard, and live ownership checks still apply. Approval reviewers need their own approval permission. Model arguments must not choose reviewer devices.

A factory can normalize arguments before schema validation and can request sequential execution for calls that must not overlap. Runtime metadata and execution use the same current factory instance. Retained tools stop working when their plugin registry is retired. A wait tool can remain synchronous on supported OpenAI asynchronous requests. Other providers and catalog calls keep their existing behavior.

### Owner-authorized continuations

A version two factory can participate when the exact parent resumes after an explicit yield. It can restrict creation to an owner and receives an invocation guard. Carry the guard through awaited work and call it at the final write or request boundary. It checks the admitted invocation and plugin lifetime. A continuation also checks the original owner's live parent binding. A catalog entry alone grants no invocation authority.

Shared event callbacks can run under another call's asynchronous context. Capture the calling context when needed and run the guard within it. A tool accepting client-supplied bytes may also receive a host-bound input admission check. Carry it to the storage owner's final admission boundary. It checks current upload policy and does not replace invocation or mutation authority.

Legacy registrations remain supported with their existing direct-turn context. They do not gain continued owner identity. A version two factory does not grant authority to unrelated sessions, management-only callers, or detached scheduled runs. A tool may hide transient channel progress while preserving lifecycle events and final results.

### Results and output contracts

Declarative tools can return text or a structured value. The SDK wraps it for the model and retains structured details. Use a factory when a custom tool result is needed.

Add an output schema when structured output is stable. It describes the original structured details. OpenClaw validates the final details after hooks. An invalid schema prevents execution, and a result that violates its schema fails the completed call. Include all normal result variants, including structured errors, or omit an unstable schema. Descriptions may be visible to the model, so keep secrets out. Code Mode and Tool Search can use complete closed schemas as compact hints.

Some common result fields have reserved outcome meanings. A failure status can mark a call as failed even when execution returned normally. Put domain data under a separate object when its fields might be mistaken for execution status. For a tool-owned timeout, report the timeout and duration. For useful partial results, mark them partial and include the results. Neither turns an incomplete operation into success.

### Direct replies

A tool can opt in to deliver a finished report, confirmation, or receipt directly. The capability belongs to the tool definition. The result must contain a complete user-ready reply. OpenClaw waits for the whole model step and continues model processing if another call fails or needs further work. Hooks can rewrite or withdraw the reply before delivery. A call inside a Code Mode program returns to that program rather than delivering directly. Use this feature for complete answers, not intermediate search results.

### Build, inspect, and publish

Configuration schemas are optional for declarative tool plugins. When omitted, the host uses a strict empty schema. Store secrets through configuration or supported secret mechanisms rather than in source. The Gateway reads generated manifest metadata before importing runtime code. Regenerate it after changing identity, configuration, activation, or tool names, and keep package metadata aligned with the built entry and dependencies.

Build the plugin, check generated metadata, validate the entry and manifest, and run its tests in continuous integration. A type-aware lint rule can detect deprecated SDK calls. Install the built package in a separate environment and inspect its runtime. Ask the agent to use the tool in the Control UI or a chat channel. If it is missing, check effective tool policy, activation, declared ownership, package entry, and runtime diagnostics before changing code. Reload after source or manifest changes.

Review a ClawHub publishing dry run before publishing. The [plugin CLI](https://docs.openclaw.ai/cli/plugins), [SDK entry points](https://docs.openclaw.ai/plugins/sdk-entrypoints), and [ClawHub publishing guide](https://docs.openclaw.ai/clawhub/publishing) provide exact commands. See also [Building plugins](#building-plugins), the [manifest](#plugin-manifest), and [plugin testing](#plugin-testing).

[Source page on OpenClaw Docs](https://docs.openclaw.ai/plugins/tool-plugins)

## Plugin hooks

Hooks let a native plugin observe or influence an agent run, a tool call, channel delivery, or the Gateway lifecycle. Each hook has its own event, context, and result. Some context is optional, so a plugin should check it before limiting an action to a particular agent or session.

### Choose the right boundary

A prompt hook can add context or narrow the available tools. A run admission hook can block input on a runtime that supports it. A model request hook can change or withhold the final request. Runtime coverage differs, so check the selected runtime before relying on a hook for enforcement.

Tool call hooks can change inputs, block a call, or request approval. Other hooks can change a reply, cancel delivery, record timing, or perform cleanup. When several plugins handle an event, their priority and merge rules determine the result. Consult the catalog for each hook's contract.

Typed plugin hooks, internal automation hooks, and Gateway webhooks are separate systems. Internal hooks respond to events such as a new session or agent bootstrap. Webhooks receive requests from external services. Register each kind through its own interface.

### Try a small hook first

A reply hook is an easy way to test registration and conversation access. Have it look for a distinctive test phrase and return a short confirmation. Send the phrase from the Control UI or a channel. You should get the confirmation without a model call. A normal message should still reach the agent. Match a distinctive phrase because the prepared input can include channel context as well as the sender's words.

### Permissions and privacy

Plugin loading rules still apply to hooks. A third-party plugin needs conversation access for hooks that read or prepare conversations. An operator can approve its declared capability or grant access to that plugin. Bundled plugins receive conversation access unless it is disabled. Session-end metadata can be available without it, but reading the transcript requires access.

Prompt modification has its own switch. The final model request hook also needs an additional explicit permission, including for bundled plugins. A missing grant prevents that hook from registering. These gates control specific hooks. Native plugin code itself runs with the Gateway process's authority, so review its source before installation.

Incognito sessions withhold model input and output observations. End-of-run settlement still receives identifiers, success, and duration, while conversation content and detailed run information are withheld. Policy, provider, approval, and explicitly invoked tool hooks still run.

### Channel input and troubleshooting

A supported channel can let a plugin transform incoming data before storage. Discord does this before its durable admission queue. Other channels must opt in. A plugin that depends on filtering should check host and channel support rather than assume coverage.

The channel checks provider identity and routing lane again after transformation. Errors, timeouts, cancellation, or retired plugin authority refuse intake. Previously queued messages are unchanged. Higher-priority handlers run first, and each sees the latest replacement. Validate incoming data and pass the cancellation signal to outside work. A host timeout can end the wait while the plugin is still working.

If a hook does not run, inspect the plugin's runtime details and diagnostics. Check that the plugin is enabled, the correct registration interface and permissions are in place, and changed code has been reloaded. Also check runtime coverage, trigger conditions, optional context, and competing handlers.

The [hook catalog](https://docs.openclaw.ai/plugins/hooks/reference), [tool policy hooks](https://docs.openclaw.ai/plugins/hooks/tool-policy), [prompt and session hooks](https://docs.openclaw.ai/plugins/hooks/prompt-and-session), and [message hooks](https://docs.openclaw.ai/plugins/hooks/messages) provide exact contracts and examples.

[OpenClaw plugin hooks](https://docs.openclaw.ai/plugins/hooks)

## Operating the Gateway

The Gateway is the long-running service that owns channel connections, routes messages, and provides the Control UI. Most installations need one Gateway for all their agents and channels. The Control UI and channel integrations share that service, so check the Gateway before treating several simultaneous connection failures as separate problems.

### Start and check the service

On a Linux host, install the Gateway as a user service and check its status after starting it. A healthy status shows a running service and a successful connectivity check. Use the channel probe for live account checks, and consult logs when a connection or delivery fails. The [Gateway runbook](https://docs.openclaw.ai/gateway) gives the exact commands.

The Gateway normally listens only on the local machine. Container defaults can expose the listening port for forwarding. Gateway authentication is required by default. If you make the service reachable beyond the host, configure an appropriate authentication method and explicitly allow the remote browser origins that need the Control UI.

Configuration changes normally use hybrid reload. Safe changes take effect while the Gateway is running, and changes that require a restart trigger one. If you change the service port, update the installed service definition as described in the runbook.

### Linux supervision

A user service can keep the Gateway running after logout when lingering is enabled for that account. A headless host also needs a working user service manager and user message bus. Check service status and logs if installation or startup fails.

A deliberately system-managed service should run as the non-root account that owns the OpenClaw state and configuration. Avoid starting a competing user service for the same profile and port. Manage the service through its chosen owner, and run Doctor as the service account with the same state and configuration locations.

An invalid configuration stops startup. Repair the configuration before restarting repeatedly. Startup also stops if workspace recovery cannot safely finish after its retries. Use Doctor and service diagnostics to investigate rather than bypassing recovery.

### Remote access and recovery

For remote access, prefer a private VPN or an SSH tunnel. The tunnel transports the connection but does not bypass Gateway authentication.

Separate Gateway instances are useful for deliberate isolation or rescue. Give each its own port, configuration, state, and workspace. The runbook calls for at least 120 ports between base ports so the related ports do not overlap. Multiple connection URLs can still lead to the same Gateway.

If the service is running but clients cannot connect, check the target address and credentials as well as service health. A port conflict, missing authentication, or invalid local mode can prevent startup. Doctor, logs, and channel probes help narrow the cause. A reachable Gateway alone does not prove that a particular channel can deliver a message.

[Gateway runbook](https://docs.openclaw.ai/gateway)

## Configuration

Configuration connects channels and controls access, models, tools, sandboxing, sessions, networking, and automation. OpenClaw uses safe defaults when no configuration file exists. Global settings and agent defaults can be refined for individual agents where supported.

### Make a change

Onboarding and the configuration wizard guide initial setup. In the Control UI, open Config to use a form generated from the active schema. Common settings appear first. Advanced settings are grouped separately, and search can reveal matching advanced options. A raw editor is available for experienced operators.

Choose a workspace and chat model before connecting a channel. Then set who can reach the agent through that channel. When two agents have different jobs, start with shared defaults and override only what needs to differ, such as the model or workspace. [Model providers](#model-providers-for-a-linux-gateway) and [channel routing](#chat-channels-and-routing)

The Gateway watches its active configuration and normally applies changes with hybrid reload. Some changes take effect immediately and others require a restart. Use the [configuration reference](https://docs.openclaw.ai/gateway/configuration-reference) for exact fields, defaults, and examples.

### Validation and recovery

The complete configuration must validate. Unknown settings, incorrect types, or invalid values can prevent startup. Runtime plugin and channel schemas contribute their own settings. The active configuration file must be a regular file for writes. If you use a separate location, point the Gateway directly to the real file. A setting appearing as advanced only affects how the form presents it.

A failed reload leaves the last accepted configuration running. After a successful startup, the Gateway keeps a trusted recovery copy, but it does not restore that copy automatically. Doctor can diagnose problems and explicitly repair or restore a suitable copy. Automatic migration only writes a fully valid result, and some externally managed or newer configurations are excluded from migration.

OpenClaw also guards against changes that look like accidental loss of a large part of the configuration. It may save a rejected proposal separately while leaving the active configuration unchanged. Review the diagnostic and use Doctor for recovery. Backups can contain sensitive information, so protect them as carefully as the active file.

[OpenClaw configuration](https://docs.openclaw.ai/gateway/configuration)

## Chat channels and routing

Channels connect chat applications to the Gateway. Several can run at once. The host selects the agent for an incoming message, and replies normally return to the conversation that sent it. The Control UI uses WebChat as its internal channel.

### Connect and protect a channel

Telegram is a useful first channel because its plugin is bundled and setup uses a bot token. Add an account during onboarding or with the channel setup tools, then use the channel probe to check it. WhatsApp uses QR pairing. Other services have their own credentials and setup guides.

Set direct-message pairing and allowlists deliberately before broadening access. Groups have their own access and mention rules. For example, Slack treats a multi-person direct message as a group. Supported channels may also protect against bots replying to one another indefinitely.

### Accounts, agents, and sessions

A channel is an integration, and an account identifies a login within it. An agent supplies a workspace and session store. A session holds conversation state and orders work.

Direct messages normally share the agent's main session across channels. Choose a more isolated direct-message scope when people, channels, or accounts should have separate history. Even with shared history, external messages have their own runtime identity for sandbox and tool policy.

Groups and rooms normally have separate sessions. Threads and forum topics can have more specific context. A binding can instead share a group's context with the main session, while replies and mention rules still follow the originating room. When several accounts exist, set an intentional default for outbound requests that do not name an account.

### Choose an agent

Routing uses the most specific matching binding. A binding for a particular conversation takes priority over broader account or channel rules. Thread routing can inherit from its parent conversation. Every condition in a binding must match.

An unmatched message needs an eligible fallback owner. With multiple agents, OpenClaw does not simply choose the first one. Broadcast settings can deliberately involve several agents in an admitted group message. Channel access rules still apply, and explicitly bound ACP sessions remain exclusive.

### Delivery and history

A WebChat turn and its background completions stay in WebChat unless an external route is explicitly chosen. A saved external route does not override the current conversation. Failed or suppressed sends do not establish a new delivery route. A confirmed partial send can establish a route without counting as full delivery.

Session history belongs to each agent. Back up state and follow the documented migration procedure if startup reports an older session store. Use channel probes and logs to distinguish a connected transport from successful delivery.

Supported channels can introduce a bot when it joins an allowed room. The introduction uses available room information, respects access policy, and does not invent unavailable history. It can be disabled for supported channels or accounts.

[Chat channels](https://docs.openclaw.ai/channels) and [channel routing](https://docs.openclaw.ai/channels/channel-routing)

## Managing secrets

Secret references let supported credentials live outside ordinary configuration. They reduce exposure to an agent that can read configuration files. They do not isolate the Gateway process or protect other readable copies of a credential. Tool results and transcripts do not automatically mask everything read from a file.

### Store and connect a secret

In the Control UI, open Settings and then Secrets. A Protected secret is write-only and can be used by a supported secret reference or destination-bound Gateway egress. Choose Agent-readable environment only when commands on the Gateway host need the value and the agent is allowed to expose or persist it.

Adding a value to the store does not connect it to a setting. Select a secret reference in the supported field as well. References can also use supported environment, file, or executable providers. The selector can suggest providers without proving that a named value exists. Consult the [credential reference](https://docs.openclaw.ai/gateway/secrets) for supported fields and exact setup.

### Audit and rotate

Use the secrets audit and configuration tools to find plaintext credentials, configure references, and check the result again. Preflight checks can validate references before applying changes. Executable providers may have side effects, so resolving them requires deliberate permission.

A migration is complete only after the audit is clean and remaining plaintext copies have been handled. Check configuration, authentication stores, environment files, generated files, backups, and copies. Rotating credentials and unsupported credential surfaces may need operating-system isolation or an external credential proxy.

The Gateway resolves active references into an in-memory snapshot at startup and reload. After rotating a backend secret, reload secrets and verify the affected account or provider. A secret still exists in process memory when needed, even when OpenClaw delays exposing it to a model provider until the outbound request.

### Diagnose unavailable credentials

Some isolated provider or channel failures allow the Gateway and healthy accounts to start while the affected account remains unavailable. Failures involving Gateway authentication or invalid references can stop startup. During reload, an unchanged eligible account may temporarily retain its last known good secret. A strict failure preserves the active snapshot.

Doctor and status views report degraded owners without exposing values. Restore the source credential, reload secrets, and verify the affected service. A live Gateway does not necessarily mean every channel is ready.

[Secrets management](https://docs.openclaw.ai/gateway/secrets), [runtime model](https://docs.openclaw.ai/gateway/secrets/runtime-model), and [operations](https://docs.openclaw.ai/gateway/secrets/operations)

## Session permission modes

A permission mode sets the filesystem boundary and command review posture for a session's OpenClaw-managed tools. The boundary is the session root, or the agent's workspace when no root is recorded. Sandboxing and other tool restrictions remain in force. Native runtimes can also have their own controls.

### Choose a mode

Read only permits reads inside the root and denies managed writes and command execution. Ask me permits reads and writes inside the root and sends commands requiring escalation to a human reviewer. Auto-review uses an automated reviewer for eligible commands, which can allow, deny, or ask a human. Full access permits unrestricted filesystem access and ordinary command execution without a reviewer, subject to independent restrictions. Full access requires administrator authority.

A reviewer denial gives the agent a reason. The agent must find a materially safer approach or ask the user. It must not work around the denial. Some commands require human approval regardless of automated review. Approval-bound commands are checked again before launch to detect changes.

### Session roots and defaults

An explicit working directory or managed worktree can establish the session root. A worktree boundary covers the checkout even if the working directory is nested inside it. File tools reject paths that escape the trusted boundary, including escaping links.

Without an explicit mode, the agent inherits its configured file and command policies. Those policies are independent. A worktree alone does not select a permission mode. An operator can configure a creation-time default for attended sessions. Existing sessions keep their settings, and a Full access selection still requires current administrator authority.

The Control UI can display the resolved posture of Agent default when it matches a named mode. That display describes the current settings and does not grant authority. Selecting Agent default removes the session override.

### Delegated administration

Persistent changes delegated by an agent are checked against the requesting run's effective authority. Restricted or uncertain authority generally requires human approval unless an independent grant applies. A one-time approval covers the proposed change only.

An operator can configure a standing delegation grant, or require human review even in Full access. Such a grant can permit administrative changes that enable host code execution. Expanding the grant requires operator administration or approval of that specific change. An agent cannot approve its own increase in authority, and child runs retain inherited restrictions.

When approval is required, use the Control UI or the channel's native approval controls when offered. A casual text reply does not grant approval. Stopping a run cancels its pending approval. The host checks authority again before applying a persistent effect.

### Change a mode during work

Use Permissions in the chat composer to change the session mode. For the OpenClaw runtime, subsequent tool calls use the new policy. Pending approvals under the previous policy are cancelled. Completed writes and commands already started are not undone.

Some active runtimes cannot change modes during a run. Stop the task, change the mode, and continue in the same session. Session policy, host approval requirements, sandboxing, and tool allow or deny rules can all constrain an action. See the [permission mode reference](https://docs.openclaw.ai/gateway/permission-modes) for exact precedence and settings.

## Exec approvals

Exec approvals govern commands on the Linux Gateway host or a paired execution node. The agent first needs access to the execution tool. The target, execution policy, and any required approval must also permit the call. Once started, the process remains subject to its operating-system and sandbox permissions.

### Choose a policy

A deny policy blocks host execution. An allowlist policy runs matching commands. Ask can send a command outside the allowlist for human review. Auto can send eligible misses to an automated reviewer, which may allow, deny, or escalate the request. Full permits host execution without ordinary prompts. Separate strict review rules can still apply.

The host or node can impose stricter requirements. When a required review cannot be delivered or times out, the fallback normally denies execution. The [execution reference](https://docs.openclaw.ai/tools/exec) explains policy precedence and exact settings.

### Configure and review

In the Control UI, open Devices and then Command approvals. Select the Gateway or a compatible paired node, choose the applicable defaults or agent, and edit the policy and allowlist. The approval inspection tools show requested and effective settings. An available tool still must pass checks when it is called.

Keep allowlist rules as narrow as the recurring work requires. A broad rule for a program can allow a call even when a narrower rule would not. Shell chains must satisfy policy for each top-level command. Argument restrictions need careful matching, so use the documentation when writing them.

Read the approval card's agent, execution host, command, and working directory before deciding. Allow once covers the pending call. A durable approval should be used only when its displayed scope is appropriate for repetition. Always allow here binds the approved arguments and working directory. Running the same operation somewhere else calls for a new decision. The host rechecks policy and executable identity before launch. Cancellation, changed executables, expired handoffs, or a used one-time approval can prevent execution.

### Recurring automation

An eligible isolated automation can request a standing approval through a connected Control UI reviewer. Automation approval cards are not delivered to chat channels. If review is required and no approval surface is connected, the run is denied.

A standing grant binds the agent, job, command, working directory, and requested environment. Current host policy still applies. A substantive job edit or deletion invalidates the grant, while pausing and resuming an unchanged job preserves it. Some commands still require individual review.

Open Settings and then Approvals to inspect or revoke standing grants. Revocation prevents future use. An operation that already consumed a grant may still finish starting after final checks.

[Exec approvals](https://docs.openclaw.ai/tools/exec-approvals) and [approval administration](https://docs.openclaw.ai/cli/approvals)

## Agent loop

An agent run takes an admitted message, assembles context, asks the model for a response, and carries out permitted tool calls. It may repeat that cycle before producing a final reply. The Gateway owns the run and sends progress and the result back to the originating conversation.

### Admission and ordering

The Gateway acknowledges an accepted input before the run finishes. Work for the same session stays ordered, while independent sessions can run concurrently as capacity allows. The runtime reserves the session's turn before it takes a global execution slot. If a turn loses its claim on the transcript, it cannot append stale results.

As the turn starts, the runtime resolves the workspace, reads the skills snapshot, and prepares the current model and credentials. Some workspace and plugin settings can be reused across turns. Model selection and authentication are resolved for the current attempt. A new message can steer, queue behind, or interrupt active work under the session's queue mode. [Agent runtime](#agent-runtime) and [session management](#session-management)

### Context and tools

The runtime prepares instructions, conversation history, available tools, and current context for the selected model. Tool arguments are validated before execution. Tool policy, sandboxing, and approvals still decide whether a call may run. Results return to the model so it can continue. A failed tool call needs an honest account or a successful retry. If the model prints something that resembles a tool call, the runtime can request a corrected call through the tool interface. The printed text has no authority to execute.

A confirmed final message or final reaction to the current conversation can complete the run. Progress messages and actions elsewhere do not establish that the current conversation received its answer. Confirmed delivery helps prevent duplicate replies during retries.

### Streaming and recovery

The Control UI and supported channels can show text as it arrives, along with tool and lifecycle events. A final response, error, or cancellation closes the visible run. A retryable attempt can continue without presenting a premature final failure.

When context is full, OpenClaw can compact older history and retry. If a model response reaches its output limit during tool work, already accepted tools can finish and their recorded results can support a bounded continuation. Completed actions are not replayed. Useful partial output remains separate from a failure notice.

If the tools have finished but the turn still needs a reply, OpenClaw can make a final synthesis pass from their stored results. That pass reports any unresolved tool failure. An empty answer does not satisfy a required reply. If recovery cannot produce a required answer, the user receives a short failure notice. External channel turns can deliberately end silently when appropriate. The Control UI and other sessions that require a result must receive one or continue unfinished work.

### Waiting and timeouts

Waiting for a result can time out without stopping the underlying run. Wait again for the same run when appropriate. Execution also has its own time budget, and a fallback model receives a fresh attempt budget. Approval waits pause the unused attempt budget, while a question to the user does not.

Provider connection and progress limits are separate from the overall attempt budget. For a slow local Ollama model, check the provider timeout before increasing the agent's overall budget. Cancellation stops the run and revokes pending tool and approval authority.

A timeout during a tool call can leave its outcome unknown. Inspect the actual state before repeating the action. Completed tool results remain in history. A terminal timeout is a failed turn, and continuing afterward is new input.

### Stuck work

Diagnostics can distinguish long-running work from stalled work using ownership and progress. The controller can request a stop when a run is semantically stuck. Cleanup and transcript settlement may continue after the visible run ends. Pending questions, child work, and active tool calls retain their owners until they settle or are cancelled.

[Agent loop](https://docs.openclaw.ai/concepts/agent-loop), [tools](https://docs.openclaw.ai/tools), and [compaction](#compaction)

## System prompt

OpenClaw assembles a system prompt for each agent run. It combines stable guidance with current tools, workspace context, sandbox state, channel capabilities, and provider contributions. The prompt guides the agent, while tool policy, sandboxing, approvals, and channel access rules enforce permissions.

### What the prompt tells the agent

The prompt describes available tools and directs the agent to act on actionable requests, continue until complete or blocked, and verify its work. It also directs care with existing files, credentials, and security boundaries. User instructions, existing authorization, and applicable skill requirements remain important. A prompt cannot grant a tool permission that the runtime denies.

Provider plugins can tailor interaction style and execution guidance for a model family. Current runtime facts, such as local time and active work, arrive separately from stable instructions. A fresh snapshot replaces an older snapshot for the same scope. An empty snapshot describes that scope at that moment and does not prove that no other work exists.

For work intended to happen later, the agent should arrange a scheduled task or an appropriate completion path. Delegating work to a child does not by itself complete the user's overall request.

### Stable instructions and current facts

OpenClaw can reuse the stable part of the prompt while refreshing facts that change each turn. The stable part can include project instructions and provider guidance. Tool availability, sandbox state, current time, and recalled memory can change during a conversation. Caching a tool description leaves each call subject to fresh checks.

A provider plugin can adapt the interaction style or instructions for a model family. It can keep lasting guidance in the reusable part of the prompt and attach fresh facts for the current turn. A route change, profile change, reset, or compaction can start a fresh prompt sequence. [System prompt reference](https://docs.openclaw.ai/concepts/system-prompt)

### Prompt modes and workspace context

The full prompt includes all applicable sections. A shorter mode used for subagents omits some sections while retaining essential tool, workspace, sandbox, and runtime guidance. A minimal identity-only mode is also available. External channel turns can deliberately finish silently. Sessions that require a result must provide one or continue the work.

The configured workspace supplies the agent's identity, user context, instructions, and durable memory when applicable. A project working directory can add its own instructions without changing the agent's persona or memory. For example, a release worktree can explain how to test that branch while the agent keeps its own operating rules and long-term memory. Subagents receive a narrower bootstrap context. Daily notes are normally retrieved when needed, while durable memory should stay concise.

Injected files have size limits. When a file is truncated for a prompt, its contents remain intact on disk and the agent receives a notice. Missing files are identified. The workspace and its memory provide instructions and context, while OpenClaw documentation remains the source for product behavior.

### Context and inspection

The model's context window contains instructions, tool descriptions, conversation history, tool results, current input, and space for output. Context inspection tools show estimated file sizes, truncation, and tool overhead. Compaction summarizes older conversation, while pruning reduces tool results in the request view.

Eligible skills appear as short descriptions. The agent reads a skill's full instructions when needed. Skill eligibility depends on installed skills, configuration, and applicable allowlists. The prompt also points to available local or public documentation. A missing tool in one session does not necessarily mean the product lacks the capability.

Prompt hardening helps distinguish runtime instructions from conversation data. It does not create an authorization boundary or guarantee protection from prompt injection. Treat outside content as untrusted and rely on actual permission controls.

[System prompt](https://docs.openclaw.ai/concepts/system-prompt), [context](https://docs.openclaw.ai/concepts/context), and [agent loop](#agent-loop)

## Compaction

Every model has a limited context window. As a conversation approaches that limit, OpenClaw can summarize older turns and keep recent messages in full. The saved conversation remains on disk. In the Control UI, the Context compacted divider can show how many tokens were saved and the percentage reduction.

### What the summary keeps

OpenClaw keeps tool calls together with their results when choosing where to split the conversation. It builds on the previous summary and gives special attention to the current request, recent conversation, and important identifiers. It may sample older material and shorten long tool results. Details from the middle of a result can be missed, even though the full result remains in saved history.

Safeguard mode is the default for new configurations. It checks the summary for structure, pending requests, and exact identifiers, then attempts corrections when needed. If the facts cannot fit or corrections fail, OpenClaw may keep a reduced summary and warn that its quality has degraded. Essential details can still be lost, so check the warning and repeat anything the agent needs.

If a summary cannot be generated, OpenClaw normally keeps the original history and reports the failure. In some recovery cases it can retain recent history without a new summary so the conversation can continue. A timeout during an active automatic compaction can also trigger a deterministic reduction. That keeps recent messages, complete tool pairs, pending input, and the previous summary, but older unsummarized facts leave the model's view.

### Automatic and manual compaction

Automatic compaction normally runs as the context fills or after a recognized context overflow. OpenClaw also checks whether new tool results will fit before submitting another request. Recovery can preserve completed tool results and continue without repeating completed actions. If the prompt still cannot fit, shorten the input, start a new conversation, or choose a model with a larger context window.

You can also ask for compaction in a supported chat and give it a focus, such as the decisions made in a design discussion. The official reference explains the exact chat command. Manual compaction reports failure if it cannot produce a valid summary. The amount of recent history retained depends on the available space after instructions, tools, pending input, and output reserves.

Starting a new conversation clears its conversation history from the active context. Fixed instructions and available tools still occupy space. If those alone are too large, compaction cannot solve the problem.

### Choosing settings

The active session model normally makes the summary. You can choose a separate summarization model, including a local Ollama model. An explicitly selected model uses that exact choice rather than inheriting the session's fallback chain. A larger summarizer does not increase the active model's context window.

A larger summary can preserve more detail but consumes more space in later requests. Strict identifier preservation is enabled by default, although a degraded summary can still omit identifiers that do not fit. Optional notices can announce routine compaction. Degraded summaries produce a warning even when routine notices are off.

A transcript size guard can trigger compaction before a run. If that cannot bring the selected history within the limit, OpenClaw can temporarily omit older complete turns while keeping the current request and tool pairs. This does not delete saved history. A separate history loading limit can also leave old material outside the model's view. Manual compaction provides a semantic summary when old context matters.

### Memory and provider behavior

Before compaction, an optional memory flush can save durable facts. It uses the active session model and its normal fallbacks. Use a local model and local fallbacks when extraction must stay local. A failed flush does not discard the conversation. See [Memory](#memory).

Eligible direct OpenAI Responses routes can use OpenAI's compaction endpoint. The provider chooses the retained context, which still counts against the prompt budget. OpenClaw falls back to its own summarization when the endpoint fails or its result cannot be used. A focused manual request uses OpenClaw's own summarizer so the focus can be applied.

A custom compaction provider can be supplied by a plugin. OpenClaw preserves recent context and falls back to its built-in safeguard summarizer if the provider fails or returns nothing. Custom provider output does not receive the built-in summary quality audit.

### Compaction and pruning

Compaction saves a summary in the transcript. Pruning temporarily reduces older tool results in the request without saving a summary. Both can help when large tool results fill context. If compaction happens frequently, check the model's window and consider pruning. If the agent has lost an important decision, repeat it or start a focused compaction before more context is lost.

[OpenClaw compaction reference](https://docs.openclaw.ai/concepts/compaction)

## Standing orders

Standing orders give an agent ongoing authority for defined work. Say what the agent may do, what starts the work, which actions need approval, and when it must stop and escalate. Begin with narrow authority and expand it as experience warrants.

Put the instructions in the agent's workspace instructions file. OpenClaw normally includes that file in each session, including short-lived command-line runs. For a larger program, refer from those instructions to a dedicated document. Files in arbitrary subdirectories are not included automatically. Workspace context injection can be disabled, so check the agent's settings if an order seems absent.

### Define the work and its boundaries

A weekly status order might authorize the agent to collect configured metrics, compare them with last week and the targets, save a dated report, and deliver a summary to a named owner. State whether it may change source data or send anything outside the organization. Tell it what to do when a source is unavailable or a result is unusual.

Give unrelated programs their own scope, cadence, and approval boundaries. A monitoring order could permit health checks and a restart, specify when to alert about low disk space, and require escalation after two unsuccessful restarts. Identify approved recipients and actions clearly.

### Schedule and verify

Standing orders do not run by themselves. Use an automation or an appropriate event hook to trigger the work. The automation can refer to the standing order so that the authority and procedure stay in one place.

Ask the agent to perform the work, verify the result where possible, and report both what happened and what it checked. Set a finite retry limit and a path for persistent failures. Review logs and update the orders as your needs and permissions change.

[OpenClaw standing orders reference](https://docs.openclaw.ai/automation/standing-orders)

## Automations

Automations are OpenClaw's persistent scheduler. A job describes when work runs, what it does, which session it uses, and how its result is delivered. Manage jobs on the Control UI's Automations page, or ask the agent in chat to create one. Review the saved job and its run history.

A reminder might run once and delete itself afterward. A weekday report might run in an isolated session, use named sources, and deliver to an authorized channel. Standing orders define lasting authority. The scheduled message can refer to those orders.

### Choose a schedule

Jobs can run once, at a fixed interval, on a calendar schedule, when a watched process exits, or when a supervised stream produces output. Give calendar jobs an explicit time zone when local time matters. Without one, recurring calendar schedules use the Gateway host's time zone. The Control UI interprets its Run at field in the browser's time zone and rejects a time that does not exist during a daylight-saving transition. For a repeated fall-back time, a new entry chooses the first occurrence.

Hourly calendar jobs may be staggered by up to five minutes. Choose exact timing when the minute matters. Calendar expressions that specify both a day of the month and a day of the week match either condition. Active hours can limit when a job may run, including overnight windows. A one-time job waits for the window to open. A recurring job skips an occurrence outside it.

An idle-only job waits for the whole agent to be quiet and may wait indefinitely. A manual force-run bypasses the ordinary schedule but still respects active hours, authorization, lifecycle, and delivery restrictions.

### Choose what runs

A job can place a system event in the main session, request an agent turn, run a process on the Gateway, or run a headless script with the agent's tools. A deterministic condition or script can avoid a model call when the condition is machine-checkable.

An agent turn can use the main session, a child of the current conversation, a fresh isolated transcript, or a named session that retains context between runs. Isolated runs do not inherit the earlier conversation or its routing. Put durable instructions in the job or its scratch space. A light-context option omits workspace bootstrap instructions, so avoid it when standing orders are needed.

Tool access remains subject to current policy, sandboxing, approvals, and the creator's permission ceiling. A job's delivery permission does not grant permission to read a channel. Linked jobs pause if their originating conversation is removed or archived, or its worktree disappears. Each occurrence rechecks current permissions. Disabling or removing a job cancels its active occurrence.

For unattended work, ask for a finished result and define when a quiet monitoring run should produce no reply. A recurring report should still deliver on its requested cadence. Scratch can hold a checklist. A job may be configured to skip a turn when scratch is explicitly empty, while missing scratch still allows the run.

### Watchers and delivery

A stream watcher persists and restarts until disabled or removed. Execution approval can identify the exact watcher and its location. Changes or restarts may require fresh approval. Check the observed stream status because a paused record alone does not prove the process has exited. A sandboxed stream uses its approved container and mounts. Unconfirmed cleanup can prevent replacement until the process is stopped and the Gateway restarted.

A job can announce to an authorized chat, send to a webhook, or deliver nothing. Owner delivery requires an identified owner and does not guess from the last group conversation. A missing owner route is recorded even if execution succeeds. State the desired output language in the job because the scheduler does not infer it from prior messages or channel locale.

### Check failures

Execution and delivery are separate outcomes. A job can finish its work and still fail to deliver the result. Check the run history, destination, schedule, time zone, model, and tool policy separately.

Temporary provider failures may receive quick retries. Repeated execution failures can disable a recurring job, and repeated schedule calculation errors can disable it sooner. After fixing the cause, enable the job again. Some conversation-owned jobs can raise a repair request in their originating conversation. An uncertain webhook response may leave delivery status unknown, so verify before repeating a consequential action.

If a local provider was unavailable, restore it before running again. A missed one-time occurrence may need a new schedule. OpenClaw can migrate supported older heartbeat monitors into editable jobs while preserving their history.

[OpenClaw automation reference](https://docs.openclaw.ai/automation/cron-jobs)

## Tool Search

Tool Search is an experimental way to work with a large catalog. It gives the model a compact directory and lets it discover the full details of an authorized tool when needed. This can reduce the information sent on every request. It does not grant access to tools that policy has denied.

OpenClaw normally selects structured Tool Search for embedded runs when no choice has been set. Direct tool descriptions remain an option. If Code Mode is engaged, it takes precedence. With native Ollama transport, common web and memory tools normally remain directly visible while other optional tools can be deferred. An explicit setting overrides that local default.

### How discovery works

OpenClaw first applies the agent, sandbox, session, channel, and provider policies. It then assembles eligible built-in, plugin, MCP, and client tools. The model can search by task or exact name, inspect a tool's full input requirements, and request a call. Search ranks trusted tool metadata by words. It does not index untrusted parameter descriptions from MCP servers or clients.

The resulting call follows the ordinary permission checks, approvals, hooks, and logging. Invalid inputs fail before execution. A skill is a set of instructions, so the agent should read it rather than treating its name as a callable tool.

A large network result may be omitted if it cannot fit the tool-result budget. For a read-only operation, ask for a smaller page from the same starting point. Do not repeat a change merely to recover its output.

### Choose what stays visible

Operators can choose which eligible tools are deferred and which remain directly visible. Core and required tools retain the visibility their mode requires. In directory mode, common coding and client tools also stay direct while other eligible descriptions can be deferred. Selectors can target a source, a registered name, or both. Exclusions take precedence. These choices affect presentation, not server activation or authorization.

The MCP directory is bounded. As it fills, OpenClaw removes descriptions before summarizing names by server and pointing the model to search. Client tools remain searchable. A server that fails to connect or list its tools is absent for that turn and can return on a later successful turn. Server descriptions are untrusted, so choose MCP servers carefully.

### Decide whether it helps

Large catalogs can benefit from deferred descriptions. For a small catalog, the extra discovery calls may cost more than the saved context. Compare real request size, latency, and session activity for your workload. Older configurations may require OpenClaw's migration procedure before the Gateway starts. The official reference provides exact settings and migration commands.

[OpenClaw Tool Search reference](https://docs.openclaw.ai/tools/tool-search)

## Code Mode

OpenClaw Code Mode is an experimental way for an agent to coordinate several tool calls with short JavaScript programs. It presents a compact execution surface instead of most individual tool descriptions. The agent can discover authorized tools, inspect their requirements, call them, and combine results. Normal permissions, approvals, authentication, and channel rules still apply.

The automatic setting engages Code Mode only for models marked as preferred performers. You can choose the global setting in Settings, under Agents & Tools, Labs, and Code Mode. Agent and model overrides can take precedence. If the selected executor is unavailable, the run fails rather than silently exposing every tool.

### Choose the executor carefully

The default Node executor runs on a worker thread outside the Gateway's main event loop. It is intended for trusted execution and is not a security boundary. The bundled QuickJS executor provides hardened guest isolation. Both use the Gateway's tool bridge and its permission checks. Review the executor documentation before enabling either one.

OpenClaw Code Mode is separate from the similarly named Codex feature. Its execution surface runs JavaScript, not a shell command. Shell and file work must go through an authorized tool. The official reference provides the exact interfaces.

### How a run works

The model sees a bounded index of callable tools and can search for more detail. MCP tools are discovered through their own namespace. Full descriptions are available when the compact hint is insufficient. Each nested call goes through the normal policy, approval, hook, and logging path. Some tools remain directly available outside the guest bridge because their results cannot cross it.

For example, an agent could find a calendar-reading tool, inspect its requirements, request a bounded date range, and summarize the results. Independent reads can run together. Calls that depend on earlier results should wait for those results.

A Code Mode run can continue in the background. Wait for it only when the outer result says it is waiting, using the run identity supplied there. A background shell process returned inside a completed run has a separate identity and needs the process-control tool instead. A persistent task session is also distinct from a supervised delegated helper and does not produce a child-completion event.

### When to use it

Code Mode can help with large catalogs and workflows that combine several calls or transform results. Direct tool descriptions can be easier for a small catalog or a model that struggles with short programs. Tool Search provides structured discovery and dispatch without JavaScript orchestration.

[OpenClaw Code Mode reference](https://docs.openclaw.ai/tools/code-mode)

## Plugin SDK overview

The Plugin SDK is OpenClaw's typed contract with code installed inside the Gateway. Use its focused subpaths to build a plugin. For an independent service, script, or application that calls an already running Gateway, use the [external integration interfaces](https://docs.openclaw.ai/gateway/external-apps).

Pin the OpenClaw version you develop against and test the versions you claim to support. The SDK marks registration APIs, runtime APIs, provider and channel contracts, hooks, and native Control UI APIs as experimental. Compatibility windows and documented migrations still apply. Use focused imports for the capabilities you need and local modules for private implementation. The [import guide](https://docs.openclaw.ai/plugins/sdk-overview/imports) groups subpaths by purpose.

### Use the registration object

The entry point's registration function receives a plugin API object. It carries the plugin's ID, name, description and version, its discovery source, and, when available, its root and selected runtime entry. The runtime entry can be emitted JavaScript even if discovery found a package or source directory. Use the runtime source field to locate private modules beside the selected entry. It is absent on metadata-only paths. Resolve plugin-relative files with the provided path helper.

Use the registration configuration snapshot for the configuration snapshot available at registration and the resolved plugin settings for the plugin's own resolved settings. Code that needs the latest active snapshot should use the documented runtime config helper. Use the scoped logger for operational messages. Metrics registration is available when the operator enables it. Registration mode tells you whether the host is loading a runtime, a lightweight setup runtime, or a narrower surface. Keep any lightweight entry free of unnecessary runtime imports.

### Choose a registration surface

Register an agent tool when you want the model to select a typed action. Use a command for an explicit operator or user invocation. An installed node can expose a node-host command under its own contract. A widget presenter lets an operation show a structured result in the Control UI. Across all of these, declare discovery metadata in the manifest when required and let the corresponding host policy enforce permissions.

Use typed hooks for lifecycle and policy decisions. Use an HTTP route or a scoped Gateway method when another authenticated client should call the plugin. Background services and migrations have their own registration contracts. A workflow plugin can also own a session extension, a trusted tool policy, or a Control UI contribution. Match any privileged runtime registration with the manifest declarations the host requires. The [infrastructure guide](https://docs.openclaw.ai/plugins/sdk-overview/infrastructure) and [workflow plugin hooks](https://docs.openclaw.ai/plugins/sdk-overview/host-hooks) cover these paths.

Providers register an inference, embedding, search, or other capability through its specific registration contract. The memory capability and context engine are exclusive slots. Each slot has one selected owner even when plugins for several engines are installed. A plugin can also register a process-wide session discussion provider. It reports whether a discussion is unavailable, ready to open, or already open, then creates or resolves it. Registering a different provider replaces the active one.

A native Control UI contribution is enabled by default for eligible enabled plugins. The advanced opt-out for user-installed browser code is independent of backend plugin loading. Use the declaration that matches the UI surface you intend to own.

### Keep runtime work with its owner

Use the narrow helper for the task instead of reconstructing host state. A command handler can receive a compaction capability for its current bound session. Await it and report the result or reason. If the capability is absent, ask for a bound conversation. The capability expires when the invocation settles. OpenClaw owns transcript persistence, the active session generation, and token accounting.

For transcript-aware plugins, use the asynchronous Session Manager APIs in the focused agent-sessions SDK subpath. Use bounded active-branch reads when a worker only needs part of a transcript. An incomplete read can leave the prior prepared view intact, and an absent database must be prepared by its session owner.

Wait for append and persistence operations before publishing dependent work. The low-level persistence operation writes an entry without updating the loaded view, so use the typed append method when the caller also needs the new view. Follow the [agent runtime helper reference](https://docs.openclaw.ai/plugins/sdk-runtime/agent) for admission, cancellation, and identities.

Keep tool factories and long-running operations scoped to their owning invocation. Registration tells the host what exists. A scoped runtime handle carries the authority needed for a particular run, request, or service lifetime. Release resources when that lifetime ends and reacquire active handles after reload.

[Source page on OpenClaw Docs](https://docs.openclaw.ai/plugins/sdk-overview)

## Feature plugins

A feature plugin can provide both typed backend operations and views in the Control UI. It can add a page, sidebar destination, panel, widget, or action. It can also offer replacements for host surfaces such as the workspace, transcript, or composer. Pin and test the host version because the browser and backend contracts are experimental.

Native UI is available by default when its plugin is enabled. Use the Control UI served by the connected Gateway. Native assets require the same origin and a secure browser context. An HTTPS connection or browser-trusted loopback works. A plain HTTP LAN connection can show normal dashboard features while failing to load authenticated plugin assets. Backend operations remain available in that case.

The plugin's browser code runs with the signed-in viewer's Gateway authority. Check the plugin's declared extensions and trust the code before enabling it. When isolation matters, use a sandboxed dashboard widget or an MCP App. An advanced Gateway setting can opt out of native browser code for user-installed plugins. Changing it updates the available views without disabling backend tools, operations, or services. Reload browser tabs to clear code already running. Bundled plugins have their own native UI policy.

### Try a feature in the Control UI

Create a project named Draft Review from the feature-plugin starter. Install its dependencies, build and validate it, then install the local plugin. The starter gives you a draft analyzer and lets you try it as a tool or through the dashboard.

Open the draft-review page from the sidebar, or open Plugins, then Advanced, then Customize UI to try the replacement composer. Choose Built-in to restore the host view. Replacement selection belongs to the browser runtime. The built-in plugin settings page remains available if a workspace replacement conceals navigation.

A feature project uses three focused SDK subpaths. The feature-contract subpath defines shared operation schemas and client calls. Feature-plugin connects backend handlers to the live host. Control-ui supplies browser activation, view contracts, and host components. The plugin owns its browser DOM and bundles its framework dependencies.

### Define operations once

Declare a named query or action with TypeBox input and output schemas. Implement it through the plugin setup function. A query requires the Gateway's operator read scope. An action requires operator write. You can also declare an agent tool or add a command adapter to an operation. The implementation receives the originating session action, tool, or authenticated command context. Each route keeps its own checks.

For example, a draft analyzer can take draft text and return a bounded report. A page invokes it through the typed feature client and displays the result. The same handler can serve an agent tool if you choose to expose one. Use one contract for operations and events. If your server contract imports backend-only code, pass a browser-safe descriptor to the typed client and retain the canonical contract for type checking.

Validate bounded inputs and outputs, and use caller-safe error messages. Session actions return validation errors separately from operation failures. A thrown operation message is bounded before it reaches the caller. Keep secrets and internal exception details out of it. Store durable data through the plugin's approved runtime and storage surfaces.

A browser view can subscribe to named events or watch a query. The watcher fetches an initial snapshot and refreshes after selected events and reconnection. It discards stale results after a newer refresh or disposal. Use the view's cancellation signal after awaited work.

### Build views around the host's session and request owners

Export a browser entry using the Control UI plugin helper and match its ID to the plugin manifest. Register your contributions through the host UI interface. A view mounts into an HTML element with properties, the host, and a cancellation signal. Its update method receives fresh state and its dispose method releases observers, subscriptions, and framework roots. A hidden but mounted view can pause rendering work and retain state. Removing it retires its handles.

Carry both the agent ID and session key when acting on a conversation. The same session key can exist under different agents. A change to either part retires the old view and its composer operations. Use the provided composer operations to read drafts, propose edits, or send. A proposal waits for the user's acceptance and can be dismissed. A rejected submission should leave the draft available for retry.

Use host navigation to open plugin pages and panels. A panel can appear beside the relevant session. The conversation dock is optional, so check for it before offering a dock action. Use the host's scoped recovery storage for private retry drafts when it is available. Scope storage keys to the agent and session, reacquire the handle after reconnect, and reauthorize the server resource before restoring private content.

Use independent session queries when a page needs its own filters. A missing row in a partial list is not enough to establish deletion.

### Return a tool result with an inline view

A tool can return an installed plugin view alongside a plain text summary. For example, a support tool might return an incident ID and a short description. The Control UI can mount an incident panel inline and fetch the current details through a scoped operation. Chat channels, text exports, and model context still have the plain summary.

Declare the view in the plugin, register the same view ID and interface version in the browser entry, and return it through the host's inline-view helper. The saved descriptor includes the plugin ID, view ID, version, payload, and summary. The payload is at most sixteen kibibytes, and the summary at most four. Keep large data in plugin storage and pass an ordinary resource ID.

The Gateway associates the result with its actual native tool invocation. Only an installed and permitted renderer can mount it for the current viewer.

History restores the descriptor without rerunning the tool or model. Make mounting safe to repeat. Mount can read a snapshot or a live resource reference. Save mutations for an explicit action and authorize the current viewer on the backend. Never put credentials in the saved payload. Keep a compatible renderer for each historical interface version you want to support. If the renderer is absent or fails, the saved summary remains visible.

### Build and reload the browser assets

Point package metadata at the browser source, separately from the backend entry. OpenClaw's plugin build bundles the browser code and dependencies and adds content-addressed JavaScript and CSS entries to the manifest. Keep browser imports analyzable and bundle the framework with your plugin. Each asset is limited to four MiB, with an eight MiB total and a maximum of 128 assets. Run build validation before packing the plugin.

After a browser-only edit, rebuild and use Reload plugin UI in the advanced customization view as an administrator. A failed browser activation can preserve the previous working view. Choose Built-in to recover a replacement when needed. Backend changes use plugin reload or update. Check browser activation separately from backend registration and test the operation in an active chat or channel.

### Review a plugin artifact before activation

Pack a built plugin into an import archive before proposing it for activation. The receipt identifies the archive and includes its cryptographic digest so the operator can approve those exact bytes. The managed installer inspects declared capabilities and retains the exact bytes during review. Changing the source file afterward cannot change the approved artifact.

Review the capability list and native UI declarations because approval includes trusted browser code and the backend. The artifact path supports a single bundled backend entry. Use the normal reviewed package install for shapes that need separate runtime files.

After approval, verify that the running Gateway applied the backend. A saved installation on a stopped host still needs runtime application. A browser activation receipt indicates that a connected browser initialized the specified revision. Test the feature itself in the Control UI to verify its operation and permissions.

[Source page on OpenClaw Docs](https://docs.openclaw.ai/plugins/feature-plugins)

## Plugin testing

Test what your code does, what the OpenClaw loader accepts, and what a user gets from the installed package. These are different checks. A registration mock can prove that a plugin asked to add a tool or hook. A loader-backed run proves that it registered with the host's real metadata, scopes, and policy gates.

### Start with a small implementation test

For a tool, pass representative valid and invalid inputs and verify the return value and structured details. Exercise the denied, cancelled, or incomplete cases that matter for that tool. Use a disposable workspace and test credentials. For a tool that uses request-bound authority after asynchronous preparation, make the fixture capable of rejecting the final effect, and assert that rejection prevents the write or send.

For a channel plugin, test the resolver with missing and blank destinations, a value that cannot normalize, and explicit versus implicit destinations under the channel allowlist. Assert the destination or error. A channel account can be configured without exposing its credential in the status view. Test the account resolver and the inspection result separately, checking that only the safe status view is returned.

For a provider plugin, test a dynamic model result and a catalog result with a fixture credential. Use a test route whose endpoint class is explicit and assert the class if the route matters. That catches missing manifest metadata that would otherwise exercise the custom-endpoint path by accident.

Use per-instance stubs for API clients. Replacing a prototype affects unrelated instances and makes tests harder to isolate. If your plugin stores a runtime handle, supply a fixture with the narrow config or agent methods you need and clear it after each test. Model current config reads and authorized mutation separately.

### Exercise the real loader and installed artifact

Run a loader-backed smoke test for each registration surface you rely on. A hook registration requires a hook name. A plugin that registers a memory capability must declare the memory kind in the manifest or supported entry metadata. Test the trust and activation conditions too. For optional tools, load the same installed package under an agent allowed to use the tool and one without access. With conversation hooks, test that the required permission applies to the specific registration.

Build and pack an external plugin and install it through OpenClaw's managed package path. Inspect the runtime on a supported version of the Gateway. Check that the built entry and its dependencies are present. Compare the tool names in the manifest with the names registered at runtime.

Set up a disposable agent and exercise the tool or command in the Control UI or supported chat channel. If a plugin depends on catalog-backed official trust, also verify through a catalog-backed install.

### Use the right test helpers

The testing SDK subpaths listed for bundled OpenClaw plugins are repository-local. External plugin packages should use their own fixtures and the published runtime contracts. The retired monolithic testing barrel and test-utils alias are no longer available.

In an OpenClaw source checkout, the focused test helpers cover registry creation and retirement, isolated state and auth, channel contracts, provider request captures, disposable servers, and live-provider opt-in. Start with the narrowest fixture. Keep live tests off unless their credentials and scope are explicitly enabled. Channel policy inheritance helpers supply fresh cases with omitted fields preserved. For provider catalog tests, prepare manifest metadata before the suite, install and clear the snapshot around assertions, and avoid cold runtime discovery.

Close retained handles before resetting runtime state. Await retirement, including borrowed cache generations, and check for failures before deleting files or restoring the environment. Await database cleanup before removing state directories. A fixture should survive a failed teardown when the failure needs investigation.

### Run scoped checks before a release

In a source checkout, run the plugin's targeted pnpm test and any applicable contract tests for registration shape, auth choices, or runtime seams. The repository's boundary checks cover direct imports of core source, monolithic SDK imports, and references to removed test aliases. Keep external plugin imports on the same published boundaries.

OpenClaw's repository uses Vitest with informational V8 coverage. Filter by test file or test name to diagnose failures. If local runs hit memory pressure, reduce the worker count. Before publishing, repeat the packaged smoke test for each supported host version. The quickstart and specialized channel and provider guides contain worked testing examples.

[Source page on OpenClaw Docs](https://docs.openclaw.ai/plugins/sdk-testing)
