claude-config/skills/openclaw/SKILL.md

name, description

name	description
openclaw	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

# 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

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

# 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

{
  // 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

# 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

{
  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

# 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

# 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

# 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/

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

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

SKILL.md Format

---
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

{
  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.

# 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:

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

Endpoints

POST /hooks/wake - Enqueue system event:

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:

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.

# 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:

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

# My Hook
Description here.

3. Create handler.ts:

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

# 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

# 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:

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.

# Discover models
openclaw models [list]

Common Workflows

Initial Setup

npm install -g openclaw@latest
openclaw onboard --install-daemon
openclaw channels login
openclaw gateway

Add New Channel

openclaw channels add --channel telegram --token BOT_TOKEN
openclaw agents bind --agent main --bind telegram
openclaw gateway restart

Multi-Agent Setup

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

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

openclaw config set skills.entries.web-search.enabled true --strict-json
openclaw gateway restart

Troubleshooting

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