> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev.byterover.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw Integration Reference

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

## Configuration Reference

### Context Engine

Added to `openclaw.json`:

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

<Accordion title="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.
</Accordion>

### Automatic Memory Flush

Added to `openclaw.json`:

```json theme={null}
{
  "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:

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="Config file not found">
    **Cause:** OpenClaw has not been initialized.

    **Solution:** Install and run OpenClaw first:
    [https://docs.openclaw.ai/install](https://docs.openclaw.ai/install)
  </Accordion>

  <Accordion title="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 theme={null}
    # List available backups
    ls ~/.openclaw/openclaw.json.bak.*

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

  <Accordion title="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 theme={null}
    curl -fsSL https://byterover.dev/install.sh | sh
    ```

    See the [installation docs](https://docs.byterover.dev) for offline or package-manager options.
  </Accordion>

  <Accordion title="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 theme={null}
    npx clawhub@latest install byterover --force
    ```
  </Accordion>

  <Accordion title="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 theme={null}
       openclaw plugins list
       ```
    2. Run the plugin diagnostics tool:
       ```bash theme={null}
       openclaw plugins doctor
       ```
    3. Check that `brv` is in your PATH:
       ```bash theme={null}
       which brv
       ```
    4. Verify the plugin is enabled in config:
       ```bash theme={null}
       cat ~/.openclaw/openclaw.json | grep -A2 byterover
       ```
  </Accordion>
</AccordionGroup>

## 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

<AccordionGroup>
  <Accordion title="How it works: workspace structure">
    OpenClaw agents use [multiple workspaces](https://docs.openclaw.ai/concepts/multi-agent) — one per agent:

    ```bash theme={null}
    ~/.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 theme={null}
    ~/.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.
    </Tip>
  </Accordion>

  <Accordion title="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 theme={null}
    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.
    </Tip>
  </Accordion>

  <Accordion title="Legacy plugin (deprecated)">
    <Warning>
      This plugin is deprecated. Use the Context Engine plugin for new installations.
    </Warning>

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

    ```bash theme={null}
    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`
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Onboard Context" icon="lightbulb" href="/common-workflows/onboard-context">
    Learn how to onboard context into ByteRover
  </Card>
</CardGroup>