OpenClaw Master Operations#

The comprehensive OpenClaw operations skill — combining CLI mastery, gateway administration, security hardening, troubleshooting workflows, and production best practices.

When to Use This Skill#

Use this skill whenever the user needs to:

• Set up OpenClaw — Installation, initial config, onboarding, multi-node deployments
• Operate the Gateway — Start/stop/restart, bind modes, auth, discovery, Tailscale exposure
• Debug issues — Connection failures, auth errors, channel problems, agent crashes, exec failures
• Harden security — Audit config, fix permissions, tighten group policies, SecretRef management
• Manage channels — Telegram, WhatsApp, Discord, Slack, Signal setup and troubleshooting
• Configure agents/models — Model routing, sandbox settings, tool profiles, ACP harness setup
• Automate operations — Cron jobs, scheduled tasks, watchdogs, health monitoring
• Manage plugins/skills — Install, update, publish to ClawHub, troubleshoot plugin conflicts
• Respond to incidents — Gateway crashes, session corruption, credential expiry, approval failures

Core Principles#

1. Safety First#

• Back up before destructive actions — Always backup openclaw.json, credentials/, sessions/ before --fix operations
• Prefer trash over rm — Use recoverable deletion when cleaning up state
• Verify before applying — Show users what will change before running --fix or --repair commands
• SecretRef awareness — Know when config values are secret-managed vs plaintext

2. Diagnostic Discipline#

Follow this triage sequence for any OpenClaw issue:

text

1. Check gateway status → openclaw gateway status
2. Run health check → openclaw doctor
3. Inspect logs → openclaw logs --recent 50
4. Verify auth → openclaw gateway query whoami
5. Check channels → openclaw channels list
6. Test exec → openclaw exec "echo test"
7. Security audit → openclaw security audit

3. Output Hygiene#

• Prefer --json for automation — Machine-readable output for scripts/CI
• Use --no-color in logs — Clean output for cron/webhook contexts
• Redact sensitive data — Never log tokens, passwords, or credential paths

Command Reference#

Gateway Operations#

bash

# Start/Stop/Restart
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway status

# Run in foreground (dev)
openclaw gateway run --bind loopback --auth token

# Query running gateway
openclaw gateway query whoami
openclaw gateway query sessions
openclaw gateway query channels
openclaw gateway query nodes

# Discovery (find gateways on network)
openclaw gateway discover
openclaw gateway discover --wide  # DNS-SD beyond local network

Health & Diagnostics#

bash

# Quick health check
openclaw doctor

# Auto-repair common issues
openclaw doctor --repair
openclaw doctor --repair --non-interactive

# Deep scan (includes system services)
openclaw doctor --deep

# Generate gateway token
openclaw doctor --generate-gateway-token

Security Operations#

bash

# Security audit
openclaw security audit
openclaw security audit --deep
openclaw security audit --json | jq '.summary'

# Apply safe fixes
openclaw security audit --fix
openclaw security audit --fix --json

# Manage secrets
openclaw secrets list
openclaw secrets get <name>
openclaw secrets set <name> <value>
openclaw secrets delete <name>

Channel Management#

bash

# List channels
openclaw channels list
openclaw channels list --json

# Channel status
openclaw channels status telegram
openclaw channels status whatsapp

# QR codes (for WhatsApp/Telegram bot setup)
openclaw qr show telegram
openclaw qr show whatsapp

# Channel troubleshooting
openclaw channels repair telegram
openclaw channels repair whatsapp

Node & Agent Management#

bash

# List nodes
openclaw nodes list
openclaw nodes status

# Node pairing
openclaw node pair
openclaw node unpair <node-id>
openclaw pairing list

# Agent management
openclaw agents list
openclaw agent status <agent-id>
openclaw agent restart <agent-id>

# ACP harness (Claude Code, Cursor, etc.)
openclaw acp list
openclaw acp status

Session Management#

bash

# List sessions
openclaw sessions list
openclaw sessions list --active-minutes 30
openclaw sessions list --kinds subagent

# Session history
openclaw sessions history <session-key>
openclaw sessions history <session-key> --limit 50 --include-tools

# Send to session
openclaw sessions send <session-key> "message here"

# Kill session
openclaw sessions kill <session-key>

Cron & Automation#

bash

# List cron jobs
openclaw cron list
openclaw cron list --json

# Manage jobs
openclaw cron add "0 6 * * *" "openclaw doctor --repair"
openclaw cron remove <job-id>
openclaw cron run <job-id>

# Heartbeat management
openclaw heartbeat status
openclaw heartbeat run

Plugin & Skill Management#

bash

# Skills (ClawHub)
clawhub install <skill-slug>
clawhub update <skill-slug>
clawhub update --all
clawhub list
clawhub search "<query>"

# Plugins
openclaw plugins list
openclaw plugins install <plugin-name>
openclaw plugins update <plugin-name>
openclaw plugins remove <plugin-name>

Logs & Debugging#

bash

# Recent logs
openclaw logs --recent 100
openclaw logs --follow
openclaw logs --level debug

# Gateway logs
openclaw logs gateway --recent 50

# Agent logs
openclaw logs agent <agent-id> --recent 50

# Export logs
openclaw logs export ./logs-backup.tar.gz

Config Management#

bash

# View config
openclaw config list
openclaw config get <key>
openclaw config get gateway.auth.token

# Set config
openclaw config set <key> <value>
openclaw config set gateway.mode local

# Delete config
openclaw config delete <key>

# Backup/Restore
openclaw backup create
openclaw backup list
openclaw backup restore <backup-id>

System Operations#

bash

# System status
openclaw system info
openclaw system status
openclaw system resources

# Update OpenClaw
openclaw update
openclaw update --preview

# Reset (careful!)
openclaw reset --keep-channels
openclaw reset --all  # Full reset

Troubleshooting Playbooks#

Gateway Won't Start#

bash

# 1. Check if something's using the port
lsof -i :18789
netstat -tlnp | grep 18789

# 2. Kill existing process
openclaw gateway stop --force

# 3. Check config
openclaw config get gateway.mode
openclaw config get gateway.bind

# 4. Run doctor
openclaw doctor --repair

# 5. Check logs
openclaw logs gateway --recent 100

"Pairing Required" Errors#

bash

# 1. Check pairing status
openclaw pairing list

# 2. Re-pair node
openclaw node pair

# 3. If still failing, reset pairing
openclaw config delete nodes.paired
openclaw node pair

# 4. For mobile apps, show QR
openclaw qr show

Channel Auth Failures#

bash

# 1. Check channel status
openclaw channels status <channel>

# 2. Verify credentials exist
ls -la ~/.openclaw/credentials/

# 3. Re-authenticate
openclaw channels auth <channel>

# 4. For Telegram/WhatsApp, regenerate QR
openclaw qr show <channel>

Exec Approval Timeouts#

bash

# 1. Check approval config
openclaw config get gateway.nodes.allowCommands
openclaw config get gateway.nodes.denyCommands

# 2. Check pending approvals
openclaw approvals list

# 3. For known-safe commands, add to allowlist
openclaw config set gateway.nodes.allowCommands '["ls", "cat", "grep"]'

# 4. Restart gateway
openclaw gateway restart

Session Corruption#

bash

# 1. List sessions
openclaw sessions list

# 2. Kill problematic session
openclaw sessions kill <session-key>

# 3. Clean up orphaned transcripts
openclaw doctor --repair

# 4. If severe, reset sessions
openclaw reset --sessions-only

Model/API Errors#

bash

# 1. Check model config
openclaw config get agents.defaults.model

# 2. Test inference
openclaw infer --model qwen/qwen3.5-plus "Hello"

# 3. Check provider status
openclaw models list

# 4. Rotate API keys if needed
openclaw secrets set OPENAI_API_KEY <new-key>

Security Hardening Checklist#

Run these periodically (weekly for production):

bash

# 1. Security audit
openclaw security audit --deep

# 2. Apply safe fixes
openclaw security audit --fix

# 3. Check for exposed secrets
openclaw secrets list --show-metadata

# 4. Verify channel allowlists
openclaw config get channels.telegram.allowFrom
openclaw config get channels.whatsapp.allowFrom

# 5. Check group policies
openclaw config get channels.telegram.groupPolicy
openclaw config get channels.whatsapp.groupPolicy

# 6. Audit installed plugins
openclaw plugins list
clawhub list

# 7. Review recent sessions
openclaw sessions list --active-minutes 1440

# 8. Check for updates
openclaw update --check

Production Best Practices#

1. Use SecretRef for Sensitive Values#

json

{
  "gateway.auth.token": {
    "$secretRef": "gateway-token"
  },
  "channels.telegram.token": {
    "$secretRef": "telegram-bot-token"
  }
}

2. Enable Sandbox Mode#

bash

openclaw config set agents.defaults.sandbox.mode on
openclaw config set agents.defaults.sandbox.docker true

3. Configure Session DM Scope#

For shared inboxes:

bash

openclaw config set session.dmScope per-channel-peer

4. Set Up Monitoring Cron#

bash

# Health check every 30 minutes
openclaw cron add "*/30 * * * *" "openclaw doctor --non-interactive"

# Security audit weekly
openclaw cron add "0 3 * * 0" "openclaw security audit --deep --json > ~/security-audit.json"

5. Enable Logging Redaction#

bash

openclaw config set logging.redactSensitive tools

6. Configure Model Routing#

bash

# Default model for agents
openclaw config set agents.defaults.model.primary qwen/qwen3.5-plus

# Fallback model
openclaw config set agents.defaults.model.fallback zai/glm-5

# Model for specific tasks
openclaw config set agents.defaults.model.reasoning qwen/qwen3.5-plus

Quick Reference: Command Families#

FamilyCommandsUse WhenGatewaygateway start/stop/status/queryManaging the WebSocket serverHealthdoctor, healthDiagnosing issuesSecuritysecurity audit, secretsHardening configChannelschannels list/status/repair, qrChannel setup/debugNodesnodes list, node pair, pairingMulti-node setupsAgentsagents list, agent status, acpAgent managementSessionssessions list/history/send/killSession orchestrationCroncron list/add/run/removeAutomationPluginsplugins list/install/updatePlugin managementSkillsclawhub install/update/searchSkill managementConfigconfig list/get/set/deleteConfig changesLogslogs --recent/--followDebuggingSystemsystem info/status/updateSystem ops

Escalation Paths#

When standard troubleshooting fails:

1. Check official docs — openclaw docs or https://docs.openclaw.ai
2. Search ClawHub — clawhub search "<topic>" for relevant skills
3. Check GitHub issues — https://github.com/openclaw/openclaw/issues
4. Discord community — https://discord.gg/clawd
5. Enable debug logging — openclaw config set logging.level debug

Notes#

• Profile isolation — Use --profile <name> to isolate state: openclaw --profile dev gateway
• Dev mode — Use --dev flag for isolated dev environment: openclaw --dev gateway
• Container targeting — Use --container <name> to target specific containers
• JSON output — Add --json for machine-readable output in all commands
• No color — Add --no-color or set NO_COLOR=1 for clean logs

Release Tracking#

This skill includes automated OpenClaw release tracking to stay current with frequent updates.

Database#

Location: skills/openclaw-master-ops/release-history.db

Tracks:

• Release versions and changelogs
• Breaking changes (auto-detected)
• Skill knowledge verification status

Commands#

bash

cd /home/marius/.openclaw/workspace/skills/openclaw-master-ops

# Sync latest releases from GitHub
python3 scripts/release-tracker.py sync

# View release history
python3 scripts/release-tracker.py history

# Check breaking changes
python3 scripts/release-tracker.py breaking

# Check if skill needs updates
python3 scripts/release-tracker.py skill-update

# Export for skill context
python3 scripts/release-tracker.py export

Automated Sync (Cron)#

bash

# Weekly sync (Sundays 3 AM)
openclaw cron add "0 3 * * 0" "cd ~/.openclaw/workspace/skills/openclaw-master-ops && python3 scripts/release-tracker.py sync"

# Daily check for updates
openclaw cron add "0 8 * * *" "cd ~/.openclaw/workspace/skills/openclaw-master-ops && python3 scripts/release-tracker.py skill-update"

When OpenClaw Updates#

After running openclaw update:

1. Run sync — python3 scripts/release-tracker.py sync
2. Check breaking — python3 scripts/release-tracker.py breaking
3. Review skill updates — python3 scripts/release-tracker.py skill-update
4. Update skill if needed — Edit SKILL.md based on breaking changes
5. Republish — clawhub publish ... --version 1.X.0 --changelog "Updated for OpenClaw <version>"

Breaking Change Detection#

Auto-detects these patterns in changelogs:

• removed → feature_removal
• deprecated → deprecation
• breaking → breaking_change
• migration → migration_required
• changed default → default_change
• config schema → config_change
• command removed → command_removal

See references/release-tracking.md for full workflow.

---

Related Skills#

• deep-research — For researching OpenClaw topics, comparing configurations
• plugin-publisher — For creating and publishing OpenClaw plugins
• npd-validator — For validating new OpenClaw feature ideas