> ## Documentation Index
> Fetch the complete documentation index at: https://docs.screenpipe.com/llms.txt
> Use this file to discover all available pages before exploring further.
# OpenClaw - AI assistant with screenpipe memory
> Connect screenpipe to OpenClaw, a self-hosted personal AI that ties into WhatsApp, Telegram, Discord, and iMessage, so it can recall your screen history.
[OpenClaw](https://openclaw.ai) is a self-hosted personal AI assistant that connects to your messaging apps (WhatsApp, Telegram, Discord, iMessage, etc.) and can take actions on your behalf.
With screenpipe, OpenClaw can recall what you've seen on screen, reference past conversations, and answer questions about your digital history.
## quick setup
One command makes OpenClaw screenpipe-aware: it installs the screenpipe skills into OpenClaw's skills directory and registers the screenpipe MCP server in its config.
```bash theme={null}
npx -y screenpipe@latest agent setup openclaw
```
Restart OpenClaw and it can search your screen history, audio transcriptions, and memories. The command is idempotent (safe to re-run) and preserves any MCP servers you already had.
The same command wires up other agents too: `npx -y screenpipe@latest agent setup `.
Want to wire it up by hand, or run OpenClaw on another machine? See the manual and remote setups below.
## same machine (manual)
If OpenClaw and screenpipe run on the same machine, setup is straightforward.
### MCP
Add screenpipe to your OpenClaw MCP config:
```json theme={null}
{
"mcpServers": {
"screenpipe": {
"command": "npx",
"args": ["-y", "screenpipe-mcp"]
}
}
}
```
Restart OpenClaw — it will now have access to your screen history, audio transcriptions, and more.
You can test the MCP server independently:
```bash theme={null}
npx @modelcontextprotocol/inspector npx screenpipe-mcp
```
### custom skill (alternative)
Create `~/openclaw/skills/screenpipe/skill.md`:
````markdown theme={null}
---
name: screenpipe
description: Search screen recordings and audio transcriptions from the user's computer
tools:
- Bash
---
# screenpipe skill
Query the user's screen history via the local API at http://localhost:3030.
## search content
```bash
curl -s "http://localhost:3030/search?q=QUERY&limit=20"
```
## get recent activity
```bash
curl -s "http://localhost:3030/search?limit=10&content_type=all"
```
````
Restart OpenClaw to load the skill.
## different machines
If OpenClaw runs on a different machine (e.g., a VPS or home server) than screenpipe, the simplest path is to sync your data over and run the one-command setup. You can also query screenpipe's API over the network — see the options below.
### recommended: selective sync + one-command setup
**1. sync your data to the server (lightly).** screenpipe's remote sync pushes `~/.screenpipe` over SSH — no cloud account needed. Skip the heavy media and exclude anything sensitive, so you ship just text, transcripts, and memories:
```bash theme={null}
npx -y screenpipe@latest sync remote now \
--host openclaw.example.com --user ubuntu \
--key-path ~/.ssh/id_ed25519 --remote-path /home/ubuntu/.screenpipe \
--no-media \
--exclude "secrets/*" \
--disable-clipboard-capture
```
* `--no-media` skips screenshots and video — text, transcripts, and memories still sync.
* `--exclude ` is repeatable, and a `/.screenpipeignore` file (one glob per line) is honored too.
Put it on a timer for continuous sync (see the cron example below).
**2. point OpenClaw at the synced data.** On the server, one command writes the skill + MCP config targeting the local synced copy:
```bash theme={null}
npx -y screenpipe@latest agent setup openclaw --api-url http://localhost:3030
```
Headless `npx -y screenpipe@latest login` writes the cloud token where the engine reads it, so cloud features work on the server without the desktop app.
### option 1: query screenpipe's REST API directly
If both machines are on the same network, OpenClaw can query screenpipe's API directly. Use a custom skill:
Create `~/openclaw/skills/screenpipe/skill.md`:
````markdown theme={null}
---
name: screenpipe
description: Search screen recordings and audio transcriptions from the user's computer
tools:
- Bash
---
# screenpipe skill
Query the user's screen history via their screenpipe REST API at http://SCREENPIPE_IP:3030.
## search content
```bash
curl -s "http://SCREENPIPE_IP:3030/search?q=QUERY&limit=20"
```
## filter by type
```bash
# screen content (accessibility-first text plus OCR fallback)
curl -s "http://SCREENPIPE_IP:3030/search?q=QUERY&content_type=all"
# audio transcriptions
curl -s "http://SCREENPIPE_IP:3030/search?q=QUERY&content_type=audio"
```
## activity summary
```bash
curl -s "http://SCREENPIPE_IP:3030/activity-summary?start_time=2024-01-15T10:00:00Z&end_time=2024-01-15T18:00:00Z"
```
## list meetings
```bash
curl -s "http://SCREENPIPE_IP:3030/meetings?limit=20"
```
````
Replace `SCREENPIPE_IP` with the IP of the machine running screenpipe. If the machines aren't on the same network, use [Tailscale](https://tailscale.com) to create a private network between them.
### option 2: push data to the OpenClaw machine over SSH
Use screenpipe's built-in **remote sync** to push your `~/.screenpipe/` directory to the OpenClaw machine over SFTP. No screenpipe-cloud account needed — just SSH access to your server.
> **⚠️ clipboard sensitivity:** Remote sync includes clipboard events and content by default. If you're syncing to a less-trusted machine (VPS, shared server), disable clipboard capture first with `--disable-clipboard-capture` to avoid syncing passwords, API keys, or other sensitive data that flows through your clipboard.
On the laptop (or any machine recording):
```bash theme={null}
# one-shot push (excludes clipboard)
npx -y screenpipe@latest sync remote now \
--host openclaw.example.com \
--user ubuntu \
--key-path ~/.ssh/id_ed25519 \
--remote-path /home/ubuntu/.screenpipe \
--disable-clipboard-capture
# verify SSH first if you want
npx -y screenpipe@latest sync remote test --host ... --user ... --key-path ... --remote-path ...
# auto-discover candidate hosts from ~/.ssh/config
npx -y screenpipe@latest sync remote discover
```
Run that on a cron / launchd / systemd timer for continuous sync:
```bash theme={null}
# crontab -e — every 15 minutes (without clipboard)
*/15 * * * * npx -y screenpipe@latest sync remote now \
--host openclaw.example.com --user ubuntu \
--key-path /home/me/.ssh/id_ed25519 --remote-path /home/ubuntu/.screenpipe \
--disable-clipboard-capture
```
Or set env vars instead of flags: `SCREENPIPE_REMOTE_HOST`, `SCREENPIPE_REMOTE_USER`, `SCREENPIPE_REMOTE_KEY`, `SCREENPIPE_REMOTE_PATH`.
On the OpenClaw machine, point its skill at the synced directory or run a local screenpipe pointing to the same data dir — OpenClaw can then query `localhost:3030` as if the data were captured locally.
> The old **Settings → Cloud** sync flow is being phased out in favor of explicit remote sync setups. Use `npx -y screenpipe@latest sync remote` for new setups where you control the destination.
## available MCP tools
When connected via MCP (same machine setup), OpenClaw gets access to these tools:
| Tool | Description |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **search-content** | Search screen text (accessibility-first with OCR fallback), audio transcriptions, user input. Supports time range, app, window, and speaker filters. |
| **activity-summary** | Lightweight overview of app usage, audio speakers, and recent texts for a time range (\~200 tokens). |
| **search-elements** | Search structured UI elements (buttons, links, text fields) from the accessibility tree. |
| **frame-context** | Get full accessibility tree, URLs, and text for a specific frame. |
| **list-meetings** | List detected meetings with duration, app, and attendees. |
| **export-video** | Export screen recordings as MP4 for a time range. |
The MCP server also provides **resources** (`screenpipe://context` for current time, `screenpipe://guide` for search strategy) and **prompts** (search-recent, find-in-app, meeting-notes).
## example prompts
Once configured, message OpenClaw from any chat app:
* "what was I reading about yesterday afternoon?"
* "find the slack message from john about the deployment"
* "what code was I looking at in cursor this morning?"
* "summarize my meetings from last week"
* "what tabs did I have open when researching that bug?"
* "when did I last see the budget spreadsheet?"
* "what did I copy to clipboard recently?"
* "show me what buttons I clicked in Figma today"
## build a second brain (automation)
the prompts above answer questions on demand. to have OpenClaw *proactively* segment your workflows, summarize your processes, and keep a living memory of you — like the [digital clone pipe](/pipe-store), but inside OpenClaw — paste the prompt from [build a second brain](/second-brain) into OpenClaw and let it run on a schedule.
prefer to run it inside the screenpipe app instead of OpenClaw? do the same thing as a [pipe](/pipes) — `npx -y screenpipe@latest pipe install && npx -y screenpipe@latest pipe enable ` (`bunx` works too).
## troubleshooting
**MCP not connecting?**
* Test the server: `npx @modelcontextprotocol/inspector npx screenpipe-mcp`
* Check screenpipe is running: `curl http://localhost:3030/health`
**remote machine can't reach screenpipe?**
* Check Tailscale is connected: `tailscale status`
* Check SSH tunnel is up: `curl http://localhost:3030/health` on the remote
* Make sure screenpipe is running on your computer
**no results from queries?**
* Verify screenpipe is running: `curl http://localhost:3030/health`
* Ensure screenpipe has screen recording permissions