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

> Learn to integrate Caveman with OpenClaw for self-hosted agent deployment. Easily provision a Caveman skill into OpenClaw for an always on agent.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: how-to-guide
- Published: 2026-07-08

---

**Caveman provides a dedicated helper in [`bin/lib/openclaw.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/lib/openclaw.js) that provisions the Caveman skill into an OpenClaw workspace and injects a persistent bootstrap block into [`SOUL.md`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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:

```javascript
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`](https://github.com/JuliusBrussee/caveman/blob/main/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:

```bash
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:

```javascript
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:

```javascript
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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/bin/lib/openclaw.js)** – Core integration logic containing `installOpenclaw`, `uninstallOpenclaw`, `mergeOpenclawFrontmatter`, and `appendBootstrapToSoul`
- **[`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md)** – The canonical skill definition that gets copied into the OpenClaw workspace
- **[`src/rules/caveman-openclaw-bootstrap.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-openclaw-bootstrap.md)** – Optional template for the bootstrap snippet when the full repository is available
- **[`commands/caveman.md`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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.