| name | openclawadmin |
| version | 1.2.0 |
| description | Operate, diagnose, configure, and fix OpenClaw installations — gateway not responding, channel silent, model failover issues, auth errors, agent routing problems, config validation failures, plugin drift after update, or any operational task involving openclaw.json, the gateway, agents, channels, or the openclaw CLI. |
| license | MIT |
| metadata | {"openclaw":{"emoji":"🛠️","always":false}} |
openclawadmin — OpenClaw admin skill pack
One pack for everything OpenClaw admin: diagnose, configure, fix, update, babysit, and keep the upstream source in sync.
This is the umbrella skill. It ships with sibling skills in the same repo so each common task has its own trigger:
| Sibling skill | Triggers on | Job |
|---|
openclaw-update | update openclaw, is there a new openclaw, time to upgrade | End-to-end version upgrade with preflight, backup, verify, highlights briefing |
openclaw-troubleshooting | openclaw isn't working, not replying, won't start, fix my openclaw | Evidence-based diagnosis; explicit approval before any repair |
openclaw-instance-discovery | find my openclaw, rescan | Builds the on-host instance registry (auto-triggered by troubleshooting) |
openclaw-troubleshooting-compound | after an incident resolves | Drafts incident-log entry + signatures, writes to per-host memory |
openclaw-babysit | babysit my openclaw, keep openclaw running | Recurring channel-health monitor; supports --auto-fix in authorized mode |
What lives in this umbrella (openclawadmin/)
config-map.md — config keys with hot-reload vs restart behavior. The most-asked reference.update-failure-patterns.md — generic install/update regression patterns (plugin drift, config drift, service-manager disagreement, channel auth failures, etc.).local-install.md — per-install profile template; built on first use. Keep your host-specific facts (failover chain, auth ordering, dual-allowlist, ACP allowlist) here.scripts/refresh-openclaw-docs.sh — optional: pulls the live https://docs.openclaw.ai/llms.txt into a local cache so this pack has current published docs indexed.
Agent Context (Read First)
The right path depends on where you are running.
External agent (Claude Code, Codex CLI, shell user):
- Use the
openclaw CLI directly. You survive gateway restart / stop / service reinstall — the gateway dying does not kill you.
- Use the diagnostic ladder + sibling skills below as written.
OpenClaw agent running inside the gateway (dispatched via ACP, a channel, or cron):
- Prefer native gateway tools when available:
gateway config.get, gateway config.patch, gateway config.schema.lookup, cron, message. They do not leak secrets into context.
- You die with your gateway. Before triggering
gateway restart, gateway stop, or any service reinstall, schedule a cron wake event for after the restart so you can resume verification. Otherwise the conversation ends mid-repair.
- Treat shell-out paths as a fallback for things native tools cannot do.
- When in doubt, check whether
context.gateway / context.cron (or equivalent native APIs) are available before assuming external.
Local Install Profile
Before non-trivial OpenClaw work, read local-install.md in this directory. That file is the only intended local-customization point for host-specific install facts.
- If
local-install.md is missing or still says Status: uninitialized template, build it first from read-only discovery commands.
- If live discovery disagrees with
local-install.md, treat the file as stale, verify current state, and update it with non-secret facts before relying on it.
- Update
local-install.md whenever the user changes install type, host, profile, service manager, config path, gateway port, package source, plugin roots, rescue gateway, or secondary instance layout. Update it whenever the OpenClaw version changes.
- Keep
SKILL.md generic. Do not add hostnames, ports, profiles, service names, secrets, tokens, env-file contents, session bodies, agent workspace contents, or private conversation text anywhere in this skill.
Scope & Safety
This skill operates locally only on the user's OpenClaw installation. Keep these rails:
- Never open
~/.openclaw/secrets.json or ~/.openclaw/.env. Reference them by path when explaining config; do not read their contents into the conversation, tool output, logs, or any external destination. If a diagnostic genuinely requires a secret value, ask the user to paste the specific field.
- Never transmit config, env, secrets, session data, or agent workspace contents to any external service (web fetches, paste sites, third-party APIs, remote agents). Local commands and user-approved doc lookups only.
- Require explicit user confirmation before any of:
- writing to
~/.openclaw/openclaw.json beyond a single validated openclaw config set
openclaw gateway restart / stop / service reinstall- rotating, deleting, or overwriting tokens, OAuth profiles, or plugin credentials
- deleting agents, sessions, plugins, or cron jobs
- any
rm, mv, or destructive git/systemd action touching OpenClaw state
- Back up before editing. Use the safe-config workflow in
config-map.md for any openclaw.json change — never batch-write the whole file.
- Read-only investigation is fine without asking (status commands, log tailing, config validation, grepping docs).
- Agent sessions and workspaces may contain user conversations, prompts, and PII. Listing them (names, timestamps, sizes, file paths) is fine without asking. Before reading the contents of any file under
~/.openclaw/agents/<id>/sessions/ or an agent workspace, ask the user first — explain what you are looking for and why so they can approve, narrow the scope, or point you at the right session. Never quote or summarize session bodies in external fetches, cross-agent messages, or any destination outside this conversation.
Diagnostic Ladder (entry summary)
For the full ladder and decision tree, see the openclaw-troubleshooting/SKILL.md sibling. The condensed sequence:
openclaw status — is the gateway even running? What is the agent reachability summary?openclaw doctor — explicit health gates. Read every flagged item.- Last resort:
tail -n 200 ~/.openclaw/logs/openclaw.log
- Channel specific:
openclaw status channel <id-or-name> --deep. Discord / Telegram / Slack each have their own checklist in the troubleshooting playbooks/channels.md.
- Then run
openclaw-instance-discovery if multi-instance routing looks wrong.
If a fix is suggested, run openclaw-troubleshooting (the sibling) for the explicit-approval workflow. Do not patch openclaw.json without the safe-config workflow from config-map.md.
Common Update Failure Patterns (entry summary)
For the full pattern list, see update-failure-patterns.md. The four highest-frequency categories:
- Plugin drift after update — config references a plugin that the new version does not ship, or the plugin shape changed. Symptom:
openclaw doctor flags a slot as missing.
- Config drift after update — keys renamed or restructured. Symptom: validation errors at gateway start. Always diff your current
openclaw.json against the doc snapshot for the new version (use config-map.md).
- Service-manager disagreement — gateway runs under systemd on Linux but launchd on macOS. Auto-restart policy must match the active service manager. Symptom: gateway died and never came back.
- Channel auth failures — token rotated upstream, gateway still holding the old one. Symptom: channel status
auth_error. Re-auth per playbooks/auth-and-pairing.md in openclaw-troubleshooting.
Upstream Sync
This pack is itself a downstream merge of two upstream sources:
pejmanjohn/openclaw-admin-skills — the 5-skill action pack (update / troubleshoot / discover / compound / babysit) with the install scripts.rendrag-git/openclaw-admin-skill — the single-skill reference pack with config-map, update-failure-patterns, local-install, and the live-docs refresh script.
The cron job openclawadmin-upstream-sync (weekly) runs scripts/refresh-upstream.sh, fetches both upstream HEADs, diffs against the previous snapshot under local/upstream-snapshot.json, writes a sync report under local/sync-reports/, and only emits a notice if drift was found or an upstream is unreachable. Do not auto-merge upstream changes into this pack without a human review — the sync script writes a report; a human decides what to apply.
Source attribution
