Skills Setup

Runs setup scripts declared by installed OpenClaw skills.

This plugin registers the admin-only skills.setup Gateway RPC. Callers can use it to run an idempotent setup script from an installed skill directory, for example to install local dependencies or prepare tool-specific configuration.

Background

This plugin is a plugin-based implementation path for openclaw/openclaw#80213, which tracks skill author-defined setup hooks for running skill-supplied scripts after install/update.

Unlike a future core install/update hook, this plugin does not run setup scripts automatically. A caller with operator.admin scope must invoke skills.setup for a specific installed skill.

Skill Metadata

Add setup metadata to the skill's SKILL.md frontmatter:

---
name: example-skill
description: Example skill with a setup script
metadata:
  openclaw:
    skillKey: example-skill
    setup:
      script: scripts/setup.sh
---

The setup.script value must be a relative path inside the skill directory.

Runtime Behavior

• Looks for skills under the active agent workspace skills/ directory.
• Supports grouped skills such as skills/team/example-skill.
• Accepts group-qualified selectors such as team/example-skill. Basename selectors are rejected when multiple grouped skills share the same basename.
• Runs setup scripts with bash.
• Sets SKILL_DIR to the resolved skill directory.
• Merges configured skill env with request env, while blocking reserved execution-context keys such as HOME, PATH, and SKILL_DIR, bash startup/control keys such as BASH_ENV, ENV, SHELLOPTS, BASHOPTS, PS4, and IFS, and injected function/loader prefixes such as BASH_FUNC_, LD_, and DYLD_.
• Enforces bounded setup timeouts.

Configuration

{
  "plugins": {
    "entries": {
      "skills-setup": {
        "config": {
          "timeoutMs": 120000
        }
      }
    }
  }
}

timeoutMs defaults to 120 seconds and is capped at 600 seconds.

Security

This plugin intentionally runs local setup scripts, so the Gateway method is restricted to operator.admin. Scripts must resolve inside the skill directory, and path escapes are rejected before execution. Review the setup script and the env values you pass before invoking setup, especially when providing secrets.