Module Scaffold (OpenClaw-Module Canonical)

Scope

• In-scope: scaffold module follows OpenClaw-Module's canonical template, keeping service lifecycle/install-upgrade reusable logic.
• Out-of-scope: deeply refactor runtime/service outside scope scaffold or domain other than Magisk/KSU packaging.

Indexed Reference Map

• @[SKILL.md#L1-L161] Standard Frontmatter (name, description).
• @[SKILL.md#L6-L161] Module Scaffold (OpenClaw-Module Canonical).
• @[SKILL.md#L8-L161] Target.
• @[SKILL.md#L16-L161] Canonical source of truth.
• @[SKILL.md#L33-L161] When to use.
• @[SKILL.md#L38-L161] Required rule.
• @[SKILL.md#L46-L161] Token map (required when rendering).
• @[SKILL.md#L55-L161] Standard SOP scaffold.
• @[SKILL.md#L112-L161] Guardrails.
• @[SKILL.md#L118-L161] Standard output when completed.

Supporting files

• @[templates/init_module.sh#L1-L42] Template used to quickly scaffold/patch.
• @[templates/module-tree.txt#L1-L18] Template used to quickly scaffold/patch.

Target

Use OpenClaw-Module as a standard logic template to create new modules, instead of a minimalist scaffold. The created module must retain production characteristics:

• install/upgrade flow is clear,
• safe backup/restore,
• standard service lifecycle,
• wrapper command is stable,
• consistent permission/security.

Canonical source of truth

When scaffolding, prioritize getting logic from:

• /data/adb/openclaw/home/.openclaw/workspace/Claw-G/module-src/

Standard files must mirror this structure:

• module.prop
• customize.sh
• service.sh
• action.sh
• uninstall.sh
• <runtime>/settings.ini
• <runtime>/scripts/<runtime>.service
• <runtime>/scripts/start.sh
• system/bin/<cmd>
• system/bin/<cmd>.service
• META-INF/com/google/android/{update-binary,updater-script}

When to use

• Create a new module for another runtime/service but want to keep the standard OpenClaw behavior.
• Refactor old modules lacking install/upgrade safety.
• Standardize modules to reduce drift between Android Root projects.

Mandatory principles

1. Template-first: clone logic from previous OpenClaw-Module, only changing token/namespace.
2. Namespace isolation: all runtime paths must be separate (/data/adb/<module>), do not overwrite other modules.
3. Upgrade-safe: must detect fresh vs upgrade + backup/restore.
4. Service-contract stable: the service script must have start|stop|status|restart|log.
5. Secure defaults: config/secrets permissions must be tight, do not allow excessive permissions.
6. Deterministic output: same input must yield the same structure.

Token map (required when rendering)

• __MODULE_ID__ (e.g. my-runtime)
• __MODULE_NAME__
• __RUNTIME_DIR__ (e.g. /data/adb/my-runtime)
• __RUNTIME_NAME__ (e.g. myruntime)
• __CMD_NAME__ (binary wrapper in system/bin)
• __SERVICE_NAME__ (e.g. myruntime_service.sh)
• __PORT__ (if the module has gateway/web)

Standard SOP scaffold

Step 1 — Define spec

Front latch:

• module id/name/version/versionCode
• runtime dir
• command name
• service entry + healthcheck command
• artifact bundle (*.tar.xz) and unpacked structure

Step 2 — Copy canonical tree

• Build the file tree according to Claw-G/module-src.
• Replace token map in scripts.
• Do not omit important lifecycle hooks (customize/service/action/uninstall).

Step 3 — Port install/upgrade logic from customize.sh

The new module must keep the branches:

• precheck bootmode/KSU version,
• detect fresh vs upgrade,
• stop the old service before updating,
• back up data/config/scripts when upgrading,
• extract runtime artifact,
• set env/runtime wrapper,
• set permissions,
• install boot service,
• clear post-installation report.

Step 4 — Port service lifecycle

Script <runtime>.service must have at least:

• start: start daemon + write PID
• stop: cleanly stop + clear stale PID
• status: check PID + health endpoint (if available)
• restart: stop + start
• log/tail: read runtime log

Step 5 — Wrapper contract

system/bin/<cmd> and system/bin/<cmd>.service must:

• Point to the correct absolute runtime path,
• set PATH to match the runtime,
• with glibc-runner: call the local loader + process-level --library-path, do not export global LD_LIBRARY_PATH,
• with a bundle packed directly from Termux: follow the termux-packager recipe + patch RPATH/RUNPATH before bundling,
• not depend on fragile symlinks,
• be runnable from shell after reboot.

Step 6 — Verify before packaging

Required Checklist:

• full standard file tree
• script executable permissions are correct
• install path does not overwrite other modules
• service start/stop/status pass
• upgrade simulation (preserve config/data) passes
• uninstall does not accidentally delete data that must be kept

Step 7 — Package flashable zip

Output:

• Complete module directory
• flashable zip
• verification report + main runtime paths

Guardrails

• Do not use minimalist scaffolds for production modules.
• Do not hardcode the OpenClaw path if the new module has a different namespace.
• Do not omit the backup step in the upgrade path.
• Do not remove permission hardening for config/secrets.

Standard output when completed

⚡ [scaffold] module <id> → created from OpenClaw canonical
- runtime: <runtime_dir>
- command: <cmd>
- service: <service_script>
- artifact: <tar.xz>
- verify: install/fresh=pass, upgrade=pass, service=pass
🛡️ [WARN] <points not yet 100% parity with OpenClaw-Module>

Trigger Rules

• Positive: Triggers when user request matches module-scaffold according to description: Creates Magisk/KSU module according to OpenClaw-Module standard (canonical template), retains service lifecycle and install/upgrade logic for reuse in all future modules.
• Negative: Not enabled for requests outside scope or without the workflow/expertise of this skill.
• Escalation: If there is an external action/network write or sensitive operation, an approval checkpoint must be added before executing.

Output Contract

• Deliverable: target tracking result of module-scaffold; specify the artifact/path/steps performed (if any).
• Validation: reports PASS/FAIL status and the main checks that were run.
• Failure mode: when there is an error, the root cause + proposed fix must be stated.

Error Handling

• If input/permissions are missing: report what is missing and clearly request additional information.
• If runtime/tool error: brief error return + possible cause + suggested fix.
• If there is a risk policy/safety concern: stop and escalate according to the approval checkpoint.