How the OpenClaw Library Integrates with the Caveman System

The Caveman toolset runs continuously inside an OpenClaw workspace by installing a skill definition into the workspace directory and injecting a bootstrap block into OpenClaw's SOUL.md file, managed entirely through the openclaw.js helper library.

The JuliusBrussee/caveman repository provides a seamless bridge between the Caveman system and OpenClaw orchestration platforms. By treating Caveman as a native OpenClaw skill, the integration enables persistent "smart caveman" behavior without inflating prompt sizes. This article examines the technical implementation in bin/lib/openclaw.js and explains how the library manages workspace detection, skill preparation, and idempotent installation flows.

Workspace Resolution and Environment Detection

The integration begins with workspace resolution. According to the source code in bin/lib/openclaw.js, the helper determines the OpenClaw workspace directory through two mechanisms:

• Environment variable: Checks for OPENCLAW_WORKSPACE
• Default fallback: Uses ~/.openclaw/workspace when the environment variable is unset

This resolution logic appears at lines 35-38 of the library file.

Skill Definition Preparation

Once the workspace is located, the library prepares the Caveman skill by reading skills/caveman/SKILL.md from the repository root. The helper processes this file using three lightweight YAML utilities defined in the same module:

• splitFrontmatter: Parses existing frontmatter from the skill definition
• frontmatterHasKey: Validates required keys are present
• mergeOpenclawFrontmatter: Injects required fields including name, version, and the always flag

This merge operation (lines 44-78) ensures OpenClaw recognizes Caveman as an ever-present skill that loads automatically on every turn.

Bootstrap Snippet Injection

The core integration mechanism relies on a bootstrap snippet that activates Caveman behavior on each OpenClaw turn. The library loads this text from src/rules/caveman-openclaw-bootstrap.md via the loadBootstrapSnippet function (lines 82-90).

The snippet is wrapped in HTML comment markers to ensure safe insertion and removal:

• MARK_BEGIN: <!-- caveman-begin -->
• MARK_END: <!-- caveman-end -->

These markers (defined at lines 31-34) allow the library to identify and manage the Caveman block within SOUL.md without affecting other configuration content.

Installation and Uninstallation Flows

Installing Caveman into OpenClaw

The installOpenclaw function orchestrates the complete setup through three distinct operations:

1. Creates the caveman skill directory inside the resolved OpenClaw workspace
2. Writes the merged SKILL.md file with proper OpenClaw frontmatter
3. Calls appendBootstrapToSoul to inject the bootstrap block into SOUL.md

The appending logic handles edge cases including pre-existing markers or corrupted blocks (lines 55-80), ensuring the operation remains idempotent across multiple runs.

Removing the Integration

The uninstallOpenclaw function reverses the process cleanly:

• Removes the caveman skill folder from the workspace entirely
• Invokes stripBootstrapFromSoul to surgically remove the marked block from SOUL.md (lines 42-73)

This two-step cleanup ensures no orphaned references remain in the OpenClaw configuration after removal.

Practical Implementation Examples

Developers can programmatically control the integration using the exports from bin/lib/openclaw.js:

Basic installation:

const { installOpenclaw } = require('./bin/lib/openclaw');
installOpenclaw({ repoRoot: __dirname, log: console });

Dry-run mode (preview changes without filesystem modifications):

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

Custom workspace path:

installOpenclaw({
  workspace: '/custom/path/to/.openclaw/workspace',
  repoRoot: __dirname,
  log: console
});

Complete removal:

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

Summary

• The OpenClaw library integration centers on bin/lib/openclaw.js, which manages Caveman as a persistent skill within OpenClaw workspaces.
• Workspace resolution supports both the OPENCLAW_WORKSPACE environment variable and the default ~/.openclaw/workspace path.
• Skill preparation merges Caveman's SKILL.md with required OpenClaw frontmatter using specialized YAML helpers like mergeOpenclawFrontmatter.
• Bootstrap injection adds content from src/rules/caveman-openclaw-bootstrap.md to SOUL.md, wrapped in <!-- caveman-begin --> and <!-- caveman-end --> markers.
• Idempotent operations allow repeated installation and clean uninstallation via installOpenclaw and uninstallOpenclaw without corrupting the OpenClaw configuration.

Frequently Asked Questions

What file does the OpenClaw library modify to activate Caveman?

The library modifies OpenClaw's SOUL.md file by appending a bootstrap block wrapped in <!-- caveman-begin --> and <!-- caveman-end --> markers. This injection is handled by the appendBootstrapToSoul function in bin/lib/openclaw.js, which safely manages pre-existing or corrupted markers to prevent duplicate entries.

How does the library determine where to install the Caveman skill?

The helper checks for the OPENCLAW_WORKSPACE environment variable first, falling back to ~/.openclaw/workspace if undefined. This resolution occurs in bin/lib/openclaw.js (lines 35-38) and ensures the Caveman skill directory is created in the correct OpenClaw workspace location regardless of system configuration.

Can I preview changes before installing Caveman into OpenClaw?

Yes. Pass { dryRun: true } to the installOpenclaw function. This mode logs all intended filesystem operations—including skill directory creation and SOUL.md modifications—without writing actual changes, allowing safe verification of the integration steps.

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

The uninstallOpenclaw function calls stripBootstrapFromSoul to locate and remove the marked bootstrap block between MARK_BEGIN and MARK_END comment markers. This operation cleans the SOUL.md file while preserving all other content, ensuring OpenClaw continues functioning normally without Caveman-specific instructions.

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