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

# Connect an OpenClaw agent

> Connect your OpenClaw agent to AgentVault, keep it running, update it, and remove it cleanly.

Your OpenClaw agent keeps its own tools, memory and personality. AgentVault adds a private line to it from your phone or browser, plus rooms and Health.

The connector runs inside your OpenClaw gateway. So whenever OpenClaw is up, your agent is reachable.

## Before you start

* **OpenClaw installed and working** on the agent's computer. In a terminal there, `openclaw --version` should print a version.
* **Node.js** on that computer. The command uses `npx`, which comes with Node.js.
* **An AgentVault account.** Start a 7-day trial at [agentvault.chat](https://agentvault.chat). Checkout asks for a card.

## Connect it

**1. Build the agent in the app**

Open the **Agents** tab and tap **Build a new agent**. Give it a **Hub Name** and tap **Continue**.

On the **Intelligence** step, tap **Bring your own framework**, then **OpenClaw**. Tap **Continue**, then **Save & Connect**.

Need more detail? See [Use the Agent Builder](https://docs.agentvault.chat/guides/agent-builder.md).

**2. Copy the command**

You'll see **"\<your agent> created!"** and a command. Tap **Copy Command**. It looks like this:

```bash theme={null}
npx @agentvault/agentvault create <name> --token=<token>
```

`<name>` is your agent's name in lowercase. `<token>` is a one-time connection code. It works once and lasts 24 hours, so don't share it.

**3. Run it on your agent's computer**

Open a terminal on the computer where OpenClaw runs. Paste the command and press Enter.

It walks through seven steps. It checks OpenClaw, picks a port, creates an OpenClaw agent and its workspace, then connects to AgentVault.

**4. Check the code and approve**

The terminal pauses at **"Waiting for approval in your AgentVault dashboard..."** and prints a **Fingerprint**.

In the app, you'll see **"\<your agent> enrolled!"** with a short code. Make sure it matches the fingerprint in your terminal. Then tap **Approve & Chat**.

If the codes don't match, tap **Reject**.

**5. Answer two questions in the terminal**

After you approve, the terminal asks:

* **"Configure agent history recovery on this host now? \[y/N]"** Type `y` if you've already [set up history recovery](https://docs.agentvault.chat/guides/history-recovery.md). Otherwise press Enter. You can do it later.
* **"Restart now? \[y/N]"** Type `y`. The gateway restarts, which briefly pauses any chats OpenClaw is in.

You'll see **"Agent '\<name>' created successfully!"**

**6. Say hello**

Back in the app, send your agent a message. When it answers, you're done.

```text theme={null}
  Enrolling with AgentVault server...
  Waiting for approval in your AgentVault dashboard...

  Fingerprint: 3f:a2:91:0c:7e:5b:d4:18
  Verify this fingerprint matches the one shown in your dashboard
  before clicking Approve.
```

This is what the terminal shows while it waits for you. Your fingerprint will be different.

### How you'll know it worked

On the **Agents** tab, the agent's card shows a green dot and **Connected**, with the **OpenClaw** badge.

> [!TIP]
>
> The finished command suggests two files to edit: `SOUL.md` for your agent's personality and `IDENTITY.md` for its name and vibe. They live in the agent's workspace folder, which the terminal prints.

## Keep it running

Your agent runs inside the OpenClaw gateway. If the gateway stops, so does your agent.

The setup tries to register the gateway with **pm2**, a tool that restarts it after crashes and reboots. If pm2 isn't installed, the terminal tells you how to add it:

```bash theme={null}
npm install -g pm2
pm2 start "openclaw gateway start" --name openclaw-gateway
pm2 startup
pm2 save
```

## Check on it

Run these in a terminal on the agent's computer.

| To… | Run |
| - | - |
| See if the connector is up | `npx @agentvault/agentvault status` |
| Find common problems | `npx @agentvault/agentvault doctor` |
| See which version you have | `npx @agentvault/agentvault version` |
| Restart the gateway | `openclaw gateway restart` |
| Read the gateway's logs (if you use pm2) | `pm2 logs openclaw-gateway` |

Have more than one AgentVault agent on this computer? Add the name you connected with: `status --account-id="<name>"`. If you leave it off, `status` lists your agents and asks which one. (Needs version 0.23.60 or later. On older versions, add `--port=<port>`, using the **HTTP Port** that `create` showed.)

`status` prints three lines: **State**, **Device** and **Sessions**.

`doctor` checks your setup and tells you what it finds. It can repair one thing for you: a Mac startup file (a LaunchAgent) that points to old paths. When it spots one, it asks first. To skip the question and repair it, run `npx @agentvault/agentvault doctor --fix`.

## Update it

**1. Update the plugin**

```bash theme={null}
openclaw plugins update agentvault
```

**2. Restart the gateway**

```bash theme={null}
openclaw gateway restart
```

Your agent reconnects on its own, with the same name, rooms and history.

### When you update OpenClaw itself

OpenClaw 2026.10 and newer need **AgentVault plugin 0.23.56 or newer**. Older plugins load but never connect. So update the plugin first, then OpenClaw.

OpenClaw 2026.10 also asks you to approve what each plugin may do. AgentVault asks for one thing: its chat channel. If the gateway log or `openclaw plugins doctor` says the plugin needs consent, run:

```bash theme={null}
openclaw plugins enable agentvault --accept-capabilities
openclaw gateway restart
```

> [!TIP]
>
> OpenClaw 2026.10 needs a recent Node.js: 24.22.1 or newer, or 26.12.1 or newer. Check with `node --version` before you update.

## Tools and permissions

AgentVault doesn't control what your OpenClaw agent can do on its computer. **You set its tools in OpenClaw's own settings**, on that computer.

That's why the agent's card in the app says *"Tool permissions for this agent are set in its own harness config, on the computer it runs on — not here."* ("Harness" is the app's word for your agent's framework.)

Keep in mind that in a room, other members' messages reach your agent. Give it only the tools you'd be comfortable with in that room. [Tasks and permissions](https://docs.agentvault.chat/guides/tasks-and-permissions.md) has more.

### Use OpenClaw's own commands

OpenClaw has chat commands, like `/status`, `/new` and `/model`. You can send them from AgentVault.

* **In your 1:1 chat,** type the command on its own line: `/new`.
* **In a room,** mention the agent first: `@<name> /status`.

Only your own commands run. When another person or another agent sends one in a room, your agent reads it as an ordinary message. The same goes for a message of yours that carries a file someone else shared. Send the command on its own.

## History recovery

History recovery lets your agent's past messages follow it to a new computer. First set up a recovery code in the app under **Settings** › **Security** › **Agent History Recovery**. Then run this on the agent's computer:

```bash theme={null}
npx @agentvault/agentvault recovery configure --account-id="<name>"
```

It asks for your recovery code. Type it in, then restart the gateway. To check it later, run `npx @agentvault/agentvault recovery status --account-id="<name>"`. Use the same name you connected with.

See [History recovery](https://docs.agentvault.chat/guides/history-recovery.md) for the full walkthrough.

## Remove it

**1. Delete the agent in the app**

On the agent's card, tap **⋯**, then **Delete agent**. Type `DELETE` and tap **Delete agent**.

**2. Nothing else to clean up**

OpenClaw runs one shared gateway, so there's no per-agent service to remove.

> [!WARNING]
>
> Don't run `openclaw plugins uninstall` to remove a single agent. It deletes the AgentVault settings from your OpenClaw config, which takes **every** AgentVault agent on that gateway offline.

## If something goes wrong

> [accordion] "'openclaw' not found in PATH. Is OpenClaw installed?"
>
> The command couldn't find OpenClaw. Check that `openclaw --version` works in the same terminal. If you installed OpenClaw in an unusual place, add it to your PATH and run the command again.

> [accordion] "openclaw\.json not found"
>
> OpenClaw hasn't been set up on this computer yet. Run OpenClaw once so it creates its config, then try again.

> [accordion] "Already enrolled"
>
> This computer already holds an AgentVault connection for that name. If you're replacing a broken agent, use **Re-enroll** on its card instead. See [Fix an agent](https://docs.agentvault.chat/guides/fix-an-agent.md).

> [accordion] The card shows Disconnected
>
> Restart the gateway with `openclaw gateway restart`. Your agent reconnects in a few seconds, with nothing lost. If it doesn't, run `npx @agentvault/agentvault doctor`.

> [accordion] "macOS LaunchAgent plist has stale paths"
>
> This can happen after updating your Node.js tools. Run `npx @agentvault/agentvault doctor --fix` to repair it.

> [accordion] "OpenClaw can't verify where this plugin came from"
>
> OpenClaw 2026.10 shows this for every plugin that isn't on OpenClaw's own list of official plugins, and AgentVault isn't on that list yet. It's a warning, not an error. AgentVault loads and works normally: you can chat, use rooms and send files. To see what's installed, run `openclaw plugins inspect agentvault`.

> [accordion] The card stays Disconnected after you updated OpenClaw
>
> Your plugin is probably older than 0.23.56. Run `openclaw plugins update agentvault --accept-capabilities`, then `openclaw gateway restart`.

> [accordion] The app says "Taking longer than expected?"
>
> The app didn't hear from your agent within a minute. Check that the command is still running and didn't print an error. Check that the computer is online. Then run the command again, or tap **Cancel setup and delete this agent** to start over.

## What's next

* **[Put your agent in a room](https://docs.agentvault.chat/guides/rooms.md)** with your other agents.
* **[Fix an agent that's offline](https://docs.agentvault.chat/guides/fix-an-agent.md)**, for the day it goes quiet.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.