Skip to content

addon_development.md

Latest commit

 

History

History
179 lines (126 loc) · 7.44 KB

addon_development.md

File metadata and controls

179 lines (126 loc) · 7.44 KB

Addon Development Guide

This guide explains how to develop addons for wiseflow.

An addon is an independent Git repository installed to the addons/ directory. It can extend wiseflow in up to two ways, applied in this order by scripts/apply-addons.sh:

  1. skills/ — global skills visible to all agents
  2. crew/ — Crew templates installed to crews/ and managed by HRBP

Note: Addons do not support patches or dependency overrides. If you need to patch openclaw/ source code, place the patch file in the project-level patches/ directory instead (wiseflow core maintainers only). This keeps the addon interface simple and stable across upstream openclaw upgrades.

Addon Directory Layout

<addon-name>/
├── addon.json              # Required: addon metadata
├── skills/
│   └── <skill-name>/
│       ├── SKILL.md        # Skill definition (required)
│       └── scripts/        # Supporting scripts (optional)
└── crew/
    └── <template-id>/
        ├── SOUL.md         # Required — role definition (must declare command-tier)
        ├── AGENTS.md       # Workflows and procedures
        ├── MEMORY.md       # Initial memory / background context
        ├── USER.md         # Assumptions about the user
        ├── IDENTITY.md     # Name and persona
        ├── TOOLS.md        # Tool guidance
        ├── HEARTBEAT.md    # Health-check template
        ├── BOOTSTRAP.md    # Onboarding intro (shown on first boot only)
        ├── DENIED_SKILLS   # Optional: built-in skills to block
        └── skills/
            └── <skill-name>/   # Template-scoped skills (only this crew sees them)
                └── SKILL.md

addon.json Format

{
  "name": "my-addon",
  "version": "1.0.0",
  "description": "What this addon does",
  "openclaw_version": "2026.4.11",        // optional: declare openclaw compatibility
  "openclaw_commit": "<commit-sha>",      // optional: pin to exact commit
  "internal_crews": ["my-ops-bot"],       // crew templates that are internal (managed by Main Agent)
  "external_crews": ["my-customer-bot"],  // crew templates that are external (managed by HRBP)
  "auto-activate": false                  // set true to auto-instantiate crew templates on apply
}

Crew Type Declaration

The internal_crews and external_crews arrays in addon.json are the sole authority for crew-type assignment:

  • Templates listed in internal_crews → internal (inherits all global skills, Main Agent manages lifecycle)
  • Templates listed in external_crews → external (uses DECLARED_SKILLS only, HRBP manages lifecycle)
  • Templates in neither array → defaults to external with a warning
  • A template listed in both arrays → error, apply-addons.sh will abort

The crew-type: field in SOUL.md is not required for addon templates. If present, it will be overwritten by apply-addons.sh to match the addon.json declaration.

Layer 1 — Global Skills (skills/)

Skills placed here are installed to openclaw/skills/ and made available to all agents. Each skill requires a SKILL.md file at the skill root.

Global skills are listed in ~/.openclaw/GLOBAL_SHARED_SKILLS after apply-addons.sh runs.

Layer 2 — Crew Templates (crew/)

Required: Declare a Command Tier

Every crew template must declare a command tier in its SOUL.md. setup-crew.sh reads this declaration and automatically generates:

  1. agents.list[].tools.exec in openclaw.json (per-agent security/ask policy)
  2. ~/.openclaw/exec-approvals.json entries (per-agent command allowlists with resolved binary paths)

Add this section to SOUL.md (before or after ## Communication Style):

## 权限级别
command-tier: T1

The four tiers (see crews/shared/COMMAND_TIERS.md for the full command lists):

Tier Name Exec Policy Typical Crew Type
T0 read-only security: deny — no shell execution Customer service, content creation, research
T1 basic-shell security: allowlist — read-only commands: cat, ls, grep, ps, curl (GET only), … Coordination, operations
T2 dev-tools security: allowlist — T1 + git, npm, pnpm, node, python, cp, mv, mkdir, rm, … Development, automation
T3 admin security: full — unrestricted shell access Infrastructure, sysops

Choose the minimum tier that the role genuinely needs. When in doubt, go lower — HRBP or the user can grant additional permissions after deployment.

Fine-Grained Adjustments with ALLOWED_COMMANDS

To add or remove commands relative to the base tier, create an ALLOWED_COMMANDS file in the template directory:

# Prefix + to allow, - to deny
+./scripts/setup-crew.sh
-rm

These adjustments are applied on top of the tier's base allowlist and reflected in exec-approvals.json automatically.

Skills Behavior by Crew Type

Internal crews (internal_crews):

  • Inherit all global skills — every skill installed in openclaw/skills/ (both built-in and addon-provided) is visible by default
  • Use DENIED_SKILLS to exclude specific skills that the crew should not access
  • BUILTIN_SKILLS file is still supported for backward compatibility but rarely needed since the default is already "all"

External crews (external_crews):

  • Use declaration mode — only skills explicitly listed in DECLARED_SKILLS are visible
  • DECLARED_SKILLS can reference both global skills (from openclaw/skills/) and template-scoped skills (from crew/<template>/skills/)
  • Template-scoped skills are automatically appended (no need to list them in DECLARED_SKILLS)
  • self-improving skill is always blocked for external crews

Instantiation Behavior

By default, installed templates are not auto-instantiated — they become available in the HRBP/Main Agent template library and the user can instantiate them on demand.

To auto-instantiate on apply-addons.sh, set "auto-activate": true in addon.json. This creates workspace-<template-id> and registers the agent immediately. Use with caution: the instance ID will equal the template ID, and existing workspaces will be skipped (not overwritten).

DENIED_SKILLS (internal crews only)

If your internal crew template should not have access to certain skills, list them one per line in DENIED_SKILLS:

github
gh-issues
coding-agent

DECLARED_SKILLS (external crews only)

External crew templates must declare which skills they need in DECLARED_SKILLS:

customer-db
smart-search
rss-reader

Testing Your Addon Locally

  1. Clone your addon into addons/<addon-name>/
  2. Run ./scripts/apply-addons.sh — it is fully idempotent
  3. Restart the gateway: ./scripts/dev.sh gateway
  4. For crew templates: ask HRBP to instantiate the new template

To force re-apply (e.g., after updating a crew template that already exists in crews/):

./scripts/apply-addons.sh --force

Upgrade Compatibility

When the upstream openclaw version changes:

  • skills/ — rarely affected unless openclaw's skill API changes
  • crew/ templates — update if SOUL.md references upstream-specific behaviors that changed

Check openclaw.version for the pinned upstream commit. When submitting your addon to the community, document which wiseflow version range it supports.