Ops

README

# openclaw-ops

Claude Code plugin for managing OpenClaw instances via SSH.

## What It Does

Manage your remote OpenClaw deployment directly from Claude Code — check health, view logs, deploy skills, manage channels, troubleshoot issues, and update safely. All without leaving your editor.

## Installation

Copy or symlink this directory to your Claude Code plugins folder:

```bash
# Symlink (recommended for development)
ln -s /path/to/openclaw-ops ~/.claude/plugins/openclaw-ops

# Or copy
cp -r /path/to/openclaw-ops ~/.claude/plugins/openclaw-ops
```

Then run `/oc-setup` to connect to your OpenClaw instance.

## Quick Start

```
/oc-setup myserver          # Connect to your instance via SSH
/oc-status                  # Quick health check
/oc-logs 5m                 # Last 5 minutes of logs
/oc-logs errors             # Recent errors only
/oc-deploy my-skill/        # Deploy a local skill
/oc-troubleshoot            # Full diagnostic sweep
```

## Commands

| Command | Description |
|---------|-------------|
| `/oc-setup <host>` | Configure connection to your OpenClaw instance |
| `/oc-status [verbose]` | Quick health check (container, gateway, channels) |
| `/oc-logs <filter>` | View logs with smart filtering (time, errors, module) |
| `/oc-deploy <path\|slug>` | Deploy a local skill or install from ClawHub |
| `/oc-troubleshoot [symptom]` | Diagnose issues using known-issues database |

## Skills

Skills activate automatically based on context. You can also reference them by name.

| Skill | When It Activates |
|-------|------------------|
| **container-ops** | Container status, restart, recreate, shell access |
| **diagnostics** | Health checks, doctor, security audit, diagnostic reports |
| **log-analysis** | Log parsing, error classification, module tracing |
| **config-management** | View/edit config, env vars, model settings |
| **channel-management** | Channel status, login, pairing, per-channel troubleshooting |
| **skill-deploy** | Skill installation, validation, transfer, lifecycle |
| **cron-management** | Scheduled job CRUD, execution history, debugging |
| **troubleshoot** | Symptom matching against 40+ known issues |
| **update** | Safe update workflow with backup and rollback |

## Agent

**incident-responder** — Autonomous agent that systematically diagnoses and fixes
OpenClaw incidents. Follows an assess-diagnose-match-propose-execute-verify flow.
Always asks for confirmation before applying fixes.

## Configuration

Instance-specific settings are stored in `.claude/openclaw-ops.local.md`. This file
is created by `/oc-setup` and contains:

- SSH connection details
- Container name and paths
- Hosting provider detection
- Instance-specific known issues
- Channel and API key status

This file should be gitignored — it contains instance-specific details.

## Requirements

- SSH access to your VPS (key-based auth recommended)
- Docker and Docker Compose on the remote host
- OpenClaw installed and running in a Docker container
- Claude Code with Bash tool access

## How It Works

All operations execute via SSH. The plugin sends commands like:

```bash
ssh <your-host> 'docker exec <container> openclaw <command>'
```

It prefers the OpenClaw CLI (`openclaw doctor`, `openclaw cron list`, etc.) over raw
file manipulation. Docker commands are used as fallback when the gateway is down.

## Known Issues Database

The plugin includes a comprehensive known-issues database covering:

- **Gateway & Startup**: crash loops, port conflicts, config errors, permission issues
- **Config & Persistence**: proxy injection model, hosting-provider quirks
- **Channels**: WhatsApp session expiry, Telegram privacy mode, Discord intents
- **Performance**: memory usage, skill bloat, ARM optimization
- **Skills & Plugins**: deployment issues, cron debugging, security concerns
- **Security**: unauthorized access, malicious skills

## Contributing

To add a new known issue, edit `skills/troubleshoot/references/known-issues.md`.

To add a new skill, create `skills/<name>/SKILL.md` with YAML frontmatter containing
`name` and `description`.