OpenClaw Integration Reference

Configuration details, troubleshooting, and advanced topics for the OpenClaw integration

Configuration Reference

Context Engine

Added to openclaw.json:

{
  "plugins": {
    "entries": {
      "byterover": {
        "enabled": true,
        "config": {
          "brvPath": "/custom/path/to/brv"
        }
      }
    },
    "allow": ["byterover"],
    "slots": {
      "contextEngine": "byterover"
    }
  }
}

How the context engine works

The plugin participates in two lifecycle methods:

• Assemble (before each model run) — Extracts the user's query, runs brv query to retrieve curated knowledge from the context tree, and injects it as a systemPromptAddition.
• After Turn (after each run completes) — Serializes the conversation turn and runs brv curate asynchronously to extract and store valuable knowledge back into the context tree.

The plugin delegates compaction to the OpenClaw runtime (ownsCompaction: false), so built-in auto-compaction continues to work as normal.

Automatic Memory Flush

Added to openclaw.json:

{
  "agents": {
    "defaults": {
      "compaction": {
        "reserveTokensFloor": 50000,
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 4000,
          "systemPrompt": "Session nearing compaction. Store durable memories now.",
          "prompt": "Review the session for any architectural decisions, bug fixes, or new patterns. If found, run 'brv curate \"<summary of change>\"' to update the context tree. Also write personal notes to memory/YYYY-MM-DD.md. Reply NO_REPLY if nothing to store."
        }
      }
    }
  }
}

Uninstalling

Re-run the script and decline each feature when prompted:

curl -fsSL https://byterover.dev/openclaw-setup.sh | sh

The script cleanly removes:

• Context Engine — Uninstalls the plugin and removes config entries
• Memory Flush — Removes compaction config

Troubleshooting

Config file not found

Cause: OpenClaw has not been initialized.

**Solution:** Install and run OpenClaw first:
https://docs.openclaw.ai/install

Config file is not valid JSON

Cause: Your ~/.openclaw/openclaw.json is corrupted.

**Solution:** Restore from a backup. The script automatically reverts to the backup if an error occurs during patching. To restore manually:

```bash
# List available backups
ls ~/.openclaw/openclaw.json.bak.*

# Restore the most recent backup
cp ~/.openclaw/openclaw.json.bak.<timestamp> ~/.openclaw/openclaw.json
```

ByteRover CLI auto-install failed

Cause: The setup script attempted curl -fsSL https://byterover.dev/install.sh | sh but it failed (no network, sandboxed shell, etc.).

**Solution:** Install the ByteRover CLI manually and re-run the setup script:

```bash
curl -fsSL https://byterover.dev/install.sh | sh
```

See the installation docs for offline or package-manager options.

Clawhub skill install failed

Cause: The setup script attempted npx clawhub@latest install byterover --force but it failed (no npx on PATH, no network).

**Solution:** Install `npx`/Node.js, then re-run the setup script. To install the skill manually:

```bash
npx clawhub@latest install byterover --force
```

Plugin not loading

Cause: The plugin is not installed, brv is not in PATH, or the plugin is not enabled.

**Solution:**

1. Check that the plugin is installed and active:
   ```bash
   openclaw plugins list
   ```
2. Run the plugin diagnostics tool:
   ```bash
   openclaw plugins doctor
   ```
3. Check that `brv` is in your PATH:
   ```bash
   which brv
   ```
4. Verify the plugin is enabled in config:
   ```bash
   cat ~/.openclaw/openclaw.json | grep -A2 byterover
   ```

File Reference

Path	Description
~/.openclaw/openclaw.json	OpenClaw configuration (patched by script)
~/.openclaw/openclaw.json.bak.*	Timestamped config backups
~/.openclaw/{workspace}/.brv/	ByteRover context tree storage
~/.openclaw/skills/byterover/	ByteRover skill (installed via Clawhub)

Advanced

How it works: workspace structure

OpenClaw agents use multiple workspaces — one per agent:

```bash
~/.openclaw/workspace/         # Main agent workspace
~/.openclaw/workspace-/        # Sub-agent workspace
```

The setup script scans `openclaw.json` for configured workspaces and updates their protocol files (`AGENTS.md`, `TOOLS.md`) with ByteRover usage instructions. The `.brv/` context tree directory is created automatically on first use:

```bash
~/.openclaw/workspace/.brv/
~/.openclaw/workspace/.brv/context-tree/
```

All ByteRover operations execute against the `.brv` directory in the current workspace.

TIP

To manually run ByteRover commands (brv pull, brv push, brv curate, brv query), first cd into the appropriate workspace directory so the CLI finds the correct .brv context tree.

Migrating existing memory data

If you already have OpenClaw memory files (daily logs in memory/), you can migrate them to ByteRover's context tree. Navigate to your workspace and run:

```bash
cd ~/.openclaw/workspace
brv curate "curate the data in the folder ~/.openclaw/workspace/memory by reviewing each file one by one."
```

ByteRover reads each file, extracts valuable insights, and organizes them into the context tree automatically:

```
update .brv/context-tree/architecture/api_design/middleware_pipeline.md
update .brv/context-tree/architecture/openclaw/memory_configuration.md
update .brv/context-tree/market_trends/github_repos/trending_repositories.md
✓ Context curated successfully.
```

TIP

You can point to any directory that contains your memory .md files.

Legacy plugin (deprecated)

WARNING

This plugin is deprecated. Use the Context Engine plugin for new installations.

The legacy plugin uses OpenClaw's hook system instead of the context engine lifecycle:

```bash
curl -fsSL https://byterover.dev/byterover-legacy-plugin.sh | sh
```

It intercepts the `before_prompt_build` event, extracts the user's query, runs `brv query` to retrieve context, and prepends it as a `## ByteRover Context (Auto-Enriched)` section.

The legacy plugin does **not** automatically curate conversation turns — it only retrieves context.

**Files changed:** `~/.openclaw/extensions/byterover/index.ts`, `openclaw.plugin.json` and `~/.openclaw/openclaw.json`

Next Steps

• Onboard Context — Learn how to onboard context into ByteRover