# OpenClaw

**Chat with your [OpenClaw](https://openclaw.ai) AI agent directly from Obsidian.**

Your vault becomes the workspace. Your AI lives in the sidebar. No browser tabs, no separate apps — just your notes and your AI, side by side.

## Features

- **Chat sidebar** — Talk to your AI agent from any Obsidian tab
- **Streaming responses** — See replies appear in real-time
- **Markdown rendering** — Code blocks, lists, links rendered natively
- **Tool call visibility** — See files read/written, commands run, pages fetched
- **Cross-device sync** — Chat history and tool calls persist via Obsidian Sync
- **"Ask about this note"** — Send any note as context with one command
- **Dark/light theme** — Follows your Obsidian theme automatically

## Prerequisites

Before you install the plugin, you'll need:

- [OpenClaw](https://openclaw.ai) gateway running somewhere (Mac, Linux, Raspberry Pi)
- [Tailscale](https://tailscale.com/download) on all your devices
- Gateway bound to Tailscale: `openclaw config set gateway.bind tailnet && openclaw gateway restart`
- **A small patch to OpenClaw** so it accepts Obsidian's `app://obsidian.md` origin — see below.

### One-time OpenClaw patch (required)

Obsidian's renderer loads from `app://obsidian.md`. Per the URL spec, custom schemes have a "null" origin, so vanilla OpenClaw rejects the websocket handshake from Obsidian. This plugin needs a one-line fallback added to OpenClaw's origin check.

Run this on your **gateway machine**:

```bash
curl -fsSL https://raw.githubusercontent.com/oscarhenrycollins/obsidianclaw/main/scripts/patch-openclaw.sh | sudo bash
```

The script is idempotent, backs up the file it edits, and restarts the gateway. Review it first: [`scripts/patch-openclaw.sh`](scripts/patch-openclaw.sh).

> ⚠️ **Re-run this after every `openclaw update`** — gateway upgrades wipe the patch. We're tracking an upstream fix so this requirement can be removed.

## Install

### Official Community Plugin (recommended)

1. In Obsidian, open **Settings → Community plugins → Browse**
2. Search for **OpenClaw**
3. Click **Install**, then **Enable**

Plugin page: https://community.obsidian.md/plugins/openclaw

### BRAT (optional)

If you want pre-release builds:

1. Install **BRAT**
2. **BRAT → Add Beta Plugin**
3. Use repo: `oscarhenrycollins/obsidianclaw`

## Connect

The setup wizard opens automatically after install:

1. **Gateway URL:**
   - Preferred: `https://<your-tailnet-hostname>` (plugin converts to `wss://.../ws`)
   - Alternate: `ws://<your-tailscale-ip>:18789`
2. **Auth Token:** from `~/.openclaw/openclaw.json` → `gateway.auth.token`
3. Click **Test connection**
4. **Approve the device** from the OpenClaw dashboard or CLI:
   ```bash
   openclaw devices list
   openclaw devices approve <requestId>
   ```

Done. The device is remembered permanently.

> If connection fails, first confirm gateway health and Serve routes:
> `openclaw status` and `tailscale serve status`

## Commands

| Command | Description |
|---------|-------------|
| `OpenClaw: Toggle chat sidebar` | Open/close the chat panel |
| `OpenClaw: Ask about current note` | Send the active note as context |
| `OpenClaw: Reconnect to gateway` | Re-establish the connection |
| `OpenClaw: Run setup wizard` | Re-run the onboarding flow |

## Troubleshooting

**"Could not connect" / "Disconnected"** — Most common cause: the gateway stopped. SSH into your gateway machine and run `openclaw gateway restart`. If that fixes it, the gateway had crashed. Also check: Is Tailscale running on both devices? Is the URL correct (`ws://<tailscale-ip>:18789`)? Is the token right?

**Connection rejected right after an OpenClaw update** — `openclaw update` wipes the origin-check patch. Re-run the [one-time OpenClaw patch](#one-time-openclaw-patch-required) on your gateway machine.

**"Pairing required"** — Every new device needs a one-time approval. Run `openclaw devices list` and `openclaw devices approve <requestId>` on your gateway machine, or approve from the dashboard.

**Switching devices** — Force-quit Obsidian and reopen. It picks up synced data from the other device.

## Security

Three layers: **Tailscale** encrypts all traffic (WireGuard VPN), **gateway token** authenticates connections, and **Ed25519 device keys** fingerprint each device. Your keys never leave your machine.

## Building from Source

```bash
git clone https://github.com/oscarhenrycollins/obsidianclaw.git
cd obsidianclaw
npm install
npm run build
```

Copy `main.js`, `manifest.json`, and `styles.css` to `.obsidian/plugins/openclaw/`.

## Links

- [ObsidianClaw](https://obsidianclaw.ai) — Official site
- [OpenClaw](https://openclaw.ai) — The AI agent framework
- [Bot Setup Guide](https://botsetupguide.com) — Full setup walkthrough
- [Humanity Labs](https://humanitylabs.org) — Built by Humanity Labs

## License

MIT