How to Integrate Caveman with OpenClaw for Self-Hosted Agent Deployment

Caveman provides a dedicated helper in bin/lib/openclaw.js that provisions the Caveman skill into an OpenClaw workspace and injects a persistent bootstrap block into SOUL.md, enabling an always-on agent without manual configuration.

The JuliusBrussee/caveman repository ships with built-in support for OpenClaw workspaces, allowing you to deploy Caveman as a self-hosted agent. This integration copies the skill definition into your OpenClaw environment and automatically configures the bootstrap sequence required for persistent operation.

How the Integration Works

The integration logic resides in bin/lib/openclaw.js and performs two distinct operations to make Caveman available to your OpenClaw instance.

Skill Provisioning

The installOpenclaw function first loads the original skill definition from skills/caveman/SKILL.md using loadSkillBody. It then merges the OpenClaw-specific frontmatter—specifically setting version and always: true—via mergeOpenclawFrontmatter.

The merged file is written to ~/.openclaw/workspace/skills/caveman/SKILL.md using fs.writeFileSync. This ensures OpenClaw recognizes Caveman as an always-on skill available to every conversation.

Bootstrap Injection

OpenClaw injects a SOUL.md file on every turn. The helper appends a fenced bootstrap block between <!-- caveman-begin --> and <!-- caveman-end --> markers that instructs the agent to load the Caveman skill.

The loadBootstrapSnippet function generates this content either from src/rules/caveman-openclaw-bootstrap.md (when the repository is available) or from a built-in fallback list of lines. The appendBootstrapToSoul method then safely adds this block to SOUL.md, repairing any stray markers and ensuring idempotence so repeated runs do not duplicate content.

Installation Methods

You can deploy Caveman to OpenClaw using either direct programmatic calls or the CLI wrapper.

Programmatic Installation

Require the helper directly and invoke installOpenclaw with your repository root and logging preferences:

const { installOpenclaw } = require('./bin/lib/openclaw');

installOpenclaw({
  repoRoot: __dirname,
  log: console
});

This writes the skill file to the OpenClaw workspace and injects the bootstrap block into SOUL.md. The installer automatically resolves the workspace location from the OPENCLAW_WORKSPACE environment variable, defaulting to ~/.openclaw/workspace if unset.

CLI Shortcut

The main Caveman CLI provides a convenience flag that loads the helper with sane defaults:

caveman … --only openclaw

This executes the same installOpenclaw routine without requiring you to write custom Node.js scripts.

Dry-Run Mode

For CI checks or validation, pass dryRun: true to preview actions without touching the filesystem:

installOpenclaw({
  repoRoot: __dirname,
  dryRun: true,
  log: console
});

If the workspace does not exist, the installer can create it when using --force, or it will abort with a helpful error message guiding you to create the directory structure.

Uninstalling Caveman from OpenClaw

The uninstallOpenclaw function reverses the installation cleanly:

const { uninstallOpenclaw } = require('./bin/lib/openclaw');

uninstallOpenclaw({
  log: console
});

This removes the ~/.openclaw/workspace/skills/caveman/ directory entirely and strips the bootstrap block from SOUL.md while preserving any user-added content outside the caveman-begin and caveman-end markers.

Key Files and Architecture

Understanding the file structure helps when troubleshooting or customizing the integration:

• bin/lib/openclaw.js – Core integration logic containing installOpenclaw, uninstallOpenclaw, mergeOpenclawFrontmatter, and appendBootstrapToSoul
• skills/caveman/SKILL.md – The canonical skill definition that gets copied into the OpenClaw workspace
• src/rules/caveman-openclaw-bootstrap.md – Optional template for the bootstrap snippet when the full repository is available
• commands/caveman.md – User-facing documentation for the caveman CLI, including the --only openclaw shortcut

Both the installation and uninstallation routines are idempotent. Re-running the installer detects existing skill files and bootstrap blocks, skipping duplicate writes. This safety mechanism ensures you can safely include the installation command in setup scripts or Docker entrypoints without risking configuration drift.

Summary

• Two-step integration: The helper provisions the skill file to ~/.openclaw/workspace/skills/caveman/ and injects a bootstrap block into SOUL.md via appendBootstrapToSoul.
• Idempotent operations: Running installOpenclaw multiple times does not duplicate content; stray markers are automatically repaired.
• Flexible invocation: Use programmatic JavaScript, the CLI shortcut (--only openclaw), or dry-run mode for CI validation.
• Clean removal: uninstallOpenclaw removes the skill directory and bootstrap markers while preserving user edits to SOUL.md.
• Environment aware: Respects OPENCLAW_WORKSPACE for custom workspace locations.

Frequently Asked Questions

What OpenClaw environment variables does Caveman support?

Caveman checks for the OPENCLAW_WORKSPACE environment variable to determine where to write the skill file and SOUL.md. If this variable is unset, it defaults to ~/.openclaw/workspace. This allows you to host multiple OpenClaw instances on the same machine or deploy to non-standard paths.

Is the Caveman OpenClaw integration idempotent?

Yes. The appendBootstrapToSoul function in bin/lib/openclaw.js detects existing <!-- caveman-begin --> markers and repairs any stray delimiters before writing. Similarly, the skill provisioning step checks for existing files before overwriting. You can safely run the installer in setup scripts or cron jobs without creating duplicate entries.

What happens to my SOUL.md file when uninstalling Caveman?

The uninstallOpenclaw function targets only the content between <!-- caveman-begin --> and <!-- caveman-end --> markers. It strips these markers and the enclosed bootstrap instructions while preserving all other user-added content in SOUL.md. This surgical removal ensures your custom OpenClaw configuration remains intact.

Can I use a custom bootstrap template for OpenClaw integration?

Yes. The loadBootstrapSnippet function first attempts to load src/rules/caveman-openclaw-bootstrap.md from your repository. If this file exists, it uses that content for the bootstrap block. If the file is missing, it falls back to a built-in list of lines. Create this file in your repository root to customize the initialization instructions sent to the OpenClaw agent.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}