Get your first reply
The Gateway is the service that runs OpenClaw. It keeps your chat accounts connected, accepts work, and serves the browser dashboard, called the Control UI. The agent is the worker that handles a request. It has a model for conversation, a workspace for its files, and sessions that carry conversation history. Getting a reply in the dashboard exercises all three. Once that works, set who may reach the agent before connecting a channel such as Telegram. Getting started
Prepare a Linux host and choose a model
OpenClaw recommends Node 26. If you use Node 24, check the installation guide for a supported release with the current security fixes. Have a model connection ready before running onboarding. For OpenAI, that means an API key or an eligible sign-in. For Ollama, start the server and download a chat model. Node setup
Think of the model connection as three choices. Pick the model that will answer, the account or credential that authorizes the call, and the runtime that manages the conversation and tool calls. The same model name can appear through more than one provider, so name the provider when the route matters. A short name can resolve through an alias, a unique configured match, or the default provider.
For hosted conversation through the OpenAI Platform, use a project API key with access to your chosen model. For eligible subscription access, connect a ChatGPT or Codex account. On a headless host, device sign-in lets you begin on the Linux machine and finish in a browser elsewhere. Each of these choices authorizes model calls. Signing in to the OpenClaw dashboard is a separate step with its own credential. OpenAI setup OpenAI authentication
For a model you serve yourself, open the Ollama provider setup and choose Local only. Use the address of the native Ollama service, which normally listens on port 11434. The OpenAI-compatible route can cause tool calls to show up as text. A loopback or private-network server can use OpenClaw's local credential marker. Supply a real credential for a public remote endpoint. The address belongs in provider settings and credentials belong in authentication profiles. Ollama setup
Automatic Ollama onboarding looks for a loaded chat model that reports tool support and at least sixteen thousand tokens of context. If you downloaded a model and it hasn't been loaded, connect to it explicitly so OpenClaw can prepare and test it. OpenClaw saves the route after it receives a real response. Choose a conversational model here. You can use an embedding model later to search memory. Ollama model discovery
Onboard and start the Gateway
Install OpenClaw through the Linux installation guide and launch onboarding. Start with Quick start if you have working model access. OpenClaw can try a detected credential against the model, save the route, and open the dashboard. If the test fails or OpenClaw finds no usable connection, it opens manual provider setup. Choose Custom setup to step through all the options yourself. Linux installation Onboarding wizard
Say yes when onboarding asks whether OpenClaw should run in the background on an always-on host. On Linux this creates a systemd user service. You can also decline and keep the Gateway running in your terminal. The settings you saved work either way, and you can register the service later. Give the Gateway time to start after the service is registered. Look for both a running service and a successful connectivity check before opening the dashboard. A standard local installation uses port 18789 for the page and its live connection. Gateway runbook
Connect and pair your browser
Open the Control UI in a recent supported browser. On the sign-in screen, enter the Gateway's token or password in the Gateway secret field. You can also find the field in Gateway settings. Onboarding normally saves a persistent token and honors an existing password. A Gateway started in token mode without a saved token can issue a temporary one. If you need to recover a configured token, use the interactive administrative procedure on the host. If the browser has no usable token, use Doctor to generate a persistent one and restart the service. Connect and pair
Authentication gets your connection admitted. Pairing records which device is connecting. The browser proves its own identity and may ask you to approve it. A direct local connection can qualify for automatic pairing. Connections over a private network generally require explicit approval. An approved browser gets a device token for later connections. When you use the shared Gateway token, the browser keeps it for the current tab and Gateway origin. It keeps a Gateway password in memory. If the device identity changes, the Gateway can require pairing repair.
The Gateway normally binds to the local host. For a browser elsewhere, reach that local service over a private virtual network or an SSH tunnel and complete the same authentication and pairing steps. Container defaults can expose the port for forwarding. If you deliberately make the Gateway reachable beyond the host, configure its authentication and explicitly allow the Control UI origins you use. A deployment where a proxy supplies identity needs the corresponding proxy configuration. Network model
Send a short message in dashboard chat. A reply tells you the browser reached the Gateway and the selected agent could reach its model. A new agent database can take a few minutes to prepare, during which the dashboard shows Starting up. If preparation fails, follow the repair guidance it displays. Someone operating the Gateway can disable dashboard serving while bots and existing connections continue. Re-enabling serving takes effect immediately. Changing where the dashboard is served requires a restart. A read-only configuration still allows inspection in the dashboard. Control UI
Find the first failing connection
If the page itself fails to load, start with service status, the address and port, and the Gateway credential. A port conflict, missing authentication, or invalid local mode can stop startup. If the page opens and a model call fails, check the agent's model selection and credential. For Ollama, test the model connection directly, then send another chat message to exercise workspace context and tool selection as well. When a later channel connection fails, use a live account probe and check its sender rules. Troubleshooting Ollama troubleshooting
Use diagnostic triage for read-only checks and a sanitized report. The report preparation excludes credentials, raw chat payloads, and raw logs. You can inspect the report yourself or choose an agent to help investigate. Doctor handles local diagnosis and offers repairs.
Change the model after setup
In Control UI Settings, open Models to connect OpenAI. Select the intended agent before adding a credential shared by that agent. Use Profile settings for a personal connection. A personal default can apply to new chats, and an existing chat retains its account selection. Adding or refreshing credentials normally preserves the primary model. Change the model explicitly when you want another choice.
An eligible official OpenAI route can use the bundled Codex runtime automatically. Custom endpoints and request adapters generally default to the OpenClaw runtime. Check the active choice if you depend on runtime-specific behavior. Native Codex sign-in and OpenClaw agent credentials are stored separately. Doctor can migrate old Codex model references and retain the intended runtime. OpenAI runtime selection
Ollama can discover other installed chat models after you connect it. Refresh the model list after downloading a new one, or limit the list to entries you configure yourself. A failed check retains the last successful inventory for that same connection. A successful check with zero results clears it. Repeating onboarding replaces the Ollama catalog, so preserve custom entries you want to keep.
Set the agent's primary model and list any fallbacks in the order you want them tried. Credential rotation can try another account for the same model. Model fallback moves to another model route. An explicit choice in a chat can require that exact route, so a failure can reach the chat directly. If a local Ollama endpoint is down, an isolated job that uses it can be skipped.
Work in a conversation
A session is one agent's ongoing conversation. It holds the history, model preferences, and context the agent can use on the next turn. The Gateway owns that state. The Control UI and connected chat channels get their views from it.
Pick the agent and working folder
Select the agent before starting a new chat. With several agents, Show all groups the sidebar conversations by agent. Automations and Usage also have single-agent and all-agent views. Each conversation still belongs to its own agent.
Use the command palette to find an existing session or start a background one. In Compose, enter the task and choose the agent and workspace. An attachment alone creates a draft. A rejected attachment can cancel a pending automatic start. The palette draft lasts for the current browser session, so save any text you need before reloading.
The workspace picker includes saved projects and recent folders. Its search uses the saved project catalog. For Git work, choose a branch or revision and start a separate worktree. If a saved workspace is unavailable, the agent falls back to its own workspace. The workspace you select for the job can supply project instructions while the agent keeps its own identity and memory. Sessions and sidebar
Answer, correct, or branch
When the agent asks a question, an answer control appears above the composer. Pick and submit an answer there. You can also skip the question or continue drafting a follow-up. A normal chat message is a separate input.
If a model rejected your last message and you want to change it, first send or clear any existing draft. Edit message puts the rejected message back in the composer. The revised chat uses a new branch, and you can still inspect the older one. Choose Try again to continue without sending the original input a second time. If the agent might already have done something outside the chat, verify what happened before repeating it. Changing a conversation branch only changes its history.
To explore another direction, open the session menu. New child session creates an empty conversation under the parent. Fork session carries over the parent's history. Both require write access to the parent. A session can get a title from its first task while work starts. Use the sidebar or chat header to rename a writable session.
Open Sessions to see a conversation's agent, model, history, and recent activity. The person who started the conversation and its current owner can differ. Reassigning a session or job changes responsibility. The creator retains the applicable rights over public links, sharing, archive, and restore. Publishing requires a separate action. Stopping or archiving affects the selected agent's session only. Session management
Find work again
Threads brings together conversations from the dashboard and chat channels. Snooze removes a thread from the active sidebar temporarily while messages and work can continue. Archive keeps a thread available for inspection or restoration under the applicable retention rules. Set a thread's own model or thinking level in its settings.
Channels is where you check account status. A slow check can leave the last status visible alongside a partial-result notice. Automations shows the next wake and the history of each job. If a job input appears in a chat, its link leads to the originating run. Memory shows the selected agent's dreaming status and diary. Subagents shows delegated work beside the parent. Control UI features
Recover a disconnected tab
While reconnecting, the browser may show older page data and keep drafts in memory. Once it reconnects, it can retry failed reads. Treat messages, approvals, and configuration changes as pending verification. These actions require your explicit retry if the first attempt never took effect.
A tab running the same dashboard build can usually reconnect after a restart. When a new build needs a reload, the dashboard protects unsaved work. A full reload can still lose drafts. Signing out, switching accounts or Gateways, or losing access clears the affected data and drafts. Help opens a public reporting form with a fixed template. Review what you enter. The form starts without attached chats, logs, or credentials. Reconnecting and recovery
Follow a message through the Gateway
On connection, the Gateway checks admission and sends a snapshot of health and presence. The client can then request work and subscribe to live updates. The Gateway acknowledges an accepted message with a run identifier. Progress and the final reply refer to that same run. An accepted run can keep working after your browser disconnects. Refresh the run or session to see where it ended. The live stream resumes with new events and can leave gaps for the time the browser was offline.
Clients supply a unique retry identifier for requests that can change state. If an input was accepted, another request with the same identifier can be acknowledged without adding another message or starting another reply. The Gateway rejects reuse of the identifier with different content or a different sender. Changes made later to messages in a channel leave the earlier stored transcript entry intact. Gateway architecture Gateway protocol
Work stays ordered within a session. Independent sessions can run at the same time if the Gateway has capacity. The runtime reserves the session turn before taking a global execution slot. A turn that loses ownership of its place in the transcript loses the ability to append results there. At the start of each attempt the runtime resolves the working folder, reads the skills snapshot, and chooses the model and credentials. It can reuse some prepared workspace and plugin settings across turns. Agent runtime Agent loop
Steer a run while it works
By default, a message sent during a run can steer that run. Work already started proceeds under its own rules. If the agent has begun executing a sequence of tool calls, your message can affect calls that have yet to start. A parallel batch runs together. Once the batch settles, the runtime checks for steering input before its next model request. Choose a follow-up or collection queue for input you want held until later. Choose interruption to stop the current run. Any effects already committed still need to be handled where they occurred. Command queue
The dashboard can stream agent text, tool activity, and run events. Channels have their own rules for sending completed chunks of a reply as separate updates. Block streaming is off by default at the agent level. A successful final message or reaction in the current conversation can complete a run. A progress update or an action in another destination leaves the current reply pending. Recording confirmed delivery helps avoid duplicate replies on retry.
Understand what the model sees
For each run, OpenClaw builds a system prompt with standing instructions, the current tools, workspace context, sandbox state, channel capabilities, and guidance from the model provider. The workspace can supply the agent's persona, relevant user context, and durable memory. A working directory selected for a project can add its own instructions. For example, a release worktree can tell the agent how to test that branch while its long-term memory stays with the agent.
The prompt tells the agent to act on requests it can carry out, continue until completion or a genuine blocker, verify the outcome, and handle existing files and credentials carefully. If work needs to happen later, arrange a schedule or a completion path. A child run's result still needs to be incorporated by whoever owns the overall request. Tool policy, sandboxing, approvals, and channel access provide enforcement. Treat instructions from outside content as untrusted. Prompt hardening helps distinguish those inputs from runtime instructions, while actual permissions control effects. System prompt
OpenClaw can reuse stable project and provider guidance while refreshing facts such as the clock, active work, available tools, sandbox state, and recalled memory. A newer snapshot supersedes the previous snapshot for the same scope. An empty snapshot can be accurate for its scope while work continues elsewhere. A change of route or profile, a reset, or compaction can start a new prompt sequence. Cached tool descriptions still go through current checks on every call.
The full prompt includes each applicable section. Subagents can get a smaller prompt that keeps essential tool, sandbox, workspace, and runtime guidance with fewer bootstrap details. A minimal mode supplies identity alone. The prompt includes short descriptions for eligible skills, and the agent can read full instructions as needed. It also points to local or public product documentation. Missing and truncated workspace files are identified, and shortened files remain intact on disk.
The model's context window has to hold all of this, plus history, tool results, the new input, and room for the answer. Context inspection estimates file sizes, tool overhead, and truncation. Compaction summarizes old conversation and pruning reduces old tool results in a request. Those two controls matter once a chat has been running for a while. Context inspection
Watch the model and tools take turns
The model can return a reply or ask to use a tool. The runtime validates the arguments and checks permission, sandbox, and any approval required by the call. It then returns the result to the model, which can act again or compose its answer. Text that looks like a tool call can prompt OpenClaw to ask for a corrected structured call. The call only executes through the tool interface. Failed tools need either a successful retry or an account of what failed. OpenClaw tools
A final reply, cancellation, or error closes the visible run. OpenClaw can continue retryable work without posting a final failure prematurely. When the context fills, it can compact and retry. If model output ends abruptly during tool work, tools already accepted can finish. Their recorded results can support a bounded continuation without executing completed actions again. Useful partial output and any failure each remain identifiable.
When tools finish and a reply is still owed, OpenClaw can ask the model to synthesize the recorded results. The reply should identify unresolved tool failures. A run that still cannot provide a required response sends a short failure notice. An external channel run can intentionally end silently when appropriate. The dashboard and other sessions that require an answer need a result or continued work.
Tell a slow run from a finished one
A wait can expire while the underlying run continues. If it is still active, wait on the same run identifier. Execution itself has an attempt budget, and a fallback model gets a fresh one. Time spent waiting for approvals pauses the unused attempt budget. Time spent waiting on a question to the user continues to count. Provider connection and progress limits are separate. For a slow local Ollama model, inspect the provider timeout before raising the overall budget.
Cancellation stops the run and revokes pending tool and approval authority. If a tool times out, inspect the system it was working on before repeating an action with side effects. Completed tool results remain in history. A terminal timeout is a failed turn, and continuing from it requires new input. Diagnostics can distinguish a long task from a stall by checking progress and ownership. The controller can request a stop for work that is semantically stuck. Transcript settlement and cleanup can continue after the visible run ends, with pending questions, tool calls, and children still attached to their owners until they settle or are cancelled.
Give the agent a workspace it can keep using
An agent's workspace is the starting folder for its file tools and the home of its instructions, skills, and notes. Credentials and active session history live separately in OpenClaw's state area. Plan to preserve both locations if you want to recover both files and conversations. A workspace also sets a starting point for tools. A host tool with permission to use an absolute path can reach beyond it. Set a session boundary or sandbox when the tool needs a restricted view. Agent workspace
Set up and verify the folder
Onboarding gives a single agent a default workspace. Named profiles and custom state locations can change that default. For several agents, give them distinct folders and verify each one in the Agents roster. An agent can inherit the shared base path. Pin the main agent to its existing folder if you plan to change the base without moving that agent.
Onboarding can fill in missing bootstrap files while preserving existing instructions. A new workspace can get one-time bootstrap instructions. Remove them once the agent finishes setting up. A completed initialization survives a restart. If an initialized workspace disappears, restore it or use the documented reset procedure. With a complete set of files you manage yourself, disable bootstrap creation. Pre-seeded or template-managed workspaces can skip it as well. To switch back to an older workspace, stop the Gateway, point the agent to that folder, use Doctor to review its old setup state, and restart.
A sandboxed session can have a separate working copy. Choose whether it sees the host workspace, and with which access. Host file tools confined to a workspace can use registered linked worktrees of that repository. On writes the host checks that registration and the resolved path. Link metadata copied from a different repository leaves that repository outside the boundary.
Put each instruction where the agent will look
In the Control UI, open the agent's settings and then Files. Put operating procedures and project conventions in the Agents file. The Soul file defines tone and boundaries. The Identity file tells the agent how it is named and how to present itself. The optional user profile describes stable preferences and useful current personal context. If you enable the boot hook, it can run a short startup checklist. Use workspace skills for repeatable project procedures.
The copy included in the prompt has its own size budget. A large file on disk can survive intact while only its beginning reaches the prompt. Put the important rules first and point the agent to supporting material it can read when needed. Optional files can be absent. If an edit exceeds the file editor's save limit, the editor rejects it before replacing the original.
Decide which facts should last
Treat the user profile as the current account of stable preferences. When a preference changes, update the profile and add any useful history to a dated note. Keep durable facts and decisions in the long-term memory file. Use daily notes for observations, detailed summaries, and work in progress. A fresh or reset conversation can load today's and yesterday's notes. The agent usually retrieves older material when it has a reason to look for it.
For example, the long-term note for a project could record that findings from a trial are available for a proposal and that rollout requires the owner's review. Include who made the decision and when it expires if those facts affect the next action. Enforce the review with permissions and approvals. Use an automation to start a check at a particular time. Keep private personal memory out of context shared with a group. Memory
If a note you expected is absent from the prompt, check whether it was shortened or excluded on provenance grounds. Context inspection shows truncation, and Doctor can explain a provenance exclusion. You can ask the agent to read a longer file directly if it has permission. To bring earlier notes over, open Import Memory, preview the detected Markdown, and pick a destination agent. A Codex import copies its consolidated notes to a separate searchable workspace area. Review conflicts before replacing a prior import. Memory provenance
Search for an old decision
Workspace notes are readable even if you have no search plugin. When a plugin is active, keyword search is good for exact names, phrases, or identifiers. Semantic search can find a related note that uses different words. Hybrid search uses both. OpenAI embeddings are the default. You can choose local Ollama embeddings independently of the chat model.
The built-in engine uses SQLite by default. A supported PostgreSQL setup can provide keyword and semantic search with the required extensions. The engines can rank results differently. If you want keyword search alone, select that mode and omit vector support. A rebuild refreshes the index from the existing source notes. Memory search
A search result pointing to a transcript is a reference to a conversation entry. Retrieve the permitted excerpt through the session-history tools. Session visibility still applies. Automatic recall has a short preparation budget and can skip a slow search. An explicit request can still retrieve it if access permits.
For a trusted personal agent, protected recall can bring in relevant excerpts from its other private conversations if the active memory provider supports it. Each session retains its own transcript. Group and channel conversations are excluded from supplying or receiving this private context by default. Session management
Review what gets promoted to long-term memory
Dreaming is a background process that scores recent signals from recall and checks where their material came from. It excludes untrusted and system-generated candidates. A qualified finding can add to what the agent knows or update an older fact. Open the Memory tab and inspect the dreaming diary to see what changed.
Historical backfill reads older daily notes and prepares entries in the diary for review. You can stage eligible findings and let the normal promotion process apply them later. Until then, the long-term file stays as it was. Backfill has its own rollback. Follow the memory instructions if you are migrating an older dreaming store. Dreaming and backfill
If you enable Memory Wiki, it compiles a separate collection of claims and sources you can browse in the dashboard. Look there for stale statements or contradictions. Recall and promotion still belong to the active memory engine. Memory Wiki
Memory Core creates new long-term memory and dreaming reports with private permissions by default. You can give a trusted local group limited read or write access to selected new reports. Directory permissions and the process's permission mask still apply. Existing reports retain their existing permissions. Daily notes and the session corpus stay private under this setting.
Back up the files and conversation state
Use a private Git repository for workspace instructions and memory you want to recover. Review the files before the first commit, especially if you are adopting an older workspace. Keep credentials, personal exports, and sensitive chat material outside the repository. OpenClaw may need a damaged repository or incomplete worktree registration repaired before it can use it safely.
To move the agent, restore or clone the workspace on the new host, select it, and verify its location in the roster. If the conversations matter, restore the corresponding agent database too. Handle older transcript archives separately where needed. Confirm what you need from the old location before retiring it. Session storage and migration
Keep long conversations useful
A session can run for months while the model sees only the context that fits in one request. The Gateway stores history separately from the working view passed to the model. You can choose when a conversation resets, summarize part of it with compaction, or start a temporary chat with different retention.
Reset a conversation on purpose
A session normally continues until it is reset. You can set a reset hour, a period of inactivity, or both. A new message goes into a fresh session once the first applicable deadline passes. Only genuine user activity extends the idle clock. Service events and jobs can run while that clock continues. Direct messages, groups, and threads can use different lifetimes. Session management
Open an incognito thread
Turn on Incognito before starting a new thread. The Gateway keeps its session, transcript, and compaction state in memory. It expires after twenty-four hours or on Gateway restart, whichever comes first. Activity leaves the expiry deadline fixed. Expiry stops work, skips the automatic memory flush, and leaves no session archive.
The model provider still receives the input. An explicit file write or a tool call can leave a record, and live activity remains visible to operators. Uploads, approvals, and configured diagnostics have their own storage rules. The Codex runtime writes submitted messages to its diagnostic database even for a temporary session thread. Select the OpenClaw runtime if you need to avoid that Codex record. Incognito sessions
Make room without losing the thread
As the context window fills, OpenClaw can store a summary of older turns and keep recent messages in full. This is compaction. The saved transcript remains on disk. The dashboard can show a Context compacted divider with the number of tokens saved and the percentage reduction.
When choosing a split, OpenClaw keeps tool calls paired with their results. The summary can build on an earlier summary and favors the current request, recent conversation, and important identifiers. It may sample older material and shorten long tool results. Middle details can drop out of the model's current view while remaining available in history. Safeguard mode is the default for new configurations. It checks the summary for structure, pending requests, and exact identifiers, and tries to correct problems. If details still cannot fit, OpenClaw may keep a reduced summary with a warning. Give the agent any essential detail that did not survive.
If summarization fails, OpenClaw normally keeps the history as it was and reports the failure. In some recoveries it can continue from recent history alone. A timeout during automatic compaction can trigger a deterministic reduction that keeps recent messages, complete tool pairs, pending input, and the previous summary. Older unsummarized details then drop out of the request. Compaction
Automatic compaction can run near the context limit or after a recognized overflow. OpenClaw also checks whether new tool results will fit before making another model request. Completed tools can carry their recorded results into recovery. If a request still exceeds the window, shorten the input, start a new conversation, or use a model with a larger window. Manual compaction in supported chats can focus a summary on a particular topic, such as the decisions reached during a design discussion. It reports failure if it cannot make a valid summary. The amount of recent history it keeps depends on the room left after instructions, tools, input, and the output reserve.
Pruning reduces older tool results in the request temporarily. Compaction stores a summary in the transcript. If large results keep filling a session, inspect what the model is receiving and consider pruning them. A fresh conversation clears the active conversation history. Fixed instructions and tool definitions still take space. If those alone fill the window, trim what is injected or choose a larger window.
Preserve a decision before the summary replaces its details
Before compaction, a quiet memory flush can ask the agent to write durable facts to a daily note. Memory Core requires a writable workspace. Session or sandbox policy that disallows writing causes the file flush to be skipped. A memory plugin with its own authorized persistence tool can use that instead.
A file flush appends new material. It rejects a replay of the whole note or a copy of an existing paragraph. A failed optional flush still allows compaction. The flush uses the session model and its fallbacks. Use a local model and local fallbacks if the extracted material must stay on your machine. Check the daily note when you need to confirm what the flush kept. Memory
Tune how much history goes to the model
By default the session model makes the summary. If you choose a dedicated summarizer, including a local Ollama model, that exact selection applies without the session's fallback chain. A larger summarizer may handle more history, and the chat model still has its original context limit. A longer summary can carry more detail at the cost of space on later requests. Strict identifier preservation is on by default. A degraded summary can still omit an identifier when it does not fit. Routine compaction notices are optional. Degradation produces a warning even when you turn those notices off.
A transcript size guard can trigger compaction before a run. If the selected history is still too large, OpenClaw can omit older complete turns from the temporary view while preserving the current request and complete tool pairs. A separate history loading limit can also leave old material out of that view. Both leave saved history on disk. Use manual compaction when you need a summary that accounts for the meaning of older material.
Eligible direct OpenAI Responses routes can use the provider's compaction endpoint. The provider decides what context to keep, and that context consumes the prompt budget. OpenClaw uses its own summarizer if the endpoint fails or its result is unusable, and also handles a focused manual request itself. A plugin can supply a custom compaction provider. OpenClaw preserves recent context and falls back to the built-in safeguard summarizer if the custom provider fails or returns nothing. Custom output bypasses the built-in summary quality audit.
Recover work after a restart
During a graceful restart, the Gateway can record which root sessions had active work. After startup, an eligible root can look at what completed and decide how to continue. A crash may also leave sufficient durable run identity to recover. Child runs depend on the parent to inspect their state and decide what to delegate again. Scheduled jobs and external harnesses recover according to their own lifecycles.
Recovery checks current ownership, permissions, and tool policy. Removed sessions or revoked access prevent resumption. A queued message already accepted by the Gateway keeps its original sender's authority and is revalidated before running. Check the actual effect of a previous send or write before repeating it. A settled transcript after restart can still leave the external outcome uncertain.
Keep history you will need later
Active history lives in each agent's database. If startup reports a legacy store, stop the Gateway, back up its state, and use Doctor to migrate. Restart after the migration finishes. Keep older archives and imports separately if the migration calls for it. Session storage and migration
Maintenance can archive inactive dashboard chats and remove disposable scheduled or delegated records. Pinned sessions, active runs, and sessions with durable external references can qualify for protection. A dashboard conversation can be archived after seven inactive days. Many other durable sessions use thirty days. Check the actual retention for any thread you will need later. An archive created to reclaim capacity can normally be searched and restored, but may be eligible for deletion under disk pressure. Manual archives can have different protections. Preview maintenance before enforcing it, and export important material. Session maintenance
Set the boundaries before you share the agent
Start with the people who can connect and the actions they can trigger. The Gateway owns credentials, channel connections, and authorization. Operator devices, channel senders, and agents each reach it under their own access rules. A typical Linux installation binds to the local machine and requires a working authentication method before listening on a wider network. The trust boundary
An admitted message can still face several independent checks before a tool acts. Sandbox settings decide where tools run and which files they see. Tool policy decides which operations the model can call. Session permission mode sets the working root and review posture. Exec approvals govern individual commands on the target machine. Check each layer when testing what a particular session can do.
Choose where tools run
A shell command can run on the Gateway, in a sandbox, or on a paired node. The default assumes one trusted operator. Sandboxing is off and exec can run on the Gateway host without prompts. Choose isolation and approval settings before adding people or allowing actions with side effects.
Sandbox mode can leave sessions on the host, isolate non-main sessions such as groups and channels, or isolate every session. Set whether a sandbox has no host workspace access, read-only access, or read-write access. A creator role can require a sandbox regardless of the agent's ordinary mode. A run that requires a sandbox fails if one cannot start. An already sandboxed run rejects a per-call request to move to the host.
The default Docker or Podman sandbox on Linux runs as a non-root user with a read-only root filesystem and no network. Other supported backends can enforce different boundaries. A bind mount exposes a chosen host path inside the sandbox. Use read-only mode when a source or secret only needs to be read. A mount without a mode defaults to read-write. Shared sandbox scope uses global binds. OpenClaw checks the requested path and its resolved location, including parent links, and keeps protections for credentials and system paths even where other mount paths are allowed. Mount permissions and workspace access are independent. Giving the container the Docker socket effectively gives it control of the host. Sandbox, tool policy, and elevation
A paired node declares the capabilities it offers. The Gateway checks authorization before it sends work. A node that hosts sessions receives a sealed worker artifact and verifies its hash on download and reuse. Opening that session uses the artifact without package installs or lifecycle scripts. The node can enforce a separate container for each session. Inspect command approvals on the actual execution machine. Gateway architecture
Enable the operations the agent needs
Global and per-agent tool profiles, provider profiles, allow and deny rules, and sandbox policy all affect the callable tool set. A denial wins. A nonempty allowlist exposes only named tools from that list, subject to the other gates. Rules can target a provider or a specific model. A tool denied by policy stays unavailable even if a workspace instruction tells the agent to use it.
If you want a session to be able to read files without changing them, check both file tools and runtime tools. A shell with write permission can edit files even when the direct editing tool is disabled. Use the sandbox or host boundary to enforce file access. Tool policy governs calls to the shell tool. The execution environment governs what the shell can do once it runs.
Tool groups can cover runtime, files, sessions, memory, web, messaging, and plugins. The OpenClaw group omits low-level filesystem and runtime tools and provider plugins. The plugins group includes loaded plugin tools, including MCP tools. MCP tools in a sandbox also need to pass the sandbox tool allow gate. You can allow the bundle, plugin group, or relevant server tools there. Reload and inspect the visible tools. Doctor checks managed MCP server names, and Gateway logs show which policy removed or blocked a tool. Doctor's managed list can omit bundled sources.
Use the sandbox inspector for an actual session or agent to see sandbox scope, workspace access, rule sources, and elevation gates. Use the security audit to find unexpected settings. Elevated execution applies to the shell tool. Ordinary elevation is still subject to approvals. Full elevation skips execution approvals for that session. Neither can override tool policy or a sandbox required by the creator. When a command already runs directly, elevation usually has no effect. It cannot select an arbitrary host, and preserves a node target only if the node was already selected. Global and per-agent settings and sender allowlists govern who can request it. Security audit
Set a session permission mode
The session root is normally the working directory you selected or the whole checkout for a managed worktree. A nested working directory in a worktree still uses the checkout boundary. An agent workspace supplies the root when the session has none of its own. Managed file tools reject a path that resolves outside a restricted root, including a link that leads out of it.
Use Read only for a session that may inspect files within the root. This mode blocks managed writes and command execution. Ask me permits reads and writes within the root and sends commands that need escalation to a human. Auto-review uses an automated reviewer for eligible commands, which can approve, deny, or ask a human. Full access allows unrestricted filesystem access and ordinary command execution without a reviewer, subject to independent restrictions. Only an administrator can select Full access. Native runtimes can add their own controls.
With Agent default, the configured file and command policies apply independently. The UI can show a resolved named mode if the current settings happen to match one. Choosing Agent default removes any override. You can set a creation-time default for new attended sessions. Existing sessions retain their settings, and Full access still requires current administrator authority. Selecting a worktree alone only establishes the root.
Change Permissions in the composer when you need a different mode. In the OpenClaw runtime, the new mode applies to subsequent calls and cancels pending approvals under the old mode. A completed write or a command already running can still have its effects. If an active runtime cannot change modes mid-run, stop the task, change the mode, and continue in the same session. Session permission modes
Keep administrative decisions with the operator
When an agent requests a persistent administrative change, the Gateway checks the requesting run's effective authority. Restricted or uncertain authority usually requires a human unless an independent grant applies. An operator can give a standing delegation grant or require human review even in Full access. Some such grants allow configuration changes that enable code execution on the host. Expanding one requires an administrator or approval for the specific expansion. Child runs retain inherited restrictions, and the requesting agent cannot approve its own increase.
Use the dashboard or an available native channel approval control. An ordinary chat reply is a message and carries no approval. A one-time approval covers the proposed change alone. Stopping the run cancels its pending approval. The Gateway checks authority again before a persistent effect. If a reviewer denies an operation, use the reason to find a materially safer approach or ask the user. Some operations always require a human. Approval-bound commands are checked again before launch.
Review a shell command on its execution machine
Open Devices and then Command approvals. Select the Gateway or compatible node and the applicable agent or defaults. Deny blocks host commands. Allowlist runs matching commands. Ask can send a command outside the allowlist to a human. Auto can send eligible misses to an automated reviewer, which can approve, deny, or escalate. Full permits ordinary execution without a prompt. Stricter target policy or independent strict review can still require a decision. If required review times out or cannot be delivered, the fallback normally denies the run.
Use an allowlist rule only as broad as the work requires. A broad program rule can allow commands beyond the scope of an argument-specific rule. In a shell chain, each top-level command must pass. Use the execution reference when writing argument matches. The approval inspector lets you compare requested and effective policy. The target still checks the call at execution time. The process runs under the operating system and sandbox permissions it starts with. Exec Exec approvals
Read the agent, host, command, and working directory on the approval card. Allow once covers the pending call. A durable approval should match a scope you intend to repeat. Always allow here binds the approved arguments and working directory. A different working directory needs a separate decision. The target rechecks policy and executable identity before launch. Cancellation, an executable change, an expired handoff, or a consumed one-time approval can prevent execution. Approval administration
Put credentials in Secrets and connect them to their consumers
In Settings, open Secrets. Choose Protected for a write-only value used by a supported secret reference or a Gateway outbound request pinned to its destination. Use Agent-readable environment only when a host command needs the value and the agent is allowed to expose or persist it. Then select the reference in the field that consumes the credential. The provider appearing in a picker means it can be selected. Verify that the named value actually exists. Supported references can also use the environment, a file, or an executable. Executable providers can have side effects and need deliberate permission to resolve.
References reduce exposure through ordinary configuration files. The Gateway still has the secret in memory when it needs it, even if disclosure to a provider waits until the outgoing request. Check other readable copies and paths. Tool outputs and transcripts can preserve values read from files. If a credential surface cannot use references, operating-system isolation or an external credential proxy may be needed.
Audit before and after converting settings. Use preflight checks to validate references before applying them. Check authentication stores, environment files, generated files, backups, and other copies as well as configuration. A completed migration requires both a clean audit and handling the remaining plaintext copies.
The Gateway resolves active references into an in-memory snapshot at startup and reload. After rotating a credential in its source, reload secrets and test the affected account or provider. Gateway authentication failures or invalid references can stop startup. An isolated account failure can leave the rest of the Gateway running. During reload, an unchanged eligible account may temporarily retain its last good value. A strict failure preserves the active snapshot. Doctor and status show degraded owners without showing their credentials. Restore the secret at its source, reload, and verify that account directly. Secrets management Secrets runtime Secrets operations
Connect a chat channel and route its messages
A channel connects a service to the Gateway. An account is a login on that service, an agent is the worker assigned to it, and a session is the conversation context the worker receives. Several channels and accounts can use one Gateway. Dashboard chat uses the internal WebChat channel. A single Gateway should own a given WhatsApp connection on a host. Chat channels
Set up a channel for one person first
For Telegram, add a bot account using its token during onboarding or in the channel setup tools. The Telegram plugin is bundled. WhatsApp uses QR pairing. Set sender access before sharing the bot. Configure direct-message pairing or an allowlist and decide which group messages need a mention. A multi-person direct message in Slack is treated as a group. Supported channels may also prevent loops where bots answer one another indefinitely.
Run a live channel probe and send a test message from an allowed sender. The probe checks the account. The message checks admission, agent selection, and delivery. If WebChat works but the channel fails, check the channel account, sender and group rules, binding, and delivery log. Telegram setup Channel routing
Give separate conversations separate context
Direct messages normally share an agent's main session across channels. That works for one trusted person. With several senders, scope direct messages by channel and sender. Include the account as well if several logins share the channel. When one person intentionally shares context across channels, you can link their identities. Verify isolation with the security audit. External inputs keep their own runtime identity for tool and sandbox rules even if they share history.
A room normally has its own session. Threads and forum topics can have more specific context. You can bind a group into the main session deliberately. Its mentions and reply destination still follow the originating room. Use an intentional default for outbound requests without an account when several accounts are available. Two agents can use the same session key and still have separate histories and work. Direct-message isolation
Give a second agent its own job
For example, use a personal agent and a project reviewer. In Agents, create or inspect each agent and set its workspace, primary model, and ordered fallbacks. Keep authentication and conversation state in separate directories. Pin the main agent's workspace before changing shared defaults if you need to keep its current location. An agent can inherit a shared authentication profile. Under the documented rules, it can use the inheritance owner's matching credential for renewal. To give an agent its own model identity, connect a separate account from that agent. Use the supported profile mechanism for copying credentials and treat refresh tokens as belonging to their owner.
Give an agent its own skill allowlist if it needs a different selection. A per-agent selection replaces the shared default. Tool policy still applies to the actions those skills use. Configure plugin storage separately if you need plugin data kept apart, such as separate Memory Wiki vaults.
Separate workspaces and histories help organize the jobs. Cross-agent session access can still be available by default. Limit which agents can reach each other and which conversations they can inspect, including access to a delegated child. The normal memory engine searches its own agent's transcript corpus. Share a reference folder deliberately if both agents should retrieve it. Returned transcript excerpts can carry sensitive information even when they omit internal tool detail. For a stronger separation between operators or workloads, use a separate Gateway. Multi-agent routing
Route each account or room
Connect the account first and keep the sender allowlist and credentials specific to that account. Then add a binding and verify it with a message. You might send the personal WhatsApp account to the personal agent, then add a narrower rule for one project group to reach the reviewer. The group rule wins and replies still use the originating account.
A conversation rule takes precedence over an account rule, which takes precedence over a broad channel rule. All conditions must match. At the same precedence, the first matching binding wins. Thread routing can inherit from the parent conversation. Other cases such as wildcards and platform roles have their own positions in the full precedence order. By default, a binding with a channel and no account means the default account. Use an explicit channel-wide binding when you intend to cover every account.
With multiple agents, an unbound message needs an eligible fallback owner such as the system agent. Some adapters retry temporarily, so check account status and bindings together. Broadcast settings can send an admitted group message to several agents deliberately. Channel access still applies and explicitly bound ACP sessions stay exclusive. When migrating older implicit owners, use Doctor to create explicit bindings and retest every account. An unresolved account can stay blocked while the rest of the Gateway continues. Reconcile its workspace instructions and memory if its older workspaces diverged. Binding precedence
Check where the reply went
Replies normally go back to the conversation that sent the message. A WebChat turn and its background completions stay in WebChat unless an external route is chosen explicitly. A previously saved external destination does not replace the current one. A failed or suppressed send does not establish a new route. A confirmed partial send can establish a route even if the full reply failed. Read the delivery result separately from account connectivity.
Some channels can introduce the bot when it joins an allowed room. The introduction uses available room context and respects access rules. You can disable it for supported channels or accounts.
Keep the Linux Gateway running
Once the browser and channel both work, keep a known-good way to inspect the service, understand config changes, and recover access. If several connections fail at once, check their common Gateway before diagnosing each connection separately.
Run it under the right service account
A systemd user service can survive logout if lingering is enabled for its account. On a headless host it also needs a working user service manager and user message bus. If it fails to start, check service status and logs. If you intentionally run it as a system service, use the non-root account that owns its state and configuration. Run Doctor as that same account with the same state and configuration paths. Keep one supervisor for the profile and port to avoid competing services.
For deliberate isolation or a rescue Gateway, give each instance its own port, configuration, state, and workspace. The runbook calls for at least 120 ports between base ports to keep their related ports from overlapping. Several URLs can still point to one Gateway. To check whether you reached the intended instance, inspect the address and credentials as well as the service's health. Gateway runbook
Change a setting and check that it took effect
Open Config in the dashboard. The form uses the active schema, including the schemas from enabled plugins and channels. Common settings appear first. Search can also find advanced fields, and a raw editor is available. Advanced marks where a field appears in the form. Global defaults and supported per-agent overrides let you keep common behavior in one place while changing a model or workspace for a particular job. Onboarding and the configuration wizard help with initial setup. The Gateway also has defaults for when no configuration file exists. Gateway configuration Configuration reference
The Gateway watches the active file and normally uses hybrid reload. Some changes apply live. Others trigger a restart. If you change the service port, update the installed service definition too. A file being written must be a regular file. If you use a separate path, point the Gateway at the real file directly.
The entire configuration must validate. Unknown fields, wrong types, and bad values can prevent startup. A failed reload leaves the last accepted configuration running. After a successful startup, the Gateway keeps a trusted recovery copy for explicit repair or restore through Doctor. Automatic migration writes only a fully valid result, and may exclude newer or externally managed settings. OpenClaw can reject changes that look like an accidental loss of large parts of the file and retain that proposal separately for inspection. Protect any recovery copies as carefully as the active file.
If startup stops, read the diagnostics before restarting again. A bad configuration needs repair. An unresolved workspace recovery problem can also stop startup after its retries. Use Doctor and the service logs to find the underlying cause.
Know what survives sleep and shutdown
A shared scheduler coordinates jobs and maintenance. Each feature keeps the records it needs to reconstruct deadlines after restart. After sleep, due work can wake once and periodic work waits for its previous invocation to finish. Missed ticks can be combined to avoid a burst of identical runs.
On shutdown the Gateway stops accepting new work, cancels pending wakeups, and waits within its shutdown budget for active callbacks and tracked work. A plugin can use a scheduler owned by a service or channel account. The host closes that lifetime on retirement. The plugin controls the order in which it closes connections and flushes its data. Gateway lifecycle
Teach the agent a repeatable procedure
A tool performs an operation. A skill tells the agent when and how to use tools for a particular task. If your project has a regular release check, a skill can tell the agent which files to inspect, which checks to run, and how to report a failure. Its tools still need to be allowed by policy.
Create and try a workspace skill
In the workspace skills area, make a folder and give it a lowercase name made of letters, digits, and hyphens. Add the skill's Markdown instruction file, named SKILL.md. Match the declared skill name to the folder and give it a short description. Tell the agent when to use it, what to inspect, and what to do if a step fails. Refer to supporting files through the skill's base directory so the procedure can move to a different machine. Keep untrusted input from becoming shell commands.
Check the skills list for discovery, then ask the agent to do the task. File watching normally picks up edits. If it is off or your chat has an older view, start a new chat or restart the Gateway. Check skill eligibility when it is discovered but unavailable. A skill can require executables, environment variables, settings, or a supported operating system. It can identify a primary credential and provide installation guidance. Set credentials through a supported secret mechanism. Environment provided on the host may be unavailable in a sandbox. Creating skills Skills and requirements
Choose how the agent gets to the skill
In the dashboard composer, type the dollar sign and pick the skill. One message can reference up to eight distinct eligible skills that users are allowed to invoke. The agent is directed to read each. Hidden references and additional ones produce an error. Channel slash commands can expand to agent instructions or, when configured, dispatch straight to a tool. A skill can remain available to a user who selects it explicitly while being excluded from automatic model invocation. A plugin's skills require the plugin to be enabled and still have their own prerequisites.
An agent's allowlist controls which skills appear in the prompt or command picker, sync into sandboxes, and enter snapshots. If the shared default is omitted, visibility is unrestricted. If an agent omits its setting, it inherits the default. An empty selection explicitly shows none, and an agent selection replaces the shared one. Shell access to files and programs has its own controls. Use sandboxing, operating-system isolation, command policies, and resource credentials when you need to restrict that access.
Find which copy the Gateway picked
Start with the skill list and the command-line skill check. For a name that appears in several places, the agent's workspace wins. Its regular skills folder comes before its dot-agents folder. For the default state directory, the user's dot-agents folder comes next, followed by managed state skills, the agent's Workshop skills, and bundled skills. Extra directories and plugin skills come last. Plugin-provided learned skills can sit between managed and bundled entries. The Custodian library receives bundled precedence for its configured agent. Personal library skills are chosen by identity and revision.
Managed state skills are shared by agents using that state. Workshop skills belong to an individual agent. A nondefault state directory omits home-scoped personal and compatibility roots. Codex keeps native skills in a separate location. OpenClaw offers a migration plan and a copy operation to put those skills in a supported workspace.
Discovery descends up to six levels through grouped directories and stops when it finds a skill instruction file. The declared name determines the command, with the directory name as a fallback. Invalid files are skipped with diagnostics. Collisions with different content are reported, including a workspace override of a bundled skill.
When a run uses a different workspace, its skills follow the agent's catalog in precedence. The run's regular skills folder wins over its dot-agents folder. Both can sync to a sandbox. A managed worktree uses its recorded source workspace. Selecting the worktree as the agent's own workspace changes the precedence. Discovery stays within its selected roots, and sandbox copies are reconciled when source files change or disappear.
A connected headless node can publish its own skills. If one shares a name with a local skill, the local name is kept and the node skill gets a stable prefixed name. Its files and programs stay on the node, so target the node when executing it. Restart its host after changing its skill files.
Install, update, or share a skill
You can install from ClawHub, a Git repository, a local folder, or another supported source. The usual destination is the workspace. A shared managed destination is also available. Tracked ClawHub installations can update in place. Refresh Git and local installs by reinstalling them. Check the trust and scan details, read third-party instructions, and use an owner-qualified name if the name is ambiguous.
An administrator has to enable private archive uploads. A trusted local installation policy can examine staged content before an install or update. A missing or invalid decision blocks the installation. Workspace and extra roots check resolved paths unless an administrator has trusted a specific symlink target. Workshop links stay inside their directory. Managed and personal skills can use linked folders with the instruction file resolving inside the skill directory.
In a signed-in Gateway profile, open Plugins, then Skills, then My skills to create, import, or install a personal library skill. A shared token carries no individual profile identity. A managed skill initially belongs to its creator. Share with team lets others use the skill. Editing stays with its owner. Transfer to team changes management ownership while preserving the author. Both preserve the stable skill identity. A shared Gateway is one trust domain. Treat delivered skill content as session input and store secrets through a credential mechanism.
A save creates an immutable revision when the instructions, bundled files, paths, sizes, or executable flags change. Identical saves have no effect. An edit made from an older revision can conflict. A session pins its attached revision through restarts and ownership changes. New sessions see published edits. Attach or refresh the skill to use the new version in an existing chat. Rollback selects a retained revision. Removing a skill stops new selections and preserves pinned revisions. Disabling it removes it from new-session defaults and still permits explicit attachment.
A new session can select up to 64 enabled library skills, with personal skills first. Allowlists and prerequisites still apply. Bundle limits can exclude supporting files with a notice. The instructions are delivered whole when they fit, or the session receives an explicit notice that they are unavailable. Use the library editor or authorized tools to manage revisions. An authorized agent can help create or improve a personal skill through the library service.
In Skill Workshop, inspect the history of a learned skill. You can archive it with a reason and restore it later. Before publishing a skill yourself, complete its name, description, requirements, and homepage if applicable. Test locally, check for an existing ClawHub solution, and sign in to the ClawHub command line. Publish under a personal or organization owner with the required rights. ClawHub publishing
Connect outside tools with MCP
Model Context Protocol, or MCP, is a way to connect an outside tool server. A server can expose tools, resources, and prompts. Once connected, each tool still needs to pass agent, session, and sandbox policy. OpenClaw can also act as a server and expose its own channel conversations to another MCP client. MCP guide
Add a server, then prove it is reachable
In Settings, open MCP and choose Add server under Configured servers. Give it a unique name. Choose Streamable HTTP, Server-Sent Events, or standard input and output. An HTTP transport takes a server address and HTTP settings. A local standard-input server takes an executable, arguments, and a working directory. Use one transport per definition. The editor rejects new or modified mixed definitions. Legacy mixed definitions retain their old behavior with a warning until repaired.
In the editor you can set credentials, authentication, timeouts, parallel-call hints, and tool filters. Store sensitive headers and environment values through supported secret mechanisms. You can disable a definition without deleting it.
An administrator can also open Plus in the composer, then Plugins and Add MCP server. This session enables the server in the current session. Everywhere enables it globally. Both save a global definition. To inspect or deny individual tools for the current session, open Plus, then Plugins and Tool access. A denial applies before the next turn.
After saving, run the MCP diagnostic with a live probe and check the server's capabilities. For HTTP OAuth, sign in when prompted, confirm in the browser, and send another message afterward. Directly exposed tools can have server initialization instructions in the system prompt. For deferred tools, discovery can direct the agent to read further instructions from the tool description. OpenClaw limits embedded instructions per server and marks truncation. Optional MCP Apps supply sandboxed views and plugin extensions. Interface enablement and permission checks still apply.
Set the review posture for Codex calls
Full permission normally allows MCP calls without a prompt. Stricter Codex session modes check tools without safety annotations and can use automatic review or ask the user. When available, Allow Always covers the exact agent, server, and tool regardless of arguments. It applies to Gateway-hosted Codex calls that the Gateway can match unambiguously. Ambiguous calls retain native or session behavior. Codex apps, native plugin servers, and computer-use servers use their own approval behavior.
A server can override the posture. Automatic mode can use a saved grant. Prompt mode keeps asking. Saved grants survive restarts and take effect on the next thread configuration and hook registration. The current session uses Codex's remembered choice. Follow the MCP guide to inspect or revoke a grant.
Recover a changed or failing connection
When Gateway hot reload changes or removes a server, it retires the old connection immediately. New definitions appear for discovery on the next turn. Unchanged servers retain connections and caches. A crashed server can still show its last successful catalog while recovery runs. Its tools become executable again on recovery, and a successful listing replaces the catalog. Configuration changes and plugin reloads retire the affected runtime.
Startup failure backoff starts at thirty seconds and can reach ten minutes. Retries continue in the background, and recovered tools appear at the next turn boundary. A successful connection, configuration publication, or explicit reload clears the backoff. Reload the process that actually owns the connection. For an OAuth failure, change the affected credential or definition, or explicitly reload. A change to someone else's credential does not clear it.
Legacy Server-Sent Events can preserve a session at the same endpoint. A new endpoint requires fresh initialization. Local HTTP cleanup can succeed without confirmation from the server, leaving the remote session to expire. If local cleanup fails, replacement is blocked.
If a tool is missing, use the live probe and inspect include and exclude filters. For a local server, test executable resolution in the Gateway's environment and check its arguments and working folder. Standard error is drained and kept out of normal logs because it can contain private content. Startup errors still have diagnostics. Successful structured tool results are checked against the server's output schema. Error results carry the error content the agent needs for recovery.
Sign in on the Gateway that owns the server
For an enabled HTTP server with shared native OAuth credentials, an administrator can select Sign in in Settings. Authentication saved means that the selected Gateway stored the credential. Run a probe afterward to confirm that the server accepts it. Changing Gateway or agent closes the dialog. A restart ends unfinished sign-in.
Use Settings on the Gateway's secure address, local loopback, or published Tailscale address so the browser callback can return. A separately hosted UI cannot receive that callback. Other identity mappings have their own sign-in paths. You can also use the command-line login on the installation that owns the connection. If a redirect cannot reach the Gateway, the original direct chat or login flow can accept the complete failed redirect. Preserve its state and issuer information as described in the MCP guide.
For a plugin-declared server, sign out from the plugin's Accounts page. Uninstalling the plugin removes its saved sign-ins. Standalone server definitions retain their own credentials.
Give the model a manageable tool catalog
With a short catalog, the model can see full descriptions of tools on every request. As the catalog grows, OpenClaw can defer some descriptions with Tool Search. Code Mode can also coordinate calls in a short program. Both operate on tools already admitted by policy.
Let the model find a tool when it needs one
Tool Search is experimental. OpenClaw normally selects structured Tool Search for embedded runs when no choice is configured. Direct descriptions are still available as a setting. When Code Mode is engaged, it takes precedence. On native Ollama transport, common web and memory tools normally remain directly visible and other optional ones can be deferred. An explicit setting overrides that default.
The Gateway first applies agent, sandbox, session, channel, and provider policy. It assembles eligible built-in, plugin, MCP, and client tools. The model can search by task or exact name, read full input requirements, and request a call. Ranking uses words in trusted tool metadata. Untrusted MCP and client parameter descriptions are omitted from that index. Calls still pass validation, policy, approvals, hooks, and logging. The agent reads a skill's instructions through the skills mechanism.
You can choose which eligible descriptions to defer by source, registered name, or both. Exclusions take precedence. Core and required tools retain the visibility required by the mode. In directory mode, common coding and client tools also stay direct. A server has to connect and list tools successfully for the current turn. Client tools stay searchable. When the bounded MCP directory fills, OpenClaw first removes descriptions, then summarizes names by server and points the model to search. Treat server descriptions as untrusted input.
A large network result can be omitted when it exceeds the tool-result budget. For a read-only call, ask for a smaller page from the same starting point. For a call with effects, check what it did before deciding how to retrieve its result.
Compare request size, latency, and session activity if you want to measure whether discovery pays for itself. With a short tool list, the extra discovery calls can cost more than the context they save. Older configurations may need the documented Tool Search migration before the Gateway starts. Tool Search
Coordinate several calls with Code Mode
OpenClaw Code Mode is experimental. It gives the model a compact JavaScript execution interface and a bounded index for finding tools. A model can discover a calendar-reading tool, inspect its requirements, fetch a bounded date range, and combine the results. The program can run independent reads together and wait for earlier results before issuing dependent calls. Search MCP tools through their namespace and request full descriptions when the compact hints are insufficient.
Find the global setting in Settings, then Agents & Tools, Labs, and Code Mode. Automatic mode engages only for preferred models. Agent and model overrides can supersede the global setting. If the chosen executor is unavailable, the run fails. The default Node executor uses a worker thread outside the main event loop and is intended for trusted execution. Use the bundled QuickJS executor for hardened guest isolation. Both call tools through the Gateway bridge. File and shell actions need authorized tools, and each nested call follows normal authentication, approval, channel, hook, and logging checks. Some tools remain available directly because their results cannot cross the bridge. Codex has its own feature with a similar name. OpenClaw Code Mode
When the outer result says the Code Mode run is waiting, use its run identity to wait for that work. If a finished program returns a background shell process, use that process identity with process control. A persistent task session has its own lifecycle and does not produce a delegated-child completion event.
Try direct descriptions for a small catalog or a model that struggles to compose short programs. Tool Search offers structured discovery and dispatch on its own. Code Mode is useful when several tools need to exchange data or produce one combined result.
Give part of a job to another agent
A subagent is a background run started by a parent agent. It gets its own session and context and normally reports back to the parent. Use one for a distinct piece of research, an independent review, or other work the parent can check before replying. Each child has a token cost. It can use a less expensive model, and depth and child limits bound how much work can be delegated. Subagents
Assign a concrete deliverable
Give a child the result it needs to produce and the relevant constraints. An isolated child starts from that assignment. A same-agent fork carries the current user turn and completed tool results. Thread-bound children normally fork by default.
A same-agent child usually gets the parent's model unless there is a configured default or explicit choice. A child assigned to a different agent normally uses that agent's model and authentication order. The requester's personal account choice stays with the requester's run. The child can inherit a sandbox or be required to use one. Set a timeout when the assignment has a deadline. Subagent tool reference Nesting rules
A team template can create a coordinator and specialists with their own roles and workspaces. For example, the coordinator can send an evidence question to a researcher and a draft change to a reviewer, then check both results. If only the coordinator should delegate, allow it to spawn the intended specialists. The team preset sets up that structure. Its preference for delegation guides the model, and tool policy still controls what anyone can call. Job scheduling and channel ownership are configured separately. Multi-agent routing
Follow the result back to its owner
From the parent chat, open Subagents and select a running or completed task. Its title identifies the assignment, and you can read its view-only transcript beside the parent. An open child offers Open parent session. Stop is available when the run is stoppable and your session access permits it.
An ordinary hidden helper returns through its parent. Eligible hidden completions can go to the parent privately, without automatic delivery to the channel. A visible persistent child stays in the session tree, where the user can return to it and steer it. It can get conversation and session tools that hidden helpers usually lack. Choose a visible session when you want a separate interaction with that worker. Tool policy, sandboxing, sender access, channel rules, and delegation limits apply in either case.
While waiting, the parent can inspect the active task and yield. In nested delegation, each child reports to its immediate parent. Each parent checks the result and passes usable findings upward. The parent that owns the original request is responsible for completing it and delivering the answer. Subagent completion
Put recurring work on a schedule
Start with what wakes the agent. Use the persistent scheduler for a one-time reminder, a recurring report, or monitoring. An authenticated Gateway webhook receives a request from an external service. The IMAP plugin can open an isolated reader session for permitted senders. Subagents take work handed to them by an agent, and ACP runs coding-harness sessions. Lobster runs local pipelines with resumable approvals. Internal hooks react to lifecycle events, and typed plugin hooks can intervene in operations inside the Gateway. The former Tasks ledger and TaskFlow orchestration services have been removed. Automation overview
Write a standing order for ongoing authority
Say what the agent may do, what starts the work, which actions require approval, and when to stop or escalate. Start with narrow authority. Put the order in the agent's workspace instructions file. OpenClaw normally supplies that file even to short-lived command-line sessions. For a larger program, link to a dedicated document from the instructions. A document in an arbitrary subdirectory needs such a reference or an explicit read. If an order seems absent, check whether workspace context injection is disabled.
A weekly status order could authorize reading configured metrics, comparing them with last week's figures and targets, saving a dated report, and delivering it to a named owner. State whether the agent may change source data or send anything outside the organization. Specify how to handle unavailable sources and unusual results.
A separate service-monitoring order might authorize health checks and a restart, require a low-disk alert, and escalate after two unsuccessful restarts. Give each program its own scope, cadence, approved recipients, and actions. Ask for verification and a report of what happened. Set a finite retry limit and a path for persistent failures. Review logs and update the order when the scope changes.
Use an automation or appropriate event hook to trigger a standing order. The job can refer to the order for procedure and authority. Doctor can convert supported older heartbeat monitors into editable jobs and preserve their history. Setup creates an ambient owner check. Subsequent reloads and restarts preserve edits or deletions to it. Standing orders
Create and verify your first recurring job
Open Automations or ask the agent in chat to create a job. For the weekly status order, choose a calendar schedule and enter a self-contained task. Give the job the named sources, the expected report or conditions for staying quiet, and its recipient. Verify the account and thread. Choose silent delivery if the result only needs to appear in Run history.
An isolated session suits a bounded weekly report with its own model. The main, current, or a named session can make sense if later work needs conversation continuity. Inspect the saved job, then check the next wake in Automations. After a run, open Run history for status, duration, and result. If the task completed and no message appeared, inspect its delivery status and destination separately. Job payloads and sessions Delivery and failure notices
Set when it can run
A job can run once at a time or after a delay, repeat at an interval or on a calendar schedule, or react to a watched process exit or supervised stream output. A one-time reminder can delete itself afterward. Give a recurring calendar schedule an explicit time zone when local time matters. With none specified it uses the Gateway host's time zone. The dashboard's Run at field uses the browser time zone. It rejects a local time that does not exist during a daylight-saving transition. For a repeated fall-back time, a new entry picks the first occurrence.
Hourly calendar jobs can be staggered by up to five minutes. Choose exact timing when the minute matters. A calendar expression with both a day of the month and a day of the week matches either one. Active hours can span midnight. A one-time job waits until the window opens. A repeating job skips an occurrence outside the window. An idle-only job waits for the entire agent to be quiet and can wait indefinitely. Force-run bypasses the ordinary schedule and still respects active hours, authorization, job lifecycle, and delivery restrictions. Automation schedules
Choose what runs and what it can see
A job can place a system event in the main session, request an agent turn, launch a process on the Gateway, or run a headless script with the agent's tools. A deterministic condition or script can handle a machine-checkable condition without asking a model. An agent turn can use the main session, a child of the current conversation, a fresh isolated transcript, or a named session that keeps context between runs.
An isolated run starts without the prior conversation or its route. Put the necessary instructions in the job or its scratch space. Light context omits workspace bootstrap instructions, so use the ordinary context when the job depends on standing orders. Scratch can hold a small checklist. With the corresponding option, explicitly empty scratch skips the turn, while absent scratch allows it. Give unattended runs a clear finish condition. A monitoring job can stay silent when nothing needs attention. A recurring report should still arrive on the cadence the owner requested.
The current sandbox, tool policy, approvals, and creator's permission ceiling apply to each occurrence. Permission to deliver to a channel does not grant the ability to read it. A linked job pauses when its originating conversation is removed or archived, or its worktree disappears. Disabling or removing a job cancels its active occurrence.
Approve a recurring command or watcher
An eligible isolated job can request standing execution approval from a connected Control UI reviewer. Review cards for these jobs go to the dashboard. Required review with no connected approval surface denies the run. A standing grant binds the agent, job, command, working directory, and requested environment. Current host policy still applies, and some commands always need individual review.
A substantive job edit or deletion invalidates the grant. Pausing and resuming an unchanged job preserves it. Use Settings and then Approvals to inspect or revoke a grant. Revocation prevents future use. An operation that already consumed the grant can still finish starting after its final checks. Exec approvals
A stream watcher persists and restarts until disabled or removed. Execution approval can identify the particular watcher and its location. Changes or restarts can need fresh approval. A sandboxed watcher uses its approved container and mounts. If you pause a watcher, inspect observed stream status to confirm its process exited. When cleanup is unconfirmed, you may have to stop the process and restart the Gateway before it can be replaced.
Diagnose a missed report
A job can announce to an authorized chat, send to a webhook, or keep its result in history. Owner delivery requires an identified owner. The Gateway records a missing owner route even when the work succeeds. It does not choose an owner from the last group conversation. Set the desired output language in the task itself. The scheduler does not derive it from older chats or the channel locale.
Open Run history and check execution and delivery separately. For an execution failure, check the schedule, time zone, model, and tool policy. Temporary provider failures may retry quickly. Repeated execution failures can disable a recurring job, and repeated schedule calculation failures can disable it sooner. Fix the cause before enabling it again. A conversation-owned job can sometimes open a repair request in its original conversation.
If a local provider was down, restore it before running the job again. A missed one-time occurrence may need a new time. If a webhook response was inconclusive, confirm what the receiver did before repeating an operation with effects.
Add a model that evaluates evidence
A conversational model handles the agent's chat and tool loop. Some features can also ask a decision model to evaluate a piece of evidence for a narrower purpose. The feature selects the evidence and decides how to use the result. The Gateway can supply a global decision model. An agent inherits it unless it has its own override. An explicitly empty agent override turns decisions off for that agent. With no global selection, decisions are off by default.
TypeSafe Jev appears in the Decision picker when you have a compatible host and TypeSafe plugin that supports version two of the Decision API. Check the required versions before installing. The plugin guide covers a source checkout when a compatible packaged release is pending. For hosted Jev, create a protected credential in Secrets, reference it from the enabled plugin, and choose Jev in the picker. After rotating its credential, reload secrets. Pin a Jev version if you depend on consistent behavior across evaluations. The latest alias can move. Enabled consumers can send the evidence they select to the endpoint, and hosted calls can incur charges. Scheduling and approvals stay with the feature that asks for the decision. TypeSafe plugin
For a local System One model such as Kev, run the inference server yourself and point the plugin at it. The checkpoint loaded by that server determines which weights run. Give a separate inference host its own provider entry, endpoint, and authentication. If the local endpoint fails, the request stays local and fails there. OpenAI also offers a decision model. That route requires Decisions API access and a Platform key. Subscription sign-in is for other eligible routes. OpenAI setup
Build a plugin that the Gateway can load
A skill teaches an agent a procedure. A plugin extends what OpenClaw can do. It can add an agent tool, connect a chat channel, introduce a model provider, or add operations and views to the Control UI. A native plugin runs inside the Gateway through the Plugin SDK. An independent service that wants to call a running Gateway can use the external integration interfaces. Building plugins External integrations
Develop against a pinned OpenClaw version. Registration, runtime, provider, channel, hook, and native dashboard APIs are experimental. Test all the versions you claim to support and check documented migrations and compatibility windows. The documented setup uses a recent supported Node.js release, TypeScript, and ES modules. An external plugin can have its own repository and publish through ClawHub. Bundled plugins use the OpenClaw source checkout and workspace tools. Plugin SDK
Start with a tool that returns a short answer
A small string-returning tool lets you test package discovery, registration, input, and output without an external service. Set the package name, version, and module type. Declare its runtime dependencies and OpenClaw peer dependency, compatible API and Gateway versions, and the SDK version it was built against. A local development entry can be TypeScript. Publish JavaScript and include the runtime dependencies that its entry imports. Channel plugins have their own entry convention. SDK entry points Package metadata
Give the manifest a stable ID, a description, an appropriate category, and a configuration schema. Declare the exact tool name there. In the entry point, register that same name with a description, input schema, and implementation. Add an output schema if the structured result is stable. The manifest allows the Gateway to find the tool's owner before it imports the implementation. Tool-result middleware targets, trusted tool policies, and other surfaces that need host authority require matching manifest declarations. Manifest Manifest surfaces
Use the smallest published SDK subpath that covers your registration. Keep private implementation imports local. A tool is for a typed action the model can choose. A command is for an explicit operator or user action. Node-host commands have a contract for installed nodes, and widget presenters can show structured operation results in the dashboard. Background services and migrations have their own registrations. For an authenticated external caller, register an HTTP route or scoped Gateway method. Prefix custom methods with your plugin's identity. If you forward authenticated requests, declare the bridge surface. The host preserves the client and cancellation signal, checks the target scope, and rechecks authority before a mutation. SDK imports Infrastructure registrations
Give setup and runtime work different lifetimes
The registration function receives a plugin API object. It provides identifying metadata, discovery source, and where available the plugin root and selected runtime entry. The host can load emitted JavaScript even if it discovered a package or source folder. Use the runtime source field to locate private modules beside the selected entry. That field can be absent on metadata-only paths. Resolve plugin-relative files with the provided path helper.
Use the registration snapshot for config as it stood at registration, and the resolved plugin settings for your own configuration. Use the runtime config helper for the latest active snapshot. Log through the scoped logger. Metrics registration depends on operator enablement. Check registration mode to learn whether the host is loading the full runtime, a lightweight setup runtime, or a narrower surface. Keep the lightweight entry free of extra runtime imports. SDK runtime helpers
Register a typed hook to participate in lifecycle or policy decisions. A workflow plugin can own a session extension, trusted tool policy, or a dashboard contribution. Pair privileged runtime registrations with the manifest declarations the host expects. The respective provider contract covers inference, embeddings, search, and other capabilities. Memory and context engines have exclusive slots with one selected owner each. A process-wide session discussion provider reports whether the discussion is unavailable, ready to open, or already open, and creates or resolves it. Registering a different one replaces the active provider. Eligible enabled plugins can contribute native Control UI by default. User-installed browser code has an advanced opt-out independent of backend enablement. Workflow plugin hooks
Use the narrow runtime handle for the work you were given. A command handler bound to a session can receive compaction authority for that session. Await its result and report what happened. If the capability is absent, request a bound conversation. The capability expires with the invocation. OpenClaw owns transcript persistence, the current session generation, and token accounting.
For plugins that read transcripts, use the asynchronous Session Manager interfaces in the focused agent-sessions SDK subpath. Use bounded reads of the active branch when a worker needs only part of the transcript. An incomplete read can leave the previously prepared view intact. A missing database needs preparation by its session owner. Await appends and persistence before publishing work that depends on them. A low-level persistence operation writes an entry while the loaded view stays unchanged. Use typed append when you need the updated view too. Release run or service resources when their lifetime ends and acquire current handles after a reload. Agent runtime helpers
Tell the host what it can learn without executing your plugin
OpenClaw reads a native manifest at the root before it loads code. That is where the host learns identity and capability metadata and validates settings safely at startup. Package metadata points to the runtime entry and describes compatibility and distribution. Runtime code implements the declared behavior. Missing or invalid native manifests and schemas can raise a plugin error and block configuration validation. Other compatible bundle formats have their own discovery rules.
Use a stable ID and give it a human-facing name, description, and version. Give each entry a distinct ID if a package has several. Declare former IDs so references can normalize to the current one. Every native manifest needs a configuration schema, even for an empty configuration. In a declarative tool plugin the author can omit a separate schema in the definition, and the host supplies a strict empty one. Add settings to the schema before using them. Specify their types, provide helpful labels, and mark credentials sensitive. The Gateway applies defaults and checks required values during validation. Manifest configuration and secrets
List the exact tool names, including optional tools, and add availability metadata for discovery and profile eligibility. Declare skill folders relative to the plugin root. An enabled plugin can also expose learned skills scoped to an agent. They fall between bundled and managed skills in precedence. A missing declared plugin dependency can produce a warning and still allow the plugin to load.
For an exclusive capability such as memory or a context engine, declare the kind so the operator can select its owner. Declared engine IDs also let the host plan selection before activation. One declared context engine can be selected automatically at installation. Several require a choice. Keep activation metadata lightweight. It helps the host plan when to load around startup, a provider, a channel, a command, or another capability. Enablement still follows operator settings.
A channel plugin declares channel identity and configuration ahead of loading. Its account selection metadata can tell the host how it picks a stored login. A provider can declare IDs, setup options, aliases, credential environment names, and a lightweight model catalog. The catalog can include aliases and compatibility. Inference and usage lookup can use different credentials. Provider trust and activation rules still apply. A provider can manage capacity cooldown behavior within authentication and subscription restrictions.
The manifest can also describe commands, views, widgets, quality checks, backup resources, and static MCP servers. Bind a dashboard contribution to a method from the same plugin with the matching read or write scope. Operators can override or disable a declared MCP server. Backup declarations can cover a retained database while its plugin is disabled. Choose the catalog category for the plugin's main purpose. You can include up to three starter prompts. If the user picks one after installation or enablement, it goes into an editable draft for the user to send.
Replace a plugin without losing its state
By default the host serializes replacement. If a running turn has no per-turn state that a later call needs, a plugin can opt to have the next model step use the new version. A separate overlap option can let old and new generations run at the same time when both opt in and their surfaces qualify. If both options are declared, overlap takes precedence. Exclusive surfaces such as channels still use serialized replacement.
Use overlap when startup, resources, and cleanup have independent ownership. Keep the successor from taking a port, subscription, or singleton still in use. Coordinate shared writes and make sure a failed replacement leaves the earlier version usable. Each instance cleans up its own timers and watchers. Both generations stay subject to authorization and approvals. A source plugin can offer retained-state inspection for upgrades. A staged Gateway can run this check for matching official or bundled owners. Failed inspection can stop the upgrade while preserving the active service and its files.
Unknown settings for an active channel normally fail config validation. Unavailable plugin references can warn if they are stale. The host can retain disabled configuration and report it, including intentional uninstall markers. An unknown memory slot owner normally produces an error. Use Doctor for diagnostics and repair the package if the manifest or schema is broken.
Give a plugin tool a well-defined job
For a slightly larger tool, imagine looking up a quote from a symbol. Choose a unique tool name, declare the symbol input, and keep any service credential in configuration or a supported secret store. A result can include the symbol and whether the service is configured. Keep the credential out of the result. Use cancellation for work that can be interrupted. A declarative plugin can supply a static set of tools and infer types from their schemas. Tool plugins
Make the tool available at the right time
An enabled plugin's required tool still needs to pass effective tool policy. Mark a tool optional when a side effect, unusual binary, or special capability warrants explicit operator consent. Keep optional status aligned at runtime and in the generated manifest. An operator can allow a particular tool or its plugin, subject to explicit denials. Where warranted, a permission request can ask for approval after tool selection and before the effect. Associate usage guidance with the tools it describes so the host supplies it when the tools are callable. Plugin permission requests
Declare whether the tool needs working files. If a factory reads the workspace to construct a tool, the workspace must be ready at construction. If the tool needs those files only at execution, preparation can wait. Declare tools independent of a workspace as such. This lets the host keep working while a checkout is prepared.
Validate what the model supplies
Keep schemas shallow. OpenClaw limits nesting, including expanded local references, to 128 levels. Deeper portions become permissive and stop enforcing their constraints. This also applies to MCP tools. If you need a dictionary with arbitrary keys, use the SDK's open dictionary support. A native OpenAI Responses route can normalize an object with no declared properties into a closed object. For a fixed object, declare its fields and whether extra keys are accepted.
Registration diagnostics identify affected nested objects. A factory's schemas are checked as it produces tools, so consult runtime health or Doctor for those warnings. The warnings leave registration and normalization behavior as it was. Validate domain-specific requirements before execution and use the SDK's typed argument validation error to report invalid input. Other preparation and execution errors keep their usual classifications.
Use a factory when a tool depends on the run
A factory suits a tool whose availability or implementation depends on the active context, such as its prepared sandbox. It can return one, several, or no tools. Its execution signature differs from the declarative interface. A factory can normalize arguments before schema validation and request sequential execution when calls must stay apart. The tool metadata and execution share the current factory instance. When its plugin registry retires, retained tool handles stop working.
An eligible channel turn can give a factory a turn-bound delivery capability. The host controls the account, destination, thread, and policy. Use it during that turn. If another transport owns delivery, the capability is unavailable. The context can also report the current route and conversation identity. Version two factories can receive sandbox and model capabilities from the prepared environment and current model policy. They last only as long as the run or plugin that owns them. Model output shares the initiating model's budget. Full-value catalog calls use Code Mode admission.
An admitted turn can supply a resolved memory audience. Use that audience for authority. Sender identity or a plausible session name alone cannot establish it. After awaiting work, check that the invocation and audience are still current immediately before releasing data or causing an effect. The version two context supplies those live checks.
Other context can report local browser capability, selected approval devices, run identity, input provenance, or the source of a background fork. These facts help identify the work. The host policy, invocation guard, and live ownership checks determine what it may do. Reviewers need their own approval permission, and reviewer devices must come from trusted selection outside the model's arguments. A wait tool can remain synchronous for supported OpenAI asynchronous requests. Other providers and catalog calls keep their normal behavior.
Carry authority to the last operation
A version two factory can allow work when the exact parent resumes after an explicit yield. It can restrict construction to an owner. Carry the invocation guard across awaited work and check it at the final write or request. It verifies the admitted invocation and plugin lifetime. A continuation also checks the original owner's live parent binding. The tool appearing in a catalog only establishes discoverability.
A shared event callback may run in a different call's asynchronous context. Capture the context of the authorized caller and use it for the guard. For client-supplied bytes, the host may provide a separate input admission check. Carry it to the storage owner's admission boundary so it can check current upload policy there. Check ordinary invocation and mutation authority separately.
Legacy registrations keep their direct-turn context. Continued owner identity is available through the version two contract for eligible resumption. Unrelated sessions, management-only callers, and detached scheduled runs still need their own authority. A tool can hide transient channel progress while retaining lifecycle events and final results.
Return a result the next caller can use
A declarative tool can return text or a structured value. The SDK wraps it for the model and retains structured details. Use a factory when you need your own result shape. If you add an output schema, describe the original details and include all normal variants, including structured errors. The host validates the final details after hooks. An invalid schema blocks execution and a mismatched result fails the completed call. Leave the schema out if you cannot describe stable variants. Keep secrets out of model-visible descriptions. Complete closed schemas give Code Mode and Tool Search compact hints.
Certain common result fields carry reserved outcome meanings. A failure status can mark a call as failed even if the implementation returned normally. Put domain data in its own object if its fields could be interpreted as execution status. When the tool owns a timeout, report the timeout and duration. If there is useful partial output, mark it partial and return what was obtained. Treat the operation as incomplete.
A tool can opt into delivering a complete report, confirmation, or receipt directly. Declare this at the tool level and return a user-ready reply. OpenClaw waits for the whole model step and keeps processing if another call fails or needs work. Hooks can change or withdraw the reply before delivery. A call made from a Code Mode program returns to the program. Use direct delivery once you have a complete answer.
Verify the registration in a running Gateway
Regenerate manifest metadata after changing the plugin ID, configuration, activation, or tool names. Keep package metadata aligned with the built entry. Build and run the tests, validate the entry and manifest, and use type-aware linting for deprecated SDK calls. Inspect the live runtime and exercise registered commands. If the model cannot see the tool, check policy, activation, manifest ownership, package entry, and diagnostics before changing the implementation. Reload after source or manifest changes. Test the actual packed package in a separate environment. Development dependencies alone will be missing from an ordinary runtime install. Plugin CLI SDK entry points
Use a hook when the host should call your plugin
A typed plugin hook can observe or influence a run, tool call, delivery, or stage in the Gateway's lifecycle. Choose the event that owns the decision you need to make. Each hook has its own context, result, and runtime coverage. Context fields can be optional. Check them before applying a rule to a specific agent or session. Internal automation hooks for events such as bootstrap and Gateway webhooks for external requests have their own registration interfaces. Plugin hooks
Try a reply hook before enforcing a rule
Have the hook look for a distinctive phrase and return a short test confirmation. Send the phrase from the Control UI or an enabled channel. It should receive the confirmation without a model call. Send an ordinary message and verify that it reaches the agent. The prepared input can contain channel context as well as the sender's words, so make the phrase distinctive.
A prompt hook can add context or narrow the tool set. A run admission hook can block input on a runtime that supports it. A model request hook can alter or withhold the final request. Check coverage before depending on a hook for enforcement. Tool call hooks can change inputs, request approval, or block execution. Reply and delivery hooks can change a response or cancel delivery. Other hooks record timing or clean up. If several handlers match, the individual hook's priority and merge rules determine the result. Hook catalog Tool policy hooks
Grant only the conversation access the hook needs
A third-party plugin needs conversation access to read or prepare conversations through hooks. An operator can approve the declared capability or grant access for that plugin. Bundled plugins have conversation access unless it is disabled. A session-end hook may receive metadata with no transcript access. Reading the transcript requires the separate grant.
Prompt modification has its own switch. The final model request hook requires explicit additional permission for bundled plugins too. Without that grant the hook does not register. Native plugin code runs with the Gateway process's authority, so review the source as part of installation. Prompt and session hooks
Incognito sessions withhold model input and output observations. At run settlement, a hook can still receive identifiers, success, and duration. Conversation content and more detailed run data are withheld. Policy, provider, approval, and explicitly invoked tool hooks still run.
Transform a channel input at admission
Discord can call a transformation hook before it stores the message in its durable admission queue. Other channels must opt in. Verify host and channel support if your plugin relies on this behavior. Higher-priority handlers run first and each sees the latest replacement. The host checks provider identity and routing lane again after the transformation.
Validate the incoming data and pass the cancellation signal to any outside work. An error, timeout, cancellation, or retired plugin authority can refuse intake. Previously queued messages stay as they were. A timeout can end the host's wait while plugin code is still running. If the hook never fires, inspect the installed plugin's runtime and diagnostics. Check enablement, registration interface, permissions, reload, runtime coverage, trigger conditions, optional fields, and competing handlers. Message hooks
Put a plugin feature in the Control UI
A feature plugin can put typed operations behind a page, sidebar item, panel, widget, or action. It can also offer replacements for the workspace, transcript, or composer. For a first example, build the Draft Review starter. Its draft analyzer can run as an agent tool and through a dashboard page. The browser and backend contracts are experimental, so pin and test both against the Gateway version you support. Feature plugins
Run the starter on the connected Gateway
Create a Draft Review project from the feature starter, install its dependencies, then build, validate, and install the local package. Open its draft review page from the sidebar. To try the replacement composer, open Plugins, then Advanced and Customize UI. Choose Built-in to restore the host view. Replacement selection belongs to the browser runtime. If a replacement hides navigation, the built-in plugin settings page remains available.
Native UI is normally available when its plugin is enabled. Use the Control UI served from the connected Gateway. Its authenticated native assets need the same origin and a secure browser context. HTTPS or browser-trusted loopback works. Plain HTTP on a LAN can display dashboard features while native assets fail, and the plugin's backend operations can continue to work.
The browser code runs with the viewer's signed-in Gateway authority. Review the declared extensions and trust the code before enabling it. For isolated UI, use a sandboxed dashboard widget or an MCP App. An advanced setting can opt out of native browser code for user-installed plugins while keeping their backend tools, operations, and services. Reload tabs to clear code already running. Bundled plugins have their own native UI policy.
Give the tool and the page one operation contract
Use the feature-contract SDK subpath for shared schemas and client calls. Use feature-plugin to connect backend handlers to the host. Use control-ui for browser activation, view contracts, and host components. The plugin owns the browser elements it creates and bundles the framework it uses.
Define a named query or action with TypeBox input and output schemas. Implement it through plugin setup. Queries require the Gateway's operator read scope. Actions require operator write. You can attach an agent tool or command adapter to the same operation. The handler receives the originating session action, tool, or authenticated command context, and each route keeps its checks.
For Draft Review, the operation could take draft text and return a bounded report. The page calls it through the typed client and displays the result. The tool can reuse the same handler. Use a single contract for named events and operations. If the contract pulls in backend-only code, give the typed browser client a browser-safe descriptor and keep the canonical contract for type checking.
Bound and validate both input and output. Keep exposed errors safe for callers. Session actions distinguish validation errors from operation failures, and the host bounds a thrown error message before returning it. Keep secrets and internal exceptions out of that message. Store durable data through approved plugin runtime and storage interfaces.
A page can subscribe to named events or watch a query. A watcher gets the first snapshot, then refreshes on selected events or reconnect. It discards outdated results after a newer refresh or disposal. Check the view's cancellation signal after any awaited work.
Keep browser work tied to its session and request
Export a browser entry using the Control UI plugin helper. Match its ID to the manifest and register contributions through the host UI interface. On mount, the view receives an HTML element, properties, the host, and a cancellation signal. Its update method gets fresh state. Dispose releases subscriptions, observers, and framework roots. A hidden view can keep its state while pausing rendering. Removing the view retires its handles.
Carry both the agent ID and the session key when you act on a conversation. Different agents can have the same key. A change to either part retires the old view and its composer operations. Use host composer operations to read a draft, propose an edit, or send. A proposal waits for the user's acceptance and can be dismissed. A failed submission should keep the draft available for retry.
Use the host's navigation to open pages and panels. A panel can open beside its session. Check whether the optional conversation dock exists before offering an action that needs it. If scoped recovery storage is available, use it for private retry drafts. Scope keys to agent and session. After reconnect, acquire a fresh handle and reauthorize the server resource before restoring private content. Use independent session queries for a page that has its own filters. A row missing from a partial list leaves its deletion unconfirmed.
Return a report with a view the dashboard can open
Imagine an incident tool that returns an incident ID and a short description. The text appears in chat, exports, and model context. The Control UI can also mount an inline panel and fetch current incident data through a scoped operation. Declare the view in the plugin, register its ID and interface version in the browser entry, and return it with the host's inline-view helper.
The saved descriptor contains the plugin ID, view ID, interface version, payload, and text summary. The payload limit is sixteen kibibytes and the summary limit is four. Put large objects in plugin storage and pass a resource ID. Keep credentials out of the descriptor. The Gateway associates it with the actual native tool call. It only mounts an installed renderer the current viewer is allowed to use.
When the user opens history, the saved descriptor can mount again without another tool or model call. Make mounting safe to repeat. It may read a saved snapshot or a live reference. Save mutations for explicit actions and authorize the current viewer on the backend. Keep a compatible renderer for every historical version you want to support. If a renderer is missing or fails, the saved text is still available.
Build, reload, and verify the browser side
Point package metadata to the browser source separately from the backend entry. The plugin build bundles scripts and styles and records content-addressed JavaScript and CSS in the manifest. Keep imports analyzable and bundle framework dependencies. An asset can be up to four mebibytes. The bundle can contain up to eight mebibytes and 128 assets. Validate the build before packing.
After a browser-only edit, rebuild and use Reload plugin UI in advanced customization as an administrator. A failed activation can preserve the previous working view. Choose Built-in if you need to recover a replacement. Backend edits use plugin reload or update. Check browser activation and backend registration independently, then try the operation in an active chat or channel.
Review the exact artifact before enabling it
Pack the built plugin into an import archive if you intend to propose it for managed activation. Its receipt identifies the archive and its cryptographic digest so an operator can approve those exact bytes. The managed installer inspects its declarations and retains the same bytes throughout review. A later source change leaves the reviewed archive intact.
Review backend capabilities and native UI declarations because the approval includes trusted browser code as well. This artifact path supports a single bundled backend entry. For plugins needing separate runtime files, use a normal reviewed package installation. After approval, verify backend application on the running Gateway. A saved installation on a stopped host still needs application. A browser activation receipt shows that a connected browser initialized the named revision. Test the feature in the dashboard and check its permissions.
Test the package someone else will install
Test the implementation, registration through the real loader, and behavior after installing the built package. A mocked registration can show what your code asked the host to add. The real loader verifies manifest metadata, scopes, policy, and trust.
Start with the failure cases your implementation owns
For a tool, try typical valid and invalid inputs. Check the return value, structured details, model-visible text, and any important denied, cancelled, or incomplete cases. Use disposable workspaces and fixture credentials. If a tool waits and then needs authority to perform a final effect, make the fixture reject that last guard check. Verify the effect is prevented.
For a channel, exercise missing, blank, and invalid destinations. Check both explicit and implicit destinations under the allowlist. Test the account resolver separately from the status inspector. An account can be configured while its credential stays out of the status view. Assert that the view contains only the safe fields.
For a provider, use a fixture credential to test a dynamic model result and a catalog result. Give the test route an explicit endpoint class. Check that class when routing depends on it, so a missing manifest declaration cannot accidentally exercise a custom endpoint.
Stub clients per instance to keep cases isolated. If your plugin retains a runtime handle, give your fixture the narrow configuration or agent methods the plugin uses and clear the handle after the case. Model a current configuration read separately from an authorized mutation. Plugin testing
Load the registration and then install the package
Use a loader-backed smoke test for each registration surface you rely on. Register a hook with its hook name. For a memory capability, declare the memory kind in the manifest or supported entry metadata. Check activation and trust conditions. For an optional tool, exercise the same package with an agent allowed to use it and with one that is denied. For conversation hooks, check the required grant for the particular hook.
Build and pack the external plugin, then install it through the managed package path in a separate test environment. Check that the built entry and runtime dependencies are present. Compare tool names declared in the manifest with those registered by the live Gateway. Use a disposable agent in the dashboard or a supported channel to call the tool or command. If the plugin relies on catalog-backed official trust, verify through a catalog-backed installation too.
Scope the fixtures and release checks
The focused testing SDK subpaths for bundled OpenClaw plugins are repository-local. External packages can use their own fixtures and the published runtime contracts. The old monolithic testing export and test-utils alias have been removed. In a source checkout, use a focused helper for registry setup and retirement, isolated state and authentication, channel contracts, provider request captures, or disposable servers. Keep live-provider tests opt-in with explicitly enabled credentials and scope.
Channel inheritance helpers give each test fresh cases with omitted fields preserved. For catalog tests, prepare manifest metadata before the suite, install and clear the snapshot around assertions, and avoid cold runtime discovery. Close retained handles and await registry retirement, including borrowed cache generations, before resetting state. Await database cleanup before removing its directory. If teardown fails, keep the fixture available for investigation.
In the OpenClaw checkout, use the plugin's targeted pnpm test and applicable contract checks for registration, authentication choices, or runtime interfaces. Repository boundary checks cover imports of core source, monolithic SDK imports, and removed aliases. External code should stay within the corresponding published interfaces. The repository uses Vitest with informational V8 coverage. Filter by filename or test name to diagnose failures, and reduce workers if local memory is tight.
Review reload behavior and check for deprecated SDK use before shipping. Test beta versions you claim to support early. Repeat the packaged smoke test on each supported host version. Review a ClawHub publishing dry run, then publish using the ClawHub command line. Install the published package on the Linux Gateway, inspect its runtime, and exercise the feature through its normal entry point. Plugin CLI ClawHub publishing