npm package: @sacheeperera/cyclawps
Description: Your portable OpenClaw platform engineer — instance profiling, health checks, guided workflows, and a knowledge corpus. One command: /cyclawps.
Author: Sachee Perera
Latest version: 0.1.0

# cyCLAWps

**Your OpenClaw instance doesn't come with a platform engineer. Now it does.**

cyCLAWps gives every OpenClaw operator a platform engineer that knows their instance -- one command, zero config. It reads your setup, understands your agents, and walks you through everything from first install to production debugging.

Type `/cyclawps` in Claude Code. That's it.

---

## The Problem

OpenClaw is powerful. It is also unforgiving.

A single misplaced comma in `openclaw.json` takes down every agent on your instance simultaneously. Not the one you were editing -- all of them. There is no warning, no graceful degradation, no "hey, your config has a typo." Just silence.

Cron jobs fail silently when you forget a delivery field. You set up a weekly report, the skill runs perfectly, the output is great -- and it never arrives. The job executed. The report was generated. But you left out `accountId`, so the message had nowhere to go. You find out a week later when you wonder why Monday's report never showed up.

Channel setup is full of hidden gotchas. Slack needs a triple of config flags set together -- miss one and streaming breaks. Discord uses `"disabled"` not `"off"` -- use the wrong string and the gateway ignores it silently. Telegram needs you to message the bot first before you can find the chat ID. None of this is obvious from the docs.

The learning curve wastes days. Conventions are tribal knowledge. Identity files must be real files (not symlinks) or the agent starts with no personality -- no error, no log, just a blank assistant. Area context files should be symlinks. Bootstrap files have a size limit. The docs exist, but they are scattered across the official site, Deep Wiki, GitHub Issues, subreddit threads, and Discord channels. Getting an agent from zero to production means stitching together a dozen sources.

## The Solution

```
> /cyclawps
```

Cyclawps detects your instance, reads your config, and meets you where you are.

**New operator, no instance yet:**

```
Cyclawps: I don't see an OpenClaw instance on this machine yet. Want me to help
you set one up? I'll walk you through install, your first agent, your first
channel, and verify everything works. Takes about 10 minutes.
```

**Adding an agent to an existing instance:**

```
You: I want to add an agent that writes marketing content

Cyclawps: Got it. I can see your instance — you have 2 agents running (Ruka and
Cyclawps), Telegram connected, and 6 cron jobs. Let me set up a content agent
for you.

I need three things:
1. What exactly should this agent do?
2. What should we call it?
3. Does this belong to a business unit?
```

**Something is broken:**

```
You: My cron jobs are running but I'm not getting messages

Cyclawps: Let me check. Reading your cron/jobs.json...

Found it. 3 of your 12 jobs are missing the accountId field. The skill runs,
the report generates, but the message has no sending account — so it goes
nowhere. This is the most common cron mistake.

Let me fix all three. Backing up jobs.json first...
```

Cyclawps follows every change with a recap, a concept explanation, and next steps. You learn OpenClaw by using it.

## Install

```bash
git clone --depth 1 https://github.com/comicsansbestfont/cyclawps.git ~/cyclawps
cd ~/cyclawps && ./setup
```

The setup script detects your environment and installs what makes sense:

```
cyCLAWps — Your OpenClaw platform engineer
v0.1.0

Detecting environment...
  Platform:    macOS (Darwin)
  Node.js:     v22.14.0 ✓
  Claude Code: found ✓
  OpenClaw:    found (4 agents) ✓

✓ Claude Code skill installed → ~/.claude/skills/cyclawps
  Type /cyclawps in Claude Code to get started

OpenClaw instance detected at ~/.openclaw/
  4 agents configured

  Install Cyclawps as an agent? (health checks + monitoring) [Y/n]
```

No Claude Code? No OpenClaw? The setup script tells you exactly what is missing and how to get it. Already have everything? It skips what is already installed.

## Three Modes

### Interactive -- `/cyclawps` in Claude Code

This is the primary interface. You talk to your platform engineer in natural language. It reads your instance, follows battle-tested workflows, and makes changes using a safe config protocol (backup, edit copy, validate JSON, deploy).

Best for: setup, debugging, learning, anything that needs back-and-forth.

### Plugin -- `openclaw plugins install @sacheeperera/cyclawps`

Registers tools and CLI commands directly inside OpenClaw. Any agent on your instance can call Cyclawps capabilities programmatically -- health checks, config validation, instance profiling.

Best for: automation, integrating Cyclawps into your agents' workflows.

### Agent -- optional, autonomous

Install the agent workspace during setup and register it in your config. It runs health checks on a schedule, alerts you when something is wrong, and keeps an instance profile up to date.

Best for: production instances that need continuous monitoring.

## What Cyclawps Knows How to Do

- **Set up a fresh OpenClaw instance from scratch** -- install, first agent, first channel, verify everything works
- **Create agents** -- workspace, identity files, model selection, config registration, channel connection
- **Write skills** -- markdown playbooks that give agents specific capabilities
- **Wire up cron jobs** -- scheduling, delivery fields, timeout tuning, concurrency checks
- **Connect channels** -- Telegram bots, Slack workspaces (with the streaming triple), Discord servers
- **Safely edit config** -- backup, edit copy in /tmp, validate JSON, deploy with hot-reload
- **Upgrade OpenClaw** -- version checks, changelog review, safe upgrade with rollback plan
- **Debug systematically** -- read logs, check config, consult the gotchas corpus, trace the issue
- **Audit instance health** -- agents, cron, channels, symlinks, gateway, bootstrap sizes, concurrency pressure
- **Organize into business units** -- area creation, governance files, artifact patterns, agent migration
- **Generate documentation** -- workspace maps, architecture docs, team rosters

## The Knowledge Base

Cyclawps ships with a curated reference corpus -- not scraped docs, but battle-tested operational knowledge from running a 10-agent production instance.

**43 operational gotchas.** Every one documents a real failure: the symptom you see, the root cause, how to prevent it, and how to recover. Config errors that nuke all agents. Cron delivery fields that fail silently. The Slack streaming triple. Discord policy strings. Model provider cooldowns. Bootstrap file symlink traps. Hook resolution quirks. Born from 30+ production incidents including a 2-hour gateway outage, a 46-job cron cascade, and an identity crisis that affected all agents for 2 days.

**6 troubleshooting catalogues.** Organized by topic -- config errors, cron failures, channel issues, gateway problems, model provider issues, plugin problems. Each follows a symptom-to-diagnosis-to-fix pattern.

**Community source index.** Subreddits, Discord servers, GitHub Issues, Discussions, official docs, Deep Wiki, npm -- every place where OpenClaw operators share solutions, indexed and annotated.

**Deep Wiki and release notes directories.** Starter directories where you can cache Deep Wiki architecture docs and release notes for offline reference. Populate them from [Deep Wiki](https://deepwiki.com/openclaw/openclaw) and [GitHub Releases](https://github.com/openclaw/openclaw/releases) so Cyclawps can reference them without fetching each session.

## See It in Action

These are full conversation transcripts showing Cyclawps working through real scenarios:

- **[Creating your first agent](examples/first-agent.md)** -- from "I want a content writer" to a fully configured agent with Telegram, including identity files, BU placement, model selection, and the safe config protocol

- **[Writing your first skill](examples/first-skill.md)** -- building a competitor analysis skill, explaining the resolution chain, wiring it to a weekly cron job with proper delivery fields and concurrency checks

- **[Setting up business units](examples/multi-bu-setup.md)** -- organizing loose agents into areas with governance files, shared artifacts, symlink patterns, and the config migration

- **[What a production instance looks like](examples/production-instance.md)** -- a full health audit of a 10-agent, 5-BU instance: agent census, cron pressure analysis, channel validation, version check, and three prioritized recommendations

## Built By

Built by [Sachee Perera](https://github.com/comicsansbestfont) -- battle-tested on a 10-agent, 5-BU OpenClaw instance running GTM advisory, e-commerce, content, and platform engineering workloads.

## License

MIT