openclaw-setup
Bootstrap OpenClaw in a project — install the orchestrator if missing, run project setup script (or `openclaw onboard`), configure gateway (bind mode, auth, UI), start Mission Control if compose exist
SKILL.md.claude/skills/openclaw-setup/SKILL.md
GitHubopenclaw-setup
The bootstrap skill that creates an OpenClaw deployment for a project from scratch. Distinct from openclaw-add-agent (adds to existing deployment) and openclaw-health (audits existing deployment) — this skill creates the deployment itself: gateway, Mission Control, supporting Docker services, initial config.
Trigger phrases (when to load this skill)
Load when the conversation matches any of:
- No deployment exists: project has no
openclaw statusoutput (command not found OR returns "no gateway"), no Mission Control on:8000, noagent-tooling.yaml. - Direct verb: operator says "set up OpenClaw", "install the orchestrator", "bootstrap the fleet", "wire up Mission Control", "first OpenClaw run".
- New sister project: a fleet-class project (e.g., new
openfleet-*instance) needs its own OpenClaw.
Do NOT load when:
- OpenClaw exists; you're adding agents — load
openclaw-add-agent. - OpenClaw exists; auditing health — load
openclaw-health. - Mission Control specifically needs reconnection (gateway up but MC connection lost) — load
openclaw-configure-mc. - Operator wants to scale an existing deployment to multi-host — load
evolve-scale.
Operations
This skill has 4 named operations. Execute in order. Each step verifies before proceeding.
Operation 1: Pre-flight + install OpenClaw
Trigger: skill loaded; operator confirmed greenfield setup.
Process:
- Pre-flight check:
Capture: which prerequisites are present.command -v openclaw && openclaw --version || echo "NOT INSTALLED" docker --version || echo "DOCKER MISSING" command -v claude && claude --version || echo "CLAUDE CLI MISSING" - If OpenClaw not installed: install per the operator's tool of choice (npm / brew / source build per project README). Verify with
openclaw --versionagain. - If Docker missing: STOP — operator must install Docker first (system-level, not in scope here).
- If Claude CLI missing: STOP — OpenClaw orchestrates Claude Code instances; without CLI it can't run agents.
- Pick the project path (
$ARGUMENTSor cwd). Verify it's a git repo and has a clear identity (CLAUDE.md or README). If neither, ask operator if this really is the right path.
Quality bar (Operation 1 done when):
- All 3 prerequisites verified or explicitly stopped-on.
- OpenClaw installed and
--versionreturns successfully. - Project path confirmed.
- No backed-up config overwritten silently — if existing OpenClaw config exists, back up first (rename to
.bak.<timestamp>).
Operation 2: Run project setup or onboard
Trigger: Operation 1 complete.
Process:
- Look for project-specific setup:
ls <project>/setup.sh <project>/scripts/openclaw-setup.sh 2>/dev/null - If a setup script exists: read it FIRST (don't run blind). Verify it's not destructive (no
rm -rfoutside its scope, nochmodon system paths). If it looks safe, run it; capture output. - If no setup script: run the OpenClaw default onboarding:
This createscd <project> openclaw onboard --workspace . --no-interactive.openclaw/config dir, registers the project as a workspace, and produces a defaultagent-tooling.yamlskeleton. - After either path: verify
.openclaw/exists with the expected files (config.yaml,agents/,gateway.logafter first start). - Check the resulting
agent-tooling.yaml(or equivalent) — it should have at minimum:agents:block,skills:referenced,mode_defaults:. Empty or trivial configs need operator guidance to populate.
Quality bar (Operation 2 done when):
- Setup or onboard ran to completion (exit 0).
-
.openclaw/directory exists with expected structure. -
agent-tooling.yaml(or equivalent) is non-trivial — at least lists agent slots. - Any setup-script output read; warnings/errors flagged to operator.
Operation 3: Configure gateway + Mission Control
Trigger: Operation 2 complete.
Process:
- Configure gateway via
openclaw config(or edit.openclaw/config.yaml):- bind mode:
local(default — only localhost can talk to gateway) orbind(network-exposed for multi-host fleets). Picklocalunless operator confirms multi-host. - auth: enable token-auth for the control UI. Generate a token; store in
.env(gitignored). Don't commit the token. - control UI port: default :7000 unless operator wants different.
- bind mode:
- If a Mission Control
docker-compose.yamlexists in the project (typical foropenfleet/):
Wait up to 60s for MC to come up; verify withdocker compose -f openfleet/mission-control/docker-compose.yaml up -dcurl -sS -m 5 http://localhost:8000/health. - Wire MC ↔ Gateway: typically MC reads gateway URL from env (
OPENCLAW_GATEWAY_URL). Set in MC's compose file or.env. - Some auth flows need interactive operator input (Claude Code login token, OAuth flow). DETECT this; pause and tell operator: "Run
claude loginto authenticate before continuing."
Quality bar (Operation 3 done when):
- Gateway config has bind mode + auth + UI port set.
- Auth token in
.env, gitignored, NOT committed. - Mission Control running (if compose existed) and responding to
/health. - Any interactive auth surfaced to operator with clear instructions.
Operation 4: Verify all components
Trigger: Operation 3 complete.
Process:
- Verify gateway:
openclaw status # should report "running, version X.Y.Z" - Verify Mission Control (if applicable):
curl -sS -m 5 http://localhost:8000/health # 200 OK curl -sS -m 5 -o /dev/null -w "%{http_code}" http://localhost:3000 # 200 (frontend) - Verify Docker services:
docker compose ps # all "running (healthy)" - Verify the workspace is registered:
openclaw agents list # should be empty for now (no agents added yet) but command works - Suggest the next skill:
openclaw-add-agentto register the first agent.
Quality bar (Operation 4 done when):
- Gateway returns "running" with version.
- MC backend + frontend respond (or explicitly "MC not deployed, gateway-only" stated).
- Docker services all healthy (or "no docker services" if compose-less setup).
- Workspace registered.
- Operator told to load
openclaw-add-agentnext.
Gotchas (known failure modes — read before doing)
Gotcha 1: Overwriting existing OpenClaw config
Operator runs setup again on a project that already has .openclaw/. The skill silently overwrites config.yaml, losing operator's custom auth tokens, agent registrations, queue state.
The rule: Operation 1 always checks for existing .openclaw/ BEFORE running setup. If it exists, back up to .openclaw.bak.<timestamp>/ first. Then proceed (or ask operator if they want to abort and audit existing instead — openclaw-health).
Gotcha 2: Running setup.sh blind
Project's setup.sh is read by the skill and run without inspection. The script does rm -rf $HOME/.config/openclaw/, wiping operator's other-project credentials. Setup "succeeds" but operator's other deployments break.
The rule: read every setup script before running. Look for rm -rf / chmod / sudo / writes outside the project tree. If any of those, present the suspicious line(s) to the operator and ask before running. Trust no setup script that hasn't been reviewed.
Gotcha 3: Auth token committed by accident
Operation 3 generates an auth token; skill writes it to .openclaw/config.yaml instead of .env. config.yaml is committed to git. Token is now in history.
The rule: secrets ONLY in .env (gitignored). Config files reference env-var names, not values. Verify with git diff after Operation 3 — no token literals.
Gotcha 4: Gateway up but MC unreachable, declared healthy
openclaw status returns "running"; the skill marks setup successful. But MC compose hasn't started, MC backend isn't reachable, the operator can't see the board. Setup is technically complete; the system is not actually usable.
The rule: Operation 4 verifies BOTH gateway AND MC (if compose exists). One being healthy isn't enough; both must respond. If MC is "deferred" by design (gateway-only setup), state that explicitly.
Gotcha 5: Skipping interactive auth detection
OpenClaw needs claude login (or equivalent) to dispatch agents. Skill runs setup, declares success. First time operator tries to add an agent, the agent fails to start because auth isn't done. Operator scratches head — "but setup said success!"
The rule: detect interactive-auth requirements during Operation 3 step 4. Surface them to the operator with EXACT command to run. Setup is "complete" only when interactive auth is also done — or explicitly noted as a follow-up step the operator must complete.
Reference exemplars
The Extension Standards reference exemplars for skills are the second brain's model-builder and wiki-agent skills — see ~/devops-solutions-research-wiki/skills/. This skill follows their structure: trigger phrases, multiple named operations, per-operation Process + Quality bar, Gotchas with detection + rule + reasoning.
Domain context
This skill primarily targets the OpenFleet sister project (where OpenClaw runs). AICP itself doesn't run OpenClaw — it provides the inference + skills the orchestrated agents consume. Per docs/architecture/fleet-integration.md, the AICP↔OpenFleet split keeps the inference path off the orchestrator.
Related skills
| Skill | When | Why distinct |
|---|---|---|
| openclaw-add-agent | Add agents to existing deployment | This skill creates the deployment first |
| openclaw-health | Audit an existing deployment | This skill creates; openclaw-health audits |
| openclaw-fleet-status | Operational snapshot | This skill is bootstrap; fleet-status is post-bootstrap operations |
| openclaw-configure-mc | Reconnect MC to existing gateway | Sub-task; this skill includes MC bootstrap as part of full setup |
| evolve-scale | Add a second host | Multi-host evolution; this skill is single-host bootstrap |