---
name: openclaw
description: Operate OpenClaw - self-hosted AI gateway connecting chat apps to AI agents. Manage gateway, agents, channels, skills, plugins, sessions, hooks, webhooks, cron jobs, and configuration.
---

# OpenClaw Operations

## Overview

OpenClaw is a self-hosted gateway connecting messaging platforms (WhatsApp, Telegram, Discord, Slack, Signal, iMessage, MS Teams, etc.) to AI coding agents. It runs on Node.js 22+ and uses a WebSocket-based control plane.

- Config: `~/.openclaw/openclaw.json` (JSON5 format, hot-reloads)
- Default port: `18789`
- Local repo: `C:\Users\yaoji\git\OpenSource\openclaw`
- Docs: https://docs.openclaw.ai/

## Gateway Management

### Start / Stop / Status

```bash
# Run gateway foreground
openclaw gateway
openclaw gateway run

# With options
openclaw gateway --port 18789 --bind loopback --verbose
openclaw gateway --dev                    # dev mode, creates config if missing
openclaw gateway --allow-unconfigured     # skip gateway.mode check
openclaw gateway --force                  # kill existing listener on port

# Service lifecycle
openclaw gateway install [--port 18789] [--token TOKEN] [--force]
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall

# Status and diagnostics
openclaw gateway status [--json] [--deep] [--no-probe]
openclaw gateway health --url ws://127.0.0.1:18789
openclaw gateway probe [--json]

# Discovery (Bonjour/mDNS)
openclaw gateway discover [--timeout 4000] [--json]

# Low-level RPC
openclaw gateway call <method> [--params '{"key":"value"}']
openclaw gateway call status
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
```

### Gateway Config Keys

```bash
openclaw config set gateway.port 19001 --strict-json
openclaw config set gateway.bind "loopback"
openclaw config set gateway.auth.mode "token"
openclaw config set gateway.auth.token "my-secret"
openclaw config set gateway.http.endpoints.chatCompletions.enabled true --strict-json
```

## Configuration

Config file: `~/.openclaw/openclaw.json`

```bash
# Print config file path
openclaw config file

# Read values (dot/bracket notation)
openclaw config get agents.defaults.workspace
openclaw config get agents.list[0].id
openclaw config get channels.whatsapp.enabled

# Write values (JSON5 auto-parsed, use --strict-json for explicit)
openclaw config set agents.defaults.workspace "/path/to/workspace"
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config set channels.whatsapp.groups '["*"]' --strict-json
openclaw config set agents.list[0].tools.exec.node "node-id"

# Remove values
openclaw config unset tools.web.search.apiKey

# Validate
openclaw config validate [--json]

# Interactive wizard
openclaw configure
```

### Config Structure Reference

```json5
{
  // Identity
  identity: { name: "Pi", theme: "space lobster", emoji: "" },

  // Agents
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: { primary: "anthropic/claude-sonnet-4-20250514", fallbacks: [] },
      skills: [],                    // skill allowlist
      sandbox: { mode: "off" },      // "off" | "non-main" | "all"
      heartbeat: { every: "1h" },
    },
    list: [
      {
        id: "main",
        default: true,
        workspace: "~/.openclaw/workspace",
        model: { primary: "anthropic/claude-sonnet-4-20250514" },
        skills: [],
        identity: { name: "Pi", emoji: "" },
        runtime: { type: "embedded" },  // "embedded" | "acp"
        subagents: { allowAgents: [], model: "..." },
      }
    ]
  },

  // Channels
  channels: {
    whatsapp: { enabled: true, dmPolicy: "pairing", allowFrom: ["+15555550123"], groups: { "*": { requireMention: true } } },
    telegram: { enabled: true, botToken: "...", dmPolicy: "open" },
    discord: { enabled: true, token: "..." },
    slack: { enabled: true, botToken: "...", signingSecret: "..." },
    signal: { enabled: true, phoneNumber: "+1..." },
    // imessage, googlechat, msteams, matrix, irc, line, feishu, mattermost, etc.
  },

  // Session
  session: {
    scope: "per-peer",   // "main" | "per-peer" | "per-channel-peer" | "per-account-channel-peer"
    reset: { mode: "idle", idleMinutes: 120 },
    maintenance: { mode: "warn", pruneAfter: "30d", maxEntries: 500 },
  },

  // Skills
  skills: {
    allowBundled: [],
    load: { extraDirs: [], watch: true },
    install: { preferBrew: true, nodeManager: "npm" },
    entries: {
      "web-search": { enabled: true },
      "image-gen": { enabled: true, apiKey: "..." },
    }
  },

  // Plugins
  plugins: {
    enabled: true,
    allow: [],
    deny: [],
    load: { paths: [] },
    entries: {
      "my-plugin": { enabled: true, config: {} }
    }
  },

  // Tools
  tools: {
    web: { search: { enabled: true }, fetch: { enabled: true } },
    browser: { enabled: true },
    canvas: { enabled: true },
    media: { audio: { enabled: true } },
  },

  // Gateway
  gateway: {
    mode: "local",
    bind: "loopback",     // "loopback" | "lan" | "tailnet" | "auto"
    port: 18789,
    auth: { mode: "token", token: "..." },
    controlUi: { enabled: true },
    http: {
      endpoints: {
        chatCompletions: { enabled: false },
        responses: { enabled: false },
      }
    },
  },

  // Hooks (webhooks)
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedAgentIds: ["main"],
    // Internal hooks (event-driven)
    internal: {
      enabled: true,
      entries: {
        "session-memory": { enabled: true },
        "command-logger": { enabled: false },
      }
    },
    // Webhook mappings
    mappings: [
      { match: { path: "gmail" }, action: "agent", agentId: "main", deliver: true }
    ],
  },

  // Cron
  cron: { enabled: true, maxConcurrentRuns: 2 },

  // ACP (Agent Control Protocol)
  acp: { enabled: false, backend: "acpx", maxConcurrentSessions: 5 },

  // Logging
  logging: { level: "info", redactSensitive: "tools" },

  // Environment
  env: { vars: { MY_KEY: "value" } },
}
```

## Agent Management

```bash
# List agents
openclaw agents list

# Add agent with workspace
openclaw agents add work --workspace ~/.openclaw/workspace-work

# Delete agent
openclaw agents delete work

# Routing bindings
openclaw agents bindings [--agent work] [--json]
openclaw agents bind --agent work --bind telegram:ops --bind discord:guild-a
openclaw agents unbind --agent work --bind telegram:ops
openclaw agents unbind --agent work --all

# Set agent identity
openclaw agents set-identity --agent main --name "Pi" --emoji ""
openclaw agents set-identity --workspace ~/.openclaw/workspace --from-identity
openclaw agents set-identity --agent main --avatar avatars/openclaw.png
```

### Agent Config Example

```json5
{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        workspace: "~/.openclaw/workspace",
        identity: { name: "Pi", theme: "space lobster", emoji: "" },
      },
      {
        id: "work",
        workspace: "~/.openclaw/workspace-work",
        model: { primary: "openai/gpt-5" },
        skills: ["web-search", "code-runner"],
      }
    ]
  }
}
```

### Bootstrap Files

Place in agent workspace root:
- `AGENTS.md` - Operating instructions + memory
- `SOUL.md` - Persona, boundaries, tone
- `TOOLS.md` - User tool notes
- `BOOTSTRAP.md` - One-time ritual (deleted after first run)
- `IDENTITY.md` - Agent name/vibe
- `USER.md` - User profile

## Channel Management

```bash
# List and status
openclaw channels list
openclaw channels status [--probe]
openclaw channels capabilities [--channel discord --target channel:123]

# Add / remove accounts
openclaw channels add --channel telegram --token <bot-token>
openclaw channels remove --channel telegram [--delete]

# Login/logout (interactive)
openclaw channels login --channel whatsapp
openclaw channels logout --channel whatsapp

# Resolve names to IDs
openclaw channels resolve --channel slack "#general" "@jane"
openclaw channels resolve --channel discord "My Server/#support"

# Tail channel logs
openclaw channels logs --channel all
```

### DM Policies

- `pairing` (default) - Require pairing code approval
- `allowlist` - Only allow specific senders
- `open` - Allow all DMs
- `disabled` - Block all DMs

## Sending Messages

```bash
# Send text
openclaw message send --channel telegram --target @mychat --message "Hello"

# Send with media
openclaw message send --channel discord --target channel:123 --message "See this" --media ./image.png

# Reply to message
openclaw message send --channel discord --target channel:123 --message "Reply" --reply-to 456

# Create poll
openclaw message poll --channel discord --target channel:123 \
  --poll-question "Lunch?" --poll-option Pizza --poll-option Sushi --poll-multi

# React
openclaw message react --channel slack --target C123 --message-id 456 --emoji "check"

# Read messages
openclaw message read --channel discord --target channel:123 --limit 20

# Edit / delete
openclaw message edit --channel discord --target channel:123 --message-id 789 --message "Updated"
openclaw message delete --channel discord --target channel:123 --message-id 789

# Broadcast to multiple targets
openclaw message broadcast --channel all --targets user1 --targets user2 --message "Announcement"

# Thread operations (Discord)
openclaw message thread create --channel discord --target channel:123 --thread-name "Discussion"
openclaw message thread list --channel discord --guild-id 456
openclaw message thread reply --channel discord --target thread:789 --message "Reply"
```

### Target Formats

| Channel | Format |
|---------|--------|
| WhatsApp | E.164 (`+15551234567`) or group JID |
| Telegram | chat id or `@username` |
| Discord | `channel:<id>` or `user:<id>` |
| Slack | `channel:<id>` or `user:<id>` |
| Signal | `+E.164`, `group:<id>`, `username:<name>` |
| iMessage | handle, `chat_id:<id>`, `chat_guid:<guid>` |
| MS Teams | `conversation:<id>` or `user:<aad-object-id>` |

## Session Management

```bash
# List sessions
openclaw sessions [--agent work] [--all-agents] [--json]
openclaw sessions --active 120     # active in last 120 minutes

# Cleanup
openclaw sessions cleanup --dry-run [--agent work] [--all-agents]
openclaw sessions cleanup --enforce
```

Session storage: `~/.openclaw/agents/<agentId>/sessions/`

### Session Scopes

- `main` - Single session per agent
- `per-peer` - One session per sender
- `per-channel-peer` - One session per sender per channel
- `per-account-channel-peer` - Full isolation

## Skills Management

Skills extend agent capabilities. Three sources (precedence: workspace > managed > bundled):
- **Bundled**: shipped with OpenClaw (web-search, browser, canvas, cron, etc.)
- **Managed**: `~/.openclaw/skills/`
- **Workspace**: `<workspace>/skills/`

```bash
# List skills
openclaw skills list [--eligible] [--verbose] [--json]

# Info and check
openclaw skills info <name> [--json]
openclaw skills check
```

### SKILL.md Format

```markdown
---
name: my-skill
description: What this skill does
requires:
  bins: [node, git]
  env: [MY_API_KEY]
  config: [tools.web.search.apiKey]
install:
  - kind: node
    package: my-skill-package
always: false
skillKey: MY_SKILL
emoji: ""
homepage: https://example.com
---

# My Skill

Instructions and tool definitions for the LLM agent...
```

### Skills Config

```json5
{
  skills: {
    entries: {
      "web-search": { enabled: true },
      "browser": { enabled: true },
      "image-gen": { enabled: true, apiKey: "sk-..." },
    }
  }
}
```

## Plugins Management

Plugins are in-process gateway extensions with full API access.

```bash
# List, info
openclaw plugins list
openclaw plugins info <id>

# Install
openclaw plugins install <path-or-npm-spec> [--pin] [--link]
openclaw plugins install -l ./my-plugin    # link local plugin

# Enable / disable
openclaw plugins enable <id>
openclaw plugins disable <id>

# Update
openclaw plugins update <id>
openclaw plugins update --all [--dry-run]

# Uninstall
openclaw plugins uninstall <id> [--keep-files] [--dry-run]

# Diagnostics
openclaw plugins doctor
```

### Plugin Manifest

Every plugin needs `openclaw.plugin.json` with:
- Plugin metadata
- `configSchema` (JSON Schema, even if empty)

## Webhooks (External Triggers)

Enable in config:

```json5
{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
  }
}
```

### Endpoints

**POST /hooks/wake** - Enqueue system event:
```bash
curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"New email received","mode":"now"}'
```

**POST /hooks/agent** - Run isolated agent turn:
```bash
curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Summarize inbox",
    "name": "Email",
    "agentId": "main",
    "deliver": true,
    "channel": "telegram",
    "to": "123456789",
    "model": "anthropic/claude-sonnet-4-20250514",
    "timeoutSeconds": 120
  }'
```

**POST /hooks/\<name\>** - Custom mapped hooks (via `hooks.mappings`).

### Auth

- Header: `Authorization: Bearer <token>` (recommended)
- Header: `x-openclaw-token: <token>`
- Query string tokens are rejected

## Internal Hooks (Event-Driven)

Hooks run inside the gateway on agent events.

```bash
# List / info / check
openclaw hooks list [--eligible] [--verbose] [--json]
openclaw hooks info <name> [--json]
openclaw hooks check [--json]

# Enable / disable
openclaw hooks enable <name>
openclaw hooks disable <name>

# Install hook packs
openclaw hooks install <path-or-npm-spec>
```

### Bundled Hooks

| Hook | Event | Purpose |
|------|-------|---------|
| session-memory | command:new | Save session context to memory files |
| bootstrap-extra-files | agent:bootstrap | Inject extra workspace bootstrap files |
| command-logger | command | Audit log all commands to JSONL |
| boot-md | gateway:startup | Run BOOT.md on gateway start |

### Creating Custom Hooks

1. Create directory: `~/.openclaw/hooks/my-hook/`
2. Create `HOOK.md`:

```markdown
---
name: my-hook
description: "Does something useful"
metadata: { "openclaw": { "emoji": "", "events": ["command:new"] } }
---

# My Hook
Description here.
```

3. Create `handler.ts`:

```typescript
const handler = async (event) => {
  if (event.type !== "command" || event.action !== "new") return;
  console.log("[my-hook] Triggered!");
  event.messages.push("Hook executed!");
};
export default handler;
```

4. Enable: `openclaw hooks enable my-hook`

### Event Types

- `command:new`, `command:reset`, `command:stop`
- `session:compact:before`, `session:compact:after`
- `agent:bootstrap`
- `gateway:startup`
- `message:received`, `message:sent`, `message:transcribed`, `message:preprocessed`

## Cron Jobs

```bash
# Add recurring job
openclaw cron add \
  --name "Morning brief" \
  --cron "0 7 * * *" \
  --session isolated \
  --message "Summarize overnight updates." \
  --announce --channel telegram --to "123456789"

# Add one-shot job
openclaw cron add --name "Reminder" --at "2026-03-15T10:00:00" --message "Check report"

# Edit job
openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
openclaw cron edit <job-id> --no-deliver
openclaw cron edit <job-id> --light-context

# Full help
openclaw cron --help
```

## Onboarding & Setup

```bash
# Interactive onboarding wizard
openclaw onboard [--install-daemon]

# Setup workspace
openclaw setup

# System diagnostics
openclaw doctor [--fix]
openclaw status [--deep]
openclaw health

# Logs
openclaw logs [--follow]

# Update OpenClaw
openclaw update
```

## OpenAI-Compatible API

When enabled, the gateway exposes:
- `POST /v1/chat/completions` - OpenAI Chat Completions format
- `POST /v1/responses` - Open response format

Enable:
```bash
openclaw config set gateway.http.endpoints.chatCompletions.enabled true --strict-json
openclaw config set gateway.http.endpoints.responses.enabled true --strict-json
```

## Model Providers

25+ supported providers including:
- Anthropic (Claude)
- OpenAI (GPT)
- Ollama (local)
- OpenRouter
- AWS Bedrock
- Mistral, Qwen, vLLM, Deepgram, etc.

```bash
# Discover models
openclaw models [list]
```

## Common Workflows

### Initial Setup
```bash
npm install -g openclaw@latest
openclaw onboard --install-daemon
openclaw channels login
openclaw gateway
```

### Add New Channel
```bash
openclaw channels add --channel telegram --token BOT_TOKEN
openclaw agents bind --agent main --bind telegram
openclaw gateway restart
```

### Multi-Agent Setup
```bash
openclaw agents add work --workspace ~/.openclaw/workspace-work
openclaw agents bind --agent work --bind telegram:ops
openclaw agents bind --agent main --bind whatsapp
```

### Trigger Agent via API
```bash
curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Analyze this data","deliver":false}'
```

### Enable Skill
```bash
openclaw config set skills.entries.web-search.enabled true --strict-json
openclaw gateway restart
```

## Troubleshooting

```bash
openclaw doctor [--fix]          # Guided diagnostics and repairs
openclaw status --deep           # Full system status audit
openclaw channels status --probe # Channel connectivity check
openclaw config validate         # Config schema validation
openclaw gateway probe           # Debug gateway connectivity
openclaw logs --follow           # Tail gateway logs
```