### Install LiteLLM Proxy and Start Proxy

Source: https://docs.openclaw.ai/providers/litellm

Installs the LiteLLM proxy with necessary dependencies and starts the LiteLLM proxy service, making it ready to accept connections.

```bash
pip install 'litellm[proxy]'
litellm --model claude-opus-4-6
```

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

### OpenClaw: Anthropic Token Setup Example

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

Example demonstrating the setup process for Anthropic's token authentication, followed by checking the model status using the OpenClaw CLI. This illustrates a common workflow for integrating specific provider authentication.

```bash
claude setup-token
openclaw models status
```

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

### Run Interactive Onboarding

Source: https://docs.openclaw.ai/cli/setup

Triggers the interactive setup wizard to guide the user through the configuration process.

```bash
openclaw setup --wizard
```

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

### Start and Install Node Host

Source: https://docs.openclaw.ai/nodes

Commands to initiate a node host in the foreground or install it as a persistent service. This allows the gateway to route system commands to remote machines.

```bash
openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"
openclaw node install --host <gateway-host> --port 18789 --display-name "Build Node"
openclaw node restart
```

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

### Install OpenClaw on VM

Source: https://docs.openclaw.ai/install/azure

Downloads and executes the OpenClaw installation script from a URL. It installs Node LTS and dependencies if they are not present, then installs OpenClaw and starts the onboarding wizard. The script is removed after execution.

```bash
curl -fsSL https://openclaw.ai/install.sh -o /tmp/install.sh
bash /tmp/install.sh
rm -f /tmp/install.sh
```

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

### Install Binaries in Dockerfile

Source: https://docs.openclaw.ai/install/docker-vm-runtime

This Dockerfile example demonstrates how to install necessary binaries like gog, goplans, and wacli at image build time. It ensures these tools are available within the container and persist across restarts. The process involves downloading, extracting, and placing binaries in /usr/local/bin.

```dockerfile
FROM node:24-bookworm

RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*

# Example binary 1: Gmail CLI
RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/gog

# Example binary 2: Google Places CLI
RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/goplaces

# Example binary 3: WhatsApp CLI
RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli

# Add more binaries below using the same pattern

WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts

RUN corepack enable
RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build

ENV NODE_ENV=production

CMD ["node","dist/index.js"]
```

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

### Setup OpenClaw Podman Environment

Source: https://docs.openclaw.ai/install/podman

Executes the setup script to create a dedicated user, build the container image, and install launch scripts. Use the --quadlet flag for production-style systemd service management.

```bash
./scripts/podman/setup.sh
./scripts/podman/setup.sh --quadlet
```

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

### Manual LiteLLM Proxy Setup

Source: https://docs.openclaw.ai/providers/litellm

Steps to manually set up and start the LiteLLM proxy server.

```APIDOC
## Manual LiteLLM Proxy Setup

### Description
Manually set up and start the LiteLLM proxy server for integration with OpenClaw.

### Method
CLI Commands

### Endpoint
N/A

### Parameters
None

### Request Example
```bash
pip install 'litellm[proxy]'
litellm --model claude-opus-4-6
```

### Response
N/A
```

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

### Install Dependencies and Start Gateway Watch

Source: https://docs.openclaw.ai/start/setup

Installs project dependencies using pnpm and starts the Gateway in watch mode. This is the primary command for the bleeding-edge workflow, enabling hot-reloading.

```bash
pnpm install
pnpm gateway:watch
```

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

### Implement Channel Setup Wizard in TypeScript

Source: https://docs.openclaw.ai/plugins/sdk-setup

Provides an example of a `ChannelSetupWizard` object, defining how interactive setup for a channel plugin works. It includes status resolution, credential input, and inspection logic.

```typescript
import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup";

const setupWizard: ChannelSetupWizard = {
  channel: "my-channel",
  status: {
    configuredLabel: "Connected",
    unconfiguredLabel: "Not configured",
    resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),
  },
  credentials: [
    {
      inputKey: "token",
      providerHint: "my-channel",
      credentialLabel: "Bot token",
      preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",
      envPrompt: "Use MY_CHANNEL_BOT_TOKEN from environment?",
      keepPrompt: "Keep current token?",
      inputPrompt: "Enter your bot token:",
      inspect: ({ cfg, accountId }) => {
        const token = (cfg.channels as any)?.["my-channel"]?.token;
        return {
          accountConfigured: Boolean(token),
          hasConfiguredValue: Boolean(token),
        };
      },
    },
  ],
};
```

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

### Onboard OpenClaw with Setup Token Authentication

Source: https://docs.openclaw.ai/providers/anthropic

This command initiates the OpenClaw onboarding process, specifically choosing the setup token method for authentication. It guides the user through setting up a new agent or service with Anthropic.

```bash
openclaw onboard --auth-choice setup-token
```

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

### OpenClaw Configuration Example with Groq (JSON5)

Source: https://docs.openclaw.ai/providers/groq

An example configuration file for OpenClaw that includes setting the Groq API key and specifying a default model. This demonstrates how to integrate Groq credentials and model preferences into the OpenClaw setup.

```json5
{
  env: { GROQ_API_KEY: "gsk_..." },
  agents: {
    defaults: {
      model: { primary: "groq/llama-3.3-70b-versatile" },
    },
  },
}
```

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

### Install Homebrew on Linux

Source: https://docs.openclaw.ai/help/faq

This command provides a quick setup for installing Homebrew (Linuxbrew) on a Linux system. Homebrew is a package manager that simplifies software installation.

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

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

### Migrate Single Agent to Multi-Agent Configuration (JSON)

Source: https://docs.openclaw.ai/tools/multi-agent-sandbox-tools

Demonstrates the transformation from a single-agent configuration to a multi-agent setup with distinct profiles. The 'Before' example shows a basic single-agent setup, while the 'After' example illustrates a multi-agent structure where the 'main' agent is configured with sandbox mode turned off.

```json
{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "sandbox": {
        "mode": "non-main"
      }
    }
  },
  "tools": {
    "sandbox": {
      "tools": {
        "allow": ["read", "write", "apply_patch", "exec"],
        "deny": []
      }
    }
  }
}
```

```json
{
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "workspace": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      }
    ]
  }
}
```

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

### Onboard and Install OpenClaw Service

Source: https://docs.openclaw.ai/

Executes the OpenClaw onboarding process, which includes setting up the service as a daemon. This command guides users through initial configuration and service installation.

```bash
openclaw onboard --install-daemon

```

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

### Setup Entry Point

Source: https://docs.openclaw.ai/plugins/sdk-setup

Defines the `setup-entry.ts` file, a lightweight alternative to `index.ts` for OpenClaw setup surfaces. It avoids loading heavy runtime code during setup flows.

```APIDOC
## Setup entry

The `setup-entry.ts` file is a lightweight alternative to `index.ts` that
OpenClaw loads when it only needs setup surfaces (onboarding, config repair,
disabled channel inspection).

```typescript
// setup-entry.ts
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/core";
import { myChannelPlugin } from "./src/channel.js";

export default defineSetupPluginEntry(myChannelPlugin);
```

This avoids loading heavy runtime code (crypto libraries, CLI registrations,
background services) during setup flows.

**When OpenClaw uses `setupEntry` instead of the full entry:**

* The channel is disabled but needs setup/onboarding surfaces
* The channel is enabled but unconfigured
* Deferred loading is enabled (`deferConfiguredChannelFullLoadUntilAfterListen`)

**What `setupEntry` must register:**

* The channel plugin object (via `defineSetupPluginEntry`)
* Any HTTP routes required before gateway listen
* Any gateway methods needed during startup

**What `setupEntry` should NOT include:**

* CLI registrations
* Background services
* Heavy runtime imports (crypto, SDKs)
* Gateway methods only needed after startup
```

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

### OpenClaw Matrix Channel Interactive Setup

Source: https://docs.openclaw.ai/channels/matrix

Commands to initiate the interactive setup for adding and configuring Matrix channels within OpenClaw. These commands guide the user through the necessary configuration steps.

```bash
openclaw channels add
```

```bash
openclaw configure --section channels
```

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

### Standard Installation and Onboarding

Source: https://docs.openclaw.ai/help/faq

Performs a standard installation of the OpenClaw software and initiates the onboarding wizard to configure the daemon and UI assets.

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

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

### Install OpenClaw Gateway (Bash)

Source: https://docs.openclaw.ai/install/oracle

Downloads and executes the OpenClaw installation script. It then sources the bashrc file to make OpenClaw commands available in the current session. Users are prompted to defer gateway setup.

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

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

### Install and Run OpenClaw

Source: https://docs.openclaw.ai/install/raspberry-pi

Downloads the installation script, runs the onboarding wizard, and verifies the service status.

```bash
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw status
sudo systemctl status openclaw
journalctl -u openclaw -f
```

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

### Install Plugin

Source: https://docs.openclaw.ai/plugins/sdk-setup

Install a plugin from a specified source or the default registry.

```APIDOC
## POST /plugins/install

### Description
Installs a plugin package. Defaults to ClawHub, with fallback to npm. Supports explicit source selection.

### Method
CLI Command

### Endpoint
openclaw plugins install [source:]<package-name>

### Parameters
#### Path Parameters
- **package-name** (string) - Required - The name of the plugin package to install.

#### Query Parameters
- **source** (string) - Optional - Specify 'clawhub:' or 'npm:' to force a specific registry.

### Request Example
openclaw plugins install @myorg/openclaw-my-plugin

### Response
#### Success Response (200)
- **status** (string) - Confirmation of successful installation.
```

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

### OpenClaw Matrix Channel Setup

Source: https://docs.openclaw.ai/channels/matrix

Configuration examples for setting up the Matrix channel in OpenClaw. Supports token-based and password-based authentication, with options for DM policies and E2EE.

```json
{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      dm: { policy: "pairing" },
    },
  },
}
```

```json
{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      userId: "@bot:example.org",
      password: "replace-me",
      deviceName: "OpenClaw Gateway",
    },
  },
}
```

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

### Execute Provider Login Examples

Source: https://docs.openclaw.ai/cli/models

Practical examples for authenticating with specific providers like Anthropic or OpenAI, including setting default models and using CLI-based login methods.

```bash
openclaw models auth login --provider anthropic --method cli --set-default
openclaw models auth login --provider openai-codex --set-default
```

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

### Install OpenClaw using Script (macOS/Linux/WSL2)

Source: https://docs.openclaw.ai/install

Installs OpenClaw using a curl command to download and execute an installation script. This method detects the OS, installs Node.js if needed, and sets up OpenClaw. The `--no-onboard` flag can be used to skip the onboarding process.

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

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

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

### Install Docker and Verify

Source: https://docs.openclaw.ai/install/gcp

Installs Docker on the remote VM, adds the current user to the docker group for permission management, and verifies the installation.

```bash
sudo apt-get update
sudo apt-get install -y git curl ca-certificates
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
exit
gcloud compute ssh openclaw-gateway --zone=us-central1-a
docker --version
docker compose version
```

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

### Search and Install Plugins

Source: https://docs.openclaw.ai/plugins/sdk-setup

Commands to search for available plugins using a query string and install them by their package name.

```bash
openclaw plugins search <query>
openclaw plugins install <package-name>
```

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

### Setup Wizards for Channel Plugins

Source: https://docs.openclaw.ai/plugins/sdk-setup

Details how channel plugins can provide interactive setup wizards for `openclaw onboard` using the `ChannelSetupWizard` object.

```APIDOC
## Setup wizards

Channel plugins can provide interactive setup wizards for `openclaw onboard`.
The wizard is a `ChannelSetupWizard` object on the `ChannelPlugin`:

```typescript
import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup";

const setupWizard: ChannelSetupWizard = {
  channel: "my-channel",
  status: {
    configuredLabel: "Connected",
    unconfiguredLabel: "Not configured",
    resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),
  },
  credentials: [
    {
      inputKey: "token",
      providerHint: "my-channel",
      credentialLabel: "Bot token",
      preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",
      envPrompt: "Use MY_CHANNEL_BOT_TOKEN from environment?",
      keepPrompt: "Keep current token?",
      inputPrompt: "Enter your bot token:",
      inspect: ({ cfg, accountId }) => {
        const token = (cfg.channels as any)?.["my-channel"]?.token;
        return {
          accountConfigured: Boolean(token),
          hasConfiguredValue: Boolean(token),
        };
      },
    },
  ],
};
```

The `ChannelSetupWizard` type supports `credentials`, `textInputs`,
`dmPolicy`, `allowFrom`, `groupAccess`, `prepare`, `finalize`, and more.
See bundled plugins (e.g. `extensions/discord/src/channel.setup.ts`) for
full examples.

For DM allowlist prompts that only need the standard
`note -> prompt -> parse -> merge -> patch` flow, prefer the shared setup
helpers from `openclaw/plugin-sdk/setup`: `createPromptParsedAllowFromForAccount(...)`,
`createTopLevelChannelParsedAllowFromPrompt(...)`, and
`createNestedChannelParsedAllowFromPrompt(...)`.

For channel setup status blocks that only vary by labels, scores, and optional
extra lines, prefer `createStandardChannelSetupStatus(...)` from
`openclaw/plugin-sdk/setup` instead of hand-rolling the same `status` object in
each plugin.

For optional setup surfaces that should only appear in certain contexts, use
`createOptionalChannelSetupSurface` from `openclaw/plugin-sdk/channel-setup`:

```typescript
import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup";

const setupSurface = createOptionalChannelSetupSurface({
  channel: "my-channel",
  label: "My Channel",
  npmSpec: "@myorg/openclaw-my-channel",
  docsPath: "/channels/my-channel",
});
// Returns { setupAdapter, setupWizard }
```
```

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

### Build and Develop Control UI

Source: https://docs.openclaw.ai/web/control-ui

Commands to build the static UI files for production or start a development server for local testing. The build process automatically installs dependencies on the first run.

```bash
pnpm ui:build
```

```bash
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
```

```bash
pnpm ui:dev
```

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

### Tool Execution Examples

Source: https://docs.openclaw.ai/tools/exec

Examples demonstrating different ways to execute tools, including foreground commands, background processes with polling, and sending keys.

```APIDOC
## Foreground Command Execution

### Description
Executes a command in the foreground.

### Method
POST

### Endpoint
/execute

### Request Body
- **tool** (string) - Required - The tool to use, e.g., "exec".
- **command** (string) - Required - The command to execute.

### Request Example
```json
{
  "tool": "exec",
  "command": "ls -la"
}
```

## Background Process with Polling

### Description
Starts a background process and polls for its completion.

### Method
POST

### Endpoint
/execute

### Request Body
- **tool** (string) - Required - The tool to use, e.g., "exec".
- **command** (string) - Required - The command to execute.
- **yieldMs** (integer) - Optional - The polling interval in milliseconds.
- **action** (string) - Required - The action to perform, e.g., "poll".
- **sessionId** (string) - Required - The session ID of the process to poll.

### Request Example
```json
{
  "tool": "exec",
  "command": "npm run build",
  "yieldMs": 1000
}
```
```json
{
  "tool": "process",
  "action": "poll",
  "sessionId": "<id>"
}
```

## Sending Keys to a Process (tmux-style)

### Description
Sends key presses to a running process, mimicking tmux keybindings.

### Method
POST

### Endpoint
/execute

### Request Body
- **tool** (string) - Required - The tool to use, e.g., "process".
- **action** (string) - Required - The action to perform, "send-keys".
- **sessionId** (string) - Required - The session ID of the process.
- **keys** (array of strings) - Required - An array of keys to send.

### Request Example
```json
{
  "tool": "process",
  "action": "send-keys",
  "sessionId": "<id>",
  "keys": ["Enter"]
}
```
```json
{
  "tool": "process",
  "action": "send-keys",
  "sessionId": "<id>",
  "keys": ["C-c"]
}
```
```json
{
  "tool": "process",
  "action": "send-keys",
  "sessionId": "<id>",
  "keys": ["Up", "Up", "Enter"]
}
```

## Submitting Input to a Process (send CR only)

### Description
Submits input to a process by sending only a carriage return (CR).

### Method
POST

### Endpoint
/execute

### Request Body
- **tool** (string) - Required - The tool to use, "process".
- **action** (string) - Required - The action to perform, "submit".
- **sessionId** (string) - Required - The session ID of the process.

### Request Example
```json
{
  "tool": "process",
  "action": "submit",
  "sessionId": "<id>"
}
```

## Pasting Text into a Process

### Description
Pastes text into a running process. Supports multi-line text.

### Method
POST

### Endpoint
/execute

### Request Body
- **tool** (string) - Required - The tool to use, "process".
- **action** (string) - Required - The action to perform, "paste".
- **sessionId** (string) - Required - The session ID of the process.
- **text** (string) - Required - The text to paste.

### Request Example
```json
{
  "tool": "process",
  "action": "paste",
  "sessionId": "<id>",
  "text": "line1\nline2\n"
}
```
```

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

### Manual Docker Flow for OpenClaw Gateway

Source: https://docs.openclaw.ai/install/docker

Executes the OpenClaw gateway setup steps manually without using the setup script. This involves building the Docker image, running onboarding and configuration commands, and starting the gateway service.

```bash
docker build -t openclaw:local -f Dockerfile .
docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js onboard --mode local --no-install-daemon
docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js config set gateway.mode local
docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js config set gateway.bind lan
docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js config set gateway.controlUi.allowedOrigins \
  '["http://localhost:18789","http://127.0.0.1:18789"]' --strict-json
docker compose up -d openclaw-gateway
```

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

### OpenClaw Teams Plugin Setup

Source: https://docs.openclaw.ai/channels/msteams

Steps to install the Microsoft Teams plugin for OpenClaw and configure bot registration.

```APIDOC
## Setup (minimal text-only)

1. **Install the Microsoft Teams plugin**
   * From npm: `openclaw plugins install @openclaw/msteams`
   * From a local checkout: `openclaw plugins install ./extensions/msteams`

2. **Bot registration**
   * Create an Azure Bot and note:
     * App ID
     * Client secret (App password)
     * Tenant ID (single-tenant)
```

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

### Hello-Ok Response Example

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

Example of the `hello-ok` response frame sent by the Gateway after a successful `connect` request.

```APIDOC
## WebSocket Response (hello-ok)

### Description
Response from the Gateway confirming a successful connection handshake.

### Method
WebSocket Frame (Response)

### Endpoint
WebSocket Connection

### Response
#### Success Response (hello-ok)
- **type** (string) - Description: Must be "res".
- **id** (string) - Description: The ID of the original `connect` request.
- **ok** (boolean) - Description: True if the connection was successful.
- **payload** (object) - Description: The `hello-ok` payload.
  - **type** (string) - Description: Must be "hello-ok".
  - **protocol** (integer) - Description: The negotiated protocol version.
  - **server** (object) - Description: Server information.
    - **version** (string) - Description: Server version.
    - **connId** (string) - Description: Unique connection identifier.
  - **features** (object) - Description: Supported features.
    - **methods** (array of strings) - Description: List of supported methods.
    - **events** (array of strings) - Description: List of supported events.
  - **snapshot** (object) - Description: Initial state snapshots.
  - **policy** (object) - Description: Connection policy details.
    - **maxPayload** (integer) - Description: Maximum allowed payload size in bytes.
    - **maxBufferedBytes** (integer) - Description: Maximum buffered bytes.
    - **tickIntervalMs** (integer) - Description: Interval for `tick` events in milliseconds.

#### Response Example
```json
{
  "type": "res",
  "id": "c1",
  "ok": true,
  "payload": {
    "type": "hello-ok",
    "protocol": 2,
    "server": { "version": "dev", "connId": "ws-1" },
    "features": { "methods": ["health"], "events": ["tick"] },
    "snapshot": {
      "presence": [],
      "health": {},
      "stateVersion": { "presence": 0, "health": 0 },
      "uptimeMs": 0
    },
    "policy": { "maxPayload": 1048576, "maxBufferedBytes": 1048576, "tickIntervalMs": 30000 }
  }
}
```
```

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

### Manage Gateway Service Lifecycle

Source: https://docs.openclaw.ai/cli/gateway

Standard service management commands to install, start, stop, restart, and uninstall the gateway service.

```bash
openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall
```

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

### Install and Configure Tailscale (Bash)

Source: https://docs.openclaw.ai/install/oracle

Downloads and installs Tailscale using the official script, then configures it to connect to the Tailscale network with SSH enabled and sets the hostname. Subsequent connections can be made via Tailscale.

```bash
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up --ssh --hostname=openclaw
```

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

### Install OpenClaw Gateway on Ubuntu

Source: https://docs.openclaw.ai/install/digitalocean

Updates the system, installs Node.js 24, and downloads the OpenClaw installation script to set up the environment.

```bash
ssh root@YOUR_DROPLET_IP

apt update && apt upgrade -y

# Install Node.js 24
curl -fsSL https://deb.nodesource.com/setup_24.x | bash -
apt install -y nodejs

# Install OpenClaw
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw --version
```

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

### Basic Openclaw Onboarding

Source: https://docs.openclaw.ai/cli/onboard

Demonstrates the basic 'openclaw onboard' command and its common flow options like 'quickstart' and 'manual'. It also shows how to specify a remote gateway URL.

```bash
openclaw onboard
openclaw onboard --flow quickstart
openclaw onboard --flow manual
openclaw onboard --mode remote --remote-url wss://gateway-host:18789
```

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

### Install OpenClaw Plugins

Source: https://docs.openclaw.ai/cli/plugins

Demonstrates various ways to install OpenClaw plugins, including from ClawHub, npm, local paths, and marketplaces. It covers options for pinning versions and specifying sources.

```bash
openclaw plugins install <package>                      # ClawHub first, then npm
openclaw plugins install clawhub:<package>              # ClawHub only
openclaw plugins install <package> --pin                # pin version
openclaw plugins install <path>                         # local path
openclaw plugins install <plugin>@<marketplace>         # marketplace
openclaw plugins install <plugin> --marketplace <name>  # marketplace (explicit)
```

```bash
openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
```

```bash
openclaw plugins install openclaw-codex-app-server
```

```bash
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
```

```bash
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
openclaw plugins install <plugin-name> --marketplace <owner/repo>
openclaw plugins install <plugin-name> --marketplace ./my-marketplace
```

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

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

### OpenClaw Plugin Configuration (`package.json`)

Source: https://docs.openclaw.ai/plugins/architecture

Defines the main entry points for an OpenClaw plugin, specifying extensions and an optional setup entry. Dependencies must be installed locally within the plugin directory.

```json
{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"],
    "setupEntry": "./src/setup-entry.ts"
  }
}
```

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

### Install OpenClaw WhatsApp Plugin

Source: https://docs.openclaw.ai/channels/whatsapp

Command to manually install the OpenClaw WhatsApp plugin from npm. This is an alternative to the on-demand installation prompted during onboarding or channel setup.

```bash
openclaw plugins install @openclaw/whatsapp
```

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

### Installing OpenClaw via Script

Source: https://docs.openclaw.ai/install/exe-dev

Executes the official OpenClaw installation script to set up the environment on the VM.

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

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

### Verify Gateway installation and start service

Source: https://docs.openclaw.ai/platforms/mac/bundled-gateway

Checks the installed version of the OpenClaw CLI and starts the Gateway service on a specific port and bind address. The environment variables are used to skip optional features during the smoke test.

```bash
openclaw --version

OPENCLAW_SKIP_CHANNELS=1 \
OPENCLAW_SKIP_CANVAS_HOST=1 \
openclaw gateway --port 18999 --bind loopback
```

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

### Comprehensive CLI Backend Configuration Example

Source: https://docs.openclaw.ai/gateway/cli-backends

Provides a detailed example of configuring a custom CLI backend ('my-cli') with various options, including command arguments, output parsing, model aliasing, session handling, and system prompt arguments.

```json5
{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          input: "arg",
          modelArg: "--model",
          modelAliases: {
            "claude-opus-4-6": "opus",
            "claude-opus-4-6": "opus",
            "claude-sonnet-4-6": "sonnet",
          },
          sessionArg: "--session",
          sessionMode: "existing",
          sessionIdFields: ["session_id", "conversation_id"],
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}
```

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

### Multi-account Example

Source: https://docs.openclaw.ai/channels/matrix

Configuration example for setting up and managing multiple Matrix accounts within OpenClaw, including default account selection and account-specific settings.

```APIDOC
## Multi-account example

```json5
{
  "channels": {
    "matrix": {
      "enabled": true,
      "defaultAccount": "assistant",
      "dm": {"policy": "pairing"},
      "accounts": {
        "assistant": {
          "homeserver": "https://matrix.example.org",
          "accessToken": "syt_assistant_xxx",
          "encryption": true,
        },
        "alerts": {
          "homeserver": "https://matrix.example.org",
          "accessToken": "syt_alerts_xxx",
          "dm": {
            "policy": "allowlist",
            "allowFrom": ["@ops:example.org"],
          },
        },
      },
    },
  },
}
```

Top-level `channels.matrix` values act as defaults for named accounts unless an account overrides them.
Set `defaultAccount` when you want OpenClaw to prefer one named Matrix account for implicit routing, probing, and CLI operations.
If you configure multiple named accounts, set `defaultAccount` or pass `--account <id>` for CLI commands that rely on implicit account selection.
Pass `--account <id>` to `openclaw matrix verify ...` and `openclaw matrix devices ...` when you want to override that implicit selection for one command.
```

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

### Initialize Development Profile

Source: https://docs.openclaw.ai/gateway

Quick setup commands to initialize a development environment with isolated state and configuration.

```bash
openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
```

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

### Install and Configure Ollama

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

Instructions for installing Ollama and pulling a model, followed by a configuration snippet to set Ollama as the default model provider. No API key is required for local Ollama servers.

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

```json
{
  "agents": {
    "defaults": { "model": { "primary": "ollama/llama3.3" } },
  },
}
```

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

### Manual Development Install (Clone and Build)

Source: https://docs.openclaw.ai/help/faq

Clones the OpenClaw repository from GitHub, installs dependencies using pnpm, and builds the project. This method provides a local repository for development and modification.

```bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
```

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

### Install Node.js on Ubuntu/Debian

Source: https://docs.openclaw.ai/install/node

Installs Node.js version 24.x on Ubuntu and Debian-based systems using NodeSource repositories. This involves fetching a setup script and then installing the nodejs package.

```bash
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs
```

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

### Install OpenClaw using Script (Windows PowerShell)

Source: https://docs.openclaw.ai/install

Installs OpenClaw on Windows using PowerShell to download and execute an installation script. This method handles OS detection and Node.js installation. The `-NoOnboard` parameter can be used to bypass the onboarding flow.

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

```powershell
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
```

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

### Create Optional Channel Setup Surface in TypeScript

Source: https://docs.openclaw.ai/plugins/sdk-setup

Demonstrates using `createOptionalChannelSetupSurface` to define setup surfaces that appear conditionally. This function helps in creating reusable setup adapters and wizards.

```typescript
import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup";

const setupSurface = createOptionalChannelSetupSurface({
  channel: "my-channel",
  label: "My Channel",
  npmSpec: "@myorg/openclaw-my-channel",
  docsPath: "/channels/my-channel",
});
// Returns { setupAdapter, setupWizard }
```

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

### Install Synology Chat Plugin

Source: https://docs.openclaw.ai/channels/synology-chat

Install the Synology Chat plugin from a local directory using the OpenClaw CLI.

```bash
openclaw plugins install ./extensions/synology-chat
```

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

### CLI Setup for OpenCode Go

Source: https://docs.openclaw.ai/providers/opencode-go

This snippet shows how to onboard and set up OpenCode Go using the command-line interface. It provides both interactive and non-interactive methods for configuring the OpenCode API key.

```bash
openclaw onboard --auth-choice opencode-go
# or non-interactive
openclaw onboard --opencode-go-api-key "$OPENCODE_API_KEY"
```

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

### Install Docker and Git on Ubuntu/Debian

Source: https://docs.openclaw.ai/install/hetzner

Installs necessary packages including Git, curl, and Docker on the Ubuntu or Debian VPS. It updates package lists and then installs Docker using the official convenience script.

```bash
apt-get update
apt-get install -y git curl ca-certificates
curl -fsSL https://get.docker.com | sh
```

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

### Running the Gateway

Source: https://docs.openclaw.ai/channels/msteams

Information on how the Teams channel automatically starts once the plugin is installed and configured.

```APIDOC
## Run the gateway
   * The Teams channel starts automatically when the plugin is installed and `msteams` config exists with credentials.
```

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

### Install OpenClaw from Source

Source: https://docs.openclaw.ai/install

Installs OpenClaw by cloning the repository, installing dependencies, building the project, and linking it globally. This method is suitable for developers or users who need to work with the latest code from the main branch.

```bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install && pnpm ui:build && pnpm build
pnpm link --global
openclaw onboard --install-daemon
```

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

### Store Wizard Setup Metadata

Source: https://docs.openclaw.ai/gateway/configuration-reference

Records metadata from CLI-guided setup flows, including the last run timestamp, version, commit hash, command, and mode.

```json5
{
  wizard: {
    lastRunAt: "2026-01-01T00:00:00.000Z",
    lastRunVersion: "2026.1.4",
    lastRunCommit: "abc1234",
    lastRunCommand: "configure",
    lastRunMode: "local",
  },
}
```

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

### Define Setup Plugin Entry Point (TypeScript)

Source: https://docs.openclaw.ai/plugins/sdk-entrypoints

Use `defineSetupPluginEntry` for lightweight `setup-entry.ts` files. This function returns just the plugin object without runtime or CLI wiring, suitable for disabled, unconfigured, or deferred loading scenarios. Dependencies include the 'openclaw/plugin-sdk/core' module.

```typescript
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/core";

export default defineSetupPluginEntry(myChannelPlugin);
```

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

### Install Context Engine Plugin

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

Commands to install a context engine plugin from a remote repository or a local development directory.

```bash
openclaw plugins install @martian-engineering/lossless-claw
openclaw plugins install -l ./my-context-engine
```

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

### Install Node.js 24

Source: https://docs.openclaw.ai/install/raspberry-pi

Configures the NodeSource repository and installs Node.js version 24.

```bash
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
node --version
```

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

### Connect Request Example

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

Example of the initial `connect` request frame sent by a client to establish a WebSocket connection.

```APIDOC
## POST /connect (WebSocket)

### Description
Initiates a WebSocket connection with the Gateway. This is the first message a client must send.

### Method
WebSocket Frame (Request)

### Endpoint
WebSocket Connection

### Request Body
- **type** (string) - Required - Must be "req".
- **id** (string) - Required - Unique identifier for the request.
- **method** (string) - Required - Must be "connect".
- **params** (object) - Required - Connection parameters.
  - **minProtocol** (integer) - Required - Minimum supported protocol version.
  - **maxProtocol** (integer) - Required - Maximum supported protocol version.
  - **client** (object) - Required - Client information.
    - **id** (string) - Required - Client identifier (e.g., "openclaw-macos").
    - **displayName** (string) - Required - Human-readable name for the client.
    - **version** (string) - Required - Client version.
    - **platform** (string) - Optional - Client platform information.
    - **mode** (string) - Optional - Client mode (e.g., "ui").
    - **instanceId** (string) - Optional - Unique instance identifier for the client.

### Request Example
```json
{
  "type": "req",
  "id": "c1",
  "method": "connect",
  "params": {
    "minProtocol": 2,
    "maxProtocol": 2,
    "client": {
      "id": "openclaw-macos",
      "displayName": "macos",
      "version": "1.0.0",
      "platform": "macos 15.1",
      "mode": "ui",
      "instanceId": "A1B2"
    }
  }
}
```
```

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

### Setup xAI API Key with OpenClaw

Source: https://docs.openclaw.ai/providers/xai

This command-line snippet shows how to onboard the xAI provider by setting up your API key. It's a prerequisite for using Grok models.

```bash
openclaw onboard --auth-choice xai-api-key
```

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

### Install and Use Node.js with fnm

Source: https://docs.openclaw.ai/install/node

Demonstrates installing and switching to Node.js version 24 using fnm, a fast and cross-platform Node.js version manager. This is useful for managing multiple Node.js versions.

```bash
fnm install 24
fnm use 24
```

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

### Install Google Chrome on Linux for OpenClaw

Source: https://docs.openclaw.ai/tools/browser-linux-troubleshooting

Installs the official Google Chrome browser, which bypasses snap's AppArmor confinement issues. This is the recommended solution for OpenClaw browser control on Linux. It involves downloading the .deb package, installing it, and fixing any potential dependency errors.

```bash
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb
sudo apt --fix-broken install -y  # if there are dependency errors
```

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

### Bootstrap OpenClaw Setup

Source: https://docs.openclaw.ai/start/setup

Initializes the OpenClaw environment. This command should be run once to set up the necessary configurations and workspace.

```bash
openclaw setup
```

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

### Manage Gateway Service Lifecycle

Source: https://docs.openclaw.ai/gateway

Commands to install, start, and manage the OpenClaw gateway service on different operating systems.

```bash
# macOS (launchd)
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

# Linux (systemd user)
openclaw gateway install
systemctl --user enable --now openclaw-gateway[-<profile>].service
openclaw gateway status

# Linux (system service)
sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway[-<profile>].service
```

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

### OpenClaw Configuration Example

Source: https://docs.openclaw.ai/

An example JSON configuration for OpenClaw, demonstrating how to set up channel-specific rules, such as allowing specific phone numbers for WhatsApp and requiring mentions in group chats.

```json
{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15555550123"],
      "groups": { "*": { "requireMention": true } },
    },
  },
  "messages": { "groupChat": { "mentionPatterns": ["@openclaw"] } },
}

```

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

### Install OpenClaw CLI

Source: https://docs.openclaw.ai/

Installs the OpenClaw command-line interface globally using npm. This is the first step to setting up the OpenClaw gateway.

```bash
npm install -g openclaw@latest

```

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

### Install OpenClaw Prerequisites and Repository

Source: https://docs.openclaw.ai/install/ansible

Commands to update system packages, install Ansible and Git, and clone the OpenClaw repository to the local environment.

```bash
sudo apt update && sudo apt install -y ansible git
git clone https://github.com/openclaw/openclaw-ansible.git
cd openclaw-ansible
```

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

### Workflow File Example (.lobster)

Source: https://docs.openclaw.ai/tools/lobster

An example of a Lobster workflow file defining steps for inbox triage.

```APIDOC
## Workflow files (.lobster)

Lobster can run YAML/JSON workflow files with `name`, `args`, `steps`, `env`, `condition`, and `approval` fields. In OpenClaw tool calls, set `pipeline` to the file path.

```yaml
name: inbox-triage
args:
  tag:
    default: "family"
steps:
  - id: collect
    command: inbox list --json
  - id: categorize
    command: inbox categorize --json
    stdin: $collect.stdout
  - id: approve
    command: inbox apply --approve
    stdin: $categorize.stdout
    approval: required
  - id: execute
    command: inbox apply --execute
    stdin: $categorize.stdout
    condition: $approve.approved
```

Notes:

* `stdin: $step.stdout` and `stdin: $step.json` pass a prior step’s output.
* `condition` (or `when`) can gate steps on `$step.approved`.
```

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

### Verify OpenClaw Version and Gateway Status

Source: https://docs.openclaw.ai/gateway/troubleshooting

Use these commands to perform a diagnostic check on the OpenClaw installation and verify the current status of the gateway service during migration or setup.

```bash
openclaw --version
openclaw doctor
openclaw gateway status
```

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

### Channel-Specific Configuration Example (JSON5)

Source: https://docs.openclaw.ai/plugins/sdk-setup

Shows how to define configuration for specific channels, including sensitive information like bot tokens and access control lists. This is separate from general plugin configuration.

```json5
{
  channels: {
    "my-channel": {
      token: "bot-token",
      allowFrom: ["user1", "user2"],
    },
  },
}
```

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

### Install signal-cli on Linux

Source: https://docs.openclaw.ai/channels/signal

Downloads and installs the latest native Linux version of signal-cli to /opt and creates a symbolic link in /usr/local/bin.

```bash
VERSION=$(curl -Ls -o /dev/null -w %{url_effective} https://github.com/AsamK/signal-cli/releases/latest | sed -e 's/^.*\/v//')
curl -L -O "https://github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}-Linux-native.tar.gz"
sudo tar xf "signal-cli-${VERSION}-Linux-native.tar.gz" -C /opt
sudo ln -sf /opt/signal-cli /usr/local/bin/
signal-cli --version
```

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

### Diffs Plugin Usage Examples

Source: https://docs.openclaw.ai/tools/diffs

Examples demonstrating how to call the diffs plugin with different input types and modes.

```APIDOC
## Input Examples

### Using `before` and `after` text

This example shows how to generate a diff using the `before` and `after` text fields, with the mode set to `"view"`.

```json
{
  "before": "# Hello\n\nOne",
  "after": "# Hello\n\nTwo",
  "path": "docs/example.md",
  "mode": "view"
}
```

### Using `patch` text

This example demonstrates generating a diff using a unified `patch` string, with the mode set to `"both"`.

```json
{
  "patch": "diff --git a/src/example.ts b/src/example.ts\n--- a/src/example.ts\n+++ b/src/example.ts\n@@ -1 +1 @@\n-const x = 1;\n+const x = 2;\n",
  "mode": "both"
}
```
```

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

### Configure Exec Tool via JSON

Source: https://docs.openclaw.ai/tools/exec

Example configuration for the Exec tool, demonstrating how to prepend custom directories to the system PATH for command execution.

```json5
{
  tools: {
    exec: {
      pathPrepend: ["~/bin", "/opt/oss/bin"],
    },
  },
}
```