Skip to content

USER_GUIDE.md

Latest commit

 

History

History
916 lines (674 loc) · 42.1 KB

USER_GUIDE.md

File metadata and controls

916 lines (674 loc) · 42.1 KB

OpenClaw.NET User Guide

Welcome to the OpenClaw.NET User Guide! This document will walk you through the core concepts, configuring your preferred AI provider via API keys, and deploying your first agent.

Upgrading from an earlier release? See Breaking Changes at the end of this guide.

Recommended First Run

Start with the guided setup path:

openclaw start

From a source checkout, use:

dotnet run --project src/OpenClaw.Cli -c Release -- start

Use --profile public when you are preparing a reverse-proxy or internet-facing deployment. If openclaw start finds an existing config, it reuses it; if it needs to run setup, the flow writes an external config file, a matching env example, and prints the exact gateway launch, --doctor, and openclaw admin posture commands for that config.

For private access from other devices in your tailnet, keep OpenClaw.NET bound to 127.0.0.1 and use Tailscale Serve. The guided helper prints the recommended Serve command and checks:

openclaw setup tailscale serve

See deployment/TAILSCALE.md.

Continue the supported bootstrap flow with:

openclaw start
openclaw setup launch --config ~/.openclaw/config/openclaw.settings.json
openclaw setup service --config ~/.openclaw/config/openclaw.settings.json --platform all
openclaw setup status --config ~/.openclaw/config/openclaw.settings.json
openclaw upgrade check --config ~/.openclaw/config/openclaw.settings.json
openclaw upgrade rollback --config ~/.openclaw/config/openclaw.settings.json --offline

For local-model installs, the supported path is now:

openclaw setup --non-interactive --profile local --workspace ./workspace --provider ollama --model llama3.2 --model-preset ollama-general
openclaw models presets
openclaw models doctor
openclaw maintenance scan --config ~/.openclaw/config/openclaw.settings.json

That gives you an explicit local preset, native Ollama routing, doctor guidance for compatibility or fallback gaps, and a maintenance scan that reports storage drift, prompt budget pressure, and top operator actions.

If you start the gateway directly from a local terminal instead of using setup launch, the direct fallback is:

dotnet run --project src/OpenClaw.Gateway -c Release -- --quickstart

That flow is interactive-only. It applies a minimal local loopback profile, prompts for missing provider inputs, retries on the common startup failures, and after a successful start can save the working config to ~/.openclaw/config/openclaw.settings.json.

If you want raw starter files instead of the guided flow, use openclaw init. For the supported upstream skill, plugin, and channel compatibility surface, treat the Compatibility Guide as the source of truth.

After the base config exists, use the channel-specific setup wizard for the common chat integrations:

openclaw setup channel telegram --config ~/.openclaw/config/openclaw.settings.json
openclaw setup channel slack --config ~/.openclaw/config/openclaw.settings.json
openclaw setup channel discord --config ~/.openclaw/config/openclaw.settings.json
openclaw setup channel teams --config ~/.openclaw/config/openclaw.settings.json
openclaw setup channel whatsapp --config ~/.openclaw/config/openclaw.settings.json

These wizards update the existing external config and keep the readiness and admin surfaces aligned with what the CLI generated.

Important distinction:

  • openclaw start is the primary one-command local entrypoint
  • openclaw setup and openclaw init generate the supported onboarding configs
  • directly editing src/OpenClaw.Gateway/appsettings.json is a lower-level path and can expose optional features that are not part of the easiest first run
  • direct gateway startup now prints explicit startup phases and a ready banner with /chat, /admin, /doctor/text, /health, /mcp, and /ws

A2A Task Quick View

If A2A is enabled (OpenClaw:MicrosoftAgentFramework:EnableA2A=true), OpenClaw exposes:

  • HTTP+JSON: /a2a
  • JSON-RPC: /a2a/rpc
  • Agent Card discovery: /.well-known/agent-card.json

A2A requests run with protocol task semantics. message:send and message:stream both execute in task context, and streaming follows the standard lifecycle:

  • submitted
  • working
  • terminal completed or failed

Task cancellation is wired through the A2A handler when a task id is provided. The current task store is in-memory (ITaskStore), so task state is not durable across process restarts.

For the full A2A behavior and operator notes, see a2a.md.

Operator Auth Model

OpenClaw.NET now has three fixed operator roles:

  • viewer: read-only dashboard, audit, setup status, observability, and export access
  • operator: viewer permissions plus approvals, memory/profile/learning changes, automation execution, session promotion, and webhook replay
  • admin: operator permissions plus settings, plugins, provider policies, accounts, and organization policy

Recommended auth flow:

  1. Use OPENCLAW_AUTH_TOKEN once on a non-loopback deployment to bootstrap the first operator account.
  2. Sign into /admin with the operator account username and password.
  3. Exchange credentials for an operator account token when setting up Companion, API clients, CLI automation, or websocket integrations.

Operator token exchange is available at POST /auth/operator-token.

Core Concepts

OpenClaw is split into three main logical layers:

  1. The Gateway: Handles WebSocket, HTTP, and Webhook connectivity (e.g. Telegram/Twilio). It performs authentication and passes messages.
  2. The Agent Runtime: The cognitive loop of the framework. It handles the "ReAct" (Reasoning and Acting) loop, executing tools like Shell, Browser, or File I/O until the goal is completed.
  3. The Tools: A set of native capabilities (48 built-in at the time of writing) that the Agent can invoke to interact with the world, such as Web Fetching, File Writing, or Git Operations.

API Key Setup & LLM Providers

OpenClaw.NET relies on Microsoft.Extensions.AI to abstract away provider complexity. You can configure which provider to use via appsettings.json or environment variables.

External config file (recommended for desktop app / installers)

You can point the Gateway at an additional JSON config file (merged on top of defaults):

  • --config /path/to/openclaw.json
  • or OPENCLAW_CONFIG_PATH=/path/to/openclaw.json

This is useful when you want to keep configuration under your OS app-data folder rather than editing appsettings.json in the install directory.

Environment Variable Defaults

For the quickest start, set your API key as an environment variable before running the gateway.

Bash / Zsh (Linux/macOS):

export MODEL_PROVIDER_KEY="sk-..."

PowerShell (Windows/macOS/Linux):

$env:MODEL_PROVIDER_KEY = "sk-..."

If you need to change the endpoint (e.g., for Azure or local models), set MODEL_PROVIDER_ENDPOINT similarly.

Advanced Provider Configuration (appsettings.json)

To explicitly define your LLM configuration, edit src/OpenClaw.Gateway/appsettings.json under the Llm block:

{
  "OpenClaw": {
    "Llm": {
      "Provider": "openai",
      "Model": "gpt-4o",
      "ApiKey": "env:MODEL_PROVIDER_KEY",
      "Temperature": 0.7,
      "MaxTokens": 4096
    }
  }
}

Note on Resilience & Streaming: Configured properties like FallbackModels and agent constraints like the SessionTokenBudget are enforced uniformly across both standard HTTP API requests and real-time WebSocket streaming sessions (RunStreamingAsync). If a primary provider drops mid-stream, the gateway will flawlessly failover and resume generation using your fallback model.

Supported Providers

OpenClaw supports native routing for several providers out-of-the-box. Change the Provider field in your config to utilize them:

1. OpenAI (Default)

  • Provider: "openai"
  • Required: ApiKey
  • Optional: Endpoint (if routing through a proxy).

2. Azure OpenAI

  • Provider: "azure-openai"
  • Required: ApiKey and Endpoint
  • Notes: The Endpoint must be your Azure resource URL (e.g. https://myresource.openai.azure.com/).

3. Ollama (Local AI)

  • Provider: "ollama"
  • Required: Model (e.g., "llama3" or "mistral")
  • Default Endpoint: http://127.0.0.1:11434
  • Recommended Setup: choose an explicit preset such as ollama-general, ollama-agentic, or ollama-vision
  • Notes: OpenClaw uses Ollama's native /api/chat and /api/embed endpoints. Legacy /v1 compatibility URLs still load, but openclaw models doctor warns so you can migrate to the native base URL.

4. Embedded Local Models

  • Provider: "embedded"
  • Required: a verified local model package and a local sidecar runtime
  • Recommended Setup: embedded-gemma-small-q4 for first-run private/offline helper tasks
  • Notes: OpenClaw owns package install/verify, cache paths, sidecar startup, health checks, and request mapping. Video support is frame-based: local video/* inputs are sampled into ordered image frames before the model call. LiteRT-LM packages are experimental and require an OpenClaw-compatible adapter binary. See Embedded Local Models.

5. Claude / Anthropic

  • Provider: "anthropic" or "claude"
  • Required: ApiKey and Model
  • Optional: Endpoint
  • Notes: This uses the native Anthropic client. You only need Endpoint when routing through a proxy or compatible gateway.

6. Gemini / Google

  • Provider: "gemini" or "google"
  • Required: ApiKey and Model
  • Optional: Endpoint
  • Notes: This uses the native Gemini client for chat and embeddings. You only need Endpoint when routing through a proxy or compatible gateway.

7. Groq / Together AI / LM Studio / OpenAI-compatible

  • Provider: "groq", "together", "lmstudio", or "openai-compatible"
  • Required: ApiKey, Model, and usually Endpoint
  • Notes: These providers are accessed via the OpenAI-compatible REST abstractions. Ensure that you provide the proper base API URL as the Endpoint when required by the target service.

8. Aperture by Tailscale

  • Provider: "aperture" or "openai-compatible" with an Aperture endpoint
  • Required: Endpoint/BaseUrl and Model; ApiKey is required for bearer-token mode
  • Optional: AuthMode = "tailnet-identity" for tailnet identity access without a provider bearer token
  • Notes: Aperture is an optional upstream AI gateway route. OpenClaw.NET still owns agents, tools, sessions, approvals, memory, channels, MCP, and runtime governance. Request metadata headers are disabled by default and are sent only when SendRequestMetadata is explicitly enabled.

Setup helper:

openclaw setup provider aperture \
  --endpoint https://YOUR_APERTURE_ENDPOINT \
  --model YOUR_APERTURE_MODEL_ROUTE \
  --auth-mode bearer \
  --env-var OPENCLAW_APERTURE_TOKEN

For private runtime access, see deployment/TAILSCALE.md. Aperture is a separate optional upstream model-gateway route.

9. Microsoft.Extensions.AI provider bridge

  • Provider: your dynamic provider id, for example "my-meai-provider"
  • Required: JIT runtime mode, dynamic native plugins enabled, a factory implementing IMicrosoftExtensionsAiChatClientFactory, and at least one model id
  • Notes: This optional bridge is for advanced .NET integrations where you already have an IChatClient. OpenClaw still owns routing, policy, budget checks, tracing, approvals, sessions, and usage accounting. See Microsoft.Extensions.AI Provider Bridge.

Tooling & Sandbox

OpenClaw gives the AI extreme power. By default, it can run bash commands (ShellTool), navigate dynamic websites (BrowserTool), and read/write to your local machine.

What most local users should do first

If you are just trying to get the project running locally from source:

  • use the config generated by openclaw setup
  • open http://127.0.0.1:18789/chat for chat
  • open http://127.0.0.1:18789/admin for operator/admin work
  • or visit http://127.0.0.1:18789/, which redirects to /chat
  • ignore sandboxing unless you explicitly want isolated execution

If you are running the gateway directly from Visual Studio and want the simplest behavior, set:

{
  "OpenClaw": {
    "Sandbox": {
      "Provider": "None"
    }
  }
}

This disables optional sandbox routing for sandbox-capable native tools and keeps execution local.

Why the sandbox story is confusing

The current codebase supports OpenSandbox, but it is optional:

  • the checked-in gateway config files now default to OpenClaw:Sandbox:Provider=None
  • the default gateway build does not include the OpenSandbox integration unless you compile with OpenClawEnableOpenSandbox=true
  • the supported onboarding flow does not require OpenSandbox

So if you are new to the project, the right interpretation is:

  • sandboxing is an advanced deployment/runtime option
  • it is not required for a normal local first run

For the full optional path, see sandboxing.md.

Security Configurations

You can lock down the agent via the Tooling config block:

{
  "OpenClaw": {
    "Tooling": {
      "AllowShell": false,
      "AllowedReadRoots": ["/Users/telli/safe-dir"],
      "AllowedWriteRoots": ["/Users/telli/safe-dir"],
      "RequireToolApproval": true,
      "ApprovalRequiredTools": ["shell", "write_file"],
      "EnableBrowserTool": false
    }
  }
}

Setup-generated local profiles keep the browser tool disabled unless you explicitly configure a non-local execution backend or sandbox. Turn EnableBrowserTool on only after that backend is available.

If you expose OpenClaw to the internet (a non-loopback bind address like 0.0.0.0), the Gateway will refuse to start unless you explicitly harden these settings or opt-out of the safety checks.

For a complete list of all available tools and their configuration details, see the Tool Guide.

Skills (Built-In + Custom)

OpenClaw.NET supports “skills” — reusable instruction packs loaded from SKILL.md files and injected into the system prompt.

Skill locations (precedence order):

  1. Workspace: $OPENCLAW_WORKSPACE/skills/<skill>/SKILL.md
  2. Managed: ~/.openclaw/skills/<skill>/SKILL.md
  3. Bundled: skills/<skill>/SKILL.md (shipped with the gateway)
  4. Extra dirs: OpenClaw:Skills:Load:ExtraDirs

Installing skills from ClawHub

OpenClaw.NET skill folders are compatible with the upstream OpenClaw skill format (a folder containing SKILL.md).

Prerequisite: install the ClawHub CLI:

  • npm i -g clawhub (or pnpm add -g clawhub)

Install into your workspace skills (recommended):

  • Ensure OPENCLAW_WORKSPACE is set
  • openclaw clawhub install <skill-slug>

Install into managed skills (shared across workspaces):

  • openclaw clawhub --managed install <skill-slug>

Note: start a new Gateway session (or restart the Gateway) to pick up newly installed skills.

Inspecting and installing local skill packages

When you already have a local upstream-style skill folder or tarball, use the built-in skill installer:

  • openclaw skills inspect ./path/to/skill
  • openclaw skills install ./path/to/skill --dry-run
  • openclaw skills install ./path/to/skill
  • openclaw skills install ./path/to/skill.tgz --managed
  • openclaw skills list

inspect and install --dry-run report trust classification, install slug, requirements, command dispatch metadata, and warnings before any files are copied.

Compatibility catalog for upstream packages

OpenClaw.NET also ships the pinned compatibility catalog that backs the public smoke lane:

  • openclaw compatibility catalog
  • openclaw compatibility catalog --status compatible --kind npm-plugin
  • openclaw compat catalog --json

This is useful when you want a concrete list of tested upstream scenarios, including install commands, config examples, and expected failure diagnostics for known-bad cases.

This repo ships a bundled set of powerful personas and capabilities out-of-the-box (Software Developer, Deep Researcher, Data Analyst, daily news digest, email triage, Home Assistant + MQTT operations). You can disable any skill via:

{
  "OpenClaw": {
    "Skills": {
      "Entries": {
        "daily-news-digest": { "Enabled": false }
      }
    }
  }
}

Interacting With Your Agent

For operator account management (openclaw accounts) and external coding backend configuration (openclaw backends), see External Coding Backends.

WebChat UI (Built-In)

The easiest way to interact with OpenClaw locally is via the embedded frontend:

  1. Start the Gateway: dotnet run --project src/OpenClaw.Gateway
  2. Open your browser to http://127.0.0.1:18789/chat
  3. For chat-only local usage, load the token the UI asks for. For operator/admin workflows, use /admin and sign in with an operator account.

The root URL (http://127.0.0.1:18789/) is not the main browser chat entrypoint. Use /chat.

WebChat token details:

  • The browser client authenticates WebSocket using ?token=<value> on the /ws URL.
  • For non-loopback/public binds, enable OpenClaw:Security:AllowQueryStringToken=true if you use the built-in WebChat.
  • Tokens are stored in sessionStorage by default.
  • Enable the Remember checkbox to also store openclaw_token in localStorage. WebChat includes a Doctor button which fetches GET /doctor/text and prints a diagnostics report (helpful for onboarding and debugging).

Concise Operational Responses

Operational runs such as automations, heartbeat-style workflows, and contract-governed repair/status flows default to a terse operator format. The runtime keeps ordinary chat unchanged, but for the current session you can override the behavior with:

/concise on
/concise off
/concise auto
  • on forces the concise operational format
  • off disables it for the current session
  • auto restores the default behavior, where only operational workflows become concise

This is separate from /verbose on|off, which only controls the extra token and tool-call footer.

Maintenance And Reliability

Use the maintenance surface to understand long-run drift and remove only safe generated artifacts:

openclaw maintenance scan --config ~/.openclaw/config/openclaw.settings.json
openclaw maintenance fix --config ~/.openclaw/config/openclaw.settings.json --dry-run

The report now includes:

  • storage cleanup candidates such as orphaned session metadata, model evaluation artifacts, and managed prompt-cache traces
  • prompt budget pressure from recent turns plus large AGENTS.md or SOUL.md files
  • a reliability score with concrete next commands such as openclaw models doctor or openclaw setup verify --require-provider

The gateway also exposes the same data in /admin/maintenance, /admin/setup/status, and the integration dashboard.

Admin operator surfaces

The built-in admin UI at /admin is now the primary browser operator surface. It supports:

  • username/password browser-session login
  • operator account token login
  • bootstrap token fallback for first-account setup and emergency access
  • setup/deploy status, operator accounts, organization policy, observability, audit export, and local migration report review

For operator workflows outside the chat UI, the gateway also exposes:

  • GET /admin/posture
  • GET /admin/setup/status
  • GET /admin/observability/summary
  • GET /admin/observability/series
  • GET /admin/audit/export
  • POST /admin/approvals/simulate
  • GET /admin/incident/export
  • GET /admin/operator-accounts
  • POST /admin/operator-accounts
  • POST /admin/operator-accounts/{id}/tokens
  • GET /admin/organization-policy
  • PUT /admin/organization-policy
  • GET /admin/memory/notes
  • GET /admin/memory/search
  • GET /admin/memory/notes/{key}
  • POST /admin/memory/notes
  • DELETE /admin/memory/notes/{key}
  • GET /admin/memory/export
  • POST /admin/memory/import
  • GET /admin/profiles
  • GET /admin/profiles/{actorId}
  • GET /admin/profiles/export
  • POST /admin/profiles/import
  • GET /admin/plugins
  • GET /admin/plugins/{id}
  • POST /admin/plugins/{id}/review
  • POST /admin/plugins/{id}/unreview
  • GET /admin/skills
  • GET /admin/compatibility/catalog
  • GET /admin/learning/proposals
  • GET /admin/learning/proposals/{id}
  • POST /admin/learning/proposals/{id}/approve
  • POST /admin/learning/proposals/{id}/reject
  • POST /admin/learning/proposals/{id}/rollback

CLI mirrors:

  • openclaw admin posture
  • openclaw admin approvals simulate
  • openclaw admin incident export
  • openclaw compatibility catalog

Companion and other non-browser clients should authenticate with operator account tokens. The Companion now has an Admin tab that exchanges account credentials for a token and persists it through the OS-backed secret store.

These are useful for validating public-bind posture, approval-policy behavior, and exporting a redacted incident bundle during support/debugging.

For memory and learning operations, the admin API now also supports:

  • searching durable note memory and inspecting project-scoped memory entries
  • editing and deleting memory notes from the operator surface
  • exporting/importing memory bundles that include notes, profiles, learning proposals, and automations
  • browsing stored user profiles directly
  • exporting/importing profile bundles for portability between deployments
  • inspecting a learning proposal with provenance and computed profile diffs before approval
  • rolling back an approved profile-update proposal when a learned preference should be reverted
  • reviewing bridge or dynamic plugins after operator validation and clearing that review state later
  • browsing the currently loaded skills with trust level, required env/config/bin dependencies, and command dispatch metadata
  • browsing the pinned public compatibility catalog with pass/fail scenarios, install guidance, config examples, and expected diagnostics
  • using the built-in operator dashboard to inspect session volume, approval pressure, automation health, memory activity, delegation usage, channel readiness, and plugin trust in one view
  • inspecting automation run history with separate lifecycle, verification, and health states, then replaying a past run or clearing automation quarantine from the operator surface
  • inspecting a session's delegated child agents, delegated tool usage, and proposed changes directly from the session detail pane
  • promoting a successful session into a disabled automation draft, a scoped provider policy, or a pending skill draft proposal without leaving the admin UI
  • using the built-in automation center to apply reusable templates such as inbox triage, daily summary, incident follow-up, channel moderation, and repo hygiene
  • reviewing learning proposals directly in the admin UI, including profile diffs, provenance, risk, validation warnings, rollback, and one-click loading of automation drafts into the automation editor

Review-first learning

OpenClaw.NET can observe repeated patterns and propose durable improvements, including profile_update, automation_suggestion, and skill_draft proposals. By default, this is review-first: observing a pattern creates a proposal, not a silent runtime mutation.

Operators can inspect each proposal before approval:

  • provenance: source session ids, source turn ids when available, repeated count, tool sequence, and tool observations
  • safety context: risk level, confidence, validation status, validation warnings, and hard validation errors
  • proposed change preview: profile before/after diff, disabled automation draft details, or generated SKILL.md content

View proposals from the admin UI Learning Queue, the TUI Learning Proposals panel, or the admin API:

  • GET /admin/learning/proposals
  • GET /admin/learning/proposals/{id}
  • POST /admin/learning/proposals/{id}/approve
  • POST /admin/learning/proposals/{id}/reject
  • POST /admin/learning/proposals/{id}/rollback

Approval applies the durable change and records runtime/operator audit evidence. Automation suggestions are approved as disabled drafts. Skill drafts are approved as managed skills with learning metadata. Rollback is supported for profile updates, managed learning skills, and learning-created automations. Skill rollback only touches managed skills created by the proposal system; modified managed skills are archived instead of silently deleted.

What is not automatic: OpenClaw.NET does not auto-approve proposals by default, does not silently change durable runtime behavior, and does not treat high-risk proposals as safe just because a pattern repeated. High-risk proposals remain reviewable and require explicit approval.

Plugin trust levels shown in the admin UI and CLI are:

  • first-party
  • upstream-compatible
  • third-party-reviewed
  • untrusted

Memory Retention Sweeper (Sessions + Branches)

Retention is opt-in and targets persisted sessions/branches only (not notes).

Key defaults:

  • OpenClaw:Memory:Retention:Enabled=false
  • SessionTtlDays=30
  • BranchTtlDays=14
  • ArchiveEnabled=true with archive-before-delete
  • ArchiveRetentionDays=30

Recommended enablement flow:

  1. Configure retention in appsettings.json under OpenClaw:Memory:Retention.
  2. Run a dry-run first: POST /memory/retention/sweep?dryRun=true
  3. Inspect status: GET /memory/retention/status
  4. Validate /doctor/text warnings and retained-count trends after enabling.

The runtime also performs proactive in-memory active-session expiry sweeps, so expired sessions are evicted over time even without max-capacity pressure.

Avalonia Desktop Companion

You can also interact via the C# desktop interface:

  1. Start the Gateway: dotnet run --project src/OpenClaw.Gateway
  2. Start the UI: dotnet run --project src/OpenClaw.Companion The app will connect to ws://127.0.0.1:18789/ws automatically.

Breaking change: Companion should now use an operator account token as its primary credential. Use the Admin tab to exchange username/password for a token instead of reusing the shared bootstrap token.

Typed integration API and MCP facade

The gateway also exposes two typed automation surfaces alongside the browser UI, WebSocket endpoint, and OpenAI-compatible routes:

  • /api/integration/* for typed operational reads and inbound message enqueueing
  • /mcp for a gateway-hosted MCP JSON-RPC facade over the same runtime/integration data

Current integration API coverage includes:

  • status and dashboard snapshots
  • pending approvals and approval history
  • provider and plugin health snapshots
  • machine-readable compatibility export for CI (GET /api/integration/compatibility/export)
  • operator audit events
  • session lists, session detail, and session timelines
  • automation definitions, latest run state, per-run history, replay, and quarantine clearing
  • runtime event queries
  • message enqueueing

Current MCP coverage includes:

  • initialize
  • tools/list and tools/call
  • resources/list, resources/templates/list, and resources/read
  • prompts/list and prompts/get

If you are building a .NET client, use OpenClaw.Client for typed access to both /api/integration/* and /mcp.

Example:

using System.Text.Json;
using OpenClaw.Client;
using OpenClaw.Core.Models;

using var client = new OpenClawHttpClient("http://127.0.0.1:18789", authToken: null);

var sessions = await client.ListSessionsAsync(page: 1, pageSize: 25, query: null, CancellationToken.None);
var mcp = await client.InitializeMcpAsync(new McpInitializeRequest { ProtocolVersion = "2025-03-26" }, CancellationToken.None);

using var emptyArguments = JsonDocument.Parse("{}");
var status = await client.CallMcpToolAsync("openclaw.get_status", emptyArguments.RootElement.Clone(), CancellationToken.None);

On non-loopback/public binds, authenticate these surfaces with Authorization: Bearer <operator-account-token> for normal automation, or the bootstrap token only for first-run recovery flows.

OpenAI-compatible stable sessions

X-OpenClaw-Session-Id remains the external header for stable OpenAI-compatible conversations, but the gateway now scopes the internal session key by requester identity.

  • The same stable session id can be reused safely by different callers without sharing history.
  • Admin session listings and session detail now expose stableSessionId, stableSessionNamespace, and stableSessionOwnerKey so operators can audit the binding.
  • Unsafe stable session ids (path separators, traversal patterns, overlong ids) are rejected at the HTTP edge.

OpenAI-compatible model resolution

For POST /v1/chat/completions and POST /v1/responses, the incoming model field is resolved in this order:

  1. If model matches a configured OpenClaw model profile id, OpenClaw selects that profile.
  2. Otherwise, OpenClaw treats model as a literal upstream model id override.
  3. If model is omitted, OpenClaw falls back to the configured gateway default model profile or OpenClaw:Llm:Model.

Important implications:

  • The incoming bearer token only authenticates the caller to OpenClaw. It does not tell OpenClaw which provider or model to use.
  • A model profile id is an OpenClaw concept. An upstream model id is a provider concept. They are not interchangeable unless you intentionally name them the same way.
  • "default" is not a reserved sentinel on the OpenAI-compatible routes. It only works if you actually defined a model profile with id default.
  • If your client wants "whatever OpenClaw is configured to use by default", omit the model field instead of sending "default".

Examples:

  • Omit model: use the gateway default route.
  • "model": "frontier-tools": select the OpenClaw model profile with id frontier-tools.
  • "model": "gpt-4o-mini": pass the literal upstream model id gpt-4o-mini through the selected provider route.

If you are building a downstream app against OpenClaw's OpenAI-compatible surface, do not assume your own config placeholder values such as "default" or "primary" have meaning unless you created matching model profiles in OpenClaw.

Upstream Migration

Use the upstream migration flow to translate an upstream-style OpenClaw tree into an external OpenClaw.NET config:

openclaw migrate upstream \
  --source ./upstream-agent \
  --target-config ~/.openclaw/config/openclaw.settings.json \
  --report ./migration-report.json

Dry-run is the default. --apply writes the translated config, imports managed SKILL.md packages, and writes the plugin review plan next to the target config.

Webhook Channels

You can configure OpenClaw to listen to messages in the background natively. Enable them under the Channels block in your config.

  • Telegram: Basic bot API support.
  • Twilio SMS: SMS support via Twilio.
  • WhatsApp: Official Cloud API or custom bridge support.
  • Setup walkthroughs: ../README.md#telegram-webhook-channel and ../README.md#twilio-sms-channel.

Recipient IDs (Telegram / SMS / Email)

Scheduled jobs (Cron) and outbound delivery require a RecipientId that is specific to each channel:

  • Email (ChannelId="email"): the destination email address (e.g. you@example.com)
  • SMS (ChannelId="sms"): an E.164 number (e.g. +15551234567)
  • Telegram (ChannelId="telegram"): a numeric Telegram chat.id (not from.id) or a public channel username such as @openclaw_updates

To discover a Telegram chat.id:

  1. Enable the Telegram channel and temporarily set DmPolicy="open" (or approve the pairing).
  2. Temporarily allow inbound messages:
    • If OpenClaw:Channels:AllowlistSemantics="legacy": you can leave AllowedFromUserIds empty.
    • If OpenClaw:Channels:AllowlistSemantics="strict" (recommended): set AllowedFromUserIds=["*"] (or use POST /allowlists/telegram/add_latest after you send a test message).
  3. Send your bot a message from Telegram so a session is created.
  4. In the WebChat UI, ask: “Use the sessions tool to list active sessions.”
  5. Find the telegram:<chatId> session and use that numeric <chatId> in AllowedFromUserIds and Cron RecipientId.

If you keep DmPolicy="pairing" (recommended for internet-facing deployments), new senders will receive a 6-digit code and their messages will be ignored until approved. Approve via the gateway API:

curl -X POST "http://127.0.0.1:18789/pairing/approve?channelId=telegram&senderId=<chatId>&code=<code>"

If your gateway is bound to a non-loopback address, include -H "Authorization: Bearer $OPENCLAW_OPERATOR_TOKEN" for normal operator automation, or use the bootstrap token only when you are still bootstrapping accounts.

Once you’ve verified the right senders, you can tighten allowlists:

  • POST /allowlists/{channelId}/tighten (replaces wildcard with paired senders for that channel)

Tool Approvals (Supervised Mode)

If OpenClaw:Tooling:AutonomyMode="supervised", the gateway will request approval before running write-capable tools (shell, write_file, etc.).

  • WebChat prompts via a confirmation dialog.
  • On non-loopback/public binds, requester-bound HTTP approval depends on OpenClaw:Security:RequireRequesterMatchForHttpToolApproval.
    • true: the approver must match the original requester.
    • false: any authenticated admin/operator can approve the pending request by id.
  • Fallbacks:
    • Reply: /approve <approvalId> yes|no
    • Admin API: POST /tools/approve?approvalId=...&approved=true|false

Use POST /admin/approvals/simulate or openclaw admin approvals simulate to inspect the effective result for a tool/action without mutating the live approval queue.

Webhook request size controls:

  • OpenClaw:Channels:Sms:Twilio:MaxRequestBytes (default 65536)
  • OpenClaw:Channels:Telegram:MaxRequestBytes (default 65536)
  • OpenClaw:Channels:WhatsApp:MaxRequestBytes (default 65536)
  • OpenClaw:Webhooks:Endpoints:<name>:MaxRequestBytes (default 131072)

For custom /webhooks/{name} routes, MaxBodyLength still controls prompt truncation after size validation. If ValidateHmac=true, Secret is mandatory and validated at startup.

Compaction note:

  • History compaction remains off by default.
  • If you enable OpenClaw:Memory:EnableCompaction=true, CompactionThreshold must be greater than MaxHistoryTurns.

Estimated token admission control

OpenClaw can optionally reject a turn before the provider call when the next turn estimate would already exceed the session budget.

Config:

{
  "OpenClaw": {
    "EnableEstimatedTokenAdmissionControl": true
  }
}

This is off by default for compatibility with the existing post-admission budget behavior.

WhatsApp Setup

OpenClaw.NET supports WhatsApp via two methods: the Official Meta Cloud API and a Bridge (for whatsmeow or similar proxies).

1. Official Meta Cloud API

  1. Create a Meta Developer App and set up "WhatsApp Business API".
  2. Get your Phone Number ID and Cloud API Access Token.
  3. Set your Webhook URL to https://your-public-url.com/whatsapp/inbound.
  4. Set the Verify Token (default: openclaw-verify).
"WhatsApp": {
  "Enabled": true,
  "Type": "official",
  "ValidateSignature": true,
  "WebhookAppSecretRef": "env:WHATSAPP_APP_SECRET",
  "PhoneNumberId": "YOUR_PHONE_ID",
  "CloudApiTokenRef": "env:WHATSAPP_CLOUD_API_TOKEN"
}

For non-loopback/public binds, official mode requires ValidateSignature=true and a valid app secret.

2. WhatsApp Bridge

If you are using a proxy that handles the WhatsApp protocol (like a whatsmeow wrapper), use the bridge mode.

"WhatsApp": {
  "Enabled": true,
  "Type": "bridge",
  "BridgeUrl": "http://your-bridge:3000/send",
  "BridgeTokenRef": "env:WHATSAPP_BRIDGE_TOKEN"
}

Bridge mode validates inbound webhook auth using Authorization: Bearer <BridgeToken> or X-Bridge-Token. For non-loopback/public binds, BridgeTokenRef/BridgeToken is required.

Email Features

OpenClaw.NET includes a built-in Email Tool that allows your agent to interact with the world via email. Unlike Telegram or SMS which act as "Channels" to talking to the agent, the Email Tool is a capability the agent uses to perform tasks like sending reports or reading your inbox.

Configuring the Email Tool

To enable the email tool, update the OpenClaw:Plugins:Native section in your appsettings.json or use environment variables.

Example appsettings.json Configuration:

{
  "OpenClaw": {
    "Plugins": {
      "Native": {
        "Email": {
          "Enabled": true,
          "SmtpHost": "smtp.gmail.com",
          "SmtpPort": 587,
          "SmtpUseTls": true,
          "ImapHost": "imap.gmail.com",
          "ImapPort": 993,
          "Username": "your-email@gmail.com",
          "PasswordRef": "env:EMAIL_PASSWORD",
          "FromAddress": "your-email@gmail.com",
          "MaxResults": 10
        }
      }
    }
  }
}

Authentication Security

We strongly recommend using env:VARIABLE_NAME for the PasswordRef field.

For PowerShell:

$env:EMAIL_PASSWORD = "your-app-password"

For Bash/Zsh:

export EMAIL_PASSWORD="your-app-password"

Tip

If using Gmail, you must use an "App Password" rather than your primary password if Two-Factor Authentication is enabled.

Using Email via the Agent

Once enabled, you can naturally ask the agent to handle emails:

  • "Send an email to boss@example.com with the subject 'Weekly Report' and a summary of my recent work."
  • "Check my inbox for any emails from 'Support' in the last hour and summarize them."
  • "Search my email for a receipt from Amazon and tell me the total amount."

Scheduled Delivery (Email Channel)

If OpenClaw:Plugins:Native:Email:Enabled=true, the gateway also enables an email channel adapter for scheduled jobs. This is separate from the email tool:

  • Email tool: the agent decides when to send/read email as part of a conversation.
  • Email channel: cron jobs can deliver their final response directly via SMTP, using ChannelId="email" and RecipientId="<address>".

Scheduled Tasks (Cron)

OpenClaw.NET supports scheduled prompts via OpenClaw:Cron. Each cron job enqueues an internal system message; the agent runs it and sends the response back through the specified channel.

Cron time + syntax notes

  • Cron expressions are currently evaluated in UTC.
  • Supported cron format is 5 fields: minute hour day-of-month month day-of-week.
  • Supported forms per field: *, */n, a,b,c, a-b, or a single integer.

Example recipe

Daily news (delivered to email)

  • Use the example job in src/OpenClaw.Gateway/appsettings.json as a starting point.
  • Prompt idea: “Summarize today’s top AI + security news. Include links and 5 bullet takeaways.”

For the full per-job field reference (SessionId, ChannelId, RecipientId, Subject) and additional recipes, see the Scheduled Tasks section of the Tool Guide.

Home Automation (Home Assistant + MQTT)

OpenClaw.NET supports native (C#) smart-home control via:

  • Home Assistant tools: home_assistant (read) and home_assistant_write (write)
  • MQTT tools: mqtt (read) and mqtt_publish (write)

Matter support:

  • OpenClaw.NET does not commission Matter devices directly; the recommended approach is to commission devices into Home Assistant and control them through Home Assistant’s entity/service model.

Safety model:

  • Keep writes gated via tool approval by adding home_assistant_write and mqtt_publish to OpenClaw:Tooling:ApprovalRequiredTools.
  • Use allow/deny policies (Policy.Allow*Globs / Policy.Deny*Globs) to restrict entities, services, and MQTT topics.

Shared Scratchpads (Notion)

OpenClaw.NET supports an optional native Notion integration for shared scratchpads and note databases:

  • notion: read/search/list operations
  • notion_write: append/create/update operations

Recommended use:

  • shared project scratchpads
  • operator-visible runbooks
  • handoff notes across sessions or team members

Design constraints:

  • Notion is not used for session memory, branch storage, or core retention.
  • Access is bounded by AllowedPageIds / AllowedDatabaseIds plus any configured defaults.
  • DefaultPageId is used for scratchpad-style reads/appends.
  • DefaultDatabaseId is used for list/search/create workflows.

Recommended safety posture:

  • Keep RequireApprovalForWrites=true unless you intentionally want autonomous writes.
  • Set ReadOnly=true if the agent should only search/read Notion.
  • Share only the specific pages/databases the integration needs. The token may have broader workspace reach than the local allowlist, so the allowlist is part of the tool boundary.

Minimal config example:

"OpenClaw": {
  "Plugins": {
    "Native": {
      "Notion": {
        "Enabled": true,
        "ApiKeyRef": "env:NOTION_API_KEY",
        "DefaultPageId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "DefaultDatabaseId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
        "AllowedPageIds": [
          "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
        ],
        "AllowedDatabaseIds": [
          "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
        ],
        "ReadOnly": false,
        "RequireApprovalForWrites": true
      }
    }
  }
}

Plugin Bridge (Ecosystem Compatibility)

OpenClaw.NET is designed to be compatible with the original OpenClaw TypeScript/JavaScript plugin ecosystem. This allows you to leverage hundreds of community plugins without rewriting them.

OpenClaw.NET spawns a Node.js bridge process to run upstream plugins over JSON-RPC. For runtime requirements, the compatibility matrix, and install paths, see the Bridged Tools section of the Tool Guide. For the full supported-feature breakdown, see the Compatibility Guide.

Breaking Changes

  • OPENCLAW_AUTH_TOKEN is now the bootstrap and breakglass credential, not the recommended day-to-day operator login.
  • Browser admin usage is now account/session-first.
  • Companion, CLI, API, and websocket clients should use operator account tokens instead of the shared bootstrap token.
  • Mutation access is role-gated. A read-only viewer account can no longer rely on the old "any authenticated operator can mutate" assumption.
  • Bare openclaw migrate remains the legacy automation migration alias in this release. Upstream translation now lives under openclaw migrate upstream.