web42
Login

OpenClaw

Package requirements, installation flow, and management for OpenClaw agents on Web42.

Overview

OpenClaw is the first platform supported by Web42. This page covers what an OpenClaw agent package must include, how the CLI installs it into your local OpenClaw environment, and how to manage installed agents. For general publishing concepts see the Publishing guide.

Package structure

When you run web42 init and select OpenClaw, the following files are scaffolded. Every OpenClaw package published to the marketplace must include these files.

your-agent/
├── manifest.json        # Required — package metadata
├── AGENTS.md            # Required — operating manual
├── IDENTITY.md          # Required — agent persona
├── SOUL.md              # Required — personality & values
├── TOOLS.md             # Required — local tool notes
├── USER.md              # Auto-generated on install
├── HEARTBEAT.md         # Optional — periodic task checklist
├── BOOTSTRAP.md         # Optional — first-run setup
└── skills/              # Optional — capability modules
    └── your-skill/
        └── SKILL.md

Required files

manifest.json

Package metadata for the marketplace. Must include "platform": "openclaw". Defines name, version, skills, config variables, and more. See the manifest.json reference for all fields.

AGENTS.md

The operating manual the agent reads every session. Defines startup behavior (read SOUL.md → USER.md → memory files), memory rules, safety boundaries, group chat etiquette, heartbeat behavior, and any custom conventions. This is the most important file — it tells the agent how to behave.

IDENTITY.md

Defines the agent's persona: name, creature type, vibe, signature emoji, and avatar path. Filled in by the agent during its first conversation with the user.

SOUL.md

Core personality and behavioral guidelines — the agent's value system. Defines how the agent communicates, handles boundaries, and persists across sessions.

TOOLS.md

Local infrastructure notes for the agent's environment. Camera names, SSH hosts, TTS voices, device nicknames — anything specific to the user's setup. Kept separate from skills so skills can be shared without leaking local details.

Optional files

HEARTBEAT.md

Periodic task checklist. When present, the agent checks this file on heartbeat polls and runs any listed tasks (email checks, calendar reviews, etc.). Leave empty or omit to skip heartbeats entirely.

BOOTSTRAP.md

First-run setup instructions. Guides the user through API key setup and messaging channel connections. The agent deletes this file after completing initial configuration.

skills/

Directory of capability modules. Each skill lives in its own folder with a SKILL.md file. Skills are auto-detected during web42 init and web42 pack.

Auto-generated on install

USER.md

Information about the human the agent helps (name, pronouns, timezone). This file is always regenerated fresh during install so each user gets a blank slate. Not included in the published package.

Excluded from packages

The following files and directories are automatically excluded when running web42 pack. They never get uploaded to the marketplace:

MEMORY.md              # Private long-term memory
memory/                # Private daily session logs
sessions/              # Private session data
USER.md                # Regenerated per-user on install
manifest.json          # Uploaded separately
openclaw.json          # Local OpenClaw config
auth-profiles.json     # Local auth credentials
.web42/                # Build artifact
.git/, node_modules/   # Standard exclusions

You can add additional exclusions in a .web42ignore file at the root of your agent directory, one pattern per line.

How pack works

When you run web42 pack (or web42 push which auto-packs), the OpenClaw adapter performs these steps:

  1. Collects all files from the current directory, excluding the hardcoded list above plus any patterns in .web42ignore
  2. Sanitizes file contents — replaces absolute paths to ~/.openclaw with {{OPENCLAW_HOME}} template variables so they resolve correctly on any machine
  3. Extracts the agent's configuration from your local openclaw.json — agent entry, channel bindings, skill configs, and tool settings are bundled into a config template
  4. Strips secrets from skill configs and channel configs, replacing them with {{PLACEHOLDER}} variables that become config variables in the manifest
  5. Outputs everything to the .web42/ directory, including a .openclaw/config.json with the config template

Use web42 pack --dry-run to preview the bundled output without writing files.

Skills and config variables

Skills live in skills/<name>/SKILL.md. They're auto-detected during init and pack — the name comes from the first markdown heading, the description from the body text.

Config variables let each user provide their own API keys, tokens, and preferences. They come from two sources:

  • Explicitly declared in manifest.json under configVariables
  • Auto-extracted during pack when secrets are stripped from skill and channel configs

During install, the CLI prompts the user for each required variable. Values are stored locally in .web42.config.json inside the workspace and never uploaded to the marketplace.

Example in a manifest:

"configVariables": [
  {
    "key": "OPENAI_API_KEY",
    "label": "OpenAI API Key",
    "description": "Used for embeddings and completions",
    "required": true
  },
  {
    "key": "DISCORD_TOKEN",
    "label": "Discord Bot Token",
    "required": true
  }
]

Installation flow

What happens when a user runs:

web42 openclaw install @username/agent-name
  1. Access check — The CLI verifies the user has access to the agent (owner, free acquisition, or paid purchase). For paid agents the user must purchase on the web first.
  2. Fetch files — Downloads all agent files and the config template from the marketplace API.
  3. Config prompts — If the agent has config variables, the CLI prompts for each one interactively. Use --no-prompt to use defaults instead.
  4. Model API key — If the manifest specifies a modelPreferences.primary model and the provider API key isn't configured, the CLI prompts for it and saves it to ~/.openclaw/.env.
  5. Create workspace — Writes all agent files to ~/.openclaw/workspace-<agent-name>/. Template variables like {{OPENCLAW_HOME}} are resolved to actual paths. A fresh USER.md is generated.
  6. Merge config — The config template is merged into ~/.openclaw/openclaw.json: the agent entry is added to agents.list, channel bindings are appended, skill and tool configs are merged (existing entries are not overwritten), and config variable placeholders are replaced with the user's answers.
  7. Save install metadata — A .web42.config.json file is written to the workspace with the source reference and all config answers.

Install options

  • --as <name> — Install under a different local agent name
  • --no-prompt — Skip interactive config prompts, use defaults

Managing installed agents

List installed agents

web42 openclaw list

Shows all agents in your OpenClaw environment. Reads from openclaw.json first, falls back to scanning workspace-* directories.

Update agents

web42 openclaw update

Updates all installed agents to their latest marketplace versions.

Uninstall an agent

web42 openclaw uninstall @username/agent-name

Removes the agent's workspace directory and agent directory, then cleans up the agent entry and bindings from openclaw.json.

File system layout

After installing an agent, the local OpenClaw directory looks like this:

~/.openclaw/
├── openclaw.json                    # Global config (agents, bindings, skills, channels)
├── .env                             # Provider API keys
├── workspace-my-agent/              # Agent workspace
│   ├── AGENTS.md
│   ├── IDENTITY.md
│   ├── SOUL.md
│   ├── TOOLS.md
│   ├── USER.md
│   ├── HEARTBEAT.md
│   ├── BOOTSTRAP.md
│   ├── .web42.config.json           # Install metadata + config answers
│   ├── skills/
│   │   └── ...
│   └── memory/                      # Created at runtime
│       └── YYYY-MM-DD.md
└── agents/
    └── my-agent/
        └── agent/                   # Agent directory referenced by openclaw.json

Next steps