### Install and setup OpenClaw Honcho plugin

Source: https://docs.openclaw.ai/concepts/memory-honcho.md

Run these commands to install the plugin, run setup, and start the gateway. The setup command prompts for API credentials, writes the config, and optionally migrates existing workspace memory files. The API key is only needed for the managed API at api.honcho.dev; self-hosted deployments have no key to enter.

```bash
openclaw plugins install @honcho-ai/openclaw-honcho
openclaw honcho setup
openclaw gateway --force
```

--------------------------------

### Install the OpenClaw Gateway service (openclaw gateway install)

Source: https://docs.openclaw.ai

Installs the Gateway as a background service after pressing Ctrl+C to stop the foreground Gateway started by quick start.

```bash
openclaw gateway install
```

--------------------------------

### Run slack-desktop-smoke Mantis QA scenario with gateway setup

Source: https://docs.openclaw.ai/concepts/mantis.md

Leases or reuses a Crabbox desktop, syncs the checkout, runs Slack QA inside the VM, opens Slack Web in the VNC browser, and copies artifacts back. With --gateway-setup, it creates a persistent OpenClaw home and starts the gateway; without it, runs the normal bot-to-bot Slack QA lane.

```bash
pnpm openclaw qa mantis slack-desktop-smoke \
  --output-dir .artifacts/qa-e2e/mantis/slack-desktop \
  --gateway-setup \
  --scenario slack-canary \
  --keep-lease
```

--------------------------------

### Example flow with verbose and trace

Source: https://docs.openclaw.ai/concepts/active-memory/session-controls.md

Example commands to see active memory status and debug summary in a chat.

```text
/verbose on
/trace on
what wings should i order?
```

--------------------------------

### Install context engine plugin from local path

Source: https://docs.openclaw.ai/concepts/context-engine.md

Install a context engine plugin from a local path using the `-l` flag.

```bash
openclaw plugins install -l ./my-context-engine
```

--------------------------------

### Run QA Lab with pnpm qa:lab:up

Source: https://docs.openclaw.ai/concepts/qa-e2e-automation/operator-flow.md

Starts the QA Lab environment: builds the QA site, starts the Docker-backed gateway lane, and exposes the QA Lab page for operator or automation use.

```bash
pnpm qa:lab:up
```

--------------------------------

### BytePlus ARK plugin installation and restart

Source: https://docs.openclaw.ai/concepts/model-providers/custom-providers.md

Commands to install the official BytePlus provider plugin and restart the Gateway. Required before using the byteplus provider.

```bash
openclaw plugins install @openclaw/byteplus-provider
openclaw gateway restart
```

--------------------------------

### Install context engine plugin from npm

Source: https://docs.openclaw.ai/concepts/context-engine.md

Install a context engine plugin from npm using `openclaw plugins install`.

```bash
openclaw plugins install @martian-engineering/lossless-claw
```

--------------------------------

### Configure messages.queue with JSON5

Source: https://docs.openclaw.ai/concepts/queue.md

Example configuration for setting queue mode, cap, drop policy, and per-channel overrides. Both maps accept channel IDs from bundled and installed plugins. Config validation warns about IDs absent from the channel registry.

```json5
{
  messages: {
    queue: {
      mode: "steer",
      cap: 20,
      drop: "summarize",
      byChannel: { discord: "collect", x: "followup" },
      debounceMsByChannel: { discord: 1000, x: 500 },
    },
  },
}
```

--------------------------------

### ClawSweeper proof command examples

Source: https://docs.openclaw.ai/concepts/mantis.md

Example invocations of the `@clawsweeper proof` command, which can be used once the integration is deployed. The command accepts optional proof types, including comma-separated lists.

```text
@clawsweeper proof
@clawsweeper proof web-ui-chat-proof
@clawsweeper proof telegram-bot-e2e-proof
@clawsweeper proof web-ui-chat-proof,telegram-bot-e2e-proof
```

--------------------------------

### Install OpenClaw with curl (macOS/Linux/WSL2) and PowerShell (Windows)

Source: https://docs.openclaw.ai

Installs OpenClaw on macOS/Linux/WSL2 (bash) and Windows (PowerShell). The installer detects the OS, installs Node if needed, installs OpenClaw, and starts onboarding.

```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```

```powershell
iwr -useb https://openclaw.ai/install.ps1 | iex
```

--------------------------------

### Link WhatsApp accounts before starting the gateway

Source: https://docs.openclaw.ai/concepts/multi-agent.md

Run these commands to link the 'personal' and 'biz' WhatsApp accounts before starting the gateway. Each account is associated with a specific agent via bindings.

```bash
openclaw channels login --channel whatsapp --account personal
openclaw channels login --channel whatsapp --account biz
```

--------------------------------

### Example output with verbose and trace

Source: https://docs.openclaw.ai/concepts/active-memory/session-controls.md

Shows the diagnostic lines appended after the normal reply when verbose and trace are on.

```text
...normal assistant reply...

🧩 Active Memory: status=ok elapsed=842ms query=recent summary=34 chars
🔎 Active Memory Debug: Lemon pepper wings with blue cheese.
```

--------------------------------

### Fast QA Lab iteration with pnpm qa:lab:up:fast

Source: https://docs.openclaw.ai/concepts/qa-e2e-automation/operator-flow.md

Faster QA Lab UI iteration workflow: builds the Docker image, builds the QA Lab bundle, starts the stack with a bind-mounted bundle, and watches for changes with auto-reload.

```bash
pnpm openclaw qa docker-build-image
```

```bash
pnpm qa:lab:build
```

```bash
pnpm qa:lab:up:fast
```

```bash
pnpm qa:lab:watch
```

--------------------------------

### Usage bar schema example with verbs and piece forms

Source: https://docs.openclaw.ai/concepts/usage-tracking.md

Example JSONC configuration for a usage bar. It defines scales, aliases, and output surfaces. The output uses piece forms like 'when', 'map', and 'each' to conditionally render text and apply verbs like 'alias' and 'meter'.

```jsonc
{
  "schema": "openclaw.usageBar.v1",
  "scales": { "braille": "⠐⡀⡄⡆⡇⣇⣧⣷⣿" },
  "aliases": { "reasoning": { "medium": "🌗", "high": "🌕" } },
  "output": {
    "surfaces": {
      "discord": [
        { "text": "{model.display_name}" },
        { "when": "model.reasoning", "text": " {model.reasoning|alias:reasoning}" },
        { "map": "state.fast_mode", "cases": { "true": " ⚡", "false": " 🐌" } },
        {
          "when": "context.max_tokens",
          "text": " | 📚 [{context.pct_used|meter:5:braille}]{context.max_tokens|num}",
        },
      ],
    },
  },
}
```

--------------------------------

### Allowlist with aliases and per-model settings (JSON5)

Source: https://docs.openclaw.ai/concepts/models.md

Example configuration combining an allowlist with model aliases and per-model settings. This shows how to set primary model, allowlist entries, and aliases for specific models.

```json5
{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-sonnet-4-6" },
      modelPolicy: {
        allow: ["anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4-6"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "anthropic/claude-opus-4-6": { alias: "Opus" },
      },
    },
  },
}
```

--------------------------------

### /model command usage examples

Source: https://docs.openclaw.ai/concepts/models.md

Shows the /model command with various flags and arguments: listing models, selecting by provider/model or alias, setting session, agent, or global scope, and using default or status. Note that numeric selections like /model 3 are not supported.

```text
/model
/model list
/model Opus
/model openai/gpt-5.4
/model openai/gpt-5.4 -s
/model openai/gpt-5.4 -a
/model openai/gpt-5.4 -g
/model default -s
/model default
/model status
```

--------------------------------

### Install llama.cpp provider for local embeddings

Source: https://docs.openclaw.ai/concepts/memory-builtin.md

Installs the official llama.cpp provider plugin, which is required to use local GGUF embeddings with the builtin memory engine.

```bash
openclaw plugins install @openclaw/llama-cpp-provider
```

--------------------------------

### Link local plugin directory with openclaw plugins install -l

Source: https://docs.openclaw.ai/concepts/context-engine.md

Use this command during development to link a local plugin directory without copying it.

```bash
openclaw plugins install -l ./my-engine
```

--------------------------------

### Notice message example

Source: https://docs.openclaw.ai/concepts/session-state.md

Example of the system notice a watcher receives when a notify-eligible event lands and the watcher's cursor is behind. The notice is byte-stable while pending and deduped.

```text
Session "agent:main:subagent:child" changed (other actor). Reconcile before acting: session_status sessionKey "agent:main:subagent:child" changesSince 12.
```

--------------------------------

### Honcho CLI commands

Source: https://docs.openclaw.ai/concepts/memory-honcho.md

Commands to configure, check status, query, and search Honcho memory. Setup requires an API key and migrates files.

```bash
openclaw honcho setup                        # Configure API key and migrate files
openclaw honcho status                       # Check connection status
openclaw honcho ask <question>               # Query Honcho about the user
openclaw honcho search <query> [-k N] [-d D] # Semantic search over memory
```

--------------------------------

### Run Multipass suite with channel-chat-baseline scenario

Source: https://docs.openclaw.ai/concepts/qa-e2e-automation/scenario-coverage.md

Runs the QA suite in a disposable Multipass VM without Docker. Boots a fresh guest, installs dependencies, builds OpenClaw inside the guest, and runs qa suite. The guest writes the normal QA report and summary through the mounted workspace into .artifacts/qa-e2e/... on the host, including when a scenario fails. Reuses the same scenario-selection behavior as qa suite on the host.

```bash
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
```

--------------------------------

### Example retirement JSON request

Source: https://docs.openclaw.ai/concepts/managed-worktrees.md

Example JSON payload for the --exact-state option. Use actual observed values, not the example. Omit ownerId for a manual record without an owner ID. The fields include ownerKind, ownerId, createdAt, lastActiveAt, head, branchHead, and indexSha256.

```json
{
  "ownerKind": "session",
  "ownerId": "example-session",
  "createdAt": 1800000000000,
  "lastActiveAt": 1800000000001,
  "head": "1111111111111111111111111111111111111111",
  "branchHead": "2222222222222222222222222222222222222222",
  "indexSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
```

--------------------------------

### Run qa run with root profile before QA command

Source: https://docs.openclaw.ai/concepts/qa-e2e-automation/command-surface.md

Shows how to include an OpenClaw root profile before the QA command by placing the root profile before `qa run`. This example uses `--profile work` and `--qa-profile smoke-ci`.

```bash
pnpm openclaw --profile work qa run --qa-profile smoke-ci
```

--------------------------------

### Narrowing rollout with allowedChatIds and deniedChatIds

Source: https://docs.openclaw.ai/concepts/active-memory/how-it-works.md

Example configuration that narrows the rollout to specific chat IDs while denying a large public group. The deniedChatIds always wins over allowedChatTypes and allowedChatIds.

```json5
allowedChatTypes: ["direct", "group"],
allowedChatIds: ["ou_operator_open_id", "oc_small_ops_group"],
deniedChatIds: ["oc_large_public_group"]
```

--------------------------------

### ContextEngine Interface

Source: https://docs.openclaw.ai/concepts/context-engine.md

Defines the required members for a context engine: info, ingest, assemble, and compact. The optional commitTurn method is also shown in the example.

```APIDOC
## ContextEngine Interface

### Description
Defines the required members for a context engine: info, ingest, assemble, and compact. The optional commitTurn method is also shown in the example.

### Members
#### info (Property)
- **id** (string) - Required - Engine identifier.
- **name** (string) - Required - Human-readable engine name.
- **ownsCompaction** (boolean) - Required - Whether the engine handles compaction.
- **acceptedHostParams** (array) - Required - List of host parameters accepted.
- **transcriptSemantics** (object) - Required - Semantics for transcript handling.

#### ingest(params) (Method)
- **params.sessionId** (string) - Required - Session identifier.
- **params.message** (object) - Required - The message to store.
- **params.isHeartbeat** (boolean) - Optional - Whether the message is a heartbeat.
- **Returns** (Promise<object>) - Result of ingestion.

#### assemble(params) (Method)
- **params.sessionId** (string) - Required - Session identifier.
- **params.sessionKey** (string) - Optional - Session key.
- **params.messages** (array) - Required - Messages to assemble.
- **params.tokenBudget** (number) - Required - Token budget.
- **params.availableTools** (Set) - Optional - Available tools.
- **params.citationsMode** (string) - Optional - Citations mode.
- **Returns** (Promise<AssembleResult>) - Assembled context.

#### compact(params) (Method)
- **params.sessionId** (string) - Required - Session identifier.
- **params.force** (boolean) - Optional - Force compaction.
- **Returns** (Promise<object>) - Compaction result.

#### commitTurn(params) (Method) - Optional
- **params.advancementKey** (string) - Required - Key for turn advancement.
- **params.messages** (array) - Required - Messages to commit.
- **Returns** (Promise<object>) - Commit result, may return "duplicate" for retries.

### Example
```ts
const engine = {
  info: {
    id: "my-engine",
    name: "My Context Engine",
    ownsCompaction: true,
    acceptedHostParams: ["sessionKey", "runtimeContext"],
    transcriptSemantics: {
      currentTurnFence: "before-current-turn-entry-v1",
      turnAdvancementIdempotency: "atomic-idempotent-v1",
    },
  },
  async ingest({ sessionId, message, isHeartbeat }) {
    return { ingested: true };
  },
  async assemble({ sessionId, sessionKey, messages, tokenBudget, availableTools, citationsMode }) {
    return {
      messages: buildContext(messages, tokenBudget),
      estimatedTokens: countTokens(messages),
      systemPromptAddition: buildMemorySystemPromptAddition({
        availableTools: availableTools ?? new Set(),
        citationsMode,
        agentSessionKey: sessionKey,
      }),
    };
  },
  async compact({ sessionId, force }) {
    return { ok: true, compacted: true };
  },
  async commitTurn({ advancementKey, messages }) {
    return await commitAcceptedTurn({ advancementKey, messages });
  },
};
```
```

--------------------------------

### Custom usage footer template example

Source: https://docs.openclaw.ai/concepts/usage-tracking.md

A full custom template for the /usage full footer. It defines scales, aliases for model names and reasoning levels, and output pieces for the default and Discord surfaces. The template uses placeholders like {model.provider} and {context.pct_used|meter:5:braille}.

```jsonc
{
  "schema": "openclaw.usageBar.v1",
  "scales": {
    "braille": "⠐⡀⡄⡆⡇⣇⣧⣷⣿",
    "block": "░▏▎▍▌▋▊▉█",
    "shade": "░▒▓█",
    "moon": "🌑🌘🌗🌖🌕",
    "level": "▁▂▃▄▅▆▇█",
    "weather": ["🥶", "☁️", "🌥", "⛅️", "🌤", "☀️"],
    "plants": ["🪾", "🍂", "🌱", "☘️", "🍀", "🌿"],
    "moons6": ["🌑", "🌚", "🌘", "🌗", "🌖", "🌝"],
  },
  "aliases": {
    "models": {
      "claude-opus-4-6": "opus46",
      "claude-opus-4-8": "opus48",
      "claude-sonnet-4-6": "sonnet46",
      "claude-haiku-4-5": "haiku45",
      "gpt-5.5": "gpt5.5",
    },
    "reasoning": {
      "off": "🌑",
      "minimal": "🌚",
      "low": "🌘",
      "medium": "🌗",
      "high": "🌕",
      "xhigh": "🌝",
    },
  },
  "output": {
    "sep": "",
    "default": [
      { "text": "{model.provider}{identity.emoji|🤖}{model.display_name|alias:models}" },
      { "map": "model.is_fallback", "cases": { "true": "🔄" } },
      { "map": "model.is_override", "cases": { "true": "📌" } },
      { "when": "model.reasoning", "text": "{model.reasoning|alias:reasoning}" },
      { "map": "state.fast_mode", "cases": { "true": "⚡️", "false": "🐌" } },
      {
        "when": "context.max_tokens",
        "text": " | 📚[{context.pct_used|meter:5:braille}]{context.max_tokens|num}",
      },
      { "when": "cost.turn_usd", "text": " 💰{cost.turn_usd|fixed:4}" },
    ],
    "surfaces": {
      "discord": [
        { "text": "-# -\n" },
        { "text": "-# {model.provider}{identity.emoji|🤖}{model.display_name|alias:models}" },
        { "map": "model.is_fallback", "cases": { "true": "🔄" } },
        { "map": "model.is_override", "cases": { "true": "📌" } },
        { "when": "model.reasoning", "text": "{model.reasoning|alias:reasoning}" },
        { "map": "state.fast_mode", "cases": { "true": "⚡️", "false": "🐌" } },
        {
          "when": "context.max_tokens",
          "text": " | 📚[{context.pct_used|meter:5:braille}]{context.max_tokens|num}",
        },
        { "when": "cost.turn_usd", "text": " 💰{cost.turn_usd|fixed:4}" },
      ],
    },
  },
}
```

--------------------------------

### Allowlist with provider wildcards (JSON5)

Source: https://docs.openclaw.ai/concepts/models.md

Example configuration for agents.defaults.modelPolicy.allow using provider-wide wildcards. This limits the model picker to the specified providers and allows new models to appear without editing the allowlist.

```json5
{
  agents: {
    defaults: {
      modelPolicy: {
        allow: ["openai/*", "vllm/*"],
      },
    },
  },
}
```

--------------------------------

### Local CLI prove native Slack approval UI

Source: https://docs.openclaw.ai/concepts/mantis-slack-desktop-runbook.md

Runs the smoke test with approval checkpoints enabled. `--approval-checkpoints` is mutually exclusive with `--gateway-setup`. It runs the opt-in `slack-approval-exec-native` and `slack-approval-plugin-native` scenarios unless an explicit approval-checkpoint `--scenario` is passed. Other Slack scenarios are rejected before the VM starts.

```bash
pnpm openclaw qa mantis slack-desktop-smoke \
  --provider aws \
  --class standard \
  --approval-checkpoints \
  --credential-source convex \
  --credential-role maintainer \
  --hydrate-mode source
```

--------------------------------

### Pull Ollama model

Source: https://docs.openclaw.ai/concepts/model-providers/custom-providers.md

Installs Ollama and pulls the llama3.3 model for local use.

```bash
# Install Ollama, then pull a model:
ollama pull llama3.3
```

--------------------------------

### mantis-evidence.json schema version 2 example

Source: https://docs.openclaw.ai/concepts/mantis.md

Example of the mantis-evidence.json manifest with schemaVersion 2. Each lane must declare expectationMet; the publisher downgrades a claimed pass when a lane's expectation was not met. The manifest is a presentation contract, not an authenticated proof receipt.

```json
{
  "schemaVersion": 2,
  "id": "discord-status-reactions",
  "title": "Mantis Discord Status Reactions QA",
  "summary": "Human-readable top summary for the PR comment.",
  "scenario": "discord-status-reactions-tool-only",
  "comparison": {
    "baseline": {
      "sha": "<baseline-sha>",
      "status": "fail",
      "expected": "queued-only",
      "expectationMet": true
    },
    "candidate": {
      "sha": "<candidate-sha>",
      "status": "pass",
      "expected": "queued -> thinking -> done",
      "expectationMet": true
    },
    "pass": true,
    "outcome": "pass"
  },
  "artifacts": [
    {
      "kind": "timeline",
      "lane": "baseline",
      "label": "Baseline queued-only",
      "path": "baseline/timeline.png",
      "targetPath": "baseline.png",
      "alt": "Baseline Discord timeline",
      "width": 420
    }
  ]
}
```

--------------------------------

### Run openclaw onboard to set up models and auth

Source: https://docs.openclaw.ai/concepts/models.md

Initializes model and authentication configuration for common providers, including OpenAI Codex subscription OAuth and Anthropic API key or Claude CLI reuse. With no primary model configured, fresh OpenAI API-key and ChatGPT/Codex OAuth setup selects the exact openai/gpt-6-astra catalog ref. Reauthentication preserves an existing explicit primary model.

```bash
openclaw onboard
```

--------------------------------

### Tune per-line character budget with maxLineChars

Source: https://docs.openclaw.ai/concepts/progress-drafts.md

Adjust the per-line character budget for progress lines. The default is 120 characters; this example sets it to 160.

```json5
{
  channels: {
    discord: {
      streaming: {
        mode: "progress",
        progress: {
          maxLineChars: 160,
        },
      },
    },
  },
}
```

--------------------------------

### Per-agent sandbox and tool configuration in JSON5

Source: https://docs.openclaw.ai/concepts/multi-agent.md

Defines agents with explicit ownership, default auth inheritance, and per-agent sandbox and tool restrictions. The 'personal' agent has sandbox mode 'off' and no tool restrictions, while the 'family' agent has sandbox mode 'all' with a setup command and only the 'read' tool allowed. Note that setupCommand runs once on container creation and per-agent sandbox.docker overrides are ignored when scope is 'shared'.

```json5
{
  agents: {
    ownership: "explicit",
    defaults: {
      authInheritance: { agentId: "personal" },
      heartbeat: { agentId: "personal" },
      systemAgent: { agentId: "personal" },
    },
    entries: {
      personal: {
        workspace: "~/.openclaw/workspace-personal",
        sandbox: {
          mode: "off", // No sandbox for personal agent
        },
        // No tool restrictions - all tools available
      },
      family: {
        workspace: "~/.openclaw/workspace-family",
        sandbox: {
          mode: "all", // Always sandboxed
          scope: "agent", // One container per agent
          docker: {
            // Optional one-time setup after container creation
            setupCommand: "apt-get update && apt-get install -y git curl",
          },
        },
        tools: {
          allow: ["read"], // Only read tool
          deny: ["exec", "write", "edit", "apply_patch"], // Deny others
        },
      },
    },
  },
  talk: { agentId: "personal" },
}
```

--------------------------------

### Login with OAuth provider

Source: https://docs.openclaw.ai/concepts/oauth.md

Use this command to start the OAuth login flow for a provider that supports it, such as OpenAI Codex or Anthropic Claude CLI. The command is the entry point for provider plugins that ship their own OAuth or API-key flow.

```bash
openclaw models auth login --provider <id>
```

--------------------------------

### Create agent workspaces with openclaw agents add

Source: https://docs.openclaw.ai/concepts/multi-agent.md

Run these commands to create separate workspaces for each agent. Each agent gets its own workspace with SOUL.md, AGENTS.md, and optional USER.md, plus a dedicated agentDir and session store. By default, agent files live under ~/.openclaw/agents/<agentId>.

```bash
openclaw agents add coding
openclaw agents add social
```

--------------------------------

### Example decision answers

Source: https://docs.openclaw.ai/concepts/decision-models.md

Illustrative answers returned in outcome.result.answers, keyed by question IDs. The host validates the complete batch before returning any answers. Narrow an answer by its type before accessing type-specific fields.

```JSON
{
  "route": {
    "type": "choice",
    "choice": "support",
    "probabilities": { "support": 0.97, "billing": 0.02, "sales": 0.01 }
  },
  "urgency": {
    "type": "score",
    "score": 2.85,
    "probabilities": [0, 0, 0.15, 0.85]
  },
  "escalate": { "type": "boolean", "probabilityTrue": 0.96 }
}
```

--------------------------------

### Enable compaction notifications with notifyUser

Source: https://docs.openclaw.ai/concepts/compaction.md

Set `agents.defaults.compaction.notifyUser` to `true` to show brief status messages when compaction starts and completes, and when a pre-compaction memory flush is exhausted but the reply continues. By default, routine compaction runs silently.

```json5
{
  agents: {
    defaults: {
      compaction: {
        notifyUser: true,
      },
    },
  },
}
```

--------------------------------

### Recommended starter configuration for active-memory plugin

Source: https://docs.openclaw.ai/concepts/active-memory/recommended-setup.md

Starter configuration for the active-memory plugin using 'recent' query mode and 'escalate' mode. Includes 'timeoutMs: 15000' and 'setupGraceTimeoutMs' is not set, so the default behavior applies. Use '/verbose on' and '/trace on' for tuning.

```json5
{
  plugins: {
    entries: {
      "active-memory": {
        enabled: true,
        config: {
          agents: ["main"],
          mode: "escalate",
          queryMode: "recent",
          promptStyle: "balanced",
          timeoutMs: 15000,
          maxSummaryChars: 220,
          logging: true,
        },
      },
    },
  },
}
```

--------------------------------

### Suggested .gitignore starter

Source: https://docs.openclaw.ai/concepts/agent-workspace.md

A starter .gitignore to avoid committing secrets and sensitive files. Includes .DS_Store, .env, key/pem files, and secrets directories.

```gitignore
.DS_Store
.env
**/*.key
**/*.pem
**/secrets*
```

--------------------------------

### Run WhatsApp QA lane

Source: https://docs.openclaw.ai/concepts/qa-e2e-automation/whatsapp-and-credentials.md

Command to run the WhatsApp QA lane using pnpm. Targets two dedicated WhatsApp Web accounts: a driver account controlled by the harness and a SUT account started by the child OpenClaw gateway.

```bash
pnpm openclaw qa whatsapp
```

--------------------------------

### CLI commands for onboarding and model management

Source: https://docs.openclaw.ai/concepts/model-providers.md

Commands to onboard with opencode-zen, set a model, and list models.

```bash
openclaw onboard --auth-choice opencode-zen
openclaw models set opencode/claude-opus-4-6
openclaw models list
```

--------------------------------

### Enable progress streaming mode on Discord (JSON5)

Source: https://docs.openclaw.ai/concepts/progress-drafts.md

Sets the Discord channel streaming mode to 'progress' in a JSON5 config. With this, defaults apply: a 1.5-second start delay, a quiet status draft while work happens, and suppression of older standalone progress messages for that turn.

```json5
{
  channels: {
    discord: {
      streaming: {
        mode: "progress",
      },
    },
  },
}
```

--------------------------------

### Set worktreeRoot in openclaw.json

Source: https://docs.openclaw.ai/concepts/managed-worktrees.md

Use this JSON5 configuration to set the global worktreeRoot option to a custom directory. The path must be absolute, use ~ for the Gateway user's home, or start with ~/. Relative paths are rejected. The Gateway user must have write access to the directory.

```json5
{
  worktreeRoot: "/mnt/workspaces/openclaw-worktrees",
}
```

--------------------------------

### Run desktop-browser-smoke Mantis QA scenario

Source: https://docs.openclaw.ai/concepts/mantis.md

Leases or reuses a Crabbox desktop, launches a browser in the VNC session, captures screenshots and optional video, and syncs artifacts back. Use --lease-id to reuse a warmed desktop, --browser-profile-dir to reuse a Chrome profile, and --keep-lease to keep the VM open for inspection.

```bash
pnpm openclaw qa mantis desktop-browser-smoke \
  --output-dir .artifacts/qa-e2e/mantis/desktop-browser
```

--------------------------------

### buildMemorySystemPromptAddition

Source: https://docs.openclaw.ai/concepts/context-engine.md

Synchronous helper from the plugin SDK that builds a system prompt addition based on available tools, citations mode, and agent session key. It reads an immutable run snapshot prepared by the host before assemble.

```APIDOC
## buildMemorySystemPromptAddition

### Description
Synchronous helper from the plugin SDK that builds a system prompt addition based on available tools, citations mode, and agent session key. It reads an immutable run snapshot prepared by the host before assemble.

### Method
buildMemorySystemPromptAddition

### Endpoint
buildMemorySystemPromptAddition({ availableTools, citationsMode, agentSessionKey })

### Parameters
#### Parameters
- **availableTools** (Set) - Required - Set of available tools.
- **citationsMode** (string) - Required - Citations mode.
- **agentSessionKey** (string) - Required - Agent session key.

### Request Example
```ts
buildMemorySystemPromptAddition({
  availableTools: new Set(),
  citationsMode: "default",
  agentSessionKey: "session-key",
});
```

### Response
#### Success Response
- **systemPromptAddition** (string) - The generated system prompt addition.

#### Response Example
```ts
"..."
```
```

--------------------------------

### Cold-start grace configuration for upgrading from v2026.4.x

Source: https://docs.openclaw.ai/concepts/active-memory/recommended-setup.md

Configuration to restore the pre-v2026.5.2 effective timeout budget by setting 'setupGraceTimeoutMs: 30000'. This is recommended if you upgraded from v2026.4.x and tuned 'timeoutMs' for the old implicit-grace world. Worst-case blocking time is 'timeoutMs + setupGraceTimeoutMs + 3000' ms.

```json5
{
  plugins: {
    entries: {
      "active-memory": {
        config: {
          timeoutMs: 15000,
          setupGraceTimeoutMs: 30000,
        },
      },
    },
  },
}
```

--------------------------------

### Local CLI cold source proof for slack-desktop-smoke

Source: https://docs.openclaw.ai/concepts/mantis-slack-desktop-runbook.md

Runs the smoke test from source with a fresh AWS VM, setting up the gateway and using Convex credentials. Uses live-frontier provider mode and the slack-canary scenario.

```bash
pnpm openclaw qa mantis slack-desktop-smoke \
  --provider aws \
  --class standard \
  --gateway-setup \
  --credential-source convex \
  --credential-role maintainer \
  --provider-mode live-frontier \
  --model openai/gpt-5.4 \
  --alt-model openai/gpt-5.4 \
  --scenario slack-canary \
  --hydrate-mode source
```

--------------------------------

### Create delegate agent with openclaw agents add

Source: https://docs.openclaw.ai/concepts/delegate-architecture.md

Creates a new delegate agent with a dedicated workspace. Sets up workspace, agent state, and sessions directories.

```bash
openclaw agents add delegate --workspace ~/.openclaw/workspace-delegate
```

--------------------------------

### Initialize the Git repository

Source: https://docs.openclaw.ai/concepts/agent-workspace.md

Run these commands in the workspace directory to initialize a Git repository and commit the initial agent files.

```bash
cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md IDENTITY.md USER.md memory/
git commit -m "Add agent workspace"
```

--------------------------------

### Create a team with openclaw agents team create

Source: https://docs.openclaw.ai/concepts/multi-agent.md

Run these two commands to create a small team non-interactively and then instruct the coordinator to research and draft a recommendation. The preset creates a chief of staff (coordinator), researcher, writer, and reviewer, each with its own workspace and identity.

```bash
openclaw agents team create --non-interactive
openclaw agent --agent coordinator --message "Research the options and draft a recommendation."
```

--------------------------------

### Set progress draft line limit with maxLines

Source: https://docs.openclaw.ai/concepts/progress-drafts.md

Limit how many lines stay visible in the progress draft. The default is 8; this example sets it to 4.

```json5
{
  channels: {
    discord: {
      streaming: {
        mode: "progress",
        progress: {
          maxLines: 4,
        },
      },
    },
  },
}
```

--------------------------------

### modelFallback configuration

Source: https://docs.openclaw.ai/concepts/active-memory/tuning.md

Example of setting `config.modelFallback` to a fast model, used as the last resort in the model resolution chain. This field is not a runtime failover; `config.modelFallbackPolicy` is deprecated and does not affect behavior.

```json5
modelFallback: "google/gemini-3-flash"
```

--------------------------------

### Run Matrix QA with mock OpenAI provider

Source: https://docs.openclaw.ai/concepts/qa-e2e-automation/operator-flow.md

Use this command to run the Matrix QA lane with a deterministic mock OpenAI provider, avoiding the need for real model-provider credentials.

```bash
pnpm openclaw qa matrix --provider-mode mock-openai
```

--------------------------------

### Configure local model provider (JSON5)

Source: https://docs.openclaw.ai/concepts/model-providers/custom-providers.md

Defines a local provider (e.g., lmstudio) with base URL, API key, and model settings. Optional fields like reasoning, input, cost, contextWindow, and maxTokens have defaults when omitted.

```json5
{
  agents: {
    defaults: {
      model: { primary: "lmstudio/my-local-model" },
      models: { "lmstudio/my-local-model": { alias: "Local" } },
    },
  },
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://localhost:1234/v1",
        apiKey: "${LM_API_TOKEN}",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 200000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}
```

--------------------------------

### Explain promotion CLI command

Source: https://docs.openclaw.ai/concepts/dreaming.md

CLI command to explain why a specific candidate would or would not promote, with optional JSON output.

```bash
openclaw memory promote-explain "router vlan"
openclaw memory promote-explain "router vlan" --json
```

--------------------------------

### Memory promotion preview and apply CLI commands

Source: https://docs.openclaw.ai/concepts/dreaming.md

CLI commands to preview or apply memory promotion, limit the number of promotions, and check deep status. Manual promote uses deep-phase thresholds by default unless overridden with flags.

```bash
openclaw memory promote
openclaw memory promote --apply
openclaw memory promote --limit 5
openclaw memory status --deep
```

--------------------------------

### Query mode full context

Source: https://docs.openclaw.ai/concepts/active-memory/tuning.md

Shows the context sent in `full` query mode: the entire conversation. Use when recall quality matters more than latency or important setup is far back in the thread.

```text
Full conversation context:
user: ...
assistant: ...
user: ...
...
```

--------------------------------

### Set agent-level default typing mode and interval

Source: https://docs.openclaw.ai/concepts/typing-indicators.md

Configures the default typing behavior for all agents. `typingMode` controls when typing starts, `typingIntervalSeconds` controls the refresh cadence (default 6 seconds).

```json5
{
  agents: {
    defaults: {
      typingMode: "thinking",
      typingIntervalSeconds: 6,
    },
  },
}
```

--------------------------------

### Restart gateway and verify agents and channels

Source: https://docs.openclaw.ai/concepts/multi-agent.md

Run these commands to restart the gateway and verify the agent bindings and channel status. This is the final step after configuring agents, accounts, and bindings.

```bash
openclaw gateway restart
openclaw agents list --bindings
openclaw channels status --probe
```

--------------------------------

### session_status response with changesSince

Source: https://docs.openclaw.ai/concepts/session-state.md

Example JSON response from session_status with changesSince, returning typed events after the given version (up to 200) without advancing cursors. historyGap: false indicates the response is an exact delta.

```json
{
  "stateVersion": 19,
  "stateChanges": {
    "events": [
      {
        "sequence": 14,
        "kind": "human_direct_message",
        "actorType": "human",
        "summary": "human message via telegram"
      },
      { "sequence": 19, "kind": "goal_changed", "actorType": "human", "summary": "goal updated" }
    ],
    "historyGap": false
  }
}
```

--------------------------------

### Exported transcript artifact path

Source: https://docs.openclaw.ai/concepts/active-memory/advanced-options.md

Shows the path pattern for exported transcript artifacts. Agent ids are URI-encoded; for example, support/agent becomes support%2Fagent. Change the final artifact subdirectory with config.transcriptDir.

```text
<state-dir>/plugins/active-memory/transcripts/agents/<encoded-agent>/active-memory/<blocking-memory-sub-agent-session-id>.jsonl
```

--------------------------------

### Use --profile and --source-profile together

Source: https://docs.openclaw.ai/concepts/managed-worktrees.md

The existing --profile option selects runtime state; --source-profile only selects repository source. Both can be used in the same command.

```bash
openclaw --profile work worktrees create /path/to/repo --name task --source-profile gateway
```

--------------------------------

### Register a custom context engine with the plugin API

Source: https://docs.openclaw.ai/concepts/context-engine.md

Shows how to use `api.registerContextEngine` to define a custom engine with `ingest`, `assemble`, `compact`, and `commitTurn` lifecycle methods. The `buildMemorySystemPromptAddition` helper is imported from the SDK and must be used synchronously after the host completes async memory prompt preparation. The factory `ctx` provides optional `config`, `agentDir`, and `workspaceDir` for per-agent or per-workspace initialization.

```TypeScript
import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";

// `buildContext`, `countTokens`, and `commitAcceptedTurn` below are your own
// plugin's helpers to implement. They are not part of the plugin SDK.
// `buildMemorySystemPromptAddition` is real SDK surface, imported above.

export default function register(api) {
  api.registerContextEngine("my-engine", (ctx) => ({
    info: {
      id: "my-engine",
      name: "My Context Engine",
      ownsCompaction: true,
      acceptedHostParams: ["sessionKey", "runtimeContext"],
      transcriptSemantics: {
        currentTurnFence: "before-current-turn-entry-v1",
        turnAdvancementIdempotency: "atomic-idempotent-v1",
      },
    },

    async ingest({ sessionId, message, isHeartbeat }) {
      // Store the message in your data store
      return { ingested: true };
    },

    async assemble({
      sessionId,
      sessionKey,
      messages,
      tokenBudget,
      availableTools,
      citationsMode,
    }) {
      // Return messages that fit the budget
      return {
        messages: buildContext(messages, tokenBudget),
        estimatedTokens: countTokens(messages),
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
          agentSessionKey: sessionKey,
        }),
      };
    },

    async compact({ sessionId, force }) {
      // Summarize older context
      return { ok: true, compacted: true };
    },

    async commitTurn({ advancementKey, messages }) {
      // Atomically store the accepted turn and advancementKey. Return
      // "duplicate" when that exact key was committed by an earlier retry.
      return await commitAcceptedTurn({
        advancementKey,
        messages,
      });
    },
  }));
}
```

--------------------------------

### Set OpenAI primary model in agent defaults

Source: https://docs.openclaw.ai/concepts/model-providers/official-provider-plugins.md

Configures the default primary model to openai/gpt-6-astra in the agent defaults. This is used for fresh setups; if the API organization does not expose GPT-5.6, set openai/gpt-5.5 explicitly.

```json5
{
  agents: { defaults: { model: { primary: "openai/gpt-6-astra" } } },
}
```

--------------------------------

### Cerebras provider setup for active memory

Source: https://docs.openclaw.ai/concepts/active-memory/tuning.md

Shows a Cerebras provider configuration for active memory, setting a dedicated fast model. Requires `CEREBRAS_API_KEY` and the API key must have `chat/completions` access for the chosen model.

```json5
{
  models: {
    providers: {
      cerebras: {
        baseUrl: "https://api.cerebras.ai/v1",
        apiKey: "${CEREBRAS_API_KEY}",
        api: "openai-completions",
        models: [{ id: "gpt-oss-120b", name: "GPT OSS 120B (Cerebras)" }],
      },
    },
  },
  plugins: {
    entries: {
      "active-memory": {
        enabled: true,
        config: { model: "cerebras/gpt-oss-120b" },
      },
    },
  },
}
```

--------------------------------

### /compact command with focus instruction

Source: https://docs.openclaw.ai/concepts/compaction.md

Use this command in the built-in OpenClaw runtime to force compaction and guide the summary with focus instructions. In native Codex sessions, use bare /compact without focus instructions.

```text
/compact Focus on the API design decisions
```

--------------------------------

### Configure Lossless Claw with Active Memory (JSON5)

Source: https://docs.openclaw.ai/concepts/active-memory/memory-tools.md

Merge this JSON5 configuration into the agent's existing tool configuration. It keeps the 'coding' profile and adds the three Lossless Claw tools via 'alsoAllow'. Assumes agent scope does not define 'tools.allow' because 'allow' and 'alsoAllow' cannot be combined. Do not add 'lcm_expand' to 'toolsAllow' as it is a lower-level tool for delegated expansion.

```json5
{
  agents: {
    entries: {
      main: {
        tools: {
          profile: "coding",
          alsoAllow: ["lcm_grep", "lcm_describe", "lcm_expand_query"],
        },
      },
    },
  },
  plugins: {
    slots: {
      contextEngine: "lossless-claw",
    },
    entries: {
      "lossless-claw": {
        enabled: true,
      },
      "active-memory": {
        enabled: true,
        config: {
          agents: ["main"],
          toolsAllow: ["memory_search", "lcm_grep", "lcm_describe", "lcm_expand_query"],
          promptAppend: "Use lcm_grep first for compacted conversation recall. Use lcm_describe to inspect a specific summary. Use lcm_expand_query only when the latest user message needs exact details that may have been compacted away. Return NONE if the retrieved context is not clearly useful.",
        },
      },
    },
  },
}
```

--------------------------------

### Server handler for system.echo

Source: https://docs.openclaw.ai/concepts/typebox.md

Adds a handler that responds with { ok: true, text } echoing the provided text.

```ts
export const systemHandlers: GatewayRequestHandlers = {
  "system.echo": ({ params, respond }) => {
    const text = String(params.text ?? "");
    respond(true, { ok: true, text });
  },
};
```

--------------------------------

### Enable rememberAcrossConversations in agent config

Source: https://docs.openclaw.ai/concepts/active-memory/enabling.md

Set `rememberAcrossConversations: true` for the `personal` agent to enable cross-conversation recall. Defaults on for personal installs when `session.dmScope` is unset or `"main"` and no binding overrides it. Explicit true/false always wins.

```json5
{
  agents: {
    entries: {
      personal: {
        memory: {
          search: {
            rememberAcrossConversations: true,
          },
        },
      },
    },
  },
}
```

--------------------------------

### Call decision_evaluate with state and questions map

Source: https://docs.openclaw.ai/concepts/decision-models.md

Example JSON payload for the decision_evaluate tool. It includes shared state and a questions map with boolean, choice, and score question types. Each question sees the same state and cannot see other answers in the batch.

```json
{
  "state": { "message": "Checkout is failing for all customers." },
  "questions": {
    "escalate": {
      "type": "boolean",
      "instructions": "Does this need incident response?",
      "criteria": {
        "true": { "includes": ["Widespread service outages"] },
        "false": "A routine request can follow normal handling"
      }
    },
    "route": {
      "type": "choice",
      "criteria": { "support": "Service failures", "billing": "Payment questions" }
    },
    "urgency": {
      "type": "score",
      "criteria": ["No disruption", "One workflow blocked", "Widespread outage"]
    }
  }
}
```

--------------------------------

### Export VLLM_API_KEY for auto-discovery

Source: https://docs.openclaw.ai/concepts/model-providers/custom-providers.md

Sets the VLLM_API_KEY environment variable to opt in to local auto-discovery; any value works if the server doesn't enforce auth.

```bash
export VLLM_API_KEY="vllm-local"
```